@agent-native/core 0.85.7 → 0.86.0

package/dist/cli/skills.js

@@ -20,9 +20,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|content|design-exploration|visual-edit|visual-plan|visual-recap|context-xray|scaffold] [--client codex|claude-code|pi|all] [--scope user|project] [--json]
-  npx @agent-native/core@latest skills update [assets|content|design-exploration|visual-edit|visual-plan|visual-recap|context-xray|scaffold] [--client codex|claude-code|pi|all] [--scope user|project] [--dry-run] [--json]
-  npx @agent-native/core@latest skills add assets|content|design-exploration|visual-edit|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-edit|visual-plan|visual-recap|visualize-repo|context-xray|scaffold] [--client codex|claude-code|pi|all] [--scope user|project] [--json]
+  npx @agent-native/core@latest skills update [assets|content|design-exploration|visual-edit|visual-plan|visual-recap|visualize-repo|context-xray|scaffold] [--client codex|claude-code|pi|all] [--scope user|project] [--dry-run] [--json]
+  npx @agent-native/core@latest skills add assets|content|design-exploration|visual-edit|visual-plan|visual-recap|visualize-repo|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:
@@ -32,6 +32,7 @@ Examples:
   npx @agent-native/core@latest skills add visual-edit
   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 visualize-repo
   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
@@ -68,9 +69,10 @@ 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.
+When installing visual-plan, visual-recap, or visualize-repo interactively, the
+CLI asks where Plans artifacts 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 the localhost bridge viewer.
@@ -600,9 +602,10 @@ not hit an OAuth wall:
 npx @agent-native/core@latest skills add visual-plans
 \`\`\`
 
-After that, \`/visual-plan\` and \`/visual-recap\` are the two installed slash
-commands. If you only need one command, use \`skills add visual-plan\` or
-\`skills add visual-recap\` instead. The other planning modes
+After that, \`/visual-plan\`, \`/visual-recap\`, and \`/visualize-repo\` are the
+installed slash commands. If you only need one command, use
+\`skills add visual-plan\`, \`skills add visual-recap\`, or
+\`skills add visualize-repo\` instead. 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
@@ -622,6 +625,10 @@ 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 the MDX folder locally, run \`plan local check\`, then run \`plan local serve\`.
+For repo-wide visual docs, run
+\`npx @agent-native/core@latest visualize-repo --open\` to create/update
+\`agent-native.json\`, seed \`.agent-native/visual-docs/repo-overview\`, and open
+the local bridge.
 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
@@ -1994,9 +2001,10 @@ not hit an OAuth wall:
 npx @agent-native/core@latest skills add visual-plans
 \`\`\`
 
-After that, \`/visual-plan\` and \`/visual-recap\` are the two installed slash
-commands. If you only need one command, use \`skills add visual-plan\` or
-\`skills add visual-recap\` instead. The other planning modes
+After that, \`/visual-plan\`, \`/visual-recap\`, and \`/visualize-repo\` are the
+installed slash commands. If you only need one command, use
+\`skills add visual-plan\`, \`skills add visual-recap\`, or
+\`skills add visualize-repo\` instead. 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
@@ -2016,6 +2024,11 @@ 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 repo-wide visual docs, run
+\`npx @agent-native/core@latest visualize-repo --open\` to create/update
+\`agent-native.json\`, seed \`.agent-native/visual-docs/repo-overview\`, and open
+the local bridge.
+
 If a Plans tool returns \`needs auth\`, \`Unauthorized\`, or \`Session terminated\`, do
 not keep retrying it — stop and give the user the per-client reconnect step from
 \`references/connection.md\`, then continue once the connector is available.
@@ -2570,6 +2583,99 @@ auto-re-run is the remaining fast-follow.
   recap's redaction and visibility gating mirror.
 - **sharing** — org/login-gated visibility for the plan that holds the recap.
 `;
+export const VISUALIZE_REPO_SKILL_MD = `---
+name: visualize-repo
+description: >-
+  Open or create a repo-native visual documentation workspace backed by local
+  Plan MDX files. Use when the user asks to visualize a repository, create
+  durable visual docs for APIs/components/models/flows, launch a visual repo
+  viewer, review repo docs like a visual IDE, or collect Plan comments that
+  should become coding-agent changes.
+metadata:
+  visibility: exported
+---
+
+# Visualize Repo
+
+\`/visualize-repo\` opens a local, source-controlled visual documentation layer
+for a repository. It is for durable repo understanding, not a one-off plan:
+components can have wireframes, APIs can have specs, models can have schema
+views, and reviewers can comment on those docs before sending work to a coding
+agent.
+
+## Default Command
+
+Run the Agent-Native CLI from the repo root:
+
+\`\`\`bash
+npx @agent-native/core@latest visualize-repo --open
+\`\`\`
+
+Useful variants:
+
+\`\`\`bash
+npx @agent-native/core@latest visualize-repo init
+npx @agent-native/core@latest visualize-repo --target actions --target server/db/schema.ts
+npx @agent-native/core@latest visualize-repo check
+npx @agent-native/core@latest visualize-repo verify
+npx @agent-native/core@latest visualize-repo --no-open
+\`\`\`
+
+The command writes or updates \`agent-native.json\` with an
+\`apps.visualize-repo\` local-files section, creates a starter MDX folder at
+\`.agent-native/visual-docs/repo-overview\`, then serves it through the Plan
+local bridge. The hosted Plan UI can render the review surface, but the plan
+source stays in local files and bridge comments stay in \`comments.json\`.
+
+## When There Is No Manifest
+
+If \`agent-native.json\` does not exist, let the CLI bootstrap one. It scans for
+high-value starting points such as \`actions/\`, \`app/components/\`,
+\`app/pages/\`, \`server/db/schema.ts\`, \`src/\`, \`packages/\`, \`templates/\`,
+\`docs/\`, and \`content/\`. Keep the first run targeted. Prefer 5-20 visualized
+nodes over a generated wall of repo prose.
+
+Use explicit targets when the user already knows the important surface:
+
+\`\`\`bash
+npx @agent-native/core@latest visualize-repo \\
+  --target actions/webhooks.ts \\
+  --target server/db/schema.ts \\
+  --target app/components/PromptComposer.tsx
+\`\`\`
+
+## Agent Workflow
+
+1. Inspect \`agent-native.json\` and the generated \`plan.mdx\`.
+2. Read the source anchors listed for each target before changing the visual
+   docs.
+3. Add only the visual blocks that earn their keep: \`api-endpoint\` for stable
+   APIs, \`data-model\` for durable schema, \`wireframe\` for user-facing
+   components/flows, \`diagram\` for architecture, and \`annotated-code\` for
+   load-bearing implementation.
+4. Run \`npx @agent-native/core@latest visualize-repo check\` after editing MDX.
+5. Use \`verify\` before handoff when renderer correctness matters.
+
+When acting on comments, treat local \`comments.json\` as the feedback inbox.
+Agent-targeted comments should become code changes plus matching MDX updates so
+the visual docs and executable code stay in sync.
+
+## Privacy Boundary
+
+\`visualize-repo check\` is local/offline lint. \`visualize-repo --open\` starts a
+localhost bridge and opens the Plan UI against local files; it does not publish
+the plan to hosted storage and performs no hosted Plan database writes.
+\`visualize-repo verify\` may send the MDX folder to the Plan app's public
+validation action so the real renderer schema can check it. For no hosted
+content egress, pass \`--app-url\` pointing at a local Plan app or skip
+\`verify\` and rely on \`check\`.
+
+Do not call hosted Plan write tools for this workflow unless the user explicitly
+asks to publish or share the docs. Avoid \`create-visual-plan\`,
+\`update-visual-plan\`, \`import-visual-plan-source\`, \`patch-visual-plan-source\`,
+and \`get-plan-feedback\` for local repo docs; edit the MDX files directly and
+use the local bridge.
+`;
 export const BUILT_IN_APP_SKILLS = {
     assets: {
         skillName: "assets",
@@ -2721,6 +2827,7 @@ export const BUILT_IN_APP_SKILLS = {
         skillName: "visual-plan",
         extraSkills: {
             "visual-recap": VISUAL_RECAP_SKILL_MD,
+            "visualize-repo": VISUALIZE_REPO_SKILL_MD,
         },
         // Sibling reference files materialized alongside each skill's SKILL.md
         // (progressive disclosure). Keyed by skill name -> relative path -> content.
@@ -2745,7 +2852,7 @@ export const BUILT_IN_APP_SKILLS = {
             schemaVersion: 1,
             id: "visual-plans",
             displayName: "Agent-Native Plan",
-            description: "Create rich interactive visual plans and recaps with diagrams, file maps, annotated code and diffs, API/schema summaries, feedback, and HTML export.",
+            description: "Create rich interactive visual plans, recaps, and repo-native visual docs with diagrams, file maps, annotated code and diffs, API/schema summaries, feedback, and HTML export.",
             hosted: {
                 url: "https://plan.agent-native.com",
                 mcpUrl: "https://plan.agent-native.com/_agent-native/mcp",
@@ -2768,6 +2875,11 @@ export const BUILT_IN_APP_SKILLS = {
                     path: "/plans",
                     description: "Create an interactive visual recap from a PR, commit, branch, or git diff so reviewers see the shape of the change before raw diff review.",
                 },
+                {
+                    id: "visualize-repo",
+                    path: "/local-plans",
+                    description: "Open a local, repo-backed visual documentation workspace for APIs, components, models, flows, comments, and coding-agent handoff.",
+                },
             ],
             skills: [
                 {
@@ -2780,6 +2892,11 @@ export const BUILT_IN_APP_SKILLS = {
                     visibility: "exported",
                     exportAs: "visual-recap",
                 },
+                {
+                    path: "skills/visualize-repo",
+                    visibility: "exported",
+                    exportAs: "visualize-repo",
+                },
             ],
             hostAdapters: [
                 "codex-plugin",
@@ -2855,6 +2972,10 @@ const BUILT_IN_APP_SKILL_ALIASES = {
     "visual-plan": "visual-plans",
     "visual-recap": "visual-plans",
     "visual-recaps": "visual-plans",
+    "visualize-repo": "visual-plans",
+    visualize: "visual-plans",
+    "repo-visualizer": "visual-plans",
+    "visual-docs": "visual-plans",
     "code-review-recap": "visual-plans",
     "code-review-recaps": "visual-plans",
     "html-plan": "visual-plans",
@@ -2888,6 +3009,7 @@ const BUILT_IN_APP_SKILL_DISPLAY_ALIASES = {
     "visual-plans": [
         "visual-plan",
         "visual-recap",
+        "visualize-repo",
         "code-review-recap",
         "html-plan",
         "plannotate",
@@ -2987,9 +3109,9 @@ function builtInSkillNames(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.
+ * (the plan bundle ships `visual-plan`, `visual-recap`, and `visualize-repo`),
+ * 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();
@@ -2998,6 +3120,12 @@ function builtInOnlySkillNames(target) {
     if (normalized === "visual-recap" || normalized === "visual-recaps") {
         return ["visual-recap"];
     }
+    if (normalized === "visualize-repo" ||
+        normalized === "visualize" ||
+        normalized === "repo-visualizer" ||
+        normalized === "visual-docs") {
+        return ["visualize-repo"];
+    }
     if (normalized === "design-exploration" ||
         normalized === "agent-native-design-exploration") {
         return ["design-exploration"];
@@ -3328,6 +3456,18 @@ argument-hint: [PR, branch, commit, diff, or scope]
 
 Use the visual-recap skill. Treat any arguments as the recap target or focus:
 
+$ARGUMENTS
+`;
+    }
+    if (skillName === "visualize-repo") {
+        return `---
+description: Open or create a local Agent-Native visual docs workspace for this repo.
+argument-hint: [optional targets or focus]
+---
+
+Use the visualize-repo skill. Treat any arguments as source targets, repo areas,
+or review focus:
+
 $ARGUMENTS
 `;
     }
@@ -3948,6 +4088,11 @@ 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: "visualize-repo",
+        label: "visualize-repo",
+        hint: "Local repo visual docs workspace for APIs, components, models, flows, comments, and coding-agent handoff.",
+    },
     {
         value: "assets",
         label: "assets",
@@ -3974,7 +4119,11 @@ const BUILT_IN_SKILL_PROMPT_OPTIONS = [
         hint: BUILT_IN_APP_SKILLS["context-xray"].manifest.description,
     },
 ];
-const DEFAULT_SKILL_PROMPT_TARGETS = ["visual-plan", "visual-recap"];
+const DEFAULT_SKILL_PROMPT_TARGETS = [
+    "visual-plan",
+    "visual-recap",
+    "visualize-repo",
+];
 function hiddenBuiltInSkillTargets(options) {
     return new Set((options.hiddenBuiltInSkillTargets ?? []).map((target) => target.trim().toLowerCase()));
 }
@@ -4289,7 +4438,7 @@ function resolveSelectedSkillTargets(selected, options) {
         throw new Error(`Unknown skill: ${raw}. Run "npx @agent-native/core@latest skills list".`);
     }
     const out = [];
-    const planSubskills = ["visual-plan", "visual-recap"];
+    const planSubskills = ["visual-plan", "visual-recap", "visualize-repo"];
     const selectedPlanSubskills = planSubskills.filter((skill) => builtInSelections.includes(skill));
     if (selectedPlanSubskills.length === planSubskills.length) {
         out.push("visual-plans");
@@ -4961,7 +5110,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
     const baseDir = options.baseDir ?? process.cwd();
     if (isLocalOnlyBuiltInSkill(knownBuiltIn)) {
         if (parsed.planMode) {
-            throw new Error("--mode only applies to visual-plan / visual-recap / content.");
+            throw new Error("--mode only applies to visual-plan / visual-recap / visualize-repo / content.");
         }
         if (parsed.mcpUrl) {
             throw new Error("Context X-Ray is installed locally and does not use --mcp-url yet.");
@@ -5031,7 +5180,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
                     : undefined))
         : undefined;
     if (parsed.planMode && !modeAwareTargetId) {
-        throw new Error("--mode only applies to visual-plan / visual-recap / content.");
+        throw new Error("--mode only applies to visual-plan / visual-recap / visualize-repo / content.");
     }
     if (planMode === "local-files" && parsed.mcpUrl) {
         throw new Error("--mode local-files cannot be combined with --mcp-url.");
@@ -5402,6 +5551,9 @@ function instructionContentForSkill(skillName) {
     if (skillName === "visual-recap") {
         return "When a PR, branch, commit, or diff needs an interactive visual recap, use the /visual-recap skill always.";
     }
+    if (skillName === "visualize-repo") {
+        return "When a repository needs local visual docs or a navigable Plan-backed repo viewer, use the /visualize-repo skill always.";
+    }
     return null;
 }
 function selectedPlainSkillNamesForInstructionPrompt(targets, parsed) {
@@ -5590,7 +5742,7 @@ export async function runSkills(argv, options = {}) {
         const includesInstallModeSkills = targetsIncludeInstallModeSkills(targets) ||
             installModeSkillNamesSelected(parsed.plainSkillNames);
         if (parsed.planMode && !includesInstallModeSkills) {
-            throw new Error("--mode only applies to visual-plan / visual-recap / content.");
+            throw new Error("--mode only applies to visual-plan / visual-recap / visualize-repo / content.");
         }
         if (includesPlans) {
             if (!parsed.planMode && parsed.mcpUrl) {