@palate/cli 0.0.0-stage → 0.0.1

package/kb/sections/closing-result-previewed.md

@@ -0,0 +1,88 @@
+---
+id: closing-result-previewed
+name: The result, previewed with the visitor's own input
+kind: closing
+shape: split
+layout: "one input for the visitor's own thing (their name, URL, file, sentence) on the left; on the right the product's result rendered with it, live; the action keeps what they made"
+fits: [saas, ai, consumer, productivity, crafted, friendly, playful, developer, launch, waitlist, education]
+avoid: [enterprise-compliance, government, clinical, crisis, finance-trust-first, food, portfolio]
+needs: ["a result the product can preview client-side (or cheaply server-side) from one small input", "a sensible default input so the preview is never empty", "a signup or start action that carries the input forward"]
+imagery: product-ui
+density: balanced
+effort: l
+---
+
+## When it's right
+
+The last section should give the visitor something new, not the hero's form again. The most persuasive new thing is their own result: type your shop name and see the storefront header with it; paste your repo URL and see the badge; write one sentence and see it set in the type system. The primary action then keeps what they made ("Save this and continue"). Use when the product's output can be previewed from a tiny input in under a second. Not when the real result needs an account, private data or minutes of work; use `closing-demo-final-state` instead.
+
+## Structure
+
+```
+1440 ─ container 1200
+┌──────────────────────────────────────────────────────────────────────────┐
+│ ┌ cols 1–5 ───────────────────────┐ ┌ cols 6–12 ─────────────────────────┐ │
+│ │ H2 "Try it with yours"          │ │ ┌ preview, product scale ─────────┐ │ │
+│ │ one line on what you'll see     │ │ │                                 │ │ │
+│ │                                 │ │ │   Marlow Ceramics               │ │ │  ← the visitor's input, rendered
+│ │ Your shop's name                │ │ │   ───────────                   │ │ │     the way the product would
+│ │ [ Marlow Ceramics          ]    │ │ │   [ product tiles … ]           │ │ │
+│ │ try: Fernhill · Kiln & Co       │ │ │                                 │ │ │  ← quick sample chips
+│ │                                 │ │ └─────────────────────────────────┘ │ │
+│ │ [ Keep this storefront → ]      │ │  Preview. The real one takes ~2 min │ │
+│ │ Free; we'll carry your name in. │ │                                     │ │
+│ └─────────────────────────────────┘ └─────────────────────────────────────┘ │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+```
+390 ─ one column
+H2, line
+input (full width) + sample chips
+preview (full width, product scale, cropped to the top of the result)
+primary button full width, reassurance line
+```
+
+At 390 the input comes first (the keyboard opens without covering the preview's top, since the preview sits directly under the input). The preview crops to the region where the input appears.
+
+## Finish
+
+- The preview is the raised object (`--shadow-2` (raised, `_finish.md`), `--r-lg`) and takes 7 of 12 columns; the left column carries no box.
+- Input: the page's input recipe at large size (48–56px tall, lead size (`--t-lead`) text), label above, visible focus ring. Sample chips under it in small type, as buttons, to show the effect without typing.
+- Preview built in HTML with the product's own rendering, readable at 100%. The visitor's text appears in it exactly as the product would set it (real fonts, wrapping, truncation).
+- A small secondary caption under the preview says what is preview and what is real.
+- One primary button (the page's `.btn-primary`), label says what is kept ("Keep this storefront"). Its destination carries the input as a query value or in session storage, never personal data in the URL beyond what they typed for the preview (no emails).
+- Section stands apart from the hero: different shape (split vs the hero's), and if the hero used a form, this one's button and copy are different.
+
+## Content
+
+- One input only. The input is about their thing (shop name, repo, sentence, photo), never their email.
+- The default value is a realistic example so the preview is never empty on load.
+- Copy says what happens next in one line ("Free; we'll carry your name in").
+- The preview never claims to be the final result if it isn't; label it.
+
+## States and motion
+
+- Preview updates on input (debounced 150ms for text, immediately for chips); changed parts crossfade 150ms, layout never jumps. Reduced motion: instant swap.
+- Empty input: the preview shows the placeholder example in tertiary colour with "Type yours" in the input; never a blank preview.
+- Very long input: the preview truncates or wraps exactly as the product does; the section height stays fixed.
+- Error (unsupported URL, file too big): a one-line message under the input with the fix (M39); preview keeps the last good state.
+- Live region announces "Preview updated" politely, debounced.
+- No-JS: static preview of the example; the button still works.
+
+## Pitfalls
+
+- Repeating the hero's email form here: nothing new at the end.
+- A preview that needs a network round trip of seconds; it should feel instant.
+- Asking for an email to see the preview.
+- A preview that looks better than the real product will deliver.
+
+## Floor checks
+
+- Does the section show a result built from something the visitor can type or pick, rather than repeating the hero's form?
+- Is the preview filled with a realistic example before any input?
+- Is there exactly one primary action, and does its label say what the visitor keeps?
+- Is the input labelled, large and clearly the place to start?
+- Is the preview readable at product scale (not a thumbnail)?
+- Is it clear what is a preview and what the real result will be?
+- At 390, are the input and the top of the preview visible together?

package/kb/sections/closing-three-real-steps.md

@@ -0,0 +1,87 @@
+---
+id: closing-three-real-steps
+name: Start in three real steps, shown happening
+kind: closing
+shape: timeline
+layout: "the three actual steps from nothing to a first result, left to right, each with the real artefact (the command, the click, the result) playing in sequence; the first step is the action"
+fits: [developer, saas, ai, productivity, technical, honest, friendly, education, b2b]
+avoid: [luxury, fashion, artsy, crisis, cinematic, food, portfolio]
+needs: ["a real onboarding path of three steps or fewer to a first result", "the real artefact of each step (a command, a screen, a URL)", "a median time to the first result, measured"]
+imagery: product-ui
+density: balanced
+moves: [copy-confirmation, first-win-onboarding]
+effort: m
+---
+
+## When it's right
+
+The visitor's last doubt is effort: "how long until this works for me?". The answer is the real path, shown: install, connect, see it working, three steps that actually play out on the page, with the first step being the action itself (a copyable command, a sign-in button). It follows the move `first-win-onboarding`: only use it if the product's real path is three steps or fewer; if it's twelve, fix onboarding first. Not to be confused with a features "how it works" row (M22): this is the start, and it's live.
+
+## Structure
+
+```
+1440 ─ container 1200, three equal columns joined by a progress line
+┌──────────────────────────────────────────────────────────────────────────┐
+│ H2 "Live in about two minutes"                                           │
+│ median time from signup to first preview, Sep 2026                       │
+│                                                                          │
+│ ①━━━━━━━━━━━━━━━━━━━━━━━━━②━━━━━━━━━━━━━━━━━━━━━━━━━③                     │  ← line fills as each step plays
+│ Install                    Connect your repo         See your preview    │
+│ ┌──────────────────────┐   ┌──────────────────────┐  ┌──────────────────┐ │
+│ │ $ npx acme init   [⧉]│   │ [GitHub] marlow/shop │  │ ✓ preview ready  │ │  ← real artefacts, product scale
+│ │ ✓ created acme.json  │   │ ✓ connected          │  │ marlow-pr-12.acme│ │
+│ └──────────────────────┘   └──────────────────────┘  └──────────────────┘ │
+│ 20 s                       30 s                      about 1 min          │
+│                                                                          │
+│ [ Copy the command ]  or  Sign up with GitHub →                          │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+```
+390 ─ vertical timeline
+① Install       (line runs down the left, 24px from the edge)
+  [ command block, full width, copy button ]
+② Connect your repo
+  [ artefact ]
+③ See your preview
+  [ artefact ]
+primary button full width
+```
+
+At 390 the steps stack along a vertical line on the left; each artefact is full content width. Times sit beside the step titles.
+
+## Finish
+
+- Step markers: 24–28px circles with real numbers (these are a real sequence, so numbering is right; M17), outline in `--hairline`, filled with the accent once that step has played. The connecting line 2px, `--hairline`, filling with the accent left to right (transform: scaleX).
+- Step titles body size 600; times small secondary `tabular-nums`, under the artefact.
+- Artefacts: product-scale fragments built in HTML (terminal block in mono because it is code, the repo picker in the product's UI), `--r-sm`, `--shadow-1` or just a hairline outline from `_finish.md`. All three the same height so the row reads as one sequence (P04).
+- The command block has a copy button with confirmation (see `copy-confirmation`).
+- One primary action under the row: the first step itself ("Copy the command" or "Sign up with GitHub"), as the page's `.btn-primary`.
+
+## Content
+
+- The steps are the product's actual first-run steps, in their real words and commands. Each time is measured (median), or omitted.
+- The header's time claim comes from measurement with its period stated.
+- Step three ends on a result, not on "you're all set".
+
+## States and motion
+
+- On entering view, the steps play in order once: each artefact shows its "doing" state for 600ms then its done state, the line fills to the next marker (400ms), total under 3s. Reduced motion and no-JS: all three in their done state, line full.
+- Doesn't loop. A small "Replay" text button appears after it finishes.
+- Copy button: copied state 1.5s with a check; works by keyboard.
+
+## Pitfalls
+
+- Four or five steps with paragraphs: that's documentation (M22).
+- Fake steps that hide real setup (billing, team invites) behind the third.
+- Decorative numbers on things that aren't a sequence.
+- A spinner loop that never finishes.
+
+## Floor checks
+
+- Are there three steps or fewer, each showing a real artefact (command, screen, result) rather than an icon and paragraph?
+- Does the last step end on a visible result?
+- Is the first step actionable right there (a copy button or a sign-in action)?
+- Is there one primary call to action?
+- Are the step artefacts the same height and aligned in a row (or a clean vertical line at 390)?
+- Is any time claim accompanied by how it was measured?

package/kb/sections/command-reference-table.md

@@ -0,0 +1,70 @@
+---
+id: command-reference-table
+name: Command reference, grouped and ruled
+kind: docs
+shape: table
+layout: "every command or API call in a ruled table, grouped by what people use it for (start, build, finish, taste); the command in mono on the left, one plain sentence on the right, a filter box above, and an anchor per row"
+fits: [docs, developer, technical, data-dense-tool, productivity, ai, saas, honest, calm]
+avoid: [cinematic, luxury, fashion, kids, playful]
+needs: ["every public command with its arguments", "one sentence each on what it does, in plain words", "the groups people think in"]
+imagery: none
+density: dense
+effort: s
+---
+
+## When it's right
+
+When a product has more than eight commands, tools or endpoints and people come back to look one up. A ruled table is the fastest thing to scan; groups let a new reader see the shape, and the filter gets a returning one to their row. Not for three commands (show them in the guide) or for full API docs with parameters and responses (one page per endpoint).
+
+## Structure
+
+```
+reading column or wider (the table may use cols 4–12)
+[ Filter commands…                    ]                      42 commands
+Start
+──────────────────────────────────────────────────────────────────────────
+acme plan "<request>"            What the request deserves, and why        #
+acme activate <code>             Activate on this machine, once            #
+Build
+──────────────────────────────────────────────────────────────────────────
+...
+```
+
+```
+390 ─ each row stacks: the command (mono, wraps), the sentence under it
+```
+
+## Finish
+
+- Group labels: small, 600, secondary, sentence case, 32px above.
+- Rows: 1px hairlines, 12–14px vertical padding; command column mono 13–14px in ink, wrapping at spaces, never truncated; description body small in secondary-to-ink.
+- Filter: a quiet input (the site's input style), filters as you type over command and description, shows "No commands match "xyz"" with a clear button when empty; `/` focuses it.
+- If the same commands exist as agent tools (MCP), a second column or a toggle shows the tool name; don't make two tables.
+
+## Content
+
+- Arguments in angle brackets, options in square brackets, exactly as the help prints them.
+- One sentence per row, starting with a verb or what it returns; no marketing.
+- Group by the user's job, not alphabetically.
+
+## States and motion
+
+- Filtering hides rows instantly; group labels with no rows hide too.
+- Empty filter result with a way back.
+- Each row has an id; hovering shows a `#` link.
+- No JS: the full table, no filter box.
+
+## Pitfalls
+
+- Truncated commands with ellipses.
+- A table in cards on a phone that loses the grouping.
+- Descriptions copied from code comments that only the authors understand.
+- Mono for the descriptions too.
+
+## Floor checks
+
+- Is every command shown in full, never truncated?
+- Are commands grouped by job, with group labels?
+- Can the table be filtered, with an honest empty result?
+- Is each row one plain sentence that says what the command does?
+- At 390, do rows stack without horizontal scrolling?

package/kb/sections/comparison-old-way-bars.md

@@ -0,0 +1,88 @@
+---
+id: comparison-old-way-bars
+name: Against the old way, drawn as bars
+kind: comparison
+shape: table
+layout: "a real table comparing the product with the way people do the job today (by hand, with spreadsheets), 3–6 measured rows, each value drawn as a bar so the gap is seen, with the difference called out at the row's end"
+fits: [saas, developer, b2b, technical, productivity, honest, data-rich, ai, finance, scientific]
+avoid: [luxury, calm, playful-kids, enterprise-compliance, artsy]
+needs: ["3–6 measurable differences (time, cost, steps, errors) with real numbers", "a source line: sample, period, method", "a named process to compare against, not a named competitor unless legal approved"]
+imagery: none
+density: balanced
+moves: [animated-comparison-table]
+effort: m
+---
+
+## When it's right
+
+The product's case is a measurable gap against the current way of working: minutes to seconds, twelve steps to two, five tools to one. A table of ticks hides magnitude; bars show it. Implements the move `animated-comparison-table` as a section. Compare against a process ("By hand", "With spreadsheets"), which is honest and avoids trademark trouble. Not for tick-box feature lists (use `pricing-comparison-table-sticky`) or numbers without a source.
+
+## Structure
+
+```
+1440 ─ container 1200
+┌──────────────────────────────────────────────────────────────────────────┐
+│ H2 "The same release, two ways"                [ per release | per month ]│
+│ ┌───────────────┬──────────────────────────────────────────┬───────────┐ │
+│ │               │ By hand          With Acme               │           │ │  ← column heads
+│ ├───────────────┼──────────────────────────────────────────┼───────────┤ │
+│ │ Time to ship  │ ████████████████████████████ 3 h 10 min   │           │ │
+│ │               │ ██ 9 min                                  │  21× less │ │  ← difference callout
+│ ├───────────────┼──────────────────────────────────────────┼───────────┤ │
+│ │ Manual steps  │ ██████████████████████ 14                 │           │ │
+│ │               │ ███ 2                                     │  −12      │ │
+│ ├───────────────┼──────────────────────────────────────────┼───────────┤ │
+│ │ Rollbacks/qtr │ ██████████ 6                              │           │ │
+│ │ (fewer=better)│ █ 1                                       │  −5       │ │
+│ └───────────────┴──────────────────────────────────────────┴───────────┘ │
+│ Median of 1,240 releases by 38 teams, Jul–Sep 2026. Method →             │  ← source line
+└──────────────────────────────────────────────────────────────────────────┘
+cols: measure 1–3 | bars 4–10 | difference 11–12
+```
+
+```
+390 ─ one card-like row per measure (still table semantics)
+Time to ship                      21× less
+By hand   ██████████████ 3 h 10 min
+Acme      █ 9 min
+──────────
+```
+
+At 390 each measure becomes a block: measure name and difference on one line, then the two bars full width with labels. Table rows restyled with `display: grid`; semantics unchanged.
+
+## Finish
+
+- Semantic `<table>` with caption, `th scope`. Rows 72–88px with two stacked bars per row, 12–16px tall each, 8px apart; hairlines between rows (`_finish.md`).
+- Bars: old way in a neutral (`--hairline-strong`), the product in the accent; same scale per row starting at zero (`scaleX(value/rowMax)`), `--r-sm` on the bar's end only. Values in small-to-body `tabular-nums` right after each bar.
+- Difference column: h3 size, weight 600, accent or primary colour, right-aligned. The only large text in the table.
+- "Fewer is better" rows labelled in small secondary under the measure name.
+- Toggle (optional): a radio-group segmented control, top right on the heading's baseline.
+- Source line: small secondary, with a link to the method.
+
+## Content
+
+- Every number real, same unit per row, from benchmarks or customer data; the source line states sample, period and method.
+- Name the old way as a process people recognise. Name a competitor only with approved data.
+- 3–6 rows, strongest first. Don't include a row where the product loses unless you're happy to say why (that honesty builds trust).
+
+## States and motion
+
+- Bars grow once when each row enters view: old way first, then the product, staggered 80ms, 700ms `cubic-bezier(.23,1,.32,1)`; the difference fades in 200ms after. Reduced motion and no-JS: full bars from the start (CSS default).
+- Toggle recomputes values and animates bars between lengths.
+- Every value is text; bars are `aria-hidden`.
+
+## Pitfalls
+
+- Axes not starting at zero, or different scales per bar in one row.
+- Ticks and bars mixed in one table.
+- Values hidden until the animation runs.
+- A competitor's name with unverifiable numbers.
+
+## Floor checks
+
+- Can you see the size of the difference from the bar lengths without reading the numbers?
+- Does every bar have its value written next to it?
+- Is there a source line saying where the numbers come from?
+- Is the product's bar visually distinct (accent) from the old way's bar (neutral)?
+- Is the difference called out per row in one short figure?
+- At 390, are both bars of each measure visible and labelled without sideways scrolling?

package/kb/sections/comparison-same-task-two-ways.md

@@ -0,0 +1,88 @@
+---
+id: comparison-same-task-two-ways
+name: The same task, done two ways, side by side
+kind: comparison
+shape: split
+layout: "one real task shown twice in two equal panes: the old way on the left (its steps, its mess, its result) and the product on the right (its steps, its result), with a step count and time under each"
+fits: [saas, productivity, ai, developer, crafted, honest, friendly, consumer, education, b2b]
+avoid: [luxury, enterprise-compliance, crisis, clinical, food, portfolio]
+needs: ["one concrete task both ways can do", "the real steps of each way (the old way's honestly, not exaggerated)", "the result of each, buildable in HTML or as real images"]
+imagery: product-ui
+density: balanced
+moves: [before-after-slider]
+effort: l
+---
+
+## When it's right
+
+The difference is qualitative as much as quantitative: the result is better, not only faster. Show one real task (rename 400 files, write the release note, plan a week of meals) done the old way and with the product, side by side, ending on both results. The visitor judges for themselves. Pairs with the move `before-after-slider` when the task is visual (a photo edit, a design fix): then the two panes collapse into one image with a slider. Not when the gap is only numeric (use `comparison-old-way-bars`).
+
+## Structure
+
+```
+1440 ─ container 1200, two equal panes with a 24 gutter
+┌──────────────────────────────────────────────────────────────────────────┐
+│ H2 "Write this week's release note"                                      │
+│ ┌ The usual way (cols 1–6) ────────────┐ ┌ With Acme (cols 7–12) ───────┐ │
+│ │ 1 Open 23 merged PRs                 │ │ 1 Click "Draft release note" │ │
+│ │ 2 Copy titles into a doc             │ │ 2 Edit two lines             │ │
+│ │ 3 Rewrite for customers              │ │                              │ │
+│ │ 4 Ask PMs what shipped               │ │                              │ │
+│ │ 5 Format, post                       │ │                              │ │
+│ │ ┌ result ─────────────────────────┐  │ │ ┌ result ───────────────────┐│ │  ← results share a baseline
+│ │ │ the real note, a bit uneven     │  │ │ │ the real note, grouped,   ││ │
+│ │ └─────────────────────────────────┘  │ │ │ linked, readable          ││ │
+│ │ 5 steps · about 2 hours              │ │ └───────────────────────────┘│ │
+│ └──────────────────────────────────────┘ │ 2 steps · 4 minutes          │ │
+│                                          └──────────────────────────────┘ │
+│ Timed with our own team's release, 14 Oct 2026.        [ Try it on yours ]│
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+```
+390 ─ segmented switch between the two panes
+[ The usual way | With Acme ]
+steps list
+result
+step count · time
+source line, button
+```
+
+At 390 the two panes become one pane with a two-option segmented control; the default is "With Acme", and the summary line under the switch keeps both numbers visible ("5 steps · 2 h → 2 steps · 4 min").
+
+## Finish
+
+- Two equal panes, the same height; results aligned on a shared top line (P04). The old-way pane on a muted surface (one step darker or desaturated), the product pane on the page surface with `--shadow-1` (resting, `_finish.md`). No red/green colouring.
+- Steps: a real ordered list (numbers are right here), body-small, 8px apart; the old way's steps in secondary colour.
+- Results: built in HTML at product scale, readable at 100%; the old way's result is honest (what people really produce, not a strawman).
+- Step count and time under each pane: body 600, `tabular-nums`.
+- Source line small secondary; one primary button on the same row, right side ("Try it on yours"), the page's `.btn-primary`.
+
+## Content
+
+- One concrete task, named in the heading as the task itself ("Write this week's release note").
+- The old way's steps are what people actually do, checked with a few real users. Exaggeration loses trust.
+- Times are measured, with when and by whom.
+
+## States and motion
+
+- Optional: when the section enters view, both panes play their steps at true relative speed in a compressed loop (the product finishes first and shows its result while the old way is still on step 3). Plays once; reduced motion shows both finished.
+- Segmented control at 390 slides its indicator; panes crossfade 150ms.
+- Results are real text or images with alt text.
+
+## Pitfalls
+
+- A strawman old way (dramatic chaos) that no one recognises.
+- Results that differ in content, not quality, so the comparison is unfair.
+- Red crosses on the left, green ticks on the right.
+- Two panes of different heights with results at different heights.
+
+## Floor checks
+
+- Is the same task shown both ways, side by side, ending in a visible result for each?
+- Do the two panes have the same size, with their results aligned?
+- Are the step count and time shown under each way?
+- Is the old way shown plainly (muted, not a red-and-crosses strawman)?
+- Is there a line saying how the times were measured?
+- Is there one primary action that lets the visitor try it on their own task?
+- At 390, can you switch between the two ways while still seeing both totals?

package/kb/sections/day-of-the-place.md

@@ -0,0 +1,102 @@
+---
+id: day-of-the-place
+name: The day of the place, told by the clock
+kind: story
+shape: timeline
+layout: "4–6 moments of the place's real day in order, each a photograph taken at that hour with the time set large in type and one sentence; laid as a run of pictures along the page at 1440 and a vertical sequence on phone"
+fits: [food, local, crafted, warm, community, heritage, honest, cinematic]
+avoid: [saas, developer, b2b, enterprise-compliance, data-dense-tool]
+needs: ["4–6 real photographs of the place at different hours (the dough at 3 am, the queue at 8)", "the real time of each moment", "one true sentence per moment"]
+imagery: photo
+density: balanced
+effort: m
+moves: [time-of-day-theming, story-led-long-scroll]
+---
+
+## When it's right
+
+The place's care shows in its routine. A bakery that starts mixing at 3 am, lights the ovens at 6, opens at 8, sells out by 1 and gives the rest to the community larder at close; a restaurant whose hearth is lit at 2 pm for a 5 pm service; an inn's morning from the first kettle to the kayaks on the lawn. Told by the clock with real photographs, the day explains the product (why it sells out, why pre-order closes Thursday) and makes the visitor feel they've stood in the room.
+
+It is a story section, not a "how it works". Not when the photographs don't exist (don't stage a day with stock), not for a process the customer drives (use `how-it-works-in-place`), and never as numbered step cards.
+
+## Structure
+
+```
+1440 ─ container 1240; a run of 5 photographs at 4:5, the active one wider
+┌──────────────────────────────────────────────────────────────────────────────────────────┐
+│ H2 "A Saturday at Mabel's"                     one line: “Everything is baked here, …”   │
+│                                                                                          │
+│ 3:00 am        6:00 am        8:00 am         1:00 pm        5:00 pm                     │ ← times in display type,
+│ ┌──────────┐   ┌──────────┐   ┌──────────┐    ┌──────────┐   ┌──────────┐                │   --t-h2, tabular
+│ │ dough on │   │ ovens,   │   │ the door,│    │ empty    │   │ crates   │                │
+│ │ the bench│   │ first    │   │ the queue│    │ trays    │   │ to the   │                │
+│ │  4:5     │   │ trays    │   │ outside  │    │          │   │ larder   │                │
+│ └──────────┘   └──────────┘   └──────────┘    └──────────┘   └──────────┘                │
+│ Mixing starts  The ovens      Doors open.     Sold out,      What's left goes            │
+│ in the dark.   take 40 trays. Pre-orders at   most Saturdays. to the Leith                │
+│                               the window.                    Community Larder.           │
+│ ─────────●──────────────●──────────────●───────────────●──────────────●───────────────── │ ← optional thin rule
+└──────────────────────────────────────────────────────────────────────────────────────────┘   with the hour marks
+  each column ~220 wide, gap --s-5; photos share one height; sentence max 2 lines
+```
+
+```
+390 ─ vertical: time, photo, sentence, repeated
+┌──────────────────────────────┐
+│ H2 "A Saturday at Mabel's"   │
+│                              │
+│ 3:00 am                      │  ← time in display type
+│ ┌──────────────────────────┐ │
+│ │ photo, 4:5               │ │
+│ └──────────────────────────┘ │
+│ Mixing starts in the dark.   │
+│                              │
+│ 6:00 am                      │
+│ ┌ photo ───────────────────┐ │
+│ …                            │
+└──────────────────────────────┘
+```
+
+At 390 the day runs down the page: time, photograph (4:5, full width minus 32px), sentence, then `--s-8` to the next hour. Keep to 4–5 moments on phone so the section stays under about 3.5 screens; a sideways snap strip is acceptable only if each frame shows the next one peeking 24px.
+
+## Finish
+
+- Photographs: one treatment for all (`_finish.md`), same aspect and height, no frames or shadows; they sit on the ground like prints laid in a row. Real light of the hour is the point, so tone-match gently rather than flatten the night shots.
+- Times: the display face at `--t-h2`, `tabular-nums`, weight to suit the face; "am"/"pm" in `--t-small` small caps. The time is the heading of each moment; no numbers in circles, no icons.
+- Sentences: `--t-body`, `--ink`, max two lines, `text-wrap: pretty`. Any detail (flour from the Borders) in `--t-small` `--ink-2` under it.
+- Optional rule: a 1px `--hairline-strong` under the row with a small tick at each moment, like marks on a clock face. Never a progress bar that fills.
+- Ground: one change for the section; pairs with move `time-of-day-theming` if the page already shifts tone with the hour (a darker ground for the night moments is allowed, a gradient across the whole band is not).
+- Credit line for the photographer in `--t-caption` under the run.
+
+## Content
+
+- The real day: times the place actually keeps (from the README or the owner), moments a regular would recognise.
+- One sentence each, in the owner's voice, concrete: "The ovens take 40 trays at a time." Not "Passion in every bake."
+- End on the moment that says something about the place (leftovers to the larder, the hearth banked for tomorrow).
+- Link at most once, to the thing the day explains ("Pre-order by Thursday 9 pm →").
+
+## States and motion
+
+- Static by default; all moments visible in a screenshot.
+- Optional with move `story-led-long-scroll`: on a long page the run can pin and advance one moment per scroll step at 1440 only; reduced motion and phone get the plain sequence.
+- Photos lazy-load with the average colour placeholder; the first two are eager if the section is near the fold.
+- No auto-advancing slideshow.
+
+## Pitfalls
+
+- Numbered step cards with icons ("1 Mix · 2 Bake · 3 Sell") and a progress track: a SaaS process, not a morning.
+- A status track with coloured pills ("Baking", "Ready", "Sold out") that looks like an order tracker.
+- Stock photos of bread from somewhere else, or one photo reused with different captions.
+- Times with no meaning ("Morning", "Later").
+- Long paragraphs under each picture.
+- A horizontal strip at 390 that scrolls the page instead of its own row.
+
+## Floor checks
+
+- Does each moment show a real photograph of the place at that hour?
+- Is each moment headed by an actual clock time set in type, in order through the day?
+- Is each moment told in one or two short sentences?
+- Is the section free of numbered step cards, icons in circles and status pills?
+- Do the photographs share one aspect ratio and one treatment?
+- Does the last moment say something specific about the place rather than a slogan?
+- At 390, does the day run vertically (or in a contained strip) with readable photos and nothing scrolling the page sideways?

package/kb/sections/docs-reading-rail.md

@@ -0,0 +1,88 @@
+---
+id: docs-reading-rail
+name: Docs page with a reading rail
+kind: docs
+shape: split
+layout: "the page head (title, one line, a small bar to take the page to an agent: copy as Markdown, the .md link, llms.txt) above a sticky contents rail on the left and one reading column on the right; every heading anchored"
+fits: [docs, developer, technical, calm, honest, trustworthy, saas, ai, productivity, education, minimal, quiet]
+avoid: [cinematic, experimental, luxury, fashion]
+needs: ["the real sections of the docs, in the order a new user needs them", "the same content as Markdown, served at the page's URL + .md", "the product's own header and footer"]
+imagery: type
+density: balanced
+effort: m
+---
+
+## When it's right
+
+A single docs page (or a short guide) that people read top to bottom once and come back to for one answer. The rail shows the whole shape of the page and gets a returning reader to their answer in one click; the reading column keeps lines short. Modern docs are read by agents as much as by people, so the same content is served as clean Markdown and the page says so in its head. Not for a docs site of fifty pages (that needs a sidebar of pages and search, not a rail of headings).
+
+## Structure
+
+```
+1440 ─ container 1200, the site's own header above
+┌──────────────────────────────────────────────────────────────────────────┐
+│ Docs                                                                     │  ← small label, the site's accent
+│ H1 "Get started with Acme"                                               │
+│ One line: what this page covers and who it's for.                        │
+│ [Copy page as Markdown]  View as .md  ·  llms.txt  ·  Updated 7 Nov 2026 │  ← the agent bar, quiet
+│ ──────────────────────────────────────────────────────────────────────── │
+│ ┌ cols 1–3 (sticky) ┐  ┌ cols 4–10 (reading column, 68ch) ──────────┐   │
+│ │ On this page      │  │ ## Install                          #      │   │
+│ │ • Install         │  │ ...                                         │   │
+│ │   What it does    │  │ ## What it does                     #      │   │
+│ │   Commands        │  │ ...                                         │   │
+│ │   FAQ             │  │                                             │   │
+│ └───────────────────┘  └─────────────────────────────────────────────┘   │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+```
+390 ─ one column
+label, H1, line
+agent bar (wraps; the copy button full width)
+"On this page" as a closed <details> under the head
+the reading column
+```
+
+At 390 the rail becomes a collapsible contents list under the head; it never floats over the text.
+
+## Finish
+
+- The head sits on the page ground with the site's own type: H1 at the site's H1 size or one step down, the line at lead size, 60ch.
+- The agent bar: one secondary button (Copy page as Markdown, with a copied state that says "Copied" for 2s) and text links (`.md`, `llms.txt`), small size, secondary colour; a hairline under the head.
+- Rail: `position: sticky; top` below the header; small size; the current section in ink with a 2px accent bar, the rest secondary; hover moves to ink. Scrollspy with IntersectionObserver, no scroll listeners.
+- Reading column: body 16–17px, line-height 1.6, max 68ch; H2 at the site's H2 step down, 64px above, 16px below; H3 20px. A `#` link appears on hover and focus beside every heading (copies the URL).
+- Code: inline code in the mono face on a faint tint; blocks with a copy button, no line numbers for commands, the language named only when it helps.
+- Use the site's own header, footer, buttons and tokens. The docs page is part of the site, not a template dropped in.
+
+## Content
+
+- The order a new user needs: what it is (one paragraph), install, first success, what it can do, reference, questions.
+- Every step is copyable and complete: no "replace X" without saying where X comes from.
+- Dates and versions are real ("Updated 7 Nov 2026", "palate 0.9"), never placeholders.
+- The Markdown twin carries exactly the same words, headings and code as the page. It's generated from one source, never maintained by hand.
+
+## States and motion
+
+- Rail scrollspy: the active item changes as a heading crosses the top third of the viewport; 150ms colour change; reduced motion keeps it.
+- Deep links: arriving at `#commands` scrolls below the sticky header (`scroll-margin-top`).
+- The copy button: pending, copied ("Copied"), failed ("Copy failed, select the text instead").
+- Works with no JS: the rail is plain links, every tab panel is in the HTML, the copy buttons hide.
+- Agents: `/docs.md` (or `Accept: text/markdown`) returns the Markdown; `/llms.txt` lists the page with one line; the HTML has one H1, ordered headings and no content that exists only after a click.
+
+## Pitfalls
+
+- A three-column docs template (page nav, content, "on this page") for a single page.
+- Content only reachable through tabs or accordions an agent can't open.
+- A hand-written Markdown copy that drifts from the page.
+- A rail that scrolls away, or covers the text on a phone.
+- Gradient "Docs" heroes; the docs page is calm and fast.
+
+## Floor checks
+
+- Does the page head say what the page covers, with a way to copy it as Markdown?
+- Does a sticky contents rail (or a collapsible list on a phone) show every section and mark the current one?
+- Is the reading column at most about 70 characters wide with clear heading steps?
+- Does every heading have an anchor link?
+- Is the page in the site's own header, footer and type, not a separate template?
+- At 390, is everything one column with nothing overlapping the text?