@agent-native/core 0.69.0 → 0.70.1

package/corpus/templates/plan/.agents/skills/visual-plan/SKILL.md

@@ -88,13 +88,14 @@ surface.
   approach and options in the plan. Ask a clarifying question only when an
   ambiguity would change the design and you cannot resolve it from the code; use
   the host agent's normal ask-user-question flow and batch 2-4 high-leverage
-  questions before finalizing. Do not call `create-visual-questions` from
-  `/visual-plan`. Otherwise state the assumption explicitly and proceed, and
-  keep anything unresolved in the plan's single bottom `question-form` Open
-  Questions block. For complex plans, do a final open-question pass before
-  handoff: if a decision would affect architecture, scope, UX, data shape, or
-  rollout, either decide it in the plan with rationale or put it in that bottom
-  form with a recommended default.
+  questions before finalizing. Do not call `create-visual-questions` for
+  ordinary clarification or preflight; reserve it for the visual-intake mode when
+  the user explicitly asks for a visual intake questionnaire. Otherwise state the
+  assumption explicitly and proceed, and keep anything unresolved in the plan's
+  single bottom `question-form` Open Questions block. For complex plans, do a
+  final open-question pass before handoff: if a decision would affect
+  architecture, scope, UX, data shape, or rollout, either decide it in the plan
+  with rationale or put it in that bottom form with a recommended default.
 - **The plan is the approval gate.** After surfacing it, ask the user to review
   and approve before you write code, and name which files/areas the work touches.
   Presenting the plan and requesting sign-off is the approval step — do not ask a
@@ -139,6 +140,11 @@ is reachable. Local-files privacy mode (after Tool Guidance) is the exception.
 
 ## Core Workflow
 
+This section describes the default hosted Plan MCP workflow. If
+`AGENT_NATIVE_PLANS_MODE=local-files` is set, or the user asks for fully local
+files/no hosted Plan writes, use **Local-Files Privacy Mode** instead; carry
+forward only the code-research and plan-composition guidance here.
+
 1. Follow the host agent's normal planning flow: inspect the codebase, delegate
    wide exploration when useful, gather the info needed, and ask native
    clarifying questions as needed before generating the plan. If a source plan
@@ -185,11 +191,13 @@ is reachable. Local-files privacy mode (after Tool Guidance) is the exception.
    backend, data, multi-file, or risky), also kick off the self-review pass in
    **Self-Review Before Handoff** while the user reads, instead of blocking the
    handoff on it.
-5. Call `get-plan-feedback` before editing, after review, after any long pause,
+5. For hosted plans, call `get-plan-feedback` before editing, after review,
+   after any long pause,
    and before the final response. Treat `anchorDetails`, resolver intent, recent
    review events, and any focused screenshots from browser handoff as the source
    of truth for exactly what changed and exactly what each comment points at.
-6. Apply changes with `update-visual-plan`, preferring targeted `contentPatches`.
+6. For hosted plans, apply changes with `update-visual-plan`, preferring
+   targeted `contentPatches`.
    Treat the top-level `content` payload as a full replacement, not a merge; do
    not send a partial `content` object to add a canvas or one block. If a full
    replacement is unavoidable, first read the complete plan source/content, carry
@@ -197,8 +205,8 @@ is reachable. Local-files privacy mode (after Tool Guidance) is the exception.
    afterward so the document body was not truncated. When the user wants
    source-control friendly edits, use `patch-visual-plan-source` against the MDX
    files instead of regenerating the plan.
-7. Export with `export-visual-plan` only when the user wants a shareable receipt
-   or repo-check-in artifacts.
+7. For hosted plans, export with `export-visual-plan` only when the user wants a
+   shareable receipt or repo-check-in artifacts.
 
 ## Self-Review Before Handoff
 
@@ -394,11 +402,12 @@ The local-files contract is:
   wants the artifact checked into the repo, or use 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 contains `plan.mdx`, optional
-  `canvas.mdx`, optional `prototype.mdx`, and optional `.plan-state.json`.
-- Run `npx @agent-native/core@latest plan local check --dir plans/<slug>`
-  before serving, then run
-  `npx @agent-native/core@latest plan local serve --dir plans/<slug> --kind plan --open`.
-  Report the returned local bridge URL from stdout or `plans/<slug>/.plan-url`.
+  `canvas.mdx`, optional `prototype.mdx`, and optional `.plan-state.json`. Use
+  that exact chosen folder as `<plan-dir>` in every local CLI command below.
+- Run `npx @agent-native/core@latest plan local check --dir <plan-dir>` before
+  serving, then run
+  `npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind plan --open`.
+  Report the returned 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. On macOS, `--open` prefers Chromium browsers;
@@ -407,7 +416,7 @@ The local-files contract is:
   running locally with the same `PLAN_LOCAL_DIR`, the `/local-plans/<slug>` route
   is also valid.
 - For headless verification, run
-  `npx @agent-native/core@latest plan local verify --dir plans/<slug> --kind plan`.
+  `npx @agent-native/core@latest plan local verify --dir <plan-dir> --kind plan`.
   It starts the bridge, checks the private-network preflight and JSON payload,
   prints diagnostics, and exits. If the browser hangs on "Loading plan", fetch
   the `bridgeUrl` from the verify/serve JSON to read the concrete validation
@@ -429,6 +438,11 @@ otherwise approved by the user.
 
 ## Interpreting comment anchors
 
+This section applies to hosted plans with `get-plan-feedback` /
+`update-visual-plan`. In local-files mode, do not call hosted feedback or update
+tools; interpret file/chat feedback directly, edit the MDX files, rerun the
+local bridge check/serve/verify command, and report the new local URL.
+
 `get-plan-feedback` returns rich anchors — read them before acting on any comment.
 
 - **Coordinate frames.** `targetX`/`targetY` are percentages *within* the

package/corpus/templates/plan/.agents/skills/visual-plan/references/wireframe.md

@@ -135,12 +135,15 @@ no labels or copy. The renderer drops borders, sketch, and color into the
 skeleton register automatically. Never escape to a `custom-html` document block
 to fake a loader.
 
-**Editing an existing mockup.** To change one element, text, or color in an
-existing html mockup, call `update-visual-plan`
-with `contentPatches: [{ op: "patch-wireframe-html", blockId, edits: [{ find,
+**Editing an existing mockup.** In hosted mode, to change one element, text, or
+color in an existing html mockup, do not regenerate the frame — call
+`update-visual-plan` with
+`contentPatches: [{ op: "patch-wireframe-html", blockId, edits: [{ find,
 replace }] }]`. Each `find` is a unique snippet of the current html (read it
 first with `get-visual-plan`); set `all: true` on an edit to replace every
-occurrence. The result is re-sanitized.
+occurrence. The result is re-sanitized. In local-files privacy mode, do not call
+hosted Plan tools; edit the local MDX source directly and rerun the local
+check/serve or verify command for `<plan-dir>`.
 
 **Treat the wireframe border as part of the visible design.** Always wrap HTML
 wireframe content in a root container with real inner padding before drawing

package/corpus/templates/plan/.agents/skills/visual-recap/SKILL.md

@@ -36,8 +36,9 @@ In local-files mode:
   `npx @agent-native/core@latest plan blocks --out plan-blocks.md` when the Plan
   MCP connector is not registered; it calls the public no-auth
   `get-plan-blocks` route and sends no recap content. If network access is
-  unavailable, use the bundled references and validate with
-  `plan local check` / `plan local serve`. For `checklist` and `question-form`,
+  unavailable, use the bundled references and validate the MDX with
+  `plan local check`; do not run `plan local serve` unless the hosted Plan UI is
+  reachable or a local Plan app is already running. For `checklist` and `question-form`,
   copy the catalog examples verbatim: checklist items need `id` and `label`;
   question-form questions need `id`, `title`, and `mode`; and each option needs
   `id` and `label`. `plan local check` validates these required fields against
@@ -47,21 +48,24 @@ In local-files mode:
   folder such as `.agent-native/plans/<slug>/` or `/tmp/agent-native-plans/<slug>/`
   when it should not be checked in. The folder contains `plan.mdx`, optional
   `canvas.mdx`, optional `prototype.mdx`, and optional `.plan-state.json`. Set
-  `kind: "recap"` and `localOnly: true` in frontmatter/state when authoring
-  the source.
-- Run `npx @agent-native/core@latest plan local check --dir plans/<slug>`
-  before serving, then run
-  `npx @agent-native/core@latest plan local serve --dir plans/<slug> --kind recap --open`.
-  Report the returned local bridge URL from stdout or `plans/<slug>/.plan-url`.
+  `kind: "recap"` and `localOnly: true` in frontmatter/state when authoring the
+  source. Use that exact chosen folder as `<plan-dir>` in every local CLI command
+  below.
+- Run `npx @agent-native/core@latest plan local check --dir <plan-dir>` before
+  any preview. When the hosted Plan UI is reachable, run
+  `npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind recap --open`.
+  Report the returned 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. 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.
+  is also valid. In a truly offline environment, hand off the local `<plan-dir>`
+  path after `plan local check` and note that interactive preview requires either
+  network access to the hosted Plan UI or a running local Plan app.
 - For headless verification, run
-  `npx @agent-native/core@latest plan local verify --dir plans/<slug> --kind recap`.
+  `npx @agent-native/core@latest plan local verify --dir <plan-dir> --kind recap`.
   It starts the bridge, checks the private-network preflight and JSON payload,
   prints diagnostics, and exits. If the browser hangs on "Loading plan", fetch
   the `bridgeUrl` from the verify/serve JSON to read the concrete validation
@@ -72,7 +76,9 @@ In local-files mode:
   `set-resource-visibility`, or any hosted Plan tool for that recap except the
   schema-only block catalog lookup above.
 - Treat review feedback as file or chat feedback: update the MDX files directly,
-  rerun the local bridge command, and summarize the new local bridge URL.
+  rerun `plan local check`, and rerun `serve` or `verify` only when that preview
+  path is available. Summarize the new local URL when one exists; otherwise
+  summarize the checked local folder path.
   Hosted comments, sharing, screenshots, usage attachment, and PR sticky comment
   publishing are unavailable until the user explicitly opts into publishing.
 
@@ -288,10 +294,10 @@ and re-import before reporting the link. A text-match screenshot is not enough;
 visually inspect the captured image. When no browser is available (for example
 a headless CI agent), state that in the recap handoff instead.
 
-## Top Canvas Recaps — read `../visual-plans/references/canvas.md`
+## Top Canvas Recaps — read `../visual-plan/references/canvas.md`
 
 When a recap includes a top canvas, storyboard, or flow view, READ
-`../visual-plans/references/canvas.md` before authoring `canvas.mdx`. Recap
+`../visual-plan/references/canvas.md` before authoring `canvas.mdx`. Recap
 canvas artboards must use the same HTML wireframe path as good document-body
 wireframes: `<Screen surface="..." html={...} />` with a semantic HTML fragment.
 Do not author fresh kit-tree children such as `<FrameScreen>`, `<Card>`,
@@ -305,8 +311,8 @@ assume it used the legacy kit path and replace it with an HTML screen.
 
 In local-files privacy mode, run `plan local check` first, then report the local
 bridge URL from
-`npx @agent-native/core@latest plan local serve --dir plans/<slug> --kind recap --open`
-or from `plans/<slug>/.plan-url`. It opens the hosted Plan UI but reads from the
+`npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind recap --open`
+or from `<plan-dir>/.plan-url`. It opens the hosted Plan UI but reads from the
 localhost bridge on this machine, so it is not shareable across machines. If the
 Plan app itself is running locally with the same `PLAN_LOCAL_DIR`, the
 `/local-plans/<slug>` route is also valid. Do not invent a hosted database URL
@@ -471,7 +477,8 @@ installed as plain text and no MCP tools are registered after discovery, run
 `npx @agent-native/core@latest plan blocks --out plan-blocks.md` and read that
 file first. The CLI command calls the public no-auth `get-plan-blocks` route and
 sends no plan/recap content. If network access is unavailable, use the bundled
-references and validate with `plan local check` / `plan local serve`.
+references and validate with `plan local check`; run `plan local serve` only
+when the hosted Plan UI is reachable or a local Plan app is already running.
 
 The catalog returns the authoritative, always-current block vocabulary generated
 live from the app's own block registry — the same config the renderer and MDX
@@ -579,14 +586,17 @@ inferred (not extracted) as inferred in prose.
 
 ## Bidirectional Loop
 
-Because a recap is a real, editable plan, the same review loop as forward plans
-applies: a reviewer can annotate any block, and the coding agent reads
-`get-plan-feedback` to drive fixes back into the code — annotation → agent →
-diff, the same close-the-loop flow forward plans use. After a reviewer annotates
-a block, call `get-plan-feedback` to read the structured feedback, then either
-update the recap with `create-visual-recap` (passing the existing `planId` to
-replace it in place) or apply targeted changes with `update-visual-plan`. The
-loop is live and wired. The one thing not yet automatic is PR-comment-triggered
+In hosted mode, because a recap is a real, editable plan, the same review loop
+as forward plans applies: a reviewer can annotate any block, and the coding
+agent reads `get-plan-feedback` to drive fixes back into the code — annotation →
+agent → diff, the same close-the-loop flow forward plans use. After a reviewer
+annotates a block, call `get-plan-feedback` to read the structured feedback,
+then either update the recap with `create-visual-recap` (passing the existing
+`planId` to replace it in place) or apply targeted changes with
+`update-visual-plan`. The loop is live and wired. In local-files privacy mode,
+do not call those hosted tools; read review notes from chat or local files, edit
+`<plan-dir>/*.mdx` directly, and rerun `plan local check`, `serve`, or `verify`
+for `<plan-dir>`. The one thing not yet automatic is PR-comment-triggered
 re-runs: the GitHub Action creates an initial recap per PR, but it does not yet
 re-run automatically when new review feedback is posted in GitHub — that
 auto-re-run is the remaining fast-follow.

package/corpus/templates/plan/.agents/skills/visual-recap/references/wireframe.md

@@ -135,12 +135,15 @@ no labels or copy. The renderer drops borders, sketch, and color into the
 skeleton register automatically. Never escape to a `custom-html` document block
 to fake a loader.
 
-**Editing an existing mockup.** To change one element, text, or color in an
-existing html mockup, call `update-visual-plan`
-with `contentPatches: [{ op: "patch-wireframe-html", blockId, edits: [{ find,
+**Editing an existing mockup.** In hosted mode, to change one element, text, or
+color in an existing html mockup, do not regenerate the frame — call
+`update-visual-plan` with
+`contentPatches: [{ op: "patch-wireframe-html", blockId, edits: [{ find,
 replace }] }]`. Each `find` is a unique snippet of the current html (read it
 first with `get-visual-plan`); set `all: true` on an edit to replace every
-occurrence. The result is re-sanitized.
+occurrence. The result is re-sanitized. In local-files privacy mode, do not call
+hosted Plan tools; edit the local MDX source directly and rerun the local
+check/serve or verify command for `<plan-dir>`.
 
 **Treat the wireframe border as part of the visible design.** Always wrap HTML
 wireframe content in a root container with real inner padding before drawing

package/corpus/templates/plan/AGENTS.md

@@ -46,6 +46,10 @@ review before code changes happen.
   resource paths for the latest code index, file tree, and captured source
   snapshots.
 - `navigate` moves the UI to the plan list or a specific visual plan.
+- The sidebar brand header has a `Customize branding` popover. Treat it as a
+  source-code request, not plan data: local Code mode edits `templates/plan`
+  source directly, while hosted/live surfaces route people to Desktop or
+  Builder for code customization.
 
 ## Normal Planning Flow
 

package/corpus/templates/plan/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable user-facing changes to Agent-Native Plan are documented here. Open it any
+time from the command menu (Cmd+K → "What's new").
+
+## 2026-06-23
+
+### Added
+
+- See what's new right inside Agent-Native Plan — a changelog now lives in the command menu (Cmd+K).

package/corpus/templates/plan/actions/view-screen.ts

@@ -34,6 +34,11 @@ export default defineAction({
     const screen: Record<string, unknown> = {};
     if (navigation) screen.navigation = navigation;
     if (localCodebase) screen.localCodebase = localCodebase;
+    screen.brandingCustomization = {
+      surface: "sidebar brand header",
+      workflow:
+        "The Customize branding popover sends a source-code request. In local Code mode it routes to the local code agent; on hosted/live surfaces it should guide the user to Desktop or Builder for source edits.",
+    };
     const nav = navigation as {
       planId?: string;
       localPlanSlug?: string;

package/corpus/templates/plan/app/components/layout/Sidebar.tsx

@@ -28,7 +28,11 @@ import {
   appPath,
   markAgentChatHomeHandoff,
   navigateWithAgentChatViewTransition,
+  PromptComposer,
+  sendToAgentChat,
+  useCodeMode,
   useChatThreads,
+  useSendToAgentChat,
   useSession,
   type ChatThreadSummary,
 } from "@agent-native/core/client";
@@ -44,6 +48,11 @@ import {
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
 import { Input } from "@/components/ui/input";
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/components/ui/popover";
 import { Skeleton } from "@/components/ui/skeleton";
 import {
   Tooltip,
@@ -53,6 +62,23 @@ import {
 
 const PLAN_CHAT_STORAGE_KEY = "plans";
 
+const PLAN_BRANDING_CODE_CONTEXT = [
+  "The user is using the Plan app branding customization popover.",
+  "Make source-code changes for Agent-Native Plan branding in templates/plan.",
+  "Inspect the current brand surfaces first: app/lib/app-config.ts, app/components/layout/Sidebar.tsx, app/root.tsx metadata/icons, public brand assets, and app/global.css theme tokens.",
+  "Keep runtime plan data, stored plans, recaps, comments, and generated plan content unchanged unless the user explicitly asks for those data changes.",
+  "Use existing Plan styling, shadcn primitives, Tabler icons, and repo patterns. Keep changes tightly scoped.",
+].join("\n");
+
+function buildBrandingCustomizationMessage(request: string) {
+  return [
+    "Customize the Agent-Native Plan app branding.",
+    "",
+    "Request:",
+    request,
+  ].join("\n");
+}
+
 const navItems = [
   { icon: IconMessageCircle, label: "Ask", href: "/" },
   { icon: IconClipboardCheck, label: "Plan", href: "/plans" },
@@ -521,6 +547,76 @@ function PlansSidebarSection({ collapsed }: { collapsed: boolean }) {
   );
 }
 
+function BrandingCustomizePopover() {
+  const [open, setOpen] = useState(false);
+  const { isCodeMode } = useCodeMode();
+  const { send, isGenerating, codeRequiredDialog } = useSendToAgentChat();
+
+  function handleSubmit(text: string) {
+    const trimmed = text.trim();
+    if (!trimmed || isGenerating) return;
+    const message = buildBrandingCustomizationMessage(trimmed);
+    const payload = {
+      message,
+      context: PLAN_BRANDING_CODE_CONTEXT,
+      submit: true,
+      type: "code" as const,
+      newTab: true,
+    };
+    const tabId = isCodeMode ? sendToAgentChat(payload) : send(payload);
+    setOpen(false);
+    if (tabId) {
+      toast.success(
+        isCodeMode
+          ? "Sent branding request to the local code agent"
+          : "Sent branding request to the code agent",
+      );
+    }
+  }
+
+  return (
+    <>
+      {codeRequiredDialog}
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverTrigger asChild>
+          <button
+            type="button"
+            aria-label="Customize Plan branding"
+            title="Customize branding"
+            className="flex size-7 shrink-0 items-center justify-center rounded-md text-sidebar-foreground/55 opacity-0 transition-colors hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:opacity-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring group-hover/brand:opacity-100 group-focus-within/brand:opacity-100 data-[state=open]:opacity-100"
+          >
+            <IconEdit className="size-3.5" />
+          </button>
+        </PopoverTrigger>
+        <PopoverContent
+          side="right"
+          align="start"
+          sideOffset={8}
+          className="w-[calc(100vw-2rem)] max-w-[420px] rounded-xl border-border bg-card p-3 shadow-xl sm:w-[420px]"
+        >
+          <div className="mb-2 px-1">
+            <h3 className="text-sm font-semibold text-foreground">
+              Customize branding
+            </h3>
+            <p className="mt-1 text-xs text-muted-foreground">
+              Describe the brand changes to make across Plan.
+            </p>
+          </div>
+          <PromptComposer
+            autoFocus
+            disabled={isGenerating}
+            attachmentsEnabled={false}
+            showModelSelector={false}
+            placeholder="Use our logo, change the app name, update colors..."
+            draftScope="plans:customize-branding"
+            onSubmit={handleSubmit}
+          />
+        </PopoverContent>
+      </Popover>
+    </>
+  );
+}
+
 export function Sidebar({
   collapsed = false,
   collapsible = true,
@@ -562,7 +658,7 @@ export function Sidebar({
     >
       <div
         className={cn(
-          "flex h-12 shrink-0 items-center border-b border-border",
+          "group/brand flex h-12 shrink-0 items-center border-b border-border",
           collapsed ? "justify-center px-0" : "gap-2 px-3",
         )}
       >
@@ -590,6 +686,7 @@ export function Sidebar({
             </span>
           )}
         </div>
+        {!collapsed && <BrandingCustomizePopover />}
       </div>
 
       <nav className="flex-1 space-y-1 overflow-y-auto px-2 py-2">

package/corpus/templates/plan/app/components/plan/wireframe/html-artboard.css

@@ -293,7 +293,9 @@
   --wf-font: var(--wf-font-clean);
 
   position: relative;
-  overflow: hidden;
+  /* Matches core blocks.css `.plan-diagram-frame`: scroll oversized diagrams
+     instead of clipping them (Plan's copy had drifted to `hidden`). */
+  overflow: auto;
   width: 100%;
   border: 0;
   border-radius: 10px;

package/corpus/templates/plan/app/pages/PlansPage.tsx

@@ -68,6 +68,7 @@ import {
   useAgentEngineConfigured,
   useActionQuery,
   useSession,
+  track,
   emailToColor,
   emailToName,
   type AgentSidebarStateChangeDetail,
@@ -219,6 +220,11 @@ import {
   type PlanVersionDetail,
   type PlanVersionSummary,
 } from "@shared/types";
+import {
+  PLAN_SHARE_SURFACE,
+  readPlanShareAttribution,
+  withPlanShareAttribution,
+} from "@shared/share-attribution";
 import {
   diffPlanVersions,
   formatVersionDiffSummary,
@@ -3783,13 +3789,92 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
     }
     if (!selectedId) return undefined;
     const base = bundle?.plan.kind === "recap" ? "recaps" : "plans";
-    return `${window.location.origin}${appPath(`/${base}/${selectedId}`)}`;
+    const url = `${window.location.origin}${appPath(`/${base}/${selectedId}`)}`;
+    // Viral attribution: tag the shared/public plan link so signups arriving
+    // from it can be attributed even when `document.referrer` is empty. `via`
+    // is a non-PII owner id and is only set when the current viewer is the
+    // owner (the only person whose session userId is the plan owner's id).
+    const ownerViaId =
+      effectivePlanAccessRole === "owner" ? (session?.userId ?? null) : null;
+    return withPlanShareAttribution(url, ownerViaId);
   }, [
     bundle?.plan.kind,
+    effectivePlanAccessRole,
     localPlanMode,
     localPlanRepoPath,
     localPlanSlug,
     selectedId,
+    session?.userId,
+  ]);
+
+  // Viral attribution: read the `ref`/`via` the visitor arrived on (from a
+  // tagged share link) so funnel events carry the same attribution the
+  // framework first-touch cookie captured. Read once from the URL on mount.
+  const shareAttribution = useMemo(
+    () =>
+      readPlanShareAttribution(
+        typeof window === "undefined" ? "" : window.location.search,
+      ),
+    [],
+  );
+
+  // A logged-out visitor looking at a public plan/recap is the share funnel
+  // audience. Their CTAs (comment, sign in) route through `openSignIn`.
+  const isLoggedOutPublicPlanView =
+    !sessionLoading &&
+    !session &&
+    !localPlanMode &&
+    Boolean(selectedId) &&
+    effectivePlanVisibility === "public";
+
+  // share_cta_click — fire alongside (never instead of) the real navigation.
+  // `track` is non-throwing, but guard anyway so analytics can never break a
+  // CTA. Only fires for the logged-out public-plan funnel audience.
+  const fireShareCtaClick = useCallback(
+    (cta: string) => {
+      if (!isLoggedOutPublicPlanView) return;
+      try {
+        void track("share_cta_click", {
+          surface: PLAN_SHARE_SURFACE,
+          plan_id: selectedId ?? "",
+          cta,
+          ref: shareAttribution.ref,
+          via: shareAttribution.via,
+        });
+      } catch {
+        // Never let analytics break a CTA.
+      }
+    },
+    [
+      isLoggedOutPublicPlanView,
+      selectedId,
+      shareAttribution.ref,
+      shareAttribution.via,
+    ],
+  );
+
+  // share_view — fire once when a logged-out visitor views a public plan. The
+  // ref guard prevents double-fire across re-renders / StrictMode double-invoke.
+  const shareViewFiredRef = useRef(false);
+  useEffect(() => {
+    if (!isLoggedOutPublicPlanView) return;
+    if (shareViewFiredRef.current) return;
+    shareViewFiredRef.current = true;
+    try {
+      void track("share_view", {
+        surface: PLAN_SHARE_SURFACE,
+        plan_id: selectedId ?? "",
+        ref: shareAttribution.ref,
+        via: shareAttribution.via,
+      });
+    } catch {
+      // Never let analytics break the page render.
+    }
+  }, [
+    isLoggedOutPublicPlanView,
+    selectedId,
+    shareAttribution.ref,
+    shareAttribution.via,
   ]);
 
   useEffect(() => {
@@ -6227,11 +6312,14 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
                   {!session ? (
                     <GuestCommentCta
                       position={inlineCommentPosition}
-                      onSignIn={() =>
+                      onSignIn={() => {
+                        // share funnel: logged-out viewer of a public plan
+                        // clicking the "create account to comment" CTA.
+                        fireShareCtaClick("comment_signin");
                         openSignIn(
                           window.location.pathname + window.location.search,
-                        )
-                      }
+                        );
+                      }}
                       onCancel={closeInlineComment}
                     />
                   ) : (
@@ -6669,9 +6757,12 @@ function PlanShareControl({
     effectivePublishedUrl && hostedPlanOnCurrentOrigin && effectiveHostedPlanId
       ? effectiveHostedPlanId
       : planId;
+  // Viral attribution: the owner is the one publishing/managing the share here,
+  // so `via` is their non-PII session userId. `localShareUrl` is already tagged
+  // upstream; tag the hosted/public URL too so both paths self-attribute.
   const managedShareUrl =
     effectivePublishedUrl && hostedPlanOnCurrentOrigin
-      ? effectivePublishedUrl
+      ? withPlanShareAttribution(effectivePublishedUrl, session?.userId ?? null)
       : localShareUrl;
 
   useEffect(() => {
@@ -6713,11 +6804,20 @@ function PlanShareControl({
             hostedPlanId: result.hostedPlanId,
           });
           setAuthPrompt(null);
-          copyPublishedUrl(result.hostedPlanUrl ?? result.url);
+          // Tag the freshly-minted public link so signups from it are
+          // attributed. The publisher is the owner, so `via` is their userId.
+          copyPublishedUrl(
+            withPlanShareAttribution(
+              result.hostedPlanUrl ?? result.url,
+              session?.userId ?? null,
+            ) ??
+              result.hostedPlanUrl ??
+              result.url,
+          );
         },
       },
     );
-  }, [copyPublishedUrl, planId, publishPlan]);
+  }, [copyPublishedUrl, planId, publishPlan, session?.userId]);
 
   // Logged-in / local-dev: manage shares for the plan in this app instance.
   if (canManageLocalShares) {

package/corpus/templates/plan/app/root.tsx

@@ -22,6 +22,7 @@ import {
 } from "@agent-native/core/client";
 import { IconSun, IconMoon } from "@tabler/icons-react";
 import { useTheme } from "next-themes";
+import changelog from "../CHANGELOG.md?raw";
 import { Toaster } from "@/components/ui/sonner";
 import { Layout as AppLayout } from "@/components/layout/Layout";
 import { TAB_ID } from "@/lib/tab-id";
@@ -106,7 +107,12 @@ function AppContent() {
   );
   return (
     <>
-      <CommandMenu open={cmdkOpen} onOpenChange={setCmdkOpen}>
+      <CommandMenu
+        open={cmdkOpen}
+        onOpenChange={setCmdkOpen}
+        changelog={changelog}
+        changelogKey="plan"
+      >
         <CommandMenu.Group heading="Actions">
           <CommandMenu.Item onSelect={() => go("/")}>Ask Plan</CommandMenu.Item>
           <CommandMenu.Item onSelect={() => go("/plans")}>

package/corpus/templates/plan/changelog/2026-06-23-large-diagrams-in-a-plan-now-scroll-within-their-block-inste.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-06-23
+---
+
+Large diagrams in a plan now scroll within their block instead of being cut off