@agent-native/core 0.122.3 → 0.123.0

package/corpus/core/docs/content/template-chat-first-edits.mdx

@@ -0,0 +1,145 @@
+---
+title: "Your first feature in Chat"
+description: "The one file that renders Chat's starter screen, what its real props do, and a full walkthrough of adding a feature end to end."
+---
+
+# Your first feature in Chat
+
+This page is for developers extending the [Chat template](/docs/template-chat). It covers the single file that renders the starter chat screen, then walks through everything the agent typically touches when you ask for a real feature.
+
+## First code to inspect {#first-code}
+
+- `actions/hello.ts` is the starter behavior the agent can call. Replace it or
+  add actions beside it.
+- `app/routes/_index.tsx` renders the full-page chat surface. Adjust the
+  suggestions, empty state, composer, or surrounding layout here.
+- `AGENTS.md` tells the built-in agent how to work inside this app.
+
+<FileTree
+  id="doc-block-chat3"
+  title="Chat template layout"
+  entries={[
+    {
+      path: "actions/hello.ts",
+      note: "the one example action; replace or add actions beside it",
+    },
+    {
+      path: "actions/view-screen.ts",
+      note: "standard context action the agent calls first",
+    },
+    {
+      path: "actions/navigate.ts",
+      note: "standard navigation action",
+    },
+    {
+      path: "app/routes/_index.tsx",
+      note: "renders the full-page chat surface; edit suggestions, empty state, composer",
+    },
+    {
+      path: "app/routes/chat.$threadId.tsx",
+      note: "re-exports _index.tsx so /chat/:threadId renders the same surface with a thread id in the URL",
+    },
+    {
+      path: "AGENTS.md",
+      note: "chat-first guidance the built-in agent reads",
+    },
+  ]}
+/>
+
+The real starter file is more than a bare `<AgentChatSurface />` — it wires thread-URL sync, a tab identity for multi-tab runs, and a hero composer layout, and its copy comes from i18n keys rather than literal strings:
+
+<AnnotatedCode
+  id="doc-block-chat4"
+  title="app/routes/_index.tsx (trimmed)"
+  filename="app/routes/_index.tsx"
+  language="tsx"
+  code={
+    'import {\n  AgentChatSurface,\n  markAgentChatHomeHandoff,\n} from "@agent-native/core/client/agent-chat";\nimport { useT } from "@agent-native/core/client/i18n";\nimport { useEffect } from "react";\nimport { useNavigate, useParams } from "react-router";\n\nimport { TAB_ID } from "@/lib/tab-id";\n\nfunction chatThreadPath(threadId: string | null) {\n  return threadId ? `/chat/${encodeURIComponent(threadId)}` : "/";\n}\n\nexport default function ChatRoute() {\n  const { threadId } = useParams();\n  const navigate = useNavigate();\n  const t = useT();\n  const threadUrlSync = threadId\n    ? { routeThreadId: threadId, getPath: chatThreadPath, navigate }\n    : undefined;\n\n  useEffect(() => {\n    function handleChatRunning(event: Event) {\n      const detail = (event as CustomEvent).detail;\n      if (detail?.isRunning === true) markAgentChatHomeHandoff("chat");\n    }\n    window.addEventListener("agentNative.chatRunning", handleChatRunning);\n    return () =>\n      window.removeEventListener("agentNative.chatRunning", handleChatRunning);\n  }, []);\n\n  return (\n    <AgentChatSurface\n      mode="page"\n      chatViewTransition\n      threadUrlSync={threadUrlSync}\n      browserTabId={TAB_ID}\n      dynamicSuggestions={false}\n      suggestions={[\n        t("chat.suggestionCapabilities"),\n        t("chat.suggestionCustomize"),\n        t("chat.suggestionActions"),\n      ]}\n      emptyStateText={t("chat.emptyState")}\n      centerComposerWhenEmpty\n      composerLayoutVariant="hero"\n      composerPlaceholder={t("chat.composerPlaceholder")}\n      composerSlot={\n        <div className="mx-auto mb-5 max-w-xl px-4 text-center">\n          <h1>{t("chat.heroTitle")}</h1>\n          <p>{t("chat.heroDescription")}</p>\n        </div>\n      }\n    />\n  );\n}'
+  }
+  annotations={[
+    {
+      lines: "19-21",
+      label: "Thread URL sync",
+      note: "`/chat/:threadId` (`chat.$threadId.tsx`) re-exports this same component. When the route has a thread id, `threadUrlSync` keeps the URL and the active thread in lock-step: switching threads pushes `/chat/<id>`, and opening that URL restores the thread.",
+    },
+    {
+      lines: "38",
+      label: "Tab identity",
+      note: "`TAB_ID` (`app/lib/tab-id.ts`, a random id generated once per browser tab) lets the shared chat runtime tell multiple open tabs of the same app apart, so a run started in one tab isn't mistaken for one in another.",
+    },
+    {
+      lines: "39-44",
+      label: "Suggestions are i18n keys",
+      note: 'Suggestion copy comes from `t("chat.suggestionCapabilities")` etc. (see `app/i18n/en-US.ts`), not literal English strings, and `dynamicSuggestions={false}` turns off the runtime\'s own suggestion generation in favor of these three.',
+    },
+    {
+      lines: "46-47",
+      label: "Hero composer layout",
+      note: '`composerLayoutVariant="hero"` plus `centerComposerWhenEmpty` centers the composer with a title/description above it, instead of the plain bottom-docked composer other `mode="page"` chat routes use.',
+    },
+    {
+      lines: "49-54",
+      label: "composerSlot",
+      note: 'Arbitrary JSX rendered above the composer only while it\'s centered — this is where the "How can I help?" heading lives. Edit this to change the empty-state pitch without touching the runtime.',
+    },
+    {
+      lines: "23-31",
+      label: "Home handoff",
+      note: 'When a run starts on this page, `markAgentChatHomeHandoff("chat")` records that the home surface owns the active run, so navigating away and back reattaches to it instead of losing it.',
+    },
+  ]}
+/>
+
+## First edits {#first-edits}
+
+Most first features follow the same shape: a table, one or two actions, a route, a nav entry, and an `AGENTS.md` update. Ask the agent:
+
+> Add a data model for `notes`. A note has an id, title, body, and owner. Render a notes page at `/notes`, add create/list actions, and keep chat able to create notes.
+
+Chat ships with no `server/db/schema.ts` at all (see [What's not in it](/docs/template-chat#not-in-it)), so the first change is a new file, following the same `table`/`text`/`ownableColumns` shape every other template uses:
+
+<Diff
+  id="doc-block-chat5"
+  title="A new notes table"
+  filename="server/db/schema.ts"
+  language="ts"
+  before={""}
+  after={
+    'import {\n  table,\n  text,\n  ownableColumns,\n} from "@agent-native/core/db/schema";\n\nexport const notes = table("notes", {\n  id: text("id").primaryKey(),\n  title: text("title").notNull(),\n  body: text("body").notNull(),\n  createdAt: text("created_at").notNull(),\n  updatedAt: text("updated_at").notNull(),\n  ...ownableColumns(),\n});'
+  }
+  annotations={[
+    {
+      lines: "1-5",
+      label: "Shared schema helpers",
+      note: "`table`/`text`/`ownableColumns` come from `@agent-native/core/db/schema` — the same dialect-agnostic helpers every template uses, so this file stays portable across SQLite/Postgres.",
+    },
+    {
+      lines: "13",
+      label: "ownableColumns",
+      note: "`...ownableColumns()` adds the owner/org columns the framework's `accessFilter`/`resolveAccess` helpers expect, so notes slot into the standard per-user/per-org sharing model with no extra plumbing.",
+    },
+  ]}
+/>
+
+The rest of the feature follows from there:
+
+- `actions/create-note.ts` — a `defineAction` with a Zod schema (`title`, `body`), shaped like `actions/hello.ts`.
+- `actions/list-notes.ts` — a read-only action (`readOnly: true`, like `actions/view-screen.ts`) that queries the new table through `accessFilter`.
+- `app/routes/notes.tsx` — a new route; the app uses file-system routing (`flatRoutes()` in `app/routes.ts`), so adding the file is enough to mount `/notes`.
+- A new entry in the `navItems` array in `app/components/layout/Sidebar.tsx` pointing at `/notes`.
+- An `AGENTS.md` addition telling the agent notes exist and which actions manage them.
+
+A new action is callable by chat as soon as it exists — every `defineAction` is a tool by default unless it sets `agentTool: false`. It won't necessarily be in the model's very first request, though: `server/plugins/agent-chat.ts` sets `INITIAL_TOOL_NAMES = ["view-screen", "navigate", "hello"]`, which controls only which tool schemas are sent on the first turn. Everything else, including a brand-new `create-note`, stays reachable through `tool-search` and loads on demand — add a name to that list only if you want it in the model's default toolset from message one.
+
+## Use your own agent backend {#own-agent-backend}
+
+The template uses the built-in app-agent loop by default. To connect a custom backend, swap the chat runtime behind the agent chat plugin instead of rewriting the UI. The Chat route should stay a thin renderer around the shared chat surface; the backend choice belongs in the server plugin/runtime adapter.
+
+Use this when your model orchestration already lives elsewhere, but you still want an app with auth, threads, actions, UI state, and deployable pages.
+
+## What's next
+
+- [**Chat Template**](/docs/template-chat) — what ships by default and when to pick it
+- [**Chat — runtime and admin surfaces**](/docs/template-chat-developers) — core tables, auth, and the admin pages
+- [**Actions**](/docs/actions) — the action system chat and UI both call
+- [**Native Chat UI**](/docs/native-chat-ui) — chat surface primitives and runtime options

package/corpus/core/docs/content/template-chat.mdx

@@ -5,11 +5,11 @@ description: "A minimal chat-first agent-native app: durable chat threads, actio
 
 # Chat Template
 
-Chat is the basic agentic app starting point. It gives you a clean ChatGPT-style shell with chat at the center, a threads list on the left, standard app navigation, auth, live sync, actions, and one example action. Start here when you want a real browser app you can build on before committing to a domain template.
+Chat is the plainest agent-native starting point: a ChatGPT-style shell with chat at the center, a thread list, auth, and one example action — nothing domain-specific. It's for developers who want a real, deployable app to build their own agent and screens on top of, not a finished product for a specific job.
 
 If you want a finished domain product shape, start from [Calendar](/docs/template-calendar), [Mail](/docs/template-mail), [Content](/docs/template-content), [Forms](/docs/template-forms), [Analytics](/docs/template-analytics), or another domain template. If you truly do not need a browser UI yet, see [Automation-First Apps](/docs/pure-agent-apps).
 
-<WireframeBlock id="doc-block-1qu69ww">
+<WireframeBlock id="doc-block-chat1">
   <Screen
     surface="desktop"
     html={
@@ -23,10 +23,11 @@ If you want a finished domain product shape, start from [Calendar](/docs/templat
 - **Full-page chat** on `/` using the framework chat surface and durable chat threads.
 - **Thread list in the app sidebar** so users can create, reopen, rename, pin, and archive chats.
 - **Agent chat plugin** pre-configured so the chat talks to the built-in app-agent loop once your agent credentials are set.
-- **Auth** via Better Auth — login, signup, sessions, organizations. The same flow runs locally and in production; in development email verification is skipped.
+- **Auth** via Better Auth — login, signup, sessions, organizations. See [Chat — runtime and admin surfaces](/docs/template-chat-developers#auth) for how sessions, orgs, and dev-mode email verification are configured.
 - **Actions directory** with one example (`actions/hello.ts`) plus the standard `view-screen` and `navigate` actions.
-- **The framework's core tables** for application state, settings, sessions, resources, chat threads, run history, and other runtime state.
+- **The framework's core tables** for chat threads, application state, settings, sessions, resources, and run history — plus a Database admin page and an Observability dashboard mounted by default, whether or not you ever open them. See [Chat — runtime and admin surfaces](/docs/template-chat-developers).
 - **Live sync** (`useDbSync`) already wired so UI auto-refreshes when the agent writes to SQL.
+- **Extensions** routes mounted by default too, for sandboxed mini-apps your users build inside the chat later. See [Extensions](/docs/extensions).
 - **AGENTS.md** with chat-first guidance for adding actions, routes, skills, and application state.
 
 ## What's _not_ in it {#not-in-it}
@@ -37,7 +38,7 @@ If you want a finished domain product shape, start from [Calendar](/docs/templat
 
 That's the point. Chat is a thin, useful default shell for your own agent, not a domain product pretending to be generic.
 
-<Diagram id="doc-block-1sm2lyf" title="What ships in the Chat shell" summary={"A thin chat surface over the framework's standard runtime — actions, durable threads, live sync, and auth — with room to add your own UI."}>
+<Diagram id="doc-block-chat2" title="What ships in the Chat shell" summary={"A thin chat surface over the framework's standard runtime — actions, durable threads, live sync, and auth — with room to add your own UI."}>
 
 ```html
 <div class="diagram-chat">
@@ -112,88 +113,22 @@ That's the point. Chat is a thin, useful default shell for your own agent, not a
 
 ```bash
 npx @agent-native/core@latest create my-chat-app --standalone --template chat
-cd my-chat-app
-pnpm install
-pnpm dev
 ```
 
-The no-browser scaffold is still available for automation-first work, but it is not the main Chat template path:
+See [Getting started](/docs/getting-started) for `cd`, install, first run, and what the generated app looks like.
+
+For automation-first work with no browser UI at all:
 
 ```bash
 npx @agent-native/core@latest create my-agent --headless
 ```
 
-Use it for scheduled jobs, queues, CLI loops, or external-agent workflows where chat and app pages are not useful yet. The key invariant stays the same: actions are the shared surface for chat, UI, HTTP, MCP, A2A, and CLI.
-
-## First code to inspect {#first-code}
-
-- `actions/hello.ts` is the starter behavior the agent can call. Replace it or
-  add actions beside it.
-- `app/routes/_index.tsx` renders the full-page chat surface. Adjust the
-  suggestions, empty state, composer, or surrounding layout here.
-- `AGENTS.md` tells the built-in agent how to work inside this app.
-
-<FileTree
-  id="doc-block-1w9aksk"
-  title="Chat template layout"
-  entries={[
-    {
-      path: "actions/hello.ts",
-      note: "the one example action; replace or add actions beside it",
-    },
-    {
-      path: "actions/view-screen.ts",
-      note: "standard context action the agent reads",
-    },
-    {
-      path: "actions/navigate.ts",
-      note: "standard navigation action",
-    },
-    {
-      path: "app/routes/_index.tsx",
-      note: "renders the full-page chat surface; edit suggestions, empty state, composer",
-    },
-    {
-      path: "AGENTS.md",
-      note: "chat-first guidance the built-in agent reads",
-    },
-  ]}
-/>
-
-The chat page is intentionally thin:
-
-```tsx filename="app/routes/_index.tsx"
-import { AgentChatSurface } from "@agent-native/core/client/agent-chat";
-export default function ChatRoute() {
-  return (
-    <AgentChatSurface
-      mode="page"
-      suggestions={[
-        "What can you do?",
-        "Help me customize this chat app",
-        "Show me the actions and pages I can add",
-      ]}
-    />
-  );
-}
-```
-
-## Use your own agent backend {#own-agent-backend}
-
-The template uses the built-in app-agent loop by default. To connect a custom backend, swap the chat runtime behind the agent chat plugin instead of rewriting the UI. The Chat route should stay a thin renderer around the shared chat surface; the backend choice belongs in the server plugin/runtime adapter.
-
-Use this when your model orchestration already lives elsewhere, but you still want an app with auth, threads, actions, UI state, and deployable pages.
-
-## First edits {#first-edits}
-
-After scaffolding, ask the agent:
-
-> Add a data model for `notes`. A note has an id, title, body, and owner. Render a notes page at `/notes`, add create/list actions, and keep chat able to create notes.
-
-The agent should add a Drizzle schema, actions, route, navigation, and instructions. Then you can use the notes feature from either the UI or chat.
+Use it for scheduled jobs, queues, CLI loops, or external-agent workflows where chat and app pages are not useful yet. The key invariant stays the same: actions are the shared surface for chat, UI, HTTP, MCP, A2A, and CLI. See [Automation-First Apps](/docs/pure-agent-apps) for that path in depth.
 
 ## What's next
 
+- [**Your first feature in Chat**](/docs/template-chat-first-edits) — the starter chat route, annotated, plus a full walkthrough of adding a real feature
+- [**Chat — runtime and admin surfaces**](/docs/template-chat-developers) — core tables, auth, and the Database/Observability/Extensions pages that ship by default
 - [**Getting Started**](/docs/getting-started) — build the chat-first path from action to inline result to app page
 - [**Templates**](/docs/cloneable-saas) — the clone-and-own model, and every domain template to start from instead
 - [**Agent Surfaces**](/docs/agent-surfaces) — chat, inline UI, app pages, embedded, automation, and external-agent patterns

package/corpus/core/docs/content/template-clips-ai-and-editing.mdx

@@ -0,0 +1,114 @@
+---
+title: "AI Pipeline, Editing, and Insights"
+description: "How Clips transcribes and titles a recording, edits it non-destructively, exports transcripts to Brain, and reports who's actually watching a clip."
+search: "Clips transcription cleanup titles summaries chapters non-destructive editing trim filler words Brain export insights views"
+---
+
+# AI pipeline, editing, and insights
+
+This page covers what happens to a recording after it's captured: transcription and AI metadata, non-destructive editing, exporting transcripts to Brain, and the view/engagement numbers an owner can see.
+
+## Transcription, cleanup, and AI metadata
+
+Transcription tries the fastest, free option first and only falls back to a paid one when it has to:
+
+| Order | Provider                        | Notes                                                                                     |
+| ----- | ------------------------------- | ----------------------------------------------------------------------------------------- |
+| 1     | Native (on-device)              | Browser Web Speech API or desktop local Whisper/macOS speech — instant, no API key        |
+| 2     | Builder.io managed (Gemini)     | Cloud fallback when native text is missing; no extra key needed once Builder is connected |
+| 3     | Groq (`whisper-large-v3-turbo`) | Optional backup if you'd rather bring your own key                                        |
+
+Once a transcript is ready, the agent fills in a title, summary, and chapter markers automatically, and keeps them current as you edit. You can also ask directly:
+
+- "Regenerate the title and summary."
+- "Add chapters — this one's long."
+- "Pull three quotes for a blog post."
+- "Fix the mis-transcribed word at 1:42."
+
+For a silent screen recording where the audio alone would be misleading, turn on **Include full video** in the AI tools menu so the agent watches the recording itself (this requires Gemini) instead of relying on the transcript alone.
+
+## Non-destructive editing
+
+Trim, split, blur, speed changes, filler-word removal, and silence removal are all recorded as instructions layered on top of your original recording — never baked into the video file itself. That means every edit is undoable, and the original media is never touched until you explicitly export.
+
+<Diagram id="doc-block-clips4" title="Non-destructive edits" summary={"Edits accumulate as instructions on top of the original media. Undo removes the most recent one; Export is the only step that renders a new file."}>
+
+```html
+<div class="diagram-flow">
+  <div class="diagram-box" data-rough>
+    Original recording<br /><small class="diagram-muted">never modified</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel center">
+    <span class="diagram-pill accent">Trim · cut · blur · speed</span
+    ><small class="diagram-muted">appended, not overwritten</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-col">
+    <div class="diagram-pill">Player</div>
+    <div class="diagram-pill">Export</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-flow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.diagram-flow .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.diagram-flow .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+}
+.diagram-flow .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+Ask the agent to make the edits for you:
+
+- "Remove the ums and uhs and re-stitch."
+- "Trim the first 10 seconds."
+- "Blur my email address in the top-right corner for the first minute."
+- "Combine these three clips into one, in this order."
+
+## Exporting transcripts to Brain
+
+Once your workspace has connected Brain (Agent Native's institutional-memory app), Clips can send ready transcripts over automatically after each recording finishes, so meeting notes and screen-recording context become searchable company memory alongside everything else Brain ingests.
+
+You can also ask the agent to backfill a bounded window of past recordings — for example, everything from the last 28 days — rather than waiting for new ones to trickle in. A backfill reports how many transcripts were exported, quarantined (flagged sensitive by Brain), skipped, or failed, and returns a cursor so a large backlog can be worked through in pages without re-processing anything already sent.
+
+## Recording and organization insights
+
+Every clip owner can see who's actually watching:
+
+| What                      | Shows you                                                                                                                                                                    |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Recording insights**    | Views (counted separately for humans and for outside agents reading the clip's agent-context APIs), unique viewers, completion rate, a drop-off curve, and CTA click-through |
+| **Organization insights** | Org-wide totals for the period, top clips by views/reactions/comments, top creators, and a day-by-day engagement trend — the Insights Hub                                    |
+| **CSV export**            | Every recording in the organization with its view and engagement counts, as a downloadable CSV                                                                               |
+
+Human views and agent views are tracked in separate counters on purpose, so an agent polling a shared clip's transcript never inflates the "people who watched this" number.
+
+## Builder credit status
+
+Backup transcription, transcript cleanup, and AI titles/summaries run on Builder.io-managed AI credits by default. If one of those stops working, ask the agent — it checks the current credit status and explains whether credits are paused rather than treating it as a bug. The fix is either adding Builder.io credits/upgrading, or connecting a personal Groq key as a fallback for transcription.
+
+## What's next
+
+- [**Clips**](/docs/template-clips) — the overview
+- [**Capturing Everywhere**](/docs/template-clips-capture-everywhere) — how a recording gets into your library in the first place
+- [**Sharing, Teams, and Agent-Readable Clips**](/docs/template-clips-sharing-and-teams) — who can see a clip once it's edited
+- [**Extending Clips**](/docs/template-clips-developers) — the `edits_json` shape, transcript schema, and full action reference

package/corpus/core/docs/content/template-clips-capture-everywhere.mdx

@@ -0,0 +1,120 @@
+---
+title: "Capturing Everywhere: Desktop, Mobile, and Screen Memory"
+description: "Every way to get a recording into Clips — the desktop tray app, the mobile companion, Rewind quick-save, local-only Screen Memory, and the Chrome extension for browser logs."
+search: "Clips desktop app mobile companion Rewind quick save Screen Memory Chrome extension browser logs"
+---
+
+# Capturing everywhere
+
+Clips isn't only a browser recorder. This page covers every place you can start a capture — the desktop tray app, the mobile companion app, pulling in a moment you forgot to record, the local-only Screen Memory buffer, and the Chrome extension for browser logs — and who each one is for.
+
+<Diagram id="doc-block-clips1" title="Capture surfaces" summary={"Desktop, mobile, and the Chrome extension all land in your shared Clips library. Screen Memory is the one exception — it never leaves your machine."}>
+
+```html
+<div class="diagram-flow">
+  <div class="diagram-col">
+    <div class="diagram-node">Desktop app</div>
+    <div class="diagram-node">Mobile app</div>
+    <div class="diagram-node">Chrome extension</div>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box" data-rough>
+    Clips library<br /><small class="diagram-muted"
+      >hosted, SQL — searchable and shareable</small
+    >
+  </div>
+</div>
+<div class="diagram-flow" style="margin-top: 14px">
+  <div class="diagram-node">Screen Memory</div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel center">
+    <span class="diagram-pill">Your machine only</span
+    ><small class="diagram-muted"
+      >local files, off by default, never uploaded</small
+    >
+  </div>
+</div>
+```
+
+```css
+.diagram-flow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.diagram-flow .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.diagram-flow .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+}
+.diagram-flow .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## Desktop recorder and the desktop tray app
+
+Clips ships a desktop companion built for the smoothest everyday capture path: screen and webcam recording with a draggable camera bubble, live transcription while you record, calendar meeting reminders, and Hold-Fn dictation — all without keeping a browser tab open.
+
+The first time you record your screen, your operating system will ask you to grant Screen Recording permission (on a Mac: System Settings → Privacy & Security → Screen Recording). That's an OS-level permission, not a Clips setting, and Clips can't record without it.
+
+While a meeting app like Zoom or Microsoft Teams is in the foreground, the desktop app can also offer a quick "Take notes?" prompt so you don't have to remember to start a recording yourself — see [Recording, importing, and meetings](/docs/template-clips#recording-importing-and-meetings) for what happens once you accept.
+
+## Mobile companion capture
+
+The Agent Native mobile app (iOS/Android) brings capture to your phone: dictate, join or record a meeting, shoot a quick video, or import a clip — from the phone's home screen or an OS quick action.
+
+A few things are different from desktop:
+
+- **Meeting audio is microphone-only.** Phones can't capture another app's call audio the way a desktop can, so mobile meeting recordings don't get the same per-attendee action-item attribution as a desktop capture with both mic and system audio. Mobile is a good fit for in-person rooms or for capturing audio playing from a separate device.
+- **Dictation is tap-to-start/stop**, not press-and-hold like the desktop Fn-hold flow.
+- **Uploads are durable.** The audio or video file saves to your phone before any network request, so a dropped connection never loses the capture — it resumes the upload automatically once you're back online. You don't need to keep the app open or re-record after a failed upload.
+
+## Rewind quick-save
+
+If you use [Rewind](https://www.rewind.ai) (a local screen-recall app) on your Mac and realize, after the fact, that a moment was worth keeping, Clips can pull in the last 30 seconds or 5 minutes of your local Rewind history and prepend it to a private clip.
+
+A few rules keep this predictable:
+
+- Only the clip's owner can request it, and only on a **private** clip with no one else already granted direct access — removing anyone else's access first keeps the pulled-in Rewind footage from being retroactively shared.
+- It replaces the clip's media with the combined recording. The transcript, chapters, comments, and reactions all shift automatically so their timestamps still line up with the new, earlier start time.
+- It's explicit and per-clip — Rewind quick-save never runs automatically in the background.
+
+## Screen Memory
+
+Screen Memory is a different, optional feature: a local-only buffer that quietly notes which app or window was in front of you recently, entirely on your own machine.
+
+<Callout id="doc-block-clips2" tone="info">
+  Screen Memory is off by default. Nothing is captured until you turn it on, and
+  nothing ever leaves your machine automatically — you export or clear it
+  yourself from the desktop tray's settings.
+</Callout>
+
+When it's enabled, you can ask the agent things like "what was I looking at 20 minutes ago?" and it checks the local buffer before answering. It is never a hosted or shareable Clips recording, and it never exposes raw screen images to the agent — only bounded text snippets of app and window context.
+
+## Browser logs with the Chrome extension
+
+Install the Clips Chrome extension when you want a recording plus the browser logs and network activity from the tab you're debugging — useful for reporting product bugs and browser-only repros.
+
+- It only watches the tab you're actively recording, and only while the recording is running.
+- It saves console messages and basic per-request info (method, a redacted URL, status, duration, and whether a request failed) — never request or response bodies, headers, or cookies.
+- Use the desktop app for the smoothest everyday recording; reach for the Chrome extension specifically when you need those browser logs attached.
+
+See [Extending Clips](/docs/template-clips-developers) for the extension's install link and how to configure it on a self-hosted deployment.
+
+## What's next
+
+- [**Clips**](/docs/template-clips) — the overview, and what happens to a recording once it's captured
+- [**Sharing, Teams, and Agent-Readable Clips**](/docs/template-clips-sharing-and-teams) — who can see a clip once it's recorded
+- [**AI Pipeline, Editing, and Insights**](/docs/template-clips-ai-and-editing) — transcription and editing once a clip lands in your library
+- [**Extending Clips**](/docs/template-clips-developers) — the recording data model and the Chrome extension's developer setup