@palate/cli 0.0.0-stage → 0.0.2

package/kb/sections/horizontal-scroll-strip.md

@@ -0,0 +1,101 @@
+---
+id: horizontal-scroll-strip
+name: Horizontal strip of tall feature frames
+kind: features
+shape: cards-row
+layout: "heading block pinned left 3–4/12, a strip of 5–8 tall feature frames (portrait, ~360–420 wide) that scrolls horizontally inside the section with native scroll, snap, a peek of the next frame and prev/next buttons"
+fits: [consumer, productivity, ai, ecommerce, playful, friendly, energetic, saas, launch, media]
+avoid: [enterprise-compliance, serious-news, government, data-dense-tool, crisis]
+needs: ["5–8 features or use cases, each with its own picture or product state", "a short caption per frame"]
+imagery: any
+density: balanced
+effort: m
+moves: [marquee-done-right, product-in-context]
+---
+
+## When it's right
+
+The product has many small, concrete things it does, or many situations it is used in, and the point is breadth: "it handles all of these". A horizontal strip of tall frames lets the visitor browse at their own pace, the way they flick through a shelf, without the page growing six screens taller. Each frame is a picture first (a product state, a photo of the product in use, an illustration) with a short caption. The section ends with the strip running off the right edge of the viewport, which says "there's more" without a word.
+
+Native scroll only. The strip moves when the visitor swipes, trackpad-scrolls sideways or presses the buttons; vertical scrolling never drives it (L15). Not for features that need reading (use `ruled-list-pinned-visual`) or for fewer than five items (use `alternating-rows-live-tiles`).
+
+## Structure
+
+```
+1440 ─ heading in the container; the strip starts at column 5 and runs to the viewport edge
+┌──────────────────────────────────────────────────────────────────────────────────────────┐
+│ ┌ cols 1–4 ─────────────┐ ┌ strip: overflow-x auto, scroll-snap x mandatory ──────────────────
+│ │ H2, 2–3 lines          │ │ ┌ frame 1 ─────┐ ┌ frame 2 ─────┐ ┌ frame 3 ─────┐ ┌ frame 4 ──
+│ │                        │ │ │              │ │              │ │              │ │
+│ │ lead, ink-2, 32ch      │ │ │  picture or  │ │              │ │              │ │
+│ │                        │ │ │  product     │ │              │ │              │ │  frames 380×520
+│ │                        │ │ │  state, 3:4  │ │              │ │              │ │  (portrait 3:4
+│ │ [‹] [›]  2 / 7         │ │ │              │ │              │ │              │ │   or 4:5)
+│ │ buttons at the bottom  │ │ ├──────────────┤ ├──────────────┤ ├──────────────┤ ├──
+│ │ of the heading block   │ │ │ title        │ │ title        │ │ title        │ │
+│ │                        │ │ │ one line     │ │ one line     │ │ one line     │ │
+│ └────────────────────────┘ │ └──────────────┘ └──────────────┘ └──────────────┘ └──
+│                                                                    peek ≥ 80px at 1440 ─▶│
+└──────────────────────────────────────────────────────────────────────────────────────────┘
+  heading block is position: sticky to the strip's top; gap between frames 16–24
+```
+
+```
+390 ─ heading stacked above, strip full bleed with 16px start padding
+┌──────────────────────────────┐
+│ H2                           │
+│ lead                         │
+│ ┌ frame 1 ───────────┐┌ fr ─│  ← frame 300×400, next frame peeks 32–48px
+│ │                    ││     │
+│ │                    ││     │
+│ ├────────────────────┤│     │
+│ │ title / one line   ││     │
+│ └────────────────────┘└─────│
+│ 2 / 7                        │  ← position text; buttons hidden on touch
+└──────────────────────────────┘
+```
+
+At 390 the heading block stacks above the strip; the strip goes edge to edge with `scroll-padding-inline: 16px` so the first frame starts on the gutter. Frames are about 300×400 (78% of the width) so the next one peeks 32–48px. The page itself never scrolls sideways; only the strip does.
+
+## Finish
+
+- Strip: `display: grid; grid-auto-flow: column; grid-auto-columns: 380px; gap: --s-5; overflow-x: auto; scroll-snap-type: x mandatory; overscroll-behavior-x: contain; scroll-padding-inline: var(--page-x)`. Frames `scroll-snap-align: start`. Keep the scrollbar visible on desktop but thin (`scrollbar-width: thin; scrollbar-color: var(--hairline-strong) transparent`).
+- Frames: picture on top at a fixed 3:4 (or 4:5), radius `--r-lg` with the picture clipped by the frame (`overflow: clip`); caption area padding `--s-4`. Flat frames on `--paper-2` or raised `--shadow-1` frames on `--paper`, not both.
+- One image treatment for every picture (`_finish.md`: duotone or tone-matched). Product states inside frames are the product frame recipe without its own shadow.
+- Caption: title `--t-body` weight 600; one line `--t-small` `--ink-2`. Same caption height in every frame (one-line titles).
+- Buttons: two 40px round icon buttons with a `--hairline-strong` ring and the states in `_finish.md`, disabled at the ends, plus a position text "2 / 7" in tabular figures, `--t-small` `--ink-3`.
+- Section padding normal; the strip's bottom aligns with the heading block's bottom.
+
+## Content
+
+- Heading: the breadth claim in plain words ("One app for every kind of list"). Lead: one sentence.
+- Frames: one feature or use case each, shown not described: the product state, or a real photo of it in use. Captions name it ("Recipes that scale servings") and add one line.
+- 5–8 frames. Fewer and the strip looks empty; more and nobody reaches the end.
+- No made-up customer photos or generated people (M47). If the project has no pictures, every frame is a code-built product state.
+
+## States and motion
+
+- Prev/next buttons scroll by one frame width with `scrollBy({ left, behavior: 'smooth' })` (instant under reduced motion); they update disabled state on `scrollend` or a throttled scroll listener.
+- Keyboard: the strip is a labelled region (`role="region" aria-label="Features"`, `tabindex="0"`); arrow keys scroll it; frames with links are focusable and focus scrolls them into view.
+- Hover on a frame: the picture scales 1.02 over 300ms inside its clip. No tilt, no glow.
+- No autoplay or auto-advance; no scroll hijacking; no marquee motion (if you want ambient motion, see move `marquee-done-right`, a different section).
+- No JS: the strip still scrolls natively; buttons are hidden.
+
+## Pitfalls
+
+- Vertical scroll converted into horizontal movement: scroll-jacking (L15).
+- A strip that fits entirely on screen at 1440, so it looks like a static row with a pointless scrollbar.
+- Hidden scrollbars and no buttons on desktop: mouse users can't move it.
+- The page scrolling sideways on phone because the strip's bleed isn't clipped.
+- Square stock thumbnails with long paragraphs under them: the frames should be pictures first.
+- Frames of different heights or caption lengths, so the bottom edge is ragged (P04).
+
+## Floor checks
+
+- Does the strip visibly run past the right edge, with part of the next frame showing?
+- Is every frame a picture or product state first, with a short caption under it?
+- Are all frames the same size with captions starting at the same height?
+- Are there visible previous and next buttons on desktop?
+- Does the heading block sit beside the strip at 1440 rather than as a separate band above it?
+- Is the first frame aligned to the page's left gutter or the grid?
+- At 390, does only the strip scroll sideways while the page does not?

package/kb/sections/how-i-work-own-voice.md

@@ -0,0 +1,111 @@
+---
+id: how-i-work-own-voice
+name: How I work, in my own voice, beside real prints
+kind: process
+shape: editorial-columns
+layout: "a first-person account of how the work is done, written as a short essay in 3–5 paragraphs down a reading column, with real prints, contact sheets or work-in-progress pictures hung in the margin beside the paragraph they belong to; the practical facts (what's included, timings, price) gathered in a quiet list at the end"
+fits: [portfolio, artsy, crafted, editorial, warm, honest, quiet, agency]
+avoid: [saas, developer, b2b, enterprise, data-dense-tool]
+needs: ["the maker's own words about how they work, 250–450 words, in first person", "3–5 real pictures from the process: a contact sheet, a print being developed, a sketch, the studio, a test print", "the practical facts a client asks: what's included, how long, when delivered, from what price"]
+imagery: photo
+density: airy
+effort: m
+moves: [editorial-drop-cap, hand-drawn-annotations]
+---
+
+## When it's right
+
+A person or small studio sells themselves as much as a service: a documentary wedding photographer, an illustrator, a bookbinder taking commissions, a sound designer. The client's real question is "what will it be like to work with you?", and the honest answer is in the maker's voice. The median page answers with four step cards ("1. Enquire 2. Consult 3. Shoot 4. Deliver") with icons, which made blind judges call our photographer page "SaaS-like". This archetype replaces the steps with a short piece of writing and the real objects of the work: the contact sheet, the roll of film, the proof print.
+
+Not for teams that need to explain a procedure with many dependencies (a clinic, a firm: use `numbered-editorial-columns`), and not without the maker's real words. A ghost-written "my passion for storytelling" is worse than the step cards.
+
+## Structure
+
+```
+1440 ─ container 1240; text in cols 2–7, margin pictures in cols 9–12
+┌──────────────────────────────────────────────────────────────────────────────────────────┐
+│    How I work                                                                            │ ← H2, cols 2–7
+│                                                                                          │
+│    I was a newspaper photographer for eight     ┌ contact sheet, cols 9–12 ──────────┐   │
+│    years before I photographed a wedding, and   │ ▢▢▢▢▢▢  a real 35 mm contact      │   │
+│    I still work the same way: I arrive early,   │ ▢▢▢▢▢▢  sheet, one frame circled  │   │
+│    I don't pose anyone, and I stay out of …     │ ▢▢▢▢▢▢  in grease pencil          │   │
+│                                                 └────────────────────────────────────┘   │
+│    Every wedding gets one roll of black-and-     Contact sheet, Tolu & James, roll 2     │ ← caption
+│    white film. I develop it by hand in my                                                │
+│    kitchen, and those twelve frames are …        ┌ print, cols 10–12 ──────┐             │
+│                                                  │ the developed print     │             │
+│    You'll get around 600 pictures four weeks     └─────────────────────────┘             │
+│    after the day. I'd rather send you fewer …                                            │
+│                                                                                          │
+│    ─────────────────────────────────────────                                             │
+│    What's included   up to 10 hours, one roll of film, an online gallery                 │ ← the practical list,
+│    Delivered         about 600 pictures, 4 weeks after                                   │   label/value, ruled
+│    Booking           12–18 months ahead · The Day from £3,200                            │
+│    Ask about your date →                                                                 │
+└──────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+```
+390 ─ the essay in one column; each picture follows its paragraph
+┌──────────────────────────────┐
+│ How I work                   │
+│ I was a newspaper            │
+│ photographer for eight …     │
+│ ┌──────────────────────────┐ │
+│ │ contact sheet, full width│ │
+│ └──────────────────────────┘ │
+│ Contact sheet, roll 2        │
+│ Every wedding gets one roll  │
+│ of black-and-white film …    │
+│ ──────────────────────────── │
+│ Included   up to 10 hours …  │
+│ Delivered  ~600, 4 weeks     │
+│ Ask about your date →        │
+└──────────────────────────────┘
+```
+
+At 390 the margin pictures drop into the text flow directly after the paragraph they belong to, full container width, in their own ratio. The practical list keeps label/value rows. The section is at most 3.5 phone screens; if the essay runs longer, cut words, not pictures.
+
+## Finish
+
+- Reading column: `--t-body` at 18px, leading 1.6, max 60ch, `text-wrap: pretty`, `hanging-punctuation` on quotes. The first paragraph may open with a drop cap (move `editorial-drop-cap`) in the display face, 3 lines tall, only if the type system uses one elsewhere.
+- Margin pictures: aligned to the top of the paragraph they illustrate (CSS grid with each pair in one row, or `position: sticky` within the paragraph's row). Different sizes (one spans 4 cols, the next 3), no two the same. No cards, no shadow; a contact sheet or a print may sit on `--paper-2` with a 1px `--hairline` edge like a physical sheet, rotated at most 0.5° if the page's direction is tactile, never more.
+- Annotations: if the maker marks frames (a grease-pencil circle, a crop mark), draw them as SVG over the picture (move `hand-drawn-annotations`) in one ink colour; never more than one per picture.
+- Captions: `--t-caption`, `--ink-2`, what the object is and from which job.
+- The practical list: a definition list under a 1px `--hairline-strong`, labels `--t-small` weight 600 in a 160px column, values `--t-small` `--ink`, prices `tabular-nums`. It is a footnote to the essay, not a pricing table.
+- The action: a text link with an arrow ("Ask about your date →"), or the page's secondary button. The section is not a hard sell.
+- Ground: `--paper`, or `--paper-2` if the previous section was image-heavy on `--paper`.
+
+## Content
+
+- First person, the maker's real voice, concrete: what they do on the day, what they don't do ("I don't pose anyone"), what the client receives and when. Edit for length, never for personality.
+- Each paragraph is about one part of the work; the picture beside it is the evidence (the roll of film beside the paragraph about film).
+- Facts from the maker's real terms: hours, delivery time, number of images, booking lead time, starting price.
+- No numbered steps, no "Step 1: Enquire". If the order matters, the prose carries it ("First we talk on the phone…").
+
+## States and motion
+
+- Static. Pictures lazy-load with dominant-colour placeholders and fixed ratios.
+- Each picture may open larger on click (a dialog or a link to the full-size file), with focus returned on close.
+- No scroll-triggered reveals on the paragraphs; the essay is read, not performed.
+- Reduced motion and no-JS: identical, since nothing moves.
+
+## Pitfalls
+
+- Step cards with icons and numbers ("1 Enquire · 2 Consult · 3 Shoot · 4 Deliver"): SaaS onboarding in a portfolio.
+- A progress track, status chips or a timeline widget for a human process.
+- Ghost-written clichés ("I capture your story", "timeless moments") instead of the maker's real words.
+- Stock pictures of cameras and film rolls; the objects must be the maker's own.
+- Pictures that don't relate to the paragraph beside them, so the margin is decoration.
+- The practical facts buried in the prose; a client should find the price and turnaround in the list at a glance.
+
+## Floor checks
+
+- Is the process told as first-person prose in a readable column, not as numbered step cards with icons?
+- Are there real pictures from the maker's process (contact sheets, prints, sketches, the studio) beside the text?
+- Does each picture sit next to the paragraph it relates to, with a short caption?
+- Is the section free of app chrome: no step numbers in circles, progress tracks, status chips or icon tiles?
+- Are the practical facts (what's included, delivery time, starting price) easy to find in a short list?
+- Is the body text comfortable to read (about 60 characters per line, 17px or larger)?
+- At 390, does each picture follow its own paragraph in a single column without sideways scrolling?

package/kb/sections/how-it-works-in-place.md

@@ -0,0 +1,109 @@
+---
+id: how-it-works-in-place
+name: How it works, shown with the place's own objects
+kind: process
+shape: cards-row
+layout: "3–4 photographs of the real moments of using the place (the shelf, the tag, the counter, the return bin) in one row at a shared height, each with a single plain sentence under it in the place's own voice; one line of the rules that matter and one action after the row"
+fits: [local, nonprofit, community, food, crafted, honest, friendly, warm, tactile]
+avoid: [saas, developer, b2b, enterprise, data-dense-tool]
+needs: ["3–4 real photographs of each moment of using the place, taken there (or careful drawings of the real objects)", "one sentence per moment, in the order a first-timer goes through it", "the 1–3 rules that matter (loan length, cut-off, cost) and the real next step"]
+imagery: photo
+density: balanced
+effort: m
+moves: [product-in-context, hand-drawn-annotations]
+---
+
+## When it's right
+
+A place where people do something in person, and a first-timer needs to know how it goes: borrowing from a tool library, picking up a pre-order at a bakery window, dropping off a bike for a same-day service, coming to a free evening class. The honest "how it works" is three or four physical moments, and the place already has the objects that explain them: the shelf of drills with luggage tags, the paper bag with your name on it, the hook where your bike hangs, the library card. Photographs of those objects say more, and say it more warmly, than any step card.
+
+This is the process archetype for places, not software. In our benchmark a nonprofit tool library and a bakery both failed on "process" sections built as app UI (status pills, step cards, receipt cards); this replaces them. For a software product's flow use `process-happening`; for a maker's personal way of working use `how-i-work-own-voice`.
+
+## Structure
+
+```
+1440 ─ container 1240; four photographs at one height, gutter 24
+┌──────────────────────────────────────────────────────────────────────────────────────────┐
+│ How borrowing works                          Membership is $0–80 a year, you choose.     │ ← H2 left, the key rule right
+│                                                                                          │
+│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐                      │
+│ │              │ │              │ │              │ │              │                      │ ← photographs, 4:5, same
+│ │ the shelf of │ │ a volunteer  │ │ the drill on │ │ the return   │                      │   height, own crops
+│ │ drills with  │ │ hands over   │ │ a loft bed   │ │ shelf by the │                      │
+│ │ their tags   │ │ the tagged   │ │ half built   │ │ door         │                      │
+│ │              │ │ ladder       │ │              │ │              │                      │
+│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘                      │
+│ Find it online   Pick it up       Use it for a     Bring it back                         │ ← 2–3 word label, ink
+│ 2,300 tools, from Lake Street,    week. Renew      clean-ish. A volunteer                │ ← one sentence, ink-2
+│ a tape measure   Tue–Sat.         online if no-    checks it.                            │
+│ to a tile saw.                    one's waiting.                                         │
+│                                                                                          │
+│ ─────────────────────────────────────────────────────────────────────────────────────────│
+│ Loans are 7 days. Late? We'll text, not fine you.        [ Browse the catalogue ]        │ ← rules line + one action
+└──────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+```
+390 ─ a vertical sequence: photograph, label, sentence
+┌──────────────────────────────┐
+│ How borrowing works          │
+│ Membership is $0–80 a year.  │
+│ ┌──────────────────────────┐ │
+│ │ the shelf of drills, 3:2 │ │ ← 3:2 on phone so four fit
+│ └──────────────────────────┘ │   in about 2.5 screens
+│ Find it online               │
+│ 2,300 tools, from a tape …   │
+│ ┌──────────────────────────┐ │
+│ │ the handover, 3:2        │ │
+│ └──────────────────────────┘ │
+│ Pick it up …                 │
+│ …                            │
+│ Loans are 7 days …           │
+│ [ Browse the catalogue ]     │
+└──────────────────────────────┘
+```
+
+At 390 the row becomes a vertical sequence, each photograph re-cropped to 3:2 around its object so the four moments fit in about 2.5 screens, each followed by its label and sentence. A sideways strip is acceptable only for four or more moments and only if each sentence stays under its photograph.
+
+## Finish
+
+- Photographs: one treatment for all (`_finish.md` image treatment), one ratio (4:5 at 1440), one height, `object-position` on the object (the tag, the hands). Radius none or `--r-sm`; no card, no border, no shadow; they sit on the ground like prints on a noticeboard. Gutter `--s-5`.
+- Labels: `--t-body` weight 600, `--ink`, 2–3 words in the place's own verbs ("Pick it up", "Grab your bag"). Sentence under it: `--t-small` or `--t-body`, `--ink-2`, one sentence, max 36ch, `text-wrap: pretty`. Label `--s-3` below the photograph; sentence `--s-1` below the label.
+- Order is carried by left-to-right reading and the verbs. Numbers only if the place itself numbers things (a ticket number, a numbered hook); never numbers in circles.
+- If one object needs pointing at (the tag's due date, the pickup window), one hand-drawn annotation in the brand's ink over that photograph (move `hand-drawn-annotations`), not on every one.
+- Heading row: H2 left, the single most important rule right on the same baseline (`--t-body`, `--ink-2`).
+- Rules line: under a 1px `--hairline`, `--s-6` below the row: the 1–3 rules in one or two sentences, and the page's `.btn-primary` on the same line, right.
+- Ground: `--paper` or `--paper-2` as background planning requires; a paper-fibre texture at 3% only if the page already uses it.
+
+## Content
+
+- Photographs of the real place and real objects, taken there, with permission from anyone in them (volunteers, members). If photographs don't exist yet, careful drawings of the real objects in one style (the tag, the bag, the hook) are acceptable; icons are not.
+- Sentences in the place's voice and with its real facts: hours, loan length, cut-offs, cost ("Pick up Saturday from 8 am at the side window. Say your name.").
+- The rules a first-timer needs, kindly put ("Late? We'll text, not fine you."), and only if true.
+- One action: the real next step (browse the catalogue, pre-order, book a drop-off).
+
+## States and motion
+
+- Static. Photographs lazy-load with dominant-colour placeholders at fixed ratios.
+- No step animation, no sequence playing, no progress line filling. If anything moves, it is a single hover on desktop that lifts the photograph's brightness 4%.
+- The annotation, if any, may draw itself once over 600ms when the section enters view; reduced motion shows it drawn.
+- No-JS: identical.
+
+## Pitfalls
+
+- Step cards with icons and numbers in circles, connected by arrows: the "SaaS-like" process the benchmark judges rejected.
+- Status pills ("Reserved", "Ready", "Returned") or a mocked app screen showing an order tracker for a physical errand.
+- A receipt card or kitchen-display UI standing in for the real handover.
+- Stock photos of generic tools or bread; the objects must be this place's.
+- Four photographs at four different heights and ratios, so the row reads as a collage rather than a sequence.
+- Long paragraphs under each photograph; one sentence each.
+
+## Floor checks
+
+- Is each step shown with a photograph (or careful drawing) of the place's real objects or moments rather than an icon?
+- Is the section free of app chrome: no status pills, step numbers in circles, mocked trackers or receipt cards?
+- Do the photographs share one height and treatment so the row reads as a single sequence?
+- Is each step named in 2–3 plain words with no more than one sentence of supporting text?
+- Are the key rules (cost, loan length or cut-off) stated plainly near the steps?
+- Is there one clear next action after the steps?
+- At 390, do the steps run as a vertical sequence of photograph, label and sentence with no sideways scrolling of the page?

package/kb/sections/impact-numbers-sourced.md

@@ -0,0 +1,109 @@
+---
+id: impact-numbers-sourced
+name: Impact in real numbers, each with its source
+kind: stats
+shape: editorial-columns
+layout: "3–4 real figures set large in editorial columns, each with one plain sentence on what it means and a footnote-style source line (year, how it was counted, link); one honest line on what can't be counted yet"
+fits: [nonprofit, honest, community, trustworthy, education, sustainability, government, serious]
+avoid: [saas, b2b, playful-kids, luxury]
+needs: ["3–4 figures from the organisation's own records or published report, with the year they cover", "for each: how it was counted and where a visitor can check it (annual report, open data, audited accounts)", "one thing the organisation would like to count but can't yet"]
+imagery: type
+density: balanced
+effort: s
+moves: [real-world-data]
+---
+
+## When it's right
+
+A nonprofit, civic project or education programme has to show it works, and the visitor (a donor, a volunteer, a funder, a sceptical neighbour) wants to know the numbers are true. The median page answers with a band of four counters ticking up from zero beside icons: it reads like a SaaS metrics strip and it convinces nobody, because nothing says where the numbers came from.
+
+This archetype sets a few real figures large, says in plain words what each one means for a person, and gives every figure its source like a footnote in a good report: the year, how it was counted, a link to check it. One line admits what can't be counted yet. That honesty is the persuasion. Open Shelf's 11,000 loans, River Watch's 26 sewage investigations, Lantern's 83% of learners reaching a first goal: each is stronger with its source under it.
+
+Not for a single defining number (use `one-huge-number`), for a long list of facts to compare (use `ruled-facts-table`), or when the figures are estimates nobody can check: say less, or don't build it.
+
+## Structure
+
+```
+1440 ─ container 1240, 12-col grid; heading cols 1–4, figures cols 5–12 in 3 (or 4) columns
+┌──────────────────────────────────────────────────────────────────────────────────────────┐
+│ H2 "What 2025 looked like"          ┌ col ──────────┐ ┌ col ──────────┐ ┌ col ─────────┐ │
+│ one line lead, ink-2: "From our     │ 11,000        │ │ 1,840         │ │ $1.2M        │ │ ← figure: --t-display,
+│ annual report, checked by our       │               │ │               │ │              │ │   tabular-nums, ink
+│ treasurer."                         │ loans of a    │ │ members, on a │ │ members did  │ │ ← sentence: --t-body,
+│                                     │ tool someone  │ │ sliding scale │ │ not spend on │ │   ink, 2–3 lines
+│                                     │ didn't buy.   │ │ from $0.      │ │ tools.¹      │ │
+│                                     │ ───────────── │ │ ───────────── │ │ ──────────── │ │ ← hairline
+│                                     │ 2025 loan log │ │ Member list,  │ │ ¹ Estimate:  │ │ ← source: --t-caption,
+│                                     │ Annual report │ │ 31 Dec 2025   │ │ loans × shop │ │   ink-2, link
+│                                     │ p. 4 →        │ │               │ │ price. How → │ │
+│                                     └───────────────┘ └───────────────┘ └──────────────┘ │
+│                                                                                          │
+│ What we can't count yet: how many of those tools would have ended up in landfill.        │ ← one honest line, --t-small,
+│                                                                                          │   ink-2, cols 5–12
+└──────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+```
+390 ─ side padding 16; one column
+┌──────────────────────────────┐
+│ H2                           │
+│ lead, ink-2                  │
+│                              │
+│ 11,000                       │ ← figure 56–64px
+│ loans of a tool someone      │
+│ didn't buy.                  │
+│ ──────────────────────────── │
+│ 2025 loan log · Report p.4 → │
+│                              │
+│ 1,840                        │
+│ …                            │
+│                              │
+│ What we can't count yet: …   │
+└──────────────────────────────┘
+```
+
+At 390 the figures stack in one column, each block (figure, sentence, hairline, source) spaced `--s-7` from the next. The figure steps down to 56–64px; the source line stays readable at 13px and its link is a 44px tap target. No horizontal carousel of numbers.
+
+## Finish
+
+- Figures: `--t-display` (72–88px at 1440), the page's display face, weight to suit it, `font-variant-numeric: tabular-nums lining-nums`, tracking −0.03em, leading 1.0, `--ink`. Units in the same line at `--t-h3` in `--ink-2` ("83%" keeps its % at full size; "$1.2M" keeps the M; "kg" or "sites" drop to the smaller size).
+- Sentence: `--t-body` 17–18px, `--ink`, max 26ch so it stays two or three lines; `text-wrap: pretty`. It says what the number means for a person, not the number again in words.
+- Source: a 1px `--hairline` above, `--s-3` gap, then `--t-caption` in `--ink-2`: "2025 loan log. Annual report, p. 4 →". The link is underlined and goes to the actual document or dataset. Estimates are marked with a superscript ¹ and explained in their own source line.
+- Columns: the figures share one baseline across columns, the sentences start on one line, the hairlines align (P01). Column gap `--s-7`; heading column to figures `--s-8`.
+- The "can't count yet" line: `--t-small`, `--ink-2`, `--s-7` below the columns, aligned with the first figure column. No icon.
+- Ground: `--paper` or `--paper-2` to alternate with the previous section; no cards, no shadows, no tinted tiles behind numbers. The numbers sit on the page like figures in a printed report.
+- No icons above the numbers (a hand holding a heart, a globe): the number and its sentence are enough.
+
+## Content
+
+- Only numbers the organisation can stand behind, for a stated period ("in 2025", "since 2021"). Round honestly: 11,000 if it is 11,040; never 10,000+ to sound modest or 11k+ to sound big.
+- The sentence makes the number human: "learners reached their first goal within six months" rather than "success rate". Use the organisation's own words where possible.
+- Sources: the annual report page, the open dataset (River Watch's results are CC BY 4.0: link them), the charity regulator's listing, audited accounts. Say how an estimate was made ("loans × the price of the tool new").
+- One "what we can't count yet" line: real, specific, not false modesty.
+- No comparisons to invented baselines, no "10×", no "lives changed" without a count of what changed.
+
+## States and motion
+
+- Static. The numbers are visible on first paint and in screenshots; no count-up from zero (it shows a wrong number for a second and reads as a SaaS counter).
+- Optional: the source link previews the report page on hover (desktop only); no motion needed.
+- Links have hover (underline thickens) and visible focus states.
+- If a figure is updated live (River Watch's sites tested this month), say when it was last updated in the source line and fetch it at build time; never fake liveness.
+
+## Pitfalls
+
+- Four counters ticking up beside icons in tinted tiles: a SaaS metrics strip, and the least credible way to show impact.
+- Numbers with no year and no source.
+- "Lives changed: 10,000+" or any number that can't be checked.
+- Numbers in cards with shadows, pills or badges ("+12% YoY" chips): app chrome on a report.
+- The sentence repeating the label ("11,000 loans: total loans").
+- Six or more figures: the strongest three get lost.
+
+## Floor checks
+
+- Are there three or four figures, each set large with tabular figures on a shared baseline?
+- Does each figure have a plain sentence saying what it means for a person?
+- Does each figure have a visible source line (year and where to check it), with estimates marked as estimates?
+- Is there one honest line about what can't be counted yet?
+- Is the section free of counter tiles, icons above numbers, pills, badges and card shadows?
+- In a static screenshot, are all numbers shown at their final values (no zeros mid-count)?
+- At 390, do the figures stack in one readable column with source lines still legible and nothing scrolling sideways?

package/kb/sections/install-steps-per-agent.md

@@ -0,0 +1,77 @@
+---
+id: install-steps-per-agent
+name: Install steps, one tab per tool
+kind: docs
+shape: timeline
+layout: "three to five numbered steps down a thin rule; a step that differs per tool (agent, OS, package manager) has tabs, every command has a copy button, and the last step is the first success"
+fits: [docs, developer, technical, ai, saas, productivity, honest, calm, friendly, trustworthy, launch, waitlist]
+avoid: [cinematic, luxury, fashion, experimental]
+needs: ["the real install commands for every supported tool", "what the user needs first (versions, accounts, codes)", "the first thing to try once it's installed, and what they'll see"]
+imagery: none
+density: balanced
+effort: s
+---
+
+## When it's right
+
+The part of the docs every new user goes through once, usually copying while they read. Numbered steps say how long it is; tabs keep three tools' commands from tripling the page; the last step ends in a result, not "you're done". Not for a one-command install (a single code block says it) or a long migration (that's a guide with sections).
+
+## Structure
+
+```
+reading column, 68ch
+Before you start: Node 22+, Chrome or Edge, your invite code.       ← one line, requirements
+
+ ①  Add it to your agent
+ │   [Claude Code] [Codex] [Cursor]                                 ← tabs, the first is the most used
+ │   In a terminal:
+ │   ┌───────────────────────────────────────────── [Copy] ┐
+ │   │ claude mcp add acme -- npx acme mcp                  │
+ │   └──────────────────────────────────────────────────────┘
+ │
+ ②  Activate it
+ │   ┌ npx acme activate <your code> ────────────── [Copy] ┐
+ │
+ ③  Try it
+     Ask your agent: "make the pricing section"                     ← the first success, in their words
+     You'll see: ...                                                ← what happens next
+```
+
+```
+390 ─ the same, one column; tabs scroll sideways if they don't fit; code wraps (overflow-wrap: anywhere), never scrolls the page
+```
+
+## Finish
+
+- Step numbers: 28px circles in the accent's tint with the accent number, tabular; a 1px rule joins them in `--hairline`.
+- Step title at H3 (17–20px, 500); the text under it small and secondary; 40px between steps.
+- Tabs: a segmented control (`role="tablist"`, arrow keys, Home/End), 32px tall; the choice is remembered (localStorage) and applied to every tab group on the page.
+- Code blocks: mono 13–14px on a faint tint, 12px radius, the copy button inside on the right; a command that takes a value shows the placeholder in the accent (`<your code>`), explained in the line above.
+- An "or ask your agent to do it" block may follow: one copyable prompt that installs it for them.
+
+## Content
+
+- Requirements first, in one line, with versions.
+- Each command exactly as it runs, for each tool; config file paths named in full (`~/.codex/config.toml`).
+- The last step is a real first task with what the user will see.
+
+## States and motion
+
+- Tab change: instant panel swap, no slide.
+- Copy: "Copied" for 2s, then back; failure says so.
+- No JS: every tab's panel is in the HTML, each under its own small heading, so people without JS and agents get all of them.
+
+## Pitfalls
+
+- Hiding the other tools' commands from agents and search (only the active panel in the HTML).
+- Commands with prompts (`$`) or output mixed in, so the copy button copies junk.
+- "You're all set!" with no first task.
+- Seven steps where three would do.
+
+## Floor checks
+
+- Are the steps numbered and few (three to five)?
+- Does every command have its own copy button and run exactly as copied?
+- Is every supported tool's setup on the page (all shown at once, or tabs whose panels are all in the HTML)?
+- Does the last step give a first thing to try and what will happen?
+- Are the requirements stated before step one?

package/kb/sections/masonry-real-work.md

@@ -0,0 +1,109 @@
+---
+id: masonry-real-work
+name: Masonry of real work
+kind: gallery
+shape: masonry
+layout: "3 columns at 1440 (4 when items are small) of real outputs at their natural aspect ratios, packed with one 24px gutter; a heading and filter row above; every item captioned with what it is and who made it"
+fits: [portfolio, agency, artsy, crafted, community, editorial, media, publishing, fashion, food, ai, music, honest, cultural]
+avoid: [enterprise-compliance, finance-trust-first, data-dense-tool, clinical, government]
+needs: ["9–24 real outputs made with the product or by the studio (images, pages, prints, renders, screens)", "a caption for each: what it is, who made it, with permission", "varied aspect ratios (a masonry of identical squares is just a grid)"]
+imagery: any
+density: dense
+effort: m
+moves: [made-with-proof, honest-testimonial-wall, link-preview-peek, screenshot-detail-crops]
+---
+
+## When it's right
+
+The best argument for the product is the volume and range of what people have made with it: a design tool's community gallery, an image model's outputs, a studio's portfolio, a print shop's jobs, a template marketplace. The masonry shows range at a glance and lets items keep their real shapes, which is the honest way to show creative work (cropping everyone's work to the same square erases what makes it theirs).
+
+It is proof made of work, not of quotes. Not for products whose output is not visual, for fewer than 9 items (use `alternating-rows-live-tiles` or `horizontal-scroll-strip`), or when the work is not real yet: placeholders in a masonry are the most obvious fake on a page (M10, L24).
+
+## Structure
+
+```
+1440 ─ container 1240, 3 columns of 397 with 24 gutters (4 × 292 for small items)
+┌──────────────────────────────────────────────────────────────────────────────────────────┐
+│ H2 "Made with X this month"                                      [All] [Posters] [Sites] │ ← heading left, filters right,
+│ one line: how these were chosen, ink-2                                     View all 240 →│   same baseline
+│                                                                                          │
+│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐                                          │
+│ │             │ │   3:2       │ │             │                                          │
+│ │   4:5       │ │             │ │   1:1       │                                          │
+│ │             │ └─────────────┘ │             │                                          │
+│ │             │ Title · Maker   └─────────────┘                                          │
+│ └─────────────┘ ┌─────────────┐ Title · Maker                                            │
+│ Title · Maker   │             │ ┌─────────────┐                                          │
+│ ┌─────────────┐ │   2:3       │ │   16:9      │                                          │
+│ │   1:1       │ │             │ └─────────────┘                                          │
+│ └─────────────┘ │             │ Title · Maker                                            │
+│ Title · Maker   └─────────────┘ ┌─────────────┐                                          │
+│                 Title · Maker   │   4:5       │                                          │
+│ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ │ ← columns end ragged; a soft fade
+│                                   [ See all 240 pieces ]                                 │   (mask) over the last 160px and
+└──────────────────────────────────────────────────────────────────────────────────────────┘   one secondary button
+  section height: capped at about 1.6 screens (1400–1600px); the rest is behind "See all"
+```
+
+```
+390 ─ 2 columns of 171 with 16 gutter (1 column if items are text-heavy pages)
+┌──────────────────────────────┐
+│ H2, 2 lines                  │
+│ [All][Posters][Sites] → scroll│ ← filter chips scroll horizontally inside their row
+│ ┌──────┐ ┌──────┐            │
+│ │ 4:5  │ │ 3:2  │            │
+│ └──────┘ └──────┘            │
+│ Title    ┌──────┐            │
+│ ┌──────┐ │ 1:1  │            │
+│ │ 1:1  │ └──────┘            │
+│ └──────┘ Title               │
+│ … 8–10 items, then fade      │
+│ [ See all 240 pieces ]       │
+└──────────────────────────────┘
+```
+
+At 390, two columns with a 16px gutter (one column if the items are web pages or documents whose detail matters). Show 8–10 items, then the fade and the button: the section is never taller than 2.2 phone screens. Filter chips scroll sideways inside their own row; the page never does.
+
+## Finish
+
+- Layout: CSS columns are the simplest correct masonry (`columns: 3 397px; column-gap: 24px;` with `break-inside: avoid` on items), which orders items top-to-bottom per column. If reading order matters (newest first, left to right), use a grid with `grid-template-rows: masonry` where supported and a JS packing fallback (measure heights, place each item in the shortest column). Never fake masonry with fixed heights and `object-fit: cover`: the point is real shapes.
+- Items: images at their natural aspect ratio with `width`/`height` set (no shift as they load). Radius `--r-md` on the image only; no card around it, no border, no shadow: work sits on the page ground like prints on a table. Item spacing: `--s-5` vertical between items (same as the gutter, so the masonry reads as one even weave).
+- Caption under each item, `--s-2` gap: title in `--t-small`, weight 500, `--ink`; maker in `--t-small`, `--ink-2`, after a middle dot. One line, truncated with an ellipsis and the full text in the `title` attribute and the link. Captions are part of the item; P15: caption gap 8 < item gap 24.
+- Hover (desktop): the image darkens 6% and a 1px `--hairline-strong` ring appears inside its radius; the caption title underlines. No zoom-scale on hover (it shifts neighbours' perceived edges).
+- Filters: segmented chips, 32px tall, `--r-pill`, a `--hairline-strong` ring, the states in `_finish.md`; the active chip uses `--ink` fill and paper text. Changing a filter crossfades (150ms) rather than animating positions.
+- End of section: mask the last 160px with `mask-image: linear-gradient(to bottom, #000 calc(100% - 160px), transparent)`; the "See all" secondary button sits centred below the mask, `--s-6` gap. A dedicated page holds the full set.
+- Ground: the gallery on `--paper-2` makes the work's own colours read as the subject, and counts as a ground change in background planning. Very colourful work on a quiet, slightly warm or cool ground, never on pure white or black.
+
+## Content
+
+- Only real work, used with the maker's permission and credited by name (and link, if they want one). If the product has no users yet, show work made by the team with the product and say so ("Made by us while building X").
+- Curate: range over volume. Mix kinds, colours and scales; put the strongest piece top-left (in CSS columns, the first item) and a second strong one at the top of column 3.
+- The line under the heading says how the items were chosen ("Picked by the team from this month's public projects") so it reads as editorial, not as a cherry-picked ad.
+- No stars, likes or download counts unless they are real and useful to the visitor.
+
+## States and motion
+
+- Images lazy-load below the fold with the item's average colour as a placeholder background (computed at build time), so columns never collapse or jump.
+- Each item is a link (to the work, the maker or a detail view) with a visible focus ring around the image (`outline-offset: 2px`, follows the radius).
+- Optional: move `link-preview-peek` on hover for items that link off-site.
+- No entrance animation on items (staggered fade-ups on 20 tiles is M44 at its worst). Filtering: crossfade only.
+- Empty filter result: one line ("No sites this month yet.") and a link back to All; never an empty band (P38).
+
+## Pitfalls
+
+- Every item cropped to the same square, which turns a masonry into a stock grid and erases the work.
+- Placeholder or generated "community" work (M10). One fake item discredits the real ones.
+- Cards with borders, shadows and padding around each piece (M36): the work should be the only thing with colour.
+- An endless gallery inside the landing page: cap it and link out.
+- Columns of wildly different lengths at the bottom with a hard cut; use the fade.
+- Uncredited work.
+
+## Floor checks
+
+- Are the items shown at different natural aspect ratios rather than cropped to one shape?
+- Does every item carry a visible caption with what it is and who made it?
+- Does the work read as real output (specific, varied, finished) rather than placeholders or stock?
+- Is the work set directly on the ground without heavy cards, borders or shadows around each piece?
+- Is the gutter between items the same horizontally and vertically, with captions sitting closer to their own item than to the next one?
+- Does the section end in a deliberate way (a fade and a "see all" link) rather than columns cut off at ragged heights?
+- At 390, is the gallery two columns (or one) with nothing scrolling the page sideways?