scriveno 2.0.5

package/commands/scr/publish.md

@@ -0,0 +1,455 @@
+---
+description: "Publishing wizard or preset-driven pipeline. Chains export commands based on destination."
+argument-hint: "[--preset <preset>] [--all] [--skip-validate]"
+---
+
+# /scr:publish -- Publishing Wizard
+
+You are the publishing wizard. Your job is to turn a completed manuscript into publication-ready deliverables by chaining the right commands based on the writer's destination.
+
+## Usage
+
+```
+/scr:publish [--preset <preset>] [--all] [--skip-validate]
+```
+
+- `--preset <preset>` -- Run a named preset pipeline without questions
+- `--all` -- Run every preset available for the current work type
+- `--skip-validate` -- Skip the scaffold-marker gate (not recommended)
+- No arguments -- Run the interactive wizard
+
+---
+
+## Instruction
+
+### STEP 0: BOOTSTRAP (context-cost protocol)
+
+Read `.manuscript/CONTEXT.md` first if it exists. If its `Updated` timestamp is newer than `.manuscript/STATE.md` and newer than the newest file in `.manuscript/drafts/body/`, use it as your orientation source for project title, work type, phase, current unit, recent activity, and open items. In STEP 1, skip the raw-file loads of `config.json`, `STATE.md`, and `OUTLINE.md` for those fields -- still load `CONSTRAINTS.json` (CONTEXT.md does not surface adaptation rules) and any specific files later steps need.
+
+If CONTEXT.md is missing, stale, or contradicts STATE.md, fall back to the original loads in STEP 1 unchanged. See `docs/context-protocol.md` for the contract.
+
+---
+
+### STEP 1: LOAD CONTEXT
+
+Load these project files:
+
+- `.manuscript/config.json` -- to get `work_type`, title, author, language
+- Scriveno's installed/shared `CONSTRAINTS.json` (global `~/.scriveno/data/CONSTRAINTS.json` or project `.scriveno/data/CONSTRAINTS.json`) -- to check `publishing_prerequisites`, `exports` section, and work type group
+- `.manuscript/OUTLINE.md` -- to verify draft completeness
+
+Determine the work type group from CONSTRAINTS.json `work_type_groups` so you can check which presets and commands are available.
+
+---
+
+### STEP 1.5: VALIDATE MANUSCRIPT
+
+**Check for scaffold markers in `.manuscript/drafts/`.**
+
+Scan all `.md` files in `.manuscript/drafts/` for:
+- Lines containing `[Fill in` (covers `[Fill in:]`, `[Fill in or delete:]`)
+- Lines containing `[Delete if not applicable:]`
+- Lines containing `Alternate 1:` or `Alternate 2:`
+- Files with more than one `# ` (top-level H1) heading
+
+**Note:** `{{VAR}}` tokens are NOT scaffold markers and must not be flagged. They are writer content placeholders, out of scope for this gate.
+
+**If `--skip-validate` was passed:**
+
+> **Warning: Validate gate skipped (`--skip-validate`). Your manuscript may contain
+> unresolved scaffold markers. Run `/scr:validate` to check before submitting.**
+
+Proceed to STEP 2.
+
+**If markers are found** (and `--skip-validate` was not passed):
+
+> **Publishing blocked: unresolved scaffold markers found.**
+>
+> [list each as: `path/to/file.md:LINE_NUMBER: marker text`]
+>
+> **Fix:** Run `/scr:cleanup --apply` to remove scaffold markers, or manually
+> edit the listed files, then re-run this publish command.
+
+Then **stop** -- do not proceed to STEP 2.
+
+If no markers found: proceed to STEP 2.
+
+---
+
+### STEP 1.6: FRONT-MATTER GATE
+
+**1.6a -- Scaffold exclusion**
+
+Check if `.manuscript/front-matter/` exists.
+
+If the directory does not exist:
+> **Note:** No front matter found -- run `/scr:front-matter` first if you want publication front matter included.
+
+Proceed to 1.6b.
+
+If the directory exists, scan all `.md` files in `.manuscript/front-matter/`. For each file, check the first 10 lines for a YAML block containing `scaffold: true`. Build a scaffold exclusion list of the paths of all files where `scaffold: true` is found.
+
+If any files were added to the scaffold exclusion list, note them for the assembly step and show:
+> **Note:** [N] scaffold front-matter element(s) will be excluded from this export:
+>   - `.manuscript/front-matter/12-preface.md` (scaffold: true -- edit and set scaffold: false to include)
+>
+> To include a scaffold element, open the file and change `scaffold: true` to `scaffold: false`.
+
+If no scaffold files were found, show no note.
+
+**1.6b -- GENERATE element auto-refresh**
+
+If `.manuscript/front-matter/` does not exist, skip auto-refresh and proceed to STEP 2.
+
+If `.manuscript/WORK.md` does not exist, skip auto-refresh and proceed to STEP 2.
+
+Compare the modification timestamp of `.manuscript/WORK.md` against each of the following GENERATE front-matter files:
+- `.manuscript/front-matter/01-half-title.md`
+- `.manuscript/front-matter/03-title-page.md`
+- `.manuscript/front-matter/04-copyright.md`
+- `.manuscript/front-matter/07-toc.md`
+
+To compare timestamps, use the appropriate command for the platform:
+- macOS: `stat -f %m <file>`
+- Linux: `stat -c %Y <file>`
+- Windows: `(Get-Item '<file>').LastWriteTimeUtc.Ticks`
+- If timestamp comparison is not possible, assume WORK.md is newer and regenerate.
+
+If WORK.md is newer than ANY of those 4 files, or if ANY of those 4 files do not exist:
+Re-run the GENERATE step from `/scr:front-matter` for elements 1, 3, 4, and 7 only (half-title, title page, copyright page, TOC) using current WORK.md metadata. Regenerate all four even if only one triggered the condition. Do NOT regenerate scaffold elements (5, 6, 11, 12, 13) or any other elements.
+
+If WORK.md is not newer than all 4 files and all 4 files exist: skip regeneration silently.
+
+Proceed to STEP 2.
+
+---
+
+### STEP 2: ROUTE
+
+**If `--preset` is given:** Validate the preset name against the known presets below. If valid, jump to STEP 4 (preset pipeline). If invalid, show the list of available presets and stop.
+
+**If `--all` is given:** Run every preset available for the current work type group. Warn the writer this will take a while. Run each preset sequentially, showing progress between them.
+
+**If no arguments:** Run the interactive wizard (STEP 3).
+
+---
+
+### STEP 3: INTERACTIVE WIZARD
+
+#### 3a. Check Prerequisites (per D-07)
+
+Check each publishing prerequisite and show a readiness checklist:
+
+```
+Publishing Readiness Checklist
+==============================
+[x] Complete draft (all units drafted)
+[ ] Front matter -- run /scr:front-matter
+[x] Back matter
+[ ] Blurb -- run /scr:blurb
+[ ] Synopsis -- run /scr:synopsis
+[x] Cover art
+
+Missing 3 prerequisites. Generate them now? (yes/no)
+```
+
+**How to check each prerequisite:**
+
+| Prerequisite | How to Check | Fix Command |
+|-------------|-------------|-------------|
+| Complete draft | All units in OUTLINE.md have corresponding draft files in `.manuscript/drafts/body/` | `/scr:draft` (draft remaining units) |
+| Front matter | `.manuscript/front-matter/` directory has files | `/scr:front-matter` |
+| Back matter | `.manuscript/back-matter/` directory has files | `/scr:back-matter` |
+| Blurb | `.manuscript/output/blurb.md` exists | `/scr:blurb` |
+| Synopsis | Any `.manuscript/marketing/SYNOPSIS-*.md` file exists | `/scr:synopsis` |
+| Cover art | `.manuscript/build/ebook-cover.jpg` or `.png`, plus `.manuscript/build/paperback-cover.pdf` for print presets | `/scr:cover-art` |
+
+**Canonical cover build surface:** Scriveno's cover handoff contract lives under `.manuscript/build/`:
+- Ebook front cover: `.manuscript/build/ebook-cover.jpg` (or `.png`)
+- Paperback full wrap: `.manuscript/build/paperback-cover.pdf`
+- Hardcover case wrap: `.manuscript/build/hardcover-cover.pdf`
+
+**Critical prerequisite:** If the draft is not complete (missing body units), warn the writer:
+> Your draft is not complete. Missing units: [list]. Run `/scr:next` to continue drafting, or proceed anyway with incomplete manuscript.
+
+**Non-critical prerequisites:** If the writer says "yes" to generating missing items, run each missing command in order before proceeding.
+
+#### 3b. Choose Destination
+
+After prerequisites are resolved, ask the destination question as a two-level decision tree. Show the top-level prompt first, then drill into the chosen branch. Filter every option against the current work type group (skip a row entirely when the underlying preset is unavailable for the group).
+
+> What are you doing?
+>
+> 1. **Share** -- hand someone a single file (beta reader, friend, agent who asked for "the manuscript")
+> 2. **Publish** -- ship to a retail or distribution platform (KDP, IngramSpark, ebook stores)
+> 3. **Submit** -- query letter / submission package for an agent or editor
+> 4. **Academic** -- journal article, thesis, or other academic build
+> 5. **Screenplay** -- script-format deliverables for a manager or production
+> 6. **Everything** -- generate every format I can (archival)
+> 7. **Custom** -- pick specific formats by hand
+
+Then, based on the top-level answer:
+
+**Share branch** -- ask:
+> Which file?
+>
+> 1. **share-pdf** -- manuscript PDF (single file, no print formatting)
+> 2. **share-docx** -- manuscript DOCX (single file, opens in Word/Pages/Docs)
+> 3. **share-epub** -- standalone EPUB (single file, no store packaging)
+> 4. **share-bundle** -- PDF + DOCX + EPUB together
+
+**Publish branch** -- ask:
+> Where?
+>
+> 1. **ebook-wide** -- All major ebook stores (EPUB + manuscript PDF)
+> 2. **kdp-ebook** -- Amazon Kindle (EPUB)
+> 3. **kdp-paperback** -- Amazon KDP print-on-demand (interior PDF + KDP package)
+> 4. **ingram-paperback** -- IngramSpark bookstore distribution (CMYK PDF/X-1a + package)
+
+**Submit branch** -- ask:
+> Which submission?
+>
+> 1. **query-submission** -- agent query (blurb + synopsis + query letter + sample)
+> 2. **submission-package** -- full manuscript submission (DOCX + synopsis + cover letter + bio)
+
+**Academic branch** -- map directly to:
+- **academic-submission** -- journal article wrapper for the writer's chosen academic platform (`ieee`, `acm`, `lncs`, `elsevier`, `apa7`)
+- **thesis-defense** -- thesis/dissertation build with front/back matter and academic platform wrapper
+
+If only one academic preset is appropriate, run it; otherwise ask which.
+
+**Screenplay branch** -- map directly to:
+- **screenplay-query** -- Fountain + FDX + query package
+
+**Everything branch** -- map directly to:
+- **all-formats** -- generate markdown, DOCX, PDF, and EPUB in one pass (no store/package wrappers)
+
+**Custom branch** -- ask which `/scr:export --format <format>` calls to chain, then run them in sequence.
+
+Map the final answer to a preset and proceed to STEP 3c.
+
+#### 3c. Choose Front + Back Matter Level
+
+If the chosen preset includes front-matter or back-matter generation steps (any preset whose pipeline calls `/scr:front-matter` or `/scr:back-matter` -- see STEP 4), and the corresponding directories are empty, ask the writer once **per matter type that the preset will generate**:
+
+> Front matter: how much should I generate?
+>
+> 1. **skip** -- I do not want any front matter
+> 2. **minimum** -- title page, copyright, TOC (legal floor)
+> 3. **balanced** -- minimum + half-title, dedication, epigraph, acknowledgments (recommended for retail)
+> 4. **maximum** -- every applicable element
+
+> Back matter: how much should I generate?
+>
+> 1. **skip** -- I do not want any back matter
+> 2. **minimum** -- about-the-author (legal floor)
+> 3. **balanced** -- minimum + colophon, permissions when applicable
+> 4. **maximum** -- every applicable element
+
+**Defaults to suggest if the writer just hits enter:**
+- Share-* and all-formats presets: **minimum** for both (these are not retail builds)
+- kdp-ebook, kdp-paperback, ebook-wide, ingram-paperback: **balanced** for both
+- academic-submission, thesis-defense: **balanced** front, **balanced** back (academic adaptation will pull bibliography in automatically)
+- query-submission, screenplay-query, submission-package: skip both (the package itself does not need book front/back matter)
+
+If the writer answers **skip** for either, the preset will skip that step entirely (do not run the corresponding `/scr:front-matter` / `/scr:back-matter` call). If `.manuscript/front-matter/` or `.manuscript/back-matter/` already has files, do not ask -- treat them as already chosen and skip the prompt.
+
+Pass the chosen level to the underlying calls in STEP 4 as `--level <value>`.
+
+---
+
+### STEP 4: PRESET PIPELINES (per D-08)
+
+Run the selected preset pipeline. For each step: check if the output already exists, skip if so (tell the writer), run if missing.
+
+Show progress for each step:
+```
+Publishing: kdp-paperback
+==========================
+Step 1/4: Checking front matter... already exists, skipping
+Step 2/4: Generating back matter...
+Step 3/4: Exporting print-ready PDF...
+Step 4/4: Building KDP package...
+```
+
+#### Locked Presets (D-08)
+
+**kdp-paperback** -- Amazon KDP print-on-demand
+| Step | Command | Condition |
+|------|---------|-----------|
+| 1 | `/scr:front-matter --level {front-level}` | If `.manuscript/front-matter/` is empty AND the writer did not pick **skip** in STEP 3c |
+| 2 | `/scr:back-matter --level {back-level}` | If `.manuscript/back-matter/` is empty AND the writer did not pick **skip** in STEP 3c |
+| 3 | `/scr:export --format pdf --print-ready` | Always (produces interior PDF) |
+| 4 | `/scr:export --format kdp-package` | Always (produces KDP upload package) |
+
+**kdp-ebook** -- Amazon Kindle ebook
+| Step | Command | Condition |
+|------|---------|-----------|
+| 1 | `/scr:front-matter --level {front-level}` | If `.manuscript/front-matter/` is empty AND the writer did not pick **skip** in STEP 3c |
+| 2 | `/scr:back-matter --level {back-level}` | If `.manuscript/back-matter/` is empty AND the writer did not pick **skip** in STEP 3c |
+| 3 | `/scr:export --format epub` | Always |
+
+**query-submission** -- Traditional publishing query
+| Step | Command | Condition |
+|------|---------|-----------|
+| 1 | `/scr:blurb` | If `.manuscript/output/blurb.md` missing |
+| 2 | `/scr:synopsis` | If no `.manuscript/marketing/SYNOPSIS-*.md` file exists |
+| 3 | `/scr:query-letter` | If `.manuscript/marketing/QUERY-LETTER.md` missing |
+| 4 | `/scr:export --format query-package` | Always |
+
+**ebook-wide** -- All major ebook stores
+| Step | Command | Condition |
+|------|---------|-----------|
+| 1 | `/scr:front-matter --level {front-level}` | If `.manuscript/front-matter/` is empty AND the writer did not pick **skip** in STEP 3c |
+| 2 | `/scr:back-matter --level {back-level}` | If `.manuscript/back-matter/` is empty AND the writer did not pick **skip** in STEP 3c |
+| 3 | `/scr:export --format epub` | Always |
+| 4 | `/scr:export --format pdf` | Always (manuscript PDF for stores that accept it) |
+
+#### Additional Presets
+
+**ingram-paperback** -- IngramSpark bookstore distribution
+| Step | Command | Condition |
+|------|---------|-----------|
+| 1 | `/scr:front-matter --level {front-level}` | If `.manuscript/front-matter/` is empty AND the writer did not pick **skip** in STEP 3c |
+| 2 | `/scr:back-matter --level {back-level}` | If `.manuscript/back-matter/` is empty AND the writer did not pick **skip** in STEP 3c |
+| 3 | `/scr:export --format pdf --print-ready` | Always |
+| 4 | `/scr:export --format ingram-package` | Always |
+
+**academic-submission** -- Journal or academic press
+| Step | Command | Condition |
+|------|---------|-----------|
+| 1 | Ask the writer which supported academic platform they need: `ieee`, `acm`, `lncs`, `elsevier`, or `apa7` | If not already specified |
+| 2 | `/scr:build-print --platform <selected academic platform>` | Always |
+
+**thesis-defense** -- Thesis or dissertation
+| Step | Command | Condition |
+|------|---------|-----------|
+| 1 | `/scr:front-matter --level {front-level}` | If `.manuscript/front-matter/` is empty AND the writer did not pick **skip** in STEP 3c |
+| 2 | `/scr:back-matter --level {back-level}` | If `.manuscript/back-matter/` is empty AND the writer did not pick **skip** in STEP 3c |
+| 3 | Ask the writer which supported academic platform best matches the institution requirement: `ieee`, `acm`, `lncs`, `elsevier`, or `apa7` | If not already specified |
+| 4 | `/scr:build-print --platform <selected academic platform>` | Always |
+
+**screenplay-query** -- Screenplay agent/manager submission
+| Step | Command | Condition |
+|------|---------|-----------|
+| 1 | `/scr:blurb` | If `.manuscript/output/blurb.md` missing |
+| 2 | `/scr:synopsis` | If no `.manuscript/marketing/SYNOPSIS-*.md` file exists |
+| 3 | `/scr:query-letter` | If `.manuscript/marketing/QUERY-LETTER.md` missing |
+| 4 | `/scr:export --format fountain` | Always |
+| 5 | `/scr:export --format fdx` | Always |
+| 6 | `/scr:export --format query-package` | Always |
+
+#### Destination-neutral Presets
+
+These presets produce single deliverables without retailer-specific packaging. They are appropriate for sharing manuscripts with beta readers, collaborators, or agents who asked for "the manuscript" rather than a store package.
+
+**share-pdf** -- single-file PDF, no print formatting
+| Step | Command | Condition |
+|------|---------|-----------|
+| 1 | `/scr:export --format pdf` | Always |
+
+**share-docx** -- single-file DOCX
+| Step | Command | Condition |
+|------|---------|-----------|
+| 1 | `/scr:export --format docx` | Always |
+
+**share-epub** -- single-file standalone EPUB (no store packaging)
+| Step | Command | Condition |
+|------|---------|-----------|
+| 1 | `/scr:export --format epub` | Always |
+
+**share-bundle** -- PDF + DOCX + EPUB together for handing someone "everything readable"
+| Step | Command | Condition |
+|------|---------|-----------|
+| 1 | `/scr:export --format pdf` | Always |
+| 2 | `/scr:export --format docx` | Always |
+| 3 | `/scr:export --format epub` | Always |
+
+**all-formats** -- archival pass: every base format Scriveno can produce (no store/package wrappers)
+| Step | Command | Condition |
+|------|---------|-----------|
+| 1 | `/scr:export --format markdown` | Always |
+| 2 | `/scr:export --format docx` | Always |
+| 3 | `/scr:export --format pdf` | Always |
+| 4 | `/scr:export --format epub` | Always |
+
+If a base format is not available for the current work type group (per `CONSTRAINTS.json` `exports`), skip that step silently and continue. Report skipped formats in STEP 5.
+
+---
+
+### STEP 5: REPORT
+
+After the pipeline completes, show a summary:
+
+```
+Publishing Complete
+==================
+Preset: kdp-paperback
+
+Generated:
+  - Front matter (7 elements)
+  - Back matter (5 elements)
+  - manuscript-print.pdf (interior, 6x9, ~312 pages)
+  - kdp-package/ (cover specs, metadata, upload checklist)
+
+Skipped:
+  - Front matter (already existed)
+
+Next Steps:
+  1. Review the interior PDF at .manuscript/output/manuscript-print.pdf
+  2. Review `.manuscript/output/kdp-package/cover-specs.md` and place the finished print cover at `.manuscript/build/paperback-cover.pdf`
+  3. Upload the interior PDF and the final cover file to https://kdp.amazon.com
+  4. Set pricing, categories, and keywords on KDP
+```
+
+Adapt the "Next Steps" section to the preset:
+
+- **kdp-paperback/kdp-ebook:** KDP upload instructions
+- **ingram-paperback:** IngramSpark upload instructions
+- **query-submission/screenplay-query:** How to send query packages to agents
+- **academic-submission/thesis-defense:** Academic wrapper and TeX compilation submission steps
+- **ebook-wide:** Upload to each platform (KDP, Apple Books, Kobo, B&N, Google Play)
+- **share-pdf/share-docx/share-epub:** Path to the single output file and a one-line "send this to your reader" note. No upload steps.
+- **share-bundle:** Paths to the three output files and a note that they are interchangeable -- send whichever the recipient prefers.
+- **all-formats:** Paths to every generated file plus a note listing any formats that were skipped because they are not available for this work type.
+
+---
+
+### STEP 6: HISTORY LOG
+
+After the preset pipeline completes, append one line to `.manuscript/HISTORY.log` per `docs/history-protocol.md`:
+
+```
+{ISO timestamp} | scr:publish | preset={resolved preset} | front-level={resolved or "skip" or "-"} | back-level={resolved or "skip" or "-"} | outcome={ok|partial:<count-failed>|failed:<short-reason>}
+```
+
+Use `front-level=-` and `back-level=-` for presets that do not run front-matter / back-matter generation (share-*, all-formats, query-submission, screenplay-query, submission-package). The chained `/scr:export`, `/scr:front-matter`, `/scr:back-matter` calls log their own lines per their command specs -- this `scr:publish` line records the wrapper invocation so the log shows both the high-level intent and the granular steps. Create HISTORY.log if it does not exist.
+
+---
+
+## 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
+
+This is the moment the writer becomes a publisher. Be efficient and confident -- they are counting on you to handle the mechanical work so they can focus on the decisions that matter (cover aesthetic, blurb feel, pricing strategy). Show progress at a high level. Surface only the decisions that need their input.

package/commands/scr/query-letter.md

@@ -0,0 +1,183 @@
+---
+description: Generate agent query letter adapted to genre conventions.
+---
+
+# /scr:query-letter -- Agent Query Letter
+
+Generate a query letter adapted to genre conventions for literary agent submission.
+
+## Usage
+```
+/scr:query-letter
+```
+
+## Instruction
+
+You are a **literary agent query specialist**. You write the letters that get manuscripts requested -- concise, professional, and perfectly calibrated to genre expectations. Every genre has unspoken rules about what agents want to see first, and you know them all.
+
+---
+
+### STEP 1: LOAD CONTEXT
+
+Read the following files:
+
+1. `.manuscript/config.json` -- work type, genre, word count
+2. Scriveno's installed/shared `CONSTRAINTS.json` (global `~/.scriveno/data/CONSTRAINTS.json` or project `.scriveno/data/CONSTRAINTS.json`) -- verify `query-letter` is available for this work type (available: prose, script, sacred; hidden: academic, visual, poetry, interactive, speech_song). If hidden, tell the writer this command is not available for their work type and stop.
+3. `.manuscript/WORK.md` -- genre, word count, comparable titles, protagonist, central conflict
+4. The complete draft (for voice and tone reference)
+
+---
+
+### STEP 2: CHECK PREREQUISITES
+
+Verify that the following files exist in `.manuscript/marketing/`:
+
+- `BLURB.md` -- at least one blurb variation must exist
+- `SYNOPSIS-*.md` -- at least one synopsis must exist (any length)
+
+If either is missing, tell the writer:
+
+> "A query letter requires both a blurb and a synopsis. Please run `/scr:blurb` and `/scr:synopsis` first, then come back to `/scr:query-letter`."
+
+Stop execution if prerequisites are not met.
+
+---
+
+### STEP 3: DETERMINE GENRE AND ADAPT
+
+Read the genre from WORK.md and adapt the query letter's approach accordingly:
+
+#### Literary Fiction
+- **Lead with:** Voice and prose quality -- quote or echo a striking line
+- **Emphasize:** Themes, emotional complexity, character interiority
+- **Comp titles:** Literary authors and prize-listed books
+- **Positioning:** Place within literary tradition (e.g., "in the vein of...")
+- **Avoid:** Plot-heavy description; literary agents want to feel the prose, not just the premise
+
+#### Romance
+- **Lead with:** The central relationship -- who are these people and why is their connection irresistible?
+- **Include:** Heat level hint (clean, sweet, steamy, explicit) without being crass
+- **Comp titles:** Romance-specific (not general fiction) -- match subgenre (contemporary, historical, paranormal)
+- **Mention:** Key tropes (enemies-to-lovers, second chance, forced proximity) -- romance readers and agents search by trope
+- **Avoid:** Being coy about the HEA/HFN -- romance requires it
+
+#### Thriller / Mystery
+- **Lead with:** The hook -- the body, the threat, the ticking clock
+- **Emphasize:** Pacing, stakes, twists (hint at them without spoiling)
+- **Comp titles:** Genre-specific (name the subgenre: psychological thriller, cozy mystery, legal thriller)
+- **Include:** The ticking clock or countdown element if applicable
+- **Avoid:** Revealing the ending or the twist -- unlike a synopsis, a query letter teases
+
+#### Fantasy / Sci-Fi
+- **Lead with:** The world or concept -- what makes this universe unique?
+- **Mention:** Worldbuilding scope (epic vs. intimate, hard vs. soft magic/science)
+- **Comp titles:** Genre-specific, ideally recent (within 3-5 years)
+- **Position:** Within subgenre (epic fantasy, urban fantasy, space opera, dystopian)
+- **Avoid:** Over-explaining the magic system or technology -- save that for the synopsis
+
+#### General Fiction
+- **Lead with:** Character and conflict -- balanced approach
+- **Emphasize:** What makes this story universal and timely
+- **Comp titles:** Broad but specific (book club fiction, upmarket, contemporary)
+- **Avoid:** Being too vague -- "a story about life" tells the agent nothing
+
+#### Other Genres
+- Analyze the genre field from WORK.md
+- Research conventions for that genre's query expectations
+- Apply the closest applicable pattern from above
+- When in doubt, lead with what makes this specific book compelling
+
+---
+
+### STEP 4: COMPOSE THE QUERY LETTER
+
+Follow the standard query letter structure:
+
+#### 1. Hook (1 sentence)
+The single most compelling sentence about the book. This is the "elevator pitch" -- if the agent reads nothing else, this sentence should make them curious.
+
+#### 2. Book Paragraph (1 paragraph, 150-250 words)
+Adapted from the blurb (use the Standard variation as a starting point) but reframed for a professional audience. This is not back-cover copy -- it's a business pitch. Include:
+- Genre and word count woven naturally into the opening
+- The protagonist's situation and what disrupts it
+- The central conflict and stakes
+- The dramatic question (without resolving it)
+
+#### 3. Bio Paragraph (1 short paragraph)
+From the writer's profile, include:
+- Relevant credentials, publications, or platform
+- Why this writer is the right person to write this book
+- Any relevant personal connection to the subject matter
+- If no relevant credentials: keep it brief and confident, do not apologize
+
+#### 4. Housekeeping (1-2 sentences)
+- Title (formatted)
+- Genre and subgenre
+- Word count (rounded to nearest thousand)
+- Comparable titles with publication years
+- Note that the full manuscript is available upon request
+
+---
+
+### STEP 5: PRESENT AND REFINE
+
+Present the complete query letter to the writer. Ask:
+
+- Does the hook capture the book's essence?
+- Is the genre positioning accurate?
+- Are the comp titles appropriate and current?
+- Does the bio paragraph represent them well?
+- Is there anything that feels off-tone for their genre?
+
+---
+
+### STEP 6: SAVE
+
+Save to `.manuscript/marketing/QUERY-LETTER.md`:
+
+```markdown
+# Query Letter
+
+[Dear [Agent Name],]
+
+[hook]
+
+[book paragraph]
+
+[bio paragraph]
+
+[housekeeping]
+
+[Sincerely,]
+[Writer Name]
+
+---
+*Generated by /scr:query-letter*
+*Genre adaptation: [genre]*
+*Prerequisites: blurb, synopsis*
+```
+
+Create the `.manuscript/marketing/` directory if it does not exist.
+
+## 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.