@orbytes/astrolab 0.4.0-next.1 → 0.4.0-next.2

package/README.md

@@ -11,12 +11,14 @@ the site right now**, derived from the pages rather than declared. Its engine be
 **Tasks — the pin board** at `/lab/tasks` — click a rendered element on `astro dev`, leave a
 comment, and a markdown ticket plus a screenshot land on local disk for an agent to pick up
 ([docs/PIN.md](./docs/PIN.md), contract at [docs/PIN-CONTRACT.md](./docs/PIN-CONTRACT.md)). Kanban and
-table views, in the lab's own sidebar. Dev only, switchable off with `pin: false`; `/pin`, its old
+table views in the lab, and a **Comment** button in its navbar that pins an element of the page it
+is previewing. Dev only, and only in a site that is inside a git repository (see
+[Tasks](#tasks--the-pin-board-at-labtasks)); switchable off with `pin: false`. `/pin`, its old
 address, redirects there.
 
 It ships mostly **source**. The `.astro` files, and everything under `src/chrome/`, `src/shell/`,
 `src/ui/` and `src/types/`, are compiled by the consumer's own Vite, the way Starlight ships its components —
-which is why the lab picks up the consumer's tokens, fonts and breakpoints in a story preview: it
+which is why the lab picks up the consumer's tokens, fonts and breakpoints in a variant's preview: it
 renders inside the consumer's pipeline. The one exception is `src/core/`, transpiled to `dist/` by
 `scripts/build-core.mjs` at `prepack` and `prepare`, because `astro.config.mjs` is loaded by Node's
 own ESM loader and Node refuses to strip TypeScript under `node_modules`. Without that step an
@@ -25,9 +27,12 @@ installed copy cannot be loaded at all. The script's header comment is the full
 ## Install
 
 ```sh
-npm i -D @orbytes/astrolab
+npm i -D -E @orbytes/astrolab
 ```
 
+`-E` (`--save-exact`) pins the version: a lab upgrade is a deliberate change to a site, never a
+side effect of `npm install`.
+
 Then add the integration:
 
 ```js
@@ -38,18 +43,26 @@ import orbytesLab from "@orbytes/astrolab";
 export default defineConfig({
   integrations: [
     orbytesLab({
-      css: ["./src/styles/global.css"], // your token and base stylesheets
+      css: ["./src/styles/global.css"], // optional: your site's own stylesheet(s), for the previews
     }),
   ],
 });
 ```
 
+`css` is optional, and `./src/styles/global.css` is only an example: name whatever stylesheet your
+site's layout imports. A new Astro project has no such file, so either point `css` at the one you
+have or leave the option out. Left out, it is `[]` and the variant previews get no site stylesheet
+at all, only each component's own scoped styles; the lab's chrome never gets it either way. Each
+entry becomes a plain `import` in the preview's layout (a path starting with `.` resolves against
+the project root, anything else as a package), so name only files that exist.
+
 That is the whole configuration. In particular, **do not add an `ssr.noExternal` entry for this
 package** — the integration adds its own, because the package ships `.astro` files that Vite would
 otherwise externalise and hand to Node, which cannot read them. A consumer needs nothing. (Two
 older orbytes repos set it by hand; it is redundant, and copying it from them is copying noise.)
 
-Now write a story. Stories live under `src/lab/`, in one directory per tier:
+Each named export in a stories file is a story; the lab lists them as **Variants**. Now write a
+story. Stories live under `src/lab/`, in one directory per tier:
 
 ```
 src/lab/
@@ -57,12 +70,11 @@ src/lab/
   components/Button.astro + Button.stories.ts
   explorations/KeycapButton.astro + KeycapButton.stories.ts
   decorators/            ← yours, built against YOUR page shell (see below)
-  cull.json              ← written by the lab, commit it
   responsive.json        ← written by the lab, commit it
 ```
 
 A stories file has a default export naming the component, and one named export per story. The
-export's name is what the sidebar shows; its `args` are the component's props.
+export's name is the variant's label in the lab; its `args` are the component's props.
 
 ```ts
 // src/lab/components/Button.stories.ts
@@ -81,7 +93,13 @@ Then `npm run dev` and open **`http://localhost:4321/lab`**. `subpath` moves it;
 the stories.
 
 **Test versions** are published under the `next` tag while the redesign settles:
-`npm i -D @orbytes/astrolab@next`. `latest` stays on the last stable release until 1.0.
+`npm i -D -E @orbytes/astrolab@next`. `latest` stays on the last stable release until 1.0.
+
+**Upgrading from 0.3.** The mark-for-deletion feature (the cull) is removed, decided 2026-09-24.
+The `orbytes-lab-cull` command is gone, so delete any `lab:cull` script that calls it, and the
+`src/lab/cull.json` it kept. The `cullTier`, `cullDir` and `cullFile` options and a tier's
+`cullable` flag are no longer read: a config that still sets them builds, but they do nothing, and
+a typed config will flag them. Nothing else a 0.3 site configured changes meaning.
 
 **Peers.** Astro **7 or newer**, narrowed from `>=5.2.0` on 2026-09-22 when the pin board moved in:
 the board's dev-toolbar app imports `astro/client/dev-toolbar/apps/utils/highlight.js` and
@@ -192,7 +210,7 @@ This package is MIT too; see [LICENSE](./LICENSE).
 ### The chrome is not styled by the website
 
 **Decided 2026-09-22.** The lab's own furniture looks the same in every site it is installed in,
-and only the rendered story takes the site's styling. A site that wants a different-looking lab
+and only the rendered variant takes the site's styling. A site that wants a different-looking lab
 edits this package's source: there is no theme API and no token override, on purpose.
 
 So the chrome — both sidebar levels, the navbar, every view — is drawn by one stylesheet that ships
@@ -200,10 +218,10 @@ with this package, [`src/ui/lab.css`](./src/ui/lab.css), in `--lab-*` tokens tha
 a site's own, in Inter, with light and dark themes of its own. It never receives the `css` list or
 the `head` component.
 
-The **preview** — the bare story at `/lab/stories/<id>`, and the site's own pages — gets both,
+The **preview** — the bare variant at `/lab/stories/<id>`, and the site's own pages — gets both,
 because seeing a component as the real site renders it is the whole point. Since the redesign the
 chrome only ever shows a preview **inside an `<iframe>`**, so the two never share a document: no
-chrome page carries a byte of the site's CSS, and the chrome's stylesheet never reaches a story.
+chrome page carries a byte of the site's CSS, and the chrome's stylesheet never reaches a variant.
 The preview also keeps its **own** light/dark, separate from the chrome's.
 
 ## Options
@@ -214,14 +232,14 @@ Every option is optional.
 | --- | --- | --- |
 | `directory` | `"src/lab"` | Where the stories live, relative to the project root. |
 | `subpath` | `"/lab"` | Where the lab is served. `""` serves it at the site root. |
-| `css` | `[]` | The site's token and base stylesheets. They reach the story **previews** only, never the lab's own chrome. |
-| `head` | — | A path to the site's own head component, rendered inside every story preview's head. This is how fonts arrive: stories never render through the site's layout, so whatever that layout registers has to be repeated here. |
+| `css` | `[]` | The site's own token and base stylesheets, if you want the previews styled like the site (see [Install](#install)). They reach the variant **previews** only, never the lab's own chrome. |
+| `head` | — | A path to the site's own head component, rendered inside every variant preview's head. This is how fonts arrive: variants never render through the site's layout, so whatever that layout registers has to be repeated here. |
 | `title` | `"Component lab"` | The site's name as the lab shows it — the tab title and the home page. |
-| `stagingUrl` | — | The deployed lab's base URL — the real minified build, which a dev server is not. Every card and the story header link to the same story there. Omit it and those links do not appear. |
+| `stagingUrl` | — | The deployed lab's base URL — the real minified build, which a dev server is not. Every card and every component page link to the same variant there. Omit it and those links do not appear. |
 | `previewUrlTemplate` | — | A branch-preview URL with a `{branch}` placeholder, e.g. `"https://{branch}-my-site.workers.dev"`. The home page then lists the local git branches with a link each. Omit it and there is no branch list. It is a string, not a function, because the config crosses a virtual module and has to stay JSON-serialisable. |
 | `feedbucketKey` | — | Set it and every lab page carries the [Feedbucket](https://feedbucket.app) tag. The package takes a key or nothing: the consumer keeps its own staging gate, so pass the key only where the widget belongs. |
-| `tiers` | `["sections", "components", "explorations"]` | The tiers, in reading order. A tier is the first path segment under `directory`. A tier with no stories is left out of the menu. |
-| `viewports` | the orbytes scale | The viewport's screen sizes: `design` widths (the device switch), `breakpoints` (the band readout and the presets) and named `devices`. See [Viewports](#viewports). |
+| `tiers` | `["sections", "components", "explorations"]` | The tiers, in reading order. A tier is the first path segment under `directory`. A tier with no stories files is left out of the menu. |
+| `viewports` | the orbytes scale | The viewport's screen sizes: `design` widths (the device switch), `breakpoints` (the band the Viewport field names, and the presets) and named `devices`. See [Viewports](#viewports). |
 | `pin` | `true` | The pin board. `false` omits it entirely; an object is the board's own options — see below. |
 
 ### Tiers
@@ -233,18 +251,17 @@ what each one *is*:
 tiers: [
   { id: "pages", label: "Page sections", responsive: true },
   "atoms",
-  { id: "sketches", label: "Sketches", cullable: true },
+  { id: "sketches", label: "Sketches" },
 ]
 ```
 
-- **`responsive`** — this tier holds page sections. Its stories carry the responsive mark, and they
-  render at page width (1440×900) in thumbnails and as the viewport's default frame; everything
-  else renders on a component stage (960×540). Defaults to true for a tier named `sections`.
-- **`cullable`** — this tier's stories may be marked for deletion in the sidebar and removed by
-  `orbytes-lab-cull`. Nothing else can be: version history and shared chrome are never deleted from
-  a browser. Defaults to true for a tier named `explorations`.
+- **`responsive`** — this tier holds page sections, laid out `<tier>/<Section>/<Version>/`; the lab
+  reads the section and version from those folders whatever the tier is called. Its variants carry
+  the responsive mark, and they render at page width (1440×900) in thumbnails and as the viewport's
+  default frame; everything else renders on a component stage (960×540). Defaults to true for a
+  tier named `sections`.
 
-At most one tier holds each role.
+At most one tier holds the role.
 
 ### Viewports
 
@@ -265,25 +282,57 @@ the last one `0`; the presets offer both sides of every edge (1024 and 1023).
 ## What you get
 
 Two sidebar levels — the menu (Home; Site: Pages, one entry per tier, Assets; Tasks; Support and
-Settings) and a panel with a breadcrumb, a search box and a tree — and a main area with a navbar
-over the content.
+Settings), with the lab's own light/dark switch (a moon) beside the logo, and a panel with a
+breadcrumb, a search box and a tree — and a main area with a navbar over the content. The menu
+shrinks to a 64px icon rail, where the moon sits under the logomark and each group opens as a
+flyout under its own name. Kanban Board and All Tasks have no panel. The panel's tree has no icons
+and reads at 12px.
 
 **`<subpath>/`** — Home: counts for pages, each tier, assets and open tasks, and every page's
 mounted components in slot order — what is on the site right now.
 
 **`<subpath>/pages/<route>`** — the site's own pages, in a tree nested the way the routes nest, each
-shown on the viewport canvas at its real URL. `<subpath>/pages` lists them all.
+shown on the viewport canvas at its real URL. The navbar is the component page's, less the
+variants: the page's name and route, the eye (below), a menu of the components the page mounts, in
+slot order, and **Reload** and **Open page** beside the viewport controls. `<subpath>/pages` lists
+them all.
 
 **`<subpath>/browse/<tier>`** — a tier (Sections, Components, …): its components as cards with a live
-thumbnail and their pills, filterable by live / used / unused / responsive.
-
-**`<subpath>/dashboard/<story>`** — a component's page. The tree stops at the component; its stories
-are tabs (a dropdown past four), with previous/next buttons and `j`/`k` stepping through every story
-of the tier. The story renders on a **canvas**: pick a design width, type or drag the frame's size,
-rotate, pick a breakpoint edge or a device, zoom (Fit by default), and read the band. The viewport
-is in the URL (`?w=390&h=844&z=fit`), so a link names the exact frame. `[` `]` step the widths, `r`
-rotates, `f` fits, `0` is 100%. The pills open a **status menu** (where it is live, and the marks
-below); everything that leaves the lab (VS Code, full screen, staging, a link) is under ⋯.
+thumbnail, under a title bar with filter chips (All · Live · Used · Unused). A live component's card
+carries a green badge with its slot number; the others carry a *used by N* pill when something live
+uses them, and a section carries its responsive state. On the sections tier the panel's filter
+menu adds responsive state.
+
+On the sections tier the panel is the **Sections tree**: one row per section with a slot badge —
+green with its slot number, a grey dash when no page mounts it, violet on the row you are on. The
+mounted sections come first; the rest sit under *Unslotted · on no page*. **Sort by** switches
+between slot number and name (A–Z) and is remembered in this browser.
+
+**`<subpath>/dashboard/<story>`** — a component's page. The tree stops at the component, and the
+navbar carries the rest:
+
+- **The name, the version and an eye.** Hovering the eye opens the **Properties** panel: where the
+  component is live and in which slot (or what uses it, or *Not on any page*), its open and resolved
+  pins, the two responsive marks as checkboxes (sections only, see [Marks](#marks)) and its source
+  file. Clicking the eye keeps the panel open; Escape or a click elsewhere closes it.
+- **Variants** — always a dropdown ("Default 1 of 3"), whatever the count — and previous / next
+  buttons, with `j`/`k` stepping through every variant of the tier.
+- **The device switch and the Viewport field.** The switch picks a design width. The field is the
+  frame's width × height, typed in place, and a button naming the band and the zoom ("tablet Fit")
+  that opens the presets: Rotate, both sides of every breakpoint edge, the named devices and a zoom
+  row (Fit, 25–200%). Drag the frame's right edge, bottom edge or corner to resize it. Fit is the
+  default: it scales the frame to fit the stage in both directions, and never past 100%.
+- **Comment**, where the pin board runs — see [Pinning from the lab](#pinning-from-the-lab).
+- **Parameters**, only for a variant that registers some — see [Parameters panel](#parameters-panel).
+- **⋯** — everything that leaves the lab (Open in VS Code, open the bare variant full screen, view
+  on staging, copy a link to this exact size), then two sets of switches: **Pins** (Show pins, on;
+  Show resolved, off) and **Preview › Dark mode**, which appears only when the framed site has a
+  dark mode of its own and switches the preview, not the lab.
+
+The navbar is one row when it is 1040px wide or more, and two rows below that, the viewport row
+last. The viewport is in the URL (`?w=390&h=844&z=fit`), so a link names the exact frame, and it
+rides along when you step between variants. `[` `]` step the widths, `r` rotates, `f` fits, `0` is
+100%.
 
 **`<subpath>/assets`** — every image under `src/` and `public/`, its size and dimensions, and which
 files reference it, so "what does nothing use?" is a filter.
@@ -298,8 +347,24 @@ read this instead of globbing.
 component page, kept so old links still land.
 
 **Keys.** `⌘B` closes and opens the panel, `⌘⇧B` shrinks the menu to icons, `⌘.` does both,
-`⌘K` searches. With the panel closed, point at the canvas's left edge and the panel slides out over
-it without resizing the preview.
+`⌘K` searches. With the panel closed, point at the canvas's left edge and the panel slides out
+under the navbar, over the canvas, without resizing the preview.
+
+**Astro's dev toolbar is hidden inside the lab's frames**, so a lab page shows one toolbar: its
+own. The site's pages, and a bare variant opened in its own tab, keep theirs.
+
+### Pinning from the lab
+
+Where the pin board runs, **Comment** pins an element of the framed preview: click it, click the
+element, and the pin app on Astro's dev toolbar opens its composer. The pick is confined to the
+canvas, so it can never land on the lab's own chrome; Escape stops it. The button stays disabled
+until that toolbar app has started, because it is the one picker and composer the lab uses.
+
+Pins already left on the framed page are drawn over the frame at their elements, blue while open and
+grey once resolved; a pin whose selector finds nothing on the page, or more than one thing, is not
+drawn. Clicking a pin, or the pin row in the Properties panel, opens All Tasks. ⋯ › Pins decides
+what is drawn — Show pins (on) and Show resolved (off) — and the choice is remembered in this
+browser. On the site's own pages, outside the lab, pinning goes through the dev toolbar as before.
 
 **An unconditional `noindex`** on every lab page. Lab pages do not render through the site's
 layout, so they never inherit its staging `noindex` — this one is not gated on the environment, on
@@ -309,47 +374,26 @@ purpose. Keep your own build gate as well: two mechanisms, because the rule is a
 
 A component is live when a page under `src/pages/` imports it **and** mounts it as a tag. Every
 page is walked, the layout is excluded, and the slot is the component's position in that page's
-document order. Nothing is configured, so the pill cannot go stale.
+document order. Nothing is configured, so the slot badge cannot go stale.
 
 ## Marks
 
-Two JSON files under `directory`, both written by a **dev-only** API (`PUT /__lab/cull`,
-`PUT /__lab/responsive`) and both meant to be committed. Both are ticked in a component's **status
-menu** (its pills, in the navbar):
-
-- **`responsive.json`** — `{ done, approved }` per section version. Responsive work is
-  approval-gated and neither fact is readable from the code, so both are ticked by hand.
-- **`cull.json`** — `{ marked }`: stories in the cullable tier, marked for deletion.
-
-The API refuses anything outside the right tier, anything that is not a stories file on disk, and
-anything live or used by a live section — with the offender and the reason. In a build there is no
-dev server, so there is no write path at all and the boxes stay disabled.
-
-### `orbytes-lab-cull`
-
-The marks delete nothing. This binary does, and only when told to:
-
-```sh
-orbytes-lab-cull            # dry run — print the plan, remove nothing
-orbytes-lab-cull --json     # the same plan as JSON
-orbytes-lab-cull --yes      # perform it: `git rm` (staged, not committed)
-orbytes-lab-cull --dir=…    # when the lab is not at src/lab
-```
-
-It runs in the current working directory, so wire it as a script in the consumer:
+One JSON file under `directory`, **`responsive.json`**, written by a **dev-only** API
+(`PUT /__lab/responsive`) and meant to be committed. It holds `{ done, approved }` per section
+version, ticked in the component's **Properties** panel (the eye beside its name). Responsive work
+is approval-gated and neither fact is readable from the code, so both are ticked by hand.
 
-```json
-"scripts": { "lab:cull": "orbytes-lab-cull" }
-```
-
-It removes each marked stories file, the component it renders, and anything under the lab
-directory that only the removal set imports — then refuses the whole run if any entry is blocked.
+The API refuses anything outside the responsive tier and anything that is not a stories file on
+disk — with the offender and the reason. In a build there is no dev server, so there is no write
+path at all: the boxes stay disabled and show the state the page was built with.
 
 ## Parameters panel
 
 A component with something to tune declares it and renders no UI of its own. The panel is a drawer
-on the right of the component page's canvas, opened from the navbar's **Parameters** button, which
-exists only for a story that registered something — the bare story page shows nothing.
+over the right edge of the component page's canvas, opened from the navbar's **Parameters** button,
+which exists only for a variant that registered something — the bare variant page shows nothing.
+The drawer never resizes the canvas, because that would change the preview's width and trip its
+breakpoints; whether it is open, and which groups are collapsed, is remembered in this browser.
 
 ```ts
 import { registerLabParams } from "@orbytes/astrolab/params";
@@ -359,6 +403,7 @@ const panel = registerLabParams({
   title: "hero shader",
   controls: [
     { kind: "range", id: "speed", label: "Speed", min: 0, max: 4, step: 0.05, value: 1, unit: "×" },
+    { kind: "number", id: "headlineSize", label: "Headline size", value: 72, unit: "px" },
     { kind: "toggle", id: "grain", label: "Grain", value: true },
   ],
   apply(values) { /* push them into whatever they configure */ },
@@ -368,34 +413,88 @@ const values = panel.values;          // LIVE — mutated in place, safe to hold
 panel.status("WebGL2 · 0.8 ms/frame");
 ```
 
+The control kinds are `range` (a slider), `number` (below), `toggle`, `select` and `color`.
+
 `apply` is called once at registration with the restored values, so it must tolerate running before
 the thing it configures exists. Values persist per group in `localStorage`. Reset, Copy settings,
 the readouts and the collapse are the panel's job, not the component's.
 
-Exported types: `LabParamControl`, `LabParamGroup`, `LabParamHandle`, `LabParamValue`,
-`LabParamValues`, `LabParamEntry`.
+### Sizes are never sliders
+
+**Decided 2026-09-24.** A parameter that is a size — a font size, a tracking, a line height, a width,
+an offset, a radius — is `kind: "number"`: a field to type the value into, joined to a select of the
+units it can be expressed in. Sliders stay for unitless tuning values (speed, grain, scale,
+opacity).
+
+```ts
+{ kind: "number", id, label, value, unit, units?, step?, min?, max?, note? }
+```
+
+- `value` is the bare default number (`72`) and `unit` its default unit (`"px"`, or `""` for none).
+- `units` is what the select offers. It defaults to `LAB_UNITS.size` — px · rem · em · vw · vh · %.
+  `LAB_UNITS.tracking` (em · px) and `LAB_UNITS.lineHeight` (none · px) are there too, or pass a
+  list of your own; the default `unit` is added if the list lacks it.
+- `step` is what ↑ / ↓ add (1 by default); `min` and `max` bound typed and restored values alike.
+
+`apply` receives **one CSS-ready string** per number control, the number and the unit joined —
+`"72px"`, `"12.5rem"`, or `"1.05"` when the unit is `""` — so it drops straight into a style:
+
+```ts
+el.style.setProperty("--headline-size", String(values.headlineSize)); // "72px"
+```
+
+`parseLabLength("72px")` gives `{ value: 72, unit: "px" }` back when the number itself is wanted,
+and `null` for anything that is not one number and an optional unit. Changing the unit keeps the
+number and changes what it means: the panel never converts between units, because px → rem
+depends on a root size it cannot know. A size that used to be a `range` can become a `number`
+without losing its saved tuning — a stored bare number is read in the default unit.
+
+Exported from `@orbytes/astrolab/params`: `registerLabParams`, `LAB_UNITS`, `parseLabLength`,
+`formatLabLength` (its inverse), `labUnitsOf`, and the types `LabParamControl`, `LabParamGroup`,
+`LabParamHandle`, `LabParamValue`, `LabParamValues`, `LabParamEntry`.
 
 ## Tasks — the pin board at `/lab/tasks`
 
-Dev only, on by default, and it needs no configuration. Inside the lab it is two views in the lab's
-own chrome — **Kanban Board** at `<subpath>/tasks` and **All Tasks**, a sortable table, at
-`<subpath>/tasks/all` — with the statuses and their counts in the panel. `/pin`, its old address,
-redirects there. Everything it does is in [docs/PIN.md](./docs/PIN.md); what matters at the
-integration boundary is here.
+Dev only and on by default. Inside the lab it is two views in the lab's own chrome — **Kanban
+Board** at `<subpath>/tasks` and **All Tasks**, a sortable table, at `<subpath>/tasks/all` — with no
+panel beside them: the board's own chips filter by status. `/pin`, its old address, redirects there.
+Pinning from inside the lab is the navbar's Comment button ([Pinning from the
+lab](#pinning-from-the-lab)). Everything the board does is in [docs/PIN.md](./docs/PIN.md); what
+matters at the integration boundary is here.
+
+**It needs the site to be inside a git repository.** Every ticket path is stored relative to the
+repository root: the Astro project's folder, or the nearest one above it, that holds `.git`.
+With none, the board switches itself off for that run and says so only as a warning in the dev
+server's log; the lab is unaffected. Nothing on screen says why: `<subpath>/tasks`,
+`<subpath>/tasks/all` and `/pin` answer 404, the Tasks group and the Comment button are absent,
+there is no pin app on the dev toolbar and no source stamp. Run `git init` (then restart the dev
+server) to turn it on, or pass `pin: false` to silence the warning.
 
 ```js
 orbytesLab({
   css: ["./src/styles/global.css"],
   pin: {
-    stamp: ["src/lab/sections", "src/components"],  // site-relative
+    // site-relative; this adds the lab's components tier to the default
+    stamp: ["src/lab/sections", "src/lab/components", "src/components"],
     project: "acme-website",                        // the screenshot archive folder
   },
 })
 ```
 
+**Which files a pin can name.** A pin names the source file of the nearest element that carries a
+`data-orbytes-src` attribute, and `stamp` decides which `.astro` files get one. The default is
+`src/lab/sections` and `src/components` — **not** `src/lab/components` or `src/lab/explorations`,
+where the layout above puts components — so a pin on one of those, in its own variant, records
+its source as `unresolved` (its selector, screenshot and HTML are still in the ticket). Rendered
+inside a stamped section, the same component's pin names the section's file. Add the directories you
+want, as in the example: `stamp` replaces the default rather than adding to it, and it does not
+follow `directory` if you moved the stories. Before widening it, read the last bullet below: a
+template in a stamped folder with no element to stamp (its first top-level tag a component, say)
+throws, and needs a `stampSkip` entry.
+
 | Option | Default | What it does |
 | --- | --- | --- |
-| `stamp` | `["src/lab/sections", "src/components"]` | **Site-relative** directories whose `.astro` files get `data-orbytes-src`, so a pin can name the file it came from. |
+| `stamp` | `["src/lab/sections", "src/components"]` | **Site-relative** directories whose `.astro` files get `data-orbytes-src`, so a pin can name the file it came from. Replaces the default whole; see above for `src/lab/components`. |
 | `stampSkip` | `[]` | **Site-relative** `.astro` paths exempt from the stamp's hard failure. A repo-relative path is accepted too, for configs written before 2026-09-22. |
 | `backlogDir` | `"backlog"` | Repo-relative board directory: tickets in `tasks/`, PNGs in `assets/`. |
 | `archiveDir` | `~/.orbytes/feedback-archive` | Canonical screenshot home; the repo copy is a hardlink into it. |
@@ -430,8 +529,8 @@ orbytes-pin-gallery --backlog-dir feedback # when the site moved its board
 ```
 
 It renders from the same module the live board does and is read-only — a `file://` page has nothing
-listening behind it. It runs in the current working directory, like `orbytes-lab-cull`, so wire it
-as a script in the consumer:
+listening behind it. It runs in the current working directory, so wire it as a script in the
+consumer:
 
 ```json
 "scripts": { "pin:gallery": "orbytes-pin-gallery" }
@@ -442,7 +541,7 @@ as a script in the consumer:
 - **`decorators/`** — a decorator wraps a story in the page shell it will really live in. That
   shell is different in every build, so the package ships none: write your own against your own
   layout.
-- **`cull.json` / `responsive.json`** — data about your components, committed with them.
+- **`responsive.json`** — data about your components, committed with them.
 - **The build gate** — whether the lab is in this build is the consumer's decision, in the
   consumer's `astro.config.mjs`, and worth asserting with a check of your own.
 - **The head component** — fonts and anything else the site's layout registers.
@@ -450,6 +549,7 @@ as a script in the consumer:
 ## Notes
 
 - The `tags` a story declares (`export default { component, meta: { tags: [...] } }`) are read
-  through `import.meta.glob("/src/**/*.stories.ts")`, so a `directory` outside `src/` gets no tags.
+  from the stories file's text, not imported, so write them as string literals: a tag built at
+  runtime is not seen.
 - Editing the integration or its `.mjs` helpers is not picked up by the dev server's config-change
   restart — they stay in Node's ESM cache. Stop and start the server.

package/bin/pin-gallery.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 // pin-gallery — render every pin ticket as ONE standalone kanban on disk.
 //
-// The board itself lives at `/pin` on `astro dev` now, generated from `backlog/tasks/` on every
+// The board itself lives at `<subpath>/tasks` on `astro dev` now (`/lab/tasks` by default, or the
+// pin half's `route` when it runs without the lab), generated from `backlog/tasks/` on every
 // request, so looking at it is a refresh and this script is no longer part of that loop. What it
 // is still for is the file: a page that opens with no dev server running — on a plane, on another
 // machine, attached to a message — and a snapshot of the board at a moment in time.
@@ -15,15 +16,16 @@
 //   npx orbytes-pin-gallery                      # → backlog/gallery.html
 //   npx orbytes-pin-gallery --out x.html
 //   npx orbytes-pin-gallery --backlog-dir feedback   # a site that moved its board
+//   npx orbytes-pin-gallery --help                   # the usage; writes nothing
 //
-// IT RUNS IN THE CONSUMER'S REPO, NOT ITS OWN — the same rule as ./lab-cull.mjs, and for the same
-// reason. The root is walked up from `process.cwd()`, never from this file's location, which since
-// the merge into @orbytes/astrolab (2026-09-22) is somewhere under the consumer's node_modules and,
-// when the package is workspace-linked, resolves to THIS repo instead of theirs. A gallery of the
+// IT RUNS IN THE CONSUMER'S REPO, NOT ITS OWN. The root is walked up from `process.cwd()`, never
+// from this file's location, which since the merge into @orbytes/astrolab (2026-09-22) is somewhere
+// under the consumer's node_modules and, when the package is workspace-linked, resolves to THIS
+// repo instead of theirs. A gallery of the
 // lab's own (empty) backlog, written into the lab's own checkout, would exit 0 and look fine.
 //
 // EVERY line of the board — the parser, the cards, the columns, the CSS — comes from
-// `../src/pin/board.mjs`, which the `/pin` board renders with as well. Nothing about a ticket is read
+// `../src/pin/board.mjs`, which the live board renders with as well. Nothing about a ticket is read
 // or drawn here. That is the whole shape of this file, and it is not a preference: this script
 // carried its own copy of the parsing and rendering until 2026-09-21 and that copy produced three
 // separate bugs, each of them a drift from the package's own reader — a frontmatter parser that
@@ -32,19 +34,17 @@
 // A second implementation of this page would be the fourth. Add nothing here; add it to board.mjs.
 //
 // The page opens straight from file:// — image sources stay relative to the output file, so the
-// HTML stays a few KB and the (gitignored) PNGs are never inlined.
+// HTML stays a few KB and the PNGs are never inlined.
 
 import { existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
 
-// `../src/pin/board.mjs` and not the package root: the root pulls in the lab, which imports
-// TypeScript the consumer's Vite compiles and plain Node cannot. The board module is dependency-
-// free by design, and it does not reach shot.mjs — so a static HTML renderer needs no browser and
-// no bundler to run.
+// `../src/pin/board.mjs` and not the package root. The root does load in plain Node now — it
+// imports the compiled core in ../dist/core — but it brings the lab integration and that core
+// with it for a job that needs neither. The board module imports only node:fs and node:path, and it
+// does not reach shot.mjs — so a static HTML renderer needs no browser and no bundler to run.
 import { collectTickets, renderBoard, findRepoRoot } from "../src/pin/board.mjs";
 
-const REPO = findRepoRoot(process.cwd());
-
 /* -------------------------------------------------------------------- main */
 
 const args = process.argv.slice(2);
@@ -53,6 +53,41 @@ const flag = (name) => {
 	return at !== -1 && args[at + 1] ? args[at + 1] : null;
 };
 
+const USAGE = `Usage: orbytes-pin-gallery [--out <file>] [--backlog-dir <dir>]
+
+Writes every pin ticket in <repo>/<backlog-dir>/tasks/, cancelled ones included, as one read-only
+kanban page that opens with no dev server running. <repo> is the current directory or the nearest
+one above it that holds .git, so run it from inside the site's repo.
+
+  --out <file>          where to write the page, relative to the current directory
+                        (default: <repo>/<backlog-dir>/gallery.html)
+  --backlog-dir <dir>   the board directory, relative to <repo> (default: backlog)
+  -h, --help            print this and exit, writing nothing
+
+If any ticket cannot be read it writes nothing and exits 1.
+The live board is <subpath>/tasks on astro dev (/lab/tasks by default).`;
+
+// Every argument is accounted for, or the run is refused. Until 2026-09-24 nothing checked them:
+// a typo — `--output`, `--out=x.html`, `--help` itself — was ignored and the default gallery was
+// written anyway, exit 0, which reads exactly like the command having done what was asked.
+const VALUE_FLAGS = ["--out", "--backlog-dir"];
+for (let i = 0; i < args.length; i++) {
+	const arg = args[i];
+	if (arg === "--help" || arg === "-h") {
+		console.log(USAGE);
+		process.exit(0);
+	}
+	if (VALUE_FLAGS.includes(arg)) {
+		i++; // its value, read below by `flag()`
+		continue;
+	}
+	console.error(`pin-gallery: unknown argument ${JSON.stringify(arg)} — nothing was written.\n`);
+	console.error(USAGE);
+	process.exit(2);
+}
+
+const REPO = findRepoRoot(process.cwd());
+
 // The board directory, and the reason this flag exists at all.
 //
 // A binary cannot read the integration's options — it runs in a different process, from a shell,
@@ -67,7 +102,7 @@ const outPath = flag("--out")
 	? resolve(process.cwd(), flag("--out"))
 	: join(REPO, backlogDir, "gallery.html");
 
-// `includeCancelled`: this file is the offline twin of `/pin`, so it shows what `/pin` shows —
+// `includeCancelled`: this file is the offline twin of the live board, so it shows what that shows —
 // archive rail included. The default is the other way round precisely because every OTHER reader
 // is agent-facing, and a cancelled ticket must not reach an agent's context (ruled 2026-09-22).
 const { tickets, broken, paths } = collectTickets(REPO, { backlogDir, includeCancelled: true });
@@ -84,7 +119,7 @@ const { tickets, broken, paths } = collectTickets(REPO, { backlogDir, includeCan
 // on disk is left exactly as it was — stale, but the message below says so in as many words, which
 // is the difference between a stale file and a lie.
 //
-// The `/pin` board does the opposite and shows the panel instead, because a live page that refuses is a
+// The live board does the opposite and shows the panel instead, because a live page that refuses is a
 // blank screen with nothing to act on. A file that refuses is simply the file you already had.
 if (broken.length) {
 	console.error(`pin-gallery: refusing to write — ${broken.length} ticket(s) could not be read:`);
@@ -92,7 +127,7 @@ if (broken.length) {
 	console.error(`  ${tickets.length} readable ticket(s) were NOT written anywhere.`);
 	console.error(`  An agent reading the board hits the same wall: listTickets() throws on the first`);
 	console.error(`  of these and returns no tickets at all. Fix the ticket(s) and run again.`);
-	console.error(`  The /pin board lists them by name on the dev server, if it is running.`);
+	console.error(`  The live board (<subpath>/tasks, /lab/tasks by default) lists them by name on the dev server, if it is running.`);
 	if (existsSync(outPath)) {
 		const stamp = statSync(outPath).mtime.toLocaleString("en-AU", { dateStyle: "medium", timeStyle: "short" });
 		console.error(`  ${relative(REPO, outPath) || outPath} was left untouched (written ${stamp}) and is now out of date.`);
@@ -108,8 +143,7 @@ const assetHref = (t) => (t.shotAbs ? relative(outDir, t.shotAbs).split(sep).joi
 // The directory may not exist yet: on a fresh install `backlog/` is only created when the first
 // ticket is written, and this command can run before that — or be pointed somewhere else entirely
 // with `--out`. Measured 2026-09-22 on a clean project: without this the command died with a raw
-// `ENOENT ... open 'backlog/gallery.html'` stack trace. Its sibling `orbytes-lab-cull` already
-// handles the same case.
+// `ENOENT ... open 'backlog/gallery.html'` stack trace.
 mkdirSync(outDir, { recursive: true });
 writeFileSync(outPath, renderBoard(tickets, broken, { assetHref }), "utf8");
 
@@ -117,5 +151,5 @@ const missing = tickets.filter((t) => !assetHref(t)).length;
 console.log(`pin-gallery: ${tickets.length} ticket(s), ${missing} without a screenshot`);
 console.log(`  → ${relative(REPO, outPath) || outPath}`);
 console.log(`  read from ${relative(REPO, paths.tasks)}`);
-console.log(`  the live board is /pin on the dev server; this file is the read-only standalone copy`);
+console.log(`  the live board is <subpath>/tasks on the dev server (/lab/tasks by default); this file is the read-only standalone copy`);
 if (!existsSync(paths.assets)) console.log(`  note: ${relative(REPO, paths.assets)} does not exist yet`);