@nimtech/nimpress 2.3.1

package/.claude/rules/changelog-entries.md

@@ -0,0 +1,229 @@
+# Authoring changelog entries
+
+Rules for writing release notes when the site uses `type: changelog`.
+
+## One file per release
+
+Every release is its own markdown file. Reviewing a release is a single file PR. Combining releases in one file is a rule violation.
+
+## How files collapse into one page
+
+Every entry file declares `title: Changelog` (or whatever the collection's display name is) and `type: changelog`. Files sit in one folder. The plugin groups by `(parent folder, title)` and produces one collection page mounted at that folder's path. Each file is one entry on the page.
+
+The filename is arbitrary. Use the version (`v1.4.2.md`) so the file tree reads as a release log.
+
+## Required frontmatter
+
+```yaml
+---
+title: Changelog
+type: changelog
+data:
+  version: 1.4.2
+  release_date: 2026-06-08
+  title: Booking calendars
+  description: Booking calendars become a first class resource.
+---
+```
+
+1. Top level `title` is the page title and the grouping key. Every entry file in the same folder uses the exact same string.
+
+2. `type: changelog` is required for the plugin to group the file.
+
+3. `data.version` is required. Newest version sorts first. Parsed as dot delimited numeric segments. Optional leading `v` is allowed.
+
+4. `data.release_date` is required. An RFC 3339 timestamp. Date only (`2026-06-08`) is accepted and interpreted as midnight UTC. Full timestamps (`2026-06-08T09:00:00Z`) are accepted. The renderer formats it as `DD.MM.YYYY` next to the entry title. Invalid values fail the build.
+
+5. `data.title` is the per release name. Hard limits:
+
+5.1. **Max 48 characters.** Builds fail above the limit.
+
+5.2. **No commas.** A comma means the title is trying to list more than one shipped thing — split it into two releases or move the rest to the body.
+
+5.3. **No code identifiers.** No backticks, no method names, no path segments, no query parameters, no field names, no SQL identifiers, no Go symbols, no `:`-prefixed param placeholders. If the only way to name the release is with an identifier, the title is wrong — pick the user-visible capability instead.
+
+5.4. **Sentence case, one phrase.** Examples to write: `Booking calendars`, `Organization settings`, `Conflict clarity`. Examples to reject: `Setting joins claimius, with-set hydration on the audit and relation endpoints, and an actor naming sweep`, `` `with=access` everywhere ``, `POST /api/calendar shipped`.
+
+6. `data.description` is one short sentence that frames the release for a reader scanning the changelog. Hard limits:
+
+6.1. **Max 160 characters.** Builds fail above the limit.
+
+6.2. **One sentence.** Period only at the end.
+
+6.3. **No code identifiers.** No backticks, no method names, no paths, no query parameters, no function names, no struct names, no SQL identifiers. The description is the introduction, not the implementation summary.
+
+6.4. **No detail enumeration.** Skip `routes through`, `hydrates`, `is renamed to`, multi-clause `and …, and …` constructions. Frame the why or the user-facing effect.
+
+6.5. Plain text only, markdown is not rendered.
+
+## Linking to a roadmap issue
+
+`data.issue` on a changelog entry declares an explicit link to a roadmap issue file by relative path. The plugin resolves the path against the changelog file. `data.status` reports the effect of this release on the issue: a number `0..100` for partial progress, or the literal word `completes` (also `completed`, `complete`, `closes`, `fixes`, `resolves`) to flip the issue to `shipped`.
+
+```yaml
+data:
+  version: 1.5.0
+  release_date: 2026-06-10
+  title: Organization settings
+  description: Plain text sentence.
+  issue: ../roadmap/organization-settings
+  status: completes
+```
+
+1. Use the issue path with or without the trailing `.md`.
+
+2. `data.status` as a number sets the rocket position; the highest number across all linked releases for the same issue wins.
+
+3. `data.status: completes` flips the issue to `shipped` and parks the rocket at this point.
+
+4. The release drops a marker on the roadmap spine at the changelog's `release_date`. Clicking the marker navigates back to the changelog entry.
+
+## Never set these on a changelog entry
+
+1. `path` is rejected. The route is derived from the entry folder.
+
+2. Top level `description` is ignored. Put it under `data` instead.
+
+## Layout in the file tree
+
+Place every changelog file inside one directory:
+
+```
+docs/
+└── solutions/
+    └── bookable/
+        └── changelog/
+            ├── v1.4.0.md
+            ├── v1.4.1.md
+            └── v1.4.2.md
+```
+
+The collection page lives at `/solutions/bookable/changelog`. Each file shares `title: Changelog` so they merge.
+
+## Version sort
+
+Newest first. Parsed as dot delimited numeric segments. `1.10.0` ranks above `1.2.9`. Pre release suffixes are not parsed, they sort last among same base versions.
+
+## Entry body
+
+The body carries the real detail of the release. The renderer applies its own scaled down styling for headings inside an entry, so H1 through H6 are all allowed and read as compact section markers, not page chrome.
+
+1. Lead with one short paragraph that names the shipped capability.
+
+2. Group user visible changes under headings: themes, not severity. One section per shipped capability. Use the heading level that reflects nesting depth.
+
+3. Heading text is a short friendly readable label. Never an identifier, method, path, query parameter, or backticked token. Examples to write: `Creator hydration`, `Booking calendars`, `Conflict clarity`. Examples to avoid: `` `with=creator` on every endpoint ``, `POST /api/calendar`, `inherit on POST endpoints removed`.
+
+4. Under each heading, write one prose paragraph that frames the change in human terms. Move every identifier, route, query parameter, status code, schema name, and token into that prose (or the code blocks beneath it), inside backticks. Identifiers belong in the body, not in the heading.
+
+5. Inside each section, use a bulleted or short prose list. One change per item, one sentence per item, with identifiers wrapped in backticks.
+
+6. Use fenced code blocks for HTTP exchanges, YAML, JSON, and request or response bodies. Inline `code` spans carry the identifiers inside prose.
+
+7. Link to the relevant PR or issue when the change references work outside the docs.
+
+## Markdown shapes that are encouraged
+
+The body is rendered as full GitHub flavored markdown. Reach for whichever shape makes the change scan fastest, not just prose paragraphs.
+
+1. Bulleted lists for two or more sibling changes under one theme.
+
+2. Tables when the section is a list of `(thing, effect)` pairs, `(field, default value)` pairs, `(endpoint, status)` pairs, or any other rows that share the same columns. A table reads faster than five bullets that repeat the same sentence shape. Wrap identifiers in backticks inside cells.
+
+3. Fenced code blocks for HTTP exchanges, request bodies, response bodies, YAML, JSON, and SQL snippets. Tag the language so the docs panel highlights.
+
+4. Block quotes for a one line callout when a section needs to interrupt the flow with a warning or a note (use sparingly).
+
+5. Nested lists when a single change has two or three steps that the consumer runs in order; a flat bulleted list is the default and the nested shape is the exception.
+
+A section that compares before and after, names defaults per field, or lists endpoints with their new status code is almost always clearer as a table than as a stack of bullets.
+
+## Linking from a changelog entry
+
+A release that introduces a new example, a new concept page, or a new API endpoint links to the canonical doc page from inside the entry body. The reader scanning the changelog jumps straight to the deeper doc.
+
+1. New example walkthrough — link to `/solutions/<product>/examples/<slug>` from inside the prose of the section that ships the example.
+
+2. New concept page — link to `/solutions/<product>/concepts/<slug>` from the section that explains the new concept.
+
+3. New API endpoint — link to the docs panel anchor for that endpoint when one exists; otherwise link to the section in the relevant concept page that names the endpoint.
+
+4. Roadmap issue — set `data.issue` on the frontmatter (see above). Do not also paste the link in the body.
+
+5. Use markdown link syntax `[label](path)`. Relative paths are resolved against the changelog file; site root paths starting at `/solutions/` also work and read more obviously.
+
+6. Link text is the human label of the target, not the path. `the Admin booking management example` reads; `/solutions/bookable/examples/admin_booking_management` does not.
+
+7. Link once per target inside a single entry. A second mention in the same entry stays as plain text.
+
+## What to include
+
+1. User visible behavior changes.
+
+2. Breaking changes, called out explicitly. Bold the word `breaking` so the reader cannot miss it.
+
+3. New configuration fields, with the value to set.
+
+4. Removed features, with the migration path.
+
+## What not to include
+
+1. Internal refactors with no user visible effect.
+
+2. Dependency bumps that do not change behavior.
+
+3. Documentation only changes.
+
+4. Anything already obvious from the version number.
+
+5. Repository file paths, directory layouts, code-base file names, or any reference to where code lives in the source tree. The changelog is read by API consumers, not by repo contributors. Anything that names `internal/`, `cmd/`, `openapi_definition/`, `<op_id>_*.yml`, or a path under the repo is a rule violation. The API path (`/api/...`) is fine; the file path is not.
+
+6. Wording that names the same fact from two angles ("absent from the running surface and absent from the spec", "removed from the code and the spec", "dropped from both X and Y"). State the user-facing fact once. The reader does not see the spec and the running handlers as two separate things — only the API.
+
+7. Restating what the version number already conveys. A line that says "this release ships v1.5.1" carries no information.
+
+## How to phrase changes for the reader
+
+The reader is an API consumer planning their next integration step. They do not run the database, they do not know the trigger or migration names, and they have never seen the table that backs a resource. Frame every change in the words the consumer would use when describing it to a teammate.
+
+1. Lead with what the consumer can now do, or what they no longer need to do.
+
+2. Skip database and infrastructure terms. Words like `seed`, `seeded`, `row`, `trigger`, `materialized`, `backfill`, `cascade table`, `enqueued`, `dispatcher`, `pool` belong to the implementation. Reach for `prefilled with the default values`, `record`, `behind the scenes`, `applied to every existing organization at the release`.
+
+3. Skip naming internal subsystems. The reader does not know which Go package or SQL function owns the change. Talk about the API surface and the resulting behavior.
+
+4. Skip implementation rationale unless the consumer needs it to integrate. The reader does not need to know that a function moved or that two write paths merged into one; they need to know which endpoint to call.
+
+5. Match the tone of a release note that a product team sends to integrators: short, clear, friendly, anchored on what the consumer sees in their own client.
+
+A sentence that names an internal column, a function name, or a migration number is a sign the section is written for a contributor, not a consumer. Rewrite it in the consumer's words.
+
+## How to phrase removals
+
+A removal lands in one of three buckets. Pick the bucket; the wording follows.
+
+1. Breaking removal of a public capability — keep the heading short, name the capability, write a short paragraph that names what the consumer must change to keep working, and bold the word `breaking`.
+
+2. Gated capability that is held back from public exposure — say it is held back and why ("held back until end-to-end testing finishes"), do not say "removed". A held-back capability is coming back; calling it removed is misleading.
+
+3. Capability the consumer never saw (debug, internal, deprecated-from-day-one) — do not write a line at all. It does not belong in the changelog.
+
+## How to phrase examples and error responses
+
+The reader cares that the docs Try-It and the response panels show meaningful bodies, not that some example file lives at a repo path.
+
+1. Write what the reader sees in the docs: "Every endpoint shows a real captured response body for `200`, `400` and `403` in the docs panel" — not "examples live under `openapi_definition/examples/...`".
+
+2. Status codes belong inside backticks. Repo paths to example files do not appear at all.
+
+3. If the change is the addition of error response bodies on the docs site, that is one line. Not three list items naming the file layout.
+
+## Rendered shape
+
+1. Page H1 reads from the top level `title` of the highest version entry, so every entry file uses the same string.
+
+2. Each entry is a row of `[version pill] [data.title] [chevron]`. Clicking the row expands the body.
+
+3. The first entry expands by default. A direct hash like `/path#v1.4.2` expands that entry and scrolls to it.
+
+4. The right rail TOC lists every version as a level 2 heading. The left sidebar adds one child entry per version under the collection page, each pointing at the hash anchor.

package/.claude/rules/chunk-cycles.md

@@ -0,0 +1,23 @@
+# Chunk cycles
+
+The workshop build code splits every story and component entry into its own chunk. When a module bundled into shared code statically imports a component that also gets its own chunk, and that component imports anything from the shared side, Rollup emits chunks that import each other. The source module graph has no cycle, dev serves modules unbundled and works, and the deployed static site throws `Uncaught ReferenceError: Cannot access 'x' before initialization` while evaluating whichever cyclic chunk loads first. One crash rejects the whole import chain, so every story loading either chunk renders nothing.
+
+## The guard
+
+Every nimpress build runs the `nimpress:chunk-cycle-guard` plugin over the emitted bundle, for the site and for each harness system. A cycle fails the build and prints each cycle as a chunk path with the source module behind every chunk. `nimpress lint` builds, so the guard runs there and in CI with no configuration.
+
+## The rule for library code
+
+1. Registries, menus, and any module shared across many components load components through dynamic imports, in vue via `defineAsyncComponent(() => import('...'))`, never through static imports.
+
+2. A component may statically import other components it renders. The cycle needs both directions: shared code importing the component and the component importing shared code. Breaking the registry side is always the fix.
+
+3. Dynamic imports defer evaluation past module init, so no cycle forms and the component chunk loads on demand.
+
+## When the guard fires
+
+1. Read the printed cycle. Each line names the emitted chunks and the source module each chunk was built from.
+
+2. Find the shared module in the cycle that statically imports a component, switch that import to a dynamic one, and rebuild.
+
+3. Never widen chunks or force chunk grouping to silence the guard; that hides the coupling instead of removing it.

package/.claude/rules/component-modules.md

@@ -0,0 +1,152 @@
+# Component modules
+
+The component workshop surface in nimpress. One system per component library, one page per component, stories as executable files beside the page. This rule is the contract for authoring and for the pipeline.
+
+## Config
+
+The `modules` array in the nimpress config declares systems:
+
+```ts
+modules: [
+  {
+    name: 'nimtech',
+    framework: 'vue',
+    source: './src/components',
+    package: '@nimling/components-nimtech',
+    port: 6161,
+    css: ['./src/assets/style.css'],
+    harness: './docs/components/harness.vue'
+  }
+]
+```
+
+1. `framework` is `vue` or `svelte`. One framework per system.
+
+2. `source` is the component source root for local mode. `package` is the released npm package for package mode. Source wins when the component resolves; package is the fallback.
+
+3. `css` entries load inside the harness iframe. Point them at the token and theme sheets the components need.
+
+4. The harness mounts the component bare. Everything a library needs around its components is declared, never discovered: `setup` points at a module bootstrapping the app, its default export carries `install(app)` run on every created app before mount and `companion`, a component rendered beside every story; a svelte system exports a function run once. Overlay roots, plugin installs, and providers all come through `setup` or the harness.
+
+4.1. `harness` points at the system harness component wrapping every story, a `.ts`, `.tsx`, `.vue`, or `.svelte` path. There is no filename discovery; a harness exists only where the config or a story declares it.
+
+4.2. The frame is a composition of harness primitives imported from `@nimtech/nimpress/harness/vue` or `@nimtech/nimpress/harness/svelte`. `ComponentHarness` is the root, `ComponentStory` is the mount point where nimpress renders the component under test, `ComponentHarnessEffects` wraps its children and applies the toolbar drop shadow, `ComponentHarnessOverlay` mounts the system overlay root. The default composition is `ComponentHarness` wrapping `ComponentHarnessEffects` around `ComponentStory` with `ComponentHarnessOverlay` beside it, and it runs when a system declares no harness.
+
+4.3. A custom harness imports the primitives and arranges them freely, wrapping `ComponentStory` in a layout, adding providers, reordering, or omitting a piece. nimpress feeds the component, its props, slots, and overlay into the tree, so `ComponentStory` always resolves it. The checkerboard background, zoom, and vision filters are workshop chrome around the iframe, not harness primitives, and stay on the toolbar.
+
+5. `port` pins the harness dev server. Pin distinct ports when several repos run side by side.
+
+6. Consumer `vite` config flows into the harness, so aliases like `@` work inside components and stories.
+
+7. `visibility: dev-only` keeps a system in `nimpress dev` and out of the built bundle.
+
+8. Sizing is never configured here. The frame centers whatever the story mounts, so a component that needs a width owns it in the harness component or in a wrapping div in the story's own render.
+
+## The component page
+
+1. A folder under `docs/components/<Group>/<Component>/` holds exactly one md file with `type: component`; the build refuses a second one. The folder becomes the sidebar parent, the page appears inside it under its title, stories follow as siblings.
+
+2. Frontmatter contract: `title`, `type: component`, `data.system`, `data.component`, optional `data.package`, optional `data.file` when the source layout deviates from `<Component>/<Component>.<ext>`.
+
+2.1. The overview body opens with the `## Usage` import statement, then prose describing the component, what it is for, its behaviors, its slots and events. Import and create scaffold the usage section; the description is authored by hand and is expected on every component. The live preview frame renders below the body automatically, followed by the CLAUDE.md section; neither is written in the markdown.
+
+3. Grouping is physical or declared: the group folder above the component folder groups by location, and a top level `sidebar` frontmatter block groups by declaration without changing the folder or the URL. A declared group sits at the outer level, sibling to the physical group folders, standing in for the page's parent folder in the sidebar.
+
+3.1. The `sidebar` block: required `name` as the verbatim group label, optional `icon` for an ascii icon before the label, optional `style` for inline css on the group row, optional `path` overriding the group route. Latest definition among members wins. A `name` matching the page's own parent folder decorates that physical group instead. On a folder `index.md` the block decorates the folder's own sidebar entry rather than nesting a group.
+
+4. A CLAUDE.md in the component source folder renders on the page and is editable in local dev only.
+
+## Stories
+
+1. A story is a `.story.tsx` file beside the component page, so html sits directly in the render; `.story.ts` also loads. Import `vueStory` or `svelteStory` from `@nimtech/nimpress/story` and default export the definition.
+
+2. Name resolution order: `// story: <name>` comment frontmatter, then the `name` field, then the file name with underscores read as spaces, so `With_Controls.story.ts` names the story `With Controls`.
+
+2.1. A story decorates its own sidebar row with an optional `sidebar` object, `sidebar: { name, icon, style }`, the same shape as the frontmatter `sidebar` block. `name` overrides the row label, `icon` is an ascii glyph rendered before it, `style` is inline css on the row. The story link stays keyed on the resolved story name, so only the label changes, never the url.
+
+2.2. Story `name`, `props`, `slots`, and `sidebar` are read by parsing the story file as text, never by executing the module, so their values must be inline literals. An imported or computed value does not resolve; a `props` or `sidebar` that references an import comes through empty. A story that needs an imported value, a raw html or css file loaded with `?raw`, uses `render`, which runs in the browser where imports resolve.
+
+3. A value story carries `props` and optional `slots`; the workshop controls seed from it and drive the component live over the iframe channel with base64 encoded props in the url.
+
+4. An executable story carries `render`, a function returning a mount definition. Vue: an options object with `components`, `setup`, `template`. The harness runs it verbatim; controls do not apply. A story is self contained: it imports the component and holds its own fixture data inline. There is no shared story fixture folder.
+
+4.1. A value story nests itself in a per story harness with the `harness` field: `vueStory({ harness: BlockEditorHarness, props })`. The harness is a component that renders `<slot />` where `ComponentStory` mounts, and it folds inside the system harness as `SystemHarness > StoryHarness > ComponentStory`. A render story includes the shared harness component directly in its own markup instead and owns its sizing there, `<div style="width: 210mm">` around the harness when the story needs a width. Shared setup that a family of stories needs, a wrapping editor, providers, or seeded context, lives in one harness component the stories import from their group folder, a `harness.vue` beside the group's pages.
+
+5. Props and controls are one structure loaded from the schema file beside `index.md`, `schema.json` or `schema.yml`, one of the two. The schema is the read path: the workshop controls, validation, and mock selection all come from it. Object schemas resolve into nested member controls, arrays into row editors, enums into selects. Story `props` are plain data destructured into that tree; a story never defines controls. The schema carries `properties`, `required`, `slots`, `emits`, and a `mock` name per member.
+
+6. The schema is seeded from the component types by import and create, and from there the file is authored: defaults, enums, descriptions, mocks, and narrowing live in the schema, not in the component. `nimpress modules update [component]` upserts source changes into it: new props, slots, and emits are added, a changed type shape refreshes on existing members, authored fields are never overwritten, an empty description fills from a JSDoc or line comment above the type member, and a member gone from the source stays in the file and is flagged so the author decides its removal.
+
+6.1. In `nimpress dev` the upsert runs automatically whenever a component under a page changes, and every pass warns about what the author should fix: props without a description, opaque types, and schema members without a source counterpart. The warnings coach the library toward fully documented and typed components.
+
+6.2. In local dev the json dialog carries a set defaults action that writes the current live control values into the schema file as the prop defaults, so defaults are found by testing in the workshop and persisted where they belong.
+
+7. A `data.schema` block in the page frontmatter carries the same schema structure inline and merges over the schema file as the page local last word, for small curations that do not warrant the file.
+
+8. The page `title` is the human readable display name; `data.component` is the technical identifier the harness resolves. They may differ freely.
+
+## Controls and kinds
+
+1. Control kinds derive from the schema: `text`, `number`, `boolean`, `select` from enums, `object` with nested member rows, `array` with item rows, `record` with key value entries, `function` for callable props, `json` only for opaque leaves. Enum options render as chips in the control info; a long option list collapses to one line that expands in a hover popup.
+
+2. The schema to control walk expands nested members to a depth of 12, held in `SCHEMA_CONTROL_MAX_DEPTH` in `src/modules/parse/typeMembers.ts`. That covers an array of groups holding lanes holding entries holding a style block holding colors, the deepest real component tree. A member past the bound becomes a `json` leaf and the opaque warning names it, so a warning on a member that carries `properties` or `items` is the bound speaking, not the schema.
+
+3. Function props and events hold real code: the workshop stores `{ __nimpressFn: "<source>" }` values edited in a CodeMirror editor, the harness compiles the source with the Function constructor and runs it on every call, firings counting on the event row and printing in the console panel. The default mock stub logs its arguments.
+
+4. Every event renders as its own control row under the events header: the handler source sits in an always visible code editor spanning the row, mock resets it to the logging stub, clear detaches the event, a chevron hides the editor per row. A story starts with logging stubs attached to all events. A default button at the events header resets every handler to the logging stub at once.
+
+5. Mock resolves from the schema through the `@nimtech/nimpress/mock` named exports: the `mock` name stored per member picks the function, `mockEmail`, `mockParagraph`, `mockInt`, `mockOption`, `mockEvent`, and the rest, all star wars flavored. Reclicking regenerates via a seed, and option picks exclude values already present so a reclick lands on a fresh option. Per row mock fills one prop; the panel header mock fills everything empty including handlers.
+
+6. Control values persist to localStorage per system, component, and story. Clear per row or clear all from the panel header; the panel header also carries default, resetting every control to its schema default and every slot to its declared default. Once the workshop has pushed props to the frame, the pushed set alone drives the component and story props and required defaults no longer fill in underneath, so a cleared prop renders truly empty. The json dialog in the panel head shows the live values as one editable json object plus the schema, with copy and populated counts.
+
+## The workshop layout
+
+1. The shell is the martin special: absolute inset zero root, `overflow: hidden` everywhere structural, one unconditional grid, top bar row then sidebar and page columns, the document never scrolls, scrolling lives only inside panels, the sidebar, and the component's own frame.
+
+2. The workshop grid has a bottom slot and a right slot that collapse to zero when empty. The props panel and the frame console panel each toggle from the toolbar and dock to either slot; sharing a slot splits it. Drag areas are unstyled divs straddling the panel borders.
+
+3. The console panel streams the iframe's own console, every level plus window errors and unhandled rejections, forwarded over the message bridge, filterable and clearable. An input at the bottom evaluates js inside the frame console style, enter runs, arrows walk the history, input and result echo as `>` and `<` entries.
+
+4. The harness iframe document is locked, `#host` is absolute inset zero with `overflow: auto`; a natural sized component centers on the checkered background, an oversized one scrolls inside the frame, and one set to full width and height fills the frame exactly at any zoom.
+
+5. The toolbar shadow toggle drops a shadow on the component inside the frame and an inset shadow on the frame itself, tuned per frame theme so both read on light and dark.
+
+## Embedding a component in any page
+
+The `:::component` directive renders a live component inline in any markdown page through the same harness:
+
+```markdown
+:::component {"component":"MarButton","props":{"label":"Save"},"height":"12em"}
+:::
+```
+
+1. `component` alone suffices when one system is configured; `system` names it otherwise. `story` selects a story file by its base name, `props` and `slots` travel base64 encoded, `height` sizes the frame.
+
+2. `:::component MarButton` is the shorthand for the default story with default controls.
+
+## CLI
+
+Every modules subcommand takes `--system=<name>`; it is required only when several systems are configured.
+
+1. `nimpress modules import` walks the system source, mines storybook CSF files for groups from meta titles, named stories with args, argTypes merged into the seeded schema, and render stories ported executable, then fills storyless components with generated default stories. A mined story whose name equals the component becomes the Default story, written as `default.story.tsx` with the name `Default`. A data module a render story imports copies in beside the story so the component folder stays self contained. Flags: `--source=`, `--stories=<extra csf dir>`, `--match=<component name regex>`, `--select` for interactive picking. Reimports upsert the schema and never clear authored content.
+
+2. `nimpress modules import <file> --name=` registers one external component file into the system.
+
+3. `nimpress modules story [component] [--framework=]` writes `default.story.tsx` named `Default` for every storyless component page, one uniform entry story per component.
+
+4. `nimpress modules create <Component>` scaffolds the dedicated component folder: Overview `index.md`, `default.story.tsx`, and the seeded `schema.json`.
+
+5. `nimpress modules update [component] [--system=]` upserts the schema for one component page, or every page of a system when no component is named. The ref is the component name when unique across systems, else the component file path; `create --component=<ref> --schema` runs the same upsert for one page. This is the refresh loop after changing component types, since the workshop reads the schema, not the source.
+
+6. `nimpress modules lint [--system=]` checks framework purity of stories and component files, that every page carries at least one story, exactly one schema file present and parseable beside every `index.md`, value story props against the schema, and the schema structurally against the component source: every source member exists in the schema, schema members without a source counterpart are flagged, an authored type conflicting with the source type fails, and an authored enum must fit the source type and stay inside a source union. Authored narrowing, an enum over a string, is legal. Harness and render stories are exempt from the prop check. Coaching warnings for undocumented props and opaque types print without failing the run. Run it after touching stories, schemas, or component types.
+
+7. `nimpress lint` validates structure, folder and file naming, file combinations, frontmatter, and every import in content code files, then builds to verify the output compiles. The import pipeline lives in the nimpress CLI; a consumer repo carries no generator or import scripts.
+
+8. Import and create seed the schema beside `index.md` when none exists. Opaque prop types log warnings naming the component, prop path, and type; fix them by authoring the member in the schema with enum or properties, or by documenting the type in the component file or a sibling `.types.ts` and running update.
+
+8.1. `unknown` is never the fix for an opaque member. Neither the source type nor an authored `tsType` is widened to `unknown` to silence the warning; the member gets its real shape, an enum, properties, typed items, or a real interface in the source. A prop that only exists to hold untyped data is removed instead.
+
+9. `nimpress modules dev [--system=]` runs harness servers. `nimpress dev` starts them all beside the docs.
+
+10. `nimpress modules build [--system=]` emits static harness bundles into `dist/_components/<system>/`; `nimpress build` runs it for every system whose visibility is not `dev-only`.
+
+11. `nimpress export [--target=] [--out=]` collects pages marked with the `export:` frontmatter header into `.nimpress` for the docs-sync pipeline, rewriting component pages to package mode. The `docs-export` action is the pipeline twin; see the docs-sync rule.

package/.claude/rules/dbml-pages.md

@@ -0,0 +1,118 @@
+# DBML diagrams
+
+The database diagram surface in nimpress. One DBML source, one interactive entity relationship diagram, either inline in a page or as a page of its own.
+
+## The pieces
+
+1. `@dbml/core` parses the DBML at build time inside the plugin. The browser never sees DBML, only the diagram model.
+
+2. `@xyflow/svelte` renders the model as a canvas of nodes and edges, lazily imported by `DBMLBlock` together with the node components.
+
+3. `DbmlTable.svelte` and `DbmlNote.svelte` are the node components. Every table card, column row, flag, and sticky note is nimpress markup styled from `tokens.css`, so the diagram follows the site theme.
+
+4. `src/dbml/erd.ts` is the converter. Every mapping decision from DBML to the diagram, including the table positions and which side of a table an edge leaves from, lives there and nowhere else.
+
+## Inline fence
+
+A ` ```dbml ` fence renders inline in any page that hydrates markdown: `doc`, `changelog`, and `roadmap`.
+
+````md
+```dbml
+Table users {
+  id uuid [pk]
+  email varchar(255) [not null, unique]
+}
+```
+````
+
+1. The info line takes an optional JSON object. `height` is the only field, `520px` by default. Pick it from the table count: the reader pans by dragging whatever the tables do not cover, so a cramped frame has nothing to grab.
+
+2. The plugin rewrites the fence to `<div class="np-dbml" data-schema="…">` carrying the base64 diagram model, and the page mounts `DBMLBlock` over it.
+
+3. An inline diagram mounts behind a click to explore shield so the frame never captures page scrolling. Clicking it activates the frame and swaps the shield for a gesture hint. `DbmlPage` passes `activateOnMount` because there the diagram is the page.
+
+## Page type
+
+`type: dbml` turns one `.dbml` file into a full page viewer.
+
+```yaml
+---
+title: Bookable schema
+type: dbml
+spec: ./bookable.dbml
+description: Every table the booking api reads and writes.
+data:
+  eyebrow: Database
+  lead: Rooms, desks, and bookings.
+  download: Download the schema
+  fullscreen: Open fullscreen
+---
+```
+
+1. `spec` is required and resolves relative to the markdown file. Lint fails when it is missing or does not resolve.
+
+2. The page opens with a hero band. Title, description, `data.eyebrow`, `data.lead`, `data.logo`, `data.banner`, and `data.align` shape it, and the markdown body renders under them. Every one of those sits in the same centered content column as a doc page, so only the diagram is full width.
+
+3. The band carries the page buttons. `data.download` labels the button handing over the `.dbml` source, `data.fullscreen` labels the button opening the diagram fullscreen, and `false` on either removes that button. `data.actions` adds links, each with `text`, `link`, and a `variant` of `primary`, `secondary`, or `ghost`.
+
+4. The page has no right rail. The diagram runs edge to edge under the band with no padding, no margin, and no rounded corners, and fills the viewport below the site header. `data.height` overrides that height.
+
+5. The `.dbml` file lands in the build output beside the page, so readers can open the source.
+
+## The interaction contract
+
+Pan by dragging empty canvas or by the minimap. Zoom with the scroll wheel, with the control buttons, or by the minimap. Drag a table to move it, which is a view only rearrangement and is never written back to the `.dbml` file.
+
+Click a column carrying a link or a foreign key to follow it. A foreign key column centers the table it points at and selects it. A markdown link in the column note overrides that: a target naming a table centers that table, and any other target is a page link, navigating for a site path, opening a new tab for a full url, and scrolling for a `#anchor`.
+
+The starting layout comes from `src/dbml/erd.ts`, which positions the tables at build time and separates any two cards that would touch. Cards never overlap on first paint. A schema that still reads badly is fixed there or in the source order, not by asking readers to drag.
+
+Scroll zoom is armed only once the frame is active, so an inline diagram never captures page scrolling before the reader clicks it.
+
+## What the converter maps
+
+1. Tables, columns, data types, defaults, and notes.
+
+2. Primary keys, composite primary keys from an `indexes` block marked `pk`, unique columns, not null columns, and auto increment.
+
+3. Refs as relationship lines drawn between the two columns themselves, entering the side of each table that faces the other. The endpoint with cardinality `1` is the parent; a one to one ref takes the right hand side as the parent. A to many line carries an arrow head at the child end.
+
+4. Named and unique indexes.
+
+5. `headercolor` as the table header color.
+
+6. Standalone `Note` blocks as sticky notes placed to the right of the tables.
+
+7. Schema qualified table names when the schema is not `public`.
+
+8. A markdown link inside a column note as the column's click target, its label as a pill on the row, and the remaining note text as the hover title.
+
+## Authoring the source
+
+1. One `.dbml` file per page. Do not split a schema across files and stitch it in the markdown.
+
+2. Write a `Note` on every table. It renders as a second line inside the table header, so a schema with notes reads without hovering anything.
+
+3. Write column notes too. A column note becomes the hover title on that row.
+
+3.1. Draw a `jsonb` payload as a table of its own and link the column at it from the column note, `[booking_answers](booking_answers)`. The payload table carries a `Note` saying it has no table of its own in the database.
+
+4. Name every index. An unnamed index renders under a generated label in the table footer.
+
+5. Set `headercolor` on a table to group it visually. Tables without one take the brand color.
+
+## What is wrong if you see it
+
+1. DBML parsed in the browser. Parsing is a build time step; the page payload carries the diagram model.
+
+2. A component importing `@xyflow/svelte` from shared code, or `DbmlTable.svelte` and `DbmlNote.svelte` imported statically. All three are lazy imports inside `DBMLBlock`, see the chunk cycles rule.
+
+3. Mapping or layout logic added to `DBMLBlock` or a page renderer. It belongs in `src/dbml/erd.ts`.
+
+3.1. Colors written into the node components as literals. The cards read `tokens.css` so light and dark both work.
+
+4. A `type: dbml` page with a long markdown body. Move the prose to a sibling `doc` page and link to it.
+
+4.1. A `type: dbml` page whose header text runs the full window width. The band is centered in the content column; only the diagram is full width.
+
+5. A schema pasted into a fenced ` ```sql ` block as a stand in for a diagram.

package/.claude/rules/deploy.md

@@ -0,0 +1,47 @@
+# Deploy
+
+The release pipeline for `@nimtech/nimpress`. Run from the repo root.
+
+## Steps in order
+
+1. `just build` to compile the library into `dist/`. Fail the deploy if the build fails.
+
+2. `just check` to run `svelte-check` and `tsc`. Fail the deploy if type checks fail.
+
+3. Stage and commit every changed file with a single sentence summarizing the release. Conventional commits are not required, the wording should describe the user visible change.
+
+4. `git push` to `origin/main`.
+
+5. `just deploy` to invoke `sbump` which bumps the patch version, writes the tag, and pushes both.
+
+## What the tag triggers
+
+1. `Generate and publish nimpress` builds the library, runs the tests, and publishes the package to npm under the `@nimtech` scope. It is public, so a consumer installs it with no registry configuration and no token.
+
+2. `Release nimpress actions` validates the Go actions and moves the major tag onto the release.
+
+3. `Publish the docs site` builds `docs/` with the freshly built library and deploys it to GitHub Pages at `nimling.github.io/nimpress`. The site build writes into `dist/site` so it never clears the library output, and the `base` field in `nimpress.config.json` is what makes the project page path resolve.
+
+A release that changes a user visible surface carries its changelog entry in `docs/changelog/` in the same commit, one file per release. The entry contract is in `changelog-entries.md`.
+
+## Variants
+
+1. Minor release: replace step 5 with `just deploy-minor`.
+
+2. Major release: replace step 5 with `just deploy-major`.
+
+## Never
+
+1. Never run `just deploy` without a clean build and clean type check first. A broken release is harder to roll back than to prevent.
+
+2. Never push directly to a published version. `sbump` increments the version. Manual edits to `package.json` `version` are not how this repo ships.
+
+3. Never bypass GPG signing or pre commit hooks. If the hook fails, fix the issue and retry.
+
+4. Never deploy with uncommitted changes in the working tree. `sbump` writes a commit, the tree must already be at the state you want to ship.
+
+5. Never run `pnpm publish` directly. The `just deploy` flow is the only sanctioned path.
+
+## When the user says "deploy"
+
+The `deploy` skill in `.claude/skills/deploy.md` lays out the exact commands. Execute it end to end, stopping only if a step fails. Surface errors verbatim, do not paper over them.