agentwheel 0.10.0 → 0.14.3

package/openpack.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "name": "NestDevLab/agentwheel",
-  "version": "0.9.0",
+  "version": "0.14.2",
   "provides": [
-    { "type": "skills", "path": "skills", "required": true }
+    { "type": "skills", "path": "skills" }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentwheel",
-  "version": "0.10.0",
+  "version": "0.14.3",
   "description": "Weave skills, rules, and instructions across every AI agent.",
   "type": "module",
   "license": "MIT",
@@ -40,6 +40,7 @@
   "scripts": {
     "build": "tsup && chmod +x dist/index.js",
     "prepack": "pnpm build",
+    "sync-site-version": "node scripts/sync-site-version.mjs",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   },

package/skills/agentwheel/SKILL.md

@@ -20,7 +20,7 @@ Mental model:
 ## Safety Rules
 
 - Prefer `agentwheel plan ...` or `agentwheel install --dry-run` before applying changes.
-- Do not hand-edit generated runtime files such as `.openclaw/skills`, `.claude/skills`, `.codex/skills`, `.hermes/skills`, or generated instructions.
+- Do not hand-edit generated runtime files such as `skills/`, `.agents/skills`, `.claude/skills`, `.github/skills`, `~/.hermes/skills`, or generated instructions.
 - If a plan reports `drift` or `conflict`, stop and explain it. Do not use `--force` unless the user explicitly approves that scope.
 - Gmail, Drive, registry publishing, git commits, pushes, and runtime restarts are separate external side effects. Get explicit approval for them.
 - Programmatic adapters execute local code. Use `--adapter-module` only with `--allow-adapter-code` after the user approves that local code execution.
@@ -30,7 +30,7 @@ Mental model:
 
 ```bash
 agentwheel registry search tmux
-agentwheel add github:NestDevLab/agent-mesh --skill codex-tmux --adapter codex --mode tracking
+agentwheel add github:NestDevLab/agent-mesh --skill codex-tmux --adapter codex --installation-type local --mode tracking
 agentwheel plan
 agentwheel install
 ```
@@ -45,9 +45,13 @@ agentwheel install
 To add and install in one step:
 
 ```bash
-agentwheel install github:owner/repo --adapter codex
+agentwheel install github:owner/repo --adapter codex,claude
 ```
 
+Explicit source installs with explicit adapters default to user-level artifacts. Use `--local` for
+the current directory or `-t/--target-root <project>` for project/workspace installs. Use `--user`, `--local`, or
+`-i/--installation-type <type>` when scope should be explicit.
+
 ## Workspace Setup
 
 Initialize an agentwheel workspace:
@@ -126,11 +130,11 @@ agentwheel add <source> --driver vercel-skills
 `add` saves a package entry in `.agentwheel/config.json`; it does not install runtime files by itself.
 
 ```bash
-agentwheel add github:owner/repo --adapter openclaw
-agentwheel add github:owner/repo --adapter claude
-agentwheel add github:owner/repo --adapter codex
-agentwheel add github:owner/repo --adapter hermes
-agentwheel add github:owner/repo --adapter copilot
+agentwheel add github:owner/repo --adapter openclaw --installation-type local
+agentwheel add github:owner/repo --adapter claude --installation-type local
+agentwheel add github:owner/repo --adapter codex --installation-type local
+agentwheel add github:owner/repo --adapter hermes --installation-type user
+agentwheel add github:owner/repo --adapter copilot --installation-type local
 ```
 
 Select only part of a package:
@@ -141,6 +145,35 @@ agentwheel add github:owner/repo --select skills/code-review --select rules/core
 agentwheel add github:owner/repo --select skills/code-review,rules/core.md
 ```
 
+Use a source override when a selected package should replace the same artifact coming from another
+source, such as a forked skill overriding a meta-pack dependency. The declaration is explicit and
+planning fails if it does not match exactly one losing artifact and one selected replacement:
+
+```bash
+agentwheel add github:example-org/agent-toolkit#main \
+  --skill self-improve \
+  --override 'github:example-upstream/agent-toolkit::skills/self-improve'
+```
+
+Equivalent config:
+
+```json
+{
+  "name": "agent-toolkit-nestdev",
+  "source": "github:example-org/agent-toolkit#main",
+  "driver": "git",
+  "adapter": "codex",
+  "installationType": "local",
+  "mode": "tracking",
+  "select": ["skills/self-improve"],
+  "overrides": ["github:example-upstream/agent-toolkit::skills/self-improve"]
+}
+```
+
+`source::type/name` identifies the artifact being replaced. `github:owner/repo` matches any ref
+for that repo; include `#main` or another ref to narrow it. Review `OVERRIDE` lines in
+`agentwheel plan`, `agentwheel deps tree`, or `agentwheel deps why` before applying fleet-wide.
+
 Use `--name` for a stable local alias:
 
 ```bash
@@ -178,9 +211,14 @@ agentwheel install team-agent-pack
 Add and install a source in one step:
 
 ```bash
-agentwheel install github:owner/repo --adapter codex
+agentwheel install github:owner/repo --adapter codex,claude
 ```
 
+Explicit source installs with explicit adapters default to documented user-level installs. Pass
+`--local` for the current directory or `-t/--target-root <project>` for project/workspace installs, and use `--user`, `--local`,
+or `-i/--installation-type <type>` when scope should be explicit. If a package can be installed in
+more than one type and no CLI/context default applies, agentwheel fails instead of guessing.
+
 Target selection order is `--target-root`, then `--agent`, then runtime auto-detection from the current directory, then the current directory.
 
 ## Status
@@ -191,8 +229,15 @@ Use status to see configured packages, lock/manifest state, and pending install
 agentwheel status
 agentwheel status --agent lab-codex
 agentwheel status --all
+agentwheel status --profile daily
 ```
 
+For profile-managed fleets, prefer `agentwheel status --profile <name>` over
+direct agent status; profile status uses the same runtime resolution, adapter
+config, installation type, and graph lock fingerprinting as
+`install --profile <name>`. If a workspace defines a profile named `all`,
+`agentwheel status --all` checks that profile.
+
 ## Named Agents And Profiles
 
 Global config is `~/.agentwheel/config.json`. Project config is `.agentwheel/config.json`; project values win.
@@ -205,8 +250,8 @@ Current config shape:
   "packages": [],
   "registry": {},
   "agents": {
-    "lab-codex": { "adapter": "codex", "root": "/Users/me/project" },
-    "lab-claude": { "adapter": "claude", "root": "/Users/me/project" }
+    "lab-codex": { "adapter": "codex", "installationType": "local", "root": "$HOME/project" },
+    "lab-claude": { "adapter": "claude", "installationType": "local", "root": "$HOME/project" }
   },
   "profiles": {
     "daily": {
@@ -272,8 +317,14 @@ Target configured agents:
 ```bash
 agentwheel update --agent lab-codex --dry-run
 agentwheel update --all --dry-run
+agentwheel update --profile daily --dry-run
 ```
 
+For profile-managed fleets, use `agentwheel update --profile <name>` before
+`install --profile <name>` when tracking packages should move forward. If a
+workspace defines a profile named `all`, `agentwheel update --all` checks that
+profile.
+
 Limit an update to one configured package:
 
 ```bash
@@ -289,7 +340,9 @@ Drift means a managed runtime output changed outside agentwheel. Fix drift by ch
 
 - Layer local instructions with `agentwheel remember`.
 - Add separate local artifacts under `.agentwheel/additions`.
-- Override an upstream item under `.agentwheel/overrides`.
+- Override upstream content under `.agentwheel/overrides`.
+- Override source precedence with package `overrides` when a forked source should replace a
+  colliding upstream artifact.
 - Eject an item into `.agentwheel/ejected` when the user wants local ownership.
 
 Append durable local instruction text:
@@ -388,7 +441,7 @@ agentwheel install
 If the current directory has multiple runtime markers:
 
 ```bash
-agentwheel install --adapter codex --dry-run
+agentwheel install --adapter codex --installation-type local --dry-run
 ```
 
 If a selected artifact is missing:

package/skills/agentwheel-smoke/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: agentwheel-smoke
+description: Run a read-only smoke diagnostic for the current AI harness and its Agentwheel-managed installation state. Use when asked to smoke test an agent, verify fleet deployment, inspect whether a harness is installed in the expected Agentwheel path, or summarize local Agentwheel status without mutating files or external systems.
+---
+
+# Agentwheel Smoke
+
+Use this skill to answer: "What harness am I running in, where was this skill installed, and what does Agentwheel think about this target?"
+
+The default workflow is read-only. Do not run `agentwheel install`, `agentwheel update`, `agentwheel uninstall`, `agentwheel remember`, `agentwheel eject`, or any file-writing fix while using this skill unless the user separately approves that mutation scope.
+
+## Quick Start
+
+From the user's current workspace, run the bundled smoke script:
+
+```bash
+node path/to/agentwheel-smoke/scripts/smoke.mjs
+```
+
+Use JSON output only when another tool or script needs to consume the result:
+
+```bash
+node path/to/agentwheel-smoke/scripts/smoke.mjs --json
+```
+
+When the user names an Agentwheel target, pass only read-only status target flags:
+
+```bash
+node path/to/agentwheel-smoke/scripts/smoke.mjs --agent lab-codex
+node path/to/agentwheel-smoke/scripts/smoke.mjs --profile daily
+node path/to/agentwheel-smoke/scripts/smoke.mjs --all
+```
+
+## Report The Result
+
+Summarize the script output in four parts:
+
+- Overall: `PASS`, `WARN`, or `FAIL`.
+- Harness: detected adapter, installation type, runtime root, and skill path.
+- Agentwheel: CLI availability, version, config locations, packages, agents, profiles, and status result.
+- Recommended next command: prefer `agentwheel status`, `agentwheel plan`, or `agentwheel install --dry-run`.
+
+Treat these as important signals:
+
+- `PASS`: skill path maps to a documented Agentwheel harness target and `agentwheel status` reports no pending work.
+- `WARN`: the skill is running from package source, status is missing, config is absent, manifest is missing, or pending work is reported.
+- `FAIL`: Agentwheel CLI is unavailable, the skill path maps to a known wrong target, `agentwheel status` exits unsuccessfully, or drift/conflict appears.
+
+## Compatibility Checks
+
+Use these documented skill targets when explaining path compatibility:
+
+- Codex local: `.agents/skills/<name>/SKILL.md`; Codex user: `~/.agents/skills/<name>/SKILL.md`.
+- Claude local: `.claude/skills/<name>/SKILL.md`; Claude user: `~/.claude/skills/<name>/SKILL.md`.
+- Copilot local: `.github/skills/<name>/SKILL.md`; Copilot user: `~/.copilot/skills/<name>/SKILL.md`.
+- OpenClaw local: `skills/<name>/SKILL.md`; OpenClaw user: `~/.openclaw/skills/<name>/SKILL.md`.
+- Hermes user: `~/.hermes/skills/<name>/SKILL.md`; local Hermes skills are unsupported by default.
+
+Flag `.codex/skills/<name>/SKILL.md` as incompatible for Agentwheel-managed Codex skills.
+
+## Safety
+
+This skill is diagnostic. It may inspect files and run read-only Agentwheel commands, but it must not mutate runtime outputs, package source, Google Workspace data, Git state, registry state, or deployment state.

package/skills/agentwheel-smoke/scripts/smoke.mjs

@@ -0,0 +1,397 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import os from "node:os";
+
+const skillName = "agentwheel-smoke";
+const scriptPath = fileURLToPath(import.meta.url);
+const skillRoot = dirname(dirname(scriptPath));
+const cwd = process.cwd();
+const home = os.homedir();
+
+const parsed = parseArgs(process.argv.slice(2));
+if (parsed.error) {
+  console.error(parsed.error);
+  process.exit(2);
+}
+
+const config = findConfigs(cwd, home);
+const harness = detectHarness(skillRoot, cwd, home);
+const envHint = detectHarnessFromEnv();
+const agentwheel = inspectAgentwheel(parsed.statusArgs, envHint);
+const manifests = findStateFiles(harness.runtimeRoot ?? projectRootFromConfig(config.projectConfig) ?? cwd);
+const assessment = assess({ harness, agentwheel, manifests, config });
+const report = {
+  overall: assessment.overall,
+  checks: assessment.checks,
+  harness,
+  agentwheel,
+  config,
+  manifests,
+  recommendedNextCommand: recommendedNextCommand(assessment, agentwheel.status.args),
+};
+
+if (parsed.json) {
+  console.log(JSON.stringify(report, null, 2));
+} else {
+  console.log(formatMarkdown(report));
+}
+
+process.exit(report.overall === "FAIL" ? 1 : 0);
+
+function parseArgs(args) {
+  const statusArgs = [];
+  let json = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--json") {
+      json = true;
+      continue;
+    }
+    if (["--all", "--all-detected"].includes(arg)) {
+      statusArgs.push(arg);
+      continue;
+    }
+    if (["--agent", "--profile", "--target-root", "--adapter", "--installation-type"].includes(arg)) {
+      const value = args[index + 1];
+      if (!value || value.startsWith("--")) return { error: `${arg} requires a value.` };
+      statusArgs.push(arg, value);
+      index += 1;
+      continue;
+    }
+    return { error: `Unsupported smoke option: ${arg}` };
+  }
+  return { json, statusArgs };
+}
+
+function inspectAgentwheel(statusArgs, hint) {
+  const which = run("command", ["-v", "agentwheel"], { shell: true });
+  const version = which.ok ? run("agentwheel", ["--version"]) : { ok: false, code: null, stdout: "", stderr: "agentwheel not found" };
+  let effectiveStatusArgs = statusArgs;
+  let status = which.ok ? run("agentwheel", ["status", ...effectiveStatusArgs]) : { ok: false, code: null, stdout: "", stderr: "agentwheel not found" };
+  if (!status.ok && statusArgs.length === 0 && /Multiple runtime directories detected/i.test(status.stderr) && hint?.adapter) {
+    effectiveStatusArgs = ["--adapter", hint.adapter, "--installation-type", hint.installationType ?? "local"];
+    status = run("agentwheel", ["status", ...effectiveStatusArgs]);
+  }
+  return {
+    cliAvailable: which.ok,
+    cliPath: firstLine(which.stdout),
+    version: firstLine(version.stdout),
+    status: {
+      args: effectiveStatusArgs,
+      ok: status.ok,
+      code: status.code,
+      stdout: status.stdout.trim(),
+      stderr: status.stderr.trim(),
+      summary: summarizeStatus(status.stdout, status.stderr),
+    },
+  };
+}
+
+function run(command, args, options = {}) {
+  try {
+    const stdout = execFileSync(command, args, {
+      cwd,
+      env: { ...process.env, AGENTWHEEL_NO_UPDATE_CHECK: "1" },
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: options.shell ?? false,
+    });
+    return { ok: true, code: 0, stdout, stderr: "" };
+  } catch (error) {
+    return {
+      ok: false,
+      code: typeof error.status === "number" ? error.status : null,
+      stdout: String(error.stdout ?? ""),
+      stderr: String(error.stderr ?? error.message ?? ""),
+    };
+  }
+}
+
+function findConfigs(start, homeDir) {
+  const globalConfig = join(homeDir, ".agentwheel", "config.json");
+  const foundConfig = findUp(start, ".agentwheel/config.json");
+  const projectConfig = foundConfig && resolve(foundConfig) !== resolve(globalConfig) ? foundConfig : null;
+  return {
+    projectConfig,
+    globalConfig: existsSync(globalConfig) ? globalConfig : null,
+    project: projectConfig ? summarizeConfig(projectConfig) : null,
+    global: existsSync(globalConfig) ? summarizeConfig(globalConfig) : null,
+  };
+}
+
+function detectHarnessFromEnv() {
+  if (process.env.CODEX_THREAD_ID || process.env.CODEX_CI) return { adapter: "codex", installationType: "local" };
+  if (process.env.CLAUDECODE || process.env.CLAUDE_CODE) return { adapter: "claude", installationType: "local" };
+  if (process.env.GITHUB_COPILOT_CLI || process.env.COPILOT_AGENT) return { adapter: "copilot", installationType: "local" };
+  return null;
+}
+
+function summarizeConfig(path) {
+  try {
+    const json = JSON.parse(readFileSync(path, "utf8"));
+    return {
+      packages: Array.isArray(json.packages) ? json.packages.map((entry) => entry.name ?? entry.source ?? "unnamed") : [],
+      agents: json.agents && typeof json.agents === "object" ? Object.keys(json.agents) : [],
+      profiles: json.profiles && typeof json.profiles === "object" ? Object.keys(json.profiles) : [],
+    };
+  } catch (error) {
+    return { error: error.message };
+  }
+}
+
+function detectHarness(path, currentDir, homeDir) {
+  const normalized = resolve(path);
+  const homeRelative = relative(homeDir, normalized);
+  const localPatterns = [
+    { marker: [".agents", "skills", skillName], adapter: "codex", installationType: "local", expected: ".agents/skills/<name>" },
+    { marker: [".claude", "skills", skillName], adapter: "claude", installationType: "local", expected: ".claude/skills/<name>" },
+    { marker: [".github", "skills", skillName], adapter: "copilot", installationType: "local", expected: ".github/skills/<name>" },
+    { marker: ["skills", skillName], adapter: "openclaw", installationType: "local", expected: "skills/<name>" },
+  ];
+  const userPatterns = [
+    { root: join(homeDir, ".agents", "skills", skillName), adapter: "codex", installationType: "user", expected: "~/.agents/skills/<name>" },
+    { root: join(homeDir, ".claude", "skills", skillName), adapter: "claude", installationType: "user", expected: "~/.claude/skills/<name>" },
+    { root: join(homeDir, ".copilot", "skills", skillName), adapter: "copilot", installationType: "user", expected: "~/.copilot/skills/<name>" },
+    { root: join(homeDir, ".openclaw", "skills", skillName), adapter: "openclaw", installationType: "user", expected: "~/.openclaw/skills/<name>" },
+    { root: join(homeDir, ".hermes", "skills", skillName), adapter: "hermes", installationType: "user", expected: "~/.hermes/skills/<name>" },
+  ];
+  const wrongCodex = containsSegments(normalized, [".codex", "skills", skillName]);
+  if (wrongCodex) {
+    return {
+      adapter: "codex",
+      installationType: "unknown",
+      confidence: "high",
+      runtimeRoot: null,
+      skillPath: normalized,
+      expectedSkillPath: ".agents/skills/<name> or ~/.agents/skills/<name>",
+      compatibility: "FAIL",
+      note: ".codex/skills is not an Agentwheel-managed Codex skill target.",
+    };
+  }
+  for (const pattern of userPatterns) {
+    if (normalized === pattern.root || normalized.startsWith(`${pattern.root}${sep}`)) {
+      return {
+        adapter: pattern.adapter,
+        installationType: pattern.installationType,
+        confidence: "high",
+        runtimeRoot: homeDir,
+        skillPath: normalized,
+        expectedSkillPath: pattern.expected,
+        compatibility: "PASS",
+        note: `Skill path is under ${pattern.expected}.`,
+      };
+    }
+  }
+  for (const pattern of localPatterns) {
+    const root = rootBeforeMarker(normalized, pattern.marker);
+    if (!root) continue;
+    const packageSource = pattern.adapter === "openclaw" && isAgentwheelSourcePackage(root);
+    return {
+      adapter: packageSource ? "unknown" : pattern.adapter,
+      installationType: packageSource ? "source" : pattern.installationType,
+      confidence: packageSource ? "medium" : "high",
+      runtimeRoot: root,
+      skillPath: normalized,
+      expectedSkillPath: pattern.expected,
+      compatibility: packageSource ? "WARN" : "PASS",
+      note: packageSource
+        ? "Skill is running from the Agentwheel source package; this is useful for authoring but does not prove fleet deployment."
+        : `Skill path is under ${pattern.expected}.`,
+    };
+  }
+  return {
+    adapter: "unknown",
+    installationType: "unknown",
+    confidence: "low",
+    runtimeRoot: findUp(currentDir, ".agentwheel") ? dirname(findUp(currentDir, ".agentwheel")) : null,
+    skillPath: normalized,
+    expectedSkillPath: null,
+    compatibility: "WARN",
+    note: `Could not map ${homeRelative.startsWith("..") ? normalized : `~/${homeRelative}`} to a documented Agentwheel skill target.`,
+  };
+}
+
+function isAgentwheelSourcePackage(root) {
+  const openpackPath = join(root, "openpack.json");
+  if (!existsSync(openpackPath)) return false;
+  try {
+    const json = JSON.parse(readFileSync(openpackPath, "utf8"));
+    return json.name === "NestDevLab/agentwheel";
+  } catch {
+    return false;
+  }
+}
+
+function findStateFiles(root) {
+  const stateDir = join(root, ".agentwheel");
+  if (!existsSync(stateDir)) return { root, installManifests: [], sourceLocks: [] };
+  const files = readdirSync(stateDir).sort();
+  return {
+    root,
+    installManifests: files.filter((file) => file.endsWith(".install-manifest.json")),
+    sourceLocks: files.filter((file) => file.endsWith(".source-lock.json")),
+  };
+}
+
+function assess({ harness, agentwheel, manifests, config }) {
+  const checks = [];
+  pushCheck(checks, harness.compatibility, "harness-path", harness.note);
+  pushCheck(checks, agentwheel.cliAvailable ? "PASS" : "FAIL", "agentwheel-cli", agentwheel.cliAvailable ? `Found ${agentwheel.cliPath}` : "agentwheel is not available on PATH.");
+  pushCheck(checks, agentwheel.status.ok ? "PASS" : "FAIL", "agentwheel-status", agentwheel.status.ok ? "agentwheel status completed." : statusFailure(agentwheel.status));
+  pushCheck(checks, config.projectConfig || config.globalConfig ? "PASS" : "WARN", "agentwheel-config", config.projectConfig || config.globalConfig ? "Agentwheel config found." : "No project or global Agentwheel config found.");
+  const statusHasManifest = /Install manifest:\s*(?!missing\b).+/i.test(agentwheel.status.stdout);
+  pushCheck(
+    checks,
+    manifests.installManifests.length > 0 || statusHasManifest ? "PASS" : "WARN",
+    "install-manifest",
+    manifests.installManifests.length > 0
+      ? `${manifests.installManifests.length} install manifest file(s) found.`
+      : statusHasManifest
+        ? "agentwheel status reports an install manifest."
+        : "No install manifest files found under the target .agentwheel directory.",
+  );
+  if (statusHasBlockingDriftOrConflict(agentwheel.status.stdout + agentwheel.status.stderr)) {
+    pushCheck(checks, "FAIL", "drift-conflict", "agentwheel status reports drift or conflict.");
+  }
+  if (statusHasPendingInstallWork(agentwheel.status.stdout)) {
+    pushCheck(checks, "WARN", "pending-work", "agentwheel status reports pending install work.");
+  }
+  if (/Install manifest:\s*missing/i.test(agentwheel.status.stdout)) {
+    pushCheck(checks, "WARN", "manifest-missing", "agentwheel status reports a missing install manifest.");
+  }
+  const overall = checks.some((check) => check.status === "FAIL") ? "FAIL" : checks.some((check) => check.status === "WARN") ? "WARN" : "PASS";
+  return { overall, checks };
+}
+
+function projectRootFromConfig(configPath) {
+  return configPath ? dirname(dirname(configPath)) : null;
+}
+
+function statusHasBlockingDriftOrConflict(text) {
+  return /^Pending install work:.*(?:\bdrift=[1-9]\d*|\bconflict=[1-9]\d*|\bblocking=[1-9]\d*)/im.test(text)
+    || /^\s*(?:DRIFT|CONFLICT)\s+/im.test(text);
+}
+
+function statusHasPendingInstallWork(text) {
+  const line = String(text ?? "").split(/\r?\n/).find((entry) => /^Pending install work:/i.test(entry));
+  if (!line) return false;
+  const value = line.replace(/^Pending install work:/i, "").trim();
+  return value.length > 0 && !/^none$/i.test(value);
+}
+
+function recommendedNextCommand(assessment, statusArgs) {
+  const target = statusArgs.length > 0 ? ` ${statusArgs.join(" ")}` : "";
+  if (assessment.checks.some((check) => check.id === "agentwheel-cli" && check.status === "FAIL")) return "Install or expose the agentwheel CLI, then rerun the smoke test.";
+  if (assessment.checks.some((check) => check.id === "drift-conflict")) return `agentwheel status${target}`;
+  if (assessment.checks.some((check) => check.id === "pending-work" || check.id === "manifest-missing")) return `agentwheel plan${target}`;
+  return `agentwheel status${target}`;
+}
+
+function formatMarkdown(report) {
+  const lines = [
+    "# Agentwheel Smoke Report",
+    "",
+    `Overall: ${report.overall}`,
+    "",
+    "## Harness",
+    `- Detected adapter: ${report.harness.adapter}`,
+    `- Installation type: ${report.harness.installationType}`,
+    `- Confidence: ${report.harness.confidence}`,
+    `- Runtime root: ${report.harness.runtimeRoot ?? "unknown"}`,
+    `- Skill path: ${report.harness.skillPath}`,
+    `- Expected skill path: ${report.harness.expectedSkillPath ?? "unknown"}`,
+    `- Compatibility: ${report.harness.compatibility}`,
+    `- Note: ${report.harness.note}`,
+    "",
+    "## Agentwheel",
+    `- CLI available: ${yesNo(report.agentwheel.cliAvailable)}`,
+    `- CLI path: ${report.agentwheel.cliPath || "not found"}`,
+    `- Version: ${report.agentwheel.version || "unknown"}`,
+    `- Status command: ${report.agentwheel.status.ok ? "PASS" : "FAIL"}`,
+    `- Status args: ${report.agentwheel.status.args.length > 0 ? report.agentwheel.status.args.join(" ") : "none"}`,
+    `- Status summary: ${report.agentwheel.status.summary}`,
+    "",
+    "## Config",
+    `- Project config: ${report.config.projectConfig ?? "not found"}`,
+    `- Global config: ${report.config.globalConfig ?? "not found"}`,
+    `- Project packages: ${listOrNone(report.config.project?.packages)}`,
+    `- Project agents: ${listOrNone(report.config.project?.agents)}`,
+    `- Project profiles: ${listOrNone(report.config.project?.profiles)}`,
+    "",
+    "## Managed State",
+    `- State root checked: ${report.manifests.root}`,
+    `- Install manifests: ${listOrNone(report.manifests.installManifests)}`,
+    `- Source locks: ${listOrNone(report.manifests.sourceLocks)}`,
+    "",
+    "## Checks",
+    ...report.checks.map((check) => `- ${check.status} ${check.id}: ${check.message}`),
+    "",
+    "## Recommended Next Command",
+    `- ${report.recommendedNextCommand}`,
+  ];
+  if (report.agentwheel.status.stdout) {
+    lines.push("", "## agentwheel status stdout", "```text", report.agentwheel.status.stdout, "```");
+  }
+  if (report.agentwheel.status.stderr) {
+    lines.push("", "## agentwheel status stderr", "```text", report.agentwheel.status.stderr, "```");
+  }
+  return lines.join("\n");
+}
+
+function summarizeStatus(stdout, stderr) {
+  const text = `${stdout}\n${stderr}`.trim();
+  if (!text) return "no status output";
+  const interesting = text.split(/\r?\n/).filter((line) =>
+    /Status for|Install manifest|Graph lock|Pending install work|No agents configured|No packages configured|drift|conflict/i.test(line),
+  );
+  return interesting.length > 0 ? interesting.join(" | ") : firstLine(text);
+}
+
+function statusFailure(status) {
+  return status.stderr || status.stdout || "agentwheel status failed.";
+}
+
+function pushCheck(checks, status, id, message) {
+  checks.push({ status, id, message });
+}
+
+function firstLine(value) {
+  return String(value ?? "").trim().split(/\r?\n/)[0] ?? "";
+}
+
+function yesNo(value) {
+  return value ? "yes" : "no";
+}
+
+function listOrNone(values) {
+  return values && values.length > 0 ? values.join(", ") : "none";
+}
+
+function findUp(start, relativePath) {
+  let cursor = resolve(start);
+  while (true) {
+    const candidate = join(cursor, relativePath);
+    if (existsSync(candidate)) return candidate;
+    const next = dirname(cursor);
+    if (next === cursor) return null;
+    cursor = next;
+  }
+}
+
+function rootBeforeMarker(path, marker) {
+  const parts = resolve(path).split(sep).filter(Boolean);
+  for (let index = 0; index <= parts.length - marker.length; index += 1) {
+    if (marker.every((part, offset) => parts[index + offset] === part)) {
+      const rootParts = parts.slice(0, index);
+      return `${sep}${rootParts.join(sep)}`;
+    }
+  }
+  return null;
+}
+
+function containsSegments(path, marker) {
+  return Boolean(rootBeforeMarker(path, marker));
+}