How this wiki is maintained

A wiki page that describes behaviour the code no longer has is worse than no page at all. It produces failed prints, and it burns the trust this whole project runs on.

Nothing in a build can catch that — Astro will happily render a confidently wrong sentence. So there is a gate, and this page is the contract it enforces.

Every page carries frontmatter

---
title: Drawing channels
description: The three tools, how snapping works, editing nodes and segments.
sourceRefs:
  - src/components/draw/DrawCanvas.tsx
  - src/lib/snapping.ts
lastReviewed: '2026-08-25'
reviewedAtCommit: 94e86ac5aba8031aef02dd9eb9422d028184f05e
status: stable
audience: practitioner
---

Field	Required	What it is
title	yes
description	yes	One sentence. Shown in search and in link previews.
sourceRefs	yes	Repo-relative paths this page documents. [] is valid.
lastReviewed	yes	YYYY-MM-DD. When a human last verified this against the source.
reviewedAtCommit	yes	The git SHA it was verified at. Staleness is measured from here.
status	yes	stable, draft, or needs-review.
audience	no	beginner, practitioner, or reference.

These are required, not optional. A page with a missing or malformed field fails the wiki’s own build rather than shipping and quietly falling out of the index.

sourceRefs is the whole mechanism

It is the reverse index from a git diff to the pages that diff affects.

Change src/lib/validation/types.ts and this is what says “these four pages document that file” — rather than someone grepping for a phrase they half remember, and missing two.

Pages that document practice rather than code declare sourceRefs: []. The physics and printing pages are mostly like this. That exempts them from staleness checks. It does not exempt them from being wrong, and it is not a way to silence a warning on a page that really does describe app behaviour.

If a changed file appears in no page’s sourceRefs, that is a signal. Either a page is missing a ref, or the feature is undocumented. Both are worth fixing; neither is worth shrugging at.

The audit

npm run wiki:audit              # staleness warns
npm run wiki:audit -- --strict  # staleness fails

Run from the repo root, where it can see both src/ and wiki/. Vercel builds the wiki in isolation with Root Directory set and cannot see src/ at all, so this is a local and CI gate — the wiki’s own build command stays a plain astro build.

The non-strict version is wired into npm test at the root.

What it checks

#	Check
1	Every internal link and anchor resolves.
2	Every page’s frontmatter validates.
3	Every path in every sourceRefs exists in the repo.
4	Warning coverage — every WarningKind has an anchored section in the design-check catalogue, and no orphan sections document a check that no longer exists.
5	Schema coverage — every field in src/types/project.ts appears in the file-format reference.
6	Shortcut coverage — every key bound in the Draw view appears in the shortcuts reference.
7	Deep-link coverage — every anchor src/lib/wikiLinks.ts points at exists.
8	Staleness — pages whose sourceRefs have commits after reviewedAtCommit.
9	Index resolution — every slug and source path in the update-wiki skill’s references/MAPPING.md points at something that exists.

Checks 4 to 7 and 9 are the ones that earn their keep. They run from the source to the docs, so adding a WarningKind or a schema field fails the audit until someone writes the section for it.

Check 9 exists because the supplied MAPPING.md arrived with six entries that pointed at nothing — a file that had been renamed, and five slugs that were never this wiki’s. A source→page index that misses is worse than no index, because a sweep that follows it finds nothing and reads that as “no page needed updating”.

Caution

wiki:audit failing is not a formality to work around. It is usually telling you that a check or a schema field went undocumented. Fix the docs, not the audit.

Anchors are an API

src/lib/wikiLinks.ts maps in-app context to wiki anchors. Every warning row in the Design checks panel has a Learn more link that lands on a specific section of the catalogue.

Renaming a heading breaks that link. Do it deliberately, and update wikiLinks.ts in the same commit. The audit will tell you if you forget.

Why the catalogue’s headings look the way they do

Every section in the design-check catalogue is headed by the warning’s literal kind, as a code span, with the human title on the line below:

### `channels-too-close`

**Channels are closer than the wall between them can print.**

That looks like a stylistic choice. It is a workaround, and it is worth knowing before you “tidy” it.

The obvious way to pin an anchor is an explicit id — ### Something {#stable-id} — which is standard in most Markdown toolchains. It does not work here. In MDX, {…} opens a JavaScript expression, so the build fails rather than producing the id. Astro’s plain Markdown does not support the syntax either, and a raw HTML heading keeps its id but drops out of Starlight’s table of contents.

So the anchor is the heading text: channels-too-close slugifies to #channels-too-close, which is exactly what src/lib/wikiLinks.ts points at.

The consequence is the thing to hold on to — the heading text is now load-bearing. Rewording one silently breaks a Learn more link in the app. Check 7 catches it, which is why that check exists.

When you change the code

1. Find what changed. git log and git diff --stat since the last sync point in wiki/.wiki-sync.json.
2. Map it to pages. grep -rl "src/lib/validation" wiki/src/content/docs/ finds every page that declares that path.
3. Read the source. Not the diff — the current state of the file. The diff tells you where to look; it does not tell you what is true now.
4. Fix exactly those pages. Surgical edits. Change the sentences that are wrong; do not rewrite a paragraph because you would have phrased it differently.
5. Update lastReviewed and reviewedAtCommit on every page you touched or verified. A verified-unchanged page is a real result, and stamping it stops it being re-flagged forever.
6. Run the audit, then build the wiki.
7. Update wiki/.wiki-sync.json and add a Changelog entry for anything a reader would notice.

Defaults are the sneaky class

A number like 0.4 mm gets quoted in a guide page, a reference table, a tutorial, and a printing tip. sourceRefs will not find all four, because only one of them documents the file the constant lives in.

Grep the whole wiki for the old value. Every time.

House rules

• Never invent a number. Every figure traces to source, to a cited paper, or it does not appear.
• Physics claims carry their assumptions. Hagen–Poiseuille assumes fully developed laminar flow, a constant cross-section, and a Newtonian fluid. Say so where you use it.
• Cite, do not reproduce. Reference papers by author, year, and title or DOI. Paraphrase; never paste passages.
• Advisory, never blocking. OpenChip’s validation philosophy is absolute and this wiki must reflect it. Never write “you must fix this before exporting”. Write what the risk is and let the reader decide.
• Removals get removed. If a feature is gone, delete its page and its sidebar entry. A stub saying “this was removed” is only worth it when the feature was prominent.
• State limits in the same breath as capabilities. Every estimate on this site says what it does not cover, on the same page, not in a footnote.

The update-wiki skill

There is a Claude Code skill at .agents/skills/update-wiki/ that automates the workflow above — establishing scope from the sync file, mapping a diff to pages through sourceRefs, reading the source rather than the diff, and running the audit.

It exists so the convention survives contact with a busy week. The conventions on this page are the thing that matters; the skill is one way of following them.

Next

• Contributing
• Changelog