@agent-native/core 0.37.2 → 0.38.0

package/dist/templates/workspace-core/.agents/skills/security/SKILL.md

@@ -4,6 +4,8 @@ description: >-
   Secure coding practices for agent-native apps: input validation, SQL
   injection, XSS, secrets, data scoping, and auth. Use when writing any action,
   route, or component that touches user data or external input.
+metadata:
+  internal: true
 ---
 
 # Security
@@ -12,6 +14,25 @@ description: >-
 
 Use the framework's security primitives everywhere. Never bypass them.
 
+## Absolute Secrets Rule
+
+Never hardcode secret values or real private data. This applies to source code,
+docs, tests, fixtures, generated prompts, screenshots, seed data, and extension
+HTML just as much as production code.
+
+Do not paste or invent real-looking API keys, bearer tokens, OAuth refresh
+tokens, webhook URLs, signing secrets, private Builder/internal data, or customer
+data into the repo. Examples must use obvious placeholders such as
+`<OPENAI_API_KEY>`, `${keys.SLACK_WEBHOOK}`, `sk-test-example`, or
+`example.customer@example.com`. Test literals should be clearly fake and must
+not match real provider token formats when an `example` token will do.
+
+Credential values enter the system only through approved runtime channels:
+deployment env vars for deploy-level secrets, the encrypted `app_secrets` vault
+or `saveCredential` / `resolveCredential` for user/org/workspace API keys, and
+`oauth_tokens` for OAuth. Code and instructions may name the credential key
+(`OPENAI_API_KEY`), but must never contain the credential value.
+
 ## Input Validation
 
 Use `defineAction` with a Zod `schema:` for every action. The framework validates input automatically and returns clear 400 errors for HTTP callers and structured error results for agent tool calls.
@@ -51,10 +72,27 @@ await client.execute(`SELECT * FROM users WHERE id = '${id}'`);
 - For rich text editing, use TipTap (framework dependency).
 - For rendering markdown, use `react-markdown`.
 
+## SSRF
+
+Any server-side `fetch` of a user- or agent-controlled URL must go through the framework SSRF guard — a bare `fetch()` can be steered at cloud metadata (`169.254.169.254`), `localhost`, or internal services.
+
+```ts
+import { ssrfSafeFetch } from "@agent-native/core/extensions/url-safety";
+// Blocks private/internal targets, re-checks the resolved IP at connect time
+// (DNS rebinding), and re-validates every redirect hop.
+const res = await ssrfSafeFetch(userProvidedUrl, {}, { maxRedirects: 3 });
+```
+
+For a pre-flight-only check (e.g. before a streaming or one-shot fetch), use `isBlockedExtensionUrlWithDns(url)` plus `createSsrfSafeDispatcher()` from the same module, and set `redirect: "manual"`. Never let the default `fetch` follow redirects for an untrusted URL — a public URL can 30x into the private network.
+
 ## Secrets
 
 - OAuth tokens go in the `oauth_tokens` store via `saveOAuthTokens()`.
-- Never store secrets in `settings`, `application_state`, source code, or action responses sent to the client.
+- Per-user / per-org API keys go through `saveCredential` / `resolveCredential` (`@agent-native/core/credentials`) or the `app_secrets` vault. Both encrypt values at rest with AES-256-GCM (keyed by `SECRETS_ENCRYPTION_KEY`, falling back to `BETTER_AUTH_SECRET`; production refuses to start without one).
+- Never hand-roll secrets into `settings`, `application_state`, source code, or action responses sent to the client. The credential / vault APIs above are the only sanctioned stores.
+- Never commit real keys, tokens, webhook URLs, signing secrets, or private
+  Builder/customer data in examples or fixtures. Use placeholders that cannot be
+  mistaken for working credentials.
 
 ## User Credentials Are Per-User Data — Never `process.env`
 
@@ -65,6 +103,8 @@ import { resolveCredential } from "@agent-native/core/credentials";
 const apiKey = await resolveCredential("OPENAI_API_KEY", { userEmail, orgId });
 ```
 
+Values are encrypted at rest (AES-256-GCM, shared `secrets/crypto.ts`): `saveCredential` encrypts on write and `resolveCredential` decrypts on read, with a transparent fallback for legacy plaintext rows. The agent's raw `db-query` / `db-exec` tools also cannot read credential rows — they are excluded from the scoped `settings` view. To encrypt pre-existing rows in place, run `pnpm action db-migrate-encrypt-credentials` (idempotent, non-destructive; needs the same `SECRETS_ENCRYPTION_KEY` / `BETTER_AUTH_SECRET` as the app).
+
 On 2026-04-29 the previous one-arg `resolveCredential(key)` form fell back to `process.env[key]` and an unscoped global `settings` row, so every signed-in user inherited the deployment's credentials. Two guards now block this in CI (`pnpm prep`):
 
 - `scripts/guard-no-env-credentials.mjs` — bans `process.env.<KEY>` reads in `packages/core/src/credentials/`, `secrets/`, `vault/`, and `templates/*/server/{lib,routes/api}/credential*` paths, except for an explicit allowlist of deploy-level vars (`DATABASE_URL`, `BETTER_AUTH_SECRET`, `NETLIFY_*`, etc.). Per-line opt-out: `// guard:allow-env-credential — <reason>`.
@@ -82,6 +122,9 @@ Two more CI guards (also wired into `pnpm prep`) target the 2026-04 cross-tenant
 ## Auth
 
 - All actions are protected by the auth guard automatically.
+- Prefer actions for normal app data. Do not hand-write `/api/*` routes for
+  CRUD, data queries, or action re-exports just to add auth; action endpoints
+  already get auth and request context.
 - If you must create custom `/api/` routes, always call `getSession(event)` and reject requests without a session:
 
 ```ts
@@ -138,6 +181,8 @@ export default defineEventHandler(async (event) => {
 
 In production, the framework automatically restricts all agent SQL queries to the current user's data using temporary views. This is enforced at the SQL level — the agent cannot bypass it.
 
+The `db-query` / `db-exec` tools (and the extension SQL bridge, which shares the same path) reject schema-qualified table references like `public.<table>` or `main.<table>` — a qualified name resolves to the base table and would skip the temp view. Use bare table names; scoping is applied automatically.
+
 ### Per-User Scoping (`owner_email`)
 
 Every template table with user data **must** have an `owner_email` text column:
@@ -180,6 +225,10 @@ Run `pnpm action db-check-scoping` to verify. Use `--require-org` for multi-org
 - [ ] New action uses `defineAction` with a Zod `schema:`
 - [ ] No SQL string concatenation with user input
 - [ ] No `dangerouslySetInnerHTML` with user content
+- [ ] Server-side fetches of user/agent URLs use `ssrfSafeFetch`, not bare `fetch`
+- [ ] Secrets stored via `saveCredential` / the vault (encrypted), never raw in `settings` or responses
+- [ ] No hardcoded API keys, tokens, webhook URLs, signing secrets, real
+      credential-looking strings, private Builder/internal data, or customer data
 - [ ] New env vars in `.env` only, not committed
 - [ ] New user-data tables have `owner_email` column
 - [ ] Custom routes call `getSession` and reject unauthenticated requests

package/dist/templates/workspace-core/.agents/skills/self-modifying-code/SKILL.md

@@ -4,6 +4,8 @@ description: >-
   How the agent can modify the app's own source code. Use when the agent needs
   to edit components, routes, styles, or scripts, when designing UI for agent
   editability, or when deciding what the agent should and shouldn't modify.
+metadata:
+  internal: true
 ---
 
 # Self-Modifying Code
@@ -74,6 +76,6 @@ el.dataset.selectedId = selectedItem?.id || "";
 ## Related Skills
 
 - **storing-data** — Tier 1 modifications (data files) are the safest and most common
-- **scripts** — The agent can create or modify scripts to add new capabilities
+- **actions** — The agent can create or modify actions to add new capabilities
 - **delegate-to-agent** — Self-modification requests come through the agent chat
-- **real-time-sync** — Database writes trigger poll events to update the UI
+- **real-time-sync** — Database writes trigger change events to update the UI

package/dist/templates/workspace-core/.agents/skills/server-plugins/SKILL.md

@@ -4,6 +4,8 @@ description: >-
   Framework server plugins and the `/_agent-native/` route namespace. Use when
   adding a custom server plugin, deciding whether to create an `/api/` route vs
   an action, or debugging auto-mounted framework routes.
+metadata:
+  internal: true
 ---
 
 # Server Plugins & Framework Routes
@@ -29,9 +31,12 @@ All framework-level routes live under `/_agent-native/` to avoid collisions with
 ### Hard rule
 
 - **ALL framework routes go under `/_agent-native/`.**
-- Templates own `/api/*` for their domain routes.
+- Templates own `/api/*` only for route-only domain concerns such as uploads,
+  streaming, webhooks, OAuth callbacks, or non-JSON protocols.
 - Never put framework routes under `/api/`.
 - Never put template routes under `/_agent-native/` — that namespace is reserved.
+- Never create `/api/*` routes that only wrap, proxy, or re-export actions. Use
+  the existing `/_agent-native/actions/:name` endpoint or the React action hooks.
 
 ### Auto-mounted framework routes
 
@@ -64,6 +69,11 @@ For standard CRUD and data operations, use `defineAction` in `actions/` — the
 - Webhooks from external services
 - OAuth callbacks
 
+Before adding a route, inspect the existing action files. Reuse the action if
+it already encodes the business rule, or add a new action if the operation
+should be available to both the agent and the UI. A route whose implementation
+mostly calls an action is usually the wrong abstraction.
+
 The Nitro Vite plugin handles both `/api/` and `/_agent-native/` prefixes via file-based routing in `server/routes/`.
 
 ## Related Skills

package/dist/templates/workspace-core/.agents/skills/shadcn-ui/SKILL.md

@@ -5,6 +5,8 @@ description: >-
   components, forms, dialogs, menus, charts, sidebars, themes, registries, or
   any project with a components.json file.
 source: https://ui.shadcn.com/docs/skills
+metadata:
+  internal: true
 ---
 
 # shadcn/ui
@@ -57,6 +59,19 @@ This skill keeps shadcn/ui work project-aware. Components are source files in th
 - Do not add manual `z-index` to overlay primitives unless you are fixing a verified stacking bug.
 - Add custom colors as CSS variables in the existing Tailwind CSS file reported by shadcn info. For Tailwind v4, register variables with `@theme inline`.
 
+## Transitions And Motion
+
+shadcn's built-in component animations are the right level of polish — keep them. The goal is a snappy, clean UI, not a motionless one. Match shadcn's motion vocabulary; don't strip it and don't pile on decorative custom animation.
+
+- **Never remove or override a shadcn component's default animation.** `data-[state=open]:animate-in`, `data-[state=closed]:animate-out`, `fade-in/out`, `zoom-in/out`, `slide-in-from-*`, accordion height, the `tailwindcss-animate` utilities — these ship for a reason. Leave them as-is.
+- **Custom transitions are fine when they communicate a state change and match shadcn's feel.** Reuse the same vocabulary: short durations (~120–200ms), `ease-out`, opacity/transform only, gated on `data-[state=...]`. Examples that are good and welcome:
+  - A portaled custom popover/tooltip/sheet that fades + scales/slides in on `data-[state=delayed-open]` / `data-[state=closed]`, mirroring Radix's own content animation.
+  - A list row or toast that fades/slides in on mount and out on dismiss.
+  - A chevron/caret `rotate` on expand, a subtle `opacity`/`color` hover on an icon button, skeleton shimmer, a progress/height transition on a collapsible.
+  - Continuous, product-defining motion where it _is_ the experience (e.g. a multi-stage booking flow's stage transitions) — fine, and framer-motion is acceptable there.
+- **Avoid decorative, attention-seeking, or slow motion:** hand-rolled `duration-700` hero fade-ins, parallax, bouncing/spring entrances on ordinary content, animated gradients, staggered cascades on long lists, anything that delays the user seeing or acting on content. If an animation makes the UI feel slower, cut it.
+- Rule of thumb: if the motion clarifies what just changed and is over in well under a quarter-second, it's polish; if it's there to look impressive, it's bloat.
+
 ## Icons
 
 - Agent-native apps use `@tabler/icons-react`. Do not add `lucide-react` because a registry example used it.

package/dist/templates/workspace-core/.agents/skills/sharing/SKILL.md

@@ -5,6 +5,8 @@ description: >-
   (dashboards, documents, forms, decks, etc.). Use when making a resource
   table ownable, wiring list/read/update access checks, or dropping the
   standard share dialog into a template.
+metadata:
+  internal: true
 ---
 
 # Sharing — Private by Default, Explicit Share
@@ -187,7 +189,9 @@ The framework auto-mounts these actions in every template — no per-template bo
 | `list-resource-shares`     | `resourceType, resourceId`                                                     | Current visibility + all share grants.    |
 | `set-resource-visibility`  | `resourceType, resourceId, visibility`                                         | Change to `private` / `org` / `public`.  |
 
-Both the agent and the UI call these via the same endpoints.
+Both the agent and the UI use these same actions. The agent calls them as tools;
+UI code should use `ShareButton` / `ShareDialog` or the action client hooks
+instead of hand-writing route calls.
 
 ## Migration pattern for existing tables
 

package/dist/templates/workspace-core/.agents/skills/storing-data/SKILL.md

@@ -4,30 +4,52 @@ description: >-
   How to store application data in agent-native apps. All data lives in SQL.
   Use when adding data models, deciding where to store data, or reading/writing
   application data.
+metadata:
+  internal: true
 ---
 
 # Storing Data — SQL is the Source of Truth
 
 ## Rule
 
-All application data lives in **SQL** (SQLite locally, cloud database in production). The agent and UI share the same database. There is no filesystem dependency for data.
+All application data lives in **SQL** (SQLite locally, persistent database in production). The agent and UI share the same database. Do not store durable app data in the filesystem.
 
 ## How It Works
 
-Agent-native apps use SQLite via Drizzle ORM + `@libsql/client`. This works locally out of the box and upgrades seamlessly to cloud databases (Turso, Neon, Supabase, D1) by setting `DATABASE_URL`. **Local and production behave identically.**
+Agent-native apps use Drizzle ORM over the configured SQL backend. Local development works out of the box with a SQLite file at `data/app.db`; production and shared preview deploys need a persistent `DATABASE_URL` because container/serverless filesystems can reset. The code should behave the same across backends, but the local SQLite file is not durable once deployed.
+
+For app code, use Drizzle's schema/query DSL by default. Raw SQL is an escape hatch for additive migrations, health checks, or one-off maintenance, not the normal way to build features.
 
 ### Core SQL Stores (auto-created, available in all templates)
 
 | Store               | Purpose                                              | Access                                     |
 | ------------------- | ---------------------------------------------------- | ------------------------------------------ |
 | `application_state` | Ephemeral UI state (compose windows, navigation)     | `readAppState()` / `writeAppState()`       |
-| `settings`          | Persistent KV config (preferences, app settings)     | `getSetting()` / `setSetting()`            |
+| `settings`          | Persistent KV config (preferences, app settings)     | `getSetting()` / `putSetting()`            |
 | `oauth_tokens`      | OAuth credentials                                    | `@agent-native/core/oauth-tokens`          |
 | `sessions`          | Auth sessions                                        | `@agent-native/core/server`               |
 
 ### Domain Data (per-template)
 
-Define schema with Drizzle ORM in `server/db/schema.ts`. Get a database instance with `const db = getDb()` from `server/db/index.ts`. All queries are async.
+Define schema with the framework Drizzle helpers in `server/db/schema.ts`. Get a database instance with `const db = getDb()` from `server/db/index.ts`. All queries are async.
+
+```ts
+import { eq } from "drizzle-orm";
+import { table, text, integer, now } from "@agent-native/core/db/schema";
+
+export const tasks = table("tasks", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  completed: integer("completed", { mode: "boolean" })
+    .notNull()
+    .default(false),
+  createdAt: text("created_at").notNull().default(now()),
+});
+
+const rows = await db.select().from(tasks).where(eq(tasks.id, taskId));
+```
+
+Never import `sqliteTable` / `pgTable` or column helpers from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` in app templates. Use `@agent-native/core/db/schema` so the same schema can run against SQLite, Postgres, libSQL/Turso, D1, and other supported backends.
 
 | Template     | Tables                                        |
 | ------------ | --------------------------------------------- |
@@ -40,15 +62,15 @@ Define schema with Drizzle ORM in `server/db/schema.ts`. Get a database instance
 
 ### Agent Access
 
-The agent uses actions to read/write the database:
+The agent uses app-specific actions to read/write the database. Core DB scripts are for inspection and maintenance, not for implementing normal product behavior:
 
 - `pnpm action db-schema` — Show all tables, columns, types
 - `pnpm action db-query --sql "SELECT * FROM forms"` — Run SELECT queries
-- `pnpm action db-exec --sql "INSERT INTO ..."` — Run INSERT / UPDATE / DELETE / REPLACE. Use for short columns, multi-column writes, computed updates. For several related writes, prefer `--statements '[{"sql":"...","args":[...]}]'` so they run sequentially in one transaction. Schema changes are blocked; use reviewed additive migrations/startup code instead.
+- `pnpm action db-exec --sql "UPDATE ..."` — Last-resort ad-hoc maintenance for short columns, multi-column writes, or computed updates when no domain action exists. For several related writes, prefer `--statements '[{"sql":"...","args":[...]}]'` so they run sequentially in one transaction. Schema changes are blocked; use reviewed additive migrations/startup code instead.
 - `pnpm action db-patch --table <t> --column <c> --where "<clause>" --find "<old>" --replace "<new>"` — **Surgical search/replace on a large text column.** Sends the diff instead of re-transmitting the whole value, so it's dramatically more token-efficient than `db-exec UPDATE` when editing multi-kilobyte documents, slide HTML, dashboard/form JSON, etc. Targets exactly one row per call — narrow `--where` by primary key. Supports `--edits '[{find,replace},...]'` for batch edits and `--all` to replace every occurrence.
-- App-specific actions for domain operations (auto-exposed as HTTP endpoints) — **always prefer these over raw SQL when one exists.** They encode business rules, and for editor-backed tables (documents, slides) they also push live Yjs updates to open collaborative editors. `db-patch` is the generic fallback for tables without a dedicated edit action.
+- App-specific actions for domain operations — **always prefer these over raw SQL when one exists.** They encode business rules, power the client action hooks, and for editor-backed tables (documents, slides) also push live Yjs updates to open collaborative editors. `db-patch` is the generic fallback for tables without a dedicated edit action.
 
-**How to choose between `db-exec UPDATE` and `db-patch`:**
+**For one-off maintenance, how to choose between `db-exec UPDATE` and `db-patch`:**
 
 | Scenario                                                       | Use          |
 | -------------------------------------------------------------- | ------------ |
@@ -65,27 +87,29 @@ All of these honor the per-user / per-org data scoping — you can't read or wri
 
 ### Frontend Access
 
-The frontend calls actions via their auto-mounted HTTP endpoints using React Query hooks:
+The frontend calls actions using React Query hooks from the client API. The framework owns the HTTP transport behind these hooks, so components should not call action routes with raw `fetch`.
 
 ```ts
 import { useActionQuery, useActionMutation } from "@agent-native/core/client";
 
-// Read data (calls GET /_agent-native/actions/list-meals)
-const { data } = useActionQuery<Meal[]>("list-meals", { date: "2025-01-01" });
+// Read data
+const { data } = useActionQuery("list-meals", { date: "2025-01-01" });
 
-// Write data (calls POST /_agent-native/actions/log-meal)
-const { mutate } = useActionMutation<Meal>("log-meal");
+// Write data
+const { mutate } = useActionMutation("log-meal");
 ```
 
 Actions are the **preferred way** for the frontend to access data. You rarely need custom `/api/` routes — only for file uploads, streaming, webhooks, or OAuth callbacks.
 
-### Cloud Deployment
+### Production / Cloud Deployment
+
+Local SQLite works out of the box for development. To deploy to production or any environment where data must survive restarts:
 
-Local SQLite works out of the box. To deploy to production with a cloud database:
+1. Set `DATABASE_URL` to a persistent SQL database.
+2. Set `DATABASE_AUTH_TOKEN` only when the provider requires a separate token, such as Turso/libSQL.
+3. No code changes should be needed when the schema and queries stay portable.
 
-1. Set `DATABASE_URL` (e.g. `libsql://your-db.turso.io`)
-2. Set `DATABASE_AUTH_TOKEN` for auth
-3. No code changes needed — `@libsql/client` handles both local and remote
+Turso is one valid option, not the required option. Common choices include Neon or Supabase Postgres, Turso/libSQL, plain Postgres, durable SQLite, Cloudflare D1 bindings, and managed platform SQL environments when available.
 
 ### Real-time Sync
 
@@ -94,6 +118,8 @@ Polling streams database changes to the UI. When the agent writes to the databas
 ## Do
 
 - Use Drizzle ORM for structured domain data (forms, bookings, documents)
+- Use Drizzle query builder methods (`select`, `insert`, `update`, `delete`) and portable operators from `drizzle-orm` (`eq`, `and`, `or`, `inArray`, `desc`, etc.) for app reads/writes
+- Use framework schema helpers from `@agent-native/core/db/schema`, not dialect-specific Drizzle imports
 - Use the `settings` store for app configuration and user preferences
 - Use `application-state` for ephemeral UI state that the agent and UI share
 - Use `oauth-tokens` for OAuth credentials
@@ -107,6 +133,8 @@ Polling streams database changes to the UI. When the agent writes to the databas
 - Don't store app state in localStorage, sessionStorage, or cookies (except for UI-only preferences like sidebar width)
 - Don't keep state only in memory (server variables, global stores)
 - Don't use Redis or any external state store for app data
+- Don't implement product features with raw SQL or `getDbExec()` when Drizzle can express the query
+- Don't write SQLite-only or Postgres-only SQL in app code
 - Don't interpolate user input directly into SQL queries — use Drizzle ORM's query builder
 
 ## Security
@@ -128,5 +156,6 @@ When adding a new data model or feature, also consider what navigation and selec
 
 - **context-awareness** — How to expose navigation and selection state via application-state
 - **real-time-sync** — Set up polling so the UI updates when the database changes
-- **actions** — Create actions with `defineAction` to query the database (auto-exposed as HTTP endpoints)
+- **actions** — Create actions with `defineAction` to query the database
+- **client-methods** — Keep route details behind named client helpers/hooks
 - **self-modifying-code** — The agent can also modify the app's source code

package/dist/templates/workspace-core/.agents/skills/tracking/SKILL.md

@@ -4,6 +4,8 @@ description: >-
   Server-side analytics tracking with pluggable providers. Use when adding
   analytics events, registering custom tracking providers, or configuring
   built-in providers (PostHog, Mixpanel, Amplitude, Webhook).
+metadata:
+  internal: true
 ---
 
 # Tracking
@@ -28,7 +30,7 @@ Fire an analytics event.
 ```ts
 import { track } from "@agent-native/core/tracking";
 
-track("meal.logged", { mealName: "Salad", calories: 350 }, { userId: "owner@example.com" });
+track("meal.logged", { mealName: "Salad", calories: 350 }, { userId: "user@example.com" });
 ```
 
 ### `identify(userId, traits?)`
@@ -38,7 +40,7 @@ Identify a user with traits. Forwarded to providers that support it.
 ```ts
 import { identify } from "@agent-native/core/tracking";
 
-identify("owner@example.com", { plan: "pro", company: "Example Co" });
+identify("user@example.com", { plan: "pro", company: "ExampleCo" });
 ```
 
 ### `registerTrackingProvider(provider)`
@@ -90,6 +92,7 @@ Template roots call `configureTracking()` once during app startup. That installs
 - Fires on initial load, `history.pushState`, `history.replaceState`, and `popstate`
 - De-dupes repeated events for the same URL
 - Includes `url`, `path`, `hostname`, `referrer`, `title`, `navigation_type`, `app`, and inferred `template`
+- Includes LLM connection context on browser events when known: `llm_connection` (`builder`, `anthropic`, `openai`, etc.), `llm_engine`, `llm_model`, `llm_connection_source`, and `llm_connection_configured`
 - Does not send first-party events from localhost/local dev
 
 ### Visitor identity (`anonymousId` + `sessionId`)
@@ -106,7 +109,8 @@ Other framework-level baseline events:
 
 - `session status` from `useSession()`, with `signed_in`
 - `signup` from Better Auth user creation, with `auth_provider` and `auth_user_id`
-- `builder connect started`, `builder connect succeeded`, `builder connect failed`, `builder disconnect succeeded`, and `builder disconnect failed` from the Builder connection routes
+- `builder connect clicked` and `builder connect popup blocked` from browser Connect Builder CTAs
+- `builder connect started`, `builder connect succeeded`, `builder connect failed`, `builder disconnect succeeded`, and `builder disconnect failed` from the Builder connection routes, with LLM connection context when resolvable
 
 For new lifecycle events, call `track()` server-side when the server is the source of truth, and `trackEvent()` client-side only for browser interactions.
 

package/dist/templates/workspace-core/.agents/skills/voice-transcription/SKILL.md

@@ -6,6 +6,8 @@ description: >-
   Voice Transcription settings section. Covers transcription-source routing,
   cleanup routing, Google realtime gating, and the voice transcription
   application-state keys.
+metadata:
+  internal: true
 ---
 
 # Voice Transcription
@@ -36,8 +38,8 @@ that renders `TiptapComposer`.
 Settings must keep these as separate choices:
 
 - **Live transcription source**: `mac-native`, `google-realtime`, or `batch`.
-- **AI cleanup**: independent off/on toggle. Cleanup uses Builder Gemini first
-  when hosted Gemini is configured, then BYOK Gemini (`GEMINI_API_KEY`).
+- **AI cleanup**: independent off/on toggle. Cleanup uses managed Gemini first
+  when a managed AI services connection is configured, then BYOK Gemini (`GEMINI_API_KEY`).
   Gemini cleanup/title/summary generation is not a live STT source.
 
 `application_state["voice-transcription-prefs"]` stores
@@ -49,8 +51,8 @@ is still written for old clients and batch provider preferences:
 | `mac-native`      | Native macOS/Tauri speech path; web clients normalize to browser-native where needed | No                           |
 | `google-realtime` | Dedicated WebSocket → Google Speech-to-Text gRPC `StreamingRecognize` path | `GOOGLE_APPLICATION_CREDENTIALS` |
 | `batch`           | Upload audio after stop through the existing batch route       | Builder/Gemini/Groq/OpenAI depending on fallback |
-| `auto` provider   | Existing batch fallback chain                                  | Any configured batch provider |
-| `builder-gemini`  | Builder Gemini Flash-Lite batch/cleanup preference             | hosted Gemini provider connected |
+| `auto` provider   | Browser SpeechRecognition when supported; server batch fallback chain otherwise | No key needed in browsers that support SpeechRecognition |
+| `builder-gemini`  | Managed Gemini Flash-Lite batch/cleanup preference             | Managed AI services account connected |
 | `gemini`          | Direct Google Gemini BYOK batch/cleanup preference             | `GEMINI_API_KEY`             |
 | `groq`            | Groq Whisper batch preference                                  | `GROQ_API_KEY`               |
 | `openai`          | OpenAI Whisper batch preference                                | `OPENAI_API_KEY`             |
@@ -58,13 +60,18 @@ is still written for old clients and batch provider preferences:
 
 Default behavior:
 
-- The shared web settings/composer default to Batch / `auto`.
+- The shared web settings/composer default to Batch / `auto`. In `auto` mode,
+  `useVoiceDictation` uses `startBrowser()` (Web Speech API, no key required,
+  incremental streaming) when the browser supports `SpeechRecognition`. It only
+  falls back to the MediaRecorder → server upload path when `SpeechRecognition`
+  is not available (e.g. Firefox). This means dictation works out of the box in
+  Chrome, Edge, and Safari without any API key configuration.
 - Dedicated macOS Tauri-native surfaces may save `mac-native`, but do not
   assume the shared React settings default to it.
 - Old stored `builder` values are treated as `builder-gemini`.
 - Old stored `browser` values are treated as `mac-native`.
 - Saved `google-realtime` preferences must never hit `/_agent-native/transcribe-voice`. They go through the dedicated session bridge `POST /_agent-native/transcribe-stream/session`, which mints an opaque ai-services websocket session and keeps the Google service-account JSON off the client.
-- In the current bridge, the Google option is only actually ready when both the user's `GOOGLE_APPLICATION_CREDENTIALS` secret exists and Builder is connected, because the framework mints the managed ai-services session with Builder auth before streaming begins.
+- In the current bridge, the Google option is only actually ready when both the user's `GOOGLE_APPLICATION_CREDENTIALS` secret exists and a managed AI services connection is configured, because the framework mints the managed ai-services session before streaming begins.
 
 ## Where the pieces live