# Song Planner agent guide

Updated: 2026-06-19

Song Planner is the user's durable music-creation workspace. It stores projects, song plans, source/research notes, lyric drafts, prompt attempts, generation attempts, source checks, version review state, and genre context.

What Song Planner is:
- a private planner for AI-assisted music creation;
- a public genre encyclopedia that can inform style and prompt recipes;
- the durable memory layer where assistants should save structured creation work.

What Song Planner is not:
- it is not a replacement for an assistant's reasoning, web research, or browser tools;
- it is not a copyright authority;
- it does not operate Suno or other external accounts by itself in V1.

Account and auth:
- private planner data requires a signed-in Song Planner account through Clerk;
- clients must not choose owner/user IDs;
- backend functions derive ownership from the authenticated caller;
- remote MCP/OAuth is planned, but exact client setup is not verified or published yet.

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, lyric drafts, prompt attempts, and generation attempts as structured records.
5. Use the existing planner table to review generated versions and album picks.

Creation modes:
- exact-public-domain: preserve public-domain lyrics exactly when that is the goal.
- adapted-public-domain: adapt or transform public-domain lyrics.
- scripture-idea: create from scripture, themes, or ideas.
- original: create a complete original song.

Planned MCP families:
- songplanner_get_workspace_context
- songplanner_list_projects
- songplanner_get_project_context
- songplanner_get_song_plan_context
- songplanner_upsert_song_plan
- songplanner_write_research_note
- songplanner_upsert_lyric_draft
- songplanner_upsert_prompt_attempt
- songplanner_log_generation_attempt
- songplanner_log_source_check
- songplanner_save_creation_result
- songplanner_get_genre_recipe

Safety rules:
- do not export private workspace data;
- do not perform destructive actions in V1;
- do not claim a song or source is public domain unless the source check supports it;
- do not automate external accounts unless the user has access and explicitly asks;
- record uncertainty and limitations in source checks or research notes.

More:
- concise LLM index: /llms.txt
- full LLM contract: /llms-full.txt
- planned MCP tool contract draft: /mcp-tool-contract.txt
- human-readable guide: /ai