@agent-native/core 0.16.1 → 0.16.3

package/docs/content/code-agents-ui.md

@@ -5,14 +5,22 @@ description: "Build and customize Agent-Native Code surfaces with the shared UI
 
 # Agent-Native Code UI
 
-Agent-Native Code is the Agent-Native coding surface: a local Claude Code/Codex-style workspace for coding sessions, slash commands, migrations, audits, transcripts, and follow-ups.
+Agent-Native Code is the Agent-Native coding surface: a local Claude Code/Codex-style workspace for coding sessions, slash commands, migrations, audits, transcripts, run controls, and follow-ups. A bare `npx @agent-native/core@latest` or installed `agent-native` command opens this workspace; `agent-native code` is the explicit subcommand for the same experience.
 
 There are three layers:
 
-- **CLI**: `npx @agent-native/core@latest code` starts and resumes runs.
-- **Desktop**: the left-sidebar Code surface adds native terminal launch, app webviews, and desktop deep links.
+- **CLI**: `npx @agent-native/core@latest`, `agent-native`, and `agent-native code` start, resume, inspect, and stop runs.
+- **Desktop**: the left-sidebar Code tab adds native terminal launch, app webviews, and desktop deep links while using the same run model.
 - **Shared UI**: `@agent-native/code-agents-ui` renders the reusable React surface.
 
+The current split is intentionally converging: the standard agent sidebar and
+Agent Teams run on the core `run-manager` lifecycle, while Agent-Native Code
+uses local long-running sessions backed by the file-based Code run store and the
+shared background-run controller vocabulary. New surfaces should build on the
+shared background-run adapter/foundation instead of inventing another
+lifecycle, so CLI, Desktop, background sessions, and sub-agents keep moving
+toward one run model.
+
 The shared UI is host-driven. It does not know whether it is running in Electron, a browser template, or a future hosted shell. Hosts provide a `CodeAgentsHost` implementation.
 
 ```ts
@@ -37,6 +45,13 @@ export function CodeSurface() {
 }
 ```
 
+Hosts can mix run sources in the same list. Local Agent-Native Code sessions
+can appear next to Agent Teams or other background-run adapters as long as each
+entry normalizes to `CodeAgentRun`. When a host supplies `sourceLabel`,
+`source`, or `kind`, the hub renders a small source label such as "Local Code"
+or "Agent Teams" in the run list and selected-session header. Omit those fields
+for a single-source surface; the empty state and base layout stay unchanged.
+
 ## Desktop Host
 
 Desktop uses the shared UI but keeps privileged capabilities in Electron:
@@ -82,6 +97,79 @@ The template wraps the local run store through normal actions:
 
 It uses `@agent-native/core/code-agents`, which exposes the same file-backed run store and executor used by the CLI.
 
+## CLI Run Controls
+
+The top-level CLI behaves like Claude Code or Codex:
+
+```bash
+npx @agent-native/core@latest
+agent-native
+agent-native "fix the failing auth tests"
+agent-native code
+```
+
+Inside the framework checkout, use `pnpm dev:cli ...` to exercise the source
+CLI before a build, for example `pnpm dev:cli --help` or
+`pnpm dev:cli code goals`.
+
+Use `agent-native code` when you want the explicit namespace. Built-in slash
+goals and project commands can run inside the interactive workspace or directly
+from the shell:
+
+```bash
+agent-native code /migrate ./legacy-app --emit ./migration-dossier
+agent-native code /audit --url https://example.com
+agent-native code /release-check
+```
+
+Project commands come from `.agents/commands/*.md`; project skills come from
+`.agents/skills/*/SKILL.md`. The control commands operate on the same run
+records that the Desktop Code tab and shared UI display:
+
+```bash
+agent-native code list
+agent-native code status --last
+agent-native code attach --last
+agent-native code logs --last
+agent-native code resume --last
+agent-native code stop --last
+agent-native code ui
+```
+
+`resume` appends context and continues a run, `status` reports the latest run
+state, `stop` asks the active controller to halt work, and `ui` opens the local
+Code surface. These are run controls, not a separate implementation path.
+
+For cross-surface lists, dashboards, or monitoring panes, prefer the shared
+background-run exports from `@agent-native/core/code-agents` over reading Code
+run files directly. They normalize local Code sessions into the same vocabulary
+used by hosted background work: run id, status, cwd, needs-input,
+needs-approval, transcript events, and artifact root.
+
+Hosted Agent Teams are also exposed from the agent chat route for browser
+hosts that need a Code hub-compatible list without direct server imports:
+`GET /_agent-native/agent-chat/runs/list?goalId=agent-team` returns
+`{ status: "ok", goalId, runs }`, where each run includes `kind`,
+`source`, `sourceLabel`, `status`, `title`, timestamps, and task metadata.
+`GET /_agent-native/agent-chat/runs/:id/background-events` returns the
+shared background transcript events for an Agent Teams run.
+
+Adapter-backed hosts may also attach source metadata:
+
+```ts
+{
+  id: run.id,
+  goalId: "task",
+  title: run.title,
+  source: "agent-teams",
+  sourceLabel: "Agent Teams",
+  kind: "background-run",
+  status: run.status,
+  createdAt: run.createdAt,
+  updatedAt: run.updatedAt,
+}
+```
+
 ## Run Store
 
 Local Agent-Native Code runs are stored at:
@@ -170,6 +258,8 @@ Background coding-agent work should reuse the same harness as the rest of
 Agent-Native:
 
 - Use the Code run store/executor for local Code sessions.
+- Use the shared background-run adapter/foundation when a surface needs to list,
+  inspect, or bridge local Code sessions alongside other background work.
 - Use core `run-manager` for hosted agent runs so streams, aborts, heartbeats,
   resumability, soft timeouts, and stuck-run cleanup behave consistently.
 - Use `agent-teams` / `spawnTask()` when the UI is delegating work to a
@@ -179,6 +269,11 @@ Do not add a parallel background-agent runner just because a new surface needs a
 different layout. Build a host adapter or UI slot on top of the shared harness
 instead.
 
+Regression rule for new prompt or background surfaces: Code, Brain, and the
+standard sidebar must keep using `PromptComposer` through the shared composer
+stack, and background work must use the Code run store, the background-run
+adapter, `run-manager`, or `agent-teams` rather than a bespoke queue/runner.
+
 ## Follow-Ups
 
 Follow-ups on active runs support two delivery modes:
@@ -188,6 +283,11 @@ Follow-ups on active runs support two delivery modes:
 
 Inactive runs keep the compatible behavior: the follow-up is appended and the run resumes immediately.
 
+That gives Code the same user-facing two-way messaging shape as Agent Teams:
+the user can keep talking to active work, but execution only consumes that
+message at a safe continuation point. If a runner cannot steer immediately, it
+must persist the follow-up as queued work rather than dropping or racing it.
+
 ## Remote Dispatch
 
 Desktop can expose the local Code Agent runner to a deployed Dispatch relay so a

package/docs/content/creating-templates.md

@@ -364,3 +364,19 @@ Community templates can be created from a GitHub repo:
 ```bash
 pnpm dlx @agent-native/core create my-app --template github:user/repo
 ```
+
+## Test Unpublished Framework Changes {#test-unpublished-framework-changes}
+
+When you are working inside the framework monorepo and need a generated
+workspace to use unpublished package or template changes, run create with the
+local-package flag:
+
+```bash
+AGENT_NATIVE_CREATE_USE_LOCAL_CORE=1 pnpm --filter @agent-native/core create my-platform
+```
+
+The generated workspace links the local `@agent-native/core` and
+`@agent-native/dispatch` packages, so changes to Core APIs, Dispatch workspace
+behavior, or first-party templates can be tested before publishing. The package
+`prepack` scripts build `dist` before linking, which keeps the generated
+workspace pointed at current build output.

package/docs/content/getting-started.md

@@ -30,6 +30,29 @@ The `create` command defaults to a workspace monorepo. It shows a multi-select p
 
 Open the URL the dev server prints. Workspace apps use app-specific ports, often `http://localhost:8080` or another 808x port; standalone apps usually use `http://localhost:3000`.
 
+### Testing local framework changes {#testing-local-framework-changes}
+
+Framework contributors can scaffold against the current checkout instead of the
+published packages:
+
+```bash
+AGENT_NATIVE_CREATE_USE_LOCAL_CORE=1 pnpm --filter @agent-native/core create my-platform
+```
+
+With that flag, generated workspaces link both the local `@agent-native/core`
+and local `@agent-native/dispatch` packages. Use it when you need to verify
+unpublished template or package changes end-to-end in a freshly generated
+workspace. The packages run their `prepack` build first, so the linked packages
+serve fresh `dist` output instead of stale build artifacts.
+
+To exercise the repo-local CLI itself without building first, run it through
+the root script:
+
+```bash
+pnpm dev:cli --help
+pnpm dev:cli code goals
+```
+
 ## Creating vs adding apps {#creating-vs-adding-apps}
 
 Run `create` from the folder where you want a brand-new workspace:
@@ -68,15 +91,18 @@ That parity between agent and UI is the whole point — see [What Is Agent-Nativ
 
 ## Try one concrete next step {#first-next-step}
 
-From here, use any AI coding tool (Claude Code, Cursor, Windsurf, Builder.io) to customize the app. The agent instructions in `AGENTS.md` are already set up so any tool understands the codebase.
+From here, use any AI coding tool (Agent-Native Code, Claude Code, Cursor, Windsurf, Builder.io) to customize the app. The agent instructions in `AGENTS.md` are already set up so any tool understands the codebase.
 
 Good first moves:
 
+- **Open Agent-Native Code** — run `npx @agent-native/core@latest` or `npx @agent-native/core@latest code` from the project. A bare command opens the local Claude Code/Codex-like workspace; a bare prompt such as `npx @agent-native/core@latest "rename the app"` starts a Code task directly.
 - **Ask the built-in agent what it sees** — open the agent panel and type "what app am I looking at, and what can you do here?" This verifies the app, UI state, and agent loop are all talking to each other.
 - **Make a tiny customization** — ask your coding tool to rename the app, change the first screen copy, or add one field to a form. It will read `AGENTS.md` for the framework conventions.
 - **Add another app to the same workspace** — use `npx @agent-native/core add-app` from inside the workspace folder. The command starts at `npx`.
 - **Single app instead of a monorepo?** Pass `--standalone` when creating: `npx @agent-native/core create my-app --standalone --template mail`.
 
+Agent-Native Code understands built-in slash goals such as `/migrate` and `/audit`, plus project commands in `.agents/commands/*.md`. Use `agent-native code list`, `status`, `resume`, `stop`, or `ui` to inspect and control the same run from the CLI, the local UI, or the Desktop Code tab.
+
 ## Next docs to read {#next-docs}
 
 Once your app is running, the most useful follow-ups are:
@@ -91,19 +117,19 @@ Once your app is running, the most useful follow-ups are:
 
 Each template is a complete app with UI, agent actions, database schema, and AI instructions ready to go:
 
-| Template                            | Replaces                                         |
-| ----------------------------------- | ------------------------------------------------ |
-| [Calendar](/templates/calendar)     | Google Calendar, Calendly                        |
-| [Content](/templates/content)       | Notion, Google Docs                              |
-| [Brain](/templates/brain)           | Company chat, cited memory, and review queue     |
-| [Slides](/templates/slides)         | Google Slides, Pitch                             |
-| [Analytics](/templates/analytics)   | Amplitude, Mixpanel, Looker                      |
-| [Mail](/templates/mail)             | Superhuman, Gmail                                |
-| [Clips](/templates/clips)           | Replaces Loom — screen + camera recording        |
-| [Design](/templates/design)         | HTML prototyping studios                         |
-| [Forms](/docs/template-forms)       | Typeform                                         |
-| [Dispatch](/docs/template-dispatch) | Workspace control plane — secrets, routing, jobs |
-| [Starter](/docs/template-starter)   | Minimal scaffold — build from scratch            |
+| Template                            | Replaces                                        |
+| ----------------------------------- | ----------------------------------------------- |
+| [Calendar](/templates/calendar)     | Google Calendar, Calendly                       |
+| [Content](/templates/content)       | Notion, Google Docs                             |
+| [Brain](/templates/brain)           | Company chat with cited institutional memory    |
+| [Slides](/templates/slides)         | Google Slides, Pitch                            |
+| [Analytics](/templates/analytics)   | Amplitude, Mixpanel, Looker                     |
+| [Mail](/templates/mail)             | Superhuman, Gmail                               |
+| [Clips](/templates/clips)           | Replaces Loom — screen + camera recording       |
+| [Design](/templates/design)         | HTML prototyping studios                        |
+| [Forms](/docs/template-forms)       | Typeform                                        |
+| [Dispatch](/docs/template-dispatch) | Workspace control plane — integrations, routing |
+| [Starter](/docs/template-starter)   | Minimal scaffold — build from scratch           |
 
 Browse the [template gallery](/templates) for live demos, or see [Templates](/docs/cloneable-saas) for the full list and the clone → customize → deploy flow.
 

package/docs/content/migration-workbench.md

@@ -18,6 +18,12 @@ npx @agent-native/core@latest code /migrate ./my-next-app --out ../migrated-app
 
 **Agent-Native Code** is the open-source Claude Code/Codex-like workspace for coding work in Agent-Native. `agent-native` or `agent-native code` launches it with no prompt required, and a bare prompt starts a generic coding task directly. `/migrate` is one built-in capability for moving an existing app, URL, or described product into agent-native. It uses the same session store, transcript, and desktop hub as the CLI `code` command, so migration behaves like a goal you can resume, attach to, inspect, and stop rather than a separate one-off product.
 
+That session store is local and long-running by design. It is separate from the
+hosted agent sidebar and Agent Teams `run-manager` lifecycle today, but new
+surfaces should bridge through the shared background-run foundation so Code,
+sidebar, Brain, and Agent Teams continue converging on one lifecycle instead of
+growing parallel runners.
+
 By default `/migrate` creates a generic Agent-Native Code session plus a portable migration dossier. Migration is a slash command in the Code workspace, not a normal template to scaffold. The hidden `migration` app is now a legacy/internal detail surface, available with `--app-surface` when a run needs a richer assessment/approval/task/verifier dashboard.
 
 The direct `migrate` command remains a shortcut into the same goal:
@@ -68,11 +74,11 @@ npx @agent-native/core@latest code /audit --url https://example.com
 
 Run `agent-native code goals` to see the goals registered in your checkout. A bare prompt starts a local coding-agent session for open-ended code work, streams the run, records transcript/status/tool events, and accepts follow-up prompts through the same run record.
 
-Bare `agent-native` launches the Agent-Native Code workspace in this branch, and `agent-native "prompt"` starts a generic Agent-Native Code task directly, matching the Codex/Claude Code habit of treating unknown text as a coding prompt. If an installed version does not include that top-level entrypoint yet, run `agent-native code` directly.
+Installed `agent-native` with no arguments launches the Agent-Native Code workspace, and `agent-native "prompt"` starts a generic Agent-Native Code task directly. Use `agent-native create` when you want to scaffold apps or workspaces.
 
 ## Sessions and Modes
 
-The next Agent-Native Code follow-up features make the workspace feel like a local Codex/Claude Code session manager instead of a one-shot command. The CLI and Desktop hub share the same run store, so you can start work in one place and continue it in the other:
+Agent-Native Code makes migration feel like a local Codex/Claude Code session instead of a one-shot command. The CLI and Desktop hub share the same run store, so you can start work in one place and continue it in the other:
 
 ```bash
 npx @agent-native/core@latest code list
@@ -85,6 +91,18 @@ npx @agent-native/core@latest code resume --last "check the auth edge cases next
 
 `list` shows previous and active sessions for the current workspace. `attach` follows a live transcript. `logs` prints the transcript once. `resume` reopens a session with its prior context, and a quoted resume prompt records the next instruction against that same run. If a high-risk command pauses for approval, `approve --last` runs that one pending command and then points you back to resume the session. Desktop adds the visual session picker on top of the same data: choose a run, inspect status and tool events, then attach, resume, stop, or open the run workspace.
 
+The same hub can display mixed background-run sources. Local Agent-Native Code
+runs are available today through the file-backed Code run store, and Agent Teams
+or other hosted background work can appear through adapters that normalize their
+runs to the Code hub contract. Adapters should provide a subtle `sourceLabel`,
+`source`, or `kind` when the list mixes sources, so users can distinguish "Local
+Code" from "Agent Teams" without turning the session picker into a dashboard.
+
+Follow-up prompts have two-way messaging semantics. Active runs can receive
+steering prompts at the next safe continuation point, while queued follow-ups
+run after the current turn completes. If a host cannot apply a message
+immediately, it should persist it as queued work and continue safely.
+
 Run modes make editing policy explicit per session:
 
 | Mode          | CLI flag | Behavior                                                                                                 |
@@ -211,6 +229,11 @@ npx @agent-native/core@latest code /audit --url https://example.com
 
 The hub exposes the same generic run controls the CLI does: the session picker opens past runs, `resume` opens the goal surface or reattaches to the run, a quoted resume prompt records and executes follow-up feedback for executable goals, status refreshes the run list, and stop reports or stops the owning process when one is known. Browser/Desktop approval remains the trust gate for generated output writes. Future coding goals can reuse the same CLI and desktop shell by registering another slash goal or a project command under `.agents/commands/*.md`.
 
+Implementation note: any prompt entry for Code, Brain, or the standard agent
+sidebar should use the shared `PromptComposer` stack. Any background coding or
+sub-agent work should use the Code run store, shared background-run adapter,
+`run-manager`, or Agent Teams primitives rather than a template-specific runner.
+
 ## Emit Mode
 
 Use `--emit` when you want Codex, Claude Code, another code agent, or Agent-Native Desktop to do the next phase without opening the internal run surface:

package/docs/content/multi-app-workspace.md

@@ -31,7 +31,7 @@ Anything every app in your org should agree on can live in `packages/shared`:
 
 Each individual app becomes _just a set of screens_ — routes, dashboards, views, domain-specific actions. Framework defaults cover the rest until you add a real workspace customization.
 
-That same boundary applies when your app wants to use another first-party app. A new workspace dashboard that needs email, calendar, and analytics context should use the existing Mail, Calendar, and Analytics apps as connected neighbors over links or A2A. It should not clone those templates, create a wrapper app that nests them, or scaffold child apps inside itself just to get access to their data or agents. For example, the hosted first-party apps already live at [mail.agent-native.com](https://mail.agent-native.com), [calendar.agent-native.com](https://calendar.agent-native.com), and [analytics.agent-native.com](https://analytics.agent-native.com). Fork or scaffold a copy only when you explicitly want to customize that app; otherwise, using the hosted/shared app keeps base template improvements flowing automatically.
+That same boundary applies when your app wants to use another first-party app. A new workspace dashboard that needs email, calendar, analytics, and company-memory context should use the existing Mail, Calendar, Analytics, and Brain apps as connected neighbors over links or A2A. It should not clone those templates, create a wrapper app that nests them, or scaffold child apps inside itself just to get access to their data or agents. For example, the hosted first-party apps already live at [mail.agent-native.com](https://mail.agent-native.com), [calendar.agent-native.com](https://calendar.agent-native.com), [analytics.agent-native.com](https://analytics.agent-native.com), and [brain.agent-native.com](https://brain.agent-native.com). Fork or scaffold a copy only when you explicitly want to customize that app; otherwise, using the hosted/shared app keeps base template improvements flowing automatically.
 
 ## Getting started {#getting-started}
 

package/docs/content/template-analytics.md

@@ -27,6 +27,10 @@ It's an open-source replacement for Amplitude, Mixpanel, and Looker — for team
 - **Maintain a living data dictionary** of metrics, tables, and SQL recipes so the agent uses the right column names every time (no more guessed `is_closed` when it's actually `hs_is_closed`).
 - **Share dashboards** with your team — private by default, shareable per-user or per-org with viewer / editor / admin roles.
 - **Connect to many sources** out of the box: BigQuery, GA4, Mixpanel, Amplitude, PostHog, HubSpot, Jira, Apollo, Pylon, Gong, Common Room, Twitter, plus app-specific SEO sources.
+- **Reuse workspace integrations** when a workspace has already connected and
+  granted a provider to Analytics. The shared integration stores provider
+  identity and credential refs; Analytics keeps app-specific source selection,
+  data dictionary entries, dashboard SQL, and analysis history.
 
 ## Getting started
 
@@ -143,7 +147,19 @@ Every BigQuery panel's SQL is dry-run against the warehouse before the dashboard
 
 ### Connecting data sources
 
-Open the **Data Sources** page (`/data-sources`) to connect providers. Each source exposes an env-key list, a walkthrough, and a **Test Connection** button. The page calls `/api/credential-status`, `/api/credentials`, and `/api/test-connection`.
+Open the **Data Sources** page (`/data-sources`) to connect providers. Each
+source exposes an env-key list, a walkthrough, and a **Test Connection** button.
+When Analytics is running in a workspace, `data-source-status` also reports
+granted reusable workspace connections for `appId=analytics` so the agent can
+ask for an app grant instead of another copy of the same provider key.
+For reusable providers such as Slack, HubSpot, Notion, and GitHub, the Data
+Sources UI shows the shared integration state directly: ready via workspace,
+needs grant, needs credentials, or local credentials.
+
+Reusable workspace integrations are the runtime direction for shared providers:
+the framework stores provider identity, account metadata, credential refs, and
+per-app grants once; Analytics stores data-source interpretation, source of
+truth choices, metric definitions, dashboards, and analyses.
 
 Credentials are stored via the framework's settings/env layer — no secrets in git. Production requires:
 

package/docs/content/template-brain.md

@@ -1,46 +1,50 @@
 ---
 title: "Brain"
-description: "A public first-party template for cited company memory, reviewable source ingestion, and the path toward universal workspace search."
+description: "Clean company chat backed by cited institutional memory, reviewable source ingestion, and reusable workspace integrations."
 ---
 
 # Brain
 
-Brain is a public first-party template for Company Brain: cited institutional
-memory that agents and humans can search without pretending raw workplace data
-is already clean, complete, or safe to publish. The first-run surface is a
-full-page company chat with demo and eval controls, source health, review
-counts, and cited answers from approved company knowledge.
+Brain is clean company chat backed by cited institutional memory. People ask
+plain-English questions; Brain answers from approved company knowledge with
+links back to the Slack thread, meeting, transcript, issue, or webhook capture
+that supports the answer.
 
 Brain ingests approved Slack channels, Clips recordings, Granola Team-space
 notes, GitHub issues/PRs, and generic transcript/webhook payloads. It stores raw
 captures, distills durable facts/decisions/processes, and routes sensitive or
 low-confidence memories through review before they become company knowledge.
 
+The product surface stays simple on purpose: **Ask** is the primary chat
+experience, while **Sources**, **Review**, and **Knowledge** are admin/support
+surfaces for connecting data, approving proposals, and inspecting cited memory.
+
 Use Brain when your team wants agents to answer questions like "why did we make
 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 is intentionally on an open-source, Glean-shaped path, but it is not a
-complete Glean replacement today. V1 is cited company memory over reviewed
-knowledge. V1.5 adds universal Brain search across knowledge, captures, and
-sources, plus reusable workspace connections for source credentials. V2 points
-toward federated app/source search, permission-aware result filtering, ranking,
-and an expertise graph as a future platform layer.
+complete Glean replacement today. V1 is company chat plus cited memory over
+reviewed knowledge. V1.5 adds Brain-wide search across knowledge,
+captures, and sources, plus reusable workspace connections for source
+credentials. V2 points toward federated app/source search, permission-aware
+result filtering, ranking, and an expertise graph as a future platform layer.
 
 ## What It Includes
 
-- **Full-page company chat.** The Ask route is the main product surface. It
-  shows a compact demo CTA, source health, review count, and suggested
-  company-memory questions. It uses `AgentChatSurface`, so the Brain composer
-  stays on the same shared chat input stack as the agent sidebar and
+- **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. Slack is channel-oriented by design; DMs
-  and MPIMs are not scan targets.
+  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
@@ -54,8 +58,12 @@ and an expertise graph as a future platform layer.
   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, so Brain can use
-  Dispatch/workspace-managed credentials when a grant exists.
+  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
@@ -65,9 +73,10 @@ and an expertise graph as a future platform layer.
 
 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. Raw capture content is
-redacted by default in review/search surfaces; editor-authorized distillation
-can request exact raw text for quote validation.
+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
 
@@ -76,17 +85,28 @@ 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 universal Brain search:** use `search-everything` as the broad first
+- **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.
+  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.
+
 ## Brain vs Dispatch
 
 Brain and Dispatch are complementary, but they do different jobs:
@@ -95,12 +115,19 @@ Brain and Dispatch are complementary, but they do different jobs:
   distills durable facts/decisions/processes, answers from cited evidence, and
   exposes approved knowledge to agents.
 - **Dispatch owns the workspace control plane.** It centralizes messaging,
-  secrets, recurring jobs, approvals, A2A orchestration, and workspace-wide
-  resources.
+  secrets, recurring jobs, approvals, A2A orchestration, and the distribution
+  and approval of workspace-wide resources.
 
 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
 
@@ -327,8 +354,10 @@ Brain access instead of copying the same secret into a Brain-specific setting.
 
 Keep the ownership model simple:
 
-- Dispatch or the workspace layer owns provider account metadata, credential
-  ref names, and app grants.
+- 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.

package/docs/content/template-dispatch.md

@@ -7,7 +7,7 @@ description: "Dispatch is the workspace control plane — central inbox, cross-a
 
 > **See also:** for the conceptual overview of what Dispatch does and when you want it, see [Dispatch](/docs/dispatch). This page is the template-specific reference.
 
-Dispatch is the **workspace control plane**. Where other templates are domain apps (Mail, Calendar, Analytics), Dispatch is the app you run _alongside_ them to coordinate everything: a central inbox, a secrets vault, scheduled jobs, Slack/Telegram integration, and an orchestrator agent that delegates domain work to the right specialist app over [A2A](/docs/a2a-protocol).
+Dispatch is the **workspace control plane**. Where other templates are domain apps (Mail, Calendar, Analytics, Brain), Dispatch is the app you run _alongside_ them to coordinate everything: a central inbox, a secrets vault, scheduled jobs, Slack/Telegram integration, and an orchestrator agent that delegates domain work to the right specialist app over [A2A](/docs/a2a-protocol).
 
 <!-- screenshot:
   app: dispatch
@@ -27,7 +27,10 @@ If you're running an [multi-app workspace](/docs/multi-app-workspace) with many
 - **Orchestrator, not specialist.** Dispatch does _not_ try to be the email app or the analytics app. When someone asks "summarize last week's signups," Dispatch calls the analytics agent over A2A and returns the answer. When someone asks "draft a reply to Alice," Dispatch calls the mail agent.
 - **Secrets vault.** A central store for API keys, OAuth tokens, and shared credentials. Apps in the workspace resolve secrets from Dispatch instead of duplicating them in every `.env`. Requests + approvals for sensitive access.
 - **Workspace resources.** Global skills, guardrail instructions, custom agent profiles, and reference resources can be created once in Dispatch. All-app resources are inherited at runtime by every app with no copy or manual sync step; selected grants are for app-specific exceptions.
-- **Integrations catalog.** One page showing every third-party integration — Slack, Telegram, SendGrid, Apollo, etc. — with a "configured / not configured / pending approval" status per app.
+- **Reusable integrations.** One place to connect provider accounts, track
+  credential refs, and grant apps access. Dispatch owns provider identity and
+  app grants; domain apps still own app-specific source choices such as Brain's
+  Slack channel allow-list or Analytics' metric/dashboard configuration.
 - **Scheduled jobs hub.** Cross-app [recurring jobs](/docs/recurring-jobs) live here: "every weekday at 7, pull yesterday's key metrics from analytics and draft a morning summary email."
 - **Dreams.** Dispatch can review recent agent runs, failures, feedback, and successful patterns to propose memory, skill, job, and instruction improvements before anything durable is applied.
 - **Approval flow.** Destructive or external actions (sending money, shipping an outbound email, posting to Slack at scale) can require an admin OK before they fire. Dispatch owns the queue.
@@ -49,6 +52,10 @@ Day-to-day, Dispatch is the place admins and ops folks open to keep the workspac
 
 - **Connect Slack, email, and Telegram** so people can message your agent from wherever they already work. See [Messaging](/docs/messaging) for the wiring steps.
 - **Save shared secrets once.** API keys, OAuth tokens, and service credentials live in the vault and the other apps in your workspace pull from there instead of every team member juggling their own `.env`.
+- **Connect providers once.** Reusable integrations store safe account metadata
+  and credential references, then grant apps such as Brain, Analytics, Mail, or
+  Dispatch access without copying raw secrets. App-specific source
+  configuration stays in the app that uses the provider.
 - **Keep company context global.** Put personas, positioning, messaging, company facts, brand guidelines, and guardrails in Dispatch Resources once, then preview the effective workspace -> app/org -> personal stack for any app/user or inspect the stack from an app card's Context view.
 - **Set up recurring jobs.** "Every Monday at 7am, ask the analytics agent for last week's signups and email me a summary." See [Recurring Jobs](/docs/recurring-jobs).
 - **Review dream proposals.** Dispatch Dreams inspect prior agent runs and create source-backed proposals for what the workspace should remember, which stale notes should be cleaned up, and which repeated lessons should become skills or jobs.