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:

```powershell
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:

```powershell
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.

## 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.