git:20260728.f1370ad to git:20260824.ad76754

- ## CRITICAL: Never checkout branches in this directory

-

- This is the main worktree. Switching branches here breaks all parallel agents.

-

- **Always create a worktree:**

- ```bash

- git worktree add "$(git rev-parse --show-toplevel)/../worktrees/<branch-name>" -b <branch-name>

- cd "$(git rev-parse --show-toplevel)/../worktrees/<branch-name>"

- ```

-

- **Before any work, verify:** `pwd | grep -q "worktree" || echo "STOP: create a worktree first"`

-

- ## Before debugging infrastructure

-

- Read `docs/explanation/infrastructure-lessons.md` first. It records failures that

- already cost significant time here — silent OIDC trust mismatches, SSM ciphertext

- passing as a value, Vercel preview failures that are actually a Neon branch quota,

- stale CLI versions producing wrong signatures. Several present with symptoms far from

- their cause, and at least three were made worse by reasoning about how something

- "should" work instead of printing the actual value.

-

- ## Project Quick Reference

-

- | Directory | Purpose |

- |-----------|---------|

- | `packages/core/` | Shared library — parsing, verification, linting, risk assessment |

- | `cli/` | CLI tool (`dossier verify`, `dossier search`, etc.) |

- | `mcp-server/` | MCP server — tools/resources/prompts for LLM integration |

- | `registry/` | Vercel-deployed registry API |

- | `packages/worktree-pool/` | Pre-warmed git worktree management |

-

- ```bash

- make build-all # build core → mcp-server + cli (skip lint)

- make build # lint then build

- make test # test all workspaces

- make check # biome format + lint with auto-fix

- ```

-

- - Node 20+ required (vitest v4 + vite v7 dropped Node 18)

- - Linter/formatter: **Biome** (not ESLint/Prettier) — `npx biome check --write .`

- - Build order: core first, then mcp-server and cli (both depend on core)

- - MCP integration: see `mcp-server/README.md`