@skyf0xx/hedgehog 0.1.5 → 0.1.8

package/README.md

@@ -1,20 +1,12 @@
-# The Antidote to AI Spaghetti Code
+# The Antidote to AI Spaghetti Code ⭐
 
-AI can write code faster than humans ever could.
+[![GitHub stars](https://img.shields.io/github/stars/skyf0xx/hedgehog?style=social)](https://github.com/skyf0xx/hedgehog/stargazers)
 
-But **speed without discipline creates chaos**.
+AI writes code faster than humans ever could, but speed without discipline creates chaos.
 
-Hedgehog gives AI the guard-rails it needs to **build software that stays clean.**
+Hedgehog gives AI the guard-rails to build software that stays clean: structured workflows, opinionated architecture, composable skills, incremental build loops, and enforced quality gates.
 
-A complete development methodology combining:
-
-- structured workflows
-- opinionated architecture
-- composable skills
-- incremental build loops
-- enforced quality gates
-
-**Build faster, Save context**. Stay aligned. Ship software you can still understand six months later.
+Build faster, save context, stay aligned, and ship software you can still understand six months later.
 
 ![Hedgehog — build software the right way, one step at a time](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/hero.png)
 
@@ -22,27 +14,22 @@ A complete development methodology combining:
 
 1. An opinionated stack
 2. An enforced build order
-3. Agents and skills that make good engineering the default.
+3. Agents and skills that make good engineering the default
 
-## Hedghog's secret to great outcomes
+## Hedgehog's secret to great outcomes
 
-- 🧩 **Progressive layering:** types → schema → backend → UI, each layer built on a stable one beneath it
-- 🎯 **Small context loops:** decompose work into atomic, verifiable changes
-- 🌳 **Self-documenting architecture:** the codebase carries the context, not the AI
-- 🔁 **Traceable evolution:** decisions are preserved through conventional commits
+- **Progressive layering:** types → schema → backend → UI, each layer built on a stable one beneath it
+- **Small context loops:** decompose work into atomic, verifiable changes
+- **Self-documenting architecture:** the codebase carries the context, not the AI
+- **Traceable evolution:** decisions are preserved through conventional commits
 
 ![Just describe what you want](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/curve.png)
 
 ## Why Hedgehog Exists
 
-AI coding starts fast then breaks down.
-
-Context accumulates, prompts get longer, architecture drifts.
-
-Eventually, adding one more feature feels
-dangerous.
+AI coding starts fast, then breaks down. Context accumulates, prompts get longer, architecture drifts. Eventually, adding one more feature feels dangerous.
 
-**The enemy isn't AI. It's the absence of guardrails.**
+Hedgehog's answer: guardrails, not more discipline from the AI.
 
 ## Plans Expire. Structure Doesn't
 
@@ -115,7 +102,7 @@ AI becomes the builder operating inside those constraints — turning ideas into
 
 ## Architecture
 
-Hedgehog is a package of agents and skills. An opinionated stack is used so the build order above is mechanical and enforced by the tooling itself:
+Hedgehog is a package of agents and skills, built on an opinionated stack so the build order above is mechanical and enforced by the tooling itself:
 
 | Layer | Choice | Why |
 | --- | --- | --- |
@@ -124,6 +111,7 @@ Hedgehog is a package of agents and skills. An opinionated stack is used so the
 | Backend | NestJS | Modules naturally mirror Hedgehog's build progression. |
 | ORM | Drizzle + drizzle-zod | Database schema is the single source of truth. |
 | Database | PostgreSQL | Simple, relational, predictable. |
+| Local infra | Docker Compose | Postgres/Redis run identically on every machine. |
 | Platform | Railway | Infrastructure is available from the first commit. |
 | API contract | ts-rest | Contracts are code, not documentation. |
 | Validation | Zod | One schema for runtime and compile time. |
@@ -140,11 +128,9 @@ Hedgehog is a package of agents and skills. An opinionated stack is used so the
 
 ## How Hedgehog Compares
 
-Superpowers and BMAD both improve on raw prompting: one gives the AI good habits, the other gives it a planning process.
+Superpowers and BMAD both improve on raw prompting: one gives the AI good habits, the other gives it a planning process. In both, the order of work is a convention the AI can still break.
 
-But in both, the order of work is a **convention, not a constraint** it's unable to break.
-
-Hedgehog **enforces its build order with tooling** instead: Nx module boundaries, commit hooks, phase gates. The order holds because the tooling holds it, not because the discipline was followed.
+Hedgehog enforces its build order with tooling instead: Nx module boundaries, commit hooks, phase gates. The order holds because the tooling holds it, not because the AI followed the discipline.
 
 | | Superpowers | BMAD | Hedgehog |
 | --- | --- | --- | --- |
@@ -156,3 +142,9 @@ Hedgehog **enforces its build order with tooling** instead: Nx module boundaries
 | **Context per step** | As much as the task pulls in | A full brief, PRD, and architecture doc per story | One module layer at a time (e.g. just the repository, just the controller) |
 | **Finding a bug** | Search wherever the task touched | Search wherever the story touched | Search one layer, in one module, in a fixed order |
 | **Real cost** | No safety net if the model shortcuts its own process | Documentation overhead most solo projects don't need | Less flexibility: the stack and order aren't negotiable |
+
+## Support Hedgehog
+
+If Hedgehog helps you build better AI software, consider giving it a ⭐ on GitHub.
+
+[![GitHub stars](https://img.shields.io/github/stars/skyf0xx/hedgehog?style=social)](https://github.com/skyf0xx/hedgehog/stargazers)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "0.1.5",
+  "version": "0.1.8",
   "description": "Install the Hedgehog build discipline (agents + skills) into a repo.",
   "type": "module",
   "repository": {
@@ -13,6 +13,9 @@
   "bin": {
     "hedgehog": "bin/cli.mjs"
   },
+  "scripts": {
+    "release": "npm version patch -m \"chore: bump version to %s\""
+  },
   "files": [
     "bin",
     "src/agents",

package/src/agents/bootstrap.md

@@ -0,0 +1,110 @@
+---
+name: bootstrap
+description: Use once per invocation, at the start of a new Hedgehog project, to run exactly ONE step of the hedgehog-bootstrap skill's 7-step scaffold, then hand off to a fresh instance of itself for the next step. Not for per-module work — that's hedgehog-loop and its agents (planner, ui-builder, reviewer). Skip entirely if nx.json already exists.
+model: sonnet
+color: green
+tools: Read, Glob, Grep, Edit, Write, Bash
+---
+
+You are the bootstrap role in the Hedgehog discipline. `hedgehog-bootstrap`
+scaffolds the stack and the enforcement config (Nx module boundaries,
+typecheck target, lefthook, commitlint, env validation, phase gate, Docker
+Compose) that makes the stack and build order mechanically true — 7 steps,
+each its own commit. **You run exactly one step per invocation, then
+stop.** Steps 1 and 6 carry the most detail (step 1 bundles the entire
+enforcement config; step 6 has several known-issue workarounds) — reading
+only the one step you're running, not the whole skill file's worth of
+detail for steps you aren't touching yet, is what keeps you inside
+context. A fresh instance of you picks up the next step; nothing about
+this needs to survive in your own memory past your one commit.
+
+You touch no domain modules — no schema, no contract, nothing under
+`libs/<module>/`. That's Phase A, started after all 7 steps close, run by
+`hedgehog-loop` and its own agents.
+
+## Which step is yours
+
+`TODO.md`'s `## Bootstrap` section has one checkbox per step, in order.
+Before doing anything else:
+
+1. Read `TODO.md`. Find the **first unchecked** Bootstrap box — that line
+   is your step, and the only step you touch this run.
+2. Cross-check against the commit log (`git log --oneline --grep="^feat("`)
+   that no commit for this step already exists. TODO.md is the fast path;
+   the commit log is the ground truth if the two ever disagree (e.g. a
+   commit landed but the box wasn't checked). If they disagree, trust the
+   commit log and fix the checkbox before proceeding.
+3. If every Bootstrap box is already checked, there's no step for you to
+   run — stop and say so; `hedgehog-loop` owns everything from here.
+4. If `nx.json` already exists but boxes are unchecked, or a Bootstrap
+   commit exists for a step whose box is unchecked, that's drift between
+   TODO.md and reality, not a fresh start — reconcile the checklist to
+   match the commits actually on disk before running anything, don't
+   re-run a step that already landed.
+
+## Running your one step
+
+Open `hedgehog-bootstrap` and read **only the section for your step**
+(plus "Before running" and "Enforcement wiring" if your step is step 1 —
+that's where the enforcement config lives, bundled into step 1's commit).
+Don't read ahead into later steps' detail; you won't need it and it's
+exactly the context cost this design avoids. Every command, package
+choice, and known-issue workaround for your step lives in that skill
+file — follow it exactly, don't work from memory of a prior project's
+bootstrap (package/generator flags drift upstream).
+
+If your step is step 1: confirm Docker is available (`docker --version`)
+first — stop and point to installing Docker Desktop/Engine if not, rather
+than falling back to a native Postgres/Redis install. Step 1 also wires
+the full enforcement config (Nx tags/`depConstraints`, the
+`@nx/js/typescript` plugin with `composite`/`declaration`, `lefthook.yml`
++ `commitlint.config.js`, `packages/config/env.schema.ts`, the CI phase
+gate script) — this needs to be live before step 2's commit, not added
+later. After `nx init`, verify it didn't leave a stray
+`package-lock.json` next to `pnpm-lock.yaml` — delete and regenerate via
+`pnpm install` if it did, before committing.
+
+If your step is step 7 (`apps/mobile`): check the scope boundary
+`planner` produced at Intake first. Mobile out of scope means this step
+doesn't apply — check its box anyway (skipped-and-confirmed, not
+left dangling for a future run to wonder about) and stop; you're the last
+step either way.
+
+## Closing your step
+
+1. Commit — exactly the message `hedgehog-bootstrap` specifies for your
+   step, once it compiles, lints, and passes tests. A step that doesn't
+   pass the gate isn't done; don't check its box or hand off.
+2. Check that one box in `TODO.md`'s `## Bootstrap` section. Leave every
+   other box and every other section untouched.
+3. If every Bootstrap box is now checked (your step was step 7, or step 6
+   with mobile out of scope): Bootstrap is closed. State that plainly —
+   `hedgehog-loop` owns everything from here, one module at a time. Don't
+   hand off again.
+4. Otherwise: hand off to a fresh instance of yourself for the next step.
+   State plainly which step just closed and which step is next, so
+   whoever re-invokes you (the user or the orchestrating session) knows
+   to just say "continue bootstrap" rather than re-deriving it.
+
+## Constraints
+
+- One step per invocation. Never run two steps in the same context just
+  because you have room left — the discipline is per-commit, not
+  per-context-budget.
+- Never re-run a step whose commit already exists — see "Which step is
+  yours." A felt need to redo a landed step is a Correction Protocol case
+  (patch it at its source, per `hedgehog-loop`), not a re-run.
+- Don't scaffold `apps/mobile` (step 7) unless mobile is explicitly in
+  scope from Intake.
+- Don't add domain schema, contracts, or any `libs/<module>/*` content —
+  that's Phase A, started only after every Bootstrap box is checked.
+- Don't deviate from the locked stack or package choices in
+  `hedgehog-bootstrap`. If a generator or package name changed upstream
+  since that file was written, verify against current docs before
+  running — don't substitute a different library.
+- Local Postgres/Redis always run through the `docker-compose.yml` from
+  step 1, on every host OS. Never a natively-installed Postgres/Redis,
+  even to match a contributor's existing local setup.
+- Don't read ahead into other steps' detail in `hedgehog-bootstrap` beyond
+  what "Running your one step" calls for — that's the context budget this
+  design protects.

package/src/agents/planner.md

@@ -3,7 +3,7 @@ name: planner
 description: Use for Intake (scope boundary + domain vocabulary) at the start of a project, and for determining module scope/order when a new set of domain modules enters play. Not a per-step planner — the step sequence within a module and TODO.md already handle that.
 model: sonnet
 color: yellow
-tools: Read, Glob, Grep, Write
+tools: Read, Glob, Grep, Edit, Write
 ---
 
 You are the planner role in the Hedgehog discipline. The build sequence
@@ -59,7 +59,11 @@ Revising a draft is a normal edit — the Correction Protocol
 3. **`docs/context.md`** — the product narrative, scope boundary, and
    domain vocabulary, written as current state (see below). Mandatory,
    every project gets one.
-4. **Screen/flow notes** — captured by module in
+4. **Root `CLAUDE.md`'s `{{PROJECT_NAME}}` and `{{PROJECT_SUMMARY}}`
+   placeholders** — filled in on the project's first Intake only (see
+   below). A later Intake doesn't touch these unless the project's
+   identity itself changed, not just its scope.
+5. **Screen/flow notes** — captured by module in
    `docs/design/<module>-notes.md`, for `ux-planner` to act on at that
    module's Phase B (see below). Mandatory per module in scope, even when
    nothing was offered for that module.
@@ -206,13 +210,19 @@ on — read which one this is early and let it set the pace.
 5. **Mark it provisional** — consumed by Bootstrap and revised there or
    at the schema step as needed.
 6. **Run Confirm & lock** (below) before writing anything. Only after
-   the person confirms does synthesis proceed to steps 7–8.
+   the person confirms does synthesis proceed to steps 7–9.
 7. **Write `docs/context.md`**: product narrative, scope boundary, and
    the domain vocabulary table, stated as current state only — no record
    of alternatives considered, no "originally X, now Y." A later Intake
    updates this file in place so it keeps reading as current state; it
    never grows into a history.
-8. **File screen/flow notes** under their module in
+8. **Fill root `CLAUDE.md`'s `{{PROJECT_NAME}}` and `{{PROJECT_SUMMARY}}`
+   placeholders**, first Intake only, then delete the installer's HTML
+   comment block at the top of that file (its job — marking what's
+   placeholder vs. constant — is done once both are filled). Leave every
+   other line untouched; the rest of the file is a Hedgehog constant, not
+   project-specific content.
+9. **File screen/flow notes** under their module in
    `docs/design/<module>-notes.md`, one file per module in scope, even
    when nothing was offered for that module (say so plainly instead of
    omitting the file) — verbatim or lightly organized, raw material for
@@ -338,17 +348,27 @@ ask now than fix forward later.
    domain vocabulary — current state only. On a second Intake, update it
    in place to reflect the new current state; don't append a log of what
    changed or why.
-9. **File screen/flow notes** captured during Intake under
-   `docs/design/<module>-notes.md`, one file per module in scope — create
-   it even for a module with no screen input yet, stating that plainly.
-10. **Return a summary**: scope boundary, module list, any open
+9. **Fill root `CLAUDE.md`'s placeholders**, first Intake only —
+   `{{PROJECT_NAME}}`, `{{PROJECT_SUMMARY}}`, then delete the installer's
+   comment block. Skip this step entirely on a second or later Intake;
+   the file has no other project-specific content to update.
+10. **File screen/flow notes** captured during Intake under
+    `docs/design/<module>-notes.md`, one file per module in scope — create
+    it even for a module with no screen input yet, stating that plainly.
+11. **Return a summary**: scope boundary, module list, any open
     questions.
 
 ## Constraints
 
 - Never write or modify application code. Read-only against the
-  codebase; you may write `TODO.md`, `docs/context.md`, and
-  `docs/design/<module>-notes.md`.
+  codebase; you may write `TODO.md`, `docs/context.md`,
+  `docs/design/<module>-notes.md`, and — first Intake only — root
+  `CLAUDE.md`'s `{{PROJECT_NAME}}`/`{{PROJECT_SUMMARY}}` placeholders and
+  its installer comment block.
+- Never touch root `CLAUDE.md` outside those placeholders. Every other
+  line is a Hedgehog constant (stack, layout, rules, agent/skill
+  pointers) shared verbatim across every Hedgehog project — not
+  project-specific content to edit, extend, or "improve."
 - `docs/context.md` and `docs/design/<module>-notes.md` are not
   optional — every project gets the former, every module in scope gets
   the latter, regardless of how much material Intake produced.

package/src/skills/hedgehog-bootstrap/SKILL.md

@@ -29,6 +29,7 @@ One opinionated stack, applied the same way on every project:
 | Backend framework | NestJS |
 | ORM | Drizzle (+ `drizzle-zod`) |
 | Database | PostgreSQL |
+| Local infra | Docker Compose (Postgres + Redis) |
 | Platform | Railway |
 | API contract | ts-rest |
 | Validation | Zod |
@@ -106,6 +107,13 @@ project misconfiguration or a corrupted pnpm store — check **Known issue:
 esbuild postinstall version mismatch** below first; this is a known,
 deterministic collision, not something to misdiagnose from scratch.
 
+Confirm Docker is available (`docker --version`) before step 1. Local
+Postgres/Redis run through Docker Compose on every host OS — see **Local
+infra: Docker, always** below. No Docker installed: stop and point the
+user to installing Docker Desktop (macOS/Windows) or Docker
+Engine (Linux) rather than falling back to a natively-installed
+Postgres/Redis.
+
 ## Steps (run in sequence, one commit per step)
 
 ### 1. Nx workspace + `packages/config`
@@ -134,6 +142,18 @@ root; if present, delete it and run `pnpm install` to regenerate
 `pnpm-lock.yaml` before continuing to step 2. Don't assume `nx init`
 respects the locked package manager — verify.
 
+`nx init` also does not create `pnpm-workspace.yaml`. Without it, pnpm
+doesn't recognize `packages/*` or `apps/*` as workspace members —
+`pnpm add -w` fails with `ERR_PNPM_ADDING_TO_ROOT`-adjacent errors, and
+cross-package `pnpm add` for a lib silently installs to the wrong place.
+Create it manually right after `nx init`, before the first `pnpm add`:
+
+```yaml
+packages:
+  - 'packages/*'
+  - 'apps/*'
+```
+
 Then generate the first lib. The **first** `@nx/js:lib` call materializes
 the whole workspace shape (`tsconfig.base.json`, root `eslint.config.mjs`,
 `.prettierrc`, `vitest.workspace.ts`, the `packages/` layout, and the
@@ -150,7 +170,16 @@ files:
 - `packages/config/eslint-base.js` — flat config, extended by every
   app/lib. Include `@nx/enforce-module-boundaries` and `depConstraints`
   from Enforcement wiring below, verbatim.
-- `packages/config/prettier.js` — includes `prettier-plugin-tailwindcss`.
+- `packages/config/prettier.js` — **don't** add `prettier-plugin-tailwindcss`
+  here. The plugin parses every file prettier touches (not just files with
+  Tailwind classes) and throws (`TypeError: e.charAt is not a function` /
+  `a.startsWith is not a function`) on any file when no Tailwind config is
+  resolvable yet — which is every project from step 1 through step 5, since
+  Tailwind doesn't arrive until `apps/web` in step 6. Loading it globally
+  here breaks `nx format:write` and any bare `prettier --check` for the
+  first five steps of every project. Add the plugin to `apps/web`'s own
+  prettier setup (extending this base config) once Tailwind exists, not to
+  the shared base.
 - `packages/config/env.schema.ts` — the Zod env schema from Enforcement
   wiring below (`DATABASE_URL`, `BETTER_AUTH_SECRET`, `REDIS_URL`,
   `NODE_ENV`; extend per project as new infra is added later).
@@ -158,6 +187,53 @@ files:
   declares the project tags table below (`scope:*`, `type:*`) as comments
   or a lookup, so every later generator step tags its project correctly.
 
+Root `eslint.config.mjs` is itself ESM (`.mjs`), which surfaces a Node
+warning ("Module type of file... is not specified") unless the root
+`package.json` declares `"type": "module"`. Setting that is correct and
+worth doing — but it changes how Node resolves *every* plain `.js` file
+in the repo from CommonJS to ESM by default. Several files later steps
+generate are CommonJS (`require`/`module.exports`) and will break with
+`ReferenceError: require is not defined` or `module is not defined` the
+moment `"type": "module"` is set: `apps/*/webpack.config.js`,
+`commitlint.config.js`, and any hand-written CommonJS tool script (e.g.
+`tools/phase-gate.js`). Rename each to `.cjs` as it's created (or convert
+its content to ESM, as `next.config.js` supports natively via
+`export default`) rather than discovering the break later when `nx
+graph` or a generator that depends on the project graph fails
+opaquely — Nx surfaces this as "Failed to process project graph" pointing
+at the offending file, not as a module-system explanation.
+
+Add a root `docker-compose.yml` provisioning Postgres and Redis for local
+dev, regardless of host OS (macOS, Windows, Linux) — see **Local infra:
+Docker, always** below for why this isn't optional. `DATABASE_URL` and
+`REDIS_URL` in `.env` point at the compose services from the first
+commit, matching the env schema below.
+
+```yaml
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: app
+    ports:
+      - '5432:5432'
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - '6379:6379'
+    volumes:
+      - redis-data:/data
+
+volumes:
+  postgres-data:
+  redis-data:
+```
+
 Add an `esbuild` override to root `package.json` in this step, before step
 2 installs `drizzle-kit` — see **Known issue: esbuild postinstall version
 mismatch** below for why.
@@ -209,6 +285,20 @@ structured logging. Call `loadEnv()` at the top of `apps/api/src/main.ts`.
 Tag: `scope:api`. No controllers beyond a health check — domain
 controllers arrive per module in Phase A.
 
+`@nx/nest:app` also scaffolds a companion `apps/api-e2e` project wired to
+Jest (`jest.config.cts`), not Vitest — inconsistent with the locked stack.
+Convert it: delete the Jest config, add a `vitest.config.mts` (mirroring
+`packages/db`'s), and give `apps/api-e2e`'s `tsconfig.spec.json` the same
+`composite`/`declaration` treatment as above. Rename its target from the
+plugin-inferred `test` to an explicit `e2e` — an HTTP e2e suite needs a
+live server (`dependsOn: ["api:build", "api:serve"]`), and if it keeps the
+default `test` name, `nx affected -t test` (what lefthook's pre-commit
+hook runs on every commit, per the Commit gate below) will try to boot a
+server on every commit. Exclude `apps/api-e2e` from the `@nx/vitest`
+plugin's auto-inference in `nx.json` (`"exclude": ["apps/api-e2e/**"]` on
+that plugin entry) so it stops registering a `test` target for this
+project at all, keeping only the manually-defined `e2e` target.
+
 Commit: `feat(api): nest shell + global guard + pino`
 
 ### 5. `apps/worker` — BullMQ seam (Redis, no consumers yet)
@@ -230,17 +320,73 @@ Commit: `feat(worker): bullmq seam, no consumers`
 ```bash
 npx nx g @nx/next:app apps/web
 pnpm add @tanstack/react-query
-pnpm dlx shadcn@latest init
 ```
 
-Wire the TanStack Query provider at the root layout. `shadcn init` writes
-`apps/web`'s base theme (CSS variables for color, radius, light/dark
-mode) — set the actual palette here, once, rather than leaving ShadCN's
-placeholder values for `ui-builder` to inherit unnoticed on the first
-screen. Light/dark mode toggle wiring belongs here too, not as a
-per-screen decision later. No screens or hooks yet — Phase B doesn't
+**Do not run `pnpm dlx shadcn@latest init` (or `shadcn add`) against
+`apps/web` directly.** The shadcn CLI hard-requires a `package.json` in
+its target directory to detect the project; an Nx-generated app under
+this stack has no per-app `package.json` (dependencies live at the
+workspace root). Finding none, the CLI's default behavior is to offer —
+and on `--yes`, silently proceed — to scaffold a *brand-new*
+`create-next-app` project **inside** `apps/web`, complete with its own
+nested `.git`, its own lockfile, and its own `package.json`. This doesn't
+error; it succeeds and leaves a corrupted nested project (e.g.
+`apps/web/web/`) that has to be manually detected and deleted. There is
+currently no supported non-interactive flag that makes shadcn's CLI
+target an existing package-json-less directory in place.
+
+Build the base theme by hand instead: write `apps/web/components.json`
+directly (style, aliases, `tailwind.css` path — the `css` field), add
+`class-variance-authority`, `clsx`, `tailwind-merge`, `lucide-react`, and
+`@radix-ui/react-slot` as dependencies, write `apps/web/src/lib/utils.ts`
+(the standard `cn()` helper), and hand-write the CSS variable theme block
+(light/dark, using shadcn's published default token values) into
+`apps/web`'s global stylesheet. Individual components (e.g. `button.tsx`)
+can then be hand-written from shadcn's published source for that
+component — small, stable, well-known files — rather than fetched via the
+CLI. Set the actual palette here, once, rather than leaving placeholder
+values for `ui-builder` to inherit unnoticed on the first screen. Light/
+dark mode toggle wiring belongs here too, not as a per-screen decision
+later.
+
+Wire the TanStack Query provider at the root layout (App Router: a
+`'use client'` `Providers` wrapper component, since the root layout
+itself is a server component). No screens or hooks yet — Phase B doesn't
 start until Phase A closes for at least one module. Tag: `scope:web`.
 
+**Set `NODE_ENV` explicitly on the `build` target, or the production
+build silently runs in dev mode under Nx.** Nx's task runner sets
+`NODE_ENV=development` by default for every task unless a target
+overrides it — including a plain `nx:run-commands` target running `next
+build`. Next.js's production build pipeline assumes `NODE_ENV=production`;
+running it under `development` produces a build that compiles and
+appears to succeed on individual pages but crashes prerendering the
+auto-generated `/_global-error` route with `TypeError: Cannot read
+properties of null (reading 'useContext')` — a React-internals mismatch
+from the dev/prod build split, not an app bug. This only reproduces
+through `nx run web:build`; the identical `next build --webpack` run
+directly from `apps/web` succeeds, because a bare shell has no `NODE_ENV`
+set and Next defaults it correctly itself — which makes the symptom look
+Nx-specific and environment-related rather than what it is (a task-runner
+default silently overriding a value the build assumes). Set it on the
+`build` target only, in `apps/web/project.json`:
+
+```json
+{
+  "targets": {
+    "build": {
+      "options": {
+        "command": "next build --webpack",
+        "env": { "NODE_ENV": "production" }
+      }
+    }
+  }
+}
+```
+
+Leave `dev` alone — it correctly wants `NODE_ENV=development`, which is
+also what Nx already defaults it to.
+
 Commit: `feat(web): next shell + query provider + base theme`
 
 ### 7. `apps/mobile` — Expo shell (only if mobile is in scope)
@@ -315,6 +461,51 @@ e.g. `libs/orders/port`, `libs/orders/repository`, `libs/orders/service`.
 Building out of order (a controller before a service exists, a hook
 reaching into `apps/api` directly) fails `nx lint`.
 
+The rule list above is illustrative, not exhaustive — `@nx/enforce-
+module-boundaries` denies by default for any project whose tag isn't
+named as a `sourceTag` in some `depConstraints` entry ("A project without
+tags matching at least one constraint cannot depend on any libraries").
+`packages/db` (`scope:db`, `type:adapter`) and `apps/api` (`scope:api`)
+both hit this the moment they're generated and tagged in steps 2 and 4,
+because neither `type:adapter` nor `scope:api` has an entry above. Add
+constraints for every tag combination as it's introduced, not only the
+ones in the illustrative list — at minimum `type:adapter` (needs
+`type:util`, for `packages/config`) and `scope:api` (needs `type:port`,
+`type:service`, `type:util` — never `scope:db` directly; `apps/api`
+reaches storage through a module's repository/service, not by importing
+`packages/db` itself).
+
+### Typecheck target (required before the commit gate can work)
+
+`lefthook.yml`'s pre-commit below runs `nx affected -t typecheck`, but
+`@nx/js:lib` and `@nx/nest:app` don't register a `typecheck` target on
+their own — it only exists once the `@nx/js/typescript` plugin is
+registered in `nx.json`, added in step 1 alongside the eslint and
+vitest plugins:
+
+```json
+{
+  "plugin": "@nx/js/typescript",
+  "options": { "typecheck": { "targetName": "typecheck" } }
+}
+```
+
+Registering the plugin isn't sufficient on its own, either: `tsc
+--build`'s composite-project mode (what the inferred `typecheck` target
+actually runs) requires every `tsconfig.lib.json` and `tsconfig.spec.json`
+it touches to set `"composite": true` and `"declaration": true`. The
+generators don't set these — every `@nx/js:lib` and `@nx/nest:app`
+project needs both added by hand to `tsconfig.lib.json` /
+`tsconfig.app.json` and `tsconfig.spec.json` right after generation, or
+`nx run <proj>:typecheck` fails immediately with `TS5069: Option
+'emitDeclarationOnly' cannot be specified without specifying option
+'declaration' or option 'composite'`. If a project's spec file imports
+from its own lib source (the common case), `tsconfig.spec.json` also
+needs an explicit `references` entry pointing at `tsconfig.lib.json`, or
+`tsc` reports `TS6307: File '...' is not listed within the file list of
+project`. Do this for `packages/config` in step 1 so the pattern is
+established before every later step repeats it.
+
 ### Commit gate (lefthook + commitlint)
 
 Enforces one coherent change, tested, conventionally committed. Runs on
@@ -441,10 +632,30 @@ One shared config, extended everywhere:
 
 - `packages/config/eslint-base.js` — flat config, extended by every
   app/lib.
-- `packages/config/prettier.js` — includes `prettier-plugin-tailwindcss`.
+- `packages/config/prettier.js` — the shared base, *without*
+  `prettier-plugin-tailwindcss` (see step 1 — it belongs in `apps/web`'s
+  own config once Tailwind exists, not the shared base).
 
 A per-app override request signals to fix the base config at the source.
 
+## Local infra: Docker, always
+
+Postgres and Redis run through the `docker-compose.yml` from step 1 on
+every project, on every host OS — macOS, Windows, Linux alike. This isn't
+a convenience default; it's what makes "clone the repo, run the stack"
+mechanically true regardless of who's building. A natively-installed
+Postgres or Redis (Homebrew, an existing Windows service, a system
+package) is a per-machine setup step that isn't in the commit history and
+isn't reproducible on the next machine — exactly the kind of
+tribal-knowledge dependency Hedgehog's enforcement exists to remove.
+
+Don't offer a "native install" path as an alternative, even if a
+contributor already has Postgres running locally for another project. One
+mechanism, every machine: `docker compose up -d` before `pnpm install`,
+every time. If Docker genuinely can't run on a target machine, that's a
+platform-support gap to raise, not a reason to quietly fall back to a
+native install for that one contributor.
+
 ## Known issue: esbuild postinstall version mismatch
 
 `@nx/vite` (step 1) declares `esbuild` as an *optional* peer dependency
@@ -494,3 +705,7 @@ gated by lefthook, each its own commit.
 - Each of the 7 steps is its own commit, in order — same unit-of-work
   discipline as every other step in the discipline, even though this is
   infra rather than a domain module.
+- Local Postgres/Redis always run through the `docker-compose.yml` from
+  step 1, on every host OS. Never substitute a natively-installed
+  Postgres/Redis, even to match a contributor's existing local setup —
+  see **Local infra: Docker, always**.

package/src/templates/CLAUDE.md

@@ -66,6 +66,8 @@ steps from memory:
 
 ### The agents — delegate the judgment calls
 
+- **`bootstrap`** — runs `hedgehog-bootstrap`'s 7 steps once, at project
+  start, after Intake. Skip if `nx.json` already exists.
 - **`planner`** — Intake (scope boundary + domain vocabulary) at project
   start, and module scoping when new scope enters play. Writes `TODO.md`,
   `docs/context.md`, and `docs/design/<module>-notes.md`.
@@ -81,11 +83,13 @@ steps from memory:
 ### Stack (locked)
 
 Nx monorepo · pnpm · **NestJS** (all domain logic + DB access) · **Drizzle**
-(+ `drizzle-zod`) · **PostgreSQL** · Railway · **ts-rest** contracts · **Zod**
-validation · **Better Auth** · **TanStack Query** hooks · **Next.js** + ShadCN
-+ Tailwind (web, UI only) · Expo + React Native Reusables + NativeWind
-(mobile, optional) · **BullMQ + Redis** (queues) · Pino logging · Vitest +
-Playwright (tests) · Conventional Commits + commitlint + lefthook · Sentry.
+(+ `drizzle-zod`) · **PostgreSQL** · **Docker Compose** (local Postgres +
+Redis, every host OS) · Railway · **ts-rest** contracts · **Zod**
+validation · **Better Auth** · **TanStack Query** hooks · **Next.js** +
+ShadCN + Tailwind (web, UI only) · Expo + React Native Reusables +
+NativeWind (mobile, optional) · **BullMQ + Redis** (queues) · Pino logging ·
+Vitest + Playwright (tests) · Conventional Commits + commitlint + lefthook ·
+Sentry.
 
 Don't substitute libraries. If a package or generator name changed
 upstream, verify against current docs before running — don't swap in a
@@ -94,6 +98,7 @@ different library.
 ### Layout
 
 ```
+docker-compose.yml   local Postgres + Redis — every host OS, no native install
 apps/
   web        Next.js — UI only
   mobile     Expo — optional
@@ -130,6 +135,9 @@ docs/
   (lefthook gate).
 - **Fix wrong steps at the source** via the Correction Protocol — never a
   downstream workaround.
+- **Local Postgres/Redis always run through `docker-compose.yml`**, on
+  every host OS. Never a natively-installed Postgres/Redis, even to match
+  a contributor's existing local setup.
 - **`packages/config` is the single source** for shared config. A per-app
   override request means fix the base config, not add an override.
 
@@ -168,9 +176,10 @@ context small:
 - **A cleared or new session recovers by reading `TODO.md`,
   `docs/context.md`, and the commit log**, never by needing the prior
   conversation.
-- **Delegate heavy work to agents.** Intake elicitation (`planner`),
-  screen builds (`ui-builder`), and reviews (`reviewer`) each run in their
-  own isolated context — so that work doesn't pile up in the main thread.
+- **Delegate heavy work to agents.** The project scaffold (`bootstrap`),
+  Intake elicitation (`planner`), screen builds (`ui-builder`), and
+  reviews (`reviewer`) each run in their own isolated context — so that
+  work doesn't pile up in the main thread.
 - **Don't paste large context back in.** If you find yourself
   re-explaining the architecture, stop — it's fixed and stated in this
   file, not something to reconstruct. If you need a project specific, read

package/src/templates/TODO.md

@@ -10,7 +10,7 @@ has one, written by planner at Intake. -->
  
 ## Bootstrap
  
-- [ ] Nx workspace + `packages/config`
+- [ ] Nx workspace + `packages/config` (incl. `docker-compose.yml` for local Postgres/Redis)
 - [ ] `packages/db` — Drizzle client
 - [ ] `packages/auth` — Better Auth config
 - [ ] `apps/api` — Nest shell, global guard, Pino