@crewhaus/context-bundle 0.1.3 → 0.1.5

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+export type BuildContextBundleOpts = {
+    readonly docsRoot: string;
+    readonly demosRoot: string;
+    readonly factoryRoot: string;
+    readonly bundledAt?: string;
+};
+export type ContextBundleSource = {
+    readonly path: string;
+    readonly bytes: number;
+};
+export type ContextBundle = {
+    readonly markdown: string;
+    readonly sources: readonly ContextBundleSource[];
+};
+export declare function buildContextBundle(opts: BuildContextBundleOpts): ContextBundle;
+export declare function sliceDecisionTree(indexMarkdown: string): string;
+export declare function sliceSpecSchemaExcerpt(specSource: string): string;
+export type DiscoverRootsOpts = {
+    readonly startDir?: string;
+    readonly env?: NodeJS.ProcessEnv;
+};
+export type DiscoveredRoots = {
+    readonly factoryRoot: string;
+    readonly docsRoot: string;
+    readonly demosRoot: string;
+};
+export declare function discoverRoots(opts?: DiscoverRootsOpts): DiscoveredRoots;

package/dist/index.js

@@ -0,0 +1,148 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+const HEADER = `# CrewHaus Context Bundle
+
+> A single-file orientation manifest for AI agents working with CrewHaus.
+> CrewHaus is a meta-harness compiler: write one spec, emit many runtime shapes.
+> Live docs: https://crewhaus.ai/docs · Source of truth for schema: \`packages/spec/src/index.ts\`
+`;
+const QUICKSTART = `## Quickstart
+
+\`\`\`bash
+crewhaus init my-agent
+crewhaus compile my-agent/crewhaus.yaml -o ./dist
+crewhaus run ./dist
+\`\`\`
+
+The \`target:\` field in \`crewhaus.yaml\` selects the runtime shape. Currently supported:
+
+| target      | shape                                  |
+|-------------|----------------------------------------|
+| \`cli\`       | interactive coding-agent loop         |
+| \`workflow\`  | sequence of steps                     |
+| \`channel\`   | Slack/Discord/Telegram/iMessage daemon|
+| \`graph\`     | stateful graph with HITL checkpoints  |
+| \`managed\`   | Anthropic Managed Agents              |
+| \`pipeline\`  | RAG / extract-transform pipeline      |
+| \`crew\`      | multi-agent role-based crew           |
+| \`research\`  | autonomous long-horizon research      |
+| \`batch\`     | queue worker                          |
+| \`voice\`     | voice agent                           |
+| \`browser\`   | browser agent                         |
+| \`eval\`      | eval harness bundle                   |
+`;
+export function buildContextBundle(opts) {
+    const bundledAt = opts.bundledAt ?? new Date().toISOString();
+    const sources = [];
+    const sections = [];
+    sections.push(HEADER);
+    sections.push(`> Bundled at: ${bundledAt}`);
+    sections.push(QUICKSTART);
+    sections.push(readSection("Spec schema (source of truth)", "ts", () => readTracked(sources, resolve(opts.factoryRoot, "packages/spec/src/index.ts"))));
+    sections.push(readSection("Picking a recipe — diagnostic decision tree", "md", () => sliceDecisionTree(readTracked(sources, resolve(opts.demosRoot, "recipes/INDEX.md")))));
+    sections.push(`## Recipe index\n\n${listRecipes(opts.demosRoot, sources)}`);
+    sections.push(readSection("Module catalog — layer index", "md", () => extractHeadings(readTracked(sources, resolve(opts.docsRoot, "MODULE-CATALOG.md")))));
+    sections.push(readSection("Getting started", "md", () => readTracked(sources, resolve(opts.docsRoot, "GETTING-STARTED.md"))));
+    const markdown = `${sections.join("\n\n")}\n`;
+    return { markdown, sources };
+}
+function readTracked(sources, path) {
+    const text = readFileSync(path, "utf-8");
+    sources.push({ path, bytes: Buffer.byteLength(text, "utf-8") });
+    return text;
+}
+function readSection(title, fence, body) {
+    const content = body();
+    if (fence === "ts") {
+        return `## ${title}\n\n\`\`\`ts\n${content}\n\`\`\``;
+    }
+    return `## ${title}\n\n${content}`;
+}
+export function sliceDecisionTree(indexMarkdown) {
+    const startMarker = "## Pick a recipe";
+    const endMarker = "## Recipes by part";
+    const start = indexMarkdown.indexOf(startMarker);
+    if (start === -1)
+        return indexMarkdown;
+    const end = indexMarkdown.indexOf(endMarker, start);
+    if (end === -1)
+        return indexMarkdown.slice(start);
+    return indexMarkdown.slice(start, end).trim();
+}
+export function sliceSpecSchemaExcerpt(specSource) {
+    const marker = specSource.indexOf("discriminatedUnion");
+    if (marker === -1)
+        return specSource.slice(0, 8000);
+    const start = Math.max(0, marker - 800);
+    const end = Math.min(specSource.length, marker + 5000);
+    return specSource.slice(start, end);
+}
+function extractHeadings(catalog) {
+    const lines = catalog.split("\n");
+    const headings = lines.filter((line) => /^#{1,3}\s/.test(line));
+    return headings.join("\n");
+}
+function listRecipes(demosRoot, sources) {
+    const recipesDir = resolve(demosRoot, "recipes");
+    if (!existsSync(recipesDir))
+        return "_(recipes directory not found)_";
+    const files = readdirSync(recipesDir)
+        .filter((name) => name.endsWith(".md") && name !== "INDEX.md")
+        .sort();
+    const rows = [];
+    for (const file of files) {
+        const path = join(recipesDir, file);
+        const text = readFileSync(path, "utf-8");
+        sources.push({ path, bytes: Buffer.byteLength(text, "utf-8") });
+        const title = firstHeading(text) ?? basename(file, ".md");
+        rows.push(`- [${file}](demos/walkthroughs/${file}) — ${title}`);
+    }
+    return rows.join("\n");
+}
+function firstHeading(markdown) {
+    for (const rawLine of markdown.split("\n")) {
+        const line = rawLine.trim();
+        if (line.startsWith("# "))
+            return line.slice(2).trim();
+    }
+    return undefined;
+}
+export function discoverRoots(opts = {}) {
+    const env = opts.env ?? process.env;
+    const factoryRoot = resolveRoot(env["CREWHAUS_FACTORY_ROOT"], "factory", ["packages/spec/src/index.ts"], opts.startDir);
+    const docsRoot = resolveRoot(env["CREWHAUS_DOCS_ROOT"], "docs", ["GETTING-STARTED.md", "MODULE-CATALOG.md"], opts.startDir);
+    const demosRoot = resolveRoot(env["CREWHAUS_DEMOS_ROOT"], "demos", ["recipes/INDEX.md"], opts.startDir);
+    return { factoryRoot, docsRoot, demosRoot };
+}
+function resolveRoot(envValue, siblingName, markers, startDir) {
+    if (envValue !== undefined && envValue !== "") {
+        const abs = resolve(envValue);
+        assertMarkers(abs, markers, `${envValue} (from env)`);
+        return abs;
+    }
+    const found = walkUpForSibling(startDir ?? process.cwd(), siblingName, markers);
+    if (found !== undefined)
+        return found;
+    throw new Error(`Could not locate ${siblingName}/ with markers ${markers.join(", ")}. ` +
+        `Set CREWHAUS_${siblingName.toUpperCase()}_ROOT or run from inside a CrewHaus checkout.`);
+}
+function assertMarkers(root, markers, label) {
+    for (const marker of markers) {
+        if (!existsSync(resolve(root, marker))) {
+            throw new Error(`${label} is missing required file: ${marker}`);
+        }
+    }
+}
+function walkUpForSibling(from, siblingName, markers) {
+    let current = resolve(from);
+    let parent = resolve(current, "..");
+    for (;; current = parent, parent = resolve(current, "..")) {
+        const candidate = resolve(current, siblingName);
+        if (existsSync(candidate) && markers.every((m) => existsSync(resolve(candidate, m)))) {
+            return candidate;
+        }
+        if (parent === current)
+            break;
+    }
+    return undefined;
+}

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@crewhaus/context-bundle",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "Builds a single-markdown manifest of CrewHaus docs + recipes + schema. Consumed by `crewhaus context --bundle` and the cloud demo prompt builder.",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
     "test": "bun test src"
@@ -30,5 +33,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -1,225 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { mkdirSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join, resolve } from "node:path";
-import { buildContextBundle, discoverRoots, sliceSpecSchemaExcerpt } from "./index";
-
-function makeFixtureTree(): {
-  factoryRoot: string;
-  docsRoot: string;
-  demosRoot: string;
-  monorepoRoot: string;
-} {
-  const monorepoRoot = join(
-    tmpdir(),
-    `crewhaus-context-bundle-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
-  );
-  const factoryRoot = join(monorepoRoot, "factory");
-  const docsRoot = join(monorepoRoot, "docs");
-  const demosRoot = join(monorepoRoot, "demos");
-
-  mkdirSync(join(factoryRoot, "packages/spec/src"), { recursive: true });
-  mkdirSync(docsRoot, { recursive: true });
-  mkdirSync(join(demosRoot, "recipes"), { recursive: true });
-
-  writeFileSync(
-    join(factoryRoot, "packages/spec/src/index.ts"),
-    "export const SPEC_VERSION = 0;\nconst _x = z.discriminatedUnion('target', []);\n",
-  );
-  writeFileSync(
-    join(docsRoot, "GETTING-STARTED.md"),
-    "# Getting started\n\nWelcome to the fixture.\n",
-  );
-  writeFileSync(
-    join(docsRoot, "MODULE-CATALOG.md"),
-    "# Module catalog\n\n## Layer A — Foundations\n\nbody\n\n### A1 — IR\n\nbody\n",
-  );
-  writeFileSync(
-    join(demosRoot, "recipes/INDEX.md"),
-    [
-      "# Recipes",
-      "",
-      "preamble paragraph",
-      "",
-      "## Pick a recipe — diagnostic decision tree",
-      "",
-      "1. First option",
-      "2. Second option",
-      "",
-      "## Recipes by part",
-      "",
-      "more content here",
-    ].join("\n"),
-  );
-  writeFileSync(join(demosRoot, "recipes/01-cli-coding-agent.md"), "# CLI Coding Agent\n\nbody\n");
-  writeFileSync(
-    join(demosRoot, "recipes/02-sequential-workflow.md"),
-    "# Sequential Workflow\n\nbody\n",
-  );
-
-  return { factoryRoot, docsRoot, demosRoot, monorepoRoot };
-}
-
-describe("buildContextBundle", () => {
-  test("produces a bundle with the major sections", () => {
-    const { factoryRoot, docsRoot, demosRoot } = makeFixtureTree();
-    const { markdown, sources } = buildContextBundle({
-      factoryRoot,
-      docsRoot,
-      demosRoot,
-      bundledAt: "2026-05-21T00:00:00Z",
-    });
-
-    expect(markdown).toContain("# CrewHaus Context Bundle");
-    expect(markdown).toContain("Bundled at: 2026-05-21T00:00:00Z");
-    expect(markdown).toContain("## Quickstart");
-    expect(markdown).toContain("## Spec schema");
-    expect(markdown).toContain("z.discriminatedUnion('target', [])");
-    expect(markdown).toContain("## Picking a recipe");
-    expect(markdown).toContain("1. First option");
-    expect(markdown).not.toContain("more content here");
-    expect(markdown).toContain("## Recipe index");
-    expect(markdown).toContain("01-cli-coding-agent.md");
-    expect(markdown).toContain("CLI Coding Agent");
-    expect(markdown).toContain("## Module catalog — layer index");
-    expect(markdown).toContain("## Layer A — Foundations");
-    expect(markdown).not.toContain("body\n");
-    expect(markdown).toContain("## Getting started");
-    expect(markdown).toContain("Welcome to the fixture");
-
-    const paths = sources.map((s) => s.path);
-    expect(paths.some((p) => p.endsWith("packages/spec/src/index.ts"))).toBe(true);
-    expect(paths.some((p) => p.endsWith("recipes/INDEX.md"))).toBe(true);
-    expect(paths.some((p) => p.endsWith("GETTING-STARTED.md"))).toBe(true);
-    expect(paths.some((p) => p.endsWith("MODULE-CATALOG.md"))).toBe(true);
-  });
-
-  test("is deterministic for a fixed bundledAt and tree", () => {
-    const { factoryRoot, docsRoot, demosRoot } = makeFixtureTree();
-    const first = buildContextBundle({
-      factoryRoot,
-      docsRoot,
-      demosRoot,
-      bundledAt: "2026-05-21T00:00:00Z",
-    });
-    const second = buildContextBundle({
-      factoryRoot,
-      docsRoot,
-      demosRoot,
-      bundledAt: "2026-05-21T00:00:00Z",
-    });
-    expect(first.markdown).toBe(second.markdown);
-  });
-});
-
-describe("discoverRoots", () => {
-  test("walks up to find sibling factory/docs/demos directories", () => {
-    const { factoryRoot, docsRoot, demosRoot, monorepoRoot } = makeFixtureTree();
-    const nested = join(monorepoRoot, "factory/packages/spec/src");
-
-    const roots = discoverRoots({ startDir: nested, env: {} });
-
-    expect(roots.factoryRoot).toBe(resolve(factoryRoot));
-    expect(roots.docsRoot).toBe(resolve(docsRoot));
-    expect(roots.demosRoot).toBe(resolve(demosRoot));
-  });
-
-  test("env overrides take precedence", () => {
-    const { factoryRoot, docsRoot, demosRoot } = makeFixtureTree();
-
-    const roots = discoverRoots({
-      startDir: "/tmp",
-      env: {
-        CREWHAUS_FACTORY_ROOT: factoryRoot,
-        CREWHAUS_DOCS_ROOT: docsRoot,
-        CREWHAUS_DEMOS_ROOT: demosRoot,
-      },
-    });
-
-    expect(roots.factoryRoot).toBe(resolve(factoryRoot));
-    expect(roots.docsRoot).toBe(resolve(docsRoot));
-    expect(roots.demosRoot).toBe(resolve(demosRoot));
-  });
-
-  test("throws when roots cannot be located", () => {
-    expect(() => discoverRoots({ startDir: tmpdir(), env: {} })).toThrow(/Could not locate/);
-  });
-
-  test("throws when an env-provided root is missing a required marker", () => {
-    const { factoryRoot, docsRoot } = makeFixtureTree();
-    // Point the demos root at a directory that exists but lacks recipes/INDEX.md.
-    const emptyDemos = join(
-      tmpdir(),
-      `crewhaus-context-bundle-empty-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
-    );
-    mkdirSync(emptyDemos, { recursive: true });
-
-    expect(() =>
-      discoverRoots({
-        startDir: "/tmp",
-        env: {
-          CREWHAUS_FACTORY_ROOT: factoryRoot,
-          CREWHAUS_DOCS_ROOT: docsRoot,
-          CREWHAUS_DEMOS_ROOT: emptyDemos,
-        },
-      }),
-    ).toThrow(/missing required file: recipes\/INDEX\.md/);
-  });
-});
-
-describe("recipe heading fallback", () => {
-  test("falls back to the file basename when a recipe has no top-level heading", () => {
-    const { factoryRoot, docsRoot, demosRoot } = makeFixtureTree();
-    // A recipe whose only headings are deeper than h1 (no "# " line) must
-    // fall back to its basename in the recipe index.
-    writeFileSync(
-      join(demosRoot, "recipes/99-no-top-heading.md"),
-      "## Subheading only\n\nbody without an h1\n",
-    );
-
-    const { markdown } = buildContextBundle({
-      factoryRoot,
-      docsRoot,
-      demosRoot,
-      bundledAt: "2026-05-21T00:00:00Z",
-    });
-
-    expect(markdown).toContain(
-      "- [99-no-top-heading.md](demos/walkthroughs/99-no-top-heading.md) — 99-no-top-heading",
-    );
-  });
-});
-
-describe("sliceSpecSchemaExcerpt", () => {
-  test("centers the excerpt on the discriminatedUnion marker", () => {
-    const before = "A".repeat(2000);
-    const after = "B".repeat(6000);
-    const source = `${before}discriminatedUnion${after}`;
-
-    const excerpt = sliceSpecSchemaExcerpt(source);
-
-    // Starts 800 chars before the marker and runs up to 5000 chars past it.
-    const markerIndex = source.indexOf("discriminatedUnion");
-    expect(excerpt).toBe(source.slice(markerIndex - 800, markerIndex + 5000));
-    expect(excerpt).toContain("discriminatedUnion");
-    expect(excerpt.length).toBe(800 + 5000);
-  });
-
-  test("clamps the window to the source bounds when the marker is near the edges", () => {
-    const source = "discriminatedUnion then a short tail";
-
-    const excerpt = sliceSpecSchemaExcerpt(source);
-
-    // marker - 800 clamps to 0 and marker + 5000 clamps to source.length.
-    expect(excerpt).toBe(source);
-  });
-
-  test("falls back to the first 8000 chars when no marker is present", () => {
-    const source = "C".repeat(10000);
-
-    const excerpt = sliceSpecSchemaExcerpt(source);
-
-    expect(excerpt.length).toBe(8000);
-    expect(excerpt).toBe(source.slice(0, 8000));
-  });
-});

package/src/index.ts

@@ -1,232 +0,0 @@
-import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { basename, join, resolve } from "node:path";
-
-export type BuildContextBundleOpts = {
-  readonly docsRoot: string;
-  readonly demosRoot: string;
-  readonly factoryRoot: string;
-  readonly bundledAt?: string;
-};
-
-export type ContextBundleSource = {
-  readonly path: string;
-  readonly bytes: number;
-};
-
-export type ContextBundle = {
-  readonly markdown: string;
-  readonly sources: readonly ContextBundleSource[];
-};
-
-const HEADER = `# CrewHaus Context Bundle
-
-> A single-file orientation manifest for AI agents working with CrewHaus.
-> CrewHaus is a meta-harness compiler: write one spec, emit many runtime shapes.
-> Live docs: https://crewhaus.ai/docs · Source of truth for schema: \`packages/spec/src/index.ts\`
-`;
-
-const QUICKSTART = `## Quickstart
-
-\`\`\`bash
-crewhaus init my-agent
-crewhaus compile my-agent/crewhaus.yaml -o ./dist
-crewhaus run ./dist
-\`\`\`
-
-The \`target:\` field in \`crewhaus.yaml\` selects the runtime shape. Currently supported:
-
-| target      | shape                                  |
-|-------------|----------------------------------------|
-| \`cli\`       | interactive coding-agent loop         |
-| \`workflow\`  | sequence of steps                     |
-| \`channel\`   | Slack/Discord/Telegram/iMessage daemon|
-| \`graph\`     | stateful graph with HITL checkpoints  |
-| \`managed\`   | Anthropic Managed Agents              |
-| \`pipeline\`  | RAG / extract-transform pipeline      |
-| \`crew\`      | multi-agent role-based crew           |
-| \`research\`  | autonomous long-horizon research      |
-| \`batch\`     | queue worker                          |
-| \`voice\`     | voice agent                           |
-| \`browser\`   | browser agent                         |
-| \`eval\`      | eval harness bundle                   |
-`;
-
-export function buildContextBundle(opts: BuildContextBundleOpts): ContextBundle {
-  const bundledAt = opts.bundledAt ?? new Date().toISOString();
-  const sources: ContextBundleSource[] = [];
-
-  const sections: string[] = [];
-  sections.push(HEADER);
-  sections.push(`> Bundled at: ${bundledAt}`);
-  sections.push(QUICKSTART);
-
-  sections.push(
-    readSection("Spec schema (source of truth)", "ts", () =>
-      readTracked(sources, resolve(opts.factoryRoot, "packages/spec/src/index.ts")),
-    ),
-  );
-
-  sections.push(
-    readSection("Picking a recipe — diagnostic decision tree", "md", () =>
-      sliceDecisionTree(readTracked(sources, resolve(opts.demosRoot, "recipes/INDEX.md"))),
-    ),
-  );
-
-  sections.push(`## Recipe index\n\n${listRecipes(opts.demosRoot, sources)}`);
-
-  sections.push(
-    readSection("Module catalog — layer index", "md", () =>
-      extractHeadings(readTracked(sources, resolve(opts.docsRoot, "MODULE-CATALOG.md"))),
-    ),
-  );
-
-  sections.push(
-    readSection("Getting started", "md", () =>
-      readTracked(sources, resolve(opts.docsRoot, "GETTING-STARTED.md")),
-    ),
-  );
-
-  const markdown = `${sections.join("\n\n")}\n`;
-  return { markdown, sources };
-}
-
-function readTracked(sources: ContextBundleSource[], path: string): string {
-  const text = readFileSync(path, "utf-8");
-  sources.push({ path, bytes: Buffer.byteLength(text, "utf-8") });
-  return text;
-}
-
-function readSection(title: string, fence: "ts" | "md", body: () => string): string {
-  const content = body();
-  if (fence === "ts") {
-    return `## ${title}\n\n\`\`\`ts\n${content}\n\`\`\``;
-  }
-  return `## ${title}\n\n${content}`;
-}
-
-export function sliceDecisionTree(indexMarkdown: string): string {
-  const startMarker = "## Pick a recipe";
-  const endMarker = "## Recipes by part";
-  const start = indexMarkdown.indexOf(startMarker);
-  if (start === -1) return indexMarkdown;
-  const end = indexMarkdown.indexOf(endMarker, start);
-  if (end === -1) return indexMarkdown.slice(start);
-  return indexMarkdown.slice(start, end).trim();
-}
-
-export function sliceSpecSchemaExcerpt(specSource: string): string {
-  const marker = specSource.indexOf("discriminatedUnion");
-  if (marker === -1) return specSource.slice(0, 8000);
-  const start = Math.max(0, marker - 800);
-  const end = Math.min(specSource.length, marker + 5000);
-  return specSource.slice(start, end);
-}
-
-function extractHeadings(catalog: string): string {
-  const lines = catalog.split("\n");
-  const headings = lines.filter((line) => /^#{1,3}\s/.test(line));
-  return headings.join("\n");
-}
-
-function listRecipes(demosRoot: string, sources: ContextBundleSource[]): string {
-  const recipesDir = resolve(demosRoot, "recipes");
-  if (!existsSync(recipesDir)) return "_(recipes directory not found)_";
-  const files = readdirSync(recipesDir)
-    .filter((name) => name.endsWith(".md") && name !== "INDEX.md")
-    .sort();
-  const rows: string[] = [];
-  for (const file of files) {
-    const path = join(recipesDir, file);
-    const text = readFileSync(path, "utf-8");
-    sources.push({ path, bytes: Buffer.byteLength(text, "utf-8") });
-    const title = firstHeading(text) ?? basename(file, ".md");
-    rows.push(`- [${file}](demos/walkthroughs/${file}) — ${title}`);
-  }
-  return rows.join("\n");
-}
-
-function firstHeading(markdown: string): string | undefined {
-  for (const rawLine of markdown.split("\n")) {
-    const line = rawLine.trim();
-    if (line.startsWith("# ")) return line.slice(2).trim();
-  }
-  return undefined;
-}
-
-export type DiscoverRootsOpts = {
-  readonly startDir?: string;
-  readonly env?: NodeJS.ProcessEnv;
-};
-
-export type DiscoveredRoots = {
-  readonly factoryRoot: string;
-  readonly docsRoot: string;
-  readonly demosRoot: string;
-};
-
-export function discoverRoots(opts: DiscoverRootsOpts = {}): DiscoveredRoots {
-  const env = opts.env ?? process.env;
-  const factoryRoot = resolveRoot(
-    env["CREWHAUS_FACTORY_ROOT"],
-    "factory",
-    ["packages/spec/src/index.ts"],
-    opts.startDir,
-  );
-  const docsRoot = resolveRoot(
-    env["CREWHAUS_DOCS_ROOT"],
-    "docs",
-    ["GETTING-STARTED.md", "MODULE-CATALOG.md"],
-    opts.startDir,
-  );
-  const demosRoot = resolveRoot(
-    env["CREWHAUS_DEMOS_ROOT"],
-    "demos",
-    ["recipes/INDEX.md"],
-    opts.startDir,
-  );
-  return { factoryRoot, docsRoot, demosRoot };
-}
-
-function resolveRoot(
-  envValue: string | undefined,
-  siblingName: string,
-  markers: readonly string[],
-  startDir: string | undefined,
-): string {
-  if (envValue !== undefined && envValue !== "") {
-    const abs = resolve(envValue);
-    assertMarkers(abs, markers, `${envValue} (from env)`);
-    return abs;
-  }
-  const found = walkUpForSibling(startDir ?? process.cwd(), siblingName, markers);
-  if (found !== undefined) return found;
-  throw new Error(
-    `Could not locate ${siblingName}/ with markers ${markers.join(", ")}. ` +
-      `Set CREWHAUS_${siblingName.toUpperCase()}_ROOT or run from inside a CrewHaus checkout.`,
-  );
-}
-
-function assertMarkers(root: string, markers: readonly string[], label: string): void {
-  for (const marker of markers) {
-    if (!existsSync(resolve(root, marker))) {
-      throw new Error(`${label} is missing required file: ${marker}`);
-    }
-  }
-}
-
-function walkUpForSibling(
-  from: string,
-  siblingName: string,
-  markers: readonly string[],
-): string | undefined {
-  let current = resolve(from);
-  let parent = resolve(current, "..");
-  for (; ; current = parent, parent = resolve(current, "..")) {
-    const candidate = resolve(current, siblingName);
-    if (existsSync(candidate) && markers.every((m) => existsSync(resolve(candidate, m)))) {
-      return candidate;
-    }
-    if (parent === current) break;
-  }
-  return undefined;
-}