@frontera-sdk/cli 1.43.10 → 1.44.0

package/src/templates/next-skills.ts

@@ -0,0 +1,1216 @@
+/**
+ * The pattern skills shipped inside every scaffolded App.
+ *
+ * These are written to the same anatomy as the in-repo Sebati skills, because
+ * that anatomy is what makes a skill usable by a small model: a description
+ * that says WHEN to load it, rules stated as decisions rather than advice, one
+ * excerpt copied from code that actually exists in the project, the naming
+ * conventions, an explicit red-flag list, and the command that proves the work.
+ *
+ * Two constraints keep them honest:
+ *
+ *  - Every `frontera …` invocation and every `--flag` named here is asserted
+ *    against the real command registry by `skill-accuracy.test.ts`. A skill
+ *    that advertises a command nobody implemented has happened twice in this
+ *    repo; it is now a test failure rather than a review question.
+ *  - Every path named here is a path the scaffold writes. A rule pointing at a
+ *    directory that does not exist teaches an agent to invent one.
+ *
+ * Lines are authored as arrays of strings so markdown backticks need no
+ * escaping — these files are mostly code spans, and an escaped skill is an
+ * unreadable skill.
+ */
+
+interface Skill {
+  name: string
+  description: string
+  body: string[]
+}
+
+/** Skill file map, keyed by path relative to the project root. */
+export function nextSkillFiles(): Record<string, string> {
+  return Object.fromEntries(
+    SKILLS.map((skill) => [
+      `.agents/skills/${skill.name}/SKILL.md`,
+      `---\nname: ${skill.name}\ndescription: ${skill.description}\n---\n\n${skill.body.join('\n')}\n`,
+    ]),
+  )
+}
+
+/** Names of the shipped skills, in dispatcher order. */
+export const NEXT_SKILL_NAMES = [
+  'using-frontera-app-patterns',
+  'frontera-app-project',
+  'frontera-app-routing',
+  'frontera-app-session',
+  'frontera-blueprint-data',
+  'frontera-blueprint-actions',
+  'frontera-app-ui',
+  'frontera-design-tokens',
+  'frontera-ui-components',
+  'frontera-query-ui-states',
+  'frontera-app-tables',
+  'frontera-app-testing',
+  'frontera-app-security',
+  'frontera-app-release',
+] as const
+
+const dispatcher: Skill = {
+  name: 'using-frontera-app-patterns',
+  description:
+    'Use at the START of any task in a Frontera App — a Next.js project with frontera.config.json that deploys through the frontera CLI. Establishes the architecture, names the reference feature to copy, and routes you to the pattern skill for the layer you are touching.',
+  body: [
+    '# Frontera App patterns',
+    '',
+    'The dispatcher. Load this first, then the skill for the layer you touch. These patterns',
+    'are already followed by the code in this project — match them, do not start a second style.',
+    '',
+    '## Am I in a Frontera App?',
+    '',
+    'Yes if the project has ANY of: `frontera.config.json`, `@frontera-sdk/core` in',
+    '`package.json`, a `.frontera/` directory, or `.agents/skills/frontera-app-*/`.',
+    '',
+    '## The reference feature — read it before writing anything',
+    '',
+    'One complete vertical slice ships with the scaffold, and every rule below is visible in it:',
+    '',
+    '```text',
+    'src/app/page.tsx                          thin route adapter',
+    'src/ui/app-shell/app-shell.tsx            the frame, aware of embedded vs standalone',
+    'src/ui/object-explorer/                   the feature folder',
+    'src/lib/blueprint/objects/objects-hooks.ts  the data layer + pure helpers',
+    'src/lib/blueprint/objects/__tests__/      the tests those helpers earn',
+    '```',
+    '',
+    'Copying that shape is faster and more accurate than reasoning from these skills alone.',
+    '',
+    '## Invariants — all layers',
+    '',
+    '1. **Bun runs everything.** `bun install`, `bun run <script>`, `bun test`. Never npm/yarn/pnpm.',
+    '2. **The result is static files.** `bun run build` must emit `out/index.html`. There is no',
+    '   server runtime: no Server Actions, no request-time Route Handlers, no middleware.',
+    '3. **One concern per file.** One React component per file under `src/ui/`. Data access and',
+    '   components never share a file. No `index.ts` barrels anywhere.',
+    '4. **Components take props; hooks fetch.** Every Blueprint read lives in',
+    '   `src/lib/blueprint/<domain>/`.',
+    '5. **The server filters, sorts, cursor-pages and counts.** Narrowing a fetched page is the single',
+    '   most common way an App silently lies about the data.',
+    '6. **Browser code holds no secret.** Not in source, not in `NEXT_PUBLIC_*`, not in `.env`.',
+    '7. **User-visible strings come from `src/lib/copy.ts`.**',
+    '',
+    '## Router — load the skill for what you are touching',
+    '',
+    '| Working on | Path signal | Skill |',
+    '|---|---|---|',
+    '| Structure, dependencies, scripts, build config | `package.json`, `next.config.ts` | **frontera-app-project** |',
+    '| Pages, links, deep links, record selection | `src/app/**/page.tsx` | **frontera-app-routing** |',
+    '| Session, host integration, local development | `src/app/providers.tsx` | **frontera-app-session** |',
+    '| Reading objects, filters, paging, aggregates | `src/lib/blueprint/` | **frontera-blueprint-data** |',
+    '| Changing data — submitting an Action, approvals | `src/lib/blueprint/` | **frontera-blueprint-actions** |',
+    '| Feature folders, composition, responsiveness | `src/ui/<feature>/` | **frontera-app-ui** |',
+    '| Colors, elevation, dark mode, CSS variables | `src/app/globals.css` | **frontera-design-tokens** |',
+    '| Shared primitives, shadcn components | `src/components/ui/` | **frontera-ui-components** |',
+    '| Loading, empty, error, stale rendering | any query consumer | **frontera-query-ui-states** |',
+    '| Tables, server paging, column definitions | `*-table.tsx`, `*-columns.ts` | **frontera-app-tables** |',
+    '| Tests | `src/**/__tests__/` | **frontera-app-testing** |',
+    '| External requests, CSP, secrets, iframe | `frontera.config.json` | **frontera-app-security** |',
+    '| Build, preview, promote, rollback | deployment | **frontera-app-release** |',
+    '',
+    'A feature touches several layers — load in dependency order: project (where) → blueprint-data',
+    '(reads) → ui (shape) → query-ui-states/tables (rendering) → release (ship). Do not load all of them.',
+    '',
+    'For the CLI rather than the code — logging in, discovering data, packaging, deploying — load',
+    '`.agents/skills/using-frontera-cli/SKILL.md` when it is present.',
+    '',
+    '## The only write path',
+    '',
+    'Blueprint Actions. There is no direct object mutation, and no service route to reach around',
+    'them because the browser can construct a URL. Reads are `useObjects` and friends; writes are',
+    '`useSubmitAction` — see **frontera-blueprint-actions**.',
+    '',
+    '## Verify before claiming done',
+    '',
+    '```bash',
+    'bun run check',
+    '```',
+    '',
+    'That runs typecheck, then tests, then the build. For anything touching data, also run it',
+    'against real data:',
+    '',
+    '```bash',
+    'frontera app dev',
+    '```',
+  ],
+}
+
+const project: Skill = {
+  name: 'frontera-app-project',
+  description:
+    'Use when changing project structure, dependencies, scripts, or build configuration in a Frontera App — which file owns which concern, what a static export forbids, and which command is the gate before claiming done.',
+  body: [
+    '# Project contract',
+    '',
+    'The build happens on a laptop or in customer CI. Frontera serves an uploaded immutable',
+    'artifact; it never installs dependencies and never runs Next.',
+    '',
+    '## Rules',
+    '',
+    '- Files own separate concerns and do not borrow from each other:',
+    '  - `package.json` — package identity, scripts, dependencies, `packageManager`. No `frontera` field.',
+    '  - `frontera.config.json` — `displayName`, `outputDirectory`, `routing`, `connectDomains`, `resourceDomains`.',
+    '  - `next.config.ts` — static-export behaviour.',
+    '  - `.frontera/state.json` — environment binding written by the CLI. Gitignored; never author it.',
+    '  - `.env*` — public build values only. A credential here ships to the browser.',
+    '- Keep the required Next configuration: `output: "export"`, `trailingSlash: true`,',
+    '  `images.unoptimized: true`, and `transpilePackages` for both SDK packages. The artifact',
+    '  contract is `outputDirectory: "out"` with `routing: "filesystem"` — it describes files, not a framework.',
+    '- Use the public versioned `@frontera-sdk/core` and `@frontera-sdk/blueprint` packages. Do not',
+    '  vendor, copy or patch SDK source into a Next App — that is the legacy Vite scaffold only.',
+    '- Scripts are a fixed set with fixed meanings. `dev` MUST stay `next dev`: `frontera app dev`',
+    '  spawns `bun run dev` and passes the host and port it chose.',
+    '- Add a dependency only if it runs in a browser bundle. No `node:` built-ins, no server SDKs,',
+    '  no package that needs a secret to be useful.',
+    '- `bun run check` is the gate. `next build` does not type-check the project and `tsc` never',
+    '  sees the export constraints, so neither one alone proves anything.',
+    '- No linter ships with the scaffold. If a project adds one, wire it into `check` in the same',
+    '  commit, or it will never run again.',
+    '',
+    '```jsonc',
+    '// package.json',
+    '"scripts": {',
+    '  "dev": "next dev",                    // spawned by `frontera app dev` — do not rename',
+    '  "build": "next build",                // must produce out/index.html',
+    '  "typecheck": "tsc --noEmit",',
+    '  "test": "bun test src",',
+    '  "check": "bun run typecheck && bun run test && bun run build",',
+    '  "blueprint:types": "frontera blueprint generate-types",',
+    '  "blueprint:types:check": "frontera blueprint generate-types --check",',
+    '  "deploy": "bun run check && frontera app deploy"',
+    '}',
+    '```',
+    '',
+    '## Unsupported',
+    '',
+    'Middleware and proxy files, Server Actions, request-time Route Handlers, request-time',
+    'rendering, a custom Node server, optimized Next Image endpoints, and runtime-only dynamic',
+    'routes. Each of these builds locally and fails on the deployed artifact, which is the worst',
+    'possible time to find out.',
+    '',
+    '## Naming',
+    '',
+    'Filenames kebab-case (`object-table.tsx`, `use-debounced-value.ts`). Exports PascalCase for',
+    'components and types, camelCase for hooks, functions and constants. Import through the `@/`',
+    'alias, always to an explicit file.',
+    '',
+    '## Red Flags — STOP',
+    '',
+    '- A `frontera` key added to `package.json`, or hosting configuration in `next.config.ts`.',
+    '- Renaming or removing the `dev` script.',
+    '- `@frontera-sdk/*` source copied into `src/`.',
+    '- A dependency that needs a server, a secret, or a Node built-in.',
+    '- Claiming done after `bun run build` alone.',
+    '',
+    '## Verification',
+    '',
+    '```bash',
+    'bun run check',
+    '```',
+    '',
+    '```bash',
+    'ls out/index.html',
+    '```',
+    '',
+    '## Scope',
+    '',
+    'Applies to every Next.js Frontera App. The legacy Vite scaffold (`frontera app init` with',
+    '`--framework react`) vendors SDK source instead and is governed by its own bundled skills.',
+  ],
+}
+
+const routing: Skill = {
+  name: 'frontera-app-routing',
+  description:
+    'Use when adding routes, navigation, deep links, or record-selection flows in a Frontera App — fixed exported routes only, search params instead of bracket routes, thin page adapters, and how init.path maps to a route.',
+  body: [
+    '# Routing',
+    '',
+    'Only routes that exist as files after `bun run build` are servable. `src/app/shipments/page.tsx`',
+    'becomes `out/shipments/index.html` and is served at `/shipments/`.',
+    '',
+    '## Rules',
+    '',
+    '- Keep `page.tsx` a thin adapter: read configuration or search params, choose a layout wrapper,',
+    '  render ONE component from `src/ui/<feature>/<feature>.tsx`. No feature JSX, no hooks, no reads.',
+    '- Do not model runtime identity with a bracket route (`src/app/shipments/[id]/`). Nothing',
+    '  generates those pages at build time. Use a fixed route plus a search parameter',
+    '  (`/shipments/?id=…`) or client state, and validate and encode the value before it reaches a URL.',
+    '- Next owns application routing. Use `Link`, `useRouter` and `useSearchParams` normally.',
+    '- `useFronteraApp().navigate(path)` synchronizes the HOST url while embedded. It is deliberately',
+    '  a no-op standalone and locally. It is not a replacement for `router.push`; call both when a',
+    '  navigation should also change the platform address bar.',
+    '- On embedded startup `init.path` is the platform-owned deep link. Map it to a route your build',
+    '  actually exported, and give unknown paths an explicit not-found experience.',
+    '- A page that reads search params needs a Suspense boundary under static export. Keep the',
+    '  reading component inside the feature folder so the boundary lives in one place.',
+    '',
+    '```tsx',
+    '// src/app/page.tsx — the whole file',
+    "import { STARTER_OBJECT_TYPE, STARTER_SEARCH_PROPERTY } from '@/lib/blueprint/starter'",
+    "import { AppShell } from '@/ui/app-shell/app-shell'",
+    "import { ObjectExplorer } from '@/ui/object-explorer/object-explorer'",
+    '',
+    'export default function HomePage() {',
+    '  return (',
+    '    <AppShell>',
+    '      <ObjectExplorer objectType={STARTER_OBJECT_TYPE} searchProperty={STARTER_SEARCH_PROPERTY} />',
+    '    </AppShell>',
+    '  )',
+    '}',
+    '```',
+    '',
+    '## Naming',
+    '',
+    'Page component `<Thing>Page`; layout `<Area>Layout`; route directories kebab-case and plural',
+    'when they list (`shipments/`). Feature components keep their own names.',
+    '',
+    '## Red Flags — STOP',
+    '',
+    '- A bracket route directory.',
+    '- Assuming an SPA root fallback exists — a filesystem export has none.',
+    '- Feature UI, hooks or data access living under `src/app/`.',
+    '- Co-located `*-client.tsx` siblings or `components/` trees under `src/app/`.',
+    '- Record identifiers in path segments that no build step generated.',
+    '- Two navigation systems with different active-state rules.',
+    '',
+    '## Verification',
+    '',
+    '```bash',
+    'bun run build',
+    '```',
+    '',
+    'Then confirm each intended route exists as a directory with an `index.html` under `out/`.',
+    '',
+    '## Scope',
+    '',
+    'Applies to every Next.js Frontera App. Bracket routes become legal only if a build-time',
+    '`generateStaticParams` enumerates them — which requires data at build time that an App',
+    'generally does not have.',
+  ],
+}
+
+const session: Skill = {
+  name: 'frontera-app-session',
+  description:
+    'Use when working on authentication, App initialization, host integration, or local development in a Frontera App — the single provider mount, the three transports, what useFronteraApp returns, and how to treat the token.',
+  body: [
+    '# Sessions',
+    '',
+    'The App has no data scope until a session hands it one. `FronteraAppProvider` completes that',
+    'handshake and only then renders children, so no hook below it needs a "not ready" branch.',
+    '',
+    '## Rules',
+    '',
+    '- Mount ONE `FronteraAppProvider` in `src/app/providers.tsx`, with domain providers passed as a',
+    '  list (`providers={[blueprintProvider]}`). A second data domain is one more array entry.',
+    '- Never recreate the bridge, the session fetch, or the query client in application code. A',
+    '  per-route provider stack forks the session and the cache; the symptom is a second handshake',
+    '  and rows that will not refresh.',
+    '- The provider picks exactly one configured transport before connecting:',
+    '  - `embedded` — validated postMessage bridge to the Frontera parent.',
+    '  - `standalone` — same-origin `/.frontera/session` backed by App cookies.',
+    '  - `local` — exact-origin loopback broker started by `frontera app dev`.',
+    '- Every mode supplies the same `BridgeInit` and client, so feature code branches on `mode` only',
+    '  for presentation (chrome density, external links), never for data access.',
+    '- Treat `init.token` as opaque and short-lived. Do not cache it, put it in state, log it, send it',
+    '  anywhere, or retry an authorization failure with a different credential.',
+    '- Local development is `frontera app dev`. It mints a short-lived App token, keeps the stored CLI',
+    '  key in the broker, and owns `NEXT_PUBLIC_FRONTERA_DEV_SESSION_ENDPOINT` — never hand-write that',
+    '  variable. `bun run dev` alone starts Next with no session: fine for layout, useless for data.',
+    '',
+    '```tsx',
+    "'use client'",
+    '',
+    "import { useFronteraApp } from '@frontera-sdk/core/react'",
+    '',
+    'export function AppShell({ children }: { children: React.ReactNode }) {',
+    '  const { mode, init } = useFronteraApp()',
+    '  // mode: "embedded" | "standalone" | "local"',
+    '  // init: { appId, version, orgId, workspaceId, theme, state, path? }',
+    '  return <section data-mode={mode}>{children}</section>',
+    '}',
+    '```',
+    '',
+    '## Naming',
+    '',
+    'Root component `Providers` in `src/app/providers.tsx`. Shell component `AppShell` in',
+    '`src/ui/app-shell/app-shell.tsx`. Session values are read with `useFronteraApp()`, never threaded',
+    'through props.',
+    '',
+    '## Red Flags — STOP',
+    '',
+    '- A second `FronteraAppProvider`, or a provider stack under a route layout.',
+    '- Reading a token out of context to pass to `fetch`.',
+    '- Writing `NEXT_PUBLIC_FRONTERA_DEV_SESSION_ENDPOINT` by hand into `.env`.',
+    '- Branching data access on `mode`.',
+    '- Rendering the app before the session resolves, or adding a "not ready" guard inside a feature.',
+    '',
+    '## Verification',
+    '',
+    '```bash',
+    'frontera app dev',
+    '```',
+    '',
+    'The App should mount with real rows. A page that renders but 401s on every read means the',
+    'session is not the one you think it is.',
+    '',
+    '## Scope',
+    '',
+    'Applies to every Next.js Frontera App. Standalone mode requires the App to be published and',
+    'authorized; embedded mode is what the platform surface uses.',
+  ],
+}
+
+const blueprintData: Skill = {
+  name: 'frontera-blueprint-data',
+  description:
+    'Use when reading Blueprint data in a Frontera App — the src/lib/blueprint/<domain>/ data layer, useObjects/useObjectInstance/useAggregate, server-side where clauses, paging, totals, and typed contracts from bun run blueprint:types.',
+  body: [
+    '# Blueprint reads',
+    '',
+    'Blueprint is the data contract. Every read is scoped by the credential the session handed over,',
+    'so an object type this workspace was not granted is simply absent.',
+    '',
+    '## Rules',
+    '',
+    '- One folder per domain: `src/lib/blueprint/<domain>/<domain>-hooks.ts`. Never two domains in one',
+    '  file, never a read inside a component, never an `index.ts` barrel. Consumers import the explicit file.',
+    '- Discover what exists before writing a query:',
+    '',
+    '```bash',
+    'frontera blueprint list',
+    '```',
+    '',
+    '```bash',
+    'frontera blueprint get <apiName>',
+    '```',
+    '',
+    '- Generate the typed contract, then commit it:',
+    '',
+    '```bash',
+    'bun run blueprint:types',
+    '```',
+    '',
+    '  It writes `src/generated/frontera-blueprint.ts`, a deterministic projection of the Blueprint',
+    '  this workspace is granted. Never edit that file, never copy server ids into source, and rerun',
+    '  it after a Blueprint publication or a grant change. `bun run blueprint:types:check` is an',
+    '  authenticated freshness gate for CI — install, build, dev and deploy never contact Blueprint.',
+    '- Pass LITERAL api names so inference works: `useObjects("Shipment")` types rows, filters, sorts',
+    '  and projections from the committed contract. A `string` variable erases all of it.',
+    '- Choose the hook by the question: `useObjects` for rows, `useObjectInstance` for one selected',
+    '  record, `useAggregate` for measures, `useObjectQuery` when the object type is dynamic.',
+    '- Filter, order, cursor-page and aggregate on the SERVER. `where` compiles into the object set.',
+    '- A total is its own `useAggregate` over the SAME object set — build the filter once and share it.',
+    '  `rows.length` is the size of a page.',
+    '- Use `enabled` for anything depending on a runtime value, and `placeholderData: keepPreviousData`',
+    '  for paging so the table dims instead of collapsing.',
+    '- Keep query inputs serializable and stable; the SDK derives cache keys from the request.',
+    '- Extract pure helpers (filter builders, aggregate parsing, formatting) and test them. They are the only',
+    '  part of a data layer that can be tested without a session.',
+    '- Do not collapse forbidden, unknown object type, network failure and a successful empty result',
+    '  into one empty array. They are four different things to say to a customer.',
+    '- This skill is reads. Writes go through Blueprint Actions — see **frontera-blueprint-actions**.',
+    '',
+    '```ts',
+    '// src/lib/blueprint/shipment/shipment-hooks.ts',
+    "import { keepPreviousData } from '@tanstack/react-query'",
+    "import { useAggregate, useObjects } from '@frontera-sdk/blueprint/hooks'",
+    "import { objectsOf } from '@frontera-sdk/blueprint/types'",
+    "import type { BlueprintWhereNode } from '@frontera-sdk/blueprint/types'",
+    '',
+    'export const PAGE_SIZE = 25',
+    '',
+    "export function delayedWhere(city?: string): BlueprintWhereNode<'Shipment'> {",
+    "  const status = { property: 'status', op: 'eq', value: 'delayed' } as const",
+    "  return city ? { and: [status, { property: 'city', op: 'eq', value: city }] } : status",
+    '}',
+    '',
+    'export function useDelayedShipments(pageToken: string | undefined, city?: string) {',
+    "  return useObjects('Shipment', {",
+    '    where: delayedWhere(city),',
+    "    orderBy: [{ property: 'promisedAt', dir: 'asc' }],",
+    '    pageToken,',
+    '    pageSize: PAGE_SIZE,',
+    '    placeholderData: keepPreviousData,',
+    '  })',
+    '}',
+    '',
+    'export function useDelayedShipmentTotal(city?: string) {',
+    '  return useAggregate({',
+    "    objectSet: objectsOf('Shipment', delayedWhere(city)),",
+    "    aggregations: [{ alias: 'total', fn: 'count' }],",
+    '    groupBy: [],',
+    '  })',
+    '}',
+    '```',
+    '',
+    '## Naming',
+    '',
+    'Folder = domain, singular for a standalone entity (`shipment`), plural when the entity is',
+    'inherently collective (`api-keys`). Hooks read as questions: `useDelayedShipments`,',
+    '`useShipment`, `useDelayedShipmentTotal`. Filter builders are `<thing>Where`. Constants are',
+    'SCREAMING_SNAKE only for tuning values such as `PAGE_SIZE`.',
+    '',
+    '## Red Flags — STOP',
+    '',
+    '- `rows.filter(...)` or `rows.sort(...)` on data that came back paged.',
+    '- `rows.length` presented as a count.',
+    '- A raw `fetch()` to the platform, or a URL built by hand.',
+    '- A read inside a component, or a `useEffect` that fetches.',
+    '- An object type spelled from memory instead of from `frontera blueprint list`.',
+    '- Editing `src/generated/frontera-blueprint.ts`.',
+    '- A filter used by the rows query but not by the total.',
+    '',
+    '## Verification',
+    '',
+    '```bash',
+    'bun run typecheck',
+    '```',
+    '',
+    '```bash',
+    'frontera app dev',
+    '```',
+    '',
+    'Compare the number under the table with the row count for the same filter in the platform. If',
+    'they disagree, the filtering is happening in the wrong place.',
+    '',
+    '## Scope',
+    '',
+    'Applies to every Frontera App. Before `bun run blueprint:types` has ever run, object names are',
+    'plain strings and rows are untyped — which is why the scaffold starter takes its object type as',
+    'an argument. Real features do not.',
+  ],
+}
+
+const actions: Skill = {
+  name: 'frontera-blueprint-actions',
+  description:
+    'Use when a Frontera App CHANGES data — submitting a Blueprint Action, rendering only the actions a user may invoke, following a request to its outcome, approvals, and optimistic-concurrency versions. Covers useActions, useSubmitAction, useActionRequest and why a successful submit is not a successful write.',
+  body: [
+    '# Blueprint Actions',
+    '',
+    'Actions are the ONLY write path. There is no direct object mutation, and no service route to',
+    'reach around one. An Action is governed: who may invoke it, whether it needs approval, and what',
+    'it did are decided and recorded server-side.',
+    '',
+    '```tsx',
+    "import { useActions, useAction, useSubmitAction, useActionRequest } from '@frontera-sdk/blueprint/action-hooks'",
+    "import { actionEffectOf, recordVersionOf } from '@frontera-sdk/blueprint/action-types'",
+    '```',
+    '',
+    '## Rules',
+    '',
+    '- **Render controls from `useActions()`**, or `useAction(apiName)` for one — never from a',
+    '  hard-coded list. The same page offers different actions to different colleagues, and only the',
+    '  server knows which. A button that 403s on click is worse than one that was never drawn.',
+    '- An empty discovery list in development is almost always permissions, not a bug: an Action is',
+    '  hidden unless it is published, deployed, AND its invoke capability is held by your role.',
+    '- **A submit is not a write.** `useSubmitAction(action)` resolves when the Request is RECORDED;',
+    '  dispatch happens on a background worker. A success toast in `onSuccess` claims something the',
+    '  App does not know yet.',
+    '- Follow the returned id with `useActionRequest(requestId)`. It polls while the lifecycle is',
+    '  non-terminal and stops once it settles — do not hand-roll `setInterval`.',
+    '- Decide what to SAY with `actionEffectOf(request)`: `pending`, `applied`, `refused`, or',
+    '  `uncertain`. `uncertain` means the outcome could not be established — rendering it as failure',
+    '  invites a duplicate submit, rendering it as success is a lie. Say it is being checked.',
+    '- Approval is a mode, not an afterthought. When `action.approval.mode === "required"`, submitting',
+    '  creates a Request someone else decides; the reviewer path is `useDecideActionRequest()`, which',
+    '  takes `{ requestId, decision, reason }`. Do not design a flow that assumes instant application.',
+    '- Editing an existing record: pass `expectedVersion: recordVersionOf(instance.data)`, read from',
+    '  `useObjectInstance` — a LIST row does not carry the version. Omitting it does not fail; the',
+    '  compare-and-set is skipped and two people overwrite each other with no refusal and no evidence.',
+    '- Idempotency keys are minted per `mutate` call. That is the correct lifetime — a retried network',
+    '  call cannot double-apply, a second click is a second intent — so do not supply your own.',
+    '- Refresh reads when the request reaches a terminal APPLIED state, not when the submit resolves.',
+    '- `inputSchema` on the descriptor is the contract, and the server validates against it. Mirror',
+    '  required fields in the form for a good experience; never treat client validation as the gate.',
+    '',
+    '```tsx',
+    '// src/ui/approve-loan/approve-loan.tsx',
+    "const { action } = useAction('ApproveLoan')",
+    'const submit = useSubmitAction(action)',
+    'const [requestId, setRequestId] = useState<string | null>(null)',
+    'const request = useActionRequest(requestId)',
+    'const effect = actionEffectOf(request.data)',
+    '',
+    '// Not drawn at all when the caller may not invoke it.',
+    'if (!action) return null',
+    '',
+    'return (',
+    '  <>',
+    '    <Button',
+    '      disabled={submit.isPending || effect === "pending"}',
+    '      onClick={() =>',
+    '        submit.mutate(',
+    '          { objectId: loanId, input: { decision: "approve" }, expectedVersion: recordVersionOf(loan.data) },',
+    '          { onSuccess: (created) => setRequestId(created.id) },',
+    '        )',
+    '      }',
+    '    >',
+    '      {copy.loan.approve}',
+    '    </Button>',
+    '    {effect === "pending" && <p>{copy.loan.submitted}</p>}',
+    '    {effect === "applied" && <p>{copy.loan.applied}</p>}',
+    '    {effect === "refused" && <p role="alert">{copy.loan.refused}</p>}',
+    '    {effect === "uncertain" && <p role="alert">{copy.loan.checking}</p>}',
+    '  </>',
+    ')',
+    '```',
+    '',
+    '## Naming',
+    '',
+    'Hooks keep the SDK names. A feature that submits one Action is a folder named after the action',
+    'in kebab-case (`approve-loan/`), and the request-following state stays in the entry component,',
+    'not in the button.',
+    '',
+    '## Red Flags — STOP',
+    '',
+    '- A hard-coded action button, or one rendered before `useAction` returns a descriptor.',
+    '- Success shown when the submit resolves.',
+    '- `setInterval` polling a request.',
+    '- `uncertain` collapsed into success or failure.',
+    '- An edit submitted with no `expectedVersion`, or a version read from a list row.',
+    '- Reads invalidated on submit rather than on a terminal applied state.',
+    '- Any write attempted outside an Action.',
+    '',
+    '## Verification',
+    '',
+    '```bash',
+    'bun run check',
+    '```',
+    '',
+    '```bash',
+    'frontera app dev',
+    '```',
+    '',
+    'Submit one for real and watch it to a terminal state. A flow only tested to the submit call has',
+    'not been tested — that is the half that always works.',
+    '',
+    '## Scope',
+    '',
+    'Applies to every Frontera App that changes data. Authoring the Actions themselves — defining,',
+    'binding and deploying them — is CLI and platform work, not App work.',
+  ],
+}
+
+const ui: Skill = {
+  name: 'frontera-app-ui',
+  description:
+    'Use when creating, splitting, or refactoring a feature under src/ui/ in a Frontera App — the feature folder layout, one component per file, where hooks and helpers go, and designing one capability for both the embedded frame and a standalone page.',
+  body: [
+    '# App UI',
+    '',
+    'Every feature is a folder under `src/ui/`. The layout is not a suggestion: it is what makes a',
+    'feature navigable by someone who has never opened it.',
+    '',
+    '## Canonical layout',
+    '',
+    '```text',
+    'src/ui/<feature>/',
+    '  <feature>.tsx          entry — consumers import THIS file explicitly',
+    '  components/            sub-components, one per file, kebab-case',
+    '    <part>.tsx',
+    '  hooks/                 hooks used only by this feature',
+    '    use-<name>.ts',
+    '  utils.ts               pure helpers shared inside the folder',
+    '  types.ts               types shared inside the folder or with consumers',
+    '```',
+    '',
+    '## Rules',
+    '',
+    '- **Folder name = entry file stem = kebab-case of the exported component.** `ObjectExplorer`',
+    '  lives in `object-explorer/object-explorer.tsx`. Do not shorten the folder.',
+    '- **One React component per file** under `src/ui/`. Even a single sub-component goes in',
+    '  `components/`, not next to the entry file.',
+    '- Promote a flat file to a folder the moment any of these happen: a second component, a hook',
+    '  over ~15 lines, a helper used twice, or a type another module imports.',
+    '- **No barrels.** Import the explicit path: `import { ObjectExplorer } from "@/ui/object-explorer/object-explorer"`.',
+    '- The entry component owns view state and calls the data layer. Sub-components receive data as',
+    '  props and fetch nothing — that is what keeps a filter change from becoming a request inside a cell.',
+    '- Every user-visible string comes from `src/lib/copy.ts`, including empty and error text.',
+    '- Design one capability for two containers, not two designs:',
+    '  - embedded — constrained width and height, platform chrome outside the App, the App owns its',
+    '    own internal scrolling;',
+    '  - standalone — full viewport, direct navigation, room for denser controls.',
+    '- Mobile-first: fluid layouts, no fixed viewport widths, primary controls at least 44px tall,',
+    '  wide content scrolling inside its own container so the page never scrolls sideways.',
+    '- Never hide a workflow on small screens with no replacement. Collapse a secondary rail into a',
+    '  disclosure, do not amputate it.',
+    '- Colors, spacing and elevation come from tokens — see **frontera-design-tokens**.',
+    '- Shared primitives come from the shadcn registry (`bunx --bun shadcn@latest add <name>`), not',
+    '  from hand-written markup — see **frontera-ui-components**.',
+    '',
+    '```tsx',
+    '// src/ui/object-explorer/object-explorer.tsx — the entry owns state, children take props',
+    'const rows = useObjectPage(params)',
+    'return (',
+    '  <section className="flex flex-col gap-4">',
+    '    <ObjectSearch value={search} onChange={handleSearch} />',
+    '    <ObjectTable columns={columns} rows={records} isRefreshing={rows.isFetching} />',
+    '  </section>',
+    ')',
+    '```',
+    '',
+    '## Naming',
+    '',
+    'Filenames kebab-case, always. Components PascalCase, hooks `use<Name>`, helpers camelCase.',
+    'Skeletons are `<part>-skeleton.tsx` next to the part they replace.',
+    '',
+    '## Red Flags — STOP',
+    '',
+    '- A sub-component at the folder root instead of in `components/`.',
+    '- An `index.ts` created "just for re-exports".',
+    '- A PascalCase filename.',
+    '- A component that calls a Blueprint hook and also renders a leaf of the tree.',
+    '- Hardcoded strings instead of `copy`.',
+    '- A layout that assumes the App owns the whole viewport.',
+    '- Hover-only affordances, or icon-only controls with no accessible name.',
+    '',
+    '## Verification',
+    '',
+    '```bash',
+    'bun run check',
+    '```',
+    '',
+    'Then open the App at a narrow width and confirm nothing overflows the page horizontally.',
+    '',
+    '## Scope',
+    '',
+    'Applies to everything under `src/ui/`. `src/components/ui/` follows the primitive conventions',
+    'instead — see **frontera-ui-components**.',
+  ],
+}
+
+const tokens: Skill = {
+  name: 'frontera-design-tokens',
+  description:
+    'Use when styling any Frontera App surface, choosing colors or elevation, or adding a CSS variable — the token utilities in src/app/globals.css, host-driven dark mode, and why a hex literal in a component breaks customer branding.',
+  body: [
+    '# Design tokens',
+    '',
+    'Tailwind v4, CSS-first. `src/app/globals.css` declares raw variables and re-exports them as',
+    'utilities through `@theme inline`. There is no `tailwind.config.*`.',
+    '',
+    '## Rules',
+    '',
+    '- Reference tokens through utility classes: `bg-background`, `text-foreground`, `bg-card`,',
+    '  `text-muted-foreground`, `border-border`, `text-destructive`, `ring-ring`, `rounded-lg`.',
+    '- Pick a surface by stacking depth, not by eye: `surface-inset-deep` < `surface-inset` <',
+    '  `surface` < `surface-raised` < `surface-overlay`, each with `-hover` and `-active` variants.',
+    '- **Never write a raw color in a component** — no `#…`, no `oklch(…)`, no `hsl(…)`. The host',
+    '  writes its palette into these variables at handshake, and a customer brand overrides them.',
+    '  A literal is the one thing branding cannot reach.',
+    '- Dark mode is a class the SDK toggles on `<html>` from the host theme. Style it with the `dark:`',
+    '  variant; never write the selector by hand, and never force a dark shell.',
+    '- Both themes are first class. If a surface only looks right in one of them, it is not done.',
+    '- To add a token, edit BOTH the raw declaration (light and dark) AND the `@theme inline` mirror,',
+    '  or the utility will not exist.',
+    '- `chart-*` colors are for data visualization only, never for UI chrome.',
+    '- Merge classes through `cn()` from `@/lib/utils`, with the caller className LAST.',
+    '',
+    '```tsx',
+    "import { cn } from '@/lib/utils'",
+    '',
+    '<div',
+    '  className={cn(',
+    "    'rounded-lg border border-border bg-card p-4 text-sm text-foreground',",
+    "    isRefreshing && 'opacity-60',",
+    '    className,',
+    '  )}',
+    '/>',
+    '```',
+    '',
+    '## Naming',
+    '',
+    'Variables are `--color-*`, `--surface-*`, `--radius-*`, `--chart-N`; state suffixes are',
+    '`-hover` and `-active`. Utilities read the same way with the prefix dropped.',
+    '',
+    '## Red Flags — STOP',
+    '',
+    '- A color literal anywhere under `src/ui/` or `src/components/`.',
+    '- A new raw variable with no `@theme inline` mirror.',
+    '- Writing the dark selector directly in a component.',
+    '- A surface that is unreadable in the theme you did not test.',
+    '- `chart-*` used for chrome.',
+    '- A locally redefined `cn`.',
+    '',
+    '## Verification',
+    '',
+    '```bash',
+    'bun run build',
+    '```',
+    '',
+    'Tailwind fails the build on an unknown utility. Then check the App in both themes — the host',
+    'toggle in the platform, or the system setting standalone.',
+    '',
+    '## Scope',
+    '',
+    'The token names ship with the scaffold stylesheet, which is a projection of the platform',
+    'stylesheet. A customer deployment may redefine their values; it does not rename them.',
+  ],
+}
+
+const components: Skill = {
+  name: 'frontera-ui-components',
+  description:
+    'Use when adding or editing a shared primitive in a Frontera App — pulling components from the shadcn registry with bunx shadcn add, why shadcn init must never run, and the cva + data-slot + cn conventions for editing one.',
+  body: [
+    '# Shared components',
+    '',
+    'Primitives come from the **shadcn registry**. This project does not maintain a component',
+    'library: `components.json` is already configured, so any upstream component drops in unmodified.',
+    'Once added, the file is copied source and yours to edit.',
+    '',
+    '## Rules',
+    '',
+    '- Add what you need, by name, before writing one yourself:',
+    '',
+    '```bash',
+    'bunx --bun shadcn@latest add dialog dropdown-menu tabs',
+    '```',
+    '',
+    '  Files land in `src/components/ui/`, importing `cn` from `@/lib/utils`. The scaffold already',
+    '  ships `button`, `input`, `table`, `skeleton`, `card` and `alert` — check there first.',
+    '- **Never run `shadcn init`.** It rewrites `src/app/globals.css` with the vanilla palette and',
+    '  drops the platform surface scale, so every screen in the App changes colour at once. `add`',
+    '  leaves that stylesheet alone, which is the whole reason this configuration exists.',
+    '- The registry declares no npm dependencies of its own, so an added component installs nothing.',
+    '  Everything upstream imports — `class-variance-authority`, `radix-ui`, `lucide-react`,',
+    '  `tw-animate-css` — is already in `package.json`. If a new component wants something else,',
+    '  add it with `bun add` and say so in the same commit.',
+    '- A primitive is shared, generic, and knows nothing about your data. Anything that knows about',
+    '  one feature belongs in `src/ui/<feature>/components/` instead.',
+    '- `src/components/ui/` is EXEMPT from one-component-per-file: compound primitives keep their',
+    '  parts together (`Card`, `CardHeader`, `CardContent`).',
+    '- Editing one is normal — it is your file. Keep the conventions it arrived with: variants',
+    '  through `cva` with `defaultVariants`, props typed as',
+    '  `React.ComponentProps<"el"> & VariantProps<typeof xVariants>`, classes merged with `cn()` with',
+    '  the caller className LAST, a kebab `data-slot` on every part, and both the component and its',
+    '  variants function exported.',
+    '- Colours come from tokens — see **frontera-design-tokens**. Upstream components reference the',
+    '  same token names this stylesheet defines, which is why they look native without patching.',
+    '- `frontera app add` is a second, Frontera-specific registry: page and dashboard compositions',
+    '  (`app-page`, `page-header`, `stat-tile`, `filter-bar`, `data-table`) that upstream has no',
+    '  equivalent for. Use it for those; use shadcn for everything generic.',
+    '',
+    '```tsx',
+    '// src/components/ui/badge.tsx — as shadcn writes it, and as you keep it',
+    'function Badge({ className, variant, ...props }:',
+    "  React.ComponentProps<'span'> & VariantProps<typeof badgeVariants>) {",
+    '  return <span data-slot="badge" className={cn(badgeVariants({ variant }), className)} {...props} />',
+    '}',
+    '',
+    'export { Badge, badgeVariants }',
+    '```',
+    '',
+    '## Naming',
+    '',
+    'Files kebab-case, as the registry writes them. Exports PascalCase with compound sub-exports.',
+    'The variants function is `<name>Variants`; variant values are lowercase.',
+    '',
+    '## Red Flags — STOP',
+    '',
+    '- Hand-writing a button, input, dialog or table that the registry publishes.',
+    '- Running `shadcn init` in an existing project.',
+    '- Re-adding a component over local edits without meaning to.',
+    '- Feature-specific logic inside `src/components/ui/`.',
+    '- A missing `data-slot`, a locally redefined `cn`, or a variant system invented next to `cva`.',
+    '- Editing a token to make one component look right — that changes every component.',
+    '',
+    '## Verification',
+    '',
+    '```bash',
+    'bun run check',
+    '```',
+    '',
+    'Then look at the component in both themes. A primitive that only works in one of them is not done.',
+    '',
+    '## Scope',
+    '',
+    'The shadcn registry changes independently of this project — list or search it rather than',
+    'assuming this skill knows what is in it. A component that needs a Radix package the project',
+    'does not have will say so at build time.',
+  ],
+}
+
+const queryStates: Skill = {
+  name: 'frontera-query-ui-states',
+  description:
+    'Use when rendering asynchronous Blueprint-backed UI in a Frontera App — the error/loading/empty/content branch order, content-shaped skeletons, background refetch dimming, and telling forbidden apart from empty.',
+  body: [
+    '# Query states',
+    '',
+    'A query has more outcomes than "data" and "not yet". Rendering them in a deliberate order is',
+    'what stops an App from telling a customer their records are gone when a request merely failed.',
+    '',
+    '## Rules',
+    '',
+    '- Branch in this order: **error → initial loading → empty → content**. Configuration gaps come',
+    '  first of all, because nothing below them can succeed.',
+    '- `isLoading` is the FIRST load and earns a skeleton. `isFetching` is a background refresh: keep',
+    '  the stale rows, dim them, mark the region `aria-busy`, and never reset selection or scroll.',
+    '- A skeleton is shaped like the content it replaces — the same rows, the same column count, the',
+    '  same border. A centred spinner communicates nothing and moves the layout when it disappears.',
+    '- Keep the skeleton in its own file next to the component: `<part>-skeleton.tsx`.',
+    '- Default optional data only AFTER error and loading have been distinguished. `data?.rows ?? []`',
+    '  is a rendering convenience, never a substitute for handling a failure.',
+    '- An empty success says what was queried and offers the next useful action. A forbidden result',
+    '  says access is unavailable — it must not read as "there are no records".',
+    '- A recoverable error keeps the surrounding context, uses `role="alert"`, and offers a retry that',
+    '  calls `refetch`.',
+    '- Every one of those strings comes from `src/lib/copy.ts`.',
+    '',
+    '```tsx',
+    '// src/ui/object-explorer/object-explorer.tsx',
+    'const records = rows.data?.rows ?? []',
+    '',
+    'return rows.isError ? (',
+    '  <QueryError message={rows.error.message} onRetry={() => void rows.refetch()} />',
+    ') : rows.isLoading ? (',
+    '  <ObjectTableSkeleton />',
+    ') : records.length === 0 ? (',
+    '  <EmptyPanel title={copy.explorer.empty} body={copy.explorer.emptyHint} />',
+    ') : (',
+    '  <ObjectTable columns={columns} rows={records} isRefreshing={rows.isFetching} />',
+    ')',
+    '```',
+    '',
+    '## Naming',
+    '',
+    'Query flags stay as React Query names them: `isLoading`, `isFetching`, `isError`. Shared state',
+    'components are `empty-panel.tsx`, `query-error.tsx`, `<part>-skeleton.tsx`.',
+    '',
+    '## Red Flags — STOP',
+    '',
+    '- An unhandled `isError`.',
+    '- A bare spinner where a shaped skeleton belongs.',
+    '- A failed read rendered as an empty state.',
+    '- The table remounting on every page change instead of dimming.',
+    '- Empty or error copy written inline.',
+    '',
+    '## Verification',
+    '',
+    '```bash',
+    'frontera app dev',
+    '```',
+    '',
+    'Exercise all four states: a filter that matches nothing, a stopped network, a first load, and a',
+    'page change. Each must look different.',
+    '',
+    '## Scope',
+    '',
+    'Applies to every query consumer in a Frontera App.',
+  ],
+}
+
+const tables: Skill = {
+  name: 'frontera-app-tables',
+  description:
+    'Use when rendering Blueprint rows as a table or list in a Frontera App — server-driven paging and sorting, totals from an aggregate, column definitions, the registry data-table, and the narrow-screen strategy.',
+  body: [
+    '# Tables',
+    '',
+    'A table over Blueprint is a server-driven table. The dataset is larger than the page, always.',
+    '',
+    '## Rules',
+    '',
+    '- Start from `src/ui/object-explorer/` — search, shaped skeleton, dimmed refetch, pager and',
+    '  aggregate total are already wired there over the shadcn `table` primitive.',
+    '- For sorting, faceted filters, column visibility and a toolbar, do NOT hand-roll them. The',
+    '  shadcn registry has no data-table item — it is a documentation example — so take the',
+    '  Frontera one, which is that example already wired to this token system:',
+    '',
+    '```bash',
+    'frontera app add data-table',
+    '```',
+    '',
+    '  It brings `@tanstack/react-table`; install what it reports as missing.',
+    '',
+    '- Declare columns in their own file, `<feature>-columns.tsx`, exporting a FUNCTION',
+    '  (`getShipmentColumns(options)`) so values discovered at runtime can be injected. Never rebuild',
+    '  the column list inline on every render.',
+    '- Everything that changes the result set goes to the server: `where`, `orderBy`, `pageToken`,',
+    '  `pageSize`. Client-side sorting of a page reorders 25 rows and calls it a ranking.',
+    '- The first request omits `pageToken`. Advance with the response `nextPageToken`; retain earlier',
+    '  tokens locally if the UI supports Previous. Never calculate, inspect or manufacture a token.',
+    '- Use `hasMore` to enable Next. An aggregate total is useful for a displayed range such as',
+    '  "1–25 of 8,961", but it does not drive Blueprint navigation.',
+    '- Reset the token history on ANY change to search, filters or sort — do it in the handler, not',
+    '  in an effect. A cursor belongs to the exact query shape that created it.',
+    '- Debounce free-text search around 300ms; every keystroke otherwise becomes a Blueprint scan.',
+    '- Keep the skeleton column count in step with the real column count.',
+    '- Narrow screens need a strategy, not a shrug: scroll the table inside its own',
+    '  `overflow-x-auto` container, or render a card list. The page itself must never scroll sideways.',
+    '',
+    '```tsx',
+    '// reset cursor history where the query shape changes',
+    'const handleSearch = (value: string) => {',
+    '  setSearch(value)',
+    '  setPageIndex(0)',
+    '  setPageTokens([undefined])',
+    '}',
+    '',
+    '<ObjectPager',
+    '  hasPrevious={pageIndex > 0}',
+    '  hasNext={rows.data?.hasMore ?? false}',
+    '  onPrevious={() => setPageIndex((index) => Math.max(0, index - 1))}',
+    '  onNext={() => {',
+    '    const token = rows.data?.nextPageToken',
+    '    if (!token) return',
+    '    setPageTokens((tokens) => [...tokens.slice(0, pageIndex + 1), token])',
+    '    setPageIndex((index) => index + 1)',
+    '  }}',
+    '/>',
+    '```',
+    '',
+    '## Naming',
+    '',
+    'Table component `<feature>-table.tsx`, columns `<feature>-columns.tsx` exporting',
+    '`get<Feature>Columns()`, skeleton `<feature>-table-skeleton.tsx`, pager `<feature>-pager.tsx`.',
+    '',
+    '## Red Flags — STOP',
+    '',
+    '- Sorting or filtering an array that came from a paged query.',
+    '- `rows.length` used as the total, or a footer that says "Page 1 of 1" over a filtered set.',
+    '- Sending a numeric page or offset to Blueprint instead of using `nextPageToken`.',
+    '- Reusing a cursor after its filter, sort or projection changes.',
+    '- Columns rebuilt inline, or a second table implementation next to the first.',
+    '- A table that forces the whole page to scroll horizontally on a phone.',
+    '',
+    '## Verification',
+    '',
+    '```bash',
+    'bun run check',
+    '```',
+    '',
+    'Then, with real data: filter to a subset, confirm the total matches the filter, page to the end,',
+    'and check the layout at a phone width.',
+    '',
+    '## Scope',
+    '',
+    'Applies to every list surface in a Frontera App, including card lists and boards — the paging',
+    'and total rules are about the query, not the markup.',
+  ],
+}
+
+const testing: Skill = {
+  name: 'frontera-app-testing',
+  description:
+    'Use when adding or running tests in a Frontera App — bun test over pure helpers in src/lib, what is worth testing in a static App, and why data behaviour is verified with frontera app dev rather than mocks.',
+  body: [
+    '# Testing',
+    '',
+    'A static App has a small, sharp testable core: the pure functions that decide what to ask for',
+    'and how to present the answer. Test those, and verify the rest against real data.',
+    '',
+    '## Rules',
+    '',
+    '- `bun run test` runs `bun test src`. Test files are named `*.test.ts` and colocated in',
+    '  `__tests__/` next to the code they cover. Never `.spec.ts`.',
+    '- Test the pure layer: filter builders, page arithmetic, totals, formatters, deep-link parsing.',
+    '  These are exactly the functions a Blueprint query depends on and a screenshot cannot check.',
+    '- Extract a helper to make it testable rather than testing through a hook. If the logic is',
+    '  trapped inside a component, that is a design problem, not a testing problem.',
+    '- Do not mock the Blueprint client to assert hook internals. A mocked read proves the mock:',
+    '  it will happily agree that a filter compiles into an object set the service would reject.',
+    '- Verify data behaviour by running the App against a real workspace with `frontera app dev`, and',
+    '  confirm the states from **frontera-query-ui-states** each render.',
+    '- No DOM test runner ships with the scaffold. If a component genuinely needs one, add the runner',
+    '  and its configuration in the same commit, wire it into the `check` script, and say why.',
+    '- Tests must be deterministic and offline: no network, no clock dependence, no shared state',
+    '  between files.',
+    '',
+    '```ts',
+    '// src/lib/blueprint/objects/__tests__/objects-hooks.test.ts',
+    "import { describe, expect, test } from 'bun:test'",
+    "import { objectWhere } from '../objects-hooks'",
+    '',
+    "describe('objectWhere', () => {",
+    "  test('ignores whitespace-only input rather than filtering on an empty string', () => {",
+    "    expect(objectWhere({ objectType: 'Shipment', search: '   ', searchProperty: 'city' }))",
+    '      .toBeUndefined()',
+    '  })',
+    '})',
+    '```',
+    '',
+    '## Naming',
+    '',
+    '`describe("<unit>")` names the function; `test("<verb phrase>")` states the behaviour and the',
+    'consequence, not the mechanics. Fixtures are factory functions, not shared mutable objects.',
+    '',
+    '## Red Flags — STOP',
+    '',
+    '- `.spec.ts` naming.',
+    '- A test that asserts a mock was called.',
+    '- Logic left inside a component because it "cannot be tested".',
+    '- A test that hits the network, or depends on the current date.',
+    '- Claiming a data change works without having run it against real data.',
+    '',
+    '## Verification',
+    '',
+    '```bash',
+    'bun run test',
+    '```',
+    '',
+    '## Scope',
+    '',
+    'Applies to every Frontera App. The scaffold ships one example suite next to the starter data',
+    'layer; it is the shape to copy, not the extent of what should be tested.',
+  ],
+}
+
+const security: Skill = {
+  name: 'frontera-app-security',
+  description:
+    'Use when adding external requests, browser capabilities, secrets, or iframe behaviour to a Frontera App — declaring CSP domains, why a static App has no secret storage, and the boundaries of the App token.',
+  body: [
+    '# Security boundaries',
+    '',
+    'An App runs in a sandboxed frame with a short-lived, App-scoped credential. Every boundary here',
+    'exists because the App is browser code a customer can read.',
+    '',
+    '## Rules',
+    '',
+    '- Declare every external host in `frontera.config.json`: `connectDomains` for connections the',
+    '  browser makes, `resourceDomains` for images, fonts and other resources. The deployed manifest',
+    '  becomes CSP, so anything undeclared fails closed — including in the preview you are about to test.',
+    '- **Browser code has no secret storage.** Never put a workspace key, service credential or private',
+    '  token in source, in `NEXT_PUBLIC_*`, in `.env*`, in a URL, in `localStorage`, in a log line, or',
+    '  in App state. A static App cannot hold a secret; the honest answer to "where do I put the key"',
+    '  is that this App does not get one.',
+    '- The App token is short-lived, App-scoped and limited to the allowlisted read surface. Embedded',
+    '  and standalone bind it to the signed-in user; local development binds it to the stored CLI',
+    '  credential. Treat it as opaque and do not move it anywhere.',
+    '- Do not recreate the iframe bridge, weaken the parent-origin check, accept `*` as a postMessage',
+    '  target, or treat an asset cookie as a data credential.',
+    '- Do not request a service route just because the browser can construct the URL. Blueprint is the',
+    '  contract; anything outside it is not an entitlement you have.',
+    '- Never send customer data to a third-party host without an explicit decision that the customer',
+    '  permits it to leave Frontera. Adding a domain is that decision, in writing.',
+    '- Treat data returned by a query as data. Rendering user-controlled HTML, or building a URL from',
+    '  a record without validating its scheme, hands the page to whoever wrote the row.',
+    '',
+    '## Before adding a domain',
+    '',
+    '1. Confirm the browser genuinely needs direct access, rather than the data arriving through Blueprint.',
+    '2. Use HTTPS, name the narrowest host that works, and avoid wildcards.',
+    '3. Put it in the right list — a connection is not a resource.',
+    '4. Redeploy: CSP comes from the deployed manifest, so a local change proves nothing.',
+    '',
+    '## Red Flags — STOP',
+    '',
+    '- A credential in `.env`, in a `NEXT_PUBLIC_*` variable, or in committed source.',
+    '- A wildcard domain, or a domain added to silence a CSP error without understanding it.',
+    '- A hand-rolled postMessage listener next to the SDK bridge.',
+    '- A token logged, cached, stored, or attached to a third-party request.',
+    '- `dangerouslySetInnerHTML` over query results.',
+    '',
+    '## Verification',
+    '',
+    '```bash',
+    'frontera app deploy --no-promote',
+    '```',
+    '',
+    'Open the preview URL and watch the browser console: a blocked request is a CSP declaration you',
+    'have not made yet. Then confirm nothing sensitive appears in the built output.',
+    '',
+    '## Scope',
+    '',
+    'Applies to every Frontera App. Server-side capabilities and Frontera Secrets are out of scope',
+    'here — a static App has no server side to hold them.',
+  ],
+}
+
+const release: Skill = {
+  name: 'frontera-app-release',
+  description:
+    'Use when validating, building, deploying, previewing, promoting, or rolling back a Frontera App — the safe release sequence, version immutability, and what the recorded provenance does and does not prove.',
+  body: [
+    '# Release',
+    '',
+    'Frontera serves an uploaded immutable artifact. It does not install dependencies and does not',
+    'run Next, so whatever `bun run build` produced is exactly what customers get.',
+    '',
+    '## Safe sequence',
+    '',
+    '1. `bun run check` — typecheck, tests, then the build. The build is the authoritative',
+    '   static-export compatibility check.',
+    '2. Confirm `out/index.html` exists, along with every route you intended to export.',
+    '3. `frontera app deploy --no-promote` — publishes a version without moving the live pointer.',
+    '4. Open the returned preview URL. Check it embedded and at a narrow width, in both themes, and',
+    '   watch the console for blocked requests.',
+    '5. `frontera app promote <version>` — point live at it.',
+    '',
+    '```bash',
+    'frontera app deploy --no-promote',
+    '```',
+    '',
+    '```bash',
+    'frontera app versions',
+    '```',
+    '',
+    '## Rules',
+    '',
+    '- Versions are immutable. Never reuse a version string for different bytes.',
+    '- Rollback is promoting an earlier version, not rebuilding one. That is the whole reason the old',
+    '  bytes are kept.',
+    '- Promote deliberately. A deploy that promotes by default turns every experiment into a release.',
+    '- `frontera app versions` shows runtime, routing, framework provenance, source commit and dirty',
+    '  status, sizes and the live pointer. The CLI-recorded provenance is metadata; the',
+    '  service-computed digest, file count, byte count and uploader are authoritative.',
+    '- Deploying from a dirty tree is recorded as dirty. Do not do it for a release you intend to',
+    '  reproduce later.',
+    '- Customer CI runs the same two commands with credentials from the CI secret store, never from',
+    '  the repository.',
+    '- A schema-dependent change needs `bun run blueprint:types:check` in CI: the App can build',
+    '  perfectly against a contract the workspace no longer has.',
+    '',
+    '## Red Flags — STOP',
+    '',
+    '- Promoting a version nobody opened.',
+    '- Deploying without `bun run check`, or after only a typecheck.',
+    '- Editing `out/` by hand.',
+    '- Rebuilding to "roll back".',
+    '- A credential in CI configuration instead of the secret store.',
+    '',
+    '## Verification',
+    '',
+    '```bash',
+    'frontera app versions',
+    '```',
+    '',
+    'The live pointer must name the version you promoted, and its digest must match the deploy you',
+    'previewed.',
+    '',
+    '## Scope',
+    '',
+    'Applies to every Frontera App. Automations and platform resources have their own lifecycles and',
+    'are not released this way.',
+  ],
+}
+
+const SKILLS: Skill[] = [
+  dispatcher,
+  project,
+  routing,
+  session,
+  blueprintData,
+  actions,
+  ui,
+  tokens,
+  components,
+  queryStates,
+  tables,
+  testing,
+  security,
+  release,
+]