# Global Codex Configuration

## Tool Preferences

### Search And Navigation
- Always use `rg` over `grep` for code search.
- Prefer narrow searches over broad sweeps.
- Use precise file globs and code-aware navigation when available.
- Prefer MCP tools when they provide better precision than shell commands.

### Code Manipulation
- Read the relevant code before editing.
- Prefer structural understanding over blind text replacement.
- Make the smallest change that solves the problem.
- Do not rewrite surrounding code without a concrete reason.

### Verification
- Every change needs verification.
- Verification can be tests, a build, a targeted command, or frontend validation with Playwright.
- For non-trivial work, state the verification method before implementing.

## Language Patterns

### Python
- Prefer `black` or `ruff format` for formatting.
- Prefer `ruff` for linting.
- Use type hints on public code.
- Prefer `pytest`.
- Check for `.venv/` or `venv/` before assuming interpreter paths.

### Go
- Use `gofmt`.
- Prefer `go vet` for linting and `go test ./...` for verification.
- Check `go.mod` for module structure.
- Do not ignore errors with `_` unless there is a defensible reason.

### TypeScript
- Prefer `prettier` and `eslint` when present.
- Check `package.json` for the repo's actual test and build commands.
- Check `tsconfig.json` before changing compiler-sensitive code.
- Prefer strict typing patterns.

## Workflow Principles

### Research First
Before changing unfamiliar code:
1. Identify the relevant files and relationships.
2. Understand the local pattern in that area.
3. Check for similar implementations elsewhere.
4. Look for tests that define expected behavior.

### Plan Before Implement
For non-trivial work:
1. State what is changing and why.
2. Name the files or components likely to change.
3. Define how the change will be verified.
4. Note obvious risks or breakpoints.

### Preserve Context
- Keep findings compressed and structured.
- Reuse existing project artifacts like `.claude/progress.md`, `PITFALLS.md`, and project `CLAUDE.md` when they exist.
- If a repo already uses `.claude/` planning or checkpoint files, continue to respect them rather than inventing a second system.

## Session Workflow

### Starting A Session
1. Check for `.claude/progress.md` and load it as prior context when present.
2. Read `PITFALLS.md` if present.
3. Read project instructions from `AGENTS.md`. Codex is also configured to treat project `CLAUDE.md` as a fallback instruction file.

### During Work
- Research unfamiliar areas before editing.
- Make plans for non-trivial work.
- Review changes before commit when risk is non-trivial.

### Ending A Session
- If the repo uses `.claude/progress.md`, update it when useful.
- If there are uncommitted changes, leave the next session enough context to resume cleanly.

## Shell
- Use zsh-compatible syntax when writing shell commands or scripts.
- Assume `~/.zshrc` can affect shell behavior.

## Anti-Patterns
- Do not search broadly and read dozens of files without narrowing scope.
- Do not change code before understanding the local pattern.
- Do not skip verification.
- Do not rewrite code that does not need to change.
- Do not add comments, docstrings, or annotations to untouched code without a clear reason.

## System Knowledge Journal (Obsidian)

Maintain a running journal of **host/environment** changes in the Obsidian vault at `Tech/Infrastructure/`, using the shared `sysjournal` helper (on PATH). This is for *system administration*, NOT ordinary work inside a code repo.

**Trigger — the task changes the machine/environment, not just repo code:** system config; services/daemons (systemd/launchd/cron); networking/DNS/VPN/firewall; VMs & host-level containers; drivers/kernel/boot; disks/mounts; build toolchains & global/system package installs; or **wiring an app into the host** (a systemd unit, cron job, opened port, service account).

**Do NOT journal** feature work, bug fixes, refactors, or tests *inside* a project repo. Discriminator: *does it change state outside the repo, on the host?* If no → skip. **Straddle case** (you build an app **and** install it as a service): journal only the **host-wiring** part (the unit/cron/port), not the app code.

1. **Recall first.** Before diagnosing or acting on such a task, search the journal and read relevant hits:
   `sysjournal search <keywords>`   (e.g. `sysjournal search systemd relay port`)
2. **Journal after.** Once the change is made or the problem resolved:
   `sysjournal new "Short Descriptive Title" --type change --status deployed --tags systemd,relay`
   Then fill in the created note (its path is printed): **Why**, **What changed**, **Design decisions / gotchas**, **Verify** (command + observed result), **Status / follow-ups**. Link related notes with `[[wikilinks]]`.

Keep it a real record — what changed, why, the gotcha you hit, how you verified. `sysjournal help` for the frontmatter schema (the `System Log MOC.md` Dataview index depends on it).