oikos/.agents/domains/knowledge/schema.md

Knowledge domain — schema

The knowledge domain is the durable, authoritative current-state documentation of the homelab: narrative for every node and cross-cutting system, synthesized from live state and evidence. It answers "what exists and how does it work right now."

It follows the LLM Wiki layer model and the writing-style and page-templates rules.

Source of truth — the database

Per ADR 0003, the Postgres database is the single source of truth for all structured data and narrative knowledge. The narrative/substrate split of the Python era is gone: the DB holds both the structured graph (entities, relationships, status, metrics) and the narrative layer (documents, investigations, runbooks) in the knowledge_entities table.

Concern	Where it lives	How it gets there
Knowledge content — documents, investigations, runbooks	knowledge_entities table (rows linked to entities via documents / about edges)	Seeded from seeds/knowledge.yaml at deploy; mutated at runtime via the API
Seed manifest (bootstrap + DR)	seeds/knowledge.yaml	Hand-edited or regenerated; ingested idempotently (content-hashed via seed_versions)
Structured graph — hosts, services, entity types, relationships	entities, relationships, entity_types tables	Seeded from seeds/{ontology,inventory}.yaml; mutated via API/MCP
Archived narrative wiki (read-only history)	archive/knowledge/ (deleted 2026-08-16)	Frozen 2026-07-07 when the DB became source of truth; no longer in repo

Seed ingest

seeds/knowledge.yaml has three top-level lists — documents, investigations, runbooks — each entry carrying slug, title, content (markdown), and tags. internal/knowledge/seed.go ingests each entry by:

1. getOrCreateEntity — ensures the slug exists in entities (type document / investigation / runbook).
2. upsertKnowledgeEntity — writes the markdown body into knowledge_entities, keyed by content_hash so re-ingest is a no-op when nothing changed.
3. createEdge — links the knowledge entity to its subject(s) via documents (for document) or about (for investigation) edges. Runbooks bind to an entity_type via applies_to_type rather than to a single entity.

Runtime mutation

Agents register or update knowledge through the API, not by editing the seed:

• POST /api/v1/knowledge/{entity_slug} — upsert a document/investigation on an entity (upsert_knowledge MCP tool).
• update_entity_attributes — merge a discovered fact (IP, version, port) into an entity.
• create_relationship — record a discovered edge (depends-on, hosts, routes-to).

Export gap. oikos export regenerates seeds/{ontology,inventory,policy}.yaml from the DB for version control, but not seeds/knowledge.yaml. Knowledge added via the API today lives only in the DB until someone hand-edits the seed. Tracked as a follow-up.

Knowledge kinds

• Documents (document entities, linked via documents edges) — node and cross-cutting narrative pages. Carry at_glance (structured attributes) and a parsed changelog. Follow the container / cross-cutting templates in page-templates.md.
• Investigations (investigation entities, linked via about edges) — incident evidence, written once at incident time. Sections: ## Summary, ## Timeline, ## Root cause, ## Mitigations applied, ## Open questions.
• Runbooks (runbook entities, bound by applies_to_type) — repeatable procedures. Carry risk_class and a JSON-schema-validated procedure. Runbooks also live as SKILL.md files under .agents/skills/<name>/ — the DB row is the policy/lifecycle framing, the SKILL.md is the executable procedure the agent loads. See the operations schema.

The two logs

• The per-document ## Changelog records infrastructure changes to that node. Keep the ### YYYY-MM-DD — title shape so the parsed changelog field stays structured.
• archive/knowledge/log.md (deleted) is the append-only record of documentation-maintenance operations on the legacy wiki (restructures, source ingests, lint sweeps): ## [YYYY-MM-DD] <op> | <summary>. It is frozen; new doc-maintenance operations are recorded in the DB audit trail instead.

Querying knowledge

Use MCP, not grep:

• search_knowledge(query) — ILIKE search over documents, investigations, and runbooks in knowledge_entities.
• get_entity_knowledge(entity_slug) — every document, investigation, and runbook linked to one entity, in one call.
• get_entity(slug) / get_relations(entity) — the structured graph around an entity.

Grep the clone only when MCP is unreachable, and prefer the DB for all queries narrative (it is not updated when the DB changes).

Same-session update rule

A change to a node updates the DB in the same session — the entity's attributes, the relationships that reference it, and any document whose at_glance or changelog should reflect the new state. See page-templates.md for the legacy wiki equivalent (deleted).