@agent-native/core 0.152.1 → 0.153.0

package/src/templates/chat/.agents/skills/frontend-design/SKILL.md

@@ -36,7 +36,7 @@ Before coding, decide:
   can wait until context or intent makes it relevant?
 - **Differentiation**: What makes this feel designed for this exact domain?
 
-Then implement working code that is cohesive, accessible, responsive, and polished in small details: typography, spacing, copy, motion, empty states, loading states, focus states, and error states.
+Then implement working code that is cohesive, accessible, responsive, and polished in small details: typography, spacing, motion, empty states, loading states, focus states, and error states. Polish means removing copy, not writing more of it.
 
 ## Visual Direction Contract
 
@@ -54,80 +54,72 @@ before selecting its accent family. Shared behavior and semantic token names
 should stay consistent; palette, density, composition, type contrast, and
 shape language should not be identical by default.
 
-## High-Signal Minimalism And Progressive Disclosure
-
-Minimalism means fewer competing kinds of UI, not less useful information. Keep
-surfaces dense and scannable: reduce redundant prose, decorative containers,
-borders, badges, accent colors, and persistent controls before removing content
-that helps the user orient, compare, decide, or recover. The reference class is
-calm productivity software such as ChatGPT/Codex, Linear, and Vercel, not empty
-whitespace.
-
-### Product UX Philosophy
-
-Apply these principles as binding decision rules:
-
-- **Purpose over presence**: Every visible element must support orientation,
-  state comprehension, a decision, an action, or recovery. Before adding one,
-  name which; if it supports none or duplicates another element, remove or
-  defer it.
-- **Clarity over cleverness**: Use plain language, familiar patterns, explicit
-  hierarchy, and visible state. Do not make decoration or invented terminology
-  carry meaning. Preserve the labels, hit targets, focus states, and recovery
-  paths required for accessible use.
-- **Simple first, powerful on demand**: Keep the current task and state in the
-  default presentation. Put advanced, rare, diagnostic, and secondary work
-  behind contextual disclosure, menus, or Settings. Do not turn a discoverability
-  concern into permanent chrome, and do not hide information needed for the
-  current decision.
-- **Hierarchy over chrome**: Use typography, spacing, alignment, and restrained
-  emphasis to organize information. Treat prose, controls, borders, cards,
-  badges, and accent colors as a competition budget: reduce competing kinds of
-  elements before reducing useful information. When a surface has one clear
-  next decision, give it dominant emphasis and move secondary actions out of
-  the default path. Do not wrap every section in a card or add borders for
-  grouping alone; use spacing, alignment, typography, or dividers first. A
-  container must communicate grouping, state, or interaction.
-- **Coherence over novelty**: Reuse the product's primitives, interaction
-  patterns, and language. When given a screenshot or reference product, match
-  its underlying hierarchy, density, and behavior; do not copy decoration or
-  introduce a second visual language without a product reason.
-- **Quiet continuity**: Feedback must be immediate, contextual, and honest.
-  Preserve the user's place and layout, make loading, empty, and error states
-  understandable, and use motion only to explain a change.
-- **Respect repeated use**: Optimize for the hundredth use, not the first
-  impression. If a control repeats an explanation, occupies persistent space
-  for an occasional task, or turns routine work into ceremony, remove it or
-  move it to the contextual surface that owns it.
-
-### Progressive Disclosure And Information Timing
-
-Expose information and controls according to relevance, frequency, and
-consequence. Before coding, inventory the content and actions and assign them to
-the smallest useful visibility layer:
-
-1. **Orient and act**: location, current state, and context needed for the next
-   meaningful choice.
-2. **Support active work**: details and controls for the selected item or
-   current workflow.
-3. **Available on demand**: advanced settings, diagnostics, credentials,
-   metadata, destructive actions, documentation, and rare tools.
-
-Use a disclosure pattern that matches the task. Keep independent concerns easy
-to scan inside an expanded area instead of dumping every form, explanation,
-and secondary action into the first reveal. A collapsed row must retain its
-label and essential state; remove explanatory subtext unless it changes the
-next decision. For configuration with a known current state, show that state
-first and expose editing contextually instead of defaulting to a full form.
+## Default Surface Density
+
+This is the most repeated correction in this repo, tracked as `text-heavy-ui` in
+`node scripts/agent-friction-report.mjs`. Every item below has been asked for by
+name more than once, usually right after a previous surface was corrected for the
+same thing. So treat the list as the default shape you apply, not a tradeoff you
+weigh per surface. If the user wants one of these, they will ask.
+
+Density comes from data, not from prose. Linear, Vercel, and ChatGPT/Codex are
+dense — with rows, values, and state, and almost no explanatory sentences. That
+is the target: a surface full of information and nearly empty of narration. So
+"make it minimal" is never satisfied by removing data or by burying it behind
+extra clicks, and never blocked by deleting a sentence.
+
+Do not add, unless asked:
+
+- A page title that repeats the nav item or route the user just clicked, or a
+  breadcrumb on a page that already has a back arrow.
+- A description, subtitle, tagline, or eyebrow under any title — page, card,
+  panel, tab, dialog, settings group, or list row. A surface gets a title or a
+  description, never both.
+- A count, stat, or summary strip over content already on screen: "11 apps",
+  "25 results", "0 signals · 0 decisions · 0 runs".
+- An About, help, or "what this does" section in settings.
+- Helper text under each option in a chooser. The option label carries it.
+- A placeholder that restates its own label.
+
+The explanation goes in a tooltip, a `Manage` popover, a menu, or nowhere.
+Settings use one shape: a compact row with the label and its current state, one
+action on the right, and `Manage` revealing the form once something is
+configured. Do not spell every input out on the default surface.
+
+**Chrome is not content.** These rules govern strings you write into JSX. A
+`description` the user typed and the app stored is data — render it, and render
+nothing when it is empty. Never add a `|| "No description yet."` fallback; an
+empty field is empty, not an opening to explain the feature.
+
+### The Shape That Got Approved
+
+A multi-step connect flow the user accepted on 2026-08-12, after rejecting a
+dense dialog of the same content as "HORRIBLE ... overwhelming":
+
+- Full-screen takeover rather than a crowded modal. Generous empty space is fine.
+- One question per step as the heading ("Who should use this?"), at most one
+  short line under it, and nothing under the options.
+- Choices are single-line rows — icon plus label — with the common one
+  preselected, so the happy path is one click.
+- "Step 2 of 2" and a thin progress bar instead of every field at once.
+- Advanced and rare detail behind a labeled collapsed row ("Advanced details",
+  "App grants"): label only, no preview of the contents.
+- Current state shown rather than explained: "Dispatch can reuse this account".
+- Quiet Cancel on the left, primary action on the right.
+
+Use that same treatment for sibling flows. When the user points at another
+surface — "like forms", "like the integrations grid" — copy that surface's
+structure instead of inventing a second language for the same job.
+`templates/forms/` is the reference implementation: no page title, no
+breadcrumbs, no eyebrows, no card descriptions, and row subtext only where it
+renders a user-authored field.
 
 Before shipping, verify collapsed, expanded, loading, empty, error, and
 narrow-width states. The default state fails review when its first viewport
-contains multiple unrelated forms, repeated explanatory copy, documentation
-links, or controls for unrelated tasks. It also fails when useful information
-has been replaced with empty whitespace or extra clicks solely to look minimal.
-The default state passes when users can identify their location, current state,
-current task, and relevant next choice without reading documentation, while
-the useful information remains dense and scannable.
+carries explanatory paragraphs, several unrelated forms, or controls for another
+task. `guard:no-default-chrome` checks the structural half of this on lines your
+branch adds; it cannot see a sentence you wrote, so the list above is still
+yours to apply.
 
 ## Aesthetic Guidelines
 
@@ -212,8 +204,9 @@ the useful information remains dense and scannable.
 Before shipping a new app or a substantial redesign, review the surface as an
 operator would use it repeatedly:
 
-- Can users identify where they are, what state they are in, and what
-  meaningful choices or next steps are available?
+- Count the sentences in the first viewport. If any of them explains the UI
+  rather than reporting state, delete it. "Could a user identify where they are?"
+  is a question every surface passes; a sentence count is not.
 - Remove competing or redundant elements, then place optional inputs, provider
   choices, diagnostics, long explanations, and secondary actions where they
   remain discoverable without crowding the current task.
@@ -229,8 +222,8 @@ operator would use it repeatedly:
   consistent, but a repeated palette, hero composition, type pairing, and
   radius language without a product reason is visual drift, not consistency.
 - Check the result with realistic content at the target desktop width and a
-  narrow width. If it feels like documentation instead of a tool, reduce noise
-  or clarify the hierarchy.
+  narrow width. If it feels like documentation instead of a tool, subtract until
+  it does not — restyling it is not the fix.
 
 ## shadcn/ui Design Rules
 
@@ -241,7 +234,7 @@ operator would use it repeatedly:
 - Use `cn()` from the local utils alias for conditional classes.
 - Dialog, Sheet, Drawer, and AlertDialog content must have an accessible title. Use `sr-only` only when the visible design already communicates the title.
 - Put menu/list items inside their group primitives: `SelectGroup`, `DropdownMenuGroup`, `CommandGroup`, and equivalents.
-- Use full `Card` composition when the content has a title, description, content, or actions. Do not dump complex cards into a single `CardContent`.
+- Compose cards from `CardHeader`, `CardTitle`, `CardContent`, and `CardFooter`. Do not add `CardDescription`, and do not hand-roll a muted `<p>` under a `CardTitle` — a card gets a title or a description, never both.
 - Use `ToggleGroup` for small option sets, `Switch` for binary settings, `Checkbox` for multi-select, `RadioGroup` for one-of-many, and `Slider`/inputs for numeric values.
 - For forms, prefer the app's existing shadcn form pattern. If newer `Field`, `FieldGroup`, or `InputGroup` primitives are installed or appropriate to add, use them instead of raw layout divs.
 - Page and section data loading uses layout-matching `Skeleton` geometry. Do
@@ -263,9 +256,9 @@ task without a clear product reason:
   preserve discoverability and reduce noise.
 - Full-width banners, persistent helper rows, decorative cards, or explanatory
   chrome for status that could be communicated more clearly with less weight.
-- Hiding essential meaning or operability behind progressive disclosure. Defer
-  complexity when it is contextual or infrequent, but preserve labels, focus,
-  hit targets, accessibility, and recovery paths.
+- Dropping a label, focus state, hit target, accessible name, or recovery path in
+  the name of minimalism. Defer complexity freely; never defer the ability to
+  operate the control.
 - UI cards nested inside other cards.
 - Text or icons that resize or shift fixed-format UI on hover/loading.
 

package/src/templates/chat/.agents/skills/portability/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: portability
+description: >-
+  How to keep template code database-agnostic and hosting-agnostic. Use when
+  defining schemas, writing raw SQL, creating server routes, or anything that
+  could leak a SQLite-only, Postgres-only, or Node-only assumption.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Portability
+
+## Rule
+
+**Never write code that only works on one database or one hosting platform.** Templates must run on portable SQL backends (SQLite, Postgres, D1, Turso/libSQL, Supabase, Neon, managed platform SQL environments when available) and any Nitro deploy target (Node, Cloudflare, Netlify, Vercel, Deno, Lambda, Bun) without code changes.
+
+## Database Agnostic
+
+Use the dialect-agnostic schema helpers from `@agent-native/core/db/schema` for schemas and Drizzle's query builder for reads/writes:
+
+```ts
+import {
+  table,
+  text,
+  integer,
+  real,
+  now,
+  sql,
+} from "@agent-native/core/db/schema";
+
+export const meals = table("meals", {
+  id: text("id").primaryKey(),
+  name: text("name").notNull(),
+  calories: integer("calories").notNull(),
+  weight: real("weight"),
+  archived: integer("archived", { mode: "boolean" }).notNull().default(false),
+  createdAt: text("created_at").notNull().default(now()),
+});
+```
+
+| Helper    | Purpose                                                                                   |
+| --------- | ----------------------------------------------------------------------------------------- |
+| `table`   | Delegates to `pgTable` or `sqliteTable` based on dialect                                  |
+| `text`    | Works in both dialects, supports `{ enum: [...] }`                                        |
+| `integer` | `{ mode: "boolean" }` maps to Postgres `boolean` automatically                            |
+| `real`    | `real` on SQLite, `double precision` on Postgres                                          |
+| `now`     | Dialect-agnostic current timestamp — use with `.default(now())` on text timestamp columns |
+| `sql`     | Re-exported from `drizzle-orm` for raw SQL expressions                                    |
+
+**Never import from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` directly in template code.** Always use `@agent-native/core/db/schema` instead.
+
+Use Drizzle's portable query DSL for app code:
+
+```ts
+import { and, desc, eq } from "drizzle-orm";
+
+const rows = await db
+  .select()
+  .from(meals)
+  .where(and(eq(meals.ownerEmail, userEmail), eq(meals.archived, false)))
+  .orderBy(desc(meals.createdAt));
+```
+
+Avoid `db.execute(...)`, `getDbExec()`, and handwritten SQL in actions, handlers, and stores when Drizzle can express the query. Raw SQL should be limited to additive migrations, health checks, carefully reviewed advanced queries, or one-off maintenance scripts. For timestamps in Drizzle schemas, use `.default(now())`; for migration SQL, use `runMigrations()` so framework-supported compatibility rewrites and dialect-gated statements stay centralized.
+
+### Raw SQL helpers
+
+- `getDbExec()` — auto-converts `?` params to `$1` for Postgres
+- `isPostgres()` — runtime dialect check
+- `intType()` — returns correct integer type for the dialect
+
+### Never
+
+Never write SQLite-only syntax in product code or docs examples: `INSERT OR REPLACE`, `AUTOINCREMENT`, `datetime('now')`. When writing docs, say "SQL database" — not "SQLite".
+
+Never write Postgres-only syntax in shared app code either: `ILIKE`, `::type` casts, `jsonb_*`, `RETURNING` assumptions, serial/identity syntax, `ON CONFLICT` upserts, or `ALTER ... TYPE` unless the code is inside a dialect-gated migration block. Prefer Drizzle APIs or framework helpers.
+
+When giving deployment guidance, be precise about durability: local SQLite is the development fallback, while production needs a persistent `DATABASE_URL`. Do not steer users to Turso as the only path; it is one option among Neon, Supabase, Turso/libSQL, plain Postgres, durable SQLite, D1 bindings, and managed platform SQL environments when available.
+
+## Hosting Agnostic
+
+The server runs on **Nitro** with **H3** as the HTTP framework. Templates must be deployable to any Nitro-supported target.
+
+### Never use Express
+
+All server code uses H3/Nitro: `defineEventHandler`, `readBody`, `getMethod`, `setResponseHeader`, etc. Express is not a dependency. If you see Express types or patterns anywhere, replace them with H3 equivalents.
+
+### No platform-specific config in scaffolded template source
+
+Files like `netlify.toml`, `wrangler.toml`, `vercel.json`, and `netlify/functions/` must NOT appear in the CLI scaffold source (`packages/core/src/templates/`) — apps generated for users stay hosting-agnostic, with platform configuration living in CI/hosting dashboards.
+
+**Exception:** this monorepo's own first-party deployed apps (`templates/*/netlify.toml`, the root `wrangler-*.toml` files) are deployment artifacts of _this_ repo (mail.agent-native.com, etc.) and are expected to exist. Do not delete them as if they were accidental cruft — the rule above is about what gets scaffolded into a new app, not about this repo's deploy configs.
+
+### No Node APIs in server routes/plugins
+
+Never use `fs`, `child_process`, or `path` in server routes and plugins. Use Nitro abstractions. (Actions in `actions/` run in Node.js and can use Node APIs freely.)
+
+### No persistent-process assumptions
+
+Never assume a persistent server process. Use the SQL database for all state.
+
+## Related Skills
+
+- `storing-data` — Schema patterns and the core SQL stores
+- `server-plugins` — Framework routes and H3 handler patterns
+- `security` — SQL injection prevention via parameterized queries

package/src/templates/chat/.agents/skills/secrets/SKILL.md

@@ -0,0 +1,339 @@
+---
+name: secrets
+description: >-
+  Declaratively register API keys and service credentials a template needs so
+  they appear in the agent sidebar settings UI and the onboarding checklist.
+  Use for any third-party API key (OpenAI, Stripe, Twilio, etc.) and for
+  surfacing OAuth connections in the unified settings UI.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Secrets Registry
+
+## Non-negotiable rule
+
+Never hardcode credential values. Source, docs, tests, fixtures, prompts, seed
+data, and generated extension/app content may mention credential **names** such
+as `OPENAI_API_KEY`, but must not contain real API keys, tokens, webhook URLs,
+signing secrets, OAuth refresh tokens, or private Builder/customer data.
+
+Secret values are supplied at runtime through deployment configuration, the
+encrypted `app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
+`${keys.NAME}` substitution. Examples must use obvious placeholders such as
+`<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not real-looking copied values.
+
+## When to use
+
+Use this for any external credential your template needs: API keys, service
+tokens, webhook secrets. It gives you:
+
+- A sidebar UI entry for each credential (masked input, rotate, test, delete).
+- Automatic onboarding-checklist items for `required: true` secrets.
+- A stable server-side read API (`readAppSecret`) that decrypts values on
+  demand.
+- Validator hooks for health-checking keys before save and from a Test button.
+
+## When NOT to use
+
+- OAuth flows that need to run the full authorization code exchange — use
+  `@agent-native/core/oauth-tokens` directly to save/refresh tokens. The
+  registry can still surface the OAuth connection in the sidebar by
+  registering a secret with `kind: "oauth"` — that just delegates status
+  lookup to oauth-tokens and renders a Connect button, no `app_secrets` row
+  is written.
+- Purely process-level env vars that are never user-facing (e.g. `NODE_ENV`,
+  deployment flags). Those belong in the onboarding `form` method or the
+  `envKeys` list in `core-routes-plugin`.
+
+## Registering a secret
+
+```ts
+// server/plugins/register-secrets.ts
+import { defineNitroPlugin } from "@agent-native/core/server";
+import { registerRequiredSecret } from "@agent-native/core/secrets";
+
+export default defineNitroPlugin(() => {
+  registerRequiredSecret({
+    key: "OPENAI_API_KEY",
+    label: "OpenAI API Key",
+    description: "Used for Whisper transcription of your recordings.",
+    docsUrl: "https://platform.openai.com/api-keys",
+    scope: "user",
+    kind: "api-key",
+    required: true,
+    validator: async (value) => {
+      const res = await fetch("https://api.openai.com/v1/models", {
+        headers: { Authorization: `Bearer ${value}` },
+      });
+      return res.ok
+        ? { ok: true }
+        : { ok: false, error: `OpenAI rejected the key (HTTP ${res.status})` };
+    },
+  });
+});
+```
+
+### OAuth in the unified UI
+
+```ts
+registerRequiredSecret({
+  key: "GOOGLE_CONNECTED",
+  label: "Google account",
+  description: "Grants access to Gmail / Calendar APIs.",
+  scope: "user",
+  kind: "oauth",
+  required: true,
+  oauthProvider: "google", // must match the provider id in oauth-tokens
+  oauthConnectUrl: "/_agent-native/google/auth-url",
+});
+```
+
+The sidebar shows a Connect button instead of a text input; no `app_secrets`
+row is written — status is derived from `hasOAuthTokens("google")`.
+
+## Registered options
+
+| Field              | Type                                    | Purpose                                                                  |
+| ------------------ | --------------------------------------- | ------------------------------------------------------------------------ |
+| `key`              | `string`                                | Env-var style name (`OPENAI_API_KEY`). Also the storage key.             |
+| `label`            | `string`                                | Human-readable title in the sidebar.                                     |
+| `description`      | `string?`                               | Subtitle under the label.                                                |
+| `docsUrl`          | `string?`                               | "Get key" link rendered on the card.                                     |
+| `scope`            | `"user" \| "workspace"`                 | Per-user or shared across the active org.                                |
+| `kind`             | `"api-key" \| "oauth"`                  | Drives UI and storage behavior.                                          |
+| `required`         | `boolean?`                              | When true, an onboarding step is auto-injected.                          |
+| `validator`        | `(v) => Promise<boolean \| {ok,error}>` | Runs on save and from the Test button. Never log `v`.                    |
+| `oauthProvider`    | `string?` (oauth-kind only)             | Provider id in `oauth-tokens` that backs this entry.                     |
+| `oauthConnectUrl`  | `string?` (oauth-kind only)             | URL the Connect button points at.                                        |
+
+## Reading a secret from an action
+
+```ts
+import { z } from "zod";
+import { defineAction } from "@agent-native/core/action";
+import { readAppSecret } from "@agent-native/core/secrets";
+import { getRequestUserEmail } from "@agent-native/core/server";
+
+export default defineAction({
+  description: "Transcribe an audio file with Whisper",
+  schema: z.object({ fileUrl: z.string() }),
+  run: async ({ fileUrl }) => {
+    const email = await getRequestUserEmail();
+    if (!email) throw new Error("Not signed in");
+
+    const stored = await readAppSecret({
+      key: "OPENAI_API_KEY",
+      scope: "user",
+      scopeId: email,
+    });
+    const apiKey = stored?.value;
+    if (!apiKey) {
+      throw new Error(
+        "OPENAI_API_KEY is not set. Configure it in the sidebar settings.",
+      );
+    }
+
+    // …call OpenAI. NEVER log the key or include it in error messages.
+  },
+});
+```
+
+Rules:
+
+- **Never log the value.** The read layer enforces this server-side; your
+  code must do the same.
+- **Use env vars only for deploy-level secrets.** If a credential is
+  user-scoped, org-scoped, or workspace-scoped, read the scoped vault/credential
+  store. Do not add a `process.env` fallback that makes every user inherit one
+  deployment's key.
+- **Scope matches the registration.** `scope: "user"` → pass the user email.
+  `scope: "workspace"` → pass the active `orgId` from
+  `getOrgContext(event).orgId`.
+- **One resolver per key, and every runtime path goes through it.** Before
+  reading a credential, grep the app for the key name. If a resolver already
+  exists (`resolveXConfig`, a connector, a client factory), call it — do not
+  read `process.env` for that key a second time somewhere else.
+- **Identity comes from the caller, not the module.** A shared helper under
+  `server/lib/` takes the email as a parameter; only an entrypoint (action,
+  route, cron) decides whose identity it is. A library that resolves its own
+  identity from `process.env.AGENT_USER_EMAIL` authorizes the deployment rather
+  than the caller.
+
+The failure this prevents is not a leak — it is a split brain. When the config
+check reads the vault and the feature reads `process.env`, the settings UI and
+onboarding checklist report the integration as **configured** while every actual
+call fails with "env var is required". The credential is right there in the
+vault, so the error names the wrong cause and sends everyone hunting for a sync
+or redeploy problem that does not exist. This has now shipped four times in one
+app (BigQuery, Jira, Pylon, Academy).
+
+Before finishing any change that touches a credential, run the guard from the
+app directory — it finds this whether the app lives in `templates/` or in a
+workspace repo:
+
+```bash
+npx agent-native doctor --only no-env-credentials
+```
+
+## `resolveCredential` sees exactly one organization
+
+`resolveCredential(key, { userEmail, orgId })` checks the user scope, then the
+one `orgId` you pass, then the solo workspace. That is the whole search. It is
+correct for a signed-in request, and wrong for two common cases:
+
+- **The caller has no organization.** A cron, a scheduled job, or any CLI run
+  without a real member identity resolves no `orgId`, so only the user and solo
+  scopes are ever consulted — and a shared key is in neither.
+- **The key was synced under a different organization.** `app_secrets` has no
+  scope visible to every org (`readAppSecret` is strict equality on
+  `(scope, scope_id, key)`), so a key the vault UI advertises as available to
+  every app is unreadable from any org except the one that ran the sync.
+
+Both produce the same misleading "not set" that the split brain above produces,
+which is why swapping `process.env` for `resolveCredential` can look like a fix
+and change nothing. A workspace app should read shared keys through a resolver
+that also sweeps the caller's other memberships and a designated vault org —
+see `resolveConnectorSecret` and `AGENT_VAULT_ORG_ID` in the builder-workspace
+repo for the shape, including the boot-time assertion that the deployment really
+is single-tenant before a non-membership-gated fallback is safe.
+
+**The doctor guard does not catch this second form** — it looks for
+`process.env` reads, and `resolveCredential` is not one. Grep for
+`resolveCredential` yourself and confirm each call sits somewhere a single-org
+lookup is genuinely the right question. Findings that pair it with a
+`?? process.env.KEY` fallback are the sanctioned deploy-level escape hatch; the
+bugs are calls whose value can only live in another org's vault.
+
+## HTTP routes
+
+Core routes plugin mounts these under `/_agent-native/secrets/` automatically:
+
+- `GET /_agent-native/secrets` — list registered secrets with status (`set`
+  / `unset` / `invalid`), metadata, and — for set api-keys — the last 4
+  characters. Values are never returned.
+- `POST /_agent-native/secrets/:key` — body `{ value, scope?, scopeId? }`.
+  Runs the registered validator; returns 400 with the error on failure.
+- `DELETE /_agent-native/secrets/:key` — remove the stored value.
+- `POST /_agent-native/secrets/:key/test` — re-run the validator against the
+  currently stored value.
+
+## Storage & encryption
+
+- Values are stored in `app_secrets` (created on-demand; no migration
+  needed).
+- Values are encrypted at rest with AES-256-GCM. Generic app-local secrets
+  prefer `<APP_NAME>_SECRETS_ENCRYPTION_KEY` (for example,
+  `ANALYTICS_SECRETS_ENCRYPTION_KEY`), then `SECRETS_ENCRYPTION_KEY`, then
+  `BETTER_AUTH_SECRET`.
+- Workspace-shared `app_secrets` prefer
+  `WORKSPACE_SECRETS_ENCRYPTION_KEY`, then the legacy shared
+  `SECRETS_ENCRYPTION_KEY`, then a purpose-derived key from `A2A_SECRET`.
+  Better Auth and app-scoped keys remain legacy read candidates; a successful
+  legacy decrypt is compare-and-swap migrated to the preferred shared key
+  without changing the row timestamp.
+- Set the same stable `WORKSPACE_SECRETS_ENCRYPTION_KEY` in every app that
+  reads a shared vault. It is intentionally separate from app-local OAuth
+  encryption. If the vault still relies on `A2A_SECRET`, rotating A2A material
+  also rotates its encryption key. Add the stable vault key everywhere and
+  read/migrate existing rows before rotating A2A.
+- To rotate the dedicated workspace key itself, deploy the new value together
+  with `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS=<old value>`, let reads
+  migrate ciphertext, then remove the previous key after the migration window.
+- If no configured key material exists, development uses a machine-local
+  fallback and logs a one-time warning. Production fails closed.
+
+## Ad-hoc Keys
+
+Ad-hoc keys are user-created secrets that are not declared by the template.
+Users create them through the settings UI or the agent chat to use with
+automations and the `web-request` tool. They support `${keys.NAME}`
+substitution in outbound HTTP requests.
+
+### Ad-hoc API
+
+Core routes plugin mounts these under `/_agent-native/secrets/adhoc`:
+
+- `GET /_agent-native/secrets/adhoc` — list all ad-hoc keys (name, last 4
+  chars, URL allowlist). Values are never returned.
+- `POST /_agent-native/secrets/adhoc` — body `{ name, value, urlAllowlist? }`.
+  Creates or updates an ad-hoc key.
+- `DELETE /_agent-native/secrets/adhoc/:name` — remove an ad-hoc key.
+
+### URL Allowlists
+
+Each ad-hoc key can have a URL allowlist — an array of origin URLs that
+restrict where the key's value can be sent. The check is origin-level
+(scheme + host + port). If no allowlist is configured, the key can be used
+with any URL.
+
+```ts
+// Creating a key with an allowlist
+POST /_agent-native/secrets/adhoc
+{
+  "name": "SLACK_WEBHOOK",
+  "value": "<SLACK_WEBHOOK_URL_FROM_SETTINGS>",
+  "urlAllowlist": ["https://hooks.slack.com"]
+}
+```
+
+### `${keys.NAME}` Substitution
+
+The `web-request` tool supports `${keys.NAME}` placeholders in the URL,
+headers, and body. Substitution happens server-side after the agent emits
+the tool call — the raw secret value never enters the agent's context.
+
+```ts
+import {
+  resolveKeyReferences,
+  validateUrlAllowlist,
+} from "@agent-native/core/secrets/substitution";
+
+// Resolve all ${keys.NAME} references in a string
+const { resolved, usedKeys } = await resolveKeyReferences(
+  "Bearer ${keys.API_TOKEN}",
+  "user",
+  "user@example.com",
+);
+
+// Validate a URL against a key's allowlist
+const allowed = validateUrlAllowlist(
+  "https://hooks.slack.com/services/<WORKSPACE>/<CHANNEL>/<SECRET>",
+  ["https://hooks.slack.com"],
+);
+```
+
+Key resolution falls back from user scope to workspace scope, so users can
+override shared keys without breaking automations that reference workspace
+defaults.
+
+## Dispatch Vault Access
+
+Dispatch workspaces have a vault access policy for workspace app credentials:
+
+- `all-apps` is the default. Every saved Dispatch vault key is available to
+  every workspace app; `sync-vault-to-app` pushes all vault keys to the target
+  app.
+- `manual` requires explicit per-app grants. Use
+  `create-vault-grant` / `grant-vault-secrets-to-app`, then
+  `sync-vault-to-app`.
+
+Use `get-vault-access-settings` before deciding whether to create grants, and
+use `set-vault-access-settings` only when the user asks to change the policy.
+
+### Key Files (ad-hoc)
+
+| File                                           | Purpose                                     |
+| ---------------------------------------------- | ------------------------------------------- |
+| `packages/core/src/secrets/substitution.ts`    | `resolveKeyReferences()`, `validateUrlAllowlist()` |
+| `packages/core/src/tools/fetch-tool.ts`        | `web-request` tool consuming key references |
+
+## Related skills
+
+- `onboarding` — the setup checklist that required secrets show up in.
+- `actions` — where you'll read secrets when calling third-party APIs.
+- `authentication` — session scoping; `scope: "user"` uses the session
+  email.
+- `security` — input validation and never logging secrets.
+- `automations` — ad-hoc keys power `${keys.NAME}` in automation web requests.