@agent-native/core 0.44.3 → 0.45.0

package/docs/content/plan-plugin.md

@@ -14,7 +14,24 @@ One install gives you:
 - **Two skills** — `/visual-plan` (the canonical entry point) and `/visual-recap`.
 - **The Plan MCP connector** — registered against the hosted app at `https://plan.agent-native.com` (MCP endpoint `https://plan.agent-native.com/_agent-native/mcp`, server name `agent-native-plans`).
 
-Both skills **always publish to the hosted Plan app** — they create a plan via the MCP connector and hand you a link or inline plan to review. They never dump an inline Markdown/ASCII plan into chat as the deliverable. If a Plan tool returns `needs auth`, `Unauthorized`, or `Session terminated`, authenticate the connector (see each route below) instead of falling back to inline output.
+By default, both skills publish to the hosted Plan app — they create a plan via
+the MCP connector and hand you a link or inline plan to review. They never dump
+an inline Markdown/ASCII plan into chat as the deliverable. If a Plan tool
+returns `needs auth`, `Unauthorized`, or `Session terminated`, authenticate the
+connector (see each route below) instead of falling back to inline output.
+
+The exception is explicit **local-files privacy mode**. When you ask for no DB
+writes or set `AGENT_NATIVE_PLANS_MODE=local-files`, the skills must not call
+the Plan MCP connector. They write `plans/<slug>/plan.mdx` plus optional
+`canvas.mdx`, `prototype.mdx`, and `.plan-state.json`, then preview locally with:
+
+```bash
+agent-native plan local preview --dir plans/<slug> --kind plan
+```
+
+This keeps plan content out of the Agent-Native Plan database. Hosted sharing,
+comments, screenshots, and plan history are unavailable until you explicitly
+publish later.
 
 > The plugin (`agent-native-visual-plans`) carries app id `visual-plans`, which is why the Claude Code plugin name and Codex plugin name are both `agent-native-visual-plans`. The Plan app's display name is "Agent-Native Plan".
 

package/docs/content/pr-visual-recap.md

@@ -1,26 +1,28 @@
 ---
 title: "PR Visual Recap"
-description: "A GitHub Action that runs your repo's visual-recap skill on every PR. An LLM coding agent reads the diff, publishes an interactive recap plan, and posts it as a sticky PR comment with an inline screenshot. Informational and non-blocking."
+description: "A GitHub Action that runs your repo's visual-recap skill on every PR. An LLM coding agent reads the diff, publishes an interactive recap plan, shows an informational check, and posts a sticky PR comment with an inline screenshot. Informational and non-blocking."
 ---
 
 # PR Visual Recap
 
-PR Visual Recap is a GitHub Action that turns every pull request into a **visual code review**. On each push, an LLM coding agent runs your repo's [`visual-recap`](/docs/template-plan) skill against the PR diff, publishes a structured recap plan to the hosted Plans app, and upserts **one sticky PR comment** that links to the interactive plan with an **inline screenshot** embedded right in the comment.
+PR Visual Recap is a GitHub Action that turns every pull request into a **visual code review**. On each push, an LLM coding agent runs your repo's [`visual-recap`](/docs/template-plan) skill against the PR diff, publishes a structured recap plan to the hosted Plans app, shows an informational `Visual Recap` check while it runs, and upserts **one sticky PR comment** that links to the interactive plan with an **inline screenshot** embedded right in the comment.
 
 This is not a deterministic diff renderer. The action invokes a real coding agent (Claude Code CLI by default, or OpenAI Codex CLI) that reads the change, decides what matters, and authors the recap by calling the Plans MCP tool `create-visual-recap` — the same tool the `/visual-recap` slash command uses. You get a high-altitude, schema/API/before-after view of the change instead of a wall of raw diff.
 
-The recap is **informational and non-blocking**. It is not a required check, it never blocks the PR, and it never replaces reading the actual diff. The sticky comment is a review aid, not a sign-off.
+The recap is **informational and non-blocking**. It creates a check row so reviewers can see that generation is in progress, but it is not a required check, it never blocks the PR, and it never replaces reading the actual diff. The sticky comment is a review aid, not a sign-off.
 
 ## What it does
 
 On each PR push, the workflow:
 
 1. Collects a bounded diff between the PR base and head.
-2. Runs the configured coding agent against that diff. The agent reads your repo's `visual-recap` skill and authors a recap, publishing it with `create-visual-recap`.
-3. Reads the published plan URL the agent wrote to `recap-url.txt`.
-4. Opens that URL in headless Chrome and screenshots the rendered plan.
-5. Uploads the PNG to a signed public image route on the Plans app.
-6. Upserts a single sticky PR comment that embeds the screenshot **inline** (served through GitHub's camo image proxy) next to the link to the interactive recap.
+2. Creates an informational `Visual Recap` GitHub check with `Review in progress`.
+3. Runs the configured coding agent against that diff. The agent reads your repo's `visual-recap` skill and authors a recap, publishing it with `create-visual-recap`.
+4. Reads the published plan URL the agent wrote to `recap-url.txt`.
+5. Opens that URL in headless Chrome and screenshots the rendered plan.
+6. Uploads the PNG to a signed public image route on the Plans app.
+7. Upserts a single sticky PR comment that embeds the screenshot **inline** (served through GitHub's camo image proxy) next to the link to the interactive recap.
+8. Completes the `Visual Recap` check as success, skipped, or neutral.
 
 A re-push updates the same plan and the same sticky comment in place — no orphaned plans, no comment spam.
 
@@ -89,12 +91,37 @@ The workflow uses the plain `pull_request` trigger, **not** `pull_request_target
 
 This also means you can merge the workflow file **before** the secrets exist: with no token configured, every run is a quiet no-op until you set the secrets.
 
+## Local-files privacy mode
+
+The GitHub Action is designed for hosted, shareable PR review. If you want a
+recap without sending recap content to the Agent-Native Plan database, run the
+same helper flow locally in local-files mode instead:
+
+```bash
+agent-native recap collect-diff --base main --head HEAD --out recap.diff --stat recap.stat
+agent-native recap scan --diff recap.diff
+agent-native recap build-prompt --pr 123 --diff recap.diff --stat recap.stat --local-files --local-dir plans/pr-123-visual-recap
+```
+
+Give the generated `recap-prompt.md` to your coding agent. In local-files mode
+the prompt instructs the agent to write `plans/pr-123-visual-recap/plan.mdx`
+plus optional visual files and then run:
+
+```bash
+agent-native plan local preview --dir plans/pr-123-visual-recap --kind recap
+```
+
+The returned `file://` preview, or `/local-plans/pr-123-visual-recap` in a local
+Plan app using the same `PLAN_LOCAL_DIR`, is the review link. This mode disables
+the hosted sticky PR comment, inline screenshot upload, usage attachment, and
+browser comments until you explicitly publish.
+
 ## It's informational, not a gate
 
 The recap is a review aid layered on top of the normal PR flow:
 
-- It is **never a required check** and never blocks merging.
-- A generation or publish failure surfaces as an explanatory sticky comment, not a red X on unrelated code.
+- It shows a `Visual Recap` check row for visibility, but it is **never a required check** and never blocks merging.
+- A generation or publish failure completes neutrally and surfaces as an explanatory sticky comment, not a red X on unrelated code.
 - The recap and its screenshot **do not imply the diff has been reviewed**. Reviewers still need to read the actual changed lines.
 
 ## Related

package/docs/content/template-plan.md

@@ -162,6 +162,47 @@ Sharing and commenting are the workflows that need an account:
 The hosted Plans connector lives at `https://plan.agent-native.com/_agent-native/mcp`.
 Never put shared secrets in skill files.
 
+## Local-files privacy mode {#local-files}
+
+For privacy-focused work, ask for local-files mode:
+
+```text
+Use /visual-plan in local-files mode. Do not write this plan to the Plan DB.
+```
+
+or set the convention for your agent environment:
+
+```bash
+export AGENT_NATIVE_PLANS_MODE=local-files
+```
+
+In this mode the agent writes a local MDX folder under `plans/<slug>/` and must
+not call the hosted Plan MCP tools. The durable files are:
+
+- `plan.mdx`
+- optional `canvas.mdx`
+- optional `prototype.mdx`
+- optional `.plan-state.json`
+
+After writing the folder, the agent validates and previews it locally:
+
+```bash
+agent-native plan local preview --dir plans/<slug> --kind plan
+```
+
+If you run the Plan app locally with the same `PLAN_LOCAL_DIR`, you can open the
+read-only app route:
+
+```text
+http://localhost:<port>/local-plans/<slug>
+```
+
+Local-files mode prevents plan or recap content from going to the Agent-Native
+Plan database. It also disables hosted sharing, browser comments, plan history,
+and publish/export receipts until you explicitly opt into publishing. It does
+not automatically make your coding agent's LLM local; choose a local or approved
+model if that privacy boundary matters too.
+
 ## Useful prompts
 
 - "Use `/visual-plan` before changing the auth flow."
@@ -169,6 +210,7 @@ Never put shared secrets in skill files.
 - "Use `/visual-plan` on the Markdown plan below and make it easier to review."
 - "Run `/visual-recap` on this PR so I can review the shape of the change first."
 - "Use `/visual-recap` on the diff between `main` and this branch."
+- "Use `/visual-recap` in local-files mode so no recap content is written to the Plan DB."
 
 ## Recovering from auth errors {#auth-errors}
 
@@ -205,7 +247,9 @@ persistence, or running a fully self-hosted review surface.
 For fully offline, no-account use, you can run the Plans app locally and sync
 your plans to your repo as MDX. This local mode is a separate, advanced path —
 not the default hosted flow — and is best when you need everything to stay on
-your machine and in version control.
+your machine and in version control. For the stricter no-DB path, use
+[local-files privacy mode](#local-files), which reads from MDX folders instead
+of creating local SQL rows.
 
 ## What's next
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.44.3",
+  "version": "0.45.0",
   "type": "module",
   "engines": {
     "node": ">=22"

package/src/templates/workspace-core/.agents/skills/external-agents/SKILL.md

@@ -95,9 +95,9 @@ For local stdio proxying, Codex/Cowork compatibility, or clients without
 remote MCP OAuth, use the hosted connect fallback:
 
 ```bash
-npx @agent-native/core connect https://dispatch.agent-native.com
+npx @agent-native/core@latest connect https://dispatch.agent-native.com
 # or, for an isolated app:
-npx @agent-native/core connect https://mail.agent-native.com
+npx @agent-native/core@latest connect https://mail.agent-native.com
 ```
 
 The command opens the app in the browser, the user clicks **Authorize**, and a
@@ -111,6 +111,19 @@ Claude bearer-token entry is the migration path: the CLI replaces
 `Authorization` headers with URL-only OAuth config and tells the user to
 authenticate from `/mcp`.
 
+To re-authenticate an already-installed local/fallback client without
+reinstalling skills or connectors, use:
+
+```bash
+npx @agent-native/core@latest reconnect https://dispatch.agent-native.com --client codex
+# or:
+npx @agent-native/core@latest connect reconnect https://dispatch.agent-native.com --client codex
+```
+
+With no URL, `reconnect` searches the selected client config for the existing
+Agent Native MCP entry. Pass `--name <serverName>` when the config has multiple
+entries or a custom server name.
+
 Under the hood: a logged-in browser session mints an `A2A_SECRET`-signed JWT
 carrying the caller's `sub` + `org_domain` and a unique `jti`, so tool runs
 stay tenant-scoped via `runWithRequestContext`. The existing
@@ -339,14 +352,17 @@ and mutating actions are filtered out (`filterPublicAgentActions`). The full
 surface appears when authenticated as a real caller: a deployed /
 `AGENT_MODE=production` app, or a local app reached through `connect` /
 `agent-native mcp install` (which provisions an identity-bearing token). A
-sparse `tools/list` means you are hitting an unauthenticated dev endpoint —
-connect or present a token rather than assuming the action is missing.
+sparse or empty `tools/list` is diagnostic, not proof of auth failure: check
+OAuth scopes, compact-catalog filtering, and the client/server auth status
+before telling the user they are unauthenticated.
 
 ## Do
 
 - Do connect local/fallback clients to Dispatch with
-  `npx @agent-native/core connect https://dispatch.agent-native.com`; use a
-  direct app URL only when the host should be isolated to one app.
+  `npx @agent-native/core@latest connect https://dispatch.agent-native.com`;
+  use `npx @agent-native/core@latest reconnect ...` for reauth without
+  reinstalling; use a direct app URL only when the host should be isolated to
+  one app.
 - Do add a `link` builder to any action that produces or lists a navigable
   resource (draft, event, dashboard, document).
 - Do add `mcpApp` when a UI-capable MCP host should render an inline review or