contentbit 0.1.1 → 0.3.0

package/dist/commands/agents.d.ts

@@ -0,0 +1,11 @@
+import type { Io } from '../run.js';
+export interface AgentOptions {
+    /** Install Claude Code skills; defaults to detecting a .claude/ directory. */
+    claude?: boolean;
+    /** Manage the AGENTS.md block; defaults to true. */
+    agentsMd?: boolean;
+}
+/** Install or refresh the agent integration. Shared by `agents` and `init`. */
+export declare function installAgentIntegration(cwd: string, options: AgentOptions, io: Io): Promise<void>;
+export declare function agentsCommand(args: string[], io: Io): Promise<number>;
+//# sourceMappingURL=agents.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,243 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+// Everything here is static and project-independent by design: skills fetch
+// live data (authoring guide, stats, diagnostics) by running the CLI, so the
+// 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 = 2;
+const 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 — 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 — 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 — 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\` — 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.
+`;
+const 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 — thin pages, missing
+  structure, validation issues — 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** — broken content ships broken pages.
+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.
+6. **Missing or inconsistent frontmatter** compared to sibling documents.
+7. **Structural imbalance** — 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) — offer that as a follow-up.
+`;
+const AGENTS_MD_BLOCK = `<!-- contentbit:start -->
+
+## contentbit content (generated — 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 — 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. 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 -->`;
+const START = '<!-- contentbit:start -->';
+const END = '<!-- contentbit:end -->';
+/** Insert or replace the fenced contentbit block, leaving the rest untouched. */
+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}\n`;
+    return `${existing.replace(/\n*$/, '\n\n')}${AGENTS_MD_BLOCK}\n`;
+}
+/** Install or refresh the agent integration. Shared by `agents` and `init`. */
+export 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 {
+            /* not there yet */
+        }
+        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`);
+        }
+    }
+}
+export 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 || undefined, // false means "detect", not "skip"
+        agentsMd: !values['no-agents-md'],
+    }, io);
+    return 0;
+}

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;AAiSnC,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAyMzE"}
+{"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

@@ -4,12 +4,15 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { parseArgs } from 'node:util';
 import { loadRegistry } from '../load-registry.js';
-const TARGETS = ['react', 'html', 'markdown'];
+import { installAgentIntegration } from './agents.js';
+const TARGETS = ['react', 'html', 'markdown', 'astro'];
 /** Markdown library choices per target; the first entry is the default. */
 const MD_CHOICES = {
     react: ['react-markdown', 'none'],
     html: ['marked', 'markdown-it', 'none'],
     markdown: ['none'],
+    // @contentbit/astro ships its own marked-based default; nothing to install.
+    astro: ['none'],
 };
 const REGISTRY_TEMPLATE = `// Custom block definitions for this project. The CLI and your app share
 // this module — Node 22.18+ imports TypeScript directly:
@@ -75,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:
 
@@ -97,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" : '';
@@ -114,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.
@@ -124,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}
@@ -148,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')
@@ -213,6 +248,67 @@ export default async function ExamplePage() {
   )
 }
 `;
+const 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' }),
+  }),
+}
+`;
+const 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;">
+    — {author}{role ? \`, \${role}\` : null}
+  </figcaption>
+</figure>
+`;
+/** The example page: styled pack renderer or the headless ContentBlocks. */
+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) {
     // The project's lockfile outranks however the CLI itself was launched.
     const locks = [
@@ -253,6 +349,27 @@ function runInstall(pm, args, cwd) {
         child.on('error', () => resolve(1));
     });
 }
+/** Wire the @contentbit shadcn registry and install a styled pack. Returns true on success. */
+async function installStyledPack(cwd, pack, noInstall, io) {
+    const componentsJsonPath = join(cwd, 'components.json');
+    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)}\n`, '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;
+}
 /** Write a file unless it already exists; returns what happened for the summary. */
 async function scaffold(path, content) {
     try {
@@ -276,6 +393,7 @@ export async function initCommand(args, io) {
             'no-install': { type: 'boolean', default: false },
             'no-page': { type: 'boolean', default: false },
             'no-styled': { type: 'boolean', default: false },
+            'no-agents': { type: 'boolean', default: false },
         },
     });
     const cwd = values.cwd;
@@ -291,7 +409,8 @@ export async function initCommand(args, io) {
     }
     // Resolve the render target: flag > prompt (interactive) > detection.
     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)) {
@@ -307,6 +426,7 @@ export 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' },
             ],
@@ -353,6 +473,8 @@ export async function initCommand(args, io) {
         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']) {
@@ -374,32 +496,14 @@ 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.
     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)}\n`, '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');
-        }
+        styled = await installStyledPack(cwd, '@contentbit/generic-pack', values['no-install'], io);
     }
     if (target === 'react') {
         const depth = layout.componentPath.split('/').length - 1;
@@ -420,19 +524,50 @@ export async function initCommand(args, io) {
             htmlRenderScript(md),
         ]);
     }
+    if (target === 'astro') {
+        let astroStyled = false;
+        if (!values['no-styled'] && existsSync(componentsJsonPath)) {
+            astroStyled = await installStyledPack(cwd, '@contentbit/astro-pack', values['no-install'], io);
+        }
+        files.push(['blocks/QuoteBlock.astro', ASTRO_QUOTE_BLOCK]);
+        // Every config filename Astro resolves (src/content.config.* plus the
+        // legacy src/content/config.* location), so we never scaffold a second
+        // config that Astro would silently ignore.
+        const configCandidates = ['ts', 'mts', 'mjs', 'js'].flatMap((ext) => [
+            `src/content.config.${ext}`,
+            `src/content/config.${ext}`,
+        ]);
+        const existingConfig = configCandidates.find((p) => existsSync(join(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);
         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 {
@@ -445,9 +580,17 @@ export async function initCommand(args, io) {
     const guide = registry.toAuthoringGuide({ audience: 'llm', includeExamples: true });
     await writeFile(join(cwd, 'contentbit-guide.md'), guide, 'utf8');
     io.stdout('created: contentbit-guide.md (LLM authoring instructions)');
+    // Coding-agent integration: an AGENTS.md block for every agent, plus Claude
+    // Code skills when a .claude/ directory exists. `contentbit agents` refreshes.
+    if (!values['no-agents']) {
+        await installAgentIntegration(cwd, {}, io);
+        io.stdout('Agent integration installed — 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.');
@@ -458,6 +601,10 @@ export async function initCommand(args, io) {
         }
         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');
     }

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"}