@agent-native/core 0.37.2 → 0.38.0

package/src/templates/workspace-core/.agents/skills/adding-a-feature/SKILL.md

@@ -3,6 +3,8 @@ name: adding-a-feature
 description: >-
   The four-area checklist every new feature must complete. Use when adding any
   feature, integration, or capability to ensure the agent and UI stay in parity.
+metadata:
+  internal: true
 ---
 
 # Adding a Feature — The Four-Area Checklist
@@ -21,7 +23,7 @@ When you add a new feature, work through these four areas in order:
 
 ### 1. UI Component
 
-Build the user-facing interface — a page, component, dialog, or route. Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` to call actions for data fetching and mutations — you rarely need custom `/api/` routes.
+Build the user-facing interface — a page, component, dialog, or route. Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` to call actions for data fetching and mutations. Do not create a custom REST endpoint just so React can call action-backed data; the action endpoint already exists.
 
 **Auto-refresh on agent writes is non-negotiable** — when the agent mutates data, the UI must reflect the change without a manual refresh. There are two paths, and you must pick the right one:
 
@@ -44,12 +46,45 @@ Build the user-facing interface — a page, component, dialog, or route. Use `us
 
 ### 2. Action
 
-Create an action in `actions/` using `defineAction`. This serves double duty: the agent calls it as a tool, and the framework auto-exposes it as an HTTP endpoint at `/_agent-native/actions/:name` for the UI to call. Set `http: { method: "GET" }` for read actions, leave default for writes, or set `http: false` for agent-only actions like `navigate` and `view-screen`.
+Create an action in `actions/` using `defineAction`. This serves double duty: the agent calls it as a tool, and the UI calls it through `useActionQuery` / `useActionMutation` while the framework owns the HTTP transport. Set `http: { method: "GET" }` for read actions, leave default for writes, or set `http: false` for agent-only actions like `navigate` and `view-screen`.
+
+Before adding a new route or endpoint, inspect the existing actions. Reuse an
+action if it already covers the business operation, extend it if the shared
+contract is incomplete, or create a new `defineAction` if the agent and UI both
+need the capability. Do not add pass-through `/api/*` routes that re-export
+actions. If client code needs a new framework/app route, expose a named helper
+or hook first and use that helper from components and docs.
+
+For provider-backed analysis/query/reporting integrations, do not turn every
+provider endpoint or filter into a rigid action. Prefer the shared
+`provider-api-catalog` / `provider-api-docs` / `provider-api-request` pattern
+from `@agent-native/core/provider-api`, then add narrow convenience actions only
+for workflows that truly deserve a first-class shortcut.
+
+If the feature needs credentials, design the credential path in the same change.
+Never hardcode API keys, tokens, webhook URLs, signing secrets, private
+Builder/internal data, or customer data in the action, UI, seed data, fixtures,
+docs, prompts, or generated extension/app content. Register required secrets,
+use OAuth helpers, or read scoped values from the vault/credential store.
+
+**If the action produces or lists a navigable resource**, add a `link` builder that returns `{ url: buildDeepLink({ app, view, params }), label }`. External coding agents and MCP hosts (Claude / ChatGPT / Claude Code / Cowork / Codex, over MCP/A2A) then surface an "Open in … →" deep link that drops the user back into the running UI focused on the record — for free. If a compatible MCP host should render an inline review/edit surface, also add `mcpApp` with `embedApp()` so the action embeds the real React app route instead of a one-off HTML UI. The `link` builder and `mcpApp` metadata must be pure and synchronous (no I/O). Any external-agent read/ingest action must be `http: { method: "GET" }` + `readOnly: true` + `publicAgent: { expose: true, readOnly: true, requiresAuth: true }`. See the `external-agents` skill.
 
 ### 3. Skills / Instructions
 
 Update `AGENTS.md` and/or create a skill in `.agents/skills/` if the feature introduces patterns the agent needs to know. At minimum, add the new actions to the action table in the template's `AGENTS.md`.
 
+Reusable actions are part of the app contract, not just implementation detail. When an action is useful outside one screen, update agent instructions in the same change so app agents know when to call it, which arguments matter, and what output to preserve. If the capability is workflow-heavy, cross-app, provider-backed, or has a non-obvious sequence of actions, add or update a skill instead of burying the behavior in one long `AGENTS.md` paragraph.
+
+Instruction examples may name secret keys like `SLACK_WEBHOOK`, but must use
+placeholders such as `${keys.SLACK_WEBHOOK}` or `<SLACK_WEBHOOK>`. Do not paste
+real keys, internal data, or customer data into instructions as examples.
+
+For app-backed skills, declare skill visibility in the app-skill manifest:
+
+- `internal` — only the app's own agents should use it.
+- `exported` — marketplace installs receive it, but the app does not need it loaded internally.
+- `both` — shared between the app's internal agents and exported marketplace bundles.
+
 ### 4. Application State Sync
 
 Expose navigation and selection state so the agent knows what the user is looking at. Write to the `navigation` app-state key on route changes. Update the `view-screen` action to fetch relevant data for the new feature. Add a `navigate` command if the agent needs to open the new view.
@@ -100,7 +135,10 @@ See the "Client-Side Routing" section in the root `CLAUDE.md` for full details.
 - **Per-route `<AppLayout>` wrappers** — Every route file wraps its content in `<AppLayout>` or `<Layout>`. React sees a different component at the outlet on each nav and unmounts the whole shell, causing the agent sidebar to reload on every click. Mount the shell once above `<Outlet />` (root.tsx or `_app.tsx` pathless layout).
 - **UI without actions** — The user can create forms but the agent cannot. The agent says "I don't have access to that" when it should be able to do it.
 - **Actions without AGENTS.md** — The actions exist but the agent doesn't know about them because they're not documented. The agent reinvents solutions instead of using the actions.
-- **Duplicate API routes** — Creating `/api/` routes for operations that actions already handle. Actions are auto-exposed as HTTP endpoints — use `useActionQuery`/`useActionMutation` instead.
+- **Duplicate API routes** — Creating `/api/` routes for operations that actions already handle, including pass-through routes that just call or repackage an action. Use `useActionQuery`/`useActionMutation` instead.
+- **Raw client route calls** — Teaching or adding `fetch("/_agent-native/...")`,
+  `fetch(agentNativePath(...))`, or template `/api/*` calls in components for
+  normal app work. Add a named client helper/hook and call that instead.
 - **Features without app-state** — The agent cannot see that the user is looking at a specific form, email, or chart. It asks "which one?" instead of acting on the current selection.
 - **Actions without UI** — The agent can do something the user cannot. This is less common but still breaks parity.
 
@@ -113,6 +151,9 @@ After completing all four areas, verify:
 3. Does `pnpm action view-screen` show the relevant state when the user is using the feature?
 4. Can the agent navigate to the feature view via the `navigate` action?
 5. Is the feature documented in AGENTS.md with action names and args?
+6. Are credentials and sensitive data supplied only through approved runtime
+   channels, with no hardcoded real keys, tokens, webhook URLs, Builder/internal
+   data, or customer data?
 
 ## One more area — sharing
 
@@ -125,6 +166,7 @@ TL;DR: spread `ownableColumns()` into the resource table, pair it with `createSh
 - **sharing** — How to make a new resource ownable (private by default, share with users/orgs/public)
 - **context-awareness** — How to expose UI state to the agent (area 4 in detail)
 - **actions** — How to create actions with `defineAction` and the `http` option (area 2 in detail)
+- **external-agents** — Add a `link` builder so external agents (MCP/A2A) get an "Open in … →" deep link
 - **create-skill** — How to create skills for new patterns (area 3 in detail)
 - **storing-data** — Where to store the feature's data
 - **real-time-sync** — How the UI stays in sync when the agent writes data

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

@@ -4,6 +4,8 @@ description: >-
   Triage feedback docs or pasted feedback into bugs to fix, UX suggestions to
   propose, unclear questions, and skipped noise; verify bugs, check Sentry when
   relevant, and keep UI changes minimal.
+metadata:
+  internal: true
 ---
 
 # Address Feedback

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

@@ -4,6 +4,8 @@ description: >-
   How auth works in agent-native apps. Use when wiring login/signup,
   configuring auth modes, setting up organizations, protecting routes, or
   debugging session issues.
+metadata:
+  internal: true
 ---
 
 # Authentication
@@ -20,7 +22,7 @@ Auth is powered by **Better Auth** with account-first design. Every new user cre
 | **Production (default)**  | Better Auth with email/password + social providers (Google, GitHub). Organizations built in.                                             |
 | **`AUTH_MODE=local`**     | **Not** a browser auth bypass, and never returns `local@localhost`. It only affects CLI/agent identity: it lets `pnpm action` / the local agent loop auto-bind to the single real signed-in dev user from the `sessions` table (see `scripts/dev-session.ts`). Browser login is unchanged. |
 | **`AUTH_SKIP_EMAIL_VERIFICATION=1`** | QA/preview escape hatch for real email/password accounts. Signup skips email verification and does not send the signup verification email. Local dev/test skips verification by default; set `AUTH_SKIP_EMAIL_VERIFICATION=0` only when testing verification itself. Use `+qa` emails for test accounts. |
-| **`ACCESS_TOKEN` / `ACCESS_TOKENS`** | Simple token-based auth for production deployments.                                                                           |
+| **`ACCESS_TOKEN` / `ACCESS_TOKENS`** | Static bearer fallback for MCP/connect clients that cannot use OAuth. Not browser auth and never a token login page.         |
 | **`AUTH_DISABLED=true`**  | Skip auth entirely (for apps behind infrastructure-level auth like Cloudflare Access).                                                   |
 | **Custom**                | Pass your own `getSession` to `autoMountAuth(app, { getSession })`.                                                                     |
 
@@ -31,6 +33,22 @@ Auth is powered by **Better Auth** with account-first design. Every new user cre
 > When there is no session, **throw or return 401** — never substitute a
 > sentinel. Enforced by `scripts/guard-no-localhost-fallback.mjs`.
 
+## Remote MCP OAuth
+
+Every app's `/_agent-native/mcp` endpoint is also a standard protected MCP
+resource. OAuth-capable hosts connect with the remote MCP URL only, receive a
+`WWW-Authenticate` challenge, discover `/.well-known/oauth-protected-resource`
+and `/.well-known/oauth-authorization-server`, dynamically register a public
+client, and complete authorization-code + PKCE at
+`/_agent-native/mcp/oauth/authorize` / `/_agent-native/mcp/oauth/token`.
+Access tokens are audience-bound to the exact MCP URL and carry user/org
+identity plus `mcp:read`, `mcp:write`, and/or `mcp:apps`; refresh tokens are
+stored hashed and rotate. Keep `ACCESS_TOKEN` and `agent-native connect` for
+local stdio proxying and fallback clients. The CLI
+uses the OAuth-native URL-only entry for Claude Code/Claude Code CLI by
+default; use the Connect page or `agent-native connect --token <token>` when a
+client needs explicit bearer headers.
+
 ## Local → Real Account Migration
 
 Upgrading from `local@localhost` to a real account preserves SQL-backed workspace data. The built-in migration moves `application_state`, user-scoped `settings`, `oauth_tokens`, and any template table that uses `owner_email`.
@@ -39,9 +57,9 @@ Templates with legacy global settings can provide `POST /api/local-migration` fo
 
 ## Organizations
 
-Better Auth's organization plugin is built in. Every app supports creating orgs, inviting members, and role-based access (owner/admin/member).
+Organizations are **framework-managed**, not handled by Better Auth's organization plugin (which is intentionally NOT registered). Org data lives in the framework's own `organizations`, `org_members`, and `org_invitations` tables. Every app supports creating orgs, inviting members, and role-based access (owner/admin/member).
 
-The active org flows automatically: `session.orgId` → `AGENT_ORG_ID` → SQL scoping (see `security` skill).
+The active org flows automatically: `session.orgId` — resolved by `getOrgContext` from `org_members` plus the user's `active-org-id` setting (_not_ from a Better Auth session field) — → `AGENT_ORG_ID` → SQL scoping (see `security` skill).
 
 **If your template requires an org to function** (data is scoped by `organization_id`, core features can't run without one), set `AUTO_CREATE_DEFAULT_ORG=1` in your `.env`. The framework will auto-create a default org (named after the user) on first login when no memberships exist. This happens inside `getOrgContext` — no template integration needed.
 
@@ -55,13 +73,27 @@ Set `A2A_SECRET` (same value) on all apps that must verify each other's identity
 - Inbound calls are verified cryptographically
 - Without `A2A_SECRET`, A2A calls are unauthenticated (fine for local dev)
 
+## Cross-App SSO (Dispatch identity hub)
+
+Each hosted `*.agent-native.com` app has its **own user store**, so "sign in once" is identity federation, not a shared cookie. **Dispatch is the identity authority.**
+
+- **Opt-in per app via one env var:** set `AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com` and the app shows a "Sign in with Agent-Native" option. **Unset = zero behavior change** — the whole path is dormant. Reversible at any time.
+- **Flow:** app → `GET <hub>/_agent-native/identity/authorize?app=&redirect_uri=&state=` → user logs in at Dispatch → 302 back with a short-lived (`≤5min`) `A2A_SECRET`-signed identity JWT (`sub`/`email`/`name`/`org_domain`/`scope:"identity"`). Strict `redirect_uri` allowlist (`*.agent-native.com` + localhost). App verifies the token, **JIT-links strictly by verified email** (existing same-email user → reused unchanged; new email → created), then mints a normal local session.
+- **Invariant (do not break):** identity rows are only ever **added** — never modified, renamed, or deleted. Enabling SSO logs users out, but they always log back into the **same email-matched account with data intact**. Email is the only thing that crosses the trust boundary; the app never trusts a user id, role, or org from the wire.
+- **Canary rollout:** deploy with the env unset everywhere (no-op) → set it on **one** app (mail) only → verify (logout → SSO → Dispatch → back to the same pre-existing account, data intact, direct logins still work) → expand app-by-app → rollback = unset the env on that app's deploy (instant, no data change).
+
+Full runbook + flow detail: [Cross-App SSO doc](/docs/cross-app-sso).
+
 ## Builder Browser Access
 
 Apps can connect to Builder via the `cli-auth` flow and persist shared browser credentials in `.env`. Agents then use the built-in `get-browser-connection` tool to provision a real browser session via AI Services.
 
 ## Protecting Custom Routes
 
-Actions are auto-protected. For custom `/api/` routes:
+Actions are auto-protected. Do not create custom `/api/` routes for normal
+CRUD, data queries, or action-backed operations; use `defineAction` and the
+auto-mounted action endpoint instead. If a route-only concern forces a custom
+route:
 
 ```ts
 import { getSession } from "@agent-native/core/server";
@@ -93,3 +125,4 @@ Bookmarked private paths already work without any plumbing — the framework's l
 
 - `security` — Data scoping, SQL injection, secrets
 - `actions` — Auto-protected by the auth guard
+- [Cross-App SSO doc](/docs/cross-app-sso) — Dispatch identity hub, federation flow, canary runbook

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

@@ -4,6 +4,8 @@ description: >-
   Event-triggered and schedule-triggered automations with natural-language
   conditions. Use when creating automations, wiring events, or understanding
   how triggers fire.
+metadata:
+  internal: true
 ---
 
 # Automations
@@ -42,7 +44,7 @@ event: calendar.booking.created
 condition: "attendee email ends with @example.com"
 mode: agentic
 domain: calendar
-createdBy: owner@example.com
+createdBy: user@example.com
 runAs: creator
 ---
 
@@ -109,7 +111,7 @@ emit("calendar.booking.created", {
   bookingId: "abc",
   attendeeEmail: "jane@co.com",
   startTime: "2025-01-15T10:00:00Z",
-}, { owner: "owner@example.com" });
+}, { owner: "user@example.com" });
 ```
 
 ### Built-in Events
@@ -134,7 +136,7 @@ emit("calendar.booking.created", {
 
 ## Condition Evaluator
 
-When an automation has a `condition`, the dispatcher calls Haiku (claude-haiku-4-5) to classify whether the event payload satisfies the condition. This is a yes/no classification, not a generation task.
+When an automation has a `condition`, the dispatcher calls the configured fast/classification model to classify whether the event payload satisfies the condition. This is a yes/no classification, not a generation task. The exact model ID lives in `condition-evaluator.ts`.
 
 - Empty or missing condition = unconditional (always fires).
 - Results are memoized (SHA-256 of condition + payload) with a 5-minute TTL and 500-entry LRU cache.
@@ -149,6 +151,9 @@ Automations use the `web-request` tool for outbound HTTP. It supports `${keys.NA
 - Each key can have a URL allowlist that restricts which origins the key can be sent to.
 - `resolveKeyReferences()` resolves placeholders, falling back from user scope to workspace scope.
 - `validateUrlAllowlist()` checks the resolved URL against per-key allowlists (origin-level matching).
+- Automation definitions, examples, event payloads, and prompts must not
+  hardcode real API keys, webhook URLs, tokens, private Builder/internal data, or
+  customer data. Use `${keys.NAME}` and synthetic `example.com` identities.
 
 ## UI
 
@@ -163,7 +168,7 @@ Agent flow:
 1. Calls `manage-automations` with `action=list-events` to find `calendar.booking.created`.
 2. Confirms the plan with the user.
 3. Calls `manage-automations` with `action=define`:
-   - `name`: `slack-on-builder-booking`
+   - `name`: `slack-on-example-booking`
    - `trigger_type`: `event`
    - `event`: `calendar.booking.created`
    - `condition`: `attendee email ends with @example.com`

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

@@ -5,6 +5,8 @@ description: >-
   user gives feedback, shares preferences, corrects a mistake, or when you
   discover something worth remembering for future conversations.
 user-invocable: false
+metadata:
+  internal: true
 ---
 
 # Capture Learnings

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

@@ -0,0 +1,106 @@
+---
+name: client-methods
+description: >-
+  Client method surface rules. Use when wiring browser/client code to actions,
+  application state, framework routes, app APIs, uploads, auth, or settings.
+metadata:
+  internal: true
+---
+
+# Client Methods
+
+## Rule
+
+Browser/client code imports named methods, hooks, or client modules instead of
+hand-writing REST calls to framework or app routes.
+
+## Why
+
+Route shapes are transport details. If components and docs call
+`fetch("/_agent-native/...")` or template `/api/*` routes directly, every caller
+has to rediscover auth, base paths, request-source headers, JSON parsing, error
+handling, optimistic updates, sync invalidation, and route quirks. A named client
+method gives the UI, docs, and future agents one stable contract.
+
+## How
+
+1. Look for an existing client API first.
+
+   | Need | Use |
+   | --- | --- |
+   | App action reads/writes | `useActionQuery` / `useActionMutation` from `@agent-native/core/client` |
+   | Imperative action calls | `callAction` from `@agent-native/core/client` |
+   | Browser application state | `readClientAppState`, `writeClientAppState`, `setClientAppState`, `deleteClientAppState` |
+   | Navigation/app-state sync | `useAgentRouteState` / `useSemanticNavigationState` from `@agent-native/core/client` |
+   | Agent chat context | Agent chat client helpers from `@agent-native/core/client` |
+   | Ask the user a multiple-choice question from app code | `askUserQuestion` from `@agent-native/core/client` (renders inline in the agent panel; answer goes to the agent — do not build a custom modal) |
+   | Live sync | `useDbSync`, `useChangeVersion`, `useChangeVersions` |
+   | Extension iframe calls | `appAction`, `appFetch`, `extensionFetch` from the extension runtime |
+
+2. If no client API exists, add the narrowest helper at the boundary.
+
+   - Put shared framework helpers in `packages/core/src/client/*`.
+   - Put template-local helpers in `templates/<app>/app/hooks/*`,
+     `templates/<app>/app/lib/*`, or an existing local client module.
+   - Export reusable core helpers from `@agent-native/core/client`; add a leaf
+     export when callers may need to avoid the broad barrel.
+   - Keep raw `fetch`, `agentNativePath`, and route paths inside that helper,
+     not scattered through components or docs.
+   - Add focused tests for URL construction, headers, response parsing, error
+     shape, and any sync invalidation.
+
+3. Teach the helper, not the route.
+
+   Docs, skills, examples, and generated code should show:
+
+   ```ts
+   await setClientAppState("selection", selection, { keepalive: true });
+   ```
+
+   not:
+
+   ```ts
+   await fetch("/_agent-native/application-state/selection", {
+     method: "PUT",
+     body: JSON.stringify(selection),
+   });
+   ```
+
+## Exceptions
+
+Raw route calls are acceptable only inside low-level client helpers or for
+route-shaped protocols that cannot be hidden cleanly:
+
+- multipart uploads
+- streaming/SSE/WebSocket transports
+- OAuth redirects and callback URL construction
+- webhooks and external provider callbacks
+- extension sandbox `appFetch` / `extensionFetch`, which are themselves exposed
+  client methods
+- tests that assert route construction
+
+Even for exceptions, prefer a named helper as soon as more than one caller needs
+the behavior.
+
+## Don't
+
+- Don't put `fetch("/_agent-native/...")`, `fetch(agentNativePath(...))`, or
+  template `/api/*` calls directly in React components for normal app data,
+  actions, settings, or application state.
+- Don't document route calls as the way client code should do work.
+- Don't add pass-through `/api/*` routes just to make client fetches look
+  simpler; expose an action and call it with action hooks.
+- Don't duplicate auth/session/base-path/request-source/error parsing logic in
+  every component.
+
+## Related Skills
+
+- `actions` — app operations shared by UI and agent.
+- `context-awareness` — application-state navigation and selection helpers.
+- `real-time-sync` — keeping helper-backed UI reads fresh.
+- `server-plugins` — when a new route is actually warranted.
+
+## References
+
+- `references/legacy-client-fetch-audit-2026-06-03.md` — known legacy cleanup
+  targets found when this rule was added.

package/src/templates/workspace-core/.agents/skills/client-methods/references/legacy-client-fetch-audit-2026-06-03.md

@@ -0,0 +1,53 @@
+# Legacy Client Fetch Audit (2026-06-03)
+
+These are known legacy client-side route calls found while adding the
+`client-methods` rule. Treat them as cleanup targets when editing the relevant
+area. Do not migrate them mechanically without reading the local action/data
+contracts; some need new actions or helper modules first.
+
+## Highest Priority
+
+- `templates/analytics/app/pages/analyses/AnalysesList.tsx`,
+  `templates/analytics/app/pages/analyses/AnalysisDetail.tsx`,
+  `templates/analytics/app/components/layout/Sidebar.tsx`, and
+  `templates/analytics/app/components/layout/CommandPalette.tsx` use `/api/*`
+  for normal app data. `list-analyses` and `get-analysis` already exist; add
+  action-backed hooks/helpers for dashboard, explorer, theme, and user-pref
+  routes.
+- `templates/slides/app/context/DeckContext.tsx` and
+  `templates/slides/app/pages/Presentation.tsx` use `/api/decks` for deck CRUD.
+  `list-decks` and `get-deck` already exist; add or expose UI-safe actions for
+  upsert/delete flows before migrating.
+- `templates/mail/app/hooks/use-emails.ts`,
+  `templates/mail/app/hooks/use-scheduled-jobs.ts`,
+  `templates/mail/app/hooks/use-automations.ts`, and
+  `templates/mail/app/pages/SettingsPage.tsx` still use `/api/*` for normal
+  email/settings/automation work. Reuse existing actions where possible and add
+  missing structured actions for aliases, scheduled jobs, and automation
+  settings.
+- `templates/calendar/app/hooks/use-events.ts` bypasses existing private event
+  actions for event CRUD. Prefer `get-event`, `update-event`, `delete-event`,
+  and `rsvp-event` through action hooks or `callAction`.
+
+## Medium Priority
+
+- Raw action endpoint calls remain in several client flows, including Gmail
+  filters, calendar people search, slides import, videos composition generation,
+  and design variant flow. Prefer hooks or `callAction`.
+- Template navigation hooks duplicate application-state fetch logic. Prefer
+  `setClientAppState`, `readClientAppState`, `deleteClientAppState`, or a shared
+  navigation-state helper.
+- Mail integration credentials are written through application state in
+  `templates/mail/app/hooks/use-integrations.ts` and `use-apollo.ts`; move
+  credential values to secrets/actions instead of browser-readable app-state.
+- Content comments and versions are partially migrated. Add missing actions such
+  as `resolve-comment`, `delete-comment`, `list-document-versions`, and
+  `restore-document-version`.
+
+## Acceptable Exceptions
+
+Uploads/file transfer, exports, public/anonymous pages, OAuth/auth redirects,
+webhooks/tracking endpoints, media/blob routes, collab text endpoints,
+framework setup/status routes, low-level core helper implementations, and the
+extension bridge `appFetch` / `extensionFetch` can be route-shaped protocols.
+Prefer named helpers when more than one caller needs the behavior.

package/src/templates/workspace-core/.agents/skills/client-side-routing/SKILL.md

@@ -4,6 +4,8 @@ description: >-
   How to add routes without remounting the app shell. Use when adding a new
   route, fixing agent sidebar reloads on navigation, or choosing between
   `root.tsx` layout and pathless `_app.tsx` layout patterns.
+metadata:
+  internal: true
 ---
 
 # Client-Side Routing