coding: Instructions file for Claude Code

CLAUDE.md - Coding Project Guidelines

Mandatory Rules

• PlantUML: Use plantuml CLI command. NEVER java -jar plantuml.jar
• TypeScript: Mandatory with strict type checking
• API design: Never modify working APIs for TypeScript compliance; fix types instead
• Visual UI verification — use gsd-browser: For visual smoke/screenshot/click-through against localhost:3002/3032/8080 or any local web UI, use the gsd-browser CLI (navigate, screenshot, click, eval, select-frame, snapshot) — wraps Playwright with the correct chromium resolution, avoids ERR_MODULE_NOT_FOUND from inline chromium.launch() scripts. /playwright-cli is an allowed entry point but a hand-rolled node /tmp/foo.mjs Playwright script still violates prefer-gsd-browser. Structured E2E tests go under tests/e2e/<area>/<spec>.spec.ts, run via npx playwright test.
• gsd-browser MUST NOT drive the user's own Chrome bundle — ~/.gsd-browser/config.toml pins [browser] path to Playwright's "Google Chrome for Testing" (bundle id com.google.chrome.for.testing) via the ~/.gsd-browser/chromium.app symlink. Apple Events are addressed by BUNDLE ID, so two live instances of com.google.Chrome are indistinguishable to AppleScript and the automation one answers FIRST: every tell application "Google Chrome" on the machine silently retargets into the headless profile. That is what broke the status-line click handler — it found a dashboard tab, navigated it and reported reused idx=9 active=9 against a browser nobody could see, for hours, with no error anywhere. It also defeats its own verification, since asking AppleScript what happened asks the wrong browser too; only a screenshot from the user caught it. The daemon leaks (daemon stop reports success and stops nothing), so one screenshot run shadows every AppleScript on the machine until the next reboot. Config keys follow the env names (GSD_BROWSER_BROWSER_PATH → [browser] path); browser_path is silently IGNORED. The symlink must point at the .app, never the binary inside it — Chrome resolves ../Frameworks from argv[0]'s directory and dies with a dlopen error otherwise. Playwright deletes old revisions on upgrade, so re-point it if gsd-browser stops launching: ln -sfn ~/Library/Caches/ms-playwright/chromium-*/chrome-mac-arm64/"Google Chrome for Testing.app" ~/.gsd-browser/chromium.app. install.sh applies this pin on macOS only — Linux and Windows have no Apple Event routing, so two Chrome instances there cannot intercept one another and reusing a system Chrome is correct. bin/statusline-click is likewise per-platform: macOS gets AppleScript tab reuse, Linux xdg-open/gio open, WSL wslview/cmd.exe start, Windows start. Reuse is macOS-only (no scripting bridge elsewhere) — a new tab is the honest ceiling. Every branch ends in a launched browser or a message in the pane, and the handler ALWAYS exits 0, because tmux renders a failing run-shell as a view the user must dismiss.
• gsd-browser has TWO failure modes and they look nothing alike. (a) Daemon won't start / receiver is gone — stale runner lock: pkill -9 -f "chromiumoxide-runner" then rm -f /private/var/folders/*/*/T/chromiumoxide-runner/Singleton*. That glob legitimately matches NOTHING on some machines, and "no matches found" is not evidence the daemon is healthy. (b) Daemon alive, its Chrome gone — commands time out after ~30 s with request failed while the daemon PID was still alive: timeout reading response from daemon, and NO Chrome process survives (ps aux | grep -c "[C]hrome for Testing" → 0). A lid-close sleep causes it: both wedges of 2026-10-24 followed one, and SIGKILLing only the Chrome reproduces it. Since then bin/gsd-browser (the shim) heals it itself: on that timeout, when the DevTools port in ~/.gsd-browser/session.json does not answer, it resets both halves and retries once (a slow page whose browser still answers is left alone). Only if the shim's heal fails, clear the lock in the browser PROFILE by hand: pkill -9 -f "Chrome for Testing"; rm -f ~/.gsd-browser/browser-profile/Singleton* ~/.gsd-browser/daemon.pid ~/.gsd-browser/daemon.sock; gsd-browser daemon start. (c) Daemon alive, its socket dead — cannot connect to daemon socket: Connection refused: a second daemon (e.g. an installer's verify step) rebound ~/.gsd-browser/daemon.sock and exited; the shim heals it like (a). Since gsd-browser 0.2.1 (open-gsd, installed by install.sh) daemon stop really stops both halves; on 0.1.24 it printed "Daemon stopped." and stopped nothing.
• Clicking a force-directed canvas: dispatch on the ELEMENT, never click --x --y. The simulation keeps moving nodes, so coordinates read by eval are stale by the time the click lands and it silently selects whichever node drifted under the point (this picked SpecstoryIntegration instead of LiveLoggingSystem twice in a row, reporting success both times). Find the g.node by label, then for (const ev of ['pointerdown','mousedown','pointerup','mouseup','click']) el.dispatchEvent(new MouseEvent(ev,{bubbles:true,cancelable:true,view:window})), and always assert afterwards on WHICH node ended up selected.
• A viewer page can take minutes to first paint under gsd-browser — /viewer/coding parses ~18MB of entities plus 18k relations and sits on "Loading coding graph…" with Showing 0 of 0 nodes the whole time. That is not the localhost-vs-127.0.0.1 hang; check gsd-browser network for whether /api/v1/entities was even issued before concluding anything. Poll with a Monitor until-loop rather than a single long eval.
• Constraint dodging is forbidden: fix the underlying issue, don't swap APIs to pattern-match around a regex (e.g. process.stderr.write to dodge no-console-log). For legitimate exceptions, include OVERRIDE_CONSTRAINT: <id> with rationale.
• km-core LLM proxy endpoint: rapid-llm-proxy serves POST /api/complete (NOT OpenAI /v1/chat/completions) on port 12435 (host) / host.docker.internal:12435 (container, pre-set as LLM_CLI_PROXY_URL). Don't confuse with port 3033 (Health API — silently 404s Cannot POST /api/complete). Body: { process, messages, complexity? }; response: { content, provider, model, tokens, latencyMs } (not OpenAI-wrapped; provider is the ACCOUNT id). URL precedence: RAPID_LLM_PROXY_URL → LLM_CLI_PROXY_URL → LLM_PROXY_URL → http://localhost:${LLM_CLI_PROXY_PORT ?? '12435'}, append /api/complete once. Canonical clients: scripts/backfill-raw-observations.mjs:40,95 (host), integrations/semantic-analysis/src/agents/llm-with-process.ts (container). taskType does nothing — only the complexity band (via bg-<process> route in llm-routing.yaml, or per-request on a from-caller route) controls cost.
• km-core reads MUST NOT write — pass readOnly on request-scoped opens: close() persists by default; persistGraph writes the WHOLE graph under one LevelDB key, so a read-only open still rewrites it on close. Fine for a one-shot CLI, fatal for a polled HTTP route (caused a 550× disk-amplification OOM-kill loop on vkb-server via /api/experiments/runs). Use openExperimentStore({ readOnly: true }) for any read-path handler. Diagnostic: one GET adding one ~1MB .ldb file, or an order-of-magnitude gap between du -sh of the LevelDB and its JSON export. Recovery: stop vkb-server, launchctl bootout the writers, move the leveldb dir aside, open+close once to let hydrate() rebuild from .data/experiments/exports/*.json.