Editing the corpus

The corpus is flat Markdown in docs/. Two ways to edit.

1. Sveltia CMS (local mode)

Recommended for non-trivial edits — gives you a real editor with field validation, drag-and-drop media, and live preview. Works without a backend.

Browser requirement

Sveltia local mode uses the File System Access API. Chrome, Edge, or any Chromium-based browser. Safari and Firefox are not supported in local mode.

Start it:

pnpm dev
# then open http://localhost:5173/admin/

When the CMS loads, click Work with a local repository and grant access to the 200apps-corpus folder. Sveltia will read collections defined in docs/public/admin/config.yml and let you edit pages with typed fields.

The CMS writes Markdown back to disk in real time. Commit and push as normal:

git add docs/
git commit -m "docs: <area> — <change>"
git push

2. Direct edit

For small text fixes, edit the Markdown file directly in your editor of choice. The repository follows a strict layout — see Information architecture below.

Frontmatter — what each field means

Both Volumes and Master Areas pages use a shared frontmatter schema. Cross-linkage relies on these fields, so keep them current.

Field	Type	Purpose
title	string	Page title — also the H1
volume	I–V	Which volume the page belongs to (volume pages only)
part	number	Part number within the volume (volume parts only)
section	1–13	Master Area section (area pages only)
section_name	string	Master Area section name (area pages only)
owners	list	PO, Designer, Tech Lead, Developer, QA, CS Lead, Leadership, On-call
volumes	list	For area pages — which volumes address this craft
areas	list	For volume pages — which Master Areas this part references (slug form like 10.signal-reading)
related	list	Other pages worth linking from here
maturity	gap / seed / draft / stable / reviewed	How well this page is written
last_reviewed	date	When the content was last sanity-checked

Information architecture

docs/
  index.md                   ← home
  map.md                     ← cross-linkage graph
  glossary.md                ← terms
  volumes/
    index.md                 ← all five covers
    {i,ii,iii,iv,v}-*/
      index.md               ← cover
      intro.md               ← inside cover
      {n}-{slug}.md          ← part
  areas/
    index.md                 ← 13 sections grid
    {01..13}-{slug}/
      index.md               ← section index
      {craft-slug}.md        ← craft page
  contributing/
    editing.md               ← this page
  public/
    admin/                   ← Sveltia CMS
    media/                   ← uploaded assets (gitignored to private if needed)

Voice rules

These are the editing rules that make the corpus the corpus. They are not optional.

• Person-first. Named personas (Dina, Miri, Avi) — never the user.
• Witnessed, not described. Show the moment, not the abstraction.
• Predictions are made before, checked after. A claim without a check date is a guess.
• Chain-aware. Every defect traces to a level. Structural fixes, not patches.
• Terse. Write what carries information forward. Cut what doesn't.

Maturity ladder

Use the maturity frontmatter field honestly. It feeds the map and the gaps view.

Maturity	Meaning
gap	The area exists in the chain but is unaddressed in any volume.
seed	Stub: name, owner, volume reference. No prose.
draft	First-pass prose. May contradict other pages.
stable	Reviewed prose. Voice and facts hold.
reviewed	Recently re-checked against current practice.