create-simone-app 0.1.0

package/src/scaffold.ts

@@ -0,0 +1,304 @@
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, symlink, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { basename, dirname, extname, join, resolve } from 'node:path'
+
+import { type Options, deviationsFor } from './options'
+import {
+  type App,
+  type Deviation,
+  type Layer,
+  TEMPLATES_DIR,
+  layersFor,
+  loadLayer,
+  walk,
+} from './templates'
+
+export interface ScaffoldResult {
+  dir: string
+  /** Relative paths that are (or would be) written, sorted. */
+  files: string[]
+  warnings: string[]
+}
+
+type Content = string | Uint8Array
+type Plan = Map<string, Content>
+
+const TEXT_EXT = new Set([
+  '.ts',
+  '.tsx',
+  '.js',
+  '.mjs',
+  '.json',
+  '.md',
+  '.html',
+  '.css',
+  '.yaml',
+  '.yml',
+  '.toml',
+  '.sh',
+  '.txt',
+  '.svg',
+  '',
+])
+const isText = (file: string) =>
+  TEXT_EXT.has(extname(file)) || basename(file).startsWith('.')
+
+const AGENTS_HEADER =
+  '<!-- Generated by `bun run agents:build` from docs/agents/*.md. Edit the fragments, not this file. -->\n\n'
+
+const renderDeviations = (rows: Deviation[]): string => {
+  const body = rows.length
+    ? rows.map((d) => `| ${d.rule} | ${d.what} | ${d.why} |`).join('\n')
+    : '| — | none | every choice follows the ai-rules |'
+  return `## Deviations from ai-rules\n\n| Rule § | Deviation | Why |\n|---|---|---|\n${body}\n`
+}
+
+interface PackageJson {
+  name?: string
+  scripts?: Record<string, string>
+  dependencies?: Record<string, string>
+  devDependencies?: Record<string, string>
+  [key: string]: unknown
+}
+
+const sorted = (o: Record<string, string>) =>
+  Object.fromEntries(Object.entries(o).sort(([a], [b]) => a.localeCompare(b)))
+
+/** Base package.json + variant deps/removals, deps sorted for stable diffs. */
+const mergePackageJson = (base: string, layers: Layer[]): string => {
+  const pkg = JSON.parse(base) as PackageJson
+  const drop = (o: Record<string, string>, keys: string[]) =>
+    Object.fromEntries(Object.entries(o).filter(([k]) => !keys.includes(k)))
+  let deps = { ...pkg.dependencies }
+  let dev = { ...pkg.devDependencies }
+  let scripts = { ...pkg.scripts }
+  for (const { manifest } of layers) {
+    deps = drop(
+      { ...deps, ...manifest.dependencies },
+      manifest.removeDependencies ?? [],
+    )
+    dev = drop(
+      { ...dev, ...manifest.devDependencies },
+      manifest.removeDevDependencies ?? [],
+    )
+    scripts = drop(scripts, manifest.removeScripts ?? [])
+  }
+  return (
+    JSON.stringify(
+      {
+        ...pkg,
+        scripts,
+        dependencies: sorted(deps),
+        devDependencies: sorted(dev),
+      },
+      null,
+      2,
+    ) + '\n'
+  )
+}
+
+/** Builds one app (fe or api) into `plan` under `prefix` ('' or 'apps/fe/'). */
+const planApp = async (
+  app: App,
+  options: Options,
+  plan: Plan,
+  prefix: string,
+  stripCi: boolean,
+) => {
+  const layers = await Promise.all(
+    layersFor(app, options).map((name) => loadLayer(app, name)),
+  )
+  const token = (s: string) => s.replaceAll('__NAME__', options.name)
+  const put = (rel: string, content: Content) => plan.set(prefix + rel, content)
+
+  for (const layer of layers) {
+    for (const rel of await walk(layer.dir)) {
+      if (rel === 'variant.json') continue
+      const target =
+        basename(rel) === '_gitignore' ? join(dirname(rel), '.gitignore') : rel
+      const source = join(layer.dir, rel)
+      put(
+        target,
+        isText(rel)
+          ? token(await readFile(source, 'utf8'))
+          : new Uint8Array(await readFile(source)),
+      )
+    }
+  }
+  const removed = layers
+    .flatMap((l) => l.manifest.remove ?? [])
+    .concat(stripCi ? ['.github'] : [])
+  for (const key of [...plan.keys()]) {
+    const rel = key.startsWith(prefix) ? key.slice(prefix.length) : undefined
+    if (rel && removed.some((r) => rel === r || rel.startsWith(r + '/')))
+      plan.delete(key)
+  }
+
+  const basePkg = plan.get(prefix + 'package.json')
+  if (typeof basePkg === 'string')
+    put('package.json', mergePackageJson(basePkg, layers))
+
+  // AGENTS.md from fragments: base + variant fragments + deviations.
+  const fragments = [
+    'base',
+    ...layers.flatMap((l) => l.manifest.agents ?? []),
+    'deviations',
+  ]
+  const deviations = layers.flatMap((l) => l.manifest.deviations ?? [])
+  put('docs/agents/fragments.json', JSON.stringify(fragments, null, 2) + '\n')
+  put('docs/agents/deviations.md', renderDeviations(deviations))
+  const parts = fragments.map((f) => {
+    const content = plan.get(`${prefix}docs/agents/${f}.md`)
+    if (typeof content !== 'string')
+      throw new Error(`missing AGENTS fragment ${f} for ${app}`)
+    return content.trim()
+  })
+  put('AGENTS.md', AGENTS_HEADER + parts.join('\n\n') + '\n')
+
+  if (app === 'fe') {
+    const stateLibs = layers.flatMap((l) => l.manifest.eslint?.stateLibs ?? [])
+    put('eslint.variants.json', JSON.stringify({ stateLibs }, null, 2) + '\n')
+  }
+  // Claude Code shares the skills folder with Codex through a symlink (recreated, never shipped).
+  put('.claude/skills', SYMLINK)
+}
+
+const SYMLINK = '__symlink__:../.agents/skills'
+
+/** Computes every file of the project in memory. Writes nothing. */
+export const plan = async (options: Options): Promise<Plan> => {
+  const files: Plan = new Map()
+  if (options.preset === 'fullstack') {
+    const root = join(TEMPLATES_DIR, 'fullstack')
+    for (const rel of await walk(root)) {
+      const target = basename(rel) === '_gitignore' ? '.gitignore' : rel
+      files.set(
+        target,
+        (await readFile(join(root, rel), 'utf8')).replaceAll(
+          '__NAME__',
+          options.name,
+        ),
+      )
+    }
+    if (!options.features.includes('github-ci'))
+      files.delete('.github/workflows/ci.yml')
+    await planApp(
+      'api',
+      { ...options, name: `${options.name}-api` },
+      files,
+      'apps/api/',
+      true,
+    )
+    await planApp(
+      'fe',
+      { ...options, name: `${options.name}-fe` },
+      files,
+      'apps/fe/',
+      true,
+    )
+  } else {
+    await planApp(options.preset, options, files, '', false)
+  }
+  return files
+}
+
+const write = async (dir: string, files: Plan) => {
+  for (const [rel, content] of files) {
+    const target = join(dir, rel)
+    await mkdir(dirname(target), { recursive: true })
+    if (content === SYMLINK) {
+      if (!existsSync(target)) await symlink('../.agents/skills', target)
+    } else {
+      await writeFile(target, content)
+    }
+  }
+}
+
+/** Where the company ai-rules live: `AI_RULES_PATH` or the conventional checkout. */
+export const rulesSource = (): string =>
+  process.env.AI_RULES_PATH ?? join(homedir(), 'Progetti', 'ai-rules')
+
+// node:child_process, not Bun.spawn: Vitest runs this module on Node.
+const run = (
+  cmd: string[],
+  cwd: string,
+  env: Record<string, string> = {},
+  quiet = false,
+) =>
+  new Promise<void>((resolvePromise, reject) => {
+    const [bin, ...args] = cmd
+    if (!bin) throw new Error('empty command')
+    const child = spawn(bin, args, {
+      cwd,
+      env: { ...process.env, ...env },
+      stdio: ['ignore', quiet ? 'ignore' : 'inherit', 'inherit'],
+    })
+    child.on('error', reject)
+    child.on('exit', (code) =>
+      code === 0
+        ? resolvePromise()
+        : reject(new Error(`${cmd.join(' ')} exited with ${code}`)),
+    )
+  })
+
+/** Mirrors the ai-rules into each app (docs/ai-rules + MANIFEST.json). Missing source = warning, never an error. */
+const syncRules = async (dir: string, appDirs: string[]): Promise<string[]> => {
+  const source = rulesSource()
+  if (!existsSync(join(source, 'README.md'))) {
+    return [
+      `ai-rules not found at ${source}: docs/ai-rules/ left empty. Set AI_RULES_PATH and run \`bun run rules:sync\` before pushing (CI runs rules:check).`,
+    ]
+  }
+  for (const app of appDirs) {
+    await run(
+      ['bun', 'scripts/rules-sync.ts'],
+      join(dir, app),
+      { AI_RULES_PATH: source },
+      true,
+    )
+  }
+  return []
+}
+
+export const scaffold = async (options: Options): Promise<ScaffoldResult> => {
+  const dir = resolve(options.dir)
+  const files = await plan(options)
+  const list = [...files.keys()].sort()
+  const appDirs =
+    options.preset === 'fullstack' ? ['apps/api', 'apps/fe'] : ['.']
+  if (options.dryRun) return { dir, files: list, warnings: [] }
+
+  if (existsSync(dir) && (await walk(dir)).length > 0) {
+    throw new Error(`target directory is not empty: ${dir}`)
+  }
+  await write(dir, files)
+  const warnings = await syncRules(dir, appDirs)
+  if (options.install) {
+    await run(['bun', 'install'], dir)
+    // Token substitution can change line widths: normalise once so `format:check` is green from commit 1.
+    for (const app of appDirs)
+      await run(
+        ['bunx', 'prettier', '--write', '--log-level', 'warn', '.'],
+        join(dir, app),
+      )
+  }
+  if (options.git) {
+    await run(['git', 'init', '-q', '-b', 'main'], dir)
+    await run(['git', 'add', '-A'], dir)
+    await run(
+      [
+        'git',
+        'commit',
+        '-q',
+        '-m',
+        `chore: scaffold ${options.name} with create-simone-app`,
+      ],
+      dir,
+    )
+  }
+  return { dir, files: list, warnings }
+}
+
+export { deviationsFor }

package/src/templates.ts

@@ -0,0 +1,77 @@
+import { existsSync } from 'node:fs'
+import { readFile, readdir } from 'node:fs/promises'
+import { join, relative, resolve } from 'node:path'
+
+import type { Options } from './options'
+
+export const TEMPLATES_DIR = resolve(import.meta.dirname, '../templates')
+
+export type App = 'fe' | 'api'
+
+export interface Deviation {
+  rule: string
+  what: string
+  why: string
+}
+
+/** variant.json: what a variant adds/removes on top of base. Files next to it are overlaid. */
+export interface VariantManifest {
+  dependencies?: Record<string, string>
+  devDependencies?: Record<string, string>
+  remove?: string[]
+  removeDependencies?: string[]
+  removeDevDependencies?: string[]
+  removeScripts?: string[]
+  /** AGENTS.md fragment names shipped in this variant's docs/agents/. */
+  agents?: string[]
+  deviations?: Deviation[]
+  eslint?: { stateLibs?: string[] }
+}
+
+export interface Layer {
+  name: string
+  dir: string
+  manifest: VariantManifest
+}
+
+/** Ordered layers for an app: base first, later layers override earlier files. */
+export const layersFor = (app: App, options: Options): string[] => {
+  const layers = ['base']
+  if (app === 'fe') {
+    layers.push(`variants/state/${options.state}`, `variants/ui/${options.ui}`)
+    for (const f of ['msw', 'playwright'] as const) {
+      if (!options.features.includes(f))
+        layers.push(`variants/features/no-${f}`)
+    }
+  } else {
+    layers.push(`variants/framework/${options.framework}`)
+  }
+  if (!options.features.includes('github-ci'))
+    layers.push('variants/features/no-github-ci')
+  return layers
+}
+
+export const loadLayer = async (app: App, name: string): Promise<Layer> => {
+  const dir = join(TEMPLATES_DIR, app, name)
+  if (!existsSync(dir))
+    throw new Error(`template layer not found: ${app}/${name}`)
+  const manifestPath = join(dir, 'variant.json')
+  const manifest: VariantManifest = existsSync(manifestPath)
+    ? (JSON.parse(await readFile(manifestPath, 'utf8')) as VariantManifest)
+    : {}
+  return { name, dir, manifest }
+}
+
+/** All files under `dir`, as paths relative to it. Symlinks are skipped (the scaffold recreates them). */
+export const walk = async (dir: string, root = dir): Promise<string[]> => {
+  const entries = await readdir(dir, { withFileTypes: true })
+  const files = await Promise.all(
+    entries.map(async (e) => {
+      const full = join(dir, e.name)
+      if (e.isSymbolicLink()) return []
+      if (e.isDirectory()) return walk(full, root)
+      return [relative(root, full)]
+    }),
+  )
+  return files.flat().sort()
+}

package/templates/api/base/.agents/skills/ai-rules/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: ai-rules
+description: Consult the company ai-rules mirrored in docs/ai-rules before writing code that they cover (test selectors, and in the FE template also stack, TanStack, shadcn, a11y). Use whenever a rule might apply.
+---
+
+# ai-rules
+
+1. `AGENTS.md` → "## ai-rules" table maps topic → `docs/ai-rules/<file>`. Read the relevant file section, not the whole file.
+2. The rules are company-wide and **read-only**: never edit `docs/ai-rules/*`. If a rule looks wrong, propose a change upstream and keep following it here.
+3. A deliberate deviation must be listed in `docs/agents/deviations.md` with the rule § and the reason, then `bun run agents:build`.
+4. `bun run rules:check` fails when the mirror drifted from upstream (`AI_RULES_PATH` or `~/Progetti/ai-rules`): run `bun run rules:sync` and commit `docs/ai-rules/` + `MANIFEST.json` in their own `chore(rules): sync ai-rules` commit.
+5. The "## Non-negotiables" digest in `AGENTS.md` must never contradict `docs/ai-rules/`; the full text wins.

package/templates/api/base/.agents/skills/plan-feature/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: plan-feature
+description: Turn a feature request into TASK.md with small verifiable increments (one commit each). Use before writing code for anything bigger than a one-line fix.
+---
+
+# plan-feature
+
+1. Copy `TASK.md.template` to `TASK.md` (git-ignored is fine; it may also be committed with the feature).
+2. Fill **Goal** in one sentence and **Context** with the files that will change (read them first).
+3. Split into increments of ≤ 1 hour each. Each row: what, files, how to verify (a test name or a curl), commit subject in Conventional Commits.
+4. Ordering rule: schema → repository → router → openapi → test, or test-first when behaviour is clear (see `tdd-step`).
+5. Anything that would deviate from `docs/ai-rules/` goes into the **Deviations** section _before_ implementation.
+6. Show the plan and wait for confirmation only if a decision is not covered by `AGENTS.md`; otherwise start with increment 1.

package/templates/api/base/.agents/skills/review-diff/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: review-diff
+description: Review the working-tree diff against AGENTS.md before committing. Use at the end of every increment or when asked "review".
+---
+
+# review-diff
+
+1. `git diff` and `git diff --staged`; read `AGENTS.md`.
+2. Run `bun run verify`; a red verify is finding #1.
+3. Walk the checklist in `.claude/agents/reviewer.md` (contracts, types, runtime, tests, openapi, generated files untouched).
+4. Report only violations, as `path:line — problem — fix`. No praise, no restating the diff.
+5. End with APPROVE / REQUEST CHANGES.

package/templates/api/base/.agents/skills/tdd-step/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: tdd-step
+description: Execute one increment red → green → refactor → verify → commit. Use for every increment of TASK.md.
+---
+
+# tdd-step
+
+1. **Red**: write the failing test first in `test/<module>.test.ts` (supertest on `createApp()`). Run `bunx vitest run test/<module>.test.ts` and confirm it fails for the right reason.
+2. **Green**: minimal code in `src/modules/<module>/`. No extra abstractions, no speculative options.
+3. **Refactor** only what the new code touched. Keep the response shapes from `AGENTS.md`.
+4. `openapi.yaml` updated if a route changed.
+5. `bun run verify` must be green (typecheck, lint, format, AGENTS check, coverage ≥80%).
+6. One commit: `type(scope): subject` in English, body in Italian explaining _why_ (not what). Show `git log --oneline -1`.
+7. Tick the increment in `TASK.md`.

package/templates/api/base/.claude/agents/reviewer.md

@@ -0,0 +1,20 @@
+---
+name: reviewer
+description: Reviews a diff against AGENTS.md conventions and docs/ai-rules. Use after each increment, before committing.
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
+You review the current diff (`git diff` + `git diff --staged`) of __NAME__. Read `AGENTS.md` first.
+
+Check, in this order, and report only violations with file:line and a one-line fix:
+
+1. `bun run verify` is green (run it).
+2. Conventions: `{ data, page, limit, total }` on lists, `HttpError` + `{ error, details? }`, `validate()` on every route with input, status codes 200/201/404/422/500.
+3. Types: no `any`, `@ts-ignore`, `enum`, `!`; `import type` where possible.
+4. Runtime: no `Bun.*` in `src/`.
+5. Tests: every new route has a supertest file covering happy path, 422 and 404.
+6. `openapi.yaml` updated for any route change.
+7. Nothing edited by hand in `AGENTS.md`, `docs/ai-rules/`, `src/data/*.json`.
+
+Finish with "APPROVE" or "REQUEST CHANGES" and, if changes, the commit message subject you would use.

package/templates/api/base/.claude/hooks/format.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# PostToolUse hook: prettier + eslint --fix on the file just edited.
+# Reads $CLAUDE_FILE_PATH, falls back to the hook JSON on stdin. Exit 0 on anything not lintable.
+set -uo pipefail
+
+file="${CLAUDE_FILE_PATH:-}"
+if [ -z "$file" ] && [ ! -t 0 ]; then
+  file="$(bun -e 'const s = await Bun.stdin.text(); try { const j = JSON.parse(s); console.log(j.tool_input?.file_path ?? j.file_path ?? "") } catch { console.log("") }')"
+fi
+[ -n "$file" ] && [ -f "$file" ] || exit 0
+
+case "$file" in
+  *.ts|*.tsx|*.js|*.jsx|*.json|*.md|*.yaml|*.yml|*.css) ;;
+  *) exit 0 ;;
+esac
+
+cd "$(dirname "${BASH_SOURCE[0]}")/../.." || exit 0
+bunx prettier --write --log-level warn "$file" || true
+case "$file" in
+  *.ts|*.tsx|*.js|*.jsx) bunx eslint --fix --no-warn-ignored "$file" || true ;;
+esac
+exit 0

package/templates/api/base/.claude/settings.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Bash(bun run:*)",
+      "Bash(bun install:*)",
+      "Bash(bun add:*)",
+      "Bash(bunx vitest:*)",
+      "Bash(bunx eslint:*)",
+      "Bash(bunx prettier:*)",
+      "Bash(bunx tsc:*)",
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)"
+    ],
+    "deny": [
+      "Bash(git push:*)",
+      "Bash(rm -rf:*)",
+      "Read(.env)",
+      "Read(.env.*)",
+      "Edit(AGENTS.md)",
+      "Edit(docs/ai-rules/**)",
+      "Edit(src/data/*.json)"
+    ]
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          { "type": "command", "command": "bash .claude/hooks/format.sh" }
+        ]
+      }
+    ]
+  }
+}

package/templates/api/base/.codex/agents/reviewer.toml

@@ -0,0 +1,7 @@
+name = "reviewer"
+description = "Reviews the diff against AGENTS.md conventions and docs/ai-rules."
+instructions = """
+Read AGENTS.md, then `git diff` and `git diff --staged`. Run `bun run verify`.
+Report only violations as `path:line — problem — fix`, following the checklist in .claude/agents/reviewer.md.
+End with APPROVE or REQUEST CHANGES.
+"""

package/templates/api/base/.codex/config.toml

@@ -0,0 +1,10 @@
+# Codex CLI project config. AGENTS.md is picked up natively; hooks in hooks.json mirror .claude/settings.json.
+model = "gpt-5-codex"
+approval_policy = "on-request"
+sandbox_mode = "workspace-write"
+
+[projects."."]
+trust_level = "trusted"
+
+[agents]
+reviewer = "agents/reviewer.toml"

package/templates/api/base/.codex/hooks.json

@@ -0,0 +1,12 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "apply_patch|write_file|edit_file",
+        "hooks": [
+          { "type": "command", "command": "bash .claude/hooks/format.sh" }
+        ]
+      }
+    ]
+  }
+}

package/templates/api/base/.env.example

@@ -0,0 +1,2 @@
+PORT=4000
+LOG_LEVEL=info

package/templates/api/base/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - run: bun install --frozen-lockfile
+      - run: bun run rules:check
+      - run: bun run verify

package/templates/api/base/.prettierignore

@@ -0,0 +1,10 @@
+node_modules
+dist
+coverage
+bun.lock
+docs/ai-rules
+AGENTS.md
+
+docs/agents/deviations.md
+docs/agents/fragments.json
+eslint.variants.json

package/templates/api/base/.prettierrc

@@ -0,0 +1,20 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "printWidth": 80,
+  "tabWidth": 2,
+  "trailingComma": "all",
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "endOfLine": "lf",
+  "plugins": ["@trivago/prettier-plugin-sort-imports"],
+  "importOrder": [
+    "^react",
+    "^@tanstack/(.*)$",
+    "<THIRD_PARTY_MODULES>",
+    "^@/(.*)$",
+    "^[./]"
+  ],
+  "importOrderSeparation": true,
+  "importOrderSortSpecifiers": true
+}

package/templates/api/base/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/api/base/README.md

@@ -0,0 +1,43 @@
+# __NAME__
+
+Mock REST API built with **Bun + Express 5 + Zod**. Backend for [`simone-fe-template`](../simone-fe-template) and pilot for the `create-simone-app` generator (`api/base` + `framework/express` variant).
+
+## Quickstart
+
+```bash
+bun install
+cp .env.example .env
+bun run dev          # http://localhost:4000
+bun run verify       # typecheck + lint + format + AGENTS check + tests (coverage ≥ 80%)
+```
+
+## Endpoints
+
+| Method | Path                           | Notes                                                                      |
+| ------ | ------------------------------ | -------------------------------------------------------------------------- |
+| GET    | `/api/health`                  | liveness                                                                   |
+| GET    | `/api/users?page&limit&q&sort` | `{ data, page, limit, total }`, `sort=-name` for desc                      |
+| GET    | `/api/users/:id`               | 404 `{ error }`                                                            |
+| GET    | `/api/products?category&sort`  | same list contract                                                         |
+| GET    | `/api/products/:id`            |                                                                            |
+| POST   | `/api/orders`                  | `{ userId, items[{ productId, qty }] }` → 201, prices resolved server-side |
+| GET    | `/api/stats`                   | counts, revenue, top category                                              |
+| GET    | `/docs.json`                   | parsed `openapi.yaml`                                                      |
+
+Validation errors → `422 { error, details: [{ path, message }] }`.
+
+## Data
+
+`src/data/*.json` are committed fixtures (50 users, 20 products, 10 orders) generated by `bun run seed:regen` with a fixed faker seed. The API keeps them in memory; `POST /api/orders` mutates memory only.
+
+## AI harness
+
+- `AGENTS.md` (generated from `docs/agents/*.md` via `bun run agents:build`) is the single source of conventions; `CLAUDE.md` just includes it.
+- Company **ai-rules** are mirrored read-only in `docs/ai-rules/` with `MANIFEST.json`; `bun run rules:check` fails on drift, `bun run rules:sync` refreshes from `$AI_RULES_PATH` (default `~/Progetti/ai-rules`).
+- Skills in `.agents/skills/` (shared by Claude Code via the `.claude/skills` symlink and Codex): `ai-rules`, `plan-feature`, `tdd-step`, `review-diff`.
+- `.claude/settings.json`: permissions + PostToolUse hook `format.sh` (prettier + eslint --fix). `.codex/` mirrors the same hook and reviewer agent.
+- `TASK.md.template`: per-feature plan with one commit per increment.
+
+## Scripts
+
+`dev` · `build` · `test` · `test:watch` · `lint` · `lint:fix` · `format` · `format:check` · `typecheck` · `verify` · `rules:sync` · `rules:check` · `seed:regen` · `agents:build` · `agents:check`