@agent-native/core 0.26.9 → 0.27.0

package/docs/content/template-brain.md

@@ -26,13 +26,40 @@ this product decision?", "how does this in-development feature work?", or "what
 changed in this process?" with links back to the source conversation, meeting,
 or issue.
 
-Brain's shipped shape is company chat plus cited, reviewed memory over approved
-sources. The current template also includes Brain-wide search across knowledge,
-captures, and source records, plus reusable workspace connections for source
-credentials. Broader federated workspace search and expertise ranking are
-platform direction, not something you need to set up on day one.
+## What you can do with it
+
+- **Ask cited questions.** Ask is the main product surface: a clean chat over
+  reviewed company memory, with source health, review count, and suggested
+  questions kept secondary. Every answer links back to the Slack thread,
+  meeting, issue, or capture that supports it.
+- **Connect approved sources.** Configure manual, generic webhook, Clips, Slack,
+  Granola, and GitHub sources. Sources are org-shared by default so company
+  memory is useful to the whole workspace.
+- **Review before publishing.** Proposed memories get a first-class Review route
+  where reviewers edit wording, inspect evidence/source links, and approve or
+  reject. High-confidence, non-sensitive entries can publish immediately;
+  company-tier or sensitive entries queue as proposals.
+- **Inspect cited knowledge.** The Knowledge route shows distilled, atomic
+  entries with kind, topic, entities, confidence, exact evidence quotes, and
+  supersede links.
+- **Reuse workspace integrations.** Brain sources can reuse shared workspace
+  connection grants instead of re-entering provider tokens. The Sources page
+  shows Brain source records beside reusable connection grants and provider
+  readiness.
+- **Mirror approved memory as ambient context.** Canonical approved entries can
+  mirror into workspace resources under `context/company-brain/...` so other
+  apps can use them as context. Both flows preview the exact Markdown before the
+  resource is written or removed.
+
+## Useful prompts
 
-## Start Here
+- "What did we decide about annual pricing, and where was that discussed?"
+- "Find the most recent onboarding-process change and cite the source."
+- "Summarize what this GitHub discussion means for the launch plan."
+- "Review the pending memory proposals and flag anything too vague to publish."
+- "Which sources are stale or failing sync?"
+
+## Getting started
 
 1. **Try the demo.** Open Ask and choose **Start demo**. Brain seeds a small
    product-decision corpus, runs the trust checks, and asks a cited question so
@@ -46,89 +73,55 @@ platform direction, not something you need to set up on day one.
 4. **Ask from the source.** Use Ask for questions that should be grounded in
    approved knowledge, not raw chat logs.
 
-## Useful Prompts
+For a public demo, the seeded corpus demonstrates product-decision recall,
+citation links, supersede behavior, review gating, redaction, personal-content
+exclusion, and honest not-found behavior without connecting a real workspace.
 
-- "What did we decide about annual pricing, and where was that discussed?"
-- "Find the most recent onboarding-process change and cite the source."
-- "Summarize what this GitHub discussion means for the launch plan."
-- "Review the pending memory proposals and flag anything too vague to publish."
-- "Which sources are stale or failing sync?"
+### Scaffolding
 
-## What It Includes
-
-- **Full-page company chat.** The Ask route is the main product surface: a
-  clean chat over cited company memory with source health, review count, and
-  suggested questions kept secondary. It uses `AgentChatSurface`, so the Brain
-  composer stays on the same shared chat input stack as the agent sidebar and
-  Agent-Native Code.
-- **Repeatable demo flow.** Load a product-decision corpus, run the demo eval,
-  ask a cited question immediately, then continue into Review or Knowledge so a
-  new workspace can see the trust loop before connecting real sources.
-- **Approved sources.** Configure manual, generic webhook, Clips, Slack,
-  Granola, and GitHub source records. Sources are org-shared by default so the
-  company memory is useful to the whole workspace. Slack is channel-oriented by
-  design; DMs and MPIMs are not scan targets.
-- **Raw captures.** Store transcripts, channel exports, notes, and webhook imports in portable SQL with dedupe keys and source metadata.
-- **Distilled knowledge.** Write atomic entries with kind, topic, entities, confidence, exact evidence quotes, and supersede links.
-- **Review queue.** Proposed company memories have a first-class Review route
-  where reviewers edit wording, inspect evidence/source links, approve, or
-  reject. Reviewers can also choose whether an approved proposal becomes
-  canonical company context immediately.
-- **Review gating.** High-confidence non-sensitive entries can publish immediately; company-tier or sensitive entries can queue as proposals for approval.
-- **Cited retrieval.** V1 exposes `search-knowledge` and `get-knowledge` for
-  distilled company memory. The V1.5 expansion adds a Search route and
-  `search-everything` action for searching knowledge, raw captures, and source
-  records together, then drilling into `get-knowledge` / `get-capture`.
-- **Pilot and Ops controls.** Slack pilots stay bounded by default, `get-pilot-report` summarizes source quality without raw bodies, and the Ops route tracks stale or failed distillation queue items with safe retry controls.
-- **Shared integrations.** The Sources page shows Brain source records beside
-  reusable workspace connection grants and provider readiness. Reusable
-  integrations own provider identity, credential references, and app grants;
-  Brain sources own app-specific choices such as channels, repositories,
-  cursors, review posture, and distillation state. The provider-reader runtime
-  gives shared provider search/get contracts; live provider API calls stay
-  template-owned unless a reader is explicitly promoted to shared.
-- **Ambient context.** Canonical approved entries can mirror into workspace
-  resources under `context/company-brain/...` for cross-app context. The Review
-  route exposes this as a per-proposal switch; the Knowledge route can publish
-  or unpublish approved memories later with `set-knowledge-canonical`. Both
-  flows preview the exact Markdown through `preview-canonical-resource` before
-  the resource is written or removed.
-
-Brain intentionally uses SQL text search and agentic query expansion for v1.
-There is no vector database requirement, so the template stays portable across
-SQLite, Postgres, Neon, D1, Turso, and similar hosts. Privacy is handled with
-source allow-lists, personal-source exclusions, redaction, and review gates.
-Raw capture content is redacted by default in review/search surfaces;
-editor-authorized distillation can request exact raw text for quote validation.
-
-## Search Model
-
-Brain search has three layers:
-
-- **V1 Company Brain search:** answer from reviewed, distilled knowledge first.
-  This is the trust layer for decisions, policies, product facts, processes,
-  and durable summaries.
-- **V1.5 Brain-wide search:** use `search-everything` as the broad first
-  pass across knowledge, raw captures, and sources. Then call `get-knowledge`
-  for reviewed entries or `get-capture` for exact source context and links.
-  The action also returns `federatedCoverage`: Brain source/provider coverage,
-  reusable workspace connection readiness, compact discovered agent metadata
-  when available, and deterministic hints for which specialist app the agent
-  should ask next.
-- **V2 federated workspace search:** reuse workspace connections and search
-  across apps/sources with permission-aware result filtering and ranking. The
-  expertise graph belongs to this future/platform layer. V1.5 does not directly
-  read sibling app databases; cross-app work is delegated from the agent loop
-  with `call-agent`.
-
-Agents should cite evidence links or source URLs whenever available. If Brain
-does not return support for a question, the agent should report that honestly
-instead of implying the company memory contains an answer.
-
-Use `federatedCoverage.delegationHints` as routing guidance, not as retrieved
-evidence: Analytics owns dashboards/metrics, Mail/Gmail owns mailbox-native
-search, and Dispatch owns workspace resources, provider grants, approvals,
-secrets, recurring jobs, and cross-app routing.
+```bash
+pnpm dlx @agent-native/core create my-brain --template brain --standalone
+```
+
+Then open the app, add sources, import a transcript, and ask the agent to
+distill cited memories from the raw capture.
+
+## Connecting sources
+
+Brain resolves provider credentials from a granted workspace connection first,
+then from backward-compatible Brain-local or registered vault credentials.
+Brain source credentials do not fall back to deploy-level environment variables.
+If a shared provider already exists, grant Brain access instead of copying the
+same secret into a Brain-specific setting.
+
+**Slack.** Create a source scoped to specific channel IDs. The connector
+verifies each configured conversation, rejects DMs and MPIMs, and stores cursor
+state so each sync resumes where the last one stopped. A safe rollout flow on
+each Slack source card lets you **Test** the credential and allow-list without
+reading history, run a tiny capped **Safe pilot** sample, **Review captures**,
+and approve in the **Review queue** before anything becomes queryable. Grant the
+bot only the scopes the source needs (credential validation, allow-list
+verification, allow-listed channel history, and durable permalinks).
+
+**Granola.** Create a source with a polling window and page size. Granola
+Enterprise API keys expose Team-space notes, not private notes or folders. Brain
+stores the note summary, transcript, attendees, calendar metadata, and source
+URL as a raw capture before distillation.
+
+**GitHub.** Create a source scoped to approved repositories. The connector
+imports bounded issue and pull-request context with stable source URLs that can
+be distilled like Slack or meeting context. This is Brain context ingestion, not
+a replacement for Analytics-style GitHub reporting.
+
+**Clips and generic webhooks.** Brain exposes a signed webhook for Clips and
+generic transcript/capture imports at `/api/_agent-native/brain/ingest`. Create
+a source with a `sourceKey` to receive a bearer token, then send a
+`RawCapturePayload` with `Authorization: Bearer <ingestToken>`. Generic sources
+use the same payload shape for call transcripts, customer research, imported
+notes, or any other source that can produce a bounded capture.
+
+Slack, Granola, and GitHub sources can opt into background `autoSync` with a
+poll cadence once review quality is proven.
 
 ## Brain vs Dispatch
 
@@ -145,299 +138,29 @@ In a multi-app workspace, Dispatch can route a question to Brain over A2A and
 can grant Brain shared provider credentials. Brain remains the specialist for
 approved source ingestion, review, retrieval, and cited Company Brain answers.
 Brain exposes read-only, citation-backed retrieval as its public A2A capability
-so Dispatch and sibling apps can ask company-memory questions. That is not
-anonymous data access: the A2A agent card is public discovery metadata, while
-retrieval still happens inside Brain's authenticated action surface. Callers
-ask over A2A, then Brain uses `ask-brain`, `search-everything`,
-`get-knowledge`, and `get-capture` with its normal review, redaction, citation,
-and source-access rules.
-
-## Scaffolding
-
-```bash
-pnpm dlx @agent-native/core create my-brain --template brain --standalone
-```
-
-Then open the app, add sources, import a transcript, and ask the agent to distill cited memories from the raw capture.
-
-For a public demo, open the Ask page and choose **Start demo**. Brain seeds the
-product-decision corpus, runs the demo eval, asks the cited freemium question,
-then offers Review and Knowledge follow-ups. The seeded corpus demonstrates
-product-decision recall, citation links, supersede behavior, review gating,
-redaction, personal-content exclusion, and honest not-found behavior without
-connecting a real workspace.
-
-## Generic Ingest
-
-Brain exposes a signed webhook for Clips and generic transcript/capture imports
-at:
-
-```txt
-/api/_agent-native/brain/ingest
-```
-
-Create a source with a `sourceKey` to receive a bearer token, then send a `RawCapturePayload`:
-
-```json
-{
-  "sourceKey": "clips",
-  "externalId": "meeting-123",
-  "title": "Pricing decision review",
-  "participants": ["Ada", "Grace"],
-  "occurredAt": "2026-05-15T15:00:00.000Z",
-  "transcript": "We decided to keep annual pricing because...",
-  "sourceUrl": "https://example.com/share/meeting-123",
-  "tags": ["pricing", "product"],
-  "raw": {}
-}
-```
-
-Set `Authorization: Bearer <ingestToken>` on the request. Clips can export to
-that endpoint without Brain reading the Clips database directly. Generic sources
-use the same payload shape for call transcripts, customer research, imported
-notes, or any other source that can produce a bounded capture.
-
-## Slack Backfill
-
-Brain resolves `SLACK_BOT_TOKEN` from a granted Slack workspace connection
-first, then from backward-compatible Brain-local or registered vault
-credentials. It scans only channels that an admin configures on the source:
-
-```bash
-pnpm --filter brain action create-source \
-  --title "Slack product channels" \
-  --provider slack \
-  --visibility org \
-  --config '{"channelIds":["C0123456789"],"historyLimit":15}'
-```
-
-The connector verifies each configured conversation before reading history and
-rejects DMs and MPIMs. Cursor state is stored on the source so each sync can pick
-up where the last one stopped, including after Slack rate limiting.
-
-Use `test-slack-connection` before a production backfill. It validates the
-Slack bot token with `auth.test` and, when channel refs are provided, checks
-channel metadata without reading message history.
-
-For Slack, grant the bot the smallest scopes needed for the source:
-
-- `auth.test` for credential validation.
-- `conversations.info` for allow-list verification and DM/MPIM rejection.
-- `conversations.history` for allow-listed channel history.
-- `chat.getPermalink` for durable citations.
-- `conversations.list` only when setup resolves channel names instead of IDs.
-
-Private channels require inviting the bot to the channel. Public channels may
-also require joining or inviting the bot depending on the Slack app posture.
-
-For local CLI/action-runner QA, put `SLACK_BOT_TOKEN` in a workspace connection,
-registered vault secret, or Brain-local app credential before running source
-actions. Brain source connectors intentionally do not read process environment
-variables directly, so `.env.local` alone is not a credential source.
-
-Use `run-slack-pilot` for a safer first-pass rollout report. The default action
-validates the Slack credential and allow-listed channels, reports guardrails,
-privacy exclusions, current knowledge/proposal counts, and next steps, and does
-not call `conversations.history`. Only pass `readHistory: true` when the user
-explicitly wants a tiny sample sync; the pilot caps the read to two validated
-channels, one page per channel, ten messages per page, ten permalinks,
-`autoSync: false`, and a recent default history window.
-
-After a sample sync succeeds, list the imported inventory before opening raw
-message bodies:
-
-```bash
-pnpm --filter brain action list-captures \
-  --sourceId <source-id> \
-  --status queued
-```
-
-The listing omits raw capture content by default and includes each capture's
-latest distillation queue state. Use `get-capture` for one specific record when
-a reviewer or agent needs exact source context, then write only durable, cited
-knowledge. Keep `autoSync` disabled until the channel allow-list, review gate,
-and first distilled entries are validated.
-
-The Sources UI has the same flow: open **Captures** on a source card to review
-queued records, opt into short previews only when needed, queue distillation,
-see whether a capture is waiting on the distillation worker, or mark non-company
-material ignored.
-
-Slack source cards expose this as a clean rollout flow: **Test** checks the
-credential and allow-list without history reads, **Safe pilot** imports only a
-tiny capped sample, **Review captures** opens the capture inventory, and
-**Review queue** sends reviewers to approve proposals before they become
-queryable company memory.
-
-Use `get-pilot-report` after a sample sync to inspect sync health, capture
-counts, queue state, published knowledge, pending proposals, privacy notes, and
-recommended rollout steps without returning raw capture bodies.
-
-Recommended production rollout:
-
-1. Start with one or two high-signal channels and channel IDs.
-2. Keep `autoSync: false` until review quality is proven.
-3. Run `test-slack-connection`, then `run-slack-pilot` without history.
-4. Run one explicit `run-slack-pilot --readHistory true` sample when the report
-   is clean.
-5. Review captures with previews only when needed; ignore social, personal, or
-   thin records.
-6. Distill durable company context, approve proposal-gated memories, and verify
-   `ask-brain` returns cited Slack permalinks.
-7. Expand with bounded manual `sync-source` runs before enabling background
-   polling.
-
-When approving a proposal, keep the company-context switch off unless the
-memory should be ambient context for Dispatch and other apps. Turn it on for
-canonical decisions, policies, product facts, or durable process notes that are
-safe to place under `context/company-brain/...`; Brain shows the exact Markdown
-preview before approval publishes it. Use the Knowledge route or
-`set-knowledge-canonical --published=false` to remove a mirrored resource after
-previewing what will be removed, without deleting the underlying Brain
-knowledge.
-
-Distillation has two worker paths. When a Brain tab is open, the app shell
-claims queued items with `claim-distillation` and delegates them to the app
-agent in the background. When no tab is open, the `brain-distillation` server
-sweep runs with `RUN_BACKGROUND_JOBS`, claims due queued rows, reclaims stale
-`processing` rows, and invokes the same agent loop headlessly. Re-running
-`enqueue-distillation` for an active queue item refreshes the handoff instead
-of duplicating queue rows. The agent reads the capture, writes cited knowledge
-or review proposals, then calls `mark-capture-distilled`, which marks the
-active queue row done. If the agent does not close the queue, the worker
-requeues the item with a short delay and eventually fails it after repeated
-attempts.
-
-The Ops route is the operator view for distillation. It lists queued,
-processing, failed, done, stale, and retryable handoffs, backed by
-`list-distillation-queue` and `retry-distillation`.
-
-## Granola Polling
-
-Brain resolves `GRANOLA_API_KEY` from a granted Granola workspace connection
-first, then from backward-compatible Brain-local or registered vault
-credentials. It polls Granola's public API for notes, then fetches each note
-with its transcript:
-
-```bash
-pnpm --filter brain action create-source \
-  --title "Granola team notes" \
-  --provider granola \
-  --visibility org \
-  --config '{"pageSize":10,"updatedAfter":"2026-05-01T00:00:00.000Z"}'
-```
-
-Granola Enterprise API keys expose Team-space notes, not private notes or
-private folders. Brain stores the note summary, transcript, attendees, calendar
-metadata, and source URL as a raw capture before distillation.
-
-## GitHub Connector
-
-GitHub is Brain's first reusable connector proof. It resolves `GITHUB_TOKEN`
-from a granted GitHub workspace connection first, then from backward-compatible
-Brain-local or registered vault credentials, and imports bounded issue and pull
-request context from approved repositories:
-
-```bash
-pnpm --filter brain action create-source \
-  --title "GitHub product repos" \
-  --provider github \
-  --visibility org \
-  --config '{"repositories":["owner/repo"],"state":"all","limit":25}'
-```
-
-The connector accepts `repositories` or `repos`, optional `state`, `limit`,
-`includeIssues`, and `includePullRequests`. Imported items become raw captures
-with stable source URLs and can be distilled like Slack or meeting context. This
-is intentionally Brain context ingestion, not a replacement for Analytics-style
-GitHub reporting.
-
-## Shared Workspace Connections
-
-Brain sources can reuse shared workspace connections when Dispatch or another
-workspace setup has already connected a provider and granted `appId=brain`
-access. The source record still belongs to Brain: it stores channel ids,
-repositories, sync cursors, review settings, and other source-specific choices,
-while the provider credential stays in the workspace vault behind a connection
-or grant credential ref.
-
-The `list-connection-providers` action returns each Brain provider with
-connection counts, grant state, credential reference names, credential health,
-and whether Brain has access. It never returns credential values. Source sync
-resolves credentials in this order:
-
-1. Granted `workspace_connections` / `workspace_connection_grants` credential
-   refs for `appId=brain`.
-2. Backward-compatible Brain-local SQL credentials.
-3. Registered vault secrets for the same user/org/workspace scope.
-
-Brain source credentials do not fall back to deploy-level environment
-variables. If a shared provider exists but has not been granted to Brain, grant
-Brain access instead of copying the same secret into a Brain-specific setting.
-
-Keep the ownership model simple:
-
-- Reusable workspace integrations own provider identity, account metadata,
-  credential ref names, and app grants.
-- Dispatch is the workspace control plane where admins usually connect, repair,
-  and grant those integrations.
-- The vault owns the secret values.
-- Brain owns source-local choices such as Slack channels, GitHub repositories,
-  Granola polling windows, cursors, review posture, and distillation status.
-- Agents should inspect connection readiness first, then request a grant or
-  source configuration instead of asking the user for another provider token.
-
-The Sources page surfaces the same provider catalog. A provider can be:
-
-- `connected` when an active workspace connection is already granted to Brain.
-- `granted` when Brain can access the connection but it is not currently active.
-- `needs_grant` when the workspace has a connection that has not been granted to
-  Brain.
-- `not_connected` when Brain is using scoped credentials or has no connection
-  yet.
-
-The page also shows provider readiness: ready, grant needed, needs repair,
-missing keys, or metadata only. Agents should inspect this same readiness via
-`list-connection-providers` before asking users for duplicate Slack, Granola,
-GitHub, or future provider credentials.
-
-## Scheduled Sync
-
-The Sources page includes a setup sheet for Slack, Granola, GitHub, Clips,
-generic webhooks, and manual imports. Slack, Granola, and GitHub sources can
-opt into `autoSync` with a `pollMinutes` cadence. Use `sync-source` for a
-single source, `sync-due-sources` for all due accessible sources, or enable
-`RUN_BACKGROUND_JOBS=1` locally to let the Brain background job poll due sources
-from the Nitro process.
-
-## Demo and Eval
-
-Brain ships with a repeatable product-decision demo corpus. `seed-demo-data`
-loads Slack, Clips, Granola, and webhook-style captures; creates cited knowledge
-about retiring freemium, how Decision Digest works, and why product decisions
-are the lead demo; queues a policy-sensitive proposal; redacts an email; and
-keeps a personal aside out of queryable knowledge.
-
-`run-demo-eval` checks the behavior that matters most for trust: recall,
-citations, supersede links, proposal gating, redaction, and personal-content
-exclusion. The Ask page includes a compact **Start demo** CTA for empty
-workspaces and reveals Review, Knowledge, and **Run eval** follow-ups once the
-demo is ready.
-
-`run-retrieval-eval` checks an offline real-channel-style retrieval set. It
-uses existing workspace Brain data when the expected branch-safety answers
-already have citation-backed support; otherwise, with `seedIfMissing` enabled,
-it seeds a small Slack-style fallback corpus and re-runs the same checks. The
-result covers Slack-style citations, branch-safety terms, and an unsupported
-cleanup-cron not-found case. The same mode is available through `run-demo-eval`
-with `mode: "retrieval"`.
-
-The repository-level `pnpm test` command includes `pnpm test:brain-evals`, which
-runs Brain's product-demo and retrieval action evals against a disposable local
-SQLite database. The CI/prep eval path is fully seeded and offline; it does not
-require production Slack, Granola, Clips, or any external workspace data.
-
-## Privacy And Gating
+so Dispatch and sibling apps can ask company-memory questions — the A2A agent
+card is public discovery metadata, while retrieval still happens inside Brain's
+authenticated action surface.
+
+## Data model overview
+
+Brain intentionally uses SQL text search and agentic query expansion. There is
+no vector database requirement, so the template stays portable across SQLite,
+Postgres, Neon, D1, Turso, and similar hosts.
+
+- **Sources** hold connector configuration: provider, allow-listed channels or
+  repositories, sync cursors, review posture, and distillation state.
+- **Raw captures** store transcripts, channel exports, notes, and webhook
+  imports in portable SQL with dedupe keys and source metadata. Raw content is
+  redacted from listing/search surfaces by default.
+- **Distilled knowledge** holds atomic entries with kind, topic, entities,
+  confidence, exact evidence quotes, and supersede links.
+- **Proposals** queue company-tier or sensitive entries for review before they
+  become durable company memory.
+- **Application state** mirrors route, filters, and selected IDs so the agent
+  always knows the current navigation and selection.
+
+## Privacy and gating
 
 Brain is designed for company memory, not personal surveillance:
 
@@ -451,18 +174,21 @@ Brain is designed for company memory, not personal surveillance:
 - Settings control default publish tier, whether company-tier knowledge requires
   approval, citation requirements, email redaction, and connector error
   notifications.
-- Demo/eval coverage checks proposal gating, PII redaction, personal-content
-  exclusion, citations, real-channel-style retrieval, and honest not-found
-  behavior.
 
-## Developer Notes
+## Customizing it
 
 The template follows the agent-native four-area contract:
 
-- **UI:** Ask, Search, Knowledge, Review, Sources, Ops, and Settings routes.
-- **Actions:** imports, source management, pilot reports, distillation queueing/claiming/retry, proposal review, cited search, and navigation/context actions.
-- **Skills/instructions:** Brain-specific guidance for distillation and retrieval.
-- **Application state:** route, filters, and selected IDs mirror into `application_state` for agent context.
+- **UI:** Ask, Search, Knowledge, Review, Sources, and Settings routes.
+- **Actions:** imports, source management, pilot reports, distillation, proposal
+  review, cited search, and navigation/context actions.
+- **Skills/instructions:** Brain-specific guidance for distillation and
+  retrieval in `templates/brain/.agents/skills/`.
+- **Application state:** route, filters, and selected IDs mirror into
+  `application_state` for agent context.
+
+Ask the agent to make changes for you — it can edit its own source. See
+[Self-Modifying Code](/docs/key-concepts#agent-modifies-code).
 
 See [Dispatch](/docs/dispatch) for the workspace control plane, the
 [Dispatch template](/docs/template-dispatch) for the scaffolded app,

package/docs/content/template-clips.md

@@ -1,11 +1,11 @@
 ---
 title: "Clips"
-description: "Async screen recording (Loom-style), calendar-synced meeting notes (Granola-style), and push-to-talk voice dictation (Wisprflow-style) — all transcribed, summarized, and searchable in one app you own."
+description: "Async screen recording, calendar-synced meeting notes, and push-to-talk voice dictation — all transcribed, summarized, and searchable in one app you own."
 ---
 
 # Clips
 
-A capture-everything app: screen recordings (Loom-style), meeting notes from your calendar (Granola-style), and Fn-hold voice dictation (Wisprflow-style). The agent transcribes, titles, summarizes, and indexes all of it — then lets you ask "find the clip where we discussed the rollout plan" and searches across every transcript you've ever made.
+A capture-everything app: screen recordings, meeting notes from your calendar, and Fn-hold voice dictation. The agent transcribes, titles, summarizes, and indexes all of it — then lets you ask "find the clip where we discussed the rollout plan" and searches across every transcript you've ever made.
 
 <!-- screenshot:
   app: clips
@@ -69,6 +69,46 @@ pnpm dlx @agent-native/core create my-clips --template clips --standalone
 
 Clips is a larger template with a native recorder (it ships a desktop companion for local capture). See the template `README.md` for setup specifics around screen-capture permissions and storage configuration.
 
+### Data model
+
+All data lives in SQL via Drizzle ORM. Schema: `templates/clips/server/db/schema.ts`. Recordings, meetings, dictations, calendar accounts, and vocabulary all carry the standard `ownableColumns` and have a matching framework shares table, so they slot into the per-user / per-org sharing model.
+
+| Table                                           | What it holds                                                                                                                                                                 |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `recordings`                                    | The core resource — title, video URL/format/size, duration, thumbnails, status, non-destructive `edits_json`, `chapters_json`, privacy (password, expiry), and player toggles |
+| `recording_transcripts`                         | Per-recording transcript: `segments_json` (`{startMs,endMs,text}`), `full_text`, language, and status                                                                         |
+| `recording_tags`                                | Free-form tags on a recording                                                                                                                                                 |
+| `recording_ctas`                                | Call-to-action buttons (label, url, color, placement) overlaid on a recording                                                                                                 |
+| `recording_comments`                            | Threaded, timestamped comments with emoji-reaction map and resolved flag                                                                                                      |
+| `recording_reactions`                           | Emoji reactions pinned to a video timestamp (anonymous viewers allowed)                                                                                                       |
+| `recording_viewers` / `recording_events`        | View analytics: per-viewer watch time and completion, plus granular events (view-start, watch-progress, seek, pause, cta-click, reaction)                                     |
+| `clips_meetings`                                | Calendar-sourced or ad-hoc meetings — schedule/actual spans, platform, user notes, AI `summary_md`, `bullets_json`, `action_items_json`, and the link to its `recording_id`   |
+| `meeting_participants` / `meeting_action_items` | Attendees and extracted action items for a meeting                                                                                                                            |
+| `calendar_accounts` / `calendar_events`         | Connected calendar accounts (OAuth tokens live in `app_secrets`, only referenced here) and synced event snapshots                                                             |
+| `clips_dictations`                              | Push-to-talk dictation history — raw `full_text`, optional `cleaned_text`, source (`fn-hold`, etc.), and target app                                                           |
+| `clips_vocabulary`                              | Personal vocabulary corrections (term → preferred replacement) that bias future dictations                                                                                    |
+| `spaces` / `space_members` / `folders`          | Library organization — spaces (topic-scoped containers), their members, and nestable folders                                                                                  |
+| `organization_settings`                         | Per-org Clips sidecar: brand color, logo, default visibility                                                                                                                  |
+
+Recordings and transcripts are intentionally separate tables so the library and transcript views can each render fast. Meetings compose with recordings rather than duplicating media: a meeting owns the recording it captures, but the `recordings` row remains the source of truth for the video and per-segment transcript.
+
+Routes in the UI live under `templates/clips/app/routes/` — the authenticated app sits under `_app.*` (library, spaces, folders, meetings, dictate, insights, trash, settings), with public surfaces at `r.$recordingId`, `share.$shareId`, `embed.$shareId`, and `invite.$token`.
+
+### Key actions
+
+Every agent-callable operation is a TypeScript file in `templates/clips/actions/`, auto-mounted at `POST /_agent-native/actions/:name` and runnable from the CLI as `pnpm action <name>`. There are ~80 actions; the useful groupings:
+
+- **Recording lifecycle** — `create-recording`, `finalize-recording`, `update-recording`, `set-thumbnail`, `archive-recording` / `restore-recording` / `trash-recording` / `delete-recording-permanent`, `move-recording`, `tag-recording`.
+- **Transcript & AI** — `request-transcript`, `cleanup-transcript`, `regenerate-title` / `regenerate-summary` / `regenerate-chapters`, `set-chapters`, `generate-workflow`. (`cleanup-transcript` and `finalize-meeting` are server-side media-pipeline calls; most other AI features delegate to the agent chat.)
+- **Editing** — non-destructive `trim-recording`, `split-recording`, `remove-filler-words`, `remove-silences`, plus `stitch-recordings`, `undo-edit`, `clear-edits`. Edits accumulate in `edits_json`; the client concatenates/exports via ffmpeg.wasm.
+- **Meetings** — `create-meeting`, `start-meeting-recording` / `stop-meeting-recording`, `finalize-meeting`, `update-meeting`, `get-meeting`, `list-meetings`, plus calendar wiring `connect-calendar` / `disconnect-calendar` / `sync-calendars` / `list-calendar-accounts`.
+- **Dictation** — `create-dictation`, `cleanup-dictation`, `update-dictation`, `list-dictations`, and `add-vocabulary-term` / `list-vocabulary` for personal vocabulary biasing.
+- **Library organization** — `create-space` / `rename-space` / `delete-space`, `add-space-member` / `remove-space-member`, `create-folder` / `rename-folder` / `delete-folder`, `add-recording-to-space`.
+- **Sharing, comments & engagement** — framework sharing actions plus `create-cta` / `update-cta` / `delete-cta`, `add-comment` / `reply-to-comment` / `resolve-comment` / `react-to-comment` / `delete-comment`, `react-to-recording`, `list-viewers`.
+- **Organizations & members** — `create-organization`, `set-organization-branding`, `invite-member` / `accept-invite` / `decline-invite` / `get-invite`, `remove-member`, `update-member-role`, `list-organization-state`, `list-notifications`.
+- **Search, insights & export** — `search-recordings` (matches titles, descriptions, transcript text, and comments, with timestamps), `get-recording-insights`, `get-organization-insights`, `export-insights-csv`, `export-to-brain`.
+- **Context & navigation** — `view-screen` (current clip, playhead, selected transcript range) and `navigate`; `refresh-list` after mutations.
+
 ### Customize it
 
 Clips is a complete, cloneable template — fork it and ask the agent to extend it. Some examples:

package/docs/content/template-content.md

@@ -58,7 +58,7 @@ pnpm install
 pnpm dev
 ```
 
-Open `http://localhost:8080` and create your first page. The agent panel is on the right — try asking it to "create a page called Onboarding and add three sub-pages under it".
+Open `http://localhost:8083` and create your first page. The agent panel is on the right — try asking it to "create a page called Onboarding and add three sub-pages under it".
 
 ### Key features (technical) {#key-features}