dtoro
b5c1247093
Problem: after the wiki-hq reorg, agent-instruction and human-doc domains were still scattered across the repo root, with three now-redundant stub files cluttering it. The organizing principle wasn't visible in the layout. Change — enforce three clear buckets: - .agents/ = how agents operate: OIKOS.md, HERMES.md (moved from root), shared/ conventions, domains/ schemas, skills/, and operations/ (operator cheatsheet + enrollment + hermes-agent, moved from root). - knowledge/ = what exists + evidence: wiki/, GLOSSARY.md, and sources/ now including investigations/ (incident records are evidence/sources). - root = substrate + two entry points (AGENTS.md, README.md), plus plans/ as its own design-intent domain. Moves: - investigations/ -> knowledge/sources/investigations/ (incl. archive/, index). - operations/ -> .agents/operations/. - HERMES.md -> .agents/HERMES.md. - Deleted unreferenced root stubs CAVEMAN.md, CONTRIBUTING.md, and OIKOS.md (its 7 remaining linkers repointed to .agents/OIKOS.md). Consumers updated: - inventory.yaml doc_page (agent-enrollment) + regenerated hosts/*.yaml + cards. - tools/setup-hermes-soul.sh and bootstrap.sh (x2) -> .agents/HERMES.md. - bin/homelab help string -> .agents/operations/hermes-agent.md. - knowledge/operations schemas, llm-wiki, page-templates, incident-investigation skill, AGENTS.md/README nav -> new investigations/operations paths. - All markdown links rewritten via the path-resolving mapper. Left in place (substrate/executable/separate-domain): hosts/, ledger/, tools/, plans/, oikos/, mcp/, secrets/, bin/, inventory.yaml. Verification: docs-lint at baseline (2 intentional cross-repo refs, no new breakage); gen-topology.py --check exit 0; build_host_files.py idempotent; all doc_page targets resolve; Hermes provisioning scripts point at the new path. 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/, 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,
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 (
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 (
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.