@agent-native/core 0.26.9 → 0.28.0

package/docs/content/mcp-protocol.md

@@ -76,94 +76,17 @@ If an action declares `mcpApp`, the server also advertises the official MCP Apps
 
 ### MCP App embed bridge {#mcp-app-embed-bridge}
 
-`embedApp()` is the low-level URL-first MCP App helper. It reads the action
-result's open link, asks the app-only `create_embed_session` tool to mint a
-route-scoped session, then launches the resulting app route. Standard hosts
-hydrate the signed route by navigating the MCP App frame itself. Claude web
-uses a single-frame transplant path that fetches the signed app HTML and
-hydrates it inside Claude's MCP App iframe because Claude does not reliably
-allow app-owned child iframes or external frame navigation. ChatGPT web keeps
-the signed app URL in a controlled route iframe for stable `window.openai`
-host APIs and bounded height control.
-For normal action authoring, use `embedRoute()` when the action's
-`link` and `mcpApp` should come from the same pure route builder. The route
-itself should derive state from the URL and normal app data fetching.
-Same-app `open_app({ embed: true })` returns a server-minted `embedStartUrl`
-so the resource can launch without a second iframe-originated tool call. The
-server moves that ticket-bearing URL into hidden metadata and strips it from
-model-visible structured content and normal open-link metadata. Custom actions
-can return the same field when they already know the target route.
-
-The outer MCP resource reports a bounded inline height to the host and the app
-route scrolls internally. `embedApp({ height })` defaults to a `560px` shell,
-clamps to `320-900px`, and subtracts `44px` for the wrapper toolbar before
-sizing the route viewport. Do not rely on host auto-resize measuring the full
-document; in ChatGPT and Claude this can make a normal full-app route appear as
-a huge chat artifact. Host conversations also keep already-rendered iframes, so
-after changing the resource shell or `ui://` version, test a fresh tool call
-rather than re-measuring an old frame.
-
-If a user reopens an older chat after a one-time embed start ticket expires,
-the start route returns a small refresh page and posts
-`agentNative.embedSessionExpired` to the wrapper. `embedApp()` clears the stale
-start URL and asks the app-only `create_embed_session` tool for a fresh ticket
-when it still has the original app route.
-
-Default direct embeds talk to the MCP Apps host through standard `ui/*`
-JSON-RPC messages:
-
-| Type                      | Payload shape                      |
-| ------------------------- | ---------------------------------- |
-| `ui/update-model-context` | `{ content?, structuredContent? }` |
-| `ui/message`              | `{ role: "user", content }`        |
-| `ui/open-link`            | `{ url }`                          |
-| `ui/request-display-mode` | `{ mode }`                         |
-
-Claude's transplanted route uses the same `ui/*` bridge after hydration. Test
-Claude against deployed/preview URLs or a local production build served with
-`agent-native start`; raw Vite dev modules can be app-auth protected and fail
-dynamic imports from Claude's resource origin.
-
-The ChatGPT controlled-frame path and any explicit `embedMode: "iframe"` /
-`renderMode: "iframe"` diagnostic path use the wrapper-to-route postMessage
-relay:
-
-| Direction       | Type                                     | Payload shape                                 |
-| --------------- | ---------------------------------------- | --------------------------------------------- |
-| wrapper → route | `agentNative.mcpHostContext`             | `{ context, capabilities, version }`          |
-| route → wrapper | `agentNative.mcpHost.updateModelContext` | `{ requestId, content?, structuredContent? }` |
-| route → wrapper | `agentNative.mcpHost.openLink`           | `{ requestId, url }`                          |
-| route → wrapper | `agentNative.mcpHost.requestDisplayMode` | `{ requestId, mode }`                         |
-| wrapper → route | `agentNative.mcpHost.response`           | `{ requestId, ok, result?, error? }`          |
-
-`embedApp()` includes the MCP request origin in the resource CSP so the
-launcher can fetch and, when explicitly requested, frame the signed first-party
-route. Dispatch's `open_app` resource adds the exact origins for apps granted
-through Dispatch, which keeps the one-connector path narrow while still letting
-Claude/ChatGPT inline target app routes. Pass additional domains only for
-custom third-party frames or assets.
-
-Leave standard `_meta.ui.domain` unset by default. Its format is host-specific:
-Claude expects Claude content-domain hashes, while ChatGPT reads the separate
-`openai/widgetDomain` compatibility field. App URLs belong in CSP sources and
-open-link targets, not portable `ui.domain` metadata.
-
-Extension detail routes render their extension iframe from `srcDoc` when the
-route is already inside an MCP chat embed. That avoids a second
-`/_agent-native/extensions/:id/render` frame navigation being rejected by chat
-host ancestry checks, while keeping the same sandbox flags and postMessage
-extension bridge.
-
-Host-mediated open links keep the iframe from choosing its own browser target.
-Model context updates are opt-in and hidden from the user-facing transcript.
-`ui/message` is the portable way for an embedded app button to ask the host to
-post a visible user message and continue the chat. In agent-native routes,
-`sendToAgentChat()` uses `ui/update-model-context` plus `ui/message` when
-called from a submitted MCP App embed. Hidden context is sent through model
-context, while `ui/message` contains only the visible prompt. `submit: false`
-remains an in-route draft/prefill path.
-Display mode requests are best-effort: a host can honor, ignore, or reject the
-request. Embedded routes must remain functional in the default inline mode.
+`embedApp()` is the low-level URL-first MCP App helper: it launches a signed app
+route inline through transplant (Claude), controlled-frame (ChatGPT), or direct
+navigation, mediates host actions over the `ui/*` JSON-RPC bridge (and the
+`agentNative.mcpHost.*` postMessage relay for the controlled-frame path), and
+clamps the resource shell height so a full-app route does not render as an
+oversized chat artifact.
+
+See [External Agents](/docs/external-agents#mcp-app-bridge) for the full MCP App
+embed bridge and host-bridge details — transplant vs controlled-frame, the
+`ui/*` and postMessage tables, `create_embed_session` / `embedStartUrl`, CSP and
+domain rules, extension `srcDoc` embedding, and height clamping.
 
 ## Tools {#tools}
 

package/docs/content/messaging.md

@@ -294,7 +294,7 @@ The email adapter also enforces:
 
 ### Proactive sends {#proactive-sends}
 
-The agent can send messages on its own initiative (notifications, reminders, scheduled summaries) by calling the `send-platform-message` action with a `platform` field of `"slack"`, `"telegram"`, `"whatsapp"`, or `"email"`. The action lives in the Dispatch template at `actions/send-platform-message.ts` and you can copy/adapt it for any template.
+The agent can send messages on its own initiative (notifications, reminders, scheduled summaries) by calling the `send-platform-message` action with a `platform` field of `"slack"`, `"telegram"`, `"whatsapp"`, or `"email"`. The action lives in the Dispatch package at `packages/dispatch/src/actions/send-platform-message.ts` and you can copy/adapt it for any template.
 
 ### Custom adapters {#custom-adapters}
 

package/docs/content/migration-workbench.md

@@ -1,5 +1,5 @@
 ---
-title: "Agent-Native Code Workspace and /migrate"
+title: "Migration Workbench"
 description: "Use the open-source Agent-Native Code workspace for coding sessions, including the built-in /migrate capability."
 ---
 
@@ -18,11 +18,7 @@ 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.
+See [Agent-Native Code UI](/docs/code-agents-ui) for the shared CLI run controls (`list`/`attach`/`logs`/`resume`/`status`/`stop`/`ui`) and the file-backed, long-running background-run model that `/migrate` sessions use.
 
 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.
 
@@ -34,14 +30,8 @@ npx @agent-native/core@latest migrate ./my-next-app --out ../migrated-app
 
 Both forms print the same handoff: run id, source, output, dossier directory,
 important artifact files, and the exact Agent-Native Code commands to inspect or
-resume the session:
-
-```bash
-npx @agent-native/core@latest code attach --last
-npx @agent-native/core@latest code logs --last
-npx @agent-native/core@latest code resume --last
-npx @agent-native/core@latest code status --last
-```
+resume the session (see [Agent-Native Code UI](/docs/code-agents-ui) for the
+full run-control command set).
 
 ## Code Workspace
 
@@ -59,10 +49,7 @@ code> /migrate ./my-next-app --out ../migrated-app
 code> /audit --url https://example.com
 ```
 
-Agent-Native Code uses the same minimal coding tools as the sidebar development
-agent: `bash` for discovery/search/tests/builds, `read` for line-numbered file
-reads, `edit` for exact replacements, and `write` for new files or full
-rewrites.
+Agent-Native Code uses the same minimal coding-tool profile (`bash`, `read`, `edit`, `write`) and shared composer as the rest of the framework; see [Agent-Native Code UI](/docs/code-agents-ui) for details.
 
 The same goals can run directly from the command line:
 
@@ -83,50 +70,17 @@ Installed `agent-native` with no arguments launches the Agent-Native Code worksp
 
 ## Sessions and Modes
 
-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
-npx @agent-native/core@latest code attach --last
-npx @agent-native/core@latest code logs --last
-npx @agent-native/core@latest code approve --last
-npx @agent-native/core@latest code resume --last
-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                                                                                                 |
-| ------------- | -------- | -------------------------------------------------------------------------------------------------------- |
-| **Plan mode** | `--plan` | Inspect, plan, and explain without writing files or running mutations.                                   |
-| **Auto mode** | `--auto` | Edit files, run checks, and pause only for genuinely destructive file, git, publish, or data operations. |
-
-Auto mode is the default for local Agent-Native Code sessions. Use Plan mode for assessment, architecture, review, or any task where you want a proposal before edits.
+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 a `/migrate` run in one place and continue it in the other with the standard `list`/`attach`/`logs`/`resume`/`approve`/`stop` controls. See [Agent-Native Code UI](/docs/code-agents-ui) for those run controls, the mixed background-run source model, two-way follow-up semantics, and the Plan/Auto run modes that also govern `/migrate` sessions. Auto mode is the default; use Plan mode for migration assessment, architecture, or review where you want a proposal before edits.
 
 ## Project Slash Commands
 
-Built-in slash goals such as `/migrate` and `/audit` are framework commands. Projects can also define custom commands in `.agents/commands/*.md` using the same npx-first workflow:
+Built-in slash goals such as `/migrate` and `/audit` are framework commands. Projects can also define migration variants as custom commands in `.agents/commands/*.md` (see [Agent-Native Code UI](/docs/code-agents-ui) for how project commands and skills are discovered and inserted):
 
 ```bash
-npx @agent-native/core@latest code /release-check
 npx @agent-native/core@latest code /migrate-storefront ./legacy-shop --out ../agent-shop
 ```
 
-Each Markdown file names the command and contains the prompt/instructions the Agent-Native Code should run. This keeps team-specific workflows close to the repository: release checks, migration variants, framework upgrade playbooks, security audits, or customer-specific handoffs can be versioned without adding code. Source-specific systems such as AEM or Builder.io should stay as optional instruction-pack examples inside those commands, not top-level migration assumptions.
+Versioning migration variants this way keeps source-specific handoffs close to the repository. Source-specific systems such as AEM or Builder.io should stay as optional instruction-pack examples inside those commands, not top-level migration assumptions.
 
 ## Input Shapes
 
@@ -177,24 +131,7 @@ Inside that optional internal surface, the flow is:
 4. **Sweep** runs migration tasks against the generated output project.
 5. **Verify** runs deterministic checks and writes `04-report.md`.
 
-Useful CLI helpers:
-
-```bash
-npx @agent-native/core@latest code status --last
-npx @agent-native/core@latest code list
-npx @agent-native/core@latest code attach --last
-npx @agent-native/core@latest code logs --last
-npx @agent-native/core@latest code approve --last
-npx @agent-native/core@latest code resume --last
-npx @agent-native/core@latest code --continue "check the auth edge cases next"
-npx @agent-native/core@latest code resume --last "check the auth edge cases next"
-npx @agent-native/core@latest code ui --last
-npx @agent-native/core@latest code stop --last
-```
-
-`attach --last` follows a live transcript until the run reaches a terminal state, while `logs --last` prints the transcript once. `resume --last` reopens the latest run handoff. Passing a quoted prompt, or using `--continue "prompt"`, records it as a follow-up transcript event and immediately runs that follow-up against the same session context for executable coding sessions. `approve --last` is intentionally narrow: it only runs the pending approved command for a session that paused on a high-risk command, then tells you to resume.
-
-`stop` marks the run paused and sends SIGTERM when the run has a tracked Desktop/CLI runner process id. If the active work belongs to another terminal or external agent, stop that owner directly.
+Drive this surface with the standard run controls (`status`/`list`/`attach`/`logs`/`approve`/`resume`/`ui`/`stop`, plus `--continue "prompt"` to record and run a follow-up). See [Agent-Native Code UI](/docs/code-agents-ui) for what each control does and how stop/approve behave.
 
 ## Long-Running Goals
 
@@ -212,9 +149,11 @@ The `/migrate` goal reuses the same credentials system as agent-native. There is
 
 In Agent-Native Code, Desktop, or the internal run surface, connect providers through the normal settings and onboarding surfaces. For headless CLI use, existing provider environment variables are detected, including `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY`, and other provider env vars supported by the framework. Secret values are never copied into migration artifacts.
 
-## Agent-Native Code
+## Desktop Deep Links
+
+`/migrate` runs appear in the Desktop Agent-Native Code hub alongside any other Code session and use the same hub run controls and approval gate ([Agent-Native Code UI](/docs/code-agents-ui) covers the Desktop host and run controls). Browser/Desktop approval remains the trust gate for generated output writes.
 
-Agent-Native Desktop includes a **Agent-Native Code** hub for long-running coding-agent sessions. It is the general Code app/surface in Desktop, and it pairs with the `agent-native code` shell as the primary CLI/Desktop coding experience. A bare prompt is the generic coding session, and `/migrate` is one specialized capability there: the hub shows recent and active runs, opens a transcript-first session view with compact tool summaries and artifacts, sends follow-up prompts, stops tracked runners, opens a terminal in the run workspace, and handles links like:
+The hub handles a `/migrate` goal deep link:
 
 ```text
 agentnative://open?goal=migrate&run=<runId>
@@ -226,19 +165,6 @@ The legacy app-style deep link still works and opens the internal run detail sur
 agentnative://open?app=migration&run=<runId>
 ```
 
-The hub also includes `/audit`, a lightweight native goal backed by `agent-native audit-agent-web`, to keep the shell honest about more than one goal:
-
-```bash
-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

@@ -138,43 +138,7 @@ Because the shared package is a `workspace:*` dependency, pnpm symlinks it into
 
 Use `packages/shared` for code-level defaults that should ship with the repo: plugins, shared actions, shared React code, filesystem `AGENTS.md`, and filesystem skills. Use Dispatch workspace resources for runtime-editable global context that admins want to manage without a code change.
 
-Dispatch resources support two scopes:
-
-- **All apps** — global resources for every app in the workspace. Dispatch stores them once at workspace scope and every app agent inherits them at runtime; no copy or sync step is required.
-- **Selected apps** — resources granted per app for app-specific context or tools. Use these sparingly; most company, brand, persona, positioning, messaging, and guardrail context should be All apps.
-
-Canonical paths control behavior:
-
-| Runtime resource        | Path                                    | How agents use it                               |
-| ----------------------- | --------------------------------------- | ----------------------------------------------- |
-| Guardrail instructions  | `AGENTS.md` or `instructions/<slug>.md` | Loaded every turn in every app that receives it |
-| Global skills           | `skills/<slug>/SKILL.md`                | Listed as workspace skills and read on demand   |
-| Brand/company resources | `context/<slug>.md`                     | Indexed every turn, read when relevant          |
-| Custom agent profiles   | `agents/<slug>.md`                      | Available as reusable local agent profiles      |
-| Shared HTTP MCP servers | `mcp-servers/<slug>.json`               | Loaded into granted apps' MCP tool registry     |
-
-This is the right home for core personas, positioning, messaging, company facts, brand guidelines, support policies, shared skills, or shared HTTP MCP tools that many apps should benefit from.
-
-For a starter workspace, create these Dispatch resources and scope them to **All apps**:
-
-```text
-context/company.md              # company overview, ICP, products, canonical links
-context/brand.md                # brand voice, visual identity, spelling, terms to avoid
-context/messaging.md            # value props, product pillars, proof points, objections
-instructions/guardrails.md      # rules that must be loaded every turn
-skills/company-voice/SKILL.md   # copywriting and review workflow for brand voice
-```
-
-Example `skills/company-voice/SKILL.md`:
-
-```markdown
----
-name: company-voice
-description: Rewrite or review customer-facing copy using the workspace brand and messaging resources.
----
-
-Before writing, read `context/brand.md` and `context/messaging.md`. Keep claims grounded in those resources, preserve required terminology, and flag missing proof instead of inventing it.
-```
+Dispatch resources are scoped **All apps** (every app inherits them at runtime, no copy or sync step) or **Selected apps** (granted per app for app-specific context). The path — `AGENTS.md`/`instructions/<slug>.md`, `skills/<slug>/SKILL.md`, `context/<slug>.md`, `agents/<slug>.md`, `mcp-servers/<slug>.json` — determines how the agent uses each resource. See [Workspace](/docs/workspace#global-resources) for the full resource-model table and the recommended starter pack (`context/company.md`, `context/brand.md`, `context/messaging.md`, `instructions/guardrails.md`, `skills/company-voice/SKILL.md`).
 
 ## Authentication and RBAC {#auth-and-rbac}
 
@@ -293,7 +257,7 @@ The shared package itself is never deployed standalone. It's a `workspace:*` dep
 The workspace pattern is intentionally narrow. A few things it deliberately doesn't handle yet:
 
 - **Cross-domain SSO.** The unified `agent-native deploy` flow solves the common case (one origin, many apps at `/mail`, `/calendar`, …). If you need `mail.company.com` and `calendar.company.com` on _different_ domains to share a session, that requires a shared cookie domain or a central auth app with OAuth redirects — both supported by the underlying stack but neither scaffolded out of the box.
-- **Encrypted credential vault.** Shared credentials live in the `settings` table as plain text today. Rotate responsibly.
+- **Encrypted credential vault.** Prefer the Dispatch vault for runtime app credentials (see [Shared environment variables](#shared-env)). The non-vault fallback path — shared credentials written directly to the framework `settings` table — stores them as plain text today, so rotate responsibly when you rely on it.
 - **Publishing shared code to private npm.** The shared package is `workspace:*` only; multi-repo sharing via a private registry is doable but not scaffolded.
 - **Opinionated component library.** `packages/shared` is where _you_ put shared components. The framework doesn't force shadcn/ui or any other system into that slot.
 

package/docs/content/multi-tenancy.md

@@ -38,36 +38,13 @@ await auth.api.createInvitation({
 });
 ```
 
-The agent can also manage organizations through actions — `create-organization`, `invite-member`, `update-member-role`, and `remove-member` are available in every template.
+Org management is a **framework built-in**: the core org plugin auto-mounts REST routes under `/_agent-native/org/*` (create org, switch org, list/invite/remove members, change roles, set allowed email domain), and these back the org-switcher and members UI in every template with no extra code. Agent-callable actions with names like `create-organization` or `invite-member` are **template-authored** on top of this surface, not built-in tools — a template wires its own `defineAction` wrappers when it wants the agent to manage its specific membership model.
 
 ## Data scoping {#data-scoping}
 
-Every table that holds tenant-specific data includes an `organization_id` foreign key. The framework scopes queries automatically:
+Tenant data is isolated by an `org_id` column (added by `ownableColumns()`), and the framework scopes every query to the active org automatically — `session.orgId → AGENT_ORG_ID → SQL`. When a user switches organizations, the UI, actions, and agent all see only that org's data; the agent cannot reach data for an org the user isn't a member of.
 
-```
-session.orgId → AGENT_ORG_ID → SQL row scoping
-```
-
-When a user switches organizations, all queries, actions, and agent operations see only that org's data. This applies to both the UI and the agent — the agent cannot access data belonging to an organization the user isn't a member of.
-
-For full details on how scoping works at the SQL level, see [Security & Data Scoping](/docs/security).
-
-## Adding multi-tenancy to a new table {#new-tables}
-
-When you add a new domain table, use the framework's dialect-agnostic schema helpers and include ownership columns to make it tenant-aware:
-
-```typescript
-import { table, text, ownableColumns } from "@agent-native/core/db/schema";
-
-export const projects = table("projects", {
-  id: text("id").primaryKey(),
-  title: text("title").notNull(),
-  ...ownableColumns(),
-  // ... other columns
-});
-```
-
-Then scope your queries by the active org from the session. The framework's `accessFilter` helper and `assertAccess` guard handle this automatically when you follow the standard action patterns.
+This is the same pipeline used for per-user scoping. For the SQL-level mechanics, the `ownableColumns()` contract, and the `accessFilter` / `resolveAccess` / `assertAccess` guards, see [Security & Data Scoping](/docs/security#data-scoping).
 
 ## No configuration needed {#zero-config}
 

package/docs/content/onboarding.md

@@ -144,10 +144,17 @@ import { listWorkspaceConnectionProviderCatalogForApp } from "@agent-native/core
 // Inside registerOnboardingStep:
 isComplete: async () => {
   // Check if a managed workspace connection exists and is ready
-  const catalog = await listWorkspaceConnectionProviderCatalogForApp("gmail");
-  const connection = catalog.find((p) => p.providerId === "google-gmail");
+  const catalog = await listWorkspaceConnectionProviderCatalogForApp({
+    appId: "mail",
+    templateUse: "mail",
+    provider: "gmail",
+  });
+  const connection = catalog.providers[0];
 
-  if (connection?.status === "ready" && connection.granted) {
+  if (
+    connection?.readiness.status === "ready" &&
+    connection.workspaceConnection.grantState === "granted"
+  ) {
     return true;
   }
 

package/docs/content/recurring-jobs.md

@@ -57,7 +57,7 @@ Standard 5-field cron (minute, hour, day-of-month, month, day-of-week):
 | `0 17 * * 1-5` | Weekdays at 17:00        |
 | `0 0 1 * *`    | First day of every month |
 
-The framework exports `isValidCron()` and `describeCron()` from `@agent-native/core/jobs` if you want to validate or render cron strings in the UI.
+The framework includes cron utilities (`isValidCron()` and `describeCron()`) for validating and rendering cron strings, used internally by the resource and scheduler layers.
 
 ## Creating a job {#creating}
 
@@ -91,7 +91,7 @@ Summarize overnight emails.`,
 
 ## How the scheduler runs {#how-scheduler-runs}
 
-The scheduler is a framework plugin (`processRecurringJobs()` in `@agent-native/core/jobs`). On each tick it:
+The scheduler is a framework plugin (the internal `processRecurringJobs()` routine). On each tick it:
 
 1. Lists every enabled `jobs/*.md` resource across all owners.
 2. Compares `nextRun` to the current time.

package/docs/content/security.md

@@ -69,7 +69,17 @@ React auto-escapes all JSX expressions. Additional guidelines:
 
 ## Data Scoping {#data-scoping}
 
-In production, the framework automatically restricts agent SQL queries to the current user's data. This is enforced at the SQL level — agents cannot bypass it.
+In production, the framework automatically restricts agent SQL queries to the current user's data. This is enforced at the SQL level — agents cannot bypass it. This section is the canonical reference for the scoping pipeline; the [Authentication](/docs/authentication) and [Multi-Tenancy](/docs/multi-tenancy) docs link here for the mechanics.
+
+### The scoping pipeline {#scoping-pipeline}
+
+Scoping flows from the authenticated session down to the SQL the agent runs:
+
+```
+session.orgId → AGENT_ORG_ID → SQL row scoping
+```
+
+The signed-in session carries `email` and (when an org is active) `orgId`. The framework establishes request context from that session, exposes the active org to agent SQL as `AGENT_ORG_ID`, and rewrites every query so it can only see rows the current identity owns. The same path applies whether the query comes from the UI, an action, or the agent — the agent cannot read data for an org the user isn't a member of.
 
 ### Per-User Scoping (`owner_email`)
 
@@ -100,6 +110,28 @@ INSERT statements get `owner_email` auto-injected when the column isn't already
 
 For multi-user apps where teams share data, add an `org_id` column. When both columns are present, queries are scoped by both: `WHERE owner_email = ? AND org_id = ?`.
 
+The `ownableColumns()` schema helper adds both `owner_email` and `org_id` in one call, so new tenant-aware tables get the full scoping contract by default:
+
+```typescript
+import { table, text, ownableColumns } from "@agent-native/core/db/schema";
+
+export const projects = table("projects", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  ...ownableColumns(), // adds owner_email + org_id
+});
+```
+
+### Access guards in actions {#access-guards}
+
+Raw agent SQL is scoped by the temporary views above. Action code that queries with Drizzle directly should go through the framework's access helpers so reads and writes stay scoped to the current identity:
+
+- **`accessFilter`** — returns the `WHERE` predicate that limits a query to rows the current user/org may see. Use it in list/read queries.
+- **`resolveAccess`** — resolves the effective access scope (owner, org, shared) for the current request.
+- **`assertAccess`** — guards a write or single-record read, throwing if the current identity may not act on the target row.
+
+Tables built with `ownableColumns()` require these scoped reads and writes; custom Nitro routes must establish request context before querying ownable data. The `guard-no-unscoped-queries` check (run via `pnpm guards`) enforces this at CI time. See the `sharing` skill for the full helper API.
+
 ### Validation
 
 ```bash

package/docs/content/server.md

@@ -64,7 +64,7 @@ Actions mounted by the framework automatically run with request context. Custom
 import { defineEventHandler } from "h3";
 import { getSession, runWithRequestContext } from "@agent-native/core/server";
 import { getDb } from "@agent-native/core/db";
-import { accessFilter } from "@agent-native/core/access";
+import { accessFilter } from "@agent-native/core/sharing";
 import * as schema from "../../db/schema";
 
 export default defineEventHandler(async (event) => {

package/docs/content/template-assets.md

@@ -11,7 +11,7 @@ Use it when your team needs reusable visual direction and searchable source asse
 
 ![Assets library for brand media and generated output](https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F769092170a14474f998cbca47384f891?format=webp&width=1200)
 
-## Start Here
+## Getting started
 
 1. **Create a library.** Add the brand, campaign, product, or content stream you
    want to manage.
@@ -23,7 +23,7 @@ Use it when your team needs reusable visual direction and searchable source asse
 4. **Use the asset elsewhere.** Copy the export, embed the picker in another
    app, or let another agent call Assets over A2A.
 
-## Useful Prompts
+## Useful prompts
 
 - "Generate three blog hero options using the Acme product screenshots as references."
 - "Create a square social image in the launch-campaign style."
@@ -31,7 +31,7 @@ Use it when your team needs reusable visual direction and searchable source asse
 - "Turn this uploaded diagram into a cleaner product explainer image."
 - "Create a video storyboard and save the best frame set to this library."
 
-## What You Can Do With It
+## What you can do with it
 
 - **Create asset libraries.** Group reference images, videos, canonical logos, style notes, palettes, folders, and generated output by brand, campaign, product, or category.
 - **Generate through chat.** The home composer and library Generate controls send the prompt to the agent with `sendToAgentChat()`, so users can inspect variants, give feedback, and iterate.
@@ -43,13 +43,13 @@ Use it when your team needs reusable visual direction and searchable source asse
 - **Install as an app-backed skill.** The `agent-native.app-skill.json` manifest exports an Assets skill plus MCP connector metadata so marketplaces can install the app, its instructions, and its picker together.
 - **Serve other agents.** Slides, Design, Content, Mail, and Dispatch can call Assets through A2A to list libraries, generate batches, create videos, refine an asset, fetch exports, and render inline previews where embedding is allowed.
 
-## Why It's Interesting
+## Why it's interesting
 
 Most AI media tools treat brand consistency as a prompt-writing problem. Assets treats it as application state: references, folders, collections, style briefs, run history, descriptions, and saved assets live in SQL, while binary media lives in object storage or the local file-upload fallback during development.
 
 Because generation and library management are actions and chat workflows, the UI and the agent share the same operations. A user can start from the big prompt box, a library detail page, another app's chat, or an A2A request from Slides, and the same audit and lineage model is preserved. Once enabled, the provider path prefers Builder-managed image generation so teams do not need to paste model-provider keys into every app.
 
-## For Developers
+## For developers
 
 The rest of this doc is for anyone forking the Assets template or extending it.
 
@@ -59,7 +59,7 @@ The rest of this doc is for anyone forking the Assets template or extending it.
 pnpm dlx @agent-native/core create my-assets --template assets --standalone
 ```
 
-### Customize It
+### Customizing it
 
 Assets is a complete, cloneable template. Some practical extension ideas:
 
@@ -71,7 +71,7 @@ Assets is a complete, cloneable template. Some practical extension ideas:
 
 The agent edits routes, components, actions, skills, and SQL-backed models as needed. See [Templates](/docs/cloneable-saas) for the full clone, customize, deploy flow, and [A2A Protocol](/docs/a2a-protocol) for cross-app generation.
 
-### Embed The Picker
+### Embed the picker
 
 Use the picker route when a human is choosing or generating an asset inside
 another product. Image is the default media type; pass `mediaType=video` when
@@ -104,7 +104,7 @@ generation preset before choosing the final asset URL.
 Use A2A when another agent needs to create, search, or export assets without a
 human picker UI.
 
-### Developer: Distribute The App Skill
+### Developer: distribute the app skill
 
 The Assets app skill has app id `assets` and hosted MCP URL
 `https://assets.agent-native.com/_agent-native/mcp`.
@@ -151,7 +151,7 @@ hosted MCP connector so those instructions can call the live Assets app:
 npx @agent-native/core@latest app-skill ensure --manifest ./dist/assets-skill/agent-native.app-skill.json --yes
 ```
 
-## What's Next
+## What's next
 
 - [**Templates**](/docs/cloneable-saas) — the clone-and-own model
 - [**Embedding SDK**](/docs/embedding-sdk) — iframe picker and sidecar patterns