mdcontext 0.0.1 → 0.1.0

package/dist/cli/main.js

@@ -0,0 +1,2015 @@
+#!/usr/bin/env node
+import {
+  watchDirectory
+} from "../chunk-KRYIFLQR.js";
+import {
+  assembleContext,
+  buildEmbeddings,
+  estimateEmbeddingCost,
+  formatAssembledContext,
+  formatSummary,
+  getEmbeddingStats,
+  handleApiKeyError,
+  isAdvancedQuery,
+  search,
+  searchContent,
+  semanticSearch,
+  summarizeFile
+} from "../chunk-VVTGZNBT.js";
+import {
+  buildIndex,
+  createStorage,
+  getIncomingLinks,
+  getOutgoingLinks,
+  loadDocumentIndex,
+  loadSectionIndex,
+  parseFile
+} from "../chunk-S7E6TFX6.js";
+
+// src/cli/main.ts
+import { CliConfig, Command as Command8 } from "@effect/cli";
+import { NodeContext, NodeRuntime } from "@effect/platform-node";
+import { Effect as Effect8, Layer } from "effect";
+
+// src/cli/flag-schemas.ts
+var jsonFlag = {
+  name: "json",
+  type: "boolean",
+  description: "Output as JSON"
+};
+var prettyFlag = {
+  name: "pretty",
+  type: "boolean",
+  description: "Pretty-print JSON output"
+};
+var forceFlag = {
+  name: "force",
+  type: "boolean",
+  description: "Force full rebuild"
+};
+var rootFlag = {
+  name: "root",
+  type: "string",
+  alias: "r",
+  description: "Root directory"
+};
+var indexSchema = {
+  name: "index",
+  flags: [
+    {
+      name: "embed",
+      type: "boolean",
+      alias: "e",
+      description: "Build semantic embeddings"
+    },
+    {
+      name: "no-embed",
+      type: "boolean",
+      description: "Skip semantic search prompt"
+    },
+    {
+      name: "watch",
+      type: "boolean",
+      alias: "w",
+      description: "Watch for changes"
+    },
+    forceFlag,
+    jsonFlag,
+    prettyFlag
+  ]
+};
+var searchSchema = {
+  name: "search",
+  flags: [
+    {
+      name: "keyword",
+      type: "boolean",
+      alias: "k",
+      description: "Force keyword search"
+    },
+    {
+      name: "heading-only",
+      type: "boolean",
+      alias: "H",
+      description: "Search headings only"
+    },
+    {
+      name: "mode",
+      type: "string",
+      alias: "m",
+      description: "Force search mode (semantic or keyword)"
+    },
+    {
+      name: "limit",
+      type: "string",
+      alias: "n",
+      description: "Maximum results"
+    },
+    { name: "threshold", type: "string", description: "Similarity threshold" },
+    {
+      name: "context",
+      type: "string",
+      alias: "C",
+      description: "Lines of context around matches (like grep -C)"
+    },
+    {
+      name: "before-context",
+      type: "string",
+      alias: "B",
+      description: "Lines of context before matches (like grep -B)"
+    },
+    {
+      name: "after-context",
+      type: "string",
+      alias: "A",
+      description: "Lines of context after matches (like grep -A)"
+    },
+    jsonFlag,
+    prettyFlag
+  ]
+};
+var contextSchema = {
+  name: "context",
+  flags: [
+    { name: "tokens", type: "string", alias: "t", description: "Token budget" },
+    { name: "brief", type: "boolean", description: "Minimal output" },
+    { name: "full", type: "boolean", description: "Include full content" },
+    {
+      name: "section",
+      type: "string",
+      alias: "S",
+      description: "Filter by section name, number, or glob pattern"
+    },
+    {
+      name: "sections",
+      type: "boolean",
+      description: "List available sections"
+    },
+    {
+      name: "shallow",
+      type: "boolean",
+      description: "Exclude nested subsections when filtering"
+    },
+    jsonFlag,
+    prettyFlag
+  ]
+};
+var treeSchema = {
+  name: "tree",
+  flags: [jsonFlag, prettyFlag]
+};
+var linksSchema = {
+  name: "links",
+  flags: [rootFlag, jsonFlag, prettyFlag]
+};
+var backlinksSchema = {
+  name: "backlinks",
+  flags: [rootFlag, jsonFlag, prettyFlag]
+};
+var statsSchema = {
+  name: "stats",
+  flags: [jsonFlag, prettyFlag]
+};
+var commandSchemas = {
+  index: indexSchema,
+  search: searchSchema,
+  context: contextSchema,
+  tree: treeSchema,
+  links: linksSchema,
+  backlinks: backlinksSchema,
+  stats: statsSchema
+};
+var getCommandSchema = (commandName) => {
+  return commandSchemas[commandName];
+};
+var getValidFlags = (schema) => {
+  const flags = /* @__PURE__ */ new Set();
+  for (const spec of schema.flags) {
+    flags.add(`--${spec.name}`);
+    if (spec.alias) {
+      flags.add(`-${spec.alias}`);
+    }
+  }
+  return flags;
+};
+var flagTakesValue = (schema, flag) => {
+  if (flag.includes("=")) {
+    return false;
+  }
+  for (const spec of schema.flags) {
+    if (flag === `--${spec.name}` || spec.alias && flag === `-${spec.alias}`) {
+      return spec.type === "string";
+    }
+  }
+  return false;
+};
+
+// src/cli/typo-suggester.ts
+var levenshteinDistance = (a, b) => {
+  const matrix = [];
+  for (let i = 0; i <= a.length; i++) {
+    matrix[i] = [i];
+  }
+  for (let j = 0; j <= b.length; j++) {
+    matrix[0][j] = j;
+  }
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      matrix[i][j] = Math.min(
+        matrix[i - 1][j] + 1,
+        // deletion
+        matrix[i][j - 1] + 1,
+        // insertion
+        matrix[i - 1][j - 1] + cost
+        // substitution
+      );
+    }
+  }
+  return matrix[a.length][b.length];
+};
+var suggestFlag = (typo, schema, maxDistance = 2) => {
+  const normalizedTypo = typo.replace(/^-+/, "");
+  let bestMatch;
+  let bestDistance = Infinity;
+  for (const spec of schema.flags) {
+    const flagName = spec.name;
+    const distance = levenshteinDistance(normalizedTypo, flagName);
+    if (distance <= maxDistance && distance < bestDistance) {
+      bestDistance = distance;
+      bestMatch = {
+        flag: `--${spec.name}`,
+        distance,
+        description: spec.description
+      };
+    }
+    if (spec.alias) {
+      const aliasDistance = levenshteinDistance(normalizedTypo, spec.alias);
+      if (aliasDistance <= maxDistance && aliasDistance < bestDistance) {
+        bestDistance = aliasDistance;
+        bestMatch = {
+          flag: `--${spec.name}`,
+          distance: aliasDistance,
+          description: spec.description
+        };
+      }
+    }
+  }
+  if (!bestMatch || bestDistance > 0) {
+    for (const spec of schema.flags) {
+      if (spec.name.startsWith(normalizedTypo)) {
+        const prefixDistance = spec.name.length - normalizedTypo.length;
+        if (prefixDistance <= maxDistance && prefixDistance < bestDistance) {
+          bestDistance = prefixDistance;
+          bestMatch = {
+            flag: `--${spec.name}`,
+            distance: prefixDistance,
+            description: spec.description
+          };
+        }
+      }
+    }
+  }
+  return bestMatch;
+};
+var formatValidFlags = (schema) => {
+  const lines = [];
+  for (const spec of schema.flags) {
+    const alias = spec.alias ? `, -${spec.alias}` : "";
+    const desc = spec.description ? `  ${spec.description}` : "";
+    lines.push(`  --${spec.name}${alias}${desc}`);
+  }
+  return lines.join("\n");
+};
+
+// src/cli/argv-preprocessor.ts
+var isFlag = (arg) => {
+  return arg.startsWith("-");
+};
+var extractFlagName = (arg) => {
+  const eqIndex = arg.indexOf("=");
+  return eqIndex >= 0 ? arg.slice(0, eqIndex) : arg;
+};
+var validateFlag = (flag, schema) => {
+  const flagName = extractFlagName(flag);
+  const validFlags = getValidFlags(schema);
+  if (validFlags.has(flagName)) {
+    return void 0;
+  }
+  const suggestion = suggestFlag(flagName, schema);
+  let errorMsg = `Unknown option '${flagName}' for '${schema.name}'`;
+  if (suggestion) {
+    errorMsg += `
+Did you mean '${suggestion.flag}'?`;
+  }
+  errorMsg += `
+
+Valid options for '${schema.name}':
+${formatValidFlags(schema)}`;
+  return errorMsg;
+};
+var preprocessArgv = (argv) => {
+  const result = preprocessArgvWithValidation(argv);
+  if (result.error) {
+    console.error(`
+Error: ${result.error}`);
+    console.error('\nRun "mdcontext <command> --help" for usage information.');
+    process.exit(1);
+  }
+  return result.argv;
+};
+var preprocessArgvWithValidation = (argv) => {
+  const nodeAndScript = argv.slice(0, 2);
+  const userArgs = argv.slice(2);
+  if (userArgs.length === 0) {
+    return { argv };
+  }
+  const firstArg = userArgs[0];
+  if (!firstArg || isFlag(firstArg)) {
+    return { argv };
+  }
+  const subcommand = firstArg;
+  const restArgs = userArgs.slice(1);
+  const schema = getCommandSchema(subcommand);
+  if (!schema) {
+    return { argv };
+  }
+  const flags = [];
+  const positionals = [];
+  let i = 0;
+  while (i < restArgs.length) {
+    const arg = restArgs[i];
+    if (!arg) {
+      i++;
+      continue;
+    }
+    if (isFlag(arg)) {
+      if (arg === "--help" || arg === "-h") {
+        flags.push(arg);
+        i++;
+        continue;
+      }
+      if (arg === "--") {
+        i++;
+        while (i < restArgs.length) {
+          const remaining = restArgs[i];
+          if (remaining) positionals.push(remaining);
+          i++;
+        }
+        continue;
+      }
+      const error = validateFlag(arg, schema);
+      if (error) {
+        return { argv, error };
+      }
+      if (arg.includes("=")) {
+        flags.push(arg);
+        i++;
+      } else if (flagTakesValue(schema, arg)) {
+        flags.push(arg);
+        i++;
+        if (i < restArgs.length) {
+          const nextArg = restArgs[i];
+          if (nextArg && !isFlag(nextArg)) {
+            flags.push(nextArg);
+            i++;
+          }
+        }
+      } else {
+        flags.push(arg);
+        i++;
+      }
+    } else {
+      positionals.push(arg);
+      i++;
+    }
+  }
+  return {
+    argv: [...nodeAndScript, subcommand, ...flags, ...positionals]
+  };
+};
+
+// src/cli/commands/backlinks.ts
+import * as path2 from "path";
+import { Args, Command, Options as Options2 } from "@effect/cli";
+import { Console, Effect } from "effect";
+
+// src/cli/options.ts
+import { Options } from "@effect/cli";
+var jsonOption = Options.boolean("json").pipe(
+  Options.withDescription("Output as JSON"),
+  Options.withDefault(false)
+);
+var prettyOption = Options.boolean("pretty").pipe(
+  Options.withDescription("Pretty-print JSON output"),
+  Options.withDefault(true)
+);
+var forceOption = Options.boolean("force").pipe(
+  Options.withDescription("Force full rebuild, ignoring cache"),
+  Options.withDefault(false)
+);
+
+// src/cli/utils.ts
+import * as fsPromises from "fs/promises";
+import * as path from "path";
+var formatJson = (obj, pretty) => {
+  return pretty ? JSON.stringify(obj, null, 2) : JSON.stringify(obj);
+};
+var isMarkdownFile = (filename) => {
+  return filename.endsWith(".md") || filename.endsWith(".mdx");
+};
+var walkDir = async (dir) => {
+  const files = [];
+  const entries = await fsPromises.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.name.startsWith(".") || entry.name === "node_modules") {
+      continue;
+    }
+    if (entry.isDirectory()) {
+      const subFiles = await walkDir(fullPath);
+      files.push(...subFiles);
+    } else if (entry.isFile() && isMarkdownFile(entry.name)) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+};
+var isRegexPattern = (query) => {
+  return /[.*+?^${}()|[\]\\]/.test(query);
+};
+var hasEmbeddings = async (dir) => {
+  const vectorsPath = path.join(dir, ".mdcontext", "vectors.bin");
+  try {
+    await fsPromises.access(vectorsPath);
+    return true;
+  } catch {
+    return false;
+  }
+};
+var getIndexInfo = async (dir) => {
+  const sectionsPath = path.join(dir, ".mdcontext", "indexes", "sections.json");
+  const vectorsMetaPath = path.join(dir, ".mdcontext", "vectors.meta.json");
+  let exists = false;
+  let lastUpdated;
+  let sectionCount;
+  let embeddingsExist = false;
+  let vectorCount;
+  try {
+    const stat2 = await fsPromises.stat(sectionsPath);
+    exists = true;
+    lastUpdated = stat2.mtime.toISOString();
+    const content = await fsPromises.readFile(sectionsPath, "utf-8");
+    const sections = JSON.parse(content);
+    sectionCount = Object.keys(sections.sections || {}).length;
+  } catch {
+  }
+  try {
+    const content = await fsPromises.readFile(vectorsMetaPath, "utf-8");
+    const meta = JSON.parse(content);
+    embeddingsExist = true;
+    vectorCount = Object.keys(meta.entries || {}).length;
+    if (meta.updatedAt) {
+      lastUpdated = meta.updatedAt;
+    }
+  } catch {
+  }
+  return {
+    exists,
+    lastUpdated,
+    sectionCount,
+    embeddingsExist,
+    vectorCount
+  };
+};
+
+// src/cli/commands/backlinks.ts
+var backlinksCommand = Command.make(
+  "backlinks",
+  {
+    file: Args.file({ name: "file" }).pipe(
+      Args.withDescription("Markdown file to find references to")
+    ),
+    root: Options2.directory("root").pipe(
+      Options2.withAlias("r"),
+      Options2.withDescription("Root directory for resolving relative links"),
+      Options2.withDefault(".")
+    ),
+    json: jsonOption,
+    pretty: prettyOption
+  },
+  ({ file, root, json, pretty }) => Effect.gen(function* () {
+    const resolvedRoot = path2.resolve(root);
+    const resolvedFile = path2.resolve(file);
+    const relativePath = path2.relative(resolvedRoot, resolvedFile);
+    const links = yield* getIncomingLinks(resolvedRoot, resolvedFile);
+    if (json) {
+      yield* Console.log(
+        formatJson({ file: relativePath, backlinks: links }, pretty)
+      );
+    } else {
+      yield* Console.log(`Incoming links to ${relativePath}:`);
+      yield* Console.log("");
+      if (links.length === 0) {
+        yield* Console.log("  (none)");
+      } else {
+        for (const link of links) {
+          yield* Console.log(`  <- ${link}`);
+        }
+      }
+      yield* Console.log("");
+      yield* Console.log(`Total: ${links.length} backlinks`);
+    }
+  })
+).pipe(Command.withDescription("What links to this?"));
+
+// src/cli/commands/context.ts
+import * as path3 from "path";
+import { Args as Args2, Command as Command2, Options as Options3 } from "@effect/cli";
+import { Console as Console2, Effect as Effect2 } from "effect";
+
+// src/parser/section-filter.ts
+var globMatch = (text, pattern) => {
+  const regexPattern = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+  const regex = new RegExp(`^${regexPattern}$`, "i");
+  return regex.test(text);
+};
+var buildSectionList = (document) => {
+  const result = [];
+  const processSection = (section, prefix, index) => {
+    const number = prefix ? `${prefix}.${index + 1}` : `${index + 1}`;
+    result.push({
+      number,
+      heading: section.heading,
+      level: section.level,
+      tokenCount: section.metadata.tokenCount
+    });
+    section.children.forEach((child, i) => {
+      processSection(child, number, i);
+    });
+  };
+  document.sections.forEach((section, i) => {
+    processSection(section, "", i);
+  });
+  return result;
+};
+var formatSectionList = (sections) => {
+  const lines = [];
+  for (const section of sections) {
+    const depth = (section.number.match(/\./g) || []).length;
+    const indent = "   ".repeat(depth);
+    lines.push(
+      `${indent}${section.number}. ${section.heading} (${section.tokenCount} tokens)`
+    );
+  }
+  return lines.join("\n");
+};
+var matchesSelector = (section, selector) => {
+  if (/^[\d.]+$/.test(selector)) {
+    return section.number === selector;
+  }
+  if (section.heading.toLowerCase() === selector.toLowerCase()) {
+    return true;
+  }
+  if (selector.includes("*") || selector.includes("?")) {
+    return globMatch(section.heading, selector);
+  }
+  return section.heading.toLowerCase().includes(selector.toLowerCase());
+};
+var findMatchingSections = (sectionList, selector) => {
+  return sectionList.filter((s) => matchesSelector(s, selector));
+};
+var getDescendantNumbers = (sectionList, parentNumber) => {
+  const result = /* @__PURE__ */ new Set();
+  const prefix = `${parentNumber}.`;
+  for (const section of sectionList) {
+    if (section.number.startsWith(prefix)) {
+      result.add(section.number);
+    }
+  }
+  return result;
+};
+var extractSectionContent = (document, selector, options = {}) => {
+  const sectionList = buildSectionList(document);
+  const matchedSections = findMatchingSections(sectionList, selector);
+  if (matchedSections.length === 0) {
+    return { sections: [], matchedNumbers: [] };
+  }
+  const numbersToInclude = /* @__PURE__ */ new Set();
+  const matchedNumbers = [];
+  for (const matched of matchedSections) {
+    numbersToInclude.add(matched.number);
+    matchedNumbers.push(matched.number);
+    if (!options.shallow) {
+      const descendants = getDescendantNumbers(sectionList, matched.number);
+      for (const desc of descendants) {
+        numbersToInclude.add(desc);
+      }
+    }
+  }
+  const numberToSection = /* @__PURE__ */ new Map();
+  const mapSections = (sections, prefix) => {
+    sections.forEach((section, i) => {
+      const number = prefix ? `${prefix}.${i + 1}` : `${i + 1}`;
+      numberToSection.set(number, section);
+      mapSections(section.children, number);
+    });
+  };
+  mapSections(document.sections, "");
+  const extractedSections = [];
+  for (const number of matchedNumbers) {
+    const section = numberToSection.get(number);
+    if (section) {
+      if (options.shallow) {
+        extractedSections.push({
+          ...section,
+          children: []
+        });
+      } else {
+        extractedSections.push(section);
+      }
+    }
+  }
+  return { sections: extractedSections, matchedNumbers };
+};
+var formatExtractedSections = (sections) => {
+  const formatSection = (section, includeChildren) => {
+    const lines = [];
+    const headingPrefix = "#".repeat(section.level);
+    lines.push(`${headingPrefix} ${section.heading}`);
+    lines.push("");
+    const contentLines = section.content.split("\n");
+    const contentWithoutHeading = contentLines.filter((line, i) => i > 0 || !line.startsWith("#")).join("\n").trim();
+    if (contentWithoutHeading) {
+      lines.push(contentWithoutHeading);
+    }
+    if (includeChildren) {
+      for (const child of section.children) {
+        lines.push("");
+        lines.push(formatSection(child, true));
+      }
+    }
+    return lines.join("\n");
+  };
+  return sections.map((s) => formatSection(s, true)).join("\n\n");
+};
+
+// src/cli/commands/context.ts
+var contextCommand = Command2.make(
+  "context",
+  {
+    files: Args2.file({ name: "files" }).pipe(
+      Args2.withDescription("Markdown file(s) to summarize"),
+      Args2.repeated
+    ),
+    tokens: Options3.integer("tokens").pipe(
+      Options3.withAlias("t"),
+      Options3.withDescription("Token budget"),
+      Options3.withDefault(2e3)
+    ),
+    brief: Options3.boolean("brief").pipe(
+      Options3.withDescription("Minimal output"),
+      Options3.withDefault(false)
+    ),
+    full: Options3.boolean("full").pipe(
+      Options3.withDescription("Include full content"),
+      Options3.withDefault(false)
+    ),
+    section: Options3.text("section").pipe(
+      Options3.withAlias("S"),
+      Options3.withDescription(
+        'Filter by section name, number (e.g., "5.3"), or glob pattern (e.g., "Memory*")'
+      ),
+      Options3.optional
+    ),
+    sections: Options3.boolean("sections").pipe(
+      Options3.withDescription("List available sections"),
+      Options3.withDefault(false)
+    ),
+    shallow: Options3.boolean("shallow").pipe(
+      Options3.withDescription("Exclude nested subsections when filtering"),
+      Options3.withDefault(false)
+    ),
+    json: jsonOption,
+    pretty: prettyOption
+  },
+  ({ files, tokens, brief, full, section, sections, shallow, json, pretty }) => Effect2.gen(function* () {
+    const fileList = Array.isArray(files) ? files : [];
+    if (fileList.length === 0) {
+      yield* Effect2.fail(
+        new Error(
+          "At least one file is required. Usage: mdcontext context <file> [files...]"
+        )
+      );
+    }
+    const sectionSelector = section._tag === "Some" ? section.value : void 0;
+    if (sections) {
+      for (const file of fileList) {
+        const filePath = path3.resolve(file);
+        const document = yield* parseFile(filePath).pipe(
+          Effect2.mapError((e) => new Error(`${e._tag}: ${e.message}`))
+        );
+        const sectionList = buildSectionList(document);
+        if (json) {
+          const output = {
+            path: filePath,
+            title: document.title,
+            sections: sectionList.map((s) => ({
+              number: s.number,
+              heading: s.heading,
+              level: s.level,
+              tokens: s.tokenCount
+            }))
+          };
+          yield* Console2.log(formatJson(output, pretty));
+        } else {
+          yield* Console2.log(`# ${document.title}`);
+          yield* Console2.log(`Path: ${filePath}`);
+          yield* Console2.log("");
+          yield* Console2.log("Available sections:");
+          yield* Console2.log(formatSectionList(sectionList));
+        }
+      }
+      return;
+    }
+    if (sectionSelector) {
+      for (const file of fileList) {
+        const filePath = path3.resolve(file);
+        const document = yield* parseFile(filePath).pipe(
+          Effect2.mapError((e) => new Error(`${e._tag}: ${e.message}`))
+        );
+        const { sections: extractedSections, matchedNumbers } = extractSectionContent(document, sectionSelector, { shallow });
+        if (extractedSections.length === 0) {
+          yield* Console2.error(
+            `No sections found matching "${sectionSelector}" in ${file}`
+          );
+          yield* Console2.error("Use --sections to list available sections.");
+          continue;
+        }
+        if (json) {
+          const output = {
+            path: filePath,
+            title: document.title,
+            selector: sectionSelector,
+            shallow,
+            matchedSections: matchedNumbers,
+            content: formatExtractedSections(extractedSections),
+            sections: extractedSections.map((s) => ({
+              heading: s.heading,
+              level: s.level,
+              tokens: s.metadata.tokenCount
+            }))
+          };
+          yield* Console2.log(formatJson(output, pretty));
+        } else {
+          yield* Console2.log(`# ${document.title}`);
+          yield* Console2.log(`Path: ${filePath}`);
+          yield* Console2.log(`Sections: ${matchedNumbers.join(", ")}`);
+          yield* Console2.log("");
+          yield* Console2.log(formatExtractedSections(extractedSections));
+        }
+      }
+      return;
+    }
+    const level = full ? "full" : brief ? "brief" : "summary";
+    const effectiveMaxTokens = full ? void 0 : tokens;
+    const firstFile = fileList[0];
+    if (fileList.length === 1 && firstFile) {
+      const filePath = path3.resolve(firstFile);
+      const summary = yield* summarizeFile(filePath, {
+        level,
+        maxTokens: effectiveMaxTokens
+      });
+      if (json) {
+        yield* Console2.log(formatJson(summary, pretty));
+      } else {
+        yield* Console2.log(
+          formatSummary(summary, { maxTokens: effectiveMaxTokens })
+        );
+      }
+    } else {
+      const root = process.cwd();
+      const assembled = yield* assembleContext(root, fileList, {
+        budget: full ? Number.MAX_SAFE_INTEGER : tokens,
+        level
+      });
+      if (json) {
+        yield* Console2.log(formatJson(assembled, pretty));
+      } else {
+        yield* Console2.log(formatAssembledContext(assembled));
+      }
+    }
+  })
+).pipe(Command2.withDescription("Get LLM-ready summary"));
+
+// src/cli/commands/index-cmd.ts
+import * as path4 from "path";
+import * as readline from "readline";
+import { Args as Args3, Command as Command3, Options as Options4 } from "@effect/cli";
+import { Console as Console3, Effect as Effect3 } from "effect";
+var promptUser = (message) => {
+  return new Promise((resolve8) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    rl.question(message, (answer) => {
+      rl.close();
+      resolve8(answer.trim().toLowerCase());
+    });
+  });
+};
+var indexCommand = Command3.make(
+  "index",
+  {
+    path: Args3.directory({ name: "path" }).pipe(
+      Args3.withDescription("Directory to index"),
+      Args3.withDefault(".")
+    ),
+    embed: Options4.boolean("embed").pipe(
+      Options4.withAlias("e"),
+      Options4.withDescription("Also build semantic embeddings"),
+      Options4.withDefault(false)
+    ),
+    noEmbed: Options4.boolean("no-embed").pipe(
+      Options4.withDescription("Skip semantic search prompt"),
+      Options4.withDefault(false)
+    ),
+    exclude: Options4.text("exclude").pipe(
+      Options4.withAlias("x"),
+      Options4.withDescription(
+        "Exclude files matching patterns (comma-separated globs)"
+      ),
+      Options4.optional
+    ),
+    watch: Options4.boolean("watch").pipe(
+      Options4.withAlias("w"),
+      Options4.withDescription("Watch for changes"),
+      Options4.withDefault(false)
+    ),
+    force: forceOption,
+    json: jsonOption,
+    pretty: prettyOption
+  },
+  ({
+    path: dirPath,
+    embed,
+    noEmbed,
+    exclude,
+    watch: watchMode,
+    force,
+    json,
+    pretty
+  }) => Effect3.gen(function* () {
+    const resolvedDir = path4.resolve(dirPath);
+    const excludePatterns = exclude._tag === "Some" ? exclude.value.split(",").map((p) => p.trim()) : void 0;
+    if (watchMode) {
+      yield* Console3.log(`Watching ${resolvedDir} for changes...`);
+      yield* Console3.log("Press Ctrl+C to stop.");
+      yield* Console3.log("");
+      const watcher = yield* watchDirectory(resolvedDir, {
+        force,
+        onIndex: (result) => {
+          if (json) {
+            console.log(formatJson(result, pretty));
+          } else {
+            console.log(
+              `Re-indexed ${result.documentsIndexed} documents (${result.duration}ms)`
+            );
+          }
+        },
+        onError: (error) => {
+          console.error(`Watch error: ${error.message}`);
+        }
+      });
+      yield* Effect3.async(() => {
+        process.on("SIGINT", () => {
+          watcher.stop();
+          console.log("\nStopped watching.");
+          process.exit(0);
+        });
+      });
+    } else {
+      yield* Console3.log(`Indexing ${resolvedDir}...`);
+      const result = yield* buildIndex(resolvedDir, { force });
+      if (!json) {
+        yield* Console3.log("");
+        const newlyIndexed = result.documentsIndexed < result.totalDocuments ? ` (${result.documentsIndexed} updated)` : "";
+        yield* Console3.log(
+          `Indexed ${result.totalDocuments} documents${newlyIndexed}`
+        );
+        yield* Console3.log(`  Sections: ${result.totalSections}`);
+        yield* Console3.log(`  Links: ${result.totalLinks}`);
+        yield* Console3.log(`  Duration: ${result.duration}ms`);
+        if (result.errors.length > 0) {
+          yield* Console3.log("");
+          yield* Console3.log(`Errors (${result.errors.length}):`);
+          for (const error of result.errors) {
+            yield* Console3.log(`  ${error.path}: ${error.message}`);
+          }
+        }
+      }
+      const embedsExist = yield* Effect3.promise(
+        () => hasEmbeddings(resolvedDir)
+      );
+      if (embed) {
+        yield* Console3.log("");
+        const estimate = yield* estimateEmbeddingCost(resolvedDir, {
+          excludePatterns
+        }).pipe(handleApiKeyError);
+        if (!json) {
+          yield* Console3.log(`Found ${estimate.totalFiles} files to embed:`);
+          for (const dir of estimate.byDirectory) {
+            const costStr = dir.estimatedCost < 1e-3 ? "<$0.001" : `~$${dir.estimatedCost.toFixed(4)}`;
+            yield* Console3.log(
+              `  ${dir.directory.padEnd(20)} ${String(dir.fileCount).padStart(3)} files   ${costStr}`
+            );
+          }
+          yield* Console3.log("");
+          yield* Console3.log(
+            `Total: ~${estimate.totalTokens.toLocaleString()} tokens, ~$${estimate.totalCost.toFixed(4)}, ~${estimate.estimatedTimeSeconds}s`
+          );
+          yield* Console3.log("");
+        }
+        if (!force) {
+          yield* Console3.log("Checking embeddings...");
+        } else {
+          yield* Console3.log("Rebuilding embeddings (--force specified)...");
+        }
+        const embedResult = yield* buildEmbeddings(resolvedDir, {
+          force,
+          excludePatterns,
+          onFileProgress: (progress) => {
+            if (!json) {
+              process.stdout.write(
+                `\r  [${progress.fileIndex}/${progress.totalFiles}] ${progress.filePath} (${progress.sectionCount} sections)...`
+              );
+            }
+          }
+        }).pipe(handleApiKeyError);
+        if (!json) {
+          process.stdout.write(`\r${" ".repeat(80)}\r`);
+          yield* Console3.log("");
+          if (embedResult.cacheHit) {
+            yield* Console3.log(
+              `Embeddings already exist (${embedResult.existingVectors} vectors)`
+            );
+            yield* Console3.log("  Use --force to rebuild");
+            yield* Console3.log("");
+            yield* Console3.log(
+              `Skipped embedding generation (saved ~$${(embedResult.estimatedSavings ?? 0).toFixed(4)})`
+            );
+          } else {
+            yield* Console3.log(
+              `Completed in ${(embedResult.duration / 1e3).toFixed(1)}s`
+            );
+            yield* Console3.log(`  Files: ${embedResult.filesProcessed}`);
+            yield* Console3.log(`  Sections: ${embedResult.sectionsEmbedded}`);
+            yield* Console3.log(
+              `  Tokens: ${embedResult.tokensUsed.toLocaleString()}`
+            );
+            yield* Console3.log(`  Cost: $${embedResult.cost.toFixed(6)}`);
+          }
+        }
+      } else if (!noEmbed && !embedsExist && !json) {
+        yield* Console3.log("");
+        yield* Console3.log(
+          "Enable semantic search? This allows natural language queries like:"
+        );
+        yield* Console3.log(
+          '  "how does authentication work" instead of exact keyword matches'
+        );
+        yield* Console3.log("");
+        const estimate = yield* estimateEmbeddingCost(resolvedDir).pipe(
+          Effect3.catchAll(() => Effect3.succeed(null))
+        );
+        if (estimate) {
+          yield* Console3.log(
+            `Cost: ~$${estimate.totalCost.toFixed(4)} for this corpus (~${estimate.estimatedTimeSeconds}s)`
+          );
+        }
+        yield* Console3.log("Requires: OPENAI_API_KEY environment variable");
+        yield* Console3.log("");
+        const answer = yield* Effect3.promise(
+          () => promptUser("Create semantic index? [y/N]: ")
+        );
+        if (answer === "y" || answer === "yes") {
+          if (!process.env.OPENAI_API_KEY) {
+            yield* Console3.log("");
+            yield* Console3.log("OPENAI_API_KEY not set.");
+            yield* Console3.log("");
+            yield* Console3.log(
+              "To enable semantic search, set your OpenAI API key:"
+            );
+            yield* Console3.log("  export OPENAI_API_KEY=sk-...");
+            yield* Console3.log("");
+            yield* Console3.log("Or add to .env file in project root.");
+          } else {
+            yield* Console3.log("");
+            yield* Console3.log("Building embeddings...");
+            const embedResult = yield* buildEmbeddings(resolvedDir, {
+              force: false,
+              onFileProgress: (progress) => {
+                process.stdout.write(
+                  `\r  [${progress.fileIndex}/${progress.totalFiles}] ${progress.filePath} (${progress.sectionCount} sections)...`
+                );
+              }
+            }).pipe(
+              handleApiKeyError,
+              Effect3.catchAll(() => Effect3.succeed(null))
+            );
+            if (embedResult) {
+              process.stdout.write(`\r${" ".repeat(80)}\r`);
+              yield* Console3.log("");
+              yield* Console3.log(
+                `Completed in ${(embedResult.duration / 1e3).toFixed(1)}s`
+              );
+              yield* Console3.log(`  Files: ${embedResult.filesProcessed}`);
+              yield* Console3.log(
+                `  Sections: ${embedResult.sectionsEmbedded}`
+              );
+              yield* Console3.log(
+                `  Tokens: ${embedResult.tokensUsed.toLocaleString()}`
+              );
+              yield* Console3.log(`  Cost: $${embedResult.cost.toFixed(6)}`);
+            }
+          }
+        }
+      }
+      if (json) {
+        yield* Console3.log(formatJson(result, pretty));
+      }
+    }
+  })
+).pipe(Command3.withDescription("Index markdown files"));
+
+// src/cli/commands/links.ts
+import * as path5 from "path";
+import { Args as Args4, Command as Command4, Options as Options5 } from "@effect/cli";
+import { Console as Console4, Effect as Effect4 } from "effect";
+var linksCommand = Command4.make(
+  "links",
+  {
+    file: Args4.file({ name: "file" }).pipe(
+      Args4.withDescription("Markdown file to analyze")
+    ),
+    root: Options5.directory("root").pipe(
+      Options5.withAlias("r"),
+      Options5.withDescription("Root directory for resolving relative links"),
+      Options5.withDefault(".")
+    ),
+    json: jsonOption,
+    pretty: prettyOption
+  },
+  ({ file, root, json, pretty }) => Effect4.gen(function* () {
+    const resolvedRoot = path5.resolve(root);
+    const resolvedFile = path5.resolve(file);
+    const relativePath = path5.relative(resolvedRoot, resolvedFile);
+    const links = yield* getOutgoingLinks(resolvedRoot, resolvedFile);
+    if (json) {
+      yield* Console4.log(formatJson({ file: relativePath, links }, pretty));
+    } else {
+      yield* Console4.log(`Outgoing links from ${relativePath}:`);
+      yield* Console4.log("");
+      if (links.length === 0) {
+        yield* Console4.log("  (none)");
+      } else {
+        for (const link of links) {
+          yield* Console4.log(`  -> ${link}`);
+        }
+      }
+      yield* Console4.log("");
+      yield* Console4.log(`Total: ${links.length} links`);
+    }
+  })
+).pipe(Command4.withDescription("What does this link to?"));
+
+// src/cli/commands/search.ts
+import * as path6 from "path";
+import * as readline2 from "readline";
+import { Args as Args5, Command as Command5, Options as Options6 } from "@effect/cli";
+import { Console as Console5, Effect as Effect5, Option } from "effect";
+var AUTO_INDEX_THRESHOLD_SECONDS = 10;
+var promptUser2 = (message) => {
+  return new Promise((resolve8) => {
+    const rl = readline2.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    rl.question(message, (answer) => {
+      rl.close();
+      resolve8(answer.trim().toLowerCase());
+    });
+  });
+};
+var searchCommand = Command5.make(
+  "search",
+  {
+    query: Args5.text({ name: "query" }).pipe(
+      Args5.withDescription("Search query (natural language or regex pattern)")
+    ),
+    path: Args5.directory({ name: "path" }).pipe(
+      Args5.withDescription("Directory to search in"),
+      Args5.withDefault(".")
+    ),
+    keyword: Options6.boolean("keyword").pipe(
+      Options6.withAlias("k"),
+      Options6.withDescription("Force keyword search (content text match)"),
+      Options6.withDefault(false)
+    ),
+    headingOnly: Options6.boolean("heading-only").pipe(
+      Options6.withAlias("H"),
+      Options6.withDescription("Search headings only (not content)"),
+      Options6.withDefault(false)
+    ),
+    mode: Options6.choice("mode", ["semantic", "keyword"]).pipe(
+      Options6.withAlias("m"),
+      Options6.withDescription("Force search mode: semantic or keyword"),
+      Options6.optional
+    ),
+    limit: Options6.integer("limit").pipe(
+      Options6.withAlias("n"),
+      Options6.withDescription("Maximum results"),
+      Options6.withDefault(10)
+    ),
+    threshold: Options6.float("threshold").pipe(
+      Options6.withDescription("Similarity threshold for semantic search (0-1)"),
+      Options6.withDefault(0.45)
+    ),
+    context: Options6.integer("context").pipe(
+      Options6.withAlias("C"),
+      Options6.withDescription("Lines of context around matches (like grep -C)"),
+      Options6.optional
+    ),
+    beforeContext: Options6.integer("before-context").pipe(
+      Options6.withAlias("B"),
+      Options6.withDescription("Lines of context before matches (like grep -B)"),
+      Options6.optional
+    ),
+    afterContext: Options6.integer("after-context").pipe(
+      Options6.withAlias("A"),
+      Options6.withDescription("Lines of context after matches (like grep -A)"),
+      Options6.optional
+    ),
+    autoIndexThreshold: Options6.integer("auto-index-threshold").pipe(
+      Options6.withDescription(
+        "Auto-create semantic index if estimated time is under this threshold (seconds)"
+      ),
+      Options6.withDefault(AUTO_INDEX_THRESHOLD_SECONDS)
+    ),
+    json: jsonOption,
+    pretty: prettyOption
+  },
+  ({
+    query,
+    path: dirPath,
+    keyword,
+    headingOnly,
+    mode,
+    limit,
+    threshold,
+    context,
+    beforeContext,
+    afterContext,
+    autoIndexThreshold,
+    json,
+    pretty
+  }) => Effect5.gen(function* () {
+    const resolvedDir = path6.resolve(dirPath);
+    const indexInfo = yield* Effect5.promise(() => getIndexInfo(resolvedDir));
+    if (!indexInfo.exists && !json) {
+      yield* Console5.log("No index found.");
+      yield* Console5.log("");
+      yield* Console5.log("Run: mdcontext index /path/to/docs");
+      yield* Console5.log("  Add --embed for semantic search capabilities");
+      return;
+    }
+    let embedsExist = indexInfo.embeddingsExist;
+    let useKeyword;
+    let modeReason;
+    const modeValue = Option.getOrUndefined(mode);
+    if (modeValue === "semantic") {
+      if (!embedsExist) {
+        embedsExist = yield* handleMissingEmbeddings(
+          resolvedDir,
+          autoIndexThreshold,
+          json
+        );
+        if (!embedsExist) {
+          return;
+        }
+      }
+      useKeyword = false;
+      modeReason = "--mode semantic";
+    } else if (modeValue === "keyword") {
+      useKeyword = true;
+      modeReason = "--mode keyword";
+    } else if (keyword) {
+      useKeyword = true;
+      modeReason = "--keyword flag";
+    } else if (isAdvancedQuery(query)) {
+      useKeyword = true;
+      modeReason = "boolean/phrase pattern detected";
+    } else if (isRegexPattern(query)) {
+      useKeyword = true;
+      modeReason = "regex pattern detected";
+    } else if (!embedsExist) {
+      useKeyword = true;
+      modeReason = "no embeddings";
+    } else {
+      useKeyword = false;
+      modeReason = "embeddings available";
+    }
+    const modeIndicator = useKeyword ? "[keyword]" : "[semantic]";
+    if (!json && indexInfo.lastUpdated) {
+      const lastUpdatedDate = new Date(indexInfo.lastUpdated);
+      const dateStr = lastUpdatedDate.toLocaleDateString("en-CA");
+      const timeStr = lastUpdatedDate.toLocaleTimeString("en-US", {
+        hour: "2-digit",
+        minute: "2-digit",
+        hour12: false
+      });
+      yield* Console5.log(`Using index from ${dateStr} ${timeStr}`);
+      yield* Console5.log(`  Sections: ${indexInfo.sectionCount ?? 0}`);
+      if (indexInfo.embeddingsExist) {
+        yield* Console5.log(
+          `  Embeddings: yes (${indexInfo.vectorCount ?? 0} vectors)`
+        );
+      } else {
+        yield* Console5.log("  Embeddings: no");
+      }
+      yield* Console5.log("");
+    }
+    const contextValue = Option.getOrUndefined(context);
+    const beforeValue = Option.getOrUndefined(beforeContext);
+    const afterValue = Option.getOrUndefined(afterContext);
+    const contextBefore = beforeValue ?? contextValue ?? 1;
+    const contextAfter = afterValue ?? contextValue ?? 1;
+    if (useKeyword) {
+      const results = headingOnly ? yield* search(resolvedDir, { heading: query, limit }) : yield* searchContent(resolvedDir, {
+        content: query,
+        limit,
+        contextBefore,
+        contextAfter
+      });
+      if (json) {
+        const output = {
+          mode: "keyword",
+          modeReason,
+          query,
+          contextBefore,
+          contextAfter,
+          results: results.map((r) => ({
+            path: r.section.documentPath,
+            heading: r.section.heading,
+            level: r.section.level,
+            tokens: r.section.tokenCount,
+            line: r.section.startLine,
+            matches: r.matches?.map((m) => ({
+              lineNumber: m.lineNumber,
+              line: m.line,
+              contextLines: m.contextLines
+            }))
+          }))
+        };
+        yield* Console5.log(formatJson(output, pretty));
+      } else {
+        const searchType = headingOnly ? "Heading" : "Content";
+        const showReason = modeReason !== "--mode keyword" && modeReason !== "--keyword flag";
+        const modeStr = showReason ? `${modeIndicator} (${modeReason})` : modeIndicator;
+        yield* Console5.log(`${modeStr} ${searchType} search: "${query}"`);
+        yield* Console5.log(`Results: ${results.length}`);
+        yield* Console5.log("");
+        for (const result of results) {
+          const levelMarker = "#".repeat(result.section.level);
+          yield* Console5.log(
+            `  ${result.section.documentPath}:${result.section.startLine}`
+          );
+          yield* Console5.log(
+            `    ${levelMarker} ${result.section.heading} (${result.section.tokenCount} tokens)`
+          );
+          if (result.matches && result.matches.length > 0) {
+            yield* Console5.log("");
+            for (const match of result.matches.slice(0, 3)) {
+              if (match.contextLines && match.contextLines.length > 0) {
+                for (const ctxLine of match.contextLines) {
+                  const marker = ctxLine.isMatch ? ">" : " ";
+                  yield* Console5.log(
+                    `  ${marker} ${ctxLine.lineNumber}: ${ctxLine.line}`
+                  );
+                }
+              } else {
+                yield* Console5.log(`    Line ${match.lineNumber}:`);
+                const snippetLines = match.snippet.split("\n");
+                for (const line of snippetLines) {
+                  yield* Console5.log(`      ${line}`);
+                }
+              }
+              yield* Console5.log("");
+            }
+            if (result.matches.length > 3) {
+              yield* Console5.log(
+                `    ... and ${result.matches.length - 3} more matches`
+              );
+            }
+          }
+          yield* Console5.log("");
+        }
+        if (!indexInfo.embeddingsExist) {
+          yield* Console5.log(
+            "Tip: Run 'mdcontext index --embed' to enable semantic search"
+          );
+        }
+      }
+    } else {
+      const results = yield* semanticSearch(resolvedDir, query, {
+        limit,
+        threshold
+      }).pipe(handleApiKeyError);
+      if (json) {
+        const output = {
+          mode: "semantic",
+          modeReason,
+          query,
+          results
+        };
+        yield* Console5.log(formatJson(output, pretty));
+      } else {
+        const showSemanticReason = modeReason !== "--mode semantic";
+        const semanticModeStr = showSemanticReason ? `${modeIndicator} (${modeReason})` : modeIndicator;
+        yield* Console5.log(`${semanticModeStr} Semantic search: "${query}"`);
+        yield* Console5.log(`Results: ${results.length}`);
+        yield* Console5.log("");
+        for (const result of results) {
+          const similarity = (result.similarity * 100).toFixed(1);
+          yield* Console5.log(`  ${result.documentPath}`);
+          yield* Console5.log(`    ${result.heading} (${similarity}% match)`);
+          yield* Console5.log("");
+        }
+        yield* Console5.log("Tip: Use --mode keyword for exact text matching");
+      }
+    }
+  })
+).pipe(Command5.withDescription("Search by meaning or structure"));
+var handleMissingEmbeddings = (resolvedDir, autoIndexThreshold, json) => Effect5.gen(function* () {
+  const estimate = yield* estimateEmbeddingCost(resolvedDir).pipe(
+    Effect5.catchAll(() => Effect5.succeed(null))
+  );
+  if (!estimate) {
+    yield* Console5.error(
+      "No semantic index found and could not estimate cost."
+    );
+    yield* Console5.error('Run "mdcontext index --embed" first.');
+    return false;
+  }
+  if (estimate.estimatedTimeSeconds <= autoIndexThreshold) {
+    if (!json) {
+      yield* Console5.log(
+        `Creating semantic index (~${estimate.estimatedTimeSeconds}s, ~$${estimate.totalCost.toFixed(4)})...`
+      );
+    }
+    const result = yield* buildEmbeddings(resolvedDir, {
+      force: false,
+      onFileProgress: (progress) => {
+        if (!json) {
+          process.stdout.write(
+            `\r  [${progress.fileIndex}/${progress.totalFiles}] ${progress.filePath}...`
+          );
+        }
+      }
+    }).pipe(
+      handleApiKeyError,
+      Effect5.catchAll(() => Effect5.succeed(null))
+    );
+    if (!result) {
+      return false;
+    }
+    if (!json) {
+      process.stdout.write(`\r${" ".repeat(80)}\r`);
+      yield* Console5.log(
+        `Index created (${result.sectionsEmbedded} sections, $${result.cost.toFixed(6)})`
+      );
+      yield* Console5.log("");
+    }
+    return true;
+  }
+  if (!json) {
+    yield* Console5.log("");
+    yield* Console5.log("No semantic index found.");
+    yield* Console5.log("");
+    yield* Console5.log("Options:");
+    yield* Console5.log(
+      `  1. Create now (recommended, ~${estimate.estimatedTimeSeconds}s, ~$${estimate.totalCost.toFixed(4)})`
+    );
+    yield* Console5.log("  2. Use keyword search instead");
+    yield* Console5.log("");
+  }
+  const answer = yield* Effect5.promise(() => promptUser2("Choice [1]: "));
+  const choice = answer === "" || answer === "1" ? "1" : answer;
+  if (choice === "1") {
+    if (!json) {
+      yield* Console5.log("");
+      yield* Console5.log("Building embeddings...");
+    }
+    const result = yield* buildEmbeddings(resolvedDir, {
+      force: false,
+      onFileProgress: (progress) => {
+        if (!json) {
+          process.stdout.write(
+            `\r  [${progress.fileIndex}/${progress.totalFiles}] ${progress.filePath}...`
+          );
+        }
+      }
+    }).pipe(
+      handleApiKeyError,
+      Effect5.catchAll(() => Effect5.succeed(null))
+    );
+    if (!result) {
+      return false;
+    }
+    if (!json) {
+      process.stdout.write(`\r${" ".repeat(80)}\r`);
+      yield* Console5.log(
+        `Index created (${result.sectionsEmbedded} sections, $${result.cost.toFixed(6)})`
+      );
+      yield* Console5.log("");
+    }
+    return true;
+  }
+  yield* Console5.log("");
+  yield* Console5.log("Falling back to keyword search.");
+  return false;
+});
+
+// src/cli/commands/stats.ts
+import * as path7 from "path";
+import { Args as Args6, Command as Command6 } from "@effect/cli";
+import { Console as Console6, Effect as Effect6 } from "effect";
+var statsCommand = Command6.make(
+  "stats",
+  {
+    path: Args6.directory({ name: "path" }).pipe(
+      Args6.withDescription("Directory to show stats for"),
+      Args6.withDefault(".")
+    ),
+    json: jsonOption,
+    pretty: prettyOption
+  },
+  ({ path: dirPath, json, pretty }) => Effect6.gen(function* () {
+    const resolvedRoot = path7.resolve(dirPath);
+    const storage = createStorage(resolvedRoot);
+    const docIndex = yield* loadDocumentIndex(storage);
+    const sectionIndex = yield* loadSectionIndex(storage);
+    if (!docIndex || !sectionIndex) {
+      if (json) {
+        yield* Console6.log(formatJson({ error: "No index found" }, pretty));
+      } else {
+        yield* Console6.log("No index found.");
+        yield* Console6.log("Run 'mdcontext index <path>' to create an index.");
+      }
+      return;
+    }
+    const docs = Object.values(docIndex.documents);
+    const sections = Object.values(sectionIndex.sections);
+    const tokenCounts = docs.map((d) => d.tokenCount).sort((a, b) => a - b);
+    const totalTokens = tokenCounts.reduce((sum, t) => sum + t, 0);
+    const sectionsByLevel = {};
+    for (const section of sections) {
+      sectionsByLevel[section.level] = (sectionsByLevel[section.level] || 0) + 1;
+    }
+    const indexStats = {
+      documentCount: docs.length,
+      totalTokens,
+      avgTokensPerDoc: docs.length > 0 ? Math.round(totalTokens / docs.length) : 0,
+      totalSections: sections.length,
+      sectionsByLevel,
+      tokenDistribution: {
+        min: tokenCounts[0] || 0,
+        max: tokenCounts[tokenCounts.length - 1] || 0,
+        median: tokenCounts[Math.floor(tokenCounts.length / 2)] || 0
+      }
+    };
+    const embeddingStats = yield* getEmbeddingStats(resolvedRoot);
+    if (json) {
+      yield* Console6.log(
+        formatJson({ ...indexStats, embeddings: embeddingStats }, pretty)
+      );
+    } else {
+      yield* Console6.log("Index statistics:");
+      yield* Console6.log("");
+      yield* Console6.log("  Documents");
+      yield* Console6.log(`    Count:       ${indexStats.documentCount}`);
+      yield* Console6.log(
+        `    Tokens:      ${indexStats.totalTokens.toLocaleString()}`
+      );
+      yield* Console6.log(`    Avg/doc:     ${indexStats.avgTokensPerDoc}`);
+      yield* Console6.log("");
+      yield* Console6.log("  Token distribution");
+      yield* Console6.log(
+        `    Min:         ${indexStats.tokenDistribution.min}`
+      );
+      yield* Console6.log(
+        `    Median:      ${indexStats.tokenDistribution.median}`
+      );
+      yield* Console6.log(
+        `    Max:         ${indexStats.tokenDistribution.max}`
+      );
+      yield* Console6.log("");
+      yield* Console6.log("  Sections");
+      yield* Console6.log(`    Total:       ${indexStats.totalSections}`);
+      const levels = Object.keys(sectionsByLevel).map(Number).sort((a, b) => a - b);
+      for (const level of levels) {
+        yield* Console6.log(
+          `    h${level}:          ${sectionsByLevel[level]}`
+        );
+      }
+      yield* Console6.log("");
+      yield* Console6.log("  Embeddings");
+      if (embeddingStats.hasEmbeddings) {
+        yield* Console6.log(`    Vectors:     ${embeddingStats.count}`);
+        yield* Console6.log(`    Provider:    ${embeddingStats.provider}`);
+        yield* Console6.log(`    Dimensions:  ${embeddingStats.dimensions}`);
+        yield* Console6.log(
+          `    Cost:        $${embeddingStats.totalCost.toFixed(6)}`
+        );
+      } else {
+        yield* Console6.log("    Not enabled");
+        yield* Console6.log(
+          "    Run 'mdcontext index --embed' to build embeddings."
+        );
+      }
+    }
+  })
+).pipe(Command6.withDescription("Index statistics"));
+
+// src/cli/commands/tree.ts
+import * as fs from "fs";
+import * as path8 from "path";
+import { Args as Args7, Command as Command7 } from "@effect/cli";
+import { Console as Console7, Effect as Effect7 } from "effect";
+var treeCommand = Command7.make(
+  "tree",
+  {
+    pathArg: Args7.text({ name: "path" }).pipe(
+      Args7.withDescription("Directory (shows files) or file (shows outline)"),
+      Args7.withDefault(".")
+    ),
+    json: jsonOption,
+    pretty: prettyOption
+  },
+  ({ pathArg, json, pretty }) => Effect7.gen(function* () {
+    const resolvedPath = path8.resolve(pathArg);
+    const stat2 = yield* Effect7.try(() => fs.statSync(resolvedPath));
+    if (stat2.isFile()) {
+      const result = yield* parseFile(resolvedPath).pipe(
+        Effect7.mapError((e) => new Error(`${e._tag}: ${e.message}`))
+      );
+      const extractStructure = (section) => ({
+        heading: section.heading,
+        level: section.level,
+        tokens: section.metadata.tokenCount,
+        children: section.children.map(extractStructure)
+      });
+      if (json) {
+        const structure = {
+          title: result.title,
+          path: result.path,
+          totalTokens: result.metadata.tokenCount,
+          sections: result.sections.map(extractStructure)
+        };
+        yield* Console7.log(formatJson(structure, pretty));
+      } else {
+        yield* Console7.log(`# ${result.title}`);
+        yield* Console7.log(`Total tokens: ${result.metadata.tokenCount}`);
+        yield* Console7.log("");
+        const printOutline = (section, depth = 0) => Effect7.gen(function* () {
+          const indent = "  ".repeat(depth);
+          const marker = "#".repeat(section.level);
+          yield* Console7.log(
+            `${indent}${marker} ${section.heading} [${section.metadata.tokenCount} tokens]`
+          );
+          for (const child of section.children) {
+            yield* printOutline(child, depth + 1);
+          }
+        });
+        for (const section of result.sections) {
+          yield* printOutline(section);
+        }
+      }
+    } else {
+      const files = yield* Effect7.promise(() => walkDir(resolvedPath));
+      const tree = files.sort().map((f) => ({
+        path: f,
+        relativePath: path8.relative(resolvedPath, f)
+      }));
+      if (json) {
+        yield* Console7.log(formatJson(tree, pretty));
+      } else {
+        yield* Console7.log(`Markdown files in ${resolvedPath}:`);
+        yield* Console7.log("");
+        for (const file of tree) {
+          yield* Console7.log(`  ${file.relativePath}`);
+        }
+        yield* Console7.log("");
+        yield* Console7.log(`Total: ${tree.length} files`);
+      }
+    }
+  })
+).pipe(Command7.withDescription("Show files or document outline"));
+
+// src/cli/help.ts
+var helpContent = {
+  index: {
+    description: "Index markdown files for fast searching",
+    usage: "mdcontext index [path] [options]",
+    examples: [
+      "mdcontext index                    # Index current directory",
+      "mdcontext index docs/              # Index specific directory",
+      "mdcontext index --embed            # Include semantic embeddings",
+      "mdcontext index --watch            # Watch for file changes",
+      "mdcontext index --embed --watch    # Full setup with live updates",
+      "mdcontext index --force            # Rebuild from scratch"
+    ],
+    options: [
+      {
+        name: "-e, --embed",
+        description: "Build semantic embeddings (enables AI-powered search)"
+      },
+      {
+        name: "--no-embed",
+        description: "Skip the prompt to enable semantic search"
+      },
+      {
+        name: "-w, --watch",
+        description: "Watch for changes and re-index automatically"
+      },
+      { name: "--force", description: "Rebuild from scratch, ignoring cache" },
+      { name: "--json", description: "Output results as JSON" },
+      { name: "--pretty", description: "Pretty-print JSON output" }
+    ],
+    notes: [
+      "After indexing, prompts to enable semantic search (use --no-embed to skip).",
+      "Embedding requires OPENAI_API_KEY environment variable.",
+      "Index is stored in .mdcontext/ directory."
+    ]
+  },
+  search: {
+    description: "Search markdown content by meaning or heading pattern",
+    usage: "mdcontext search [options] <query> [path]",
+    examples: [
+      'mdcontext search "auth"                    # Simple term search',
+      'mdcontext search "auth AND deploy"         # Both terms required',
+      'mdcontext search "error OR bug"            # Either term matches',
+      'mdcontext search "impl NOT test"           # Exclude "test"',
+      'mdcontext search "auth AND (error OR bug)" # Grouped expressions',
+      `mdcontext search '"exact phrase"'          # Exact phrase match`,
+      `mdcontext search '"context resumption" AND drift'  # Phrase + boolean`,
+      'mdcontext search -H "API.*"                # Regex on headings only',
+      'mdcontext search --mode keyword "auth"     # Force keyword mode',
+      'mdcontext search --mode semantic "auth"    # Force semantic mode',
+      'mdcontext search -n 5 "setup"              # Limit to 5 results',
+      'mdcontext search "config" docs/            # Search in specific directory',
+      "",
+      "# Context lines (like grep):",
+      'mdcontext search "checkpoint" -C 3         # 3 lines before AND after',
+      'mdcontext search "error" -B 2 -A 5         # 2 before, 5 after'
+    ],
+    options: [
+      {
+        name: "-k, --keyword",
+        description: "Force keyword search (content text match)"
+      },
+      {
+        name: "-H, --heading-only",
+        description: "Search headings only (not content)"
+      },
+      {
+        name: "-m, --mode <mode>",
+        description: "Force search mode: semantic or keyword"
+      },
+      {
+        name: "-n, --limit <n>",
+        description: "Maximum number of results (default: 10)"
+      },
+      {
+        name: "-C <n>",
+        description: "Show N context lines before AND after each match"
+      },
+      {
+        name: "-B <n>",
+        description: "Show N context lines before each match"
+      },
+      {
+        name: "-A <n>",
+        description: "Show N context lines after each match"
+      },
+      {
+        name: "--threshold <n>",
+        description: "Similarity threshold 0-1 for semantic search (default: 0.5)"
+      },
+      { name: "--json", description: "Output results as JSON" },
+      { name: "--pretty", description: "Pretty-print JSON output" }
+    ],
+    notes: [
+      "Auto-detects mode: semantic if embeddings exist, keyword otherwise.",
+      "Boolean operators: AND, OR, NOT (case-insensitive).",
+      'Quoted phrases match exactly: "context resumption".',
+      'Regex patterns (e.g., "API.*") always use keyword search.',
+      'Run "mdcontext index --embed" first for semantic search.'
+    ]
+  },
+  context: {
+    description: "Get LLM-ready summary of markdown files",
+    usage: "mdcontext context [options] <files>...",
+    examples: [
+      "mdcontext context README.md        # Summarize single file",
+      "mdcontext context *.md             # Summarize all markdown files",
+      "mdcontext context -t 1000 *.md     # Fit within 1000 token budget",
+      "mdcontext context --brief *.md     # Minimal output (headings only)",
+      "mdcontext context --full doc.md    # Include full content",
+      "mdcontext context *.md | pbcopy    # Copy to clipboard (macOS)",
+      "",
+      "# Section filtering:",
+      "mdcontext context doc.md --sections                # List available sections",
+      'mdcontext context doc.md --section "Setup"         # Extract by section name',
+      'mdcontext context doc.md --section "2.1"           # Extract by section number',
+      'mdcontext context doc.md --section "API*"          # Glob pattern matching',
+      'mdcontext context doc.md --section "Config" --shallow  # Top-level only'
+    ],
+    options: [
+      {
+        name: "-t, --tokens <n>",
+        description: "Token budget for output (default: 2000)"
+      },
+      {
+        name: "--brief",
+        description: "Minimal output (headings and key points only)"
+      },
+      {
+        name: "--full",
+        description: "Include full content (no summarization)"
+      },
+      {
+        name: "--section <name>",
+        description: "Extract specific section by name, number, or glob pattern"
+      },
+      {
+        name: "--sections",
+        description: "List available sections with numbers and token counts"
+      },
+      {
+        name: "--shallow",
+        description: "Exclude nested subsections when using --section"
+      },
+      { name: "--json", description: "Output as JSON" },
+      { name: "--pretty", description: "Pretty-print JSON output" }
+    ],
+    notes: [
+      "Token budget controls how much content is included.",
+      "Lower tokens = more aggressive summarization.",
+      "Output is formatted for direct use in LLM prompts.",
+      "Use --sections to discover section names before filtering."
+    ]
+  },
+  tree: {
+    description: "Show file tree or document outline",
+    usage: "mdcontext tree [path] [options]",
+    examples: [
+      "mdcontext tree                     # List markdown files in current dir",
+      "mdcontext tree docs/               # List files in specific directory",
+      "mdcontext tree README.md           # Show document outline (headings)",
+      "mdcontext tree doc.md --json       # Outline as JSON"
+    ],
+    options: [
+      { name: "--json", description: "Output as JSON" },
+      { name: "--pretty", description: "Pretty-print JSON output" }
+    ],
+    notes: [
+      "Pass a directory to list markdown files.",
+      "Pass a file to show its heading structure with token counts."
+    ]
+  },
+  links: {
+    description: "Show what a file links to (outgoing links)",
+    usage: "mdcontext links <file> [options]",
+    examples: [
+      "mdcontext links README.md          # Show outgoing links",
+      "mdcontext links doc.md --json      # Output as JSON",
+      "mdcontext links doc.md -r docs/    # Resolve links relative to docs/"
+    ],
+    options: [
+      {
+        name: "-r, --root <dir>",
+        description: "Root directory for resolving relative links"
+      },
+      { name: "--json", description: "Output as JSON" },
+      { name: "--pretty", description: "Pretty-print JSON output" }
+    ]
+  },
+  backlinks: {
+    description: "Show what links to a file (incoming links)",
+    usage: "mdcontext backlinks <file> [options]",
+    examples: [
+      "mdcontext backlinks api.md         # What links to api.md?",
+      "mdcontext backlinks doc.md --json  # Output as JSON",
+      "mdcontext backlinks doc.md -r ./   # Resolve from current directory"
+    ],
+    options: [
+      {
+        name: "-r, --root <dir>",
+        description: "Root directory for resolving relative links"
+      },
+      { name: "--json", description: "Output as JSON" },
+      { name: "--pretty", description: "Pretty-print JSON output" }
+    ],
+    notes: ['Requires index to exist. Run "mdcontext index" first.']
+  },
+  stats: {
+    description: "Show index statistics",
+    usage: "mdcontext stats [path] [options]",
+    examples: [
+      "mdcontext stats                    # Show stats for current directory",
+      "mdcontext stats docs/              # Show stats for specific directory",
+      "mdcontext stats --json             # Output as JSON"
+    ],
+    options: [
+      { name: "--json", description: "Output as JSON" },
+      { name: "--pretty", description: "Pretty-print JSON output" }
+    ],
+    notes: ["Shows embedding count, dimensions, and cost if embeddings exist."]
+  }
+};
+var showSubcommandHelp = (command) => {
+  const help = helpContent[command];
+  if (!help) {
+    console.log(`Unknown command: ${command}`);
+    console.log('Run "mdcontext --help" for available commands.');
+    process.exit(1);
+  }
+  console.log(`
+\x1B[1mmdcontext ${command}\x1B[0m - ${help.description}`);
+  console.log(`
+\x1B[33mUSAGE\x1B[0m`);
+  console.log(`  ${help.usage}`);
+  console.log(`
+\x1B[33mEXAMPLES\x1B[0m`);
+  for (const example of help.examples) {
+    console.log(`  ${example}`);
+  }
+  console.log(`
+\x1B[33mOPTIONS\x1B[0m`);
+  for (const opt of help.options) {
+    const paddedName = opt.name.padEnd(24);
+    console.log(`  ${paddedName}${opt.description}`);
+  }
+  if (help.notes && help.notes.length > 0) {
+    console.log(`
+\x1B[33mNOTES\x1B[0m`);
+    for (const note of help.notes) {
+      console.log(`  ${note}`);
+    }
+  }
+  console.log("");
+};
+var showMainHelp = () => {
+  const help = `
+\x1B[1mmdcontext\x1B[0m - Token-efficient markdown analysis for LLMs
+
+\x1B[33mCOMMANDS\x1B[0m
+  index [path]              Index markdown files (default: .)
+  search <query> [path]     Search by meaning or structure
+  context <files>...        Get LLM-ready summary
+  tree [path]               Show files or document outline
+  links <file>              Show outgoing links
+  backlinks <file>          Show incoming links
+  stats [path]              Index statistics
+
+\x1B[33mEXAMPLES\x1B[0m
+  mdcontext tree                         # List all markdown files
+  mdcontext tree README.md               # Show document outline
+  mdcontext index                        # Index current directory
+  mdcontext index --embed                # Index with semantic embeddings
+  mdcontext search "auth"                # Simple term search
+  mdcontext search "auth AND deploy"     # Boolean AND (both required)
+  mdcontext search "error OR bug"        # Boolean OR (either matches)
+  mdcontext search '"exact phrase"'      # Quoted phrase (exact match)
+  mdcontext search "how to deploy"       # Semantic search (if embeddings exist)
+  mdcontext context README.md            # Summarize a file
+  mdcontext context *.md -t 2000         # Multi-file with token budget
+
+\x1B[33mWORKFLOWS\x1B[0m
+  \x1B[2m# Quick context for LLM\x1B[0m
+  mdcontext context README.md docs/*.md | pbcopy
+
+  \x1B[2m# Find relevant documentation\x1B[0m
+  mdcontext search "error handling"
+
+  \x1B[2m# Complex queries with boolean operators\x1B[0m
+  mdcontext search "auth AND (error OR exception) NOT test"
+
+  \x1B[2m# Explore a new codebase\x1B[0m
+  mdcontext tree && mdcontext stats
+
+  \x1B[2m# Build semantic search\x1B[0m
+  mdcontext index --embed && mdcontext search "authentication flow"
+
+\x1B[33mGLOBAL OPTIONS\x1B[0m
+  --json          Output as JSON
+  --pretty        Pretty-print JSON
+  --help, -h      Show help
+  --version, -v   Show version
+
+Run \x1B[36mmdcontext <command> --help\x1B[0m for command-specific options.
+`;
+  console.log(help);
+};
+var checkSubcommandHelp = () => {
+  const args = process.argv.slice(2);
+  if (args.length < 2) return false;
+  const command = args[0];
+  const hasHelpFlag = args.includes("--help") || args.includes("-h");
+  if (hasHelpFlag && command && helpContent[command]) {
+    showSubcommandHelp(command);
+    process.exit(0);
+  }
+  return false;
+};
+var shouldShowMainHelp = () => {
+  const args = process.argv.slice(2);
+  const showHelp = args.length === 0 || args.includes("--help") || args.includes("-h") || args.length === 1 && args[0] === "help";
+  return showHelp && !args.some((a) => !a.startsWith("-") && a !== "help");
+};
+
+// src/cli/main.ts
+var mainCommand = Command8.make("mdcontext").pipe(
+  Command8.withDescription("Token-efficient markdown analysis for LLMs"),
+  Command8.withSubcommands([
+    indexCommand,
+    searchCommand,
+    contextCommand,
+    treeCommand,
+    linksCommand,
+    backlinksCommand,
+    statsCommand
+  ])
+);
+var cli = Command8.run(mainCommand, {
+  name: "mdcontext",
+  version: "0.1.0"
+});
+var cliConfigLayer = CliConfig.layer({
+  showBuiltIns: false
+});
+var formatCliError = (error) => {
+  if (error && typeof error === "object") {
+    const err = error;
+    if (err._tag === "ValidationError" && err.error) {
+      const validationError = err.error;
+      if (validationError._tag === "Paragraph" && validationError.value) {
+        const paragraph = validationError.value;
+        if (paragraph._tag === "Text" && typeof paragraph.value === "string") {
+          return paragraph.value;
+        }
+      }
+    }
+    if (err._tag === "MissingValue" && err.error) {
+      const missingError = err.error;
+      if (missingError._tag === "Paragraph" && missingError.value) {
+        const paragraph = missingError.value;
+        if (paragraph._tag === "Text" && typeof paragraph.value === "string") {
+          return paragraph.value;
+        }
+      }
+    }
+  }
+  return String(error);
+};
+var isValidationError = (error) => {
+  if (error && typeof error === "object") {
+    const err = error;
+    return err._tag === "ValidationError" || err._tag === "MissingValue" || err._tag === "InvalidValue";
+  }
+  return false;
+};
+checkSubcommandHelp();
+if (shouldShowMainHelp()) {
+  showMainHelp();
+  process.exit(0);
+}
+var processedArgv = preprocessArgv(process.argv);
+Effect8.suspend(() => cli(processedArgv)).pipe(
+  Effect8.provide(Layer.merge(NodeContext.layer, cliConfigLayer)),
+  Effect8.catchAll(
+    (error) => Effect8.sync(() => {
+      if (isValidationError(error)) {
+        const message = formatCliError(error);
+        console.error(`
+Error: ${message}`);
+        console.error('\nRun "mdcontext --help" for usage information.');
+        process.exit(1);
+      }
+      throw error;
+    })
+  ),
+  NodeRuntime.runMain
+);