# Review guide

Read by Devin Review and any reviewer. `AGENTS.md`, `mcpjam-inspector/AGENTS.md`
and `DESIGN.md` hold the full rules; this file lists what to check on every PR.

## Block the PR

- **Hardcoded colors.** A literal hex, `rgb()` or `oklch()` value in a component
  or stylesheet. Colors come from role tokens in
  `design-system/src/tokens.css`. The only allowed exception is chat-ui's
  `--trace-waterfall-*` palette.
- **Hand-edited generated regions.** DESIGN.md's YAML front matter, the fenced
  token blocks in `docs/style.css` and `chat-ui/src/styles.css`, and the color
  fields in `docs/docs.json` are generated by `npm run design:sync`.
- **Stale browserd bundle.** A change under
  `mcpjam-inspector/server/services/browserd/daemon/`, or anything it imports
  (`protocol.ts`, the WebMCP launch flags), without matching changes in
  `server/services/browserd/dist/`.
- **Raw `console.*` in `server/` or `bin/start.js`.** Server code uses
  `logger` from `@/utils/logger`; route catch sites use `reportRouteFailure`
  from `server/utils/route-error-report.ts`, not `logger.error`.
- **New `logger.warn` that should be an error, or `logger.error` for an
  expected condition.** `logger.error` pages Sentry; warnings do not.
- **Behavior change without a test.** Tests live in `__tests__/` next to the
  source.

## Look closely

- Auth, sessions and tokens: `server/routes/workos-authkit.ts`,
  `server/services/authkit-jwt.ts`, `server/services/guest-token*.ts`,
  `server/services/api-keys-relay.ts`, `server/middleware/`. Check who can
  reach the route, what is logged, and that secrets never reach telemetry.
- Anything that writes access links or tokens to output. Access links are
  terminal-only.
- Releasable packages (`sdk/`, `cli/`, `evaluators/`, `vitest/`,
  `mcpjam-inspector/`, `chat-ui/`, `widget-react/`) need a changeset
  (`npx changeset`) for user-visible changes.
- UI changes should use primitives from `@mcpjam/design-system/*` rather than
  re-implementing them.

## Skip

- `package-lock.json` unless dependencies changed.
- `server/services/browserd/dist/` beyond confirming it changed alongside the
  daemon source.