Every path in Important Paths, Useful Commands, and External Context named the lost E: drive. CLAUDE.md is a bare @AGENTS.md import, so those dead paths were loaded into every session in this repo. Swapping E: for F: would only reset the timer, so the paths are now repo-relative and gamecult-ops is named as a sibling repo rather than an absolute location. All ten referenced files were confirmed present after the move; none were lost with the drive. The interpreter guidance was worse than stale. It pointed at a venv under the dead drive, and the documented fallback did not work either: this workstation had no Python at all, and both `python` and `python3` resolved to Microsoft Store aliases that print an install prompt and exit 0. Python 3.13.15 is now installed to the user scope and ahead of WindowsApps on PATH, both tools were run under it, and the section documents that failure mode so the next agent installs an interpreter instead of hard-coding a path to someone else's. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
5.3 KiB
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.yamlas the canonical current project map. - Treat
state/scratch.mdas disposable working memory for one bounded subgoal. - Treat
state/evidence.jsonlas the distilled durable ledger of decisions, verified boundaries, and rejected paths. - Treat
state/branches.jsonas hypothesis tracking, not phase/status prose. - Treat
notes/fresh-workspace-handoff.mdas the compact re-entry packet. - Treat
docs/architecture.mdas the source-grounded shared architecture note. - Treat
docs/implementation-plan.mdas the forward plan. - Treat
docs/app-profiles/repixelizer.mdanddocs/app-profiles/streampixels.mdas 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:
- read:
state/map.yamlnotes/fresh-workspace-handoff.mddocs/architecture.mddocs/implementation-plan.md
- run:
python .\tools\heimdall_state.py statusgit status --short --branchgit log --oneline -5
- restate the current next action from persisted state before editing
After compaction or suspicious continuity loss:
- rerun
heimdall_state.py status - reread
state/map.yamlandnotes/fresh-workspace-handoff.md - treat the persisted next action as authoritative unless fresh evidence contradicts it
When the user says to prepare for imminent compaction:
- run
tools/heimdall_prepare_compaction.py - update only the state that actually changed
- rerun the helper
- 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:
- run
tools/heimdall_prepare_compaction.py - sync only the persistent state that genuinely changed
- rerun the helper
- commit the persistence pass before moving on unless the work is deliberately mid-surgery
- push the current branch to
originafter 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, refreshnotes/fresh-workspace-handoff.md, add distilled evidence when future belief changed, and make the next action explicit.
External Context
- For StreamPixels architecture/auth context, prefer the indexed
StreamPixelsrepo throughvoidbotbefore filesystem spelunking. - For GameCult deployment and host conventions, check the sibling
gamecult-opsrepo in the same projects root as this one before improvising infra claims.