@agent-native/core 0.101.14 → 0.102.1

package/corpus/templates/tasks/.agents/skills/security/SKILL.md

@@ -0,0 +1,280 @@
+---
+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>`.
+
+## 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/templates/tasks/.agents/skills/self-modifying-code/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: self-modifying-code
+description: >-
+  How the agent can modify the app's own source code. Use when the agent needs
+  to edit components, routes, styles, or scripts, when designing UI for agent
+  editability, or when deciding what the agent should and shouldn't modify.
+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 patches, vendored copies, or invented "dispatch/core behavior"
+  shims meant to paper over a version skew or failed upgrade
+
+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 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
+- **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/templates/tasks/.agents/skills/shadcn-ui/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: shadcn-ui
+description: >-
+  Use when adding, updating, debugging, styling, or composing shadcn/ui
+  components, forms, dialogs, menus, charts, sidebars, themes, registries, or
+  any project with a components.json file.
+scope: dev
+source: https://ui.shadcn.com/docs/skills
+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. Run `pnpm dlx shadcn@latest info --json` when you need current project context: framework, Tailwind version, aliases, icon library, installed components, and resolved paths.
+3. Use the actual aliases from `components.json` or `shadcn info`; do not assume `@/components/ui` if the project says otherwise.
+4. Check `app/components/ui/` or the resolved `ui` path before importing a component.
+5. For unfamiliar components, run `pnpm dlx shadcn@latest docs <component>` and read the returned docs or examples before coding.
+
+## 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
+- **actions** — Data fetching and mutation patterns for agent-native apps
+- **security** — User data, forms, external input, and action safety

package/corpus/templates/tasks/.agents/skills/stay-within-limits/README.md

@@ -0,0 +1,61 @@
+# /stay-within-limits
+
+Keep long-running agent work inside model and account usage windows.
+
+`/stay-within-limits` gives coding agents a lightweight budget loop for broad,
+parallel, or multi-hour work. The agent checks current 5-hour and weekly usage,
+runs work in bounded waves, and pauses before it crosses the limit instead of
+burning through the last usable budget mid-task.
+
+## What It Does
+
+- Checks 5-hour and weekly usage before substantial work and between waves.
+- Uses waves of at most 3 parallel subagents by default.
+- Pauses new work when either window reaches 95% of its limit.
+- Resumes only after re-checking that the actual window or block is clear.
+- Makes wake prompts self-contained so work can continue after a long pause.
+- Carries the remaining plan, verification steps, and delegation stop
+  conditions into the resume prompt.
+- Documents the Claude Code-compatible `ccusage` command while allowing host
+  usage tools to take priority.
+
+## When To Use It
+
+Use this for long-running coding sessions, PR babysitting, broad reviews,
+multi-wave refactors, large research tasks, or any task where parallel agents
+could exhaust the current 5-hour or weekly budget.
+
+Skip it for small one-shot edits where checking budget would add more ceremony
+than value.
+
+## Claude Code Usage Check
+
+When Claude Code does not expose a better first-party usage signal, use:
+
+```sh
+npx -y ccusage@latest blocks --active --json
+```
+
+The agent should read the active block start, current usage or cost, and time
+remaining. On wake, it should compare the block start timestamp with the
+previous check rather than trusting elapsed time alone.
+
+## Resume Pattern
+
+For hosts with a wake/resume tool, the wake prompt should restate the remaining
+plan, the 95% pause threshold, the wave throttle, the exact usage check, and the
+rule to reschedule if the limit is still too high. If more delegated work
+remains, include the next wave's scope, verification commands, and stop
+conditions so the resumed agent does not depend on old chat momentum.
+
+For waits longer than an hour, chain wakeups. For budget pauses, preserving the
+usage window matters more than keeping the prompt cache warm.
+
+## Install
+
+```sh
+npx @agent-native/skills@latest add --skill stay-within-limits --update-instructions
+```
+
+Use `--update-instructions` when you want the 5-hour and weekly limit convention
+added to `AGENTS.md` or `CLAUDE.md` automatically.

package/corpus/templates/tasks/.agents/skills/stay-within-limits/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: stay-within-limits
+description: Use when long-running or parallel agent work must respect 5-hour and weekly usage limits by checking usage between waves, pausing near the cap, and resuming only when the window is clear.
+---
+
+# Stay Within Limits
+
+Keep long-running agent work inside the current 5-hour and weekly usage windows.
+Check usage before launching substantial work and between waves of parallel
+subagents. If an active 5-hour or weekly limit is at or above 95%, pause new
+work until the window is clear enough to continue safely.
+
+## Core Loop
+
+1. Run a bounded wave of work. Default to at most 3 parallel subagents unless
+   the user or host gives a different throttle.
+2. Wait for the wave to finish. Do not interrupt in-flight subagents just to
+   save budget; that usually loses work.
+3. Check current 5-hour and weekly usage with the host's usage/budget tool.
+4. If either window is at or above 95%, stop launching work and schedule a
+   self-contained resume when the relevant window should clear.
+5. On resume, re-check the real window or block before continuing. Do not trust
+   elapsed wall-clock time alone.
+
+## Usage Signals
+
+Prefer a first-party host usage tool when available. In Claude Code, use:
+
+```sh
+npx -y ccusage@latest blocks --active --json
+```
+
+Use the JSON to identify the active block start, current cost or percentage, and
+time remaining. On wake, compare the active block start timestamp with the
+previous one; a new timestamp is stronger evidence than "enough time passed."
+
+If the tool reports cost instead of a direct percentage, convert through the
+current account limit when known. For Claude Max-style 5-hour blocks, some users
+prefer an earlier caution threshold around $500-550; treat that as a
+user-configured guardrail, not a universal rule. The default stop rule is still
+95% of the active 5-hour or weekly limit.
+
+## Pausing And Resuming
+
+When a wake/resume tool is available, schedule a wakeup for:
+
+```txt
+min(3600, secondsUntilWindowClears)
+```
+
+If the runtime clamps wake delays to 60-3600 seconds, chain wakeups for longer
+waits. Each wakeup should re-check usage, reschedule if still over budget, and
+continue only when the window is safely below the threshold.
+
+Make wake prompts self-contained. Include:
+
+- The remaining plan.
+- The check-then-reschedule rule.
+- The 95% threshold and wave throttle.
+- The exact usage command or host usage tool to run.
+- The previous block/window identifier when available.
+- The next verification steps.
+- The next wave's handoff packets, including scope, verification commands, and
+  stop conditions, if delegation will resume.
+
+## Choosing The Wait Mechanism
+
+- Use a wake/resume tool when the agent needs instructions attached to the
+  future resume.
+- Use a background sleep or watcher for fixed timers and things a process can
+  observe directly.
+- Use cron or recurring schedules only for recurring fresh-session work.
+
+Avoid short-interval polling for things the host will notify you about, such as
+background task or subagent completion. For budget pauses, a prompt-cache miss
+after a long sleep is acceptable; preserving the limit matters more.
+
+## Reporting
+
+If you pause, tell the user which window is over threshold, the observed usage,
+when you scheduled or expect the next check, and what work remains. Keep enough
+state in the wake prompt that the next turn can resume without relying on
+conversation momentum.