fix(core-shared): satisfy strict typecheck in purge job + audit hook

The hoisted applyAction closure loses the collection narrowing (TS18048)
and apps with generated CollectionSlug unions reject comparing slugs to
'audit-logs' (TS2367). Re-bind the narrowed collection and widen the
slug comparison to string.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.claude/hooks/bash-guard.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Tier 1 — blocks dangerous shell invocations the agent shouldn't run
+# autonomously. Reads PreToolUse JSON on stdin; exits 2 with stderr to block,
+# 0 to allow. Reinforces the Git Safety Protocol in CLAUDE.md.
+
+set -euo pipefail
+
+input=$(cat)
+cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // ""')
+
+blocks=(
+  '(^|[[:space:]])--no-verify([[:space:]]|$)'
+  '(^|[[:space:]])--no-gpg-sign([[:space:]]|$)'
+  'git[[:space:]]+push[[:space:]]+([^&|;]*[[:space:]])?(-f|--force)([[:space:]]|$)'
+  'git[[:space:]]+reset[[:space:]]+[^&|;]*--hard'
+  'git[[:space:]]+clean[[:space:]]+-[a-zA-Z]*f'
+  'git[[:space:]]+checkout[[:space:]]+\.([[:space:]]|$)'
+  'git[[:space:]]+restore[[:space:]]+\.([[:space:]]|$)'
+  'git[[:space:]]+branch[[:space:]]+-D'
+  'git[[:space:]]+commit[[:space:]]+[^&|;]*--amend'
+  'rm[[:space:]]+-rf?[[:space:]]+/'
+  'rm[[:space:]]+-rf?[[:space:]]+~'
+  'rm[[:space:]]+-rf?[[:space:]]+\$HOME'
+)
+
+for pattern in "${blocks[@]}"; do
+  if [[ "$cmd" =~ $pattern ]]; then
+    cat >&2 <<EOF
+BLOCKED by .claude/hooks/bash-guard.sh
+
+This template forbids the agent from running this autonomously:
+  Pattern: ${pattern}
+  Command: ${cmd}
+
+If the user has explicitly authorized this action this turn, ask them to
+run it themselves (\`! <command>\` in the prompt) or document the override
+in their request. See CLAUDE.md → "Executing actions with care" and the
+Git Safety Protocol section.
+EOF
+    exit 2
+  fi
+done
+
+exit 0

.claude/hooks/generator-first-nudge.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Tier 1 — enforces the generator-first rule. Blocks hand-rolled scaffolding
+# under packages/ or apps/ via mkdir/cp/touch. Use `pnpm turbo gen <kind>`.
+
+set -euo pipefail
+
+input=$(cat)
+cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // ""')
+
+# Match creation of a NEW top-level packages/<name>/ or apps/<name>/ directory.
+# Allows working inside an existing package (e.g. `mkdir -p packages/blog/src/foo`).
+patterns=(
+  'mkdir[[:space:]]+(-p[[:space:]]+)?packages/[a-zA-Z0-9_-]+/?([[:space:]]|$)'
+  'mkdir[[:space:]]+(-p[[:space:]]+)?apps/[a-zA-Z0-9_-]+/?([[:space:]]|$)'
+  'cp[[:space:]]+-[rR][[:space:]]+packages/[^[:space:]]+[[:space:]]+packages/[a-zA-Z0-9_-]+/?([[:space:]]|$)'
+)
+
+for pattern in "${patterns[@]}"; do
+  if [[ "$cmd" =~ $pattern ]]; then
+    cat >&2 <<EOF
+BLOCKED by .claude/hooks/generator-first-nudge.sh
+
+This template enforces "generator-first" — hand-rolled scaffolding under
+packages/ or apps/ is forbidden. Use a generator:
+
+  pnpm turbo gen feature              # new vertical feature
+  pnpm turbo gen core-package <name>  # optional core (events|realtime|audit|trpc|ui)
+  pnpm turbo gen event                # event contract or handler
+  pnpm turbo gen job                  # background job
+  pnpm turbo gen realtime             # realtime channel or handler
+  pnpm turbo gen core-ui-component    # atomic-design UI component
+
+If you're modifying an existing package (e.g. \`mkdir -p packages/blog/src/x\`)
+this hook will not block you. If you genuinely need to bypass (e.g. fixing
+the generator itself), ask the user to authorize and re-state the intent.
+
+Command: ${cmd}
+EOF
+    exit 2
+  fi
+done
+
+exit 0

.claude/hooks/library-policy-nudge.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# Advisory — nudges the agent to run /evaluate-library before adding runtime
+# dependencies. Non-blocking (exit 0). Stdout is injected as system-reminder
+# context by the harness.
+#
+# Dispatches on payload shape:
+#   .tool_input.command   → PreToolUse / Bash  (pnpm add / pnpm i <pkg>)
+#   .tool_input.file_path → PostToolUse / Edit|Write (**/package.json edits)
+
+set -euo pipefail
+
+input=$(cat)
+
+# --- PreToolUse / Bash path ---
+cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // ""')
+if [[ -n "$cmd" ]]; then
+  # Match: pnpm add <...> or pnpm i <pkg> — must have a space after keyword
+  if [[ "$cmd" =~ (^|[[:space:]])pnpm[[:space:]]+(add[[:space:]]|i[[:space:]]) ]]; then
+    # Skip dev-dependency installs — no policy evaluation needed for devDeps
+    if [[ ! "$cmd" =~ (^|[[:space:]])(-D|--save-dev)([[:space:]]|$) ]]; then
+      cat <<'EOF'
+[library-policy-nudge] Runtime dependency detected — evaluate before adding.
+
+Run the evaluate-library skill first:
+  /evaluate-library <name> --tier <feature|core|app> --target <package-path>
+
+This ensures the dependency is logged in docs/decisions/ before the pre-commit gate fires.
+EOF
+    fi
+  fi
+  exit 0
+fi
+
+# --- PostToolUse / Edit|Write path ---
+file_path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // ""')
+if [[ "$file_path" == */package.json ]]; then
+  cat <<'EOF'
+[library-policy-nudge] package.json edited — verify any new runtime dependencies are evaluated.
+
+If you added a runtime dependency, run the evaluate-library skill:
+  /evaluate-library <name> --tier <feature|core|app> --target <package-path>
+
+This ensures the dependency is logged in docs/decisions/ before the pre-commit gate fires.
+EOF
+fi
+
+exit 0

.claude/hooks/library-policy-nudge.test.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# Smoke tests for library-policy-nudge.sh
+# Usage: bash .claude/hooks/library-policy-nudge.test.sh
+
+set -euo pipefail
+
+SCRIPT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/library-policy-nudge.sh"
+MARKER="/evaluate-library"
+PASS=0
+FAIL=0
+
+assert_contains() {
+  local name="$1"
+  local input="$2"
+  local output
+  output=$(printf '%s' "$input" | bash "$SCRIPT" 2>/dev/null)
+  if echo "$output" | grep -qF "$MARKER"; then
+    echo "  PASS: $name"
+    PASS=$((PASS + 1))
+  else
+    echo "  FAIL: $name"
+    echo "    Expected stdout to contain: $MARKER"
+    echo "    Got: ${output:-<empty>}"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+assert_no_output() {
+  local name="$1"
+  local input="$2"
+  local output
+  output=$(printf '%s' "$input" | bash "$SCRIPT" 2>/dev/null)
+  if ! echo "$output" | grep -qF "$MARKER"; then
+    echo "  PASS: $name"
+    PASS=$((PASS + 1))
+  else
+    echo "  FAIL: $name"
+    echo "    Expected no $MARKER in stdout, got: $output"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+echo "library-policy-nudge.sh smoke tests"
+echo "------------------------------------"
+
+# pnpm add <pkg> → reminder (runtime dep)
+assert_contains \
+  "pnpm add foo triggers reminder" \
+  '{"tool_input":{"command":"pnpm add foo"}}'
+
+# pnpm add -D <pkg> → no reminder (dev dep)
+assert_no_output \
+  "pnpm add -D foo produces no reminder" \
+  '{"tool_input":{"command":"pnpm add -D foo"}}'
+
+# pnpm add --save-dev <pkg> → no reminder (dev dep, long flag)
+assert_no_output \
+  "pnpm add --save-dev foo produces no reminder" \
+  '{"tool_input":{"command":"pnpm add --save-dev foo"}}'
+
+# Edit on non-package.json → no reminder
+assert_no_output \
+  "Edit on feature.manifest.ts produces no reminder" \
+  '{"tool_input":{"file_path":"/workspace/packages/auth/src/feature.manifest.ts"}}'
+
+# Edit on package.json → reminder
+assert_contains \
+  "Edit on package.json triggers reminder" \
+  '{"tool_input":{"file_path":"/workspace/packages/auth/package.json"}}'
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+[[ $FAIL -eq 0 ]]

.claude/hooks/post-manifest-edit.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Tier 3 — when a feature.manifest.ts is edited, remind the agent to surface
+# drift and follow manifest-first ordering. Non-blocking (stderr exit 0 is
+# visible in transcript; we don't want this to kill the agent's flow).
+
+set -euo pipefail
+
+input=$(cat)
+file_path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // ""')
+
+if [[ "$file_path" != *"feature.manifest.ts" ]]; then
+  exit 0
+fi
+
+feature=$(echo "$file_path" | sed -nE 's|.*packages/([^/]+)/src/feature\.manifest\.ts$|\1|p')
+
+cat >&2 <<EOF
+[post-manifest-edit] feature.manifest.ts changed (${feature:-unknown feature})
+
+Manifest-first ordering reminder:
+  (1) manifest entry      ← you just did this
+  (2) contracts           — xInputSchema, xOutputSchema, IXUseCase
+  (3) tests (red)         — colocated *.test.ts
+  (4) implementation      — use-case + controller + DI binding
+
+Surface drift now:
+  pnpm --filter @repo/${feature:-<feature>} test typecheck lint
+  pnpm conformance
+EOF
+
+exit 0

.claude/hooks/prompt-context.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Tier 2 — injects relevant ADR + workflow pointers when the user's prompt
+# mentions concepts covered by an ADR or a hard ordering rule.
+# stdout is appended to the agent's context for this turn.
+
+set -euo pipefail
+
+input=$(cat)
+prompt=$(printf '%s' "$input" | jq -r '.prompt // ""' | tr '[:upper:]' '[:lower:]')
+
+inject=()
+
+if echo "$prompt" | grep -qE 'event|publish|consume|cross-feature|job queue'; then
+  inject+=('Events/jobs: ADR-015 + docs/guides/events-and-jobs.md. Rules E0 (events for cross-feature only), E1 (handlers private), J0 (jobs for deferred work).')
+fi
+if echo "$prompt" | grep -qE 'realtime|socket\.io|channel|broadcast|presence'; then
+  inject+=('Realtime: ADR-016 + docs/guides/realtime.md. Rules R0 (state delivery only), R1 (handlers private), R2 (socket.io in core-realtime only).')
+fi
+if echo "$prompt" | grep -qE 'audit|compliance|gdpr|dpa|erasure'; then
+  inject+=('Audit: ADR-018 + docs/guides/audit-and-compliance.md. Optional core; scaffold with pnpm turbo gen core-package audit.')
+fi
+if echo "$prompt" | grep -qE 'sentry|otel|opentelemetry|tracing|instrumentation|pii|scrub'; then
+  inject+=('Instrumentation: ADR-014 (interfaces) + ADR-017 (OTel migration). PII rules non-negotiable: sendDefaultPii=false, server-side scrub at OTel processor layer.')
+fi
+if echo "$prompt" | grep -qE 'use case|use-case|controller|repository|feature\.manifest|new feature|scaffold'; then
+  inject+=('Manifest-first ordering: (1) manifest → (2) contracts (xInputSchema, xOutputSchema, IXUseCase) → (3) tests (red) → (4) impl (green). Use pnpm turbo gen feature/event/job/realtime — never hand-roll.')
+fi
+if echo "$prompt" | grep -qE 'prd|epic|story|task|sandcastle|dispatch|orchestrat'; then
+  inject+=('Workflow: docs/architecture/agent-first-workflow-and-conformance.md + ADR-019. PRDs live in docs/work/prds/ — use the to-prd skill. Stress-test plans with grill-with-docs.')
+fi
+if echo "$prompt" | grep -qE 'di container|inject|bind-production|bind-dev-seed|symbols'; then
+  inject+=('DI: ADR-008 (per-feature containers). Binders take ctx from core-shared/di. Use .toDynamicValue() for factory bindings. Tests inject mocks directly — no container rebinding.')
+fi
+if echo "$prompt" | grep -qE 'boundary|boundaries|cross-package|cross feature'; then
+  inject+=('Boundaries: ADR-006 + ADR-010. Five tags (app|core|core-composition|feature|tooling). Features may only depend on core + tooling. Enforced by ESLint + Turborepo boundaries.')
+fi
+if echo "$prompt" | grep -qE 'coverage|uncovered|lcov|mutation|stryker|coverage band'; then
+  inject+=('Coverage: ADR-020 + docs/guides/coverage.md (cookbook). 4 layers — L0 vitest thresholds, L1 pnpm coverage:diff (cover-the-diff), L2 coverage/summary.json (committed trend), L3 pnpm mutate (Stryker on entities + use-cases). Manifest-driven: feature.manifest.ts coverage.bands is the single source of truth.')
+fi
+if echo "$prompt" | grep -qE 'commit|message|changelog|conventional'; then
+  inject+=('Conventional Commits (non-negotiable): <type>(<scope>): <imperative subject> (≤72 chars). Types: feat|fix|docs|style|refactor|test|chore|perf|ci|build|revert. Use `!` for breaking changes. Body explains WHY if non-obvious. Examples: feat(auth): hash password before persisting; refactor(docs)!: consolidate scaffolding into guides. See CLAUDE.md Key Conventions.')
+fi
+if echo "$prompt" | grep -qE 'release|version|bump|semver|tag\b'; then
+  inject+=('Releases: ADR-021 + docs/guides/releasing.md. Hybrid versioning — root template (template-v...) + 5 feature packages (auth-v..., blog-v..., etc.) version independently from 0.1.0. release-please reads Conventional Commits and opens a rolling release PR on every push to main; merging cuts per-package tags. Bump targeting is by commit-path, not (scope). Pre-1.0 policy: feat: -> patch, feat!: -> minor.')
+fi
+if echo "$prompt" | grep -qE 'refactor|deepening|shallow|architecture|seam|adapter|interface design|design it twice'; then
+  inject+=('Architecture refactors: invoke the improve-codebase-architecture skill (.claude/skills/improve-codebase-architecture/SKILL.md). Vocabulary: module (= feature by default in this repo) / interface / seam / adapter / depth / leverage / locality. Process: Explore -> Present numbered candidates -> Grilling loop. Hard constraints: respect ADRs 001-021 (factory-function shape, per-feature DI, manifest-first, generator-first, boundary tags, vendor isolation). Companion files: DEEPENING.md (dependency categories), INTERFACE-DESIGN.md (parallel sub-agent design pattern), LANGUAGE.md (vocab + this-repo identifier mapping).')
+fi
+
+if [ ${#inject[@]} -gt 0 ]; then
+  echo "=== context-relevant pointers (from .claude/hooks/prompt-context.sh) ==="
+  printf -- '- %s\n' "${inject[@]}"
+fi
+
+exit 0

.claude/hooks/session-start.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Tier 2 — surfaces a fresh session's "where to look first" pointers.
+# Output on stdout is injected as additional context.
+
+cat <<'EOF'
+=== template-vertical session pointers ===
+Canonical vocabulary: docs/glossary.md  (resolve "what does X mean here?" first)
+Architecture: AGENTS.md, docs/architecture/overview.md, docs/architecture/agent-first-workflow-and-conformance.md
+Workflow: pnpm work status | pnpm work next | pnpm work dispatch (ADR-019)
+Generator-first: pnpm turbo gen <kind> beats hand-rolled scaffolding (non-negotiable)
+Conformance: pnpm conformance + pnpm fallow (5-gate drift detection)
+Conventional Commits (non-negotiable): <type>(<scope>): <subject> — see CLAUDE.md Key Conventions
+Releases: release-please reads commits + opens rolling release PR on merge to main (ADR-021)
+Skills: to-prd, grill-with-docs, grill-me, handoff, improve-codebase-architecture, evaluate-library (.claude/skills/)
+EOF
+
+exit 0

.claude/hooks/stop-check-manifest-tests.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# Tier 3 — when the agent tries to stop, check whether feature.manifest.ts
+# changes have matching test changes. If manifest moved without tests,
+# nudge the agent to continue (exit 2 forces continuation).
+
+set -euo pipefail
+
+input=$(cat)
+
+# Loop guard — Claude Code sets stop_hook_active when a Stop hook already
+# forced continuation; don't loop infinitely.
+already_stopped=$(printf '%s' "$input" | jq -r '.stop_hook_active // false')
+if [ "$already_stopped" = "true" ]; then
+  exit 0
+fi
+
+# Only run inside the repo
+if ! git rev-parse --git-dir >/dev/null 2>&1; then
+  exit 0
+fi
+
+manifest_changed=$(git diff --name-only HEAD 2>/dev/null | grep -E 'feature\.manifest\.ts$' || true)
+
+if [ -z "$manifest_changed" ]; then
+  exit 0
+fi
+
+tests_changed=$(git diff --name-only HEAD 2>/dev/null | grep -E '\.test\.(ts|tsx)$' || true)
+
+if [ -n "$tests_changed" ]; then
+  exit 0
+fi
+
+cat >&2 <<EOF
+[stop-check] Manifest changes detected without matching test changes:
+
+${manifest_changed}
+
+Manifest-first ordering says: contracts + a red test must land before
+implementation. If you already shipped tests in a previous commit on this
+branch (and only the manifest changed this turn), say so and re-stop —
+this hook tracks unstaged + uncommitted-on-HEAD diffs only and can't tell.
+
+Otherwise, write the sibling test file(s) for any new use case before stopping.
+EOF
+
+exit 2

.claude/settings.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/bash-guard.sh"
+          },
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/generator-first-nudge.sh"
+          },
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/library-policy-nudge.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/post-manifest-edit.sh"
+          },
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/library-policy-nudge.sh"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.sh"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/prompt-context.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/stop-check-manifest-tests.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

.claude/skills/evaluate-library/EXAMPLES/approved-example.md

@@ -0,0 +1,91 @@
+---
+package: clsx
+version: "^2.1.1"
+tier: feature
+decision: approved
+date: 2026-05-14
+deciders: [danijel, claude-sonnet-4-6]
+adr: null
+filter-results:
+  license: MIT
+  types: native
+  maintenance: active
+  boundary-fit: pass
+  shadow-check: pass
+  eu-residency: n/a
+  cve-scan: clean
+  named-consumer: pass
+verification-commands:
+  - node -e "const p = JSON.parse(require('fs').readFileSync('./node_modules/clsx/package.json','utf8')); console.log(p.license)"
+  - ls node_modules/clsx/dist/clsx.d.ts
+  - npm view clsx time.modified
+  - pnpm audit --audit-level=moderate
+accepted-cves: []
+---
+
+## Filter: license
+
+<!-- Result: MIT -->
+
+`package.json` declares `"license": "MIT"`. MIT is on the allowlist. Pass.
+
+## Filter: types
+
+<!-- Result: native -->
+
+`clsx` ships its own `.d.ts` declarations at `dist/clsx.d.ts`. No `@types/clsx` package needed.
+The TypeScript surface covers the full public API (`ClassValue`, overloads). Pass.
+
+## Filter: maintenance
+
+<!-- Result: active -->
+
+Last npm release: `2.1.1` published 2024-02-06 (15 months ago at evaluation date — within the 18-month threshold). GitHub shows open PR/issue activity within the last 3 months. The library is small, intentionally stable, and actively maintained. Pass.
+
+## Filter: boundary-fit
+
+<!-- Result: pass -->
+
+`clsx` is a pure string-concatenation utility. It imports nothing from Node.js or browser globals; it has zero transitive dependencies. Adding it to `packages/navigation` as a `feature`-tagged package introduces no boundary violations under ADR-006 or ADR-010. It does not import `@sentry/*`, `@opentelemetry/*`, or any core-reserved vendor SDK. Pass.
+
+## Filter: shadow-check
+
+<!-- Result: pass -->
+
+The locked workspace must-haves are: `zod`, `inversify`, `payload`, `@trpc/server`, `superjson`, `reflect-metadata`. None of these perform CSS class-name composition. There is no existing utility in the workspace for this purpose. Pass.
+
+## Filter: eu-residency
+
+<!-- Result: n/a -->
+
+`clsx` is a pure in-process string utility. It performs no network calls, transmits no user data, and has no SaaS endpoint. EU residency filter does not apply.
+
+## Filter: cve-scan
+
+<!-- Result: clean -->
+
+`pnpm audit --audit-level=moderate` returns 0 vulnerabilities for `clsx@2.1.1` at evaluation time. No accepted advisories.
+
+## Filter: named-consumer
+
+<!-- Result: pass -->
+
+Named consumer: `packages/navigation/src/ui/components/navigation-menu.tsx` — the `NavigationMenuLink` component must compute conditional class names for the active/inactive link state. Without `clsx` this is implemented as a ternary chain that becomes unreadable past three conditions. The component exists today; this is not a hypothetical future use case.
+
+Secondary consumer: `packages/navigation/src/ui/components/mobile-nav.tsx` — open-state drawer overlay class computation. Both components are blocked on this adoption.
+
+## Prompt: replaces
+
+Replaces inline ternary chains like `` `base-class ${isActive ? 'active' : ''} ${isDisabled ? 'disabled' : ''}` ``. No library is being retired — this is a first-time adoption of a class-composition utility. No parallel adoption risk.
+
+## Prompt: migration-cost-out
+
+**Mechanical.** `clsx` is called only at the component leaf level. Removal means replacing `clsx(...)` calls with equivalent template-literal ternaries — a mechanical sed-style refactor bounded to the `packages/navigation/src/ui/` subtree. No data format dependencies, no vendor lock-in, no protocol coupling.
+
+## Prompt: alternatives-considered
+
+1. **`classnames`** — functional equivalent, MIT, widely used. Rejected in favour of `clsx` because `clsx` is the successor written by the same author with better TypeScript support and 2× faster benchmarks at comparable bundle size (330 B vs 440 B minzipped). `classnames` would also pass all eight filters; `clsx` is strictly preferable.
+
+2. **Inline ternary chains (no library)** — the current approach. Adequate for one or two conditions; degrades rapidly past three. The `navigation-menu` component already has four conditional classes; this is the threshold where a utility library pays for itself. Rejected as the status quo.
+
+3. **`tailwind-merge`** — superset of `clsx` that also de-duplicates conflicting Tailwind classes. Overkill for this use case (navigation components use a small, non-conflicting class set). Higher migration cost out (data-format dependency on Tailwind class semantics). Deferred.

.claude/skills/evaluate-library/EXAMPLES/rejected-trpc-to-openapi.md

@@ -0,0 +1,99 @@
+---
+package: trpc-to-openapi
+version: "^1.2.0"
+tier: core
+decision: rejected
+date: 2026-05-14
+deciders: [danijel, claude-sonnet-4-6]
+adr: null
+filter-results:
+  license: MIT
+  types: native
+  maintenance: active
+  boundary-fit: pass
+  shadow-check: pass
+  eu-residency: n/a
+  cve-scan: clean
+  named-consumer: fail
+verification-commands:
+  - npm info trpc-to-openapi license
+  - npm info trpc-to-openapi time.modified
+  - pnpm audit --audit-level=moderate
+accepted-cves: []
+---
+
+## Filter: license
+
+<!-- Result: MIT -->
+
+`package.json` declares `"license": "MIT"`. On the allowlist. Pass.
+
+## Filter: types
+
+<!-- Result: native -->
+
+`trpc-to-openapi` ships TypeScript declarations (`.d.ts`) alongside the compiled output. Full API surface typed. Pass.
+
+## Filter: maintenance
+
+<!-- Result: active -->
+
+Last npm release: `1.2.0` published within the past 12 months at evaluation date. GitHub shows active issue triage. Pass.
+
+## Filter: boundary-fit
+
+<!-- Result: pass -->
+
+`trpc-to-openapi` would land in a `core`-tagged package alongside the tRPC router configuration. Core packages are permitted to hold tRPC-adjacent tooling. The library imports `@trpc/server` (already a workspace must-have) and standard `zod` types. No boundary violations under ADR-006 or ADR-010. Pass.
+
+## Filter: shadow-check
+
+<!-- Result: pass -->
+
+No existing workspace library performs OpenAPI spec generation from tRPC routers. `trpc-to-openapi` does not duplicate any locked must-have. Pass.
+
+## Filter: eu-residency
+
+<!-- Result: n/a -->
+
+`trpc-to-openapi` is a pure in-process code-generation utility. It produces an OpenAPI JSON spec at build time or request time; it transmits nothing to a vendor endpoint. EU residency filter does not apply.
+
+## Filter: cve-scan
+
+<!-- Result: clean -->
+
+`pnpm audit --audit-level=moderate` returns 0 vulnerabilities at evaluation time. Pass.
+
+## Filter: named-consumer
+
+<!-- Result: fail -->
+
+**No named consumer exists.**
+
+The proposal arose during a 2026-05-14 grill session exploring whether to expose the tRPC router surface as a REST API for external consumers. The session established that **all current callers are TypeScript** and use `createCaller` directly — there are no HTTP REST clients calling the API, and no external consumers are blocked waiting for an OpenAPI spec.
+
+The hypothetical consumers cited were:
+
+- "External partners might want a REST API someday" — speculative; no partner is waiting.
+- "A mobile client might prefer REST over tRPC-HTTP" — hypothetical; no mobile client exists.
+- "OpenAPI docs improve DX for third-party integrations" — no third-party integration is in flight.
+
+The grill-session question "who calls this code path today, or who is blocked waiting for it?" had the honest answer: nobody. The library would have shipped approximately 30 lines of `.meta({...})` annotations per router and a `superjson`-incompatible HTTP handler configuration in exchange for zero downstream consumers — pure carrying cost.
+
+This trace exists as a permanent record per ADR-022 §4 so future agents do not re-evaluate `trpc-to-openapi` without first answering whether a named consumer now exists. If a concrete external integration is later planned, re-open this evaluation with the integration as the named consumer, re-run all eight filters, and write a new trace.
+
+## Prompt: replaces
+
+Nothing is being retired. The adoption would have been additive alongside the existing `createCaller` usage path.
+
+## Prompt: migration-cost-out
+
+**Hard.** Once `.meta({...})` annotations are added to tRPC procedures, they accumulate across routers over time. Removal requires stripping those annotations, deleting the OpenAPI spec generation step, and coordinating with any REST consumers that may have formed since adoption. The `superjson`-incompatible HTTP handler creates a parallel request path that would need to be decommissioned. Hard-rated because of the scattered annotation surface.
+
+## Prompt: alternatives-considered
+
+1. **`@anatine/zod-nestjs` + NestJS** — full REST framework alternative; overkill for a tRPC-native repo and would require replacing the tRPC layer entirely. Not a serious alternative for this use case.
+
+2. **Custom OpenAPI spec, hand-authored** — maintain a `openapi.yaml` alongside the tRPC router. Zero runtime cost; no dependency; the spec is always exactly what consumers need. Viable if a named consumer materialises and the schema surface is stable. The correct path when named-consumer passes.
+
+3. **No action (status quo)** — current approach: TypeScript callers use `createCaller`; no REST surface exposed. Correct given that no named consumer exists today. This is the chosen outcome.

.claude/skills/evaluate-library/POLICY.md

@@ -0,0 +1,110 @@
+# Library Evaluation Policy — Quick Reference
+
+> Authoritative source: `docs/decisions/adr-022-library-evaluation-policy.md`
+> Authoritative runbook: `.claude/skills/evaluate-library/SKILL.md`
+
+---
+
+## Why this policy exists
+
+The repo ships with a deliberately narrow runtime surface (six deps per feature package). That discipline is uncodified. Three signals exposed the gap: a near-miss adding `trpc-to-openapi` for hypothetical REST consumers; three ADRs recording library choices _after_ adoption; and no EU-residency gate before a library could silently transmit user data to a US-only SaaS endpoint. ADR-022 codifies the discipline and makes it agent-runnable.
+
+---
+
+## Tier trigger
+
+The policy applies to **direct runtime dependencies** in feature- and core-tier packages. Devdeps and app-tier deps are exempt.
+
+| Where the dep lands        | Process required          | Companion record |
+| -------------------------- | ------------------------- | ---------------- |
+| `apps/<x>`                 | Author's call — no policy | —                |
+| `packages/<feature>`       | Trace required            | —                |
+| `packages/core-*`          | Trace required            | ADR required     |
+| New optional-core category | Trace required            | ADR required     |
+
+The trigger maps onto the existing ESLint `boundaries` tag system (ADR-006, ADR-010) — no new mental model.
+
+---
+
+## Eight hard auto-reject filters
+
+**Phase 1 — cheap (always run to completion)**
+
+| #   | Filter           | Auto-reject condition                                                                                                      |
+| --- | ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **license**      | Outside `MIT`, `Apache-2.0`, `BSD-*`, `ISC`, `MPL-2.0`                                                                     |
+| 2   | **types**        | No `.d.ts` and no `@types/<pkg>`                                                                                           |
+| 3   | **shadow-check** | Functional parallel to a locked must-have (`zod`, `inversify`, `payload`, `@trpc/server`, `superjson`, `reflect-metadata`) |
+| 4   | **boundary-fit** | Dep would violate ESLint boundary rules for the target tier (e.g., `@sentry/node` in a feature package — ADR-017 §4)       |
+
+**Phase 2 — expensive (short-circuit after first reject)**
+
+| #   | Filter             | Auto-reject condition                                                                                                  |
+| --- | ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| 5   | **maintenance**    | Last release ≥ 18 months OR activity gap ≥ 12 months (`abandoned`)                                                     |
+| 6   | **cve-scan**       | Open advisory at `moderate` severity or above (via `pnpm audit`)                                                       |
+| 7   | **eu-residency**   | Library transmits user data/telemetry to a vendor endpoint with no EU data region available or not configured          |
+| 8   | **named-consumer** | No concrete call site exists today and no feature is blocked waiting for it — hypothetical future use does not qualify |
+
+A single failure in any filter → `decision: rejected`. Cheap filters always run; expensive filters stop at the first fail.
+
+---
+
+## Three discussion prompts
+
+Not auto-reject filters — any answer is acceptable with justification. Required in every trace.
+
+1. **replaces** — What existing approach does this replace? Parallel adoption of the same capability is a smell.
+2. **migration-cost-out** — Rate the removal cost 18 months from now: mechanical / hard / impossible.
+3. **alternatives-considered** — Two named alternatives minimum. For core-tier, also duplicated into the companion ADR.
+
+---
+
+## Trace artifact
+
+Every decision — approved or rejected — produces a file at `docs/library-decisions/<YYYY-MM-DD>-<package-name>.md`.
+
+**Required frontmatter fields:**
+
+| Field                           | Values                                     |
+| ------------------------------- | ------------------------------------------ |
+| `package`                       | npm package name                           |
+| `version`                       | semver range                               |
+| `tier`                          | `app` \| `feature` \| `core`               |
+| `decision`                      | `approved` \| `rejected`                   |
+| `date`                          | `YYYY-MM-DD`                               |
+| `deciders`                      | list of authors (human and/or agent)       |
+| `adr`                           | `adr-NNN` or `null`                        |
+| `filter-results.license`        | SPDX id                                    |
+| `filter-results.types`          | `native` \| `@types/<x>` \| `none`         |
+| `filter-results.maintenance`    | `active` \| `dormant` \| `abandoned`       |
+| `filter-results.boundary-fit`   | `pass` \| `fail`                           |
+| `filter-results.shadow-check`   | `pass` \| `fail` \| `"shadows <x>"`        |
+| `filter-results.eu-residency`   | `ok` \| `n/a` \| `self-hostable` \| `fail` |
+| `filter-results.cve-scan`       | `clean` \| advisory ID \| `fail`           |
+| `filter-results.named-consumer` | `pass` \| `fail`                           |
+| `verification-commands`         | list of literal commands run               |
+| `accepted-cves`                 | list of accepted advisory IDs (optional)   |
+
+Skipped expensive filters (short-circuited by an earlier reject) → write `skip` as the frontmatter value and note "Not evaluated" in the prose section.
+
+The trace lands in **the same commit** as the `package.json` change. The pre-commit hook validates this for approved traces.
+
+---
+
+## Four-layer enforcement stack
+
+| Layer                                                       | Latency    | Catches                                                           |
+| ----------------------------------------------------------- | ---------- | ----------------------------------------------------------------- |
+| Claude `PreToolUse`/`PostToolUse` hook                      | inline     | Agent skipping the skill before `pnpm add` or `package.json` edit |
+| `/evaluate-library` skill                                   | seconds    | The decision itself + writes the trace                            |
+| Git pre-commit hook (`scripts/library-decisions/check.mjs`) | pre-commit | Humans or agents bypassing the skill                              |
+| Sandcastle reviewer prompt                                  | per-slice  | Bypasses that slipped past pre-commit                             |
+
+The Claude hook injects a `<system-reminder>` pointing to this skill. It is non-blocking — devdep additions and app-tier changes trigger the reminder but do not require a trace. The pre-commit hook is the deterministic gate.
+
+---
+
+## Composition with generators
+
+`pnpm turbo gen core-package <name>` emits **pre-shipped traces** — one per direct runtime dep of the new core package — pre-marked `decision: approved` and citing the relevant ADR (ADR-015 for events, ADR-016 for realtime, ADR-018 for audit). No separate evaluation needed for scaffolded optional cores.

.claude/skills/evaluate-library/SKILL.md

@@ -0,0 +1,308 @@
+---
+name: evaluate-library
+description: Walk the 9-filter + 3-prompt library evaluation protocol for a named package, write the decision trace to docs/library-decisions/, and return pass/fail. Use when adding a runtime dependency to a feature or core package, or when the library-policy-nudge hook fires.
+---
+
+<invocation>
+
+```
+/evaluate-library <package-name> --tier <feature|core|app> --target <package-path>
+```
+
+All three arguments are required. The `library-policy-nudge` hook emits this exact invocation. For `app`-tier packages, evaluation still runs but a trace is optional (author's call per ADR-022 §1).
+
+</invocation>
+
+<runbook>
+
+## Overview
+
+Walk nine hard auto-reject filters in **collect-cheap-skip-expensive** order, then answer three discussion prompts. Write the trace unconditionally at the end — including for rejections. A rejection trace is a permanent record that prevents future agents from re-litigating the same decision.
+
+## Phase 1 — Cheap filters (always run to completion, even if one fails)
+
+Run all four cheap filters regardless of their outcomes. Record each result before moving to Phase 2.
+
+### Filter 1: license
+
+Command: `node -e "const p = JSON.parse(require('fs').readFileSync('./node_modules/<pkg>/package.json','utf8')); console.log(p.license)"`
+
+Allowlist: `MIT`, `Apache-2.0`, `BSD-2-Clause`, `BSD-3-Clause`, `ISC`, `MPL-2.0`.
+
+Result values: the SPDX identifier (e.g. `MIT`) if allowed, or `<SPDX-id> (rejected)` if outside the allowlist. Anything outside the allowlist is an automatic reject but does not stop Phase 1.
+
+### Filter 2: types
+
+Check whether TypeScript types ship with the package or via `@types/<pkg>`:
+
+```
+ls node_modules/<pkg>/index.d.ts 2>/dev/null && echo native || npm info @types/<pkg> version 2>/dev/null | head -1
+```
+
+Result values: `native` (ships its own `.d.ts`), `@types/<pkg>` (community types available), or `none` (auto-reject — un-typed library shifts maintenance cost to the feature).
+
+### Filter 3: shadow-check
+
+Check whether this library duplicates a must-have already locked in the workspace. Locked must-haves: `zod` (validation), `inversify` (DI, ADR-002), `payload` (CMS), `@trpc/server` (API layer), `superjson` (serialisation), `reflect-metadata` (DI metadata).
+
+Command: `cat package.json | grep -E '"(zod|inversify|payload|@trpc/server|superjson|reflect-metadata)"'` — run from the workspace root.
+
+Result values: `pass` (no shadow), `fail` (exact duplicate of a locked dep), `"shadows <x>"` (functional parallel that would create two libraries doing the same job — auto-reject). A replacement must be a separate ADR with consequences analysis, not a parallel adoption.
+
+### Filter 4: boundary-fit
+
+Confirm the dependency does not violate ESLint boundary-tag rules for the target tier (ADR-006, ADR-010, ADR-017).
+
+Key rules:
+
+- Feature packages cannot import `@sentry/*` or `@opentelemetry/sdk-*` directly — those are reserved for core (ADR-017 §4).
+- No package may import across feature boundaries without going through the event bus or tRPC.
+- Optional core packages can only be imported by apps and `core-composition`-tagged packages.
+
+Check by reviewing what the proposed library's transitive imports would bring in and whether any violate the boundary ruleset.
+
+Result values: `pass` or `fail`.
+
+---
+
+After Phase 1: tally results. If **any cheap filter failed**, the overall decision is `rejected`. Proceed to Phase 2 anyway — all expensive filters still run if the Phase 1 decision is already rejected (they inform the full record). If all cheap filters passed, proceed to Phase 2 to determine the final decision.
+
+## Phase 2 — Expensive filters (short-circuit after first reject)
+
+Run in order. On the first failure, set remaining filter results to `skip` and skip to the [Trace write step](#trace-write-step).
+
+### Filter 5: maintenance
+
+Check last release date and recent PR/issue activity:
+
+```
+npm info <pkg> time.modified
+npm info <pkg> time | tail -5
+```
+
+Result values:
+
+- `active` — last release < 18 months **and** PR/issue activity < 12 months
+- `dormant` — stable, not actively developed (acceptable for finished libraries like `reflect-metadata`)
+- `abandoned` — last release ≥ 18 months **or** no activity in ≥ 12 months → auto-reject; short-circuit remaining expensive filters
+
+On `abandoned` → set `cve-scan`, `eu-residency`, `named-consumer`, `socketRisk` to `skip` → write trace.
+
+### Filter 6: cve-scan
+
+```
+pnpm audit --audit-level=moderate 2>&1 | head -40
+```
+
+Result values: `clean` (no advisories), an advisory ID like `GHSA-xxxx-xxxx-xxxx` (accepted risk — document in `accepted-cves` frontmatter), or `fail` (open advisory not accepted → auto-reject; short-circuit remaining expensive filters).
+
+On `fail` → set `eu-residency`, `named-consumer`, `socketRisk` to `skip` → write trace.
+
+### Filter 7: eu-residency
+
+Applies only if the library transmits user data, telemetry, business state, or secrets to a vendor-controlled endpoint by default. Examples: analytics SDKs, error-tracking clients, AI APIs, log aggregation services.
+
+Exemptions (result: `n/a`): pure in-process libraries (no network calls), self-hostable software where the operator controls the endpoint, and build-time-only tools.
+
+For non-exempt libraries: verify the vendor offers an EU data region AND that the integration in `target` is configured to use it.
+
+Result values: `ok` (vendor offers EU region, integration configured), `n/a` (no data transmission), `self-hostable` (operator-controlled endpoint), `fail` → auto-reject; short-circuit `named-consumer`.
+
+On `fail` → set `named-consumer`, `socketRisk` to `skip` → write trace.
+
+### Filter 8: named-consumer
+
+Answer: **Who calls this code path today, or who is blocked waiting for it?**
+
+A named consumer is a concrete call site that exists now or a feature blocked on this capability today. "We might want this later", "external clients could use this", and "it would be nice to have" are not named consumers.
+
+If the only possible callers are hypothetical or future → `fail` → set `socketRisk` to `skip` → auto-reject.
+
+Result value: `pass` or `fail`.
+
+### Filter 9: supply-chain behavior (Socket)
+
+**Expensive — network call. Run last in Phase 2. Short-circuit: if any earlier Phase 2 filter already rejected the library, set `socketRisk` to `skip` and proceed to the [Trace write step](#trace-write-step).**
+
+Verify the package's supply-chain health via `socket-cli`:
+
+```
+npx socket-cli@latest scan . --json 2>&1
+```
+
+This scans the current directory's lockfile for packages installed from the target under evaluation. For a targeted single-package check before installing:
+
+```
+npx socket-cli@latest info <pkg>@<version> --json 2>&1
+```
+
+The JSON output contains an array of findings, each with a `severity` field. Cross-reference with the repo-root `.socket.json` `issueRules` to determine the classification:
+
+| Finding severity                    | `.socket.json` rule | `socketRisk` value  |
+| ----------------------------------- | ------------------- | ------------------- |
+| No findings, or only `medium`/`low` | `ignore`            | `clean`             |
+| `high`-severity finding present     | `warn`              | `flagged`           |
+| `critical`-severity finding present | `error`             | `<finding-summary>` |
+
+Where `<finding-summary>` is a concise label for the critical finding (e.g. `"new-author-on-publish"`, `"install-scripts-added"`, `"exfiltrates-env"`).
+
+Set `filter-results.socketRisk` in the trace frontmatter to one of these three values.
+
+Result values:
+
+- `clean` — no meaningful supply-chain signals; proceed to Phase 3 prompts.
+- `flagged` — `high`-severity finding; document the specific signal in the trace body and decide whether to accept with justification. Not an auto-reject.
+- `<finding-summary>` — `critical`-severity finding; auto-reject. This is the last filter — no further filters to skip.
+
+---
+
+## Skip sentinel
+
+When a filter is short-circuited (not evaluated), write `skip` for its frontmatter value. The Zod schema validates approved traces end-to-end; rejected/partial traces may carry `skip` in fields that would normally require an enum value. The pre-commit check only validates that approved traces exist for new deps — partial traces are informational records.
+
+## Three discussion prompts
+
+Answer all three in the trace, regardless of filter outcome. These are not auto-reject filters; any answer is acceptable with justification.
+
+### Prompt: replaces
+
+What existing library or approach does this replace? New-and-old running in parallel is a smell — name the thing being retired and the retirement plan, or explain why parallel adoption is intentional and time-bounded.
+
+### Prompt: migration-cost-out
+
+What does ripping this back out look like 18 months from now? Rate: **mechanical** (swap one package, update call sites), **hard** (scattered integration points, data-format dependencies), or **impossible** (vendor lock-in, protocol coupling). Higher cost raises the bar for adoption.
+
+### Prompt: alternatives-considered
+
+Name at least two alternatives evaluated before choosing this library. For `core`-tier adoptions, this section is also duplicated into the companion ADR. If no alternatives exist, explain why (e.g., the library is the de-facto standard with no viable substitutes).
+
+---
+
+## Sub-processor classification
+
+Answer these two questions before writing the trace. The answers become
+top-level frontmatter fields required by ADR-022 §9.
+
+### Question: is-sub-processor
+
+**Does the vendor receive personal data on the operator's behalf?**
+
+A library is a sub-processor when it transmits personal data (user identifiers,
+email addresses, behavioural events, request bodies, etc.) to a vendor-controlled
+endpoint — analytics SDKs, error-tracking clients, AI APIs, log aggregation
+services. Network calls alone do not make a library a sub-processor; only calls
+that carry personal data do.
+
+Pure in-process libraries (no network calls), self-hostable software where the
+operator controls the endpoint, and build-time-only tools are **not** sub-processors.
+
+Set `is-sub-processor: true | false`.
+
+### Question: processes-pii
+
+**Does the library process personal data in-process, even without transmitting
+it to a vendor?**
+
+A library processes PII if it reads, validates, serialises, stores, or
+transforms data fields that may contain personal information (names, emails,
+IDs, content authored by users, authentication credentials). A self-hosted
+database or CMS is a prime example: no data leaves to a vendor, yet the
+library clearly handles PII.
+
+Pure utility libraries (DI containers, type validators, serialisers operating
+on already-typed objects without inspecting field semantics, test runners)
+typically answer `false`.
+
+Set `processes-pii: true | false`.
+
+### Conditional block: when is-sub-processor is true
+
+When `is-sub-processor: true`, five additional fields are **required** in the
+trace frontmatter. Gather them before writing the trace:
+
+```
+data-sent: "<what personal data the library transmits to the vendor>"
+region: "<vendor data region, e.g. eu-west-1 or eu>"
+dpa-signed: true | false     # has the operator signed a DPA with this vendor?
+sccs-required: true | false  # does the vendor require SCCs (non-EEA transfer)?
+contact: "<vendor DPO or privacy contact email/URL>"
+```
+
+If the vendor does not yet have a signed DPA or if you cannot determine the
+region, record `dpa-signed: false` / region as best-known and add a prose note
+under `## Sub-processor` in the trace body explaining the gap.
+
+---
+
+## Trace write step
+
+Write the trace **unconditionally** at evaluation end — even for rejections, even for partial traces.
+
+**Path:** `docs/library-decisions/<YYYY-MM-DD>-<package-name>.md`
+
+Use today's date. Use `docs/library-decisions/_template.md` as the structural guide.
+
+Frontmatter rules:
+
+- `decision: approved` only if all eight filters passed. Otherwise `decision: rejected`.
+- `adr: null` for feature-tier. For core-tier approvals, coordinate the ADR slug before writing (`adr: adr-NNN`).
+- `verification-commands` — include the literal commands run for each filter, one per line.
+- `accepted-cves: []` (empty unless you accepted a specific advisory).
+- `is-sub-processor` and `processes-pii` are **always required** (see Sub-processor classification above).
+- When `is-sub-processor: true`, include `data-sent`, `region`, `dpa-signed`, `sccs-required`, and `contact`.
+- For skipped expensive filters, write `skip` for the frontmatter value and omit the prose section body or note "Not evaluated — skipped due to earlier rejection."
+
+Frontmatter template:
+
+```yaml
+---
+package: <name>
+version: "<semver range>"
+tier: app | feature | core
+decision: approved | rejected
+date: <YYYY-MM-DD>
+deciders: [<author>, ...]
+adr: adr-NNN | null
+lastRevalidated: null
+is-sub-processor: false
+processes-pii: false
+# include the block below only when is-sub-processor: true
+# data-sent: "<description>"
+# region: "<eu | eu-west-1 | ...>"
+# dpa-signed: false
+# sccs-required: false
+# contact: "<url or email>"
+filter-results:
+  license: <SPDX id>
+  types: native | "@types/<x>" | none
+  maintenance: active | dormant | abandoned
+  boundary-fit: pass | fail
+  shadow-check: pass | fail | "shadows <x>"
+  eu-residency: ok | n/a | self-hostable | fail
+  cve-scan: clean | "<advisory-id>" | fail
+  named-consumer: pass | fail
+  socketRisk: clean | flagged | <arbitrary-string>
+verification-commands:
+  - <literal command that produced each filter result>
+accepted-cves: []
+---
+```
+
+After writing the trace:
+
+- For approved traces: confirm the trace is staged in the same commit as the `package.json` change. The pre-commit hook validates this.
+- For rejected traces: stage the trace file alone. Do not run `pnpm add <pkg>`.
+
+</runbook>
+
+<output-format>
+
+After completing the evaluation, emit a one-paragraph summary:
+
+```
+/evaluate-library result: <approved|rejected> — <package>@<version> (<tier>)
+Rejection filters (if any): <filter names>
+Trace written to: docs/library-decisions/<date>-<package>.md
+```
+
+</output-format>

.claude/skills/evaluate-library/TRACE-TEMPLATE.md

@@ -0,0 +1,167 @@
+# Trace Template
+
+Use this file as the structural guide when writing a library decision trace. Copy the frontmatter block and all 11 headings. Replace placeholder values with real results.
+
+Trace path: `docs/library-decisions/<YYYY-MM-DD>-<package-name>.md`
+
+---
+
+## Frontmatter — all filters evaluated
+
+```markdown
+---
+package: <npm-package-name>
+version: "<semver range>"
+tier: app | feature | core
+decision: approved | rejected
+date: <YYYY-MM-DD>
+deciders: [<author>, ...]
+adr: adr-NNN | null
+filter-results:
+  license: <SPDX id>
+  types: native | "@types/<x>" | none
+  maintenance: active | dormant | abandoned
+  boundary-fit: pass | fail
+  shadow-check: pass | fail | "shadows <x>"
+  eu-residency: ok | n/a | self-hostable | fail
+  cve-scan: clean | "<advisory-id>" | fail
+  named-consumer: pass | fail
+  socketRisk: clean | flagged | <finding-summary>
+verification-commands:
+  - <literal command that produced the license result>
+  - <literal command that confirmed types>
+  - <literal command that checked maintenance>
+  - <literal command that ran the CVE scan>
+accepted-cves: []
+---
+```
+
+## Frontmatter — partial trace (expensive filters short-circuited)
+
+When an expensive filter fails (Phase 2 short-circuit), set remaining filter fields to `skip`. The Zod schema validates approved traces end-to-end; `skip` is the accepted sentinel for unevaluated fields in rejected traces.
+
+Example: `maintenance: abandoned` → `cve-scan`, `eu-residency`, `named-consumer` skipped.
+
+```markdown
+---
+package: <npm-package-name>
+version: "<semver range>"
+tier: feature | core
+decision: rejected
+date: <YYYY-MM-DD>
+deciders: [<author>, ...]
+adr: null
+filter-results:
+  license: MIT
+  types: native
+  maintenance: abandoned
+  boundary-fit: pass
+  shadow-check: pass
+  eu-residency: skip
+  cve-scan: skip
+  named-consumer: skip
+  socketRisk: skip
+verification-commands:
+  - npm view <pkg> time.modified
+accepted-cves: []
+---
+```
+
+---
+
+## Required headings (11 total, in this order)
+
+### Filter sections (8)
+
+```markdown
+## Filter: license
+
+<!-- Result: <SPDX id> -->
+
+Record the SPDX identifier from `package.json` or `npx license-checker --packages <pkg>`.
+Allowed: MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, MPL-2.0.
+Anything else → auto-reject (note the identifier and rejection reason).
+
+## Filter: types
+
+<!-- Result: native | @types/<x> | none -->
+
+Confirm TypeScript types are available. `native` = ships its own `.d.ts`; `@types/<x>` = community
+types package exists and is current; `none` = no types → auto-reject.
+
+## Filter: maintenance
+
+<!-- Result: active | dormant | abandoned -->
+
+Check last release date and recent PR/issue activity. `active` = last release < 18 months AND
+activity < 12 months. `dormant` = stable but not actively developed (acceptable for finished
+libraries). `abandoned` = auto-reject.
+If skipped (earlier expensive filter failed), write: "Not evaluated — skipped due to <filter> rejection."
+
+## Filter: boundary-fit
+
+<!-- Result: pass | fail -->
+
+Confirm the dependency does not violate ESLint boundary-tag rules for the target tier
+(ADR-006, ADR-010, ADR-017). Name the specific rule checked and the result.
+
+## Filter: shadow-check
+
+<!-- Result: pass | fail | "shadows <x>" -->
+
+Check whether this library duplicates a must-have already locked in the workspace.
+Locked must-haves: zod, inversify, payload, @trpc/server, superjson, reflect-metadata.
+`shadows <x>` → auto-reject; a replacement requires a dedicated ADR.
+
+## Filter: eu-residency
+
+<!-- Result: ok | n/a | self-hostable | fail | skip -->
+
+If the library transmits user data, telemetry, or business state to a vendor-controlled
+endpoint by default, the vendor must offer an EU data region and the integration must be
+configured to use it. Pure in-process libraries and build-time tools → `n/a`.
+If skipped, write: "Not evaluated — skipped due to <filter> rejection."
+
+## Filter: cve-scan
+
+<!-- Result: clean | "<advisory-id>" | fail | skip -->
+
+Run `pnpm audit --audit-level=moderate`. `clean` = no advisories at adoption time. Record
+accepted advisory IDs in the `accepted-cves` frontmatter field and explain the risk acceptance
+here. If skipped, write: "Not evaluated — skipped due to <filter> rejection."
+
+## Filter: named-consumer
+
+<!-- Result: pass | fail | skip -->
+
+Answer: "Who calls this code path today, or who is blocked waiting for it?"
+Hypothetical future callers are not consumers (ADR-022 §2.8 — the direct response to the
+2026-05-14 OpenAPI near-miss). If skipped, write: "Not evaluated — skipped due to <filter> rejection."
+```
+
+### Prompt sections (3)
+
+```markdown
+## Prompt: replaces
+
+<!-- Required: answer in either direction with justification -->
+
+What existing library or approach does this replace? New-and-old running in parallel is a smell.
+Name the thing being retired and its retirement plan, or explain why parallel adoption is
+intentional and time-bounded.
+
+## Prompt: migration-cost-out
+
+<!-- Required: mechanical | hard | impossible + justification -->
+
+What does ripping this back out look like 18 months from now? Rate: mechanical (swap package,
+update call sites), hard (scattered integration, data-format dependencies), or impossible
+(vendor lock-in, protocol coupling). Higher migration cost raises the adoption bar.
+
+## Prompt: alternatives-considered
+
+<!-- Required: minimum two named alternatives, or "none with explanation" -->
+
+Name at least two alternatives evaluated before choosing this library. For core-tier adoptions,
+this section is also duplicated into the companion ADR. If no alternatives exist, explain why.
+```

.claude/skills/grill-me/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: grill-me
+description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when the user wants to stress-test a plan, get grilled, or mentions "grill me". Use grill-with-docs instead when the plan should cross-check against ADRs + glossary + manifests.
+---
+
+Interview the user relentlessly about every aspect of this plan until you reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions **one at a time**, waiting for feedback before continuing.
+
+If a question can be answered by exploring the codebase, explore the codebase instead. Useful shortcuts in this repo:
+
+- `pnpm work status` — current epics and ready stories
+- `cat packages/<feature>/src/feature.manifest.ts` — declared use cases / events / audits
+- `ls docs/decisions/` — ADRs by number
+- `pnpm fallow` — dead exports, dupes, complexity hotspots
+- grep manifests across all features: `grep -r "publishes:" packages/*/src/feature.manifest.ts`
+
+When grilling pulls in ADR / glossary / manifest cross-checks and you want to update those docs inline, switch to `grill-with-docs` instead.

.claude/skills/grill-with-docs/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: grill-with-docs
+description: Stress-test a plan against this repo's domain glossary, ADRs, conformance rules, and feature manifests. Update docs/glossary.md inline as terms crystallize; offer ADRs sparingly. Use when the user wants to harden a plan before it becomes a PRD.
+---
+
+<what-to-do>
+
+Interview the user relentlessly about every aspect of this plan until you reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions **one at a time**, waiting for feedback on each before continuing.
+
+If a question can be answered by exploring the codebase, explore the codebase instead of asking. The repo has fast feedback loops — run `pnpm work status`, grep manifests, read feature `feature.manifest.ts`, check ADRs. Speculation is a last resort.
+
+</what-to-do>
+
+<supporting-info>
+
+## Repo doc map
+
+This repo uses a **single context** with these doc locations:
+
+```
+/
+├── docs/
+│   ├── glossary.md                 ← lazy-create when first term resolves
+│   ├── decisions/                  ← ADRs (adr-NNN-<slug>.md, 3-digit zero-pad)
+│   │   ├── adr-001-monorepo-tool.md
+│   │   ├── adr-018-audit-and-compliance.md
+│   │   └── ...
+│   ├── architecture/               ← long-form specs + workflow design
+│   ├── work/                       ← PRDs, epics, stories, tasks
+│   └── guides/                     ← how-to runbooks
+└── packages/<feature>/src/feature.manifest.ts   ← per-feature contract
+```
+
+There is **no `CONTEXT.md` or `CONTEXT-MAP.md`** — this repo uses `docs/glossary.md` (create lazily) plus the per-feature `feature.manifest.ts` files for machine-readable domain shape. Don't create the multi-context layout (`CONTEXT-MAP.md`) unless this becomes a polyrepo.
+
+## During the session
+
+### Challenge against the glossary + manifests
+
+When the user introduces a term that conflicts with `docs/glossary.md` (if it exists) or with a `feature.manifest.ts` entry, call it out immediately:
+
+> "Your glossary defines `cancellation` as the act of voiding an unsent invoice, but you seem to mean the user-initiated subscription teardown — which is it?"
+
+> "`auth.signIn` exists in `packages/auth/src/feature.manifest.ts` with that exact slug — are you adding a new use case or extending the existing one?"
+
+### Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term:
+
+> "You're saying `account` — do you mean a `User` (entity in `packages/auth`) or a Payload-collection record? Those are distinct."
+
+### Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent edge cases that force precision about boundaries between concepts. Lean on the existing feature set — auth, blog, media, marketing-pages, navigation — for grounding examples.
+
+### Cross-reference with code
+
+When the user states how something works, verify it against the code. Look at:
+
+- The feature's `feature.manifest.ts` for declared use cases, audits, publishes, consumes
+- `packages/<feature>/src/application/use-cases/` for the actual shape
+- `packages/<feature>/src/di/bind-production.ts` for what's wired
+- `docs/decisions/adr-NNN-*.md` for the decision history
+
+If you find a contradiction, surface it:
+
+> "You said cross-feature reactions happen through the bus, but `packages/auth/src/feature.manifest.ts` shows `publishes: []` — has this been wired yet?"
+
+### Cross-reference with ADRs
+
+Before recommending an approach, scan `docs/decisions/` for relevant ADRs. If your recommendation contradicts a current-status ADR, surface that explicitly:
+
+> "You're proposing direct cross-feature imports, but `adr-006-vertical-feature-packages.md` plus rule R20 in the ESLint config forbid that — events (`core-events`) are the sanctioned path. Want to use events, or do you want to reopen the ADR?"
+
+### Cross-reference with conformance rules
+
+The conformance system (`docs/architecture/agent-first-workflow-and-conformance.md`) defines hard contracts:
+
+- Every use case has a manifest entry → contracts → tests → impl (in that order)
+- TS brands (`Instrumented`, `Captured`, `Audited`) attached at DI bind time
+- ESLint rules enforce manifest ↔ code alignment
+- `pnpm conformance` enforces cross-feature event closure
+
+If the plan would violate any of these, flag it.
+
+### Update `docs/glossary.md` inline
+
+When a term is resolved during the conversation, append it to `docs/glossary.md` right then — don't batch. Lazy-create the file when the first term is resolved. Use the format in [glossary-format.md](./glossary-format.md).
+
+Only include terms meaningful to **this repo's domain** (template / monorepo / agent-first workflow / clean architecture / vertical features). Skip general programming concepts. Skip implementation details — those belong in code or ADRs.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
+3. **Result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If any is missing, skip the ADR. The repo's ADRs follow a long-form `Context → Decision → Alternatives considered → Consequences → Related` shape (see `docs/decisions/adr-015-events-and-jobs.md` for a representative example). Number is next-highest in `docs/decisions/` zero-padded to 3 digits (`adr-020-...`, `adr-021-...`).
+
+If the grill produced a major refactor decision rather than a new feature, lead the user to an ADR; if it produced a feature plan, lead to a PRD via `to-prd`.
+
+</supporting-info>

.claude/skills/grill-with-docs/glossary-format.md

@@ -0,0 +1,62 @@
+# docs/glossary.md Format
+
+## Structure
+
+```md
+# Glossary
+
+Domain vocabulary for `template-vertical`. Terms specific to this repo — clean architecture, vertical features, agent workflow, conformance. General programming concepts don't belong here; implementation details belong in code or ADRs.
+
+## Architecture
+
+**Feature**:
+A vertical slice owning its Clean Architecture layers (entities → application → infrastructure → DI → integrations).
+_Avoid_: module, domain, app.
+
+**Use case**:
+A single business action exposed by a feature, implemented as a factory `(deps) => async (input) => output`. Each one has a manifest entry, a Zod input/output schema pair, a colocated test, and a controller.
+_Avoid_: command, action, handler.
+
+**Manifest**:
+The `feature.manifest.ts` file that declares a feature's use cases, audits, publishes, consumes, and required core packages. Source of truth for conformance gates.
+
+**Conformance**:
+The 5-gate enforcement system (TS brands → ESLint → boot assertion → `pnpm conformance` → fallow) that keeps manifest and code aligned.
+
+## Workflow
+
+**PRD**:
+The top-level requirements doc at `docs/work/prds/<date>-<slug>.prd.md` that seeds an epic.
+
+**Epic**:
+A large body of work containing stories. Folder at `docs/work/epics/<epic-slug>/_epic.md`.
+
+**Story**:
+One use case or technical capability. Folder under the epic, file `_story.md`.
+
+**Task**:
+One vertical slice = one PR = one commit. File `<slug>.task.md` under the story folder.
+
+## Relationships
+
+- A **PRD** decomposes into one or more **Epics**
+- An **Epic** contains one or more **Stories**
+- A **Story** is implemented by one or more **Tasks**
+- A **Use case** is declared in a **Manifest** before it has code
+- **Conformance** asserts that the **Manifest** and the code agree
+
+## Flagged ambiguities
+
+- (none yet — append here when conflicts are resolved during grilling)
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid.
+- **Flag conflicts explicitly.** When grilling surfaces ambiguity, capture both meanings under "Flagged ambiguities" with the resolution.
+- **Keep definitions tight.** One sentence max. Define what it IS, not what it does.
+- **Show relationships.** Use bold term names; express cardinality where obvious.
+- **Only domain terms specific to this repo.** General programming concepts (timeouts, retries, errors, DI) don't belong even if used heavily. Before adding, ask: is this concept unique to template-vertical, or generic?
+- **Group under subheadings** when natural clusters emerge (Architecture, Workflow, Instrumentation, etc.).
+
+This repo is **single-context**: one `docs/glossary.md`, no `CONTEXT-MAP.md`. Don't switch to multi-context layout unless the repo splits.

.claude/skills/handoff/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: handoff
+description: Compact the current conversation into a handoff document for another agent to pick up. Use when the user wants to transition work to a fresh session, switch worktrees, or hand off to a subagent.
+argument-hint: "What will the next session be used for?"
+---
+
+Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save it to a path produced by `mktemp -t handoff-XXXXXX.md` (read the file before you write to it).
+
+Suggest the skills the next session should use, if any. In this repo, the common follow-ups are:
+
+- `grill-with-docs` — stress-test the plan before coding
+- `to-prd` — materialize the plan into `docs/work/prds/<date>-<slug>.prd.md`
+- `superpowers:writing-plans` — author the implementation plan
+- `superpowers:subagent-driven-development` — dispatch implementer + reviewer subagents per task
+
+## Don't duplicate
+
+Reference these artifacts by path or URL rather than inlining their content:
+
+- PRDs (`docs/work/prds/*.prd.md`), epics (`docs/work/epics/<epic>/_epic.md`), stories (`_story.md`), tasks (`*.task.md`)
+- ADRs (`docs/decisions/adr-NNN-*.md`)
+- AGENTS.md and CLAUDE.md (the next agent loads these automatically)
+- `_state.json` (orchestrator-derived; the next agent regenerates it from markdown via `pnpm work rebuild-state`)
+- Commit messages, diffs, PR descriptions — link the SHA / PR number
+- Existing plans under `docs/superpowers/plans/`
+
+## Do capture
+
+- The active **goal** in one sentence
+- **In-flight branch / worktree** and any uncommitted state (e.g. `git status` summary, dangling commits)
+- **Decisions made in conversation** that haven't yet landed in a PRD or ADR
+- **Blockers** and proposed next steps
+- **Skills to invoke first** in the next session
+- If the user passed arguments, treat them as the next session's focus and tailor the doc accordingly
+
+Keep the document short — it's a baton, not a thesis.

.claude/skills/improve-codebase-architecture/DEEPENING.md

@@ -0,0 +1,98 @@
+# Deepening
+
+How to deepen a cluster of shallow modules in this repo, given its dependencies. **In this repo "module" defaults to "feature"** — most deepenings operate on or within a feature (`packages/<name>/`). Narrower scopes (use case, controller, repository) follow the same dependency-category logic. Assumes the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**.
+
+## Dependency categories
+
+When assessing a candidate for deepening, classify its dependencies. The category determines how the deepened module is tested across its seam.
+
+### 1. In-process
+
+Pure computation, in-memory state, no I/O. Always deepenable — merge the modules and test through the new interface directly. No adapter needed.
+
+**Where this lives in our repo:**
+
+- `entities/models/**` — Zod schemas + types + pure helpers
+- `entities/errors/**` — domain error classes
+- `application/use-cases/**` — pure orchestration (factories take ports as deps)
+- `interface-adapters/controllers/**` + their colocated `presenter` functions
+- Pure helpers in `core-shared/conformance/`, `core-shared/instrumentation/` (the non-OTel parts)
+
+For category 1 modules: **merge, then test the result through its interface**. No mocks. The test surface IS the new interface.
+
+### 2. Local-substitutable
+
+Dependencies that have local test stand-ins. **In this repo every infrastructure port already has both a real implementation and a mock side-by-side** — the mock IS the test stand-in.
+
+**Pattern (from ADR-012):**
+
+- `<x>.repository.interface.ts` — the port (seam)
+- `<x>.repository.ts` — Payload-backed adapter (real)
+- `<x>.repository.mock.ts` — in-memory adapter (test stand-in)
+
+The deepened module is tested with the `.mock.ts` adapter injected directly via the factory function. No container rebinding (ADR-012).
+
+**Common category-2 ports in this repo:**
+
+- `IUsersRepository`, `IArticlesRepository`, `IMediaRepository`, etc. → Mock + Payload adapters
+- `IAuthenticationService` → Mock + real adapter
+- `IJobQueue` (from `core-shared/jobs/`) → `InMemoryJobQueue` + `PayloadJobQueue`
+- `IEventBus` (from `core-events/`) → `InMemoryEventBus` + `PayloadJobsEventBus`
+- `ITracer`, `ILogger`, `IMetrics` (from `core-shared/instrumentation/`) → `Noop*` + `Otel*` + `Recording*` (the third one lives in `core-testing` for assertions)
+
+If the deepening touches a category-2 port, the recommendation shape is: _"Merge X into Y, keep the port boundary at the existing `<x>.repository.interface.ts`; both adapters survive unchanged."_
+
+### 3. Remote but owned
+
+Our own services across a network boundary. **In this repo, cross-feature communication is already this pattern via the event bus (ADR-015).**
+
+The **port** is `IEventBus.publish(descriptor, payload)` + `IEventBus.subscribe(descriptor, consumerFeature, handler)`. Adapters:
+
+- `InMemoryEventBus` (test + dev-seed) — synchronous fan-out
+- `PayloadJobsEventBus` (production) — Payload tasks fan-out durably across the network if features are split into separate deploys
+
+If a deepening proposal would introduce a NEW cross-feature seam, the answer is almost always "use the event bus" — don't invent a new transport. Rule E0 forbids in-feature use of the bus (in-feature reactions are direct use-case calls); E1 keeps consumer handlers private.
+
+If the deepening proposal would EXPOSE one feature's internals to another, that's a boundary violation — reject and suggest events instead.
+
+### 4. True external
+
+Third-party services we don't control. The deepened module takes the external dependency as an injected port; tests provide a mock adapter.
+
+**Where this lives in our repo:**
+
+- Payload CMS itself — features depend on `IXRepository`, not on `payload` directly. The real adapter (`<x>.repository.ts`) is the only place Payload is touched.
+- Sentry / OpenTelemetry exporters — features use `ITracer`/`ILogger`/`IMetrics` from `core-shared/instrumentation/`. The OTel SDK lives ONLY in `core-shared/instrumentation/otel/` (ESLint-enforced via rule R52).
+- Socket.IO — features use `IRealtimeBroadcaster`; `socket.io` itself lives only in `@repo/core-realtime` (rule R2).
+
+If a deepening proposal would import a vendor SDK from a feature package, that's an ADR-014/ADR-016/ADR-017 violation — reject and route through the existing port.
+
+## Seam discipline
+
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a port unless at least two adapters are justified (typically production + test). Single-adapter ports in this repo are usually a smell — check if the mock is missing or if the port itself is unnecessary.
+- **Internal seams vs external seams.** A deep module can have internal seams (private to its implementation, used by its own tests) as well as the external seam at its interface. Don't expose internal seams through the interface just because tests use them.
+- **The DI symbol is the seam contract.** `*_SYMBOLS.IXRepository` plus `<x>.repository.interface.ts` together define what callers depend on. Adapter swaps happen at bind time in `bind-production.ts` / `bind-dev-seed.ts`.
+- **`feature.manifest.ts` is the structural-conformance seam.** If a deepening moves use cases across features, the manifests of BOTH features change — the conformance ESLint rules + `assertFeatureConformance` boot check enforce that the move is reflected in declarations, not just code.
+
+## Testing strategy: replace, don't layer
+
+- **Old unit tests on shallow modules become waste** once tests at the deepened module's interface exist — delete them. Our coverage thresholds (ADR-020) reward this: collapsing N shallow modules + their N test files into one deep module + one test file at its interface keeps coverage 100% without test bloat.
+- **Write new tests at the deepened module's interface.** The **interface is the test surface**.
+- **Tests assert on observable outcomes through the interface**, not internal state.
+- **Tests should survive internal refactors** — if a test has to change when the implementation changes, it's testing past the interface.
+- **L1 diff coverage (`pnpm coverage:diff`) will surface uncovered lines after the refactor** — every deepened module needs its new tests to cover the merged behaviour before the refactor PR is mergeable.
+
+## Conformance check (run before claiming the deepening is complete)
+
+After deepening, the following must all stay green:
+
+```
+pnpm typecheck                         # TS brand-slot enforcement
+pnpm lint                              # ESLint conformance + boundaries
+pnpm test --filter @repo/<feature> -- --coverage   # per-layer L0 thresholds
+pnpm conformance                       # cross-feature event closure
+pnpm fallow:audit                      # whole-codebase audit + dead-export sweep
+pnpm coverage:diff -- --base origin/main   # cover-the-diff (ADR-020 L1)
+```
+
+If `pnpm dev` was running, it should still boot — `assertFeatureConformance` will fail loudly on brand-slot or manifest drift if the deepening forgot a binding update.

.claude/skills/improve-codebase-architecture/INTERFACE-DESIGN.md

@@ -0,0 +1,66 @@
+# Interface Design
+
+When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best.
+
+Uses the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module** (= **feature** by default in this repo), **interface**, **seam**, **adapter**, **leverage**.
+
+## Process
+
+### 1. Frame the problem space
+
+Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
+
+- The constraints any new interface would need to satisfy
+- The dependencies it would rely on, and which category they fall into (see [DEEPENING.md](DEEPENING.md))
+- The **hard constraints from SKILL.md** that the new interface must respect (factory-function shape, per-feature DI, manifest-first, generator-first, brand wrappers, etc.)
+- A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete
+
+Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel.
+
+### 2. Spawn sub-agents
+
+Spawn 3+ sub-agents in parallel using the `Agent` tool (`subagent_type=general-purpose` or a more specific type if appropriate). Each must produce a **radically different** interface for the deepened module.
+
+Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:
+
+- **Agent 1**: "Minimise the interface — aim for 1–3 entry points max. Maximise leverage per entry point."
+- **Agent 2**: "Maximise flexibility — support many use cases and extension."
+- **Agent 3**: "Optimise for the most common caller — make the default case trivial."
+- **Agent 4 (if applicable)**: "Design around ports & adapters for cross-seam dependencies."
+
+**Every brief MUST also include:**
+
+- This repo's vocabulary from [`docs/glossary.md`](../../../docs/glossary.md) (use case, manifest, feature, slice, etc.)
+- The architecture vocabulary from [LANGUAGE.md](LANGUAGE.md)
+- The hard constraints from [SKILL.md](SKILL.md) — sub-agents must not propose interfaces that violate ADR-006 (boundaries), ADR-008 (per-feature DI), ADR-012 (factory shape, one controller per use case), ADR-013 (schemas in use-case file), ADR-014/017 (vendor isolation), ADR-015 (events for cross-feature), ADR-020 (manifest-driven coverage bands), or ADR-021 (versioning by commit-path).
+- The relevant feature `feature.manifest.ts` shape so the proposed interface aligns with manifest-first ordering.
+
+Each sub-agent outputs:
+
+1. **Interface** (types, methods, params — plus invariants, ordering, error modes, schemas if applicable)
+2. **Usage example** showing how callers in this repo would use it (use real file paths and real existing feature names)
+3. **What the implementation hides** behind the seam
+4. **Dependency strategy and adapters** (see [DEEPENING.md](DEEPENING.md)) — which existing ports/adapters get reused, which (if any) are new
+5. **Manifest + binder impact** — which `feature.manifest.ts` entries and which `bind-production.ts` / `bind-dev-seed.ts` files change
+6. **Trade-offs** — where leverage is high, where it's thin
+7. **ADR conflicts (if any)** — call out by ADR number with rationale, or state "none"
+
+### 3. Present and compare
+
+Present designs sequentially so the user can absorb each one, then compare them in prose. Contrast by:
+
+- **Depth** (leverage at the interface)
+- **Locality** (where change concentrates)
+- **Seam placement** (which existing `*.interface.ts` survives, which gets replaced, which is new)
+- **Conformance impact** (how many manifests change, how many binders change, how many tests rewrite)
+- **Coverage delta** (cumulative L0 band impact — does any layer drop below its declared 100% / 95%?)
+
+After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not a menu.
+
+If the chosen design crosses a feature-package boundary (e.g. moves a use case from `@repo/blog` to `@repo/media`), state explicitly:
+
+- Which `feature.manifest.ts` files lose / gain entries
+- Which package versions will bump on the next release-please PR (per ADR-021 commit-path bump targeting)
+- Whether the migration needs an intermediate compatibility seam to keep `pnpm conformance` green during the transition
+
+The implementation lands via the manifest-first ordering: (1) update the manifests in both packages, (2) write the new contracts in the use-case file, (3) write the failing tests, (4) implement until green. Don't skip the order even when the move feels mechanical.

.claude/skills/improve-codebase-architecture/LANGUAGE.md

@@ -0,0 +1,78 @@
+# Language
+
+Shared vocabulary for every suggestion this skill makes. Use these terms exactly — don't substitute "component," "service" (we use that narrowly for DI ports), "API," or "boundary" (overloaded with our workspace-tag enforcement). Consistent language is the whole point.
+
+This vocabulary is foundational for the skill's reasoning. The project's domain vocabulary lives in [`docs/glossary.md`](../../../docs/glossary.md) — terms like _use case_, _manifest_, _slice_, _binder_, _brand_, _conformance band_, _coverage layer_. Both vocabularies are in scope when proposing deepenings; see the "Mapping to this repo's identifiers" section below for how the abstract terms here land on concrete file shapes.
+
+## Terms
+
+**Module** — **in this repo, "module" defaults to "feature"** (`packages/<name>/`). The abstract definition (anything with an interface + implementation) still applies at narrower scales — a use case, controller, repository/service port, or binder can also be a module — but **whenever the refactor scope is "the whole thing", say feature**. Reach for "module" only when the abstraction across scales actually matters (e.g., comparing how a use case's depth differs from its containing feature's depth).
+_Avoid_: unit, component, service (we use "service" for DI ports specifically).
+
+**Interface**
+Everything a caller must know to use the module correctly. Includes the type signature, but also invariants, ordering constraints, error modes, required configuration, performance characteristics, **manifest declarations**, and **DI symbol contract**.
+_Avoid_: API, signature (too narrow — those refer only to the type-level surface).
+
+**Implementation**
+What's inside a module — its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Payload-backed repository) or a large adapter with a small implementation (an in-memory mock). Reach for "adapter" when the seam is the topic; "implementation" otherwise.
+
+**Depth**
+Leverage at the interface — the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface. A module is **shallow** when the interface is nearly as complex as the implementation.
+
+**Seam** _(from Michael Feathers)_
+A place where you can alter behaviour without editing in that place. The _location_ at which a module's interface lives. Choosing where to put the seam is its own design decision, distinct from what goes behind it.
+_Avoid_: boundary (this repo uses "boundary" specifically for ESLint workspace-tag rules — keep it for that meaning).
+
+**Adapter**
+A concrete thing that satisfies an interface at a seam. Describes _role_ (what slot it fills), not substance (what's inside). In this repo every port typically has at least two adapters (real + mock); some have three (real + mock + recording).
+
+**Leverage**
+What callers get from depth. More capability per unit of interface they have to learn. One implementation pays back across N call sites and M tests.
+
+**Locality**
+What maintainers get from depth. Change, bugs, knowledge, and verification concentrate at one place rather than spreading across callers. Fix once, fixed everywhere.
+
+## Principles
+
+- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface.
+- **The deletion test.** Imagine deleting the module. If complexity vanishes, the module wasn't hiding anything (it was a pass-through). If complexity reappears across N callers, the module was earning its keep.
+- **The interface is the test surface.** Callers and tests cross the same seam. If you want to test _past_ the interface, the module is probably the wrong shape.
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it. In this repo, the typical justification is "one real adapter + one mock for tests" — that's two.
+- **The manifest is a structural seam.** A feature's `feature.manifest.ts` declares its use cases / events / jobs / channels / required cores / coverage bands. Refactors that move behaviour between features MUST move manifest entries too; the conformance gates enforce this.
+
+## Relationships
+
+- A **Module** has exactly one **Interface** (the surface it presents to callers and tests).
+- **Depth** is a property of a **Module**, measured against its **Interface**.
+- A **Seam** is where a **Module**'s **Interface** lives.
+- An **Adapter** sits at a **Seam** and satisfies the **Interface**.
+- **Depth** produces **Leverage** for callers and **Locality** for maintainers.
+
+## Mapping to this repo's identifiers
+
+Abstract → concrete translation table. When proposing a deepening, name things using the right column.
+
+| Abstract term      | Where it lands in this repo                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Module**         | **Primarily a feature** (`packages/<name>/`) — that's the canonical refactor scope. Also: a use case (`*.use-case.ts`), controller (`*.controller.ts`), repository port + adapters (`*.repository.{interface,mock,}.ts`), service port + adapters (`*.service.{interface,mock,}.ts`), binder (`bind-production.ts` / `bind-dev-seed.ts`), manifest (`feature.manifest.ts`), or a core package (`packages/core-<name>/`) — when the refactor operates at those narrower scales. When in doubt, say "feature". |
+| **Interface**      | The exported types from a module file: `IXUseCase = ReturnType<typeof xUseCase>`, `IXController`, the `<x>.repository.interface.ts` shape, the manifest's declared keys, the Zod input/output schemas, the DI symbol contract.                                                                                                                                                                                                                                                                               |
+| **Implementation** | The factory body, the adapter class body, what the binder wires.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| **Seam**           | `<x>.repository.interface.ts`, `<x>.service.interface.ts`, the DI symbol (`*_SYMBOLS.IXRepository`), the manifest entry, a `// <gen:*>` anchor, the protocol types in `core-shared/di/bind-protocols.ts`.                                                                                                                                                                                                                                                                                                    |
+| **Adapter**        | `<x>.repository.ts` (Payload real) ↔ `<x>.repository.mock.ts` (in-memory). For instrumentation: `Noop*` ↔ `Otel*` ↔ `Recording*` (test). For bus: `InMemoryEventBus` ↔ `PayloadJobsEventBus`.                                                                                                                                                                                                                                                                                                                |
+| **Test stand-in**  | The `.mock.ts` adapter (constructed directly + injected into the factory). No container rebinding (ADR-012).                                                                                                                                                                                                                                                                                                                                                                                                 |
+
+## Rejected framings
+
+- **Depth as ratio of implementation-lines to interface-lines** (Ousterhout's original metric): rewards padding the implementation. We use depth-as-leverage instead.
+- **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know, including manifest entries and DI symbols.
+- **"Boundary"** as a synonym for **seam**: this repo uses "boundary" specifically for ESLint workspace-tag rules (`feature` may depend on `core` + `tooling` only). Keep that meaning intact; say **seam** or **interface** when discussing features.
+- **"Service" as a generic term**: in this repo, **service** = a DI-injected port for non-collection capabilities (`IAuthenticationService`, `IMailerService`). Not a generic stand-in for "feature" or "the module doing the work."
+- **"Module" as the canonical noun**: avoid in everyday discourse — say **feature** (or **use case** / **controller** / **package** when narrower). "Module" is the abstract refactor vocabulary's word for the same thing, useful only when the abstraction across scales is the point.
+
+## Cross-references
+
+- [`docs/glossary.md`](../../../docs/glossary.md) — project domain vocabulary (use case, manifest, slice, brand, coverage band, etc.)
+- [`docs/decisions/`](../../../docs/decisions/) — 21 ADRs that constrain the design space
+- [SKILL.md](SKILL.md) — the skill's process + hard constraints
+- [DEEPENING.md](DEEPENING.md) — dependency categories + seam discipline
+- [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md) — parallel sub-agent design exploration

.claude/skills/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: improve-codebase-architecture
+description: Find deepening opportunities in this repo, informed by docs/glossary.md and the ADRs in docs/decisions/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make the codebase more testable and AI-navigable. Respects the conformance system, boundary rules, and the 21 ADRs that govern shape.
+---
+
+# Improve Codebase Architecture
+
+Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability, scoped to what this template's existing rules permit.
+
+## Glossary
+
+Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service" (we use that for DI ports specifically), or "boundary" (we use that for ESLint workspace-tag rules). Full definitions in [LANGUAGE.md](LANGUAGE.md).
+
+- **Module** — **in this repo defaults to "feature"** (`packages/<name>/`). The abstract definition (anything with interface + implementation) still applies at narrower scales — a use case, controller, repository/service port, binder, or core package can also be a module — but say "feature" whenever that's the scope. Reach for "module" only when comparing depth/leverage across scales.
+- **Interface** — everything a caller must know to use the module: types, invariants, error modes, ordering, schemas, DI shape. Not just the TypeScript type signature.
+- **Implementation** — the code inside.
+- **Depth** — leverage at the interface: a lot of behaviour behind a small interface. **Deep** = high leverage. **Shallow** = interface nearly as complex as the implementation.
+- **Seam** — where an interface lives; a place behaviour can be altered without editing in place. In this repo seams take a concrete shape: `*.interface.ts` files, DI symbols, manifest declarations, and `<gen:*>` anchors.
+- **Adapter** — a concrete thing satisfying an interface at a seam. In this repo: `<x>.repository.ts` (Payload real impl) vs `<x>.repository.mock.ts` vs `Recording*` test doubles.
+- **Leverage** — what callers get from depth.
+- **Locality** — what maintainers get from depth: change, bugs, knowledge concentrated in one place.
+
+Key principles (see [LANGUAGE.md](LANGUAGE.md) for the full list):
+
+- **Deletion test**: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
+- **The interface is the test surface.**
+- **One adapter = hypothetical seam. Two adapters = real seam.**
+
+This skill is **informed by** the project's domain model and architecture decisions. Read [`docs/glossary.md`](../../../docs/glossary.md) for project vocabulary and the relevant ADR(s) in [`docs/decisions/`](../../../docs/decisions/) before proposing anything in their territory.
+
+## Hard constraints (do not propose violations)
+
+These are settled decisions — propose deepening WITHIN them, never against them:
+
+- **Factory-function use cases & controllers** (ADR-012, ADR-013) — every use case is `(deps) => async (input) => output`; every controller is one verb-noun pair per file with a co-located `presenter`.
+- **Schemas in the use-case file** (ADR-013) — `xInputSchema`/`xOutputSchema` colocate with the factory; don't propose moving them to a separate module.
+- **Per-feature DI containers** (ADR-008) — don't propose a single global container.
+- **Five boundary tags + the dependency-direction matrix** (ADR-006, ADR-010) — features may depend only on `core` + `tooling`; cross-feature reactions go through `IEventBus` (ADR-015).
+- **Manifest-first ordering** (ADR-012, ADR-020) — new use cases land manifest → contracts → tests → impl; don't propose collapsing the steps.
+- **Brand-based conformance** — `Instrumented` / `Captured` / `Audited` are attached at DI bind time via `withSpan` / `withCapture` / `withAudit`; don't propose moving the wrapping elsewhere.
+- **Generator-first** — `pnpm turbo gen <kind>` is the entry point for new features/events/jobs/realtime channels. Don't propose hand-rolled scaffolding.
+- **Conventional Commits** (CLAUDE.md Key Conventions) — any refactor lands as conventional-commit messages.
+- **Hybrid versioning** (ADR-021) — refactors that move code between feature packages have version + CHANGELOG implications.
+
+If a proposed deepening **would** violate an ADR, surface it explicitly with the ADR number and a "worth reopening because…" justification — but only if the friction is real enough. Most should be silently scoped out.
+
+## Process
+
+### 1. Explore
+
+Read [`docs/glossary.md`](../../../docs/glossary.md) and any ADRs in the area you're touching first. Then walk the codebase noting friction. The primary unit of attention is the **feature** (`packages/<name>/`); narrower units (use cases, controllers, repositories) get attention when the friction lives at that scale.
+
+- Where does understanding one concept require bouncing between many small files across `entities/`, `application/`, `infrastructure/`, `interface-adapters/` inside a single feature?
+- Where is a feature **shallow** — its public surface (the `.` + `./ui` + `./api` exports) nearly as complex as its internal implementation? Or where inside a feature is a smaller unit shallow:
+  - A `service.interface.ts` with one method that wraps a single repository call.
+  - A `presenter` that's just `(x) => x`.
+  - A controller body that's just `useCase(parsed.data)` with no transformation.
+  - A repository wrapping another repository.
+  - A use case wrapping another use case.
+- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
+- Where do tightly-coupled features leak across their seams? (e.g. a feature reaches into another feature's internals via deep import — though ESLint should catch this.)
+- Which parts are untested, or hard to test through their current interface? `pnpm coverage:diff` and `pnpm fallow` surface candidates.
+
+Useful exploration shortcuts in this repo:
+
+- `pnpm fallow` — dead exports, dupes, complexity hotspots, circular deps
+- `pnpm fallow:audit` — the AI-change audit; surfaces drift across recent edits
+- `git log --oneline --follow -- <path>` — change frequency is a depth signal
+- `cat packages/<feature>/src/feature.manifest.ts` — declared surface of a feature
+- `pnpm turbo boundaries` — workspace dependency graph
+
+Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
+
+### 2. Present candidates
+
+Present a numbered list of deepening opportunities. For each candidate:
+
+- **Files** — which files / features / smaller units are involved (give exact paths)
+- **Problem** — why the current architecture is causing friction
+- **Solution** — plain English description of what would change
+- **Benefits** — explained in terms of **locality** and **leverage**, plus how tests would improve
+- **ADR impact** — any ADR this touches. If the proposed change conflicts with a current ADR, mark it explicitly: _"contradicts ADR-NNN — worth reopening because…"_ (only when the friction warrants it).
+- **Manifest impact** — if the change moves use cases / events / jobs / channels across features, the `feature.manifest.ts` of each feature involved will need an update; flag this so the user knows the conformance gates will require manifest edits before code edits (manifest-first ordering).
+
+**Use [`docs/glossary.md`](../../../docs/glossary.md) vocabulary for the domain (use case, manifest, slice, feature, etc.) and [LANGUAGE.md](LANGUAGE.md) vocabulary for the architecture (module, seam, adapter, depth, leverage, locality).**
+
+Do NOT propose interfaces yet. Ask the user: "Which of these would you like to explore?"
+
+### 3. Grilling loop
+
+Once the user picks a candidate, drop into a grilling conversation. Walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
+
+Side effects happen inline as decisions crystallize:
+
+- **Naming a deepened module after a concept not in [`docs/glossary.md`](../../../docs/glossary.md)?** Add the term to the glossary right there — same discipline as the `grill-with-docs` skill. Pick the appropriate section (Packages / Architecture layers / Feature building blocks / Conformance / Cross-feature / Instrumentation / Workflow / Releasing).
+- **Sharpening a fuzzy term during the conversation?** Update the glossary inline.
+- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as ADR-NNN so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future agent to avoid re-suggesting the same thing. The next ADR number is `001 + max(existing)` (currently `ADR-022`). Our ADR shape: `Context → Decision → Alternatives considered → Consequences → Related`.
+- **Refactor will move code between feature packages?** Flag the release-please impact: both affected packages will bump versions on the next release PR.
+- **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md).
+
+## Related skills
+
+- `grill-with-docs` (`.claude/skills/grill-with-docs/`) — stress-tests plans against ADRs + glossary + manifests; share the same glossary-update discipline.
+- `to-prd` — if the deepening is large enough to merit a multi-task epic, materialize it as a PRD.

.claude/skills/to-prd/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: to-prd
+description: Turn the current conversation context into a PRD and write it to docs/work/prds/. Use when the user wants to materialize the discussion into a draft PRD that feeds the pnpm work pipeline.
+---
+
+This skill takes the current conversation context and codebase understanding and produces a PRD. Do NOT interview the user — just synthesize what you already know. If you need to interview first, invoke `grill-with-docs` instead.
+
+The PRD lives on the filesystem (this repo does not use an issue tracker for work). The downstream pipeline is `pnpm work decompose` → epic + stories → tasks → sandcastle dispatch (see `docs/architecture/agent-first-workflow-and-conformance.md`).
+
+## Process
+
+1. **Explore the repo if you haven't already.** Use the project's domain vocabulary throughout (check `docs/glossary.md` if it exists, otherwise lift terms from `docs/architecture/vertical-feature-spec.md` §6 and the feature packages' `feature.manifest.ts`). Respect any ADRs in the area you're touching — they're at `docs/decisions/adr-NNN-<slug>.md`. Use `pnpm work status` to see in-flight epics.
+
+2. **Sketch the major modules / packages.** Identify which existing packages (`packages/<feature>/`, `packages/core-*/`) you'll modify and which new ones — if any — you'll create. Actively look for **deep modules**: small interface, deep implementation, rarely-changing surface. The vertical-feature-package shape (entities → application → infrastructure → DI) is the default unit; resist scaffolding new core packages unless required.
+
+   Check with the user that this module sketch matches their expectations. Confirm which modules they want tests written for. (The conformance system already mandates tests for every use case + controller; this question is about extra coverage — repository contract suites, integration tests, etc.)
+
+3. **Pick a slug** for the PRD filename: `docs/work/prds/<kebab-slug>.prd.md`. No date prefix in the slug — the `created:` timestamp in frontmatter carries the date. Future task-tracker IDs (e.g. ClickUp) will land as `<task-id>-<kebab-slug>` once that integration ships; until then, bare slug only.
+
+4. **Write the PRD using the template below**, then save it. Status starts at `draft`. The decomposer (`pnpm work decompose`) refuses to run on `draft` PRDs — the human flips it to `approved` after review.
+
+<prd-template>
+
+```markdown
+---
+id: <kebab-slug>
+title: <Human-readable title>
+type: prd
+status: draft
+author: <user>
+elicitation-session: <agent-session-id-or-omit>
+created: <ISO-8601-UTC-timestamp, e.g. 2026-05-14T19:23:45Z>
+---
+
+## Problem
+
+What's broken or missing today? Who hurts because of it? Frame it from the user's perspective (where "user" may be a developer using the template, an end-user of an app built on it, or an AI agent operating in the codebase).
+
+## Goal
+
+What state are we trying to reach? One or two sentences.
+
+## In scope
+
+- Bullets of what this PRD covers.
+
+## Out of scope
+
+- Bullets of what's explicitly excluded. The explicit no-s are as valuable as the yes-s.
+
+## Constraints
+
+- Non-negotiables: existing ADRs to respect, conformance rules, performance budgets, compliance requirements, etc.
+- Reference ADRs by ID: `ADR-014`, `ADR-017`, etc.
+
+## Success criteria
+
+- Verifiable outcomes. "Feature X passes `pnpm typecheck && pnpm test && pnpm conformance` green" is concrete; "feature X is great" is not.
+
+## User stories
+
+A numbered list. Cover all aspects of the feature, including edge cases.
+
+1. As a `<actor>`, I want `<capability>`, so that `<benefit>`.
+2. ...
+
+## Implementation decisions
+
+Decisions captured here so the decomposer (and downstream agents) don't re-litigate them. Include:
+
+- Modules to be built / modified (by package or feature name — no file paths; those rot fast)
+- Interface shapes (Zod schemas, TypeScript types, tRPC procedures) — describe in prose; inline only if a snippet encodes the decision more precisely than prose (e.g., a Zod schema, a discriminated union, a state machine)
+- Architectural choices (DI factory shape, withSpan/withCapture wrapping, manifest entries, anchor placements)
+- Schema changes (Payload collections, database migrations)
+- Cross-feature interactions (event publish/consume pairs, realtime channels, audit emissions)
+- Optional-core requirements (does this feature require `core-events`? `core-realtime`? `core-audit`?)
+
+Do NOT include specific file paths or full code snippets — they go stale quickly. Prefer prose plus inline contracts (schemas, types) where they tighten the decision.
+
+## Testing decisions
+
+- What "good test" means for this feature (behavior through public interfaces, not implementation details)
+- Which modules get repository contract suites (any new `IXRepository`)
+- Which modules get use-case unit tests (every use case — that's a conformance rule)
+- Integration / e2e coverage: which apps, which Playwright specs
+- Prior art in the codebase: pointers to similar test patterns to mirror
+
+## Open questions
+
+- Q1: `<question>` — `<recommended answer>`
+- Q2: ...
+
+## Out of scope (deferred)
+
+Things that are tempting to include but should be a separate PRD.
+
+## Further notes
+
+Anything else: stakeholders, related PRDs (`Builds on <prd-id>`, `Supersedes <prd-id>`), external references.
+```
+
+</prd-template>
+
+## After writing
+
+- Verify the file lives at `docs/work/prds/<slug>.prd.md`.
+- Tell the user the path and remind them to review and flip `status: draft → approved` before running `pnpm work decompose`.
+- If new domain terms were introduced or sharpened during synthesis, append them to `docs/glossary.md` (lazy-create if missing) — same rules as `grill-with-docs`.

.claude/skills/work-decompose/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: work-decompose
+description: Use when an approved PRD must be broken into an epic with story and task files under docs/work/. Triggers — the user asks to decompose a PRD, invokes /work-decompose, or wants a PRD turned into the work tree.
+---
+
+# work-decompose
+
+Decompose an `approved` PRD into an epic + story files under `docs/work/epics/`, by dispatching a **decomposer sub-agent** whose role is defined by the existing Sandcastle prompt.
+
+This is the in-session, skill form of `pnpm work decompose --execute`. It adds a path; it changes nothing about `.sandcastle/` or `pnpm work`.
+
+## Single source of truth — do not copy the prompt
+
+The decomposer's role is defined in **`.sandcastle/decomposer.prompt.md`** — the same file `pnpm work decompose --execute` consumes. This skill **reads that file at dispatch time and passes it verbatim**. Never paraphrase, summarise, or inline it here. If this skill and the prompt ever disagree, **the prompt wins** — fix this skill, not the prompt.
+
+## Process
+
+1. **Resolve the PRD.** The user names a PRD (slug or path); otherwise list `docs/work/prds/*.prd.md` and ask which. Read the file.
+
+2. **Refuse drafts.** If the PRD's frontmatter `status:` is not `approved`, **stop** — tell the user to flip it after review. The decomposer refuses drafts; catch it early.
+
+3. **Build the prompt.** Read `.sandcastle/decomposer.prompt.md`. Substitute its `{{PRD_FILE_CONTENT}}` placeholder with the full PRD file contents.
+
+4. **Dispatch the decomposer sub-agent.** Use the Agent tool, `general-purpose`. Its instructions are the substituted prompt, followed by this environment-adaptation note (the note adapts the environment — it is not a prompt edit):
+
+   > **Environment:** you are a Claude Code sub-agent, not running inside Sandcastle. Ignore the `<promise>COMPLETE</promise>` marker instruction — there is no iteration loop; just return your final summary. Write the epic + story files to `docs/work/epics/`. **Do not commit** — leave the files for the human to review and commit, per your own "offer them a chance to review + edit" step.
+
+5. **Report.** Relay the epic folder path the sub-agent created. Remind the user to review/edit the stories, then commit, and that `pnpm work rebuild-state` (or the pre-commit hook) refreshes `_state.json`. The next step in the pipeline is `/work-dispatch`.
+
+## Why a sub-agent
+
+Decomposition is a self-contained, read-heavy job — the whole PRD, the slice-rule reasoning, the file-writing. Running it in a sub-agent keeps all of that out of the main session; you get back only the epic path.
+
+## Quick reference
+
+|                   |                                                                    |
+| ----------------- | ------------------------------------------------------------------ |
+| Input             | an `approved` PRD in `docs/work/prds/`                             |
+| Role prompt       | `.sandcastle/decomposer.prompt.md` — read, never copied            |
+| Sub-agent         | one `general-purpose` agent                                        |
+| Output            | `docs/work/epics/<epic-id>/` — `_epic.md` + `NN-<story>/_story.md` |
+| Upstream          | `to-prd` / `grill-with-docs` produce the PRD                       |
+| Downstream        | `/work-dispatch` runs the tasks                                    |
+| Sandcastle parity | mirrors `pnpm work decompose --execute`                            |
+
+## Common mistakes
+
+- **Copying the prompt into this skill.** `.sandcastle/decomposer.prompt.md` is the source of truth — read it at dispatch time, every time.
+- **Decomposing a `draft` PRD.** Check `status: approved` first.
+- **Letting the sub-agent commit.** It writes files; the human reviews and commits.

.claude/skills/work-dispatch/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: work-dispatch
+description: Use when a task in the docs/work/ tree should be implemented and reviewed. Triggers — the user asks to dispatch a task, run the next task, run the implement-review loop, or invokes /work-dispatch.
+---
+
+# work-dispatch
+
+Run one work-tree task through the **implement → review loop**, using two separate sub-agents whose roles are defined by the existing Sandcastle prompts.
+
+This is the in-session, skill form of `pnpm work dispatch --execute`. It adds a path; it changes nothing about `.sandcastle/` or `pnpm work`.
+
+## Single source of truth — do not copy the prompts
+
+Two role definitions, two files, read at dispatch time — **never copied**:
+
+- implementer role → **`.sandcastle/implementer.prompt.md`**
+- reviewer role → **`.sandcastle/reviewer.prompt.md`**
+
+`pnpm work dispatch --execute` (Sandcastle) and this skill consume the **same** files. Never paraphrase or inline them. If a prompt and this skill disagree, **the prompt wins**. This skill is only the _wiring_: pick the task, substitute placeholders, dispatch the sub-agents, run the loop.
+
+## Separate sub-agents — non-negotiable
+
+The implementer and the reviewer are **distinct sub-agents**, dispatched separately:
+
+- The **implementer** writes code. Dispatch a `general-purpose` Agent with `isolation: "worktree"` — it works on an isolated git worktree + branch, so bad output never touches your main tree.
+- The **reviewer** must be a _different_ agent and must _not_ write. Dispatch an `Explore` Agent (read-only by construction) — it cannot Edit/Write the repo even by accident; it only verifies the diff.
+
+Never collapse the two into one agent. An agent that writes code and then grades its own work has not been reviewed.
+
+## Process
+
+1. **Resolve the task.** Default: run `pnpm work next`, then read the first unchecked task file of that story (`docs/work/epics/<epic>/<story>/NN-<slug>.task.md`). Or the user names a task id. Read the task file; note its `max-attempts` frontmatter (default 3).
+
+2. **Dispatch the implementer.** Read `.sandcastle/implementer.prompt.md`, substitute `{{TASK_FILE_CONTENT}}` with the task file. Dispatch a `general-purpose` Agent with `isolation: "worktree"`; instructions = the substituted prompt + this environment-adaptation note:
+
+   > **Environment:** a Claude Code sub-agent in a fresh, isolated git worktree — NOT a Sandcastle Docker sandbox. Run `pnpm install` as your first step (the worktree has no `node_modules`). Commit your slice on a branch. **Report that branch name** in the `notes` field of your output JSON. Ignore the `<promise>COMPLETE</promise>` marker — there is no iteration loop; just return the structured JSON as your final message.
+
+   Read the returned JSON: `status`, `commit_sha`, `files_changed`, `notes` (which carries the branch name).
+
+3. **Handle the implementer's status.** `complete` → step 4. `blocked` or `needs-clarification` → surface the `notes` to the user and stop; do not proceed to review.
+
+4. **Compute the diff.** `git diff main...<task-branch>` from the main tree — git worktrees share `.git`, so the implementer's branch is visible.
+
+5. **Dispatch the reviewer.** Read `.sandcastle/reviewer.prompt.md`, substitute `{{TASK_FILE_CONTENT}}` and `{{DIFF}}`. Dispatch an `Explore` Agent (read-only); instructions = the substituted prompt + this environment-adaptation note:
+
+   > **Environment:** a Claude Code sub-agent reviewing a LOCAL branch — there is no pull request or CI run yet. Where the prompt says to trust Sandcastle's CI step: the implementer has already run and reported the five conformance gates + coverage as its commit precondition — verify AC coverage, out-of-scope discipline, and slice discipline by **reading the diff**, as your checks describe. Run the library-trace check directly (`node scripts/library-decisions/check.mjs`). The Socket and CodeQL steps require a CI run — note them as "deferred to CI", do not block on them. Ignore the `<promise>COMPLETE</promise>` marker; return the JSON decision.
+
+   Read the returned JSON: `decision`, `scope_violations`, `notes`.
+
+6. **Run the loop.**
+   - **`approve`** → merge `<task-branch>` into `main`; remove the worktree. Then run `pnpm typecheck && pnpm lint && pnpm test && pnpm conformance` once on `main` as a post-merge safety check. Print the suggested task-checkbox / `_state.json` mutation for the user to apply — **do not write state yourself.**
+   - **`reject`** → re-dispatch the implementer (step 2) with the reviewer's `notes` appended to its instructions. Repeat until `approve`, or until the task's `max-attempts` is reached — then stop and surface the last reviewer notes.
+
+## Why this shape
+
+State mutation stays manual (the skill suggests, the human applies) — exactly as Sandcastle's v1 orchestrator does, and consistent with the implementer prompt's "the orchestrator handles state writes." Worktree isolation gives the implementer a clean room without Docker. The read-only reviewer makes "the reviewer does not modify the repo" a property of the tool, not a promise.
+
+## Quick reference
+
+|                   |                                                                                       |
+| ----------------- | ------------------------------------------------------------------------------------- |
+| Implementer       | `.sandcastle/implementer.prompt.md` · `general-purpose` · `isolation: "worktree"`     |
+| Reviewer          | `.sandcastle/reviewer.prompt.md` · `Explore` (read-only)                              |
+| Placeholders      | implementer: `{{TASK_FILE_CONTENT}}` · reviewer: `{{TASK_FILE_CONTENT}}` + `{{DIFF}}` |
+| Loop cap          | the task's `max-attempts` frontmatter (default 3)                                     |
+| State writes      | suggested to the user, never applied by the skill                                     |
+| Upstream          | `/work-decompose` produces the tasks                                                  |
+| Sandcastle parity | mirrors `pnpm work dispatch --execute`                                                |
+
+## Common mistakes
+
+- **Copying a prompt into this skill.** The `.sandcastle/*.prompt.md` files are the source of truth — read them at dispatch time.
+- **One agent for both roles.** Implementer and reviewer are separate sub-agents; the reviewer is `Explore` (read-only).
+- **Writing `_state.json` or ticking the checkbox.** The skill prints the suggested mutation; the human applies it.
+- **Skipping the environment-adaptation note.** Without it the sub-agent follows Sandcastle-only instructions — the `<promise>` marker, "trust CI" — that do not apply in-session.
+- **Reviewing before the implementer says `complete`.** A `blocked` status stops the loop; do not review a partial slice.

.env.example

@@ -1,9 +1,90 @@
-# Database
+# =============================================================================
+# Environment variables — copy this file to .env and fill in your values.
+# See docs/guides/runbook.md for the full reference.
+# =============================================================================
+
+# --- Required for `pnpm dev` ---
+
+# Postgres connection. Matches `docker compose up -d` default.
 DATABASE_URL=postgresql://postgres:postgres@localhost:5433/template
 
-# Payload CMS
-PAYLOAD_SECRET=your-secret-here
+# Payload CMS encryption key. Any random 32+ char string in dev.
+PAYLOAD_SECRET=replace-with-a-random-32-char-string
+
+# --- Optional: app URLs (defaults work in dev) ---
 
-# App URLs
 NEXT_PUBLIC_APP_URL=http://localhost:3000
 CMS_URL=http://localhost:3001
+
+# Force dev-seed binders (mock repos) regardless of NODE_ENV. Useful for
+# running pnpm dev without Payload booted.
+# USE_DEV_SEED=true
+
+# --- Optional: Sentry observability ---
+# Leaving these unset → instrumentation falls back to the no-op tracer/logger.
+# Set the DSN for any app you want OTel + Sentry on.
+
+# WEB_NEXT_SENTRY_DSN=
+# NEXT_PUBLIC_WEB_NEXT_SENTRY_DSN=
+# CMS_SENTRY_DSN=
+# WEB_TANSTACK_SENTRY_DSN=
+# VITE_WEB_TANSTACK_SENTRY_DSN=
+
+# Source-map upload at build time (production only).
+# SENTRY_AUTH_TOKEN=
+# SENTRY_ORG=
+# SENTRY_PROJECT_WEB_NEXT=
+# SENTRY_PROJECT_CMS=
+# SENTRY_PROJECT_WEB_TANSTACK=
+
+# OTel trace sample rate (0.0 = none, 1.0 = all). 0.1 recommended in dev.
+# SENTRY_TRACES_SAMPLE_RATE=0.1
+# SENTRY_ENVIRONMENT=development
+
+# --- Optional: git commit SHA for releases ---
+
+# VERCEL_GIT_COMMIT_SHA=
+# NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA=
+# VITE_GIT_COMMIT_SHA=
+
+# --- Optional: core-audit (only when `gen core-package audit` is scaffolded) ---
+
+# Salt for GDPR pseudonymisation. PRODUCTION MUST set this to a stable secret.
+# AUDIT_PSEUDONYM_SALT=
+
+# --- Optional: sandcastle dispatch (only when running `pnpm work dispatch --execute`) ---
+
+# Auth (pick one — subscription is preferred):
+#
+# 1. Subscription mode (recommended for Pro/Max subscribers):
+#    Run `claude login` on the host once. Sandcastle bind-mounts ~/.claude/
+#    into the sandbox so the container's Claude Code CLI uses your session.
+#    Zero per-task token spend. No env var needed.
+#
+# 2. API-key mode (fallback when no host creds available):
+# ANTHROPIC_API_KEY=
+# OPENAI_API_KEY=
+
+# Override the path to host Claude Code creds (default: ~/.claude/)
+# SANDCASTLE_CLAUDE_CREDS_DIR=
+
+# GitHub access (optional — for orchestrator-created PRs)
+# GITHUB_TOKEN=
+
+# Sandbox provider (default: docker; alternatives: podman, vercel, daytona)
+# SANDCASTLE_PROVIDER=docker
+
+# Agent iteration budgets. Sandcastle's `run()` cuts the agent off after N
+# iterations (one iteration = one tool-use + response round-trip). The
+# repo's defaults are tuned for typical work; bump if an agent gets cut
+# mid-commit (you'll see "Reached max iterations" in .sandcastle/logs/).
+#
+# SANDCASTLE_DECOMPOSE_ITERATIONS=10     # decompose: read PRD, write epic + stories, commit
+# SANDCASTLE_IMPLEMENTER_ITERATIONS=30   # implementer: full TDD slice (red test → green impl → gates → commit)
+# SANDCASTLE_REVIEWER_ITERATIONS=10      # reviewer: read diff + task, return decision
+
+# Reject-cycle cap. After this many reviewer rejects on the same slice, the
+# dispatch loop gives up on that slice and exits 1 with the last rejection
+# notes printed. Bump for tricky slices; lower for fast-feedback iteration.
+#
+# SANDCASTLE_MAX_ATTEMPTS=3

.fallowrc.json

@@ -0,0 +1,109 @@
+{
+  "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
+  "ignorePatterns": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/.next/**",
+    "**/.turbo/**",
+    "**/storybook-static/**",
+    "**/__snapshots__/**",
+    "**/turbo/generators/templates/**",
+    "**/*.generated.ts",
+    "**/*.d.ts"
+  ],
+  "dynamicallyLoaded": [
+    "packages/**/__factories__/**",
+    "packages/**/__seeds__/**",
+    "apps/**/instrumentation.ts",
+    "apps/**/instrumentation-client.ts",
+    "apps/storybook/test-runner.config.ts",
+    "scripts/**/*.mjs",
+    "turbo/generators/**/*.test.mjs"
+  ],
+  "publicPackages": ["@repo/core-*"],
+  "ignoreDependencies": [
+    "@payloadcms/ui",
+    "sass",
+    "sharp",
+    "@tanstack/react-query",
+    "@trpc/server",
+    "superjson",
+    "@repo/blog",
+    "@repo/core-api",
+    "@repo/marketing-pages",
+    "@repo/navigation",
+    "@repo/core-testing",
+    "http-server",
+    "wait-on",
+    "@opentelemetry/api-logs",
+    "@typescript-eslint/eslint-plugin",
+    "@testing-library/user-event",
+    "zod",
+    "@eslint/js",
+    "@opentelemetry/sdk-node",
+    "@sentry/opentelemetry",
+    "@stryker-mutator/core",
+    "@stryker-mutator/vitest-runner",
+    "@trpc/client",
+    "@trpc/react-query"
+  ],
+  "ignoreExportsUsedInFile": true,
+  "rules": {
+    "unused-files": "warn",
+    "unused-exports": "warn",
+    "unused-types": "off",
+    "unused-class-members": "warn",
+    "unused-dependencies": "warn",
+    "unused-dev-dependencies": "warn",
+    "unlisted-dependencies": "warn",
+    "circular-dependencies": "error",
+    "duplicate-code": "warn",
+    "duplicate-exports": "off"
+  },
+  "health": {
+    "maxCyclomatic": 25,
+    "maxCognitive": 30,
+    "maxCrap": 400
+  },
+  "usedClassMembers": ["validateSession"],
+  "duplicates": {
+    "ignore": [
+      "**/*.test.ts",
+      "**/*.test.tsx",
+      "**/*.stories.tsx",
+      "**/__fixtures__/**",
+      "**/__factories__/**",
+      "**/__seeds__/**",
+      "**/di/bind-production.ts",
+      "**/di/bind-dev-seed.ts",
+      "**/di/symbols.ts",
+      "**/integrations/api/**",
+      "**/ui/trpc.ts",
+      "**/feature.manifest.ts",
+      "**/vitest.config.ts",
+      "scripts/work/**",
+      "**/*.test.mjs",
+      "**/*.test.js",
+      "**/*.mock.ts",
+      "**/instrumentation/sentry/init-client*.ts",
+      "**/instrumentation/di/bind-*.ts",
+      "packages/core-eslint/rules/component-must-have-*.js",
+      "scripts/compliance/**",
+      "**/setup/no-instrumentation.ts",
+      "packages/core-eslint/rules/no-undeclared-*.js"
+    ],
+    "minOccurrences": 2,
+    "minTokens": 70,
+    "threshold": 3.0
+  },
+  "ignoreExports": [
+    {
+      "file": "apps/cms/src/app/**/not-found.tsx",
+      "exports": ["generateMetadata"]
+    },
+    {
+      "file": "apps/web-next/src/server/bind-production.ts",
+      "exports": ["__getInstrumentationForTests"]
+    }
+  ]
+}

.github/renovate.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": [
+    "config:base",
+    "helpers:pinGitHubActionDigests",
+    ":separateMajorReleases",
+    ":automergeMinor",
+    ":automergePatch"
+  ],
+  "dependencyDashboard": true,
+  "dependencyDashboardLabels": ["renovate/dashboard"],
+  "commitMessagePrefix": "chore(deps):",
+  "major": {
+    "commitMessagePrefix": "chore(deps-major):"
+  },
+  "packageRules": [
+    {
+      "groupName": "Sentry packages",
+      "matchPackagePatterns": ["^@sentry/"],
+      "schedule": ["on monday"],
+      "automerge": false
+    },
+    {
+      "groupName": "OpenTelemetry packages",
+      "matchPackagePatterns": ["^@opentelemetry/"],
+      "schedule": ["on monday"],
+      "automerge": false
+    },
+    {
+      "groupName": "tRPC packages",
+      "matchPackagePatterns": ["^@trpc/"],
+      "schedule": ["on monday"],
+      "automerge": false
+    },
+    {
+      "groupName": "Payload packages",
+      "matchPackagePatterns": ["^payload"],
+      "schedule": ["on monday"],
+      "automerge": false
+    },
+    {
+      "groupName": "Inversify packages",
+      "matchPackagePatterns": ["^inversify"],
+      "schedule": ["on monday"],
+      "automerge": false
+    }
+  ],
+  "dockerfile": {
+    "enabled": true,
+    "fileMatch": ["^\\.sandcastle/Dockerfile$"]
+  }
+}

.github/workflows/ci.yml

@@ -0,0 +1,180 @@
+# CI workflow — runs on every push to main and every pull request.
+#
+# TURBO_TOKEN / TURBO_TEAM: set these in your repository secrets/variables
+# to enable Turborepo remote caching. Without them the workflow still works,
+# just without the remote-cache speedup.
+#
+# PAYLOAD_SECRET: the value used here is a throwaway test secret. Do NOT
+# reuse it in production. Set a real secret for your deployed environments.
+
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+env:
+  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+  TURBO_TEAM: ${{ vars.TURBO_TEAM }}
+  CI: true
+
+jobs:
+  validate:
+    name: typecheck + lint + boundaries + test + build
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_USER: postgres
+          POSTGRES_DB: cms_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Full history so coverage:diff can resolve `origin/<base-ref>...HEAD`
+          # against the PR's base branch (ADR-020 L1).
+          fetch-depth: 0
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      # pnpm has no `audit signatures` (that's an npm feature) — the old
+      # step silently ignored "signatures" and ran a plain full audit that
+      # hard-fails on unfixable transitive dev-tooling advisories. Gate on
+      # CRITICAL production-path advisories; Renovate + the weekly trace
+      # revalidation own the long tail.
+      - name: Dependency vulnerability audit (critical, prod paths)
+        run: pnpm audit --prod --audit-level=critical
+      # The real Socket CLI package is `socket` — `socket-cli` is a 0.0.1
+      # stub on npm; failures must be loud, not silently green.
+      - name: Socket supply-chain scan
+        if: github.event_name == 'pull_request'
+        run: |
+          if git diff --name-only origin/${{ github.base_ref }}...HEAD \
+              | grep -qE '(^|/)package\.json$|(^|/)pnpm-lock\.yaml$'; then
+            npx --yes socket@latest scan create --report . || {
+              echo "Socket scan failed (missing SOCKET_SECURITY_API_KEY?) — failing loudly rather than silently skipping."
+              exit 1
+            }
+          else
+            echo "No package.json or pnpm-lock.yaml changes — skipping Socket scan."
+          fi
+      # ADR-023 escalation matrix: Renovate major bumps re-run the library
+      # evaluation; the gate blocks a renovate/* PR whose lockfile majors a
+      # traced dependency without a refreshed trace. No-op on ordinary PRs.
+      - name: Library-trace major-bump gate
+        if: github.event_name == 'pull_request'
+        run: node scripts/library-decisions/check.mjs --renovate-pr
+      - run: pnpm typecheck
+      - run: pnpm lint
+      - run: pnpm conformance
+      # scripts/ is not a workspace package, so `pnpm test` (turbo) never
+      # reaches its test files — they get their own vitest run.
+      - name: Root scripts test suite
+        run: pnpm test:scripts
+      - name: Compliance manifest drift check
+        run: |
+          pnpm compliance:emit-all --check || {
+            echo ""
+            echo "Compliance artifacts are out of date."
+            echo "Run \`pnpm compliance:emit-all\` locally and commit the updated files."
+            exit 1
+          }
+      - name: Fallow whole-codebase analysis
+        run: pnpm fallow --format annotations
+      - run: pnpm turbo boundaries
+      - name: Test with coverage
+        env:
+          DATABASE_URL: postgres://postgres:postgres@localhost:5432/cms_test
+          PAYLOAD_SECRET: test-secret-do-not-use-in-prod
+        run: pnpm test -- --coverage
+      # L2 — merge per-package lcovs to coverage/lcov.info + emit
+      # coverage/summary.json (ADR-020). Runs even on test failure so the
+      # artifact still captures what was produced.
+      - name: Coverage — aggregate (L2)
+        if: always()
+        run: pnpm coverage:aggregate
+      # L1 — cover-the-diff gate. Only meaningful on PRs (push-to-main has
+      # no base ref to diff against). Compares against the PR's base branch.
+      - name: Coverage — diff (L1)
+        if: github.event_name == 'pull_request'
+        run: pnpm coverage:diff -- --base origin/${{ github.base_ref }}
+      - run: pnpm build
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: coverage
+          path: |
+            coverage/lcov.info
+            coverage/summary.json
+            **/coverage/lcov.info
+          retention-days: 7
+
+  e2e:
+    name: Playwright e2e
+    needs: validate
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_USER: postgres
+          POSTGRES_DB: cms_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm exec playwright install --with-deps chromium
+      - name: Run e2e
+        env:
+          DATABASE_URL: postgres://postgres:postgres@localhost:5432/cms_test
+          PAYLOAD_SECRET: test-secret-do-not-use-in-prod
+        run: pnpm test:e2e
+
+  storybook:
+    name: Storybook smoke tests + visual regression
+    needs: validate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm exec playwright install --with-deps chromium
+      - name: Build Storybook
+        run: pnpm --filter @repo/storybook build:storybook
+      - run: pnpm test:stories
+      - name: Visual regression
+        run: pnpm test:visual

.github/workflows/codeql.yml

@@ -0,0 +1,44 @@
+# CodeQL static analysis — javascript-typescript.
+#
+# Runs on every push to main, every pull request, and weekly on Wednesday
+# at 02:00 UTC (staggered from the trace-revalidation cron on Monday 06:30).
+#
+# NOTE (consumers): CodeQL is free for public repositories and GitHub Free
+# plans. For *private* repositories it requires GitHub Advanced Security
+# (available on GitHub Enterprise Cloud/Server or as an add-on). If you are
+# using this template with a private repo and do not have Advanced Security
+# enabled, remove or disable this workflow — it will fail at the "Initialize
+# CodeQL" step with a licensing error.
+
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    # 02:00 UTC every Wednesday
+    - cron: "0 2 * * 3"
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  analyze:
+    name: Analyze (javascript-typescript)
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: javascript-typescript
+          # Uses the default query suite (security-and-quality). To restrict
+          # to security-only queries, set:
+          #   queries: security-extended
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v3
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3

.github/workflows/coverage-snapshot.yml

@@ -0,0 +1,72 @@
+# Coverage snapshot — commits coverage/summary.json back to main after each
+# merge so the trend history accumulates in `git log -- coverage/summary.json`
+# (ADR-020 L2). This is the only workflow that needs `contents: write`.
+#
+# Skipped if summary.json hasn't changed since the previous commit.
+
+name: Coverage snapshot
+
+on:
+  push:
+    branches: [main]
+
+# Avoid two snapshot runs racing each other on rapid-fire merges.
+concurrency:
+  group: coverage-snapshot
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+
+jobs:
+  snapshot:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_USER: postgres
+          POSTGRES_DB: cms_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Token with write scope so we can push the snapshot back.
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - name: Test with coverage
+        env:
+          DATABASE_URL: postgres://postgres:postgres@localhost:5432/cms_test
+          PAYLOAD_SECRET: test-secret-do-not-use-in-prod
+        run: pnpm test -- --coverage
+      - name: Aggregate
+        run: pnpm coverage:aggregate
+      - name: Commit summary.json if changed
+        run: |
+          if git diff --quiet --exit-code coverage/summary.json; then
+            echo "No summary.json change; skipping commit."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add coverage/summary.json
+          git commit -m "chore(coverage): snapshot ${GITHUB_SHA::7}
+
+          Auto-generated by .github/workflows/coverage-snapshot.yml.
+
+          [skip ci]"
+          git push origin HEAD:main

.github/workflows/mutation-nightly.yml

@@ -0,0 +1,114 @@
+# Mutation testing (L3) — nightly run + on-demand. ADR-020.
+#
+# Stryker is slow (~minutes per feature) so it's NOT part of the default
+# CI loop. This workflow runs nightly (and on manual dispatch) across every
+# feature with a stryker.config.json, then uploads the HTML + JSON
+# mutation reports as artifacts.
+#
+# On a meaningful score drop (>5%) it opens a tracking issue.
+
+name: Mutation testing (nightly)
+
+on:
+  schedule:
+    # 02:30 UTC nightly
+    - cron: "30 2 * * *"
+  workflow_dispatch:
+    inputs:
+      filter:
+        description: "Feature filter (e.g. @repo/auth). Empty = all features."
+        required: false
+        default: ""
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  mutate:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_USER: postgres
+          POSTGRES_DB: cms_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - name: Run mutation testing
+        id: mutate
+        env:
+          DATABASE_URL: postgres://postgres:postgres@localhost:5432/cms_test
+          PAYLOAD_SECRET: test-secret-do-not-use-in-prod
+        run: |
+          if [ -n "${{ inputs.filter }}" ]; then
+            pnpm mutate -- --filter "${{ inputs.filter }}"
+          else
+            pnpm mutate
+          fi
+        continue-on-error: true
+      - name: Upload mutation reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: mutation-reports
+          path: packages/*/reports/mutation/
+          retention-days: 30
+      # `continue-on-error: true` means the JOB never reports failure — gate
+      # the tracking issue on the STEP outcome instead (if: failure() was
+      # unreachable and the issue could never open).
+      - name: Open tracking issue on >5% score drop
+        if: steps.mutate.outcome == 'failure'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const path = require('path');
+            const reports = [];
+            const pkgsDir = path.join(process.cwd(), 'packages');
+            if (fs.existsSync(pkgsDir)) {
+              for (const pkg of fs.readdirSync(pkgsDir)) {
+                const json = path.join(pkgsDir, pkg, 'reports', 'mutation', 'mutation.json');
+                if (fs.existsSync(json)) {
+                  try {
+                    const data = JSON.parse(fs.readFileSync(json, 'utf8'));
+                    const score = data.thresholds?.high && data.systemUnderTestMetrics?.metrics?.mutationScore;
+                    if (typeof score === 'number') {
+                      reports.push({ pkg, score: score.toFixed(2) });
+                    }
+                  } catch { /* skip */ }
+                }
+              }
+            }
+            if (reports.length === 0) return;
+            const body = [
+              'Nightly mutation testing run flagged failures. Latest scores:',
+              '',
+              ...reports.map(r => `- **${r.pkg}**: ${r.score}%`),
+              '',
+              `Run: ${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
+            ].join('\n');
+            await github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: `Mutation score drop — ${new Date().toISOString().slice(0, 10)}`,
+              body,
+              labels: ['mutation-testing', 'automated'],
+            });

.github/workflows/release-please.yml

@@ -0,0 +1,83 @@
+# Release Please — automated changelog + version bumps on merge to main.
+#
+# How it works:
+#   1. On every push to main, release-please scans conventional commits since
+#      the last release tag for each tracked package.
+#   2. It opens (or updates) a single rolling "release PR" containing:
+#        - version bumps in each affected package.json
+#        - new CHANGELOG.md entries grouped by section (Features / Bug Fixes
+#          / Performance / Refactoring / Documentation / Reverts)
+#        - updated .release-please-manifest.json
+#   3. Merging that PR triggers tag creation (`template-vN.N.N`, `auth-vN.N.N`,
+#      etc.) and GitHub release notes.
+#
+# Hybrid versioning (ADR-021): root template versions independently from the
+# 5 feature packages. Tags use the per-package component prefix so they don't
+# collide (e.g. `template-v0.2.0` vs `auth-v0.1.1`).
+#
+# Tracked packages, manifest baseline, and changelog sections live in
+# `release-please-config.json` + `.release-please-manifest.json`.
+
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+# A second push to main while a release PR is open shouldn't fight with the
+# first invocation — release-please-action already updates the rolling PR
+# idempotently, but concurrency keeps the audit trail clean.
+concurrency:
+  group: release-please
+  cancel-in-progress: false
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      # The steps below run only when release-please actually cut a release.
+      # pnpm dlx avoids adding @cyclonedx/cyclonedx-npm to the lockfile (CI-only
+      # tool per ADR-022); SHA-pinned action follows ADR-023 §1 Renovate pattern.
+      - uses: actions/checkout@v4
+        if: ${{ steps.release.outputs.releases_created == 'true' }}
+
+      - uses: pnpm/action-setup@v4
+        if: ${{ steps.release.outputs.releases_created == 'true' }}
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        if: ${{ steps.release.outputs.releases_created == 'true' }}
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        if: ${{ steps.release.outputs.releases_created == 'true' }}
+        run: pnpm install --frozen-lockfile
+
+      - name: Generate CycloneDX SBOM
+        if: ${{ steps.release.outputs.releases_created == 'true' }}
+        run: >
+          pnpm dlx @cyclonedx/cyclonedx-npm
+          --output-file sbom-${{ steps.release.outputs.tag_name }}.cdx.json
+          --output-format json
+          --ignore-npm-errors
+
+      - name: Attach SBOM to GitHub release
+        if: ${{ steps.release.outputs.releases_created == 'true' }}
+        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v3.0.0
+        with:
+          tag_name: ${{ steps.release.outputs.tag_name }}
+          files: sbom-${{ steps.release.outputs.tag_name }}.cdx.json

.github/workflows/sentry-pii-guard.yml

@@ -0,0 +1,28 @@
+# R31 — block sendDefaultPii: true from ever landing.
+#
+# This is a defense-in-depth gate: the privacy posture is also enforced by
+# the centralized init helpers in core-shared/instrumentation/sentry/, but
+# this grep makes any drift impossible to merge.
+
+name: Sentry PII guard (R31)
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  pii-guard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Verify sendDefaultPii is never true
+        run: |
+          if grep -RIn --include='*.ts' --include='*.tsx' --include='*.mjs' --include='*.cjs' --include='*.js' \
+              --exclude-dir=node_modules --exclude-dir=.next --exclude-dir=dist --exclude-dir=.turbo \
+              -E 'sendDefaultPii\s*:\s*true' \
+              packages/ apps/; then
+            echo "::error::R31 violation — sendDefaultPii: true is forbidden anywhere in the repo."
+            exit 1
+          fi
+          echo "OK — no sendDefaultPii: true detected."

.github/workflows/trace-revalidation-weekly.yml

@@ -0,0 +1,38 @@
+# Library trace revalidation — weekly run + on-demand. ADR-022.
+#
+# Walks every approved + pre-shipped trace in docs/library-decisions/,
+# re-runs each trace's verification-commands, classifies divergence as
+# soft (minor drift → rolling dashboard issue) or hard (re-evaluation
+# warranted → per-dep issue), and opens/updates/closes GitHub issues
+# accordingly. Runs in parallel to main — does NOT gate deployments.
+
+name: Library trace revalidation (weekly)
+
+on:
+  schedule:
+    # 06:30 UTC every Monday
+    - cron: "30 6 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  revalidate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - name: Revalidate library traces
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: node scripts/library-decisions/revalidate.mjs

.gitignore

@@ -1,9 +1,18 @@
 # Dependencies
 node_modules
 
+# pnpm's content-addressable store (only present when a misconfigured
+# pnpm install places the store inside the project rather than at the
+# global default ~/.local/share/pnpm/store). Always ignored — the store
+# is pnpm's cache, not source.
+.pnpm-store/
+
 # Turbo
 .turbo
 
+# TypeScript incremental build state
+*.tsbuildinfo
+
 # Build outputs
 dist
 build
@@ -16,8 +25,23 @@ storybook-static
 .env.local
 .env.*.local
 
-# Testing
-coverage
+# Per-user local overrides (never commit — .claude/settings.local.json, etc.)
+*.local
+*.local.*
+**/settings.local.json
+
+# Testing — per-package coverage output (vitest)
+packages/*/coverage/
+apps/*/coverage/
+# Aggregated coverage output (pnpm coverage:aggregate): ignore everything
+# under /coverage/ EXCEPT summary.json (committed for trend history per
+# ADR-020) and .gitkeep markers.
+/coverage/*
+!/coverage/summary.json
+!/coverage/.gitkeep
+# Keep the source scripts at scripts/coverage/ tracked (allows files
+# named "coverage" elsewhere)
+!/scripts/coverage/
 
 # OS
 .DS_Store
@@ -37,3 +61,9 @@ pnpm-debug.log*
 
 # Git worktrees
 .worktrees/
+
+# Template setup history — preserved locally, invisible to fresh clones.
+.archive/
+
+# Scratch / working notes — local only, never committed.
+.tmp/

.gitleaks.toml

@@ -0,0 +1,14 @@
+# Gitleaks configuration for this monorepo.
+# Docs: https://github.com/gitleaks/gitleaks#configuration
+
+title = "gitleaks config"
+
+[extend]
+# Use the upstream default ruleset as the base.
+useDefault = true
+
+[allowlist]
+description = "Test fixtures in __seeds__ directories use token-shaped dummy strings that are not real credentials."
+paths = [
+  '''__seeds__/''',
+]

.husky/pre-commit

@@ -0,0 +1,38 @@
+#!/usr/bin/env sh
+
+# Pre-commit gates — fast checks only. Slow checks (full conformance, full
+# test, full typecheck) stay in CI.
+
+# 1. lint-staged: format + lint staged files
+pnpm exec lint-staged || exit 1
+
+# 2. Stamp the `updated:` frontmatter field on every staged docs/work/ md file.
+node scripts/work/bump-updated-timestamps.mjs || exit 1
+
+# 3. If any docs/work/ markdown is staged, regenerate _state.json + re-stage it
+if git diff --cached --name-only | grep -qE '^docs/work/.*\.md$'; then
+  pnpm work rebuild-state
+  git add docs/work/_system/_state.json
+fi
+
+# 3. Run the state-sync guard: refuses to commit if _state.json is
+# staged but doesn't match what rebuild-state would produce. Catches the case
+# where someone hand-edits _state.json without going through rebuild-state.
+node scripts/work/state-sync-guard.mjs || exit 1
+
+# 4. Check library decision traces for new runtime deps in feature/core packages.
+node scripts/library-decisions/check.mjs || exit 1
+
+# 5. If any staged file touches Payload configs, library traces, or compliance
+#    artifacts, regenerate compliance YAMLs and auto-stage them.
+if git diff --cached --name-only | grep -qE '^(packages/[^/]+/src/integrations/cms/|docs/library-decisions/|compliance/)'; then
+  pnpm compliance:emit-all || exit 1
+  git add compliance/
+fi
+
+# 6. Scan staged changes for secrets (skip gracefully if gitleaks is not installed).
+if command -v gitleaks > /dev/null 2>&1; then
+  gitleaks protect --staged --redact || exit 1
+else
+  echo "gitleaks not found in \$PATH — skipping secret scan (install via brew install gitleaks or https://github.com/gitleaks/gitleaks)"
+fi

.prettierignore

@@ -0,0 +1,2 @@
+# Generated compliance artifacts — do not reformat
+compliance/*.yml

.release-please-manifest.json

@@ -0,0 +1,8 @@
+{
+  ".": "0.1.0",
+  "packages/auth": "0.1.0",
+  "packages/blog": "0.1.0",
+  "packages/media": "0.1.0",
+  "packages/marketing-pages": "0.1.0",
+  "packages/navigation": "0.1.0"
+}

.sandcastle/.env.example

@@ -0,0 +1,20 @@
+# .sandcastle/.env — runtime tokens for sandcastle dispatch.
+# Copy to .sandcastle/.env (gitignored) and fill what you need.
+#
+# Most developers don't need ANY of these if they've run `claude login` on
+# the host — sandcastle mounts ~/.claude/ into the sandbox by default.
+
+# Anthropic API key (fallback when no host Claude Code session exists)
+# ANTHROPIC_API_KEY=
+
+# OpenAI / Codex (alternative)
+# OPENAI_API_KEY=
+
+# GitHub access for orchestrator-created PRs
+# GITHUB_TOKEN=
+
+# Override Claude creds path (default: ~/.claude/)
+# SANDCASTLE_CLAUDE_CREDS_DIR=
+
+# Sandbox provider (docker / podman / vercel / daytona)
+SANDCASTLE_PROVIDER=docker

.sandcastle/.gitignore

@@ -0,0 +1,3 @@
+.env
+*.log
+.cache/

.sandcastle/Dockerfile

@@ -0,0 +1,52 @@
+# Sandcastle sandbox image — runs the implementer + reviewer + decomposer
+# agents. Shape required by @ai-hero/sandcastle: a non-root `agent` user
+# (UID/GID aligned with the host so bind-mounted files share owner), Claude
+# Code CLI on PATH, and a long-running ENTRYPOINT so the container survives
+# the gap between sandcastle creating it and exec'ing into it.
+#
+# Authenticates via the host's mounted ~/.claude/ session (subscription
+# mode — sandcastle issue #191 workaround, our primary flow). Falls back
+# to ANTHROPIC_API_KEY when no host credentials are present.
+
+FROM node:22-bookworm
+
+# System deps — git for worktree ops, curl for the Claude installer, jq for
+# JSON tooling agents use, plus ca-certificates implicit in the base image.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    curl \
+    jq \
+    && rm -rf /var/lib/apt/lists/*
+
+# pnpm via corepack (matches the repo's packageManager version).
+RUN corepack enable && corepack prepare pnpm@9 --activate
+
+# Build-args for UID/GID alignment: `sandcastle docker build-image` passes
+# the host user's UID/GID by default so image-built files and bind-mounted
+# files share an owner without runtime chown.
+ARG AGENT_UID=1000
+ARG AGENT_GID=1000
+
+# Rename the base image's "node" user to "agent" and align UID/GID.
+# `-o` (non-unique) is required because the host's GID may collide with a
+# pre-existing system group in the base image (e.g. macOS UID:501 GID:20
+# collides with Debian's `dialout` group at GID 20). Allowing a duplicate
+# GID is safe here — only one user occupies the sandbox.
+RUN groupmod -o -g $AGENT_GID node && \
+    usermod -o -u $AGENT_UID -g $AGENT_GID -d /home/agent -m -l agent node
+
+USER ${AGENT_UID}:${AGENT_GID}
+
+# Claude Code CLI — used by sandcastle's claudeCode() agent provider.
+# The CLI reads credentials from ~/.claude/ inside the container; the host
+# mounts its ~/.claude/ over that path at sandbox start.
+RUN curl -fsSL https://claude.ai/install.sh | bash
+
+ENV PATH="/home/agent/.local/bin:$PATH"
+
+WORKDIR /home/agent
+
+# In worktree sandbox mode, sandcastle bind-mounts the git worktree at
+# ${SANDBOX_REPO_DIR} and overrides the working directory to that path at
+# container start. The Dockerfile's WORKDIR is just the default home.
+ENTRYPOINT ["sleep", "infinity"]

.sandcastle/README.md

@@ -0,0 +1,57 @@
+# .sandcastle/
+
+This directory holds prompt templates that the future orchestrator
+(`pnpm work dispatch` in the `sandcastle-dispatch-v1` epic) feeds to
+[sandcastle](https://github.com/mattpocock/sandcastle) when dispatching
+agents.
+
+## Prompt templates
+
+| File                     | Role                                      | Variables                           |
+| ------------------------ | ----------------------------------------- | ----------------------------------- |
+| `prd-eliciter.prompt.md` | Interview a human to produce a PRD draft  | `{{INITIAL_BRIEF}}`                 |
+| `adr-eliciter.prompt.md` | Interview a human to produce an ADR draft | `{{INITIAL_PROPOSAL}}`              |
+| `decomposer.prompt.md`   | Turn a PRD into epic + story files        | `{{PRD_FILE_CONTENT}}`              |
+| `implementer.prompt.md`  | Execute a single task                     | `{{TASK_FILE_CONTENT}}`             |
+| `reviewer.prompt.md`     | Review the implementer's diff             | `{{TASK_FILE_CONTENT}}`, `{{DIFF}}` |
+
+## Convention: every prompt enforces "generators first"
+
+Each prompt template starts with the same non-negotiable rule: **the agent
+must prefer `pnpm turbo gen <kind>` over hand-rolled scaffolding.** This
+applies to feature packages, events, jobs, realtime channels, optional
+core packages, and atomic-design components. Hand-rolled code is only
+acceptable when the generator's output doesn't cover the case — and even
+then, the agent runs the generator first and modifies its output rather
+than starting from scratch.
+
+## Environment
+
+Configure runtime tokens via `.env` (gitignored). Copy `.env.example`
+and fill values for the providers you use.
+
+## Build the sandbox image (one-time)
+
+Sandcastle dispatches into a Docker image tagged `sandcastle:<root-package-name>`.
+Build it once per clone before `pnpm work dispatch --execute` or
+`pnpm work decompose <id> --execute` will work:
+
+```bash
+pnpm exec sandcastle docker build-image
+# Tags: sandcastle:template-vertical
+```
+
+Rebuild after editing this `Dockerfile`:
+
+```bash
+pnpm exec sandcastle docker remove-image
+pnpm exec sandcastle docker build-image
+```
+
+See [`docs/guides/runbook.md` → Using Sandcastle → Prerequisites](../docs/guides/runbook.md#using-sandcastle-for-agent-dispatch) for the full setup.
+
+## Manual usage
+
+Until the orchestrator ships, these templates are usable manually: copy
+the relevant `.prompt.md` content into a Claude / Codex / other agent
+session, fill the `{{VARIABLE}}` placeholders by hand, and run.

.sandcastle/adr-eliciter.prompt.md

@@ -0,0 +1,61 @@
+# ADR Elicitation Agent
+
+You are an Architecture Decision Record (ADR) elicitation agent for the template-vertical monorepo. Your job is to interview a human (one question at a time) and produce a complete ADR that captures the trade-offs of a proposed infrastructure decision.
+
+## Use generators first (non-negotiable)
+
+When the ADR concerns adopting infrastructure that has a generator path, the ADR's "Decision" section MUST reference the generator:
+
+- **New optional core package** (cache, email, feature-flags, etc.) → `pnpm turbo gen core-package <name>`
+- **Atomic-design component library** → `pnpm turbo gen core-ui-component <name>` to seed
+- **Feature package as part of the integration** → `pnpm turbo gen feature <name>`
+
+If the ADR is about adopting a package that has a generator and you describe the integration as hand-rolled, you have failed.
+
+## Input
+
+The human's initial proposal:
+
+```
+{{INITIAL_PROPOSAL}}
+```
+
+## Interview rules
+
+1. Ask ONE question at a time.
+2. **Push the human to articulate alternatives.** If they only describe one option, your next question is "What other options did you consider and reject?" — ADRs without alternatives are weak.
+3. Topics, in order:
+   - **Context**: what's the situation? What problem is forcing a decision?
+   - **Drivers**: what's making this decision urgent (timeline, cost, deprecation, …)?
+   - **Considered options**: enumerate ALL alternatives, minimum 2. For each, pros + cons.
+   - **Decision**: which option, and why. Reference generators if applicable.
+   - **Consequences**: positive + negative + follow-up work (PRDs).
+4. Minimum 5 substantive answers before drafting.
+
+## Output
+
+Write the ADR to `docs/adr/NNN-<slug>.md` (use the next available NNN number; check `docs/adr/` for existing ADRs).
+
+Frontmatter:
+
+```yaml
+---
+id: NNN
+title: <decision title>
+status: proposed
+date: <today>
+supersedes: []
+superseded-by: null
+related-prds: []
+---
+```
+
+Body: Context, Drivers, Considered options, Decision, Consequences (Positive / Negative / Follow-up work).
+
+Tell the human the file path. Tell them to review and flip `status: proposed` → `status: accepted` (or `rejected` / `superseded`) before any downstream PRDs are decomposed.
+
+## Don't
+
+- Don't accept a single-option ADR. Push for alternatives.
+- Don't skip the generator check.
+- Don't write code or PRDs.

.sandcastle/decomposer.prompt.md

@@ -0,0 +1,87 @@
+# Decomposer Agent
+
+You are the decomposer agent. Given an approved PRD, you produce the epic file + one story file per requirement under `docs/work/epics/<epic-slug>/`. Folder names use the **bare slug** — no date prefix; the `created:` timestamp in frontmatter carries the date. Each story has its own checkbox-driven Tasks list — where **every checkbox is a vertical slice**.
+
+## The slice rule (non-negotiable)
+
+**slice = task = PR = commit.** Every task you write MUST satisfy ALL of:
+
+1. **One green commit.** After the task lands, `pnpm typecheck && pnpm lint && pnpm test && pnpm conformance && pnpm fallow:audit && pnpm coverage:diff` all pass. No task may leave the repo in a broken state.
+2. **Exercises a layer.** The task either creates a NEW piece of vertical capability (manifest entry + contracts + test + impl + DI wiring + integration, end-to-end for one slice), OR completes a self-contained refactor (e.g. "wire feature X's binder through the new helper") that keeps the slice green.
+3. **Independently meaningful.** Reading the task description, an implementer can know what "done" looks like without reading the next checkbox.
+
+## Tasks that are FORBIDDEN
+
+- **"Read X file"** — reading is part of doing the work, not a separate task. The implementer reads what it needs to read.
+- **"Write the test"** as a standalone task when the implementation hasn't landed (the test gate is red between this checkbox and the next — violates rule 1). Same for "write the implementation" without the test.
+- **"Run typecheck"** / **"Run pnpm test"** / **"Run lint"** as separate tasks — these gates are part of the implementer's done-criteria for every task, not their own checkboxes.
+- **"Export X from index.ts"** as a standalone task when the export's consumer also lands in this story — combine them. (Standalone export is fine only when it's the entire payload of a slice; rare.)
+- **Sub-step decomposition of a single slice** ("Step 1: scaffold the file. Step 2: implement the body. Step 3: add tests.") — that's one task, not three.
+
+## Tasks that are CORRECT
+
+- **`Run pnpm turbo gen <kind> <args>`** — generator scaffolds an entire slice (manifest + contracts + tests + impl + DI wiring) in one shot. Always the FIRST task for any story that creates new feature/event/job/realtime/core-package/component code.
+- **`Add use case <name> to <feature>`** — one full vertical slice: manifest entry + contracts (input/output schemas, IXUseCase type) + red test + green impl + DI binding + (if cross-feature) event wiring. All in one commit; the implementer follows the manifest-first ordering inside the task.
+- **`Migrate <feature>'s binders to <helper>`** — for refactor stories: replace the inline wrapping in `bind-production.ts` + `bind-dev-seed.ts` of one feature, keep the feature's tests green. One commit per feature, NOT one per binder file.
+- **`Add audit emission to <use-case>`** — manifest's `audits: [...]` declaration + `auditLog.record(...)` call site + test asserting the audit, all in one commit.
+- **`Wire <feature> into apps/<app>/bindAll()`** — single binding integration point landing with its test.
+
+## Manifest-first ordering INSIDE a task
+
+When a single task creates a new use case, the implementer's INTERNAL ordering is (1) manifest entry → (2) contracts → (3) red test → (4) green impl — but this is one task that lands as one commit. The four steps don't become four separate checkboxes; they're the work done inside a single slice. The reviewer verifies the slice is whole, not that the implementer wrote things in a specific order.
+
+## Use generators first (non-negotiable)
+
+When decomposing requirements into stories + tasks, your first task in every story that creates a feature / event / job / realtime / core-package / component MUST be `Run \`pnpm turbo gen <kind> <name>\``. Do not write a story whose first task is "hand-write src/foo.ts" when a generator can produce src/foo.ts. The generators are:
+
+- `pnpm turbo gen feature <name>` — feature scaffold (manifest, contracts, binders, controllers, tests)
+- `pnpm turbo gen event` — event contract (publish) or handler (consume)
+- `pnpm turbo gen job` — background job
+- `pnpm turbo gen realtime` — realtime channel or inbound handler
+- `pnpm turbo gen core-package <name>` — optional core package
+- `pnpm turbo gen core-ui-component <name>` — atomic-design component
+
+For each requirement, ask: "is there a generator for this?" If yes, the first task is the generator invocation; subsequent tasks customise the generator's output (add use-case behaviours, declare audits/publishes, etc.).
+
+## Input
+
+The approved PRD:
+
+```
+{{PRD_FILE_CONTENT}}
+```
+
+## Your job
+
+1. Read the PRD. Extract: epic id (kebab-slug from title — **no date prefix**; the `created:` timestamp carries the date), story list (one per Requirement), dependency edges (from "depends on" hints in the PRD), out-of-scope items. The epic id should match the PRD's `id:` field exactly.
+2. Write `docs/work/epics/<epic-id>/_epic.md` with frontmatter: `id`, `prd` (path to the PRD file), `title`, `type: epic`, `status: in-progress`, `features`, `created: <ISO-8601-UTC-timestamp>` (use the current timestamp). The pre-commit hook adds `updated:` automatically — do NOT set it yourself.
+3. For each Requirement, write `docs/work/epics/<epic-id>/<NN>-<story-slug>/_story.md`:
+   - Frontmatter: `id`, `epic`, `title`, `type: technical-story | user-story`, `status: in-progress` (for the first) or `todo` (subsequent), `feature`, `depends-on` (array, may reference other stories in this epic by id), `blocks`, `created: <ISO-8601-UTC-timestamp>`. The pre-commit hook stamps `updated:` — do NOT set it yourself.
+   - Sections: Goal, Why, Done when, In scope, Out of scope, Tasks (checkbox list).
+   - **Each story's Tasks list:** every checkbox MUST satisfy the slice rule above — one green commit per checkbox. If a generator is applicable, list the generator invocation as the FIRST checkbox; subsequent checkboxes customise the generator's output and each one lands its own green commit (e.g. "Add audit emission to use case X", "Wire event publish from X into bus").
+
+## Output
+
+Do not implement anything. Do not write code. Do not invent requirements not in the PRD. Each story should be a thin descriptor; the implementer fills in details when it picks up each task.
+
+When done, tell the human the epic folder path and offer them a chance to review + edit before invoking the implementer.
+
+## Constraints
+
+- Stay literal to the PRD. The decomposer's judgment is about structure (which requirement becomes which story, what depends-on edges look like), not content.
+- If a Requirement is too broad for one story, split it into multiple stories with clear depends-on chains. Don't merge unrelated Requirements into one story.
+- If the PRD's status is not `approved`, refuse to decompose and tell the human to flip it first.
+- **Slice discipline:** prefer FEWER but FATTER tasks (one per vertical slice) over MANY thinner sub-steps. If you're tempted to write more than ~5 checkboxes for a story, ask: "is each one really an independent vertical slice that lands as its own green commit?" If not, collapse the sub-steps into a single task and trust the implementer to follow the manifest-first ordering internally.
+- **Self-check before writing each Tasks list:** for each checkbox, imagine the commit it would produce. Would `pnpm typecheck && pnpm lint && pnpm test && pnpm conformance && pnpm coverage:diff` all pass on that commit alone? If no, the checkbox isn't a slice — merge it with its neighbours.
+
+## Signal completion (required)
+
+When the epic folder + story files are written and committed (or you have determined the work is truly done — including the case where you decided not to write anything and reported the reason), emit the literal string `<promise>COMPLETE</promise>` as the final line of your response.
+
+Sandcastle uses this marker to stop the iteration loop. Without it, the orchestrator will re-invoke you up to `maxIterations` times even when the work is already done — every redundant iteration costs subscription quota and time.
+
+Do NOT emit the marker if:
+
+- You still have files to write, gates to run, or commits to make.
+- You returned a partial result and intend the next iteration to continue.
+- You hit an error you want sandcastle to surface as "max iterations reached" rather than "complete."

.sandcastle/implementer.prompt.md

@@ -0,0 +1,112 @@
+# Implementer Agent
+
+You are the implementer agent. You execute ONE task at a time, identified by the task description below. Your output is a single green commit (or a series of commits squashed at merge time).
+
+## Use generators first (non-negotiable)
+
+Before writing any code: if your task description includes `pnpm turbo gen <kind> ...`, run that command FIRST and use its output as your starting point. Even if the generator only emits half of what you need, customising generator output is always preferred over hand-rolling.
+
+Available generators:
+
+- `pnpm turbo gen feature <name>` — full feature scaffold
+- `pnpm turbo gen event` — event contract or handler
+- `pnpm turbo gen job` — background job
+- `pnpm turbo gen realtime` — realtime channel or handler
+- `pnpm turbo gen core-package <name>` — optional core package
+- `pnpm turbo gen core-ui-component <name>` — atomic-design component
+
+If your task's first checkbox is a generator invocation, that's your first action. Do not skip ahead.
+
+## Task
+
+```
+{{TASK_FILE_CONTENT}}
+```
+
+## Manifest-first ordering
+
+For any new use case, the order is non-negotiable:
+
+1. **Manifest entry** — add to `feature.manifest.ts`
+2. **Contracts** — `xInputSchema`, `xOutputSchema`, `IXUseCase` exports in the use-case file (factory body throws `not implemented` initially)
+3. **Tests (red)** — write the failing test
+4. **Implementation (green)** — fill the factory body until tests pass
+
+The generator handles step 1 + 2 for you when scaffolding a new feature.
+
+## Conformance gates (run before declaring done)
+
+```
+pnpm typecheck   # TS brand-slot enforcement, 0s
+pnpm lint        # ESLint rules incl. conformance/* — <1s
+pnpm test --filter @repo/<feature> -- --coverage   # tests + per-layer thresholds for the feature you touched
+pnpm conformance # cross-feature event closure
+pnpm fallow:audit # whole-codebase analysis: dead exports, dupes, circular deps, complexity
+```
+
+All five pass before you commit. If any fail, fix or report BLOCKED — do not paper over.
+
+## Coverage gates (ADR-020 — run after the conformance gates)
+
+The coverage architecture has its own multi-layer enforcement that's distinct from the conformance gates above. Run all of these before declaring done:
+
+```
+pnpm test -- --coverage          # L0 — per-layer thresholds (100% on entities/use-cases/controllers)
+pnpm coverage:aggregate          # L2 — merges per-package lcovs to coverage/lcov.info + coverage/summary.json
+pnpm coverage:diff -- --base <base-ref>   # L1 — cover-the-diff: every changed line must be exercised
+```
+
+Treat `pnpm coverage:diff` output as machine-readable:
+
+- Exit 0 → pass; the JSON stdout has `status: "pass"`
+- Exit 1 → fail; the JSON stdout's `uncovered` array lists each `{ file, line, kind }` hit
+- `kind: "uncovered"` → write the missing test
+- `kind: "no-coverage-data"` → entire file isn't in lcov; you shipped untested code (a sibling test file is missing)
+
+Fix every hit before reporting `complete`. If you legitimately can't (e.g., the line is genuinely unreachable), extend the allowlist in `scripts/coverage/diff.mjs` AND add a test in `scripts/coverage/diff.test.mjs` — don't silently bypass.
+
+See `docs/guides/coverage.md` for the full architecture (4 layers) and the troubleshooting section. The base ref is usually `origin/main` for PR work; for in-session iteration use `HEAD~N`.
+
+## Commit message format
+
+`<type>(<scope>): <imperative subject>`
+
+Examples:
+
+- `feat(auth): hash password before persisting`
+- `test(blog): assert article not found error`
+- `feat(scripts): conformance drift gate + tests`
+
+Subject line ≤72 chars. Body explains WHY if non-obvious.
+
+## When you're stuck
+
+Report status `BLOCKED` (don't silently produce work you're unsure about). State specifically: what you tried, what's unclear, what kind of help you need (more context / different model / smaller task / plan is wrong).
+
+## Output format
+
+When done, return structured JSON:
+
+```json
+{
+  "status": "complete" | "blocked" | "needs-clarification",
+  "ac_satisfied": [0, 1, 2],
+  "files_changed": ["packages/..."],
+  "commit_sha": "abc123",
+  "notes": "..."
+}
+```
+
+Do NOT modify the task markdown or `_state.json` yourself — the orchestrator handles state writes.
+
+## Signal completion (required)
+
+After you have committed the slice (or returned a terminal `blocked` / `needs-clarification` status), emit the literal string `<promise>COMPLETE</promise>` as the final line of your response.
+
+Sandcastle uses this marker to stop the iteration loop. Without it, the orchestrator will re-invoke you up to `maxIterations` times even when the work is already done — every redundant iteration costs subscription quota and time.
+
+Do NOT emit the marker if:
+
+- The five conformance gates haven't all passed yet.
+- You still have files to write, fixes to apply, or commits to make.
+- You returned a partial result and intend the next iteration to continue.

.sandcastle/prd-eliciter.prompt.md

@@ -0,0 +1,64 @@
+# PRD Elicitation Agent
+
+You are a PRD elicitation agent for the template-vertical monorepo. Your job is to interview a human (one question at a time) and produce a complete, agent-ready PRD that the decomposer can turn into stories.
+
+## Use generators first (non-negotiable)
+
+When the human's idea maps to creating any of these, the PRD's "Requirements" section must explicitly reference the generator that will produce the artefact:
+
+- **Feature package** → `pnpm turbo gen feature <name>`
+- **Event contract / handler** → `pnpm turbo gen event`
+- **Background job** → `pnpm turbo gen job`
+- **Realtime channel / handler** → `pnpm turbo gen realtime`
+- **Optional core package** → `pnpm turbo gen core-package <name>`
+- **Atomic-design component** → `pnpm turbo gen core-ui-component <name>`
+
+If a requirement could be satisfied by a generator and you write it instead as a hand-rolled file list, you have failed. Always check first whether a generator covers the requirement.
+
+## Input
+
+The human's initial brief:
+
+```
+{{INITIAL_BRIEF}}
+```
+
+## Interview rules
+
+1. Ask ONE question at a time. Never bundle multiple questions in one turn.
+2. Prefer multiple-choice when the answer space is small. Open-ended only when the answer is genuinely open.
+3. Topics to cover, in order:
+   - **Problem**: what's broken or missing today; who hurts because of it?
+   - **Goal**: what state are we trying to reach?
+   - **In scope** / **Out of scope**: the explicit fence.
+   - **Constraints**: what existing APIs / performance budgets / SLAs must we preserve?
+   - **Success criteria**: how do we observe success?
+   - **Requirements**: numbered list (R1, R2, …). For each, identify the generator that produces it if applicable.
+   - **Open questions**: decisions you couldn't resolve in the interview.
+4. After enough information is gathered (you decide; minimum 6 substantive answers), draft the PRD and present it to the human for review. The PRD's `status` is `draft` until the human flips it to `approved`.
+
+## Output
+
+When you've gathered enough, write the PRD to `docs/work/prds/<YYYY-MM-DD>-<slug>.prd.md` with this frontmatter:
+
+```yaml
+---
+id: <YYYY-MM-DD>-<slug>
+title: <one-line title>
+type: prd
+status: draft
+author: <human's name or "human">
+elicitation-session: <this session's id>
+created: <today>
+---
+```
+
+And the body sections (in order): Problem, Goal, In scope, Out of scope, Constraints, Success criteria, Requirements (numbered), Open questions.
+
+Tell the human the file path. Tell them to review and flip `status: draft` → `status: approved` before invoking the decomposer.
+
+## Don't
+
+- Don't decompose into stories — that's the decomposer's job
+- Don't write code or tests
+- Don't skip the generator check on each requirement

.sandcastle/reviewer.prompt.md

@@ -0,0 +1,129 @@
+# Reviewer Agent
+
+You are the reviewer agent. You verify the implementer's diff against the task's AC + scope. You do NOT modify the repo.
+
+## Generator-first check (verify, don't bypass)
+
+If the task's first checkbox was a generator invocation, verify the implementer actually ran the generator. Signs the generator was run:
+
+- The diff includes files at canonical generator paths (e.g., `packages/<name>/src/feature.manifest.ts`, `packages/<name>/src/di/bind-production.ts`, etc.)
+- The generator's anchor comments (`// <gen:event-handlers>`, `// <gen:jobs>`, etc.) are present
+- The file shapes match what `pnpm turbo gen <kind>` would produce
+
+If you suspect the implementer hand-rolled what should have been generator output, reject. Tell them to delete what they wrote and run the generator.
+
+## Task
+
+```
+{{TASK_FILE_CONTENT}}
+```
+
+## Diff
+
+```
+{{DIFF}}
+```
+
+## Your checks
+
+1. **AC coverage** (acceptance criteria, not test coverage): every checkbox in the task's AC list is verifiably satisfied by the diff. Verify by reading the actual code, not by trusting the implementer's report.
+2. **Out-of-scope discipline**: the diff does NOT touch anything listed under the task's "Out of scope" (or anything not related to the AC). Over-engineering / drive-by refactors are rejection causes.
+3. **Manifest-first ordering**: if a new use case landed, the manifest was updated; tests exist; the factory was wrapped at bind time.
+4. **Conformance gates**: the diff's tests + lint + typecheck pass. (You don't run them yourself; sandcastle's CI step does. Trust the CI status, reject if it's red.)
+5. **Generator-first**: see the section above. Hand-rolled code that should have been generated is a rejection.
+6. **Fallow audit**: verify the implementer ran `pnpm fallow:audit` and it passed. If their diff increases dead exports / dupes / circular deps / complexity beyond the baseline, that's a rejection cause unless the implementer's notes explicitly justify it.
+7. **Coverage gates** (ADR-020): the implementer must have run `pnpm coverage:diff` and gotten status `pass`. The CI surfaces this as the "Coverage — diff (L1)" step; if it's red, reject. Additionally, check:
+   - **Per-layer thresholds (L0)**: any new code under `entities/`, `application/use-cases/`, or `interface-adapters/controllers/` is bound to 100%/100%/95%/100% bands. If the test run produced threshold errors, that's a rejection.
+   - **No silent allowlist expansion**: if `scripts/coverage/diff.mjs`'s `ALLOWED_GLOBS` grew, the implementer's notes must explain why (and the matching test fixture must exist in `scripts/coverage/diff.test.mjs`).
+   - **Manifest coverage band drift**: if `feature.manifest.ts` was edited, its `coverage:` section must match `DEFAULT_COVERAGE_BANDS` from `@repo/core-shared/conformance/coverage` (or carry an explicit override the implementer's notes justify).
+8. **Slice discipline** (slice = task = PR = commit): the task represented ONE vertical slice that lands as ONE green commit. Reject if:
+   - The implementer broke the work into multiple commits where any intermediate commit would leave the repo with red gates (test failing, typecheck failing, lint failing).
+   - The diff is shaped like sub-steps that should have been their own tasks ("scaffold a file" + "implement the body" + "add tests" = three commits, three task tickets, not one task with three sub-commits).
+   - The slice is incomplete — e.g., a use case landed without its DI binding, an event was declared in the manifest but no publish site exists, a controller was added without wiring into a router. The slice is whole or it's a rejection.
+
+## Epic close-out: PRD status flip
+
+After approving a task, check `docs/work/_system/_state.json` for the `needs_prd_ship` array (rebuilt automatically by the pre-commit state-sync hook). Each entry has shape:
+
+```json
+{
+  "epic": "<epic-slug>",
+  "prd": "<prd-id>",
+  "prd_status": "approved",
+  "action": "pnpm work prd-ship <prd-id> --auto-commits"
+}
+```
+
+If the task you just approved was the FINAL task of an epic (i.e., the epic transitioned to `status: done`) and that epic appears in `needs_prd_ship`, the orchestrator must run the suggested `action` command before declaring the epic closed. The `prd-ship` command:
+
+- Refuses to flip `draft` PRDs (must go through human review first)
+- Idempotent — won't double-flip an already `shipped` PRD
+- Writes `status: shipped`, `shipped: <today>`, and `shipping-commits: [...]` to the PRD frontmatter
+- Auto-derives the shipping-commits list from `git log` of the linked epic folder when `--auto-commits` is passed
+
+Include the PRD-ship outcome in your review notes when applicable.
+
+## Output format
+
+Return structured JSON:
+
+```json
+{
+  "decision": "approve" | "reject",
+  "ac_verified": [0, 1, 2],
+  "scope_violations": ["files touched that weren't in scope"],
+  "generator_skipped": false,
+  "prd_shipped": "<prd-id>" | null,
+  "notes": "..."
+}
+```
+
+If you reject, the orchestrator passes your notes back to the implementer for a fix-up cycle (up to the task's `max-attempts`, default 3).
+
+## Library-trace check
+
+Before issuing your verdict, run:
+
+```bash
+node scripts/library-decisions/check.mjs --staged-against <base-branch>
+```
+
+where `<base-branch>` is the PR's base branch (typically `main`). If the command exits non-zero, **reject** the slice: a new runtime dependency in a feature- or core-tier package is missing an approved library-decision trace. The implementer must run the evaluate-library skill (`.claude/skills/evaluate-library/SKILL.md`) and add the resulting `docs/library-decisions/*.md` trace before the slice can be approved.
+
+## CI security checks
+
+Before issuing your verdict, retrieve the CI run logs for the PR and scan for security findings:
+
+```bash
+gh run view <run-id> --log
+```
+
+where `<run-id>` is the most recent workflow run for the PR's head commit (find it via `gh pr checks <pr-number>`).
+
+**Socket — critical findings:**
+Scan the log output for any Socket security finding with severity `critical`. These appear in the "Socket Security" check step output. If any `critical` finding is present:
+
+- **Reject** the slice.
+- Name the specific finding (package name + finding label) in your notes.
+- Cite the failure-mode hierarchy in `docs/guides/ci-security.md` for remediation guidance.
+
+Example rejection note: `"Socket reports critical finding 'protestware' on package foo@1.2.3. See docs/guides/ci-security.md for the failure-mode hierarchy."`
+
+**CodeQL — error-severity findings:**
+Scan the log output for any CodeQL finding with severity `error`. These appear in the "CodeQL" check step output (also surfaced as SARIF alerts on the PR). If any `error`-severity finding is present:
+
+- **Reject** the slice.
+- Name the specific finding (rule ID + file + line) in your notes.
+- Cite the failure-mode hierarchy in `docs/guides/ci-security.md` for remediation guidance.
+
+Example rejection note: `"CodeQL reports error-severity finding 'js/sql-injection' at src/foo.ts:42. See docs/guides/ci-security.md for the failure-mode hierarchy."`
+
+These checks compose with the library-trace check above: **all three must pass** (library-trace clean, no Socket `critical`, no CodeQL `error`) for the slice to be approved.
+
+## Signal completion (required)
+
+After you have returned the structured JSON decision, emit the literal string `<promise>COMPLETE</promise>` as the final line of your response.
+
+Sandcastle uses this marker to stop the iteration loop. Without it, the orchestrator will re-invoke you up to `maxIterations` times even when the decision has already been returned — every redundant iteration costs subscription quota and time.
+
+Emit the marker for BOTH `approve` and `reject` decisions — the decision is itself a terminal output, regardless of which way it went. Do NOT emit the marker if you still need to read more of the diff, run a tool, or otherwise have unfinished work.

.socket.json

@@ -0,0 +1,8 @@
+{
+  "issueRules": {
+    "critical": "error",
+    "high": "warn",
+    "medium": "ignore",
+    "low": "ignore"
+  }
+}

CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog — template-vertical
+
+All notable changes to this template at the root level. Per-feature changelogs live at `packages/<feature>/CHANGELOG.md`.
+
+This file is maintained by [release-please](https://github.com/googleapis/release-please) — do not edit manually. Edits land via the rolling release PR triggered by merges to `main`. See [ADR-021](./docs/decisions/adr-021-versioning-and-changelog.md) for the architecture and [`docs/guides/releasing.md`](./docs/guides/releasing.md) for the day-to-day reference.
+
+## 0.1.0 (2026-05-13)
+
+### Initial baseline
+
+- Hybrid versioning established (ADR-021): root template + 5 feature packages each version independently.
+- Conventional Commits required for every commit (CLAUDE.md Key Conventions).
+- Coverage architecture shipped (ADR-020): L0 vitest thresholds, L1 `pnpm coverage:diff`, L2 `pnpm coverage:aggregate`, L3 `pnpm mutate`.
+- Manifest-driven coverage bands in every `feature.manifest.ts`.
+- Sandcastle agent orchestration (ADR-019) + PRD-lifecycle automation (`pnpm work prd-ship`).
+- 5 features (auth / blog / media / marketing-pages / navigation) all green on declared L0 bands.
+
+Future entries appear above this section as release-please assembles them from conventional commits since the last release.

CLAUDE.md

@@ -3,22 +3,140 @@
 ## Quick Start
 
 ```bash
-pnpm install          # Install all dependencies
-pnpm dev              # Start all dev servers
-pnpm build            # Build all packages
-pnpm test             # Run all tests
-docker compose up -d  # Start PostgreSQL
+pnpm install                # Install + auto-wire husky pre-commit hooks
+pnpm dev                    # Start all dev servers
+pnpm build                  # Build all packages
+pnpm test                   # Run all tests
+pnpm typecheck              # TypeScript across all packages
+pnpm lint                   # ESLint (incl. 15 conformance/* rules)
+pnpm conformance            # Cross-feature event closure
+pnpm fallow                 # Whole-codebase: dead exports, dupes, complexity
+pnpm fallow:audit           # AI-change audit (run before commits)
+pnpm coverage:aggregate     # Merge per-package lcovs -> coverage/lcov.info + summary.json (L2)
+pnpm coverage:diff          # Cover-the-diff gate; JSON to stdout (L1, ADR-020)
+pnpm mutate                 # Stryker mutation testing on entities + use-cases (L3, on-demand)
+pnpm turbo boundaries       # Workspace dependency graph
+pnpm work status            # docs/work/ epic + story state
+pnpm work next              # Next ready story
+pnpm work dispatch          # Print next dispatch plan (use --execute to invoke sandcastle)
+pnpm turbo gen feature      # Scaffold a new feature package
+pnpm turbo gen event        # Scaffold an event contract or handler
+pnpm turbo gen job          # Scaffold a background job
+pnpm turbo gen realtime     # Scaffold a realtime channel or handler
+pnpm turbo gen reader       # Scaffold a cross-feature reader
+pnpm turbo gen core-package # Scaffold an optional core package
+pnpm turbo gen core-ui-component # Scaffold an atomic-design component
+docker compose up -d        # Start PostgreSQL
 ```
 
+**First time?** Read [`docs/guides/runbook.md`](./docs/guides/runbook.md) end-to-end.
+
+## TDD
+
+```bash
+pnpm test --watch --filter @repo/<feature>   # watch one feature
+pnpm test -- --coverage                      # full run with coverage
+pnpm test:stories                            # Storybook smoke tests
+pnpm test:e2e                                # Playwright e2e
+```
+
+See `docs/guides/tdd-workflow.md` for the full cycle.
+
 ## Project Overview
 
-Turborepo + pnpm monorepo based on Clean Architecture (Uncle Bob / Lazar Nikolov). Supports Next.js and TanStack Start as frontend frameworks, Payload CMS for content management, and comprehensive agent-optimized documentation.
+Turborepo + pnpm monorepo organized by vertical features. Each feature (`auth`, `blog`, `media`, `marketing-pages`, `navigation`) owns its Clean Architecture layers. Must-have core packages (`core-shared`, `core-cms`, `core-api`) provide foundation; five optional core packages (`core-realtime`, `core-events`, `core-trpc`, `core-ui`, `core-audit`) scaffold on demand via `pnpm turbo gen core-package <name>` (see `docs/architecture/template-tiers.md`). Two tooling packages (`core-eslint`, `core-typescript`) provide shared configs. Workspace boundaries are enforced by ESLint (lint-time) and Turborepo (build-graph time). Supports Next.js and TanStack Start as frontend frameworks, Payload CMS for content management, and comprehensive agent-optimized documentation.
 
 ## Read First
 
-- `AGENTS.md` — Monorepo structure, dependency flow, hard rules
-- `docs/architecture/overview.md` — High-level architecture
-- `docs/guides/adding-a-feature.md` — End-to-end walkthrough
+- `docs/glossary.md` — **Canonical vocabulary** for the monorepo. Resolves "what does X mean here?" for every cross-cutting term (feature, use case, manifest, conformance, slice, dispatch, etc.). Shared between humans and agents.
+- `AGENTS.md` — Package map, boundary rules, per-package conventions
+- `docs/architecture/overview.md` — High-level architecture and package responsibilities
+- `docs/architecture/vertical-feature-spec.md` — Design spec with rationale and decision log
+- `docs/guides/scaffolding-a-feature.md` — `turbo gen feature` reference (fast path; prefer this over the manual walkthrough)
+- `docs/guides/adding-a-feature.md` — End-to-end new feature walkthrough (manual path; for cases the generator's scope doesn't cover)
+- `docs/guides/events-and-jobs.md` — publish/consume/schedule cookbook (cross-feature events + background jobs; _requires `gen core-package events`_)
+- `docs/guides/realtime.md` — Socket.IO channels, broadcasts, handlers (_requires `gen core-package realtime`_)
+- `docs/guides/audit-and-compliance.md` — DPA-compliant audit logging cookbook (_requires `gen core-package audit`_)
+- `docs/guides/coverage.md` — 4-layer coverage cookbook (L0 vitest thresholds, L1 `pnpm coverage:diff`, L2 aggregate, L3 mutation; ADR-020)
+- `docs/guides/releasing.md` — release-please workflow: how Conventional Commits become tagged versions + per-package CHANGELOGs (ADR-021)
+- `docs/architecture/template-tiers.md` — must-have vs optional packages and how to scaffold the optionals
+- `docs/guides/building-feature-ui.md` — Feature UI components, hooks, data fetching (tRPC + React Query), SSR prefetch/hydration, seed data, DI wiring
+- `docs/guides/compliance-overview.md` — hub for operator compliance obligations: GDPR, cookie consent, DSR, and pre-launch checklist
+
+## Conformance system
+
+Every feature has a `src/feature.manifest.ts` declaring its use cases, audits, publishes, consumes, reads (cross-feature reader deps), required cores, `rateLimit?: RateLimitBudget[]` (when applicable, for per-use-case rate-limit budgets), and (when applicable) `requiresConsent: ConsentCategory[]` for features that gate behaviour behind user consent. Drift is caught at five latencies:
+
+| Layer                                  | Latency | Catches                                                                                                     |
+| -------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
+| **TypeScript brands**                  | 0s      | forgotten `withSpan` / `withCapture` / `withAudit` at bind time                                             |
+| **ESLint rules**                       | <1s     | manifest ↔ code drift; undeclared `bus.publish` / `auditLog.record`; missing manifest; missing sibling test |
+| **Boot assertion** (`pnpm dev`)        | ~3s     | binding without required brand at runtime; manifest edited without rebinder                                 |
+| **CI drift gate** (`pnpm conformance`) | ~120s   | orphan event consumers across features                                                                      |
+| **Fallow** (`pnpm fallow`)             | ~30–60s | dead exports / unused files; duplicate code; circular deps; complexity hotspots; AI-change audit drift      |
+
+The sixteen conformance ESLint rules: `feature-must-have-manifest` (error), `usecase-must-have-test-file` (error), `required-cores-installed` (error), `usecase-must-be-wired` (error), `no-undeclared-event-publish` (warn), `no-undeclared-audit` (warn), `no-undeclared-analytics-event` (warn), `no-undeclared-reader` (warn), `pii-declaration-must-be-complete` (warn), `component-must-have-story` (warn), `component-must-have-test` (warn), `atomic-tier-import-direction` (warn), `no-undeclared-consent-check` (warn), `no-undeclared-rate-limit` (warn), `entity-must-have-test` (warn), `no-relative-parent-import-in-tests` (warn). Fallow runs as a fifth layer, post-ESLint, whole-codebase.
+
+See `docs/architecture/agent-first-workflow-and-conformance.md` for the full design and `docs/guides/conformance-quickref.md` for the day-to-day reference.
+
+### Sibling architecture: coverage (ADR-020)
+
+Coverage runs in parallel to the 5-gate conformance system above — same multi-latency philosophy, different signal. Each feature's `feature.manifest.ts` declares a `coverage.bands` section that vitest (test-time), `pnpm coverage:diff` (CI/agent-loop), and `pnpm mutate` (nightly) all read from. Four layers:
+
+| Layer                              | Catches                                                             | Surface                                                       |
+| ---------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------- |
+| **L0** Per-layer vitest thresholds | Drift below declared bands (entities/use-cases/controllers at 100%) | `pnpm test -- --coverage`                                     |
+| **L1** Diff coverage               | Changed line not exercised by tests                                 | `pnpm coverage:diff` — CI-gated on PRs + dispatch post-task   |
+| **L2** Aggregate trend             | Codebase coverage drifted over time                                 | `pnpm coverage:aggregate` → committed `coverage/summary.json` |
+| **L3** Mutation testing            | Tests that exist + execute the code but assert nothing              | `pnpm mutate` — on-demand + nightly GH Action                 |
+
+See `docs/guides/coverage.md` for the cookbook and ADR-020 for the full rationale. Agents running in sandcastle: run `pnpm coverage:diff` before reporting `complete` — the implementer and reviewer prompts enforce this.
+
+## Key Conventions
+
+- **Conventional Commits (non-negotiable)** — Every commit message MUST follow the [Conventional Commits](https://www.conventionalcommits.org/) spec: `<type>(<scope>): <imperative subject>` (≤72 chars). Types: `feat | fix | docs | style | refactor | test | chore | perf | ci | build | revert`. Use `!` after type/scope for breaking changes. Body explains WHY if non-obvious. Examples: `feat(auth): hash password before persisting`, `test(blog): assert article not found error`, `refactor(docs)!: consolidate scaffolding into guides`. The sandcastle implementer + reviewer prompts both enforce this; agents authoring commits autonomously MUST honor it. Commits become versions + changelog entries automatically via release-please (ADR-021 / `docs/guides/releasing.md`).
+- **Versioning is hybrid (ADR-021)** — Root template (`template-vertical`) + 5 feature packages (`@repo/{auth,blog,media,marketing-pages,navigation}`) each version independently from `0.1.0`. release-please reads Conventional Commits since the last tag and opens a rolling release PR on every merge to main; merging it cuts per-package tags (`template-v0.2.0`, `auth-v0.1.1`, etc.) + GitHub releases. **Bump targeting is by commit path** — files under `packages/<feature>/**` bump that feature; cross-cutting paths (`docs/`, `scripts/`, `.github/`, root configs) bump the root. Pre-1.0 policy: `feat:` → patch, `feat!:` → minor.
+- **Relative imports in `src/`** — Source files use relative paths (`../repositories/...`), not `@/` alias
+- **`@/` alias in tests** — Test files (`*.test.ts`) use `@/` to import from `src/`
+- **`vitest.config.ts`** — Every package must define `resolve.alias: { "@": path.resolve(__dirname, "./src") }`
+- **`tsconfig.json` rootDir** — Set `"rootDir": "."` so TypeScript finds both `src/` and test files
+- **File layout convention** — Entities live at `entities/models/<x>.ts`; errors at `entities/errors/<domain>.ts` + `entities/errors/common.ts`; mock siblings use the `.mock.ts` suffix (`<x>.repository.mock.ts`); real repository impls drop the `payload-` prefix (`<x>.repository.ts`); interface filenames are dot-separated (`<x>.repository.interface.ts`)
+- **Factory-function use cases & controllers** — Every use case and controller is `(deps) => async (input) => result`; each exports `export type I*UseCase = ReturnType<typeof xUseCase>` (and the analogous `I*Controller`); one controller per use case (no multi-method controllers)
+- **DI uses `.toDynamicValue()` for factories** — `bind<IXUseCase>(SYMBOL).toDynamicValue((ctx) => xUseCase(ctx.container.get(...)))`; mocks remain the default binding
+- **Tests inject mocks directly** — Construct `MockXRepository` and pass into the factory: `signInUseCase(mockUsers, mockAuth)(input)`. No container rebinding in unit tests
+- **Schemas in the use-case file** — Every use case exports `xInputSchema` (a `z.ZodObject` with `.strict()`; `z.object({}).strict()` for void inputs) and, for non-void use cases, `xOutputSchema`. Types: `XInput = z.infer<typeof xInputSchema>` and `XOutput`. Use case body ends with `xOutputSchema.parse(result)` before returning (runtime guarantee against malformed repository data)
+- **Controllers receive `unknown` + presenter** — Controllers `safeParse(xInputSchema)` from the use-case file and throw `InputParseError` on failure. Non-void controllers define a top-level `function presenter(value: XOutput)` and return `Promise<ReturnType<typeof presenter>>` (identity is fine — `return value`); void controllers return `Promise<void>` with no presenter
+- **Feature-scoped tRPC error mapping** — Each feature has `integrations/api/procedures.ts` exporting `xProcedure = t.procedure.use(defineErrorMiddleware([[Ctor, "TRPC_CODE"], ...]))` from `@repo/core-shared/trpc/define-error-middleware`. Routers use `xProcedure.input(xInputSchema)` — schemas are imported from the use-case file, never redefined inline. `core-shared` never enumerates feature error classes
+- **Public surface split** — Feature root (`.`) exports contracts only: types, errors, schemas, IUseCase / IController aliases, router type, constants. UI artifacts (hooks, components, query builders) live behind `./ui` (`src/ui/index.ts`). Apps import hooks/components from `@repo/<feature>/ui`, schemas/types from `@repo/<feature>`
+- **Feature UI owns its data fetching** — Each feature's `src/ui/hooks/` contains `"use client"` hooks that wrap `useTRPC` + `useSuspenseQuery`. Connected components in `src/ui/components/` call these hooks. App pages prefetch via `appRouter.createCaller({})` and hydrate via `HydrationBoundary` + `dehydrate` + `setQueryData`. See `docs/guides/building-feature-ui.md`
+- **Payload repositories via constructor** — Feature packages receive Payload config at constructor time, not as a direct dependency
+- **Three binding modes per feature** — Each feature exports two binders: `./di/bind-production` (real Payload) and `./di/bind-dev-seed` (populated mock). The app's `bindAll()` dispatcher in `apps/web-next/src/server/bind-production.ts` picks one by env: `USE_DEV_SEED="true"` → dev seed; `NODE_ENV="production"` → production; otherwise → dev seed (developer default so `pnpm dev` boots without Payload). Dev seed lives in `src/__seeds__/dev.ts` as a lazy `buildDev<Entities>()` function that uses the feature's existing factory
+- **Binders take a `ctx` arg from `core-shared/di`** — `bindProductionX(ctx: BindProductionContext)` for production binders; `bindDevSeedX(ctx: BindContext)` for dev-seed. Required fields: `tracer`, `logger`, plus `config` for production. Optional fields: `bus`, `queue`, `realtime`, `realtimeRegistry` (correspond to optional core packages — guard with `?.` or `if (bus) { ... }` when used; use-case signatures should accept the protocol type when they only need protocol methods, not the full concrete interface). Aggregator builds one ctx object and passes it to all feature binders
+- **App bootstrap** — Each app calls `bindAll()` from a server entry point (page server component, route handler) before resolving any feature controller. The dispatcher is idempotent
+- **Instrumentation lives in `core-shared/instrumentation/`** — Three interfaces (`ITracer`, `ILogger`, `IMetrics`), three implementation pairs (`Noop*`, `Otel*`, and `Recording*` from `core-testing`). The OTel SDK is the substrate; Sentry is wired as the exporter via `@sentry/opentelemetry`. Feature packages MUST NOT import `@opentelemetry/sdk-*` or `@sentry/*` directly (ESLint-enforced); the vendor-neutral `@opentelemetry/api` family is the import surface for advanced cases (ADR-017)
+- **Spans + capture composed at DI bind time** — Use cases + controllers are wrapped at DI bind time in this order (outermost → innermost): `withSpan → withCapture → withAudit → withAnalytics → withConsent → factory(deps)`. Apply `withAudit` when the manifest declares `audits`, `withAnalytics` when it declares `analyticsEvents`, `withConsent` when it declares `requiresConsent`. `withSpan` is always outermost so an errored span's timing reflects the capture-and-rethrow. Repository methods are different — they call `this.tracer.startSpan(...)` and `this.logger.captureException(...)` inline per method because they own per-call attributes
+- **Capture at throw sites only, with double-report guard** — Repos capture infra errors inline; use cases + controllers capture via `withCapture` at bind time; `defineErrorMiddleware` never captures. Each error gets a non-enumerable `__sentryReported` flag the first time it's captured; `withCapture`, `OtelLogger`, and `RecordingLogger` all bail if the flag is set, so a bubbled error surfaces exactly once with the inner-most layer's tags (helper at `core-shared/instrumentation/reported-flag.ts`)
+- **PII handling is non-negotiable** — `sendDefaultPii: false` everywhere (CI grep gate); replay default-masks all text/inputs/media (allowlist starts empty); `setUser({ id })` only — no email/username; server-side PII scrubbing happens at the OTel processor layer (`PiiScrubSpanProcessor` + `PiiScrubLogRecordProcessor`) before any exporter sees the data (ADR-017 §7)
+- **Three apps, three Sentry projects** — `WEB_NEXT_SENTRY_DSN`, `CMS_SENTRY_DSN`, `WEB_TANSTACK_SENTRY_DSN`. Browser DSNs use `NEXT_PUBLIC_` (web-next) and `VITE_` (web-tanstack) prefixes
+- **Instrumentation binding is orthogonal to repo binding** — `bindAll()`'s Rule 0 (DSN → OTel+Sentry vs Noop) is independent of `USE_DEV_SEED` / `NODE_ENV`. Run `pnpm dev` with `WEB_NEXT_SENTRY_DSN` set to test the integration locally
+- **Cross-feature events go through `IEventBus` (E0)** — In-feature reactions are direct use-case calls, not bus publishes. The bus is for _crossing_ feature boundaries (e.g. `auth` → `marketing-pages` welcome email)
+- **Event contracts are public; handlers are private (E1)** — Publisher's `events/<x>.event.ts` is exported from the feature root barrel. Consumer's `events/handlers/on-<publisher>-<event>.handler.ts` is never re-exported (ESLint-enforced via `core-eslint/rules/no-handler-reexport`)
+- **Jobs are for _deferred_ work, not abstraction (J0)** — Synchronous code stays synchronous. A job exists only when something must run off the request path (latency, retries, cron). Feature packages enqueue via `IJobQueue` only — direct `payload.jobs.queue()` is ESLint-blocked outside `core-shared/jobs/`
+- **Realtime is for state delivery, not for replacing tRPC (R0)** — Persistent request/response operations belong on tRPC procedures. Use realtime when the server needs to push without a request or the data is too high-frequency for HTTP
+- **Realtime channel descriptors are exported; handlers are private (R1)** — A feature's `realtime/<name>.channel.ts` is re-exported from the root barrel; `realtime/handlers/*.handler.ts` is wired only in bind-\* files and never re-exported (ESLint-enforced via `no-realtime-handler-reexport`)
+- **`socket.io` lives in `@repo/core-realtime` only (R2)** — Feature packages MUST NOT import `socket.io` or `socket.io-client`. ESLint rule `no-direct-socket-io` enforces this; allowlist covers `core-realtime/src/socket-io-*.ts` and `apps/*/server.ts`
+- **Cross-feature domain queries go through readers (Q0)** — When a use case needs another vertical's domain-evaluated answer on the request path (e.g., permission check), use a reader (`I<Feature>Reader`). For raw data joins, use Payload `relationTo`. For reactions/side effects, use the event bus
+- **Reader contracts are public; implementations are private (Q1)** — The owning feature exports `I<Feature>Reader` from `./reader` subpath (`integrations/readers/`). The implementation (`<Feature>Reader`) is internal, constructed by the binder. Consumers import the type only
+- **Readers are strictly read-only; cross-feature writes go through events (Q2)** — A reader may only wrap use cases declared `mutates: false`. Enforced by `ReadOnly<F>` brand at compile time and `assertReaderPurity` at boot time
+- **Reader cycles are a design error (Q3)** — If Feature A reads from Feature B and vice versa, the boundaries are wrong. Break via: (a) UI composition at app layer, (b) event for one direction, (c) merge the features
+- **Readers wrap existing use cases, not repositories** — The reader is a thin facade; if the domain logic doesn't exist as a use case yet, create the use case first (manifest-first). No `MockReader` needed — same class works in dev-seed because the use cases beneath it are backed by mock repos
+- **Manifest `reads` field** — Use cases that query another feature's reader declare `reads: ["<feature>"]` in `feature.manifest.ts`. Verified by `assertFeatureConformance` at boot and `no-undeclared-reader` ESLint rule
+- **Binders return readers; `bindAll()` threads them** — `bindProductionAuth(ctx)` returns `{ reader: IAuthReader }`. `bindAll()` passes it: `bindProductionBlog(ctx, { authReader: authResult.reader })`. Ordering in `bindAll()` is explicit — owning feature first, consumers after
+- **Manifest-first ordering** — for any new use case, the workflow is **(1) manifest entry** → **(2) contracts** (`xInputSchema`, `xOutputSchema`, `IXUseCase`) → **(3) tests (red)** → **(4) implementation (green)**. The generator emits the manifest + a self-asserting `bind-production.ts` so new features are conformance-compliant by default
+- **Self-asserting `bindProductionX(ctx)`** — every feature's bind-production calls `assertFeatureConformance(container, manifest, symbols, ctx)` at its tail. `pnpm dev` refuses to boot on drift
+- **`pnpm conformance`** — cross-feature event-closure and reader-closure check; fails CI on orphan consumers or unresolvable `reads` entries
+- **New runtime dependencies require a library trace** — adding a runtime dependency to a feature- or core-tier package requires a trace at `docs/library-decisions/<date>-<name>.md` produced by the `/evaluate-library` skill; see ADR-022 and `docs/guides/adding-a-library.md`
+- **CI security + supply-chain enforcement** — Renovate for bumps + Action SHA pinning, Socket for supply-chain behavior, weekly trace revalidation, CodeQL + audit signatures + gitleaks. See ADR-023 + `docs/guides/ci-security.md`
 
 ## MCP Servers
 
@@ -28,10 +146,10 @@ Storybook MCP available at `http://localhost:6006/mcp` — use `list-all-documen
 
 ## Key Ports
 
-| Service | Port |
-|---|---|
-| Next.js | 3000 |
-| Payload CMS | 3001 |
+| Service        | Port |
+| -------------- | ---- |
+| Next.js        | 3000 |
+| Payload CMS    | 3001 |
 | TanStack Start | 3002 |
-| PostgreSQL | 5432 |
-| Storybook | 6006 |
+| PostgreSQL     | 5432 |
+| Storybook      | 6006 |

README.md

@@ -0,0 +1,114 @@
+# Clean Architecture Monorepo Template
+
+Turborepo + pnpm monorepo organised by vertical features, with an **agent-first workflow** and **five conformance gates**.
+
+This template is built for **agent-driven development**. [Sandcastle](https://github.com/mattpocock/sandcastle) is the orchestration substrate; `pnpm work dispatch` is the entry point. See [ADR-019](./docs/decisions/adr-019-sandcastle-for-agent-orchestration.md) for the decision rationale and [`docs/guides/runbook.md`](./docs/guides/runbook.md) for end-to-end usage.
+
+## Start here
+
+Read [`docs/guides/runbook.md`](./docs/guides/runbook.md) — day-1 onboarding (prerequisites, env vars, daily commands, troubleshooting, **Using Sandcastle for agent dispatch**).
+
+## Quick reference
+
+```bash
+pnpm install           # Install + auto-wire husky pre-commit hooks
+pnpm dev               # All dev servers (web-next:3000, cms:3001, web-tanstack:3002, storybook:6006)
+pnpm test              # All tests
+pnpm typecheck         # TypeScript across all packages
+pnpm lint              # ESLint (incl. 8 conformance/* rules)
+pnpm conformance       # Cross-feature event closure
+pnpm fallow            # Whole-codebase: dead exports, dupes, complexity
+pnpm turbo boundaries  # Workspace dependency graph
+pnpm work status       # docs/work/ epic + story state
+docker compose up -d   # Start PostgreSQL
+```
+
+## Sandcastle setup (one-time)
+
+Required only if you'll use `pnpm work dispatch --execute` or `pnpm work decompose <id> --execute` (agent dispatch). The dispatch loop runs the implementer / reviewer / decomposer agents inside an isolated Docker sandbox; the image is built once locally.
+
+```bash
+# 1. Ensure Docker is running
+docker info >/dev/null
+
+# 2. Build the sandcastle image (reads .sandcastle/Dockerfile)
+pnpm exec sandcastle docker build-image
+# Tags as: sandcastle:template-vertical (derived from the root package.json name)
+
+# 3. Pick ONE auth path:
+#    (a) Recommended — Claude Pro/Max subscription:
+claude login           # one-time; ~/.claude/ becomes the auth source
+#    (b) Fallback — API key:
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+**macOS users**: subscription auth needs an extra step. Claude Code stores credentials in the macOS Keychain by default, so the host's `~/.claude/` directory has no `.credentials.json` for the sandbox to read. Two workarounds:
+
+```bash
+# (preferred for macOS subscription users) extract keychain -> file once:
+security find-generic-password -s "Claude Code-credentials" -a "$USER" -w \
+  > ~/.claude/.credentials.json
+chmod 600 ~/.claude/.credentials.json
+# Trade-off: credentials now live as a plaintext file at the path; refresh
+# when the token expires (re-run the same one-liner). The file is in your
+# home directory — chmod 600 + your home permissions are the protection.
+
+# OR fall back to API key — no host changes needed:
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+Linux + WSL users with `claude login` write `~/.claude/.credentials.json` directly; nothing extra needed.
+
+After the image exists, dispatch flows work without further setup:
+
+```bash
+pnpm work dispatch                                    # print plan (safe anywhere)
+pnpm work dispatch --execute                          # actually dispatch via sandcastle
+pnpm work decompose <prd-id>                          # print decompose plan
+pnpm work decompose <prd-id> --execute                # decompose an approved PRD
+```
+
+To rebuild the image after changing `.sandcastle/Dockerfile`:
+
+```bash
+pnpm exec sandcastle docker remove-image
+pnpm exec sandcastle docker build-image
+```
+
+See [`docs/guides/runbook.md` → Using Sandcastle](./docs/guides/runbook.md#using-sandcastle-for-agent-dispatch) for the full dispatch lifecycle, auth modes, and troubleshooting.
+
+## Documentation map
+
+- **[`docs/guides/runbook.md`](./docs/guides/runbook.md)** — start here
+- **[`CLAUDE.md`](./CLAUDE.md)** — full conventions reference
+- **[`AGENTS.md`](./AGENTS.md)** — package map + boundary rules
+- **[`docs/guides/conformance-quickref.md`](./docs/guides/conformance-quickref.md)** — manifest + 5-gate daily reference
+- **[`docs/architecture/agent-first-workflow-and-conformance.md`](./docs/architecture/agent-first-workflow-and-conformance.md)** — full design
+- **[`docs/architecture/feature-conformance-explainer.html`](./docs/architecture/feature-conformance-explainer.html)** — interactive explainer
+
+## Scaffolding
+
+```bash
+pnpm turbo gen feature <name>             # Scaffold a feature (manifest + contracts + tests)
+pnpm turbo gen event                      # Event contract or handler (requires gen core-package events)
+pnpm turbo gen job                        # Background job
+pnpm turbo gen realtime                   # Realtime channel (requires gen core-package realtime)
+pnpm turbo gen core-package <name>        # Optional core: events / realtime / trpc / ui / audit
+pnpm turbo gen core-ui-component <name>   # Atomic-design component
+```
+
+**Generator-first is non-negotiable** — hand-rolled feature/event/job/realtime/component code is rejected by reviewer agents and may fail the CI scaffold-drift check.
+
+## Optional packages
+
+Five core packages scaffold on demand:
+
+```bash
+pnpm turbo gen core-package realtime  # Socket.IO realtime layer (ADR-016)
+pnpm turbo gen core-package events    # Cross-feature events + Payload jobs (ADR-015)
+pnpm turbo gen core-package trpc      # tRPC server setup
+pnpm turbo gen core-package ui        # Design system
+pnpm turbo gen core-package audit     # DPA-compliant audit logging (ADR-018)
+```
+
+See [`docs/architecture/template-tiers.md`](./docs/architecture/template-tiers.md) for the full tier list.

apps/cms/AGENTS.md

@@ -1,108 +1,97 @@
-# apps/cms -- Payload CMS Admin Shell
+# AGENTS.md — apps/cms
+
+**Thin shell** hosting the Payload CMS admin panel via Next.js. All CMS configuration (collections, globals, hooks, access control, `payload.config.ts`) lives in `@repo/core-cms`, which aggregates collections from feature packages.
 
 ## Purpose
 
-**THIN SHELL ONLY** -- this app exists solely to serve the Payload CMS admin panel via Next.js. All CMS logic (collections, globals, hooks, access control, `payload.config.ts`) lives in `@repo/cms-core`. This app contains no custom CMS code beyond Next.js routing boilerplate that Payload generates automatically.
+This app exists solely to serve the Payload Admin UI. It contains no custom CMS code beyond Next.js routing boilerplate. All business knowledge lives in feature packages (`@repo/auth`, `@repo/blog`, etc.), which export their collections/globals via subpath exports (`.../cms`). `@repo/core-cms` composes them into a single Payload config.
 
 ## Port: 3001
 
 ```bash
-pnpm dev --filter @repo/cms   # http://localhost:3001/admin
+docker compose up -d postgres    # Start PostgreSQL on port 5432
+pnpm dev --filter @repo/cms      # http://localhost:3001/admin
 ```
 
-Requires PostgreSQL running first:
-
-```bash
-docker compose up -d postgres   # Starts PostgreSQL on port 5432
-```
-
-## Hard Rules
-
-- **NEVER** add collections, globals, hooks, or access control in this app -- put them in `@repo/cms-core`
-- **NEVER** import from `@repo/core/infrastructure`
-- **NEVER** modify auto-generated files (marked with "THIS FILE WAS GENERATED AUTOMATICALLY BY PAYLOAD")
-- All CMS configuration changes go in `packages/cms-core/`
-
 ## Key Files
 
 | File | Purpose |
 |---|---|
-| `next.config.mjs` | Next.js config wrapped with `withPayload()` from `@payloadcms/next` |
+| `next.config.mjs` | Minimal config wrapped with `withPayload()` from `@payloadcms/next` |
 | `tsconfig.json` | TypeScript config with `@payload-config` path alias |
 | `src/app/(payload)/layout.tsx` | Auto-generated Payload root layout (DO NOT MODIFY) |
 | `src/app/(payload)/admin/[[...segments]]/page.tsx` | Auto-generated catch-all admin page (DO NOT MODIFY) |
-| `src/app/(payload)/admin/[[...segments]]/not-found.tsx` | Auto-generated 404 page (DO NOT MODIFY) |
 | `src/app/(payload)/importMap.js` | Auto-generated Payload import map (DO NOT MODIFY) |
-| `src/app/(payload)/custom.scss` | Custom SCSS overrides for admin panel styling |
+
+## Hard Rules
+
+- **NEVER** add collections, globals, or hooks in this app — put them in feature packages
+- **NEVER** create custom CMS logic here — use `@repo/core-cms`
+- **NEVER** modify auto-generated files under `src/app/(payload)/`
+- All Payload config changes go in `packages/core-cms/src/payload.config.ts`
 
 ## @payload-config Alias
 
-The `tsconfig.json` defines a path alias that points to the config in `@repo/cms-core`:
+The `tsconfig.json` points to `@repo/core-cms`:
 
 ```json
 {
   "compilerOptions": {
     "paths": {
-      "@payload-config": [
-        "../../packages/cms-core/src/payload.config.ts"
-      ]
+      "@payload-config": ["../../packages/core-cms/src/payload.config.ts"]
     }
   }
 }
 ```
 
-When Payload or auto-generated files import `@payload-config`, it resolves to `packages/cms-core/src/payload.config.ts`. This is how the thin shell delegates all configuration to `@repo/cms-core`.
+When Payload imports `@payload-config`, it resolves to the composed config from `@repo/core-cms`, which in turn imports feature collections.
 
-## next.config.mjs
+## Composition flow
 
-The Next.js config is minimal -- just the `withPayload` wrapper:
-
-```javascript
-import { withPayload } from "@payloadcms/next/withPayload";
-
-/** @type {import('next').NextConfig} */
-const nextConfig = {};
-
-export default withPayload(nextConfig);
 ```
+Feature 1 (@repo/blog)
+  └─ src/integrations/cms/collections/articles.ts
+      └─ exported as ./cms
 
-`withPayload()` adds the necessary webpack aliases, module resolution, and middleware for Payload to work within Next.js.
+Feature 2 (@repo/auth)
+  └─ src/integrations/cms/collections/users.ts
+      └─ exported as ./cms
 
-## Auto-Generated Files
+Feature 3 (@repo/navigation)
+  └─ src/integrations/cms/globals/header.ts
+      └─ exported as ./cms
 
-The files under `src/app/(payload)/` are generated by Payload and should NOT be manually edited:
+Core CMS (@repo/core-cms)
+  └─ src/payload.config.ts
+      imports all feature /cms exports
+      calls buildConfig({ collections, globals })
 
-- **`layout.tsx`** -- Wraps the admin panel with `RootLayout` from `@payloadcms/next/layouts`, injects config and importMap
-- **`admin/[[...segments]]/page.tsx`** -- Catch-all route that renders `RootPage` from `@payloadcms/next/views`
-- **`admin/[[...segments]]/not-found.tsx`** -- 404 handler using `NotFoundPage` from `@payloadcms/next/views`
-- **`importMap.js`** -- Maps Payload component paths for the admin UI
-
-If you need to regenerate these files, Payload will do so automatically during dev/build.
+This app (@repo/cms)
+  └─ src/app/(payload)/layout.tsx
+      loads config from @payload-config
+      Payload CLI auto-generates admin routes
+```
 
 ## Type Generation
 
-To regenerate Payload TypeScript types after changing collections/globals:
+After adding/modifying collections in any feature's `/cms` folder:
 
 ```bash
 cd apps/cms && pnpm generate:types
-# Equivalent to: payload generate:types
-# Output goes to: packages/cms-core/src/payload-types.ts
+# Regenerates packages/core-cms/src/generated-types.ts
 ```
 
 ## Dependencies
 
 | Dependency | Purpose |
 |---|---|
-| `@repo/cms-core` | All Payload configuration (collections, globals, hooks, config) |
-| `@payloadcms/next` | Next.js integration for Payload (withPayload, admin UI views) |
-| `@payloadcms/ui` | Payload admin panel React components |
+| `@repo/core-cms` | Payload config + buildConfig |
+| `@payloadcms/next` | Next.js integration for Payload |
 | `payload` | Payload CMS core |
 | `next` | Next.js 15 framework |
-| `react` / `react-dom` | React 19 runtime |
-| `sharp` | Image processing for Payload uploads |
+| `sharp` | Image processing |
 
 ## Cross-References
 
-- **ALL CMS configuration:** `packages/cms-core/` -- see `packages/cms-core/AGENTS.md`
-- **CMS client for querying data:** `packages/cms-client/` -- see `packages/cms-client/AGENTS.md`
-- **Core business logic:** `packages/core/` -- see `packages/core/AGENTS.md`
+- **Feature collections:** each feature's `src/integrations/cms/` folder
+- **CMS composition:** `packages/core-cms/AGENTS.md`

apps/cms/eslint.config.js

@@ -0,0 +1,11 @@
+import baseConfig from "@repo/core-eslint/base";
+
+export default [
+  ...baseConfig,
+  {
+    files: ["next-env.d.ts"],
+    rules: {
+      "@typescript-eslint/triple-slash-reference": "off",
+    },
+  },
+];

apps/cms/instrumentation.ts

@@ -0,0 +1,23 @@
+// apps/cms/instrumentation.ts
+// CMS is server-only (Payload admin UI). No instrumentation-client.ts here —
+// Payload admin UI bundling is opinionated and the public DSN flow is
+// out-of-scope per spec §8.
+//
+// Initializes the OTel SDK here so PII scrub processors are active from the
+// very first request — before bindAll() fires (C1 fix).
+
+export async function register() {
+  if (
+    process.env["NEXT_RUNTIME"] === "nodejs" ||
+    process.env["NEXT_RUNTIME"] === "edge"
+  ) {
+    const { initOtelServerNode } = await import(
+      "@repo/core-shared/instrumentation/otel/init-server-node"
+    );
+    initOtelServerNode({
+      dsn: process.env["CMS_SENTRY_DSN"] ?? "",
+      serviceName: "cms",
+      environment: process.env["NODE_ENV"] ?? "development",
+    });
+  }
+}

apps/cms/middleware.ts

@@ -0,0 +1,16 @@
+import { withSecurityHeaders } from "@repo/core-shared/security/next";
+import type { NextRequest, NextResponse } from "next/server";
+
+// Payload's admin UI is served by this Next.js app and is always dynamically
+// rendered, so the shared nonce-based middleware works here: it generates a
+// per-request nonce, threads it into the CSP, and sets the CSP on the
+// forwarded request headers — which is how Next propagates the nonce onto
+// the admin's scripts. Without a nonce, the prod CSP's `strict-dynamic`
+// script-src would block every Payload admin script.
+export function middleware(request: NextRequest): NextResponse {
+  return withSecurityHeaders(request);
+}
+
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+};

apps/cms/next.config.mjs

@@ -1,6 +1,14 @@
 import { withPayload } from "@payloadcms/next/withPayload";
+import { withSentryConfig } from "@sentry/nextjs";
 
 /** @type {import('next').NextConfig} */
 const nextConfig = {};
 
-export default withPayload(nextConfig);
+export default withSentryConfig(withPayload(nextConfig), {
+  silent: process.env.CI !== "true",
+  authToken: process.env.SENTRY_AUTH_TOKEN,
+  org: process.env.SENTRY_ORG,
+  project: process.env.SENTRY_PROJECT_CMS,
+  hideSourceMaps: true,
+  disableLogger: true,
+});

apps/cms/package.json

@@ -7,14 +7,17 @@
     "build": "echo 'CMS build requires database — use docker compose or pnpm dev'",
     "dev": "next dev --port 3001",
     "lint": "eslint .",
+    "test": "vitest run --passWithNoTests",
     "typecheck": "tsc --noEmit",
     "generate:types": "payload generate:types"
   },
   "dependencies": {
     "@payloadcms/next": "^3.14.0",
+    "@payloadcms/richtext-lexical": "^3.14.0",
     "@payloadcms/ui": "^3.14.0",
-    "@repo/cms-core": "workspace:*",
     "@repo/core-cms": "workspace:*",
+    "@repo/core-shared": "workspace:*",
+    "@sentry/nextjs": "^10.51.0",
     "next": "^15.3.0",
     "payload": "^3.14.0",
     "react": "^19.0.0",
@@ -23,10 +26,13 @@
     "sharp": "^0.33.0"
   },
   "devDependencies": {
-    "@repo/eslint-config": "workspace:*",
-    "@repo/typescript-config": "workspace:*",
+    "@repo/core-eslint": "workspace:*",
+    "@repo/core-testing": "workspace:*",
+    "@repo/core-typescript": "workspace:*",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0"
+    "@types/react-dom": "^19.0.0",
+    "@vitest/coverage-v8": "^3.2.7",
+    "vitest": "^3.2.7"
   }
 }

apps/cms/src/app/(payload)/admin/importMap.js

@@ -23,6 +23,7 @@ import { BoldFeatureClient as BoldFeatureClient_e70f5e05f09f93e00b997edb1ef0c864
 import { ItalicFeatureClient as ItalicFeatureClient_e70f5e05f09f93e00b997edb1ef0c864 } from '@payloadcms/richtext-lexical/client'
 import { CollectionCards as CollectionCards_f9c02e79a4aed9a3924487c0cd4cafb1 } from '@payloadcms/next/rsc'
 
+/** @type {Record<string, any>} */
 export const importMap = {
   "@payloadcms/richtext-lexical/rsc#RscEntryLexicalCell": RscEntryLexicalCell_44fe37237e0ebf4470c9990d8cb7b07e,
   "@payloadcms/richtext-lexical/rsc#RscEntryLexicalField": RscEntryLexicalField_44fe37237e0ebf4470c9990d8cb7b07e,

apps/cms/src/middleware.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+const responseMock = vi.hoisted(() => {
+  function makeResponseMock() {
+    const store = new Map<string, string>();
+    return {
+      _store: store,
+      headers: {
+        set: vi.fn((k: string, v: string) => store.set(k, v)),
+        get: vi.fn((k: string) => store.get(k) ?? null),
+      },
+    };
+  }
+  return { makeResponseMock };
+});
+
+vi.mock("next/server", () => ({
+  NextResponse: {
+    next: vi.fn(),
+  },
+}));
+
+import type { NextRequest } from "next/server";
+import { NextResponse } from "next/server";
+import { middleware } from "../middleware";
+
+const ALL_SIX_HEADERS = [
+  "Strict-Transport-Security",
+  "X-Frame-Options",
+  "X-Content-Type-Options",
+  "Referrer-Policy",
+  "Permissions-Policy",
+  "Content-Security-Policy",
+] as const;
+
+function makeRequest(): NextRequest {
+  return { headers: new Headers() } as unknown as NextRequest;
+}
+
+describe("cms middleware", () => {
+  let mock: ReturnType<typeof responseMock.makeResponseMock>;
+
+  beforeEach(() => {
+    mock = responseMock.makeResponseMock();
+    vi.mocked(NextResponse.next).mockReturnValue(
+      mock as unknown as ReturnType<typeof NextResponse.next>,
+    );
+  });
+
+  it("sets all six security headers on the response", () => {
+    middleware(makeRequest());
+
+    for (const header of ALL_SIX_HEADERS) {
+      expect(mock._store.has(header)).toBe(true);
+    }
+  });
+
+  it("sets a per-request nonce header on the response", () => {
+    middleware(makeRequest());
+
+    const nonce = mock._store.get("x-nonce");
+    expect(nonce).toBeDefined();
+    expect((nonce as string).length).toBeGreaterThan(0);
+  });
+
+  it("CSP is permissive in development mode", () => {
+    vi.stubEnv("NODE_ENV", "development");
+
+    middleware(makeRequest());
+
+    const csp = mock._store.get("Content-Security-Policy");
+    expect(csp).toContain("'unsafe-inline'");
+  });
+
+  it("production CSP uses strict-dynamic seeded with the nonce", () => {
+    vi.stubEnv("NODE_ENV", "production");
+
+    middleware(makeRequest());
+
+    const csp = mock._store.get("Content-Security-Policy");
+    const nonce = mock._store.get("x-nonce");
+    expect(csp).toContain("'strict-dynamic'");
+    expect(csp).toContain(`'nonce-${nonce}'`);
+  });
+
+  it("forwards the CSP + nonce on the request headers so Next can propagate it to Payload's scripts", () => {
+    vi.stubEnv("NODE_ENV", "production");
+
+    middleware(makeRequest());
+
+    const call = vi.mocked(NextResponse.next).mock.calls[0] as [
+      { request?: { headers?: Headers } } | undefined,
+    ];
+    const requestHeaders = call[0]?.request?.headers;
+    const requestCsp = requestHeaders?.get("Content-Security-Policy");
+    const nonce = requestHeaders?.get("x-nonce");
+    expect(requestCsp).toBeTruthy();
+    expect(nonce).toBeTruthy();
+    expect(requestCsp).toContain(`'nonce-${nonce}'`);
+    expect(requestCsp).toBe(mock._store.get("Content-Security-Policy"));
+  });
+});

apps/cms/src/payload.config.test.ts

@@ -0,0 +1,20 @@
+import { describe, it, expect } from "vitest";
+import config from "./payload.config";
+
+describe("CMS app payload.config", () => {
+  it("registers all feature collections", async () => {
+    const resolved = await config;
+    const slugs = resolved.collections?.map((c) => c.slug) ?? [];
+    expect(slugs).toEqual(
+      expect.arrayContaining(["users", "articles", "pages", "media"]),
+    );
+  });
+
+  it("registers all feature globals", async () => {
+    const resolved = await config;
+    const slugs = resolved.globals?.map((g) => g.slug) ?? [];
+    expect(slugs).toEqual(
+      expect.arrayContaining(["site-settings", "header"]),
+    );
+  });
+});

apps/cms/tsconfig.json

@@ -1,7 +1,6 @@
 {
-  "extends": "@repo/typescript-config/nextjs.json",
+  "extends": "@repo/core-typescript/nextjs.json",
   "compilerOptions": {
-    "baseUrl": ".",
     "paths": {
       "@/*": [
         "./src/*"
@@ -10,7 +9,8 @@
         "./src/payload.config.ts"
       ]
     },
-    "allowJs": true
+    "allowJs": true,
+    "types": ["vitest/globals"]
   },
   "include": [
     "next-env.d.ts",

apps/cms/turbo.json

@@ -0,0 +1,4 @@
+{
+  "extends": ["//"],
+  "tags": ["app"]
+}

apps/cms/vitest.config.ts

@@ -0,0 +1,7 @@
+import path from "node:path";
+import { mergeConfig } from "vitest/config";
+import { nodeVitestConfig } from "@repo/core-typescript/vitest.base.node";
+
+export default mergeConfig(nodeVitestConfig, {
+  resolve: { alias: { "@": path.resolve(__dirname, "./src") } },
+});

apps/storybook/.eslintignore

@@ -0,0 +1,2 @@
+storybook-static
+.storybook/storybook-static

apps/storybook/.storybook/css.d.ts

@@ -0,0 +1 @@
+declare module "*.css";

apps/storybook/.storybook/main.ts

@@ -2,18 +2,18 @@ import type { StorybookConfig } from "@storybook/react-vite";
 
 const config: StorybookConfig = {
   framework: "@storybook/react-vite",
-  stories: ["../../../packages/ui/src/**/*.stories.@(ts|tsx)"],
+  // ALL workspace stories: core-ui atoms/molecules AND every feature
+  // package's src/ui/components — a story that isn't globbed here is
+  // invisible in Storybook and skipped by pnpm test:stories.
+  stories: ["../../../packages/*/src/**/*.stories.@(ts|tsx)"],
   addons: ["@storybook/addon-essentials"],
   docs: {
     autodocs: "tag",
   },
   async viteFinal(config) {
-    const { mergeConfig } = await import("vite");
     const tailwindPlugin = await import("@tailwindcss/vite");
-
-    return mergeConfig(config, {
-      plugins: [tailwindPlugin.default()],
-    });
+    config.plugins = [tailwindPlugin.default(), ...(config.plugins || [])];
+    return config;
   },
 };
 

apps/storybook/.storybook/preview.ts

@@ -1,5 +1,5 @@
+import "./storybook.css";
 import type { Preview } from "@storybook/react";
-import "../../../packages/ui/src/styles/globals.css";
 
 const preview: Preview = {
   parameters: {

apps/storybook/.storybook/storybook.css

@@ -0,0 +1,4 @@
+@import "tailwindcss";
+@source "../../../packages/core-ui/src";
+
+@import "../../../packages/core-ui/src/styles/theme.css";

apps/storybook/AGENTS.md

@@ -1,8 +1,12 @@
-# apps/storybook -- Centralized Storybook
+# AGENTS.md — apps/storybook
+
+Centralized Storybook instance for visual component development, documentation, and MCP integration for AI agents. Currently ships with an empty stories list — scaffold `@repo/core-ui` first to populate it.
 
 ## Purpose
 
-Centralized Storybook instance that pulls and renders all stories from `packages/ui`. Provides a visual development environment, component documentation, and MCP integration for AI agents.
+Visual testing and documentation hub for the design system. When `@repo/core-ui` is scaffolded, stories live colocated with their components there. Storybook serves as the single source of truth for component usage.
+
+> **core-ui is optional.** Scaffold it with `pnpm turbo gen core-package ui`, then add the stories glob and CSS import (see next-steps printed by the generator).
 
 ## Port: 6006
 
@@ -14,20 +18,17 @@ pnpm dev --filter @repo/storybook   # http://localhost:6006
 
 ### `.storybook/main.ts`
 
-```typescript
-import type { StorybookConfig } from "@storybook/react-vite";
+Stories are empty by default. After scaffolding `@repo/core-ui`, add the glob:
 
+```typescript
 const config: StorybookConfig = {
   framework: "@storybook/react-vite",
-  stories: ["../../../packages/ui/src/**/*.stories.@(ts|tsx)"],
+  stories: ["../../../packages/core-ui/src/**/*.stories.@(ts|tsx)"],
   addons: ["@storybook/addon-essentials"],
-  docs: {
-    autodocs: "tag",
-  },
+  docs: { autodocs: "tag" },
   async viteFinal(config) {
     const { mergeConfig } = await import("vite");
     const tailwindPlugin = await import("@tailwindcss/vite");
-
     return mergeConfig(config, {
       plugins: [tailwindPlugin.default()],
     });
@@ -35,17 +36,18 @@ const config: StorybookConfig = {
 };
 ```
 
-Key configuration details:
-- **`stories`** glob reaches into `packages/ui/src/` to find all `.stories.tsx` files
-- **`viteFinal`** adds the `@tailwindcss/vite` plugin so Tailwind v4 classes render correctly in stories
-- **`autodocs: "tag"`** generates documentation pages for stories tagged with `"autodocs"`
-- **`@storybook/addon-essentials`** includes Controls, Actions, Backgrounds, Viewport, Docs
+Key settings:
+- **`stories` glob** — empty by default; add `"../../../packages/core-ui/src/**/*.stories.@(ts|tsx)"` after scaffolding core-ui
+- **`viteFinal`** — adds Tailwind v4 plugin so classes render in Storybook
+- **`autodocs: "tag"`** — auto-generates docs for tagged stories
 
 ### `.storybook/preview.ts`
 
+After scaffolding `@repo/core-ui`, import global styles here:
+
 ```typescript
 import type { Preview } from "@storybook/react";
-import "../../../packages/ui/src/styles/globals.css";
+import "@repo/core-ui/styles/globals.css";
 
 const preview: Preview = {
   parameters: {
@@ -59,77 +61,76 @@ const preview: Preview = {
 };
 ```
 
-Key details:
-- Imports `globals.css` from `@repo/ui` so all Tailwind v4 `@theme` tokens are available
-- Control matchers auto-detect color and date props for appropriate editor widgets
-
 ## Story Organization
 
-Stories are organized by Atomic Design level via the `title` field in story metadata. The title determines the sidebar hierarchy in Storybook.
+Stories are organized by Atomic Design level via the `title` field:
 
-### Story Title Convention
-
-| Level | Title format | Example | Sidebar path |
-|---|---|---|---|
-| Atom | `"Atoms/{ComponentName}"` | `"Atoms/Button"` | Atoms > Button |
-| Molecule | `"Molecules/{ComponentName}"` | `"Molecules/FormField"` | Molecules > FormField |
-| Organism | `"Organisms/{ComponentName}"` | `"Organisms/DataTable"` | Organisms > DataTable |
-| Template | `"Templates/{ComponentName}"` | `"Templates/DashboardLayout"` | Templates > DashboardLayout |
-
-### Existing Stories
-
-| Story title | Component | Location in `@repo/ui` |
+| Level | Title format | Sidebar path |
 |---|---|---|
-| `Atoms/Button` | Button (5 variants: Default, Secondary, Destructive, Outline, Ghost) | `src/atoms/button/button.stories.tsx` |
-| `Atoms/Input` | Input (Default, Disabled) | `src/atoms/input/input.stories.tsx` |
-| `Molecules/FormField` | FormField (Default, WithDescription, WithError) | `src/molecules/form-field/form-field.stories.tsx` |
+| Atom | `"Atoms/{ComponentName}"` | Atoms > ComponentName |
+| Molecule | `"Molecules/{ComponentName}"` | Molecules > ComponentName |
+| Organism | `"Organisms/{ComponentName}"` | Organisms > ComponentName |
+| Template | `"Templates/{ComponentName}"` | Templates > ComponentName |
+
+Example story file (after scaffolding core-ui at `packages/core-ui/src/atoms/button/button.stories.tsx`):
+
+```typescript
+import type { Meta, StoryObj } from "@storybook/react";
+import { Button } from "./button";
+
+const meta = {
+  title: "Atoms/Button",
+  component: Button,
+  tags: ["autodocs"],
+} satisfies Meta<typeof Button>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { children: "Click me" },
+};
+
+export const Variant: Story = {
+  args: { children: "Secondary", variant: "secondary" },
+};
+```
 
 ## MCP Integration
 
-When Storybook is running, the MCP (Model Context Protocol) endpoint is available at:
+When Storybook runs, the MCP endpoint is available at:
 
 ```
 http://localhost:6006/mcp
 ```
 
-### Available MCP tools:
+### Available tools:
 
-- **`list-all-documentation`** -- Lists all documented components and their stories
-- **`get-documentation`** -- Gets detailed documentation for a specific component (props, variants, usage)
-- **`run-story-tests`** -- Runs visual tests on stories to validate rendering
+- **`list-all-documentation`** — Lists all component stories and their properties
+- **`get-documentation`** — Gets detailed component info (props, variants, usage examples)
+- **`run-story-tests`** — Validates story rendering
 
-### Installing addon-mcp
+### Before building new components:
 
-If `@storybook/addon-mcp` is not already installed:
-
-```bash
-npx storybook add @storybook/addon-mcp
-```
-
-This adds the addon to `.storybook/main.ts` and enables the MCP endpoint.
-
-### Using MCP in workflows
-
-Always query MCP before creating new UI components:
-
-1. **Before creating:** `list-all-documentation` to check if a similar component exists
-2. **Before extending:** `get-documentation` to understand existing props and variants
-3. **After creating:** `run-story-tests` to validate the new story renders correctly
+1. Query `list-all-documentation` to check if a similar component exists
+2. Query `get-documentation` to understand existing props and variants
+3. After creating: `run-story-tests` to validate
 
 ## Dependencies
 
 | Dependency | Purpose |
 |---|---|
-| `@repo/ui` | Source of all component stories |
-| `@storybook/react-vite` | Storybook framework using Vite bundler |
-| `@storybook/addon-essentials` | Controls, Actions, Docs, Backgrounds, Viewport |
-| `@tailwindcss/vite` | Vite plugin for Tailwind CSS v4 |
-| `storybook` | Storybook core CLI and dev server |
-| `tailwindcss` | Tailwind CSS v4 engine |
-| `vite` | Build tool / dev server |
-| `react` / `react-dom` | React 19 runtime |
+| `@repo/core-ui` | Component source + stories (optional — scaffold with `pnpm turbo gen core-package ui`) |
+| `@storybook/react-vite` | Storybook with Vite bundler |
+| `@storybook/addon-essentials` | Controls, Actions, Docs, Backgrounds |
+| `@tailwindcss/vite` | Vite plugin for Tailwind v4 |
+| `storybook` | Storybook CLI + dev server |
+| `tailwindcss` | Tailwind CSS v4 |
+| `vite` | Build tool |
+| `react` / `react-dom` | React 19 |
 
 ## Cross-References
 
-- **Component source:** `packages/ui/` -- see `packages/ui/AGENTS.md`
-- **Tailwind tokens:** `packages/ui/src/styles/globals.css`
+- **Component source (when scaffolded):** `packages/core-ui/AGENTS.md`
+- **Scaffold core-ui:** `pnpm turbo gen core-package ui`
+- **Storybook docs:** `.storybook/` folder

apps/storybook/eslint.config.js

@@ -0,0 +1,3 @@
+import baseConfig from "@repo/core-eslint/base";
+
+export default baseConfig;

apps/storybook/package.json

@@ -6,22 +6,31 @@
   "scripts": {
     "build": "echo 'Storybook build — use pnpm dev for development'",
     "build:storybook": "storybook build",
+    "build-storybook": "storybook build",
     "dev": "storybook dev -p 6006",
-    "lint": "eslint ."
-  },
-  "dependencies": {
-    "@repo/ui": "workspace:*"
+    "lint": "eslint .",
+    "test-storybook": "test-storybook --url http://localhost:6006",
+    "test:stories": "concurrently -k -s first -n 'SB,TEST' -c 'magenta,blue' 'pnpm exec http-server storybook-static --port 6006 --silent' 'pnpm exec wait-on tcp:6006 && pnpm test-storybook'"
   },
+  "dependencies": {},
   "devDependencies": {
-    "@repo/eslint-config": "workspace:*",
-    "@repo/typescript-config": "workspace:*",
+    "@playwright/test": "^1.49.0",
+    "@repo/core-eslint": "workspace:*",
+    "@repo/core-typescript": "workspace:*",
+    "@repo/core-ui": "workspace:*",
     "@storybook/addon-essentials": "^8.6.0",
+    "@storybook/react": "^8.6.0",
     "@storybook/react-vite": "^8.6.0",
+    "@storybook/test-runner": "^0.19.1",
     "@tailwindcss/vite": "^4.1.0",
+    "concurrently": "^9.0.0",
+    "http-server": "^14.1.0",
+    "playwright": "^1.52.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "storybook": "^8.6.0",
     "tailwindcss": "^4.1.0",
-    "vite": "^6.3.0"
+    "vite": "^6.3.0",
+    "wait-on": "^8.0.0"
   }
 }

apps/storybook/test-runner.config.ts

@@ -0,0 +1,13 @@
+import type { TestRunnerConfig } from "@storybook/test-runner";
+
+const config: TestRunnerConfig = {
+  async preVisit(page) {
+    page.on("console", (msg) => {
+      if (msg.type() === "error") {
+        throw new Error(`Console error in story: ${msg.text()}`);
+      }
+    });
+  },
+};
+
+export default config;

apps/storybook/tests/visual.spec.ts

@@ -0,0 +1,51 @@
+import { test, expect } from "@playwright/test";
+
+/**
+ * Iterates every story registered in Storybook and takes a screenshot.
+ *
+ * Storybook exposes its story manifest at /index.json (Storybook 7+). For
+ * each entry where `type === "story"`, we navigate to the iframe URL and
+ * snapshot.
+ *
+ * Today the index is empty (no components in the repo). The harness still
+ * runs — it just finds zero stories. The moment a story lands, the
+ * baseline is captured on first run and subsequent runs diff against it.
+ */
+type StoryEntry = {
+  id: string;
+  title: string;
+  name: string;
+  type: "story" | "docs";
+};
+
+async function fetchStoryIndex(baseURL: string): Promise<StoryEntry[]> {
+  const res = await fetch(`${baseURL}/index.json`);
+  if (!res.ok) return [];
+  const json = (await res.json()) as {
+    entries?: Record<string, StoryEntry>;
+  };
+  return Object.values(json.entries ?? {}).filter((e) => e.type === "story");
+}
+
+test.describe("Storybook visual regression", () => {
+  test("captures a screenshot for every registered story", async ({
+    page,
+    baseURL,
+  }) => {
+    const stories = await fetchStoryIndex(baseURL!);
+    if (stories.length === 0) {
+      test.skip(
+        true,
+        "No stories registered yet — visual regression harness is inactive until the first story lands.",
+      );
+      return;
+    }
+    for (const story of stories) {
+      await test.step(`${story.title} — ${story.name}`, async () => {
+        await page.goto(`/iframe.html?id=${story.id}&viewMode=story`);
+        await page.waitForLoadState("networkidle");
+        await expect(page).toHaveScreenshot(`${story.id}.png`);
+      });
+    }
+  });
+});

apps/storybook/tsconfig.json

@@ -1,11 +1,16 @@
 {
-  "extends": "@repo/typescript-config/react-library.json",
+  "extends": "@repo/core-typescript/react-library.json",
   "compilerOptions": {
-    "baseUrl": ".",
     "paths": {
       "@/*": ["./src/*"]
     }
   },
-  "include": ["src/**/*.ts", "src/**/*.tsx"],
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    ".storybook/**/*.ts",
+    "*.ts",
+    "*.tsx"
+  ],
   "exclude": ["node_modules"]
 }

apps/storybook/turbo.json

@@ -0,0 +1,4 @@
+{
+  "extends": ["//"],
+  "tags": ["app"]
+}

apps/web-next/AGENTS.md

@@ -1,8 +1,10 @@
-# apps/web-next -- Next.js 15 Reference App
+# AGENTS.md — apps/web-next
+
+Next.js 15 reference application using App Router. Demonstrates consuming feature packages via tRPC and importing UI components from `@repo/core-ui`. Both `@repo/core-trpc` and `@repo/core-ui` are optional packages — scaffold them with `pnpm turbo gen core-package trpc` / `ui` if needed.
 
 ## Purpose
 
-Next.js 15 reference application using App Router. Demonstrates how to consume `@repo/api-client` for tRPC data fetching, `@repo/ui` for components, and `@repo/api` for the tRPC HTTP endpoint. This is a thin app -- business logic lives in `@repo/core`, UI components live in `@repo/ui`.
+Thin app showcasing how features work end-to-end. Business logic lives in feature packages (`@repo/auth`, `@repo/blog`, etc.); UI primitives live in `@repo/core-ui`; this app is mostly routes, layouts, and component composition.
 
 ## Port: 3000
 
@@ -10,177 +12,56 @@ Next.js 15 reference application using App Router. Demonstrates how to consume `
 pnpm dev --filter @repo/web-next   # http://localhost:3000
 ```
 
+Requires `@repo/cms` and PostgreSQL running to fetch live data:
+
+```bash
+docker compose up -d postgres       # PostgreSQL on port 5432
+pnpm dev --filter @repo/cms        # Payload admin on port 3001
+pnpm dev --filter @repo/web-next   # Next.js on port 3000
+```
+
 ## Key Files
 
 | File | Purpose |
 |---|---|
-| `src/app/layout.tsx` | Root layout -- wraps children with `<Providers>`, sets HTML metadata |
-| `src/app/providers.tsx` | Client component that wraps the app with `<ApiProvider trpcUrl="/api/trpc">` |
-| `src/app/page.tsx` | Home page (server component by default) |
-| `src/app/api/trpc/[trpc]/route.ts` | tRPC HTTP endpoint using the Next.js fetch adapter |
+| `src/app/layout.tsx` | Root layout — wraps app with `<Providers>` |
+| `src/app/providers.tsx` | Client component wrapper (add tRPC/React Query here after scaffolding `@repo/core-trpc`) |
+| `src/app/page.tsx` | Home page — navigation + marketing content |
+| `src/app/blog/[slug]/page.tsx` | Dynamic blog post route |
+| `e2e/` | Playwright end-to-end tests |
 
-## tRPC Endpoint Setup
+## tRPC Setup (optional)
 
-The file `src/app/api/trpc/[trpc]/route.ts` creates a catch-all API route that handles all tRPC requests:
+`@repo/core-trpc` is not installed by default. After scaffolding with `pnpm turbo gen core-package trpc`:
+
+1. Create `src/app/api/trpc/[trpc]/route.ts`:
 
 ```typescript
 import { fetchRequestHandler } from "@trpc/server/adapters/fetch";
-import { appRouter } from "@repo/api";
+import { appRouter } from "@repo/core-api";
+import { bindAll } from "../../../../server/bind-production";
 
-const handler = (req: Request) =>
-  fetchRequestHandler({
+const handler = async (req: Request) => {
+  await bindAll();
+  return fetchRequestHandler({
     endpoint: "/api/trpc",
     req,
     router: appRouter,
     createContext: () => ({}),
   });
+};
 
 export { handler as GET, handler as POST };
 ```
 
-How it works:
-1. Next.js catch-all route `[trpc]` matches any path under `/api/trpc/`
-2. `fetchRequestHandler` from tRPC's fetch adapter processes the request
-3. `appRouter` from `@repo/api` contains all registered routers
-4. `createContext` provides the context object to all procedures (currently empty `{}`)
-5. Both GET (for queries) and POST (for mutations/batched queries) are exported
-
-## Provider Setup
-
-The `<ApiProvider>` from `@repo/api-client` must wrap the entire app. Since it uses React hooks, it lives in a `"use client"` component:
-
-```tsx
-// src/app/providers.tsx
-"use client";
-
-import { ApiProvider } from "@repo/api-client";
-
-export function Providers({ children }: { children: React.ReactNode }) {
-  return <ApiProvider trpcUrl="/api/trpc">{children}</ApiProvider>;
-}
-```
-
-```tsx
-// src/app/layout.tsx
-import { Providers } from "./providers";
-
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en">
-      <body>
-        <Providers>{children}</Providers>
-      </body>
-    </html>
-  );
-}
-```
-
-## Recipe: Adding a New Page with Data Fetching
-
-This example adds an `/articles` page that lists published articles.
-
-### Step 1: Create the page route
-
-Create `src/app/articles/page.tsx`:
-
-```tsx
-import { ArticleList } from "./article-list";
-
-export default function ArticlesPage() {
-  return (
-    <main>
-      <h1>Articles</h1>
-      <ArticleList />
-    </main>
-  );
-}
-```
-
-### Step 2: Create the client component with data fetching
-
-Create `src/app/articles/article-list.tsx`:
-
-```tsx
-"use client";
-
-import { useTRPC } from "@repo/api-client";
-import { useQuery } from "@tanstack/react-query";
-import { Button } from "@repo/ui";
-
-export function ArticleList() {
-  const trpc = useTRPC();
-  const { data, isLoading, error } = useQuery(
-    trpc.content.listArticles.queryOptions({ status: "published", limit: 20 })
-  );
-
-  if (isLoading) return <p>Loading articles...</p>;
-  if (error) return <p>Error loading articles: {error.message}</p>;
-
-  return (
-    <ul>
-      {data?.map((article) => (
-        <li key={article.id}>
-          <h2>{article.title}</h2>
-          <Button variant="outline" size="sm">
-            Read more
-          </Button>
-        </li>
-      ))}
-    </ul>
-  );
-}
-```
-
-Key patterns:
-- The page component (`page.tsx`) is a server component by default -- no `"use client"` needed
-- Data-fetching components that use `useTRPC()` must be client components (`"use client"`)
-- Import UI components from `@repo/ui`, never recreate them locally
-
-## Payload Initialization Pattern (Server-Side Local API)
-
-For server-side access to Payload CMS data (e.g., in server components, API routes, or server actions), create a Payload client initializer:
+2. Update `src/app/providers.tsx`:
 
 ```typescript
-// src/lib/payload.ts
-import { getPayload } from "payload";
-import config from "@repo/cms-core/src/payload.config";
-import { createPayloadClient, type PayloadClient } from "@repo/cms-client";
+"use client";
+import { NextTrpcProvider } from "@repo/core-trpc/next";
 
-let cachedClient: PayloadClient | null = null;
-
-export async function getPayloadClient(): Promise<PayloadClient> {
-  if (cachedClient) return cachedClient;
-
-  const payload = await getPayload({ config });
-  cachedClient = createPayloadClient({ mode: "local", payload });
-  return cachedClient;
-}
-```
-
-Usage in a server component:
-
-```tsx
-// src/app/articles/page.tsx (server component)
-import { getPayloadClient } from "@/lib/payload";
-
-export default async function ArticlesPage() {
-  const client = await getPayloadClient();
-  const result = await client.find("articles", {
-    where: { status: { equals: "published" } },
-    sort: "-publishedAt",
-    limit: 20,
-  });
-
-  return (
-    <main>
-      <h1>Articles</h1>
-      <ul>
-        {result.docs.map((article) => (
-          <li key={article.id}>{article.title}</li>
-        ))}
-      </ul>
-    </main>
-  );
+export function Providers({ children }: { children: React.ReactNode }) {
+  return <NextTrpcProvider trpcUrl="/api/trpc">{children}</NextTrpcProvider>;
 }
 ```
 
@@ -188,16 +69,43 @@ export default async function ArticlesPage() {
 
 | Dependency | Purpose |
 |---|---|
-| `@repo/api` | `appRouter` for the tRPC HTTP endpoint |
-| `@repo/api-client` | `ApiProvider` + `useTRPC()` for client-side data fetching |
-| `@repo/ui` | Shared UI components (Button, Input, Label, FormField, etc.) |
-| `next` | Next.js 15 framework with App Router |
-| `react` / `react-dom` | React 19 runtime |
+| `@repo/core-api` | `appRouter` for tRPC endpoint |
+| `@repo/core-trpc/next` | Next.js tRPC client + provider (optional — scaffold first) |
+| `@repo/core-ui` | Design system components (optional — scaffold first) |
+| `@repo/auth`, `@repo/blog`, etc. | Feature packages (indirectly via core-api) |
+| `next` | Next.js 15 framework |
+| `@trpc/server` | tRPC server (fetch adapter) |
+
+## Test conventions
+
+- Unit tests colocated: `src/app/blog/article-list.test.tsx`
+- Vitest environment: `jsdom`
+- e2e tests in `e2e/` folder: `*.spec.ts`
+- Run: `pnpm test --filter @repo/web-next` (units) or `pnpm test:e2e` (Playwright)
+
+## E2E Test Setup
+
+Playwright config in `e2e/playwright.config.ts`:
+
+```typescript
+import { defineConfig, devices } from "@playwright/test";
+
+export default defineConfig({
+  testDir: "./e2e",
+  webServer: {
+    command: "pnpm dev",
+    port: 3000,
+    reuseExistingServer: !process.env.CI,
+  },
+  use: { ...devices["Desktop Chrome"].use },
+});
+```
+
+Run: `pnpm test:e2e` starts the dev server and runs all `.spec.ts` files.
 
 ## Cross-References
 
-- **tRPC routers:** `packages/api/` -- see `packages/api/AGENTS.md`
-- **tRPC client/hooks:** `packages/api-client/` -- see `packages/api-client/AGENTS.md`
-- **UI components:** `packages/ui/` -- see `packages/ui/AGENTS.md`
-- **CMS client:** `packages/cms-client/` -- see `packages/cms-client/AGENTS.md`
-- **CMS config:** `packages/cms-core/` -- see `packages/cms-core/AGENTS.md`
+- **Feature packages:** `packages/{auth,blog,media,marketing-pages,navigation}/`
+- **tRPC composition:** `packages/core-api/AGENTS.md`
+- **tRPC client + provider (optional):** scaffold `@repo/core-trpc` first, then see `turbo/generators/templates/core-package/trpc/AGENTS.md.hbs`
+- **UI components (optional):** scaffold with `pnpm turbo gen core-package ui`, then see `turbo/generators/templates/core-package/ui/AGENTS.md.hbs`

apps/web-next/e2e/blog-post.spec.ts

@@ -0,0 +1,20 @@
+import { test, expect } from "@playwright/test";
+
+test("/blog/[slug] returns 404 for non-existent slug", async ({ page }) => {
+  const response = await page.goto("/blog/this-slug-does-not-exist", {
+    waitUntil: "domcontentloaded",
+  });
+  expect(response?.status()).toBe(404);
+});
+
+test("/blog/[slug] for a real slug renders the article", async ({ page }) => {
+  // The mock blog repository is empty by default — so this test currently
+  // expects 404. When seeded data exists in Payload, replace 404 with 200
+  // and check for article.title in the page body.
+  test.skip(
+    true,
+    "Pending: seed a published article in Payload before enabling this test",
+  );
+  await page.goto("/blog/example-slug");
+  await expect(page.locator("h1").first()).toBeVisible();
+});

apps/web-next/e2e/home.spec.ts

@@ -0,0 +1,12 @@
+import { test, expect } from "@playwright/test";
+
+test("home page renders site name + nav + article list", async ({ page }) => {
+  await page.goto("/");
+  // Page renders and shows site name
+  await expect(page.locator("h1").first()).toBeVisible();
+  // Site name from siteSettings (mock seed: "My App")
+  await expect(page.locator("body")).toContainText(/My App/i);
+  // Nav element is present on the page
+  const nav = page.locator("nav");
+  await expect(nav).toHaveCount(1);
+});

apps/web-next/e2e/marketing-page.spec.ts

@@ -0,0 +1,10 @@
+import { test, expect } from "@playwright/test";
+
+test("/about renders the about marketing page", async ({ page }) => {
+  await page.goto("/about");
+  // Either renders the seeded page (h1 = "About us") or "not yet published" message
+  // — both are HTTP 200, so the test only checks it doesn't 500.
+  const status = (await page.context().request.get("/about")).status();
+  expect(status).toBe(200);
+  await expect(page.locator("body")).toBeVisible();
+});

apps/web-next/eslint.config.js

@@ -0,0 +1,11 @@
+import baseConfig from "@repo/core-eslint/base";
+
+export default [
+  ...baseConfig,
+  {
+    files: ["next-env.d.ts"],
+    rules: {
+      "@typescript-eslint/triple-slash-reference": "off",
+    },
+  },
+];

apps/web-next/instrumentation-client.ts

@@ -0,0 +1,19 @@
+// apps/web-next/instrumentation-client.ts
+// Next.js 15+ browser hook: runs in the client bundle on app start.
+
+import { initSentryClient } from "@repo/core-shared/instrumentation/sentry/init-client";
+
+function getNonce(): string {
+  if (typeof document === "undefined") return "";
+  return (
+    document.querySelector('meta[name="csp-nonce"]')?.getAttribute("content") ??
+    ""
+  );
+}
+
+initSentryClient({
+  dsn: process.env["NEXT_PUBLIC_WEB_NEXT_SENTRY_DSN"],
+  app: "web-next",
+  release: process.env["NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA"],
+  nonce: getNonce(),
+});

apps/web-next/instrumentation.ts

@@ -0,0 +1,22 @@
+// apps/web-next/instrumentation.ts
+// Next.js convention: this module runs once on server boot (before any request handler).
+// Initializes the OTel SDK here so PII scrub processors are active from the very first
+// request — before bindAll() fires. Calling initOtelServerNode here (not inside bindAll)
+// closes the startup window where @sentry/nextjs auto-instrumentation could send
+// unscrubbed errors (C1 fix).
+
+export async function register() {
+  if (
+    process.env["NEXT_RUNTIME"] === "nodejs" ||
+    process.env["NEXT_RUNTIME"] === "edge"
+  ) {
+    const { initOtelServerNode } = await import(
+      "@repo/core-shared/instrumentation/otel/init-server-node"
+    );
+    initOtelServerNode({
+      dsn: process.env["WEB_NEXT_SENTRY_DSN"] ?? "",
+      serviceName: "web-next",
+      environment: process.env["NODE_ENV"] ?? "development",
+    });
+  }
+}

apps/web-next/middleware.ts

@@ -0,0 +1,10 @@
+import { withSecurityHeaders } from "@repo/core-shared/security/next";
+import type { NextRequest } from "next/server";
+
+export function middleware(request: NextRequest) {
+  return withSecurityHeaders(request);
+}
+
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+};

apps/web-next/next.config.mjs

@@ -1,6 +1,31 @@
+import { withSentryConfig } from "@sentry/nextjs";
+
 /** @type {import('next').NextConfig} */
 const nextConfig = {
-  transpilePackages: ["@repo/api", "@repo/api-client", "@repo/core", "@repo/ui"],
+  transpilePackages: [
+    "@repo/auth",
+    "@repo/blog",
+    "@repo/core-analytics",
+    "@repo/core-api",
+    "@repo/core-audit",
+    "@repo/core-cms",
+    "@repo/core-consent",
+    "@repo/core-dsr",
+    "@repo/core-shared",
+    "@repo/core-ui",
+    "@repo/marketing-pages",
+    "@repo/media",
+    "@repo/navigation",
+    "@repo/core-trpc",
+  ],
 };
 
-export default nextConfig;
+export default withSentryConfig(nextConfig, {
+  // Token is build-time only; CI sets SENTRY_AUTH_TOKEN.
+  silent: process.env.CI !== "true",
+  authToken: process.env.SENTRY_AUTH_TOKEN,
+  org: process.env.SENTRY_ORG,
+  project: process.env.SENTRY_PROJECT_WEB_NEXT,
+  hideSourceMaps: true,
+  disableLogger: true,
+});

apps/web-next/package.json

@@ -5,23 +5,54 @@
   "type": "module",
   "scripts": {
     "build": "echo 'Next.js build requires full environment — use pnpm dev or docker'",
-    "dev": "next dev --port 3000",
+    "dev": "TSX_TSCONFIG_PATH=../../tsconfig.json tsx server.ts",
+    "start": "node --import tsx server.ts",
     "lint": "eslint .",
+    "test": "vitest run --passWithNoTests",
+    "test:e2e": "playwright test",
+    "test:e2e:install": "playwright install --with-deps chromium",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@repo/api": "workspace:*",
-    "@repo/api-client": "workspace:*",
-    "@repo/ui": "workspace:*",
+    "@repo/auth": "workspace:*",
+    "@repo/blog": "workspace:*",
+    "@repo/core-api": "workspace:*",
+    "@repo/core-audit": "workspace:*",
+    "@repo/core-cms": "workspace:*",
+    "@repo/core-consent": "workspace:*",
+    "@repo/core-dsr": "workspace:*",
+    "@repo/core-shared": "workspace:*",
+    "@repo/core-trpc": "workspace:^",
+    "@repo/marketing-pages": "workspace:*",
+    "@repo/media": "workspace:*",
+    "@repo/navigation": "workspace:*",
+    "@sentry/nextjs": "^10.51.0",
+    "@tailwindcss/postcss": "^4.3.0",
+    "@tanstack/react-query": "^5.96.2",
+    "@trpc/server": "^11.18.0",
+    "inversify": "^6.2.0",
     "next": "^15.3.0",
+    "payload": "^3.14.0",
     "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "react-dom": "^19.0.0",
+    "reflect-metadata": "^0.2.2",
+    "superjson": "^2.2.1",
+    "tailwindcss": "^4.1.0"
   },
   "devDependencies": {
-    "@repo/eslint-config": "workspace:*",
-    "@repo/typescript-config": "workspace:*",
+    "@playwright/test": "^1.50.0",
+    "@repo/core-eslint": "workspace:*",
+    "@repo/core-testing": "workspace:*",
+    "@repo/core-typescript": "workspace:*",
+    "@testing-library/jest-dom": "^6.5.0",
+    "@testing-library/react": "^16.0.0",
+    "@testing-library/user-event": "^14.5.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0"
+    "@types/react-dom": "^19.0.0",
+    "@vitest/coverage-v8": "^3.2.7",
+    "jsdom": "^25.0.0",
+    "tsx": "^4.0.0",
+    "vitest": "^3.2.7"
   }
 }

apps/web-next/playwright.config.ts

@@ -0,0 +1,26 @@
+import { defineConfig, devices } from "@playwright/test";
+
+export default defineConfig({
+  testDir: "./e2e",
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: "list",
+  use: {
+    baseURL: "http://localhost:3000",
+    trace: "on-first-retry",
+  },
+  projects: [
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"] },
+    },
+  ],
+  webServer: {
+    command: "pnpm dev",
+    url: "http://localhost:3000",
+    reuseExistingServer: !process.env.CI,
+    timeout: 60_000,
+  },
+});

apps/web-next/postcss.config.mjs

@@ -0,0 +1,5 @@
+export default {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};

apps/web-next/server.ts

@@ -0,0 +1,23 @@
+// apps/web-next/server.ts
+// SERVER-ONLY entry. Custom Next.js server for local development.
+// When @repo/core-realtime is scaffolded, this file is extended to boot
+// Socket.IO alongside Next (see pnpm turbo gen core-package realtime).
+import "reflect-metadata";
+import { createServer } from "node:http";
+import next from "next";
+import { bindAll } from "./src/server/bind-production.js";
+
+const dev = process.env.NODE_ENV !== "production";
+const port = Number(process.env.PORT ?? 3000);
+
+const app = next({ dev });
+const handle = app.getRequestHandler();
+
+await app.prepare();
+
+await bindAll();
+
+const httpServer = createServer((req, res) => handle(req, res));
+httpServer.listen(port, () => {
+  console.log(`> Ready on http://localhost:${port}`);
+});

apps/web-next/src/__tests__/middleware.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+const responseMock = vi.hoisted(() => {
+  function makeResponseMock() {
+    const store = new Map<string, string>();
+    return {
+      _store: store,
+      headers: {
+        set: vi.fn((k: string, v: string) => store.set(k, v)),
+        get: vi.fn((k: string) => store.get(k) ?? null),
+      },
+    };
+  }
+  return { makeResponseMock };
+});
+
+vi.mock("next/server", () => ({
+  NextResponse: {
+    next: vi.fn(),
+  },
+}));
+
+import type { NextRequest } from "next/server";
+import { NextResponse } from "next/server";
+import { middleware } from "../../middleware";
+
+const ALL_SIX_HEADERS = [
+  "Strict-Transport-Security",
+  "X-Frame-Options",
+  "X-Content-Type-Options",
+  "Referrer-Policy",
+  "Permissions-Policy",
+  "Content-Security-Policy",
+] as const;
+
+function makeRequest(): NextRequest {
+  return { headers: new Headers() } as unknown as NextRequest;
+}
+
+describe("web-next middleware", () => {
+  let mock: ReturnType<typeof responseMock.makeResponseMock>;
+
+  beforeEach(() => {
+    mock = responseMock.makeResponseMock();
+    vi.mocked(NextResponse.next).mockReturnValue(
+      mock as unknown as ReturnType<typeof NextResponse.next>,
+    );
+  });
+
+  it("sets all six security headers on the response", () => {
+    middleware(makeRequest());
+
+    for (const header of ALL_SIX_HEADERS) {
+      expect(mock._store.has(header)).toBe(true);
+    }
+  });
+
+  it("sets x-nonce header on the response", () => {
+    middleware(makeRequest());
+
+    const nonce = mock._store.get("x-nonce");
+    expect(nonce).toBeDefined();
+    expect(typeof nonce).toBe("string");
+    expect((nonce as string).length).toBeGreaterThan(0);
+  });
+
+  it("CSP contains nonce in production mode", () => {
+    vi.stubEnv("NODE_ENV", "production");
+
+    middleware(makeRequest());
+
+    const nonce = mock._store.get("x-nonce");
+    const csp = mock._store.get("Content-Security-Policy");
+    expect(csp).toContain(`'nonce-${nonce}'`);
+  });
+
+  it("CSP is permissive (unsafe-inline) in development mode", () => {
+    vi.stubEnv("NODE_ENV", "development");
+
+    middleware(makeRequest());
+
+    const csp = mock._store.get("Content-Security-Policy");
+    expect(csp).toContain("'unsafe-inline'");
+  });
+
+  it("x-nonce is forwarded in request headers passed to NextResponse.next", () => {
+    middleware(makeRequest());
+
+    const call = vi.mocked(NextResponse.next).mock.calls[0] as [
+      { request?: { headers?: Headers } } | undefined,
+    ];
+    expect(call[0]?.request?.headers?.get("x-nonce")).toBeTruthy();
+  });
+});

apps/web-next/src/__tests__/sign-up-welcome-email.test.ts

@@ -0,0 +1,50 @@
+// Cross-feature event bus proof-of-life (DISABLED — @repo/core-events removed).
+//
+// @repo/core-events is now optional. When absent, ctx.bus is undefined, and
+// bus?.subscribe(...) / bus?.publish(...) calls are no-ops. Cross-feature event
+// fanout does not occur until core-events is scaffolded via:
+//
+//   pnpm turbo gen core-package events
+//
+// After scaffolding, restore this test and re-wire the bus in bind-production.ts
+// (see the comment in bindAll()). Until then, signing up does NOT trigger a
+// welcome email — the mailer queue stays empty.
+//
+// Replaced with a reduced test that asserts the no-bus behavior.
+
+import "reflect-metadata";
+import { describe, it, expect, beforeEach } from "vitest";
+import { bindAllDevSeed, __resetBindStateForTests } from "@/server/bind-production";
+import { authContainer } from "@repo/auth/di/container";
+import { AUTH_SYMBOLS } from "@repo/auth/di/symbols";
+import type { ISignUpController } from "@repo/auth";
+import { marketingPagesContainer } from "@repo/marketing-pages/di/container";
+import { MARKETING_PAGES_SYMBOLS } from "@repo/marketing-pages/di/symbols";
+import { RecordingMailerService } from "@repo/marketing-pages/services/recording-mailer";
+
+describe("e2e: sign-up with no event bus (core-events not scaffolded)", () => {
+  beforeEach(() => {
+    __resetBindStateForTests();
+  });
+
+  it("sign-up succeeds and mailer stays empty (no cross-feature fanout without bus)", async () => {
+    await bindAllDevSeed();
+
+    const mailer = marketingPagesContainer.get<RecordingMailerService>(
+      MARKETING_PAGES_SYMBOLS.IMailerService,
+    );
+    const signUp = authContainer.get<ISignUpController>(AUTH_SYMBOLS.ISignUpController);
+
+    await signUp({
+      username: "testuser",
+      password: "secret_password",
+      confirmPassword: "secret_password",
+    });
+
+    // Without a bus, bus?.subscribe() is a no-op so the event handler never
+    // fires and the mailer receives nothing.
+    await new Promise((r) => setImmediate(r));
+
+    expect(mailer.sent).toEqual([]);
+  });
+});

apps/web-next/src/app/about/page.tsx

@@ -0,0 +1,12 @@
+import { PageContent } from "@repo/marketing-pages/ui";
+import { bindAll } from "../../server/bind-production";
+
+export default async function AboutPage() {
+  await bindAll();
+
+  return (
+    <main className="px-6 py-8">
+      <PageContent slug="about" />
+    </main>
+  );
+}

apps/web-next/src/app/api/trpc/[trpc]/route.ts

@@ -1,12 +1,18 @@
 import { fetchRequestHandler } from "@trpc/server/adapters/fetch";
-import { appRouter } from "@repo/api";
+import { appRouter } from "@repo/core-api";
+import { createWebNextTrpcContext } from "../../../../server/trpc-context";
 
-const handler = (req: Request) =>
-  fetchRequestHandler({
+const handler = async (req: Request) => {
+  return fetchRequestHandler({
     endpoint: "/api/trpc",
     req,
     router: appRouter,
-    createContext: () => ({}),
+    // Real per-request context (A11): server-derived clientIp (B2, trust
+    // caveat in core-shared/trpc/context.ts), the authenticated user resolved
+    // from the session cookie (B7), and the consent/dsr bindings that make
+    // the mounted compliance routers live.
+    createContext: () => createWebNextTrpcContext(req),
   });
+};
 
 export { handler as GET, handler as POST };

apps/web-next/src/app/blog/[slug]/page.tsx

@@ -0,0 +1,17 @@
+import { ArticleDetail } from "@repo/blog/ui";
+import { bindAll } from "../../../server/bind-production";
+
+type PageProps = {
+  params: Promise<{ slug: string }>;
+};
+
+export default async function BlogPostPage({ params }: PageProps) {
+  await bindAll();
+  const { slug } = await params;
+
+  return (
+    <main className="px-6 py-8">
+      <ArticleDetail slug={slug} />
+    </main>
+  );
+}

apps/web-next/src/app/layout.tsx

@@ -1,4 +1,7 @@
 import type { Metadata } from "next";
+import "../styles/app.css";
+import { getNonce } from "@repo/core-shared/security/next";
+import { bindAll } from "../server/bind-production";
 import { Providers } from "./providers";
 
 export const metadata: Metadata = {
@@ -6,13 +9,20 @@ export const metadata: Metadata = {
   description: "Clean Architecture Monorepo Template",
 };
 
-export default function RootLayout({
+export default async function RootLayout({
   children,
 }: {
   children: React.ReactNode;
 }) {
+  await bindAll();
+  const nonce = await getNonce();
+
   return (
     <html lang="en">
+      <head>
+        {/* nonce exposed to client so instrumentation-client.ts can read it */}
+        <meta name="csp-nonce" content={nonce} />
+      </head>
       <body>
         <Providers>{children}</Providers>
       </body>

apps/web-next/src/app/page.tsx

@@ -1,8 +1,15 @@
-export default function Home() {
+import { ArticleList } from "@repo/blog/ui";
+import { bindAll } from "../server/bind-production";
+
+export default async function Home() {
+  await bindAll();
+
   return (
-    <main>
-      <h1>Template — Next.js</h1>
-      <p>Clean Architecture Monorepo Template</p>
+    <main className="mx-auto max-w-5xl px-6 py-8">
+      <h2 className="mb-4 text-2xl font-bold text-foreground">
+        Latest articles
+      </h2>
+      <ArticleList />
     </main>
   );
 }

apps/web-next/src/app/providers.test.tsx

@@ -0,0 +1,14 @@
+import { describe, it, expect } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { Providers } from "./providers";
+
+describe("Providers", () => {
+  it("renders children", () => {
+    render(
+      <Providers>
+        <div data-testid="child">hi</div>
+      </Providers>,
+    );
+    expect(screen.getByTestId("child")).toBeInTheDocument();
+  });
+});

apps/web-next/src/app/providers.tsx

@@ -1,7 +1,7 @@
 "use client";
 
-import { ApiProvider } from "@repo/api-client";
+import { NextTrpcProvider } from "@repo/core-trpc/next";
 
 export function Providers({ children }: { children: React.ReactNode }) {
-  return <ApiProvider trpcUrl="/api/trpc">{children}</ApiProvider>;
+  return <NextTrpcProvider>{children}</NextTrpcProvider>;
 }