# Codex Project Instructions

## Project intent
- Keep this repository a stable, local-first Claude Code monitoring platform.
- Maintain correctness across hooks, API, DB, websocket, UI, and MCP integration.

## Priorities
- Correctness over cleverness.
- Small, scoped, reversible diffs.
- Preserve existing behavior unless change is requested.
- Update docs whenever workflow or architecture changes — follow `skills/update-project-docs/` automatically at the end of every change-set (README + VN/CN/KO mirrors, ARCHITECTURE, wiki + i18n + cache bump, server/client READMEs, docs/*).
- Every applicable source file you create or update (`.js/.ts/.tsx/.cjs/.mjs/.py/.sh/.css`) must start with the authorship header: a truthful file overview plus the exact line `@author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>`. See `skills/file-headers/` and `.claude/rules/file-headers.md`; verify with `bash skills/file-headers/scripts/check-headers.sh`.

## Declare your lane stage as you work

This repository is watched by CCAM, its own dashboard. A **lane** is keyed by
working directory, and the pipeline map only moves forward when the agent doing
the work declares its stage:

```bash
ccam stage <stage> --tool codex --evidence "<what is actually done>"
```

- Call it at every real transition — starting to plan, starting to implement,
  running tests, opening the PR — not once at the end.
- Stage names, `default` template: `intake → plan → implement → tests → review
  → gate → ship → done` (the 16-node `ship-feature` template accepts these as
  aliases too; `ccam stage` warns on stderr and names the valid nodes if a stage
  matches none).
- **`--tool codex` matters.** One directory can back both a `claude` lane and a
  `codex` lane, and without a tool the command fails rather than guess (it names
  both candidates). Inside a pane the dashboard started you need nothing — that
  pane carries `CCAM_LANE_ID`, which outranks everything but `--lane`.
- If `ccam stage` reports that no lane owns the directory, this checkout was
  never adopted: skip the stage calls and carry on. Stage reporting is
  reporting, never control flow — a failed `ccam stage` never justifies skipping
  a step of the actual work.

The dashboard also *infers* your stage from your tool calls (it reads Codex's
own rollout journals — see `docs/LANES.md#stage-detection`), but an inference
only paints a dashed amber badge. It never counts as evidence and never renders
a node green. Only your own declaration does.

If you go a while without declaring while that inference has clearly moved
past your last declared stage, the dashboard may type a one-line `[ccam]`
reminder straight into this pane asking you to run `ccam stage`. That is the
dashboard, not the user — treat it as the same instruction as this section and
just make the real call.

## Where to work
- `server/` for API/routes/data processing.
- `client/` for React UI behavior.
- `mcp/` for local MCP server tooling.
- `scripts/` for hook/install/import/cleanup utilities.

## Validation expectations
- Backend changes: run `npm run test:server` when possible.
- Frontend changes: run `npm run test:client` when possible.
- MCP changes: run `npm run mcp:typecheck` and `npm run mcp:build`.
- If any check is skipped, report it explicitly.

## Safety expectations
- Keep destructive capabilities behind explicit configuration gates.
- Never broaden destructive behavior without explicit user request.
- Treat hook execution path as fail-safe and non-blocking.

## Useful commands
- Setup: `npm run setup`
- Dev: `npm run dev`
- Build/start: `npm run build` then `npm start`
- MCP helpers: `npm run mcp:install`, `npm run mcp:build`, `npm run mcp:start`