@agent-native/core 0.152.1 → 0.153.0

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

@@ -1,176 +0,0 @@
----
-name: address-feedback
-description: >-
-  Triage feedback from docs, issues, Slack threads, or pasted notes into
-  verified bugs, UX proposals, unclear questions, and skipped noise. Use when a
-  user asks you to address product feedback or investigate a reported workflow.
-scope: dev
-metadata:
-  internal: true
----
-
-# Address Feedback
-
-Use this skill when the user shares a feedback document, issue, thread, or pasted notes and asks you to address the feedback.
-
-The default posture is judgment plus action: fix clear, verified bugs you agree with; propose UX changes with rationale; skip or flag low-signal, unclear, or out-of-scope items.
-
-## Prerequisites
-
-- If no link or feedback text is provided, ask for it.
-- Read the repo `AGENTS.md` before touching code.
-- Use the relevant connector/plugin/skill for the source when available, instead of scraping authenticated pages.
-- Before starting work, search available task history and local Git/PR metadata for the exact feedback link or issue identifiers. Reuse existing work instead of creating a duplicate fix.
-
-## Steps
-
-1. Read the feedback source.
-
-   | Source | Reader |
-   | --- | --- |
-   | Notion link | Notion connector or Notion skill |
-   | Google Docs/Drive link | Google Drive connector or Google Docs skill |
-   | Linear link | Linear connector if installed; otherwise ask for pasted content |
-   | GitHub issue or PR | GitHub connector or `gh issue view` / `gh pr view` |
-   | Slack thread | Slack connector |
-   | Public URL | Web browsing |
-   | Pasted text | Read directly |
-
-   Use web browsing only for public URLs. Auth-gated docs usually need their matching connector. For threads, read the parent and all replies; note when there are no replies, and inspect linked files or newer follow-ups when the source refers to them.
-
-2. Check whether this defect has already been reported.
-
-   A feedback channel holds months of reports and nobody remembers all of them,
-   so the same defect gets filed by different people weeks apart and every
-   filing reads as new. One recorded case: the same Clips recording bug was
-   filed almost word-for-word 29 days apart by the same reporter, and neither
-   message mentions the other. Another defect was reported fifteen times by
-   nine people across three months, was announced as fixed once in the middle,
-   and was reported again two weeks later.
-
-   Search before fixing, going back at least three months: the source channel
-   in the reporter's words and in your own, Sentry, and merged PR titles. Search
-   the feature name, the error text, and the surface separately — repeat reports
-   rarely share vocabulary.
-
-   - **No prior report** — proceed normally.
-   - **Prior report, no fix landed** — say how long it has been open. The person
-     forwarding it to you is likely seeing it for the second time too.
-   - **Prior report, fix landed** — this is a regression, and the bar is now
-     different. Patching it again and reporting done is exactly how it returns a
-     third time. Find why the first fix stopped holding, and leave behind
-     something that fails when it breaks again: a test that reproduces the
-     user's path, or an assertion in the flow the report names.
-
-   Report the repeat explicitly, with dates and reporters. A defect on its third
-   report is not a bug ticket, it is a missing check — and the missing check is
-   the deliverable, not the patch.
-
-3. Decompose and categorize every actionable item.
-
-   Build a compact checklist before changing code. For each item, record the
-   symptom, expected behavior, evidence, and owning surface: UI, action/tool,
-   data model, provider/runtime, or product policy.
-
-   - **Bug**: Broken behavior, crash, wrong data, dead link, package/API mismatch, or captured exception. Verify and fix when you agree.
-   - **UX suggestion**: Design, discoverability, workflow, or feature feedback. Propose the cleanest version first unless the user explicitly asked you to implement UX changes.
-   - **Question or unclear**: Missing detail, contradictory feedback, or behavior you cannot inspect. Ask or flag it.
-   - **Out of scope**: Outside this repo, already shipped, intentionally unsupported, or too low-signal. Note briefly and skip.
-
-4. For data, permissions, or resource-lifecycle feedback, verify the whole capability boundary before calling it UX.
-
-   - Check the supported create/read/update/delete lifecycle, including whether the backend/action exists when a UI control is missing.
-   - Inspect both the UI and the shared action/tool surface so agent and UI behavior stay in parity.
-   - Verify scope semantics such as owner/private, organization, shared, and public access. Test owner and non-owner paths with safe fixtures or read-only checks; never use another user's production data to test access.
-   - Treat possible cross-user or cross-organization exposure as a security/correctness bug and verify it before proposing polish.
-   - Keep undefined product policy separate from implementation bugs. If supported source types or scope semantics are not defined, flag the contract question instead of inventing behavior.
-
-5. Check Sentry when the feedback smells like an error.
-
-   - Use the Sentry skill/plugin if available, or the repo's Sentry scripts if documented.
-   - Search by route, stack symbol, error text, and symptom keywords.
-   - Default org is `builder-io` unless the user specifies another.
-   - Cite issue IDs or links when you find a match.
-   - If nothing matches, say that plainly.
-
-6. Fix only the clear bugs you agree with.
-
-   - Verify before fixing: reproduce locally, read the relevant code, inspect logs, or confirm with a stack trace.
-   - Keep each fix narrow and mapped to a feedback item.
-   - Follow existing project conventions and nearby patterns.
-   - Do not switch branches, stash, reset, force-push, or open a PR unless the user asks.
-   - Add or update focused tests when the bug risk warrants it.
-
-7. Treat UX feedback with product judgment.
-
-   Do not add visible UI as the default response. Address the underlying user
-   problem first, then choose the smallest change that makes the current state,
-   decision, action, or recovery path clearer.
-
-   - Make the current intent, state, and meaningful next step easier to find.
-   - Remove competing or redundant elements before adding controls, helper
-     text, banners, top-level navigation, or always-open panels.
-   - Put secondary or advanced actions in a `DropdownMenu`, `Popover`, `Sheet`,
-     `Collapsible`, tabs, or another contextual surface. Keep essential meaning,
-     labels, focus, hit targets, and recovery in the default path.
-   - Improve empty, loading, and error states around the user's actual need.
-
-   When the user has corrected the same visual preference more than once, treat
-   it as an acceptance criterion for the surface, not as a one-off copy edit.
-   State the underlying invariant before coding, such as “the default state
-   makes one next decision obvious and defers secondary detail,” then check the
-   rendered result against it. A screenshot showing unrelated forms, repeated
-   explanatory copy, documentation links, or competing controls in the default
-   state fails the review. Subtract that competition instead of explaining the
-   UI with more copy.
-
-   When proposing a UX change, write it as: what to change, why it helps, and the tradeoff. Keep each proposal short.
-
-8. Verify changed behavior.
-
-   - Run the smallest relevant test or typecheck command.
-   - For UI fixes, inspect the actual screen with a browser tool you already
-     have. Do not write a browser-automation script to check a small fix.
-   - For resource visibility or lifecycle changes, verify both the screen and
-     shared action/tool behavior, including owner versus non-owner access when
-     relevant.
-   - If you cannot run a useful verification, say why.
-
-## Report Format
-
-Keep the final report short:
-
-```md
-## Repeat Reports
-- [defect] - reported [N] times since [date] by [reporters]; [what now fails if it regresses]
-
-## Bugs Fixed
-- [feedback item] - [what changed, file:line]
-
-## Bugs Flagged But Not Fixed
-- [feedback item] - [why]
-
-## UX Suggestions
-- [feedback item] -> [proposed change]
-
-## Skipped
-- [feedback item] - [reason]
-```
-
-Only include sections that have content. The user can read the diff; do not write a second feedback document.
-
-## Avoid
-
-- Do not agree with every suggestion by default.
-- Do not bundle unrelated cleanups.
-- Do not implement UX changes that make an important screen busier without explicit user approval.
-- Do not claim a UI change is done without browser verification when a local app can be run.
-- Do not invent Sentry matches, affected users, or reproduction steps.
-
-## Related Skills
-
-- `github:gh-address-comments` for GitHub PR review threads.
-- `github:gh-fix-ci` for failing GitHub checks.
-- `sentry:sentry` for production error investigation.
-- `frontend-design` for approved UI implementation work.
-- `qa` for broader browser verification.

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

@@ -1,63 +0,0 @@
----
-name: agent-page
-description: >-
-  The full-page Agent surface (/agent) with Context, Files, Connections,
-  Automations, and Access tabs. Use when mounting the Agent page in a template, adding an
-  app-specific tab, surfacing context transparency, MCP servers, A2A agents,
-  recurring jobs, or external-client connect flows in the UI.
-scope: dev
-metadata:
-  internal: true
----
-
-# Agent Page
-
-`AgentTabsPage` (from `@agent-native/core/client`, source
-`packages/core/src/client/agent-page/`) is the canonical full-page surface for
-everything that can influence the agent. Design principles:
-
-- The page answers "what can influence this agent, and why" — it is not a
-  generic admin console.
-- Capability and access stay separate: **Connections** is what this agent can
-  reach; **Access** is who can reach this agent.
-- It is a thin shell that re-hosts existing components (ResourcesPanel, MCP
-  hooks, AgentsSection, context X-Ray, jobs actions) — do not re-implement
-  those surfaces inside it.
-- Context must be inspectable, attributable, and governable — provenance and
-  governance tiers, not just a token meter.
-
-## Tabs
-
-| Tab | Contents |
-| --- | --- |
-| `context` | System-vs-conversation split meter, provenance-grouped system sections (governance tiers: required/inherited/user), live-thread manifest. Backed by `context-preview-get` / `context-manifest-get` (see `context-xray` skill). |
-| `files` | ResourcesPanel (skills, instructions, memory, uploads) with the virtual `mcp-servers/` folder hidden (`showMcpServers={false}`). |
-| `connections` | MCP server management (both scopes, admin-gated org writes) plus A2A remote agents this app can call. |
-| `jobs` | **Automations**: personal and organization Scheduled/Event tasks with pause/resume/delete. The `jobs` hash is stable for compatibility (see `automations` and `recurring-jobs`). |
-| `access` | Copyable MCP URL and A2A agent-card URL, per-client connect steps (Claude, ChatGPT, Cursor, Claude Code, Codex, Other) from `packages/core/src/shared/mcp-connect-content.ts` (shared with the `/mcp/connect` route — edit the shared module, never fork copy), static-token fallback link. Grants/scopes/revocation UI is future work. |
-
-## Mounting In A Template
-
-1. Add an `/agent` route following the template's settings-route pattern
-   (`app/routes/agent.tsx` or `_app.agent.tsx`), mounting `AgentTabsPage`.
-   CSR is fine; keep the app shell in `root.tsx` so navigation does not
-   remount it (`client-side-routing` skill).
-2. Add an "Agent" item to primary navigation and the command palette,
-   mirroring the Settings entries. Link-first (`native-navigation` skill).
-3. Pass `agentPageHref="/agent"` to `AgentSidebar` so the sidebar Resources
-   and settings modes link out to the full page.
-4. Hash deep-links work out of the box: `/agent#context`, `/agent#files`,
-   `/agent#connections`, `/agent#jobs`, `/agent#access`.
-5. App-specific additions go in `extraTabs` (same `SettingsTabItem` shape as
-   the settings page); hide built-ins only with `hiddenTabs` when a template
-   genuinely lacks the underlying capability.
-
-## Scope
-
-The page currently passes personal `scope` (and `canManageOrg`) to tabs via
-`AgentPageTabProps`; it does not expose a page-level Personal/Organization
-toggle. A tab may render its own scoped sections where the underlying actions
-support them. The Automations tab shows personal and organization sections for
-both Scheduled and Event triggers. Organization event automations remain
-creator-run: administrators can manage them, but cannot retarget the creator's
-identity.

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

@@ -1,96 +0,0 @@
----
-name: audit-log
-description: >-
-  Durable, access-scoped, append-only record of who changed what app data,
-  when, and whether it was the agent or a human. Use when adding an activity
-  feed or change history, declaring what a mutating action targets, auditing
-  sensitive reads, or answering "what did the agent change / who edited this".
-scope: dev
-metadata:
-  internal: true
----
-
-# Audit Log
-
-## Rule
-
-Every mutating action automatically records an audit event — **no wiring
-needed**. The framework captures who/what/when/from-where at the `defineAction`
-seam, redacts credentials, and attributes the change to a human or the agent
-(with the agent thread/turn that caused it). You only touch `audit` config to
-make events *more useful* (declare the target) or to opt a read in / a noisy
-write out.
-
-This is distinct from:
-
-- **observability** — sampled agent-run telemetry (traces, evals), developer-facing.
-- **tracking** — fire-and-forget product analytics to external SaaS.
-
-Audit is complete, durable, locally queryable, and scoped to the data it
-describes.
-
-## Declare the target so it lands in the owner's trail
-
-By default an event is scoped to the **actor** (you see your own changes and the
-agent's changes on your behalf). To make a change to a *shared* resource show up
-in the **owner's** audit trail, declare the target:
-
-```ts
-defineAction({
-  description: "Delete a recording",
-  schema: z.object({ id: z.string() }),
-  audit: {
-    // type + id label the event; ownerEmail/orgId/visibility scope who can read it.
-    target: (args, result, meta) => ({
-      type: "recording",
-      id: args.id,
-      // Optional — defaults to the actor. Set when editing someone else's resource.
-      ownerEmail: result?.ownerEmail,
-      visibility: "org",
-    }),
-    summary: (args) => `Deleted recording ${args.id}`,
-  },
-  run: async (args, ctx) => { /* ... */ },
-});
-```
-
-`target`, `ownerEmail`, `visibility`, and `summary` are all optional. The
-minimum useful addition is `target: () => ({ type, id })`.
-
-## Defaults and how to override them
-
-- **Mutations** (anything not GET / `readOnly`) are audited automatically.
-- **Read-only** actions are skipped. Audit a sensitive read (secret access, bulk
-  export) with `audit: { onRead: true }`.
-- **High-frequency framework actions** (app-state sync, context-xray, navigate,
-  appearance) are skipped by default. Force one on with `audit: { enabled: true }`.
-- **Opt a noisy write out** with `audit: { enabled: false }`.
-- **Skip capturing arguments** (large/sensitive payloads) with
-  `audit: { recordInputs: false }`. Inputs are credential-redacted regardless.
-
-## Reading the log
-
-Two actions are available to the agent and the frontend in every app, scoped in
-SQL to the caller — they never leak another tenant's rows:
-
-- `list-audit-events` — filter by `targetType`/`targetId`, `actorKind`
-  (`agent` | `human` | `system`), `status`, `threadId`/`turnId`, `action`,
-  `sinceMs`, `limit`.
-- `get-audit-event` — one event by id, with its redacted input payload.
-- `export-audit-events` — bulk CSV/NDJSON export (same filters minus `limit`,
-  plus `format` and `maxRows`) for offline/compliance pulls; itself audited
-  via `onRead`.
-
-Call them from the UI with `useActionQuery` to build an activity feed or a
-"who changed this" line — never hand-write a fetch to the audit table.
-
-## Never
-
-- Don't write a parallel "history" table for a resource — declare an `audit.target`
-  and read it back instead.
-- Don't put secrets in `summary` or rely on inputs being safe — redaction covers
-  credential-shaped values, but keep summaries free of sensitive data.
-- Don't expose an update/delete path for audit rows. The log is append-only; the
-  only deletion is the retention purge (`AGENT_NATIVE_AUDIT_RETENTION_DAYS`,
-  default 365 days; `0` = keep forever). Global kill switch:
-  `AGENT_NATIVE_AUDIT_ENABLED=false`.

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

@@ -1,295 +0,0 @@
----
-name: authentication
-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.
-scope: dev
-metadata:
-  internal: true
----
-
-# Authentication
-
-## Rule
-
-Auth is powered by **Better Auth** with account-first design. Every new user creates an account on first visit. Use `getSession(event)` to authenticate custom routes; actions are auto-protected. Normal app HTML and React Router page-data responses are one impersonal, public-cacheable shell for every visitor. The client decides whether to render private UI or redirect to sign-in.
-
-## Auth Modes
-
-| Mode                      | Behavior                                                                                                                                 |
-| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| **Development (default)** | Real Better Auth — same flow as production. There is **no auth bypass**. On first run the framework auto-creates a throwaway dev account and signs you in without printing its credentials (disable with `AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT=1`), so you are not stuck at a login wall. `getSession()` returns the signed-in user or `null` — it never falls back to a sentinel identity. |
-| **Production (default)**  | Magic-link-first Better Auth when outbound email is ready, with email/password fallback and 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 password-fallback 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. It does not change magic-link delivery. Use `+qa` emails for test accounts. |
-| **`AUTH_MAGIC_LINK=0`** | Force the email/password fallback even when outbound email is ready. |
-| **`AUTH_DISABLED=true`** | Skip login/signup entirely — every request runs as `dev@local.test`. For local dev, cloud previews, and internal demos only; not for production with real users. |
-| **`ACCESS_TOKEN` / `ACCESS_TOKENS`** | Static bearer fallback for MCP/connect clients that cannot use OAuth. Not browser auth and never a token login page.         |
-| **Custom**                | Pass your own `getSession` to `autoMountAuth(app, { getSession })`.                                                                     |
-
-> **Never** use `local@localhost` as a fallback identity in app code
-> (`getRequestUserEmail() ?? "local@localhost"`, `session?.email ?? "local@localhost"`,
-> etc.). There is no dev auth shim. That pattern pools every unauthenticated
-> request into one shared tenant and caused the 2026-04-29 credentials leak.
-> 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 `/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`, then use a validated Client ID
-Metadata Document when the client id is an HTTPS URL or dynamically register a
-public client otherwise. URL-like client ids never fall back to dynamic
-registration when their metadata is missing or invalid. Clients complete
-authorization-code + PKCE at
-`/mcp/oauth/authorize` / `/mcp/oauth/token`.
-Access tokens are audience-bound to the exact MCP URL and carry user/org
-identity plus `mcp:read`, `mcp:write`, `mcp:apps`, and/or `offline_access`;
-advertising `offline_access` lets hosts such as ChatGPT retain refresh access.
-Refresh tokens are stored hashed and rotate. Keep `ACCESS_TOKEN` and `pnpm exec 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 `npx @agent-native/core@latest 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`.
-
-Templates with legacy global settings can provide `POST /api/local-migration` for one-time re-homing during the upgrade flow.
-
-## Organizations
-
-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).
-
-Owners and admins can require Google sign-in for an organization from Team
-settings or `PUT /_agent-native/org/auth-provider` with `{ provider: "google" }`.
-Enabling it revokes current Better Auth and legacy sessions; password signup,
-password login, and non-Google social sessions are rejected for that org.
-
-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).
-
-When an authenticated user has no org memberships, the framework auto-creates a
-default org (named after the user) the first time `getOrgContext` runs. This
-keeps org-scoped templates from showing a manual "create organization" step.
-The auto-create path skips users with pending invites or a matching
-`allowed_domain` org so they can join the intended team instead. Set
-`AUTO_CREATE_DEFAULT_ORG=0` only for deployments that intentionally want manual
-org creation.
-
-### App-Specific Roles
-
-When a request needs "only some teammates may do this **inside this app**", the
-answer is per-app roles — **not** a second organization. App roles are an
-overlay on the one org membership, never a second roster. Three role systems
-coexist and never imply one another: the org role (`org_members.role`) says what
-a person may do to the *team*, an app role says what they may do inside *one
-app*, and a share role (`sharing` skill) says what they may do to *one row*. An
-app `admin` is not an org admin, and org handlers never read app roles.
-
-Declare the vocabulary once on the server and guard actions with it:
-
-```ts
-import { defineAppRoles } from "@agent-native/core/org-team";
-
-export const coachAccess = defineAppRoles({
-  appId: "coach",
-  roles: ["member", "coach-admin"] as const,
-  defaultRole: "member",
-});
-
-// in an action
-authorize: coachAccess.requireAny("coach-admin"),
-```
-
-Roles are an unordered set, not a ladder — declaration order carries no meaning,
-and every guard names its accepted roles explicitly. `defaultRole` is **display
-only**: `requireAny` matches an explicit assignment row and nothing else, so
-"nobody assigned this person" never reads as "granted", and widening the default
-cannot silently widen a guard. Org membership is a precondition, resolved in the
-same statement as the assignment, so a leftover assignment for a removed member
-can never authorize. Only org owners/admins may assign app roles; render the
-picker with `<TeamPage appRoles={descriptor} />`.
-
-`requireAny` validates at definition time — no roles, or a role outside the
-declared vocabulary, throws when the module loads rather than surfacing as an
-unexplained 403 later. When calling `resolve`/`assertAny` directly, note that an
-explicit `userEmail: null` / `orgId: null` means "this run has no identity" and
-does **not** fall back to the ambient request context; only `undefined` does.
-
-### Stop And Confirm Before Creating Or Switching Organizations
-
-Vault credentials are scoped per organization and are **not** shared between
-them. A second organization therefore orphans every key synced under the first,
-and the only symptom is a missing-credential error somewhere else entirely,
-naming the key rather than the org change that caused it.
-
-So: **do not create an organization, repoint anyone's `active-org-id`, or
-migrate a user/roster/identity list into a new organization on your own
-initiative.** Stop, say plainly that it will orphan the existing organization's
-credentials, and get an explicit yes first — even when the user asked for
-something that seems to imply it ("use the real org user list", "align this to
-the Settings team view", "migrate my users").
-
-The intended pattern is **one organization per workspace**, with every app
-sharing it. When a request needs real org members, add them to the existing
-organization; never provision a parallel one per app. `createOrganization()`
-logs a loud warning when it creates an additional org for an account that
-already belongs to one, and `setActiveOrgId()` logs one whenever it moves an
-account from one org to another, naming both orgs and the orphaned credentials.
-Treat either warning as a bug report against your own change, not as noise.
-
-Write `active-org-id` only through `setActiveOrgId(email, orgId, reason)` from
-`@agent-native/core` (`src/org/active-org.ts`). Calling `putUserSetting(email,
-"active-org-id", ...)` directly is how a roster migration silently repointed 21
-accounts with nothing in the logs; the helper exists so that cannot happen
-again.
-
-Do not wrap normal app shells in `<RequireActiveOrg>` just to force setup. Use
-non-blocking org UI such as `InvitationBanner`, `OrgSwitcher`, and a `/team`
-route so users can accept invites, join domain-matched teams, or switch orgs
-without blocking the primary product experience. Place org UI inside the agent
-sidebar so the setup
-checklist, chat, and CLI stay usable during setup.
-
-## A2A Identity
-
-Set `A2A_SECRET` (same value) on all apps that must verify each other's identity.
-
-- Outbound A2A calls are signed with JWTs
-- 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:** the app creates a bound state and PKCE verifier, then opens `GET <hub>/_agent-native/identity/authorize?response_type=code&app=&client_id=&redirect_uri=&state=&code_challenge=`. Dispatch authenticates the human and redirects back with only a short-lived, one-time authorization code. The app keeps the verifier in a callback-scoped HttpOnly cookie and redeems the code server-to-server at `/_agent-native/identity/token`; only that response contains the short-lived `A2A_SECRET`-signed identity assertion. No bearer token or JWT is placed in a browser URL. Canonical clients require an exact registered app ID, client ID, origin, and callback path; localhost remains available for development. The app verifies the assertion, **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).
-
-### Packaged Desktop workspace sign-in
-
-For canonical first-party hosted apps, the packaged Desktop SSO Canary may compose the same
-federation into one workspace sign-in. Dispatch owns the default-off
-`desktop.workspace-sso` availability flag; every app still owns its local
-session. One explicit Settings action opens one interactive Dispatch ceremony,
-then provisions every currently eligible app. Later eligible webviews are
-provisioned lazily when they load. The flag is never an auth or authorization
-boundary. Keep nonce, signature, exact origin/callback, authenticated-session,
-app-binding, cookie allowlist, revocation, and credential-custody checks
-unconditional. When the flag is Off or unreadable, Desktop must leave ordinary
-per-app sign-in, sign-out, and Settings unchanged. Never extend the broker to
-arbitrary third-party sites, and never expose cookies, identity tokens, or
-provider credentials through IPC.
-Canonical hosted apps recognize packaged Desktop requests without per-app
-identity-hub environment configuration. A custom workspace app is eligible only
-when its Desktop config explicitly sets `workspaceSso: true`, its production
-origin is exact HTTPS, and Dispatch has an exact registration in
-`IDENTITY_SSO_APP_REGISTRY_JSON` with its app ID, client ID, callback path, and
-`identity-sso` capability. The custom app also needs
-`AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com` and the shared
-`A2A_SECRET`. Ordinary browsers and self-hosted apps still require the explicit
-hub configuration.
-Stable Desktop builds must not initialize the broker until a later release is
-separately approved.
-Treat the Canary user-agent marker only as an availability hint, never as
-remote attestation or an authentication boundary. Bind supervised acceptance
-to exact signed-artifact provenance.
-The Canary must not intercept anonymous app sign-in navigation. The user
-explicitly chooses workspace sign-in in Desktop Settings for the active eligible
-app; ordinary app sign-in remains the default path. A failed app fan-out is
-reported as incomplete and can be retried; Desktop must not claim workspace
-sign-in is complete until every eligible app in that snapshot succeeds.
-
-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. 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";
-
-export default defineEventHandler(async (event) => {
-  const session = await getSession(event);
-  if (!session) throw createError({ statusCode: 401 });
-  // ...
-});
-```
-
-Never create unprotected routes that modify data.
-
-## Sign-In from a Public Page
-
-For public pages (share links, embeds, marketing pages) that need anonymous viewers to sign in and return to where they were, navigate them through the framework's sign-in entry point — never roll your own:
-
-```ts
-const ret = window.location.pathname + window.location.search;
-window.location.href =
-  "/sign-in?return=" + encodeURIComponent(ret);
-```
-
-After successful sign-in (token / email-password / Google OAuth), the framework redirects to `return`. The path is validated as same-origin via the URL parser — open-redirect / header-injection inputs fall back to `/`.
-
-Bookmarked private paths work through the client session gate: the shared shell hydrates, `AppProviders` redirects the signed-out visitor to the framework sign-in entrypoint with the current path as `return`, and successful sign-in sends them back.
-
-## Gating the App Shell (avoid the logged-out infinite spinner)
-
-Normal app HTML and React Router page-data responses deliberately bypass the
-server session guard. They are rendered impersonally and cached as one shared,
-public, hard-cached-at-the-CDN shell; APIs, actions, and framework data routes
-remain server-protected. The client session gate is therefore the
-authoritative decision point for whether private app UI renders.
-
-**Never**, on the SSR HTML/`.data` path: set `private`, `no-store`, or
-`Vary: Cookie`; call `getSession` or read cookies in the SSR route or the
-login HTML path; or embed tokens/secrets into the rendered HTML — a
-token-bearing page still returns the same anonymous shell and resolves access
-client-side. This has regressed repeatedly (agents "fixing" it back to
-per-user SSR); it is enforced by `guard:ssr-cache-shell` and
-`ssr-handler.spec.ts` (`packages/core/src/server/ssr-handler.ts`), and reverts
-will be rejected.
-
-`AppProviders` applies `RequireSession` automatically on its private branch. It
-resolves the session on the client and redirects signed-out visitors to
-`/sign-in?return=…` before mounting the routed shell. The legacy
-`/_agent-native/sign-in` path remains supported for older generated apps and
-bookmarks:
-
-```tsx
-import { AppProviders } from "@agent-native/core/client/hooks";
-
-<AppProviders queryClient={queryClient}>
-  <AppLayout>
-    <Outlet />
-  </AppLayout>
-</AppProviders>;
-```
-
-- Keep the layout/outlet and always-mounted effects (poll, automation trigger)
-  inside `AppProviders` so they do not fire 401s before the gate resolves.
-- Pass `sessionBypass` to `AppProviders` only for a private-looking surface that
-  authenticates by another mechanism (for example, an embed iframe carrying
-  its own scoped token).
-- Pass `isPublicPath` for public/anonymous and SEO routes. That branch does not
-  mount `RequireSession` and SSRs real content.
-- Use `RequireSession` directly only when a nested subtree needs custom
-  `redirect={false}` / `signedOut` behavior.
-
-## Related Skills
-
-- `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