stego-cli 0.1.2 → 0.1.3

package/README.md

@@ -1,9 +1,12 @@
 # Stego
 
-This workspace is a Markdown-first creative writing pipeline for short stories through novels.
+Stego is a Markdown-first creative writing workflow packaged as an installable CLI: `stego-cli`.
+
+This repository is the source for the CLI and the example/template content that `stego init` scaffolds into a new workspace.
 
 ## What this includes
 
+- 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`).
@@ -11,23 +14,77 @@ This workspace is a Markdown-first creative writing pipeline for short stories t
 - Deterministic build into one manuscript Markdown file.
 - Stage-based quality gates (`draft` -> `final`).
 - Export abstraction (`md` always, `docx`/`pdf` via optional `pandoc`).
-- TypeScript-based tooling executed directly by Node (`--experimental-strip-types`).
+- Example/demo projects (`docs-demo`, `plague-demo`) included in `stego init`.
 
-## Quick start
+## Getting started (from npm)
 
 ```bash
-cd ~/Code/stego
+npm install -g stego-cli
+
+mkdir my-stego-workspace
+cd my-stego-workspace
+stego init
+
+npm install
 npm run list-projects
-npm run new-project -- --project my-new-project --title "My New Project"
 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
 ```
 
-`npm run new-project` scaffolds `manuscript/`, `spine/`, `notes/`, and `dist/`, and seeds `stego-project.json` with a default `characters` category plus `spine/characters.md`.
-It also creates `projects/<project-id>/.vscode/settings.json` so markdown font settings apply when opening the project folder directly.
-It also creates a project-local `package.json` so you can run `npm run validate`, `npm run build`, etc. from inside that project directory without `--project`.
+`stego init` scaffolds a new workspace in the current directory (it must be empty unless you pass `--force`).
+
+Create another project in the workspace:
+
+```bash
+stego new-project --project my-new-project --title "My New Project"
+```
+
+`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.
+
+## Running commands for a specific project
+
+From the workspace root, target a project with `--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
+```
+
+Each project also has local scripts, so you can work from inside the project directory:
+
+```bash
+cd projects/plague-demo
+npm run validate
+npm run build
+npm run check-stage -- --stage proof
+npm run export -- --format md
+```
+
+## VS Code workflow
+
+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.
+
+This keeps editor context focused and applies the project's recommended extensions via `projects/<project-id>/.vscode/extensions.json`.
+
+## Developing `stego-cli` (this repo)
+
+If you are working on the CLI itself (this repository), use the local development scripts:
+
+```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 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)
 
@@ -63,14 +120,22 @@ npm run export -- --project plague-demo --format docx
 npm run export -- --project plague-demo --format pdf
 ```
 
-## Project layout
+## 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
-- `tools/` build, checks, export CLI
+- `.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
 

package/dist/stego-cli.js

@@ -25,6 +25,56 @@ projects/*/dist/*
 projects/*/.vscode/settings.json
 .vscode/settings.json
 `;
+const SCAFFOLD_README_CONTENT = `# Stego Workspace
+
+This directory is a Stego writing workspace (a monorepo for one or more writing projects).
+
+## What was scaffolded
+
+- \`stego.config.json\` workspace configuration
+- \`projects/\` demo projects (\`docs-demo\` and \`plague-demo\`)
+- \`docs/\` workflow and conventions docs
+- root \`package.json\` scripts for Stego commands
+- root \`.vscode/tasks.json\` tasks for common workflows
+
+## First run
+
+\`\`\`bash
+npm install
+npm run 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
+\`\`\`
+
+## Work inside one project
+
+Each project also has local scripts, so you can run commands from inside a project directory:
+
+\`\`\`bash
+cd projects/plague-demo
+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\`).
+
+This keeps your editor context focused and applies the project's recommended extensions (including Stego + Saurus) for that project.
+
+## Create a new project
+
+\`\`\`bash
+stego new-project --project my-book --title "My Book"
+\`\`\`
+`;
 const PROJECT_EXTENSION_RECOMMENDATIONS = [
     "matt-gold.stego-extension",
     "matt-gold.saurus-extension"
@@ -398,6 +448,7 @@ function initWorkspace(options) {
     }
     const copiedPaths = [];
     writeScaffoldGitignore(targetRoot, copiedPaths);
+    writeScaffoldReadme(targetRoot, copiedPaths);
     copyTemplateAsset(".markdownlint.json", targetRoot, copiedPaths);
     copyTemplateAsset(".cspell.json", targetRoot, copiedPaths);
     copyTemplateAsset(ROOT_CONFIG_FILENAME, targetRoot, copiedPaths);
@@ -447,6 +498,11 @@ function writeScaffoldGitignore(targetRoot, copiedPaths) {
     fs.writeFileSync(destinationPath, SCAFFOLD_GITIGNORE_CONTENT, "utf8");
     copiedPaths.push(".gitignore");
 }
+function writeScaffoldReadme(targetRoot, copiedPaths) {
+    const destinationPath = path.join(targetRoot, "README.md");
+    fs.writeFileSync(destinationPath, SCAFFOLD_README_CONTENT, "utf8");
+    copiedPaths.push("README.md");
+}
 function shouldCopyTemplatePath(currentSourcePath) {
     const relativePath = path.relative(packageRoot, currentSourcePath);
     if (!relativePath || relativePath.startsWith("..")) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stego-cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "description": "Installable CLI for the Stego writing monorepo workflow.",
   "bin": {