@agent-native/core 0.69.0 → 0.70.0

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/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/shared/share-attribution.ts

@@ -0,0 +1,72 @@
+/**
+ * Viral attribution contract for shared/public Plan links.
+ *
+ * Public plan/recap URLs self-attribute so the signup funnel can be measured
+ * even when `document.referrer` is empty (desktop app, Slack, native clients,
+ * etc.). The framework captures first-touch from these params into a cookie and
+ * enriches the `signup` event; Plan's job is to (a) tag the share/public URLs it
+ * mints and (b) emit funnel events when a logged-out visitor views a public plan
+ * and clicks a sign-up CTA.
+ *
+ * Contract strings are centralized here so the minting side (share popover /
+ * copy-link) and the measuring side (public plan view) cannot drift apart. The
+ * framework also derives `plan_share` from public plan paths (`/p/`, `/plan/`,
+ * `/plans/`, `/recaps/`, `/share-plan/`) as a fallback when the param is lost.
+ *
+ * Privacy: `via` must be a non-PII stable id (the owner's user id), never an
+ * email. Omit `via` rather than leak PII into a public URL or event.
+ */
+
+/** Fixed referral source for plan shares. */
+export const PLAN_SHARE_REF = "plan_share";
+
+/** Surface tag included on plan share funnel events. */
+export const PLAN_SHARE_SURFACE = "plan";
+
+/** Query param names that carry attribution. */
+export const REF_PARAM = "ref";
+export const VIA_PARAM = "via";
+
+/**
+ * Append `ref=plan_share` (and `via=<ownerId>` when a non-PII owner id is known)
+ * to an absolute share/public plan URL, preserving any existing query params.
+ * Returns the input unchanged when it isn't a parseable absolute URL.
+ */
+export function withPlanShareAttribution(
+  url: string | undefined,
+  ownerId?: string | null,
+): string | undefined {
+  if (!url) return url;
+  try {
+    const parsed = new URL(url);
+    parsed.searchParams.set(REF_PARAM, PLAN_SHARE_REF);
+    const owner = (ownerId ?? "").trim();
+    if (owner) parsed.searchParams.set(VIA_PARAM, owner);
+    return parsed.toString();
+  } catch {
+    return url;
+  }
+}
+
+export type ShareAttribution = {
+  ref: string | undefined;
+  via: string | undefined;
+};
+
+/**
+ * Read `ref`/`via` from a query string (e.g. `window.location.search`). Falls
+ * back to `ref=plan_share` so downstream attribution stays meaningful even when
+ * the visitor arrived via a link that lost the param. Never throws.
+ */
+export function readPlanShareAttribution(search: string): ShareAttribution {
+  let ref: string | undefined;
+  let via: string | undefined;
+  try {
+    const params = new URLSearchParams(search ?? "");
+    ref = params.get(REF_PARAM) ?? undefined;
+    via = params.get(VIA_PARAM) ?? undefined;
+  } catch {
+    // Ignore malformed query strings — fall through to the default below.
+  }
+  return { ref: ref || PLAN_SHARE_REF, via: via || undefined };
+}

package/corpus/templates/slides/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable user-facing changes to Agent-Native Slides 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 Slides — a changelog now lives in the command menu (Cmd+K).

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

@@ -28,6 +28,7 @@ import { useQueryClient } from "@tanstack/react-query";
 import type { LinksFunction } from "react-router";
 import stylesheet from "./global.css?url";
 import { configureTracking } from "@agent-native/core/client";
+import changelog from "../CHANGELOG.md?raw";
 import { getThemeInitScript } from "@agent-native/core/client";
 import { TAB_ID } from "@/lib/tab-id";
 configureTracking({
@@ -162,7 +163,12 @@ function AppContent() {
 
   return (
     <>
-      <CommandMenu open={cmdkOpen} onOpenChange={setCmdkOpen}>
+      <CommandMenu
+        open={cmdkOpen}
+        onOpenChange={setCmdkOpen}
+        changelog={changelog}
+        changelogKey="slides"
+      >
         <CommandMenu.Group heading="Presentations">
           <CommandMenu.Item onSelect={() => {}}>Search decks</CommandMenu.Item>
         </CommandMenu.Group>