dtoro
986937799a
archive/ contained the old narrative wiki (superseded by DB as source of truth), hermes-plans, oikos-cards, ledger, secrets-issuance, and SOPS backups — all Python-era artifacts with no ongoing value. Updated all cross-references in: - AGENTS.md, README.md - .agents/operations/commands.md (point to docs/infrastructure/) - .agents/shared/llm-wiki.md, page-templates.md - .agents/domains/knowledge/schema.md, operations/schema.md - .agents/skills/*/SKILL.md - docs/infrastructure/*.md (removed archive link targets) - docs-lint/SKILL.md known-baseline note
51 lines
3.2 KiB
Markdown
51 lines
3.2 KiB
Markdown
# 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](../domains/knowledge/schema.md) 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 investigation entities in the DB), 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
|
|
(deleted — DB is sole source of truth).
|
|
- **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; frozen legacy log was deleted with the archive.
|
|
|
|
## 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](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](../domains/operations/schema.md).
|