@agent-native/core 0.45.0 → 0.46.0

package/dist/templates/workspace-core/.agents/skills/real-time-collab/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: real-time-collab
 description: >-
-  Multi-user collaborative editing with Yjs CRDT and live cursors. Use when
-  adding real-time collaborative editing to a template, debugging sync issues,
-  or understanding how the agent and humans edit documents simultaneously.
+  Multi-user collaborative editing with Yjs CRDT, SSE fast-path transport, and
+  granular server-side merge. Use when adding real-time collaborative editing to
+  a template, debugging sync issues, or understanding how the agent and humans
+  edit documents simultaneously.
 metadata:
   internal: true
 ---
@@ -12,39 +13,57 @@ metadata:
 
 ## Rule
 
-Collaborative editing uses Yjs CRDT via TipTap. The agent and human users are equal participants — both edit the same Y.Doc and changes merge cleanly without conflicts.
+Collaborative editing uses Yjs CRDT via TipTap. The agent and human users are
+equal participants — both edit the same Y.Doc and changes merge cleanly without
+conflicts. Always set `resourceType` on `createCollabPlugin`.
 
 ## How It Works
 
 - **`Y.Doc`** stores the document as a `Y.XmlFragment` (ProseMirror node tree)
-- **TipTap's Collaboration extension** binds the editor to the Y.XmlFragment via `ySyncPlugin`
-- **CollaborationCaret extension** renders remote users' cursors with names and colors
-- **Polling** (every 2s) syncs Y.Doc updates and awareness state between clients and server
-- **SQL `_collab_docs` table** persists Yjs state as base64-encoded binary (works across SQLite/Postgres)
+- **TipTap's Collaboration extension** binds the editor to the Y.XmlFragment
+  via `ySyncPlugin`
+- **CollaborationCaret extension** renders remote users' cursors with names and
+  colors
+- **SSE fast-path** — `/_agent-native/poll-events` `EventSource` delivers collab
+  events push-style; while SSE is healthy the collab poll interval relaxes to
+  ~12 s
+- **Polling fallback** — `/_agent-native/poll` is polled every 2 s when SSE is
+  unavailable; this is the universal serverless fallback
+- **Update batching** — local Yjs updates are debounced ~80 ms and coalesced
+  with `Y.mergeUpdates` before sending; flushed immediately on
+  `visibilitychange` / `pagehide`
+- **SQL `_collab_docs` table** persists Yjs state as base64 (SQLite/Postgres
+  compatible). Tombstone compaction fires automatically when the stored blob
+  exceeds 4× the fresh encoded size.
 
 ## Agent + Human Editing
 
 1. **Human edits** → TipTap → ySyncPlugin → Y.XmlFragment → `POST /_agent-native/collab/:docId/update`
 2. **Agent edits** → action edits canonical SQL content + bumps `updatedAt` → change-sync refetch → the open editor reconciles the new content into the live Y.Doc (see below) → poll update → all clients
 
-Both produce Yjs operations that merge cleanly. Agent edits appear without destroying cursor position, selection, or undo history.
+Both produce Yjs operations that merge cleanly. Agent edits appear without
+destroying cursor position, selection, or undo history.
 
-This is how content (documents) and slides now work. The agent does **not** push edits into Yjs in-process, and it does **not** call any `findCollabOrigin()` / localhost probe — that approach silently no-op'd on serverless (the action runs in a different process), so agent edits didn't show up live until the user navigated away and back. Nor does it search-and-replace inside existing Y.XmlText nodes, which could never create new block structure (lists, headings, tables). The peer-editor model below replaces both.
+The agent does **not** push edits into Yjs in-process and does **not** call any
+localhost probe — those approaches silently no-op on serverless (the action runs
+in a different process). The peer-editor model below replaced them.
 
 ## Agent Edits As A Real-Time Peer Editor
 
-The agent edits documents the same way a human collaborator does: its change lands in the shared Y.Doc, propagates to every connected client, and persists. It gets there without any in-process Yjs push from the action.
+**SQL is the durable source of truth for document body content.** The agent
+action edits the canonical content column and bumps `updatedAt`. No localhost
+calls, no in-process Yjs mutation.
 
-**SQL is the durable source of truth for document body content.** The agent action edits the canonical content (e.g. `documents.content`) and bumps `updatedAt`. That's the whole server side — no localhost calls, no Yjs mutation from the action.
-
-**The open editor reconciles authoritative external content into the live Y.Doc.** The action's `updatedAt` bump flows through the change-sync system (see `real-time-sync`), which refetches the record. The editor applies the new content through its real markdown/HTML pipeline via `setContent`, so new block structure (lists, headings, tables) renders correctly and merges with concurrent human edits through the Yjs CRDT diff. The result: the agent's edit propagates to every connected client and persists, exactly like a human collaborator's edit.
+**The open editor reconciles authoritative external content into the live
+Y.Doc.** The `updatedAt` bump flows through change-sync, which refetches the
+record. The lead client applies the new content via `setContent`, producing Yjs
+operations that merge with concurrent human edits. Every connected client
+receives the result through normal Yjs sync.
 
 ### The `updatedAt` gate
 
-The editor only adopts content that is genuinely **newer** than what it already reflects. An older-or-equal `updatedAt` is a lagging poll or a stale snapshot and is **ignored**.
-
 ```ts
-// Pseudocode in the editor's reconcile effect
+// In the editor's reconcile effect
 if (loaded.updatedAt > lastAppliedUpdatedAt.current) {
   applyAuthoritativeContent(loaded.content); // adopt
   lastAppliedUpdatedAt.current = loaded.updatedAt;
@@ -52,56 +71,107 @@ if (loaded.updatedAt > lastAppliedUpdatedAt.current) {
 // else: lagging poll / stale snapshot → ignore
 ```
 
-**Why:** without the gate, a slightly-behind poll response re-applies old content right after the agent's edit, so the edit "reverts on the next poll" / "doesn't show until refresh" — the whack-a-mole we kept hitting. A **fresh mount or doc-switch has no baseline**, so it always adopts whatever content it loaded — which is why a manual refresh is always correct.
+Without the gate, a slightly-behind poll response re-applies old content and
+the edit "reverts on next poll". A fresh mount always adopts whatever content
+it loaded.
 
 ### Lead-client election
 
-Exactly ONE connected client applies an authoritative snapshot into the shared Y.Doc; the rest receive it through normal Yjs sync. The lead is the present client with the lowest Yjs `clientID`, decided by the core helper:
+Exactly ONE connected client applies the authoritative snapshot; the rest
+receive it through Yjs sync:
 
 ```ts
 import { isReconcileLeadClient } from "@agent-native/core/client";
 
 if (
   loaded.updatedAt > lastAppliedUpdatedAt.current &&
-  isReconcileLeadClient(provider.awareness, ydoc.clientID)
+  isReconcileLeadClient(awareness, ydoc.clientID)
 ) {
   applyAuthoritativeContent(loaded.content);
 }
 ```
 
-**Why:** if every open editor independently diffed the same snapshot into the CRDT, each would insert the changed region at the same position, duplicating it N times (concurrent inserts → duplicated text). Electing one lead avoids that. The agent's awareness id (`AGENT_CLIENT_ID`, max int) can never win, and a client editing alone is always the lead. The election is deterministic across clients with no coordination round-trip.
+The agent's awareness entry (`AGENT_CLIENT_ID`, max int) can never be the
+lead. A sole client is always the lead. The election is deterministic with no
+coordination round-trip.
 
 ### v1 limitation
 
-A full-content reconcile is **last-writer-wins for the rare case** where a human has unsaved edits in the exact region the agent simultaneously rewrites — the agent's snapshot can clobber that in-flight human edit. Inline and structural edits in **different** regions merge fine through the CRDT; only same-region simultaneous rewrites are at risk.
+Full-content reconcile is **last-writer-wins** for the rare case where a human
+has unsaved edits in the exact region the agent simultaneously rewrites. Edits
+in **different** regions merge fine through the CRDT.
+
+## Security
+
+### Always set `resourceType`
+
+```ts
+// server/plugins/collab.ts
+import { createCollabPlugin } from "@agent-native/core/server";
+
+export default createCollabPlugin({
+  table: "documents",
+  contentColumn: "content",
+  idColumn: "id",
+  resourceType: "document", // required
+});
+```
+
+Without `resourceType`, the server logs a one-time warning and collab push
+events are delivered to **all authenticated users** without document-level
+scoping. Set it to the resource type name registered via
+`registerShareableResource`.
+
+Non-owner sharees who have explicit access fall back to state-vector catch-up
+(safe, slightly higher latency). Awareness routes require the same viewer
+access as read routes.
+
+### Payload limits
+
+Write routes reject payloads exceeding `maxPayloadBytes` (default 2 MB) with
+HTTP 413. Override:
+
+```ts
+createCollabPlugin({ resourceType: "document", maxPayloadBytes: 512 * 1024 });
+```
 
 ## Enabling Collaboration
 
 ### 1. Install packages
 
 ```bash
-pnpm add @tiptap/extension-collaboration @tiptap/extension-collaboration-caret @tiptap/y-tiptap
+pnpm add @tiptap/extension-collaboration @tiptap/extension-collaboration-caret @tiptap/y-tiptap @tiptap/core
 ```
 
-### 2. Add collab server plugin
+### 2. Add collab server plugin (with `resourceType`)
 
 ```ts
 // server/plugins/collab.ts
-import { createCollabPlugin } from "@agent-native/core/collab";
+import { createCollabPlugin } from "@agent-native/core/server";
 
 export default createCollabPlugin({
   table: "documents",
   contentColumn: "content",
   idColumn: "id",
+  resourceType: "document",
 });
 ```
 
 ### 3. Use the client hook
 
 ```ts
-import { useCollaborativeDoc } from "@agent-native/core/client";
-
-const { ydoc, provider } = useCollaborativeDoc(documentId);
+import { useCollaborativeDoc, emailToColor, emailToName } from "@agent-native/core/client";
+
+const { ydoc, awareness, activeUsers, agentActive, agentPresent } =
+  useCollaborativeDoc({
+    docId: documentId,
+    requestSource: TAB_ID,
+    user: {
+      name: emailToName(session.email),
+      email: session.email,
+      color: emailToColor(session.email),
+    },
+  });
 ```
 
 ### 4. Add TipTap extensions
@@ -112,12 +182,14 @@ import { CollaborationCaret } from "@tiptap/extension-collaboration-caret";
 
 const editor = useEditor({
   extensions: [
+    StarterKit.configure({ history: false }), // Yjs handles undo
     Collaboration.configure({ document: ydoc }),
     CollaborationCaret.configure({
-      provider,
+      provider: { awareness },
       user: { name: session.email, color: "#6366f1" },
     }),
   ],
+  // Do NOT pass content — Yjs owns it
 });
 ```
 
@@ -126,6 +198,9 @@ const editor = useEditor({
 ```ts
 optimizeDeps: {
   include: [
+    "yjs",
+    "y-protocols/awareness",
+    "@tiptap/core",
     "@tiptap/extension-collaboration",
     "@tiptap/extension-collaboration-caret",
     "@tiptap/y-tiptap",
@@ -137,22 +212,95 @@ optimizeDeps: {
 
 | Route | Purpose |
 | ----- | ------- |
-| `GET /_agent-native/collab/:docId/state` | Fetch full Y.Doc state |
+| `GET /_agent-native/collab/:docId/state` | Fetch full Y.Doc state (accepts `?stateVector=` for diff) |
 | `POST /_agent-native/collab/:docId/update` | Apply client Yjs update |
 | `POST /_agent-native/collab/:docId/text` | Apply full text (diff-based) |
 | `POST /_agent-native/collab/:docId/search-replace` | Surgical find/replace in Y.XmlFragment |
+| `POST /_agent-native/collab/:docId/json` | Apply full JSON diff to Y.Map/Y.Array |
+| `GET /_agent-native/collab/:docId/json` | Read current JSON state |
+| `POST /_agent-native/collab/:docId/patch` | Surgical JSON patch ops |
 | `POST /_agent-native/collab/:docId/awareness` | Sync cursor/presence state |
 | `GET /_agent-native/collab/:docId/users` | List active users |
 
+## Granular Server-Side Merge Pattern
+
+For structured documents (slides, forms, design files) where body collab would
+cause LWW conflicts at the container level, use **granular server-side merge**:
+define an action with targeted per-item operations.
+
+**When to use granular merge vs body collab:**
+
+| Scenario | Recommended approach |
+| -------- | -------------------- |
+| Free-form rich text, cursor-level CRDT matters | Body collab (Y.XmlFragment + TipTap) |
+| Structured items (slides, fields) where different users edit different items | Granular server-side merge (action with patch ops) |
+
+Example operation shape for slides:
+
+```ts
+type PatchDeckOp =
+  | { type: "patch"; slideId: string; fields: Partial<SlideFields> }
+  | { type: "add"; position: number; slide: SlideData }
+  | { type: "delete"; slideId: string }
+  | { type: "reorder"; slideId: string; newIndex: number };
+```
+
+Concurrent edits to different slides both succeed at the action level; there
+is no whole-deck LWW. Forms use the same shape with field-level ops.
+
+## Collaborative Undo Scoping (Y.UndoManager)
+
+Scope undo/redo to the local user's own edits so peer and agent changes are
+never accidentally reversed:
+
+```ts
+import * as Y from "yjs";
+
+const LOCAL_EDIT_ORIGIN = "local";
+
+const undoManager = new Y.UndoManager(ydoc.getText("content"), {
+  trackedOrigins: new Set([LOCAL_EDIT_ORIGIN]),
+  captureTimeout: 800, // coalesces rapid slider drags into one undo step
+});
+
+// Mark local edits with the tracked origin
+ydoc.transact(() => {
+  // apply local change
+}, LOCAL_EDIT_ORIGIN);
+
+undoManager.undo(); // only reverses LOCAL_EDIT_ORIGIN transactions
+undoManager.redo();
+```
+
+Rules:
+- Pass a `Set` to `trackedOrigins` — not an array.
+- Remote (`"remote"`) and agent (`"agent"`) origins are never captured.
+- Recreate and destroy the manager when the active document changes.
+
 ## Common Pitfalls
 
-- **Don't pass `content` as a TipTap prop** when Collaboration is enabled — Yjs owns the content. Set initial content via the Y.Doc instead.
-- **Don't call `editor.setContent()` ad hoc for agent edits.** The only sanctioned `setContent` is the editor's reconcile path described above — gated by `updatedAt` and guarded by `isReconcileLeadClient`. Calling it from elsewhere (e.g. on every poll, or from every client) re-applies stale content or duplicates the changed region across the CRDT.
-- **Add packages to `optimizeDeps`** — Vite won't pre-bundle Yjs packages correctly otherwise, causing runtime errors in dev.
-- **One `Y.Doc` per document** — Don't create multiple Y.Doc instances for the same document ID. Use the `useCollaborativeDoc` hook which caches by ID.
+- **Missing `resourceType`** — The server logs a warning on startup and
+  delivers collab events to all authenticated users without access scoping.
+  Always set `resourceType`.
+- **Don't pass `content` as a TipTap prop** when Collaboration is enabled —
+  Yjs owns the content. Seed via `editor.commands.setContent()` only when the
+  Y.XmlFragment is empty.
+- **Don't call `editor.setContent()` ad hoc for agent edits** — the only
+  sanctioned `setContent` is gated by `updatedAt` and guarded by
+  `isReconcileLeadClient`. Calling it from elsewhere duplicates content across
+  the CRDT or re-applies stale snapshots.
+- **Add packages to `optimizeDeps`** — Vite won't pre-bundle Yjs correctly
+  otherwise, causing runtime errors in dev.
+- **One `Y.Doc` per document** — Don't create multiple Y.Doc instances for the
+  same document ID. `useCollaborativeDoc` caches by ID.
+- **Destroy Y.UndoManager on doc change** — Stale managers hold Y.Doc
+  references and grow unboundedly. Recreate on `docId` change.
 
 ## Related Skills
 
-- `real-time-sync` — The change-sync system that delivers the `updatedAt` bump driving editor reconciliation; also `useReconciledState` for non-collaborative "copy a server value into local edit state" surfaces
-- `storing-data` — The `_collab_docs` table where Yjs state is persisted; SQL holds the canonical document body that the editor reconciles from
-- `self-modifying-code` — Agent edits to collaborative documents edit canonical SQL content, not raw Yjs
+- `real-time-sync` — The change-sync system that delivers the `updatedAt` bump
+  driving editor reconciliation; also `useReconciledState` for non-Yjs surfaces
+- `storing-data` — The `_collab_docs` table and SQL canonical content
+- `security` — `registerShareableResource`, `resolveAccess`, `assertAccess`
+- `self-modifying-code` — Agent edits to collaborative documents edit canonical
+  SQL content, not raw Yjs

package/dist/templates/workspace-core/.agents/skills/real-time-sync/SKILL.md

@@ -49,7 +49,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
 
    For list/sidebar queries, use the same pattern — pass the counter into the queryKey of every list query you want to keep fresh.
 
-4. **Fallback** polling calls `/_agent-native/poll?since=N`. It runs every 2 seconds until SSE is connected, then relaxes to 15 seconds. If SSE is disabled or unavailable, polling continues at the normal cadence.
+4. **Fallback** polling calls `/_agent-native/poll?since=N`. It runs every 2 seconds until SSE is connected, then relaxes to 15 seconds (`SSE_FALLBACK_INTERVAL_MS`). If SSE is disabled or unavailable (e.g., edge/serverless deployments), polling continues at the 2 s cadence. Polling is the universal serverless fallback — it detects DB timestamp changes even when the write happened in a different process or invocation.
 
 5. When the agent writes to the database, the version increments, SSE/polling detects it, and React Query refetches the affected queries.
 
@@ -196,6 +196,16 @@ const [title, setTitle] = useReconciledState(props.title, { active: isEditing })
 | Local edit state copied from a server value (inputs, popovers, inline editors) | `useReconciledState(externalValue, { active })` |
 | Collaborative rich-text editor (Yjs) | `updatedAt`-gated reconcile + `isReconcileLeadClient` — see `real-time-collab` |
 
+## Granular server-side merge for non-body fields
+
+For structured documents (slide decks, form builders, design files) where the
+Yjs body collab would cause LWW conflicts at the container level, pair the
+change-sync `updatedAt` bump with a **granular server-side merge action** that
+accepts targeted per-item operations (add/patch/delete/reorder). Concurrent
+edits to different items both survive at the action level; the `collab` source
+version bump then propagates the merged state to all open clients. See
+`real-time-collab` for the pattern and examples.
+
 ## Related Skills
 
 - **storing-data** — Application-state and settings are data stores that sync through change events
@@ -203,4 +213,4 @@ const [title, setTitle] = useReconciledState(props.title, { active: isEditing })
 - **actions** — Mutating actions trigger change events
 - **client-methods** — Route details belong in helpers/hooks, not components
 - **self-modifying-code** — Agent code edits trigger change events; rapid edits can cause event storms
-- **real-time-collab** — Collaborative editors reconcile agent edits into a shared Y.Doc, driven by the same change-sync `updatedAt` bump
+- **real-time-collab** — Collaborative editors reconcile agent edits into a shared Y.Doc, driven by the same change-sync `updatedAt` bump; also the granular server-side merge pattern for structured data

package/docs/content/plan-plugin.md

@@ -12,7 +12,7 @@ The Agent-Native **Plan** app ships as one installable bundle. A single install
 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`).
+- **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 `plan`, with legacy alias `agent-native-plans` during migration).
 
 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
@@ -49,14 +49,27 @@ npx @agent-native/core@latest skills add visual-plan
 agent-native skills add visual-plan
 ```
 
-This installs `visual-plan` plus the companion `visual-recap` skill, then registers the `agent-native-plans` connector and runs auth (OAuth prompt for hosted/account-backed sharing). Useful flags:
+This installs `visual-plan` plus the companion `visual-recap` skill, then registers the `plan` connector and its legacy `agent-native-plans` alias, then runs auth (OAuth prompt for hosted/account-backed sharing). Useful flags:
 
 - `--client codex|claude-code|claude-code-cli|cowork|all` — which local agents to write the MCP config for (default `codex`).
 - `--no-connect` — register the connector without authenticating; run `agent-native connect https://plan.agent-native.com` later.
 - `--mcp-url <url>` — point the connector at a custom origin (an ngrok tunnel, a local dev server, or a self-hosted deployment) instead of the hosted default.
 - `--with-github-action` — also write the PR Visual Recap GitHub Action (see [PR Visual Recap](/docs/pr-visual-recap)).
 
-After it finishes, restart or reload the agent client so the new skills and tools load, then run `/visual-plan`.
+Interactive installs also offer the PR Visual Recap Action when no workflow is
+present. Say yes to add it during skill setup, or run the command above later
+with `--with-github-action`. After the workflow is written, run:
+
+```bash
+agent-native recap setup
+agent-native recap doctor
+```
+
+`recap setup` configures the GitHub Action secrets and variables where possible,
+and `recap doctor` verifies the workflow, local publish token, GitHub repo
+access, and required Actions configuration. After install finishes, restart or
+reload the agent client so the new skills and tools load, then run
+`/visual-plan`.
 
 > Note: the bare `npx skills add BuilderIO/agent-native --skill visual-plan` (Vercel/open Skills CLI) installs **instructions only** — it does not register the MCP connector. Use the Agent-Native CLI above when you want the connector wired up too.
 
@@ -82,10 +95,12 @@ The same repo is a Codex plugin marketplace. Add it, install the plugin, then au
 ```bash
 codex plugin marketplace add BuilderIO/agent-native
 codex plugin add agent-native-visual-plans@agent-native-apps
-codex mcp login agent-native-plans   # OAuth in the browser
+codex mcp login plan   # OAuth in the browser
+# Existing installs may already be authenticated as:
+codex mcp login agent-native-plans
 ```
 
-After install, **start a new Codex thread** so the skills and MCP tools load into the session. The plugin ships a URL-only connector (`[mcp_servers.agent-native-plans]` → `https://plan.agent-native.com/_agent-native/mcp`); `codex mcp login` runs the OAuth flow. The universal CLI route above also works for Codex (`agent-native skills add visual-plan --client codex`) if you prefer one command that installs and authenticates together.
+After install, **start a new Codex thread** so the skills and MCP tools load into the session. The plugin ships URL-only connectors (`[mcp_servers.plan]` and legacy `[mcp_servers.agent-native-plans]` → `https://plan.agent-native.com/_agent-native/mcp`); `codex mcp login` runs the OAuth flow. The universal CLI route above also works for Codex (`agent-native skills add visual-plan --client codex`) if you prefer one command that installs and authenticates together.
 
 ## Updates {#updates}
 
@@ -93,7 +108,7 @@ The plugin routes auto-update — you do not re-pack or re-add the marketplace f
 
 - **Claude Code** — the marketplace entry sets `autoUpdate: true` and the plugin uses commit-SHA versioning, so Claude Code pulls new versions from the repo at startup; run `/reload-plugins` to activate. Every push to the repo's default branch reaches installed users automatically.
 - **Codex** — the plugin `version` embeds a content hash of the bundled skills and MCP endpoint (e.g. `1.0.0+codex.<hash>`), so any skill or endpoint change yields a new version. Codex's startup auto-upgrade re-installs configured git marketplaces on its own; just **start a new thread** to pick up the change. No manual `codex plugin marketplace upgrade` is needed for routine updates.
-- **Universal CLI route** — re-run `npx @agent-native/core@latest skills add visual-plan` to refresh the skills and re-register the connector. `@latest` always pulls the current skills from the published `@agent-native/core` package.
+- **Universal CLI route** — run `npx @agent-native/core@latest skills status visual-plan` to check copied skill folders, or `npx @agent-native/core@latest skills update visual-plan` to refresh them in place. Re-running `skills add visual-plan` still works when you also want to re-register/authenticate the connector. `@latest` always pulls the current skills from the published `@agent-native/core` package.
 
 The connector points at a **hosted** app, so the Plan app's actions and live tool surface always reflect the deployed version regardless of when you installed; only the bundled skill instructions follow the update mechanisms above.
 

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

@@ -28,13 +28,34 @@ A re-push updates the same plan and the same sticky comment in place — no orph
 
 ## Installing it
 
-The Agent-Native CLI writes the workflow into your repository and prints the secrets to set:
+When you install Plans interactively, the Agent-Native CLI asks whether to add
+automatic PR Visual Recaps. Say yes to write the GitHub Action, or add it
+explicitly at any time:
 
 ```bash
 agent-native skills add visual-plan --with-github-action
 ```
 
-This installs the `visual-plan` skill (which includes the `visual-recap` skill the action runs) and writes `.github/workflows/pr-visual-recap.yml` into your repo. The workflow calls **published CLI subcommands** — `agent-native recap scan|build-prompt|shot|comment` — so nothing is copied into your repo as helper scripts. Commit the generated workflow file, set the secrets below, and open a PR to see it run.
+This installs the `visual-plan` skill (which includes the `visual-recap` skill the action runs) and writes `.github/workflows/pr-visual-recap.yml` into your repo. The workflow calls **published CLI subcommands** — `agent-native recap scan|build-prompt|shot|comment` — so nothing is copied into your repo as helper scripts.
+
+Then run the guided setup helper:
+
+```bash
+agent-native recap setup
+agent-native recap doctor
+```
+
+`recap setup` refreshes the workflow, uses `gh` to set GitHub Actions
+secrets/variables when values are available from env or the local Plans
+publish-token store, and prints exact missing commands for anything it cannot
+set. Secret values are sent to `gh` through stdin, not command arguments. Commit
+the generated workflow file and open a PR to see it run.
+
+By default, the workflow builds its agent prompt from the latest bundled
+`visual-recap` guidance in `@agent-native/core@latest`, including any sibling
+reference files the skill ships with. If your repo intentionally customizes and
+pins its committed `visual-recap` folder, set the repository variable
+`VISUAL_RECAP_SKILL_SOURCE=repo`.
 
 ## Backend selection
 
@@ -53,6 +74,7 @@ Beyond the backend, two repository variables tune _how_ the agent runs:
 
 - **`VISUAL_RECAP_MODEL`** pins the model passed to the CLI (`--model`) — for example `gpt-5.5` for Codex, or a Claude model id. Leave it unset to use the CLI's own default model.
 - **`VISUAL_RECAP_REASONING`** sets the reasoning depth: `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. It applies to the Codex backend; Claude's reasoning is model-driven, so this variable is ignored there.
+- **`VISUAL_RECAP_SKILL_SOURCE`** controls prompt freshness: `auto`/unset uses the latest bundled skill guidance, while `repo` pins to the committed repo-local `visual-recap` skill folder.
 
 For example, to run the recap on Codex with GPT-5.5 at high reasoning, set the repository variables `VISUAL_RECAP_AGENT=codex`, `VISUAL_RECAP_MODEL=gpt-5.5`, and `VISUAL_RECAP_REASONING=high`.
 
@@ -67,7 +89,18 @@ Set these in your repository's **Settings → Secrets and variables → Actions*
 | `PLAN_RECAP_TOKEN`  | Per-user, revocable token minted by `agent-native connect`. Authorizes publishing the recap plan and the screenshot upload. |
 | `ANTHROPIC_API_KEY` | The LLM key for the default Claude Code backend.                                                                            |
 
-Mint `PLAN_RECAP_TOKEN` with `agent-native connect` against your Plans app, then paste the printed token into the secret. Use a placeholder like `plan_recap_xxxxxxxxxxxxxxxx` only for examples — never commit a real token.
+Mint `PLAN_RECAP_TOKEN` with `agent-native connect` against your Plans app. For
+the hosted app, this also writes a local publish-token file that
+`agent-native recap setup` can read:
+
+```bash
+agent-native connect https://plan.agent-native.com --client codex
+agent-native recap setup
+```
+
+If you prefer manual setup, paste the token into the GitHub secret. Use a
+placeholder like `plan_recap_xxxxxxxxxxxxxxxx` only for examples — never commit a
+real token.
 
 ### Optional (only if you change defaults)
 
@@ -91,6 +124,22 @@ 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.
 
+## Self-modifying guard (sensitive paths)
+
+The workflow's gate job skips the recap entirely if a PR touches any of the following paths, so a PR can never rewrite what the trusted recap job runs and exfiltrate secrets:
+
+| Path pattern                               | Reason                                                    |
+| ------------------------------------------ | --------------------------------------------------------- |
+| `.github/workflows/pr-visual-recap.yml`    | The workflow itself                                       |
+| `**/skills/visual-(recap\|plan\|plans)/**` | The visual-recap skill the agent follows                  |
+| `**/.claude/**`                            | Agent settings the runner loads                           |
+| `**/CLAUDE.md`                             | Agent instructions the runner loads                       |
+| `**/AGENTS.md`                             | Agent instructions the runner loads                       |
+| `**/.mcp.json`                             | MCP server config the runner loads                        |
+| `packages/core/**`                         | Recap CLI source _(BuilderIO/agent-native monorepo only)_ |
+
+The `packages/core/**` rule applies only in the `BuilderIO/agent-native` monorepo where `packages/core` is the recap CLI source. In consumer repos an unrelated `packages/core/` directory does not trigger the guard.
+
 ## Local-files privacy mode
 
 The GitHub Action is designed for hosted, shareable PR review. If you want a