@homie-rocks/studio 0.51.4 → 0.51.6

package/guides/music/SKILL.md

@@ -1,197 +1,88 @@
 ---
 name: music
-description: Make songs, themes and game scores for a Homie studio with ElevenLabs Music, through the creator's OWN ElevenLabs account — a composition plan for anything sung, a transcription check that every line is actually sung, mastering to a loudness target, seamless loops and stems for games — then a song page on the studio's site. It tells the person the plan, the rights and the credit cost before anything is rendered, and never spends past the budget they set. Use when someone in a studio asks for a song, a theme song, a jingle, background music, a game score, loops or stems.
-compatibility: Node 22 and ffmpeg. ElevenLabs' own CLI (elevenlabs, signed in with elevenlabs auth login) or ELEVENLABS_API_KEY, on the creator's own ElevenLabs account.
+description: "Compose music with the official ElevenLabs MCP and keep arrangement, rights, mastering and scene integration in Homie."
+compatibility: Node 22 and the official ElevenLabs plugin in the AI client. Local media processing uses ffmpeg and Chrome where needed.
 metadata:
   providers: elevenlabs
 ---
 
-# Music for a studio
-
-A studio is the folder with `studio.json` (the `studio-setup` skill makes one). Songs live in
-`music/<slug>/`, listed in `music/manifest.json`; a published entry is a page at
-`/music/<slug>/` on the studio's own site. Everything below runs through one script in this
-skill's folder: `scripts/music.mjs` (in Claude Code:
-`node "${CLAUDE_PLUGIN_ROOT}/skills/music/scripts/music.mjs" <command>`; elsewhere, the path next
-to this file). Run it from inside the studio. It needs Node 22 and ffmpeg. Every command takes
-`--json`.
-
-Finish in this turn: a render is one call that usually returns in a minute or two. Only stop early to
-ask the person something (the go-ahead on the cost, a budget, an install).
-
-## 1. The provider, only now
-
-A studio that never makes music is never asked about ElevenLabs. **Free first:** sound effects, a
-chiptune or synth theme, a game score from chords and patterns, loops and stems that cost nothing and
-need no account are the `sound` skill (synthesized on this computer). Use this skill for sung songs and
-produced music from a model, when the person wants that and has (or will make) an ElevenLabs account.
-Check when this skill starts:
-
-```sh
-node <music.mjs> check
-```
-
-It reports the road (the `elevenlabs` CLI signed in, or `ELEVENLABS_API_KEY` in the
-environment), the plan, the credits left and when they reset, whether the account can go over,
-the rights that plan gives, ffmpeg, and whether the studio's site has song pages.
-
-Not connected? Offer ElevenLabs' own tools, never a copy of anyone's key or code:
-
-- **The official CLI** (what this skill uses for music): `brew install elevenlabs/tap/elevenlabs`
-  (or `npm install -g @elevenlabs/cli`), then `elevenlabs auth login`. It opens ElevenLabs in the
-  browser; the person signs in once and the sign-in stays in the OS keychain. Nobody pastes a key.
-  Install the CLI yourself as part of the requested music work. An older CLI works; `brew upgrade elevenlabs` keeps it current
-  (1.4.0 on 2026-09-25).
-- An existing API key in the environment still works, but never send a new person to find or set one.
-  Use the browser sign-in above.
-- **ElevenLabs' plugin** for Claude Code (`/plugin marketplace add elevenlabs/plugin`, then
-  `/plugin install elevenlabs@elevenlabs`; in Codex `codex plugin marketplace add elevenlabs/plugin`)
-  brings their own skills and their hosted MCP (`https://api.elevenlabs.io/v1/mcp`, signed in on
-  ElevenLabs' page: speech, voices, transcription, agents). Their skills alone: `npx skills add
-  elevenlabs/skills`. It is optional here, and their MCP has no music tools: songs, stems and the
-  lyric check go through this skill's script, which keeps the budget, the receipts and the rights.
-  Their speech and sound-effect tools spend the same credits: tell the person the cost first, and the
-  Homie mod (Claude Code) and Homie's hooks (Codex) hold a generating tool (an `estimate_only` call is free).
-
-Prefer the CLI to a raw API call or a pasted key; never call ElevenLabs' API with `curl` for a song
-(the same request twice is twice the bill, and nothing records it).
-
-No ffmpeg: offer `brew install ffmpeg` (macOS) or the system package; the person approves.
-
-## 2. Say the plan and the rights, plainly, before anything is made
-
-From `check`, tell the person in two or three lines: the plan (tier), the credits left, and what
-the plan allows. ElevenLabs' terms: **the free plan has no commercial licence** (no ads, sales or
-monetised channels, and published copies credit "Eleven Music"); **paid plans include a
-commercial licence** (not for Beta features) under their Terms and Prohibited Use Policy. The plan
-**at render time** is what counts, and every render records it. Details:
-`references/RIGHTS.md`.
-
-## 3. Write the song
-
-Write `music/<slug>/spec.json` (shape and a full example: `references/COMPOSITION.md`): tempo,
-key, global styles and what to avoid, and sections in whole bars, each either instrumental or
-with its sung lines. Then:
-
-```sh
-node <music.mjs> plan <slug> --spec music/<slug>/spec.json
-```
-
-It builds the composition plan (every section a whole number of bars, so section starts are bar
-lines that loops and video cuts can land on), checks ElevenLabs' limits (each section 3 s to
-120 s, lines up to 200 characters) and quotes the cost.
-
-- **Anything sung goes through the plan's sections.** A prompt with lyrics beside it has come
-  back with nothing sung; `render --prompt` refuses words for that reason.
-- A theme or a song: the hook inside the first 10 seconds, one or two sung lines per bar at
-  most, simple words that sing clearly.
-- A game score: instrumental, a steady tempo, sections of 4, 8 or 16 bars that can each loop.
-- Describe sound, not artists: no "in the style of" a real singer or band, no real person's name
-  or voice (ElevenLabs refuses them, and they are not ours to use).
-
-## 4. Price it, get the go-ahead, render once
-
-```sh
-node <music.mjs> quote --seconds <s> [--vocals] [--budget <credits>]
+# Music for the scene
+
+Read the studio's style and the scene's emotional arc. Write a composition brief with
+instrumentation, tempo, duration, transitions, loop points and any exact lyrics.
+Use original language; preserve the owner's requested musical direction.
+
+Use the official ElevenLabs plugin's MCP creative workflow. Discover current tools first:
+`creative_get_flow_node_types` and `creative_get_model_guide` describe supported nodes
+and prompting; `creative_get_flow_run_status` follows a submitted flow. Only invoke
+music or sound generation if the connected server actually exposes that capability.
+The hosted OAuth server's public descriptions vary; never invent a music tool name or
+silently substitute speech. If unavailable, explain the missing capability and continue
+local composition/placement with a supplied file. The official provider plugin owns any
+alternative setup flow; Homie does not install a key-based local server or read CLI auth.
+
+Use the provider's estimate capability where exposed and record credits as quoted or
+measured. Read the current account plan's music terms before commercial use. Keep
+lyrics, composition brief and generation identifiers beside the song.
+Local `scripts/music.mjs` retains `plan`, `analyze`, `master`, `loop`, `add` and `publish`.
+Master from the downloaded audio, check clipping and loudness, audition the loop seam,
+and verify every sung line by listening. Transcription or stems, if needed, use discovered
+official MCP capabilities; neither is assumed available. Add metadata and credits to
+`music/manifest.json`, then wire the track to the scene or music page. Publish only when requested.
+
+## Official generation workflow
+
+The owner's AI uses the provider's official plugin/MCP in its own client. Homie never
+asks for, stores, reads or prints provider credentials. Read the current provider
+skill and discover its available tools and input schemas; host prefixes vary.
+Connection instructions and verified sources: [official integrations](../studio-setup/references/OFFICIAL-MEDIA.md).
+If tools are missing, connect that official plugin once in the client's browser flow.
+Do not fall back to a Homie client, key file, environment key or CLI generation wrapper.
+
+Before spending, state the model, count/duration, estimated cost and remaining approved
+budget. Use the owner's existing authorization; ask only if the spend is outside it.
+Record the request ID as soon as accepted. Poll that same request; never resubmit to
+retry a slow job. Unknown cost is unknown, never zero. Provider billing is authoritative;
+Homie's local receipt cannot enforce spending in another client.
+
+## Place and prove the result
+
+Download the completed tool's output using the AI client's file/download facilities.
+Keep temporary signed URLs out of committed records. Keep the original in the studio's
+art/job folder; put the optimized delivered asset beside its game/app, or in music/ or
+videos/ for a published work. Record a receipt with these fields:
+
+```json
+{
+  "provider": "fal",
+  "tool": "run_model",
+  "model": "exact endpoint returned by the provider",
+  "requestId": "actual request ID",
+  "prompt": "the actual prompt, including style constraints",
+  "styleRevision": "revision from the studio's style",
+  "rights": {"source": "provider/model terms URL", "checkedAt": "YYYY-MM-DD", "commercial": false, "note": "record the actual plan and permitted use"},
+  "cost": {"status": "unknown"}
+}
 ```
 
-About **27.5 credits per second** of `music_v2` (measured on a paid account; every render then
-records what it really cost, read off the account before and after). Tell the person the cost and
-ask for the go-ahead and a cap. Then:
+For ElevenLabs use its actual discovered tool and model, and its flow/session or request
+identifier. A measured cost uses `{"status":"actual","amount":1,"unit":"credits"}`;
+a quote uses `estimate`. Never claim commercial rights from the fact that generation
+succeeded. Read the provider and model terms for the account's plan; record attribution,
+reference-image permissions and any restrictions. Mark test fixtures `"fixture": true`.
 
-```sh
-node <music.mjs> budget <slug> --cap <credits they agreed to>
-node <music.mjs> render <slug> --dry-run      # free: the CLI validates the request and sends nothing
-node <music.mjs> render <slug> --yes          # the one paid render
-```
-
-- `render` refuses with no budget, refuses anything that would pass the cap, and asks again
-  without `--yes`. If the ask costs more than the cap, say so and offer what fits: the longest
-  length within it (`quote --budget` works it out), or a shorter section that loops honestly to
-  length (a loop, called a loop). Never raise a cap yourself.
-- ElevenLabs' balance can take a minute to show a render (measured: unchanged right after,
-  +445 a minute later). `render` waits up to 40 s for it; if it has not moved, the quote is
-  counted against the cap and the receipt is marked pending. `node <music.mjs> reconcile <slug>`
-  a minute later writes the real number. Never report a pending cost as zero.
-- Never re-send a failed render on your own: the same request twice is twice the bill. A render
-  that was sent and never answered leaves `work/render-<n>.pending`; the script refuses to send
-  again until the person has looked at their ElevenLabs history and agrees (`--again`).
-- Never buy credits, never change the plan, never turn on usage-based billing.
-
-## 5. Check that every line is sung
-
-```sh
-node <music.mjs> lyrics <slug>
-```
-
-ElevenLabs' own speech-to-text (Scribe) listens to the render, and every planned line is
-matched against what it heard, in order. A line passes at 75 % of its words (sung contractions
-drift: "I'll" comes back "I"). A **MISS** is a line the model did not sing, or sang as something
-else. Tell the person; the fix is a simpler line (the key word on a strong beat, fewer syllables)
-and another paid render, which needs their go-ahead. Update the lyrics shown on the page to what
-is actually sung.
-
-## 6. Master it
-
-```sh
-node <music.mjs> master <slug>                       # -14 LUFS integrated, -1 dBTP: the web and streaming
-node <music.mjs> master <slug> --lufs -18 --tp -1.5   # a bed under game sound effects
-node <music.mjs> analyze music/<slug>/<slug>.mp3      # duration, loudness, tempo, first beat
-```
-
-Two-pass loudness, then a limiter, measured after on both the WAV master (kept off the site) and
-the mp3 the page plays. Listen-worthy numbers go in your report, not adjectives.
-
-## 7. Loops and stems for games
-
-```sh
-node <music.mjs> loop <slug> --bars 8 --from-bar 4    # a seamless loop cut on bar lines, WAV + OGG
-node <music.mjs> stems <slug> --yes                   # paid, priced by measurement; ask first
-```
-
-The loop is cut at the song's measured bar lines, the tail crossfaded into the head, and checked:
-the jump at the wrap against the music's own sample steps, and the beat grid of the loop played
-three times. Never ship a loop as mp3 (encoders pad the ends with silence). Using loops in a
-game: `references/GAME-AUDIO.md`.
-
-## 8. The page
+Wire the delivered path into the scene or manifest, then run:
 
 ```sh
-node <music.mjs> add <slug> --title "<Title>" --blurb "<one line>" [--for-game <game id>] --publish
-node <music.mjs> publish <slug>
+npx --no-install homie-studio media import --file <downloaded-file> --receipt <receipt.json> --out games/<id>/assets/<name> --used-by games/<id>/view.ts
 ```
 
-`add` writes the manifest entry from what is in `music/<slug>/` (the mp3 the page plays, the
-master kept off the site, loops and stems offered for download, the lyrics, the plan and rights
-at render time, the credits line). `publish` rebuilds and redeploys the site and checks the
-page answers 200 and the audio answers a byte range. Without storage the site serves the song
-itself (a song is a few MB; the limit is 25 MiB a file). A studio that has storage (`storage add`)
-keeps its big media in its own R2: the deploy uploads the song (over 1 MiB, or left out of git),
-reads it back, checks it by SHA-256 and serves it from R2 at the same address. If the studio is
-not online yet, use the `publish` skill first. If `check` says the studio's `@homie-rocks/studio`
-predates song pages, say so and update it.
-
-## 9. Tell the person
-
-Four or five lines: the page link, the length, the credits it cost (measured) and what is left,
-the plan and whether it may be used commercially, the lyric check result, the loudness. Commit
-`music/` in the studio (the big audio files stay out of git by the studio's `.gitignore`; the
-manifest, spec, plan and receipts go in).
-
-## Never
-
-- Never print, paste or store a key; never ask for one in chat.
-- Never render without the person's go-ahead on the cost, and never past their cap.
-- Never claim rights the plan did not give, and never drop the "Eleven Music" credit on a
-  free-plan render.
-- Never imitate a real artist, voice or person.
-
-### Existing provider credentials
+This copies bytes, verifies a static reference, hashes the asset and records allowlisted
+provenance in `media/provenance.json`. Reimporting the same output is idempotent; it
+never generates or charges. Include each generation step's receipt for derived assets.
+Run the scene and look/listen: a file and static reference are not proof that it renders
+or plays. Report the placed path, usage evidence, rights and actual/estimated cost.
 
-The tools read `FAL_KEY` or `ELEVENLABS_API_KEY` first, then the plain single-line
-key in `~/.homie/keys/fal-key` or `~/.homie/keys/elevenlabs-key`. They also accept
-`~/.homie/workspace/fal-key` and `~/.homie/workspace/elevenlabs-key` from earlier
-installs. Checks name the source, never the key. Keep these files private (mode
-0600); never copy them into a studio. ElevenLabs also accepts its CLI browser
-sign-in and the existing Stripe Projects connection. Run the tool’s `check`
-before declaring a provider disconnected.
+The toolkit’s `lib/media-workflows.mjs` declares this skill’s verified tool references.
+Validate them against the host’s current tool inventory before execution; tool discovery
+is required for generation capabilities that have no stable documented name.

package/guides/music/references/COMPOSITION.md

@@ -1,7 +1,8 @@
 # Composition plans
 
-ElevenLabs Music (`music_v2`) takes either a short prompt or a **composition plan**: a list of
-chunks, each with its own length, text, and styles. Anything with words goes through a plan.
+Homie plans music as sections with their own length, lyrics and styles. Discover the official
+ElevenLabs MCP music capability and read its current schema before adapting this local plan
+to a generation request; the local plan is not a promise about a provider API.
 
 ## The spec `plan` reads
 
@@ -25,9 +26,9 @@ chunks, each with its own length, text, and styles. Anything with words goes thr
 What `plan` does with it:
 
 - **Whole bars.** A section of `bars` bars at `bpm` lasts `bars × beatsPerBar × 60 / bpm`
-  seconds; the boundaries are rounded to the millisecond so the total is exact. For `music_v2`
-  ElevenLabs holds every section to its length, so section starts are bar lines in the render.
-- **Limits.** Each section 3 s to 120 s (at 120 BPM a bar is 2 s, so the shortest section is 2
+  seconds; the boundaries are rounded to the millisecond so the planned total is exact. Measure
+  the generated audio before relying on these boundaries.
+- **Local planning limits.** Each section 3 s to 120 s (at 120 BPM a bar is 2 s, so the shortest section is 2
   bars); the whole song 3 s to 10 min; a line up to 200 characters.
 - **Styles.** The first chunk carries the global styles, the tempo and the key (they set the whole
   song); every later chunk repeats the tempo and adds its own. `avoid` becomes each chunk's
@@ -36,24 +37,18 @@ What `plan` does with it:
 - **Lines.** A sung section's text is `[Name]` and its lines. About one line a bar at pop tempos,
   two at most; more comes back rushed or skipped.
 
-## Traps, measured
-
-- **A prompt with `lyrics_text` has come back with nothing sung.** Words go in the plan's
-  sections. `render --prompt` refuses words for this reason.
-- **`output_format` is a query option, not a body field.** Put in the JSON body it is rejected
-  before anything is sent. The script passes `--output-format mp3_48000_192`.
-- **Short hooks drift.** In one render a three-word hook came back as a different three words;
-  making the key word unambiguous (and on a strong beat) fixed it in the next render. The lyric
-  check (Scribe) is what catches this, not listening once.
-- **Contractions drift.** "I'll wake up" came back "I wake up": the check passes lines at 75 % of
-  their words, and the page should show what is actually sung.
-- **The cost is about 27.5 credits per second** of `music_v2` on a paid plan (1,015 credits for
-  37 s and 5,204 for 189 s, measured). The quote uses this; the render records the real number off
-  the account.
-
-## What a render leaves
-
-`music/<slug>/work/render-<n>.mp3` (the audio as rendered), `render-<n>.json` (the plan
-ElevenLabs used, song metadata, and word timestamps: the model's own times for every sung
-word, which the `video` skill uses for lyric type), `music/<slug>/render.json` (the latest),
-`budget.json` (the cap and every call), and a line in `music/receipts.jsonl`.
+## Generation and review
+
+Read the discovered music tool's model guide, supported durations, lyric controls and output
+formats. Adapt the plan to that schema; do not send unsupported fields or assume a fixed model.
+Quote the requested duration through the official integration where available, and keep it
+within the approved budget. Record unknown cost explicitly when no quote is exposed.
+
+Short hooks and contractions can drift. Listen to every sung line; use an official transcription
+capability if available and compare the words with the plan. The page should show what is
+actually sung. Timestamps are optional provider output, not guaranteed by Homie.
+
+Keep the original audio under `music/<slug>/work/`, along with the local composition plan and
+any usable timing metadata. Place the final audio through `homie-studio media import` and keep
+its normalized receipt in `media/provenance.json`. Local analysis, mastering and loop commands
+operate on downloaded files; they do not generate music or inspect provider credentials.

package/guides/music/references/GAME-AUDIO.md

@@ -38,9 +38,9 @@ src.start();               // after the player's first tap or key: browsers need
 
 ## Stems
 
-`music.mjs stems <slug> --yes` asks ElevenLabs to split the master into stems (vocals, drums,
-bass, other). It is paid and its price is measured off the account, so it needs the person's
-go-ahead and fits inside the song's budget. Stems let a game drop the vocals under dialogue or
+The official ElevenLabs MCP, if its discovered tools expose stem separation, asks ElevenLabs to split the master into stems (vocals, drums,
+bass, other). Price it through the official integration and keep it inside the approved song budget.
+Record provider-reported actual cost, an estimate, or unknown explicitly. Stems let a game drop the vocals under dialogue or
 bring the drums in when the action starts.
 
 ## The page

package/guides/music/references/RIGHTS.md

@@ -16,10 +16,10 @@ Terms change: when a person is about to publish commercially, read the current p
 
 ## The plan at render time is what counts
 
-`render` reads the plan before it sends anything and writes it into the render's receipt and
-into the manifest entry (`rights.plan`, `rights.commercial`, `rights.attribution`). The song page
-shows it in plain words. A render made on the free plan stays under free-plan terms after an
-upgrade: to use it commercially, render it again on the paid plan.
+Use the official ElevenLabs MCP's available account and rights information and the current
+terms to record the plan and permitted use at generation time. If the MCP does not expose a
+fact, record it as unknown; do not infer a commercial licence from a successful generation.
+An account upgrade does not retroactively change the terms of earlier output.
 
 ## What never goes in
 
@@ -29,15 +29,12 @@ upgrade: to use it commercially, render it again on the paid plan.
 
 ## Receipts
 
-Every paid call leaves three records:
+Before a paid call, record the approved budget and the official tool's quote, if available.
+Keep the accepted request ID so polling or downloading an existing job does not submit it again.
+Save the output and a normalized receipt with `homie-studio media import`, which records the
+provider, tool, model, request ID, prompt, style revision, rights source and date, cost, file
+hash and consumer in `media/provenance.json`.
 
-- `music/<slug>/budget.json`: the cap the person agreed to, who agreed, and every call with its
-  cost;
-- `music/receipts.jsonl`: one line per call (provider, model, the song id, credits quoted and
-  measured, the plan and rights, the file it made);
-- optionally a team ledger: set `HOMIE_SPEND_LEDGER=<file>` (and `HOMIE_SPEND_ATTRIBUTION`) and
-  each call is also appended there.
-
-Credits are measured off the account (used before and after the call). Another job spending on
-the same account at the same moment shows up in that number; the receipt keeps the quote beside
-it.
+Distinguish provider-reported actual cost from an estimate; use unknown when neither is exposed.
+Do not infer job cost from changes in the account balance. Never save raw authentication data,
+signed download URLs or an unfiltered MCP response in the studio.