astrolabe/CLAUDE.md

Claude Context — Astrolabe

See @AGENTS.md for project overview, architecture rules, and the AI developer protocol.

Documentation Index

• SOUL.md — project philosophy and identity. Read first.
• docs/spec/ — authoritative behavioral specification (sections 00–10): the what. This is the contract; implement to it.
• docs/architecture/ — architecture playbook (00–10): the how (state, persistence, modals, routing, rendering, inference, relationships, vega-editor techniques, visual design, interaction & feedback). Self-contained — no external repo needed. Companion: visual-specimen.html — token sandbox + reusable-primitive catalog (open in a browser).
• /council — the design council: consult external interaction/content/a11y canon (Carbon, GOV.UK, WAI-ARIA APG, Nielsen Norman, cloned under reference/) before a user-facing decision. It advises; our contract (architecture 09/10) decides. Resolutions are recorded back into the contract.
• /eng-council — the engineering council: evidence-grounded review of codebase structure, consistency, altitude, and subtraction (what to delete). Sweep / refactor-review / new-work-review / pre-build-consult modes; recurring findings become docs/architecture/ rules and /alignment checks.
• docs/IMPLEMENTATION-PLAN.md — incremental milestone plan (M0–M6), MVP boundary, per-milestone tests + manual checks, and an architecture reference index.
• docs/manual-verification.md — standing QA checklist for what tests can't cover (offline/install, keyboard/a11y, theming, reduced-motion).
• AGENTS.md — onboarding, stack, directory map, scripts, conventions.

Quick Orientation

• Astrolabe is a spec-driven rebuild — the behavior is fixed in docs/spec/; the architecture is adapted from Syto. Implement to the spec; don't port legacy code.
• src/core/ is portable and tested hardest. Browser specifics live in src/app/infrastructure/. UI is React + Zustand.
• Editor is Monaco, charts render via vega-embed, storage is IndexedDB.
• Work milestone by milestone (see the plan): core-first, then UI, then tests, then a manual smoke check against the spec's acceptance points.

Conventions

• No git actions unless explicitly invited.
• Run npm run typecheck and npm test after changes.
• Single-line commit subjects; no Co-Authored-By trailers.