@agent-native/core 0.122.4 → 0.123.0

package/docs/content/template-plan-local-and-desktop.mdx

@@ -0,0 +1,236 @@
+---
+title: "Local-Files Mode and Desktop Sync"
+description: "Keep Agent-Native Plan content out of the hosted database with local-files privacy mode and visualize-repo, or mirror a hosted plan's source to a folder with Agent Native Desktop."
+---
+
+# Local-Files Mode and Desktop Sync
+
+Some plans should never touch a shared database — a security review, an
+unreleased feature, or a repo you want the plan checked into directly. This
+page covers the two ways Plan content can live in files on disk instead of (or
+alongside) the hosted database, and how the two differ.
+
+## 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 and must not call the hosted
+Plan MCP tools. Use a repo folder such as `plans/<slug>/` when you want the plan
+checked in with the code. Use a temp or ignored folder, such as
+`/tmp/agent-native-plans/<slug>/` or `.agent-native/plans/<slug>/`, when the
+plan should stay out of git.
+
+<FileTree
+  id="doc-block-plan3"
+  title="Local plan folder shape"
+  entries={[
+    { path: "plan.mdx", note: "frontmatter plus markdown/document blocks" },
+    {
+      path: "canvas.mdx",
+      note: "optional — DesignBoard/Section/Artboard/Screen/Annotation/Connector markup",
+    },
+    {
+      path: "prototype.mdx",
+      note: "optional — Prototype/PrototypeScreen/PrototypeTransition markup",
+    },
+    {
+      path: ".plan-state.json",
+      note: "optional — source metadata for stable bare-Markdown block IDs",
+    },
+    {
+      path: "assets/",
+      note: "optional — local image assets referenced by the MDX",
+    },
+  ]}
+/>
+
+After writing the folder, the agent starts a tiny localhost bridge and opens the
+hosted Plan UI against that local-only source:
+
+```bash
+npx @agent-native/core@latest plan local check --dir plans/<slug>
+npx @agent-native/core@latest plan local serve --dir plans/<slug> --kind plan --open
+```
+
+The bridge URL looks like
+`https://plan.agent-native.com/local-plans/local-<opaque-id>#bridge=http://127.0.0.1:...`.
+The page is the normal Plan viewer, but the browser fetches `plan.mdx`,
+`canvas.mdx`, `prototype.mdx`, `.plan-state.json`, and local image assets from
+the localhost bridge. Plan content is not written to the hosted database and is
+not sent through hosted Plan actions. Keep the bridge process running while you
+review; the URL is local to your machine and is not a shareable team link. The
+serve command writes the open URL to `.plan-url` by default so coding agents can
+capture it without scraping long-running stdout; treat that file as local-only
+because the URL contains the bridge token, and do not commit it.
+
+On macOS, `--open` prefers Chrome/Chromium because Safari can block the hosted
+HTTPS Plan page from fetching an HTTP localhost bridge. For headless
+troubleshooting, run:
+
+```bash
+npx @agent-native/core@latest plan local verify --dir plans/<slug> --kind plan
+```
+
+`verify` starts the bridge, checks the private-network preflight and JSON
+payload, prints diagnostics, and exits.
+
+If you run the Plan app locally with the same `PLAN_LOCAL_DIR`, you can also
+open the editable app route:
+
+```text
+http://localhost:<port>/local-plans/<slug>
+```
+
+For repo-backed folders, the direct local route can carry the repo-relative
+folder path so browser edits keep writing to that folder:
+
+```text
+http://localhost:<port>/local-plans/<slug>?path=plans%2F<slug>
+```
+
+The Plan app uses `apps.plan.roots[0].path` in `agent-native.json` as the
+default repo location for promoted local plans, falling back to `plans/`:
+
+```json
+{
+  "version": 1,
+  "apps": {
+    "plan": {
+      "mode": "local-files",
+      "roots": [{ "name": "Plans", "path": "plans", "kind": "plans" }]
+    }
+  }
+}
+```
+
+Direct local Plan routes include a menu action to save a temporary local folder
+into that repo location. After promotion, the page reopens with `?path=...` and
+continues autosaving MDX edits to the repo folder.
+
+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.
+Local-files mode does not automatically make your coding agent's LLM local;
+choose a local or approved model if that privacy boundary matters too.
+
+## Promoting a local plan into the hosted database {#promote}
+
+To move a local plan into the hosted database, call `publish-visual-plan` with
+the local MDX folder path. This uploads the plan, assigns it a hosted ID,
+enables sharing and commenting, and returns the hosted URL — at that point the
+plan follows the normal [sharing and commenting rules](/docs/template-plan-review-workflow#sharing)
+like any other hosted plan.
+
+<Diagram id="doc-block-plan4" title="Three lanes for plan content" summary="Local-files mode and desktop sync both keep source in a folder, but only one of them skips the hosted database entirely.">
+
+```html
+<div class="diagram-lanes">
+  <div class="diagram-box">
+    Local-files mode<br /><small class="diagram-muted"
+      >MDX folder only — never in the Plan DB</small
+    >
+  </div>
+  <div class="diagram-box">
+    Desktop local sync<br /><small class="diagram-muted"
+      >Plan DB is the source of truth — folder is a mirror</small
+    >
+  </div>
+  <div class="diagram-panel center">
+    Hosted (default)<br /><small class="diagram-muted"
+      >SQL-backed — sharing, comments, history, live review</small
+    >
+  </div>
+</div>
+```
+
+```css
+.diagram-lanes {
+  display: flex;
+  align-items: stretch;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.diagram-lanes .diagram-box {
+  flex: 1;
+  min-width: 180px;
+}
+.diagram-lanes .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 4px;
+  text-align: center;
+  flex: 1;
+  min-width: 180px;
+}
+```
+
+</Diagram>
+
+## Repo visual docs {#visualize-repo}
+
+Use `/visualize-repo` when you want a durable visual documentation layer for a
+codebase instead of a one-off plan or recap. It creates or opens a local Plan
+MDX workspace, updates `agent-native.json` with an `apps.visualize-repo`
+local-files section, and serves the docs through the same localhost bridge:
+
+```bash
+npx @agent-native/core@latest visualize-repo --open
+```
+
+If no `agent-native.json` exists, the command bootstraps one and recommends a
+small starter set from the repo structure, such as `actions/`,
+`app/components/`, `app/pages/`, `server/db/schema.ts`, `src/`, `packages/`,
+`templates/`, `docs/`, or `content/`. You can target specific source anchors:
+
+```bash
+npx @agent-native/core@latest visualize-repo \
+  --target actions/webhooks.ts \
+  --target server/db/schema.ts \
+  --target app/components/PromptComposer.tsx
+```
+
+The starter folder lives at `.agent-native/visual-docs/repo-overview` by
+default. Comments stay local in `comments.json`, so reviewers can mark sections
+for a coding agent and the agent can update both code and MDX in the same
+change. Run `visualize-repo check` for local lint, and `visualize-repo verify`
+when you want the Plan renderer schema to validate the MDX.
+
+## Desktop local file sync {#desktop-local-sync}
+
+Agent Native Desktop also gives hosted Plans a native local-folder bridge. This
+is different from local-files privacy mode: the hosted Plan database remains the
+source of truth for sharing, comments, history, and live review, while Desktop
+can mirror the current plan's source files to a folder you choose.
+
+Open a plan in Agent Native Desktop, use the plan menu's **Local files** actions,
+then:
+
+- **Link local folder** — choose the folder for that plan's MDX source.
+- **Sync to local folder** — write `plan.mdx`, optional `canvas.mdx`,
+  optional `prototype.mdx`, optional `.plan-state.json`, and image assets.
+- **Import local edits** — read the folder and apply it through
+  `import-visual-plan-source` with the plan's current update timestamp.
+- **Auto-sync changes** — keep exporting the hosted plan's latest source after
+  edits made in the app.
+
+This path does not require cloning the Plan app or running a CLI. It is for
+file-first review/editing around a hosted plan, not for keeping plan content out
+of the hosted database.
+
+## What's next
+
+- [**Visual Plans**](/docs/template-plan) — the two commands and the guest browser flow
+- [**Reviewing and Commenting on Plans**](/docs/template-plan-review-workflow) — what publishing a local plan unlocks
+- [**Extending Plan**](/docs/template-plan-developers) — MDX source sync actions and the fully offline local dev mode

package/docs/content/template-plan-review-workflow.mdx

@@ -0,0 +1,180 @@
+---
+title: "Reviewing and Commenting on Plans"
+description: "How reviewers comment on an Agent-Native Plan, how the agent tells addressed feedback from open feedback, how sharing and roles work, and how to delete or restore a plan."
+---
+
+# Reviewing and Commenting on Plans
+
+This page is for anyone reviewing a plan or recap, and for anyone sharing,
+reporting, or deleting one. It covers what happens after a plan exists — see
+[Visual Plans](/docs/template-plan) for how a plan gets created in the first
+place.
+
+## Comment types {#comment-types}
+
+Reviewers comment directly on the plan instead of leaving separate notes.
+
+- **Text comments** attach to the nearest prose block.
+- **Visual and canvas comments** pin to an exact spot on a wireframe, image, or
+  design board, and carry target coordinates so the agent knows precisely what
+  was flagged.
+- Every comment can target either the **agent** or a **human** reviewer.
+  Agent-targeted comments are the ones the agent is expected to act on; a
+  human-targeted comment is context, not an instruction.
+- **@mentions** notify teammates with inline chips. When email is configured,
+  new comments send a best-effort notification: root comments and replies
+  notify the plan owner and anyone @mentioned, and replies also notify prior
+  human participants in that thread.
+- Comments thread as replies to a parent comment, and each one carries the
+  reviewer's identity (name/email) when known.
+
+<WireframeBlock id="doc-block-plan1">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='display:flex;flex-direction:column;gap:12px;padding:16px;min-height:420px;box-sizing:border-box'><div style='display:flex;align-items:center;gap:8px'><span class='wf-pill accent'>Open</span><span class='wf-muted' style='font-size:12px'>3 comments · 1 resolved</span></div><div class='wf-card' style='display:flex;flex-direction:column;gap:8px;padding:12px'><div style='display:flex;align-items:center;gap:8px'><span class='wf-pill'>Ada</span><span class='wf-muted' style='font-size:11px'>targets: agent</span></div><div class='wf-box'>Should this button disable while saving?</div><div style='display:flex;align-items:center;gap:8px;padding-left:16px'><span class='wf-pill'>Agent</span><span class='wf-muted' style='font-size:11px'>reply</span></div><div class='wf-box' style='margin-left:16px'>Yes — added a disabled state, see the updated screen.</div><button class='primary' style='align-self:flex-end'>Resolve</button></div><div class='wf-card' style='display:flex;flex-direction:column;gap:8px;padding:12px;opacity:0.6'><div style='display:flex;align-items:center;gap:8px'><span class='wf-pill'>Priya</span><span class='wf-muted' style='font-size:11px'>targets: human · resolved</span></div><div class='wf-box'>Copy nit — fixed in v2.</div></div></div>"
+    }
+  />
+</WireframeBlock>
+
+## Resolving feedback and version history {#resolving}
+
+The agent reads pending feedback with `get-plan-feedback`, which returns flat
+comments, grouped threads, anchor summaries, and recent review events. Once a
+change addresses a thread, the agent re-reads the plan to confirm the change
+persisted, then calls `resolve-plan-comment` for that thread and
+`consume-plan-feedback` for its comments — so review history stays visible
+instead of being deleted.
+
+<Diagram id="doc-block-plan2" title="Comment lifecycle" summary="A comment stays open until the agent verifies the requested change landed, then marks it resolved and consumed.">
+
+```html
+<div class="diagram-lifecycle">
+  <div class="diagram-node">
+    Posted<br /><small class="diagram-muted"
+      >text, visual, or canvas anchor</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel center">
+    Agent reads<br /><small class="diagram-muted">get-plan-feedback</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box">
+    Plan updated<br /><small class="diagram-muted">re-read to verify</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-node">
+    Resolved + consumed<br /><small class="diagram-muted"
+      >resolve-plan-comment · consume-plan-feedback</small
+    >
+  </div>
+</div>
+```
+
+```css
+.diagram-lifecycle {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.diagram-lifecycle .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
+}
+.diagram-lifecycle .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+  text-align: center;
+}
+```
+
+</Diagram>
+
+Deleting a comment (`delete-plan-comment`) is a soft delete — it disappears
+from normal views but the row stays for audit/debugging, and deleting a
+thread's root comment also deletes its replies. Use it only when a reviewer
+explicitly wants a comment removed or an accidental post undone; prefer
+resolving for feedback that has simply been handled.
+
+Plans also keep snapshots before meaningful authoring changes (pure comments
+and status changes do not trigger a snapshot). Use `list-plan-versions` to see
+saved snapshots and `get-plan-version` to inspect one before recommending a
+rollback. `restore-plan-version` snapshots the current plan first (so restore
+itself is reversible) and restores the plan's authoring content while
+preserving sharing, ownership, hosted publish metadata, comments, and activity
+history.
+
+## Sharing a plan {#sharing}
+
+- **Viewing** a public or org-shared plan works for anyone with the link — no
+  account required.
+- **Commenting** on a shared plan requires an agent-native account.
+- **Sharing** a plan — publishing it to a link, private sharing, or granting
+  reviewer roles — requires signing in. Google sign-in appears when the
+  standard Google OAuth env vars are configured.
+
+Each share grant has a role:
+
+| Role       | Can do                                                               |
+| ---------- | -------------------------------------------------------------------- |
+| **Viewer** | View the plan and comment on it                                      |
+| **Editor** | Everything a viewer can, plus edit plan content                      |
+| **Admin**  | Everything an editor can, plus grant or remove other people's access |
+
+Only the plan's owner can delete it, publish/unpublish it, or run a hard
+delete, regardless of admin shares — share roles control collaboration, not
+ownership transfer. See [Requesting access to a private plan](/docs/template-plan#request-access)
+for what a viewer without a share sees.
+
+The hosted Plans connector lives at `https://plan.agent-native.com/mcp`.
+Never put shared secrets in skill files.
+
+## Reporting abuse on a public plan {#report-abuse}
+
+Anyone who can view a **public** plan can report it for moderation without
+changing the plan's content. Reporting requires being signed in — the report
+is scoped to that viewer so it cannot be spoofed anonymously.
+
+A report has one required reason plus optional free-text details:
+
+`spam`, `harassment`, `hate`, `sexual`, `violence`, `self-harm`, `privacy`,
+`illegal`, `other`.
+
+Submitting a second report for the same plan from the same person does not
+create a duplicate — it updates the existing open report (bumping an
+occurrence count) instead. This is a flag for moderation review; it does not
+remove the plan or notify the plan's owner.
+
+## Deleting and restoring plans {#delete-data}
+
+Signed-in owners can delete their hosted plans and recaps from the Plans list
+or the plan action menu.
+
+- **Soft delete** moves the plan to the **Deleted** tab, makes normal plan
+  views/direct links stop working, and removes public access by making the row
+  private. The SQL rows are retained so the owner can restore the plan later.
+- **Restore** is available from the **Deleted** tab for soft-deleted plans.
+- **Permanent delete** removes the hosted plan row and plan-scoped comments,
+  sections, activity events, version snapshots, share grants, abuse reports,
+  and SQL asset records. The UI requires typing `DELETE <plan-id>` before the
+  final button enables.
+
+Permanent delete removes the Plan app's database records and SQL-backed asset
+bytes/references. If a deployment uses an external upload provider, provider
+object retention follows that provider's lifecycle because the shared upload
+abstraction does not currently expose object deletion. Local-files privacy mode
+keeps the source in your local MDX folder instead; deleting hosted data does
+not touch local files — see
+[Local-Files Mode and Desktop Sync](/docs/template-plan-local-and-desktop).
+
+## What's next
+
+- [**Visual Plans**](/docs/template-plan) — how a plan or recap gets created
+- [**Local-Files Mode and Desktop Sync**](/docs/template-plan-local-and-desktop) — keep review content off the hosted database
+- [**Events and Automations**](/docs/template-plan-automations) — trigger a webhook or wake the agent when someone comments
+- [**Extending Plan**](/docs/template-plan-developers) — the comment and sharing data model
+- [**Sharing**](/docs/sharing) — the framework-level sharing model Plan builds on