Documentation system decisions

Context

A personal development environment spans machines, applications, shared browser state, isolated worktrees and external identities. Future agents need operational context without this conversation. Humans need searchable HTML and several levels of visual explanation. Changes must remain reviewable in Git.

Decisions

Use Markdown-first Starlight pages, organized into workflows, recovery recipes, reference and explanation (following Diataxis). Reuse C4-inspired context/deployment/runtime views and selected arc42 concerns. Use LikeC4 for architectural relationships and multiple views; the representative build and relationship-change test passed. Use ordinary HTML lists for task sequences so the diagram remains readable text.

Inventory holds operational facts and links to model identifiers. The model holds architecture relationships; we do not maintain a second relationship graph in JSON. A build validates cross-references. Diagrams describe dated architecture, not live telemetry.

Use an isolated, pinned documentation Node runtime. Do not change application toolchains for a docs dependency. Build output stays ignored; the source is readable without JavaScript. Local preview stays on loopback. On 6 October the owner approved public Cloudflare Pages hosting of the generated site, while keeping the source repository private. The publishing workflow records deployment status.

The initial import preserved curated working scripts byte-for-byte. Review and test runtime changes separately from documentation edits. Keep live ~/dev-environment separate from the personal repository checkout. Installation is explicit and refuses unexplained drift. Leave application PRs unchanged until compatibility decisions are resolved.

Public hosting

Use a Cloudflare Pages direct-upload project and the existing GitHub Actions validation workflow. Publish only dist/ after successful checks on main; PR builds do not publish. This gives the site an address independent of the development machines and keeps build and validation steps in one place. No Access login is configured because the owner explicitly chose public pages. Wrangler is pinned as the deployment CLI; it does not change application toolchains.

Consequences and reconsideration

LikeC4 adds a DSL and build dependency, justified only if a shared model makes multi-level views easier to maintain. The diagram explorer is a separate generated static application linked from the docs. Text equivalents remain available. Reconsider if contributors struggle with it or its dependencies outweigh its value.

No new slide framework yet; a browser walkthrough serves initial presentations. Add slides only when a real presentation requires them. No centralized infrastructure inventory server or auto-repair daemon is needed.

Sources

Starlight, LikeC4, Diataxis, C4, arc42. The scope/ownership rules here are local choices, not claims that those frameworks enforce safe operations.