@agent-native/core 0.127.1 → 0.128.0

package/corpus/core/src/templates/chat/.agents/skills/security/SKILL.md

@@ -1,282 +0,0 @@
----
-name: security
-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.
-scope: dev
-metadata:
-  internal: true
----
-
-# Security
-
-## Rule
-
-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.
-
-```ts
-export default defineAction({
-  schema: z.object({
-    email: z.string().email(),
-    role: z.enum(["admin", "member"]),
-    limit: z.coerce.number().int().min(1).max(100).default(25),
-  }),
-  run: async (args) => { /* args is fully typed and validated */ },
-});
-```
-
-The legacy `parameters:` field (plain JSON Schema) has no runtime validation — do not use it for new code.
-
-## Large Payloads
-
-Do not accept or persist unbounded base64/file blobs through actions, SQL writes,
-or `application_state`. Route uploads through the file-upload provider and store
-references. This prevents database bloat, slow hot paths, and accidental secret
-or customer-data embedding inside binary payloads.
-
-## SQL Injection
-
-Never concatenate user input into SQL strings. Use Drizzle ORM's query builder (always safe) or parameterized queries:
-
-```ts
-// Safe — Drizzle ORM
-await db.select().from(users).where(eq(users.email, args.email));
-
-// Safe — parameterized raw SQL
-await client.execute({ sql: "SELECT * FROM users WHERE id = ?", args: [id] });
-
-// NEVER do this
-await client.execute(`SELECT * FROM users WHERE id = '${id}'`);
-```
-
-## XSS
-
-- React auto-escapes JSX content — trust it.
-- Never use `dangerouslySetInnerHTML`, `innerHTML`, `eval()`, or `document.write()` with user-controlled content.
-- 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()`.
-- 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`
-
-User credentials (API keys, third-party tokens) are per-user (or per-org) data. They MUST live in SQL, scoped per-user (`u:<email>:credential:KEY`) or per-org (`o:<orgId>:credential:KEY`). Always read with the request context:
-
-```ts
-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>`.
-- `scripts/guard-no-unscoped-credentials.mjs` — bans one-arg calls to `resolveCredential` / `hasCredential` / `saveCredential` / `deleteCredential`. Per-line opt-out: `// guard:allow-unscoped-credential — <reason>`.
-
-If a deploy-level value genuinely needs an env var (CI-set token, host secret), it's not a user credential — keep it out of the credentials/ secrets/ vault/ paths and the env-credentials guard won't see it.
-
-## Guards
-
-Two more CI guards (also wired into `pnpm prep`) target the 2026-04 cross-tenant leak class — request-state escaping into shared process state, and dev-mode sentinel identities used as production fallbacks.
-
-- `scripts/guard-no-env-mutation.mjs` — bans `process.env.<KEY> = …` (and bracket / compound forms) anywhere in production code. On serverless, every warm container handles many concurrent requests in one Node process, so `process.env` mutation leaks across in-flight requests (the "restore" line at the end of a handler races and never helps — most recently the Zoom webhook). Use `runWithRequestContext({ userEmail, orgId, timezone }, fn)` from `@agent-native/core/server` instead — it's AsyncLocalStorage-backed and per-request safe. Allowlisted paths: `scripts/`, `*.spec.ts` / `*.test.ts`, `packages/core/src/dev**`, `templates/*/test/`, anything under `/cli/` or `/scaffold/`. Per-line opt-out: `process.env.X = y // guard:allow-env-mutation — <reason>`.
-- `scripts/guard-no-localhost-fallback.mjs` — bans the literal `"local@localhost"` / `'local@localhost'` / `` `local@localhost` `` in production code. The bug class: `getRequestUserEmail() ?? "local@localhost"` silently pools every unauthenticated request into a single shared tenant, leaking credentials, tools, and `application_state` rows between accounts. The right behavior is to throw / 401 when there's no session. Allowlisted paths: the dev-mode auth shim (`packages/core/src/server/auth.ts`), `packages/core/src/dev**`, tests, `scripts/`, `seed/` / `seeds/`, plus a few framework helpers that intentionally inspect or migrate the dev identity. SQL DDL `DEFAULT 'local@localhost'` and the Drizzle helper `.default('local@localhost')` are skipped per-line — schema column defaults are intentional dev fixtures, not the dangerous fallback pattern. Per-line opt-out: `email ?? "local@localhost" // guard:allow-localhost-fallback — <reason>`.
-
-  The same guard also bans the **ambient process identity** as a request-scoped fallback: `?? process.env.AGENT_USER_EMAIL`, `|| process.env.WORKSPACE_OWNER_EMAIL`, and `?? getAmbientUserEmail()`. Those name the identity of the *deployment*, not the caller, so a handler reading one authorizes whoever the deploy env names rather than whoever signed in — it fails open toward more privilege. Exempt paths are the ones with no request by construction: `scripts/` (including `templates/*/scripts/`), `src/cli/`, `src/scripts/`, `script-helpers.ts` / `script-entries.ts`, tests, and seeds. It deliberately matches only the `??` / `||` fallback position, so reading the same env var to build an admin allowlist (`envEmails("WORKSPACE_OWNER_EMAIL").includes(email)`) is untouched. Known gaps, both requiring dataflow analysis the guard does not do: an env read aliased through a local (`const fallback = process.env.AGENT_USER_EMAIL; … ?? fallback`) and a destructured `const { AGENT_USER_EMAIL } = process.env`.
-
-## 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
-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.
-
-**Exception — the SSR HTML/`.data` catch-all is deliberately session-blind.**
-The rule above is for routes that read or mutate user data. The SSR page
-render and React Router `.data` route are different: they serve one
-impersonal, public-cacheable shell to every visitor by design, and loaders on
-that path render no user data. Do not "fix" this by adding `getSession`,
-`private`, or `no-store` to it — that regresses the CDN cache contract for the
-whole site. Data scoping lives in actions and API routes; the client gates
-private UI after the shell loads. See the `authentication` skill and
-`guard:ssr-cache-shell` / `ssr-handler.spec.ts`.
-
-## Human-in-the-Loop Approval for High-Consequence Actions
-
-For a small set of outward-facing, hard-to-undo operations — sending an email, charging a card, deleting an account, posting publicly — auth and access control are necessary but not sufficient: you also do not want the **agent** to perform them autonomously. Set `needsApproval` on the `defineAction` so the agent cannot run the action without a human approving the specific call.
-
-```ts
-export default defineAction({
-  description: "Send an email via Gmail.",
-  schema: z.object({ to: z.string(), subject: z.string(), body: z.string() }),
-  needsApproval: true, // or (args, ctx) => boolean | Promise<boolean>
-  run: async (args) => {
-    /* ...actually send... */
-  },
-});
-```
-
-When the gate is truthy and the call is not yet approved, the loop emits an `approval_required` event and **stops the turn — `run()` never executes**. The human approves via the chat UI's Approve affordance, which re-issues the turn with the call's stable `approvalKey`; only then does the action run. A predicate gates conditionally (e.g. only external recipients) and **fails closed** — a throw is treated as "approval required".
-
-Rules:
-
-- Reach for `needsApproval` only for genuinely high-consequence operations. The default is off, and the framework intentionally keeps approvals rare — over-gating turns the agent into a click-through wizard. The canonical (and intentionally lone) framework example is Mail's `send-email`.
-- `needsApproval` is **not** a substitute for `accessFilter` / `assertAccess` or for hiding sensitive operations from the model with `agentTool: false` / `toolCallable: false`. It is the layer for "a human must explicitly bless this specific outward-facing call," not for scoping data. See the `actions` skill for the full surface.
-
-## Custom HTTP Routes Must Apply Access Control Themselves
-
-This is the single most-failed rule in the codebase. Auto-mounted action routes (`/_agent-native/actions/...`) get a request context wired up automatically. **Hand-written `/api/*` Nitro routes do not.** If your handler queries an ownable resource (any table with `...ownableColumns()`), you MUST:
-
-1. Read the session: `const session = await getSession(event).catch(() => null)`.
-2. Run the work inside `runWithRequestContext({ userEmail: session?.email, orgId: session?.orgId }, fn)` from `@agent-native/core/server`.
-3. Inside `fn`, query through one of:
-   - `accessFilter(table, sharesTable)` in the WHERE clause for list/read-many.
-   - `resolveAccess("<type>", id)` for read-by-id (returns null if no access — return 404, not 403, so existence isn't leaked).
-   - `assertAccess("<type>", id, "viewer"|"editor"|"admin")` for write/delete-by-id.
-
-```ts
-// Bad — Brent's signup leaked every other user's decks because of this exact shape.
-export default defineEventHandler(async () => {
-  const db = getDb();
-  return db.select().from(schema.decks); // no access filter!
-});
-
-// Good
-import { getSession, runWithRequestContext } from "@agent-native/core/server";
-import { accessFilter } from "@agent-native/core/sharing";
-export default defineEventHandler(async (event) => {
-  const session = await getSession(event).catch(() => null);
-  return runWithRequestContext(
-    { userEmail: session?.email, orgId: session?.orgId },
-    async () => {
-      const db = getDb();
-      return db
-        .select()
-        .from(schema.decks)
-        .where(accessFilter(schema.decks, schema.deckShares));
-    },
-  );
-});
-```
-
-`scripts/guard-no-unscoped-queries.mjs` runs in `pnpm prep` and fails the build if any file in `templates/*/server/`, `templates/*/actions/`, or `packages/*/src/` queries an ownable table without one of the access helpers. Last-resort opt-out is the marker comment `// guard:allow-unscoped — <reason>` — only use it for cases like the sharing primitives themselves or share-token-public viewer endpoints, and always include a reviewer-readable reason.
-
-## Data Scoping
-
-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:
-
-1. Framework detects `owner_email` via schema introspection
-2. Creates temp views `WHERE owner_email = <current user>` before each query
-3. Auto-injects `owner_email` into INSERT statements
-
-The current user is resolved from `AGENT_USER_EMAIL` (set automatically from the session).
-
-### Per-Org Scoping (`org_id`)
-
-For multi-org apps, tables also need `org_id`:
-
-1. `WHERE org_id = <current org>` is added (in addition to `owner_email` if present)
-2. `org_id` is auto-injected into INSERT statements
-
-Enable org scoping in the agent-chat plugin:
-
-```ts
-createAgentChatPlugin({
-  resolveOrgId: async (event) => {
-    const ctx = await getOrgContext(event);
-    return ctx.orgId;
-  },
-});
-```
-
-### Column Conventions
-
-| Column        | Purpose                 | Required                        |
-| ------------- | ----------------------- | ------------------------------- |
-| `owner_email` | Per-user data isolation | Yes, for all user-facing tables |
-| `org_id`      | Per-org data isolation  | Yes, for multi-org apps         |
-
-Run `pnpm action db-check-scoping` to verify. Use `--require-org` for multi-org apps.
-
-## Checklist
-
-- [ ] 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
-
-## Related Skills
-
-- `storing-data` — SQL patterns and the agent's db tools
-- `actions` — `defineAction` with Zod schema validation
-- `authentication` — Auth modes, sessions, and org context

package/corpus/core/src/templates/chat/.agents/skills/self-modifying-code/SKILL.md

@@ -1,119 +0,0 @@
----
-name: self-modifying-code
-description: >-
-  Tiers, checkpoints, and off-limits paths for an agent editing the app's own
-  source. Use when designing UI for agent editability, deciding whether a file
-  is safe for the agent to change, or when tempted to patch config, `.env`, or
-  an `@agent-native/*` package. Do not load it for ordinary source edits.
-scope: dev
-metadata:
-  internal: true
----
-
-# Self-Modifying Code
-
-## Rule
-
-The agent can edit the app's own source code — components, routes, styles, scripts. This is a feature, not a bug. Design your app expecting this.
-
-## Why
-
-An agent-native app isn't just an app the agent can _use_ — it's an app the agent can _change_. The agent can fix bugs, add features, adjust styles, and restructure code. This makes the agent a true collaborator, not just an operator.
-
-## Modification Taxonomy
-
-Not all modifications are equal. Use this to decide what level of care is needed:
-
-| Tier          | What                  | Examples                                         | After modifying                   |
-| ------------- | --------------------- | ------------------------------------------------ | --------------------------------- |
-| 1: Data       | Files in `data/`      | JSON state, generated content, markdown          | Nothing — these are routine       |
-| 2: Source     | App code              | Components, routes, styles, scripts              | Run `pnpm typecheck && pnpm lint` |
-| 3: Config     | Project config        | `package.json`, `tsconfig.json`, `vite.config.*` | Ask for explicit approval first   |
-| 4: Off limits | Secrets and framework | `.env`, `@agent-native/*` packages & overrides   | Never modify these                |
-
-Tier 4 includes **all** of the following — not only editing package source:
-
-- Files under `node_modules/@agent-native/*` (core, dispatch, scheduling, …)
-- `pnpm.overrides`, `overrides`, `resolutions`, or `patchedDependencies` that
-  target any `@agent-native/*` package
-- Local package patches or invented "dispatch/core behavior" shims meant to
-  paper over a version skew or failed upgrade
-
-This does not prohibit intentional app-owned UI customization. When public
-props and composition are insufficient, the `customizing-agent-native` skill
-uses `agent-native eject` to transfer the smallest supported unit from the
-installed package into the app. The ejected unit must keep public runtime
-contracts and must not replace Core auth, DB, actions, agent execution, or
-transport behavior. Manual copying is only the fallback described by an unknown
-third-party package's add-style blueprint.
-
-When an older branch needs current packages, use **`agent-native upgrade`**
-(see the `upgrade-agent-native` skill). If upgrade or typecheck fails, fix
-**app** code or stop and ask — do not patch the framework.
-
-## Git Checkpoint Pattern
-
-Before modifying source code (Tier 2+), create a rollback point:
-
-1. Commit or stash current state
-2. Make the edit
-3. Run `pnpm typecheck && pnpm lint`
-4. If verification fails → revert with `git checkout -- <file>`
-5. If verification passes → continue
-
-This ensures the agent can experiment without breaking the app.
-
-## Designing for Agent Editability
-
-Make your app easy for the agent to understand and modify:
-
-**Expose UI state via `data-*` attributes** so the agent knows what's selected:
-
-```ts
-const el = document.documentElement;
-el.dataset.currentView = view;
-el.dataset.selectedId = selectedItem?.id || "";
-```
-
-**Expose richer context via `window.__appState`** for complex state:
-
-```ts
-(window as any).__appState = {
-  selectedId: id,
-  currentLayout: layout,
-  itemCount: items.length,
-};
-```
-
-**Use configuration-driven rendering** — Extract visual decisions (colors, layouts, sizes) into JSON config files in `data/`. The agent can modify the config (Tier 1) instead of the component source (Tier 2).
-
-**Keep localized copy in catalogs** — When editing visible UI copy, labels,
-toasts, empty states, prompts, or formatting, read `internationalization` and
-update `app/i18n/en-US.ts` plus existing locale catalogs instead of leaving new
-inline strings in components.
-
-## Don't
-
-- Don't modify `.env` files or files containing secrets
-- Don't modify `@agent-native/core`, `@agent-native/dispatch`, or other
-  `@agent-native/*` package internals (including under `node_modules`)
-- Don't confuse readable package source with app-owned code: use
-  `customizing-agent-native` and `agent-native eject` for supported ownership
-  transfer
-- Don't add `pnpm.overrides` / `patchedDependencies` / `resolutions` for
-  `@agent-native/*` to "make the app run" after a version bump
-- Don't invent local dispatch/core behavior overrides when upgrade fails —
-  run `npx @agent-native/core@latest upgrade`, then fix app-level errors only
-- Don't modify `.agents/skills/` or `AGENTS.md` unless explicitly requested
-- Don't skip the typecheck/lint step after editing source code
-- Don't make source changes without a git checkpoint to roll back to
-
-## Related Skills
-
-- **upgrade-agent-native** — supported path to bring an older app/workspace current
-- **customizing-agent-native** — configure, compose, or eject installed features safely
-- **storing-data** — Tier 1 modifications (data files) are the safest and most common
-- **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 change events to update the UI
-- **internationalization** — UI copy, language catalogs, locale switching, and RTL-safe edits

package/corpus/core/src/templates/chat/.agents/skills/shadcn-ui/SKILL.md

@@ -1,123 +0,0 @@
----
-name: shadcn-ui
-description: >-
-  The shadcn CLI, component composition, theming, and registry workflow. Use
-  when adding, replacing, upgrading, or debugging a shadcn/ui primitive itself,
-  or when changing a theme or registry. Do not load it for ordinary edits to a
-  file that happens to import a shadcn component.
-scope: dev
-source: https://ui.shadcn.com/docs/skills
-local-changes: >-
-  Description narrowed deliberately; an upstream sync must not restore the
-  "any project with a components.json file" trigger.
-metadata:
-  internal: true
----
-
-# shadcn/ui
-
-This skill keeps shadcn/ui work project-aware. Components are source files in the app, so always inspect the local project before adding, importing, or rewriting them.
-
-## First Steps
-
-1. Work from the app root that owns `components.json`.
-2. In an Agent Native app, inspect `app/design-system.ts` and
-   `ToolkitProvider` before choosing a primitive. A registered company design
-   system takes precedence over the default shadcn adapter.
-3. Run `pnpm dlx shadcn@latest info --json` when you need current project context: framework, Tailwind version, aliases, icon library, installed components, and resolved paths.
-4. Use the actual aliases from `components.json` or `shadcn info`; do not assume `@/components/ui` if the project says otherwise.
-5. Check `app/components/ui/` or the resolved `ui` path before importing a component.
-6. For unfamiliar components, run `pnpm dlx shadcn@latest docs <component>` and read the returned docs or examples before coding.
-
-## Agent Native Adapter Rule
-
-Pages, routes, and domain components import controls through the app's local UI
-adapter layer. Never import `@agent-native/toolkit/ui/*` directly in app product
-code. Direct imports bypass `app/design-system.ts` and make Toolkit/Core
-surfaces use different controls from the app.
-
-When shadcn is the app's adapter, add or update the local primitive and keep
-product code on that local import. When a company design system is registered,
-adapt its components to the semantic contracts from
-`@agent-native/toolkit/design-system`; do not recreate a parallel shadcn
-surface. The semantic API is styling-runtime agnostic, so do not require
-Tailwind, CVA, or `className` in customer adapters.
-
-For shared Toolkit features, customize presentation through semantic
-components, a feature-level controller, and product-level render slots. Keep
-the same controller for default and custom views. Use the conformance kit for
-behavior components whose focus, portal, keyboard, dismissal, or stacking
-behavior comes from the company design system.
-
-## Adding Or Updating Components
-
-- Add missing primitives with `pnpm dlx shadcn@latest add <component>` from the app root.
-- Before overwriting an existing component, use `pnpm dlx shadcn@latest add <component> --dry-run` and `--diff` to inspect the change.
-- After adding registry code, read the generated files. Fix import aliases, icon imports, missing subcomponents, and composition issues before using the component.
-- Do not fetch raw component files manually from GitHub when the shadcn CLI can resolve the registry item.
-- If a user asks to add a third-party block but does not name a registry, ask which registry to use instead of guessing.
-
-## Component Composition
-
-- Use existing primitives before custom markup: `Alert` for callouts, `Badge` for small status labels, `Separator` for dividers, `Skeleton` for placeholders, `Table` for tabular data, and `Card` for framed content.
-- Use full card anatomy when appropriate: `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, and `CardFooter`.
-- Dialog, Sheet, Drawer, and AlertDialog content must include an accessible title. Use visually hidden titles only when the visible UI already communicates the title.
-- Put items inside their group components: `SelectItem` in `SelectGroup`, `DropdownMenuItem` in `DropdownMenuGroup`, `CommandItem` in `CommandGroup`, and equivalent menu groups.
-- `TabsTrigger` belongs inside `TabsList`.
-- `Avatar` always needs `AvatarFallback`.
-- Buttons do not have magic loading props. Compose loading with `disabled`, `Spinner`, and clear text.
-
-## Forms And Inputs
-
-- Use the app's shadcn form primitives instead of raw div stacks.
-- If `Field`, `FieldGroup`, `FieldSet`, or `InputGroup` are installed or worth adding, use them for form layout, grouped fields, and input add-ons.
-- Do not place buttons inside inputs with absolute positioning. Use `InputGroup` and `InputGroupAddon` when available.
-- Use `ToggleGroup` for small option sets, `RadioGroup` for one-of-many choices, `Checkbox` for multi-select, `Switch` for settings toggles, `Select` or `Combobox` for predefined choices, and `Slider` or numeric input for numeric values.
-- Validation must be accessible: pair visual invalid states with `aria-invalid`, and connect descriptions/errors to controls.
-
-## Styling And Theming
-
-- Use semantic tokens (`bg-background`, `text-foreground`, `text-muted-foreground`, `bg-primary`, `border-border`, `text-destructive`) instead of raw colors for reusable app UI.
-- Prefer built-in variants and sizes before custom classes.
-- Use `className` mostly for layout and spacing; avoid overriding component colors and typography unless the component is intentionally being extended.
-- Use `gap-*` instead of `space-x-*` / `space-y-*`.
-- Use `size-*` when width and height are equal.
-- Use `truncate` for single-line clipping.
-- Use `cn()` for conditional classes.
-- 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.
-- If registry code imports a different icon package, replace those imports with Tabler equivalents before finishing.
-- Let shadcn components size icons through their CSS. Avoid manual icon sizing inside buttons, menus, alerts, and sidebars unless the local component API requires it.
-
-## Base-Specific APIs
-
-Check the project context before using trigger composition APIs:
-
-- Radix-based components use `asChild` for custom triggers.
-- Base UI components may use `render` and sometimes `nativeButton={false}`.
-
-Do not wrap triggers in extra divs just to place a Button or Link inside them.
-
-## Related Skills
-
-- **frontend-design** — Product UX, visual direction, responsive polish, and verification
-- **customizing-agent-native** — Registered design systems, controllers, slots, conformance, and ejection
-- **actions** — Data fetching and mutation patterns for agent-native apps
-- **security** — User data, forms, external input, and action safety

package/corpus/core/src/templates/chat/.agents/skills/upgrade-agent-native/SKILL.md

@@ -1,122 +0,0 @@
----
-name: upgrade-agent-native
-description: >-
-  Bring an older Agent Native app or workspace current. Use when updating
-  @agent-native/core, fixing a broken upgrade, or when tempted to patch or
-  override core/dispatch packages to make an old branch run.
-scope: dev
-metadata:
-  internal: true
----
-
-# Upgrade Agent Native
-
-## Rule
-
-When an older Agent Native app/branch needs to run on current packages, use
-`agent-native upgrade`. Never "fix" upgrade breakage with
-`pnpm.overrides`, `patchedDependencies`, `resolutions`, local patches, or
-edits under `node_modules/@agent-native/*` — especially not against
-`@agent-native/core` or `@agent-native/dispatch`.
-
-## Why
-
-Agents often respond to a failed core bump by inventing framework patches and
-dispatch behavior overrides. That hides the real app-level break, drifts from
-upstream, and makes the next upgrade worse. The supported path is bump →
-install → refresh scaffold skills → verify, then fix **app** code only.
-
-## How
-
-1. **Preview migration codemods first**
-
-   ```bash
-   npx @agent-native/core@latest upgrade --codemods
-   ```
-
-   Codemods are preview-by-default: read the diff before applying it. Do not
-   manually edit imports before running this command; the migration manifest is
-   the source of truth for renamed specifiers and symbols.
-
-2. **Apply the reviewed codemods, then run the upgrade**
-
-   ```bash
-   npx @agent-native/core@latest upgrade --codemods --yes
-   npx @agent-native/core@latest upgrade
-   ```
-
-   Or from an already-installed CLI: `pnpm exec agent-native upgrade` /
-   `agent-native upgrade`.
-
-   What it does:
-
-   - Blocks (unless `--force`) when `@agent-native/*` overrides/patches exist
-   - Rewrites non-local `@agent-native/*` dependency pins to `latest`
-   - Runs the package manager install
-   - Runs `skills update scaffold --project`
-   - Runs `typecheck` when the project has that script
-
-3. **Pull upstream template changes (optional, separate from the bump)**
-
-   `agent-native upgrade` moves package versions. It never touches files that
-   were copied out of a template at scaffold time, so template fixes and
-   improvements do not arrive with a bump.
-
-   ```bash
-   agent-native template status        # recorded ref vs latest, drift counts
-   agent-native template diff          # what upstream changed, read-only
-   agent-native template sync          # 3-way merge it into the app
-   ```
-
-   `sync` defaults to the ref matching the installed `@agent-native/core`, so
-   run it after `upgrade`. It merges per file against a pristine baseline
-   stored in `refs/agent-native/template-baseline/<app-path>`; files upstream
-   did not touch are left alone, and real collisions get conflict markers.
-   After resolving markers, run `agent-native template accept` — the baseline
-   deliberately does not advance past an unresolved merge.
-
-   Apps scaffolded before provenance existed have no baseline. Create one
-   with `agent-native template baseline` before the first sync.
-
-4. **If upgrade or typecheck fails**
-
-   - Read the concrete error
-   - Fix **app** source, actions, config, or env — not framework packages
-   - Re-run `agent-native upgrade` or `pnpm typecheck`
-   - Stop and ask the user if you cannot fix the app-level error
-
-   Intentional app-level UI customization is a separate workflow. Read
-   `customizing-agent-native` when the product needs to own a selectively
-   copied component; do not use that path to reproduce framework runtime
-   behavior or hide version skew.
-
-5. **Dry-run / partial runs**
-
-   ```bash
-   agent-native upgrade --dry-run
-   agent-native upgrade --skip-verify
-   agent-native upgrade --skip-install   # package.json bumps only
-   agent-native doctor --only migration-manifest
-   ```
-
-   `migration-manifest` has no opt-out. Run it in CI before upgrading to find
-   imports that will break, then use `npx @agent-native/core@latest upgrade --codemods`
-   to preview the supported rewrite.
-
-## Don't
-
-- Don't add `pnpm.overrides`, `overrides`, `resolutions`, or
-  `patchedDependencies` for any `@agent-native/*` package
-- Don't edit `node_modules/@agent-native/core` or
-  `node_modules/@agent-native/dispatch`
-- Don't invent local "dispatch behavior" shims to paper over version skew
-- Don't keep iterating with more framework patches after a failed install
-- Don't skip `skills update scaffold --project` after a core bump (the
-  upgrade command does this for you)
-
-## Related Skills
-
-- **self-modifying-code** — Tier 4: framework packages are off limits
-- **agent-native-docs** — version-matched docs after the bump
-- **customizing-agent-native** — intentional app-owned UI copies, not upgrade patches
-- **portability** — keep app code provider-agnostic across upgrades

package/corpus/core/src/templates/chat/.env.example

@@ -1,5 +0,0 @@
-# Custom health check message
-PING_MESSAGE=pong
-
-# Skip login/signup (local dev / preview only)
-# AUTH_DISABLED=true