# Avi — The AI assistant for real work. Exceptional at the everyday work of a company — email, meetings, deals, documents, and support. Avi works on screen where you can watch it, distills everything into a feed of what matters, and turns repeat work into automations that run on their own. - SOC 2 Type II Audited Team - Google CASA AL2 Certified - Zero Data Retention by AI Models Avi is invitation only, for now. [Continue with Google](https://cloud.avi.run/api/v1/auth/google?redirect_uri=https%3A%2F%2Fapp.avi.run) · [Build on Avi](https://avi.run/docs) ## The most powerful and visual apps in AI. Not connectors — full apps. Email, Calendar, Drive, CRM, Messages, Code and more, on your Google, Slack, HubSpot, and GitHub accounts — each with beautiful live panels, deep tools, its own data, automations, and voice controls. One click to connect, instantly usable by you and your AI. Connects with: Google, AWS, HubSpot, GitHub, Slack, Linear, X, Freshdesk, Resend. ## The AI-curated feed. Your whole world, minus the noise. Avi and your apps produce a constant stream of events. Avi's curation engine reads every one and distills them into relevant, high-signal updates. ## Automations on your payroll. Delegate the recurring work: automations run on schedules or react to events — triaging support, chasing renewals, watching costs — and report every outcome back to your feed. ## Build your own rich apps. Everything that makes an Avi app powerful — live panels, deep tools, its own data and automations — is yours to build with. Serverless hosting, data/file storage, and vector search come standard. Bring your workflows, ship in one deploy. ## White-glove setup. Live in days. One flat fee. Our expert team connects your apps, brings in your data, and stands up your first agents and automations — with a partner on call from day one. [Chat with us](https://meetings.avi.tools/3vpgQXK4_R1e) · [Continue with Google](https://cloud.avi.run/api/v1/auth/google?redirect_uri=https%3A%2F%2Fapp.avi.run) ## More about Avi - [Pricing](https://avi.run/pricing.md) — $79 per person per month billed annually, or $99 monthly. - [Documentation](https://avi.run/docs.md) — guides for every part of Avi. - [Public API](https://avi.run/docs/api.md) — Avi's docs, pricing and trust details as JSON, described by OpenAPI. - [Trust](https://avi.run/trust.md) — certifications, AI data retention, encryption, and subprocessors. - [About](https://avi.run/about.md) · [Contact](https://avi.run/contact.md) · [llms.txt](https://avi.run/llms.txt) --- # Getting Started Avi is the AI assistant for real work. It works inside projects you organize around whatever you're doing — a company, a side project, a research area. You chat with it, and it can run tools to read and change real things: files, notes, GitHub issues, and more. It can also set up automations that keep working on a schedule after the chat ends. ## 1. Sign up Head to [avi.run](https://avi.run) and sign in with Google. Avi is currently **invite-only**, so a new sign-in lands on the waitlist. There are two ways in: - **Enter an invite code** on the waitlist screen. - **Accept an invitation** from someone already using Avi. Invitations sent to your email address show up right on the waitlist screen, and the link in the invite email works too. Sign in with the address the invitation was sent to. Once you're in, Avi creates your **personal account**, a **personal organization**, and a private **Personal project** you can use right away. You start with 1,500 free credits — no card required — and connecting your first account (Google) adds **1,500 more**; see [Billing](/docs/billing). ## 2. Pick your apps — Avi sets itself up The first time you open your Personal project, Avi asks what it should take care of — Email, Calendar, Drive, Contacts, Messages, and more, each a card with its own toggle. Pick the ones you want and sign in once per service; the moment a connection completes, those apps configure themselves: Email shows your Gmail, Calendar syncs your calendars, Drive brings in your files. No per-app setup. Connecting also adds the **1,500 free credits** mentioned above. Your data stays yours: neither Avi nor its AI model providers train AI models on it, it's processed only to run Avi for you, and our team doesn't read it except with your permission, to investigate a security issue, or when the law requires. You can disconnect any account from the settings of the app that uses it, and you can skip the whole step — every app works on its own, and each one offers to connect its service right where you'd need it. ## 3. Open your first project After sign-in you land in the web app at [app.avi.run](https://app.avi.run). Your Personal project is already created. Type a message in the chat to start working with the agent. Simple ways to get oriented: - "What can you do?" - "Take notes on the following plan: ..." - "Email me the weather every morning." ## 4. Invite teammates (optional) If you want other people in the same workspace, create a new **org** and invite teammates. Each member gets their own private Personal project inside the org, and anyone in it can make agents the org owns. See [Organizations & Projects](/docs/orgs-and-projects). ## 5. Optional: add Avi to your phone's home screen On your phone, open [app.avi.run](https://app.avi.run) and add it to your home screen (on iPhone: Share → **Add to Home Screen**; on Android: browser menu → **Add to Home screen** / **Install**). You get the Avi icon on your home screen, and it opens full screen like a native app. ## Key ideas - **Org** — a workspace you own or belong to. Your personal org is created automatically. - **Home feed** — what you see when nothing else is open: one row per topic (a deal, a feature, an incident, one of your tasks), newest activity first, each showing its latest development. Click a row to open its page — anything waiting on you at the top, then its whole history; **back** returns you to the feed. - **Project** — where all of Avi's work lives: chat history, tasks, notes, files, instructions. - **Agent** — a project your org owns, with its own name, picture, handle and people; its automations are its work. See [Agents](/docs/agents). - **Tool** — something the agent can do for you (send an email, search the web, read a file). You control which tools are on in each project. - **Task** — a to-do item you and the agent track inside a project. - **Automation** — work Avi runs in the background: once, on a schedule, or whenever something happens, reporting its progress as it goes. - **Wiki** — your org's shared knowledge: company facts, skills (step-by-step playbooks the agent follows) and a page for each person. - **App** — a bundle of related tools (e.g. the Code app, the CRM app). Turn apps on per project. Ready to go deeper? Start with [Organizations & Projects](/docs/orgs-and-projects). --- # Organizations & Projects Avi is organized as **accounts** → **orgs** → **projects**. You don't need to think about most of this day-to-day, but knowing the pieces helps when you collaborate or want to keep work separate. ## Accounts An **account** is the billing unit. When you sign up, you get a personal account automatically. Your trial credits and, later, your subscription live on the account. See [Billing](/docs/billing). ## Organizations (orgs) An **org** is a workspace. Every account has one **Personal org** created at signup. You can also create or join **shared orgs** to collaborate. - **Personal org** — always yours and can't be deleted. It gets a random name at signup (something like *Amber Falcon 314*); rename it any time from its settings. Your personal projects live here by default. - **Shared orgs** — created by you or someone who invited you. Orgs have members with roles: - **Owner** — full control, including billing and member management. - **Admin** — can manage members and change settings. Can't manage billing. - **Member** — has their own private Personal project in the org and can make agents the org owns. Each member has one private **Personal** project — nobody else in the org, owners and admins included, can see it — and can make **agents**, projects the org owns, that the people on them share. See [Agents](/docs/agents). ## Projects A **project** is the container for a body of work: chat history, tasks, notes, files, instructions. Every project has its own settings — its own tools enabled, its own agent instructions, its own conversation. There are two kinds: your own **Personal** project in each org, and **agents** the org owns. ### Personal projects Every user in an org has a private project called **Personal**. Only you can see it, read from it, or chat in it — not even org owners or admins can. It's the right place for personal work inside a shared org (e.g. your own to-dos, your own notes) without worrying about other people seeing it. ### Agents The other kind of project is an **agent**: a project the org owns, with a name, a picture, a handle and people at two roles — members, who see it and talk to it, and managers, who change it. Its automations are its work, and the accounts it connects are the team's. Make one from the org menu (**New agent…**). See [Agents](/docs/agents). ### Per-project agent settings Each project can have: - **Instructions** — persistent guidance the agent follows in this project. Good for domain-specific rules, style preferences, or constraints. ("Always respond in English." "This is a Node.js project using ESM." "Never touch the `prod` branch.") - **Enabled apps** — which bundles of tools the agent has access to. See [Apps](/docs/using-apps). - **Tool permissions** — individual tools can be turned off even if their app is enabled, for finer control. - **AI model** — override the org-level default. See [AI Models](/docs/models). ## Inviting teammates From an org's settings, invite people by email. They receive a link that expires in 7 days. Accepting joins them to the org. Each new org member gets their own private Personal project inside that org automatically. --- # Chatting with Your Agent Each project has one conversation with the agent. Open a project and start typing — that's it. ## How it works - Each message you send can trigger the agent to **call tools** — searching the web, reading files, writing notes, creating tasks, or whatever else you've enabled in the project. - When the agent **searches**, one search covers your project's own data at once — updates, files, and everything your apps keep here — and reaches into a connected app's own search (your CRM, mailbox, chat workspace, cloud drive) when your question points there or when you ask it to search everything. It can look for several things in a single search, and every result says which app it came from. - The agent can chain multiple tool calls together to complete a request. You'll see each step as it happens. - Conversations are **persistent** — the agent remembers what you said and did in the project, across sessions. When a conversation gets long it's automatically summarized so older context stays available without slowing things down. - Responses are **resilient** — if you close the tab, put your laptop to sleep, or lose connection mid-response, the agent keeps working. Reopen the chat and you'll rejoin the live response (or find it finished and waiting). Only the Stop button cancels a run. - Links the agent shares on their own line show up as **link cards** — a clickable box with the destination's icon and a readable title. Cards into Avi (an app panel, a settings page) open right in place; external links open in a new tab. A card for a file or a folder always shows that file's or folder's own name. ## The agent sees what you're looking at When you chat with a panel open beside the conversation, the agent knows which panel is focused and what it's showing: an open email or note and how it begins, or which list you're on. Ask about it directly ("what's this note about?", "reply to this") without pasting the content in — typed or spoken. In a voice session the agent also sees the rows and buttons on screen, so it can act on them ("open the third one", "close this"). A few things are handled on the spot without a round trip: navigation ("open my contacts", "go back", "scroll down"), and the view zoom — "zoom in", "zoom out", "bigger", "smaller", "zoom to 150 percent", "reset zoom" — which scales the whole window in 10% steps between 50% and 200% and is remembered per browser. ## Getting good results - **Be concrete.** "Summarize today's GitHub notifications and post an update" beats "check GitHub." - **Add project instructions** for things that apply every time (see [Projects](/docs/orgs-and-projects#per-project-agent-settings)). You only have to say them once. - **Write a skill in the wiki** when you have a procedure the agent should follow — a multi-step workflow, a style guide, a specific prompt template. See [Wiki](/docs/wiki). - **Pick the right model** for what you're doing. More capable models use more credits but do better on harder reasoning. See [AI Models](/docs/models). ## Queueing messages You don't have to wait for the agent to finish before sending your next message. If you send while it's still responding, the message is **queued** — it shows up below the response with a "Queued" label and sends automatically, in order, as soon as the agent finishes. - Queue as many messages as you like; they send one at a time. - Changed your mind? Click the **X** next to a queued message to cancel it before it sends. - Queued messages live in your browser tab — closing the tab discards any that haven't sent yet. ## Bigger work runs in the background Avi does most work right in the conversation, and that includes Word documents and Excel workbooks: drafting a quote from your template, changing wording or a table, redlining a contract, building a budget, adding rows and formulas to a spreadsheet. It brings its Word or Excel know-how to the request and answers in the same reply. Work that would keep you waiting runs in the background instead, as a [one-time automation](/docs/background-agents#one-time-automations): - **Research** takes a question that needs real looking. - **Anything long** that you ask for once, such as going through a folder of files or comparing several vendors. Avi says so in one line, and the conversation stays free for your next message. A card appears in the chat and shows each step while the work runs. When it is done, the answer appears at the end of that message: the short version first, with **Show more** for the specifics, and a tile for each file it created or changed. In voice mode you hear the short version, and a file it made opens on screen. It is in your Automations list while it works, and in History once it is done; its result is also a line on the project's single **One-time automations** row in Updates, so you can find it again later. Two kinds of request wait on other people for days, so Avi sets up an [automation](/docs/background-agents#meetings) for each one: - **Meetings** books meetings with other people. - **Requests** collects things people owe you. Their card in the chat keeps itself current, and they report to [Updates](/docs/updates) as they go. Ask about any result whenever you like and Avi picks it up from there. Avi creates an automation of your own only when you ask for one or the work is ongoing, such as every morning or whenever something happens. ## Seeing what Avi found When seeing beats reading — product photos, pages worth opening, a side-by-side comparison, where each of several things stands — Avi shows it: the things it found, each with its picture, name and a line about it, plus a comparison table and a short note, together. In a written chat it appears right in the reply; in a voice session it shows on your home screen instead (see below). Things that live in an app — an email, a file, a deal — are shown by opening them in that app instead. ## Stopping an in-flight response If the agent starts doing something you didn't want, use the Stop button in the chat. It interrupts the current run immediately. If you have messages queued, the next one sends once the run stops — cancel them first if you don't want that. In voice mode, if Avi starts on your request while you are still talking, just keep going: Avi works out that the rest belongs to the same request. If it hasn't done anything yet it starts over with the whole thing; if it has already made something, it applies what you added as a change to that work rather than doing it twice. Something unrelated runs as its own request. Say "repeat that" or "say that again" to hear the last thing Avi said once more. Background noise that contains no words is ignored, and so is a stray "um" or "okay" on its own. In voice mode, say "stop", "don't", or "wait" to stop everything — the talking and every request in progress. To only make Avi stop talking, say "stop talking", "be quiet" or "don't talk": the reply is cut, but every request keeps running and you hear its answer when it's done. Screen commands and new requests work while Avi is talking, without interrupting it. Say "mute" to mute the microphone without leaving voice mode — it works while Avi is working or talking too, and whatever Avi is doing carries on — and "unmute" to bring it back. While muted, Avi ignores everything it hears except "unmute". The voice options menu under the orb has the same Mute / Unmute item, and a **Microphone** entry that opens a list of your inputs (available whether or not voice mode is on): "System default" follows your computer's sound settings, or pick a specific microphone to use in this browser; during a session the list also shows which microphone Avi is listening to right now. If the microphone in use is unplugged, Avi switches to what's left and says so. You can also change the AI model by voice: "switch to Sonnet", "use the Haiku model", "change the model to Opus five" — you don't need to pronounce the name perfectly, and if two models share a name Avi asks which one. In voice mode, every request you speak runs in the background: a ring around the orb shows it's registered, a soft pop plays when you add a request while another is still running, a small circle on the orb shows how many requests are still owed to you — running, or finished and waiting to be read — and Avi is ready for your next one straight away — you can keep talking, even while it's reading you an answer. Whatever it creates or edits for you — a draft, an event, a note, a file — opens on screen the moment it's written. When a request is done, Avi says its answer at the next quiet moment; if the request was to write or change something and it went as asked, it says nothing at all — the app's own chime and the change on screen are the confirmation — unless you also asked it something in the same breath, in which case it reads you the answer. Ask if you want the details. Independent requests run at the same time, and each answers when it is done; a request that builds on the one before it waits for that one to finish. "Stop" stops all of them — the one running, any waiting behind it, and whatever Avi is saying — and so do "stop all jobs", "stop everything", "cancel all requests", and "clear the queue". These are handled by the app on the spot and never reach the assistant; when more than one request was stopped, Avi says "Stopped everything." Say "use the default model" to go back to your org's default. While Avi is working on a spoken request or reading its reply, only screen commands are taken ("open email", "scroll down", "go back"); anything else you say — or any background noise it hears — is ignored without comment, and nothing is queued behind the current request. Voice stays in the project you're in; switch projects from the project menu. ## When a message doesn't go through Sometimes a turn fails outright — the model provider is overloaded, the conversation has outgrown the model's context, or something you attached can't be read. When that happens the chat tells you what went wrong in place, with the underlying error underneath it, instead of leaving a blank reply. Most of these clear on a retry; a conversation that's grown too long is the one to clear. ## Sounds Avi plays a short sound when a reply finishes while you're away from the window, when something fails, when a new update lands in your feed, and when voice mode starts or stops. In voice mode, where your eyes may be elsewhere, it also sounds when something succeeds (an email sent, a draft created), when a confirmation needs you, and when the record you're looking at changes underneath you; in written mode those moments are already on screen, so they stay silent. Turn them off or on for the browser you're in under **Settings → General → Sounds**. The choice is per browser, so your phone and your laptop can differ. You can also ask for "some music" in the conversation, spoken or typed, and quiet background music starts and keeps playing whether you are talking or typing; it fades under every voice. "Pause the music", "stop the music", "next track", "skip this song", "quieter", "louder", "set the music to 20 percent", and "what's playing" control it, and it stops when you leave the voice session. "Next track" and "skip the song" only mean the music while it is on; otherwise they reach Avi like anything else you say. Anything Avi understands about the music it can do for you as well, so "put on something calm" or "make the music quieter" in writing works too. Each "louder" or "quieter" is a clear step, and 5 percent is close to silent. Hover the music note beside the orb to see what is playing, pause or stop it, and set the volume. When the music comes from a licensed station, the station decides whether a song can be skipped and there is no going back to the previous one; Avi tells you when it can't. Avi knows when music is on and what's playing, so you can ask about it in the conversation too. When you ask Avi to show you something in a voice session, what it found takes the place of your updates on the home screen, laid out the same way it is in the conversation, with each page's own picture and icon where the page provides them. Press the back arrow, or say "back" or "close that", and your updates return. ## Clearing history You can clear a conversation's history from the project's chat menu. Useful if you want to start fresh or if the agent's gone off on a tangent. Clearing takes effect everywhere at once — the conversation history lives on the server, so any other tab, device, or voice session on the same conversation starts from the cleared state on its next message. Nothing carries the old history forward. ## Task conversations Tasks don't run on their own, and they don't have their own chats — talk about a task in the project chat (`+`-mention it to point the agent straight at it). For work that should happen on a schedule, the agent sets up an [automation](/docs/background-agents). See [Tasks](/docs/tasks). --- # Tasks Tasks are to-do items — things you or the agent want to track inside a project. Use them for anything with a "done" state: work to get to later, steps in a bigger effort, or items the agent creates while working for you. Tasks are a first-party **app** that is always on in every project — there's nothing to enable, and its panel sits on the rail like any other. Tasks don't run on their own. If you want Avi to *do* something on a schedule or in the background, ask it in chat and it will set up an [automation](/docs/background-agents) — tasks are for tracking, automations are for running. ## Creating a task Open the **Tasks** panel from the rail and click **New task**. The new task opens beside the list, where tasks open. Fill in its name, status, priority and labels, then press **Create**. You can also just ask the agent ("add a task to review the Q3 numbers") — it creates and updates tasks with the same fields you see. ## Fields - **Name** — what the task is. - **Notes** — free-form markdown: persistent context about the task (links, requirements, decisions). Yours to own — nothing writes them automatically. - **Priority** — every task has one, from 1 to 4, and higher means more important: **4 Urgent**, **3 High**, **2 Medium**, **1 Low**. When the agent creates a task it judges the priority from what you said ("an urgent task to…", "when you get a chance…"); with nothing to go on, a task starts at 1. - **Status** — **Incomplete**, **In Progress**, **Complete**, or **Cancelled**. Change it from the task's row in the list, or on the task's page. - **Labels** — any of the project's [labels](#labels), such as "Errands" or "Finance". Add and remove them on the task's page. The list has three columns: **Task**, **Status** and **Priority**. A task's labels show in small type under its name. You can change a task's status or priority right from its row, without opening it. Priority shows as four signal bars: **Urgent** lights all four in red, **High** three in orange, **Medium** two in yellow, and **Low** one in grey. The list shows your unfinished work, meaning Incomplete and In Progress tasks, with the most important first and the newest first within each level. Click the **Task**, **Status** or **Priority** header to sort by it, and click again to reverse the order. Sorted by status, each status still lists the most important first. You can also say "sort by status" or "sort by name". Use the **Filter** menu to show any mix of the four statuses, or only tasks with certain labels (a task shows if it has any of the labels you pick); **Clear filters** shows every task. On a task's page, status, priority and labels save the moment you change them. The name and notes save when you press **Save**. Tasks used to have due dates. Tasks created before priorities got a priority from their due date: overdue became Urgent, due within a week High, due within a month Medium, and everything else Low. The old date stays on the task for reference. Every task also carries a `metadata` bag your apps can write to — see [Data Types](/docs/data-types). ## Subtasks A task can have subtasks — useful for breaking a larger piece of work into steps, or for letting the agent lay out a checklist beneath a parent task. Click a task's **Subtasks** tab to see its subtasks as a list of their own, which works like the main list. It has the same search box, the same filters (Status and Labels), sorting by column, and the same Status and Priority controls on each row. The path at the top reads Tasks / task / Subtasks. Click the task's name there, or the back arrow, to return to the task. **New subtask** opens a new subtask in the same pane. When you open a subtask, the list beside it shows its parent's subtasks, with the same search and filters, and the path reads Tasks / task / Subtasks / subtask. Closing a subtask (the **×**, or saying "close") takes you back to that subtasks list; click **Tasks** in the path for the full task list. A subtask's page shows **Subtask of** and its parent's name, and the path at the top reads Tasks / parent / subtask. Click the parent to go back to it. Rules worth knowing: - **Subtasks go one level deep.** A subtask can't have subtasks of its own, and a task that has subtasks can't be moved under another task. - **Completing a parent never completes its children.** They're separate to-dos. - **Deleting a task deletes its subtasks with it.** ## Labels Labels are your own way to group tasks, such as **Errands**, **Finance** or **Waiting on someone**. A task can have any number of them. To manage them, click the **⋮** options button next to **New task** and choose **Manage labels**. The labels page lists every label with its description. It works like the task list: click a label and it opens beside the list. From there you can: - **Create a label** with **New label**. Give it a name, a description and a color, then press **Create**. - **Edit a label**: change its name, description or color, then press **Save**. - **Delete a label** with the trash button at the bottom of an open label. The label comes off every task that had it, and the tasks themselves stay. **Write a description.** Avi reads it to decide when a label fits. For example, "anything I have to leave the house for" makes Errands useful to the agent. **Avi labels new tasks automatically.** When Avi adds a task for you, whether in chat, from an automation or when you say "add a subtask …", it applies the labels whose descriptions fit, unless you told it which labels to use. It uses only the labels you have made and doesn't invent new ones unless you ask. If a label doesn't fit, take it off on the task's page or say "remove the errands label". Tasks you create with **New task** keep exactly the labels you picked. Each label has a color: blue, green, orange, purple, red, yellow or grey. These are the same hues the priorities and badges use. A new label takes the next color that hasn't been used much yet, and you can change it any time. On a task's page, the **Labels** field shows the task's labels. Click **Add label** to attach one, and click the **×** next to a label to take it off. If something can't be saved, the reason shows at the top of the task or label you have open, and it clears itself after a few seconds. ## Assigning and sharing Your tasks are yours: nobody else in the org sees them unless you hand them over. There are two ways to do that. - **Assign a task** to one or more people in your org. They become responsible for it: it shows up in *their* Tasks panel, they can start, complete and edit it, and they're told about it. On a task's page, use **Assign** under **People** to pick people, or ask Avi: "assign the proposal to Matt", "give the tax return to Sam". You can assign a task to yourself too, and a new task can be assigned as you create it. - **Share a task** with people, or with everyone in the org, without making anyone responsible. Under **People** on the task's page, use **Share** to pick a person (they can view it), or turn on the **Everyone in the org** toggle next to it (everyone can view it). It's off unless you turn it on. Ask Avi the same way: "share the launch checklist with Sam", "share it with the whole org". A task's **People** section lists everyone who has it, once each, with what they are: **Owner**, **Assigned** (responsible for it, so they can edit it), **Can view** or **Can edit** (shared, not responsible). On your own task you manage it there. On someone else's task the list is read-only, and one line at the top says whose task it is and what you are on it, such as "Austen Collins's task · assigned to you". A task that someone assigned or shared to you appears in your list alongside your own, with the owner's name under it. If you can edit it, changes you make are made to *their* task, so you both see the same thing. If it was shared with you to view, its page is read-only. Only the task's owner can delete it, move it under another task, label it, or add subtasks under it. Labels are each person's own vocabulary, so a task's labels show only in its owner's list. To change what someone you shared with can do, pick **Can view** or **Can edit** next to their name, or say "set Sam's access to edit". Sharing covers the task's subtasks too, at the same level, and a subtask the owner adds later is shared the same way. A subtask shows who it's shared with but has no sharing controls of its own: it says "Sharing follows the parent task", with a link to the parent task, where you change it. A subtask can still be assigned to someone on its own. Taking someone off a task (unassigning them) takes their access with it. To let them keep seeing it, share it with them instead. Someone assigned to a task can already edit it, so to make them view-only, unassign them first and then share it with them. Use the **People** filter to show only tasks **assigned to me**, **shared with me**, or **my own**. Every task's row shows who it's assigned to, by name. ## Associated records A task can have associated records — the things it's about: a CRM deal, contact or company, an email thread, a message, a Drive file, a calendar event, or another task. Ask Avi, for example "associate this task with the Acme deal", or "make a task to follow up on this email" while you have the email open. A task holds up to 10 associated records. They show as small tags with each record's app icon. In the task list and a task's subtasks list, a task shows its first two and "+N" for the rest. On a task's **Details** tab, every one is listed under **Associated records**, below **People**. Click one to open the record in its own app. To take one off, click the **×** next to it (you need to be able to edit the task). Associating a record with a task never gives anyone access to that record. People who can see the task see its title, but opening the record still needs access to it. ## Finding tasks The panel has a search box at the top: type to filter to tasks whose **name or notes** contain what you typed. Tasks also turn up in Avi's global search, and you can `+`-mention one in chat to point the agent at it. ## Saying it out loud In voice mode the Tasks panel listens for the same things you would click: - **Find a task** — "open the third task", "open the invoices one", "search for tax", "search tasks for invoices", "clear the search". - **Update any listed task** — "mark groceries as complete", "change the tax return to priority 3", "set invoices to done", "move the offsite to in progress", "update the lease to urgent", "make taxes high priority". You don't have to say punctuation, and near forms count ("follow up" for "Follow-up", "setup" for "Set up"); one misheard word in a longer name is forgiven. Anything that isn't a status or priority change for a task on screen — "update the notes of this task with the latest…" — goes to Avi as a normal request. Say enough of the name to pick one task; if two tasks fit, Avi asks for more of the name instead of guessing. - **Label tasks** — "tag groceries errands", "tag the tax return as finance", "add the errands label to groceries", "put the finance tag on the invoices", "remove the errands label from groceries", "untag the tax return finance". With a task open: "tag it errands", "add the finance label", "remove the errands label". To use "add", "put" or "remove", say the word "label" or "tag". "Tag" and "untag" work with the name alone. - **Manage labels** — "manage labels" or "show labels" opens the labels page. You can also say "new label receipts" or "create a label called Avi with the description our product" from anywhere in the panel. If the name can't be saved as said, for example because it's longer than 40 characters, the new label opens filled in so you can fix it. On the labels page: "make errands red", "change the finance label to purple", "open the errands label", "delete the receipts label" (Avi asks you to confirm), "back to tasks". - **Assign tasks** — "assign groceries to Matt", "give the tax return to Sam Lee", "delegate the lease to Ryan", "assign the third task to me", "unassign Matt from groceries". "Reassign the tax return to Sam" hands it to Sam and takes everyone else off. With a task open: "assign to Matt", "assign it to me", "reassign this to Sam". A first or last name works when only one person has it; if two people fit, Avi asks which. - **Share tasks** — "share groceries with Sam", "invite Matt to the tax return", "share the tax return with everyone" (or "with the team"), "unshare groceries from Sam", "stop sharing it with everyone". With a task open: "share with Matt", "share this with everyone", or just "everyone can see this". A share lets them view it, the same as picking them under **People**. Only the task's owner can share it. - **Narrow the list** — "only complete", "only in progress", "filter by cancelled", "only incomplete", "filter status to complete and cancelled", "filter by errands", "only assigned to me", "filter by shared with me", "only my own", "clear the filters". Filter words narrow the list; they never change a task. - **With a task open** — "set the status to in progress", "change status to cancelled", "start it", "mark it in progress", "mark it done", "reopen it", "cancel it"; "set the priority to high", "set priority to 4", "make it urgent", "low priority", "bump it up", "lower the priority". "Change the status" or "change the priority" opens the picker so you can choose. - **Edit and add** — "rename the task to …", "new subtask" or "add a subtask" (opens one to fill in; to name it in one go, ask Avi: "add a subtask to buy milk"), "new task", "type in the name …" then "save" or "create it", and "delete the task" (Avi asks you to confirm). - **Get around a task** — "show subtasks", "open subtasks" or "list the subtasks" opens its subtasks; "details" goes back to the task. On a subtask, "go to the parent" or "parent task" opens the task it belongs to. "edit notes" opens the Notes tab. A voice command runs on its own only when the whole sentence is the command; anything longer, or a question, goes to Avi. In voice mode, a new task plays the success chime — one you create, a subtask you add, or one Avi creates for you when it shows up in the Tasks panel. ## In the feed Your tasks are topics in your [Updates](/docs/updates) feed. A task never appears there on its own. It shows up when something happens that is the task's work: an email from the vendor it names, the document it was waiting on, someone asking how it's going. That activity lands on the task itself, titled by the task's name, instead of on a separate topic. If a topic about the same work already exists, it is folded into the task, so you see one row named for the task. Later activity about it adds to the same topic. Completing or reopening the task shows there too, and renaming the task renames the topic. Open the task from the topic with **Open task**. ## Want it to happen automatically? Tell the agent in chat — "check the homepage every 15 minutes and page me if it's down", "every Monday morning summarize last week's GitHub issues". It will set up an [automation](/docs/background-agents) that runs on that schedule and reports progress to the Automations panel. --- # Contacts Contacts is the project's address book: the people this project deals with, with their names, email addresses, phone numbers, company, title, tags, and notes. It's a first-party **app** that is always on in every project — there's nothing to enable, and its panel sits on the rail like any other. It works with nothing connected, and it syncs with Google Contacts when you point it there. This is the *project's* address book. The **CRM** app's people are a different thing — your org's shared book of business, with companies, pipelines, and deals — and the two are deliberately separate. ## Where your contacts come from Contacts has a **Source** setting with two values: - **Standalone** (the default) — Avi's own contact list. Nothing to connect. - **Google Contacts** — the Google account you bind in the same settings. The source is a **mode, not a blend**: only the active source's contacts appear in the panel, in the agent's tools, and in search. An address book that silently mixes two books is one you can't trust. Switching sources **hides, never deletes**. The other book stays exactly where it is and comes back the moment you switch back. Disconnecting a Google account doesn't change your data either — only ongoing sync stops. Change the source in **Project Settings → Apps → Contacts**. The panel's Settings tab shows what's active and when Google was last checked. ### Syncing with Google The first pass loads your whole Google contact list; after that a pass every ten minutes pulls just what changed. While Google is the active source, creating or editing a contact writes to Google first and only then mirrors locally — if Google refuses, the write fails and tells you why, instead of quietly leaving you with two different truths. Two things stay local: **notes** and **tags**. Google never sees them. Google's auto-saved "other contacts" — the addresses it keeps every time you mail someone new — are never synced. Only your real contact list comes across. ## Notes are yours A contact's **notes** are free-form prose that a person writes. Avi does not maintain them: no enrichment, no agent, no sync pass, and no background job writes them. **What changed:** Avi used to keep an AI-written "context" block on every contact and refresh it in the background. That's gone. When the Contacts app shipped, each contact's existing context was appended to that contact's notes exactly once, under a dated marker — so nothing was lost, and nothing has been written there since. Contacts are also no longer created behind your back. Apps that read your email, Slack, or X used to mint a contact for every new person they saw; they don't any more. Contacts are the people you (or the agent, when you ask) put in the book. ## Finding people The panel's search box searches **name, email, company, and title**. An email address also matches a person's secondary addresses, so looking someone up by the address they actually wrote from finds them. Contacts turn up in Avi's global search, and typing `@` in chat offers them alongside your project handles. ## Duplicates A contact's primary email is the duplicate key within a source. Creating a second contact with an address already in the book is refused, and the refusal names the existing person — so the agent updates them instead of quietly creating a second row. ## Fields Name, primary and secondary emails, phones, company, title, website, addresses, social identities, tags, and notes — plus a `metadata` bag your apps can write to (see [Data Types](/docs/data-types)). --- # Wiki The **Wiki** is your organization's shared knowledge. Everyone in the org reads it, and so does every agent and every person's Avi, so the same facts and the same playbooks steer all of them. It is in every project and every [agent](/docs/agents). ## Three kinds of page - **Knowledge**: what is true about the company, such as products, pricing, policies, your voice, and where things live. - **Skills**: how a kind of work is done, step by step. Agents follow these playbooks when the work comes up. Your own skills live only here. - **People**: one page per person in the org: their role, what they own, what they approve, and how to reach them. Everyone gets one when they join. ## How Avi uses it When a topic comes up, Avi searches the wiki and reads the page it needs before it answers or acts, instead of guessing. Ask it things like "what's our refund window?" or "who approves discounts?" ## Owners - Every page has **one owner**. Only they change it, delete it, and choose who can read it. A person page belongs to its person. - Your Avi can create, change and delete your pages when you ask it ("update the pricing page, the Team plan is $60 now", "move the onboarding skill to Knowledge"). It asks before deleting, and it can't change anyone else's. - Want a change to someone else's page? Ask its owner. - A page whose owner left the org has **Become the owner** for anyone who can read it. ## Who can read it A page is either readable by **everyone in the org** (the default) or **private**. The owner switches it under **Sharing**. A private page stays in the project it was made private in: in your own project only you see it; in an agent's, only that agent's people do. ## Good to know - Deleting a page is permanent and always asks first. - Skills written before the wiki are private skill pages in the project that had them. - Avi also has **Native Skills** built in: how to work on Word documents, Excel workbooks, PDFs and e-signatures, keep this wiki, set up automations, research, arrange meetings, collect requests, and the Code app's Spec, Build and Review. They come with Avi, are not wiki pages, and can't be edited. See [Native Skills](/docs/background-agents#native-skills-work-avi-knows-how-to-do). --- # Automations Automations are standing work Avi sets up for you. Each one is a prompt plus an optional schedule or event trigger: it runs on its own, without tying up your chat, and reports progress as it works. They're how Avi does anything recurring, long-running, deferred, or reactive. Two words carry the whole model: - An **automation** is the standing work: its instructions, tools, triggers, budget — and its own working state and **status**. It's active, it needs you, it succeeded, it failed, or you stopped it. - A **session** is one *sitting* — what one wake did, and any replies to it. Sessions are mechanical: one finishes, errors, times out, hits a limit, or is stopped; the automation's verdict never hangs on a single sitting. When one piece of work should fan out into several — one per customer, per repo, per email thread — each is its own automation, with its own thread and its own verdict. One piece of work, one automation, one story. Work like that belongs in an [agent](/docs/agents): a project the org owns, where "onboard Acme" sets up Acme's automation and an automation that finds new customers sets up each one's. ## Creating one You don't build automations by hand — you ask for them in chat: - "Every morning at 7am, email me a summary of new GitHub issues." - "Check if our homepage is up every 15 minutes; page me if not." - "Keep an eye on these five competitors and tell me whenever one changes its pricing." - "Whenever a PR comes in on my repo, triage it — if it needs my review, make a task for it." - "Whenever my grandmother emails me, draft a warm reply." - "Ask everyone on the team for their shirt size today, then nudge whoever hasn't replied each morning until they all have." Avi sets up a standing automation only when you ask for one or the work is ongoing: later, on a schedule, whenever something happens, or until other people reply. A one-off question or document never becomes a standing automation. Avi answers it in the conversation, or hands it to a [one-time automation](#one-time-automations) in the background, whose answer comes back in the chat. **The result finds you — without cluttering the chat.** An automation never posts into your conversation. The card Avi put in the chat when it started the automation keeps itself current: the automation's name, where things stand, and — when it finishes — how it ended and what came of it. The full result lands in Updates, and the automation's own page has everything. You can follow up in chat directly ("ok, fix the second one") — Avi knows where each automation it started stands. In a voice session Avi tells you in one sentence when it finishes — it waits for a quiet moment and never talks over you — and "tell me more" gets you the rest. Automations that run on a schedule or a trigger report to Updates as they go. When a result is worth seeing — photos, pages it compared, a side-by-side table — the automation shows it on its update in your feed, not just describes it. The agent decides whether to answer you right away or hand the work to an automation, sets the schedule, and confirms — and the chat stays free while the automation works: progress lands in [Updates](/docs/updates), and you can ask for a status check any time. There's deliberately no form to fill in: describe what you want and when, and adjust it the same way ("make that weekly instead", "stop the issue digest"). **From chat**, Avi picks the tools the automation's work needs and switches them on when it sets it up, so it starts working on its first session (see [Tool access](#tool-access)). **From the panel**, **New** creates a draft — a dormant automation that opens on its **Setup** tab, where you fill in its name, when it runs, its instructions and tools, then press **Start**. Nothing runs and no trigger fires until you start it. ## Pre-made automations Some work is common enough that you shouldn't have to write it from a blank page. **New** in the Automations panel opens a picker: start from scratch, or pick a pre-made automation. It is added at once and opens on its **Setup**: its stages in the chart, its instructions a tab away. Change what you like, or nothing. It is added active with no triggers of its own: give it a schedule or triggers there or in chat, or message it, to set it working. A pre-made automation is an ordinary automation that arrives already written, and nothing more. Its **General** instructions and each stage's instructions come filled in with short, plain guidelines in your words, and what you read on the Instructions tab is everything it follows: there is no hidden playbook underneath, and no questions to answer. Edit a line and that is what it does. It also arrives with the tools its work needs switched on, such as your email, Drive and calendar, as far as your project has them. They show on its **Tools** tab like any other. The list offers: - **Client onboarding** — welcome a new client, set up their folder and contacts, get the engagement letter e-signed, take in what you need and book the kickoff, and hand them over ready to work with. The folder exists before the letter, and nothing is collected until the letter is signed. - **Document collection** — ask people for files, chase them, review what arrives, and file it in Drive. Each is written for one client or one collection. A project holds one of each — picking it again opens the one you have — so for one per client, make it a [group](#groups) (**⋮** → **Make it a group…**) in the [agent](/docs/agents) that looks after them, and add each client to it with who they are: their email address or domain, and what is known so far. ## The Curator Every project has one automation you didn't create: the **Curator**, which keeps the project's [Updates feed](/docs/updates#the-curator). It's always on, in every project, including new ones. - **It can't be stopped, archived or deleted.** Its menu has none of those, and Avi refuses them in chat too. - **Its setup is Avi's.** Its instructions, model and tools are kept up to date by Avi. Its **When it runs** reads **Always on**: it wakes two minutes after new activity arrives, never on a schedule. - **Its Instructions tab** shows **Built-in** (Avi's curation rules, read-only) and **Yours**, where you write what matters in this project's feed. Yours are added to the built-in ones, and win where the two disagree. - **Its Sessions tab** shows each pass it made over new activity. ## Stages Work that moves through steps shows them. Document collection goes **Ask → Collect → Review → File**; client onboarding goes **Welcome → Set up → Agreement → Intake → Hand off** (the folder exists before the agreement goes out, and nothing is collected until it is signed). Wherever a stage is named it wears the same small stage icon. - On the **Activity** tab, the stages are the page: one row per stage. A finished stage carries a green check after its name, under it what it came to in a sentence, and on the right when it was completed. The current stage shows where things stand, and when it is waiting on you the question and its answer buttons sit right inside that stage. Stages still ahead show what will happen in them. Colour is kept for what matters: orange when something needs you, green when it succeeded, a quiet red when it was unsuccessful, and the full red for an error. Work that is simply under way stays in plain ink. **Stages are the path to success.** Work moves through them one at a time, and a stage is only marked finished when its work was done. When the work cannot go on — an address bounced and there is no other, they declined, nobody answered — the automation ends as **Unsuccessful** right then and stays in the stage where it stopped: that stage is not marked finished, and nothing after it is. **Succeeded** is only reached from the last stage. So do not add a stage for things not working out ("No response", "Lost"); such a stage is refused. Say in the instructions when to give up instead. **Your own stages.** Tell Avi the steps when you describe the automation ("stages should be Introduction, Contract, Hand-off; the contract must be reviewed before it goes out") and it declares them, with your approval required where you said, and writes each stage's own instructions — what happens in it — which you can read and change on the **Instructions** tab under the stage's name. Renaming or reordering stages keeps what you wrote for each. You can also add, rename, reorder (the up and down arrows on a row) or remove them on the automation's **Setup** tab with **Add stages** or **Edit stages**, or ask in chat. Work already under way stays in its stage when the edited list still has it. A pre-made automation's stages are fixed and each comes with its own instructions, which you can read on the Instructions tab under the stage's name. Their approval switches, and anything you change under a stage, are yours and stay through every update of the automation. Only automations that have stages show them. An automation without stages shows a plain timeline of what it did, and no stage display anywhere. ### Needs my approval Each stage has one switch on the Setup tab: **Needs my approval**. When it is on, Avi prepares that stage's work, then asks you to sign off before it moves on. This switch is the only place approval lives: when an automation has stages, it asks for your approval in a stage you switched on and nowhere else, so turning a switch off stops the asking even if its instructions still mention checking with you first, and Avi puts an approval you ask for on the stage's switch rather than in the instructions. The question arrives like any other (see [When an automation needs you](#when-an-automation-needs-you)), with one-tap choices that include approving everything at once. This is enforced, not just requested: until you answer, the automation cannot move to the next stage or finish as succeeded. Document collection needs your approval in **Ask** (the first emails) and **Review** by default; client onboarding in **Welcome** (before the first email goes out) and **Agreement** (before the engagement letter goes out for signature). Switch a gate off when you trust the work, or on when you want a look. ## An older automation with a Coding Sandbox Coding work runs in the Code app, never in an automation. An automation made before that may still have a Coding Sandbox. It keeps it and runs exactly as before: its Setup shows the sandbox read-only, and it can't be duplicated. ## Automations and Word documents An automation brings the same Word know-how Avi uses in chat. If its instructions involve documents ("every Friday, draft the status memo as a Word document"), or you message it a document task, it works on the document itself with the same care: one tracked change per edit, totals worked out, no PDF unless asked. Nothing needs to be turned on. ## One-time automations A **one-time automation** is one request Avi does in the background and reports back on: it runs once, finishes on its own, and its answer returns to the conversation you asked in. It is an automation like any other — in your Automations list, opened and stopped the same way. - **Ask in chat and Avi starts one.** "What does Feed.fm allow in a screen recording?" becomes a one-time Research automation. "Go through the contracts folder and summarize each one" becomes a one-time automation too. Avi replies in one line and the chat stays free. - **Each one is a card in the chat.** The card carries the automation's name and the step it is on. When it finishes, the answer follows: the short version first, **Show more** for the specifics and sources, and a tile for each file it created or changed. In voice mode you hear the short version, and a file it made opens on screen. - **It is in your Automations list.** While it works it sits in **Live**; once it is done it moves to **History**. Click its card in the chat and it opens there, like any automation: Activity, Setup, Instructions (the request it was started with), Tools and Session. - **You can keep talking to it.** Type into its message box. While it is working, your message changes its course at its next step. After it has finished, your message continues the same work: it remembers everything above and picks up from there, and its result in the chat updates. (It has nothing to wait on, so there is no **Resume** for it — a message is how it picks back up. Its model and tools are Avi's for that kind of work, shown on Setup without a switch.) - **It always reports.** It ends by reporting its result or by asking you something, never by going quiet. If it stops without reporting, it is marked failed with what it last said, so the card in the chat tells you what happened and you can start it again. It is never left sitting Active: if its session crashes or is stopped, or it cannot start at all, it ends there — failed or Stopped, with why — and moves to History; a message picks it back up. - **It asks you.** When it needs a decision only you can make, it asks as a **Needs you** question on its card. - **Only the chat starts them.** Your automations don't start one-time automations; Avi starts them from chat when you ask. Work an automation started before this changed still shows as a tile in the session that started it, and that automation still answers it. ## Native Skills: work Avi knows how to do Avi comes with **Native Skills**: know-how for particular kinds of work, built in and maintained by the Avi team. Avi brings the right one to a request without being asked. They are not pages in your [Wiki](/docs/wiki), where the skills are your own. Where the work runs depends on the work: - **Word documents** are done in the conversation (see [Files](/docs/files#word-documents)). - **Excel workbooks, PDFs and e-signatures**, and keeping the [Wiki](/docs/wiki), are done in the conversation too. - **Research** runs as a one-time automation and reports back in the chat. - **Meetings** and **Requests** wait on other people for days, so each request becomes an automation of its own. It appears in the Automations list, named for what you asked, with **Meetings** or **Requests** beside its name, and it reports to your feed as it goes. Avi sets it up; there is nothing for you to configure. Research, Meetings and Requests bring their own tools. They do not need those tools turned on in your project's Tools list. Their playbook and model are Avi's, so their **Setup** tab shows them without letting you rewrite them; you can still change when they run, message them, stop them, or archive them. A request is one piece of work, however many meetings or items it holds. Settings such as a tone, a default meeting length, or additional guidance are filled in per request from what you asked and your project instructions; a note on one meeting ("keep the coffee more formal") overrides the setting for that meeting. Put standing preferences in your project instructions and every request honors them. ### Research Research answers a question that needs more than one quick search. It checks what your project already has first (an earlier note, a thread about it), searches the web several ways, and reads the pages that settle the question: the company's own terms, docs, pricing and help pages, not someone else's summary of them. Its answer leads with one sentence that stands on its own, then the specifics with links to where each came from, then what the sources leave open and who could settle it. It reads only: it never signs up, buys, sends, or contacts anyone. ### Meetings Meetings puts meetings on your calendar with the people you name: one request, however many meetings and people it holds. It reads your availability, writes to each person once by email covering everything you need from them, handles the back and forth in that one thread, and books each meeting with a Google Meet or Zoom link when a time is agreed. It uses your Calendar, Email, and Contacts apps and the web. - Starts every session by re-reading its email threads and anything the other people sent outside them, so nothing that arrived between sessions is missed. - Follows your project instructions (your name, company, signature, who to copy, hard rules) ahead of its own defaults. - Proposes two or three concrete times inside your working hours, with the timezone spelled out. Working hours belong in your project instructions; without them it assumes 9:00 to 17:00, Monday to Friday. - For an in-person meeting, checks the place on the web first: that it still exists, that it is open at the proposed time, and its exact address, which goes on the invitation. It never proposes or books a place it could not verify. - Writes as you: first person, your name, your signature from the project instructions, sent through your Email app. It presents itself as your assistant only if your project instructions or your request say so. You do not click Send; asking for the meeting is the instruction. - One thread per person, everything in it. Three meetings with the same person are one email with three sets of options, and every reply stays in that thread. It continues an open scheduling thread with that person rather than starting another. - Wakes up the moment a reply lands (it listens for mail from everyone named in the request from the start), checks your calendar again, and either books or offers new times. - Keeps to the meetings. If the other person raises anything else — a question for you, a request, an invoice, a personal matter — it does not answer for you: it brings it to you as a **Needs you** question with a suggested reply you can approve, change, or dismiss (through the automation that started it, when one of your automations did). - Books each meeting on your default calendar as it is agreed, with the attendees invited and the video link attached, nudges once after two quiet working days, asks you before giving up, and marks itself done when everything in the request is booked. Per request, whoever starts it fills in its settings: **Timezone**, **Default meeting length**, **Buffer between meetings**, **Video** (Google Meet, Zoom — needs a Zoom account connected in the Calendar app's settings — or no link), **Tone** (friendly or formal), and **Additional guidance** (free text for that request). To steer a request already under way, message it (or the automation that started it): Meetings replies in the same email thread it started, never a second one. The playbook itself is not editable; additional guidance is how you shape it. ### Requests Requests gets things sent in that other people owe you, and keeps after them until every item is in: documents (a signed form, last year's return, a countersigned contract), confirmations (an explicit yes or no), and details (an address, bank details, references). Chasing an overdue invoice, a late deliverable, or an unanswered approval is the same job. It uses your Email and Contacts apps, nothing else. - **One request, one thread per set of people.** Hand it everything at once — every item, who owes it, the exact wording, the deadlines. An item can be owed by one person or by several who can each provide it (a client and their advisor), and people you name together get one thread with all of them on it. It writes each set one email covering all they owe, grouped by due date with the soonest first, why, how to send it (an attachment, a link, or wherever you tell it people should upload), that they should send each thing as soon as they have it rather than waiting for the rest, and that anything which does not apply just needs saying — and keeps that one thread going. Items have their own deadlines when you give them: reminders lead with what is due soonest and always mention what comes later. - **It keeps the checklist itself.** Its own working state is the record of every item: asked, arrived, received, declined, or waived, with what came in and when. It never relies on a folder or a mailbox to know where things stand. - **A reply from anyone counts, whoever sends it.** People delegate: a colleague answers from their own address, an assistant or a financial advisor at another firm writes in, someone forwards the file from a personal account. Requests wakes on three things: mail from the people it asked and their organizations, anything continuing a conversation it started (from any sender), and mail Avi judges to be about the request even from an address it has never seen. On every session it also reads its conversations and searches the mail since it last ran, whatever woke it. And it cannot send a reminder while a reply it has not read is waiting: Avi refuses that email before it leaves. An answer written into the email itself, like a quoted price where a written quote was asked for, counts as something arriving. - **It never judges what arrives — its reviewer does.** Requests cannot know what a valid contract, a complete address, or an acceptable photo of a document looks like for you. When something arrives — an attachment, a link, a stated upload, an answer, or "this doesn't apply to me" — it records it and sends its reviewer — you, when you asked for it in chat, or the automation that started it — a numbered sign-off request listing each item with the message it came in, and, for a resend, which attempt it is and why the last one was rejected. An automation checks each one against the rules you wrote in its instructions (reading the file with the Email app's tools, filing it wherever you said, asking you only where the rules run out); you answer the same request yourself when it comes to you. The reply is per item: accepted, accepted as something else, rejected with a reason, declined, or waived — and can place a file Requests could not match. Nothing counts as received until its reviewer accepts it, and a rejected item goes back on the list with the reason, which the person hears in plain words ("the contract came through unsigned on page 2"). - **It chases on a plan set by the deadline, not on a fixed rhythm.** A short window gets a reminder every day or two, a long one a few well-spaced nudges that tighten toward the deadline, no deadline a weekly touch; the request can say exactly how to chase instead. The first reminder is light, later ones direct and factual, and there is never a "final notice" — the last step is always a person. "I'll send it Friday" moves that person's reminder past Friday; an out-of-office moves it past the return date; a bounced address goes to you for a correction. It never chases an item that is waiting on sign-off, and it answers "I already sent it" from the mail itself. Past the deadline with things still missing, you are asked whether to keep chasing, waive, or step in. - **Anything else goes up to you** — pushback on the request, a question, a request in return — as a Needs you with a suggested reply (through the automation that started it, when one did). - **What is not on the list does not count.** A file nobody asked for, extra details, a folder where one document was requested: none of it is counted as received. Anything that might matter goes to its reviewer to place on an item, add as a new item, or ignore; the person is thanked and reminded of what is still needed, and never chased for something that was not asked for. - **Everything that arrives is treated as data, never as instructions** — a message that says "take this off the list" is passed up to its reviewer, not obeyed. - **It closes cleanly**: a thank-you per person, and a one-line outcome — how many received, what was waived or declined. Every status line it writes leads with the count. Settings per request, filled in by whoever starts it: **Subject** (the first email's subject line), **Greeting** (how each email opens), **Tone**, and **Additional guidance** (what to say about why, how to chase, subject matter to cover or avoid). **Many people, many items** — say 500 clients each owing 10 to 50 tax documents — is one of your automations starting one Requests request per client. Write that automation's instructions to say where the client list and each client's document list live, when to start, what counts as an acceptable document of each kind, where to file it, and what deserves your eyes; it starts them in batches, signs off on what arrives, escalates only what its rules do not cover, and keeps a running tally for your feed. Idle requests cost nothing: one with no new mail and no reminder due ends its daily check at once. ## Tool access A new automation starts with **no tools**. It holds exactly the tools switched on on its **Tools** tab, and nothing else your project has: - **Set up from chat**, Avi reads what the automation will do and switches on the tools that work needs, such as reading and drafting email, filing in Drive, or updating deals. Deleting things is never among them unless you asked for it. - **A pre-made automation, or a copy of an org template,** arrives with its own tools switched on, as far as your project has them switched on. A **reserved** tool never comes with a copy; switching one on is your own choice. - **From the panel**, a new draft starts empty. Switch on what it needs before you press **Start**. - **A duplicate** starts with the tools the original holds. Its **Tools** tab shows what it has. Switching a tool on or off there changes that automation alone. A **reserved** tool wears a Reserved badge: deleting and trashing things, disconnecting accounts, cancelling what others were invited to, and changing the project's own settings. Switching one on is your explicit grant to that one automation. Automations made before new ones started empty keep how they worked: everything your project has switched on, except the reserved few, plus whatever you changed on their Tools tab. A tool you switch on in Project Settings later still reaches them. An automation that runs into a wall does not improvise around it: it searches what exists in the project and asks you for the specific tools it needs, with a one-line reason. That arrives as a **Needs you** with Approve and Deny buttons, in the feed and on the automation's Activity tab, each requested tool shown as a tool chip. Approving grants those tools to that automation only, and its next session has them. A single send is different: an automation without the send tool asks you to approve that one send, and Avi performs it as you (see [When an automation needs you](#when-an-automation-needs-you)); the automation holds no new tool afterwards. A tool you have switched off in Project Settings → Tools reaches an automation only this way, by your own switch under **Tools**, or when Avi names it among the automation's tools in chat, while setting it up or when you ask. You can also set the whole set in chat: "give this automation only the CRM and web search tools" sets exactly those switches on its **Tools** tab, everything else off, and the reply lists what it now holds. Ask what it holds first ("what tools does it have?") when you want to trim rather than rebuild the list. Whatever the grant, an automation never manages other automations, and Research, Meetings or Requests work it starts brings its own tools. An automation holds **one open question at a time**. If what it needs changes before you answer — another tool, a different choice — it rewrites that same question in place, so you see one card that changes, never a pile of cards. A tool request that grows becomes one request for all the tools. When it no longer needs an answer, it withdraws the question. ## The Automations panel Open the **Automations** tile on the rail (the dock on a phone). One list holds every automation — the ones you set up, and the [one-time automations](#one-time-automations) Avi started from chat — in three columns: **Automation**, **Status**, and **Last ran**. Under each name sits a one-line account of what it last did, and under that **what starts it**, one tag per trigger in plain words — "Weekdays at 7 AM", "Email from acme.com", "Replies to its emails". An automation that reacts to several things shows several tags; they wrap, and hovering one shows the detail behind it. The list opens on **Live**: everything standing or in hand, ordered by what needs attention — **Needs you** first, then what is working, then what is paused, then the rest, most recent first. **History**, chosen under **Filter** → Show, holds what has finished: one-time work that succeeded or failed, and automations with nothing left to start them. An automation you stopped that still has a schedule or triggers stays in Live, one click from resuming. Each row ends with a **⋮**: **Stop**, **Start** or **Resume**, **Archive** (or **Unarchive**) and **Delete** — the automation's own menu, which asks first before it stops, archives or deletes one. A group's row has **Stop all** and **Delete**. Search by name; filter by **State** and by **Runs** (One-time, On events, On a schedule); the headers sort. Archived automations are under History's State filter. When the list is narrow (on a phone, or beside an open automation) its header shows only **Filter**. **New** opens the picker for a [pre-made automation](#pre-made-automations) or a blank draft. Open an automation and its tabs sit directly under the breadcrumb. An automation has **Activity**, **Setup**, **Instructions**, **Tools** and **Sessions** (a one-time automation's reads **Session**). - **Activity** — the automation's own account of its work. With [stages](#stages), it is the stage table. Without them, it is a timeline of what changed, newest first: options sent, a reply received, booked, a question for you, a failed session. The automation writes these itself and only when something actually changed, so the timeline stays readable however many sessions ran. Each session's newest entry has a **View session** link to that session's transcript. When the automation finishes, its final entry carries the whole outcome, not a one-line summary. If it is waiting on you, the question appears inside its timeline entry and you answer it there. When the automation is tracking several things — each document it requested, each person it asked — it shows where each one stands as a short table inside the timeline entry that reported it: each item with its state above it (waiting, working, done, blocked, or needs you), and a link tile when it points to a file or record — the tile opens it inside Avi. The newest table is shown open; earlier ones open with **Show what it looked like**. That table is the current picture and says when it was last updated; earlier versions stay in the timeline behind **Show what it looked like**. The same table appears on the automation's row in [Updates](/docs/updates). To message the automation, use its **Sessions** tab (see below). Every entry is its own point on the timeline, always shown; a session's newest entry carries its **View session** link. A session that finished without writing anything still leaves one line, what it did in a sentence, with its **View session** link. A question for you is answered at the top of its point, above anything it lists. Several links under one line show as one compact list. - **Setup** — everything that defines the automation. Setup, **Instructions** and **Tools** are tabs of the automation, beside the others; say any of them, or what sits on them ("the schedule", "the prompt", "tool list"), and the record opens there. Every label's description sits behind a small info mark to its right: press it to read, and close with the X. **Setup** is the automation's fields, in this order: - **Name**. Rename it here and save, or ask in chat ("rename the outreach automation to Email Avi deck to SMBs v1"). It stays the same automation, and its row in Updates follows. - **When it runs** — every trigger as a tag, the same tags as the list ("Weekdays at 7 AM", "Email from acme.com"). An app's event is named in full ("CRM deal created or stage changed"); only a subscription to everything an app emits reads as activity, and says so ("Any CRM activity"). Hover a tag for the exact event names behind it. An automation with no trigger of its own shows **When started** and **When messaged**. When the automation started work of its own before automations stopped doing so, that work's triggers are listed too, each naming the work it belongs to. - **Stages** — only on an automation that has them: each stage, its **Needs my approval** switch (see [Stages](#stages)), and an **Instructions** button that opens that stage's own instructions. A stage is its name and its instructions; there is no separate description to keep in step. - **Model and limits** — the model, max daily spend, and spend so far. Every automation runs on **GLM 5.3 Flash** unless you pick another model here, or name one when you ask Avi to set it up. That includes the one-time automations Avi starts, and Research, Meetings and Requests. The daily spend ceiling is the one limit on how much an automation may use; there is no cap on sessions per hour. In an [agent](/docs/agents), up to 10 sessions run at once across its automations, and the rest wait their turn. - **Advanced** — collapsed, and shown only for a legacy **Coding Sandbox** (read-only — see [An older automation with a Coding Sandbox](#an-older-automation-with-a-coding-sandbox)). Work an automation started earlier shows as tiles in its sessions, and never asks you directly; its questions come to you from the automation itself. **Instructions** is the standing brief, with the whole tab to write in. Edit it, save, and the next session uses it. When the automation has [stages](#stages), a picker above the editor chooses whose instructions you are editing: **General**, or one stage by name, which has instructions of its own: what happens in that stage, in as much detail as you like. Each stage in the Setup chart is a link to its instructions. Automations you already had keep their instructions exactly as they were; a stage's own instructions start empty until you or Avi write them, and a pre-made automation's arrive filled in. Work Avi started for a request — a one-time automation from chat, or Meetings and Requests — shows **What it does** here instead: the request it was started with and your answers. **Tools** is the table of tools it holds, each with a switch (see [Tool access](#tool-access)). - **Sessions** — every time the automation wakes (its schedule fires, an event arrives, you message it) it starts a session of its own. The list shows one row per session, newest first: what it did, what woke it, how it ended, and when it started; search it, or filter by what woke it and how it ended. Open one to read it like a chat — every reply and tool call inline, streaming live while it works, with a stop button and a message box. A message in an open session is a **reply**: it continues that session, which picks up exactly where it left off. **Message** above the list starts a new session with your message. Each new session starts fresh: what carries from one to the next is the automation's [working state](#working-state), its status and its instructions. A one-time automation is the exception: its **Session** tab is one conversation, and every wake continues it. A table it showed earlier is a picture of that moment: a row that was still being worked on then wears a still mark, and only a table being shown in a session streaming right now has a turning one. Under the tabs, one status row shows the state badge and when the automation last ran — on every tab but Instructions and Tools, which have none. On the right sit **Save** (on Setup in that row, and on Instructions at the right end of the row that picks whose instructions you are editing, with the ⋮ menu beside it; Tools has none, since its switches apply as you flip them — the one Save for everything typed on that tab: name, instructions, spend, what each one is called, stages being edited, a pre-made automation's answers; switches and menus apply as you flip them), **Start** (on a draft), and the ⋮ menu. The ⋮ menu holds **State** (the automation's own working notes — see [Working state](#working-state)), **Stop automation…** or **Resume automation**, **Archive automation…** (or **Unarchive automation**), and **Delete automation…** — permanent; the confirm says what is lost. ### How an automation shows up in Updates An automation's work reads as one story, and all of it is in one place: everything an automation does, and everything that comes back about it, lands on its row. Its row in [Updates](/docs/updates) carries what it did, the records and files it created, the messages it sent, its questions to you and its outcome — not a separate row for each. An automation has **one row** in Updates — in an [agent](/docs/agents), each customer's automation has a row of its own: - **Everything it does** is a line on that row. Routine progress stays quiet, and the newest line is rewritten as things move. - **Questions** count on the row ("Needs you (2)") and are answered on the automation's update page: open the row, and what is waiting on you is listed at the top, a line each, above the story. You are notified for each question. A question also appears on any other topic that carries that automation's work, so wherever you read the story, the question is there to answer. - **Outcomes** — the automation succeeding, or ending unsuccessful — and a run hitting an error are lines on the row that notify you. **Automations chain.** Tell Avi "when onboarding finishes, start the kickoff automation" and the second starts on the first's conclusion, with the result and what it made as its first message. The tag on Setup reads **After Client onboarding**, and a chain can never loop back to itself. **One-time automations share one row.** Every [one-time automation](#one-time-automations) Avi starts from chat reports its result as a line on the project's single **One-time automations** row, led by its name, so you can go back to it without a row each. It does not notify you there: its answer is already in the conversation. Avi decides which of these a development belongs on, the same way it curates the rest of the feed; if something is plainly part of another matter you follow, it goes there. **When an email bounces.** If an email an automation sent cannot be delivered, the automation that sent it is told right away: which address failed and why. It does not have to notice the mail system's notice in your inbox, and no other automation is disturbed. This works the same whether the mail went out from your Avi address or a connected account such as Gmail. What it does next is up to its instructions (try another contact, stop, or ask you). **When a run fails.** A run that stops on an error is never silent. It appears on the automation's row in Updates as "Error: …" and notifies you; on the Automations list its line reads "Session failed: …" with the reason, and the failure is the newest entry on its **Activity** tab. To run it again now, press **Message** on its **Sessions** tab or ask in chat. The automation stays active and runs again on its next trigger. Results also reach you the normal ways: anything an automation produces (notes, emails, messages) lands where it was sent, and its activity is folded into the project's Updates feed. ## Groups When the same work happens for each of many things — onboarding each new client, screening each candidate for a role, chasing each unpaid invoice — make it a **group**: automations that share **one setup** while each does its own work. - **One setup, changed in one place.** The group's instructions, stages (with their **Needs my approval** switches), tools, model and max daily spend are shared by every automation in it. Change them on the group and every one of them runs on the change from its next session. - **Each one is its own.** Each automation in a group has its own name ("Acme Dental"), its own triggers (its client's email, its own schedule), its own conversation, its own stage and its own outcome. - **A group calls them by name.** You tell Avi what one of them is — a client, a candidate, an invoice — and the group uses that word everywhere: "6 Clients", the **Clients** tab, "Stop Client…". **Making one.** **New** → **Start a group**: give it a name ("Client onboarding") and say what one of them is ("client" / "clients"). The group opens on its **Setup**, empty, ready for the instructions, stages and tools they will share. Or ask in chat: "set up client onboarding as a group — one per client, starting with Acme Dental". An automation you already have can become the first of a group: its **⋮** → **Make it a group…**, or ask Avi ("make the onboarding automation a group of clients"). It keeps its name and triggers, and its setup becomes the group's. Its tools become exactly the ones it holds now, set for the whole group (switching a tool on for the project no longer adds it). Save any changes first. An automation copied from an org template can't start a group — start one fresh instead; one published to your org, or archived, can once you unpublish or unarchive it. **Adding one**: **New** on the group's page asks for its name ("Cedar Street Dental") and opens it — it runs on the group's setup and starts when you start it or message it; ask in chat to give it triggers of its own. Or ask Avi ("onboard Cedar Street Dental") — once the group has its instructions. In an [agent](/docs/agents), an automation that finds new clients can add each one to the group itself. **In the Automations list** a group is ONE row: its name with a stacked icon after it, and under it how its automations stand — "6 Clients · 1 needs you · 3 under way · 1 succeeded". Its status is theirs: **Needs you** when one of them needs you, **Working** while one is working. It stays in the live list while any of them is live — including one you stopped that still has triggers. Searching the list finds a group by the name of any automation in it, and **Filter → Runs** shows a group under the triggers its automations have. **The group's page** has four tabs: - **Clients** (named for what the group handles): one row per automation — its name, where it stands, what wakes it, its stage, its status and when it last did something — what needs you first. Search, **Filter** (by status, by stage) and **New** sit above the list; each row's **⋮** stops, starts, archives or deletes that one. - **Setup**: the group's name, what one of them is called, its stages and their approval switches, its model and its max daily spend. The spend is a ceiling **each** automation in the group has of its own, not one shared pool. When one of them reaches it and you raise it, the raise is the group's: every automation in it gets the new ceiling. - **Instructions**: the general instructions, and each stage's own. - **Tools**: what every automation in the group may use. The group's **⋮** stops every one of its automations, or deletes the group with all of them. **One automation of a group** opens under "Automations / Client onboarding / Acme Dental" with three tabs: **Activity**, **Sessions**, and **Triggers** — what wakes it, which is its own. Its setup is the group's: ask Avi to change it on the group, or open the group's page. A group keeps its setup when its last automation goes; delete the group itself from its **⋮**. ## Templates A **template** gives someone their own copy of your automation. Publish an automation to the org and anyone here can copy it: the copy is theirs, runs as them, with their accounts, and starts dormant on its own Setup page — so a sales lead can design Client outreach once and every rep can run it on their own territory. - **Publish** from the automation's menu: **Publish to the org…**. Write the one line people see in the picker. Your triggers, model and spend are not part of the template; what people get is the name, the instructions, the stages with their instructions and approval switches, and the tools it holds, as far as their project has them switched on and never a reserved one. - **Find and copy** under **New automation**: pick **Your org** beside the search to see only what your org has published, or leave **All** for everything. Picking one makes a copy of your own in your project, which opens on Setup. - **Edit** a template by editing the automation you published. Your later edits reach every copy wherever its owner has not written their own: a stage's instructions someone rewrote stay theirs, a switch they flipped stays flipped, a list they reordered or added to keeps their shape. The listing's one line is edited from the automation's menu (**Edit the template…**). - **Unpublish** from the automation's menu (**Edit the template…** → Unpublish). The listing goes; copies people already made are theirs and stay. ## Messaging an automation A standing automation isn't fire-and-forget — you can talk to it. Open it in the panel, go to **Sessions**, and reply in a session ("why did you email Sam twice?") or press **Message** to start a new one ("also include closed PRs"), or just tell the assistant in chat ("tell the issue-digest automation to also cover the docs repo"): - If it's working right now, your message reaches the session in flight — it changes course mid-session instead of starting something new. (Sandbox sessions are the exception: the message becomes the next session.) A message that arrives just as a session ends isn't lost: it continues that session right away. - Otherwise it runs right away to act on it: a reply continues its session; a new message starts a fresh one. - A tweak sticks for future sessions: when you tell it to change how it works ("skip weekends from now on"), it records that in its working state, which every later session reads. - A message can even change what *triggers* the automation ("also run whenever Bob emails me", "stop watching that repo") — the automation updates its own event or feed subscription in response. Messaging a concluded automation **resumes** it — the same automation picks back up with your message as its next input: a reply in one of its sessions continues that session, a new message starts a fresh one (see [States](#states)). Adding a new question to finished work is exactly this: message the automation, don't start a copy. ## When an automation needs you Sometimes an automation hits a decision that's genuinely yours — "both Tuesday 2pm and Thursday 10am work for everyone; which do you prefer?", "this contact has two emails on file; which is current?" Instead of guessing or silently stalling, it **asks**: - The question lands in your [Updates feed](/docs/updates) (and notifies you) as a "Needs you" mark on the automation's own row. Open the row: everything waiting on you is at the top of its page, above the story — the question, what the decision needs in the automation's own words, the draft or record it is about as a tile, the controls, and one line saying what happens if you never answer ("If unanswered in 3 days: I'll propose Tuesday 2pm"). Press **Answer** on a question to see its choices and type your own answer. The automation's **Activity** tab shows exactly the same thing inside its "Needs you" entry on the timeline — it is always the newest entry, because asking is the last thing a session does. - **Approving a send.** When what an automation needs is your go-ahead to send something — an email it drafted, a meeting it is booking, a message it is posting — the line says exactly that ("Send “Welcome aboard” to alex@drumsinc.com"), the draft sits under it as a tile that opens it in its app, and two controls follow: **Approve** sends it, **Decline** takes an optional reason the automation reads. The automation never sends it itself: on Approve, Avi performs that one send as you, and the line settles to **Sent**. If you open the draft and send it from the Email app instead, the line settles to Sent on its own and the automation carries on. Nothing goes out until you approve, and a request you leave unanswered expires without sending. To make this the only way out, switch the send tool off under the automation's **Tools** tab; the automation then asks for every send. - The automation shows **Needs you** in the panel until you answer. - Your answer resumes the work immediately: a session that is working gets it at its next step; otherwise a new session starts with your answer in hand. Replying in plainer ways works too: messaging the automation (in the panel or via chat: "tell the scheduler Tuesday works") counts as the answer. - Every question comes with a deadline and a stated fallback — what the automation will do if you never answer ("if I don't hear back in 3 days, I'll propose Tuesday 2pm"). An unanswered question quietly becomes that plan, never a stuck automation. The feed shows how each question resolved: answered, expired into its fallback, or withdrawn (the automation finished or was stopped first). A one-off that asked a question waits for the answer (or the deadline) before it wraps up. Automations are told to ask sparingly — routine judgment calls stay theirs; questions are for decisions only you can make. ### When the decision is someone else's An automation can put a question or an approval to another member of your org. Name them by their **handle** — the @name on their identity in the org — in its instructions: "escalate pricing to @matt" is enough. From one of your own automations, the row lands on **their** Updates feed, exactly as it would on yours: the deed, the reason, Approve and Decline. Only they can act on it; on your feed it shows who it is assigned to, with their name, until they act. From an [agent](/docs/agents), the question reaches them as a message from the agent instead. When they approve an action, Avi performs it **from their account** — an email goes out from their mailbox and sits in their Sent folder. If they decline, their words come back to the automation like yours would. ### Reviewing many at once When the same decision applies to many records — move each of these deals, send each of these drafts — you get a **review list** that fills as the automation works: one row per record, the reason it is on the list under it, a chevron for the full reasoning, **Open** to look at the record, and **Approve** or **Decline** (with an optional reason) for that row alone. **Approve all** and **Decline all** handle the rest in one go. A row you have reviewed leaves the list, as does one whose deadline passed; the header keeps the count ("2 of 5 reviewed · 1 unanswered") and "Show 3 rows" brings them back if you want to look. The header says how many are left and what happens to rows you never answer; rows you have handled stay in the list, dimmed, until the whole review is done. Avi performs each approved change for you the moment you approve it; nothing happens to a row you decline or leave. The automation keeps working while the list is open — it is a proposal, not a question — and hears back once, after its run has ended and every row is settled or past its deadline, with what was approved, what was declined and why, and what was left for its fallback. ## Working state Automations keep private working notes — where they left off, what they are waiting on, decisions they've made, and standing directives you've messaged them ("skip weekends from now on"). Each session starts fresh, so these notes are what carries from one session to the next. This state never touches your Tasks, Drive, or other apps; it belongs to the automation alone. You can inspect it any time: open the automation's ⋮ menu and choose **State** — useful for seeing exactly what a months-old automation believes it's doing next. ## States **The status belongs to the automation.** A session doesn't carry a verdict — it's one sitting, and a bad sitting doesn't sink the work. Every automation shows exactly one state, everywhere it appears — the list, its own page, and the Updates feed all use the same vocabulary: - **Needs you** — the automation asked you a question and is waiting on the answer (see [When an automation needs you](#when-an-automation-needs-you)). This outranks every other state. - **Working** — a session is executing right now (you can watch it live). - **Paused** — the daily credit budget is spent; new sessions wait for tomorrow. Resumes on its own (or ask in chat to raise the budget). - **Active** — live: watching its triggers or waiting on its schedule, nothing running at this moment. - **Not started** — a draft: created with **New** and never started. Review its **Setup**, then press **Start**. - **Succeeded** — done for good. A one-off succeeds when its work does; a standing automation succeeds when it decides its work is complete ("watch for X, then report") or when you tell the assistant to mark it done. - **Unsuccessful** — done, and the goal was not reached: the automation decided for itself that it could not go on (the address bounced and there was no other, they declined, nobody answered after the last follow-up). It always says why. This is an ordinary outcome, shown in a quieter red. - **Error** — the automation broke and the platform ended it: a one-time run that crashed, or five failed sessions in a row. Shown in the full red, with the error. (A single session that hits an error is also marked **Error** on its Session and in Updates, but the automation stays active and runs again on its next trigger.) - **Stopped** — done because you chose to end it (**Stop automation…**, or ask in chat). Not a failure — just your call. - **Archived** — put away. **Archive automation…** ends it if it was running and keeps everything (sessions, working state, questions, its topic in the feed) while taking it out of the list, search, and the assistant's view. Pick **Archived** in the State filter to see archived automations; **Unarchive automation** brings one back with the state it had, and you can resume it from there. Succeeded, Unsuccessful, Error, and Stopped mean the automation is **dormant** — its schedule and triggers stop firing, and nothing runs on its own again. But a concluded automation isn't sealed: **you can resume it**, and the *same* automation continues — same working state, same sessions list, same topic in your feed. Message it (from its **Sessions** tab, or in chat — sending resumes it with your message), choose **Resume automation** in its ⋮ menu, or ask in chat. Resuming clears a failure and starts the reliability clock fresh; resuming an automation with a schedule arms the schedule again. This is deliberate: one piece of work should live in one automation — resuming keeps search, the Updates feed, and the assistant all pointing at the same story instead of a trail of near-duplicates. When you are done with an automation for good, archive it rather than deleting it: nothing is lost, and it can come back. When an automation reaches a verdict — Succeeded or Unsuccessful — that always lands in the project's [Updates feed](/docs/updates) too, under the automation's own topic, headed by a one-line account of the outcome: "Succeeded: *what it accomplished*", or "Failed: *why*". The full outcome sits beneath that line, in the Update and on the automation's Activity tab, so you can read what it found or did without opening a session. You never have to open the panel to learn that standing work finished or broke, or what it did. (Stopping an automation yourself doesn't post one — that's your choice, not news.) ## Max daily spend Every automation carries one ceiling — its **max daily spend** — so nothing can quietly run away. It is a guardrail, not a target, and it is deliberately high: **100,000 credits a day** for every automation, on every model — the ones you set up, the [one-time automations](#one-time-automations) Avi starts from chat, and Research, Meetings and Requests alike. There is no other limit on what an automation spends. - As a session approaches the day's ceiling it's told to wind down: it finishes the item in hand, saves its progress, and ends cleanly. - Once the ceiling is reached, new sessions wait until the next day and the automation's Activity tab records the pause. When the ceiling is one you set lower, a **Needs you** lands on its row in Updates asking whether to raise it — pick a raise or type a number, and the automation picks its work back up within a couple of minutes; choose to wait and it resumes tomorrow. Two things are never lost to a pause: a one-time scheduled run and any message you send the automation — those run once the pause lifts. - A session that ignores the wind-down and crosses the ceiling anyway is simply stopped. That is not a failure: the automation stays active, nothing counts against its reliability, and it resumes the next day. 100,000 is also the most an automation can have. Name a lower number when you create the automation, or ask in chat any time ("cap the digest at 2,000 credits a day"), and that number is used instead. Sandbox sessions count toward the same ceiling. Automations don't expire on a timer — an automation lives until it concludes or you stop it. Budgets and the panel's per-automation cost display are what keep a forgotten automation from becoming a surprise. ## Scheduling Automations support three kinds of schedule: - **Recurring at a time of day** — "every morning at 9am", "Mondays at 8". Runs on a cron schedule in your local timezone, so it stays correct across daylight-saving changes. - **Recurring by interval** — "every 2 hours". Minimum interval is one hour. - **One-time** — "tonight at 11pm", "in three hours". Runs once, then the automation is done. Creating an automation never runs it. Whatever its instructions hold, nothing happens until its trigger fires, you press **Start** in its panel, or you ask for a run now. An automation with no schedule runs only on those last two. ### Starting now *and* staying scheduled A schedule doesn't have to mean waiting: for two-phase work — "message everyone today, then nudge stragglers each morning" — Avi arms the schedule (often with an event subscription too, so it reacts the moment each reply lands) and, because you asked for today's pass, starts that first run as a separate step with your words behind it. If you did not ask for a run now, the first run waits for the first tick, and you can say "kick it off now" at any time — it runs immediately without disturbing the schedule. ## Feed subscriptions Besides (or instead of) a schedule, an automation can subscribe to the project's [Updates feed](/docs/updates), so it runs the moment something newsworthy lands there — whatever the source (GitHub, email, Slack, AWS, an app): - "Triage every PR on my repo" — runs whenever a pull-request update appears or gains activity in the feed, with that update's headline and latest activity as its input. - "When anything new lands in the feed, summarize it to Slack" — runs on every new update. Because the trigger is the curated feed — not raw source events — the automation reacts to the same deduped, living stories you see in your feed. Subscriptions can be narrowed by source ("only GitHub activity"), by a specific thing ("only PRs from `acme/api`"), or by headline keywords, and combined with a schedule (a daily digest that also reacts to PRs). Housekeeping changes that don't add news never wake an automation. If updates land while sessions are in flight, they run side by side — unless the automation works one session at a time. Either way, everything that arrives while a session waits to start is handled together in that one session, so a burst costs one session, not one per update. The max daily spend keeps a noisy feed from running away. One thing to know: the feed is **curated**. An editor decides what's newsworthy enough to appear there, so something low-key — a brief personal note, a routine notification — may never become a feed update at all, and a feed-subscribed automation won't run for it. When the automation must catch a *specific occurrence every time*, it uses an event subscription instead. ## Event subscriptions A trigger names the app its event comes from ("CRM deal created", "Calendar event"); one that would fire on that event from every app is refused, except messages, which many apps deliver. Changing an automation's schedule or triggers never runs it, and nothing runs unless you asked. An automation can also subscribe directly to the project's **event log** — the raw record of everything Avi ingests (every email, chat message, calendar change, repo event, app event), before any curation: - "Whenever my grandmother emails me, draft a reply" — runs on every inbound email from her addresses, even a one-word hello. - "When Jane messages me, ping my phone" — runs per message from her handle, on any channel that carries it. - "When something lands in #deals, summarize it for me" — runs on posts in that chat channel. - "When a meeting with the Acme folks changes, re-check my prep doc" — runs on calendar activity involving those attendees. - "On every new support ticket, do a first-pass triage" — runs per ticket event, no editorial gate in between. Event subscriptions match on the event's *envelope*, and the filters compose: - **Type** — what kind of event, with wildcards: inbound email, a chat message, a calendar change, repo activity. - **From** — the sender's email address(es) or chat handle(s), or a bare **domain**. This is deliberately *per-sender, not per-thread*: replies get knocked out of threads all the time, but mail from `jane@acme.com` is mail from Jane wherever it lands. List every address a person writes from. For an automated sender — a school's notification system, a bank, a service's alerts — use its domain (`parentsquare.com`): those systems often mint a different `donotreply+…@` address for every message, and a domain matches all of them. A plus-tag never breaks a match either: `donotreply@x.com` matches `donotreply+abc@x.com`. - **Involving** — the person in *any* role: an email's to/cc, a calendar event's attendees. - **Channel** — the chat channel a message was posted in. - **Provider** — which service carried it ("avi", "slack", "google"). This matters for chat handles, which are only unique *within* a service: "jane" on Slack and "jane" on avi messages can be different people, so "when Jane messages me on Slack" pins both the handle and the provider. (Email addresses are globally unique, so they rarely need it.) They're exact and predictable: if the matching event lands, the automation runs; if it doesn't, nothing runs and nothing is spent. That's also why narrow filters matter — every match wakes the automation, and "every inbound email" includes the newsletters. When you name a person or a channel, the agent arms the filter to match just that; describe the trigger as precisely as you'd like the spend to be. Use event subscriptions whenever missing an occurrence isn't acceptable; use feed subscriptions when you want to react to the bigger, curated story. Bursts gather the same way, and an automation can never trigger itself: neither the platform's internal events nor the automation's own edits (a note it updates, a task it creates) will re-fire its own subscription. ## Relationship to Tasks [Tasks](/docs/tasks) are to-do items — they track work, they don't run it. Automations are the engine: when you ask for anything automated, the agent sets one up. ## Good uses - Daily briefings ("every morning at 7am, email me a summary of new GitHub issues"). - Monitoring ("every 15 minutes, check if our homepage is up; page me if not"). - Reacting to activity ("triage every PR from my repo and make a task if it needs my review"). - Coding work on a repo belongs to the Code app, not an automation. - Weekly reports. - "Work on this in the background" requests you explicitly want as their own automation. - Anything you'd otherwise have to remember to ask for again. --- # Agents An **agent** is a project your org owns. It has a name, a picture and a handle (`@concierge`), people who work with it, its own apps and accounts, and its own Instructions. Its [automations](/docs/background-agents) are its work. Where a personal project is yours alone, an agent is the org's: its creator is its first manager, it outlives any one person, and everyone on it sees the same work. Use one for work that belongs to the team rather than to a person: a customer concierge that looks after every customer, a support desk that answers `support@` and escalates to engineering, a recruiter that moves every candidate through the same steps. ## Making one Open the org menu — the org's square at the foot of the rail — and choose **New agent…**. Give it a name and, if you like, a picture (it wears a bot until it has one) and the people who should be on it. It opens on its Apps, where you connect what it will use — the team's shared mailbox, the org CRM, Drive — through the ordinary app flows, once. An account you connect to an agent is used by everyone who can talk to it, so connect the team's accounts there, never your own. The org's square at the foot of the rail is the switcher: your **Personal** project with your photo, then the agents you are on, then your orgs below a rule. Pick one to go there. While you are in an agent, its picture sits in the corner of the org's square. Write what it is for in its **Instructions**. Every automation in the agent follows them, so "change how we greet new customers" is one edit. The agent gets a handle the moment it exists — a starter; a manager can claim a custom one in its Settings, and change it later, as you can for your own (an old handle is retired, never reassigned). ## Sharing An agent has two roles: - **Members** open the agent, read everything in it — its automations, their sessions, its feed, its files, its Settings and Instructions — and talk to it. A member can run an automation and message it; a question it asks is answered by a manager, so a member's message never counts as the answer. Setting one up, or changing its instructions, is a manager's. - **Managers** also change it: its name, picture, people, apps, Instructions and automations. Org owners and admins manage every agent. A manager adds people from the agent's **Settings → Sharing**, and can open the agent to the whole org, which makes every org member a member. Anyone named on it can take themselves off (an org owner or admin still manages it afterwards). ## Talking to it Open the agent and type in **Chat**, or send `@concierge` a message in **Messages** (its **Agents** tab lists every agent you can use; pick one to open your conversation with it). Both are the same thread: your own, private conversation with the agent — nobody else on the agent sees it, not even its managers, and theirs stays theirs. Its reply comes back where you asked. Only the people on the agent can talk to it; a member can ask it anything, run its automations and message them, but cannot change it through chat — setting automations up, and its Instructions, are its managers' to change. The agent's work is shared; the conversation is not. ## Its work Automations in an agent work exactly as they do anywhere, with one difference in how you use them: when the work is one thing per customer, candidate or order, it is one automation per customer, in the agent — usually a [group](/docs/background-agents#groups), so they all share one setup you change in one place. Ask the agent, as a manager ("onboard Acme"), and it adds one; an automation that finds new customers — on a schedule, or when a company is created in the CRM — adds each one itself. Each runs on its own, with its own thread, triggers, stage and verdict. An agent runs up to ten sessions at once; the rest wait their turn and start as sessions end. Nothing fails or is skipped for waiting. An automation that works one session at a time still does. ## When it needs you When an automation in an agent needs a decision, it asks by message. A question for a particular person — "send this to Acme from your account", named by their handle in the automation's instructions — goes to them. Anything else goes to the people named as its managers (the org's owners, when none are named). In Messages the question shows as a **Needs you** card, the same one your Updates feed and the automation's Activity show: the question in full, **Approve** and **Decline** (with an optional reason) or the answer form with its choices, and what happens if nobody answers by the deadline. A review list (several things to approve or decline at once) shows every row, each approved or declined on its own, or all at once. The automation's name on the card opens it. You can still answer in words: reply with one of its choices; anything else is just a message to the agent. An open question — one without choices — takes any reply, as long as it is the last thing the agent said to you; once the agent has answered you since, your words are a message again, and the card is the way to answer. A send asked of you by name goes out from your own account; the agent's own sends go out from its accounts. When someone else answers first, the card says so, and you hear so in the same thread. The agent's own feed keeps the story of what happened; the asking lives in Messages. ## Credits An agent draws on the org's credits like every member. It is not a seat and is not billed as one. --- # Updates The Updates feed is your project's living timeline — what's happening across everything connected to the project, curated automatically so you can catch up at a glance. ## How the feed works Every row in the feed is a **topic**: one real piece of work, followed from start to finish. That can be a deal, a feature, an incident, an order, a hire, a meeting being arranged, or one of your own [tasks](/docs/tasks). Each topic is named for what it's about ("Sales: Acme — Enterprise, Q3", "Incident: checkout — error spike") and gathers everything about that work in one place, from every app you use. The same deal discussed over email, in chat, and in your CRM stays one topic. As new activity arrives, the topic gains a new **beat**: a one-line headline of what just happened, with detail underneath. The newest beat is the topic's current status. Click a row to open the topic's page: anything waiting on you at the top, then its whole history, newest first; **back** returns you to the feed where you were. Timestamps show when things actually happened (when the email arrived, when the message was sent), not when Avi processed them. - **Your tasks are topics.** When something happens that is the work of one of your open tasks, such as the vendor's quote for "Get the office quote" or the signed contract for "Send Hooli the contract", it lands on the task itself, titled by the task's name, instead of on a new topic beside it. A task never shows up on its own. It appears the first time real work about it arrives. After that, completing or reopening the task shows on the same topic, and renaming the task renames the topic. If a topic about that work already exists, it is folded into the task: its whole history moves under the task's name, and later activity lands on the task. Open the task from the topic with **Open task**. - **Many events, few rows.** A busy topic is still one row: it moves to the top when something worth a look happens, and routine progress is added to its timeline quietly without moving it. Recurring notices, like marketplace renewals, payouts, or sign-ups, are kept together as one topic per month with a running tally, not a row for each one. When a few messages about the same moment arrive together, they're written as one beat. - **Routine record activity is one row a month.** Records moving through your tools in the ordinary course of business — deals appearing and changing stage in your CRM, for example — are kept on one topic per month ("Sales: Pipeline deals — October") with a running count, however many records there are. A record gets a topic of its own when there is a reason for you to follow it: it is yours (the deal's owner is you), people are already emailing, messaging, or working a task about it (its changes then land on that conversation), or it turns — a deal won or lost always gets its own topic, worth everyone seeing. Older per-record topics that held nothing but routine activity are folded into the month's row. - The unread dot is personal: it tracks what *you* have and haven't seen. A topic you've read comes back as unread only when something worth a look happens. - The small icon on a row shows where its latest activity came from (email, Slack, and so on); a task's row shows a checkmark. - A topic that has gone quiet comes right back to the top when its work picks up again. - In the Avi mobile app, tabs at the top sort your [automations](/docs/background-agents) by what they're doing, under a one-line summary ("1 needs you, 2 working"). **All** is the feed. **Needs you** lists automations waiting on your answer — the number beside it is how many. **Active** lists every live automation: the ones working right now first (the number beside it counts those), then the ones waiting for their schedule or trigger, then any paused for the day. **Finished** lists what your automations concluded, succeeded and failed, newest first. Open an automation from any of these tabs to answer it or read its full outcome. Automations you stopped or archived live in the Automations panel. You can say the tab names in a voice session. - The feed stays current on its own as activity arrives. In the mobile app, you can also pull the feed down from the top to refresh it on demand. ## Automatic curation Avi curates the feed for every project by default — no setup. As activity arrives from your connected sources, Avi decides what's worth keeping, places it on the topic it belongs to (or on one of your tasks, or starts a new topic when it's genuinely new work), and writes the timeline beats. Replies in the same thread stay together on one update, so a conversation is understood in context rather than message-by-message. Avi keeps the **substance** from everyone in your conversations — decisions, agreements, action items, key facts, open questions — whoever said them, you included, so you and Avi share the full picture of what your team is doing. It filters the **noise** — newsletters, bulk mail, and content-free chatter like reactions, acknowledgements, and off-topic banter — no matter who sends it. A message that @mentions you is always given full consideration — and so are your own messages: Avi reads each one alongside the conversation it's replying to, so a quick "approved", "ship it", or "yes, go ahead" from you lands as the decision it is, not dismissed as a throwaway. Curation never creates or changes tasks. Tasks are yours. Avi only records what happened, on the task it was about. ### The Curator Every project has a **Curator**: the automation that keeps this feed. You'll find it in the project's [Automations](/docs/background-agents) list. It's always on — it can't be stopped, archived or deleted, and it needs no setup. - **It waits two minutes, then reads everything together.** When new activity arrives, the Curator starts two minutes later, so a burst of replies in one thread is curated as one development, not one message at a time. - **Some things are filed straight away.** An app asking for your approval, and changes to your own tasks, land on the feed without waiting for the Curator. - **It looks things up before it decides.** When a message can't be understood on its own — a quick "lgtm" to something it can't see — the Curator reads the thread, task, deal, event, pull request, ticket or file it refers to first. - **Tell it what matters.** Its **Instructions** tab has two views, picked from the menu at the top: **Built-in** (Avi's curation rules, kept up to date; you can read them but not change them) and **Yours**. Write what matters in this project's feed, in your words — yours are added to the built-in ones, and where the two disagree, yours win. You can also ask Avi in chat ("tell the Curator customer escalations always matter"). A few things skip the editor entirely because you must never miss them: an [automation](/docs/background-agents) concluding its work, hitting its daily budget, or **asking you a question** always posts directly. These items are titled by the automation ("*Collecting shirt sizes from the team*"). When an automation is, or was, working a topic, the row shows it on its own line under the latest activity: the automation's name and its state — a live state (working, needs you, paused) as a badge, a finished one as plain text with when it ran — so a completed automation never reads as the outcome of later activity on that topic. A question shows as a **Needs you** item — open it and answer right in the feed (tap a choice or type a reply), and the automation resumes with your answer. Each question carries a deadline and the automation's stated fallback, and its row keeps the whole story: asked, then answered — or expired into the fallback. Some apps also publish their own digest updates straight into the feed. Those belong to the app that writes them: curation never merges, regroups, or rewrites a digest. ## Grouping is automatic Keeping related activity together is Avi's job, not yours. The Curator places each development on the topic it belongs to — on one of your tasks first, when it's that task's work — and opens a new topic only for genuinely new work. Two of your tasks are never merged, and a topic that turns out to be one of your tasks' work is folded into the task. ## Beats know their records Opening an update shows its whole story, newest beat first, every beat in full — nothing to expand. Every beat Avi writes remembers exactly which records it came from — the email thread, the deal, the file, the ticket — and the app's own link to each. Each beat carries those links to jump straight into the source app, and when you ask Avi to act on something in the feed ("reply to that thread", "open that file"), it goes directly to the record instead of searching for it first. ## Ask Avi about your feed When you chat with Avi in a project, it already has your most recent updates in view — so you can ask "what happened today?" or "anything I missed on the Acme deal?" and get a straight answer without telling it to go look. For anything older or more specific, it pulls the full feed or opens a single update to read the whole timeline. --- # Apps An **app** is a bundle of related tools the agent can use — and often more: a panel of its own, background automation, activity feeding your project's Updates. Apps are turned on **per project** — so your engineering project might have the Code app on, while your sales project has the CRM on. You control what the agent has access to, project by project. Seven apps are built in and **always on**: Drive, Email, Messages, Calendar, [Tasks](/docs/tasks), [Contacts](/docs/contacts) and the [Wiki](/docs/wiki). They're in every project from day one, with their own panels and nothing to enable, and they can't be switched off. Everything else in this guide is opt-in, per project. ## Finding apps A project's settings → Apps has two tabs: **Installed** — the apps already on in this project — and **Discover** — everything available to add: apps published by Avi, public apps from other publishers, and any apps your own team has built and deployed. Searching looks across both at once. Apps published by Avi include: | App | What it does | |---|---| | **AWS** | Read anything in a connected AWS account, plus background monitoring — error spikes (including your own custom error metrics), firing CloudWatch alarms, security findings, and critical changes surfaced into the project feed. | | **Code** | Your GitHub, inside Avi. Connected accounts' repos, pull requests, issues, code files, and search — browsable in the panel (fully voice-operable) and readable by the agent, with PR reviews, merges, and issue writes from chat — and meaningful repository activity (merged pull requests, releases, issues) feeding the project's Updates. Connect GitHub once and it all just works. Set up a **Factory** on one or more repos in the Code panel and it turns issues into reviewed pull requests, each built in its own Coding Sandbox. | | **CRM** | Your organization's book of business — companies, contacts, pipelines with stages, deals, and an activity log. Works standalone (Avi is the system of record, shared across every project in the org), or connected to your own CRM (HubSpot today): everything is read from and written straight to your CRM, so what you see is always what it holds — nothing is copied or synced. Includes a panel for deals, contacts and companies. | | **Freshdesk** | Support tickets — list, create, and update them, with new and updated tickets surfaced into the project feed. A reply to a customer goes out only once you OK it. | | **Drive** | Always on. Your files, documents, and notes in one place — one tree, searchable end to end, with Google Drive and ShareFile mounting in as roots when connected. | | **Email** | Always on. A real inbox on the project's own avi-mail.com address out of the box, or switched to your connected Gmail — one inbox per source, reviewable drafts, and spam that never sneaks in. | | **Messages** | Always on. Chat with other orgs on the project's own @handle out of the box, blended live with a connected Slack workspace — one inbox, channels and DMs across both. | | **Calendar** | Always on. Your calendar and scheduling, standalone or on Google Calendar. View and manage events (multiple named calendars with colors, recurrence, attendees, all-day spans) with a draft-first review loop and an agenda panel; bind a Google account to work live against Google Calendar instead of the built-in store. Plus the scheduling layer: shareable video-meeting links (a connected Zoom account mints real Zoom meetings, no calendar event required) and a public booking page — anyone picks a time from your real availability, confirmed bookings land on the active calendar with the visitor invited, and you choose whether booked meetings carry a Google Meet or a Zoom link. | | **Resend** | Marketing email broadcasts through your Resend account. Ask the agent to draft a broadcast — the email template, subject, and audience segment — then review it in the Resend panel: see exactly what will go out and send it yourself with one click. Nothing sends without you. Delivery and engagement analytics live in Resend's own dashboard. | | **Sentry** | Your Sentry errors, inside Avi. Browse and filter issues in the panel, read the latest stack trace, breadcrumbs, the distributed trace it happened in, and tag breakdown, and resolve, archive, assign, or comment, by hand or by asking Avi. Avi can also search spans and read whole traces to answer performance questions. New issues are checked every 15 minutes and show up in the project feed. | | **Social** | Your social presence in one place — X today, more networks to come. Connect one or several accounts; follow mentions, lists, searches and timelines on a voice-driven board; read mentions and replies; draft posts that Avi publishes only when you say so; and get briefings on what your board is following. | ### The Social app Connect your X account from the Social app's settings — one click through X's consent screen, nothing else to set up (the platform provides the X API access and covers its usage). Connect several accounts if you speak from more than one. If you connected before list columns existed, reconnect once to grant list access. Once connected: - **The board.** A deck of live columns, one feed each: your mentions, your home timeline, one of your lists, a search on a topic, or a user. Add as many as you like, reorder and resize them from the column menu, and sort any column by latest or top (top ranks the loaded posts by likes, reposts and replies; a search column asks X for its most relevant posts). Every column has a filter (original posts, replies, reposts, quotes, media, links) you can drive by voice, and leaves out posts from accounts that look like bots or spam unless you ask to include them: *"show filter"*, *"only replies"*, *"no reposts"*, *"clear the filters"*. Removing a column always confirms first. Posts read like they do on X, with photos, videos, quoted posts, X Articles, link previews and the reply, repost, like, views and share icons; like or repost straight from the feed, and links to X posts, articles and profiles open right in the app. Opening a post shows the posts it answers above it and its replies below as conversations (for posts from the last seven days), top replies first; open any reply to follow it further. Everything works by voice, instantly: *"scroll economics down"*, *"scroll the second column to the top"*, *"select economics"* then *"scroll down"*, *"make wider"*, *"move left"*, *"sort by top"*, *"refresh column"*, *"next column"*, *"add a column"*, *"pause economics"*, *"open the third post"*. - **Your activity flows into the feed.** New mentions and replies on your threads land in the Activity tab and in the project's Updates, grouped with related email and chat activity about the same matter. - **Briefings from your board.** Every search, list, mentions and home column on the board is checked about once an hour and, when something noteworthy happened, a short briefing lands in your feed: the themes, the notable voices, the posts worth reading. Nothing to set up — add a column to get its briefings, remove it to stop. Quiet columns are checked less often until they pick up again. - **Posting costs are always surfaced.** X charges much more for posts containing links ($0.20 vs about $0.015) — Avi will always tell you and ask before sending one. - **Drafts.** Ask Avi to draft a post or a whole thread and it lands in the Social app's **Drafts** tab — with a preview that looks exactly like it will on the network: threads, reply context, photos, GIFs and videos (from Drive or a link, on any post of a thread), character counts. Avi links you straight to any draft it creates; when you're happy with one, ask Avi to post it, photos and videos included. - **Avi never posts on its own.** Posting is refused outright for any background or automated caller — publishing works only when you explicitly ask in chat. ## Building your own You can build and deploy your own apps — an internal API, a vendor Avi doesn't cover yet, a custom panel — with the [Avi CLI](/docs/apps). Your team's deployed apps show up in project settings next to Avi's, and enable the same way. ## Reading an app's documentation Every app ships its own documentation, and it updates automatically with every new version of the app — so what you read always matches what's deployed. Each app has an **intro page**: an overview written by the app's author, framed by a generated header (name, one-line summary, version, last updated) and a generated reference of every tool, setting, webhook, and data store the app ships. Deeper pages cover things like how its integrations authenticate, what runs on a schedule, and troubleshooting. You'll find it in three places: - **Discover** — open any app from the Discover tab to read its full intro page before enabling it. - **The app's Docs tab** — for apps your org built, the org settings app detail has a Docs tab with every page. - **The agent** — project agents read the same docs, so you can just ask ("how does the Calendar app decide what to sync?") and the agent consults the app's documentation before answering. ## Enabling an app In a project's settings → Apps, press **Enable** on the apps you want. Enabling an app: - **Turns on all of its tools at once** — the agent can use the whole app immediately, with no need to enable each tool by hand. (You can still turn individual tools off afterward — see below.) - May ask you to approve the app's **capabilities** — what the app is allowed to read and write. If a later update to the app requests new capabilities, the project re-approves them before the app runs again. Apps made by Avi, like Drive, Email and Calendar, never ask: they come with the access they need, including after updates. - May add its own panel to the project, opened from the rail. - May require you to connect an account (e.g. linking GitHub or HubSpot via OAuth). - If the app does background work on a schedule, enabling it kicks off a first run right away — you don't wait for the next scheduled tick. Each project remembers which panel you had open — and where you were inside it. Switch projects and come back, reload, or share the URL: the panel reopens exactly where you left it (the open panel and its view live in the page URL). ## Connecting an account Some apps run on an outside service — the Email, Calendar, and Drive apps on a Google account, Messages on Slack, CRM on HubSpot, Code on GitHub, Social on X. You connect that service from the app itself: its settings screen shows the account as a row with a **Connect Google** (or whichever service) button: pick what to share, sign in at the service, and you land straight back on the app's settings screen. One sign-in sets up every app that uses it. The consent screen lists what the service can share, and each row names the apps that will be set up with it — connect Google from Email with Calendar and Drive ticked, and all three are configured the moment you return. Connect Drive later and the same Google account simply widens. Each connected account shows up in every app that uses it, with **Also used by** naming the others. **Use here** puts it to work in this app, and **Stop using** takes it out of this one (that app goes back to running on its own). The row's **⋮** menu holds the rest: **Reconnect** goes straight to the service's sign-in with the access the account already has, and every app using the account picks it up at once; **Permissions** changes what the account shares; **Disconnect** removes it from the project and every app bound to it. If an account loses access — you changed your password, or removed Avi's access at the service — every app that uses it shows a **lost access** strip across its top with a **Reconnect** button. Reconnect once, from any of them, and they all come back. Connected accounts only ever reach Avi's own apps. An app from any other publisher connects to its services with its own credentials — its settings screen says so instead of offering your accounts. Beyond connections, an app's settings screen holds any other options the app offers. For example, the Email app lets you toggle the small "(Email by Avi)" signature it appends to emails it sends and drafts — it's on by default, and you can switch it off there. Some apps ask for a credential that isn't an OAuth connection — an API key or token you hold. Those settings are a dropdown over the project's **Secrets**: add the key under the project's Secrets tab first, then pick it in the app's settings. The app only ever stores a *reference* to your secret — it can't read your other secrets, and the actual value stays protected by Avi and is handed to the app securely each time it runs. If the dropdown is empty, add a secret first. ## Tool-level control Enabling an app switches all of its tools on for you. If that's more than you want, you can disable individual tools inside it — useful if you want the agent to *read* from a service but not *write* or *delete*. Use the **Tools** tab in the project's settings. ## Webhooks Some apps receive events from an outside service in real time (for example, a support desk pushing new tickets). When an app does, its settings page shows a **Webhooks** section with one entry per webhook: - **URL** — a unique, secret address for this project. Copy it into the outside service's webhook settings. Because the URL is secret, treat it like a password. - **Rotate** — generates a fresh URL and immediately disables the old one. Use this if a URL might have leaked; then update the outside service with the new URL. - **Enable / Disable** — Disable is an instant off-switch: deliveries to that URL stop being accepted. - **Secrets** — some apps ask you to bind a vendor secret (e.g. a "signing secret" the service gives you) so the app can verify each delivery is genuine. Pick the matching **project secret** from the dropdown. If it isn't listed yet, add it first under the project's Secrets, then come back and select it. Deliveries only flow when the app is enabled and the webhook is active. ## What apps the agent can actually use For a tool to be callable, two things must be true: 1. The app it belongs to is enabled in this project. 2. The specific tool is permitted in this project. Both gates matter. Turning off a single tool is a quick way to keep the rest of an app's capabilities while blocking one risky one. --- # Files Every project can have files the agent can read, write, and edit. They're stored in Avi's cloud storage, scoped to your project. The agent can: - Search and list files across the project — one federated search that also covers a connected Google Drive or ShareFile account. - Read any file. Text files (markdown, CSV, JSON, code, etc.) come through as text. **Images are seen directly, and PDFs are read on any model — their text, or the page itself when it is a scan.** Word, Excel, and PowerPoint files (.docx/.xlsx/.pptx) are read as extracted text — spreadsheets come through sheet-by-sheet so Avi can reason over the rows — and when layout matters (a table, a slide, a chart), Avi can look at the file as rendered pages instead. Avi can also check a file's size, checksum, and an image's pixel dimensions without reading it. Avi can also change the wording of a Word document for you, in place, with its formatting preserved. - Write new files (text, or binary from generated bytes) and download files from the web by URL. - Edit parts of existing text files in place. - Create notes, make business documents — quotes, invoices, engagement letters and more — as Word documents from your own templates in Avi's document design (working out every amount and total itself; a detail it doesn't have — your address, a phone number — is left out rather than left blank, and added when you give it; the typeface travels inside the file, so it looks right for everyone), and produce new files as it works — exported PDFs, converted or resized images, Office files exported to PDF or converted between formats (an old `.doc` to `.docx`, a spreadsheet to CSV). - Fill out fillable PDF forms, accurately and completely (see [PDFs](#pdfs)). - Move and rename files or whole folders (moving a file under the Google Drive or ShareFile root uploads it there). - Delete files (recoverable for about a week — ask Avi to undo a delete, or restore from Drive's Recently deleted). - Create and change Excel workbooks: values and formulas, rows and columns, formats, sheets, tables, dropdowns, highlighting rules, charts and summaries, with every formula recalculated (see [Excel workbooks](#excel-workbooks)). - Write and format Word documents with real styles, numbered clauses, lists, tables, and page numbers; redline them with tracked changes in your name (and a clean copy that carries no editing history); comment, reply, and resolve; compare two versions; and export to PDF, PDF/A, A4, or one section. All of this happens through the **Drive** app's tools — files (Word documents included) and notes are one tree with one set of tools. ### Getting files in There are four ways to put a file into a project: - **Drive panel**: open the Drive app from the rail and drag files in (or pick from your computer). They appear in the tree and are immediately readable by the agent. - **Paste or drop in chat**: paste a screenshot from the clipboard, or drag a file onto the chat composer. Attachments are saved into the project's **`Attachments/` folder** automatically, so they show up in Drive and Avi can come back to them in later conversations. Limits: 8 attachments per message, 10 MB each, 20 MB in all. Very large images are automatically downscaled before they're shown to the model (the stored file keeps its full resolution). - **Let the agent create them**: Avi can write new files as it works (a generated report, a chart, a transformed CSV). - **Pull them in from connected apps**: with the Email and Drive apps connected to your Google account, ask Avi to save an email attachment, a Google Drive file, or a ShareFile file into the project — "grab the invoice PDF from Dana's email and review it". The file lands in the project's files (email attachments default to the `Attachments/Email/` folder), and since PDFs and images are read natively, Avi can review the contents right away. Email attachments up to 10 MB; Google Drive and ShareFile files up to 32 MB. Files persist for as long as the project exists. ### Getting files out Project files also travel the other way. With the Email and Drive apps, Avi can **attach project files to emails** it sends or drafts ("send the Q3 report to Dana as an attachment" — up to 10 files and 18 MB of attachments per email) and **move project files to Google Drive or ShareFile** byte-exact, including binary files like PDFs and images; the project copy is removed once the upload lands. ### Editing files safely When Avi edits part of a file in place, it has to point at a snippet that's unique in the file — otherwise the edit might land at the wrong copy of a common phrase. If your file has the same exact line in two spots, Avi will ask for more context to disambiguate, or you can tell it explicitly to replace every occurrence. Edits and overwrites are also protected against collisions: if a file changed between Avi reading it and writing it back (say, a teammate re-uploaded it), the write is refused and Avi re-reads before retrying — so nobody's changes get silently overwritten. **A file you have open follows a rename.** If Avi (or you, in another tab) renames or moves the file on screen, the view moves with it and says where it went — it never closes as if the file were gone. **Nothing is lost when a file is replaced.** Whenever Avi overwrites, edits, or replaces one of your files, the previous version is kept in a hidden working area for about 7 days (the twenty most recent versions of a file that changes a lot) — open **Working files** from the Drive panel's root menu to see it, and ask Avi to restore it if a change should be undone. Avi also uses the same area to stage things it produces (a converted image, a filled PDF) so it can double-check the result before placing it in your tree; anything left unplaced cleans itself up after a week. **Notes get the same protection.** Avi can't replace a note's whole body without having just read it — a blind rewrite is refused outright, and targeted edits only ever change the exact passage they name. Whenever a note's content does change, the previous body is kept in the same working area for about 7 days, so any edit can be undone by asking Avi to restore it. ### Word documents Avi works on Word documents (.docx) itself, right in the conversation — there is no separate agent to hand the work to, and the answer comes back in the same reply. When a request is about a document (you mention one, attach one, or have one open in Drive), Avi brings its Word know-how to it automatically. - **Everyday changes.** "Change 30 days to 45", "add our address to the letterhead", "make the headings dark green", "the pricing table should be one row and a total" — done in place, in seconds, with the formatting kept. - **Rearranging.** "Delete the second paragraph under Terms", "put these four lines in two columns", "move the client details to the top right", "move Terms above Pricing", "turn this list into a table" — paragraphs and tables can be removed, moved, and rebuilt; lines that are only being moved keep their formatting exactly. - **Business documents from your templates.** Quotes, estimates, engagement letters, statements of work, invoices, one-pagers, and cover letters, made from your own template (your own template for a document type is what Avi starts from — the built-in design only when you have none; or whichever you mark as the default for that type) in your `Documents` folder. Avi fills in every detail it knows, writes the line items, and works out every amount, tax, and total itself. Templates are covered too: making one, changing its wording, giving it a logo, making it the default. - **Tracked changes.** "Redline", "mark up", or "propose" means tracked changes on the document itself, one per change you asked for, credited to you. Avi never rebuilds the document or renumbers clauses you did not mention. Templates are changed directly, never with tracked changes. - **Comments**: adding, replying, resolving. - **New documents** with real headings, numbered clauses and numbered lists. - **Accepting or rejecting** changes, and producing a clean copy with the editing history scrubbed. - **Comparing two versions** into a redline, when you give it both. - **It looks at the pages.** After making a document or changing its layout — a new row, a signature block, a moved section — Avi looks at pictures of the pages the change landed on before answering: that the change is there, that it matches its neighbours, that nothing was pushed onto a new page or cut in two. If something is off it fixes it once more and looks again; if it still is, it tells you exactly what. - **PDFs only when you ask.** A document is done as a Word file you open in Drive; it exports to PDF (clean, archival PDF/A, A4, one section, with bookmarks) when you say so, never on its own. When you change a document that has a PDF of it beside it, Avi tells you that PDF still shows the old version. It works the way a document professional does: one tracked change per edit, never accepting its own changes, never touching the other side's changes or comments unless you say so, and a clean copy only when you ask. When an edit moves clause numbers or touches a defined term, it lists the cross-references for you to decide on rather than changing them silently. When something can't be done with a Word document yet (a footnote, an image in the text, merged table cells), Avi says so plainly instead of trying things out on your file. ### Excel workbooks Avi works on Excel workbooks (.xlsx) itself, right in the conversation. When a request is about a spreadsheet (you mention one, attach one or a CSV, or have one open in Drive), Avi brings its Excel know-how to it automatically. - **New workbooks.** "Make a budget tracker for the first half of the year", "build a price list with a margin column", "turn this CSV into a spreadsheet with totals" — a real workbook with a header row, number formats, and formulas for everything that is calculated. - **Everyday changes.** "March rent went up to 2,400", "add these three orders", "add a tax column at 8%", "sort by amount, largest first" — done in place. New rows go above the totals row and the totals grow to cover them. - **Formulas, not typed-in numbers.** Totals, margins, lookups and summaries are written as formulas, so they keep working when you change the data. Avi never types a number over a formula without telling you. Ask for a calculated number to come out at a target ("make the total 250,000") and Avi says what it is calculated from and asks which numbers to change before changing any. - **Always recalculated.** Every change is recalculated straight away, and Avi reports the numbers the formulas now show. A change that would leave a new error such as `#REF!` or `#DIV/0!` is not saved; Avi fixes it or tells you why. - **Rows, columns and sheets.** Insert or delete rows and columns, rename, add, copy, hide or delete sheets — every formula, chart and named range that pointed at the moved cells follows. - **Summaries.** "Revenue and order count by region on a summary sheet" — built with live formulas, and a chart if you want one. - **Formatting and rules.** Currency, percent and date formats, column widths, frozen headers, filters, tables, dropdown lists, and highlighting rules ("flag anything overdue in red") that stay true as the data changes. - **Charts.** Column, bar, line, area, pie, doughnut and scatter charts, as real Excel charts that follow their data. - **Questions.** "Which month had the best margin?" — answered from the cells, naming where the answer was read. - **A real spreadsheet view.** In Drive a workbook opens as a grid with sheet tabs and a formula bar. Click a cell, type, press Enter — it saves and recalculates. Select cells and ask Avi about "these". Highlighting rules show in the grid, including ones that light a whole row or match text. Charts, data bars and top-10-style rules aren't drawn in the grid; Export to PDF (in the ⋮ menu) shows charts. - **Everything else is left alone.** Charts, pivot tables, macros and pictures already in your workbook are kept exactly as they were. A few things Avi can't do in a workbook yet, and says so rather than trying things out on your file: creating or changing pivot tables (it builds the same summary with formulas instead), changing an existing chart's design, editing macros, and opening password-protected workbooks. Older `.xls` files are converted to `.xlsx` first. Excel recalculates everything again when you open the file, so its numbers are always the final word. ### PDFs Avi reads PDFs, fills their forms, writes on their pages, and signs them — and shows you a picture of what it wrote before calling it done. - **Reading.** Ask what a PDF says, or anything about it — a schedule, a contract clause, an invoice total. Avi reads the text of the pages it needs, on any model. A scanned page has no text to read, so Avi looks at the page itself, the way you would. - **Any PDF you throw at it.** Files locked against editing read like any other. A file that needs a password to open: give Avi the password and it reads it. A damaged file (cut short, exported badly) is repaired and read. Sideways and cropped pages are handled. - **Filling forms.** Avi reads the form's real field list — each field with the words printed beside it — so every value goes in the right field, even when the fields have cryptic internal names. A fill is all or nothing: a value that doesn't fit its field (a choice that isn't one of the options, text longer than the field allows) stops the fill, and Avi fixes it first. Every value is read back from the saved file, and Avi tells you which fields are still empty. - **Writing anywhere.** On a flat or scanned form — no real fields — Avi writes straight onto the page: a name in the blank after "Name:", a date beside a signature, an X in a printed checkbox, an image. It places things against the words printed on the page, so they land on their lines. - **Signing.** "Sign this for me" puts your signature on the document's signature line: your name in a handwriting style, or your own signature image if you've saved one in Drive (a PNG with a transparent background works best). When a document has more than one signature line, Avi asks whose is whose rather than guessing. This is a visual signature — how a signed page looks — not a certificate-based digital signature. Avi only ever signs as you, and only when you ask: asked to sign for someone else, it declines and offers to send them the document to sign themselves. - **Checked before it's done.** Avi won't write over existing words or off the edge of a page, and every write is verified by comparing the page before and after. Then Avi looks at a picture of each place it wrote, and fixes anything that sits wrong before telling you it's finished. - **Your original stays safe.** Changes are made on a working copy. Avi saves the result beside the original under a clear name — a filled form as "… (filled).pdf", so the blank stays blank — or replaces the original when that's what you asked for (the previous version is kept for about a week). - **Your call.** A form the publisher marked against changes, or a document that already carries a digital signature, is only changed after you say so — a change removes the protection or invalidates the signature. - **Pages.** Merge PDFs, pull out or reorder pages, rotate a sideways scan. The originals are never modified. - **International text.** Names in Cyrillic, Greek, or extended Latin alphabets (ł, ő, đ…) are written correctly. Not yet: turning a long scan into searchable text, changing words already printed in a PDF, redacting (a box drawn over text leaves the text in the file, so Avi won't pass one off as a redaction — it suggests removing it from the source document instead), certificate-based digital signatures, and Adobe "LiveCycle" (XFA) forms. Avi says so when it meets one. ### Getting documents signed by others Connect a ShareFile e-signature account (RightSignature; Drive → settings → E-signature) and Avi sends documents out for other people to sign, straight from the conversation. - **Ask for it.** "Send the Globex agreement to Dana at Globex and Casey to sign." Avi finds the signature lines on the document, marks where each person signs (and dates), and shows you the marked page — each box named for its signer — with a link to the file, before anything goes out. A Word document works too — it is sent as a PDF; your original is never changed. - **You say send.** Nothing is emailed until you've seen who signs where and said so. RightSignature then emails each person their own signing link. - **Follow it.** "Has everyone signed?" tells you where it stands, read from RightSignature. "Remind them" nudges whoever hasn't signed. "Cancel it" voids the request. - **It comes back on its own.** When everyone has signed, the signed copy and the signature certificate are saved beside the original as "… (signed).pdf" and "… (signature certificate).pdf". - **When Avi can't find the place.** It asks you where each person signs, or hands you RightSignature's own screen to place the fields on that document — Avi still tracks it from there. This is different from "sign this for me", which puts *your* signature on a page as a picture. Signatures from other people go through RightSignature, with their emails, links and certificate. Only RightSignature is supported today, and its API needs a ShareFile plan that includes e-signature. ### Finding files Avi's project-wide search covers files too — by name, and by content for text files. "Find the Q3 budget spreadsheet" works even when the filename doesn't say Q3. ### Large files Avi can read very large text files (logs, big CSVs) in pages — by byte range — rather than swallowing the whole thing at once. You don't have to think about this — Avi will page through automatically when a file is big. ### Browsing files Your project's files live in the **Drive** app alongside your notes, document templates, and connected cloud storage — one tree for everything. Select text in an open note or Word document and Avi knows what "this" means: ask "rewrite this" or "what does this clause say" and it works on exactly the highlighted part. Your files are yours until you share them: a file, a folder, or a document template can be shared with specific people or with everyone in your org, to view or to edit (**Share…** in its menu). What others share with you is in **Shared with me** at the top of your Drive. Open Drive from the rail to browse folders, preview files inline (images, PDFs, and Word documents render right in the panel — and a `.docx` can be edited and saved in place), download, upload by drag-and-drop, and manage folders. For the full tour, open Drive in the project's settings → Apps to read its own docs, or just ask Avi. The `Attachments/` folder is special: chat uploads land there and messages reference those paths permanently, so it can't be renamed or deleted. ### Custom metadata on files Every file carries a freeform `metadata` JSON object ([Data Types](/docs/data-types)). Use it to attach cross-system identifiers (`stripe.invoice_id`, `hubspot.attachment_id`), workflow state (`reviewed_by`, `team_owner`), or any tag you'll later want to filter on. Two systems writing different top-level keys never clobber each other. You can read or write a file's metadata from the agent (Avi sets keys as part of a file write, patches them alone, sees each file's bag in listings, and filters listings by metadata containment), or from apps. See the [Data Types](/docs/data-types) page for the full merge semantics and query shape. When you list a directory with a metadata filter, **directories with no matching files inside are hidden** — the filtered view is focused, not a tree of empty folders. List without a filter to see the full structure. --- # Data Types Avi is built on a small set of native data types that every project has from day one. The agent reads and writes them, apps extend them, and you can query them — they're the shared substrate the whole platform sits on. ## The native types - **Events** — an append-only log of everything that happens in a project: messages received, automation runs, deploys, app activity. Events are immutable and carry a structured payload. Apps publish them, and Avi's curation engine reads the log to build the [Updates](/docs/updates) feed. - **Files** — documents, images, PDFs, and data stored in the project. The agent reads them (PDFs and images natively), writes and edits them, and searches across them. See [Files](/docs/files). Three more types were once built into every project and now live in **apps**, each owned by the app for its domain — the records, panels and tools carried over unchanged: - **Tasks** — to-dos you and the agent track together: a name, notes, a priority (1–4, higher is more important), and subtasks. In the always-on **Tasks** app; see [Tasks](/docs/tasks). (For work that *runs* on a schedule, see [Automations](/docs/background-agents).) - **Contacts** — the people this project deals with: names, emails, phones, companies, tags, and notes, standalone or synced with Google Contacts. In the always-on **Contacts** app; see [Contacts](/docs/contacts). - **Notes** — free-form documents like meeting notes, runbooks, plans, and drafts. In the **Drive** app, alongside your documents and connected cloud storage. Everything that existed before each move was imported automatically, and old links open in the owning app. ## Custom metadata **Files** also carry a `metadata` field: a freeform key-value bag where apps, integrations, and your own code can store arbitrary data alongside each file. This is how Avi stays the most extensible AI assistant for real work: every file can be tagged, joined, and queried by the systems your team already uses — Stripe, HubSpot, Linear, Intercom, anything — without modifying the schema. ### What `metadata` is A JSON object on every File. The shape is open — you decide what goes in it. ```json { "stripe.invoice_id": "in_NffrFeUfNV2Hib", "hubspot.deal_id": "1234567", "team_owner": "alex@acme.com" } ``` There is no schema. There's no registry. You just write the keys you need. ### Convention: prefix your keys The platform doesn't enforce anything, but the universal convention is to **prefix your keys with a namespace** so two systems writing to the same file don't accidentally collide: - `stripe.customer_id` - `hubspot.deal_id` - `internal.priority_score` Pick something obvious (your tool name, your team) and stick with it. ### Writing metadata Every file write accepts an optional `metadata` field. From an app (with the `project:files:write` capability): **On create**, you supply the initial object: ```ts await context.projectFiles.put({ path: "invoices/2026-q1.pdf", data: pdfBase64, encoding: "base64", metadata: { "stripe.invoice_id": "in_NffrFe…" }, }); ``` **On update**, `metadata` is a **shallow merge patch**, not a replace: - Each top-level key you supply REPLACES the value at that key. - A `null` value DELETES that key. - Keys you don't mention are left untouched. - `null` ANYWHERE in the patch is stripped — including nested. `{ stripe: { token: null } }` stores as `{ stripe: {} }`. If you need to keep a `null` somewhere nested, just don't write it; store an explicit sentinel value instead. ```ts // Adds stripe.invoice_id without disturbing anything else await context.projectFiles.updateMetadata({ path, patch: { "stripe.invoice_id": "in_NffrFe…" } }); // Removes a key await context.projectFiles.updateMetadata({ path, patch: { "stripe.invoice_id": null } }); ``` This is the important property: **two apps writing different top-level keys never clobber each other**. Stripe's tool can write `stripe.*` while HubSpot's tool writes `hubspot.*`, and neither has to know the other exists. Files keep metadata beside the file, not in its bytes — so renames, moves, and re-uploads all preserve it. An app can set metadata alongside a write or patch it on its own, and the agent can do both when you ask. On re-upload of the same path, the new metadata is merged into whatever was already there. ### Querying metadata Listing files accepts a `metadata` filter. It matches files whose metadata **contains** all the key/value pairs you supply (JSON containment). ```ts // All files a review app has signed off on await context.projectFiles.list({ metadata: { "review.approved": true } }); ``` The matching is exact at each key — pass the value you stored. Nested objects compare by structural containment, so `{ stripe: { customer_id: "cus_…" } }` matches a file that has at least that nested shape. ### When to use it - **Cross-system identifiers.** The single most common use: storing the id another system uses for the same thing, so you can round-trip between Avi and that system. - **App-defined fields.** An app wants to attach a `priority_score` or `triage_status` without needing a new column. - **Ad-hoc tags or hints** the agent or your apps will later filter on. ### When not to use it - **Real first-class fields.** If a value belongs on every record of a type, it belongs in an app's own data, not in file metadata. Metadata is for the long tail, not the spine. - **Anything secret.** Metadata is plaintext and visible to anyone who can read the file. Secrets belong in **Secrets**, not metadata. ### Where it works Metadata as described here is a Files feature. Events and Updates aren't part of this surface: events are immutable log entries that carry their own structured payload rather than an editable metadata bag. --- # AI Models Avi ships its own catalog of top-tier models. You don't bring your own API key — Avi is the provider, and usage consumes credits at each model's own rate. See [Billing](/docs/billing). ## Catalog | Model | Best for | |---|---| | **Claude Sonnet 5** | The default. Balanced reasoning and speed. Works well for almost everything. | | **Claude Sonnet 5.5** | The newest Sonnet: an upgrade over Sonnet 5 at the same credit rate, and faster. Balanced reasoning and speed. | | **Claude Opus 5.5** | Hardest problems. Long-running coding and knowledge work, complex reasoning, high stakes; reports back clearly on what it did. Uses more credits per token. | | **Claude Fable 5.1** | For the hardest, highest-stakes work; among the priciest per token. Needs your org's data-retention opt-in first (see [below](#claude-fable-51-and-data-retention)). | | **Claude Haiku 5.5** | Fast, cheap, light tasks. Good for quick lookups or high-volume work. | | **OpenAI GPT-5.6 Sol** | OpenAI's flagship for ambitious agentic work. | | **OpenAI GPT-5.6 Terra** | Balanced OpenAI model for efficient, high-volume work. | | **OpenAI GPT-5.6 Luna** | Fast, affordable OpenAI model for everyday work. | | **OpenAI GPT-6 Astra** | OpenAI's most capable model. The hardest end-to-end reasoning, coding, and research work. Among the priciest per token. | | **OpenAI GPT-6 Sol** | OpenAI's daily model for complex coding and agentic workflows. GPT-6 intelligence at a fraction of Astra's price. | | **OpenAI GPT-6.1 Sol** | The upgraded GPT-6 Sol: close to Astra on coding, computer use, and professional work at about a fifth of Astra's price. | | **OpenAI GPT-6 Luna** | OpenAI's most efficient GPT-6. Summarization, extraction, classification, routing — high volume, very cheap. | | **GLM 5.3 Flash** | Frontier open-weight reasoning at a fraction of the cost. Fast, very cheap. | | **GLM 5.3** | Z.ai's open-weight flagship. Stronger reasoning than Flash, still affordable. | | **GLM 5.3 Fast** | GLM 5.3 on dedicated capacity for higher sustained throughput. Same reasoning, faster. | | **DeepSeek Flash 4.1** | DeepSeek's newer Flash generation. Cheap, fast, for high-volume everyday work. | | **Kimi K3** | Moonshot's open-weight flagship. Deep reasoning and long-horizon agentic work. | ## Picking a model - **Start with Sonnet.** It's the right call most of the time. - **Upgrade to Opus** when a task is hard, multi-step, or the stakes are high enough that you'd want a second opinion. - **Drop to Haiku** when you want fast and cheap — short summarizations, quick lookups. - **Try GPT-5.6 Sol** for advanced coding, research, and long-running agentic work. - **Audio or video? Use a Claude or GPT model.** The open-weight models (GLM, DeepSeek, Kimi) read text and images, including images from your files, but not audio or video. PDFs work on every model: Avi reads their text and looks at their pages as pictures. When a model opens a file it can't read, it tells you so. ## Where to set the model - **Org-level default** — in org settings. Every project in the org picks this up unless overridden. - **Per-project** — override in project settings. Lets you use Opus for your most demanding project while keeping Sonnet everywhere else. - **Per automation** — every automation runs on **GLM 5.3 Flash** unless you pick another model on its Setup tab. It never follows your chat model. See [Automations](/docs/background-agents). Voice turns use the project's configured chat model too — speaking to the agent and typing to it go to the same model. ## Claude Fable 5.1 and data retention Every model in the catalog runs without its provider keeping your prompts or training on them — except Claude Fable 5.1, which is only served with data retention on: the model provider keeps prompts and outputs from Fable 5.1 requests for 30 days for safety monitoring. Only Fable 5.1 is affected; no other model's data handling changes. Until an org owner or admin turns on **Claude Fable 5.1 data retention** in org settings, nobody in the org can select it. Turning it off makes Fable 5.1 unavailable at once. ## Background work Some of Avi's work happens without you asking: sorting events into your feed, summarizing long conversations, telling whether a second thing you said finishes the first, and app chores like labeling a new task. All of it runs on **GLM 5.3 Flash**, whatever chat model you pick, and it's billed at GLM 5.3 Flash's rates. The updates in your feed are then written by **Claude Sonnet 5.5**. If your org's **Allowed models** list leaves out GLM 5.3 Flash, that background work pauses, feed updates included, until an owner or admin allows it again. Leaving out Claude Sonnet 5.5 pauses the feed's updates the same way. Your chats keep using the models you allowed. An automation on the default needs an allowed model picked on its Setup tab. --- # Billing Avi has one plan. You start on **trial credits**, and when they run out you **subscribe** — $99 per person per month, or $79 per person per month billed annually. Everything Avi does draws from a single pool of **credits**: chatting, tools that call a model, automation runs, web searches, and app actions. Your **account** carries the credit balance, and every feature is available whether you're on trial credits or subscribed. ## Credits - **AI requests** consume credits based on the model and how much work the request does — a typical chat turn is 5–30 credits, more for multi-step tool use. Each model has its own rate in credits per million tokens, so a fast model costs a fraction of a frontier one. - **Web search and app actions** (posting to X, hosting a site, and so on) run on the same credit system and are included at no charge today. - One credit is one cent of usage: a $25 top-up is 2,500 credits. - Automations each carry a **daily credit ceiling** — 100,000 credits a day by default, on every model — so nothing can quietly run away — see [Automations](/docs/background-agents#max-daily-spend). ## Your trial - **1,500 credits** when you create an account. No card required. - **1,500 more when you connect your first account** — see below. - Trial credits expire 30 days after they're granted. Everything works during the trial: every model, every app, teammates, automations. - When your trial credits are gone, subscribe to keep going. ### The first-connection offer Avi is at its best when it can see your email and calendar — that's when morning briefings, meeting prep, and "what needs a reply?" start working. So the first time your account connects Google (or Microsoft), Avi adds **1,500 credits** to your trial. Once per account. Connecting Google also sets up your Email, Calendar, and Drive apps automatically — see [Getting Started](/docs/getting-started). You stay in control: the connect screen lets you choose exactly which permissions to grant, and you can disconnect anytime from the settings of the app that uses the account. ## Subscribing — $99 per person per month - **$99 per person per month**, or **$79 per person per month billed annually** ($948 per person per year). Choose either at checkout. - **10,000 included credits per person every month**, pooled across everyone on your account and every org under it. Five people = 50,000 credits a month that anyone can spend. On the annual plan the credits still arrive monthly — paying yearly changes the price, not the pace. - Everyone you invite is a person on your subscription. Adding someone mid-cycle takes effect immediately; you're billed for the seat in full at your next renewal — no prorating, no partial-month math. - **Top-ups**: when you need more than the monthly grant, add 2,500 credits for $25 any time from the Billing page. Top-up credits never expire. - **Auto-refill** (optional): when your available credits drop to 200 or less, Avi charges $25 and adds 2,500 credits automatically. It's capped by a monthly budget you control (default $100) so surprises are bounded. - Cancel or update your card any time in the Stripe Customer Portal. ## How the numbers work The Billing page shows your credit picture in a few numbers: - **Monthly Credits Used** (subscribed) — how many credits you've spent this month against the included grant (`people × 10,000`). If you add someone mid-month, the grant grows right away. - **Trial Credits** (on trial) — what's left of your trial, and when it expires. - **Extra Credits Balance** — your persistent pool: top-ups, auto-refills, and any promo grants. Never expires, carries across cycles. Credits are spent in that order: the monthly grant first, then trial credits, then extra credits. At cycle end, the monthly grant resets; unused monthly credits don't roll over (they're part of your subscription, not a balance you own). Extra credits always carry over. ## Where to manage it - **User Settings → Billing** — see your trial or subscription, credit usage, daily breakdown, subscribe, toggle auto-refill, top up. - **Manage Billing** button — opens the Stripe Customer Portal. From there you can update your card, view past invoices, or cancel. - **Org Settings → Analytics** — per-org credit usage if you want to understand spend by project. ## Inviting teammates Anyone can invite teammates, on trial or subscribed. Each person you add shares the account's credits. If you're subscribed, the new seat activates on accept and appears on your next invoice at your per-person rate; removing a member drops your seat count at the next renewal (no mid-cycle refund). ## Who can change billing Billing is **account-scoped** — the account owner is the only one who can subscribe, cancel, top up, or update the card. Exactly one owner per account. --- # Appearance Avi has four themes: **Light**, **Dark**, **System**, and **Natural**. Switch between them in the account menu. ## Light, Dark, and System **System** is the default: it matches your device's light or dark setting. **Light** and **Dark** keep Avi in one look all day. None of them color the interface. In the Avi mobile app, the theme follows your phone's light or dark setting. ## Natural Natural follows the time of day where you are: - **Light by day, dark by night.** The app is light from 6 am to 7 pm and dark overnight. The switch happens at the same times every day, so you always know what to expect. - **A living sky.** The whole window is lit by a sky that changes through the day — soft peach and periwinkle at dawn, clear blue at midday, gold and coral through sunset, deep blue after dark. The light moves continuously, so a sunrise or sunset plays out while you work. - **A landscape behind it all.** A slow, quiet landscape plays behind the window, a little stronger or softer to suit the light. It is hidden if your device is set to reduce motion, and it never plays on phones. Natural reads only your device's clock. It never asks for your location. --- # Apps If none of the [existing apps](/docs/using-apps) cover what you need, write your own. Avi's CLI turns a small TypeScript file into a deployable app that your agent can use in any project. ## The idea An app is one installable unit. It can provide **tools** the agent or a panel calls, a **background handler** woken by **triggers** (a schedule, project events, or a webhook), its own **data** stores, project **settings**, and optional **React panels**. An app also decides how its own activity is summarized in the project's Updates feed — which events matter, which are just counted. You author it locally, bundle it with the CLI, and deploy. The CLI hosts the code for you; you don't need to run any infrastructure. There is one app shape: `defineApp({ ... })`. Tools are on-demand functions. The optional `handler(event, context)` is the app's autonomous worker — Avi wakes it whenever a declared trigger fires. Everything (tools, handler, panels) shares the same app `data`, `settings`, and `capabilities`. Great candidates: - An internal API your team uses that Avi doesn't have an app for. - A proprietary workflow only your company does. - A bespoke integration — Slack automations, internal dashboards, anything. ## Install the CLI ```bash npm install -g @avi-hq/cli # or build it from source: npm -w @avi-hq/cli run build ``` ## Sign in ```bash avi login ``` Prints a link and a code. Open the link in a browser and enter the code to connect the CLI to your Avi account, then pick which org your apps belong to. `avi switch-org` changes that org later, and `avi logout` signs the CLI out. ## Scaffold an app ```bash avi init my-app ``` Writes a starter project into the current directory, with `my-app` as the app's name (without a name, the directory's name is used). Pass `--dir ` to create it in a new folder instead. Files that already exist are kept unless you add `--force`. The starter includes: - `app.ts` — the entry point where you declare app metadata plus tools, an optional background `handler` with its `triggers`, `data` stores, `settings`, and panels. - `@avihq/apps-sdk` as the authoring SDK for types like `AppToolContext`. - This SDK is type-only; Avi supplies the runtime when your app runs. - An optional `src/` area you can add later for supporting code. - A skill file for authoring agents (e.g. Claude Code) so they can help you write tools and the background handler. - A `package.json` wired up with the right scripts. ## App icon Every app **must** declare a top-level `icon` — it can't deploy without one. The icon is **an image** (no built-in glyph names): an `https://` image URL, a `data:image/...` URI, or — most common — a relative path to an image you bundle next to `app.ts`. The CLI inlines a bundled path at deploy, so you just commit the file: ```ts export default defineApp({ name: "customer-success", title: "Customer Success", // display name — free casing, shown wherever the UI names the app summary: "Flags customer accounts at renewal risk.", // the app's one-liner on every card and list icon: "./icon.svg", // bundled next to app.ts — .svg/.png/.jpg/.gif/.webp, up to 96 KB // ... }); ``` Your icon is what users see for the app across Avi — in the Apps list, the app's rail tile, and beside the updates it posts to the project feed. **Icons render monochrome, everywhere.** You supply **one** icon file, and Avi paints it as a flat silhouette in the current theme color — light and dark, active and dimmed, every surface as one set. The color in your file is never shown; only its **shape** matters. The silhouette is derived from your icon's **alpha channel**, so a mark on a **transparent background** works with no extra effort. That's the only real requirement: - Use an SVG with a **transparent background**. A `0 0 64 64` (or `0 0 24 24`) viewBox works well. Drawing in `currentColor` or any single color is ideal — the shape is what ships. - For a real brand mark, the [Simple Icons](https://simpleicons.org) set is a great source — their marks are single-color with transparent backgrounds, exactly the right shape. - No logo? A clean one- or two-letter monogram or a minimal glyph is perfect. ### When your logo needs an `iconMono` If your mark sits on an **opaque background tile** — a colored square with a knocked-out white glyph — its alpha channel is the whole square, so the silhouette would come out as a solid block. Only in that case, add a second file: ```ts export default defineApp({ icon: "./icon.svg", // your mark; its alpha channel is the shape iconMono: "./icon-mono.svg", // transparent, single-color version of the mark }); ``` When `iconMono` is present its alpha is used for the silhouette instead of `icon`'s. Most apps never need it. (A panel's own `ui.panels[].icon` may also use a built-in glyph name — panels are Avi's chrome, not your brand. The app's `icon` is the identity shown on the rail and the panel title bar.) ## Write your tools Edit `app.ts`. Import authoring types such as `AppToolContext` from `@avihq/apps-sdk`, then declare the app's **name**, **title**, **summary**, **icon** (required — see below), and the list of **tools**. The `name` is the app's identity — kebab-case only (it becomes the tool prefix and the app's public subdomain), so it can never contain capital letters. The optional `title` is the human-facing display name with free casing (`"HubSpot"`, `"CRM"`, up to 60 characters) shown wherever the UI names the app; when omitted, the UI shows the `name`. The background `handler`, `data`, `settings`, and React panels live beside tools in the same `defineApp(...)` declaration. The SDK describes the handler contract; the deployed runtime layer provides the actual `context` implementation. Each tool has: - **Name** — what the agent calls it. - **Description** — what it does (the agent reads this to decide whether to use it). Write it for the model: it can be long, technical, and full of parameter guidance. - **Summary** (optional but recommended) — one short plain sentence shown to people in the Apps and Tools views instead of the description. Keep it under ~80 characters; when omitted, the UI shows the description. The app itself takes only a required `summary` — its one-liner on every card and list. There is no app-level `description`: long-form prose about what the app does and how it works belongs in `docs/README.md` (see [Documentation](#documentation)). - **Input schema** — JSON Schema or Zod schema of the arguments. - **Output schema** — JSON Schema (or Zod) of exactly what the handler returns. Agents call tools from code-mode programs, where each tool is a TypeScript function signature; the output schema becomes its return type (`=> Promise<{ deal: { id: string; … } }>`), so a program reads the right keys without a throwaway call. Without one, the result types as `unknown`. Declare it on every tool: `type: "object"` at the top (a union goes inside a property), the real key names, `required` on keys that are always present, `enum` for fixed values, `type: [T, "null"]` for anything that can be null. Describe the shape only; meaning belongs in the description, which shouldn't restate the shape. It is **descriptive** — Avi never validates or rejects an output against it — so change it in the same edit as the handler's return, and check real results in your tests with `outputSchemaMismatches(schema, result)` from `@avihq/apps-sdk/testing`. `avi build` warns about tools without one and refuses a schema that isn't a single object type or is larger than 16 KB. - **Callable from** (optional) — `agent` (chat assistant), `ui` (React panels), and/or `handler` (the app's own background handler), as a single value or an array. **Defaults to all three.** This controls who may call the tool. The handler's `context.apps.invoke` reaches any of the app's tools callable from `agent` or `handler`, so mark an internal helper `callableFrom: "handler"` to keep it out of the agent's tool list and the panels. - **Handler** — the function that runs. - **Secret inputs** (optional) — per-project secret references the backend resolves before your handler runs. Each field is required by default; declare `optional: true` on a field to let callers omit it (your handler then sees `undefined`) — useful when only some of a tool's actions need the credential. Declare `list: true` to accept an **array** of secret keys (your handler receives the array of resolved values in the same order, up to 20 per call) — useful when one call needs several credentials at once. A list field can also declare `allowedFromSetting: ""`, naming one of your app's `secret`-type settings: the backend then rejects any key a project admin hasn't selected in that setting, **fail-closed** — with nothing selected, no key resolves. Pair it with `resolve: false` on the setting (see below) when the setting is purely an allowlist. ```ts tools: { "get-deal": { description: "Get one deal by id.", inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"], additionalProperties: false }, outputSchema: { type: "object", properties: { deal: { type: "object", properties: { id: { type: "string" }, title: { type: "string" }, stage: { type: "string" }, closed_at: { type: ["string", "null"] } }, required: ["id", "title", "stage", "closed_at"], }, }, required: ["deal"], }, async handler({ id }, context) { return { deal: await loadDeal(context, id) }; }, }, } ``` A `search` tool uses the shared envelope: `outputSchema: searchOutputSchema({ kinds: ["deal"], hitProperties: { stage: { type: "string" } } })`. Use `callableFrom` to narrow normal project-level callers, such as a panel-only helper: ```ts tools: { "refresh-cache": { description: "Refresh cached customer data from the panel.", inputSchema: { type: "object", additionalProperties: false }, outputSchema: { type: "object", properties: { ok: { type: "boolean" } }, required: ["ok"] }, callableFrom: "ui", async handler() { return { ok: true }; }, }, } ``` ## The background handler Beyond on-demand tools, an app can run autonomously. Declare what wakes it under `triggers`, then write **one** `handler(event, context)` — Avi calls that single function for every wake-up. An app declares no agents of its own (a manifest with an `agents` field is refused at deploy) and has nothing extra to approve; the handler runs under the app's one declared capability set, the same `data`, and the same `settings` as its tools. ```ts import { defineApp, type AppEvent } from "@avihq/apps-sdk"; export default defineApp({ name: "customer-success", summary: "Flags customer accounts at renewal risk.", icon: "./icon.svg", capabilities: ["data:read", "data:write", "updates:write", "logs:write"] as const, data: { state: { type: "kv", scope: "project" }, }, settings: { lookbackDays: { type: "number", label: "Look-back window (days)", default: 14 }, }, // What wakes the handler. All three are independent and optional. triggers: { schedule: "0 * * * *", // a 5-field cron in UTC, or an array of them events: ["billing.invoice.*"], // event types from the project event log webhook: false, // true to expose a public inbound URL }, async handler(event: AppEvent, context) { if (event.type === "schedule.ticked") { const since = Date.now() - context.settings.lookbackDays * 86_400_000; const last = (await context.data.state.get("last-sweep")) ?? null; // ...do the work: read data, call tools, publish updates and events... await context.updates.publish({ subject: "Renewal risk: Acme", body: "Usage down 40% since the last invoice", }); // Durable history (schedule/webhook wake-ups are NOT auto-logged): await context.events.publish({ type: "customer-success.sweep.completed", data: { since, previous: last }, }); await context.data.state.set("last-sweep", new Date().toISOString()); } }, tools: { // ...on-demand tools the chat agent and panels call... }, }); ``` ### Triggers `triggers` declares what wakes the handler. All three fields are independent and optional — set any combination: | Trigger | Shape | The handler is called with | |---|---|---| | `schedule` | a standard 5-field cron string, read in UTC, or an array of them (e.g. `"*/10 * * * *"`, `["0 9 * * 1-5"]`) | a `schedule.ticked` event on each tick | | `events` | an array of dotted event-type filters, `*` wildcard allowed (e.g. `["gmail.message.*"]`) | the matching `AppEvent` from the project event log | | `webhook` | derived automatically when you declare top-level `webhooks` (see [Webhooks](#webhooks)) | a `.webhook.` event per inbound request | Schedule wake-ups are **ephemeral handler inputs** — not written to the event log; call `context.events.publish(...)` to record durable history. A webhook wake-up writes a lean audit event automatically. An `events`-triggered handler reacts to events that already live in the log. ### The `event` argument Every wake-up passes an `AppEvent`: ```ts { id, orgId, projectId, appId, // the app that published it, or null for system sources type, // dotted, e.g. "schedule.ticked", "gmail.message.received" tags, // free-form labels for filtering contactIds, taskIds, noteIds, // first-class entity associations this event is about occurredAt, // when the underlying thing actually happened data, // arbitrary structured payload createdAt, } ``` Branch on `event.type` to handle each trigger. For a scheduled app, that's just `schedule.ticked`; for an event-driven one, it's whatever types you subscribed to. ### Runtime behavior The handler runs as a **system actor**: `context.user`, `context.userId`, and `context.timezone` are `null` (nobody is reading a handler run as it happens — in tool calls, `context.timezone` is the IANA zone of the person the call is for, so tools can show times on their clock). The handler ships in your app's own bundle, beside its tools. - **Schedule** — every project that enabled the app gets its own ticks for each declared cron, so a slow project never holds up another's. Change the crons and redeploy, and every project picks up the new schedule. A schedule that isn't a 5-field cron runs every five minutes instead. - **Events** — when a matching event is appended to the project event log, Avi dispatches it to the handler. - **Webhook** — an inbound request to the app's per-install public URL wakes the handler with a `.webhook.` event (see [Webhooks](#webhooks)). A handler invocation may run for up to 15 minutes. Keep per-tick work bounded and resume across ticks using a `"kv"` data store (persist a cursor / last-run marker, as the example does with `last-sweep`). ### Publishing events A handler (or a tool) with `events:write` can append to the project event log: ```ts await context.events.publish({ type: "customer-success.sweep.completed", occurredAt: new Date(), // when it actually happened; omit for the server clock tags: ["renewal"], data: { riskScore: 0.82 }, dedupeKey: "sweep:2026-06-16", // optional — collapses duplicate publishes of the same source item }); ``` Other apps can subscribe to these types via their own `triggers.events`, and Avi's curation engine reasons over the log to surface project updates. Read the log with `events:read` (`context.events.list(...)` / `context.events.get(id)`). Two optional envelope fields tune how the curation engine treats an event: - `embedText` — a short, pre-trimmed projection (headline + leading content) that Avi embeds and matches on *instead of* the whole `data` payload, so long bodies and id/link metadata never dilute placement. - `curatable: false` — keeps the event off the curation engine entirely (right for high-churn activity your other events already summarize). This only narrows: `true` is ignored — an app can't force itself into the feed. For events you *want* the engine to be great at, shape `data` with the `curatableEventFields` helper from the SDK. It assembles the standard field names the engine understands — `subject`, a full `body` with honest truncation flags, `thread_id` / `record_id` (stable identities that group later events about the same thread or record onto the same update), `conversation_id`, `participants`, `mentions_user` / `from_user`, `provider` / `direction`, `connection`, and a deep link — and returns `{ data, embedText }` ready to publish: ```ts import { curatableEventFields } from "@avihq/apps-sdk"; const { data, embedText } = curatableEventFields({ subject: ticket.title, body: ticket.description, // full text — capped + flagged for you recordId: ticket.id, // later events about this ticket group onto its update provider: "acme-desk", direction: "inbound", aviLink: panelUrl, extra: { ticket_id: ticket.id, severity: ticket.severity }, }); await context.events.publish({ type: "support.ticket.opened", data, embedText }); ``` Every field is optional — a plain `data` payload still flows through the engine unchanged. #### Telling the feed what your events mean Avi's feed follows each real piece of work — a deal, a ticket, an incident — as one topic, and labels it with tags: `engineering`, `product`, `sales`, `finance`, `support`, `schedule`. You never write the feed. Add a `curation` section to `defineApp` to say what your events mean, and Avi places them. ```ts curation: { // big = a real change of state (won, shipped), never a volume; routine is // the default; bookkeeping = joins its topic silently; ignore = never shown. events: { "support.ticket.escalated": "big", "support.ticket.viewed": "ignore" }, // The tags a type carries (the field keeps its old name, `topics`). topics: { "support.ticket.*": ["support"] }, // Messages people wrote. Everything else is activity on a record. conversation: ["support.message.*"], // data keys that tie later events to the same topic, beside record_id and thread_id. matters: { attachBy: ["ticket_id"] }, }, ``` - Keys are an exact type or a `family.*`; the most specific entry wins. Name only types you publish. - Without a `curation` section, `*.message.*` types are read as messages. Once you declare one, `conversation` decides. - Avi tags messages itself, and any record type you don't map. A type you don't grade is routine, except plumbing like `*.sync.*` and `*.webhook.*`, which defaults to `ignore`. - If your app keeps someone's to-do list, declare `matters.todos`. `list` names one of your tools that lists the open tasks (`{ tool, input? }`; each item needs an `id` and a `name` or `title`, and may carry `notes_preview` and `url`). `events` names the types that carry a task's current state (`record_id` and `name` in `data`): publish one when a task is renamed, completed, cancelled, deleted, or reopened. Work that belongs to a task then lands on it. - `guidance` and `upcoming` (and `matters.seed`, `matters.guidance`) were for topic summaries Avi no longer writes. Deploys still accept them, but nothing reads them, so remove them. - Publish an Update yourself (`updates:write`) only for something no single event says, like a digest. ### Calling your own tools from the handler A handler can call **its own app's** tools (any callable from `agent` or `handler`) through `context.apps.invoke` — no capability needed: ```ts const result = await context.apps.invoke("support_tickets-poll", { since: cursor }); ``` Rules: - The tool must belong to the same app (runtime name `_`). Apps cannot invoke other apps' tools — that was removed. If your app needs data another app owns, publish and subscribe to events; sending email or messages as the project is a first-party feature, so a third-party app that needs to notify someone publishes an update/event for the project's own surfaces to act on, or sends through its own provider with its own credentials. - For tools with `secretInputs`, pass the secret key exactly as a normal tool caller would — the backend resolves the real secret value before invoking the tool. ## Webhooks A webhook lets an external service push events to your app in real time, instead of you polling for them. Declare them with the top-level `webhooks` array. Avi mints one **public URL per install** (per project that enables your app) on your app's own subdomain of the public user-content domain — `https://.avi.tools/api/v1/webhooks/apps/` (the same `avi.tools` subdomain that serves the app's pages, never the product/API domain); the project admin pastes it into the vendor's webhook settings. ```ts export default defineApp({ name: "my-app", capabilities: ["events:write"], webhooks: [ { name: "events", // kebab-case; the URL segment + event suffix description: "Vendor event deliveries.", respond: "ack", // "ack" (default) or "sync" — see below secrets: [ { name: "signing_secret", description: "Vendor signing secret, for verifying each request." }, ], }, ], handler, }); ``` An inbound request wakes your handler with a `.webhook.` event — route on `event.data.hook`: ```ts import { readWebhookRequest, webhookBodyText } from "@avihq/apps-sdk"; import crypto from "node:crypto"; export async function handler(event, context) { if (event.data?.hook !== "events") return; const request = readWebhookRequest(event); if (!request) return; // Verify the request is really from the vendor — you have the verbatim bytes. const body = webhookBodyText(request); const ok = verifyHmac(request.secrets.signing_secret, request.headers, body); if (!ok) return { status: "skipped" }; const payload = JSON.parse(body); await context.events.publish({ type: "vendor.thing.happened", data: payload }); } ``` How it works: - **The URL is the credential.** It carries a secret token; treat it like a password. Rotating it (in the app's settings) revokes the old URL immediately; disabling it is a kill switch. - **You verify authenticity.** Avi passes the **verbatim request bytes + headers** through untouched. Declare the vendor's signing secret under `secrets`; the project admin binds it to a project secret key in settings, and it arrives on `request.secrets.` (never written to the event log). Use it to check the vendor's signature (HMAC) yourself. - **Verification handshakes are automatic.** Avi answers generic subscription challenges (Slack `url_verification`, Meta `hub.challenge`) for you without waking your handler — so most webhooks stay `respond: "ack"`. - **`ack` vs `sync`.** `ack` (default) returns `202` immediately and runs your handler in the background — right for normal event delivery. `sync` runs your handler inline (bounded by `timeoutSeconds`) and relays its returned `{ status?, headers?, body? }` to the sender — use it only when the vendor needs a specific response body. - **Read the body** with `readWebhookRequest(event)` then `webhookBodyBytes` / `webhookBodyText` / `webhookBodyJson`. Configuring the URL and binding secrets is done per project in the app's settings — see [Apps → Webhooks](/docs/using-apps#webhooks). **Reading your own webhook URL from code.** Sometimes the app itself needs its ingress URL — for example to embed it as a contact form's `action` in a site it publishes. Declare the `webhooks:read` capability and call `context.webhooks.url(name)` with a declared webhook name: it returns this install's public URL, creating the endpoint on first use (the same URL the project admin sees in settings). An undeclared name rejects. ## React panels Apps can also expose React panels, which open from the rail (the dock on a phone) in every project that enables the app. Panels run in a sandboxed iframe, so your React code never executes inside Avi's main app tree and cannot access Avi auth tokens, local storage, cookies, or the parent DOM. ```ts export default defineApp({ name: "customers", summary: "Customer dashboard.", icon: "./icon.svg", capabilities: ["data:read", "data:write"] as const, data: { // A KV store for the app's own state. state: { type: "kv" }, // A queryable record collection. customers: { type: "collection", fields: { name: { type: "string", required: true }, status: { type: "enum", enum: ["lead", "active", "at-risk", "churned"] }, notes: { type: "string" }, }, indexes: [{ fields: ["status"] }], fullText: ["name", "status", "notes"], vector: ["name", "notes"], globalSearch: { kind: "customer", titleField: "name", snippetField: "notes" }, }, }, ui: { panels: { dashboard: { title: "Customers", icon: "users", entry: "./ui/Dashboard.tsx", }, }, }, tools: { // ... }, }); ``` A collection's `globalSearch` opts its records into Avi's **global search** — the chat agent's one search tool and the chat composer's `+`-mention picker — so your records show up next to native Tasks and can be referenced directly in a message (the composer inlines the record for the agent, along with a pointer to your app's `read` tool when you expose one). Set `titleField` (which field is the result title) and, optionally, `snippetField` (the subtitle), `kind` (a human label like `"customer"`), and `searchFields` (which fields to text-match; defaults to `fullText`, else the title field). Every field you name must exist on the collection, or the deploy is rejected. Omit `globalSearch` entirely and the collection stays private to your app. Panel code is normal React. Import components from Avi's component library, `@avihq/ui/panel`, and bridge hooks such as `useAvi` from `@avihq/apps-sdk/react`: Panel icons can use Avi's built-in names, relative SVG/PNG/JPEG/GIF/WebP paths that the CLI bundles at deploy time, compact `data:image/...` URIs, or HTTPS image URLs. ```tsx import { AppShell, Button } from "@avihq/ui/panel"; import { useAvi } from "@avihq/apps-sdk/react"; export default function Dashboard() { const avi = useAvi(); return ( avi.data.customers.create({ name: "New customer", status: "lead" })}> Add ); } ``` Limits: - An app can define up to five panels. Prefer one, with extra surfaces as tabs inside it. - Each panel bundle must be 4 MB or smaller. - Panel entries must be relative `.tsx`, `.ts`, `.jsx`, or `.js` files. - Browser panel bundles cannot import Node built-ins such as `fs`, `path`, or `node:*`. - Panel data access goes through the Avi bridge and is checked against the same approved app capabilities as tools. `@avihq/ui/panel` carries the layout, form, dialog, and record components (`AppShell`, `Select`, `ConfirmDialog`, `RecordPage`, and more), all themed and voice-operable; lists come from `@avihq/ui/data-table` (`RecordBrowser`, `DataTable`). `@avihq/apps-sdk/react` carries the bridge hooks: `useAvi`, `useTheme`, `useAviView`, `useLiveData`, `useAppData`, `useAppTool`, and more. (The SDK's older `Button`/`Input`/`PanelHeader` primitives still render in already-deployed panels, but new panels should use `@avihq/ui/panel`. `useAppRecords` is a deprecated alias of `useAppData` — record collections are now declared data stores reached through `avi.data.`.) For the full authoring guide, including the manifest contract, bridge APIs, theming, limits, security model, and troubleshooting, see [App React UI](/docs/app-react-ui). ## Public pages and sites Apps can publish two kinds of public surfaces, and they solve different problems: **Pages** (`ui.pages`) are React bundles served inside Avi's hardened shell on your app's own subdomain (`.avi.tools/`), rendering data from your app — booking pages, shared views, per-thing links. Pages are unlisted by default; set `indexable: true` on a page's manifest entry when it's public content that should appear in search engines. **Sites** (`context.sites`) are real static websites on a dedicated sites domain, each on its **own subdomain** — full HTML documents and assets you author, served verbatim and fully SEO-capable (your own `