dtoro
5e3b946ded
- Rewrite AGENTS.md: DB as source of truth, MCP knowledge tools, archive refs - Fix OIKOS.md: seeds/ paths, remove Python-era notes, update deployment status - Fix commands.md, agent-enrollment.md: archive/knowledge/ links - Fix all SKILL.md files: remove hosts/*.yaml refs, point to inventory.yaml - Fix HERMES.md, schema.md, page-templates.md, llm-wiki.md: update paths - Fix bootstrap.sh: identity check reads inventory.yaml - Fix README.md, cutover-checklist.md: stale wiki references - Move convert-wiki.py to archive/ (one-shot done)
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 (archive/knowledge/) built on top
of immutable evidence (knowledge/sources/, incident records), with pure-listing indexes and an
append-only operations log.
This contract governs the narrative layer only. The machine-readable substrate — inventory.yaml,
secrets/, scripts/, 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 (
knowledge/sources/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 (
archive/knowledge/) 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.