@gallopsystems/agent-skills 1.31.1 → 1.32.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -21,6 +21,7 @@ Then install the skills you want:
21
21
  /plugin install vue-nuxt@gallop-systems-agent-skills
22
22
  /plugin install frontend-design@gallop-systems-agent-skills
23
23
  /plugin install gallop-ui@gallop-systems-agent-skills
24
+ /plugin install generate-documentation@gallop-systems-agent-skills
24
25
  ```
25
26
 
26
27
  ## Updating
@@ -180,6 +181,18 @@ Covers:
180
181
  - Pulling a release: `yarn ui:pull`, `ui:migrate`, `ui:tokens`, `ui:check`, merge-commit subtree PRs
181
182
  - Changing the layer, checking every app with `ui:impact` and screenshot sweeps, and working rules learned the hard way
182
183
 
184
+ ### generate-documentation
185
+
186
+ Write a client-facing guide with real screenshots of the app, as a PDF, HTML page, email draft or WhatsApp messages.
187
+ Run it as `/generate-documentation <format> <what to document>`.
188
+
189
+ Covers:
190
+ - Two modes: **answer** (turn a client's questions into "you can already do this", "we changed it", "here's the fix") and **announce** (turn merged work into an unsolicited "you can now…" note)
191
+ - Checking each answer in the code and the running app before writing it
192
+ - Screenshots from a scratch copy of the app's fictional demo data only, never real data
193
+ - `bin/shots.mjs` Playwright helpers (sign-in, still captures, highlight rings, region and element shots) and `bin/render.mjs` (HTML to PDF, plus a contact sheet for reviewing page breaks)
194
+ - A guide template, writing rules for non-technical readers, and per-format rules
195
+
183
196
  ## Contributing a Lesson Back
184
197
 
185
198
  Every skill ends with a **Contributing Back** section: when Claude works through
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gallopsystems/agent-skills",
3
- "version": "1.31.1",
3
+ "version": "1.32.0",
4
4
  "description": "Gallop Systems agent skills, symlinked into .claude/skills (Claude Code) and .agents/skills (Codex) on install.",
5
5
  "license": "UNLICENSED",
6
6
  "repository": {
@@ -27,8 +27,8 @@ colour tokens.
27
27
  | `CLAUDE.md` | The layer's rules for people and agents who change it. |
28
28
  | `README.md` | Adding the layer, taking versions, customizing (`pt`, `gallopUi`), restyling states. |
29
29
  | `TOKENS.md`, `FORMATTERS.md` | The colour-token contract; `formatDate`, `formatCurrency`… and time zones. |
30
- | `CHANGELOG.md`, `migrations/<version>/`, `docs/migrating-to-*.md` | What changed, and the codemod tables. |
31
- | `docs/decisions.md` | Settled API names and who decided them. Read before proposing a rename. |
30
+ | `CHANGELOG.md`, `migrations/<version>/`, `docs/upgrading.md` | What changed, how to take a release, and the codemod tables. |
31
+ | `docs/decisions.md` | Settled API names and the reasons for them. Read before proposing a rename. |
32
32
  | `docs/playground.md` | `/_ui` and `yarn ui:impact`. |
33
33
 
34
34
  `yarn ui:version` prints the app's layer version.
@@ -68,7 +68,7 @@ Detail, and how to propose a component: [finding-a-component.md](finding-a-compo
68
68
  ## Pull an update (decision procedure)
69
69
 
70
70
  New worktree from `origin/main` → `yarn ui:pull vX.Y.Z` (its own commit; needs a clean tree) → read `CHANGELOG.md`
71
- and `migrations/` between the two versions → on a breaking release, `yarn ui:migrate --dry`, then `yarn ui:migrate`
71
+ and `migrations/` between the two versions → whenever there's a newer `migrations/` table (minor releases too), `yarn ui:migrate --dry`, then `yarn ui:migrate`
72
72
  and work its checklist → `yarn ui:tokens`, `yarn ui:check` → remove workarounds the release makes unnecessary → full
73
73
  tests and a before/after visual sweep → PR, merged with a **merge commit**.
74
74
  Steps and commands: [pulling-updates.md](pulling-updates.md).
@@ -108,8 +108,8 @@ colours: an app's extra button colour maps onto an existing `color`.
108
108
  ## `pt` sections and slots
109
109
 
110
110
  - `class` is always `pt.root`. An overlay's `root` is its panel; its backdrop is `overlay`.
111
- - Inside a list, an item's parts are `item`, `itemLabel`, `itemDescription`, `itemIcon`; a group heading is
112
- `groupLabel`.
111
+ - Inside a list, an item's parts are `item`, `itemLabel`, `itemDescription`, `itemIcon`, and every other part of a
112
+ row is prefixed `item` too (`itemBadge`, `itemCount`, `itemKbd`, `itemMeta`); a group heading is `groupLabel`.
113
113
  - `icon` is only the component's own leading icon; other icons are named for their job (`toggleIcon`, `zoneIcon`,
114
114
  `checkIcon`).
115
115
  - A field's popup is `panel`; Tabs' panels are `tabPanel`; a title-plus-description block is `text`; an inner
@@ -150,6 +150,9 @@ colours: an app's extra button colour maps onto an existing `color`.
150
150
  without new evidence.
151
151
  - **Backward compatible by default:** a new prop or option must leave every existing call site rendering exactly as
152
152
  before. A look that changes without the caller touching `pt` is a breaking change.
153
+ - **A rename can ship in a minor release** when the old name keeps working until the next major: a `pt` section
154
+ through `usePt`'s `renamed` map (a deprecated alias with one dev warning per old name), a data attribute rendered
155
+ under both names. It still gets a codemod row, so apps stop using the old name before the major removes it.
153
156
  - **Breaking changes after 1.0** need a major release, a `CHANGELOG.md` note, and a row per change in
154
157
  `migrations/<version>/<area>.json` with a `codemod` the kit can apply (`rename`, `invert-to`, `wrap-array`…) or
155
158
  `manual` with a `locate` and a note. `yarn ui:migrate` then rewrites apps and writes the checklist. Before 1.0,
@@ -5,7 +5,7 @@ Fixes and features for the layer are made **in the gallop-ui repo** (`gallop-sys
5
5
  app, so the bar is higher than for app code: backward compatible, documented, tested, and checked in every app.
6
6
 
7
7
  The layer's `CLAUDE.md` is the authority on its rules. Read it, `docs/decisions.md` (settled names) and
8
- `docs/review-queue.md` (open questions) before you start.
8
+ `docs/roadmap.md` (what's planned and open) before you start.
9
9
 
10
10
  ## 1. Worktree
11
11
 
@@ -86,8 +86,8 @@ yarn tokens:check # if you touched tokens
86
86
  the `Co-Authored-By` trailer you were given.
87
87
  - The PR body: what changed and why, the apps you checked with `impact.mjs` and what changed in each, and any naming
88
88
  call the owner still has to make. End it with the Claude Code line you were given.
89
- - Record a decision the owner made in `docs/decisions.md`. Add an open question to `docs/review-queue.md`, and delete
90
- an item there when it is done.
89
+ - Record a settled decision, with its reason, in `docs/decisions.md`. Add planned or open work to `docs/roadmap.md`,
90
+ and remove it there when it ships.
91
91
  - **Layer PRs are squash-merged**, with the PR title as the Conventional Commit. A merge commit hides the change
92
92
  from release-please.
93
93
  - Merge only when checks are green **and** `gh pr view <n> --json mergeStateStatus` says `CLEAN`, and only if you
@@ -50,6 +50,11 @@ instead of a choice), it is a different component.
50
50
  While the layer change is pending, the app may carry a small, local workaround marked `TODO(gallop-ui): <what the
51
51
  layer should do>`. The next `ui:pull` removes it.
52
52
 
53
+ **A list of rows you write yourself** (people with an avatar and actions, settings rows, a pick-one list, a list the
54
+ user reorders) is `List` with `ListItem` and `ListGroup`: slots for leading, content and actions; selection with
55
+ checkboxes or pick-one; reorder; ghost or outlined, ruled or gapped. Don't hand-roll a `<ul>` with borders and
56
+ checkboxes. A list of records with columns is still `DataTable`.
57
+
53
58
  ## 4. No match: compose, then propose
54
59
 
55
60
  1. **Compose layer primitives in the app** (`Card` + `DescriptionList` + `Button`…), in an app component named for
@@ -88,5 +93,5 @@ The owner decides names and whether the layer grows. Bring a short proposal, not
88
93
  `docs/decisions.md` so you don't reopen a settled name.
89
94
  - **What it replaces**, and whether adopting it is a scripted rewrite.
90
95
 
91
- `docs/composite-candidates.md` in the gallop-ui repo lists what earlier surveys found and what was declined. Check
92
- it first. An idea that isn't built yet goes in `docs/review-queue.md` as an open item.
96
+ In the gallop-ui repo, `docs/roadmap.md` ("Later") lists ideas not built yet, and `docs/decisions.md` ("Considered
97
+ and not built") lists what was declined and why. Check both first. A new idea goes in `docs/roadmap.md`.
@@ -66,6 +66,11 @@ Rules learned the hard way while building the layer and moving every app onto it
66
66
  open must read it again.
67
67
  - **DataTable cell state follows the position** on a page turn unless the stateful component has `:key="row.id"`.
68
68
  - **Don't copy an old phone table** with `layout="table"`: phones get cards.
69
+ - **Default icons missing after a pull?** The app has no `gallopUi.icons` and no `@iconify-json/ph`, so the layer
70
+ draws Phosphor from a collection that isn't there. Run `yarn ui:migrate` (it writes `icons: "lucide"`), or install
71
+ Phosphor on purpose. The layer prints a `[gallop-ui]` warning at build time for this.
72
+ - **A dev warning `[gallop-ui] <Component> pt "<old>" is deprecated`** means the app uses a name a minor release
73
+ renamed. It still works; run `yarn ui:migrate` to rename it before the next major removes it.
69
74
  - **`/_ui` shows the wrong font?** The app sets its font from a layout. Move it to `--font-sans` in `@theme`.
70
75
 
71
76
  ## Verifying and reporting
@@ -36,16 +36,27 @@ yarn ui:pull v<X.Y.Z> # git subtree pull --squash, committed as "chore(ga
36
36
 
37
37
  ```sh
38
38
  sed -n '/^## \[<X.Y.Z>\]/,/^## \[<current>\]/p' layers/gallop-ui/CHANGELOG.md
39
- ls layers/gallop-ui/migrations/ layers/gallop-ui/docs/migrating-to-*.md
39
+ ls layers/gallop-ui/migrations/; cat layers/gallop-ui/docs/upgrading.md
40
40
  ```
41
41
 
42
42
  For each entry, decide: does this app call it (`git grep -n "<Component\|propName" -- app tests`), and does the call
43
- site need to change? Read the affected components' `.md` "Migrating" sections. A release that crosses a major
44
- version has a `docs/migrating-to-<version>.md` and a `migrations/<version>/` folder. Jumping several releases is
43
+ site need to change? Read the affected components' `.md` "Migrating" sections. Any release with renames has a
44
+ `migrations/<major.minor>/` folder, minor releases included (1.1 has one); `docs/upgrading.md` explains how to apply it. Jumping several releases is
45
45
  fine as long as you read every entry in between. The kit only knows the versions it has tables for, so check the
46
46
  migration doc for how far back it reaches.
47
47
 
48
- ## 3. Run the codemod on a breaking release
48
+ ## 3. Run the codemod whenever there's a newer table
49
+
50
+ Run it whenever `layers/gallop-ui/migrations/` has a folder newer than the version you came from, minor or major.
51
+
52
+ - **Minor releases (1.1, 1.2…) rename without breaking.** A renamed `pt` section keeps its old name as a deprecated
53
+ alias until the next major, and a renamed data attribute is rendered under both names. So the app renders the same
54
+ before the codemod, but logs one dev warning per old name: `[gallop-ui] <Component> pt "<old>" is deprecated`. Run
55
+ the codemod anyway so the warnings stop and the next major is a non-event.
56
+ - **A minor release can also add settings for existing apps.** 1.1's `icons` row writes `icons: "lucide"` into
57
+ `app/app.config.ts` so an existing app keeps its icons. Commit that line with the codemod output, and keep it.
58
+ - **Major releases break.** The old names are gone; the codemod and its checklist are how the app keeps working.
59
+ - An app already on the newest table gets `nothing to migrate` (exit 0).
49
60
 
50
61
  ```sh
51
62
  yarn ui:migrate --dry # the diff and counts; nothing written
@@ -69,6 +69,19 @@ a plain class chosen in script, so a caller's class always beats it. What that m
69
69
  - Overlays (Modal, Drawer, Popover, Tooltip, DropdownMenu) portal their box away: that box is `root`, so `class`
70
70
  still styles what you see. The backdrop is `overlay`.
71
71
 
72
+ ## Icons
73
+
74
+ - **One icon set per app: `gallopUi.icons`** in `app/app.config.ts`, `"phosphor"` (the layer's default, and a new
75
+ app's) or `"lucide"` (apps from before 1.1; `ui:migrate` writes it so they keep their glyphs). The layer's own
76
+ icons (chevrons, close, check, search…) follow it. Write the app's own icons in the same set (`ph:*` or
77
+ `lucide:*`), never a mix.
78
+ - The set's collection must be installed (`@iconify-json/ph` or `@iconify-json/lucide`) and listed in
79
+ `icon.serverBundle.collections`. The layer warns at build time when it isn't; otherwise the default icons would
80
+ silently be missing. `layers/gallop-ui/docs/icons.md` has the setup and a name map between the sets.
81
+ - An `icon` prop takes any Iconify name and is never mapped: `icon="ph:users"` stays Phosphor whatever the setting.
82
+ - To change single layer icons, give `gallopUi.icons` a map of roles instead of a preset name: `icons: { close: "ph:x-circle" }`
83
+ overrides that role over Phosphor. The roles are in `layers/gallop-ui/docs/icons.md`.
84
+
72
85
  ## Tokens and dark mode
73
86
 
74
87
  - **Dark mode is required in every app.** No light-only option, no pinned light colours.
@@ -76,6 +89,8 @@ a plain class chosen in script, so a caller's class always beats it. What that m
76
89
  strategy: the OS (`:root { color-scheme: light dark }`, the template default), or an attribute on `<html>`
77
90
  (`data-color-scheme="light|dark"`, set from a cookie by `useColorScheme()`; no flash on first paint).
78
91
  `TOKENS.md` has the contract; `theme/neutral.css` has every value.
92
+ - **A bare `border` is the `line` colour** (the layer's base style), not `currentColor`. Add a colour class only to
93
+ change it; `border-current` brings back the text colour.
79
94
  - In app code write token classes (`bg-surface`, `text-fg-muted`, `border-line`, `bg-danger-soft`), not
80
95
  `bg-white dark:bg-zinc-900`. Status colours are the `danger | warning | success | info` families.
81
96
  - `yarn ui:tokens` checks the app's theme CSS against the contract: what is missing, what still has an old name.
@@ -0,0 +1,8 @@
1
+ {
2
+ "name": "generate-documentation",
3
+ "description": "Write a client-facing guide with screenshots of the app (PDF, HTML, email or WhatsApp): answer a client's questions, or announce what shipped. Screenshots come from fictional demo data only; includes Playwright capture helpers and a PDF renderer with a page-review contact sheet.",
4
+ "version": "1.0.0",
5
+ "author": {
6
+ "name": "Gallop Systems"
7
+ }
8
+ }
@@ -0,0 +1,186 @@
1
+ ---
2
+ name: generate-documentation
3
+ description: Write a client-facing guide with screenshots of the app, as a PDF, HTML page, email or WhatsApp messages. Two modes. "answer" turns a client's questions into answers ("you can already do this, here's how", "we changed it, here's how it works", "here's why that happened and the fix"). "announce" turns merged work into an unsolicited "you can now…" note. Use when the user wants to send a client or their staff documentation, a how-to, release notes, a "what's new" or answers to their questions about a Gallop app, even if they don't say "documentation".
4
+ argument-hint: <pdf|html|email|whatsapp> <answer: pasted questions | announce: PR, branch, or "what merged since …">
5
+ ---
6
+
7
+ # Generate client documentation
8
+
9
+ You are writing for the client's staff: people who use the app every day and do
10
+ not read code. The result is a document they can follow alone, with real
11
+ screenshots of the app, that never shows real client data.
12
+
13
+ Arguments: a **format** (`pdf`, `html`, `email`, `whatsapp`; default `pdf`) and
14
+ what to document. Work out the **mode** from what you are given:
15
+
16
+ - **answer**: their questions or messages (pasted, a screenshot, an email). Each
17
+ question gets a section.
18
+ - **announce**: work that shipped (a PR, a branch, "everything merged since
19
+ Monday", or "the feature we just built"). Each user-visible change gets a
20
+ section. Nobody asked; you are telling them what they can now do.
21
+
22
+ If the format or the mode is unclear, ask once. Everything else you decide.
23
+
24
+ Format-specific output rules are in [formats.md](formats.md). Read it before
25
+ writing.
26
+
27
+ ## 1. Work out what is true
28
+
29
+ Do this before taking a single screenshot. A guide that confidently describes the
30
+ wrong thing is worse than no guide.
31
+
32
+ ### answer mode
33
+
34
+ Split the messages into separate questions (people send several in a row). For
35
+ each one, find out from the code, the in-app docs and the data (read-only) which
36
+ of these it is:
37
+
38
+ | Kind | Tag in the guide | What the section does |
39
+ |---|---|---|
40
+ | They can already do it | **You can do this already** | Numbered steps with screenshots |
41
+ | It needed a change, and we made it | **New** | How it works now, with screenshots, and the rules |
42
+ | A setting, data or setup problem | **A setting to fix** | Why it happened, then the fix |
43
+ | Not possible yet | (leave out, or **Not yet**) | Say so plainly; ask the user whether to build it before you write anything |
44
+ | Something only they can tell you | **Needs your answer** | Ask the question; don't guess |
45
+
46
+ Look at how the status or behaviour they're asking about is *derived*, not just
47
+ what it is called. "Why does it say Ready to send?" is usually answered by the
48
+ rule behind the label (a list of required items, a permission, a filter on an import).
49
+ Fixing the input to that rule is usually something they can do themselves.
50
+
51
+ For a question about records that are missing or wrong, check the actual records
52
+ (read-only) and the job that is supposed to bring them in (when it last ran,
53
+ whether it failed, what it filters on). If you cannot read production, give the
54
+ user a read-only query to run and wait for the result. Don't write the section on
55
+ a guess.
56
+
57
+ ### announce mode
58
+
59
+ Collect what shipped: `gh pr view <n> --json title,body,files`, `git log
60
+ <range>`, or the merged PRs since a date. Then keep only **user-visible
61
+ changes**. Drop refactors, tests, dependency bumps, internal tooling and
62
+ performance work nobody will notice.
63
+
64
+ For each change that is left:
65
+
66
+ - Read the diff for its real behaviour: what staff see, what they click, what
67
+ changes on its own, and what changes the day it goes live (existing records that
68
+ will suddenly look different). That last one is the thing clients most need to
69
+ hear in advance.
70
+ - Read the page's in-app doc if the repo has them (Gallop portals keep one beside
71
+ every page). If the PR changed behaviour and didn't update that doc, tell the
72
+ user. Don't paper over it in the guide.
73
+ - Check who can use it. Admin-only screens either go in an admin-only guide or
74
+ are marked "ask your admin".
75
+ - Check it has been merged, or deployed if the user says the client already has
76
+ it. Never announce work that is still in progress.
77
+
78
+ Several changes make one short "What's new" guide. One feature makes a one-pager.
79
+
80
+ ## 2. Try every step in the app
81
+
82
+ Before writing a step, do it in the running app on demo data: click every button
83
+ you are about to tell them to click. This is where wrong answers show up. A
84
+ move the guide said would work gets refused because the target record lacks a permission.
85
+ A setting turns out to be admin-only. A label on screen differs from the code's
86
+ name for it. When doing it shows your earlier answer was wrong, fix the answer,
87
+ and tell the user what changed.
88
+
89
+ ## 3. Screenshots, from demo data only
90
+
91
+ **Never capture from a database or environment holding real client data**, not
92
+ even "just to look". The pictures go to the client and may be forwarded on.
93
+
94
+ 1. **Find the safe data.** Read the repo's CLAUDE.md. Gallop Nuxt apps usually
95
+ have a fictional demo database and a dev server for doc screenshots (for
96
+ example `yarn docs:demo-data` and `yarn docs:dev`), plus a dev-only preview
97
+ login (`/api/auth/preview-login`). Build a **scratch copy** of the demo
98
+ database under its own name, and serve it on its own port, so you don't clash
99
+ with other sessions. If the repo has no fictional data source, stop and tell
100
+ the user. Don't screenshot real data, and don't invent data in a real database.
101
+ 2. **Stage the scenarios** in the scratch database with SQL: the record that
102
+ shows the problem, the setting before it is fixed, the record filed under the
103
+ wrong owner. Use the same kind of record the client described, with made-up names.
104
+ Remove anything that distracts from the point (an unrelated badge on the same
105
+ card).
106
+ 3. **Script the captures.** Copy [bin/capture-example.mjs](bin/capture-example.mjs)
107
+ to a scratch directory and write one step per section; it imports
108
+ [bin/shots.mjs](bin/shots.mjs). Run it from the app repo
109
+ (`cd <repo> && node <scratch>/capture.mjs <out-dir> [step]`), so Playwright
110
+ resolves from there. For each step, capture before, the action and after.
111
+ Ring the thing to click with `mark()`.
112
+ 4. **Look at every image** before using it. Common faults: the crop cuts off the
113
+ heading, the wrong column was clicked, a dialog is half-rendered, or the
114
+ picture shows a state from a previous run.
115
+ 5. **Reset what a step changed**, at the start of that step, so any step can be
116
+ re-run alone.
117
+
118
+ Capture gotchas:
119
+
120
+ - Find table columns by their header text, never by position: an index that was
121
+ right for one table clicks the neighbouring column of the next. A cell that
122
+ cycles states (Required → Optional → none) will have been changed by the wrong
123
+ click, so check the data and put it back.
124
+ - Write capture scripts as `.mjs`. A `.ts` file run through `tsx` outside a
125
+ `"type": "module"` package fails on top-level `await`
126
+ (`ERR_REQUIRE_ASYNC_MODULE`).
127
+ - Use `element()` for dialogs and drawers. For a panel, frame it with `shot()`
128
+ on its heading and its last line, or find it with
129
+ `xpath=ancestor::*[.//button[normalize-space()='…']][1]`.
130
+ - A Nuxt dev server freshly started after a lockfile change can 500 every
131
+ request with "IPC connection closed" while Vite re-optimizes. Restart it once.
132
+ - Image viewers, the Read tool included, can cache an image by its path.
133
+ When you regenerate a review image, give it a new name.
134
+
135
+ ## 4. Write it
136
+
137
+ The writing rules hold in every format:
138
+
139
+ - **Their words, the app's labels.** Head each section with their question or the
140
+ feature in plain words. Name every button, menu and field exactly as it appears
141
+ on screen, in bold. No file paths, routes, table names, code or developer terms.
142
+ - **Second person, short sentences, one action per step.**
143
+ - **Say why before how**, in a sentence: "An order says Ready to ship once every
144
+ required document is in, and this product line doesn't require the signed
145
+ form." Then the steps.
146
+ - **Say who can do it.** If a step needs an admin, or a particular sign-in, say so
147
+ at the top of the guide and at the step.
148
+ - **Say what else it changes.** A setting changed for one record usually applies
149
+ to all of them. Say so, and give the narrower alternative when there is one.
150
+ - **Warn about day one.** If going live will change how many existing records
151
+ look, say what they'll see and that it is expected.
152
+ - **Warn about doing both.** When there are two ways to fix something and doing
153
+ both creates a duplicate, say "pick one".
154
+ - **"Please confirm first"** when the right fix depends on a fact only they know
155
+ (is this supplier the contract holder, or working under someone else's?). Give both branches.
156
+ - **Note the demo data** once, near the top: the screenshots use made-up records,
157
+ so the names differ but the screens are the same.
158
+ - Don't apologise, don't mention AI, and don't describe how you investigated.
159
+
160
+ ## 5. Render, review, deliver
161
+
162
+ - **pdf and html:** start from [templates/guide.html](templates/guide.html) (its
163
+ header comment lists the building blocks), then render with
164
+ `node <skill-dir>/bin/render.mjs <guide.html> <out.pdf> --footer "<App name>"`,
165
+ run from the app repo. **Look at the contact sheet it prints.** Fix a heading
166
+ stranded at the foot of a page, a page holding a single note, or a figure
167
+ separated from its step: use `.keep` wrappers, a smaller figure width, or move a
168
+ note above its figures. Re-render, and look again.
169
+ - **email and whatsapp:** see [formats.md](formats.md).
170
+ - Save the deliverable where the user can open it, and hand it over (attach it
171
+ where your environment can). **Never send it yourself.** Emails are drafts,
172
+ WhatsApp text is for the user to paste, and publishing anything waits for
173
+ their yes.
174
+ - Then clean up: stop the dev servers you started, drop the scratch databases,
175
+ and undo any launch-config entries you added. Keep the capture script in
176
+ scratch so the user can ask for a retake.
177
+
178
+ In your reply, give the user the file, a line per section, and anything you
179
+ found that changes an earlier answer. Also list any open question the guide asks
180
+ the client to confirm.
181
+
182
+ ## Contributing Back
183
+
184
+ This skill grows by capturing what it missed. If you just worked through something in this domain that this skill did not cover — an error you had to figure out, a behavior that contradicts what is documented above, a workflow knot — ask the user: **"Want me to contribute this back to the generate-documentation skill?"**
185
+
186
+ If yes, run `/contribute-skill`. If that command is not available, do the equivalent inline: distill the generic lesson (placeholders only — no project names, IDs, domains, or secrets), then branch or fork [gallop-systems/agent-skills](https://github.com/gallop-systems/agent-skills) and open a PR editing this skill.
@@ -0,0 +1,53 @@
1
+ /**
2
+ * Example per-job capture script. Copy it to a scratch directory, edit the
3
+ * steps, and run it from the app repo:
4
+ *
5
+ * cd <app repo> && node <scratch>/capture.mjs <out-dir> [only-step]
6
+ *
7
+ * Paths, labels and SQL below are placeholders for a typical Gallop Nuxt app.
8
+ */
9
+ import { open, run, sql } from "<skill-dir>/bin/shots.mjs";
10
+
11
+ const [outDir, only] = process.argv.slice(2);
12
+ const BASE = "http://localhost:3100"; // the demo-data dev server, never one on real data
13
+ const DB = "postgresql://localhost:5432/<app>-docs-scratch"; // a scratch copy of the demo DB
14
+ const db = (q) => sql(DB, q);
15
+
16
+ const { browser, page, kit } = await open({ base: BASE, login: "/api/auth/preview-login" });
17
+ kit.out(outDir);
18
+
19
+ await run(
20
+ {
21
+ // A thing the user can already do: show before, the click, and after.
22
+ async setting() {
23
+ db("update widgets set required = false where code = 'example'"); // reset, so the step re-runs
24
+ await kit.go("/admin/widgets");
25
+ const table = page.locator("table").first();
26
+ const heads = await table.locator("thead th").allInnerTexts();
27
+ const col = heads.findIndex((h) => h.trim() === "Example"); // find columns by header text, never by index
28
+ const cell = table.locator("tbody tr", { hasText: "Row label" }).first().locator("th, td").nth(col);
29
+ await kit.mark(cell);
30
+ await kit.shot("setting-1-before", [table.locator("thead"), cell]);
31
+ await kit.unmark();
32
+ await cell.locator("button").first().click();
33
+ await page.waitForTimeout(1000);
34
+ await kit.mark(cell);
35
+ await kit.shot("setting-2-after", [table.locator("thead"), cell]);
36
+ await kit.unmark();
37
+ },
38
+
39
+ // A dialog or drawer: shoot the element itself.
40
+ async dialog() {
41
+ await kit.go("/records/1");
42
+ await page.getByRole("button", { name: "Outcome" }).first().click();
43
+ await kit.settle(500);
44
+ const dialog = page.getByRole("dialog").last();
45
+ await kit.mark(dialog.getByRole("button", { name: "Transfer…" }));
46
+ await kit.element("dialog-1", dialog);
47
+ await kit.unmark();
48
+ },
49
+ },
50
+ { only },
51
+ );
52
+
53
+ await browser.close();
@@ -0,0 +1,82 @@
1
+ /**
2
+ * Render a guide's HTML to PDF, and make a contact sheet of its pages to review.
3
+ * Run it from the app repo, so Playwright resolves from there:
4
+ *
5
+ * cd <app repo> && node <skill-dir>/bin/render.mjs <guide.html> <out.pdf> [--footer "Product name"]
6
+ *
7
+ * Prints the page count and the path of `<out>.sheet.png` (every page side by
8
+ * side). Look at the sheet before sending: it is how you catch a heading left at
9
+ * the bottom of a page, a page holding one note, or a screenshot split from its
10
+ * step. The sheet needs `pdftoppm` (poppler) and ImageMagick; without them it is
11
+ * skipped and only the page count is printed.
12
+ */
13
+ import { createRequire } from "node:module";
14
+ import { execFileSync } from "node:child_process";
15
+ import fs from "node:fs";
16
+ import os from "node:os";
17
+ import path from "node:path";
18
+
19
+ const require = createRequire(path.join(process.cwd(), "package.json"));
20
+ const { chromium } = require("playwright");
21
+
22
+ const args = process.argv.slice(2);
23
+ const footerAt = args.indexOf("--footer");
24
+ const footer = footerAt >= 0 ? args.splice(footerAt, 2)[1] : "";
25
+ const [html, out] = args.map((p) => path.resolve(p));
26
+ if (!html || !out) {
27
+ console.error("usage: render.mjs <guide.html> <out.pdf> [--footer text]");
28
+ process.exit(1);
29
+ }
30
+
31
+ const escape = (s) => s.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
32
+ const browser = await chromium.launch();
33
+ const page = await browser.newPage();
34
+ await page.goto(`file://${html}`, { waitUntil: "networkidle" });
35
+ await page.evaluate(() => document.fonts.ready);
36
+ await page.pdf({
37
+ path: out,
38
+ format: "Letter",
39
+ printBackground: true,
40
+ preferCSSPageSize: true,
41
+ displayHeaderFooter: true,
42
+ headerTemplate: "<span></span>",
43
+ footerTemplate: `<div style="font-size:7pt;color:#8a847b;width:100%;text-align:center;font-family:sans-serif">${
44
+ footer ? `${escape(footer)} · ` : ""
45
+ }<span class="pageNumber"></span> of <span class="totalPages"></span></div>`,
46
+ });
47
+ await browser.close();
48
+
49
+ const has = (bin) => {
50
+ try {
51
+ execFileSync("which", [bin], { stdio: "ignore" });
52
+ return true;
53
+ } catch {
54
+ return false;
55
+ }
56
+ };
57
+
58
+ if (has("pdftoppm") && has("magick")) {
59
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), "gd-pages-"));
60
+ execFileSync("pdftoppm", ["-r", "60", "-png", out, path.join(dir, "p")]);
61
+ const pages = fs.readdirSync(dir).filter((f) => f.endsWith(".png")).sort((a, b) =>
62
+ a.localeCompare(b, undefined, { numeric: true }),
63
+ );
64
+ // A new name every run: an image viewer that caches by path would show the old sheet.
65
+ const sheet = out.replace(/\.pdf$/i, `.sheet-${Date.now()}.png`);
66
+ const cols = Math.min(5, pages.length);
67
+ execFileSync("magick", [
68
+ "montage",
69
+ ...pages.map((p) => path.join(dir, p)),
70
+ "-tile", `${cols}x`,
71
+ "-geometry", "+6+6",
72
+ "-background", "#999",
73
+ sheet,
74
+ ]);
75
+ console.log(`${pages.length} pages`);
76
+ console.log(`sheet: ${sheet}`);
77
+ console.log(`pages: ${dir}`);
78
+ } else {
79
+ const count = (fs.readFileSync(out, "latin1").match(/\/Type\s*\/Page[^s]/g) ?? []).length;
80
+ console.log(`${count} pages (install poppler and imagemagick for a contact sheet)`);
81
+ }
82
+ console.log(`pdf: ${out}`);
@@ -0,0 +1,139 @@
1
+ /**
2
+ * Screenshot helpers for /generate-documentation.
3
+ *
4
+ * Import this from a per-job capture script (see capture-example.mjs). Playwright
5
+ * is resolved from the APP repo (the current working directory), not from this
6
+ * skill, so nothing needs installing here:
7
+ *
8
+ * cd <app repo> && node <scratch>/capture.mjs <out-dir> [only-step]
9
+ *
10
+ * Every helper works on one page that is already signed in. Captures are 2x,
11
+ * light theme, reduced motion, with dev chrome (Nuxt devtools, loading bar,
12
+ * scrollbars) hidden, so re-running a step gives the same picture.
13
+ */
14
+ import { createRequire } from "node:module";
15
+ import { execFileSync } from "node:child_process";
16
+ import path from "node:path";
17
+ import fs from "node:fs";
18
+
19
+ const require = createRequire(path.join(process.cwd(), "package.json"));
20
+ const { chromium } = require("playwright");
21
+
22
+ export const STILL_CSS = `
23
+ *, *::before, *::after { transition: none !important; animation: none !important; caret-color: transparent !important; }
24
+ nuxt-devtools-frame, nuxt-devtools-inspect-panel, #nuxt-devtools-container, #nuxt-devtools-anchor,
25
+ [id^="nuxt-devtools"], #vue-tracer-overlay, vite-error-overlay, .nuxt-loading-indicator { display: none !important; }
26
+ ::-webkit-scrollbar { display: none; }
27
+ .gd-mark { outline: 3px solid #e4572e !important; outline-offset: 3px; border-radius: 6px; }
28
+ `;
29
+
30
+ /**
31
+ * Open a browser signed in to `base`.
32
+ * `login` is a path that signs in on GET (a dev/preview login route), or an
33
+ * async function `(page) => {}` that signs in some other way.
34
+ */
35
+ export async function open({ base, login, width = 1440, height = 900, timeZone = "America/New_York" }) {
36
+ const browser = await chromium.launch();
37
+ const context = await browser.newContext({
38
+ viewport: { width, height },
39
+ deviceScaleFactor: 2,
40
+ colorScheme: "light",
41
+ reducedMotion: "reduce",
42
+ timezoneId: timeZone,
43
+ });
44
+ // esbuild's keepNames helper, which some dev bundles reference before defining.
45
+ await context.addInitScript("globalThis.__name = (fn) => fn;");
46
+ const page = await context.newPage();
47
+ if (typeof login === "string") await page.goto(new URL(login, base).href);
48
+ else if (login) await login(page);
49
+ return { browser, page, kit: kit(page, base) };
50
+ }
51
+
52
+ function kit(page, base) {
53
+ let outDir = ".";
54
+ const k = {
55
+ page,
56
+ /** Where `shot`/`full`/`element` write. */
57
+ out(dir) {
58
+ outDir = dir;
59
+ fs.mkdirSync(dir, { recursive: true });
60
+ },
61
+ /** Go to a path and wait for it to be still. */
62
+ async go(p) {
63
+ await page.goto(new URL(p, base).href);
64
+ await k.settle();
65
+ },
66
+ /** Wait for the network, fonts and a beat for skeletons; re-apply the still CSS. */
67
+ async settle(ms = 700) {
68
+ await page.waitForLoadState("networkidle").catch(() => {});
69
+ await page.addStyleTag({ content: STILL_CSS });
70
+ await page.evaluate(() => document.fonts.ready);
71
+ await page.waitForTimeout(ms);
72
+ },
73
+ /** Ring the given elements (call `unmark` after the shot). */
74
+ async mark(...locators) {
75
+ for (const l of locators) await l.evaluate((el) => el.classList.add("gd-mark"));
76
+ },
77
+ async unmark() {
78
+ await page.evaluate(() =>
79
+ document.querySelectorAll(".gd-mark").forEach((el) => el.classList.remove("gd-mark")),
80
+ );
81
+ },
82
+ /**
83
+ * Screenshot the box that covers every locator, padded. Use two locators to
84
+ * frame a region (a heading and the last thing under it).
85
+ */
86
+ async shot(name, locators, pad = 14) {
87
+ for (const l of locators) await l.scrollIntoViewIfNeeded().catch(() => {});
88
+ const boxes = [];
89
+ for (const l of locators) {
90
+ const box = await l.boundingBox();
91
+ if (!box) throw new Error(`shot ${name}: a locator is not visible`);
92
+ boxes.push(box);
93
+ }
94
+ const vw = page.viewportSize().width;
95
+ const x = Math.max(0, Math.min(...boxes.map((b) => b.x)) - pad);
96
+ const y = Math.max(0, Math.min(...boxes.map((b) => b.y)) - pad);
97
+ const right = Math.min(vw, Math.max(...boxes.map((b) => b.x + b.width)) + pad);
98
+ const bottom = Math.max(...boxes.map((b) => b.y + b.height)) + pad;
99
+ await page.screenshot({
100
+ path: path.join(outDir, `${name}.png`),
101
+ clip: { x, y, width: right - x, height: bottom - y },
102
+ });
103
+ console.log("shot", name);
104
+ },
105
+ /** One element exactly (a dialog, a drawer). */
106
+ async element(name, locator) {
107
+ await locator.screenshot({ path: path.join(outDir, `${name}.png`) });
108
+ console.log("shot", name);
109
+ },
110
+ /** The whole viewport. */
111
+ async full(name) {
112
+ await page.screenshot({ path: path.join(outDir, `${name}.png`) });
113
+ console.log("shot", name);
114
+ },
115
+ };
116
+ return k;
117
+ }
118
+
119
+ /**
120
+ * Run the named steps in order, or just `only`. Each step is an async function
121
+ * taking the kit. Steps should reset the demo data they change (with `sql`) so
122
+ * any one of them can be re-run alone.
123
+ */
124
+ export async function run(steps, { only } = {}) {
125
+ for (const [name, step] of Object.entries(steps)) {
126
+ if (only && only !== name) continue;
127
+ await step();
128
+ }
129
+ }
130
+
131
+ /** Run SQL against a SCRATCH database (never a real-data one). */
132
+ export function sql(databaseUrl, query) {
133
+ if (!/demo|docs|scratch|fixture|seed|test/i.test(databaseUrl)) {
134
+ throw new Error(
135
+ `refusing to write to ${databaseUrl}: name it as a demo/docs/scratch database, or edit this guard deliberately`,
136
+ );
137
+ }
138
+ return execFileSync("psql", [databaseUrl, "-qAtc", query], { encoding: "utf8" });
139
+ }
@@ -0,0 +1,71 @@
1
+ # Output formats
2
+
3
+ The content is the same in every format: one section per answer or feature, each
4
+ with the kind of answer, the why, the steps and the screenshots. What changes is
5
+ how much fits and how it is delivered. Whatever the format, you prepare it and
6
+ the user sends it.
7
+
8
+ ## pdf (default)
9
+
10
+ For anything with more than two or three steps, or when the client will print
11
+ it or forward it.
12
+
13
+ - Start from `templates/guide.html`. Page 1 has the title, the date, who it is
14
+ for, a numbered contents list (one line per section, with the outcome), the
15
+ demo-data note and any sign-in or admin note. The first section may start
16
+ under it.
17
+ - One `<section>` per answer or feature. Each section after the first starts a
18
+ new page.
19
+ - Screenshot widths: `w-s` for a chip, a header or a single control; `w-m` for a
20
+ dialog, a card or a panel; `w-l` for a wide table. Before/after goes in a
21
+ `.pair`.
22
+ - Render with `bin/render.mjs` and review the contact sheet. A clean guide has no
23
+ stranded headings, no page holding a single note, and no figure on a different
24
+ page from its step. Eight pages for four answers is normal.
25
+ - File name: `<App> - <what it is> - <reader or date>.pdf`, for example
26
+ `Portal - answers for Dana.pdf` or `Portal - what's new - March 2026.pdf`.
27
+
28
+ ## html
29
+
30
+ The same file as the pdf, before rendering, for the web: a link the client can
31
+ open, or a page in the app's own docs.
32
+
33
+ - Keep `shots/` beside the HTML and use relative image paths.
34
+ - If it is going to be published somewhere (an artifact, a docs site), that is the
35
+ user's call. Prepare it, and ask before publishing.
36
+
37
+ ## email
38
+
39
+ For one to three short answers, or an announcement of one or two features.
40
+
41
+ - Write a **draft** in the user's voice, never sent by you. Give the subject, the
42
+ body and the list of attachments. If the user has an email tool connected,
43
+ create a draft there only if they ask.
44
+ - Subject: what it's about, in their words ("Your questions about order
45
+ documents", "New: orders now wait for the signed form").
46
+ - Body: a one-line greeting, then one short paragraph per answer: the answer
47
+ first, then the steps as a numbered list with the exact labels in bold. Refer to
48
+ the screenshots by number ("see screenshot 2"). End with one line offering
49
+ help.
50
+ - Attach the screenshots as numbered PNGs (`1-documents-setting.png`, …), in the
51
+ order the body refers to them. For more than about five screenshots, attach
52
+ the pdf instead and keep the body to a summary of each answer.
53
+
54
+ ## whatsapp
55
+
56
+ For quick answers to someone who asked in a chat.
57
+
58
+ - **One message per answer**, short enough to read on a phone (about 600
59
+ characters at most). Put a number on each when there are several ("1/3").
60
+ - WhatsApp formatting only: `*bold*` (single asterisks), `_italic_`, plain line
61
+ breaks, and numbered steps as `1.` lines. No headings, tables, links in
62
+ markdown syntax, or nested lists.
63
+ - Bold the exact button and menu names: `Go to *Admin → Documents*`.
64
+ - Screenshots go as separate images, each with a one-line caption, sent after
65
+ the message they belong to. List them in order: message 1, image 1a, image 1b,
66
+ message 2, and so on. Two images per answer at most; crop tight, because they
67
+ are seen on a phone.
68
+ - Give the user the messages as plain text blocks, ready to paste, plus the image
69
+ files in order. You never send them.
70
+ - If an answer needs more than four steps, say so in the message and send the
71
+ pdf for that part.
@@ -0,0 +1,116 @@
1
+ <!doctype html>
2
+ <!--
3
+ The guide layout for pdf and html output. Copy it next to the shots/ folder,
4
+ replace the example content, and render with bin/render.mjs.
5
+
6
+ Building blocks (all in the <style> below):
7
+ .toc numbered list of every answer, on page 1
8
+ .tag.can/.new/.data/.ask
9
+ what kind of answer this is: "You can do this already",
10
+ "New", "A setting or data fix", "Needs your answer"
11
+ blockquote.ask the client's own words, quoted
12
+ ol.steps numbered steps; each <li> holds its text and its figure
13
+ figure.w-s/.w-m/.w-l
14
+ screenshot widths: small (a chip or a header), medium (a
15
+ dialog, a card), large (a full-width table)
16
+ .pair + .arrow before → after, side by side
17
+ .note / .note.warn
18
+ grey for "good to know", amber for "watch out"
19
+ .keep wrap a heading, its text and its figure so a page break
20
+ cannot separate them
21
+
22
+ Page breaks: each top-level <section> after the first starts a new page. Keep
23
+ sections to one per answer or feature; never split one answer into two
24
+ sections just to start a page.
25
+ -->
26
+ <html lang="en">
27
+ <head>
28
+ <meta charset="utf-8">
29
+ <title>TITLE</title>
30
+ <link href="https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@400;500;600;700&display=swap" rel="stylesheet">
31
+ <style>
32
+ @page { size: Letter; margin: 0.6in 0.65in 0.7in; }
33
+ :root { --ink: #23201c; --muted: #6b655d; --line: #e6e1d9; --accent: #1f4d3a; --soft: #f4f1ec; --amber: #9a5b00; --amber-soft: #fdf6e3; --blue: #24467a; --blue-soft: #e7eefb; --green-soft: #e5f2ea; }
34
+ * { box-sizing: border-box; }
35
+ body { font-family: "Plus Jakarta Sans", system-ui, sans-serif; color: var(--ink); font-size: 10.5pt; line-height: 1.5; margin: 0; }
36
+ h1 { font-size: 22pt; margin: 0 0 4pt; letter-spacing: -0.01em; }
37
+ .sub { color: var(--muted); margin: 0 0 18pt; }
38
+ h2 { font-size: 15pt; margin: 0 0 4pt; letter-spacing: -0.005em; break-after: avoid; }
39
+ h3 { font-size: 11pt; margin: 14pt 0 4pt; break-after: avoid; }
40
+ h3 + p { break-before: avoid; }
41
+ section + section { break-before: page; }
42
+ blockquote.ask { border-left: 3px solid var(--line); padding: 2pt 0 2pt 10pt; color: var(--muted); font-style: italic; margin: 6pt 0 10pt; }
43
+ .tag { display: inline-block; font-size: 8.5pt; font-weight: 600; padding: 2pt 7pt; border-radius: 99px; margin-bottom: 6pt; }
44
+ .tag.can { background: var(--green-soft); color: var(--accent); }
45
+ .tag.new { background: var(--blue-soft); color: var(--blue); }
46
+ .tag.data, .tag.ask { background: var(--amber-soft); color: var(--amber); }
47
+ ol.steps { padding-left: 0; list-style: none; counter-reset: s; margin: 8pt 0; }
48
+ ol.steps > li { counter-increment: s; position: relative; padding-left: 26pt; margin: 0 0 12pt; break-inside: avoid; }
49
+ ol.steps > li::before { content: counter(s); position: absolute; left: 0; top: 0; width: 18pt; height: 18pt; border-radius: 50%; background: var(--accent); color: #fff; font-size: 9pt; font-weight: 600; display: flex; align-items: center; justify-content: center; }
50
+ figure { margin: 6pt 0 0; break-inside: avoid; }
51
+ figure img { display: block; max-width: 100%; border: 1px solid var(--line); border-radius: 6px; }
52
+ figcaption { font-size: 8.5pt; color: var(--muted); margin-top: 3pt; }
53
+ .w-s img { max-width: 2.4in; } .w-m img { max-width: 4.2in; } .w-l img { max-width: 100%; }
54
+ .pair { display: flex; gap: 14pt; align-items: flex-end; break-inside: avoid; }
55
+ .pair figure { flex: 0 0 auto; }
56
+ .arrow { font-size: 16pt; color: var(--muted); padding-bottom: 18pt; }
57
+ .note { background: var(--soft); border-radius: 6px; padding: 8pt 11pt; margin: 10pt 0; break-inside: avoid; }
58
+ .note.warn { background: var(--amber-soft); }
59
+ .note > strong:first-child { display: block; margin-bottom: 2pt; }
60
+ .keep { break-inside: avoid; }
61
+ ul { margin: 4pt 0 8pt; padding-left: 15pt; } li { margin: 2pt 0; }
62
+ .toc { border: 1px solid var(--line); border-radius: 8px; padding: 10pt 14pt; }
63
+ .toc li { margin: 4pt 0; }
64
+ .small { font-size: 8.5pt; color: var(--muted); }
65
+ b, strong { font-weight: 600; }
66
+ </style>
67
+ </head>
68
+ <body>
69
+
70
+ <section>
71
+ <h1>TITLE</h1>
72
+ <p class="sub">DATE · for READER</p>
73
+
74
+ <div class="toc">
75
+ <ol>
76
+ <li><b>First answer or feature, in the reader's words.</b> One line on the outcome.</li>
77
+ <li><b>Second.</b> One line.</li>
78
+ </ol>
79
+ </div>
80
+ <p class="small" style="margin-top:14pt">The screenshots come from a demo copy of APP filled with made-up records, so you'll see different names, but the screens and buttons are the same.</p>
81
+
82
+ <!-- The first answer may start on page 1, under the contents. -->
83
+ <h2 style="margin-top:22pt">1. Heading in the reader's words</h2>
84
+ <span class="tag can">You can do this already</span>
85
+ <blockquote class="ask">"Their question, quoted."</blockquote>
86
+ <p>Why it behaves the way it does, in one short paragraph.</p>
87
+ <ol class="steps">
88
+ <li>Go to <b>Exact label</b>, then <b>Exact label</b>.
89
+ <figure class="w-l"><img src="shots/example-1.png"></figure></li>
90
+ <li>Click <b>Exact label</b>. It saves straight away.
91
+ <div class="pair">
92
+ <figure class="w-s"><img src="shots/example-2-before.png"><figcaption>Before</figcaption></figure>
93
+ <div class="arrow">→</div>
94
+ <figure class="w-s"><img src="shots/example-2-after.png"><figcaption>After</figcaption></figure>
95
+ </div></li>
96
+ </ol>
97
+ <div class="note"><strong>Good to know</strong>
98
+ <ul><li>What else this changes.</li><li>The alternative for a single record.</li></ul>
99
+ </div>
100
+ </section>
101
+
102
+ <section>
103
+ <h2>2. A new feature</h2>
104
+ <span class="tag new">New in APP</span>
105
+ <p>What you can now do, and why it helps you. You don't need to do anything; it works on its own.</p>
106
+ <div class="keep">
107
+ <h3>Where you'll see it</h3>
108
+ <p>One sentence pointing at the screenshot.</p>
109
+ <figure class="w-m"><img src="shots/feature-1.png"><figcaption>What's circled.</figcaption></figure>
110
+ </div>
111
+ <div class="note"><strong>The rules</strong><ul><li>Rule, in the on-screen words.</li></ul></div>
112
+ <div class="note warn"><strong>What to expect the first day</strong>What changes as soon as this is live.</div>
113
+ </section>
114
+
115
+ </body>
116
+ </html>