contentbit 0.2.0 → 0.3.0

package/dist/run.js

@@ -371,12 +371,58 @@ function parseValue(value, indented) {
     if (indented.length === 0)
       return null;
     const items = dedent(indented);
-    if (items.every((l) => l.startsWith("- ")))
-      return items.map((l) => parseScalar(l.slice(2).trim()));
+    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));
@@ -408,6 +454,20 @@ function parseScalar(value) {
       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) {
@@ -1096,21 +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_frontmatter();
-    init_analyze();
-    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) {
@@ -1175,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.`);
@@ -11344,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();
@@ -16192,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({
@@ -16616,7 +17090,7 @@ var TEMPLATE_VERSION, AUTHOR_SKILL, AUDIT_SKILL, AGENTS_MD_BLOCK, START, END;
 var init_agents = __esm({
   "src/commands/agents.ts"() {
     "use strict";
-    TEMPLATE_VERSION = 1;
+    TEMPLATE_VERSION = 2;
     AUTHOR_SKILL = `---
 name: contentbit-author
 description: |
@@ -16639,6 +17113,8 @@ 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
 
@@ -16653,7 +17129,19 @@ below. No script? Default to \`content/**/*.md\` with no \`--registry\` flag.
 
 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.
+   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:**
 
@@ -16663,8 +17151,19 @@ below. No script? Default to \`content/**/*.md\` with no \`--registry\` flag.
 
    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. Fix every diagnostic and re-run. Never finish with a failing
-   validate.
+   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
 
@@ -16686,6 +17185,8 @@ version: ${TEMPLATE_VERSION}
 
 \`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
 
@@ -16694,23 +17195,31 @@ 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. **Thin documents** \u2014 outline sections with very low word counts.
-3. **Block-less documents** \u2014 \`blocks.byName\` empty where sibling documents
+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.
-4. **Missing or inconsistent frontmatter** compared to sibling documents.
-5. **Structural imbalance** \u2014 skipped heading levels, single-section walls of text.
+6. **Missing or inconsistent frontmatter** compared to sibling documents.
+7. **Structural imbalance** \u2014 skipped heading levels, single-section walls of text.
 
 ## Report
 
@@ -16726,14 +17235,22 @@ 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. Validate until clean (exit 0): \`contentbit validate <file> [--registry <path>]\`.
+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:
 
@@ -16741,6 +17258,9 @@ When auditing content health:
   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.
@@ -16808,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.
@@ -16818,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}
@@ -16838,14 +17358,14 @@ 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')
@@ -17058,7 +17578,8 @@ 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;
@@ -17112,9 +17633,15 @@ async function initCommand(args, io) {
   fresh.scripts ??= {};
   if (!fresh.scripts["content:check"]) {
     fresh.scripts["content:check"] = 'contentbit validate "content/**/*.md" --registry ./blocks/registry.ts';
+    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");
-    io.stdout("added script: content:check");
   }
   let registry2;
   try {
@@ -17133,6 +17660,7 @@ async function initCommand(args, io) {
   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.");
@@ -17152,7 +17680,7 @@ 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, ASTRO_CONTENT_CONFIG, ASTRO_QUOTE_BLOCK;
+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";
@@ -17194,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:
 
@@ -17215,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'
 
@@ -17279,6 +17839,36 @@ const { author, role } = Astro.props
   }
 });
 
+// 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";
+  }
+});
+
 // src/commands/validate.ts
 var validate_exports = {};
 __export(validate_exports, {
@@ -17293,7 +17883,12 @@ async function validateCommand(args, io) {
     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) {
@@ -17306,10 +17901,13 @@ 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 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));
@@ -17317,6 +17915,13 @@ async function validateCommand(args, io) {
       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;
@@ -17326,6 +17931,7 @@ var init_validate2 = __esm({
   "src/commands/validate.ts"() {
     "use strict";
     init_dist();
+    init_link_options();
     init_load_registry();
   }
 });
@@ -17543,7 +18149,7 @@ async function renderCommand(args, io) {
   }
   const registry2 = await loadRegistry(values.registry);
   const source = await readFile5(file2, "utf8");
-  const result = validateDocument(parseDocument(source), registry2);
+  const result = validateDocument(parseDocument(stripFrontmatter(source)), registry2);
   if (!result.ok) {
     for (const d of result.diagnostics) io.stderr(formatDiagnostic(d, file2));
     return 1;
@@ -17622,17 +18228,133 @@ 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|stats|render|instructions|docs|agents> [options]
+var USAGE = `Usage: contentbit <init|validate|stats|render|instructions|docs|agents|links> [options]
 
   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,
@@ -17640,7 +18362,8 @@ var commands = {
   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,
-  agents: async () => (await Promise.resolve().then(() => (init_agents(), agents_exports))).agentsCommand
+  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;