DocSite/CLAUDE.md

DocSite — project rules

DocSite is a single-source-of-truth LAN documentation server: it renders each project's docs live from that project's canonical Gitea repository (the pushed main revision), with one consistent theme across all projects, holding no second copy of the content and never writing to a source repo. The maintainer is an AI (the skills pipeline); recurring content types map to a fixed, documented directive vocabulary rather than ad-hoc markup, so the same formats are reused instead of reinvented per page.

This file is the project sittenkodex. It imports the universal discipline from ~/dev/skills/templates/CLAUDE.md.fragment and adds DocSite's domain invariants. Per-cycle specs (docs/specs/) and plans (docs/plans/) are ephemeral working artifacts, git-tracked while their cycle is live and removed (git rm) at cycle close.

Roles

I am the orchestrator, not the implementer. The skills-plugin agents are my workers: I plan, design, decide, and integrate; they implement, refactor, test, and diagnose. Trivial mechanical edits I may do directly; anything needing broad reading or judgement goes to an agent. Agent reports describe intent, not outcome — I verify the diff and the test output myself before committing.

Commit discipline and main-branch sanctity

• Only the orchestrator commits. No skill agent runs git commit; agents leave their output as unstaged working-tree changes for me to inspect and shape into commits.
• main HEAD is sacrosanct below the session anchor. No git reset / git revert on user-ratified main history; main moves forward only via my commits. Wrong agent output is discarded with git checkout -- <paths> / git stash. The one narrow /boss exception is the rollback sandbox: my own unpushed autonomous commits above the session anchor may be wound back toward (never below) it.
• When a commit closes a Gitea issue, reference it in the body: closes #N (or refs #N for non-final work). No Co-Authored-By trailer.

Design rationale ≠ implementation effort

Design choices are justified by substance — semantics, structural fit, what the design permits vs forbids, compositional clarity, future-proofing. Implementation effort ("approach A touches 250 sites, B touches 1") is an observation about the current code, not a rationale. Effort is at most a named tiebreaker after substantive reasons tie.

Bug fixes — TDD, always

Bug fixes are RED-first and autonomous: the failing test exists in the working tree before any fix. The debug skill is mandatory for any observable misbehaviour (failing test, panic, wrong output, wrong HTTP status).

Domain invariants (load-bearing — never silently violate)

These are the contracts the whole design rests on. A change that breaks one is a design decision, not a refactor, and belongs in the design record.

1. Read-only on source repos. DocSite never writes to any repo it publishes from — no commits, no file edits, no marker comments. Source docs are fetched at request time from Gitea's read-only raw/API endpoints (the pushed main revision), never through a writable path. The publish whitelist and the navigation live in DocSite's own registry.toml, never in the source repos. (A project-owned publish.toml is a possible later migration, but it never grants DocSite write access — the project's own pipeline would author it.)

2. Single source of truth. Content lives exactly once — in the canonical Gitea repository. DocSite keeps no content clone; it holds only a cache, keyed on the source commit SHA (revision-exact), which is a derived artifact, not a source. Rendered HTML is a pure, regenerated function of (source markdown at a revision + config) — never hand-edited, never persisted as a second authority.

3. Reference integrity is detected and reported, never enforced by writing to sources and never silently degraded. Because repair cannot happen in a source repo (invariant 1), DocSite's duty is lossless, precise detection: startup / reload validation of every listed path, a visible error block at render time for an unresolved reference (never silent emptiness), and a docsite check subcommand that validates every reference (nav paths, and later code-includes and intra-doc links) against the current Gitea sources with a report and exit code. Repair happens at the source or in registry.toml, never by a write to a source.

4. Closed directive vocabulary, open at one seam. Authoring uses a documented, closed set of directives; a new content type is added at the handler registry (a deliberate, reviewed act), never as ad-hoc HTML in a doc. The vocabulary is closed to the author, extensible to the maintainer.

5. Whitelist publishing. Only what registry.toml lists is reachable. Unlisted paths — docs/specs, docs/plans, postmortems, anything internal — are structurally unservable, and any path escaping a project's configured docs root is refused.

Skills plugin: project facts

The few facts the skills plugin needs that genuinely vary per project. Everything else is a fixed convention (see ~/dev/skills/docs/conventions.md).

• Code roots — src
• Build — cargo build
• Test — cargo test
• Lint — cargo clippy --all-targets -- -D warnings
• Doc build — cargo doc --no-deps 2>&1
• Issue tracker — Gitea, repo Brummel/DocSite:
  • browsable URL: http://192.168.178.103:3000/Brummel/DocSite/issues
  • list open issues: tea issues ls --repo Brummel/DocSite --state open
  • show one issue with comments: tea issues --comments --repo Brummel/DocSite <idx>