Keeping the docs current

Keeping the docs current

In this page: the working discipline of this documentation, the ●◐○ status-marker lifecycle, who updates what and when, and the mechanics (sources, conventions, gates) that keep the published site honest. Releases and their tagging live in Documentation releases.

---

1. The status-marker discipline

Every capability statement in this tree carries one of three markers:

• ● exists in the running system, backed by code and data you can run today, behind the command gates of the oimlsmart/smart repository.
• ◐ partial, the concept exists, but thin, declared-only, or living in the wrong home; the gap is named next to the marker.
• ○ planned in the v3 program, a concept of the frame with no realization yet; it carries its driver (an Appendix B gap id, or the phase/task that will land it).

The lifecycle is ○ → ◐ → ●: planned, then partial with a named gap, then running. A marker never moves backwards silently, if running functionality is removed, the marker flips and the prose says why.

Two laws govern the markers:

1. When a marker and the running system disagree, the running system is right, fix the page. (The roadmap states this for itself; it applies to the whole tree.)
2. Every marker has an address. A ● traces to a gate that proves it; a ○ traces to the driver that will land it. Nothing here is aspiration without an address.

2. Who updates what, and when

• Whoever lands the work flips the markers, in the same change. Marker updates are not a separate docs chore; a change that makes a ◐ real, or a ○ partial, is incomplete until the markers in the affected chapters, the roadmap status table, and the volume overview say so.
• Chapter prose is owned by its volume: when behavior changes, the chapter that describes it changes in the same change.
• The roadmap page is the consolidated status map. It is swept at every phase boundary (and whenever a gate goes green on new content) so the markers in the chapters and the roadmap table never drift apart.
• The releases page is updated by the program maintainer when a docs release is tagged, the row flips to ● with the tag date.
• Phase close-out re-verifies, not just sweeps: at a milestone, every ● in the frozen volumes is walked back to its gate.

3. Writing conventions

• Sources. docs/ is the single source of truth; src/content/docs/ is generated by scripts/sync-content.mjs (README.md → index.md, .md links rewritten to routes) and is never edited by hand.
• Links between pages are relative file links , [text](../../primmel/07-expressions/) with the .md suffix and optional #anchor. They work on GitHub as-is; the sync rewrites them for the site. Do not hand-write /…/ route paths.
• Status markers are written as the plain Unicode glyphs ● ◐ ○; the build renders them as badges automatically. To show a glyph as a literal (like this sentence does), wrap it in backticks: ○.
• Fenced code blocks always carry a language, prl, yaml, ocl, or text for plain listings and ASCII diagrams.
• Diagrams are hand-authored SVG in each volume’s diagrams/ directory, referenced relatively. Every diagram starts with a full-bleed background rect (<rect width="100%" height="100%" fill="#ffffff"/>) so it reads as a card in both light and dark themes; the palette is the documented one (slate structure, indigo subjects, green IS, amber HAS, red DOES, violet relations). The build optimizes SVGs with SVGO and CI enforces the background-plus-palette contract (npm run check:svg).

4. The gates

Run these before pushing; CI runs the same set on every pull request and push:

npm run check         # astro check (types for components + scripts)
npm run lint:md       # markdown lint over docs/
npm run check:svg     # diagram background + palette contract
npm run build         # sync + Astro build (Pagefind, sitemap)
npm run check:links   # zero broken internal refs over dist/

The deploy workflow runs the same gates before publishing; a red gate means nothing ships.