@nimtech/nimpress 2.3.9 → 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

@@ -1,19 +1,19 @@
 ---
 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, wiring gated pages to the auth provider, or installing this skill and shell completion.
+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, and wires gated pages to the auth provider. Every command runs from the repo root of the site it acts on.
+`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.
+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`, and `completion` 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.
+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.
+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.
 
@@ -40,9 +40,10 @@ Writes `nimpress.config.ts` with every field documented and commented out, or `n
 
 ```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.
+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
 
@@ -100,6 +101,30 @@ 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
@@ -113,6 +138,16 @@ Both read `access.json` from the build folder and fail with `[nimpress] guard: <
 
 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
@@ -191,6 +226,12 @@ Publish a repo's pages into the central docs site:
 nimpress export --target=nimployer
 ```
 
+See those pages inside the central docs site before the tag:
+
+```sh
+nimpress view
+```
+
 Ship a gated build:
 
 ```sh
@@ -207,7 +248,7 @@ 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`.
+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>`.