@nimtech/nimpress 2.3.8 → 2.4.0

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

@@ -32,7 +32,7 @@ title: How sessions work
 
 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.
+6. `hide: [toc]` hides the right rail. Use only on short pages where the TOC would feel empty. The same list takes `navigation`, `path`, `footer`, and `tags`.
 
 7. `footer` renders a centered, muted line at the bottom of the page.
 
@@ -56,7 +56,7 @@ title: How sessions work
 
 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).
+8. Definition lists for reference grids of terms with one line descriptions. See [Definition lists](https://nimling.github.io/nimpress/authoring/definition-lists).
 
 9. Mermaid blocks render `flowchart`, `stateDiagram-v2`, `sequenceDiagram`, `erDiagram` when a flow or state reads more cleanly visually.
 

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

@@ -30,7 +30,7 @@ Rules for writing markdown pages, both inside this repo's `docs/` and inside con
 
 ## Links
 
-1. Prefer relative links within the same section, absolute links across sections. See [Relative links](https://nimling.github.io/nimpress/relative-links).
+1. Prefer relative links within the same section, absolute links across sections. See [Relative links](https://nimling.github.io/nimpress/authoring/relative-links).
 
 2. Use the page title as the link text. Avoid `click here`.
 
@@ -64,6 +64,24 @@ Rules for writing markdown pages, both inside this repo's `docs/` and inside con
 
 5. `:::check` for verification steps.
 
+6. `:::abstract` for a summary of the section that follows.
+
+7. `:::success` for the outcome the reader sees when a step worked.
+
+8. `:::question` for a question the reader is likely to ask, answered in the body.
+
+9. `:::failure` for the outcome the reader sees when a step did not work.
+
+10. `:::danger` for actions that lose data or cannot be undone.
+
+11. `:::bug` for a known defect and its workaround.
+
+12. `:::example` for a worked example set apart from the prose.
+
+13. `:::quote` for a quotation with its source.
+
+Text after the type name is the title, `""` removes the title row, and a JSON payload on the opening line takes `collapsible`, `open`, and `inline`. See [Markdown](https://nimling.github.io/nimpress/authoring/markdown).
+
 Use sparingly. Three callouts on a page is already a lot.
 
 ## Definition lists
@@ -75,7 +93,7 @@ term_name
 : One line description.
 ```
 
-See [Definition lists](https://nimling.github.io/nimpress/definition-lists).
+See [Definition lists](https://nimling.github.io/nimpress/authoring/definition-lists).
 
 ## When to write what
 
@@ -85,6 +103,24 @@ See [Definition lists](https://nimling.github.io/nimpress/definition-lists).
 
 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).
+4. Changelog entry: one markdown file per release, `type: changelog`, `data.version` set. See [Changelog renderer](https://nimling.github.io/nimpress/page-types/changelog).
+
+5. Landing page: `type: hero` with a tagline and feature grid. See [Hero](https://nimling.github.io/nimpress/page-types/hero).
+
+## Page skeleton
+
+Every feature page in `docs/` follows one shape.
+
+1. A definition paragraph opens the page: what the thing is, why it matters in documentation, and what nimpress provides. A definition sentence borrowed from a reference keeps its adjectives and dashes; the voice rules above do not rewrite it.
+
+2. `## Configuration` follows when a switch exists, with one H3 per option. A configuration paragraph ends with "Add the following lines to your configuration:" and a fenced json block of the config field.
+
+3. `## Usage` follows with one H3 per verb, `### Add a button`, `### Hide the sidebars`, `### Use card grids`. A usage paragraph that depends on a switch opens with "When X is enabled".
+
+4. `## Customization` follows when an override exists, with one H3 per override. Pages that render chrome end with `## Restyling` pointing at the styling reference.
+
+5. Names stay nimpress names when the sentences are borrowed: callouts, actions, cards, features, frontmatter. Nothing is called an admonition.
+
+## The tree
 
-5. Landing page: `type: hero` with a tagline and feature grid. See [Hero](https://nimling.github.io/nimpress/hero).
+`docs/` has one folder per top level section: `get-started`, `usage`, `setup`, `authoring`, `page-types`, `examples`, `styling`, `community`, plus `changelog`, `tags`, `glossary`, and `404` at the root. A page that lives at the root keeps its url and joins its section with a `sidebar` block whose `path` names the section folder.

package/.claude/rules/frontmatter.md

@@ -24,7 +24,13 @@ Every markdown page declares YAML frontmatter at the top. Parsed with `gray-matt
 
 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.
+6. `hide` is a list of page elements to drop. Use the hide front matter property to hide one or more elements of a page: `navigation` drops the sidebar column, `toc` the right rail, `path` the breadcrumbs, `footer` the page footer line, `tags` the tag row. `hide: [toc]` on hero pages and short pages where the TOC would feel empty. A `hide` list in `defaultFrontmatter` merges with the page's own list.
+
+6.1. `status: <identifier>` marks the page in the sidebar. A status can be assigned to each page and displayed in the navigation sidebar. `new` and `deprecated` carry labels without configuration; the `status` config field maps further identifiers to labels. The row renders a `np-sidebar-status` mark with the label as its title plus `np-sidebar-status-<identifier>` for coloring.
+
+6.2. `feedback: true` shows the was this page helpful widget under the page when the `feedback` config block exists, the way `subscribe: true` shows the subscribe control on a changelog. Sites that want it everywhere set it in `defaultFrontmatter`, and a page turns it off again with `feedback: false`.
+
+6.3. `styles` lists extra stylesheets for the page, relative to the markdown file. `<page>.css` and `<page>.<component>.css` beside the page load by name without it. See the styling rule.
 
 7. `footer: string` renders a centered, muted line at the bottom. Use for "Last reviewed", attribution, or a contact pointer.
 
@@ -40,6 +46,14 @@ Every markdown page declares YAML frontmatter at the top. Parsed with `gray-matt
 | 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 landing page under the header alone, no sidebar, no rail, full width | `fullpage` |
+| The not found page the build serves for an unknown address | `404` |
+| A folder index that lists its children as a card grid | `section` |
+| The listing of every tag with its pages | `tags` |
+| The definition list of the site terms that feeds tooltips everywhere | `glossary` |
+| A grid of people from frontmatter data | `team` |
+| A row of plans with prices from frontmatter data | `pricing` |
+| A shape of your own, or a built in renderer replaced | a name from `pageTypes` in the config |
 | 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` |
@@ -50,7 +64,19 @@ Every markdown page declares YAML frontmatter at the top. Parsed with `gray-matt
 
 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).
+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/page-types/hero) and [Markdown](https://nimling.github.io/nimpress/authoring/markdown).
+
+3.1. `type: fullpage` reads `data.eyebrow`, `data.logo`, `data.background`, `data.tagline`, `data.lead`, `data.align`, and `data.width`. The type hides `navigation`, `path`, `toc`, and `footer` by itself. See [Full pages](https://nimling.github.io/nimpress/page-types/fullpage).
+
+3.2. `type: 404` needs `title` alone. The build writes the page as `404.html` at the output root, the app routes an unknown path to it, and it stays out of the sidebar, search, and the sitemap. One per site. See [Not found page](https://nimling.github.io/nimpress/page-types/404).
+
+3.3. `type: section` belongs on a folder `index.md` and reads `data.columns` and `data.depth`. The body renders first and every child page follows as a card in sidebar order. See [Section pages](https://nimling.github.io/nimpress/page-types/section).
+
+3.4. `type: tags` needs `title` alone and lists every tag with its pages under the body. One per site. Every page shows its `tags` at the bottom, hidden with `hide: [tags]`, and the `tags` config block maps tags to identifiers and identifiers to icons. See [Tags page](https://nimling.github.io/nimpress/page-types/tags).
+
+3.5. `type: glossary` needs `title` and a definition list body. Every term gets an anchor, the rail lists the terms, and the first occurrence of a term in each paragraph of every other page renders as an abbreviation with a tooltip. One per site. See [Glossary page](https://nimling.github.io/nimpress/page-types/glossary).
+
+3.6. `type: team` requires `data.members`, each with `name` and optional `role`, `image`, `bio`, and `links`; `data.columns` and `data.align` shape the grid. `type: pricing` requires `data.tiers`, each with `name` and optional `price`, `period`, `description`, `benefits`, `action`, and `highlight`; `data.columns` and `data.footnote` shape the row. See [Team pages](https://nimling.github.io/nimpress/page-types/team) and [Pricing pages](https://nimling.github.io/nimpress/page-types/pricing).
 
 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.
 
@@ -82,6 +108,8 @@ meta:
     headline: My page
 ```
 
+`meta.override: true` keeps the authored keywords and description when `seo.auto` generates them; without it the generated values win. `meta.ai: false` adds `noai, noimageai` to the page's robots meta, and `true` lifts a site wide `seo.ai.index: false` for the 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

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

@@ -42,6 +42,40 @@ Use sparingly for:
 
 Do not use `hero` for ordinary documentation. The oversized typography is a beacon, not a default.
 
+## `fullpage`
+
+Use for:
+
+1. The site home when the sidebar would distract from the pitch.
+
+2. A product landing that opens a section and routes the reader onward.
+
+The type hides the sidebar, the breadcrumbs, the rail, and the previous and next links by itself, and the band plus the body span the viewport. Do not use `fullpage` for a page the reader will read top to bottom; a `hero` keeps the shell for that.
+
+## `404`
+
+Use for exactly one page per site: the not found page the build serves for every address with no page behind it. The body carries the prose and an action row back into the site. Never place it in the sidebar unless the site wants a visible link to it.
+
+## `section`
+
+Use for a folder `index.md` that opens a section: the prose renders first and every child page follows as a card in sidebar order, so the overview needs no authored list. `data.columns` pins the column count and `data.depth: 2` lists grandchildren under a heading per child folder. The type belongs on a folder index only. See [Section pages](https://nimling.github.io/nimpress/page-types/section).
+
+## `tags`
+
+Use for exactly one page per site: the listing of every tag with its pages. Tags themselves go on the pages through the `tags` frontmatter field, and the `tags` config block gives them icons. See [Tags page](https://nimling.github.io/nimpress/page-types/tags).
+
+## `glossary`
+
+Use for exactly one page per site: the definition list of the terms every page should explain. Each term becomes an abbreviation with a tooltip wherever it occurs in the prose of other pages. Page local abbreviations use `*[TERM]: description` lines instead. See [Glossary page](https://nimling.github.io/nimpress/page-types/glossary).
+
+## `team`
+
+Use for a page whose content is people: a grid of members from `data.members` with a name, a role, a bio, and links. Prose stays in the body above the grid. See [Team pages](https://nimling.github.io/nimpress/page-types/team).
+
+## `pricing`
+
+Use for a page whose content is plans: a row of tiers from `data.tiers` with a price, a benefit list, and one action, `highlight` on the recommended one. Prose stays in the body and the small print in `data.footnote`. See [Pricing pages](https://nimling.github.io/nimpress/page-types/pricing).
+
 ## `roadmap`
 
 Use when:
@@ -86,6 +120,10 @@ A live component workshop page. Use when:
 
 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).
 
+## Custom types
+
+A type the site registers under `pageTypes` in the config, a Svelte component that receives the page. Use it when a shape recurs on a site and none of the built in types fits, and put a `<Component>.schema.json` beside it so lint validates the `data` fields. A built in name under `pageTypes` replaces that renderer for the whole site. See [Custom page types](https://nimling.github.io/nimpress/page-types/custom).
+
 ## Decision tree
 
 ```
@@ -102,6 +140,20 @@ Is the page rendered from an OpenAPI spec?
    │  └─ Yes  → type: dbml
    ├─ Is it a live component workshop page?
    │  └─ Yes  → type: component
+   ├─ Is it a grid of people?
+   │  └─ Yes  → type: team
+   ├─ Is it a row of plans with prices?
+   │  └─ Yes  → type: pricing
+   ├─ Is it the definition list of the site's terms?
+   │  └─ Yes  → type: glossary
+   ├─ Is it the listing of every tag with its pages?
+   │  └─ Yes  → type: tags
+   ├─ Is it a folder index that lists its children as cards?
+   │  └─ Yes  → type: section
+   ├─ Is it the not found page of the site?
+   │  └─ Yes  → type: 404
+   ├─ Is it a landing page with none of the shell chrome?
+   │  └─ Yes  → type: fullpage
    ├─ Is it a beacon style landing page?
    │  └─ Yes  → type: hero
    └─ Otherwise → type: doc  (omit the field)

package/.claude/rules/style.md

@@ -42,6 +42,10 @@ Consumers override Nimpress styles by:
 
 2. A per page stylesheet named the same as a markdown file. `guide/index.css` next to `guide/index.md` loads while the route is `/guide` or any path under it. A leaf page's stylesheet loads only on its own page. The author writes normal selectors and they apply only while inside that subtree.
 
+2.1. A file under `styles/` in the content folder named after a component class root, `styles/tag.css`, applies to that component on every page, wrapped in `@scope (.np-tag)`. A file named `<page>.<component>.css` beside a page applies to that component on that page only. Lint checks the component name against the class roots.
+
+2.2. A `styles` list in the frontmatter names further stylesheets for the page, relative to the markdown file.
+
 3. A css file that is not a page style, such as a story asset loaded with `?raw`, is named with a leading underscore, `template/_cv.css`. Lint treats underscore css as inert; any other css file must sit next to the markdown page it is named after.
 
 Consumers never need to fork the framework to change visuals.

package/.claude/skills/nimpress/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: nimpress
+description: Drive the nimpress documentation site cli from the terminal. Use when scaffolding a docs site, running or building it, linting content and frontmatter, managing the component workshop with schemas stories and harnesses, exporting pages for the docs sync pipeline, previewing a repo's export folder inside the central docs site, wiring gated pages to the auth provider, or installing this skill and shell completion.
+---
+
+# nimpress
+
+`nimpress` is the cli of `@nimtech/nimpress`, a Svelte 5 documentation site framework. It scaffolds a site, serves it, builds it, lints the content, drives the component workshop, collects pages for the central docs site, previews them inside that site, and wires gated pages to the auth provider. Every command runs from the repo root of the site it acts on.
+
+## Boundaries
+
+1. The cli acts on the current working directory. There is no target flag and no remote mode. Change directory into the site before running anything. `view` is the one command that reaches another repo, the central docs site, and it does so through a cache clone it owns.
+
+2. Every command except `init`, `skill`, `completion`, `view`, and `cache clear` loads the site config first. A missing or broken `nimpress.config.ts` or `nimpress.config.json` fails the command before it starts, so `nimpress init` is what a bare folder runs first. `view` and `cache clear` run from any repo the docs sync pipeline publishes, config or not.
+
+3. `nimpress` writes only into the folders the `paths` config block declares. It never writes into the repo root beyond the config, the content folder, `CLAUDE.md`, `AGENTS.md`, and a temporary `index.html` that the build removes. Outside the repo it writes `~/.nimpress` for the links `view` resolves and `~/.tide/nimpress/sites/` for the docs site clones, and nothing else.
+
+4. The authoritative authoring rules ship inside the package at `node_modules/@nimtech/nimpress/.claude/rules/`. Read the rule before writing content, never guess the frontmatter contract from a rendered page.
+
+## Shape of every command
+
+```
+nimpress <command> [subcommand] [positional] [--flag] [--flag=value]
+```
+
+With no arguments the cli runs `dev`. An unrecognised command fails with `[nimpress] unknown command: <name>`. Boolean flags are the bare `--name`. Value flags are always `--name=value`, never `--name value`. Positional arguments are the words that do not start with `--`.
+
+## Commands
+
+### init
+
+```sh
+nimpress init
+nimpress init --json
+```
+
+Writes `nimpress.config.ts` with every field documented and commented out, or `nimpress.config.json` with `--json`, and only when neither file already exists. Creates the content folder with an `index.md` when the folder is missing or empty. Writes `CLAUDE.md` and `AGENTS.md` when they are missing, each pointing at the packaged rules.
+
+### dev
+
+```sh
+nimpress dev
+nimpress dev --view
+```
+
+Serves the site and starts one harness server for every configured component system. It stays running and binds the vite cli shortcuts. `--view` serves the central docs site this repo publishes into instead, with the exported pages in place, the same run as `view` below.
+
+### build
+
+```sh
+nimpress build
+```
+
+Builds the static site into `paths.out`, then builds the harness bundle of every system whose `visibility` is not `dev-only`.
+
+### lint
+
+```sh
+nimpress lint
+nimpress lint --no-build
+```
+
+Runs the structure check, the frontmatter check, the import check, and the modules check, then builds into `<cache>/lint` to prove the output compiles and removes that folder afterwards. `--no-build` stops after the checks. A clean run prints `nimpress lint: structure, frontmatter, imports, and modules ok` and then `nimpress lint: build ok, everything passes`. Any problem prints one line per problem and exits 1.
+
+### modules
+
+The component workshop. `--system=<name>` names the system when several are configured, and is optional when exactly one is.
+
+```sh
+nimpress modules init
+nimpress modules dev --system=nimtech
+nimpress modules build --system=nimtech
+nimpress modules lint --system=nimtech
+nimpress modules story <Component> --system=nimtech --framework=vue
+nimpress modules import <file> --system=nimtech --name=Button --source=./src/components --stories=./stories --match='^Btn' --from-stories --select
+nimpress modules create <Component> --system=nimtech --framework=svelte
+nimpress modules create --component=<ref> --schema
+nimpress modules update <ref> --component=<ref> --system=nimtech
+```
+
+1. `init` creates the modules folder and adds a `modules` block to `nimpress.config.json` when that file exists.
+
+2. `dev` serves the harnesses and never returns. `build` builds the deployable harness bundles.
+
+3. `lint` checks the systems, the schemas, and the stories, and is the check to run after touching a component page.
+
+4. `story` with a component name writes one auto story, and with no name writes an auto story for every component of the system. `--framework=vue` or `--framework=svelte` overrides the framework the system declares.
+
+5. `import` with a positional file imports that one component, and `--name=` sets the page name. With no file it walks `--source=` or the system source, picks up `.stories.ts` files there and under `--stories=`, filters names with the `--match=` regular expression, and asks which components to take with `--select`. `--from-stories` takes the component list from the csf files and requires `--stories=`.
+
+6. `create <Component>` creates the component page folder. `create --component=<ref> --schema` upserts a single schema instead, and `--schema` is required in that form.
+
+7. `update` upserts every component schema from the component types, adding new members without touching authored defaults, enums, or descriptions. A positional reference or `--component=<ref>` limits it to one component.
+
+### export
+
+```sh
+nimpress export --target=<name>
+nimpress export --target=<name> --out=.nimpress
+```
+
+Copies every page carrying `export: <name>` in its frontmatter, together with the whole folder that page sits in, into `paths.export`. A page with `export: true` is taken by every target. The `export:` and `file:` frontmatter lines are stripped and a `version:` line is written from the `version` field of `package.json` when the page carries a `package:` field. `--out=` overrides the destination.
+
+### view
+
+```sh
+nimpress view
+nimpress view --no-browser
+nimpress view --docs-repo=<owner/repo>
+nimpress view --export-dir=<folder> --target=<name>
+nimpress view --offline
+nimpress dev --view
+```
+
+Serves the central docs site this repo publishes into with the repo's export folder overlaid at its mapped path, and opens the browser on those pages. It needs no config in the repo. The docs site is read from the `docs-notify` step of the workflows under `.github/workflows/`, `docs-repo` and `export-dir`, one link per site when several name one; where none does, the command asks for the repo url, http or ssh, and `--docs-repo=` answers it up front. A connection that is refused leads to a login through `gh` when installed, else by naming the ssh key. Links and the login method persist in `~/.nimpress`, so the question is asked once per repo. The site is cloned under `~/.tide/nimpress/sites/<owner>__<repo>/`, fetched on every run unless `--offline`, and `pnpm install` runs there on first use and on a lockfile change. The mapped path is `nimpress.sources.json` merged with the receiver's `defaults`, the source winning per field. A repo with its own config runs `export` in watch mode underneath; `nimpress dev --view` is the same run from there. `--no-browser` prints the url instead of opening it, `--export-dir=` names the export folder when no workflow does, and `--target=` limits the export to one target name.
+
+### cache
+
+```sh
+nimpress cache clear
+nimpress cache clear --links
+nimpress cache clear --sites
+nimpress cache clear --local
+```
+
+`clear` with no flag removes the links in `~/.nimpress` and the docs site clones under `~/.tide/nimpress/sites/`, so the next `view` resolves and clones afresh. `--links` and `--sites` take one of the two. `--local` removes `paths.cache` of the current repo and needs a config there.
+
+### guard
+
+```sh
+nimpress guard map --dist=dist --out=guard.map.json
+nimpress guard apply --dist=dist --map=uploaded.json
+```
+
+Both read `access.json` from the build folder and fail with `[nimpress] guard: <path>/access.json not found, run a build first` when there is none. `--dist=` overrides `paths.out`.
+
+1. `map` walks the guarded folder, records the path, the sha256, the size, the mime type, and the gates of every file, and writes the mapping. `--out=` names the file instead of `<dist>/guard.map.json`.
+
+2. `apply` reads the mapping the asset host returned, requires `--map=`, writes the base url and the published asset list back into `access.json`, and removes both the guarded folder and `guard.map.json` from the build.
+
+### seo
+
+```sh
+nimpress seo
+nimpress seo --write
+nimpress seo --out=reports/seo.json
+```
+
+Prints one line per page with the route, the keyword count, the description length, whether the robots directive carries `noai`, and whether the values are authored or generated, and writes the full set to `seo.map.json`. `--write` puts the generated keywords and description into each page's frontmatter under `meta`, only where the page has none. `--out=` names the map file.
+
+### skill
+
+```sh
+nimpress skill get
+nimpress skill put
+nimpress skill put --project
+```
+
+`get` prints this document. `put` writes it to `~/.claude/skills/nimpress/SKILL.md`, or to `.claude/skills/nimpress/SKILL.md` under the current directory with `--project`, and prints the path it wrote.
+
+### completion
+
+```sh
+nimpress completion zsh
+nimpress completion --auto
+nimpress completion --auto --skill
+nimpress completion bash --auto
+```
+
+With a shell name and no `--auto` it prints the script for `bash`, `zsh`, `fish`, or `powershell` to stdout. `--auto` detects the shell from `$SHELL` when none is named, writes a nimpress owned file under `~/.config/nimpress/completions`, and points the rc file at it inside a block delimited by `# >>> nimpress completion >>>` and `# <<< nimpress completion <<<`. Rerunning `--auto` rewrites the block in place. fish is written to `~/.config/fish/completions/nimpress.fish` and needs no rc change. `--skill` installs this skill globally in the same step and only works alongside `--auto`.
+
+## Where files land
+
+The `paths` config block declares every folder nimpress writes, each with a default.
+
+| Field | Default | What it holds |
+| --- | --- | --- |
+| `paths.out` | `dist` | the build root, build artifacts only |
+| `paths.cache` | `node_modules/.nimpress` | the one cache root, layered per feature |
+| `paths.export` | `.nimpress` | the handoff folder `export` fills |
+| `paths.modules` | `_components` | the harness bundles under `out` and their url segment |
+| `paths.guarded` | `_guarded` | the guarded pages under `out` and their url segment |
+
+The cache is layered: `<cache>/site` for the docs vite cache, `<cache>/modules/<system>` for each harness, `<cache>/lint` for the lint verification build which is removed when lint finishes, and `<cache>/verify` as the one sanctioned scratch layer for throwaway verification pages. Never write ephemeral files anywhere else, and never commit anything from the cache root.
+
+## The packaged rules
+
+Read the rule before writing content. They live at `node_modules/@nimtech/nimpress/.claude/rules/`.
+
+1. `frontmatter.md` and `page-types.md` before creating or editing any page.
+
+2. `docs-authoring.md` and `style.md` for prose, structure, and markdown surface.
+
+3. `component-modules.md` before touching component pages, stories, controls, or the modules commands.
+
+4. `changelog-entries.md`, `roadmap-entries.md`, and `dbml-pages.md` for those page types.
+
+5. `docs-sync.md` and `deploy.md` for the publishing flows and the export header.
+
+6. `file-layout.md` and `doc-pages.md` for where files go, and `paths.md` for every folder nimpress writes.
+
+7. `chunk-cycles.md` when a build fails on the `nimpress:chunk-cycle-guard` plugin, which every build and therefore `nimpress lint` runs over the emitted bundle.
+
+## Recipes
+
+Stand a new site up and prove it builds:
+
+```sh
+nimpress init
+nimpress lint
+nimpress build
+```
+
+Take a component library into the workshop and keep the schemas current:
+
+```sh
+nimpress modules init
+nimpress modules import --system=nimtech --source=./src/components
+nimpress modules update --system=nimtech
+nimpress modules lint --system=nimtech
+```
+
+Publish a repo's pages into the central docs site:
+
+```sh
+nimpress export --target=nimployer
+```
+
+See those pages inside the central docs site before the tag:
+
+```sh
+nimpress view
+```
+
+Ship a gated build:
+
+```sh
+nimpress build
+nimpress guard map
+nimpress guard apply --map=uploaded.json
+```
+
+Install the skill and completion on a fresh machine:
+
+```sh
+nimpress completion --auto --skill
+```
+
+## Failure reading
+
+1. `[nimpress] unknown command: <name>` means the first word is not one of `init`, `lint`, `dev`, `build`, `guard`, `modules`, `export`, `skill`, `completion`, `seo`.
+
+2. `[nimpress] modules <sub>: several systems configured` means the config declares more than one system and the command needs `--system=<name>`.
+
+3. `[nimpress] modules import --from-stories requires --stories=<csf dir>` and `[nimpress] modules create --component expects --schema to upsert the schema` both name the flag that was missing. The message states the required flag by name.
+
+4. `[nimpress] guard: <path>/access.json not found, run a build first` means the guard commands ran before `nimpress build`, or against the wrong `--dist=`.
+
+5. A lint failure prints `nimpress lint failed with <n> problems` and then one line per problem, each naming the file relative to the content folder and what to change. Fix the file the line names, never the checker.
+
+6. A build problem inside `nimpress lint` is reported one line per message prefixed with `build:`. It is the same failure `nimpress build` gives, caught before the real output folder is touched.