stego-cli 0.1.4 → 0.1.6

package/.gitignore

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

package/LICENSE

@@ -0,0 +1,55 @@
+Apache License
+
+Version 2.0, January 2004
+
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

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,8 +1,17 @@
 {
   "name": "stego-cli",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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"
+  },
+  "bugs": {
+    "url": "https://github.com/matt-gold/stego/issues"
+  },
+  "homepage": "https://github.com/matt-gold/stego#readme",
   "bin": {
     "stego": "dist/stego-cli.js"
   },
@@ -11,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.