@tristan2828/ui-foundation 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tristan2828
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# @tristan2828/ui-foundation
+
+The shared layer of a family of small, contract-first, database-backed React
+apps: shadcn primitives, the `DataTable`/`EntityForm` composites, an app
+shell with session-cookie auth, the gateway's error seam, design tokens,
+lint rules, Playwright suites, and the conventions an AI agent follows to
+build on it. Apps upgrade by bumping the version.
+
+Built for Vite + React 19 + TypeScript, Tailwind v4, shadcn/ui on Base UI,
+React Router 7 and TanStack Query. Start a new app from the template rather
+than installing this by hand:
+[docs/create-an-app.md](https://github.com/Tristan2828/ui-foundation/blob/main/docs/create-an-app.md).
+
+## Entry points
+
+| Import | What |
+|---|---|
+| `@tristan2828/ui-foundation` | `AppShell`, `DataTable`, `EntityForm`, `ErrorState`, `MultiChoice`, `PasswordInput`, `RouteErrorBoundary`, `FoundationProviders`, `LoginRoute`, `RegisterRoute`, `useAuth`, `useTableUrlState`, `useDebouncedValue`, `createQueryClient`, `cn`; types `Page`, `AppError`, `QuerySpec` |
+| `@tristan2828/ui-foundation/ui/<name>` | shadcn primitives: badge, button, calendar, card, combobox, dialog, empty, field, input, input-group, label, popover, select, separator, sheet, sidebar, skeleton, sonner, spinner, table, textarea, tooltip |
+| `@tristan2828/ui-foundation/gateway` | `safeFetch`, `toAppError`, `networkError` — for an app's `src/api/gateway/` only |
+| `@tristan2828/ui-foundation/mocks` | MSW: `authHandlers`, `resetMockAuth`, `exposeMswForE2E` |
+| `@tristan2828/ui-foundation/testing` | Playwright: `defineA11ySuite`, `defineMockModeBannerSuite`, `forceMswOverride`, `forceLoggedOut`, `waitForMswReady` |
+| `@tristan2828/ui-foundation/eslint` | the lint rules, as a flat config: `export default [...uiFoundation()]` |
+| `@tristan2828/ui-foundation/styles.css` | tokens and base styles, after `@import "tailwindcss";` |
+| `@tristan2828/ui-foundation/openapi.yaml` | the part of an app's API contract the package calls: `/auth/*` and the error bodies |
+
+## The `ui-foundation` command
+
+Run from an app's root:
+
+- `ui-foundation sync` writes the conventions into the app: the rules block
+  in `AGENTS.md`, `docs/foundation/`, and the agent files in `.claude/` and
+  `.codex/`. Run it after every upgrade and commit what it writes.
+  `sync --check` (in `verify`) fails when they differ from the installed
+  version.
+- `ui-foundation check-contract [openapi.yaml]` fails unless the app's spec
+  contains the foundation's part unchanged.
+- `ui-foundation check-deps` fails if `package.json` names a dependency
+  missing from `deps-allowlist.json`.
+
+## Upgrading
+
+```bash
+npm install @tristan2828/ui-foundation@<version>
+npx ui-foundation sync
+npm run verify
+```
+
+Release notes: https://github.com/Tristan2828/ui-foundation/releases.
+
+MIT licensed.

package/bin/ui-foundation.mjs

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+// The `ui-foundation` command, run from an app's root:
+//
+//   ui-foundation sync [--check]
+//     Writes the foundation's conventions into the app: the rules block in
+//     AGENTS.md, docs/foundation/ (the entity playbook and design docs), and
+//     the agent files (.claude/, .codex/). --check writes nothing and fails
+//     if any of them differ from this installed version, which is how
+//     `verify` catches a package upgrade that skipped `sync`, or a synced
+//     file edited in the app.
+//
+//   ui-foundation check-contract [openapi.yaml]
+//     Fails unless the app's spec contains the foundation's part of the
+//     contract (auth paths, error envelopes) unchanged — the part the
+//     package's own code calls.
+//
+//   ui-foundation check-deps [--allowlist deps-allowlist.json]
+//     Fails if package.json names a dependency the allowlist doesn't.
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { load as loadYaml } from 'js-yaml'
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const PACKAGE = JSON.parse(readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8'))
+const APP_ROOT = process.cwd()
+
+const read = (file) => readFileSync(file, 'utf8').replace(/\r\n/g, '\n')
+const fail = (message) => {
+  console.error(message)
+  process.exit(1)
+}
+
+// ---------------------------------------------------------------- sync
+
+const BLOCK_START = '<!-- ui-foundation:start'
+const BLOCK_END = '<!-- ui-foundation:end -->'
+const BLOCK_HEADER = `${BLOCK_START} — synced from ${PACKAGE.name} by \`npx ui-foundation sync\`. Don't edit inside this block: your app's own notes go below it, and a change to the rules belongs in the foundation. -->`
+
+// docs/foundation/ belongs to sync entirely: files the package no longer
+// ships are removed from it. Everything else is written file by file.
+const DOCS_DIR = 'docs/foundation'
+
+function syncedFiles() {
+  const conventions = path.join(PACKAGE_ROOT, 'conventions')
+  const files = new Map()
+  for (const doc of readdirSync(path.join(conventions, 'docs'))) {
+    files.set(`${DOCS_DIR}/${doc}`, read(path.join(conventions, 'docs', doc)))
+  }
+  const skill = read(path.join(conventions, 'agents/skills/new-entity/SKILL.md'))
+  files.set('.claude/skills/new-entity/SKILL.md', skill)
+  files.set('.codex/skills/new-entity/SKILL.md', skill)
+  files.set('.claude/agents/spec-tester.md', read(path.join(conventions, 'agents/spec-tester.md')))
+  files.set('.claude/hooks/deny-impl-read.mjs', read(path.join(conventions, 'agents/deny-impl-read.mjs')))
+  return files
+}
+
+function agentsBlock() {
+  const rules = read(path.join(PACKAGE_ROOT, 'conventions/AGENTS.md')).trimEnd()
+  return `${BLOCK_HEADER}\n\n${rules}\n\n${BLOCK_END}`
+}
+
+// The app's AGENTS.md with the block replaced (or added, above the app's
+// own content, when an older app has none yet).
+function agentsMdWithBlock(current) {
+  const block = agentsBlock()
+  if (current === null) {
+    return `${block}\n\n## This app\n\nWhat this app is, and anything an agent needs that the rules above don't cover.\n`
+  }
+  const start = current.indexOf(BLOCK_START)
+  const end = current.indexOf(BLOCK_END)
+  if (start === -1 || end === -1) return `${block}\n\n${current.trimStart()}`
+  return current.slice(0, start) + block + current.slice(end + BLOCK_END.length)
+}
+
+function sync({ check }) {
+  const problems = []
+  const write = (relative, content) => {
+    const target = path.join(APP_ROOT, relative)
+    const current = existsSync(target) ? read(target) : null
+    if (current === content) return
+    if (check) {
+      problems.push(`${current === null ? 'missing' : 'differs'}: ${relative}`)
+      return
+    }
+    mkdirSync(path.dirname(target), { recursive: true })
+    writeFileSync(target, content)
+    console.log(`sync: wrote ${relative}`)
+  }
+
+  const files = syncedFiles()
+  for (const [relative, content] of files) write(relative, content)
+
+  const docsDir = path.join(APP_ROOT, DOCS_DIR)
+  if (existsSync(docsDir)) {
+    for (const file of readdirSync(docsDir)) {
+      const relative = `${DOCS_DIR}/${file}`
+      if (files.has(relative)) continue
+      if (check) problems.push(`no longer shipped: ${relative}`)
+      else {
+        rmSync(path.join(docsDir, file), { recursive: true })
+        console.log(`sync: removed ${relative}`)
+      }
+    }
+  }
+
+  const agentsPath = path.join(APP_ROOT, 'AGENTS.md')
+  const agents = existsSync(agentsPath) ? read(agentsPath) : null
+  if (check && agents !== null && !agents.includes(BLOCK_START)) {
+    problems.push('AGENTS.md has no ui-foundation block')
+  } else {
+    write('AGENTS.md', agentsMdWithBlock(agents))
+  }
+  if (agents !== null && !agents.includes(BLOCK_START) && !check) {
+    console.log(
+      'sync: AGENTS.md had no foundation block; added one at the top. Delete any older copy of the foundation rules below it.',
+    )
+  }
+
+  // Claude Code reads CLAUDE.md, which imports AGENTS.md. Created once;
+  // the app may add to it.
+  if (!existsSync(path.join(APP_ROOT, 'CLAUDE.md'))) {
+    if (check) problems.push('missing: CLAUDE.md')
+    else write('CLAUDE.md', '@AGENTS.md\n')
+  }
+
+  if (check) {
+    if (problems.length > 0) {
+      fail(
+        [
+          `sync --check: the app's conventions don't match ${PACKAGE.name}@${PACKAGE.version}:`,
+          ...problems.map((problem) => `  ${problem}`),
+          'Run `npx ui-foundation sync`. If a synced file was edited on purpose, that change belongs in the foundation — raise it there; the next sync overwrites it here.',
+        ].join('\n'),
+      )
+    }
+    console.log(`sync --check: conventions match ${PACKAGE.name}@${PACKAGE.version}`)
+  } else {
+    console.log(`sync: conventions match ${PACKAGE.name}@${PACKAGE.version}`)
+  }
+}
+
+// ---------------------------------------------------------- check-contract
+
+// Wording may differ between the app's spec and the foundation's; shapes may not.
+const IGNORED_KEYS = new Set(['description', 'summary', 'example', 'examples', 'tags', 'x-optional'])
+
+function normalise(value) {
+  if (Array.isArray(value)) return value.map(normalise)
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.keys(value)
+        .filter((key) => !IGNORED_KEYS.has(key))
+        .sort()
+        .map((key) => [key, normalise(value[key])]),
+    )
+  }
+  return value
+}
+
+const same = (a, b) => JSON.stringify(normalise(a)) === JSON.stringify(normalise(b))
+
+function checkContract(specPath) {
+  const target = path.resolve(APP_ROOT, specPath)
+  if (!existsSync(target)) fail(`check-contract: no ${specPath} here`)
+  const app = loadYaml(read(target))
+  const foundation = loadYaml(read(path.join(PACKAGE_ROOT, 'openapi/foundation.yaml')))
+  const problems = []
+
+  for (const [route, item] of Object.entries(foundation.paths)) {
+    const appItem = app.paths?.[route]
+    if (appItem === undefined) {
+      if (!item['x-optional']) problems.push(`missing path ${route}`)
+    } else if (!same(appItem, item)) {
+      problems.push(`path ${route} differs`)
+    }
+  }
+  for (const [section, entries] of Object.entries(foundation.components)) {
+    for (const [name, entry] of Object.entries(entries)) {
+      const appEntry = app.components?.[section]?.[name]
+      if (appEntry === undefined) problems.push(`missing components.${section}.${name}`)
+      else if (!same(appEntry, entry)) problems.push(`components.${section}.${name} differs`)
+    }
+  }
+
+  if (problems.length > 0) {
+    fail(
+      [
+        `check-contract: ${specPath} doesn't contain ${PACKAGE.name}'s part of the contract unchanged:`,
+        ...problems.map((problem) => `  ${problem}`),
+        `The package's auth and error handling call exactly these shapes. Copy them from node_modules/${PACKAGE.name}/openapi/foundation.yaml (wording may differ, shapes may not).`,
+      ].join('\n'),
+    )
+  }
+  console.log(`check-contract: ${specPath} contains the foundation contract`)
+}
+
+// -------------------------------------------------------------- check-deps
+
+function checkDeps(allowlistPath) {
+  const allowlistFile = path.resolve(APP_ROOT, allowlistPath)
+  const packageFile = path.join(APP_ROOT, 'package.json')
+  if (!existsSync(allowlistFile)) fail(`check-deps: no ${allowlistPath} here`)
+  const allowlist = JSON.parse(read(allowlistFile))
+  const allowed = new Set([...allowlist.dependencies, ...allowlist.devDependencies])
+  const pkg = JSON.parse(read(packageFile))
+  const declared = new Set(
+    ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'].flatMap((field) =>
+      Object.keys(pkg[field] ?? {}),
+    ),
+  )
+  const violations = [...declared].filter((name) => !allowed.has(name))
+  if (violations.length > 0) {
+    fail(
+      violations
+        .map(
+          (name) =>
+            `check-deps: "${name}" is not in ${allowlistPath}. If it is needed, write the case in docs/BLOCKERS.md and stop.`,
+        )
+        .join('\n'),
+    )
+  }
+  console.log(`check-deps: all ${declared.size} declared dependencies are allowlisted`)
+}
+
+// ------------------------------------------------------------------- main
+
+const [command, ...args] = process.argv.slice(2)
+const option = (name, fallback) => {
+  const index = args.indexOf(name)
+  return index === -1 ? fallback : args[index + 1]
+}
+
+switch (command) {
+  case 'sync':
+    sync({ check: args.includes('--check') })
+    break
+  case 'check-contract':
+    checkContract(args.find((arg) => !arg.startsWith('--')) ?? 'openapi.yaml')
+    break
+  case 'check-deps':
+    checkDeps(option('--allowlist', 'deps-allowlist.json'))
+    break
+  case '--version':
+    console.log(PACKAGE.version)
+    break
+  default:
+    fail('usage: ui-foundation <sync [--check] | check-contract [openapi.yaml] | check-deps [--allowlist file] | --version>')
+}

package/conventions/AGENTS.md

@@ -0,0 +1,149 @@
+# Built on @tristan2828/ui-foundation
+
+## Stack
+Vite + React 19 + TypeScript, Tailwind v4, shadcn/ui (Base UI primitives),
+React Router v7, TanStack Query. The shared layer — primitives, the
+`DataTable`/`EntityForm` composites, the app shell, auth, the gateway error
+seam, design tokens, lint rules — is the npm package
+`@tristan2828/ui-foundation`, updated by bumping its version. Everything in
+`src/` is this app's own.
+
+Contract-first: `openapi.yaml` is the source of truth and is owned by this
+app. In development MSW serves the contract, so there may be no backend at
+all.
+
+Pinned tool versions live in `deps-allowlist.json` (`tools`). Never use
+`@latest` for a tool command.
+
+## Hard Rules
+Each rule names the check that enforces it. If you hit the check, the check
+is right. Do not disable, skip, or work around it.
+
+- NEVER copy a file out of `node_modules/@tristan2828/ui-foundation` to
+  change it, and never patch it in place. Configure it through its props, or
+  raise the change for the foundation (see "Changing the Foundation"). A
+  copied composite is a file maintained twice with nothing saying so.
+  (Enforced: lint forbids importing the package's internals, and a shipped
+  primitive from anywhere but the package.)
+- NEVER hand-roll a component that exists in shadcn. Import it from
+  `@tristan2828/ui-foundation/ui/<name>` if the package ships it; otherwise
+  run `npx shadcn@<tools.shadcn> add <name>` into `src/components/ui/`. If
+  that also writes a primitive the package ships (a dependency of the one
+  you asked for), delete the copy and import the package's. (Enforced: lint
+  rejects `@/components/ui/<name>` for any primitive the package ships.)
+- NEVER add a dependency that is not in `deps-allowlist.json`. If you
+  believe one is needed, write the case in `docs/BLOCKERS.md` and stop.
+  (Enforced: `ui-foundation check-deps` in verify.)
+- NEVER hand-write an API type. All types come from `src/api/schema.d.ts`,
+  generated from `openapi.yaml`. If a type is missing, run `npm run gen:api`.
+  (Enforced: codegen diff in verify.)
+- NEVER change the foundation's part of `openapi.yaml` — the `/auth/*` paths
+  and the error envelopes. The package's code calls exactly those shapes.
+  (Enforced: `ui-foundation check-contract` in verify.)
+- NEVER use a raw hex value or a Tailwind palette color (`bg-blue-500`).
+  Semantic tokens only: `bg-primary`, `text-muted-foreground`. (Enforced:
+  the foundation's ESLint token rule; axe contrast in light and dark mode,
+  `e2e/a11y.spec.ts`.)
+- NEVER fetch in `useEffect`. All server state goes through TanStack Query.
+  (Enforced: eslint-plugin-query + the no-bare-fetch rule.)
+- NEVER read auth state outside `useAuth()`. The package exports nothing
+  else that knows how auth works. (Enforced: the package's exports.)
+- NEVER import `@tristan2828/ui-foundation/gateway` outside
+  `src/api/gateway/`. Components and hooks call a gateway module through
+  TanStack Query. (Enforced: no-restricted-imports.)
+- NEVER let a backend-shaped response reach a component. Paginated data is
+  `Page<T>`. Failures are `AppError`. Queries are `QuerySpec`. The gateway
+  translates; nothing above it knows the wire format. (Enforced: gateway
+  return types are the contracts; tsc.)
+- NEVER write a gateway test by reading the gateway. Tests come from
+  `openapi.yaml`. (Enforced in Claude Code: the spec-tester subagent cannot
+  read `src/api/gateway/`. In other tools: write them before the gateway
+  exists — `docs/foundation/add-an-entity.md` step 3.)
+- NEVER name a file in PascalCase or snake_case. Kebab-case everywhere —
+  routes, components, hooks, tests (`widget-form.tsx`, not
+  `WidgetForm.tsx`). (Enforced: eslint-plugin-check-file.)
+- NEVER edit a synced file: this block, `docs/foundation/`, and the agent
+  files under `.claude/` and `.codex/` that `ui-foundation sync` writes.
+  (Enforced: `ui-foundation sync --check` in verify.)
+
+## Required States
+Every data view handles: loading, empty, error, and success. Use
+`<Skeleton>`, `<Empty>`, and the error boundary — `DataTable` already does.
+Every screen has one Playwright test per state, forced via MSW overrides
+(`@tristan2828/ui-foundation/testing`).
+
+## Design Language
+Colour, tone, badges, cell patterns and density follow
+`docs/foundation/design-language.md` and `docs/foundation/cell-patterns.md`.
+A pattern the foundation lacks is worth raising there: the design language
+grows in the package so every app gets it, with axe contrast coverage in
+both themes.
+
+## Scope and Stopping
+- Do the task you were given and nothing beyond it. A task is done when
+  `npm run verify` passes — not when it feels complete.
+- If verify cannot pass without breaking a Hard Rule, an instruction
+  conflicts with current library docs, or the change would exceed the
+  task's scope: write `docs/BLOCKERS.md` (what, why, what you tried) and
+  stop. Do not guess, do not widen scope.
+- Ideas that are out of scope go in the app's backlog, not in code.
+
+## Correct Patterns
+```tsx
+// Error handling — AppError, never a raw response
+const { data, error } = useWidgetsQuery(query)
+if (error) return <ErrorState error={error} />   // error is AppError
+
+// Validation — server field errors bind straight to the form
+form.setError(field, { message: err.fieldErrors[field][0] })
+
+// Color — semantic tokens only
+<div className="bg-card text-card-foreground border-border" />
+
+// Forms — FieldGroup wraps every field, never a bare <label>+<input> stack
+<FieldGroup>
+  <Field>
+    <FieldLabel htmlFor="name">Name</FieldLabel>
+    <Input id="name" {...register('name')} />
+  </Field>
+</FieldGroup>
+```
+
+## Tooling
+Look up shadcn component APIs with `npx shadcn@<tools.shadcn> view <name>`
+before guessing props — component APIs move between releases and training
+data lags them. The package's own props are in its type declarations
+(`node_modules/@tristan2828/ui-foundation/dist/**/*.d.ts`).
+
+## Before You Finish
+Run `npm run verify`. It must pass. Do not report a task complete on a
+failing gate. The developer reviews results — the running app, a
+screenshot, an options page — not every line, so the gates are the safety
+net.
+
+## Adding an Entity
+Follow `docs/foundation/add-an-entity.md` (in Claude Code, `/new-entity
+<Name>` is a shortcut to it). It builds from the entity's plan,
+`docs/entities/<entity>.md`; if there's no plan, work one out with the
+developer first. Never guess the fields.
+
+## Upgrading the Foundation
+```bash
+npm install @tristan2828/ui-foundation@<version>
+npx ui-foundation sync
+npm run verify
+```
+Read the release notes between your version and the new one first
+(https://github.com/Tristan2828/ui-foundation/releases). `sync` rewrites
+this block, `docs/foundation/` and the agent files; commit what it writes.
+
+## Changing the Foundation
+The package is shared by every app. When this app needs something it
+doesn't do:
+1. Prefer a prop or slot the package already has.
+2. If the change is generic — another app would want it — raise it in the
+   foundation repo (an issue, or a PR against `packages/ui-foundation`), and
+   build this app's screen once the release ships. That's the path a fix
+   takes to reach every app.
+3. If it is truly this app's alone, build it in `src/` on top of the
+   package's exports — a new component, not a modified copy of one.

package/conventions/agents/deny-impl-read.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// PreToolUse hook for the spec-tester subagent: refuses any Read of the
+// app's gateway implementation, or the package's. This is what makes "tests written
+// from openapi.yaml, not from the implementation" an enforced guarantee
+// instead of a prompt instruction. Must be declared in spec-tester.md's own
+// frontmatter — subagents do not inherit hooks from .claude/settings.json.
+import { readFileSync } from 'node:fs';
+
+const DENIED_PATTERNS = [
+  /src[\\/]api[\\/]gateway[\\/]/,
+  /ui-foundation[\\/]dist[\\/](api[\\/](gateway|transport)|gateway\.js)/,
+];
+
+let input = '';
+try {
+  input = readFileSync(0, 'utf8');
+} catch {
+  process.exit(0);
+}
+
+let payload;
+try {
+  payload = JSON.parse(input);
+} catch {
+  process.exit(0);
+}
+
+const filePath = payload?.tool_input?.file_path ?? '';
+if (DENIED_PATTERNS.some((re) => re.test(filePath))) {
+  console.error(
+    `spec-tester may not read implementation files. Denied: ${filePath}. Write tests from openapi.yaml and the UI contracts only.`,
+  );
+  process.exit(2);
+}
+
+process.exit(0);

package/conventions/agents/skills/new-entity/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: new-entity
+description: This skill should be used when the user asks to "add an entity", "add a new entity", "scaffold a CRUD screen", "add a resource screen", or names a new domain object (e.g. "add Invoice") that needs a spec, gateway, mocks, table, and form built following this repo's widgets reference pattern.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent
+---
+
+Add a full CRUD entity end to end. The entity name is this skill's
+argument — if none was given, ask for one before proceeding.
+
+Read `docs/foundation/add-an-entity.md` in full, then follow it exactly, in order —
+starting with its "Before anything: the entity plan" section. Never guess
+what the entity is: every field comes from `docs/entities/<entity>.md`,
+and if that file doesn't exist you plan it with the developer and wait for
+their go-ahead before building anything. That file is the only copy of the
+playbook; this skill deliberately does not repeat it, so the two can't
+drift apart. Do not add anything beyond what it lists — note extra ideas
+in the app's backlog.
+
+This skill is a shortcut, not a gate: a developer asking in plain words
+("add a Game entity following docs/foundation/add-an-entity.md") gets exactly the
+same workflow, in Claude Code or any other tool. The plan requirement is
+what keeps an agent from building on its own initiative.

package/conventions/agents/spec-tester.md

@@ -0,0 +1,35 @@
+---
+name: spec-tester
+description: Writes gateway translation tests from openapi.yaml and contracts.ts only. Used in Phase 2 and by the new-entity playbook — never invoked to test code it can read.
+tools: Read, Write, Bash(vitest *)
+hooks:
+  PreToolUse:
+    - matcher: "Read"
+      hooks:
+        - type: command
+          command: "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/deny-impl-read.mjs"
+---
+
+Write gateway tests from `openapi.yaml` and the UI contracts `Page<T>`,
+`AppError` and `QuerySpec` (their type declarations are in
+`node_modules/@tristan2828/ui-foundation/dist/api/contracts.d.ts`). You have
+not seen the implementation in `src/api/gateway/` and must not read it — a
+`PreToolUse` hook will refuse those reads.
+
+Assert, from the spec alone:
+
+- A 422 response becomes `AppError` with `kind: 'validation'` and populated
+  `fieldErrors`.
+- Paginated list responses normalize to `Page<T>` (`items`, `total`,
+  `page`, `pageSize`).
+- A network failure (no response reached) becomes `kind: 'network'`, never
+  a false success.
+- Other error shapes (404, 401, 500) map to `notfound`, `auth`, `server`
+  respectively.
+
+Write the tests to fail first — the gateway that makes them pass does not
+exist yet the first time you run in Phase 2. That is correct.
+
+Do not attempt to work around a denied read. If you are refused a file you
+believe you need, stop and report which file and why in your final
+response — do not guess at the gateway's behavior instead.