@nimtech/nimpress 2.3.1

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

@@ -0,0 +1,93 @@
+# Authoring doc pages
+
+Rules for the default page type. Any markdown file without an explicit `type:` renders as a `doc`. Concept guides, references, tutorials, design docs, and one off retrospectives all use this type.
+
+## Default behavior
+
+1. No `type:` field. Setting `type: doc` is allowed and equivalent.
+
+2. The route is derived from the file location under `contentDir`. Override with `path:` only when the URL and the file location must differ.
+
+3. The page mounts inside the same shell as every other page: header, sidebar, content column, right rail TOC. The right rail lists H2 and H3 headings from the body.
+
+## Required frontmatter
+
+```yaml
+---
+title: How sessions work
+---
+```
+
+1. `title: string` is required. Use sentence case. This is the H1, the breadcrumb label, and the default sidebar label.
+
+## Recommended frontmatter
+
+1. `description` is a one sentence summary. Used as the meta description and the search excerpt. Add it for any page expected to land via search.
+
+2. `tags` is a comma separated string or a YAML array. The search index boosts tag matches and shows them as pills under each result. Example: `tags: api, sessions, identity`. Search treats a trailing slash like `api/` as a folder scope filter.
+
+3. `order` pins the page inside its parent sidebar group. Use sparingly. Default is alphabetical by title.
+
+4. `icon` is a short emoji or icon name rendered next to the sidebar label.
+
+5. `slug` shortens the sidebar label without renaming the file.
+
+6. `noToc: true` hides the right rail. Use only on short pages where the TOC would feel empty.
+
+7. `footer` renders a centered, muted line at the bottom of the page.
+
+8. `lastUpdated: true` shows the last commit date for the file in the footer.
+
+9. `meta` carries `description`, `canonical`, `robots`, `keywords`, `og`, `twitter`, `jsonLd` for SEO and social cards. Full reference in `frontmatter.md`.
+
+## Body conventions
+
+1. One H1 per page lives in `title`. Start the markdown body at H2.
+
+2. Use H2 to separate top level sections. H3 for sub sections. Avoid H4 unless absolutely necessary.
+
+3. Headings are sentence case.
+
+4. Numbered lists at column zero in the form `1.`, `2.`, with a blank line between entries. Sub items use `1.1.`, `1.2.` at column zero. Never indent.
+
+5. Fence every code block with its language. `bash`, `ts`, `python`, `json`, `yaml`, `http`. Aliases: `curl` renders as bash, `hurl` renders as http.
+
+6. Use `:::code-group` when showing the same example in two or more languages.
+
+7. Callouts are `:::tip`, `:::note`, `:::warning`, `:::info`, `:::check`. Three on a page is a lot.
+
+8. Definition lists for reference grids of terms with one line descriptions. See [Definition lists](https://nimling.github.io/nimpress/definition-lists).
+
+9. Mermaid blocks render `flowchart`, `stateDiagram-v2`, `sequenceDiagram`, `erDiagram` when a flow or state reads more cleanly visually.
+
+10. ` ```dbml ` blocks render an interactive entity relationship diagram. Reach for it over a mermaid `erDiagram` whenever the subject is a real database schema. See `dbml-pages.md`.
+
+## Linking
+
+1. Relative links within the same section, absolute links across sections.
+
+2. Use the page title as the link text. Avoid `click here`.
+
+3. Anchor references to current code by file path and line number when describing implementation.
+
+## Auth
+
+1. `gate` marks the page guarded. Any string works; the build's guard function maps it to a guarded bundle and the runtime checks the viewer against it. Public pages omit it.
+
+2. `visibility` controls where the page appears. `hidden` removes it from the sidebar, the search index, and the build. `dev-only` keeps it in `nimpress dev`, leaves it out of the built bundle, and marks its sidebar row with a red dot. Omit the field for a public page.
+
+## Reading direction
+
+1. The reader scrolls top to bottom. The URL hash updates as they pass headings so deep links survive sharing.
+
+2. A back to top button slides in from the bottom left after 600px of scroll, sized to clear the sidebar column.
+
+## Never
+
+1. Never write an H1 inside the body. The title already renders as the H1.
+
+2. Never set `path` to a value that conflicts with another page's `path`. The build raises an error.
+
+3. Never invent fields the schema does not declare. Add them to the schema first, in the same change.
+
+4. Never write Boolean values as quoted strings (`'true'`). Use unquoted booleans.

package/.claude/rules/docs-authoring.md

@@ -0,0 +1,90 @@
+# Authoring documentation
+
+Rules for writing markdown pages, both inside this repo's `docs/` and inside consumer sites that use Nimpress.
+
+## Voice
+
+1. Short sentences. One idea per sentence.
+
+2. Present tense. Active voice. Describe what is, not what will be.
+
+3. No marketing language. No fluff.
+
+4. Numbered lists at column zero in the form `1.`, `2.`, with a blank line between entries. Sub items use `1.1.`, `1.2.` at column zero. Never indent.
+
+5. No bullets for ordered material. No a, b, c, no roman numerals.
+
+6. No hyphens in text unless the word genuinely requires one, like `re-run` or `pre-commit`.
+
+7. No em dashes, no en dashes, no parentheses. Restructure the sentence.
+
+8. Never use the words `old`, `legacy`, `formerly`, `previously`, `used to be`, `replaces`, `renamed from`. Describe current state only.
+
+## Headings
+
+1. One H1 per page. The H1 is the rendered title, populated from frontmatter, so the markdown body starts at H2.
+
+2. Use H2 to separate top level sections. H3 for sub sections. Avoid H4 unless absolutely necessary, the right rail TOC stops showing H4 in some themes.
+
+3. Headings are sentence case. `## How it works`, not `## How It Works`.
+
+## Links
+
+1. Prefer relative links within the same section, absolute links across sections. See [Relative links](https://nimling.github.io/nimpress/relative-links).
+
+2. Use the page title as the link text. Avoid `click here`.
+
+## Code
+
+1. Fence every code block with its language. `bash`, `ts`, `python`, `json`, `yaml`, `http`. Aliases: `curl` and `sh` render as bash, `hurl` renders as http.
+
+2. Use `:::code-group` when showing the same example in two or more languages.
+
+2.1. A ` ```dbml ` fence renders as an interactive diagram, not as code. Use it for database schemas and use `sql` for statements.
+
+3. Keep code blocks short. Long examples belong in a runnable repo, linked from the docs.
+
+## Tables
+
+1. Tables for reference grids of fields, options, or commands.
+
+2. First column is the identifier, last column is the description.
+
+3. No nested markdown inside cells beyond inline code spans.
+
+## Callouts
+
+1. `:::tip` for opt in advice that improves outcomes.
+
+2. `:::note` for context the reader benefits from but can skip.
+
+3. `:::warning` for things that will go wrong if ignored.
+
+4. `:::info` for neutral background.
+
+5. `:::check` for verification steps.
+
+Use sparingly. Three callouts on a page is already a lot.
+
+## Definition lists
+
+Use for reference grids of terms with one line descriptions:
+
+```md
+term_name
+: One line description.
+```
+
+See [Definition lists](https://nimling.github.io/nimpress/definition-lists).
+
+## When to write what
+
+1. Concept guide: one focused topic, 100 to 400 words, with examples. Lives under `docs/`.
+
+2. Tutorial: a sequence of steps the reader follows in order. Numbered list at column zero, one section per phase.
+
+3. Reference: dense table of fields, options, or APIs. Tables and definition lists carry most of the content.
+
+4. Changelog entry: one markdown file per release, `type: changelog`, `data.version` set. See [Changelog renderer](https://nimling.github.io/nimpress/changelog-renderer).
+
+5. Landing page: `type: hero` with a tagline and feature grid. See [Hero](https://nimling.github.io/nimpress/hero).

package/.claude/rules/docs-sync.md

@@ -0,0 +1,59 @@
+# Docs sync pipeline
+
+Rules for wiring a repo's docs into the central docs site through the nimpress actions. The actions live in `nimling/nimpress/actions`, the docs site is the repo the pipeline is pointed at, and the shared GitHub App carries the cross repo trust. The reference is [Publishing a repo's docs to the central site](https://nimling.github.io/nimpress/actions).
+
+## The shape
+
+1. A source repo keeps its docs in an export folder at its root, `.nimpress` by default. The `export-dir` input on `docs-notify` names another. That folder is the content that syncs.
+
+2. The source repo has a consumer workflow `.github/workflows/docs.yml` that triggers on a version tag, not on a branch push, and guards on whether the export folder changed since the previous version tag.
+
+3. The docs site has the receiver `.github/workflows/docs-sync.yml` and optionally the mapping `nimpress.sources.json` at its root.
+
+## Consumer workflow
+
+1. Trigger is `on: push: tags: ['v*']` plus `workflow_dispatch`. Never trigger docs publish on a plain branch push.
+
+2. A guard step compares the export folder between the current tag and the previous version tag with `git diff`, and the notify runs only when it changed. The folder name lives in one workflow level variable that both the guard and the `export-dir` input read. A `workflow_dispatch` always counts as changed.
+
+3. Mint the token with `actions/create-github-app-token` using `app-id: secrets.APP_ID`, `private-key: secrets.APP_PRIVATE_KEY`, `owner: nimling`, and `repositories:` naming the docs site. Pass `steps.app.outputs.token` to `docs-notify@v2` with `docs-repo:` naming the same repo.
+
+## Receiver workflow
+
+The receiver is thin. The `docs-sync` action owns the mirror, the version bump, the commit and tag, and the pull request, with no other dependency.
+
+1. Listens on `repository_dispatch` type `nimpress-docs-sync` and `workflow_dispatch`.
+
+2. Mints an organization App token before checkout, then checks out the docs with that token and `fetch-depth: 0`, and checks out the source at the dispatched sha with the same token.
+
+3. Runs `docs-sync@v2` with `token`, `docs-repo`, `docs-dir`, `source-repo`, `source-path`, `content-root`, and optionally `mapping` and `defaults`. Nothing else.
+
+## Configuration
+
+1. The action `defaults` input and each `nimpress.sources.json` source hold the same json shape: `target`, `mode`, `publish`, `branch`, `commit`, `pullRequest`, `version`. The result is `defaults` merged with the source, the source winning per field. Either alone can fully configure a source.
+
+2. `commit.message`, `pullRequest.title`, `pullRequest.body`, and labels are Go templates with `.Repo`, `.Target`, `.Branch`, `.Version`, `.Added`, `.Modified`, `.Deleted`.
+
+3. `publish` is `auto` or `pr`. `auto` commits to `branch`, default main, and on a push conflict falls back to a pull request. `pr` always opens one.
+
+4. `version.files` are patch bumped in the sbump path form, and `version.tag` is pushed by the App token so the deploy fires on its own.
+
+## Secrets and the App
+
+1. The shared App is installed on each source repo and the docs repo with Contents read and write, Pull requests read and write, Metadata read.
+
+2. Each source repo and the docs repo carry `APP_ID` and `APP_PRIVATE_KEY`. The private key is the `.pem` from the App settings Private keys section.
+
+3. Never commit a private key. Keep `*.pem` in `.gitignore`.
+
+## What is wrong if you see it
+
+1. A consumer workflow triggered on a branch push rather than a version tag.
+
+2. A receiver that commits, opens pull requests, or bumps versions in its own steps instead of letting the action do it.
+
+3. A version tag pushed with the default token, which does not trigger the deploy. The App token must push it.
+
+4. A hand committed `tools/<repo>` subtree. The action owns it.
+
+5. A `.pem` tracked in git.

package/.claude/rules/file-layout.md

@@ -0,0 +1,49 @@
+# File layout
+
+Conventions for organizing markdown content inside a Nimpress site.
+
+## Directory mirrors URL
+
+By default, the directory layout under `contentDir` is the URL layout. `docs/guide/intro.md` lives at `/guide/intro`. `docs/guide/index.md` lives at `/guide`. `docs/index.md` lives at `/`.
+
+Override with frontmatter `path` when the URL and the file location should differ.
+
+## Index files
+
+A directory that should have its own landing page contains an `index.md`. That file becomes the directory's route and the directory's sidebar group label.
+
+A directory without an `index.md` shows as a synthetic group in the sidebar. The group label is a Title Case version of the directory name. The group has no link of its own, only its children.
+
+## Naming
+
+1. Files use lowercase kebab case. `getting-started.md`, not `Getting_Started.md`.
+
+2. Directories use lowercase. `guide/`, not `Guide/`.
+
+3. No spaces in file or directory names ever.
+
+4. Avoid abbreviations unless the abbreviation is the canonical name in the domain.
+
+## Grouping
+
+1. One top level directory per top level section. Keep the count small, the sidebar gets crowded fast.
+
+2. Co locate related pages. Tutorials for the OpenAPI renderer live near `docs/openapi.md`, not in a separate `tutorials/` tree.
+
+3. Resist creating a directory for a single page. Promote that page up a level instead.
+
+## Reorganizing
+
+1. Renaming a file changes its URL. If the page might be linked externally, set frontmatter `path` to the old URL so the link still works.
+
+2. Moving a file across directories is the same rule.
+
+3. Deleting a file is a hard break. Decide whether to delete or to redirect via frontmatter `redirect`.
+
+## Assets
+
+1. Shared assets live in the `assetsDir` folder, `assets` by default, at the repo root. Reference them by an absolute path under `assetUrlBase`, `/assets` by default. `![Diagram](/assets/architecture.svg)`. Downloadable files such as a pdf live here too and are served at the same base. The whole `assetsDir` folder is copied into the build output.
+
+2. Images that belong to one page live next to that page's markdown file inside `contentDir`. Reference them with a path relative to the markdown file. `![Diagram](./architecture.svg)`. nimpress serves them in dev and emits every non markdown file under `contentDir` into the build output.
+
+3. `assetsDir`, `assetUrlBase`, and `contentDir` are set in `nimpress.config`. A consumer that keeps a single public folder points `assetsDir` at it and sets `assetUrlBase` to `/`.

package/.claude/rules/frontmatter.md

@@ -0,0 +1,91 @@
+# Frontmatter rules
+
+Every markdown page declares YAML frontmatter at the top. Parsed with `gray-matter` and validated with `zod` in `src/plugin.ts`. Unknown fields warn but do not fail the build; declared fields come from the schema and the type definitions, extended there first, in the same change.
+
+## Always
+
+1. `title: string` is required. Use sentence case.
+
+## Sometimes
+
+1. `slug` shortens the sidebar label. Use when the title is descriptive but the sidebar needs to stay tight.
+
+2. `path` overrides the route. Use when the file location and the URL should differ. Two pages sharing an effective path raise a build error.
+
+3. `order: number` pins position inside the parent sidebar group. Use sparingly, the default alphabetical order is fine for most cases.
+
+3.1. `sidebar` inserts the page under a named sidebar group without changing its URL: required `name` as the verbatim label, optional `icon` and `style` decorating the group row, optional `path` overriding the group route. On a folder `index.md` the block changes and styles the folder's own sidebar entry instead of nesting a group; this works on every page type. On the root `index.md` the block inserts the page into the sidebar as the entry for the directory named by `path`, making the root page a clickable top level item. A `.story.ts` file carries the same block on its definition, `sidebar: { name, icon, style }`, to decorate its own story row; see the component modules rule.
+
+3.2. `sidebar.icon` accepts literal text or ascii art rendered verbatim in the mono font, inline `<svg>` markup rendered as markup, or a path ending in `.svg` resolved against the declaring file, or against `contentDir` when it starts with `/`, read at build time and inlined. An unreadable path warns and drops the icon. The sidebar renders icons only from `sidebar` blocks and story definitions.
+
+4. `description` gets used as a meta description and a search excerpt. Add it for any page expected to land via search.
+
+5. `visibility` controls where the page appears, one of `visible`, `hidden`, `dev-only`. `visible` is the default. `hidden` removes the page from sidebar, search, and the build, use it for drafts. `dev-only` keeps the page in `nimpress dev` but excludes it from the built bundle, use it for pages that must never ship.
+
+6. `noToc: true` hides the right rail. Use on hero pages and short pages where the TOC would feel empty.
+
+7. `footer: string` renders a centered, muted line at the bottom. Use for "Last reviewed", attribution, or a contact pointer.
+
+8. `tags` is a comma separated string or a YAML array of short keywords. The search index boosts tag matches and shows matched tags as pills under each result. Query syntax: a token ending in `/` like `api/` scopes the result set to pages whose sidebar path starts with that segment, case insensitive. Combine: `api/ device` returns device results inside the api folder.
+
+9. `gate: <string>` marks the page guarded. Any string works; the build's guard function maps gated pages into guarded bundles under `dist/_guarded/<bundle>/` and the runtime checks the viewer against the gate. Public pages omit it. Booleans stay unquoted (`true`, not `'true'`) everywhere in frontmatter.
+
+## Choosing `type`
+
+| You want | Set `type:` |
+|----------|-------------|
+| A normal documentation page | omit or `doc` |
+| A reference page rendered from an OpenAPI 3.1 spec | `openapi` |
+| A page combining several release notes into one collapsible list | `changelog` |
+| A landing page with an oversized hero band on top | `hero` |
+| A vertical roadmap timeline of milestones, epics, features, and bugs | `roadmap` |
+| An interactive entity relationship diagram of a database | `dbml` |
+| A live workshop page for one component in a library | `component` |
+
+## Type specific fields
+
+1. `type: openapi` requires `spec: ./path/to/spec.json` relative to the markdown file. `spec` carries the same duty on `type: dbml`, pointing at a `.dbml` file.
+
+2. `type: changelog` requires `data.version: '1.2.3'`, `data.release_date` as an RFC 3339 date, `data.title` for the per release headline, and `data.description` for the per release summary. Top level `title` is the shared collection title and the grouping key, every entry file in the same folder uses the exact same string. The route comes from the folder, so entries carry no `path` field. Optional `data.issue: <relative path>` plus `data.status` link the entry to a roadmap issue. See [changelog-entries.md](./changelog-entries.md).
+
+3. `type: hero` reads `data.eyebrow`, `data.logo`, `data.banner`, `data.tagline`, `data.lead`, `data.image`, `data.align`. Action buttons and feature grids compose as `:::actions` and `:::features` in the markdown body, `data` carries only the band fields. See [Hero](https://nimling.github.io/nimpress/hero) and [Markdown](https://nimling.github.io/nimpress/markdown).
+
+4. `type: roadmap` reads `title`, optional `description`, optional `background`, and optional `data.changelog`, `data.issues` to scope which sibling folders feed the timeline. The markdown body renders as the page header above the timeline. Sibling files of `type: milestone | epic | feature | bug` become the timeline items.
+
+5. `type: milestone | epic | feature | bug` (issue pages) require `title`, `description`, and `data.date` as an RFC 3339 string. Optional `data.parent` references another issue by relative filename. Each issue page renders at its own URL with a kind chip and date header. See [roadmap-entries.md](./roadmap-entries.md).
+
+6. `type: dbml` requires `spec: ./path/to/schema.dbml` relative to the markdown file. The title, the description, and the markdown body render inside a hero band above the diagram, shaped by `data.eyebrow`, `data.lead`, `data.logo`, `data.banner`, and `data.align`, with `data.download`, `data.fullscreen`, and `data.actions` for its buttons and `data.height` for the diagram. See [dbml-pages.md](./dbml-pages.md).
+
+7. `type: component` requires `data.system` naming a configured module system and `data.component` naming the component. Optional `data.package`, `data.file`, `data.version`, and `data.schema` as an inline schema layer merged over the schema file. One `type: component` page per folder; the sibling story files are its stories. See [component-modules.md](./component-modules.md).
+
+## SEO and social cards
+
+`meta` carries the per page metadata written to `<head>` at build time:
+
+```yaml
+meta:
+  description: One sentence for search.
+  canonical: https://developer.samna.io/path
+  robots: index,follow
+  keywords: [topic-a, topic-b]
+  og:
+    image: /og/page.png
+    type: article
+  twitter:
+    card: summary_large_image
+    site: '@samnaio'
+  jsonLd:
+    '@context': https://schema.org
+    '@type': TechArticle
+    headline: My page
+```
+
+Structured payloads beyond `meta` live inside `data` as structured objects, never as loose top level fields. Defaults flow from `frontmatter.description` and the site level `site` config in `createNimpressApp`. Full reference in [SEO](https://nimling.github.io/nimpress/seo).
+
+## Gating
+
+1. `gate` is the single gating field. The value is an arbitrary string the site's guard function and access checker interpret; nimpress assigns it no meaning of its own.
+
+2. At build, gated pages leave the public bundle and land in `dist/_guarded/<bundle>/`, where the bundle name comes from the `auth.guard` function in the nimpress config, or the gate value itself without one. `dist/guard.map.json` records what went where.
+
+3. `visibility: hidden` removes a page from the build entirely, and `dev-only` from the built bundle, independent of `gate`. A viewer who satisfies the gate still cannot reach a page whose visibility excludes it.

package/.claude/rules/page-types.md

@@ -0,0 +1,108 @@
+# Choosing a page type
+
+Quick guide for picking the right `type` in frontmatter.
+
+## `doc`
+
+The default. Reach for it first. Anything that does not match another type is a `doc`.
+
+## `openapi`
+
+Use only when:
+
+1. The page exists to document an HTTP API.
+
+2. There is a maintained OpenAPI 3.1 spec next to the markdown file.
+
+3. The reader expects per operation deep links such as `#operation/PostBookable`.
+
+Do not duplicate the spec by writing prose for each endpoint. Edit the spec descriptions, the renderer pulls them in and runs them through the same markdown pipeline.
+
+## `changelog`
+
+Use when:
+
+1. The page collects release notes that grow over time.
+
+2. Each release should be authored as one markdown file, so reviewing a release is a single file PR.
+
+3. Multiple files should share one URL and one rendered scroll.
+
+Do not use `changelog` for migration guides or one off retrospectives. Those are `doc` pages.
+
+## `hero`
+
+Use sparingly for:
+
+1. The site home page.
+
+2. Top level section landing pages: `/solutions`, `/tools`, `/libraries`, `/api`.
+
+3. New product or service introductions.
+
+Do not use `hero` for ordinary documentation. The oversized typography is a beacon, not a default.
+
+## `roadmap`
+
+Use when:
+
+1. The page surfaces planned and shipped work as a customer facing timeline.
+
+2. The markdown file describes only the page header and background. Sibling files of `type: milestone | epic | feature | bug` carry the actual items.
+
+3. Changelog entries can opt in with `data.issue: <relative path>` and `data.status` so shipped work updates the rocket and drops a marker on the spine.
+
+Do not use `roadmap` for internal status notes or engineering tickets. The page is customer facing. See [roadmap-entries.md](./roadmap-entries.md).
+
+## `milestone | epic | feature | bug`
+
+Issue page types. Each file is one standalone page at its own URL, listed under a parent `type: roadmap` page in the sidebar.
+
+1. Use when describing a roadmap item that customers should be able to deep link to.
+
+2. Frontmatter: `title`, `description`, `data.date` are required. `data.parent` references another issue in the same roadmap.
+
+3. The body is a regular doc page that renders with a kind chip and date header above the markdown.
+
+## `dbml`
+
+A full page entity relationship viewer. Use when:
+
+1. The page exists to show the shape of a database.
+
+2. The schema is maintained as a `.dbml` file next to the markdown file.
+
+3. The reader should pan, zoom, and read column level detail rather than look at a static picture.
+
+Frontmatter needs `spec` pointing at the `.dbml` file, and `data` shapes the hero band and its buttons. For a diagram inside a page that is mostly prose, use the inline ` ```dbml ` fence instead of this type. See [dbml-pages.md](./dbml-pages.md).
+
+## `component`
+
+A live component workshop page. Use when:
+
+1. The page presents one component from a library configured as a module system.
+
+2. Readers should render it live, drive its props through controls, and browse its stories.
+
+Frontmatter needs `data.system` and `data.component`. One `type: component` page per folder; the sibling `.story.ts` files become the stories. See [component-modules.md](./component-modules.md).
+
+## Decision tree
+
+```
+Is the page rendered from an OpenAPI spec?
+├─ Yes  → type: openapi
+└─ No
+   ├─ Is it a stack of versioned release notes?
+   │  └─ Yes  → type: changelog
+   ├─ Is it a customer facing roadmap header?
+   │  └─ Yes  → type: roadmap
+   ├─ Is it one item on a roadmap timeline?
+   │  └─ Yes  → type: milestone | epic | feature | bug
+   ├─ Is it a full page database diagram?
+   │  └─ Yes  → type: dbml
+   ├─ Is it a live component workshop page?
+   │  └─ Yes  → type: component
+   ├─ Is it a beacon style landing page?
+   │  └─ Yes  → type: hero
+   └─ Otherwise → type: doc  (omit the field)
+```

package/.claude/rules/paths.md

@@ -0,0 +1,27 @@
+# Paths and the cache root
+
+Every folder nimpress writes is declared under the optional `paths` block in the config, each field carrying a default. This rule is the contract for where files may appear, for the tool and for anyone working in a consumer repo.
+
+1. `paths.out`, default `dist`, is the build root. Build artifacts only.
+
+2. `paths.cache`, default `node_modules/.nimpress`, is the single cache root for every operation, layered per feature beneath it.
+
+2.1. `<cache>/site` holds the docs vite cache.
+
+2.2. `<cache>/modules/<system>` holds the harness cache for each component system.
+
+2.3. `<cache>/lint` holds the lint verification build and is removed when lint finishes.
+
+2.4. `<cache>/verify` is the scratch layer for throwaway verification pages: harness html an agent or a human drops in to exercise a component through the running dev server, loaded same origin through the server's `@fs` urls. nimpress never reads or writes this layer. Whoever creates a file here deletes it when the verification is done.
+
+3. `paths.export`, default `.nimpress`, is the handoff folder the export command fills for the docs-sync pipeline. An artifact, not a cache.
+
+4. `paths.modules` and `paths.guarded`, defaults `_components` and `_guarded`, are both the folders under `out` and the served url segments.
+
+## Never
+
+1. Never write ephemeral files anywhere else: not the repo root, not a new dot folder under `node_modules`, not a temp dir the dev server cannot serve. The cache root is the one sanctioned location and `<cache>/verify` is the one sanctioned scratch layer.
+
+2. Never write by hand into `<cache>/site`, `<cache>/modules/<system>`, or `<cache>/lint`. Those layers are owned by the commands that build them.
+
+3. Never commit anything from the cache root. It lives under `node_modules` so git never sees it.