stego-cli 0.1.4 → 0.1.6

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",

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

@@ -0,0 +1,55 @@
+# Commands
+
+## CMD-INIT
+
+- `stego init [--force]`
+- Initialize a Stego workspace in the current directory.
+- Related workflows: FLOW-INIT-WORKSPACE.
+- Related concepts: CON-WORKSPACE, CON-PROJECT.
+- Related integrations: INT-VSCODE.
+
+## CMD-LIST-PROJECTS
+
+- `stego list-projects [--root <path>]`
+- List projects found in the current workspace.
+- Related workflows: FLOW-INIT-WORKSPACE, FLOW-DAILY-WRITING.
+- Related concepts: CON-WORKSPACE, CON-PROJECT.
+
+## CMD-NEW-PROJECT
+
+- `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-VALIDATE
+
+- `stego validate --project <project-id> [--file <project-relative-manuscript-path>] [--root <path>]`
+- Validate project configuration, manuscript structure, metadata, and references.
+- Related workflows: FLOW-DAILY-WRITING, FLOW-STAGE-PROMOTION.
+- Related concepts: CON-METADATA, CON-SPINE.
+- Related configuration: CFG-REQUIRED-METADATA, CFG-SPINE-CATEGORIES.
+
+## CMD-BUILD
+
+- `stego build --project <project-id> [--root <path>]`
+- Compile manuscript files into one generated markdown output.
+- Related workflows: FLOW-BUILD-EXPORT, FLOW-DAILY-WRITING.
+- Related concepts: CON-MANUSCRIPT, CON-DIST, CON-COMPILE-STRUCTURE.
+- Related configuration: CFG-COMPILE-STRUCTURE, CFG-COMPILE-LEVELS.
+
+## CMD-CHECK-STAGE
+
+- `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.
+- Related workflows: FLOW-STAGE-PROMOTION, FLOW-PROOF-RELEASE.
+- Related concepts: CON-STAGE-GATE, CON-METADATA.
+- Related configuration: CFG-STAGE-POLICIES, CFG-ALLOWED-STATUSES.
+
+## CMD-EXPORT
+
+- `stego export --project <project-id> --format <md|docx|pdf|epub> [--output <path>] [--root <path>]`
+- Export compiled output to target formats.
+- Related workflows: FLOW-BUILD-EXPORT, FLOW-PROOF-RELEASE.
+- Related concepts: CON-DIST.
+- Related integrations: INT-PANDOC.

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

@@ -0,0 +1,62 @@
+# Concepts
+
+## CON-WORKSPACE
+
+- 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
+
+- 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
+
+- `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
+
+- `spine/` stores canonical entities used for continuity and navigation.
+- Related configuration: CFG-SPINE-CATEGORIES.
+- Related integrations: INT-STEGO-EXTENSION.
+
+## CON-NOTES
+
+- `notes/` contains supporting material that is not part of compiled manuscript output.
+- Related commands: CMD-NEW-PROJECT.
+- Related workflows: FLOW-DAILY-WRITING.
+
+## CON-DIST
+
+- `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
+
+- 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
+
+- Stage gates apply stricter checks as work moves from drafting to release.
+- Related commands: CMD-CHECK-STAGE.
+- Related workflows: FLOW-STAGE-PROMOTION, FLOW-PROOF-RELEASE.
+- Related configuration: CFG-STAGE-POLICIES.
+
+## CON-COMPILE-STRUCTURE
+
+- 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
+
+- A spine category defines a metadata key, ID prefix, and canonical notes file.
+- Related concepts: CON-SPINE, CON-METADATA.
+- Related configuration: CFG-SPINE-CATEGORIES.

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

@@ -0,0 +1,49 @@
+# Configuration
+
+## CFG-STEGO-CONFIG
+
+- 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
+
+- 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
+
+- Advisory list of frontmatter keys expected in manuscript files.
+- Related concepts: CON-METADATA.
+- Related commands: CMD-VALIDATE.
+
+## CFG-COMPILE-STRUCTURE
+
+- Build grouping configuration that defines structural levels and heading behavior.
+- Related concepts: CON-COMPILE-STRUCTURE.
+- Related commands: CMD-BUILD.
+
+## CFG-COMPILE-LEVELS
+
+- 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
+
+- 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
+
+- Stage policy settings determine which checks are enforced at each stage.
+- Related concepts: CON-STAGE-GATE.
+- Related commands: CMD-CHECK-STAGE.
+
+## CFG-ALLOWED-STATUSES
+
+- Workspace-level list of allowed manuscript statuses.
+- Related concepts: CON-METADATA, CON-STAGE-GATE.
+- Related commands: CMD-VALIDATE, CMD-CHECK-STAGE.

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

@@ -0,0 +1,37 @@
+# Integrations
+
+## INT-VSCODE
+
+- 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
+
+- 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
+
+- The Saurus extension complements prose editing and research workflows in project folders.
+- Related integrations: INT-VSCODE.
+- Related workflows: FLOW-DAILY-WRITING.
+
+## INT-PANDOC
+
+- Pandoc is used for optional export formats such as docx, pdf, and epub.
+- Related commands: CMD-EXPORT.
+- Related workflows: FLOW-BUILD-EXPORT.
+
+## INT-MARKDOWNLINT
+
+- Markdownlint is used in stricter proofreading and release stages.
+- Related concepts: CON-STAGE-GATE.
+- Related workflows: FLOW-PROOF-RELEASE.
+
+## INT-CSPELL
+
+- CSpell supports spelling and terminology checks during later-stage quality passes.
+- Related concepts: CON-STAGE-GATE.
+- Related workflows: FLOW-PROOF-RELEASE.

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

@@ -0,0 +1,42 @@
+# Workflows
+
+## FLOW-INIT-WORKSPACE
+
+- 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
+
+- Open one project, write in manuscript files, validate, build, and commit progress.
+- Related commands: CMD-VALIDATE, CMD-BUILD.
+- Related concepts: CON-MANUSCRIPT, CON-METADATA, CON-DIST.
+- Related integrations: INT-VSCODE.
+
+## FLOW-NEW-PROJECT
+
+- Create a new project, review generated folders, and configure project metadata rules.
+- Related commands: CMD-NEW-PROJECT, CMD-VALIDATE.
+- Related concepts: CON-PROJECT, CON-MANUSCRIPT, CON-SPINE.
+- Related configuration: CFG-STEGO-PROJECT.
+
+## FLOW-STAGE-PROMOTION
+
+- Move files through statuses and verify readiness with stage checks.
+- Related commands: CMD-CHECK-STAGE, CMD-VALIDATE.
+- Related concepts: CON-STAGE-GATE, CON-METADATA.
+- Related configuration: CFG-STAGE-POLICIES, CFG-ALLOWED-STATUSES.
+
+## FLOW-BUILD-EXPORT
+
+- Build a compiled markdown manuscript and export distribution formats.
+- Related commands: CMD-BUILD, CMD-EXPORT.
+- Related concepts: CON-DIST, CON-COMPILE-STRUCTURE.
+- Related integrations: INT-PANDOC.
+
+## FLOW-PROOF-RELEASE
+
+- Run strict checks, build outputs, export artifacts, and archive release files.
+- Related commands: CMD-CHECK-STAGE, CMD-BUILD, CMD-EXPORT.
+- Related concepts: CON-STAGE-GATE, CON-DIST.
+- Related integrations: INT-MARKDOWNLINT, INT-CSPELL.

package/projects/stego-docs/stego-project.json

@@ -0,0 +1,50 @@
+{
+  "id": "stego-docs",
+  "title": "Stego Docs",
+  "subtitle": "Canonical documentation project for stego-cli and the Stego writing workflow",
+  "author": "Matt Gold",
+  "requiredMetadata": [
+    "status",
+    "chapter",
+    "concepts"
+  ],
+  "compileStructure": {
+    "levels": [
+      {
+        "key": "chapter",
+        "label": "Chapter",
+        "titleKey": "chapter_title",
+        "injectHeading": true,
+        "headingTemplate": "{label} {value}: {title}",
+        "pageBreak": "between-groups"
+      }
+    ]
+  },
+  "spineCategories": [
+    {
+      "key": "commands",
+      "prefix": "CMD",
+      "notesFile": "commands.md"
+    },
+    {
+      "key": "concepts",
+      "prefix": "CON",
+      "notesFile": "concepts.md"
+    },
+    {
+      "key": "workflows",
+      "prefix": "FLOW",
+      "notesFile": "workflows.md"
+    },
+    {
+      "key": "configuration",
+      "prefix": "CFG",
+      "notesFile": "configuration.md"
+    },
+    {
+      "key": "integrations",
+      "prefix": "INT",
+      "notesFile": "integrations.md"
+    }
+  ]
+}