Documentation as Data

# labs/user_manual.py
from dataclasses import dataclass


@dataclass
class Command:
    action: str
    trigger: str
    source: str
    category: str
    example: str
    enabled: bool = True
    requires: str = ""


if __name__ == "__main__":
    cmd = Command("turn_off_lights", "lights off", "rules", "home",
                  "GLaDOS, lights off please.")
    print(f'{cmd.action:<16} matched on "{cmd.trigger}" by the {cmd.source} engine')
    print(f'{"":<16} category={cmd.category} enabled={cmd.enabled}')

$ uv run python -m labs.user_manual
turn_off_lights  matched on "lights off" by the rules engine
                 category=home enabled=True

Seven fields, and the split between them is the design. action, trigger, source and enabled are facts the running system owns; nobody types those into a manual. category and example are editorial, invented by a person who knows what a household would actually say. requires is the odd one: a person decides that halting everything is meaningless without a servo, and the wiring manifest decides whether that servo exists. Command is not a record you write, it is the record the generator produces after joining those sources.

from labs.automation import ACTION_REGISTRY, RULES
from labs.behavior_engine import BEHAVIORS


def discover() -> list[tuple[str, str, str, bool]]:
    found = []
    for rule in RULES:
        if rule["action"] in ACTION_REGISTRY:
            found.append((rule["action"], rule["trigger"], "rules", True))
    for b in BEHAVIORS:
        found.append((b.action, b.trigger, "behaviors", b.enabled))
    return found


if __name__ == "__main__":
    for action, trigger, source, enabled in discover():
        flag = " " if enabled else "-"
        print(f"{flag} {action:<16} {trigger:<12} {source}")

$ uv run python -m labs.user_manual
  turn_off_lights  lights off   rules
  set_timer        set timer    rules
  play_music       play music   rules
  halt.all         emergency    behaviors
  warn.power       battery_low  behaviors
  greet.user       wake_word    behaviors
  status.report    status       behaviors
- snark.reply      wake_word    behaviors

Eight lines, produced by importing two modules and reading their data. The membership test on the rules side matters: a rule whose action names a handler nobody registered is a row that warns at dispatch time and does nothing, so it is not a command and does not belong in a manual. On the behavior side there is no such test, because a behavior carries its own enabled flag, and the single dash on the last line is that flag surviving the trip into documentation. Night snark is off today. Any manual that quietly promised it would be lying, and this one cannot, because the flag came from the table the engine consults.

@dataclass
class Doc:
    category: str
    example: str
    requires: str = ""


DOCS: dict[str, Doc] = {
    "turn_off_lights": Doc("home", "GLaDOS, lights off please."),
    "set_timer": Doc("home", "GLaDOS, set a timer for five minutes."),
    "play_music": Doc("home", "GLaDOS, play music."),
    "greet.user": Doc("social", "GLaDOS, wake up."),
    "snark.reply": Doc("social", "GLaDOS, wake up."),
    "status.report": Doc("system", "Give me a status report."),
    "halt.all": Doc("system", "GLaDOS, emergency stop.", requires="servo_sg90"),
    "warn.power": Doc("system", ""),
}


def build_commands() -> list[Command]:
    found: list[Command] = []
    for rule in RULES:
        doc = DOCS.get(rule["action"])
        if doc is None or rule["action"] not in ACTION_REGISTRY:
            continue
        found.append(Command(rule["action"], rule["trigger"], "rules",
                             doc.category, doc.example, requires=doc.requires))
    for b in BEHAVIORS:
        doc = DOCS.get(b.action)
        if doc is None:
            continue
        found.append(Command(b.action, b.trigger, "behaviors", doc.category,
                             doc.example, enabled=b.enabled, requires=doc.requires))
    return found


def print_manual(commands: list[Command], wired: set[str]) -> None:
    by_category: dict[str, list[Command]] = {}
    for cmd in commands:
        by_category.setdefault(cmd.category, []).append(cmd)
    print(f"=== GLaDOS voice commands ({len(commands)} known) ===\n")
    for category, cmds in sorted(by_category.items()):
        print(f"[{category.upper()}]")
        for cmd in cmds:
            say = f'"{cmd.example}"' if cmd.example else "(nothing: she starts this one)"
            print(f"  Say:      {say}")
            print(f"  Matches:  {cmd.trigger} -> {cmd.action} ({cmd.source})")
            if cmd.requires:
                state = "wired" if cmd.requires in wired else "NOT WIRED"
                print(f"  Hardware: {cmd.requires} ({state})")
            if not cmd.enabled:
                print("  Status:   switched off in the behavior table")
            print()

$ uv run python -m labs.user_manual
=== GLaDOS voice commands (8 known) ===

[HOME]
  Say:      "GLaDOS, lights off please."
  Matches:  lights off -> turn_off_lights (rules)

  Say:      "GLaDOS, set a timer for five minutes."
  Matches:  set timer -> set_timer (rules)

  Say:      "GLaDOS, play music."
  Matches:  play music -> play_music (rules)

[SOCIAL]
  Say:      "GLaDOS, wake up."
  Matches:  wake_word -> greet.user (behaviors)

  Say:      "GLaDOS, wake up."
  Matches:  wake_word -> snark.reply (behaviors)
  Status:   switched off in the behavior table

[SYSTEM]
  Say:      "GLaDOS, emergency stop."
  Matches:  emergency -> halt.all (behaviors)
  Hardware: servo_sg90 (wired)

  Say:      (nothing: she starts this one)
  Matches:  battery_low -> warn.power (behaviors)

  Say:      "Give me a status report."
  Matches:  status -> status.report (behaviors)

DOCS is keyed by action name because the action name is the one string both dispatchers agree on. Everything else about a command is reachable from it. setdefault builds each category bucket the first time that category is seen, and sorted on the buckets fixes the printing order at HOME, SOCIAL, SYSTEM, so two runs a month apart differ only where the system differs. Two entries are doing quiet work. The empty example on warn.power renders as "she starts this one", which is the truth: a battery warning is not something you can ask for. And the hardware line reads servo_sg90 (wired) only because the manifest's parts list declares a component under exactly that name. Pull the servo off the board, take it out of the rig, and the manual stops claiming she can halt a limb she no longer has.

# labs/user_manual.py — the parts that turn the list into artifacts
import json
import sys
from dataclasses import asdict
from pathlib import Path

from labs.wiring_manifest import bench_manifest

MANUAL_PATH = Path("docs/voice_commands.json")


def wired_components() -> set[str]:
    return {c.name for c in bench_manifest().components}


def to_help_text(commands: list[Command]) -> str:
    usable = [c for c in commands if c.enabled and c.example]
    names = ", ".join(f'"{c.trigger}"' for c in usable[:3])
    return f"I answer to {len(usable)} phrases, including {names}. The rest are in the manual."


def save_manual(commands: list[Command], path: Path) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    payload = {"count": len(commands), "commands": [asdict(c) for c in commands]}
    path.write_text(json.dumps(payload, indent=2))


def audit() -> list[str]:
    system = set(ACTION_REGISTRY) | {b.action for b in BEHAVIORS}
    problems = []
    for action in sorted(system - set(DOCS)):
        problems.append(f"UNDOCUMENTED  {action}: she can run it, the manual never mentions it")
    for action in sorted(set(DOCS) - system):
        problems.append(f"UNKNOWN       {action}: documented, but nothing registers that name")
    return problems


def main() -> None:
    commands = build_commands()
    print_manual(commands, wired_components())
    save_manual(commands, MANUAL_PATH)
    print(f"Wrote {MANUAL_PATH} ({len(commands)} commands)")
    print(to_help_text(commands))
    problems = audit()
    for line in problems:
        print(line)
    print(f"audit: {len(problems)} problem(s)")
    sys.exit(1 if problems else 0)


if __name__ == "__main__":
    main()

$ uv run python -m labs.user_manual   # last lines only
Wrote docs/voice_commands.json (8 commands)
I answer to 6 phrases, including "lights off", "set timer", "play music". The rest are in the manual.
audit: 0 problem(s)

$ head -12 docs/voice_commands.json
{
  "count": 8,
  "commands": [
    {
      "action": "turn_off_lights",
      "trigger": "lights off",
      "source": "rules",
      "category": "home",
      "example": "GLaDOS, lights off please.",
      "enabled": true,
      "requires": ""
    },

Three consumers, one list. The printed reference is for a person at a terminal, the JSON is for anything that is not a person, and to_help_text is the sentence she speaks when someone asks what she can do: six phrases, not eight, because the disabled behavior and the automatic one are filtered by fields rather than by memory. asdict converts each Command into a plain dict, since json.dumps handles built-in types only and raises TypeError: Object of type Command is not JSON serializable otherwise. The last line is the one that changes how the project behaves: sys.exit(1) on any problem makes stale documentation a failing command instead of an observation. Run it from the systemd pre-start check you generated in chapter 54, or from CI, and a command that nobody documented stops the build.