@agent-native/core 0.37.3 → 0.38.0

package/src/templates/workspace-core/.agents/skills/mvp-followup/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: mvp-followup
+description: >-
+  Use when asking what to do next after a feature pass while avoiding bloat and
+  checking for unfinished MVP work.
+metadata:
+  internal: true
+---
+
+# MVP Follow-Up
+
+## Rule
+
+Recommend or execute only closeout work that makes the current MVP more real,
+verified, documented, or shippable. Do not propose new product scope unless
+there is a clear blocker to the MVP working for real users.
+
+## Workflow
+
+1. Identify the current feature or thread outcome.
+2. Check for unfinished work in this order:
+   - failing or skipped verification
+   - unreviewed real-data pilot results
+   - pending review/proposals/approval queues
+   - docs that no longer match behavior
+   - unrelated dirty files that block full prep/ship hygiene
+3. Recommend the smallest next batch that closes those gaps.
+4. Explicitly skip tempting bloat: new integrations, dashboards, settings,
+   abstractions, or extra UI unless they directly unblock real use.
+5. If the user says "do it", run the closeout work in parallel where safe and
+   keep edits minimal.
+
+## Output Shape
+
+Lead with the concrete next step. Keep the list short. Separate:
+
+- **Do now**: validation, real pilot, docs, or bug fixes.
+- **Defer**: useful ideas that should wait for real user feedback.
+- **Blocker**: any specific user/manual action needed.
+
+## Verification Bias
+
+Prefer non-mutating checks when the worktree has unrelated dirty files. Use full
+`pnpm prep` only when it will not rewrite someone else's concurrent work.
+
+## Related Skills
+
+- `qa`
+- `ship`
+- `adding-a-feature`
+- `capture-learnings`

package/src/templates/workspace-core/.agents/skills/observability/SKILL.md

@@ -4,6 +4,8 @@ description: >-
   Agent observability, evals, feedback, and experiments. Use when adding
   observability dashboards, configuring trace capture, setting up evals,
   creating A/B experiments, or collecting user feedback on agent responses.
+metadata:
+  internal: true
 ---
 
 # Agent Observability
@@ -78,17 +80,25 @@ const criteria: EvalCriteria = {
 A/B testing with sticky user-level assignment:
 
 ```ts
-import { createExperiment, startExperiment } from "@agent-native/core/observability";
+import { insertExperiment, updateExperiment } from "@agent-native/core/observability";
 
-const exp = await createExperiment({
+const exp = {
+  id: crypto.randomUUID(),
   name: "sonnet-vs-haiku",
+  status: "draft" as const,
   variants: [
     { id: "control", weight: 50, config: { model: "claude-sonnet-4-6" } },
     { id: "treatment", weight: 50, config: { model: "claude-haiku-4-5-20251001" } },
   ],
   metrics: ["cost", "latency", "satisfaction"],
-});
-await startExperiment(exp.id);
+  assignmentLevel: "user" as const,
+  startedAt: null,
+  endedAt: null,
+  createdAt: Date.now(),
+};
+await insertExperiment(exp);
+// Move it to "running" when ready to start collecting assignments.
+await updateExperiment(exp.id, { status: "running" });
 ```
 
 The agent loop reads active experiments via `resolveActiveExperimentConfig()` and applies the variant's `model` override automatically. Assignment uses consistent hashing — same user always gets the same variant.

package/src/templates/workspace-core/.agents/skills/onboarding/SKILL.md

@@ -4,6 +4,8 @@ description: >-
   How to register user-facing setup steps (API keys, OAuth, connecting
   third-party services) for the sidebar setup checklist. Use when adding a
   feature that needs initial user configuration.
+metadata:
+  internal: true
 ---
 
 # Onboarding Steps
@@ -12,10 +14,19 @@ description: >-
 
 If a feature requires user-facing setup (API keys, OAuth, connecting a third-party service), register an onboarding step so it appears in the agent sidebar's setup checklist.
 
+Onboarding must point users to a secure credential path; it must never encode
+the credential value in source, docs, fixtures, prompts, or generated content.
+For API keys and service tokens, prefer `registerRequiredSecret()` from the
+`secrets` skill so the settings UI, encrypted storage, validation, and
+onboarding checklist stay in one place. For OAuth, check the scoped OAuth token
+store. Use deployment env vars only for deploy-level configuration, not
+per-user credentials.
+
 ## Registering a Step
 
 ```ts
 import { registerOnboardingStep } from "@agent-native/core/onboarding";
+import { hasOAuthTokens } from "@agent-native/core/oauth-tokens";
 
 registerOnboardingStep({
   id: "gmail",
@@ -31,7 +42,8 @@ registerOnboardingStep({
       payload: { url: "/_agent-native/google/auth-url" },
     },
   ],
-  isComplete: () => !!process.env.GMAIL_REFRESH_TOKEN,
+  isComplete: async (ctx) =>
+    ctx?.userEmail ? hasOAuthTokens("google", ctx.userEmail) : false,
 });
 ```
 

package/src/templates/workspace-core/.agents/skills/portability/SKILL.md

@@ -4,17 +4,19 @@ 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.
+metadata:
+  internal: true
 ---
 
 # Portability
 
 ## Rule
 
-**Never write code that only works on one database or one hosting platform.** Templates must run on any SQL database (SQLite, Postgres, D1, Turso, Supabase, Neon) and any Nitro deploy target (Node, Cloudflare, Netlify, Vercel, Deno, Lambda, Bun) without code changes.
+**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`:
+Use the dialect-agnostic schema helpers from `@agent-native/core/db/schema` for schemas and Drizzle's query builder for reads/writes:
 
 ```ts
 import {
@@ -47,6 +49,20 @@ export const meals = table("meals", {
 
 **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
@@ -55,7 +71,11 @@ export const meals = table("meals", {
 
 ### Never
 
-Never write SQLite-only syntax: `INSERT OR REPLACE`, `AUTOINCREMENT`, `datetime('now')`. When writing docs, say "SQL database" — not "SQLite".
+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
 
@@ -65,9 +85,11 @@ The server runs on **Nitro** with **H3** as the HTTP framework. Templates must b
 
 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 templates
+### 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.
 
-Files like `netlify.toml`, `wrangler.toml`, `vercel.json`, and `netlify/functions/` do not belong in template source. Platform configuration lives in CI/hosting dashboards or in deployment-specific repos.
+**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
 

package/src/templates/workspace-core/.agents/skills/qa/SKILL.md

@@ -5,6 +5,8 @@ description: >-
   apps end-to-end, finding and fixing bugs, or running a QA sweep. Invoke as
   /qa with optional --apps and --focus args.
 user-invocable: true
+metadata:
+  internal: true
 ---
 
 # QA Testing
@@ -19,6 +21,15 @@ Autonomous QA testing that spins up template apps, tests them with Playwright in
 /qa --focus "test form submission and compose"  # prioritize specific flows
 ```
 
+## Browser MCP Readiness
+
+QA can use the framework's built-in browser MCP capabilities instead of a hand-written `mcp.config.json`. The built-ins are off by default and are toggled through `/_agent-native/mcp/builtin`.
+
+- Prefer `browser-playwright` for automated QA sweeps: it runs `npx -y @playwright/mcp@0.0.75`.
+- Use `browser-chrome-devtools` only when the test specifically needs to attach to a live Chrome session. It runs `npx -y chrome-devtools-mcp@0.26.0 --autoConnect --no-usage-statistics` and requires Chrome 144+ with remote debugging enabled. Do not assume it signs into the user's Chrome profile.
+- Browser built-ins are exclusive per scope: enabling Chrome disables Playwright and enabling Playwright disables Chrome.
+- `computer-use` runs `npx -y computer-use-mcp@1.8.0` and is macOS-only.
+
 **Args:**
 
 - `--apps` — comma-separated app names (default: `mail,calendar,content,forms`)
@@ -39,14 +50,16 @@ Parse the user's invocation to determine:
 
 For each app, check if required credentials exist:
 
-| App      | Check                                          | Can test without? |
-|----------|-------------------------------------------------|-------------------|
-| forms    | No credentials needed                          | Yes               |
-| content  | No credentials needed (Notion is opt-in)       | Yes               |
-| calendar | `templates/calendar/.env` has GOOGLE_CLIENT_ID | Partially — local events work, Google sync won't |
-| mail     | `templates/mail/.env` has GOOGLE_CLIENT_ID     | Partially — UI renders, Gmail features won't |
+| App      | Check                                                    | Can test without? |
+| -------- | -------------------------------------------------------- | ----------------- |
+| forms    | No credentials needed                                    | Yes               |
+| content  | No credentials needed (Notion is opt-in)                 | Yes               |
+| calendar | `templates/calendar/.env` has `GOOGLE_CLIENT_ID` present | Partially — local events work, Google sync won't |
+| mail     | `templates/mail/.env` has `GOOGLE_CLIENT_ID` present     | Partially — UI renders, Gmail features won't |
 
-Read each app's `.env` file (if it exists) to check. If credentials are missing:
+Read each app's `.env` file (if it exists) only to check whether required names
+are present. Never print, copy, summarize, paste, or pass `.env` values into
+tester prompts, reports, screenshots, logs, or chat. If credentials are missing:
 
 - Still test the app — many features work without external APIs
 - Include in the tester's instructions: "No Google credentials found. Test local features. Flag any feature that crashes without credentials as 'needs credentials' rather than a bug."
@@ -79,7 +92,8 @@ For each app, read these files to understand what to test:
 
 1. `templates/<app>/app/routes/` or `templates/<app>/app/routes.ts` — discover all pages
 2. `templates/<app>/CLAUDE.md` — features, API routes, data model
-3. `templates/<app>/server/routes/api/` — API endpoints
+3. `templates/<app>/actions/` — domain operations the UI and agent share
+4. `templates/<app>/server/routes/api/` — route-only endpoints such as uploads, streaming, webhooks, and OAuth callbacks
 
 Combine with any `--focus` guidance to produce a test plan. The test plan is a numbered list of user-facing flows to verify. Example:
 
@@ -311,3 +325,5 @@ This is a known issue. The tester should:
 3. Check the server plugin that loads credentials
 4. Try to fix the credential detection logic
 5. If unfixable, report as "needs review" with details about what the app expects vs. what's configured
+
+Only report variable names and presence/absence. Do not include secret values.

package/src/templates/workspace-core/.agents/skills/real-time-collab/SKILL.md

@@ -4,6 +4,8 @@ description: >-
   Multi-user collaborative editing with Yjs CRDT and live cursors. Use when
   adding real-time collaborative editing to a template, debugging sync issues,
   or understanding how the agent and humans edit documents simultaneously.
+metadata:
+  internal: true
 ---
 
 # Real-Time Collaboration
@@ -23,11 +25,55 @@ Collaborative editing uses Yjs CRDT via TipTap. The agent and human users are eq
 ## Agent + Human Editing
 
 1. **Human edits** → TipTap → ySyncPlugin → Y.XmlFragment → `POST /_agent-native/collab/:docId/update`
-2. **Agent edits** → `edit-document` action → server search-replace → Y.XmlFragment mutation → poll update → all clients
+2. **Agent edits** → action edits canonical SQL content + bumps `updatedAt` → change-sync refetch → the open editor reconciles the new content into the live Y.Doc (see below) → poll update → all clients
 
-Both produce minimal Yjs operations that merge cleanly. Agent edits appear without destroying cursor position, selection, or undo history.
+Both produce Yjs operations that merge cleanly. Agent edits appear without destroying cursor position, selection, or undo history.
 
-The `edit-document` action uses surgical search-and-replace on Y.XmlText nodes — more efficient than regenerating the entire document.
+This is how content (documents) and slides now work. The agent does **not** push edits into Yjs in-process, and it does **not** call any `findCollabOrigin()` / localhost probe — that approach silently no-op'd on serverless (the action runs in a different process), so agent edits didn't show up live until the user navigated away and back. Nor does it search-and-replace inside existing Y.XmlText nodes, which could never create new block structure (lists, headings, tables). The peer-editor model below replaces both.
+
+## Agent Edits As A Real-Time Peer Editor
+
+The agent edits documents the same way a human collaborator does: its change lands in the shared Y.Doc, propagates to every connected client, and persists. It gets there without any in-process Yjs push from the action.
+
+**SQL is the durable source of truth for document body content.** The agent action edits the canonical content (e.g. `documents.content`) and bumps `updatedAt`. That's the whole server side — no localhost calls, no Yjs mutation from the action.
+
+**The open editor reconciles authoritative external content into the live Y.Doc.** The action's `updatedAt` bump flows through the change-sync system (see `real-time-sync`), which refetches the record. The editor applies the new content through its real markdown/HTML pipeline via `setContent`, so new block structure (lists, headings, tables) renders correctly and merges with concurrent human edits through the Yjs CRDT diff. The result: the agent's edit propagates to every connected client and persists, exactly like a human collaborator's edit.
+
+### The `updatedAt` gate
+
+The editor only adopts content that is genuinely **newer** than what it already reflects. An older-or-equal `updatedAt` is a lagging poll or a stale snapshot and is **ignored**.
+
+```ts
+// Pseudocode in the editor's reconcile effect
+if (loaded.updatedAt > lastAppliedUpdatedAt.current) {
+  applyAuthoritativeContent(loaded.content); // adopt
+  lastAppliedUpdatedAt.current = loaded.updatedAt;
+}
+// else: lagging poll / stale snapshot → ignore
+```
+
+**Why:** without the gate, a slightly-behind poll response re-applies old content right after the agent's edit, so the edit "reverts on the next poll" / "doesn't show until refresh" — the whack-a-mole we kept hitting. A **fresh mount or doc-switch has no baseline**, so it always adopts whatever content it loaded — which is why a manual refresh is always correct.
+
+### Lead-client election
+
+Exactly ONE connected client applies an authoritative snapshot into the shared Y.Doc; the rest receive it through normal Yjs sync. The lead is the present client with the lowest Yjs `clientID`, decided by the core helper:
+
+```ts
+import { isReconcileLeadClient } from "@agent-native/core/client";
+
+if (
+  loaded.updatedAt > lastAppliedUpdatedAt.current &&
+  isReconcileLeadClient(provider.awareness, ydoc.clientID)
+) {
+  applyAuthoritativeContent(loaded.content);
+}
+```
+
+**Why:** if every open editor independently diffed the same snapshot into the CRDT, each would insert the changed region at the same position, duplicating it N times (concurrent inserts → duplicated text). Electing one lead avoids that. The agent's awareness id (`AGENT_CLIENT_ID`, max int) can never win, and a client editing alone is always the lead. The election is deterministic across clients with no coordination round-trip.
+
+### v1 limitation
+
+A full-content reconcile is **last-writer-wins for the rare case** where a human has unsaved edits in the exact region the agent simultaneously rewrites — the agent's snapshot can clobber that in-flight human edit. Inline and structural edits in **different** regions merge fine through the CRDT; only same-region simultaneous rewrites are at risk.
 
 ## Enabling Collaboration
 
@@ -101,12 +147,12 @@ optimizeDeps: {
 ## Common Pitfalls
 
 - **Don't pass `content` as a TipTap prop** when Collaboration is enabled — Yjs owns the content. Set initial content via the Y.Doc instead.
-- **Don't use `editor.setContent()`** for agent edits — it bypasses Yjs and causes conflicts. Use the `search-replace` route or `edit-document` action.
+- **Don't call `editor.setContent()` ad hoc for agent edits.** The only sanctioned `setContent` is the editor's reconcile path described above — gated by `updatedAt` and guarded by `isReconcileLeadClient`. Calling it from elsewhere (e.g. on every poll, or from every client) re-applies stale content or duplicates the changed region across the CRDT.
 - **Add packages to `optimizeDeps`** — Vite won't pre-bundle Yjs packages correctly otherwise, causing runtime errors in dev.
 - **One `Y.Doc` per document** — Don't create multiple Y.Doc instances for the same document ID. Use the `useCollaborativeDoc` hook which caches by ID.
 
 ## Related Skills
 
-- `real-time-sync` — Polling infrastructure that delivers Y.Doc updates
-- `storing-data` — The `_collab_docs` table where Yjs state is persisted
-- `self-modifying-code` — Agent edits to collaborative documents go through `edit-document`, not raw SQL
+- `real-time-sync` — The change-sync system that delivers the `updatedAt` bump driving editor reconciliation; also `useReconciledState` for non-collaborative "copy a server value into local edit state" surfaces
+- `storing-data` — The `_collab_docs` table where Yjs state is persisted; SQL holds the canonical document body that the editor reconciles from
+- `self-modifying-code` — Agent edits to collaborative documents edit canonical SQL content, not raw Yjs

package/src/templates/workspace-core/.agents/skills/real-time-sync/SKILL.md

@@ -4,6 +4,8 @@ description: >-
   How to keep the UI in sync with agent changes via SSE plus polling fallback.
   Use when wiring query invalidation for new data models, debugging UI not
   updating, or understanding jitter prevention.
+metadata:
+  internal: true
 ---
 
 # Real-Time Sync
@@ -20,7 +22,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
 
 1. **Server** increments a version counter on every database write. In-process events stream through the authenticated `/_agent-native/events` endpoint.
 
-2. **Client** listens for SSE/poll events and updates per-source change counters:
+2. **Client** listens for sync events and updates per-source change counters:
 
    ```ts
    import { useDbSync } from "@agent-native/core";
@@ -47,9 +49,9 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
 
    For list/sidebar queries, use the same pattern — pass the counter into the queryKey of every list query you want to keep fresh.
 
-3. **Fallback** polling calls `/_agent-native/poll?since=N`. It runs every 2 seconds until SSE is connected, then relaxes to 15 seconds. If SSE is disabled or unavailable, polling continues at the normal cadence.
+4. **Fallback** polling calls `/_agent-native/poll?since=N`. It runs every 2 seconds until SSE is connected, then relaxes to 15 seconds. If SSE is disabled or unavailable, polling continues at the normal cadence.
 
-4. When the agent writes to the database, the version increments, SSE/polling detects it, and React Query refetches the affected queries.
+5. When the agent writes to the database, the version increments, SSE/polling detects it, and React Query refetches the affected queries.
 
 ## Don't
 
@@ -132,9 +134,9 @@ The `use-navigation-state.ts` hook sends the same `TAB_ID` in the `X-Request-Sou
 
 Without jitter prevention, a cycle occurs: the UI writes state, sync detects the change, the UI refetches and re-renders, potentially overwriting what the user is actively editing. With `ignoreSource`, the UI only reacts to changes from other sources (agent scripts, other browser tabs, other users).
 
-## Action Routes and Polling
+## Action Routes and Live Sync
 
-Action routes (`/_agent-native/actions/:name`) work with the same sync system. When a POST/PUT/DELETE action writes to the database, the version counter increments and `useDbSync` picks up the change. Frontend mutations via `useActionMutation` automatically invalidate `["action"]` query keys on success, triggering refetches of `useActionQuery` hooks.
+Actions work with the same sync system. When a mutating action writes to the database, the version counter increments and `useDbSync` picks up the change. Frontend mutations via `useActionMutation` automatically invalidate `["action"]` query keys on success, triggering refetches of `useActionQuery` hooks. Client components should call actions through those hooks, not with raw action-route fetches.
 
 For custom apps, the best out-of-the-box path is:
 
@@ -146,14 +148,13 @@ This avoids duplicate `/api/*` JSON CRUD routes and makes agent-created records
 
 ### Auto-emit on mutating actions
 
-The framework emits a poll event with `source: "action"` whenever any non-read-only action runs to completion — whether called via HTTP (`/_agent-native/actions/:name`) or as an agent tool call. Read-only actions (`http: { method: "GET" }` or explicit `readOnly: true`) are skipped.
+The framework emits a change event with `source: "action"` whenever any non-read-only action runs to completion — whether called via HTTP (`/_agent-native/actions/:name`) or as an agent tool call. Read-only actions (`http: { method: "GET" }` or explicit `readOnly: true`) are skipped.
 
 This means UIs don't need the agent to remember to call `refresh-screen` after every mutation. A listener like this (used in the `macros` template) will refresh after any mutating agent call:
 
 ```ts
 useDbSync({
   queryClient,
-  queryKeys: [],
   ignoreSource: TAB_ID,
   onEvent: (data) => {
     if (data.requestSource === TAB_ID) return;
@@ -165,9 +166,41 @@ useDbSync({
 
 `refresh-screen` remains available for unusual cases — e.g. the agent mutated data via a path the framework can't see (external system the app mirrors), or the agent wants to pass a `scope` hint for narrower invalidation.
 
+## Keeping Stateful Components In Sync
+
+The `useChangeVersion` / `useActionQuery` pattern above keeps the **query layer** fresh. But components that copy a server value into local React state still go stale on agent edits — refetching the query updates the prop, yet the local copy never re-adopts it. This is a recurring bug.
+
+**Never do this** for a value the agent can mutate:
+
+```ts
+// BUG: `title` is captured once and never re-reads the prop.
+const [title, setTitle] = useState(props.title);
+```
+
+When the agent renames the record, the query refetches, `props.title` updates, but the input still shows the stale value until the component remounts.
+
+**Derived-state surfaces (form fields, inline editors, popovers): use `useReconciledState`.** It re-adopts the authoritative external value when it changes, except while the user is actively editing that field — so agent mutations show up live without clobbering in-progress typing:
+
+```ts
+import { useReconciledState } from "@agent-native/core/client";
+
+// `active` = true while the user is editing this field (focused / dirty).
+const [title, setTitle] = useReconciledState(props.title, { active: isEditing });
+```
+
+**Collaborative rich-text editors are different** — they don't copy a value into `useState`. They reconcile authoritative SQL content into a shared Y.Doc under an `updatedAt` gate with lead-client election. See `real-time-collab` → "Agent edits as a real-time peer editor". Don't reach for `useReconciledState` for a Yjs-backed editor.
+
+| Surface | Keep it fresh with |
+| ------- | ------------------ |
+| React Query reads | `useChangeVersion` / `useActionQuery` (above) |
+| Local edit state copied from a server value (inputs, popovers, inline editors) | `useReconciledState(externalValue, { active })` |
+| Collaborative rich-text editor (Yjs) | `updatedAt`-gated reconcile + `isReconcileLeadClient` — see `real-time-collab` |
+
 ## Related Skills
 
-- **storing-data** — Application-state and settings are the data stores that sync via polling
+- **storing-data** — Application-state and settings are data stores that sync through change events
 - **context-awareness** — Navigation state writes use jitter prevention to avoid overwriting active edits
-- **actions** — Action routes auto-expose actions as HTTP endpoints; database writes trigger poll events
-- **self-modifying-code** — Agent code edits trigger poll events; rapid edits can cause event storms
+- **actions** — Mutating actions trigger change events
+- **client-methods** — Route details belong in helpers/hooks, not components
+- **self-modifying-code** — Agent code edits trigger change events; rapid edits can cause event storms
+- **real-time-collab** — Collaborative editors reconcile agent edits into a shared Y.Doc, driven by the same change-sync `updatedAt` bump

package/src/templates/workspace-core/.agents/skills/recurring-jobs/SKILL.md

@@ -4,6 +4,8 @@ description: >-
   Scheduled tasks the agent runs on a cron schedule. Use when a user asks for
   something recurring ("every morning", "daily", "weekly"), when creating or
   updating jobs, or when debugging the job scheduler.
+metadata:
+  internal: true
 ---
 
 # Recurring Jobs

package/src/templates/workspace-core/.agents/skills/secrets/SKILL.md

@@ -5,10 +5,24 @@ description: >-
   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.
+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
@@ -96,25 +110,24 @@ row is written — status is derived from `hasOAuthTokens("google")`.
 ## Reading a secret from an action
 
 ```ts
+import { z } from "zod";
 import { defineAction } from "@agent-native/core";
 import { readAppSecret } from "@agent-native/core/secrets";
-import { getSession } from "@agent-native/core/server";
+import { getRequestUserEmail } from "@agent-native/core/server";
 
 export default defineAction({
-  name: "transcribe-audio",
   description: "Transcribe an audio file with Whisper",
-  input: { fileUrl: "string" },
-  handler: async ({ fileUrl }, ctx) => {
-    const session = await getSession(ctx.event);
-    if (!session?.email) throw new Error("Not signed in");
+  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: session.email,
+      scopeId: email,
     });
-    // Env var wins if set (useful for hosted deployments).
-    const apiKey = process.env.OPENAI_API_KEY ?? stored?.value;
+    const apiKey = stored?.value;
     if (!apiKey) {
       throw new Error(
         "OPENAI_API_KEY is not set. Configure it in the sidebar settings.",
@@ -130,8 +143,10 @@ Rules:
 
 - **Never log the value.** The read layer enforces this server-side; your
   code must do the same.
-- **Check `process.env[key]` first.** Env vars win so ops teams can set keys
-  via deploy configuration without the user ever visiting the sidebar.
+- **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`.
@@ -187,7 +202,7 @@ with any URL.
 POST /_agent-native/secrets/adhoc
 {
   "name": "SLACK_WEBHOOK",
-  "value": "https://hooks.slack.com/services/T00/B00/xxxx",
+  "value": "<SLACK_WEBHOOK_URL_FROM_SETTINGS>",
   "urlAllowlist": ["https://hooks.slack.com"]
 }
 ```
@@ -208,12 +223,12 @@ import {
 const { resolved, usedKeys } = await resolveKeyReferences(
   "Bearer ${keys.API_TOKEN}",
   "user",
-  "owner@example.com",
+  "user@example.com",
 );
 
 // Validate a URL against a key's allowlist
 const allowed = validateUrlAllowlist(
-  "https://hooks.slack.com/services/T00/B00/xxxx",
+  "https://hooks.slack.com/services/<WORKSPACE>/<CHANNEL>/<SECRET>",
   ["https://hooks.slack.com"],
 );
 ```
@@ -222,6 +237,20 @@ 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                                     |