Skip to content
Gopher

ADR-019: A public documentation site

Status: Accepted (2026-09-02)

Decision: Gopher’s documentation is a public site (site/, published at gopher.michi.onl), built from Markdown that lives in this repository. Beside it sits memory.md, at the repository root, which carries only the state of in-progress work. A single rule decides which of the two a sentence belongs to: would it still be correct in six months if nobody touched the code? A page under site/src/content/docs/ if yes; memory.md if no. When work closes, its fact moves out of memory.md into a page, and the memory entry is deleted.

Why a monorepo, not a separate site repository:

  1. tests/docs.test.ts validates backticked paths against files on disk. That check is the strongest correctness guarantee the documentation had, and it is only possible when the prose and the code share a tree. A separate repository would destroy it.
  2. AGENTS.md says “Correct the document in the same change that makes it wrong.” That rule is enforceable inside one commit. Across two repositories it becomes two pull requests, and the second one gets forgotten.
  3. The content must live in this repository regardless. A separate site repository would need a submodule, a subtree, or a sync job — a step that can silently not run.
  4. There is no independent cadence to protect. One author, no separate deploy risk, no release train of its own.

A monorepo costs a documentation framework landing in the repository. A package boundary instead of a repository boundary pays that cost off. site/ carries its own package.json and package-lock.json and is not an npm workspace. The root npm install stays exactly what it was, and only the documentation CI job installs Astro and Starlight.

Why this site replaces the project’s old single document: that file mixed reference (architecture, the manifest, the decisions) with working memory. The working memory was what is verified today, what is not complete, and what must happen before the store release. An agent reading it could not tell a durable fact from a snapshot. The file could not be published as-is, because it also carried harness procedure and account-data rules. It had no mechanism that made it shrink — a closed item stayed in its own section forever. Splitting reference from memory, and giving memory.md a 200-line ceiling enforced by tests/docs.test.ts, fixes all three.

The condition to open this decision again: the site stops being “the docs” and becomes “the website.” A website here means a marketing home page, a blog, screenshots, its own design system. And a different person comes to own it. Until then, growth here still means a second package in this repository, not a new one.

Read the documentation system and the .agents/skills/gopher-docs/ skill for the workflow this decision produces.