@agent-native/core 0.51.7 → 0.51.9

package/dist/cli/skills.js

@@ -21,7 +21,7 @@ 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] [--mcp-url <url>] [--no-connect] [--with-github-action] [--yes] [--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 add <manifest-or-app-dir|skill-repo> [--skill <name>] [--client ...] [--yes]
 
 Examples:
@@ -30,6 +30,8 @@ Examples:
   npx @agent-native/core@latest skills add visual-plan
   npx @agent-native/core@latest skills add visual-recap
   npx @agent-native/core@latest skills add visual-recap --with-github-action
+  npx @agent-native/core@latest skills add visual-plan --mode local-files
+  npx @agent-native/core@latest skills add visual-plan --mode self-hosted --mcp-url https://my-plan-app.example.com
   npx @agent-native/core@latest skills status visual-plan
   npx @agent-native/core@latest skills update visual-plan
   npx @agent-native/core@latest skills add visual-plan --no-connect
@@ -59,6 +61,13 @@ deployment) instead of the built-in hosted default — a bare origin gets the
 standard /_agent-native/mcp path appended. Use app-skill pack for marketplace
 bundles and custom adapter output.
 
+When installing visual-plan or visual-recap interactively, the CLI asks where
+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.
+
 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
@@ -252,6 +261,22 @@ the connector without authenticating, then run
 whenever you are ready, or choose a narrower \`--client\`. Auth and MCP tool
 loading are per client config/session.
 
+**Local-only / text installs.** If the user wants no sharing and all local files,
+install with \`--mode local-files\`:
+
+\`\`\`bash
+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
+install/reconnect step above.
+
 **Browser (people you share with).** Open the Plans editor and create & edit
 with no sign-up — you work as a guest. Sign in only when you want to save or
 share; signing in claims the plans you made as a guest into your account.
@@ -259,9 +284,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, run the Plans app locally and sync plans to
-your repo as MDX. This local mode is a separate advanced path, not the default
-hosted flow.
+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\`.
 
 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
@@ -1291,11 +1317,20 @@ 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
 infrastructure. In this mode the plan data must never be sent to the Plan MCP
-server or Plan app action surface.
+server or Plan app action surface. Schema-only block catalog lookup is allowed
+because it sends no plan content: use the MCP \`get-plan-blocks\` tool if it is
+already available, or run
+\`npx @agent-native/core@latest plan blocks --out plan-blocks.md\` and read that
+file before authoring MDX.
 
 The local-files contract is:
 
 - Read source context from local files and shell commands only.
+- Fetch/read the block catalog before writing structured MDX. The
+  \`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\`.
@@ -1306,7 +1341,8 @@ The local-files contract is:
 - 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.
+  \`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
   comments, sharing, history, and publish/export receipts are unavailable until
@@ -1437,6 +1473,12 @@ In local-files mode:
   The existing \`npx @agent-native/core@latest recap collect-diff\`, \`scan\`, and
   \`build-prompt --local-files\` helpers are safe to use because they operate on
   local files and do not write to the Plan database.
+- Fetch/read the block catalog before writing structured MDX. Use
+  \`npx @agent-native/core@latest plan blocks --out plan-blocks.md\` when the Plan
+  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
@@ -1448,7 +1490,8 @@ In local-files mode:
 - 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.
+  \`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.
   Hosted comments, sharing, screenshots, usage attachment, and PR sticky comment
@@ -1811,12 +1854,19 @@ memorized tags — they drift and silently produce a wrong tag (\`ApiEndpoint\`
 instead of \`Endpoint\`, \`JsonExplorer\` instead of \`Json\`, \`Tabs\` instead of
 \`TabsBlock\`) that errors on import.
 
-**Before writing any structured plan content, call \`get-plan-blocks\` on the Plan
-MCP connector (\`plan\` or legacy \`agent-native-plans\`).** It returns the
-authoritative, always-current block
-vocabulary generated live from the app's own block registry — the same config
-the renderer and MDX round-trip use — so it can never be stale even if this
-SKILL.md is an old installed copy:
+**Before writing any structured plan content, fetch/read the block catalog.** In
+hosted or self-hosted mode, call \`get-plan-blocks\` on the Plan MCP connector
+(\`plan\` or legacy \`agent-native-plans\`). In local-files mode, or when the skill
+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\`.
+
+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
+round-trip use — so it can never be stale even if this SKILL.md is an old
+installed copy:
 
 - \`get-plan-blocks\` (default \`format: "reference"\`) → a compact table of every
   block's runtime \`type\`, exact MDX \`<Tag>\`, placement, and key data fields.
@@ -2244,12 +2294,62 @@ function stableSkillHash(files) {
     }
     return hash.digest("hex").slice(0, 16);
 }
-function skillFilesForBuiltIn(appSkillId) {
+function insertAfterFrontmatter(markdown, block) {
+    if (!block.trim())
+        return markdown;
+    const match = markdown.match(/^---\n[\s\S]*?\n---\n/);
+    if (!match)
+        return `${block}\n\n${markdown}`;
+    return `${match[0]}\n${block.trim()}\n\n${markdown.slice(match[0].length)}`;
+}
+function planModeInstructionBlock(input) {
+    if (input.mode === "local-files") {
+        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\`,
+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.`;
+    }
+    if (input.mode === "self-hosted") {
+        return `## Installed Mode
+
+Default storage for this installation: the configured self-hosted/custom Plan
+app${input.mcpUrl ? ` at \`${input.mcpUrl}\`` : ""}. Use that Plan MCP connector
+for plans and recaps instead of assuming \`https://plan.agent-native.com\`.`;
+    }
+    return "";
+}
+function applyPlanModeToSkillMarkdown(markdown, input) {
+    if (input.appSkillId !== "visual-plans")
+        return markdown;
+    const block = planModeInstructionBlock({
+        mode: input.mode,
+        mcpUrl: input.mcpUrl,
+    });
+    return insertAfterFrontmatter(markdown, block);
+}
+function skillFilesForBuiltIn(appSkillId, options = {}) {
     const entry = BUILT_IN_APP_SKILLS[appSkillId];
     const skills = {
-        [entry.skillName]: entry.skillMarkdown,
+        [entry.skillName]: applyPlanModeToSkillMarkdown(entry.skillMarkdown, {
+            appSkillId,
+            mode: options.planMode,
+            mcpUrl: options.mcpUrl,
+        }),
         ...builtInExtraSkills(entry),
     };
+    for (const [skillName, skillMarkdown] of Object.entries(builtInExtraSkills(entry))) {
+        skills[skillName] = applyPlanModeToSkillMarkdown(skillMarkdown, {
+            appSkillId,
+            mode: options.planMode,
+            mcpUrl: options.mcpUrl,
+        });
+    }
     const extraFiles = builtInExtraFiles(entry);
     const out = {};
     for (const [skillName, skillMarkdown] of Object.entries(skills)) {
@@ -2261,11 +2361,12 @@ function skillFilesForBuiltIn(appSkillId) {
             appSkillId,
             displayName: entry.manifest.displayName,
             skillName,
-            mcpUrl: isLocalOnlyBuiltInSkill(entry)
+            mcpUrl: isLocalOnlyBuiltInSkill(entry) || options.planMode === "local-files"
                 ? ""
-                : entry.manifest.hosted.mcpUrl,
+                : (options.mcpUrl ?? entry.manifest.hosted.mcpUrl),
             files,
             contentHash: stableSkillHash(files),
+            planMode: options.planMode,
         };
     }
     return out;
@@ -2295,6 +2396,7 @@ function writeSkillFolder(dir, bundle, installedAt = new Date().toISOString()) {
         mcpUrl: bundle.mcpUrl,
         installedAt,
         updateCommand: `npx @agent-native/core@latest skills update ${bundle.skillName}`,
+        ...(bundle.planMode ? { planMode: bundle.planMode } : {}),
     };
     fs.writeFileSync(path.join(dir, AGENT_NATIVE_SKILL_METADATA_FILE), `${JSON.stringify(metadata, null, 2)}\n`, "utf-8");
 }
@@ -2324,7 +2426,10 @@ function builtInSkillsRootForAgent(agent, scope, baseDir) {
  * (which would have to be published to npm first). Returns the written folders.
  */
 function installBuiltInInstructions(input) {
-    const bundles = Object.values(skillFilesForBuiltIn(input.appSkillId)).filter((bundle) => !input.onlySkillNames || input.onlySkillNames.includes(bundle.skillName));
+    const bundles = Object.values(skillFilesForBuiltIn(input.appSkillId, {
+        planMode: input.planMode,
+        mcpUrl: input.mcpUrl,
+    })).filter((bundle) => !input.onlySkillNames || input.onlySkillNames.includes(bundle.skillName));
     const written = [];
     for (const agent of input.skillsAgents) {
         const root = builtInSkillsRootForAgent(agent, input.scope, input.baseDir);
@@ -2438,7 +2543,7 @@ function clientFilterForStatus(parsed) {
 }
 function collectSkillInstallStates(parsed, options) {
     const appSkillIds = targetIdsForStatus(parsed);
-    const latest = latestSkillBundlesForTargets(appSkillIds);
+    const defaultLatest = latestSkillBundlesForTargets(appSkillIds);
     const roots = skillSearchRoots({
         baseDir: options.baseDir ?? process.cwd(),
         clients: clientFilterForStatus(parsed),
@@ -2447,7 +2552,7 @@ function collectSkillInstallStates(parsed, options) {
     const states = [];
     const seenDirs = new Set();
     for (const root of roots) {
-        for (const bundle of Object.values(latest)) {
+        for (const bundle of Object.values(defaultLatest)) {
             const dir = path.join(root.root, bundle.skillName);
             const resolvedDir = path.resolve(dir);
             if (seenDirs.has(resolvedDir) || !fs.existsSync(dir))
@@ -2456,35 +2561,41 @@ function collectSkillInstallStates(parsed, options) {
                 continue;
             seenDirs.add(resolvedDir);
             const files = listSkillFolderFiles(dir);
-            const installedHash = Object.keys(files).length > 0 ? stableSkillHash(files) : null;
             const metadata = readSkillInstallMetadata(dir);
+            const stateBundle = skillFilesForBuiltIn(bundle.appSkillId, {
+                planMode: metadata?.planMode,
+                mcpUrl: metadata?.mcpUrl,
+            })[bundle.skillName] ?? bundle;
+            const installedHash = Object.keys(files).length > 0 ? stableSkillHash(files) : null;
             states.push({
-                appSkillId: bundle.appSkillId,
-                displayName: bundle.displayName,
-                skillName: bundle.skillName,
+                appSkillId: stateBundle.appSkillId,
+                displayName: stateBundle.displayName,
+                skillName: stateBundle.skillName,
                 path: dir,
                 root: root.root,
                 scope: root.scope,
                 client: root.client,
-                latestHash: bundle.contentHash,
+                latestHash: stateBundle.contentHash,
                 installedHash,
                 metadataHash: metadata?.contentHash,
-                current: installedHash === bundle.contentHash,
+                current: installedHash === stateBundle.contentHash,
                 managed: metadata?.source === "agent-native",
+                planMode: metadata?.planMode,
+                mcpUrl: metadata?.mcpUrl,
             });
         }
     }
     return states.sort((a, b) => `${a.skillName}:${a.path}`.localeCompare(`${b.skillName}:${b.path}`));
 }
 function updateSkillInstallStates(states, dryRun) {
-    const latest = latestSkillBundlesForTargets([
-        ...new Set(states.map((state) => state.appSkillId)),
-    ]);
     const updated = [];
     for (const state of states) {
         if (state.current && state.managed)
             continue;
-        const bundle = latest[state.skillName];
+        const bundle = skillFilesForBuiltIn(state.appSkillId, {
+            planMode: state.planMode,
+            mcpUrl: state.mcpUrl,
+        })[state.skillName];
         if (!bundle)
             continue;
         if (!dryRun)
@@ -2622,6 +2733,56 @@ async function promptForScope(context) {
     }
     return result === "project" ? "project" : "user";
 }
+async function promptForPlanMode(context) {
+    const clack = await import("@clack/prompts");
+    const result = await clack.select({
+        message: "Where should visual plans and recaps live?",
+        options: [
+            {
+                value: "hosted",
+                label: "Hosted Plans, shareable links",
+                hint: "Stores plans at plan.agent-native.com. Enables sharing, comments, 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.",
+            },
+            {
+                value: "self-hosted",
+                label: "Self-hosted/custom URL",
+                hint: "Connect to your own Plan app or local dev tunnel.",
+            },
+        ],
+        initialValue: context.initialMode,
+    });
+    if (clack.isCancel(result)) {
+        clack.cancel("Cancelled.");
+        return null;
+    }
+    return normalizePlanInstallMode(String(result));
+}
+async function promptForPlanMcpUrl() {
+    const clack = await import("@clack/prompts");
+    const result = await clack.text({
+        message: "Plan app URL or MCP URL",
+        placeholder: "https://my-plan-app.example.com",
+        validate(value) {
+            try {
+                resolveMcpUrlOverride(value);
+                return undefined;
+            }
+            catch (err) {
+                return err?.message ?? "Enter a valid http:// or https:// URL.";
+            }
+        },
+    });
+    if (clack.isCancel(result)) {
+        clack.cancel("Cancelled.");
+        return null;
+    }
+    return String(result).trim();
+}
 async function promptForSkills(context) {
     const clack = await import("@clack/prompts");
     const result = await clack.multiselect({
@@ -2659,6 +2820,30 @@ async function resolveSkillsClients(parsed, options) {
     }
     return selected;
 }
+function normalizePlanInstallMode(value) {
+    const normalized = value?.trim().toLowerCase();
+    if (!normalized || normalized === "hosted")
+        return "hosted";
+    if (normalized === "local" ||
+        normalized === "local-file" ||
+        normalized === "local-files" ||
+        normalized === "files") {
+        return "local-files";
+    }
+    if (normalized === "self-hosted" ||
+        normalized === "selfhosted" ||
+        normalized === "custom" ||
+        normalized === "custom-url") {
+        return "self-hosted";
+    }
+    throw new Error('--mode must be one of "hosted", "local-files", or "self-hosted".');
+}
+function targetIncludesPlans(target) {
+    return normalizeKnownSkillTarget(target) === "visual-plans";
+}
+function targetsIncludePlans(targets) {
+    return targets.some(targetIncludesPlans);
+}
 async function resolveSkillTargets(parsed, options) {
     if (parsed.target || !shouldPrompt(parsed, options)) {
         return [parsed.target ?? "assets"];
@@ -2755,6 +2940,14 @@ export function parseSkillsArgs(argv) {
         }
         else if ((value = eat("--mcp-url")) !== undefined)
             out.mcpUrl = value;
+        else if ((value = eat("--mode")) !== undefined)
+            out.planMode = normalizePlanInstallMode(value);
+        else if (arg === "--hosted")
+            out.planMode = "hosted";
+        else if (arg === "--local" || arg === "--local-files")
+            out.planMode = "local-files";
+        else if (arg === "--self-hosted" || arg === "--custom-url")
+            out.planMode = "self-hosted";
         else if (arg === "--yes" || arg === "-y")
             out.yes = true;
         else if (arg === "--dry-run")
@@ -2785,6 +2978,9 @@ export function parseSkillsArgs(argv) {
     if (out.scope !== "user" && out.scope !== "project") {
         throw new Error("--scope must be either user or project.");
     }
+    if (out.planMode === "local-files" && out.mcpUrl) {
+        throw new Error("--mode local-files cannot be combined with --mcp-url.");
+    }
     return out;
 }
 function loadSkillTarget(target, onlySkillNames) {
@@ -2898,6 +3094,8 @@ function dryRunInstallCommand(parsed, target) {
         "--scope",
         parsed.scope,
     ];
+    if (parsed.planMode)
+        args.push("--mode", parsed.planMode);
     if (parsed.mcpUrl)
         args.push("--mcp-url", parsed.mcpUrl);
     if (parsed.instructions && !parsed.mcp)
@@ -3159,6 +3357,20 @@ async function connectAfterEnsure(installTarget, clients, parsed, options) {
 export async function addAgentNativeSkill(parsed, options = {}) {
     const target = parsed.target ?? "assets";
     const knownTarget = normalizeKnownSkillTarget(target);
+    const planMode = knownTarget === "visual-plans"
+        ? (parsed.planMode ?? (parsed.mcpUrl ? "self-hosted" : "hosted"))
+        : undefined;
+    if (parsed.planMode && knownTarget !== "visual-plans") {
+        throw new Error("--mode only applies to visual-plan / visual-recap.");
+    }
+    if (planMode === "local-files" && parsed.mcpUrl) {
+        throw new Error("--mode local-files cannot be combined with --mcp-url.");
+    }
+    if (planMode === "self-hosted" && !parsed.mcpUrl) {
+        throw new Error("--mode self-hosted requires --mcp-url <url>.");
+    }
+    const shouldRegisterMcp = parsed.mcp &&
+        !(knownTarget === "visual-plans" && planMode === "local-files");
     // For multi-skill bundles (the plan bundle), a single-skill target installs
     // only that skill. `installsRecap` controls the PR Visual Recap github-action
     // offer, which is only relevant when the recap skill is part of the install.
@@ -3258,12 +3470,15 @@ export async function addAgentNativeSkill(parsed, options = {}) {
                 displayName: installTarget.displayName,
                 skillNames: installTarget.skillNames,
                 skillsAgents,
-                mcpUrl: installTarget.loaded.manifest.hosted.mcpUrl,
-                mcpClients: clients,
+                mcpUrl: knownTarget === "visual-plans" && planMode === "local-files"
+                    ? ""
+                    : installTarget.loaded.manifest.hosted.mcpUrl,
+                mcpClients: shouldRegisterMcp ? clients : [],
                 dryRun: true,
                 commands: [dryRunInstallCommand(parsed, target)],
                 githubActionPath,
                 githubActionSuggestedCommand,
+                planMode,
             };
         }
         finally {
@@ -3279,7 +3494,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
     try {
         if (parsed.instructions) {
             if (skillsAgents.length === 0) {
-                if (!parsed.mcp) {
+                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.");
                 }
             }
@@ -3295,6 +3510,8 @@ export async function addAgentNativeSkill(parsed, options = {}) {
                     scope: parsed.scope,
                     baseDir: options.baseDir ?? process.cwd(),
                     dryRun: parsed.dryRun,
+                    planMode,
+                    mcpUrl: installTarget.loaded.manifest.hosted.mcpUrl,
                 });
                 instructionSource = instructionsWritten[0];
                 commands.push(...instructionsWritten.map((dir) => `write ${dir}`));
@@ -3333,7 +3550,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
             scope: parsed.scope,
             dryRun: Boolean(parsed.dryRun),
         });
-        if (parsed.mcp) {
+        if (shouldRegisterMcp) {
             commands.push(`npx @agent-native/core@latest app-skill ensure --manifest ${installTarget.loaded.file} --client ${parsed.client} --scope ${parsed.scope} --yes`);
             if (!parsed.dryRun) {
                 await ensureAppSkill(installTarget.loaded, {
@@ -3414,13 +3631,16 @@ export async function addAgentNativeSkill(parsed, options = {}) {
             instructionSource,
             skillNames: installTarget.skillNames,
             skillsAgents,
-            mcpUrl: installTarget.loaded.manifest.hosted.mcpUrl,
-            mcpClients: clients,
+            mcpUrl: knownTarget === "visual-plans" && planMode === "local-files"
+                ? ""
+                : installTarget.loaded.manifest.hosted.mcpUrl,
+            mcpClients: shouldRegisterMcp ? clients : [],
             dryRun: parsed.dryRun,
             commands,
             written: instructionsWritten,
             connected,
             connectCommand,
+            planMode,
             githubActionPath,
             githubActionExisted,
             githubActionSuggestedCommand,
@@ -3454,6 +3674,7 @@ function skillStateJson(state) {
         installedHash: state.installedHash,
         latestHash: state.latestHash,
         metadataHash: state.metadataHash,
+        planMode: state.planMode,
     };
 }
 function formatSkillState(state) {
@@ -3464,6 +3685,13 @@ function formatSkillState(state) {
         : "";
     return `${state.skillName.padEnd(22)} ${status.padEnd(7)} ${state.scope}/${state.client} ${managed}${hashes}\n  ${state.path}`;
 }
+function planModeSummary(mode) {
+    if (mode === "local-files")
+        return "Local files - No sharing, all local.";
+    if (mode === "self-hosted")
+        return "Self-hosted/custom Plan app";
+    return "Hosted Plans - shareable links and comments";
+}
 function runSkillsStatusOrUpdate(parsed, options, update) {
     const before = collectSkillInstallStates(parsed, options);
     const changed = update ? updateSkillInstallStates(before, parsed.dryRun) : [];
@@ -3586,6 +3814,45 @@ export async function runSkills(argv, options = {}) {
             selectedAll: targets.length === skillPromptOptions().length,
             preselected,
         });
+        const includesPlans = targetsIncludePlans(targets);
+        if (parsed.planMode && !includesPlans) {
+            throw new Error("--mode only applies to visual-plan / visual-recap.");
+        }
+        if (includesPlans) {
+            if (!parsed.planMode && parsed.mcpUrl) {
+                parsed.planMode = "self-hosted";
+            }
+            if (!parsed.planMode && shouldPrompt(parsed, options)) {
+                const prompt = options.promptPlanMode ?? promptForPlanMode;
+                const mode = await prompt({ initialMode: "hosted" });
+                if (!mode) {
+                    telemetry.track("skills_cli cancelled", { step: "plan-mode" });
+                    return;
+                }
+                parsed.planMode = mode;
+            }
+            if (!parsed.planMode)
+                parsed.planMode = "hosted";
+            if (parsed.planMode === "self-hosted" && !parsed.mcpUrl) {
+                if (shouldPrompt(parsed, options)) {
+                    const prompt = options.promptPlanMcpUrl ?? promptForPlanMcpUrl;
+                    const mcpUrl = await prompt();
+                    if (!mcpUrl) {
+                        telemetry.track("skills_cli cancelled", {
+                            step: "plan-mcp-url",
+                        });
+                        return;
+                    }
+                    parsed.mcpUrl = mcpUrl;
+                }
+                else {
+                    throw new Error("--mode self-hosted requires --mcp-url <url> in non-interactive mode.");
+                }
+            }
+            telemetry.track("skills_cli plan mode selected", {
+                mode: parsed.planMode,
+            });
+        }
         const clients = await resolveSkillsClients(parsed, optionsWithTelemetry);
         if (!clients) {
             telemetry.track("skills_cli cancelled", { step: "clients" });
@@ -3684,6 +3951,11 @@ export async function runSkills(argv, options = {}) {
                 .filter((result) => result.local)
                 .flatMap((result) => result.commands)),
         ];
+        const planModes = [
+            ...new Set(results
+                .map((result) => result.planMode)
+                .filter((mode) => Boolean(mode))),
+        ];
         const authConnected = results.some((result) => result.connected);
         const pendingConnectCommands = [
             ...new Set(results
@@ -3720,6 +3992,9 @@ export async function runSkills(argv, options = {}) {
                 ? `MCP config           ${mcpClients.join(", ")}`
                 : "MCP config           not required",
             mcpUrls.length ? `MCP URL              ${mcpUrls.join(", ")}` : "",
+            planModes.length
+                ? `Plan mode            ${planModes.map(planModeSummary).join(", ")}`
+                : "",
             authConnected
                 ? "Authentication       completed"
                 : pendingConnectCommands.length