@agent-native/core 0.122.4 → 0.123.0

package/corpus/templates/brain/.agents/skills/sharing/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: sharing
+description: >-
+  Framework-level sharing and privacy for user-authored resources
+  (dashboards, documents, forms, decks, etc.). Use when making a resource
+  table ownable, wiring list/read/update access checks, or dropping the
+  standard share dialog into a template.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Sharing — Private by Default, Explicit Share
+
+## Rule
+
+Any resource a user **creates** (dashboards, documents, forms, decks, compositions, booking links, issues, analyses) is **private to the creator** by default and visible to others only when they have been **explicitly shared** with or when the creator changes visibility to `org` or `public`.
+
+This is the framework-level primitive. Every ownable resource gets it for free — same API, same UI, same skill.
+
+## Concepts
+
+### Three visibility levels
+
+- **`private`** — owner + explicit share grants only. Default.
+- **`org`** — owner + explicit grants + anyone in the same org (read-only).
+- **`public`** — owner + explicit grants + **anyone with the link** (read-only). Public docs do NOT appear in other users' list/sidebar/search results — `accessFilter` omits them by default. They're reachable by id (`resolveAccess` admits them) so direct links and SSR routes like `/p/:id` keep working. If a list endpoint legitimately needs cross-user public discovery (a template gallery, etc.), pass `accessFilter(table, shares, ctx, minRole, { includePublic: true })`.
+
+Visibility is coarse. Explicit share grants are fine-grained (per user or per org).
+
+### Roles on a share grant
+
+- **`viewer`** — read only.
+- **`editor`** — read + write.
+- **`admin`** — read + write + manage shares. Does NOT replace the single `owner_email` on the resource.
+
+### Anonymous public URLs stay separate
+
+Form "publish" slugs, booking-link slugs, any feature that exposes a URL to unauthenticated users — these are a different axis and are NOT controlled by the sharing system. Keep them alongside it.
+
+## Make a resource ownable
+
+In your template's `server/db/schema.ts`:
+
+```ts
+import {
+  table,
+  text,
+  integer,
+  now,
+  ownableColumns,
+  createSharesTable,
+} from "@agent-native/core/db/schema";
+
+export const decks = table("decks", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  data: text("data").notNull(),
+  createdAt: text("created_at").notNull().default(now()),
+  updatedAt: text("updated_at").notNull().default(now()),
+  ...ownableColumns(), // adds owner_email, org_id, visibility
+});
+
+export const deckShares = createSharesTable("deck_shares");
+```
+
+Then register it **in `server/db/index.ts`** (not the schema file — keeps the schema file free of the `getDb` closure and avoids circular imports):
+
+```ts
+// server/db/index.ts
+import * as schema from "./schema.js";
+import { createGetDb } from "@agent-native/core/db";
+import { registerShareableResource } from "@agent-native/core/sharing";
+
+export const getDb = createGetDb(schema);
+export { schema };
+
+registerShareableResource({
+  type: "deck",
+  resourceTable: schema.decks,
+  sharesTable: schema.deckShares,
+  displayName: "Deck",
+  titleColumn: "title",
+  getResourcePath: (deck) => `/deck/${deck.id}`,
+  getDb,
+});
+```
+
+The `type` string is the stable id the UI and actions use. `getDb` is required — the framework-level share actions use it to reach your template's DB.
+
+### Restricting public visibility and cross-org user shares
+
+Some resources should NOT be reachable by an arbitrary authenticated user even with the link, and should NOT be shareable to an email outside the org. Two optional registration flags lock these axes down:
+
+```ts
+registerShareableResource({
+  type: "extension",
+  // ...
+  allowPublic: false, // hides "Public" in the share dialog and rejects it server-side
+  requireOrgMemberForUserShares: true, // user shares must target an org member or pending invitee
+});
+```
+
+- **`allowPublic: false`** — `set-resource-visibility('public')` throws `ForbiddenError`, `accessFilter` / `resolveAccess` treat any stored `'public'` row as private (defense in depth against bad data), and the share popover hides the "Public" option. `list-resource-shares` returns `policy.allowPublic: false` so the UI follows the server.
+- **`requireOrgMemberForUserShares: true`** — `share-resource` looks up `principalId` in `org_members` and `org_invitations` (pending) for the resource's `orgId` and rejects user shares to anyone else. The same flag also pins `principalType: "org"` shares to the resource's own org — sharing to a *different* org would let that org's members run code in the viewer's auth context (same threat model as a public extension). (The flag name is kept for backward compatibility; treat it as "lock both user and org shares to the resource's org".)
+
+Use both for resources that execute code or expose privileged data with the *viewer's* credentials. Extensions ship with both set: an extension's HTML calls actions / SQL / the secrets-injecting proxy as the viewer, so a public or cross-org-shared extension would let a stranger run arbitrary code with someone else's auth context. `scripts/guard-extension-no-public.mjs` (CI + `pnpm prep`) statically enforces that the extension registration keeps both flags set.
+
+Defaults match historical behaviour: `allowPublic: true`, `requireOrgMemberForUserShares: false`. Resources that don't set the flags work as before.
+
+## Filter list/read queries
+
+```ts
+import { accessFilter } from "@agent-native/core/sharing";
+
+const rows = await db
+  .select()
+  .from(schema.decks)
+  .where(accessFilter(schema.decks, schema.deckShares));
+```
+
+`accessFilter` admits rows the current user owns, has been shared on, or that the user can reach via `org` visibility. `public` rows are NOT admitted by default — see the visibility section above for why and how to opt in.
+
+## Guard write actions
+
+```ts
+import { assertAccess } from "@agent-native/core/sharing";
+
+export default defineAction({
+  schema: z.object({ id: z.string(), title: z.string() }),
+  run: async (args) => {
+    await assertAccess("deck", args.id, "editor");
+    // ...proceed
+  },
+});
+```
+
+For delete actions use `"admin"` (or fold in `"owner"` to require the real owner).
+
+## Create actions must set owner
+
+When inserting a new row, fill `ownerEmail` and `orgId` from the request context:
+
+```ts
+import {
+  getRequestUserEmail,
+  getRequestOrgId,
+} from "@agent-native/core/server/request-context";
+
+const ownerEmail = getRequestUserEmail();
+// Never fall back to a sentinel like "local@localhost" — that pools every
+// unauthenticated write into one shared tenant (see the 2026-04-29 leak and
+// guard-no-localhost-fallback). Throw / 401 when there is no session instead.
+if (!ownerEmail) throw new Error("Not authenticated");
+
+await db.insert(schema.decks).values({
+  id: nanoid(),
+  title,
+  data,
+  ownerEmail,
+  orgId: getRequestOrgId(),
+  // visibility defaults to 'private'
+  // ...
+});
+```
+
+## Drop in the share UI
+
+```tsx
+import { ShareButton } from "@agent-native/core/client/sharing";
+
+// In the resource's header/toolbar:
+<ShareButton
+  resourceType="deck"
+  resourceId={deck.id}
+  resourceTitle={deck.title}
+/>;
+```
+
+For list views, show `<VisibilityBadge visibility={row.visibility} />` next to each resource.
+
+## Actions available everywhere
+
+The framework auto-mounts these actions in every template — no per-template boilerplate:
+
+| Action                     | Args                                                                           | Purpose                                   |
+| -------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------- |
+| `share-resource`           | `resourceType, resourceId, principalType, principalId, role, notify?, resourceUrl?` | Grant a user or org access. `notify` defaults to true for individual user shares; `resourceUrl` can provide the direct app link used in the notification email. |
+| `unshare-resource`         | `resourceType, resourceId, principalType, principalId`                         | Revoke access.                            |
+| `list-resource-shares`     | `resourceType, resourceId`                                                     | Current visibility + all share grants.    |
+| `set-resource-visibility`  | `resourceType, resourceId, visibility`                                         | Change to `private` / `org` / `public`.  |
+
+Both the agent and the UI use these same actions. The agent calls them as tools;
+UI code should use `ShareButton` / `ShareDialog` or the action client hooks
+instead of hand-writing route calls.
+
+## Migration pattern for existing tables
+
+When retrofitting an existing resource table:
+
+1. Add `owner_email`, `org_id`, `visibility` columns (defaults `'local@localhost'`, `NULL`, `'private'`).
+2. Backfill `owner_email` from any prior creator trail; otherwise leave the default.
+3. Add the companion `{type}_shares` table.
+4. Register via `registerShareableResource`.
+5. Update list/read actions to use `accessFilter`.
+6. Update update/delete actions to `assertAccess` with the correct role.
+7. Add `<ShareButton>` to the resource header.
+8. Add `getResourcePath` in the registration so agent-triggered shares can email a direct link even when no UI supplied `resourceUrl`.
+
+## Templates that opt out
+
+Sharing doesn't apply to:
+
+- **Personal-data apps** (mail, macros) — user-scoped by design.
+- **External source-of-truth apps** (issues → Jira, recruiting → Greenhouse) — ACL lives in the upstream system.
+- **Demo/boilerplate** (starter) — no resources.
+
+For these, add a short note to the template's `AGENTS.md` explaining why.
+
+## Analytics (follow-up)
+
+Dashboards and analyses in the `analytics` template currently live in the settings KV store (`u:<email>:dashboard-*` keys), not SQL. Sharing requires either migrating them to SQL tables (then applying this skill) or extending the settings store with a parallel share overlay. This is a tracked follow-up — see the analytics template's `AGENTS.md`.
+
+## Debugging
+
+- `ForbiddenError` from an action means the current user isn't owner / hasn't been shared / can't meet the role bar.
+- If the agent can't see a resource it just created, check that the insert actually set `owner_email` from the request context.
+- If a share doesn't take effect in the UI, confirm the template's `list-*` action uses `accessFilter` — the share rows are there but nothing is reading them yet.

package/corpus/templates/brain/.agents/skills/storing-data/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: storing-data
+description: >-
+  How to store application data in agent-native apps. All data lives in SQL.
+  Use when adding data models, deciding where to store data, or reading/writing
+  application data.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Storing Data — SQL is the Source of Truth
+
+## Rule
+
+All application data lives in **SQL** (SQLite locally, persistent database in production). The agent and UI share the same database. SQL stores structured records, metadata, references, and searchable text — not large raw file payloads. Do not store durable app data in the filesystem unless the app is explicitly running a Local File Mode artifact flow described below.
+
+Large binary or file-like payloads (images, video/audio, PDFs, ZIPs, screenshots, session replay chunks, thumbnails, generated assets, `data:` URLs, and base64 file bodies) must go through configured file/blob storage such as `uploadFile()` or `putPrivateBlob()`. Persist only the returned URL, asset id, or opaque blob handle in SQL. If storage is unavailable in hosted or persistent-database mode, fail closed with setup guidance instead of falling back to base64 in `application_state`, `settings`, `resources`, or app tables. Local SQLite-only dev fallbacks may exist for tiny assets, but they must be capped, documented as dev-only, and kept off hot list/read paths.
+
+**Local File Mode exception:** some artifact apps (Content, Plans, Slides, Dashboards, Designs, etc.) can intentionally use repo files as the source of truth for the artifact itself. This must be explicit via `agent-native.json`, `AGENT_NATIVE_MODE=local-files`, or an app-owned local-file action helper. In that mode, the UI and agent still go through app actions, but those actions read/write scoped files through `@agent-native/core/local-artifacts` instead of SQL rows. App state, auth, settings, credentials, collaboration metadata, and hosted database mode remain SQL. File-to-database or file-to-provider synchronization is an explicit sync step, not an implicit side effect of editing.
+
+When you add a data model, a list, or a read path, also follow the `performance` skill: project only the columns a list renders, index the columns hot queries filter/sort on, and avoid query waterfalls — so apps stay fast as data grows.
+
+## How It Works
+
+Agent-native apps use Drizzle ORM over the configured SQL backend. Local development works out of the box with a SQLite file at `data/app.db`; production and shared preview deploys need a persistent `DATABASE_URL` because container/serverless filesystems can reset. The code should behave the same across backends, but the local SQLite file is not durable once deployed.
+
+For app code, use Drizzle's schema/query DSL by default. Raw SQL is an escape hatch for additive migrations, health checks, or one-off maintenance, not the normal way to build features.
+
+### Naming migrations
+
+When you add an entry to a `runMigrations([...])` list (`@agent-native/core/db`), always give it a unique `name:` slug (e.g. `name: "analytics-alert-rules-table"`) alongside its `version`. Never renumber or reuse version numbers on existing entries.
+
+Why: version numbers alone are not a safe identity. Two branches that each independently extend the same migration list can ship different DDL under the same version numbers — whichever branch deploys first "claims" those version numbers in the bookkeeping table, and the other branch's DDL is silently treated as already applied even though it never ran. This exact collision took down analytics: parallel branches both extended their migration list through v75-v83 with different DDL, so `analytics_alert_rules`, `analytics_alert_incidents`, and `session_recordings.network_error_count` never made it to production despite the bookkeeping table showing every version as applied. A `name:` slug is tracked independently of version numbers, so it applies exactly once per database regardless of what any other branch already recorded.
+
+Existing unnamed migrations don't need to be renamed retroactively (the two gating strategies coexist), but any new entry should always carry a name.
+
+### Core SQL Stores (auto-created, available in all templates)
+
+| Store               | Purpose                                              | Access                                     |
+| ------------------- | ---------------------------------------------------- | ------------------------------------------ |
+| `application_state` | Ephemeral UI state (compose windows, navigation)     | `readAppState()` / `writeAppState()`       |
+| `settings`          | Persistent KV config (preferences, app settings)     | `getSetting()` / `putSetting()`            |
+| `oauth_tokens`      | OAuth credentials                                    | `@agent-native/core/oauth-tokens`          |
+| `sessions`          | Auth sessions                                        | `@agent-native/core/server`               |
+
+### Domain Data (per-template)
+
+Define schema with the framework Drizzle helpers in `server/db/schema.ts`. Get a database instance with `const db = getDb()` from `server/db/index.ts`. All queries are async.
+
+```ts
+import { eq } from "drizzle-orm";
+import { table, text, integer, now } from "@agent-native/core/db/schema";
+
+export const tasks = table("tasks", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  completed: integer("completed", { mode: "boolean" })
+    .notNull()
+    .default(false),
+  createdAt: text("created_at").notNull().default(now()),
+});
+
+const rows = await db.select().from(tasks).where(eq(tasks.id, taskId));
+```
+
+Never import `sqliteTable` / `pgTable` or column helpers from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` in app templates. Use `@agent-native/core/db/schema` so the same schema can run against SQLite, Postgres, libSQL/Turso, D1, and other supported backends.
+
+| Template     | Tables                                        |
+| ------------ | --------------------------------------------- |
+| **Mail**     | emails, labels (+ Gmail API when connected)   |
+| **Calendar** | events, bookings                              |
+| **Forms**    | forms, responses                              |
+| **Content**  | documents                                     |
+| **Slides**   | decks (JSON stored in SQL)                    |
+| **Videos**   | compositions in registry + localStorage       |
+
+### Agent Access
+
+The agent uses app-specific actions to read/write the database. Core DB scripts are for inspection and maintenance, not for implementing normal product behavior:
+
+- `pnpm action db-schema` — Show all tables, columns, types
+- `pnpm action db-query --sql "SELECT * FROM forms"` — Run SELECT queries
+- `pnpm action db-exec --sql "UPDATE ..."` — Last-resort ad-hoc maintenance for short columns, multi-column writes, or computed updates when no domain action exists. For several related writes, prefer `--statements '[{"sql":"...","args":[...]}]'` so they run sequentially in one transaction. Schema changes are blocked; use reviewed additive migrations/startup code instead.
+- `pnpm action db-patch --table <t> --column <c> --where "<clause>" --find "<old>" --replace "<new>"` — **Surgical search/replace on a large text column.** Sends the diff instead of re-transmitting the whole value, so it's dramatically more token-efficient than `db-exec UPDATE` when editing multi-kilobyte documents, slide HTML, dashboard/form JSON, etc. Targets exactly one row per call — narrow `--where` by primary key. Supports `--edits '[{find,replace},...]'` for batch edits and `--all` to replace every occurrence.
+- App-specific actions for domain operations — **always prefer these over raw SQL when one exists.** They encode business rules, power the client action hooks, and for editor-backed tables (documents, slides) also push live Yjs updates to open collaborative editors. `db-patch` is the generic fallback for tables without a dedicated edit action.
+
+**For one-off maintenance, how to choose between `db-exec UPDATE` and `db-patch`:**
+
+| Scenario                                                       | Use          |
+| -------------------------------------------------------------- | ------------ |
+| `SET status = 'published'` on one row                          | `db-exec`    |
+| `SET calories = calories + 50`                                 | `db-exec`    |
+| Updating several columns at once                               | `db-exec`    |
+| Inserting/updating several rows as one logical operation        | `db-exec --statements` |
+| Fixing a typo in a 50KB markdown document's `content` column   | `db-patch`   |
+| Changing a single key in a dashboard's JSON blob               | `db-patch`   |
+| Tweaking one paragraph of slide HTML stored in `decks.data`    | `db-patch`   |
+| Any edit where you'd otherwise re-send thousands of characters | `db-patch`   |
+
+All of these honor the per-user / per-org data scoping — you can't read or write rows outside the current user's data, regardless of which tool you choose.
+
+### Frontend Access
+
+The frontend calls actions using React Query hooks from the client API. The framework owns the HTTP transport behind these hooks, so components should not call action routes with raw `fetch`.
+
+```ts
+import { useActionQuery, useActionMutation } from "@agent-native/core/client/hooks";
+
+// Read data
+const { data } = useActionQuery("list-meals", { date: "2025-01-01" });
+
+// Write data
+const { mutate } = useActionMutation("log-meal");
+```
+
+Actions are the **preferred way** for the frontend to access data. You rarely need custom `/api/` routes — only for file uploads, streaming, webhooks, or OAuth callbacks.
+
+### Production / Cloud Deployment
+
+Local SQLite works out of the box for development. To deploy to production or any environment where data must survive restarts:
+
+1. Set `DATABASE_URL` to a persistent SQL database.
+2. Set `DATABASE_AUTH_TOKEN` only when the provider requires a separate token, such as Turso/libSQL.
+3. No code changes should be needed when the schema and queries stay portable.
+
+Turso is one valid option, not the required option. Common choices include Neon or Supabase Postgres, Turso/libSQL, plain Postgres, durable SQLite, Cloudflare D1 bindings, and managed platform SQL environments when available.
+
+### Real-time Sync
+
+Polling streams database changes to the UI. When the agent writes to the database via scripts, the UI updates automatically via `useDbSync()` which invalidates React Query caches.
+
+## Do
+
+- Use Drizzle ORM for structured domain data (forms, bookings, documents)
+- Use Drizzle query builder methods (`select`, `insert`, `update`, `delete`) and portable operators from `drizzle-orm` (`eq`, `and`, `or`, `inArray`, `desc`, etc.) for app reads/writes
+- Use framework schema helpers from `@agent-native/core/db/schema`, not dialect-specific Drizzle imports
+- Use the `settings` store for app configuration and user preferences
+- Use `application-state` for ephemeral UI state that the agent and UI share
+- Use `oauth-tokens` for OAuth credentials
+- Use `uploadFile()` or `putPrivateBlob()` for large files/blob data and store only URLs, ids, or handles in SQL
+- Use core DB scripts (`db-schema`, `db-query`, `db-exec`, `db-patch`) for ad-hoc database operations
+- Use `db-exec --statements` instead of several separate `db-exec` calls for related writes; it is faster and rolls back the whole batch if one statement fails
+- Reach for `db-patch` instead of `db-exec UPDATE` whenever you're making a small change to a large text/JSON column — it's much cheaper on tokens
+
+## Don't
+
+- Don't store structured app data as JSON files
+- Don't store app state in localStorage, sessionStorage, or cookies (except for UI-only preferences like sidebar width)
+- Don't keep state only in memory (server variables, global stores)
+- Don't use Redis or any external state store for app data
+- Don't store large files, base64 blobs, `data:` URLs, screenshots, videos, audio, PDFs, ZIPs, or session replay chunks directly in SQL rows, `application_state`, `settings`, or `resources`
+- Don't implement product features with raw SQL or `getDbExec()` when Drizzle can express the query
+- Don't write SQLite-only or Postgres-only SQL in app code
+- Don't interpolate user input directly into SQL queries — use Drizzle ORM's query builder
+
+## Security
+
+- **SQL injection** — Use Drizzle ORM's query builder, never raw string interpolation for SQL queries
+- **Validate before writing** — Check data shape before writing, especially for user-submitted data
+
+## Application State and Context Awareness
+
+When storing app-state, include **navigation state** — the agent needs to know what the user is looking at. The `application_state` table holds ephemeral UI state that both the agent and UI share. Key patterns:
+
+- **`navigation` key** — the UI writes current view and selection on every route change. The agent reads this before acting.
+- **`navigate` key** — the agent writes one-shot commands to navigate the UI. The UI processes and deletes them.
+- **Domain-specific keys** (e.g., `compose-{id}`) — bidirectional state for features like email drafts.
+
+When adding a new data model or feature, also consider what navigation and selection state needs to be exposed via application-state. See the **context-awareness** skill for the full pattern.
+
+## Related Skills
+
+- **context-awareness** — How to expose navigation and selection state via application-state
+- **real-time-sync** — Set up polling so the UI updates when the database changes
+- **actions** — Create actions with `defineAction` to query the database
+- **client-methods** — Keep route details behind named client helpers/hooks
+- **self-modifying-code** — The agent can also modify the app's source code

package/corpus/templates/brain/AGENTS.md

@@ -1,84 +1,70 @@
 # Brain — Agent Guide
 
-Brain is an agent-native workspace knowledge system. The agent ingests sources,
-distills memories, answers across connected knowledge, cites evidence, and
-captures durable learnings through actions and shared state.
+Brain is an agent-native workspace knowledge system: ingest sources, distill
+memories, answer with cited evidence, and capture durable learnings through
+actions and shared state.
 
-Detailed retrieval, capture, connector, and feature rules live in
-`.agents/skills/`.
+## Skills
 
 Before building common workspace or agent UI, read `agent-native-toolkit` to
 inventory existing public kits and installed package seams. Use
 `customizing-agent-native` for the configure → compose → eject → propose seam
 ladder.
 
+Read the matching skill before deeper work:
+
+- `brain` — ingestion, distillation, retrieval, and review flows, the
+  `sourcePolicy` table, publish-tier/proposal gating, evidence quotes, capture
+  sanitization, and the full per-action reference.
+- `ask-across-everything` — cross-source answers and `federatedCoverage`
+  delegation.
+- `ingestion-and-connectors` — source lifecycle, providers, health states,
+  credential resolution, and raw provider HTTP.
+- `brain/RUNBOOK.md` — Brain internals and ops (search layers, distillation
+  worker, scheduled sync, Slack rollout, demo/eval, ingest payloads); read it
+  only when operating or debugging internals. It is a file inside the `brain`
+  skill, not its own skill slug.
+- `agent-native-toolkit` — check existing kits and package seams before
+  building workspace or agent UI.
+- `customizing-agent-native` — the configure → compose → eject → propose seam
+  ladder.
+- `adding-a-feature` — Brain feature changes.
+- `actions`, `real-time-sync`, `security`, `frontend-design`, and `shadcn-ui`
+  for framework work; `actions` covers the shared provider API pattern.
+
 ## Core Rules
 
-- Store large file/blob payloads in configured file/blob storage, not SQL: no
-  base64, `data:` URLs, images, video/audio, PDFs, ZIPs, screenshots,
-  thumbnails, or replay chunks in app tables, `application_state`, `settings`,
-  or `resources`; persist URLs, ids, or handles instead.
-- Never hardcode API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
+- Never put large payloads in SQL — no base64, `data:` URLs, images,
+  video/audio, PDFs, ZIPs, screenshots, thumbnails, or replay chunks in app
+  tables, `application_state`, `settings`, or `resources`. Use configured
+  file/blob storage and persist URLs, ids, or handles instead.
+- Never hardcode API keys, tokens, webhook URLs, signing secrets, private
+  Builder/internal data, customer data, or credential-looking literals. Use
+  secrets/OAuth/runtime configuration and obvious placeholders in examples.
 - Use Brain actions for ingestion, search, retrieval, distillation, capture,
   review, and connector work. Do not bypass access checks or ownable scopes.
 - **Call `get-brain-settings` before answering, searching broadly, or
-  distilling** if settings aren't already in context. The returned guidance
-  encodes every retrieval and distillation rule below as concrete policy —
-  read `brain` for how `sourcePolicy` and publish-tier gating actually work.
-- Retrieval answers must be evidence-backed. Cite or summarize source context and
-  clearly separate facts from inference.
+  distilling** if it isn't already in context; it encodes the retrieval and
+  distillation rules as concrete policy (see `brain`).
+- Retrieval answers must be evidence-backed. Cite or summarize source context
+  and clearly separate facts from inference.
 - Do not fabricate source contents, dates, people, permissions, or connector
   health. Inspect sources when unsure.
-- Capture only durable, useful knowledge. Avoid storing secrets, transient noise,
-  or unsupported personal data.
-- Use `view-screen` when the active source, review item, search, or collection is
-  unclear.
-- For connector work, use existing workspace integration grants when available;
-  do not duplicate provider tokens into Brain. `list-connection-providers`
-  shows readiness (`connected`, `granted`, `needs_grant`, `not_connected`) per
-  provider before you ask the user for another credential.
-- Source sync actions are convenience readers, not integration limits. For ad
-  hoc provider analysis or questions that need an endpoint/filter/payload the
-  source actions do not model, call `provider-api-catalog` /
-  `provider-api-docs`, then `provider-api-request` against the provider's real
-  HTTP API. Use `connectionId` for a specific shared grant and `accountId` for a
-  specific OAuth account.
-- Sources support exactly five providers: `manual`, `generic`, `clips`,
-  `slack`, `granola`, `github` (`sourceProviderSchema` in `actions/_schemas.ts`).
-  `create-source` rejects anything else.
-- **Evidence quotes must be exact substrings.** `write-knowledge` calls
-  `validateEvidence`, which throws if `evidence[].quote` is not found verbatim
-  in the referenced capture's content. Copy the quote from `get-capture`
-  output — do not paraphrase, trim mid-sentence in a way that changes the
-  substring, or reconstruct it from memory.
-- `review-proposal` and `approve-proposal`/`reject-proposal` overlap:
-  `review-proposal` is the general one (`decision`: `approve` | `reject` |
-  `needs_changes`); `approve-proposal` and `reject-proposal` are narrower
-  single-purpose actions with the same underlying effect. Any of them is
-  correct; don't call more than one for the same proposal.
-
-## Action Map
-
-| Action                                                                                            | Purpose                                                                                                 |
-| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| `get-brain-settings`                                                                              | Identity, tone, `sourcePolicy`, citation, and distillation settings — read first.                       |
-| `search-everything`                                                                               | Broad search across knowledge + captures + sources, plus `federatedCoverage`.                           |
-| `search-knowledge`                                                                                | SQL text search over distilled knowledge only.                                                          |
-| `ask-brain`                                                                                       | Cited-answer endpoint: reviewed knowledge, capped raw-capture fallback, citations, `federatedCoverage`. |
-| `get-knowledge` / `list-knowledge`                                                                | Read one or list distilled knowledge records.                                                           |
-| `get-capture` / `list-captures`                                                                   | Read one or list raw captures (redacted by default; `includeRawContent` for exact quotes).              |
-| `import-capture` / `import-transcript`                                                            | Ingest a generic capture or a meeting transcript; auto-creates a `manual` source.                       |
-| `enqueue-distillation` / `mark-capture-distilled`                                                 | Queue a capture for distillation; close out the queue row when done.                                    |
-| `write-knowledge`                                                                                 | Write/update durable knowledge; may return a pending proposal — see Publish Tiers below.                |
-| `review-proposal` / `approve-proposal` / `reject-proposal` / `list-proposals` / `update-proposal` | Human-review workflow for gated writes.                                                                 |
-| `set-knowledge-canonical`                                                                         | Mirror/unmirror approved knowledge into `context/company-brain/...` workspace resources.                |
-| `create-source` / `update-source` / `delete-source` / `list-sources` / `get-source`               | Source lifecycle across the five providers.                                                             |
-| `sync-source` / `sync-due-sources`                                                                | Run one connector now, or sweep all due sources.                                                        |
-| `get-brain-health`                                                                                | Setup/source health, sync freshness, queue and proposal counts, next steps.                             |
-| `list-connection-providers`                                                                       | Per-provider workspace-connection readiness and credential health.                                      |
-| `test-slack-connection` / `run-slack-pilot`                                                       | Slack credential/channel validation and bounded first-sync report.                                      |
-| `provider-api-catalog` / `provider-api-docs` / `provider-api-request`                             | Raw provider HTTP calls beyond the source actions.                                                      |
-| `run-demo-eval` / `run-retrieval-eval` / `seed-demo-data`                                         | Demo corpus and offline eval checks (see `brain-runbook`).                                              |
+- Capture only durable, useful knowledge. Avoid storing secrets, transient
+  noise, or unsupported personal data.
+- Use `view-screen` when the active source, review item, search, or collection
+  is unclear.
+- Evidence quotes must be exact substrings of the referenced capture; copy them
+  from `get-capture` output.
+- Sources support exactly six providers: `manual`, `generic`, `clips`, `slack`,
+  `granola`, `github`. `create-source` rejects anything else.
+- Reuse existing workspace integration grants (check `list-connection-providers`
+  readiness) instead of duplicating provider tokens into Brain. Source sync
+  actions are convenience readers, not integration limits — for an endpoint,
+  filter, or payload they do not model, use `provider-api-catalog` /
+  `provider-api-docs` / `provider-api-request`.
+- If `write-knowledge` returns `mode: "proposal"`, leave it in review unless the
+  user explicitly asks to approve it now.
 
 ## Application State
 
@@ -89,59 +75,27 @@ ladder.
   `extensions`, `ops`, or `settings`, with matching `sourceId` / `captureId` /
   `knowledgeId` / `proposalId` / `extensionId` / `query` / `provider` /
   `status` / `issue` params.
-- Use retrieval actions for full source context instead of ambient screen text.
-
-## Retrieval Policy Is Configurable — Read It, Don't Assume
-
-`sourcePolicy` (in Brain settings) changes what `ask-brain` and
-`search-everything` are allowed to answer from, and it is enforced in code,
-not just documented:
-
-| `sourcePolicy`       | `rawCaptureFallback` | Behavior                                                                                                                                                                      |
-| -------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `strict`             | `never-answer`       | Reviewed knowledge only. If knowledge is missing/thin, say so — never fall back to raw captures as answer support.                                                            |
-| `balanced` (default) | `thin-results`       | Prefer reviewed knowledge; fall back to raw captures only when knowledge is missing or combined summary+body text is under ~260 chars, and label them as raw capture matches. |
-| `exploratory`        | `allowed-leads`      | Always include accessible raw captures/sources alongside knowledge, clearly labeled as unreviewed leads.                                                                      |
+- Use retrieval actions for full source context, not ambient screen text.
 
-`requireCitations` (default true) additionally blocks `ask-brain` from
-returning an answer with no usable citation — it returns a policy-explanation
-message instead of a bare summary when that happens.
-
-## Publish Tiers And Proposal Gating
-
-`write-knowledge` writes at a `publishTier`: `private` (draft, private
-visibility), `team`, or `company` (published, org visibility) — default comes
-from `settings.defaultPublishTier`. A `company`-tier write becomes a
-**proposal** (`mode: "proposal"`, held for human review) instead of publishing
-immediately when ALL of:
-
-- `proposalMode !== "never"`, and
-- `tier === "company"`, and
-- `settings.requireApprovalForCompanyKnowledge` is true, and
-- it is NOT a high-confidence auto-publish (`confidence >= 90` AND it's a new
-  record, no `knowledgeId` AND nothing was redacted).
-
-Setting `proposalMode: "always"` forces a proposal regardless of tier/settings;
-`proposalMode: "never"` only works when the caller also has bypass access
-(e.g. `approve-proposal`/`review-proposal` set it internally). If
-`write-knowledge` returns `mode: "proposal"`, leave it in review unless the
-user explicitly asks to approve it now.
-
-## Skills
-
-Read the relevant skill before deeper work:
+## Action Map
 
-- `brain` for core ingestion, distillation, retrieval, and review flows —
-  including exact publish-tier/proposal mechanics and capture sanitization.
-- `ask-across-everything` for cross-source answers and `federatedCoverage`
-  delegation.
-- `ingestion-and-connectors` for source lifecycle, health states, Slack
-  backfill rollout, and provider credential resolution order.
-- `brain/RUNBOOK.md` (the `brain-runbook` skill) for internal architecture,
-  ops, and rollout detail: search layers, distillation worker internals,
-  scheduled sync, demo/eval internals, and generic ingest payloads. Read it
-  only when operating or debugging Brain internals.
-- `adding-a-feature` for Brain feature changes.
-- `actions`, `real-time-sync`, `security`, `frontend-design`, and `shadcn-ui`
-  for framework work. The `actions` skill includes the shared provider API
-  pattern for flexible integrations.
+| Action | Purpose |
+| --- | --- |
+| `get-brain-settings` | Identity, tone, `sourcePolicy`, citation, distillation settings. |
+| `search-everything` | Broad search over knowledge, captures, sources + `federatedCoverage`. |
+| `search-knowledge` | Text search over distilled knowledge only. |
+| `ask-brain` | Cited-answer endpoint with `federatedCoverage`. |
+| `get-knowledge` / `list-knowledge` | Read or list distilled knowledge. |
+| `get-capture` / `list-captures` | Read or list raw captures (redacted by default). |
+| `import-capture` / `import-transcript` | Ingest a capture or meeting transcript. |
+| `enqueue-distillation` / `mark-capture-distilled` | Queue distillation; close the queue row. |
+| `write-knowledge` | Write/update knowledge; may return a pending proposal. |
+| `review-proposal` / `approve-proposal` / `reject-proposal` / `list-proposals` / `update-proposal` | Human review of gated writes. |
+| `set-knowledge-canonical` | Mirror approved knowledge into workspace resources. |
+| `create-source` / `update-source` / `delete-source` / `list-sources` / `get-source` | Source lifecycle. |
+| `sync-source` / `sync-due-sources` | Run one connector, or sweep all due sources. |
+| `get-brain-health` | Source health, sync freshness, queue/proposal counts. |
+| `list-connection-providers` | Provider readiness and credential health. |
+| `test-slack-connection` / `run-slack-pilot` | Slack validation and first-sync report. |
+| `provider-api-catalog` / `provider-api-docs` / `provider-api-request` | Raw provider HTTP. |
+| `run-demo-eval` / `run-retrieval-eval` / `seed-demo-data` | Demo corpus and eval checks. |

package/corpus/templates/brain/app/entry.client.tsx

@@ -1,7 +1,10 @@
 import { appBasePath } from "@agent-native/core/client/api-path";
+import { installRouteChunkRecovery } from "@agent-native/core/client/route-chunk-recovery";
 import { hydrateRoot } from "react-dom/client";
 import { HydratedRouter } from "react-router/dom";
 
+installRouteChunkRecovery();
+
 const basePath = appBasePath();
 const pathname = window.location.pathname;
 const routerBasePath =