contentbit 0.1.1 → 0.3.0

package/dist/run.js

@@ -319,6 +319,383 @@ var init_parser = __esm({
   }
 });
 
+// ../core/dist/frontmatter.js
+function stripFrontmatter(source) {
+  const match = FM_RE.exec(source);
+  if (!match)
+    return source;
+  return match[0].replace(/[^\n]+/g, "") + source.slice(match[0].length);
+}
+function extractFrontmatter(source) {
+  const match = source.match(FM_RE);
+  if (!match)
+    return null;
+  const blockLines = match[0].replace(/\r?\n$/, "").split(/\r?\n/);
+  const inner = blockLines.slice(1, -1);
+  const { data, keys } = parseYamlSubset(inner);
+  return { raw: inner.join("\n"), data, keys, lines: { start: 1, end: blockLines.length } };
+}
+function parseYamlSubset(lines) {
+  const data = {};
+  const keys = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#") || /^[ \t]/.test(line)) {
+      i++;
+      continue;
+    }
+    const m = line.match(KEY_RE2);
+    if (!m) {
+      i++;
+      continue;
+    }
+    const [, key, rawValue] = m;
+    const value = rawValue.trim();
+    i++;
+    const indented = [];
+    while (i < lines.length && /^[ \t]/.test(lines[i]) && lines[i].trim() !== "") {
+      indented.push(lines[i]);
+      i++;
+    }
+    keys.push(key);
+    data[key] = parseValue(value, indented);
+  }
+  return { data, keys };
+}
+function parseValue(value, indented) {
+  if (/^[|>][+-]?$/.test(value))
+    return dedent(indented).join("\n");
+  if (value === "") {
+    if (indented.length === 0)
+      return null;
+    const items = dedent(indented);
+    const list = parseDashList(items);
+    if (list)
+      return list;
+    const mapping = parseNestedMapping(items);
+    if (mapping)
+      return mapping;
+    return items.join("\n");
+  }
+  return parseScalar(value);
+}
+function parseNestedMapping(items) {
+  const out = {};
+  for (const line of items) {
+    if (/^[ \t]/.test(line))
+      return null;
+    const m = line.match(KEY_RE2);
+    if (!m)
+      return null;
+    const [, key, rawValue] = m;
+    const v = rawValue.trim();
+    if (v === "")
+      return null;
+    out[key] = parseScalar(v);
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}
+function parseDashList(items) {
+  const groups = [];
+  let current = null;
+  for (const line of items) {
+    if (line.startsWith("- ")) {
+      if (current)
+        groups.push(current);
+      current = [line.slice(2)];
+    } else if (current && /^[ \t]/.test(line)) {
+      current.push(line);
+    } else {
+      return null;
+    }
+  }
+  if (current)
+    groups.push(current);
+  return groups.map((group) => parseDashItem(group));
+}
+function parseDashItem(lines) {
+  const first = lines[0].trim();
+  if (lines.length === 1)
+    return parseNestedMapping([first]) ?? parseScalar(first);
+  const rest = dedent(lines.slice(1));
+  const mapping = parseNestedMapping([first, ...rest]);
+  return mapping ?? lines.join("\n");
+}
+function dedent(lines) {
+  const indent = Math.min(...lines.map((l) => l.match(/^[ \t]*/)[0].length));
+  return lines.map((l) => l.slice(indent));
+}
+function parseScalar(value) {
+  if (value === "" || value === "null" || value === "~")
+    return null;
+  if (value === "true")
+    return true;
+  if (value === "false")
+    return false;
+  if (/^[+-]?\d+$/.test(value))
+    return Number.parseInt(value, 10);
+  if (/^[+-]?\d*\.\d+$/.test(value))
+    return Number.parseFloat(value);
+  if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return value.slice(1, -1);
+    }
+  }
+  if (value.startsWith("'") && value.endsWith("'") && value.length >= 2) {
+    return value.slice(1, -1).replace(/''/g, "'");
+  }
+  if (value.startsWith("[") && value.endsWith("]")) {
+    const inner = value.slice(1, -1).trim();
+    if (inner === "")
+      return [];
+    return splitInlineItems(inner).map((item) => parseScalar(item.trim()));
+  }
+  if (value.startsWith("{") && value.endsWith("}")) {
+    const inner = value.slice(1, -1).trim();
+    if (inner === "")
+      return {};
+    const out = {};
+    for (const item of splitInlineItems(inner)) {
+      const m = item.trim().match(KEY_RE2);
+      if (!m)
+        return value;
+      const [, key, rawValue] = m;
+      out[key] = parseScalar(rawValue.trim());
+    }
+    return out;
+  }
+  return value;
+}
+function splitInlineItems(inner) {
+  const items = [];
+  let current = "";
+  let quote = null;
+  for (const ch of inner) {
+    if (quote) {
+      current += ch;
+      if (ch === quote)
+        quote = null;
+    } else if (ch === '"' || ch === "'") {
+      current += ch;
+      quote = ch;
+    } else if (ch === ",") {
+      items.push(current);
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  items.push(current);
+  return items;
+}
+var FM_RE, KEY_RE2;
+var init_frontmatter = __esm({
+  "../core/dist/frontmatter.js"() {
+    "use strict";
+    FM_RE = /^---[ \t]*\r?\n(?:[\s\S]*?\r?\n)?---[ \t]*(?:\r?\n|$)/;
+    KEY_RE2 = /^([A-Za-z0-9_.-]+):(.*)$/;
+  }
+});
+
+// ../core/dist/analyze.js
+function utf8Length(source) {
+  let bytes = 0;
+  for (const ch of source) {
+    const cp = ch.codePointAt(0);
+    bytes += cp <= 127 ? 1 : cp <= 2047 ? 2 : cp <= 65535 ? 3 : 4;
+  }
+  return bytes;
+}
+function analyzeDocument(source, options = {}) {
+  const frontmatter = extractFrontmatter(source);
+  const { document } = parseDocument(stripFrontmatter(source));
+  const outline = [];
+  const blocks = { total: 0, byName: {}, maxDepth: 0, instances: [] };
+  const links = {
+    total: 0,
+    external: 0,
+    internal: 0,
+    domains: [],
+    items: []
+  };
+  const images = { total: 0, missingAlt: 0 };
+  const code = { fences: 0, languages: [], inlineSpans: 0 };
+  const structure = { listItems: 0, tables: 0, blockquotes: 0 };
+  const languages = /* @__PURE__ */ new Set();
+  const domains = /* @__PURE__ */ new Set();
+  let words = 0;
+  function addWords(count) {
+    words += count;
+    const section = outline[outline.length - 1];
+    if (section)
+      section.words += count;
+  }
+  function recordLink(url2, text, line) {
+    const external = EXTERNAL_URL_RE.test(url2);
+    links.total++;
+    if (external) {
+      links.external++;
+      const host = url2.match(/^(?:https?:)?\/\/(?:[^/?#@]*@)?([^/?#:]+)/i);
+      if (host)
+        domains.add(host[1].toLowerCase());
+    } else {
+      links.internal++;
+    }
+    links.items.push({ url: url2, text, line, external });
+  }
+  function inlineToProse(text, line) {
+    return text.replace(CODE_SPAN_RE, () => {
+      code.inlineSpans++;
+      return " ";
+    }).replace(IMAGE_RE, (_, alt) => {
+      images.total++;
+      if (alt.trim() === "")
+        images.missingAlt++;
+      return " ";
+    }).replace(LINK_RE, (_, label, url2) => {
+      recordLink(url2, label, line);
+      return label;
+    }).replace(AUTOLINK_RE, (_, url2) => {
+      recordLink(url2, url2, line);
+      return " ";
+    });
+  }
+  function countWords(text) {
+    return text.split(/\s+/).filter((token) => /[\p{L}\p{N}]/u.test(token)).length;
+  }
+  function scanMarkdown(value, startLine) {
+    let fence = null;
+    let inBlockquote = false;
+    let prevLineHasPipe = false;
+    const lines = value.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const lineNo = startLine + i;
+      const trimmed = line.trim();
+      const fenceMatch = trimmed.match(CODE_FENCE_RE2);
+      if (fence !== null) {
+        if (fenceMatch && fenceMatch[1][0] === fence[0] && fenceMatch[1].length >= fence.length) {
+          fence = null;
+        }
+        continue;
+      }
+      if (fenceMatch) {
+        fence = fenceMatch[1];
+        code.fences++;
+        const lang = fenceMatch[2].trim().split(/\s+/)[0];
+        if (lang)
+          languages.add(lang);
+        inBlockquote = false;
+        prevLineHasPipe = false;
+        continue;
+      }
+      if (trimmed === "") {
+        inBlockquote = false;
+        prevLineHasPipe = false;
+        continue;
+      }
+      const heading = trimmed.match(HEADING_RE);
+      if (heading) {
+        const raw = heading[2].replace(/\s+#+\s*$/, "");
+        const text = inlineToProse(raw, lineNo).replace(/\s+/g, " ").trim();
+        outline.push({ level: heading[1].length, text, line: lineNo, words: 0 });
+        addWords(countWords(text));
+        inBlockquote = false;
+        prevLineHasPipe = false;
+        continue;
+      }
+      let content = trimmed;
+      if (content.startsWith(">")) {
+        if (!inBlockquote) {
+          structure.blockquotes++;
+          inBlockquote = true;
+        }
+        content = content.replace(/^(>\s*)+/, "");
+      } else {
+        inBlockquote = false;
+      }
+      if (LIST_ITEM_RE.test(content)) {
+        structure.listItems++;
+        content = content.replace(LIST_ITEM_RE, "");
+      }
+      if (content.includes("|")) {
+        if (TABLE_SEPARATOR_RE.test(content) && content.includes("-") && prevLineHasPipe) {
+          structure.tables++;
+        }
+        prevLineHasPipe = true;
+        content = inlineToProse(content, lineNo).replaceAll("|", " ");
+      } else {
+        prevLineHasPipe = false;
+        content = inlineToProse(content, lineNo);
+      }
+      addWords(countWords(content));
+    }
+  }
+  function walk(nodes, depth) {
+    for (const node of nodes) {
+      if (node.type === "block") {
+        blocks.total++;
+        blocks.byName[node.name] = (blocks.byName[node.name] ?? 0) + 1;
+        blocks.maxDepth = Math.max(blocks.maxDepth, depth);
+        blocks.instances.push({ name: node.name, line: node.openPosition.start.line, depth });
+        walk(node.children, depth + 1);
+      } else {
+        scanMarkdown(node.value, node.position.start.line);
+      }
+    }
+  }
+  walk(document.children, 1);
+  code.languages = [...languages];
+  links.domains = [...domains].sort();
+  const sourceLines = source === "" ? 0 : source.split("\n").length - (source.endsWith("\n") ? 1 : 0);
+  return {
+    file: {
+      path: options.path ?? null,
+      bytes: utf8Length(source),
+      lines: sourceLines
+    },
+    frontmatter: frontmatter ? {
+      present: true,
+      keys: frontmatter.keys,
+      data: frontmatter.data,
+      lines: frontmatter.lines
+    } : { present: false, keys: [], data: {}, lines: null },
+    length: {
+      words,
+      characters: source.length,
+      readingMinutes: Math.ceil(words / 200),
+      approxTokens: Math.ceil(source.length / 4)
+    },
+    outline,
+    blocks,
+    links,
+    images,
+    code,
+    structure
+  };
+}
+var CODE_FENCE_RE2, HEADING_RE, LIST_ITEM_RE, TABLE_SEPARATOR_RE, CODE_SPAN_RE, IMAGE_RE, LINK_RE, AUTOLINK_RE, EXTERNAL_URL_RE;
+var init_analyze = __esm({
+  "../core/dist/analyze.js"() {
+    "use strict";
+    init_frontmatter();
+    init_parser();
+    CODE_FENCE_RE2 = /^(`{3,}|~{3,})(.*)$/;
+    HEADING_RE = /^(#{1,6})\s+(.*)$/;
+    LIST_ITEM_RE = /^\s*(?:[-*+]|\d+[.)])\s+/;
+    TABLE_SEPARATOR_RE = /^\|?[\s:|-]+$/;
+    CODE_SPAN_RE = /`[^`]+`/g;
+    IMAGE_RE = /!\[([^\]]*)\]\(([^)]*)\)/g;
+    LINK_RE = /\[([^\]]+)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+    AUTOLINK_RE = /<(https?:\/\/[^>\s]+)>/g;
+    EXTERNAL_URL_RE = /^(?:https?:)?\/\//i;
+  }
+});
+
 // ../core/dist/position.js
 function bodyLineRange(node, bodyLineIndex) {
   const bodyLines = node.body.split("\n");
@@ -339,6 +716,45 @@ var init_position = __esm({
 });
 
 // ../core/dist/authoring.js
+function typeLabel(def) {
+  switch (def.type) {
+    case "enum":
+      return `one of ${Object.values(def.entries ?? {}).join("|")}`;
+    case "literal":
+      return `one of ${(def.values ?? []).map(String).join("|")}`;
+    case "union":
+      return `one of ${(def.options ?? []).map((o) => typeLabel(o.def).replace(/^one of /, "")).join("|")}`;
+    default:
+      return def.type;
+  }
+}
+function describeProps(schema) {
+  const root = schema.def;
+  if (root.type !== "object" || !root.shape)
+    return [];
+  const lines = [];
+  for (const [name, field] of Object.entries(root.shape)) {
+    let current = field;
+    let optional2 = false;
+    let defaultValue;
+    let description = current.description;
+    while (["optional", "default", "nullable"].includes(current.def.type)) {
+      optional2 = true;
+      if (current.def.type === "default") {
+        const dv = current.def.defaultValue;
+        defaultValue = typeof dv === "function" ? dv() : dv;
+      }
+      if (!current.def.innerType)
+        break;
+      current = current.def.innerType;
+      description ??= current.description;
+    }
+    const presence = defaultValue !== void 0 ? `(optional, default: ${String(defaultValue)})` : optional2 ? "(optional)" : "(required)";
+    const suffix = description ? ` \u2014 ${description}` : "";
+    lines.push(`- ${name}: ${typeLabel(current.def)} ${presence}${suffix}`);
+  }
+  return lines;
+}
 function generateAuthoringGuide(defs, opts = {}) {
   const includeExamples = opts.includeExamples ?? true;
   const includeAvoid = opts.includeAvoidRules ?? true;
@@ -348,6 +764,11 @@ function generateAuthoringGuide(defs, opts = {}) {
   for (const def of defs) {
     const lines = [`## ${def.name}`, ""];
     lines.push(def.childOnly ? `${def.description} (child block \u2014 only inside a parent that allows it)` : def.description);
+    if (def.props) {
+      const props = describeProps(def.props);
+      if (props.length > 0)
+        lines.push("", "Props:", ...props);
+    }
     lines.push("", `Content: ${def.content.describe()}`);
     if (def.authoring.useWhen.length > 0) {
       lines.push("", "Use when:", ...def.authoring.useWhen.map((u) => `- ${u}`));
@@ -735,19 +1156,6 @@ var init_render_markdown = __esm({
   }
 });
 
-// ../core/dist/index.js
-var init_dist = __esm({
-  "../core/dist/index.js"() {
-    "use strict";
-    init_diagnostics();
-    init_parser();
-    init_registry();
-    init_content_models();
-    init_validate();
-    init_render_markdown();
-  }
-});
-
 // ../../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/core/core.js
 // @__NO_SIDE_EFFECTS__
 function $constructor(name, initializer3, params) {
@@ -812,7 +1220,7 @@ var init_core = __esm({
     NEVER = /* @__PURE__ */ Object.freeze({
       status: "aborted"
     });
-    $brand = Symbol("zod_brand");
+    $brand = /* @__PURE__ */ Symbol("zod_brand");
     $ZodAsyncError = class extends Error {
       constructor() {
         super(`Encountered Promise during synchronous parse. Use .parseAsync() instead.`);
@@ -6654,13 +7062,13 @@ var init_he = __esm({
         // no unit
       };
       const typeEntry = (t) => t ? TypeNames[t] : void 0;
-      const typeLabel = (t) => {
+      const typeLabel2 = (t) => {
         const e = typeEntry(t);
         if (e)
           return e.label;
         return t ?? TypeNames.unknown.label;
       };
-      const withDefinite = (t) => `\u05D4${typeLabel(t)}`;
+      const withDefinite = (t) => `\u05D4${typeLabel2(t)}`;
       const verbFor = (t) => {
         const e = typeEntry(t);
         const gender = e?.gender ?? "m";
@@ -6710,7 +7118,7 @@ var init_he = __esm({
         switch (issue2.code) {
           case "invalid_type": {
             const expectedKey = issue2.expected;
-            const expected = TypeDictionary[expectedKey ?? ""] ?? typeLabel(expectedKey);
+            const expected = TypeDictionary[expectedKey ?? ""] ?? typeLabel2(expectedKey);
             const receivedType = parsedType(issue2.input);
             const received = TypeDictionary[receivedType] ?? TypeNames[receivedType]?.label ?? receivedType;
             if (/^[A-Z]/.test(issue2.expected)) {
@@ -10981,8 +11389,8 @@ function registry() {
 var _a2, $output, $input, $ZodRegistry, globalRegistry;
 var init_registries = __esm({
   "../../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/core/registries.js"() {
-    $output = Symbol("ZodOutput");
-    $input = Symbol("ZodInput");
+    $output = /* @__PURE__ */ Symbol("ZodOutput");
+    $input = /* @__PURE__ */ Symbol("ZodInput");
     $ZodRegistry = class {
       constructor() {
         this._map = /* @__PURE__ */ new WeakMap();
@@ -15829,6 +16237,435 @@ var init_zod = __esm({
   }
 });
 
+// ../core/dist/links.js
+function parseLinkFrontmatter(data, options = {}) {
+  const normalized = normalizeFrontmatter(data, options);
+  if (!("slug" in normalized))
+    return { ok: true, value: null };
+  const parsed = LinkFrontmatter.safeParse(normalized);
+  if (parsed.success)
+    return { ok: true, value: parsed.data };
+  return { ok: false, errors: parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`) };
+}
+function buildLinkIndex(inputs, options = {}) {
+  const resolvedOptions = { ...DEFAULT_OPTIONS, ...options };
+  const pages = /* @__PURE__ */ new Map();
+  const aliases = /* @__PURE__ */ new Map();
+  const aliasEntries = [];
+  for (const { path, data } of inputs) {
+    const parsed = parseLinkFrontmatter(data, resolvedOptions);
+    if (!parsed.ok || parsed.value === null)
+      continue;
+    const fm = parsed.value;
+    const page = {
+      slug: fm.slug,
+      key: fm.key,
+      locale: effectiveLocale(fm, resolvedOptions),
+      path,
+      title: fm.title,
+      keywords: fm.keywords,
+      linksTo: [],
+      linkedFrom: [],
+      aliases: fm.aliases ?? [],
+      linkRefs: [],
+      linkedFromRefs: []
+    };
+    pages.set(pageMapKey(page, resolvedOptions), page);
+  }
+  for (const page of pages.values()) {
+    for (const alias of page.aliases) {
+      const replacement = replacementFor(page, resolvedOptions);
+      const key = aliasMapKey(alias, page.locale, resolvedOptions);
+      aliases.set(key, replacement);
+      aliasEntries.push({ alias, locale: page.locale, replacement, page });
+    }
+  }
+  const lookup = buildLookup(pages, resolvedOptions);
+  for (const page of pages.values()) {
+    const source = parseLinkFrontmatter(inputForPage(page, inputs, resolvedOptions), resolvedOptions);
+    if (!source.ok || source.value === null)
+      continue;
+    for (const rawTarget of source.value.linksTo ?? []) {
+      const resolved = resolveTarget(rawTarget, page, lookup, resolvedOptions);
+      if (!resolved.page) {
+        page.linksTo.push(resolved.target);
+        continue;
+      }
+      page.linksTo.push(replacementFor(resolved.page, resolvedOptions));
+      page.linkRefs.push(referenceFor(resolved.page, resolved.target));
+      if (resolved.page === page)
+        continue;
+      const from = replacementFor(page, resolvedOptions);
+      if (!resolved.page.linkedFrom.includes(from))
+        resolved.page.linkedFrom.push(from);
+      if (!resolved.page.linkedFromRefs.some((r) => sameReference(r, page))) {
+        resolved.page.linkedFromRefs.push(referenceFor(page));
+      }
+    }
+  }
+  return { pages, aliases, aliasEntries, options: resolvedOptions };
+}
+function serializeLinkIndex(index) {
+  const scoped = [...index.pages.values()].some((page) => page.locale || page.key);
+  const pages = [...index.pages.values()].map((p) => {
+    const base = {
+      slug: p.slug,
+      ...p.key ? { key: p.key } : {},
+      ...p.locale ? { locale: p.locale } : {},
+      path: p.path,
+      ...p.title ? { title: p.title } : {},
+      ...p.keywords ? { keywords: p.keywords } : {},
+      linksTo: scoped ? p.linkRefs : [...p.linksTo],
+      linkedFrom: scoped ? sortedRefs(p.linkedFromRefs) : [...p.linkedFrom].sort(),
+      aliases: [...p.aliases]
+    };
+    return base;
+  }).sort((a, b) => sortIdentity(a.locale, a.slug).localeCompare(sortIdentity(b.locale, b.slug)));
+  const aliases = {};
+  if (scoped) {
+    for (const entry of [...index.aliasEntries].sort((a, b) => sortIdentity(a.locale, a.alias).localeCompare(sortIdentity(b.locale, b.alias)))) {
+      aliases[aliasMapKey(entry.alias, entry.locale, index.options)] = referenceFor(entry.page);
+    }
+  } else {
+    for (const key of [...index.aliases.keys()].sort())
+      aliases[key] = index.aliases.get(key);
+  }
+  return { pages, aliases };
+}
+function aliasReplacementsForPage(index, data) {
+  const parsed = parseLinkFrontmatter(data, index.options);
+  const out = /* @__PURE__ */ new Map();
+  if (!parsed.ok || parsed.value === null)
+    return out;
+  const locale = effectiveLocale(parsed.value, index.options);
+  for (const entry of index.aliasEntries) {
+    if (index.options.resolve === "global-slug" || entry.locale === locale) {
+      out.set(entry.alias, entry.replacement);
+    }
+  }
+  return out;
+}
+function validateLinks(inputs, options = {}) {
+  const resolvedOptions = { ...DEFAULT_OPTIONS, ...options };
+  const out = [];
+  const validInputs = [];
+  const seenSlug = /* @__PURE__ */ new Map();
+  const seenKey = /* @__PURE__ */ new Map();
+  const seenAlias = /* @__PURE__ */ new Map();
+  for (const { path, data } of inputs) {
+    const parsed = parseLinkFrontmatter(data, resolvedOptions);
+    if (!parsed.ok) {
+      for (const e of parsed.errors)
+        out.push(diag(path, "CB_LINK_SHAPE", "error", `invalid link frontmatter: ${e}`));
+      continue;
+    }
+    if (parsed.value === null)
+      continue;
+    const fm = parsed.value;
+    const locale = effectiveLocale(fm, resolvedOptions);
+    validInputs.push({ path, fm });
+    const slugKey = scopedKey(fm.slug, locale, resolvedOptions);
+    const prior = seenSlug.get(slugKey);
+    if (prior)
+      out.push(diag(path, "CB_SLUG_DUPLICATE", "error", `slug "${fm.slug}" also used by ${prior}`));
+    else
+      seenSlug.set(slugKey, path);
+    if (usesKeyResolution(resolvedOptions) && !fm.key) {
+      out.push(diag(path, "CB_KEY_MISSING", "error", `page "${fm.slug}" is missing key`));
+    }
+    if (fm.key) {
+      const keyKey = scopedKey(fm.key, locale, resolvedOptions);
+      const priorKey = seenKey.get(keyKey);
+      if (priorKey)
+        out.push(diag(path, "CB_KEY_DUPLICATE", "error", `key "${fm.key}" also used by ${priorKey}`));
+      else
+        seenKey.set(keyKey, path);
+    }
+    for (const alias of fm.aliases ?? []) {
+      const aliasKey = scopedKey(alias, locale, resolvedOptions);
+      if (seenAlias.has(aliasKey))
+        out.push(diag(path, "CB_ALIAS_CONFLICT", "error", `alias "${alias}" already declared by ${seenAlias.get(aliasKey)}`));
+      else
+        seenAlias.set(aliasKey, path);
+    }
+  }
+  const index = buildLinkIndex(inputs, resolvedOptions);
+  const lookup = buildLookup(index.pages, resolvedOptions);
+  for (const { path, fm } of validInputs) {
+    const page = index.pages.get(pageMapKey(frontmatterIdentity(fm, resolvedOptions), resolvedOptions));
+    if (!page)
+      continue;
+    for (const alias of page.aliases) {
+      if (collidesWithPageIdentity(alias, page.locale, lookup, resolvedOptions))
+        out.push(diag(page.path, "CB_ALIAS_CONFLICT", "error", `alias "${alias}" collides with an existing page identity`));
+    }
+    for (const target of fm.linksTo ?? []) {
+      const resolved = resolveTarget(target, page, lookup, resolvedOptions);
+      if (resolved.page === page) {
+        out.push(diag(page.path, "CB_LINK_SELF", "warning", `page "${page.slug}" links to itself`));
+        continue;
+      }
+      if (resolved.page && resolved.crossLocale) {
+        out.push(diag(page.path, "CB_LINK_CROSS_LOCALE", "warning", `linksTo "${resolved.target}" resolves to locale "${resolved.page.locale}"`));
+        continue;
+      }
+      if (!resolved.page) {
+        if (targetExistsOutsideLocale(resolved.target, page.locale, lookup, resolvedOptions)) {
+          out.push(diag(page.path, "CB_LINK_LOCALE_MISSING", "error", `linksTo "${resolved.target}" exists in another locale but not "${page.locale ?? "default"}"`));
+          continue;
+        }
+        const hint = closest(resolved.target, candidatesFor(page.locale, lookup, resolvedOptions));
+        out.push(diag(page.path, "CB_LINK_UNRESOLVED", "error", `linksTo "${resolved.target}" does not resolve to any page`, hint ? `Did you mean "${hint}"?` : void 0));
+      }
+    }
+    if (page.linkedFrom.length === 0)
+      out.push(diag(page.path, "CB_LINK_ORPHAN", "warning", `page "${page.slug}" has no inbound links`));
+  }
+  return out;
+}
+function normalizeFrontmatter(data, options) {
+  const out = { ...data };
+  copyConfiguredField(out, data, options.slugField, "slug");
+  copyConfiguredField(out, data, options.keyField, "key");
+  copyConfiguredField(out, data, options.localeField, "locale");
+  return out;
+}
+function copyConfiguredField(out, data, from, to) {
+  if (!from || from === to || !(from in data) || to in out)
+    return;
+  out[to] = data[from];
+}
+function effectiveLocale(fm, options) {
+  return fm.locale ?? options.defaultLocale;
+}
+function frontmatterIdentity(fm, options) {
+  return { slug: fm.slug, key: fm.key, locale: effectiveLocale(fm, options) };
+}
+function pageMapKey(page, options) {
+  if (options.resolve === "global-slug")
+    return page.slug;
+  return scopedKey(page.slug, page.locale, options);
+}
+function scopedKey(value, locale, options) {
+  if (options.resolve === "global-slug")
+    return value;
+  return `${locale ?? ""}\0${value}`;
+}
+function aliasMapKey(alias, locale, options) {
+  return options.resolve === "global-slug" ? alias : `${locale ?? ""}:${alias}`;
+}
+function replacementFor(page, options) {
+  if (options.resolve === "same-locale-key")
+    return page.key ?? page.slug;
+  if (options.resolve === "prefer-same-locale-key-fallback-slug")
+    return page.key ?? page.slug;
+  return page.slug;
+}
+function referenceFor(page, target) {
+  return {
+    ...target ? { target } : {},
+    ...page.locale ? { locale: page.locale } : {},
+    slug: page.slug,
+    ...page.key ? { key: page.key } : {}
+  };
+}
+function sameReference(ref, page) {
+  return ref.slug === page.slug && ref.locale === page.locale && ref.key === page.key;
+}
+function sortedRefs(refs) {
+  return [...refs].sort((a, b) => sortIdentity(a.locale, a.key ?? a.slug).localeCompare(sortIdentity(b.locale, b.key ?? b.slug)));
+}
+function sortIdentity(locale, value) {
+  return `${locale ?? ""}\0${value}`;
+}
+function buildLookup(pages, options) {
+  const lookup = {
+    bySlug: /* @__PURE__ */ new Map(),
+    byScopedSlug: /* @__PURE__ */ new Map(),
+    byKey: /* @__PURE__ */ new Map(),
+    byScopedKey: /* @__PURE__ */ new Map(),
+    aliasBySlug: /* @__PURE__ */ new Map(),
+    aliasByScopedSlug: /* @__PURE__ */ new Map(),
+    aliasByKey: /* @__PURE__ */ new Map(),
+    aliasByScopedKey: /* @__PURE__ */ new Map()
+  };
+  for (const page of pages.values()) {
+    pushMulti(lookup.bySlug, page.slug, page);
+    lookup.byScopedSlug.set(scopedKey(page.slug, page.locale, options), page);
+    if (page.key) {
+      pushMulti(lookup.byKey, page.key, page);
+      lookup.byScopedKey.set(scopedKey(page.key, page.locale, options), page);
+    }
+    for (const alias of page.aliases) {
+      lookup.aliasBySlug.set(alias, page);
+      lookup.aliasByScopedSlug.set(scopedKey(alias, page.locale, options), page);
+      if (page.key) {
+        lookup.aliasByKey.set(alias, page);
+        lookup.aliasByScopedKey.set(scopedKey(alias, page.locale, options), page);
+      }
+    }
+  }
+  return lookup;
+}
+function pushMulti(map2, key, page) {
+  const existing = map2.get(key);
+  if (existing)
+    existing.push(page);
+  else
+    map2.set(key, [page]);
+}
+function resolveTarget(rawTarget, source, lookup, options) {
+  if (typeof rawTarget !== "string") {
+    const locale2 = rawTarget.locale ?? source.locale;
+    const page2 = rawTarget.key ? lookup.byScopedKey.get(scopedKey(rawTarget.key, locale2, options)) : rawTarget.slug ? lookup.byScopedSlug.get(scopedKey(rawTarget.slug, locale2, options)) : void 0;
+    const target = rawTarget.key ?? rawTarget.slug ?? "";
+    return {
+      page: page2,
+      target,
+      explicitLocale: rawTarget.locale,
+      crossLocale: Boolean(page2 && rawTarget.locale && rawTarget.locale !== source.locale),
+      matchedBy: rawTarget.key ? "key" : "slug"
+    };
+  }
+  const locale = source.locale;
+  if (options.resolve === "global-slug") {
+    const page2 = lookup.aliasBySlug.get(rawTarget) ?? single(lookup.bySlug.get(rawTarget));
+    return { page: page2, target: rawTarget, crossLocale: false, matchedBy: page2 ? "slug" : void 0 };
+  }
+  if (options.resolve === "same-locale-key") {
+    const scoped2 = scopedKey(rawTarget, locale, options);
+    const page2 = lookup.byScopedKey.get(scoped2) ?? lookup.aliasByScopedKey.get(scoped2);
+    return { page: page2, target: rawTarget, crossLocale: false, matchedBy: page2 ? "key" : void 0 };
+  }
+  if (options.resolve === "prefer-same-locale-key-fallback-slug") {
+    const scoped2 = scopedKey(rawTarget, locale, options);
+    const page2 = lookup.byScopedKey.get(scoped2) ?? lookup.aliasByScopedKey.get(scoped2) ?? lookup.byScopedSlug.get(scoped2) ?? lookup.aliasByScopedSlug.get(scoped2);
+    return { page: page2, target: rawTarget, crossLocale: false, matchedBy: page2 ? "key" : void 0 };
+  }
+  const scoped = scopedKey(rawTarget, locale, options);
+  const page = lookup.byScopedSlug.get(scoped) ?? lookup.aliasByScopedSlug.get(scoped);
+  return { page, target: rawTarget, crossLocale: false, matchedBy: page ? "slug" : void 0 };
+}
+function single(values) {
+  return values?.length === 1 ? values[0] : void 0;
+}
+function usesKeyResolution(options) {
+  return options.resolve === "same-locale-key";
+}
+function collidesWithPageIdentity(alias, locale, lookup, options) {
+  if (options.resolve === "global-slug")
+    return lookup.bySlug.has(alias);
+  const scoped = scopedKey(alias, locale, options);
+  return lookup.byScopedSlug.has(scoped) || usesKeyResolution(options) && lookup.byScopedKey.has(scoped);
+}
+function targetExistsOutsideLocale(target, locale, lookup, options) {
+  if (options.resolve === "global-slug")
+    return false;
+  const byIdentity = usesKeyResolution(options) ? lookup.byKey : lookup.bySlug;
+  return (byIdentity.get(target) ?? []).some((page) => page.locale !== locale);
+}
+function candidatesFor(locale, lookup, options) {
+  if (options.resolve === "global-slug")
+    return [...lookup.bySlug.keys()];
+  const out = [];
+  for (const page of lookup.byScopedSlug.values()) {
+    if (page.locale === locale)
+      out.push(usesKeyResolution(options) && page.key ? page.key : page.slug);
+  }
+  return out;
+}
+function inputForPage(page, inputs, options) {
+  for (const input of inputs) {
+    const parsed = parseLinkFrontmatter(input.data, options);
+    if (!parsed.ok || parsed.value === null)
+      continue;
+    const identity = frontmatterIdentity(parsed.value, options);
+    if (pageMapKey(identity, options) === pageMapKey(page, options))
+      return input.data;
+  }
+  return {};
+}
+function diag(file2, code, severity, message, hint) {
+  return { file: file2, diagnostic: { code, severity, message, hint, position: FM_POSITION } };
+}
+function editDistance(a, b) {
+  const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+  for (let j = 0; j <= b.length; j++)
+    dp[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;
+      dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost);
+    }
+  }
+  return dp[a.length][b.length];
+}
+function closest(target, candidates) {
+  let best;
+  let bestD = Infinity;
+  for (const c of candidates) {
+    const d = editDistance(target, c);
+    if (d < bestD) {
+      bestD = d;
+      best = c;
+    }
+  }
+  return best && bestD <= Math.max(2, Math.floor(target.length / 3)) ? best : void 0;
+}
+var Keywords, LinkTarget, LinkFrontmatter, DEFAULT_OPTIONS, FM_POSITION;
+var init_links = __esm({
+  "../core/dist/links.js"() {
+    "use strict";
+    init_zod();
+    Keywords = external_exports.object({
+      primary: external_exports.string().optional(),
+      secondary: external_exports.array(external_exports.string()).optional()
+    });
+    LinkTarget = external_exports.union([
+      external_exports.string(),
+      external_exports.object({
+        slug: external_exports.string().min(1).optional(),
+        key: external_exports.string().min(1).optional(),
+        locale: external_exports.string().min(1).optional()
+      }).refine((target) => target.slug || target.key, {
+        message: "object linksTo targets must include slug or key"
+      })
+    ]);
+    LinkFrontmatter = external_exports.object({
+      slug: external_exports.string().min(1),
+      key: external_exports.string().min(1).optional(),
+      locale: external_exports.string().min(1).optional(),
+      title: external_exports.string().optional(),
+      linksTo: external_exports.array(LinkTarget).optional(),
+      aliases: external_exports.array(external_exports.string()).optional(),
+      keywords: Keywords.optional()
+    });
+    DEFAULT_OPTIONS = {
+      resolve: "global-slug"
+    };
+    FM_POSITION = {
+      start: { line: 1, column: 1, offset: 0 },
+      end: { line: 1, column: 1, offset: 0 }
+    };
+  }
+});
+
+// ../core/dist/index.js
+var init_dist = __esm({
+  "../core/dist/index.js"() {
+    "use strict";
+    init_diagnostics();
+    init_parser();
+    init_frontmatter();
+    init_analyze();
+    init_registry();
+    init_content_models();
+    init_validate();
+    init_render_markdown();
+    init_links();
+  }
+});
+
 // ../blocks/dist/blocks/callout.js
 var calloutBlock, calloutMarkdown;
 var init_callout = __esm({
@@ -16181,16 +17018,269 @@ var init_load_registry = __esm({
   }
 });
 
+// src/commands/agents.ts
+var agents_exports = {};
+__export(agents_exports, {
+  agentsCommand: () => agentsCommand,
+  installAgentIntegration: () => installAgentIntegration
+});
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+function upsertBlock(existing) {
+  const start = existing.indexOf(START);
+  const end = existing.indexOf(END);
+  if (start !== -1 && end !== -1) {
+    return existing.slice(0, start) + AGENTS_MD_BLOCK + existing.slice(end + END.length);
+  }
+  if (existing.trim() === "") return `${AGENTS_MD_BLOCK}
+`;
+  return `${existing.replace(/\n*$/, "\n\n")}${AGENTS_MD_BLOCK}
+`;
+}
+async function installAgentIntegration(cwd, options, io) {
+  const claude = options.claude ?? existsSync(join(cwd, ".claude"));
+  const agentsMd = options.agentsMd ?? true;
+  if (agentsMd) {
+    const path = join(cwd, "AGENTS.md");
+    let existing = "";
+    try {
+      existing = await readFile(path, "utf8");
+    } catch {
+    }
+    const created = existing === "";
+    await writeFile(path, upsertBlock(existing), "utf8");
+    io.stdout(`${created ? "created" : "updated"}: AGENTS.md (contentbit block)`);
+  }
+  if (claude) {
+    const skills = [
+      ["contentbit-author", AUTHOR_SKILL],
+      ["contentbit-audit", AUDIT_SKILL]
+    ];
+    for (const [name, content] of skills) {
+      const dir = join(cwd, ".claude/skills", name);
+      await mkdir(dir, { recursive: true });
+      await writeFile(join(dir, "SKILL.md"), content, "utf8");
+      io.stdout(`installed: .claude/skills/${name}/SKILL.md`);
+    }
+  }
+}
+async function agentsCommand(args, io) {
+  const { values } = parseArgs({
+    args,
+    options: {
+      claude: { type: "boolean", default: false },
+      "no-agents-md": { type: "boolean", default: false },
+      cwd: { type: "string", default: process.cwd() }
+    }
+  });
+  await installAgentIntegration(
+    values.cwd,
+    {
+      claude: values.claude || void 0,
+      // false means "detect", not "skip"
+      agentsMd: !values["no-agents-md"]
+    },
+    io
+  );
+  return 0;
+}
+var TEMPLATE_VERSION, AUTHOR_SKILL, AUDIT_SKILL, AGENTS_MD_BLOCK, START, END;
+var init_agents = __esm({
+  "src/commands/agents.ts"() {
+    "use strict";
+    TEMPLATE_VERSION = 2;
+    AUTHOR_SKILL = `---
+name: contentbit-author
+description: |
+  Write or edit contentbit Markdown content (directive blocks like :::callout).
+  Use when asked to create or modify content documents in a project that uses
+  contentbit \u2014 blog posts, docs pages, changelogs, any Markdown covered by
+  \`contentbit validate\`.
+version: ${TEMPLATE_VERSION}
+---
+
+# Writing contentbit content
+
+contentbit documents are plain Markdown plus directive blocks
+(\`:::name{props} ... :::\`). Every block has a schema. Never guess block names,
+props, or body shapes \u2014 fetch the live guide from the project's registry first.
+
+## Find the project conventions
+
+Check \`package.json\` for a \`content:check\` script. It holds the canonical
+validate invocation for this project: the content glob and, if present, the
+\`--registry <path>\` flag pointing at custom block definitions. Reuse both
+below. No script? Default to \`content/**/*.md\` with no \`--registry\` flag.
+If the project has a \`content:links\` script, use it for the internal-link
+index; otherwise run \`contentbit links <content glob>\` directly.
+
+## The loop
+
+1. **Fetch the authoring guide** (always \u2014 it covers this project's custom blocks):
+
+   \`\`\`sh
+   contentbit instructions --audience llm [--registry <path from content:check>]
+   \`\`\`
+
+   Read it before writing. It documents every available block: props, body
+   shape, and when to use or avoid it.
+
+2. **Write the document.** Plain Markdown everywhere; blocks only where the
+   guide's use-when guidance fits. Keep frontmatter consistent with sibling
+   documents in the same folder. If sibling documents use \`slug\`, \`linksTo\`,
+   \`aliases\`, or \`keywords\`, run the link index first:
+
+   \`\`\`sh
+   contentbit links <content glob>
+   \`\`\`
+
+   Read \`.contentbit/link-index.json\` to pick existing slugs and related
+   pages. Author only \`slug\`, \`linksTo\`, \`aliases\`, and \`keywords\` in
+   frontmatter; never write derived \`linkedFrom\` into source files. When
+   creating a linked page, include \`keywords.primary\` and
+   \`keywords.secondary\` with search-intent phrases that would help future
+   agents choose this page as a \`linksTo\` target.
+
+3. **Validate and fix until clean:**
+
+   \`\`\`sh
+   contentbit validate <file> [--registry <path>]
+   \`\`\`
+
+   Diagnostics print to stderr as \`file:line:col severity CODE message\`, often
+   with a \`hint:\` line suggesting the fix. Exit 0 means clean; exit 1 means
+   errors remain. If the document has link frontmatter, validate the full
+   content glob so cross-file links are checked against the whole graph. Fix
+   every diagnostic and re-run. Never finish with a failing validate.
+
+4. **Refresh internal links when present:**
+
+   \`\`\`sh
+   contentbit links <content glob> --fix
+   \`\`\`
+
+   \`--fix\` only rewrites \`linksTo\` values that point at known aliases. It
+   does not invent links, remove aliases, or write backlinks. Re-run validate
+   after it changes files.
+
+## Failure modes
+
+- \`contentbit\` not found or no registry resolvable: the project is not set up.
+  Say so and suggest \`npx contentbit@latest init\` \u2014 do not invent block syntax.
+- A block you want does not exist: use plain Markdown, or ask whether to define
+  a custom block in the registry. Never emit an unregistered block name.
+`;
+    AUDIT_SKILL = `---
+name: contentbit-audit
+description: |
+  Audit contentbit Markdown content health using document stats. Use when asked
+  to audit, review, or find improvements across content \u2014 thin pages, missing
+  structure, validation issues \u2014 in a project that uses contentbit.
+version: ${TEMPLATE_VERSION}
+---
+
+# Auditing contentbit content
+
+\`contentbit stats\` analyzes documents and prints JSON to stdout. It is a read
+tool: it always exits 0, even when documents have validation errors.
+\`contentbit links\` builds the frontmatter-authored internal-link graph and
+prints link diagnostics.
+
+## Gather
+
+Check \`package.json\` for the \`content:check\` script to find this project's
+content glob and \`--registry\` flag, then:
+
+\`\`\`sh
+contentbit stats "content/**/*.md" [--registry <path>]
+contentbit links "content/**/*.md"
+\`\`\`
+
+One matched file prints a single stats object; multiple files print an array.
+Each entry includes the file path, frontmatter data, a heading \`outline\` with
+per-section word counts, \`blocks.byName\` usage counts, \`links.domains\`, and
+a \`validation\` summary (\`errors\`/\`warnings\`).
+\`contentbit links\` also writes \`.contentbit/link-index.json\`, whose pages
+contain \`slug\`, resolved \`linksTo\`, derived \`linkedFrom\`, \`aliases\`, and
+\`keywords\`.
+
+## Interpret
+
+Prioritize findings in this order:
+
+1. **Validation errors and warnings** \u2014 broken content ships broken pages.
+2. **Internal-link errors** \u2014 unresolved links, duplicate slugs, and alias
+   conflicts from \`contentbit links\`.
+3. **Orphans and self-links** \u2014 link warnings that point to isolated or noisy
+   pages.
+4. **Thin documents** \u2014 outline sections with very low word counts.
+5. **Block-less documents** \u2014 \`blocks.byName\` empty where sibling documents
+   use blocks; structure (steps, callouts, comparisons, faq) may be missing.
+6. **Missing or inconsistent frontmatter** compared to sibling documents.
+7. **Structural imbalance** \u2014 skipped heading levels, single-section walls of text.
+
+## Report
+
+Report findings per file with concrete suggestions, ordered by priority. Do not
+edit files during the audit. To fix a finding, follow the contentbit-author
+skill (fetch the guide, edit, validate until clean) \u2014 offer that as a follow-up.
+`;
+    AGENTS_MD_BLOCK = `<!-- contentbit:start -->
+
+## contentbit content (generated \u2014 edits inside this block are overwritten)
+
+This project validates Markdown content with contentbit. Documents are plain
+Markdown plus directive blocks (\`:::name{props} ... :::\`), each with a schema.
+The \`content:check\` script in package.json holds the canonical validate
+command \u2014 the content glob and the \`--registry\` flag \u2014 reuse its arguments.
+If the project has a \`content:links\` script, use it to build the internal-link
+index; otherwise run \`contentbit links <content glob>\`.
+
+When writing or editing content:
+
+1. Fetch the live authoring guide first \u2014 never guess block syntax:
+   \`contentbit instructions --audience llm [--registry <path>]\`
+2. Write plain Markdown; use blocks where the guide's use-when guidance fits.
+3. If sibling documents use \`slug\` / \`linksTo\`, read
+   \`.contentbit/link-index.json\` from \`contentbit links <content glob>\` and
+   author frontmatter links with existing slugs. When creating a linked page,
+   include \`keywords.primary\` and \`keywords.secondary\` with search-intent
+   phrases future agents can use to choose related pages.
+4. Validate until clean (exit 0): \`contentbit validate <file> [--registry <path>]\`.
+   Diagnostics print as \`file:line:col severity CODE message\` with fix hints.
+   For link frontmatter, validate the full content glob so cross-file checks run.
+
+When auditing content health:
+
+- \`contentbit stats "content/**/*.md" [--registry <path>]\` prints JSON stats
+  and always exits 0: outline word counts, block usage, link domains, and
+  validation error/warning counts. Flag validation issues, thin documents, and
+  block-less pages first.
+- \`contentbit links "content/**/*.md" [--fix]\` builds
+  \`.contentbit/link-index.json\`, reports dangling links/orphans, and rewrites
+  alias references in \`linksTo\` when \`--fix\` is used.
+
+If \`contentbit\` is unavailable, suggest \`npx contentbit@latest init\` instead
+of inventing block syntax.
+
+<!-- contentbit:end -->`;
+    START = "<!-- contentbit:start -->";
+    END = "<!-- contentbit:end -->";
+  }
+});
+
 // src/commands/init.ts
 var init_exports = {};
 __export(init_exports, {
   initCommand: () => initCommand
 });
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import { parseArgs } from "node:util";
+import { existsSync as existsSync2 } from "node:fs";
+import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
+import { join as join2 } from "node:path";
+import { parseArgs as parseArgs2 } from "node:util";
 function blockComponentsTemplate(styled) {
   const body = styled ? `  return (
     <figure className="my-6 border-s-2 ps-4">
@@ -16238,7 +17328,7 @@ import { ContentRenderer } from '@/components/content-blocks/content-renderer'`
   return `'use client'
 
 import { genericBlocks } from '@contentbit/blocks'
-import { createBlockRegistry, parseDocument, validateDocument } from '@contentbit/core'
+import { createBlockRegistry, parseDocument, stripFrontmatter, validateDocument } from '@contentbit/core'
 ${reactImport}${mdImport}${rendererImport}
 // Everything block-related lives in the blocks/ folder: definitions in
 // registry.ts (shared with the validate CLI), components in components.tsx.
@@ -16248,7 +17338,7 @@ import { blockComponents } from '${blocksImport}/components'
 const registry = createBlockRegistry().use(genericBlocks()).use(customBlocks)
 
 export function Content({ source }: { source: string }) {
-  const result = validateDocument(parseDocument(source), registry)
+  const result = validateDocument(parseDocument(stripFrontmatter(source)), registry)
   return (
     <${renderer}
       document={result.document}
@@ -16268,21 +17358,21 @@ const renderMarkdown = (md) => mdIt.render(md)` : `// TODO: plug a Markdown libr
 const renderMarkdown = undefined`;
   return `// Render content/example.md to example.html. Run: node scripts/render-example.mjs
 import { genericBlocks } from '@contentbit/blocks'
-import { createBlockRegistry, parseDocument, validateDocument } from '@contentbit/core'
+import { createBlockRegistry, parseDocument, stripFrontmatter, validateDocument } from '@contentbit/core'
 import { renderToHtml } from '@contentbit/html'
 import { readFile, writeFile } from 'node:fs/promises'
 ${wiring}
 
 const source = await readFile('content/example.md', 'utf8')
 const registry = createBlockRegistry().use(genericBlocks())
-const result = validateDocument(parseDocument(source), registry)
+const result = validateDocument(parseDocument(stripFrontmatter(source)), registry)
 const html = renderToHtml(result.document, { renderMarkdown })
 await writeFile('example.html', html, 'utf8')
 console.log('wrote example.html')
 `;
 }
 function detectFramework(cwd, deps) {
-  if ((deps["@tanstack/react-start"] || deps["@tanstack/react-router"]) && existsSync(join(cwd, "src/routes"))) {
+  if ((deps["@tanstack/react-start"] || deps["@tanstack/react-router"]) && existsSync2(join2(cwd, "src/routes"))) {
     return {
       framework: "tanstack",
       componentPath: "src/components/content-blocks.tsx",
@@ -16290,8 +17380,8 @@ function detectFramework(cwd, deps) {
     };
   }
   if (deps.next) {
-    const appDir = existsSync(join(cwd, "src/app")) ? "src/app" : "app";
-    if (existsSync(join(cwd, appDir))) {
+    const appDir = existsSync2(join2(cwd, "src/app")) ? "src/app" : "app";
+    if (existsSync2(join2(cwd, appDir))) {
       return {
         framework: "next",
         componentPath: "components/content-blocks.tsx",
@@ -16301,6 +17391,34 @@ function detectFramework(cwd, deps) {
   }
   return { framework: null, componentPath: "components/content-blocks.tsx", pagePath: null };
 }
+function astroPage(styled) {
+  const importLine = styled ? "import ContentRenderer from '../components/content-blocks/content-renderer.astro'" : "import { ContentBlocks } from '@contentbit/astro/components'";
+  const renderer = styled ? "ContentRenderer" : "ContentBlocks";
+  return `---
+import { genericBlocks } from '@contentbit/blocks'
+import { createBlockRegistry, parseDocument, validateDocument } from '@contentbit/core'
+import { getEntry } from 'astro:content'
+
+${importLine}
+
+// Definitions in blocks/registry.ts are shared with the validate CLI.
+import customBlocks from '../../blocks/registry'
+import QuoteBlock from '../../blocks/QuoteBlock.astro'
+
+// Entry ids are the file path relative to the collection base, minus ".md".
+const entry = await getEntry('articles', 'example')
+if (!entry?.body) throw new Error('Entry "example" not found in the articles collection.')
+
+const registry = createBlockRegistry().use(genericBlocks()).use(customBlocks)
+// Static pages render at build time, so invalid blocks fail the build here.
+const result = validateDocument(parseDocument(entry.body), registry)
+---
+
+<main style="max-width: 42rem; margin: 0 auto; padding: 3rem 1.5rem;">
+  <${renderer} document={result.document} components={{ quote: QuoteBlock }} />
+</main>
+`;
+}
 function detectPackageManager(cwd) {
   const locks = [
     ["pnpm-lock.yaml", "pnpm"],
@@ -16310,7 +17428,7 @@ function detectPackageManager(cwd) {
     ["package-lock.json", "npm"]
   ];
   for (const [file2, pm] of locks) {
-    if (existsSync(join(cwd, file2))) return pm;
+    if (existsSync2(join2(cwd, file2))) return pm;
   }
   const agent = process.env.npm_config_user_agent ?? "";
   for (const pm of ["pnpm", "yarn", "bun"]) {
@@ -16335,18 +17453,38 @@ function runInstall(pm, args, cwd) {
     child.on("error", () => resolve(1));
   });
 }
+async function installStyledPack(cwd, pack, noInstall, io) {
+  const componentsJsonPath = join2(cwd, "components.json");
+  const componentsJson = JSON.parse(await readFile2(componentsJsonPath, "utf8"));
+  componentsJson.registries ??= {};
+  if (!componentsJson.registries["@contentbit"]) {
+    componentsJson.registries["@contentbit"] = "https://contentbit.dev/r/{name}.json";
+    await writeFile2(componentsJsonPath, `${JSON.stringify(componentsJson, null, 2)}
+`, "utf8");
+    io.stdout("added @contentbit registry to components.json");
+  }
+  if (noInstall) {
+    io.stdout(`skipped: shadcn add ${pack}`);
+    return true;
+  }
+  const [bin, prefix] = dlxCommand(detectPackageManager(cwd));
+  io.stdout(`installing the styled pack: shadcn add ${pack}`);
+  const code = await runInstall(bin, [...prefix, "shadcn@latest", "add", pack, "--yes"], cwd);
+  if (code !== 0) io.stderr("styled pack install failed; falling back to headless defaults");
+  return code === 0;
+}
 async function scaffold(path, content) {
   try {
-    await readFile(path, "utf8");
+    await readFile2(path, "utf8");
     return "skipped";
   } catch {
-    await mkdir(join(path, ".."), { recursive: true });
-    await writeFile(path, content, "utf8");
+    await mkdir2(join2(path, ".."), { recursive: true });
+    await writeFile2(path, content, "utf8");
     return "created";
   }
 }
 async function initCommand(args, io) {
-  const { values } = parseArgs({
+  const { values } = parseArgs2({
     args,
     options: {
       target: { type: "string", short: "t" },
@@ -16355,20 +17493,22 @@ async function initCommand(args, io) {
       cwd: { type: "string", default: process.cwd() },
       "no-install": { type: "boolean", default: false },
       "no-page": { type: "boolean", default: false },
-      "no-styled": { type: "boolean", default: false }
+      "no-styled": { type: "boolean", default: false },
+      "no-agents": { type: "boolean", default: false }
     }
   });
   const cwd = values.cwd;
   let pkg;
-  const pkgPath = join(cwd, "package.json");
+  const pkgPath = join2(cwd, "package.json");
   try {
-    pkg = JSON.parse(await readFile(pkgPath, "utf8"));
+    pkg = JSON.parse(await readFile2(pkgPath, "utf8"));
   } catch {
     io.stderr("No package.json found. Run this inside a project (npm init first).");
     return 1;
   }
   const hasReact = Boolean(pkg.dependencies?.react ?? pkg.devDependencies?.react);
-  const detected = hasReact ? "react" : "html";
+  const hasAstro = Boolean(pkg.dependencies?.astro ?? pkg.devDependencies?.astro);
+  const detected = hasAstro ? "astro" : hasReact ? "react" : "html";
   let target;
   if (values.target) {
     if (!TARGETS.includes(values.target)) {
@@ -16383,6 +17523,7 @@ async function initCommand(args, io) {
       initialValue: detected,
       options: [
         { value: "react", label: "React", hint: "ContentBlocks component" },
+        { value: "astro", label: "Astro", hint: "content collections + .astro components" },
         { value: "html", label: "Static HTML", hint: "renderToHtml, no framework" },
         { value: "markdown", label: "Plain Markdown", hint: "fallback rendering only" }
       ]
@@ -16419,6 +17560,7 @@ async function initCommand(args, io) {
   const runtime = ["@contentbit/core", "@contentbit/blocks", "zod"];
   if (target === "react") runtime.push("@contentbit/react");
   if (target === "html") runtime.push("@contentbit/html");
+  if (target === "astro") runtime.push("@contentbit/astro");
   if (md !== "none") runtime.push(md);
   if (values["no-install"]) {
     io.stdout(`skipped install: ${runtime.join(" ")} + contentbit (dev)`);
@@ -16436,34 +17578,14 @@ async function initCommand(args, io) {
   }
   const files = [
     ["blocks/registry.ts", REGISTRY_TEMPLATE],
-    ["content/example.md", EXAMPLE_CONTENT]
+    ["content/example.md", EXAMPLE_CONTENT],
+    ["content/related.md", RELATED_CONTENT]
   ];
   const layout = detectFramework(cwd, { ...pkg.dependencies, ...pkg.devDependencies });
   let styled = false;
-  const componentsJsonPath = join(cwd, "components.json");
-  if (target === "react" && !values["no-styled"] && existsSync(componentsJsonPath)) {
-    const componentsJson = JSON.parse(await readFile(componentsJsonPath, "utf8"));
-    componentsJson.registries ??= {};
-    if (!componentsJson.registries["@contentbit"]) {
-      componentsJson.registries["@contentbit"] = "https://contentbit.dev/r/{name}.json";
-      await writeFile(componentsJsonPath, `${JSON.stringify(componentsJson, null, 2)}
-`, "utf8");
-      io.stdout("added @contentbit registry to components.json");
-    }
-    if (values["no-install"]) {
-      io.stdout("skipped: shadcn add @contentbit/generic-pack");
-      styled = true;
-    } else {
-      const [bin, prefix] = dlxCommand(detectPackageManager(cwd));
-      io.stdout("installing the styled pack: shadcn add @contentbit/generic-pack");
-      const code = await runInstall(
-        bin,
-        [...prefix, "shadcn@latest", "add", "@contentbit/generic-pack", "--yes"],
-        cwd
-      );
-      if (code === 0) styled = true;
-      else io.stderr("styled pack install failed; falling back to headless defaults");
-    }
+  const componentsJsonPath = join2(cwd, "components.json");
+  if (target === "react" && !values["no-styled"] && existsSync2(componentsJsonPath)) {
+    styled = await installStyledPack(cwd, "@contentbit/generic-pack", values["no-install"], io);
   }
   if (target === "react") {
     const depth = layout.componentPath.split("/").length - 1;
@@ -16483,30 +17605,62 @@ async function initCommand(args, io) {
       htmlRenderScript(md)
     ]);
   }
+  if (target === "astro") {
+    let astroStyled = false;
+    if (!values["no-styled"] && existsSync2(componentsJsonPath)) {
+      astroStyled = await installStyledPack(cwd, "@contentbit/astro-pack", values["no-install"], io);
+    }
+    files.push(["blocks/QuoteBlock.astro", ASTRO_QUOTE_BLOCK]);
+    const configCandidates = ["ts", "mts", "mjs", "js"].flatMap((ext) => [
+      `src/content.config.${ext}`,
+      `src/content/config.${ext}`
+    ]);
+    const existingConfig = configCandidates.find((p) => existsSync2(join2(cwd, p)));
+    if (existingConfig) {
+      io.stdout(`content config exists (${existingConfig}); add this collection manually:`);
+      io.stdout(ASTRO_CONTENT_CONFIG);
+      io.stdout('the example page expects the "articles" collection above');
+    } else {
+      files.push(["src/content.config.ts", ASTRO_CONTENT_CONFIG]);
+    }
+    if (!values["no-page"]) files.push(["src/pages/example.astro", astroPage(astroStyled)]);
+  }
   for (const [rel, content] of files) {
-    const result = await scaffold(join(cwd, rel), content);
+    const result = await scaffold(join2(cwd, rel), content);
     io.stdout(`${result}: ${rel}`);
   }
-  const fresh = JSON.parse(await readFile(pkgPath, "utf8"));
+  const fresh = JSON.parse(await readFile2(pkgPath, "utf8"));
   fresh.scripts ??= {};
   if (!fresh.scripts["content:check"]) {
     fresh.scripts["content:check"] = 'contentbit validate "content/**/*.md" --registry ./blocks/registry.ts';
-    await writeFile(pkgPath, `${JSON.stringify(fresh, null, 2)}
-`, "utf8");
     io.stdout("added script: content:check");
   }
+  if (!fresh.scripts["content:links"]) {
+    fresh.scripts["content:links"] = 'contentbit links "content/**/*.md"';
+    io.stdout("added script: content:links");
+  }
+  if (!pkg.scripts?.["content:check"] || !pkg.scripts?.["content:links"]) {
+    await writeFile2(pkgPath, `${JSON.stringify(fresh, null, 2)}
+`, "utf8");
+  }
   let registry2;
   try {
-    registry2 = await loadRegistry(join(cwd, "blocks/registry.ts"));
+    registry2 = await loadRegistry(join2(cwd, "blocks/registry.ts"));
   } catch {
     registry2 = await loadRegistry();
   }
   const guide = registry2.toAuthoringGuide({ audience: "llm", includeExamples: true });
-  await writeFile(join(cwd, "contentbit-guide.md"), guide, "utf8");
+  await writeFile2(join2(cwd, "contentbit-guide.md"), guide, "utf8");
   io.stdout("created: contentbit-guide.md (LLM authoring instructions)");
+  if (!values["no-agents"]) {
+    await installAgentIntegration(cwd, {}, io);
+    io.stdout("Agent integration installed \u2014 try asking your agent:");
+    io.stdout('  "write a blog post about X" or "audit my content"');
+  }
   io.stdout("");
   io.stdout("Done. Next steps:");
   io.stdout(`  1. Validate the starter content: ${detectPackageManager(cwd)} run content:check`);
+  io.stdout(`     Build the link index: ${detectPackageManager(cwd)} run content:links`);
   if (target === "react") {
     if (!values["no-page"] && layout.pagePath) {
       io.stdout("  2. Start the dev server and open /example to see the article rendered.");
@@ -16515,6 +17669,9 @@ async function initCommand(args, io) {
       io.stdout("     <Content source={...content/example.md as a string} />");
     }
     io.stdout("  3. Styled components: pnpm dlx shadcn@latest add @contentbit/generic-pack");
+  } else if (target === "astro") {
+    io.stdout("  2. Start the dev server and open /example to see the article rendered.");
+    io.stdout("  3. Styled components: pnpm dlx shadcn@latest add @contentbit/astro-pack");
   } else if (target === "html") {
     io.stdout("  2. Render it: node scripts/render-example.mjs && open example.html");
   } else {
@@ -16523,16 +17680,19 @@ async function initCommand(args, io) {
   io.stdout("  Docs: https://contentbit.dev/docs");
   return 0;
 }
-var TARGETS, MD_CHOICES, REGISTRY_TEMPLATE, EXAMPLE_CONTENT, TANSTACK_PAGE, NEXT_PAGE;
+var TARGETS, MD_CHOICES, REGISTRY_TEMPLATE, EXAMPLE_CONTENT, RELATED_CONTENT, TANSTACK_PAGE, NEXT_PAGE, ASTRO_CONTENT_CONFIG, ASTRO_QUOTE_BLOCK;
 var init_init = __esm({
   "src/commands/init.ts"() {
     "use strict";
     init_load_registry();
-    TARGETS = ["react", "html", "markdown"];
+    init_agents();
+    TARGETS = ["react", "html", "markdown", "astro"];
     MD_CHOICES = {
       react: ["react-markdown", "none"],
       html: ["marked", "markdown-it", "none"],
-      markdown: ["none"]
+      markdown: ["none"],
+      // @contentbit/astro ships its own marked-based default; nothing to install.
+      astro: ["none"]
     };
     REGISTRY_TEMPLATE = `// Custom block definitions for this project. The CLI and your app share
 // this module \u2014 Node 22.18+ imports TypeScript directly:
@@ -16562,7 +17722,18 @@ export const quote = defineBlock({
 
 export default [quote] satisfies BlockDefinition<unknown>[]
 `;
-    EXAMPLE_CONTENT = `# Hello, Content Blocks
+    EXAMPLE_CONTENT = `---
+slug: hello-content-blocks
+linksTo:
+  - related-contentbit-workflows
+aliases:
+  - getting-started-contentbit
+keywords:
+  primary: validated Markdown blocks
+  secondary: [content workflow, agent writing]
+---
+
+# Hello, Content Blocks
 
 Regular Markdown works everywhere. Blocks add validated structure:
 
@@ -16583,6 +17754,27 @@ by the \`QuoteBlock\` component, in about twenty lines:
 The Analytical Engine weaves algebraic patterns just as the Jacquard loom
 weaves flowers and leaves.
 :::
+`;
+    RELATED_CONTENT = `---
+slug: related-contentbit-workflows
+linksTo:
+  - hello-content-blocks
+keywords:
+  primary: contentbit workflow
+  secondary: [validation loop, internal links]
+---
+
+# Related contentbit workflows
+
+This supporting page exists to show internal links in frontmatter. The link
+graph is authored once with \`slug\` and \`linksTo\`, then contentbit derives
+\`linkedFrom\` in \`.contentbit/link-index.json\`.
+
+:::callout{type="note"}
+Run \`contentbit links "content/**/*.md" --fix\` after renaming a page. Alias
+references in \`linksTo\` are rewritten to the current slug, while \`aliases\`
+stays as the rename record.
+:::
 `;
     TANSTACK_PAGE = `import { createFileRoute } from '@tanstack/react-router'
 
@@ -16614,6 +17806,66 @@ export default async function ExamplePage() {
   )
 }
 `;
+    ASTRO_CONTENT_CONFIG = `import { defineCollection } from 'astro:content'
+import { glob } from 'astro/loaders'
+
+export const collections = {
+  articles: defineCollection({
+    // Astro's builtin Markdown loader. Entry bodies are parsed and validated
+    // where they render (see src/pages/example.astro); \`contentbit validate\`
+    // covers the same files in CI.
+    loader: glob({ pattern: '**/*.md', base: './content' }),
+  }),
+}
+`;
+    ASTRO_QUOTE_BLOCK = `---
+// The Astro component for the custom \`quote\` block defined in blocks/registry.ts.
+// Block props arrive as component props; nested content arrives via <slot />.
+interface Props {
+  author: string
+  role?: string
+}
+
+const { author, role } = Astro.props
+---
+
+<figure style="margin: 1.5rem 0; border-left: 2px solid #d4d4d4; padding-left: 1rem;">
+  <blockquote style="font-style: italic;"><slot /></blockquote>
+  <figcaption style="margin-top: 0.5rem; font-size: 0.875rem; opacity: 0.7;">
+    \u2014 {author}{role ? \`, \${role}\` : null}
+  </figcaption>
+</figure>
+`;
+  }
+});
+
+// src/link-options.ts
+function linkResolverOptions(values) {
+  const out = {};
+  const resolve = stringValue(values["link-resolve"]);
+  if (resolve) {
+    if (!isResolveMode(resolve)) throw new Error(`invalid --link-resolve ${resolve}`);
+    out.resolve = resolve;
+  }
+  const localeField = stringValue(values["locale-field"]);
+  const slugField = stringValue(values["slug-field"]);
+  const keyField = stringValue(values["key-field"]);
+  const defaultLocale = stringValue(values["default-locale"]);
+  if (localeField) out.localeField = localeField;
+  if (slugField) out.slugField = slugField;
+  if (keyField) out.keyField = keyField;
+  if (defaultLocale) out.defaultLocale = defaultLocale;
+  return out;
+}
+function stringValue(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function isResolveMode(value) {
+  return value === "global-slug" || value === "same-locale-slug" || value === "same-locale-key" || value === "prefer-same-locale-key-fallback-slug";
+}
+var init_link_options = __esm({
+  "src/link-options.ts"() {
+    "use strict";
   }
 });
 
@@ -16622,16 +17874,21 @@ var validate_exports = {};
 __export(validate_exports, {
   validateCommand: () => validateCommand
 });
-import { readFile as readFile2 } from "node:fs/promises";
-import { parseArgs as parseArgs2 } from "node:util";
+import { readFile as readFile3 } from "node:fs/promises";
+import { parseArgs as parseArgs3 } from "node:util";
 import { glob } from "tinyglobby";
 async function validateCommand(args, io) {
-  const { values, positionals } = parseArgs2({
+  const { values, positionals } = parseArgs3({
     args,
     allowPositionals: true,
     options: {
       registry: { type: "string" },
-      "strict-warnings": { type: "boolean", default: false }
+      "strict-warnings": { type: "boolean", default: false },
+      "link-resolve": { type: "string" },
+      "locale-field": { type: "string" },
+      "slug-field": { type: "string" },
+      "key-field": { type: "string" },
+      "default-locale": { type: "string" }
     }
   });
   if (positionals.length === 0) {
@@ -16644,17 +17901,27 @@ async function validateCommand(args, io) {
     return 2;
   }
   const registry2 = await loadRegistry(values.registry);
+  const linkOptions = linkResolverOptions(values);
   let errors = 0;
   let warnings = 0;
+  const linkInputs = [];
   for (const file2 of files.sort()) {
-    const source = await readFile2(file2, "utf8");
-    const result = validateDocument(parseDocument(source), registry2);
+    const source = await readFile3(file2, "utf8");
+    linkInputs.push({ path: file2, data: extractFrontmatter(source)?.data ?? {} });
+    const result = validateDocument(parseDocument(stripFrontmatter(source)), registry2);
     for (const d of result.diagnostics) {
       io.stderr(formatDiagnostic(d, file2));
       if (d.severity === "error") errors++;
       else if (d.severity === "warning") warnings++;
     }
   }
+  if (linkInputs.some((i) => "slug" in i.data)) {
+    for (const { file: file2, diagnostic } of validateLinks(linkInputs, linkOptions)) {
+      io.stderr(formatDiagnostic(diagnostic, file2));
+      if (diagnostic.severity === "error") errors++;
+      else if (diagnostic.severity === "warning") warnings++;
+    }
+  }
   io.stdout(`${files.length} file(s): ${errors} errors, ${warnings} warnings`);
   if (errors > 0) return 1;
   if (warnings > 0 && values["strict-warnings"]) return 1;
@@ -16662,6 +17929,64 @@ async function validateCommand(args, io) {
 }
 var init_validate2 = __esm({
   "src/commands/validate.ts"() {
+    "use strict";
+    init_dist();
+    init_link_options();
+    init_load_registry();
+  }
+});
+
+// src/commands/stats.ts
+var stats_exports = {};
+__export(stats_exports, {
+  statsCommand: () => statsCommand
+});
+import { readFile as readFile4 } from "node:fs/promises";
+import { parseArgs as parseArgs4 } from "node:util";
+import { glob as glob2 } from "tinyglobby";
+async function fileStats(file2, registry2) {
+  const source = await readFile4(file2, "utf8");
+  const stats = analyzeDocument(source, { path: file2 });
+  if (registry2) {
+    const result = validateDocument(parseDocument(stripFrontmatter(source)), registry2);
+    let errors = 0;
+    let warnings = 0;
+    for (const d of result.diagnostics) {
+      if (d.severity === "error") errors++;
+      else if (d.severity === "warning") warnings++;
+    }
+    stats.validation = { errors, warnings };
+  }
+  return stats;
+}
+async function statsCommand(args, io) {
+  const { values, positionals } = parseArgs4({
+    args,
+    allowPositionals: true,
+    options: {
+      registry: { type: "string" },
+      "no-validate": { type: "boolean", default: false }
+    }
+  });
+  if (positionals.length === 0) {
+    io.stderr("stats: provide at least one file or glob.");
+    return 2;
+  }
+  const files = await glob2(positionals, { absolute: true });
+  if (files.length === 0) {
+    io.stderr(`stats: no files matched ${positionals.join(" ")}`);
+    return 2;
+  }
+  const registry2 = values["no-validate"] ? null : await loadRegistry(values.registry);
+  const all = [];
+  for (const file2 of files.sort()) {
+    all.push(await fileStats(file2, registry2));
+  }
+  io.stdout(JSON.stringify(all.length === 1 ? all[0] : all, null, 2));
+  return 0;
+}
+var init_stats = __esm({
+  "src/commands/stats.ts"() {
     "use strict";
     init_dist();
     init_load_registry();
@@ -16748,12 +18073,18 @@ var init_blocks = __esm({
 });
 
 // ../html/dist/render.js
-function defaultMarkdown(md) {
+function fallbackMarkdown(md) {
   return md.trim().split(/\n{2,}/).map((p) => `<p>${escapeHtml(p)}</p>`).join("\n");
 }
+function invalidBlockHtml(node, prefix) {
+  return `<div class="${prefix}invalid" data-cb-invalid="${escapeHtml(node.name)}"><pre>${escapeHtml(node.body)}</pre></div>`;
+}
+function unrenderableBlockError(name) {
+  return new Error(`Cannot render block "${name}": not validated or no renderer registered.`);
+}
 function renderToHtml(document, opts = {}) {
   const prefix = opts.classPrefix ?? "cb-";
-  const renderMarkdown = opts.renderMarkdown ?? defaultMarkdown;
+  const renderMarkdown = opts.renderMarkdown ?? fallbackMarkdown;
   const renderers = { ...genericHtmlRenderers, ...opts.renderers };
   const onInvalid = opts.onInvalid ?? "fallback";
   const ctx = {
@@ -16767,13 +18098,11 @@ function renderToHtml(document, opts = {}) {
         const renderer = renderers[node.name];
         if (renderer && isValidatedBlock(node))
           return renderer(node, ctx);
-        if (onInvalid === "strict") {
-          throw new Error(`Cannot render block "${node.name}": not validated or no renderer registered.`);
-        }
-        if (onInvalid === "annotated") {
-          return `<div class="${prefix}invalid" data-cb-invalid="${escapeHtml(node.name)}"><pre>${escapeHtml(node.body)}</pre></div>`;
-        }
-        return defaultMarkdown(node.body);
+        if (onInvalid === "strict")
+          throw unrenderableBlockError(node.name);
+        if (onInvalid === "annotated")
+          return invalidBlockHtml(node, prefix);
+        return fallbackMarkdown(node.body);
       }).join("\n");
     }
   };
@@ -16801,10 +18130,10 @@ var render_exports = {};
 __export(render_exports, {
   renderCommand: () => renderCommand
 });
-import { readFile as readFile3 } from "node:fs/promises";
-import { parseArgs as parseArgs3 } from "node:util";
+import { readFile as readFile5 } from "node:fs/promises";
+import { parseArgs as parseArgs5 } from "node:util";
 async function renderCommand(args, io) {
-  const { values, positionals } = parseArgs3({
+  const { values, positionals } = parseArgs5({
     args,
     allowPositionals: true,
     options: {
@@ -16819,8 +18148,8 @@ async function renderCommand(args, io) {
     return 2;
   }
   const registry2 = await loadRegistry(values.registry);
-  const source = await readFile3(file2, "utf8");
-  const result = validateDocument(parseDocument(source), registry2);
+  const source = await readFile5(file2, "utf8");
+  const result = validateDocument(parseDocument(stripFrontmatter(source)), registry2);
   if (!result.ok) {
     for (const d of result.diagnostics) io.stderr(formatDiagnostic(d, file2));
     return 1;
@@ -16845,9 +18174,9 @@ var instructions_exports = {};
 __export(instructions_exports, {
   instructionsCommand: () => instructionsCommand
 });
-import { parseArgs as parseArgs4 } from "node:util";
+import { parseArgs as parseArgs6 } from "node:util";
 async function instructionsCommand(args, io) {
-  const { values } = parseArgs4({
+  const { values } = parseArgs6({
     args,
     options: {
       audience: { type: "string", default: "llm" },
@@ -16877,9 +18206,9 @@ var docs_exports = {};
 __export(docs_exports, {
   docsCommand: () => docsCommand
 });
-import { parseArgs as parseArgs5 } from "node:util";
+import { parseArgs as parseArgs7 } from "node:util";
 async function docsCommand(args, io) {
-  const { values } = parseArgs5({
+  const { values } = parseArgs7({
     args,
     options: {
       registry: { type: "string" },
@@ -16899,21 +18228,142 @@ var init_docs = __esm({
   }
 });
 
+// src/links-io.ts
+import { readFile as readFile6 } from "node:fs/promises";
+async function collectLinkInputs(files) {
+  const inputs = [];
+  for (const path of files) {
+    const source = await readFile6(path, "utf8");
+    const fm = extractFrontmatter(source);
+    inputs.push({ path, data: fm?.data ?? {} });
+  }
+  return inputs;
+}
+var init_links_io = __esm({
+  "src/links-io.ts"() {
+    "use strict";
+    init_dist();
+  }
+});
+
+// src/commands/links.ts
+var links_exports = {};
+__export(links_exports, {
+  linksCommand: () => linksCommand
+});
+import { mkdir as mkdir3, readFile as readFile7 } from "node:fs/promises";
+import { dirname, join as join3 } from "node:path";
+import { parseArgs as parseArgs8 } from "node:util";
+import { glob as glob3 } from "tinyglobby";
+async function linksCommand(args, io) {
+  const { values, positionals } = parseArgs8({
+    args,
+    allowPositionals: true,
+    options: {
+      out: { type: "string" },
+      fix: { type: "boolean", default: false },
+      "link-resolve": { type: "string" },
+      "locale-field": { type: "string" },
+      "slug-field": { type: "string" },
+      "key-field": { type: "string" },
+      "default-locale": { type: "string" }
+    }
+  });
+  if (positionals.length === 0) {
+    io.stderr("links: provide at least one file or glob.");
+    return 2;
+  }
+  const files = (await glob3(positionals, { absolute: true })).sort();
+  if (files.length === 0) {
+    io.stderr(`links: no files matched ${positionals.join(" ")}`);
+    return 2;
+  }
+  const inputs = await collectLinkInputs(files);
+  const linkOptions = linkResolverOptions(values);
+  let errors = 0;
+  let warnings = 0;
+  for (const { file: file2, diagnostic } of validateLinks(inputs, linkOptions)) {
+    io.stderr(formatDiagnostic(diagnostic, file2));
+    if (diagnostic.severity === "error") errors++;
+    else if (diagnostic.severity === "warning") warnings++;
+  }
+  const index = buildLinkIndex(inputs, linkOptions);
+  if (values.fix && errors > 0) {
+    io.stderr("links: --fix skipped because link errors must be resolved first.");
+  } else if (values.fix && index.aliases.size > 0) {
+    for (const file2 of files) {
+      const source = await readFile7(file2, "utf8");
+      const fm = extractFrontmatter(source);
+      if (!fm) continue;
+      const lines = source.split("\n");
+      let changed = false;
+      let inLinksTo = false;
+      for (let i = 0; i < fm.lines.end && i < lines.length; i++) {
+        const line = lines[i];
+        const topKey = line.match(/^([A-Za-z0-9_.-]+):(.*)$/);
+        if (topKey) inLinksTo = topKey[1] === "linksTo";
+        if (!inLinksTo) continue;
+        let next = line;
+        for (const [alias, current] of aliasReplacementsForPage(index, fm.data)) {
+          const re = new RegExp(`(^|[\\s\\[,'"-])${escapeRe(alias)}($|[\\s\\],'"])`, "g");
+          next = next.replace(re, (_m, p1, p2) => `${p1}${current}${p2}`);
+        }
+        if (next !== line) {
+          lines[i] = next;
+          changed = true;
+        }
+      }
+      if (changed) {
+        await io.writeFile(file2, lines.join("\n"));
+        io.stdout(`fixed alias references in ${file2}`);
+      }
+    }
+  }
+  const outPath = values.out ?? join3(process.cwd(), ".contentbit", "link-index.json");
+  await mkdir3(dirname(outPath), { recursive: true });
+  await io.writeFile(outPath, JSON.stringify(serializeLinkIndex(index), null, 2) + "\n");
+  let edges = 0;
+  for (const p of index.pages.values()) edges += p.linksTo.length;
+  const orphans = [...index.pages.values()].filter((p) => p.linkedFrom.length === 0).length;
+  io.stdout(
+    `${index.pages.size} page(s), ${edges} link(s), ${orphans} orphan(s): ${errors} errors, ${warnings} warnings`
+  );
+  io.stdout(`index written to ${outPath}`);
+  return errors > 0 ? 1 : 0;
+}
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+var init_links2 = __esm({
+  "src/commands/links.ts"() {
+    "use strict";
+    init_dist();
+    init_link_options();
+    init_links_io();
+  }
+});
+
 // src/run.ts
-var USAGE = `Usage: contentbit <init|validate|render|instructions|docs> [options]
+var USAGE = `Usage: contentbit <init|validate|stats|render|instructions|docs|agents|links> [options]
 
-  init [-t react|html|markdown] [--md ...] [-y] [--no-install] [--no-page]
+  init [-t react|html|markdown|astro] [--md ...] [-y] [--no-install] [--no-page] [--no-agents]
+  agents [--claude] [--no-agents-md]
 
-  validate <globs...> [--registry <module.mjs>] [--strict-warnings]
+  validate <globs...> [--registry <module.mjs>] [--strict-warnings] [--link-resolve <mode>]
+  stats <globs...> [--registry <module.mjs>] [--no-validate]
   render <file> --target html|markdown [--registry <module.mjs>] [--out <file>]
   instructions [--audience llm|human] [--no-examples] [--registry <module.mjs>] [--out <file>]
-  docs [--registry <module.mjs>] [--out <file>]`;
+  docs [--registry <module.mjs>] [--out <file>]
+  links <globs...> [--fix] [--out <file>] [--link-resolve <mode>]`;
 var commands = {
   init: async () => (await Promise.resolve().then(() => (init_init(), init_exports))).initCommand,
   validate: async () => (await Promise.resolve().then(() => (init_validate2(), validate_exports))).validateCommand,
+  stats: async () => (await Promise.resolve().then(() => (init_stats(), stats_exports))).statsCommand,
   render: async () => (await Promise.resolve().then(() => (init_render2(), render_exports))).renderCommand,
   instructions: async () => (await Promise.resolve().then(() => (init_instructions(), instructions_exports))).instructionsCommand,
-  docs: async () => (await Promise.resolve().then(() => (init_docs(), docs_exports))).docsCommand
+  docs: async () => (await Promise.resolve().then(() => (init_docs(), docs_exports))).docsCommand,
+  agents: async () => (await Promise.resolve().then(() => (init_agents(), agents_exports))).agentsCommand,
+  links: async () => (await Promise.resolve().then(() => (init_links2(), links_exports))).linksCommand
 };
 async function run(argv, io) {
   const [name, ...rest] = argv;