source: .forge/guides/README.md · generated — edit the markdown, not this file

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 ## Writing rule (.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 ```mermaid blocks — the doc-site renders them client-side, light/dark aware.

Generated from .forge/guides/README.md by .claude/lib/render-docs-html.js. Markdown is canonical.