@gallopsystems/agent-skills 1.31.2 → 1.33.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.
Files changed (48) hide show
  1. package/README.md +24 -0
  2. package/package.json +1 -1
  3. package/plugins/gallop-ui/skills/gallop-ui/SKILL.md +1 -1
  4. package/plugins/gallop-ui/skills/gallop-ui/api-principles.md +5 -2
  5. package/plugins/gallop-ui/skills/gallop-ui/finding-a-component.md +5 -0
  6. package/plugins/gallop-ui/skills/gallop-ui/pitfalls.md +5 -0
  7. package/plugins/gallop-ui/skills/gallop-ui/pulling-updates.md +14 -3
  8. package/plugins/gallop-ui/skills/gallop-ui/using-in-an-app.md +15 -0
  9. package/plugins/generate-documentation/.claude-plugin/plugin.json +8 -0
  10. package/plugins/generate-documentation/skills/generate-documentation/SKILL.md +186 -0
  11. package/plugins/generate-documentation/skills/generate-documentation/bin/capture-example.mjs +53 -0
  12. package/plugins/generate-documentation/skills/generate-documentation/bin/render.mjs +82 -0
  13. package/plugins/generate-documentation/skills/generate-documentation/bin/shots.mjs +139 -0
  14. package/plugins/generate-documentation/skills/generate-documentation/formats.md +71 -0
  15. package/plugins/generate-documentation/skills/generate-documentation/templates/guide.html +116 -0
  16. package/plugins/kysely-postgres/skills/kysely-postgres/SKILL.md +17 -3
  17. package/plugins/kysely-postgres/skills/kysely-postgres/references/common-pitfalls.md +91 -0
  18. package/plugins/kysely-postgres/skills/kysely-postgres/references/concurrency-and-transactions.md +155 -0
  19. package/plugins/kysely-postgres/skills/kysely-postgres/references/full-text-and-grouping.md +13 -0
  20. package/plugins/kysely-postgres/skills/kysely-postgres/references/migrations-and-codegen.md +50 -0
  21. package/plugins/kysely-postgres/skills/kysely-postgres/references/query-patterns.md +65 -0
  22. package/plugins/kysely-postgres/skills/kysely-postgres/references/set-lateral-locking.md +2 -0
  23. package/plugins/nitro-testing/skills/nitro-testing/SKILL.md +10 -0
  24. package/plugins/nitro-testing/skills/nitro-testing/proving-the-claim.md +240 -0
  25. package/plugins/nitro-testing/skills/nitro-testing/transaction-rollback.md +1 -0
  26. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/SKILL.md +23 -12
  27. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/auth-patterns.md +50 -0
  28. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/error-handling.md +34 -3
  29. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/examples/validation-endpoint.ts +2 -2
  30. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/fetch-patterns.md +57 -0
  31. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/nitro-tasks.md +2 -0
  32. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/server-services.md +100 -1
  33. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/sse.md +1 -1
  34. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/validation.md +120 -14
  35. package/plugins/pr-review/.claude-plugin/plugin.json +8 -0
  36. package/plugins/pr-review/skills/pr-review/SKILL.md +68 -0
  37. package/plugins/pr-review/skills/pr-review/brief-prompt.md +33 -0
  38. package/plugins/pr-review/skills/pr-review/focus-areas.md +63 -0
  39. package/plugins/pr-review/skills/pr-review/judge.md +29 -0
  40. package/plugins/vue-nuxt/skills/vue-nuxt/SKILL.md +29 -0
  41. package/plugins/vue-nuxt/skills/vue-nuxt/async-state.md +229 -0
  42. package/plugins/vue-nuxt/skills/vue-nuxt/component-authoring.md +45 -0
  43. package/plugins/vue-nuxt/skills/vue-nuxt/editing-forms.md +137 -0
  44. package/plugins/vue-nuxt/skills/vue-nuxt/formatters.md +8 -0
  45. package/plugins/vue-nuxt/skills/vue-nuxt/slots.md +16 -0
  46. package/plugins/vue-nuxt/skills/vue-nuxt/template-idioms.md +52 -0
  47. package/plugins/vue-nuxt/skills/vue-nuxt/v-model.md +2 -1
  48. package/plugins/vue-nuxt/skills/vue-nuxt/watch.md +5 -1
package/README.md CHANGED
@@ -21,6 +21,8 @@ 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
25
+ /plugin install pr-review@gallop-systems-agent-skills
24
26
  ```
25
27
 
26
28
  ## Updating
@@ -180,6 +182,28 @@ Covers:
180
182
  - Pulling a release: `yarn ui:pull`, `ui:migrate`, `ui:tokens`, `ui:check`, merge-commit subtree PRs
181
183
  - Changing the layer, checking every app with `ui:impact` and screenshot sweeps, and working rules learned the hard way
182
184
 
185
+ ### generate-documentation
186
+
187
+ Write a client-facing guide with real screenshots of the app, as a PDF, HTML page, email draft or WhatsApp messages.
188
+ Run it as `/generate-documentation <format> <what to document>`.
189
+
190
+ Covers:
191
+ - 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)
192
+ - Checking each answer in the code and the running app before writing it
193
+ - Screenshots from a scratch copy of the app's fictional demo data only, never real data
194
+ - `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)
195
+ - A guide template, writing rules for non-technical readers, and per-format rules
196
+
197
+ ### pr-review
198
+
199
+ Review a branch or pull request for defects before a human sees it.
200
+
201
+ Covers:
202
+ - Building a context brief with a cheap model: the change's goal, callers, sibling code and stated claims
203
+ - Running `codex review` with the brief
204
+ - Judging every finding against the code (five keep-rules) before fixing or reporting it
205
+ - Deep mode: one focused reviewer per concern (tests, docs, migrations, UI state, races, agreeing paths, inputs, access)
206
+
183
207
  ## Contributing a Lesson Back
184
208
 
185
209
  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.2",
3
+ "version": "1.33.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": {
@@ -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,
@@ -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
@@ -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
@@ -40,12 +40,23 @@ 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 `migrations/<version>/` folder; `docs/upgrading.md` explains how to apply it. 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
+ }