askshepherd 0.1.44 → 0.1.45

package/bin/shepherd.js

@@ -12,6 +12,7 @@ const DEFAULT_STATE_PATH = join(homedir(), ".shepherd", "mcp.json");
 const DEFAULT_AGENT_STATE_PATH = join(homedir(), ".shepherd", "raw-onboarding-agent.json");
 const PACKAGE_SPEC = "askshepherd@latest";
 const PUBLIC_COMMAND = `npx -y ${PACKAGE_SPEC}`;
+const SKILL_INSTALL_TARGETS = ["codex", "claude"];
 const MCP_ENVIRONMENT_TARGETS = {
   deploy: {
     label: "Customer deploy",
@@ -94,6 +95,16 @@ async function dispatch() {
     return;
   }
 
+  if (command === "guide" || command === "workflow") {
+    await runGuide();
+    return;
+  }
+
+  if (command === "troubleshoot" || command === "doctor") {
+    await runTroubleshoot();
+    return;
+  }
+
   if (command === "onboard") {
     await runOnboardCommand();
     return;
@@ -215,6 +226,468 @@ async function runCall() {
   await runToolByName(toolName);
 }
 
+async function runGuide() {
+  const payload = await buildGuidePayload();
+  if (args.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  console.log(renderGuide(payload));
+}
+
+async function runTroubleshoot() {
+  const payload = await buildTroubleshootPayload();
+  if (args.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  console.log(renderTroubleshoot(payload));
+}
+
+async function buildGuidePayload() {
+  const [agentPrompt, statusResult] = await Promise.all([
+    loadEngineAgentPrompt(),
+    collectStatusJson(),
+  ]);
+  const onboardingState = await readOnboardingStateOptional(statusResult.status?.statePath);
+  const apiUrl = trimTrailingSlash(stringArg("api") ?? onboardingState?.apiUrl ?? DEFAULT_API_URL);
+  const capabilities = await fetchOnboardingCapabilities(apiUrl);
+  const sourceRows = onboardingSourceRows(capabilities);
+  const workflow = guideWorkflow({ sourceRows });
+  return {
+    command: `${PUBLIC_COMMAND} guide`,
+    apiUrl,
+    currentState: summarizeGuideState(statusResult, onboardingState),
+    capabilities,
+    sourceSelection: {
+      instruction: "Use a native multi-select window/control when your agent environment supports it. Otherwise ask one concise multi-select question in chat.",
+      options: sourceRows,
+    },
+    workflow,
+    help: {
+      command: `${PUBLIC_COMMAND} troubleshoot`,
+      instruction: "Run this if onboarding state, source setup, local sync, MCP tools, or wiki readiness is unclear.",
+    },
+    canonicalEnginePrompt: agentPrompt,
+  };
+}
+
+async function buildTroubleshootPayload() {
+  const guide = await buildGuidePayload();
+  return {
+    command: `${PUBLIC_COMMAND} troubleshoot`,
+    apiUrl: guide.apiUrl,
+    currentState: guide.currentState,
+    capabilities: guide.capabilities,
+    diagnostics: troubleshootDiagnostics(guide.currentState),
+    help: guide.help,
+  };
+}
+
+async function loadEngineAgentPrompt() {
+  const argv = ["agent", "--json"];
+  appendEngineContextArgs(argv);
+  const result = await execEngineCapture(argv);
+  if (result.exitCode !== 0) {
+    return {
+      status: "unavailable",
+      error: renderCapturedCommand(result),
+    };
+  }
+  try {
+    return {
+      status: "available",
+      payload: JSON.parse(result.stdout),
+    };
+  } catch {
+    return {
+      status: "invalid_json",
+      error: "The Shepherd onboarding engine did not return valid JSON for its agent workflow prompt.",
+    };
+  }
+}
+
+async function collectStatusJson() {
+  const argv = ["status", "--json"];
+  appendEngineContextArgs(argv);
+  const result = await execEngineCapture(argv);
+  if (result.exitCode !== 0) {
+    return {
+      status: null,
+      error: renderCapturedCommand(result),
+    };
+  }
+  try {
+    return {
+      status: JSON.parse(result.stdout),
+      error: null,
+    };
+  } catch {
+    return {
+      status: null,
+      error: "The Shepherd status command did not return valid JSON.",
+    };
+  }
+}
+
+function appendEngineContextArgs(argv) {
+  // Deliberately excludes --state: the wrapper documents it as the MCP token
+  // state path, but the engine would read it as the onboarding agent state.
+  for (const key of ["api", "onboarding-state", "channel"]) {
+    const value = stringArg(key);
+    if (value) argv.push(`--${key}`, value);
+  }
+}
+
+async function readOnboardingStateOptional(enginePath) {
+  const path = typeof enginePath === "string" && enginePath ? enginePath : onboardingStatePathForGuide();
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf8"));
+    return recordValue(parsed);
+  } catch {
+    return null;
+  }
+}
+
+function onboardingStatePathForGuide() {
+  const explicit = stringArg("onboarding-state");
+  if (explicit) return expandHome(explicit);
+  // Mirrors the engine's cliChannel()/agentStatePath(): any non-stable channel
+  // gets a suffixed state file, and env channels count.
+  const channel = [stringArg("channel"), process.env.SHEPHERD_ONBOARD_CHANNEL, process.env.SHEPHERD_APP_CHANNEL]
+    .map((value) => String(value ?? "").trim().toLowerCase())
+    .find(Boolean) ?? "stable";
+  if (channel !== "stable") {
+    return join(homedir(), ".shepherd", `raw-onboarding-agent.${channel}.json`);
+  }
+  return DEFAULT_AGENT_STATE_PATH;
+}
+
+async function fetchOnboardingCapabilities(apiUrl) {
+  let endpoint = String(apiUrl);
+  try {
+    endpoint = new URL("/onboarding/raw/capabilities", `${trimTrailingSlash(apiUrl)}/`).toString();
+    const response = await fetch(endpoint, { signal: AbortSignal.timeout(10_000) });
+    const body = await response.json().catch(() => ({}));
+    if (!response.ok) {
+      return {
+        status: "unavailable",
+        endpoint,
+        error: safeError(body?.error ?? `capabilities request failed (${response.status})`),
+        sources: {},
+      };
+    }
+    return {
+      status: "available",
+      endpoint,
+      sources: normalizeCapabilities(body),
+    };
+  } catch (err) {
+    return {
+      status: "unavailable",
+      endpoint,
+      error: safeError(err),
+      sources: {},
+    };
+  }
+}
+
+function normalizeCapabilities(body) {
+  const sources = recordValue(body?.sources) ?? recordValue(body?.capabilities?.sources) ?? {};
+  const normalized = {};
+  for (const source of onboardingSourceDefinitions()) {
+    const raw = sources[source.capabilityKey];
+    normalized[source.capabilityKey] = raw === undefined ? source.defaultAvailable === true : raw !== false;
+  }
+  return normalized;
+}
+
+function onboardingSourceDefinitions() {
+  return [
+    { capabilityKey: "google", sourceId: "google", label: "Google Workspace", detail: "Gmail, Drive, Docs, Calendar, Sheets, Slides, Tasks, Contacts via domain-wide delegation" },
+    { capabilityKey: "notion", sourceId: "notion", label: "Notion", detail: "browser OAuth" },
+    { capabilityKey: "slack", sourceId: "slack", label: "Slack", detail: "browser OAuth" },
+    { capabilityKey: "github", sourceId: "github", label: "GitHub", detail: "PAT + owner/repo for webhook-backed event sync" },
+    { capabilityKey: "granola", sourceId: "granola", label: "Granola", detail: "browser OAuth, with legacy API-key fallback" },
+    { capabilityKey: "messages", sourceId: "messages", label: "Messages", detail: "local macOS source; requires explicit consent, Full Disk Access, and chat selection", localOnly: true },
+    { capabilityKey: "codingSessions", sourceId: "coding-sessions", label: "Coding Sessions", detail: "local Codex/Claude Code metadata sync; requires explicit consent", defaultAvailable: true, localOnly: true },
+  ];
+}
+
+function onboardingSourceRows(capabilities) {
+  const availableSources = capabilities.status === "available" ? capabilities.sources : {};
+  return onboardingSourceDefinitions().map((source) => ({
+    id: source.sourceId,
+    label: source.label,
+    // Local-only sources never depend on backend capability reporting; backend
+    // OAuth sources stay fail-closed when capabilities are unavailable.
+    available: source.localOnly === true
+      ? true
+      : capabilities.status === "available" && availableSources?.[source.capabilityKey] !== false,
+    detail: source.detail,
+  }));
+}
+
+function summarizeGuideState(statusResult, onboardingState) {
+  const status = statusResult.status;
+  const wikiReadiness = status ? wikiReadinessPayloadFromStatus(status) : null;
+  const sourceRows = status ? statusSourceRowsFromStatus(status) : [];
+  return {
+    configured: Boolean(status?.configured ?? onboardingState),
+    statusError: statusResult.error,
+    account: status?.account ?? onboardingState?.account ?? null,
+    production: status?.production ?? null,
+    productionError: status?.productionError ?? null,
+    savedSources: status?.savedSources ?? onboardingState?.sources ?? {},
+    sources: sourceRows,
+    wikiReadiness,
+    local: status?.local ?? null,
+    commands: status?.commands ?? {
+      login: `${PUBLIC_COMMAND} login`,
+      continueSetup: `${PUBLIC_COMMAND} continue`,
+      checkStatus: `${PUBLIC_COMMAND} status`,
+      messagesChats: `${PUBLIC_COMMAND} messages-chats`,
+    },
+  };
+}
+
+function statusSourceRowsFromStatus(status) {
+  const providers = recordValue(status?.providers) ?? {};
+  const savedSources = recordValue(status?.savedSources) ?? {};
+  const definitions = [
+    ["google", "Google Workspace", "google"],
+    ["notion", "Notion", "notion"],
+    ["slack", "Slack", "slack"],
+    ["github", "GitHub", "github"],
+    ["granola", "Granola", "granola"],
+    ["messages", "Messages", "messages"],
+    ["codingSessions", "Coding Sessions", "codingSessions"],
+  ];
+  return definitions.map(([key, label, sourceKey]) => ({
+    key,
+    label,
+    selected: savedSources[sourceKey] === true,
+    seen: Boolean(providers[key]),
+    connected: providers[key]?.connected === true,
+  }));
+}
+
+function guideWorkflow({ sourceRows }) {
+  const sourceList = sourceRows
+    .filter((source) => source.available)
+    .map((source) => source.id)
+    .join(",");
+  return [
+    {
+      id: "install_usage_skill",
+      title: "Ask where to install the Shepherd usage skill",
+      prompt: "Ask the user whether to install the Shepherd usage skill into Codex, Claude Code, both, or skip for now.",
+      commands: [`${PUBLIC_COMMAND} skill --install <codex|claude|all>`],
+    },
+    {
+      id: "workos_login",
+      title: "Authenticate with WorkOS",
+      prompt: "Run one Shepherd WorkOS login/signup flow. Use the returned email as account identity; do not ask for email separately.",
+      commands: [`${PUBLIC_COMMAND} login`],
+    },
+    {
+      id: "name_org",
+      title: "Collect name and organization",
+      prompt: "Ask for full name and organization name. Shepherd verifies existing organization joins from the authenticated account and company email domain; typed org text is not trusted by itself.",
+      commands: [],
+    },
+    {
+      id: "source_selection",
+      title: "Show source selection",
+      prompt: `Put up a native multi-select window/control if available. Offer only connectable sources (${sourceList || "none reported"}). Ask explicit consent before Messages or Coding Sessions, and never default Messages to all chats.`,
+      commands: [],
+    },
+    {
+      id: "start_onboarding",
+      title: "Start source onboarding",
+      prompt: "Run onboarding with only the sources the user selected. Use comma-separated source ids from the guide output.",
+      commands: [`${PUBLIC_COMMAND} onboard --name "<full_name>" --org "<organization>" --sources "<selected_sources>"`],
+    },
+    {
+      id: "continue_modalities",
+      title: "Complete one setup modality at a time",
+      prompt: "After each browser/admin/PAT/local permission step, run continue and follow the current modality it prints. Do not open later source setup surfaces until the command advances.",
+      commands: [`${PUBLIC_COMMAND} continue`],
+    },
+    {
+      id: "verify_readiness",
+      title: "Verify setup and wiki readiness",
+      prompt: "Check local sync, wiki readiness, and the live tool catalog. If wiki status is wiki_not_ready, tell the user Shepherd is still learning and include progress/ETA instead of answering memory questions.",
+      commands: [`${PUBLIC_COMMAND} status`, `${PUBLIC_COMMAND} shepherd_wiki_status`, `${PUBLIC_COMMAND} tools --json`],
+    },
+    {
+      id: "install_query_tools",
+      title: "Ask where to install Shepherd MCP",
+      prompt: "After onboarding completes, ask whether to install Shepherd MCP into Codex, Claude Code, both, or none so Shepherd is queryable from their tools.",
+      commands: [`${PUBLIC_COMMAND} mcp-login --install <codex|claude|all>`],
+    },
+  ];
+}
+
+function renderGuide(payload) {
+  const lines = ["Shepherd agent onboarding workflow", ""];
+  lines.push("Use this workflow in order. Keep prompts short and interactive; do not paste the whole checklist to the user unless they ask.");
+  lines.push(`API target: ${payload.apiUrl}`);
+  lines.push("");
+  lines.push("Current state:");
+  lines.push(...renderGuideCurrentState(payload.currentState).map((line) => `- ${line}`));
+  lines.push("");
+  lines.push("Available source choices:");
+  for (const source of payload.sourceSelection.options) {
+    lines.push(`- ${source.available ? "[available]" : "[unavailable]"} ${source.label} (${source.id}): ${source.detail}`);
+  }
+  if (payload.capabilities.status !== "available") {
+    lines.push(`- Capability check unavailable from ${payload.capabilities.endpoint}: ${payload.capabilities.error}`);
+  }
+  lines.push("");
+  lines.push("Workflow:");
+  payload.workflow.forEach((step, index) => {
+    lines.push(`${index + 1}. ${step.title}`);
+    lines.push(`   ${step.prompt}`);
+    for (const command of step.commands) lines.push(`   Run: ${command}`);
+  });
+  lines.push("");
+  lines.push("If confused or blocked:");
+  lines.push(`- Run: ${payload.help.command}`);
+  lines.push(`- ${payload.help.instruction}`);
+  lines.push("");
+  lines.push("Canonical engine prompt:");
+  if (payload.canonicalEnginePrompt.status === "available") {
+    lines.push("- The onboarding engine prompt is available in `shepherd guide --json` under `canonicalEnginePrompt.payload`.");
+    lines.push("- It is the source of truth for one-modality-at-a-time setup, Messages Full Disk Access guidance, GitHub PAT setup, and MCP install prompts.");
+  } else {
+    lines.push(`- Unavailable: ${payload.canonicalEnginePrompt.error}`);
+  }
+  return lines.join("\n");
+}
+
+function renderGuideCurrentState(state) {
+  if (state.statusError) return [`Status unavailable: ${state.statusError}`];
+  const lines = [];
+  if (state.account) {
+    const email = state.account.email ? ` <${state.account.email}>` : "";
+    const org = state.account.organizationName ? ` / ${state.account.organizationName}` : "";
+    lines.push(`Account: ${state.account.name ?? "unknown"}${email}${org}`);
+  } else {
+    lines.push("Account: no saved Shepherd onboarding session");
+  }
+  if (state.productionError) lines.push(`Backend status: unavailable (${state.productionError})`);
+  else if (state.production) lines.push(`Backend status: ${state.production.status ?? "unknown"}`);
+  else lines.push("Backend status: not checked");
+  if (state.wikiReadiness) {
+    const wiki = recordValue(state.wikiReadiness.wiki);
+    const progress = wiki?.progress_percent == null ? "" : `, ${wiki.progress_percent}% built`;
+    const eta = wiki?.eta ? `, ETA ${wiki.eta}` : "";
+    lines.push(`Wiki: ${state.wikiReadiness.status}${progress}${eta}`);
+  }
+  const selected = state.sources.filter((source) => source.selected);
+  if (selected.length) {
+    lines.push(`Selected sources: ${selected.map((source) => `${source.label} ${source.connected ? "(connected)" : "(pending)"}`).join(", ")}`);
+  }
+  return lines;
+}
+
+function troubleshootDiagnostics(state) {
+  const diagnostics = [];
+  if (state.statusError) {
+    diagnostics.push({
+      symptom: "Status command failed",
+      likelyCause: "Local onboarding state is missing, unreadable, or points at an unavailable API.",
+      fix: [`Run ${PUBLIC_COMMAND} guide`, `Then retry ${PUBLIC_COMMAND} status --json`],
+    });
+    return diagnostics;
+  }
+
+  if (!state.configured || !state.account) {
+    diagnostics.push({
+      symptom: "No saved Shepherd onboarding session",
+      likelyCause: "WorkOS login has not completed on this machine or the selected --onboarding-state path is empty.",
+      fix: [`Run ${PUBLIC_COMMAND} login`, `Then run ${PUBLIC_COMMAND} guide`],
+    });
+  }
+
+  if (state.productionError) {
+    diagnostics.push({
+      symptom: "Backend status is unavailable",
+      likelyCause: "The saved onboarding token/API target is expired, revoked, or temporarily unreachable.",
+      fix: [`Run ${PUBLIC_COMMAND} login`, `Then run ${PUBLIC_COMMAND} continue`],
+    });
+  }
+
+  for (const source of state.sources.filter((row) => row.selected && !row.connected)) {
+    diagnostics.push({
+      symptom: `${source.label} is selected but not connected`,
+      likelyCause: "That source still has a pending browser/admin/PAT/local permission modality.",
+      fix: [`Run ${PUBLIC_COMMAND} continue`, `If it is Messages, run ${PUBLIC_COMMAND} messages-chats and pass selected chat IDs back to continue.`],
+    });
+  }
+
+  if (state.local?.messages?.configPath && state.local.messages.launch && state.local.messages.launch.running === false) {
+    diagnostics.push({
+      symptom: "Messages LaunchAgent is installed but not running",
+      likelyCause: "macOS Full Disk Access or launchd startup did not validate.",
+      fix: [`Run ${PUBLIC_COMMAND} status`, "Grant Full Disk Access to the onboarding app and Node.js, then rerun continue if status asks for it."],
+    });
+  }
+
+  if (state.local?.messages?.configPath && state.local.messages.storage?.readable === false) {
+    diagnostics.push({
+      symptom: "Messages database is not readable",
+      likelyCause: "Full Disk Access is missing for the app running Shepherd onboarding.",
+      fix: ["Open System Settings -> Privacy & Security -> Full Disk Access and enable the terminal/agent app plus Node.js.", `Then run ${PUBLIC_COMMAND} messages-chats`],
+    });
+  }
+
+  if (state.local?.codingSessions?.configPath && state.local.codingSessions.launch && state.local.codingSessions.launch.running === false) {
+    diagnostics.push({
+      symptom: "Coding Sessions LaunchAgent is installed but not running",
+      likelyCause: "launchd startup failed or macOS denied access to the session folders.",
+      fix: [`Run ${PUBLIC_COMMAND} coding-sessions-status`, `Then run ${PUBLIC_COMMAND} continue if status asks for setup repair.`],
+    });
+  }
+
+  if (state.wikiReadiness?.status === "wiki_not_ready") {
+    diagnostics.push({
+      symptom: "Wiki is not ready yet",
+      likelyCause: "Initial ingestion/wiki processing is still building. This is not a setup failure.",
+      fix: ["Tell the user Shepherd is still learning about them, include progress/ETA from shepherd_wiki_status, and retry the memory question later."],
+    });
+  }
+
+  if (diagnostics.length === 0) {
+    diagnostics.push({
+      symptom: "No obvious local onboarding blocker found",
+      likelyCause: "Setup appears coherent from local status.",
+      fix: [`Run ${PUBLIC_COMMAND} tools --json to verify query tools, then use exact listed tool names.`],
+    });
+  }
+  return diagnostics;
+}
+
+function renderTroubleshoot(payload) {
+  const lines = ["Shepherd troubleshooting", ""];
+  lines.push(`API target: ${payload.apiUrl}`);
+  lines.push("");
+  lines.push("Current state:");
+  lines.push(...renderGuideCurrentState(payload.currentState).map((line) => `- ${line}`));
+  lines.push("");
+  lines.push("Diagnostics:");
+  payload.diagnostics.forEach((item, index) => {
+    lines.push(`${index + 1}. ${item.symptom}`);
+    lines.push(`   Likely cause: ${item.likelyCause}`);
+    for (const fix of item.fix) lines.push(`   Fix: ${fix}`);
+  });
+  lines.push("");
+  lines.push(`For the full workflow, run: ${PUBLIC_COMMAND} guide`);
+  return lines.join("\n");
+}
+
 async function runToolByName(toolName) {
   const toolArgs = await readToolArgs();
   const localNames = new Set(localToolDefinitions({ environmentControls: true }).map((tool) => tool.name));
@@ -323,6 +796,20 @@ function localToolDefinitions(opts = {}) {
     openWorldHint: false,
   };
   const tools = [
+    {
+      name: "shepherd_onboarding_guide",
+      description: "LOCAL agent-facing Shepherd onboarding workflow. Use when setting up Shepherd, choosing sources, deciding skill/MCP install targets, or recovering the next onboarding step.",
+      inputSchema: emptyInputSchema,
+      annotations: readOnlyAnnotations,
+      _meta: { provider: "local_cli", command: "shepherd guide" },
+    },
+    {
+      name: "shepherd_troubleshoot",
+      description: "LOCAL state-aware Shepherd onboarding/setup help. Use when confused, blocked, auth expired, source setup is pending, local sync is unhealthy, or the wiki is still building.",
+      inputSchema: emptyInputSchema,
+      annotations: readOnlyAnnotations,
+      _meta: { provider: "local_cli", command: "shepherd troubleshoot" },
+    },
     {
       name: "shepherd_status",
       description: "LOCAL Shepherd setup and sync status. Use this first when the user asks what they have enabled, what is connected, whether Shepherd is syncing, or why local Messages/Coding Sessions are not running.",
@@ -394,6 +881,14 @@ function localToolDefinitions(opts = {}) {
 }
 
 async function callLocalTool(name) {
+  if (name === "shepherd_onboarding_guide") {
+    return textResult(renderGuide(await buildGuidePayload()), false);
+  }
+
+  if (name === "shepherd_troubleshoot") {
+    return textResult(renderTroubleshoot(await buildTroubleshootPayload()), false);
+  }
+
   if (name === "shepherd_environment_status") {
     return textResult(await renderCliEnvironmentStatus(), false);
   }
@@ -492,6 +987,7 @@ function printInstructions() {
 - Use shepherd tools --json as the source of truth for all available MCP-equivalent tools.
 - Use exact tool names only: shepherd call <tool_name> --args '<json_object>'.
 - Unknown commands are treated as exact tool names, so shepherd <tool_name> --args '<json_object>' is also valid.
+- For onboarding, run shepherd guide and follow the returned workflow. If blocked, run shepherd troubleshoot.
 - Run shepherd onboard to create/select the account, link sources, and mint CLI tool auth.
 - Use shepherd_status for local setup/sync-health and shepherd_wiki_status before memory/wiki questions when readiness is uncertain. Do not inspect the user's home directory, repositories, ~/.shepherd, ~/.codex, or ~/.claude yourself.
 - If shepherd_wiki_status or a production Shepherd tool returns status: "wiki_not_ready", do not answer the memory/wiki question yet; report the readiness progress/ETA instead.
@@ -503,18 +999,23 @@ function printInstructions() {
 async function runSkill() {
   const skillText = await readFile(SKILL_PATH, "utf8");
   const outputPath = stringArg("output");
-  const installTarget = stringArg("install");
-  const destination = outputPath
-    ? expandHome(outputPath)
-    : installTarget
-      ? skillInstallPath(installTarget)
-      : null;
-
-  if (destination) {
-    await mkdir(dirname(destination), { recursive: true });
-    await writeFile(destination, skillText);
-    if (args.json) console.log(JSON.stringify({ path: destination }, null, 2));
-    else console.log(`Wrote Shepherd skill: ${destination}`);
+  const installTarget = stringArg("install") ?? (args.install === true ? "codex" : undefined);
+
+  if (outputPath || installTarget) {
+    const installed = installTarget ? await writeSkillInstallTargets(installTarget, skillText) : [];
+    let outputDestination = null;
+    if (outputPath) {
+      outputDestination = expandHome(outputPath);
+      await mkdir(dirname(outputDestination), { recursive: true });
+      await writeFile(outputDestination, skillText);
+    }
+    if (args.json) {
+      console.log(JSON.stringify({ path: outputDestination ?? installed[0]?.path ?? null, installed }, null, 2));
+    } else {
+      if (outputDestination) console.log(`Wrote Shepherd skill: ${outputDestination}`);
+      for (const entry of installed) console.log(`Wrote Shepherd skill for ${entry.target}: ${entry.path}`);
+      if (!outputDestination && installed.length === 0) console.log("Shepherd skill install skipped.");
+    }
     return;
   }
 
@@ -523,12 +1024,12 @@ async function runSkill() {
 
 async function runAgentSetup() {
   const target = args["no-install"] ? null : stringArg("install") ?? "codex";
-  let installedPath = null;
+  let installed = [];
   if (target) {
-    installedPath = await writeSkill(target);
+    installed = await writeSkill(target);
   }
 
-  const payload = agentSetupPayload(installedPath);
+  const payload = agentSetupPayload(installed);
   if (args.json) {
     console.log(JSON.stringify(payload, null, 2));
     return;
@@ -536,7 +1037,7 @@ async function runAgentSetup() {
 
   console.log(`Shepherd agent setup
 
-Installed skill: ${installedPath ?? "skipped"}
+Installed skill: ${installed.length ? installed.map((entry) => `${entry.target}: ${entry.path}`).join(", ") : "skipped"}
 
 One-line prompt to give an agent:
 ${payload.oneLinePrompt}
@@ -545,11 +1046,14 @@ Bootstrap prompt when the agent does not already have the skill:
 ${payload.bootstrapPrompt}
 
 Agent instructions:
-1. Ask the user which sources to connect and ask consent before Messages or Coding Sessions.
-2. Run ${payload.commands.login}.
-3. Run ${payload.commands.onboard}.
-4. Run ${payload.commands.continue} after each browser/admin/local permission step.
-5. Finish with ${payload.commands.status}, ${payload.commands.wikiStatus}, and ${payload.commands.tools}.
+1. Run ${payload.commands.guide} and follow the returned workflow.
+2. Confirm the usage skill install target (agent-setup installs Codex by default; adjust with ${payload.commands.installSkill}).
+3. Ask which sources to connect with a multi-select UI when available; ask consent before Messages or Coding Sessions.
+4. Run ${payload.commands.login}.
+5. Run ${payload.commands.onboard}.
+6. Run ${payload.commands.continue} after each browser/admin/local permission step.
+7. Finish with ${payload.commands.status}, ${payload.commands.wikiStatus}, and ${payload.commands.tools}.
+8. If blocked, run ${payload.commands.troubleshoot}.
 
 Customer default:
 - Do not pass --env for normal customer setup or tool calls. The CLI defaults to the Production Customer deploy lane.
@@ -564,20 +1068,34 @@ Environment selection changes the tool catalog, tool execution, and backend data
 
 async function writeSkill(target) {
   const skillText = await readFile(SKILL_PATH, "utf8");
-  const destination = skillInstallPath(target);
-  await mkdir(dirname(destination), { recursive: true });
-  await writeFile(destination, skillText);
-  return destination;
+  return writeSkillInstallTargets(target, skillText);
+}
+
+async function writeSkillInstallTargets(target, skillText) {
+  const targets = parseSkillInstallTargets(target);
+  const installed = [];
+  for (const installTarget of targets) {
+    const destination = skillInstallPath(installTarget);
+    await mkdir(dirname(destination), { recursive: true });
+    await writeFile(destination, skillText);
+    installed.push({ target: installTarget, path: destination });
+  }
+  return installed;
 }
 
-function agentSetupPayload(installedPath) {
-  const bootstrapPrompt = `Set up Shepherd for me: run \`${PUBLIC_COMMAND} agent-setup\`, follow its prompts, ask me before connecting each source, then verify with \`${PUBLIC_COMMAND} status\`, \`${PUBLIC_COMMAND} shepherd_wiki_status\`, and \`${PUBLIC_COMMAND} tools --json\`.`;
+function agentSetupPayload(installed) {
+  const installedSkillPath = installed[0]?.path ?? null;
+  const bootstrapPrompt = `Set up Shepherd for me: run \`${PUBLIC_COMMAND} agent-setup\` (installs the Codex usage skill by default; pass --install claude|all|none to change), then \`${PUBLIC_COMMAND} guide\`; follow the returned workflow, ask me where to install MCP tools, ask consent before connecting each source, then verify with \`${PUBLIC_COMMAND} status\`, \`${PUBLIC_COMMAND} shepherd_wiki_status\`, and \`${PUBLIC_COMMAND} tools --json\`.`;
   return {
-    installedSkillPath: installedPath,
+    installedSkillPath,
+    installedSkillPaths: installed,
     oneLinePrompt: "Use the Shepherd skill to onboard me to this repository before coding.",
     bootstrapPrompt,
     commands: {
       agentSetup: `${PUBLIC_COMMAND} agent-setup`,
+      guide: `${PUBLIC_COMMAND} guide`,
+      troubleshoot: `${PUBLIC_COMMAND} troubleshoot`,
+      installSkill: `${PUBLIC_COMMAND} skill --install <codex|claude|all>`,
       login: `${PUBLIC_COMMAND} login`,
       onboard: `${PUBLIC_COMMAND} onboard --name "<full_name>" --org "<organization>" --sources "<sources>"`,
       continue: `${PUBLIC_COMMAND} continue`,
@@ -602,12 +1120,37 @@ function agentSetupPayload(installedPath) {
   };
 }
 
+function parseSkillInstallTargets(value) {
+  const raw = String(value ?? "").trim().toLowerCase();
+  if (!raw || raw === "codex") return ["codex"];
+  if (raw === "all" || raw === "both" || raw === "yes" || raw === "true") return [...SKILL_INSTALL_TARGETS];
+  if (raw === "none" || raw === "no" || raw === "false" || raw === "skip") return [];
+  const aliases = new Map([
+    ["codex-cli", "codex"],
+    ["claude-code", "claude"],
+    ["claude", "claude"],
+  ]);
+  const targets = raw
+    .split(/[,\s]+/)
+    .map((target) => aliases.get(target) ?? target)
+    .filter(Boolean);
+  for (const target of targets) {
+    if (!SKILL_INSTALL_TARGETS.includes(target)) {
+      throw new Error(`unknown skill install target "${target}". Use codex, claude, all, none, or --output <path>.`);
+    }
+  }
+  return [...new Set(targets)];
+}
+
 function skillInstallPath(target) {
   const normalized = String(target ?? "").trim().toLowerCase();
   if (!normalized || normalized === "codex") {
     return join(homedir(), ".codex", "skills", "shepherd", "SKILL.md");
   }
-  throw new Error(`unknown skill install target "${target}". Use codex or --output <path>.`);
+  if (normalized === "claude") {
+    return join(homedir(), ".claude", "skills", "shepherd", "SKILL.md");
+  }
+  throw new Error(`unknown skill install target "${target}". Use codex, claude, all, none, or --output <path>.`);
 }
 
 function printHelp() {
@@ -616,6 +1159,8 @@ function printHelp() {
 Usage:
   npx -y askshepherd@latest
   npx -y askshepherd@latest agent-setup
+  shepherd guide
+  shepherd troubleshoot
   shepherd login
   shepherd onboard
   shepherd continue
@@ -625,10 +1170,12 @@ Usage:
   shepherd <tool_name> --args '<json_object>'
   shepherd status
   shepherd instructions
-  shepherd skill [--install codex|--output <path>]
+  shepherd skill [--install codex|claude|all|--output <path>]
 
 Commands:
   agent-setup               Install/print the one-line coding-agent setup handoff.
+  guide                     Print the agent-facing onboarding workflow.
+  troubleshoot              Print state-aware setup/onboarding help.
   login                     Authenticate Shepherd account and save local onboarding auth.
   onboard                   Create/select account, link sources, and prepare tool auth.
   continue                  Resume pending source setup.
@@ -638,7 +1185,7 @@ Commands:
   <tool_name>               Call one exact Shepherd MCP tool.
   status                    Shorthand for shepherd_status.
   instructions              Print agent-facing behavior instructions.
-  skill                     Print or write the bundled Codex skill.
+  skill                     Print or write the bundled usage skill.
 
 Options:
   --args <json>             JSON object passed to a tool call.
@@ -650,7 +1197,7 @@ Options:
   --url <url>               Override the MCP endpoint.
   --token <token>           Override the bearer token.
   --env <environment>       askshepherd.ai only: select deploy, canary, or customer-facing for tools/calls.
-  --install codex           With skill, write to ~/.codex/skills/shepherd/SKILL.md.
+  --install <targets>       With skill, write to codex, claude, all, none, or comma-separated targets.
   --output <path>           With skill, write SKILL.md to this path.
   --json                    Print machine-readable output where supported.
   --help                    Show this help.