bread CLAUDE.md

CLAUDE.md — start here

Onboarding + operating rules for any AI (or human) joining this repo. Read this first, then the docs it points to. Keep it accurate: if you change how the project works, update this file too.

What this is

A no-build, server-rendered hypermedia stack and the things built on it. One direction of dependency — each layer builds only on the layers below it:

batch/   BATCH — the substrate (Bun · Addressable · TypeScript · CSS · htmx); no build step
  └─ grain/   GRAIN — an AI-interaction design system + its default theme (the look) + the catalog
       ├─ MILL/               the markdown CMS (LIVE — renders /notes + the layer docs; its OWN reusable project)
       ├─ proof/              PROOF — the AI plan board, a mountable layer (plans-as-markdown → kanban)
       ├─ pantry/             PANTRY — the installable dev-docs + AI cockpit app (`bunx pantry`)
       ├─ tjakoen.github.io/  THE personal-site app + the composition root
       └─ project/            the product — a personal AI assistant; **PAUSED**, docs-only archive

The composition root folded into tjakoen.github.io/ (2026-07-05): the portfolio is now THE app — it wires batch + grain + mill and runs the site; the hero desk is the reference surface where you watch the AI act. The portfolio uses MILL for its markdown content; MILL does not build it. Dependency purity: grain imports nothing from batch except the OpChannel port; MILL depends on both, never the reverse — a new layer above both, not an extension of either.

The defining idea: a UI where every surface is addressable and operable by both a human and an AI through one shared vocabulary, with the AI's presence shown as a visible signal (grain = AI). A human click and an AI decision become the same Intent, flow through one door (POST /intent → grain/ai/interaction-layer.ts), and return as RenderOps pushed over SSE. No privileged AI→DOM back channel.

Fuller detail on each layer, and the paused-project history, is in DOCS.md — the full doc map.