@jesdi/skills 0.0.13 → 0.0.15

package/skills/prototype/UI.md

@@ -0,0 +1,99 @@
+# UI Prototype
+
+Generate **several radically different UI variations** inside one self-contained HTML file, switchable from a floating bottom bar. The user flips between variants in the page, picks one (or steals bits from each), then throws the rest away.
+
+If the question is about logic/state rather than what something looks like, this is the wrong branch. Use [LOGIC.md](LOGIC.md).
+
+## When this is the right shape
+
+- "What should this page look like?"
+- "I want to see a few options for this dashboard before committing."
+- "Try a different layout for the settings screen."
+- Any time the user would otherwise spend a day picking between three vague mockups in their head.
+
+## Why one file and not routes in the app
+
+A prototype mounted in the running application is easier to judge because it sits among the real header, sidebar and data, but it needs a dev server and a browser on the machine that built it. The reviewer here may be looking at a file served from a machine with neither, on a phone. So the page recreates enough of the surrounding app to judge the variant against (a header strip, a sidebar outline, realistic density of sample data) and nothing more. Every variant lives in the same file, so what is being compared is the structure, not the chrome.
+
+## Process
+
+### 1. State the question and pick N
+
+Default to **3 variants**. More than 5 stops being radically different and starts being noise, so cap there.
+
+Write down the plan in one line at the top of the file, visible on the page:
+
+> "Three variants of the settings page. Use the bar at the bottom or ←/→ to switch."
+
+### 2. Generate radically different variants
+
+Draft each variant. Hold each one to:
+
+- The page's purpose and the data it has access to. Inline realistic sample data once and let every variant render it.
+- The project's look: copy its colours, fonts, spacing and border radii into the page's `<style>` so a variant does not look foreign. Do not import the real component library; approximate it in plain CSS.
+- A clear name, e.g. `A (Sidebar layout)`, `B (Cards)`, `C (Single column)`.
+
+Variants must be **structurally different**: different layout, different information hierarchy, different primary affordance, not just different colours. Three slightly-tweaked card grids isn't a UI prototype, it's wallpaper. If two drafts come out too similar, redo one with explicit "do not use a card grid" guidance.
+
+### 3. Wire them together
+
+Each variant is one `<section data-variant="A">` (B, C, …) in the file. Only the section for the current variant is displayed. The current variant is stored in the URL hash (`#variant=B`) so a specific one can be linked and survives reload:
+
+```html
+<!-- pseudo-code, adapt freely -->
+<section data-variant="A"> … </section>
+<section data-variant="B"> … </section>
+<section data-variant="C"> … </section>
+<div id="switcher"><button data-dir="-1">←</button><span id="label"></span><button data-dir="1">→</button></div>
+<script>
+  const variants = [...document.querySelectorAll('[data-variant]')];
+  const names = { A: 'Sidebar layout', B: 'Cards', C: 'Single column' };
+  function current() { return (location.hash.match(/variant=(\w)/) || [, variants[0].dataset.variant])[1]; }
+  function show(key) {
+    variants.forEach(s => s.hidden = s.dataset.variant !== key);
+    label.textContent = `${key} (${names[key]})`;
+    if (current() !== key) location.hash = `variant=${key}`;
+  }
+  function cycle(dir) {
+    const keys = variants.map(s => s.dataset.variant);
+    show(keys[(keys.indexOf(current()) + dir + keys.length) % keys.length]);
+  }
+  document.querySelectorAll('#switcher button').forEach(b => b.onclick = () => cycle(+b.dataset.dir));
+  addEventListener('keydown', e => {
+    if (e.target.matches('input, textarea, [contenteditable]')) return;
+    if (e.key === 'ArrowLeft') cycle(-1); if (e.key === 'ArrowRight') cycle(1);
+  });
+  addEventListener('hashchange', () => show(current()));
+  show(current());
+</script>
+```
+
+### 4. Build the floating switcher
+
+A small fixed-position bar at the bottom-centre of the screen with three pieces:
+
+- **Left arrow**: cycles to the previous variant (wraps around).
+- **Variant label**: shows the current variant key and its name, e.g. `B (Cards)`.
+- **Right arrow**: cycles forward (wraps around).
+
+Behaviour:
+
+- Clicking an arrow updates the URL hash so the variant is shareable and reload-stable.
+- Keyboard: `←` and `→` arrow keys also cycle. Don't intercept arrow keys when an `<input>`, `<textarea>`, or `[contenteditable]` is focused.
+- Touch: the arrows are at least 44px tall so the bar works on a phone.
+- Visually distinct from the page (e.g. high-contrast pill, subtle shadow) so it's obviously not part of the design being evaluated.
+
+### 5. Hand it over
+
+Say where the file is and list the variant keys with their `#variant=` links. The user will flip through whenever they get to it. The interesting feedback is usually **"I want the header from B with the sidebar from C"**, which is the actual design they want.
+
+### 6. Capture the answer and clean up
+
+Once a variant has won, record the verdict the way [SKILL.md](SKILL.md) rule 6 describes: an issue comment naming the winner and why, and any parts borrowed from the others. Rebuild the winner properly in the real code with the project's real components; nothing is copied out of the prototype file. The file itself never lands on `main`.
+
+## Anti-patterns
+
+- **Variants that differ only in colour or copy.** That's a tweak, not a prototype. Real variants disagree about structure.
+- **Sharing too much markup between variants.** A shared header strip is fine; a shared layout defeats the point. Each variant should be free to throw out the layout.
+- **Loading anything from the network.** No CDN scripts, no web fonts, no images by URL. The file must render from disk with no connection.
+- **Promoting the prototype directly to production.** The variant markup was written under prototype constraints (no components, no tests, no accessibility pass). Rebuild it properly when you fold it in.

package/skills/to-spec/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/to-spec/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: to-spec
+description: "Turn the current conversation into a design spec and write it where the next stage reads it: a GitHub issue body labelled spec-ready (after a grilling session), or a dated design file on the current branch (an unattended spec stage). No interview, just synthesis of what you've already discussed."
+---
+
+<!--
+Modified copy of https://github.com/mattpocock/skills/tree/3cca18b368ae95cdbdebbff572ccafa662551015/skills/engineering/to-spec
+(mattpocock-skills v1.2.3). Copyright (c) 2026 Matt Pocock, MIT — see LICENSE.
+Changes: publishes to an issue body or a design file instead of an issue tracker;
+seams are stated rather than confirmed when unattended; the document must pass the
+agent-ops mechanical spec check; Testing Decisions must name the seams; the
+`ready-for-agent` label became `spec-ready`; model invocation is allowed.
+-->
+
+This skill takes the current conversation context and codebase understanding and produces a spec. Do NOT interview the user; just synthesize what you already know.
+
+## Destination
+
+Decide where the spec goes before writing it. There are exactly two destinations:
+
+- **Issue body.** Use this when a human settled the design with you interactively (a grilling session) and the unattended pipeline will pick the work up later. Create a GitHub issue in the current repo whose body is the spec, labelled `spec-ready`. If the conversation started from an existing issue, replace that issue's body and add the label instead of creating a new issue. The spec's H1 becomes the issue title and is omitted from the body.
+- **Design file.** Use this when the invoking prompt names a file path, or when you are running unattended on a task branch. Write the spec to that path; with no path given, use `docs/specs/<YYYY-MM-DD>-<slug>-design.md`. Keep the H1 as the first line. Commit it to the current branch with a `docs:` message.
+
+If neither is clear, ask once: "Issue body or design file?". Never publish anywhere else.
+
+## Process
+
+1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the spec, and respect any ADRs in the area you're touching.
+
+2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better - the ideal number is one.
+
+   With a human present, check that these seams match their expectations. Unattended, state your choice in the Testing Decisions section instead: a later implement session treats that section as the seams already agreed and cannot stop to ask.
+
+3. Write the spec using the template below, then deliver it to the destination.
+
+## Mechanical requirements
+
+The unattended pipeline rejects a spec that fails a format check, so every spec must have:
+
+- One `# <title>` H1 as the first line (file destination) or as the issue title (issue destination).
+- At least two `## ` sections. Use every section of the template; write "None." rather than dropping one.
+- A **Testing Decisions** section that names each seam explicitly: the module, function, command or endpoint the tests drive through, and whether it exists today or is new.
+
+## Delivery commands
+
+```bash
+# Issue body (new issue). Write the body to a temp file first.
+gh issue create --repo <owner/repo> --title "<H1 text>" --label spec-ready --body-file /tmp/spec.md
+
+# Issue body (existing issue)
+gh issue edit <number> --repo <owner/repo> --body-file /tmp/spec.md --add-label spec-ready
+
+# If the label does not exist yet (the backlog skill's setup normally provisions it)
+gh label create spec-ready --repo <owner/repo> --description "Issue body carries a settled design; the pipeline skips its interview" --color 006B75 --force
+
+# Design file
+git add docs/specs/<date>-<slug>-design.md && git commit -m "docs: spec for <slug>"
+```
+
+Read `<owner/repo>` from `gh repo view --json nameWithOwner -q .nameWithOwner`.
+
+<spec-template>
+
+# <Feature title>
+
+## Problem Statement
+
+The problem that the user is facing, from the user's perspective.
+
+## Solution
+
+The solution to the problem, from the user's perspective.
+
+## User Stories
+
+A LONG, numbered list of user stories. Each user story should be in the format of:
+
+1. As an <actor>, I want a <feature>, so that <benefit>
+
+<user-story-example>
+1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending
+</user-story-example>
+
+This list of user stories should be extremely extensive and cover all aspects of the feature.
+
+## Implementation Decisions
+
+A list of implementation decisions that were made. This can include:
+
+- The modules that will be built/modified
+- The interfaces of those modules that will be modified
+- Technical clarifications from the developer
+- Architectural decisions
+- Schema changes
+- API contracts
+- Specific interactions
+
+Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
+
+Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts, not a working demo, just the important bits.
+
+## Testing Decisions
+
+A list of testing decisions that were made. Include:
+
+- A description of what makes a good test (only test external behavior, not implementation details)
+- **The seams**: every interface the tests drive through, named (module, function, command or endpoint), each marked existing or new. This list is the agreement a later implement session works from.
+- Which modules will be tested
+- Prior art for the tests (i.e. similar types of tests in the codebase)
+
+## Out of Scope
+
+A description of the things that are out of scope for this spec.
+
+## Further Notes
+
+Any further notes about the feature.
+
+</spec-template>

package/skills/to-tickets/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/to-tickets/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: to-tickets
+description: Break a spec, plan, or the current conversation into numbered tracer-bullet ticket files under .agent/tickets/, each declaring its blocking edges and acceptance criteria phrased as observable behavior. Use after a spec is approved and before implementation starts.
+---
+
+<!--
+Modified copy of https://github.com/mattpocock/skills/tree/3cca18b368ae95cdbdebbff572ccafa662551015/skills/engineering/to-tickets
+(mattpocock-skills v1.2.3). Copyright (c) 2026 Matt Pocock, MIT — see LICENSE.
+Changes: tickets always go to `.agent/tickets/<NN>-<slug>.md` (no tracker path);
+numbering is contiguous from 01 in dependency order; acceptance criteria must state
+observable behavior; the approval quiz is skipped when unattended; model
+invocation is allowed.
+-->
+
+# To Tickets
+
+Break a plan, spec, or conversation into a set of **tickets**: tracer-bullet vertical slices, each declaring the tickets that **block** it.
+
+## Process
+
+### 1. Gather context
+
+Work from whatever is already in the conversation context. If the user passes a reference (a spec path, an issue number or URL) as an argument, fetch it and read its full body and comments.
+
+### 2. Explore the codebase (optional)
+
+If you have not already explored the codebase, do so to understand the current state of the code. Ticket titles and descriptions should use the project's domain glossary vocabulary, and respect ADRs in the area you're touching.
+
+Look for opportunities to prefactor the code to make the implementation easier. "Make the change easy, then make the easy change."
+
+### 3. Draft vertical slices
+
+Break the work into **tracer bullet** tickets.
+
+<vertical-slice-rules>
+
+- Each slice cuts a narrow but COMPLETE path through every layer (schema, API, UI, tests): vertical, NOT a horizontal slice of one layer
+- A completed slice is demoable or verifiable on its own
+- Each slice is sized to fit in a single fresh context window
+- Any prefactoring should be done first
+
+</vertical-slice-rules>
+
+Give each ticket its **blocking edges**: the other tickets that must complete before it can start. A ticket with no blockers can start immediately.
+
+**Wide refactors are the exception to vertical slicing.** A **wide refactor** is one mechanical change (rename a column, retype a shared symbol) whose **blast radius** fans across the whole codebase, so a single edit breaks thousands of call sites at once and no vertical slice can land green. Don't force it into a tracer bullet; sequence it as **expand–contract**. First expand: add the new form beside the old so nothing breaks. Then migrate the call sites over in batches sized by blast radius (per package, per directory), each batch its own ticket blocked by the expand, keeping CI green batch to batch because the old form still exists. Finally contract: delete the old form once no caller remains, in a ticket blocked by every migrate batch. When even the batches can't stay green alone, keep the sequence but let them share an integration branch that all block a final integrate-and-verify ticket; green is promised only there.
+
+### 4. Quiz the user (attended only)
+
+When a human is in the loop, present the proposed breakdown as a numbered list. For each ticket, show:
+
+- **Title**: short descriptive name
+- **Blocked by**: which other tickets (if any) must complete first
+- **What it delivers**: the end-to-end behaviour this ticket makes work
+
+Ask the user:
+
+- Does the granularity feel right? (too coarse / too fine)
+- Are the blocking edges correct: does each ticket only depend on tickets that genuinely gate it?
+- Should any tickets be merged or split further?
+
+Iterate until the user approves the breakdown.
+
+Running unattended (no human to answer), skip this step: the approved spec and the plan stage's own reviewers are the checkpoints. Write the tickets directly.
+
+### 5. Write the ticket files
+
+Write one file per ticket under `.agent/tickets/<NN>-<slug>.md`. `NN` is a two-digit number starting at `01`, assigned in dependency order (blockers first) with no gaps and no duplicates: a reader executes them in numeric order and the sequence must never stop early. Delete any stale files in that directory first so the set is exactly the tickets you drafted. Use the template below: one ticket per file, never a single combined file.
+
+`.agent/` is working state, not source. It is never committed; check it is gitignored before committing anything else.
+
+Work the **frontier**: any ticket whose blockers are all done. For a purely linear chain that means top to bottom.
+
+Do NOT close or modify any parent issue.
+
+<ticket-template>
+
+# <NN>: <Ticket title>
+
+**What to build:** the end-to-end behaviour this ticket makes work, from the user's perspective, not a layer-by-layer implementation list.
+
+**Blocked by:** the numbers/titles of the tickets that gate this one, or "None (can start immediately)".
+
+- [ ] Acceptance criterion 1
+- [ ] Acceptance criterion 2
+
+</ticket-template>
+
+<acceptance-criteria-rule>
+
+Every acceptance criterion states **observable behavior**: something a reviewer can check by running the product, a command, or a test, without reading the implementation. "Running `make test` passes with the new endpoint covered" and "A user with an expired token sees the login page" are criteria. "Add a `TokenExpiry` class" and "Refactor the auth module" are implementation steps and do not belong here.
+
+</acceptance-criteria-rule>
+
+Avoid specific file paths or code snippets: they go stale fast. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it and note briefly that it came from a prototype. Trim to the decision-rich parts, not a working demo, just the important bits.

package/skills/wizard/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/wizard/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: wizard
+description: Generate an interactive bash wizard that walks a human through steps only they can perform, and that says for every captured value whether it ends up in CI, on the agent-ops box (1Password), or local only. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.
+---
+
+<!--
+Modified copy of https://github.com/mattpocock/skills/tree/3cca18b368ae95cdbdebbff572ccafa662551015/skills/engineering/wizard
+(mattpocock-skills v1.2.3). Copyright (c) 2026 Matt Pocock, MIT — see LICENSE.
+Changes: every captured value declares a destination (ci, box, local); box values
+are recorded with `box_ref` and the closing summary prints the exact 1Password
+reference lines for the box's env template plus the not-live-until-converged
+warning.
+-->
+
+# Wizard
+
+A **wizard** is a bash script that walks a human, step by step, through a manual procedure that's tedious to do by hand and tedious to re-explain to an AI every time. It opens each URL, says exactly what to click and copy, captures the values, writes them where they belong (`.env`, GitHub secrets, 1Password for the box), confirms at every stage, and shows how many stages are left. It might configure third-party services, run a one-off migration, or move the project from one state to another.
+
+The delightful UX is already solved by [template.sh](template.sh): stage-by-stage progress, confirmation gates, cross-platform URL opening (including WSL), hidden secret entry, idempotent `.env` upserts, `gh secret`/`gh variable` writes, box credential references, and a closing summary. **Your job is only to scope the procedure and author its stages.** The library above the `STAGES` marker is identical in every wizard; that consistency is the point: never hand-edit it.
+
+A wizard is ephemeral by default: built for one run, saved to a scratch or `scripts/` path, deleted when the job's done. Commit it only when the user wants a repeatable setup path that should live in the repo.
+
+## Destinations
+
+Every captured value has exactly one of three destinations, decided in step 1 and visible in the script:
+
+| Destination | Meaning | Helper |
+|---|---|---|
+| `ci` | GitHub Actions reads it | `set_secret` / `set_var` |
+| `box` | The agent-ops box reads it from 1Password through its env template | `box_ref KEY "op://agent-ops/<item>/<FIELD>"` after the human stores it |
+| `local` | Only this machine's `.env` needs it | `write_env` alone |
+
+A value can also be written to `.env` for local development on top of `ci` or `box`. The box is the one that silently fails: a wizard that captures a value the box needs but stops at the laptop finishes green while the box still cannot see it. `box_ref` is what makes that visible.
+
+## Process
+
+### 1. Scope the procedure
+
+Work out every manual step the human must take and every value that gets captured along the way. Read the repo first, don't ask cold:
+
+- For setup: `.env`, `.env.example`, `.env.*`, `README`, `docker-compose*`, framework config, and `.github/workflows/*` (every `secrets.*` / `vars.*` reference is a value the wizard must produce). For anything the box runs, also the env template in agent-ops (`provision/op.env.tpl`): every key there is a `box` value.
+- For a migration or transition: the current state, the target state, and the irreversible actions between them.
+
+Then show the user the ordered list of stages and the values each produces, and confirm: they may add, drop, or reorder.
+
+**Done when:** every stage is named in order, and for each captured value you know (a) where the human gets it, (b) its destination (`ci`, `box` or `local`) plus whether `.env` also gets it, and (c) whether it's secret (hidden entry) or public.
+
+### 2. Map each stage's journey
+
+For each stage, write the precise path a human follows: which URL to open, what to do there, where a value is shown, which variable it fills: e.g. "Dashboard → Developers → API keys → Reveal test key → copy". For a `box` value the journey continues into 1Password: which vault, item and field the human stores it under, which is exactly the `op://` reference the box will read. Where you don't actually know the current UI or the exact command, say so and ask the user or check the docs: never invent steps that may not exist.
+
+**Done when:** every stage traces to concrete instructions a stranger could follow.
+
+### 3. Author the wizard
+
+Copy `template.sh` to the target path. Replace the example stage with one `stage` per step, in dependency order. Use the library helpers: `stage`, `say`/`step`, `open_url`, `ask`/`ask_secret`, `write_env`, `set_secret`/`set_var`, `box_ref`, `pause`/`confirm`. Set `TOTAL_STAGES` to the number of stages you wrote.
+
+Hold the bar the template sets: open the URL before asking for its value, use `ask_secret` for anything secret, `write_env` every value local development needs, `set_secret` only the values CI actually needs, `box_ref` every value the box needs (after a `step` telling the human where to store it in 1Password and a `pause`), and `confirm` before any irreversible action. Each `stage` clears the screen so only the current step is visible: keep a stage to one focused task so nothing the human needs scrolls away. Don't touch the library above the marker.
+
+### 4. Verify and hand off
+
+- `bash -n <script>`; run `shellcheck` if available.
+- `chmod +x <script>`.
+- Don't run it end-to-end yourself: it opens browsers and blocks on human input. Trace it statically instead: every value from step 1 is captured and lands where step 1 said, every `set_secret` name exactly matches a `secrets.*` reference in CI, and every `box_ref` key matches a key the box's env template has or will get.
+- Tell the user how to run it, and repeat what the closing summary will say: box values are not live until the env template change is merged in agent-ops and the box has converged. If it's a repeatable setup path, commit it and link it from the README so the next person runs the script instead of asking an AI.