@agent-native/core 0.51.15 → 0.53.0

package/dist/cli/skills.js

@@ -19,9 +19,9 @@ const HELP = `npx @agent-native/core@latest skills
 
 Usage:
   npx @agent-native/core@latest skills list
-  npx @agent-native/core@latest skills status [assets|design-exploration|visual-plan|visual-recap|context-xray] [--client codex|claude-code|all] [--scope user|project] [--json]
-  npx @agent-native/core@latest skills update [assets|design-exploration|visual-plan|visual-recap|context-xray] [--client codex|claude-code|all] [--scope user|project] [--dry-run] [--json]
-  npx @agent-native/core@latest skills add assets|design-exploration|visual-plan|visual-recap|context-xray [--client codex|claude-code|claude-code-cli|cowork|all] [--scope user|project] [--mode hosted|local-files|self-hosted] [--mcp-url <url>] [--no-connect] [--with-github-action] [--yes] [--dry-run] [--json]
+  npx @agent-native/core@latest skills status [assets|design-exploration|visual-plan|visual-recap|context-xray] [--client codex|claude-code|pi|all] [--scope user|project] [--json]
+  npx @agent-native/core@latest skills update [assets|design-exploration|visual-plan|visual-recap|context-xray] [--client codex|claude-code|pi|all] [--scope user|project] [--dry-run] [--json]
+  npx @agent-native/core@latest skills add assets|design-exploration|visual-plan|visual-recap|context-xray [--client codex|claude-code|cowork|cursor|opencode|github-copilot|all] [--scope user|project] [--mode hosted|local-files|self-hosted] [--mcp-url <url>] [--no-connect] [--with-github-action] [--yes] [--dry-run] [--json]
   npx @agent-native/core@latest skills add <manifest-or-app-dir|skill-repo> [--skill <name>] [--client ...] [--yes]
 
 Examples:
@@ -44,11 +44,14 @@ Examples:
 
 The add command installs the SKILL.md instructions, registers the app-backed
 MCP connector, and then authenticates it in one step so you do not hit an OAuth
-wall on the first tool call. By default, add targets every supported local
-client this CLI can configure (Claude Code, Codex, and Cowork);
-pass --client to narrow it. Authentication reuses "npx @agent-native/core@latest connect":
-OAuth-capable clients (Claude Code) get a URL-only entry and a /mcp authenticate
-prompt, while Codex / Cowork run the browser device-code flow. In a
+wall on the first tool call. Hosted installs can configure Claude Code, Codex,
+Claude Cowork, Cursor, OpenCode, and GitHub Copilot / VS Code; local-files
+instruction installs target the shared .agents skill path used by Codex, Pi,
+Cursor, OpenCode, Copilot, and similar agents, plus Claude Code's native skill
+path when selected. Pass --client to narrow it. Authentication reuses
+"npx @agent-native/core@latest connect": OAuth-capable clients (Claude Code,
+Cursor, OpenCode, GitHub Copilot / VS Code) get URL-only entries and authenticate
+inside that host, while Codex / Cowork run the browser device-code flow. In a
 non-interactive shell or CI the auth step is skipped and the exact
 "npx @agent-native/core@latest connect <url> --client all" command is printed instead.
 
@@ -66,12 +69,12 @@ plans and recaps should live: hosted Plans for shareable links/comments, local
 files for "No sharing, all local.", or a self-hosted/custom Plan app URL.
 Pass --mode to choose directly. Local-files mode skips MCP registration and
 auth and installs instructions that default to a no-auth block catalog fetch,
-MDX folders, and local preview.
+MDX folders, and the localhost bridge viewer.
 
 When installing visual-recap interactively, the CLI offers to add the optional PR
 Visual Recap GitHub Action. Pass --with-github-action to write it directly, then
 run "npx @agent-native/core@latest recap setup" / "npx @agent-native/core@latest recap doctor" to configure and
-verify GitHub Actions.
+verify GitHub Actions. Docs: https://www.agent-native.com/docs/pr-visual-recap.
 
 The status/update commands inspect copied Agent Native skill folders and refresh
 their instruction files from the current @agent-native/core package.`;
@@ -271,10 +274,10 @@ npx @agent-native/core@latest skills add visual-plan --mode local-files
 This mode does not register the Plan MCP connector. Before authoring structured
 MDX, fetch the no-auth, schema-only block catalog with
 \`npx @agent-native/core@latest plan blocks --out plan-blocks.md\`, read that file,
-write \`plans/<slug>/plan.mdx\` locally, then run \`plan local preview\`. Plain
-text skill installs (Vercel Skills CLI, copied GitHub files, etc.) can follow
-that same local flow if \`@agent-native/core\` is available. Text alone cannot
-register MCP tools; hosted/shareable Plans still need the Agent-Native CLI
+write the MDX folder locally, then run \`plan local serve\`. Plain text skill
+installs (Vercel Skills CLI, copied GitHub files, etc.) can follow that same
+local flow if \`@agent-native/core\` is available. Text alone cannot register
+MCP tools; hosted/shareable Plans still need the Agent-Native CLI
 install/reconnect step above.
 
 **Browser (people you share with).** Open the Plans editor and create & edit
@@ -284,10 +287,10 @@ share; signing in claims the plans you made as a guest into your account.
 Sharing and commenting require an account: public/shared plans are viewable by
 anyone with the link, but commenting on them needs an agent-native account.
 
-For fully offline, no-account use, use local-files mode and the local preview
-command. The optional \`plan blocks\` lookup reads only public schema metadata; if
-network access is unavailable, use the bundled references and validate with
-\`plan local preview\`.
+For no-account, no-DB plan storage, use local-files mode and the local bridge
+command. The optional \`plan blocks\` lookup reads only public schema metadata.
+If network access is unavailable, use the bundled references and a local Plan
+app/runtime for validation.
 
 If a Plans tool returns \`needs auth\`, \`Unauthorized\`, or \`Session terminated\`,
 do not keep retrying the tool. Stop and give the user the reconnect step for the
@@ -1312,7 +1315,7 @@ skill — never hand-edit one stored plan. Turn feedback into better guidance.
 ## Local-Files Privacy Mode
 
 Use local-files privacy mode when the user explicitly asks for no DB writes,
-no hosted Plan app, no Plan MCP publish, fully local files, offline/private
+no hosted Plan database writes, no Plan MCP publish, fully local files, offline/private
 planning, repo-owned/source-controlled planning artifacts, or when
 \`AGENT_NATIVE_PLANS_MODE=local-files\` is set. Also use it when a user or repo
 policy says a plan must stay under their own brand, domain, source control, or
@@ -1330,21 +1333,24 @@ The local-files contract is:
   \`plan blocks\` command calls the public no-auth \`get-plan-blocks\` route and
   writes only registry metadata to disk; use \`--format schema\` if exact nested
   fields are needed. If network access is unavailable, use the bundled
-  references and rely on \`plan local preview\` to catch invalid tags.
-- Write the plan as a local MDX folder under \`plans/<slug>/\`: \`plan.mdx\`,
-  optional \`canvas.mdx\`, optional \`prototype.mdx\`, and optional
-  \`.plan-state.json\`.
-- Run \`npx @agent-native/core@latest plan local preview --dir plans/<slug> --kind plan --open\`
-  after writing or updating the folder. Report the returned local URL or the
-  \`/local-plans/<slug>\` route if the local Plan app is running with the same
-  \`PLAN_LOCAL_DIR\`.
+  references and rely on \`plan local serve\` to catch invalid tags.
+- Write the plan as a local MDX folder: use \`plans/<slug>/\` when the user
+  wants the artifact checked into the repo, or use a repo-ignored/temporary
+  folder such as \`.agent-native/plans/<slug>/\` or \`/tmp/agent-native-plans/<slug>/\`
+  when it should not be checked in. The folder contains \`plan.mdx\`, optional
+  \`canvas.mdx\`, optional \`prototype.mdx\`, and optional \`.plan-state.json\`.
+- Run \`npx @agent-native/core@latest plan local serve --dir plans/<slug> --kind plan --open\`
+  after writing or updating the folder. Report the returned local bridge URL. It opens the hosted Plan UI but reads
+  from the localhost bridge on this machine, so it is not shareable across
+  machines. If the Plan app itself is running locally with the same
+  \`PLAN_LOCAL_DIR\`, the \`/local-plans/<slug>\` route is also valid.
 - Do **not** call \`create-visual-plan\`, \`create-ui-plan\`,
   \`create-prototype-plan\`, \`create-plan-design\`, \`import-visual-plan-source\`,
   \`update-visual-plan\`, \`patch-visual-plan-source\`, \`get-plan-feedback\`,
   \`export-visual-plan\`, or any hosted Plan tool for that plan except the
   schema-only block catalog lookup above.
 - Treat feedback as file or chat feedback: update the MDX files directly, rerun
-  the local preview command, and summarize the new local URL/path. Hosted
+  the local bridge command, and summarize the new local bridge URL. Hosted
   comments, sharing, history, and publish/export receipts are unavailable until
   the user explicitly opts into publishing.
 
@@ -1463,7 +1469,7 @@ before spending attention on the literal lines.
 ## Local-Files Privacy Mode Exception
 
 Use local-files privacy mode when the user explicitly asks for no DB writes,
-no hosted Plan app, no Plan MCP publish, fully local files, offline/private
+no hosted Plan database writes, no Plan MCP publish, fully local files, offline/private
 recaps, or when \`AGENT_NATIVE_PLANS_MODE=local-files\` is set. This is the only
 exception to the hosted publish rule below.
 
@@ -1478,22 +1484,26 @@ In local-files mode:
   MCP connector is not registered; it calls the public no-auth
   \`get-plan-blocks\` route and sends no recap content. If network access is
   unavailable, use the bundled references and validate with
-  \`plan local preview\`.
-- Write the recap as a local MDX folder under \`plans/<slug>/\`: \`plan.mdx\`,
-  optional \`canvas.mdx\`, optional \`prototype.mdx\`, and optional
-  \`.plan-state.json\`. Set \`kind: "recap"\` and \`localOnly: true\` in
-  frontmatter/state when authoring the source.
-- Run \`npx @agent-native/core@latest plan local preview --dir plans/<slug> --kind recap --open\`
-  after writing or updating the folder. Report the returned local URL or the
-  \`/local-plans/<slug>\` route if the local Plan app is running with the same
-  \`PLAN_LOCAL_DIR\`.
+  \`plan local serve\`.
+- Write the recap as a local MDX folder: use \`plans/<slug>/\` when the user
+  wants the artifact checked into the repo, or use a repo-ignored/temporary
+  folder such as \`.agent-native/plans/<slug>/\` or \`/tmp/agent-native-plans/<slug>/\`
+  when it should not be checked in. The folder contains \`plan.mdx\`, optional
+  \`canvas.mdx\`, optional \`prototype.mdx\`, and optional \`.plan-state.json\`. Set
+  \`kind: "recap"\` and \`localOnly: true\` in frontmatter/state when authoring
+  the source.
+- Run \`npx @agent-native/core@latest plan local serve --dir plans/<slug> --kind recap --open\`
+  after writing or updating the folder. Report the returned local bridge URL. It opens the hosted Plan UI but reads
+  from the localhost bridge on this machine, so it is not shareable across
+  machines. If the Plan app itself is running locally with the same
+  \`PLAN_LOCAL_DIR\`, the \`/local-plans/<slug>\` route is also valid.
 - Do **not** call \`create-visual-recap\`, \`create-visual-plan\`,
   \`import-visual-plan-source\`, \`update-visual-plan\`,
   \`patch-visual-plan-source\`, \`get-plan-feedback\`, \`export-visual-plan\`,
   \`set-resource-visibility\`, or any hosted Plan tool for that recap except the
   schema-only block catalog lookup above.
 - Treat review feedback as file or chat feedback: update the MDX files directly,
-  rerun the local preview command, and summarize the new local URL/path.
+  rerun the local bridge command, and summarize the new local bridge URL.
   Hosted comments, sharing, screenshots, usage attachment, and PR sticky comment
   publishing are unavailable until the user explicitly opts into publishing.
 
@@ -1704,10 +1714,13 @@ a headless CI agent), state that in the recap handoff instead.
 
 ## Open And Report The Recap
 
-In local-files privacy mode, report the local preview URL/path from
-\`npx @agent-native/core@latest plan local preview\` or the \`/local-plans/<slug>\` route for a local
-Plan app using the same \`PLAN_LOCAL_DIR\`. Do not invent a hosted URL and do not
-publish just to get an absolute Plan link.
+In local-files privacy mode, report the local bridge URL from
+\`npx @agent-native/core@latest plan local serve --dir plans/<slug> --kind recap --open\`.
+It opens the hosted Plan UI but reads from the localhost bridge on this machine,
+so it is not shareable across machines. If the Plan app itself is running
+locally with the same \`PLAN_LOCAL_DIR\`, the \`/local-plans/<slug>\` route is also
+valid. Do not invent a hosted database URL and do not publish just to get an
+absolute Plan link.
 
 After creating the recap, link the reviewer to the rendered plan with an
 **absolute URL on the origin whose database actually holds the plan**. That
@@ -1861,7 +1874,7 @@ was installed as plain text and no MCP tools are registered, run
 \`npx @agent-native/core@latest plan blocks --out plan-blocks.md\` and read that
 file first. The CLI command calls the public no-auth \`get-plan-blocks\` route and
 sends no plan/recap content. If network access is unavailable, use the bundled
-references and validate with \`plan local preview\`.
+references and validate with \`plan local serve\`.
 
 The catalog returns the authoritative, always-current block vocabulary generated
 live from the app's own block registry — the same config the renderer and MDX
@@ -2239,20 +2252,45 @@ const CLIENT_LABELS = {
     "claude-code-cli": "Claude Code CLI",
     codex: "Codex",
     cowork: "Claude Cowork",
+    cursor: "Cursor",
+    opencode: "OpenCode",
+    "github-copilot": "GitHub Copilot / VS Code",
 };
 const CLIENT_HINTS = {
     "claude-code": ".mcp.json or ~/.claude.json",
     "claude-code-cli": ".mcp.json or ~/.claude.json",
     codex: "$CODEX_HOME/config.toml or ~/.codex/config.toml",
     cowork: "~/.cowork/mcp.json",
+    cursor: ".cursor/mcp.json or ~/.cursor/mcp.json",
+    opencode: "opencode.json or ~/.config/opencode/opencode.json",
+    "github-copilot": ".vscode/mcp.json or VS Code user mcp.json",
+};
+const SKILLS_CLIENTS = [
+    "claude-code",
+    "codex",
+    "cowork",
+    "cursor",
+    "opencode",
+    "github-copilot",
+];
+const SKILL_INSTRUCTION_CLIENTS = [
+    "codex",
+    "claude-code",
+    "pi",
+];
+const SKILL_INSTRUCTION_CLIENT_LABELS = {
+    "claude-code": "Claude Code",
+    "claude-code-cli": "Claude Code",
+    codex: "Shared .agents skills",
+    cowork: "MCP only",
+    pi: "Pi",
 };
-const SKILLS_CLIENTS = ["claude-code", "codex", "cowork"];
-const SKILL_INSTRUCTION_CLIENTS = ["claude-code", "codex"];
 const SKILL_INSTRUCTION_CLIENT_HINTS = {
-    "claude-code": ".claude/skills or .claude/commands",
-    "claude-code-cli": ".claude/skills or .claude/commands",
-    codex: ".agents/skills or ~/.codex/skills",
+    "claude-code": "Also write Claude Code's native .claude/skills and commands files.",
+    "claude-code-cli": "Also write Claude Code's native .claude/skills and commands files.",
+    codex: "Project scope writes .agents skills/commands for Codex, Pi, Cursor, OpenCode, Copilot, and similar agents; user scope writes Codex's ~/.codex skills/commands.",
     cowork: "MCP only",
+    pi: "Project scope writes .agents/skills plus .pi/prompts; user scope writes ~/.agents/skills plus ~/.pi/agent/prompts.",
 };
 function normalizeKnownSkillTarget(value) {
     const key = value?.trim().toLowerCase();
@@ -2319,13 +2357,16 @@ function planModeInstructionBlock(input) {
         return `## Installed Mode
 
 Default storage for this installation: local files. Create and update plans and
-recaps as MDX folders under \`plans/<slug>/\`. Before authoring structured MDX,
-run \`npx @agent-native/core@latest plan blocks --out plan-blocks.md\` and read
-the no-auth block catalog; it sends no plan content. Then run
-\`npx @agent-native/core@latest plan local preview --dir plans/<slug> --kind plan|recap --open\`,
-and report the local preview URL or path. No sharing, all local. Use a hosted
-or self-hosted Plan MCP connector only if the user explicitly asks to publish or
-share.`;
+recaps as MDX folders under \`plans/<slug>/\` when they should be checked in, or
+under a repo-ignored/temp folder when they should stay private scratch. Before
+authoring structured MDX, run
+\`npx @agent-native/core@latest plan blocks --out plan-blocks.md\` and read the
+no-auth block catalog; it sends no plan content. Then run
+\`npx @agent-native/core@latest plan local serve --dir plans/<slug> --kind plan|recap --open\`,
+and report the local bridge URL. It opens the hosted Plan UI but reads from the
+localhost bridge on this machine, so it is not shareable across machines. No
+sharing, all local. Use a hosted or self-hosted Plan MCP connector only if the
+user explicitly asks to publish or share.`;
     }
     if (input.mode === "self-hosted") {
         return `## Installed Mode
@@ -2420,17 +2461,68 @@ function writeSkillFolder(dir, bundle, installedAt = new Date().toISOString()) {
 function builtInSkillsRootForAgent(agent, scope, baseDir) {
     const home = homeDir() ?? baseDir;
     if (scope === "project") {
-        return agent === "codex"
-            ? path.join(baseDir, ".agents", "skills")
-            : path.join(baseDir, ".claude", "skills");
+        if (agent === "codex")
+            return path.join(baseDir, ".agents", "skills");
+        if (agent === "pi")
+            return path.join(baseDir, ".agents", "skills");
+        return path.join(baseDir, ".claude", "skills");
     }
     if (agent === "codex") {
         return process.env.CODEX_HOME
             ? path.join(process.env.CODEX_HOME, "skills")
             : path.join(home, ".codex", "skills");
     }
+    if (agent === "pi") {
+        return path.join(home, ".agents", "skills");
+    }
     return path.join(home, ".claude", "skills");
 }
+function builtInCommandsRootForAgent(agent, scope, baseDir) {
+    const home = homeDir() ?? baseDir;
+    if (scope === "project") {
+        if (agent === "codex")
+            return path.join(baseDir, ".agents", "commands");
+        if (agent === "pi")
+            return path.join(baseDir, ".pi", "prompts");
+        return path.join(baseDir, ".claude", "commands");
+    }
+    if (agent === "codex") {
+        return process.env.CODEX_HOME
+            ? path.join(process.env.CODEX_HOME, "commands")
+            : path.join(home, ".codex", "commands");
+    }
+    if (agent === "pi") {
+        const piHome = process.env.PI_CODING_AGENT_DIR || path.join(home, ".pi", "agent");
+        return path.join(piHome, "prompts");
+    }
+    return path.join(home, ".claude", "commands");
+}
+function slashCommandForBuiltInSkill(skillName) {
+    if (skillName === "visual-plan") {
+        return `---
+description: Create an interactive Agent-Native visual plan for the current task.
+argument-hint: [optional request or scope]
+---
+
+Use the visual-plan skill for this task. Treat any arguments as the user's
+requested plan scope or focus:
+
+$ARGUMENTS
+`;
+    }
+    if (skillName === "visual-recap") {
+        return `---
+description: Create an interactive Agent-Native visual recap for a PR, branch, commit, or diff.
+argument-hint: [PR, branch, commit, diff, or scope]
+---
+
+Use the visual-recap skill. Treat any arguments as the recap target or focus:
+
+$ARGUMENTS
+`;
+    }
+    return null;
+}
 /**
  * Write a built-in skill's instruction folders straight into each client's
  * skills directory. Built-in skills ship their SKILL.md inside this package, so
@@ -2445,11 +2537,21 @@ function installBuiltInInstructions(input) {
     const written = [];
     for (const agent of input.skillsAgents) {
         const root = builtInSkillsRootForAgent(agent, input.scope, input.baseDir);
+        const commandsRoot = builtInCommandsRootForAgent(agent, input.scope, input.baseDir);
         for (const bundle of bundles) {
             const dir = path.join(root, bundle.skillName);
             if (!input.dryRun)
                 writeSkillFolder(dir, bundle);
             written.push(dir);
+            const command = slashCommandForBuiltInSkill(bundle.skillName);
+            if (command) {
+                const commandPath = path.join(commandsRoot, `${bundle.skillName}.md`);
+                if (!input.dryRun) {
+                    fs.mkdirSync(path.dirname(commandPath), { recursive: true });
+                    fs.writeFileSync(commandPath, command, "utf-8");
+                }
+                written.push(commandPath);
+            }
         }
     }
     return written;
@@ -2508,6 +2610,10 @@ function skillSearchRoots(input) {
         if (hasClient("claude-code") || hasClient("claude-code-cli")) {
             add(path.join(input.baseDir, ".claude", "skills"), "project", "claude-code");
         }
+        if (hasClient("pi")) {
+            add(path.join(input.baseDir, ".agents", "skills"), "project", "pi");
+            add(path.join(input.baseDir, ".pi", "skills"), "project", "pi");
+        }
         if (includeAll)
             add(path.join(input.baseDir, "skills"), "project", "repo");
     }
@@ -2522,6 +2628,12 @@ function skillSearchRoots(input) {
         if (hasClient("claude-code") || hasClient("claude-code-cli")) {
             add(home ? path.join(home, ".claude", "skills") : undefined, "user", "claude-code");
         }
+        if (hasClient("pi")) {
+            const piHome = process.env.PI_CODING_AGENT_DIR ||
+                (home ? path.join(home, ".pi", "agent") : undefined);
+            add(home ? path.join(home, ".agents", "skills") : undefined, "user", "pi");
+            add(piHome ? path.join(piHome, "skills") : undefined, "user", "pi");
+        }
     }
     const seen = new Set();
     return roots.filter((entry) => {
@@ -2551,7 +2663,7 @@ function scopeFilterForStatus(parsed) {
         : ["project", "user"];
 }
 function clientFilterForStatus(parsed) {
-    return parsed.clientExplicit ? resolveClients(parsed.client) : [];
+    return parsed.clientExplicit ? resolveSkillsClientArg(parsed.client) : [];
 }
 function collectSkillInstallStates(parsed, options) {
     const appSkillIds = targetIdsForStatus(parsed);
@@ -2640,11 +2752,28 @@ function normalizeClientIds(values) {
     }
     return out;
 }
-function normalizeSkillsClientIds(values) {
+function isMcpClientId(value) {
+    return CLIENTS.includes(value);
+}
+function normalizeSkillInstructionClientIds(values) {
+    if (!Array.isArray(values))
+        return [];
     const seen = new Set();
     const out = [];
-    for (const client of normalizeClientIds(values)) {
-        const normalized = client === "claude-code-cli" ? "claude-code" : client;
+    for (const value of values) {
+        if (typeof value !== "string")
+            continue;
+        const id = value.toLowerCase();
+        let normalized = null;
+        if (id === "pi") {
+            normalized = "pi";
+        }
+        else if (CLIENTS.includes(id)) {
+            const client = id;
+            normalized = client === "claude-code-cli" ? "claude-code" : client;
+        }
+        if (!normalized)
+            continue;
         if (seen.has(normalized))
             continue;
         seen.add(normalized);
@@ -2652,22 +2781,37 @@ function normalizeSkillsClientIds(values) {
     }
     return out;
 }
-function resolveSkillsClientArg(client) {
-    return normalizeSkillsClientIds(resolveClients(client));
+function resolveSkillsClientArg(client, installsMcp = false) {
+    if (installsMcp)
+        return normalizeSkillInstructionClientIds(resolveClients(client));
+    const values = client.split(",").flatMap((raw) => {
+        const id = raw.trim().toLowerCase();
+        if (!id)
+            return [];
+        if (id === "all")
+            return SKILL_INSTRUCTION_CLIENTS;
+        if (id === "pi")
+            return ["pi"];
+        return resolveClients(id);
+    });
+    return normalizeSkillInstructionClientIds(values);
 }
 function skillsClients(installsMcp) {
     return installsMcp ? SKILLS_CLIENTS : SKILL_INSTRUCTION_CLIENTS;
 }
 function filterSkillsClients(clients, installsMcp) {
-    if (installsMcp)
-        return clients;
+    if (installsMcp) {
+        return clients.filter((client) => isMcpClientId(client) && SKILLS_CLIENTS.includes(client));
+    }
     return clients.filter((client) => SKILL_INSTRUCTION_CLIENTS.includes(client));
 }
 function clientPromptOptions(installsMcp) {
     return skillsClients(installsMcp).map((client) => ({
         value: client,
-        label: CLIENT_LABELS[client],
-        hint: installsMcp
+        label: installsMcp && isMcpClientId(client)
+            ? CLIENT_LABELS[client]
+            : SKILL_INSTRUCTION_CLIENT_LABELS[client],
+        hint: installsMcp && isMcpClientId(client)
             ? CLIENT_HINTS[client]
             : SKILL_INSTRUCTION_CLIENT_HINTS[client],
     }));
@@ -2675,16 +2819,6 @@ function clientPromptOptions(installsMcp) {
 const DEFAULT_PUBLIC_SKILLS_SOURCE = "BuilderIO/skills";
 const PUBLIC_SKILL_TARGET_PREFIX = "public-skills:";
 const BUILT_IN_SKILL_PROMPT_OPTIONS = [
-    {
-        value: "assets",
-        label: "assets",
-        hint: BUILT_IN_APP_SKILLS.assets.manifest.description,
-    },
-    {
-        value: "design-exploration",
-        label: "design-exploration",
-        hint: BUILT_IN_APP_SKILLS.design.manifest.description,
-    },
     {
         value: "visual-plan",
         label: "visual-plan",
@@ -2695,6 +2829,16 @@ const BUILT_IN_SKILL_PROMPT_OPTIONS = [
         label: "visual-recap",
         hint: "Interactive visual recap that maps PRs/diffs with diagrams, annotated diffs, API/schema summaries, and review notes.",
     },
+    {
+        value: "assets",
+        label: "assets",
+        hint: BUILT_IN_APP_SKILLS.assets.manifest.description,
+    },
+    {
+        value: "design-exploration",
+        label: "design-exploration",
+        hint: BUILT_IN_APP_SKILLS.design.manifest.description,
+    },
     {
         value: "context-xray",
         label: "context-xray",
@@ -2702,6 +2846,13 @@ const BUILT_IN_SKILL_PROMPT_OPTIONS = [
     },
 ];
 const DEFAULT_SKILL_PROMPT_TARGETS = ["visual-plan", "visual-recap"];
+function hiddenBuiltInSkillTargets(options) {
+    return new Set((options.hiddenBuiltInSkillTargets ?? []).map((target) => target.trim().toLowerCase()));
+}
+function builtInSkillPromptOptions(options) {
+    const hidden = hiddenBuiltInSkillTargets(options);
+    return BUILT_IN_SKILL_PROMPT_OPTIONS.filter((entry) => !hidden.has(entry.value));
+}
 function publicSkillEntries(options) {
     if (options.catalogMode !== "all")
         return [];
@@ -2732,15 +2883,13 @@ function publicSkillPromptOptions(options) {
 }
 function skillPromptOptions(options = {}) {
     return [
-        ...BUILT_IN_SKILL_PROMPT_OPTIONS,
+        ...builtInSkillPromptOptions(options),
         ...publicSkillPromptOptions(options),
     ];
 }
 function defaultSkillPromptTargets(options) {
-    return [
-        ...DEFAULT_SKILL_PROMPT_TARGETS,
-        ...publicSkillEntries(options).map((entry) => entry.name),
-    ];
+    const available = new Set(skillPromptOptions(options).map((entry) => entry.value));
+    return DEFAULT_SKILL_PROMPT_TARGETS.filter((target) => available.has(target));
 }
 function publicSkillSelectionTarget(skillNames) {
     return `${PUBLIC_SKILL_TARGET_PREFIX}${skillNames.join(",")}`;
@@ -2760,6 +2909,7 @@ function prVisualRecapWorkflowPath(baseDir) {
 function prVisualRecapWorkflowDisplayPath() {
     return path.join(".github", "workflows", "pr-visual-recap.yml");
 }
+const PR_VISUAL_RECAP_DOCS_URL = "https://www.agent-native.com/docs/pr-visual-recap";
 function prVisualRecapInstallCommand() {
     return "npx @agent-native/core@latest skills add visual-recap --with-github-action";
 }
@@ -2773,6 +2923,7 @@ async function promptForGithubAction(context) {
             "  Posts a human-friendly recap on every pull request — a high-altitude\n" +
             "  overview of what the PR does, with annotated code, diagrams, and\n" +
             "  before/after notes instead of a raw diff.\n" +
+            `  Learn more: ${PR_VISUAL_RECAP_DOCS_URL}\n` +
             `  Writes ${context.workflowPath}; ${context.setupCommand} finishes the GitHub secrets.`,
         initialValue: false,
     });
@@ -2796,9 +2947,9 @@ function shouldPrompt(parsed, options) {
 async function promptForClients(context) {
     const clack = await import("@clack/prompts");
     const message = context.installsMcp
-        ? "Install the MCP connector and skills for which local agents?\n" +
+        ? "Install the MCP connector for which clients?\n" +
             "  (space toggles, enter confirms; saved for next time)"
-        : "Install skill instructions for which local agents?\n" +
+        : "Where should the skill instructions be written?\n" +
             "  (space toggles, enter confirms; saved for next time)";
     const result = await clack.multiselect({
         message,
@@ -2810,7 +2961,7 @@ async function promptForClients(context) {
         clack.cancel("Cancelled.");
         return null;
     }
-    return normalizeClientIds(result);
+    return normalizeSkillInstructionClientIds(result);
 }
 async function promptForScope(context) {
     const clack = await import("@clack/prompts");
@@ -2843,13 +2994,13 @@ async function promptForPlanMode(context) {
         options: [
             {
                 value: "hosted",
-                label: "Hosted Plans, shareable links",
+                label: "Hosted Plans, shareable links (recommended)",
                 hint: "100% free and open source. Stores plans at plan.agent-native.com with sharing, comments, and browser editor. Requires one-time browser sign-in.",
             },
             {
                 value: "local-files",
                 label: "Local files only",
-                hint: "Writes plans/<name>/plan.mdx in this repo and opens a local preview. No sharing, all local.",
+                hint: "Writes local MDX, starts a localhost bridge, and opens the hosted Plan UI. No sharing, all local.",
             },
             {
                 value: "self-hosted",
@@ -2917,15 +3068,17 @@ async function promptForSkills(context) {
 }
 async function resolveSkillsClients(parsed, options, installsMcp) {
     if (parsed.clientExplicit || !shouldPrompt(parsed, options)) {
-        const clients = filterSkillsClients(resolveSkillsClientArg(parsed.client), installsMcp);
+        const clients = filterSkillsClients(resolveSkillsClientArg(parsed.client, installsMcp), installsMcp);
         if (clients.length === 0) {
-            throw new Error("Local-file skill instructions only support Codex or Claude Code clients.");
+            throw new Error(installsMcp
+                ? "MCP setup supports Claude Code, Codex, Claude Cowork, Cursor, OpenCode, or GitHub Copilot / VS Code clients. Use --mode local-files or --no-mcp for Pi."
+                : "Skill instructions use shared .agents for Codex, Pi, Cursor, OpenCode, Copilot, and similar agents, or Claude Code's native files.");
         }
         return clients;
     }
     const initialClients = skillsClients(installsMcp);
     const prompt = options.promptClients ?? promptForClients;
-    const selected = normalizeSkillsClientIds(await prompt({
+    const selected = normalizeSkillInstructionClientIds(await prompt({
         initialClients,
         options: clientPromptOptions(installsMcp),
         installsMcp,
@@ -2934,7 +3087,7 @@ async function resolveSkillsClients(parsed, options, installsMcp) {
         return null;
     if (!parsed.dryRun) {
         try {
-            writeConnectClientPreferences(selected);
+            writeConnectClientPreferences(selected.filter(isMcpClientId));
         }
         catch { }
     }
@@ -3225,6 +3378,8 @@ function skillsAgentsForClients(clients) {
         if (client === "claude-code" || client === "claude-code-cli") {
             agents.add("claude-code");
         }
+        if (client === "pi")
+            agents.add("pi");
     }
     return [...agents];
 }
@@ -3237,7 +3392,7 @@ function commandString(cmd, args) {
     return [cmd, ...args].map(shellArg).join(" ");
 }
 function clientArgForClients(clients) {
-    if (clients.length === CLIENTS.length)
+    if (clients.length === CLIENTS.length && clients.every(isMcpClientId))
         return "all";
     if (clients.length === 1)
         return clients[0];
@@ -3272,7 +3427,8 @@ function preserveMcpUrlAppPathOverride(target, input) {
     };
 }
 function dryRunInstallCommand(parsed, target) {
-    const clients = parsed.clients ?? resolveSkillsClientArg(parsed.client);
+    const clients = parsed.clients ??
+        resolveSkillsClientArg(parsed.client, targetInstallsMcp(target, parsed));
     const args = [
         "@agent-native/core@latest",
         "skills",
@@ -3410,6 +3566,7 @@ function agentNativeSkillsInstallArgs(parsed, target, clients, baseDir) {
         "--yes",
         "@agent-native/skills@latest",
         "add",
+        "--quiet",
         "--copy",
         target,
         "--client",
@@ -3457,12 +3614,12 @@ async function addPlainSkillRepo(parsed, options) {
     const skillsAgents = skillsAgentsForClients(clients);
     const selectedSkillNames = parsed.plainSkillNames ?? [];
     if (skillsAgents.length === 0) {
-        throw new Error("Plain skill repositories can only install instructions for Codex or Claude Code clients.");
+        throw new Error("Plain skill repositories install through shared .agents for Codex, Pi, Cursor, OpenCode, Copilot, and similar agents, or Claude Code's native files.");
     }
-    const args = agentNativeSkillsInstallArgs(parsed, target, clients, options.baseDir);
+    const args = agentNativeSkillsInstallArgs(parsed, target, skillsAgents, options.baseDir);
     if (!parsed.dryRun) {
         const code = await (options.runCommand ?? runCommand)("npx", args, {
-            stdio: parsed.yes ? "silent" : "inherit",
+            stdio: "silent",
         });
         if (code !== 0)
             throw new Error(`npx @agent-native/skills@latest add exited with ${code}.`);
@@ -3622,7 +3779,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
         if (!parsed.instructions && parsed.mcp) {
             throw new Error("Context X-Ray does not need MCP config yet. Run without --mcp-only.");
         }
-        const clients = parsed.clients ?? resolveSkillsClientArg(parsed.client);
+        const clients = (parsed.clients ?? resolveSkillsClientArg(parsed.client)).filter(isMcpClientId);
         const skillsAgents = skillsAgentsForClients(clients);
         if (parsed.dryRun) {
             const githubActionPath = parsed.withGithubAction && knownTarget === "visual-plans"
@@ -3677,7 +3834,11 @@ export async function addAgentNativeSkill(parsed, options = {}) {
     if (parsed.mcpUrl) {
         installTarget = withMcpUrlOverride(installTarget, parsed.mcpUrl);
     }
-    const clients = parsed.clients ?? resolveSkillsClientArg(parsed.client);
+    const clients = parsed.clients ?? resolveSkillsClientArg(parsed.client, shouldRegisterMcp);
+    const mcpClients = clients.filter(isMcpClientId);
+    if (shouldRegisterMcp && mcpClients.length === 0) {
+        throw new Error("MCP setup supports Claude Code, Codex, Claude Cowork, Cursor, OpenCode, or GitHub Copilot / VS Code clients. Use --mode local-files or --no-mcp for Pi.");
+    }
     installTarget = preserveMcpUrlAppPathOverride(installTarget, parsed.mcpUrl);
     const skillsAgents = skillsAgentsForClients(clients);
     if (parsed.dryRun) {
@@ -3702,7 +3863,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
                 mcpUrl: knownTarget === "visual-plans" && planMode === "local-files"
                     ? ""
                     : installTarget.loaded.manifest.hosted.mcpUrl,
-                mcpClients: shouldRegisterMcp ? clients : [],
+                mcpClients: shouldRegisterMcp ? mcpClients : [],
                 dryRun: true,
                 commands: [dryRunInstallCommand(parsed, target)],
                 githubActionPath,
@@ -3720,12 +3881,12 @@ export async function addAgentNativeSkill(parsed, options = {}) {
     let instructionsWritten;
     let connected = false;
     let connectCommand;
-    let registeredMcpClients = shouldRegisterMcp ? clients : [];
+    let registeredMcpClients = shouldRegisterMcp ? mcpClients : [];
     try {
         if (parsed.instructions) {
             if (skillsAgents.length === 0) {
                 if (!shouldRegisterMcp) {
-                    throw new Error("Skill instructions can only be installed for Codex or Claude Code clients. Use an MCP-capable client or omit --instructions-only.");
+                    throw new Error("Skill instructions use shared .agents for Codex, Pi, Cursor, OpenCode, Copilot, and similar agents, or Claude Code's native files. Use an MCP-capable client or omit --instructions-only.");
                 }
             }
             else if (knownTarget) {
@@ -3755,6 +3916,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
                     "--yes",
                     "@agent-native/skills@latest",
                     "add",
+                    "--quiet",
                     instructionSource,
                     "--copy",
                     ...installTarget.skillNames.flatMap((skill) => ["--skill", skill]),
@@ -3784,7 +3946,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
             commands.push(`npx @agent-native/core@latest app-skill ensure --manifest ${installTarget.loaded.file} --client ${parsed.client} --scope ${parsed.scope} --yes`);
             if (!parsed.dryRun) {
                 const ensureResult = await ensureAppSkill(installTarget.loaded, {
-                    clients,
+                    clients: mcpClients,
                     scope: parsed.scope,
                     baseDir: options.baseDir,
                     yes: parsed.yes || Boolean(knownTarget),
@@ -3800,16 +3962,16 @@ export async function addAgentNativeSkill(parsed, options = {}) {
                 // does not hit an OAuth wall on the first tool call. `--no-connect`
                 // opts out; non-interactive shells get the exact command to run.
                 if (parsed.connect) {
-                    const result = await connectAfterEnsure(installTarget, clients, parsed, options);
+                    const result = await connectAfterEnsure(installTarget, mcpClients, parsed, options);
                     connected = result.connected;
                     connectCommand = result.connectCommand || undefined;
                     if (connected)
-                        registeredMcpClients = clients;
+                        registeredMcpClients = mcpClients;
                     if (connectCommand)
                         commands.push(connectCommand);
                 }
                 else {
-                    const pendingClients = clients.filter((client) => !registeredMcpClients.includes(client));
+                    const pendingClients = mcpClients.filter((client) => !registeredMcpClients.includes(client));
                     if (pendingClients.length > 0) {
                         connectCommand = connectCommandFor(installTarget.loaded.manifest.hosted.url, pendingClients, parsed.scope);
                         commands.push(connectCommand);
@@ -3835,6 +3997,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
                 const choice = await prompt({
                     workflowPath: prVisualRecapWorkflowDisplayPath(),
                     setupCommand: prVisualRecapSetupCommand(),
+                    docsUrl: PR_VISUAL_RECAP_DOCS_URL,
                 });
                 if (choice === null) {
                     options.telemetry?.track("skills_cli cancelled", {
@@ -3892,8 +4055,11 @@ export async function addAgentNativeSkill(parsed, options = {}) {
     }
 }
 function listSkills(options = {}) {
+    const hidden = hiddenBuiltInSkillTargets(options);
     return [
-        ...Object.values(BUILT_IN_APP_SKILLS).map((entry) => ({
+        ...Object.values(BUILT_IN_APP_SKILLS)
+            .filter((entry) => !hidden.has(entry.skillName))
+            .map((entry) => ({
             id: entry.manifest.id,
             aliases: BUILT_IN_APP_SKILL_DISPLAY_ALIASES[entry.manifest.id] ?? [],
             name: entry.manifest.displayName,
@@ -3946,6 +4112,15 @@ function planModeSummary(mode) {
         return "Self-hosted/custom Plan app";
     return "Hosted Plans - shareable links and comments";
 }
+function skillInstructionAgentLabel(agent) {
+    if (agent === "codex")
+        return SKILL_INSTRUCTION_CLIENT_LABELS.codex;
+    if (agent === "claude-code")
+        return SKILL_INSTRUCTION_CLIENT_LABELS["claude-code"];
+    if (agent === "pi")
+        return SKILL_INSTRUCTION_CLIENT_LABELS.pi;
+    return agent;
+}
 function targetInstallsMcp(target, parsed) {
     if (!parsed.mcp)
         return false;
@@ -4223,6 +4398,7 @@ export async function runSkills(argv, options = {}) {
             const choice = await prompt({
                 workflowPath: prVisualRecapWorkflowDisplayPath(),
                 setupCommand: prVisualRecapSetupCommand(),
+                docsUrl: PR_VISUAL_RECAP_DOCS_URL,
             });
             if (choice === null) {
                 telemetry.track("skills_cli cancelled", { step: "github-action" });
@@ -4278,7 +4454,7 @@ export async function runSkills(argv, options = {}) {
         ];
         const localCommands = [
             ...new Set(results
-                .filter((result) => result.local)
+                .filter((result) => result.local && result.scriptPath)
                 .flatMap((result) => result.commands)),
         ];
         const planModes = [
@@ -4316,10 +4492,10 @@ export async function runSkills(argv, options = {}) {
         const clack = await import("@clack/prompts");
         const summary = [
             skillsAgents.length
-                ? `Skill instructions   ${skillsAgents.join(", ")}`
+                ? `Skill instructions   ${skillsAgents.map(skillInstructionAgentLabel).join(", ")}`
                 : "Skill instructions   skipped",
             mcpClients.length
-                ? `MCP config           ${mcpClients.join(", ")}`
+                ? `MCP config           ${mcpClients.map((client) => CLIENT_LABELS[client]).join(", ")}`
                 : "MCP config           not required",
             mcpUrls.length ? `MCP URL              ${mcpUrls.join(", ")}` : "",
             planModes.length