oikos/.agents/domains/operations/schema.md

Operations domain — schema

The operations domain holds the procedural and time-stamped documentation: runbooks (repeatable procedures), investigations (incident evidence), and plans (design docs for non-trivial work). It follows writing-style; runbooks and plans use the imperative voice exception.

Where each kind lives: runbooks are skills under .agents/skills/; operator reference (command cheatsheet, enrollment, Nomos agent) lives in .agents/operations/; investigations are investigation entities in the DB (historically investigation entities in the DB); plans stay in the repo-root plans/ folder (below).

Plans always live in plans/

Any plan or design doc for the Homelab is written into the repo plans/ folder as plans/YYYY-MM-DD-slug.md — never a scratch path, an agent-private plan location, or a chat message. An agent drafting a plan:

1. Writes the file under plans/ using the plan template in page-templates.md.
2. Lists it in plans/index.md.
3. On completion, moves it to plans/done/ and updates the index status.

This is the single source for homelab design intent; keeping it in-repo means the plan is versioned, reviewable, and reachable by MCP search_knowledge like any other doc.

Runbooks

Repeatable procedures are skills — one folder per skill at .agents/skills/<name>/SKILL.md, with YAML front-matter that the Oikos policy and lifecycle machinery reads:

---
name: <name>
risk_class: read_only | reversible_low | config_mutation | destructive
inputs: [<param>, ...]
verification: "<shell expression that proves success>"
docs_update_checklist: [<doc artifacts to update>]
transition: "<from> -> <to>"   # only for lifecycle runbooks
---

risk_class values and the lifecycle transition states must match seeds/policy.yaml and seeds/ontology.yaml.

Investigations

Incident records are investigation entities in the DB, linked to the entities they implicate via about edges. They are evidence sources — written once at incident time, then back-linked from the changelogs of the nodes they implicate. Sections: ## Summary, ## Timeline, ## Root cause, ## Mitigations applied, ## Open questions. The legacy file-based investigations live at investigation entities in the DB.

The operations log

plans/log.md is the append-only record of documentation operations on plans (## [YYYY-MM-DD] <op> | <summary>), distinct from the DB audit trail. The legacy archive/knowledge/log.md is frozen with the rest of the archived wiki.