[codex] require Codex handoff docs

AGENTS.md

@@ -41,6 +41,30 @@ git add -A && git commit -m "vX.XX: description" && git push
 
 ---
 
+## Codex Handoff Requirement
+
+For any meaningful Codex work, create or update a Markdown handoff file under
+`docs/` before finishing. This applies to local-only changes, pushed branches,
+pull requests, field-log reviews, debugging sessions, release decisions, and
+weekly progress checks.
+
+Use `docs/CODEX_HANDOFF_TEMPLATE.md` as the starting format. A handoff note
+should include:
+
+- date, branch, commit, and PR link if one exists
+- what changed or what was diagnosed
+- why it matters for BlindNav
+- exact files touched or logs reviewed
+- commands/tests run and their results
+- known caveats, failed attempts, and next steps for the next Codex chat
+
+If the work is pushed to GitHub, include the handoff doc in the PR unless the
+user explicitly says not to. Do not paste secrets, API keys, full raw logs, or
+private personal data into docs; summarize sensitive logs and reference their
+safe location instead.
+
+---
+
 ## Hard Rules — Never Break These
 
 **NEVER send SIGTERM to aplay.**

docs/CODEX_HANDOFF_2026-05-03.md

@@ -0,0 +1,67 @@
+# Codex Handoff - 2026-05-03
+
+## Session
+
+- Date: 2026-05-03
+- Branch: `codex/add-codex-handoff-doc-rule`
+- Commit: pending
+- Pull request: pending
+- Related issue/logs: user requested persistent handoff docs for future Codex chats
+
+## Summary
+
+Added a repo-level requirement that future Codex sessions must create or update
+a Markdown handoff file under `docs/` whenever they do meaningful work.
+
+## Why It Matters
+
+BlindNav work often happens across the Codex app, Pi terminal sessions, school
+computer sessions, GitHub branches, and field logs. Raw Codex conversations may
+not be easy to recover later, so the durable record should live in GitHub docs
+and PRs.
+
+## Files Or Logs Used
+
+- `AGENTS.md`
+- `docs/CODEX_HANDOFF_TEMPLATE.md`
+
+## Evidence
+
+The new `AGENTS.md` rule tells future Codex sessions to document meaningful
+work:
+
+```md
+For any meaningful Codex work, create or update a Markdown handoff file under
+`docs/` before finishing.
+```
+
+The template gives future sessions a consistent structure:
+
+```md
+## Summary
+## Why It Matters
+## Files Or Logs Used
+## Evidence
+## Validation
+## Caveats
+## Next Steps
+```
+
+## Validation
+
+No runtime tests were needed because this is a documentation-only workflow
+change.
+
+## Caveats
+
+- This rule depends on future Codex sessions reading `AGENTS.md`.
+- It does not automatically sync raw local Codex conversations to Codex Cloud.
+- Handoff docs should summarize sensitive logs instead of pasting secrets or
+  full private raw logs.
+
+## Next Steps
+
+1. Push this branch.
+2. Open a PR into `main`.
+3. In future Codex work, include a handoff doc in the same PR unless explicitly
+   told not to.

docs/CODEX_HANDOFF_TEMPLATE.md

@@ -0,0 +1,59 @@
+# Codex Handoff Template
+
+Use this template whenever Codex does meaningful local work, opens a branch,
+opens a PR, reviews field logs, or makes a repo-backed decision.
+
+## Session
+
+- Date:
+- Branch:
+- Commit:
+- Pull request:
+- Related issue/logs:
+
+## Summary
+
+Shortly describe what changed or what was diagnosed.
+
+## Why It Matters
+
+Explain how this affects BlindNav safety, latency, reliability, testing, field
+workflow, or release readiness.
+
+## Files Or Logs Used
+
+- `path/to/file`
+- `path/to/log`
+
+## Evidence
+
+Include small code snippets, log snippets, command output, or test results.
+Do not include API keys, secrets, or full raw private logs.
+
+```text
+example output
+```
+
+## Validation
+
+```bash
+pytest tests/test_blindnav.py tests/test_blindnav_v326.py -q
+```
+
+Result:
+
+```text
+example: 174 passed
+```
+
+## Caveats
+
+- What was not tested?
+- What might be stale?
+- What should the next Codex chat verify first?
+
+## Next Steps
+
+1. Next concrete action.
+2. Follow-up validation.
+3. GitHub branch or PR action if needed.