docs: teach the composer first and describe what --out actually is

README Quick Start went straight to `generate` with a lyrics file the reader
was never told how to produce, and the write section described `--out` as
"write the song to a file" — which is what made the composite-document bug
easy to miss. Quick Start now leads with write → fill → generate → download,
`--out` is documented as the lyric block only, and the redirection-versus-
`--out` distinction is stated instead of implied.

The skill and CHANGELOG record the same contract, including the envelope
change from a `generate` string to `next_action.argv`.

Claude-Session: https://claude.ai/code/session_01JpQKiFkvQHL5W1v4chubdR

Author: longevityboris

CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## v0.8.0 — the composer and the renderer agree about the artifact
+
+One invariant now holds end to end: the file named by the emitted generate command exists, is directly consumable by `--lyrics-file`, contains no unresolved instructions, and reflects every selected control.
+
+**Breaking** (agents reading `write --json`):
+
+- `write --out FILE` writes the **lyric block only**. It previously wrote a composite document (title, Style Prompt, `---` rules, Suno Tags, and in priming mode the Prime-Stack Map and research artefact) that the emitted workflow then handed to `--lyrics-file` — so headers, tags and research metadata were sent to Suno as lyrics and embedded in the MP3. The composite document moved to the new `--project-out FILE`.
+- The `generate` string field is replaced by `next_action: {argv, command}`. `argv` is authoritative; `command` is shell-escaped display text. It is `null` when no `--out` file exists, instead of advertising a hardcoded `song.txt` that was never written.
+- `write --mode priming` requires `--target`, `--objective` and `--domain` (exit 3 when missing) — priming is consent-based and every run must be auditable. `--domain` and `--subtlety` values are validated.
+- `guide` lost the `write` alias (it competed with the `suno write` command).
+
+**Fixes:**
+
+- `--mood` / `--vocal` / `--bpm` / `--instrumental` now drive the Style Prompt, the `[Mood:]`/`[Energy:]`/vocal meta-tags and `suno_tags` from one resolved-controls struct. `--mood "dark and brooding"` no longer emitted `[Mood: Uplifting]` and an "uplifting" tag alongside it.
+- `--instrumental` is coherent: no `<...>` fill instructions, `--instrumental` in the emitted command, no vocal-only tags.
+- Titles and paths in the emitted command are shell-escaped (`She Said "Go"` produced invalid shell).
+- `generate` refuses lyrics containing unresolved `<...>` scaffold placeholders (exit 3, naming the line numbers) so an unfilled draft cannot burn ~70 credits. `--force` overrides.
+- The emitted command no longer pins `--model v4.5-all` while help and config advertise v5.5 — it omits `--model` so the configured default applies, and names the cheap-draft option separately.
+- New fields: `placeholders_remaining`, `ready_to_generate`, `missing_requirements`, `project_written`.
+
+**Discovery:**
+
+- `write` leads the command list in `--help`; the root example is the full write → fill → generate → download flow, with a one-liner distinguishing write/generate/describe/lyrics. README Quick Start mirrors it.
+- `write --help` no longer claims plain text on stdout while the framework sends JSON when piped: shell redirection gets the envelope, `--out` gets the lyrics file.
+- `agent-info` gained the `write` output schema, workflow, and mode-specific required fields.
+
 ## v0.6.0 — framework conformance, captcha preflight, real config
 
 **Breaking** (agents pinned to the 0.5.x contract must update):

README.md

@@ -2,7 +2,7 @@
 
 # suno
 
-**Generate AI music from your terminal — full Suno v5.5 support**
+**Write and generate AI music from your terminal — full Suno v5.5 support**
 
 <br />
 
@@ -86,25 +86,24 @@ suno doctor
 # 3. Check your credits
 suno credits
 
-# 4. Generate a song with full control
+# 4. Write a song — the composer scaffolds it, you fill the <...> lyric slots
+suno write --genre "indie rock" --theme "late-night city drives" --vocal male --out song.txt
+
+# 5. Generate the audio from the file you just filled (write prints this exact command)
 suno generate \
-  --title "Weekend Code" \
-  --tags "indie rock, guitar, upbeat" \
-  --exclude "metal, heavy" \
-  --lyrics-file lyrics.txt \
-  --vocal male \
-  --weirdness 40 \
-  --style-influence 65 \
+  --title "Night Drive" \
+  --tags "Indie rock, jangly and nostalgic, 110 BPM, warm male vocals, clean guitars, driving drums" \
+  --lyrics-file song.txt \
   --wait --download ./songs/
 
-# 5. Generate with your voice persona
+# 6. Generate with your voice persona
 suno generate \
   --title "My Song" \
   --tags "pop, warm" \
   --persona e483d2f0-50ca-4a09-8a74-b9e074646377 \
   --lyrics "[Verse]\nHello from the CLI"
 
-# 6. Let Suno write the lyrics for you
+# 7. Or skip the composer and let Suno write the lyrics from a description
 suno describe --prompt "a chill lo-fi track about rainy mornings" --wait
 ```
 
@@ -115,14 +114,18 @@ Generation costs ~70 credits per call on v5.5 (35 per clip, 2 clips per call —
 `suno write` is the way to compose. It assembles a Suno-ready song scaffold from a genre grammar compiled into the binary — a Style Prompt line, a meta-tagged `[Verse]`/`[Chorus]` skeleton with inline `<...>` lyric placeholders, and a Suno Tags line — then hands you the exact `suno generate` command to run. The grammar is executable, so you never hand-assemble a style prompt: run one command, fill the `<...>` slots, generate.
 
 ```bash
-# 1. Scaffold the song (free, no credits) — plain text to stdout, or --out to a file
+# 1. Scaffold the song (free, no credits) — --out writes the lyric block to a file
 suno write --genre "indie rock" --theme "late-night city drives" --vocal male --viral --out song.txt
 
-# 2. Fill the <...> lyric lines in song.txt, then generate the audio
-suno generate --title "..." --tags "..." --lyrics-file song.txt --model v4.5-all --wait --download ./songs/
+# 2. Fill the <...> lyric lines in song.txt, then run the command `write` printed
+suno generate --title "..." --tags "..." --lyrics-file song.txt --wait --download ./songs/
 ```
 
-Fuzzy genre matching covers ~24 subgenres; an unknown genre is passed through verbatim as a style tag, so `write` never fails on input. In human mode the song is raw plain text on stdout and the ready-to-run `suno generate` command prints to stderr; piped or with `--json` you get a `{title, mode, genre, style_prompt, structure, suno_tags, structure_tags, bpm, vocal, theme, viral, instrumental, generate}` envelope.
+`--out` writes the **lyric block only** — no title, no style prompt, no tag list — so the file feeds `generate --lyrics-file` directly and nothing but lyrics reaches the model. The title, Style Prompt and Suno Tags go to stderr (human mode) and into the JSON envelope; `--project-out FILE` additionally saves the full composite document for humans. `suno generate` refuses lyrics that still contain `<...>` scaffold placeholders (exit 3, naming the line numbers), so an unfilled draft can never burn credits — `--force` overrides.
+
+Note that shell redirection (`suno write > song.txt`) receives the JSON envelope, not lyrics: output is a JSON envelope whenever stdout is not a terminal. `--out` is the way to get an editable lyrics file.
+
+Fuzzy genre matching covers ~24 subgenres; an unknown genre is passed through verbatim as a style tag, so `write` never fails on input. Piped or with `--json` you get a `{title, mode, genre, style_prompt, structure, suno_tags, structure_tags, bpm, vocal, theme, viral, instrumental, placeholders_remaining, ready_to_generate, missing_requirements, next_action, written}` envelope. `next_action.argv` is the authoritative handoff — run it as argv, never shell-parse `next_action.command`. It is `null` until `--out` names a real file, and the emitted command omits `--model` so your configured default applies (add `--model v4.5-all` for a ~10-credit draft).
 
 ### Priming / research songs
 
@@ -135,6 +138,8 @@ suno write --mode priming \
   --domain marketing --subtlety stealth --out song.txt
 ```
 
+Priming is consent-based, so `--target`, `--objective` and `--domain` are required: an incomplete request exits 3 with the missing flags named, rather than emitting a scaffold and a ready-to-run command. The objective also seeds the song theme. The Prime-Stack Map and research artefact stay out of the lyrics file — they live in the JSON envelope and `--project-out`.
+
 The deep references live in the built-in guides: `suno guide songwriting` for the full grammar, `suno guide priming` for the consent frame, evidence-graded prime library, and quality gates.
 
 | Flag | What it does | Values |
@@ -145,11 +150,14 @@ The deep references live in the built-in guides: `suno guide songwriting` for th
 | `--vocal` | Vocal gender direction | male, female |
 | `--bpm` | Tempo | number (else the genre's default) |
 | `--viral` | Add earworm/hook meta-tags | flag |
-| `--instrumental` | No vocals, no lyric placeholders | flag |
+| `--instrumental` | No vocals, no lyric placeholders; adds `--instrumental` to the emitted command | flag |
 | `--title` | Song title | free text (else derived from theme) |
 | `--mode` | Composition mode | songwriting (default), priming |
-| `--target` / `--objective` / `--domain` / `--subtlety` | Priming research fields | `--mode priming` only |
-| `--out` | Write the song to a file | path (else stdout) |
+| `--target` / `--objective` / `--domain` | Priming research fields | required with `--mode priming` |
+| `--subtlety` | Priming subtlety dial | stealth, medium (default), overt |
+| `--out` | Write the lyric block to a file (the generation input) | path |
+| `--project-out` | Write the composite human document to a file | path |
+| `--download` | Download dir baked into the emitted generate command | path (default `./`) |
 
 ## Commands
 

assets/SKILL.md

@@ -11,21 +11,22 @@ One binary does the whole job — composing the song and rendering the audio. Al
 
 1. Scaffold a Suno-ready song from the built-in grammar:
    ```bash
-   suno write --genre "indie rock" --theme "late-night city drives" --vocal male --viral --out song.txt
+   suno write --genre "indie rock" --theme "late-night city drives" --vocal male --viral --out song.txt --json
    ```
-   You get a Style Prompt line, a meta-tagged `[Verse]`/`[Chorus]` skeleton with inline `<...>` lyric placeholders, a Suno Tags line, and the exact `suno generate` command to run next.
-2. Fill in the `<...>` lyric lines in `song.txt`.
-3. Render the audio:
+   `--out` writes the **lyric block only** (meta-tagged `[Verse]`/`[Chorus]` skeleton with inline `<...>` placeholders), so the file feeds `generate --lyrics-file` directly. The Style Prompt, Suno Tags and `data.next_action` come back in the JSON envelope. `--project-out FILE` saves the composite human document; never pass that one as lyrics.
+2. Fill in the `<...>` lyric lines in `song.txt` — replace every angle-bracket span, keep the `[Section]` tags, repeat the chorus verbatim.
+3. Render the audio by running `data.next_action.argv` (authoritative — never shell-parse `next_action.command`):
    ```bash
-   suno generate --title "..." --tags "..." --lyrics-file song.txt --model v4.5-all --wait --download ./songs/
+   suno generate --title "..." --tags "<style_prompt>" --lyrics-file song.txt --wait --download ./songs/
    ```
+   `generate` exits 3 if any `<...>` placeholder survives, so an unfilled scaffold can never burn credits. It uses the configured default model; add `--model v4.5-all` for a ~10-credit draft.
 
 ## Priming / research songs
 
 ```bash
-suno write --mode priming --target "..." --objective "..." --domain investment --subtlety stealth --out song.txt
+suno write --mode priming --target "..." --objective "..." --domain investment --subtlety stealth --out song.txt --json
 ```
-Adds a chill-lounge low-arousal scaffold plus a Prime-Stack Map and research-artefact block. Then fill the lyrics and `suno generate` as above.
+Adds a chill-lounge low-arousal scaffold plus a Prime-Stack Map and research-artefact block (in the envelope, not the lyrics file). Priming is consent-based: `--target`, `--objective` and `--domain` are required and a missing one exits 3. Then fill the lyrics and `suno generate` as above.
 
 ## Deep reference & everything else
 
@@ -35,4 +36,4 @@ Adds a chill-lounge low-arousal scaffold plus a Prime-Stack Map and research-art
 - `suno --help` / `suno <command> --help` — usage, tips, real examples
 - First run: `suno auth --login`, then `suno doctor` to verify
 
-Piped output is a JSON envelope automatically. `suno write` and `suno lyrics` are free; generation ≈70 credits/call on v5.5.
+Piped output is a JSON envelope automatically — `suno write > song.txt` gets JSON, not lyrics; use `--out`. `suno write` and `suno lyrics` are free; generation ≈70 credits/call on v5.5.