perpetualsoftware/pad/onboard

Set this project up with Pad. If pad is not on PATH, give the install one-liner from https://getpad.dev/install and stop.

If no .pad.toml exists, first run pad auth whoami (fast and safe: in non-interactive use — which is where you run — it returns immediately rather than waiting on input, and it works regardless of workspace-link state) to check whether this machine is already configured and authenticated:

• If it reports a real user, it's safe to self-heal: run pad workspace init

(a name/--template are optional) to link and create the workspace non-interactively.

• If it reports "not configured," "session expired," or anything other than a

real user, this machine hasn't finished setup yet. Do not run pad init or pad workspace init yourself — pad workspace init now fails fast, non-interactively, with an actionable error instead of hanging (BUG-2538/BUG-2577): "not been initialized yet" pointing at pad auth setup, or "not authenticated" pointing at pad auth login. That error still means only a human at an interactive terminal can finish it, so running it yourself just spends a tool call confirming what pad auth whoami already told you. (With both stdin AND stdout attached to a real terminal it instead drops into the browser auth flow, now bounded at 20 minutes wall-clock — not a state your tool call is ever in.) pad init is not a safer probe either: verified live, it fails fast when stdin/stdout aren't terminals in both states — genuinely unconfigured, and (since BUG-2592) the session-expired sub-case of configured-but-unauthenticated — with the same real-terminal caveat as above, so probing it tells you nothing pad auth whoami didn't. Tell the user to run pad init themselves in an interactive terminal — in Claude Code, suggest they type ! pad init to run it directly in their own terminal. Stop here; there's nothing more this skill can do until that completes.

Once linked, run pad bootstrap --format json, then run the onboard playbook — do not improvise your own setup script. The playbook is workspace-owned and user-editable (PLAN-1496's adaptation posture): a team that has rewritten theirs must get their version from every surface, including this shortcut. Three steps, in this order:

1. Ensure the playbook is active. Check the bootstrap's playbooks

array for invocation_slug=onboard, status=active. If instead an onboard entry exists in a non-active status (draft/deprecated), REACTIVATE it in place (pad item update PLAYB-N --field status=active) — invocation_slug is workspace-unique, so library activation next to an existing entry creates a duplicate or fails on the slug. Only when no onboard playbook exists at all, activate from the library: pad library activate "Onboard a workspace" (activate takes the exact library title; pad library list shows it), or the Web UI's Playbooks → Library.

1. Load the body and follow it — it IS the script:

``bash pad playbook show onboard --format markdown ``

1. **Let its mode detection route, and frame needs_onboarding

honestly.** The playbook's mode argument is auto (default), build, audit, or revisit, plus a separate defaults flag that fast-paths the interview. auto sends a workspace with ANY user-created item to revisit — and needs_onboarding: false means exactly that one fact, NOT that onboarding ever ran. So when it's false, say what exists (collections, active conventions from convention_index), and if the user says the workspace was never really set up, pass an explicit mode=build or mode=audit — the playbook honors the override — rather than expecting auto to pick the fuller pass, and rather than declaring setup complete yourself.

Create items only after the user confirms the shape — the same confirm-before-creating rule as everywhere else.