@agent-native/core 0.48.2 → 0.48.4

package/README.md

@@ -200,7 +200,7 @@ Every template is a complete cloneable SaaS — fork it, customize it with the a
 ## Quick Start
 
 ```bash
-npx @agent-native/core create my-platform
+npx @agent-native/core@latest create my-platform
 cd my-platform
 pnpm install
 pnpm dev
@@ -211,7 +211,7 @@ The CLI shows a multi-select picker so you can include as many templates as you
 Want a single app, no monorepo? Use `--standalone`:
 
 ```bash
-npx @agent-native/core create my-app --standalone --template mail
+npx @agent-native/core@latest create my-app --standalone --template mail
 ```
 
 ## Workspaces (Monorepo)
@@ -234,13 +234,13 @@ my-platform/
 Add another app later:
 
 ```bash
-npx @agent-native/core add-app notes --template content
+npx @agent-native/core@latest add-app notes --template content
 ```
 
 Deploy every app behind one origin:
 
 ```bash
-agent-native deploy
+npx @agent-native/core@latest deploy
 # https://your-agents.com/mail/*       → mail
 # https://your-agents.com/calendar/*   → calendar
 # https://your-agents.com/forms/*      → forms

package/dist/cli/skills.js

@@ -26,7 +26,8 @@ Examples:
   agent-native skills add assets
   agent-native skills add design-exploration
   agent-native skills add visual-plan
-  agent-native skills add visual-plan --with-github-action
+  agent-native skills add visual-recap
+  agent-native skills add visual-recap --with-github-action
   agent-native skills status visual-plan
   agent-native skills update visual-plan
   agent-native skills add visual-plan --no-connect
@@ -54,7 +55,7 @@ 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 interactively, the CLI offers to add the optional PR
+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 "agent-native recap setup" / "agent-native recap doctor" to configure and
 verify GitHub Actions.
@@ -125,7 +126,7 @@ of using a generic image generator.
   browser approved but the local MCP config unwritten. Restart or reload the
   agent client after installing or connecting if Assets tools do not appear in
   the live session.
-- Local customization: use \`agent-native app-skill launch --local\` from an
+- Local customization: use \`npx @agent-native/core@latest app-skill launch --local\` from an
   Assets app-skill manifest, or pass \`--into <path>\` for editable source.
 - Do not call image/video providers directly from another app. Assets owns
   generation, picker UI, search/list/export, and asset context.
@@ -228,7 +229,7 @@ authenticates it in the same step (a one-time browser sign-in at setup — this
 intended), so the first tool call does not hit an OAuth wall:
 
 \`\`\`bash
-agent-native skills add visual-plan
+npx @agent-native/core@latest skills add visual-plan
 \`\`\`
 
 After that, \`/visual-plan\` and \`/visual-recap\` are the two installed slash
@@ -236,7 +237,7 @@ commands. The other planning modes (\`create-ui-plan\`, \`create-prototype-plan\
 \`create-plan-design\`, \`create-visual-questions\`) are MCP tools reachable from
 \`/visual-plan\`, not separate slash commands. Pass \`--no-connect\` to register
 the connector without authenticating, then run
-\`agent-native connect https://plan.agent-native.com\` whenever you are ready.
+\`npx @agent-native/core@latest connect https://plan.agent-native.com\` whenever you are ready.
 
 **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
@@ -251,7 +252,7 @@ hosted flow.
 
 If a Plans tool returns \`needs auth\`, \`Unauthorized\`, or \`Session terminated\`,
 do not keep retrying the tool. Authenticate the connector with
-\`agent-native connect https://plan.agent-native.com\` (OAuth-capable hosts can
+\`npx @agent-native/core@latest connect https://plan.agent-native.com\` (OAuth-capable hosts can
 instead re-run /mcp and choose Authenticate), then continue once the connector
 is available.
 
@@ -917,7 +918,7 @@ inline output: the usual cause is a connector that did not finish connecting
 this session (it registers zero tools), not auth. Stop and give the user the
 exact restore step — reconnect via \`/mcp\` (or restart the session); only if
 genuinely unauthenticated, run
-\`agent-native connect https://plan.agent-native.com\`. Publish once the tool is
+\`npx @agent-native/core@latest connect https://plan.agent-native.com\`. Publish once the tool is
 reachable. Local-files privacy mode (after Tool Guidance) is the only
 exception.
 
@@ -1091,7 +1092,7 @@ The local-files contract is:
 - 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 \`agent-native plan local preview --dir plans/<slug> --kind plan\` after
+- Run \`npx @agent-native/core@latest plan local preview --dir plans/<slug> --kind plan\` 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\`.
@@ -1179,14 +1180,14 @@ exception to the hosted publish rule below.
 In local-files mode:
 
 - Read the diff/stat/source context from local files and shell commands only.
-  The existing \`agent-native recap collect-diff\`, \`scan\`, and
+  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.
 - 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 \`agent-native plan local preview --dir plans/<slug> --kind recap\` after
+- Run \`npx @agent-native/core@latest plan local preview --dir plans/<slug> --kind recap\` 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\`.
@@ -1224,7 +1225,7 @@ connector that did not finish connecting this session (it registers zero tools),
 NOT necessarily an auth problem — so do not assume the user must authenticate.
 Stop and tell the user how to restore it: reconnect the Plan MCP connector (in
 Claude Code, run \`/mcp\` and reconnect, or restart the session); only if it is
-genuinely unauthenticated, run \`agent-native connect <plan-app-url>\` or
+genuinely unauthenticated, run \`npx @agent-native/core@latest connect <plan-app-url>\` or
 re-authenticate via \`/mcp\`. Then publish once the tool is reachable. Falling
 back to inline content is a defect, not a degraded mode.
 
@@ -1401,7 +1402,7 @@ 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
-\`agent-native plan local preview\` or the \`/local-plans/<slug>\` route for a local
+\`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.
 
@@ -1947,6 +1948,21 @@ function builtInExtraFiles(entry) {
 function builtInSkillNames(entry) {
     return [entry.skillName, ...Object.keys(builtInExtraSkills(entry))];
 }
+/**
+ * When a target names a single skill that lives inside a multi-skill bundle
+ * (the plan bundle ships both `visual-plan` and `visual-recap`), restrict the
+ * install to just that skill. The bundle aliases (`visual-plans`, `plannotate`,
+ * …) return undefined so they install every skill in the bundle.
+ */
+function builtInOnlySkillNames(target) {
+    const normalized = target.trim().toLowerCase();
+    if (normalized === "visual-plan")
+        return ["visual-plan"];
+    if (normalized === "visual-recap" || normalized === "visual-recaps") {
+        return ["visual-recap"];
+    }
+    return undefined;
+}
 function stableSkillHash(files) {
     const hash = createHash("sha256");
     for (const rel of Object.keys(files).sort()) {
@@ -2013,6 +2029,45 @@ 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");
 }
+/**
+ * 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
+ * `skills status` / `skills update` find the folders again.
+ */
+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 process.env.CODEX_HOME
+            ? path.join(process.env.CODEX_HOME, "skills")
+            : path.join(home, ".codex", "skills");
+    }
+    return path.join(home, ".claude", "skills");
+}
+/**
+ * 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
+ * there is no need to shell out to the separate @agent-native/skills installer
+ * (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 written = [];
+    for (const agent of input.skillsAgents) {
+        const root = builtInSkillsRootForAgent(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);
+        }
+    }
+    return written;
+}
 function listSkillFolderFiles(dir) {
     const out = {};
     const walk = (current, prefix = "") => {
@@ -2200,12 +2255,25 @@ function clientPromptOptions() {
         hint: CLIENT_HINTS[client],
     }));
 }
+// For now the interactive installer offers only the two plan skills, each as
+// an independently selectable entry (uncheck one to install just the other).
+// The other built-in skills stay installable via `agent-native skills add
+// <name>` but are hidden from the default checklist. The values are the real
+// slash-command names so users see exactly what they are installing.
+const PLAN_SKILL_PROMPT_OPTIONS = [
+    {
+        value: "visual-plan",
+        label: "visual-plan",
+        hint: "Reviewable coding-agent plan: diagrams, annotated code, file trees, open questions.",
+    },
+    {
+        value: "visual-recap",
+        label: "visual-recap",
+        hint: "Turn a PR, commit, branch, or git diff into a high-altitude visual recap.",
+    },
+];
 function skillPromptOptions() {
-    return Object.values(BUILT_IN_APP_SKILLS).map((entry) => ({
-        value: entry.skillName,
-        label: entry.manifest.displayName,
-        hint: entry.manifest.description,
-    }));
+    return PLAN_SKILL_PROMPT_OPTIONS;
 }
 function prVisualRecapWorkflowPath(baseDir) {
     return path.join(baseDir, ".github", "workflows", "pr-visual-recap.yml");
@@ -2214,10 +2282,10 @@ function prVisualRecapWorkflowDisplayPath() {
     return path.join(".github", "workflows", "pr-visual-recap.yml");
 }
 function prVisualRecapInstallCommand() {
-    return "agent-native skills add visual-plan --with-github-action";
+    return "npx @agent-native/core@latest skills add visual-recap --with-github-action";
 }
 function prVisualRecapSetupCommand() {
-    return "agent-native recap setup";
+    return "npx @agent-native/core@latest recap setup";
 }
 async function promptForGithubAction(context) {
     const clack = await import("@clack/prompts");
@@ -2258,6 +2326,30 @@ async function promptForClients(context) {
     }
     return normalizeClientIds(result);
 }
+async function promptForScope(context) {
+    const clack = await import("@clack/prompts");
+    const result = await clack.select({
+        message: "Where do you want to install these skills?",
+        options: [
+            {
+                value: "project",
+                label: "Project",
+                hint: "This repo only (.agents / .claude in the current directory) — committed with your project",
+            },
+            {
+                value: "user",
+                label: "User",
+                hint: "Your home directory (~/.codex, ~/.claude) — available across all projects",
+            },
+        ],
+        initialValue: context.initialScope,
+    });
+    if (clack.isCancel(result)) {
+        clack.cancel("Cancelled.");
+        return null;
+    }
+    return result === "project" ? "project" : "user";
+}
 async function promptForSkills(context) {
     const clack = await import("@clack/prompts");
     const result = await clack.multiselect({
@@ -2301,11 +2393,21 @@ async function resolveSkillTargets(parsed, options) {
     }
     const prompt = options.promptSkills ?? promptForSkills;
     const selected = await prompt({
-        initialTargets: ["assets"],
+        initialTargets: ["visual-plan", "visual-recap"],
         options: skillPromptOptions(),
     });
     if (!selected || selected.length === 0)
         return null;
+    // Both plan skills share one MCP connector, so when both are selected install
+    // them through the bundle target — that registers/authenticates the connector
+    // once instead of twice.
+    const planSubskills = ["visual-plan", "visual-recap"];
+    if (planSubskills.every((skill) => selected.includes(skill))) {
+        return [
+            "visual-plans",
+            ...selected.filter((s) => !planSubskills.includes(s)),
+        ];
+    }
     return selected;
 }
 export function parseSkillsArgs(argv) {
@@ -2406,11 +2508,11 @@ export function parseSkillsArgs(argv) {
     }
     return out;
 }
-function loadSkillTarget(target) {
+function loadSkillTarget(target, onlySkillNames) {
     const knownTarget = normalizeKnownSkillTarget(target);
     if (knownTarget) {
         const builtIn = BUILT_IN_APP_SKILLS[knownTarget];
-        const skillNames = builtInSkillNames(builtIn);
+        const skillNames = builtInSkillNames(builtIn).filter((name) => !onlySkillNames || onlySkillNames.includes(name));
         return {
             id: builtIn.manifest.id,
             displayName: builtIn.manifest.displayName,
@@ -2423,6 +2525,9 @@ function loadSkillTarget(target) {
             materializeInstructions(outDir) {
                 const bundles = skillFilesForBuiltIn(knownTarget);
                 for (const bundle of Object.values(bundles)) {
+                    if (onlySkillNames && !onlySkillNames.includes(bundle.skillName)) {
+                        continue;
+                    }
                     writeSkillFolder(path.join(outDir, "skills", bundle.skillName), bundle);
                 }
                 return outDir;
@@ -2705,7 +2810,7 @@ function canRunInteractiveConnect(options) {
         return false;
     return !!process.stdin.isTTY && !!process.stdout.isTTY;
 }
-/** Build the `agent-native connect <url> --client … --scope …` command. */
+/** Build the `npx @agent-native/core@latest connect <url> --client … --scope …` command. */
 function connectCommandFor(hostedUrl, clients, scope) {
     const args = [
         "connect",
@@ -2760,6 +2865,14 @@ async function connectAfterEnsure(installTarget, clients, parsed, options) {
 export async function addAgentNativeSkill(parsed, options = {}) {
     const target = parsed.target ?? "assets";
     const knownTarget = normalizeKnownSkillTarget(target);
+    // 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.
+    const onlySkillNames = knownTarget
+        ? builtInOnlySkillNames(target)
+        : undefined;
+    const installsRecap = knownTarget === "visual-plans" &&
+        (!onlySkillNames || onlySkillNames.includes("visual-recap"));
     if (!knownTarget && isPlainSkillRepoTarget(target)) {
         return addPlainSkillRepo({ ...parsed, target }, options);
     }
@@ -2813,7 +2926,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
             commands: localInstall.commands,
         };
     }
-    let installTarget = loadSkillTarget(target);
+    let installTarget = loadSkillTarget(target, onlySkillNames);
     if (parsed.mcpUrl) {
         installTarget = withMcpUrlOverride(installTarget, parsed.mcpUrl);
     }
@@ -2822,10 +2935,10 @@ export async function addAgentNativeSkill(parsed, options = {}) {
     const skillsAgents = skillsAgentsForClients(clients);
     if (parsed.dryRun) {
         try {
-            const githubActionPath = parsed.withGithubAction && knownTarget === "visual-plans"
+            const githubActionPath = parsed.withGithubAction && installsRecap
                 ? prVisualRecapWorkflowDisplayPath()
                 : undefined;
-            const githubActionSuggestedCommand = knownTarget === "visual-plans" && !parsed.withGithubAction
+            const githubActionSuggestedCommand = installsRecap && !parsed.withGithubAction
                 ? prVisualRecapInstallCommand()
                 : undefined;
             return {
@@ -2848,6 +2961,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
     const commands = [];
     const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "an-skills-add-"));
     let instructionSource;
+    let instructionsWritten;
     let connected = false;
     let connectCommand;
     try {
@@ -2857,7 +2971,26 @@ export async function addAgentNativeSkill(parsed, options = {}) {
                     throw new Error("Skill instructions can only be installed for Codex or Claude Code clients. Use an MCP-capable client or omit --instructions-only.");
                 }
             }
+            else if (knownTarget) {
+                // Built-in skills ship their instructions inside this package, so copy
+                // the skill folders straight into each client's skills directory. This
+                // avoids shelling out to the separate @agent-native/skills installer
+                // (which would need to be published to npm to run via npx).
+                instructionsWritten = installBuiltInInstructions({
+                    appSkillId: knownTarget,
+                    onlySkillNames,
+                    skillsAgents,
+                    scope: parsed.scope,
+                    baseDir: options.baseDir ?? process.cwd(),
+                    dryRun: parsed.dryRun,
+                });
+                instructionSource = instructionsWritten[0];
+                commands.push(...instructionsWritten.map((dir) => `write ${dir}`));
+            }
             else {
+                // External app-skill manifests / plain skill repos still go through the
+                // standalone installer, which knows how to pack adapters and fetch
+                // remote skill collections.
                 instructionSource = installTarget.materializeInstructions(tmpRoot);
                 const args = [
                     "--yes",
@@ -2881,7 +3014,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
             }
         }
         if (parsed.mcp) {
-            commands.push(`agent-native app-skill ensure --manifest ${installTarget.loaded.file} --client ${parsed.client} --scope ${parsed.scope} --yes`);
+            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, {
                     clients,
@@ -2911,7 +3044,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
         let githubActionPath;
         let githubActionExisted;
         let githubActionSuggestedCommand;
-        if (knownTarget === "visual-plans" &&
+        if (installsRecap &&
             !withGithubAction &&
             !fs.existsSync(prVisualRecapWorkflowPath(baseDir))) {
             if (shouldPrompt(parsed, options)) {
@@ -2927,8 +3060,8 @@ export async function addAgentNativeSkill(parsed, options = {}) {
             }
         }
         if (withGithubAction) {
-            if (knownTarget !== "visual-plans") {
-                options.log?.("--with-github-action only applies to the visual-plan skill; skipping the workflow.");
+            if (!installsRecap) {
+                options.log?.("--with-github-action only applies to the visual-recap skill; skipping the workflow.");
             }
             else {
                 const writeResult = writePrVisualRecapWorkflow(baseDir, {
@@ -2953,6 +3086,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
             mcpClients: clients,
             dryRun: parsed.dryRun,
             commands,
+            written: instructionsWritten,
             connected,
             connectCommand,
             githubActionPath,
@@ -3072,6 +3206,15 @@ export async function runSkills(argv, options = {}) {
     const clients = await resolveSkillsClients(parsed, options);
     if (!clients)
         return;
+    // Ask where to install (project vs user) unless an explicit --scope was
+    // passed or we are running non-interactively.
+    if (!parsed.scopeExplicit && shouldPrompt(parsed, options)) {
+        const promptScope = options.promptScope ?? promptForScope;
+        const scope = await promptScope({ initialScope: "project" });
+        if (!scope)
+            return;
+        parsed.scope = scope;
+    }
     const results = [];
     for (const target of targets) {
         results.push(await addAgentNativeSkill({