contentbit 0.2.0 → 0.3.0

package/dist/commands/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/commands/agents.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,WAAW,CAAA;AA2JnC,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,+EAA+E;AAC/E,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,YAAY,EACrB,EAAE,EAAE,EAAE,GACL,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAkB3E"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/commands/agents.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,WAAW,CAAA;AAyMnC,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,+EAA+E;AAC/E,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,YAAY,EACrB,EAAE,EAAE,EAAE,GACL,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAkB3E"}

package/dist/commands/agents.js

@@ -7,7 +7,7 @@ import { parseArgs } from 'node:util';
 // registry stays the single source of truth and nothing can drift. Bump the
 // frontmatter version when a template changes; `contentbit agents` re-runs
 // overwrite in place.
-const TEMPLATE_VERSION = 1;
+const TEMPLATE_VERSION = 2;
 const AUTHOR_SKILL = `---
 name: contentbit-author
 description: |
@@ -30,6 +30,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
 
@@ -44,7 +46,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:**
 
@@ -54,8 +68,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
 
@@ -77,6 +102,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
 
@@ -85,23 +112,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** — broken content ships broken pages.
-2. **Thin documents** — outline sections with very low word counts.
-3. **Block-less documents** — \`blocks.byName\` empty where sibling documents
+2. **Internal-link errors** — unresolved links, duplicate slugs, and alias
+   conflicts from \`contentbit links\`.
+3. **Orphans and self-links** — link warnings that point to isolated or noisy
+   pages.
+4. **Thin documents** — outline sections with very low word counts.
+5. **Block-less documents** — \`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** — skipped heading levels, single-section walls of text.
+6. **Missing or inconsistent frontmatter** compared to sibling documents.
+7. **Structural imbalance** — skipped heading levels, single-section walls of text.
 
 ## Report
 
@@ -117,14 +152,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 — the content glob and the \`--registry\` flag — 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 — 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:
 
@@ -132,6 +175,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.

package/dist/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,WAAW,CAAA;AAgYnC,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAyNzE"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,WAAW,CAAA;AAianC,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAqOzE"}

package/dist/commands/init.js

@@ -78,7 +78,18 @@ export const blockComponents: Record<string, BlockComponent> = {
 }
 `;
 }
-const EXAMPLE_CONTENT = `# Hello, Content Blocks
+const 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:
 
@@ -100,6 +111,27 @@ The Analytical Engine weaves algebraic patterns just as the Jacquard loom
 weaves flowers and leaves.
 :::
 `;
+const 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.
+:::
+`;
 /** The wrapper component: styled pack or headless, with or without a Markdown lib. */
 function reactComponent(styled, mdWired, blocksImport) {
     const mdImport = mdWired ? "import ReactMarkdown from 'react-markdown'\n" : '';
@@ -117,7 +149,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.
@@ -127,7 +159,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}
@@ -151,14 +183,14 @@ const renderMarkdown = (md) => mdIt.render(md)`
 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')
@@ -464,6 +496,7 @@ export async function initCommand(args, io) {
     const files = [
         ['blocks/registry.ts', REGISTRY_TEMPLATE],
         ['content/example.md', EXAMPLE_CONTENT],
+        ['content/related.md', RELATED_CONTENT],
     ];
     const layout = detectFramework(cwd, { ...pkg.dependencies, ...pkg.devDependencies });
     // shadcn project? Pull the styled component pack from the contentbit registry.
@@ -520,15 +553,21 @@ export async function initCommand(args, io) {
         const result = await scaffold(join(cwd, rel), content);
         io.stdout(`${result}: ${rel}`);
     }
-    // Wire the validate script.
+    // Wire content scripts.
     const fresh = JSON.parse(await readFile(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)}\n`, '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 writeFile(pkgPath, `${JSON.stringify(fresh, null, 2)}\n`, 'utf8');
+    }
     // Generate the LLM authoring guide from the registry, ready to paste into a prompt.
     let registry;
     try {
@@ -551,6 +590,7 @@ export 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.');

package/dist/commands/links.d.ts

@@ -0,0 +1,3 @@
+import type { Io } from '../run.js';
+export declare function linksCommand(args: string[], io: Io): Promise<number>;
+//# sourceMappingURL=links.d.ts.map

package/dist/commands/links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.d.ts","sourceRoot":"","sources":["../../src/commands/links.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,WAAW,CAAA;AAKnC,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAuF1E"}

package/dist/commands/links.js

@@ -0,0 +1,97 @@
+import { aliasReplacementsForPage, buildLinkIndex, extractFrontmatter, formatDiagnostic, serializeLinkIndex, validateLinks, } from '@contentbit/core';
+import { mkdir, readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { glob } from 'tinyglobby';
+import { linkResolverOptions } from '../link-options.js';
+import { collectLinkInputs } from '../links-io.js';
+export async function linksCommand(args, io) {
+    const { values, positionals } = parseArgs({
+        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 glob(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, diagnostic } of validateLinks(inputs, linkOptions)) {
+        io.stderr(formatDiagnostic(diagnostic, file));
+        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 file of files) {
+            const source = await readFile(file, 'utf8');
+            const fm = extractFrontmatter(source);
+            if (!fm)
+                continue;
+            const lines = source.split('\n');
+            let changed = false;
+            // Only rewrite alias tokens inside the `linksTo:` block — never inside an
+            // `aliases:` list (which records the rename and must stay intact), and
+            // never in document body. Track whether we are within linksTo's scope:
+            // a top-level key resets it, dash-list / inline continuation keeps it.
+            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(file, lines.join('\n'));
+                io.stdout(`fixed alias references in ${file}`);
+            }
+        }
+    }
+    const outPath = values.out ?? join(process.cwd(), '.contentbit', 'link-index.json');
+    // The default target lives in a .contentbit/ dir that may not exist yet, and
+    // the shared Io.writeFile is a thin fs wrapper that won't create it.
+    await mkdir(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, '\\$&');
+}

package/dist/commands/render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/commands/render.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,WAAW,CAAA;AAInC,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA6B3E"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/commands/render.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,WAAW,CAAA;AAInC,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA6B3E"}

package/dist/commands/render.js

@@ -1,5 +1,5 @@
 import { genericMarkdownRenderers } from '@contentbit/blocks';
-import { formatDiagnostic, parseDocument, renderToMarkdown, validateDocument, } from '@contentbit/core';
+import { formatDiagnostic, parseDocument, renderToMarkdown, stripFrontmatter, validateDocument, } from '@contentbit/core';
 import { renderToHtml } from '@contentbit/html';
 import { readFile } from 'node:fs/promises';
 import { parseArgs } from 'node:util';
@@ -21,7 +21,7 @@ export async function renderCommand(args, io) {
     }
     const registry = await loadRegistry(values.registry);
     const source = await readFile(file, 'utf8');
-    const result = validateDocument(parseDocument(source), registry);
+    const result = validateDocument(parseDocument(stripFrontmatter(source)), registry);
     if (!result.ok) {
         for (const d of result.diagnostics)
             io.stderr(formatDiagnostic(d, file));

package/dist/commands/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,WAAW,CAAA;AAInC,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAsC7E"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,WAAW,CAAA;AAKnC,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAwD7E"}

package/dist/commands/validate.js

@@ -1,7 +1,8 @@
-import { formatDiagnostic, parseDocument, stripFrontmatter, validateDocument, } from '@contentbit/core';
+import { extractFrontmatter, formatDiagnostic, parseDocument, stripFrontmatter, validateDocument, validateLinks, } from '@contentbit/core';
 import { readFile } from 'node:fs/promises';
 import { parseArgs } from 'node:util';
 import { glob } from 'tinyglobby';
+import { linkResolverOptions } from '../link-options.js';
 import { loadRegistry } from '../load-registry.js';
 export async function validateCommand(args, io) {
     const { values, positionals } = parseArgs({
@@ -10,6 +11,11 @@ export async function validateCommand(args, io) {
         options: {
             registry: { type: 'string' },
             '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) {
@@ -22,13 +28,16 @@ export async function validateCommand(args, io) {
         return 2;
     }
     const registry = await loadRegistry(values.registry);
+    const linkOptions = linkResolverOptions(values);
     let errors = 0;
     let warnings = 0;
+    const linkInputs = [];
     for (const file of files.sort()) {
         const source = await readFile(file, 'utf8');
         // Frontmatter is metadata, not content: blanked (positions preserved) so
         // block syntax inside YAML never produces diagnostics — matching what
         // frontmatter-aware consumers like Astro validate from entry bodies.
+        linkInputs.push({ path: file, data: extractFrontmatter(source)?.data ?? {} });
         const result = validateDocument(parseDocument(stripFrontmatter(source)), registry);
         for (const d of result.diagnostics) {
             io.stderr(formatDiagnostic(d, file));
@@ -38,6 +47,16 @@ export async function validateCommand(args, io) {
                 warnings++;
         }
     }
+    // Cross-file internal-link checks, only when the project uses linking.
+    if (linkInputs.some((i) => 'slug' in i.data)) {
+        for (const { file, diagnostic } of validateLinks(linkInputs, linkOptions)) {
+            io.stderr(formatDiagnostic(diagnostic, file));
+            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;

package/dist/link-options.d.ts

@@ -0,0 +1,10 @@
+import type { LinkResolverOptions } from '@contentbit/core';
+export interface LinkOptionValues {
+    'link-resolve'?: string | boolean;
+    'locale-field'?: string | boolean;
+    'slug-field'?: string | boolean;
+    'key-field'?: string | boolean;
+    'default-locale'?: string | boolean;
+}
+export declare function linkResolverOptions(values: LinkOptionValues): LinkResolverOptions;
+//# sourceMappingURL=link-options.d.ts.map

package/dist/link-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-options.d.ts","sourceRoot":"","sources":["../src/link-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAE3D,MAAM,WAAW,gBAAgB;IAC/B,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACjC,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACjC,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IAC/B,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IAC9B,gBAAgB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CACpC;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,gBAAgB,GAAG,mBAAmB,CAgBjF"}

package/dist/link-options.js

@@ -0,0 +1,31 @@
+export 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 : undefined;
+}
+function isResolveMode(value) {
+    return (value === 'global-slug' ||
+        value === 'same-locale-slug' ||
+        value === 'same-locale-key' ||
+        value === 'prefer-same-locale-key-fallback-slug');
+}

package/dist/links-io.d.ts

@@ -0,0 +1,3 @@
+import { type LinkInput } from '@contentbit/core';
+export declare function collectLinkInputs(files: string[]): Promise<LinkInput[]>;
+//# sourceMappingURL=links-io.d.ts.map

package/dist/links-io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"links-io.d.ts","sourceRoot":"","sources":["../src/links-io.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAMrE,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAQ7E"}

package/dist/links-io.js

@@ -0,0 +1,14 @@
+import { extractFrontmatter } from '@contentbit/core';
+import { readFile } from 'node:fs/promises';
+// Read each file's frontmatter (head only — bodies are never parsed) into the
+// LinkInput shape the core link functions consume. Files with no frontmatter
+// contribute an empty data object (a non-participating page).
+export async function collectLinkInputs(files) {
+    const inputs = [];
+    for (const path of files) {
+        const source = await readFile(path, 'utf8');
+        const fm = extractFrontmatter(source);
+        inputs.push({ path, data: fm?.data ?? {} });
+    }
+    return inputs;
+}

package/dist/run.d.ts

@@ -3,6 +3,6 @@ export interface Io {
     stderr(line: string): void;
     writeFile(path: string, content: string): Promise<void>;
 }
-export declare const USAGE = "Usage: contentbit <init|validate|stats|render|instructions|docs|agents> [options]\n\n  init [-t react|html|markdown|astro] [--md ...] [-y] [--no-install] [--no-page] [--no-agents]\n  agents [--claude] [--no-agents-md]\n\n  validate <globs...> [--registry <module.mjs>] [--strict-warnings]\n  stats <globs...> [--registry <module.mjs>] [--no-validate]\n  render <file> --target html|markdown [--registry <module.mjs>] [--out <file>]\n  instructions [--audience llm|human] [--no-examples] [--registry <module.mjs>] [--out <file>]\n  docs [--registry <module.mjs>] [--out <file>]";
+export declare const USAGE = "Usage: contentbit <init|validate|stats|render|instructions|docs|agents|links> [options]\n\n  init [-t react|html|markdown|astro] [--md ...] [-y] [--no-install] [--no-page] [--no-agents]\n  agents [--claude] [--no-agents-md]\n\n  validate <globs...> [--registry <module.mjs>] [--strict-warnings] [--link-resolve <mode>]\n  stats <globs...> [--registry <module.mjs>] [--no-validate]\n  render <file> --target html|markdown [--registry <module.mjs>] [--out <file>]\n  instructions [--audience llm|human] [--no-examples] [--registry <module.mjs>] [--out <file>]\n  docs [--registry <module.mjs>] [--out <file>]\n  links <globs...> [--fix] [--out <file>] [--link-resolve <mode>]";
 export declare function run(argv: string[], io: Io): Promise<number>;
 //# sourceMappingURL=run.d.ts.map

package/dist/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,EAAE;IACjB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACxD;AAED,eAAO,MAAM,KAAK,qkBAS8B,CAAA;AAchD,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAcjE"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,EAAE;IACjB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACxD;AAED,eAAO,MAAM,KAAK,sqBAUgD,CAAA;AAelE,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAcjE"}