@bendyline/docblocks-cli 2.6.2 → 2.7.1

package/dist/bin.js

@@ -166,7 +166,7 @@ var init_cancellation = __esm({
 });
 
 // src/mcp/artifact-store.ts
-import { createHash, randomUUID as randomUUID2 } from "crypto";
+import { createHash, randomUUID as randomUUID3 } from "crypto";
 import { mkdtemp as mkdtemp2, open as open3, rm as rm2 } from "fs/promises";
 import { join as join2 } from "path";
 import { tmpdir } from "os";
@@ -216,9 +216,9 @@ function immutableArtifactRef(ref) {
   );
   return Object.freeze({ ...ref, appliedOptions, engineVersions });
 }
-async function writeFileCancellable(path9, bytes, signal) {
+async function writeFileCancellable(path10, bytes, signal) {
   throwIfAborted4(signal);
-  const handle = await open3(path9, "wx");
+  const handle = await open3(path10, "wx");
   try {
     let offset = 0;
     while (offset < bytes.byteLength) {
@@ -233,9 +233,9 @@ async function writeFileCancellable(path9, bytes, signal) {
     await handle.close();
   }
 }
-async function readFileCancellable(path9, options) {
+async function readFileCancellable(path10, options) {
   throwIfAborted4(options.signal);
-  const handle = await open3(path9, "r");
+  const handle = await open3(path10, "r");
   try {
     const stats = await handle.stat();
     throwIfAborted4(options.signal);
@@ -275,7 +275,7 @@ async function hashBytesCancellable(bytes, signal) {
   return hash.digest("hex");
 }
 async function removeFilesBestEffort(paths) {
-  await Promise.allSettled(paths.map((path9) => rm2(path9, { force: true })));
+  await Promise.allSettled(paths.map((path10) => rm2(path10, { force: true })));
 }
 async function waitForIoDrain(leases, timeoutMs) {
   if (leases.length === 0) return;
@@ -388,8 +388,8 @@ var init_artifact_store = __esm({
           throw new Error("MCP artifact exceeds the configured per-artifact limit");
         }
         const sha2562 = await hashBytesCancellable(bytes, signal);
-        const id = randomUUID2();
-        const path9 = join2(await this.directory, `${id}.artifact`);
+        const id = randomUUID3();
+        const path10 = join2(await this.directory, `${id}.artifact`);
         throwIfAborted4(signal);
         const created = /* @__PURE__ */ new Date();
         const ref = immutableArtifactRef({
@@ -424,7 +424,7 @@ var init_artifact_store = __esm({
         });
         await removeFilesBestEffort(acquisition.expiredPaths);
         try {
-          await this.dependencies.writeFile(path9, bytes, acquisition.io.controller.signal);
+          await this.dependencies.writeFile(path10, bytes, acquisition.io.controller.signal);
           throwIfAborted4(acquisition.io.controller.signal);
           await this.lock(() => {
             this.assertActive();
@@ -432,7 +432,7 @@ var init_artifact_store = __esm({
             this.releaseReservationLocked(reservation);
             this.records.set(id, {
               ref,
-              path: path9,
+              path: path10,
               conversionReport: null,
               reportBytes: 0,
               activeReaders: 0,
@@ -443,7 +443,7 @@ var init_artifact_store = __esm({
           return ref;
         } catch (caught) {
           await this.lock(() => this.releaseReservationLocked(reservation));
-          await rm2(path9, { force: true }).catch(() => void 0);
+          await rm2(path10, { force: true }).catch(() => void 0);
           throw caught;
         } finally {
           this.completeIoLease(acquisition.io);
@@ -556,8 +556,8 @@ var init_artifact_store = __esm({
         for (const [id, stored] of this.records) {
           const expiresAt = stored.ref.expiresAt ? Date.parse(stored.ref.expiresAt) : Number.POSITIVE_INFINITY;
           if (expiresAt > now) continue;
-          const path9 = this.removeRecordLocked(id, stored);
-          if (path9) paths.push(path9);
+          const path10 = this.removeRecordLocked(id, stored);
+          if (path10) paths.push(path10);
         }
         return paths;
       }
@@ -697,8 +697,8 @@ var init_artifact_store = __esm({
 
 // src/mcp/authority.ts
 import { lstat as lstat3, link as link2, open as open4, realpath as realpath4, rename as rename2, stat as stat5, unlink } from "fs/promises";
-import path7 from "path";
-import { createHash as createHash2, randomUUID as randomUUID3 } from "crypto";
+import path8 from "path";
+import { createHash as createHash2, randomUUID as randomUUID4 } from "crypto";
 import { MCP_WIRE_LIMITS as MCP_WIRE_LIMITS2 } from "@bendyline/docblocks/mcp";
 async function resolveRoots(values) {
   const roots = [];
@@ -718,7 +718,7 @@ function rootIdFor(physicalPath) {
   return `root-${createHash2("sha256").update(normalized).digest("hex").slice(0, 16)}`;
 }
 function rootLabel(physicalPath) {
-  const candidate = path7.basename(physicalPath) || "root";
+  const candidate = path8.basename(physicalPath) || "root";
   let label = "";
   for (const character of candidate) {
     const codePoint = character.codePointAt(0) ?? 0;
@@ -729,7 +729,7 @@ function rootLabel(physicalPath) {
   return label || "root";
 }
 function parseRootRelativePath(value) {
-  if (!value || value.length > MAX_PATH_CHARACTERS || value.includes("\0") || value.includes("\\") || path7.posix.isAbsolute(value) || /^[a-zA-Z]:/u.test(value)) {
+  if (!value || value.length > MAX_PATH_CHARACTERS || value.includes("\0") || value.includes("\\") || path8.posix.isAbsolute(value) || /^[a-zA-Z]:/u.test(value)) {
     throw new Error("Invalid MCP root-relative path");
   }
   const segments = value.split("/");
@@ -747,7 +747,7 @@ async function nearestExistingPath(candidate) {
       await lstat3(current);
       return current;
     } catch {
-      const parent = path7.dirname(current);
+      const parent = path8.dirname(current);
       if (parent === current) throw new Error("MCP output has no accessible parent directory");
       current = parent;
     }
@@ -757,7 +757,7 @@ function validatePath(value) {
   if (!value || value.length > MAX_PATH_CHARACTERS || value.includes("\0")) {
     throw new Error("Invalid MCP filesystem path");
   }
-  return path7.resolve(value);
+  return path8.resolve(value);
 }
 function validatePortableFilename(value) {
   const stem = value.split(".", 1)[0]?.toLowerCase() ?? "";
@@ -774,7 +774,7 @@ function hasUnsafeFilenameCharacter(value) {
 }
 function samePath(left, right) {
   const normalize = (value) => {
-    const resolved = path7.resolve(value);
+    const resolved = path8.resolve(value);
     return process.platform === "win32" ? resolved.toLowerCase() : resolved;
   };
   return normalize(left) === normalize(right);
@@ -836,7 +836,7 @@ async function hashFileBounded(filePath, maximumBytes, signal, afterChunk) {
   }
 }
 async function readMaterializationParentIdentity(target, writeRoots) {
-  const parent = path7.dirname(target);
+  const parent = path8.dirname(target);
   let lexical;
   let physical;
   let info;
@@ -980,7 +980,7 @@ var init_authority = __esm({
             "Call list_roots and copy a returned read-enabled root id. If no roots are listed, use an inline markdown or bundle source, or restart the server with --allow-read."
           );
         }
-        const candidate = path7.join(root.physical, ...parseRootRelativePath(workspacePath));
+        const candidate = path8.join(root.physical, ...parseRootRelativePath(workspacePath));
         const physical = await realpath4(candidate).catch(() => null);
         if (!physical || !isPathInside(root.physical, physical)) {
           throw new Error("MCP read path is outside the selected root");
@@ -996,9 +996,9 @@ var init_authority = __esm({
             "Call list_roots and copy a returned write-enabled root id. If none is writable, keep the result as a session artifact or restart the server with --allow-write."
           );
         }
-        const candidate = path7.join(root.physical, ...parseRootRelativePath(workspacePath));
+        const candidate = path8.join(root.physical, ...parseRootRelativePath(workspacePath));
         const authorized = await this.authorizeWrite(candidate);
-        const physicalParent = await realpath4(path7.dirname(authorized));
+        const physicalParent = await realpath4(path8.dirname(authorized));
         if (!isPathInside(root.physical, physicalParent)) {
           throw new Error("MCP write path is outside the selected root");
         }
@@ -1017,7 +1017,7 @@ var init_authority = __esm({
       }
       async authorizeWrite(requestedPath) {
         const candidate = validatePath(requestedPath);
-        const filename = path7.basename(candidate);
+        const filename = path8.basename(candidate);
         validatePortableFilename(filename);
         const existing = await lstat3(candidate).catch(() => null);
         if (existing?.isSymbolicLink()) {
@@ -1026,16 +1026,16 @@ var init_authority = __esm({
         if (existing && !existing.isFile()) {
           throw new Error("MCP output target must be a regular file");
         }
-        const nearest = await nearestExistingPath(existing ? candidate : path7.dirname(candidate));
+        const nearest = await nearestExistingPath(existing ? candidate : path8.dirname(candidate));
         const physicalTarget = existing ? await realpath4(candidate) : null;
-        const physicalParent = physicalTarget ? path7.dirname(physicalTarget) : await realpath4(nearest);
+        const physicalParent = physicalTarget ? path8.dirname(physicalTarget) : await realpath4(nearest);
         if (!this.writeRoots.some((root) => isPathInside(root.physical, physicalParent))) {
           throw new Error("MCP write path is outside the configured roots");
         }
-        if (!existing && !samePath(nearest, path7.dirname(candidate))) {
+        if (!existing && !samePath(nearest, path8.dirname(candidate))) {
           throw new Error("MCP output parent directory does not exist");
         }
-        return physicalTarget ?? path7.join(physicalParent, filename);
+        return physicalTarget ?? path8.join(physicalParent, filename);
       }
       /** Publish bounded bytes through an operation-owned sibling file. */
       async materializeBytes(requestedPath, content, maximumBytes, options = {}) {
@@ -1079,9 +1079,9 @@ var init_authority = __esm({
             );
             if (actual !== expectedSha256) throw new Error("MCP output hash precondition failed");
           }
-          const temporary = path7.join(
-            path7.dirname(target),
-            `.${path7.basename(target)}.${process.pid}.${randomUUID3()}.tmp`
+          const temporary = path8.join(
+            path8.dirname(target),
+            `.${path8.basename(target)}.${process.pid}.${randomUUID4()}.tmp`
           );
           let handle = null;
           try {
@@ -1181,7 +1181,7 @@ import { createHash as createHash3 } from "crypto";
 import { createRequire } from "module";
 import { readFileSync } from "fs";
 import { readdir, readFile as readFile2, stat as stat6 } from "fs/promises";
-import path8 from "path";
+import path9 from "path";
 function getPackageVersion() {
   const pkg = readPackageJson();
   if (typeof pkg?.version === "string" && pkg.version.length > 0) {
@@ -1217,10 +1217,10 @@ async function computeRuntimeVersion(packageName, resolutionSpecifier) {
   try {
     const entry = require2.resolve(resolutionSpecifier);
     const root = await findPackageRoot(entry, packageName);
-    const files = await collectRuntimeFiles(path8.join(root, "dist"));
+    const files = await collectRuntimeFiles(path9.join(root, "dist"));
     const hash = createHash3("sha256");
     for (const file of files) {
-      const relative = path8.relative(root, file).split(path8.sep).join("/");
+      const relative = path9.relative(root, file).split(path9.sep).join("/");
       hash.update(relative);
       hash.update("\0");
       hash.update(await readFile2(file));
@@ -1240,16 +1240,16 @@ function readPackageJson() {
   }
 }
 async function findPackageRoot(entry, packageName) {
-  let directory = path8.dirname(entry);
+  let directory = path9.dirname(entry);
   for (let depth = 0; depth < 12; depth += 1) {
     try {
       const parsed = JSON.parse(
-        await readFile2(path8.join(directory, "package.json"), "utf8")
+        await readFile2(path9.join(directory, "package.json"), "utf8")
       );
       if (parsed.name === packageName) return directory;
     } catch {
     }
-    const parent = path8.dirname(directory);
+    const parent = path9.dirname(directory);
     if (parent === directory) break;
     directory = parent;
   }
@@ -1262,7 +1262,7 @@ async function collectRuntimeFiles(directory) {
   while (pending.length > 0) {
     const current = pending.pop();
     for (const entry of await readdir(current, { withFileTypes: true })) {
-      const candidate = path8.join(current, entry.name);
+      const candidate = path9.join(current, entry.name);
       if (entry.isDirectory()) {
         pending.push(candidate);
       } else if (entry.isFile() && /\.(?:js|json|css|wasm)$/iu.test(entry.name)) {
@@ -1346,9 +1346,9 @@ var init_output_bounds = __esm({
 
 // src/mcp/document-service.ts
 import { createHash as createHash5 } from "crypto";
-import { basename as basename3, extname as extname3 } from "path";
+import { basename as basename4, extname as extname3 } from "path";
 import { MCP_WIRE_LIMITS as MCP_WIRE_LIMITS4 } from "@bendyline/docblocks/mcp";
-import { decodeUtf8Text as decodeUtf8Text3, tryParseWorkspacePath } from "@bendyline/docblocks/filesystem";
+import { decodeUtf8Text as decodeUtf8Text4, tryParseWorkspacePath as tryParseWorkspacePath2 } from "@bendyline/docblocks/filesystem";
 async function readAssetManifest(container, signal) {
   const bytes = await container.readFile(ASSET_MANIFEST_PATH);
   if (!bytes) return /* @__PURE__ */ new Map();
@@ -1358,7 +1358,7 @@ async function readAssetManifest(container, signal) {
   }
   try {
     const parsed = JSON.parse(
-      decodeUtf8Text3(bytes, {
+      decodeUtf8Text4(bytes, {
         label: "The document asset manifest",
         path: ASSET_MANIFEST_PATH
       })
@@ -1372,12 +1372,12 @@ async function readAssetManifest(container, signal) {
       if (!isExactRecord(candidate, ["path", "mimeType", "altText", "credit", "license"])) {
         throw new Error("The document asset manifest contains an invalid entry");
       }
-      const path9 = tryParseWorkspacePath(candidate.path);
-      if (path9 === null || path9 === "" || path9 === "index.md" || path9.startsWith(".docblocks/") || !isNullableMimeType(candidate.mimeType) || !isNullableMetadata(candidate.altText) || !isNullableMetadata(candidate.credit) || !isNullableMetadata(candidate.license) || entries.has(path9)) {
+      const path10 = tryParseWorkspacePath2(candidate.path);
+      if (path10 === null || path10 === "" || path10 === "index.md" || path10.startsWith(".docblocks/") || !isNullableMimeType(candidate.mimeType) || !isNullableMetadata(candidate.altText) || !isNullableMetadata(candidate.credit) || !isNullableMetadata(candidate.license) || entries.has(path10)) {
         throw new Error("The document asset manifest contains invalid metadata");
       }
-      entries.set(path9, {
-        path: path9,
+      entries.set(path10, {
+        path: path10,
         mimeType: candidate.mimeType,
         altText: candidate.altText,
         credit: candidate.credit,
@@ -1513,7 +1513,7 @@ function throwIfAborted5(signal) {
   throwIfAborted(signal, "MCP operation was cancelled");
 }
 function baseNameFromName(name) {
-  const leaf = basename3(name.replace(/\\/gu, "/")) || "document";
+  const leaf = basename4(name.replace(/\\/gu, "/")) || "document";
   const extension = extname3(leaf);
   return (extension ? leaf.slice(0, -extension.length) : leaf) || "document";
 }
@@ -1605,7 +1605,7 @@ var init_document_service = __esm({
           const physical = await this.authority.authorizeRootRead(source.rootId, source.path);
           const bytes = await this.authority.readFile(physical, signal);
           throwIfAborted5(signal);
-          const filename = basename3(source.path);
+          const filename = basename4(source.path);
           return {
             bytes,
             filename,
@@ -1662,7 +1662,7 @@ var init_document_service = __esm({
           case "file": {
             const physical = await this.authority.authorizeRootRead(source.rootId, source.path);
             const bytes = await this.authority.readFile(physical, signal);
-            const name = basename3(source.path);
+            const name = basename4(source.path);
             return {
               source: { kind: "bytes", data: bytes, filename: name },
               sourceFormat: normalizeFormat(source.format ?? formatFromName(name)),
@@ -2670,7 +2670,7 @@ var init_intelligence = __esm({
 // src/mcp/preview-service.ts
 import { mkdtemp as mkdtemp3, readFile as readFile3, rm as rm3, writeFile as writeFile2 } from "fs/promises";
 import { tmpdir as tmpdir2 } from "os";
-import { basename as basename4, extname as extname4, join as join3 } from "path";
+import { basename as basename5, extname as extname4, join as join3 } from "path";
 import { DOCBLOCKS_MCP_WIRE_VERSION as DOCBLOCKS_MCP_WIRE_VERSION2 } from "@bendyline/docblocks/mcp";
 async function previewEngineVersions() {
   return [
@@ -2908,7 +2908,7 @@ function thumbnailFilter(width, height) {
   return `scale=${width}:${height}:force_original_aspect_ratio=decrease,pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2`;
 }
 function baseNameFromFilename(filename) {
-  const leaf = basename4(filename.replace(/\\/gu, "/")) || "video";
+  const leaf = basename5(filename.replace(/\\/gu, "/")) || "video";
   const extension = extname4(leaf);
   return (extension ? leaf.slice(0, -extension.length) : leaf) || "video";
 }
@@ -3706,7 +3706,7 @@ async function convertPreparedDocument(artifacts, prepared, request, signal, pro
   }
 }
 function createConversionCacheKey(prepared, request, target, fidelity, engineVersions) {
-  const canonical = canonicalJson({
+  const canonical2 = canonicalJson({
     source: {
       sha256: prepared.sourceSha256,
       format: prepared.sourceFormat,
@@ -3727,7 +3727,7 @@ function createConversionCacheKey(prepared, request, target, fidelity, engineVer
       title: request.title ?? null
     }
   });
-  return createHash6("sha256").update(canonical).digest("hex");
+  return createHash6("sha256").update(canonical2).digest("hex");
 }
 async function findCompletedConversion(artifacts, key) {
   const cache = completedConversionCache(artifacts);
@@ -4305,10 +4305,10 @@ function registerAgenticTools(server, context) {
     async ({ source, targets, themeId, transformId, autoTemplates, title }, extra) => {
       try {
         return await context.runOperation(extra.signal, async (operationSignal) => {
-          const canonical = requireDocumentSource(source);
+          const canonical2 = requireDocumentSource(source);
           const documents = new DocumentService(await context.authority, context.artifacts);
           await sendProgress(extra, 0, targets.length + 1, "Resolving document");
-          const prepared = await documents.prepare(canonical, operationSignal);
+          const prepared = await documents.prepare(canonical2, operationSignal);
           const results = await convertPreparedDocument(
             context.artifacts,
             prepared,
@@ -4350,9 +4350,9 @@ function registerAgenticTools(server, context) {
     async ({ source }, extra) => {
       try {
         return await context.runOperation(extra.signal, async (operationSignal) => {
-          const canonical = requireDocumentSource(source);
+          const canonical2 = requireDocumentSource(source);
           const documents = new DocumentService(await context.authority, context.artifacts);
-          const prepared = await documents.prepare(canonical, operationSignal);
+          const prepared = await documents.prepare(canonical2, operationSignal);
           const [result] = await convertPreparedDocument(
             context.artifacts,
             prepared,
@@ -4385,7 +4385,7 @@ function registerAgenticTools(server, context) {
     async ({ artifactUri, destination }, extra) => {
       try {
         return await context.runOperation(extra.signal, async (operationSignal) => {
-          const canonical = requireWire(
+          const canonical2 = requireWire(
             parseMaterializationOptions(destination),
             "materialization options"
           );
@@ -4395,15 +4395,15 @@ function registerAgenticTools(server, context) {
             context.artifacts.read(artifactUri, operationSignal)
           ]);
           throwIfAborted5(operationSignal);
-          const outputPath = await authority.authorizeRootWrite(canonical.rootId, canonical.path);
+          const outputPath = await authority.authorizeRootWrite(canonical2.rootId, canonical2.path);
           await authority.materializeBytes(outputPath, bytes, bytes.byteLength, {
-            ifExists: canonical.ifExists,
-            expectedSha256: canonical.expectedSha256 ?? void 0,
+            ifExists: canonical2.ifExists,
+            expectedSha256: canonical2.expectedSha256 ?? void 0,
             signal: operationSignal
           });
           const payload = {
             artifact,
-            destination: { rootId: canonical.rootId, path: canonical.path },
+            destination: { rootId: canonical2.rootId, path: canonical2.path },
             sha256: artifact.sha256
           };
           return textAndStructured(payload);
@@ -4710,6 +4710,7 @@ function registerTemplateTools(server, context) {
                 title: boundNullableWireText(block.title, MCP_WIRE_LIMITS7.labelCharacters),
                 profile: {
                   ...profile,
+                  hasCompoundBody: profile.hasCompoundBody ?? false,
                   hasAsciiDiagram: profile.hasAsciiDiagram ?? false,
                   hasTimeline: profile.hasTimeline ?? false,
                   hasTree: profile.hasTree ?? false
@@ -4866,6 +4867,7 @@ function registerTemplateTools(server, context) {
               title: boundNullableWireText(block.title, MCP_WIRE_LIMITS7.labelCharacters),
               profile: {
                 ...profile,
+                hasCompoundBody: profile.hasCompoundBody ?? false,
                 hasAsciiDiagram: profile.hasAsciiDiagram ?? false,
                 hasTimeline: profile.hasTimeline ?? false,
                 hasTree: profile.hasTree ?? false
@@ -6158,12 +6160,12 @@ var init_server = __esm({
 });
 
 // src/program.ts
-import { Command as Command9 } from "commander";
+import { Command as Command10 } from "commander";
 
 // src/commands/build.ts
 import { Command } from "commander";
 import { mkdir, opendir, readFile, stat as stat2, writeFile } from "fs/promises";
-import path4 from "path";
+import path5 from "path";
 
 // src/render-html.ts
 init_contained_file();
@@ -6172,7 +6174,7 @@ init_node_error();
 import { realpath, stat } from "fs/promises";
 import path3 from "path";
 import { markdownToDoc } from "@bendyline/squisq/doc";
-import { parseMarkdown } from "@bendyline/squisq/markdown";
+import { parseMarkdown, readFrontmatterThemeId } from "@bendyline/squisq/markdown";
 import { collectImagePaths, docToHtml } from "@bendyline/squisq-formats/html";
 import { PLAYER_BUNDLE } from "@bendyline/squisq-react/standalone-source";
 
@@ -6194,25 +6196,35 @@ var DEFAULT_MAX_ASSET_BYTES = 50 * 1024 * 1024;
 var MAX_SINGLE_ASSET_BYTES = 20 * 1024 * 1024;
 async function renderMarkdownHtml(markdown, options) {
   await assertKnownThemeId(options.themeId);
+  const warn = options.onWarning ?? ((message) => console.warn(message));
   const markdownDoc = parseMarkdown(markdown);
   const doc = markdownToDoc(markdownDoc);
+  const themeId = options.themeId ?? (readFrontmatterThemeId(markdownDoc.frontmatter) ? void 0 : await usableFallbackThemeId(options.fallbackThemeId, warn));
   const images = options.sourcePath && options.assetRoot ? await readReferencedImages(
     doc,
     options.sourcePath,
     options.assetRoot,
     options.maxAssetBytes ?? DEFAULT_MAX_ASSET_BYTES,
     options.allowReferencedAsset,
-    options.onWarning ?? ((message) => console.warn(message))
+    warn
   ) : void 0;
   return docToHtml(doc, {
     playerScript: PLAYER_BUNDLE,
     images,
     title: options.title,
     mode: options.mode ?? "static",
-    themeId: options.themeId,
+    themeId,
     showCodeCopyButton: true
   });
 }
+async function usableFallbackThemeId(fallbackThemeId, warn) {
+  if (!fallbackThemeId) return void 0;
+  if ((await getAvailableThemeIds()).includes(fallbackThemeId)) return fallbackThemeId;
+  warn(
+    `Ignoring unknown fallback theme "${fallbackThemeId}"; the document's default theme applies.`
+  );
+  return void 0;
+}
 async function readReferencedImages(doc, sourcePath, assetRoot, maxAssetBytes, allowReferencedAsset, warn) {
   const images = /* @__PURE__ */ new Map();
   const root = await realpathIfPresent(path3.resolve(assetRoot));
@@ -6310,7 +6322,564 @@ function positiveLimit(value, fallback, label) {
 
 // src/commands/build.ts
 init_node_error();
-import { decodeUtf8Text } from "@bendyline/docblocks/filesystem";
+
+// src/internal/workspace-settings.ts
+import { decodeUtf8Text, parseWorkspacePath as parseWorkspacePath2 } from "@bendyline/docblocks/filesystem";
+import {
+  WORKSPACE_SETTINGS_LIMITS,
+  WORKSPACE_SETTINGS_PATH,
+  parseWorkspaceSettingsText,
+  resolveWorkspaceDefaultThemeId
+} from "@bendyline/docblocks/workspace-settings";
+
+// src/internal/workspace-io.ts
+init_link_support();
+import { constants as fsConstants } from "fs";
+import fs2 from "fs/promises";
+import { randomUUID } from "crypto";
+import path4 from "path";
+import {
+  FsError,
+  mapNodeErrorCodeToFsErrorCode,
+  parseFileSystemVersion,
+  parseWorkspacePath,
+  tryParseWorkspacePath
+} from "@bendyline/docblocks/filesystem";
+init_node_error();
+init_paths();
+var NODE_WORKSPACE_IO_LIMITS = {
+  maxFileBytes: 256 * 1024 * 1024,
+  maxDirectoryEntries: 1e5
+};
+var LISTING_STAT_CONCURRENCY = 16;
+var TEMPORARY_PREFIX = ".docblocks-tmp-";
+async function createNodeWorkspaceIO(rootDir, options = {}) {
+  const requested = path4.resolve(rootDir);
+  let root;
+  try {
+    root = await fs2.realpath(requested);
+  } catch (error) {
+    if (isNodeErrorCode(error, ["ENOENT", "ENOTDIR"])) {
+      throw new FsError("not-found", `Workspace folder not found: ${requested}`, {
+        operation: "stat"
+      });
+    }
+    throw toFsError(error, "stat", "");
+  }
+  let info;
+  try {
+    info = await fs2.stat(root);
+  } catch (error) {
+    throw toFsError(error, "stat", "");
+  }
+  if (!info.isDirectory()) {
+    throw new FsError("type-mismatch", `Workspace root is not a folder: ${requested}`, {
+      operation: "stat"
+    });
+  }
+  return new NodeWorkspaceIO(root, {
+    maxFileBytes: positiveLimit(
+      options.maxFileBytes,
+      NODE_WORKSPACE_IO_LIMITS.maxFileBytes,
+      "workspace file byte"
+    ),
+    maxDirectoryEntries: positiveLimit(
+      options.maxDirectoryEntries,
+      NODE_WORKSPACE_IO_LIMITS.maxDirectoryEntries,
+      "workspace folder entry"
+    )
+  });
+}
+var NodeWorkspaceIO = class {
+  constructor(root, limits) {
+    this.root = root;
+    this.limits = limits;
+  }
+  async stat(input) {
+    const workspacePath = canonical(input, "stat");
+    try {
+      const located = await this.locate(workspacePath, "stat");
+      if (!located) return null;
+      const info = await lstatOrNull(located);
+      if (!info) return null;
+      return snapshotFor(workspacePath, assertSupportedKind(info, workspacePath, "stat"), info);
+    } catch (error) {
+      throw toFsError(error, "stat", workspacePath);
+    }
+  }
+  async readFile(input) {
+    const workspacePath = canonical(input, "read");
+    try {
+      const located = await this.locate(workspacePath, "read");
+      if (!located) return null;
+      const before = await lstatOrNull(located);
+      if (!before) return null;
+      if (assertSupportedKind(before, workspacePath, "read") !== "file") {
+        throw new FsError("type-mismatch", `"${workspacePath}" is a folder, not a file.`, {
+          operation: "read",
+          path: workspacePath
+        });
+      }
+      this.assertFileSize(before.size, workspacePath, "read");
+      return await this.readLocatedFile(located, before, workspacePath);
+    } catch (error) {
+      if (isNodeErrorCode(error, ["ENOENT", "ENOTDIR"])) return null;
+      throw toFsError(error, "read", workspacePath);
+    }
+  }
+  async readDirectory(input) {
+    const workspacePath = canonical(input, "list");
+    try {
+      let directory = this.root;
+      if (workspacePath) {
+        const located = await this.locate(workspacePath, "list");
+        const info = located ? await lstatOrNull(located) : null;
+        if (!located || !info) {
+          throw new FsError("not-found", `Folder "${workspacePath}" does not exist.`, {
+            operation: "list",
+            path: workspacePath
+          });
+        }
+        if (assertSupportedKind(info, workspacePath, "list") !== "directory") {
+          throw new FsError("type-mismatch", `"${workspacePath}" is a file, not a folder.`, {
+            operation: "list",
+            path: workspacePath
+          });
+        }
+        directory = located;
+      }
+      const names = await this.listNames(directory, workspacePath);
+      const entries = [];
+      for (let index = 0; index < names.length; index += LISTING_STAT_CONCURRENCY) {
+        const batch = names.slice(index, index + LISTING_STAT_CONCURRENCY);
+        const snapshots = await Promise.all(
+          batch.map(async (name) => {
+            const info = await lstatOrNull(path4.join(directory, name));
+            if (!info || info.isSymbolicLink()) return null;
+            const kind = info.isFile() ? "file" : info.isDirectory() ? "directory" : null;
+            if (!kind) return null;
+            const childPath = parseWorkspacePath(workspacePath ? `${workspacePath}/${name}` : name);
+            return snapshotFor(childPath, kind, info);
+          })
+        );
+        for (const snapshot of snapshots) if (snapshot) entries.push(snapshot);
+      }
+      return Object.freeze(entries.sort(compareSnapshots));
+    } catch (error) {
+      throw toFsError(error, "list", workspacePath);
+    }
+  }
+  async writeFile(input, data, options = {}) {
+    const workspacePath = canonical(input, "write");
+    if (!workspacePath) {
+      throw new FsError("invalid-path", "The workspace root cannot be written.", {
+        operation: "write",
+        path: workspacePath
+      });
+    }
+    const bytes = ArrayBuffer.isView(data) ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength) : new Uint8Array(data);
+    const mode = options.mode ?? "upsert";
+    const expectedVersion = options.expectedVersion;
+    let temporary = null;
+    try {
+      this.assertFileSize(BigInt(bytes.byteLength), workspacePath, "write");
+      const parent = await this.ensureParent(workspacePath, options.createParents === true);
+      const target = path4.join(parent, basename(workspacePath));
+      let current = await lstatOrNull(target);
+      assertWritable(current, workspacePath, mode, expectedVersion);
+      temporary = path4.join(parent, `${TEMPORARY_PREFIX}${randomUUID()}`);
+      const handle = await fs2.open(temporary, "wx", 438);
+      try {
+        await handle.writeFile(bytes);
+        if (current?.isFile()) await handle.chmod(Number(current.mode & 0o7777n));
+      } finally {
+        await handle.close();
+      }
+      current = await lstatOrNull(target);
+      assertWritable(current, workspacePath, mode, expectedVersion);
+      if (!current && (mode === "create" || expectedVersion === null)) {
+        await publishExclusive(temporary, target, bytes, workspacePath, mode);
+      } else {
+        await fs2.rename(temporary, target);
+        temporary = null;
+      }
+      const written = await fs2.lstat(target, { bigint: true });
+      const snapshot = snapshotFor(workspacePath, "file", written);
+      if (snapshot.kind !== "file") throw new Error("Unreachable: wrote a non-file entry.");
+      return snapshot;
+    } catch (error) {
+      throw toFsError(error, "write", workspacePath);
+    } finally {
+      if (temporary) await fs2.rm(temporary, { force: true }).catch(() => void 0);
+    }
+  }
+  /**
+   * Physical absolute path for `workspacePath`, with its parent proven to be
+   * inside the root, or null when a parent is missing or is a file.
+   */
+  async locate(workspacePath, operation) {
+    if (!workspacePath) return this.root;
+    const segments = workspacePath.split("/");
+    const name = segments.pop();
+    let parent;
+    try {
+      parent = await fs2.realpath(path4.join(this.root, ...segments));
+    } catch (error) {
+      if (isNodeErrorCode(error, ["ENOENT", "ENOTDIR"])) return null;
+      throw error;
+    }
+    if (!isPathInside(this.root, parent)) throw escapeError(workspacePath, operation);
+    return path4.join(parent, name);
+  }
+  /** Resolve (and optionally create) the physical parent folder of a write. */
+  async ensureParent(workspacePath, createParents) {
+    const segments = workspacePath.split("/").slice(0, -1);
+    let current = this.root;
+    let walked = "";
+    for (const segment of segments) {
+      walked = walked ? `${walked}/${segment}` : segment;
+      const next = path4.join(current, segment);
+      let info = await lstatOrNull(next);
+      if (!info) {
+        if (!createParents) {
+          throw new FsError("not-found", `Parent folder "${walked}" does not exist.`, {
+            operation: "write",
+            path: workspacePath
+          });
+        }
+        try {
+          await fs2.mkdir(next);
+        } catch (error) {
+          if (!isNodeErrorCode(error, "EEXIST")) throw error;
+        }
+        info = await fs2.lstat(next, { bigint: true });
+      }
+      if (info.isSymbolicLink()) {
+        const physical = await fs2.realpath(next);
+        if (!isPathInside(this.root, physical)) throw escapeError(workspacePath, "write");
+        if (!(await fs2.stat(physical)).isDirectory()) throw parentFileError(walked, workspacePath);
+        current = physical;
+      } else if (info.isDirectory()) {
+        current = next;
+      } else {
+        throw parentFileError(walked, workspacePath);
+      }
+    }
+    const physicalParent = await fs2.realpath(current);
+    if (!isPathInside(this.root, physicalParent)) throw escapeError(workspacePath, "write");
+    return physicalParent;
+  }
+  async listNames(directory, workspacePath) {
+    const names = [];
+    let seen = 0;
+    const handle = await fs2.opendir(directory);
+    for await (const dirent of handle) {
+      seen += 1;
+      if (seen > this.limits.maxDirectoryEntries) {
+        throw new FsError(
+          "not-supported",
+          `Folder "${workspacePath || "."}" has more than ${this.limits.maxDirectoryEntries} entries.`,
+          { operation: "list", path: workspacePath }
+        );
+      }
+      if (dirent.isSymbolicLink()) continue;
+      if (tryParseWorkspacePath(dirent.name) !== dirent.name) continue;
+      names.push(dirent.name);
+    }
+    return names;
+  }
+  async readLocatedFile(located, before, workspacePath) {
+    const noFollow = typeof fsConstants.O_NOFOLLOW === "number" ? fsConstants.O_NOFOLLOW : 0;
+    const handle = await fs2.open(located, fsConstants.O_RDONLY | noFollow);
+    try {
+      const opened = await handle.stat({ bigint: true });
+      if (!opened.isFile() || opened.ino !== before.ino) throw changedError(workspacePath);
+      const physical = await fs2.realpath(located);
+      if (!isPathInside(this.root, physical)) throw escapeError(workspacePath, "read");
+      this.assertFileSize(opened.size, workspacePath, "read");
+      const size = Number(opened.size);
+      const buffer = new Uint8Array(size);
+      let offset = 0;
+      while (offset < size) {
+        const { bytesRead } = await handle.read(buffer, offset, size - offset, offset);
+        if (bytesRead === 0) break;
+        offset += bytesRead;
+      }
+      const probe = new Uint8Array(1);
+      const grew = (await handle.read(probe, 0, 1, offset)).bytesRead > 0;
+      const after = await handle.stat({ bigint: true });
+      if (grew || offset !== size || !sameFileState(opened, after)) {
+        throw changedError(workspacePath);
+      }
+      const entry = snapshotFor(workspacePath, "file", opened);
+      if (entry.kind !== "file") throw new Error("Unreachable: read a non-file entry.");
+      return Object.freeze({ entry, data: buffer.buffer });
+    } finally {
+      await handle.close();
+    }
+  }
+  assertFileSize(size, workspacePath, operation) {
+    if (size > BigInt(this.limits.maxFileBytes)) {
+      throw new FsError(
+        "not-supported",
+        `"${workspacePath}" is larger than the ${this.limits.maxFileBytes}-byte workspace file limit.`,
+        { operation, path: workspacePath }
+      );
+    }
+  }
+};
+function canonical(input, operation) {
+  try {
+    return parseWorkspacePath(input);
+  } catch (error) {
+    throw toFsError(error, operation, input);
+  }
+}
+function basename(workspacePath) {
+  const slash = workspacePath.lastIndexOf("/");
+  return slash < 0 ? workspacePath : workspacePath.slice(slash + 1);
+}
+async function lstatOrNull(absolutePath) {
+  try {
+    return await fs2.lstat(absolutePath, { bigint: true });
+  } catch (error) {
+    if (isNodeErrorCode(error, ["ENOENT", "ENOTDIR"])) return null;
+    throw error;
+  }
+}
+function assertSupportedKind(info, workspacePath, operation) {
+  if (info.isSymbolicLink()) {
+    throw new FsError(
+      "not-supported",
+      `"${workspacePath}" is a symbolic link; workspace outputs never follow links.`,
+      { operation, path: workspacePath }
+    );
+  }
+  if (info.isFile()) return "file";
+  if (info.isDirectory()) return "directory";
+  throw new FsError("not-supported", `"${workspacePath}" is not a regular file or folder.`, {
+    operation,
+    path: workspacePath
+  });
+}
+function versionFor(kind, info) {
+  return parseFileSystemVersion(
+    `node-v1:${kind}:ino=${info.ino}:size=${kind === "file" ? info.size : 0n}:mtime-ns=${info.mtimeNs}`
+  );
+}
+function snapshotFor(workspacePath, kind, info) {
+  const base = {
+    path: workspacePath,
+    name: basename(workspacePath),
+    version: versionFor(kind, info),
+    lastModified: info.mtime.toISOString()
+  };
+  if (kind === "directory") return Object.freeze({ ...base, kind, size: null });
+  const size = Number(info.size);
+  if (!Number.isSafeInteger(size)) {
+    throw new FsError("not-supported", `"${workspacePath}" is too large to describe.`, {
+      path: workspacePath
+    });
+  }
+  return Object.freeze({ ...base, kind, size });
+}
+function sameFileState(left, right) {
+  return left.ino === right.ino && left.size === right.size && left.mtimeNs === right.mtimeNs;
+}
+function assertWritable(current, workspacePath, mode, expectedVersion) {
+  if (current) {
+    const kind = assertSupportedKind(current, workspacePath, "write");
+    if (kind === "directory") {
+      throw new FsError("type-mismatch", `"${workspacePath}" is a folder; it cannot be replaced.`, {
+        operation: "write",
+        path: workspacePath
+      });
+    }
+    if (mode === "create") {
+      throw new FsError("already-exists", `"${workspacePath}" already exists.`, {
+        operation: "write",
+        path: workspacePath
+      });
+    }
+  } else if (mode === "replace") {
+    throw new FsError("not-found", `"${workspacePath}" does not exist.`, {
+      operation: "write",
+      path: workspacePath
+    });
+  }
+  if (expectedVersion === void 0) return;
+  const matches = expectedVersion === null ? !current : !!current && versionFor("file", current) === expectedVersion;
+  if (!matches) {
+    throw new FsError("conflict", `"${workspacePath}" changed since it was read.`, {
+      operation: "write",
+      path: workspacePath,
+      retryable: true
+    });
+  }
+}
+async function publishExclusive(temporary, target, bytes, workspacePath, mode) {
+  try {
+    await fs2.link(temporary, target);
+    return;
+  } catch (error) {
+    if (isNodeErrorCode(error, "EEXIST")) throw existsRaceError(workspacePath, mode);
+    if (!isLinkUnsupportedError(error)) throw error;
+  }
+  let handle;
+  try {
+    handle = await fs2.open(target, "wx", 438);
+  } catch (error) {
+    if (isNodeErrorCode(error, "EEXIST")) throw existsRaceError(workspacePath, mode);
+    throw error;
+  }
+  try {
+    await handle.writeFile(bytes);
+  } finally {
+    await handle.close();
+  }
+}
+function existsRaceError(workspacePath, mode) {
+  return mode === "create" ? new FsError("already-exists", `"${workspacePath}" already exists.`, {
+    operation: "write",
+    path: workspacePath
+  }) : new FsError("conflict", `"${workspacePath}" was created by another writer.`, {
+    operation: "write",
+    path: workspacePath,
+    retryable: true
+  });
+}
+function escapeError(workspacePath, operation) {
+  return new FsError(
+    "path-escape",
+    `"${workspacePath}" resolves outside the workspace folder through a symbolic link.`,
+    { operation, path: workspacePath }
+  );
+}
+function parentFileError(parent, workspacePath) {
+  return new FsError("type-mismatch", `"${parent}" is a file, not a folder.`, {
+    operation: "write",
+    path: workspacePath
+  });
+}
+function changedError(workspacePath) {
+  return new FsError("conflict", `"${workspacePath}" changed while it was being read.`, {
+    operation: "read",
+    path: workspacePath,
+    retryable: true
+  });
+}
+function compareSnapshots(left, right) {
+  if (left.kind !== right.kind) return left.kind === "directory" ? -1 : 1;
+  return left.name < right.name ? -1 : left.name > right.name ? 1 : 0;
+}
+function toFsError(error, operation, workspacePath) {
+  if (error instanceof FsError) return error;
+  const message = error instanceof Error ? error.message : String(error);
+  const code = nodeErrorCode(error);
+  if (code === "ELOOP") {
+    return new FsError(
+      "not-supported",
+      `"${workspacePath}" is a symbolic link; workspace outputs never follow links.`,
+      { operation, path: workspacePath }
+    );
+  }
+  if (code) {
+    return new FsError(
+      mapNodeErrorCodeToFsErrorCode(code),
+      `Could not ${OPERATION_VERBS[operation]} "${workspacePath || "."}": ${message}`,
+      { operation, path: workspacePath }
+    );
+  }
+  return new FsError("io", message, { operation, path: workspacePath });
+}
+function nodeErrorCode(error) {
+  if (!(error instanceof Error) || !("code" in error)) return null;
+  const { code } = error;
+  return typeof code === "string" ? code : null;
+}
+var OPERATION_VERBS = {
+  "parse-path": "parse",
+  read: "read",
+  stat: "inspect",
+  list: "list",
+  write: "write",
+  "create-directory": "create",
+  remove: "remove",
+  move: "move",
+  snapshot: "snapshot",
+  watch: "watch",
+  dispose: "close"
+};
+
+// src/internal/workspace-settings.ts
+var MAX_SETTINGS_FILE_BYTES = WORKSPACE_SETTINGS_LIMITS.maxFileBytes + 3;
+async function readWorkspaceSettings(io) {
+  const settingsPath = parseWorkspacePath2(WORKSPACE_SETTINGS_PATH);
+  const info = await io.stat(settingsPath);
+  if (!info) return { status: "missing" };
+  if (info.kind !== "file") {
+    return { status: "invalid", message: `${WORKSPACE_SETTINGS_PATH} is a folder, not a file.` };
+  }
+  if (info.size > MAX_SETTINGS_FILE_BYTES) return tooLarge();
+  const read = await io.readFile(settingsPath);
+  if (!read) return { status: "missing" };
+  if (read.data.byteLength > MAX_SETTINGS_FILE_BYTES) return tooLarge();
+  let text;
+  try {
+    text = decodeUtf8Text(read.data, {
+      label: "Workspace settings",
+      path: WORKSPACE_SETTINGS_PATH
+    });
+  } catch (error) {
+    return {
+      status: "invalid",
+      message: error instanceof Error ? error.message : `${WORKSPACE_SETTINGS_PATH} is not UTF-8.`
+    };
+  }
+  return parseWorkspaceSettingsText(text);
+}
+function describeWorkspaceSettingsProblem(message) {
+  return message.includes(WORKSPACE_SETTINGS_PATH) ? message : `${WORKSPACE_SETTINGS_PATH}: ${message}`;
+}
+function tooLarge() {
+  return {
+    status: "invalid",
+    message: `${WORKSPACE_SETTINGS_PATH} is larger than ${WORKSPACE_SETTINGS_LIMITS.maxFileBytes / 1024} KiB.`
+  };
+}
+async function createWorkspaceThemeFallback(rootDir, warn) {
+  const io = await createNodeWorkspaceIO(rootDir);
+  let lastWarning = null;
+  const report = (message) => {
+    if (message !== null && message !== lastWarning) warn(message);
+    lastWarning = message;
+  };
+  return {
+    async resolve() {
+      const result = await readWorkspaceSettings(io);
+      if (result.status === "missing") {
+        report(null);
+        return void 0;
+      }
+      if (result.status !== "ok") {
+        report(`Ignoring workspace settings. ${describeWorkspaceSettingsProblem(result.message)}`);
+        return void 0;
+      }
+      const themeId = resolveWorkspaceDefaultThemeId(result.settings);
+      if (themeId && !(await getAvailableThemeIds()).includes(themeId)) {
+        report(
+          `Ignoring workspace default theme "${themeId}" from ${WORKSPACE_SETTINGS_PATH}: it is not a known theme.`
+        );
+        return void 0;
+      }
+      report(null);
+      return themeId;
+    }
+  };
+}
+
+// src/commands/build.ts
+import { decodeUtf8Text as decodeUtf8Text2 } from "@bendyline/docblocks/filesystem";
 var DEFAULT_MAX_BUILD_ENTRIES = 1e5;
 var DEFAULT_MAX_BUILD_DEPTH = 64;
 var DEFAULT_MAX_BUILD_INPUT_BYTES = 20 * 1024 * 1024;
@@ -6319,8 +6888,8 @@ var DEFAULT_MAX_BUILD_OUTPUT_BYTES = 128 * 1024 * 1024;
 var DEFAULT_MAX_BUILD_TOTAL_OUTPUT_BYTES = 1024 * 1024 * 1024;
 async function runBuild(opts) {
   await assertKnownThemeId(opts.theme);
-  const inputDir = path4.resolve(opts.input);
-  const outputDir = path4.resolve(opts.output);
+  const inputDir = path5.resolve(opts.input);
+  const outputDir = path5.resolve(opts.output);
   let inputStat;
   try {
     inputStat = await stat2(inputDir);
@@ -6329,6 +6898,8 @@ async function runBuild(opts) {
     throw new Error(`Input directory not found: ${inputDir}`);
   }
   if (!inputStat.isDirectory()) throw new Error(`Input is not a directory: ${inputDir}`);
+  const warn = opts.onWarning ?? ((message) => console.warn(message));
+  const fallbackThemeId = opts.theme || opts.ignoreWorkspaceSettings ? void 0 : await (await createWorkspaceThemeFallback(inputDir, warn)).resolve();
   const markdownFiles = await listMarkdownFiles(inputDir, {
     maxEntries: positiveLimit(opts.maxEntries, DEFAULT_MAX_BUILD_ENTRIES, "build entry"),
     maxDepth: positiveLimit(opts.maxDepth, DEFAULT_MAX_BUILD_DEPTH, "build depth")
@@ -6343,8 +6914,8 @@ async function runBuild(opts) {
   let totalInputBytes = 0;
   let totalOutputBytes = 0;
   for (const sourcePath of markdownFiles) {
-    const relativePath = path4.relative(inputDir, sourcePath);
-    const outputPath = path4.join(outputDir, replaceMarkdownExtension(relativePath));
+    const relativePath = path5.relative(inputDir, sourcePath);
+    const outputPath = path5.join(outputDir, replaceMarkdownExtension(relativePath));
     const sourceBytes = await readFile(sourcePath);
     if (sourceBytes.byteLength > byteLimits.maxInputBytes) {
       throw new Error(
@@ -6357,13 +6928,15 @@ async function runBuild(opts) {
         `Build inputs exceed the ${byteLimits.maxTotalInputBytes}-byte aggregate limit.`
       );
     }
-    const source = decodeUtf8Text(sourceBytes, { label: "Build input", path: sourcePath });
+    const source = decodeUtf8Text2(sourceBytes, { label: "Build input", path: sourcePath });
     const html = await renderMarkdownHtml(source, {
       title: titleFromPath(relativePath),
       sourcePath,
       assetRoot: inputDir,
       themeId: opts.theme,
-      mode: "static"
+      fallbackThemeId,
+      mode: "static",
+      onWarning: warn
     });
     const outputBytes = Buffer.byteLength(html, "utf8");
     if (outputBytes > byteLimits.maxOutputBytes) {
@@ -6377,18 +6950,22 @@ async function runBuild(opts) {
         `Build outputs exceed the ${byteLimits.maxTotalOutputBytes}-byte aggregate limit.`
       );
     }
-    await mkdir(path4.dirname(outputPath), { recursive: true });
+    await mkdir(path5.dirname(outputPath), { recursive: true });
     await writeFile(outputPath, html, "utf-8");
     builtFiles.push(outputPath);
   }
   return { inputDir, outputDir, builtFiles };
 }
-var buildCommand = new Command("build").description("Build markdown files into HTML output").option("-i, --input <dir>", "input directory", ".").option("-o, --output <dir>", "output directory", "dist").option("-t, --theme <id>", "Squisq theme ID to apply").option("--max-input-bytes <bytes>", "maximum bytes in one Markdown input").option("--max-total-input-bytes <bytes>", "maximum aggregate Markdown input bytes").option("--max-output-bytes <bytes>", "maximum bytes in one generated HTML file").option("--max-total-output-bytes <bytes>", "maximum aggregate generated HTML bytes").option("--allow-large-build", "disable default byte budgets for a trusted bulk build").action(async (opts) => {
+var buildCommand = new Command("build").description("Build markdown files into HTML output").option("-i, --input <dir>", "input directory", ".").option("-o, --output <dir>", "output directory", "dist").option("-t, --theme <id>", "Squisq theme ID to apply").option(
+  "--ignore-workspace-settings",
+  "do not apply the default theme from <input>/.docblocks/workspace.json"
+).option("--max-input-bytes <bytes>", "maximum bytes in one Markdown input").option("--max-total-input-bytes <bytes>", "maximum aggregate Markdown input bytes").option("--max-output-bytes <bytes>", "maximum bytes in one generated HTML file").option("--max-total-output-bytes <bytes>", "maximum aggregate generated HTML bytes").option("--allow-large-build", "disable default byte budgets for a trusted bulk build").action(async (opts) => {
   try {
     const result = await runBuild({
       input: opts.input,
       output: opts.output,
       theme: opts.theme,
+      ignoreWorkspaceSettings: opts.ignoreWorkspaceSettings,
       maxInputBytes: parseOptionalByteLimit("--max-input-bytes", opts.maxInputBytes),
       maxTotalInputBytes: parseOptionalByteLimit(
         "--max-total-input-bytes",
@@ -6472,7 +7049,7 @@ async function listMarkdownFiles(root, limits) {
       if (entryCount > limits.maxEntries) {
         throw new Error(`Build traversal exceeded ${limits.maxEntries} filesystem entries.`);
       }
-      const absolutePath = path4.join(current.directory, entry.name);
+      const absolutePath = path5.join(current.directory, entry.name);
       if (entry.isDirectory()) {
         if (current.depth >= limits.maxDepth) {
           throw new Error(`Build traversal exceeded a depth of ${limits.maxDepth}.`);
@@ -6492,7 +7069,7 @@ function replaceMarkdownExtension(filePath) {
   return filePath.replace(/\.(md|markdown)$/i, ".html");
 }
 function titleFromPath(filePath) {
-  const baseName = path4.basename(filePath).replace(/\.(md|markdown)$/i, "");
+  const baseName = path5.basename(filePath).replace(/\.(md|markdown)$/i, "");
   return baseName || "DocBlocks Document";
 }
 
@@ -6501,11 +7078,11 @@ import { Command as Command2 } from "commander";
 import { createServer } from "http";
 import { realpath as realpath2, stat as stat3 } from "fs/promises";
 import { isIP } from "net";
-import path6 from "path";
+import path7 from "path";
 init_contained_file();
 
 // src/preview-policy.ts
-import path5 from "path";
+import path6 from "path";
 var PREVIEW_FILE_EXTENSIONS = /* @__PURE__ */ new Set([
   ".css",
   ".gif",
@@ -6551,14 +7128,14 @@ var SENSITIVE_FILE_NAMES = /* @__PURE__ */ new Set([
   "id_rsa"
 ]);
 function isAllowedPreviewPath(rootPath, requestedPath, physicalPath, purpose) {
-  const root = path5.resolve(rootPath);
-  const requested = path5.resolve(requestedPath);
-  const physical = path5.resolve(physicalPath);
+  const root = path6.resolve(rootPath);
+  const requested = path6.resolve(requestedPath);
+  const physical = path6.resolve(physicalPath);
   for (const candidate of /* @__PURE__ */ new Set([requested, physical])) {
-    const relative = path5.relative(root, candidate);
+    const relative = path6.relative(root, candidate);
     if (!isContainedRelativePath(relative) || containsSensitiveSegment(relative)) return false;
     if (purpose !== "directory") {
-      const extension = path5.extname(path5.basename(candidate)).toLowerCase();
+      const extension = path6.extname(path6.basename(candidate)).toLowerCase();
       const allowedExtensions = purpose === "embedded-image" ? EMBEDDED_IMAGE_EXTENSIONS : PREVIEW_FILE_EXTENSIONS;
       if (!allowedExtensions.has(extension)) return false;
     }
@@ -6568,15 +7145,15 @@ function isAllowedPreviewPath(rootPath, requestedPath, physicalPath, purpose) {
 function containsSensitiveSegment(relativePath) {
   return relativePath.split(/[\\/]+/).filter(Boolean).some((segment) => {
     const lower = segment.toLowerCase();
-    return lower.startsWith(".") || SENSITIVE_FILE_NAMES.has(lower) || SENSITIVE_FILE_EXTENSIONS.has(path5.extname(lower));
+    return lower.startsWith(".") || SENSITIVE_FILE_NAMES.has(lower) || SENSITIVE_FILE_EXTENSIONS.has(path6.extname(lower));
   });
 }
 function isContainedRelativePath(relativePath) {
-  return relativePath === "" || !relativePath.startsWith(`..${path5.sep}`) && relativePath !== ".." && !path5.isAbsolute(relativePath);
+  return relativePath === "" || !relativePath.startsWith(`..${path6.sep}`) && relativePath !== ".." && !path6.isAbsolute(relativePath);
 }
 
 // src/commands/serve.ts
-import { decodeUtf8Text as decodeUtf8Text2 } from "@bendyline/docblocks/filesystem";
+import { decodeUtf8Text as decodeUtf8Text3 } from "@bendyline/docblocks/filesystem";
 init_node_error();
 var DEFAULT_HOST = "127.0.0.1";
 var DEFAULT_MAX_FILE_BYTES = 50 * 1024 * 1024;
@@ -6584,7 +7161,7 @@ var DEFAULT_MAX_CONCURRENT_READS = 16;
 var MAX_ALLOWED_HOSTS = 32;
 async function startPreviewServer(opts) {
   await assertKnownThemeId(opts.theme);
-  const requestedRoot = path6.resolve(opts.dir);
+  const requestedRoot = path7.resolve(opts.dir);
   let root;
   try {
     root = await realpath2(requestedRoot);
@@ -6595,6 +7172,8 @@ async function startPreviewServer(opts) {
   const rootStat = await stat3(root);
   if (!rootStat.isDirectory()) throw new Error(`Preview root is not a directory: ${root}`);
   const host = validateHost(opts.host ?? DEFAULT_HOST, opts.allowNetwork === true);
+  const warn = opts.onWarning ?? ((message) => console.warn(message));
+  const themeFallback = opts.theme || opts.ignoreWorkspaceSettings ? null : await createWorkspaceThemeFallback(root, warn);
   const allowedHosts = validateAllowedHosts(opts.allowedHosts ?? []);
   const maxFileBytes = positiveLimit(
     opts.maxFileBytes,
@@ -6624,7 +7203,7 @@ async function startPreviewServer(opts) {
       return;
     }
     activeRequests += 1;
-    handlePreviewRequest(req, res, root, opts.theme, maxFileBytes).catch((error) => {
+    handlePreviewRequest(req, res, root, { themeId: opts.theme, themeFallback, warn }, maxFileBytes).catch((error) => {
       reportPreviewFailure(req, error);
       if (!res.headersSent) sendText(res, 500, "Internal server error", req.method === "HEAD");
       else res.end();
@@ -6643,13 +7222,17 @@ async function startPreviewServer(opts) {
   const port = typeof address === "object" && address ? address.port : opts.port;
   return { server, root, host, url: `http://${urlHost(host)}:${port}/` };
 }
-var serveCommand = new Command2("serve").description("Start a local dev server for previewing markdown files").option("-p, --port <port>", "port to listen on", "3000").option("-d, --dir <dir>", "directory to serve", ".").option("-t, --theme <id>", "Squisq theme ID to apply").option("--host <host>", "interface to bind (loopback by default)", DEFAULT_HOST).option("--allow-network", "allow a non-loopback --host").option("--allow-host <host...>", "additional Host header names this server answers to").action(
+var serveCommand = new Command2("serve").description("Start a local dev server for previewing markdown files").option("-p, --port <port>", "port to listen on", "3000").option("-d, --dir <dir>", "directory to serve", ".").option("-t, --theme <id>", "Squisq theme ID to apply").option(
+  "--ignore-workspace-settings",
+  "do not apply the default theme from <dir>/.docblocks/workspace.json"
+).option("--host <host>", "interface to bind (loopback by default)", DEFAULT_HOST).option("--allow-network", "allow a non-loopback --host").option("--allow-host <host...>", "additional Host header names this server answers to").action(
   async (opts) => {
     try {
       const server = await startPreviewServer({
         port: parsePort(opts.port),
         dir: opts.dir,
         theme: opts.theme,
+        ignoreWorkspaceSettings: opts.ignoreWorkspaceSettings,
         host: opts.host,
         allowNetwork: opts.allowNetwork,
         allowedHosts: opts.allowHost
@@ -6662,7 +7245,7 @@ var serveCommand = new Command2("serve").description("Start a local dev server f
     }
   }
 );
-async function handlePreviewRequest(req, res, root, themeId, maxFileBytes) {
+async function handlePreviewRequest(req, res, root, render, maxFileBytes) {
   if (req.method !== "GET" && req.method !== "HEAD") {
     sendText(res, 405, "Method not allowed");
     return;
@@ -6686,16 +7269,18 @@ async function handlePreviewRequest(req, res, root, themeId, maxFileBytes) {
     return;
   }
   if (target.markdown) {
-    const markdown = decodeUtf8Text2(await readContainedFile(root, target.filePath, maxFileBytes), {
+    const markdown = decodeUtf8Text3(await readContainedFile(root, target.filePath, maxFileBytes), {
       label: "Preview document",
       path: target.filePath
     });
     const html = await renderMarkdownHtml(markdown, {
-      title: path6.basename(target.filePath).replace(/\.(md|markdown)$/i, ""),
+      title: path7.basename(target.filePath).replace(/\.(md|markdown)$/i, ""),
       sourcePath: target.filePath,
       assetRoot: root,
-      themeId,
+      themeId: render.themeId,
+      fallbackThemeId: render.themeFallback ? await render.themeFallback.resolve() : void 0,
       mode: "static",
+      onWarning: render.warn,
       allowReferencedAsset: ({ assetRoot, requestedPath, physicalPath }) => isAllowedPreviewPath(assetRoot, requestedPath, physicalPath, "embedded-image")
     });
     sendBody(res, 200, html, "text/html; charset=utf-8", headOnly);
@@ -6708,7 +7293,7 @@ async function resolveServeTarget(root, requestUrl, maxFileBytes = DEFAULT_MAX_F
   if (requestUrl.length > 8192 || requestUrl.includes("\0")) return { kind: "bad-request" };
   let physicalRoot;
   try {
-    physicalRoot = await realpath2(path6.resolve(root));
+    physicalRoot = await realpath2(path7.resolve(root));
   } catch (error) {
     if (isMissingPathError2(error)) return { kind: "missing" };
     if (isPermissionError(error)) return { kind: "forbidden" };
@@ -6717,7 +7302,7 @@ async function resolveServeTarget(root, requestUrl, maxFileBytes = DEFAULT_MAX_F
   const decodedPath = decodeRequestPath(requestUrl);
   if (!decodedPath) return { kind: "bad-request" };
   const requestedPath = decodedPath.replace(/^\/+/, "");
-  const candidate = path6.resolve(physicalRoot, requestedPath);
+  const candidate = path7.resolve(physicalRoot, requestedPath);
   if (!isAllowedPreviewPath(physicalRoot, candidate, candidate, "directory")) {
     return { kind: "forbidden" };
   }
@@ -6777,7 +7362,7 @@ async function inspectTarget(root, candidate, maxFileBytes) {
 }
 async function directoryIndexTarget(root, dirPath, maxFileBytes) {
   for (const fileName of ["index.html", "index.htm", "index.md", "index.markdown"]) {
-    const target = await inspectTarget(root, path6.join(dirPath, fileName), maxFileBytes);
+    const target = await inspectTarget(root, path7.join(dirPath, fileName), maxFileBytes);
     if (target.kind === "file" || target.kind === "forbidden" || target.kind === "too-large") {
       return target;
     }
@@ -6912,7 +7497,7 @@ function urlHost(host) {
   return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
 }
 function contentTypeFor(filePath) {
-  const ext = path6.extname(filePath).toLowerCase();
+  const ext = path7.extname(filePath).toLowerCase();
   switch (ext) {
     case ".html":
     case ".htm":
@@ -6979,8 +7564,8 @@ import {
   rm,
   stat as stat4
 } from "fs/promises";
-import { randomUUID } from "crypto";
-import { dirname, basename, extname, join, resolve } from "path";
+import { randomUUID as randomUUID2 } from "crypto";
+import { dirname, basename as basename2, extname, join, resolve } from "path";
 import { Command as Command3 } from "commander";
 init_link_support();
 init_node_error();
@@ -7057,7 +7642,7 @@ async function runConvert(inputPath, opts) {
   throwIfAborted2(opts.signal);
   const resolvedInput = resolve(inputPath);
   const outputDir = opts.outputDir ? resolve(opts.outputDir) : dirname(resolvedInput);
-  const inputBasename = basename(resolvedInput);
+  const inputBasename = basename2(resolvedInput);
   const inputExt = extname(inputBasename);
   const baseName = inputExt ? inputBasename.slice(0, -inputExt.length) : inputBasename;
   const maxInputBytes = positiveLimit(
@@ -7199,7 +7784,7 @@ async function runConvert(inputPath, opts) {
     if (totalOutputBytes > maxTotalOutputBytes) {
       throw new Error(`Conversion outputs exceed the ${maxTotalOutputBytes}-byte aggregate limit.`);
     }
-    const suggestedFilename = basename(conversion.suggestedFilename);
+    const suggestedFilename = basename2(conversion.suggestedFilename);
     const outPath = join(outputDir, suggestedFilename);
     const outputPathKey = process.platform === "win32" ? outPath.toLowerCase() : outPath;
     if (outputPathKeys.has(outputPathKey)) {
@@ -7315,7 +7900,7 @@ async function publishConversionBatch(outputs, outputDir, allowOverwrite, signal
       throwIfAborted2(signal);
       const output = outputs[index];
       if (!output) continue;
-      const stagedPath = join(stagingDirectory, `${index}-${randomUUID()}.stage`);
+      const stagedPath = join(stagingDirectory, `${index}-${randomUUID2()}.stage`);
       await writePrivateFile(stagedPath, output.bytes);
       stagedOutputs.push({ outputPath: output.path, stagedPath, bytes: output.bytes });
     }
@@ -7345,7 +7930,7 @@ async function publishConversionBatch(outputs, outputDir, allowOverwrite, signal
             throw new Error(`Refusing to replace a non-file destination: ${output.outputPath}`);
           }
           if (existing) {
-            state.backupPath = join(stagingDirectory, `${index}-${randomUUID()}.backup`);
+            state.backupPath = join(stagingDirectory, `${index}-${randomUUID2()}.backup`);
             await rename(output.outputPath, state.backupPath);
           }
           await rename(output.stagedPath, output.outputPath);
@@ -7373,8 +7958,8 @@ async function publishConversionBatch(outputs, outputDir, allowOverwrite, signal
     }
   }
 }
-async function writePrivateFile(path9, bytes) {
-  const handle = await open2(path9, "wx", 384);
+async function writePrivateFile(path10, bytes) {
+  const handle = await open2(path10, "wx", 384);
   try {
     await handle.writeFile(bytes);
     await handle.sync();
@@ -7433,9 +8018,9 @@ async function assertReplaceableOutputs(outputPaths) {
     }
   }
 }
-async function lstatIfPresent(path9) {
+async function lstatIfPresent(path10) {
   try {
-    return await lstat(path9);
+    return await lstat(path10);
   } catch (error) {
     if (isNodeErrorCode(error, ["ENOENT", "ENOTDIR"])) return null;
     throw error;
@@ -7454,11 +8039,11 @@ function throwIfAborted2(signal) {
 }
 async function applyTransformToMarkdown(markdownDoc, container, transformStyle, themeId) {
   const { markdownToDoc: markdownToDoc3, docToMarkdown } = await import("@bendyline/squisq/doc");
-  const { readFrontmatterThemeId } = await import("@bendyline/squisq/markdown");
+  const { readFrontmatterThemeId: readFrontmatterThemeId2 } = await import("@bendyline/squisq/markdown");
   const { applyTransform, extractDocImages } = await import("@bendyline/squisq/transform");
   const doc = markdownToDoc3(markdownDoc);
   const images = extractDocImages(doc.blocks);
-  const effectiveTheme = themeId ?? readFrontmatterThemeId(markdownDoc.frontmatter);
+  const effectiveTheme = themeId ?? readFrontmatterThemeId2(markdownDoc.frontmatter);
   const result = applyTransform(doc, transformStyle, { themeId: effectiveTheme, images });
   const projected = projectTransformOntoMarkdownSource(doc, result.doc);
   const transformedMarkdown = docToMarkdown(projected);
@@ -7649,7 +8234,7 @@ function isConversionErrorMetadata(error) {
 // src/commands/video.ts
 init_cancellation();
 import { lstat as lstat2, mkdir as mkdir3 } from "fs/promises";
-import { dirname as dirname2, basename as basename2, extname as extname2, resolve as resolve2 } from "path";
+import { dirname as dirname2, basename as basename3, extname as extname2, resolve as resolve2 } from "path";
 import { Command as Command4 } from "commander";
 import {
   resolveDimensions,
@@ -7691,7 +8276,7 @@ async function runVideo(inputPath, opts, onProgress, dependencies = {}) {
     width: opts.width,
     height: opts.height
   });
-  const inputBasename = basename2(resolvedInput);
+  const inputBasename = basename3(resolvedInput);
   const inputExt = extname2(inputBasename);
   const baseName = inputExt ? inputBasename.slice(0, -inputExt.length) : inputBasename;
   const outputPath = opts.output ? resolve2(opts.output) : resolve2(dirname2(resolvedInput), `${baseName}.mp4`);
@@ -7982,7 +8567,7 @@ var transformsCommand = new Command7("transforms").description("List all availab
 import { open as open5 } from "fs/promises";
 import { resolve as resolve3 } from "path";
 import { Command as Command8 } from "commander";
-import { decodeUtf8Text as decodeUtf8Text4 } from "@bendyline/docblocks/filesystem";
+import { decodeUtf8Text as decodeUtf8Text5 } from "@bendyline/docblocks/filesystem";
 init_node_error();
 var DEFAULT_MAX_PARSE_INPUT_BYTES = 20 * 1024 * 1024;
 var DEFAULT_MAX_PARSE_OUTPUT_BYTES = 128 * 1024 * 1024;
@@ -7999,7 +8584,7 @@ async function runParse(inputPath, options = {}) {
     "parse output byte"
   );
   const bytes = await readBoundedFile(resolvedInput, maxInputBytes);
-  const content = decodeUtf8Text4(bytes, { label: "Parse input", path: resolvedInput });
+  const content = decodeUtf8Text5(bytes, { label: "Parse input", path: resolvedInput });
   const { parseMarkdown: parseMarkdown2 } = await import("@bendyline/squisq/markdown");
   const markdownDoc = parseMarkdown2(content);
   const stats = {
@@ -8062,9 +8647,95 @@ var parseCommand = new Command8("parse").description("Parse a markdown file and
   }
 });
 
+// src/commands/workspace.ts
+import { Command as Command9 } from "commander";
+import { FsError as FsError2 } from "@bendyline/docblocks/filesystem";
+import {
+  WORKSPACE_SETTINGS_PATH as WORKSPACE_SETTINGS_PATH2,
+  refreshWorkspaceOutputs,
+  resolveCatalogOutputs
+} from "@bendyline/docblocks/workspace-settings";
+import { htmlToMarkdownDocSync, markdownDocToPlainHtml } from "@bendyline/squisq-formats/html";
+async function runWorkspaceRefresh(options = {}) {
+  const io = await createNodeWorkspaceIO(options.dir ?? ".");
+  const dryRun = options.dryRun === true;
+  const settingsRead = await readWorkspaceSettings(io);
+  if (settingsRead.status === "missing") {
+    return { root: io.root, status: "missing", documentCount: 0, outputs: [], dryRun };
+  }
+  if (settingsRead.status !== "ok") {
+    throw new Error(describeWorkspaceSettingsProblem(settingsRead.message));
+  }
+  const settings = settingsRead.settings;
+  const resolved = resolveCatalogOutputs(settings);
+  if (!resolved) {
+    return { root: io.root, status: "disabled", documentCount: 0, outputs: [], dryRun };
+  }
+  const warn = options.onWarning ?? ((message) => console.warn(message));
+  const catalogThemeId = resolved.html?.themeId;
+  if (catalogThemeId && !(await getAvailableThemeIds()).includes(catalogThemeId)) {
+    warn(
+      `Catalog theme "${catalogThemeId}" from ${WORKSPACE_SETTINGS_PATH2} is not a known theme; the page renders with the standard theme.`
+    );
+  }
+  const refresh = () => refreshWorkspaceOutputs(io, settings, renderer, {
+    signal: options.signal,
+    force: options.force === true,
+    dryRun,
+    limits: options.limits
+  });
+  let result;
+  try {
+    result = await refresh();
+  } catch (error) {
+    if (!(error instanceof FsError2) || error.code !== "conflict") throw error;
+    result = await refresh();
+  }
+  return {
+    root: io.root,
+    status: "refreshed",
+    documentCount: result.documentCount,
+    outputs: result.outputs,
+    dryRun
+  };
+}
+var renderer = {
+  renderCatalogHtml: (document2, { title, themeId }) => markdownDocToPlainHtml(document2, { title, themeId }),
+  importHtml: (html) => htmlToMarkdownDocSync(html)
+};
+function describeWorkspaceOutput(output) {
+  const status = output.status === "would-write" ? "would write" : output.status;
+  return output.message ? `${status} ${output.path}: ${output.message}` : `${status} ${output.path}`;
+}
+var refreshCommand = new Command9("refresh").description(`Regenerate the catalog outputs enabled in <dir>/${WORKSPACE_SETTINGS_PATH2}`).argument("[dir]", "workspace root", ".").option("--force", "rewrite the catalog page even when its inputs are unchanged").option("--dry-run", "report what would change without writing anything").action(async (dir, opts) => {
+  try {
+    const result = await runWorkspaceRefresh({ dir, force: opts.force, dryRun: opts.dryRun });
+    if (result.status === "missing") {
+      console.error(
+        `No workspace settings found at ${WORKSPACE_SETTINGS_PATH2} in ${result.root}; no outputs are enabled.`
+      );
+      return;
+    }
+    if (result.status === "disabled") {
+      console.error(`${WORKSPACE_SETTINGS_PATH2} enables no catalog outputs; nothing to refresh.`);
+      return;
+    }
+    for (const output of result.outputs) console.error(describeWorkspaceOutput(output));
+    console.error(
+      `${result.dryRun ? "Dry run: " : ""}${result.documentCount} document(s) cataloged in ${result.root}.`
+    );
+    if (result.outputs.some((output) => output.status === "blocked")) process.exitCode = 1;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`Error: ${message}`);
+    process.exitCode = 1;
+  }
+});
+var workspaceCommand = new Command9("workspace").description(`Maintain workspace outputs configured in ${WORKSPACE_SETTINGS_PATH2}`).addCommand(refreshCommand);
+
 // src/program.ts
 init_version();
-var program = new Command9().name("docblocks").description("Build, preview, convert, render, inspect, and automate documents").version(getPackageVersion()).addCommand(buildCommand).addCommand(serveCommand).addCommand(convertCommand).addCommand(videoCommand).addCommand(mcpCommand).addCommand(themesCommand).addCommand(transformsCommand).addCommand(parseCommand);
+var program = new Command10().name("docblocks").description("Build, preview, convert, render, inspect, and automate documents").version(getPackageVersion()).addCommand(buildCommand).addCommand(serveCommand).addCommand(convertCommand).addCommand(videoCommand).addCommand(mcpCommand).addCommand(themesCommand).addCommand(transformsCommand).addCommand(parseCommand).addCommand(workspaceCommand);
 
 // src/bin.ts
 program.parseAsync().catch((error) => {