fullkomnun · March 24, 2026 22:00 · Mar 24, 2026 · Mar 24, 2026
diff --git a/CODEX-CLI-GUIDE.md b/CODEX-CLI-GUIDE.md
@@ -298,7 +298,7 @@ Recommended setup:
 ```bash
 cp .env.example .env
 npm ci --ignore-scripts
-npm install -g @sealance-io/dokojs@1.0.1 --ignore-scripts
+npm install -g @sealance-io/dokojs@1.0.4 --ignore-scripts
 ```
 
 Node notes:

diff --git a/CODEX-CLI-GUIDE.md b/CODEX-CLI-GUIDE.md
@@ -0,0 +1,568 @@
+# Codex CLI Guide for `compliant-transfer-aleo`
+
+Slack-ready onboarding guide for a teammate on Apple Silicon macOS who has ChatGPT Plus and wants to use Codex CLI well in this repository.
+
+## What this is
+
+- This guide assumes Apple Silicon Mac.
+- This guide assumes a ChatGPT Plus subscription.
+- This guide assumes little or no prior Codex CLI or terminal-agent experience.
+- This guide assumes you want to review, design, plan, implement, and debug work in this repo.
+- This repo is already prepared with agent context.
+- Root `AGENTS.md` exists and is auto-loaded by Codex when you start in the repo.
+- The linked docs are useful, but not auto-loaded unless you ask Codex to read them.
+
+## Important current note
+
+- As of 2026-03-24, the latest public Codex CLI GitHub release is `0.116.0`, released on 2026-03-19.
+- Codex CLI supports ChatGPT sign-in. For a ChatGPT Plus user, that is the recommended path for interactive local use.
+
+## 5-minute install and first run
+
+### 1. Install Codex CLI
+
+Recommended on macOS if you already use Homebrew:
+
+```bash
+brew install --cask codex
+codex --version
+```
+
+If you prefer npm:
+
+```bash
+npm install -g @openai/codex
+codex --version
+```
+
+### 2. Sign in the right way
+
+Run:
+
+```bash
+codex
+```
+
+Then choose:
+
+- `Sign in with ChatGPT`
+
+Why:
+
+- That uses your ChatGPT subscription access
+- Fast-mode features rely on ChatGPT sign-in
+- It is the default CLI login path when no valid session exists
+
+If your ChatGPT account uses email/password, set up MFA first. If you use Apple/Google/Microsoft login, manage MFA with that provider.
+
+### 3. Prefer macOS Keychain for cached auth
+
+Create or edit `~/.codex/config.toml`:
+
+```toml
+cli_auth_credentials_store = "keyring"
+```
+
+That keeps credentials in the macOS credential store instead of a plaintext auth file when possible.
+
+### 4. Open this repo and verify Codex sees the repo instructions
+
+```bash
+cd /path/to/repo/compliant-transfer-aleo
+codex
+```
+
+First prompt to send:
+
+```text
+Summarize the instruction sources you loaded for this repository, then list which additional docs I should explicitly ask you to read for Leo work and for test work.
+```
+
+Expected result:
+
+- Codex should mention the root `AGENTS.md`.
+- It should point you to docs like `docs/DEVELOPMENT.md`.
+- It should point you to docs like `docs/TESTING.md`.
+- It should point you to docs like `docs/LEO-ALEO-PATTERNS.md`.
+- It should point you to docs like `docs/CODE-PATTERNS.md`.
+
+## Best one-time quickstart for `/review` with GPT-5.4 and high reasoning
+
+If you want a single command without setting up config first:
+
+```bash
+codex \
+  -C /path/to/repo/compliant-transfer-aleo \
+  -m gpt-5.4 \
+  -a on-request \
+  -s read-only \
+  -c 'model_reasoning_effort="high"' \
+  -c 'plan_mode_reasoning_effort="high"' \
+  -c 'review_model="gpt-5.4"' \
+  -c 'service_tier="fast"'
+```
+
+Then inside Codex:
+
+```text
+/status
+```
+
+Check that you are in:
+
+- model `gpt-5.4`
+- reasoning effort `high`
+- sandbox `read-only`
+- approval policy `on-request`
+
+Then send:
+
+```text
+Read AGENTS.md, docs/LEO-ALEO-PATTERNS.md, docs/CODE-PATTERNS.md, and docs/TESTING.md. After that, review this repository's current working tree for correctness, security, Leo/Aleo execution-model mistakes, authorization-order mistakes, private/public visibility leaks, Merkle/freeze-list inconsistencies, and missing tests. Findings first with file references.
+```
+
+Then:
+
+```text
+/review
+```
+
+Notes:
+
+- `/review` uses the current session model unless `review_model` is configured
+- `/review` is ideal for uncommitted changes, a commit, or a PR-style review against a base branch
+- `/diff` is the fastest follow-up when you want to inspect exact changed files
+
+## Recommended personal config
+
+Put this in `~/.codex/config.toml`.
+
+```toml
+model = "gpt-5.4"
+review_model = "gpt-5.4"
+model_reasoning_effort = "high"
+plan_mode_reasoning_effort = "high"
+model_reasoning_summary = "concise"
+model_verbosity = "medium"
+personality = "pragmatic"
+approval_policy = "on-request"
+sandbox_mode = "read-only"
+service_tier = "fast"
+cli_auth_credentials_store = "keyring"
+
+[profiles.review]
+model = "gpt-5.4"
+review_model = "gpt-5.4"
+model_reasoning_effort = "high"
+plan_mode_reasoning_effort = "high"
+model_reasoning_summary = "concise"
+model_verbosity = "medium"
+approval_policy = "on-request"
+sandbox_mode = "read-only"
+service_tier = "fast"
+personality = "pragmatic"
+
+[profiles.edit]
+model = "gpt-5.4"
+review_model = "gpt-5.4"
+model_reasoning_effort = "high"
+plan_mode_reasoning_effort = "high"
+model_reasoning_summary = "concise"
+model_verbosity = "medium"
+approval_policy = "on-request"
+sandbox_mode = "workspace-write"
+service_tier = "fast"
+personality = "pragmatic"
+
+[sandbox_workspace_write]
+network_access = false
+writable_roots = []
+```
+
+Why this is a good starting point:
+
+- `review` profile is safe for reading and reviewing
+- `edit` profile allows normal implementation work but still asks before risky commands
+- `gpt-5.4` with `high` reasoning is a good default for complex code review, debugging, and design
+- `service_tier = "fast"` is useful for interactive work if your ChatGPT sign-in supports it
+
+If `fast` is not available in your workspace, switch that line to:
+
+```toml
+service_tier = "flex"
+```
+
+## Daily start commands
+
+### Review mode
+
+```bash
+cd /path/to/repo/compliant-transfer-aleo
+codex --profile review
+```
+
+### Edit / implement mode
+
+```bash
+cd /path/to/repo/compliant-transfer-aleo
+codex --profile edit
+```
+
+### One-off non-interactive run
+
+```bash
+codex exec \
+  --profile review \
+  --cd /path/to/repo/compliant-transfer-aleo \
+  "Read AGENTS.md, docs/LEO-ALEO-PATTERNS.md, docs/CODE-PATTERNS.md, and docs/TESTING.md. Review the current working tree and output findings only."
+```
+
+### Resume the last non-interactive session
+
+```bash
+codex exec resume --last
+```
+
+## The commands and slash commands you will actually use
+
+### Terminal commands
+
+```bash
+codex --profile review
+codex --profile edit
+codex --version
+codex login
+codex logout
+codex features list
+codex exec "your prompt here"
+codex exec resume --last
+```
+
+Useful flags:
+
+- `-C` or `--cd`: start Codex in a specific directory
+- `-m` or `--model`: override the model for one run
+- `-p` or `--profile`: use a named config profile
+- `-a` or `--ask-for-approval`: `untrusted`, `on-request`, or `never`
+- `-s` or `--sandbox`: `read-only`, `workspace-write`, or `danger-full-access`
+- `-c` or `--config`: one-off config override
+- `--search`: enable live web search for that run
+- `--json`: machine-readable output for automation
+- `-o` or `--output-last-message`: write the final answer to a file
+
+### Slash commands
+
+These are the ones worth memorizing:
+
+- `/status`
+- `/debug-config`
+- `/model`
+- `/fast`
+- `/plan`
+- `/review`
+- `/diff`
+- `/mention`
+- `/new`
+- `/resume`
+- `/fork`
+- `/mcp`
+
+What they are for:
+
+- `/status`: confirm model, approvals, writable roots, token usage
+- `/debug-config`: see which config layer is winning
+- `/model`: switch models in-session
+- `/fast`: toggle fast mode for the thread
+- `/plan`: force planning before coding
+- `/review`: run a focused code review
+- `/diff`: inspect Git diff
+- `/mention`: explicitly attach a file into the current conversation
+- `/resume`: reopen a saved chat
+- `/fork`: branch the current conversation into an alternative path
+- `/mcp`: list connected MCP tools
+
+## Repository bootstrap for actual work
+
+If you want Codex to compile or test changes in this repo, make sure the repo itself is prepared first.
+
+### Required local setup
+
+Use the repo root only:
+
+```bash
+cd /path/to/repo/compliant-transfer-aleo
+```
+
+Recommended setup:
+
+```bash
+cp .env.example .env
+npm ci --ignore-scripts
+npm install -g @sealance-io/dokojs@1.0.1 --ignore-scripts
+```
+
+Node notes:
+
+- Repo requirement: Node `20.19.0+` on the 20.x line, or `22.12.0+`
+- Repo default in `.nvmrc`: `v24`
+
+Critical repo rules:
+
+- Always install from repo root
+- Never run `npm install` inside a workspace subdirectory
+- Keep `--ignore-scripts` on npm installs in this repo
+- Integration tests must run sequentially
+
+### Build and test commands Codex should use here
+
+```bash
+dokojs compile
+npm test
+DEVNET=true npm test
+npm run test:agent
+npm run test:select ./test/merkle_tree.test.ts
+npm run test:select:agent ./test/merkle_tree.test.ts
+npm run build --workspace=@sealance-io/policy-engine-aleo
+npm run format:fix
+```
+
+Important repo-specific test behavior:
+
+- Default and recommended mode is `devnode`
+- `DEVNET=true` is slower and should be used only when needed
+- Prefer the `agent` reporter for Vitest when possible
+- Tests share chain state, so they must not be parallelized
+
+If tests fail to pull images:
+
+```bash
+docker login ghcr.io
+```
+
+If port `3030` is already taken:
+
+```bash
+docker stop $(docker ps -q --filter ancestor=ghcr.io/sealance-io/leo-lang)
+```
+
+## How to prompt Codex well in this repo
+
+OpenAI’s own guidance is a strong default:
+
+- State the goal
+- Give the relevant context
+- State constraints
+- Define what “done” means
+
+In this repo, the biggest mistake is assuming Codex will automatically read every linked architecture/testing doc. It will not. Tell it what to read.
+
+### Good default prompt shape
+
+```text
+Goal: <what you want>
+Context: Read AGENTS.md and <specific docs/files>.
+Constraints: Follow repo rules, keep changes minimal, preserve existing patterns, and call out assumptions.
+Done when: <tests/review output/behavioral proof>.
+```
+
+## Copy-paste prompt templates
+
+### 1. Review current changes
+
+```text
+Read AGENTS.md, docs/LEO-ALEO-PATTERNS.md, docs/CODE-PATTERNS.md, and docs/TESTING.md. Then review the current working tree. Prioritize correctness, security, behavioral regressions, Leo async transition/finalize mistakes, authorization-order issues, public/private visibility leaks, Merkle and freeze-list mismatches, and missing tests. Findings first with file references.
+```
+
+### 2. Review a Leo feature design before coding
+
+```text
+Use /plan. Read AGENTS.md, docs/ARCHITECTURE.md, docs/LEO-ALEO-PATTERNS.md, docs/CODE-PATTERNS.md, and the relevant files under programs/ and test/. Propose the safest implementation plan for <feature>. Include affected programs, async transition/finalize changes, SDK parity implications, required tests, deployment implications, and open questions. Do not edit yet.
+```
+
+### 3. Implement a Leo feature
+
+```text
+Read AGENTS.md, docs/DEVELOPMENT.md, docs/TESTING.md, docs/LEO-ALEO-PATTERNS.md, and docs/CODE-PATTERNS.md. Implement <feature> with the smallest safe change. Preserve repository patterns. Update or add tests. Run dokojs compile and the narrowest relevant tests first, then summarize residual risks.
+```
+
+### 4. Debug a failing test
+
+```text
+Read AGENTS.md, docs/TESTING.md, docs/CODE-PATTERNS.md, and docs/LEO-ALEO-PATTERNS.md. Reproduce the failure in <test file or command>, explain the root cause, fix it, add a regression test if needed, and rerun only the narrowest relevant commands before broadening scope.
+```
+
+### 5. Review or implement SDK parity work
+
+```text
+Read AGENTS.md, packages/policy-engine-sdk/AGENTS.md, packages/policy-engine-sdk/README.md, docs/LEO-ALEO-PATTERNS.md, and the relevant Leo program. Compare the SDK's off-chain hashing, Merkle proof generation, constants, and encoding against the on-chain logic. Call out or fix any parity mismatches and add tests.
+```
+
+### 6. Ask Codex to interview you before planning
+
+```text
+Before proposing a design, interview me. Ask the minimum set of concrete questions needed to remove ambiguity around constraints, Leo visibility rules, authorization flow, test expectations, and deployment impact. Then switch to /plan and propose the implementation plan.
+```
+
+## Repo-specific best practices for Leo work
+
+When the task touches `programs/**/*.leo`, ask Codex to explicitly check:
+
+- Async transitions vs async functions
+- That mappings are written only in async functions
+- That only public values or commitments cross public async boundaries
+- Authorization order for token-registry style flows.
+- Check that `prehook` happens before transfer.
+- Check that the `prehook` future is awaited before the transfer future.
+- Public/private visibility decisions
+- Freeze-list invariants.
+- Check `ZERO_ADDRESS` sentinel usage.
+- Check index mappings.
+- Check root updates.
+- Check previous root window rules.
+- Block height window checks in threshold-style policy flows
+- Upgradability and multisig assumptions when relevant
+
+Good habit:
+
+- Ask Codex to inspect both the Leo program and the nearest tests before proposing changes
+
+## Repo-specific best practices for tests
+
+When the task touches behavior, ask Codex to:
+
+- Start with the narrowest test file
+- Prefer `devnode` first
+- Use `agent` reporter where possible
+- Avoid full `DEVNET=true` runs unless needed
+- Keep tests sequential
+- Add regression coverage for every bug fix that changed behavior
+
+Good review prompt for tests:
+
+```text
+Read AGENTS.md, docs/TESTING.md, docs/CODE-PATTERNS.md, and the affected tests. Review whether coverage is missing for negative cases, authorization failures, private/public boundary cases, Merkle proof edge cases, initialization requirements, and block-height timing windows.
+```
+
+## Suggested workflow by task type
+
+### For review
+
+1. Start `codex --profile review`
+2. Run `/status`
+3. Ask Codex to read the relevant repo docs
+4. Run `/review`
+5. Use `/diff` for changed files
+6. If findings are interesting, `/fork` the session to explore fixes without losing the original review
+
+### For design / planning
+
+1. Start `codex --profile review`
+2. Use `/plan`
+3. Point Codex to the exact docs and files
+4. Make it list risks, assumptions, affected tests, and rollout impact
+5. Only switch to `edit` profile after the plan looks correct
+
+### For implementation
+
+1. Start `codex --profile edit`
+2. Ask it to read the relevant docs first
+3. Ask for the smallest safe change
+4. Require compile and narrow test verification
+5. End with `/review`
+
+### For bug fixing
+
+1. Reproduce with the smallest test or command
+2. Ask Codex to explain root cause before broad changes
+3. Fix the bug
+4. Add a regression test
+5. Re-run the narrow test
+6. Review the diff
+
+## Anti-patterns to avoid
+
+- Do not start Codex outside the repo and expect it to pick up repo instructions
+- Do not assume linked docs are loaded automatically
+- Do not ask it to run the whole suite first when a single test file can reproduce the issue
+- Do not ask it to parallelize integration tests in this repo
+- Do not jump into `danger-full-access` unless you truly need it
+- Do not use API-key auth for normal interactive local work if you already have ChatGPT Plus
+- Do not ask for vague output like "take a look"; ask for findings, plan, or implementation with explicit done criteria
+
+## Minimal cheat sheet
+
+### Install / update
+
+```bash
+brew install --cask codex
+brew upgrade codex
+```
+
+Or:
+
+```bash
+npm install -g @openai/codex
+npm update -g @openai/codex
+```
+
+### Start sessions
+
+```bash
+codex --profile review
+codex --profile edit
+```
+
+### One-off overrides
+
+```bash
+codex --profile review -m gpt-5.4 -c 'model_reasoning_effort="high"'
+codex --profile edit -s workspace-write -a on-request
+```
+
+### Useful repo commands
+
+```bash
+dokojs compile
+npm test
+npm run test:agent
+npm run test:select:agent ./test/merkle_tree.test.ts
+npm run format:fix
+```
+
+### Useful slash commands
+
+```text
+/status
+/model
+/fast
+/plan
+/review
+/diff
+/mention
+/resume
+/fork
+/debug-config
+```
+
+## Official sources
+
+- Codex CLI GitHub repo and install instructions: https://github.com/openai/codex
+- Latest release: https://github.com/openai/codex/releases/latest
+- Codex authentication: https://developers.openai.com/codex/auth
+- Codex CLI command reference: https://developers.openai.com/codex/cli/reference
+- Codex CLI slash commands: https://developers.openai.com/codex/cli/slash-commands
+- Codex config basics: https://developers.openai.com/codex/config-basic
+- Codex config reference: https://developers.openai.com/codex/config-reference
+- Codex sample config: https://developers.openai.com/codex/config-sample
+- Codex best practices: https://developers.openai.com/codex/learn/best-practices
+- GPT-5.4 model docs: https://developers.openai.com/api/docs/models/gpt-5.4
+
+## Repo docs to explicitly ask Codex to read
+
+- `AGENTS.md`
+- `docs/DEVELOPMENT.md`
+- `docs/TESTING.md`
+- `docs/LEO-ALEO-PATTERNS.md`
+- `docs/CODE-PATTERNS.md`
+- `packages/policy-engine-sdk/AGENTS.md`
+- `packages/policy-engine-sdk/README.md`
No results found