dtoro
bb5c0717a1
Problem: the narrative docs lacked an enforceable style standard, and
agent-facing instruction (OIKOS/CAVEMAN/CONTRIBUTING) was interleaved with
human content at the repo root.
Change:
- Add .agents/shared/{writing-style,llm-wiki}.md — a lint-checkable prose
standard (with an imperative-voice exception for runbooks/recipes) and the
sources/wiki/index/log layer model.
- Move CAVEMAN.md -> .agents/shared/caveman.md,
CONTRIBUTING.md -> .agents/shared/page-templates.md,
OIKOS.md -> .agents/OIKOS.md; leave thin root stubs so old links resolve.
- Add .agents/domains/{knowledge,operations}/schema.md; operations schema
codifies "plans always live in plans/".
- Repoint live references (AGENTS, README, GLOSSARY, OIKOS) and fix OIKOS.md's
internal relative links for its new depth.
Risk: none to the operational substrate — inventory.yaml, hosts/*.yaml,
oikos/, mcp/, secrets/, bin/ untouched (verified via git status).
Verification: relative-link check across .agents/ clean; substrate churn empty.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2.5 KiB
2.5 KiB
LLM Wiki — the documentation contract
How the narrative documentation in this repo is organized. The pattern is borrowed from the
sources / wiki / index / log model: a durable synthesized layer (knowledge/wiki/) built on top
of immutable evidence (knowledge/sources/, investigations/), with pure-listing indexes and an
append-only operations log.
This contract governs the narrative layer only. The machine-readable substrate — inventory.yaml,
generated hosts/*.yaml, oikos/, mcp/, secrets/, bin/ — is not part of the wiki and never
moves under it. See the knowledge schema for the split.
Layers
- Sources are immutable raw material: incident records (
investigations/), external reference docs (knowledge/sources/references/), and the live system itself (pct config,docker inspect). Read them; do not rewrite them into other sources. - Wiki (
knowledge/wiki/) is the synthesized, authoritative current-state layer: one page per node (containers/,vms/, host narratives) and per cross-cutting system (infrastructure/). A reader understands the topic from the wiki page without reading the sources. - Index (
index.md/ folderREADME.md) is a pure listing — every page in scope with a one-line summary, and nothing else. Anything the section wants to say up front goes into a page the index lists, not into the index. - Log (
log.md) is append-only, recording doc-maintenance operations (restructures, source ingests, lint sweeps) in single-line format:## [YYYY-MM-DD] <op> | <summary>.
Two logs, kept distinct
## Changelogon each node/topic page records infrastructure changes to that node. It is machine-parsed (get_changelog, the Oikos ledger) — keep the### YYYY-MM-DD — titleshape.log.mdper area records documentation operations only. It never duplicates the Oikos change ledger (oikos/ledger.py), which stays authoritative for infra changes with who/what/risk/approval/verification.
Rules
- Wiki pages stay short and focused. A page past ~300 lines splits.
- Pages stay flat under
wiki/<section>/until there are enough to warrant a sub-group. - Every page follows writing-style.md.
- Plans and design docs always live in the repo
plans/folder (plans/YYYY-MM-DD-slug.md), listed inplans/index.md, moved toplans/done/on completion — never a scratch path or a chat message. See the operations schema.