stego-cli 0.3.4 → 0.4.1

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,
@@ -22,6 +25,7 @@ const RESERVED_COMMENT_PREFIX = "CMT";
 const DEFAULT_NEW_MANUSCRIPT_SLUG = "new-document";
 const ROOT_CONFIG_FILENAME = "stego.config.json";
 const PROSE_FONT_PROMPT = "Switch workspace to proportional (prose-style) font? (recommended)";
+const COMMENT_AUTHOR_PROMPT = "Default comment author for stego.comments.author?";
 const SCAFFOLD_GITIGNORE_CONTENT = `node_modules/
 /dist/
 .DS_Store
@@ -89,6 +93,103 @@ stego new-project --project my-book --title "My Book"
 stego new --project fiction-example
 \`\`\`
 `;
+const SCAFFOLD_AGENTS_CONTENT = `# AGENTS.md
+
+## Purpose
+
+This workspace is designed to be AI-friendly for writing workflows.
+
+## Canonical CLI Interface
+
+- Run \`stego --help\` for the full command reference.
+- Run \`stego --version\` to confirm which CLI is active.
+- Run project docs commands in \`projects/stego-docs\` when available.
+
+## CLI Resolution Rules
+
+- Prefer local CLI over global CLI:
+  - \`npm exec -- stego ...\`
+  - \`npx --no-install stego ...\`
+- At the start of mutation tasks, run \`stego --version\` and report the version used.
+
+## Workspace Discovery Checklist
+
+1. Confirm workspace root contains \`stego.config.json\`.
+2. Run \`stego list-projects\`.
+3. Use explicit \`--project <id>\` for project-scoped commands.
+
+## CLI-First Policy (Required)
+
+When asked to edit Stego project content, use documented Stego CLI commands first.
+
+Typical targets:
+
+- manuscript files
+- spine categories and entries
+- frontmatter metadata
+- comments
+- stage/build/export workflows
+
+Preferred commands include:
+
+- \`stego new\`
+- \`stego spine read\`
+- \`stego spine new-category\`
+- \`stego spine new\`
+- \`stego metadata read\`
+- \`stego metadata apply\`
+- \`stego comments ...\`
+
+## Machine-Mode Output
+
+- For automation and integrations, prefer \`--format json\` and parse structured output.
+- Use text output only for human-facing summaries.
+
+## Mutation Protocol
+
+1. Read current state first (\`metadata read\`, \`spine read\`, \`comments read\`).
+2. Mutate via CLI commands.
+3. Verify after writes (\`stego validate --project <id>\` and relevant read commands).
+
+## Manual Edit Fallback
+
+Manual file edits are a last resort.
+
+If manual edits are required, the agent must:
+
+1. warn that CLI was bypassed,
+2. explain why CLI could not be used, and
+3. list which files were manually edited.
+
+## Failure Contract
+
+When CLI fails:
+
+1. show the attempted command,
+2. summarize the error briefly,
+3. report the recovery attempt, and
+4. if fallback is required, apply the Manual Edit Fallback policy.
+
+## Validation Expectations
+
+After mutations, run relevant checks when feasible (for example \`stego validate --project <id>\`) and report results.
+
+## Scope Guardrails
+
+- Do not manually edit \`dist/\` outputs or compiled export artifacts.
+- Do not modify files outside the requested project scope unless the user explicitly asks.
+
+## Task To Command Quick Map
+
+- New manuscript: \`stego new --project <id> [--filename <name>]\`
+- Read spine: \`stego spine read --project <id> --format json\`
+- New spine category: \`stego spine new-category --project <id> --key <category>\`
+- New spine entry: \`stego spine new --project <id> --category <category> [--filename <path>]\`
+- Read metadata: \`stego metadata read <markdown-path> --format json\`
+- Apply metadata: \`stego metadata apply <markdown-path> --input <path|-> --format json\`
+- Read comments: \`stego comments read <manuscript> --format json\`
+- Mutate comments: \`stego comments add|reply|set-status|delete|clear-resolved|sync-anchors ... --format json\`
+`;
 const PROSE_MARKDOWN_EDITOR_SETTINGS = {
     "[markdown]": {
         "editor.fontFamily": "Inter, Helvetica Neue, Helvetica, Arial, sans-serif",
@@ -102,7 +203,8 @@ const PROSE_MARKDOWN_EDITOR_SETTINGS = {
 };
 const PROJECT_EXTENSION_RECOMMENDATIONS = [
     "matt-gold.stego-extension",
-    "matt-gold.saurus-extension"
+    "matt-gold.saurus-extension",
+    "streetsidesoftware.code-spell-checker"
 ];
 const scriptDir = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(scriptDir, "..");
@@ -111,6 +213,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 +234,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 +328,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 +372,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 +406,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 +499,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);
 }
@@ -529,6 +612,7 @@ async function initWorkspace(options) {
     const copiedPaths = [];
     writeScaffoldGitignore(targetRoot, copiedPaths);
     writeScaffoldReadme(targetRoot, copiedPaths);
+    writeScaffoldAgents(targetRoot, copiedPaths);
     copyTemplateAsset(".markdownlint.json", targetRoot, copiedPaths);
     copyTemplateAsset(".markdownlint.manuscript.json", targetRoot, copiedPaths);
     copyTemplateAsset(".cspell.json", targetRoot, copiedPaths);
@@ -538,8 +622,13 @@ async function initWorkspace(options) {
     copyTemplateAsset(path.join(".vscode", "extensions.json"), targetRoot, copiedPaths, { optional: true });
     rewriteTemplateProjectPackageScripts(targetRoot);
     const enableProseFont = await promptYesNo(PROSE_FONT_PROMPT, true);
-    if (enableProseFont) {
-        writeProjectProseEditorSettings(targetRoot, copiedPaths);
+    const suggestedCommentAuthor = resolveSuggestedCommentAuthor(targetRoot);
+    const commentAuthor = (await promptText(COMMENT_AUTHOR_PROMPT, suggestedCommentAuthor)).trim();
+    if (enableProseFont || commentAuthor) {
+        writeProjectProseEditorSettings(targetRoot, copiedPaths, {
+            enableProseFont,
+            commentAuthor
+        });
     }
     writeInitRootPackageJson(targetRoot);
     logLine(`Initialized Stego workspace in ${targetRoot}`);
@@ -582,6 +671,46 @@ async function promptYesNo(question, defaultYes) {
         rl.close();
     }
 }
+async function promptText(question, defaultValue = "") {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        return defaultValue;
+    }
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+    const suffix = defaultValue ? ` [${defaultValue}] ` : " ";
+    try {
+        const answer = (await rl.question(`${question}${suffix}`)).trim();
+        if (!answer) {
+            return defaultValue;
+        }
+        return answer;
+    }
+    finally {
+        rl.close();
+    }
+}
+function resolveSuggestedCommentAuthor(cwd) {
+    const gitAuthor = spawnSync("git", ["config", "--get", "user.name"], {
+        cwd,
+        encoding: "utf8"
+    });
+    const fromGit = (gitAuthor.stdout || "").trim();
+    if (gitAuthor.status === 0 && fromGit) {
+        return fromGit;
+    }
+    try {
+        const username = os.userInfo().username.trim();
+        if (username) {
+            return username;
+        }
+    }
+    catch {
+        // ignore lookup failure and fall back to empty
+    }
+    return "";
+}
 function copyTemplateAsset(sourceRelativePath, targetRoot, copiedPaths, options) {
     const sourcePath = path.join(packageRoot, sourceRelativePath);
     if (!fs.existsSync(sourcePath)) {
@@ -616,6 +745,11 @@ function writeScaffoldReadme(targetRoot, copiedPaths) {
     fs.writeFileSync(destinationPath, SCAFFOLD_README_CONTENT, "utf8");
     copiedPaths.push("README.md");
 }
+function writeScaffoldAgents(targetRoot, copiedPaths) {
+    const destinationPath = path.join(targetRoot, "AGENTS.md");
+    fs.writeFileSync(destinationPath, SCAFFOLD_AGENTS_CONTENT, "utf8");
+    copiedPaths.push("AGENTS.md");
+}
 function shouldCopyTemplatePath(currentSourcePath) {
     const relativePath = path.relative(packageRoot, currentSourcePath);
     if (!relativePath || relativePath.startsWith("..")) {
@@ -691,7 +825,7 @@ function ensureProjectExtensionsRecommendations(projectRoot) {
     };
     fs.writeFileSync(extensionsPath, `${JSON.stringify(extensionsConfig, null, 2)}\n`, "utf8");
 }
-function writeProjectProseEditorSettings(targetRoot, copiedPaths) {
+function writeProjectProseEditorSettings(targetRoot, copiedPaths, options) {
     const projectsRoot = path.join(targetRoot, "projects");
     if (!fs.existsSync(projectsRoot)) {
         return;
@@ -701,14 +835,16 @@ function writeProjectProseEditorSettings(targetRoot, copiedPaths) {
             continue;
         }
         const projectRoot = path.join(projectsRoot, entry.name);
-        const settingsPath = writeProseEditorSettingsForProject(projectRoot);
+        const settingsPath = writeProseEditorSettingsForProject(projectRoot, options);
         copiedPaths.push(path.relative(targetRoot, settingsPath));
     }
 }
-function writeProseEditorSettingsForProject(projectRoot) {
+function writeProseEditorSettingsForProject(projectRoot, options) {
     const vscodeDir = path.join(projectRoot, ".vscode");
     const settingsPath = path.join(vscodeDir, "settings.json");
     fs.mkdirSync(vscodeDir, { recursive: true });
+    const enableProseFont = options?.enableProseFont ?? true;
+    const commentAuthor = (options?.commentAuthor ?? "").trim();
     let existingSettings = {};
     if (fs.existsSync(settingsPath)) {
         try {
@@ -724,17 +860,22 @@ function writeProseEditorSettingsForProject(projectRoot) {
     const proseMarkdownSettings = isPlainObject(PROSE_MARKDOWN_EDITOR_SETTINGS["[markdown]"])
         ? PROSE_MARKDOWN_EDITOR_SETTINGS["[markdown]"]
         : {};
-    const existingMarkdownSettings = isPlainObject(existingSettings["[markdown]"])
-        ? existingSettings["[markdown]"]
-        : {};
     const nextSettings = {
-        ...existingSettings,
-        "[markdown]": {
+        ...existingSettings
+    };
+    if (enableProseFont) {
+        const existingMarkdownSettings = isPlainObject(existingSettings["[markdown]"])
+            ? existingSettings["[markdown]"]
+            : {};
+        nextSettings["[markdown]"] = {
             ...existingMarkdownSettings,
             ...proseMarkdownSettings
-        },
-        "markdown.preview.fontFamily": PROSE_MARKDOWN_EDITOR_SETTINGS["markdown.preview.fontFamily"]
-    };
+        };
+        nextSettings["markdown.preview.fontFamily"] = PROSE_MARKDOWN_EDITOR_SETTINGS["markdown.preview.fontFamily"];
+    }
+    if (commentAuthor) {
+        nextSettings["stego.comments.author"] = commentAuthor;
+    }
     fs.writeFileSync(settingsPath, `${JSON.stringify(nextSettings, null, 2)}\n`, "utf8");
     return settingsPath;
 }
@@ -753,6 +894,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 +911,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 +924,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 +945,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 +958,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 +967,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 +989,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 +1236,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 +1285,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 +1312,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 +1322,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 +1351,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 +1360,7 @@ function parseChapter(chapterPath, runtimeConfig, requiredMetadata, spineCategor
         title,
         order,
         status,
-        referenceIds: referenceValidation.ids,
+        referenceKeysByCategory: referenceValidation.referencesByCategory,
         groupValues,
         metadata,
         body,
@@ -1228,49 +1403,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 +1692,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 +1753,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 +1769,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 +1927,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();