@agent-native/core 0.113.0 → 0.114.0

package/src/cli/skills-content/exemplar.ts

@@ -0,0 +1,69 @@
+export const EXEMPLAR_CORE = `<!-- SHARED-CORE:exemplar START -->
+
+**GOOD.** A UI-first plan for a todo app: a canvas with a \`desktop\` artboard whose
+\`data.html\` is a real flex layout — a sidebar of links (\`Inbox 12\`, \`Today 4\`,
+\`Done\`), a main column with an \`<h1>Today</h1>\`, accent \`.wf-pill\`s for the
+filters, a muted section label \`OVERDUE\`, and \`.wf-card\` task rows carrying real
+titles, due dates, and a primary \`button.primary\` — styled only through bare
+elements, helper classes, and \`--wf-*\` tokens, so the renderer applies the
+correct desktop footprint, theme, and one subtle whole-frame wobble. Plain-text
+designer notes sit spaced off the frame, pointing only at the controls that need
+explanation. Below it, a Claude/Codex-grade document: objective and
+done-criteria, a few \`code\` blocks (grouped in a vertical \`tabs\` block when
+more than one) showing the real shape of the load-bearing files, a \`callout\`
+with \`tone="decision"\` stating the chosen approach with a \`columns\` block
+weighing the two real options behind it,
+and a validation step — none of it repeating the canvas. If the task also
+changes a multi-step completion flow, the same top area includes a Prototype tab
+whose screens use the same labels and states as the canvas artboards, with
+\`data-goto\` controls for the sequence. This is the bar.
+
+**GOOD.** A broad product-architecture plan opens with a plain recommendation
+and one concrete app state before the abstraction. The first canvas artboard is
+pure product UI that matches the current app shell; nearby notes explain the
+user-visible delta. A separate diagram below shows the mechanics, such as file
+or data flow. The document then separates the reusable core from app/provider
+adapters and examples, covers contracts, folder or schema shape, sync
+boundaries, roadmap, non-goals, a bottom Open Questions form for unresolved
+decisions, and a verification section with at least one realistic end-to-end
+smoke. A reviewer who was not in the chat gets the idea from the top snapshot
+before reading the technical plan.
+
+**GOOD.** A \`/visual-plan\` for a backend architecture review: no top canvas.
+The document opens with context and a legend, then repeats recommendation cards:
+title, confidence/category badges, a monospace grid of real file paths, one
+inline two-dimensional before/after or layered architecture diagram, and terse
+Problem/Solution/Why bullets using the codebase's vocabulary. The diagram uses
+space to show boundaries, layers, and ownership; it is not a default
+left-to-right chain. The plan ends with a top recommendation and a bottom
+question-form only if the next architecture direction is genuinely open. This is
+better than a top canvas because each diagram is local to the claim it supports.
+
+**BAD.** A \`data.html\` with hard-coded hex colors, a \`font-family\`, or fixed
+pixel width/height; gray placeholder bars "insinuating" text on a non-skeleton
+frame; a forced desktop + mobile pair for a popover; floating bordered
+annotation cards hugging the frames; a fresh hand-authored kit-tree \`screen\`
+instead of \`html\`; a multi-step UI flow with only static frames and no prototype
+tab; a mockup escaped into a document \`custom-html\` block; and a marketing-style
+document with a hero heading and value props that just restates what the canvas
+already shows. Also bad: an architecture-only plan forced into a top canvas of
+labeled boxes with overlapping text, where the actual code evidence and
+recommendations live elsewhere; a product wireframe that mixes a real screen
+with repo names, file-contract arrows, architecture explanations, or a made-up
+permanent inspector; and a plan that describes itself as a revision of a prior
+conversation instead of a standalone proposal. Never produce this.
+
+<!-- SHARED-CORE:exemplar END -->`;
+
+export const EXEMPLAR_REFERENCE_MD = `# Good vs. bad exemplar — single source of truth
+
+This file is the canonical worked example of a great plan (and the anti-patterns
+to avoid). Read it alongside the document-quality and canvas references before
+authoring a plan; it is the bar these plans must clear.
+
+${EXEMPLAR_CORE}
+`;
+
+export const EXEMPLAR_REFERENCE_POINTER = `For a worked example of the bar — a great UI-first plan and \`/visual-plan\`, plus
+the anti-patterns to avoid — READ \`references/exemplar.md\` in this skill
+directory before authoring a plan.`;

package/src/cli/skills-content/help.ts

@@ -0,0 +1,77 @@
+export 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|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:
+  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-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
+  npx @agent-native/core@latest skills status visual-plan
+  npx @agent-native/core@latest skills update visual-plan
+  npx @agent-native/core@latest skills update scaffold --project
+  npx @agent-native/core@latest skills add visual-plan --no-connect
+  npx @agent-native/core@latest skills add context-xray --client all
+  npx @agent-native/core@latest skills add assets --client claude-code
+  npx @agent-native/core@latest skills add assets --mcp-url https://my-app.ngrok-free.dev
+  npx @agent-native/core@latest skills add ./dist/assets-skill --client codex
+  npx @agent-native/core@latest skills add BuilderIO/skills --client codex --scope project
+  npx @agent-native/core@latest skills add BuilderIO/skills --with-github-action
+
+The add command installs the SKILL.md instructions, registers the app-backed
+MCP connector, and then authenticates it in one step so you do not hit an OAuth
+wall on the first tool call. Hosted installs can configure Claude Code, Codex,
+Claude Cowork, Cursor, OpenCode, and GitHub Copilot / VS Code; local-files
+instruction installs target the shared .agents skill path used by Codex, Pi,
+Cursor, OpenCode, Copilot, and similar agents, plus Claude Code's native skill
+path when selected. Pass --client to narrow it. Authentication reuses
+"npx @agent-native/core@latest connect": OAuth-capable clients (Claude Code,
+Cursor, OpenCode, GitHub Copilot / VS Code) get URL-only entries and authenticate
+inside that host, while Codex / Cowork run the browser device-code flow. In a
+non-interactive shell or CI the auth step is skipped and the exact
+"npx @agent-native/core@latest connect <url> --client all" command is printed instead.
+
+Running "npx @agent-native/skills@latest add ..." uses this same shared install
+flow with the broader BuilderIO skills catalog enabled. Pass --no-connect to
+register MCP where possible without authenticating (leave auth to the host or run
+"npx @agent-native/core@latest connect" later). Pass --mcp-url to register that connector against
+a custom origin (an ngrok tunnel, a local dev server, or a self-hosted
+deployment) instead of the built-in hosted default — a bare origin gets the
+standard /mcp path appended. Use app-skill pack for marketplace
+bundles and custom adapter output.
+
+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.
+
+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
+verify GitHub Actions. Docs: https://www.agent-native.com/docs/pr-visual-recap.
+
+The status/update commands inspect copied Agent Native skill folders and refresh
+their instruction files from the current @agent-native/core package. In generated
+apps/workspaces, "skills update scaffold --project" refreshes the framework
+skills copied into the scaffold and repairs AGENTS.md / CLAUDE.md and
+.agents/skills / .claude/skills compatibility links.`;

package/src/cli/skills-content/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Barrel for the large embedded-markdown string constants used by
+ * `agent-native skills` (SKILL.md bodies, shared reference docs, and the CLI
+ * help text). Split out of `skills.ts` so that file can lead with real CLI
+ * logic instead of ~3,000 lines of data. Content is purely relocated here —
+ * no bytes were changed.
+ */
+export * from "./help.js";
+export * from "./assets-skill.js";
+export * from "./content-skill.js";
+export * from "./design-exploration-skill.js";
+export * from "./design-visual-edit-skill.js";
+export * from "./plan-setup-auth.js";
+export * from "./wireframe.js";
+export * from "./canvas.js";
+export * from "./document-quality.js";
+export * from "./exemplar.js";
+export * from "./connection.js";
+export * from "./local-files.js";
+export * from "./visual-plan-skill.js";
+export * from "./visual-recap-skill.js";
+export * from "./visualize-repo-skill.js";

package/src/cli/skills-content/local-files.ts

@@ -0,0 +1,100 @@
+export const LOCAL_FILES_REFERENCE_MD = `# Local-files privacy mode — single source of truth
+
+This file is the canonical contract for fully local, no-database planning and
+recaps. It is shared word for word by \`/visual-plan\` and \`/visual-recap\`. Read it
+in full before using local-files mode; do not call any hosted Plan tool for a
+local plan/recap except the schema-only block-catalog lookup described below.
+
+<!-- SHARED-CORE:local-files START -->
+
+**When to use it.** Use local-files privacy mode when the user explicitly asks
+for no DB writes, no hosted Plan database writes, no Plan MCP publish, fully local
+files, offline/private work, or repo-owned/source-controlled artifacts, or when
+\`AGENT_NATIVE_PLANS_MODE=local-files\` is set. Also use it when a user or repo
+policy says the work must stay under their own brand, domain, source control, or
+infrastructure. In this mode the plan/recap data must never be sent to the Plan
+MCP server or the Plan app action surface. This is the only exception to the
+always-publish rule in \`references/connection.md\`.
+
+The local-files contract:
+
+- **Read context locally.** Read source, diff, and stat context from local files
+  and shell commands only. For recaps, the
+  \`npx @agent-native/core@latest recap collect-diff\`, \`scan\`, and
+  \`build-prompt --local-files\` helpers are safe — they operate on local files and
+  do not write to the Plan database.
+- **Fetch the block catalog first** (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; it calls the public no-auth \`get-plan-blocks\` route.
+  Use \`--format schema\` when you need exact nested fields. If network access is
+  unavailable, use the bundled \`references/*.md\` and rely on \`plan local check\` to
+  catch invalid tags. Copy the catalog examples verbatim for the fields the
+  registry table cannot encode: \`checklist\` items need \`id\` and \`label\`;
+  \`question-form\` questions need \`id\`, \`title\`, and \`mode\`, and each option needs
+  \`id\` and \`label\`; and \`Code\` / \`AnnotatedCode\` / \`Diff\` are whitespace-sensitive
+  — encode multiline code as JSON string attributes such as \`code={"const x =\\n  y"}\`
+  (a static template literal is accepted only when it has no \`\${...}\`
+  interpolation). \`plan local check\` is a quick OFFLINE lint (a subset of the
+  renderer schema), so a green \`check\` does not guarantee the plan renders.
+  \`plan local verify\` also stays on-device: it uses the offline lint unless it
+  can reach a Plan renderer on an explicit loopback \`--app-url\`.
+- **Write a local MDX folder.** Use \`plans/<slug>/\` to check the artifact into the
+  repo, or a repo-ignored/temporary folder such as \`.agent-native/plans/<slug>/\`
+  or \`/tmp/agent-native-plans/<slug>/\` when it should not be checked in. The
+  folder holds \`plan.mdx\`, optional \`canvas.mdx\`, optional \`prototype.mdx\`, and
+  optional \`.plan-state.json\`. For a recap, set \`kind: "recap"\` and
+  \`localOnly: true\` in the frontmatter/state. Use that exact folder as
+  \`<plan-dir>\` in every command below.
+- **Check, then serve.** Run
+  \`npx @agent-native/core@latest plan local check --dir <plan-dir>\` before any
+  preview, then
+  \`npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind <plan|recap> --open\`
+  (use \`--kind plan\` for plans, \`--kind recap\` for recaps). Report the local
+  bridge URL from stdout or \`<plan-dir>/.plan-url\`; treat \`.plan-url\` as a local
+  token file and do not commit it. The URL opens the hosted Plan UI but reads from
+  the localhost bridge on this machine, so it is not shareable across machines.
+  The token is carried in the URL fragment (which is not sent to the hosted
+  origin), and the local-plan route disables DOM autocapture and session replay
+  while retaining sanitized pageviews and error monitoring. On
+  macOS \`--open\` prefers Chromium browsers; if Safari opens, switch to
+  Chrome/Chromium because Safari can block the hosted HTTPS page from fetching the
+  HTTP localhost bridge. If the Plan app itself is running locally with the same
+  \`PLAN_LOCAL_DIR\`, the \`/local-plans/<slug>\` route is also valid. In a truly
+  offline environment, hand off the \`<plan-dir>\` path after \`plan local check\` and
+  note that interactive preview requires network access to the hosted Plan UI or a
+  running local Plan app.
+- **Headless verify.** Run
+  \`npx @agent-native/core@latest plan local verify --dir <plan-dir> --kind <plan|recap>\`.
+  It starts the bridge and checks the private-network preflight and JSON payload
+  entirely on loopback. It never sends MDX or assets to a remote validation
+  action. When \`--app-url\` points to a loopback Plan app, verify also validates
+  against that local app's real renderer schema via \`validate-local-plan-source\`.
+  A non-\`ok\` result with
+  \`validation.valid: false\` lists the renderer's exact schema-path issues (e.g.
+  \`blocks[1].data.tabs[0]...\`); fix those before handing off. If \`validation.ran\`
+  is \`false\`, verify used the offline lint because the app URL was remote or the
+  local Plan app was unavailable. Run a local Plan app and pass
+  \`--app-url http://localhost:8096\` for the authoritative check. If the browser hangs on
+  "Loading plan", fetch the \`bridgeUrl\` from the verify/serve JSON to read the
+  concrete validation error.
+- **Never call hosted tools for that plan/recap.** Do not call
+  \`create-visual-plan\`, \`create-ui-plan\`, \`create-prototype-plan\`,
+  \`create-plan-design\`, \`create-visual-recap\`, \`create-visual-questions\`,
+  \`import-visual-plan-source\`, \`update-visual-plan\`, \`patch-visual-plan-source\`,
+  \`get-plan-feedback\`, \`export-visual-plan\`, \`set-resource-visibility\`, or any
+  other hosted Plan tool — except the schema-only block-catalog lookup above.
+- **Feedback is file/chat feedback.** Update the MDX files directly, rerun
+  \`plan local check\`, and rerun \`serve\` or \`verify\` when that preview path is
+  available. Summarize the new local URL when one exists; otherwise summarize the
+  checked \`<plan-dir>\` path. Hosted comments, sharing, screenshots, history, usage
+  attachment, and publish/export receipts are unavailable until the user
+  explicitly opts into publishing.
+
+Local-files mode prevents plan/recap content from being uploaded to the
+Agent-Native Plan server or database. It does not by itself make the coding agent's language model local;
+for that stronger boundary the host agent/model must also be local or otherwise
+approved by the user.
+
+<!-- SHARED-CORE:local-files END -->
+`;

package/src/cli/skills-content/plan-setup-auth.ts

@@ -0,0 +1,80 @@
+/**
+ * Setup/auth block for the `/visual-plan` skill. Interpolated into
+ * `VISUAL_PLANS_SKILL_MD` below so the install + one-step authenticate
+ * instructions are single-sourced. The materialized SKILL.md copies under
+ * `templates/plan/.agents/skills/*`, top-level `skills/*`, and
+ * `.agents/skills/*` are guarded byte-identical by `skills.sync.spec.ts`.
+ */
+export const PLAN_SETUP_AUTH_MD = `## Setup & Authentication
+
+There are two ways into Plans.
+
+**Coding agent (CLI).** Install once with the Agent-Native CLI. The command
+installs the Plans skills, registers the hosted Plans MCP connector, and runs
+auth/setup for the selected local client(s) in the same step (a one-time browser
+sign-in at setup — this is intended), so the first tool call in that client does
+not hit an OAuth wall:
+
+\`\`\`bash
+npx @agent-native/core@latest skills add visual-plans
+\`\`\`
+
+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
+authenticating, then run
+\`npx @agent-native/core@latest connect https://plan.agent-native.com --client all\`
+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-plans --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 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
+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.
+
+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 no-account, no-DB plan storage, use local-files mode and the local bridge
+command. The optional \`plan blocks\` lookup reads only public schema metadata.
+If network access is unavailable, use the bundled references and a local Plan
+app/runtime for validation.
+
+If a Plans tool returns \`needs auth\`, \`Unauthorized\`, or \`Session terminated\`,
+do not keep retrying the tool. Stop and give the user the reconnect step for the
+client they are using: Codex/Codex Desktop should run
+\`npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex\`
+and start a new Codex session; Claude Code should run \`/mcp\` and choose
+Authenticate/Reconnect for the plan connector, or run the reconnect command with
+\`--client claude-code\` and restart Claude. To refresh every local client config
+that already has the Plan entry, use \`--client all\`, then restart/reload each
+client. Reconnect re-authenticates WITHOUT reinstalling and finds the entry by
+URL regardless of connector name. Never reinstall from scratch just to fix auth.
+Continue once the connector is available.
+
+Hosted default: connect \`https://plan.agent-native.com/mcp\`. Do
+not put shared secrets in skill files.`;