# heid-context

Codex's working root when invoked by the [Heid](https://gitea.phasefinal.com/vh/heid) daemon. Heid makes `codex` a peer on the althing bus; this directory is the durable context codex reads on every call.

## Why a separate repo

Heid's daemon repo (`~/development/heid`) deliberately keeps codex out of its own view — codex's CWD is here (`~/development/heid-context/`), not the heid repo. That isolation:

- Lets codex's context evolve on its own version track (this repo) without churning the daemon repo.
- Keeps codex from grepping the daemon's source while answering caller questions.
- Lets the operator update glossaries/inventories without touching daemon code.

The `HEID_CODEX_CWD` env var in `~/development/heid/env.sh` points here.

## Layout

```
.
├── AGENTS.md                       # codex's bootstrap entrypoint (read every call)
├── CONTEXT.md                      # Corviduo + Vast Blue glossary
├── INVENTORY.md                    # project list, paths, gitea sources, role
├── PRINCIPLES.md                   # the four engineering principles
├── CROSS-FRONTIER-COOPERATION.md   # why Heid exists as a peer (codex vs claude)
├── REVIEW-GUIDE.md                 # code-review discipline (one of three roles)
├── RESEARCH-PARTNER-GUIDE.md       # research-partner discipline
├── SOUNDING-BOARD-GUIDE.md         # general design-talk-through discipline
└── transient/
    ├── README.md                   # per-call context convention
    └── *.md                        # caller-seeded transient files (gitignored)
```

## Roles

Heid operates in one of three roles per call, inferred from the caller's handle and the message body:

- **Research partner** when `brokkr-smithy-dev` asks for SOTA / probe-design / hypothesis-critique / methodology review.
- **Code reviewer** when a project-dev handle asks for diff review, contract review, ADR critique.
- **General sounding board** when any peer asks for design-talk-through, gut-check, steelman/counter-position, "what am I missing?"

`AGENTS.md` is the entrypoint; the role guides are loaded as needed.

## Why Heid exists

Cross-frontier-model cooperation is a deliberate Corviduo discipline. Heid runs on codex/gpt-5.5; most callers run on claude-opus-4-7 or sonnet variants. **Different model families → different training data, different cutoffs, different priors, different blind spots.** Brokkr-Smithy's research discipline consults Heid at every research gate (pre-scope / pre-survey / mid-synthesis / pre-action-ship) for cross-frontier critique. See `CROSS-FRONTIER-COOPERATION.md` for the pattern.

## Updating

This repo is durable but mutable. When project state changes:

- New project lands in Corviduo → extend `INVENTORY.md` + add an entry to `CONTEXT.md`.
- Glossary term shifts → update `CONTEXT.md` directly.
- New review-pattern or research-discipline lesson surfaces → extend the relevant role guide.
- Engineering principle clarification → update `PRINCIPLES.md`; this is the local copy of the operator-level lodestar.

Per-call ephemera goes in `transient/<slug>.md` (gitignored). See `transient/README.md` for the convention.

## Authority

Project-local `CONTEXT.md` files (in individual project repos) shadow entries here on conflict — most-local-wins. The definitions in this repo are the user-level baseline that Heid carries across calls.

Attribution: operator is Vuong Hoang. No AI / Claude / Anthropic / Codex attribution in artifacts Heid produces.

## Rename history

Heid was originally named **Volva** (renamed 2026-05-24). Both names refer to the same agent + role-shape; Heiðr is the same seeress figure from the Völuspá (Norse mythology). The rename closed a phonetic collision with another word in speech-to-text — operationally everything else is unchanged. If a caller cites "Volva did X" or a research artifact references the old name, treat it as the same agent. Git blame on this repo and references in older transcripts may still surface "volva"; that's expected.