stego-cli 0.2.1 → 0.3.1

package/README.md

@@ -56,8 +56,22 @@ stego check-stage --project fiction-example --stage revise
 stego export --project fiction-example --format md
 ```
 
+`stego new` also supports `--i <prefix>` for numeric prefix override and `--filename <name>` for an explicit manuscript filename.
+
 Projects also include local npm scripts so you can work from inside a project directory.
 
+## Advanced integration command
+
+`stego comments add` is a machine-facing command for editor/tool integrations.
+
+```bash
+stego comments add manuscript/100-scene.md --message "Could this transition be clearer?"
+stego comments add manuscript/100-scene.md --input payload.json --format json
+stego comments add manuscript/100-scene.md --input - --format json <<'JSON'
+{"message":"Could this transition be clearer?","range":{"start":{"line":10,"col":4},"end":{"line":10,"col":32}}}
+JSON
+```
+
 ## VS Code workflow
 
 When actively working on one project, open that project directory directly in VS Code (for example `projects/fiction-example`).

package/dist/comments/add-comment.js

@@ -0,0 +1,177 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CommentsCommandError } from "./errors.js";
+const COMMENT_HEADING_REGEX = /^###\s+(CMT-(\d{4,}))\s*$/;
+const START_SENTINEL = "<!-- stego-comments:start -->";
+const END_SENTINEL = "<!-- stego-comments:end -->";
+/** Adds one stego comment entry to a manuscript and writes the updated file. */
+export function addCommentToManuscript(request) {
+    const absolutePath = path.resolve(request.cwd, request.manuscriptPath);
+    if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile()) {
+        throw new CommentsCommandError("INVALID_USAGE", 2, `Manuscript file not found: ${request.manuscriptPath}`);
+    }
+    const raw = fs.readFileSync(absolutePath, "utf8");
+    const lineEnding = raw.includes("\r\n") ? "\r\n" : "\n";
+    const lines = raw.split(/\r?\n/);
+    const sentinelState = resolveSentinelState(lines);
+    const hasYamlFrontmatter = raw.startsWith(`---${lineEnding}`) || raw.startsWith("---\n");
+    if (!sentinelState.hasSentinels && !hasYamlFrontmatter) {
+        throw new CommentsCommandError("NOT_STEGO_MANUSCRIPT", 3, "File is not recognized as a Stego manuscript (missing frontmatter and comments sentinels).");
+    }
+    const commentId = getNextCommentId(lines);
+    const createdAt = new Date().toISOString();
+    const meta = buildMetaPayload(request.range, request.sourceMeta);
+    const meta64 = Buffer.from(JSON.stringify(meta), "utf8").toString("base64url");
+    const entryLines = buildCommentEntryLines(commentId, createdAt, request.author, request.message, meta64);
+    const nextLines = applyCommentEntry(lines, sentinelState, entryLines);
+    const nextContent = `${nextLines.join(lineEnding)}${lineEnding}`;
+    try {
+        fs.writeFileSync(absolutePath, nextContent, "utf8");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new CommentsCommandError("WRITE_FAILURE", 6, `Failed to update manuscript: ${message}`);
+    }
+    const result = {
+        ok: true,
+        manuscript: absolutePath,
+        commentId,
+        status: "open",
+        anchor: request.range
+            ? {
+                type: "selection",
+                excerptStartLine: request.range.startLine,
+                excerptStartCol: request.range.startCol,
+                excerptEndLine: request.range.endLine,
+                excerptEndCol: request.range.endCol
+            }
+            : { type: "file" },
+        createdAt
+    };
+    return result;
+}
+function buildMetaPayload(range, sourceMeta) {
+    const payload = {
+        status: "open"
+    };
+    if (range) {
+        payload.anchor = "selection";
+        payload.excerpt = {
+            start_line: range.startLine,
+            start_col: range.startCol,
+            end_line: range.endLine,
+            end_col: range.endCol
+        };
+    }
+    if (sourceMeta && Object.keys(sourceMeta).length > 0) {
+        payload.signature = sourceMeta;
+    }
+    return payload;
+}
+function buildCommentEntryLines(commentId, timestamp, author, message, meta64) {
+    const safeAuthor = author.trim() || "Saurus";
+    const normalizedMessageLines = message
+        .replace(/\r\n/g, "\n")
+        .split("\n")
+        .map((line) => line.trimEnd());
+    return [
+        `### ${commentId}`,
+        `<!-- meta64: ${meta64} -->`,
+        `> _${timestamp} | ${safeAuthor}_`,
+        ">",
+        ...normalizedMessageLines.map((line) => `> ${line}`)
+    ];
+}
+function applyCommentEntry(lines, sentinelState, entryLines) {
+    if (!sentinelState.hasSentinels) {
+        const baseLines = trimTrailingBlankLines(lines);
+        return [
+            ...baseLines,
+            "",
+            START_SENTINEL,
+            "",
+            ...entryLines,
+            "",
+            END_SENTINEL
+        ];
+    }
+    const startIndex = sentinelState.startIndex;
+    const endIndex = sentinelState.endIndex;
+    const block = lines.slice(startIndex + 1, endIndex);
+    const trimmedBlock = trimOuterBlankLines(block);
+    const nextBlock = trimmedBlock.length > 0
+        ? [...trimmedBlock, "", ...entryLines]
+        : [...entryLines];
+    return [
+        ...lines.slice(0, startIndex + 1),
+        ...nextBlock,
+        ...lines.slice(endIndex)
+    ];
+}
+function resolveSentinelState(lines) {
+    const startIndexes = findTrimmedLineIndexes(lines, START_SENTINEL);
+    const endIndexes = findTrimmedLineIndexes(lines, END_SENTINEL);
+    const hasAnySentinel = startIndexes.length > 0 || endIndexes.length > 0;
+    if (!hasAnySentinel) {
+        return {
+            hasSentinels: false,
+            startIndex: -1,
+            endIndex: -1
+        };
+    }
+    if (startIndexes.length !== 1 || endIndexes.length !== 1) {
+        throw new CommentsCommandError("COMMENT_APPENDIX_INVALID", 5, `Expected exactly one '${START_SENTINEL}' and one '${END_SENTINEL}' marker.`);
+    }
+    const startIndex = startIndexes[0];
+    const endIndex = endIndexes[0];
+    if (endIndex <= startIndex) {
+        throw new CommentsCommandError("COMMENT_APPENDIX_INVALID", 5, `'${END_SENTINEL}' must appear after '${START_SENTINEL}'.`);
+    }
+    return {
+        hasSentinels: true,
+        startIndex,
+        endIndex
+    };
+}
+function findTrimmedLineIndexes(lines, target) {
+    const indexes = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        if (lines[index].trim() === target) {
+            indexes.push(index);
+        }
+    }
+    return indexes;
+}
+function getNextCommentId(lines) {
+    let maxId = 0;
+    for (const line of lines) {
+        const match = line.trim().match(COMMENT_HEADING_REGEX);
+        if (!match) {
+            continue;
+        }
+        const numeric = Number.parseInt(match[2], 10);
+        if (Number.isFinite(numeric) && numeric > maxId) {
+            maxId = numeric;
+        }
+    }
+    const next = maxId + 1;
+    return `CMT-${String(next).padStart(4, "0")}`;
+}
+function trimTrailingBlankLines(lines) {
+    const copy = [...lines];
+    while (copy.length > 0 && copy[copy.length - 1].trim().length === 0) {
+        copy.pop();
+    }
+    return copy;
+}
+function trimOuterBlankLines(lines) {
+    let start = 0;
+    let end = lines.length;
+    while (start < end && lines[start].trim().length === 0) {
+        start += 1;
+    }
+    while (end > start && lines[end - 1].trim().length === 0) {
+        end -= 1;
+    }
+    return lines.slice(start, end);
+}

package/dist/comments/comments-command.js

@@ -0,0 +1,207 @@
+import fs from "node:fs";
+import path from "node:path";
+import { addCommentToManuscript } from "./add-comment.js";
+import { CommentsCommandError } from "./errors.js";
+/** Handles `stego comments ...` command group. */
+export async function runCommentsCommand(options, cwd) {
+    const [subcommand, manuscriptArg] = options._;
+    if (subcommand !== "add") {
+        throw new CommentsCommandError("INVALID_USAGE", 2, "Unknown comments subcommand. Use: stego comments add <manuscript> [--message <text> | --input <path|->].");
+    }
+    if (!manuscriptArg) {
+        throw new CommentsCommandError("INVALID_USAGE", 2, "Manuscript path is required. Use: stego comments add <manuscript> ...");
+    }
+    const outputFormat = parseOutputFormat(readString(options, "format"));
+    const messageOption = readString(options, "message");
+    const inputOption = readString(options, "input");
+    if (messageOption && inputOption) {
+        throw new CommentsCommandError("INVALID_USAGE", 2, "Use exactly one payload mode: --message <text> OR --input <path|->.", outputFormat);
+    }
+    if (!messageOption && !inputOption) {
+        throw new CommentsCommandError("INVALID_USAGE", 2, "Missing payload. Provide --message <text> or --input <path|->.", outputFormat);
+    }
+    const payload = inputOption ? readInputPayload(inputOption, cwd, outputFormat) : undefined;
+    const payloadMessage = coerceNonEmptyString(payload?.message, "Input payload 'message' must be a non-empty string.", outputFormat);
+    const payloadAuthor = coerceOptionalString(payload?.author, "Input payload 'author' must be a string if provided.", outputFormat);
+    const payloadRange = payload?.range !== undefined
+        ? parsePayloadRange(payload.range, outputFormat)
+        : undefined;
+    const payloadMeta = payload?.meta !== undefined
+        ? coerceOptionalObject(payload.meta, "Input payload 'meta' must be an object if provided.", outputFormat)
+        : undefined;
+    const optionRange = parseRangeFromOptions(options, outputFormat);
+    const finalMessage = (messageOption ?? payloadMessage ?? "").trim();
+    if (!finalMessage) {
+        throw new CommentsCommandError("INVALID_PAYLOAD", 4, "Comment message cannot be empty.", outputFormat);
+    }
+    const finalAuthor = (readString(options, "author") ?? payloadAuthor ?? "Saurus").trim() || "Saurus";
+    const finalRange = optionRange ?? payloadRange;
+    let result;
+    try {
+        result = addCommentToManuscript({
+            manuscriptPath: manuscriptArg,
+            cwd,
+            message: finalMessage,
+            author: finalAuthor,
+            range: finalRange,
+            sourceMeta: payloadMeta
+        });
+    }
+    catch (error) {
+        if (error instanceof CommentsCommandError && outputFormat === "json" && error.outputFormat !== "json") {
+            throw new CommentsCommandError(error.code, error.exitCode, error.message, outputFormat);
+        }
+        throw error;
+    }
+    if (outputFormat === "json") {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    const relativePath = path.relative(cwd, result.manuscript) || result.manuscript;
+    if (result.anchor.type === "selection") {
+        console.log(`Added ${result.commentId} to ${relativePath} (selection anchor).`);
+        return;
+    }
+    console.log(`Added ${result.commentId} to ${relativePath} (file-level anchor).`);
+}
+function readString(options, key) {
+    const value = options[key];
+    return typeof value === "string" ? value : undefined;
+}
+function parseOutputFormat(raw) {
+    if (!raw || raw === "text") {
+        return "text";
+    }
+    if (raw === "json") {
+        return "json";
+    }
+    throw new CommentsCommandError("INVALID_USAGE", 2, "Invalid --format value. Use 'text' or 'json'.");
+}
+function readInputPayload(inputPath, cwd, outputFormat) {
+    let rawJson = "";
+    try {
+        rawJson = inputPath === "-"
+            ? fs.readFileSync(0, "utf8")
+            : fs.readFileSync(path.resolve(cwd, inputPath), "utf8");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new CommentsCommandError("INVALID_PAYLOAD", 4, `Unable to read input payload: ${message}`, outputFormat);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(rawJson);
+    }
+    catch {
+        throw new CommentsCommandError("INVALID_PAYLOAD", 4, "Input payload is not valid JSON.", outputFormat);
+    }
+    if (!isPlainObject(parsed)) {
+        throw new CommentsCommandError("INVALID_PAYLOAD", 4, "Input payload must be a JSON object.", outputFormat);
+    }
+    return parsed;
+}
+function parseRangeFromOptions(options, outputFormat) {
+    const rawStartLine = readString(options, "start-line");
+    const rawStartCol = readString(options, "start-col");
+    const rawEndLine = readString(options, "end-line");
+    const rawEndCol = readString(options, "end-col");
+    const values = [rawStartLine, rawStartCol, rawEndLine, rawEndCol];
+    const hasAny = values.some((value) => value !== undefined);
+    const hasAll = values.every((value) => value !== undefined);
+    if (!hasAny) {
+        return undefined;
+    }
+    if (!hasAll) {
+        throw new CommentsCommandError("INVALID_USAGE", 2, "Range options must include all of --start-line, --start-col, --end-line, --end-col.", outputFormat);
+    }
+    const range = {
+        startLine: parseNonNegativeInt(rawStartLine, "--start-line", outputFormat),
+        startCol: parseNonNegativeInt(rawStartCol, "--start-col", outputFormat),
+        endLine: parseNonNegativeInt(rawEndLine, "--end-line", outputFormat),
+        endCol: parseNonNegativeInt(rawEndCol, "--end-col", outputFormat)
+    };
+    validateRange(range, outputFormat);
+    return range;
+}
+function parsePayloadRange(raw, outputFormat) {
+    if (!isPlainObject(raw)) {
+        throw new CommentsCommandError("INVALID_PAYLOAD", 4, "Input payload 'range' must be an object.", outputFormat);
+    }
+    const parsed = raw;
+    const start = parsed.start;
+    const end = parsed.end;
+    if (!isPlainObject(start) || !isPlainObject(end)) {
+        throw new CommentsCommandError("INVALID_PAYLOAD", 4, "Input payload 'range' must include 'start' and 'end' objects.", outputFormat);
+    }
+    const normalized = {
+        start: {
+            line: parseJsonNonNegativeInt(start.line, "range.start.line", outputFormat),
+            col: parseJsonNonNegativeInt(start.col, "range.start.col", outputFormat)
+        },
+        end: {
+            line: parseJsonNonNegativeInt(end.line, "range.end.line", outputFormat),
+            col: parseJsonNonNegativeInt(end.col, "range.end.col", outputFormat)
+        }
+    };
+    const range = {
+        startLine: normalized.start.line,
+        startCol: normalized.start.col,
+        endLine: normalized.end.line,
+        endCol: normalized.end.col
+    };
+    validateRange(range, outputFormat);
+    return range;
+}
+function validateRange(range, outputFormat) {
+    const startsBeforeEnd = range.startLine < range.endLine
+        || (range.startLine === range.endLine && range.startCol < range.endCol);
+    if (!startsBeforeEnd) {
+        throw new CommentsCommandError("INVALID_PAYLOAD", 4, "Range end must be after range start.", outputFormat);
+    }
+}
+function parseNonNegativeInt(raw, label, outputFormat) {
+    if (!/^\d+$/.test(raw)) {
+        throw new CommentsCommandError("INVALID_USAGE", 2, `${label} must be a non-negative integer.`, outputFormat);
+    }
+    const value = Number.parseInt(raw, 10);
+    if (!Number.isFinite(value)) {
+        throw new CommentsCommandError("INVALID_USAGE", 2, `${label} must be a non-negative integer.`, outputFormat);
+    }
+    return value;
+}
+function parseJsonNonNegativeInt(raw, label, outputFormat) {
+    if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0) {
+        throw new CommentsCommandError("INVALID_PAYLOAD", 4, `${label} must be a non-negative integer.`, outputFormat);
+    }
+    return raw;
+}
+function coerceNonEmptyString(value, message, outputFormat) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new CommentsCommandError("INVALID_PAYLOAD", 4, message, outputFormat);
+    }
+    return value;
+}
+function coerceOptionalString(value, message, outputFormat) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string") {
+        throw new CommentsCommandError("INVALID_PAYLOAD", 4, message, outputFormat);
+    }
+    return value;
+}
+function coerceOptionalObject(value, message, outputFormat) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!isPlainObject(value)) {
+        throw new CommentsCommandError("INVALID_PAYLOAD", 4, message, outputFormat);
+    }
+    return value;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/comments/errors.js

@@ -0,0 +1,20 @@
+/** Error raised for machine-facing comments command failures. */
+export class CommentsCommandError extends Error {
+    code;
+    exitCode;
+    outputFormat;
+    constructor(code, exitCode, message, outputFormat = "text") {
+        super(message);
+        this.name = "CommentsCommandError";
+        this.code = code;
+        this.exitCode = exitCode;
+        this.outputFormat = outputFormat;
+    }
+    toJson() {
+        return {
+            ok: false,
+            code: this.code,
+            message: this.message
+        };
+    }
+}

package/dist/stego-cli.js

@@ -8,6 +8,8 @@ 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 { runCommentsCommand } from "./comments/comments-command.js";
+import { CommentsCommandError } from "./comments/errors.js";
 const STATUS_RANK = {
     draft: 0,
     revise: 1,
@@ -128,7 +130,7 @@ async function main() {
             case "new": {
                 activateWorkspace(options);
                 const project = resolveProject(readStringOption(options, "project"));
-                const createdPath = createNewManuscript(project, readStringOption(options, "i"));
+                const createdPath = createNewManuscript(project, readStringOption(options, "i"), readStringOption(options, "filename"));
                 logLine(`Created manuscript: ${createdPath}`);
                 return;
             }
@@ -196,11 +198,23 @@ async function main() {
                 logLine(`Export output: ${outputPath}`);
                 return;
             }
+            case "comments":
+                await runCommentsCommand(options, process.cwd());
+                return;
             default:
                 throw new Error(`Unknown command '${command}'. Run with 'help' for usage.`);
         }
     }
     catch (error) {
+        if (error instanceof CommentsCommandError) {
+            if (error.outputFormat === "json") {
+                console.error(JSON.stringify(error.toJson(), null, 2));
+            }
+            else {
+                console.error(`ERROR: ${error.message}`);
+            }
+            process.exit(error.exitCode);
+        }
         if (error instanceof Error) {
             console.error(`ERROR: ${error.message}`);
         }
@@ -372,7 +386,7 @@ function resolveCompileStructure(project) {
             issues.push(makeIssue("error", "metadata", `compileStructure.levels[${index}].titleKey must match /^[a-z][a-z0-9_-]*$/.`, projectFile));
             continue;
         }
-        const pageBreakRaw = typeof entry.pageBreak === "string" ? entry.pageBreak.trim() : "none";
+        const pageBreakRaw = typeof entry.pageBreak === "string" ? entry.pageBreak.trim() : "between-groups";
         if (pageBreakRaw !== "none" && pageBreakRaw !== "between-groups") {
             issues.push(makeIssue("error", "metadata", `compileStructure.levels[${index}].pageBreak must be 'none' or 'between-groups'.`, projectFile));
             continue;
@@ -416,7 +430,7 @@ function parseArgs(argv) {
         if (token.startsWith("--")) {
             const key = token.slice(2);
             const next = rest[i + 1];
-            if (!next || next.startsWith("-")) {
+            if (!next || !canBeOptionValue(next)) {
                 options[key] = true;
                 continue;
             }
@@ -427,7 +441,7 @@ function parseArgs(argv) {
         if (token.startsWith("-") && token.length > 1) {
             const key = token.slice(1);
             const next = rest[i + 1];
-            if (!next || next.startsWith("-")) {
+            if (!next || !canBeOptionValue(next)) {
                 options[key] = true;
                 continue;
             }
@@ -442,6 +456,12 @@ function parseArgs(argv) {
     }
     return { command, options };
 }
+function canBeOptionValue(token) {
+    if (token === "-") {
+        return true;
+    }
+    return !token.startsWith("-");
+}
 function resolveWorkspaceContext(rootOption) {
     if (rootOption) {
         const explicitRoot = path.resolve(process.cwd(), rootOption);
@@ -747,7 +767,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`);
+    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`);
 }
 function listProjects() {
     const ids = getProjectIds();
@@ -791,7 +811,7 @@ async function createProject(projectIdOption, titleOption) {
                     titleKey: "chapter_title",
                     injectHeading: true,
                     headingTemplate: "{label} {value}: {title}",
-                    pageBreak: "none"
+                    pageBreak: "between-groups"
                 }
             ]
         },
@@ -849,7 +869,7 @@ Start writing here.
         logLine(`- ${path.relative(repoRoot, projectSettingsPath)}`);
     }
 }
-function createNewManuscript(project, requestedPrefixRaw) {
+function createNewManuscript(project, requestedPrefixRaw, requestedFilenameRaw) {
     fs.mkdirSync(project.manuscriptDir, { recursive: true });
     const requiredMetadataState = resolveRequiredMetadata(project, config);
     const requiredMetadataErrors = requiredMetadataState.issues
@@ -860,13 +880,33 @@ function createNewManuscript(project, requestedPrefixRaw) {
     }
     const existingEntries = listManuscriptOrderEntries(project.manuscriptDir);
     const explicitPrefix = parseManuscriptPrefix(requestedPrefixRaw);
-    const nextPrefix = explicitPrefix ?? inferNextManuscriptPrefix(existingEntries);
-    const collision = existingEntries.find((entry) => entry.order === nextPrefix);
-    if (collision) {
-        throw new Error(`Manuscript prefix '${nextPrefix}' is already used by '${collision.filename}'. Re-run with --i <number> to choose an unused prefix.`);
+    const requestedFilename = parseRequestedManuscriptFilename(requestedFilenameRaw);
+    if (requestedFilename && explicitPrefix != null) {
+        throw new Error("Options --filename and --i/-i cannot be used together.");
+    }
+    let filename;
+    if (requestedFilename) {
+        const requestedOrder = parseOrderFromManuscriptFilename(requestedFilename);
+        if (requestedOrder != null) {
+            const collision = existingEntries.find((entry) => entry.order === requestedOrder);
+            if (collision) {
+                throw new Error(`Manuscript prefix '${requestedOrder}' is already used by '${collision.filename}'. Choose a different filename prefix.`);
+            }
+        }
+        filename = requestedFilename;
+    }
+    else {
+        const nextPrefix = explicitPrefix ?? inferNextManuscriptPrefix(existingEntries);
+        const collision = existingEntries.find((entry) => entry.order === nextPrefix);
+        if (collision) {
+            throw new Error(`Manuscript prefix '${nextPrefix}' is already used by '${collision.filename}'. Re-run with --i <number> to choose an unused prefix.`);
+        }
+        filename = `${nextPrefix}-${DEFAULT_NEW_MANUSCRIPT_SLUG}.md`;
     }
-    const filename = `${nextPrefix}-${DEFAULT_NEW_MANUSCRIPT_SLUG}.md`;
     const manuscriptPath = path.join(project.manuscriptDir, filename);
+    if (fs.existsSync(manuscriptPath)) {
+        throw new Error(`Manuscript already exists: ${filename}`);
+    }
     const content = renderNewManuscriptTemplate(requiredMetadataState.requiredMetadata);
     fs.writeFileSync(manuscriptPath, content, "utf8");
     return path.relative(repoRoot, manuscriptPath);
@@ -913,6 +953,33 @@ function parseManuscriptPrefix(raw) {
     }
     return parsed;
 }
+function parseRequestedManuscriptFilename(raw) {
+    if (raw == null) {
+        return undefined;
+    }
+    const normalized = raw.trim();
+    if (!normalized) {
+        throw new Error("Option --filename requires a value.");
+    }
+    if (/[\\/]/.test(normalized)) {
+        throw new Error(`Invalid filename '${raw}'. Use a filename only (no directory separators).`);
+    }
+    const withExtension = normalized.toLowerCase().endsWith(".md")
+        ? normalized
+        : `${normalized}.md`;
+    const stem = withExtension.slice(0, -3).trim();
+    if (!stem) {
+        throw new Error(`Invalid filename '${raw}'.`);
+    }
+    return withExtension;
+}
+function parseOrderFromManuscriptFilename(filename) {
+    const match = filename.match(/^(\d+)[-_]/);
+    if (!match) {
+        return undefined;
+    }
+    return Number(match[1]);
+}
 function inferNextManuscriptPrefix(entries) {
     if (entries.length === 0) {
         return 100;
@@ -936,7 +1003,7 @@ function renderNewManuscriptTemplate(requiredMetadata) {
         seenKeys.add(normalized);
         lines.push(`${normalized}:`);
     }
-    lines.push("---", "", "# New Document", "");
+    lines.push("---", "");
     return `${lines.join("\n")}\n`;
 }
 function getProjectIds() {

package/package.json

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

package/projects/fiction-example/manuscript/200-at-the-wards.md

@@ -21,7 +21,7 @@ Matthaeus and Etienne recorded onset dates, households, trades, parish boundarie
 
 Her map was simple. Neighborhoods tied to the grain quay sickened first. Adjacent streets followed within days. The rest of the city came after. The pattern was consistent across three months of data.
 
-At the quay she showed them torn sackcloth from a riverside storehouse and asked what his conjunction tables would have predicted for this street, this month. Matthaeus answered in the terms his system provided: commerce might distribute the material substrate, but the disposition of bodies to receive corruption remained celestial. Agnes said that might be true and still leave the wrong people dead first.
+At the quay she showed them torn sackcloth from a riverside storehouse and asked what his conjunction tables would have predicted for this street, this month. Matthaeus answered in the terms his system provided: commerce might distribute corrupted matter, but the disposition of bodies to receive corruption remained celestial. Agnes said that might be true and still leave the wrong people dead first.
 
 He wrote her observation in the second ledger. He expected to reconcile it later. The framework had room. It had been designed to have room.
 

package/projects/fiction-example/manuscript/300-the-hearing.md

@@ -17,7 +17,7 @@ sources:
 
 The faculty hearing began as a technical disputation and ended as an inquiry into method. Three masters objected to Matthaeus from different directions: one said he conceded too much to natural causes, another said he conceded too much to celestial judgment, a third said he imported suspect languages from Arabic traditions into Christian medicine. The objections were mutually exclusive, which should have cancelled them out but instead compounded them, because the real charge was not error but imprudence.
 
-Raoul asked to see all sources. John presented the conjunction tables and the Galenic commentaries openly. He withheld the quire until asked a second time. When he produced it, the room changed temperature.
+Raoul asked to see all sources. Matthaeus presented the conjunction tables and the Galenic commentaries openly. He withheld the quire until asked a second time. When he produced it, the room changed temperature.
 
 No one accused him of sorcery. They accused him of carelessness: in a season of mass death, even method could scandalize if its lineage looked foreign or secretive or insufficiently authorized. The problem was not what the quire said. The problem was that Matthaeus had kept it at all — that he had judged for himself which sources were useful and which were not, without waiting to be told.
 

package/projects/stego-docs/spine/commands.md

@@ -26,9 +26,9 @@ label: stego new-project --project <project-id> [--title <title>] [--root <path>
 - Related concepts: CON-PROJECT, CON-MANUSCRIPT, CON-NOTES, CON-DIST.
 
 ## CMD-NEW
-label: stego new --project <project-id> [--i <prefix>|-i <prefix>] [--root <path>]
+label: stego new --project <project-id> [--i <prefix>|-i <prefix>] [--filename <name>] [--root <path>]
 
-- `stego new --project <project-id> [--i <prefix>|-i <prefix>] [--root <path>]`
+- `stego new --project <project-id> [--i <prefix>|-i <prefix>] [--filename <name>] [--root <path>]`
 - Create a new manuscript file with an inferred numeric prefix and draft frontmatter.
 - Related workflows: FLOW-DAILY-WRITING.
 - Related concepts: CON-MANUSCRIPT, CON-METADATA.