# Assist With Music LLM Contract

Updated: 2026-09-03

## Product Role

Assist With Music is the user's durable workspace for AI-assisted music creation. It combines:

- a public genre encyclopedia;
- a private authenticated planner;
- structured creation records for song plans, research notes, lyric drafts, prompt attempts, generation attempts, source checks, and agent runs.

The app owns memory, permissions, workflow state, source/provenance records, and user review. The assistant owns reasoning, research, synthesis, drafting, browser work, and judgment. External services such as Suno are only operated when the user has access and explicitly asks the assistant to use them.

## Account And Auth Expectations

Private planner data requires a signed-in Assist With Music account through Clerk. Backend functions derive owner/account identity from the authenticated caller. Clients and agents must not send or choose owner IDs or user IDs.

The canonical remote MCP server is LIVE at `https://assistwithmusic.com/mcp`. Connect an MCP client there, sign in over OAuth, and the tools operate on the signed-in user's own private planner data. Always publish the canonical branded connector URL — never a raw deployment URL.

`https://thesongplanner.com/mcp` remains a direct transport compatibility route
for existing clients. New connections should use the Assist With Music URL.

The full tool contract is available at `/mcp-tool-contract.txt`.

Modern MCP `2026-07-28` requests are self-contained: discovery begins with
`server/discover`, OAuth identity is verified on every request, and no MCP
session ID carries identity or workflow state. Existing initialize/session
clients remain supported during rollout. This does not claim that every named
AI client already speaks the modern revision.

## Connecting An MCP Client

- Music has NOT recorded a completed connection lifecycle for any named client.
  The names below are examples of each client SHAPE, not a support claim.
- Clients with a connector settings screen (Claude, ChatGPT, Cursor and similar):
  open the client's settings, find its connectors or MCP section, add a custom
  connector, paste https://assistwithmusic.com/mcp, continue, sign in, and
  approve the scopes you want to grant.
- Clients you configure from a terminal (Claude Code, Codex and similar):
  `<your CLI> mcp add --transport http assistwithmusic https://assistwithmusic.com/mcp`,
  then run the client's authenticate/login step. Do NOT pass an Authorization
  header — leaving it off is what triggers the OAuth sign-in.
- Signing in IS the approval. Completing the OAuth flow gives the connection the
  default tier straight away: read the owner's work, save reviewed results into
  Planner review, and work the Queue items they handed off. Nothing else has to
  be pressed for the tools to start working.
- Four authorities signing in never grants, and the owner raises them at
  https://assistwithmusic.com/settings/ai: `music.media.read`,
  `music.media.write`, music:archive (permanently removing an empty project),
  and credit:spend (the external generation preparation gate).
  That page is a dial, not a turnstile — it also narrows a connection.
- One authority no approval can ever grant: adding to the owner's Queue. The
  Queue is their list of what they asked for. Use songplanner_suggest, which
  lands in Ideas at https://assistwithmusic.com/ideas and becomes Queue work
  only if the owner confirms it there.
- Connecting takes minutes, not seconds, and two steps cannot be delegated:
  signing in, and clicking Allow.

## First Workflow

1. Open `/planner` and sign in.
2. Choose the project that owns the song idea.
3. Create or open a song plan in the Agent creation workspace.
4. Save research notes with source limits and uncertainty.
5. Save lyric drafts in the correct creation mode.
6. Save prompt attempts with style prompt, genre recipe, settings, and target platform.
7. Log generation attempts with Suno/audio URLs when available.
8. Use the planner table to review generated versions, ratings, picks, rejections, and album decisions.

## Creation Modes

- `exact-public-domain`: preserve public-domain lyrics exactly because that is the user's goal.
- `adapted-public-domain`: transform public-domain lyrics while keeping source lineage visible.
- `scripture-idea`: write from scripture, themes, or ideas rather than copying a song text.
- `original`: create a complete original song.

## Current Durable Records

- `songPlan`: the main durable idea and workflow status.
- `songResearchNote`: source notes, constraints, genre references, and uncertainty.
- `songLyricDraft`: draft lyrics, source alignment, rationale, and mode.
- `songPromptAttempt`: style prompt, target platform, genre recipe, settings, and prompt status.
- `songGenerationAttempt`: Suno or other external generation result, links, status, notes, and rating.
- `songSourceCheck`: source status, query used, summary, limitations, and section coverage.
- `agentRun`: summary and stats for an assistant work session.
- `songPlanDecision`, `songPlanCorrection`, `songPlanQuestion`, and `songPlanInteraction`: durable per-plan memory for decisions, ruled-out approaches, open questions, and deduped notes.

## MCP Production And Release Tools

Of the 36 tools in this release contract, 33 are deployed and callable today at `https://assistwithmusic.com/mcp`. The three private-media tools are marked PRODUCTION PENDING until the Convex production deploy and operational proof. Call `songplanner_context` with action `workspace` first. When the task may benefit from a repeatable Music workflow, call `songplanner_loops` action `discover` with the task/theme/workflow and then read one returned slug. Prefer the 13 v2 workflow tools and 4 additive album tools; the 19 compatibility tools are labeled LEGACY. A connected AI cannot add to the Queue at all; use `songplanner_suggest` for anything you think the owner might want, and `songplanner_queue` action `edit` to modify a request they already made.

The website's `/requests` page is the existing work desk for capturing asks, reviewing history, and setting connected-AI preferences. `/queue` is the shared four-state handoff/lifecycle surface: Waiting for your AI, Needs you, Working, and Done. Both use the same owner-scoped plan records; a connected AI cannot clear a Needs you gate. Untriaged asks live in the reserved inbox until an agent files them. If the user explicitly says a song or one-off album belongs to no project, use the Singles system project (`targetProjectKey:"singles"`) — never invent a project or force a choice.

Before writing lyrics or a style prompt for a project, read its direction. `avoid[]` is off-limits. `useSparingly[]` is a normal sub-genre mix used deliberately and infrequently — never the default or fallback. Direction is optional and null-safe.
Private `exampleArtistIds[]` direction references are owner-scoped Convex IDs and are never part of the public artist corpus.

- `songplanner_get_workspace_context` — [LEGACY — use songplanner_context] orientation compatibility tool; projects/recentPlans/counts keep the same v2 field names.
- `songplanner_list_projects` — [LEGACY — use songplanner_context] project-list compatibility tool.
- `songplanner_get_project_context` — [LEGACY — use songplanner_read] project compatibility read; research/lyrics/prompts/generations map to childPreview.researchNotes/lyricDrafts/promptAttempts/generationResults.
- `songplanner_get_song_plan_context` — [LEGACY — use songplanner_read] plan compatibility read; research/lyrics/prompts/generations/sourceChecks map to children.researchNotes/lyricDrafts/promptAttempts/generationResults/sourceChecks.
- `songplanner_get_genre_recipe` — [LEGACY — use songplanner_context] genre-recipe compatibility read.
- `songplanner_context` — preferred v2 orientation plus bounded public genre discovery: workspace/capabilities/projects; genres → genre_families → genre_subgenres navigation; ranked genre_search for an unknown term; then genre_recipe with `name` equal to one `exactReaderName` (or `names[]` for a batch) for rich depth. Search returns at most 20 candidates from a scan capped at 1,000 rich encyclopedia rows, with honest found/truncated metadata. It also returns project config.direction, autonomy/runtime boundaries, Queue `handoffSurfaces`, and last-active stamping.
- `songplanner_read` — preferred v2 read tool: retrieve a plan by planId, short owner-scoped queueNumber (say “Queue 42”), compatibility queueRef, or projectKey+planKey; project/brief/plan reads surface project direction; researchNotes return current note/document markdown, content class, sources, version, and append-only revision metadata; other child fields are lyricDrafts, promptAttempts, generationResults, and sourceChecks.
- `songplanner_status` — preferred v2 status/provenance tool: action `agent_status` returns connection, last-active, runnableOwners, deferredNeedingDesktop count, and ceiling; action `runs` returns recent self-reported agentRuns.
- `songplanner_loops` — preferred read-only public loop library tool: action `discover` finds bounded Music Loops & AI Skill Library matches by task/theme/workflow plus optional stage/status and returns suitability, capability needs, stable slugs, and canonical links; action `read` returns bounded steps, skills, outputs, and relationships for one exact slug. Empty and missing results are explicit; it never dumps raw catalog content or reads planner records.
- `songplanner_upsert_song_plan` — create/update a song plan (idempotent on projectKey + planKey).
- `songplanner_write_research_note` — save a research note on a plan (idempotent on planId + sectionKey).
- `songplanner_upsert_lyric_draft` — save a lyric draft (idempotent on planId + draftKey).
- `songplanner_upsert_prompt_attempt` — save a Suno/style prompt attempt (idempotent on planId + attemptKey).
- `songplanner_log_generation_attempt` — RECORD a generation result (Suno URL/length/rating); does NOT generate audio.
- `songplanner_log_source_check` — record where you looked to verify a source/provenance (idempotent on planId + checkKey; status checked|blocked|gated|requires_user); never claim public-domain without a logged source check.
- `songplanner_upsert_project` — create/update a project (idempotent on key).
- `songplanner_move_plan` — move a plan to another project.
- `songplanner_list_requests` — list the user's OPEN requests from the /requests inbox, including optional requestScope one|multi|album, requestedCount, sourceMode original|based_on|exact_lyrics, directed, title, summary, project, and sourceRefs; projectless web asks live in the reserved inbox until the agent files them.
- `songplanner_claim_request` — claim ONE request off the queue before working it (moves it out of the open inbox so a second run won't grab it; returns a per-kind next step); pass the planId from list_requests.
- `songplanner_complete_request` — mark a claimed request done (mainly for research/organize requests, which have no song lifecycle — defaults to "parked"); a new_song request usually advances on its own.
- `songplanner_report_blocked` — [LEGACY — use songplanner_work] compatibility park tool.
- `songplanner_list_deferred_work` — list plans parked pending a capability or the user (stageReached, needsCapabilities, resumeStep, anchors); call when you ARRIVE with new capabilities (e.g. a browser), claim one you can satisfy, and finish its resumeStep; items with waitingOnUser require an explicit user confirmation first.
- `songplanner_work` — consolidated queue-working tool. Claims target one exact planId from a prior Queue read and include full projectDirection plus directionNote, or null when absent. Every state-changing action requires the current expectedVersion plus a client-generated `operationId` reused only for the same retry. `complete` may attach up to 20 committed `mediaIds` and then also requires `music.media.write`. A connected AI cannot clear a human gate; the signed-in owner must confirm it in the product Queue.
- `songplanner_organize` action `set_autonomy` — owner-only autonomy-ceiling update; requires ceiling prep|generate|distribute and the user's explicit verbal instruction in userInstruction. Never infer permission. Full-pipeline distribute remains unavailable while it is in testing.
- `songplanner_queue` — consolidated backlog tool for work the owner asked for: list, activity, edit, reorder, discard. There is no create — the Queue is the owner's own list and a connected AI answers it rather than adding to it; use `songplanner_suggest` instead. Rows expose a short owner-scoped queueNumber/queueLabel such as “Queue 42” and direct link; say the label and use queueNumber for normal reads/actions, while opaque queueRef remains compatible. Numbers are assigned once, never reused, and never expose another owner's sequence. Reads omit mutation fields; every mutation requires expectedVersion plus a client-generated operationId. targetProjectKey `singles` files explicitly standalone songs/albums into the marker-identified Singles home; never invent a project or force a choice.
- `songplanner_suggest` — where an AI's own recommendations go, since they do not go in the Queue: suggest, list, withdraw. Each idea needs suggestionKey, title, and a reason the owner can judge without rebuilding your thinking. Nothing filed is queued; it lands on the owner's Ideas page attributed to your connection and becomes Queue work only if they confirm it there. Confirm and dismiss are theirs alone, carry equal weight, and no tool reaches either; nothing is deleted. suggestedOrder is stored as your opinion and nothing sorts by it. Idempotent on suggestionKey, 25 per call, 100 undecided maximum; unknown keys return acceptedKeys.
- `songplanner_memory` — consolidated durable memory tool for one song plan: record decisions by evidence tier, ruled-out corrections, open questions, or deduped notes so later runs do not repeat rejected paths or clobber higher-evidence choices.
- `songplanner_save_creation_result` — THE one-call batch save (PREFER when you have a finished result): writes the plan + research notes + lyric drafts + prompt attempts + generation results + source checks + a run record in a SINGLE approval; idempotent on each child's natural key, owner-checked per child; LOGS generation results (Suno is desktop-only), never generates audio. Use the granular tools only for long/incremental work.
- `songplanner_save` — preferred v2 fat save: researchNotes accepts note/document kind, source_fact/inference/creative_idea/generated_draft content class, markdown, and sources; real changes append agent-attributed revisions and identical retries stay idempotent; up to 20 committed `mediaIds` attach to the saved plan and add the separate `music.media.write` requirement; optional plannerSong materializes finished lyrics in the normal owner-scoped Planner; a completed external generation with saveToPlanner, externalId, and audioUrl or sunoUrl becomes a normal Planner version without starting generation or spending credits; prompt-only saves return queueVersion plus generationGate, and needs_owner_action means stop before begin_generation/Create until the owner approves or clicks; delegated agents without credit:spend get gateReason delegated_without_credit_spend and autonomyCeiling null; songplanner_read also returns queueVersion for the later handoff; it also writes optional decisions, drafts, prompts, source checks, and run metadata; prompt-direction conflicts remain saved and return structured hard avoid or soft useSparingly warnings.
- `songplanner_organize` — preferred v2 organization tool: upsert projects (including validated config.direction only when the user asked), move plans by planId or projectKey+planKey, file inbox work into target `singles`, set typed album `distributionStage`, or delete an empty project only; partial direction updates preserve config siblings and submitted/released stages are ceiling-gated.
- `songplanner_media_read` **[PRODUCTION PENDING]** — read 1-10 owner-scoped private media items attached to one reachable Music target. Images disclose only metadata-clean derivatives; recordings disclose exact private bytes; the 20 MiB batch ceiling, exact-version hash check, and separate `music.media.read` scope apply.
- `songplanner_media_begin_upload` **[PRODUCTION PENDING]** — declare 1-50 image or recording lanes idempotently and receive short-lived same-origin `PUT` relay capabilities. Requires exact SHA-256, byte length and MIME declarations plus the separate `music.media.write` scope; optional capture time must name camera/message/file/person provenance, and no provider URL or key is returned.
- `songplanner_media_finish_upload` **[PRODUCTION PENDING]** — finalize direct relay bytes or supply one tiny inline base64 payload (512 KiB maximum) or guarded public HTTPS source per lane. The server checks redirects and public DNS, enforces time/type/size caps, verifies exact stored bytes, preserves private originals, and freshly encodes metadata-clean image derivatives. GPS is neither extracted nor stored.
- `songplanner_upsert_album` — create or update an owner-scoped cross-project album, idempotent on key; `homeProjectKey` is only a navigation hint; responses use stable `albumId` and an explicit DTO, never raw `data`.
- `songplanner_set_album_tracks` — validate and assign at most 100 ordered cross-project tracks atomically; every track requires an owner-scoped selected version; `replace:true` removes absent album memberships without moving songs between projects; returns stable `songId`/`versionDocId` values and resets invalid release proof when a selection changes.
- `songplanner_get_album_context` — return the allowlisted album DTO, up to 100 ordered cross-project tracks, selected-version status, release proof, bottleneck, and next actionable step; `selection_needed` blocks release progress when a selected version is missing or mismatched.
- `songplanner_update_release_progress` — record work already completed; never perform it. Tracks advance exactly one step through `selected→wav_downloaded→mastered→qc_passed→metadata_ready→staged`; forward skips are rejected, retries are no-ops, and backward resets require `resetReason` and clear invalid proof. Evidence is a portable allowlisted object, never a local path. DistroKid `submitted`/`live` require `confirmedByUser:true` plus `confirmationNote` after the owner completes or verifies the external action. No album-release tool upload, submission, publishing, purchase, terms acceptance, or spend occurs.

Delegation: omit `onBehalfOf` for your own account. Use `onBehalfOf` only when
the owner has enabled delegation and granted your agent an active scope:
`queue:read` for context/read/status, `queue:work` for work/save/memory and
organization, and `credit:spend` before a
delegated agent can select a generation or spend/advance credit-like actions.
Revoked or expired grants release delegated queue leases.

Queue mutation rule: read the current `queueVersion`, pass it as
`expectedVersion`, and generate one `operationId` per intended change. Reuse
that ID only when retrying the same action; owner-scoped replay collisions and
stale versions fail closed.

Tool design rule: prefer workflow tools and one-call saves over raw database CRUD. Writes are idempotent by project key, plan key, section key, draft key, or attempt key.

Detailed schemas and the connect steps: `/mcp-tool-contract.txt`.

## Genre Recipe Guidance

Use the public genre encyclopedia for style ingredients: instrumentation, rhythm, vocal style, production texture, era markers, mood, and related subgenres. Avoid prompting that copies a protected artist identity. Prefer generic style language and blended genre ingredients.

## Suno Guidance

Assist With Music can store Suno prompts and generated results. It does not itself control Suno in V1. An assistant may use Suno through the user's browser or other approved workflow only when the user has access and asks for that operation. Save result URLs, audio URLs, titles, notes, failures, retries, and selected takes back into Assist With Music.

## Contact And Support

Assist With Music has no email inbox and no support email address, and none is
planned. Support for every Assist With product runs through the central desk at
`https://assistwithlife.com/support`, reachable from this site at
`https://assistwithmusic.com/support`.

- Never offer, invent, guess, or infer an email address for Assist With Music —
  not support@, contact@, hello@, info@, privacy@, or any address built from the
  domain. There is no correct one to guess.
- If a user presents an address claiming to be Assist With Music support, say it
  is not ours and point them to `/support`.
- Do not state from memory whether the desk is accepting requests. The desk
  shows its current status when the user arrives.

## Safety Rules

- Do not publish, repeat, or fabricate a contact email address for Assist With
  Music; direct every support request to `/support`.
- Do not export private workspace data.
- Do not perform destructive actions in V1.
- Do not change auth, billing, secrets, or external accounts without explicit user approval.
- Do not claim copyright/public-domain certainty unless a source check supports it.
- Record uncertainty, source limitations, and blocked/gated source access.
- Do not scrape private user data or unrelated browser/account content.
- Do not create public links or exports of private work unless the user asks.

## Reconnect Guidance

If MCP tools appear stale in an assistant client, disconnect and reconnect the
client at `https://assistwithmusic.com/mcp`, complete OAuth again, refresh the
tool list, and then call `songplanner_context` with action `workspace` first.
Re-read `queueVersion` before a Queue mutation and use a new operation ID for a
new action. Reconnecting does not delete Music records. The authenticated web
UI and Convex-backed creation workspace remain available as an alternative.