Odin/AGENTS.md

Odin Instructions

Project Purpose

Odin is the all-seer and rendezvous organ for the CultMesh Verse: discovery, schema awareness, translation routes, and interface aggregation. Every other GameCult target is observed through Odin, which is why its availability is load-bearing for the estate rather than for itself.

Estate-wide doctrine — the Prime Directive, Code Is A Liability, the Loud Rebuild Contract, Odin-class architecture, the CultCache/CultNet/CultMesh substrate rules — lives in F:\Projects\CLAUDE.md and ~/.claude/CLAUDE.md and is loaded automatically. It is not repeated here.

Canonical State

• docs/architecture.md — the source-grounded architecture note.
• docs/transport-shortcut-inventory.md — a dated ledger. Entries are left as written and corrected by dated notes on top, never rewritten. Follow that convention for anything else recording history here.
• notes/ — compact re-entry packets. Read the newest before touching deployment.
• state/map.yaml — the current deployment and admission map. This is the one file that goes stale fastest; verify it against the host before trusting it.
• personas/gjallar.persona_state.cc — Gjallar's Persona state, in the portable gamecult.persona_state.v0 shape.

Important Paths

Relative to the repository root.

• Daemon: crates/odin-daemon
• Shared records and documents: crates/odin-core
• Deployment recipe Idunn seals and builds from: deployment/idunn/recipe.toml
• Operator binding (lives on the host, not here): /etc/gamecult/idunn/bindings/odin.toml

Build And Deploy Target

Odin runs on Linux under Idunn on yggdrasil. This workstation is Windows and is where the shell is, not where the artifact runs: a local compile is not evidence about the Linux release. Build on the target or through the deploy path's own builder, and say which one you used.

git archive HEAD | ssh ygg 'sudo rm -rf /srv/build/odin && sudo mkdir -p /srv/build/odin && sudo tar -x -C /srv/build/odin && sudo chown -R gamecultadmin:gamecultadmin /srv/build/odin'
ssh ygg 'sudo docker run --rm -v /srv/build/odin:/w -v /etc/machine-id:/etc/machine-id:ro -v /srv/build/cargo-registry:/usr/local/cargo/registry -v /srv/build/cargo-git:/usr/local/cargo/git -w /w rust:1.95-bookworm cargo test -p odin-core -p odin-daemon'

/etc/machine-id must be mounted or every identity-enrolling test fails with Linux machine-id is unavailable — a wall of failures that looks like broken code and is a missing mount.

Scope test runs to the crates you are changing. Muninn's crates live in GameCult/Muninn now, not in this workspace.

Session Bootstrap And Re-entry Protocol

On fresh session load, before touching deployment:

1. Read the newest file in notes/.
2. Read state/map.yaml, then verify it on the host — it describes a live system and is the first thing to rot.
3. git log --oneline -5 and git status --short --branch.

The host is authoritative for every question of the form "is X running", "is X admitted", "what release is live". Two commands answer most of them:

ssh ygg 'systemctl list-units --all "idunn-odin-*" --state=active'
ssh ygg 'sudo /usr/local/bin/idunn status --state-store /var/lib/gamecult/idunn/control.cc'

Operating Discipline

• Never conclude from a partial listing. systemctl list-units | head sorts alphabetically and will hide the one active unit among dozens of failed ones. Enumerate completely or state that the answer is unknown.
• A unit can be active and own no process. odin.service in /etc/systemd/system/ is exactly that: active, MainPID 0, owning nothing. It has misled at least two separate readings. Check -p MainPID before believing a status line.
• Read the journal with sudo journalctl -q. Unprivileged journalctl shows only your own messages and returns a false zero on Started idunn-odin counts.
• Verify changing facts against the host or source, never against a document — including the documents in this repository.
• Redeploying Odin is not routine. Read notes/ first; the failure mode is documented and it is not obvious.