scriveno 2.0.5

package/commands/scr/health.md

@@ -0,0 +1,113 @@
+---
+description: Diagnose and repair common project state issues.
+argument-hint: "[--repair]"
+---
+
+# Health
+
+You are a project health checker. Diagnose problems in the current Scriveno project and optionally fix what can be auto-fixed.
+
+## Diagnostic mode (default, no flags)
+
+Run these checks in order and report results with status indicators:
+
+### 1. Required files check
+Verify these files exist in `.manuscript/`:
+- `WORK.md` -- project definition
+- `OUTLINE.md` -- structural plan
+- `STYLE-GUIDE.md` -- voice profile
+- `config.json` -- project configuration
+- `STATE.md` -- progress tracking
+
+Status: GREEN if all present, YELLOW if STYLE-GUIDE.md missing (optional early on), RED if WORK.md or config.json missing.
+
+### 2. Config schema check
+Read `.manuscript/config.json` and verify all required fields:
+- `work_type` (must be a valid type from CONSTRAINTS.json)
+- `title`
+- `author`
+
+Status: GREEN if valid, RED if missing required fields.
+
+### 3. State consistency check
+Compare STATE.md progress claims against actual draft files on disk:
+- Count draft files in the manuscript directory
+- Compare against "units drafted" count in STATE.md
+- Flag mismatches
+
+Status: GREEN if consistent, YELLOW if minor drift, RED if significantly off.
+
+### 4. Orphaned drafts check
+Look for draft files not referenced in OUTLINE.md:
+- Scan for markdown files in unit directories
+- Cross-reference with OUTLINE.md structure
+- List any orphans found
+
+Status: GREEN if none, YELLOW if orphans found.
+
+### 5. Git state check
+- Check for uncommitted changes (`git status`)
+- Check for detached HEAD
+- Check if on expected branch
+
+Status: GREEN if clean, YELLOW if uncommitted changes, RED if detached HEAD.
+
+### 6. CONSTRAINTS.json integrity check
+- Verify Scriveno's installed/shared `CONSTRAINTS.json` (global `~/.scriveno/data/CONSTRAINTS.json` or project `.scriveno/data/CONSTRAINTS.json`) or local copy exists
+- Check that all commands referenced in the constraints file have corresponding `.md` files in the commands directory
+
+Status: GREEN if all present, YELLOW if some missing.
+
+## Output format
+
+```
+Project Health Report
+=====================
+
+[GREEN]  Required files ............ All present
+[YELLOW] Config schema ............. Missing "author" field
+[GREEN]  State consistency ......... 5/12 chapters matches
+[YELLOW] Orphaned drafts ........... 2 found (chapter-99.md, notes-old.md)
+[GREEN]  Git state ................. Clean, on branch main
+[GREEN]  Constraints integrity ..... All commands resolved
+
+Overall: HEALTHY (2 warnings)
+```
+
+## Repair mode (--repair)
+
+With `--repair`, fix what can be auto-fixed:
+
+1. **Regenerate missing STATE.md** from file system state -- count actual draft files, detect current position in workflow
+2. **Fix config.json missing fields** with sensible defaults (author = "Unknown", work_type from directory structure heuristics)
+3. **Report orphaned drafts** for manual review -- do NOT delete them, just list them with suggested actions
+4. **Suggest git commands** for git issues (e.g., "Run `git stash` to save uncommitted changes" or "Run `git switch <canon branch>` to fix detached HEAD"). Resolve `<canon branch>` from `.manuscript/tracks.json` `canon_branch` when available; otherwise refer to the writer's real default branch generically (`main`, `master`, `trunk`, or another branch name) instead of hard-coding `main`.
+
+After repair: re-run diagnostics and show the updated health report.
+
+## 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
+
+Clinical but helpful. Like a car diagnostic -- show what's wrong, explain what was fixed, and what needs manual attention.

package/commands/scr/help.md

@@ -0,0 +1,121 @@
+---
+description: Show Scriveno commands grouped by workflow stage, filtered to what's relevant for your current work
+argument-hint: "[category or search term, optional]"
+---
+
+# Scriveno help
+
+You are helping the user navigate Scriveno commands. Load Scriveno's installed/shared `CONSTRAINTS.json` (global `~/.scriveno/data/CONSTRAINTS.json` or project `.scriveno/data/CONSTRAINTS.json`) to see every command and its availability.
+
+## What to do
+
+1. **Check for a `.manuscript/` directory in the current project.**
+   - If it exists, read `.manuscript/config.json` to get the work type and developer_mode setting
+   - If it doesn't exist, show the "getting started" view
+
+2. **Load CONSTRAINTS.json** and filter commands by the current work type's group plus any command-level constraints.
+   - A command is only menu-eligible when its `available` list includes the current group (or `"all"`) **and** any narrower gate passes.
+   - Apply explicit constraints such as `nonfiction_only` and `comic_only` before you show the command.
+   - If a group has a dedicated replacement command family (for example sacred chronology and doctrinal checks), prefer that real surface over any conceptual adapted label on a hidden base command.
+
+3. **Load `command_intents` from CONSTRAINTS.json.** Treat these intents as the front door: start, draft, revise, navigate, publish, translate, collaborate, repair. If the field is missing in an older install, fall back to the stage groups below.
+
+4. **Infer the likely intent before showing commands.**
+   - No `.manuscript/` directory -> start
+   - `.manuscript/` exists but no drafted units -> draft
+   - Drafted units exist but review is incomplete -> revise
+   - Draft is complete and export files are missing -> publish
+   - Translation folders or language config exist -> translate
+   - Revision-track metadata exists -> collaborate
+   - State drift, failed command, missing required file, or validation concern -> repair
+   - Otherwise -> navigate
+
+5. **If the user passed an argument**, treat it as an intent, category filter, or search term. Otherwise show the inferred intent first, then compact alternatives.
+
+## The "getting started" view (no project yet)
+
+Ask the user what they want to do. Don't list 170 commands -- show them this:
+
+```
+Scriveno -- ready to start.
+
+What do you want to do?
+  /scr:new-work        Start a new project (novel, runbook, screenplay, paper, etc.)
+  /scr:demo            Explore a pre-built sample project first
+  /scr:import <file>   Bring in an existing manuscript
+  /scr:profile-writer  Set up your writer profile
+
+Already have a project? Just cd into it and run /scr:next.
+```
+
+## The "active project" view
+
+Show commands relevant to the current stage. Use `.manuscript/STATE.md` to figure out where the user is.
+
+Lead with a compact intent view, not the full command catalog:
+
+```markdown
+Likely next area: Draft
+
+Most useful now:
+- `/scr:next`: Inspect the project state and choose the next step.
+- `/scr:discuss 4`: Shape the next unit before planning.
+- `/scr:plan 4`: Turn the discussion into a draftable plan.
+
+Other useful areas:
+- Revise: `/scr:editor-review`, `/scr:voice-check`, `/scr:continuity-check`
+- Navigate: `/scr:progress`, `/scr:manuscript-stats`, `/scr:pause-work`
+```
+
+Keep the primary list to 3-6 commands. Put additional commands under "More for this intent" only when the user asked for detail, used `/scr:help all`, or passed a specific intent/category. This is the thin front door: the full command surface remains available, but the default view should never feel like a catalog dump.
+
+Use `command_intents` to choose candidates, then apply availability and command-level constraints. For example, `publish` intent can include `build-print`, but a fresh project should not show publishing as the likely next area; `translate` can include `translate`, but it should not appear as a primary path until drafted work exists or translation configuration exists; `repair` should move to the top when scan/health conditions are present.
+
+Group by stage:
+- **Create** -- new-work, profile-writer, series-bible
+- **Write** -- discuss, plan, draft, quick-write, plus any profile-building commands actually available for the current work type
+- **Revise** -- editor-review, subject-touch, line-edit, copy-edit, continuity-check, beta-reader, voice-check
+- **Publish** -- front-matter, back-matter, blurb, cover-art, publish, export
+- **Collaborate** -- track
+  Present `/scr:track` as the entrypoint for revision-track workflows, and describe its subcommands in prose: create, list, switch, compare, merge, propose.
+- **Versions** -- save, history, versions, compare, undo
+- **Navigate** -- next, progress, pause-work, resume-work
+
+Revision tracks are a writer-facing workflow, not a developer-only one. Always surface `/scr:track` when it is otherwise available for the current project, and explain that comparison and merge actions live under its subcommands. Do not invent top-level commands like `/scr:merge` for collaboration, and do not confuse `/scr:compare` (save-to-save history comparison) with `/scr:track compare` (revision-track comparison). `developer_mode` only changes whether you expose extra technical detail such as hashes, branch names, or raw git output -- it does not hide the collaboration workflow itself.
+
+When useful, describe Scriveno's creative-context model in one sentence: Scriveno tracks what moves, including characters, ideas, reader understanding, objects, places, procedures, doctrines, evidence, and themes. Keep this as orientation, not a lecture.
+
+Only show commands where `available` includes the current work type's group, OR where it's `"all"`, **and** any narrower command-level constraints still pass for the specific work type. For example, `book-proposal` is still hidden for fiction prose because `nonfiction_only` narrows the broad prose/sacred availability, and `panel-layout` is hidden for non-comic visual projects because `comic_only` narrows the visual group. Show canonical runnable command names, and use adapted labels as descriptive text only when the base command is actually available -- sacred review surfaces may show `/scr:editor-review` as scholarly review, and technical docs may show `/scr:plot-graph` as procedure map, but hidden commands stay hidden even if CONSTRAINTS.json stores an adapted label.
+
+## The filtered view
+
+If the argument matches an intent or category name (e.g., "revise", "publish"), show that view first. If it's a free-text search, match against command names and descriptions. If the writer asks for "all", "catalog", or "everything", show the grouped stage view after the compact intent view.
+
+## 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
+
+Scannable. No narration, no memory-system lectures. A writer checking help wants a menu, not an essay.
+
+If the user seems stuck, always suggest `/scr:next` -- it always knows what to do.

package/commands/scr/history.md

@@ -0,0 +1,92 @@
+---
+description: See the timeline of your saves. Shows when you saved and what you were working on.
+argument-hint: "[--limit N]"
+---
+
+# History
+
+You are showing the writer their save history. Your job is to format git log output as a scannable markdown table with NO git terminology.
+
+## What to do
+
+1. **Check for `.git/` directory.** If missing: "No save history yet. Save your work first with `/scr:save`."
+
+2. **Check for any save commits.** Run:
+   ```
+   git log --format="%H" --grep="^(Saved|Initial save)" --extended-regexp -n 1 .manuscript/ 2>/dev/null
+   ```
+   If empty: "No save history yet."
+
+3. **Read `.manuscript/config.json`** for `developer_mode`.
+
+4. **Retrieve the log.** Run:
+   ```
+   git log --format="%H|%ai|%s" --grep="^(Saved|Initial save)" --extended-regexp -n {limit} .manuscript/
+   ```
+   Default: last 20 entries. If the writer specified `--limit N`, use that number instead.
+   This command is a **save history**, so exclude administrative manuscript commits such as revision-track creation, proposals, and merges.
+
+5. **Parse each line** into three columns:
+   - **Date:** Convert the ISO timestamp to human-friendly format: "Mon D, H:MM AM/PM" (e.g., "Apr 6, 2:30 PM"). Omit year unless the save is from a different year than the current year.
+   - **Action:** Extract the verb and unit from the commit message:
+     - "Saved after drafting chapter 3" becomes "Drafted chapter 3"
+     - "Saved after editor review of chapter 2" becomes "Reviewed chapter 2"
+     - "Saved after revising chapter 2" becomes "Revised chapter 2"
+     - "Saved after planning chapter 4" becomes "Planned chapter 4"
+     - "Saved after discussing chapter 5" becomes "Discussed chapter 5"
+     - "Saved work in progress on chapter 3" becomes "Work in progress on chapter 3"
+     - "Saved: {custom message}" becomes "{custom message}"
+     - "Initial save of {title}" becomes "Started {title}"
+     - Any other message: use the message as-is
+   - **Details:** Extract supplementary information if available in the commit message (word count, scene count, etc.). If none, leave blank.
+
+6. **Format as a markdown table:**
+
+   ```
+   | Date | Action | Details |
+   |------|--------|---------|
+   | Apr 6, 2:30 PM | Drafted chapter 3 | 1,247 words, 4 scenes |
+   | Apr 6, 1:15 PM | Reviewed chapter 2 | 3 revision notes |
+   | Apr 5, 4:00 PM | Planned chapter 3 | 4 scene plans |
+   ```
+
+7. **Show the table to the writer.**
+
+## Writer mode output
+
+- **Writer mode** (`developer_mode: false`): Show ONLY the markdown table. No git hashes, no branch info, no file paths. If there are more saves beyond the displayed limit, add: "Showing your last [N] saves. Use `--limit 50` to see more."
+- **Developer mode** (`developer_mode: true`): Add an extra "Hash" column to the table with the short commit hash (first 7 characters). Include the current branch name above the table.
+
+## Edge cases
+
+- **No history:** "No save history yet. Save your work first with `/scr:save`."
+- **Only one save:** Show the table with one row. No "see more" message.
+- **Very long history:** Default to last 20. If more exist, mention: "Showing your last 20 saves. Use `--limit 50` to see more."
+- **Administrative manuscript commits:** Exclude track creation, proposals, merges, and other non-save checkpoints. Show only commits whose subject starts with `Saved` or `Initial save`.
+
+## 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
+
+Neutral. Informative. Let the table speak for itself. Don't editorialize about the writer's productivity or pace.

package/commands/scr/illustrate-scene.md

@@ -0,0 +1,211 @@
+---
+description: Generate a scene-specific illustration prompt with character visuals, setting, and mood.
+argument-hint: "<scene-ref> [--style <style>]"
+---
+
+# /scr:illustrate-scene -- Scene Illustration Prompt
+
+Generate a detailed, structured illustration prompt for a specific scene, pulling character descriptions, setting details, and mood from the manuscript.
+
+## Usage
+```
+/scr:illustrate-scene <scene-ref> [--style <style>]
+```
+
+## Instruction
+
+You are generating a scene-specific illustration prompt. Load:
+- `.manuscript/config.json` (to get `work_type`, `genre`, trim size if set)
+- Scriveno's installed/shared `CONSTRAINTS.json` (global `~/.scriveno/data/CONSTRAINTS.json` or project `.scriveno/data/CONSTRAINTS.json`) (to check `commands.illustrate-scene.available` and prerequisites)
+- `.manuscript/illustrations/ART-DIRECTION.md` (visual style bible -- **required**)
+- `.manuscript/OUTLINE.md` (to resolve `<scene-ref>` to a file path)
+- The drafted scene file for `<scene-ref>`
+- `.manuscript/CHARACTERS.md` or `.manuscript/FIGURES.md` (per `file_adaptations` for sacred work types)
+
+**Check availability:**
+
+Look up the current work type's group in CONSTRAINTS.json. If the group is in `commands.illustrate-scene.hidden` (script, academic, poetry, speech_song), inform the writer:
+
+> Illustrate-scene is not available for [work_type] projects.
+
+Then **stop**.
+
+**Check prerequisites:**
+
+Per CONSTRAINTS.json `prerequisites.illustrate-scene`: requires ART-DIRECTION.md and scene_drafted.
+
+If `.manuscript/illustrations/ART-DIRECTION.md` does not exist:
+> Run `/scr:art-direction` first to establish your visual style guide.
+
+Then **stop**.
+
+If the scene referenced by `<scene-ref>` has no draft yet:
+> Scene '{ref}' has no draft yet. Draft it first with `/scr:draft {ref}`.
+
+Then **stop**.
+
+---
+
+### Scene Analysis
+
+<scene_analysis>
+  Read the drafted scene file and extract:
+
+  **Characters present:**
+  Cross-reference with CHARACTERS.md (or FIGURES.md for sacred work types) to pull:
+  - Physical appearance (height, build, hair, eyes, distinguishing features)
+  - Clothing/style from ART-DIRECTION.md per-character visual specs
+  - Expression and posture appropriate to the scene's emotional beat
+  - Color associations from ART-DIRECTION.md
+
+  **Setting / Location:**
+  - Indoor or outdoor
+  - Time of day and lighting conditions
+  - Weather and atmosphere (if outdoor)
+  - Key objects, furniture, architecture
+  - Cross-reference with ART-DIRECTION.md per-setting visual specs if the location is defined there
+
+  **Key action or emotional moment:**
+  Identify the single most visually compelling beat in the scene -- the "illustratable moment." This is the focal point of the illustration. Prefer:
+  - A moment of high emotion (confrontation, revelation, tenderness)
+  - A moment of decisive action (a character making a choice visible in body language)
+  - A moment of visual drama (arrival, discovery, transformation)
+
+  **Mood / Atmosphere:**
+  - Emotional tone: tension, joy, mystery, sorrow, wonder, dread, intimacy, triumph
+  - How this maps to visual treatment: lighting quality, color temperature, depth of field
+</scene_analysis>
+
+---
+
+### Prompt Generation (D-01 Structured Format)
+
+<prompt_generation>
+  Generate the illustration prompt with the following sections:
+
+  ```markdown
+  # Illustration Prompt: [Scene Reference]
+
+  **Scene:** [scene title or reference]
+  **Source:** [file path of drafted scene]
+
+  ## Subject
+
+  [The key moment described in detail. Include all characters present with their actions, positions relative to each other, and emotional states. Describe what is happening -- not abstractly, but as a specific frozen moment.]
+
+  ## Composition
+
+  [Suggested framing and visual structure:]
+  - **Shot type:** [wide establishing | medium | close-up | extreme close-up | over-the-shoulder | bird's-eye | worm's-eye]
+  - **Focal point:** [what the eye should be drawn to first]
+  - **Depth:** [foreground, midground, background elements]
+  - **Negative space:** [where breathing room exists in the frame]
+  - **Eye flow:** [how the viewer's gaze moves through the image]
+
+  ## Style
+
+  [From ART-DIRECTION.md visual style section. Art style, rendering technique, level of detail. If --style flag provided, blend the requested style with the established art direction.]
+
+  ## Color Palette
+
+  [From ART-DIRECTION.md color palette, adjusted for this scene's mood:]
+  - **Dominant:** [primary color for this scene and why]
+  - **Supporting:** [secondary colors]
+  - **Accent:** [highlight/focal point color]
+  - **Mood shift:** [how palette differs from default -- darker for tense scenes, warmer for intimate, cooler for melancholy, desaturated for dreamlike]
+
+  ## Mood
+
+  [Derived from scene analysis:]
+  - **Emotional tone:** [the feeling this illustration should evoke]
+  - **Lighting:** [direction, quality, warmth -- e.g., "low warm side-lighting from a fireplace"]
+  - **Atmosphere:** [haze, clarity, rain, dust motes, etc.]
+  - **Time of day:** [if relevant to lighting]
+
+  ## Characters
+
+  [For each character present in the scene:]
+
+  ### [Character Name]
+  - **Appearance:** [from CHARACTERS.md / FIGURES.md]
+  - **Clothing:** [from ART-DIRECTION.md character specs or scene context]
+  - **Expression:** [appropriate to this scene's emotional beat]
+  - **Posture/Action:** [what they are doing in this moment]
+  - **Position:** [where in the frame -- foreground, left, center, background]
+
+  ## Setting Details
+
+  [Location-specific visual elements:]
+  - **Environment:** [indoor/outdoor, architecture, landscape]
+  - **Key objects:** [props, furniture, natural elements that matter to the scene]
+  - **Textures:** [surfaces, materials, fabrics visible]
+  - **Background:** [what fills the space beyond the main action]
+
+  ## Technical Specs
+
+  - **Dimensions:** [full page: match trim size at 300 DPI | half page: trim width x half trim height at 300 DPI]
+  - **Orientation:** [portrait | landscape]
+  - **DPI:** 300
+  - **Bleed:** 0.125" on all sides if full-bleed
+  - **Safe area:** Keep key elements 0.25" from trim edge
+  ```
+
+  If `--style` is provided, note the requested style and blend it with the ART-DIRECTION.md established style, explaining any adjustments.
+</prompt_generation>
+
+---
+
+### Output
+
+Create the output directory if needed:
+```bash
+mkdir -p .manuscript/illustrations/scenes/
+```
+
+Save to `.manuscript/illustrations/scenes/{scene-ref}-illustration-prompt.md`
+
+Replace any slashes or spaces in `{scene-ref}` with hyphens for the filename.
+
+Commit: `illustration: generate scene prompt for {scene-ref}`
+
+After saving, tell the writer:
+> Illustration prompt saved to `.manuscript/illustrations/scenes/{scene-ref}-illustration-prompt.md`.
+>
+> Copy this prompt into any AI image tool (GPT Image, Stable Diffusion, Midjourney) or share with an illustrator.
+>
+> To regenerate with a different style: `/scr:illustrate-scene {ref} --style watercolor`
+
+---
+
+### Edge Cases
+
+- **Sacred work type:** Use FIGURES.md instead of CHARACTERS.md. Adapt visual language for sacred art traditions (iconographic conventions, liturgical colors, sacred geometry motifs)
+- **Character not in CHARACTERS.md:** Include what can be inferred from the scene text and note: "Character '{name}' has no entry in CHARACTERS.md. Add one with `/scr:new-character {name}` for richer visual descriptions."
+- **No ART-DIRECTION.md:** Hard stop -- prerequisite per CONSTRAINTS.json
+- **Scene not drafted:** Hard stop -- prerequisite per CONSTRAINTS.json
+- **Multiple illustratable moments:** Pick the single strongest, note alternatives: "Other illustratable moments in this scene: [list]. Re-run with `--moment 2` to target a different beat."
+- **Scene with no characters:** Generate environment-only prompt (landscape, interior, establishing shot)
+- **Very long scene:** Focus on the climactic beat, not the entire scene
+
+## 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/import.md

@@ -0,0 +1,95 @@
+---
+description: Import an existing manuscript (docx, markdown, txt, or directory) and structure it into a Scriveno .manuscript/ directory.
+argument-hint: "<file_or_directory_path> [--type <work_type>]"
+---
+
+# Import
+
+You are importing an existing manuscript into Scriveno. The writer has content -- in a Google Doc, a Scrivenoer project, a folder of markdown files, a Word document, or similar -- and wants Scriveno's tooling without starting from scratch.
+
+## What to do
+
+1. **Locate the file or directory.** Accept: .docx, .md, .txt, .rtf, a directory of any of these.
+
+2. **Read the content.** For docx, use pandoc or similar to extract text. For markdown, read directly. For a directory, concatenate files in order.
+
+3. **Detect the work type.** If `--type` was passed, use it. Otherwise analyze the content and make a best guess:
+   - Scene headers (`INT./EXT.`) -> screenplay
+   - Chapter markers with prose -> novel or memoir
+   - Section headers with citations -> academic paper
+   - Verse and chapter numbers -> scripture
+   - Panel descriptions -> comic
+   - Poem titles separated by breaks -> poetry collection
+   - Ask the writer to confirm.
+
+4. **Parse structure.** Identify the unit boundaries based on the work type's `command_unit` from CONSTRAINTS.json. For a novel, find chapter breaks. For a screenplay, find act breaks or scene headers. For a research paper, find section headers.
+
+5. **Run voice analysis.** Take a 2000-word sample from the imported text and extract the writer's voice DNA: sentence architecture, vocabulary register, figurative density, POV, tense, dialogue style. Populate STYLE-GUIDE.md with the detected values. Flag anything uncertain for the writer to confirm.
+
+6. **Detect characters.** Scan for proper nouns that appear as speakers in dialogue or as recurring agents in narration. Build a draft CHARACTERS.md with name, estimated role (protagonist, antagonist, supporting), and detected voice patterns. Flag for writer review.
+
+7. **Generate the .manuscript/ directory.** Create all context files (WORK.md, BRIEF.md, OUTLINE.md, RECORD.md, STYLE-GUIDE.md, CHARACTERS.md, etc.) populated from the import. Also copy `WRITING-RULES.md` verbatim from the installed Scriveno templates (`templates/WRITING-RULES.md`) into `.manuscript/` so the drafter, voice-checker, and originality-check have the canonical universal rules available. Save the actual drafted text as `.manuscript/drafts/body/{N}-{A}-DRAFT.md` files, one per atomic unit.
+
+   Populate `RECORD.md` from the imported manuscript, not from speculation. Extract established on-page facts, open threads, promises, continuity facts, reader expectations, and visible character, subject, argument, procedure, image, object, or relationship movement. Mark uncertain discoveries as "needs writer confirmation" instead of treating them as settled truth.
+
+8. **Set STATE.md** to reflect that all imported units are drafted but not yet reviewed. This lets the writer pick up with `/scr:editor-review` or `/scr:next`.
+
+9. **Generate a report.** Tell the writer:
+   ```
+   Imported [filename] as a [work_type].
+
+   Structure detected: X chapters, Y scenes total
+   Word count: 65,432
+   Voice profile: extracted from 2000-word sample (review in STYLE-GUIDE.md)
+   Characters detected: 7 (review in CHARACTERS.md)
+   Record initialized: established facts and open threads extracted into RECORD.md
+
+   Some things I wasn't sure about:
+   - [specific flags: uncertain chapter breaks, possible POV shifts, etc.]
+
+   Next steps:
+   - Review STYLE-GUIDE.md and CHARACTERS.md -- confirm or adjust
+   - Run /scr:next to start working on the imported manuscript
+   ```
+
+## Edge cases
+
+- **Messy source.** If the import has weird formatting, OCR errors, or inconsistent structure, do your best and flag the issues. Don't refuse the import.
+- **Huge manuscript.** For texts over 200k words, warn about import time but proceed. Split voice analysis across multiple samples.
+- **Mixed work types.** A Google Doc with both prose and outline notes -- import as primary work type, save notes to `.manuscript/notes/`.
+- **Source in a different language.** Detect it. Ask if the writer wants to work in the source language or translate first.
+- **No clear structure.** If you can't find chapter or scene breaks, ask the writer how they want the text divided before creating draft files.
+
+## What NOT to do
+
+- Don't "improve" the writer's text during import. Preserve it exactly. They'll revise via normal commands.
+- Don't rename files without asking.
+- Don't skip voice analysis -- it's the highest-value part of import.
+- Don't assume character roles without evidence. Mark uncertain roles as such.
+
+## 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
+
+Respectful. The writer has worked on this text. You're bringing it into a new system, not judging it. Report what you found clearly, flag your uncertainties honestly, and make clear the writer is in charge of confirming.