# AGENTS.md

## Purpose

Mimir is the public face of this repo: the local realtime field machine for
turning cameras, microphones, speakers, and timing signals into one coherent
OBS-facing volumetric program surface.

Some native ABI names still use `localcast` until a deliberate rename cut exists.

Keep this repo blunt. The goal is not to fork OBS for sport. Use existing OBS and FFmpeg surfaces until a real invariant is impossible without native code.

For the persistent Mimir Face agent identity, voice, jurisdiction, avatar, and
VoidBot heartbeat contract, read `docs/mimir-face.md`.

## Persistence Scaffolding

- Treat `state/map.yaml` as the canonical current map for this repo.
- Treat `state/scratch.md` as disposable scratch for one bounded subgoal.
- Treat `state/evidence.jsonl` as the distilled durable ledger of decisions, verifications, rejected paths, and scars that change future belief.
- Treat `state/branches.json` as the lightweight branch/hypothesis ledger.
- Treat `notes/fresh-workspace-handoff.md` as the short re-entry packet.
- Treat `notes/current-system-map.md` as the current source-grounded architecture and data-flow map.
- Treat `docs/implementation-plan.md` as the forward plan for what is implemented, temporary, and next.
- Treat `docs/mimir-face.md` as the persistent Face memory for the Mimir agent.
- Update `state/map.yaml` when project understanding changes. Add evidence only when the lesson changes what the next agent should believe.
- Keep exact branch and HEAD snapshots out of handoff prose. Git commands own volatile truth.
- Commit `.voidbot` state whenever it is dirty, even if you did not create the
  changes. Put it in a separate state commit so Face memory and status do not
  stay stranded as local-only residue.

## Persistence Commands

Use a real Python if the Windows Store alias gets cute. In this Codex
workstation, the bundled runtime is:
`C:\Users\Meta\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe`.

```powershell
& 'C:\Users\Meta\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe' .\tools\localcast_state.py status
& 'C:\Users\Meta\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe' .\tools\localcast_state.py add-evidence --type decision --status ok --note "..."
& 'C:\Users\Meta\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe' .\tools\localcast_prepare_compaction.py
```

## Session Bootstrap And Re-entry Protocol

On a fresh session, do this before editing:

1. read:
   - `state/map.yaml`
   - `notes/fresh-workspace-handoff.md`
   - `notes/current-system-map.md`
   - `docs/implementation-plan.md`
2. run:
   - `& 'C:\Users\Meta\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe' .\tools\localcast_state.py status`
3. restate the current mechanism, intended change, and next bounded move before broad edits

After compaction, resume, or suspicious continuity loss:

1. rerun `& 'C:\Users\Meta\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe' .\tools\localcast_state.py status`
2. reread `state/map.yaml` and `notes/fresh-workspace-handoff.md`
3. treat the persisted next action as orientation, not permission to wander

When the user says to prepare for imminent compaction:

1. immediately write the hot context into a collision-proof scratch file under `state/`
2. run `tools/localcast_prepare_compaction.py` before editing persistence surfaces
3. use its warnings as the checklist for map, handoff, scratch, evidence, and git hygiene
4. update only the state that actually changed
5. run `tools/localcast_prepare_compaction.py` again after edits
6. commit the completed persistence pass unless the work is deliberately mid-surgery

## Operating Discipline

- Before substantial edits, restate the current mechanism and intended change.
- Prefer one clear hypothesis per iteration.
- Do not keep corpses of previous attempts at building the Machine. When a new
  mechanism supersedes an old one, either delete the old mechanism or demote it
  to an explicitly named diagnostic/reference artifact with no live authority.
  Do not leave dead pipelines selectable, documented as current, or quietly
  reachable through mode flags just because they once worked.
- Verify against OBS ingest behavior and actual sender-side FFmpeg capability, not vibes wearing a lab coat.
- Do not add an OBS plugin, fork, registry, custom transport daemon, or compatibility layer until the script-based SRT design fails a concrete invariant.
- Keep video, audio-source isolation, transport, and OBS composition as separate responsibilities.
- If the diff grows while understanding shrinks, stop implementation and update the map.

## Product Truths

- V1 is a LAN bridge, not an internet relay.
- Sender-side video encoding must use NVENC when available.
- Receiver-side OBS should see stable source URLs that can be added as Media Sources.
- Audio must remain separately mixable in OBS. That means separate audio endpoints in v1, even if a later synchronized bundle becomes useful.
- The repo owns repeatable setup, scripts, config, and operating docs. FFmpeg and OBS own media work.