cairn: Instructions file for Claude Code

CLAUDE.md

Guidance for agents working in this repo. AGENTS.md symlinks here, so every agent loads this file every session.

Keep this file lean. It is a map of non-obvious constraints, not an encyclopedia. Do not inline API/tool inventories, changelogs, or per-round history — link out instead. When you want to add detail, add it to docs/ARCHITECTURE.md (or the right doc below) and leave a pointer here.

What Cairn is

A self-hosted, connected, day-reading wellness OS for training / nutrition / longevity with an agentic coaching loop. It opens to a calm Brief that reads your whole picture and suggests what kind of day today should be, propagates flagged lab findings across every domain they touch (the "connected brain"), runs adaptive nutrition, learns who you are, and surfaces quiet cross-domain insights one at a time.

One Node service (src/server.ts) serves four surfaces from one process: a vanilla PWA (/), a REST API (/api/*), an MCP server (/mcp, Streamable HTTP), and a background scheduler. Storage is SQLite via Node's built-in node:sqlite.

docs/VISION.md is the constitution — calm, suggestion-not-a-gate, no-scores, pull-never-push. Read it before shaping product behavior. (Its progress log is maintained separately; don't edit it as code housekeeping.)

Commands

npm run dev      # tsx watch on src/server.ts -> http://localhost:8787 (auto-seeds on first boot)
npm run build    # typecheck client + transpile src/client -> public/js + tsc -> dist/
npm start        # node dist/server.js (run build first)
npm test         # node:test harness, sharded; pretest builds dist/
npm run migrate  # print current user_version, apply pending migrations
npm run reset    # delete data/cairn.db* and re-seed

Full deploy / migration / backup / restore playbook: docs/OPERATIONS.md. Docker image details and release flow: docs/SHARING.md.

Hard requirements

• Node 24 is the floor, Node 26 is what ships — node:sqlite is unflagged from 24; the Docker image, the release workflow and the primary CI lane run 26. No native build step.
• ESM with explicit .js import extensions (tsconfig is NodeNext). Importing a sibling .ts module is written from "./repo.js", never "./repo".
• Every string rendered into innerHTML goes through escHtml/escAttr. The only exceptions are the two SVG libraries (art.js, cairn-body-figure.js), whose output is authored geometry and never interpolates caller text.