Sentinel Trading Platform — Claude Code

Read AGENTS.md first, then docs/ai/working-agreement.md. This file adds Claude Code-specific context for the Sentinel repo and should stay thin.

Claude Role

Prefer Claude for repo understanding, root-cause analysis, architecture discussion, and final review.
For implementation, keep scope narrow and follow the branch/worktree rules in docs/ai/working-agreement.md.
If a task touches shared contracts, migrations, auth, or deployment config, stop and restate the risk before editing.

Health polling: useServiceHealth hook in AppShell polls engine + agents every 15s, writes to Zustand
Engine auth: All client-side engine calls must use engineUrl() / engineHeaders() from lib/engine-fetch.ts
Settings page has no API key form — keys are configured via .env only
The EngineClient class in lib/engine-client.ts is the server-side SDK (used by agents app); pages use engine-fetch.ts

Reusable project skills live in .claude/skills/. Check for an existing Sentinel skill before inventing a new workflow.
Permissions live in .claude/settings.json. Keep permissions narrow and project-specific.

PostToolUse hook: After any file edit, a fast check scans for high-risk path touches and warns to run pnpm validate:changed. This is a warning, not a blocker.
Stop hook: At session end, validate:changed runs automatically to surface any unvalidated changes before handoff.
contract-guardian subagent (.claude/agents/contract-guardian.md): Invoke this subagent before proposing edits that touch shared types, proxy code, auth utilities, or migrations. It enumerates consumers and flags rollback risk.

Invoke contract-guardian explicitly: Use the contract-guardian subagent to review this change.

See docs/ai/commands.md for the full matrix. Most common:

pnpm lint
pnpm test
pnpm test:engine

See docs/ai/architecture.md for the repo map. Key detail: Python version is 3.12+.

See docs/ai/commands.md. Copy .env.example to .env and fill in credentials before running live flows.