# Token and Context Budget Policy

This repository is intentionally documentation-heavy. Codex must not load all documents for every task.

## Context tiers

### Tier 0 — Always read

- `CODEX_START.md`
- `docs/00-start/START_HERE.md`
- `docs/30-codex-optimization/CODEX_RUN_CHECKLIST.md`
- active pass prompt

### Tier 1 — Read when architecture-sensitive

- `docs/governance/GEOINTEL_CONSTITUTION.md`
- `docs/governance/ARCHITECTURE_INVARIANTS.md`
- `docs/governance/FORBIDDEN_DECISIONS.md`
- relevant ADRs

### Tier 2 — Read when module-specific

- relevant module spec
- relevant skill
- relevant API/database contract
- relevant tests/fixtures

### Tier 3 — Historical reference only

- old milestone handoff summaries
- previous pass prompts not active for the current run
- release notes from previous preparation milestones

## Budget rules

- Prefer reading indexes before detailed specs.
- Prefer targeted `grep/find` over opening large unrelated docs.
- Do not re-summarize old milestones unless needed.
- Work in small coherent diffs.
- If a task requires touching more than three major subsystems, split it into passes.
- If the active prompt conflicts with governance, stop and report.

## Large file policy

Large generated files, model artifacts, tiles, rasters and exports must not be created during documentation-preparation passes unless they are tiny fixtures. Real heavy assets belong outside git or in storage paths documented by `docs/STORAGE_ARCHITECTURE.md`.