stego-cli 0.3.3 → 0.4.0

package/dist/stego-cli.js

@@ -8,8 +8,12 @@ import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { markdownExporter } from "./exporters/markdown-exporter.js";
 import { createPandocExporter } from "./exporters/pandoc-exporter.js";
+import { parseCommentAppendix } from "./comments/comment-domain.js";
 import { runCommentsCommand } from "./comments/comments-command.js";
 import { CommentsCommandError } from "./comments/errors.js";
+import { runMetadataCommand } from "./metadata/metadata-command.js";
+import { runSpineCommand } from "./spine/spine-command.js";
+import { readSpineCatalog } from "./spine/spine-domain.js";
 const STATUS_RANK = {
     draft: 0,
     revise: 1,
@@ -110,6 +114,12 @@ let config;
 void main();
 async function main() {
     const { command, options } = parseArgs(process.argv.slice(2));
+    if (command === "version" || command === "--version" || command === "-v") {
+        const cliPackage = readJson(path.join(packageRoot, "package.json"));
+        const version = typeof cliPackage.version === "string" ? cliPackage.version : "0.0.0";
+        console.log(version);
+        return;
+    }
     if (!command || command === "help" || command === "--help" || command === "-h") {
         printUsage();
         return;
@@ -125,13 +135,31 @@ async function main() {
                 return;
             case "new-project":
                 activateWorkspace(options);
-                await createProject(readStringOption(options, "project"), readStringOption(options, "title"));
+                await createProject({
+                    projectId: readStringOption(options, "project"),
+                    title: readStringOption(options, "title"),
+                    proseFont: readStringOption(options, "prose-font"),
+                    outputFormat: readStringOption(options, "format")
+                });
                 return;
             case "new": {
                 activateWorkspace(options);
                 const project = resolveProject(readStringOption(options, "project"));
                 const createdPath = createNewManuscript(project, readStringOption(options, "i"), readStringOption(options, "filename"));
-                logLine(`Created manuscript: ${createdPath}`);
+                const outputFormat = parseTextOrJsonFormat(readStringOption(options, "format"));
+                if (outputFormat === "json") {
+                    process.stdout.write(`${JSON.stringify({
+                        ok: true,
+                        operation: "new",
+                        result: {
+                            projectId: project.id,
+                            filePath: createdPath
+                        }
+                    }, null, 2)}\n`);
+                }
+                else {
+                    logLine(`Created manuscript: ${createdPath}`);
+                }
                 return;
             }
             case "validate": {
@@ -201,6 +229,20 @@ async function main() {
             case "comments":
                 await runCommentsCommand(options, process.cwd());
                 return;
+            case "metadata":
+                await runMetadataCommand(options, process.cwd());
+                return;
+            case "spine": {
+                activateWorkspace(options);
+                const project = resolveProject(readStringOption(options, "project"));
+                runSpineCommand(options, {
+                    id: project.id,
+                    root: project.root,
+                    spineDir: project.spineDir,
+                    meta: project.meta
+                });
+                return;
+            }
             default:
                 throw new Error(`Unknown command '${command}'. Run with 'help' for usage.`);
         }
@@ -231,6 +273,28 @@ function readStringOption(options, key) {
 function readBooleanOption(options, key) {
     return options[key] === true;
 }
+function parseTextOrJsonFormat(raw) {
+    if (!raw || raw === "text") {
+        return "text";
+    }
+    if (raw === "json") {
+        return "json";
+    }
+    throw new Error("Invalid --format value. Use 'text' or 'json'.");
+}
+function parseProseFontMode(raw) {
+    const normalized = (raw || "prompt").trim().toLowerCase();
+    if (normalized === "yes" || normalized === "true" || normalized === "y") {
+        return "yes";
+    }
+    if (normalized === "no" || normalized === "false" || normalized === "n") {
+        return "no";
+    }
+    if (normalized === "prompt" || normalized === "ask") {
+        return "prompt";
+    }
+    throw new Error("Invalid --prose-font value. Use 'yes', 'no', or 'prompt'.");
+}
 function activateWorkspace(options) {
     const workspace = resolveWorkspaceContext(readStringOption(options, "root"));
     repoRoot = workspace.repoRoot;
@@ -243,75 +307,6 @@ function isStageName(value) {
 function isExportFormat(value) {
     return value === "md" || value === "docx" || value === "pdf" || value === "epub";
 }
-function resolveSpineSchema(project) {
-    const issues = [];
-    const projectFile = path.relative(repoRoot, path.join(project.root, "stego-project.json"));
-    const rawCategories = project.meta.spineCategories;
-    if (rawCategories == null) {
-        return { schema: { categories: [], inlineIdRegex: null }, issues };
-    }
-    if (!Array.isArray(rawCategories)) {
-        issues.push(makeIssue("error", "metadata", "Project 'spineCategories' must be an array when defined.", projectFile));
-        return { schema: { categories: [], inlineIdRegex: null }, issues };
-    }
-    const categories = [];
-    const keySet = new Set();
-    const prefixSet = new Set();
-    const notesSet = new Set();
-    for (const [index, categoryEntry] of rawCategories.entries()) {
-        if (!isPlainObject(categoryEntry)) {
-            issues.push(makeIssue("error", "metadata", `Invalid spineCategories entry at index ${index}. Expected object with key, prefix, notesFile.`, projectFile));
-            continue;
-        }
-        const key = typeof categoryEntry.key === "string" ? categoryEntry.key.trim() : "";
-        const prefix = typeof categoryEntry.prefix === "string" ? categoryEntry.prefix.trim() : "";
-        const notesFile = typeof categoryEntry.notesFile === "string" ? categoryEntry.notesFile.trim() : "";
-        if (!/^[a-z][a-z0-9_-]*$/.test(key)) {
-            issues.push(makeIssue("error", "metadata", `Invalid spine category key '${key || "<empty>"}'. Use lowercase key names like 'cast' or 'incidents'.`, projectFile));
-            continue;
-        }
-        if (!/^[A-Z][A-Z0-9-]*$/.test(prefix)) {
-            issues.push(makeIssue("error", "metadata", `Invalid spine category prefix '${prefix || "<empty>"}'. Use uppercase prefixes like 'CHAR' or 'STATUTE'.`, projectFile));
-            continue;
-        }
-        if (prefix.toUpperCase() === RESERVED_COMMENT_PREFIX) {
-            issues.push(makeIssue("error", "metadata", `Invalid spine category prefix '${prefix}'. '${RESERVED_COMMENT_PREFIX}' is reserved for Stego comment IDs (e.g. CMT-0001).`, projectFile));
-            continue;
-        }
-        if (!/^[A-Za-z0-9._-]+\.md$/.test(notesFile)) {
-            issues.push(makeIssue("error", "metadata", `Invalid notesFile '${notesFile || "<empty>"}'. Use markdown filenames like 'characters.md' (resolved in spine/).`, projectFile));
-            continue;
-        }
-        if (keySet.has(key)) {
-            issues.push(makeIssue("error", "metadata", `Duplicate spine category key '${key}'.`, projectFile));
-            continue;
-        }
-        if (prefixSet.has(prefix)) {
-            issues.push(makeIssue("error", "metadata", `Duplicate spine category prefix '${prefix}'.`, projectFile));
-            continue;
-        }
-        if (notesSet.has(notesFile)) {
-            issues.push(makeIssue("error", "metadata", `Duplicate spine category notesFile '${notesFile}'.`, projectFile));
-            continue;
-        }
-        keySet.add(key);
-        prefixSet.add(prefix);
-        notesSet.add(notesFile);
-        categories.push({
-            key,
-            prefix,
-            notesFile,
-            idPattern: new RegExp(`^${escapeRegex(prefix)}-[A-Z0-9-]+$`)
-        });
-    }
-    return {
-        schema: {
-            categories,
-            inlineIdRegex: buildInlineIdRegex(categories)
-        },
-        issues
-    };
-}
 function resolveRequiredMetadata(project, runtimeConfig) {
     const issues = [];
     const projectFile = path.relative(repoRoot, path.join(project.root, "stego-project.json"));
@@ -405,16 +400,6 @@ function resolveCompileStructure(project) {
     }
     return { levels, issues };
 }
-function buildInlineIdRegex(categories) {
-    if (categories.length === 0) {
-        return null;
-    }
-    const prefixes = categories.map((category) => escapeRegex(category.prefix)).join("|");
-    return new RegExp(`\\b(?:${prefixes})-[A-Z0-9-]+\\b`, "g");
-}
-function escapeRegex(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -752,6 +737,8 @@ function writeInitRootPackageJson(targetRoot) {
             "list-projects": "stego list-projects",
             "new-project": "stego new-project",
             new: "stego new",
+            spine: "stego spine",
+            metadata: "stego metadata",
             lint: "stego lint",
             validate: "stego validate",
             build: "stego build",
@@ -767,7 +754,7 @@ function writeInitRootPackageJson(targetRoot) {
     fs.writeFileSync(path.join(targetRoot, "package.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
 }
 function printUsage() {
-    console.log(`Stego CLI\n\nCommands:\n  init [--force]\n  list-projects [--root <path>]\n  new-project --project <project-id> [--title <title>] [--root <path>]\n  new --project <project-id> [--i <prefix>|-i <prefix>] [--root <path>]\n  validate --project <project-id> [--file <project-relative-manuscript-path>] [--root <path>]\n  build --project <project-id> [--root <path>]\n  check-stage --project <project-id> --stage <draft|revise|line-edit|proof|final> [--file <project-relative-manuscript-path>] [--root <path>]\n  lint --project <project-id> [--manuscript|--spine] [--root <path>]\n  export --project <project-id> --format <md|docx|pdf|epub> [--output <path>] [--root <path>]\n  comments add <manuscript> [--message <text> | --input <path|->] [--author <name>] [--start-line <n> --start-col <n> --end-line <n> --end-col <n>] [--format <text|json>]\n`);
+    console.log(`Stego CLI\n\nCommands:\n  init [--force]\n  list-projects [--root <path>]\n  new-project --project <project-id> [--title <title>] [--prose-font <yes|no|prompt>] [--format <text|json>] [--root <path>]\n  new --project <project-id> [--i <prefix>|-i <prefix>] [--filename <name>] [--format <text|json>] [--root <path>]\n  validate --project <project-id> [--file <project-relative-manuscript-path>] [--root <path>]\n  build --project <project-id> [--root <path>]\n  check-stage --project <project-id> --stage <draft|revise|line-edit|proof|final> [--file <project-relative-manuscript-path>] [--root <path>]\n  lint --project <project-id> [--manuscript|--spine] [--root <path>]\n  export --project <project-id> --format <md|docx|pdf|epub> [--output <path>] [--root <path>]\n  spine read --project <project-id> [--format <text|json>] [--root <path>]\n  spine new-category --project <project-id> --key <category> [--label <label>] [--require-metadata] [--format <text|json>] [--root <path>]\n  spine new --project <project-id> --category <category> [--filename <relative-path>] [--format <text|json>] [--root <path>]\n  metadata read <markdown-path> [--format <text|json>]\n  metadata apply <markdown-path> --input <path|-> [--format <text|json>]\n  comments read <manuscript> [--format <text|json>]\n  comments add <manuscript> [--message <text> | --input <path|->] [--author <name>] [--start-line <n> --start-col <n> --end-line <n> --end-col <n>] [--cursor-line <n>] [--format <text|json>]\n  comments reply <manuscript> --comment-id <CMT-####> [--message <text> | --input <path|->] [--author <name>] [--format <text|json>]\n  comments set-status <manuscript> --comment-id <CMT-####> --status <open|resolved> [--thread] [--format <text|json>]\n  comments delete <manuscript> --comment-id <CMT-####> [--format <text|json>]\n  comments clear-resolved <manuscript> [--format <text|json>]\n  comments sync-anchors <manuscript> --input <path|-> [--format <text|json>]\n`);
 }
 function listProjects() {
     const ids = getProjectIds();
@@ -780,8 +767,8 @@ function listProjects() {
         console.log(`- ${id}`);
     }
 }
-async function createProject(projectIdOption, titleOption) {
-    const projectId = (projectIdOption || "").trim();
+async function createProject(options) {
+    const projectId = (options.projectId || "").trim();
     if (!projectId) {
         throw new Error("Project id is required. Use --project <project-id>.");
     }
@@ -801,7 +788,7 @@ async function createProject(projectIdOption, titleOption) {
     const manuscriptDir = path.join(projectRoot, config.chapterDir);
     const projectJson = {
         id: projectId,
-        title: titleOption?.trim() || toDisplayTitle(projectId),
+        title: options.title?.trim() || toDisplayTitle(projectId),
         requiredMetadata: ["status"],
         compileStructure: {
             levels: [
@@ -814,14 +801,7 @@ async function createProject(projectIdOption, titleOption) {
                     pageBreak: "between-groups"
                 }
             ]
-        },
-        spineCategories: [
-            {
-                key: "characters",
-                prefix: "CHAR",
-                notesFile: "characters.md"
-            }
-        ]
+        }
     };
     const projectJsonPath = path.join(projectRoot, "stego-project.json");
     fs.writeFileSync(projectJsonPath, `${JSON.stringify(projectJson, null, 2)}\n`, "utf8");
@@ -830,6 +810,8 @@ async function createProject(projectIdOption, titleOption) {
         private: true,
         scripts: {
             new: "npx --no-install stego new",
+            "spine:new": "npx --no-install stego spine new",
+            "spine:new-category": "npx --no-install stego spine new-category",
             lint: "npx --no-install stego lint",
             validate: "npx --no-install stego validate",
             build: "npx --no-install stego build",
@@ -850,20 +832,57 @@ chapter_title: Hello World
 
 Start writing here.
 `, "utf8");
-    const charactersNotesPath = path.join(spineDir, "characters.md");
-    fs.writeFileSync(charactersNotesPath, "# Characters\n\n", "utf8");
+    const charactersDir = path.join(spineDir, "characters");
+    fs.mkdirSync(charactersDir, { recursive: true });
+    const charactersCategoryPath = path.join(charactersDir, "_category.md");
+    fs.writeFileSync(charactersCategoryPath, `---
+label: Characters
+---
+
+# Characters
+
+`, "utf8");
+    const charactersEntryPath = path.join(charactersDir, "example-character.md");
+    fs.writeFileSync(charactersEntryPath, `# Example Character
+
+`, "utf8");
     const projectExtensionsPath = path.join(projectRoot, ".vscode", "extensions.json");
     ensureProjectExtensionsRecommendations(projectRoot);
     let projectSettingsPath = null;
-    const enableProseFont = await promptYesNo(PROSE_FONT_PROMPT, true);
+    const proseFontMode = parseProseFontMode(options.proseFont);
+    const enableProseFont = proseFontMode === "prompt"
+        ? await promptYesNo(PROSE_FONT_PROMPT, true)
+        : proseFontMode === "yes";
     if (enableProseFont) {
         projectSettingsPath = writeProseEditorSettingsForProject(projectRoot);
     }
+    const outputFormat = parseTextOrJsonFormat(options.outputFormat);
+    if (outputFormat === "json") {
+        process.stdout.write(`${JSON.stringify({
+            ok: true,
+            operation: "new-project",
+            result: {
+                projectId,
+                projectPath: path.relative(repoRoot, projectRoot),
+                files: [
+                    path.relative(repoRoot, projectJsonPath),
+                    path.relative(repoRoot, projectPackagePath),
+                    path.relative(repoRoot, starterManuscriptPath),
+                    path.relative(repoRoot, charactersCategoryPath),
+                    path.relative(repoRoot, charactersEntryPath),
+                    path.relative(repoRoot, projectExtensionsPath),
+                    ...(projectSettingsPath ? [path.relative(repoRoot, projectSettingsPath)] : [])
+                ]
+            }
+        }, null, 2)}\n`);
+        return;
+    }
     logLine(`Created project: ${path.relative(repoRoot, projectRoot)}`);
     logLine(`- ${path.relative(repoRoot, projectJsonPath)}`);
     logLine(`- ${path.relative(repoRoot, projectPackagePath)}`);
     logLine(`- ${path.relative(repoRoot, starterManuscriptPath)}`);
-    logLine(`- ${path.relative(repoRoot, charactersNotesPath)}`);
+    logLine(`- ${path.relative(repoRoot, charactersCategoryPath)}`);
+    logLine(`- ${path.relative(repoRoot, charactersEntryPath)}`);
     logLine(`- ${path.relative(repoRoot, projectExtensionsPath)}`);
     if (projectSettingsPath) {
         logLine(`- ${path.relative(repoRoot, projectSettingsPath)}`);
@@ -1060,13 +1079,16 @@ function inferProjectIdFromCwd(cwd) {
 }
 function inspectProject(project, runtimeConfig, options = {}) {
     const issues = [];
-    const emptySpineState = { ids: new Set(), issues: [] };
-    const spineSchema = resolveSpineSchema(project);
+    const emptySpineState = { categories: [], entriesByCategory: new Map(), issues: [] };
     const requiredMetadataState = resolveRequiredMetadata(project, runtimeConfig);
     const compileStructureState = resolveCompileStructure(project);
-    issues.push(...spineSchema.issues);
     issues.push(...requiredMetadataState.issues);
     issues.push(...compileStructureState.issues);
+    if (project.meta.spineCategories !== undefined) {
+        issues.push(makeIssue("error", "metadata", "Legacy 'spineCategories' in stego-project.json is no longer supported. Use spine/ category directories and files.", path.relative(repoRoot, path.join(project.root, "stego-project.json"))));
+    }
+    const spineState = readSpine(project);
+    issues.push(...spineState.issues);
     let chapterFiles = [];
     const onlyFile = options.onlyFile?.trim();
     if (onlyFile) {
@@ -1106,7 +1128,7 @@ function inspectProject(project, runtimeConfig, options = {}) {
             return { chapters: [], issues, spineState: emptySpineState, compileStructureLevels: compileStructureState.levels };
         }
     }
-    const chapters = chapterFiles.map((chapterPath) => parseChapter(chapterPath, runtimeConfig, requiredMetadataState.requiredMetadata, spineSchema.schema.categories, spineSchema.schema.inlineIdRegex, compileStructureState.levels));
+    const chapters = chapterFiles.map((chapterPath) => parseChapter(chapterPath, runtimeConfig, requiredMetadataState.requiredMetadata, spineState.categories, compileStructureState.levels));
     for (const chapter of chapters) {
         issues.push(...chapter.issues);
     }
@@ -1133,10 +1155,8 @@ function inspectProject(project, runtimeConfig, options = {}) {
         }
         return a.order - b.order;
     });
-    const spineState = readSpine(project.spineDir, spineSchema.schema.categories, spineSchema.schema.inlineIdRegex);
-    issues.push(...spineState.issues);
     for (const chapter of chapters) {
-        issues.push(...findUnknownSpineIds(chapter.referenceIds, spineState.ids, chapter.relativePath));
+        issues.push(...findUnknownSpineReferences(chapter.referenceKeysByCategory, spineState.entriesByCategory, chapter.relativePath));
     }
     return {
         chapters,
@@ -1145,7 +1165,7 @@ function inspectProject(project, runtimeConfig, options = {}) {
         compileStructureLevels: compileStructureState.levels
     };
 }
-function parseChapter(chapterPath, runtimeConfig, requiredMetadata, spineCategories, inlineIdRegex, compileStructureLevels) {
+function parseChapter(chapterPath, runtimeConfig, requiredMetadata, spineCategories, compileStructureLevels) {
     const relativePath = path.relative(repoRoot, chapterPath);
     const raw = fs.readFileSync(chapterPath, "utf8");
     const { metadata, body, comments, issues } = parseMetadata(raw, chapterPath, false);
@@ -1174,9 +1194,8 @@ function parseChapter(chapterPath, runtimeConfig, requiredMetadata, spineCategor
             void normalizeGroupingValue(metadata[level.titleKey], relativePath, chapterIssues, level.titleKey);
         }
     }
-    const referenceValidation = extractReferenceIds(metadata, relativePath, spineCategories);
+    const referenceValidation = extractReferenceKeysByCategory(metadata, relativePath, spineCategories);
     chapterIssues.push(...referenceValidation.issues);
-    chapterIssues.push(...findInlineSpineIdMentions(body, relativePath, inlineIdRegex));
     chapterIssues.push(...validateMarkdownBody(body, chapterPath));
     return {
         path: chapterPath,
@@ -1184,7 +1203,7 @@ function parseChapter(chapterPath, runtimeConfig, requiredMetadata, spineCategor
         title,
         order,
         status,
-        referenceIds: referenceValidation.ids,
+        referenceKeysByCategory: referenceValidation.referencesByCategory,
         groupValues,
         metadata,
         body,
@@ -1227,49 +1246,39 @@ function parseOrderFromFilename(chapterPath, relativePath, issues) {
     }
     return Number(match[1]);
 }
-function extractReferenceIds(metadata, relativePath, spineCategories) {
+function extractReferenceKeysByCategory(metadata, relativePath, spineCategories) {
     const issues = [];
-    const ids = new Set();
+    const referencesByCategory = {};
     for (const category of spineCategories) {
         const rawValue = metadata[category.key];
         if (rawValue == null || rawValue === "") {
             continue;
         }
         if (!Array.isArray(rawValue)) {
-            issues.push(makeIssue("error", "metadata", `Metadata '${category.key}' must be an array, for example: [\"${category.prefix}-...\"]`, relativePath));
+            issues.push(makeIssue("error", "metadata", `Metadata '${category.key}' must be an array of spine entry keys (for example: [\"matthaeus\"]).`, relativePath));
             continue;
         }
+        const seen = new Set();
+        const values = [];
         for (const entry of rawValue) {
             if (typeof entry !== "string") {
                 issues.push(makeIssue("error", "metadata", `Metadata '${category.key}' entries must be strings.`, relativePath));
                 continue;
             }
-            const id = entry.trim();
-            if (!category.idPattern.test(id)) {
-                issues.push(makeIssue("error", "metadata", `Invalid ${category.key} reference '${id}'. Expected pattern '${category.idPattern.source}'.`, relativePath));
+            const normalized = entry.trim();
+            if (!normalized) {
+                issues.push(makeIssue("error", "metadata", `Metadata '${category.key}' contains an empty entry key.`, relativePath));
                 continue;
             }
-            ids.add(id);
-        }
-    }
-    return { ids: [...ids], issues };
-}
-function findInlineSpineIdMentions(body, relativePath, inlineIdRegex) {
-    const issues = [];
-    if (!inlineIdRegex) {
-        return issues;
-    }
-    const lines = body.split(/\r?\n/);
-    for (let index = 0; index < lines.length; index += 1) {
-        const matches = lines[index].match(inlineIdRegex);
-        if (!matches) {
-            continue;
-        }
-        for (const id of matches) {
-            issues.push(makeIssue("error", "continuity", `Inline ID '${id}' found in prose. Move canon IDs to metadata fields only.`, relativePath, index + 1));
+            if (seen.has(normalized)) {
+                continue;
+            }
+            seen.add(normalized);
+            values.push(normalized);
         }
+        referencesByCategory[category.key] = values;
     }
-    return issues;
+    return { referencesByCategory, issues };
 }
 function parseMetadata(raw, chapterPath, required) {
     const relativePath = path.relative(repoRoot, chapterPath);
@@ -1375,265 +1384,29 @@ function parseMetadata(raw, chapterPath, required) {
     };
 }
 function parseStegoCommentsAppendix(body, relativePath, bodyStartLine) {
-    const lineEnding = body.includes("\r\n") ? "\r\n" : "\n";
-    const lines = body.split(/\r?\n/);
-    const startMarker = "<!-- stego-comments:start -->";
-    const endMarker = "<!-- stego-comments:end -->";
-    const issues = [];
-    const startIndexes = findTrimmedLineIndexes(lines, startMarker);
-    const endIndexes = findTrimmedLineIndexes(lines, endMarker);
-    if (startIndexes.length === 0 && endIndexes.length === 0) {
-        return { bodyWithoutComments: body, comments: [], issues };
-    }
-    if (startIndexes.length !== 1 || endIndexes.length !== 1) {
-        if (startIndexes.length !== 1) {
-            issues.push(makeIssue("error", "comments", `Expected exactly one '${startMarker}' marker.`, relativePath));
-        }
-        if (endIndexes.length !== 1) {
-            issues.push(makeIssue("error", "comments", `Expected exactly one '${endMarker}' marker.`, relativePath));
-        }
-        return { bodyWithoutComments: body, comments: [], issues };
-    }
-    const start = startIndexes[0];
-    const end = endIndexes[0];
-    if (end <= start) {
-        issues.push(makeIssue("error", "comments", `'${endMarker}' must appear after '${startMarker}'.`, relativePath, bodyStartLine + end));
-        return { bodyWithoutComments: body, comments: [], issues };
-    }
-    const blockLines = lines.slice(start + 1, end);
-    const comments = parseStegoCommentThreads(blockLines, relativePath, bodyStartLine + start + 1, issues);
-    let removeStart = start;
-    if (removeStart > 0 && lines[removeStart - 1].trim().length === 0) {
-        removeStart -= 1;
-    }
-    const kept = [...lines.slice(0, removeStart), ...lines.slice(end + 1)];
-    while (kept.length > 0 && kept[kept.length - 1].trim().length === 0) {
-        kept.pop();
-    }
+    const parsed = parseCommentAppendix(body);
+    const issues = parsed.errors.map((error) => parseCommentIssueFromParserError(error, relativePath, bodyStartLine));
+    const comments = parsed.comments.map((comment) => ({
+        id: comment.id,
+        resolved: comment.status === "resolved",
+        thread: comment.thread
+    }));
     return {
-        bodyWithoutComments: kept.join(lineEnding),
+        bodyWithoutComments: parsed.contentWithoutComments,
         comments,
         issues
     };
 }
-function parseStegoCommentThreads(lines, relativePath, baseLine, issues) {
-    const comments = [];
-    let index = 0;
-    while (index < lines.length) {
-        const trimmed = lines[index].trim();
-        if (!trimmed) {
-            index += 1;
-            continue;
-        }
-        const id = parseCommentThreadDelimiter(trimmed);
-        if (!id) {
-            issues.push(makeIssue("error", "comments", "Invalid comments appendix line. Expected comment delimiter '<!-- comment: CMT-0001 -->'.", relativePath, baseLine + index));
-            index += 1;
-            continue;
-        }
-        index += 1;
-        const rowLines = [];
-        const rowLineNumbers = [];
-        while (index < lines.length) {
-            const nextTrimmed = lines[index].trim();
-            if (parseCommentThreadDelimiter(nextTrimmed)) {
-                break;
-            }
-            rowLines.push(lines[index]);
-            rowLineNumbers.push(baseLine + index);
-            index += 1;
-        }
-        let resolved;
-        let sawMeta64 = false;
-        const thread = [];
-        let rowIndex = 0;
-        while (rowIndex < rowLines.length) {
-            const rawRow = rowLines[rowIndex];
-            const lineNumber = rowLineNumbers[rowIndex];
-            const trimmedRow = rawRow.trim();
-            if (!trimmedRow) {
-                rowIndex += 1;
-                continue;
-            }
-            if (thread.length > 0) {
-                issues.push(makeIssue("error", "comments", `Multiple message blocks found for ${id}. Create a new CMT id for each reply.`, relativePath, lineNumber));
-                break;
-            }
-            if (!sawMeta64) {
-                const metaMatch = trimmedRow.match(/^<!--\s*meta64:\s*(\S+)\s*-->\s*$/);
-                if (!metaMatch) {
-                    issues.push(makeIssue("error", "comments", `Invalid comment metadata row '${trimmedRow}'. Expected '<!-- meta64: <base64url-json> -->'.`, relativePath, lineNumber));
-                    rowIndex += 1;
-                    continue;
-                }
-                sawMeta64 = true;
-                const decoded = decodeCommentMeta64(metaMatch[1], id, relativePath, lineNumber, issues);
-                if (decoded) {
-                    resolved = decoded.resolved;
-                }
-                rowIndex += 1;
-                continue;
-            }
-            const headerQuote = extractQuotedLine(rawRow);
-            if (headerQuote === undefined) {
-                issues.push(makeIssue("error", "comments", `Invalid thread header '${trimmedRow}'. Expected blockquote header like '> _timestamp — author_'.`, relativePath, lineNumber));
-                rowIndex += 1;
-                continue;
-            }
-            const header = parseThreadHeader(headerQuote);
-            if (!header) {
-                issues.push(makeIssue("error", "comments", `Invalid thread header '${headerQuote.trim()}'. Expected '> _timestamp — author_'.`, relativePath, lineNumber));
-                rowIndex += 1;
-                continue;
-            }
-            rowIndex += 1;
-            while (rowIndex < rowLines.length) {
-                const separatorRaw = rowLines[rowIndex];
-                const separatorTrimmed = separatorRaw.trim();
-                if (!separatorTrimmed) {
-                    rowIndex += 1;
-                    continue;
-                }
-                const separatorQuote = extractQuotedLine(separatorRaw);
-                if (separatorQuote !== undefined && separatorQuote.trim().length === 0) {
-                    rowIndex += 1;
-                }
-                break;
-            }
-            const messageLines = [];
-            while (rowIndex < rowLines.length) {
-                const messageRaw = rowLines[rowIndex];
-                const messageLineNumber = rowLineNumbers[rowIndex];
-                const messageTrimmed = messageRaw.trim();
-                if (!messageTrimmed) {
-                    rowIndex += 1;
-                    if (messageLines.length > 0) {
-                        break;
-                    }
-                    continue;
-                }
-                const messageQuote = extractQuotedLine(messageRaw);
-                if (messageQuote === undefined) {
-                    issues.push(makeIssue("error", "comments", `Invalid thread line '${messageTrimmed}'. Expected blockquote content starting with '>'.`, relativePath, messageLineNumber));
-                    rowIndex += 1;
-                    if (messageLines.length > 0) {
-                        break;
-                    }
-                    continue;
-                }
-                if (parseThreadHeader(messageQuote)) {
-                    break;
-                }
-                messageLines.push(messageQuote);
-                rowIndex += 1;
-            }
-            while (messageLines.length > 0 && messageLines[messageLines.length - 1].trim().length === 0) {
-                messageLines.pop();
-            }
-            if (messageLines.length === 0) {
-                issues.push(makeIssue("error", "comments", `Thread entry for comment ${id} is missing message text.`, relativePath, lineNumber));
-                continue;
-            }
-            const message = messageLines.join("\n").trim();
-            thread.push(`${header.timestamp} | ${header.author} | ${message}`);
-        }
-        if (!sawMeta64) {
-            issues.push(makeIssue("error", "comments", `Comment ${id} is missing metadata row ('<!-- meta64: <base64url-json> -->').`, relativePath));
-            resolved = false;
-        }
-        if (thread.length === 0) {
-            issues.push(makeIssue("error", "comments", `Comment ${id} is missing valid blockquote thread entries.`, relativePath));
-        }
-        comments.push({ id, resolved: Boolean(resolved), thread });
+function parseCommentIssueFromParserError(error, relativePath, bodyStartLine) {
+    const lineMatch = error.match(/^Line\\s+(\\d+):\\s+([\\s\\S]+)$/);
+    if (!lineMatch) {
+        return makeIssue("error", "comments", error, relativePath);
     }
-    return comments;
-}
-function parseCommentThreadDelimiter(line) {
-    const markerMatch = line.match(/^<!--\s*comment:\s*(CMT-\d{4,})\s*-->\s*$/i);
-    if (markerMatch?.[1]) {
-        return markerMatch[1].toUpperCase();
-    }
-    const legacyHeadingMatch = line.match(/^###\s+(CMT-\d{4,})\s*$/i);
-    if (legacyHeadingMatch?.[1]) {
-        return legacyHeadingMatch[1].toUpperCase();
-    }
-    return undefined;
-}
-function decodeCommentMeta64(encoded, commentId, relativePath, lineNumber, issues) {
-    let rawJson = "";
-    try {
-        rawJson = Buffer.from(encoded, "base64url").toString("utf8");
-    }
-    catch {
-        issues.push(makeIssue("error", "comments", `Invalid meta64 payload for comment ${commentId}; expected base64url-encoded JSON.`, relativePath, lineNumber));
-        return undefined;
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(rawJson);
-    }
-    catch {
-        issues.push(makeIssue("error", "comments", `Invalid meta64 JSON for comment ${commentId}.`, relativePath, lineNumber));
-        return undefined;
-    }
-    if (!isPlainObject(parsed)) {
-        issues.push(makeIssue("error", "comments", `Invalid meta64 object for comment ${commentId}.`, relativePath, lineNumber));
-        return undefined;
-    }
-    const allowedKeys = new Set([
-        "status",
-        "created_at",
-        "timezone",
-        "timezone_offset_minutes",
-        "paragraph_index",
-        "excerpt_start_line",
-        "excerpt_start_col",
-        "excerpt_end_line",
-        "excerpt_end_col",
-        "anchor",
-        "excerpt",
-        "signature"
-    ]);
-    for (const key of Object.keys(parsed)) {
-        if (!allowedKeys.has(key)) {
-            issues.push(makeIssue("error", "comments", `meta64 for comment ${commentId} contains unsupported key '${key}'.`, relativePath, lineNumber));
-            return undefined;
-        }
-    }
-    const status = typeof parsed.status === "string" ? parsed.status.trim().toLowerCase() : "";
-    if (status !== "open" && status !== "resolved") {
-        issues.push(makeIssue("error", "comments", `meta64 for comment ${commentId} must include status 'open' or 'resolved'.`, relativePath, lineNumber));
-        return undefined;
-    }
-    return { resolved: status === "resolved" };
-}
-function extractQuotedLine(raw) {
-    const quoteMatch = raw.match(/^\s*>\s?(.*)$/);
-    if (!quoteMatch) {
-        return undefined;
-    }
-    return quoteMatch[1];
-}
-function parseThreadHeader(value) {
-    const match = value.trim().match(/^_(.+?)\s*(?:—|\|)\s*(.+?)_\s*$/);
-    if (!match) {
-        return undefined;
-    }
-    const timestamp = match[1].trim();
-    const author = match[2].trim();
-    if (!timestamp || !author) {
-        return undefined;
-    }
-    return { timestamp, author };
-}
-function findTrimmedLineIndexes(lines, marker) {
-    const indexes = [];
-    for (let index = 0; index < lines.length; index += 1) {
-        if (lines[index].trim() === marker) {
-            indexes.push(index);
-        }
-    }
-    return indexes;
+    const relativeLine = Number.parseInt(lineMatch[1], 10);
+    const absoluteLine = Number.isFinite(relativeLine)
+        ? bodyStartLine + relativeLine - 1
+        : undefined;
+    return makeIssue("error", "comments", lineMatch[2], relativePath, absoluteLine);
 }
 function coerceMetadataValue(value) {
     if (!value) {
@@ -1762,39 +1535,31 @@ function runStyleHeuristics(body, relativePath) {
 function countWords(text) {
     return text.trim().split(/\s+/).filter(Boolean).length;
 }
-function readSpine(spineDir, spineCategories, inlineIdRegex) {
-    const issues = [];
-    const ids = new Set();
-    if (spineCategories.length === 0) {
-        return { ids, issues };
-    }
-    if (!fs.existsSync(spineDir)) {
-        issues.push(makeIssue("warning", "continuity", `Missing spine directory: ${spineDir}`));
-        return { ids, issues };
-    }
-    for (const category of spineCategories) {
-        const fullPath = path.join(spineDir, category.notesFile);
-        const relativePath = path.relative(repoRoot, fullPath);
-        if (!fs.existsSync(fullPath)) {
-            issues.push(makeIssue("warning", "continuity", `Missing spine file '${category.notesFile}' for category '${category.key}'.`, relativePath));
-            continue;
-        }
-        const text = fs.readFileSync(fullPath, "utf8");
-        if (!inlineIdRegex) {
-            continue;
-        }
-        const matches = text.match(inlineIdRegex) || [];
-        for (const id of matches) {
-            ids.add(id);
-        }
+function readSpine(project) {
+    const catalog = readSpineCatalog(project.root, project.spineDir);
+    const categories = [];
+    const entriesByCategory = new Map();
+    for (const category of catalog.categories) {
+        const entries = new Set(category.entries.map((entry) => entry.key));
+        categories.push({ key: category.key, entries });
+        entriesByCategory.set(category.key, entries);
     }
-    return { ids, issues };
+    const issues = catalog.issues.map((message) => makeIssue("warning", "continuity", message));
+    return { categories, entriesByCategory, issues };
 }
-function findUnknownSpineIds(referenceIds, knownIds, relativePath) {
+function findUnknownSpineReferences(referencesByCategory, entriesByCategory, relativePath) {
     const issues = [];
-    for (const id of referenceIds) {
-        if (!knownIds.has(id)) {
-            issues.push(makeIssue("warning", "continuity", `Metadata reference '${id}' does not exist in the spine files.`, relativePath));
+    for (const [categoryKey, values] of Object.entries(referencesByCategory)) {
+        const known = entriesByCategory.get(categoryKey);
+        if (!known) {
+            issues.push(makeIssue("warning", "continuity", `Metadata category '${categoryKey}' has references but no matching spine category directory was found in spine/.`, relativePath));
+            continue;
+        }
+        for (const value of values) {
+            if (known.has(value)) {
+                continue;
+            }
+            issues.push(makeIssue("warning", "continuity", `Metadata reference '${categoryKey}: ${value}' does not exist in spine/${categoryKey}/.`, relativePath));
         }
     }
     return issues;
@@ -1831,8 +1596,11 @@ function runStageCheck(project, runtimeConfig, stage, onlyFile) {
         }
     }
     if (policy.requireSpine) {
+        if (report.spineState.categories.length === 0) {
+            issues.push(makeIssue("error", "continuity", "No spine categories found. Add at least one category under spine/<category>/ before this stage."));
+        }
         for (const spineIssue of report.issues.filter((issue) => issue.category === "continuity")) {
-            if (spineIssue.message.startsWith("Missing spine file")) {
+            if (spineIssue.message.startsWith("Missing spine directory")) {
                 issues.push({ ...spineIssue, level: "error" });
             }
         }
@@ -1844,7 +1612,7 @@ function runStageCheck(project, runtimeConfig, stage, onlyFile) {
         }
     }
     const chapterPaths = report.chapters.map((chapter) => chapter.path);
-    const spineWords = collectSpineWordsForSpellcheck(report.spineState.ids);
+    const spineWords = collectSpineWordsForSpellcheck(report.spineState.entriesByCategory);
     if (policy.enforceMarkdownlint) {
         issues.push(...runMarkdownlint(project, chapterPaths, true, "manuscript"));
     }
@@ -2002,18 +1770,29 @@ function runMarkdownlint(project, files, required, profile = "default") {
         prepared.cleanup();
     }
 }
-function collectSpineWordsForSpellcheck(ids) {
+function collectSpineWordsForSpellcheck(entriesByCategory) {
     const words = new Set();
-    for (const id of ids) {
-        const parts = id
-            .split("-")
+    for (const [category, entries] of entriesByCategory) {
+        const categoryParts = category
+            .split(/[-_/]+/)
             .map((part) => part.trim())
             .filter(Boolean);
-        for (const part of parts.slice(1)) {
-            if (!/[A-Za-z]/.test(part)) {
-                continue;
+        for (const part of categoryParts) {
+            if (/[A-Za-z]/.test(part)) {
+                words.add(part.toLowerCase());
+            }
+        }
+        for (const entry of entries) {
+            const entryParts = entry
+                .split(/[-_/]+/)
+                .map((part) => part.trim())
+                .filter(Boolean);
+            for (const part of entryParts) {
+                if (!/[A-Za-z]/.test(part)) {
+                    continue;
+                }
+                words.add(part.toLowerCase());
             }
-            words.add(part.toLowerCase());
         }
     }
     return Array.from(words).sort();