Oikos Week 1: kernel policy, ontology, service contract, topology gen

Adds the Oikos agent-OS kernel: oikos/policy.yaml (risk classes +
approval rules for every homelab/MCP command), oikos/ontology.yaml
(8-domain systems model, typed relationships, node lifecycle), and
OIKOS.md (OODA loop operating brief, linked from AGENTS.md).

Extends inventory.yaml with a stable service contract (doc_page,
config_repo, risk_notes) on all 17 services, and a structured
archaeology: section for the 13 destroyed LXCs (was scattered
comments + a narrative table). Fixes stale drift found in the
process: authentik's backend pointed at a retired LXC (124); core
has run on the VPS since 2026-05-31.

Adds oikos/gen-topology.py, generating infrastructure/topology.md
(Mermaid compute/ingress + storage views) from inventory.yaml.
build_host_files.py now carries state/storage/depends_on into
generated hosts/*.yaml.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

oikos/gen-topology.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+"""
+Generate infrastructure/topology.md (Mermaid views) from inventory.yaml.
+
+Views:
+  1. Compute & ingress — hypervisors → guests → services → public URLs
+  2. Storage — mounts and pools per guest
+
+Run from the repo root:
+    python3 oikos/gen-topology.py            # writes infrastructure/topology.md
+    python3 oikos/gen-topology.py --check    # exit 1 if output would change
+
+Wired into the same regeneration path as mcp/build_host_files.py so the
+diagrams never drift from inventory. Edges follow oikos/ontology.yaml
+(hosts, provides, routes-to, mounts, stores-on).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover
+    print("PyYAML is required: pip install pyyaml", file=sys.stderr)
+    sys.exit(2)
+
+REPO = Path(__file__).resolve().parent.parent
+INVENTORY = REPO / "inventory.yaml"
+OUTPUT = REPO / "infrastructure" / "topology.md"
+
+BANNER = (
+    "<!-- Generated by oikos/gen-topology.py from inventory.yaml. -->\n"
+    "<!-- Do NOT edit by hand - your changes will be overwritten. -->\n"
+)
+
+
+def node_id(name: str) -> str:
+    """Mermaid-safe node id."""
+    return name.replace("-", "_").replace(".", "_").replace("/", "_").strip("_")
+
+
+def guest_label(name: str, entry: dict) -> str:
+    pve = entry.get("pve_id")
+    role = entry.get("role", "")
+    tag = f"LXC {pve}" if entry.get("kind") == "lxc" and pve else \
+          f"VM {pve}" if entry.get("kind") == "vm" and pve else entry.get("kind", "")
+    ip = entry.get("lan_ip", "")
+    parts = [name, tag, role, ip]
+    return "<br/>".join(str(p) for p in parts if p)
+
+
+def compute_view(inv: dict) -> list[str]:
+    hosts = inv.get("hosts", {})
+    services = inv.get("services", {})
+    lines = ["```mermaid", "flowchart LR"]
+
+    hypervisors = {n: e for n, e in hosts.items() if e.get("kind") == "proxmox-host"}
+    guests = {n: e for n, e in hosts.items() if e.get("kind") in ("lxc", "vm")}
+    others = {n: e for n, e in hosts.items()
+              if e.get("kind") in ("workstation", "external")}
+
+    for hv in hypervisors:
+        lines.append(f'    subgraph {node_id(hv)}_sub["{hv} (Proxmox)"]')
+        for g, e in guests.items():
+            if e.get("host") == hv:
+                lines.append(f'        {node_id(g)}["{guest_label(g, e)}"]')
+        lines.append("    end")
+
+    # guests without a parent hypervisor recorded (e.g. rclone)
+    for g, e in guests.items():
+        if e.get("host") not in hypervisors:
+            lines.append(f'    {node_id(g)}["{guest_label(g, e)}"]')
+
+    for n, e in others.items():
+        shape = "([{}])" if e.get("kind") == "workstation" else "[[{}]]"
+        lines.append(f'    {node_id(n)}{shape.format(guest_label(n, e))}')
+
+    # ingress: public URL -> backend (routes-to)
+    for svc, e in sorted(services.items()):
+        if not isinstance(e, dict):
+            continue
+        backend = e.get("backend")
+        url = e.get("url") or (
+            f'https://{e["public_host"]}' if e.get("public_host") else None)
+        if backend and url and backend in hosts:
+            host = url.removeprefix("https://").removeprefix("http://")
+            # hypervisors are rendered as subgraphs; point edges at the subgraph id
+            target = node_id(backend) + ("_sub" if backend in hypervisors else "")
+            lines.append(
+                f'    {node_id("url_" + svc)}(["{host}"]) -->|routes-to| {target}')
+
+    lines.append("```")
+    return lines
+
+
+def storage_view(inv: dict) -> list[str]:
+    hosts = inv.get("hosts", {})
+    lines = ["```mermaid", "flowchart LR"]
+    pools: set[str] = set()
+    edges: list[str] = []
+
+    for name, e in hosts.items():
+        for mount in e.get("mounts", []):
+            pools.add(mount)
+            edges.append(f'    {node_id(name)}["{name}"] -->|mounts| {node_id(mount)}')
+
+    for pool in sorted(pools):
+        lines.append(f'    {node_id(pool)}[("{pool}")]')
+    lines.extend(sorted(set(edges)))
+    lines.append("```")
+    return lines
+
+
+def archaeology_table(inv: dict) -> list[str]:
+    arch = inv.get("archaeology", {})
+    if not arch:
+        return []
+    lines = ["| Node | ID | Destroyed | Reason |", "|---|---|---|---|"]
+    entries = sorted(arch.items(), key=lambda kv: str(kv[1].get("destroyed", "")),
+                     reverse=True)
+    for name, e in entries:
+        lines.append(
+            f'| {name} | {e.get("pve_id", "")} | {e.get("destroyed", "")} '
+            f'| {e.get("reason", "")} |')
+    return lines
+
+
+def render(inv: dict) -> str:
+    hosts = inv.get("hosts", {})
+    services = inv.get("services", {})
+    counts = (
+        f"{sum(1 for e in hosts.values() if e.get('kind') == 'proxmox-host')} hypervisors, "
+        f"{sum(1 for e in hosts.values() if e.get('kind') == 'lxc')} LXCs, "
+        f"{sum(1 for e in hosts.values() if e.get('kind') == 'vm')} VMs, "
+        f"{sum(1 for e in hosts.values() if e.get('kind') == 'workstation')} workstations, "
+        f"{len(services)} services"
+    )
+    parts = [
+        BANNER,
+        "# Topology (generated)\n",
+        f"Source: [inventory.yaml](../inventory.yaml) — {counts}.",
+        "Edge semantics: [oikos/ontology.yaml](../oikos/ontology.yaml). "
+        "Operating model: [OIKOS.md](../OIKOS.md).\n",
+        "## Compute & ingress\n",
+        "\n".join(compute_view(inv)) + "\n",
+        "## Storage (mounts)\n",
+        "\n".join(storage_view(inv)) + "\n",
+    ]
+    arch = archaeology_table(inv)
+    if arch:
+        parts += ["## Archaeology (destroyed nodes)\n", "\n".join(arch) + "\n"]
+    return "\n".join(parts)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--check", action="store_true",
+                        help="exit 1 if output would change (don't write)")
+    args = parser.parse_args()
+
+    inv = yaml.safe_load(INVENTORY.read_text())
+    content = render(inv)
+    existing = OUTPUT.read_text() if OUTPUT.exists() else ""
+    if existing == content:
+        return 0
+    if args.check:
+        print(f"{OUTPUT.relative_to(REPO)} would change", file=sys.stderr)
+        return 1
+    OUTPUT.write_text(content)
+    print(f"wrote {OUTPUT.relative_to(REPO)}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())