@agent-native/core 0.113.0 → 0.114.1

package/src/cli/plan-publish-store.ts

@@ -0,0 +1,138 @@
+/**
+ * Canonical publish-token store for the local Plans server.
+ *
+ * `agent-native connect <hosted-url>` mints a bearer token and writes it into
+ * each coding agent's per-client MCP config (`.mcp.json` / Codex `config.toml`
+ * via `mcp-config-writers`). Those files are client-specific, so the local Plans
+ * server cannot read them for a server-to-server publish.
+ *
+ * To close that seam, the connect flow ALSO writes a single canonical record to
+ * `~/.agent-native/plan-publish.json` whenever it authenticates a first-party
+ * Plans app. The local server's `publish-visual-plan` action reads the exact
+ * same file (see `templates/plan/server/lib/plan-publish.ts`):
+ *
+ *   { "url": "https://plan.agent-native.com", "token": "<bearer>" }
+ *
+ * This mirrors the existing device-token precedent in
+ * `code-agent-connector.ts` (`~/.agent-native/remote-device.json`): home-dir
+ * JSON, env-overridable path, atomic 0600 write. The write is additive — it
+ * merges into any existing file rather than clobbering sibling keys — and
+ * best-effort, since persisting MCP config is the primary contract and a failed
+ * canonical write must never fail the connect.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** Matches the env override read by `templates/plan/server/lib/plan-publish.ts`. */
+const CONFIG_PATH_ENV = "PLAN_PUBLISH_CONFIG_PATH";
+
+/**
+ * Absolute path to the canonical publish-token file. Honors
+ * `PLAN_PUBLISH_CONFIG_PATH` so connect and the local server agree on the
+ * location in tests and custom setups; defaults to
+ * `~/.agent-native/plan-publish.json`.
+ */
+export function planPublishConfigPath(): string {
+  return path.resolve(
+    process.env[CONFIG_PATH_ENV] ??
+      path.join(os.homedir(), ".agent-native", "plan-publish.json"),
+  );
+}
+
+/**
+ * Whether `url`'s host is the first-party Agent-Native Plans app whose token
+ * we should mirror to the canonical publish file. Only the hosted Plans app
+ * (`plan.agent-native.com`) qualifies — mirroring tokens for other
+ * agent-native subdomains (assets, mail, …) would silently overwrite the
+ * canonical Plans endpoint with the wrong URL+token each time `connect --all`
+ * runs last-write-wins. A custom self-hosted origin (ngrok, localhost, a
+ * private deployment) is intentionally excluded: the user can still point the
+ * server at it via `PLAN_PUBLISH_URL` / `PLAN_PUBLISH_TOKEN` env vars.
+ */
+export function isFirstPartyPlanHost(url: string): boolean {
+  try {
+    const host = new URL(url).hostname.toLowerCase();
+    return host === "plan.agent-native.com";
+  } catch {
+    return false;
+  }
+}
+
+function stripTrailingSlash(url: string): string {
+  return url.replace(/\/+$/, "");
+}
+
+/**
+ * Merge `{ url, token }` into the canonical publish file without clobbering any
+ * other keys the file already holds. Best-effort: returns the written path on
+ * success, or `null` if the write failed or the inputs were unusable.
+ *
+ * `filePath` is injectable for tests; production callers omit it and get the
+ * env-overridable home-dir path.
+ */
+export function writePlanPublishAuth(
+  params: { url: string; token: string },
+  filePath: string = planPublishConfigPath(),
+): string | null {
+  const url = stripTrailingSlash((params.url ?? "").trim());
+  const token = (params.token ?? "").trim();
+  if (!url || !token) return null;
+
+  try {
+    let existing: Record<string, unknown> = {};
+    try {
+      const raw = JSON.parse(fs.readFileSync(filePath, "utf-8")) as unknown;
+      if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+        existing = raw as Record<string, unknown>;
+      }
+    } catch {
+      // No existing file (or unreadable/corrupt) — start fresh.
+    }
+
+    const merged = {
+      ...existing,
+      url,
+      token,
+      updatedAt: new Date().toISOString(),
+    };
+
+    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const tmp = `${filePath}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(merged, null, 2) + "\n", {
+      mode: 0o600,
+    });
+    fs.renameSync(tmp, filePath);
+    return filePath;
+  } catch {
+    // Best-effort: the per-client MCP config is the primary write. A failed
+    // canonical write must never fail the connect flow.
+    return null;
+  }
+}
+
+/**
+ * Read the canonical Plans publish auth written by `agent-native connect`.
+ * Returns `null` for missing/corrupt/incomplete files so callers can treat the
+ * publish token as optional and guide the user to reconnect.
+ */
+export function readPlanPublishAuth(
+  filePath: string = planPublishConfigPath(),
+): { url: string; token: string } | null {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8")) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return null;
+    }
+    const record = parsed as Record<string, unknown>;
+    const urlValue = record.url ?? record.baseUrl ?? record.hostedUrl;
+    const tokenValue = record.token ?? record.accessToken ?? record.bearerToken;
+    const url = typeof urlValue === "string" ? urlValue.trim() : "";
+    const token = typeof tokenValue === "string" ? tokenValue.trim() : "";
+    if (!url || !token) return null;
+    return { url: stripTrailingSlash(url), token };
+  } catch {
+    return null;
+  }
+}

package/src/cli/pr-visual-recap-workflow.ts

@@ -0,0 +1,2 @@
+/** Compatibility re-export for the workflow bundled by the recap CLI package. */
+export { PR_VISUAL_RECAP_WORKFLOW_YML } from "@agent-native/recap-cli";

package/src/cli/recap.ts

@@ -0,0 +1,5 @@
+/**
+ * Compatibility re-export for the recap CLI, which now lives in its own
+ * dependency-light package so CI does not install the full framework graph.
+ */
+export * from "@agent-native/recap-cli";

package/src/cli/setup-agents.ts

@@ -0,0 +1,120 @@
+import fs from "fs";
+import path from "path";
+
+/**
+ * Symlink definitions for agent tool discovery.
+ * Each entry maps a symlink path (relative to the project root) to its target.
+ */
+const FILE_SYMLINKS: Array<{ link: string; target: string }> = [
+  { link: "CLAUDE.md", target: "AGENTS.md" },
+];
+
+const DIR_SYMLINKS: Array<{ link: string; target: string }> = [
+  { link: ".claude/skills", target: "../.agents/skills" },
+];
+
+/**
+ * Create symlinks for all supported agent tools (Claude, Cursor, Windsurf, etc.).
+ * Idempotent — skips existing correct symlinks and user-customized files.
+ */
+export function setupAgentSymlinks(targetDir: string): void {
+  // File symlinks (CLAUDE.md, .cursorrules, .windsurfrules → AGENTS.md)
+  for (const { link, target } of FILE_SYMLINKS) {
+    const linkPath = path.join(targetDir, link);
+    const targetPath = path.join(targetDir, target);
+
+    // Skip if the target doesn't exist
+    if (!fs.existsSync(targetPath)) continue;
+
+    try {
+      const stat = fs.lstatSync(linkPath);
+      if (stat.isSymbolicLink()) {
+        const existing = fs.readlinkSync(linkPath);
+        if (existing === target) continue; // Already correct
+        // Wrong target — remove and recreate
+        fs.unlinkSync(linkPath);
+      } else {
+        // Real file exists — don't overwrite user customizations
+        continue;
+      }
+    } catch {
+      // lstatSync threw ENOENT — file doesn't exist, proceed to create
+    }
+
+    try {
+      fs.symlinkSync(target, linkPath);
+    } catch {
+      // On Windows or restricted environments, copy instead
+      try {
+        fs.copyFileSync(targetPath, linkPath);
+      } catch {
+        // Skip silently if copy also fails
+      }
+    }
+  }
+
+  // Directory symlinks (.claude/skills → ../.agents/skills)
+  for (const { link, target } of DIR_SYMLINKS) {
+    const linkPath = path.join(targetDir, link);
+    const parentDir = path.dirname(linkPath);
+    const absTarget = path.resolve(parentDir, target);
+
+    // Skip if the target directory doesn't exist
+    if (!fs.existsSync(absTarget)) continue;
+
+    // Ensure parent directory exists
+    fs.mkdirSync(parentDir, { recursive: true });
+
+    if (fs.existsSync(linkPath)) {
+      try {
+        const stat = fs.lstatSync(linkPath);
+        if (stat.isSymbolicLink()) {
+          const existing = fs.readlinkSync(linkPath);
+          if (existing === target) continue; // Already correct
+        } else {
+          continue; // Real directory — don't overwrite
+        }
+      } catch {
+        // Proceed to create
+      }
+    }
+
+    const type = process.platform === "win32" ? "junction" : "dir";
+    try {
+      fs.symlinkSync(target, linkPath, type);
+    } catch {
+      try {
+        copyDir(absTarget, linkPath);
+      } catch {
+        // Skip silently
+      }
+    }
+  }
+}
+
+function copyDir(src: string, dest: string): void {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(s, d);
+    } else {
+      fs.copyFileSync(s, d);
+    }
+  }
+}
+
+/**
+ * CLI entry point for `agent-native setup-agents`.
+ * Runs in the current working directory.
+ */
+export function runSetupAgents(): void {
+  const dir = process.cwd();
+  if (!fs.existsSync(path.join(dir, "AGENTS.md"))) {
+    console.log("No AGENTS.md found in current directory. Skipping.");
+    return;
+  }
+  setupAgentSymlinks(dir);
+  console.log("Agent tool symlinks configured.");
+}

package/src/cli/skills-content/assets-skill.ts

@@ -0,0 +1,83 @@
+export const ASSETS_SKILL_MD = `---
+name: assets
+description: >-
+  Use Assets for image or video generation requests, brand-safe media,
+  human picker UI, search/list/export actions, and cross-app asset selection.
+  Prefer this over generic image tools when installed.
+metadata:
+  visibility: exported
+---
+
+# Assets
+
+Use the Assets app when a workflow needs reusable brand media, a human picker,
+or generated image/video assets that another app can reference by ID and URL.
+When this skill is available, route plain image-generation requests here instead
+of using a generic image generator.
+
+## Choose The Path
+
+- Use \`open-asset-picker\` when a person should browse, search, generate, and
+  select an asset in UI. Pass \`mediaType: "image"\` by default, or
+  \`mediaType: "video"\` for video libraries. When the user asks to create a
+  specific image and choose the best option, pass \`prompt\`,
+  \`autoGenerate: true\`, and \`count: 3\` so the picker opens with candidates
+  to preview and select.
+- Use unattended actions when the agent already knows what to do:
+  \`search-assets\`, \`list-assets\`, \`generate-image\`,
+  \`generate-image-batch\`, \`generate-video\`,
+  \`refresh-generation-run\`, and \`export-asset\`.
+- Use browser/deep-link fallback when the host cannot render MCP Apps inline.
+  Surface the returned picker link. If it opens in a normal browser tab, have
+  the user select an asset there and paste back the copied handoff summary.
+  Treat Codex, Claude Code, and Claude Desktop Code as link-out hosts; do not
+  promise inline MCP App rendering there.
+  If the skill instructions are available but the MCP tool namespace has not
+  appeared yet, use the Assets browser fallback URL shape instead of switching
+  to a generic generator:
+  \`https://assets.agent-native.com/library?mediaType=image&prompt=...&autoGenerate=1&count=3\`.
+  When reporting the final selected image in Codex or Claude Code, include the
+  asset link and, if an inline preview is important, download the selected
+  \`previewUrl\`/\`downloadUrl\` to a local temp image and embed that absolute
+  local path. Remote CDN markdown images can fail to render in code-editor chat
+  surfaces.
+
+## Image And Video Workflows
+
+1. Pick or match the library with \`list-libraries\` or \`match-library\`.
+2. For images, call \`generate-image\` or \`generate-image-batch\`. Image
+   actions are synchronous: one batch call should return the finished image
+   candidates, so do not poll or regenerate unless a returned slot failed.
+3. For videos, call \`generate-video\` and poll \`refresh-generation-run\`
+   until the run completes.
+4. Preserve returned \`assetId\`, \`runId\`, \`previewUrl\`, \`downloadUrl\`,
+   media type, and dimensions so the caller can attach or embed the result.
+
+## Cross-App Use
+
+- Hosted default: connect \`https://assets.agent-native.com/mcp\`.
+  Do not put shared secrets in skill files.
+- For CLI/code-editor clients, keep any \`npx @agent-native/core@latest connect\` command
+  running until browser authorization finishes. Stopping it early can leave the
+  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 \`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.
+- If an Assets tool call returns \`Session terminated\`, \`needs auth\`, or
+  another connector/session error, do not keep retrying the tool. Stop and give
+  the user the reconnect step: in Claude Code run \`/mcp\` and choose
+  Authenticate/Reconnect for the Assets connector; from any terminal run
+  \`npx -y @agent-native/core@latest reconnect https://assets.agent-native.com\` — this
+  re-authenticates WITHOUT reinstalling. Never reinstall from scratch just to fix
+  auth. Continue once the connector is available.
+- Do not hand-roll MCP HTTP requests with curl from the agent session. Use the
+  host-exposed Assets tools after restart/reload, or use the returned
+  browser/deep-link fallback.
+- If a batch image generation request times out in browser fallback, retry with
+  \`count: 1\` only after telling the user the multi-candidate request timed out.
+- If you inspect local MCP config, redact \`Authorization\`, \`http_headers\`,
+  and token values. Never paste bearer tokens into chat or logs.
+`;

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

@@ -0,0 +1,153 @@
+// Canvas/artboard placement mechanics. Used only by visual-plan modes
+// (visual-recap renders standalone wireframes, not a canvas).
+export const CANVAS_SURFACE_CORE = `<!-- SHARED-CORE:canvas-surface START -->
+
+**The coordinate rule.** The \`surface\` locks each artboard's footprint and
+aspect — never set artboard width/height and never use coordinates inside the
+wireframe HTML; board-level artboard \`x\`/\`y\` IS allowed when it creates clear
+lanes. Let canvas auto-placement handle simple one-row boards.
+
+**Lay out mixed canvases in lanes.** When a canvas contains broad browser /
+desktop frames plus compact \`mobile\`, \`popover\`, or \`panel\` surfaces, do not put
+everything in one horizontal strip. Use board-level artboard \`x\`/\`y\` to reserve
+lanes with generous empty space: main flow on one row, compact surfaces in their
+own column or row, and loading/error states in a lower row. Keep at least 96px
+between rendered artboard rectangles plus room for annotation gutters; when a
+broad browser/desktop frame sits beside a compact panel/popover, leave at least
+160px so frame borders, labels, and hover controls never touch. Connect only
+neighboring steps; never draw a long connector that skips across unrelated
+frames. Connector labels must sit in open canvas space. If the label would touch
+or cross either artboard, remove the label and explain the transition with a
+nearby annotation instead. Before handoff, inspect the top canvas at default zoom
+and move any frame whose label, connector, or annotation crosses another frame.
+
+**Board-unit spacing defaults.** The canvas coordinate system uses approximately 2 board units per screen pixel. \`browser\` frames occupy roughly 700 × 600 board units; \`desktop\` frames roughly 900 × 700 board units. Apply these minimum x/y gaps when placing frames explicitly — any less and frames will touch or overlap:
+
+- x-gap between \`browser\` frames: **≥ 1100** (700-unit frame + 400-unit gutter)
+- x-gap between \`desktop\` frames: **≥ 1300** (900-unit frame + 400-unit gutter)
+- y-gap between rows of any surface: **≥ 1400** (includes frame height + section header + buffer)
+
+When in doubt, use larger values — the canvas auto-zooms to fit everything.
+
+**Canvas annotations are designer notes on the artboard.** When a top canvas is
+present, sprinkle design-review notes near the frames they explain: a short
+heading, supporting text, and bullets — plain text layers, never bordered or
+shadowed cards, and never a box around a frame. The renderer spaces notes away
+from frames, so place each note by the frame it describes. Use an arrow only to
+point at one specific control or transition; for a broad frame-level note, write
+text beside the frame with no connector. Connectors are for real sequences only —
+never fake "Step 1 → Step 2" lines between independent states.
+
+**Do not create overlapping annotations.** Anchor each ordinary note to the
+frame it explains with \`targetId\` + \`placement\` (top/right/bottom/left), and
+omit \`type\` or use \`type: "note"\`. The renderer parks notes in a gutter beside
+the frame and lays them out automatically. Do not use \`type: "callout"\`,
+\`type: "text"\`, \`type: "arrow"\`, x/y, or points for ordinary notes; those are
+freeform review-markup layers and must be reserved for intentional markup in
+open canvas space. Reserve arrows for a note that must point at one specific
+control inside a frame; a note that simply sits beside its frame needs no arrow.
+
+**Patching.** Edit one wireframe, canvas annotation, diagram, or block with targeted \`contentPatches\`
+(for example \`patch-wireframe-html\`, \`patch-diagram-html\`, \`update-block\`,
+\`replace-blocks\`, \`update-canvas-annotation\`) rather
+than regenerating the whole plan. \`contentPatches\` are part of the public MCP
+action schema, so Claude Code, Codex, Cursor, and other hosts can make surgical
+edits. If an agent is working from exported source files, use
+\`read-visual-plan-source\` / \`patch-visual-plan-source\`: \`plan.mdx\` holds
+frontmatter plus markdown/document blocks, \`canvas.mdx\` holds
+\`<DesignBoard>/<Section>/<Artboard>/<Screen>/<Annotation>/<Connector>\`, and the
+patch action normalizes the MDX back into the same JSON runtime model. JSON is
+the canonical runtime shape; MDX is the repo-friendly authoring/export surface.
+In the browser, humans edit \`rich-text\` prose inline; agents should still use
+\`update-rich-text\` content patches or source patches for prose, and use
+comments/structured patches for canvas, artboard, wireframe, and diagram edits.
+Never send a partial top-level \`content\` object as a shortcut to add a canvas,
+frame, or block: \`content\` is a full structured replacement, so omitted blocks
+or surfaces can disappear. If a full replacement is truly unavoidable, read the
+complete source/JSON first, include every existing block and surface in the new
+payload, and verify the source/export immediately after the update.
+
+**Never emit a titled artboard with no interior wireframe content.** Every artboard
+you place on the canvas must carry an \`html\` wireframe or reference a wireframe
+block via \`blockId\`; when using \`blockId\`, the referenced \`wireframe\` /
+\`legacy-wireframe\` block must remain in the plan. If you remove a duplicate
+wireframe from the document body, first move its \`data\` inline onto the
+corresponding \`content.canvas.frames[*].wireframe\` / \`legacyWireframe\`. A
+label-only frame or a frame pointing at a deleted block renders empty and is
+rejected at parse time. If you only have a title, write it as a section header or
+annotation, not an empty artboard.
+
+**UI mockups belong in the top visual review area.** Static UI/product visuals
+live on the canvas; multi-step UI flows get both canvas wireframes and a
+prototype. When the user asks for a mockup, UI state, loading state, layout,
+screen, or visual comparison, make the canvas the primary home for that static
+visual. When the user asks for a prototype or the plan contains a sequence the
+reviewer must feel, keep the canvas artboards and add \`content.prototype\` so the
+top surface shows Wireframes / Prototype tabs. Architecture/code diagrams stay
+inline in the document (the SKILL.md Visual Surface Choice section owns that
+rule) unless the user explicitly asks for a spatial board. Document blocks
+can explain, compare, or map implementation, but they should not host the
+primary UI mockup or prototype just because \`custom-html\`, screenshots, or prose
+are easier to produce. If the canvas/prototype surface cannot represent the
+requested UI fidelity, still keep the closest top-surface representation and
+call out or extend the needed renderer capability. A skeleton/loading mockup
+also lives in a canvas artboard — never move a mockup out of the canvas.
+
+**Storyboards are canvas artifacts, not document diagrams.** When the requested
+output is a product flow, onboarding journey, "light storyboard", or canvas
+wireframe, author the flow as multiple top-canvas artboards with real screen
+content and neighboring connectors. Keep document-body \`diagram\` blocks for
+architecture and mechanics that are not themselves user-visible screens. A
+storyboard made from a single inline HTML diagram is the wrong surface.
+
+For abstract product concepts, use the canvas to create the first "I get it"
+moment: one real app state near the top showing how the concept appears to a
+user, followed by separate annotations or diagrams for mechanics. Do not make
+the first artboard a hybrid of app UI and architecture notes; the app screen
+should be inspectable as product UI on its own.
+
+**Legacy kit tree.** Older plans set a \`screen\` array of \`{ el, ...props }\` kit
+nodes instead of \`html\`; the renderer still accepts and displays it so saved
+plans round-trip, but new plans emit \`html\`. Do not author fresh kit-tree
+screens, and do not put nested kit components such as \`<FrameScreen>\`, \`<Card>\`,
+\`<Row>\`, \`<Title>\`, or \`<Btn>\` inside a canvas \`<Screen>\`. A new canvas artboard
+with kit-tree children is a defect: replace it with
+\`<Screen surface="..." html={...} />\` using the HTML wireframe rules. The HTML
+path is the one that gets the renderer-owned surface sizing, theme tokens,
+sketch/clean toggle, and safe text layout used by good document-body
+wireframes. Likewise, old or imported plans may carry coordinate-based regions
+or free-float x/y on notes; those are legacy escape hatches the renderer still
+shows but you must never produce. The gutter parks notes by \`targetId\` +
+\`placement\`, and the coordinate rule at the top of this file governs all
+new-plan placement.
+
+<!-- SHARED-CORE:canvas-surface END -->`;
+
+// Progressive-disclosure reference files. Like `WIREFRAME_REFERENCE_MD`, each of
+// the canvas / document-quality / exemplar cores is the single source of truth
+// for its topic and is materialized verbatim into a sibling `references/*.md`
+// file in the visual-plan skill dir instead of being interpolated inline into
+// the SKILL.md body. The body carries only the matching `*_REFERENCE_POINTER`.
+// Keeping each reference body byte-identical to its core (markers included) lets
+// the sync guard assert the on-disk copies never drift from the constant.
+export const CANVAS_REFERENCE_MD = `# Canvas & artboard placement — single source of truth
+
+This file is the canonical guide for how the visual-plan canvas works: artboard
+placement, lane layout, annotations, patching, and the legacy kit tree. Read it
+in full before authoring or editing any canvas/artboard content; do not author
+canvas layouts from memory or paraphrase these rules per mode.
+
+${CANVAS_SURFACE_CORE}
+`;
+
+// Short pointers that replace the inline canvas / document-quality / exemplar
+// cores in the SKILL.md body. Authoring detail lives in the sibling reference
+// files so the SKILL.md stays lean (progressive disclosure); the agent loads the
+// detail on demand.
+export const CANVAS_REFERENCE_POINTER = `The canvas is the single source of truth for static UI mockups: the \`surface\`
+locks each artboard's footprint, mixed surfaces lay out
+in lanes, annotations are plain-text designer notes anchored by
+\`targetId\`/\`placement\`, and edits are surgical \`contentPatches\`. Before
+authoring or editing ANY canvas, artboard, or annotation, READ
+\`references/canvas.md\` in this skill directory — it is the single source of truth
+for canvas/artboard mechanics. Do not author canvas layouts from memory.`;

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

@@ -0,0 +1,52 @@
+export const CONNECTION_REFERENCE_MD = `# Connecting & publishing — single source of truth
+
+This file is the canonical rule for the never-inline deliverable, finding the
+Plan MCP connector, and restoring it when its tools are missing. It is shared
+word for word by \`/visual-plan\` and \`/visual-recap\`. Read it when you are about
+to publish, or whenever a connector or auth error appears; do not improvise an
+inline fallback from memory.
+
+<!-- SHARED-CORE:connection START -->
+
+**The deliverable is ALWAYS a published Agent-Native Plan, never inline chat
+content.** Do not hand the plan or recap to the user as Markdown prose, an ASCII
+sketch, a table, a fenced "wireframe", or a "here's the summary" paragraph. The
+entire value is the hosted, interactive, annotatable Plan; an inline summary is
+the thing a Plan replaces, not a degraded version of one. The only supported
+output is to publish through the Plan MCP connector and return its absolute URL.
+Local-files privacy mode (\`references/local-files.md\`) is the one exception.
+
+**The connector is usually the \`plan\` server**, but older installed agents may
+expose the same hosted connector as \`agent-native-plans\` — both names are valid,
+so never report the connector as missing just because it is named
+\`agent-native-plans\` instead of \`plan\`. Some clients also lazy-load connector
+tools through a deferred tool registry instead of showing the namespace upfront.
+Before declaring the connector missing, search/load tools with the host's
+discovery surface (\`tool_search\` when available) for \`create_visual_plan\`,
+\`create_visual_recap\`, or \`get_plan_blocks\`, then use the tools it exposes.
+
+**If the tools are still missing after discovery, do NOT fall back to inline
+output.** The usual cause is a connector that did not finish connecting this
+session (it registers zero tools), NOT necessarily an auth problem — so do not
+assume the user must re-authenticate. Stop and give the user the exact restore
+step for their current client:
+
+- **Codex / Codex Desktop:** run
+  \`npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex\`
+  and start a new Codex session.
+- **Claude Code:** run \`/mcp\` and choose Authenticate/Reconnect, or run the same
+  reconnect command with \`--client claude-code\` and restart Claude.
+
+The same applies when a Plan tool returns \`needs auth\`, \`Unauthorized\`, or
+\`Session terminated\`: stop retrying the tool and give the reconnect step instead.
+
+Auth is stored per client config/session, so one client's reconnect does not make
+another running client load tools. \`--client all\` refreshes every local client
+config that already has the Plan entry, but each running client still has to
+reload its MCP tools afterward. Reconnect re-authenticates WITHOUT reinstalling
+and finds the entry by URL regardless of connector name — never reinstall from
+scratch just to fix auth. Publish once the tool is reachable. Falling back to
+inline content is a defect, not a degraded mode.
+
+<!-- SHARED-CORE:connection END -->
+`;