update skills

.agents/skills/wizard/SKILL.md

@@ -1,13 +1,15 @@
 ---
 name: wizard
-description: Generate an interactive bash wizard that walks a human through steps only they can perform. 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.
+description: Generate an interactive Bash wizard for steps only a human can perform, such as dashboard setup or credential capture. Use for a requested manual procedure, not work the agent can complete directly.
 ---
 
 # 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), 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.
+A **wizard** walks a human through the manual parts of the requested procedure, captures values, and writes only to the selected destinations. Reuse the user's chosen service and CI platform; generating a wizard does not authorize running provisioning or publishing credentials.
 
-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, 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.
+Start from [template.sh](template.sh) for progress, confirmation gates, URL opening, hidden input, and persistence helpers. Adapt helpers when the selected destination requires it; verify changes with dummy data before handling real credentials.
+
+The bundled dotenv helpers accept uppercase variable names and required, single-line values without apostrophes. They write private, single-quoted values so hashes, spaces, dollars, and backslashes survive; unsupported values or existing formats stop with an error. Confirm that the actual consumer supports this format. If it needs another dialect or multiline values, adapt both reading and writing and test a round trip through that consumer. EOF cancels the wizard; empty input keeps an existing value or fails if none exists.
 
 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.
 
@@ -17,12 +19,12 @@ A wizard is ephemeral by default — built for one run, saved to a scratch or `s
 
 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 setup: configuration examples, README, compose/framework configuration, and the actual CI files (this repository uses `.gitlab-ci.yml`). Inspect secret names and references without displaying existing secret values. Include only values needed for the requested procedure, not every variable in the repository.
 - 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) where it's written (`.env`, a GitHub secret, both, or nowhere — some stages are pure actions), and (c) whether it's secret (hidden entry) or public.
+**Done when:** every stage is named in order, and each captured value has a known source, selected destination (local file, configured secret store, or neither), and secrecy level.
 
 ### 2. Map each stage's journey
 
@@ -32,13 +34,14 @@ For each stage, write the precise path a human follows: which URL to open, what
 
 ### 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`, `pause`/`confirm` — and set `TOTAL_STAGES` to the number of stages you wrote.
+Copy `template.sh` to the target path. Replace the example stages in dependency order, using `stage`, `say`/`step`, `open_url`, `ask`/`ask_secret`, `write_env`, and `pause`/`confirm`. Set honest stage/time estimates. For CI secrets, use the selected platform's existing tooling or guide the human through its UI. Add a provider-specific writer only when needed and verify its local help, authentication, project scope, and secret-safe input mechanism first.
 
-Hold the bar the template sets: open the URL before asking for its value, use `ask_secret` for anything secret, `write_env` every persisted value, `set_secret` only the values CI actually needs, 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.
+Open the URL before asking for its value, use `ask_secret` for secrets, and persist only to the selected destinations. Require a successful `confirm` before an irreversible action. Do not expose values in logs or command arguments. On an ambiguous remote write, check its result before retrying; on missing authority or repeated failure, stop that stage and report what remains. Keep each stage focused so needed instructions remain visible.
 
 ### 4. Verify and hand off
 
 - `bash -n <script>`; run `shellcheck` if available.
+- Run `python3 test_wizard.py` from this skill directory (requires Node for the dotenv consumer check). Source the generated script to test its helpers with dummy values in a temporary directory, without running the stages.
 - `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, and every `set_secret` name exactly matches a `secrets.*` reference in CI.
-- Tell the user how to run it. 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.
+- Don't run it end-to-end yourself — it opens browsers and blocks on human input. Check that each value lands in the selected destination and any CI variable name matches an actual reference. Test remote writers with stubs, never real credentials.
+- Tell the user how to run it. For a requested repeatable setup path, link it from the relevant setup documentation. Commit only if requested, and do not execute the manual procedure merely because its script is complete.