@stacksjs/defaults 0.72.103 → 0.73.1

package/ai/skills/stacks-slug/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-slug
-description: Use when generating URL slugs in Stacks — creating unique slugs with database collision detection, the uniqueSlug function with table/column configuration, or basic slugification. Covers @stacksjs/slug.
+description: Use when generating URL slugs in Stacks - creating unique slugs with database collision detection, the uniqueSlug function with table/column configuration, or basic slugification. Covers @stacksjs/slug.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-sms/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-sms
-description: Use when implementing SMS in Stacks — sending text messages, the SmsBuilder fluent API, SMS templates, phone verification (OTP/2FA), bulk sending, Twilio/Vonage drivers, E.164 formatting, or the SMS facade. Covers @stacksjs/sms and config/sms.ts.
+description: Use when implementing SMS in Stacks - sending text messages, the SmsBuilder fluent API, SMS templates, phone verification (OTP/2FA), bulk sending, Twilio/Vonage drivers, E.164 formatting, or the SMS facade. Covers @stacksjs/sms and config/sms.ts.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-socials/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-socials
-description: Use when implementing social authentication in Stacks — OAuth2 flows with GitHub/Google/Facebook/Twitter providers, the AbstractProvider base class, PKCE support, state management, scope configuration, social user profiles, or token handling. Covers @stacksjs/socials.
+description: Use when implementing social authentication in Stacks - OAuth2 flows with GitHub/Google/Facebook/Twitter providers, the AbstractProvider base class, PKCE support, state management, scope configuration, social user profiles, or token handling. Covers @stacksjs/socials.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-storage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-storage
-description: Use when working with file storage in Stacks — the Storage facade (put/get/delete/copy/move/list), StorageAdapter interface, local and S3 disk configurations, file uploads (UploadedFile class), file operations (read/write/copy/move/delete/hash/glob/zip), visibility management, checksums, MIME types, temporary URLs, or filesystem configuration. Covers @stacksjs/storage and config/filesystems.ts.
+description: Use when working with file storage in Stacks - the Storage facade (put/get/delete/copy/move/list), StorageAdapter interface, local and S3 disk configurations, file uploads (UploadedFile class), file operations (read/write/copy/move/delete/hash/glob/zip), visibility management, checksums, MIME types, temporary URLs, or filesystem configuration. Covers @stacksjs/storage and config/filesystems.ts.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-strings/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-strings
-description: Use when working with string utilities in Stacks — case conversion (camelCase, PascalCase, snake_case, kebab-case, CONSTANT_CASE, Train-Case, etc.), pluralization, string validation (email, URL, UUID, credit card, etc.), slug generation, random strings, template interpolation, or the Str facade. Covers @stacksjs/strings.
+description: Use when working with string utilities in Stacks - case conversion (camelCase, PascalCase, snake_case, kebab-case, CONSTANT_CASE, Train-Case, etc.), pluralization, string validation (email, URL, UUID, credit card, etc.), slug generation, random strings, template interpolation, or the Str facade. Covers @stacksjs/strings.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-stx/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-stx
-description: Use when working with STX templates in a Stacks application — template syntax, components, directives, signals, reactivity, SSR, streaming, hydration, or debugging STX rendering. STX is the ONLY templating system for Stacks.
+description: Use when working with STX templates in a Stacks application - template syntax, components, directives, signals, reactivity, SSR, streaming, hydration, or debugging STX rendering. STX is the ONLY templating system for Stacks.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-tdd/EXAMPLES.md

@@ -0,0 +1,136 @@
+# Good and bad tests
+
+## Good
+
+**Integration-style**: through real interfaces, not mocks of internal parts.
+
+```typescript
+import { describe, expect, test } from 'bun:test'
+
+test('a customer can check out with a valid cart', async () => {
+  const cart = await Cart.create({ customer_id: customer.id })
+  await cart.add(product)
+
+  const result = await checkout(cart, paymentMethod)
+
+  expect(result.status).toBe('confirmed')
+})
+```
+
+Characteristics:
+
+- Tests behaviour callers care about.
+- Uses the public surface only.
+- Survives internal refactors.
+- Describes what, not how.
+- One logical assertion per test.
+
+## Bad
+
+**Implementation-detail tests**: coupled to internal structure.
+
+```typescript
+// bad: asserts on an internal collaborator
+test('checkout calls the payment driver', async () => {
+  const spy = mock(paymentDriver.process)
+  await checkout(cart, payment)
+  expect(spy).toHaveBeenCalledWith(cart.total)
+})
+```
+
+Red flags: mocking internal collaborators, testing private methods, asserting on
+call counts or ordering, a test that breaks on a refactor with no behaviour
+change, a test name that describes how.
+
+```typescript
+// bad: bypasses the interface to verify
+test('createUser saves to the database', async () => {
+  await createUser({ name: 'Alice' })
+  const row = await db.raw('select * from users where name = ?', ['Alice'])
+  expect(row).toBeDefined()
+})
+
+// good: verifies through the interface
+test('createUser makes the user retrievable', async () => {
+  const user = await createUser({ name: 'Alice' })
+  const retrieved = await User.find(user.id)
+  expect(retrieved?.name).toBe('Alice')
+})
+```
+
+**Tautological tests**: the expected value restates the implementation, so the
+test passes by construction.
+
+```typescript
+// bad: expected value recomputed the way the code computes it
+test('calculateTotal sums line items', () => {
+  const items = [{ price: 10 }, { price: 5 }]
+  const expected = items.reduce((sum, i) => sum + i.price, 0)
+  expect(calculateTotal(items)).toBe(expected)
+})
+
+// good: expected value is an independent literal
+test('calculateTotal sums line items', () => {
+  expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15)
+})
+```
+
+## When to stand something in
+
+Stand in at **system boundaries** only:
+
+- Third-party HTTP: Stripe, SES, SendGrid, Mailgun, Twilio, Anthropic, OpenAI,
+  Meilisearch, Algolia, Route53.
+- Time and randomness.
+- The queue, when the assertion is "this job was dispatched" rather than "this
+  job ran".
+- The filesystem, sometimes. The local storage driver is usually enough.
+
+Do not stand in for:
+
+- Your own actions, models, jobs or listeners.
+- The database. Use `setupDatabase()` and `refreshDatabase()`.
+- The cache. Use the `memory` driver.
+- Anything under `@stacksjs/*` that you control.
+
+## Designing for a stand-in
+
+**Accept the dependency.**
+
+```typescript
+// easy to substitute
+export async function processPayment(order: Order, gateway: PaymentGateway) {
+  return gateway.charge(order.total)
+}
+
+// hard to substitute
+export async function processPayment(order: Order) {
+  const gateway = new StripeGateway(env.STRIPE_KEY)
+  return gateway.charge(order.total)
+}
+```
+
+**Prefer an SDK-shaped surface over one generic fetcher.** A named function per
+external operation is independently substitutable and self-documenting. One
+`fetch(endpoint, options)` forces conditional logic into every stand-in. This is
+the shape the framework's own driver packages use, so a new external integration
+should copy it rather than invent a third pattern.
+
+## Queue assertions
+
+```typescript
+import { fake, restore } from '@stacksjs/queue'
+
+test('publishing an article dispatches the index job', async () => {
+  const queue = fake()
+
+  await publishArticle(article.id)
+
+  queue.assertDispatched('IndexArticle')
+  restore()
+})
+```
+
+`fake()` mutates global state, so `restore()` belongs in the same test or in
+`afterEach`. A suite that forgets it will fail somewhere else and blame the wrong
+code.

package/ai/skills/stacks-tdd/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: stacks-tdd
+description: Use when building a feature or fixing a bug test-first in a Stacks project, when the user mentions red-green-refactor or vertical slices, or when deciding which seam a test belongs at. Covers the red-green loop over bun test and @stacksjs/testing, seam selection, and the test anti-patterns.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Test-driven development
+
+TDD is the red to green loop. This skill is the reference that makes the loop
+produce tests worth keeping: what a good test is, where tests go, the
+anti-patterns, and the rules of the loop. Every section applies on every cycle.
+Consult them before and during, not after.
+
+`stacks-testing` is the *mechanics*: `setupDatabase()`, `refreshDatabase()`,
+DynamoDB Local, `bunfig.toml` preload, the CLI flags. This skill is the
+*discipline*. Read that one for the API and this one for the decisions.
+
+Credit: adapted from Matt Pocock's `tdd` skill (MIT),
+<https://github.com/mattpocock/skills>.
+
+## What a good test is
+
+Tests verify behaviour through public interfaces, never implementation details.
+Code can change entirely, tests should not. A good test reads like a
+specification: "a customer can check out with a valid cart" tells you exactly
+what capability exists, and it survives refactors because it does not care about
+internal structure.
+
+See [EXAMPLES.md](EXAMPLES.md) for good and bad tests side by side, and for
+where mocking is legitimate.
+
+## Seams: where tests go
+
+A **seam** is the public boundary you test at, the interface where you observe
+behaviour without reaching inside. Tests live at seams, never against internals.
+When the shape of that interface is itself in question, call the Skill tool with
+`stacks-codebase-design` for the vocabulary. It owns the module, interface,
+depth, seam, adapter, leverage and locality terms.
+
+**Test only at pre-agreed seams.** Before writing any test, write down the seams
+under test and confirm them with the user. No test is written at an unconfirmed
+seam. You cannot test everything, so agreeing the seams up front is how testing
+effort lands on the critical paths instead of on every edge case.
+
+A Stacks app has four seams worth naming, from highest to lowest. Prefer the
+highest one that can go red on the behaviour you care about:
+
+| Seam | Test through | Use when |
+|---|---|---|
+| Route | an HTTP request against the running route, middleware included | the behaviour is a user-visible endpoint |
+| Action | calling the action in `app/Actions/` directly | the behaviour is the request-to-response logic, and you do not need middleware in the picture |
+| Model | the model's query and mutation surface, against the test database | the behaviour is a trait, a relationship, a computed attribute, or a validation rule |
+| Function | a plain import from `resources/functions/` or a `@stacksjs/*` package | the behaviour is pure computation |
+
+The fewer seams you cross for one feature, the better. One is ideal.
+
+## The database is not a boundary to mock
+
+The framework hands you a real one. `setupDatabase()` creates
+`database/stacks_testing.sqlite`, `refreshDatabase()` drops and re-migrates it,
+and the per-attribute `factory` functions in each model produce realistic rows.
+Use them. A test that mocks `User.find()` is testing the mock.
+
+Real boundaries in a Stacks app, the ones where a stand-in is correct: third
+party HTTP (Stripe, SES, Anthropic, Meilisearch), the clock, randomness, and the
+queue when you are asserting that a job was dispatched rather than that it ran.
+`fake()` / `restore()` from `@stacksjs/queue` exist for that last one.
+
+## Anti-patterns
+
+- **Implementation-coupled**: mocks internal collaborators, tests private
+  methods, or verifies through a side channel (querying the database with raw
+  SQL instead of reading back through the model). The tell: the test breaks when
+  you refactor but behaviour has not changed.
+- **Tautological**: the assertion recomputes the expected value the way the code
+  does, so it passes by construction and can never disagree with the code.
+  Expected values must come from an independent source of truth: a known-good
+  literal, a worked example, the spec.
+- **Horizontal slicing**: writing all the tests first, then all the
+  implementation. Bulk tests verify *imagined* behaviour. You test the shape of
+  things rather than user-facing behaviour, the tests go insensitive to real
+  changes, and you commit to a test structure before understanding the
+  implementation. Work in **vertical slices** instead: one test, one
+  implementation, repeat. Each test is a **tracer bullet** that responds to what
+  the last cycle taught you.
+- **Leaking state between files**: `refreshDatabase()` drops every table, and
+  `fake()` mutates global queue state. Both belong in setup and teardown, never
+  mid-test.
+
+## Rules of the loop
+
+- **Red before green.** Write the failing test first, then only enough code to
+  pass it. Do not anticipate future tests or add speculative features.
+- **One slice at a time.** One seam, one test, one minimal implementation per
+  cycle.
+- **Run the narrow thing during the loop.** `bun test tests/feature/articles.test.ts`
+  is the loop. `buddy test` is the gate you run once at the end. Passing a path
+  to `bun test` filters, it does not scope, so keep the path narrow while you
+  iterate.
+- **Typecheck alongside.** `./buddy typecheck` for `app/`, `config/`,
+  `resources/` and `routes/`. It runs on tsgo and finishes in seconds, so there
+  is no reason to save it for the end.
+- **Refactoring is not part of the loop.** It belongs to review. Run
+  `/stacks-review` once the slice is green.
+
+## Model-first order
+
+A vertical slice in Stacks cuts through the model, the migration, the action, the
+route and the test. Migrations are derived from models here, so the loop has one
+extra beat compared to other frameworks:
+
+```
+model change  →  buddy generate:migrations  →  review the SQL  →  buddy migrate  →  red test  →  green
+```
+
+Skipping the review step is how a wrong column type reaches every downstream
+environment. See `stacks-new-feature` for the full slice and
+`stacks-migrations` for the generation rules.
+
+## Downstream
+
+> Green? Run `/stacks-review` for the two-axis review, then `/stacks-browse` if
+> the slice has a UI.

package/ai/skills/stacks-testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-testing
-description: Use when writing or running tests in Stacks — test setup, database test utilities (setup, refresh, truncate), DynamoDB testing, feature test patterns, the test CLI commands, test configuration in bunfig.toml, or test environment setup. Covers @stacksjs/testing and tests/.
+description: Use when writing or running tests in Stacks - test setup, database test utilities (setup, refresh, truncate), DynamoDB testing, feature test patterns, the test CLI commands, test configuration in bunfig.toml, or test environment setup. Covers @stacksjs/testing and tests/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -10,6 +10,11 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 Uses Bun's built-in test runner with Stacks-specific test utilities.
 
+This skill is the **mechanics**: the utilities, the setup, the CLI, the gotchas.
+`stacks-tdd` is the **discipline**: the red-green loop, which seam a test belongs
+at, and the anti-patterns that make a test worse than no test. Read that one
+before deciding what to test, and this one for how.
+
 ## Key Paths
 - Core package: `storage/framework/core/testing/src/`
 - Test directory: `tests/`
@@ -122,8 +127,13 @@ preload = ["./tests/setup.ts"]
 - Uses Bun's native test runner, NOT Jest or Vitest
 - Test preload runs `tests/setup.ts` before each test file
 - SQLite testing database is at `database/stacks_testing.sqlite`
-- `refreshDatabase()` drops ALL tables — use in test setup only
+- `refreshDatabase()` drops ALL tables - use in test setup only
 - DynamoDB Local must be installed for DynamoDB tests
-- Queue testing uses `fake()`/`restore()` pattern — affects global state
+- Queue testing uses `fake()`/`restore()` pattern - affects global state
 - `@stacksjs/faker` provides test data generation
 - Coverage reports with `bun run test:coverage`
+
+## Downstream
+
+> Deciding what to test, or where? `/stacks-tdd`. Reviewing someone else's
+> tests? `/stacks-review` audits coverage as its third pass.

package/ai/skills/stacks-tunnel/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-tunnel
-description: Use when setting up tunnels in Stacks — local development tunnels for webhook testing, custom cloud tunnel deployment to AWS EC2, tunnel event callbacks (onConnect, onRequest, onResponse, onError), subdomain configuration, or the buddy share command. Covers @stacksjs/tunnel.
+description: Use when setting up tunnels in Stacks - local development tunnels for webhook testing, custom cloud tunnel deployment to AWS EC2, tunnel event callbacks (onConnect, onRequest, onResponse, onError), subdomain configuration, or the buddy share command. Covers @stacksjs/tunnel.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-types/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-types
-description: Use when working with TypeScript type definitions in a Stacks application — model types, request types, environment variables, event types, billing types, attribute types, or auto-imported globals. Covers storage/framework/types/ and storage/framework/core/types/src/.
+description: Use when working with TypeScript type definitions in a Stacks application - model types, request types, environment variables, event types, billing types, attribute types, or auto-imported globals. Covers storage/framework/types/ and storage/framework/core/types/src/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-ui/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-ui
-description: Use when working with UI in a Stacks application — components, composables, reactivity (refs/watch/computed), Craft native components, Crosswind CSS, Crosswind utility framework, accessibility, or the STX templating engine. Covers @stacksjs/ui, @stacksjs/stx, and related UI tooling.
+description: Use when working with UI in a Stacks application - components, composables, reactivity (refs/watch/computed), Craft native components, Crosswind CSS, Crosswind utility framework, accessibility, or the STX templating engine. Covers @stacksjs/ui, @stacksjs/stx, and related UI tooling.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-utils/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-utils
-description: Use when needing general utility functions in Stacks — deep merge, debounce/throttle, color output, byte formatting, markdown tables, YAML parsing, Pipeline class, ResizeObserver, Macroable, project initialization, indentation detection, or the comprehensive utility toolkit. Covers @stacksjs/utils.
+description: Use when needing general utility functions in Stacks - deep merge, debounce/throttle, color output, byte formatting, markdown tables, YAML parsing, Pipeline class, ResizeObserver, Macroable, project initialization, indentation detection, or the comprehensive utility toolkit. Covers @stacksjs/utils.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-validation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-validation
-description: Use when implementing validation in Stacks — type guards (isString, isNumber, isBoolean, isObject, isArray, isFunction, etc.), numeric checks (isPositive, isEven, isInteger), the schema builder for model attribute validation, or request validation. Covers @stacksjs/validation.
+description: Use when implementing validation in Stacks - type guards (isString, isNumber, isBoolean, isObject, isArray, isFunction, etc.), numeric checks (isPositive, isEven, isInteger), the schema builder for model attribute validation, or request validation. Covers @stacksjs/validation.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-whois/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-whois
-description: Use when performing WHOIS lookups in Stacks — domain queries, batch lookups, SOCKS proxy support, TLD server discovery, response parsing, the WhoIsParser class, or the built-in SocksClient. Covers @stacksjs/whois.
+description: Use when performing WHOIS lookups in Stacks - domain queries, batch lookups, SOCKS proxy support, TLD server discovery, response parsing, the WhoIsParser class, or the built-in SocksClient. Covers @stacksjs/whois.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-wizard/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: stacks-wizard
+description: Use when a procedure needs a human in the loop and the agent has hit a wall it cannot pass alone - provisioning cloud credentials, verifying a sending domain, setting CI secrets, clicking through a registrar or third-party dashboard, or running a one-off cutover. Generates an interactive bash wizard that opens each URL, captures each value, and writes it into .env and GitHub secrets.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript, bash
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Wizard
+
+A **wizard** is a bash script that walks a human, step by step, through a manual
+procedure that is tedious to do by hand and tedious to re-explain to an agent
+every time. It opens each URL, says exactly what to click and copy, captures the
+values, writes them where they belong, confirms before anything irreversible, and
+shows how many stages are left.
+
+The UX is already solved by [scripts/template.sh](scripts/template.sh):
+stage-by-stage progress, confirmation gates, cross-platform URL opening including
+WSL, hidden entry for secrets, idempotent `.env` upserts, `gh secret` and
+`gh variable` writes, and a closing summary. **Your job is only to scope the
+procedure and author its stages.** Everything above the `STAGES` marker is
+identical in every wizard, and that consistency is the point. Never hand-edit it.
+
+A wizard is ephemeral by default: built for one run, saved to a scratch path or
+`scripts/`, deleted when the job is done. Commit it only when the user wants a
+repeatable setup path that should live in the repo.
+
+Credit: adapted from Matt Pocock's `wizard` skill (MIT),
+<https://github.com/mattpocock/skills>. The template library is his, unchanged
+except for the example stage.
+
+## When this is the right tool
+
+Reach for it the moment you hit a step only the human can take. In a Stacks
+project that is a short and predictable list:
+
+- **AWS access** for `buddy deploy` and `buddy cloud`, and the IAM permissions
+  behind them.
+- **Domains and DNS**: `buddy domains:purchase`, registrar nameserver changes,
+  the delegation that has to happen at the registrar rather than in Route53.
+- **Email**: SES domain verification, DKIM records, moving out of the sandbox,
+  the port 25 request.
+- **CI secrets**: every `secrets.*` and `vars.*` reference in
+  `.github/workflows/*` is a value the wizard should produce.
+- **Server provisioning**: a Hetzner or other provider token, an SSH key added to
+  the account, the first-boot steps.
+- **Payments**: Stripe keys and webhook endpoints.
+
+If the agent could just do it itself, it should. This is for where a human is
+genuinely in the loop.
+
+## Process
+
+### 1. Scope the procedure
+
+Work out every manual step the human must take and every value captured along the
+way. Read the repo first, do not ask cold:
+
+- `.env`, `.env.example`, `.env.*`, and `config/services.ts` for what the app
+  already expects.
+- `config/cloud.ts`, `config/dns.ts`, `config/email.ts` for what the deploy
+  targets.
+- `.github/workflows/*` for every secret and variable CI reads.
+- The relevant skill (`stacks-deploy`, `stacks-cloud`, `stacks-dns`,
+  `stacks-email`) for which steps the CLI already automates, so the wizard covers
+  only the gap.
+
+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) where it is written (`.env`, a GitHub secret,
+both, or nowhere, since some stages are pure actions), and (c) whether it is
+secret and so needs hidden entry.
+
+### 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 the value is shown, which variable it fills. For example
+"Route53 console, Hosted zones, pick the domain, copy the four NS records".
+
+Where you do not 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 `scripts/template.sh` to the target path. Replace the example stage with one
+`stage` per step, in dependency order. Set `TOTAL_STAGES` to the number you
+wrote. Use the library helpers: `stage`, `say`, `step`, `note`, `warn`,
+`open_url`, `ask`, `ask_secret`, `write_env`, `set_secret`, `set_var`, `pause`,
+`confirm`.
+
+Hold the bar the template sets:
+
+- Open the URL before asking for its value.
+- `ask_secret` for anything secret.
+- `write_env` every persisted value.
+- `set_secret` only the values CI actually needs.
+- `confirm` before anything irreversible.
+- One focused task per `stage`, because each stage clears the screen and anything
+  the human still needs must not have scrolled away.
+
+In a Stacks project, finish with a stage that encrypts what you just wrote:
+`./buddy env:encrypt`, and for a production file the matching
+`buddy env:keypair` / `buddy env:rotate` step. A wizard that leaves plaintext
+credentials in `.env.production` has done half a job. `buddy env:check` is the
+verification line for the closing stage.
+
+### 4. Verify and hand off
+
+- `bash -n <script>`, and `shellcheck` if it is available.
+- `chmod +x <script>`.
+- Do not 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, and every `set_secret` name matches a `secrets.*` reference
+  in CI exactly.
+- Tell the user how to run it. If it is a repeatable setup path, commit it under
+  `scripts/` and link it from the README so the next person runs the script
+  instead of asking an agent.
+
+## Downstream
+
+> Credentials in place? `/stacks-deploy` for the deploy workflow itself, and
+> `/stacks-guard` before anything touches production.