# AGENTS.md — agent-tool doorway

[AGENT.md](AGENT.md) is the single binding session entry point. Read and follow
it before changing anything. This doorway keeps only the current, easy-to-miss
guardrails; it does not replace the full rule set.

For quick orientation: [DESIGN.md](DESIGN.md) is navigation only, the whole
typed [wiki](wiki/overview.md) is the design corpus,
[wiki/process/ROADMAP.md](wiki/process/ROADMAP.md) dispatches work, and
[wiki/process/meta.md](wiki/process/meta.md) defines the corpus format.

The repository worktree convention is `.Codex/worktrees/<task>` with branch
`worktree-<task>` (override the root with `MISALIGNED_WORKTREE_ROOT`). Never
edit the shared primary checkout. If a patch tool resolves paths from that
checkout, address the task worktree explicitly and verify both worktree
statuses afterward.

## Current guardrails

- Start repository work with the [tick](wiki/process/tick.md), then inspect
  `tools/claim.sh list` and `tools/project-status.py`. Activity overlap is
  advisory, not a lock; worktrees isolate edits and final rebase/check
  reconciles them.
- This is a Cargo **workspace**, not a feature-switched root crate. Product
  code lives in `crates/misaligned-{core,terminal,bevy,assets}/`; there is no
  root product `src/` tree and no `bevy_ui` feature path. Use package-aware
  commands such as `cargo test -p misaligned-core`,
  `cargo build -p misaligned-bevy --bin misaligned-bevy`, or the proportional
  `./tools/check.sh --docs|--lib|--frontend` gate.
- The live player machine grammar is **WORK / THINK / LIE**. `Relay` is
  non-delegable graph infrastructure; Research and Operations are retired
  machine modes, not current player assignments. The save schema moves
  quickly: read `SAVE_VERSION` and the current-schema load gate in
  `crates/misaligned-core/src/save.rs` before making any compatibility claim.
  During pre-release only the exact current version loads; the deleted
  migration ladder lives in git history. Do not freeze a version number in
  this doorway.
- Any change to `crates/` must amend its owning `Type: law` or `Type: spec` in
  `wiki/` and carry a Defense. Documentation work updates stale knowledge,
  adds a dated `wiki/log/` entry, then runs `tools/ledger_index.sh`; never
  hand-edit generated `wiki/log/DEVLOG.md` or `wiki/process/specs.md`.