Guides & How-Tos
Plain-English explainers for the team. These are teaching documents, not contracts — when a guide and an authoritative source disagree, the source wins (the guide names its sources at the bottom).
These are written in markdown and rendered to HTML automatically by the doc-site generator (node .claude/lib/render-docs-html.js → docs-html/, which is gitignored and rebuilt per machine). Edit the markdown here; never hand-edit the HTML.
What’s here
| Guide | For | What it covers |
|---|---|---|
forge-deliver-explained.md |
Anyone running /forge-deliver |
How the delivery orchestrator works end to end, what’s expected of you at each checkpoint, and which model/effort to run it with. The full explainer. |
forge-deliver-cheatsheet.md |
Dinil, Biseni, Nanndish (and future joiners) | One-page quick reference — the commands, the checkpoints, the loop, the gotchas. Print-it-and-pin-it. |
../../demo-kit/README.md |
Whoever runs a client demo | The capture-app demo with prepared sample cards, loading realistic fictional data into the dev or a local CRM, and a local CRM as a fallback. |
f5-a-worked-example.md |
Learning by example | One real feature (F5-a, “Sign in with Microsoft and sign out”) walked through the whole pipeline with the actual branch and PR names. |
tech-stack-reference.md |
New joiners, anyone orienting | The plain-terms map of the whole stack — frontend, backend, how they talk, auth, hosting, the AI layer, and the locked decisions. |
aws-setup-explained.md |
Anyone working on or with the cloud estate | The AWS setup in plain terms — regions, accounts and the management account, users versus roles, how the CLI gets in, svc-github versus svc-harness, reaching the database from a laptop (Mac and Windows), making UAT and production from the Terraform, and why the database password rotation can break dev. |
email-in-the-crm-explained.md |
The whole team, and anyone explaining email to Empire Teas | How the CRM uses each user’s Microsoft 365 mailbox — the live inbox, what is stored (only linked email, in full), how past email is found, block lists, and how sign-in and Microsoft access tokens work. |
test-runs-explained.md |
The whole team | What your PR’s record runs now (the tests your change needs; on a frontend PR into main, only the browser tests it selects), the counted retry, what the nightly full run on the lead’s Mac runs and reports, and what to do with a nightly-red issue. |
forge-harness-faq.md |
The whole team | Common questions about working in the harness — the PRD trichotomy, gate order, hooks, sequencing, sessions, and which model/effort to run. A companion to the rules, not a replacement. |
Conventions for this folder
- Audience is a teammate reading cold. Follow the project
## Writingrule (.claude/CLAUDE.md): plain verbs, standard terms, no invented jargon, state context up front. - Guides teach; they don’t govern. A guide can quote a rule but is never the source of truth for it. Anything version- or state-specific (“wave 1 is open”, “React 19”) is true when written — re-check the code or the authoritative doc.
- Diagrams: use fenced
```mermaidblocks — the doc-site renders them client-side, light/dark aware.