@agent-native/core 0.122.3 → 0.123.0

package/docs/content/organizations-teams-permissions.mdx

@@ -54,20 +54,25 @@ organization plugin. The built-in flow supports:
 The framework mounts the server surface under `/_agent-native/org/*`. The main
 routes are:
 
-| Route                                            | Purpose                                                      |
-| ------------------------------------------------ | ------------------------------------------------------------ |
-| `GET /_agent-native/org/me`                      | Active org, memberships, pending invites, and domain matches |
-| `POST /_agent-native/org`                        | Create an organization                                       |
-| `PATCH /_agent-native/org`                       | Rename the active organization                               |
-| `PUT /_agent-native/org/switch`                  | Switch the active organization                               |
-| `GET /_agent-native/org/members`                 | List members in the active organization                      |
-| `DELETE /_agent-native/org/members/:email`       | Remove a member                                              |
-| `PUT /_agent-native/org/members/:email/role`     | Change a member's role                                       |
-| `POST /_agent-native/org/invitations`            | Invite one or more people                                    |
-| `POST /_agent-native/org/invitations/:id/accept` | Accept an invitation                                         |
-| `POST /_agent-native/org/join-by-domain`         | Join an organization matched by email domain                 |
-| `PUT /_agent-native/org/domain`                  | Set or clear the allowed email domain                        |
-| `PUT /_agent-native/org/a2a-secret`              | Set or regenerate the active org's A2A secret                |
+| Route                                            | Purpose                                                         |
+| ------------------------------------------------ | --------------------------------------------------------------- |
+| `GET /_agent-native/org/me`                      | Active org, memberships, pending invites, and domain matches    |
+| `POST /_agent-native/org`                        | Create an organization                                          |
+| `PATCH /_agent-native/org`                       | Rename the active organization                                  |
+| `DELETE /_agent-native/org`                      | Delete the organization (owner only)                            |
+| `PUT /_agent-native/org/switch`                  | Switch the active organization                                  |
+| `GET /_agent-native/org/members`                 | List members in the active organization                         |
+| `DELETE /_agent-native/org/members/:email`       | Remove a member                                                 |
+| `PUT /_agent-native/org/members/:email/role`     | Change a member's role                                          |
+| `GET /_agent-native/org/invitations`             | List pending invites                                            |
+| `POST /_agent-native/org/invitations`            | Invite one or more people                                       |
+| `POST /_agent-native/org/invitations/:id/accept` | Accept an invitation                                            |
+| `POST /_agent-native/org/join-by-domain`         | Join an organization matched by email domain                    |
+| `PUT /_agent-native/org/domain`                  | Set or clear the allowed email domain                           |
+| `GET /_agent-native/org/a2a-secret`              | Reveal the active org's A2A secret (owner/admin, on demand)     |
+| `PUT /_agent-native/org/a2a-secret`              | Set or regenerate the active org's A2A secret                   |
+| `POST /_agent-native/org/a2a-secret/sync`        | Push the org's A2A secret to every connected app (owner/admin)  |
+| `POST /_agent-native/org/a2a-secret/receive`     | Accept a peer app's secret push (JWT-authenticated, no session) |
 
 Use the shared UI and hooks instead of recreating this flow in each app:
 
@@ -181,38 +186,10 @@ Shareable resources use three layers together:
 `admin` on a resource does not transfer ownership. The resource owner remains
 separate from every share grant.
 
-For new tenant-aware tables, use `ownableColumns()` and the access helpers:
-
-```ts
-import { table, text, ownableColumns } from "@agent-native/core/db/schema";
-import { accessFilter, assertAccess } from "@agent-native/core/sharing";
-
-export const projects = table("projects", {
-  id: text("id").primaryKey(),
-  name: text("name").notNull(),
-  ...ownableColumns(), // owner_email + org_id + visibility
-});
-
-const visibleProjects = await db
-  .select()
-  .from(projects)
-  .where(accessFilter(projects, projectShares));
-
-await assertAccess("project", projectId, "editor");
-```
-
-Use these helpers consistently:
-
-- `accessFilter(table, sharesTable)` for list/read queries.
-- `resolveAccess(resourceType, resourceId)` when the action needs to inspect
-  the effective access role.
-- `assertAccess(resourceType, resourceId, minRole)` at the top of a write or
-  single-record action.
-
-The framework's SQL agent tools are scoped as well, but direct Drizzle queries
-in actions and custom routes still need the access helpers. Run
-`pnpm action db-check-scoping` and `pnpm guards` while developing to catch
-missing ownership or unscoped query paths.
+For the `ownableColumns()` schema helper, the `accessFilter` / `resolveAccess` /
+`assertAccess` helper API, and the CI guard that enforces scoped queries, see
+[Security → Data Scoping](/docs/security#data-scoping) — the single source of
+truth for the scoping pipeline every resource role above rides on.
 
 ## Environment variables: what belongs where
 
@@ -254,74 +231,69 @@ when it came from a private `.env` file.
 There is no single useful list of every environment variable in an app: each
 template and provider adds its own integration settings. The table below is the
 framework-level set developers most often need. Feature-specific variables stay
-on the page for the feature that owns them.
+on the page for the feature that owns them, and
+[Deployment → Environment Variables](/docs/deployment#environment-variables) is
+the canonical production checklist (build/runtime vars, required secrets such as
+`ANTHROPIC_API_KEY` and `A2A_SECRET`, and production code execution) — the
+tables below don't repeat what's already covered there.
 
 ### Database and public URL
 
-| Variable                                                  | What it does                                                                                                                      |
-| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `APP_NAME`                                                | Names the current app and enables prefixed lookups such as `MAIL_DATABASE_URL` when the app name is `mail`.                       |
-| `DATABASE_URL`                                            | Persistent SQL connection. Unset uses local SQLite; `pglite:./data/pglite` opts into local Postgres semantics.                    |
-| `DATABASE_AUTH_TOKEN`                                     | Separate auth token for providers such as Turso/libSQL.                                                                           |
-| `<APP_NAME>_DATABASE_URL`                                 | Per-app database override in a multi-app workspace; it wins over `DATABASE_URL` and `NETLIFY_DATABASE_URL`.                       |
-| `<APP_NAME>_DATABASE_AUTH_TOKEN`                          | Per-app auth-token override; it wins over `DATABASE_AUTH_TOKEN` and `NETLIFY_DATABASE_AUTH_TOKEN`.                                |
-| `NETLIFY_DATABASE_URL`                                    | Netlify-managed database fallback when no app-prefixed or generic `DATABASE_URL` is set.                                          |
-| `NETLIFY_DATABASE_AUTH_TOKEN`                             | Netlify-managed database auth-token fallback.                                                                                     |
-| `<APP_NAME>_DATABASE_URL_UNPOOLED`                        | Per-app direct connection used for migrations where the provider exposes a pooled and unpooled endpoint.                          |
-| `DATABASE_URL_UNPOOLED` / `NETLIFY_DATABASE_URL_UNPOOLED` | Generic or Netlify direct migration connection fallback. The app-prefixed value wins when present.                                |
-| `ALLOW_DRIZZLE_PUSH_ON_NEON`                              | Set to `1` only for an intentional local schema push against Neon. Do not set it in CI or production.                             |
-| `APP_URL`                                                 | Canonical app/workspace origin used for generated links and callbacks.                                                            |
-| `WORKSPACE_OAUTH_ORIGIN` / `VITE_WORKSPACE_OAUTH_ORIGIN`  | Workspace OAuth origin, used when the workspace gateway and app origin differ.                                                    |
-| `BETTER_AUTH_URL` / `VITE_BETTER_AUTH_URL`                | Explicit public auth origin for session and OAuth URL construction; `APP_URL` and request/platform origins can provide fallbacks. |
-| `WEBHOOK_BASE_URL`                                        | Optional callback origin when webhook self-callbacks should use a stable custom domain instead of the deploy preview URL.         |
-| `URL` / `DEPLOY_URL` / `DEPLOY_PRIME_URL`                 | Platform-provided public URL fallbacks, especially for Netlify previews and deploys.                                              |
-| `VERCEL_PROJECT_PRODUCTION_URL` / `VERCEL_URL`            | Vercel's production and deployment-hostname fallbacks.                                                                            |
-| `PORT`                                                    | Node server port.                                                                                                                 |
-| `APP_BASE_PATH` / `VITE_APP_BASE_PATH`                    | Mounts an app under a path such as `/mail`; the `VITE_*` form preserves that path in browser code.                                |
-| `NITRO_PRESET`                                            | Selects the deployment/build target, such as `netlify`, `vercel`, or `cloudflare_pages`.                                          |
+| Variable                                                  | What it does                                                                                                              |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `APP_NAME`                                                | Names the current app and enables prefixed lookups such as `MAIL_DATABASE_URL` when the app name is `mail`.               |
+| `DATABASE_URL`                                            | Persistent SQL connection. Unset uses local SQLite; `pglite:./data/pglite` opts into local Postgres semantics.            |
+| `DATABASE_AUTH_TOKEN`                                     | Separate auth token for providers such as Turso/libSQL.                                                                   |
+| `<APP_NAME>_DATABASE_URL`                                 | Per-app database override in a multi-app workspace; it wins over `DATABASE_URL` and `NETLIFY_DATABASE_URL`.               |
+| `<APP_NAME>_DATABASE_AUTH_TOKEN`                          | Per-app auth-token override; it wins over `DATABASE_AUTH_TOKEN` and `NETLIFY_DATABASE_AUTH_TOKEN`.                        |
+| `NETLIFY_DATABASE_URL`                                    | Netlify-managed database fallback when no app-prefixed or generic `DATABASE_URL` is set.                                  |
+| `NETLIFY_DATABASE_AUTH_TOKEN`                             | Netlify-managed database auth-token fallback.                                                                             |
+| `<APP_NAME>_DATABASE_URL_UNPOOLED`                        | Per-app direct connection used for migrations where the provider exposes a pooled and unpooled endpoint.                  |
+| `DATABASE_URL_UNPOOLED` / `NETLIFY_DATABASE_URL_UNPOOLED` | Generic or Netlify direct migration connection fallback. The app-prefixed value wins when present.                        |
+| `ALLOW_DRIZZLE_PUSH_ON_NEON`                              | Set to `1` only for an intentional local schema push against Neon. Do not set it in CI or production.                     |
+| `WORKSPACE_OAUTH_ORIGIN` / `VITE_WORKSPACE_OAUTH_ORIGIN`  | Workspace OAuth origin, used when the workspace gateway and app origin differ.                                            |
+| `WEBHOOK_BASE_URL`                                        | Optional callback origin when webhook self-callbacks should use a stable custom domain instead of the deploy preview URL. |
+| `URL` / `DEPLOY_URL` / `DEPLOY_PRIME_URL`                 | Platform-provided public URL fallbacks, especially for Netlify previews and deploys.                                      |
+| `VERCEL_PROJECT_PRODUCTION_URL` / `VERCEL_URL`            | Vercel's production and deployment-hostname fallbacks.                                                                    |
+
+`APP_URL`, `BETTER_AUTH_URL` / `VITE_BETTER_AUTH_URL`, `PORT`,
+`APP_BASE_PATH` / `VITE_APP_BASE_PATH`, and `NITRO_PRESET` are documented in
+[Deployment → Environment Variables](/docs/deployment#environment-variables).
 
 ### Authentication, cookies, and org defaults
 
-| Variable                                | What it does                                                                                                |
-| --------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| `BETTER_AUTH_SECRET`                    | Production session-signing secret and fallback key material. Generate a fresh 32+ character value.          |
-| `OAUTH_STATE_SECRET`                    | Dedicated HMAC key for OAuth state envelopes; falls back to `BETTER_AUTH_SECRET` when unset.                |
-| `SECRETS_ENCRYPTION_KEY`                | AES-256-GCM key for encrypted credentials and vault rows; falls back to `BETTER_AUTH_SECRET`.               |
-| `AUTH_DISABLED`                         | Local/demo escape hatch that makes every request one shared user. Never use it with real production users.  |
-| `AUTH_SKIP_EMAIL_VERIFICATION`          | Set to `1` for QA/preview signup without email verification.                                                |
-| `AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT` | Set to `1` to disable localhost's automatic throwaway account.                                              |
-| `AUTH_MODE`                             | Controls CLI/agent identity resolution such as `pnpm action`; it is not a browser login bypass.             |
-| `COOKIE_DOMAIN`                         | Shares cookies across same-database subdomains when explicitly configured.                                  |
-| `AGENT_NATIVE_SHARE_COOKIE_DOMAIN`      | Set to `1` with `COOKIE_DOMAIN` when intentionally sharing one auth database across first-party subdomains. |
-| `AGENT_NATIVE_WORKSPACE`                | Enables the shared workspace session realm for a multi-app workspace.                                       |
-| `VITE_AGENT_NATIVE_WORKSPACE`           | Build-time/browser equivalent of `AGENT_NATIVE_WORKSPACE`.                                                  |
-| `AUTO_CREATE_DEFAULT_ORG`               | Defaults to enabled; set to `0` to stop creating a personal organization for users with no membership.      |
-
-### OAuth providers
-
-| Variable                                                    | What it does                                                                               |
-| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| `GOOGLE_SIGN_IN_CLIENT_ID` / `GOOGLE_SIGN_IN_CLIENT_SECRET` | Preferred low-scope Google OAuth client for signing users in.                              |
-| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET`                 | Google OAuth fallback and client credentials for Google API integrations such as Calendar. |
-| `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET`                 | Enable GitHub sign-in.                                                                     |
-| `GOOGLE_AUTH_MODE`                                          | Chooses Google sign-in UX: `auto`, `popup`, or `redirect`; defaults to `auto`.             |
+Signing-key, cookie, and social-login variables (`BETTER_AUTH_SECRET`,
+`OAUTH_STATE_SECRET`, `AUTH_DISABLED`, `AUTH_SKIP_EMAIL_VERIFICATION`,
+`COOKIE_DOMAIN`, `GOOGLE_CLIENT_ID` / `GITHUB_CLIENT_ID`, and the rest) are
+documented once in [Authentication → Environment Variables](/docs/authentication#environment-variables);
+the secrets-encryption-key fallback chain is in
+[Security → Secrets Management](/docs/security#secrets). The variables below are
+org/workspace-specific and aren't covered on either of those pages:
+
+| Variable                      | What it does                                                                                           |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `AGENT_NATIVE_WORKSPACE`      | Enables the shared workspace session realm for a multi-app workspace.                                  |
+| `VITE_AGENT_NATIVE_WORKSPACE` | Build-time/browser equivalent of `AGENT_NATIVE_WORKSPACE`.                                             |
+| `AUTO_CREATE_DEFAULT_ORG`     | Defaults to enabled; set to `0` to stop creating a personal organization for users with no membership. |
+| `GOOGLE_AUTH_MODE`            | Chooses Google sign-in UX: `auto`, `popup`, or `redirect`; defaults to `auto`.                         |
 
 ### Agent providers and runtime
 
-| Variable                       | What it does                                                                                             |
-| ------------------------------ | -------------------------------------------------------------------------------------------------------- |
-| `AGENT_ENGINE`                 | Explicitly selects the agent engine, for example a built-in provider or `codex-cli`.                     |
-| `AGENT_ENGINE_PREFER_BYO_KEY`  | Set to `true` to prefer a user's stored provider key over the managed Builder engine.                    |
-| `ANTHROPIC_API_KEY`            | Deploy-level Anthropic fallback for the agent. In multi-tenant hosted apps, prefer per-user credentials. |
-| `OPENAI_API_KEY`               | Deploy-level OpenAI provider key.                                                                        |
-| `GOOGLE_GENERATIVE_AI_API_KEY` | Deploy-level Google Gemini provider key.                                                                 |
-| `OPENROUTER_API_KEY`           | Deploy-level OpenRouter provider key.                                                                    |
-| `GROQ_API_KEY`                 | Deploy-level Groq provider key.                                                                          |
-| `MISTRAL_API_KEY`              | Deploy-level Mistral provider key.                                                                       |
-| `COHERE_API_KEY`               | Deploy-level Cohere provider key.                                                                        |
-| `AGENT_MAX_ITERATIONS`         | Default maximum agent loop iterations; app settings can override it where supported.                     |
-| `AGENT_MAX_OUTPUT_TOKENS`      | Default output-token limit for the agent.                                                                |
-| `AGENT_PROD_CODE_EXECUTION`    | Production code execution mode: `off`, `sandboxed`, or `trusted`. The default is `off`.                  |
+| Variable                       | What it does                                                                          |
+| ------------------------------ | ------------------------------------------------------------------------------------- |
+| `AGENT_ENGINE`                 | Explicitly selects the agent engine, for example a built-in provider or `codex-cli`.  |
+| `AGENT_ENGINE_PREFER_BYO_KEY`  | Set to `true` to prefer a user's stored provider key over the managed Builder engine. |
+| `OPENAI_API_KEY`               | Deploy-level OpenAI provider key.                                                     |
+| `GOOGLE_GENERATIVE_AI_API_KEY` | Deploy-level Google Gemini provider key.                                              |
+| `OPENROUTER_API_KEY`           | Deploy-level OpenRouter provider key.                                                 |
+| `GROQ_API_KEY`                 | Deploy-level Groq provider key.                                                       |
+| `MISTRAL_API_KEY`              | Deploy-level Mistral provider key.                                                    |
+| `COHERE_API_KEY`               | Deploy-level Cohere provider key.                                                     |
+| `AGENT_MAX_ITERATIONS`         | Default maximum agent loop iterations; app settings can override it where supported.  |
+| `AGENT_MAX_OUTPUT_TOKENS`      | Default output-token limit for the agent.                                             |
+
+`ANTHROPIC_API_KEY` and `AGENT_PROD_CODE_EXECUTION` are documented in
+[Deployment → Environment Variables](/docs/deployment#environment-variables).
 
 ### Optional framework integrations
 
@@ -335,15 +307,14 @@ can take precedence over the deploy environment.
 | `GITHUB_TOKEN`                                                                  | Workspace-level GitHub API fallback for repository and PR operations.                                                                           |
 | `RESEND_API_KEY`                                                                | Enables Resend email delivery.                                                                                                                  |
 | `SENDGRID_API_KEY` / `EMAIL_FROM`                                               | Enables SendGrid email delivery and supplies its sender address. Production email requires Resend or SendGrid; SendGrid also requires a sender. |
-| `SENTRY_SERVER_DSN` / `SENTRY_CLIENT_DSN` / `SENTRY_DSN`                        | Optional Sentry error reporting for Nitro, browser, or both. No DSN means that surface is disabled.                                             |
-| `VITE_SENTRY_CLIENT_DSN`                                                        | Build-time browser Sentry DSN; runtime `SENTRY_CLIENT_DSN` or shared `SENTRY_DSN` can also configure SSR apps.                                  |
-| `SENTRY_ENVIRONMENT` / `SENTRY_SERVER_TRACES_SAMPLE_RATE`                       | Label Sentry events and opt into server performance traces (`0`–`1`; default `0`).                                                              |
-| `POSTHOG_API_KEY` / `POSTHOG_HOST`                                              | Configure PostHog tracking and its optional host.                                                                                               |
-| `MIXPANEL_TOKEN` / `AMPLITUDE_API_KEY`                                          | Configure Mixpanel or Amplitude tracking.                                                                                                       |
-| `AGENT_NATIVE_ANALYTICS_PUBLIC_KEY` / `VITE_AGENT_NATIVE_ANALYTICS_PUBLIC_KEY`  | Public write key for first-party analytics ingestion; the `VITE_*` form is for browser builds.                                                  |
-| `AGENT_NATIVE_ANALYTICS_ENDPOINT` / `VITE_AGENT_NATIVE_ANALYTICS_ENDPOINT`      | Override the first-party analytics ingestion endpoint for server or browser events.                                                             |
-| `TRACKING_WEBHOOK_URL` / `TRACKING_WEBHOOK_AUTH`                                | Send tracking events to a webhook and optionally provide its `Authorization` header value.                                                      |
-| `AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS`                                        | Set to `1` only for local development while configuring webhook signing secrets. Never set it in production.                                    |
+
+Product-analytics variables (PostHog, Mixpanel, Amplitude, the tracking
+webhook, and the first-party analytics keys) are documented once in
+[Tracking → Built-in providers](/docs/tracking#built-in). Sentry
+error-reporting variables are in
+[Observability → Error Reporting](/docs/observability#sentry).
+`AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS` is in
+[Security → Inbound Webhooks](/docs/security#webhooks).
 
 Template-specific variables belong with the template that owns the feature and
 its `.env.example` or feature docs. Start with [Messaging](/docs/messaging),
@@ -353,16 +324,20 @@ map.
 
 ### MCP, A2A, and CLI identity
 
-| Variable                     | What it does                                                                                                                |
-| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `A2A_SECRET`                 | Shared signing secret for production cross-app A2A and queued integration dispatch. Use the same value across sibling apps. |
-| `ACCESS_TOKEN`               | One static bearer fallback for MCP clients that cannot use OAuth. It is not browser authentication.                         |
-| `ACCESS_TOKENS`              | Comma-separated static bearer fallbacks for MCP clients.                                                                    |
-| `MCP_OAUTH_ACCESS_TOKEN_TTL` | Lifetime for MCP OAuth access tokens; defaults to `30d`.                                                                    |
-| `AGENT_USER_EMAIL`           | CLI-only user identity fallback when no request context exists. It does not impersonate browser requests.                   |
-| `AGENT_USER_NAME`            | CLI-only display-name fallback.                                                                                             |
-| `AGENT_ORG_ID`               | CLI-only active-org fallback when no request context exists. It does not override a browser session.                        |
-| `AGENT_USER_TIMEZONE`        | CLI/agent timezone fallback.                                                                                                |
+`A2A_SECRET` and the static MCP bearer fallbacks (`ACCESS_TOKEN` /
+`ACCESS_TOKENS`) are documented in
+[Authentication → Environment Variables](/docs/authentication#environment-variables)
+and [Security → A2A Identity Verification](/docs/security#a2a-identity). The
+variables below are CLI/agent-identity fallbacks specific to running outside a
+browser session:
+
+| Variable                     | What it does                                                                                              |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `MCP_OAUTH_ACCESS_TOKEN_TTL` | Lifetime for MCP OAuth access tokens; defaults to `30d`.                                                  |
+| `AGENT_USER_EMAIL`           | CLI-only user identity fallback when no request context exists. It does not impersonate browser requests. |
+| `AGENT_USER_NAME`            | CLI-only display-name fallback.                                                                           |
+| `AGENT_ORG_ID`               | CLI-only active-org fallback when no request context exists. It does not override a browser session.      |
+| `AGENT_USER_TIMEZONE`        | CLI/agent timezone fallback.                                                                              |
 
 `A2A_SECRET` is deployment-wide signing material. The organization-level
 `organizations.a2a_secret` is a separate, UI-managed secret used when an org

package/docs/content/package-lifecycle.mdx

@@ -116,15 +116,27 @@ move is rewritten only when the installed destination package exports its target
 
 ## Whole-package ejection
 
-`@agent-native/scheduling` is the first package with the generic manifest. Add
-creates action re-export stubs, adds the schema export, copies its agent skills,
-records the dependency, and reports required secret names and providers.
-Eject copies the published Scheduling source to `packages/scheduling`, switches
-the dependency to `workspace:*`, and preserves canonical
-`@agent-native/scheduling` imports so workspace resolution selects the local
-copy.
+`@agent-native/scheduling` and `@agent-native/creative-context` both ship the
+generic manifest. Add creates action re-export stubs, adds the schema export,
+copies the package's agent skills, records the dependency, and reports
+required secret names and providers. Eject copies the published package source
+to `packages/scheduling` (or `packages/creative-context`), switches the
+dependency to `workspace:*`, and preserves the canonical package import
+specifier so workspace resolution selects the local copy.
 
 Whole-package ejection and feature ejection solve different ownership needs.
 Use `agent-native package eject` when the complete domain package should become
 a workspace package. Use `agent-native eject <unit>` when the package should
 keep supplying upgrades for everything except one app-owned feature.
+
+## What's next
+
+- [**Toolkit Capability Modules**](/docs/toolkit-capability-packages) — the
+  Scheduling, Creative Context, and Pinpoint packages these commands manage.
+- [**Toolkit overview**](/docs/agent-native-toolkit#customize-or-eject) — the
+  broader `agent-native eject` unit catalog for components and integrations
+  beyond whole packages.
+- [**Doctor**](/docs/doctor) — `doctor --only migration-manifest` and the
+  framework's other CI guard checks.
+- [**Syncing Template Changes**](/docs/syncing-template-changes) — the mirror-image
+  command: pulling upstream template fixes in, instead of ejecting a package out.

package/docs/content/progress.mdx

@@ -191,6 +191,17 @@ export function HeaderBar() {
 
 Inline header widget — mount it next to the notifications bell. Shows a spinner icon + count badge when runs are active; click opens a dropdown with one live percent bar per run. Hides the trigger entirely when no active runs. Polls `/_agent-native/runs?active=true` every `pollMs` (default 3 s). Uses shadcn semantic tokens, adapts to light and dark themes.
 
+<WireframeBlock id="doc-block-progresswf1">
+  <Screen
+    surface="popover"
+    html={
+      "<div style='display:flex;flex-direction:column;min-height:220px;box-sizing:border-box'><div style='display:flex;align-items:center;justify-content:flex-end;gap:8px;padding:10px 14px;border-bottom:1.4px solid var(--wf-line)'><span class='wf-pill accent'>&#9696; 2</span></div><div style='display:flex;flex-direction:column;gap:10px;padding:14px 16px'><div class='wf-card' style='display:flex;flex-direction:column;gap:6px'><strong>Triage 128 unread emails</strong><span class='wf-muted'>Classifying 84/128</span><div style='height:6px;border-radius:4px;background:var(--wf-line);overflow:hidden'><div style='width:66%;height:100%;background:hsl(var(--primary))'></div></div></div><div class='wf-card' style='display:flex;flex-direction:column;gap:6px'><strong>Ingest 1M rows</strong><span class='wf-muted'>Writing to target DB</span><div style='height:6px;border-radius:4px;background:var(--wf-line);overflow:hidden'><div style='width:40%;height:100%;background:hsl(var(--primary))'></div></div></div></div></div>"
+    }
+  />
+</WireframeBlock>
+
+The badge in the header is the collapsed trigger; clicking it opens the dropdown shown here, with one row per active run — a title, the current `step` text, and a percent bar.
+
 ## Agent tool {#agent-tool}
 
 A single `manage-progress` tool is registered in every template. The `action` parameter selects the operation:

package/docs/content/real-time-collaboration.mdx

@@ -5,6 +5,12 @@ description: "Multi-user collaborative editing where the AI agent is a first-cla
 
 # Real-Time Collaboration
 
+<Callout tone="info">
+
+**Developer page.** This page is for developers wiring collaborative editing and presence. For the end-user experience of co-editing with the agent, see [Using Your Agent](/docs/using-your-agent).
+
+</Callout>
+
 Imagine opening a document and seeing a peer's cursor scroll to a paragraph,
 then the text rewrite itself — surgically, without losing your place. That
 peer might be a teammate. It might be the agent. From the framework's
@@ -326,7 +332,7 @@ User identity is derived from the session email. The framework provides `emailTo
 Templates can add a comments system with threaded discussions on documents. The content template's comments system includes a full implementation with:
 
 - `document_comments` SQL table (threads, replies, resolved status)
-- Comment create and list run through the `add-comment` / `list-comments` actions; the content template also exposes REST routes for update/delete at `/api/comments/:id`. Custom templates can implement their own equivalent endpoints, and comment anchors resolve against the document body through the core `POST /_agent-native/collab/:docId/search-replace` route.
+- Comment create, list, update, and delete all run through the `add-comment` / `list-comments` / `update-comment` / `delete-comment` actions. Comment anchors are resolved entirely in the browser by fuzzy-matching the stored quote text (plus prefix/suffix context) against the live editor document — no server round-trip.
 - Comments sidebar with threaded view and reply UI
 - Resolve/unresolve threads
 - **Send to AI** button — sends the comment thread context to the agent chat via `sendToAgentChat()`
@@ -592,6 +598,37 @@ plugin:
 | Compaction threshold         | Stored blob > 4× fresh encoding triggers tombstone compact |
 | Per-write DB reads           | 1 (CAS version read inside `persistMergedState` only)      |
 
+## Hosted Realtime Sync Gateway {#hosted-gateway}
+
+Self-hosted apps always use the poll/SSE transport described above — nothing
+in this section changes for them. Builder-hosted apps can additionally be
+provisioned onto a hosted Realtime Sync Gateway that fans sync events out
+across multiple serverless instances instead of each instance holding its own
+long-lived connections.
+
+- `AGENT_NATIVE_REALTIME_TRANSPORT=hosted` plus `AGENT_NATIVE_REALTIME_GATEWAY_URL`
+  switch the client onto the gateway transport. Both fail closed — if either
+  is unset, the client silently stays on the local poll/SSE path. The signing
+  secret (`AGENT_NATIVE_REALTIME_HMAC_SECRET`) is a reserved env var injected
+  by Builder's provisioning path, not something you set by hand.
+- `GET /_agent-native/realtime-token` mints a short-lived (10 minute),
+  session-scoped subscribe token the browser uses to open the gateway
+  connection. It's same-origin only and 401s without an active session.
+- `GET /_agent-native/can-see` is the gateway's per-event visibility check: it
+  verifies a signed gateway access token, then re-runs the app's own
+  `resolveAccess` so the gateway can never forward an event to a sharee who
+  has since lost access. Unknown resource types or lookup failures fail closed
+  (`{ allowed: false }`).
+- On Postgres, hosted apps allocate sync versions from the database
+  (`dbAssignedVersions`) instead of an in-process counter, because gateway
+  instances and the app's own serverless instances share one database and
+  must agree on write ordering.
+
+This is an internal hosted-infrastructure detail — most apps never set these
+env vars directly. If you're debugging why hosted realtime isn't active for a
+Builder-hosted app, confirm both the transport env var and the gateway URL are
+set; either being absent falls back to local polling rather than erroring.
+
 ## Security {#security}
 
 ### Choose the access model explicitly
@@ -625,8 +662,10 @@ poll path (safe, higher latency).
 
 All collab routes require authentication. In resource mode, reads require at
 least viewer access and writes require editor access, using the
-same `resolveAccess` / `assertAccess` helpers as the sharing system. A 404
-(not 403) is returned on access failures to avoid leaking document existence.
+same `resolveAccess` / `assertAccess` helpers as the sharing system. Reads and
+awareness routes return 404 on access failure, to avoid leaking document
+existence. Writes require editor access and return 403 (via `assertAccess`)
+when the caller has some access to the document but not editor access.
 
 ### Payload limits
 
@@ -754,3 +793,5 @@ Key properties:
   server-side merge.
 - [Template: Design](/docs/template-design) — `Y.UndoManager` undo/redo scoped
   to local user edits.
+- [Toolkit piece: Collaboration Kit](/docs/toolkit-collaboration) — the presence,
+  live-cursor, and undo components built on this transport.

package/docs/content/recurring-jobs.mdx

@@ -11,6 +11,12 @@ Recurring jobs fire on a clock. To react to _events_ (a booking created, an emai
 
 Jobs live in [Agent Resources](/docs/agent-resources) at `jobs/<name>.md` — just a Markdown file with YAML frontmatter. No registration, no wiring. Drop the file in and the framework picks it up.
 
+<Callout id="doc-block-rj1" tone="info">
+
+**New to recurring jobs?** Jump to [Creating a job](#creating) — most people create one by asking the agent or with the Resources tab `+` menu, not by hand-editing the file format below.
+
+</Callout>
+
 ## A job file {#job-file}
 
 <AnnotatedCode
@@ -209,10 +215,16 @@ The scheduler is a framework plugin (the internal `processRecurringJobs()` routi
 
 </Callout>
 
+<Callout id="doc-block-rj2" tone="warning">
+
+**Disabled by default in local dev.** The scheduler's `setInterval` loop never starts when `NODE_ENV` is `development` or `test`, or when the app URL points at `localhost` / `127.0.0.1` / `*.localhost` — which covers most local dev setups. Set `AGENT_NATIVE_ENABLE_LOCAL_RECURRING_JOBS=1` to run the scheduler locally anyway. On a hosted deployment that runs its own dedicated sweep instead of this in-process scheduler, set `AGENT_NATIVE_DISABLE_RECURRING_JOBS=1` as the matching kill switch.
+
+</Callout>
+
 ## Debugging a job {#debugging}
 
 - Open `jobs/<name>.md` in Agent Resources — the frontmatter shows `lastRun`, `lastStatus`, `lastError`, `nextRun`.
-- **Test it without waiting:** there's no force-fire tool. To exercise the same work on demand, either paste the job's prompt into the agent chat and let it run there, or temporarily set the schedule to the next minute so the scheduler picks it up on the next tick (then restore the real cron).
+- **Test it without waiting:** there's no force-fire tool. To exercise the same work on demand, either paste the job's prompt into the agent chat and let it run there, or temporarily set the schedule to the next minute so the scheduler picks it up on the next tick (then restore the real cron). This only works if the scheduler is actually running — see the local-dev caveat above; set `AGENT_NATIVE_ENABLE_LOCAL_RECURRING_JOBS=1` first if you're testing on localhost.
 - **Pause it:** flip `enabled: false`. The file stays put, just stops running.
 
 ## Agent tool {#agent-tool}
@@ -246,3 +258,4 @@ Recurring jobs are "how do I make the agent act on its own?" The scheduling pack
 - [**Actions**](/docs/actions) — the tools a job calls
 - [**MCP Clients**](/docs/mcp-clients) — connect remote or local MCP tools and OAuth grants
 - [**Agent Teams**](/docs/agent-teams) — jobs often spawn sub-agents to do parallel work
+- [**Toolkit piece: Toolkit Capability Modules**](/docs/toolkit-capability-packages) — how this differs from the installable Scheduling package

package/docs/content/security.mdx

@@ -320,7 +320,7 @@ pnpm action db-check-scoping --require-org  # Also require org_id
 | OAuth tokens (Google, GitHub)      | `oauth_tokens` store via `saveOAuthTokens()`               |
 | Session tokens                     | Automatic (Better Auth handles this)                       |
 
-Per-user/per-org credentials and the vault are encrypted at rest with AES-256-GCM, keyed by `SECRETS_ENCRYPTION_KEY` (falling back to `BETTER_AUTH_SECRET`); production refuses to start without one. To encrypt any pre-existing plaintext credential rows in place, run `pnpm action db-migrate-encrypt-credentials` (idempotent, non-destructive).
+Per-user/per-org credentials and the vault are encrypted at rest with AES-256-GCM. For a per-user/per-org credential, the key precedence is `<APP_NAME>_SECRETS_ENCRYPTION_KEY` (app-scoped — useful in a multi-app workspace where apps shouldn't share one key) → `SECRETS_ENCRYPTION_KEY` → `BETTER_AUTH_SECRET`; production refuses to start without one of these set. The shared workspace vault (`app_secrets`, meant to decrypt the same in sibling apps) checks `SECRETS_ENCRYPTION_KEY` / `BETTER_AUTH_SECRET` first, then on a hosted workspace deploy falls back further to material derived from `A2A_SECRET`, and only then to the app-scoped key as a last resort. To encrypt any pre-existing plaintext credential rows in place, run `pnpm action db-migrate-encrypt-credentials` (idempotent, non-destructive).
 
 Never store secrets in `settings`, `application_state`, source code, or action responses. Use the credential / vault APIs above — they handle both encryption and per-user scoping.
 
@@ -352,10 +352,12 @@ Without `A2A_SECRET` in production, every A2A endpoint and the `/_agent-native/i
 
 ## Inbound Webhooks {#webhooks}
 
-Inbound webhook handlers (Resend, SendGrid, Slack, Telegram, WhatsApp, Recall.ai, Deepgram, Zoom, Google Docs Pub/Sub) refuse forged requests by default in production: when the corresponding signing secret env var is missing, the handler returns 401 instead of accepting and dispatching.
+Inbound webhook handlers (Resend, SendGrid, Slack, Telegram, WhatsApp) refuse forged requests by default in production: when the corresponding signing secret env var is missing, the handler returns 401 instead of accepting and dispatching.
 
 This was previously a "warn and accept" stance — set the secret you'd otherwise be missing, or opt back into the old behavior with `AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS=1` for local dev only. See [Messaging](/docs/messaging#env-vars) for the per-integration signing-secret variables.
 
+Google Docs Pub/Sub push notifications don't go through that generic adapter gate — they're a separate code path that verifies an OIDC bearer token against `GOOGLE_DOCS_PUSH_AUDIENCE`. When that audience variable is unset in production, the endpoint fails closed with **503** (not 401); when it's set but the token doesn't verify, it returns 401.
+
 ## Production Checklist {#production-checklist}
 
 ### Auth & secrets
@@ -422,6 +424,7 @@ Workspace-scope secret writes still require org owner/admin role regardless of t
 
 - [**Authentication**](/docs/authentication) — auth modes, cookie realms, and session details this page builds on
 - [**Multi-Tenancy**](/docs/multi-tenancy) — the org-membership model behind `org_id` scoping
+- [**Organizations, Teams & Permissions**](/docs/organizations-teams-permissions) — the org-role vs. resource-role RBAC distinction and the org REST route table
 - [**Sharing**](/docs/sharing) — the `ownableColumns()` and access-guard pattern applied to shareable resources
 - [**Messaging**](/docs/messaging#env-vars) — per-integration webhook signing secrets referenced in the checklist above
 - [**Deployment**](/docs/deployment) — the production environment variables this checklist assumes are set

package/docs/content/server.mdx

@@ -258,13 +258,14 @@ Migrations must be additive. Never put destructive SQL in startup plugins.
 
 ## Framework-Mounted Routes {#framework-routes}
 
-The framework mounts its own routes under `/_agent-native/`. Treat that namespace as reserved.
+The framework mounts its own routes under `/_agent-native/`. Treat that namespace as reserved. This table is representative, not exhaustive — it lists the routes most templates touch directly.
 
 | Route prefix                     | Purpose                                                                         |
 | -------------------------------- | ------------------------------------------------------------------------------- |
 | `/_agent-native/actions/:name`   | Action HTTP endpoints                                                           |
 | `/_agent-native/agent-chat`      | Agent chat loop                                                                 |
 | `/_agent-native/poll`            | SQL-backed UI sync                                                              |
+| `/_agent-native/runs`            | Progress primitive — the `RunsTray` polls this; see [Progress](/docs/progress)  |
 | `/_agent-native/resources/*`     | Workspace resources                                                             |
 | `/_agent-native/extensions/*`    | Runtime extensions and extension proxy (legacy alias: `/_agent-native/tools/*`) |
 | `/_agent-native/integrations/*`  | Messaging/webhook integrations                                                  |

package/docs/content/sharing.mdx

@@ -95,12 +95,20 @@ Every template that stores user-authored work uses this model. Concretely:
 - **Clips** — screen recordings (Loom-style)
 - **Plan** — visual plans and PR recaps
 - **Forms** — form definitions
-- **Calendar** — events and booking links
+- **Calendar** — booking links
 - **Analytics** — dashboards, saved analyses, and tokenized session replays
+- **Assets** — asset libraries
+- **Brain** — sources, knowledge entries, proposals, and projects
 - **Extensions** — sandboxed mini-apps (see [Extensions](/docs/extensions#sharing))
 
 Every one of these uses the same `ownableColumns()` schema helper, the same `share-resource` action, and the same `<ShareButton>` UI. Move from one template to another and the share dialog looks identical.
 
+<Callout id="doc-block-sharing1" tone="info">
+
+Calendar **events** are not part of this system — they're fetched live from the Google Calendar API and have no `owner_email` row of their own, so access to an event follows Google Calendar's own sharing and invite model. Only booking links (the public scheduling pages you create) are framework-shareable resources.
+
+</Callout>
+
 ## What's not covered {#not-covered}
 
 A few areas are intentionally outside the sharing system:
@@ -113,12 +121,22 @@ A few areas are intentionally outside the sharing system:
 
 Every shareable resource gets a share button in its header. Clicking it opens a popover anchored to the button (not a modal) with:
 
-- Visibility selector (`Private` / `Organization` / `Public link`).
-- "Add people or teams" autocomplete — search users in the org or paste an email.
+- "Add people or teams" autocomplete — search users in the org or paste an email, plus a role picker.
 - A Google Docs-style `Notify people` checkbox for individual email grants.
 - A list of current grants with role pickers and a remove control.
+- General access: visibility selector (`Private` / `Organization` / `Public link`).
 - A copy-link button that respects the current visibility.
 
+<WireframeBlock id="doc-block-sharing2">
+  <Screen
+    surface="popover"
+    caption="Share popover — anchored to the header button, not a modal"
+    html={
+      "<div style='display:flex;flex-direction:column;gap:16px;padding:18px 20px;min-width:360px;box-sizing:border-box'><div style='display:flex;align-items:stretch;gap:8px'><input placeholder='Add people or teams' style='flex:1'/><span class='wf-pill'>Editor</span></div><label style='display:flex;align-items:center;gap:8px' class='wf-muted'><input type='checkbox' checked/> Notify people</label><div style='display:flex;flex-direction:column;gap:10px'><strong>People with access</strong><div style='display:flex;align-items:center;gap:10px'><span class='wf-pill'>AL</span><span style='flex:1'>Ada Lovelace (you)</span><span class='wf-muted'>Owner</span></div><div style='display:flex;align-items:center;gap:10px'><span class='wf-pill'>MT</span><span style='flex:1'>marketing@company.com</span><span class='wf-pill'>Editor</span><span class='wf-muted'>Remove</span></div></div><div style='display:flex;flex-direction:column;gap:8px;padding-top:14px;border-top:1.4px solid var(--wf-line)'><strong>General access</strong><div style='display:flex;align-items:center;gap:10px'><span class='wf-pill accent'>Organization</span><span class='wf-muted'>Anyone at the org can view</span></div></div><div style='display:flex;gap:8px'><input readonly value='https://app.example.com/share/8fq2k1' style='flex:1'/><button class='primary'>Copy link</button></div></div>"
+    }
+  />
+</WireframeBlock>
+
 The share button is a single import:
 
 ```tsx
@@ -344,3 +362,4 @@ Sharing rides on the framework's broader data-scoping model — list/read/write
 - [**Authentication**](/docs/authentication) — sessions, organizations, and how identity flows into the request context
 - [**Extensions**](/docs/extensions#sharing) — sharing in the sandboxed mini-app surface
 - [**Creating Templates**](/docs/creating-templates) — wiring `ownableColumns` into a new template's schema
+- [**Toolkit piece: Sharing Kit**](/docs/toolkit-sharing) — the share button, share dialog, and visibility badge built on this model