Heimdall/AGENTS.md

Heimdall Instructions

Project Purpose

Heimdall exists to hold the shared auth authority design for GameCult-hosted experiments without letting that shared layer metastasize into a giant mixed-data pit.

The planned shared authority owns:

• provider OAuth and linking
• signed session / claim issuance
• entitlement refresh
• capability evaluation
• app-facing access claims
• audit and grant surfaces

The planned non-shared-by-default layer is:

• app-domain user data
• audience data
• creator data
• queue/job payloads
• product-specific state
• app-local resource ownership checks

Canonical State

• Treat state/map.yaml as the canonical current project map.
• Treat state/scratch.md as disposable working memory for one bounded subgoal.
• Treat state/evidence.jsonl as the distilled durable ledger of decisions, verified boundaries, and rejected paths.
• Treat state/branches.json as hypothesis tracking, not phase/status prose.
• Treat notes/fresh-workspace-handoff.md as the compact re-entry packet.
• Treat docs/architecture.md as the source-grounded shared architecture note.
• Treat docs/implementation-plan.md as the forward plan.
• Treat docs/app-profiles/repixelizer.md and docs/app-profiles/streampixels.md as thin app bindings, not the whole shared architecture. Add new app-profile notes when a new app binding needs durable context.

Important Paths

Paths are relative to the repository root. Do not hard-code an absolute drive path into this file; the repo has already been moved between drives once, and every absolute path in here rotted the moment it happened.

• Shared architecture: docs/architecture.md
• Implementation plan: docs/implementation-plan.md
• Repixelizer profile: docs/app-profiles/repixelizer.md
• StreamPixels profile: docs/app-profiles/streampixels.md
• Spotiverse profile: docs/app-profiles/spotiverse.md
• Handoff summary: notes/fresh-workspace-handoff.md
• State CLI: tools/heimdall_state.py
• Pre-compaction helper: tools/heimdall_prepare_compaction.py

Useful Commands

Both state tools are single-file, standard-library-only Python. They need no virtualenv and no installed dependencies. Run them with python from the repo root:

python .\tools\heimdall_state.py status
python .\tools\heimdall_state.py add-evidence --type design --status accepted --note "..."
python .\tools\heimdall_prepare_compaction.py

Verified 2026-09-06 against Python 3.13.15 installed to the user scope; py -3 resolves the same interpreter.

If python --version prints an install prompt rather than a version, PATH is resolving the Microsoft Store alias in WindowsApps instead of a real interpreter, and it will still exit 0 while doing so. Install a real Python and put it ahead of WindowsApps on PATH rather than hunting for some other interpreter to hard-code here:

winget install --id Python.Python.3.13 --scope user

Session Bootstrap And Re-entry Protocol

On fresh session load:

1. read:
   • state/map.yaml
   • notes/fresh-workspace-handoff.md
   • docs/architecture.md
   • docs/implementation-plan.md
2. run:
   • python .\tools\heimdall_state.py status
   • git status --short --branch
   • git log --oneline -5
3. restate the current next action from persisted state before editing

After compaction or suspicious continuity loss:

1. rerun heimdall_state.py status
2. reread state/map.yaml and notes/fresh-workspace-handoff.md
3. treat the persisted next action as authoritative unless fresh evidence contradicts it

When the user says to prepare for imminent compaction:

1. run tools/heimdall_prepare_compaction.py
2. update only the state that actually changed
3. rerun the helper
4. commit the completed persistence pass unless the work is deliberately mid-surgery

After any major completed pass, assume compaction may be imminent even if the user did not say so yet:

1. run tools/heimdall_prepare_compaction.py
2. sync only the persistent state that genuinely changed
3. rerun the helper
4. commit the persistence pass before moving on unless the work is deliberately mid-surgery
5. push the current branch to origin after the major pass unless the user explicitly says not to publish yet

Operating Discipline

• Before substantial edits, restate the current mechanism and intended change.
• Keep identity authority central and app-domain data local unless there is a very deliberate, source-grounded reason to share something.
• Prefer the Yggdrasil-hosted Heimdall service over duplicated per-app provider stacks.
• Do not require a Heimdall round-trip for every guarded app route; host apps should verify signed claims locally and keep resource ownership checks local.
• Do not let app profiles turn into duplicate copies of the shared architecture.
• If the diff grows while the boundary gets blurrier, stop and simplify.
• Before handoff or compaction, sync state/map.yaml, refresh notes/fresh-workspace-handoff.md, add distilled evidence when future belief changed, and make the next action explicit.

Build And Deploy Target

Heimdall runs as the auth authority behind Yggdrasil-hosted nginx at heimdall.gamecult.org, on Linux. Idunn owns the deployment transaction. 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, because toolchain, linker, filesystem semantics and path handling all differ. Build for the target, or let the deploy path's own builder do it, and say which one you used.

External Context

• For StreamPixels architecture/auth context, prefer the indexed StreamPixels repo through voidbot before filesystem spelunking.
• For GameCult deployment and host conventions, check the sibling gamecult-ops repo in the same projects root as this one before improvising infra claims.