Gridwillow blueprint

Turn a system into a .bp file. The compiler renders it as an isometric engineering drawing: extruded blocks on a hairline grid, wired by orthogonal connectors with travelling packets, with a hover card on everything and an inspector behind every block.

You write one text file and nothing else. The renderer is fixed. That constraint is what makes two blueprints of two unrelated systems readable side by side.

Read reference/language.md before writing a line — it is the whole grammar and the shape table. Read reference/voice.md before writing prose; the prose is most of the value and the default register is wrong for it.

The procedure

Work the phases in order. The single most reliable way to produce a drawing full of plausible, wrong connections is to start writing before you have looked.

1. Survey — write nothing

• The manifest: Cargo.toml, package.json, pyproject.toml, go.mod. Real dependencies tell you what the system is more honestly than the README does.
• Every entrypoint: main.*, bin/*, cmd/*, server bootstraps, CLI definitions, exported handlers, worker registrations, cron entries.
• The tree, two levels deep (glob). Note which directories are large and which are one file pretending to be a package.
• Migrations or schema, if present. Tables are the most honest map of a system's nouns you will find.
• Deployment: compose files, Terraform, k8s manifests, railway.json, Dockerfile. This is where the infrastructure blocks come from.

By the end you can say in one sentence what the system does when it runs. If you cannot, keep reading.

2. Blocks — 15 to 40 of them

A block is a subsystem: something a maintainer would name out loud in a design conversation. Almost never one file; almost never a whole top-level directory either.

Under 15 blocks the drawing is trivial. Over 40 it is soup. Collapse leaf modules into their parent and mention them in the parent's why — "also holds the retry policy and the backoff table" is worth more than two extra blocks.

Choose the kind word a reader recognises, not the most technically precise one. Redis used only as a job queue is a topic, not a cache.

Group into 2–6 groups, ordered so reading the sidebar top to bottom walks the system in the order it actually runs.

3. Connections — only real ones

Work outward from the entrypoints. lsp is the right tool here: definitions, references and implementations give you the call graph directly, where grep gives you guesses.

The hard rule. Every connection names something concrete in carry — a type signature, a function, an SQL table, an HTTP route, a topic, a channel type. If you cannot name what crosses the line, the line is not real. Delete it.

This exists because the failure mode of generated architecture diagrams is boxes joined by vibes. Twenty true connections beat sixty where half are "relates to".

Spend vol. It drives packet density, which is the only way the drawing shows where the hot path is. Do not set everything to 0.5.

4. Inspector detail — be generous

fact, list, link and env fill the panel that opens on click. This is where a blueprint stops being a picture and becomes a reference:

• fact Engine = Postgres 16 — versions, regions, replica counts, retention, ports, owners, timeouts.
• list Tables = orders, refunds — table names, indexes, topics, routes, flags.
• link Runbook = https://… — runbooks, dashboards, design docs.
• env DATABASE_URL — what it needs to run.

A database block carrying its real table names is worth more to somebody new than three paragraphs of prose.

5. Narrative

Two tabs: what it does, how it's built. Audience is a competent engineer who has never seen this system and has four minutes. See reference/voice.md.

Use 6–12 [[phrase|block_id]] links across the panel. They are what makes the prose and the drawing feel like one object rather than two things on a screen.

6. Check, then hand over

bp check <name>.bp

Fix every error. Read the warnings and fix the ones that are right — they are about readability, and most of them are right.

Two things bp check cannot see, so verify them yourself:

• Every path in src exists. Check with glob; do not assume.
• Every carry is true of the code, not merely plausible.

Then tell the human, in three or four sentences, what surprised you about the system. That is often worth more than the drawing.

Rules that are not negotiable

• Never edit the renderer, the compiler, or the exported HTML. One file.
• Never invent a kind word or a connection kind. Both sets are closed; reference/language.md has them.
• Never use markdown or HTML in prose. Two inline markups exist and no others.
• Never guess a file path or a table name. Look it up.
• @col,row and via are last resorts, used after seeing a render, not while writing.

Handing it back

bp export <name>.bp        # one self-contained HTML file

Or the human opens the .bp in the Gridwillow app, which redraws on every save. If they are iterating, point them at the app rather than re-exporting for them.