contentbit 0.1.1 → 0.2.0

package/dist/run.js

@@ -319,6 +319,323 @@ var init_parser = __esm({
   }
 });
 
+// ../core/dist/frontmatter.js
+function stripFrontmatter(source) {
+  const match = FM_RE.exec(source);
+  if (!match)
+    return source;
+  return match[0].replace(/[^\n]+/g, "") + source.slice(match[0].length);
+}
+function extractFrontmatter(source) {
+  const match = source.match(FM_RE);
+  if (!match)
+    return null;
+  const blockLines = match[0].replace(/\r?\n$/, "").split(/\r?\n/);
+  const inner = blockLines.slice(1, -1);
+  const { data, keys } = parseYamlSubset(inner);
+  return { raw: inner.join("\n"), data, keys, lines: { start: 1, end: blockLines.length } };
+}
+function parseYamlSubset(lines) {
+  const data = {};
+  const keys = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#") || /^[ \t]/.test(line)) {
+      i++;
+      continue;
+    }
+    const m = line.match(KEY_RE2);
+    if (!m) {
+      i++;
+      continue;
+    }
+    const [, key, rawValue] = m;
+    const value = rawValue.trim();
+    i++;
+    const indented = [];
+    while (i < lines.length && /^[ \t]/.test(lines[i]) && lines[i].trim() !== "") {
+      indented.push(lines[i]);
+      i++;
+    }
+    keys.push(key);
+    data[key] = parseValue(value, indented);
+  }
+  return { data, keys };
+}
+function parseValue(value, indented) {
+  if (/^[|>][+-]?$/.test(value))
+    return dedent(indented).join("\n");
+  if (value === "") {
+    if (indented.length === 0)
+      return null;
+    const items = dedent(indented);
+    if (items.every((l) => l.startsWith("- ")))
+      return items.map((l) => parseScalar(l.slice(2).trim()));
+    return items.join("\n");
+  }
+  return parseScalar(value);
+}
+function dedent(lines) {
+  const indent = Math.min(...lines.map((l) => l.match(/^[ \t]*/)[0].length));
+  return lines.map((l) => l.slice(indent));
+}
+function parseScalar(value) {
+  if (value === "" || value === "null" || value === "~")
+    return null;
+  if (value === "true")
+    return true;
+  if (value === "false")
+    return false;
+  if (/^[+-]?\d+$/.test(value))
+    return Number.parseInt(value, 10);
+  if (/^[+-]?\d*\.\d+$/.test(value))
+    return Number.parseFloat(value);
+  if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return value.slice(1, -1);
+    }
+  }
+  if (value.startsWith("'") && value.endsWith("'") && value.length >= 2) {
+    return value.slice(1, -1).replace(/''/g, "'");
+  }
+  if (value.startsWith("[") && value.endsWith("]")) {
+    const inner = value.slice(1, -1).trim();
+    if (inner === "")
+      return [];
+    return splitInlineItems(inner).map((item) => parseScalar(item.trim()));
+  }
+  return value;
+}
+function splitInlineItems(inner) {
+  const items = [];
+  let current = "";
+  let quote = null;
+  for (const ch of inner) {
+    if (quote) {
+      current += ch;
+      if (ch === quote)
+        quote = null;
+    } else if (ch === '"' || ch === "'") {
+      current += ch;
+      quote = ch;
+    } else if (ch === ",") {
+      items.push(current);
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  items.push(current);
+  return items;
+}
+var FM_RE, KEY_RE2;
+var init_frontmatter = __esm({
+  "../core/dist/frontmatter.js"() {
+    "use strict";
+    FM_RE = /^---[ \t]*\r?\n(?:[\s\S]*?\r?\n)?---[ \t]*(?:\r?\n|$)/;
+    KEY_RE2 = /^([A-Za-z0-9_.-]+):(.*)$/;
+  }
+});
+
+// ../core/dist/analyze.js
+function utf8Length(source) {
+  let bytes = 0;
+  for (const ch of source) {
+    const cp = ch.codePointAt(0);
+    bytes += cp <= 127 ? 1 : cp <= 2047 ? 2 : cp <= 65535 ? 3 : 4;
+  }
+  return bytes;
+}
+function analyzeDocument(source, options = {}) {
+  const frontmatter = extractFrontmatter(source);
+  const { document } = parseDocument(stripFrontmatter(source));
+  const outline = [];
+  const blocks = { total: 0, byName: {}, maxDepth: 0, instances: [] };
+  const links = {
+    total: 0,
+    external: 0,
+    internal: 0,
+    domains: [],
+    items: []
+  };
+  const images = { total: 0, missingAlt: 0 };
+  const code = { fences: 0, languages: [], inlineSpans: 0 };
+  const structure = { listItems: 0, tables: 0, blockquotes: 0 };
+  const languages = /* @__PURE__ */ new Set();
+  const domains = /* @__PURE__ */ new Set();
+  let words = 0;
+  function addWords(count) {
+    words += count;
+    const section = outline[outline.length - 1];
+    if (section)
+      section.words += count;
+  }
+  function recordLink(url2, text, line) {
+    const external = EXTERNAL_URL_RE.test(url2);
+    links.total++;
+    if (external) {
+      links.external++;
+      const host = url2.match(/^(?:https?:)?\/\/(?:[^/?#@]*@)?([^/?#:]+)/i);
+      if (host)
+        domains.add(host[1].toLowerCase());
+    } else {
+      links.internal++;
+    }
+    links.items.push({ url: url2, text, line, external });
+  }
+  function inlineToProse(text, line) {
+    return text.replace(CODE_SPAN_RE, () => {
+      code.inlineSpans++;
+      return " ";
+    }).replace(IMAGE_RE, (_, alt) => {
+      images.total++;
+      if (alt.trim() === "")
+        images.missingAlt++;
+      return " ";
+    }).replace(LINK_RE, (_, label, url2) => {
+      recordLink(url2, label, line);
+      return label;
+    }).replace(AUTOLINK_RE, (_, url2) => {
+      recordLink(url2, url2, line);
+      return " ";
+    });
+  }
+  function countWords(text) {
+    return text.split(/\s+/).filter((token) => /[\p{L}\p{N}]/u.test(token)).length;
+  }
+  function scanMarkdown(value, startLine) {
+    let fence = null;
+    let inBlockquote = false;
+    let prevLineHasPipe = false;
+    const lines = value.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const lineNo = startLine + i;
+      const trimmed = line.trim();
+      const fenceMatch = trimmed.match(CODE_FENCE_RE2);
+      if (fence !== null) {
+        if (fenceMatch && fenceMatch[1][0] === fence[0] && fenceMatch[1].length >= fence.length) {
+          fence = null;
+        }
+        continue;
+      }
+      if (fenceMatch) {
+        fence = fenceMatch[1];
+        code.fences++;
+        const lang = fenceMatch[2].trim().split(/\s+/)[0];
+        if (lang)
+          languages.add(lang);
+        inBlockquote = false;
+        prevLineHasPipe = false;
+        continue;
+      }
+      if (trimmed === "") {
+        inBlockquote = false;
+        prevLineHasPipe = false;
+        continue;
+      }
+      const heading = trimmed.match(HEADING_RE);
+      if (heading) {
+        const raw = heading[2].replace(/\s+#+\s*$/, "");
+        const text = inlineToProse(raw, lineNo).replace(/\s+/g, " ").trim();
+        outline.push({ level: heading[1].length, text, line: lineNo, words: 0 });
+        addWords(countWords(text));
+        inBlockquote = false;
+        prevLineHasPipe = false;
+        continue;
+      }
+      let content = trimmed;
+      if (content.startsWith(">")) {
+        if (!inBlockquote) {
+          structure.blockquotes++;
+          inBlockquote = true;
+        }
+        content = content.replace(/^(>\s*)+/, "");
+      } else {
+        inBlockquote = false;
+      }
+      if (LIST_ITEM_RE.test(content)) {
+        structure.listItems++;
+        content = content.replace(LIST_ITEM_RE, "");
+      }
+      if (content.includes("|")) {
+        if (TABLE_SEPARATOR_RE.test(content) && content.includes("-") && prevLineHasPipe) {
+          structure.tables++;
+        }
+        prevLineHasPipe = true;
+        content = inlineToProse(content, lineNo).replaceAll("|", " ");
+      } else {
+        prevLineHasPipe = false;
+        content = inlineToProse(content, lineNo);
+      }
+      addWords(countWords(content));
+    }
+  }
+  function walk(nodes, depth) {
+    for (const node of nodes) {
+      if (node.type === "block") {
+        blocks.total++;
+        blocks.byName[node.name] = (blocks.byName[node.name] ?? 0) + 1;
+        blocks.maxDepth = Math.max(blocks.maxDepth, depth);
+        blocks.instances.push({ name: node.name, line: node.openPosition.start.line, depth });
+        walk(node.children, depth + 1);
+      } else {
+        scanMarkdown(node.value, node.position.start.line);
+      }
+    }
+  }
+  walk(document.children, 1);
+  code.languages = [...languages];
+  links.domains = [...domains].sort();
+  const sourceLines = source === "" ? 0 : source.split("\n").length - (source.endsWith("\n") ? 1 : 0);
+  return {
+    file: {
+      path: options.path ?? null,
+      bytes: utf8Length(source),
+      lines: sourceLines
+    },
+    frontmatter: frontmatter ? {
+      present: true,
+      keys: frontmatter.keys,
+      data: frontmatter.data,
+      lines: frontmatter.lines
+    } : { present: false, keys: [], data: {}, lines: null },
+    length: {
+      words,
+      characters: source.length,
+      readingMinutes: Math.ceil(words / 200),
+      approxTokens: Math.ceil(source.length / 4)
+    },
+    outline,
+    blocks,
+    links,
+    images,
+    code,
+    structure
+  };
+}
+var CODE_FENCE_RE2, HEADING_RE, LIST_ITEM_RE, TABLE_SEPARATOR_RE, CODE_SPAN_RE, IMAGE_RE, LINK_RE, AUTOLINK_RE, EXTERNAL_URL_RE;
+var init_analyze = __esm({
+  "../core/dist/analyze.js"() {
+    "use strict";
+    init_frontmatter();
+    init_parser();
+    CODE_FENCE_RE2 = /^(`{3,}|~{3,})(.*)$/;
+    HEADING_RE = /^(#{1,6})\s+(.*)$/;
+    LIST_ITEM_RE = /^\s*(?:[-*+]|\d+[.)])\s+/;
+    TABLE_SEPARATOR_RE = /^\|?[\s:|-]+$/;
+    CODE_SPAN_RE = /`[^`]+`/g;
+    IMAGE_RE = /!\[([^\]]*)\]\(([^)]*)\)/g;
+    LINK_RE = /\[([^\]]+)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+    AUTOLINK_RE = /<(https?:\/\/[^>\s]+)>/g;
+    EXTERNAL_URL_RE = /^(?:https?:)?\/\//i;
+  }
+});
+
 // ../core/dist/position.js
 function bodyLineRange(node, bodyLineIndex) {
   const bodyLines = node.body.split("\n");
@@ -339,6 +656,45 @@ var init_position = __esm({
 });
 
 // ../core/dist/authoring.js
+function typeLabel(def) {
+  switch (def.type) {
+    case "enum":
+      return `one of ${Object.values(def.entries ?? {}).join("|")}`;
+    case "literal":
+      return `one of ${(def.values ?? []).map(String).join("|")}`;
+    case "union":
+      return `one of ${(def.options ?? []).map((o) => typeLabel(o.def).replace(/^one of /, "")).join("|")}`;
+    default:
+      return def.type;
+  }
+}
+function describeProps(schema) {
+  const root = schema.def;
+  if (root.type !== "object" || !root.shape)
+    return [];
+  const lines = [];
+  for (const [name, field] of Object.entries(root.shape)) {
+    let current = field;
+    let optional2 = false;
+    let defaultValue;
+    let description = current.description;
+    while (["optional", "default", "nullable"].includes(current.def.type)) {
+      optional2 = true;
+      if (current.def.type === "default") {
+        const dv = current.def.defaultValue;
+        defaultValue = typeof dv === "function" ? dv() : dv;
+      }
+      if (!current.def.innerType)
+        break;
+      current = current.def.innerType;
+      description ??= current.description;
+    }
+    const presence = defaultValue !== void 0 ? `(optional, default: ${String(defaultValue)})` : optional2 ? "(optional)" : "(required)";
+    const suffix = description ? ` \u2014 ${description}` : "";
+    lines.push(`- ${name}: ${typeLabel(current.def)} ${presence}${suffix}`);
+  }
+  return lines;
+}
 function generateAuthoringGuide(defs, opts = {}) {
   const includeExamples = opts.includeExamples ?? true;
   const includeAvoid = opts.includeAvoidRules ?? true;
@@ -348,6 +704,11 @@ function generateAuthoringGuide(defs, opts = {}) {
   for (const def of defs) {
     const lines = [`## ${def.name}`, ""];
     lines.push(def.childOnly ? `${def.description} (child block \u2014 only inside a parent that allows it)` : def.description);
+    if (def.props) {
+      const props = describeProps(def.props);
+      if (props.length > 0)
+        lines.push("", "Props:", ...props);
+    }
     lines.push("", `Content: ${def.content.describe()}`);
     if (def.authoring.useWhen.length > 0) {
       lines.push("", "Use when:", ...def.authoring.useWhen.map((u) => `- ${u}`));
@@ -741,6 +1102,8 @@ var init_dist = __esm({
     "use strict";
     init_diagnostics();
     init_parser();
+    init_frontmatter();
+    init_analyze();
     init_registry();
     init_content_models();
     init_validate();
@@ -6654,13 +7017,13 @@ var init_he = __esm({
         // no unit
       };
       const typeEntry = (t) => t ? TypeNames[t] : void 0;
-      const typeLabel = (t) => {
+      const typeLabel2 = (t) => {
         const e = typeEntry(t);
         if (e)
           return e.label;
         return t ?? TypeNames.unknown.label;
       };
-      const withDefinite = (t) => `\u05D4${typeLabel(t)}`;
+      const withDefinite = (t) => `\u05D4${typeLabel2(t)}`;
       const verbFor = (t) => {
         const e = typeEntry(t);
         const gender = e?.gender ?? "m";
@@ -6710,7 +7073,7 @@ var init_he = __esm({
         switch (issue2.code) {
           case "invalid_type": {
             const expectedKey = issue2.expected;
-            const expected = TypeDictionary[expectedKey ?? ""] ?? typeLabel(expectedKey);
+            const expected = TypeDictionary[expectedKey ?? ""] ?? typeLabel2(expectedKey);
             const receivedType = parsedType(issue2.input);
             const received = TypeDictionary[receivedType] ?? TypeNames[receivedType]?.label ?? receivedType;
             if (/^[A-Z]/.test(issue2.expected)) {
@@ -16181,16 +16544,223 @@ var init_load_registry = __esm({
   }
 });
 
+// src/commands/agents.ts
+var agents_exports = {};
+__export(agents_exports, {
+  agentsCommand: () => agentsCommand,
+  installAgentIntegration: () => installAgentIntegration
+});
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+function upsertBlock(existing) {
+  const start = existing.indexOf(START);
+  const end = existing.indexOf(END);
+  if (start !== -1 && end !== -1) {
+    return existing.slice(0, start) + AGENTS_MD_BLOCK + existing.slice(end + END.length);
+  }
+  if (existing.trim() === "") return `${AGENTS_MD_BLOCK}
+`;
+  return `${existing.replace(/\n*$/, "\n\n")}${AGENTS_MD_BLOCK}
+`;
+}
+async function installAgentIntegration(cwd, options, io) {
+  const claude = options.claude ?? existsSync(join(cwd, ".claude"));
+  const agentsMd = options.agentsMd ?? true;
+  if (agentsMd) {
+    const path = join(cwd, "AGENTS.md");
+    let existing = "";
+    try {
+      existing = await readFile(path, "utf8");
+    } catch {
+    }
+    const created = existing === "";
+    await writeFile(path, upsertBlock(existing), "utf8");
+    io.stdout(`${created ? "created" : "updated"}: AGENTS.md (contentbit block)`);
+  }
+  if (claude) {
+    const skills = [
+      ["contentbit-author", AUTHOR_SKILL],
+      ["contentbit-audit", AUDIT_SKILL]
+    ];
+    for (const [name, content] of skills) {
+      const dir = join(cwd, ".claude/skills", name);
+      await mkdir(dir, { recursive: true });
+      await writeFile(join(dir, "SKILL.md"), content, "utf8");
+      io.stdout(`installed: .claude/skills/${name}/SKILL.md`);
+    }
+  }
+}
+async function agentsCommand(args, io) {
+  const { values } = parseArgs({
+    args,
+    options: {
+      claude: { type: "boolean", default: false },
+      "no-agents-md": { type: "boolean", default: false },
+      cwd: { type: "string", default: process.cwd() }
+    }
+  });
+  await installAgentIntegration(
+    values.cwd,
+    {
+      claude: values.claude || void 0,
+      // false means "detect", not "skip"
+      agentsMd: !values["no-agents-md"]
+    },
+    io
+  );
+  return 0;
+}
+var TEMPLATE_VERSION, AUTHOR_SKILL, AUDIT_SKILL, AGENTS_MD_BLOCK, START, END;
+var init_agents = __esm({
+  "src/commands/agents.ts"() {
+    "use strict";
+    TEMPLATE_VERSION = 1;
+    AUTHOR_SKILL = `---
+name: contentbit-author
+description: |
+  Write or edit contentbit Markdown content (directive blocks like :::callout).
+  Use when asked to create or modify content documents in a project that uses
+  contentbit \u2014 blog posts, docs pages, changelogs, any Markdown covered by
+  \`contentbit validate\`.
+version: ${TEMPLATE_VERSION}
+---
+
+# Writing contentbit content
+
+contentbit documents are plain Markdown plus directive blocks
+(\`:::name{props} ... :::\`). Every block has a schema. Never guess block names,
+props, or body shapes \u2014 fetch the live guide from the project's registry first.
+
+## Find the project conventions
+
+Check \`package.json\` for a \`content:check\` script. It holds the canonical
+validate invocation for this project: the content glob and, if present, the
+\`--registry <path>\` flag pointing at custom block definitions. Reuse both
+below. No script? Default to \`content/**/*.md\` with no \`--registry\` flag.
+
+## The loop
+
+1. **Fetch the authoring guide** (always \u2014 it covers this project's custom blocks):
+
+   \`\`\`sh
+   contentbit instructions --audience llm [--registry <path from content:check>]
+   \`\`\`
+
+   Read it before writing. It documents every available block: props, body
+   shape, and when to use or avoid it.
+
+2. **Write the document.** Plain Markdown everywhere; blocks only where the
+   guide's use-when guidance fits. Keep frontmatter consistent with sibling
+   documents in the same folder.
+
+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. Fix every diagnostic and re-run. Never finish with a failing
+   validate.
+
+## Failure modes
+
+- \`contentbit\` not found or no registry resolvable: the project is not set up.
+  Say so and suggest \`npx contentbit@latest init\` \u2014 do not invent block syntax.
+- A block you want does not exist: use plain Markdown, or ask whether to define
+  a custom block in the registry. Never emit an unregistered block name.
+`;
+    AUDIT_SKILL = `---
+name: contentbit-audit
+description: |
+  Audit contentbit Markdown content health using document stats. Use when asked
+  to audit, review, or find improvements across content \u2014 thin pages, missing
+  structure, validation issues \u2014 in a project that uses contentbit.
+version: ${TEMPLATE_VERSION}
+---
+
+# Auditing contentbit content
+
+\`contentbit stats\` analyzes documents and prints JSON to stdout. It is a read
+tool: it always exits 0, even when documents have validation errors.
+
+## 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>]
+\`\`\`
+
+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\`).
+
+## 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
+   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.
+
+## Report
+
+Report findings per file with concrete suggestions, ordered by priority. Do not
+edit files during the audit. To fix a finding, follow the contentbit-author
+skill (fetch the guide, edit, validate until clean) \u2014 offer that as a follow-up.
+`;
+    AGENTS_MD_BLOCK = `<!-- contentbit:start -->
+
+## contentbit content (generated \u2014 edits inside this block are overwritten)
+
+This project validates Markdown content with contentbit. Documents are plain
+Markdown plus directive blocks (\`:::name{props} ... :::\`), each with a schema.
+The \`content:check\` script in package.json holds the canonical validate
+command \u2014 the content glob and the \`--registry\` flag \u2014 reuse its arguments.
+
+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>]\`.
+   Diagnostics print as \`file:line:col severity CODE message\` with fix hints.
+
+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.
+
+If \`contentbit\` is unavailable, suggest \`npx contentbit@latest init\` instead
+of inventing block syntax.
+
+<!-- contentbit:end -->`;
+    START = "<!-- contentbit:start -->";
+    END = "<!-- contentbit:end -->";
+  }
+});
+
 // src/commands/init.ts
 var init_exports = {};
 __export(init_exports, {
   initCommand: () => initCommand
 });
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import { parseArgs } from "node:util";
+import { existsSync as existsSync2 } from "node:fs";
+import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
+import { join as join2 } from "node:path";
+import { parseArgs as parseArgs2 } from "node:util";
 function blockComponentsTemplate(styled) {
   const body = styled ? `  return (
     <figure className="my-6 border-s-2 ps-4">
@@ -16282,7 +16852,7 @@ console.log('wrote example.html')
 `;
 }
 function detectFramework(cwd, deps) {
-  if ((deps["@tanstack/react-start"] || deps["@tanstack/react-router"]) && existsSync(join(cwd, "src/routes"))) {
+  if ((deps["@tanstack/react-start"] || deps["@tanstack/react-router"]) && existsSync2(join2(cwd, "src/routes"))) {
     return {
       framework: "tanstack",
       componentPath: "src/components/content-blocks.tsx",
@@ -16290,8 +16860,8 @@ function detectFramework(cwd, deps) {
     };
   }
   if (deps.next) {
-    const appDir = existsSync(join(cwd, "src/app")) ? "src/app" : "app";
-    if (existsSync(join(cwd, appDir))) {
+    const appDir = existsSync2(join2(cwd, "src/app")) ? "src/app" : "app";
+    if (existsSync2(join2(cwd, appDir))) {
       return {
         framework: "next",
         componentPath: "components/content-blocks.tsx",
@@ -16301,6 +16871,34 @@ function detectFramework(cwd, deps) {
   }
   return { framework: null, componentPath: "components/content-blocks.tsx", pagePath: null };
 }
+function astroPage(styled) {
+  const importLine = styled ? "import ContentRenderer from '../components/content-blocks/content-renderer.astro'" : "import { ContentBlocks } from '@contentbit/astro/components'";
+  const renderer = styled ? "ContentRenderer" : "ContentBlocks";
+  return `---
+import { genericBlocks } from '@contentbit/blocks'
+import { createBlockRegistry, parseDocument, validateDocument } from '@contentbit/core'
+import { getEntry } from 'astro:content'
+
+${importLine}
+
+// Definitions in blocks/registry.ts are shared with the validate CLI.
+import customBlocks from '../../blocks/registry'
+import QuoteBlock from '../../blocks/QuoteBlock.astro'
+
+// Entry ids are the file path relative to the collection base, minus ".md".
+const entry = await getEntry('articles', 'example')
+if (!entry?.body) throw new Error('Entry "example" not found in the articles collection.')
+
+const registry = createBlockRegistry().use(genericBlocks()).use(customBlocks)
+// Static pages render at build time, so invalid blocks fail the build here.
+const result = validateDocument(parseDocument(entry.body), registry)
+---
+
+<main style="max-width: 42rem; margin: 0 auto; padding: 3rem 1.5rem;">
+  <${renderer} document={result.document} components={{ quote: QuoteBlock }} />
+</main>
+`;
+}
 function detectPackageManager(cwd) {
   const locks = [
     ["pnpm-lock.yaml", "pnpm"],
@@ -16310,7 +16908,7 @@ function detectPackageManager(cwd) {
     ["package-lock.json", "npm"]
   ];
   for (const [file2, pm] of locks) {
-    if (existsSync(join(cwd, file2))) return pm;
+    if (existsSync2(join2(cwd, file2))) return pm;
   }
   const agent = process.env.npm_config_user_agent ?? "";
   for (const pm of ["pnpm", "yarn", "bun"]) {
@@ -16335,18 +16933,38 @@ function runInstall(pm, args, cwd) {
     child.on("error", () => resolve(1));
   });
 }
+async function installStyledPack(cwd, pack, noInstall, io) {
+  const componentsJsonPath = join2(cwd, "components.json");
+  const componentsJson = JSON.parse(await readFile2(componentsJsonPath, "utf8"));
+  componentsJson.registries ??= {};
+  if (!componentsJson.registries["@contentbit"]) {
+    componentsJson.registries["@contentbit"] = "https://contentbit.dev/r/{name}.json";
+    await writeFile2(componentsJsonPath, `${JSON.stringify(componentsJson, null, 2)}
+`, "utf8");
+    io.stdout("added @contentbit registry to components.json");
+  }
+  if (noInstall) {
+    io.stdout(`skipped: shadcn add ${pack}`);
+    return true;
+  }
+  const [bin, prefix] = dlxCommand(detectPackageManager(cwd));
+  io.stdout(`installing the styled pack: shadcn add ${pack}`);
+  const code = await runInstall(bin, [...prefix, "shadcn@latest", "add", pack, "--yes"], cwd);
+  if (code !== 0) io.stderr("styled pack install failed; falling back to headless defaults");
+  return code === 0;
+}
 async function scaffold(path, content) {
   try {
-    await readFile(path, "utf8");
+    await readFile2(path, "utf8");
     return "skipped";
   } catch {
-    await mkdir(join(path, ".."), { recursive: true });
-    await writeFile(path, content, "utf8");
+    await mkdir2(join2(path, ".."), { recursive: true });
+    await writeFile2(path, content, "utf8");
     return "created";
   }
 }
 async function initCommand(args, io) {
-  const { values } = parseArgs({
+  const { values } = parseArgs2({
     args,
     options: {
       target: { type: "string", short: "t" },
@@ -16355,20 +16973,22 @@ async function initCommand(args, io) {
       cwd: { type: "string", default: process.cwd() },
       "no-install": { type: "boolean", default: false },
       "no-page": { type: "boolean", default: false },
-      "no-styled": { type: "boolean", default: false }
+      "no-styled": { type: "boolean", default: false },
+      "no-agents": { type: "boolean", default: false }
     }
   });
   const cwd = values.cwd;
   let pkg;
-  const pkgPath = join(cwd, "package.json");
+  const pkgPath = join2(cwd, "package.json");
   try {
-    pkg = JSON.parse(await readFile(pkgPath, "utf8"));
+    pkg = JSON.parse(await readFile2(pkgPath, "utf8"));
   } catch {
     io.stderr("No package.json found. Run this inside a project (npm init first).");
     return 1;
   }
   const hasReact = Boolean(pkg.dependencies?.react ?? pkg.devDependencies?.react);
-  const detected = hasReact ? "react" : "html";
+  const hasAstro = Boolean(pkg.dependencies?.astro ?? pkg.devDependencies?.astro);
+  const detected = hasAstro ? "astro" : hasReact ? "react" : "html";
   let target;
   if (values.target) {
     if (!TARGETS.includes(values.target)) {
@@ -16383,6 +17003,7 @@ async function initCommand(args, io) {
       initialValue: detected,
       options: [
         { value: "react", label: "React", hint: "ContentBlocks component" },
+        { value: "astro", label: "Astro", hint: "content collections + .astro components" },
         { value: "html", label: "Static HTML", hint: "renderToHtml, no framework" },
         { value: "markdown", label: "Plain Markdown", hint: "fallback rendering only" }
       ]
@@ -16419,6 +17040,7 @@ async function initCommand(args, io) {
   const runtime = ["@contentbit/core", "@contentbit/blocks", "zod"];
   if (target === "react") runtime.push("@contentbit/react");
   if (target === "html") runtime.push("@contentbit/html");
+  if (target === "astro") runtime.push("@contentbit/astro");
   if (md !== "none") runtime.push(md);
   if (values["no-install"]) {
     io.stdout(`skipped install: ${runtime.join(" ")} + contentbit (dev)`);
@@ -16440,30 +17062,9 @@ async function initCommand(args, io) {
   ];
   const layout = detectFramework(cwd, { ...pkg.dependencies, ...pkg.devDependencies });
   let styled = false;
-  const componentsJsonPath = join(cwd, "components.json");
-  if (target === "react" && !values["no-styled"] && existsSync(componentsJsonPath)) {
-    const componentsJson = JSON.parse(await readFile(componentsJsonPath, "utf8"));
-    componentsJson.registries ??= {};
-    if (!componentsJson.registries["@contentbit"]) {
-      componentsJson.registries["@contentbit"] = "https://contentbit.dev/r/{name}.json";
-      await writeFile(componentsJsonPath, `${JSON.stringify(componentsJson, null, 2)}
-`, "utf8");
-      io.stdout("added @contentbit registry to components.json");
-    }
-    if (values["no-install"]) {
-      io.stdout("skipped: shadcn add @contentbit/generic-pack");
-      styled = true;
-    } else {
-      const [bin, prefix] = dlxCommand(detectPackageManager(cwd));
-      io.stdout("installing the styled pack: shadcn add @contentbit/generic-pack");
-      const code = await runInstall(
-        bin,
-        [...prefix, "shadcn@latest", "add", "@contentbit/generic-pack", "--yes"],
-        cwd
-      );
-      if (code === 0) styled = true;
-      else io.stderr("styled pack install failed; falling back to headless defaults");
-    }
+  const componentsJsonPath = join2(cwd, "components.json");
+  if (target === "react" && !values["no-styled"] && existsSync2(componentsJsonPath)) {
+    styled = await installStyledPack(cwd, "@contentbit/generic-pack", values["no-install"], io);
   }
   if (target === "react") {
     const depth = layout.componentPath.split("/").length - 1;
@@ -16483,27 +17084,52 @@ async function initCommand(args, io) {
       htmlRenderScript(md)
     ]);
   }
+  if (target === "astro") {
+    let astroStyled = false;
+    if (!values["no-styled"] && existsSync2(componentsJsonPath)) {
+      astroStyled = await installStyledPack(cwd, "@contentbit/astro-pack", values["no-install"], io);
+    }
+    files.push(["blocks/QuoteBlock.astro", ASTRO_QUOTE_BLOCK]);
+    const configCandidates = ["ts", "mts", "mjs", "js"].flatMap((ext) => [
+      `src/content.config.${ext}`,
+      `src/content/config.${ext}`
+    ]);
+    const existingConfig = configCandidates.find((p) => existsSync2(join2(cwd, p)));
+    if (existingConfig) {
+      io.stdout(`content config exists (${existingConfig}); add this collection manually:`);
+      io.stdout(ASTRO_CONTENT_CONFIG);
+      io.stdout('the example page expects the "articles" collection above');
+    } else {
+      files.push(["src/content.config.ts", ASTRO_CONTENT_CONFIG]);
+    }
+    if (!values["no-page"]) files.push(["src/pages/example.astro", astroPage(astroStyled)]);
+  }
   for (const [rel, content] of files) {
-    const result = await scaffold(join(cwd, rel), content);
+    const result = await scaffold(join2(cwd, rel), content);
     io.stdout(`${result}: ${rel}`);
   }
-  const fresh = JSON.parse(await readFile(pkgPath, "utf8"));
+  const fresh = JSON.parse(await readFile2(pkgPath, "utf8"));
   fresh.scripts ??= {};
   if (!fresh.scripts["content:check"]) {
     fresh.scripts["content:check"] = 'contentbit validate "content/**/*.md" --registry ./blocks/registry.ts';
-    await writeFile(pkgPath, `${JSON.stringify(fresh, null, 2)}
+    await writeFile2(pkgPath, `${JSON.stringify(fresh, null, 2)}
 `, "utf8");
     io.stdout("added script: content:check");
   }
   let registry2;
   try {
-    registry2 = await loadRegistry(join(cwd, "blocks/registry.ts"));
+    registry2 = await loadRegistry(join2(cwd, "blocks/registry.ts"));
   } catch {
     registry2 = await loadRegistry();
   }
   const guide = registry2.toAuthoringGuide({ audience: "llm", includeExamples: true });
-  await writeFile(join(cwd, "contentbit-guide.md"), guide, "utf8");
+  await writeFile2(join2(cwd, "contentbit-guide.md"), guide, "utf8");
   io.stdout("created: contentbit-guide.md (LLM authoring instructions)");
+  if (!values["no-agents"]) {
+    await installAgentIntegration(cwd, {}, io);
+    io.stdout("Agent integration installed \u2014 try asking your agent:");
+    io.stdout('  "write a blog post about X" or "audit my content"');
+  }
   io.stdout("");
   io.stdout("Done. Next steps:");
   io.stdout(`  1. Validate the starter content: ${detectPackageManager(cwd)} run content:check`);
@@ -16515,6 +17141,9 @@ async function initCommand(args, io) {
       io.stdout("     <Content source={...content/example.md as a string} />");
     }
     io.stdout("  3. Styled components: pnpm dlx shadcn@latest add @contentbit/generic-pack");
+  } else if (target === "astro") {
+    io.stdout("  2. Start the dev server and open /example to see the article rendered.");
+    io.stdout("  3. Styled components: pnpm dlx shadcn@latest add @contentbit/astro-pack");
   } else if (target === "html") {
     io.stdout("  2. Render it: node scripts/render-example.mjs && open example.html");
   } else {
@@ -16523,16 +17152,19 @@ async function initCommand(args, io) {
   io.stdout("  Docs: https://contentbit.dev/docs");
   return 0;
 }
-var TARGETS, MD_CHOICES, REGISTRY_TEMPLATE, EXAMPLE_CONTENT, TANSTACK_PAGE, NEXT_PAGE;
+var TARGETS, MD_CHOICES, REGISTRY_TEMPLATE, EXAMPLE_CONTENT, TANSTACK_PAGE, NEXT_PAGE, ASTRO_CONTENT_CONFIG, ASTRO_QUOTE_BLOCK;
 var init_init = __esm({
   "src/commands/init.ts"() {
     "use strict";
     init_load_registry();
-    TARGETS = ["react", "html", "markdown"];
+    init_agents();
+    TARGETS = ["react", "html", "markdown", "astro"];
     MD_CHOICES = {
       react: ["react-markdown", "none"],
       html: ["marked", "markdown-it", "none"],
-      markdown: ["none"]
+      markdown: ["none"],
+      // @contentbit/astro ships its own marked-based default; nothing to install.
+      astro: ["none"]
     };
     REGISTRY_TEMPLATE = `// Custom block definitions for this project. The CLI and your app share
 // this module \u2014 Node 22.18+ imports TypeScript directly:
@@ -16613,6 +17245,36 @@ export default async function ExamplePage() {
     </main>
   )
 }
+`;
+    ASTRO_CONTENT_CONFIG = `import { defineCollection } from 'astro:content'
+import { glob } from 'astro/loaders'
+
+export const collections = {
+  articles: defineCollection({
+    // Astro's builtin Markdown loader. Entry bodies are parsed and validated
+    // where they render (see src/pages/example.astro); \`contentbit validate\`
+    // covers the same files in CI.
+    loader: glob({ pattern: '**/*.md', base: './content' }),
+  }),
+}
+`;
+    ASTRO_QUOTE_BLOCK = `---
+// The Astro component for the custom \`quote\` block defined in blocks/registry.ts.
+// Block props arrive as component props; nested content arrives via <slot />.
+interface Props {
+  author: string
+  role?: string
+}
+
+const { author, role } = Astro.props
+---
+
+<figure style="margin: 1.5rem 0; border-left: 2px solid #d4d4d4; padding-left: 1rem;">
+  <blockquote style="font-style: italic;"><slot /></blockquote>
+  <figcaption style="margin-top: 0.5rem; font-size: 0.875rem; opacity: 0.7;">
+    \u2014 {author}{role ? \`, \${role}\` : null}
+  </figcaption>
+</figure>
 `;
   }
 });
@@ -16622,11 +17284,11 @@ var validate_exports = {};
 __export(validate_exports, {
   validateCommand: () => validateCommand
 });
-import { readFile as readFile2 } from "node:fs/promises";
-import { parseArgs as parseArgs2 } from "node:util";
+import { readFile as readFile3 } from "node:fs/promises";
+import { parseArgs as parseArgs3 } from "node:util";
 import { glob } from "tinyglobby";
 async function validateCommand(args, io) {
-  const { values, positionals } = parseArgs2({
+  const { values, positionals } = parseArgs3({
     args,
     allowPositionals: true,
     options: {
@@ -16647,8 +17309,8 @@ async function validateCommand(args, io) {
   let errors = 0;
   let warnings = 0;
   for (const file2 of files.sort()) {
-    const source = await readFile2(file2, "utf8");
-    const result = validateDocument(parseDocument(source), registry2);
+    const source = await readFile3(file2, "utf8");
+    const result = validateDocument(parseDocument(stripFrontmatter(source)), registry2);
     for (const d of result.diagnostics) {
       io.stderr(formatDiagnostic(d, file2));
       if (d.severity === "error") errors++;
@@ -16668,6 +17330,63 @@ var init_validate2 = __esm({
   }
 });
 
+// src/commands/stats.ts
+var stats_exports = {};
+__export(stats_exports, {
+  statsCommand: () => statsCommand
+});
+import { readFile as readFile4 } from "node:fs/promises";
+import { parseArgs as parseArgs4 } from "node:util";
+import { glob as glob2 } from "tinyglobby";
+async function fileStats(file2, registry2) {
+  const source = await readFile4(file2, "utf8");
+  const stats = analyzeDocument(source, { path: file2 });
+  if (registry2) {
+    const result = validateDocument(parseDocument(stripFrontmatter(source)), registry2);
+    let errors = 0;
+    let warnings = 0;
+    for (const d of result.diagnostics) {
+      if (d.severity === "error") errors++;
+      else if (d.severity === "warning") warnings++;
+    }
+    stats.validation = { errors, warnings };
+  }
+  return stats;
+}
+async function statsCommand(args, io) {
+  const { values, positionals } = parseArgs4({
+    args,
+    allowPositionals: true,
+    options: {
+      registry: { type: "string" },
+      "no-validate": { type: "boolean", default: false }
+    }
+  });
+  if (positionals.length === 0) {
+    io.stderr("stats: provide at least one file or glob.");
+    return 2;
+  }
+  const files = await glob2(positionals, { absolute: true });
+  if (files.length === 0) {
+    io.stderr(`stats: no files matched ${positionals.join(" ")}`);
+    return 2;
+  }
+  const registry2 = values["no-validate"] ? null : await loadRegistry(values.registry);
+  const all = [];
+  for (const file2 of files.sort()) {
+    all.push(await fileStats(file2, registry2));
+  }
+  io.stdout(JSON.stringify(all.length === 1 ? all[0] : all, null, 2));
+  return 0;
+}
+var init_stats = __esm({
+  "src/commands/stats.ts"() {
+    "use strict";
+    init_dist();
+    init_load_registry();
+  }
+});
+
 // ../html/dist/escape.js
 function escapeHtml(value) {
   return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
@@ -16748,12 +17467,18 @@ var init_blocks = __esm({
 });
 
 // ../html/dist/render.js
-function defaultMarkdown(md) {
+function fallbackMarkdown(md) {
   return md.trim().split(/\n{2,}/).map((p) => `<p>${escapeHtml(p)}</p>`).join("\n");
 }
+function invalidBlockHtml(node, prefix) {
+  return `<div class="${prefix}invalid" data-cb-invalid="${escapeHtml(node.name)}"><pre>${escapeHtml(node.body)}</pre></div>`;
+}
+function unrenderableBlockError(name) {
+  return new Error(`Cannot render block "${name}": not validated or no renderer registered.`);
+}
 function renderToHtml(document, opts = {}) {
   const prefix = opts.classPrefix ?? "cb-";
-  const renderMarkdown = opts.renderMarkdown ?? defaultMarkdown;
+  const renderMarkdown = opts.renderMarkdown ?? fallbackMarkdown;
   const renderers = { ...genericHtmlRenderers, ...opts.renderers };
   const onInvalid = opts.onInvalid ?? "fallback";
   const ctx = {
@@ -16767,13 +17492,11 @@ function renderToHtml(document, opts = {}) {
         const renderer = renderers[node.name];
         if (renderer && isValidatedBlock(node))
           return renderer(node, ctx);
-        if (onInvalid === "strict") {
-          throw new Error(`Cannot render block "${node.name}": not validated or no renderer registered.`);
-        }
-        if (onInvalid === "annotated") {
-          return `<div class="${prefix}invalid" data-cb-invalid="${escapeHtml(node.name)}"><pre>${escapeHtml(node.body)}</pre></div>`;
-        }
-        return defaultMarkdown(node.body);
+        if (onInvalid === "strict")
+          throw unrenderableBlockError(node.name);
+        if (onInvalid === "annotated")
+          return invalidBlockHtml(node, prefix);
+        return fallbackMarkdown(node.body);
       }).join("\n");
     }
   };
@@ -16801,10 +17524,10 @@ var render_exports = {};
 __export(render_exports, {
   renderCommand: () => renderCommand
 });
-import { readFile as readFile3 } from "node:fs/promises";
-import { parseArgs as parseArgs3 } from "node:util";
+import { readFile as readFile5 } from "node:fs/promises";
+import { parseArgs as parseArgs5 } from "node:util";
 async function renderCommand(args, io) {
-  const { values, positionals } = parseArgs3({
+  const { values, positionals } = parseArgs5({
     args,
     allowPositionals: true,
     options: {
@@ -16819,7 +17542,7 @@ async function renderCommand(args, io) {
     return 2;
   }
   const registry2 = await loadRegistry(values.registry);
-  const source = await readFile3(file2, "utf8");
+  const source = await readFile5(file2, "utf8");
   const result = validateDocument(parseDocument(source), registry2);
   if (!result.ok) {
     for (const d of result.diagnostics) io.stderr(formatDiagnostic(d, file2));
@@ -16845,9 +17568,9 @@ var instructions_exports = {};
 __export(instructions_exports, {
   instructionsCommand: () => instructionsCommand
 });
-import { parseArgs as parseArgs4 } from "node:util";
+import { parseArgs as parseArgs6 } from "node:util";
 async function instructionsCommand(args, io) {
-  const { values } = parseArgs4({
+  const { values } = parseArgs6({
     args,
     options: {
       audience: { type: "string", default: "llm" },
@@ -16877,9 +17600,9 @@ var docs_exports = {};
 __export(docs_exports, {
   docsCommand: () => docsCommand
 });
-import { parseArgs as parseArgs5 } from "node:util";
+import { parseArgs as parseArgs7 } from "node:util";
 async function docsCommand(args, io) {
-  const { values } = parseArgs5({
+  const { values } = parseArgs7({
     args,
     options: {
       registry: { type: "string" },
@@ -16900,20 +17623,24 @@ var init_docs = __esm({
 });
 
 // src/run.ts
-var USAGE = `Usage: contentbit <init|validate|render|instructions|docs> [options]
+var USAGE = `Usage: contentbit <init|validate|stats|render|instructions|docs|agents> [options]
 
-  init [-t react|html|markdown] [--md ...] [-y] [--no-install] [--no-page]
+  init [-t react|html|markdown|astro] [--md ...] [-y] [--no-install] [--no-page] [--no-agents]
+  agents [--claude] [--no-agents-md]
 
   validate <globs...> [--registry <module.mjs>] [--strict-warnings]
+  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>]`;
 var commands = {
   init: async () => (await Promise.resolve().then(() => (init_init(), init_exports))).initCommand,
   validate: async () => (await Promise.resolve().then(() => (init_validate2(), validate_exports))).validateCommand,
+  stats: async () => (await Promise.resolve().then(() => (init_stats(), stats_exports))).statsCommand,
   render: async () => (await Promise.resolve().then(() => (init_render2(), render_exports))).renderCommand,
   instructions: async () => (await Promise.resolve().then(() => (init_instructions(), instructions_exports))).instructionsCommand,
-  docs: async () => (await Promise.resolve().then(() => (init_docs(), docs_exports))).docsCommand
+  docs: async () => (await Promise.resolve().then(() => (init_docs(), docs_exports))).docsCommand,
+  agents: async () => (await Promise.resolve().then(() => (init_agents(), agents_exports))).agentsCommand
 };
 async function run(argv, io) {
   const [name, ...rest] = argv;