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 doctorcheck that fails when the trap comes back (each check has a failing fixture inpython/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 anupstream-askissue; 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).