stego-cli 0.1.5 → 0.1.6

package/.gitignore

@@ -6,3 +6,4 @@ projects/*/dist/*
 !projects/*/dist/.gitkeep
 projects/*/.vscode/settings.json
 .vscode/settings.json
+local-only/

package/README.md

@@ -1,22 +1,12 @@
-# Stego
+# Stego CLI
 
-Stego is a Markdown-first creative writing workflow packaged as an installable CLI: `stego-cli`.
+`stego-cli` is an installable CLI for the Stego writing workflow.
 
-This repository is the source for the CLI and the example/template content that `stego init` scaffolds into a new workspace.
+It scaffolds a Stego workspace, validates manuscript structure and metadata, runs stage-aware quality gates, builds compiled markdown outputs, and exports release formats.
 
-## What this includes
+This repository is the source for the CLI and the template/example projects that `stego init` scaffolds.
 
-- Installable CLI (`stego`) for creating and operating Stego workspaces
-- Project-per-folder structure inside one monorepo.
-- Flexible manuscript files with per-project metadata requirements.
-- Configurable manuscript grouping via `compileStructure.levels` (for example `part` + `chapter`).
-- Project-defined spine categories (configured in each `stego-project.json`).
-- Deterministic build into one manuscript Markdown file.
-- Stage-based quality gates (`draft` -> `final`).
-- Export abstraction (`md` always, `docx`/`pdf` via optional `pandoc`).
-- Example/demo projects (`docs-demo`, `plague-demo`) included in `stego init`.
-
-## Getting started (from npm)
+## Quick start (install + init)
 
 ```bash
 npm install -g stego-cli
@@ -24,73 +14,69 @@ npm install -g stego-cli
 mkdir my-stego-workspace
 cd my-stego-workspace
 stego init
-
 npm install
-npm run list-projects
-npm run validate -- --project plague-demo
-npm run build -- --project plague-demo
-npm run check-stage -- --project plague-demo --stage revise
-npm run export -- --project plague-demo --format md
+
+stego list-projects
+stego validate --project fiction-example
+stego build --project fiction-example
 ```
 
-`stego init` scaffolds a new workspace in the current directory (it must be empty unless you pass `--force`).
+`stego init` scaffolds two example projects:
 
-Create another project in the workspace:
+- `stego-docs` (the full documentation project)
+- `fiction-example` (a fiction-oriented demo with rich Spine usage)
 
-```bash
-stego new-project --project my-new-project --title "My New Project"
-```
+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.
+
+## Full documentation
 
-`stego new-project` scaffolds `manuscript/`, `spine/`, `notes/`, and `dist/`, seeds `stego-project.json`, creates a project-local `package.json`, and writes `.vscode/extensions.json` recommendations (Stego + Saurus) for that project.
+The full user documentation lives in the `stego-docs` project.
 
-## Running commands for a specific project
+- In a scaffolded workspace: `projects/stego-docs`
+- In this source repo: `projects/stego-docs`
 
-From the workspace root, target a project with `--project`:
+Start by reading the manuscript files in order, or build the docs project:
 
 ```bash
-npm run validate -- --project plague-demo
-npm run build -- --project plague-demo
-npm run check-stage -- --project plague-demo --stage proof
-npm run export -- --project plague-demo --format md
+stego build --project stego-docs
 ```
 
-Each project also has local scripts, so you can work from inside the project directory:
+## Core commands
+
+Run commands from the workspace root and target a project with `--project`.
 
 ```bash
-cd projects/plague-demo
-npm run validate
-npm run build
-npm run check-stage -- --stage proof
-npm run export -- --format md
+stego list-projects
+stego new-project --project my-book --title "My Book"
+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
 ```
 
-## VS Code workflow
+Projects also include local npm scripts so you can work from inside a project directory.
 
-When you are actively working on one project, open that project directory directly in VS Code (for example `projects/plague-demo`) rather than the whole workspace.
+## VS Code workflow
 
-This keeps editor context focused and applies the project's recommended extensions via `projects/<project-id>/.vscode/extensions.json`.
+When actively working on one project, open that project directory directly in VS Code (for example `projects/fiction-example`).
 
-## Developing `stego-cli` (this repo)
+The Stego VS Code extension is the official UI for Stego projects, and opening a single project keeps its UI context and Spine Browser focused. Project folders also include extension recommendations.
 
-If you are working on the CLI itself (this repository), use the local development scripts:
+## Develop `stego-cli` (this repo)
 
 ```bash
 npm install
 npm run list-projects
-npm run validate -- --project docs-demo
-npm run build -- --project plague-demo
-npm run test:compile-structure
+npm run validate -- --project stego-docs
+npm run build -- --project fiction-example
+npm run test
 npm run build:cli
 npm run pack:dry-run
 ```
 
-These source-repo scripts run the TypeScript CLI directly with Node (`--experimental-strip-types`) for local development.
-
-## Export requirements (DOCX/PDF)
+## Export requirements (`docx`, `pdf`, `epub`)
 
-`docx` and `pdf` export require `pandoc` on your system `PATH`.
-
-Install:
+These formats require `pandoc` on your `PATH`.
 
 ```bash
 # macOS (Homebrew)
@@ -106,139 +92,3 @@ sudo apt-get update && sudo apt-get install -y pandoc
 # Windows (winget)
 winget install --id JohnMacFarlane.Pandoc -e
 ```
-
-Verify:
-
-```bash
-pandoc --version
-```
-
-Then run:
-
-```bash
-npm run export -- --project plague-demo --format docx
-npm run export -- --project plague-demo --format pdf
-```
-
-## Scaffolded workspace layout
-
-- `projects/<project-id>/manuscript/` source manuscript files
-- `projects/<project-id>/spine/` canonical spine category files (`spineCategories[*].notesFile`)
-- `projects/<project-id>/notes/` regular notes and planning docs
-- `projects/<project-id>/dist/` generated outputs only
-- `stego.config.json` workspace configuration
-- `docs/` workflow and conventions
-- `.vscode/tasks.json` root VS Code tasks for common Stego commands
-
-## This repo layout (`stego-cli` source)
-
-- `tools/` CLI source code and exporters
-- `projects/` template/demo projects bundled by `stego init`
-- `docs/` user-facing docs copied into scaffolded workspaces
-- `.github/workflows/` CI + Changesets release automation
-
-## Project spine categories
-
-Spine categories are not fixed. Each project can declare them in `stego-project.json` under `spineCategories`.
-
-Example:
-
-```json
-{
-  "spineCategories": [
-    { "key": "cast", "prefix": "CHAR", "notesFile": "characters.md" },
-    { "key": "places", "prefix": "LOC", "notesFile": "locations.md" },
-    { "key": "incidents", "prefix": "EVENT", "notesFile": "timeline.md" },
-    { "key": "ordinances", "prefix": "STATUTE", "notesFile": "ordinances.md" }
-  ]
-}
-```
-
-Use those keys as metadata arrays in manuscript files (for example `cast`, `places`, `incidents`, `ordinances`).
-Each `notesFile` is a filename resolved in `spine/` (for example `spine/characters.md`).
-
-If `spineCategories` is omitted or empty, category-based continuity validation is disabled.
-
-## Project metadata requirements
-
-Base config defaults to `status`.
-
-Each project can override required keys in `stego-project.json`:
-
-```json
-{
-  "requiredMetadata": ["status", "chapter", "pov", "timeline"]
-}
-```
-
-These keys are advisory and reported as warnings when missing; they do not block validate/build/export.
-Files may omit metadata entirely.
-
-## Compile structure (grouped manuscript output)
-
-Build grouping is configured per project with `compileStructure.levels`.
-
-Example:
-
-```json
-{
-  "compileStructure": {
-    "levels": [
-      {
-        "key": "part",
-        "label": "Part",
-        "titleKey": "part_title",
-        "injectHeading": true,
-        "headingTemplate": "{label} {value}: {title}",
-        "pageBreak": "between-groups"
-      },
-      {
-        "key": "chapter",
-        "label": "Chapter",
-        "titleKey": "chapter_title",
-        "injectHeading": true,
-        "headingTemplate": "{label} {value}: {title}",
-        "pageBreak": "between-groups"
-      }
-    ]
-  }
-}
-```
-
-Notes:
-
-- `pageBreak` currently supports `none` or `between-groups`.
-- TOC entries are nested by level depth.
-- Missing group key/title values inherit from the previous manuscript file, so you only need to set metadata at structural boundaries.
-- `validate` reports configuration errors for invalid `compileStructure` entries.
-
-## Included examples
-
-- `plague-demo`: full configuration — rich metadata (`pov`, `timeline`), three spine categories (`characters`, `locations`, `sources`), cross-linked spine with Wikipedia reference links
-- `docs-demo`: nonfiction documentation configuration — no spine categories, freeform notes only, primarily `status` metadata
-
-## Placeholder edit workflow (`{{...}}` + Cmd+I)
-
-This repo includes Copilot instruction files to keep placeholder edits scoped:
-
-- `.github/copilot-instructions.md`
-- `.github/instructions/placeholder-fill.instructions.md`
-
-Placeholder convention:
-
-- Write draft placeholders as `{{...}}` in manuscript prose.
-- Select the placeholder text and run Cmd+I.
-- Use short prompts like `fill placeholder` or `replace only inside {{}}`.
-
-Expected behavior:
-
-- Replace only the content inside braces.
-- Preserve surrounding sentence/paragraph text.
-
-## Next Steps
-
-- Add Mermaid graphs of metadata (entity relationships, co-occurrence, chapter sequence).
-
-## VS Code tasks
-
-Tasks are defined in `.vscode/tasks.json` for validate/build/stage-check/export.

package/dist/stego-cli.js

@@ -34,25 +34,26 @@ This directory is a Stego writing workspace (a monorepo for one or more writing
 ## What was scaffolded
 
 - \`stego.config.json\` workspace configuration
-- \`projects/\` demo projects (\`docs-demo\` and \`plague-demo\`)
-- \`docs/\` workflow and conventions docs
+- \`projects/\` demo projects (\`stego-docs\` and \`fiction-example\`)
 - root \`package.json\` scripts for Stego commands
 - root \`.vscode/tasks.json\` tasks for common workflows
 
+Full documentation lives in \`projects/stego-docs\`.
+
 ## First run
 
 \`\`\`bash
 npm install
-npm run list-projects
+stego list-projects
 \`\`\`
 
 ## Run commands for a specific project (from workspace root)
 
 \`\`\`bash
-npm run validate -- --project plague-demo
-npm run build -- --project plague-demo
-npm run check-stage -- --project plague-demo --stage revise
-npm run export -- --project plague-demo --format md
+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
 \`\`\`
 
 ## Work inside one project
@@ -60,14 +61,14 @@ npm run export -- --project plague-demo --format md
 Each project also has local scripts, so you can run commands from inside a project directory:
 
 \`\`\`bash
-cd projects/plague-demo
+cd projects/fiction-example
 npm run validate
 npm run build
 \`\`\`
 
 ## VS Code recommendation
 
-When you are actively working on one project, open that project directory directly in VS Code (for example \`projects/plague-demo\`).
+When you are actively working on one project, open that project directory directly in VS Code (for example \`projects/fiction-example\`).
 
 This keeps your editor context focused and applies the project's recommended extensions (including Stego + Saurus) for that project.
 
@@ -465,7 +466,6 @@ async function initWorkspace(options) {
     copyTemplateAsset(".markdownlint.json", targetRoot, copiedPaths);
     copyTemplateAsset(".cspell.json", targetRoot, copiedPaths);
     copyTemplateAsset(ROOT_CONFIG_FILENAME, targetRoot, copiedPaths);
-    copyTemplateAsset("docs", targetRoot, copiedPaths);
     copyTemplateAsset("projects", targetRoot, copiedPaths);
     copyTemplateAsset(path.join(".vscode", "tasks.json"), targetRoot, copiedPaths);
     copyTemplateAsset(path.join(".vscode", "extensions.json"), targetRoot, copiedPaths, { optional: true });
@@ -483,8 +483,9 @@ async function initWorkspace(options) {
     logLine("");
     logLine("Next steps:");
     logLine("  npm install");
-    logLine("  npm run list-projects");
-    logLine("  npm run validate -- --project plague-demo");
+    logLine("  stego list-projects");
+    logLine("  stego validate --project fiction-example");
+    logLine("  stego build --project fiction-example");
 }
 async function promptYesNo(question, defaultYes) {
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
@@ -589,9 +590,6 @@ function rewriteTemplateProjectPackageScripts(targetRoot) {
         const scripts = isPlainObject(projectPackage.scripts)
             ? { ...projectPackage.scripts }
             : {};
-        if (typeof projectPackage.name === "string" && projectPackage.name.startsWith("writing-project-")) {
-            projectPackage.name = projectPackage.name.replace(/^writing-project-/, "stego-project-");
-        }
         scripts.validate = "npx --no-install stego validate";
         scripts.build = "npx --no-install stego build";
         scripts["check-stage"] = "npx --no-install stego check-stage";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stego-cli",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "type": "module",
   "description": "Installable CLI for the Stego writing monorepo workflow.",
   "license": "Apache-2.0",
@@ -20,8 +20,8 @@
   },
   "files": [
     "dist/**",
-    "docs/**",
     "projects/**",
+    "!projects/local-only/**",
     "!projects/*/dist/*.md",
     "!projects/*/dist/exports/**",
     ".vscode/tasks.json",

package/projects/{plague-demo → fiction-example}/README.md

@@ -1,4 +1,4 @@
-# Under Saturn's Breath (Demo)
+# Under Saturn's Breath (Fiction Example)
 
 A full-configuration demo with rich metadata, three spine categories, cross-linked spine entries, and external reference links.
 
@@ -12,8 +12,8 @@ A full-configuration demo with rich metadata, three spine categories, cross-link
 Run from `/Users/mattgold/Code/stego`:
 
 ```bash
-npm run validate -- --project plague-demo
-npm run build -- --project plague-demo
-npm run check-stage -- --project plague-demo --stage draft
-npm run export -- --project plague-demo --format md
+npm run validate -- --project fiction-example
+npm run build -- --project fiction-example
+npm run check-stage -- --project fiction-example --stage draft
+npm run export -- --project fiction-example --format md
 ```

package/projects/{plague-demo → fiction-example}/manuscript/300-the-hearing.md

@@ -23,16 +23,4 @@ No one accused him of sorcery. They accused him of carelessness: in a season of
 
 He defended himself precisely. A text could be illicit in circulation yet sound in analysis; truth did not inherit legal status from its scribes. Raoul answered that governance could not afford that distinction under plague conditions.
 
-The compromise was severe but survivable. Matthaeus would keep his position, surrender the quire, and circulate only conclusions framed in authorized language. Etienne copied the agreement and watched his master sign it without hesitation, as though the quire had already given him everything he needed and its confiscation changed nothing.
-
-<!-- stego-comments:start -->
-
-<!-- comment: CMT-0001 -->
-<!-- meta64: eyJzdGF0dXMiOiJvcGVuIiwiY3JlYXRlZF9hdCI6IjIwMjYtMDItMjFUMDQ6MjI6MzguMDE4WiIsInRpbWV6b25lIjoiQW1lcmljYS9OZXdfWW9yayIsInRpbWV6b25lX29mZnNldF9taW51dGVzIjotMzAwLCJwYXJhZ3JhcGhfaW5kZXgiOjAsImV4Y2VycHRfc3RhcnRfbGluZSI6MTgsImV4Y2VycHRfc3RhcnRfY29sIjozMDcsImV4Y2VycHRfZW5kX2xpbmUiOjE4LCJleGNlcnB0X2VuZF9jb2wiOjMxM30 -->
-> _Feb 21, 2026, 4:22 AM — mattgold_
->
-> > “Arabic”
->
-> spicy
-
-<!-- stego-comments:end -->
+The compromise was severe but survivable. Matthaeus would keep his position, surrender the quire, and circulate only conclusions framed in authorized language. Etienne copied the agreement and watched his master sign it without hesitation, as though the quire had already given him everything he needed and its confiscation changed nothing.

package/projects/{plague-demo → fiction-example}/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "writing-project-plague-demo",
+  "name": "stego-project-fiction-example",
   "private": true,
   "scripts": {
     "validate": "node --experimental-strip-types ../../tools/stego-cli.ts validate",

package/projects/{plague-demo → fiction-example}/stego-project.json

@@ -1,5 +1,5 @@
 {
-  "id": "plague-demo",
+  "id": "fiction-example",
   "title": "Under Saturn's Breath (Demo)",
   "subtitle": "Paris, 1348 — a scholar builds a total explanation of the pestilence",
   "author": "Matt Gold",

package/projects/stego-docs/README.md

@@ -0,0 +1,27 @@
+# Stego Docs
+
+This is the canonical Stego documentation project.
+
+It is a real Stego project that demonstrates:
+
+- docs-first usage of the workspace model
+- Spine-driven navigation for commands, concepts, workflows, configuration, and integrations
+- build/export behavior for documentation teams
+
+## Read the docs
+
+Open `manuscript/` in order, or build the compiled manual:
+
+```bash
+stego build --project stego-docs
+```
+
+If you are working in this source repo (not a scaffolded workspace), the equivalent is:
+
+```bash
+npm run build -- --project stego-docs
+```
+
+## Recommended VS Code workflow
+
+Open `projects/stego-docs` directly in VS Code while editing this project so project recommendations and the Spine Browser stay focused on the documentation graph.

package/projects/stego-docs/manuscript/100-what-stego-is.md

@@ -0,0 +1,56 @@
+---
+status: draft
+chapter: 1
+chapter_title: What Stego Is
+concepts:
+  - CON-WORKSPACE
+  - CON-PROJECT
+  - CON-MANUSCRIPT
+  - CON-NOTES
+  - CON-DIST
+workflows:
+  - FLOW-INIT-WORKSPACE
+  - FLOW-DAILY-WRITING
+commands:
+  - CMD-INIT
+  - CMD-LIST-PROJECTS
+integrations:
+  - INT-VSCODE
+  - INT-STEGO-EXTENSION
+---
+
+# What Stego Is
+
+Stego is a Markdown-first writing workflow organized around a workspace that contains one or more writing projects.
+
+It combines local source files, validation, stage gates, build output, and export into a single CLI-driven system that works well with Git and VS Code.
+
+The CLI is the command and automation surface, and the Stego VS Code extension is the official UI for working inside Stego projects.
+
+## Core model
+
+A Stego workspace has a shared root configuration and a `projects/` directory.
+
+Each project is self-contained and typically includes:
+
+- `manuscript/` for canonical source text
+- `notes/` for planning and reference material
+- `spine/` for canonical entities and reference graphs (when enabled)
+- `dist/` for generated output only
+
+## Why this structure works
+
+Stego keeps source authoring close to the tools that evaluate and build it.
+
+That makes it easier to:
+
+- validate metadata and structure early
+- run stage-aware checks before release milestones
+- build deterministic compiled output for review
+- keep generated artifacts separate from hand-edited source material
+
+## Who this is for
+
+Stego works for fiction, nonfiction, and internal documentation teams.
+
+This project (`stego-docs`) demonstrates the documentation use case. The parent workspace includes a `fiction-example` as well.

package/projects/stego-docs/manuscript/200-install-and-initialize.md

@@ -0,0 +1,68 @@
+---
+status: draft
+chapter: 2
+chapter_title: Install and Initialize
+concepts:
+  - CON-WORKSPACE
+  - CON-PROJECT
+commands:
+  - CMD-INIT
+  - CMD-LIST-PROJECTS
+workflows:
+  - FLOW-INIT-WORKSPACE
+integrations:
+  - INT-VSCODE
+  - INT-STEGO-EXTENSION
+---
+
+# Install and Initialize
+
+## Install the CLI
+
+Install the CLI globally so the `stego` command is available in your shell.
+
+```bash
+npm install -g stego-cli
+```
+
+## Create a workspace
+
+Start in an empty directory and initialize a Stego workspace.
+
+```bash
+mkdir my-stego-workspace
+cd my-stego-workspace
+stego init
+```
+
+The command scaffolds a workspace with a root config, root scripts, VS Code tasks, and two example projects: `stego-docs` and `fiction-example`.
+
+If you need to initialize into a non-empty directory, run `stego init --force`.
+
+## Install workspace tools
+
+After scaffolding, install the workspace dependencies used by local scripts and quality checks.
+
+```bash
+npm install
+```
+
+## Open a project in the official UI
+
+After scaffolding, open one project directory in VS Code (start with `projects/stego-docs`).
+
+The Stego VS Code extension is the official UI for Stego projects. It provides project-aware controls, checks, and Spine Browser navigation while you edit.
+
+The scaffolded project folders include extension recommendations to help you install the Stego extension (and the Saurus companion extension) quickly.
+
+## Confirm the workspace is working
+
+Run a few commands from the workspace root.
+
+```bash
+stego list-projects
+stego validate --project stego-docs
+stego build --project stego-docs
+```
+
+The full documentation for the workspace lives inside the `stego-docs` project you just scaffolded.

package/projects/stego-docs/manuscript/300-workspace-layout-and-vscode.md

@@ -0,0 +1,56 @@
+---
+status: draft
+chapter: 3
+chapter_title: Workspace Layout and VS Code
+concepts:
+  - CON-WORKSPACE
+  - CON-PROJECT
+  - CON-MANUSCRIPT
+  - CON-NOTES
+  - CON-SPINE
+  - CON-DIST
+commands:
+  - CMD-INIT
+  - CMD-NEW-PROJECT
+workflows:
+  - FLOW-INIT-WORKSPACE
+  - FLOW-NEW-PROJECT
+integrations:
+  - INT-VSCODE
+  - INT-STEGO-EXTENSION
+  - INT-SAURUS-EXTENSION
+---
+
+# Workspace Layout and VS Code
+
+## Workspace-level files
+
+At the workspace root you will typically see:
+
+- `stego.config.json` for shared configuration and stage policies
+- `projects/` for all writing projects
+- `.vscode/tasks.json` for common root tasks
+- `package.json` for root scripts and tool dependencies
+
+## Project layout
+
+Each project under `projects/<project-id>/` contains its own source and configuration.
+
+Typical folders:
+
+- `manuscript/` for ordered source chapters or sections
+- `notes/` for planning and references
+- `spine/` for canonical entities (when a project enables Spine categories)
+- `dist/` for generated outputs
+
+## Recommended VS Code workflow
+
+When actively working on one project, open that project directory directly in VS Code instead of the whole workspace.
+
+That keeps editor context focused and ensures project recommendations apply at the project level.
+
+## Prose-style editor settings prompt
+
+When you run `stego init` or `stego new-project`, Stego can optionally write project-level markdown editor settings for a prose-friendly font and layout.
+
+Those settings are written to the project folder only, not the workspace root, so different projects can use different editor preferences.