@elench/testkit 0.1.90 → 0.1.92

package/README.md

@@ -13,6 +13,8 @@ cd my-product
 
 # Launch the interactive assistant
 npx @elench/testkit
+npx @elench/testkit assistant --provider codex --model gpt-5.4
+npx @elench/testkit assistant --provider claude --model sonnet --effort high
 
 # Ask for one assistant turn non-interactively
 npx @elench/testkit assistant --message "/status"
@@ -75,18 +77,24 @@ npx @elench/testkit assistant --message "/logs api"
 npx @elench/testkit db snapshot capture --service api --output scripts/testkit/schema-baseline.sql
 ```
 
-`testkit` is now assistant-first in an interactive TTY, but the interactive
-assistant is provider-native. `testkit` boots a real Codex CLI or Claude CLI
-session, writes local context files under `.testkit/assistant/`, places a
-repo-local `testkit` wrapper on the provider `PATH`, and then hands the
-terminal to the provider. That means the cursor, transcript, approvals, and
-conversation UX come from the provider itself, while `testkit` contributes
-repo context, durable run artifacts, focused detail/log/artifact/setup text
-files, and a stable local command surface.
-
-The non-interactive `assistant --message ...` mode remains available for one
-hosted turn at a time. It is useful in scripts and tests, but it is not the
-primary interactive UX.
+`testkit` is assistant-first in an interactive TTY. The interactive assistant
+is a testkit-owned chat shell with a bottom composer, provider-backed
+reasoning, repo context files under `.testkit/assistant/`, and inline tool
+blocks for command execution. Natural-language turns still go through Codex or
+Claude, but `testkit` owns the transcript, command execution surface, and
+rendering around `testkit`, `npm`, and `npx` commands.
+
+Assistant runtime settings are repo-local. Use `/provider`, `/model`,
+`/effort`, and `/settings` inside the assistant to inspect or change the active
+provider runtime; changes are persisted to `.testkit/assistant/settings.json`.
+CLI flags such as `--provider`, `--model`, `--effort`, and repeatable
+`--provider-arg` override those settings for the current launch. The composer
+has an always-visible cursor and supports arrow keys, Home/End, Ctrl+A/Ctrl+E,
+Backspace, Delete, and Ctrl+D.
+
+The non-interactive `assistant --message ...` mode uses the same provider/tool
+engine for one hosted turn at a time. It is useful in scripts and tests, but
+it is not the primary interactive UX.
 
 Batch `run` output stays intentionally short: one line per completed file, a
 concise failure block, and a final summary. Service logs, captured runtime

package/lib/cli/agents/index.mjs

@@ -1,6 +1,5 @@
 import fs from "fs";
 import path from "path";
-import { spawn } from "child_process";
 import { startClaudeHostedSession } from "./providers/claude.mjs";
 import { startCodexHostedSession } from "./providers/codex.mjs";
 
@@ -58,6 +57,9 @@ export function isProviderInstalled(provider, env = process.env) {
 
 export function startAgentSession({
   provider = "auto",
+  model = null,
+  effort = null,
+  providerArgs = [],
   cwd,
   prompt,
   onEvent,
@@ -67,37 +69,7 @@ export function startAgentSession({
   const resolvedProvider = resolvePreferredProvider(provider, env);
   const command = resolveProviderBinary(resolvedProvider, env);
   if (resolvedProvider === "claude") {
-    return startClaudeHostedSession({ command, cwd, prompt, onEvent, purpose });
+    return startClaudeHostedSession({ command, cwd, prompt, onEvent, purpose, model, effort, providerArgs });
   }
-  return startCodexHostedSession({ command, cwd, prompt, onEvent, purpose });
-}
-
-export function startInteractiveProviderSession({
-  provider = "auto",
-  cwd,
-  prompt,
-  env = process.env,
-} = {}) {
-  const resolvedProvider = resolvePreferredProvider(provider, env);
-  const command = resolveProviderBinary(resolvedProvider, env);
-  const args = buildInteractiveProviderArgs(resolvedProvider, prompt);
-  const child = spawn(command, args, {
-    cwd,
-    env,
-    stdio: "inherit",
-  });
-  return new Promise((resolve, reject) => {
-    child.on("error", reject);
-    child.on("close", (code) =>
-      resolve({
-        provider: resolvedProvider,
-        exitCode: code ?? 0,
-      })
-    );
-  });
-}
-
-export function buildInteractiveProviderArgs(provider, prompt = null) {
-  if (!prompt) return [];
-  return [prompt];
+  return startCodexHostedSession({ command, cwd, prompt, onEvent, purpose, model, providerArgs });
 }

package/lib/cli/agents/providers/claude.mjs

@@ -7,7 +7,16 @@ import {
   extractTextFragments,
 } from "./shared.mjs";
 
-export function startClaudeHostedSession({ command = "claude", cwd, prompt, onEvent, purpose = "assistant" } = {}) {
+export function startClaudeHostedSession({
+  command = "claude",
+  cwd,
+  prompt,
+  onEvent,
+  purpose = "assistant",
+  model = null,
+  effort = null,
+  providerArgs = [],
+} = {}) {
   const args = [
     "-p",
     "--output-format",
@@ -18,6 +27,13 @@ export function startClaudeHostedSession({ command = "claude", cwd, prompt, onEv
   if (purpose === "assistant") {
     args.push("--permission-mode", "plan");
   }
+  if (model) {
+    args.push("--model", String(model));
+  }
+  if (effort) {
+    args.push("--effort", String(effort));
+  }
+  args.push(...normalizeProviderArgs(providerArgs));
 
   args.push(prompt);
 
@@ -39,6 +55,11 @@ export function startClaudeHostedSession({ command = "claude", cwd, prompt, onEv
   });
 }
 
+function normalizeProviderArgs(providerArgs) {
+  if (!Array.isArray(providerArgs)) return [];
+  return providerArgs.flatMap((arg) => String(arg || "").split(/\s+/).filter(Boolean));
+}
+
 function parseClaudePayload(payload) {
   const events = [];
   if (!payload || typeof payload !== "object") return events;

package/lib/cli/agents/providers/codex.mjs

@@ -11,7 +11,15 @@ import {
   readTextFileIfPresent,
 } from "./shared.mjs";
 
-export function startCodexHostedSession({ command = "codex", cwd, prompt, onEvent, purpose = "assistant" } = {}) {
+export function startCodexHostedSession({
+  command = "codex",
+  cwd,
+  prompt,
+  onEvent,
+  purpose = "assistant",
+  model = null,
+  providerArgs = [],
+} = {}) {
   const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-codex-"));
   const outputFile = path.join(tempDir, "final-message.txt");
   const args = ["exec", "--json", "-o", outputFile];
@@ -19,6 +27,10 @@ export function startCodexHostedSession({ command = "codex", cwd, prompt, onEven
   if (purpose === "assistant") {
     args.push("-s", "read-only");
   }
+  if (model) {
+    args.push("--model", String(model));
+  }
+  args.push(...normalizeProviderArgs(providerArgs));
 
   args.push(prompt);
 
@@ -49,6 +61,11 @@ export function startCodexHostedSession({ command = "codex", cwd, prompt, onEven
   };
 }
 
+function normalizeProviderArgs(providerArgs) {
+  if (!Array.isArray(providerArgs)) return [];
+  return providerArgs.flatMap((arg) => String(arg || "").split(/\s+/).filter(Boolean));
+}
+
 function parseCodexPayload(payload) {
   const events = [];
   if (!payload || typeof payload !== "object") return events;

package/lib/cli/assistant/app.mjs

@@ -0,0 +1,209 @@
+import React, { createElement, useEffect, useMemo, useState } from "react";
+import { Box, Text, useApp, useInput } from "ink";
+import { bold, dim, green, red, yellow } from "../presentation/colors.mjs";
+import { getComposerRenderParts } from "./composer.mjs";
+
+const MAX_VISIBLE_MESSAGES = 22;
+
+export function AssistantApp({
+  assistantState,
+  initialPrompt = null,
+  exitAfterInitialPrompt = false,
+  inputEnabled = true,
+  onRequestClose,
+} = {}) {
+  const { exit } = useApp();
+  const [snapshot, setSnapshot] = useState(() => assistantState.getSnapshot());
+  const [initialPromptStarted, setInitialPromptStarted] = useState(false);
+  const [initialPromptFinished, setInitialPromptFinished] = useState(false);
+
+  useEffect(() => {
+    const unsubscribe = assistantState.subscribe(() => {
+      setSnapshot(assistantState.getSnapshot());
+    });
+    return unsubscribe;
+  }, [assistantState]);
+
+  useEffect(() => {
+    if (!initialPrompt || initialPromptStarted) return;
+    setInitialPromptStarted(true);
+    Promise.resolve(assistantState.submitInput(initialPrompt)).finally(() => {
+      setInitialPromptFinished(true);
+    });
+  }, [assistantState, exit, exitAfterInitialPrompt, initialPrompt, initialPromptStarted, onRequestClose]);
+
+  useEffect(() => {
+    if (!exitAfterInitialPrompt || !initialPromptFinished || snapshot.busy) return;
+    const timer = setTimeout(() => {
+      (onRequestClose || exit)();
+    }, 40);
+    return () => clearTimeout(timer);
+  }, [exit, exitAfterInitialPrompt, initialPromptFinished, onRequestClose, snapshot.busy]);
+
+  const visibleMessages = useMemo(
+    () => snapshot.messages.slice(-MAX_VISIBLE_MESSAGES),
+    [snapshot.messages]
+  );
+
+  return createElement(
+    Box,
+    { flexDirection: "column" },
+    inputEnabled
+      ? createElement(AssistantInputHandler, {
+          assistantState,
+          snapshot,
+          onRequestClose,
+        })
+      : null,
+    createElement(Text, null, dim(buildHeader(snapshot))),
+    snapshot.notice ? createElement(Text, null, yellow(snapshot.notice)) : null,
+    createElement(Text, null, ""),
+    createElement(
+      Box,
+      { flexDirection: "column" },
+      ...visibleMessages.flatMap((message) => renderMessage(message))
+    ),
+    createElement(Text, null, ""),
+    createElement(
+      Box,
+      {
+        borderStyle: "round",
+        flexDirection: "column",
+        paddingLeft: 1,
+        paddingRight: 1,
+      },
+      createElement(Text, null, dim("Message")),
+      renderComposer(snapshot)
+    ),
+    createElement(Text, null, ""),
+    createElement(Text, null, dim(buildFooter(snapshot, initialPromptFinished)))
+  );
+}
+
+function AssistantInputHandler({ assistantState, snapshot, onRequestClose }) {
+  const { exit } = useApp();
+
+  useInput((input, key) => {
+    if (key.ctrl && input === "c") {
+      (onRequestClose || exit)();
+      return;
+    }
+    if (input === "q" && !snapshot.busy && snapshot.composer.length === 0) {
+      (onRequestClose || exit)();
+      return;
+    }
+    if (key.return) {
+      if (!snapshot.busy) {
+        void assistantState.submitCurrentComposer();
+      }
+      return;
+    }
+    if (key.leftArrow) {
+      assistantState.moveComposerCursor(-1);
+      return;
+    }
+    if (key.rightArrow) {
+      assistantState.moveComposerCursor(1);
+      return;
+    }
+    if (key.home || (key.ctrl && input === "a")) {
+      assistantState.moveComposerCursorToStart();
+      return;
+    }
+    if (key.end || (key.ctrl && input === "e")) {
+      assistantState.moveComposerCursorToEnd();
+      return;
+    }
+    if (key.backspace) {
+      assistantState.backspaceComposer();
+      return;
+    }
+    if (key.delete || (key.ctrl && input === "d")) {
+      assistantState.deleteComposer();
+      return;
+    }
+    if (isPrintableInput(input, key)) {
+      assistantState.insertComposer(input);
+    }
+  });
+
+  return null;
+}
+
+function renderMessage(message) {
+  const prefix = rolePrefix(message);
+  const lines = String(message.text || "").split(/\r?\n/);
+  const rendered = [];
+  if (message.title) {
+    rendered.push(createElement(Text, { key: `${message.id}-title` }, `${prefix} ${bold(message.title)}`));
+  } else if (lines.length > 0) {
+    rendered.push(createElement(Text, { key: `${message.id}-first` }, `${prefix} ${colorForRole(message.role)(lines[0] || "")}`));
+  }
+
+  const remainingLines = message.title ? lines : lines.slice(1);
+  for (let index = 0; index < remainingLines.length; index += 1) {
+    rendered.push(
+      createElement(
+        Text,
+        { key: `${message.id}-line-${index}` },
+        `${message.title ? "  " : "    "}${remainingLines[index]}`
+      )
+    );
+  }
+  rendered.push(createElement(Text, { key: `${message.id}-gap` }, ""));
+  return rendered;
+}
+
+function renderComposer(snapshot) {
+  const { before, current, after, empty } = getComposerRenderParts({
+    text: snapshot.composer || "",
+    cursor: snapshot.composerCursor ?? 0,
+  });
+  return createElement(
+    Text,
+    null,
+    empty ? dim("Ask testkit to run or inspect something... ") : before,
+    createElement(Text, { inverse: true }, current),
+    after
+  );
+}
+
+function buildHeader(snapshot) {
+  const status = snapshot.busy ? snapshot.activeStatus || "working" : "ready";
+  const provider = snapshot.provider || "auto";
+  const resolvedProvider = snapshot.resolvedProvider && snapshot.resolvedProvider !== provider ? `→${snapshot.resolvedProvider}` : "";
+  const model = snapshot.model ? ` · ${snapshot.model}` : "";
+  const effort = snapshot.effort ? ` · ${snapshot.effort}` : "";
+  const context = snapshot.context?.selection?.filePath || snapshot.context?.selection?.serviceName || "no focus";
+  return `testkit assistant · ${provider}${resolvedProvider}${model}${effort} · ${status} · ${context}`;
+}
+
+function buildFooter(snapshot, promptFinished) {
+  if (promptFinished && snapshot.messages.length > 0) {
+    return "initial prompt complete";
+  }
+  if (snapshot.busy) {
+    return "Enter disabled while the provider is responding · Ctrl+C quit";
+  }
+  return "Enter send · arrows/Home/End move cursor · Backspace/Delete edit · /settings · q quit";
+}
+
+function rolePrefix(message) {
+  if (message.role === "user") return green("you>");
+  if (message.role === "assistant") return bold("ai>");
+  if (message.role === "tool") return yellow("tool>");
+  return red("sys>");
+}
+
+function colorForRole(role) {
+  if (role === "user") return green;
+  if (role === "tool") return yellow;
+  if (role === "system") return red;
+  return (value) => value;
+}
+
+function isPrintableInput(input, key) {
+  if (!input) return false;
+  if (key.ctrl || key.meta || key.escape || key.tab) return false;
+  return input >= " ";
+}

package/lib/cli/assistant/composer.mjs

@@ -0,0 +1,112 @@
+const segmenter =
+  typeof Intl !== "undefined" && typeof Intl.Segmenter === "function"
+    ? new Intl.Segmenter(undefined, { granularity: "grapheme" })
+    : null;
+
+export function createComposerState(value = "") {
+  const text = String(value || "");
+  return {
+    text,
+    cursor: splitGraphemes(text).length,
+  };
+}
+
+export function setComposerText(state, value) {
+  const text = String(value || "");
+  const length = splitGraphemes(text).length;
+  return {
+    text,
+    cursor: clampCursor(state?.cursor ?? length, length),
+  };
+}
+
+export function insertComposerText(state, value) {
+  const insertText = String(value || "");
+  if (!insertText) return normalizeComposerState(state);
+  const parts = splitGraphemes(state?.text || "");
+  const cursor = clampCursor(state?.cursor ?? parts.length, parts.length);
+  const insertParts = splitGraphemes(insertText);
+  const nextParts = [...parts.slice(0, cursor), ...insertParts, ...parts.slice(cursor)];
+  return {
+    text: nextParts.join(""),
+    cursor: cursor + insertParts.length,
+  };
+}
+
+export function backspaceComposerText(state) {
+  const parts = splitGraphemes(state?.text || "");
+  const cursor = clampCursor(state?.cursor ?? parts.length, parts.length);
+  if (cursor === 0) return { text: parts.join(""), cursor };
+  const nextParts = [...parts.slice(0, cursor - 1), ...parts.slice(cursor)];
+  return {
+    text: nextParts.join(""),
+    cursor: cursor - 1,
+  };
+}
+
+export function deleteComposerText(state) {
+  const parts = splitGraphemes(state?.text || "");
+  const cursor = clampCursor(state?.cursor ?? parts.length, parts.length);
+  if (cursor >= parts.length) return { text: parts.join(""), cursor };
+  const nextParts = [...parts.slice(0, cursor), ...parts.slice(cursor + 1)];
+  return {
+    text: nextParts.join(""),
+    cursor,
+  };
+}
+
+export function moveComposerCursor(state, delta) {
+  const parts = splitGraphemes(state?.text || "");
+  return {
+    text: parts.join(""),
+    cursor: clampCursor((state?.cursor ?? parts.length) + Number(delta || 0), parts.length),
+  };
+}
+
+export function moveComposerCursorToStart(state) {
+  return {
+    text: String(state?.text || ""),
+    cursor: 0,
+  };
+}
+
+export function moveComposerCursorToEnd(state) {
+  const text = String(state?.text || "");
+  return {
+    text,
+    cursor: splitGraphemes(text).length,
+  };
+}
+
+export function getComposerRenderParts(state) {
+  const parts = splitGraphemes(state?.text || "");
+  const cursor = clampCursor(state?.cursor ?? parts.length, parts.length);
+  return {
+    before: parts.slice(0, cursor).join(""),
+    current: parts[cursor] || " ",
+    after: parts.slice(cursor + (parts[cursor] ? 1 : 0)).join(""),
+    empty: parts.length === 0,
+  };
+}
+
+function normalizeComposerState(state) {
+  const text = String(state?.text || "");
+  const parts = splitGraphemes(text);
+  return {
+    text,
+    cursor: clampCursor(state?.cursor ?? parts.length, parts.length),
+  };
+}
+
+function splitGraphemes(value) {
+  const text = String(value || "");
+  if (!text) return [];
+  if (segmenter) {
+    return [...segmenter.segment(text)].map((entry) => entry.segment);
+  }
+  return [...text];
+}
+
+function clampCursor(value, length) {
+  return Math.max(0, Math.min(Number(value || 0), length));
+}

package/lib/cli/assistant/context-pack.mjs

@@ -0,0 +1,191 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { readContextContent, buildContextSelection } from "../context-resources.mjs";
+
+export function prepareAssistantContextPack({
+  productDir,
+  inspectState,
+} = {}) {
+  const contextDir = path.join(productDir, ".testkit", "assistant");
+  const binDir = path.join(contextDir, "bin");
+  fs.mkdirSync(binDir, { recursive: true });
+
+  const commandLogPath = path.join(contextDir, "commands.jsonl");
+  const contextPath = path.join(contextDir, "context.md");
+  const summaryPath = path.join(contextDir, "latest-run-summary.json");
+  const selectionPath = path.join(contextDir, "current-selection.json");
+  const commandsPath = path.join(contextDir, "commands.md");
+  const focusedDetailPath = path.join(contextDir, "focused-detail.txt");
+  const focusedLogsPath = path.join(contextDir, "focused-logs.txt");
+  const focusedArtifactsPath = path.join(contextDir, "focused-artifacts.txt");
+  const focusedSetupPath = path.join(contextDir, "focused-setup.txt");
+  const wrapperPath = path.join(binDir, "testkit");
+
+  function refresh() {
+    const snapshot = inspectState?.getSnapshot?.() || {};
+    const detailContent = readContextContent({ productDir, snapshot, mode: "detail", logTail: 12 });
+    const logsContent = readContextContent({ productDir, snapshot, mode: "logs", logTail: 12 });
+    const artifactsContent = readContextContent({ productDir, snapshot, mode: "artifacts", logTail: 12 });
+    const setupContent = readContextContent({ productDir, snapshot, mode: "setup", logTail: 12 });
+
+    writeJson(summaryPath, {
+      summaryRows: snapshot.summaryData?.rows || [],
+      phase: snapshot.phase || null,
+      artifactPath: path.join(productDir, ".testkit", "results", "latest.json"),
+    });
+    writeJson(selectionPath, buildContextSelection(snapshot));
+    fs.writeFileSync(commandsPath, buildCommandsMarkdown(), "utf8");
+    fs.writeFileSync(focusedDetailPath, `${detailContent.lines.join("\n")}\n`, "utf8");
+    fs.writeFileSync(focusedLogsPath, `${logsContent.lines.join("\n")}\n`, "utf8");
+    fs.writeFileSync(focusedArtifactsPath, `${artifactsContent.lines.join("\n")}\n`, "utf8");
+    fs.writeFileSync(focusedSetupPath, `${setupContent.lines.join("\n")}\n`, "utf8");
+    fs.writeFileSync(
+      contextPath,
+      buildContextMarkdown(productDir, snapshot, {
+        contextPath,
+        summaryPath,
+        selectionPath,
+        commandsPath,
+        commandLogPath,
+        focusedDetailPath,
+        focusedLogsPath,
+        focusedArtifactsPath,
+        focusedSetupPath,
+      }),
+      "utf8"
+    );
+    fs.writeFileSync(wrapperPath, buildWrapperScript({ cliPath: resolveCliPath() }), {
+      encoding: "utf8",
+      mode: 0o755,
+    });
+    fs.chmodSync(wrapperPath, 0o755);
+  }
+
+  refresh();
+
+  return {
+    contextDir,
+    contextPath,
+    summaryPath,
+    selectionPath,
+    commandsPath,
+    commandLogPath,
+    focusedDetailPath,
+    focusedLogsPath,
+    focusedArtifactsPath,
+    focusedSetupPath,
+    binDir,
+    wrapperPath,
+    refresh,
+    appendCommandLog(event) {
+      if (!event || typeof event !== "object") return;
+      try {
+        fs.appendFileSync(
+          commandLogPath,
+          `${JSON.stringify({ timestamp: new Date().toISOString(), ...event })}\n`,
+          "utf8"
+        );
+      } catch {
+        // Ignore assistant command log failures.
+      }
+    },
+  };
+}
+
+function resolveCliPath() {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "bin", "testkit.mjs");
+}
+
+function buildWrapperScript({ cliPath } = {}) {
+  return `#!/usr/bin/env node
+import { spawnSync } from "child_process";
+
+const result = spawnSync(process.execPath, [${JSON.stringify(cliPath)}, ...process.argv.slice(2)], {
+  cwd: process.cwd(),
+  env: {
+    ...process.env,
+    TESTKIT_NO_ASSISTANT_DEFAULT: "1",
+  },
+  stdio: "inherit",
+});
+
+if (result.error) {
+  throw result.error;
+}
+process.exit(result.status ?? 0);
+`;
+}
+
+function buildContextMarkdown(productDir, snapshot, paths) {
+  const rows = snapshot.summaryData?.rows || [];
+  const selection = snapshot.selectedEntry;
+  const lines = [
+    "# Testkit Assistant Context",
+    "",
+    `- Product directory: ${productDir}`,
+    `- Context file: ${paths.contextPath}`,
+    `- Run summary JSON: ${paths.summaryPath}`,
+    `- Current selection JSON: ${paths.selectionPath}`,
+    `- Command reference: ${paths.commandsPath}`,
+    `- Command log: ${paths.commandLogPath}`,
+    `- Focused detail: ${paths.focusedDetailPath}`,
+    `- Focused logs: ${paths.focusedLogsPath}`,
+    `- Focused artifacts: ${paths.focusedArtifactsPath}`,
+    `- Focused setup: ${paths.focusedSetupPath}`,
+    "",
+    "## Latest run summary",
+  ];
+
+  if (rows.length === 0) {
+    lines.push("- No persisted run artifact is currently loaded.");
+  } else {
+    for (const [label, value] of rows) {
+      lines.push(`- ${label}: ${value}`);
+    }
+  }
+
+  lines.push("", "## Current selection");
+  if (!selection) {
+    lines.push("- No focused file or service.");
+  } else {
+    lines.push(`- Kind: ${selection.kind}`);
+    if (selection.serviceName) lines.push(`- Service: ${selection.serviceName}`);
+    if (selection.type) lines.push(`- Type: ${selection.type}`);
+    if (selection.suiteName) lines.push(`- Suite: ${selection.suiteName}`);
+    if (selection.filePath) lines.push(`- File: ${selection.filePath}`);
+    if (selection.status) lines.push(`- Status: ${selection.status}`);
+  }
+
+  lines.push(
+    "",
+    "## Guidance",
+    "- Use shell commands like `npm run testkit`, `npx testkit`, or `testkit run --dir . --type <type>` when you need to execute tests.",
+    "- Use the command log and focused context files before rereading artifacts manually.",
+    "- Prefer repo-local commands over guessing project-specific wrappers.",
+    ""
+  );
+
+  return lines.join("\n");
+}
+
+function buildCommandsMarkdown() {
+  return [
+    "# Testkit Commands",
+    "",
+    "- `testkit run --dir . --type int`",
+    "- `testkit run --dir . --type e2e`",
+    "- `testkit run --dir . --file path/to/file.testkit.ts`",
+    "- `testkit discover --dir .`",
+    "- `testkit status --dir .`",
+    "- `testkit doctor --dir .`",
+    "- `testkit destroy --dir .`",
+    "- `npm run testkit`",
+    "- `npx testkit --dir . --type e2e`",
+    "",
+  ].join("\n");
+}
+
+function writeJson(filePath, value) {
+  fs.writeFileSync(filePath, JSON.stringify(value, null, 2), "utf8");
+}