# Codex Workflow

This project is split across the core runner and sibling module repositories. Codex works best when all active repositories are writable from the start and routine checks use targeted commands.

## Personal Codex Config

Put machine-specific access in `~/.codex/config.toml`, not in a tracked project file:

```toml
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
personality = "pragmatic"

sandbox_mode = "workspace-write"
approval_policy = "on-request"
approvals_reviewer = "user"

[sandbox_workspace_write]
writable_roots = [
  "/mnt/DATA/git",
]
network_access = false

[projects."/mnt/DATA/git/govoplan-core"]
trust_level = "trusted"

[projects."/mnt/DATA/git/govoplan-access"]
trust_level = "trusted"

[projects."/mnt/DATA/git/govoplan-organizations"]
trust_level = "trusted"

[projects."/mnt/DATA/git/govoplan-identity"]
trust_level = "trusted"

[projects."/mnt/DATA/git/govoplan-mail"]
trust_level = "trusted"

[projects."/mnt/DATA/git/govoplan-files"]
trust_level = "trusted"

[projects."/mnt/DATA/git/govoplan-campaign"]
trust_level = "trusted"
```

The broad writable root reduces approval churn. The explicit project trust entries allow project-local `AGENTS.md` guidance to load for each repository.

## Repository Guidance

Each active repository has an `AGENTS.md` file. These files define ownership, module boundaries, and focused commands for Codex. Keep durable project conventions there instead of repeating them in every prompt.

Documentation is part of the completion criteria for every behavior change. The
owning module must update its manifest-driven `DocumentationTopic` contributions
for affected user and administrator workflows, settings, permissions,
limitations, and operational consequences. Feature documentation remains in the
feature module; the optional `govoplan-docs` module projects those contributions
without importing feature internals. Every module manifest must retain a static
user and administrator baseline even when runtime providers add configured-state
details.

Use `~/.codex/config.toml` for personal defaults, auth/runtime settings, writable roots, and trust decisions. Avoid checking in absolute-path writable roots or model preferences unless they are intentionally team-wide.

Use Gitea issues as the canonical backlog and state log. See `docs/GITEA_ISSUES.md` for label setup, TODO import, and Codex issue update commands. Durable docs should describe stable behavior; changing work state belongs on the issue.

## Focused Verification

Use the consolidated script after changes that touch module discovery, optional integrations, shared mail components, mailbox listing, or cross-module WebUI behavior:

```bash
cd /mnt/DATA/git/govoplan
tools/checks/check-focused.sh
```

For smaller changes, prefer the narrow command named in the relevant `AGENTS.md` file. Examples:

```bash
cd /mnt/DATA/git/govoplan-core
/mnt/DATA/git/govoplan/.venv/bin/python -m unittest tests.test_module_system

cd /mnt/DATA/git/govoplan-mail
/mnt/DATA/git/govoplan/.venv/bin/python -m unittest discover -s tests

cd /mnt/DATA/git/govoplan-core/webui
PATH=/mnt/DATA/git/govoplan-core/webui/node_modules/.bin:/home/zemion/.nvm/versions/node/v22.22.3/bin:$PATH /home/zemion/.nvm/versions/node/v22.22.3/bin/npm run test:module-permutations
```

## Usage Discipline

- Prefer `rg`, `sed`, and targeted test commands.
- Avoid broad recursive scans and full builds unless the change warrants them.
- Keep generated build/test folders ignored.
- Keep optional module behavior behind core registry/capability/module metadata boundaries.
- Run `tools/checks/check-manifest-shapes.py` after module behavior or manifest changes so user/admin documentation coverage remains complete.
- Create or update Gitea issues for TODOs, follow-ups, blockers, and feature requests instead of keeping local backlog files.
- Do not start persistent dev servers unless the user asks.
