Files

dtoro a2410cf9c2 docs(R5): rewrite knowledge schema + llm-wiki for DB-native model; deprecate root inventory.yaml

Rewrote .agents/domains/knowledge/schema.md and .agents/shared/llm-wiki.md
which described the deleted Python substrate (bin/homelab, oikos/cards/,
oikos/ledger.py, root inventory.yaml, knowledge/sources/, get_page/
search_docs MCP tools). Now reflect ADR 0003: Postgres DB is the single
source of truth for structured data and narrative knowledge; seeds/*.yaml
are bootstrap+DR manifests (content-hashed via seed_versions); archive/
knowledge/ is the frozen legacy wiki; MCP search_knowledge/get_entity_
knowledge replace get_page/search_docs.

Swept substrate refs in .agents/shared/{writing-style,page-templates}.md
and .agents/domains/operations/schema.md: bare inventory.yaml ->
seeds/inventory.yaml; knowledge/sources/ -> archive/knowledge/sources/
(historical); get_changelog/oikos/ledger.py -> DB audit trail / structured
document changelog field; HERMES -> Nomos.

Root inventory.yaml (618-line Python-era file superseded 2026-07-07 by
seeds/inventory.yaml) replaced with a deprecation stub pointing to the seed
and DB. Kept as a stub rather than deleted because AGENTS.md §1/§2 still
point clients at /opt/homelab-context/inventory.yaml; full on-client path
reconciliation deferred to R13.

Flagged export gap: oikos export regenerates seeds/{ontology,inventory,
policy}.yaml but NOT seeds/knowledge.yaml — API-added knowledge lives only
in the DB until hand-edited into the seed.

VERSION 0.7.7 -> 0.7.8. Plan R5 marked done.

2026-07-17 22:36:41 +02:00

3.2 KiB

Raw Blame History

LLM Wiki — the documentation contract

How documentation in this repo is organized. The pattern is the sources / wiki / index / log model: a durable synthesized layer built on top of immutable evidence, with pure-listing indexes and an append-only operations log.

This contract governs the narrative layer only. The machine-readable source of truth — the Postgres database, bootstrapped from seeds/ — is not part of the wiki and never moves under it. See the knowledge schema for the split, and ADR 0003 for the DB-native model.

Layers

Source of truth is the Postgres database. Structured data (entities, relationships, status, metrics) and narrative knowledge (documents, investigations, runbooks) both live there, in the entities / relationships / knowledge_entities tables. It is bootstrapped at deploy time from seeds/{ontology,inventory,policy,knowledge}.yaml (idempotent, content-hashed via seed_versions) and mutated at runtime via the API/MCP. oikos export regenerates seeds/{ontology,inventory,policy}.yaml for version control.
Sources are immutable raw material: incident records (now investigation entities in the DB, historically archive/knowledge/sources/investigations/), external reference docs, and the live system itself (pct config, docker inspect). Read them; do not rewrite them into other sources.
Wiki — the synthesized, authoritative current-state layer. Today this is the set of document entities in the DB (one per node and per cross-cutting system), queried via MCP search_knowledge / get_entity_knowledge. The legacy file-based wiki is frozen at archive/knowledge/{hosts,containers,vms,infrastructure}/ for historical reference only.
Index (index.md / folder README.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 is append-only, recording doc-maintenance operations (restructures, source ingests, lint sweeps) in single-line format: ## [YYYY-MM-DD] <op> | <summary>. The active log is the DB audit trail; archive/knowledge/log.md is the frozen legacy equivalent.

Two logs, kept distinct

## Changelog on each node/topic document records infrastructure changes to that node. It is stored as a structured field on the document entity — keep the ### YYYY-MM-DD — title shape so it parses cleanly.
Doc-maintenance logs record documentation operations only. They never duplicate the infrastructure changelog, which stays authoritative for infra changes with who/what/risk/approval/verification (now the DB audit trail, formerly oikos/ledger.py).

Rules

Wiki pages stay short and focused. A page past ~300 lines splits.
Pages stay flat under their 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 in plans/index.md, moved to plans/done/ on completion — never a scratch path or a chat message. See the operations schema.

3.2 KiB Raw Blame History

LLM Wiki — the documentation contract

Layers

Two logs, kept distinct

Rules

3.2 KiB

Raw Blame History