stego-cli 0.1.5 → 0.1.7

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}/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/{plague-demo → 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/{plague-demo → 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/{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.

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

@@ -0,0 +1,70 @@
+---
+status: draft
+chapter: 4
+chapter_title: Everyday Workflow and Commands
+concepts:
+  - CON-PROJECT
+  - CON-MANUSCRIPT
+  - CON-METADATA
+  - CON-DIST
+commands:
+  - CMD-LIST-PROJECTS
+  - CMD-NEW-PROJECT
+  - CMD-VALIDATE
+  - CMD-BUILD
+  - CMD-CHECK-STAGE
+  - CMD-EXPORT
+workflows:
+  - FLOW-DAILY-WRITING
+  - FLOW-NEW-PROJECT
+  - FLOW-BUILD-EXPORT
+integrations:
+  - INT-VSCODE
+---
+
+# Everyday Workflow and Commands
+
+## Daily loop
+
+A practical Stego writing loop looks like this:
+
+1. Open one project folder in VS Code.
+2. Write or revise files in `manuscript/`.
+3. Run `stego validate` for fast structural feedback.
+4. Run `stego build` to inspect the compiled output.
+5. Run `stego check-stage` before moving to the next editorial milestone.
+6. Export formats as needed for review or delivery.
+
+## Root-level command usage
+
+From the workspace root, target a project with `--project`.
+
+```bash
+stego list-projects
+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
+```
+
+## Project-local scripts
+
+Projects also include local npm scripts. These are useful when you want to stay in one project directory.
+
+```bash
+cd projects/fiction-example
+npm run validate
+npm run build
+npm run check-stage -- --stage revise
+npm run export -- --format md
+```
+
+## Create a new project
+
+Use `stego new-project` from the workspace root.
+
+```bash
+stego new-project --project my-book --title "My Book"
+```
+
+This scaffolds manuscript, notes, spine, and dist folders, a project config, local scripts, extension recommendations, and (optionally) project-level prose editor settings.

package/projects/stego-docs/manuscript/500-project-configuration.md

@@ -0,0 +1,58 @@
+---
+status: draft
+chapter: 5
+chapter_title: Project Configuration
+concepts:
+  - CON-WORKSPACE
+  - CON-PROJECT
+  - CON-METADATA
+  - CON-COMPILE-STRUCTURE
+  - CON-SPINE
+  - CON-SPINE-CATEGORY
+commands:
+  - CMD-VALIDATE
+  - CMD-BUILD
+workflows:
+  - FLOW-NEW-PROJECT
+  - FLOW-DAILY-WRITING
+configuration:
+  - CFG-STEGO-CONFIG
+  - CFG-STEGO-PROJECT
+  - CFG-REQUIRED-METADATA
+  - CFG-COMPILE-STRUCTURE
+  - CFG-COMPILE-LEVELS
+  - CFG-SPINE-CATEGORIES
+  - CFG-STAGE-POLICIES
+  - CFG-ALLOWED-STATUSES
+---
+
+# Project Configuration
+
+Stego uses two configuration layers:
+
+- `stego.config.json` at the workspace root for shared directories and stage policies
+- `stego-project.json` inside each project for project-specific rules
+
+## Metadata requirements
+
+Projects can declare advisory metadata keys in `requiredMetadata`.
+
+Stego reports missing keys as warnings so teams can standardize frontmatter without blocking early drafting.
+
+Common keys include `status`, grouping fields such as `chapter`, and project-specific metadata such as point of view or timeline.
+
+## Compile structure
+
+Projects can define `compileStructure.levels` to group manuscript files during build.
+
+This is how Stego inserts structural headings and optional page breaks while still letting authors keep source files small and file-first.
+
+Grouping metadata can be repeated at boundaries only, because Stego inherits missing group values and titles from earlier files in order.
+
+## Spine categories
+
+Projects that use continuity tracking or concept browsing define `spineCategories` in `stego-project.json`.
+
+Each category maps a metadata key to an ID prefix and a canonical notes file in `spine/`.
+
+This project uses Spine categories to model documentation entities such as commands, concepts, workflows, configuration topics, and integrations.

package/projects/stego-docs/manuscript/600-spine-and-browser-workflows.md

@@ -0,0 +1,55 @@
+---
+status: draft
+chapter: 6
+chapter_title: Spine and Browser Workflows
+concepts:
+  - CON-SPINE
+  - CON-SPINE-CATEGORY
+  - CON-METADATA
+  - CON-PROJECT
+commands:
+  - CMD-VALIDATE
+workflows:
+  - FLOW-DAILY-WRITING
+  - FLOW-STAGE-PROMOTION
+configuration:
+  - CFG-SPINE-CATEGORIES
+integrations:
+  - INT-STEGO-EXTENSION
+  - INT-VSCODE
+---
+
+# Spine and Browser Workflows
+
+Stego's Spine model is useful beyond fiction. In this project, Spine acts as a canonical graph for documentation topics.
+
+## How `stego-docs` uses Spine
+
+The documentation project defines categories for:
+
+- commands
+- concepts
+- workflows
+- configuration topics
+- integrations
+
+Each manuscript chapter references relevant entries in frontmatter metadata. That lets the Stego extension's Spine Browser act as an alternate way to explore the docs.
+
+## Why this is useful for documentation teams
+
+Using Spine in docs gives you:
+
+- a canonical glossary with relationships
+- a browseable map of commands and workflows
+- traceability from a chapter to the concepts it depends on
+- a reusable pattern for internal process documentation
+
+## Fiction workflows still use the same model
+
+The `fiction-example` project shows the same mechanism applied to story continuity with entities such as characters, locations, and sources.
+
+That makes `stego-docs` a good bridge project: it documents the feature while demonstrating a non-fiction use case for the same structure.
+
+## Extension workflow
+
+When working in VS Code with the Stego extension, open the project folder and use the Spine Browser to inspect categories, entries, and cross-links while editing chapters.

package/projects/stego-docs/manuscript/700-validation-and-stage-gates.md

@@ -0,0 +1,53 @@
+---
+status: draft
+chapter: 7
+chapter_title: Validation and Stage Gates
+concepts:
+  - CON-METADATA
+  - CON-STAGE-GATE
+  - CON-SPINE
+commands:
+  - CMD-VALIDATE
+  - CMD-CHECK-STAGE
+workflows:
+  - FLOW-STAGE-PROMOTION
+  - FLOW-PROOF-RELEASE
+configuration:
+  - CFG-REQUIRED-METADATA
+  - CFG-STAGE-POLICIES
+  - CFG-ALLOWED-STATUSES
+integrations:
+  - INT-MARKDOWNLINT
+  - INT-CSPELL
+---
+
+# Validation and Stage Gates
+
+Stego separates baseline validation from stage-aware enforcement.
+
+## `validate`
+
+Use `validate` for fast project integrity checks while drafting or restructuring.
+
+It checks configuration shape, manuscript ordering, metadata parsing, and continuity reference structure.
+
+## `check-stage`
+
+Use `check-stage` to ask whether a file or project is ready for a specific editorial stage.
+
+Stages typically progress from draft through revise, line edit, proof, and final. Higher stages enable stricter policies.
+
+## Blocking vs advisory checks
+
+Stego reports a mix of errors and warnings:
+
+- errors block the command result
+- warnings highlight issues worth fixing but do not stop work
+
+This lets teams keep early drafting fast while tightening quality standards later in the workflow.
+
+## Proof and final expectations
+
+Proof and final stages commonly enable stricter checks such as markdown linting, spelling checks, local link validation, and resolved comment requirements.
+
+Those rules are configured in stage policies at the workspace level.

package/projects/stego-docs/manuscript/800-build-export-and-release-outputs.md

@@ -0,0 +1,53 @@
+---
+status: draft
+chapter: 8
+chapter_title: Build, Export, and Release Outputs
+concepts:
+  - CON-MANUSCRIPT
+  - CON-DIST
+  - CON-COMPILE-STRUCTURE
+  - CON-STAGE-GATE
+commands:
+  - CMD-BUILD
+  - CMD-EXPORT
+  - CMD-CHECK-STAGE
+workflows:
+  - FLOW-BUILD-EXPORT
+  - FLOW-PROOF-RELEASE
+configuration:
+  - CFG-COMPILE-STRUCTURE
+integrations:
+  - INT-PANDOC
+  - INT-MARKDOWNLINT
+  - INT-CSPELL
+---
+
+# Build, Export, and Release Outputs
+
+## Build contract
+
+`stego build` compiles one project's manuscript files into a single markdown output in `dist/`.
+
+The build is deterministic because source ordering comes from filename prefixes and grouping behavior comes from project configuration.
+
+Generated files in `dist/` should not be hand-edited.
+
+## Export formats
+
+`stego export` supports markdown output directly and optional richer formats through Pandoc, including docx, pdf, and epub.
+
+If you export pdf through Pandoc, you also need a compatible PDF engine installed on your machine.
+
+## Recommended release sequence
+
+1. Run `stego validate` during drafting and revision.
+2. Run `stego check-stage` for the intended milestone.
+3. Run `stego build` to produce the compiled manuscript.
+4. Run `stego export` for the delivery format.
+5. Archive exported artifacts from `dist/exports` as release outputs.
+
+## Reproducibility rule
+
+Treat `manuscript/`, `notes/`, and `spine/` as source of truth.
+
+Treat `dist/` as reproducible output that can be rebuilt at any time.

package/projects/{docs-demo → stego-docs}/package.json

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