@vellumai/assistant 0.11.4 → 0.11.5-staging.1

package/src/cli/commands/memory/__tests__/memory-v2.test.ts

@@ -69,6 +69,7 @@ mock.module("../../../../util/logger.js", () => ({
 // ---------------------------------------------------------------------------
 
 const { registerMemoryV2Command } = await import("../memory-v2.js");
+const { registerMemoryValidateCommand } = await import("../memory-validate.js");
 
 // ---------------------------------------------------------------------------
 // Test helpers
@@ -88,6 +89,7 @@ function buildProgram(): Command {
   const memory = program.command("memory");
   applyCommandHelp(memory, memoryHelp);
   registerMemoryV2Command(memory);
+  registerMemoryValidateCommand(memory);
   return program;
 }
 
@@ -287,7 +289,7 @@ describe("memory v2 validate", () => {
       result: {
         pageCount: 0,
         edgeCount: 0,
-        missingEdgeEndpoints: [],
+        danglingLinks: [],
         oversizedPages: [],
         parseFailures: [],
       },
@@ -306,7 +308,7 @@ describe("memory v2 validate", () => {
       result: {
         pageCount: 49,
         edgeCount: 166,
-        missingEdgeEndpoints: [],
+        danglingLinks: [],
         oversizedPages: [],
         parseFailures: [],
       },
@@ -318,7 +320,7 @@ describe("memory v2 validate", () => {
     expect(logOutput.some((line) => line.includes("Pages: 49"))).toBe(true);
     expect(logOutput.some((line) => line.includes("Edges: 166"))).toBe(true);
     expect(
-      logOutput.some((line) => line.includes("Missing edge endpoints: none")),
+      logOutput.some((line) => line.includes("Dangling links: none")),
     ).toBe(true);
     expect(
       logOutput.some((line) => line.includes("Oversized pages: none")),
@@ -334,7 +336,9 @@ describe("memory v2 validate", () => {
       result: {
         pageCount: 10,
         edgeCount: 20,
-        missingEdgeEndpoints: [{ from: "people/alice", to: "people/missing" }],
+        danglingLinks: [
+          { from: "people/alice", to: "people/missing", kind: "links" },
+        ],
         oversizedPages: [{ slug: "arcs/big-day", chars: 12345 }],
         parseFailures: [
           { slug: "people/broken", error: "missing frontmatter" },
@@ -345,9 +349,11 @@ describe("memory v2 validate", () => {
     const { exitCode } = await runCommand(["memory", "v2", "validate"]);
 
     expect(exitCode).toBe(1);
-    expect(logOutput.some((line) => line.includes("people/missing"))).toBe(
-      true,
-    );
+    expect(
+      logOutput.some((line) =>
+        line.includes("people/alice → people/missing (links)"),
+      ),
+    ).toBe(true);
     expect(logOutput.some((line) => line.includes("arcs/big-day"))).toBe(true);
     expect(logOutput.some((line) => line.includes("people/broken"))).toBe(true);
   });
@@ -360,3 +366,47 @@ describe("memory v2 validate", () => {
     expect(exitCode).toBe(1);
   });
 });
+
+describe("memory validate (top-level, same report)", () => {
+  test("sends memory_v2_validate and prints the report", async () => {
+    mockIpcResult = {
+      ok: true,
+      result: {
+        pageCount: 49,
+        edgeCount: 166,
+        danglingLinks: [],
+        oversizedPages: [],
+        parseFailures: [],
+      },
+    };
+
+    const { exitCode } = await runCommand(["memory", "validate"]);
+
+    expect(exitCode).toBe(0);
+    expect(lastIpcCall!.method).toBe("memory_v2_validate");
+    expect(logOutput.some((line) => line.includes("Pages: 49"))).toBe(true);
+    expect(
+      logOutput.some((line) => line.includes("Dangling links: none")),
+    ).toBe(true);
+  });
+
+  test("exits non-zero on violations, like the v2 spelling", async () => {
+    mockIpcResult = {
+      ok: true,
+      result: {
+        pageCount: 1,
+        edgeCount: 0,
+        danglingLinks: [{ from: "a", to: "missing", kind: "wikilink" }],
+        oversizedPages: [],
+        parseFailures: [],
+      },
+    };
+
+    const { exitCode } = await runCommand(["memory", "validate"]);
+
+    expect(exitCode).toBe(1);
+    expect(
+      logOutput.some((line) => line.includes("a → missing (wikilink)")),
+    ).toBe(true);
+  });
+});

package/src/cli/commands/memory/index.help.ts

@@ -23,7 +23,7 @@ The 'items' subgroup exposes full CRUD over individual memory items
 
 The memory subsystem retrieves concept pages two ways: the v2 concept-page
 activation model (prose pages with directed edges) and the v3 section-lane
-model (section-grain lanes cached as live shadow state). Each subgroup exposes
+model (section-grain lanes held in memory inside the assistant). Each subgroup exposes
 operator-facing maintenance verbs — reindexing, backfills, validation, and evals.
 
 Examples:
@@ -34,7 +34,7 @@ Examples:
   $ assistant memory items list --search "coffee"
   $ assistant memory items update 9f2c4f3a-3f1a-41e4-88e7-abc123 --statement "Prefers tea"
   $ assistant memory items delete 9f2c4f3a-3f1a-41e4-88e7-abc123
-  $ assistant memory v2 validate
+  $ assistant memory validate
   $ assistant memory v3 rebuild-index
   $ assistant memory ingest --dir .mv3/staging --dry-run`,
   subcommands: [
@@ -43,8 +43,9 @@ Examples:
       description:
         "Content-based list, delete, and update of memory graph nodes",
       helpText: `
-Memory nodes are raw graph records (content, type, fidelity) produced by the
-memory v2 subsystem. Unlike 'memory items', which addresses nodes by UUID, these
+Memory nodes are raw graph records (content, type, fidelity) in the memory
+graph store, which every memory tier writes to. Unlike 'memory items', which
+addresses nodes by UUID, these
 commands address nodes by content text — matching the way an operator refers to
 a remembered fact without first looking up its ID.
 
@@ -390,7 +391,6 @@ except reembed-skills which runs synchronously inside the assistant.
 Read-only subcommands print diagnostic reports without mutating state.
 
 Examples:
-  $ assistant memory v2 validate
   $ assistant memory v2 reembed
   $ assistant memory v2 reembed-skills
   $ assistant memory v2 activation`,
@@ -400,9 +400,10 @@ Examples:
           description:
             "Refresh dense + sparse vectors for every concept page in Qdrant",
           helpText: `
-Fans out an embed_concept_page job per concept page slug (plus the four
-reserved meta-file slugs) so each page's dense and sparse vectors get
-recomputed against the current embedding backend. Useful after upgrading
+Fans out an embed_concept_page job per concept page slug so each page's
+dense and sparse vectors get recomputed against the current embedding
+backend (the direct-injected memory/*.md meta files are not embedded and are
+not enqueued). Useful after upgrading
 the embedding model or recovering a corrupted Qdrant collection.
 
 The fan-out runs on the background memory worker — this command returns
@@ -449,20 +450,13 @@ Examples:
         {
           name: "validate",
           description:
-            "Print a diagnostic report of v2 workspace state (read-only)",
+            "Same report as 'memory validate' (read-only concept-page check)",
           helpText: `
-Walks the v2 concept-page tree on disk and reports:
-  - Page count
-  - Edge count (total and unique outgoing targets)
-  - Missing outgoing edge targets (orphan edges)
-  - Oversized pages (over the per-folder size cap)
-  - Parse failures (missing or malformed frontmatter)
-
-Read-only — does not mutate the workspace. Exits non-zero if any
-violations are reported.
+Identical to 'assistant memory validate'; prefer that spelling. The report
+covers the concept-page store, which is the same under memory v2 and v3.
 
 Examples:
-  $ assistant memory v2 validate`,
+  $ assistant memory validate`,
         },
         {
           name: "ema",
@@ -600,9 +594,9 @@ Examples:
       name: "v3",
       description: "Memory v3 live-lane maintenance (section-lane model)",
       helpText: `
-The v3 memory subsystem retrieves concept pages over section-grain lanes and
-caches them as live shadow lanes inside the assistant. These commands maintain
-that live state safely.
+The v3 memory subsystem retrieves concept pages over section-grain lanes held
+in memory inside the assistant. These commands maintain that live state
+safely.
 
 Examples:
   $ assistant memory v3 rebuild-index
@@ -614,7 +608,7 @@ Examples:
           name: "rebuild-index",
           description: "Invalidate the v3 lanes so the next turn rebuilds",
           helpText: `
-Drops the assistant's cached v3 shadow lanes so the section index is rebuilt
+Drops the assistant's in-memory v3 lanes so the section index is rebuilt
 from the current on-disk state on the next turn. Useful after editing concept
 pages out-of-band.
 
@@ -635,10 +629,10 @@ Examples:
 Embeds EVERY concept page's sections — including synthetic skill and CLI
 capability rows — into the section dense store in one pass, then advances
 the maintain checkpoint so the next incremental pass only re-embeds future
-edits. Use this once on an existing install before the section-lane A/B and
-cutover: the dense collection starts empty, and the periodic maintenance
-pass only re-embeds pages edited since its last run (and never the synthetic
-rows), so most of the corpus would otherwise never be embedded.
+edits. Use this once on an install whose section dense store is empty or
+predates v3: the periodic maintenance pass only re-embeds pages edited since
+its last run (and never the synthetic rows), so most of the corpus would
+otherwise never be embedded.
 
 Idempotent and safe to re-run. Runs inside the assistant so it uses the live
 configuration and advances the checkpoint the assistant reads.
@@ -804,6 +798,26 @@ Example:
         },
       ],
     },
+    {
+      name: "validate",
+      description:
+        "Check the concept-page store for dangling links, oversized pages, and parse failures (read-only)",
+      helpText: `
+Walks memory/concepts/ on disk and reports:
+  - Page count and edge count
+  - Dangling links: an edges: entry, a links: entry, or an inline
+    [[wikilink]] whose target page does not exist (targets under skills/
+    and cli-commands/ resolve against the registered capability catalog)
+  - Oversized pages (over the configured per-page character cap)
+  - Parse failures (malformed frontmatter)
+
+Read-only. Exits non-zero if anything is reported. Works on every memory
+tier, including before memory.v3.live or memory.v2.enabled is set, so it
+doubles as the pre-flip check for a migration.
+
+Examples:
+  $ assistant memory validate`,
+    },
     {
       name: "ingest",
       description:

package/src/cli/commands/memory/index.ts

@@ -8,6 +8,7 @@ import { registerMemoryIngestCommand } from "./memory-ingest.js";
 import { registerMemoryRetrospectiveCommand } from "./memory-retrospective.js";
 import { registerMemoryV2Command } from "./memory-v2.js";
 import { registerMemoryV3Command } from "./memory-v3.js";
+import { registerMemoryValidateCommand } from "./memory-validate.js";
 import { registerMemoryNodesCommand } from "./nodes.js";
 import { registerMemoryWorkerCommand } from "./worker.js";
 
@@ -24,6 +25,7 @@ export function registerMemoryCommand(program: Command): void {
       registerMemoryV2Command(memory);
       registerMemoryV3Command(memory);
       registerMemoryIngestCommand(memory);
+      registerMemoryValidateCommand(memory);
       registerMemoryRetrospectiveCommand(memory);
       registerMemoryWorkerCommand(memory);
     },

package/src/cli/commands/memory/memory-v2.ts

@@ -12,8 +12,9 @@
  *     from the current skill set.
  *   - `activation` — refresh persisted activation state for every
  *     conversation that has a stored row.
- *   - `validate` — print a diagnostic report (page count, edge count, and
- *     violation lists). Does not mutate the workspace.
+ *   - `validate`: {@link runMemoryValidate}, also registered as the top-level
+ *     `memory validate` (`memory-validate.ts`); kept here while this
+ *     namespace exists.
  */
 
 import type { Command } from "commander";
@@ -59,6 +60,60 @@ async function runBackfillOp(op: MemoryV2BackfillOp): Promise<void> {
   log.info(`Queued ${op} job: ${result.result!.jobId}`);
 }
 
+/**
+ * Print the validate report; sets a non-zero exit code on any violation.
+ * Registered as `memory validate` (`memory-validate.ts`) and `memory v2
+ * validate`.
+ */
+export async function runMemoryValidate(): Promise<void> {
+  const result = await cliIpcCall<MemoryV2ValidateResult>(
+    "memory_v2_validate",
+    { body: {} },
+  );
+
+  if (!result.ok) {
+    log.error(result.error ?? "Failed to validate memory state");
+    process.exitCode = 1;
+    return;
+  }
+
+  const report = result.result!;
+  log.info(`Pages: ${report.pageCount}`);
+  log.info(`Edges: ${report.edgeCount}`);
+  log.info(
+    `Dangling links: ${
+      report.danglingLinks.length === 0 ? "none" : report.danglingLinks.length
+    }`,
+  );
+  for (const d of report.danglingLinks) {
+    log.info(`  - ${d.from} → ${d.to} (${d.kind})`);
+  }
+  log.info(
+    `Oversized pages: ${
+      report.oversizedPages.length === 0 ? "none" : report.oversizedPages.length
+    }`,
+  );
+  for (const p of report.oversizedPages) {
+    log.info(`  - ${p.slug}: ${p.chars} chars`);
+  }
+  log.info(
+    `Parse failures: ${
+      report.parseFailures.length === 0 ? "none" : report.parseFailures.length
+    }`,
+  );
+  for (const p of report.parseFailures) {
+    log.info(`  - ${p.slug}: ${p.error}`);
+  }
+
+  if (
+    report.danglingLinks.length > 0 ||
+    report.oversizedPages.length > 0 ||
+    report.parseFailures.length > 0
+  ) {
+    process.exitCode = 1;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Registration
 // ---------------------------------------------------------------------------
@@ -97,58 +152,7 @@ export function registerMemoryV2Command(memory: Command): void {
 
   // ── validate ──────────────────────────────────────────────────────────
 
-  subcommand(v2, "validate").action(async () => {
-    const result = await cliIpcCall<MemoryV2ValidateResult>(
-      "memory_v2_validate",
-      { body: {} },
-    );
-
-    if (!result.ok) {
-      log.error(result.error ?? "Failed to validate memory v2 state");
-      process.exitCode = 1;
-      return;
-    }
-
-    const report = result.result!;
-    log.info(`Pages: ${report.pageCount}`);
-    log.info(`Edges: ${report.edgeCount}`);
-    log.info(
-      `Missing edge endpoints: ${
-        report.missingEdgeEndpoints.length === 0
-          ? "none"
-          : report.missingEdgeEndpoints.length
-      }`,
-    );
-    for (const m of report.missingEdgeEndpoints) {
-      log.info(`  - ${m.from} → ${m.to}`);
-    }
-    log.info(
-      `Oversized pages: ${
-        report.oversizedPages.length === 0
-          ? "none"
-          : report.oversizedPages.length
-      }`,
-    );
-    for (const p of report.oversizedPages) {
-      log.info(`  - ${p.slug}: ${p.chars} chars`);
-    }
-    log.info(
-      `Parse failures: ${
-        report.parseFailures.length === 0 ? "none" : report.parseFailures.length
-      }`,
-    );
-    for (const p of report.parseFailures) {
-      log.info(`  - ${p.slug}: ${p.error}`);
-    }
-
-    if (
-      report.missingEdgeEndpoints.length > 0 ||
-      report.oversizedPages.length > 0 ||
-      report.parseFailures.length > 0
-    ) {
-      process.exitCode = 1;
-    }
-  });
+  subcommand(v2, "validate").action(runMemoryValidate);
 
   // ── ema ───────────────────────────────────────────────────────────────
 

package/src/cli/commands/memory/memory-validate.ts

@@ -0,0 +1,18 @@
+/**
+ * `assistant memory validate`: the read-only concept-page diagnostic.
+ *
+ * The report covers the concept-page substrate, which is the same store
+ * under memory v2 and v3, so the command is tier-agnostic. The report
+ * function lives in `memory-v2.ts` (the host file already allowed to read
+ * the memory plugin's route types) and is also registered there as
+ * `assistant memory v2 validate` for as long as that namespace exists.
+ */
+
+import type { Command } from "commander";
+
+import { subcommand } from "../../lib/cli-command-help.js";
+import { runMemoryValidate } from "./memory-v2.js";
+
+export function registerMemoryValidateCommand(memory: Command): void {
+  subcommand(memory, "validate").action(runMemoryValidate);
+}

package/src/cli/commands/monitoring.ts

@@ -56,6 +56,7 @@ interface LatestSample {
   memoryStat: {
     anonBytes: number | null;
     fileBytes: number | null;
+    inactiveFileBytes: number | null;
     kernelBytes: number | null;
     slabReclaimableBytes: number | null;
     slabUnreclaimableBytes: number | null;

package/src/cli/commands/plugins.help.ts

@@ -10,37 +10,12 @@ import {
 
 export const pluginsHelp: CliCommandHelp = {
   name: "plugins",
-  description:
-    "List, search, install, and manage external plugins (`list` shows what is installed, `search` queries the marketplace)",
+  description: "List, search, install, and manage plugins.",
   helpText: `
-Examples:
-  $ assistant plugins install example
-  $ assistant plugins install example --force
-  $ assistant plugins install https://github.com/owner/repo
-  $ assistant plugins install https://github.com/owner/repo/tree/main/sub/path --name my-plugin
-  $ assistant plugins install example --ref my-feature-branch
-  $ assistant plugins versions example
-  $ assistant plugins versions example --json
-  $ assistant plugins install example --pin <sha> --force
-  $ assistant plugins list
-  $ assistant plugins list --json
-  $ assistant plugins list --all
-  $ assistant plugins list --all --json
-  $ assistant plugins inspect example
-  $ assistant plugins inspect example --json
-  $ assistant plugins diff example
-  $ assistant plugins diff example --json
-  $ assistant plugins upgrade example
-  $ assistant plugins upgrade example --dry-run
-  $ assistant plugins upgrade example --strategy ours
-  $ assistant plugins upgrade example --strategy theirs
-  $ assistant plugins upgrade example --strategy assistant
-  $ assistant plugins search example
-  $ assistant plugins search "^example"
-  $ assistant plugins search example --json
-  $ assistant plugins uninstall example
-  $ assistant plugins enable example
-  $ assistant plugins disable example`,
+Plugins are superpowers: installable extensions that add skills, tools, integrations,
+and so much more from the Vellum Community. When the user asks to set up,
+install, connect, or integrate a product, service, or app, run
+'assistant plugins search <name>' first before searching the web.`,
   subcommands: [
     {
       name: "install",
@@ -79,6 +54,10 @@ during the install, and the install asks for confirmation before finalizing:
 schedules run automatically in the background once the plugin is installed.
 Pass --force to skip the prompt (required for non-interactive installs).
 
+A plugin that ships a setup skill (skills/setup/ or
+skills/<name>-setup/) prints a line after install telling the user to
+load that skill to finish setup.
+
 A GitHub URL (anything containing a slash) installs directly from that repo,
 bypassing the marketplace whitelist. Such a plugin is UNTRUSTED — it has not
 been reviewed and its hooks/tools run with full assistant access — so the
@@ -168,13 +147,31 @@ Examples:
       name: "search",
       args: "<query>",
       description:
-        "Search the plugins/marketplace.json catalog for plugin names matching <query> (case-insensitive regex)",
+        "Search the plugin marketplace. Query is a case-insensitive regex against plugin names",
       options: [
         {
           flags: "--json",
           description: "Emit machine-readable JSON instead of a table",
         },
       ],
+      helpText: `
+When to use:
+  First stop when the user asks to set up, install, connect, or integrate a
+  product, service, or app (for example "Setup <app> for me",
+  "connect this service"). Search here before searching the web.
+
+Arguments:
+  query    Case-insensitive regex matched against plugin names, not the full
+           user sentence. Use the product or plugin name. Anchors like
+           ^example work.
+
+If a match is found, install it with 'assistant plugins install <name>'.
+If nothing matches, try 'assistant skills search <query>', then web search.
+
+Examples:
+  $ assistant plugins search example
+  $ assistant plugins search "^example"
+  $ assistant plugins search example --json`,
     },
     {
       name: "publish",

package/src/cli/commands/plugins.ts

@@ -301,6 +301,16 @@ export function registerPluginsCommand(program: Command): void {
             console.log(
               `Installed ${label} "${result.name}" (${result.fileCount} file${result.fileCount === 1 ? "" : "s"})${pinned} → ${result.target}`,
             );
+            const { skills } = libs.surfaces.detectPluginSurfaces(
+              result.target,
+            );
+            const setupSkill = libs.surfaces.findPluginSetupSkill(
+              result.name,
+              skills,
+            );
+            if (setupSkill !== undefined) {
+              console.log(libs.surfaces.formatPluginSetupHint(setupSkill));
+            }
           } catch (err) {
             if (err instanceof libs.installGitHub.PluginInstallDeclinedError) {
               // The consent gate already printed the outcome and set the exit

package/src/cli/commands/skills.help.ts

@@ -6,21 +6,8 @@ export const skillsHelp: CliCommandHelp = {
   name: "skills",
   description: "Browse and install skills from the Vellum catalog",
   helpText: `
-Manage skills from the Vellum catalog. Skills extend the assistant's
-capabilities with pre-built workflows and tools.
-
-Examples:
-  $ assistant skills list
-  $ assistant skills list --json
-  $ assistant skills inspect slack
-  $ assistant skills inspect resend-setup --json
-  $ assistant skills search react
-  $ assistant skills search react --limit 5 --json
-  $ assistant skills install weather
-  $ assistant skills install weather --overwrite
-  $ assistant skills uninstall weather
-  $ assistant skills add vercel-labs/skills@find-skills
-  $ assistant skills add vercel-labs/skills/find-skills --overwrite`,
+Manage skills from the Vellum catalog. Skills are instructions of
+workflows and tools that teach the assistant when dynamically relevant.`,
   subcommands: [
     {
       name: "list",
@@ -70,15 +57,25 @@ Examples:
         { flags: "--json", description: "Machine-readable JSON output" },
       ],
       helpText: `
+When to use:
+  Second stop after plugin search when the user asks to set up, install, or
+  add a capability (for example "Setup <app> for me", "add a skill for file management").
+  Search here before searching the web.
+
 Arguments:
   query    Free-text search term matched against skill names, descriptions,
-           and tags. Searches the Vellum catalog, the skills.sh community
+           and tags. Use the product or capability name, not the full user
+           sentence. Searches the Vellum catalog, the skills.sh community
            registry, and the clawhub registry.
 
 Displays results from all sources with clear labels. When a skill ID
 exists in both the Vellum catalog and a community registry, a conflict
 note is shown with guidance on which install command to use.
 
+If a catalog match is found, install it with 'assistant skills install <id>'.
+If a community match is found, add it with 'assistant skills add <source>'.
+If nothing matches, try web search.
+
 Examples:
   $ assistant skills search react
   $ assistant skills search "file management" --limit 3

package/src/cli/commands/trust.ts

@@ -5,6 +5,7 @@
  * IPC route (`trust_rules_list`).
  */
 
+import type { TrustRulesListIpcResponse } from "@vellumai/gateway-client";
 import type { Command } from "commander";
 
 import { cliIpcCall } from "../../ipc/cli-client.js";
@@ -13,18 +14,6 @@ import { registerCommand } from "../lib/register-command.js";
 import { log } from "../logger.js";
 import { trustHelp } from "./trust.help.js";
 
-// -- Types --------------------------------------------------------------------
-
-interface TrustRule {
-  id: string;
-  tool: string;
-  pattern: string;
-  risk: string;
-  origin: string;
-  userModified: boolean;
-  updatedAt: string;
-}
-
 // -- Registration -------------------------------------------------------------
 
 export function registerTrustCommand(program: Command): void {
@@ -44,7 +33,7 @@ export function registerTrustCommand(program: Command): void {
             ...(opts.tool ? { tool: opts.tool } : {}),
           };
 
-          const result = await cliIpcCall<{ rules: TrustRule[] }>(
+          const result = await cliIpcCall<TrustRulesListIpcResponse>(
             "trust_rules_list",
             { body: params },
           );
@@ -86,7 +75,7 @@ export function registerTrustCommand(program: Command): void {
             "MODIFIED",
           ];
 
-          const rows: string[][] = rules.map((r: TrustRule) => [
+          const rows: string[][] = rules.map((r) => [
             r.id.slice(0, 16),
             r.tool,
             r.pattern,

package/src/cli/lib/__tests__/install-from-github.test.ts

@@ -303,6 +303,44 @@ describe("installPlugin — install lifecycle", () => {
     expect(existsSync(join(target, "README.md"))).toBe(true);
   });
 
+  test("--force keeps live config.json instead of a pin-shipped default", async () => {
+    // GIVEN an install with user config, and a clone that materializes a default
+    const target = join(pluginsDir, "caveman");
+    mkdirSync(target, { recursive: true });
+    writeFileSync(join(target, "package.json"), '{"name":"caveman"}');
+    writeFileSync(
+      join(target, "config.json"),
+      '{"provider":"photon","ingressMode":"live"}\n',
+    );
+    mkdirSync(join(target, "data"), { recursive: true });
+    writeFileSync(join(target, "data", "cursor.json"), '{"n":1}\n');
+
+    const fetch = makeContentsFetch({ tree: {}, manifest: CAVEMAN_MANIFEST });
+    const runGit = fakeGitRunner({
+      tree: {
+        "package.json": '{"name":"caveman"}',
+        "README.md": "# caveman",
+        "config.json": '{"provider":"comms","ingressMode":"webhook"}\n',
+      },
+      commit: CAVEMAN_SHA,
+    });
+
+    // WHEN we reinstall with --force
+    await installPlugin(
+      { name: "caveman", force: true, ref: "main" },
+      { fetch, runGit, workspacePluginsDir: pluginsDir },
+    );
+
+    // THEN user-owned state survives and the pin's default config does not win
+    expect(readFileSync(join(target, "config.json"), "utf-8")).toBe(
+      '{"provider":"photon","ingressMode":"live"}\n',
+    );
+    expect(readFileSync(join(target, "data", "cursor.json"), "utf-8")).toBe(
+      '{"n":1}\n',
+    );
+    expect(existsSync(join(target, "README.md"))).toBe(true);
+  });
+
   test("commitOverride materializes a specific commit, keeping repo from the manifest", async () => {
     // GIVEN a manifest pinning the current SHA, but an override to an older one
     const OLD_SHA = "1".repeat(40);