@paradigma-inc/flywheel 0.1.12 → 0.1.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paradigma-inc/flywheel",
-  "version": "0.1.12",
+  "version": "0.1.15",
   "description": "One-command setup for Flywheel MCP hosts",
   "type": "module",
   "files": [

package/skills/flywheel-auto/evals/evals.json

@@ -1,19 +1,19 @@
 [
   {
     "id": "continuation-from-existing-frontier",
-    "prompt": "Use $flywheel-auto at /Users/g.f.g.f./Documents/GitHub/paradigma/project/flywheel-setup/skills/flywheel-auto to continue a Flywheel frontier that already has a persisted control node. Keep going under the existing credit cap and do not ask again for the objective or budget unless the control node is missing or contradictory.",
+    "prompt": "Use $flywheel-auto to continue a Flywheel frontier that already has a persisted control node. Keep going under the existing credit cap and do not ask again for the objective or budget unless the control node is missing or contradictory.",
     "expected_output": "Read the persisted contract from the control node content before replanning, continue from that stored objective and budget, avoid re-asking for the objective or budget when the control node is coherent, and leave behind an updated control node plus staged or committed frontier work.",
     "files": []
   },
   {
     "id": "cold-start-with-non-credit-budget",
-    "prompt": "Use $flywheel-auto at /Users/g.f.g.f./Documents/GitHub/paradigma/project/flywheel-setup/skills/flywheel-auto to explore this frontier autonomously with at most $25 of managed-compute spend. Persist the dollar-denominated cap verbatim and derive whatever operational compute approval cap is needed before acquisition.",
+    "prompt": "Use $flywheel-auto to explore this frontier autonomously with at most $25 of managed-compute spend. Persist the dollar-denominated cap verbatim and derive whatever operational compute approval cap is needed before acquisition.",
     "expected_output": "Persist the dollar-denominated budget ceiling and unit verbatim in the control node, derive an operational compute approval cap before acquisition, record both values before any compute request is made, and leave a coherent run contract behind for later continuation.",
     "files": []
   },
   {
     "id": "cold-start-with-no-objective",
-    "prompt": "Use $flywheel-auto at /Users/g.f.g.f./Documents/GitHub/paradigma/project/flywheel-setup/skills/flywheel-auto to go autonomous on this Flywheel graph until you find something interesting. If I refuse to specify an objective, infer one from the graph context and make it explicit before you execute.",
+    "prompt": "Use $flywheel-auto to go autonomous on this Flywheel graph until you find something interesting. If I refuse to specify an objective, infer one from the graph context and make it explicit before you execute.",
     "expected_output": "Ask for an objective first, infer one from graph context if the user refuses, write that objective explicitly into the control node, and only then proceed toward execution with a coherent control node and frontier plan.",
     "files": []
   }

package/skills/flywheel-auto/references/INTERFACES.md

@@ -2,7 +2,7 @@
 
 Canonical reference for Flywheel user-facing interfaces and public contracts.
 
-Last updated: 2026-03-21
+Last updated: 2026-04-08
 
 ## Primary Clients
 
@@ -19,7 +19,8 @@ All interfaces operate on the same core entities:
 - artifact
 - execution
 - compute lease
-- budget grant
+- compute budget
+- compute grant (session-scoped)
 
 Node snapshots are the canonical durable contract for resume, review, and
 cross-client interoperability.
@@ -69,11 +70,12 @@ cross-client interoperability.
 - `GET /mcp/compute/connection`
 - `POST /mcp/compute/release`
 - `POST /mcp/compute/release-all`
-- `GET /mcp/nodes/{node_id}/budget/grants`
-- `GET /mcp/nodes/{node_id}/budget/campaign-grants`
-- `POST /mcp/nodes/{node_id}/budget/campaign-grants`
-- `PATCH /mcp/nodes/{node_id}/budget/campaign-grants/{budget_grant_id}`
-- `DELETE /mcp/nodes/{node_id}/budget/campaign-grants/{budget_grant_id}`
+- `GET /mcp/compute/grants`
+- `GET /mcp/nodes/{node_id}/budgets`
+- `GET /mcp/nodes/{root_node_id}/campaign-budgets`
+- `POST /mcp/nodes/{root_node_id}/campaign-budgets`
+- `PATCH /mcp/nodes/{root_node_id}/campaign-budgets/{compute_budget_id}`
+- `DELETE /mcp/nodes/{root_node_id}/campaign-budgets/{compute_budget_id}`
 
 ### Sharing, tags, and audit
 

package/skills/flywheel-lookahead/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: flywheel-lookahead
-description: Stage next-step frontier nodes from existing Flywheel graph state with Flywheel MCP up to depth `n` and width `k` without execution or compute acquisition. Use for planning what to do next, not claim validation, source-to-graph authoring, or autonomous execution.
+description: Stage a single-path next-step frontier from existing Flywheel graph state with Flywheel MCP using lookahead depth `n` and per-hop option width `k`, without execution or compute acquisition. Use for planning what to do next, not claim validation, source-to-graph authoring, or autonomous execution.
 ---
 
 # flywheel-lookahead
@@ -15,14 +15,14 @@ If exact tool or field semantics are unclear, load [references/flywheel-mcp-tool
 
 Before planning, recover or establish these inputs:
 
-- Required before planning: start nodes, objective, lookahead depth `n`, frontier width `k`, and an explicit terminal condition.
+- Required before planning: start nodes, objective, lookahead depth `n`, step option width `k`, and an explicit terminal condition.
 - Optional: budget ceiling and budget unit, but only when the user already supplied them or wants them tracked for later execution.
-- Defaults: `lookahead_depth` defaults to `n=1`; `frontier_width` defaults to `k=1`.
+- Defaults: `lookahead_depth` defaults to `n=1`; `step_option_width` defaults to `k=1`.
 - Recovery rules:
   - Ask only when a required planning input cannot be recovered from explicit user instructions, current conversational context, or recent graph state.
   - If start nodes cannot be recovered from explicit ids/slugs, named current context, or recent graph context, ask once.
   - If the objective is missing, ask once; if the user refuses, infer it from graph context and persist it before planning.
-  - If the terminal condition is missing, ask once; if it remains unspecified, persist a planning-local terminal condition such as stopping after staging this lookahead pass through the requested `n` hops and `k` branches.
+  - If the terminal condition is missing, ask once; if it remains unspecified, persist a planning-local terminal condition such as stopping after staging this lookahead pass through the requested `n` hops with at most `k` considered options per hop and one selected continuation per hop.
 
 ## Working Terms
 
@@ -31,6 +31,19 @@ Before planning, recover or establish these inputs:
 - `control node`: the dedicated `insight` node that stores the canonical planning contract for the current frontier.
 - `terminal condition`: the explicit condition that tells this planning pass when to stop staging additional frontier nodes.
 - `expected_revision`: the node's current revision token used for optimistic-locking writes.
+- `lookahead depth (n)`: the number of sequential hops in one planned path.
+- `step option width (k)`: the number of candidate directions evaluated at each hop before choosing one continuation.
+
+## Width Semantics (Unambiguous)
+
+- Lookahead depth `n`: number of sequential hops in one plan path.
+- Step option width `k`: number of candidate directions to evaluate at each hop.
+- Expansion rule: at hop `i`, generate up to `k` non-redundant options, select exactly 1 winner, and only that winner continues to hop `i+1`.
+- Graph shape for this mode: a single chain of `n` staged nodes (not `k` parallel branches).
+- Each step node must record:
+  - the `k` considered options,
+  - the selection criterion,
+  - the chosen continuation.
 
 ## Core Rules
 
@@ -51,7 +64,7 @@ Before planning, recover or establish these inputs:
    - The flywheel-lookahead skill requires a measurable objective. Ask once if it is missing; if the user refuses to specify one, infer it from the available graph context and state it explicitly before continuing.
    - Default `n=1` and `k=1` unless the user specified otherwise.
    - Persist the planning contract in a dedicated `insight` control node for this frontier. Put the canonical contract in node `content`, keep a one-line synopsis in `summary`, and keep brief planning rationale in `insights` so the commit contract stays valid.
-   - The control contract must name: objective, decision criterion, start nodes, lookahead depth `n`, frontier width `k`, and an explicit terminal condition. Only persist a budget ceiling and unit when the user already supplied one or wants them tracked for later execution.
+   - The control contract must name: objective, decision criterion, start nodes, lookahead depth `n`, step option width `k`, and an explicit terminal condition. Only persist a budget ceiling and unit when the user already supplied one or wants them tracked for later execution.
    - Later lookahead passes must read the control node `content` first and continue from that persisted contract rather than from chat memory.
 3. Map each stable page, claim, or concept to a node.
    - For exact node-mutation shapes, load [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md).
@@ -69,12 +82,14 @@ Before planning, recover or establish these inputs:
 6. Add graph structure sparingly.
    - Promote only decision-relevant relationships to edges.
    - Leave ordinary cross-links inside the markdown body.
-7. Expand the frontier deliberately.
+7. Expand the frontier as a single selected path.
    - Expand from the resolved frontier rather than mirroring the source corpus again.
-   - Depth `n` means plan `n` hops ahead from the currently resolved frontier. Default `n=1`.
-   - Width `k` means plan up to `k` distinct non-redundant frontier directions. Default `k=1`.
-   - Avoid redundant siblings that only restate the same branch with different wording.
-   - Keep unresolved plan nodes staged until the corresponding work is resolved.
+   - Depth `n` means plan `n` sequential hops ahead from the currently resolved frontier. Default `n=1`.
+   - Width `k` means evaluate up to `k` distinct non-redundant candidate directions at each hop. Default `k=1`.
+   - At each hop, stage the considered options in the step record, apply the selection criterion, and choose exactly one continuation.
+   - Only the chosen continuation advances to hop `i+1`; do not stage `k` parallel continuation branches for this mode.
+   - The staged graph shape for this mode is a single chain of up to `n` unresolved step nodes (shorter only when the terminal condition is met early).
+   - Each step node must record: the `k` considered options, the selection criterion used, and the chosen continuation.
 8. Commit after the node snapshot is coherent with `flywheel_commit_node`.
    - Commit resolved insight nodes only when they have non-empty `insights`.
    - Commit resolved empirical nodes only when outcome and artifact rules are satisfied.
@@ -85,7 +100,7 @@ Before planning, recover or establish these inputs:
 When the skill completes a pass, it should leave behind:
 
 - One persisted `insight` control node containing the canonical planning contract.
-- Zero or more staged next-step frontier nodes up to the current `n` and `k` limits.
+- A single staged next-step chain up to the current `n` limit where each hop records up to `k` considered options and one selected continuation.
 - Updated node summaries, rationale, and edges only where the current planning pass justifies them.
 - No hidden execution, no compute approval, and no managed compute acquisition.
 
@@ -114,7 +129,7 @@ Canonical contract shape:
 - Decision criterion:
 - Start nodes:
 - Lookahead depth:
-- Frontier width:
+- Step option width:
 - Terminal condition:
 - Budget ceiling: optional
 - Budget unit: optional

package/skills/flywheel-lookahead/evals/evals.json

@@ -13,8 +13,8 @@
   },
   {
     "id": "planning-only-with-explicit-depth-and-width",
-    "prompt": "Use $flywheel-lookahead to stage two hops of next-step work across three non-redundant branches from the current Flywheel frontier. Plan only for later work and do not execute anything.",
-    "expected_output": "Persist `n=2` and `k=3` in the planning contract, stage non-redundant frontier nodes up to those limits, and avoid compute approval, managed compute acquisition, or execution launch.",
+    "prompt": "Use $flywheel-lookahead to stage two sequential hops of next-step work while evaluating up to three non-redundant options at each hop from the current Flywheel frontier. Plan only for later work and do not execute anything.",
+    "expected_output": "Persist `n=2` and `k=3` in the planning contract, evaluate up to three non-redundant options at each hop, record the considered options plus selection criterion plus chosen continuation for each step node, continue only along the single chosen path, and avoid compute approval, managed compute acquisition, or execution launch.",
     "files": []
   }
 ]

package/skills/flywheel-lookahead/references/INTERFACES.md

@@ -2,7 +2,7 @@
 
 Canonical reference for Flywheel user-facing interfaces and public contracts.
 
-Last updated: 2026-03-21
+Last updated: 2026-04-08
 
 ## Primary Clients
 
@@ -19,7 +19,8 @@ All interfaces operate on the same core entities:
 - artifact
 - execution
 - compute lease
-- budget grant
+- compute budget
+- compute grant (session-scoped)
 
 Node snapshots are the canonical durable contract for resume, review, and
 cross-client interoperability.
@@ -69,11 +70,12 @@ cross-client interoperability.
 - `GET /mcp/compute/connection`
 - `POST /mcp/compute/release`
 - `POST /mcp/compute/release-all`
-- `GET /mcp/nodes/{node_id}/budget/grants`
-- `GET /mcp/nodes/{node_id}/budget/campaign-grants`
-- `POST /mcp/nodes/{node_id}/budget/campaign-grants`
-- `PATCH /mcp/nodes/{node_id}/budget/campaign-grants/{budget_grant_id}`
-- `DELETE /mcp/nodes/{node_id}/budget/campaign-grants/{budget_grant_id}`
+- `GET /mcp/compute/grants`
+- `GET /mcp/nodes/{node_id}/budgets`
+- `GET /mcp/nodes/{root_node_id}/campaign-budgets`
+- `POST /mcp/nodes/{root_node_id}/campaign-budgets`
+- `PATCH /mcp/nodes/{root_node_id}/campaign-budgets/{compute_budget_id}`
+- `DELETE /mcp/nodes/{root_node_id}/campaign-budgets/{compute_budget_id}`
 
 ### Sharing, tags, and audit
 

package/skills/flywheel-reproduce/references/INTERFACES.md

@@ -2,7 +2,7 @@
 
 Canonical reference for Flywheel user-facing interfaces and public contracts.
 
-Last updated: 2026-03-21
+Last updated: 2026-04-08
 
 ## Primary Clients
 
@@ -19,7 +19,8 @@ All interfaces operate on the same core entities:
 - artifact
 - execution
 - compute lease
-- budget grant
+- compute budget
+- compute grant (session-scoped)
 
 Node snapshots are the canonical durable contract for resume, review, and
 cross-client interoperability.
@@ -69,11 +70,12 @@ cross-client interoperability.
 - `GET /mcp/compute/connection`
 - `POST /mcp/compute/release`
 - `POST /mcp/compute/release-all`
-- `GET /mcp/nodes/{node_id}/budget/grants`
-- `GET /mcp/nodes/{node_id}/budget/campaign-grants`
-- `POST /mcp/nodes/{node_id}/budget/campaign-grants`
-- `PATCH /mcp/nodes/{node_id}/budget/campaign-grants/{budget_grant_id}`
-- `DELETE /mcp/nodes/{node_id}/budget/campaign-grants/{budget_grant_id}`
+- `GET /mcp/compute/grants`
+- `GET /mcp/nodes/{node_id}/budgets`
+- `GET /mcp/nodes/{root_node_id}/campaign-budgets`
+- `POST /mcp/nodes/{root_node_id}/campaign-budgets`
+- `PATCH /mcp/nodes/{root_node_id}/campaign-budgets/{compute_budget_id}`
+- `DELETE /mcp/nodes/{root_node_id}/campaign-budgets/{compute_budget_id}`
 
 ### Sharing, tags, and audit
 

package/skills/flywheel-to-graph/references/INTERFACES.md

@@ -2,7 +2,7 @@
 
 Canonical reference for Flywheel user-facing interfaces and public contracts.
 
-Last updated: 2026-03-21
+Last updated: 2026-04-08
 
 ## Primary Clients
 
@@ -19,7 +19,8 @@ All interfaces operate on the same core entities:
 - artifact
 - execution
 - compute lease
-- budget grant
+- compute budget
+- compute grant (session-scoped)
 
 Node snapshots are the canonical durable contract for resume, review, and
 cross-client interoperability.
@@ -69,11 +70,12 @@ cross-client interoperability.
 - `GET /mcp/compute/connection`
 - `POST /mcp/compute/release`
 - `POST /mcp/compute/release-all`
-- `GET /mcp/nodes/{node_id}/budget/grants`
-- `GET /mcp/nodes/{node_id}/budget/campaign-grants`
-- `POST /mcp/nodes/{node_id}/budget/campaign-grants`
-- `PATCH /mcp/nodes/{node_id}/budget/campaign-grants/{budget_grant_id}`
-- `DELETE /mcp/nodes/{node_id}/budget/campaign-grants/{budget_grant_id}`
+- `GET /mcp/compute/grants`
+- `GET /mcp/nodes/{node_id}/budgets`
+- `GET /mcp/nodes/{root_node_id}/campaign-budgets`
+- `POST /mcp/nodes/{root_node_id}/campaign-budgets`
+- `PATCH /mcp/nodes/{root_node_id}/campaign-budgets/{compute_budget_id}`
+- `DELETE /mcp/nodes/{root_node_id}/campaign-budgets/{compute_budget_id}`
 
 ### Sharing, tags, and audit
 

package/src/cli.mjs

@@ -2,7 +2,7 @@ import { Command } from "commander";
 import { checkbox, confirm, select } from "@inquirer/prompts";
 import ora from "ora";
 import pc from "picocolors";
-import { rm } from "node:fs/promises";
+import { readFile, rm } from "node:fs/promises";
 import path from "node:path";
 import { randomBytes } from "node:crypto";
 
@@ -39,6 +39,8 @@ import {
   installBundledSkillForHosts,
   listBundledSkills,
   partitionInstallSkillHosts,
+  removeInstalledSkillsForHosts,
+  SUPPORTED_INSTALL_SKILL_HOSTS,
   resolveInstalledSkillDir,
   resolvePackageRoot,
 } from "./skill-installer.mjs";
@@ -751,6 +753,106 @@ function scopesFromUninstallScope(scope) {
   return scope === "all" ? ["global", "project"] : [scope];
 }
 
+function keyPath(configKey) {
+  return Array.isArray(configKey) ? configKey : [configKey];
+}
+
+function readConfigSection(config, configKey) {
+  const pathParts = keyPath(configKey);
+  let current = config && typeof config === "object" ? config : {};
+  for (const part of pathParts) {
+    if (
+      !current ||
+      typeof current !== "object" ||
+      Array.isArray(current) ||
+      !(part in current)
+    ) {
+      return {};
+    }
+    const next = current[part];
+    if (!next || typeof next !== "object" || Array.isArray(next)) {
+      return {};
+    }
+    current = next;
+  }
+  return current;
+}
+
+function parseTomlServerNames(tomlText) {
+  const serverNames = new Set();
+  for (const line of String(tomlText || "").replace(/\r\n/g, "\n").split("\n")) {
+    const match = line.trim().match(/^\[mcp_servers\.([A-Za-z0-9_-]+)\](?:\s*#.*)?$/);
+    if (!match) {
+      continue;
+    }
+    serverNames.add(match[1]);
+  }
+  return [...serverNames].sort();
+}
+
+function isLikelyFlywheelMcpUrl(url) {
+  if (typeof url !== "string" || url.trim().length === 0) {
+    return false;
+  }
+  try {
+    const parsed = new URL(url);
+    return parsed.pathname === "/mcp-server";
+  } catch {
+    return false;
+  }
+}
+
+async function listHostMcpEntries(hostName, scope) {
+  const host = getHost(hostName);
+  const filePath = await resolveMcpPath(mcpCandidatesForScope(host, scope));
+
+  if (host.mcp.configType === "toml") {
+    let raw = "";
+    try {
+      raw = await readFile(filePath, "utf8");
+    } catch {
+      return [];
+    }
+    const entries = [];
+    for (const serverName of parseTomlServerNames(raw)) {
+      // eslint-disable-next-line no-await-in-loop
+      const entry = await readTomlServerEntry(filePath, serverName);
+      if (!entry.exists) {
+        continue;
+      }
+      entries.push({
+        serverName,
+        url: typeof entry.url === "string" ? entry.url : null,
+      });
+    }
+    return entries;
+  }
+
+  const config =
+    host.mcp.configType === "yaml"
+      ? await readYamlConfig(filePath)
+      : await readJsonConfig(filePath);
+  const section = readConfigSection(config, host.mcp.configKey);
+  return Object.entries(section)
+    .filter(([, entry]) => entry && typeof entry === "object" && !Array.isArray(entry))
+    .map(([serverName, entry]) => ({
+      serverName,
+      url: typeof entry.url === "string" ? entry.url : null,
+    }));
+}
+
+async function resolveHostsWithRemainingFlywheelMcpEntries({ scope }) {
+  const remainingHosts = [];
+  for (const hostName of SUPPORTED_INSTALL_SKILL_HOSTS) {
+    // eslint-disable-next-line no-await-in-loop
+    const hostEntries = await listHostMcpEntries(hostName, scope).catch(() => []);
+    if (hostEntries.some((entry) => isLikelyFlywheelMcpUrl(entry.url))) {
+      remainingHosts.push(hostName);
+    }
+  }
+  return remainingHosts;
+}
+
 async function isConfiguredForUninstallScope(hostName, scope, serverName) {
   const scopes = scopesFromUninstallScope(scope);
   for (const singleScope of scopes) {
@@ -907,26 +1009,118 @@ async function runUninstallCommand(options) {
   const { scope, hosts } = resolved;
   const scopes = scopesFromUninstallScope(scope);
 
-  const spinner = ora("Removing Flywheel MCP entries...").start();
-  const results = [];
+  const mcpSpinner = ora("Removing Flywheel MCP entries...").start();
+  const mcpResults = [];
   for (const singleScope of scopes) {
     for (const host of hosts) {
-      spinner.text = `Removing from ${getHost(host).displayName} (${singleScope})...`;
+      mcpSpinner.text = `Removing from ${getHost(host).displayName} (${singleScope})...`;
       // eslint-disable-next-line no-await-in-loop
-      results.push(await removeHostConfig(host, singleScope, serverName));
+      mcpResults.push(await removeHostConfig(host, singleScope, serverName));
+    }
+  }
+  mcpSpinner.succeed("MCP uninstall complete");
+
+  const { supportedHosts, unsupportedHosts } =
+    partitionInstallSkillHosts(hosts);
+  const bundledSkillResults = [];
+  let bundledSkillNames = [];
+
+  if (supportedHosts.length > 0) {
+    const packageRoot = resolvePackageRoot();
+    bundledSkillNames = await listBundledSkills(packageRoot);
+    if (bundledSkillNames.length > 0) {
+      const skillSpinner = ora("Removing Flywheel bundled skills...").start();
+      for (const singleScope of scopes) {
+        // Prevent deleting shared skill directories while non-selected hosts
+        // mapped to the same location still have Flywheel MCP entries.
+        // eslint-disable-next-line no-await-in-loop
+        const configuredRetainHostNames = await resolveHostsWithRemainingFlywheelMcpEntries({
+          scope: singleScope,
+        });
+        skillSpinner.text = `Removing bundled skills from ${supportedHosts.length} host(s) (${singleScope})...`;
+        // eslint-disable-next-line no-await-in-loop
+        bundledSkillResults.push(
+          ...(await removeInstalledSkillsForHosts({
+            projectRoot: process.cwd(),
+            hostNames: supportedHosts,
+            retainHostNames: configuredRetainHostNames,
+            scope: singleScope,
+            skillNames: bundledSkillNames,
+          })),
+        );
+      }
+      skillSpinner.succeed("Bundled skill uninstall complete");
     }
   }
-  spinner.succeed("Uninstall complete");
 
   log.blank();
-  log.plain(pc.green("✔ Flywheel uninstall complete"));
+  log.plain(pc.green("✔ Flywheel uninstall complete (MCP entries and bundled skills)"));
   log.blank();
-  for (const result of results) {
+  for (const result of mcpResults) {
     const icon = result.status === "removed" ? pc.green("-") : pc.dim("~");
     log.plain(`  ${pc.bold(result.host)} ${pc.dim(`(${result.scope})`)}`);
     log.plain(`    ${icon} ${result.status}`);
     log.plain(`      ${pc.dim(result.filePath)}`);
   }
+
+  log.blank();
+  log.plain(`  ${pc.bold("Bundled skills")}`);
+  if (supportedHosts.length === 0) {
+    log.plain(`    ${pc.dim("~")} no skill-supporting hosts selected`);
+  } else if (bundledSkillNames.length === 0) {
+    log.plain(`    ${pc.dim("~")} no bundled skills found in this package`);
+  } else {
+    const groupedSkillResults = new Map();
+    for (const skillResult of bundledSkillResults) {
+      for (const hostName of skillResult.hostNames) {
+        const groupingKey = `${hostName}:${skillResult.scope}`;
+        const existingGroup = groupedSkillResults.get(groupingKey);
+        if (existingGroup) {
+          existingGroup.entries.push(skillResult);
+          continue;
+        }
+        groupedSkillResults.set(groupingKey, {
+          hostName,
+          scope: skillResult.scope,
+          entries: [skillResult],
+        });
+      }
+    }
+
+    const sortedGroups = [...groupedSkillResults.values()].sort((left, right) => {
+      const leftKey = `${left.hostName}:${left.scope}`;
+      const rightKey = `${right.hostName}:${right.scope}`;
+      return leftKey.localeCompare(rightKey);
+    });
+    for (const groupedResult of sortedGroups) {
+      log.plain(
+        `  ${pc.bold(getHost(groupedResult.hostName).displayName)} ${pc.dim(`(${groupedResult.scope})`)}`,
+      );
+      for (const entry of groupedResult.entries) {
+        const icon =
+          entry.status === "removed"
+            ? pc.green("-")
+            : entry.status === "retained"
+              ? pc.yellow("~")
+              : pc.dim("~");
+        const retainedSuffix =
+          entry.status === "retained" && Array.isArray(entry.retainedHostNames)
+            ? ` (shared with configured host(s): ${entry.retainedHostNames.join(", ")})`
+            : "";
+        log.plain(`    ${icon} ${entry.status}${retainedSuffix}: ${entry.skillNames.join(", ")}`);
+        log.plain(`      ${pc.dim(entry.installedSkillDir)}`);
+      }
+    }
+  }
+
+  for (const unsupportedHostName of unsupportedHosts) {
+    for (const singleScope of scopes) {
+      log.plain(
+        `  ${pc.bold(getHost(unsupportedHostName).displayName)} ${pc.dim(`(${singleScope})`)}`,
+      );
+      log.plain(`    ${pc.dim("~")} skill uninstall not supported (MCP-only host)`);
+    }
+  }
   log.blank();
 }
 
@@ -986,7 +1180,7 @@ Examples:
 
   program
     .command("uninstall")
-    .description("Remove Flywheel MCP entries from host configs")
+    .description("Remove Flywheel MCP entries and bundled skills from selected hosts")
     .option("--claude", "Uninstall for Claude Code")
     .option("--opencode", "Uninstall for OpenCode")
     .option("--codex", "Uninstall for Codex")

package/src/skill-installer.mjs

@@ -397,6 +397,90 @@ export async function installBundledSkillForHosts({
   }
 }
 
+export async function removeInstalledSkillsForHosts({
+  projectRoot = process.cwd(),
+  hostNames = [],
+  retainHostNames = [],
+  scope = "project",
+  skillNames,
+} = {}) {
+  const normalizedScope = normalizeInstallScope(scope);
+  const normalizedSkillNames = normalizeBundledSkillNames(skillNames);
+  const normalizedRetainHostNames = uniqueValues(retainHostNames);
+  const removalTargetsByPath = new Map();
+  const retainedTargetsByPath = new Map();
+
+  for (const hostName of uniqueValues(hostNames)) {
+    for (const skillName of normalizedSkillNames) {
+      const installedSkillDir = resolveInstalledSkillDir(
+        projectRoot,
+        hostName,
+        normalizedScope,
+        skillName,
+      );
+      const existingTarget = removalTargetsByPath.get(installedSkillDir);
+      if (existingTarget) {
+        existingTarget.hostNames.add(hostName);
+        existingTarget.skillNames.add(skillName);
+        continue;
+      }
+      removalTargetsByPath.set(installedSkillDir, {
+        installedSkillDir,
+        hostNames: new Set([hostName]),
+        skillNames: new Set([skillName]),
+      });
+    }
+  }
+
+  for (const hostName of normalizedRetainHostNames) {
+    for (const skillName of normalizedSkillNames) {
+      const installedSkillDir = resolveInstalledSkillDir(
+        projectRoot,
+        hostName,
+        normalizedScope,
+        skillName,
+      );
+      const existingRetainedTarget = retainedTargetsByPath.get(installedSkillDir);
+      if (existingRetainedTarget) {
+        existingRetainedTarget.hostNames.add(hostName);
+        continue;
+      }
+      retainedTargetsByPath.set(installedSkillDir, {
+        hostNames: new Set([hostName]),
+      });
+    }
+  }
+
+  const removalResults = [];
+  for (const removalTarget of [...removalTargetsByPath.values()].sort((left, right) =>
+    left.installedSkillDir.localeCompare(right.installedSkillDir),
+  )) {
+    const hadInstalledSkillDir = await pathExists(removalTarget.installedSkillDir);
+    const retainedTarget = retainedTargetsByPath.get(removalTarget.installedSkillDir);
+    if (retainedTarget) {
+      removalResults.push({
+        scope: normalizedScope,
+        installedSkillDir: removalTarget.installedSkillDir,
+        hostNames: [...removalTarget.hostNames].sort(),
+        retainedHostNames: [...retainedTarget.hostNames].sort(),
+        skillNames: [...removalTarget.skillNames].sort(),
+        status: hadInstalledSkillDir ? "retained" : "not present",
+      });
+      continue;
+    }
+    await rm(removalTarget.installedSkillDir, { recursive: true, force: true });
+    removalResults.push({
+      scope: normalizedScope,
+      installedSkillDir: removalTarget.installedSkillDir,
+      hostNames: [...removalTarget.hostNames].sort(),
+      skillNames: [...removalTarget.skillNames].sort(),
+      status: hadInstalledSkillDir ? "removed" : "not present",
+    });
+  }
+
+  return removalResults;
+}
+
 async function rewriteOpenAiAgentMetadataMcpTarget({
   skillDir,
   serverName,