@modexagents/core 0.3.1

package/dist/index.js

@@ -0,0 +1,1979 @@
+// src/schema.ts
+import { z } from "zod";
+var SCHEMA_VERSION = 0;
+var SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+var SkillSchema = z.object({
+  slug: z.string().min(1).max(64).regex(SLUG_PATTERN, "slug must be kebab-case [a-z0-9-]"),
+  name: z.string().min(1).max(120),
+  description: z.string().min(1).max(2e3),
+  tags: z.array(z.string().regex(SLUG_PATTERN, "tag must be kebab-case [a-z0-9-]").max(40)).min(1).max(6),
+  source: z.string().min(1).max(255)
+});
+var SkillsDocSchema = z.object({
+  schema_version: z.literal(SCHEMA_VERSION),
+  skills: z.array(SkillSchema)
+});
+var ExtractedSkillSchema = SkillSchema.omit({ source: true });
+var ExtractionResultSchema = z.object({
+  skills: z.array(ExtractedSkillSchema)
+});
+
+// src/serialize.ts
+function compareCodepoints(a, b) {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+function normalizeSkill(skill) {
+  return {
+    slug: skill.slug,
+    name: skill.name.trim(),
+    description: skill.description.trim(),
+    tags: [...skill.tags].sort(compareCodepoints),
+    source: skill.source
+  };
+}
+function renderSkill(skill) {
+  return [
+    `## ${skill.slug}`,
+    "",
+    `**Name:** ${skill.name}`,
+    "",
+    `**Description:** ${skill.description}`,
+    "",
+    `**Tags:** ${skill.tags.join(", ")}`,
+    "",
+    `**Source:** ${skill.source}`,
+    "",
+    "---"
+  ].join("\n");
+}
+function serialize(doc) {
+  const skills = doc.skills.map(normalizeSkill).sort((a, b) => compareCodepoints(a.slug, b.slug));
+  const frontmatter = ["---", `schema_version: ${SCHEMA_VERSION}`, "---"].join("\n");
+  if (skills.length === 0) {
+    return `${frontmatter}
+`;
+  }
+  const body = skills.map(renderSkill).join("\n\n");
+  return `${frontmatter}
+
+${body}
+`;
+}
+function buildDoc(skills) {
+  return { schema_version: SCHEMA_VERSION, skills };
+}
+
+// src/extract.ts
+import Anthropic from "@anthropic-ai/sdk";
+
+// src/prompt.ts
+var MODEL_ID = "claude-haiku-4-5-20251001";
+var EMIT_SKILLS_TOOL = {
+  name: "emit_skills",
+  description: "Emit the structured set of skills extracted from the user-provided corpus.",
+  input_schema: {
+    type: "object",
+    properties: {
+      skills: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            slug: {
+              type: "string",
+              pattern: "^[a-z0-9]+(-[a-z0-9]+)*$",
+              maxLength: 64,
+              description: "Kebab-case identifier, unique within this output. No underscores, spaces, or capitals."
+            },
+            name: {
+              type: "string",
+              minLength: 1,
+              maxLength: 120,
+              description: "Short human-readable title (3-8 words)."
+            },
+            description: {
+              type: "string",
+              minLength: 1,
+              maxLength: 2e3,
+              description: "One paragraph (1-4 sentences), self-contained, written so a reader who has not seen the corpus can apply it."
+            },
+            tags: {
+              type: "array",
+              minItems: 1,
+              maxItems: 6,
+              items: {
+                type: "string",
+                pattern: "^[a-z0-9]+(-[a-z0-9]+)*$",
+                maxLength: 40
+              },
+              description: "1-6 kebab-case topical labels."
+            }
+          },
+          required: ["slug", "name", "description", "tags"],
+          additionalProperties: false
+        }
+      }
+    },
+    required: ["skills"],
+    additionalProperties: false
+  }
+};
+var SYSTEM_PROMPT = `You are an extraction engine that reads a corpus and produces a structured set of distinct skills.
+
+A "skill" is a transferable, reusable practice or technique that a person could apply across contexts \u2014 not a fact, definition, story, or one-off opinion.
+
+For every skill you identify, emit:
+- slug: kebab-case identifier matching ^[a-z0-9]+(-[a-z0-9]+)*$, unique within this output
+- name: short human-readable title (3-8 words; Title Case acceptable)
+- description: one paragraph (1-4 sentences), self-contained, written as a directly applicable instruction
+- tags: 1-6 kebab-case topical labels matching ^[a-z0-9]+(-[a-z0-9]+)*$
+
+Quality rules:
+- Only emit skills that are clearly supported by the corpus.
+- Do not invent skills to pad the list. Returning fewer high-quality skills is preferred to many vague ones.
+- Avoid near-duplicates. If two passages describe the same underlying technique, emit one skill.
+- Do not include source citations, page numbers, or quotes in the description.
+- The description must stand on its own; a reader who has not seen the corpus must be able to apply the skill.
+
+Always respond by calling the emit_skills tool exactly once with the full result. Do not include any text outside the tool call.`;
+
+// src/extract.ts
+var MAX_CORPUS_BYTES = 5e5;
+var ExtractionError = class extends Error {
+  cause;
+  constructor(message, cause) {
+    super(message);
+    this.name = "ExtractionError";
+    this.cause = cause;
+  }
+};
+async function extractSkills(corpus, opts) {
+  const bytes = Buffer.byteLength(corpus, "utf8");
+  if (bytes > MAX_CORPUS_BYTES) {
+    throw new ExtractionError(
+      `Corpus is ${bytes} bytes, which exceeds the Phase A limit of ${MAX_CORPUS_BYTES}. Chunking arrives in Phase C.`
+    );
+  }
+  if (corpus.trim().length === 0) {
+    throw new ExtractionError("Corpus is empty.");
+  }
+  const apiKey = opts.apiKey ?? process.env["ANTHROPIC_API_KEY"];
+  if (!opts.client && !apiKey) {
+    throw new ExtractionError(
+      "ANTHROPIC_API_KEY is not set. Export it in your environment, or copy .env.example to .env."
+    );
+  }
+  const client = opts.client ?? new Anthropic({ apiKey });
+  const model = opts.model ?? MODEL_ID;
+  let response;
+  try {
+    response = await client.messages.create({
+      model,
+      max_tokens: opts.maxTokens ?? 4096,
+      system: [
+        {
+          type: "text",
+          text: SYSTEM_PROMPT,
+          cache_control: { type: "ephemeral" }
+        }
+      ],
+      tools: [EMIT_SKILLS_TOOL],
+      tool_choice: { type: "tool", name: "emit_skills" },
+      messages: [
+        {
+          role: "user",
+          content: corpus
+        }
+      ]
+    });
+  } catch (err) {
+    throw new ExtractionError("Anthropic API call failed", err);
+  }
+  const toolUse = response.content.find(
+    (b) => b.type === "tool_use" && b.name === "emit_skills"
+  );
+  if (!toolUse || toolUse.type !== "tool_use") {
+    throw new ExtractionError(
+      `Model did not emit the emit_skills tool call (stop_reason=${response.stop_reason}).`
+    );
+  }
+  const parsed = ExtractionResultSchema.safeParse(toolUse.input);
+  if (!parsed.success) {
+    const detail = parsed.error.issues.map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`).join("; ");
+    throw new ExtractionError(`Model output failed validation: ${detail}`);
+  }
+  return parsed.data.skills.map((s) => ({ ...s, source: opts.source }));
+}
+
+// src/sources/index.ts
+import { extname as extname2 } from "path";
+
+// src/sources/epub.ts
+import { basename } from "path";
+
+// src/sources/types.ts
+var SourceError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SourceError";
+  }
+};
+
+// src/sources/epub.ts
+function htmlToText(html) {
+  return html.replace(/<\/(p|div|h[1-6]|li|br|tr|hr)>/gi, "\n").replace(/<br\s*\/?>/gi, "\n").replace(/<[^>]+>/g, "").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/[ \t]+\n/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+async function loadEpubSource(path) {
+  const { EPub } = await import("epub2");
+  let book;
+  try {
+    book = await EPub.createAsync(path);
+  } catch (err) {
+    throw new SourceError(`Could not open EPUB ${path}: ${err.message}`);
+  }
+  const chapters = [];
+  for (const item of book.flow) {
+    if (!item.id) continue;
+    let html;
+    try {
+      html = await book.getChapterAsync(item.id);
+    } catch (err) {
+      throw new SourceError(
+        `Could not read chapter '${item.id}' from ${path}: ${err.message}`
+      );
+    }
+    const text = htmlToText(html);
+    if (text.length > 0) chapters.push(text);
+  }
+  const content = chapters.join("\n\n");
+  if (content.trim().length === 0) {
+    throw new SourceError(`EPUB ${path} extracted to empty text (no readable chapters).`);
+  }
+  return {
+    source: basename(path),
+    source_url: null,
+    source_kind: "epub",
+    content
+  };
+}
+
+// src/sources/pdf.ts
+import { readFile } from "fs/promises";
+import { basename as basename2 } from "path";
+async function loadPdfSource(path) {
+  let bytes;
+  try {
+    bytes = await readFile(path);
+  } catch (err) {
+    throw new SourceError(`Could not read ${path}: ${err.message}`);
+  }
+  const { extractText } = await import("unpdf");
+  let result;
+  try {
+    result = await extractText(new Uint8Array(bytes), { mergePages: true });
+  } catch (err) {
+    throw new SourceError(`Could not parse PDF ${path}: ${err.message}`);
+  }
+  const text = Array.isArray(result.text) ? result.text.join("\n") : result.text;
+  if (text.trim().length === 0) {
+    throw new SourceError(
+      `PDF ${path} extracted to empty text (${result.totalPages} pages). Likely an image-only/scanned PDF; OCR is out of scope for Phase C.`
+    );
+  }
+  return {
+    source: basename2(path),
+    source_url: null,
+    source_kind: "pdf",
+    content: text
+  };
+}
+
+// src/sources/text.ts
+import { readFile as readFile2 } from "fs/promises";
+import { basename as basename3, extname } from "path";
+var KIND_BY_EXT = {
+  ".txt": "text",
+  ".md": "markdown"
+};
+var TEXT_EXTENSIONS = Object.keys(KIND_BY_EXT);
+async function loadTextSource(path) {
+  const ext = extname(path).toLowerCase();
+  const kind = KIND_BY_EXT[ext];
+  if (kind === void 0) {
+    throw new SourceError(
+      `Not a text source: ${path} (extension ${ext || "(none)"} is not .txt or .md).`
+    );
+  }
+  let content;
+  try {
+    content = await readFile2(path, "utf8");
+  } catch (err) {
+    throw new SourceError(`Could not read ${path}: ${err.message}`);
+  }
+  return {
+    source: basename3(path),
+    source_url: null,
+    source_kind: kind,
+    content
+  };
+}
+
+// src/sources/web.ts
+import { lookup as dnsLookup } from "dns/promises";
+import { isIP } from "net";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_MAX_BYTES = 10 * 1024 * 1024;
+var DEFAULT_USER_AGENT = `modex-cli/${"0.3.1"} (+https://modex.md)`;
+var MAX_REDIRECTS = 10;
+var ALLOWED_CONTENT_TYPES = [
+  "text/html",
+  "application/xhtml+xml",
+  "text/plain"
+];
+function normalizeUrl(input) {
+  let u;
+  try {
+    u = new URL(input);
+  } catch {
+    throw new SourceError(`Invalid URL: ${input}`);
+  }
+  if (u.protocol !== "http:" && u.protocol !== "https:") {
+    throw new SourceError(`Unsupported URL scheme: ${u.protocol} (only http and https are allowed).`);
+  }
+  u.hash = "";
+  u.hostname = u.hostname.toLowerCase();
+  if (u.protocol === "http:" && u.port === "80" || u.protocol === "https:" && u.port === "443") {
+    u.port = "";
+  }
+  return u.toString();
+}
+function isPrivateIPv4(ip) {
+  const parts = ip.split(".").map(Number);
+  if (parts.length !== 4 || parts.some((p) => Number.isNaN(p) || p < 0 || p > 255)) {
+    return true;
+  }
+  const [a, b] = parts;
+  if (a === 0) return true;
+  if (a === 10) return true;
+  if (a === 127) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true;
+  return false;
+}
+function parseHextets(ip) {
+  let work = ip.toLowerCase();
+  let ipv4Tail = null;
+  const lastColon = work.lastIndexOf(":");
+  const tail = lastColon >= 0 ? work.slice(lastColon + 1) : work;
+  if (tail.includes(".")) {
+    const octets = tail.split(".").map(Number);
+    if (octets.length !== 4 || octets.some((o) => Number.isNaN(o) || o < 0 || o > 255)) {
+      return null;
+    }
+    ipv4Tail = [
+      octets[0] << 8 | octets[1],
+      octets[2] << 8 | octets[3]
+    ];
+    work = work.slice(0, lastColon + 1) + "0:0";
+  }
+  const halves = work.split("::");
+  if (halves.length > 2) return null;
+  const toGroups = (s) => {
+    if (s === "") return [];
+    const parts = s.split(":");
+    const groups2 = [];
+    for (const p of parts) {
+      if (!/^[0-9a-f]{1,4}$/.test(p)) return null;
+      groups2.push(parseInt(p, 16));
+    }
+    return groups2;
+  };
+  const head = toGroups(halves[0]);
+  const back = halves.length === 2 ? toGroups(halves[1]) : [];
+  if (head === null || back === null) return null;
+  let groups;
+  if (halves.length === 2) {
+    const fill = 8 - head.length - back.length;
+    if (fill < 1) return null;
+    groups = [...head, ...new Array(fill).fill(0), ...back];
+  } else {
+    groups = head;
+  }
+  if (ipv4Tail) {
+    groups = [...groups.slice(0, 6), ...ipv4Tail];
+  }
+  return groups.length === 8 ? groups : null;
+}
+function isPrivateIPv6(ip) {
+  const h = parseHextets(ip);
+  if (h === null) return true;
+  if (h.every((g) => g === 0)) return true;
+  if (h.slice(0, 7).every((g) => g === 0) && h[7] === 1) return true;
+  if (h.slice(0, 5).every((g) => g === 0) && h[5] === 65535) {
+    const a = h[6] >> 8 & 255;
+    const b = h[6] & 255;
+    const c = h[7] >> 8 & 255;
+    const d = h[7] & 255;
+    return isPrivateIPv4(`${a}.${b}.${c}.${d}`);
+  }
+  const first = h[0];
+  if (first >= 65152 && first <= 65215) return true;
+  if (first >= 64512 && first <= 65023) return true;
+  return false;
+}
+function isPrivateIP(ip, family) {
+  return family === 4 ? isPrivateIPv4(ip) : isPrivateIPv6(ip);
+}
+async function assertPublicHost(hostname, lookup) {
+  const unbracketed = hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+  if (isIP(unbracketed) !== 0) {
+    throw new SourceError(
+      `Refusing to fetch from an IP literal (${hostname}). Use a hostname.`
+    );
+  }
+  let result;
+  try {
+    result = await lookup(hostname);
+  } catch (err) {
+    throw new SourceError(`Could not resolve hostname ${hostname}: ${err.message}`);
+  }
+  if (isPrivateIP(result.address, result.family)) {
+    throw new SourceError(
+      `Refusing to fetch ${hostname}: resolves to a private/loopback address (${result.address}).`
+    );
+  }
+}
+async function readCappedBody(response, maxBytes) {
+  const ct = response.headers.get("content-type") ?? "";
+  const charset = (/charset=([^;]+)/i.exec(ct)?.[1] ?? "utf-8").trim().toLowerCase();
+  const lengthHeader = response.headers.get("content-length");
+  if (lengthHeader && Number(lengthHeader) > maxBytes) {
+    throw new SourceError(
+      `Response is ${lengthHeader} bytes (Content-Length); exceeds limit of ${maxBytes}.`
+    );
+  }
+  if (!response.body) {
+    const text = await response.text();
+    if (Buffer.byteLength(text) > maxBytes) {
+      throw new SourceError(`Response body exceeded ${maxBytes} bytes.`);
+    }
+    return { buffer: Buffer.from(text, "utf8"), charset };
+  }
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > maxBytes) {
+      await reader.cancel();
+      throw new SourceError(`Response body exceeded ${maxBytes} bytes (streamed).`);
+    }
+    chunks.push(value);
+  }
+  return { buffer: Buffer.concat(chunks), charset };
+}
+async function fetchWithGuards(url, opts) {
+  let current = url;
+  for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+    const u = new URL(current);
+    await assertPublicHost(u.hostname, opts.lookup);
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), opts.timeoutMs);
+    let response;
+    try {
+      response = await opts.fetch(current, {
+        method: "GET",
+        redirect: "manual",
+        signal: ctrl.signal,
+        headers: {
+          "user-agent": opts.userAgent,
+          accept: "text/html, application/xhtml+xml, text/plain;q=0.5"
+        }
+      });
+    } catch (err) {
+      const e = err;
+      if (e.name === "AbortError") {
+        throw new SourceError(`Fetch timed out after ${opts.timeoutMs}ms: ${current}`);
+      }
+      throw new SourceError(`Fetch failed for ${current}: ${e.message}`);
+    } finally {
+      clearTimeout(timer);
+    }
+    if (response.status >= 300 && response.status < 400) {
+      const location = response.headers.get("location");
+      if (!location) {
+        throw new SourceError(`Redirect from ${current} without a Location header.`);
+      }
+      const next = new URL(location, current).toString();
+      const nextProto = new URL(next).protocol;
+      if (nextProto !== "http:" && nextProto !== "https:") {
+        throw new SourceError(`Redirect from ${current} to non-http(s) target ${next}.`);
+      }
+      current = next;
+      continue;
+    }
+    if (!response.ok) {
+      throw new SourceError(`Fetch ${current} returned HTTP ${response.status}.`);
+    }
+    const ctype = (response.headers.get("content-type") ?? "").toLowerCase();
+    const allowed = ALLOWED_CONTENT_TYPES.some((t) => ctype.startsWith(t));
+    if (!allowed) {
+      throw new SourceError(
+        `Fetch ${current} returned unsupported content-type: ${ctype || "(none)"}. Phase C web fetching accepts ${ALLOWED_CONTENT_TYPES.join(", ")}.`
+      );
+    }
+    const { buffer, charset } = await readCappedBody(response, opts.maxBytes);
+    let html;
+    try {
+      html = new TextDecoder(charset).decode(buffer);
+    } catch {
+      html = new TextDecoder("utf-8").decode(buffer);
+    }
+    return { finalUrl: current, html };
+  }
+  throw new SourceError(`Exceeded ${MAX_REDIRECTS} redirects starting from ${url}.`);
+}
+async function htmlToArticleText(html, url) {
+  const { Readability } = await import("@mozilla/readability");
+  const { parseHTML } = await import("linkedom");
+  const dom = parseHTML(html);
+  const doc = dom.document;
+  try {
+    doc.documentURI = url;
+  } catch {
+  }
+  const article = new Readability(doc).parse();
+  if (article && article.textContent && article.textContent.trim().length > 0) {
+    return article.textContent.trim();
+  }
+  const body = doc.querySelector("body");
+  const fallback = (body?.textContent ?? "").trim();
+  if (fallback.length === 0) {
+    throw new SourceError(`Readability and body fallback both extracted empty text for ${url}.`);
+  }
+  return fallback;
+}
+async function loadWebSource(target, opts = {}) {
+  const url = normalizeUrl(target);
+  const fetchImpl = opts.fetch ?? globalThis.fetch;
+  const lookup = opts.dnsLookup ?? (async (host) => {
+    const r = await dnsLookup(host);
+    return { address: r.address, family: r.family === 6 ? 6 : 4 };
+  });
+  const { html } = await fetchWithGuards(url, {
+    fetch: fetchImpl,
+    lookup,
+    timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    maxBytes: opts.maxBytes ?? DEFAULT_MAX_BYTES,
+    userAgent: opts.userAgent ?? DEFAULT_USER_AGENT
+  });
+  const text = await htmlToArticleText(html, url);
+  return {
+    source: url,
+    source_url: url,
+    source_kind: "web",
+    content: text
+  };
+}
+
+// src/sources/index.ts
+function isWebUrl(target) {
+  return target.startsWith("http://") || target.startsWith("https://");
+}
+var EXT_LOADERS = {
+  ".txt": loadTextSource,
+  ".md": loadTextSource,
+  ".pdf": loadPdfSource,
+  ".epub": loadEpubSource
+};
+async function readSource(target) {
+  if (isWebUrl(target)) {
+    return loadWebSource(target);
+  }
+  const ext = extname2(target).toLowerCase();
+  const loader = EXT_LOADERS[ext];
+  if (loader === void 0) {
+    const shown = ext || "(no extension)";
+    throw new SourceError(
+      `Unsupported source type: ${shown}. Supported: .txt, .md, .pdf, .epub, http(s)://\u2026 URLs.`
+    );
+  }
+  return loader(target);
+}
+
+// src/glob.ts
+import { stat } from "fs/promises";
+import { isAbsolute, resolve } from "path";
+import { glob } from "tinyglobby";
+var GLOB_MAGIC = /[*?[\]{}!]/;
+function isGlobLike(pattern) {
+  return GLOB_MAGIC.test(pattern);
+}
+async function expandPatterns(patterns, opts = {}) {
+  if (patterns.length === 0) {
+    throw new SourceError("No patterns supplied.");
+  }
+  const cwd = opts.cwd ?? process.cwd();
+  const out = [];
+  for (const pattern of patterns) {
+    if (isWebUrl(pattern)) {
+      out.push(pattern);
+      continue;
+    }
+    if (isGlobLike(pattern)) {
+      const matches = await glob(pattern, { cwd, onlyFiles: true, absolute: true });
+      if (matches.length === 0) {
+        throw new SourceError(`Glob pattern matched zero files: ${pattern}`);
+      }
+      matches.sort();
+      out.push(...matches);
+      continue;
+    }
+    const abs = isAbsolute(pattern) ? pattern : resolve(cwd, pattern);
+    let s;
+    try {
+      s = await stat(abs);
+    } catch (err) {
+      throw new SourceError(`Path does not exist: ${pattern} (${err.message})`);
+    }
+    if (!s.isFile()) {
+      throw new SourceError(`Path is not a regular file: ${pattern}`);
+    }
+    out.push(abs);
+  }
+  return out;
+}
+
+// src/parseSkills.ts
+var ParseSkillsError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ParseSkillsError";
+  }
+};
+var FIELD_PATTERN = /^\*\*([A-Z][A-Za-z]*):\*\* (.*)$/;
+function parseSkills(input) {
+  if (input.includes("\r")) {
+    throw new ParseSkillsError("CR characters are not allowed; expected LF line endings.");
+  }
+  const lines = input.split("\n");
+  if (lines[0] !== "---" || lines[1] !== `schema_version: ${SCHEMA_VERSION}` || lines[2] !== "---") {
+    throw new ParseSkillsError(
+      `Missing or unrecognized frontmatter (expected schema_version: ${SCHEMA_VERSION}).`
+    );
+  }
+  const skills = [];
+  let i = 3;
+  while (i < lines.length) {
+    if (lines[i] === "" || lines[i] === void 0) {
+      i++;
+      continue;
+    }
+    const heading = lines[i];
+    const slugMatch = heading.match(/^## (.+)$/);
+    if (!slugMatch) {
+      throw new ParseSkillsError(`Expected '## <slug>' heading, got: ${JSON.stringify(heading)}`);
+    }
+    const slug = slugMatch[1];
+    i++;
+    const raw = { slug };
+    while (i < lines.length) {
+      if (lines[i] === "") {
+        i++;
+        continue;
+      }
+      const line = lines[i];
+      if (line === "---") {
+        i++;
+        break;
+      }
+      const fieldMatch = line.match(FIELD_PATTERN);
+      if (!fieldMatch) {
+        throw new ParseSkillsError(
+          `Expected '**Field:** value' or '---' inside skill '${slug}', got: ${JSON.stringify(line)}`
+        );
+      }
+      const [, field, value] = fieldMatch;
+      switch (field) {
+        case "Name":
+          raw.name = value;
+          break;
+        case "Description":
+          raw.description = value;
+          break;
+        case "Tags":
+          raw.tags = value.split(",").map((t) => t.trim()).filter((t) => t.length > 0);
+          break;
+        case "Source":
+          raw.source = value;
+          break;
+        default:
+          throw new ParseSkillsError(`Unknown field '${field}' inside skill '${slug}'.`);
+      }
+      i++;
+    }
+    if (raw.name === void 0 || raw.description === void 0 || raw.tags === void 0 || raw.source === void 0) {
+      throw new ParseSkillsError(
+        `Skill '${slug}' is missing required fields (Name, Description, Tags, Source).`
+      );
+    }
+    skills.push({
+      slug,
+      name: raw.name,
+      description: raw.description,
+      tags: raw.tags,
+      source: raw.source
+    });
+  }
+  return SkillsDocSchema.parse({ schema_version: SCHEMA_VERSION, skills });
+}
+
+// src/merge.ts
+function normalizeTags(tags) {
+  return [...new Set(tags)].sort();
+}
+function tagsEquivalent(a, b) {
+  const na = normalizeTags(a);
+  const nb = normalizeTags(b);
+  if (na.length !== nb.length) return false;
+  for (let i = 0; i < na.length; i++) if (na[i] !== nb[i]) return false;
+  return true;
+}
+function skillsEqual(a, b) {
+  return a.name === b.name && a.description === b.description && a.source === b.source && tagsEquivalent(a.tags, b.tags);
+}
+function mergeSkills(existing, incoming) {
+  const bySlug = /* @__PURE__ */ new Map();
+  for (const s of existing) bySlug.set(s.slug, s);
+  const added = [];
+  const updated = [];
+  for (const s of incoming) {
+    const prev = bySlug.get(s.slug);
+    if (prev === void 0) {
+      added.push(s.slug);
+    } else if (!skillsEqual(prev, s)) {
+      updated.push(s.slug);
+    }
+    bySlug.set(s.slug, s);
+  }
+  added.sort();
+  updated.sort();
+  return {
+    merged: [...bySlug.values()],
+    added,
+    updated
+  };
+}
+
+// src/canonicalJson.ts
+var CanonicalJsonError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CanonicalJsonError";
+  }
+};
+function compareCodepoints2(a, b) {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+function canonicalize(value) {
+  if (value === null) return "null";
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number") {
+    if (!Number.isInteger(value)) {
+      throw new CanonicalJsonError(
+        `non-integer number not allowed in canonical JSON: ${value}`
+      );
+    }
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalize).join(",")}]`;
+  }
+  if (typeof value === "object") {
+    const keys = Object.keys(value).sort(compareCodepoints2);
+    const parts = keys.map((k) => `${JSON.stringify(k)}:${canonicalize(value[k])}`);
+    return `{${parts.join(",")}}`;
+  }
+  throw new CanonicalJsonError(`unsupported value type: ${typeof value}`);
+}
+
+// src/fileLock.ts
+import { open, readFile as readFile3, unlink } from "fs/promises";
+var DEFAULT_LOCK_TIMEOUT_MS = 1e4;
+var DEFAULT_STALE_MS = 3e4;
+var RETRY_BACKOFF_MS = 50;
+var FileLockError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FileLockError";
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+async function readHolder(lockPath) {
+  try {
+    const raw = await readFile3(lockPath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.pid === "number" && typeof parsed.acquired_at === "number") {
+      return { pid: parsed.pid, acquired_at: parsed.acquired_at };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+async function withFileLock(targetPath, fn, opts = {}) {
+  const lockPath = `${targetPath}.lock`;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
+  const staleMs = opts.staleMs ?? DEFAULT_STALE_MS;
+  const now = opts.now ?? Date.now;
+  const deadline = now() + timeoutMs;
+  for (; ; ) {
+    try {
+      const handle = await open(lockPath, "wx");
+      try {
+        await handle.writeFile(
+          JSON.stringify({ pid: process.pid, acquired_at: now() }),
+          "utf8"
+        );
+      } finally {
+        await handle.close();
+      }
+      try {
+        return await fn();
+      } finally {
+        await unlink(lockPath).catch(() => {
+        });
+      }
+    } catch (err) {
+      if (err.code !== "EEXIST") throw err;
+      const holder = await readHolder(lockPath);
+      const stale = holder !== null && (!pidAlive(holder.pid) || now() - holder.acquired_at > staleMs);
+      if (stale) {
+        await unlink(lockPath).catch(() => {
+        });
+        continue;
+      }
+      if (now() >= deadline) {
+        throw new FileLockError(
+          `Timed out after ${timeoutMs}ms acquiring ${lockPath}` + (holder ? ` (held by pid ${holder.pid})` : "")
+        );
+      }
+      await sleep(RETRY_BACKOFF_MS);
+    }
+  }
+}
+
+// src/operations/feed.ts
+import { createHash as createHash2 } from "crypto";
+
+// src/agent.ts
+import { mkdir, readFile as readFile5, readdir, rename, stat as stat2, writeFile } from "fs/promises";
+import { join } from "path";
+import { v7 as uuidv7 } from "uuid";
+import { z as z3 } from "zod";
+
+// src/provenance.ts
+import { createHash } from "crypto";
+import { appendFile, readFile as readFile4 } from "fs/promises";
+import { z as z2 } from "zod";
+var PROVENANCE_SCHEMA_VERSION = 1;
+var SHA256_HEX = /^[0-9a-f]{64}$/;
+var SOURCE_KINDS = ["text", "markdown", "pdf", "epub", "web"];
+var FeedInputSchema = z2.object({
+  source: z2.string().min(1),
+  source_url: z2.union([z2.string().url(), z2.null()]),
+  source_kind: z2.enum(SOURCE_KINDS),
+  source_sha256: z2.string().regex(SHA256_HEX),
+  source_bytes: z2.number().int().nonnegative(),
+  model: z2.string().min(1)
+});
+var FeedOutputSchema = z2.object({
+  skills_added: z2.array(z2.string()),
+  skills_updated: z2.array(z2.string()),
+  skills_removed: z2.array(z2.string()),
+  skills_md_sha256: z2.string().regex(SHA256_HEX),
+  skills_md_bytes: z2.number().int().nonnegative()
+});
+var AgentCreatedInputSchema = z2.object({ name: z2.string() });
+var AgentCreatedOutputSchema = z2.object({ agent_id: z2.string().min(1) });
+var BoundInputSchema = z2.object({
+  skills_md_sha256: z2.string().regex(SHA256_HEX),
+  aspiration_sha256s: z2.array(z2.string().regex(SHA256_HEX))
+});
+var BoundOutputSchema = z2.object({
+  registry_url: z2.string().url(),
+  bound_at: z2.string().min(1)
+});
+var AspirationAddedInputSchema = z2.object({
+  aspiration_sha256: z2.string().regex(SHA256_HEX),
+  aspiration_bytes: z2.number().int().nonnegative(),
+  source: z2.string().min(1)
+});
+var AspirationAddedOutputSchema = z2.object({
+  registry_url: z2.string().url()
+});
+var BaseEntryFieldsSchema = {
+  schema_version: z2.literal(PROVENANCE_SCHEMA_VERSION),
+  seq: z2.number().int().positive(),
+  ts: z2.string().min(1),
+  prev: z2.union([z2.string().regex(SHA256_HEX), z2.null()]),
+  entry_sha256: z2.string().regex(SHA256_HEX)
+};
+var FeedEntrySchema = z2.object({
+  ...BaseEntryFieldsSchema,
+  kind: z2.literal("feed"),
+  input: FeedInputSchema,
+  output: FeedOutputSchema
+});
+var AgentCreatedEntrySchema = z2.object({
+  ...BaseEntryFieldsSchema,
+  kind: z2.literal("agent_created"),
+  input: AgentCreatedInputSchema,
+  output: AgentCreatedOutputSchema
+});
+var BoundEntrySchema = z2.object({
+  ...BaseEntryFieldsSchema,
+  kind: z2.literal("bound"),
+  input: BoundInputSchema,
+  output: BoundOutputSchema
+});
+var AspirationAddedEntrySchema = z2.object({
+  ...BaseEntryFieldsSchema,
+  kind: z2.literal("aspiration_added"),
+  input: AspirationAddedInputSchema,
+  output: AspirationAddedOutputSchema
+});
+var ProvenanceEntrySchema = z2.discriminatedUnion("kind", [
+  FeedEntrySchema,
+  AgentCreatedEntrySchema,
+  BoundEntrySchema,
+  AspirationAddedEntrySchema
+]);
+var KNOWN_ENTRY_KINDS = [
+  "feed",
+  "agent_created",
+  "bound",
+  "aspiration_added"
+];
+var ProvenanceError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ProvenanceError";
+  }
+};
+function sha256Hex(input) {
+  return createHash("sha256").update(input, "utf8").digest("hex");
+}
+function computeEntryHash(entry) {
+  return sha256Hex(canonicalize(entry));
+}
+async function readChain(path) {
+  let raw;
+  try {
+    raw = await readFile4(path, "utf8");
+  } catch (err) {
+    const e = err;
+    if (e.code === "ENOENT") return [];
+    throw err;
+  }
+  if (raw.length === 0) return [];
+  const lines = raw.split("\n").filter((l) => l.length > 0);
+  const entries = [];
+  for (let i = 0; i < lines.length; i++) {
+    let parsedJson;
+    try {
+      parsedJson = JSON.parse(lines[i]);
+    } catch (err) {
+      throw new ProvenanceError(`Line ${i + 1}: invalid JSON (${err.message})`);
+    }
+    if (parsedJson !== null && typeof parsedJson === "object" && "schema_version" in parsedJson && parsedJson.schema_version === 0) {
+      throw new ProvenanceError(
+        `Line ${i + 1}: provenance entry has schema_version=0 (modex-cli@0.1.x, Phase B). v1 (Phase C) is not backward-compatible: the feed entry shape gained source_kind and source_url. Create a fresh agent under .modex/, or pin to @modexagents/cli@0.1.x for legacy agents.`
+      );
+    }
+    if (parsedJson !== null && typeof parsedJson === "object" && "kind" in parsedJson && typeof parsedJson.kind === "string" && !KNOWN_ENTRY_KINDS.includes(parsedJson.kind)) {
+      throw new ProvenanceError(
+        `Line ${i + 1}: provenance entry kind '${parsedJson.kind}' is not recognized by this build of modex-cli. It was likely written by a newer version \u2014 upgrade modex-cli to read this chain.`
+      );
+    }
+    const result = ProvenanceEntrySchema.safeParse(parsedJson);
+    if (!result.success) {
+      throw new ProvenanceError(
+        `Line ${i + 1}: schema mismatch (${result.error.issues.map((iss) => `${iss.path.join(".")}: ${iss.message}`).join("; ")})`
+      );
+    }
+    entries.push(result.data);
+  }
+  return entries;
+}
+function verifyChain(entries) {
+  let expectedPrev = null;
+  for (let i = 0; i < entries.length; i++) {
+    const e = entries[i];
+    if (e.seq !== i + 1) {
+      throw new ProvenanceError(
+        `Entry ${i}: expected seq=${i + 1}, got seq=${e.seq}`
+      );
+    }
+    if (e.prev !== expectedPrev) {
+      throw new ProvenanceError(
+        `Entry ${i} (seq=${e.seq}): prev=${e.prev ?? "null"} does not match previous entry_sha256=${expectedPrev ?? "null"}`
+      );
+    }
+    const { entry_sha256, ...rest } = e;
+    const recomputed = computeEntryHash(rest);
+    if (recomputed !== entry_sha256) {
+      throw new ProvenanceError(
+        `Entry ${i} (seq=${e.seq}): entry_sha256 mismatch (stored=${entry_sha256}, recomputed=${recomputed})`
+      );
+    }
+    expectedPrev = entry_sha256;
+  }
+}
+async function recordEntry(opts) {
+  return withFileLock(
+    opts.path,
+    async () => {
+      let seq = opts.seq;
+      let prev = opts.prev;
+      if (seq === void 0 || prev === void 0) {
+        const existing = await readChain(opts.path);
+        seq = seq ?? existing.length + 1;
+        prev = prev ?? (existing.length === 0 ? null : existing[existing.length - 1].entry_sha256);
+      }
+      const ts = opts.ts ?? opts.draft.ts ?? (/* @__PURE__ */ new Date()).toISOString();
+      const skeleton = {
+        schema_version: PROVENANCE_SCHEMA_VERSION,
+        seq,
+        ts,
+        kind: opts.draft.kind,
+        input: opts.draft.input,
+        output: opts.draft.output,
+        prev
+      };
+      const validation = ProvenanceEntrySchema.safeParse({
+        ...skeleton,
+        entry_sha256: "0".repeat(64)
+      });
+      if (!validation.success) {
+        throw new ProvenanceError(
+          `Invalid entry: ${validation.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+        );
+      }
+      const entry_sha256 = computeEntryHash(skeleton);
+      const full = { ...skeleton, entry_sha256 };
+      const line = canonicalize(full) + "\n";
+      await appendFile(opts.path, line, "utf8");
+      return full;
+    },
+    opts.lock
+  );
+}
+
+// src/agent.ts
+var AGENT_CONFIG_SCHEMA_VERSION = 0;
+var DEFAULT_TOKEN_CAP_WARN_AT = 32e3;
+var MODEX_DIR_NAME = ".modex";
+var UUID7_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var AgentConfigSchema = z3.object({
+  schema_version: z3.literal(AGENT_CONFIG_SCHEMA_VERSION),
+  id: z3.string().regex(UUID7_PATTERN, "agent id must be a UUIDv7"),
+  name: z3.string(),
+  created_at: z3.string().min(1),
+  token_cap_warn_at: z3.number().int().positive()
+});
+var AgentError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AgentError";
+  }
+};
+function modexDir(baseDir) {
+  return join(baseDir, MODEX_DIR_NAME);
+}
+function agentPaths(baseDir, id) {
+  const dir = join(modexDir(baseDir), id);
+  return {
+    dir,
+    configFile: join(dir, "config.json"),
+    skillsFile: join(dir, "skills.md"),
+    provenanceFile: join(dir, "provenance.jsonl"),
+    registryFile: join(dir, "registry.json")
+  };
+}
+async function writeJsonAtomic(path, value) {
+  const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+  await writeFile(tmp, JSON.stringify(value, null, 2) + "\n", "utf8");
+  await rename(tmp, path);
+}
+async function writeSkillsAtomic(path, content) {
+  const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+  await writeFile(tmp, content, "utf8");
+  await rename(tmp, path);
+}
+async function ensureModexGitignore(baseDir) {
+  const gitignorePath = join(modexDir(baseDir), ".gitignore");
+  try {
+    await writeFile(gitignorePath, "*.lock\n", { flag: "wx" });
+  } catch (err) {
+    if (err.code !== "EEXIST") throw err;
+  }
+}
+async function createAgent(opts = {}) {
+  const baseDir = opts.baseDir ?? process.cwd();
+  const id = opts.id ?? uuidv7();
+  const created_at = opts.ts ?? (/* @__PURE__ */ new Date()).toISOString();
+  const name = opts.name ?? "";
+  const token_cap_warn_at = opts.tokenCapWarnAt ?? DEFAULT_TOKEN_CAP_WARN_AT;
+  const paths = agentPaths(baseDir, id);
+  await mkdir(paths.dir, { recursive: true });
+  await ensureModexGitignore(baseDir);
+  const config = {
+    schema_version: AGENT_CONFIG_SCHEMA_VERSION,
+    id,
+    name,
+    created_at,
+    token_cap_warn_at
+  };
+  await writeJsonAtomic(paths.configFile, config);
+  await recordEntry({
+    path: paths.provenanceFile,
+    draft: {
+      kind: "agent_created",
+      input: { name },
+      output: { agent_id: id }
+    },
+    ts: created_at
+  });
+  return { config, paths };
+}
+async function loadAgent(id, baseDir) {
+  const root = baseDir ?? process.cwd();
+  const paths = agentPaths(root, id);
+  let raw;
+  try {
+    raw = await readFile5(paths.configFile, "utf8");
+  } catch (err) {
+    const e = err;
+    if (e.code === "ENOENT") {
+      throw new AgentError(
+        `Agent '${id}' not found at ${paths.configFile}. Run 'modex agents create' first, or 'modex agents list' to see existing agents.`
+      );
+    }
+    throw err;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new AgentError(`Agent '${id}' has invalid config.json: ${err.message}`);
+  }
+  const result = AgentConfigSchema.safeParse(parsed);
+  if (!result.success) {
+    throw new AgentError(
+      `Agent '${id}' config.json failed validation: ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+    );
+  }
+  return { config: result.data, paths };
+}
+async function listAgents(baseDir) {
+  const root = baseDir ?? process.cwd();
+  const dir = modexDir(root);
+  let entries;
+  try {
+    entries = await readdir(dir);
+  } catch (err) {
+    const e = err;
+    if (e.code === "ENOENT") return [];
+    throw err;
+  }
+  const records = [];
+  for (const name of entries) {
+    if (!UUID7_PATTERN.test(name)) continue;
+    const candidate = join(dir, name);
+    let s;
+    try {
+      s = await stat2(candidate);
+    } catch {
+      continue;
+    }
+    if (!s.isDirectory()) continue;
+    try {
+      records.push(await loadAgent(name, root));
+    } catch {
+      continue;
+    }
+  }
+  records.sort((a, b) => a.config.created_at < b.config.created_at ? -1 : 1);
+  return records;
+}
+async function readAgentSkills(skillsFile) {
+  let raw;
+  try {
+    raw = await readFile5(skillsFile, "utf8");
+  } catch (err) {
+    const e = err;
+    if (e.code === "ENOENT") return [];
+    throw err;
+  }
+  return parseSkills(raw).skills;
+}
+
+// src/tokenEstimate.ts
+function estimateTokens(text) {
+  let count = 0;
+  for (const _ of text) count++;
+  return Math.ceil(count / 4);
+}
+
+// src/operations/feed.ts
+function sha256Hex2(text) {
+  return createHash2("sha256").update(text, "utf8").digest("hex");
+}
+function resolveTs(ts) {
+  if (ts === void 0) return (/* @__PURE__ */ new Date()).toISOString();
+  if (typeof ts === "function") return ts();
+  return ts;
+}
+async function runFeed(agentId, patterns, opts = {}) {
+  const stdout = opts.stdout ?? process.stdout;
+  const stderr = opts.stderr ?? process.stderr;
+  const agent = await loadAgent(agentId, opts.baseDir);
+  const targets = await expandPatterns(patterns, { cwd: opts.baseDir });
+  const loader = opts.loadSource ?? readSource;
+  const perSource = [];
+  for (let i = 0; i < targets.length; i++) {
+    const target = targets[i];
+    const loaded = await loader(target);
+    const incoming = await extractSkills(loaded.content, {
+      source: loaded.source,
+      model: opts.model,
+      apiKey: opts.apiKey,
+      client: opts.client
+    });
+    const existing = await readAgentSkills(agent.paths.skillsFile);
+    const { merged, added, updated } = mergeSkills(existing, incoming);
+    const skillsMd = serialize(buildDoc(merged));
+    await writeSkillsAtomic(agent.paths.skillsFile, skillsMd);
+    const skillsMdSha256 = sha256Hex2(skillsMd);
+    const skillsMdBytes = Buffer.byteLength(skillsMd, "utf8");
+    const sourceSha256 = sha256Hex2(loaded.content);
+    const sourceBytes = Buffer.byteLength(loaded.content, "utf8");
+    await recordEntry({
+      path: agent.paths.provenanceFile,
+      draft: {
+        kind: "feed",
+        input: {
+          source: loaded.source,
+          source_url: loaded.source_url,
+          source_kind: loaded.source_kind,
+          source_sha256: sourceSha256,
+          source_bytes: sourceBytes,
+          model: opts.model ?? MODEL_ID
+        },
+        output: {
+          skills_added: added,
+          skills_updated: updated,
+          skills_removed: [],
+          skills_md_sha256: skillsMdSha256,
+          skills_md_bytes: skillsMdBytes
+        }
+      },
+      ts: resolveTs(opts.ts)
+    });
+    const estimatedTokens = estimateTokens(skillsMd);
+    const warnedOverCap = estimatedTokens >= agent.config.token_cap_warn_at;
+    if (warnedOverCap) {
+      stderr.write(
+        `warning: skills.md is ~${estimatedTokens} tokens (cap: ${agent.config.token_cap_warn_at}). Consider splitting into multiple agents.
+`
+      );
+    }
+    stdout.write(
+      `[${i + 1}/${targets.length}] ${loaded.source}: +${added.length} added, ${updated.length} updated, sha256=${skillsMdSha256.slice(0, 12)}
+`
+    );
+    perSource.push({
+      target,
+      source: loaded.source,
+      added,
+      updated,
+      skillsMdSha256,
+      skillsMdBytes,
+      estimatedTokens,
+      warnedOverCap
+    });
+  }
+  const totalAdded = perSource.reduce((n, r) => n + r.added.length, 0);
+  const totalUpdated = perSource.reduce((n, r) => n + r.updated.length, 0);
+  stdout.write(
+    `done: ${perSource.length} source${perSource.length === 1 ? "" : "s"}, ${totalAdded} added, ${totalUpdated} updated total
+`
+  );
+  return { agentId: agent.config.id, perSource };
+}
+function isFeedError(err) {
+  return err instanceof ExtractionError || err instanceof SourceError || err instanceof AgentError || err instanceof ParseSkillsError || err instanceof ProvenanceError;
+}
+
+// src/operations/agents.ts
+async function runAgentsCreate(opts = {}) {
+  const stdout = opts.stdout ?? process.stdout;
+  const agent = await createAgent({ name: opts.name, baseDir: opts.baseDir });
+  stdout.write(`${agent.config.id}
+`);
+  return agent.config.id;
+}
+async function runAgentsList(opts = {}) {
+  const stdout = opts.stdout ?? process.stdout;
+  const agents = await listAgents(opts.baseDir);
+  if (agents.length === 0) {
+    stdout.write("(no agents in this directory \u2014 run `modex agents create` to make one)\n");
+    return;
+  }
+  for (const a of agents) {
+    const skills = await readAgentSkills(a.paths.skillsFile);
+    const name = a.config.name.length > 0 ? a.config.name : "(unnamed)";
+    stdout.write(`${a.config.id}	${name}	${a.config.created_at}	${skills.length} skills
+`);
+  }
+}
+
+// src/credentials.ts
+import { chmod, mkdir as mkdir2, readFile as readFile6, rename as rename2, unlink as unlink2, writeFile as writeFile2 } from "fs/promises";
+import { homedir } from "os";
+import { join as join2 } from "path";
+import { z as z4 } from "zod";
+var CREDENTIALS_SCHEMA_VERSION = 1;
+var DEFAULT_REGISTRY_URL = "https://registry.modex.md";
+var CredentialsSchema = z4.object({
+  schema_version: z4.literal(CREDENTIALS_SCHEMA_VERSION),
+  access_token: z4.string().min(1),
+  registry_url: z4.string().url()
+});
+var CredentialsError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CredentialsError";
+  }
+};
+function configDir() {
+  const xdg = process.env["XDG_CONFIG_HOME"];
+  const base = xdg && xdg.length > 0 ? xdg : join2(homedir(), ".config");
+  return join2(base, "modex");
+}
+function credentialsPath(dir = configDir()) {
+  return join2(dir, "credentials.json");
+}
+async function loadCredentials(dir = configDir()) {
+  const path = credentialsPath(dir);
+  let raw;
+  try {
+    raw = await readFile6(path, "utf8");
+  } catch (err) {
+    const e = err;
+    if (e.code === "ENOENT") return null;
+    throw new CredentialsError(`Could not read ${path}: ${e.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new CredentialsError(`${path} is not valid JSON: ${err.message}`);
+  }
+  const result = CredentialsSchema.safeParse(parsed);
+  if (!result.success) {
+    throw new CredentialsError(
+      `${path} failed validation: ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+    );
+  }
+  return result.data;
+}
+async function saveCredentials(credentials, dir = configDir()) {
+  await mkdir2(dir, { recursive: true, mode: 448 });
+  const path = credentialsPath(dir);
+  const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+  const body = JSON.stringify(credentials, null, 2) + "\n";
+  await writeFile2(tmp, body, { mode: 384, encoding: "utf8" });
+  await chmod(tmp, 384);
+  await rename2(tmp, path);
+  await chmod(path, 384);
+}
+async function clearCredentials(dir = configDir()) {
+  try {
+    await unlink2(credentialsPath(dir));
+  } catch (err) {
+    const e = err;
+    if (e.code === "ENOENT") return;
+    throw new CredentialsError(`Could not clear credentials: ${e.message}`);
+  }
+}
+
+// src/registry/types.ts
+import { z as z5 } from "zod";
+var RegistryError = class extends Error {
+  // HTTP status, or null for transport-level failures (DNS, connection reset).
+  status;
+  // The `error` field from a structured error body, if the registry sent one.
+  code;
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = "RegistryError";
+    this.status = opts.status ?? null;
+    this.code = opts.code ?? null;
+  }
+};
+var DeviceCodeStartSchema = z5.object({
+  device_code: z5.string().min(1),
+  user_code: z5.string().min(1),
+  verify_url: z5.string().url(),
+  expires_in: z5.number().int().positive(),
+  interval: z5.number().int().positive()
+});
+var TokenResponseSchema = z5.union([
+  z5.object({ access_token: z5.string().min(1) }),
+  z5.object({ error: z5.string().min(1) })
+]);
+var BindResponseSchema = z5.object({
+  skills_md_sha256: z5.string().min(1),
+  bound_at: z5.string().min(1)
+}).passthrough();
+var AspirationResponseSchema = z5.object({
+  created_at: z5.string().min(1).optional()
+}).passthrough();
+
+// src/registry/client.ts
+var SLOW_DOWN_INCREMENT_S = 5;
+function resolveDeps(deps = {}) {
+  return {
+    fetch: deps.fetch ?? globalThis.fetch,
+    sleep: deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms))),
+    now: deps.now ?? Date.now
+  };
+}
+function endpoint(registryUrl, path) {
+  return registryUrl.replace(/\/+$/, "") + path;
+}
+async function postJson(fetchImpl, url, body, token) {
+  const headers = { "content-type": "application/json" };
+  if (token) headers["authorization"] = `Bearer ${token}`;
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body)
+    });
+  } catch (err) {
+    throw new RegistryError(
+      `Could not reach the registry at ${url}: ${err.message}`,
+      { status: null }
+    );
+  }
+  let json = null;
+  const text = await response.text();
+  if (text.length > 0) {
+    try {
+      json = JSON.parse(text);
+    } catch {
+    }
+  }
+  return { status: response.status, json };
+}
+function bodyErrorCode(json) {
+  if (json !== null && typeof json === "object" && "error" in json) {
+    const code = json.error;
+    return typeof code === "string" ? code : null;
+  }
+  return null;
+}
+async function startDeviceCode(registryUrl, deps) {
+  const { fetch } = resolveDeps(deps);
+  const { status, json } = await postJson(
+    fetch,
+    endpoint(registryUrl, "/v1/auth/cli/device-code"),
+    {}
+  );
+  if (status !== 200) {
+    throw new RegistryError(
+      `Registry rejected the device-code request (HTTP ${status}).`,
+      { status, code: bodyErrorCode(json) }
+    );
+  }
+  const parsed = DeviceCodeStartSchema.safeParse(json);
+  if (!parsed.success) {
+    throw new RegistryError(
+      `Registry device-code response was malformed: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`,
+      { status }
+    );
+  }
+  return parsed.data;
+}
+async function pollForToken(registryUrl, start, deps) {
+  const { fetch, sleep: sleep2, now } = resolveDeps(deps);
+  const onPending = deps?.onPending;
+  const deadline = now() + start.expires_in * 1e3;
+  let intervalS = start.interval;
+  const url = endpoint(registryUrl, "/v1/auth/cli/token");
+  for (; ; ) {
+    if (now() >= deadline) {
+      throw new RegistryError(
+        "The login code expired before it was approved. Run `modex login` again.",
+        { code: "expired_token" }
+      );
+    }
+    await sleep2(intervalS * 1e3);
+    const { status, json } = await postJson(fetch, url, { device_code: start.device_code });
+    const parsed = TokenResponseSchema.safeParse(json);
+    if (parsed.success && "access_token" in parsed.data) {
+      return parsed.data.access_token;
+    }
+    const code = parsed.success && "error" in parsed.data ? parsed.data.error : bodyErrorCode(json);
+    if (code === "authorization_pending") {
+      onPending?.();
+      continue;
+    }
+    if (code === "slow_down") {
+      intervalS += SLOW_DOWN_INCREMENT_S;
+      onPending?.();
+      continue;
+    }
+    throw new RegistryError(
+      code ? `Registry refused the login: ${code}.` : `Registry token endpoint returned an unexpected response (HTTP ${status}).`,
+      { status, code: code ?? null }
+    );
+  }
+}
+async function bindAgent(registryUrl, agentId, token, body, deps) {
+  const { fetch } = resolveDeps(deps);
+  const { status, json } = await postJson(
+    fetch,
+    endpoint(registryUrl, `/v1/agents/${encodeURIComponent(agentId)}/bind`),
+    body,
+    token
+  );
+  if (status === 401) {
+    throw new RegistryError("Your registry token is no longer valid.", { status, code: bodyErrorCode(json) });
+  }
+  if (status === 409) {
+    throw new RegistryError(
+      `Agent ${agentId} is already bound to a different user. Re-bind is only allowed by the user who first claimed it.`,
+      { status, code: bodyErrorCode(json) }
+    );
+  }
+  if (status < 200 || status >= 300) {
+    throw new RegistryError(
+      `Registry rejected the bind (HTTP ${status}).`,
+      { status, code: bodyErrorCode(json) }
+    );
+  }
+  const parsed = BindResponseSchema.safeParse(json);
+  if (!parsed.success) {
+    throw new RegistryError(
+      `Registry bind response was malformed: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`,
+      { status }
+    );
+  }
+  return parsed.data;
+}
+async function addAspiration(registryUrl, agentId, token, body, deps) {
+  const { fetch } = resolveDeps(deps);
+  const { status, json } = await postJson(
+    fetch,
+    endpoint(registryUrl, `/v1/agents/${encodeURIComponent(agentId)}/aspirations`),
+    body,
+    token
+  );
+  if (status === 401) {
+    throw new RegistryError("Your registry token is no longer valid.", { status, code: bodyErrorCode(json) });
+  }
+  if (status === 404) {
+    throw new RegistryError(
+      `Agent ${agentId} is not bound on the registry. Run \`modex bind ${agentId}\` first.`,
+      { status, code: bodyErrorCode(json) }
+    );
+  }
+  if (status < 200 || status >= 300) {
+    throw new RegistryError(
+      `Registry rejected the aspiration (HTTP ${status}).`,
+      { status, code: bodyErrorCode(json) }
+    );
+  }
+  const parsed = AspirationResponseSchema.safeParse(json ?? {});
+  if (!parsed.success) {
+    throw new RegistryError(
+      `Registry aspiration response was malformed: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`,
+      { status }
+    );
+  }
+  return parsed.data;
+}
+
+// src/operations/login.ts
+async function runLogin(opts = {}) {
+  const stdout = opts.stdout ?? process.stdout;
+  const registryUrl = opts.registry ?? DEFAULT_REGISTRY_URL;
+  const deps = { fetch: opts.fetch, sleep: opts.sleep, now: opts.now };
+  const start = await startDeviceCode(registryUrl, deps);
+  stdout.write(
+    `To authorize this CLI, open:
+  ${start.verify_url}
+and enter the code:
+  ${start.user_code}
+
+Waiting for approval\u2026
+`
+  );
+  const accessToken = await pollForToken(registryUrl, start, {
+    ...deps,
+    onPending: () => stdout.write(".")
+  });
+  stdout.write("\n");
+  await saveCredentials(
+    { schema_version: 1, access_token: accessToken, registry_url: registryUrl },
+    opts.configDir
+  );
+  stdout.write(`Logged in to ${registryUrl}.
+`);
+  return { registryUrl };
+}
+async function runLogout(opts = {}) {
+  const stdout = opts.stdout ?? process.stdout;
+  await clearCredentials(opts.configDir);
+  stdout.write("Logged out. Local credentials cleared.\n");
+}
+function isLoginError(err) {
+  return err instanceof RegistryError || err instanceof CredentialsError;
+}
+
+// src/operations/bind.ts
+import { createHash as createHash3 } from "crypto";
+import { readFile as readFile8 } from "fs/promises";
+
+// src/registryState.ts
+import { readFile as readFile7, rename as rename3, writeFile as writeFile3 } from "fs/promises";
+import { z as z6 } from "zod";
+var REGISTRY_STATE_SCHEMA_VERSION = 1;
+var SHA256_HEX2 = /^[0-9a-f]{64}$/;
+var RegistryStateSchema = z6.object({
+  schema_version: z6.literal(REGISTRY_STATE_SCHEMA_VERSION),
+  registry_url: z6.string().url(),
+  agent_id: z6.string().min(1),
+  bound_at: z6.string().min(1),
+  last_server_skills_md_sha256: z6.string().regex(SHA256_HEX2)
+});
+var RegistryStateError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RegistryStateError";
+  }
+};
+async function readRegistryState(path) {
+  let raw;
+  try {
+    raw = await readFile7(path, "utf8");
+  } catch (err) {
+    const e = err;
+    if (e.code === "ENOENT") return null;
+    throw new RegistryStateError(`Could not read ${path}: ${e.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new RegistryStateError(`${path} is not valid JSON: ${err.message}`);
+  }
+  const result = RegistryStateSchema.safeParse(parsed);
+  if (!result.success) {
+    throw new RegistryStateError(
+      `${path} failed validation: ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+    );
+  }
+  return result.data;
+}
+async function writeRegistryState(path, state) {
+  const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+  await writeFile3(tmp, JSON.stringify(state, null, 2) + "\n", "utf8");
+  await rename3(tmp, path);
+}
+
+// src/operations/bind.ts
+var isAspirationAdded = (e) => e.kind === "aspiration_added";
+function sha256Hex3(text) {
+  return createHash3("sha256").update(text, "utf8").digest("hex");
+}
+async function runBind(agentId, opts = {}) {
+  const stdout = opts.stdout ?? process.stdout;
+  const credentials = await loadCredentials(opts.configDir);
+  if (credentials === null) {
+    throw new CredentialsError("Not logged in. Run `modex login` first.");
+  }
+  const agent = await loadAgent(agentId, opts.baseDir);
+  let skillsMd;
+  try {
+    skillsMd = await readFile8(agent.paths.skillsFile, "utf8");
+  } catch (err) {
+    const e = err;
+    if (e.code !== "ENOENT") throw err;
+    skillsMd = serialize(buildDoc(await readAgentSkills(agent.paths.skillsFile)));
+  }
+  const skillsMdSha256 = sha256Hex3(skillsMd);
+  const chain = await readChain(agent.paths.provenanceFile);
+  if (chain.length === 0) {
+    throw new AgentError(
+      `Agent ${agentId} has an empty provenance chain \u2014 cannot bind. The chain should always contain at least the agent_created entry.`
+    );
+  }
+  const provenanceHead = chain[chain.length - 1].entry_sha256;
+  const aspirationSha256s = chain.filter(isAspirationAdded).map((e) => e.input.aspiration_sha256);
+  let response;
+  try {
+    response = await bindAgent(
+      credentials.registry_url,
+      agent.config.id,
+      credentials.access_token,
+      {
+        skills_md: skillsMd,
+        skills_md_sha256: skillsMdSha256,
+        provenance_head_sha256: provenanceHead,
+        aspiration_sha256s: aspirationSha256s
+      },
+      { fetch: opts.fetch }
+    );
+  } catch (err) {
+    if (err instanceof RegistryError && err.status === 401) {
+      await clearCredentials(opts.configDir);
+      throw new RegistryError(
+        "Your registry token is no longer valid and has been cleared. Run `modex login` again.",
+        { status: 401 }
+      );
+    }
+    throw err;
+  }
+  await recordEntry({
+    path: agent.paths.provenanceFile,
+    draft: {
+      kind: "bound",
+      input: {
+        skills_md_sha256: skillsMdSha256,
+        aspiration_sha256s: aspirationSha256s
+      },
+      output: {
+        registry_url: credentials.registry_url,
+        bound_at: response.bound_at
+      }
+    },
+    ts: opts.ts
+  });
+  await writeRegistryState(agent.paths.registryFile, {
+    schema_version: 1,
+    registry_url: credentials.registry_url,
+    agent_id: agent.config.id,
+    bound_at: response.bound_at,
+    last_server_skills_md_sha256: response.skills_md_sha256
+  });
+  stdout.write(
+    `Bound ${agent.config.id} to ${credentials.registry_url}
+  skills.md sha256: ${skillsMdSha256.slice(0, 12)}\u2026
+  bound_at:         ${response.bound_at}
+`
+  );
+  return {
+    agentId: agent.config.id,
+    registryUrl: credentials.registry_url,
+    skillsMdSha256,
+    boundAt: response.bound_at
+  };
+}
+function isBindError(err) {
+  return err instanceof RegistryError || err instanceof CredentialsError || err instanceof AgentError || err instanceof ProvenanceError || err instanceof RegistryStateError;
+}
+
+// src/operations/aspirations.ts
+import { createHash as createHash4 } from "crypto";
+import { readFile as readFile9 } from "fs/promises";
+import { basename as basename4 } from "path";
+function sha256Hex4(text) {
+  return createHash4("sha256").update(text, "utf8").digest("hex");
+}
+async function runAspirationsAdd(agentId, mdFile, opts = {}) {
+  const stdout = opts.stdout ?? process.stdout;
+  const credentials = await loadCredentials(opts.configDir);
+  if (credentials === null) {
+    throw new CredentialsError("Not logged in. Run `modex login` first.");
+  }
+  const agent = await loadAgent(agentId, opts.baseDir);
+  const registryState = await readRegistryState(agent.paths.registryFile);
+  if (registryState === null) {
+    throw new AgentError(
+      `Agent ${agentId} is not bound to a registry. Run \`modex bind ${agentId}\` first.`
+    );
+  }
+  let content;
+  try {
+    content = await readFile9(mdFile, "utf8");
+  } catch (err) {
+    throw new AgentError(`Could not read aspiration file ${mdFile}: ${err.message}`);
+  }
+  if (content.trim().length === 0) {
+    throw new AgentError(`Aspiration file ${mdFile} is empty.`);
+  }
+  const aspirationSha256 = sha256Hex4(content);
+  const source = basename4(mdFile);
+  try {
+    await addAspiration(
+      registryState.registry_url,
+      agent.config.id,
+      credentials.access_token,
+      { sha256: aspirationSha256, content },
+      { fetch: opts.fetch }
+    );
+  } catch (err) {
+    if (err instanceof RegistryError && err.status === 401) {
+      await clearCredentials(opts.configDir);
+      throw new RegistryError(
+        "Your registry token is no longer valid and has been cleared. Run `modex login` again.",
+        { status: 401 }
+      );
+    }
+    throw err;
+  }
+  await recordEntry({
+    path: agent.paths.provenanceFile,
+    draft: {
+      kind: "aspiration_added",
+      input: {
+        aspiration_sha256: aspirationSha256,
+        aspiration_bytes: Buffer.byteLength(content, "utf8"),
+        source
+      },
+      output: {
+        registry_url: registryState.registry_url
+      }
+    },
+    ts: opts.ts
+  });
+  stdout.write(
+    `Added aspiration to ${agent.config.id}
+  source: ${source}
+  sha256: ${aspirationSha256.slice(0, 12)}\u2026
+`
+  );
+  return {
+    agentId: agent.config.id,
+    registryUrl: registryState.registry_url,
+    aspirationSha256,
+    source
+  };
+}
+function isAspirationsError(err) {
+  return err instanceof RegistryError || err instanceof CredentialsError || err instanceof AgentError || err instanceof ProvenanceError || err instanceof RegistryStateError;
+}
+
+// src/operations/index.ts
+function isUserFacingError(err) {
+  return isFeedError(err) || isLoginError(err) || isBindError(err) || isAspirationsError(err);
+}
+export {
+  AGENT_CONFIG_SCHEMA_VERSION,
+  AgentConfigSchema,
+  AgentCreatedEntrySchema,
+  AgentError,
+  AspirationAddedEntrySchema,
+  BoundEntrySchema,
+  CREDENTIALS_SCHEMA_VERSION,
+  CanonicalJsonError,
+  CredentialsError,
+  CredentialsSchema,
+  DEFAULT_LOCK_TIMEOUT_MS,
+  DEFAULT_REGISTRY_URL,
+  DEFAULT_STALE_MS,
+  DEFAULT_TOKEN_CAP_WARN_AT,
+  EMIT_SKILLS_TOOL,
+  ExtractedSkillSchema,
+  ExtractionError,
+  ExtractionResultSchema,
+  FeedEntrySchema,
+  FileLockError,
+  KNOWN_ENTRY_KINDS,
+  MODEL_ID,
+  MODEX_DIR_NAME,
+  PROVENANCE_SCHEMA_VERSION,
+  ParseSkillsError,
+  ProvenanceEntrySchema,
+  ProvenanceError,
+  REGISTRY_STATE_SCHEMA_VERSION,
+  RegistryError,
+  RegistryStateError,
+  RegistryStateSchema,
+  SCHEMA_VERSION,
+  SOURCE_KINDS,
+  SYSTEM_PROMPT,
+  SkillSchema,
+  SkillsDocSchema,
+  SourceError,
+  addAspiration,
+  bindAgent,
+  buildDoc,
+  canonicalize,
+  clearCredentials,
+  computeEntryHash,
+  configDir,
+  createAgent,
+  credentialsPath,
+  estimateTokens,
+  expandPatterns,
+  extractSkills,
+  isAspirationsError,
+  isBindError,
+  isFeedError,
+  isLoginError,
+  isUserFacingError,
+  isWebUrl,
+  listAgents,
+  loadAgent,
+  loadCredentials,
+  mergeSkills,
+  normalizeUrl,
+  parseSkills,
+  pollForToken,
+  readAgentSkills,
+  readChain,
+  readRegistryState,
+  readSource,
+  recordEntry,
+  runAgentsCreate,
+  runAgentsList,
+  runAspirationsAdd,
+  runBind,
+  runFeed,
+  runLogin,
+  runLogout,
+  saveCredentials,
+  serialize,
+  startDeviceCode,
+  verifyChain,
+  withFileLock,
+  writeRegistryState,
+  writeSkillsAtomic
+};
+//# sourceMappingURL=index.js.map