feat(onboard): make natural language the canonical onboard trigger (TASK-1849) (#741)

* feat(onboard): make natural language the canonical onboard trigger (TASK-1849)

The onboard procedure already single-sourced to the seeded playbook body —
both SKILL.md and the MCP pad_onboard prompt deferred to it rather than
restating it. But two gaps remained:

- Both hardcoded `/pad onboard`, a Claude-Code-ism. SKILL.md installs into
  Codex (`$pad`) and others too, so the nudge/routing copy was wrong off
  Claude Code. Reframe NL ("set up my workspace") as the canonical trigger;
  `/pad onboard` · `$pad onboard` · the `pad_onboard` MCP prompt are now
  per-surface shortcuts into the same playbook.
- The MCP prompt resolved the playbook via CLI commands (`pad playbook
  list`/`show`) that a shell-less MCP client can't run. Rewrite it to use
  the `pad_playbook` tool (action:list / action:get ref:onboard); CLI form
  kept as a secondary note. This closes the real single-source gap.

Agent-instruction surfaces only (SKILL.md + MCP prompt text); no CLI/MCP
catalog changes (CONVE-1741).

Parent: PLAN-1847. Absorbs cancelled TASK-1848.

Claude-Session: https://claude.ai/code/session_01KmxkPxLksjf1pmrZDpsnTJ

* fix(onboard): use pad_library activate for shell-less onboard recovery per Codex review (round 1)

Round-1 review flagged that the MCP prompt's missing-playbook fallback sent
agents to the web UI even though pad_library action=activate is callable from
a shell-less MCP client. Activate "Onboard a workspace" via the tool, then
re-list, before deferring to the user.

Claude-Session: https://claude.ai/code/session_01KmxkPxLksjf1pmrZDpsnTJ

internal/mcp/prompts_data.go

@@ -60,13 +60,17 @@ Always confirm before creating or mutating items.
 
 const promptOnboardBody = `# Pad: Onboard workflow
 
-The canonical workspace-onboarding interview lives in the ` + "`/pad onboard`" + ` invokable library playbook (PLAN-1496 / TASK-1499). Every new workspace auto-seeds it as ` + "`status=active`" + ` (TASK-1500), so it should be directly invokable.
+The canonical workspace-onboarding interview lives in the **onboard** invokable library playbook (PLAN-1496 / TASK-1499). Every new workspace auto-seeds it as ` + "`status=active`" + ` (TASK-1500), so it should be directly invokable.
 
-To run it:
+Natural language is the canonical trigger and works on every surface — when the user says "set up my workspace" / "onboard me," run this playbook. The slug shortcuts (` + "`/pad onboard`" + ` in Claude Code, ` + "`$pad onboard`" + ` in Codex, this ` + "`pad_onboard`" + ` prompt) are equivalent entry points into the same playbook.
 
-1. Confirm the playbook is activated. ` + "`pad playbook list --format json`" + ` and look for ` + "`invocation_slug=onboard`" + ` with ` + "`status=active`" + `. If it's missing, activate from the library: ` + "`pad library activate playbook \"Onboard a workspace\"`" + ` (web UI: ` + "`/{ws}/library?tab=playbooks`" + `).
-2. Load the body. ` + "`pad playbook show onboard --format markdown`" + `.
+To run it (using your MCP tools — no shell required):
+
+1. Confirm the playbook is activated. Call ` + "`pad_playbook`" + ` with ` + "`action: list`" + ` and look for ` + "`invocation_slug=onboard`" + ` with ` + "`status=active`" + `. If it's missing, activate it yourself — call ` + "`pad_library`" + ` with ` + "`action: activate`" + ` and ` + "`title: \"Onboard a workspace\"`" + ` (no shell needed), then re-list. (The user can also activate it from the library in the web UI: ` + "`/{ws}/library?tab=playbooks`" + `.)
+2. Load the body. Call ` + "`pad_playbook`" + ` with ` + "`action: get`" + ` and ` + "`ref: onboard`" + ` (this returns the full body; it is side-effect-free).
 3. Follow the body's instructions. It teaches you the surface-agnostic interview: discover the domain, propose collections, adapt seeded conventions/playbooks to the project's actual tooling, suggest roles, seed a first item. The body is the source of truth — this prompt is just the dispatcher.
 
+(CLI-capable agents can equivalently use ` + "`pad playbook list`" + ` / ` + "`pad playbook show onboard --format markdown`" + `; the ` + "`pad_playbook`" + ` tool is the surface-neutral path that also works for shell-less MCP clients.)
+
 The pre-PLAN-1496 step-by-step workflow that used to live here (codebase-scan / suggest-conventions / draft-doc / propose-plan / suggest-roles) was retired in TASK-1505. All of it is now embedded in the playbook body, surface-agnostic so MCP-only agents can follow it too.
 `

skills/pad/SKILL.md

@@ -36,7 +36,7 @@ The returned `AgentBootstrap` blob carries everything the skill needs to start a
 - `roles [...]` — agent roles configured in the workspace
 - `playbooks [...]` — METADATA ONLY: `ref`, `title`, `slug`, `invocation_slug`, `trigger`, `scope`, `status`, `has_arguments`, `summary`. Full bodies load on invocation via `pad playbook show <slug>`.
 - `dashboard {...}` — active items, attention, suggested next, recent activity. Five sub-arrays are capped to 5 entries each (`attention`, `recent_activity`, `active_items`, `active_plans`, `by_role`); each pairs with a `<name>_overflow_count` int field surfaced when truncation kicked in. Use `pad project dashboard` to pull the full set when any overflow > 0.
-- `needs_onboarding: bool` — true when the workspace has zero user-created items (template seeds don't count). PLAN-1496 / TASK-1504. **When this is true, lead your response with a one-line nudge:** *"This workspace hasn't been set up yet — say `/pad onboard` to walk through setup."* Then proceed with whatever else the user asked. The flag flips to false the moment any user/agent-created item exists; don't nag past that point. If the user has already declined onboarding (look at recent conversation), respect that and skip the nudge for this session.
+- `needs_onboarding: bool` — true when the workspace has zero user-created items (template seeds don't count). PLAN-1496 / TASK-1504. **When this is true, lead your response with a one-line nudge:** *"This workspace hasn't been set up yet — just say **set up my workspace** and I'll walk you through it."* Lead with the natural-language phrasing (it works on every surface); don't hardcode a slash command in the nudge, since this skill runs under Claude Code (`/pad`), Codex (`$pad`), and others. Then proceed with whatever else the user asked. The flag flips to false the moment any user/agent-created item exists; don't nag past that point. If the user has already declined onboarding (look at recent conversation), respect that and skip the nudge for this session.
 
 If the conventions list includes items, treat them as project rules you must follow. The vocabulary depends on the workspace domain — a software workspace ships rules like "use conventional commit format," a hiring workspace ships rules like "anonymize candidate names in exports," a research workspace ships rules like "always cite sources." Follow whatever the workspace has configured.
 
@@ -172,8 +172,8 @@ Interpret the user's intent and route to the appropriate action. Here are common
 **Retrospective:** "plan X is done, let's retro" → Review completed work via the playbook (or inline if none active), save retro as a Doc.
 
 **Onboarding:**
-- "set up my workspace" / "onboard me" / "scan this codebase" → `/pad onboard` (canonical entry; activate via library if the bootstrap's `playbooks` array lacks `invocation_slug=onboard, status=active`). The playbook's body is the script — surface-agnostic interview, codebase scan if available, adapt seeded artifacts to the project, seed a first item.
-- "use pad to get IDEA-1" → also `/pad onboard`. Legacy phrasing from before PLAN-1496; the IDEA-1/PLAN-2/TASK-3/DOC-4 seed-item pattern was retired. Don't try to fetch `IDEA-1` directly — newly-created workspaces don't have it.
+- "set up my workspace" / "onboard me" / "scan this codebase" → **run the onboard playbook.** Natural language is the canonical trigger and works on every surface; the slug shortcuts (`/pad onboard` in Claude Code, `$pad onboard` in Codex, the `pad_onboard` MCP prompt) are equivalent entry points into the same playbook. To run it, load the body and follow it: `pad playbook show onboard --format markdown` (CLI) or `pad_playbook` with `action: get` (MCP). Activate via library first if the bootstrap's `playbooks` array lacks `invocation_slug=onboard, status=active`. The playbook's body is the script — surface-agnostic interview, codebase scan if available, adapt seeded artifacts to the project, seed a first item.
+- "use pad to get IDEA-1" → also runs the onboard playbook. Legacy phrasing from before PLAN-1496; the IDEA-1/PLAN-2/TASK-3/DOC-4 seed-item pattern was retired. Don't try to fetch `IDEA-1` directly — newly-created workspaces don't have it.
 
 **Creating a playbook:** "save this workflow as a playbook" / "let's make a playbook for X" / "I want a `/pad <slug>` for this" → Create an item in the `playbooks` collection. Two fields make it user-callable:
 
@@ -340,7 +340,7 @@ Use the `decompose` invokable playbook: **`/pad decompose <PLAN-ref>`**. Accepts
 
 ### Onboarding
 
-Use the `/pad onboard` invokable playbook — see the **Onboarding** entry under Natural Language Routing above. The playbook body is the canonical instruction set (interview flow, codebase scan if available, collection/convention/role/playbook adaptation, first-item seed). Don't reimplement it here; this skill is the dispatcher, the playbook is the script. PLAN-1496 / TASK-1499 retired the standalone Onboarding workflow that used to live in this file.
+Run the **onboard** invokable playbook — see the **Onboarding** entry under Natural Language Routing above. Natural language ("set up my workspace") is the canonical trigger; `/pad onboard`, `$pad onboard`, and the `pad_onboard` MCP prompt are per-surface shortcuts into the same playbook. The playbook body is the canonical instruction set (interview flow, codebase scan if available, collection/convention/role/playbook adaptation, first-item seed). Don't reimplement it here; this skill is the dispatcher, the playbook is the script. PLAN-1496 / TASK-1499 retired the standalone Onboarding workflow that used to live in this file.
 
 ### Retrospective: "Plan X is done, let's retro"