stego-cli 0.1.6 → 0.2.0

package/.markdownlint.manuscript.json

@@ -0,0 +1,8 @@
+{
+  "default": true,
+  "MD013": false,
+  "MD033": false,
+  "MD026": false,
+  "MD036": false,
+  "MD041": false
+}

package/README.md

@@ -19,6 +19,7 @@ npm install
 stego list-projects
 stego validate --project fiction-example
 stego build --project fiction-example
+stego new --project fiction-example
 ```
 
 `stego init` scaffolds two example projects:
@@ -26,7 +27,7 @@ stego build --project fiction-example
 - `stego-docs` (the full documentation project)
 - `fiction-example` (a fiction-oriented demo with rich Spine usage)
 
-For day-to-day editing, open a project folder in VS Code (for example `projects/stego-docs`) and use the Stego VS Code extension, which is the official UI for Stego projects.
+For day-to-day editing, open a project folder in VS Code (for example `projects/stego-docs`) and use the [Stego VS Code extension](https://github.com/matt-gold/stego-extension), which is the official UI for Stego projects.
 
 ## Full documentation
 
@@ -48,6 +49,7 @@ Run commands from the workspace root and target a project with `--project`.
 ```bash
 stego list-projects
 stego new-project --project my-book --title "My Book"
+stego new --project fiction-example
 stego validate --project fiction-example
 stego build --project fiction-example
 stego check-stage --project fiction-example --stage revise

package/dist/stego-cli.js

@@ -16,6 +16,7 @@ const STATUS_RANK = {
     final: 4
 };
 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 SCAFFOLD_GITIGNORE_CONTENT = `node_modules/
@@ -54,6 +55,7 @@ stego validate --project fiction-example
 stego build --project fiction-example
 stego check-stage --project fiction-example --stage revise
 stego export --project fiction-example --format md
+stego new --project fiction-example
 \`\`\`
 
 ## Work inside one project
@@ -77,6 +79,12 @@ This keeps your editor context focused and applies the project's recommended ext
 \`\`\`bash
 stego new-project --project my-book --title "My Book"
 \`\`\`
+
+## Add a new manuscript file
+
+\`\`\`bash
+stego new --project fiction-example
+\`\`\`
 `;
 const PROSE_MARKDOWN_EDITOR_SETTINGS = {
     "[markdown]": {
@@ -117,6 +125,13 @@ async function main() {
                 activateWorkspace(options);
                 await createProject(readStringOption(options, "project"), readStringOption(options, "title"));
                 return;
+            case "new": {
+                activateWorkspace(options);
+                const project = resolveProject(readStringOption(options, "project"));
+                const createdPath = createNewManuscript(project, readStringOption(options, "i"));
+                logLine(`Created manuscript: ${createdPath}`);
+                return;
+            }
             case "validate": {
                 activateWorkspace(options);
                 const project = resolveProject(readStringOption(options, "project"));
@@ -157,6 +172,18 @@ async function main() {
                 }
                 return;
             }
+            case "lint": {
+                activateWorkspace(options);
+                const project = resolveProject(readStringOption(options, "project"));
+                const selection = resolveLintSelection(options);
+                const result = runProjectLint(project, selection);
+                printReport(result.issues);
+                exitIfErrors(result.issues);
+                const scopeLabel = formatLintSelection(selection);
+                const fileLabel = result.fileCount === 1 ? "file" : "files";
+                logLine(`Lint passed for '${project.id}' (${scopeLabel}, ${result.fileCount} ${fileLabel}).`);
+                return;
+            }
             case "export": {
                 activateWorkspace(options);
                 const project = resolveProject(readStringOption(options, "project"));
@@ -382,18 +409,36 @@ function parseArgs(argv) {
     const options = { _: [] };
     for (let i = 0; i < rest.length; i += 1) {
         const token = rest[i];
-        if (!token.startsWith("--")) {
-            options._.push(token);
+        if (token === "--") {
+            options._.push(...rest.slice(i + 1));
+            break;
+        }
+        if (token.startsWith("--")) {
+            const key = token.slice(2);
+            const next = rest[i + 1];
+            if (!next || next.startsWith("-")) {
+                options[key] = true;
+                continue;
+            }
+            options[key] = next;
+            i += 1;
             continue;
         }
-        const key = token.slice(2);
-        const next = rest[i + 1];
-        if (!next || next.startsWith("--")) {
-            options[key] = true;
+        if (token.startsWith("-") && token.length > 1) {
+            const key = token.slice(1);
+            const next = rest[i + 1];
+            if (!next || next.startsWith("-")) {
+                options[key] = true;
+                continue;
+            }
+            options[key] = next;
+            i += 1;
+            continue;
+        }
+        if (!token.startsWith("--")) {
+            options._.push(token);
             continue;
         }
-        options[key] = next;
-        i += 1;
     }
     return { command, options };
 }
@@ -464,6 +509,7 @@ async function initWorkspace(options) {
     writeScaffoldGitignore(targetRoot, copiedPaths);
     writeScaffoldReadme(targetRoot, copiedPaths);
     copyTemplateAsset(".markdownlint.json", targetRoot, copiedPaths);
+    copyTemplateAsset(".markdownlint.manuscript.json", targetRoot, copiedPaths);
     copyTemplateAsset(".cspell.json", targetRoot, copiedPaths);
     copyTemplateAsset(ROOT_CONFIG_FILENAME, targetRoot, copiedPaths);
     copyTemplateAsset("projects", targetRoot, copiedPaths);
@@ -594,6 +640,7 @@ function rewriteTemplateProjectPackageScripts(targetRoot) {
         scripts.build = "npx --no-install stego build";
         scripts["check-stage"] = "npx --no-install stego check-stage";
         scripts.export = "npx --no-install stego export";
+        scripts.new = "npx --no-install stego new";
         projectPackage.scripts = scripts;
         fs.writeFileSync(packageJsonPath, `${JSON.stringify(projectPackage, null, 2)}\n`, "utf8");
         ensureProjectExtensionsRecommendations(projectRoot);
@@ -684,6 +731,8 @@ function writeInitRootPackageJson(targetRoot) {
         scripts: {
             "list-projects": "stego list-projects",
             "new-project": "stego new-project",
+            new: "stego new",
+            lint: "stego lint",
             validate: "stego validate",
             build: "stego build",
             "check-stage": "stego check-stage",
@@ -698,7 +747,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  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  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`);
 }
 function listProjects() {
     const ids = getProjectIds();
@@ -729,6 +778,7 @@ async function createProject(projectIdOption, titleOption) {
     const notesDir = path.join(projectRoot, config.notesDir);
     fs.mkdirSync(notesDir, { recursive: true });
     fs.mkdirSync(path.join(projectRoot, config.distDir), { recursive: true });
+    const manuscriptDir = path.join(projectRoot, config.chapterDir);
     const projectJson = {
         id: projectId,
         title: titleOption?.trim() || toDisplayTitle(projectId),
@@ -759,6 +809,8 @@ async function createProject(projectIdOption, titleOption) {
         name: `stego-project-${projectId}`,
         private: true,
         scripts: {
+            new: "npx --no-install stego new",
+            lint: "npx --no-install stego lint",
             validate: "npx --no-install stego validate",
             build: "npx --no-install stego build",
             "check-stage": "npx --no-install stego check-stage",
@@ -767,6 +819,17 @@ async function createProject(projectIdOption, titleOption) {
     };
     const projectPackagePath = path.join(projectRoot, "package.json");
     fs.writeFileSync(projectPackagePath, `${JSON.stringify(projectPackage, null, 2)}\n`, "utf8");
+    const starterManuscriptPath = path.join(manuscriptDir, "100-hello-world.md");
+    fs.writeFileSync(starterManuscriptPath, `---
+status: draft
+chapter: 1
+chapter_title: Hello World
+---
+
+# Hello World
+
+Start writing here.
+`, "utf8");
     const charactersNotesPath = path.join(spineDir, "characters.md");
     fs.writeFileSync(charactersNotesPath, "# Characters\n\n", "utf8");
     const projectExtensionsPath = path.join(projectRoot, ".vscode", "extensions.json");
@@ -779,12 +842,103 @@ async function createProject(projectIdOption, titleOption) {
     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, projectExtensionsPath)}`);
     if (projectSettingsPath) {
         logLine(`- ${path.relative(repoRoot, projectSettingsPath)}`);
     }
 }
+function createNewManuscript(project, requestedPrefixRaw) {
+    fs.mkdirSync(project.manuscriptDir, { recursive: true });
+    const requiredMetadataState = resolveRequiredMetadata(project, config);
+    const requiredMetadataErrors = requiredMetadataState.issues
+        .filter((issue) => issue.level === "error")
+        .map((issue) => issue.message);
+    if (requiredMetadataErrors.length > 0) {
+        throw new Error(`Unable to resolve required metadata for project '${project.id}': ${requiredMetadataErrors.join(" ")}`);
+    }
+    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 filename = `${nextPrefix}-${DEFAULT_NEW_MANUSCRIPT_SLUG}.md`;
+    const manuscriptPath = path.join(project.manuscriptDir, filename);
+    const content = renderNewManuscriptTemplate(requiredMetadataState.requiredMetadata);
+    fs.writeFileSync(manuscriptPath, content, "utf8");
+    return path.relative(repoRoot, manuscriptPath);
+}
+function listManuscriptOrderEntries(manuscriptDir) {
+    if (!fs.existsSync(manuscriptDir)) {
+        return [];
+    }
+    return fs
+        .readdirSync(manuscriptDir, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+        .map((entry) => {
+        const match = entry.name.match(/^(\d+)[-_]/);
+        if (!match) {
+            return null;
+        }
+        return {
+            order: Number(match[1]),
+            filename: entry.name
+        };
+    })
+        .filter((entry) => entry !== null)
+        .sort((a, b) => {
+        if (a.order === b.order) {
+            return a.filename.localeCompare(b.filename);
+        }
+        return a.order - b.order;
+    });
+}
+function parseManuscriptPrefix(raw) {
+    if (raw == null) {
+        return undefined;
+    }
+    const normalized = raw.trim();
+    if (!normalized) {
+        throw new Error("Option --i/-i requires a numeric value.");
+    }
+    if (!/^\d+$/.test(normalized)) {
+        throw new Error(`Invalid manuscript prefix '${raw}'. Use a non-negative integer.`);
+    }
+    const parsed = Number(normalized);
+    if (!Number.isSafeInteger(parsed)) {
+        throw new Error(`Invalid manuscript prefix '${raw}'. Use a smaller integer value.`);
+    }
+    return parsed;
+}
+function inferNextManuscriptPrefix(entries) {
+    if (entries.length === 0) {
+        return 100;
+    }
+    if (entries.length === 1) {
+        return entries[0].order + 100;
+    }
+    const previous = entries[entries.length - 2].order;
+    const latest = entries[entries.length - 1].order;
+    const step = latest - previous;
+    return latest + (step > 0 ? step : 1);
+}
+function renderNewManuscriptTemplate(requiredMetadata) {
+    const lines = ["---", "status: draft"];
+    const seenKeys = new Set(["status"]);
+    for (const key of requiredMetadata) {
+        const normalized = key.trim();
+        if (!normalized || seenKeys.has(normalized)) {
+            continue;
+        }
+        seenKeys.add(normalized);
+        lines.push(`${normalized}:`);
+    }
+    lines.push("---", "", "# New Document", "");
+    return `${lines.join("\n")}\n`;
+}
 function getProjectIds() {
     const projectsDir = path.join(repoRoot, config.projectsDir);
     if (!fs.existsSync(projectsDir)) {
@@ -1602,10 +1756,10 @@ function runStageCheck(project, runtimeConfig, stage, onlyFile) {
     const chapterPaths = report.chapters.map((chapter) => chapter.path);
     const spineWords = collectSpineWordsForSpellcheck(report.spineState.ids);
     if (policy.enforceMarkdownlint) {
-        issues.push(...runMarkdownlint(project, chapterPaths, true));
+        issues.push(...runMarkdownlint(project, chapterPaths, true, "manuscript"));
     }
     else {
-        issues.push(...runMarkdownlint(project, chapterPaths, false));
+        issues.push(...runMarkdownlint(project, chapterPaths, false, "manuscript"));
     }
     if (policy.enforceCSpell) {
         issues.push(...runCSpell(chapterPaths, true, spineWords));
@@ -1615,20 +1769,133 @@ function runStageCheck(project, runtimeConfig, stage, onlyFile) {
     }
     return { chapters: report.chapters, issues };
 }
-function runMarkdownlint(project, files, required) {
+function resolveLintSelection(options) {
+    const manuscript = readBooleanOption(options, "manuscript");
+    const spine = readBooleanOption(options, "spine");
+    if (!manuscript && !spine) {
+        return { manuscript: true, spine: true };
+    }
+    return { manuscript, spine };
+}
+function formatLintSelection(selection) {
+    if (selection.manuscript && selection.spine) {
+        return "manuscript + spine";
+    }
+    if (selection.manuscript) {
+        return "manuscript";
+    }
+    if (selection.spine) {
+        return "spine";
+    }
+    return "none";
+}
+function runProjectLint(project, selection) {
+    const issues = [];
+    let fileCount = 0;
+    if (selection.manuscript) {
+        const manuscriptFiles = collectTopLevelMarkdownFiles(project.manuscriptDir);
+        if (manuscriptFiles.length === 0) {
+            issues.push(makeIssue("error", "lint", `No manuscript markdown files found in ${project.manuscriptDir}`));
+        }
+        else {
+            fileCount += manuscriptFiles.length;
+            issues.push(...runMarkdownlint(project, manuscriptFiles, true, "manuscript"));
+        }
+    }
+    if (selection.spine) {
+        const spineLintState = collectSpineLintMarkdownFiles(project);
+        issues.push(...spineLintState.issues);
+        if (spineLintState.files.length > 0) {
+            fileCount += spineLintState.files.length;
+            issues.push(...runMarkdownlint(project, spineLintState.files, true, "default"));
+        }
+    }
+    if (fileCount === 0 && issues.length === 0) {
+        issues.push(makeIssue("error", "lint", `No markdown files found for lint scope '${formatLintSelection(selection)}' in project '${project.id}'.`));
+    }
+    return { issues, fileCount };
+}
+function collectSpineLintMarkdownFiles(project) {
+    const issues = [];
+    const files = new Set();
+    addMarkdownFilesFromDirectory(files, project.spineDir, true);
+    if (!fs.existsSync(project.spineDir)) {
+        issues.push(makeIssue("warning", "lint", `Missing spine directory: ${project.spineDir}`));
+    }
+    addMarkdownFilesFromDirectory(files, project.notesDir, true);
+    if (!fs.existsSync(project.notesDir)) {
+        issues.push(makeIssue("warning", "lint", `Missing notes directory: ${project.notesDir}`));
+    }
+    for (const file of collectTopLevelMarkdownFiles(project.root)) {
+        files.add(file);
+    }
+    const sortedFiles = Array.from(files).sort();
+    if (sortedFiles.length === 0) {
+        issues.push(makeIssue("error", "lint", `No spine/notes markdown files found in ${project.spineDir}, ${project.notesDir}, or project root.`));
+    }
+    return { files: sortedFiles, issues };
+}
+function collectTopLevelMarkdownFiles(directory) {
+    if (!fs.existsSync(directory) || !fs.statSync(directory).isDirectory()) {
+        return [];
+    }
+    return fs
+        .readdirSync(directory, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+        .map((entry) => path.join(directory, entry.name))
+        .sort();
+}
+function addMarkdownFilesFromDirectory(target, directory, recursive) {
+    if (!fs.existsSync(directory) || !fs.statSync(directory).isDirectory()) {
+        return;
+    }
+    const stack = [directory];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current) {
+            continue;
+        }
+        const entries = fs.readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of entries) {
+            const fullPath = path.join(current, entry.name);
+            if (entry.isFile() && entry.name.endsWith(".md")) {
+                target.add(fullPath);
+                continue;
+            }
+            if (recursive && entry.isDirectory()) {
+                stack.push(fullPath);
+            }
+        }
+    }
+}
+function runMarkdownlint(project, files, required, profile = "default") {
+    if (files.length === 0) {
+        return [];
+    }
     const markdownlintCommand = resolveCommand("markdownlint");
     if (!markdownlintCommand) {
         if (required) {
             return [
-                makeIssue("error", "tooling", "markdownlint is required for this stage but not installed. Run 'npm i' in the repo root.")
+                makeIssue("error", "tooling", "markdownlint is required for this command but not installed. Run 'npm i' in the repo root.")
             ];
         }
         return [];
     }
-    const projectConfigPath = path.join(project.root, ".markdownlint.json");
-    const markdownlintConfigPath = fs.existsSync(projectConfigPath)
-        ? projectConfigPath
-        : path.join(repoRoot, ".markdownlint.json");
+    const manuscriptProjectConfigPath = path.join(project.root, ".markdownlint.manuscript.json");
+    const manuscriptRepoConfigPath = path.join(repoRoot, ".markdownlint.manuscript.json");
+    const defaultProjectConfigPath = path.join(project.root, ".markdownlint.json");
+    const defaultRepoConfigPath = path.join(repoRoot, ".markdownlint.json");
+    const markdownlintConfigPath = profile === "manuscript"
+        ? (fs.existsSync(manuscriptProjectConfigPath)
+            ? manuscriptProjectConfigPath
+            : fs.existsSync(manuscriptRepoConfigPath)
+                ? manuscriptRepoConfigPath
+                : fs.existsSync(defaultProjectConfigPath)
+                    ? defaultProjectConfigPath
+                    : defaultRepoConfigPath)
+        : (fs.existsSync(defaultProjectConfigPath)
+            ? defaultProjectConfigPath
+            : defaultRepoConfigPath);
     const prepared = prepareFilesWithoutComments(files);
     try {
         const result = spawnSync(markdownlintCommand, ["--config", markdownlintConfigPath, ...prepared.files], {

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "stego-cli",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "type": "module",
   "description": "Installable CLI for the Stego writing monorepo workflow.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/matt-gold/stego.git"
+    "url": "https://github.com/matt-gold/stego-cli.git"
   },
   "bugs": {
-    "url": "https://github.com/matt-gold/stego/issues"
+    "url": "https://github.com/matt-gold/stego-cli/issues"
   },
-  "homepage": "https://github.com/matt-gold/stego#readme",
+  "homepage": "https://github.com/matt-gold/stego-cli#readme",
   "bin": {
     "stego": "dist/stego-cli.js"
   },
@@ -28,6 +28,7 @@
     ".vscode/extensions.json",
     ".gitignore",
     ".markdownlint.json",
+    ".markdownlint.manuscript.json",
     ".cspell.json",
     "stego.config.json",
     "README.md"
@@ -41,6 +42,8 @@
     "release:version": "changeset version",
     "list-projects": "node --experimental-strip-types tools/stego-cli.ts list-projects",
     "new-project": "node --experimental-strip-types tools/stego-cli.ts new-project",
+    "new": "node --experimental-strip-types tools/stego-cli.ts new",
+    "lint": "node --experimental-strip-types tools/stego-cli.ts lint",
     "validate": "node --experimental-strip-types tools/stego-cli.ts validate",
     "build": "node --experimental-strip-types tools/stego-cli.ts build",
     "check-stage": "node --experimental-strip-types tools/stego-cli.ts check-stage",

package/projects/fiction-example/.markdownlint.json

@@ -1,4 +1,5 @@
 {
   "default": true,
-  "MD041": false
+  "MD013": false,
+  "MD033": false
 }

package/projects/fiction-example/.markdownlint.manuscript.json

@@ -0,0 +1,8 @@
+{
+  "default": true,
+  "MD013": false,
+  "MD033": false,
+  "MD026": false,
+  "MD036": false,
+  "MD041": false
+}

package/projects/fiction-example/package.json

@@ -2,6 +2,7 @@
   "name": "stego-project-fiction-example",
   "private": true,
   "scripts": {
+    "new": "node --experimental-strip-types ../../tools/stego-cli.ts new",
     "validate": "node --experimental-strip-types ../../tools/stego-cli.ts validate",
     "build": "node --experimental-strip-types ../../tools/stego-cli.ts build",
     "check-stage": "node --experimental-strip-types ../../tools/stego-cli.ts check-stage",

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

@@ -1,6 +1,7 @@
 # Characters
 
 ## CHAR-MATTHAEUS
+label: Magister Matthaeus de Rota
 
 - Magister Matthaeus de Rota
 - Role: Scholar of medicine and astrology at the University of Paris
@@ -9,6 +10,7 @@
 - Arc: 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
 
 ## CHAR-ETIENNE
+label: Etienne of Saint-Marcel
 
 - Etienne of Saint-Marcel
 - Role: Young cleric-scribe attached to Matthaeus (CHAR-MATTHAEUS)
@@ -16,6 +18,7 @@
 - Function: The story's witness; records the system without fully believing it, but also without offering an alternative
 
 ## CHAR-AGNES
+label: Agnes the apothecary
 
 - Agnes the apothecary
 - Role: Compounder and practical healer near the Petit Pont; supplies Hôtel-Dieu (LOC-HOTELDIEU)
@@ -24,6 +27,7 @@
 - Function: The counterweight; asks whether a system that can absorb any evidence without changing is a system or a habit
 
 ## CHAR-RAOUL
+label: Canon Raoul de Villiers
 
 - Canon Raoul de Villiers
 - Role: Cathedral canon and royal intermediary overseeing the inquiry

package/projects/fiction-example/spine/locations.md

@@ -1,6 +1,7 @@
 # Locations
 
 ## LOC-COLLEGE
+label: College chamber near the Rue Saint-Jacques
 
 - College chamber near the Rue Saint-Jacques
 - Study and disputation room
@@ -9,6 +10,7 @@
 - Significance: The space where the system is built; physically separated from the wards and streets where the plague actually operates
 
 ## LOC-HOTELDIEU
+label: "Hôtel-Dieu"
 
 - Hôtel-Dieu
 - Hospital ward near Notre-Dame
@@ -17,6 +19,7 @@
 - Significance: Where data is collected; the distance between this room and the college chamber is the distance between observation and explanation
 
 ## LOC-QUAY
+label: Grain quay on the Seine
 
 - Grain quay on the Seine
 - River unloading zone
@@ -25,6 +28,7 @@
 - Significance: Agnes's observations (SRC-WARD-DATA) trace infection along this route; it is the strongest evidence for material transmission and the hardest for the celestial framework (SRC-CONJUNCTION) to accommodate
 
 ## LOC-CHARNEL
+label: Charnel precinct at the cemetery edge
 
 - Charnel precinct at the cemetery edge
 - Overflow burial ground

package/projects/fiction-example/spine/sources.md

@@ -1,6 +1,7 @@
 # Sources
 
 ## SRC-CONJUNCTION
+label: The Great Conjunction theory
 
 - The Great Conjunction theory
 - Tradition: University astrology ([Paris faculty opinion of 1348](https://en.wikipedia.org/wiki/Black_Death#Medical_knowledge))
@@ -10,6 +11,7 @@
 - Limitation: Explains everything at once, which means it predicts nothing in particular
 
 ## SRC-GALEN
+label: Galenic humoral medicine
 
 - Galenic humoral medicine
 - Tradition: Greco-Arabic medical inheritance
@@ -19,6 +21,7 @@
 - Limitation: Cannot explain why entire neighborhoods fall at once regardless of individual constitution
 
 ## SRC-WARD-DATA
+label: "Agnes's ward observations"
 
 - Agnes's ward observations
 - Tradition: None; empirical record-keeping without institutional backing

package/projects/stego-docs/manuscript/400-everyday-workflow-and-commands.md

@@ -10,6 +10,7 @@ concepts:
 commands:
   - CMD-LIST-PROJECTS
   - CMD-NEW-PROJECT
+  - CMD-NEW
   - CMD-VALIDATE
   - CMD-BUILD
   - CMD-CHECK-STAGE
@@ -41,6 +42,7 @@ From the workspace root, target a project with `--project`.
 
 ```bash
 stego list-projects
+stego new --project fiction-example
 stego validate --project fiction-example
 stego build --project fiction-example
 stego check-stage --project fiction-example --stage revise
@@ -53,6 +55,7 @@ Projects also include local npm scripts. These are useful when you want to stay
 
 ```bash
 cd projects/fiction-example
+npm run new
 npm run validate
 npm run build
 npm run check-stage -- --stage revise

package/projects/stego-docs/package.json

@@ -2,6 +2,7 @@
   "name": "stego-project-stego-docs",
   "private": true,
   "scripts": {
+    "new": "node --experimental-strip-types ../../tools/stego-cli.ts new",
     "validate": "node --experimental-strip-types ../../tools/stego-cli.ts validate",
     "build": "node --experimental-strip-types ../../tools/stego-cli.ts build",
     "check-stage": "node --experimental-strip-types ../../tools/stego-cli.ts check-stage",

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

@@ -1,6 +1,7 @@
 # Commands
 
 ## CMD-INIT
+label: stego init [--force]
 
 - `stego init [--force]`
 - Initialize a Stego workspace in the current directory.
@@ -9,6 +10,7 @@
 - Related integrations: INT-VSCODE.
 
 ## CMD-LIST-PROJECTS
+label: stego list-projects [--root <path>]
 
 - `stego list-projects [--root <path>]`
 - List projects found in the current workspace.
@@ -16,13 +18,24 @@
 - Related concepts: CON-WORKSPACE, CON-PROJECT.
 
 ## CMD-NEW-PROJECT
+label: stego new-project --project <project-id> [--title <title>] [--root <path>]
 
 - `stego new-project --project <project-id> [--title <title>] [--root <path>]`
 - Scaffold a new project under `projects/`.
 - Related workflows: FLOW-NEW-PROJECT.
 - Related concepts: CON-PROJECT, CON-MANUSCRIPT, CON-NOTES, CON-DIST.
 
+## CMD-NEW
+label: stego new --project <project-id> [--i <prefix>|-i <prefix>] [--root <path>]
+
+- `stego new --project <project-id> [--i <prefix>|-i <prefix>] [--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.
+- Related configuration: CFG-REQUIRED-METADATA.
+
 ## CMD-VALIDATE
+label: stego validate --project <project-id> [--file <project-relative-manuscript-path>] [--root <path>]
 
 - `stego validate --project <project-id> [--file <project-relative-manuscript-path>] [--root <path>]`
 - Validate project configuration, manuscript structure, metadata, and references.
@@ -31,6 +44,7 @@
 - Related configuration: CFG-REQUIRED-METADATA, CFG-SPINE-CATEGORIES.
 
 ## CMD-BUILD
+label: stego build --project <project-id> [--root <path>]
 
 - `stego build --project <project-id> [--root <path>]`
 - Compile manuscript files into one generated markdown output.
@@ -39,6 +53,7 @@
 - Related configuration: CFG-COMPILE-STRUCTURE, CFG-COMPILE-LEVELS.
 
 ## CMD-CHECK-STAGE
+label: stego check-stage --project <project-id> --stage <draft|revise|line-edit|proof|final> [--file <project-relative-manuscript-path>] [--root <path>]
 
 - `stego check-stage --project <project-id> --stage <draft|revise|line-edit|proof|final> [--file <project-relative-manuscript-path>] [--root <path>]`
 - Run stage-aware checks for a requested editorial stage.
@@ -47,6 +62,7 @@
 - Related configuration: CFG-STAGE-POLICIES, CFG-ALLOWED-STATUSES.
 
 ## CMD-EXPORT
+label: stego export --project <project-id> --format <md|docx|pdf|epub> [--output <path>] [--root <path>]
 
 - `stego export --project <project-id> --format <md|docx|pdf|epub> [--output <path>] [--root <path>]`
 - Export compiled output to target formats.

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

@@ -1,48 +1,56 @@
 # Concepts
 
 ## CON-WORKSPACE
+label: A Stego workspace is the root directory containing `stego.config.json` and `projects/`.
 
 - A Stego workspace is the root directory containing `stego.config.json` and `projects/`.
 - Related commands: CMD-INIT, CMD-LIST-PROJECTS.
 - Related workflows: FLOW-INIT-WORKSPACE.
 
 ## CON-PROJECT
+label: A project is one writing unit inside `projects/<project-id>/` with its own `stego-project.json` and manuscript files in `/projects/<project-id>/manuscripts`.
 
 - A project is one writing unit inside `projects/<project-id>/` with its own `stego-project.json` and manuscript files in `/projects/<project-id>/manuscripts`.
 - Related commands: CMD-NEW-PROJECT, CMD-VALIDATE, CMD-BUILD.
 - Related workflows: FLOW-NEW-PROJECT, FLOW-DAILY-WRITING.
 
 ## CON-MANUSCRIPT
+label: `manuscript/` contains canonical source writing files ordered by filename prefix.
 
 - `manuscript/` contains canonical source writing files ordered by filename prefix.
 - Related commands: CMD-VALIDATE, CMD-BUILD.
 - Related configuration: CFG-REQUIRED-METADATA, CFG-COMPILE-STRUCTURE.
 
 ## CON-SPINE
+label: `spine/` stores canonical entities used for continuity and navigation.
 
 - `spine/` stores canonical entities used for continuity and navigation.
 - Related configuration: CFG-SPINE-CATEGORIES.
 - Related integrations: INT-STEGO-EXTENSION.
 
 ## CON-NOTES
+label: `notes/` contains supporting material that is not part of compiled manuscript output.
 
 - `notes/` contains supporting material that is not part of compiled manuscript output.
 - Related commands: CMD-NEW-PROJECT.
 - Related workflows: FLOW-DAILY-WRITING.
 
 ## CON-DIST
+label: `dist/` is generated output only and can be rebuilt from sources.
 
 - `dist/` is generated output only and can be rebuilt from sources.
 - Related commands: CMD-BUILD, CMD-EXPORT.
 - Related workflows: FLOW-BUILD-EXPORT, FLOW-PROOF-RELEASE.
 
 ## CON-METADATA
+label: "Frontmatter metadata drives validation, stage checks, grouping, and continuity references."
 
 - Frontmatter metadata drives validation, stage checks, grouping, and continuity references.
 - Related commands: CMD-VALIDATE, CMD-CHECK-STAGE.
 - Related configuration: CFG-REQUIRED-METADATA, CFG-ALLOWED-STATUSES.
 
 ## CON-STAGE-GATE
+label: Stage gates apply stricter checks as work moves from drafting to release.
 
 - Stage gates apply stricter checks as work moves from drafting to release.
 - Related commands: CMD-CHECK-STAGE.
@@ -50,12 +58,14 @@
 - Related configuration: CFG-STAGE-POLICIES.
 
 ## CON-COMPILE-STRUCTURE
+label: Compile structure groups ordered files into larger sections during build.
 
 - Compile structure groups ordered files into larger sections during build.
 - Related commands: CMD-BUILD.
 - Related configuration: CFG-COMPILE-STRUCTURE, CFG-COMPILE-LEVELS.
 
 ## CON-SPINE-CATEGORY
+label: "A spine category defines a metadata key, ID prefix, and canonical notes file."
 
 - A spine category defines a metadata key, ID prefix, and canonical notes file.
 - Related concepts: CON-SPINE, CON-METADATA.

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

@@ -1,48 +1,56 @@
 # Configuration
 
 ## CFG-STEGO-CONFIG
+label: Workspace-level configuration in `stego.config.json` defines shared directories and stage policies.
 
 - Workspace-level configuration in `stego.config.json` defines shared directories and stage policies.
 - Related concepts: CON-WORKSPACE.
 - Related commands: CMD-LIST-PROJECTS, CMD-CHECK-STAGE.
 
 ## CFG-STEGO-PROJECT
+label: "Project-level configuration in `stego-project.json` defines metadata rules, grouping, and spine categories."
 
 - Project-level configuration in `stego-project.json` defines metadata rules, grouping, and spine categories.
 - Related concepts: CON-PROJECT, CON-METADATA, CON-SPINE.
 - Related commands: CMD-VALIDATE, CMD-BUILD.
 
 ## CFG-REQUIRED-METADATA
+label: Advisory list of frontmatter keys expected in manuscript files.
 
 - Advisory list of frontmatter keys expected in manuscript files.
 - Related concepts: CON-METADATA.
 - Related commands: CMD-VALIDATE.
 
 ## CFG-COMPILE-STRUCTURE
+label: Build grouping configuration that defines structural levels and heading behavior.
 
 - Build grouping configuration that defines structural levels and heading behavior.
 - Related concepts: CON-COMPILE-STRUCTURE.
 - Related commands: CMD-BUILD.
 
 ## CFG-COMPILE-LEVELS
+label: "The ordered `levels` array inside compile structure, with keys, labels, title keys, and page break options."
 
 - The ordered `levels` array inside compile structure, with keys, labels, title keys, and page break options.
 - Related configuration: CFG-COMPILE-STRUCTURE.
 - Related concepts: CON-COMPILE-STRUCTURE.
 
 ## CFG-SPINE-CATEGORIES
+label: Per-project category definitions mapping metadata keys to ID prefixes and spine files.
 
 - Per-project category definitions mapping metadata keys to ID prefixes and spine files.
 - Related concepts: CON-SPINE, CON-SPINE-CATEGORY.
 - Related commands: CMD-VALIDATE.
 
 ## CFG-STAGE-POLICIES
+label: Stage policy settings determine which checks are enforced at each stage.
 
 - Stage policy settings determine which checks are enforced at each stage.
 - Related concepts: CON-STAGE-GATE.
 - Related commands: CMD-CHECK-STAGE.
 
 ## CFG-ALLOWED-STATUSES
+label: Workspace-level list of allowed manuscript statuses.
 
 - Workspace-level list of allowed manuscript statuses.
 - Related concepts: CON-METADATA, CON-STAGE-GATE.

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

@@ -1,36 +1,42 @@
 # Integrations
 
 ## INT-VSCODE
+label: VS Code is the primary editor environment for Stego projects.
 
 - VS Code is the primary editor environment for Stego projects.
 - Related workflows: FLOW-INIT-WORKSPACE, FLOW-DAILY-WRITING.
 - Related commands: CMD-INIT.
 
 ## INT-STEGO-EXTENSION
+label: "The Stego VS Code extension is the official UI for Stego projects, including status controls, checks, and Spine Browser navigation."
 
 - The Stego VS Code extension is the official UI for Stego projects, including status controls, checks, and Spine Browser navigation.
 - Related concepts: CON-SPINE, CON-STAGE-GATE.
 - Related workflows: FLOW-DAILY-WRITING, FLOW-STAGE-PROMOTION.
 
 ## INT-SAURUS-EXTENSION
+label: The Saurus extension complements prose editing and research workflows in project folders.
 
 - The Saurus extension complements prose editing and research workflows in project folders.
 - Related integrations: INT-VSCODE.
 - Related workflows: FLOW-DAILY-WRITING.
 
 ## INT-PANDOC
+label: "Pandoc is used for optional export formats such as docx, pdf, and epub."
 
 - Pandoc is used for optional export formats such as docx, pdf, and epub.
 - Related commands: CMD-EXPORT.
 - Related workflows: FLOW-BUILD-EXPORT.
 
 ## INT-MARKDOWNLINT
+label: Markdownlint is used in stricter proofreading and release stages.
 
 - Markdownlint is used in stricter proofreading and release stages.
 - Related concepts: CON-STAGE-GATE.
 - Related workflows: FLOW-PROOF-RELEASE.
 
 ## INT-CSPELL
+label: CSpell supports spelling and terminology checks during later-stage quality passes.
 
 - CSpell supports spelling and terminology checks during later-stage quality passes.
 - Related concepts: CON-STAGE-GATE.

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

@@ -1,12 +1,14 @@
 # Workflows
 
 ## FLOW-INIT-WORKSPACE
+label: "Install the CLI, initialize a workspace, install local dev tools, and inspect scaffolded projects."
 
 - Install the CLI, initialize a workspace, install local dev tools, and inspect scaffolded projects.
 - Related commands: CMD-INIT, CMD-LIST-PROJECTS.
 - Related concepts: CON-WORKSPACE, CON-PROJECT.
 
 ## FLOW-DAILY-WRITING
+label: "Open one project, write in manuscript files, validate, build, and commit progress."
 
 - Open one project, write in manuscript files, validate, build, and commit progress.
 - Related commands: CMD-VALIDATE, CMD-BUILD.
@@ -14,6 +16,7 @@
 - Related integrations: INT-VSCODE.
 
 ## FLOW-NEW-PROJECT
+label: "Create a new project, review generated folders, and configure project metadata rules."
 
 - Create a new project, review generated folders, and configure project metadata rules.
 - Related commands: CMD-NEW-PROJECT, CMD-VALIDATE.
@@ -21,6 +24,7 @@
 - Related configuration: CFG-STEGO-PROJECT.
 
 ## FLOW-STAGE-PROMOTION
+label: Move files through statuses and verify readiness with stage checks.
 
 - Move files through statuses and verify readiness with stage checks.
 - Related commands: CMD-CHECK-STAGE, CMD-VALIDATE.
@@ -28,6 +32,7 @@
 - Related configuration: CFG-STAGE-POLICIES, CFG-ALLOWED-STATUSES.
 
 ## FLOW-BUILD-EXPORT
+label: Build a compiled markdown manuscript and export distribution formats.
 
 - Build a compiled markdown manuscript and export distribution formats.
 - Related commands: CMD-BUILD, CMD-EXPORT.
@@ -35,6 +40,7 @@
 - Related integrations: INT-PANDOC.
 
 ## FLOW-PROOF-RELEASE
+label: "Run strict checks, build outputs, export artifacts, and archive release files."
 
 - Run strict checks, build outputs, export artifacts, and archive release files.
 - Related commands: CMD-CHECK-STAGE, CMD-BUILD, CMD-EXPORT.