# Don't Panic (full content) Don't Panic is the help center for ambientChat.AI — guides, tips, and answers for managing your AI context, inventory, beacons, and more. Each article below is delimited by a header banner with the canonical URL. Source of truth: https://dont-panic.ambientchat.ai Generated: 2026-08-19T05:02:48.046Z --- ## Connected Services — GitHub, Gmail, Slack & More URL: https://dont-panic.ambientchat.ai/article/connected-services-github-gmail-slack-more Updated: 2026-08-13T22:15:14.159Z # Connected Services — GitHub, Gmail, Slack & More Your ambientChat assistant already knows your stuff. Connect an outside service — GitHub, Gmail, Calendar, Slack, Linear, and more — and it can reach *their* stuff too, right inside the same conversation. ## What It Does **Connected Services** lets ambientChat reach *out* to other tools you use and pull their capabilities into chat. Connect your Gmail and you can ask the assistant to find a reservation email; connect GitHub and it can look up an issue; connect your calendar and it can check next week — all without leaving ambientChat, and all combined with your own inventory, documents, and context. Under the hood, each connection is an **MCP server** (the same open standard ambientChat itself speaks). Any service that offers an MCP endpoint can be connected **by its URL**, and the well-known ones (GitHub, Linear, Gmail, Google Calendar, Google Drive, Slack, Mercury, and others) sign you in with **OAuth** — you approve access on the service's own login screen, and ambientChat never sees your password. > **Not to be confused with Context Sharing.** Connected Services brings *outside tools into* ambientChat. The separate **Context Sharing** setting (see [Privacy & Your Data](18-privacy.md)) controls the opposite direction — how much of *your* ambientChat context is shared *out* to Claude, brand apps, and partners. Different feature, opposite arrow. ## How to Use It ### iOS App #### Connecting a Service 1. Open **Settings → Connected Services** 2. Tap **Add a service** 3. Pick a known service (GitHub, Gmail, Calendar, Drive, Slack, Linear, Mercury…) **or** paste any MCP server's **URL** 4. If the service uses OAuth, you're taken to its sign-in page — approve the access it asks for 5. The service is tested on connect, so you get a **truthful status** (connected, plus how many tools it exposes) rather than a hopeful guess #### Using a Connected Service in Chat Once connected, that service's tools become available to the assistant automatically. Just ask: - *"Any unread email from the landlord?"* (Gmail) - *"What's on my calendar Thursday afternoon?"* (Calendar) - *"Show me the open issues assigned to me in GitHub."* - *"Match my Mercury transactions to the receipts in my library."* (a fused answer — your receipts **and** the connected service together) You don't call tools by name; the assistant picks the right ones for your question. #### "Do you have my GitHub?" — asking what's connected The assistant is told, every turn, which services you've connected and roughly what each one can do. So you can just ask — *"what services can you reach?"* — and get a straight answer rather than a guess. This also means it shouldn't tell you it can't reach a service you've connected. Earlier versions could: with dozens of tools available, the assistant would sometimes fail to spot the right one and conclude the whole service was missing. It now knows the list up front, and if its first look for a tool comes up empty it tries different wording before drawing any conclusion. Two things follow from that: - **It won't stall to ask you for something it can look up.** Ask about "my app's repo" and it goes and finds it rather than asking you to name it first. - **If it says a service isn't connected, believe it.** That answer now comes from the actual list, not from a failed search. If you have connected a service and the assistant still can't see it, check its status under **Settings → Connected Services** — a connection whose sign-in has expired shows there, and reconnecting fixes it. #### Managing Connections From **Connected Services** you can: - **Edit** a connection's details - **Show / hide the token** with the eye toggle when you need to check or copy it - **Disconnect** a service — its tools leave chat immediately and its access is revoked ### Web The same **Connected Services** page exists in the web interface at `app.ambientchat.ai` — add, test, edit, show/hide token, and disconnect, in full parity with the phone. Connect on one, and it's available on both. ### Via Chat You can manage connections conversationally: - *"What services do I have connected?"* - *"Connect my GitHub."* - *"Disconnect Slack."* ### Via Claude Desktop (MCP) These tools manage your connections: - **`list_mcp_servers`** — List the services you've connected, with status and tool counts - **`add_mcp_server`** — Connect a new MCP server by URL (OAuth handled where supported) - **`update_mcp_server`** — Edit a connection's settings or token - **`remove_mcp_server`** — Disconnect a service See the [MCP Tools reference](20-mcp-tools.md) for details. ## Tips & Tricks - **Connect what you actually use.** Each connection adds tools the assistant can reach; a couple of well-chosen services (your email, your calendar) beats a dozen you never query. - **OAuth means no passwords in the app.** For supported services you approve access on the provider's own site; ambientChat stores a revocable token, never your password. - **The magic is the mix.** The point isn't just reaching Gmail — it's asking one question that combines a connected service *and* your own inventory and documents (e.g. reconciling bank transactions against your receipts). - **Disconnect cleanly.** Removing a service revokes its access and pulls its tools out of chat. If a connection ever looks stale, disconnect and reconnect to refresh it. ## Options | Setting | What It Does | Default | |---------|-------------|---------| | Connected services | The outside tools ambientChat can use in chat | None connected | | Token visibility | Show or hide a connection's stored token | Hidden | | Auth mode | OAuth (recommended, for supported services) or a manual token/URL | OAuth where available | ## Known Limitations - **The service must speak MCP.** Connected Services works with servers that offer an MCP endpoint. Well-known providers are one-tap; anything else needs its MCP server URL. - **Availability may depend on your plan.** The number of connections (and access to advanced fused tools) can vary by subscription tier — see [Subscriptions & Usage](11-subscriptions.md). - **Writes ask first.** Actions that *change* something in a connected service (not just read it) go through a confirmation step, and untrusted content coming back from a third-party service is kept away from the assistant's instructions — a deliberate safety boundary. The prompt tells you exactly what will happen (e.g. *Linear: Save issue — "Fix beacon drift"*), and if you're away from the app an iOS notification with **Approve / Deny** buttons reaches your lock screen — you have about two minutes before the request expires. Tired of approving the same tool? Tap **Always Allow** on the prompt, or manage every tool's policy (Auto / Ask / Blocked) under **Settings → MCP Servers → Tool Permissions**. Safety-critical actions (emptying trash, deleting your account) always ask. - **A connection is only as available as the service.** If the outside provider is down or you revoke access on their side, its tools won't respond until the connection is restored. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 3 | 2026-08-07 | The assistant is now told which services you have connected, so it can answer "what can you reach?" accurately, retries a failed tool lookup with different wording instead of concluding a service is missing, and looks things up rather than asking you for details it can find | | 2 | 2026-07-18 | Approval prompts now name the exact action, arrive as lock-screen Approve/Deny notifications, support "Always Allow", and are manageable per tool under Settings → MCP Servers → Tool Permissions | | 1 | 2026-07-05 | Initial guide — connect third-party MCP servers (GitHub, Gmail, Calendar, Drive, Slack, Linear, Mercury, or any by URL) with OAuth; use their tools in chat; manage/disconnect (v0.13.2) | --- ## Sharing — Items, Documents, Folders & Groups URL: https://dont-panic.ambientchat.ai/article/sharing-items-documents-folders-groups Updated: 2026-08-13T22:15:14.001Z # Sharing — Items, Documents, Folders & Groups Your context is more useful when the right people can see it. Share a receipt with your accountant, a packing list with your family, or a whole folder with a group — and keep control of it the entire time. ## What It Does Sharing lets you give another person — or a whole group — access to your items, documents, folders, and Q&A answers. You share by **email address**. If your recipient already has an ambientChat account, they get **live access**: the shared thing appears in their app under **Shared with me**, and they always see your latest version. If they don't have an account yet, they get an invitation email, and the moment they sign up the share activates automatically. You decide whether each share is **read-only** (they can look, not touch) or **read-write** (they can help you keep it current). You can see everything you've shared, and you can **revoke** any share at any time — access disappears immediately. Nothing you share ever leaves your control. Sharing the *viewing* side — how shared content shows up in your own library, the scope pill, and removing things others shared with you — is covered in the [Inventory guide](03-inventory.md). This guide is about the *act of sharing*. ## How to Use It ### iOS App #### Sharing a Single Thing 1. Open any item, document, folder, or Q&A answer 2. Tap the **share symbol** (the arrow-out-of-a-box icon) — it opens the **manage-sharing control** for that thing 3. Enter a person's **email address**, or pick a **group** you belong to 4. Choose the access level: **Can view** (read-only) or **Can edit** (read-write) 5. Add an optional note, then tap **Share** The recipient gets access right away (or an invitation if they're new). The share symbol doubles as a status light: once something is shared, it carries a **share badge** so you can tell at a glance what's out in the world. You can also reach the same control by **long-pressing** a card in a list and choosing **Share**. #### Sharing a Public Link (post it anywhere) At the top of the sharing control is **Anyone with the link** — a public, **view-only** URL you can drop into Instagram, a text, Slack, an email, anywhere. Unlike a person-invite, a link needs no recipient and **anyone who has it can view** (they don't need an account to look — a sign-up prompt appears on the page). 1. Open the sharing control and tap **Create link** 2. Tap **Copy** to put the URL on your clipboard, or **Share** to hand it straight to Messages, Mail, or a social app via your phone's share sheet 3. Paste it wherever you like — it unfurls as a rich preview card in most apps The link is **permanent** — it keeps working so an old post never dead-links. You stay in control: - **Reset link** issues a fresh URL and kills the old one (use it if you posted somewhere you regret). - **Stop sharing** switches the public link off entirely — the URL then shows "no longer shared." Sharing a **Q&A answer** as a public link asks you to **Preview the page** first — because an answer can mention your location, inventory, or names, you see exactly what a stranger will before you hand out the link. (Receipts are never shown on a public page.) #### Sharing a Whole Folder Share a folder and you share everything in it — and, because folder shares **cascade to sub-folders**, sharing *Music* also shares *Music/Vinyl* and everything beneath it. New things you add to the folder later are covered too. 1. Long-press a folder (or open it and tap the share symbol) 2. Choose **Share**, pick your recipient or group, and set the access level 3. Everyone you shared with sees the folder — and its contents — under their **Shared with me** #### Seeing and Revoking What You've Shared - The **share badge** on any card tells you it's shared. Tap into the sharing control to see **who** it's shared with. - To stop sharing, open the sharing control and tap **Revoke** next to a recipient (or **Stop sharing** to revoke everyone). Access is removed immediately — the item vanishes from their **Shared with me**. #### Groups Groups let you share with several people at once — a household, a project team, a set of neighbours — without re-typing addresses every time. 1. Open **Sharing / Groups** from the Context tab 2. Tap **New group**, name it, and **invite** people by email 3. Invitees get an invitation to **accept**; once they do, they're members 4. Share anything with the group and every member gets it. Remove a member and their access to the group's shares ends. ### Web The web interface at `app.ambientchat.ai` mirrors sharing: 1. Hover or open any item, document, or folder 2. Click the **share symbol** to open the sharing control 3. Enter an email or choose a group, set **view** or **edit** access, and confirm 4. Manage recipients — and **revoke** — from the same control. Shared content you receive shows up under the **Shared with me** scope (see the [Inventory guide](03-inventory.md)) The same control's **Anyone with the link** section gives you the public URL: **Create link**, then **Copy** it or **Share** it (your browser's share sheet where supported, otherwise it copies). **Reset link** and **Stop sharing** work exactly as on iOS. ### Via Chat You can share by simply asking: - *"Share the olive oil with my wife."* - *"Send the washing-machine manual to steve@example.com."* - *"Share my Recipes folder with the family group, read-only."* - *"Who have I shared the Warranties folder with?"* - *"Stop sharing that receipt with the repair shop."* The assistant uses the sharing tools on your behalf and tells you what it did — no confirmation taps, and an undo path if you change your mind. ### Via Claude Desktop (MCP) Through the MCP connection these tools are available: - **`share_with_email`** — Grant a person live access to an item, document, folder, or conversation by email - **`share_with_group`** — Share something with an entire group - **`share_item`** / **`share_document`** / **`share_view`** / **`share_conversation`** — Share a specific kind of thing - **`revoke_share_grant`** — Remove a share (access ends immediately) - **`list_my_shares`** — See everything you've shared and with whom - **`list_shared_with_me`** — See what others have shared with you - **`create_group`** / **`invite_to_group`** / **`accept_group_invitation`** / **`get_group_members`** / **`remove_group_member`** / **`delete_group`** — Full group lifecycle - **`resend_invitation`** — Re-send a pending invitation See the [MCP Tools reference](20-mcp-tools.md) for the complete list. ## Tips & Tricks - **Share the folder, not the files.** If you'll share a whole set of things — every receipt for a trip, every manual for the kitchen — put them in a folder and share that once. New additions are covered automatically, and sub-folders come along for the ride. - **Read-only by default is the safe choice.** Give **Can view** unless the other person genuinely needs to edit. You can always upgrade a share to **Can edit** later. - **Revoking is instant and total.** The moment you revoke, the other person loses access and the item leaves their **Shared with me**. There's no lingering copy. - **Groups save typing.** For anyone you share with repeatedly — family, a work team — make a group once and share to the group forever after. ## Options | Setting | What It Does | Default | |---------|-------------|---------| | Access level | Whether a recipient can view or also edit | Can view (read-only) | | Recipient | A single email address or a group you belong to | — | | Folder cascade | Sub-folders and their contents inherit the parent folder's shares | On (automatic) | ## Known Limitations - **Person-shares are live; public links are view-only snapshots.** Sharing *with a person* gives them live, always-current access once they have an account. A **public link** (Anyone with the link) is a read-only page anyone can open without an account — it can't be edited by viewers. Choose the person-invite for collaboration, the public link for reach. - **Revoke removes access, not memory.** If someone had **Can edit** and made changes while they had access, those edits remain — revoking stops future access, it doesn't roll back history. - **Groups are for sharing, not chat.** A group is a named set of people you share content with; it isn't a group-messaging thread. - **Invitations wait for signup.** Share with someone who has no account and the grant stays **pending** until they sign up with that email — then it activates automatically. Use **resend invitation** if they've lost the email. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 1 | 2026-07-05 | Initial guide — in-app live sharing of items, documents, folders & Q&A; groups; folder-share cascade; revoke (v0.13.2) | | 2 | 2026-07-06 | Public "Anyone with the link" sharing — permanent view-only URLs with Copy/Share, Reset & Stop; preview-before-publish for Q&A (AMB-455) | --- ## Skills — Reusable Playbooks Your AI Can Run URL: https://dont-panic.ambientchat.ai/article/skills-reusable-playbooks-your-ai-can-run Updated: 2026-08-13T22:15:13.849Z # Skills — Reusable Playbooks Your AI Can Run A **skill** is a saved playbook your AI can follow — a repeatable way to do something useful with your stuff, like filing a document, tracking what's expiring, or formatting a list for printing. You don't have to re-explain the steps each time. Just ask, and the assistant reaches for the right skill. Skills come in two flavors: a **starter set** that everyone gets, and **your own**, which you can add. Both live together in your **Skills** folder. ## What It Does Skills turn "how do I get the AI to do X the way I like?" into "just ask." Each skill is a short set of instructions the assistant follows, using your inventory, documents, tags, and location. The assistant notices when a request matches a skill and runs it — or you can ask for one by name. Because skills are just instructions (not code), they're transparent: you can read exactly what a skill does, and edit your own. ## The Starter Set Everyone gets a set of first-party skills, ready to run from day one. The everyday ones: - **Auto-Filer** — drop in a receipt, warranty, manual, or photo of paperwork and it gets classified, retitled, summarized, tagged, and filed in the right folder. - **Renewals & Warranty Watch** — scans your documents and inventory for expiry, renewal, and warranty-end dates, builds one sorted list, and sets reminders ahead of each. - **Print / Share Pack Formatter** — formats any collection or set of documents into a clean, print- or share-ready layout (checklist, table, grouped by location, with or without photos and values). And skills that lean on what makes ambientChat different — your locations, beacons, and visit history: - **Find-My / Last Seen** — locate a misplaced item from where it was last seen and what's near you now. Ask *"where did I leave my keys?"* or *"when was my passport last seen?"* - **Guided Tour / Storyteller** — at a gallery, garden, shop, or museum, it narrates what's around you from the beacons and exhibits nearby — and can recap a past visit later. - **Place Notes / Context-on-Arrival** — surfaces your own relevant items, documents, and notes for wherever you are or are heading (GPS-based, no beacons needed). *"What do I have for this place?"* - **Insurance-Ready Home Inventory** — builds an insurer-ready pack — items with values, Zones, photos, and supporting receipts/warranties — and exports it as a document. *"What's my stuff worth for insurance?"* These are **read-only** — they stay up to date automatically and you can't change them. (You can always add your own version alongside.) ## How to Use It ### The Skills button — tap to run Every chat has a **⚡ Skills** button that opens a menu of your skills — a shortcut for when you'd rather pick from a list than think of what to type. It's the answer to the blank-page moment of "what can I even ask?" - **iOS:** the ⚡ button sits in the row of controls just below the message box, next to the ☰ history menu. - **Web:** the **⚡ Skills** button is in the chat header, top-right. Tap it, then tap any skill in the list — it runs right there in the chat and you watch it work. That's also the easiest way to **try out** a skill you just created. ### Or just ask in chat You never *have* to open the menu — describing the task works just as well: - *"I just added a receipt — can you file it?"* → runs **Auto-Filer**. - *"What do I need to renew soon?"* → runs **Renewals & Warranty Watch**. - *"Format my Garage collection for printing."* → runs **Print / Share Pack Formatter**. - *"What skills can you run?"* → the assistant lists everything available to you (the starter set plus any you've added). ### Adding Your Own Skill You own your **Skills** folder, so you can add your own playbooks. The easiest way is to just describe it in chat — you don't have to write anything yourself. > **Creating your own skills is part of a paid plan (Standard and up).** On the free plan you get the full starter set and can run any of it — from the ⚡ menu or by asking. Upgrade when you want to build and save your own. **Ways to ask:** - *"Create a new skill that…"* - *"Turn what we just did into a skill."* - *"Save these steps as a skill called Trip Packer."* - *"Make a skill for formatting my wine collection as a printable list."* The assistant writes it up as a document in your **Skills** folder. Prefer to do it by hand? Write a markdown document and save it in that folder — anything in your Skills folder is treated as a skill. **A skill has three parts:** 1. A clear **name** — how you'll refer to it (*"Trip Packer"*). 2. A one-line **description of when to use it** — this is how the assistant knows to reach for it. Be specific: *"Use when I'm packing for a trip and mention a destination and number of days"* triggers far more reliably than *"packing."* 3. The **steps** you want followed, in plain English. **Example — a whole skill in one message:** > *"Create a skill called **Trip Packer**. Use it whenever I say I'm going on a trip and give a destination and how many days. Steps: 1) Check the weather for the destination. 2) Pull clothing and travel gear from my inventory that suits the trip. 3) Flag anything expiring while I'm away that I should use up first. 4) Build a checklist grouped by category and offer to save it as a document."* From then on, just say *"run my Trip Packer"* — or simply *"I'm off to Denver for 3 days"* — and the assistant follows your steps. **Reading and changing your skills:** ask *"show me my Trip Packer skill"* to see exactly what it does, or *"update my Trip Packer skill to also check my medications"* to change it. Your own skills are private to you. The starter set is shared with everyone and can't be edited — but ask for *"my own version"* and you'll get an editable copy to tweak. ### Organizing and sharing your skills The **⚡ Skills** menu is a live view of your Skills folder, so you can tidy it right there: - **Reorder** — press and hold a skill and drag it (iOS), or drag it (web), to set the order you want. Your arrangement sticks. - **Folders** — group related skills into subfolders inside your Skills folder. The ⚡ menu lets you open a folder and step back out via the breadcrumb at the top. - **Share a skill or folder** — tap the **share** icon on any of *your own* skills (or a subfolder) in the ⚡ menu to share it with a person, a group, or — if you're a superuser — everyone. A small badge shows what you've already shared and with how many people. The starter set is already shared with everyone; skills someone else shared with you aren't re-shareable from here. ### Using Your Skills in Claude or ChatGPT Your skills travel. If you connect ambientChat to Claude or ChatGPT (via the MCP integration — see **"MCP Tools"**), those assistants can list and run your skills too, working against your real inventory and documents — and they can **save and edit skills for you** with the same `create_skill` / `update_skill` tools the in-app assistant uses. Teach Claude a workflow, ask it to "save that as an ambientChat skill," and the skill shows up in your ⚡ menu everywhere. ### Exporting a skill to take elsewhere Want a skill as a file you can drop into another AI app? Ask *"export my Trip Packer skill"* and you'll get a **download link to a `.zip`** containing the skill plus a short "how to connect ambientChat" readme. Load it into Claude, ChatGPT, or a command-line AI as a custom instruction; once that app is connected to your ambientChat, the skill runs against your real data there too. Great for sharing a skill or moving it between assistants. ## Tips & Tricks - **Be specific in a skill's description.** The description is how the assistant knows when to reach for it. *"Use when I drop in a receipt or warranty"* triggers far more reliably than *"filing."* - **Let it suggest (Standard and up).** On a paid plan you usually don't need to name a skill — describe the task and the assistant picks the right one for you. On the free plan, reach for a skill yourself: tap it in the **⚡ Skills** menu or ask for it by name. - **Not sure where to start? Open the ⚡ menu.** It's the quickest way to see everything you can run. - **Read before you trust.** Ask *"show me the Auto-Filer skill"* to see exactly what it does. ## Known Limitations - **Skills are instructions, not code.** They guide the assistant through steps using your existing tools; they don't run custom scripts or generate pixel-perfect files (that's coming later). For most everyday tasks, instructions are all you need. - **The starter set is read-only.** You can't edit the first-party skills — but you can create your own version with the changes you want. - **Quality depends on your data.** A filing or renewals skill can only work with the documents and items you've added. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 1 | 2026-06-27 | Initial guide — starter set, asking in chat, adding your own, using in Claude/ChatGPT | | 2 | 2026-07-09 | Organizing & sharing — reorder, subfolders/drill-in, and sharing a skill or subfolder from the ⚡ menu | | 2 | 2026-07-06 | Expanded "Adding Your Own Skill" with example asks and a worked Trip Packer example | | 3 | 2026-07-09 | Added the ⚡ Skills launcher (tap-to-run, iOS + web), the location/beacon starter skills (Find-My, Guided Tour, Place Notes, Insurance-Ready Inventory), plan notes (creating your own = Standard+; auto-suggest = Standard+), and exporting a skill as a downloadable bundle | | 4 | 2026-07-13 | Connected assistants (Claude/ChatGPT) can now save and edit your skills directly via the new `create_skill` / `update_skill` tools | --- ## Reports & Summaries — What Your AI Can Write URL: https://dont-panic.ambientchat.ai/article/reports-summaries-what-your-ai-can-write Updated: 2026-08-13T22:15:13.690Z # Reports & Summaries — What Your AI Can Write Your AI doesn't just answer questions — it can write entire reports, pulling data from your inventory, documents, receipts, and conversation history. Need to know what your garage is worth for insurance? Want a monthly spending summary? Curious how your three blenders compare? Just ask. The report writes itself. ## What It Does ambientChat's AI can generate structured reports and summaries from any combination of your data. It searches your inventory, reads your documents, recalls your purchase history, and composes a coherent document that you can save, share, or just read once and move on. Reports are saved as markdown documents in your folders, so they're fully searchable and available for future reference. They use the same document system as your notes and lists — same folders, same search, same AI context. The key difference between asking a question and generating a report is scope. A question gets you a quick answer (*"How many electronics do I have?"* — *"47"*). A report gets you a structured, detailed analysis (*"Create an electronics inventory report with categories, values, and purchase dates"*). ## How to Use It ### iOS App **Generating a report via chat:** 1. Open the **Chat** tab 2. Describe the report you want: - *"Create a home inventory report for insurance purposes"* - *"Summarize my spending at Costco this year"* - *"Write a comparison of my coffee makers"* 3. The AI gathers the relevant data, organizes it, and presents the report 4. It saves the report as a document (or ask it to: *"Save that as a document in my Reports folder"*) **Types of reports you can request:** **Inventory reports:** - *"How much is everything in my garage worth?"* - *"Summarize my electronics collection with purchase dates and estimated values"* - *"List all my kitchen appliances with their brands and warranty status"* - *"What tools do I have? Organize by category."* - *"Create a complete home inventory by Zone"* **Spending reports:** - *"How much did I spend at Costco this month?"* - *"Summarize my grocery spending for the past 3 months"* - *"What were my biggest purchases this year?"* - *"Break down my spending by category — food, electronics, household"* **Expiry reports:** - *"Give me a weekly expiry summary for my pantry"* - *"What medications are expiring in the next 90 days?"* - *"Create a food waste risk report — what's most likely to go bad?"* **Comparison reports:** - *"Compare my 3 blenders — features, price, and which one's better"* - *"How do my two laptops compare in terms of specs and age?"* - *"Compare the nutritional profiles of my breakfast cereals"* **Insurance reports:** - *"Create a home inventory report for insurance purposes — include values, categories, and purchase dates"* - *"What's the total estimated value of my electronics?"* - *"Generate a Zone-by-Zone inventory with approximate replacement values"* **Custom summaries:** - *"Summarize everything I've scanned this week"* - *"What questions have I asked about cooking in the past month?"* - *"Give me a status report on my pantry — what's well-stocked and what's running low"* ### Via Claude Desktop (MCP) MCP tools let Claude Desktop compose reports on your data: 1. Search with **`search_items`** and **`list_expiring_items`** to gather data 2. Pull receipts with **`search_documents`** for spending analysis 3. Recall history with **`search_markdown_content`** for context 4. Save the report with **`create_markdown_document`** Example workflow: *"Search my inventory for all items over $100, then create a high-value items report sorted by category with estimated replacement costs."* ## Sample Report Here's what an insurance inventory report might look like: ```markdown --- title: Home Inventory Report — Insurance tags: [insurance, inventory, report] --- # Home Inventory Report Generated: March 1, 2026 Total estimated value: $14,850 ## Electronics ($8,200) | Item | Brand | Est. Value | Purchase Date | Source | |------|-------|-----------|---------------|--------| | MacBook Pro 14" | Apple | $2,499 | 2025-06-15 | Receipt | | iPhone 15 Pro | Apple | $1,199 | 2024-09-20 | Receipt | | Sony WH-1000XM5 | Sony | $349 | 2025-01-10 | AI estimate | | LG C3 65" OLED TV | LG | $1,799 | 2024-11-25 | Receipt | | ...12 more items | | $2,354 | | | ## Kitchen Appliances ($2,100) | Item | Brand | Est. Value | Purchase Date | Source | |------|-------|-----------|---------------|--------| | KitchenAid Stand Mixer | KitchenAid | $449 | 2024-03-08 | Receipt | | Breville Barista Express | Breville | $699 | 2025-02-14 | Receipt | | ...8 more items | | $952 | | | ## Furniture ($3,200) ... ## Notes - Values marked "AI estimate" are approximations based on product data and typical market prices. Verify with receipts where available. - 73% of item values are backed by scanned receipts. - Items without purchase dates have estimated acquisition periods. ``` ## Tips & Tricks - **Be specific about what you want included.** *"Create a report"* is vague. *"Create a report of all electronics with brand, estimated value, and purchase date, sorted by value"* gives the AI clear instructions and produces a much more useful document. - **Save important reports to a dedicated folder.** Create a "Reports" folder and ask the AI to save reports there. This makes them easy to find later and separates them from everyday notes and lists. - **Reports are point-in-time snapshots.** A spending report generated today reflects today's data. If you add more receipts tomorrow, generate a new report. The old one stays in your documents for comparison. ## Options | Setting | What It Does | Default | |---------|-------------|---------| | Report folder | Where generated reports are saved | My Documents | | Include AI-estimated values | Whether reports include values estimated by AI (not from receipts) | On | | Value source labeling | Whether reports note the source of each value (receipt, AI estimate, network lookup) | On | ## Known Limitations - **Report quality depends on data completeness.** A spending report can only include receipts you've scanned. An inventory report can only list items you've cataloged. The more data you've put in, the more comprehensive the reports come out. - **AI-generated values are estimates, not appraisals.** When the AI says your TV is worth $1,799, it's using the original purchase price or current market data — not a professional appraisal. For insurance claims, verify values with your insurer's requirements. - **Reports are static documents.** Once generated, a report doesn't auto-update when your inventory changes. Think of them as snapshots. Generate a fresh report when you need current data. - **Spending analysis requires receipt data.** If you haven't scanned your receipts, the AI can't calculate spending totals. It can still report on inventory values, but spending trends require purchase records. - **Complex cross-referencing has limits.** Asking for a report that combines inventory, spending, location, and conversation data in one analysis may produce incomplete results. For best results, focus reports on one or two data types at a time. - **No chart or graph generation.** Reports are text-based markdown with tables. The AI can't generate pie charts, bar graphs, or visual data representations. For visual analysis, export the report data and use a spreadsheet tool. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 1 | 2026-03-01 | Initial guide | --- ## Travel & Packing Lists URL: https://dont-panic.ambientchat.ai/article/travel-packing-lists Updated: 2026-08-13T22:15:13.540Z # Travel & Packing Lists Packing for a trip normally involves staring at an empty suitcase and trying to remember everything you own that might be relevant. With ambientChat, the AI already knows your wardrobe, your electronics, your toiletries — so it can do the remembering for you. All you have to do is ask. ## What It Does ambientChat combines your inventory knowledge with document creation to make travel planning practical and personalized. The AI knows what clothes you have, what electronics you own, what toiletries are in your cabinet, and what gear is in your garage. Ask it to create a packing list for any trip and it draws from your actual belongings — not a generic checklist from the internet. Packing lists are saved as documents in your folders, so you can reference them while packing, update them as you think of more items, and reuse them for future trips. The AI can also create itinerary documents, save travel information, and help you plan activities. ## How to Use It ### iOS App **Creating a packing list:** 1. Open the **Chat** tab 2. Describe your trip: - *"Create a packing list for a week in Hawaii"* - *"I'm going on a 3-day business trip to Chicago in January. What should I pack?"* - *"Pack me for a weekend camping trip — we'll be hiking and fishing"* 3. The AI searches your inventory for relevant items and creates a tailored packing list 4. The list is saved as a document — find it in your **Documents** tab **Getting specific:** The more context you give, the better the list: - *"What electronics should I bring for my business trip? I'll need to give a presentation."* - *"I'm going snorkeling in Mexico — what gear do I already have?"* - *"Create a packing list for a formal wedding in Napa Valley, plus a day of wine tasting after"* **Building an itinerary:** Beyond packing, the AI can help plan the trip itself: - *"Create a travel document for my Tokyo trip — flights are on March 15 and March 22, hotel is the Park Hyatt"* - *"Add a section for restaurants I want to try in Tokyo"* - *"What documents should I bring? Do I have my passport scanned?"* **Updating lists as you think of things:** - *"Add a portable charger to my Hawaii packing list"* - *"Actually, remove the hiking boots — we're only doing beach stuff"* - *"Add 'check weather forecast' as a reminder at the top"* **Reusing previous lists:** - *"Find my packing list from the last time I went camping"* - *"Create a packing list for Maui based on my Hawaii list from last year, but add snorkeling gear"* ### Via Claude Desktop (MCP) MCP tools make desktop trip planning seamless: 1. **`search_items`** — *"winter jackets"*, *"camera gear"*, *"hiking equipment"* 2. **`create_markdown_document`** — save packing lists and itineraries 3. **`update_markdown_document`** — add or modify sections as plans evolve 4. **`search_markdown_content`** — find previous travel documents 5. **`list_expiring_items`** — check if any travel toiletries or medications are expired before you pack them Desktop is great for longer planning sessions where you're researching flights, hotels, and activities while building your packing list and itinerary simultaneously. ## Sample Packing List Here's what the AI might generate for a week-long beach vacation, based on your actual inventory: ```markdown --- title: Hawaii Packing List - March 2026 tags: [travel, hawaii, beach] --- # Hawaii Packing List ## Clothing (from your wardrobe) - [ ] Blue Hawaiian shirt (you have this) - [ ] Khaki shorts x3 (you have 2 — consider buying 1 more) - [ ] Swim trunks - navy (you have this) - [ ] Swim trunks - floral (you have this) - [ ] Reef sandals (you have this) - [ ] Running shoes (you have your Nike Pegasus) - [ ] Light rain jacket (you have your Patagonia Torrentshell) - [ ] Sunhat (not found in inventory — buy or borrow) ## Electronics - [ ] iPhone charger - [ ] AirPods Pro (you have this) - [ ] Kindle Paperwhite (you have this) - [ ] Portable battery pack (you have the Anker 20000mAh) ## Toiletries - [ ] Sunscreen SPF 50 (you have this — check expiry: April 2026, still good) - [ ] Aloe vera gel (not in inventory) - [ ] Reef-safe sunscreen (not in inventory — required in Hawaii) ## Documents - [ ] Boarding passes - [ ] Hotel confirmation - [ ] Car rental confirmation ``` Notice how it references specific items from your inventory by name and brand, flags things you don't have, and even checks expiry dates. ## Great For - **Vacations** — beach, ski, road trips, cruises - **Business trips** — presentation gear, formal wear, chargers - **Camping & outdoor trips** — gear checklists from your actual equipment - **Day trips** — quick "what should I grab" lists - **Moving** — Zone-by-Zone inventory checklists - **Seasonal wardrobe** — "what warm clothes do I have for winter?" ## Tips & Tricks - **Scan your passport and travel documents for quick reference.** Having your passport, visa, travel insurance, and vaccination records in your Documents tab means your AI can remind you about them when planning a trip. Plus, you have a backup copy if the physical one goes missing. - **Create a Travel folder to keep everything organized.** Packing lists, itineraries, booking confirmations, and travel notes all in one place. When you ask about a trip, the AI searches this folder first. - **Review your list the night before departure, not the morning of.** Open the packing list in your Documents tab the evening before. You'll have time to wash that shirt you forgot about or buy the sunscreen you're missing. ## Options | Setting | What It Does | Default | |---------|-------------|---------| | Packing list folder | Where packing lists are saved | My Documents | | Include inventory references | Whether the AI notes which items you own vs. need to buy | On | | Check expiry dates | Whether the AI flags expired toiletries and medications | On | ## Known Limitations - **AI suggestions are based on inventory completeness.** If you haven't scanned your wardrobe, the AI can't recommend specific clothes. The more you've cataloged, the more personalized the list. You can always ask the AI to include generic categories alongside inventory matches. - **No calendar integration.** The AI doesn't know your travel dates unless you tell it. It can't pull itinerary details from your email or calendar apps. - **No booking capabilities.** The AI helps you plan and pack, but can't book flights, hotels, or rental cars. It creates the document; you do the booking. - **Weather-aware suggestions are general.** The AI knows that January in Chicago means warm clothes, but it doesn't check the actual forecast. For weather-specific packing, tell it the expected conditions. - **Checkbox state is not interactive.** The `[ ]` checkboxes in markdown are visual aids — you can't tap them to check them off in the app. Use them as a visual reference while packing. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 1 | 2026-03-01 | Initial guide | --- ## Shopping Lists & Meal Planning URL: https://dont-panic.ambientchat.ai/article/shopping-lists-meal-planning Updated: 2026-08-13T22:15:13.385Z # Shopping Lists & Meal Planning Your pantry, your fridge, your spice rack — the AI knows what's in all of them. Which makes it remarkably good at telling you what to cook tonight and what to buy tomorrow. No more standing in the grocery aisle trying to remember if you already have cumin. ## What It Does ambientChat combines your inventory data, expiry tracking, and document capabilities into a practical meal planning and shopping workflow. The AI can look at what you have, what's expiring soon, and what you're missing — then suggest meals, create shopping lists, and save everything as searchable documents. This isn't a dedicated meal planning app with recipe databases and nutritional calculators. It's something arguably more useful: an AI that knows your actual kitchen and your actual preferences, and can write you a plan that accounts for both. ## How to Use It ### iOS App **The weekly routine:** The most effective way to use this feature is as a weekly cycle: **Step 1: Check what's expiring** 1. Open the **Chat** tab 2. Ask: *"What food is expiring in the next 7 days?"* 3. The AI checks your inventory and returns a list of items that need to be used soon **Step 2: Plan meals around what you have** 1. Ask: *"Suggest 5 dinners I can make this week using what's in my pantry, especially the things expiring soon"* 2. The AI searches your inventory, prioritizes expiring items, and suggests meals using ingredients you already own 3. It will note what you're missing for each recipe **Step 3: Generate a shopping list** 1. Ask: *"Create a shopping list for those meals — only include things I don't already have"* 2. The AI cross-references the recipe ingredients against your inventory 3. It creates a document with only the items you need to buy 4. The list is saved to your Documents (specify a folder if you like: *"Save it in my Groceries folder"*) **Step 4: Shop and scan** 1. Go shopping with your list (it's in your Documents tab) 2. After shopping, scan your receipt using the **Scan** tab 3. Your inventory is automatically updated with the new purchases 4. Expiry dates are estimated for perishable items **Step 5: Repeat next week** The AI remembers your meal plans and shopping history. Over time, its suggestions get better because it knows what you actually buy and cook. **Quick queries any time:** Beyond the weekly routine, you can ask meal and shopping questions any time: - *"What can I make for dinner with what I have right now?"* - *"I have chicken thighs and rice — what else do I need for a stir fry?"* - *"What spices do I have?"* - *"Am I running low on anything?"* - *"Create a shopping list — I'm going to Trader Joe's"* ### Via Claude Desktop (MCP) Claude Desktop can do everything the in-app chat can, using MCP tools: 1. **`list_expiring_items`** — check what's expiring soon 2. **`search_items`** with queries like *"pantry staples"* or *"proteins in freezer"* 3. **`create_markdown_document`** — save meal plans and shopping lists as documents 4. **`search_markdown_content`** — recall previous meal plans This is particularly useful for desktop meal planning — you might prefer a bigger screen for working through a week's worth of meals. ## Tips & Tricks - **Keep your pantry inventory current for best suggestions.** The AI can only suggest meals with ingredients it knows about. Scan your groceries regularly (even a quick photo of the full pantry shelf works) and the suggestions will be much more relevant. - **Use folders to organize lists by store.** If you shop at multiple stores, ask the AI to create separate lists: *"Create a Costco list for bulk items and a Trader Joe's list for specialty ingredients."* Save each to its own folder for easy access while shopping. - **Scan receipts immediately after shopping.** This closes the loop — your inventory updates with what you bought, so next week's meal plan and shopping list are accurate. The longer you wait to scan, the less the AI knows about your current stock. ## Sample Conversations Here are some real examples of how to talk to your AI about food: **Expiry-driven cooking:** > You: *"What's expiring in the next 3 days?"* > AI: *"You have Greek yogurt (expires tomorrow), baby spinach (expires in 2 days), and cherry tomatoes (expires in 3 days)."* > You: *"What can I make with those?"* > AI: *"A spinach and tomato frittata would use all three. You'll need eggs — I see you have a dozen. Or a Mediterranean yogurt bowl with the tomatoes and some of your granola."* **Shopping from scratch:** > You: *"I want to meal prep lunches for the week. I like Mediterranean food. What should I buy?"* > AI: *"Based on what you already have (olive oil, feta, rice, canned chickpeas, lemons), you'd just need: pita bread, cucumbers, hummus, and fresh herbs. I can create a shopping list document if you'd like."* ## Options | Setting | What It Does | Default | |---------|-------------|---------| | Expiry check window | Default number of days for expiry alerts | 14 days | | Shopping list folder | Where shopping lists are saved | My Documents | | Meal plan folder | Where meal plans are saved | My Documents | ## Known Limitations - **AI meal suggestions depend on inventory accuracy.** If your inventory is out of date (you ate the chicken last week but never removed it), the AI will suggest meals with phantom ingredients. Keep your inventory current for reliable suggestions. - **No direct integration with grocery delivery services.** The AI creates lists, but you can't one-tap order from Instacart or Amazon Fresh. Copy the list to your delivery app of choice. - **Nutritional calculations are approximate.** When the AI suggests meals, any calorie or macro estimates are based on general food data, not precise measurements of your specific products. - **Recipe detail varies.** The AI gives you meal ideas and ingredient lists, not step-by-step cooking instructions with photos. For detailed recipes, ask the AI to elaborate on a specific dish, or pair ambientChat with a dedicated recipe app. - **No quantity tracking for bulk items.** If you bought a 5-pound bag of rice, the inventory knows you have rice but may not know how much is left after several meals. Update quantities manually or re-scan periodically. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 1 | 2026-03-01 | Initial guide | --- ## Creating Documents — Notes, Lists & Reports URL: https://dont-panic.ambientchat.ai/article/creating-documents-notes-lists-reports Updated: 2026-08-13T22:15:13.248Z # Creating Documents — Notes, Lists & Reports Documents in ambientChat aren't just receipts and manuals that you scan. You can create your own — notes, lists, plans, meal prep schedules, gift ideas, anything you want to write down and have your AI remember. Think of it as a notebook that your AI can actually read. ## What It Does Beyond storing receipts and product manuals, ambientChat lets you create and manage your own markdown documents. These documents become part of your AI context — searchable, queryable, and available whenever you ask your AI assistant a question. Markdown is a simple formatting language. If you've ever used `**bold**` or `# heading` in a message, you already know the basics. Your documents can have headings, bullet lists, tables, links, and any structure you need. They can also carry YAML frontmatter — structured metadata like title, tags, category, and version — that makes them easy to organize and find later. Every document you create is processed for semantic search. This means your AI can find your documents by meaning, not just by the exact words you used. Write a packing list for "beach vacation" and your AI will find it when you later ask about "trip to the coast." ## How to Use It ### iOS App **Creating a document via chat:** The most natural way to create a document is to ask your AI: 1. Open the **Chat** tab 2. Ask the AI to create what you need: - *"Create a packing list for my camping trip next weekend"* - *"Write up a shopping list based on what I'm running low on"* - *"Make a note about the plumber's visit — they fixed the kitchen sink, charged $180, and said the water heater should be replaced within a year"* 3. The AI creates the document and saves it to your chosen folder (or the default folder if you don't specify one) 4. Find it in the **Documents** tab under **My Things** **Uploading a markdown file:** 1. Open the **Documents** tab in My Things 2. Tap the **+** button 3. Choose **File Browser** 4. Select a `.md` file from your device 5. The file is uploaded, parsed, and indexed — ready for AI search **Editing a document by hand:** 1. Open the document and tap the **pencil** in the top bar — it's always there, so you never have to scroll to the bottom of a long note to find it 2. Type in the editor, or use the formatting bar above it — headings, bold, italic, strikethrough, code, bullet list, numbered list, quote. Tags sit below the text, out of your way until you want them 3. Tap **Save** in the top bar — while you're editing, the top bar becomes the edit controls: **✕** discards, **Save** commits Everything else a document can do — move it, print it, export it, change its type, undo the last saved change, delete it — lives behind the **⋯** button in the same top bar. ### Web **Uploading markdown files:** 1. Go to the **Documents** section 2. Click **Upload** 3. Select one or more `.md` files 4. Documents are processed and appear in the current folder The web interface also supports drag-and-drop: just drag a `.md` file onto a folder to upload it there directly. **Editing a document by hand:** 1. Open the document and click **Edit** 2. Type in the editor, or use the formatting bar above it — headings, bold, italic, strikethrough, code, link, bullet list, numbered list, quote. Tags sit below the text, out of your way until you want them 3. Click **Save** Occasional actions — undo or redo the last saved change, and on a narrow window Ask AI and Share — live behind the **⋯** button in the header. ### Via Chat Your AI assistant is your primary document author. Some examples: **Creating from scratch:** - *"Create a document called 'Home Maintenance Schedule' with sections for monthly, quarterly, and annual tasks"* - *"Write a meal plan for this week using ingredients from my pantry"* - *"Make a gift list for the holidays — I need ideas for Mom, Dad, and my sister"* **Creating from your data:** - *"Summarize everything I bought at Costco this month and save it as a document"* - *"Create an inventory report of my garage for insurance purposes"* - *"Write up a comparison of the coffee makers I own"* **Updating existing documents:** - *"Add 'sunscreen' to my beach packing list"* - *"Update the Home Maintenance Schedule — mark the furnace filter as done for March"* - *"Replace the 'Dinner' section of my meal plan with pasta recipes"* The AI can update documents at the section level — it can replace or append to a specific heading without touching the rest of the document. ### Via Claude Desktop (MCP) The markdown tools give Claude Desktop full document authorship: - **`create_markdown_document`** — Create a new document with title, content, optional folder, and YAML frontmatter - **`update_markdown_document`** — Update content, or target a specific section by heading name (replace or append) - **`undo_markdown_update`** — Undo: step the document one change back. Repeat to keep going back - **`redo_markdown_update`** — Redo: step one change forward again - **`get_markdown_document`** — Retrieve a document's full content, metadata, and table of contents - **`list_markdown_documents`** — List documents filtered by folder or tags - **`search_markdown_content`** — Semantic search across all your markdown documents For the full tool reference, see [MCP Tools — Complete Reference](20-mcp-tools.md). Example: Tell Claude Desktop *"Create a shopping list document in my Groceries folder with everything I need to restock from my pantry"* and it will search your inventory for low or expired items, compose the list, and save it as a searchable document. ## Office Documents — Excel, Word & PowerPoint Your AI can also build real Microsoft Office files from your data — a spreadsheet, a Word document, or a slide deck — and save them to your library just like any other document. Ask in chat (mobile, web, or a connected assistant): - *"Make a **spreadsheet** of everything expiring this month"* → an Excel `.xlsx` - *"Give me a **CSV** of my inventory"* → a plain `.csv`, ready to import into another program - *"Write this conversation up as a **Word document**"* → a Word `.docx` - *"Build a **slide deck** summarizing my Kitchen view"* → a PowerPoint `.pptx` The AI gathers the data (your inventory, documents, or the chat itself), composes the content, and generates the file. When it's done it gives you a **Download** link in chat, and the file appears in your **Documents** tab with a format icon (📊 / 📝 / 📈). Open any Office document from its detail view and tap **Download** to open it in Excel, Word, PowerPoint, or any compatible app — the files are fully editable, not flattened to PDF. **A generated `.csv` you can fix in place.** Open it and you get the table, not a download stub — and the pencil edits the file directly, so a wrong value or an unwanted row takes seconds rather than a download-edit-reupload round trip. See [Editing a Document](06-documents.md#editing-a-document). Generated `.xlsx`, `.docx` and `.pptx` files are still download-to-edit: those formats carry styling and multiple sheets that a text editor can't represent honestly. **Ask for the right columns.** A generated spreadsheet contains the columns the AI chose. If it gives you fewer than you wanted, say so — *"add value, quantity and location"* — and it will regenerate with them. For a straight dump of your own items, asking to **export** rather than to *make a spreadsheet* gets you the full column set without the AI deciding what to include. Because the generated file lands in your library, it gets the same folders, search, and sharing as everything else — you can move it, share it by email, or find it later by asking your AI. ### Via Claude Desktop (MCP) - **`create_data_file`** — Generate an `.xlsx`, `.docx`, `.pptx`, or `.csv` from structured content and save it to your library. Returns a download link. Provide `sheets` for a spreadsheet or CSV (a CSV takes exactly one sheet — it's a single table), `markdown` for a Word document, or `slides` for a presentation. ## Document Format Documents use **Markdown** with optional **YAML frontmatter**: ```markdown --- title: Weekend Camping Packing List version: 1 tags: [travel, camping, outdoors] --- # Weekend Camping Packing List ## Shelter & Sleeping - Tent (2-person) - Sleeping bags (2) - Sleeping pads - Camping pillow ## Cooking - Portable stove - Fuel canister - Pot and pan set - Plates, cups, utensils ## Clothing - Hiking boots - Rain jacket - Warm layers (check weather forecast) ``` **Frontmatter fields you can use:** | Field | Purpose | Example | |-------|---------|---------| | `title` | Document title | `"Weekly Meal Plan"` | | `version` | Version number (auto-incremented on update) | `1` | | `tags` | Searchable tags | `[recipes, shopping, meal-prep]` | | `category` | Document category | `help`, `note`, `list`, `report` | | `status` | Publication status | `draft`, `published` | ## Tips & Tricks - **Documents appear alongside your receipts and manuals in the Documents tab.** They're first-class citizens — same search, same folders, same AI context. There's no separate "notes" section to check. - **Use headings to structure documents for section-level updates.** When you ask the AI to "update the Dinner section," it finds the `## Dinner` heading and replaces just that section. Good structure makes documents easier to maintain over time. - **Tags in frontmatter make documents easier to find.** Adding `tags: [travel, hawaii, 2026]` to your vacation planning document means your AI can find it when you ask about any of those topics, even months later. - **To turn typed lines into a list, select them all and press • List or 1. List.** Every selected line becomes an item in one press. Press the same button again to turn the list back into plain lines, or press the other one to convert between bullets and numbers — the heading and quote buttons work the same way. This step matters because of how markdown works: lines with nothing in front of them run together into a single paragraph when the document is displayed, however many times you pressed Return. The `-` or `1.` in front of each line is what makes it a list. - **Once you're in a list, Return keeps it going.** Press Return at the end of `- Eggs` and the next line starts as `- ` already; in a numbered list it counts on — `2.`, `3.`, and so on. Press Return on an item you haven't typed anything into and the marker comes off, which is how you end the list and go back to ordinary paragraphs. Quotes carry the same way. - **Numbering picks up where the list above it left off.** Pressing 1. List on the line under `1. Flour` gives you `2.`, not another `1.` — so you can number lines one at a time and still end up with a single, correctly counted list. ## Options | Setting | What It Does | Default | |---------|-------------|---------| | Default folder | Where new documents are saved when no folder is specified | My Documents | | Auto-version | Whether version numbers auto-increment on update | On | | Embedding generation | Whether documents are indexed for semantic search | On | ## Known Limitations - **No rich text editor.** Documents are markdown: what you edit is the source text, with the formatting syntax visible (`**bold**`, `- bullets`, `## headings`). There is a formatting bar that writes that syntax for you, but you see the markers while editing and the styled version only after you save. The AI handles most of the formatting for you when it creates documents, so you rarely need to type raw markdown yourself. - **Images must be linked, not embedded.** You can include image URLs in markdown (`![alt](url)`), but you can't paste or drag images directly into a document. For image-heavy content, use the scanning workflow instead. - **No collaborative editing.** Documents belong to one user. There's no shared editing, commenting, or version merging between users. If you need to share, export the document. - **Section-level updates depend on heading structure.** The `update_markdown_document` tool matches sections by heading text. If your document doesn't use headings, the entire content gets replaced. Asking to update a heading that has sub-headings beneath it is refused, because replacing it would delete those subsections too — say which subsection you mean, or ask for the whole document to be rewritten. - **Undo and Redo work the way they do in a word processor.** Say "undo that" and the document steps back one change; say it again and it steps back another (up to 19 changes are kept). "Redo" steps forward again. As soon as you make a *new* edit, anything you'd undone past is discarded — same as Word. Undo covers markdown documents, not generated Excel/Word/PowerPoint files. - **Frontmatter parsing handles common cases.** The YAML parser supports simple `key: value` pairs and arrays (`[item1, item2]` or `- item` lists). Nested objects and complex YAML structures are not supported. - **Generated Office files are downloads, not in-app editors.** A generated Excel/Word/PowerPoint file opens in Excel, Word, PowerPoint, or a compatible app — ambientChat doesn't edit them in place. To change one, ask the AI to regenerate it with the updated content (it creates a fresh file). ## Version History | Version | Date | What Changed | |---------|------|-------------| | 9 | 2026-08-01 | Save and Cancel moved into the top bar while editing, so you no longer scroll to the bottom of a long note to finish | | 8 | 2026-07-31 | Document controls moved into the top bar: the pencil edits, ⋯ holds move/print/export/change-type/undo/delete. The old button grid at the foot of the page is gone, and tags now sit below the text you're writing | | 7 | 2026-07-31 | Return continues a list (and ends it on an empty item); numbering counts on from the list above; long lines wrap in the web editor instead of running off the right edge | | 6 | 2026-07-31 | Formatting bar gained a numbered-list button, and the list/heading/quote buttons now apply to every line you select (and toggle off on a second press) | | 5 | 2026-07-27 | Redo added; Undo now walks back through history one change at a time (word-processor behaviour) | | 4 | 2026-07-26 | Undo for document edits (`undo_markdown_update`); replacing a heading that has subsections now asks you to confirm what you meant | | 5 | 2026-08-10 | A generated `.csv` opens as a table and can be edited in place — the pencil edits the file itself, and "undo that edit" puts the previous file back | | 4 | 2026-07-28 | Generated files can now be plain `.csv` too. The tool that makes them is renamed `create_data_file` (it was `create_office_document`, which stopped being true once it made non-Office files) | | 3 | 2026-06-27 | Added Office documents — generate Excel/Word/PowerPoint files from chat (`create_data_file`) | | 2 | 2026-06-07 | Terminology: "Admin Web" → "Web" (the web interface); web upload via Scan page | | 1 | 2026-03-01 | Initial guide | --- ## Admin — User & Beacon Management URL: https://dont-panic.ambientchat.ai/article/admin-user-beacon-management Updated: 2026-08-13T22:15:13.063Z # Admin — User & Beacon Management If the Dashboard is the bridge, this is the engine room. Here's where you actually manage the people, devices, and data that make up your ambientChat deployment. ## What It Does The Admin Console goes well beyond a dashboard. It provides full management capabilities for user accounts, beacon infrastructure, billing oversight, scan pipeline monitoring, chat auditing, and system diagnostics. Every section has search, filtering, and the ability to take action — not just look at numbers. This guide covers the operational sections of the admin console: the places where you do things rather than just observe them. ## How to Use It ### Web The operational web admin screens below live in the superuser-only **Admin** section of the web interface, namespaced under `/admin/*`. #### User Management **Finding users:** 1. Go to the **Users** section from the sidebar 2. Use the **search bar** to find users by name, email, or user ID 3. Results appear as a list with key details: name, email, subscription tier, last active date **User detail view:** Click any user to see their full profile: - **Account info** — email, sign-in provider, account creation date, last login - **Subscription tier** — Free, Standard, Premium, or Max - **Billing status** — active subscription, billing exempt, credits remaining - **Usage metrics** — chat messages, scans, storage used - **Role** — regular user, brand admin, or superuser **Managing user billing:** Navigate to a user's billing detail view to see: - Current subscription tier and renewal date - Credit usage history - Whether the user is billing-exempt (superusers, partners) - Ability to adjust tier or exemption status (superuser only) #### Billing Administration The **Billing** section provides the financial overview: - **Revenue tracking** — subscription revenue by tier, period, and trend - **Tier breakdown** — how many users are on each subscription tier - **Usage analytics** — aggregate credit consumption, peak usage times - **Exemptions** — list of billing-exempt accounts and the reason for each #### Beacon Management The **Beacons** section is your command center for the physical beacon infrastructure: - **Beacon registry** — all registered beacons with their UUID, major, minor, and location - **Active regions** — which beacon regions are currently being monitored - **Beacon statistics** — detection counts, visit frequency, signal strength data - **Alert configuration** — set alert modes for specific beacons or regions Beacons are the physical Bluetooth devices that create location-aware zones. When a user's phone detects a beacon, the system logs the visit and includes that context in their AI conversations. Managing beacons means making sure the right devices are registered and the detection infrastructure is healthy. #### Scan Administration The **Scans** section monitors the image processing pipeline: - **Processing queue** — see what's currently being processed and what's waiting - **Failed jobs** — inspect scans that failed to process, with error details - **Retry controls** — manually retry failed jobs after fixing the underlying issue - **Statistics** — processing times, success rates, queue depth over time When users scan barcodes, receipts, or photos, the images go through a processing pipeline. This section lets you monitor that pipeline and intervene when something goes wrong. #### Chat Administration The **Chat** section provides conversation auditing capabilities: - **Conversation search** — find specific conversations by content, user, or date - **Message inspection** — see the full exchange including user messages, AI responses, tool calls, and context used - **Usage tracking** — which LLM models are being used, token consumption, cost per conversation This is useful for investigating user-reported issues ("The AI gave me a weird answer") or monitoring overall chat quality. #### Diagnostics The **Diagnostics** section is the system health dashboard: - **Function health** — Cloud Function execution status, error rates, latency - **Firestore inspection** — browse collection structure, document counts, storage usage - **Storage statistics** — Cloud Storage usage by category (images, documents, exports) - **Error trending** — error frequency over time, grouped by function and type When something is broken, this is where you start investigating. #### Audit Log Every action taken in the admin console is logged: - **Who** did it (admin user ID and email) - **What** they did (action type and details) - **When** they did it (timestamp with timezone) - **What changed** (before and after state for modifications) The audit log is append-only — entries cannot be modified or deleted. It's your accountability trail. #### Configuration The **Configuration** section manages system-wide settings: - Feature flags and toggles - Tier definitions and credit allocations - System prompts and AI behavior settings - Partner configurations Changes here affect all users, so proceed with caution. Most configuration changes require a deploy cycle to take full effect (see the Dev-First Workflow in the development documentation). ## Tips & Tricks - **Use search liberally in the Users section.** With many users, scrolling isn't practical. Search by email is the fastest way to find a specific account, especially when a user reports an issue. - **Check Diagnostics when users report problems.** If someone says "chat isn't working" or "my scan failed," the Diagnostics and Scans sections will show you the server-side story. Error details there are far more informative than what the user sees on their device. - **The Audit Log is your friend during investigations.** If a configuration changed unexpectedly or a user's account was modified, the audit log tells you exactly who did what and when. Start there when something seems off. ## Options | Setting | What It Does | Default | |---------|-------------|---------| | Search scope | Whether user search matches name, email, or both | Both | | Audit log retention | How long audit entries are kept | Indefinite | | Failed job auto-retry | Whether failed scan jobs are automatically retried | Off (manual retry) | | Diagnostics refresh | How often diagnostic data refreshes | On page load | ## Known Limitations - **Destructive operations require confirmation.** Deleting user accounts, clearing data, and emptying trash all go through the confirmation workflow with time-limited approval windows. This is by design — no accidental deletions. - **Some configuration changes require a deploy.** Updating seed scripts or feature flags in the Configuration section queues changes, but they may not take effect until the next deploy cycle. The console will indicate when a deploy is needed. - **Cross-organization data access is superuser-only.** Brand admins can only see and manage users within their organization's scope. Viewing data across organizations requires superuser privileges. - **Beacon management is registry-only.** The web admin screens manage the beacon registry (which beacons exist and their properties), but physical beacon hardware configuration (power levels, advertising intervals) must be done through the beacon manufacturer's own tools. - **Bulk operations have limits.** You can manage users and beacons individually, but bulk operations (e.g., changing 100 users' tiers at once) are not yet supported through the console. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 2 | 2026-06-08 | Reflect /admin/* namespacing + the "Admin" sidebar section; "Admin Web" → "Web" (AMB-303) | | 1 | 2026-03-01 | Initial guide | --- ## Admin Console — Dashboard & Management URL: https://dont-panic.ambientchat.ai/article/admin-console-dashboard-management Updated: 2026-08-13T22:15:12.950Z # Admin Console — Dashboard & Management The bridge of the starship, if you will. One web page to monitor everything happening across your ambientChat deployment — users, beacons, errors, and the general state of the universe. ## What It Does The web admin screens are the superuser-only **Admin** section of the web interface, namespaced under `/admin/*`. They provide a centralized dashboard with real-time statistics, error monitoring, and access to every administrative function in the system. If the mobile app is where users interact with their data, the Admin section is where you make sure everything is working properly for everyone. The dashboard is your landing page — a quick-glance summary of platform health, user activity, and system status. From there, you can drill into any area that needs attention. ## How to Use It ### Web **Accessing the web admin screens:** 1. Open the web interface in any modern web browser - Dev environment: `ambientchat-dev.web.app` - Production: `app.ambientchat.ai` 2. Sign in with your usual credentials (same login as the mobile app); your account must have an admin or superuser role 3. The superuser-only **Admin** section appears in the sidebar. You'll land on the **Dashboard** at `/admin/dashboard` — the home screen for all admin activity **Dashboard overview:** The dashboard presents key metrics in a widget layout: | Widget | What It Shows | |--------|-------------| | **User Statistics** | Total registered users, active users, new signups | | **Partner Counts** | Number of partner organizations and their users | | **Beacon Statistics** | Total beacons registered, active regions, recent detections | | **Error Monitoring (24h)** | Error count and rate over the last 24 hours — the number you want to keep at zero | | **Search Fallback Events** | When semantic search falls back to keyword search — indicates embedding gaps | | **Login Analytics** | Recent login activity, sign-in methods, failed attempts | **Navigation:** The **Admin** section of the sidebar gives you access to every web admin screen (all namespaced under `/admin/*`): | Section | What You'll Find | |---------|-----------------| | **Dashboard** | The overview you're looking at right now | | **Users** | Search, browse, and manage user accounts | | **Billing** | Revenue tracking, tier breakdowns, usage analytics | | **Chat** | Conversation audit, message search | | **Scans** | Processing queue status, failed jobs, retry controls | | **My Things** | Inventory overview across users | | **Beacons** | Beacon registry, region management, alert configuration | | **Partners** | Partner organization management | | **Configuration** | System settings, feature flags, tier definitions | | **Diagnostics** | Function health, Firestore inspection, storage stats | | **Audit Log** | Complete trail of every admin action with timestamps | | **Settings** | Admin console preferences | | **Profile** | Your admin profile | | **Delete Account** | Account deletion management (with confirmation workflow) | **Role-based access:** Not everyone sees everything. Access is scoped by role: - **Superusers** see the full console — every section, every user, every setting - **Brand admins** see their organization's users and data, but not system-wide configuration or other organizations' data - **Regular users** cannot access the admin console at all — they'll be redirected to sign-in ## Tips & Tricks - **Check the error monitoring widget daily.** A spike in errors is the earliest signal that something needs attention. The 24-hour window keeps the view current without overwhelming you with historical noise. - **Search fallback events matter.** When the system falls back from semantic search to keyword search, it means some items or documents are missing embeddings. This affects search quality for users. If the count is climbing, investigate the embedding generation pipeline. - **Bookmark the dashboard.** It's the fastest way to get a pulse on platform health. Most admin sessions should start here before diving into specific sections. ## Options | Setting | What It Does | Default | |---------|-------------|---------| | Dashboard refresh | How often dashboard widgets refresh their data | On page load | | Theme | Light or dark mode for the admin console | System default | | Timezone | Display times in your local timezone | Browser timezone | ## Known Limitations - **The web admin screens are web-only.** There is no mobile admin app — use a desktop or tablet browser for the best experience. - **Some operations require superuser role.** Configuration changes, system diagnostics, and cross-organization data access are restricted to superusers. Brand admins will see these sections grayed out or hidden. - **Dashboard data is not real-time streaming.** Widgets update when the page loads or when you manually refresh. For real-time monitoring of specific events, use the Diagnostics section. - **Browser compatibility.** The console works best in Chrome, Safari, Firefox, and Edge. Older browsers may not render all dashboard widgets correctly. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 2 | 2026-06-08 | Reflect /admin/* namespacing + the superuser-only "Admin" sidebar section; "Admin Web" → "Web" (AMB-303) | | 1 | 2026-03-01 | Initial guide | --- ## MCP Tools — Using ambientChat with Claude Desktop URL: https://dont-panic.ambientchat.ai/article/mcp-tools-using-ambientchat-with-claude-desktop Updated: 2026-08-13T22:15:12.698Z # MCP Tools — Using ambientChat with Claude Desktop Your AI context doesn't have to stay trapped inside one app. With MCP (Model Context Protocol), you can bring your entire ambientChat world into Claude Desktop, brand apps, or any compatible AI client — and it works exactly like having a very well-informed research assistant sitting at your desk. All tools respect your authentication. The AI can only access **your** data, using **your** credentials. Nobody else's stuff, ever. --- ## Inventory Tools Manage your physical items — everything you've scanned, photographed, or manually added. | Tool | What It Does | |------|-------------| | `list_items` | List all items, optionally filtered by category, folder, or search query | | `get_item` | Get full details of a specific item — name, brand, price, expiry, location, notes, nutritional data | | `search_items` | Semantic search — finds items by meaning, not just keywords ("things in my garage", "snacks for the party") | | `list_expiring_items` | Find items expiring within a number of days (default 14), soonest first. Set `include_expired` to also see items already past their date; `limit` sets the page size (default 200) and `truncated` flags when more match | | `get_items_at_scene` | List items last seen at a specific physical location — identified by beacon, GLN, or scene ID | | `get_scan_session_items` | List items created together in the same scan session (scan siblings) | | `update_item` | Edit any item field — name, brand, category, price, expiry date, location, notes | | `update_items_by_filter` | Bulk-update fields across many items in one call. Say "change all items in the kitchen to category Food" | | `trash_item` | Move a single item to trash (soft delete). Cleans up linked documents | | `trash_items` | Bulk move multiple items to trash at once | | `restore_item` | Restore an item from trash back to the inventory | | `regenerate_item_image` | Generate a fresh AI illustration for an item. Costs credits | **Example things you can say:** - "What's in my pantry?" - "Show me everything expiring this week." - "Change the category of all my vitamins to Health." - "How much is my electronics collection worth?" - "What was scanned with the olive oil?" (scan siblings) - "What did I leave in the garage?" (items at scene) --- ## Document Tools Navigate, search, and manage your digital paperwork — receipts, manuals, photos, and files. | Tool | What It Does | |------|-------------| | `list_documents` | List documents with optional filters for media type, category, and folder | | `get_document` | Get full document details — AI summary, linked items, metadata | | `search_documents` | Keyword search across document titles, summaries, and content | | `search_documents_semantic` | AI-powered semantic search — finds documents by meaning, returns full content | | `update_document` | Update a document's title, description, and/or tags. Improves search and accessibility | | `upload_document` | Upload a new document (image or PDF) into a folder for AI processing. Provide the bytes one of three ways: a Firebase Storage URL, a `get_document_upload_url` storage path, or inline base64 (max 10MB) | | `get_document_upload_url` | Get a short-lived signed URL for uploading document bytes directly to storage, then hand the returned path to `upload_document`. This is how an AI client that holds a file (e.g. one with a code-execution sandbox) gets it into a folder without inlining the bytes | | `get_scan_status` | Check the status of an upload/scan job by its `jobId` (returned by `upload_document`). Tells you whether it's still processing, complete (with the created document/item), or failed (with the reason) — so you don't have to keep refreshing the folder | | `move_document` | Move a document between folders | | `link_document_to_item` | Attach a document you already have to one of your inventory items — the manual, warranty, receipt, or spec sheet that belongs with a thing you own | | `unlink_document_from_item` | Detach a document from an item. Removes only the link; both records stay | | `add_document_pages` | Add the photos you attached to this message as extra pages of an image document — how a photographed multi-page manual becomes ONE document instead of a pile of photos | | `combine_documents` | Gather several photo documents into ONE multi-page document — the fix for a manual uploaded page by page. The first keeps its identity; the rest become its pages and go to Trash | | `remove_document_page` | Remove one page from a multi-page document by its number | | `get_item_documents` | List the paperwork attached to an item — its manual, warranty, receipt, or the scan photo it came from | | `trash_document` | Move a document to trash (soft delete). Cleans up linked inventory items | | `restore_document` | Restore a document from trash | | `regenerate_document_image` | Generate an AI illustration thumbnail for a document. Costs credits | | `generate_image` | Create an image from a text description — optionally grounded in your own photos. Say "draw my armchair in a jungle" and the armchair's actual photo is shown to the generator so the result looks like *your* armchair, not a generic one; "me as an astronaut" uses your profile photo. The per-image price is checked against your balance before generating, only delivered images are charged, and the result is saved into your context as an image document — with a recipe showing exactly what went into the prompt (and whether each reference was matched from its photo or just described) and a scorecard grading the image against your brief. Say "dual" or "show me both" to run the same brief on Gemini AND OpenAI side by side and pick your favorite. Ask for "widescreen" (3:2) or "phone wallpaper" (9:16) shapes, and say "final quality" for the premium render (paid plans). Prefer knobs over words? Open **Image Studio** — the ✦ button in chat, or the sidebar on web — for a full composer with model, quality, and shape controls plus live pricing. To build on something you already have, add it as a reference from **My Stuff** inside the composer | | `resolve_dual` | After a Dual image run, record your verdict: pick a winner (the other image moves to Trash, recoverable) or keep both — no extra charge either way. Works by voice too: "keep the Gemini one", "keep both" | **Example things you can say:** - "Make me an image of my armchair reupholstered in mustard." - "Generate a picture of a lighthouse at dusk and save it to my Ideas folder." - "Find my Costco receipts from January." - "Show me all my warranty documents." - "Move the washing machine manual to the Appliances folder." - "What receipts do I have for tax deductions?" - "Save these photos into my Medical folder." (uploads the attached images for processing) - "That PDF is the manual for my cordless drill — file it against that item." - "Add these three photos as pages of the drill manual." - "Read page 11 of the manual and tell me the torque setting." - "Those three photos are all the same manual — combine them into one document." - "Do I have the warranty for the dishwasher?" - "Detach that receipt from the lawnmower, it belongs to the hedge trimmer." - "Did that upload finish?" (checks the upload job's status) --- ## Views (Folders) Organize your items and documents into folders and views. | Tool | What It Does | |------|-------------| | `list_views` | List folders at a given level of the hierarchy | | `get_view` | Get folder details and its first 20 documents | | `get_view_tree` | See the entire folder hierarchy at a glance, with item, document, and subfolder counts | | `get_view_members` | Get the union of items and documents in a folder | | `create_view` | Create a new folder. Idempotent — won't create duplicates | | `update_view` | Rename a folder, change its description, sort order, or thumbnail mode | | `reorder_views` | Batch update the sort order for multiple folders | | `generate_view_icon` | Generate an AI icon for a folder based on its name and contents. Costs credits | | `add_items_to_view` | Tag items with a folder — adds them without removing prior folder memberships | | `move_items_to_view` | Move items to a single destination folder | | `remove_items_from_view` | Remove items from a folder | | `navigate_up` | Navigate to the parent folder | **Example things you can say:** - "Create a folder called Holiday Gifts." - "Move all the spices into the Spice Rack folder." - "How many items are in each folder?" - "Generate an icon for the Kitchen folder." --- ## Markdown Documents Create, edit, and search your own written documents — notes, lists, reports, and more. | Tool | What It Does | |------|-------------| | `create_markdown_document` | Create a new markdown document with optional YAML frontmatter and folder placement | | `update_text_document` | Replace the contents of any TEXT document — note, `.txt`, `.csv`, `.tsv`. Send the complete new text, not a patch. Read it with `get_document({include_source: true})` and edit `source_text` — **not** `raw_text`, which for a spreadsheet is a searchable summary rather than the file. A spreadsheet that doesn't parse is refused, not saved | | `undo_text_update` | Step a text document one state back. For a spreadsheet this restores the previous *file*, byte for byte | | `redo_text_update` | Step one state forward, undoing an undo | | `get_markdown_document` | Retrieve a document's full content, parsed frontmatter, table of contents, and version info | | `list_markdown_documents` | List markdown documents, optionally filtered by folder, type, or tags | | `search_markdown_content` | Semantic + keyword search across markdown document content | | `read_document_rows` | Read a window of rows from a stored spreadsheet (`.csv`, `.tsv`, or Excel `.xlsx`) — pages through a large file the document text only partly shows. For a workbook it reads one **sheet** at a time, names the sheet it read, and lists the others | | `propose_import_mapping` | Work out what each column of a stored spreadsheet means before importing it, and recall the mapping you approved for that file layout last time | | `create_items_bulk` | Turn mapped spreadsheet rows into inventory items as ONE reversible operation — duplicates skipped, "undo that" removes the whole import | | `create_data_file` | Generate a file from content and save it to your library with a download link — Excel `.xlsx`, Word `.docx`, PowerPoint `.pptx`, or a plain `.csv` | **Example things you can say:** - "Create a packing list for my Hawaii trip." - "Make a spreadsheet of everything expiring this month." → `create_data_file` - "Give me a CSV of my inventory I can import elsewhere." → `create_data_file` - "How many rows are in that spreadsheet, and what's in row 500?" → `read_document_rows` - "Add everything in that spreadsheet to my inventory." → `propose_import_mapping` then `create_items_bulk` - "What sheets are in that workbook? Read the Q2 one." → `read_document_rows` (it reports every sheet, and takes a sheet by name or number) - "Write a summary of what I bought this month." - "Update the recipes section of my meal plan." - "Find my notes about home insurance." --- ## Skills **Skills** are reusable SKILL.md playbooks that orchestrate your inventory, documents, tags, location, and beacons. The first-party set — curated by ambientChat — is available to everyone (read-only), and you can author your own on any Standard-or-higher plan. The same skills work in Claude and ChatGPT when you connect ambientChat there. | Tool | What It Does | |------|-------------| | `list_skills` | List the skills available to you — first-party plus your own — with name, slug, and description | | `get_skill` | Load a skill's full instructions (SKILL.md) by slug, ready to follow | | `create_skill` | Save a new skill of your own — name, slug, when-to-use description, and markdown instructions (Standard+) | | `update_skill` | Edit one of your own skills — its instructions, name, description, or tags. First-party skills stay read-only; creating your own with the same slug overrides them for you | **Example things you can say:** - "What skills can you run?" - "Use the Auto-Filer skill on this document." - "Run Renewals & Warranty Watch." - "Save what we just did as a skill called Weekly Fridge Audit." - "Update my trip-packer skill to always include chargers." --- ## Conversations & History Your Q&A history — every question you've asked and answer you've received. | Tool | What It Does | |------|-------------| | `journal_conversation` | Save a Q&A exchange to your history for searchable recall | | `recall_history` | Search your prior conversations — past Q&A, advice given, topics discussed. Filters by channel (voice/text/mcp), platform, session, or date range | | `list_conversations` | Browse your full Q&A history in date order, with paging. Use for "show my recent conversations"; use `recall_history` to find a specific topic | | `trash_conversation` | Move a conversation to trash (soft delete) | | `trash_conversations` | Bulk move multiple conversations to trash | | `restore_conversation` | Restore a conversation from trash | **Example things you can say:** - "What did we talk about last week?" - "Recall the recipe advice you gave me yesterday." - "What questions have I asked about insurance?" - "Delete all conversations from March." --- ## Change History & Undo Review and revert recent changes to your inventory. Every edit is tracked and reversible. | Tool | What It Does | |------|-------------| | `recent_item_changes` | See recent edits to inventory items — shows old and new values for each change | | `undo_item_change` | Revert a single-item edit by re-applying the old values | | `recent_bulk_changes` | List recent bulk inventory operations — useful after a mass update | | `undo_bulk_change` | Revert an entire bulk update in one call — every item the operation touched goes back | **Example things you can say:** - "What did you just change?" - "Undo that last edit." - "Show me the recent bulk changes." - "Revert the bulk update you made to my kitchen items." **How undo works:** Every change is logged with before/after values. You can undo individual edits or entire bulk operations. Undo is available from any surface — in-app chat, voice, Claude Desktop, or the web interface. --- ## Sharing Share your items, documents, conversations, and folders — with a person by email or with a whole group — and manage what others have shared with you. See the [Sharing guide](28-sharing.md) for the full walkthrough. **Share something out:** | Tool | What It Does | |------|-------------| | `share_with_email` | Grant a person live access to an item, document, folder, or conversation by email — read-only or read-write. Sends an invitation if they have no account yet | | `share_with_group` | Share something with an entire group at once | | `share_item` | Share an inventory item | | `share_document` | Share a document — includes title, type, and summary | | `share_conversation` | Share a Q&A answer | | `share_view` | Share a folder — cascades to its sub-folders and contents | | `list_my_shares` | See everything you've shared and with whom | | `revoke_share_grant` | Remove a share — access ends immediately | | `resend_invitation` | Re-send a pending invitation to someone who hasn't signed up yet | **Groups:** | Tool | What It Does | |------|-------------| | `create_group` | Create a group to share with several people at once | | `invite_to_group` | Invite a person to a group by email | | `accept_group_invitation` | Accept an invitation to join a group | | `list_my_groups` | List the groups you belong to | | `get_group_members` | See who's in a group | | `remove_group_member` | Remove a member — ends their access to the group's shares | | `delete_group` | Delete a group | **Shared with you (and mounting):** | Tool | What It Does | |------|-------------| | `list_shared_with_me` | See what others have shared with you | | `get_shared_resource` | Open a specific resource someone shared with you | | `list_shared_folder_contents` | List the contents of a shared folder | | `hide_shared_with_me` | Remove a share from *your* list (hides it for you only; owner's copy is untouched) | | `mount_shared_resource` | Add something shared with you (or with Everyone) into your own library, so it sits inline alongside your own content — like "Add to My Drive". The master stays with its owner, so you always see their latest version | | `unmount_shared_resource` | Remove a mounted shared resource from your library (reversible; doesn't delete the owner's content or revoke your access) | | `list_mounts` | List the shared resources you've added to your library | | `list_mounted_contents` | Resolve the shared resources you've mounted into a folder into their live data + provenance, so they show inline alongside your own content | **Example things you can say:** - "Share the olive oil with my wife, read-only." - "Share my Recipes folder with the family group." - "Who have I shared the Warranties folder with?" - "Stop sharing that receipt with the repair shop." - "Add the shared Skills to my library." --- ## Connected Services Connect outside tools (GitHub, Gmail, Calendar, Drive, Slack, Linear, Mercury, or any MCP server by URL) so the assistant can use them in chat alongside your own context. See the [Connected Services guide](29-connected-services.md). | Tool | What It Does | |------|-------------| | `list_mcp_servers` | List the services you've connected, with status and tool counts | | `add_mcp_server` | Connect a new MCP server by URL — OAuth handled where the provider supports it | | `update_mcp_server` | Edit a connection's settings or stored token | | `remove_mcp_server` | Disconnect a service — its tools leave chat and its access is revoked | **Example things you can say:** - "What services do I have connected?" - "Connect my GitHub." - "Match my Mercury transactions to the receipts in my library." - "Disconnect Slack." *(Connecting outside tools *into* ambientChat is the opposite of **Context Sharing** — the `get_context_sharing` / `update_context_sharing` tools below, which control what ambientChat shares *out* to Claude, brands, and partners.)* --- ## Tool Permissions Control what the assistant can do without asking — Anthropic-style per-tool cards. Every tool is **Auto** (runs automatically), **Ask** (approval prompt first), or **Blocked** (never runs). Writes to connected services ask by default; when a prompt appears you can tap **Always Allow** to stop being asked for that tool. Manage everything under **Settings → MCP Servers → Tool Permissions** (iOS and web). Safety tools like emptying trash or deleting your account always ask and can't be changed. | Tool | What It Does | |------|-------------| | `list_tool_permissions` | List every tool — built-in and from connected services — with its approval status | | `update_tool_permission` | Change a tool's policy to `approved`, `ask`, or `blocked` (asks you to confirm the change) | **Example things you can say:** - "Which tools need my approval?" - "Stop asking me about Linear writes." - "Block web search." - "Make save_issue ask again." --- ## Trash & Restore Manage your trash across all content types. | Tool | What It Does | |------|-------------| | `list_trash` | See everything currently in the trash, ordered by most recently trashed | | `restore_trash` | Generic restore — works for items, documents, and conversations without needing to know the type | | `empty_trash` | Permanently delete trash entries. Optional scope: "item", "document", or "all" | **Example things you can say:** - "What's in my trash?" - "Restore the last thing I deleted." - "Empty the trash." --- ## Search & Discovery Cross-cutting tools for finding information and getting answers. | Tool | What It Does | |------|-------------| | `web_search` | Search the web for current information — used when you need real-time data, recent events, or fact verification | | `query_expert` | Ask another AI model for a second opinion mid-conversation. Useful for comparing perspectives | | `get_user_context` | Assembles relevant context for your query — bio, nearby beacons, focus item details | **Example things you can say:** - "What's the current price of a KitchenAid mixer?" (triggers web search) - "Ask Gemini what it thinks about this recipe." (query expert) - "What do you know about me?" (user context) --- ## Settings & Profile Read and update your profile and app settings — all manageable via voice or chat. ### Profile | Tool | What It Does | |------|-------------| | `get_profile` | Get your profile — name, nickname, email, photo, timezone, home/work locations, and bio | | `update_profile` | Update profile fields — first name, last name, nickname, hail name, home/work location, and bio | | `upload_profile_image` | Upload a new profile photo from image data | | `reimagine_profile_image` | Re-render your profile photo as a claymation figurine portrait | ### Identity & Roles | Tool | What It Does | |------|-------------| | `get_identity` | Who you are and what you can do — your uid, email, role (superuser / brand-admin / brand-user / enduser), and whether you're a superuser | | `set_user_role` | (Superuser only) Grant or change a user's role by uid or email — audited; writes both the auth claim and the profile mirror so they stay in sync | ### Interests ("How I Roll") | Tool | What It Does | |------|-------------| | `list_interests` | List your interests / "how I roll" tags — free-text preferences that personalize AI responses | | `add_interest` | Add an interest tag (e.g. "vegetarian", "loves hiking") | | `remove_interest` | Remove an interest by id | ### AI & Scanning | Tool | What It Does | |------|-------------| | `get_ai_model_pref` | Get your default AI model preference | | `update_ai_model_pref` | Set your default AI model — validated against the model registry | | `get_ble_scan_rate` | Get your Bluetooth tag scan rate: off, eco, normal, or turbo | | `update_ble_scan_rate` | Set your Bluetooth scan rate | ### App Behavior | Tool | What It Does | |------|-------------| | `get_app_behavior_prefs` | Get app-behavior preferences — haptic feedback, sounds, keep source photos | | `update_app_behavior_prefs` | Update haptic feedback, feedback sounds, or the "keep source photos" toggle | | `get_background_trails_pref` | Get your background location trails master switch state | | `update_background_trails_pref` | Toggle background location trails on or off | ### Save Destinations | Tool | What It Does | |------|-------------| | `get_save_preferences` | Get your sticky save-destination — the folder new scans/items default into | | `update_save_preferences` | Set or clear your default save folder | ### Notifications & Context Sharing | Tool | What It Does | |------|-------------| | `get_notification_preferences` | Get beacon-category notification preferences — which categories are disabled | | `update_notification_preferences` | Toggle notifications for a single beacon category, or bulk enable/disable all | | `get_context_sharing` | Get third-party context-sharing preferences — master switch + per-service toggles | | `update_context_sharing` | Toggle context sharing for Claude Desktop, McCormick, Amazon, etc. | ### Account Management | Tool | What It Does | |------|-------------| | `get_account_deletion_precheck` | Pre-flight check — shows data counts, subscription status, and warnings | | `request_account_deletion` | Request account deletion. Creates a confirmation with 5-minute expiry | **Example things you can say:** - "Switch my default AI to Claude." - "Turn off haptic feedback." - "Set my scan rate to turbo." - "Turn off location trails." - "Stop sharing context with Amazon." - "Give me a claymation profile picture." --- ## Privacy Control how your ambient data (location, beacons) is shared with AI calls. | Tool | What It Does | |------|-------------| | `get_privacy_preferences` | Get your ambient-data privacy preferences — location precision per AI call type | | `update_privacy_preferences` | Update location precision settings for different AI call types | **Example things you can say:** - "What are my privacy settings?" - "Don't share my exact location with AI — use city-level only." --- ## Voice Preferences Control how the assistant speaks to you. | Tool | What It Does | |------|-------------| | `get_voice_preferences` | Get your voice/TTS settings — voice name, style, auto-speak, playback speed | | `update_voice_preferences` | Update voice name, style, auto-speak toggle, or playback speed | **Example things you can say:** - "Switch to the Shimmer voice." - "Speed up your speech." - "Stop auto-speaking responses." - "What voice are you using?" --- ## Settings Catalog Browse all available settings and their current values. | Tool | What It Does | |------|-------------| | `list_user_settings` | Read every settings document you have in a single structured payload | | `list_setting_dimensions` | Read the catalog of settings the AI can manage on your behalf | **Example things you can say:** - "Show me all my settings." - "What settings can you change for me?" --- ## Subscription & Usage Check your plan, credit balance, and usage history. | Tool | What It Does | |------|-------------| | `get_subscription` | Get your subscription summary — tier, period dates, credits used/remaining, exemption status | | `get_usage_state` | Get current usage and billing summary — tier, credits, streak, exemption status | | `get_billing_events` | Get itemized billing history — individual AI requests with credits consumed, model used, and token counts | **Example things you can say:** - "How many credits do I have left?" - "What plan am I on?" - "Show me my usage this month." - "What's my most expensive AI request?" --- ## Export & Import Move your data in and out of ambientChat. | Tool | What It Does | |------|-------------| | `print_resource` | Print an item, document, or saved answer — renders the branded PDF and (in the ambientChat app) opens the print dialog automatically | | `export_user_data` | Start an export of all your data as a ZIP archive — inventory, documents, conversations, preferences, settings, profile | | `get_export_status` | Check if your export is ready and get the download URL | | `get_import_upload_url` | Get a secure upload URL for importing data | | `import_user_data` | Import data from an uploaded archive — preserves original IDs and reconciles links | **Example things you can say:** - "Print this document." - "Print my coffee maker." - "Export all my data as a ZIP." - "Is my export ready?" - "Import data from the file I uploaded." --- ## Onboarding & Help Get started and find help. | Tool | What It Does | |------|-------------| | `get_ambientchat_welcome` | Get your personalized welcome card — tiles, greeting, suggested prompts, and next best action | | `get_help` | Search the help documentation (Don't Panic guides) for answers to your question | | `get_onboarding_state` | Read your onboarding progress — tier, engagement metrics, dismissed tiles, activation status | | `update_onboarding_state` | Update onboarding preferences — turn the welcome card off (`stop_showing`) or back on (`resume_showing`), dismiss tiles, restore dismissed items, reset | | `record_onboarding_event` | Record onboarding analytics events (used internally for A/B analysis) | **Example things you can say:** - "How do I scan a receipt?" - "Show me the getting started guide." - "Dismiss the welcome card." --- ## User Stats | Tool | What It Does | |------|-------------| | `get_user_stats` | Get counts of your content — active and trashed inventory items, documents, folders, and conversations | **Example things you can say:** - "How many items do I have?" - "Give me an overview of my account." --- ## Confirmation Tools Safety gates for irreversible actions. Some operations create a pending confirmation that you must approve within a short time window. | Tool | What It Does | |------|-------------| | `list_pending_confirmations` | See actions awaiting your approval | | `confirm_action` | Approve a pending action | | `deny_action` | Reject a pending action | Tools that require confirmation: `request_account_deletion` Tools that require failsafe confirmation: `empty_trash` --- ## Scan Regression Tools (Developer Only) These tools are restricted to superusers for internal quality testing. | Tool | What It Does | |------|-------------| | `get_scan_regression_runs` | List recent scan-regression harness runs with summary metrics | | `get_scan_regression_run` | Fetch one scan-regression run with full per-fixture detail | | `run_scan_regression` | Trigger a scan-regression run against deployed code | | `get_scan_regression_request` | Check the status of a previously created scan-regression request | --- ## How to Connect ### The MCP Server URL > **`https://mcp.ambientchat.ai`** That's the address. Point any MCP-compatible client at it, sign in with your ambientChat credentials, and the tools above become available. ### Via Claude Desktop (MCP) 1. Open **Claude Desktop** settings 2. Navigate to the **MCP Servers** configuration 3. Add a new MCP server with the URL **`https://mcp.ambientchat.ai`** 4. Authenticate with your ambientChat credentials 5. Claude Desktop will discover all available tools automatically ### Using Tools in Conversation Once connected, you don't need to call tools by name. Just ask natural questions and the AI uses the appropriate tools: - *"What food is expiring this week?"* → `list_expiring_items` - *"Find my Costco receipts from January."* → `search_documents` - *"How much is my electronics collection worth?"* → `search_items` - *"Create a packing list for my Hawaii trip."* → `create_markdown_document` - *"Change all items in the kitchen to category Food."* → `update_items_by_filter` - *"Undo that last bulk change."* → `undo_bulk_change` - *"Export all my data as CSV."* → `export_user_data` - *"What did we talk about last week?"* → `recall_history` - *"Share this recipe with my wife."* → `share_conversation` ## Tips & Tricks - **Same context everywhere.** MCP gives external clients the same context as in-app chat. The search quality, semantic matching, and data access are identical. - **Great for desktop workflows.** Writing a report? Planning a meal? Doing insurance paperwork? Your full inventory and document archive is accessible without switching to your phone. - **Combine tools naturally.** Search your inventory, then create a document summarizing what you found. The tools compose together — search, analyze, write, save — all in one conversation. - **Everything is undoable.** Bulk changes, individual edits, trash operations — all reversible. Say "undo that" and the AI knows what you mean. - **Voice works too.** Every tool listed here works identically via voice in the mobile app. Just say what you need. ## Known Limitations - **Requires a compatible MCP client.** Claude Desktop is the primary supported client. The MCP server follows the standard protocol. - **Uploading images/files now works via MCP.** Use `upload_document` with inline base64 (small files) or the `get_document_upload_url` → PUT → `upload_document` flow (any size). In claude.ai chat, dropping in a photo and saying "save this to my Medical folder" works **when code execution is enabled** — the assistant uploads the attached file for you. Live, on-device *camera* scanning still happens in the mobile app. - **Rate limits apply.** MCP tool calls consume the same credits as in-app chat. Your subscription tier determines available credits. - **Real-time sync is not instant.** If you scan something on your phone, it may take a few seconds before MCP tools see the new item. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 28 | 2026-07-28 | Spreadsheet → inventory import: `propose_import_mapping` reads the columns (remembering a layout you have approved before) and `create_items_bulk` creates the items as one operation you can undo in one go | | 29 | 2026-08-10 | Text documents are editable: `update_text_document` replaces a note/`.txt`/`.csv`/`.tsv`, with `undo_text_update` / `redo_text_update` stepping the history — a spreadsheet undo restores the previous file exactly. Read the editable text with `get_document({include_source: true})` | | 30 | 2026-08-11 | `update_markdown_document`, `undo_markdown_update` and `redo_markdown_update` are retired — markdown is a text document like any other, so `update_text_document` / `undo_text_update` / `redo_text_update` serve it too. The generic tool gained section updates (`section_heading` / `append`) so nothing was lost | | 27 | 2026-07-28 | Spreadsheets: `read_document_rows` pages through a stored `.csv`/`.tsv`/`.xlsx` (one sheet at a time for a workbook, naming the others), and `create_office_document` is now `create_data_file` — it also makes `.csv` | | 26 | 2026-07-27 | Word-style Undo/Redo — `undo_markdown_update` steps BACK one change (repeat to keep going), `redo_markdown_update` steps forward. A new edit discards anything ahead | | 23 | 2026-07-26 | Added `undo_markdown_update` — document edits are snapshotted and can be reverted with "undo that" | | 22 | 2026-07-18 | Added Tool Permissions section (`list_tool_permissions` / `update_tool_permission`) — per-tool Auto / Ask / Blocked policy, "Always Allow" on approval prompts | | 14 | 2026-07-05 | Rewrote Sharing for in-app live sharing + groups (`share_with_email`, `share_with_group`, group lifecycle, `revoke_share_grant`, `list_shared_with_me`, …); added Connected Services section (`add/list/update/remove_mcp_server`) (v0.13.2) | | 13 | 2026-06-26 | Added `list_mounted_contents` — resolve mounted shares into live data + provenance for inline display (AMB-377) | | 12 | 2026-06-26 | Added `mount_shared_resource` / `unmount_shared_resource` / `list_mounts` — add shared content into your own library (AMB-376) | | 11 | 2026-06-25 | Added `list_skills` / `get_skill` — first-party SKILL.md skills, readable by everyone (AMB-350) | | 10 | 2026-06-07 | Terminology: undo surfaces say "the web interface" not "admin console" | | 1 | 2026-03-01 | Initial guide — 28 tools across 6 categories | | 2 | 2026-05-27 | Complete rewrite — all 93 user-facing tools across 17 categories (AMB-188) | | 3 | 2026-05-28 | Added the MCP server URL (`https://mcp.ambientchat.ai`); reverted title to v1 to keep the seed idempotent | | 4 | 2026-05-29 | Added `get_document_upload_url`; `upload_document` now accepts base64 / signed-URL bytes so MCP clients can upload images into folders (AMB-281) | | 5 | 2026-05-28 | Added `list_conversations` (browse Q&A history with paging) — AMB-104 MCP promotion | | 6 | 2026-05-29 | Added `get_save_preferences` / `update_save_preferences` (sticky save folder) — AMB-104 MCP promotion | | 7 | 2026-05-29 | Added `list_interests` / `add_interest` / `remove_interest` (How I Roll tags) — AMB-104 MCP promotion | | 8 | 2026-06-01 | `get_profile` / `update_profile` now read & write `bio` (folded in from the legacy profile field, which was removed) — AMB-104 | | 9 | 2026-06-01 | Added `get_scan_status` — query an upload/scan job by jobId (processing / complete / failed) — AMB-287 | --- ## Panel of Experts — Multi-AI Answers URL: https://dont-panic.ambientchat.ai/article/panel-of-experts-multi-ai-answers Updated: 2026-08-13T22:15:12.589Z # Panel of Experts — Multi-AI Answers ambientChat can bring more than one AI model in on the same question. There are two ways to do it: 1. **Ask for a second opinion, right in the conversation.** Say *"what does Gemini think?"* or *"get a second opinion from Opus 5"* and whichever model you're talking to fetches that other model's answer for you, inline. No toggle, no mode switch — just ask. 2. **Turn on Panel of Experts and run a real back-and-forth.** Ask a question, then deliberately switch to a different model and put the *same* question to it — the new model reads the earlier answer and is told to engage with it (extend it, disagree with it, add what's missing), not just repeat it. Switch again for a third take, and you've built a multi-turn discussion in one thread. Both work the same way from **coding tools connected over MCP** — Claude Code, Claude Desktop, and others. Stuck reviewing a tricky code segment, or want a second read on a design doc before you commit to it? Ask your coding assistant to get a second opinion from a different model — the same `query_expert` tool handles it, without you leaving your editor. One thing worth being precise about: this isn't about pitting AI *vendors* against each other. It can be — OpenAI vs. Anthropic vs. Google — but it's just as often two models from the *same* vendor: a fast, cheap model against that vendor's most capable one, to see whether the extra cost actually buys a better answer. ## What It Does **Ask for a second opinion** uses a tool called `query_expert`. Your current model calls out to a different model, gets its answer, and hands it to you — labeled "Second opinion — \" — or compares it against its own answer if you ask it to. One question, one other model, inline, no mode to turn on. This is available in ambientChat's own chat (iOS and web) and from any MCP client you've connected, including coding tools. **Panel of Experts** (the toggle) is different: it changes what happens when you deliberately switch your *active* model mid-conversation. The newly-selected model is told it's joining a panel discussion — the earlier answers are still visible in the thread, each one labeled with the model that wrote it — and it's instructed to reference them by name and take a position, rather than silently agreeing or ignoring them. Nothing here fans out automatically; you're still driving one model at a time. Panel mode just makes each new model aware of, and responsive to, what came before. Both are genuinely useful for questions where you want more than one AI's take, or where seeing two models push back on each other beats seeing them agree. ## How to Use It ### iOS App #### Turning Panel Mode On 1. Open the **Chat** tab 2. In the toolbar above the text field, tap the small circular **mode toggle** (a 👥 people icon when Panel is on, a thinker icon when it's off — this is a separate control from the model selector) 3. A toast confirms the mode you switched to and spells out the procedure 4. Tapping it again switches back to **Fresh Perspectives** (independent answers, the default) #### Putting a Question to the Panel 1. With Panel of Experts on, ask your question with whichever model is currently selected 2. Read its answer 3. Tap the **model name** at the top of chat and pick a different model — from another vendor, or a different tier from the same one 4. Leave the text field **empty** and tap **Send** — with nothing typed, it turns into a **↻** icon that resubmits your last question to the newly-selected model 5. The new model sees the full thread, including the prior model's answer (labeled with its name), and responds as a panelist — building on it, disagreeing with it, or adding a missing angle 6. Switch models and tap **↻** again for a third opinion, and so on #### Fresh Perspectives (Panel Mode Off) This is the default. Switching models mid-conversation still carries your context over, but each model answers independently — it isn't told the other models exist, and it won't reference or argue with their answers. There's no **↻** repeat shortcut in this mode; to get another model's take on the same question, switch models and retype (or copy/paste) the question yourself. ### Web Same mechanic, in the browser: 1. Open the **Chat** page 2. Toggle **🎤 Panel** on near the composer (hover it for a tooltip that spells out the procedure) 3. Ask your question, then switch models (top-right model button) and press **↻** to put the same question to the next expert — it builds on or challenges the last answer, like panelists riffing off each other 4. Panel mode keeps the **full** conversation history instead of trimming older turns, so credit use climbs faster the longer the discussion runs — the UI flags this while it's on ### Via Chat (ask for a second opinion — no mode needed) This is the fastest door in, on either platform, and it works whether Panel mode is on or off. Whichever model you're talking to can pull in a one-off answer from a different model on its own, without you switching your active model or leaving the conversation. Just ask naturally: - *"What does Gemini think about this?"* - *"Get a second opinion from Opus 5."* - *"Ask Perplexity to verify this."* Your current model calls the other model, gets its answer back, and either hands it to you directly or compares it against its own take if you ask it to. This is one question routed to one other model inline — not a fan-out, and not the same as switching your active model in Panel mode. ### Via MCP (Claude Code, Claude Desktop, and other AI agents) The same **`query_expert`** tool behind "ask for a second opinion" is available to any MCP client you've connected to ambientChat — including **Claude Code**: - Pass a `model` parameter with any currently-visible model ID (the tool description lists the available models and their capabilities) - The tool automatically includes your full ambientChat context with each query This is useful mid-work, not just for ambientChat questions. Reviewing a design document and want a second read before committing to it? Stuck on a code segment that isn't behaving? Ask Claude Code to get a second opinion from a different model — *"ask Opus 5 to review this function for edge cases"* or *"get Gemini's take on this design doc"* — and it calls `query_expert` without you leaving your editor. Example from Claude Desktop: *"Ask Gemini what's the current market value for a 2023 MacBook Pro M3."* — the primary model calls `query_expert` to route to Gemini, and if the answer needs real-time pricing, the expert pulls it in via Perplexity-backed web search. For the full tool reference, see [MCP Tools — Complete Reference](20-mcp-tools.md). ## Tips & Tricks - **Use Panel mode for high-stakes questions.** Making a big purchase decision? Getting health-related advice? Two models genuinely arguing with each other surfaces things one model alone would miss. - **Compare tiers, not just vendors.** Switching between a fast, cheap model and a Premium one — from the *same* vendor — tells you whether the extra cost buys a meaningfully better answer to this specific question. - **For a quick sanity check, skip Panel mode entirely.** Just ask your current model to get a second opinion from a specific model — faster than switching your active model when you only want one outside take, not a running debate. - **The ↻ button only appears in Panel mode.** If you don't see it turn into a repeat icon when you clear the text field, check the mode toggle — you're in Fresh Perspectives. - **In a coding tool, use it to pressure-test decisions before you commit to them.** A second opinion on a design doc or a gnarly bug is often worth more before you've written the code than after. - **Switch back to Fresh Perspectives for casual questions.** Panel mode keeps the full conversation history on every turn, which adds up. Save it for when you actually want the panel dynamic, and use single-model chat for "What's expiring this week?" and other routine queries. ## Options | Setting | What It Does | Default | |---------|-------------|---------| | Panel of Experts | Toggles whether the currently-selected model is prompted to read and engage with prior models' answers, and whether full conversation history is retained (vs. trimmed) | Off | ## Known Limitations - **No automatic fan-out.** Panel mode never sends your question to more than one model at once — you drive each turn by switching models and re-asking. If you want three answers, that's three deliberate steps. - **No side-by-side comparison view.** Answers land one at a time as separate turns in the same thread, in the order you asked for them — not as cards you can scroll across. - **Higher token usage, driven by history, not parallel calls.** Panel mode never trims older turns (later models need to see exactly what earlier ones said), so the cost per question grows as the conversation gets longer — it isn't a flat multiplier like "3× a single query." - **The ↻ repeat shortcut is Panel-mode-only.** In Fresh Perspectives mode you have to switch models and resend the question yourself. - **No automatic consensus or "best answer" selection.** The app never picks a winner among the models you've asked. It's up to you to judge which answer (or combination) is most useful. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 4 | 2026-07-23 | Restructured around the two real ways in — conversational "ask for a second opinion" (`query_expert`, no mode needed) vs. the Panel of Experts toggle's switch-model-and-↻ mechanic — and led with them instead of a defensive "here's what it's not." Corrected "back-and-forth between AI vendors" to "between models" (same-vendor, different-tier comparisons are just as valid). Added the MCP/coding-tool use case: Claude Code (and other MCP clients) can call `query_expert` mid-work to get a second model's read on a design doc or a stuck code segment. | | 3 | 2026-07-23 | Corrected core mechanic: Panel of Experts is sequential (switch model → ↻ re-ask), not a simultaneous multi-model fan-out with side-by-side cards. Rewrote What It Does, How to Use It, Tips, Options, and Known Limitations to match; documented the mode toggle's actual location (toolbar circle icon, not inside the Model Selector) and the separate "ask for a second opinion" (`query_expert`) path available in ambientChat's own chat, not just via Claude Desktop. | | 2 | 2026-06-07 | Added Web section — Panel mode in the web interface | | 1 | 2026-03-01 | Initial guide | --- ## Privacy & Your Data URL: https://dont-panic.ambientchat.ai/article/privacy-your-data Updated: 2026-08-13T22:15:12.399Z # Privacy & Your Data The short version: your data is yours, it stays yours, and nobody else gets to rummage through it. The long version follows, because privacy deserves more than a slogan. ## What It Does ambientChat takes a fundamentally simple position on privacy: the data you put into the app belongs to you, is accessible only to you, and exists to serve you. There's no advertising model, no data marketplace, and no shadowy third party getting a copy of your grocery receipts. Your inventory, documents, chat history, and location data are stored in a secure cloud account protected by Firebase Authentication and Firestore security rules. These rules enforce that each user can only read and write their own data — not just as a policy, but as a technical constraint enforced at the database level. Even if someone managed to guess your document IDs, the database itself would refuse to hand over the data. It's like having a bank vault that checks your ID at the molecular level. When you talk to the AI, your context (inventory, location, conversation history) is sent to whichever AI provider you've selected — OpenAI, Google Gemini, or Anthropic Claude — to generate a response. This is necessary for the AI to be useful, but the data is sent per-request and is subject to each provider's data handling policies. You control which AI provider you use and what context is shared. ## Location Precision When the AI helps you with something location-aware — identifying a monument in a photo, answering "where did I leave my keys?", searching the web for nearby places — it uses your location. **You decide how precise that location is**, separately for each kind of AI call: - **📍 Exact GPS** (default) — coordinates like 40.4168°N 3.7038°W plus city and country. Best accuracy; the AI can identify a specific landmark, recommend the closest restaurant, or distinguish two similar places. Trade-off: your precise coordinates leave your phone and reach the AI provider. - **🏙️ City** — city + country (e.g. "Madrid, Spain"). Good balance for most queries — enough for "what monument is this?" without precise coordinates. - **🌍 Country** — country only (e.g. "Spain"). Minimal signal; some location-dependent answers will be less accurate. - **🚫 Off** — no location data sent. Maximum privacy; the AI works blind. The three independent settings: | Setting | When it's used | |---|---| | **Photos (scan)** | When the AI looks at a photo or document you scanned | | **Chat** | When the AI answers a question referencing your inventory, documents, or context | | **Web search** | When the AI calls a web search provider on your behalf | ### Adjusting your precision - **iOS**: Account → Privacy → Location precision. Tap any row, pick from the four options. - **Web**: Settings → Location precision card. Same three rows. - **Just ask**: tell the AI "Send less location info when you search the web" or "Use my exact GPS for photo scanning." It can adjust the settings on your behalf and will surface a notification with an undo whenever it does. ### Defaults New accounts start at **Exact GPS** for all three call types — maximum AI utility out of the box. Dial back any time. If the AI changes a setting on your behalf (because the next query would benefit), you'll see a notification with an Undo button. ## How to Manage It — Ask the AI The fastest way to review or change any privacy setting is to **ask the AI in chat**: - *"Guide me through the privacy controls for location."* → The AI reads your current location-precision settings and offers to change them. - *"What can I control about my privacy?"* → The AI lists every privacy-related setting along with what it does. - *"Send less location info when scanning."* → The AI changes your scan-precision setting on the spot (with a notification + undo). - *"Who has access to my data?"* → The AI reads your third-party context-sharing settings. - *"Hide adult beacons."* → The AI updates your beacon-category notification preferences. This works in **regular chat and in voice/Conversation Mode** — you don't need to leave the conversation to manage settings. The AI uses MCP tools to read your current state and apply changes, and surfaces every change as a notification with an Undo button so nothing happens behind your back. ### Settings the AI can manage for you | Setting | What it controls | Default | |---|---|---| | **Location precision** (scan / chat / web search — independent) | What the AI sends about your location — exact GPS, city, country, or off | Exact GPS | | **Voice preferences** | TTS voice name, playback speed, auto-speak | Sage, 1.0×, off | | **Beacon notification categories** | Which beacon categories (retail, hospitality, adult, etc.) trigger notifications | All on | | **Context sharing** | Whether brand/partner apps (Claude Desktop, McCormick, Amazon) can read curated context | All off | | **Profile** | Display name, nickname, profile photo, home and work addresses | Empty | ### The GUI is still there if you prefer it Every setting has a screen too — useful if you want to scan the full list visually. - **iOS**: Tap your profile icon → Settings → choose the relevant section (Privacy, Voice Settings, Application Behavior, Context Sharing, Profile) - **Web**: `/settings` — all settings live on one long scrollable page with anchor links ### Exporting your data Independent of the privacy settings above, you can download everything ambientChat knows about you. See the [Data Export & Import](17-data-export.md) guide for details. **In chat:** *"Export my data."* ### Deleting your account Ask the AI: *"Delete my account."* The AI runs the pre-flight check, summarizes what will be removed, and creates a pending confirmation that you confirm explicitly. There is no "undo" for account deletion — export your data first if you might want it later. ### MCP Tools Reference These privacy and settings tools are available via Claude Desktop and other MCP clients: - **`get_privacy_preferences`** / **`update_privacy_preferences`** — Location precision per AI call type - **`get_context_sharing`** / **`update_context_sharing`** — Third-party context sharing toggles - **`get_notification_preferences`** / **`update_notification_preferences`** — Beacon category notifications - **`get_account_deletion_precheck`** — Pre-flight check before deletion - **`request_account_deletion`** — Request deletion (creates a 5-minute confirmation) - **`export_user_data`** — Export all your data before deletion For the full tool reference, see [MCP Tools — Complete Reference](20-mcp-tools.md). ## Tips & Tricks - **Just ask the AI.** Anything below — "what's my voice speed?", "who can see my inventory?", "stop the AI from using my exact GPS" — is a one-sentence request away. Voice users especially: you should never have to look at a screen to manage these. - **The AI may adjust ambient settings on its own** (with notify + undo). For example, when scanning a monument it may temporarily upgrade your location precision to exact GPS so the identification is accurate. You'll see a notification with an Undo button after the response. Nothing happens silently. - **Per-AI-call independence.** "Location precision" isn't one switch — it's three: scan, chat, and web search are independent. You can be precise for landmark identification and coarse for everything else. - **Export before delete.** Account deletion is a one-way door — download your data first if you might want it later. ## What Data Is Collected Here's a transparent breakdown: | Data Type | Stored Where | Who Can Access | |-----------|-------------|----------------| | Inventory items | Firebase (your account) | Only you | | Documents (receipts, manuals, etc.) | Firebase (your account) | Only you | | Chat history | Firebase (your account) | Only you | | Location trails (if enabled) | Firebase (your account) | Only you | | Beacon visit history | Firebase (your account) | Only you | | AI provider interactions | Sent per-request to selected provider | You + AI provider (per their policies) | | Usage metrics | Aggregate analytics | anonymized, not personally identifiable | | Account info (email, auth) | Firebase Authentication | Firebase infrastructure | For the full, named list of every outside service that may process your data — what each one does and where it's based — see our [**Subprocessors**](https://app.ambientchat.ai/subprocessors) page. ## What Is NOT Collected - Your data is **not sold** to third parties. Ever. - There is **no ad targeting** based on your inventory or location. - Your specific items, documents, and conversations are **not used to train AI models** by ambientChat. (Individual AI providers have their own training data policies — review them if this matters to you.) - **No third party gets your data by default.** Context sharing is strictly opt-in. ## Known Limitations - **AI providers receive your context per-request.** When you ask a question, the selected AI model (OpenAI, Gemini, or Claude) receives the context needed to answer. This is how AI works — it needs your data to help you. Each provider has its own data retention and training policies, which are outside ambientChat's control. - **Aggregate analytics are collected for service improvement.** Things like "how many users scanned a barcode today" or "average response time for chat queries." These are anonymized and don't identify you personally, but they do exist. - **Account deletion is irreversible.** Once deleted, your data cannot be recovered. There is no 30-day grace period, no recycle bin, no "are you really sure?" email three weeks later. It's gone. - **Firebase security rules are the enforcement layer.** Privacy isn't just a promise — it's enforced by database rules that physically prevent cross-user data access. But like any system, it depends on correct configuration. Security rules are regularly reviewed and tested. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 1 | 2026-03-01 | Initial guide | | 2 | 2026-05-19 | Rewrote "How to Use It" → "Ask the AI" tool-first framing. Replaced stale screen breadcrumbs that referenced non-existent paths. Added the Settings table reflecting the actual MCP-controllable settings post-AMB-176 / AMB-224. Removed the "AI Provider = Gemini" default claim (that's no longer accurate — the user picks per conversation). | | 3 | 2026-06-07 | Terminology: settings screen labeled "Web" not "Admin web" (the web interface) | | 4 | 2026-07-19 | Added a link to the public Subprocessors page (the named list of service providers that may process your data). | --- ## Data Export & Import URL: https://dont-panic.ambientchat.ai/article/data-export-import Updated: 2026-08-13T22:15:12.278Z # Data Export & Import Your data, your rules. Export everything you've ever added to ambientChat — inventory, documents, conversations, preferences, the lot — as a portable archive you can keep, inspect, or bring to another platform. It's your digital life in a ZIP file. ## What It Does Data Export creates a downloadable archive of your entire ambientChat account. Everything goes in: inventory items, documents (receipts, manuals, warranties), conversation history, folder structures, preferences, and settings. You get it all in one tidy package, because your data belongs to you and you should be able to walk away with it at any time. Two formats are available: - **JSON** — A machine-readable archive that can be imported back into ambientChat. This is the format you want for backups and portability. It preserves every field, every relationship, every document ID. - **CSV** — A spreadsheet-friendly export for humans who want to browse their data in Excel, Google Sheets, or Numbers. Great for reviewing what you've got, but it's read-only — you can't import CSV back into the app. Data Import does the reverse: take a previously exported JSON archive and restore it into your account. You can choose to overwrite existing data or skip items that already exist. Handy for restoring from a backup, migrating between accounts, or recovering from that time you accidentally deleted everything. (Not that you would. But just in case.) ## Print or Export a Single Item or Document Beyond the whole-account archive, you can print or export **one** thing at a time — an inventory item or a document — straight from its detail view. Perfect for printing an item's "passport" for insurance, sharing a manual, or saving a single receipt. - **Print** produces an attractive, branded page (AirPrint on iOS, your browser's print dialog on the web). AI-estimated values are flagged in red, just like in the app, so you always know what's a guess. - **Export** saves a file in the format you choose: - **Items** — PDF (a nicely laid-out sheet) or JSON (the raw data). - **Documents** — PDF, the original Markdown (for text notes), the original file (for scans and receipts), or JSON. ### How to use it - **iOS** — Open any item or document and tap **Print** or **Export** in the action bar. Export shows a quick format picker; Print opens the system print dialog. - **Web** — Open an item or document and click **Print** or **Export**. Print opens the rendered page in a new tab (use your browser's print button); Export opens the file to save. - **Voice or chat** — Just say *"print my coffee maker"* or *"print the Sony manual"* and the print dialog opens by itself with the rendered page — on iOS that's AirPrint (if you've printed before, it remembers your printer), on the web it's your browser's print flow. No taps, no hunting for buttons — designed so it works eyes-free with VoiceOver. Asking to *"export …"* instead hands you a download link. (In external AI apps connected to ambientChat — Claude, ChatGPT — printing can't be triggered remotely, so you get the PDF link to open and print yourself.) - **Shared with you** — Items and documents others have shared with you can be printed and exported too (read-only) — handy for printing a manual a friend shared. ### Print or Export Several at Once Select multiple items or documents (tap **Select**, then pick the ones you want), and the **Print** and **Export** actions appear right alongside Delete and Move: - **Print** lays the whole selection into one tidy report — perfect for a printed inventory list (great for insurance) or a stack of documents. - **Export** saves the selection as a **PDF report**, a **CSV** spreadsheet, or **JSON**. CSV is ideal for opening your selection in Excel, Numbers, or Google Sheets. On iOS the Print/Export buttons sit in the selection toolbar; on the web they're in the selection bar at the top of the list. You can also just ask in chat: *"export my expiring items as a CSV."* **Don't want to hand-pick?** There's an **Export** (download) button in the list header too — it exports *everything currently shown*, so open a folder (or apply a filter) and export the whole thing in one tap. In chat you can name a folder directly: *"export my Kitchen folder as a PDF."* ## Save, Print or Export an AI Answer Your conversations are context too. Every AI answer — in a live chat and in your saved **Q&A** — carries its own little toolbar so you can keep the good ones: - **Copy** the answer to the clipboard. - **Save** it as a document in your context (it lands in **Documents** as Markdown), so a useful answer becomes a permanent, searchable part of your AI's knowledge. - **Share** it by email. - **Print** a clean, branded page of the question and answer (AirPrint on iOS, your browser's print dialog on the web). - **Export** it as **PDF**, **Markdown**, or **JSON**. On iOS the icons sit under each answer bubble (and under each saved Q&A); on the web they appear when you hover the answer. Print and Export of a *live* answer become available the moment it's saved to your Q&A history (a second or two after it finishes). You can also just ask: *"save that answer to my documents"* or *"export that as a PDF."* ## How to Use It ### iOS App #### Exporting Your Data 1. Go to **Account** (tap your profile icon) 2. Scroll to **Data Export/Import** 3. Tap **Export My Data** 4. Choose your format: - **JSON** for a full backup you can re-import later - **CSV** for a spreadsheet you can browse 5. The export starts as a background job — you'll see a progress indicator 6. When complete, you'll receive a notification with a **download link** 7. Tap the link to download your ZIP archive The export runs server-side, so you can close the app and come back later. It won't lose your place. #### Importing Your Data 1. Go to **Account** > **Data Export/Import** 2. Tap **Import Data** 3. Select your previously exported ZIP file 4. Choose a merge strategy: - **Overwrite** — existing items are updated with the imported data - **Skip Existing** — items that already exist in your account are left unchanged; only new items are added 5. Tap **Start Import** 6. The import processes in the background and you'll be notified when it's done ### Web From the web interface at `app.ambientchat.ai`: 1. Open **Settings** 2. Find the **Export My Data** section 3. Tick **Include images** if you want your photos in the archive 4. Click **Export** — a progress bar tracks the job, and a **download** link appears when it finishes Importing isn't available in the web interface yet — use the iOS app or MCP for that. ### Via Claude Desktop (MCP) If you've connected ambientChat to Claude Desktop, you can export and import using MCP tools: **Exporting:** 1. Use the **`export_user_data`** tool, optionally specifying `format: "json"` or `format: "csv"` 2. This starts an async export job and returns a job ID 3. Use **`get_export_status`** with the job ID to check progress 4. When the status shows "completed," you'll get a download URL in the response **Importing:** 1. Use **`get_import_upload_url`** to get a secure upload URL 2. Upload your ZIP archive to that URL via PUT request 3. Use **`import_user_data`** with the returned `storagePath` to start the import 4. Optionally set `mergeStrategy: "skip_existing"` to protect existing data, or `remapIds: true` for cross-account imports For the full tool reference, see [MCP Tools — Complete Reference](20-mcp-tools.md). Example Claude Desktop prompts: - *"Export all my ambientChat data as JSON."* - *"Check the status of my export job."* - *"Import my backup archive into ambientChat."* ## Tips & Tricks - **Export regularly as a backup.** Set a mental reminder (or ask your AI to remind you) to export every month or so. If anything ever goes wrong, you'll have a recent snapshot to restore from. Think of it as flossing for your data hygiene. - **JSON format preserves everything for re-import.** If you might ever want to restore your data, always export as JSON. CSV is lovely for browsing but it's a one-way trip — you can look but you can't go back. - **CSV exports open beautifully in spreadsheet apps.** Want to see how much you've spent at Costco this year? Export as CSV, open in Sheets, and sort to your heart's content. Pivot tables optional but encouraged. ## Options | Setting | What It Does | Default | |---------|-------------|---------| | Export Format | JSON (importable) or CSV (spreadsheet) | JSON | | Merge Strategy (Import) | Overwrite existing items or skip them | Overwrite | | Remap IDs (Import) | Generate new IDs instead of preserving originals (for cross-account imports) | Off | ## Known Limitations - **Large accounts may take a minute to export.** If you've cataloged thousands of items and uploaded hundreds of documents, the export job needs time to gather and package everything. The background job handles this gracefully — you just need a bit of patience. - **CSV is read-only.** You cannot import a CSV file back into ambientChat. It's an export-only format designed for human consumption. For round-trip portability, use JSON. - **Import replaces or skips — no per-field merge.** When importing with the "overwrite" strategy, the entire item is replaced with the imported version. There's no way to merge individual fields (e.g., keep the current price but update the notes). If you need that level of control, edit items individually after import. - **Cross-account imports require ID remapping.** If you're importing data from one account into a different account, use the `remapIds` option. Otherwise, document ID collisions may cause unexpected behavior. - **Export download links expire.** The download URL provided after export has a time limit. If you wait too long, you'll need to run the export again. Download promptly, like milk from the doorstep. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 6 | 2026-06-24 | Save / Print / Export AI answers from chat & the Q&A tab (AMB-343) | | 2 | 2026-06-07 | Added Web section — exporting your data from the web interface (Settings) | | 1 | 2026-03-01 | Initial guide | --- ## Context Allocation — Tuning Your AI URL: https://dont-panic.ambientchat.ai/article/context-allocation-tuning-your-ai Updated: 2026-08-13T22:15:12.086Z # Context Allocation — Tuning Your AI Your AI has a limited attention span — context allocation lets you decide what it pays attention to. Think of it as a mixing board for your AI's brain, where you control which instruments get turned up. ## What It Does Every time you send a message to your AI assistant, the app assembles a bundle of context to send along with it: your inventory items, your recent location visits, your past conversations, and more. But AI models have a fixed **context window** — a maximum amount of information they can consider at once. Context allocation lets you control how that limited space is divided among different data types. By adjusting the sliders, you tell the AI what to prioritize. Crank up **Inventory Items** and the AI gets more detail about your stuff — every brand, every expiry date, every note. Boost **Recent Visits** and the AI becomes more aware of where you've been and when. Increase **Questions Asked** and it remembers more of your conversation history. The total budget is fixed. Giving more space to one category means less space for another. It's a zero-sum game, but a friendly one — the defaults work well for most people, and you only need to adjust if you're asking specific types of questions that need deeper context. ## How to Use It ### iOS App 1. Go to **Account** (tap your profile icon or the Account tab) 2. Scroll to **Context Allocation** 3. You'll see sliders for each context category: - **Recent Visits** — location and beacon visit history - **Questions Asked** — your past conversation history - **Inventory Items** — your cataloged belongings and their details 4. Drag any slider to adjust its allocation 5. The total across all categories remains constant — increasing one automatically decreases others proportionally 6. Changes take effect on your **next message** to the AI #### When to Adjust **Before an inventory deep-dive:** Boost **Inventory Items** before asking detailed questions like "What electronics do I have worth over $500?" or "List every spice in my pantry with expiry dates." More inventory context means the AI can include more items and more detail per item. **Before a location-focused session:** Boost **Recent Visits** before asking "Where did I go this week?" or "How long was I at the museum?" The AI gets a richer location timeline to work with. **Before referencing past conversations:** Boost **Questions Asked** before asking "What did we talk about regarding my camera collection?" or "Remind me what recipe you suggested last week." More conversation history means better recall of past exchanges. **When things feel off:** If the AI seems to be ignoring your inventory when answering questions, or forgetting recent conversations, check your allocation — one category might be starved. ### Web Context-allocation tuning is an iOS feature today — the web interface doesn't expose these sliders yet. The budgets still apply to web chat; you just adjust them in the app. ### Via Chat You can ask the AI about your current allocation: - *"What are my context allocation settings?"* - *"How much context is going to my inventory right now?"* Note: you can't change allocation via chat — it's a settings screen feature. ## Tips & Tricks - **The defaults are genuinely good.** The balanced allocation works well for general-purpose questions that touch on inventory, location, and history. Only adjust if you're doing something specific and finding the AI's responses shallow in a particular area. - **Reset to defaults if responses feel off.** If you boosted inventory to the max for a stock-taking session and forgot to reset, your location and conversation context will be thin until you rebalance. The reset button is your friend. - **Think of it as temporary tuning, not permanent configuration.** Adjust before a specific session, then reset when you're done. It's a mixing board, not a set-it-and-forget-it thermostat. ## Options | Setting | What It Does | Default | |---------|-------------|---------| | Recent Visits | Allocation for location and beacon visit history | Balanced (equal share) | | Questions Asked | Allocation for past conversation history | Balanced (equal share) | | Inventory Items | Allocation for item details and metadata | Balanced (equal share) | | Reset to Defaults | Restores the balanced allocation | N/A | ## Known Limitations - **Total allocation is fixed.** You cannot increase the overall context budget — only redistribute it. The total is determined by the AI model's context window and your subscription tier. More of one thing always means less of another. - **Changes take effect on the next message.** Adjusting sliders mid-conversation doesn't retroactively change the AI's understanding — it affects what context is sent with your next question. - **You can't allocate by specific category of item.** The Inventory slider controls all inventory context equally. You can't say "more about food, less about electronics" — the AI decides what's most relevant based on your question. - **No per-conversation overrides.** Allocation is a global setting. If you want different allocations for different types of questions, you'll need to adjust the sliders each time. ## What Happens When Your Context Won't Fit Different models have different-sized windows. Claude Haiku and most non-flagship models have a 200,000-token window; Claude Opus has 1,000,000. If the context the app wants to attach to your question — plus the conversation history, your attached documents, and the tools the AI has on hand — would overflow the chosen model's window, the app trims it for you. The trim happens in this order: 1. Decorative document images (matched documents whose images aren't needed to answer) 2. Attached PDF binaries (when only the extracted text is needed) 3. Long document content (kept enough to be useful, dropped the rest) 4. Older messages from earlier in the conversation 5. Background-matched documents entirely (the document still exists; the AI just won't see its full text this turn) Your own attached files for the current turn — anything you paperclip or photograph in this message — are **never** dropped. Those are your explicit ask. When the app trims, it logs it for you and the AI tries to answer anyway. If you suspect you got a thinner answer than usual, the smoothest fix is to switch to a larger-context model (Claude Opus, GPT‑4.1) for that turn or ask a more focused question. If everything is dropped and the prompt still doesn't fit, you'll see a friendly message asking you to switch models or remove some attachments — never a raw `prompt is too long: 204053 tokens > 200000 maximum` error string. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 3 | 2026-06-07 | Added Web note — allocation tuning is iOS-only | | 2 | 2026-05-12 | Documented the model-aware context budgets and graceful overflow behavior (AMB-150). | | 1 | 2026-03-01 | Initial guide | --- ## Location Trails — Where You've Been URL: https://dont-panic.ambientchat.ai/article/location-trails-where-you-ve-been Updated: 2026-08-13T22:15:11.952Z # Location Trails — Where You've Been A visual breadcrumb trail of everywhere you've wandered. Unlike actual breadcrumbs, these don't get eaten by birds or swept up by janitors. ## What It Does Location Trails records your movements on an interactive map, drawing a path of where you've been throughout the day. It's background location tracking with a purpose: when you're done exploring a city, visiting a museum, or running errands, you can look back at your route, see where you stopped, and relive the journey — minus the sore feet. The app identifies **visits** — places where you stopped for a meaningful amount of time — and names them using Google Places data. That 45-minute stop becomes "Whole Foods Market" instead of "coordinates 37.7749, -122.4194." Routes between stops are snapped to actual roads and sidewalks, so your path looks like a real journey rather than a drunken line drawn by a GPS that's having a bad day. Your trail data enriches AI conversations too. Ask "Where did I go yesterday?" or "How long was I at the museum?" and the AI can answer from your actual location history. Context that follows you everywhere — literally. ## How to Use It ### iOS App #### Viewing Your Trail 1. Tap the **Location** tab at the bottom of the screen 2. You'll see an interactive map with your trail drawn as a colored path 3. **Blue dots** mark your route between stops 4. **Markers** indicate places where you stopped, labeled with place names and timestamps 5. Pinch to zoom, drag to pan — standard map interactions 6. Tap any **visit marker** to see details: place name, arrival time, departure time, and duration #### Enabling Background Location Location Trails only records when background tracking is turned on: 1. Go to **Account** > **Background Location Trails** 2. Toggle the switch to **On** 3. The app will request location permissions if it hasn't already 4. Choose **"Always Allow"** when prompted — this lets the app track in the background When enabled, a small location indicator appears in your status bar to remind you that tracking is active. This is iOS being transparent, not the app being nosy. #### Disabling Tracking 1. Go to **Account** > **Background Location Trails** 2. Toggle the switch to **Off** 3. Background tracking stops immediately 4. Your existing trail history is preserved — turning off tracking doesn't delete past data ### Web Location trails are an iOS feature — there's no trail map in the web interface. You can still ask about where you've been in chat. ### Via Chat Your AI assistant can query your location history: - *"Where did I go today?"* - *"How long was I at the grocery store?"* - *"Show me everywhere I went last Saturday."* - *"What time did I leave the office?"* - *"Where did I spend the most time this week?"* The AI draws on your trail data to give time-stamped, place-named answers. ## Tips & Tricks - **Enable trails before a trip to get the full route.** Turn on background tracking before you leave the house, and you'll have a complete record of your day's journey when you get back. Great for vacation logs, business travel, or proving to your spouse that you did, in fact, go to the gym. - **The map shows timestamps on visit markers.** Tap any stop to see exactly when you arrived and left. Useful for expense reports, time tracking, or settling debates about who was late. - **Trails pair beautifully with beacon data.** If you have beacons at indoor locations (a museum, your office), the trail shows your outdoor route while beacons fill in the indoor context. Together, they give a remarkably complete picture of your day. ## Options | Setting | What It Does | Default | |---------|-------------|---------| | Background Location Trails | Master toggle for location recording | Off | | Location Permission | iOS permission level (Always / While Using / Never) | Not set (prompted on first enable) | ## Known Limitations - **Requires "Always Allow" location permission.** Background tracking needs the highest permission level. "While Using App" only tracks when ambientChat is in the foreground, which rather defeats the purpose of background tracking. - **Battery impact when active.** Background location uses GPS, which consumes battery. The app uses efficient monitoring (significant location changes, not continuous GPS), but you'll still notice some additional drain. If your phone is dying by 3 PM, consider turning trails off when you don't need them. - **GPS accuracy depends on environment.** Open sky: excellent. Dense urban canyon: decent. Inside a concrete bunker: don't hold your breath. Indoor locations may show approximate positions or no movement at all. - **Route snapping requires road data.** Paths are snapped to known roads and walkways. If you went hiking on an unmapped trail, the path may look approximate or skip sections. - **Visit detection has a time threshold.** Very short stops (under a few minutes) may not register as visits. The system is looking for meaningful stops, not traffic lights. - **Location data stays in your secure account.** Your trails are stored in your personal cloud storage, protected by the same Firebase security rules as the rest of your data. No one else can see where you've been. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 2 | 2026-06-07 | Added Web note — trails are iOS-only; no trail map in the web interface | | 1 | 2026-03-01 | Initial guide | --- ## Beacons — Location-Aware Inventory URL: https://dont-panic.ambientchat.ai/article/beacons-location-aware-inventory Updated: 2026-08-13T22:15:11.765Z # Beacons — Location-Aware Inventory Small Bluetooth transmitters, big context upgrades. Beacons tell your AI where you are so it can give you answers that actually make sense for the Zone you’re standing in. ## What It Does Beacons are small, battery-powered Bluetooth transmitters that you place at fixed locations — a kitchen shelf, a museum exhibit, a garage workbench, your medicine cabinet. They use the iBeacon protocol to broadcast a unique identity made up of three values: a **UUID** (identifies the beacon family), a **Major** number (identifies a group or zone), and a **Minor** number (identifies the specific beacon). Together, these three values are as unique as a fingerprint, except they're useful. When your phone detects a beacon, ambientChat adds that location context to your AI conversations automatically. Ask "What's expiring soon?" while standing near your kitchen beacon, and the AI knows to prioritize pantry items. Ask "What's on this shelf?" near a museum beacon, and the AI can tell you about the exhibit. The context flows invisibly — you don't need to tell the AI where you are, because the beacons already did. The app maintains a **Beacon Registry** where you can see every beacon your phone has detected, along with signal strength, estimated distance, and whether you've given it a name. Think of it as a census of the invisible Bluetooth population in your vicinity. ## How to Use It ### iOS App #### Viewing Detected Beacons 1. Open the **Location** tab at the bottom of the screen 2. You'll see a list of beacons your phone is currently detecting or has recently seen 3. Each entry shows the beacon's **name** (if registered), **UUID**, **Major/Minor** values, **signal strength** (RSSI), and **estimated distance** 4. Beacons are sorted by proximity — the closest ones appear first #### Registering a Beacon When you see an unregistered beacon in the list: 1. Tap the beacon entry 2. Give it a **name** that describes its location (e.g., "Kitchen Counter", "Front Door", "Workshop Bench") 3. Configure the **alert mode**: - **Sound** — plays a notification sound when you enter the beacon's range - **Silent** — detects the beacon quietly, no audio interruption 4. Set a **snooze duration** if you don't want repeated alerts (e.g., "Don't alert me again for 30 minutes") 5. Tap **Save** Once registered, the beacon's name appears in your chat context whenever you're nearby. The AI stops saying "you're near beacon Minor 7832" and starts saying "you're in the kitchen." #### Managing Beacon Settings 1. Go to **Account** > **Beacon Settings** 2. Here you can: - Toggle beacon monitoring on or off - View all registered beacons - Edit beacon names and alert preferences - Remove beacons you no longer use #### Searching the Global Registry ambientChat maintains a global registry of known beacon identifiers — beacons deployed in museums, retail stores, and other public venues. 1. From the beacon list, tap **Search Registry** 2. Enter a UUID, Major, or Minor value, or search by location name 3. If a match is found, you can import the beacon's name and metadata into your personal registry ### Via Chat Your AI assistant is beacon-aware. Try these prompts: - *"Where am I right now?"* — The AI tells you which beacons are in range - *"What's near the kitchen beacon?"* — Asks about inventory associated with that location - *"When was the last time I was in the garage?"* — Checks your beacon visit history - *"What beacons have I seen today?"* — Lists your recent beacon encounters ### Via Claude Desktop (MCP) When connected via MCP, the **`get_user_context`** tool automatically includes nearby beacon information in its response. You can pass a `focus` parameter with `type: "beacon"` and the beacon's ID to get context specific to that beacon's location. ### Teaching the App Your Zones (Walk & Teach) After you've placed your beacons, teach the app how your space actually sounds: 1. Open **Settings → Bluetooth Walk & Teach** 2. You'll see every zone (live beacon) deployed at your location, each with a calibration chip — *calibrated*, *needs work*, or *never verified* 3. Tap **Start a teaching walk**, then simply walk your space, tapping the zone you're in each time you arrive 4. Watch the live ticker — each "app agreed in 4.2s ✓" is the app confirming it followed you 5. Tap **Finish walk** to see your report card: overall zone accuracy, average switch lag, and a bar per zone A three-minute walk is plenty. Zones the app struggled with get the lowest bars — usually that means the beacon is hidden inside a cabinet, too close to a neighboring zone, or has a dying battery. Move it, then walk just those zones again. Your walks are also recorded (privately, to your own account) so detection can be tuned for your specific space over time. ## Tips & Tricks - **Place beacons at fixed locations, not on things that move.** A beacon on your kitchen shelf is reliable context. A beacon in your pocket is just confusing. - **Do a teaching walk after moving furniture or beacons.** Radio shadows shift when the physical world does. Walk & Teach takes three minutes and tells you exactly which zones need attention. - **The app detects beacons even when backgrounded.** iOS region monitoring works in the background, so you'll get beacon context even if ambientChat isn't in the foreground. The app wakes briefly to note the beacon, then goes back to sleep. Very efficient, very polite. - **Beacon names flow directly into chat context.** The more descriptive your beacon names, the better the AI's location-aware answers. "Kitchen Pantry Shelf 2" beats "Beacon 1" every time. ## Options | Setting | What It Does | Default | |---------|-------------|---------| | Beacon Monitoring | Master toggle for all beacon detection | On | | Alert Mode | Sound or silent notification when entering a beacon zone | Silent | | Snooze Duration | How long to suppress repeated alerts for the same beacon | 15 minutes | | Beacon Name | Friendly name displayed in beacon list and chat context | Unnamed (shows UUID/Major/Minor) | ## Known Limitations - **Bluetooth must be enabled.** If Bluetooth is off, no beacons are detected. The app cannot force Bluetooth on — that's between you and your Settings app. - **Detection range varies wildly.** Depending on walls, furniture, humidity, and the general mood of radio waves, a beacon might be detected from 1 meter or 30 meters away. Don't expect Zone-level precision in an open-plan loft. - **Battery-powered beacons need replacement.** Most beacons run on coin cell batteries that last 1-3 years. When a beacon stops appearing, check the battery before blaming the app. - **iOS limits simultaneous beacon monitoring.** The system can monitor up to 20 beacon regions at once. If you've deployed an army of beacons, some may not be tracked simultaneously. - **Signal strength fluctuates.** RSSI values bounce around due to interference, body position, and whether Mercury is in retrograde. Distance estimates are approximate — treat them as "near," "medium," or "far" rather than precise measurements. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 1 | 2026-03-01 | Initial guide | | 2 | 2026-08-12 | Added Walk & Teach — teaching walks, calibration chips, report card | --- ## Digital Product Passports URL: https://dont-panic.ambientchat.ai/article/digital-product-passports Updated: 2026-08-13T22:15:11.648Z # Digital Product Passports Every product has a story — where it came from, what's in it, how it was made, and whether it's trying to destroy the planet. Digital Product Passports are how products tell that story, and ambientChat is how you listen. ## What It Does A Digital Product Passport (DPP) is a standardized digital identity attached to a physical product. Think of it as a product's autobiography — packed with structured data about ingredients, allergens, nutritional facts, sustainability ratings, supply chain provenance, manufacturing details, and more. The kind of information that would take you twenty minutes to research online, except it comes straight from the manufacturer and shows up in your inventory automatically. DPPs are delivered through QR codes on packaging, NFC tags on products, or linked through barcodes. When you scan a product that has a DPP, ambientChat reads the passport data and enriches your inventory item with everything the manufacturer has shared. Your simple "box of cereal" entry suddenly knows its exact ingredients list, its eco-score, where the wheat was sourced, and how the packaging can be recycled. Not all products have DPPs yet — the technology is still rolling out across industries. But when they're available, the data is remarkably rich. And it's getting more common every month, especially in food, cosmetics, and electronics. ## How to Use It ### iOS App #### Scanning a Product with a DPP 1. Tap the **Scan** tab 2. Point your camera at the **QR code** on the product's packaging 3. If the QR code links to a Digital Product Passport, ambientChat detects this automatically 4. The product is added to your inventory with all DPP data included — ingredients, allergens, sustainability info, provenance, and more 5. A standard barcode scan also checks for DPP data linked to that product's identifier For NFC-enabled products: 1. Hold your phone near the **NFC tag** on the product 2. Your device reads the tag and ambientChat processes the DPP data 3. Same result — the product appears in your inventory enriched with passport data #### Viewing DPP Data on an Item 1. Tap any item in your **Inventory** that was scanned from a DPP-enabled product 2. On the item detail screen, you'll see additional sections beyond the standard fields: - **Ingredients** — Full ingredient list from the manufacturer - **Allergens** — Highlighted allergen information - **Nutrition Facts** — Per-serving and per-100g nutritional data - **Eco-Score** — Environmental impact rating (A through E) - **Sustainability** — Packaging recyclability, carbon footprint, certifications - **Provenance** — Country of origin, manufacturing location, supply chain details 3. These fields are read-only — they come directly from the manufacturer's DPP data #### Understanding Eco-Scores DPP-enabled products often include an environmental impact score: | Grade | Color | What It Means | |-------|-------|---------------| | **A** | Dark green | Minimal environmental impact. The planet approves. | | **B** | Light green | Low impact. Solid choice. | | **C** | Yellow | Moderate impact. Room for improvement. | | **D** | Orange | Significant impact. Consider alternatives. | | **E** | Red | High environmental impact. | Eco-scores are calculated by the manufacturer or third-party sustainability organizations, not by ambientChat. The app displays them as provided. ### Web Digital Product Passports aren't surfaced in the web interface yet — view a product's passport in the iOS app, or ask about it in chat. ### Via Chat Your AI assistant can answer questions using DPP data just like any other context: - *"What are the ingredients in my cereal?"* - *"Does anything in my pantry contain tree nuts?"* - *"Which of my products have the best eco-scores?"* - *"Where was my olive oil produced?"* - *"Show me the sustainability info for my recent purchases."* - *"Are there any allergens in items I bought this week?"* The AI searches your inventory and uses the DPP data attached to items to give informed, specific answers. It knows the difference between "contains traces of peanuts" and "made in a facility that processes peanuts" — because the DPP data is that detailed. ## Tips & Tricks - **Look for QR codes on product packaging.** More products carry DPP QR codes than you might expect, especially in the European market where regulations are driving adoption. Check the back or bottom of food packaging, cosmetics, and electronics boxes. - **DPP data quality depends on the manufacturer.** Some brands provide exhaustive detail — every ingredient, every certification, full supply chain transparency. Others include the minimum required fields. ambientChat shows you everything the passport contains, but it can only display what was put there. - **Use DPP data for dietary and allergen tracking.** If you or someone in your household has food allergies, the structured allergen data from DPPs is far more reliable than trying to read tiny print on packaging. Ask the AI "does anything in my inventory contain gluten?" and it checks the actual manufacturer-provided allergen data. ## Options | Setting | What It Does | Default | |---------|-------------|---------| | DPP Auto-Enrichment | Whether scanned products are automatically enriched with DPP data when available | On | | Eco-Score Display | Whether eco-scores are shown on inventory items | On | ## Known Limitations - **Not all products have DPPs yet.** Digital Product Passports are an emerging standard. Adoption is growing quickly — especially in Europe, where EU regulations are mandating them for certain product categories — but many products still don't have one. When no DPP is available, the item is still added to your inventory with whatever the AI can determine from the scan. - **Data completeness varies by brand.** A DPP is only as detailed as the manufacturer makes it. Some passports are comprehensive; others are sparse. You might see full provenance and sustainability data for one product and only basic ingredients for another from a different brand. - **Some DPP fields may be empty.** Even on products with DPPs, not every field is always populated. The eco-score might be missing, or the supply chain details might be limited to country of origin without further breakdown. - **DPP data is manufacturer-provided, not independently verified by ambientChat.** The app displays what the manufacturer has published in their product passport. ambientChat does not independently verify ingredient lists, allergen claims, or sustainability scores. - **NFC scanning requires compatible hardware.** Not all devices support NFC reading for DPP tags. Most recent iPhones do, but older models may not. QR code scanning works on all devices with a camera. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 2 | 2026-06-07 | Added Web note — DPPs aren't surfaced in the web interface yet | | 1 | 2026-03-01 | Initial guide | --- ## Search — Finding Anything URL: https://dont-panic.ambientchat.ai/article/search-finding-anything Updated: 2026-08-13T22:15:11.497Z # Search — Finding Anything You've cataloged hundreds of items, scanned dozens of receipts, and had countless conversations with your AI. Now you need to find that one specific thing. Good news: search in ambientChat understands what you mean, not just what you type. ## What It Does Search in ambientChat is powered by AI embeddings — a fancy way of saying it understands the meaning behind your words, not just the exact letters. When you search for "red kitchen knife," it finds your "Victorinox 8-inch Chef's Knife (Fibrox Pro, Red Handle)" even though you didn't type any of those exact words. It understands that a chef's knife is a kitchen knife, and that Fibrox Pro Red means the handle is red. This semantic search works across three domains: - **Inventory** — Find items by describing them naturally. "Coffee stuff," "things I bought at Target," "electronics worth over $100." - **Documents** — Search your receipts, manuals, warranties, and other uploaded documents by what they contain, not just their filenames. - **Chat History** — Find past conversations by topic. "What did we discuss about meal planning?" surfaces the relevant exchange even if those exact words weren't used. Traditional keyword search is also available in the search bars — type a word and it matches against item names, brands, and descriptions. But the real magic is in semantic search, which happens automatically when you ask the AI in chat. ## How to Use It ### iOS App #### Searching Your Inventory 1. Tap the **Context** tab, then the **Inventory** sub-tab 2. Tap the **search bar** at the top of the screen 3. Type your search terms — results filter in real time as you type 4. This is keyword-based search: it matches against item names, brands, descriptions, and categories 5. Combine with **category chips** below the search bar to narrow results further For semantic search (meaning-based), use chat instead — see the "Via Chat" section below. #### Searching Your Documents 1. Tap the **Context** tab, then the **Documents** sub-tab 2. Tap the **search bar** at the top 3. Type to filter documents by name or content 4. Results include receipts, manuals, warranties, and any other uploaded documents #### Searching Chat History Your conversation history is searchable through the AI itself. Ask in chat: - *"What did we talk about last week?"* - *"Find our conversation about home insurance."* - *"When did I ask you about my camera collection?"* The AI searches your past exchanges and surfaces relevant conversations. ### Web Each tab in the web interface has its own search box: 1. Open **My AI Context** and pick **Inventory**, **Documents**, or **Q&A** 2. Click the search icon and type — results filter as you type 3. **Inventory** matches name, brand, category, and description; **Documents** matches title, type, store, and tags; **Q&A** matches your question text This is a fast text filter over what's loaded in the tab. For meaning-based search ("things for the party"), ask in chat. ### Via Chat Chat is where semantic search truly shines. Instead of guessing the right keywords, just describe what you want in plain language: **Inventory searches:** - *"Find my coffee-related items."* - *"What kitchen tools do I have?"* - *"Show me everything from Costco."* - *"Do I have any AA batteries?"* - *"What's the most expensive thing in my inventory?"* **Document searches:** - *"Find receipts from January."* - *"Show me the warranty for my vacuum cleaner."* - *"What does my TV manual say about wall mounting?"* - *"Find any documents mentioning insurance."* **Conversation searches:** - *"What did we discuss about meal planning?"* - *"Remind me what you suggested for organizing my garage."* - *"Find the conversation where I asked about my medication interactions."* The AI interprets your intent, searches the relevant domain (or all of them), and returns what you're looking for. No Boolean operators, no exact-match frustration, no "did you mean?" loops. ### Via Claude Desktop (MCP) If you've connected ambientChat.ai to Claude Desktop via MCP, these search tools are available: - **`search_items`** — Semantic search across inventory. Finds items by meaning, not just keywords ("things in my garage", "snacks for the party") - **`search_documents`** — Keyword search across document titles, summaries, and content - **`search_documents_semantic`** — AI-powered semantic search across documents - **`search_markdown_content`** — Semantic + keyword search across your written markdown documents - **`recall_history`** — Search past conversation history by topic. Filter by channel (voice/text/mcp), platform, session, or date range - **`web_search`** — Search the web for current information when you need real-time data For the full tool reference, see [MCP Tools — Complete Reference](20-mcp-tools.md). Example prompts in Claude Desktop: - *"Search my ambientChat inventory for anything chocolate-related."* - *"Find my ambientChat receipts from the last month."* - *"What have I discussed with ambientChat about home organization?"* ## Tips & Tricks - **Be descriptive, not precise.** Search understands meaning, so "red kitchen knife" works better than trying to remember the exact brand name. Describe the item the way you'd describe it to a friend, and let the AI figure out the match. - **Search works across all fields.** Inventory search checks item names, brands, descriptions, categories, locations, and notes. If you stored "garage shelf 3" in an item's location field, searching "garage" will find it. - **Use chat for complex queries.** The search bar in the Inventory tab does keyword matching. For anything nuanced — "what food do I have that goes with pasta?" or "electronics I bought more than a year ago" — ask the AI in chat. It combines semantic search with reasoning to give you exactly what you need. ## Options | Setting | What It Does | Default | |---------|-------------|---------| | Inventory Search Bar | Keyword search across item names, brands, and descriptions | Empty (show all) | | Document Search Bar | Keyword search across document names and content | Empty (show all) | | Category Filter | Narrow inventory results to a specific category | All categories | | MCP `query` parameter | Natural language search string for MCP tools | Required for search | | MCP `limit` parameter | Number of results to return (for `recall_history`) | 5 | ## Known Limitations - **Newly added items may not be immediately searchable.** When you scan or add an item, the system generates an AI embedding (a mathematical representation of the item's meaning) that powers semantic search. This takes a few seconds. If you search immediately after adding something and don't find it, wait a moment and try again. - **Keyword search is literal.** The search bars in the Inventory and Documents tabs do keyword matching, not semantic search. Searching for "knife" won't find "blade" or "cutting tool." For meaning-based search, ask the AI in chat. - **Very large inventories may return many results.** If you have hundreds of items and search for something broad like "food," you'll get a long list. Narrow your search with more specific terms or combine with category filters. - **Chat history search depends on conversation being saved.** Only conversations that were logged to your history are searchable. If a conversation was lost due to a connectivity issue, it won't appear in history searches. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 3 | 2026-06-07 | Added Web section — searching inventory/documents/Q&A in the web interface | | 2 | 2026-05-27 | Updated MCP tools section with current tool names + added web_search and markdown search (AMB-188) | | 1 | 2026-03-01 | Initial guide | --- ## Subscriptions & Usage URL: https://dont-panic.ambientchat.ai/article/subscriptions-usage Updated: 2026-08-13T22:15:11.328Z # Subscriptions & Usage The AI is brilliant, generous, and eager to help — but it does eat tokens. Here's how the economics work, and why you might want to feed it more. ## What It Does ambientChat uses a credit-based system tied to subscription tiers. Every time the AI processes a question, analyzes an image, or searches your inventory, it uses tokens — think of them as tiny units of computational effort. Your subscription tier determines how many tokens you get each month. **The tiers:** | Tier | What You Get | |------|-------------| | **Free** | A generous taste of what's possible. Enough tokens to explore the app, scan some items, and chat with the AI. Perfect for deciding if ambientChat is for you. | | **Standard** | A solid monthly token allocation for regular use. Scan your groceries, track your inventory, ask questions daily. | | **Premium** | More tokens, access to more capable AI models, and priority processing. For users who rely on the app as a daily tool. | | **Max** | The full experience. Maximum token allocation, all models, all features. For power users who want to catalog everything and ask about it constantly. | Tokens reset at the beginning of each billing cycle. Use them or lose them — they don't roll over. **Everything the AI does counts.** Chat questions are the obvious one, but background work spends from the same allowance: photo and receipt scans, image descriptions, document summaries, generated item images and thumbnails, web searches the AI runs on your behalf, narrations, second opinions from other AI models, and the semantic indexing that powers search. Each shows up as its own line in Billing History, so you can always see exactly where your credits went. ## How to Use It ### iOS App #### Checking Your Current Plan 1. Go to **Account** (tap your profile icon or the Account tab) 2. Tap **My Subscription** 3. You'll see your current tier, renewal date, and token usage for this period #### Viewing the Usage Ring The **usage ring** is a visual indicator that appears in the app showing how much of your monthly token budget you've consumed. Think of it as a fuel gauge for your AI: - **Mostly empty** — you've barely used your allocation, chat away freely - **Half full** — you're on pace, nothing to worry about - **Nearly full** — you're approaching your limit, be more selective with questions - **Full** — you've hit your ceiling for this month The usage ring updates after each AI interaction, so you always know where you stand. #### Comparing Plans 1. Go to **Account** 2. Tap **Compare Plans** 3. A comparison screen shows all tiers side by side with token allocations, available models, and features 4. Pick the tier that matches how you use the app #### Upgrading Your Subscription 1. Go to **Account** > **My Subscription** 2. Tap **Upgrade** or navigate to **Compare Plans** 3. Select the tier you want 4. Complete the purchase through **Apple In-App Purchase** 5. Your new token allocation is available immediately 6. Your billing cycle resets to start from the upgrade date #### Monitoring Usage in Chat While chatting, a small **usage indicator** is visible showing token consumption. Each AI response updates this counter. Longer, more complex questions and responses use more tokens. More capable models generally consume tokens at a higher rate. ### Web #### Upgrading from the Web When you reach your AI allowance in web chat (or a chat-based scan), the reply is replaced by a **capacity card** showing when your credits refill. You don't have to wait: 1. Click **Continue now** on the capacity card 2. Pick a plan — each shows its price, monthly credits, and rate bonus, with your current usage above for context 3. Pay in the embedded checkout that opens in the same window (your card details go directly to Stripe; ambientChat never sees them) 4. Your credits unlock automatically and the question you were asking is answered without re-typing it Web subscriptions are billed by **Stripe**, not Apple. If your existing plan is managed through Apple, the web checkout will tell you to upgrade in the iOS app instead — whichever store sold the plan manages it. #### Managing Your Plan from the Web The **Settings → Subscription** card adapts to how you subscribed: - **Free tier**: an **Upgrade** button opens the same plan picker as the capacity card — pick a plan and pay without leaving Settings. - **Subscribed on the web (Stripe)**: a **Manage subscription** button opens Stripe's secure customer portal, where you can switch plans, update your card, download invoices, or cancel (you keep access until the period ends). The portal returns you to Settings when you're done. - **Subscribed on iOS (Apple)**: your plan is managed through Apple — change or cancel it in the iOS app under Settings → Subscriptions. ### Via Chat You can ask the AI about your usage: - *"How many tokens have I used this month?"* - *"Am I close to my limit?"* - *"What plan am I on?"* The AI has access to your subscription status and can give you a plain-language summary of where you stand. ## Billing History Billing History gives you an itemized breakdown of every AI request — like a phone bill for your AI usage. Each entry shows the date, what kind of request it was (chat, voice, scan, image), which model handled it, and how many credits it consumed. ### iOS App 1. Go to **Account** > **My Subscription** 2. Scroll down to the **Billing History** section 3. Tap **Load Billing History** to fetch your events 4. Use the **This Period** / **Previous** toggle to switch between billing periods 5. A running total of credits appears at the bottom ### Web 1. Go to **Settings** (gear icon) 2. Scroll down past the subscription summary card 3. The **Billing History** card shows events for the current period 4. Use the period selector to switch between current and previous periods ### Via Chat Ask the AI about your billing details: - *"Show me my billing history"* - *"What have I been charged for this month?"* - *"How many credits did my last scan use?"* The AI uses the `get_billing_events` tool to pull your itemized history and summarize it. ### Via Claude Desktop (MCP) Three tools are available in Claude Desktop: - **`get_subscription`** — Your subscription summary: tier, period start/end, credits used/remaining, exemption status - **`get_usage_state`** — Current usage and billing summary: tier, credits, streak, and exemption status - **`get_billing_events`** — Itemized billing events with optional `period` (current/previous), `limit`, and `offset` parameters For the full tool reference, see [MCP Tools — Complete Reference](20-mcp-tools.md). ## Tips & Tricks - **The free tier is genuinely useful for trying the app.** Don't feel pressured to upgrade immediately. Scan some items, ask some questions, see if the context-aware AI is actually valuable to you. If you find yourself hitting the limit regularly, that's a good sign you should upgrade — it means you're actually using it. - **Shorter, more specific questions use fewer tokens.** "What food expires this week?" is cheaper than "Tell me everything about all my food items and their expiry dates and what I should cook with each one." Both work, but the first is more token-efficient. - **Check your usage ring before a big session.** If you're about to scan a week's worth of groceries and then ask the AI to generate a meal plan, glance at your usage first. Nothing worse than running out of tokens mid-meal-plan. ## Options | Setting | What It Does | Default | |---------|-------------|---------| | Current Plan | Your active subscription tier | Free | | Usage Ring | Visual indicator of monthly token consumption | Always visible | | Auto-Renewal | Whether your subscription renews automatically | On (managed by Apple) | ## Known Limitations - **Tokens don't roll over.** Unused tokens from this month don't carry into next month. Your allocation resets fresh at the start of each billing cycle. - **Refunds are handled by Apple.** Since subscriptions are purchased through Apple In-App Purchase, refund requests must go through Apple's process, not through ambientChat directly. Visit the Apple App Store or `reportaproblem.apple.com`. - **Token usage is approximate in the UI.** The usage indicator gives you a good sense of where you stand, but exact token counts vary based on model, response length, and context size. Think of it as a reliable estimate, not a precise meter. - **Downgrading takes effect at renewal.** If you switch to a lower tier, you keep your current tier's benefits until the end of the billing period. The lower tier kicks in at the next renewal. - **Some models are tier-restricted.** Not every AI model is available on every plan. The model selector shows which models your current tier can access. Upgrading unlocks additional models. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 7 | 2026-07-13 | Web Settings subscription card now adapts by provider — Upgrade button (free), Stripe customer portal (web subscribers), Apple copy (iOS subscribers) | | 6 | 2026-07-13 | Added web upgrade flow — capacity card → plan picker → embedded Stripe checkout; web plans billed via Stripe, Apple plans stay managed in the iOS app | | 5 | 2026-07-10 | Added second opinions (query expert) and semantic search indexing to the list of billable background work | | 4 | 2026-07-10 | Clarified that background AI work (scans, image generation, summaries, web search, narration) draws from the same credit allowance as chat | | 3 | 2026-06-07 | Terminology: "Admin Web" → "Web" (the web interface) | | 2 | 2026-03-31 | Added Billing History section — itemized billing events on iOS, the web interface, chat, and Claude Desktop | | 1 | 2026-03-01 | Initial guide | --- ## AI Models — Choosing Your Expert URL: https://dont-panic.ambientchat.ai/article/ai-models-choosing-your-expert Updated: 2026-08-13T22:15:11.194Z # AI Models — Choosing Your Expert Not all AIs think alike. ambientChat connects you to models from multiple leading AI vendors and lets you switch between them at any time. It's like having a panel of experts on call — each one sees the same context about you, so switching doesn't mean starting over, it means getting a different perspective. ## What It Does The model selector lets you pick which AI answers your next question. Whichever model you choose gets the same context — your inventory, documents, recent conversation, location signals — so you can swap mid-conversation without repeating yourself. ### The vendors ambientChat conversation routes to models from the three frontier AI labs: - **OpenAI** — a broad, reliable all-rounder family. - **Anthropic** — known for nuanced reasoning and careful long-form analysis. - **Google** — strong multimodal (image + text) capabilities. Web search and source-grounded answers are handled by **Perplexity** under the hood — any of the three frontier models can call it as a tool whenever a question needs real-time web information. You don't have to pick Perplexity directly; the model you're talking to will fetch web results on its own when needed, and cite them in the answer. We keep the specific model versions up to date as vendors ship new ones, so this guide sticks to vendors and tiers rather than naming particular models — those change. ### The three tiers Models are grouped into three cost tiers. Picking the right tier usually matters more than picking the right vendor. | Tier | Cost | What it's for | |---|---|---| | **Everyday** | $ | Fast, low-cost models for the majority of daily questions — quick lookups, short summaries, light reasoning. Marked *Recommended* because most questions don't need more than this. | | **Thoughtful** | $$ | Mid-cost models for harder reasoning — comparing options, working through a decision, longer-form writing. | | **Premium** | $$$ | The most capable models each vendor offers — deep reasoning, complex analysis, web-grounded research. Costs the most per question. | ### What $×N means Next to each model you'll see a badge like **$×1**, **$×3** or **$×10**. It answers one question: *roughly how many times more does this model cost than the cheapest one on your list?* - **$×1** is the cheapest model available to you. Everything else is measured against it. - **$×3** costs about three times as much per question. - **$×10** costs about ten times as much. The tiers above tell you what a model is *for*; the multiplier tells you what it *costs*. They don't line up as neatly as you might expect — two models can share a tier and still differ by three times in price, which is exactly why the number is shown. A few things worth knowing: - **It's an approximation, deliberately.** We round to friendly steps (×1, ×2, ×3, ×5, ×10) rather than showing something like ×2.7. The point is the order of magnitude, not false precision. - **It's weighted towards what you send, not what you get back.** Most of the cost of an answer is the context that goes *in* — your documents, your inventory, the conversation so far — rather than the words that come back. The multiplier reflects that. - **It updates itself.** The number comes from our current price list, so when a vendor changes their prices the badge changes with them. Nothing is hardcoded. - **A missing badge means we don't have a published price** for that model yet — not that it's free. **Does a bigger number mean a better answer?** Not automatically. A Premium model is genuinely better at hard reasoning, but for a quick lookup it costs ten times as much to tell you the same thing. Match the model to the question, not to the price. ### The capability icons Each model row shows small icons telling you what that model can do: | Icon | Meaning | |---|---| | ⚡ **Quick reply** | Tuned for speed — answers fast. Shown on Everyday-tier models. | | 🧠 **Thinks aloud** | Shows its reasoning before answering, useful for hard problems. | | 👁️ **Sees images** | Can read images you attach or that come from your inventory photos. | | 📚 **Cites sources** | Returns citations to the sources it used — helpful when facts matter. | Not every icon appears on every model. The icons reflect what each model supports today; as models improve, icons can change. ### All paid access is equal **Every paid subscription can use every model on the list.** Subscription tiers control *how many tokens you can spend per month*, not which models you're allowed to pick. Premium-tier models simply cost more tokens per question, so your monthly allowance goes less far if you use them heavily. ## How to Use It The model selector is available in three places. Your selection is remembered per-device. ### iOS app 1. Open **Chat**. 2. Tap the current model name near the top of the screen. 3. A bottom sheet slides up showing tiers (Everyday / Thoughtful / Premium) with each model's capability icons. 4. Tap the model you want. The next message uses it. ### Web 1. Open the **Chat** page. 2. Click the model button in the top-right (shows the current model). 3. A dropdown lists the tiers and models with the same capability icons. 4. Click a model to switch; your choice is remembered on this device. ### MCP (Claude Desktop, OpenClaw, and other AI agents) When you ask ambientChat via MCP — for example from Claude Desktop — the MCP client is already running its own model (that's how you're talking to it). ambientChat's role in that case is to supply *context*, not to pick a model. So there's no separate model selector in MCP clients. You choose the model *inside* your MCP client (e.g., pick a Claude model in Claude Desktop); that client then pulls context from ambientChat via tools. ### Switching mid-conversation Switching models doesn't clear your conversation. All models read the same recent history, so you can start a question with a fast Everyday model, switch to a Thoughtful or Premium model to go deeper, and the new model picks up where the last one left off. ## Tips & Tricks - **Stay on Everyday until you need more.** Most questions — "is anything expiring this week?", "which beacon am I near?", "summarise that receipt" — don't need a Premium model. Save the expensive ones for the hard ones. - **Match the model to the job.** Use a 🧠 *Thinks aloud* model when you want it to reason through a decision. Use a 👁️ *Sees images* model when you're attaching photos or asking about photos on your items. Use a 📚 *Cites sources* model when accuracy of facts matters. - **Compare answers.** If a model's response feels off, switch vendors and ask again — different vendors genuinely reason differently. Same context, different framing. - **Watch your token usage, not your model list.** The usage indicator shows how much of your monthly budget you've spent. If it's climbing fast, drop to a cheaper tier for the routine questions. ## Options | Setting | What it does | Default | |---|---|---| | Selected model | The model used for your next message on this device. Changed via the model selector. | Anthropic, Everyday tier | | Persistence | Your choice is remembered per-device (web: browser local storage; iOS: device storage). | — | ## Known Limitations - **Model catalogue is curated.** We only expose models that pass our quality and cost checks. When vendors ship new models, they're added after vetting; older ones are retired. The list you see is always the current set. - **Not every model supports every capability.** A model without the 👁️ icon can't interpret images; a model without 📚 can't return citations. The icons tell you before you pick. - **Context windows vary.** Each model has a limit on how much history + context it can consider at once. Very long conversations may drop the oldest turns on models with smaller windows. Starting a fresh conversation resets this. - **Panel of Experts costs more credits.** Panel mode — switch models mid-conversation and re-ask so each one responds to the last, see the [Panel of Experts](19-panel-of-experts.md) guide — keeps the full conversation history instead of trimming it, so it consumes credits faster than single-model chat. - **Answers will differ between models.** This is the point, not a bug. If two models disagree, that's signal worth noticing. ## Version History | Version | Date | What Changed | |---|---|---| | 6 | 2026-07-23 | Corrected Panel of Experts limitation wording — sequential switch-and-re-ask, not "ask several models at once"; see [Panel of Experts](19-panel-of-experts.md) v3 | | 5 | 2026-06-08 | Corrected stale limitation: Panel of Experts is live (was "not live yet") | | 4 | 2026-06-07 | Terminology: web model-picker section retitled "Web" (the web interface) | | 3 | 2026-04-22 | Demoted Perplexity from the primary model selector. Conversation is now handled by the three frontier labs (OpenAI, Anthropic, Google); Perplexity is used under the hood for web-grounded answers and cited sources, invoked automatically as a tool by whichever primary model you pick. Cleaner product story, consistent capabilities across all primaries. | | 2 | 2026-04-19 | Rewrote to match current behavior: three-tier structure (Everyday / Thoughtful / Premium), capability icon legend, clarified that all paid subscriptions can use all models (token budget is the limit, not access), added web + MCP platforms, removed references to specific obsolete model names. | | 1 | 2026-03-01 | Initial guide | --- ## Voice — Speaking & Listening URL: https://dont-panic.ambientchat.ai/article/voice-speaking-listening Updated: 2026-08-13T22:15:11.015Z # Voice — Speaking & Listening Why type when you can talk? And why read when the AI can read to you? Your hands are busy holding groceries, stirring risotto, or just being lazy. We don't judge. ## What It Does Voice in ambientChat works in both directions. You can speak your questions instead of typing them, and the AI can read its answers aloud instead of making you squint at text. It turns your AI assistant into something closer to an actual conversation — one where the other party happens to know the entire contents of your pantry. **Voice Input** uses speech recognition to transcribe what you say into a message for the AI. You speak, it types, the AI answers. **Voice Output** uses text-to-speech to read the AI's responses aloud. The same voice, style, and speed you configure once is used everywhere the app speaks: chat auto-play, the speaker icon on individual chat messages, Voice Conversation mode, beacon-triggered Zone narration, and the voice preview in Settings. Change any of it in one place and it applies everywhere, immediately. **Voice Conversation** is a dedicated hands-free mode. Tap the mic in the Chat button row to open a full-screen overlay that listens, thinks, and speaks back continuously — a proper back-and-forth, no tapping required between turns. ## How to Use It ### iOS App #### Speaking to the AI (voice input) 1. Open the **Chat** tab 2. Tap the **microphone button** in the row of round buttons just above the message box — it sits between the panel-of-experts toggle and the model button, and it's there whether or not you've started typing 3. Wait for the **soft "ready" chime** — that's the mic going live. Speaking before the chime can clip the first word. 4. Speak your question clearly 5. The app transcribes and sends automatically; the AI answers You can speak naturally. *"What's expiring this week?"* works as well spoken as typed. The AI doesn't care about your accent — it's heard worse. #### Listening to the AI (voice output) Every AI message has a small **speaker icon** on it. Tap to hear the response. Tap again (on any message, or the same one) to stop playback — the app treats the speaker icon as a universal mute. While the audio is being generated, a **three-dot throbber** appears next to the speaker so you know something's coming during the brief OpenAI round-trip. With **Auto-Speak** on, every AI response plays automatically as it arrives. With it off, tap the speaker on any message you want to hear. In Voice Conversation mode, responses auto-play regardless of the Auto-Speak setting — that mode wouldn't be much of a conversation otherwise. #### Voice Settings **Account** → **Voice Settings**. You configure four things: - **Voice** — choose from six OpenAI voices: **Ash**, **Fable**, **Marin**, **Onyx**, **Sage**, **Verse**. Tapping a voice auditions it immediately so you hear what you're picking. - **Voice Style** — a free-text field for how the voice should sound. Examples: *"Speak warmly like a museum guide"*, *"Sound excited about recipes"*, *"Deep, calm, reassuring tone"*. Accents are hit-or-miss (the model tries, but won't always land a convincing one). After you tap out of the field, the app auto-auditions so you immediately hear the effect. - **Speed** — how fast the voice speaks, in seven discrete steps: **0.5×, 0.75×, 1×, 1.25×, 1.5×, 1.75×, 2×**. Tapping a chip auditions at the new rate so the change is audible right away. Unlike accents, speed is exact — OpenAI honours it deterministically. - **Auto-Speak** — toggle automatic playback of every AI response in the main Chat view. Settings apply across every place the app speaks. Change it once. #### Changing voice mid-conversation (without opening Settings) In Voice Conversation, just ask. Natural language works: - *"Switch to Onyx."* - *"Let's try Sage."* - *"Use a warmer voice."* - *"Can you speak at half speed?"* - *"Speed it up to 1.5."* The AI updates your saved settings and the next response uses the new voice / style / speed. The Settings screen reflects the change the next time you open it. ### Web Voice input and spoken replies are an iOS feature. The web interface chat is text-only — you type your questions and read the answers. ### Via Chat Voice input and text input produce identical results. The AI doesn't know or care whether you typed or spoke — it receives the same text either way. So every example prompt in every other guide in this knowledge base works with voice too. Just say it instead of typing it. Some particularly useful voice scenarios: - *"What's expiring this week?"* (while unpacking groceries) - *"What spices do I have that go with salmon?"* (while staring at salmon) - *"Read me the warranty details for my laptop."* (while on hold with tech support) - *"Add a note: I put the Christmas decorations in the garage attic."* (while climbing down a ladder) ### Via Claude Desktop (MCP) Voice preferences are readable and writable via MCP: - **`get_voice_preferences`** — Get your current voice, style, auto-speak, and speed settings - **`update_voice_preferences`** — Change voice, style, speed, or auto-speak toggle For the full tool reference, see [MCP Tools — Complete Reference](20-mcp-tools.md). ## Tips & Tricks - **Wait for the chime.** It's the honest "mic is hot" signal; speaking before it can clip your first word. - **Voice output is great for hands-free workflows.** Cooking, organizing the garage, or sorting through boxes — any time your hands are busy but your ears are free. - **Tap speaker to stop.** Tap any speaker icon to silence whatever's playing. No need to wait out a long response politely. - **Change your mind about a voice?** Tap the speaker on an older message — the app regenerates audio in your current voice, style, and speed on the fly. Previously-spoken messages keep their old recording until you ask for a fresh one. - **Use Speed instead of Voice Style for rate.** Typing "speak quickly" in Voice Style is ignored by the model — the model treats that as tonal guidance, not a rate dimension. The Speed chips are the reliable way to make the voice faster or slower. ## Options | Setting | What It Does | Values | Default | |---------|-------------|--------|---------| | Voice | Which OpenAI voice reads responses | Ash · Fable · Marin · Onyx · Sage · Verse | Sage | | Voice Style | Free-text instructions shaping delivery | Any short phrase | (empty) | | Speed | Playback rate multiplier | 0.5× · 0.75× · 1× · 1.25× · 1.5× · 1.75× · 2× | 1× | | Auto-Speak | Play AI responses automatically in Chat view | On / Off | Off | ## Known Limitations - **Voice input requires an internet connection.** Speech recognition happens on Apple's servers, so it won't work in airplane mode. - **No wake word.** You have to tap the mic to start — the app doesn't listen until you tell it to. Intentional. - **Style accents are imperfect.** The model takes a shot at what you ask for ("Irish accent", "Boston accent") but doesn't always land a convincing one. Accents are probabilistic; speed is exact. - **Tapping speaker on an older message may regenerate audio** if you changed your voice, style, or speed since it was first spoken. Expect a brief delay on first tap; subsequent taps of the same message use the cached recording. - **Voice input transcription accuracy varies.** Product names, brand names, and technical terms may not transcribe perfectly. Glance at the transcribed text before it sends if accuracy matters. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 5 | 2026-08-08 | The mic moved into the row of round buttons above the message box, between the panel-of-experts toggle and the model button. It no longer disappears when you start typing. | | 4 | 2026-06-07 | Added Web note — voice is iOS-only; the web interface chat is text-only | | 3 | 2026-04-21 | Added Speed control (seven-chip grid, deterministic rate via OpenAI TTS). Listening-ready chime now fires when the mic is actually hot, not at state transition. Three-dot throbber next to chat speaker icon during TTS generation. Mid-conversation voice/style/speed changes via natural language ("switch to Onyx", "speak at half speed") now apply instantly and are reflected in Voice Settings. Universal mute: tap any speaker icon to stop all audio. Per-message speaker icons added to the Voice Conversation overlay. | | 2 | 2026-04-19 | Unified voice, voice style, and audio routing across chat speaker icon, auto-play, beacon narration, and the preview in Voice Settings. Voice and style changes now propagate instantly. Corrected voice list (six server voices; no more per-device voices or a speech-rate slider). | | 1 | 2026-03-01 | Initial guide | --- ## Expiring Items — Never Waste Food Again URL: https://dont-panic.ambientchat.ai/article/expiring-items-never-waste-food-again Updated: 2026-08-13T22:15:10.856Z # Expiring Items — Never Waste Food Again That yogurt in the back of the fridge? The ibuprofen you bought during the last pandemic scare? Your AI knows when they expire — and it will tell you before the smell does. ## What It Does ambientChat tracks expiry dates on food, medicine, supplements, and anything else with a shelf life. When you scan a product, the AI reads visible expiry dates from packaging and records them. When no date is visible, the AI estimates one based on what it knows about the product category (canned tuna gets more runway than fresh strawberries, for example). Items approaching their expiry dates get color-coded badges in your inventory, giving you a visual at-a-glance system: - **Green** — plenty of time left, no need to worry - **Yellow** — expiring soon, consider using it this week - **Red** — expired or expiring today, time to investigate (sniff test optional but recommended) You can ask your AI assistant about expiring items at any time, and it will search your inventory for anything that needs attention. No more discovering fossilized hummus at the back of the shelf. ## How to Use It ### iOS App #### Seeing Expiry Badges 1. Tap the **Context** tab, then the **Inventory** sub-tab 2. Items with expiry dates show a color-coded badge next to their name 3. The badge displays the expiry date and how many days remain 4. Tap any item to see its full detail view, including the exact expiry date and whether it was scanned from the label or estimated by AI #### Setting or Correcting Expiry Dates 1. Tap an item to open its detail view 2. Tap **Edit** (pencil icon) 3. Find the **Expiry Date** field 4. Set or correct the date using the date picker 5. Tap **Save** This is especially useful when the AI's estimate is off — you know your peanut butter better than any neural network does. #### Scanning with Visible Expiry Dates For the best results when scanning: 1. Tap the **Scan** tab 2. Point your camera at the product so the expiry date is visible in the frame 3. The AI reads the date directly from the packaging when it can see one 4. Products without a visible date get an AI-estimated expiry based on product type ### Web The web interface shows the same inventory as the iOS app — expiry tracking included. #### The "Expiring Soon" Banner 1. Open **My AI Context → Inventory** 2. When you have items approaching their expiry dates, a yellow **"N items expiring soon"** banner appears above your inventory grid 3. Each card in the banner shows the item's thumbnail, its name, and a color-coded label for how soon it expires (e.g. *"Expires in 3d"*) 4. **Click any card to jump straight to that item's detail** — the same as tapping it on iOS 5. Dismiss the banner with the **×** if you'd rather not see it; it comes back next time something is expiring Individual inventory cards carry the same color-coded expiry label too, so you can spot what's aging at a glance even after dismissing the banner. ### Via Chat Your AI assistant is ready to be your expiry watchdog. Try these: - *"What's expiring this week?"* - *"Show me expired items."* - *"What food do I need to use up soon?"* - *"Is my almond milk still good?"* - *"What medicine is expiring in the next 30 days?"* - *"What should I cook tonight based on what's expiring soonest?"* The AI searches your inventory and ranks items by urgency, so the most critical items surface first. ### Via Claude Desktop (MCP) If you've connected ambientChat.ai to Claude Desktop via MCP: - **`list_expiring_items`** — Returns items expiring within a specified window, soonest first. Pass a `days` parameter to set the lookahead (e.g., `days: 7` for the next week, `days: 30` for the next month). Default is 14 days. Set `include_expired: true` to also see items already past their date. Pass `limit` to change the page size (default 200); the response sets `truncated: true` when more items match than were returned, and because results are ordered soonest-first, anything omitted expires later than everything you got back. - **`search_items`** — Semantic search with queries like "expired food" or "medicine expiring soon" For the full tool reference, see [MCP Tools — Complete Reference](20-mcp-tools.md). Example prompt in Claude Desktop: *"Check my ambientChat for anything expiring in the next 5 days."* ## Tips & Tricks - **Scan products with the expiry date facing the camera.** The AI is good, but it's not psychic — if it can see the date printed on the package, it records the real one instead of guessing. Best-before dates, use-by dates, and expiration dates are all recognized. - **Check your expiry list weekly.** A quick "What's expiring this week?" in chat takes five seconds and could save you from wasting food (or worse, eating something that's turned). - **AI estimates are educated guesses, not guarantees.** When the AI assigns an expiry date, it's working from general knowledge about product categories. Fresh produce estimates tend to be conservative. Canned goods get generous timelines. Your nose remains the ultimate authority. ## Options | Setting | What It Does | Default | |---------|-------------|---------| | Expiry Date | Per-item field, set manually or detected by AI during scanning | Auto-detected or AI-estimated | | Category Filter | Filter inventory to show only food, medicine, or other categories with expiry dates | All categories | | MCP `days` parameter | How far ahead to look for expiring items (via `list_expiring_items`) | 14 days | | MCP `limit` parameter | Max items returned per call; results are ordered soonest-expiring first | 200 | ## Known Limitations - **AI estimates may be inaccurate.** The AI doesn't know when you actually bought the product or how it's been stored. A carton of milk estimated at 10 days might actually have 3 days if it sat in a hot car for an hour. Use estimates as a starting point, not a guarantee. - **No push notifications for expiry yet.** The app won't proactively ping you when something is about to expire. You need to check manually — either by opening the app or asking in chat. Push-based expiry alerts are on the roadmap. - **Expiry tracking works best for packaged goods.** Loose produce, bulk bin items, and homemade leftovers don't come with dates. You can always add an expiry date manually after scanning. - **Date format recognition varies.** The AI handles most common formats (MM/DD/YYYY, DD/MM/YYYY, "Best Before Mar 2026"), but unusual or hand-written dates may not be read correctly. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 3 | 2026-08-08 | Expiry checks now scan the whole inventory instead of the first 500 items, so nothing is missed on large collections; documented the MCP `limit` parameter and the `truncated` flag (AMB-693) | | 2 | 2026-06-06 | Added Web section — expiring-soon banner with clickable, thumbnailed cards (AMB-290) | | 1 | 2026-03-01 | Initial guide | --- ## Folders — Organizing Your Documents URL: https://dont-panic.ambientchat.ai/article/folders-organizing-your-documents Updated: 2026-08-13T22:15:10.699Z # Folders — Organizing Your Documents Because "that one document I saved somewhere" is not a filing system. ## What It Does Folders let you organize your documents into named collections, exactly like file folders on a computer — except these are searchable, the AI knows what's inside them, and they look considerably nicer than a manila envelope. Group your receipts together, keep warranties in their own folder, stash medical records separately, or create whatever structure makes sense for your life. You can nest folders inside other folders, move documents between them, and let the AI generate custom icons that give you a visual hint of what's inside. It's the kind of organization that feels satisfying without requiring a label maker. ### Document folders and inventory folders A folder knows what kind of thing it holds — documents, inventory items, or both. That's why the **Documents** tab and the **Inventory** tab show different folders: your "Receipts" folder holds documents, your "Music" folder holds items, and neither clutters up the other's view. Anywhere you pick a destination — moving things, filing a chat attachment, saving a generated image — you'll only be offered folders that can hold what you're filing. A new folder created from one of those pickers is made for that kind. If you deliberately put an item into a folder that only held documents (by moving it there, or by asking your AI to), **the folder simply widens to hold both** and starts appearing on both tabs. Nothing is refused, and nothing goes missing — a thing filed somewhere it can't be shown would be invisible, so the folder changes to match what you actually put in it. ## How to Use It ### The Default Folder Every account starts with **My Documents** as the root folder. This is home base — all documents land here unless you specify otherwise. You can create as many subfolders as you like inside it. ### Special Folders - **Don't Panic** — The help guides folder (the one you're reading right now). It's pinned to the top of your documents list so it's always easy to find. You can't accidentally delete or move it, which is exactly the kind of guardrail a help folder should have. - **Receipts** — A common default for uploaded purchase records. ### iOS App **Creating a folder:** 1. Open the **Documents** tab in My Things 2. Tap the **New Folder** button 3. Enter a name for your folder 4. The folder appears in your current location, ready to receive documents **Navigating folders:** - Tap a **folder card** to open it and see its contents - The **breadcrumb trail** at the top shows your current path (e.g., My Documents > Receipts > 2026) - Tap any breadcrumb to jump back to that level — no need to hit the back button repeatedly **Moving documents:** 1. Enter **selection mode** by long-pressing a document or tapping the selection icon 2. Tap to select the documents you want to move 3. Tap the **Move** action 4. Choose the destination folder 5. Documents are moved instantly **Managing a folder (rename, edit, delete):** 1. **Long-press a folder** to open its actions sheet 2. Choose **Rename** to fix a typo or rethink a name, **Edit** to change its details, or **Delete** to remove it 3. Deleting offers an **Undo** — if you tap it by mistake, the folder comes right back This works on both the **Inventory** and **Documents** tabs. Selecting a folder is also a route to **sharing** it — see the [Sharing guide](28-sharing.md) — and sharing a folder shares everything inside it, sub-folders included. ### Web **Creating a folder:** 1. Go to the **Documents** section 2. Click the **New Folder** button 3. Enter a folder name and confirm **Navigating:** - Click folder cards to drill down - Use the breadcrumb trail to navigate back up - The folder view shows document thumbnails and counts at a glance **Moving documents and items (drag-and-drop):** - Simply **drag a document or item card** and **drop it onto a folder card** to move it — or onto a **breadcrumb** to move it back up a level - This is the fastest way to organize in the web interface — grab, drag, done - Works the same on the Inventory and Documents views **Moving documents and items (folder button):** - Hover a card and click the small **folder icon** (next to the trash icon) - Choose the destination from the folder list — **Home** appears when you're inside a folder, to move things back to the top level **Moving in bulk:** - Click **Select**, tick the cards you want, then **Move to folder** — one confirmation moves them all (Inventory and Documents alike) **Managing a folder (rename, edit, delete):** - Open a folder's **menu** (the •••/gear control on the folder card) and choose **Rename**, **Edit**, or **Delete** - The same menu is a route to **sharing** the folder with a person or group — see the [Sharing guide](28-sharing.md) ### Via Chat Your AI assistant knows about your folder structure. Try: - *"What folders do I have?"* - *"Show me documents in my Kitchen folder."* - *"How many receipts are in my Receipts folder?"* - *"What's in the Warranties folder?"* ### Via Claude Desktop (MCP) If you're connected via MCP, the following tools are available: - **`list_views`** — List folders at a given level of the hierarchy - **`get_view`** — Get folder details and its contents - **`get_view_tree`** — See the entire folder hierarchy with item, document, and subfolder counts - **`get_view_members`** — Get items and documents in a folder - **`create_view`** — Create a new folder (idempotent — won't create duplicates) - **`update_view`** — Rename a folder, change description, sort order, or thumbnail mode - **`reorder_views`** — Batch update sort order for multiple folders - **`generate_view_icon`** — Generate an AI icon for a folder - **`add_items_to_view`** — Tag items with a folder (keeps prior memberships) - **`move_items_to_view`** — Move items to a destination folder - **`remove_items_from_view`** — Remove items from a folder For the full tool reference, see [MCP Tools — Complete Reference](20-mcp-tools.md). The AI navigates your folder structure automatically when answering questions about your documents. ## Folder Features ### Thumbnails & Icons Folders display a **collage of document thumbnails** so you can see at a glance what's inside — a folder full of receipts looks different from one full of product manuals. If a folder has fewer documents, it shows individual thumbnails instead of a collage. ### AI Folder Icons The system can generate a **custom AI icon** for your folder based on its name and contents. A folder called "Kitchen Appliances" might get a toaster icon, while "Travel Documents" might get a suitcase. These are generated automatically but can be regenerated if you'd prefer a different look. ### Document Counts Each folder card shows the **number of documents** it contains, so you can quickly gauge which folders are growing and which are sparse. Counts include documents in subfolders. ### Nested Folders Folders can contain subfolders for deeper organization. A structure like **Receipts > 2026 > March** is perfectly valid if that's how your brain works. The breadcrumb trail keeps you oriented no matter how deep you go. ### Seeing where an item is filed Open any inventory item and you'll find **Filed in** just under Category, naming the folder it lives in. Tap it to jump straight to that folder. If the item isn't in a folder at all, it reads **Home**. An item can be in more than one folder — filed under both "Pool" and "Spares", say — in which case you'll see something like **Pool +2**, and tapping opens the folder picker so you can see and change the full set. **Filed in** is about organization; **Last seen** further down the same card is about physical location — the Zone a beacon last spotted the thing in. They're different questions, which is why they have different names. Search results carry the folder too, as a small line under each result. That's where it does the most work: when two similar-looking things come back, the folder is usually what tells them apart. Inside a folder, results don't repeat it — every row would say the same thing. Your AI knows this as well now. Ask "which folder is my salt cell in?" or "what's in the garage that's expiring?" and it can answer directly, including through Claude Desktop and other connected apps. ## Tips & Tricks - **Keep it flat unless you have a reason not to.** A handful of well-named top-level folders (Receipts, Warranties, Medical, Home, Work) is usually better than an elaborate hierarchy. You can always add depth later. - **Use descriptive folder names.** "Stuff" and "Misc" are the enemies of future-you. "Kitchen Appliance Manuals" is a folder name that pays dividends when you're troubleshooting your dishwasher at 10 PM. - **The Don't Panic folder stays pinned at the top.** No matter how many folders you create, the help guides are always right there. It's the one folder that genuinely wants to be found. ## Options | Setting | What It Does | Default | |---------|-------------|---------| | Default upload folder | Where new documents go when you don't choose a folder | My Documents | | AI folder icons | Whether the system generates custom icons for folders | On | ## Known Limitations - ~~No drag-and-drop on iOS~~ **Drag-and-drop works everywhere now.** On iOS, long-press a card for a moment and drag it onto a folder or breadcrumb; the web interface supports the same gesture with the mouse on both Inventory and Documents. Selection mode + Move remains available on every surface for bulk reorganizing. - **Deeply nested folders can be hard to navigate on mobile.** The breadcrumb trail helps, but on a phone screen, four or five levels deep starts to feel cramped. Consider flattening your structure if you find yourself scrolling the breadcrumbs. - **Deleting a folder keeps your stuff.** A folder is a grouping, so deleting one removes the grouping and sends the folder to Trash (with an **Undo** right there if you slipped) — the items and documents that were in it stay in your library, just no longer filed under that folder. To remove the contents too, trash them separately. - **Same-name folders collapse to one.** If you (or an AI on your behalf) try to create a folder that already exists with the same name in the same parent, you'll get the existing one back rather than a duplicate. Names are matched after trimming whitespace. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 8 | 2026-08-11 | New "Seeing where an item is filed" section — **Filed in** on item detail (iOS + web), the folder on search results and chat item cards, and folder names now reaching your AI and connected apps (AMB-702) | | 7 | 2026-07-26 | New "Document folders and inventory folders" section — destination pickers offer only folders that can hold what you're filing, and a folder widens to hold both kinds when you deliberately file the other kind into it | | 6 | 2026-07-05 | Added folder management (rename / edit / delete with Undo) on iOS long-press + web menu; folder is a route to sharing; clarified that deleting a folder keeps its contents (AMB-429/430/432, v0.13.2) | | 5 | 2026-07-02 | Web: item drag-and-drop + folder button + bulk move (parity with documents); iOS drag-and-drop limitation lifted (AMB-420) | | 4 | 2026-06-07 | Terminology: "Admin Web" → "Web" (the web interface) | | 3 | 2026-05-27 | Updated MCP tools section with current view/folder tool names (AMB-188) | | 2 | 2026-05-02 | Note same-name folder collapse (AMB-106) | | 1 | 2026-03-01 | Initial guide | --- ## Documents — Receipts, Manuals & Files URL: https://dont-panic.ambientchat.ai/article/documents-receipts-manuals-files Updated: 2026-08-13T22:15:10.531Z # Documents — Receipts, Manuals & Files Your paper trail, digitized and searchable. Never rummage through a drawer looking for a warranty again. ## What It Does Documents in ambientChat are digital copies of the real-world paperwork that accumulates around your life — receipts, product manuals, warranties, certificates, contracts, and anything else worth keeping. When you upload a document, the AI reads it, extracts the important details, generates a summary, and tags it for easy searching later. The magic is in the connections. A receipt doesn't just sit in a folder — it links to the inventory items it created. A warranty knows which product it belongs to. Your AI assistant can search across all your documents when you ask about purchases, coverage, or that thing you bought six months ago whose name you can't remember. You can upload files you already have, not just photos: **PDFs**, **Office files** — Word (`.docx`), Excel (`.xlsx`), PowerPoint (`.pptx`) — and **spreadsheets exported as CSV or TSV** (`.csv`, `.tsv`). The text inside them is extracted so they're fully searchable and available to your AI assistant, exactly like the documents you can ask the AI to **create** for you (see [Creating Documents](23-creating-documents.md)). Uploading and generating produce the same kind of searchable document. A CSV gets a little extra: the app reads the table, so opening one shows its columns and first rows as a proper table — you can see what's in a spreadsheet without downloading it — and tells you how many rows and columns it holds. Your AI assistant can answer questions about the contents. Very large CSVs are still stored whole and downloadable, but only the first portion is read into a conversation; the app says so rather than quietly answering from part of the file. **Text files you can edit.** Notes (`.md`), plain text (`.txt`), and spreadsheets (`.csv`, `.tsv`) all open on the same editing screen. You read them the way they're meant to be read — a note renders as formatted text, a spreadsheet renders as a table — and the **pencil** switches to editing the file itself. See [Editing a Document](#editing-a-document) below. ## Document Types The system recognizes and handles several document types, each with tailored AI extraction: | Type | What It Is | What AI Extracts | |------|-----------|-----------------| | **Receipt** | Proof of purchase | Store name, items, prices, date, payment method, tax, subtotal, total | | **Manual** | Product documentation | Product name, key instructions, specifications | | **Warranty** | Coverage information | Product, coverage period, terms, provider | | **Certificate** | Certifications, diplomas | Issuer, date, subject, validity | | **Contract** | Agreements, terms of service | Parties, dates, key terms, obligations | | **Scan** | General scanned documents | Text content, summary | | **Help Guide** | Built-in guides (like this one) | Title, content, tags | | **Note** | Your own written documents | Content, summary | ## How to Use It ### iOS App **Uploading a document:** 1. Open the **Documents** tab in My Things 2. Tap the **Upload** button (plus icon) 3. Choose your source: - **Camera** — take a photo of a receipt, document, or label - **Photo Library** — select an existing image - **File Browser** — pick a PDF, an Office file (Word `.docx`, Excel `.xlsx`, PowerPoint `.pptx`), a `.csv`/`.tsv` spreadsheet, or an image from your device 4. The AI processes the document automatically — extracting text, generating a summary, and assigning tags 5. Your document appears in the current folder, ready to view **Viewing a document:** - Tap any document to open it - **Images** display with pinch-to-zoom - **PDFs** open in a built-in viewer - **Markdown files** render with full formatting - The document detail screen shows the AI summary, extracted data, tags, and any linked inventory items **Linked items:** When a receipt or product scan creates inventory items, those items are linked back to the source document. You'll see a **Linked Items** section on the document detail screen. Tap any linked item to jump straight to it in your inventory. ### Web 1. Go to the **Documents** section 2. Click the **Upload** button 3. Select one or more files — images, PDFs, Office files (Word `.docx`, Excel `.xlsx`, PowerPoint `.pptx`), `.csv`/`.tsv` spreadsheets, and `.md` markdown files are all supported 4. Documents are processed and appear in the current folder 5. Use **drag-and-drop** to move documents between folders — just drag a document card onto a folder ### Via Chat Your AI assistant can search and retrieve documents on your behalf. Try: - *"Show me my receipts from Costco."* - *"Find my laptop warranty."* - *"What did I buy at Target last month?"* - *"Do I have a manual for my air fryer?"* - *"How much did I spend on groceries this week?"* You can also **attach files directly in chat**. Tap the attachment button, select a file, and choose which folder to save it to. The AI will process the document and include its contents in the conversation. ### Via Claude Desktop (MCP) If you've connected ambientChat to Claude Desktop via MCP, you can access your documents with these tools: - **`list_documents`** — List documents, optionally filtered by format (`mediaType`, e.g. `text/csv`), type, category, and folder - **`get_document`** — Get full details — AI summary, linked items, metadata - **`search_documents`** — Keyword search across titles, summaries, and content - **`search_documents_semantic`** — AI-powered semantic search by meaning - **`update_document`** — Update a document's title, description, or tags - **`update_text_document`** — Replace the contents of a note, `.txt`, `.csv` or `.tsv`. Send the whole new text, not a patch. Refuses a spreadsheet that doesn't parse rather than saving a broken file - **`undo_text_update`** / **`redo_text_update`** — Step a text document back or forward through its edit history. For a spreadsheet this restores the previous *file*, exactly - **`read_document_rows`** — Page through a stored spreadsheet's rows without loading the whole file - **`upload_document`** — Upload a new document for AI processing - **`move_document`** — Move a document between folders - **`trash_document`** / **`restore_document`** — Soft delete and restore - **`regenerate_document_image`** — Generate a new AI illustration thumbnail For the full tool reference, see [MCP Tools — Complete Reference](20-mcp-tools.md). Example: Ask Claude Desktop *"Search my ambientChat documents for appliance warranties"* and it will use these tools to find and display them. ## Multi-Page Documents A manual, warranty booklet, or contract is one document with many pages — not a pile of unrelated photos. Open any photo document and you'll see a **PAGES** strip: - **Add pages** — photograph the rest and add the shots. They become numbered pages of that one document, in the order you add them. Works on iOS (Take Photo / Choose from Library, multi-select) and in the web interface. - **Tap a page** to view it full size. The **✕** removes a bad shot and the rest renumber. - **Ask about a page** — *"read page 11 of the drill manual"*. The AI can look at whichever pages you name, which matters for a long manual: without naming them it only ever sees the first few. - **In chat** — attach the photos and say *"add these as pages of the drill manual"*. The document's original photo stays as page 1, and a document always keeps at least one page — trash the whole document instead of emptying it. **Already uploaded a manual as separate photos?** Turn on **Select**, tick the pages in the order you want them, and tap **Combine**. They become one multi-page document: the first one you selected keeps its title and stays where it is, the rest become its pages and go to **Trash** — so if you pick the wrong ones, nothing is lost. Any item they were attached to stays attached. Combine only appears for photo documents. PDFs already paginate themselves, so they don't take photo pages — their page previews are rendered from the file and shown read-only. Only the first several pages get previews on very long PDFs; the AI still reads the whole document's text either way. ## Tips & Tricks - **Scan receipts sooner rather than later.** Thermal paper receipts fade over time, and once they're too faint, even AI can't read them. Snap a photo while the ink is still fresh and you'll have a permanent, searchable record. - **The AI summary is often enough.** You don't always need to open the full document. The summary on the document card captures the key details — store, total, date — so you can find what you need at a glance. - **Use folders to stay organized.** A few well-named folders (Receipts, Warranties, Medical, Home) go a long way. See the [Folders guide](07-folders.md) for more on organization. ## Options | Setting | What It Does | Default | |---------|-------------|---------| | Auto-tag | AI automatically assigns tags to uploaded documents | On | | Default folder | Where new documents are saved when no folder is selected | My Documents | ## Editing a Document Notes, plain text files and spreadsheets can be edited in place — you don't have to download, change, and re-upload. **How it works** 1. Open the document. A note shows as formatted text; a `.csv` or `.tsv` shows as a table. 2. Press the **pencil** (top right). 3. Edit, then press **Save**. Cancel throws the edit away. **What you're editing, for a spreadsheet** You edit the file's real text — one row per line, values separated by commas (or tabs, for a `.tsv`). That's deliberate: it's the actual file, so nothing is lost in translation. Two things worth knowing: - **A value containing a comma or a line break must be wrapped in double quotes** — `"Smith, John"` is one value, `Smith, John` is two. The editor tells you if you leave a quote unclosed, and **refuses to save** rather than saving a broken file. - **One row can span more than one line** when a value contains a line break. So a 95-row spreadsheet may show more than 95 numbered lines. The count above the editor always tells you the real row and column totals. **Changed your mind?** Ask your assistant to *"undo that edit"*. For a spreadsheet this puts the previous **file** back exactly as it was — not an approximation of it. You can undo repeatedly, and redo if you undo too far. **When editing isn't offered** Very large files are read-only in the app, and the screen says so with the actual number — *"This has 12,480 rows — too many to edit in the app. Download it to change it in a spreadsheet app."* There's no greyed-out button to puzzle over: either the pencil is there, or there's a sentence explaining why it isn't. Other reasons you might see: the file is bigger than the app can safely edit, someone else is editing it right now, or its stored file is missing. Everything else — PDFs, images, Office files (`.docx`/`.xlsx`/`.pptx`) — is not editable in the app. Download those, change them in the app that made them, and upload again. A `.xlsx` in particular can hold several sheets, and the editor is built around single-table files. ## Known Limitations - **Maximum file size is 100 MB per upload.** Large presentations and image-heavy documents are fine. - **Very large PDFs (over ~15 MB) skip AI visual analysis.** They still upload and become fully searchable — the text is extracted and summarized — they just don't get the vision-based content detection (receipt/manual/contract) that smaller PDFs get, which is what the AI matches against when you ask for "my warranties". - **Photographed pages aren't text-searchable yet.** Pages you add as photos can be *looked at* by the AI — ask for a page and it reads it — but their text isn't extracted into search the way a PDF's is. Searching for a phrase you know is on page 7 won't find it; asking the AI to read page 7 will. - **Handwritten documents have lower AI accuracy.** The AI does its best with handwriting, but typed or printed text is significantly more reliable. If the AI misreads something, you can edit the extracted text manually. - **PDF text extraction depends on PDF quality.** Scanned PDFs (essentially images) are processed through OCR, which works well but isn't perfect. Native-text PDFs extract cleanly. - **Filter by format.** Documents are sorted by what they're *stored as* — CSV, TSV, PDFs, Notes, Office, Images — and each card carries the same word as a badge, so the row you filter by and the label you read agree. A format only appears once you actually have a file of that kind. There's no "Receipts / Manuals / Warranties" row: what a document *means* is something the AI works out and searches on for you, not a shelf you have to file it on. - **Turn a spreadsheet into inventory.** Open a `.csv` or `.tsv` and tap **Create items** (the table-arrow button, top right on iOS and web). That hands the file to chat with the request already written — press send and the assistant shows you which column it thinks is the name, the brand, the price, and so on. Approve it and the rows become items. It remembers the layout, so the next export from the same source imports without asking again. Duplicates are skipped, and "undo that" puts the whole import in Trash in one go. - **Spreadsheet size limit.** CSV and TSV files are capped at 25 MB (other files at 100 MB) because every row is read and indexed. A CSV that won't upload is usually one that should be split. - **Office files are read for their text, not rendered as pages.** Uploaded Word/Excel/PowerPoint files have their text extracted so they're searchable, but they don't get a page-image preview — open them with the Download action to see the original formatting. Password-protected Office files can't be read. - **Receipt extraction is optimized for US retail formats.** Receipts from other countries or highly stylized formats may have lower extraction accuracy. - **Same image, same document.** If the same uploaded file shows up twice (for example, a chat upload that was also queued for inventory scanning, or a retried scan job), only one document is kept. Earlier builds occasionally produced duplicates — if your document count looks inflated, you can delete the extras from the documents list directly. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 12 | 2026-08-10 | Edit notes, `.txt`, `.csv` and `.tsv` in the app — spreadsheets open as a table and edit as text, with quoting help, a clear reason when a file is too big to edit, and "undo that edit" restoring the previous file exactly | | 11 | 2026-08-05 | Combine — gather separately-uploaded photo pages into one multi-page document from Select mode (iOS + web) | | 10 | 2026-07-28 | Turn a spreadsheet into inventory items — "Create items" on any CSV/TSV, with a column mapping you approve once per file layout, duplicates skipped, and one undo for the whole import | | 9 | 2026-07-28 | `.tsv` files upload too, and the format filter row only shows the formats you actually have | | 8 | 2026-07-28 | Upload `.csv` spreadsheets — table preview, searchable contents, and a new format filter row (CSV / PDFs / Notes / Office / Images) | | 8 | 2026-07-28 | PDF page previews shown in the same PAGES strip (read-only), with an honest count on long files | | 7 | 2026-07-27 | Multi-page documents — add photographed pages to one document, view/remove them, ask the AI to read a page (iOS + web + chat) | | 6 | 2026-07-09 | Upload limit raised 20 MB → 100 MB; very large PDFs degrade to text-only (skip vision analysis) | | 5 | 2026-07-09 | Upload Office files (.docx/.xlsx/.pptx) — text extracted + searchable, on mobile and web | | 4 | 2026-06-07 | Terminology: "Admin Web" → "Web" (the web interface) | | 3 | 2026-05-27 | Updated MCP tools section with current tool names + full tool list (AMB-188) | | 2 | 2026-05-02 | Note same-image dedup (AMB-106) | | 1 | 2026-03-01 | Initial guide | --- ## Chat — Talking to Your AI Assistant URL: https://dont-panic.ambientchat.ai/article/chat-talking-to-your-ai-assistant Updated: 2026-08-13T22:15:10.393Z # Chat — Talking to Your AI Assistant You have an AI assistant that actually knows what you own, where you are, and what you've talked about before. It's like having a personal concierge who never forgets and never judges your snack habits. ## What It Does The Chat tab is your direct line to a context-aware AI assistant. Unlike a generic chatbot that starts every conversation from scratch, your ambientChat assistant has access to your full inventory, your documents, your location context, and your conversation history. Ask it about your stuff, your receipts, what's expiring, or what you talked about last week — it already has the background. It can answer questions, generate shopping lists, summarize receipts, estimate the value of your collections, and help you make sense of everything you've cataloged. Think of it as the one friend who actually remembers where you put things. ## How to Use It ### iOS App 1. Tap the **Chat** tab at the bottom of the screen 2. Type your question or request in the **text field** at the bottom 3. Tap the **send button** (the **↑** up-arrow) to submit your message. On iOS, the keyboard's **Return** key adds a **new line** inside your message instead of sending it — so you can write multi-paragraph or list-style prompts and only send when you tap **↑**. 4. Your AI responds in the conversation area above, with your messages on the right and AI responses on the left **The Context Bar**: At the top of the chat, you'll see a bar showing the current context being sent to the AI — your active beacon or location, nearby items, and any focused context. This is how the AI knows where you are and what's around you. **Attachments**: Tap the **attachment button** (paperclip icon) next to the text field to send images, PDFs, or other documents along with your message. You can also pick something you already own — **Pick from myAI Context** attaches an existing inventory item or document by reference. **Choose what happens to an attachment.** Once a file is attached, pick one of three: | Choice | What you get | |---|---| | **Just discuss** | Nothing is saved. The AI can see the file for this conversation only. | | **Save as document** | The file is filed in **Documents**, in a folder you choose. | | **Add to inventory** | The file is scanned and any products in it become **inventory items**, filed in an inventory folder you choose. Your photo is kept alongside them. | It's one choice, not a set of checkboxes — documents and inventory are separate folder trees, so the **folder picker** below shows only the folders that can hold what you're saving. Pick "Add to inventory" and you browse inventory folders; pick "Save as document" and you browse document folders. Switching between them resets the folder, because a document folder isn't a valid home for an inventory item. You can drill into subfolders, and **New Folder** creates one of the right type in the spot you're looking at. **Attach a photo and ask the AI to save it.** Send a picture with something like *"add this to my inventory"* and the item is created from what the AI can see plus anything you tell it — and **your photo is kept as the item's image**, rather than the AI illustration scanned items normally get. Handy for one-of-a-kind things where the actual picture is the point. The same works for something you already own — *"this is a better photo of my cordless drill"* attaches the picture to that item. **Answers hand you the actual thing.** When the AI touches something you own — creates an item, updates one, finds a few, opens a document — the answer carries the real record, not just a sentence about it. What you see scales with how many there are: | How many | What appears | |---|---| | One | The item's **actual inventory card** — the same card you'd see in myAI Context, with its photo, name, and details | | Two to six | A row of **thumbnails** you can tap | | Seven or more | A single chip — *"24 items"* — that **expands in place** to list them, grouped by kind, so you stay in the conversation | Tap any of them to open the real record. If something has since been trashed it shows up muted with an **In Trash** badge instead of a dead link, and if it was deleted for good you'll see its name as plain text with a note. The names and pictures are looked up fresh every time, so a thread you reopen next year shows what things are called *now*, not what they were called then. This works for photos too. Attach a picture, choose **Add to inventory**, and the card appears in that same answer as soon as the scan finishes — usually a few seconds after the AI stops typing. You don't need to reload or go looking for it. **Ask AI about a specific item or document**: You don't have to start in chat. Open any of your items (the speech-bubble button on the item's photo) or any of your documents (the speech-bubble icon in the header) and tap **Ask AI** — a fresh conversation opens with that item or document already attached. Type your own question ("Is this contract missing anything?", "Is this still safe to eat?") and send. Because the attachment is part of the conversation, the AI keeps it in scope for follow-up questions, and you can switch models mid-thread for a second opinion on the same attachment. **Voice Input**: Tap the **microphone button** — in the row of round buttons above the message box, between the panel-of-experts toggle and the model button — to speak your question instead of typing. The app transcribes your speech and sends it as a message. Handy when your hands are full of groceries you're about to catalog. **Voice Output**: The AI can read its responses aloud. When a response arrives, you'll see **play/pause controls** to start and stop audio playback. Useful when you're cooking and need hands-free answers about that expiring cream cheese. **Model Selection**: Tap the **model button** at the right-hand end of that same row to open the model selector. The button shows the provider's logo and the model's price band — **$** Everyday, **$$** Thoughtful, **$$$** Premium, **$$$$** Frontier — and the selector spells out the band names beside the same $ signs. (Long-press the button to see the band name without opening the selector.) You can switch between AI providers — **OpenAI**, **Google Gemini**, and **Anthropic Claude** — depending on which model you prefer or which handles your question best. **Usage Indicator**: A small indicator shows how many tokens you've used against your subscription tier's limit. Keep an eye on this if you're on the free tier — your AI is helpful, but it does have a budget. ### Web The web interface at `app.ambientchat.ai` has the same chat, in your browser: 1. Open the **Chat** page 2. Type in the box at the bottom; **Enter** sends and **Shift+Enter** adds a new line (the desktop convention) 3. Responses stream in above; a **Stop** button appears while the AI is replying 4. **Attachments**: drag a file onto the chat, or use the attach button, to send images or PDFs — or **Pick from myAI Context** to attach an existing item or document. The same **Just discuss / Save as document / Add to inventory** choice appears, with a folder picker showing only folders of the matching type 5. **Ask AI from a detail view**: open any item or document in **myAI Context** and click the teal **Ask AI** pill in the header — a fresh conversation opens with it attached, ready for your question 6. **Answers hand you the actual thing** here too — the real card for one record, thumbnails for a few, an expanding *"24 items"* chip for many. Clicking one opens it, and the address bar updates so you can bookmark or share that exact record 7. **Model picker**: click the model button (top-right) to switch provider/model — your choice is remembered on this device 8. **Panel**: toggle Panel mode, then switch models and press ↻ to put your last question to the next expert — each one reads and responds to the last (see [Panel of Experts](19-panel-of-experts.md)) Voice input and spoken replies are iOS-only — the web chat is text-only. ## Tips & Tricks - **Be specific with your questions.** "What's expiring this week?" is better than "What about my food?" The AI has access to your entire inventory and document history, so the more precise you are, the more useful the answer. - **The AI remembers your conversations.** You can reference past chats: "What did we talk about last Tuesday?" or "Remind me what you said about my camera collection." It searches your conversation history automatically. - **Try different models for different tasks.** Some models are better at creative writing, others at precise analysis. If one model's answer isn't quite right, switch to another and ask again — your context carries over. - **Press Return for a new line.** On the iOS app, the Return key inserts a line break, so you can compose longer, structured prompts (steps, lists, several questions at once). Your message only sends when you tap the **↑** button. On the web interface it follows the desktop convention instead: **Enter** sends, **Shift+Enter** adds a new line. - **Re-ask the next expert in one tap.** In **Panel Discussion** mode (the 👥 team toggle), leaving the text box empty turns the send button into a **↻ repeat** icon — switch models first, then tap it to put your last question to the newly-selected model, which reads and responds to what the earlier model said. ## Example Prompts Here are some things you can ask that take full advantage of your personal context: - *"What's expiring this week?"* - *"How much is my electronics collection worth?"* - *"Create a shopping list from my low-stock pantry items."* - *"What did we talk about last Tuesday?"* - *"Show me all my receipts from Costco this month."* - *"What spices do I have that go with chicken?"* - *"Summarize the warranty for my laptop."* - *"What's in my medicine cabinet that expires soon?"* ## Options | Setting | What It Does | Default | |---------|-------------|---------| | AI Model | Which AI provider handles your questions | Gemini | | Voice Output | Whether AI responses are read aloud | Off | | Voice Input Language | Language for speech recognition | Device language | ## Every Answer Is Signed ambientChat lets you use models from all three frontier labs, so every answer tells you exactly which one wrote it: - **In the chat**, each answer carries the provider's brand icon and the friendly model name (e.g. **Gemini 3.1 Pro**, **Claude Opus 5**) above the bubble — including answers in reopened conversations and each expert's answer in Panel mode. Answers that arrived from an external AI connected over MCP are labeled "via " instead. - **In the Q&A view** (myAI Context → Q&A), every saved answer card shows the same brand icon + model name, a chip for the surface it came from (**Text**, **Voice**, or **MCP**), when it happened, and — if the exchange was part of a named conversation — the conversation's name, so you can tell at a glance which chat it belongs to. - **The Q&A view is a scannable index**: every conversation — single question or long thread — shows as one compact row with the stacked logos of every model that took part, its name, answer count, and time, so a screenful shows dozens of conversations. Everything starts collapsed; **tap a row to expand** its full answers in place (your expansions are remembered next time), and searching expands the matches automatically. - **The ↗ glyph on a row reopens that conversation in Chat** so you can pick up where you left off. ## Known Limitations - The AI cannot take actions on your behalf yet — it can tell you what's expiring, but it can't order replacements or throw things away for you. (Probably for the best.) - Token limits depend on your subscription tier. Free users have a limited number of AI interactions per month. If you hit the ceiling, you'll get a friendly nudge to upgrade. - Very long conversations may truncate older context. If the AI seems to have forgotten something from much earlier in the chat, start a new conversation — it still has access to your full inventory and documents. - Image analysis in chat depends on the selected AI model's vision capabilities. Not all models handle images equally well. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 13 | 2026-08-08 | The mic joined the button row above the message box (it used to vanish as soon as you typed); the model button now shows the price band as **$**–**$$$$** instead of the band name | | 12 | 2026-08-05 | "Pick from My Stuff" renamed **Pick from myAI Context** — My Stuff was never a real surface; the picker at Home now shows only Home's documents instead of every document in the library | | 1 | 2026-03-01 | Initial guide | | 11 | 2026-07-26 | Attachments now take ONE choice — Just discuss / Save as document / Add to inventory — and the folder picker shows only folders that can hold what you're saving; both surfaces | | 11 | 2026-07-26 | Attaching a photo also works for items you already own — adds or replaces that item's picture | | 10 | 2026-07-25 | Attach a photo and ask the AI to save it — the item keeps your photo as its image; see [Inventory](03-inventory.md) v10 | | 9 | 2026-07-23 | Corrected Panel mode description — it's sequential (switch model, then ↻ re-ask) not "ask several models at once"; see [Panel of Experts](19-panel-of-experts.md) v3 | | 8 | 2026-07-20 | Q&A is now a collapsed-by-default index — every conversation is one row, tap to expand, ↗ opens it in Chat; search auto-expands matches — both surfaces | | 7 | 2026-07-19 | Q&A conversation collapse choices are now remembered across visits — both surfaces | | 6 | 2026-07-18 | Q&A view groups answers by conversation (stacked model logos, collapsible); conversation names are tappable and reopen the thread in Chat — both surfaces | | 5 | 2026-07-16 | New "Every Answer Is Signed" section — model brand icon + friendly name on every answer (chat + Q&A view), surface chip and conversation name on Q&A cards | | 4 | 2026-07-16 | "Ask AI about this" from item/document detail on iOS **and** web — fresh thread with the asset attached, you frame the question; noted Pick from myAI Context in both attachment sections | | 3 | 2026-06-07 | Added Web section — chat in the web interface (Enter to send, model picker, Panel, attachments); fixed "web console" wording | | 2 | 2026-06-06 | iOS: Return now adds a new line; tap the **↑** button to send. Documented the web Enter / Shift+Enter convention and the **↻** re-ask-the-panel shortcut in Panel Discussion mode. | --- ## Scanning — Barcodes, Receipts & Photos URL: https://dont-panic.ambientchat.ai/article/scanning-barcodes-receipts-photos Updated: 2026-08-13T22:15:10.215Z # Scanning — Barcodes, Receipts & Photos Point your camera at practically anything and the app will figure out what it is. It's the fastest way to fill your inventory, and it's more than a little bit magical. ## What It Does Smart Scan is the AI-powered camera at the heart of ambientChat.ai. It doesn't just take photos — it understands what it's looking at. Point it at a barcode and it looks up the product. Point it at a receipt and it extracts every line item, price, and store name. Point it at a shelf full of spice jars and it identifies each one individually. Everything it recognizes gets added to your inventory automatically, complete with names, categories, estimated prices, and expiry dates where applicable. You scan, it catalogs. The division of labor is quite civilized. ## How to Use It ### iOS App #### Basic Scanning 1. Tap the **Scan** tab at the bottom of the screen 2. Your camera activates with the Smart Scan viewfinder 3. Point the camera at what you want to scan 4. Tap the **shutter button** (large circle at the bottom center) 5. The screen briefly freezes to confirm capture, then returns to the viewfinder 6. Your item is uploaded to the server for processing — you'll see a progress indicator at the top of the screen You can scan multiple things in quick succession. Each capture is queued and processed in the background, so you don't have to wait between shots. #### Barcode Scanning For products with a UPC or EAN barcode: 1. Open the **Scan** tab 2. Point the camera at the barcode — the viewfinder will recognize it automatically 3. Tap the **shutter button** to capture 4. The barcode is decoded and the product is looked up in a global product database 5. If found, the item is created with full product details: name, brand, category, image, and often nutritional or ingredient data Barcodes work best when: - The barcode is flat and not crumpled - You're close enough that the barcode fills at least a third of the viewfinder - The lighting is even (no harsh shadows across the bars) #### Receipt Scanning For paper receipts: 1. Lay the receipt flat on a surface (a table, counter, or even the floor works fine) 2. Open the **Scan** tab 3. Position the camera so the entire receipt is visible in the viewfinder 4. Tap the **shutter button** 5. The AI reads the receipt and extracts: - **Store name** and location - **Date** of purchase - **Individual line items** with descriptions and prices - **Total** amount 6. Each line item becomes a separate inventory entry, and a receipt document is created linking them all together For long receipts, you may need to take multiple photos. The AI is quite good at figuring out what's a product name and what's a tax line or subtotal. #### Photo Scanning (Products & Items) For anything that doesn't have a barcode, or when you want to scan multiple items at once: 1. Open the **Scan** tab 2. Point the camera at the item or group of items 3. Tap the **shutter button** 4. The AI analyzes the image and identifies what it sees 5. Each detected item becomes an inventory entry **Multi-item detection** is one of Smart Scan's best tricks. Take a photo of your medicine cabinet, a shelf of pantry items, or a collection of tools (or six album covers laid out on the rug), and it will try to identify each item individually. One photo, many inventory entries. #### Per-Item Photos, Cropped Automatically When you scan a group of items in one photo, each item gets its own **cropped photo** — the AI locates every item in the frame and the app cuts out just that item's region. Your Crosby, Stills & Nash record shows its actual cover, not the whole floor. The original group shot is kept too, on the scan's source document, and the "Scanned with N others" strip on any item shows its scan-mates with their own crops. A few things worth knowing: - **When the crop is good, it becomes the item's picture everywhere** — the grid thumbnail, the detail page, chat context. No stylized icon is generated for that item (which also makes the scan faster and cheaper). - **When a crop can't be trusted** — cluttered scenes, partly hidden items — the app plays it safe and keeps the group photo for that item rather than showing you a bad crop. - **Want the illustrated look instead?** Tap **Iconify** on the item's detail page and the app draws its stylized 3D icon on demand. Iconify replaces the thumbnail; the photo stays on the detail page. - **Sideways photo?** Photos taken pointing straight down (flat-lays) occasionally come out rotated — gravity gives the camera no clue which way is up. The app reads the items' own text to guess the right orientation, and if it still gets it wrong, open the item's **⋯** menu and use the **Rotate** row: two arrows, one anticlockwise and one clockwise, turning the photo 90° a tap. A spinner covers the photo while the new version is prepared. The fix shows up on every device. #### Saving Scans into a Folder Above the shutter you'll see **Save to folder?** with chips for your recently used folders, a **Browse** button, and **Skip — AI decides**. Pick a folder (or create one — you can nest folders, like Music/Vinyl) and every item from your scans lands there, visible on the Inventory tab. The chip stays armed for back-to-back scans, so cataloging a big collection is: pick folder once, then shoot, shoot, shoot. Already saved something and want it somewhere else? The **Saved** confirmation that slides up carries a **Change** button — tap it to pick a folder and the item moves. No need to decide before you shoot. #### Your Scan Session Stays Put A scan mode — AI Lookup, Radar, Add Items — is a *session*. Ask the AI about something you've just scanned and you'll land in Chat; come back to Scan and your cards, your captures, and your chosen folder are exactly where you left them. Nothing is thrown away and nothing needs re-scanning. Two things end a session deliberately: - Tapping the **✕** in the corner of the mode. - Tapping the **Scan** tab while you're *already* looking at Scan — the app-wide "tap the tab you're on to go back to the top" gesture. Anything else — switching tabs, taking a phone call, opening a document — leaves it running. The camera itself does shut off while you're away (it's the biggest battery draw on the phone) and wakes up when you return. #### Camera Controls - **Flash toggle** — Tap the lightning bolt icon to cycle the flash on or off. Useful in dim environments. - **Help overlay** — A rotating overlay appears briefly every cycle (10 seconds visible, then fades for 40 seconds) showing you what Smart Scan can detect: Receipts, Products & Items, and Barcodes. It's a gentle reminder, not a demand for attention. #### BLE Tag Scanning There's a separate scanner for Bluetooth Low Energy (BLE) tags — small wireless tags attached to physical products that carry Digital Product Passport (DPP) data. 1. From the **Scan** tab, tap the **Bluetooth icon** in the top corner 2. The BLE tag scanner opens, searching for nearby broadcasting tags 3. Detected tags appear in a list with signal strength 4. Tap a tag to read its product data and add it to your inventory This is a specialized feature — you'll only use it if you encounter products with BLE-enabled tags (common in retail pilot programs and smart packaging). #### What Happens After You Scan 1. **Immediate:** The scan is submitted to the server. You'll see a brief "Submitting..." indicator. 2. **Processing:** The server analyzes the image using AI. This typically takes 5-15 seconds, depending on complexity. 3. **Complete:** New items appear in your inventory under a "Just Added" section. A notification confirms what was found. 4. **Documents:** A source document (receipt, product scan, etc.) is also created and linked to the inventory items. You can find it in the **Documents** sub-tab under **Context**. You can keep scanning while previous items are still processing. The app handles the queue gracefully. #### Where the Scan Was Taken When the app can tell where you were when you scanned — because you're standing near a registered iBeacon, the photo carries GPS in its EXIF metadata, or your phone's location is on — that scene gets stamped onto every item the scan creates as **Last seen**. Precedence (strongest signal wins): 1. **Beacon** — most precise; pins items to a specific Zone you’ve registered. 2. **EXIF GPS in the photo** — accurate to where the photo was actually taken, even if you've since walked off. 3. **Your current device location** — falls back here when the photo has no GPS. If none of those is available — say you've denied location permission and there's no beacon nearby — the scan still works, items just don't get a "Last seen" stamp. Nothing breaks. You'll just lose the ability to ask *"what's in the kitchen?"* for those particular items. ### Web You can add things from the web interface at `app.ambientchat.ai` too — by upload rather than a live camera: 1. Open the **Scan** page 2. Click **Choose Files** and pick one or more images, PDFs, or `.md` files (up to 20MB each) 3. Pick a destination folder (defaults to My Documents) 4. The AI processes each file and creates inventory items and/or documents, just like a phone scan On a phone browser you'll also see **Take Photo** and **Photo Library** buttons; on desktop there's no live camera, so use **Choose Files**. ### Via Chat You can also add items through conversation: - *"Add a bottle of olive oil to my inventory"* - *"I just bought 3 AA batteries at Walgreens for $8.99"* The AI will create inventory entries based on your description. It's not as rich as scanning (no barcode lookup, no image analysis), but it works in a pinch. ### Via Claude Desktop (MCP) Through the MCP connection, you can use: - **`ambientchat_process_image`** — Submit an image URL for scanning and inventory creation. Works with product photos, receipts, and barcodes. Example: *"Process this image of my grocery receipt and add everything to my inventory."* ## Tips & Tricks - **Good lighting makes a real difference.** Smart Scan can handle imperfect conditions, but well-lit, clearly visible items produce dramatically better results. Natural daylight is ideal; harsh overhead fluorescents are the enemy of receipt scanning. - **Hold the camera steady for a moment before tapping.** The capture is instant, but giving the autofocus a beat to lock on produces a sharper image, which produces better AI recognition. - **Receipts work best flat and complete.** Crumpled receipts, partial captures, or photos where your thumb obscures the total will still work — but results improve significantly with a flat, fully visible receipt. Smooth it out, pin down the curling edges, and your accuracy will thank you. - **Scan in batches, review later.** You don't have to verify every item as it's scanned. Blast through a pile of products, then visit the Inventory tab to review and correct anything the AI got wrong. It's faster and more satisfying. ## Options | Setting | What It Does | Default | |---------|-------------|---------| | Camera Flash | Toggle flash on/off during scanning | Off | | Help Overlay | Rotating tips about what Smart Scan can detect | On (cycles automatically) | | BLE Tag Scanner | Separate scanner for Bluetooth product tags | Available via Bluetooth icon | ## Known Limitations - **Handwritten receipts are challenging.** The AI can handle printed thermal receipts well, but handwritten notes, invoices, or receipts from very old dot-matrix printers may produce incomplete or inaccurate results. - **Very blurry or dark images may fail.** If the AI can't make out what's in the photo, it will let you know rather than guess wildly. Retake with better lighting or a steadier hand. - **Maximum of about 20 items per photo.** Multi-item detection works well for reasonable groups, but photographing an entire warehouse aisle will hit practical limits. For large collections, take multiple focused photos. - **Barcode lookup depends on the product database.** Obscure, local, or very new products may not be in the global UPC database. In those cases, the AI falls back to visual identification from the photo. - **Processing requires an internet connection.** All image analysis happens on the server, so scanning in airplane mode or areas with no signal won't work until connectivity is restored. The app will queue the scan and submit it when you're back online. - **Thermal receipt paper fades.** This isn't our fault, but it's worth mentioning: if you've got receipts you want to keep, scan them sooner rather than later. The app preserves the data even after the paper becomes an illegible grey smudge. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 6 | 2026-08-12 | Rotate now turns the photo EITHER way — two arrows on the ⋯ menu row — and shows a spinner while it works | | 5 | 2026-07-29 | Added "Your Scan Session Stays Put" — sessions survive leaving the tab; ✕ / tab re-tap end them. Documented **Change** on the Saved confirmation | | 3 | 2026-06-07 | Added Web section — uploading photos/PDFs/markdown via the web interface | | 2 | 2026-05-01 | Added "Where the Scan Was Taken" — beacon/EXIF/GPS precedence, last_seen stamping | | 1 | 2026-03-01 | Initial guide | --- ## Inventory — Adding & Managing Your Things URL: https://dont-panic.ambientchat.ai/article/inventory-adding-managing-your-things Updated: 2026-08-13T22:15:10.062Z # Inventory — Adding & Managing Your Things Your inventory is a digital catalog of everything you own, track, or care about. Think of it as a remarkably thorough list that also happens to know what things cost, when they expire, and what category they belong to. ## What It Does The inventory is your central record of physical items. Every barcode you scan, every receipt you photograph, every product you snap a picture of — they all end up here. Each item gets a name, category, image, and whatever details the AI can figure out (brand, price, expiry date, nutritional info, and more). You can browse your inventory visually, search it, filter by category, edit any detail, and delete things you no longer have. Items link back to their source documents (the receipt or photo that created them), so you always know the provenance of your data. It's your stuff, cataloged and queryable. Surprisingly satisfying. ## How to Use It ### iOS App #### Viewing Your Inventory 1. Tap the **Context** tab at the bottom of the screen 2. You'll land on the **Inventory** sub-tab by default 3. Your items appear in a scrollable list with thumbnail images, names, brands, and categories 4. Use the **search bar** at the top to find items by name, brand, or description 5. Tap any **category chip** below the search bar to filter (Food, Electronics, Medicine, etc.) **Whose things you're seeing** — a small **scope** pill sits on the action row, just left of **Select**. It starts on **All**, which shows your own items *plus* anything other people have shared with you, woven into one list. Shared items carry a badge showing who shared them and are read-only — you can open and view them, but editing, deleting, and moving stay with the owner. Tap the pill to narrow to **Mine** (only yours), **Shared by me** (the items you've shared out), or **Shared with me** (only what others have shared in). The pill is a **filter, not a different screen** — it works exactly like the category chips: you stay right where you are (same folder, same breadcrumb, same tools), you just see fewer cards. Inside the Food folder, **Shared by me** shows only the shared things *in Food*; the folder's own share badges tell you what's inside. The same control sits on the **Documents** and **Questions** tabs. A small count on the pill hints when there's new content shared with you. **Don't want something someone shared with you?** Every shared record offers **Remove from my list** — it only hides the share for *you*; the owner's copy and anyone else's access are untouched, and an **Undo** appears in case you slip. Reach it three ways: **long-press** the shared card or row in the list, tap the **"Shared by …"** banner when you have the item or document open (the banner is the share's front door — tapping it always offers the actions for that share), or on the web interface use the eye-off control on the card or the **Remove from my list** link next to the "Shared by" line in the detail view. Opened a folder someone shared? The "From …" line under the folder name works the same way — removing there takes the whole folder off your list. If you change your mind later, ask the person to share it again. #### Adding Items There are several ways to get items into your inventory: **Scan a barcode:** 1. Tap the **Scan** tab 2. Point your camera at a UPC or EAN barcode 3. The product is looked up automatically and added to your inventory **Scan a receipt:** 1. Tap the **Scan** tab 2. Point your camera at a receipt laid flat on a surface 3. The AI extracts the store, individual items, prices, and date 4. Each line item becomes a separate inventory entry **Take a photo of anything:** 1. Tap the **Scan** tab 2. Point your camera at any product, group of items, or anything you want to track 3. Smart Scan identifies what it sees and creates inventory entries 4. One photo can detect multiple items **Upload from your Context tab:** 1. Tap the **Context** tab, then the **Documents** sub-tab 2. Tap the **+** button to upload a photo from your library or take a new one 3. The AI processes it and creates inventory items from what it finds **Attach a photo in chat:** 1. Open **Chat** and attach a photo (the paperclip, or drag it in on the web interface) 2. Ask the AI to add it — *"add this to my inventory, the artist is Jilly Sutton"* 3. The AI creates the item from what it can see plus whatever you tell it, and **your photo becomes the item's image** — no AI illustration is drawn over it Use this when the thing is one of a kind and the picture matters — a sculpture, an heirloom, a scar on a bike frame. For everyday products, **Scan** is still the better route: it reads barcodes, looks up product data, and can pull several items out of a single shot. **Keep the paperwork with the thing.** Every item has a **Documents** section on its detail screen listing what's attached — manual, warranty, receipt, the scan photo it came from. Tap or click one to open it. Tap **Attach** in that section and you get four ways in (three on the web interface, which has no camera): - **Attach existing document** — pick something already in your Docs, including PDFs. - **Upload a file** — a PDF manual, a warranty, a scan. It uploads, gets processed, and attaches itself to this item when it's done. - **Take photo** *(iOS)* — snap it there and then. - **Add photos as pages** — pick several shots of a multi-page manual and they become **one** document with numbered pages, not a pile of loose photos. Documents you **upload** from an item belong to that item, so they don't also clutter the Documents tab — the same reason a scan's source photo doesn't. They're always reachable from the item, and filing one into a folder puts it back in Docs if you want it there. Documents you **attach** from your existing Docs stay exactly where they were. Or **just say so in chat** — *"that PDF is the manual for my cordless drill"*. Then ask *"do I have the warranty for the dishwasher?"* and the AI looks at what's attached. One item can hold many documents (manual, warranty, receipt), and one document can belong to several items — a single receipt covering three tools. The **✕** on a row detaches it: that removes only the link, and both the document and the item stay put. **Add or replace the photo on an item you already have:** attach the picture in chat and say which item it belongs to — *"this is a better photo of my cordless drill"*. Your photo becomes that item's image. Any AI illustration it was wearing is kept as a second image on the detail screen rather than thrown away, so you can still flip back to it. #### Viewing Item Details 1. Tap any item in your inventory list 2. You'll see the full detail screen with: - The item's picture — your photo or scan — plus any AI illustration as a second image - Name, brand, and description - Category and subcategory - Price (with source: receipt, network lookup, or AI estimate) - Expiry date (if applicable) - Location - **Last seen** — the Zone captured at scan time. Shows as ` · ` (e.g. *"Kitchen · 2 days ago"*). Tap the chevron to reveal the underlying GS1 GLN — useful if you're sharing inventory data with another app or robot that speaks EPCIS. Hidden entirely on items that were added without any location signal. - Notes - Linked documents (the receipt or scan that created this item) - Nutritional and sustainability data (for food items) **Move to the next item without going back.** On the detail screen you can **swipe left or right** (or tap the **‹ › chevrons**) to step to the previous or next item in your list — handy for reviewing a batch you just scanned. It works the same way on the web interface. Reaching the end simply stops; you won't loop around. #### Editing Items 1. Tap an item to open its detail view 2. Tap **Edit** (pencil icon) 3. Change any field: name, brand, category, price, expiry date, location, notes 4. Tap **Save** when done Editable fields include: - **Name** and **Brand** — correct the AI if it got these wrong - **Category** — choose from Food, Electronics, Medicine, Clothing, Tools, and many more - **Price** and **Currency** — actual purchase price - **Expiry Date** — for food, medicine, supplements - **Location** — where the item is stored ("Pantry", "Garage shelf 3", "Bedroom closet") - **Notes** — any free-text annotation you like #### Deleting Items Deletes are always **soft** — items go to Trash, where they stay until you empty it. You can restore anything from there. **Single item (swipe):** 1. Swipe left on any item in the inventory list 2. Tap the **Delete** button that appears 3. The item moves to **Trash**, and a Snackbar slides up at the bottom: *"Item moved to Trash · Undo"*. Tap **Undo** to bring it back instantly. The toast auto-dismisses after a few seconds; the item is still in Trash if you change your mind later. **Multiple items (selection mode):** 1. Long-press any item to enter **selection mode** 2. Checkboxes appear next to each item 3. Tap to select as many items as you want 4. Tap the **Delete** button in the toolbar — they all move to Trash. The Snackbar offers a single batched **Undo** that restores the whole set. **Cross-channel awareness:** If you ask the AI assistant or Claude Desktop to trash an item, the mobile app surfaces the same "moved to Trash" Snackbar — courtesy notice that something just changed in your inventory, with Undo available. Same toast surface across all channels. **Restoring from Trash:** Open the **Trash** tab (count badge shows how many items are there) to see everything you've trashed recently. Tap **Restore** on any entry to bring it back where it belongs. **Empty Trash** deletes everything permanently — that's the only step that asks for confirmation, because it's the only step that's irreversible. **What shows up in the Trash tab:** The Trash tab is unified — it shows trashed inventory items, documents, *and* deleted Q&A conversations. Each row is labelled with a small overlay icon so you can tell them apart at a glance: - 📦 (cube) — an inventory item; row title is the item name, subtitle is the brand. - 📄 (document) — a trashed document; title is the document name, subtitle is its type (receipt, manual, …). - 💬 (chat bubbles) — a deleted Q&A conversation; title is the first few words of your question, subtitle is a short summary of the answer. Tap **Restore** on any of them to bring it back to its original collection. **Voice:** If you tell the assistant "trash the milk", it confirms with *"Moved milk to Trash — you can ask me to undo it"* and keeps the conversation going. There's no awkward pause waiting for an undo command. Just say "actually undo that" anytime in the next few turns and it will restore. ### Web The web interface at `app.ambientchat.ai` mirrors your inventory in the browser. Open the **Inventory** view under **My AI Context** to browse the same items you see on iOS — a thumbnail grid you can search, filter by category chip, and organize into folders, with an **All / Mine / Shared by me / Shared with me** scope control across the top — **All** is the default and weaves your own items together with anything shared with you (badged and read-only), exactly like the iOS app. **Click any card** to open its full detail, where you can edit fields just like on mobile. Items approaching their expiry dates surface in an **"expiring soon"** banner above the grid; each banner card shows a thumbnail and click-through to the item (see [Expiring Items](08-expiry.md)). **Sorting:** the toolbar's **sort pill** (next to search) offers the same options as the iOS sort control — Name, Value, Expiry date, Recently added, Last seen, Carbon footprint, and By Category. Pick an option to sort; pick it again to flip direction. Your choice is remembered between visits. **Filing items into folders** works three ways on the web, matching Documents: - **Drag and drop** — grab an item card and drop it onto a folder card, or onto a breadcrumb to move it back up. - **The folder button** — hover a card and click the small **folder icon** (next to the trash icon) to pick a destination from the folder list. - **Bulk move** — click **Select**, tick multiple items, then **Move to folder**. ### Via Chat Your AI assistant can answer inventory questions instantly: - *"What's in my inventory?"* - *"How many items do I have?"* - *"Show me my electronics."* - *"What food do I have that's expiring soon?"* - *"How much is my inventory worth?"* - *"What did I buy at Costco?"* - *"Do I have any batteries?"* - *"What spices do I have?"* - *"What's in the kitchen?"* (uses scan-time location stamping) - *"Where did I last see my passport?"* The AI searches your inventory using the same data you see in the app, so its answers reflect your actual items, categories, and quantities. ### Via Claude Desktop (MCP) If you've connected ambientChat.ai to Claude Desktop via MCP, you can use these tools: - **`list_items`** — List items, optionally filtered by category, folder, or search query - **`search_items`** — Semantic search — finds items by meaning ("things in my garage", "snacks for the party") - **`get_item`** — Get full details of a specific item by ID - **`update_item`** — Edit item fields (name, brand, category, price, expiry, location, notes) - **`update_items_by_filter`** — Bulk-update fields across many items at once ("change all items in the kitchen to category Food") - **`trash_item`** / **`trash_items`** — Move one or many items to trash - **`list_expiring_items`** — Find items expiring within a specified number of days - **`get_items_at_scene`** — List items last seen at a specific scene (by beacon, GLN, or scene ID) - **`get_scan_session_items`** — List items created together in the same scan session - **`restore_item`** — Restore an item from trash - **`regenerate_item_image`** — Generate a fresh AI illustration for an item - **`get_item_documents`** — List the paperwork attached to an item (manual, warranty, receipt, source scan) - **`link_document_to_item`** / **`unlink_document_from_item`** — Attach or detach one of your documents to an item For the full tool reference, see [MCP Tools — Complete Reference](20-mcp-tools.md). Example prompt in Claude Desktop: *"Search my ambientChat inventory for anything related to coffee."* ## Tips & Tricks - **Items automatically link to their source documents.** If you scanned a receipt from Target, each item from that receipt links back to the receipt document. Tap "Source" on any item to see the original. - **AI enriches items beyond what you scan.** For food items, the AI adds nutritional data, eco-scores, and sustainability ratings when available. For electronics, it may add specs and model details. You get more than you put in. - **Use location fields to remember where things are.** "Kitchen drawer", "Garage shelf 2", "Medicine cabinet" — when you later ask "Where are my batteries?", the AI can tell you. - **Prices show their source.** You'll see labels like "Receipt," "Network lookup," or "AI estimate" next to prices, so you know how confident to be in the number. AI estimates appear in a different color to flag that they're approximate. ## Options | Setting | What It Does | Default | |---------|-------------|---------| | Category Filter | Filter inventory view by category | All categories | | Search | Full-text search across item names, brands, and descriptions | Empty (show all) | | Sort Order | How items are ordered in the list | Most recently added | ## Known Limitations - **AI estimates are estimates.** Prices and expiry dates guessed by the AI are helpful approximations, not gospel. When in doubt, edit the item with the real data. - **Manual entry isn't available as a standalone option.** Items are created through scanning (barcode, receipt, or photo) or through chat — attach a photo, or just describe the thing, and ask the AI to add it. - **Category assignment is automatic but imperfect.** The AI does its best to categorize items, but "Sriracha" might end up under Beverages if the AI is having an off day. You can always change the category manually. - **Bulk editing is available via chat and MCP.** Ask the AI to "change all items in the kitchen to category Food" and it uses `update_items_by_filter` to do it in one call. Every bulk change is fully reversible — say "undo that" or use `undo_bulk_change`. Bulk editing in the UI (selection mode) is not yet available. - **Items with no picture get an AI illustration.** If a thing arrives without any photo — a receipt line item, something you just described in chat — the AI draws an icon so the card isn't blank. It's illustrative, not photographic evidence of *your* copy. Anything that *does* arrive with a real picture keeps it: a scan, a photo you attached, a product shot from a barcode or AI Lookup. Want an illustration anyway? **Iconify** on the item's detail screen draws one on request. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 15 | 2026-07-29 | Real pictures are kept as the item's image on every route (Lookup, barcode, scan) — AI illustrations only for items with no picture; item uploads stay out of the Documents tab; processing throbber on the Documents panel | | 14 | 2026-07-28 | Attach menu on item detail — upload a PDF or file, take a photo, or add several photos as one multi-page document | | 13 | 2026-07-27 | Documents section on item detail (iOS + web) — see what's attached, attach with a picker, detach with ✕ | | 12 | 2026-07-26 | Attach your own documents to an item — manual, warranty, receipt — and ask what paperwork an item has | | 11 | 2026-07-26 | Add or replace the photo on an existing item by attaching it in chat; any AI illustration is kept as a second image | | 10 | 2026-07-25 | Adding items by attaching a photo in chat — your photo is kept as the item's image instead of an AI illustration | | 9 | 2026-07-05 | Item detail: swipe / chevron navigation to the next & previous item (iOS + web) (AMB-237, v0.13.2) | | 5 | 2026-07-02 | Web: sort pill (iOS parity) + three ways to file items into folders — drag-and-drop, folder button, bulk move (AMB-419/420) | | 4 | 2026-06-06 | Rewrote the Web section to reflect the browser inventory (grid, tabs, clickable cards, expiring banner) (AMB-290) | | 3 | 2026-05-27 | Updated MCP tools section with current tool names, added bulk update + undo (AMB-188) | | 2 | 2026-05-01 | Added Last Seen detail row + room-scoped chat queries + `get_items_at_scene` MCP tool | | 1 | 2026-03-01 | Initial guide | --- ## Getting Started URL: https://dont-panic.ambientchat.ai/article/getting-started Updated: 2026-08-13T22:15:09.846Z # Getting Started Welcome aboard. You've just installed an app that gets smarter every time you use it — so the sooner you start, the sooner it starts being genuinely useful. ## What It Does ambientChat.ai is your personal AI context platform. That's a fancy way of saying: it remembers your stuff so your AI doesn't have to guess. You can scan barcodes, photograph receipts, snap pictures of anything you own, and the app builds a rich, searchable catalog of your world. Then, when you ask a question — "What's expiring this week?", "How much did I spend at Costco?", "What spices do I have?" — your AI assistant already knows the answer, because it knows what you have. The more you tell it, the better it gets. It's a bit like training a very eager, very organized personal assistant who never takes a day off and never forgets where you put the paprika. ## How to Use It ### iOS App When you first open the app, you'll be asked to sign in. You can use **Apple Sign-In**, **Google**, or **email**. Pick whichever feels right — you can always change later from Settings. Once you're in, you'll see a tab bar at the bottom of the screen with these sections: #### The Chat Tab This is your AI assistant. Ask it anything about your inventory, your documents, or just general questions. The more context you've given it (by scanning things, uploading documents, being near beacons), the more useful its answers become. Try typing: *"What do I have in my inventory?"* — even if the answer is "nothing yet," you'll see it working. #### The Scan Tab Point your camera at things and the app figures out what they are. Barcodes, receipts, products on a shelf, a pile of spices — Smart Scan handles all of it. This is the fastest way to build up your context. #### The Context Tab This is where your data lives. It has four sub-tabs: - **Inventory** — Everything you've scanned or added. A visual grid of your items with images, categories, and values. - **Documents** — Receipts, manuals, warranties, and any files you've uploaded or the app has created. Organized in folders. - **Me** — Your interests and preferences that help the AI understand you better. - **Questions** — A history of questions you've asked and the answers you received. Your own personal Q&A archive. #### The Settings Tab Your account, subscription, AI model preferences, privacy controls, data export, and all the knobs you might want to turn. You won't need this on day one, but it's good to know it's there. ### Your First Five Minutes Here's what we'd suggest for your first session: 1. **Scan something.** Tap the **Scan** tab, point your camera at a product with a barcode, and tap the shutter button. Watch it appear in your inventory moments later. 2. **Scan a receipt.** Got a grocery receipt handy? Lay it flat, scan it, and watch the app extract the store name, individual items, prices, and date. Each item gets added to your inventory automatically. 3. **Ask a question.** Hop over to the **Chat** tab and try something like: - *"What's in my inventory?"* - *"What did I just scan?"* - *"What categories do my items fall into?"* 4. **Browse your stuff.** Tap the **Context** tab, then **Inventory**. You should see your scanned items with AI-generated images and details. Tap any item to see its full details. 5. **Explore Settings.** Tap **Settings** to see your subscription tier, choose your preferred AI model, or adjust privacy settings. That's it. Five minutes, and you're up and running. ### Via Chat Your AI assistant is always ready. Here are some conversation starters once you have a few items: - *"What's expiring soon?"* - *"How many items do I have?"* - *"Show me my food items."* - *"What did I buy at Target?"* - *"Help me make a shopping list based on what I already have."* ### Via Claude Desktop (MCP) If you use Claude Desktop, you can connect ambientChat.ai as an MCP server. This lets Claude access your inventory, documents, and context directly from your desktop. It's the same data, the same intelligence — just a different window into it. Once connected, you can ask Claude things like: - *"Search my inventory for electronics"* - *"What documents do I have about my car?"* - *"What food is expiring this week?"* See the MCP Tools guide for setup instructions. ## Tips & Tricks - **The app learns from everything you scan.** A receipt doesn't just create a document — it creates inventory items, tracks prices, and remembers where you shop. One scan, many benefits. - **Good lighting is your friend.** Smart Scan works best in well-lit conditions. You don't need studio lighting, but scanning in a dark closet will test everyone's patience. - **You don't have to scan everything at once.** Build your inventory gradually. Scan things as you buy them, and before you know it, your AI has a comprehensive picture of your world. ## Options | Setting | What It Does | Default | |---------|-------------|---------| | AI Model | Choose which AI model answers your questions (OpenAI, Gemini, Claude) | Gemini Flash | | Voice | Enable voice input and spoken responses | Off | | Context Sharing | Control what context is shared with AI models | All enabled | | Notifications | Expiry alerts, scan completion, beacon events | Enabled | | Welcome Card | Show the briefing card with tips and what needs attention. Settings → Application Behavior → Getting Started on mobile, Settings → App Behavior on the web. Ticking "Don't show again" on the card itself turns this off — this is how you turn it back on | Enabled | ## Known Limitations - The app requires an internet connection for scanning and AI chat. Offline mode is limited to browsing cached inventory. - First-time sign-in with Apple occasionally requires a second attempt on some iOS versions. - AI answers are only as good as the context you've provided — the more you scan and add, the more accurate and helpful responses become. - Free tier users have a limited number of AI tokens per month. Upgrade to a paid tier for more. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 2 | 2026-08-01 | Added the Welcome Card setting — the card's "Don't show again" checkbox previously had no way back | | 1 | 2026-03-01 | Initial guide | --- ## Guide Index URL: https://dont-panic.ambientchat.ai/article/guide-index Updated: 2026-08-13T22:15:09.640Z # Guide Index A complete directory of every help guide in Don't Panic. This index is kept up to date — when new guides are added, they appear here. ## Core Experience | Guide | Tags | Audience | Status | |-------|------|----------|--------| | Getting Started | getting-started | User | Published | | Inventory — Adding & Managing Your Things | inventory, items | User | Published | | Scanning — Barcodes, Receipts & Photos | scanning, inventory | User | Published | | Chat — Talking to Your AI Assistant | chat, ai | User | Published | | Documents — Receipts, Manuals & Files | documents, receipts, upload | User | Published | | Folders — Organizing Your Documents | documents, folders | User | Published | ## Key Features | Guide | Tags | Audience | Status | |-------|------|----------|--------| | Expiring Items — Never Waste Food Again | inventory, expiry | User | Published | | Voice — Speaking & Listening | voice, chat | User | Published | | AI Models — Choosing Your Expert | ai, models | User | Published | | Subscriptions & Usage | subscription, account | User | Published | | Search — Finding Anything | search, inventory, documents | User | Published | | Digital Product Passports | inventory, dpp | User | Published | | Sharing — Items, Docs, Folders & Groups | sharing, collaboration | User | Published | ## Power Features | Guide | Tags | Audience | Status | |-------|------|----------|--------| | Beacons — Location-Aware Inventory | beacons, location | User | Published | | Location Trails — Where You've Been | location, trails | User | Published | | Context Allocation — Tuning Your AI | context, ai | Power User | Published | | Data Export & Import | export, privacy, account | User | Published | | Privacy & Your Data | privacy, account | User | Published | | Panel of Experts — Multi-AI Answers | chat, ai, models | Power User | Published | ## Integration & Admin | Guide | Tags | Audience | Status | |-------|------|----------|--------| | MCP Tools — Using ambientChat with Claude Desktop | mcp, claude-desktop, integration | Power User | Published | | Admin Console — Dashboard & Management | admin, dashboard | Admin | Published | | Admin — User & Beacon Management | admin, management, beacons | Admin | Published | | Creating Documents — Notes, Lists & Reports | documents, markdown, notes | User | Published | | Connected Services — GitHub, Gmail, Slack & More | connected-services, mcp, integration | User | Published | ## Use Cases & Recipes | Guide | Tags | Audience | Status | |-------|------|----------|--------| | Shopping Lists & Meal Planning | recipes, shopping, expiry, documents | User | Published | | Travel & Packing Lists | travel, documents, lists | User | Published | | Reports & Summaries — What Your AI Can Write | reports, documents, ai | User | Published | ## Version History | Version | Date | What Changed | |---------|------|-------------| | 2 | 2026-07-05 | Added Sharing and Connected Services guides (v0.13.2) — 29 guides | | 1 | 2026-03-01 | Initial index with 27 guides | --- ## Welcome to Don't Panic URL: https://dont-panic.ambientchat.ai/article/welcome-to-don-t-panic Updated: 2026-08-13T22:15:09.525Z # Welcome to Don't Panic You're holding the most remarkable reference guide ever compiled about your personal AI context platform. Much like its namesake from a certain interstellar travel guide, it has two important qualities: it's comprehensive, and it tells you not to panic. ## What Is This? **Don't Panic** is your built-in help system for ambientChat.ai. Every guide here explains a feature of the app — what it does, how to use it on each platform, and what to watch out for. Guides are written in plain language, updated as the app evolves, and searchable by your AI assistant. Think of it as the instruction manual that actually wants to be read. ## How to Find Help There are several ways to get to the information you need: ### Browse the Folder On **iOS**: Open the **Documents** tab in My Things, navigate to the **Don't Panic** folder. It's pinned to the top — you can't miss it. In the **web interface**: Go to the **Documents** section, look for the **Don't Panic** folder, or use the **Help Guides** filter chip to see all guides regardless of folder. ### Ask Your AI The fastest way to find help is to just ask. In chat, try: - *"How do I scan a receipt?"* - *"What are beacons for?"* - *"How do I export my data?"* Your AI searches these guides automatically and gives you a tailored answer. ### Search Use the search bar in the Documents tab to search guide titles and content. The system uses semantic search — you don't need exact keywords, just describe what you're looking for. ## How Guides Are Organized Every guide follows a consistent structure: 1. **What It Does** — a plain-language explanation 2. **How to Use It** — step-by-step for each platform (iOS, Web, Chat, Claude Desktop) 3. **Tips & Tricks** — things you might not discover on your own 4. **Options** — settings and parameters you can adjust 5. **Known Limitations** — honest about what doesn't work yet 6. **Version History** — what changed and when Guides are tagged by topic (inventory, chat, location, etc.) and audience (user, admin, power-user) so you can find related guides easily. ## What's Covered | Area | What You'll Find | |------|-----------------| | **Getting Started** | First steps, app overview | | **Inventory** | Adding, managing, and tracking your things | | **Scanning** | Barcodes, receipts, photos, and smart scan | | **Chat & AI** | Talking to your assistant, choosing models, voice | | **Documents** | Receipts, manuals, files, and folders | | **Location** | Beacons, trails, and location-aware features | | **Account** | Subscriptions, privacy, data export | | **Power Features** | MCP tools, Claude Desktop, context tuning | | **Use Cases** | Shopping lists, travel planning, reports | ## These Docs Are Alive Don't Panic guides aren't written once and forgotten. They're updated by AI agents every time a feature changes. The version history at the bottom of each guide shows you exactly what changed and when. If you find something that's wrong or missing, just ask your AI — it can search, explain, and even help you create your own documents. Because Don't Panic is built on the same system you can use for shopping lists, travel itineraries, project notes, and anything else you want to write. The answer to life, the universe, and everything about ambientChat.ai is right here. And it's definitely not 42. ## Version History | Version | Date | What Changed | |---------|------|-------------| | 2 | 2026-06-07 | Terminology: "Admin Web" → "Web" (the web interface) | | 1 | 2026-03-01 | Initial guide | --- ## MCP Integration — Connecting AI Agents to Your Context URL: https://dont-panic.ambientchat.ai/article/mcp-integration-connecting-ai-agents-to-your-context Updated: 2026-04-13T00:16:29.033Z # MCP Integration — Connecting AI Agents to Your Context Your AI context doesn't have to stay trapped inside one app. With MCP, any AI agent — Claude Desktop, OpenClaw, or any compatible client — can tap into everything you've cataloged, scanned, and tracked in ambientChat. ## Why This Matters AI agents are increasingly autonomous — they browse the web, write code, manage your calendar, and control smart devices. But they're blind to your physical world. They don't know what's in your pantry, where you left your tools, or when your prescriptions expire. **ambientChat is context as a service for the physical world.** When you connect an agentic framework like OpenClaw to ambientChat, your agent gains awareness of your physical environment: - A cooking agent that knows exactly what ingredients you have and what's about to expire - A shopping agent that checks your inventory before adding items to the cart - A home management agent that knows which rooms have which items and when things need attention - An insurance agent that can list everything you own and what it's worth Without this context, agents guess. With it, they act on reality. ## What It Does MCP stands for **Model Context Protocol**. It's a standardized way for AI tools to access external data sources — in this case, your ambientChat data. When you connect any MCP client to ambientChat, that client gains the ability to search your inventory, read your documents, recall your conversation history, and even create new documents. The same context that powers your in-app chat experience becomes available to any connected agent. All tools respect your authentication — agents can only access **your** data, using **your** credentials. ## How to Connect ### OpenClaw (Telegram, Discord, and more) OpenClaw is an agentic framework that lets you interact with AI through messaging platforms like Telegram. Connecting it to ambientChat gives your Telegram bot full awareness of your physical world. **Prerequisites:** - A Mac, Linux box, or server running OpenClaw - Node.js installed (`npx` available in your terminal) - An ambientChat account with a password set **Setup (one command):** On the machine running OpenClaw, run: ``` openclaw mcp set ambientchat '{"command":"npx","args":["-y","mcp-remote","https://mcp.ambientchat.ai/mcp"]}' ``` **First-time authentication:** 1. After running the command, trigger any ambientChat tool through your OpenClaw interface (e.g., ask "what's in my inventory?" via Telegram) 2. A browser window opens on the OpenClaw host machine showing the ambientChat login page 3. Sign in with Google, Apple, or email/password 4. You'll see a **"Connected!"** confirmation — you can close that browser tab 5. Tokens are cached locally, so you won't need to sign in again for 30 days **That's it.** Your OpenClaw agent can now search your inventory, check expiry dates, read your documents, and more — all through natural conversation in Telegram. **Troubleshooting:** | Problem | Fix | |---------|-----| | "Safari Can't Connect to localhost" | The auth relay process died. Run `rm -rf ~/.mcp-auth/` and try again. If it persists, retry quickly — the process has a short timeout window. | | Browser doesn't open | Check that a default browser is configured on the OpenClaw host. You can also manually open the URL printed in the terminal. | | "Unknown client_id" error | Clear cached state: `rm -rf ~/.mcp-auth/` and retry. | | Tools stop working after ~30 days | Token expired. Trigger any tool to restart the auth flow. | ### Claude Desktop 1. Open **Claude Desktop** → Settings → **MCP Servers** 2. Add a new server with URL: `https://mcp.ambientchat.ai/mcp` 3. Authenticate with your ambientChat credentials when prompted 4. Claude Desktop discovers all available tools automatically ### Claude Code and Other MCP Clients Any MCP-compatible client can connect using the server URL: ``` https://mcp.ambientchat.ai/mcp ``` The server supports OAuth 2.1 with PKCE for authentication and the Streamable HTTP transport. Clients that support `mcp-remote` can use the same setup pattern as OpenClaw. ## Available Tools The MCP server exposes tools organized into seven categories: ### Inventory Tools | Tool | What It Does | |------|-------------| | `list_inventory` | List all items, optionally filtered by category | | `get_inventory_item` | Get full details of a specific item | | `search_inventory` | Semantic search — finds items by meaning ("things in my garage") | | `get_expiring_items` | Find items expiring within N days (default: 14) | | `update_inventory_item` | Edit any item field — name, brand, price, expiry, location, notes | | `trash_inventory_item` | Move an item to trash (requires confirmation) | | `restore_inventory_item` | Restore an item from trash | | `list_trash` | See what's in the trash | | `empty_trash` | Permanently delete everything in trash (requires confirmation) | | `regenerate_item_image` | Generate a fresh AI image for an item | ### Document Tools | Tool | What It Does | |------|-------------| | `list_folders` | List folders at a given level | | `get_folder` / `get_folder_tree` | Get folder details or full hierarchy | | `list_documents` | List documents in a folder | | `get_document` | Get document details, AI summary, and linked items | | `search_documents` / `search_documents_semantic` | Keyword or semantic search across documents | | `create_folder` | Create a new folder | | `move_document` | Move a document between folders | | `upload_document` | Upload a new document | ### Markdown Document Tools | Tool | What It Does | |------|-------------| | `create_markdown_document` | Create a new markdown document with optional YAML frontmatter | | `update_markdown_document` | Update a document — full or section-level | | `get_markdown_document` | Retrieve full content and metadata | | `list_markdown_documents` | List documents, filtered by folder or tags | | `search_markdown_content` | Semantic search across markdown content | ### Conversation & History Tools | Tool | What It Does | |------|-------------| | `journal_conversation` | Save a Q&A exchange to your searchable history | | `recall_history` | Search your past conversations | ### Export & Import Tools | Tool | What It Does | |------|-------------| | `export_user_data` | Export all your data as a ZIP archive | | `get_export_status` | Check export progress and get download URL | | `import_user_data` | Import data from an uploaded archive | ### Profile & Preferences | Tool | What It Does | |------|-------------| | `get_profile` / `update_profile` | View or edit your profile | | `get_voice_preferences` / `update_voice_preferences` | Manage AI voice settings | | `get_notification_preferences` | View notification settings | ### Confirmation Tools | Tool | What It Does | |------|-------------| | `list_pending_confirmations` | See actions awaiting approval | | `confirm_action` / `deny_action` | Approve or reject a pending action | ## Tips & Tricks - **Same context everywhere.** The search quality, semantic matching, and data access are identical whether you're using the mobile app, Claude Desktop, or OpenClaw. - **Great for desktop workflows.** Writing a report? Planning a meal? Having your full inventory accessible from your desktop means you don't need to switch to your phone. - **Combine tools naturally.** Ask the agent to search your inventory, then create a document summarizing what it found. Search, analyze, write, save — all in one conversation. - **Context flows to the best model.** OpenClaw lets you choose which LLM processes your request. Your ambientChat context follows — it's not locked to any single AI provider. ## Options | Setting | What It Does | Default | |---------|-------------|---------| | MCP Server URL | The endpoint your client connects to | `https://mcp.ambientchat.ai/mcp` | | Authentication | Your ambientChat login credentials | Required | | Confirmation timeout | Time to confirm destructive actions | 5 minutes | ## Known Limitations - **Browser required for first auth.** The OpenClaw host machine needs a browser to complete the initial OAuth flow. Headless servers need `mcp-remote`'s `--header` flag with a pre-obtained token. - **Image scanning is not available via MCP.** Use the mobile app for scanning, then access results via MCP. - **Rate limits apply.** MCP tool calls consume the same credits as in-app chat. - **Real-time sync is not instant.** If you scan something on your phone, it may take a few seconds before MCP tools see the new item. - **Token refresh is automatic** but requires a browser if the refresh token expires (after ~30 days). ## Version History | Version | Date | What Changed | |---------|------|-------------| | 2 | 2026-04-12 | Broadened to cover all MCP clients. Added OpenClaw setup guide, "context as a service" framing, troubleshooting table, profile/preference tools. | | 1 | 2026-03-01 | Initial guide (Claude Desktop only) |