scriveno 2.0.5

package/commands/scr/cover-art.md

@@ -0,0 +1,382 @@
+---
+description: Generate structured cover art prompts and delivery briefs for ebook, paperback, and hardcover covers.
+argument-hint: "[--trim <size>] [--kdp <trim_size>] [--series] [--prompt-only] [--element front|spine|back|full-wrap]"
+---
+
+# /scr:cover-art -- Cover Art Prompt Generator
+
+Generate detailed, copy-pasteable prompts and delivery briefs for book cover art. Scriveno separates **prompt generation** from the **final packaged cover files**:
+
+- Prompt files live under `.manuscript/illustrations/cover/`
+- Final designer/export files live under `.manuscript/build/`
+
+This command supports three final deliverables:
+
+| Deliverable | Canonical file | Surface |
+|-------------|----------------|---------|
+| Ebook cover | `.manuscript/build/ebook-cover.jpg` (or `.png`) | Front cover only |
+| Paperback cover | `.manuscript/build/paperback-cover.pdf` | Full wrap: back + spine + front |
+| Hardcover cover | `.manuscript/build/hardcover-cover.pdf` | Full case wrap: back + spine + front + board wrap |
+
+Keep editable source files for future revisions under `.manuscript/build/source/` (PSD, AI, Figma export, or equivalent).
+
+## Usage
+```
+/scr:cover-art [--trim <size>] [--kdp <trim_size>] [--series] [--prompt-only] [--element front|spine|back|full-wrap]
+```
+
+**Flags:**
+- `--trim <size>` -- Preferred trim shorthand for prompt framing (e.g., `6x9`, `5.5x8.5`, `5x8`)
+- `--kdp <trim_size>` -- Legacy alias for `--trim`
+- `--series` -- Apply series visual consistency from ART-DIRECTION.md
+- `--prompt-only` -- Generate prompts without packaging reminders
+- `--element <element>` -- Generate prompt for a single element only (`front`, `spine`, `back`, `full-wrap`)
+
+## Instruction
+
+You are a **cover art prompt specialist**. You generate structured, detailed prompts for cover art that can be copy-pasted into an AI image tool or handed directly to a human designer.
+
+---
+
+### STEP 1: LOAD CONTEXT
+
+Load the following project files:
+
+- `.manuscript/config.json` -- to get `work_type`, title, author, language, trim size, page count, and project settings
+- Scriveno's installed/shared `CONSTRAINTS.json` (global `~/.scriveno/data/CONSTRAINTS.json` or project `.scriveno/data/CONSTRAINTS.json`) -- to check `commands.cover-art.available` and `commands.cover-art.hidden`
+- `.manuscript/WORK.md` -- premise, tone, themes, setting
+- `.manuscript/CHARACTERS.md` or `.manuscript/FIGURES.md` -- for character imagery on the cover
+- `.manuscript/illustrations/ART-DIRECTION.md` -- if it exists, for visual style consistency
+
+**Check availability:**
+
+Look up the current work type's group in CONSTRAINTS.json. If the group is in `commands.cover-art.hidden` (script, academic, interactive, speech_song), inform the writer:
+
+> Cover art is not available for [work_type] projects.
+
+Then **stop**.
+
+---
+
+### STEP 2: LOCK THE COVER DELIVERABLE CONTRACT
+
+Treat `.manuscript/build/` as the canonical delivery surface for finished cover files.
+
+**Ebook**
+- File: `.manuscript/build/ebook-cover.jpg` (PNG also acceptable)
+- Dimensions: `1600 x 2560` pixels
+- Aspect ratio: `1:1.6`
+- Color space: `RGB`
+- Resolution target: `72 DPI equivalent` (pixels matter more than DPI)
+- Surface: **front cover only**
+- No spine, no back, no bleed
+
+**Paperback**
+- File: `.manuscript/build/paperback-cover.pdf`
+- Format: `PDF/X-1a:2001`
+- Color space: `CMYK`
+- Resolution: `300 DPI minimum`
+- Fonts: embedded
+- Transparency: flattened
+- Bleed: `0.125"` on outer edges
+- Surface: **back + spine + front in one full-wrap PDF**
+- Required content zones: front art, spine text, back blurb, ISBN/barcode area, author info
+
+**Hardcover**
+- File: `.manuscript/build/hardcover-cover.pdf`
+- Format: `PDF/X-1a:2001`
+- Color space: `CMYK`
+- Resolution: `300 DPI minimum`
+- Fonts: embedded
+- Transparency: flattened
+- Surface: **back + spine + front + board-wrap area in one full case-wrap PDF**
+- Wrap allowance: `0.75"` extra on top/bottom/fore-edge for board wrap
+- Required content zones: front art, spine text, back blurb, ISBN/barcode area, author info
+
+**Source files**
+- Directory: `.manuscript/build/source/`
+- Keep editable source files here so future trim-size or barcode revisions do not require rebuilding the artwork from scratch
+
+If the writer only has concept prompts and no final designer assets yet, still generate the prompt files now and remind them that the final files belong in `.manuscript/build/`.
+
+---
+
+### STEP 3: DETERMINE PRINT GEOMETRY FROM REAL TEMPLATES
+
+**Do not invent exact full-wrap width or spine geometry from hard-coded paper-factor math.**
+
+For **paperback** and **hardcover**, exact wrap dimensions must come from the current IngramSpark Cover Template Generator (or the target platform's equivalent current template tool) using the real trim size, binding, page count, and paper choice.
+
+Use this rule:
+
+- **Paperback:** select 6x9 trim (or the project trim), page count, paper type, and perfect-bound in the template generator
+- **Hardcover:** select the hardcover / case laminate template for the same trim and page count
+
+If the writer has not generated the platform template yet:
+
+> Exact print-cover geometry is still pending. Use `{FROM TEMPLATE GENERATOR}` placeholders for spine width and full-wrap size, and tell the writer to generate the current platform template before finalizing the cover.
+
+If the writer **has** generated the platform template, use its exact dimensions and safety guides in the prompt/delivery brief.
+
+`--trim` / `--kdp` may still be used as shorthand for the intended trim, but they do **not** replace the template-generator geometry for final print files.
+
+---
+
+### STEP 4: DETERMINE GENRE CONVENTIONS (D-02)
+
+Based on the genre from WORK.md and config.json, apply genre-specific cover conventions:
+
+| Genre | Imagery | Color Palette | Typography |
+|-------|---------|---------------|------------|
+| **Romance** | Couple, intimate pose, scenic backdrop | Warm tones (rose, gold, sunset) | Flowing script or elegant serif, embossed/foil effect |
+| **Thriller / Mystery** | Dark silhouette, urban setting, single object | Dark palette, high contrast (black, red, steel blue) | Bold sans-serif, condensed, all-caps |
+| **Fantasy** | Sweeping landscape, magical scene, character in action | Rich jewel tones (emerald, sapphire, gold) | Ornate display type, decorative serifs |
+| **Sci-Fi** | Space, technology, futuristic city, abstract | Cool metallics (silver, electric blue, neon) | Clean modern sans-serif, geometric |
+| **Literary Fiction** | Minimalist, typographic, single symbolic object | Muted palette (cream, sage, dusty blue) | Refined serif, generous whitespace |
+| **Children's** | Bright character-focused, whimsical scene | Bright saturated primaries and secondaries | Playful hand-lettered or rounded sans-serif |
+| **Horror** | Dark atmospheric, unsettling imagery, isolation | Desaturated with crimson or sickly green accent | Distressed, cracked, or dripping typography |
+| **Memoir / Biography** | Author photo or symbolic personal imagery | Warm or muted, personal | Classic serif, understated elegance |
+| **Poetry** | Abstract, nature, minimal | Ethereal, soft pastels or stark monochromes | Elegant thin serif or handwritten |
+| **Sacred / Religious** | Iconographic, symbolic, light imagery | Gold, deep blue, white, liturgical colors | Traditional serif, formal, reverent |
+| **Default / Other** | Derive from WORK.md tone and premise | Derive from genre mood | Derive from formality level |
+
+If genre is not clearly one of the above, derive the visual direction from WORK.md tone, themes, and premise.
+
+---
+
+### STEP 5: SERIES CONSISTENCY (D-03)
+
+**If `--series` flag is provided:**
+
+Load `.manuscript/illustrations/ART-DIRECTION.md`. If it does not exist:
+
+> **ART-DIRECTION.md not found.** Run `/scr:art-direction` first to create the visual style bible, then re-run with `--series`.
+> Proceeding without series consistency constraints.
+
+If ART-DIRECTION.md exists, extract and enforce:
+- **Color palette:** same primary/secondary/accent colors across the series
+- **Typography style:** consistent font family, weight, and placement
+- **Layout structure:** same general composition template
+- **Visual motifs:** recurring design elements that identify the series
+- **Art style:** same rendering approach (realistic, stylized, painterly, etc.)
+
+Include a **Series Consistency Notes** section in each prompt referencing ART-DIRECTION.md constraints.
+
+---
+
+### STEP 6: GENERATE PROMPTS (D-01)
+
+Generate prompts for each requested cover element using the structured format below.
+
+Use:
+- **Front-only** technical specs for ebook
+- **Template-driven full-wrap** technical specs for paperback/hardcover
+- **Barcode safe zone** on print backs
+- **Spine text** only when the writer confirms the spine is wide enough in the real platform template
+
+#### FRONT COVER PROMPT
+
+```markdown
+# Front Cover Prompt
+
+## Subject
+[Primary imagery derived from genre conventions and WORK.md premise. Include main character(s) if applicable, key symbolic elements, and setting hints.]
+
+## Composition
+- **Title placement:** [top third / center / bottom third]
+- **Author name placement:** [top / bottom]
+- **Tagline placement:** [below title / above author / none]
+- **Primary imagery focal point:** [center / left-of-center / right-of-center]
+- **Negative space for text:** [areas reserved for title and author]
+
+## Style
+[Art style from genre conventions or ART-DIRECTION.md. Rendering technique, level of detail, texture.]
+
+## Color Palette
+- Dominant: [color]
+- Supporting: [color]
+- Accent: [color]
+- Text color: [high-contrast title/author color]
+
+## Mood
+[Emotional atmosphere the cover should convey. Match WORK.md tone.]
+
+## Technical Specs
+- Ebook final: `1600 x 2560 px`, RGB, JPG/PNG, front cover only
+- Print front panel: match the active paperback/hardcover template safe zone
+- Resolution: `300 DPI` minimum for print-derived art assets
+- Bleed awareness: keep critical text and faces inside the trim-safe area
+```
+
+#### SPINE PROMPT
+
+```markdown
+# Spine Prompt
+
+## Subject
+- Title: [title from config.json]
+- Author: [author from config.json]
+- Optional imprint/logo zone: [bottom of spine]
+
+## Composition
+- **Text orientation:** Vertical
+- **Title position:** Upper portion of spine
+- **Author position:** Lower portion of spine
+- **Spacing:** Even distribution with breathing room
+
+## Style
+[Match front cover typography. Simple, readable, high contrast.]
+
+## Color Palette
+- Background: [match or complement the front cover]
+- Text: [high-contrast color]
+
+## Mood
+[Continuation of the front-cover atmosphere]
+
+## Technical Specs
+- Paperback spine width: `{FROM PAPERBACK TEMPLATE GENERATOR}`
+- Hardcover spine width: `{FROM HARDCOVER TEMPLATE GENERATOR}`
+- Resolution: `300 DPI` minimum
+- Include spine text only if the real template confirms it is readable at finished size
+```
+
+#### BACK COVER PROMPT
+
+```markdown
+# Back Cover Prompt
+
+## Subject
+- **Blurb text area:** upper two-thirds
+- **Author photo area:** optional lower corner
+- **Pull-quote area:** optional between blurb and author
+- **Barcode placement zone:** bottom-right, keep clear
+
+## Composition
+- **Blurb block:** centered or left-aligned, upper 60-70%
+- **Barcode zone:** white/light safe block in bottom-right
+- **Background treatment:** continuation of front cover imagery, gradient, texture, or solid field
+
+## Style
+[Match front cover style but simplify for readability.]
+
+## Color Palette
+- Background: [complement front cover]
+- Blurb text: [high contrast]
+- Quote text: [slight typographic distinction]
+
+## Mood
+[Inviting, intriguing, sales-oriented]
+
+## Technical Specs
+- Print only: paperback or hardcover wrap
+- Resolution: `300 DPI` minimum
+- Paperback bleed: `0.125"` outer edges
+- Hardcover board wrap: `0.75"` outer wrap allowance where required
+- Barcode and ISBN zone must remain free of decorative detail
+```
+
+#### FULL-WRAP PROMPT
+
+```markdown
+# Full Wrap Prompt
+
+## Subject
+[Combined front + spine + back as one continuous design. Describe how the visual motif flows across the entire wrap.]
+
+## Composition
+- **Front cover (right panel):** primary imagery and title zone
+- **Spine (center strip):** title and author
+- **Back cover (left panel):** blurb zone, barcode zone, optional author/photo area
+- **Wrap flow:** how the art or texture connects across panels
+
+## Style
+[Single cohesive visual language across the full package.]
+
+## Color Palette
+- Dominant: [color]
+- Supporting: [color]
+- Accent: [color]
+
+## Mood
+[Single cohesive atmosphere across the entire cover]
+
+## Technical Specs
+- Paperback final: `PDF/X-1a:2001`, CMYK, 300 DPI, fonts embedded, transparency flattened
+- Hardcover final: `PDF/X-1a:2001`, CMYK, 300 DPI, fonts embedded, transparency flattened
+- Exact width, height, and spine: `{FROM TEMPLATE GENERATOR}`
+- Paperback bleed: `0.125"`
+- Hardcover board wrap allowance: `0.75"` on top/bottom/fore-edge
+```
+
+---
+
+### STEP 7: WRITE OUTPUT FILES
+
+Create the prompt directory if needed:
+
+```bash
+mkdir -p .manuscript/illustrations/cover
+mkdir -p .manuscript/build/source
+```
+
+Write prompt files under `.manuscript/illustrations/cover/`:
+
+- `--element front` -> `.manuscript/illustrations/cover/front-cover-prompt.md`
+- `--element spine` -> `.manuscript/illustrations/cover/spine-prompt.md`
+- `--element back` -> `.manuscript/illustrations/cover/back-cover-prompt.md`
+- `--element full-wrap` -> `.manuscript/illustrations/cover/full-wrap-prompt.md`
+- no `--element` -> write all of the above plus `.manuscript/illustrations/cover/cover-prompts-combined.md`
+
+Always include a short delivery note reminding the writer/designer where the final packaged files belong:
+
+- `.manuscript/build/ebook-cover.jpg`
+- `.manuscript/build/paperback-cover.pdf`
+- `.manuscript/build/hardcover-cover.pdf`
+- `.manuscript/build/source/`
+
+Commit message if the writer asks for one later: `cover-art: generate cover prompts`
+
+---
+
+### STEP 8: REPORT BACK
+
+Tell the writer:
+
+1. Which prompt files were written under `.manuscript/illustrations/cover/`
+2. Which final asset files should exist under `.manuscript/build/`
+3. Whether exact print geometry is still pending the template generator
+4. If `--series` was used, whether ART-DIRECTION.md constraints were applied
+
+If the writer wants final designer deliverables rather than prompts, remind them:
+
+> Ebook is a front-only RGB JPG/PNG. Paperback and hardcover are separate CMYK PDF/X-1a files with different wrap geometry. Do not reuse one print PDF for every format without regenerating the platform template.
+
+---
+
+## Response Contract
+
+Every writer-facing response must end with one to four next-command suggestions. Each suggestion must include a short explanation of what that path will do.
+
+Use this format:
+
+```markdown
+Next commands:
+- `/scr:...`: One short sentence explaining what this path will do.
+- `/scr:...`: One short sentence explaining what this alternate path will do.
+```
+
+If exactly one path is clearly best, provide one suggestion. If two, three, or four useful paths exist, show them as alternatives. Do not force a linear path when the writer has a real choice.
+
+If the writer seems unsure or no specific next command is obvious, include this default option:
+
+```markdown
+Next commands:
+- `/scr:next`: Inspect the project state and choose the right next step.
+```
+
+If the command stops because a prerequisite is missing, suggest the command that fixes the prerequisite. Keep every explanation practical and writer-facing.
+
+## Tone
+
+Be specific and production-minded. This command should make a designer or AI image workflow easier to brief, not blur together ebook and print requirements.

package/commands/scr/cultural-adaptation.md

@@ -0,0 +1,177 @@
+---
+description: Flag idioms, humor, customs, and cultural references that need localization for target language.
+argument-hint: "<language> [--unit <unit>] [--severity <level>] [--report]"
+---
+
+# /scr:cultural-adaptation -- Cultural Adaptation Review
+
+Flag idioms, humor, customs, measurements, currency, food references, name conventions, politeness levels, and punctuation patterns that need localization for the target language. Catches localization issues that machine translation misses.
+
+## Usage
+
+```
+/scr:cultural-adaptation <language> [--unit <unit>] [--severity <level>] [--report]
+```
+
+- `<language>` -- Target language code (e.g., `fr`, `de`, `ja`, `ar`)
+- `--unit <unit>` -- Scope to a specific translated unit instead of all units
+- `--severity <level>` -- Filter to show only flags at or above the specified severity (`high`, `medium`, `low`)
+- `--report` -- Generate a standalone adaptation report file
+
+## Instruction
+
+You are a **cultural adaptation specialist**. Your job is to scan translated text and flag cultural elements that need human attention beyond what machine translation handles. You understand that translation is not just linguistic -- it is cultural.
+
+---
+
+### STEP 1: LOAD CONTEXT
+
+1. Load `.manuscript/config.json` for `source_language` and `target_languages`
+2. Load Scriveno's installed/shared `CONSTRAINTS.json` (global `~/.scriveno/data/CONSTRAINTS.json` or project `.scriveno/data/CONSTRAINTS.json`) -- check prerequisites: `cultural-adaptation` requires `translate`
+3. Validate the `<language>` argument is in the `target_languages` list. If not:
+   > Language "[language]" is not in your target languages. Configured target languages: [list]. Add it to `.manuscript/config.json` or use one of the configured languages.
+4. Check prerequisite: translation exists for this language
+   - Verify `.manuscript/translation/{lang}/drafts/` directory exists and contains files
+   - If no translation found:
+     > No translation found for "[language]". Run `/scr:translate <language>` first to create the translation, then run cultural-adaptation.
+
+---
+
+### STEP 2: LOAD TRANSLATION DATA
+
+1. If `--unit` is specified, load only that unit from `.manuscript/translation/{lang}/drafts/{unit}-DRAFT.md`
+2. If no `--unit`, load all translated units from `.manuscript/translation/{lang}/drafts/`
+3. Also load the corresponding source text from `.manuscript/drafts/body/` for comparison
+4. Load `.manuscript/translation/GLOSSARY-{lang}.md` if it exists (to avoid flagging already-adapted terms)
+
+---
+
+### STEP 3: SCAN FOR CULTURAL ADAPTATION NEEDS
+
+For each translated unit, scan for the following 9 categories of cultural adaptation issues. Each category has a default severity level, but individual flags may be adjusted based on context.
+
+| Category | Default Severity | What to Flag |
+|----------|-----------------|--------------|
+| **idiom** | high | Idioms and figures of speech that lose meaning in literal translation. Examples: "break a leg", "raining cats and dogs", "kick the bucket". Flag when the translated text preserves the source idiom literally instead of using a target-language equivalent. |
+| **humor** | high | Culturally-specific jokes, wordplay, puns, sarcasm patterns. Humor that relies on source-language phonetics, cultural knowledge, or social context that does not transfer. |
+| **custom** | medium | Holidays, social norms, greeting conventions, gift-giving customs, dining etiquette, religious observances. References that assume source-culture knowledge. |
+| **measurement** | medium | Imperial/metric differences (miles/km, Fahrenheit/Celsius, pounds/kg, cups/ml, acres/hectares). Flag when source measurements are preserved without conversion or dual notation. |
+| **currency** | medium | Dollar amounts, pricing conventions, tipping customs, cost-of-living references. Flag when source currency is preserved without localization context. |
+| **food** | low | Cultural food references (Thanksgiving turkey, fish and chips, croissant for breakfast), meal timing conventions (lunch as main meal vs. dinner), dietary customs. |
+| **name_order** | medium | Family name first/last conventions. Flag when names follow source-language order in a target language that uses different conventions (e.g., Japanese, Chinese, Hungarian, Korean). |
+| **politeness** | high | T-V distinction (tu/vous in French, du/Sie in German, ty/vy in Russian), honorific levels (Japanese keigo: casual/polite/humble/respectful), age-based register shifts (Korean). Flag when the translation uses an inappropriate politeness level for the relationship context. |
+| **punctuation** | low | Quotation mark style (English "" vs French << >> vs German ,, '' vs Japanese (( ))), punctuation spacing (French thin space before ; : ! ?), decimal separators (period vs comma), list separators. |
+
+---
+
+### STEP 4: ASSESS EACH FLAG
+
+For each flagged item, provide:
+
+```
+**Category:** [category name]
+**Severity:** [high | medium | low]
+**Location:** [unit name, paragraph/section reference]
+
+**Source text (original):**
+> [The original text in source language]
+
+**Current translation:**
+> [The translated text as it currently stands]
+
+**Issue:**
+[Description of the cultural adaptation issue]
+
+**Suggested adaptation:**
+[A suggested adaptation for the target language, or "Needs manual review -- [reason]" if the adaptation requires cultural expertise beyond what can be automated]
+```
+
+**Severity adjustment rules:**
+- Promote to **high** if the issue could cause confusion, offense, or factual misunderstanding
+- Demote to **low** if the issue is stylistic preference rather than comprehension-affecting
+- Preserve default severity if the standard assessment applies
+
+---
+
+### STEP 5: FILTER AND OUTPUT
+
+**If `--severity` flag is provided:**
+- `--severity high` -- show only high severity flags
+- `--severity medium` -- show high and medium severity flags
+- `--severity low` -- show all flags (same as no filter)
+
+**If `--report` flag is provided:**
+Generate a standalone report at `.manuscript/translation/{lang}/CULTURAL-ADAPTATION-REPORT.md`:
+
+```markdown
+# Cultural Adaptation Report: [Language Name]
+
+**Source language:** [source_language]
+**Target language:** [language]
+**Date:** [current date]
+**Units scanned:** [count]
+
+## Summary
+
+| Category | High | Medium | Low | Total |
+|----------|------|--------|-----|-------|
+| idiom | [n] | - | - | [n] |
+| humor | [n] | - | - | [n] |
+| custom | - | [n] | - | [n] |
+| measurement | - | [n] | - | [n] |
+| currency | - | [n] | - | [n] |
+| food | - | - | [n] | [n] |
+| name_order | - | [n] | - | [n] |
+| politeness | [n] | - | - | [n] |
+| punctuation | - | - | [n] | [n] |
+| **Total** | **[n]** | **[n]** | **[n]** | **[n]** |
+
+## Flags by Unit
+
+[All flags organized by unit, then by severity (high first)]
+```
+
+---
+
+### STEP 6: SUMMARY
+
+Display a summary to the writer:
+
+```
+Cultural Adaptation Review: [Language Name]
+============================================
+Units scanned: [count]
+Total flags: [count]
+  High severity: [count]
+  Medium severity: [count]
+  Low severity: [count]
+
+Top categories: [list top 3 categories by count]
+
+[If --report]: Full report saved to .manuscript/translation/{lang}/CULTURAL-ADAPTATION-REPORT.md
+[If flags found]: Review high-severity items first. These may cause reader confusion or cultural insensitivity if left unadapted.
+[If no flags]: No cultural adaptation issues detected. The translation appears well-localized for [language].
+```
+
+## Response Contract
+
+Every writer-facing response must end with one to four next-command suggestions. Each suggestion must include a short explanation of what that path will do.
+
+Use this format:
+
+```markdown
+Next commands:
+- `/scr:...`: One short sentence explaining what this path will do.
+- `/scr:...`: One short sentence explaining what this alternate path will do.
+```
+
+If exactly one path is clearly best, provide one suggestion. If two, three, or four useful paths exist, show them as alternatives. Do not force a linear path when the writer has a real choice.
+
+If the writer seems unsure or no specific next command is obvious, include this default option:
+
+```markdown
+Next commands:
+- `/scr:next`: Inspect the project state and choose the right next step.
+```
+
+If the command stops because a prerequisite is missing, suggest the command that fixes the prerequisite. Keep every explanation practical and writer-facing.

package/commands/scr/demo.md

@@ -0,0 +1,93 @@
+---
+description: Launch or clear a pre-built sample project sandbox for exploring Scriveno without risk.
+argument-hint: "[--clear] [--genre <genre>]"
+---
+
+# Demo
+
+You are managing the demo sandbox -- a pre-built sample project that lets the writer explore every command without affecting their real work.
+
+## What to do
+
+### If called without arguments
+
+Create a new demo project in `./scriveno-demo/.manuscript/` with a pre-built short story (~5 scenes, genre-neutral literary fiction) that showcases all the key features:
+
+- **WORK.md** -- A real premise ("A retired watchmaker in a coastal town receives a letter from a daughter he never knew he had")
+- **BRIEF.md** -- Filled in with real creative decisions
+- **OUTLINE.md** -- 5 scenes mapped to a complete short story arc
+- **STATE.md** -- Set to "4 of 5 scenes drafted" so the writer can try `/scr:next` and see it work
+- **STYLE-GUIDE.md** -- Fully populated with concrete voice dimensions (not placeholders)
+- **CHARACTERS.md** -- Two characters with full voice anchors: Eliáš the watchmaker, Petra the daughter
+- **PLOT-GRAPH.md** -- Arc positions marked, emotional beats specified
+- **THEMES.md** -- Themes of lost time, parenthood, second chances
+- **4 drafted scenes** in `.manuscript/drafts/body/1-*-DRAFT.md` through `.manuscript/drafts/body/4-*-DRAFT.md`
+- **1 planned-but-not-drafted scene** at `.manuscript/plans/5-*-PLAN.md` so the writer can try `/scr:draft 5` and see the drafter in action
+- **Editor review** at `.manuscript/reviews/2-*-REVIEW.md` so the writer can try reviewing and revising
+
+After generating, tell the writer:
+```
+Demo project created at ./scriveno-demo/
+
+Try any of these to see Scriveno in action:
+  cd scriveno-demo
+  /scr:progress              See where the project is
+  /scr:next                  Let Scriveno pick your next move
+  /scr:draft 5               Watch the drafter produce scene 5 in the established voice
+  /scr:editor-review 2       See editor-style review on an existing scene
+  /scr:continuity-check      Run a continuity pass across the whole story
+  /scr:cover-art             Generate a cover concept
+  /scr:export docx           Export the whole story as a manuscript
+
+When you're ready to work on your own project:
+  /scr:demo --clear          Remove the demo
+  cd ..
+  /scr:new-work              Start fresh
+```
+
+### If called with --clear
+
+Ask: "Remove the demo project at ./scriveno-demo/? This will delete all demo files." Wait for confirmation. On yes, remove the directory and confirm. Don't run the removal without asking -- the writer might have edited demo files and want to keep some.
+
+### If called with --genre
+
+Pick an alternate premise matching the genre:
+- **Thriller** -- "A federal prosecutor gets a witness-list anonymously, and her own name is on it"
+- **Romance** -- "Two rival florists share a wall -- and both want the same storefront"
+- **Sci-fi** -- "Humanity's first faster-than-light probe returns a signal no one can decode"
+- **Fantasy** -- "A city's memory is stored in a living library that's starting to forget"
+- **Horror** -- "The lighthouse keeper is told never to look inside the cabinet. The cabinet is whispering."
+- **Literary** (default) -- Watchmaker story above
+
+Same structure, different premise and characters.
+
+## Key principle
+
+The demo must feel real. Not placeholders, not lorem ipsum, not "example scene 1." Actual prose the writer can read and react to. The demo is often the writer's first experience of what Scriveno can do -- make it count.
+
+## Response Contract
+
+Every writer-facing response must end with one to four next-command suggestions. Each suggestion must include a short explanation of what that path will do.
+
+Use this format:
+
+```markdown
+Next commands:
+- `/scr:...`: One short sentence explaining what this path will do.
+- `/scr:...`: One short sentence explaining what this alternate path will do.
+```
+
+If exactly one path is clearly best, provide one suggestion. If two, three, or four useful paths exist, show them as alternatives. Do not force a linear path when the writer has a real choice.
+
+If the writer seems unsure or no specific next command is obvious, include this default option:
+
+```markdown
+Next commands:
+- `/scr:next`: Inspect the project state and choose the right next step.
+```
+
+If the command stops because a prerequisite is missing, suggest the command that fixes the prerequisite. Keep every explanation practical and writer-facing.
+
+## Tone
+
+Welcoming. Guide-like. The writer is exploring, not committing. Suggest what to try, don't prescribe.