---
description: "Publishing wizard or preset-driven pipeline. Chains export commands based on destination and enforces final compliance gates for retail, print, and distributor packages."
argument-hint: "[--preset <preset>] [--all] [--skip-validate] [--preflight]"
---

# /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.

Publishing boundary: `/scr:publish` is the destination wizard and sequencing layer. Use `/scr:export` for one-off format output, `/scr:build-ebook`, `/scr:build-print`, `/scr:build-smashwords`, and `/scr:build-poetry-submission` for final channel packages, `/scr:front-matter` and `/scr:back-matter` for matter drafting, `/scr:prepublish-review` for the final editorial gate, and `/scr:compliance-check` for the platform-policy and copyright gate.

## Usage

```
/scr:publish [--preset <preset>] [--all] [--skip-validate] [--preflight]
```

- `--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)
- `--preflight` -- Check readiness and required tools, then stop before writing deliverables
- 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 -- Existing front-matter freshness check**

Publish is a routing and packaging command. It must not create, refresh, or rewrite front-matter or back-matter files. Those are writer-facing drafting surfaces owned by `/scr:front-matter` and `/scr:back-matter`.

If `.manuscript/front-matter/` does not exist, skip the freshness check and proceed to STEP 2.

If `.manuscript/WORK.md` does not exist, skip the freshness check and proceed to STEP 2.

Compare the modification timestamp of `.manuscript/WORK.md` against each of the following generated front-matter files when they exist:
- `.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, treat freshness as unknown.

If WORK.md is newer than ANY existing generated front-matter file, if ANY of those 4 files do not exist, or if freshness is unknown, show:
> **Note:** Front matter may be stale or incomplete. Publish will not generate or refresh front matter. Run `/scr:front-matter --level minimum` or `/scr:front-matter --level balanced`, then re-run publish if you want updated front matter included.

If WORK.md is not newer than all 4 files and all 4 files exist: continue silently.

Proceed to STEP 2.

---

### STEP 1.7: PREFLIGHT MODE

If `--preflight` was passed, run a readiness check only and stop before writing exports, packages, or history entries.

Preflight must include:

1. The validation gate from STEP 1.5 unless `--skip-validate` was also passed.
2. The front-matter scaffold exclusion check from STEP 1.6a.
3. The publishing prerequisite checklist from STEP 3a.
4. Preset availability against `CONSTRAINTS.json`.
5. A policy-gate check: if `.manuscript/reviews/PLATFORM-COMPLIANCE.md` does not exist or predates the newest draft, report `[WARN] platform compliance ..... not checked` and suggest `/scr:compliance-check` for the chosen destination (platform policies, copyright diligence, AI-disclosure answers).
6. External tool checks by calling the matching export checks:
   - `share-pdf`: `/scr:export --format pdf --review --check`
   - `share-docx`: `/scr:export --format docx --check`
   - `share-epub`: `/scr:export --format epub --check`
   - `share-bundle`: `/scr:export --format pdf --review --check`, `/scr:export --format docx --check`, and `/scr:export --format epub --check`
   - `kdp-ebook`: `/scr:export --format epub --check`
   - `kdp-paperback`: `/scr:export --format pdf --print-ready --check` and `/scr:export --format kdp-package --check`
   - `ingram-paperback`: `/scr:export --format pdf --print-ready --check` and `/scr:export --format ingram-package --check`
   - `query-submission`: `/scr:export --format query-package --check`
   - `submission-package`: `/scr:export --format submission-package --check`
   - `screenplay-query`: `/scr:export --format fountain --check`, `/scr:export --format fdx --check`, and `/scr:export --format query-package --check`
   - `all-formats`: check each available base format

Use this report shape:

```text
Publishing Preflight
====================
Preset: kdp-paperback

[PASS] manuscript validation
[WARN] front matter ........ not generated
[PASS] pandoc
[PASS] typst
[SKIP] ghostscript ......... not required until ingram-package

Result: ready after 1 optional item
```

If preflight finds a blocking issue, stop and suggest the command that fixes it. Do not continue into 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 -- optional; run /scr:front-matter separately if wanted
[x] Back matter
[ ] Blurb -- run /scr:blurb
[ ] Synopsis -- run /scr:synopsis
[x] Cover art

Missing 3 items. Generate non-matter prerequisites 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/marketing/BLURB.md` exists; legacy `.manuscript/output/blurb.md` is accepted for older projects | `/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` |
| Platform compliance | `.manuscript/reviews/PLATFORM-COMPLIANCE.md` exists and is newer than the newest draft for retail, wide, print, and distributor presets | `/scr:compliance-check` |

**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.

**Front/back matter boundary:** Do not generate front matter or back matter from `/scr:publish`. If either is missing, report it as optional missing publication matter and continue unless the writer explicitly says they want to stop and run the dedicated command first. Suggested commands:

- `/scr:front-matter --level balanced`
- `/scr:back-matter --level balanced`

**Compliance boundary:** For retail, wide ebook, print, and distributor destinations, do not proceed to upload checklists or packaging without a current `.manuscript/reviews/PLATFORM-COMPLIANCE.md`. If the report is missing or older than the newest draft, stop and run or suggest `/scr:compliance-check --platform <target>`. This is not optional for KDP, IngramSpark, or wide ebook paths because AI-disclosure and rights answers are part of the publishing act.

#### 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** -- review PDF (single file, printable and shareable before publication)
> 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** -- review 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. Matter Readiness Note

Before STEP 4, check whether `.manuscript/front-matter/` and `.manuscript/back-matter/` contain publishable files. If either is missing and the preset is a retail, wide, print, or thesis-style route, show a short note:

> Front/back matter is optional but usually expected for this destination. `/scr:publish` will not draft it. Continue now to build the package without it, or stop and run `/scr:front-matter` / `/scr:back-matter` first.

If the writer chooses to stop, end with the Response Contract and suggest the dedicated matter command(s). If the writer chooses to continue, proceed to STEP 4 and list omitted matter in STEP 5.

#### 3d. Compliance Gate

Before STEP 4, run the compliance readiness check for any preset that uploads or prepares files for a platform:

- `kdp-ebook` -> `/scr:compliance-check --platform kdp-ebook`
- `kdp-paperback` -> `/scr:compliance-check --platform kdp-print`
- `ingram-paperback` -> `/scr:compliance-check --platform ingramspark`
- `ebook-wide` -> `/scr:compliance-check --platform all`
- `academic-submission` and `thesis-defense` -> `/scr:compliance-check --platform all` when the package will be submitted outside the writer's institution

If `.manuscript/reviews/PLATFORM-COMPLIANCE.md` is missing or older than the newest draft, run the matching compliance command before packaging. If live policy lookup is unavailable, the compliance command may write an `UNVERIFIED` report, but `/scr:publish` must still surface that status before it produces upload instructions.

---

### 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.

Before the preset's export steps, enforce STEP 3d for every platform preset. If the compliance report returns `STOP`, do not run export or package commands. If it returns `CLEAR WITH ACTIONS`, continue only after listing the required upload-screen answers in the progress summary.

Show progress for each step:
```
Publishing: kdp-paperback
==========================
Step 1/2: Exporting print-ready PDF...
Step 2/2: Building KDP package...
```

#### Locked Presets (D-08)

**kdp-paperback** -- Amazon KDP print-on-demand
| Step | Command | Condition |
|------|---------|-----------|
| 1 | `/scr:export --format pdf --print-ready` | Always (produces interior PDF, including existing publishable matter) |
| 2 | `/scr:export --format kdp-package` | Always (produces KDP upload package) |

**kdp-ebook** -- Amazon Kindle ebook
| Step | Command | Condition |
|------|---------|-----------|
| 1 | `/scr:export --format epub` | Always (includes existing publishable matter) |

**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:export --format epub` | Always (includes existing publishable matter) |
| 2 | `/scr:export --format pdf` | Always (manuscript PDF for stores that accept it) |

#### Additional Presets

**ingram-paperback** -- IngramSpark bookstore distribution
| Step | Command | Condition |
|------|---------|-----------|
| 1 | `/scr:export --format pdf --print-ready` | Always (includes existing publishable matter) |
| 2 | `/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 | Ask the writer which supported academic platform best matches the institution requirement: `ieee`, `acm`, `lncs`, `elsevier`, or `apa7` | If not already specified |
| 2 | `/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 review PDF, no retailer packaging or print-ready trim formatting
| Step | Command | Condition |
|------|---------|-----------|
| 1 | `/scr:export --format pdf --review` | 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** -- review PDF + DOCX + EPUB together for handing someone "everything readable"
| Step | Command | Condition |
|------|---------|-----------|
| 1 | `/scr:export --format pdf --review` | 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 pdf --review` | Always |
| 5 | `/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:
  - manuscript-print.pdf (interior, 6x9, ~312 pages)
  - kdp-package/ (cover specs, metadata, upload checklist)

Skipped:
  - Front matter (not generated by publish)
  - Back matter (already existed and included by export)

Review Checklist:
  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 "Review Checklist" 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} | matter=front:{present|missing|not-applicable},back:{present|missing|not-applicable} | outcome={ok|partial:<count-failed>|failed:<short-reason>}
```

Use `not-applicable` for presets that do not normally include book front/back matter (share-*, all-formats, query-submission, screenplay-query, submission-package). `/scr:publish` does not run `/scr:front-matter` or `/scr:back-matter`; those commands write their own history lines when the writer runs them directly. 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.

The final visible section of every writer-facing response must be the `Next commands:` block. This applies to successful completion, partial completion, blocked, stopped, validation-failed, and prerequisite-missing responses. Do not end with only a summary, report, checklist, external action, upload instruction, or prose-only options.

Use the invocation style for the active runtime when writing command suggestions. Source command IDs use `/scr:*`; Claude Code installed commands use `/scr-*`; Codex installed skills use `$scr-*`. Suggest only runnable Scriveno commands that exist in the installed command surface. Do not invent adjacent workflow names.

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.