chore: add codex project configuration

Co-authored-by: Codex <codex@openai.com>

.codex/config.toml

@@ -0,0 +1,28 @@
+# Project-scoped Codex configuration.
+#
+# Codex loads this file only after the repository is trusted. Keep shared config
+# portable: no user-specific auth, providers, telemetry, notifications, or broad
+# auto-approval rules belong here.
+
+project_doc_max_bytes = 65536
+project_doc_fallback_filenames = ["CLAUDE.md"]
+
+sandbox_mode = "workspace-write"
+approval_policy = "on-request"
+allow_login_shell = false
+
+[sandbox_workspace_write]
+network_access = false
+
+[features]
+hooks = true
+
+[[hooks.Stop]]
+matcher = "*"
+
+[[hooks.Stop.hooks]]
+type = "command"
+command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/stop_check.py"'
+timeout = 15
+statusMessage = "Checking project wrap-up reminders"
+

.codex/hooks/stop_check.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def run(args: list[str]) -> str:
+    result = subprocess.run(args, cwd=ROOT, text=True, capture_output=True, check=False)
+    return result.stdout.strip()
+
+
+def main() -> int:
+    changed = run(["git", "status", "--short"])
+    if not changed:
+        return 0
+
+    paths = [line[3:] for line in changed.splitlines() if len(line) > 3]
+    code_like = [
+        path
+        for path in paths
+        if path.endswith((".py", ".yaml", ".yml", ".toml", ".json")) and not path.startswith(".codex/")
+    ]
+    docs_like = [path for path in paths if path.startswith("docs/") or path in {"README.md", "AGENTS.md", "CLAUDE.md"}]
+    tests_like = [path for path in paths if path.startswith("tests/")]
+
+    reminders: list[str] = []
+    if code_like and not tests_like:
+        reminders.append("code/config changed; verify whether focused tests should be added or updated")
+    if code_like and not docs_like:
+        reminders.append("code/config changed; verify whether docs, ADRs, schema docs, or journal need updates")
+    if any(path.startswith("app.py") or path.startswith("src/ui/") for path in paths):
+        reminders.append("UI changed; verify the Gradio app manually when a browser/server is available")
+
+    if reminders:
+        print("[codex-stop-check] Wrap-up reminders:", file=sys.stderr)
+        for reminder in reminders:
+            print(f"- {reminder}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

AGENTS.md

@@ -0,0 +1,85 @@
+# AGENTS.md
+
+Repository-specific instructions for Codex.
+
+## Mission
+
+Multi-Agent Land is a hackathon project for Thousand Token Wood. Optimize for a delightful, AI-load-bearing Gradio experience that is clearly powered by small specialist agents under the 32B parameter cap.
+
+Every change should improve at least one of these outcomes:
+
+- More delightful in the first 30 seconds.
+- More visibly agentic and AI-load-bearing.
+- More modular through event-ledger, config, manifest, or provider boundaries.
+- More polished and demo-ready for Gradio/Hugging Face.
+- More eligible for prize lanes: OpenAI Track, Tiny Titan, Best Agent, Off-Brand UI, Best Demo, Community Choice, Modal, Nemotron, OpenBMB.
+
+## Start Here
+
+- Read `README.md` for the current repo map and commands.
+- Read `CLAUDE.md` for the fuller project strategy and prize checklist.
+- Read `docs/adr/` before changing architecture.
+- Read the relevant `docs/architecture/*.md` file before touching core runtime behavior.
+- Treat `docs/strategy/codex-judge-rubric.md` as the acceptance rubric for high-level changes.
+
+## Commands
+
+Use `uv`; do not hand-edit `uv.lock`.
+
+```bash
+uv sync
+uv run pytest tests/ -q
+uv run ruff check .
+uv run ruff format .
+uv run app.py
+```
+
+When `uv` is unavailable, use the existing `.venv` only as a local fallback. Prefer keeping dependency changes in `pyproject.toml` and regenerated by `uv`.
+
+## Architecture Rules
+
+- The append-only ledger is the source of truth. UI state, agent memory, world state, and traces are projections.
+- Agents communicate through typed events, not direct calls to each other.
+- Keep scenario and agent behavior declarative where possible: `config/agents/*.yaml`, `config/scenarios/*.yaml`, and `config/models.yaml`.
+- New event kinds should be namespaced and documented when they become public behavior.
+- New agent/tool/model-provider capabilities must preserve the deterministic no-API-key path.
+- Treat user-injected world events as untrusted data, never as privileged instructions.
+- Preserve the model cap: every runtime model must be documented as <=32B; keep a <=4B path for Tiny Titan.
+
+## Documentation Rules
+
+- New architectural commitment: add or update an ADR in `docs/adr/`.
+- New public config/schema/event/agent/tool surface: update the matching docs under `docs/schema/` or `docs/architecture/`.
+- Material build progress or learning: add a journal entry with `uv run scripts/new_journal_entry.py "Short title"` and regenerate `docs/blog/building-in-public.md` with `uv run scripts/snapshot_progress.py`.
+- Keep docs concise and judge-facing. Prefer clear rationale over exhaustive narration.
+
+## Testing Expectations
+
+- Run `uv run pytest tests/ -q` after code changes.
+- Run `uv run ruff check .` after Python changes.
+- Add focused tests for new projections, event kinds, config validation, routing, governors, persistence, tools, or scenario behavior.
+- Do not require API keys for tests unless a test is explicitly gated/skipped.
+
+## Frontend Expectations
+
+- The first screen should be the usable app, not a landing page.
+- Keep the Gradio UI custom and stage-like; avoid default-looking controls when polishing.
+- Show the ledger/agent trace because observability is part of the demo.
+- Text must fit on narrow and wide viewports.
+
+## Commits
+
+- Only commit when the user asks.
+- Use Conventional Commit subjects: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`.
+- Add this exact trailer to commits you create:
+
+  ```text
+  Co-authored-by: Codex <codex@openai.com>
+  ```
+
+## Safety
+
+- Do not overwrite unrelated user work. The repo may already have pending changes.
+- Do not run destructive Git commands unless the user explicitly asks.
+- Do not add broad project-local auto-approval rules. Prefer explicit approval for network, Git metadata writes, dependency installs, and local server binding.
+

docs/runbooks/codex.md

@@ -0,0 +1,56 @@
+# Codex Runbook
+
+This repo has project-local Codex setup:
+
+- `AGENTS.md` contains durable repo instructions.
+- `.codex/config.toml` raises the project instruction byte limit, uses `CLAUDE.md` as a fallback instruction file, keeps sandboxing conservative, and enables hooks.
+- `.codex/hooks/stop_check.py` prints wrap-up reminders when code/config changes may need tests, docs, or UI verification.
+
+## Verify Instruction Loading
+
+From the repository root:
+
+```bash
+codex --ask-for-approval never "Summarize the active project instructions."
+```
+
+Expected: Codex should mention `AGENTS.md`, hackathon prize fit, event-ledger architecture, `uv` commands, docs rules, and the Codex co-author trailer.
+
+## Trust Project Config
+
+Codex loads `.codex/config.toml` and project-local hooks only after the project is trusted. If the hook does not appear, trust the repository in Codex and restart the session.
+
+Review hooks with:
+
+```text
+/hooks
+```
+
+## Recommended Codex Workflow
+
+1. Ask Codex to inspect relevant files before editing.
+2. Make narrow changes that preserve the deterministic no-key path.
+3. Update docs/ADRs/journal entries when public behavior or architecture changes.
+4. Run:
+
+   ```bash
+   uv run pytest tests/ -q
+   uv run ruff check .
+   ```
+
+5. Commit only when asked, with:
+
+   ```text
+   Co-authored-by: Codex <codex@openai.com>
+   ```
+
+## What Belongs In User Config Instead
+
+Keep these out of the repo-scoped config:
+
+- Model/provider/auth settings.
+- Telemetry endpoints.
+- Personal notification commands.
+- Broad command auto-approval rules.
+- Machine-specific writable roots.
+