Skip to content

ADR 0003: Docs-as-code, Diataxis-structured, strict-CI-checked

Status

Accepted

Context

Argus had accumulated documentation organically -- docs/specs/, docs/plans/, docs/research/, docs/design/, plus loose top-level files like REQUIREMENTS.md, ROADMAP.md, and api-conventions.md -- with no consistent home for "how do I operate this" versus "why does this exist" versus "what does this endpoint guarantee." Agents (the overnight build runner, the hub's context assembler, audit harnesses) and Aaron both read these files raw, so any restructure has to keep every currently-read path resolvable, not just look better in a rendered site.

Decision

Aaron's ruling (2026-07-14): documentation starts now, built for frequent change.

  • Plain Markdown in docs/ stays the single source of truth. Agents and the context assembler read it raw; Forgejo renders it inline. No doc lives only as HTML or only in a database.
  • The directory layout follows Diataxis: docs/runbook/ (how-to, operational), docs/reference/ (contracts -- dry, factual, e.g. API/SSE conventions and the hook-event surface), docs/explanation/ (understanding -- specs, plans, research, design history, the PRD, the roadmap), plus docs/adr/ for numbered decision records with a fixed template (this directory).
  • Material for MkDocs renders the human-facing site on top of the same Markdown, dark theme, Mermaid enabled, so every code scenario can ship as an annotated flowchart page (diagrams as diffable text agents can maintain, not binary exports).
  • CI is strict: a broken internal link or an invalid Mermaid block fails the build. Docs are treated as code with the same "drift is silent failure" standard the rest of the project holds itself to (ARGUS-630 wires the strict checks; this ADR only commits to the standard).
  • The whole skeleton (Diataxis layout, ADR convention, MkDocs config, strict CI) becomes part of runonyourown/project-template so every future project inherits it instead of re-deriving it.

Consequences

  • Every existing doc needed a new home in this same change, with the old path still resolving (a stub redirect or, for docs/specs/, a per-file stub) so nothing a human or the context assembler currently reads breaks mid-migration.
  • Future docs work is now scoped along the epic this ADR belongs to (ARGUS-628): strict CI (ARGUS-630), the rendered site + Komodo stack (ARGUS-631), the scenario atlas of annotated Mermaid pages (ARGUS-632), and a freshness lint that flags contract-touching PRs which skip docs (ARGUS-634) -- each is a separate task building on this layout, not bundled into it.
  • Documentation now carries a build step (mkdocs build --strict) that can fail a PR on its own, which is the point: a stale or broken doc is now a visible CI failure instead of a page nobody notices went wrong.
  • Deploy trigger (ARGUS-631): the rendered site redeploys via Komodo's stack polling/auto-update on the :latest image, not a push webhook. A repo-push webhook fires before the image exists (the docs workflow still has to build and push it), so a webhook-triggered redeploy would race its own artifact; polling only ever observes an image that is already in the registry, needs no cross-system secret, and minutes of latency is an acceptable cost for documentation.