threadroot 0.1.1 → 0.1.3

package/dist/index.js

@@ -3,121 +3,24 @@
 // src/cli.ts
 import { Command } from "commander";
 
-// src/core/compile/write.ts
-import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
-import path6 from "path";
-
-// src/core/harness/schema.ts
-import { z as z2 } from "zod";
-
-// src/types.ts
-import { z } from "zod";
-var profileIdSchema = z.enum([
-  "nextjs",
-  "vite-react",
-  "fastapi",
-  "python-cli",
-  "node-cli",
-  "dbt",
-  "empty"
-]);
+// src/core/bootstrap.ts
+import { stat as stat9 } from "fs/promises";
+import path23 from "path";
 
-// src/core/harness/schema.ts
-var objectScopeSchema = z2.enum(["user", "project"]);
-var riskLevelSchema = z2.enum(["low", "medium", "high"]);
-var adapterIdSchema = z2.enum(["agents", "claude", "copilot", "cursor"]);
-var memoryTypeSchema = z2.enum(["project", "repo-map", "current-focus", "handoff", "pitfalls"]);
-var referenceSchema = z2.object({
-  path: z2.string().min(1),
-  description: z2.string().optional(),
-  load: z2.enum(["link", "eager"]).default("link")
-});
-var harnessManifestSchema = z2.object({
-  name: z2.string().min(1),
-  version: z2.literal(1),
-  profile: profileIdSchema,
-  adapters: z2.array(adapterIdSchema).default([]),
-  references: z2.array(referenceSchema).default([]),
-  memory: z2.object({
-    budget: z2.record(memoryTypeSchema, z2.number().int().positive()).default({})
-  }).default({ budget: {} }),
-  tools: z2.object({
-    allow: z2.array(z2.string()).default([])
-  }).default({ allow: [] })
-});
-var skillFrontmatterSchema = z2.object({
-  name: z2.string().min(1),
-  description: z2.string().min(1).optional(),
-  when: z2.string().min(1).optional(),
-  license: z2.string().min(1).optional(),
-  compatibility: z2.string().max(500).optional(),
-  metadata: z2.record(z2.unknown()).optional(),
-  allowedTools: z2.union([z2.string(), z2.array(z2.string())]).optional(),
-  "allowed-tools": z2.union([z2.string(), z2.array(z2.string())]).optional(),
-  scope: objectScopeSchema.default("project"),
-  tags: z2.array(z2.string()).default([])
-}).refine((skill) => Boolean(skill.description ?? skill.when), {
-  message: "A skill must define `description` or legacy `when`.",
-  path: ["description"]
-}).transform((skill) => {
-  const trigger = skill.description ?? skill.when;
-  const allowedTools = skill.allowedTools ?? skill["allowed-tools"];
-  return {
-    ...skill,
-    description: skill.description ?? trigger,
-    when: skill.when ?? trigger,
-    allowedTools,
-    "allowed-tools": void 0
-  };
-});
-var ruleFrontmatterSchema = z2.object({
-  name: z2.string().min(1),
-  applyTo: z2.string().min(1).optional(),
-  scope: objectScopeSchema.default("project")
-});
-var toolInputParamSchema = z2.object({
-  type: z2.enum(["string", "number", "boolean"]).default("string"),
-  description: z2.string().optional(),
-  default: z2.union([z2.string(), z2.number(), z2.boolean()]).optional()
-});
-var healthcheckSchema = z2.object({
-  run: z2.string().min(1),
-  expectExitCode: z2.number().int().default(0)
-});
-var toolManifestSchema = z2.object({
-  name: z2.string().min(1),
-  description: z2.string().min(1),
-  scope: objectScopeSchema.default("project"),
-  risk: riskLevelSchema.default("low"),
-  confirm: z2.boolean().default(false),
-  connection: z2.string().min(1).optional(),
-  healthcheck: healthcheckSchema.optional(),
-  input: z2.record(z2.string(), toolInputParamSchema).default({}),
-  run: z2.string().min(1).optional(),
-  script: z2.string().min(1).optional()
-}).refine((tool) => Boolean(tool.run) !== Boolean(tool.script), {
-  message: "A tool must define exactly one of `run` or `script`.",
-  path: ["run"]
-});
-var connectionManifestSchema = z2.object({
-  name: z2.string().min(1),
-  provider: z2.string().min(1),
-  kind: z2.literal("cli").default("cli"),
-  command: z2.string().min(1),
-  profile: z2.string().min(1).optional(),
-  description: z2.string().min(1),
-  scope: objectScopeSchema.default("project"),
-  risk: riskLevelSchema.default("medium"),
-  confirm: z2.boolean().default(false),
-  healthcheck: healthcheckSchema.optional(),
-  allow: z2.array(z2.string()).default([]),
-  deny: z2.array(z2.string()).default([])
-});
+// src/core/doctor.ts
+import { stat as stat5 } from "fs/promises";
+import path15 from "path";
 
-// src/core/harness/paths.ts
-import os from "os";
+// src/core/compile/index.ts
+import { readFile, stat } from "fs/promises";
 import path2 from "path";
 
+// src/core/hash.ts
+import { createHash } from "crypto";
+function hashContent(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+
 // src/core/paths.ts
 import path from "path";
 function toRepoPath(repoRoot, relativePath) {
@@ -133,430 +36,68 @@ function toRepoPath(repoRoot, relativePath) {
   return resolved;
 }
 
-// src/core/harness/paths.ts
-var HARNESS_DIR = ".threadroot";
-var HARNESS_MANIFEST = "harness.yaml";
-var LOCK_FILE = "lock.json";
-var HARNESS_SUBDIRS = {
-  skills: "skills",
-  tools: "tools",
-  connections: "connections",
-  rules: "rules",
-  memory: "memory"
-};
-var HARNESS_OBJECT_EXT = {
-  prose: ".md",
-  tool: ".yaml"
+// src/core/compile/adapters/agents.ts
+var agentsAdapter = {
+  id: "agents",
+  compile(ctx) {
+    return [{ path: "AGENTS.md", content: ctx.canonicalAgents }];
+  }
 };
-function projectHarnessDir(repoRoot) {
-  return toRepoPath(repoRoot, HARNESS_DIR);
-}
-function projectManifestPath(repoRoot) {
-  return toRepoPath(repoRoot, path2.join(HARNESS_DIR, HARNESS_MANIFEST));
-}
-function projectLockPath(repoRoot) {
-  return toRepoPath(repoRoot, path2.join(HARNESS_DIR, LOCK_FILE));
-}
-function projectObjectDir(repoRoot, dir) {
-  return toRepoPath(repoRoot, path2.join(HARNESS_DIR, HARNESS_SUBDIRS[dir]));
-}
-function userHarnessDir(home = os.homedir()) {
-  return path2.join(home, HARNESS_DIR);
-}
-function userObjectDir(dir, home = os.homedir()) {
-  return path2.join(userHarnessDir(home), HARNESS_SUBDIRS[dir]);
-}
-function userLockPath(home = os.homedir()) {
-  return path2.join(userHarnessDir(home), LOCK_FILE);
-}
 
-// src/core/harness/frontmatter.ts
-import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
-var FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
-function parseFrontmatter(raw) {
-  const normalized = raw.replace(/^\uFEFF/, "");
-  const match = FRONTMATTER_RE.exec(normalized);
-  if (!match) {
-    return { data: {}, body: normalized.trim() };
+// src/core/compile/adapters/shared.ts
+function slug(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "rule";
+}
+function ruleBody(rule) {
+  const body = rule.body.trim();
+  if (body.startsWith("#")) {
+    return body;
   }
-  const parsed = parseYaml(match[1] ?? "");
-  const data = parsed && typeof parsed === "object" ? parsed : {};
-  return { data, body: (match[2] ?? "").trim() };
+  return `# ${rule.name}
+
+${body}`;
 }
-function serializeFrontmatter(data, body) {
-  const front = stringifyYaml(data).trimEnd();
-  return `---
-${front}
----
 
-${body.trim()}
+// src/core/compile/adapters/claude.ts
+function claudeRoot() {
+  const lines = [
+    "# CLAUDE.md",
+    "",
+    "@AGENTS.md",
+    "",
+    "<!-- The shared harness lives in AGENTS.md (imported above). Claude-specific",
+    "     guidance can be added below this comment; it is preserved across compiles. -->"
+  ];
+  return `${lines.join("\n")}
 `;
 }
+function ruleFile(name, applyTo, body) {
+  const frontmatter = ["---", `name: ${name}`, "paths:", `  - "${applyTo}"`, "---", ""].join("\n");
+  return { path: `.claude/rules/${slug(name)}.md`, content: `${frontmatter}
+${body}
+` };
+}
+function commandFile(name, description, run2, script) {
+  const frontmatter = ["---", `description: ${description}`, "---", ""].join("\n");
+  const invocation = run2 ? `Run this shell command and report the result:
 
-// src/core/harness/load.ts
-import { readFile, readdir } from "fs/promises";
-import path3 from "path";
-import { parse as parseYaml2 } from "yaml";
-var HarnessError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "HarnessError";
-  }
-};
-async function readObjectFiles(dir, ext) {
-  let entries;
-  try {
-    entries = await readdir(dir);
-  } catch (error) {
-    if (error.code === "ENOENT") {
-      return [];
-    }
-    throw error;
-  }
-  const files = entries.filter((name) => name.endsWith(ext)).sort();
-  return Promise.all(
-    files.map(async (name) => {
-      const full = path3.join(dir, name);
-      return { path: full, content: await readFile(full, "utf8") };
-    })
-  );
+\`\`\`sh
+${run2}
+\`\`\`` : `Run the script at \`.threadroot/tools/${script}\` and report the result.`;
+  const body = [`# /${slug(name)}`, "", description, "", invocation].join("\n");
+  return { path: `.claude/commands/${slug(name)}.md`, content: `${frontmatter}
+${body}
+` };
 }
-async function readSkillFiles(dir) {
-  let entries;
-  try {
-    entries = await readdir(dir, { withFileTypes: true });
-  } catch (error) {
-    if (error.code === "ENOENT") {
-      return [];
-    }
-    throw error;
-  }
-  const files = [];
-  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
-    if (entry.isFile() && entry.name.endsWith(HARNESS_OBJECT_EXT.prose)) {
-      const full = path3.join(dir, entry.name);
-      files.push({ path: full, content: await readFile(full, "utf8") });
-      continue;
-    }
-    if (entry.isDirectory()) {
-      const full = path3.join(dir, entry.name, "SKILL.md");
-      try {
-        files.push({ path: full, content: await readFile(full, "utf8") });
-      } catch (error) {
-        if (error.code !== "ENOENT") {
-          throw error;
-        }
-      }
-    }
-  }
-  return files;
-}
-function objectDirFor(repoRoot, dir, origin, home) {
-  return origin === "project" ? projectObjectDir(repoRoot, dir) : userObjectDir(dir, home);
-}
-function describe(error) {
-  if (error && typeof error === "object" && "issues" in error) {
-    const issues = error.issues;
-    return issues.map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`).join("; ");
-  }
-  return error instanceof Error ? error.message : String(error);
-}
-async function loadSkillsFrom(dir, origin) {
-  const files = await readSkillFiles(dir);
-  return files.map((file) => {
-    const { data, body } = parseFrontmatter(file.content);
-    const result = skillFrontmatterSchema.safeParse(data);
-    if (!result.success) {
-      throw new HarnessError(`Invalid skill ${file.path}: ${describe(result.error)}`);
-    }
-    return { name: result.data.name, origin, sourcePath: file.path, frontmatter: result.data, body };
-  });
-}
-async function loadRulesFrom(dir, origin) {
-  const files = await readObjectFiles(dir, HARNESS_OBJECT_EXT.prose);
-  return files.map((file) => {
-    const { data, body } = parseFrontmatter(file.content);
-    const result = ruleFrontmatterSchema.safeParse(data);
-    if (!result.success) {
-      throw new HarnessError(`Invalid rule ${file.path}: ${describe(result.error)}`);
-    }
-    return { name: result.data.name, origin, sourcePath: file.path, frontmatter: result.data, body };
-  });
-}
-async function loadToolsFrom(dir, origin) {
-  const files = await readObjectFiles(dir, HARNESS_OBJECT_EXT.tool);
-  return files.map((file) => {
-    const parsed = parseYaml2(file.content);
-    const result = toolManifestSchema.safeParse(parsed);
-    if (!result.success) {
-      throw new HarnessError(`Invalid tool ${file.path}: ${describe(result.error)}`);
-    }
-    return { name: result.data.name, origin, sourcePath: file.path, manifest: result.data };
-  });
-}
-async function loadConnectionsFrom(dir, origin) {
-  const files = await readObjectFiles(dir, HARNESS_OBJECT_EXT.tool);
-  return files.map((file) => {
-    const parsed = parseYaml2(file.content);
-    const result = connectionManifestSchema.safeParse(parsed);
-    if (!result.success) {
-      throw new HarnessError(`Invalid connection ${file.path}: ${describe(result.error)}`);
-    }
-    return { name: result.data.name, origin, sourcePath: file.path, manifest: result.data };
-  });
-}
-async function loadMemoryFrom(dir, origin) {
-  const files = await readObjectFiles(dir, HARNESS_OBJECT_EXT.prose);
-  const memory = [];
-  for (const file of files) {
-    const base = path3.basename(file.path, HARNESS_OBJECT_EXT.prose);
-    const type = memoryTypeSchema.safeParse(base);
-    if (!type.success) {
-      continue;
-    }
-    const { body } = parseFrontmatter(file.content);
-    memory.push({ type: type.data, origin, sourcePath: file.path, body });
-  }
-  return memory;
-}
-function mergeByName(user, project) {
-  const merged = /* @__PURE__ */ new Map();
-  for (const item of user) {
-    merged.set(item.name, item);
-  }
-  for (const item of project) {
-    merged.set(item.name, item);
-  }
-  return [...merged.values()].sort((a, b) => a.name.localeCompare(b.name));
-}
-async function loadManifest(repoRoot) {
-  const manifestPath = projectManifestPath(repoRoot);
-  let raw;
-  try {
-    raw = await readFile(manifestPath, "utf8");
-  } catch (error) {
-    if (error.code === "ENOENT") {
-      throw new HarnessError(`No harness found at ${manifestPath}. Run \`tr init\` first.`);
-    }
-    throw error;
-  }
-  const result = harnessManifestSchema.safeParse(parseYaml2(raw));
-  if (!result.success) {
-    throw new HarnessError(`Invalid ${manifestPath}: ${describe(result.error)}`);
-  }
-  return result.data;
-}
-async function resolveHarness(repoRoot, opts = {}) {
-  const { home } = opts;
-  const manifest = await loadManifest(repoRoot);
-  const [
-    userSkills,
-    projectSkills,
-    userRules,
-    projectRules,
-    userTools,
-    projectTools,
-    userConnections,
-    projectConnections,
-    userMemory,
-    projectMemory
-  ] = await Promise.all([
-    loadSkillsFrom(objectDirFor(repoRoot, "skills", "user", home), "user"),
-    loadSkillsFrom(objectDirFor(repoRoot, "skills", "project", home), "project"),
-    loadRulesFrom(objectDirFor(repoRoot, "rules", "user", home), "user"),
-    loadRulesFrom(objectDirFor(repoRoot, "rules", "project", home), "project"),
-    loadToolsFrom(objectDirFor(repoRoot, "tools", "user", home), "user"),
-    loadToolsFrom(objectDirFor(repoRoot, "tools", "project", home), "project"),
-    loadConnectionsFrom(objectDirFor(repoRoot, "connections", "user", home), "user"),
-    loadConnectionsFrom(objectDirFor(repoRoot, "connections", "project", home), "project"),
-    loadMemoryFrom(objectDirFor(repoRoot, "memory", "user", home), "user"),
-    loadMemoryFrom(objectDirFor(repoRoot, "memory", "project", home), "project")
-  ]);
-  return {
-    manifest,
-    skills: mergeByName(userSkills, projectSkills),
-    rules: mergeByName(userRules, projectRules),
-    tools: mergeByName(userTools, projectTools),
-    connections: mergeByName(userConnections, projectConnections),
-    memory: [...userMemory, ...projectMemory]
-  };
-}
-
-// src/core/harness/context.ts
-function taskTerms(task) {
-  return [
-    ...new Set(
-      task.toLowerCase().split(/[^a-z0-9+#.-]+/).filter((term) => term.length > 2)
-    )
-  ];
-}
-function scoreSkill(haystack, terms) {
-  const lower = haystack.toLowerCase();
-  return terms.reduce((score, term) => score + (lower.includes(term) ? 1 : 0), 0);
-}
-async function assembleContext(repoRoot, task, options = {}) {
-  const harness = options.harness ?? await resolveHarness(repoRoot, { home: options.home });
-  const terms = taskTerms(task);
-  const ranked = harness.skills.map((skill) => ({
-    skill,
-    score: scoreSkill(`${skill.name} ${skill.frontmatter.when} ${skill.frontmatter.tags.join(" ")}`, terms)
-  })).filter((entry) => entry.score > 0).sort((a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name)).slice(0, options.limit ?? 8).map(({ skill, score }) => ({
-    name: skill.name,
-    when: skill.frontmatter.when,
-    tags: skill.frontmatter.tags,
-    scope: skill.frontmatter.scope,
-    sourcePath: skill.sourcePath,
-    score
-  }));
-  return {
-    task,
-    skills: ranked,
-    rules: harness.rules.map((rule) => ({ name: rule.name, applyTo: rule.frontmatter.applyTo })),
-    tools: harness.tools.map((tool) => ({
-      name: tool.name,
-      description: tool.manifest.description,
-      confirm: tool.manifest.confirm,
-      risk: tool.manifest.risk,
-      connection: tool.manifest.connection,
-      healthcheck: Boolean(tool.manifest.healthcheck),
-      kind: tool.manifest.run ? "shell" : "script"
-    })),
-    memory: harness.memory.map((entry) => ({ type: entry.type, body: entry.body }))
-  };
-}
-
-// src/core/harness/memory.ts
-import { mkdir, readFile as readFile2, writeFile } from "fs/promises";
-import path4 from "path";
-function assertMemoryType(type) {
-  const parsed = memoryTypeSchema.safeParse(type);
-  if (!parsed.success) {
-    throw new HarnessError(
-      `Unknown memory type \`${type}\`. Expected one of: ${memoryTypeSchema.options.join(", ")}.`
-    );
-  }
-  return parsed.data;
-}
-function memoryDir(repoRoot, scope, home) {
-  return scope === "project" ? projectObjectDir(repoRoot, "memory") : userObjectDir("memory", home);
-}
-function memoryFilePath(repoRoot, type, scope = "project", home) {
-  return path4.join(memoryDir(repoRoot, scope, home), `${type}${HARNESS_OBJECT_EXT.prose}`);
-}
-async function readMemory(repoRoot, type, options = {}) {
-  const memoryType = assertMemoryType(type);
-  const file = memoryFilePath(repoRoot, memoryType, options.scope ?? "project", options.home);
-  try {
-    const raw = await readFile2(file, "utf8");
-    return parseFrontmatter(raw).body;
-  } catch (error) {
-    if (error.code === "ENOENT") {
-      return null;
-    }
-    throw error;
-  }
-}
-function headingFor(type) {
-  const title = type.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
-  return `# ${title}`;
-}
-async function appendMemory(repoRoot, type, note, options = {}) {
-  const memoryType = assertMemoryType(type);
-  const trimmed = note.trim();
-  if (!trimmed) {
-    throw new HarnessError("Cannot append an empty memory note.");
-  }
-  const scope = options.scope ?? "project";
-  const dir = memoryDir(repoRoot, scope, options.home);
-  const file = memoryFilePath(repoRoot, memoryType, scope, options.home);
-  let existing = "";
-  try {
-    existing = await readFile2(file, "utf8");
-  } catch (error) {
-    if (error.code !== "ENOENT") {
-      throw error;
-    }
-  }
-  await mkdir(dir, { recursive: true });
-  const base = existing.trim() ? existing.replace(/\s*$/, "") : headingFor(memoryType);
-  await writeFile(file, `${base}
-- ${trimmed}
-`, "utf8");
-  return { type: memoryType, scope, path: file };
-}
-
-// src/core/compile/index.ts
-import { readFile as readFile3, stat } from "fs/promises";
-import path5 from "path";
-
-// src/core/hash.ts
-import { createHash } from "crypto";
-function hashContent(content) {
-  return createHash("sha256").update(content).digest("hex");
-}
-
-// src/core/compile/adapters/agents.ts
-var agentsAdapter = {
-  id: "agents",
-  compile(ctx) {
-    return [{ path: "AGENTS.md", content: ctx.canonicalAgents }];
-  }
-};
-
-// src/core/compile/adapters/shared.ts
-function slug(name) {
-  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "rule";
-}
-function ruleBody(rule) {
-  const body = rule.body.trim();
-  if (body.startsWith("#")) {
-    return body;
-  }
-  return `# ${rule.name}
-
-${body}`;
-}
-
-// src/core/compile/adapters/claude.ts
-function claudeRoot() {
-  const lines = [
-    "# CLAUDE.md",
-    "",
-    "@AGENTS.md",
-    "",
-    "<!-- The shared harness lives in AGENTS.md (imported above). Claude-specific",
-    "     guidance can be added below this comment; it is preserved across compiles. -->"
-  ];
-  return `${lines.join("\n")}
-`;
-}
-function ruleFile(name, applyTo, body) {
-  const frontmatter = ["---", `name: ${name}`, "paths:", `  - "${applyTo}"`, "---", ""].join("\n");
-  return { path: `.claude/rules/${slug(name)}.md`, content: `${frontmatter}
-${body}
-` };
-}
-function commandFile(name, description, run2, script) {
-  const frontmatter = ["---", `description: ${description}`, "---", ""].join("\n");
-  const invocation = run2 ? `Run this shell command and report the result:
-
-\`\`\`sh
-${run2}
-\`\`\`` : `Run the script at \`.threadroot/tools/${script}\` and report the result.`;
-  const body = [`# /${slug(name)}`, "", description, "", invocation].join("\n");
-  return { path: `.claude/commands/${slug(name)}.md`, content: `${frontmatter}
-${body}
-` };
-}
-var claudeAdapter = {
-  id: "claude",
-  compile(ctx) {
-    const files = [{ path: "CLAUDE.md", content: claudeRoot() }];
-    for (const rule of ctx.scopedRules) {
-      const applyTo = rule.frontmatter.applyTo;
-      if (applyTo) {
-        files.push(ruleFile(rule.name, applyTo, ruleBody(rule)));
-      }
+var claudeAdapter = {
+  id: "claude",
+  compile(ctx) {
+    const files = [{ path: "CLAUDE.md", content: claudeRoot() }];
+    for (const rule of ctx.scopedRules) {
+      const applyTo = rule.frontmatter.applyTo;
+      if (applyTo) {
+        files.push(ruleFile(rule.name, applyTo, ruleBody(rule)));
+      }
     }
     for (const tool of ctx.tools) {
       files.push(
@@ -795,7 +336,7 @@ function isGlob(value) {
 }
 async function readIfExists(filePath) {
   try {
-    return await readFile3(filePath, "utf8");
+    return await readFile(filePath, "utf8");
   } catch (error) {
     if (error.code === "ENOENT") {
       return void 0;
@@ -814,7 +355,7 @@ async function resolveReference(repoRoot, reference) {
       return { reference, exists: true };
     }
     if (reference.load === "eager" && info.size <= EAGER_INLINE_LIMIT) {
-      const inlined = await readFile3(absolute, "utf8");
+      const inlined = await readFile(absolute, "utf8");
       return { reference, exists: true, inlined };
     }
     return { reference, exists: true };
@@ -826,7 +367,7 @@ async function resolveReference(repoRoot, reference) {
   }
 }
 async function buildContext(repoRoot, harness) {
-  const existingAgents = await readIfExists(path5.join(repoRoot, AGENTS_FILE)) ?? "";
+  const existingAgents = await readIfExists(path2.join(repoRoot, AGENTS_FILE)) ?? "";
   const handAuthored = extractHandAuthored(existingAgents);
   const { global, scoped } = splitRules(harness.rules);
   const references = await Promise.all(
@@ -858,201 +399,505 @@ async function compile(repoRoot, harness) {
     if (!adapter) {
       continue;
     }
-    for (const file of adapter.compile(ctx)) {
-      if (seen.has(file.path)) {
-        continue;
+    for (const file of adapter.compile(ctx)) {
+      if (seen.has(file.path)) {
+        continue;
+      }
+      seen.add(file.path);
+      files.push(file);
+    }
+  }
+  files.sort((a, b) => a.path.localeCompare(b.path));
+  return files;
+}
+async function detectDrift(repoRoot, files) {
+  const entries = await Promise.all(
+    files.map(async (file) => {
+      const existing = await readIfExists(path2.join(repoRoot, file.path));
+      if (existing === void 0) {
+        return { path: file.path, status: "create" };
+      }
+      const status = hashContent(existing) === hashContent(file.content) ? "unchanged" : "drift";
+      return { path: file.path, status };
+    })
+  );
+  return entries;
+}
+
+// src/core/harness/schema.ts
+import { z as z2 } from "zod";
+
+// src/types.ts
+import { z } from "zod";
+var profileIdSchema = z.enum([
+  "nextjs",
+  "vite-react",
+  "fastapi",
+  "python-cli",
+  "node-cli",
+  "dbt",
+  "empty"
+]);
+
+// src/core/harness/schema.ts
+var objectScopeSchema = z2.enum(["user", "project"]);
+var riskLevelSchema = z2.enum(["low", "medium", "high"]);
+var adapterIdSchema = z2.enum(["agents", "claude", "copilot", "cursor"]);
+var memoryTypeSchema = z2.enum(["project", "repo-map", "current-focus", "handoff", "pitfalls"]);
+var referenceSchema = z2.object({
+  path: z2.string().min(1),
+  description: z2.string().optional(),
+  load: z2.enum(["link", "eager"]).default("link")
+});
+var harnessManifestSchema = z2.object({
+  name: z2.string().min(1),
+  version: z2.literal(1),
+  profile: profileIdSchema,
+  adapters: z2.array(adapterIdSchema).default([]),
+  references: z2.array(referenceSchema).default([]),
+  memory: z2.object({
+    budget: z2.record(memoryTypeSchema, z2.number().int().positive()).default({})
+  }).default({ budget: {} }),
+  tools: z2.object({
+    allow: z2.array(z2.string()).default([])
+  }).default({ allow: [] })
+});
+var skillFrontmatterSchema = z2.object({
+  name: z2.string().min(1),
+  description: z2.string().min(1).optional(),
+  when: z2.string().min(1).optional(),
+  license: z2.string().min(1).optional(),
+  compatibility: z2.string().max(500).optional(),
+  metadata: z2.record(z2.unknown()).optional(),
+  allowedTools: z2.union([z2.string(), z2.array(z2.string())]).optional(),
+  "allowed-tools": z2.union([z2.string(), z2.array(z2.string())]).optional(),
+  scope: objectScopeSchema.default("project"),
+  tags: z2.array(z2.string()).default([])
+}).refine((skill) => Boolean(skill.description ?? skill.when), {
+  message: "A skill must define `description` or legacy `when`.",
+  path: ["description"]
+}).transform((skill) => {
+  const trigger = skill.description ?? skill.when;
+  const allowedTools = skill.allowedTools ?? skill["allowed-tools"];
+  return {
+    ...skill,
+    description: skill.description ?? trigger,
+    when: skill.when ?? trigger,
+    allowedTools,
+    "allowed-tools": void 0
+  };
+});
+var ruleFrontmatterSchema = z2.object({
+  name: z2.string().min(1),
+  applyTo: z2.string().min(1).optional(),
+  scope: objectScopeSchema.default("project")
+});
+var toolInputParamSchema = z2.object({
+  type: z2.enum(["string", "number", "boolean"]).default("string"),
+  description: z2.string().optional(),
+  default: z2.union([z2.string(), z2.number(), z2.boolean()]).optional()
+});
+var healthcheckSchema = z2.object({
+  run: z2.string().min(1),
+  expectExitCode: z2.number().int().default(0)
+});
+var toolManifestSchema = z2.object({
+  name: z2.string().min(1),
+  description: z2.string().min(1),
+  scope: objectScopeSchema.default("project"),
+  risk: riskLevelSchema.default("low"),
+  confirm: z2.boolean().default(false),
+  connection: z2.string().min(1).optional(),
+  healthcheck: healthcheckSchema.optional(),
+  input: z2.record(z2.string(), toolInputParamSchema).default({}),
+  run: z2.string().min(1).optional(),
+  script: z2.string().min(1).optional()
+}).refine((tool) => Boolean(tool.run) !== Boolean(tool.script), {
+  message: "A tool must define exactly one of `run` or `script`.",
+  path: ["run"]
+});
+var connectionManifestSchema = z2.object({
+  name: z2.string().min(1),
+  provider: z2.string().min(1),
+  kind: z2.literal("cli").default("cli"),
+  command: z2.string().min(1),
+  profile: z2.string().min(1).optional(),
+  description: z2.string().min(1),
+  scope: objectScopeSchema.default("project"),
+  risk: riskLevelSchema.default("medium"),
+  confirm: z2.boolean().default(false),
+  healthcheck: healthcheckSchema.optional(),
+  allow: z2.array(z2.string()).default([]),
+  deny: z2.array(z2.string()).default([])
+});
+
+// src/core/harness/paths.ts
+import os from "os";
+import path3 from "path";
+var HARNESS_DIR = ".threadroot";
+var HARNESS_MANIFEST = "harness.yaml";
+var LOCK_FILE = "lock.json";
+var HARNESS_SUBDIRS = {
+  skills: "skills",
+  tools: "tools",
+  connections: "connections",
+  rules: "rules",
+  memory: "memory"
+};
+var HARNESS_OBJECT_EXT = {
+  prose: ".md",
+  tool: ".yaml"
+};
+function projectHarnessDir(repoRoot) {
+  return toRepoPath(repoRoot, HARNESS_DIR);
+}
+function projectManifestPath(repoRoot) {
+  return toRepoPath(repoRoot, path3.join(HARNESS_DIR, HARNESS_MANIFEST));
+}
+function projectLockPath(repoRoot) {
+  return toRepoPath(repoRoot, path3.join(HARNESS_DIR, LOCK_FILE));
+}
+function projectObjectDir(repoRoot, dir) {
+  return toRepoPath(repoRoot, path3.join(HARNESS_DIR, HARNESS_SUBDIRS[dir]));
+}
+function userHarnessDir(home = os.homedir()) {
+  return path3.join(home, HARNESS_DIR);
+}
+function userObjectDir(dir, home = os.homedir()) {
+  return path3.join(userHarnessDir(home), HARNESS_SUBDIRS[dir]);
+}
+function userLockPath(home = os.homedir()) {
+  return path3.join(userHarnessDir(home), LOCK_FILE);
+}
+
+// src/core/harness/frontmatter.ts
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+var FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+function parseFrontmatter(raw) {
+  const normalized = raw.replace(/^\uFEFF/, "");
+  const match = FRONTMATTER_RE.exec(normalized);
+  if (!match) {
+    return { data: {}, body: normalized.trim() };
+  }
+  const parsed = parseYaml(match[1] ?? "");
+  const data = parsed && typeof parsed === "object" ? parsed : {};
+  return { data, body: (match[2] ?? "").trim() };
+}
+function serializeFrontmatter(data, body) {
+  const front = stringifyYaml(data).trimEnd();
+  return `---
+${front}
+---
+
+${body.trim()}
+`;
+}
+
+// src/core/harness/load.ts
+import { readFile as readFile2, readdir } from "fs/promises";
+import path4 from "path";
+import { parse as parseYaml2 } from "yaml";
+var HarnessError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "HarnessError";
+  }
+};
+async function readObjectFiles(dir, ext) {
+  let entries;
+  try {
+    entries = await readdir(dir);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+  const files = entries.filter((name) => name.endsWith(ext)).sort();
+  return Promise.all(
+    files.map(async (name) => {
+      const full = path4.join(dir, name);
+      return { path: full, content: await readFile2(full, "utf8") };
+    })
+  );
+}
+async function readSkillFiles(dir) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+  const files = [];
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (entry.isFile() && entry.name.endsWith(HARNESS_OBJECT_EXT.prose)) {
+      const full = path4.join(dir, entry.name);
+      files.push({ path: full, content: await readFile2(full, "utf8") });
+      continue;
+    }
+    if (entry.isDirectory()) {
+      const full = path4.join(dir, entry.name, "SKILL.md");
+      try {
+        files.push({ path: full, content: await readFile2(full, "utf8") });
+      } catch (error) {
+        if (error.code !== "ENOENT") {
+          throw error;
+        }
       }
-      seen.add(file.path);
-      files.push(file);
     }
   }
-  files.sort((a, b) => a.path.localeCompare(b.path));
   return files;
 }
-async function detectDrift(repoRoot, files) {
-  const entries = await Promise.all(
-    files.map(async (file) => {
-      const existing = await readIfExists(path5.join(repoRoot, file.path));
-      if (existing === void 0) {
-        return { path: file.path, status: "create" };
-      }
-      const status = hashContent(existing) === hashContent(file.content) ? "unchanged" : "drift";
-      return { path: file.path, status };
-    })
-  );
-  return entries;
+function objectDirFor(repoRoot, dir, origin, home) {
+  return origin === "project" ? projectObjectDir(repoRoot, dir) : userObjectDir(dir, home);
 }
-
-// src/core/compile/write.ts
-async function writeCompiled(repoRoot, files) {
-  await Promise.all(
-    files.map(async (file) => {
-      const absolute = path6.join(repoRoot, file.path);
-      await mkdir2(path6.dirname(absolute), { recursive: true });
-      await writeFile2(absolute, file.content, "utf8");
-    })
-  );
-  return files.map((file) => file.path);
+function describe(error) {
+  if (error && typeof error === "object" && "issues" in error) {
+    const issues = error.issues;
+    return issues.map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`).join("; ");
+  }
+  return error instanceof Error ? error.message : String(error);
 }
-async function runCompile(repoRoot, options = {}) {
-  const resolved = options.harness ?? await resolveHarness(repoRoot, { home: options.home });
-  const harness = options.adapter ? { ...resolved, manifest: { ...resolved.manifest, adapters: [options.adapter] } } : resolved;
-  const files = await compile(repoRoot, harness);
-  const drift = await detectDrift(repoRoot, files);
-  const written = await writeCompiled(repoRoot, files);
-  return { written, drift };
+async function loadSkillsFrom(dir, origin) {
+  const files = await readSkillFiles(dir);
+  return files.map((file) => {
+    const { data, body } = parseFrontmatter(file.content);
+    const result = skillFrontmatterSchema.safeParse(data);
+    if (!result.success) {
+      throw new HarnessError(`Invalid skill ${file.path}: ${describe(result.error)}`);
+    }
+    return { name: result.data.name, origin, sourcePath: file.path, frontmatter: result.data, body };
+  });
 }
-
-// src/commands/compile.ts
-async function runCompileCommand(repoRoot, options) {
-  const adapter = options.adapter ? adapterIdSchema.parse(options.adapter) : void 0;
-  try {
-    const { written, drift } = await runCompile(repoRoot, { adapter });
-    const changed = drift.filter((entry) => entry.status !== "unchanged").length;
-    console.log(`Compiled ${written.length} vendor file(s)${changed > 0 ? ` (${changed} changed)` : ""}.`);
-    for (const file of written) {
-      console.log(`  ${file}`);
+async function loadRulesFrom(dir, origin) {
+  const files = await readObjectFiles(dir, HARNESS_OBJECT_EXT.prose);
+  return files.map((file) => {
+    const { data, body } = parseFrontmatter(file.content);
+    const result = ruleFrontmatterSchema.safeParse(data);
+    if (!result.success) {
+      throw new HarnessError(`Invalid rule ${file.path}: ${describe(result.error)}`);
     }
-  } catch (error) {
-    if (error instanceof HarnessError) {
-      console.error(error.message);
-      process.exitCode = 1;
-      return;
+    return { name: result.data.name, origin, sourcePath: file.path, frontmatter: result.data, body };
+  });
+}
+async function loadToolsFrom(dir, origin) {
+  const files = await readObjectFiles(dir, HARNESS_OBJECT_EXT.tool);
+  return files.map((file) => {
+    const parsed = parseYaml2(file.content);
+    const result = toolManifestSchema.safeParse(parsed);
+    if (!result.success) {
+      throw new HarnessError(`Invalid tool ${file.path}: ${describe(result.error)}`);
     }
-    throw error;
+    return { name: result.data.name, origin, sourcePath: file.path, manifest: result.data };
+  });
+}
+async function loadConnectionsFrom(dir, origin) {
+  const files = await readObjectFiles(dir, HARNESS_OBJECT_EXT.tool);
+  return files.map((file) => {
+    const parsed = parseYaml2(file.content);
+    const result = connectionManifestSchema.safeParse(parsed);
+    if (!result.success) {
+      throw new HarnessError(`Invalid connection ${file.path}: ${describe(result.error)}`);
+    }
+    return { name: result.data.name, origin, sourcePath: file.path, manifest: result.data };
+  });
+}
+async function loadMemoryFrom(dir, origin) {
+  const files = await readObjectFiles(dir, HARNESS_OBJECT_EXT.prose);
+  const memory = [];
+  for (const file of files) {
+    const base = path4.basename(file.path, HARNESS_OBJECT_EXT.prose);
+    const type = memoryTypeSchema.safeParse(base);
+    if (!type.success) {
+      continue;
+    }
+    const { body } = parseFrontmatter(file.content);
+    memory.push({ type: type.data, origin, sourcePath: file.path, body });
   }
+  return memory;
 }
-
-// src/commands/context.ts
-async function runContext(repoRoot, task) {
-  let context;
+function mergeByName(user, project) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const item of user) {
+    merged.set(item.name, item);
+  }
+  for (const item of project) {
+    merged.set(item.name, item);
+  }
+  return [...merged.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+async function loadManifest(repoRoot) {
+  const manifestPath = projectManifestPath(repoRoot);
+  let raw;
   try {
-    context = await assembleContext(repoRoot, task);
+    raw = await readFile2(manifestPath, "utf8");
   } catch (error) {
-    if (error instanceof HarnessError) {
-      console.log("No harness found. Run `tr init` first.");
-      return;
+    if (error.code === "ENOENT") {
+      throw new HarnessError(`No harness found at ${manifestPath}. Run \`tr init\` first.`);
     }
     throw error;
   }
-  console.log(`task: ${context.task}`);
-  if (context.skills.length > 0) {
-    console.log("\nskills:");
-    for (const skill of context.skills) {
-      console.log(`- ${skill.name} - ${skill.when}`);
-    }
-  }
-  if (context.rules.length > 0) {
-    console.log("\nrules:");
-    for (const rule of context.rules) {
-      console.log(`- ${rule.name}${rule.applyTo ? ` (${rule.applyTo})` : ""}`);
-    }
-  }
-  if (context.tools.length > 0) {
-    console.log("\ntools:");
-    for (const tool of context.tools) {
-      console.log(`- ${tool.name} - ${tool.description}`);
-    }
+  const result = harnessManifestSchema.safeParse(parseYaml2(raw));
+  if (!result.success) {
+    throw new HarnessError(`Invalid ${manifestPath}: ${describe(result.error)}`);
   }
-  if (context.memory.length > 0) {
-    console.log("\nmemory:");
-    for (const entry of context.memory) {
-      console.log(`- ${entry.type}`);
-    }
+  return result.data;
+}
+async function resolveHarness(repoRoot, opts = {}) {
+  const { home } = opts;
+  const manifest = await loadManifest(repoRoot);
+  const [
+    userSkills,
+    projectSkills,
+    userRules,
+    projectRules,
+    userTools,
+    projectTools,
+    userConnections,
+    projectConnections,
+    userMemory,
+    projectMemory
+  ] = await Promise.all([
+    loadSkillsFrom(objectDirFor(repoRoot, "skills", "user", home), "user"),
+    loadSkillsFrom(objectDirFor(repoRoot, "skills", "project", home), "project"),
+    loadRulesFrom(objectDirFor(repoRoot, "rules", "user", home), "user"),
+    loadRulesFrom(objectDirFor(repoRoot, "rules", "project", home), "project"),
+    loadToolsFrom(objectDirFor(repoRoot, "tools", "user", home), "user"),
+    loadToolsFrom(objectDirFor(repoRoot, "tools", "project", home), "project"),
+    loadConnectionsFrom(objectDirFor(repoRoot, "connections", "user", home), "user"),
+    loadConnectionsFrom(objectDirFor(repoRoot, "connections", "project", home), "project"),
+    loadMemoryFrom(objectDirFor(repoRoot, "memory", "user", home), "user"),
+    loadMemoryFrom(objectDirFor(repoRoot, "memory", "project", home), "project")
+  ]);
+  return {
+    manifest,
+    skills: mergeByName(userSkills, projectSkills),
+    rules: mergeByName(userRules, projectRules),
+    tools: mergeByName(userTools, projectTools),
+    connections: mergeByName(userConnections, projectConnections),
+    memory: [...userMemory, ...projectMemory]
+  };
+}
+
+// src/core/harness/context.ts
+function taskTerms(task) {
+  return [
+    ...new Set(
+      task.toLowerCase().split(/[^a-z0-9+#.-]+/).filter((term) => term.length > 2)
+    )
+  ];
+}
+function scoreSkill(haystack, terms) {
+  const lower = haystack.toLowerCase();
+  return terms.reduce((score, term) => score + (lower.includes(term) ? 1 : 0), 0);
+}
+async function assembleContext(repoRoot, task, options = {}) {
+  const harness = options.harness ?? await resolveHarness(repoRoot, { home: options.home });
+  const terms = taskTerms(task);
+  let ranked = harness.skills.map((skill) => ({
+    skill,
+    score: scoreSkill(`${skill.name} ${skill.frontmatter.when} ${skill.frontmatter.tags.join(" ")}`, terms)
+  })).filter((entry) => entry.score > 0).sort((a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name)).slice(0, options.limit ?? 8).map(({ skill, score }) => ({
+    name: skill.name,
+    when: skill.frontmatter.when,
+    tags: skill.frontmatter.tags,
+    scope: skill.frontmatter.scope,
+    sourcePath: skill.sourcePath,
+    score
+  }));
+  if (ranked.length === 0 && options.fallbackSkills) {
+    ranked = harness.skills.slice(0, options.limit ?? 8).map((skill) => ({
+      name: skill.name,
+      when: skill.frontmatter.when,
+      tags: skill.frontmatter.tags,
+      scope: skill.frontmatter.scope,
+      sourcePath: skill.sourcePath,
+      score: 0
+    }));
   }
-  if (context.skills.length === 0 && context.rules.length === 0 && context.tools.length === 0 && context.memory.length === 0) {
-    console.log("\nNo matching harness context for this task yet.");
+  return {
+    task,
+    skills: ranked,
+    rules: harness.rules.map((rule) => ({ name: rule.name, applyTo: rule.frontmatter.applyTo })),
+    tools: harness.tools.map((tool) => ({
+      name: tool.name,
+      description: tool.manifest.description,
+      confirm: tool.manifest.confirm,
+      risk: tool.manifest.risk,
+      connection: tool.manifest.connection,
+      healthcheck: Boolean(tool.manifest.healthcheck),
+      kind: tool.manifest.run ? "shell" : "script"
+    })),
+    memory: harness.memory.map((entry) => ({ type: entry.type, body: entry.body }))
+  };
+}
+
+// src/core/harness/memory.ts
+import { mkdir, readFile as readFile3, writeFile } from "fs/promises";
+import path5 from "path";
+function assertMemoryType(type) {
+  const parsed = memoryTypeSchema.safeParse(type);
+  if (!parsed.success) {
+    throw new HarnessError(
+      `Unknown memory type \`${type}\`. Expected one of: ${memoryTypeSchema.options.join(", ")}.`
+    );
   }
+  return parsed.data;
+}
+function memoryDir(repoRoot, scope, home) {
+  return scope === "project" ? projectObjectDir(repoRoot, "memory") : userObjectDir("memory", home);
 }
-
-// src/commands/diff.ts
-import fs from "fs/promises";
-import path7 from "path";
-async function readIfExists2(filePath) {
+function memoryFilePath(repoRoot, type, scope = "project", home) {
+  return path5.join(memoryDir(repoRoot, scope, home), `${type}${HARNESS_OBJECT_EXT.prose}`);
+}
+async function readMemory(repoRoot, type, options = {}) {
+  const memoryType = assertMemoryType(type);
+  const file = memoryFilePath(repoRoot, memoryType, options.scope ?? "project", options.home);
   try {
-    return await fs.readFile(filePath, "utf8");
+    const raw = await readFile3(file, "utf8");
+    return parseFrontmatter(raw).body;
   } catch (error) {
     if (error.code === "ENOENT") {
-      return void 0;
+      return null;
     }
     throw error;
   }
 }
-function lineDiff(before, after) {
-  const a = before.length === 0 ? [] : before.split("\n");
-  const b = after.length === 0 ? [] : after.split("\n");
-  const lcs = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
-  for (let i2 = a.length - 1; i2 >= 0; i2 -= 1) {
-    for (let j2 = b.length - 1; j2 >= 0; j2 -= 1) {
-      lcs[i2][j2] = a[i2] === b[j2] ? lcs[i2 + 1][j2 + 1] + 1 : Math.max(lcs[i2 + 1][j2], lcs[i2][j2 + 1]);
-    }
-  }
-  const lines = [];
-  let i = 0;
-  let j = 0;
-  while (i < a.length && j < b.length) {
-    if (a[i] === b[j]) {
-      i += 1;
-      j += 1;
-    } else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
-      lines.push(`- ${a[i]}`);
-      i += 1;
-    } else {
-      lines.push(`+ ${b[j]}`);
-      j += 1;
-    }
-  }
-  while (i < a.length) {
-    lines.push(`- ${a[i]}`);
-    i += 1;
-  }
-  while (j < b.length) {
-    lines.push(`+ ${b[j]}`);
-    j += 1;
-  }
-  return lines;
+function headingFor(type) {
+  const title = type.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+  return `# ${title}`;
 }
-async function runDiff(repoRoot) {
-  let harness;
+async function appendMemory(repoRoot, type, note, options = {}) {
+  const memoryType = assertMemoryType(type);
+  const trimmed = note.trim();
+  if (!trimmed) {
+    throw new HarnessError("Cannot append an empty memory note.");
+  }
+  const scope = options.scope ?? "project";
+  const dir = memoryDir(repoRoot, scope, options.home);
+  const file = memoryFilePath(repoRoot, memoryType, scope, options.home);
+  let existing = "";
   try {
-    harness = await resolveHarness(repoRoot);
+    existing = await readFile3(file, "utf8");
   } catch (error) {
-    if (error instanceof HarnessError) {
-      console.log("No harness found. Run `tr init` first.");
-      return;
-    }
-    throw error;
-  }
-  const files = await compile(repoRoot, harness);
-  let changed = 0;
-  for (const file of files) {
-    const existing = await readIfExists2(path7.join(repoRoot, file.path));
-    if (existing === void 0) {
-      changed += 1;
-      console.log(`+ ${file.path} (new)`);
-      continue;
-    }
-    if (existing === file.content) {
-      continue;
-    }
-    changed += 1;
-    console.log(`~ ${file.path}`);
-    for (const line of lineDiff(existing, file.content)) {
-      console.log(`    ${line}`);
+    if (error.code !== "ENOENT") {
+      throw error;
     }
   }
-  if (changed === 0) {
-    console.log("No drift: optional compiled outputs match the canonical harness.");
-  }
+  await mkdir(dir, { recursive: true });
+  const base = existing.trim() ? existing.replace(/\s*$/, "") : headingFor(memoryType);
+  await writeFile(file, `${base}
+- ${trimmed}
+`, "utf8");
+  return { type: memoryType, scope, path: file };
 }
 
-// src/core/doctor.ts
-import { stat as stat5 } from "fs/promises";
-import path16 from "path";
-
 // src/core/install/lock.ts
-import { mkdir as mkdir3, readFile as readFile4, writeFile as writeFile3 } from "fs/promises";
-import path8 from "path";
+import { mkdir as mkdir2, readFile as readFile4, writeFile as writeFile2 } from "fs/promises";
+import path6 from "path";
 
 // src/core/install/source.ts
 import { z as z3 } from "zod";
@@ -1152,8 +997,8 @@ async function writeLockFile(lockPath, lock) {
     version: lock.version,
     objects: [...lock.objects].sort((a, b) => a.name.localeCompare(b.name))
   };
-  await mkdir3(path8.dirname(lockPath), { recursive: true });
-  await writeFile3(lockPath, `${JSON.stringify(sorted, null, 2)}
+  await mkdir2(path6.dirname(lockPath), { recursive: true });
+  await writeFile2(lockPath, `${JSON.stringify(sorted, null, 2)}
 `, "utf8");
 }
 function upsertLockEntry(lock, entry) {
@@ -1182,7 +1027,7 @@ function externalSkillNames(lock) {
 
 // src/core/skills.ts
 import { readFile as readFile5, readdir as readdir2, stat as stat2 } from "fs/promises";
-import path9 from "path";
+import path7 from "path";
 var SKILL_NAME_RE = /^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$/;
 var MIN_DESCRIPTION_LENGTH = 40;
 var MAX_DESCRIPTION_LENGTH = 1024;
@@ -1197,8 +1042,8 @@ function validateResolvedSkills(harness) {
     if (!SKILL_NAME_RE.test(skill.name)) {
       findings.push(finding("error", skill, "Skill names must use lowercase letters, digits, and hyphens."));
     }
-    if (path9.basename(skill.sourcePath) === "SKILL.md") {
-      const folderName = path9.basename(path9.dirname(skill.sourcePath));
+    if (path7.basename(skill.sourcePath) === "SKILL.md") {
+      const folderName = path7.basename(path7.dirname(skill.sourcePath));
       if (folderName !== skill.name) {
         findings.push(finding("error", skill, "Folder-based skill directory must match frontmatter `name`."));
       }
@@ -1263,14 +1108,14 @@ async function exists(filePath) {
   }
 }
 async function validateSkillDirectory(skill) {
-  if (path9.basename(skill.sourcePath) !== "SKILL.md") {
+  if (path7.basename(skill.sourcePath) !== "SKILL.md") {
     return [];
   }
   const findings = [];
-  const skillDir = path9.dirname(skill.sourcePath);
-  const referencesDir = path9.join(skillDir, "references");
-  const scriptsDir = path9.join(skillDir, "scripts");
-  const evalsDir = path9.join(skillDir, "evals");
+  const skillDir = path7.dirname(skill.sourcePath);
+  const referencesDir = path7.join(skillDir, "references");
+  const scriptsDir = path7.join(skillDir, "scripts");
+  const evalsDir = path7.join(skillDir, "evals");
   if (await exists(scriptsDir)) {
     pushPathFinding(
       findings,
@@ -1285,11 +1130,11 @@ async function validateSkillDirectory(skill) {
     if (/^[a-z]+:\/\//i.test(target) || target.startsWith("#")) {
       continue;
     }
-    if (path9.isAbsolute(target) || target.split(/[\\/]/).includes("..")) {
+    if (path7.isAbsolute(target) || target.split(/[\\/]/).includes("..")) {
       pushPathFinding(findings, "error", skill, `Skill link must stay inside the skill directory: ${target}`);
       continue;
     }
-    const resolved = path9.join(skillDir, target);
+    const resolved = path7.join(skillDir, target);
     if (!await exists(resolved)) {
       pushPathFinding(findings, "error", skill, `Skill links to missing file: ${target}`);
     }
@@ -1304,7 +1149,7 @@ async function validateSkillDirectory(skill) {
       if (!entry.isFile()) {
         continue;
       }
-      const filePath = path9.join(referencesDir, entry.name);
+      const filePath = path7.join(referencesDir, entry.name);
       const body = await readFile5(filePath, "utf8");
       if (!body.trim()) {
         pushPathFinding(findings, "error", skill, "Reference file must not be empty.", filePath);
@@ -1312,7 +1157,7 @@ async function validateSkillDirectory(skill) {
     }
   }
   if (await exists(evalsDir)) {
-    const triggersPath = path9.join(evalsDir, "triggers.json");
+    const triggersPath = path7.join(evalsDir, "triggers.json");
     if (!await exists(triggersPath)) {
       pushPathFinding(findings, "warning", skill, "Skill evals directory should include triggers.json.", evalsDir);
     } else {
@@ -1357,7 +1202,7 @@ async function loadSkillsAtPath(targetPath) {
   if (info.isFile()) {
     return [await loadSkillFile(targetPath)];
   }
-  const directSkill = path9.join(targetPath, "SKILL.md");
+  const directSkill = path7.join(targetPath, "SKILL.md");
   try {
     return [await loadSkillFile(directSkill)];
   } catch (error) {
@@ -1371,12 +1216,12 @@ async function loadSkillsAtPath(targetPath) {
   const entries = await readdir2(targetPath, { withFileTypes: true });
   const skills = [];
   for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
-    const full = path9.join(targetPath, entry.name);
+    const full = path7.join(targetPath, entry.name);
     if (entry.isFile() && entry.name.endsWith(".md") && entry.name !== "README.md") {
       skills.push(await loadSkillFile(full));
     }
     if (entry.isDirectory()) {
-      const skillPath = path9.join(full, "SKILL.md");
+      const skillPath = path7.join(full, "SKILL.md");
       try {
         skills.push(await loadSkillFile(skillPath));
       } catch (error) {
@@ -1401,15 +1246,15 @@ async function inspectSkillPath(targetPath) {
     throw new HarnessError(`Expected exactly one skill at ${targetPath}; found ${skills.length}.`);
   }
   const skill = skills[0];
-  const skillDir = path9.dirname(skill.sourcePath);
+  const skillDir = path7.dirname(skill.sourcePath);
   return {
     name: skill.name,
     description: skill.frontmatter.description,
     path: skill.sourcePath,
-    references: await listFilesIfDir(path9.join(skillDir, "references")),
-    scripts: await listFilesIfDir(path9.join(skillDir, "scripts")),
-    assets: await listFilesIfDir(path9.join(skillDir, "assets")),
-    evals: await listFilesIfDir(path9.join(skillDir, "evals")),
+    references: await listFilesIfDir(path7.join(skillDir, "references")),
+    scripts: await listFilesIfDir(path7.join(skillDir, "scripts")),
+    assets: await listFilesIfDir(path7.join(skillDir, "assets")),
+    evals: await listFilesIfDir(path7.join(skillDir, "evals")),
     allowedTools: skill.frontmatter.allowedTools
   };
 }
@@ -1471,13 +1316,13 @@ async function validateSkills(repoRoot, options = {}) {
 }
 
 // src/core/connections/index.ts
-import { mkdir as mkdir4, writeFile as writeFile4 } from "fs/promises";
-import path11 from "path";
+import { mkdir as mkdir3, writeFile as writeFile3 } from "fs/promises";
+import path9 from "path";
 import { stringify as stringifyYaml2 } from "yaml";
 
 // src/core/tools/execute.ts
 import { spawn } from "child_process";
-import path10 from "path";
+import path8 from "path";
 var ToolExecutionError = class extends Error {
   constructor(message) {
     super(message);
@@ -1565,15 +1410,15 @@ function runProcess(plan, opts) {
   });
 }
 function planScript(repoRoot, scriptRef) {
-  const resolved = path10.resolve(repoRoot, scriptRef);
+  const resolved = path8.resolve(repoRoot, scriptRef);
   const projectRoot = projectHarnessDir(repoRoot);
   const userRoot = userHarnessDir();
-  const withinProject = resolved === projectRoot || resolved.startsWith(`${projectRoot}${path10.sep}`);
-  const withinUser = resolved === userRoot || resolved.startsWith(`${userRoot}${path10.sep}`);
+  const withinProject = resolved === projectRoot || resolved.startsWith(`${projectRoot}${path8.sep}`);
+  const withinUser = resolved === userRoot || resolved.startsWith(`${userRoot}${path8.sep}`);
   if (!withinProject && !withinUser) {
     throw new ToolExecutionError(`Script must live under the harness directory: ${scriptRef}`);
   }
-  const interpreter = INTERPRETERS[path10.extname(resolved).toLowerCase()];
+  const interpreter = INTERPRETERS[path8.extname(resolved).toLowerCase()];
   if (interpreter) {
     return { file: interpreter, args: [resolved], shell: false, label: `${interpreter} ${scriptRef}` };
   }
@@ -1650,9 +1495,9 @@ async function createConnection(repoRoot, input2, options = {}) {
     throw new ConnectionCreateError(`Invalid connection definition: ${detail}`);
   }
   const dir = scope === "project" ? projectObjectDir(repoRoot, "connections") : userObjectDir("connections", options.home);
-  const filePath = path11.join(dir, `${input2.name}.yaml`);
-  await mkdir4(dir, { recursive: true });
-  await writeFile4(filePath, stringifyYaml2(parsed.data), { encoding: "utf8", flag: options.force ? "w" : "wx" }).catch(
+  const filePath = path9.join(dir, `${input2.name}.yaml`);
+  await mkdir3(dir, { recursive: true });
+  await writeFile3(filePath, stringifyYaml2(parsed.data), { encoding: "utf8", flag: options.force ? "w" : "wx" }).catch(
     (error) => {
       if (error.code === "EEXIST") {
         throw new ConnectionCreateError(
@@ -1712,12 +1557,12 @@ async function checkConnections(repoRoot, options = {}) {
 }
 
 // src/core/setup.ts
-import { mkdir as mkdir5, readFile as readFile6, rm, stat as stat3, writeFile as writeFile5 } from "fs/promises";
+import { mkdir as mkdir4, readFile as readFile6, rm, stat as stat3, writeFile as writeFile4 } from "fs/promises";
 import { homedir } from "os";
-import path13 from "path";
+import path11 from "path";
 
 // src/core/agent-providers.ts
-import path12 from "path";
+import path10 from "path";
 var AGENT_PROVIDER_IDS = [
   "antigravity",
   "claude",
@@ -1732,50 +1577,50 @@ var AGENT_PROVIDERS = {
   antigravity: {
     id: "antigravity",
     label: "Antigravity",
-    projectSkillDir: path12.join(".agent", "skills"),
-    globalSkillDir: path12.join(".gemini", "antigravity", "skills")
+    projectSkillDir: path10.join(".agent", "skills"),
+    globalSkillDir: path10.join(".gemini", "antigravity", "skills")
   },
   claude: {
     id: "claude",
     label: "Claude Code",
-    projectSkillDir: path12.join(".claude", "skills"),
-    globalSkillDir: path12.join(".claude", "skills")
+    projectSkillDir: path10.join(".claude", "skills"),
+    globalSkillDir: path10.join(".claude", "skills")
   },
   codex: {
     id: "codex",
     label: "Codex",
-    projectSkillDir: path12.join(".agents", "skills"),
-    globalSkillDir: path12.join(".agents", "skills")
+    projectSkillDir: path10.join(".agents", "skills"),
+    globalSkillDir: path10.join(".agents", "skills")
   },
   cursor: {
     id: "cursor",
     label: "Cursor",
-    projectSkillDir: path12.join(".cursor", "skills"),
-    globalSkillDir: path12.join(".cursor", "skills")
+    projectSkillDir: path10.join(".cursor", "skills"),
+    globalSkillDir: path10.join(".cursor", "skills")
   },
   gemini: {
     id: "gemini",
     label: "Gemini CLI",
-    projectSkillDir: path12.join(".gemini", "skills"),
-    globalSkillDir: path12.join(".gemini", "skills")
+    projectSkillDir: path10.join(".gemini", "skills"),
+    globalSkillDir: path10.join(".gemini", "skills")
   },
   copilot: {
     id: "copilot",
     label: "GitHub Copilot",
-    projectSkillDir: path12.join(".github", "skills"),
-    globalSkillDir: path12.join(".copilot", "skills")
+    projectSkillDir: path10.join(".github", "skills"),
+    globalSkillDir: path10.join(".copilot", "skills")
   },
   opencode: {
     id: "opencode",
     label: "OpenCode",
-    projectSkillDir: path12.join(".opencode", "skills"),
-    globalSkillDir: path12.join(".config", "opencode", "skills")
+    projectSkillDir: path10.join(".opencode", "skills"),
+    globalSkillDir: path10.join(".config", "opencode", "skills")
   },
   windsurf: {
     id: "windsurf",
     label: "Windsurf",
-    projectSkillDir: path12.join(".windsurf", "skills"),
-    globalSkillDir: path12.join(".codeium", "windsurf", "skills")
+    projectSkillDir: path10.join(".windsurf", "skills"),
+    globalSkillDir: path10.join(".codeium", "windsurf", "skills")
   }
 };
 var ALIASES = {
@@ -1871,16 +1716,17 @@ function threadrootSkillContent(provider, scope) {
     "## Workflow",
     "",
     "1. If `threadroot --version` works, use `threadroot`. Otherwise use `npx --yes threadroot@latest` for one-off commands.",
-    "2. If `.threadroot/harness.yaml` is missing and the user wants setup, run `threadroot init` or `npx --yes threadroot@latest init`.",
-    "3. Before coding in a Threadroot repo, run `threadroot doctor` and resolve errors. Treat warnings as review items, not automatic blockers.",
-    '4. For the current task, run `threadroot context "<task>"` and use the returned skills, rules, tools, memory, and references before doing broad file reads.',
-    "5. Use `threadroot status` to inspect harness state and `threadroot diff` only when compiled adapter outputs are enabled.",
-    "6. Use `threadroot tools list`, `threadroot tools check`, and `threadroot run <tool>` for explicit local capabilities. Confirm risky tools when required.",
-    "7. Do not create provider-specific files unless the user asks. Use `threadroot expose <agent>` when native project skill shims are desired.",
+    "2. If `.threadroot/harness.yaml` is missing and the user wants setup, run `threadroot bootstrap --yes` or `npx --yes threadroot@latest bootstrap --yes`.",
+    '3. At the start of a coding session, run `threadroot start "<task>"` to get doctor status, project state, relevant skills, tools, memory, and the command map.',
+    '4. For a narrower slice, run `threadroot context "<task>"` and use the returned skills, rules, tools, memory, and references before doing broad file reads.',
+    "5. Use `threadroot tools list`, `threadroot tools check`, and `threadroot run <tool>` for explicit local capabilities. Confirm risky tools when required.",
+    "6. Do not create provider-specific files unless the user asks. Use `threadroot expose <agent>` when native project skill shims are desired.",
     "",
     "## Useful Commands",
     "",
     "```bash",
+    "threadroot bootstrap --yes",
+    'threadroot start "<task>"',
     "threadroot doctor",
     "threadroot status",
     'threadroot context "<task>"',
@@ -1928,17 +1774,17 @@ async function fileExists(filePath) {
   }
 }
 function displayPath(home, filePath) {
-  const relative = path13.relative(home, filePath);
-  return relative && !relative.startsWith("..") ? path13.join("~", relative) : filePath;
+  const relative = path11.relative(home, filePath);
+  return relative && !relative.startsWith("..") ? path11.join("~", relative) : filePath;
 }
 function globalSkillPath(home, provider) {
-  return path13.join(home, provider.globalSkillDir, THREADROOT_SKILL_NAME, "SKILL.md");
+  return path11.join(home, provider.globalSkillDir, THREADROOT_SKILL_NAME, "SKILL.md");
 }
 function codexAgentsPath(home) {
-  return path13.join(home, ".codex", "AGENTS.md");
+  return path11.join(home, ".codex", "AGENTS.md");
 }
 function codexConfigPath(home) {
-  return path13.join(home, ".codex", "config.toml");
+  return path11.join(home, ".codex", "config.toml");
 }
 function codexAgentsBlock() {
   return [
@@ -1946,18 +1792,22 @@ function codexAgentsBlock() {
     "## Threadroot",
     "",
     "When a repository contains `.threadroot/`, treat it as the source of truth for agent harness context.",
-    'Before coding, prefer `threadroot doctor` and `threadroot context "<task>"` over broad, unfocused file reads.',
+    'Before coding, prefer `threadroot start "<task>"` over broad, unfocused file reads.',
+    "If `.threadroot/` is missing and the user wants setup, run `threadroot bootstrap --yes`.",
     "Do not create provider-specific project files unless the user asks; use `threadroot expose <agent>` for that.",
     CODEX_AGENTS_END,
     ""
   ].join("\n");
 }
-function codexMcpBlock() {
+function tomlString(value) {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function codexMcpBlock(entry) {
   return [
     CODEX_MCP_BEGIN,
     "[mcp_servers.threadroot]",
-    'command = "threadroot"',
-    'args = ["mcp"]',
+    `command = ${tomlString(entry.command)}`,
+    `args = [${entry.args.map(tomlString).join(", ")}]`,
     CODEX_MCP_END,
     ""
   ].join("\n");
@@ -1994,7 +1844,7 @@ async function setupGlobalSkill(home, provider, mode, force) {
         message: "Existing skill is not Threadroot-managed."
       };
     }
-    await rm(path13.dirname(filePath), { recursive: true, force: true });
+    await rm(path11.dirname(filePath), { recursive: true, force: true });
     return { kind: "skill", agent: provider.id, label: provider.label, path: shown, status: "removed" };
   }
   if (existing === desired) {
@@ -2014,8 +1864,8 @@ async function setupGlobalSkill(home, provider, mode, force) {
   if (mode === "dry-run") {
     return { kind: "skill", agent: provider.id, label: provider.label, path: shown, status };
   }
-  await mkdir5(path13.dirname(filePath), { recursive: true });
-  await writeFile5(filePath, desired, "utf8");
+  await mkdir4(path11.dirname(filePath), { recursive: true });
+  await writeFile4(filePath, desired, "utf8");
   return { kind: "skill", agent: provider.id, label: provider.label, path: shown, status };
 }
 async function setupCodexAgents(home, mode) {
@@ -2036,7 +1886,7 @@ async function setupCodexAgents(home, mode) {
     if (!hasManagedBlock(existing, CODEX_AGENTS_BEGIN, CODEX_AGENTS_END)) {
       return { kind: "codex-agents", agent: "codex", label: "Codex global AGENTS.md", path: shown, status: "missing" };
     }
-    await writeFile5(filePath, removeManagedBlock(existing, CODEX_AGENTS_BEGIN, CODEX_AGENTS_END), "utf8");
+    await writeFile4(filePath, removeManagedBlock(existing, CODEX_AGENTS_BEGIN, CODEX_AGENTS_END), "utf8");
     return { kind: "codex-agents", agent: "codex", label: "Codex global AGENTS.md", path: shown, status: "removed" };
   }
   if (existing === desired) {
@@ -2046,11 +1896,11 @@ async function setupCodexAgents(home, mode) {
   if (mode === "dry-run") {
     return { kind: "codex-agents", agent: "codex", label: "Codex global AGENTS.md", path: shown, status };
   }
-  await mkdir5(path13.dirname(filePath), { recursive: true });
-  await writeFile5(filePath, desired, "utf8");
+  await mkdir4(path11.dirname(filePath), { recursive: true });
+  await writeFile4(filePath, desired, "utf8");
   return { kind: "codex-agents", agent: "codex", label: "Codex global AGENTS.md", path: shown, status };
 }
-async function setupCodexMcp(home, mode) {
+async function setupCodexMcp(home, mode, entry) {
   const filePath = codexConfigPath(home);
   const shown = displayPath(home, filePath);
   const existing = await readMaybe(filePath) ?? "";
@@ -2064,7 +1914,7 @@ async function setupCodexMcp(home, mode) {
       message: "Existing unmanaged [mcp_servers.threadroot] table found. Leaving it untouched."
     };
   }
-  const desired = upsertManagedBlock(existing, codexMcpBlock(), CODEX_MCP_BEGIN, CODEX_MCP_END);
+  const desired = upsertManagedBlock(existing, codexMcpBlock(entry), CODEX_MCP_BEGIN, CODEX_MCP_END);
   if (mode === "check") {
     return {
       kind: "codex-mcp",
@@ -2078,7 +1928,7 @@ async function setupCodexMcp(home, mode) {
     if (!hasManagedBlock(existing, CODEX_MCP_BEGIN, CODEX_MCP_END)) {
       return { kind: "codex-mcp", agent: "codex", label: "Codex MCP config", path: shown, status: "missing" };
     }
-    await writeFile5(filePath, removeManagedBlock(existing, CODEX_MCP_BEGIN, CODEX_MCP_END), "utf8");
+    await writeFile4(filePath, removeManagedBlock(existing, CODEX_MCP_BEGIN, CODEX_MCP_END), "utf8");
     return { kind: "codex-mcp", agent: "codex", label: "Codex MCP config", path: shown, status: "removed" };
   }
   if (existing === desired) {
@@ -2088,8 +1938,8 @@ async function setupCodexMcp(home, mode) {
   if (mode === "dry-run") {
     return { kind: "codex-mcp", agent: "codex", label: "Codex MCP config", path: shown, status };
   }
-  await mkdir5(path13.dirname(filePath), { recursive: true });
-  await writeFile5(filePath, desired, "utf8");
+  await mkdir4(path11.dirname(filePath), { recursive: true });
+  await writeFile4(filePath, desired, "utf8");
   return { kind: "codex-mcp", agent: "codex", label: "Codex MCP config", path: shown, status };
 }
 async function setupGlobal(options = {}) {
@@ -2103,7 +1953,7 @@ async function setupGlobal(options = {}) {
   if (providerIds.includes("codex")) {
     entries.push(await setupCodexAgents(home, mode));
     if (options.mcp) {
-      entries.push(await setupCodexMcp(home, mode));
+      entries.push(await setupCodexMcp(home, mode, options.mcpEntry ?? { command: "threadroot", args: ["mcp"] }));
     }
   }
   return { entries };
@@ -2235,8 +2085,8 @@ function inputEnv(values) {
 }
 
 // src/core/tools/create.ts
-import { mkdir as mkdir6, writeFile as writeFile6 } from "fs/promises";
-import path14 from "path";
+import { mkdir as mkdir5, writeFile as writeFile5 } from "fs/promises";
+import path12 from "path";
 import { stringify as stringifyYaml3 } from "yaml";
 var ToolCreateError = class extends Error {
   constructor(message) {
@@ -2253,7 +2103,7 @@ function assertSafeName(name) {
   }
 }
 function assertSafeScript(script) {
-  if (path14.isAbsolute(script) || script.split(/[\\/]/).includes("..")) {
+  if (path12.isAbsolute(script) || script.split(/[\\/]/).includes("..")) {
     throw new ToolCreateError(`Script path must be inside the harness directory: ${script}`);
   }
 }
@@ -2282,9 +2132,9 @@ async function createTool(repoRoot, input2, options) {
     throw new ToolCreateError(`Invalid tool definition: ${detail}`);
   }
   const dir = scope === "project" ? projectObjectDir(repoRoot, "tools") : userObjectDir("tools", options.home);
-  const filePath = path14.join(dir, `${input2.name}.yaml`);
-  await mkdir6(dir, { recursive: true });
-  await writeFile6(filePath, stringifyYaml3(parsed.data), { encoding: "utf8", flag: options.force ? "w" : "wx" }).catch(
+  const filePath = path12.join(dir, `${input2.name}.yaml`);
+  await mkdir5(dir, { recursive: true });
+  await writeFile5(filePath, stringifyYaml3(parsed.data), { encoding: "utf8", flag: options.force ? "w" : "wx" }).catch(
     (error) => {
       if (error.code === "EEXIST") {
         throw new ToolCreateError(`Tool \`${input2.name}\` already exists at ${filePath}. Pass force to overwrite.`);
@@ -2297,7 +2147,7 @@ async function createTool(repoRoot, input2, options) {
 
 // src/core/tools/catalog.ts
 import { readFile as readFile7, stat as stat4 } from "fs/promises";
-import path15 from "path";
+import path13 from "path";
 var NAME_RE3 = /^[a-z0-9][a-z0-9-]*$/;
 var DESTRUCTIVE_RE = /\b(migrate|deploy|publish|release|prune|reset|destroy|drop|delete|rm|push|seed|wipe)\b/i;
 function looksDestructive(name, command) {
@@ -2316,13 +2166,13 @@ async function exists2(file) {
   }
 }
 async function detectPackageManager(repoRoot) {
-  if (await exists2(path15.join(repoRoot, "pnpm-lock.yaml"))) {
+  if (await exists2(path13.join(repoRoot, "pnpm-lock.yaml"))) {
     return "pnpm";
   }
-  if (await exists2(path15.join(repoRoot, "yarn.lock"))) {
+  if (await exists2(path13.join(repoRoot, "yarn.lock"))) {
     return "yarn";
   }
-  if (await exists2(path15.join(repoRoot, "bun.lockb"))) {
+  if (await exists2(path13.join(repoRoot, "bun.lockb"))) {
     return "bun";
   }
   return "npm";
@@ -2343,7 +2193,7 @@ function orderScripts(names) {
   });
 }
 async function fromPackageJson(repoRoot) {
-  const file = path15.join(repoRoot, "package.json");
+  const file = path13.join(repoRoot, "package.json");
   let raw;
   try {
     raw = await readFile7(file, "utf8");
@@ -2380,7 +2230,7 @@ async function fromPackageJson(repoRoot) {
 async function fromTargets(repoRoot, fileName, runner, source) {
   let raw;
   try {
-    raw = await readFile7(path15.join(repoRoot, fileName), "utf8");
+    raw = await readFile7(path13.join(repoRoot, fileName), "utf8");
   } catch {
     return [];
   }
@@ -2530,17 +2380,387 @@ async function checkToolHealth(repoRoot, tool) {
   if (!tool.manifest.healthcheck) {
     return { status: "skipped", tool: tool.name, message: "No healthcheck configured." };
   }
-  const result = await executeShell(tool.manifest.healthcheck.run, { cwd: repoRoot, timeoutMs: 3e4 });
-  const expected = tool.manifest.healthcheck.expectExitCode;
-  if (result.exitCode !== expected) {
-    return {
-      status: "error",
-      tool: tool.name,
-      message: `Healthcheck exited ${result.exitCode}; expected ${expected}.`,
-      result
-    };
+  const result = await executeShell(tool.manifest.healthcheck.run, { cwd: repoRoot, timeoutMs: 3e4 });
+  const expected = tool.manifest.healthcheck.expectExitCode;
+  if (result.exitCode !== expected) {
+    return {
+      status: "error",
+      tool: tool.name,
+      message: `Healthcheck exited ${result.exitCode}; expected ${expected}.`,
+      result
+    };
+  }
+  return { status: "ok", tool: tool.name, result };
+}
+
+// src/core/mcp-check.ts
+import { spawn as spawn2 } from "child_process";
+import { access, mkdtemp, readFile as readFile8, rm as rm2, writeFile as writeFile6 } from "fs/promises";
+import { constants, realpathSync } from "fs";
+import { homedir as homedir2, tmpdir } from "os";
+import path14 from "path";
+var REQUIRED_MCP_TOOLS = [
+  "context",
+  "skills_list",
+  "skills_get",
+  "tools_list",
+  "tools_check",
+  "tools_run",
+  "tools_create",
+  "tools_detect",
+  "connections_list",
+  "connections_check",
+  "memory_read",
+  "memory_append",
+  "status",
+  "doctor"
+];
+function codexConfigPath2(home = homedir2()) {
+  return path14.join(home, ".codex", "config.toml");
+}
+function mcpEntryForCurrentProcess() {
+  const scriptPath = currentScriptPath();
+  if (scriptPath && path14.basename(scriptPath) === "index.js" && scriptPath.includes(`${path14.sep}dist${path14.sep}`)) {
+    return { command: process.execPath, args: [scriptPath, "mcp"] };
+  }
+  return { command: "threadroot", args: ["mcp"] };
+}
+function currentScriptPath() {
+  const scriptPath = process.argv[1];
+  if (!scriptPath) {
+    return void 0;
+  }
+  try {
+    return realpathSync(scriptPath);
+  } catch {
+    return scriptPath;
+  }
+}
+async function readCodexThreadrootMcpEntry(home = homedir2()) {
+  let raw;
+  try {
+    raw = await readFile8(codexConfigPath2(home), "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return void 0;
+    }
+    throw error;
+  }
+  const table = raw.match(/(?:^|\n)\[mcp_servers\.threadroot\]\s*\n(?<body>[\s\S]*?)(?=\n\[|$)/);
+  if (!table?.groups?.body) {
+    return void 0;
+  }
+  const command = matchTomlString(table.groups.body, "command");
+  const args = matchTomlArray(table.groups.body, "args");
+  if (!command || !args) {
+    return void 0;
+  }
+  return { command, args };
+}
+function matchTomlString(body, key) {
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = body.match(new RegExp(`^${escaped}\\s*=\\s*"(?<value>(?:[^"\\\\]|\\\\.)*)"\\s*$`, "m"));
+  return match?.groups?.value?.replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+}
+function matchTomlArray(body, key) {
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = body.match(new RegExp(`^${escaped}\\s*=\\s*\\[(?<value>.*)\\]\\s*$`, "m"));
+  if (!match?.groups?.value) {
+    return void 0;
+  }
+  const values = [];
+  const pattern = /"((?:[^"\\]|\\.)*)"/g;
+  let value;
+  while (value = pattern.exec(match.groups.value)) {
+    values.push(value[1].replace(/\\"/g, '"').replace(/\\\\/g, "\\"));
+  }
+  return values;
+}
+async function commandExists2(command) {
+  if (path14.isAbsolute(command) || command.includes(path14.sep)) {
+    try {
+      await access(command, constants.X_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  const paths = (process.env.PATH ?? "").split(path14.delimiter).filter(Boolean);
+  for (const dir of paths) {
+    try {
+      await access(path14.join(dir, command), constants.X_OK);
+      return true;
+    } catch {
+    }
+  }
+  return false;
+}
+async function checkCodexMcp(input2) {
+  const configPath = codexConfigPath2(input2.home);
+  const entry = await readCodexThreadrootMcpEntry(input2.home);
+  if (!entry) {
+    return {
+      status: "warning",
+      configPath,
+      tools: [],
+      messages: ["No Codex Threadroot MCP config found."]
+    };
+  }
+  if (!await commandExists2(entry.command)) {
+    return {
+      status: "error",
+      configPath,
+      entry,
+      tools: [],
+      messages: [`MCP command is not executable or not on PATH: ${entry.command}`]
+    };
+  }
+  try {
+    const handshake = await runMcpHandshake(entry, input2.repoRoot, input2.timeoutMs ?? 4e3);
+    const toolNames = handshake.tools;
+    const missing = REQUIRED_MCP_TOOLS.filter((tool) => !toolNames.includes(tool));
+    if (missing.length > 0) {
+      return {
+        status: "error",
+        configPath,
+        entry,
+        serverInfo: handshake.serverInfo,
+        tools: toolNames,
+        messages: [`MCP server is missing required tool(s): ${missing.join(", ")}`]
+      };
+    }
+    return {
+      status: "ok",
+      configPath,
+      entry,
+      serverInfo: handshake.serverInfo,
+      tools: toolNames,
+      messages: ["MCP server initialized and returned the expected Threadroot tools."]
+    };
+  } catch (error) {
+    return {
+      status: "error",
+      configPath,
+      entry,
+      tools: [],
+      messages: [`MCP handshake failed: ${error instanceof Error ? error.message : String(error)}`]
+    };
+  }
+}
+function runMcpHandshake(entry, repoRoot, timeoutMs) {
+  if (process.platform !== "win32") {
+    return runOneShotMcpHandshake(entry, repoRoot, timeoutMs);
+  }
+  return new Promise((resolve, reject) => {
+    const child = spawn2(entry.command, entry.args, {
+      cwd: repoRoot,
+      stdio: ["pipe", "pipe", "pipe"],
+      env: process.env
+    });
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.kill();
+      resolve(result);
+    };
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.kill();
+      reject(error);
+    };
+    const timer = setTimeout(() => {
+      fail(new Error(`Timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    let stdout = "";
+    let stderr = "";
+    let initialized = false;
+    let serverInfo;
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+      const lines = stdout.split("\n");
+      stdout = lines.pop() ?? "";
+      for (const line of lines) {
+        if (!line.trim()) {
+          continue;
+        }
+        let message;
+        try {
+          message = JSON.parse(line);
+        } catch (error) {
+          fail(new Error(`Invalid JSON-RPC response: ${error instanceof Error ? error.message : String(error)}`));
+          return;
+        }
+        if (message.error) {
+          fail(new Error(message.error.message ?? "MCP server returned an error"));
+          return;
+        }
+        if (message.id === 1) {
+          initialized = true;
+          serverInfo = message.result?.serverInfo;
+          child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" })}
+`);
+          child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id: 2, method: "tools/list" })}
+`);
+        }
+        if (message.id === 2) {
+          finish({
+            serverInfo,
+            tools: (message.result?.tools ?? []).map((tool) => tool.name)
+          });
+        }
+      }
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", (error) => {
+      fail(error);
+    });
+    child.on("close", (code) => {
+      if (!settled && !initialized && code !== null) {
+        fail(new Error(`Server exited before initialize completed (exit ${code})${stderr ? `: ${stderr}` : ""}`));
+      }
+    });
+    child.stdin.write(
+      `${JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+          protocolVersion: "2024-11-05",
+          capabilities: {},
+          clientInfo: { name: "threadroot-check", version: "0.1.3" }
+        }
+      })}
+`
+    );
+  });
+}
+async function runOneShotMcpHandshake(entry, repoRoot, timeoutMs) {
+  const tempDir = await mkdtemp(path14.join(tmpdir(), "threadroot-mcp-check-"));
+  const inputPath = path14.join(tempDir, "input.jsonl");
+  const stdoutPath = path14.join(tempDir, "stdout.jsonl");
+  const stderrPath = path14.join(tempDir, "stderr.txt");
+  try {
+    await writeFile6(
+      inputPath,
+      [
+        JSON.stringify({
+          jsonrpc: "2.0",
+          id: 1,
+          method: "initialize",
+          params: {
+            protocolVersion: "2024-11-05",
+            capabilities: {},
+            clientInfo: { name: "threadroot-check", version: "0.1.3" }
+          }
+        }),
+        JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }),
+        JSON.stringify({ jsonrpc: "2.0", id: 2, method: "tools/list" }),
+        ""
+      ].join("\n"),
+      "utf8"
+    );
+    const commandLine = [
+      shellQuote3(entry.command),
+      ...entry.args.map(shellQuote3),
+      "<",
+      shellQuote3(inputPath),
+      ">",
+      shellQuote3(stdoutPath),
+      "2>",
+      shellQuote3(stderrPath)
+    ].join(" ");
+    await runShell(commandLine, repoRoot, timeoutMs);
+    const [stdout, stderr] = await Promise.all([readFile8(stdoutPath, "utf8"), readOptional(stderrPath)]);
+    if (stderr.trim()) {
+      throw new Error(stderr.trim());
+    }
+    return parseHandshakeOutput(stdout);
+  } finally {
+    await rm2(tempDir, { recursive: true, force: true });
+  }
+}
+function runShell(commandLine, repoRoot, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const child = spawn2("sh", ["-c", commandLine], {
+      cwd: repoRoot,
+      stdio: "ignore",
+      env: process.env
+    });
+    let settled = false;
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.kill();
+      reject(error);
+    };
+    const timer = setTimeout(() => fail(new Error(`Timed out after ${timeoutMs}ms`)), timeoutMs);
+    child.on("error", fail);
+    child.on("close", async (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(new Error(`Server exited with status ${code ?? "unknown"}`));
+    });
+  });
+}
+function parseHandshakeOutput(stdout) {
+  let initialized = false;
+  let serverInfo;
+  let tools2;
+  for (const line of stdout.split("\n")) {
+    if (!line.trim()) {
+      continue;
+    }
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch (error) {
+      throw new Error(`Invalid JSON-RPC response: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (message.error) {
+      throw new Error(message.error.message ?? "MCP server returned an error");
+    }
+    if (message.id === 1) {
+      initialized = true;
+      serverInfo = message.result?.serverInfo;
+    }
+    if (message.id === 2) {
+      tools2 = (message.result?.tools ?? []).map((tool) => tool.name);
+    }
+  }
+  if (!initialized) {
+    throw new Error("Server did not return an initialize response");
+  }
+  if (!tools2) {
+    throw new Error("Server did not return a tools/list response");
+  }
+  return { serverInfo, tools: tools2 };
+}
+async function readOptional(filePath) {
+  try {
+    return await readFile8(filePath, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return "";
+    }
+    throw error;
   }
-  return { status: "ok", tool: tool.name, result };
+}
+function shellQuote3(value) {
+  return `'${value.replace(/'/g, "'\\''")}'`;
 }
 
 // src/core/doctor.ts
@@ -2558,9 +2778,23 @@ async function exists3(filePath) {
 function finding2(severity, code, message, pathValue) {
   return pathValue ? { severity, code, message, path: pathValue } : { severity, code, message };
 }
-async function mcpConfigHints(repoRoot) {
+async function mcpConfigHints(repoRoot, home) {
+  const codexMcp = await checkCodexMcp({ repoRoot, home, timeoutMs: 2500 });
+  if (codexMcp.status === "ok") {
+    return [];
+  }
+  if (codexMcp.status === "error") {
+    return [
+      finding2(
+        "warning",
+        "codex_mcp_unhealthy",
+        `Codex Threadroot MCP is configured but failed verification: ${codexMcp.messages.join(" ")}`,
+        codexMcp.configPath
+      )
+    ];
+  }
   const configs = [".vscode/mcp.json", ".cursor/mcp.json", ".mcp.json"];
-  const present = await Promise.all(configs.map((config) => exists3(path16.join(repoRoot, config))));
+  const present = await Promise.all(configs.map((config) => exists3(path15.join(repoRoot, config))));
   if (present.some(Boolean)) {
     return [];
   }
@@ -2580,7 +2814,7 @@ async function globalSetupHints(home) {
     finding2(
       "info",
       "global_setup_missing",
-      "Codex global Threadroot setup was not detected. Run `threadroot setup --global --agent codex` for one-time machine setup."
+      "Codex global Threadroot setup was not detected. Run `threadroot bootstrap --yes --agent codex` for one-time machine setup."
     )
   ];
 }
@@ -2734,7 +2968,7 @@ async function doctor(repoRoot, options = {}) {
         )
       );
     }
-    const scriptsDir = path16.join(path16.dirname(skill.sourcePath), "scripts");
+    const scriptsDir = path15.join(path15.dirname(skill.sourcePath), "scripts");
     if (await exists3(scriptsDir)) {
       findings.push(
         finding2(
@@ -2747,7 +2981,7 @@ async function doctor(repoRoot, options = {}) {
     }
   }
   findings.push(...await globalSetupHints(options.home));
-  findings.push(...await mcpConfigHints(repoRoot));
+  findings.push(...await mcpConfigHints(repoRoot, options.home));
   return summarize(findings);
 }
 function summarize(findings) {
@@ -2757,38 +2991,12 @@ function summarize(findings) {
   return { ok: errors === 0, findings, summary: { errors, warnings, info } };
 }
 
-// src/commands/doctor.ts
-async function runDoctor(repoRoot) {
-  const report = await doctor(repoRoot);
-  const actionable = report.findings.filter((finding3) => finding3.severity !== "info");
-  const hints = report.findings.filter((finding3) => finding3.severity === "info");
-  if (actionable.length === 0) {
-    console.log("Threadroot doctor: clean");
-    for (const finding3 of hints) {
-      const suffix = finding3.path ? ` (${finding3.path})` : "";
-      console.log(`- hint ${finding3.code}: ${finding3.message}${suffix}`);
-    }
-    return;
-  }
-  console.log(
-    `Threadroot doctor: ${report.summary.errors} error(s), ${report.summary.warnings} warning(s)`
-  );
-  for (const finding3 of report.findings) {
-    const label = finding3.severity === "error" ? "error" : finding3.severity === "warning" ? "warning" : "hint";
-    const suffix = finding3.path ? ` (${finding3.path})` : "";
-    console.log(`- ${label} ${finding3.code}: ${finding3.message}${suffix}`);
-  }
-  if (!report.ok) {
-    process.exitCode = 1;
-  }
-}
-
 // src/core/expose.ts
-import { mkdir as mkdir7, readFile as readFile8, rm as rm2, stat as stat6, writeFile as writeFile7 } from "fs/promises";
-import path17 from "path";
+import { mkdir as mkdir6, readFile as readFile9, rm as rm3, stat as stat6, writeFile as writeFile7 } from "fs/promises";
+import path16 from "path";
 async function readMaybe2(filePath) {
   try {
-    return await readFile8(filePath, "utf8");
+    return await readFile9(filePath, "utf8");
   } catch (error) {
     if (error.code === "ENOENT") {
       return void 0;
@@ -2797,10 +3005,10 @@ async function readMaybe2(filePath) {
   }
 }
 function projectSkillPath(repoRoot, provider) {
-  return path17.join(repoRoot, provider.projectSkillDir, THREADROOT_SKILL_NAME, "SKILL.md");
+  return path16.join(repoRoot, provider.projectSkillDir, THREADROOT_SKILL_NAME, "SKILL.md");
 }
 function relSkillPath(provider) {
-  return path17.join(provider.projectSkillDir, THREADROOT_SKILL_NAME, "SKILL.md");
+  return path16.join(provider.projectSkillDir, THREADROOT_SKILL_NAME, "SKILL.md");
 }
 async function exposeOne(repoRoot, provider, mode, force) {
   const relativePath = relSkillPath(provider);
@@ -2832,7 +3040,7 @@ async function exposeOne(repoRoot, provider, mode, force) {
         message: "Existing skill is not Threadroot-managed."
       };
     }
-    await rm2(path17.dirname(absolutePath), { recursive: true, force: true });
+    await rm3(path16.dirname(absolutePath), { recursive: true, force: true });
     return { agent: provider.id, label: provider.label, path: relativePath, status: "removed" };
   }
   if (existing === desired) {
@@ -2851,7 +3059,7 @@ async function exposeOne(repoRoot, provider, mode, force) {
   if (mode === "dry-run") {
     return { agent: provider.id, label: provider.label, path: relativePath, status };
   }
-  await mkdir7(path17.dirname(absolutePath), { recursive: true });
+  await mkdir6(path16.dirname(absolutePath), { recursive: true });
   await writeFile7(absolutePath, desired, "utf8");
   return { agent: provider.id, label: provider.label, path: relativePath, status };
 }
@@ -2865,34 +3073,34 @@ async function exposeProject(repoRoot, options = {}) {
   return { entries };
 }
 
-// src/commands/expose.ts
-function modeFromOptions(options) {
-  if (options.undo) return "undo";
-  if (options.check) return "check";
-  if (options.dryRun) return "dry-run";
-  return "write";
-}
-async function runExpose(repoRoot, agent, options) {
-  const mode = modeFromOptions(options);
-  const result = await exposeProject(repoRoot, {
-    agents: agent,
-    mode,
-    force: options.force
-  });
-  const verb = mode === "dry-run" ? "Project exposure plan" : mode === "check" ? "Project exposure check" : mode === "undo" ? "Removed project exposure" : "Exposed Threadroot project skills";
-  console.log(`${verb}:`);
-  for (const entry of result.entries) {
-    const suffix = entry.message ? ` - ${entry.message}` : "";
-    console.log(`- ${entry.label}: ${entry.status} ${entry.path}${suffix}`);
-  }
-}
-
 // src/core/init/index.ts
-import { mkdir as mkdir9, stat as stat8, writeFile as writeFile8 } from "fs/promises";
+import { mkdir as mkdir9, stat as stat8, writeFile as writeFile9 } from "fs/promises";
 import path22 from "path";
 
+// src/core/compile/write.ts
+import { mkdir as mkdir7, writeFile as writeFile8 } from "fs/promises";
+import path17 from "path";
+async function writeCompiled(repoRoot, files) {
+  await Promise.all(
+    files.map(async (file) => {
+      const absolute = path17.join(repoRoot, file.path);
+      await mkdir7(path17.dirname(absolute), { recursive: true });
+      await writeFile8(absolute, file.content, "utf8");
+    })
+  );
+  return files.map((file) => file.path);
+}
+async function runCompile(repoRoot, options = {}) {
+  const resolved = options.harness ?? await resolveHarness(repoRoot, { home: options.home });
+  const harness = options.adapter ? { ...resolved, manifest: { ...resolved.manifest, adapters: [options.adapter] } } : resolved;
+  const files = await compile(repoRoot, harness);
+  const drift = await detectDrift(repoRoot, files);
+  const written = await writeCompiled(repoRoot, files);
+  return { written, drift };
+}
+
 // src/core/scan/package.ts
-import fs2 from "fs/promises";
+import fs from "fs/promises";
 import path18 from "path";
 
 // src/core/scan/rules.ts
@@ -2911,7 +3119,7 @@ var ignoredDirectories = /* @__PURE__ */ new Set([
 // src/core/scan/package.ts
 async function readJson(repoRoot, relativePath) {
   try {
-    return JSON.parse(await fs2.readFile(path18.join(repoRoot, relativePath), "utf8"));
+    return JSON.parse(await fs.readFile(path18.join(repoRoot, relativePath), "utf8"));
   } catch {
     return void 0;
   }
@@ -2941,7 +3149,7 @@ function inferProfile(files, packageJson) {
 }
 
 // src/core/scan/walk.ts
-import fs3 from "fs/promises";
+import fs2 from "fs/promises";
 import path19 from "path";
 function toPosix(relativePath) {
   return relativePath.split(path19.sep).join("/");
@@ -2949,7 +3157,7 @@ function toPosix(relativePath) {
 async function walkRepo(repoRoot, directory = repoRoot) {
   let entries;
   try {
-    entries = await fs3.readdir(directory, { withFileTypes: true });
+    entries = await fs2.readdir(directory, { withFileTypes: true });
   } catch {
     return [];
   }
@@ -2963,363 +3171,835 @@ async function walkRepo(repoRoot, directory = repoRoot) {
       }
       continue;
     }
-    if (entry.isFile()) {
-      files.push(relativePath);
+    if (entry.isFile()) {
+      files.push(relativePath);
+    }
+  }
+  return files;
+}
+
+// src/core/init/index.ts
+import { stringify as stringifyYaml4 } from "yaml";
+
+// src/core/init/builtins.ts
+import { cp, mkdir as mkdir8, readdir as readdir3, stat as stat7 } from "fs/promises";
+import path20 from "path";
+import { fileURLToPath } from "url";
+var DIST_DIR = path20.dirname(fileURLToPath(import.meta.url));
+var PACKAGE_ROOT_FROM_BUNDLE = path20.resolve(DIST_DIR, "..");
+var PACKAGE_ROOT_FROM_DIST = path20.resolve(DIST_DIR, "../../..");
+var PACKAGE_ROOT_FROM_SRC = path20.resolve(DIST_DIR, "../../../..");
+var SKILL_PACK_CANDIDATES = [
+  path20.join(PACKAGE_ROOT_FROM_BUNDLE, "skills"),
+  path20.join(PACKAGE_ROOT_FROM_DIST, "skills"),
+  path20.join(PACKAGE_ROOT_FROM_SRC, "skills")
+];
+var PROJECT_MEMORY_TEMPLATE = [
+  "# Project",
+  "",
+  "<!-- Stable, rarely-changing facts about this project. Keep it short. -->",
+  "",
+  "- What it is:",
+  "- Key technologies:",
+  "- How to run it:"
+].join("\n");
+async function exists4(target) {
+  try {
+    const info = await stat7(target);
+    return info.isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function bundledSkillsDir() {
+  for (const candidate of SKILL_PACK_CANDIDATES) {
+    if (await exists4(candidate)) {
+      return candidate;
+    }
+  }
+  throw new Error("Bundled Threadroot skills were not found in this package.");
+}
+async function writeBuiltinSkills(repoRoot) {
+  const sourceDir = await bundledSkillsDir();
+  const targetDir = projectObjectDir(repoRoot, "skills");
+  await mkdir8(targetDir, { recursive: true });
+  const written = [];
+  const entries = await readdir3(sourceDir, { withFileTypes: true });
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const sourceSkill = path20.join(sourceDir, entry.name);
+    const sourceSkillFile = path20.join(sourceSkill, "SKILL.md");
+    if (!await exists4(sourceSkill) || !await stat7(sourceSkillFile).then((info) => info.isFile()).catch(() => false)) {
+      continue;
+    }
+    const targetSkill = path20.join(targetDir, entry.name);
+    const targetSkillFile = path20.join(targetSkill, "SKILL.md");
+    try {
+      await cp(sourceSkill, targetSkill, { recursive: true, force: false, errorOnExist: true });
+      written.push(targetSkillFile);
+    } catch (error) {
+      if (error.code !== "ERR_FS_CP_EEXIST" && error.code !== "EEXIST") {
+        throw error;
+      }
+    }
+  }
+  return written;
+}
+
+// src/core/init/import.ts
+import { readFile as readFile10, readdir as readdir4 } from "fs/promises";
+import path21 from "path";
+var PROSE_PRECEDENCE = ["AGENTS.md", "CLAUDE.md", ".github/copilot-instructions.md"];
+var CURSOR_RULES_DIR = ".cursor/rules";
+var NAME_RE4 = /^[a-z0-9][a-z0-9-]*$/;
+async function readIfExists2(filePath) {
+  try {
+    return await readFile10(filePath, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return void 0;
+    }
+    throw error;
+  }
+}
+function normalize(text) {
+  return text.toLowerCase().replace(/\s+/g, " ").trim();
+}
+function splitSections(markdown) {
+  const sections = [];
+  let heading = "";
+  let buffer = [];
+  const flush = () => {
+    const text = buffer.join("\n").trim();
+    if (text) {
+      sections.push({ heading, text });
+    }
+  };
+  for (const line of markdown.split(/\r?\n/)) {
+    if (/^#{1,6}\s/.test(line)) {
+      flush();
+      heading = normalize(line.replace(/^#+\s*/, ""));
+      buffer = [line];
+    } else {
+      buffer.push(line);
+    }
+  }
+  flush();
+  return sections;
+}
+function novelSections(canonical, other) {
+  const haystack = normalize(canonical);
+  const seenHeadings = new Set(splitSections(canonical).map((section) => section.heading).filter(Boolean));
+  return splitSections(other).filter((section) => {
+    if (section.heading && seenHeadings.has(section.heading)) {
+      return false;
+    }
+    return !haystack.includes(normalize(section.text));
+  });
+}
+async function listCursorRules(repoRoot) {
+  const dir = path21.join(repoRoot, CURSOR_RULES_DIR);
+  let entries;
+  try {
+    entries = await readdir4(dir);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+  const files = entries.filter((name) => name.endsWith(".mdc")).sort();
+  return Promise.all(
+    files.map(async (name) => ({
+      file: `${CURSOR_RULES_DIR}/${name}`,
+      content: await readFile10(path21.join(dir, name), "utf8")
+    }))
+  );
+}
+function globsToApplyTo(value) {
+  if (typeof value === "string") {
+    const first = value.split(",")[0]?.trim();
+    return first || void 0;
+  }
+  if (Array.isArray(value) && value.length > 0 && typeof value[0] === "string") {
+    return value[0].trim() || void 0;
+  }
+  return void 0;
+}
+function ruleName(fileName) {
+  const base = path21.basename(fileName, ".mdc").toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+  return NAME_RE4.test(base) ? base : "imported-rule";
+}
+async function importVendorFiles(repoRoot, options = {}) {
+  const include = options.include ? new Set(options.include) : void 0;
+  const wanted = (file) => !include || include.has(file);
+  const prose = [];
+  for (const file of PROSE_PRECEDENCE) {
+    if (!wanted(file)) {
+      continue;
+    }
+    const content = await readIfExists2(path21.join(repoRoot, file));
+    if (content && content.trim()) {
+      prose.push({ file, content });
     }
   }
-  return files;
+  const cursorRules = (await listCursorRules(repoRoot)).filter((rule) => wanted(rule.file));
+  let canonicalSource;
+  let canonicalBody = "";
+  let rest = [];
+  if (prose.length > 0) {
+    canonicalSource = prose[0].file;
+    canonicalBody = extractHandAuthored(prose[0].content);
+    rest = prose.slice(1);
+  } else if (cursorRules.length > 0) {
+    canonicalSource = CURSOR_RULES_DIR;
+    canonicalBody = cursorRules.map((rule) => parseFrontmatter(rule.content).body).join("\n\n").trim();
+  }
+  const foldedFrom = [];
+  const skippedDuplicates = [];
+  let body = canonicalBody;
+  for (const file of rest) {
+    const hand = extractHandAuthored(file.content);
+    const novel = novelSections(body, hand);
+    if (novel.length === 0) {
+      skippedDuplicates.push(file.file);
+      continue;
+    }
+    body = `${body}
+
+<!-- imported from ${file.file} -->
+${novel.map((section) => section.text).join("\n\n")}`.trim();
+    foldedFrom.push(file.file);
+  }
+  const importedRules = cursorRules.map((rule) => {
+    const { data, body: ruleBody2 } = parseFrontmatter(rule.content);
+    return {
+      name: ruleName(rule.file),
+      applyTo: globsToApplyTo(data.globs ?? data.applyTo),
+      body: ruleBody2.trim()
+    };
+  });
+  return { canonicalSource, canonicalBody: body, foldedFrom, importedRules, skippedDuplicates };
 }
 
 // src/core/init/index.ts
-import { stringify as stringifyYaml4 } from "yaml";
-
-// src/core/init/builtins.ts
-import { cp, mkdir as mkdir8, readdir as readdir3, stat as stat7 } from "fs/promises";
-import path20 from "path";
-import { fileURLToPath } from "url";
-var DIST_DIR = path20.dirname(fileURLToPath(import.meta.url));
-var PACKAGE_ROOT_FROM_BUNDLE = path20.resolve(DIST_DIR, "..");
-var PACKAGE_ROOT_FROM_DIST = path20.resolve(DIST_DIR, "../../..");
-var PACKAGE_ROOT_FROM_SRC = path20.resolve(DIST_DIR, "../../../..");
-var SKILL_PACK_CANDIDATES = [
-  path20.join(PACKAGE_ROOT_FROM_BUNDLE, "skills"),
-  path20.join(PACKAGE_ROOT_FROM_DIST, "skills"),
-  path20.join(PACKAGE_ROOT_FROM_SRC, "skills")
-];
-var PROJECT_MEMORY_TEMPLATE = [
-  "# Project",
-  "",
-  "<!-- Stable, rarely-changing facts about this project. Keep it short. -->",
-  "",
-  "- What it is:",
-  "- Key technologies:",
-  "- How to run it:"
-].join("\n");
-async function exists4(target) {
+var DEFAULT_ADAPTERS = [];
+var AGENTS_FILE2 = "AGENTS.md";
+var InitError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InitError";
+  }
+};
+async function pathExists(target) {
   try {
-    const info = await stat7(target);
-    return info.isDirectory();
+    await stat8(target);
+    return true;
   } catch {
     return false;
   }
 }
-async function bundledSkillsDir() {
-  for (const candidate of SKILL_PACK_CANDIDATES) {
-    if (await exists4(candidate)) {
-      return candidate;
+async function detectProfile(repoRoot, override) {
+  if (override) {
+    return override;
+  }
+  const files = await walkRepo(repoRoot);
+  const packageJson = await readJson(repoRoot, "package.json");
+  const inferred = inferProfile(files, packageJson);
+  return inferred === "unknown" ? "empty" : inferred;
+}
+async function detectName(repoRoot) {
+  const packageJson = await readJson(repoRoot, "package.json");
+  if (packageJson && typeof packageJson.name === "string" && packageJson.name.trim()) {
+    return packageJson.name.trim();
+  }
+  return path22.basename(repoRoot);
+}
+async function writeManifest(repoRoot, manifest) {
+  const body = {
+    name: manifest.name,
+    version: manifest.version,
+    profile: manifest.profile,
+    adapters: manifest.adapters
+  };
+  if (manifest.tools.allow.length > 0) {
+    body.tools = { allow: manifest.tools.allow };
+  }
+  await mkdir9(projectHarnessDir(repoRoot), { recursive: true });
+  await writeFile9(projectManifestPath(repoRoot), stringifyYaml4(body), "utf8");
+}
+async function writeProjectMemory(repoRoot) {
+  const dir = projectObjectDir(repoRoot, "memory");
+  await mkdir9(dir, { recursive: true });
+  const filePath = path22.join(dir, "project.md");
+  try {
+    await writeFile9(filePath, `${PROJECT_MEMORY_TEMPLATE}
+`, { encoding: "utf8", flag: "wx" });
+    return [filePath];
+  } catch (error) {
+    if (error.code === "EEXIST") {
+      return [];
     }
+    throw error;
   }
-  throw new Error("Bundled Threadroot skills were not found in this package.");
 }
-async function writeBuiltinSkills(repoRoot) {
-  const sourceDir = await bundledSkillsDir();
-  const targetDir = projectObjectDir(repoRoot, "skills");
-  await mkdir8(targetDir, { recursive: true });
+async function writeImportedRules(repoRoot, report) {
+  if (report.importedRules.length === 0) {
+    return [];
+  }
+  const dir = projectObjectDir(repoRoot, "rules");
+  await mkdir9(dir, { recursive: true });
   const written = [];
-  const entries = await readdir3(sourceDir, { withFileTypes: true });
-  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
-    if (!entry.isDirectory()) {
-      continue;
-    }
-    const sourceSkill = path20.join(sourceDir, entry.name);
-    const sourceSkillFile = path20.join(sourceSkill, "SKILL.md");
-    if (!await exists4(sourceSkill) || !await stat7(sourceSkillFile).then((info) => info.isFile()).catch(() => false)) {
-      continue;
+  for (const rule of report.importedRules) {
+    const filePath = path22.join(dir, `${rule.name}.md`);
+    const data = { name: rule.name, scope: "project" };
+    if (rule.applyTo) {
+      data.applyTo = rule.applyTo;
     }
-    const targetSkill = path20.join(targetDir, entry.name);
-    const targetSkillFile = path20.join(targetSkill, "SKILL.md");
     try {
-      await cp(sourceSkill, targetSkill, { recursive: true, force: false, errorOnExist: true });
-      written.push(targetSkillFile);
+      await writeFile9(filePath, serializeFrontmatter(data, rule.body), { encoding: "utf8", flag: "wx" });
+      written.push(filePath);
     } catch (error) {
-      if (error.code !== "ERR_FS_CP_EEXIST" && error.code !== "EEXIST") {
+      if (error.code !== "EEXIST") {
         throw error;
       }
     }
   }
   return written;
 }
+async function writeStarterTools(repoRoot, profile, force) {
+  const candidates = await detectToolCandidates(repoRoot, profile);
+  const names = [];
+  for (const candidate of candidates) {
+    try {
+      await createTool(
+        repoRoot,
+        {
+          name: candidate.name,
+          description: candidate.description,
+          run: candidate.run,
+          risk: candidate.risk,
+          confirm: candidate.confirm
+        },
+        { actor: "human", force }
+      );
+      names.push(candidate.name);
+    } catch (error) {
+      if (error instanceof ToolCreateError) {
+        continue;
+      }
+      throw error;
+    }
+  }
+  return names;
+}
+async function initHarness(repoRoot, options = {}) {
+  if (!options.force && await pathExists(projectManifestPath(repoRoot))) {
+    throw new InitError(
+      `A harness already exists at ${path22.join(".threadroot", "harness.yaml")}. Re-run with --force to overwrite.`
+    );
+  }
+  const profile = await detectProfile(repoRoot, options.profile);
+  const name = await detectName(repoRoot);
+  const adapters = options.adapters ?? DEFAULT_ADAPTERS;
+  const tools2 = await writeStarterTools(repoRoot, profile, options.force ?? false);
+  const skills = await writeBuiltinSkills(repoRoot);
+  const memory = await writeProjectMemory(repoRoot);
+  const manifest = harnessManifestSchema.parse({
+    name,
+    version: 1,
+    profile,
+    adapters,
+    tools: { allow: tools2 }
+  });
+  await writeManifest(repoRoot, manifest);
+  let report;
+  let rules = [];
+  if (options.import !== false) {
+    report = await importVendorFiles(repoRoot, { include: options.importFiles });
+    if (report.canonicalBody.trim()) {
+      await writeFile9(path22.join(repoRoot, AGENTS_FILE2), `${report.canonicalBody.trim()}
+`, "utf8");
+    }
+    rules = await writeImportedRules(repoRoot, report);
+  }
+  const { written } = await runCompile(repoRoot, { home: options.home });
+  const exposed = options.expose ? (await exposeProject(repoRoot, { agents: options.expose })).entries.filter((entry) => entry.status !== "missing" && entry.status !== "skipped").map((entry) => entry.path) : [];
+  return { name, profile, adapters, skills, tools: tools2, memory, rules, import: report, compiled: written, exposed };
+}
+
+// src/core/status.ts
+async function harnessStatus(repoRoot, options = {}) {
+  let harness;
+  try {
+    harness = await resolveHarness(repoRoot, { home: options.home });
+  } catch (error) {
+    if (error instanceof HarnessError) {
+      return { exists: false };
+    }
+    throw error;
+  }
+  const files = await compile(repoRoot, harness);
+  const drift = await detectDrift(repoRoot, files);
+  return {
+    exists: true,
+    manifest: {
+      name: harness.manifest.name,
+      profile: harness.manifest.profile,
+      adapters: harness.manifest.adapters,
+      toolsAllow: harness.manifest.tools.allow
+    },
+    counts: {
+      skills: harness.skills.length,
+      rules: harness.rules.length,
+      tools: harness.tools.length,
+      memory: harness.memory.length
+    },
+    drift
+  };
+}
 
-// src/core/init/import.ts
-import { readFile as readFile9, readdir as readdir4 } from "fs/promises";
-import path21 from "path";
-var PROSE_PRECEDENCE = ["AGENTS.md", "CLAUDE.md", ".github/copilot-instructions.md"];
-var CURSOR_RULES_DIR = ".cursor/rules";
-var NAME_RE4 = /^[a-z0-9][a-z0-9-]*$/;
-async function readIfExists3(filePath) {
+// src/core/bootstrap.ts
+var DEFAULT_TASK = "start this project";
+async function harnessExists(repoRoot) {
+  return pathExists2(path23.join(repoRoot, ".threadroot", "harness.yaml"));
+}
+async function pathExists2(target) {
   try {
-    return await readFile9(filePath, "utf8");
+    await stat9(target);
+    return true;
   } catch (error) {
     if (error.code === "ENOENT") {
-      return void 0;
+      return false;
     }
     throw error;
   }
 }
-function normalize(text) {
-  return text.toLowerCase().replace(/\s+/g, " ").trim();
-}
-function splitSections(markdown) {
-  const sections = [];
-  let heading = "";
-  let buffer = [];
-  const flush = () => {
-    const text = buffer.join("\n").trim();
-    if (text) {
-      sections.push({ heading, text });
-    }
-  };
-  for (const line of markdown.split(/\r?\n/)) {
-    if (/^#{1,6}\s/.test(line)) {
-      flush();
-      heading = normalize(line.replace(/^#+\s*/, ""));
-      buffer = [line];
+function modeFor(options) {
+  return options.yes && !options.dryRun ? "write" : "dry-run";
+}
+async function bootstrapProject(repoRoot, options = {}) {
+  const task = options.task?.trim() || DEFAULT_TASK;
+  const mode = modeFor(options);
+  const write2 = mode === "write";
+  const notes = [];
+  const existed = await harnessExists(repoRoot);
+  let setup;
+  let init;
+  let exposed;
+  if (!options.noGlobal) {
+    setup = await setupGlobal({
+      agents: options.agents ?? "all",
+      mode,
+      home: options.home,
+      mcp: options.mcp,
+      mcpEntry: options.mcpEntry
+    });
+  } else {
+    notes.push("Skipped global setup because --no-global was set.");
+  }
+  if (!existed && !options.noInit) {
+    if (write2) {
+      init = await initHarness(repoRoot, {
+        import: options.import,
+        profile: options.profile,
+        home: options.home
+      });
     } else {
-      buffer.push(line);
+      notes.push(`Would initialize local-only harness at ${path23.join(".threadroot", "harness.yaml")}.`);
     }
+  } else if (existed) {
+    notes.push("Existing harness detected; bootstrap will not reinitialize it.");
+  } else {
+    notes.push("Skipped project initialization because --no-init was set.");
   }
-  flush();
-  return sections;
-}
-function novelSections(canonical, other) {
-  const haystack = normalize(canonical);
-  const seenHeadings = new Set(splitSections(canonical).map((section) => section.heading).filter(Boolean));
-  return splitSections(other).filter((section) => {
-    if (section.heading && seenHeadings.has(section.heading)) {
-      return false;
+  const hasHarnessAfterInit = existed || Boolean(init) || await pathExists2(path23.join(repoRoot, ".threadroot", "harness.yaml"));
+  if (options.expose) {
+    exposed = await exposeProject(repoRoot, {
+      agents: options.expose,
+      mode
+    });
+  }
+  let status;
+  let doctorReport;
+  let context;
+  let mcpCheck;
+  if (options.mcp && write2) {
+    mcpCheck = await checkCodexMcp({ repoRoot, home: options.home });
+  }
+  if (hasHarnessAfterInit) {
+    status = await harnessStatus(repoRoot, { home: options.home });
+    doctorReport = await doctor(repoRoot, { home: options.home });
+    if (status.exists) {
+      context = await assembleContext(repoRoot, task, { home: options.home, fallbackSkills: true });
     }
-    return !haystack.includes(normalize(section.text));
-  });
+  } else {
+    notes.push("Skipped doctor/status/context because no harness exists yet.");
+  }
+  if (!write2) {
+    notes.push("Run `threadroot bootstrap --yes` to apply this plan.");
+  }
+  return {
+    mode: write2 ? "write" : "plan",
+    task,
+    harnessExisted: existed,
+    setup,
+    init,
+    expose: exposed,
+    status,
+    doctor: doctorReport,
+    context,
+    mcpCheck,
+    notes
+  };
 }
-async function listCursorRules(repoRoot) {
-  const dir = path21.join(repoRoot, CURSOR_RULES_DIR);
-  let entries;
-  try {
-    entries = await readdir4(dir);
-  } catch (error) {
-    if (error.code === "ENOENT") {
-      return [];
-    }
-    throw error;
+async function startSession(repoRoot, options = {}) {
+  const task = options.task?.trim() || DEFAULT_TASK;
+  const status = await harnessStatus(repoRoot, { home: options.home });
+  const notes = [];
+  if (!status.exists) {
+    return {
+      task,
+      status,
+      notes: ["No harness found. Run `threadroot bootstrap --yes` first."]
+    };
   }
-  const files = entries.filter((name) => name.endsWith(".mdc")).sort();
-  return Promise.all(
-    files.map(async (name) => ({
-      file: `${CURSOR_RULES_DIR}/${name}`,
-      content: await readFile9(path21.join(dir, name), "utf8")
-    }))
-  );
+  const doctorReport = await doctor(repoRoot, { home: options.home });
+  const context = await assembleContext(repoRoot, task, { home: options.home, fallbackSkills: true });
+  return { task, status, doctor: doctorReport, context, notes };
 }
-function globsToApplyTo(value) {
-  if (typeof value === "string") {
-    const first = value.split(",")[0]?.trim();
-    return first || void 0;
+
+// src/commands/session-output.ts
+function printDoctor(report) {
+  if (!report) {
+    return;
   }
-  if (Array.isArray(value) && value.length > 0 && typeof value[0] === "string") {
-    return value[0].trim() || void 0;
+  const actionable = report.findings.filter((finding3) => finding3.severity !== "info");
+  console.log(actionable.length === 0 ? "doctor: clean" : `doctor: ${report.summary.errors} error(s), ${report.summary.warnings} warning(s)`);
+  for (const finding3 of report.findings.slice(0, 8)) {
+    const label = finding3.severity === "info" ? "hint" : finding3.severity;
+    const suffix = finding3.path ? ` (${finding3.path})` : "";
+    console.log(`- ${label} ${finding3.code}: ${finding3.message}${suffix}`);
+  }
+  if (report.findings.length > 8) {
+    console.log(`- ... ${report.findings.length - 8} more finding(s)`);
   }
-  return void 0;
 }
-function ruleName(fileName) {
-  const base = path21.basename(fileName, ".mdc").toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
-  return NAME_RE4.test(base) ? base : "imported-rule";
+function printStatus(status) {
+  if (!status) {
+    return;
+  }
+  if (!status.exists) {
+    console.log("harness: missing");
+    return;
+  }
+  console.log(`harness: ${status.manifest.name} (${status.manifest.profile})`);
+  console.log(`adapters: ${status.manifest.adapters.length > 0 ? status.manifest.adapters.join(", ") : "none (local-only)"}`);
+  console.log(
+    `objects: ${status.counts.skills} skills, ${status.counts.rules} rules, ${status.counts.tools} tools, ${status.counts.memory} memory`
+  );
 }
-async function importVendorFiles(repoRoot, options = {}) {
-  const include = options.include ? new Set(options.include) : void 0;
-  const wanted = (file) => !include || include.has(file);
-  const prose = [];
-  for (const file of PROSE_PRECEDENCE) {
-    if (!wanted(file)) {
-      continue;
+function printContext(context) {
+  if (!context) {
+    return;
+  }
+  console.log(`task: ${context.task}`);
+  if (context.skills.length > 0) {
+    const skillLabel = context.skills.some((skill) => skill.score > 0) ? "relevant skills:" : "starter skills:";
+    console.log(skillLabel);
+    for (const skill of context.skills.slice(0, 8)) {
+      console.log(`- ${skill.name} - ${skill.when}`);
     }
-    const content = await readIfExists3(path21.join(repoRoot, file));
-    if (content && content.trim()) {
-      prose.push({ file, content });
+  } else {
+    console.log("relevant skills: none matched; run `threadroot skills list` to inspect all skills.");
+  }
+  if (context.tools.length > 0) {
+    console.log("available tools:");
+    for (const tool of context.tools.slice(0, 8)) {
+      console.log(`- ${tool.name} (${tool.risk}) - ${tool.description}`);
     }
   }
-  const cursorRules = (await listCursorRules(repoRoot)).filter((rule) => wanted(rule.file));
-  let canonicalSource;
-  let canonicalBody = "";
-  let rest = [];
-  if (prose.length > 0) {
-    canonicalSource = prose[0].file;
-    canonicalBody = extractHandAuthored(prose[0].content);
-    rest = prose.slice(1);
-  } else if (cursorRules.length > 0) {
-    canonicalSource = CURSOR_RULES_DIR;
-    canonicalBody = cursorRules.map((rule) => parseFrontmatter(rule.content).body).join("\n\n").trim();
+  if (context.memory.length > 0) {
+    console.log(`memory: ${context.memory.map((entry) => entry.type).join(", ")}`);
   }
-  const foldedFrom = [];
-  const skippedDuplicates = [];
-  let body = canonicalBody;
-  for (const file of rest) {
-    const hand = extractHandAuthored(file.content);
-    const novel = novelSections(body, hand);
-    if (novel.length === 0) {
-      skippedDuplicates.push(file.file);
-      continue;
+}
+function printCommandMap() {
+  console.log("agent command map:");
+  console.log('- `threadroot start "<task>"` - begin a focused agent session');
+  console.log('- `threadroot context "<task>"` - get relevant skills, tools, rules, and memory');
+  console.log("- `threadroot doctor` - check harness health and trust issues");
+  console.log("- `threadroot skills list|inspect|validate` - inspect skill capabilities");
+  console.log("- `threadroot tools list|check` and `threadroot run <tool>` - use explicit local tools");
+  console.log('- `threadroot remember "<note>"` - save durable handoff/project memory');
+}
+function printMcpCheck(report) {
+  if (!report) {
+    return;
+  }
+  console.log(`mcp check: ${report.status}`);
+  if (report.entry) {
+    console.log(`mcp server: ${report.entry.command} ${report.entry.args.join(" ")}`.trim());
+  }
+  for (const message of report.messages) {
+    console.log(`- ${message}`);
+  }
+}
+function printBootstrapReport(report) {
+  console.log(`Threadroot bootstrap: ${report.mode === "write" ? "complete" : "plan"}`);
+  if (report.setup) {
+    console.log("global setup:");
+    for (const entry of report.setup.entries) {
+      const suffix = entry.message ? ` - ${entry.message}` : "";
+      console.log(`- ${entry.label}: ${entry.status} ${entry.path}${suffix}`);
     }
-    body = `${body}
-
-<!-- imported from ${file.file} -->
-${novel.map((section) => section.text).join("\n\n")}`.trim();
-    foldedFrom.push(file.file);
   }
-  const importedRules = cursorRules.map((rule) => {
-    const { data, body: ruleBody2 } = parseFrontmatter(rule.content);
-    return {
-      name: ruleName(rule.file),
-      applyTo: globsToApplyTo(data.globs ?? data.applyTo),
-      body: ruleBody2.trim()
-    };
+  if (report.init) {
+    console.log("project init: created local-only .threadroot/");
+  } else if (report.harnessExisted) {
+    console.log("project init: existing harness preserved");
+  }
+  if (report.expose) {
+    console.log("project exposure:");
+    for (const entry of report.expose.entries) {
+      const suffix = entry.message ? ` - ${entry.message}` : "";
+      console.log(`- ${entry.label}: ${entry.status} ${entry.path}${suffix}`);
+    }
+  }
+  printStatus(report.status);
+  printMcpCheck(report.mcpCheck);
+  printDoctor(report.doctor);
+  printContext(report.context);
+  printCommandMap();
+  for (const note of report.notes) {
+    console.log(`note: ${note}`);
+  }
+  if (report.mode === "write") {
+    console.log('Success: Threadroot is ready. Run `threadroot start "<task>"` for future sessions.');
+  }
+}
+function printStartReport(report) {
+  console.log("Threadroot start:");
+  printStatus(report.status);
+  printDoctor(report.doctor);
+  printContext(report.context);
+  printCommandMap();
+  for (const note of report.notes) {
+    console.log(`note: ${note}`);
+  }
+}
+
+// src/commands/bootstrap.ts
+async function runBootstrap(repoRoot, options) {
+  const report = await bootstrapProject(repoRoot, {
+    yes: options.yes,
+    dryRun: options.dryRun,
+    agents: options.agent,
+    task: options.task,
+    mcp: options.mcp,
+    expose: options.expose,
+    noGlobal: options.global === false,
+    noInit: options.init === false,
+    import: options.import,
+    profile: options.profile ? profileIdSchema.parse(options.profile) : void 0,
+    mcpEntry: options.mcp ? mcpEntryForCurrentProcess() : void 0
   });
-  return { canonicalSource, canonicalBody: body, foldedFrom, importedRules, skippedDuplicates };
+  printBootstrapReport(report);
+  if (report.mode === "write" && report.doctor && !report.doctor.ok) {
+    process.exitCode = 1;
+  }
 }
 
-// src/core/init/index.ts
-var DEFAULT_ADAPTERS = [];
-var AGENTS_FILE2 = "AGENTS.md";
-var InitError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "InitError";
+// src/commands/compile.ts
+async function runCompileCommand(repoRoot, options) {
+  const adapter = options.adapter ? adapterIdSchema.parse(options.adapter) : void 0;
+  try {
+    const { written, drift } = await runCompile(repoRoot, { adapter });
+    const changed = drift.filter((entry) => entry.status !== "unchanged").length;
+    console.log(`Compiled ${written.length} vendor file(s)${changed > 0 ? ` (${changed} changed)` : ""}.`);
+    for (const file of written) {
+      console.log(`  ${file}`);
+    }
+  } catch (error) {
+    if (error instanceof HarnessError) {
+      console.error(error.message);
+      process.exitCode = 1;
+      return;
+    }
+    throw error;
   }
-};
-async function pathExists(target) {
+}
+
+// src/commands/context.ts
+async function runContext(repoRoot, task) {
+  let context;
   try {
-    await stat8(target);
-    return true;
-  } catch {
-    return false;
+    context = await assembleContext(repoRoot, task);
+  } catch (error) {
+    if (error instanceof HarnessError) {
+      console.log("No harness found. Run `tr init` first.");
+      return;
+    }
+    throw error;
+  }
+  console.log(`task: ${context.task}`);
+  if (context.skills.length > 0) {
+    console.log("\nskills:");
+    for (const skill of context.skills) {
+      console.log(`- ${skill.name} - ${skill.when}`);
+    }
+  }
+  if (context.rules.length > 0) {
+    console.log("\nrules:");
+    for (const rule of context.rules) {
+      console.log(`- ${rule.name}${rule.applyTo ? ` (${rule.applyTo})` : ""}`);
+    }
+  }
+  if (context.tools.length > 0) {
+    console.log("\ntools:");
+    for (const tool of context.tools) {
+      console.log(`- ${tool.name} - ${tool.description}`);
+    }
+  }
+  if (context.memory.length > 0) {
+    console.log("\nmemory:");
+    for (const entry of context.memory) {
+      console.log(`- ${entry.type}`);
+    }
+  }
+  if (context.skills.length === 0 && context.rules.length === 0 && context.tools.length === 0 && context.memory.length === 0) {
+    console.log("\nNo matching harness context for this task yet.");
   }
 }
-async function detectProfile(repoRoot, override) {
-  if (override) {
-    return override;
+
+// src/commands/diff.ts
+import fs3 from "fs/promises";
+import path24 from "path";
+async function readIfExists3(filePath) {
+  try {
+    return await fs3.readFile(filePath, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return void 0;
+    }
+    throw error;
   }
-  const files = await walkRepo(repoRoot);
-  const packageJson = await readJson(repoRoot, "package.json");
-  const inferred = inferProfile(files, packageJson);
-  return inferred === "unknown" ? "empty" : inferred;
 }
-async function detectName(repoRoot) {
-  const packageJson = await readJson(repoRoot, "package.json");
-  if (packageJson && typeof packageJson.name === "string" && packageJson.name.trim()) {
-    return packageJson.name.trim();
+function lineDiff(before, after) {
+  const a = before.length === 0 ? [] : before.split("\n");
+  const b = after.length === 0 ? [] : after.split("\n");
+  const lcs = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+  for (let i2 = a.length - 1; i2 >= 0; i2 -= 1) {
+    for (let j2 = b.length - 1; j2 >= 0; j2 -= 1) {
+      lcs[i2][j2] = a[i2] === b[j2] ? lcs[i2 + 1][j2 + 1] + 1 : Math.max(lcs[i2 + 1][j2], lcs[i2][j2 + 1]);
+    }
   }
-  return path22.basename(repoRoot);
-}
-async function writeManifest(repoRoot, manifest) {
-  const body = {
-    name: manifest.name,
-    version: manifest.version,
-    profile: manifest.profile,
-    adapters: manifest.adapters
-  };
-  if (manifest.tools.allow.length > 0) {
-    body.tools = { allow: manifest.tools.allow };
+  const lines = [];
+  let i = 0;
+  let j = 0;
+  while (i < a.length && j < b.length) {
+    if (a[i] === b[j]) {
+      i += 1;
+      j += 1;
+    } else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+      lines.push(`- ${a[i]}`);
+      i += 1;
+    } else {
+      lines.push(`+ ${b[j]}`);
+      j += 1;
+    }
   }
-  await mkdir9(projectHarnessDir(repoRoot), { recursive: true });
-  await writeFile8(projectManifestPath(repoRoot), stringifyYaml4(body), "utf8");
+  while (i < a.length) {
+    lines.push(`- ${a[i]}`);
+    i += 1;
+  }
+  while (j < b.length) {
+    lines.push(`+ ${b[j]}`);
+    j += 1;
+  }
+  return lines;
 }
-async function writeProjectMemory(repoRoot) {
-  const dir = projectObjectDir(repoRoot, "memory");
-  await mkdir9(dir, { recursive: true });
-  const filePath = path22.join(dir, "project.md");
+async function runDiff(repoRoot) {
+  let harness;
   try {
-    await writeFile8(filePath, `${PROJECT_MEMORY_TEMPLATE}
-`, { encoding: "utf8", flag: "wx" });
-    return [filePath];
+    harness = await resolveHarness(repoRoot);
   } catch (error) {
-    if (error.code === "EEXIST") {
-      return [];
+    if (error instanceof HarnessError) {
+      console.log("No harness found. Run `tr init` first.");
+      return;
     }
     throw error;
   }
-}
-async function writeImportedRules(repoRoot, report) {
-  if (report.importedRules.length === 0) {
-    return [];
-  }
-  const dir = projectObjectDir(repoRoot, "rules");
-  await mkdir9(dir, { recursive: true });
-  const written = [];
-  for (const rule of report.importedRules) {
-    const filePath = path22.join(dir, `${rule.name}.md`);
-    const data = { name: rule.name, scope: "project" };
-    if (rule.applyTo) {
-      data.applyTo = rule.applyTo;
+  const files = await compile(repoRoot, harness);
+  let changed = 0;
+  for (const file of files) {
+    const existing = await readIfExists3(path24.join(repoRoot, file.path));
+    if (existing === void 0) {
+      changed += 1;
+      console.log(`+ ${file.path} (new)`);
+      continue;
     }
-    try {
-      await writeFile8(filePath, serializeFrontmatter(data, rule.body), { encoding: "utf8", flag: "wx" });
-      written.push(filePath);
-    } catch (error) {
-      if (error.code !== "EEXIST") {
-        throw error;
-      }
+    if (existing === file.content) {
+      continue;
+    }
+    changed += 1;
+    console.log(`~ ${file.path}`);
+    for (const line of lineDiff(existing, file.content)) {
+      console.log(`    ${line}`);
     }
   }
-  return written;
+  if (changed === 0) {
+    console.log("No drift: optional compiled outputs match the canonical harness.");
+  }
 }
-async function writeStarterTools(repoRoot, profile, force) {
-  const candidates = await detectToolCandidates(repoRoot, profile);
-  const names = [];
-  for (const candidate of candidates) {
-    try {
-      await createTool(
-        repoRoot,
-        {
-          name: candidate.name,
-          description: candidate.description,
-          run: candidate.run,
-          risk: candidate.risk,
-          confirm: candidate.confirm
-        },
-        { actor: "human", force }
-      );
-      names.push(candidate.name);
-    } catch (error) {
-      if (error instanceof ToolCreateError) {
-        continue;
-      }
-      throw error;
+
+// src/commands/doctor.ts
+async function runDoctor(repoRoot) {
+  const report = await doctor(repoRoot);
+  const actionable = report.findings.filter((finding3) => finding3.severity !== "info");
+  const hints = report.findings.filter((finding3) => finding3.severity === "info");
+  if (actionable.length === 0) {
+    console.log("Threadroot doctor: clean");
+    for (const finding3 of hints) {
+      const suffix = finding3.path ? ` (${finding3.path})` : "";
+      console.log(`- hint ${finding3.code}: ${finding3.message}${suffix}`);
     }
+    return;
   }
-  return names;
-}
-async function initHarness(repoRoot, options = {}) {
-  if (!options.force && await pathExists(projectManifestPath(repoRoot))) {
-    throw new InitError(
-      `A harness already exists at ${path22.join(".threadroot", "harness.yaml")}. Re-run with --force to overwrite.`
-    );
+  console.log(
+    `Threadroot doctor: ${report.summary.errors} error(s), ${report.summary.warnings} warning(s)`
+  );
+  for (const finding3 of report.findings) {
+    const label = finding3.severity === "error" ? "error" : finding3.severity === "warning" ? "warning" : "hint";
+    const suffix = finding3.path ? ` (${finding3.path})` : "";
+    console.log(`- ${label} ${finding3.code}: ${finding3.message}${suffix}`);
   }
-  const profile = await detectProfile(repoRoot, options.profile);
-  const name = await detectName(repoRoot);
-  const adapters = options.adapters ?? DEFAULT_ADAPTERS;
-  const tools2 = await writeStarterTools(repoRoot, profile, options.force ?? false);
-  const skills = await writeBuiltinSkills(repoRoot);
-  const memory = await writeProjectMemory(repoRoot);
-  const manifest = harnessManifestSchema.parse({
-    name,
-    version: 1,
-    profile,
-    adapters,
-    tools: { allow: tools2 }
+  if (!report.ok) {
+    process.exitCode = 1;
+  }
+}
+
+// src/commands/expose.ts
+function modeFromOptions(options) {
+  if (options.undo) return "undo";
+  if (options.check) return "check";
+  if (options.dryRun) return "dry-run";
+  return "write";
+}
+async function runExpose(repoRoot, agent, options) {
+  const mode = modeFromOptions(options);
+  const result = await exposeProject(repoRoot, {
+    agents: agent,
+    mode,
+    force: options.force
   });
-  await writeManifest(repoRoot, manifest);
-  let report;
-  let rules = [];
-  if (options.import !== false) {
-    report = await importVendorFiles(repoRoot, { include: options.importFiles });
-    if (report.canonicalBody.trim()) {
-      await writeFile8(path22.join(repoRoot, AGENTS_FILE2), `${report.canonicalBody.trim()}
-`, "utf8");
-    }
-    rules = await writeImportedRules(repoRoot, report);
+  const verb = mode === "dry-run" ? "Project exposure plan" : mode === "check" ? "Project exposure check" : mode === "undo" ? "Removed project exposure" : "Exposed Threadroot project skills";
+  console.log(`${verb}:`);
+  for (const entry of result.entries) {
+    const suffix = entry.message ? ` - ${entry.message}` : "";
+    console.log(`- ${entry.label}: ${entry.status} ${entry.path}${suffix}`);
   }
-  const { written } = await runCompile(repoRoot, { home: options.home });
-  const exposed = options.expose ? (await exposeProject(repoRoot, { agents: options.expose })).entries.filter((entry) => entry.status !== "missing" && entry.status !== "skipped").map((entry) => entry.path) : [];
-  return { name, profile, adapters, skills, tools: tools2, memory, rules, import: report, compiled: written, exposed };
 }
 
 // src/commands/init.ts
@@ -3369,13 +4049,13 @@ async function runInit(repoRoot, options) {
 }
 
 // src/commands/install.ts
-import path25 from "path";
+import path27 from "path";
 
 // src/core/install/fetch.ts
 import { execFile } from "child_process";
-import { mkdtemp, rm as rm3 } from "fs/promises";
+import { mkdtemp as mkdtemp2, rm as rm4 } from "fs/promises";
 import os2 from "os";
-import path23 from "path";
+import path25 from "path";
 import { promisify } from "util";
 var run = promisify(execFile);
 function cloneUrl(ref) {
@@ -3396,8 +4076,8 @@ async function git(cwd, args) {
 }
 async function fetchGitSource(ref) {
   const url = cloneUrl(ref);
-  const dir = await mkdtemp(path23.join(os2.tmpdir(), "threadroot-fetch-"));
-  const cleanup = () => rm3(dir, { recursive: true, force: true });
+  const dir = await mkdtemp2(path25.join(os2.tmpdir(), "threadroot-fetch-"));
+  const cleanup = () => rm4(dir, { recursive: true, force: true });
   try {
     if (ref.ref) {
       try {
@@ -3418,9 +4098,9 @@ async function fetchGitSource(ref) {
 }
 
 // src/core/install/install.ts
-import { cp as cp2, mkdir as mkdir10, readFile as readFile10, readdir as readdir5, stat as stat9, writeFile as writeFile9 } from "fs/promises";
+import { cp as cp2, mkdir as mkdir10, readFile as readFile11, readdir as readdir5, stat as stat10, writeFile as writeFile10 } from "fs/promises";
 import { createHash as createHash2 } from "crypto";
-import path24 from "path";
+import path26 from "path";
 var NAME_RE5 = /^[a-z0-9][a-z0-9-]*$/;
 var KIND_DIR = {
   skill: "skills",
@@ -3432,8 +4112,8 @@ function objectExt(kind) {
   return kind === "tool" || kind === "connection" ? ".yaml" : ".md";
 }
 function safeRepoPath(objectPath) {
-  const normalized = path24.normalize(objectPath);
-  if (path24.isAbsolute(normalized) || normalized === ".." || normalized.startsWith(`..${path24.sep}`)) {
+  const normalized = path26.normalize(objectPath);
+  if (path26.isAbsolute(normalized) || normalized === ".." || normalized.startsWith(`..${path26.sep}`)) {
     throw new Error(`Unsafe object path: ${objectPath}`);
   }
   return normalized;
@@ -3447,7 +4127,7 @@ function inferKind(objectPath, override) {
   if (segments.includes("tools")) return "tool";
   if (segments.includes("connections")) return "connection";
   if (segments.includes("rules")) return "rule";
-  const ext = path24.extname(objectPath).toLowerCase();
+  const ext = path26.extname(objectPath).toLowerCase();
   if (ext === ".yaml" || ext === ".yml") return "tool";
   if (ext === ".md") return "skill";
   throw new Error(
@@ -3455,7 +4135,7 @@ function inferKind(objectPath, override) {
   );
 }
 function deriveName(objectPath) {
-  const base = path24.basename(objectPath, path24.extname(objectPath));
+  const base = path26.basename(objectPath, path26.extname(objectPath));
   if (!NAME_RE5.test(base)) {
     throw new Error(`Invalid object name \`${base}\` (use lowercase letters, digits, and dashes).`);
   }
@@ -3467,8 +4147,8 @@ async function hashDirectory(root) {
   async function walk(dir) {
     const entries = (await readdir5(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
     for (const entry of entries) {
-      const full = path24.join(dir, entry.name);
-      const rel = path24.relative(root, full).split(path24.sep).join("/");
+      const full = path26.join(dir, entry.name);
+      const rel = path26.relative(root, full).split(path26.sep).join("/");
       if (entry.isSymbolicLink()) {
         throw new Error(`Refusing to install skill directory with symlink: ${rel}`);
       }
@@ -3479,7 +4159,7 @@ async function hashDirectory(root) {
       if (entry.isFile()) {
         hash.update(`file:${rel}
 `);
-        hash.update(await readFile10(full));
+        hash.update(await readFile11(full));
         hash.update("\n");
       }
     }
@@ -3488,8 +4168,8 @@ async function hashDirectory(root) {
   return hash.digest("hex");
 }
 async function validateSkillDirectory2(sourcePath, expectedName) {
-  const skillPath = path24.join(sourcePath, "SKILL.md");
-  const parsed = parseFrontmatter(await readFile10(skillPath, "utf8"));
+  const skillPath = path26.join(sourcePath, "SKILL.md");
+  const parsed = parseFrontmatter(await readFile11(skillPath, "utf8"));
   const result = skillFrontmatterSchema.safeParse(parsed.data);
   if (!result.success) {
     const detail = result.error.issues.map((issue) => issue.message).join("; ");
@@ -3518,7 +4198,7 @@ async function installObject(repoRoot, rawSource, options = {}) {
     objectPath = safeRepoPath(within);
     refLabel = ref.ref;
     const fetched = await fetchGitSource(ref);
-    sourcePath = path24.join(fetched.dir, objectPath);
+    sourcePath = path26.join(fetched.dir, objectPath);
     resolved = fetched.sha;
     cleanup = fetched.cleanup;
   } else {
@@ -3533,20 +4213,20 @@ async function installObject(repoRoot, rawSource, options = {}) {
     const destDir = scope === "user" ? userObjectDir(dirKey, options.home) : projectObjectDir(repoRoot, dirKey);
     let destPath;
     let integrity;
-    const info = await stat9(sourcePath);
+    const info = await stat10(sourcePath);
     if (info.isDirectory()) {
       if (kind !== "skill") {
         throw new Error("Only skill objects may be installed from a directory.");
       }
       integrity = `sha256:${await validateSkillDirectory2(sourcePath, name)}`;
-      destPath = path24.join(destDir, name);
+      destPath = path26.join(destDir, name);
       await mkdir10(destDir, { recursive: true });
       await cp2(sourcePath, destPath, { recursive: true, force: true });
     } else {
-      const content = await readFile10(sourcePath, "utf8");
-      destPath = path24.join(destDir, `${name}${objectExt(kind)}`);
+      const content = await readFile11(sourcePath, "utf8");
+      destPath = path26.join(destDir, `${name}${objectExt(kind)}`);
       await mkdir10(destDir, { recursive: true });
-      await writeFile9(destPath, content, "utf8");
+      await writeFile10(destPath, content, "utf8");
       integrity = `sha256:${hashContent(content)}`;
     }
     const entry = {
@@ -3598,7 +4278,7 @@ async function runInstall(repoRoot, source, options) {
     if (installed.kind === "skill" && installed.entry.sourceKind !== "local") {
       console.log("  note: inspect external skills before trusting bundled scripts, assets, or allowed tools.");
       if (scope === "project") {
-        console.log(`  inspect: threadroot skills inspect ${path25.relative(repoRoot, installed.path)}`);
+        console.log(`  inspect: threadroot skills inspect ${path27.relative(repoRoot, installed.path)}`);
       }
     }
   } catch (error) {
@@ -3611,39 +4291,6 @@ async function runInstall(repoRoot, source, options) {
 import readline from "readline";
 import { stdin as input, stdout as output } from "process";
 import { z as z4 } from "zod";
-
-// src/core/status.ts
-async function harnessStatus(repoRoot, options = {}) {
-  let harness;
-  try {
-    harness = await resolveHarness(repoRoot, { home: options.home });
-  } catch (error) {
-    if (error instanceof HarnessError) {
-      return { exists: false };
-    }
-    throw error;
-  }
-  const files = await compile(repoRoot, harness);
-  const drift = await detectDrift(repoRoot, files);
-  return {
-    exists: true,
-    manifest: {
-      name: harness.manifest.name,
-      profile: harness.manifest.profile,
-      adapters: harness.manifest.adapters,
-      toolsAllow: harness.manifest.tools.allow
-    },
-    counts: {
-      skills: harness.skills.length,
-      rules: harness.rules.length,
-      tools: harness.tools.length,
-      memory: harness.memory.length
-    },
-    drift
-  };
-}
-
-// src/mcp/server.ts
 function defineTool(spec) {
   return spec;
 }
@@ -3922,8 +4569,9 @@ async function handleMessage(repoRoot, request) {
     if (request.method === "initialize") {
       return resultResponse(request, {
         protocolVersion: "2024-11-05",
-        serverInfo: { name: "threadroot", version: "0.1.1" },
-        capabilities: { tools: {} }
+        serverInfo: { name: "threadroot", version: "0.1.3" },
+        capabilities: { tools: {} },
+        instructions: "Threadroot exposes the repository's AI agent harness. Call `context` before broad coding work, `doctor` for health and trust checks, inspect skills/tools before risky actions, and use `memory_append` for durable handoffs."
       });
     }
     if (request.method === "notifications/initialized") {
@@ -4064,29 +4712,28 @@ Repository:
 ${repoRoot}
 
 Goal:
-Initialize Threadroot so this repo has a portable AI-agent harness in one canonical \`.threadroot/\` directory.
+Make this repository ready for agent-assisted development with minimal project clutter.
 
 Rules:
 - Prefer deterministic CLI commands.
-- Do not overwrite user-owned files without checking Threadroot status/diff.
+- Do not invent Threadroot commands.
 - Keep context small. Use Threadroot context output before reading broad project files.
+- Do not create provider-specific project files unless the user asks.
 
 Steps:
 1. Check whether Threadroot is available with \`threadroot --version\`.
 2. If it is not available, try \`npm exec threadroot -- --help\` or \`pnpm dlx threadroot --help\`. If this is a local checkout, use \`${localCommand} --help\`.
-3. Run \`threadroot status\` to check whether a harness already exists.
-4. If no harness exists, run \`threadroot init\`. Use \`--no-import\` only when the user explicitly wants a blank-slate harness.
-5. Run \`threadroot status\` again.
-6. If the user asks for provider-native project skill files, run \`threadroot expose <agent>\` or \`threadroot expose all\`.
-7. Run \`threadroot context "current task"\` with the user's actual task to find relevant skills, rules, tools, and memory.
-8. If project-local MCP config is useful, ask before running \`threadroot mcp setup --write\`, then tell the user to reload their agent surface.
+3. Run \`threadroot bootstrap --yes --agent all --task "current task"\`. If this is a local checkout, run \`${localCommand} bootstrap --yes --agent all --task "current task"\`.
+4. Run \`threadroot start "current task"\` with the user's actual task.
+5. If the user asks for provider-native project skill files, run \`threadroot expose <agent>\` or \`threadroot expose all\`.
+6. If project-local MCP config is useful, ask before running \`threadroot mcp setup --write\`, then tell the user to reload their agent surface.
 
 Final response:
 Say exactly:
-"Success: Threadroot is initialized. Run \`threadroot status\` or \`threadroot context "<task>"\` to use it."
+"Success: Threadroot is ready. Run \`threadroot start "<task>"\` for future sessions."
 
 If using a local checkout instead of an installed package, say:
-"Success: Threadroot is initialized. Run \`${localCommand} status\` or \`${localCommand} context "<task>"\` to use it."`;
+"Success: Threadroot is ready. Run \`${localCommand} start "<task>"\` for future sessions."`;
 }
 function parseAgent(value) {
   if (value === "codex" || value === "copilot" || value === "cursor" || value === "claude" || value === "generic") {
@@ -4146,11 +4793,11 @@ function agentNotes(agent) {
 }
 
 // src/core/mcp-config.ts
-import { mkdir as mkdir11, readFile as readFile11, writeFile as writeFile10 } from "fs/promises";
-import path26 from "path";
+import { mkdir as mkdir11, readFile as readFile12, writeFile as writeFile11 } from "fs/promises";
+import path28 from "path";
 var TARGETS = [
-  { agent: "copilot", file: path26.join(".vscode", "mcp.json"), key: "servers" },
-  { agent: "cursor", file: path26.join(".cursor", "mcp.json"), key: "mcpServers" },
+  { agent: "copilot", file: path28.join(".vscode", "mcp.json"), key: "servers" },
+  { agent: "cursor", file: path28.join(".cursor", "mcp.json"), key: "mcpServers" },
   { agent: "claude", file: ".mcp.json", key: "mcpServers" }
 ];
 function mcpServerEntry(command, scriptPath) {
@@ -4159,7 +4806,7 @@ function mcpServerEntry(command, scriptPath) {
 async function mergeConfig(filePath, key, entry) {
   let config = {};
   try {
-    const raw = await readFile11(filePath, "utf8");
+    const raw = await readFile12(filePath, "utf8");
     const parsed = JSON.parse(raw);
     if (parsed && typeof parsed === "object") {
       config = parsed;
@@ -4172,8 +4819,8 @@ async function mergeConfig(filePath, key, entry) {
   const servers = config[key] && typeof config[key] === "object" ? config[key] : {};
   servers.threadroot = { ...entry };
   config[key] = servers;
-  await mkdir11(path26.dirname(filePath), { recursive: true });
-  await writeFile10(filePath, `${JSON.stringify(config, null, 2)}
+  await mkdir11(path28.dirname(filePath), { recursive: true });
+  await writeFile11(filePath, `${JSON.stringify(config, null, 2)}
 `, "utf8");
 }
 async function writeProjectMcpConfigs(input2) {
@@ -4181,7 +4828,7 @@ async function writeProjectMcpConfigs(input2) {
   const targets = agents ? TARGETS.filter((target) => agents.includes(target.agent)) : TARGETS;
   const written = [];
   for (const target of targets) {
-    const filePath = path26.join(input2.repoRoot, target.file);
+    const filePath = path28.join(input2.repoRoot, target.file);
     await mergeConfig(filePath, target.key, input2.entry);
     written.push(target.file);
   }
@@ -4215,6 +4862,24 @@ async function runMcpSetup(repoRoot, options) {
   }
   console.log(mcpSetupGuide({ repoRoot, agent: options.agent }));
 }
+async function runMcpCheck(repoRoot, options) {
+  const timeoutMs = options.timeout ? Number.parseInt(options.timeout, 10) : void 0;
+  const report = await checkCodexMcp({ repoRoot, timeoutMs });
+  console.log(`Threadroot MCP check: ${report.status}`);
+  console.log(`config: ${report.configPath}`);
+  if (report.entry) {
+    console.log(`server: ${report.entry.command} ${report.entry.args.join(" ")}`.trim());
+  }
+  for (const message of report.messages) {
+    console.log(`- ${message}`);
+  }
+  if (report.tools.length > 0) {
+    console.log(`tools: ${report.tools.join(", ")}`);
+  }
+  if (report.status === "error") {
+    process.exitCode = 1;
+  }
+}
 
 // src/commands/memory.ts
 async function runMemoryRead(repoRoot, type) {
@@ -4301,7 +4966,8 @@ async function runSetup(_repoRoot, options) {
     agents: options.agent,
     mode,
     force: options.force,
-    mcp: options.mcp
+    mcp: options.mcp,
+    mcpEntry: options.mcp ? mcpEntryForCurrentProcess() : void 0
   });
   const title = mode === "dry-run" ? "Global setup plan" : mode === "check" ? "Global setup check" : mode === "undo" ? "Global setup undo" : "Global setup complete";
   console.log(`${title}:`);
@@ -4309,11 +4975,33 @@ async function runSetup(_repoRoot, options) {
     const suffix = entry.message ? ` - ${entry.message}` : "";
     console.log(`- ${entry.label}: ${entry.status} ${entry.path}${suffix}`);
   }
+  if (options.mcp && options.global && mode === "write") {
+    const check = await checkCodexMcp({ repoRoot: _repoRoot });
+    console.log(`MCP verification: ${check.status}`);
+    if (check.entry) {
+      console.log(`MCP server: ${check.entry.command} ${check.entry.args.join(" ")}`.trim());
+    }
+    for (const message of check.messages) {
+      console.log(`- ${message}`);
+    }
+    if (check.status === "error") {
+      process.exitCode = 1;
+    }
+  }
   if (mode === "write") {
     console.log("Reload or restart open agent sessions so new global skills/config are discovered.");
   }
 }
 
+// src/commands/start.ts
+async function runStart(repoRoot, task, options) {
+  const report = await startSession(repoRoot, { task: task ?? options.task });
+  printStartReport(report);
+  if (!report.status.exists || report.doctor && !report.doctor.ok) {
+    process.exitCode = 1;
+  }
+}
+
 // src/commands/status.ts
 async function runStatus(repoRoot) {
   const status = await harnessStatus(repoRoot);
@@ -4338,8 +5026,8 @@ async function runStatus(repoRoot) {
 }
 
 // src/core/packs/index.ts
-import { cp as cp3, mkdir as mkdir12, readFile as readFile12, readdir as readdir6, stat as stat10 } from "fs/promises";
-import path27 from "path";
+import { cp as cp3, mkdir as mkdir12, readFile as readFile13, readdir as readdir6, stat as stat11 } from "fs/promises";
+import path29 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { parse as parseYaml3 } from "yaml";
 import { z as z5 } from "zod";
@@ -4352,18 +5040,18 @@ var packManifestSchema = z5.object({
   rules: z5.array(z5.string()).default([]),
   connections: z5.array(z5.string()).default([])
 });
-var DIST_DIR2 = path27.dirname(fileURLToPath2(import.meta.url));
-var PACKAGE_ROOT_FROM_BUNDLE2 = path27.resolve(DIST_DIR2, "..");
-var PACKAGE_ROOT_FROM_DIST2 = path27.resolve(DIST_DIR2, "../../..");
-var PACKAGE_ROOT_FROM_SRC2 = path27.resolve(DIST_DIR2, "../../../..");
+var DIST_DIR2 = path29.dirname(fileURLToPath2(import.meta.url));
+var PACKAGE_ROOT_FROM_BUNDLE2 = path29.resolve(DIST_DIR2, "..");
+var PACKAGE_ROOT_FROM_DIST2 = path29.resolve(DIST_DIR2, "../../..");
+var PACKAGE_ROOT_FROM_SRC2 = path29.resolve(DIST_DIR2, "../../../..");
 var PACK_CANDIDATES = [
-  path27.join(PACKAGE_ROOT_FROM_BUNDLE2, "packs"),
-  path27.join(PACKAGE_ROOT_FROM_DIST2, "packs"),
-  path27.join(PACKAGE_ROOT_FROM_SRC2, "packs")
+  path29.join(PACKAGE_ROOT_FROM_BUNDLE2, "packs"),
+  path29.join(PACKAGE_ROOT_FROM_DIST2, "packs"),
+  path29.join(PACKAGE_ROOT_FROM_SRC2, "packs")
 ];
 async function exists5(target) {
   try {
-    await stat10(target);
+    await stat11(target);
     return true;
   } catch (error) {
     if (error.code === "ENOENT") {
@@ -4391,22 +5079,22 @@ async function isPackRoot(candidate) {
     return false;
   }
   for (const entry of entries) {
-    if (entry.isDirectory() && await exists5(path27.join(candidate, entry.name, "pack.yaml"))) {
+    if (entry.isDirectory() && await exists5(path29.join(candidate, entry.name, "pack.yaml"))) {
       return true;
     }
   }
   return false;
 }
 function safeRelative(ref) {
-  const normalized = path27.normalize(ref);
-  if (path27.isAbsolute(normalized) || normalized === ".." || normalized.startsWith(`..${path27.sep}`)) {
+  const normalized = path29.normalize(ref);
+  if (path29.isAbsolute(normalized) || normalized === ".." || normalized.startsWith(`..${path29.sep}`)) {
     throw new Error(`Unsafe pack reference: ${ref}`);
   }
   return normalized;
 }
 async function readPackManifest(packDir) {
-  const file = path27.join(packDir, "pack.yaml");
-  const parsed = packManifestSchema.safeParse(parseYaml3(await readFile12(file, "utf8")));
+  const file = path29.join(packDir, "pack.yaml");
+  const parsed = packManifestSchema.safeParse(parseYaml3(await readFile13(file, "utf8")));
   if (!parsed.success) {
     const detail = parsed.error.issues.map((issue) => issue.message).join("; ");
     throw new Error(`Invalid pack manifest ${file}: ${detail}`);
@@ -4414,7 +5102,7 @@ async function readPackManifest(packDir) {
   return parsed.data;
 }
 async function packDirFor(repoRoot, nameOrPath) {
-  if (path27.isAbsolute(nameOrPath)) {
+  if (path29.isAbsolute(nameOrPath)) {
     return nameOrPath;
   }
   if (nameOrPath.startsWith(".") || nameOrPath.includes("/") || nameOrPath.includes("\\")) {
@@ -4422,14 +5110,14 @@ async function packDirFor(repoRoot, nameOrPath) {
   }
   const bundled = await bundledPacksDir();
   if (bundled) {
-    return path27.join(bundled, nameOrPath);
+    return path29.join(bundled, nameOrPath);
   }
-  return toRepoPath(repoRoot, path27.join("packs", nameOrPath));
+  return toRepoPath(repoRoot, path29.join("packs", nameOrPath));
 }
 async function directFiles(dir, ext) {
   try {
     const entries = await readdir6(dir, { withFileTypes: true });
-    return entries.filter((entry) => entry.isFile() && entry.name.endsWith(ext)).map((entry) => path27.join(dir, entry.name)).sort();
+    return entries.filter((entry) => entry.isFile() && entry.name.endsWith(ext)).map((entry) => path29.join(dir, entry.name)).sort();
   } catch (error) {
     if (error.code === "ENOENT") {
       return [];
@@ -4442,11 +5130,11 @@ async function skillEntries(dir) {
     const entries = await readdir6(dir, { withFileTypes: true });
     const result = [];
     for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
-      const full = path27.join(dir, entry.name);
+      const full = path29.join(dir, entry.name);
       if (entry.isFile() && entry.name.endsWith(".md")) {
         result.push(full);
       }
-      if (entry.isDirectory() && await exists5(path27.join(full, "SKILL.md"))) {
+      if (entry.isDirectory() && await exists5(path29.join(full, "SKILL.md"))) {
         result.push(full);
       }
     }
@@ -4461,34 +5149,34 @@ async function skillEntries(dir) {
 async function collectObjects(packDir, manifest) {
   async function resolveRef(ref) {
     const safe = safeRelative(ref);
-    const local = path27.resolve(packDir, safe);
+    const local = path29.resolve(packDir, safe);
     if (await exists5(local)) {
       return local;
     }
-    return path27.resolve(packDir, "..", "..", safe);
+    return path29.resolve(packDir, "..", "..", safe);
   }
   return {
     skills: [
       ...await Promise.all(manifest.skills.map(resolveRef)),
-      ...await skillEntries(path27.join(packDir, "skills"))
+      ...await skillEntries(path29.join(packDir, "skills"))
     ],
     tools: [
       ...await Promise.all(manifest.tools.map(resolveRef)),
-      ...await directFiles(path27.join(packDir, "tools"), ".yaml")
+      ...await directFiles(path29.join(packDir, "tools"), ".yaml")
     ],
     rules: [
       ...await Promise.all(manifest.rules.map(resolveRef)),
-      ...await directFiles(path27.join(packDir, "rules"), ".md")
+      ...await directFiles(path29.join(packDir, "rules"), ".md")
     ],
     connections: [
       ...await Promise.all(manifest.connections.map(resolveRef)),
-      ...await directFiles(path27.join(packDir, "connections"), ".yaml")
+      ...await directFiles(path29.join(packDir, "connections"), ".yaml")
     ]
   };
 }
 function baseName(source) {
-  const parsed = path27.basename(source) === "SKILL.md" ? path27.dirname(source) : source;
-  return path27.basename(parsed, path27.extname(parsed));
+  const parsed = path29.basename(source) === "SKILL.md" ? path29.dirname(source) : source;
+  return path29.basename(parsed, path29.extname(parsed));
 }
 async function listPacks(repoRoot) {
   const dirs = [toRepoPath(repoRoot, "packs"), await bundledPacksDir()].filter((dir) => Boolean(dir));
@@ -4505,8 +5193,8 @@ async function listPacks(repoRoot) {
       if (!entry.isDirectory() || seen.has(entry.name)) {
         continue;
       }
-      const packDir = path27.join(root, entry.name);
-      if (!await exists5(path27.join(packDir, "pack.yaml"))) {
+      const packDir = path29.join(root, entry.name);
+      if (!await exists5(path29.join(packDir, "pack.yaml"))) {
         continue;
       }
       seen.add(entry.name);
@@ -4530,14 +5218,14 @@ async function inspectPack(repoRoot, nameOrPath) {
   };
 }
 async function validateProse(file, kind) {
-  const target = path27.basename(file) === "SKILL.md" ? file : file;
-  const content = await readFile12(target, "utf8");
+  const target = path29.basename(file) === "SKILL.md" ? file : file;
+  const content = await readFile13(target, "utf8");
   const parsed = parseFrontmatter(content);
   const schema = kind === "skill" ? skillFrontmatterSchema : ruleFrontmatterSchema;
   schema.parse(parsed.data);
 }
 async function validateYaml(file, kind) {
-  const content = await readFile12(file, "utf8");
+  const content = await readFile13(file, "utf8");
   const schema = kind === "tool" ? toolManifestSchema : connectionManifestSchema;
   schema.parse(parseYaml3(content));
 }
@@ -4548,7 +5236,7 @@ async function validatePack(repoRoot, nameOrPath) {
     const manifest = await readPackManifest(packDir);
     const objects = await collectObjects(packDir, manifest);
     for (const skill of objects.skills) {
-      await validateProse(path27.basename(skill) === "SKILL.md" ? skill : path27.join(skill, "SKILL.md"), "skill");
+      await validateProse(path29.basename(skill) === "SKILL.md" ? skill : path29.join(skill, "SKILL.md"), "skill");
     }
     for (const rule of objects.rules) await validateProse(rule, "rule");
     for (const tool of objects.tools) await validateYaml(tool, "tool");
@@ -4562,9 +5250,9 @@ async function validatePack(repoRoot, nameOrPath) {
   return { ok: !findings.some((finding3) => finding3.severity === "error"), findings };
 }
 async function copyObject(source, destDir) {
-  const info = await stat10(source);
+  const info = await stat11(source);
   const name = baseName(source);
-  const dest = info.isDirectory() ? path27.join(destDir, name) : path27.join(destDir, path27.basename(source));
+  const dest = info.isDirectory() ? path29.join(destDir, name) : path29.join(destDir, path29.basename(source));
   await mkdir12(destDir, { recursive: true });
   await cp3(source, dest, { recursive: true, force: true });
   return dest;
@@ -4853,7 +5541,9 @@ async function runConnectionsCheck(repoRoot) {
 // src/cli.ts
 function createProgram(repoRoot = process.cwd()) {
   const program = new Command();
-  program.name("threadroot").description("Git for your AI agent harness: one canonical .threadroot source, optional provider exposure.").version("0.1.1");
+  program.name("threadroot").description("Git for your AI agent harness: one command to bootstrap, one .threadroot source.").version("0.1.3");
+  program.command("bootstrap").description("Plan or apply first-run Threadroot setup for this machine and repository.").option("-y, --yes", "Apply the setup plan. Without --yes, bootstrap prints a dry-run plan.").option("--dry-run", "Print the setup plan without writing files.").option("--agent <list>", "Provider(s): codex,claude,cursor,copilot,gemini,windsurf,antigravity,opencode,all.").option("--task <task>", "Task used for the initial context slice.").option("--mcp", "Also add Threadroot MCP to Codex global config when Codex is selected.").option("--expose <list>", "Also write project provider skill shims: codex,claude,cursor,copilot,gemini,windsurf,antigravity,opencode,all.").option("--no-global", "Skip one-time machine-level agent setup.").option("--no-init", "Skip project harness initialization.").option("--no-import", "Skip importing existing vendor files during init.").option("--profile <profile>", "Override the detected project profile during init.").action((options) => runBootstrap(repoRoot, options));
+  program.command("start").argument("[task]", "Task to prepare context for.").option("--task <task>", "Task to prepare context for.").description("Start a focused Threadroot agent session: doctor, status, context, and command map.").action((task, options) => runStart(repoRoot, task, options));
   program.command("init").description("Scaffold a local-only Threadroot harness and import existing vendor files once.").option("--force", "Re-initialize over an existing harness.").option("--no-import", "Skip importing existing vendor files (blank-slate init).").option("--profile <profile>", "Override the detected project profile.").option("--adapters <list>", "Comma-separated adapters: agents,claude,copilot,cursor.").option("--expose <list>", "Comma-separated provider skill shims to write: codex,claude,cursor,copilot,gemini,windsurf,antigravity,opencode,all.").action((options) => runInit(repoRoot, options));
   program.command("expose").argument("[agent]", "Provider(s) to expose: codex,claude,cursor,copilot,gemini,windsurf,antigravity,opencode,all.").option("--dry-run", "Show project files that would be written.").option("--check", "Check current project exposure state.").option("--undo", "Remove Threadroot-managed project exposure files.").option("--force", "Replace an existing unmanaged threadroot skill.").description("Write thin provider project skills that point agents at `.threadroot/`.").action((agent, options) => runExpose(repoRoot, agent, options));
   program.command("setup").option("--global", "Install machine-level Threadroot agent bootstrap skills/config.").option("--agent <list>", "Provider(s): codex,claude,cursor,copilot,gemini,windsurf,antigravity,opencode,all.").option("--dry-run", "Show global files that would be written.").option("--check", "Check global Threadroot setup state.").option("--undo", "Remove Threadroot-managed global setup files/blocks.").option("--force", "Replace an existing unmanaged threadroot skill.").option("--mcp", "Also add Threadroot MCP to Codex global config when Codex is selected.").description("Set up Threadroot once per machine for supported coding agents.").action((options) => runSetup(repoRoot, options));
@@ -4889,6 +5579,7 @@ function createProgram(repoRoot = process.cwd()) {
   skills.command("validate").option("--path <path>", "Validate a repo-relative skill file, skill directory, or skill collection.").description("Validate skill frontmatter, naming, trigger descriptions, and progressive-disclosure hygiene.").action((options) => runSkillsValidate(repoRoot, options));
   const mcp = program.command("mcp").description("Run or configure the local Threadroot MCP server.");
   mcp.action(() => runMcp(repoRoot));
+  mcp.command("check").option("--timeout <ms>", "Handshake timeout in milliseconds.").description("Verify Codex MCP config and the Threadroot stdio server handshake.").action((options) => runMcpCheck(repoRoot, options));
   mcp.command("setup").option("--agent <agent>", "all, generic, codex, copilot, cursor, or claude.").option("--write", "Write project-local MCP config files for the agents.").description("Print MCP config snippets and a pasteable agent bootstrap prompt.").action((options) => runMcpSetup(repoRoot, options));
   return program;
 }