Blueprint Manual Skill

# Build a "Making <Project>" architecture field manual

You are going to build a book-style architecture manual for the project in this repository, modelled on makingsoftware.com. It is a small static site: plain HTML, one CSS file, one JS file, no build step, no framework. A new engineer should be able to open `index.html` and understand how the system works in an afternoon.

Replace `<Project>` with the real project name everywhere. Put the manual in `docs/making-<project>/` (or the folder I name). Do not commit it unless I ask.

## 1. Research first, from sources, not memory

Before you write a word:

1. Read the existing architecture docs, READMEs, ADRs and any system diagrams in the repo.

2. Read the recent git log (last ~40 commits on the main branch) to learn what changed lately.

3. Walk the code: entry points, domain layer, data layer, background jobs, integrations, deploy config.

4. For every claim you plan to make, find the file, table, event or function that proves it. If you cannot find proof, soften the claim ("the design intends...") or drop it.

5. Make a list of open questions (things the code does not settle). Give each an id like `Q-A1`, `Q-B2` (letter = chapter area, number = sequence). These ids must stay stable across refreshes.

## 2. Structure

- `index.html`: cover, one whole-system map (each node links to its chapter), contents list, "how to read this", colophon (sources used, date, "the docs folder is the source of truth").

- 8 to 12 chapter pages, `01-<slug>.html` ... `NN-<slug>.html`. Choose chapters that match THIS system. Typical shape: overall shape and tenancy; how a request flows; how data gets in; the core domain workflow; durability and background jobs; outbound channels and integrations; money or the critical side-effect path; the AI or automation layer if any; how it ships and is observed.

- `glossary.html`, rendered from a `GLOSSARY` object in the JS file.

- `assets/style.css`, `assets/site.js`, `assets/fonts/` if needed.

Every chapter and every `h2` section title is a question a new engineer would ask. Short and literal: "How does a job start?" Not "What really happens when you press Go?"

Each chapter has the same shape:

1. Chapter head: `.kicker` -> `<h1>NN Question?</h1>` -> `<p class="lede">`. The number is plain text inside the h1.

2. Exactly 4 `h2` question sections. Each: prose that explains **why**, a figure that shows **how**, a code box that says **where** (real file paths and identifiers from the repo).

3. A `key-ideas` list of 4 items.

4. A `questions` list of open question ids with one sentence each.

Prev/next links, section numbers and figure numbers are generated by JS. Never type them by hand.

## 3. Writing standard: ASD-STE100 Simplified Technical English

All prose (ledes, body, callouts, rule boxes, figure captions, diagram notes, key ideas, open questions, glossary definitions) follows STE:

- Procedural sentences: 20 words max. Descriptive sentences: 25 words max. Paragraphs: 6 sentences max, one topic each.

- Imperative for instructions. Condition first: "If the sync fails, the worker retries."

- Active voice. Simple tenses only. No "-ing" continuous forms. Keep articles and verbs.

- One word, one meaning. Define a fixed vocabulary for this project (for example: "run" never "execution"; "provider" never "vendor"; "paged" never "paginated") and use it everywhere. Put it in the glossary.

- No phrasal verbs or idioms ("kick off", "spin up", "under the hood", "fire and forget"). No filler or marketing words ("simply", "just", "elegant", "obviously", "actually").

- Use a list for more than two items. Rule boxes start with the command, then the reason: "Do not query a domain table outside its manager. The manager applies tenancy and paging."

- No em dashes or en dashes anywhere. Use a hyphen, a comma or a new sentence.

- Code excerpts are labelled "simplified" or "abridged". Payloads are "representative".

## 4. Locked design rules

Principle: minimal CSS, minimal HTML. One rule per concern, no decorative wrappers, no per-page styling, no one-off variants. Prefer deleting a rule over adding an override.

**Layout**

- Two columns: main content (`1fr`) left, a 250px sticky right panel (`.rail`) right. No left sidebar.

- Fluid width. No `max-width` on any text or block. The only fixed width is the glossary tooltip (300px).

- One block width. Every block (figure, callout, rule box, code box, table, key ideas, questions, prev/next) is exactly as wide as the paragraphs. Nothing floats into a margin.

**Top bar**: inside `<main>`, not sticky, holds only the site brand and the current chapter label.

**Right panel**, top to bottom: REFERENCE (Cover and contents, Glossary); CONTENTS (all chapters, current one expanded to its h2 sections with scrollspy); THEME switch. Hidden below 980px.

**Typography**

- `h1`, `h2`, `h3` share one rule: same font and colour everywhere. Per-element rules set only size, line-height, margin. `h4`-`h6` are plain small labels.

- Drop cap only on the first body paragraph of a chapter (`.prose > h2:first-of-type + p::first-letter`). Not on the lede, cover or glossary intro.

- Section numbers are small grey mono.

**Figures**: same frame everywhere, full column width. Each SVG draws at its own viewBox width and is centred, so diagram text is the same size in every figure. ViewBox width <= ~880px. Every figure has `<figcaption><b>Title.</b> one sentence</figcaption>`.

**Callouts**: `<aside class="side"><span class="tag">Label</span>text</aside>` right after the paragraph it annotates. Rendered inline, full width, never floated.

**Themes**: two themes switched from the right panel and saved in localStorage; an inline `<head>` script applies the saved theme before first paint. Theme A is the project's own palette and fonts. Theme B is a "blueprint" look: near-white paper, one strong accent, a dotted figure grid, a monospace display face for headings and labels, a serif for body. All theme B rules live at the end of the CSS under `html[data-theme="blueprint"]`. All colours are CSS variables (`--accent`, `--dark`, `--line`, `--face`, ...). Never hardcode a hex in a page, an inline SVG or a component rule. Never `text-transform: uppercase` headings or diagram text (it mangles identifiers).

## 5. Interactive figures (JSON-driven, rendered by site.js)

**Diagram** (`<figure class="fig" data-diagram>` with a `<script type="application/json">`):

`{ w, h, depth, hint, zones[], nodes[], edges[], texts[] }`

- node: `id, x, y, w, h, label, sub, tag, note, href, kind`. `kind` values: `accent`, `dark`, `ext` (third party), `ghost` (designed, not built), `warn`, `store` (cylinder), `flat`, `pill` (states), `diamond` (decision).

- edge: `from, to, label, kind` (`dashed`, `forbid`), `via: [[x,y],...]` for elbows, `packet: true` for an animated dot, `both` for two arrowheads.

- zone: `x, y, w, h, label` for ownership or environment boundaries.

- Hovering a node shows its `note` in a readout. Lay out on a grid (columns ~180px, rows ~90px). Leave >= 40px between boxes joined by a labelled edge. Never route a line through a box.

**Sequence** (`<figure class="fig" data-seq>`):

`{ w, actors: [{id, label, sub}], msgs: [{from, to, label, reply, note, payload}] }`

Generated Step / Back / Play / Reset controls and a readout. 5-6 actors, 8-12 messages, labels under ~32 characters, detail in `note` and `payload`.

**Glossary tooltips**: `<span data-term="key">word</span>` shows the definition on hover. Unknown keys warn in the console.

Hand-drawn SVG is fine for one-off illustrations; use CSS variables for every colour.

## 6. Verify before you say done

1. Open every page in a headless browser. Zero console errors.

2. Screenshot every figure. Fix label collisions, lines through boxes, clipped text.

3. Screenshot at 1440px and 1280px in both themes. Check: top bar ends at the panel; panel order Reference -> Contents -> Theme; h1 is one line with its number; h1/h2/h3 share one style; drop cap only on the first section paragraph; every block is the same width as the text; `grep -n "max-width" assets/style.css` shows only the tooltip and the media query.

4. Run a check that no em or en dash exists in any file.

5. Report per chapter: what you wrote and which claims you verified in code. List claims you could not verify and softened.

## 7. Refreshing later

When asked to refresh: re-read the sources and the git log since the colophon date, write a change list per chapter before editing, edit in place keeping each chapter's shape, keep Q-ids stable (mark resolved ones), update the colophon date, re-run section 6.

Start with section 1 now. Show me the chapter list and the vocabulary you chose before writing pages.