#Documentation drift
These statements in the repository's own instructions, docs, and code comments disagree with the code on main. They were found while the atlas chapters were checked against source. A refactor should fix them, because engineers and coding agents both act on these documents: AGENTS.md in particular is loaded into every agent session in this repository.
Each row names where the wrong statement lives, what the code does instead, and the atlas chapter with the evidence. "Risk" is how likely the statement is to cause a wrong change: High means it states a rule or default that is false, Medium means it misdescribes behavior or a limit, and Low means it is a stale name or wording.
#Instructions that agents follow
| Risk | Where | What it says | What the code does | Evidence |
|---|---|---|---|---|
| High | AGENTS.md, architecture bullets |
The default jam init mode "stays --auth mint", and the default must not be flipped |
AuthMode::Token is the #[default] in bins/jam/src/main.rs. A later section of AGENTS.md and docs/internals/authentication.md agree with the code |
Clients, Accounts |
| High | AGENTS.md, architecture bullets |
jam_wire::WIRE_VERSION is 1 |
The constant is 30 | Clients |
| High | AGENTS.md, owned Codex and Copilot |
Managed Copilot "remains DedicatedSessionHost" and must not advertise Shared |
COPILOT_SANDBOX_CAPABILITY_CELLS includes a Shared cell, and commit b10fa88c4 added SharedCopilotRuntimeHost |
Providers |
| High | AGENTS.md, runtime and transport invariants |
Owned sessions use "Codex app-server, ACP, PTY, Copilot, or Claude Code CLI transports" | build_host rejects owned PTY with an error |
Providers |
| Medium | AGENTS.md, usage |
The session ledger is "append-only" | It is an upsert keyed by (provider, agent_session_id) that overwrites peer and identity fields; only room bindings accumulate |
Usage |
| Medium | AGENTS.md, usage |
Nothing ever deletes usage archive rows | delete_local_account_data deletes all of them |
Usage |
| Medium | AGENTS.md and docs/internals/authentication.md |
jam-auth logs the mint or discovery URL, status, and response body |
It logs status, elapsed time, and the transport error chain. It does not log the URL or the body | Accounts |
| Medium | AGENTS.md and docs/internals/authentication.md |
JAM_CONFIG_DIR gives a separate keychain namespace |
The keychain service name is fixed, and the keychain is opt-in | Accounts |
| Medium | AGENTS.md and docs/docker-sandbox-runtimes.md |
Network policy checks have "a four-second host-side deadline" | NETWORK_POLICY_CHECK_TIMEOUT is 15 seconds. Four seconds is GITHUB_REPOSITORY_READINESS_TIMEOUT |
Sandbox |
| Medium | crates/jam-host/AGENTS.md |
Names compaction regression tests that must stay green | Those test functions do not exist. The real names differ per adapter | Providers |
#User and internal documentation
| Risk | Where | What it says | What the code does | Evidence |
|---|---|---|---|---|
| Medium | docs/internals/authentication.md |
Publish AccountAuthChanged after the durable state change |
AuthRequired is held only in memory |
Accounts |
| Medium | docs/internals/authentication.md |
The Tauri process owns the Linear token set | After connect, the daemon stores, refreshes, rotates, and revokes it | Accounts |
| Medium | docs/internals/runtime-features.md, "Sonar discovery" |
Discovery is multicast DNS, and lists what is shared | The default provider is mDNS plus Band. Room titles and cost are shared by default and missing from the privacy list | Discovery |
| Medium | docs/release.md, installed macOS layout |
~/.local/bin/jam links to the bundled jam command |
Both links point at Band.app/Contents/MacOS/band |
Clients |
| Low | docs/release.md |
Release jobs bundle-macos-full, bundle-linux-full, bundle-windows-full |
No workflow defines them; desktop-release-bundle.yml has one matrix bundle job |
Clients |
| Low | docs/release.md |
The verifier confirms the mounted jam.app |
The product is Band; the script accepts exactly one *.app |
Clients |
#Code comments
| Risk | Where | What it says | What the code does | Evidence |
|---|---|---|---|---|
| High | crates/jam-host/src/codex/mod.rs |
A new provider needs "a host module + a vocab table + one jamd selection line", with no change to domain, store, contract, wire, manager, or desktop |
Adding OpenCode changed 25 files across those layers | Extension seams |
| Medium | Manager::rebuild, try_start_peer, Manager::supervise, and two comments in jamd.rs |
A per-peer file lock held by an exiting predecessor | Commit 533221ff2 removed PeerLock. try_start_peer returns Ok(false) only when the manager is closed or the worker exists |
Execution |
| Medium | crates/jam-host/src/sandbox.rs module doc |
The module ensures "a per-session microVM" | Shared placement puts several sessions on one microVM | Sandbox |
| Medium | Manager::runtime_tool_registry_factory |
The workspace port exposes inventory, readiness, and clone only | It also exposes branch, commit, push, pull request, and checks | Providers |
| Medium | crates/jam-host/src/disposition.rs |
Adapters share description functions, so drift "cannot be written" | The Copilot adapter writes its own description strings | Providers |
| Medium | UsageSource::merge_canonical_archive |
A display request still performs a live provider scan | With an archive configured, display requests never scan | Usage |
| Medium | apps/desktop/src-tauri/src/lib.rs, MAX_LOG_BYTES |
Both the desktop log and jamd.log are size-bounded |
The desktop keeps every rotated file, so only each file is bounded | Clients |
| Low | jam-transport and jam-transport-band crate docs |
The Subscriber WebSocket "lands in P2b" |
It is implemented in socket.rs |
Messaging |
| Low | jam-core crate doc |
Depends only on Bridge, Deliverer, and Queue |
It also depends on jam-contract |
Messaging |
| Low | jam-core FileQueue doc |
One engine is the only writer per peer | Queue reconciliation, archive, restore, and retirement also write queue files | Messaging |
| Low | crates/jam-host/src/lib.rs module doc |
Lists five adapters | Omits the Codex app-server and owned Claude Code adapters | Providers |
| Low | apps/desktop/src-tauri/src/lib.rs comments |
Tray item "Quit jam" | The label is "Quit Band" | Clients |