stego-cli 0.3.4 → 0.4.0

package/dist/stego-cli.js

@@ -11,6 +11,9 @@ 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,
@@ -111,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;
@@ -126,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": {
@@ -202,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.`);
         }
@@ -232,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;
@@ -244,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"));
@@ -406,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);
 }
@@ -753,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",
@@ -768,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 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`);
+    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();
@@ -781,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>.");
     }
@@ -802,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: [
@@ -815,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");
@@ -831,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",
@@ -851,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)}`);
@@ -1061,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) {
@@ -1107,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);
     }
@@ -1134,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,
@@ -1146,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);
@@ -1175,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,
@@ -1185,7 +1203,7 @@ function parseChapter(chapterPath, runtimeConfig, requiredMetadata, spineCategor
         title,
         order,
         status,
-        referenceIds: referenceValidation.ids,
+        referenceKeysByCategory: referenceValidation.referencesByCategory,
         groupValues,
         metadata,
         body,
@@ -1228,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);
@@ -1527,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;
@@ -1596,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" });
             }
         }
@@ -1609,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"));
     }
@@ -1767,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();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stego-cli",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "type": "module",
   "description": "Installable CLI for the Stego writing monorepo workflow.",
   "license": "Apache-2.0",
@@ -51,7 +51,8 @@
     "export": "node --experimental-strip-types tools/stego-cli.ts export",
     "test:compile-structure": "node --test tools/test/compile-structure.test.mjs",
     "test:comments": "node --test tools/test/comments-add.test.mjs",
-    "test": "npm run test:compile-structure && npm run test:comments"
+    "test:spine-v2": "node --test tools/test/spine-v2.test.mjs",
+    "test": "npm run test:compile-structure && npm run test:comments && npm run test:spine-v2"
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.8",

package/projects/fiction-example/spine/characters/CHAR-AGNES.md

@@ -0,0 +1,17 @@
+---
+label: Agnes the apothecary
+---
+
+# Agnes the apothecary
+
+## Role
+Compounder and practical healer near the Petit Pont; supplies Hôtel-Dieu (LOC-HOTELDIEU)
+
+## Disposition
+Empirical, blunt, uninterested in frameworks that don't predict which street sickens next
+
+## Sources
+Her own ward observations (SRC-WARD-DATA); she has no name for her method, which is part of its strength and its institutional weakness
+
+## Function
+The counterweight; asks whether a system that can absorb any evidence without changing is a system or a habit

package/projects/fiction-example/spine/characters/CHAR-ETIENNE.md

@@ -0,0 +1,17 @@
+---
+label: Etienne of Saint-Marcel
+---
+
+# Etienne of Saint-Marcel
+
+## Role
+Young cleric-scribe attached to Matthaeus (CHAR-MATTHAEUS)
+
+## Disposition
+Careful, loyal, doctrinally cautious; sees everything his master does and says nothing about the parts that trouble him
+
+## Sources
+He works primarily from Matthaeus's memoranda and dictated classifications, preserving the system as it is built
+
+## Function
+The witness; records the system without fully believing it, and without claiming a replacement for it

package/projects/fiction-example/spine/characters/CHAR-MATTHAEUS.md

@@ -0,0 +1,17 @@
+---
+label: Magister Matthaeus de Rota
+---
+
+# Magister Matthaeus de Rota
+
+## Role
+Scholar of medicine and astrology at the University of Paris
+
+## Disposition
+Methodical, sincere, incapable of leaving an observation outside his system; treats coherence as a moral obligation
+
+## Sources
+Works primarily from the conjunction theory (SRC-CONJUNCTION) and Galenic tradition (SRC-GALEN); consults a prohibited astrological quire privately for its method of reasoning from hidden correspondences
+
+## Function
+Builds a total explanation of the pestilence and dies at peace inside it; the question is whether his peace is understanding or its most sophisticated substitute