@agent-native/core 0.66.6 → 0.66.8

package/dist/cli/skills.js

@@ -19,13 +19,14 @@ 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|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 status [assets|content|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|content|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|content|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:
   npx @agent-native/core@latest skills add assets
+  npx @agent-native/core@latest skills add content --mode local-files
   npx @agent-native/core@latest skills add design-exploration
   npx @agent-native/core@latest skills add visual-plan
   npx @agent-native/core@latest skills add visual-recap
@@ -71,6 +72,12 @@ 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 the localhost bridge viewer.
 
+When installing content with --mode local-files, the CLI installs Content
+instructions and writes or updates agent-native.json with repo-backed Markdown /
+MDX roots for docs, blog, content, and resources. Use a local Content app, Agent
+Native Desktop, or another trusted local bridge for Content actions to read and
+write those files.
+
 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
@@ -161,6 +168,115 @@ of using a generic image generator.
 - If you inspect local MCP config, redact \`Authorization\`, \`http_headers\`,
   and token values. Never paste bearer tokens into chat or logs.
 `;
+const CONTENT_SKILL_MD = `---
+name: content
+description: >-
+  Use Content for repo-backed Markdown/MDX docs, blogs, resources, rich
+  document editing, local components, shareable copies, and Content local-file
+  workspaces. Prefer Content actions over raw filesystem writes when available.
+metadata:
+  visibility: exported
+---
+
+# Content
+
+Use the Content app when a workflow is about authoring, editing, reviewing, or
+publishing Markdown/MDX documents: docs sites, blogs, resource libraries,
+marketing pages, internal notes, and local MDX components. Content gives the
+agent a document tree, a rich editor, normal document actions, and optional
+local-file source of truth.
+
+## Choose The Path
+
+- Use Content actions when the Content MCP/action tools are available:
+  \`list-documents\`, \`search-documents\`, \`get-document\`,
+  \`pull-document\`, \`create-document\`, \`edit-document\`,
+  \`update-document\`, \`delete-document\`, \`share-local-file-document\`,
+  \`list-local-component-files\`, and \`write-local-component-file\`.
+- Use \`pull-document\` or \`get-document\` before editing a page. Use
+  \`edit-document\` for precise find/replace changes and \`update-document\`
+  for full rewrites or new content.
+- In Local File Mode, Content actions read and write the repo files declared in
+  \`agent-native.json\`; SQL remains cache/history/search glue, not the source of
+  truth for those pages.
+- If Content tools are not visible and no local Content app or Desktop bridge is
+  running, treat this skill as repo-editing guidance. Edit configured
+  \`.md\`/\`.mdx\` files directly, preserve frontmatter and MDX imports, and tell
+  the user the Content action surface was not available.
+
+## Action Examples
+
+Prefer JSON input for action calls:
+
+\`\`\`bash
+pnpm action list-documents
+pnpm action get-document '{"id":"local-file:..."}'
+pnpm action edit-document '{"id":"local-file:...","find":"old copy","replace":"new copy"}'
+pnpm action update-document '{"id":"local-file:...","content":"# Updated\\n\\nBody"}'
+pnpm action share-local-file-document '{"id":"local-file:..."}'
+\`\`\`
+
+Run \`refresh-list\` after create/update/delete operations when you need the
+open Content UI sidebar to repaint immediately.
+
+## Local File Mode
+
+Install into an existing repo with:
+
+\`\`\`bash
+npx @agent-native/core@latest skills add content --mode local-files --scope project
+\`\`\`
+
+The installer copies this skill and writes or updates \`agent-native.json\` with
+Content roots for \`docs/\`, \`blog/\`, \`content/\`, and \`resources/\`, plus a
+\`components/\` folder for local MDX components. A typical manifest looks like:
+
+\`\`\`json
+{
+  "version": 1,
+  "apps": {
+    "content": {
+      "mode": "local-files",
+      "roots": [
+        { "name": "Docs", "path": "docs", "kind": "docs", "extensions": [".md", ".mdx"] },
+        { "name": "Blog", "path": "blog", "kind": "blog", "extensions": [".md", ".mdx"] },
+        { "name": "Content", "path": "content", "kind": "content", "extensions": [".md", ".mdx"] },
+        { "name": "Resources", "path": "resources", "kind": "resources", "extensions": [".md", ".mdx"] }
+      ],
+      "components": "components",
+      "extensions": "extensions",
+      "hide": ["**/_*.md", "**/_*.mdx"]
+    }
+  }
+}
+\`\`\`
+
+Local File Mode does not make the host language model local, and the hosted
+Content app cannot read private repo files by itself. File access requires a
+local Content app, Agent Native Desktop, or another trusted local bridge.
+
+## MDX And Components
+
+- Preserve frontmatter keys you do not understand. Preserve MDX imports,
+  exports, JSX, and expression props unless the user explicitly asks to change
+  them.
+- Use local components from the configured \`components\` folder. Components
+  should be PascalCase exports from \`.tsx\` files; simple editable input metadata
+  can live next to them as \`ComponentNameInputs\`.
+- Use \`list-local-component-files\` and \`write-local-component-file\` for
+  component source changes when Content tools are available. Otherwise edit the
+  component files directly like normal repo source.
+
+## Boundaries
+
+- Moving, renaming, and reordering local-file pages are not first-class Content
+  UI operations yet. Use normal file operations when the user asks for those,
+  then let Content rediscover the file tree.
+- Do not push/pull Notion, Builder.io, or other provider-backed content unless
+  the user explicitly asks for provider sync.
+- Do not paste secrets, private provider data, or credential-looking values into
+  docs, generated pages, frontmatter, examples, or local components.
+`;
 const DESIGN_EXPLORATION_SKILL_MD = `---
 name: design-exploration
 description: >-
@@ -2164,6 +2280,53 @@ export const BUILT_IN_APP_SKILLS = {
         }),
         skillMarkdown: ASSETS_SKILL_MD,
     },
+    content: {
+        skillName: "content",
+        manifest: normalizeAppSkillManifest({
+            schemaVersion: 1,
+            id: "content",
+            displayName: "Content",
+            description: "Edit docs, blogs, resources, and MDX content through the Content app, including repo-backed Local File Mode.",
+            hosted: {
+                url: "https://content.agent-native.com",
+                mcpUrl: "https://content.agent-native.com/_agent-native/mcp",
+            },
+            mcp: { serverName: "agent-native-content" },
+            auth: {
+                mode: "oauth",
+                setup: "Authenticate with the Content MCP connector in the host app. Local File Mode requires a local Content app, Agent Native Desktop, or trusted local bridge for filesystem access.",
+            },
+            surfaces: [
+                {
+                    id: "content-documents",
+                    action: "list-documents",
+                    path: "/",
+                },
+                {
+                    id: "content-local-files",
+                    action: "share-local-file-document",
+                    path: "/local-files",
+                },
+            ],
+            skills: [
+                {
+                    path: "skills/content",
+                    visibility: "exported",
+                    exportAs: "content",
+                },
+            ],
+            hostAdapters: [
+                "codex-plugin",
+                "claude-marketplace",
+                "vercel-skills",
+                "plain-skill",
+                "claude-skill",
+                "chatgpt-mcp",
+                "generic-mcp",
+            ],
+        }),
+        skillMarkdown: CONTENT_SKILL_MD,
+    },
     design: {
         skillName: "design-exploration",
         manifest: normalizeAppSkillManifest({
@@ -2318,6 +2481,12 @@ const BUILT_IN_APP_SKILL_ALIASES = {
     "image-generation": "assets",
     "agent-native-assets": "assets",
     "agent-native-images": "assets",
+    content: "content",
+    docs: "content",
+    documents: "content",
+    "local-content": "content",
+    "content-local-files": "content",
+    "agent-native-content": "content",
     design: "design",
     "ui-design": "design",
     "ux-design": "design",
@@ -2345,6 +2514,13 @@ const BUILT_IN_APP_SKILL_ALIASES = {
 };
 const BUILT_IN_APP_SKILL_DISPLAY_ALIASES = {
     assets: ["images", "image-generation", "agent-native-images"],
+    content: [
+        "docs",
+        "documents",
+        "local-content",
+        "content-local-files",
+        "agent-native-content",
+    ],
     design: [
         "design-exploration",
         "ux-exploration",
@@ -2431,6 +2607,12 @@ function isKnownSkill(value) {
 function isLocalOnlyBuiltInSkill(entry) {
     return Boolean(entry && "localOnly" in entry && entry.localOnly);
 }
+function targetSupportsInstallMode(targetId) {
+    return targetId === "visual-plans" || targetId === "content";
+}
+function localFilesModeSkipsMcp(targetId, mode) {
+    return mode === "local-files" && targetSupportsInstallMode(targetId);
+}
 function builtInExtraSkills(entry) {
     return "extraSkills" in entry && entry.extraSkills ? entry.extraSkills : {};
 }
@@ -2508,19 +2690,49 @@ 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,
-    });
+function contentModeInstructionBlock(input) {
+    if (input.mode === "local-files") {
+        return `## Installed Mode
+
+Default storage for this installation: Content Local File Mode. This repo should
+have an \`agent-native.json\` file with \`apps.content.mode: "local-files"\`;
+the installer writes one if missing and fills in default roots for \`docs/\`,
+\`blog/\`, \`content/\`, and \`resources/\`. Prefer Content document actions
+when a local Content app,
+Agent Native Desktop, or another trusted local bridge exposes them. If those
+tools are not currently available, edit the configured Markdown/MDX files and
+local components directly, preserving frontmatter, imports, JSX, and unknown MDX
+syntax. The hosted Content app cannot read private repo files by itself.`;
+    }
+    if (input.mode === "self-hosted") {
+        return `## Installed Mode
+
+Default storage for this installation: the configured self-hosted/custom Content
+app${input.mcpUrl ? ` at \`${input.mcpUrl}\`` : ""}. Use that Content MCP
+connector instead of assuming \`https://content.agent-native.com\`.`;
+    }
+    return "";
+}
+function applyInstallModeToSkillMarkdown(markdown, input) {
+    let block = "";
+    if (input.appSkillId === "visual-plans") {
+        block = planModeInstructionBlock({
+            mode: input.mode,
+            mcpUrl: input.mcpUrl,
+        });
+    }
+    else if (input.appSkillId === "content") {
+        block = contentModeInstructionBlock({
+            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]: applyPlanModeToSkillMarkdown(entry.skillMarkdown, {
+        [entry.skillName]: applyInstallModeToSkillMarkdown(entry.skillMarkdown, {
             appSkillId,
             mode: options.planMode,
             mcpUrl: options.mcpUrl,
@@ -2528,7 +2740,7 @@ function skillFilesForBuiltIn(appSkillId, options = {}) {
         ...builtInExtraSkills(entry),
     };
     for (const [skillName, skillMarkdown] of Object.entries(builtInExtraSkills(entry))) {
-        skills[skillName] = applyPlanModeToSkillMarkdown(skillMarkdown, {
+        skills[skillName] = applyInstallModeToSkillMarkdown(skillMarkdown, {
             appSkillId,
             mode: options.planMode,
             mcpUrl: options.mcpUrl,
@@ -2545,7 +2757,8 @@ function skillFilesForBuiltIn(appSkillId, options = {}) {
             appSkillId,
             displayName: entry.manifest.displayName,
             skillName,
-            mcpUrl: isLocalOnlyBuiltInSkill(entry) || options.planMode === "local-files"
+            mcpUrl: isLocalOnlyBuiltInSkill(entry) ||
+                localFilesModeSkipsMcp(appSkillId, options.planMode)
                 ? ""
                 : (options.mcpUrl ?? entry.manifest.hosted.mcpUrl),
             files,
@@ -2584,6 +2797,90 @@ function writeSkillFolder(dir, bundle, installedAt = new Date().toISOString()) {
     };
     fs.writeFileSync(path.join(dir, AGENT_NATIVE_SKILL_METADATA_FILE), `${JSON.stringify(metadata, null, 2)}\n`, "utf-8");
 }
+function isJsonRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function defaultContentLocalFilesAppConfig() {
+    return {
+        mode: "local-files",
+        roots: [
+            {
+                name: "Docs",
+                path: "docs",
+                kind: "docs",
+                extensions: [".md", ".mdx"],
+            },
+            {
+                name: "Blog",
+                path: "blog",
+                kind: "blog",
+                extensions: [".md", ".mdx"],
+            },
+            {
+                name: "Content",
+                path: "content",
+                kind: "content",
+                extensions: [".md", ".mdx"],
+            },
+            {
+                name: "Resources",
+                path: "resources",
+                kind: "resources",
+                extensions: [".md", ".mdx"],
+            },
+        ],
+        components: "components",
+        extensions: "extensions",
+        hide: ["**/_*.md", "**/_*.mdx"],
+    };
+}
+function contentLocalFilesManifestPath(baseDir) {
+    return path.join(baseDir, "agent-native.json");
+}
+function shouldWriteContentLocalFilesManifest(targetId, mode) {
+    return targetId === "content" && mode === "local-files";
+}
+function mergeContentLocalFilesManifest(existing) {
+    const manifest = isJsonRecord(existing) ? { ...existing } : {};
+    if (manifest.version === undefined)
+        manifest.version = 1;
+    const apps = isJsonRecord(manifest.apps) ? { ...manifest.apps } : {};
+    const contentApp = isJsonRecord(apps.content) ? { ...apps.content } : {};
+    const defaults = defaultContentLocalFilesAppConfig();
+    contentApp.mode = "local-files";
+    if (!Array.isArray(contentApp.roots) || contentApp.roots.length === 0) {
+        contentApp.roots = defaults.roots;
+    }
+    if (contentApp.components === undefined) {
+        contentApp.components = defaults.components;
+    }
+    if (contentApp.extensions === undefined) {
+        contentApp.extensions = defaults.extensions;
+    }
+    if (!Array.isArray(contentApp.hide) || contentApp.hide.length === 0) {
+        contentApp.hide = defaults.hide;
+    }
+    apps.content = contentApp;
+    manifest.apps = apps;
+    return manifest;
+}
+function writeContentLocalFilesManifest(baseDir, options = {}) {
+    const manifestPath = contentLocalFilesManifestPath(baseDir);
+    let existing = {};
+    if (fs.existsSync(manifestPath)) {
+        try {
+            existing = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+        }
+        catch (error) {
+            throw new Error(`Could not parse ${manifestPath}: ${error?.message ?? error}`);
+        }
+    }
+    const manifest = mergeContentLocalFilesManifest(existing);
+    if (!options.dryRun) {
+        fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf-8");
+    }
+    return manifestPath;
+}
 /**
  * The skills directory a built-in skill's instructions are copied into for a
  * given agent + scope. Mirrors the layout the skills installer uses so
@@ -2979,6 +3276,11 @@ const BUILT_IN_SKILL_PROMPT_OPTIONS = [
         label: "assets",
         hint: BUILT_IN_APP_SKILLS.assets.manifest.description,
     },
+    {
+        value: "content",
+        label: "content",
+        hint: BUILT_IN_APP_SKILLS.content.manifest.description,
+    },
     {
         value: "design-exploration",
         label: "design-exploration",
@@ -3262,11 +3564,21 @@ function targetIncludesPlans(target) {
 function targetsIncludePlans(targets) {
     return targets.some(targetIncludesPlans);
 }
+function targetIncludesInstallModeSkill(target) {
+    return targetSupportsInstallMode(normalizeKnownSkillTarget(target));
+}
+function targetsIncludeInstallModeSkills(targets) {
+    return targets.some(targetIncludesInstallModeSkill);
+}
 function planSkillNamesSelected(skillNames) {
     return Boolean(skillNames?.some((name) => normalizeKnownSkillTarget(name) === "visual-plans"));
 }
+function installModeSkillNamesSelected(skillNames) {
+    return Boolean(skillNames?.some((name) => targetSupportsInstallMode(normalizeKnownSkillTarget(name))));
+}
 function shouldForwardPlanModeFlag(target, skillNames) {
-    return targetIncludesPlans(target) || planSkillNamesSelected(skillNames);
+    return (targetIncludesInstallModeSkill(target) ||
+        installModeSkillNamesSelected(skillNames));
 }
 function recapSkillNamesSelected(skillNames) {
     return Boolean(skillNames?.some((name) => {
@@ -3484,6 +3796,9 @@ function loadSkillTarget(target, onlySkillNames) {
                 dir: process.cwd(),
             },
             skillNames,
+            modeAwareId: targetSupportsInstallMode(knownTarget)
+                ? knownTarget
+                : undefined,
             materializeInstructions(outDir) {
                 const bundles = skillFilesForBuiltIn(knownTarget);
                 for (const bundle of Object.values(bundles)) {
@@ -3508,6 +3823,9 @@ function loadSkillTarget(target, onlySkillNames) {
         skillNames: loaded.manifest.skills
             .filter((skill) => skill.visibility === "exported" || skill.visibility === "both")
             .map((skill) => skill.exportAs ?? path.basename(skill.path)),
+        modeAwareId: targetSupportsInstallMode(loaded.manifest.id)
+            ? loaded.manifest.id
+            : undefined,
         materializeInstructions(outDir) {
             const packed = buildAppSkillPack(loaded, outDir);
             const vercelAdapter = path.join(packed.outDir, "adapters", "vercel-skills");
@@ -3571,7 +3889,7 @@ function preserveMcpUrlAppPathOverride(target, input) {
         },
     };
 }
-function dryRunInstallCommand(parsed, target) {
+function dryRunInstallCommand(parsed, target, options = {}) {
     const clients = parsed.clients ??
         resolveSkillsClientArg(parsed.client, targetInstallsMcp(target, parsed));
     const args = [
@@ -3585,7 +3903,8 @@ function dryRunInstallCommand(parsed, target) {
         parsed.scope,
     ];
     const forwardsPlanFlags = shouldForwardPlanModeFlag(target, parsed.plainSkillNames);
-    if (forwardsPlanFlags && parsed.planMode)
+    const forwardsInstallMode = forwardsPlanFlags || targetSupportsInstallMode(options.modeAwareTargetId);
+    if (forwardsInstallMode && parsed.planMode)
         args.push("--mode", parsed.planMode);
     if (parsed.mcpUrl)
         args.push("--mcp-url", parsed.mcpUrl);
@@ -3752,7 +4071,7 @@ async function addPlainSkillRepo(parsed, options) {
     if (!parsed.instructions && parsed.mcp) {
         throw new Error("Plain skill repositories only install skill instructions. Run without --mcp-only.");
     }
-    if (parsed.mcpUrl && !planSkillNamesSelected(parsed.plainSkillNames)) {
+    if (parsed.mcpUrl && !installModeSkillNamesSelected(parsed.plainSkillNames)) {
         throw new Error("--mcp-url only applies to app-backed Agent Native skills.");
     }
     const clients = parsed.clients ?? resolveSkillsClientArg(parsed.client);
@@ -3942,20 +4261,6 @@ export async function addAgentNativeSkill(parsed, options = {}) {
         }, options);
     }
     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.
@@ -3971,7 +4276,11 @@ export async function addAgentNativeSkill(parsed, options = {}) {
         throw new Error(`Unknown skill or manifest path: ${target}. Run "npx @agent-native/core@latest skills list".`);
     }
     const knownBuiltIn = knownTarget ? BUILT_IN_APP_SKILLS[knownTarget] : null;
+    const baseDir = options.baseDir ?? process.cwd();
     if (isLocalOnlyBuiltInSkill(knownBuiltIn)) {
+        if (parsed.planMode) {
+            throw new Error("--mode only applies to visual-plan / visual-recap / content.");
+        }
         if (parsed.mcpUrl) {
             throw new Error("Context X-Ray is installed locally and does not use --mcp-url yet.");
         }
@@ -4004,7 +4313,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
             };
         }
         const localInstall = installLocalContextXray({
-            baseDir: options.baseDir ?? process.cwd(),
+            baseDir,
             clients,
             scope: parsed.scope,
         });
@@ -4030,6 +4339,25 @@ export async function addAgentNativeSkill(parsed, options = {}) {
         };
     }
     let installTarget = loadSkillTarget(target, onlySkillNames);
+    const modeAwareTargetId = installTarget.modeAwareId;
+    const planMode = modeAwareTargetId
+        ? (parsed.planMode ??
+            (parsed.mcpUrl
+                ? "self-hosted"
+                : modeAwareTargetId === "visual-plans"
+                    ? "hosted"
+                    : undefined))
+        : undefined;
+    if (parsed.planMode && !modeAwareTargetId) {
+        throw new Error("--mode only applies to visual-plan / visual-recap / content.");
+    }
+    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 && !localFilesModeSkipsMcp(modeAwareTargetId, planMode);
     if (parsed.mcpUrl) {
         installTarget = withMcpUrlOverride(installTarget, parsed.mcpUrl);
     }
@@ -4042,6 +4370,9 @@ export async function addAgentNativeSkill(parsed, options = {}) {
     const skillsAgents = skillsAgentsForClients(clients);
     if (parsed.dryRun) {
         try {
+            const localManifestPath = shouldWriteContentLocalFilesManifest(modeAwareTargetId, planMode)
+                ? contentLocalFilesManifestPath(baseDir)
+                : undefined;
             const githubActionPath = parsed.withGithubAction && installsRecap
                 ? prVisualRecapWorkflowDisplayPath()
                 : undefined;
@@ -4059,15 +4390,19 @@ export async function addAgentNativeSkill(parsed, options = {}) {
                 displayName: installTarget.displayName,
                 skillNames: installTarget.skillNames,
                 skillsAgents,
-                mcpUrl: knownTarget === "visual-plans" && planMode === "local-files"
+                mcpUrl: localFilesModeSkipsMcp(modeAwareTargetId, planMode)
                     ? ""
                     : installTarget.loaded.manifest.hosted.mcpUrl,
                 mcpClients: shouldRegisterMcp ? mcpClients : [],
                 dryRun: true,
-                commands: [dryRunInstallCommand(parsed, target)],
+                commands: [
+                    dryRunInstallCommand(parsed, target, { modeAwareTargetId }),
+                    ...(localManifestPath ? [`write ${localManifestPath}`] : []),
+                ],
                 githubActionPath,
                 githubActionSuggestedCommand,
                 planMode,
+                localManifestPath,
             };
         }
         finally {
@@ -4081,6 +4416,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
     let connected = false;
     let connectCommand;
     let registeredMcpClients = shouldRegisterMcp ? mcpClients : [];
+    let localManifestPath;
     try {
         if (parsed.instructions) {
             if (skillsAgents.length === 0) {
@@ -4098,7 +4434,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
                     onlySkillNames,
                     skillsAgents,
                     scope: parsed.scope,
-                    baseDir: options.baseDir ?? process.cwd(),
+                    baseDir,
                     dryRun: parsed.dryRun,
                     planMode,
                     mcpUrl: installTarget.loaded.manifest.hosted.mcpUrl,
@@ -4121,6 +4457,12 @@ export async function addAgentNativeSkill(parsed, options = {}) {
                     ...installTarget.skillNames.flatMap((skill) => ["--skill", skill]),
                     ...skillsAgents.flatMap((agent) => ["-a", agent]),
                     ...(parsed.scope === "user" ? ["-g"] : []),
+                    ...(modeAwareTargetId && parsed.planMode
+                        ? ["--mode", parsed.planMode]
+                        : []),
+                    ...(modeAwareTargetId && parsed.mcpUrl
+                        ? ["--mcp-url", parsed.mcpUrl]
+                        : []),
                     ...(parsed.yes || knownTarget ? ["-y"] : []),
                 ];
                 commands.push(commandString("npx", args));
@@ -4133,6 +4475,10 @@ export async function addAgentNativeSkill(parsed, options = {}) {
                 }
             }
         }
+        if (shouldWriteContentLocalFilesManifest(modeAwareTargetId, planMode)) {
+            localManifestPath = writeContentLocalFilesManifest(baseDir);
+            commands.push(`write ${localManifestPath}`);
+        }
         // Skill instructions are now on disk (built-in folders copied or external
         // pack materialized) — record the install before MCP registration/connect.
         options.telemetry?.track("skills_cli install completed", {
@@ -4180,7 +4526,6 @@ export async function addAgentNativeSkill(parsed, options = {}) {
         }
         // `--with-github-action`: also drop the PR Visual Recap workflow into the
         // repo so PRs get automatic recaps. Only meaningful for the plan family.
-        const baseDir = options.baseDir ?? process.cwd();
         let withGithubAction = Boolean(parsed.withGithubAction);
         let githubActionPath;
         let githubActionExisted;
@@ -4233,7 +4578,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
             instructionSource,
             skillNames: installTarget.skillNames,
             skillsAgents,
-            mcpUrl: knownTarget === "visual-plans" && planMode === "local-files"
+            mcpUrl: localFilesModeSkipsMcp(modeAwareTargetId, planMode)
                 ? ""
                 : installTarget.loaded.manifest.hosted.mcpUrl,
             mcpClients: registeredMcpClients,
@@ -4243,6 +4588,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
             connected,
             connectCommand,
             planMode,
+            localManifestPath,
             githubActionPath,
             githubActionExisted,
             githubActionSuggestedCommand,
@@ -4306,10 +4652,10 @@ function formatSkillState(state) {
 }
 function planModeSummary(mode) {
     if (mode === "local-files")
-        return "Local files - No sharing, all local.";
+        return "Local files - no hosted writes by default";
     if (mode === "self-hosted")
-        return "Self-hosted/custom Plan app";
-    return "Hosted Plans - shareable links and comments";
+        return "Self-hosted/custom app";
+    return "Hosted app";
 }
 function skillInstructionAgentLabel(agent) {
     if (agent === "codex")
@@ -4326,8 +4672,8 @@ function targetInstallsMcp(target, parsed) {
     if (publicSkillSelectionNames(target))
         return false;
     const knownTarget = normalizeKnownSkillTarget(target);
-    if (knownTarget === "visual-plans")
-        return parsed.planMode !== "local-files";
+    if (localFilesModeSkipsMcp(knownTarget, parsed.planMode))
+        return false;
     if (knownTarget) {
         return !isLocalOnlyBuiltInSkill(BUILT_IN_APP_SKILLS[knownTarget]);
     }
@@ -4515,8 +4861,10 @@ export async function runSkills(argv, options = {}) {
         });
         const includesPlans = targetsIncludePlans(targets) ||
             planSkillNamesSelected(parsed.plainSkillNames);
-        if (parsed.planMode && !includesPlans) {
-            throw new Error("--mode only applies to visual-plan / visual-recap.");
+        const includesInstallModeSkills = targetsIncludeInstallModeSkills(targets) ||
+            installModeSkillNamesSelected(parsed.plainSkillNames);
+        if (parsed.planMode && !includesInstallModeSkills) {
+            throw new Error("--mode only applies to visual-plan / visual-recap / content.");
         }
         if (includesPlans) {
             if (!parsed.planMode && parsed.mcpUrl) {
@@ -4709,7 +5057,7 @@ export async function runSkills(argv, options = {}) {
                 : "MCP config           not required",
             mcpUrls.length ? `MCP URL              ${mcpUrls.join(", ")}` : "",
             planModes.length
-                ? `Plan mode            ${planModes.map(planModeSummary).join(", ")}`
+                ? `Install mode         ${planModes.map(planModeSummary).join(", ")}`
                 : "",
             authConnected
                 ? "Authentication       completed"