Conventions

The commands in SKILL.md are the engine; they are not what the user should read. Raw curl bodies, JSON, and HTTP codes are noise. Follow this contract so every step looks the same and the screen stays calm:

• Emit only clean status lines, one per meaningful transition, using this fixed vocabulary: ▸ doing · ✓ done · ⚠ warning (recoverable) · ✗ failed (needs a decision) · 🔑 credential card.
• Send noise to a log, not the screen. Every noisy command appends verbose output to DDLOG="${TMPDIR:-/tmp}/dd-onboard-$(id -u).log" (>>"$DDLOG" 2>&1) and echoes only a clean line. The blocks in the steps already print clean lines — when you add a curl, redirect its body to $DDLOG and echo a ▸/✓/✗ line, never the raw response.
• Details on demand. If the user asks “why” / “show details” (or a step fails), then — and only then — surface the relevant tail: tail -n 30 "$DDLOG".
• Never put a secret (key, token, password) in a status line or the log echo — only …last4.
• Never dump machine detail to the screen: raw OAuth scope lists, HTTP Location:/redirect headers, JSON bodies, and full response dumps go to $DDLOG — echo only a one-line ✓/✗. (Both bit a real run: a 40-scope wall and a Location: /signup/setup line leaked onto the user’s screen.)
• When you paraphrase a step for the user, describe the outcome (“Signed in as X on US1”), not the tool call (“ran curl …”). Do not narrate Bash invocations.

Ask with the host’s native UI — never letter-entry

For every choice (region, and the connect method), use the host’s native question UI (Claude Code AskUserQuestion; the equivalent in Codex/Cursor) so the user picks from an up/down-navigable selector. Never ask the user to type a letter or number to choose (“enter A”, “press 1”) — the letters below (A/B/C) are internal labels for you to map paths, not a prompt to show. Each native option’s visible label is the human wording (e.g. “Use my existing credentials”, “Sign in”, “Create a new account”). Only fall back to a numbered text menu when no native picker exists at all; even then, still let the user reply in words, not a bare letter.

Show a live progress checklist

This flow has five steps and it branches, so keep the user oriented with a checklist. Post it when Step 1 begins (right after the preflight board), then reprint the whole list at each step transition. Never put a secret (key, token, password) in the list.

Marker rules — the same on every line, every reprint (a real run corrupted this):

• Exactly one marker set: ● done · ◔ current · ○ todo · ⊘ skipped · ✖ failed. Every line is - <glyph> <number>. — no bare a. / b. / 2..
• Top-level steps are always numbered 1.–5.; Path-C sub-items are lettered a./b./c. and indented under step 3. Never renumber a top-level step as a letter or swap the two — that conflation is exactly what broke the last run (a. Detect … ◔ 2. Confirm … c. Authenticate).
• A completed step shows ●, not a bare letter. Re-emit the full 5-line list each time; don’t hand-edit a prior copy.

Canonical shape to copy (fill the markers, keep the numbers/letters fixed):

Each step in SKILL.md ends with a ↳ Checklist: cue telling you what to flip.

Interactive baseline:

Adapt it to the path actually taken:

• Headless (Step H) — collapse to two: Check DD_API_KEY / DD_APP_KEY / DD_SITE → Validate & hand off.
• Existing key already valid (Path A) — steps 3–4 collapse to one: 3. Validate the existing key.
• Create account in the terminal (Path C) — expand step 3 so signup is legible, e.g. mid-flow:

Tick an item only when its outcome is real — check “Confirm region” after the user confirms (not when you suggest one), and “Authenticate” after a token/key is in hand (not when the browser opens).