@paradigma-inc/flywheel 0.1.73 → 0.1.77

package/skills/flywheel-reproduce/references/flywheel-cli-tool-map.md

@@ -123,8 +123,6 @@ These commands have no MCP counterpart. They cover auth/profile management, acco
 - `flywheel nodes:create` (mutating; scopes: `write`): Create a minimal node (title only) and emit graph-change event.
 - `flywheel nodes:files` (read; scopes: `read`): List files attached to a node.
 - `flywheel nodes:sharing:summaries` (read; scopes: `read`): Read access summaries for multiple nodes in one batch.
-- `flywheel nodes:stage:backfill:hypothesis` (mutating; scopes: `write`): Derive hypothesis from staged node content.
-- `flywheel nodes:stage:backfill:insights` (mutating; scopes: `write`): Extract structured insights from staged node content.
 
 ### Artifact helpers (CLI-only)
 

package/skills/flywheel-reproduce/references/flywheel-mcp-tool-map.md

@@ -8,19 +8,17 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 
 - Use `flywheel_get_contract` + `flywheel_get_contract_section` as canonical contract references.
 - Node state is canonical durable state; avoid relying on ephemeral transcript state.
-- Node kind (`untyped`, `empirical`, `insight`) is an explicit durable field.
+- Node body state is `title`, Markdown `content`, and optional `summary`; represent observations, decisions, experiments, and evidence with Markdown structure, tags, artifacts, and executions.
 - Node references include immutable `node_id` and optional immutable `slug_name`; prefer communicating both together for human clarity and disambiguation.
-- Insight nodes should represent conceptual observations (theoretical insights, intuitions, motivations, decision-relevant framing); empirical nodes should represent experiments with explicit hypotheses and measured outcomes.
 - Graph topology should encode logical/causal relations between concepts and experiments. Avoid defaulting to shallow root-only branching unless work items are truly independent.
 - Node staging is local (non-canonical) and commit is the only canonical persistence boundary (`commit_new_node`, `commit_node`).
 - Mutating node writes are optimistic-locking operations: read latest state, pass `expected_revision` or `base_committed_revision` as required, and handle `409 conflict` with explicit reconciliation.
 - Mutating operations are idempotent; MCP tool transport auto-manages `Idempotency-Key` on mutating tool calls.
 - Existing-node field editing may use a session-scoped stage lease (`flywheel_acquire_stage_lease`, `flywheel_heartbeat_stage_lease`, `flywheel_release_stage_lease`) to coordinate local staged state before commit.
 - Existing-node commit publishes a full staged payload under an active stage lease: commit requests require `stage_session_id`, `base_committed_revision`, and `staged_payload`; conflicts on stale committed revisions are surfaced directly and are not transport-retried.
-- Stage/backfill helpers (`stage_backfill_hypothesis`, `stage_backfill_insights`) return non-canonical staged payload patches and explicit status fields (`staged_changes_pending`, `commit_required`, `next_action_hint`).
-- Committed node state must still satisfy strict contract (`summary` required; `empirical` requires hypothesis plus artifacts or `no_artifacts_reason`; `insight` requires non-empty insights).
+- Committed node state uses the same canonical body fields for every node; `summary` may be empty when the node body is intentionally represented by content, artifacts, tags, or executions.
 - When code is involved, pass `repo_url`/`branch_name`/`head_commit_sha` and align git structure with graph topology where practical (without forcing one-to-one mapping).
-- Summaries, hypotheses, and artifacts should be reproduction-grade: enough setup, method, evidence, and interpretation for another reader to reproduce or audit results.
+- Content, summaries, and artifacts should be reproduction-grade: enough setup, method, evidence, and interpretation for another reader to reproduce or audit results.
 - Empirical workflow is hypothesis-driven: launch execution, inspect outcomes, publish evidence artifacts, and commit only after terminal status.
 - For empirical work, publish evidence with `flywheel_prepare_artifact_uploads`, upload raw file bytes, then `flywheel_finalize_artifact_uploads` before commit.
 - Artifact metadata records expose a non-empty `title` suitable for display labels; title normalization must never derive from `storage_url`.
@@ -135,7 +133,7 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 8. `flywheel_list_executions`: Poll until execution reaches terminal status.
 9. `flywheel_prepare_artifact_uploads`: Prepare signed upload URLs for empirical evidence.
 10. `raw_file_upload`: Upload raw bytes to each signed URL with required headers.
-11. `flywheel_finalize_artifact_uploads`: Finalize prepared uploads before commit, or set `no_artifacts_reason` when intentionally artifact-free.
+11. `flywheel_finalize_artifact_uploads`: Finalize prepared uploads before commit when the work produced evidence artifacts.
 12. `flywheel_commit_node`: Commit terminal empirical node once contract requirements are satisfied.
 
 ## Runtime Guidance

package/skills/flywheel-to-graph/SKILL.md

@@ -64,8 +64,7 @@ Before authoring, recover or establish these inputs:
    - Create a new node with `flywheel_commit_new_node` (MCP) or `flywheel nodes:commit-new` (CLI) when needed.
    - Update an existing node with `flywheel_get_node` + `flywheel_acquire_stage_lease` + `flywheel_commit_node` (MCP) or `flywheel nodes:get` + `flywheel nodes:stage:lease:acquire` + `flywheel nodes:commit` (CLI) when continuing work.
 4. Put the primary page markdown or source narrative in the node body/readme field (`content`).
-   - Keep `summary` concise.
-   - Populate `hypothesis`, `insights`, `outcome`, and similar fields only when the source actually supports them.
+   - Put claims, rationale, methods, outcomes, and continuation notes in `content`; keep `summary` concise.
 5. Publish supporting files with the artifact upload flow.
    - For exact artifact contract details, load [references/ARTIFACTS.md](references/ARTIFACTS.md).
    - Use `flywheel_prepare_artifact_uploads` (MCP) or `flywheel artifacts:upload:prepare` (CLI).
@@ -90,7 +89,7 @@ When the skill completes a pass, it should leave behind:
 
 ## Persisted Authoring Contract
 
-When the source-to-graph work spans multiple pages or multiple passes, use a dedicated `insight` node as the durable authoring controller for that corpus. Do not rely on unstated product fields or fresh chat context.
+When the source-to-graph work spans multiple pages or multiple passes, use a dedicated node as the durable authoring controller for that corpus. Do not rely on unstated product fields or fresh chat context.
 
 For the canonical entity model and public contract terminology behind this controller, load [references/INTERFACES.md](references/INTERFACES.md).
 
@@ -99,7 +98,7 @@ Use this storage convention:
 1. Reuse an existing authoring control node when one already governs the same corpus; otherwise create one with `flywheel_commit_new_node` (MCP) or `flywheel nodes:commit-new` (CLI).
 2. Put the canonical authoring contract in node `content`.
 3. Put a one-line synopsis in `summary`.
-4. Put the current mapping rationale or continuation note in `insights` so the `insight` commit contract is satisfied.
+4. Put the current mapping rationale or continuation note in `content`.
 5. Before committing control-node edits, acquire or refresh the stage lease with `flywheel_acquire_stage_lease` (and `flywheel_heartbeat_stage_lease` for long edits) — or in CLI mode, `flywheel nodes:stage:lease:acquire` and `flywheel nodes:stage:lease:heartbeat`.
 6. Read the control node with `flywheel_get_node` (MCP) or `flywheel nodes:get` (CLI) before later passes that need a fresh `expected_revision`.
 7. Commit the control node with `flywheel_commit_node` (MCP) or `flywheel nodes:commit` (CLI) once the contract is coherent, even if downstream source nodes remain staged or in progress.

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

@@ -19,9 +19,10 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 ## Canonical Entity Model
 
 - Canonical durable entity: `node`.
-- Node kind values: `untyped`, `empirical`, `insight`.
+- Canonical node body fields: `title`, Markdown `content`, and optional `summary`.
 - Node references: `node_id`, `slug_name`.
 - `slug_name` format: `adjective-noun-####` (immutable when present).
+- Removed typed node body fields (`kind`, `node_type`, `hypothesis`, `insights`, `no_artifacts_reason`) are not write fields.
 - Approval sessions and compute grants are distinct entities; approvals are session-scoped bindings.
 - Campaign projections are derived from root config and attempt submission JSON artifacts.
 

package/skills/flywheel-to-graph/references/flywheel-cli-tool-map.md

@@ -123,8 +123,6 @@ These commands have no MCP counterpart. They cover auth/profile management, acco
 - `flywheel nodes:create` (mutating; scopes: `write`): Create a minimal node (title only) and emit graph-change event.
 - `flywheel nodes:files` (read; scopes: `read`): List files attached to a node.
 - `flywheel nodes:sharing:summaries` (read; scopes: `read`): Read access summaries for multiple nodes in one batch.
-- `flywheel nodes:stage:backfill:hypothesis` (mutating; scopes: `write`): Derive hypothesis from staged node content.
-- `flywheel nodes:stage:backfill:insights` (mutating; scopes: `write`): Extract structured insights from staged node content.
 
 ### Artifact helpers (CLI-only)
 

package/skills/flywheel-to-graph/references/flywheel-mcp-tool-map.md

@@ -8,19 +8,17 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 
 - Use `flywheel_get_contract` + `flywheel_get_contract_section` as canonical contract references.
 - Node state is canonical durable state; avoid relying on ephemeral transcript state.
-- Node kind (`untyped`, `empirical`, `insight`) is an explicit durable field.
+- Node body state is `title`, Markdown `content`, and optional `summary`; represent observations, decisions, experiments, and evidence with Markdown structure, tags, artifacts, and executions.
 - Node references include immutable `node_id` and optional immutable `slug_name`; prefer communicating both together for human clarity and disambiguation.
-- Insight nodes should represent conceptual observations (theoretical insights, intuitions, motivations, decision-relevant framing); empirical nodes should represent experiments with explicit hypotheses and measured outcomes.
 - Graph topology should encode logical/causal relations between concepts and experiments. Avoid defaulting to shallow root-only branching unless work items are truly independent.
 - Node staging is local (non-canonical) and commit is the only canonical persistence boundary (`commit_new_node`, `commit_node`).
 - Mutating node writes are optimistic-locking operations: read latest state, pass `expected_revision` or `base_committed_revision` as required, and handle `409 conflict` with explicit reconciliation.
 - Mutating operations are idempotent; MCP tool transport auto-manages `Idempotency-Key` on mutating tool calls.
 - Existing-node field editing may use a session-scoped stage lease (`flywheel_acquire_stage_lease`, `flywheel_heartbeat_stage_lease`, `flywheel_release_stage_lease`) to coordinate local staged state before commit.
 - Existing-node commit publishes a full staged payload under an active stage lease: commit requests require `stage_session_id`, `base_committed_revision`, and `staged_payload`; conflicts on stale committed revisions are surfaced directly and are not transport-retried.
-- Stage/backfill helpers (`stage_backfill_hypothesis`, `stage_backfill_insights`) return non-canonical staged payload patches and explicit status fields (`staged_changes_pending`, `commit_required`, `next_action_hint`).
-- Committed node state must still satisfy strict contract (`summary` required; `empirical` requires hypothesis plus artifacts or `no_artifacts_reason`; `insight` requires non-empty insights).
+- Committed node state uses the same canonical body fields for every node; `summary` may be empty when the node body is intentionally represented by content, artifacts, tags, or executions.
 - When code is involved, pass `repo_url`/`branch_name`/`head_commit_sha` and align git structure with graph topology where practical (without forcing one-to-one mapping).
-- Summaries, hypotheses, and artifacts should be reproduction-grade: enough setup, method, evidence, and interpretation for another reader to reproduce or audit results.
+- Content, summaries, and artifacts should be reproduction-grade: enough setup, method, evidence, and interpretation for another reader to reproduce or audit results.
 - Empirical workflow is hypothesis-driven: launch execution, inspect outcomes, publish evidence artifacts, and commit only after terminal status.
 - For empirical work, publish evidence with `flywheel_prepare_artifact_uploads`, upload raw file bytes, then `flywheel_finalize_artifact_uploads` before commit.
 - Artifact metadata records expose a non-empty `title` suitable for display labels; title normalization must never derive from `storage_url`.
@@ -135,7 +133,7 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 8. `flywheel_list_executions`: Poll until execution reaches terminal status.
 9. `flywheel_prepare_artifact_uploads`: Prepare signed upload URLs for empirical evidence.
 10. `raw_file_upload`: Upload raw bytes to each signed URL with required headers.
-11. `flywheel_finalize_artifact_uploads`: Finalize prepared uploads before commit, or set `no_artifacts_reason` when intentionally artifact-free.
+11. `flywheel_finalize_artifact_uploads`: Finalize prepared uploads before commit when the work produced evidence artifacts.
 12. `flywheel_commit_node`: Commit terminal empirical node once contract requirements are satisfied.
 
 ## Runtime Guidance

package/skills/flywheel-tree/SKILL.md

@@ -50,9 +50,8 @@ If no node id or slug is explicitly provided:
    - In chat responses, wrap renderer stdout in a fenced `text` code block.
    - Do not alter indentation or rewrite line prefixes.
 4. Keep visual conventions produced by the renderer:
-   - Node label: `name [kind] | slugname` when slug exists.
+   - Node label: `name | slugname` when slug exists.
    - Omit `| slugname` entirely when slug is missing.
-   - `[insight]` is pastel red, `[empirical]` is pastel yellow, `[untyped]` is gray.
    - `slugname` is always gray.
 
 ## Result Contract

package/skills/flywheel-tree/references/workflow.md

@@ -95,13 +95,9 @@ Preserve renderer stdout exactly. Do not rewrite formatting.
 Expected output format:
 
 - Terminal tree with box-drawing characters
-- Node label format: `name [kind] | slugname` when slug exists, otherwise `name [kind]`
+- Node label format: `name | slugname` when slug exists, otherwise `name`
 - Duplicate views for multi-parent nodes
 - One unique color per multi-parent set
-- Kind colors are fixed:
-  - `[insight]` pastel red
-  - `[empirical]` pastel yellow
-  - `[untyped]` gray
 - `slugname` segment is always gray
 - Summary with exactly:
   - `root: <title>`

package/skills/flywheel-tree/scripts/render_tree.py

@@ -42,8 +42,6 @@ DEFAULT_COLORS = [
 ]
 DEFAULT_RESET = "\u001b[0m"
 GRAY = "\u001b[38;5;245m"
-PASTEL_RED = "\u001b[38;5;217m"
-PASTEL_YELLOW = "\u001b[38;5;229m"
 
 BOX_MID = "├── "
 BOX_LAST = "└── "
@@ -53,7 +51,6 @@ BOX_SPACE = "    "
 
 class Node(NamedTuple):
     title: str
-    kind: str
     slug_name: str
     parent_ids: Tuple[str, ...]
     child_ids: Tuple[str, ...]
@@ -138,8 +135,6 @@ def _build_node_map(nodes_payload: Iterable[dict]) -> Dict[str, Node]:
             continue
 
         title = _clean_text(raw.get("title")) or node_id
-        kind_raw = raw.get("kind", raw.get("node_type", ""))
-        kind = _clean_text(kind_raw) or "untyped"
         slug_name_raw = raw.get("slug_name", raw.get("slug"))
         slug_name = _clean_text(slug_name_raw)
 
@@ -155,7 +150,6 @@ def _build_node_map(nodes_payload: Iterable[dict]) -> Dict[str, Node]:
 
         node_map[node_id] = Node(
             title=title,
-            kind=kind,
             slug_name=slug_name,
             parent_ids=parent_ids,
             child_ids=child_ids,
@@ -255,7 +249,6 @@ def _iter_render_lines(
 
     def line_for(node_id: str) -> str:
         node = node_map[node_id]
-        kind_token = f"[{node.kind}]"
         seen_count = seen_multi_parent.get(node_id)
         has_multi_parent = seen_count is not None
         mp_color = multi_parent_color[node_id] if has_multi_parent else ""
@@ -267,27 +260,13 @@ def _iter_render_lines(
             suffix = ""
 
         if not use_color:
-            rendered = f"{node.title} {kind_token}"
+            rendered = node.title
             if node.slug_name:
                 rendered += f" | {node.slug_name}"
             rendered += suffix
             return rendered
 
-        if node.kind == "insight":
-            kind_color = PASTEL_RED
-        elif node.kind == "empirical":
-            kind_color = PASTEL_YELLOW
-        elif node.kind == "untyped":
-            kind_color = GRAY
-        else:
-            kind_color = ""
-
-        title_part = (
-            f"{mp_color}{node.title}{reset}" if has_multi_parent else node.title
-        )
-        kind_part = f"{kind_color}{kind_token}{reset}" if kind_color else kind_token
-
-        rendered = f"{title_part} {kind_part}"
+        rendered = f"{mp_color}{node.title}{reset}" if has_multi_parent else node.title
         if node.slug_name:
             rendered += f" {GRAY}| {node.slug_name}{reset}"
         if suffix:

package/src/cli.mjs

@@ -15,6 +15,7 @@ import {
   isSkillOnlyHost,
   normalizeHosts,
 } from "./agents.mjs";
+import { generateCompletionScript } from "./completion.mjs";
 import {
   readEntryServerUrl,
   readNamedConfigEntry,
@@ -45,6 +46,7 @@ import {
   buildGuidedSkillInstallPrompt,
   runMcpModeCommand,
 } from "./setup/modes/mcp-command.mjs";
+import { COMPLETION_SHELL_CHOICES } from "./public-command-metadata.mjs";
 import { findFlywheelMcpEntryNames } from "./setup/shared/prior-mode-detect.mjs";
 import { renderSetupSummary } from "./setup/shared/summary.mjs";
 
@@ -475,6 +477,20 @@ async function runSetupCommandViaRouter(options) {
   });
 }
 
+async function runCompletionCommand(shell, options) {
+  try {
+    const script = await generateCompletionScript({
+      shell,
+      includeBashCompletionLib: options.includeBashCompletionLib === true,
+    });
+    process.stdout.write(script);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+  }
+}
+
 function parseUninstallScope(value) {
   const normalized = String(value || "")
     .trim()
@@ -1146,6 +1162,45 @@ Examples:
 `,
     );
 
+  program
+    .command("completion <shell>")
+    .description("Generate a shell completion script")
+    .addHelpText(
+      "before",
+      `${pc.bold(pc.cyan("✻ Flywheel Completion"))}
+
+Generate shell completion scripts from the public Flywheel Usage spec.
+Supported shells: ${COMPLETION_SHELL_CHOICES.join(", ")}.
+Requires the official Usage CLI executable on PATH.
+`,
+    )
+    .option(
+      "--include-bash-completion-lib",
+      "Include Usage's bash completion library in bash output",
+    )
+    .addHelpText(
+      "after",
+      `
+Usage CLI prerequisite:
+  ${pc.green("mise use -g usage")}
+  ${pc.green("brew install usage")}
+  ${pc.green("cargo install usage-cli")}
+  ${pc.green("cargo binstall usage-cli")}
+  ${pc.green("pacman -S usage")}
+
+Examples:
+  ${pc.green("flywheel completion bash --include-bash-completion-lib > ~/.local/share/bash-completion/completions/flywheel")}
+  ${pc.green("flywheel completion zsh > ~/.zsh/completions/_flywheel")}
+  ${pc.green("flywheel completion fish > ~/.config/fish/completions/flywheel.fish")}
+  ${pc.green("flywheel completion powershell > flywheel.ps1")}
+  ${pc.green("flywheel completion nu > ~/.config/nushell/autoload/flywheel.nu")}
+  ${pc.green("flywheel completion nushell > ~/.config/nushell/autoload/flywheel.nu")}
+`,
+    )
+    .action(async (shell, options) => {
+      await runCompletionCommand(shell, options);
+    });
+
   program
     .command("setup")
     .description("Set up Flywheel for your AI coding host")

package/src/completion.mjs

@@ -0,0 +1,326 @@
+import { spawn } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import path from "node:path";
+
+import {
+  loadPackageVersion,
+  usageExtrasArg,
+  usageVersionArg,
+} from "./public-command-metadata.mjs";
+import { runRuntimeCli } from "./runtime/delegate.mjs";
+
+export const SUPPORTED_COMPLETION_SHELLS = [
+  "bash",
+  "zsh",
+  "fish",
+  "powershell",
+  "nu",
+  "nushell",
+];
+
+const DEFAULT_WINDOWS_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+
+const SUPPORTED_COMPLETION_SHELLS_FOR_ERRORS = [
+  "bash",
+  "fish",
+  "nu",
+  "nushell",
+  "powershell",
+  "zsh",
+];
+
+const USAGE_INSTALL_HINTS = [
+  "mise use -g usage",
+  "brew install usage",
+  "cargo install usage-cli",
+  "cargo binstall usage-cli",
+  "pacman -S usage",
+];
+
+const DEFAULT_USAGE_BIN = "usage";
+const MAX_COMPLETION_BUFFER_BYTES = 50 * 1024 * 1024;
+
+function supportedShellList() {
+  return SUPPORTED_COMPLETION_SHELLS_FOR_ERRORS.join(", ");
+}
+
+function missingUsageMessage(name) {
+  return [
+    `official Usage CLI not found or not executable: ${name}`,
+    "Install usage with one of:",
+    ...USAGE_INSTALL_HINTS.map((hint) => `  ${hint}`),
+  ].join("\n");
+}
+
+function isExecutable(filePath) {
+  try {
+    accessSync(filePath, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function hasPathSeparator(value) {
+  return (
+    value.includes(path.sep) ||
+    value.includes(path.posix.sep) ||
+    value.includes(path.win32.sep)
+  );
+}
+
+function pathextCandidates(env, platform) {
+  const useWindowsDefaultPathext =
+    platform === "win32" && String(env.PATHEXT ?? "").trim() === "";
+  const rawPathext =
+    useWindowsDefaultPathext
+      ? DEFAULT_WINDOWS_PATHEXT
+      : String(env.PATHEXT ?? "");
+  const candidates = [];
+  const seen = new Set();
+  for (const rawExtension of rawPathext.split(";")) {
+    const trimmed = rawExtension.trim();
+    if (!trimmed) continue;
+    const extension = trimmed.startsWith(".") ? trimmed : `.${trimmed}`;
+    const variants = useWindowsDefaultPathext
+      ? [extension.toLowerCase(), extension, extension.toUpperCase()]
+      : [extension, extension.toLowerCase(), extension.toUpperCase()];
+    for (const candidate of variants) {
+      if (!seen.has(candidate)) {
+        candidates.push(candidate);
+        seen.add(candidate);
+      }
+    }
+  }
+  return candidates;
+}
+
+function executableNameCandidates(name, env, platform = process.platform) {
+  const candidates = [name];
+  const lowerName = name.toLowerCase();
+  const seen = new Set(candidates);
+  for (const extension of pathextCandidates(env, platform)) {
+    if (lowerName.endsWith(extension.toLowerCase())) continue;
+    const candidate = `${name}${extension}`;
+    if (!seen.has(candidate)) {
+      candidates.push(candidate);
+      seen.add(candidate);
+    }
+  }
+  return candidates;
+}
+
+export function sanitizeUsageEnv(env = process.env) {
+  const sanitized = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (key.toUpperCase().startsWith("FLYWHEEL_")) continue;
+    if (value !== undefined) {
+      sanitized[key] = value;
+    }
+  }
+  return sanitized;
+}
+
+function isWindowsCommandShim(filePath, platform) {
+  return (
+    platform === "win32" &&
+    [".bat", ".cmd"].includes(path.extname(filePath).toLowerCase())
+  );
+}
+
+function quoteWindowsCommandPath(filePath) {
+  return `"${String(filePath).replaceAll('"', '""')}"`;
+}
+
+function resolveWindowsCommandShell(env) {
+  return env.ComSpec || env.COMSPEC || "cmd.exe";
+}
+
+function buildUsageInvocation({ usagePath, args, env, platform }) {
+  if (!isWindowsCommandShim(usagePath, platform)) {
+    return { command: usagePath, args };
+  }
+  const commandLine = `"${[quoteWindowsCommandPath(usagePath), ...args].join(" ")}"`;
+  return {
+    command: resolveWindowsCommandShell(env),
+    args: ["/d", "/s", "/c", commandLine],
+  };
+}
+
+export function normalizeCompletionShell(value) {
+  if (value === "nushell") {
+    return "nu";
+  }
+  if (SUPPORTED_COMPLETION_SHELLS.includes(value)) {
+    return value;
+  }
+  throw new Error(
+    `unsupported completion shell "${value}". Supported shells: ${supportedShellList()}`,
+  );
+}
+
+export function buildUsageCompletionArgs({
+  shell,
+  includeBashCompletionLib = false,
+}) {
+  const normalizedShell = normalizeCompletionShell(shell);
+  if (includeBashCompletionLib && normalizedShell !== "bash") {
+    throw new Error("--include-bash-completion-lib is only supported for bash");
+  }
+  const args = ["generate", "completion", normalizedShell, "flywheel", "-f", "-"];
+  if (includeBashCompletionLib) {
+    args.push("--include-bash-completion-lib");
+  }
+  return args;
+}
+
+export function findExecutable(
+  name,
+  env = process.env,
+  platform = process.platform,
+) {
+  if (!name) {
+    return null;
+  }
+  if (path.isAbsolute(name) || hasPathSeparator(name)) {
+    return isExecutable(name) ? name : null;
+  }
+  const delimiter = platform === "win32" ? ";" : path.delimiter;
+  for (const entry of String(env.PATH ?? "").split(delimiter)) {
+    if (!entry) continue;
+    for (const candidateName of executableNameCandidates(name, env, platform)) {
+      const candidate = path.join(entry, candidateName);
+      if (isExecutable(candidate)) {
+        return candidate;
+      }
+    }
+  }
+  return null;
+}
+
+async function capturePublicUsageSpec() {
+  let stdout = "";
+  let stderr = "";
+  const version = await loadPackageVersion();
+  const exitCode = await runRuntimeCli([
+    "--usage",
+    usageExtrasArg(),
+    usageVersionArg(version),
+  ], {
+    stdout: (chunk) => {
+      stdout += chunk instanceof Uint8Array ? Buffer.from(chunk).toString("utf8") : chunk;
+    },
+    stderr: (chunk) => {
+      stderr += chunk instanceof Uint8Array ? Buffer.from(chunk).toString("utf8") : chunk;
+    },
+  });
+  if (exitCode !== 0) {
+    const detail = stderr.trim() ? `: ${stderr.trim()}` : "";
+    throw new Error(`failed to capture Flywheel Usage spec${detail}`);
+  }
+  return stdout;
+}
+
+function runUsageCompletion({ command, args, usageSpec, env }) {
+  return awaitChildProcess({
+    child: spawn(command, args, {
+      env: sanitizeUsageEnv(env),
+      stdio: ["pipe", "pipe", "pipe"],
+    }),
+    input: usageSpec,
+  });
+}
+
+function awaitChildProcess({ child, input }) {
+  return new Promise((resolve, reject) => {
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let stdinError = null;
+
+    function settle(callback, value) {
+      if (settled) return;
+      settled = true;
+      callback(value);
+    }
+
+    function append(streamName, chunk) {
+      if (streamName === "stdout") {
+        stdout += chunk.toString("utf8");
+        if (Buffer.byteLength(stdout, "utf8") > MAX_COMPLETION_BUFFER_BYTES) {
+          child.kill();
+          settle(reject, new Error("usage completion stdout exceeded 50 MiB"));
+        }
+      } else {
+        stderr += chunk.toString("utf8");
+        if (Buffer.byteLength(stderr, "utf8") > MAX_COMPLETION_BUFFER_BYTES) {
+          child.kill();
+          settle(reject, new Error("usage completion stderr exceeded 50 MiB"));
+        }
+      }
+    }
+
+    child.stdout.on("data", (chunk) => append("stdout", chunk));
+    child.stderr.on("data", (chunk) => append("stderr", chunk));
+    child.stdin.on("error", (error) => {
+      if (error.code === "EPIPE") {
+        stdinError = error;
+        return;
+      }
+      child.kill();
+      settle(reject, error);
+    });
+    child.on("error", (error) => settle(reject, error));
+    child.on("close", (code, signal) => {
+      if (settled) return;
+      if (code === 0) {
+        if (stdinError) {
+          settle(
+            reject,
+            new Error(
+              `usage stdin closed before Flywheel Usage spec was written: ${stdinError.message}`,
+            ),
+          );
+          return;
+        }
+        settle(resolve, stdout);
+        return;
+      }
+      const detail = stderr.trim() ? `\n${stderr.trim()}` : "";
+      const status = signal ? `signal ${signal}` : `exit code ${code}`;
+      settle(reject, new Error(`usage generate completion failed with ${status}.${detail}`));
+    });
+    child.stdin.end(input);
+  });
+}
+
+export async function generateCompletionScript({
+  shell,
+  includeBashCompletionLib = false,
+  usageBin,
+  env = process.env,
+  platform = process.platform,
+  usageSpec,
+  captureUsageSpec = capturePublicUsageSpec,
+} = {}) {
+  const args = buildUsageCompletionArgs({ shell, includeBashCompletionLib });
+  const usageName = usageBin ?? env.USAGE_BIN ?? DEFAULT_USAGE_BIN;
+  const usagePath = findExecutable(usageName, env, platform);
+  if (!usagePath) {
+    throw new Error(missingUsageMessage(usageName));
+  }
+
+  const spec = usageSpec ?? (await captureUsageSpec());
+  const usageInvocation = buildUsageInvocation({
+    usagePath,
+    args,
+    env,
+    platform,
+  });
+  return await runUsageCompletion({
+    command: usageInvocation.command,
+    args: usageInvocation.args,
+    usageSpec: spec,
+    env,
+  });
+}