Golden-path footgun ledger

Every trap in the long cern-team quickstart, and what became of it once archi init / up / doctor existed (PACT r3-golden-path, ADR 0002 §8).

  • absorbed: archi handles it. The Proof column names the test, or the archi doctor check that fails when the trap comes back (each check has a failing fixture in python/tests/cli/test_doctor.py).
  • filed: it needs a change in AKMON (okg). The Proof column names the ask. Each ask is written in golden-path-akmon-asks.md, filed on mitdbg/akmon (2026-10-25) and tracked here by an upstream-ask issue; both links are in the table.

An entry can be both: archi covers the gap today, and the ask would let archi delete that cover (ADR 0002 D7).

Quickstart sections are cited as §1–§8 and by heading.

ID Trap Status How Proof
FG-01 §1: okg had to be pip install -e from a clone, or publish refused with a message about release.pin.code_repository absorbed; filed (ask 1: mitdbg/akmon#3, #798) archi-kb depends on akmon from PyPI (AKMON 0.6.0 renamed its distribution from okg; the import and command are still okg), which meets ask 1; the MCP image installs the release wheel named for the instance's engine version; the published path was run from the wheel okg-version check; golden-path run (PACT evidence)
FG-02 §2: the graph Postgres needs three preloaded libraries, cron.database_name, one server per deployment, and --shm-size 2g absorbed the compose graph-db service carries all of them graph-db-preload, graph-db-shm checks
FG-03 §3: the deployments directory must be a git repository with a baseline commit absorbed archi init makes the instance a git repository and commits a baseline first instance-git check; test_init_writes_a_git_instance_with_secrets_kept_out
FG-04 §3: okg finds a profile only through OKG_PROFILES_DIR or ./profiles/ relative to where it runs absorbed; filed (r3-bundle-format ask 1: mitdbg/akmon#1, #792) archi renders into <instance>/profiles/ and always runs okg from the instance with OKG_PROFILES_DIR removed profiles-env check; test_init_installs_commits_then_publishes
FG-05 §3: a repository connector must be renamed from .yaml.example and given a URL; one without the other blocks the whole publish absorbed packs select sources (archi init --with, archi add --answer); doctor flags a selected source with an empty URL selected-sources-fed check
FG-06 §3: the data root must sit outside deployments/, because okg install --force deletes the deployment absorbed the data root defaults to ~/.local/share/archi/<name>; init refuses one inside the instance data-root check; test_data_root_inside_the_instance_is_refused
FG-07 §3, §8: relative path answers (archi_data_root, twiki_eos_root) resolve against okg's working directory and ignore ARCHI_DATA_ROOT absorbed init passes every path answer absolute; relative defaults are anchored on the data root absolute-paths check; test_relative_path_defaults_are_anchored_on_the_data_root
FG-08 §3: okg install fails at its own publish because the files it just wrote are not committed absorbed; filed (ask 6: mitdbg/akmon#6, #801) init runs okg install --no-publish, commits, then okg provision deployment-committed check; test_init_installs_commits_then_publishes
FG-09 §3, §5: "did it publish?" means reading okg status for a non-null generation absorbed doctor reads it published check
FG-10 §3, "What still needs a person": loopback roles have no password after the migration; catalog load fails on authentication absorbed; filed (ask 4: mitdbg/akmon#4, #799) init runs okg db role-passwords --apply after the first publish role-passwords check; test_init_installs_commits_then_publishes
FG-11 §3: inspect, filter and the MCP server fail with mcp_role_cannot_login until read-role passwords are set absorbed; filed (ask 4: mitdbg/akmon#4, #799) the same step; the okg_mcp password reaches the MCP container through .env role-passwords, mcp-answers checks
FG-12 §4: okg install will not re-run over a deployment; later changes are hand edits, commit, claim, load, ingest absorbed archi add <pack> (r3-bundle-format) does the edit, commit, claim, load, ingest and publish python/tests/bundles/test_lock.py; r3-bundle-format scratch run
FG-13 §4: an edit applied before it is committed fails with repository provenance inputs are not committed absorbed archi add commits before it runs okg; doctor names uncommitted deployment files deployment-committed check
FG-14 §6: the chat database password must be set once, in one shell, and never changed; secrets were typed by hand absorbed init generates every secret once into .env (mode 0600, git-ignored); compose reads it env-secrets, secrets-not-committed checks; test_init_writes_a_git_instance_with_secrets_kept_out
FG-15 §6: the chat app needs its own Postgres, distinct from the graph absorbed the compose chat-db service chat-db-distinct check
FG-16 §6: the graph tools are a separate long-running okg mcp-serve in its own terminal; status reports them dead absorbed; filed (ask 5: mitdbg/akmon#5, #800) the compose mcp service services check
FG-17 §6: publish the chat database and MCP on the container gateway, never on 0.0.0.0 absorbed services reach each other by name on the compose network; every published port is on 127.0.0.1 ports-loopback check
FG-18 §6: Open WebUI's first start overruns chat-instance up's 120 s default; needs --ready-timeout 300 absorbed archi up waits up to 600 s for /health webui-up check
FG-19 §6: the site being up does not mean the assistant reaches the graph absorbed archi up runs okg chat sync, which registers the MCP connection and proves initialize + tools/list; doctor reads the graph through MCP mcp-answers check
FG-20 §6: MCP must be served on chat.mcp.port (8765), where chat sync dials and nowhere else absorbed the mcp service is rendered from chat.mcp.port mcp-port check
FG-21 §6: --container-runtime podman is needed on up and refused by status absorbed archi detects docker or podman once and records it in archi.yaml test_detect_runtime_* (test_stack.py)
FG-22 §6: a retry must remove both containers, because the chat container bakes in its connection string absorbed compose recreates a container whose settings changed; archi never rewrites .env after init (you may add source credentials to it) test_compose_holds_no_secret_value (test_stack.py)
FG-23 §6: the DSN says 127.0.0.1 and okg rewrites it for the container through the gateway absorbed containers use service names; the host uses 127.0.0.1 and the published port test_compose_services_reach_each_other_by_name (test_stack.py)
FG-24 §6: the admin token for chat sync comes from a hand-run signup curl absorbed; filed (ask A: mitdbg/akmon#7, #802) archi up signs in, or signs up on a fresh site, with the generated admin password test_admin_token_* (test_stack.py)
FG-25 §6: chat sync refuses a deployment without a system prompt absorbed the bundle ships skills/chat-system-prompt.md; nothing for the operator to do python/tests/test_bundle_cern_team.py
FG-26 §6: a remote host needs an SSH tunnel to reach the loopback-bound site absorbed archi up prints the tunnel command when it runs over SSH test_up_prints_the_tunnel_over_ssh (test_stack.py)
FG-27 §6: the model provider is set by hand, at host.docker.internal:<the right port> absorbed archi up points the site at a local ollama when one answers (--ollama-url otherwise); the webui service maps host.docker.internal test_configure_ollama_* (test_stack.py)
FG-28 §6: the site opens on the raw model, not the preset with the graph tools filed (ask B: mitdbg/akmon#8, #803) okg chat sync sets the site default to chat.models.default; archi cannot change it without breaking sync's readback. archi up says to pick the preset mitdbg/akmon#8, #803
FG-29 §6: Open WebUI attaches a preset's tools only for browser sessions, not API callers absorbed the supported surface is the MCP endpoint (ADR 0002 D5); the nightly asks over MCP nightly workflow
FG-30 §7: every selected source must finish, or nothing publishes filed (r3-bundle-format ask 2: mitdbg/akmon#2, #793) optional sources in okg would remove it; until then packs keep unfed sources out of the selection mitdbg/akmon#2, #793
FG-31 §4: with code symbols the first okg ingest fails, because it runs before the repository is cloned; run it twice filed (ask C: mitdbg/akmon#9, #804) an ordering bug between a source and its predecessor's checkout mitdbg/akmon#9, #804
FG-32 §4: code symbols need a hand-edited module list absorbed packs carry their modules and composition unions them (r3-bundle-format) python/tests/bundles/test_compose.py
FG-33 §4: optional sources added after install hold unfilled placeholders (${deployment_name}, predecessor_source) absorbed archi add renders the pack with the deployment's own answers python/tests/bundles/test_lock.py
FG-34 §4, §8: after every registry edit, okg catalog ownership claim or the publish is refused as drifted absorbed archi add runs the claim and catalog load python/tests/bundles/test_lock.py
FG-35 §8: okg install --force rewrites deployment.yaml and resets the chat: block absorbed archi never runs --force: init refuses a non-empty directory and archi add only adds test_a_non_empty_directory_and_a_bad_name_are_refused
FG-36 §8: a reinstall can exit red at its ingest stage with its data staged anyway filed (ask D: mitdbg/akmon#10, #805) the exit code should tell "failed" from "staged, not published" mitdbg/akmon#10, #805
FG-37 §8: a large first publish ends with a lock_headroom warning that reads like a failure absorbed init treats okg provision exit 8 (capacity_warning) as published and says so test_provision_capacity_warning_is_not_a_failure
FG-38 §8: the TWiki dump path must be absolute and does not follow --archi-data-root absorbed as FG-07: path answers are made absolute absolute-paths check
FG-39 "Adding other sources": a removed source's records stay in the graph absorbed fixed in okg v0.2.0: okg deployment remove-source <deployment> <pack>.<source> --apply --yes retracts the source's records, publishes, and removes its registry entry. Draft ask E is withdrawn proven 2026-10-25 on a scratch cern-team instance: removing twiki.twiki_eos retracted 6 records and 5 links in a new generation; its page is node_not_found there, and other sources' records are still visible
FG-40 "Starting over": deleting the deployment folder is not a reset; the claim lives in the database absorbed archi down --purge --yes deletes the database volumes with the containers test_down_purge_deletes_volumes (test_stack.py)
FG-41 "Starting over": a run that fails partway wedges behind staged source work was not published; the only recovery is a teardown filed (ask D: mitdbg/akmon#10, #805) archi's recovery is archi down --purge --yes and a fresh init; okg should offer resume or discard mitdbg/akmon#10, #805
FG-42 "Starting over": okg install is not a retry absorbed archi init refuses an existing instance and names the reset test_a_non_empty_directory_and_a_bad_name_are_refused
FG-43 Found here: on public okg v0.2.0, okg chat-instance up refuses every published image; its pinned image is under your-registry.invalid absorbed; filed (ask A: mitdbg/akmon#7, #802) compose runs upstream open-webui:v0.11.4, which reads okg's text results, and okg chat sync accepts it golden-path run (PACT evidence)
FG-44 Found here: okg mcp-serve needs git on its PATH to serve reads (repository provenance is unavailable) absorbed; filed (ask F: mitdbg/akmon#11, #806) the MCP image installs git and marks the mounted instance safe golden-path run
FG-45 Found here: okg db role-passwords records passwords per loopback port in ~/.config/okg, so two instances that reuse a port overwrite each other absorbed archi points OKG_ROLE_SECRETS_FILE at the instance's own .secrets/ test_init_installs_commits_then_publishes
FG-46 Found here: a fresh instance's chat shows "OKG graph health: unavailable (error)" filed (ask G: mitdbg/akmon#12, #807) the banner reads okg's dogfood trust level, which a cern-team instance never reports ready mitdbg/akmon#12, #807
FG-47 §1: pip install archi installs an unrelated package absorbed the distribution is archi-kb (r3-release-home) python/tests/test_packaging.py
FG-48 §1: the SSO cookie helper needs requests-kerberos, which needs Kerberos headers absorbed the cern extra declares it python/tests/test_install_extras.py
FG-49 "Adding other sources": okg add works only for sources the deployment already knows (activation_blocked) absorbed archi add <pack> adds any installed pack python/tests/bundles/test_lock.py
FG-50 "Adding other sources": Indico talk images need an agent_surface block in deployment.yaml filed (ask H: mitdbg/akmon#13, #808) the block lives in the deployment manifest; okg should let a source declare the hosts it fetches mitdbg/akmon#13, #808

Not traps, and so not in the table: the docsite manifest for a site without a sitemap (a feature), and count drift between runs (§3, explained there).