Setup Artist

Setup Artist

Scaffold a complete artist workspace so agents can start working immediately.

Prerequisites

• The sandbox has already been set up (see setup-sandbox skill)
• An artist folder exists at orgs/{org}/artists/{artist-slug}/ with a RECOUP.md marker file
• The RECOUP.md file contains the artist's name, slug, and Recoup ID (created by setup-sandbox)

Folder Structure

{artist-slug}/
├── RECOUP.md
├── README.md
├── .env.example
├── .env
├── context/
│   ├── artist.md
│   ├── audience.md
│   ├── era.json
│   ├── tasks.md
│   └── images/
│       └── README.md
├── memory/
│   ├── README.md
│   └── MEMORY.md
├── songs/
│   └── README.md
├── releases/
│   └── README.md
├── content/
│   ├── README.md
│   ├── images/
│   └── videos/
├── config/
│   ├── README.md
│   └── SERVICES.md
├── library/
│   └── README.md
└── apps/
    └── README.md

Steps

Step 1: Read RECOUP.md and create the directory structure

1. Navigate to the artist folder and read RECOUP.md to get the artist's name, slug, and ID:

cd orgs/{org}/artists/{artist-slug}
cat RECOUP.md

2. Create the directory structure:

mkdir -p {context/images,memory,songs,releases,content/images,content/videos,config,library,apps}

Step 2: Update RECOUP.md

Update the status field from not-setup to active and replace the body with a brief description:

---
artistName: {Artist Name}
artistSlug: {artist-slug}
artistId: {uuid-from-recoupable}
status: active
---

# {Artist Name}

Connects this workspace to the Recoupable platform. See `README.md` for the full directory guide and setup checklist.

Step 3: Create context files

Create each file from the templates in references/context-files.md. The essential files:

Step 4: Create memory system

Create two files:

• memory/README.md — Full instructions for agents on how to use the memory system, including the scope concept. See references/memory-system.md.
• memory/MEMORY.md — Nearly empty starting point with frontmatter and guidelines comment (including scope rules).

The memory system uses three scopes to prevent knowledge bloat:

• permanent — true regardless of era (goes in MEMORY.md)
• era — true for the current release cycle (goes in MEMORY.md, tagged with era)
• session — about a specific piece of content or task (goes in log/ only, never MEMORY.md)

Agents should ask the user about scope before saving feedback to long-term memory.

Step 5: Create services and environment files

Services are tracked in config/, not pre-filled at setup. Create:

Do NOT pre-fill service entries. Services are added when the agent has real information — a handle, an API key, a confirmed account. The old approach of creating a massive JSON file with every possible service set to not-setup creates noise, not value.

Step 6: Create README files for remaining directories

Each directory needs a README.md explaining its purpose. See references/directory-readmes.md for templates.

Step 7: Create root README

Create README.md at the artist root with:

• Artist name as heading
• Directory structure table
• Context files table
• Config & services table
• Setup checklist

See references/root-readme.md for the template.

Step 8: Fill in what you can

If you have information about the artist (from the user, from research, or from the Recoup platform):

1. Fill context/artist.md with as much identity/brand info as possible 2. Fill context/audience.md with audience insights 3. Set context/era.json with the current release phase

Don't fabricate information. Leave placeholders for anything you don't know.

Step 9: Commit

git add -A
git commit -m "setup: create {artist-name} artist workspace"
git push origin main

Naming Conventions

• Directories and slugs: lowercase-kebab-case (e.g. gatsby-grace, a-thing-called-love)
• Audio files: Match the folder slug (e.g. songs/a-thing-called-love/a-thing-called-love.mp3)
• Context files: Use the names exactly as specified — agents and shared tools expect them

Principles

• Start lean. Only create what's needed. Agents and pipelines will create additional files (like content/videos/shortform/) as they run.
• Placeholders over empty. Use {placeholder} syntax for unknown values — it's better than blank fields.
• Don't pre-fill what you don't know. A file full of not-setup and null isn't a placeholder — it's clutter. Services, accounts, and configs should be added when they're real.
• README everything. Every directory gets a README so agents know what belongs there.
• Don't duplicate. Songs live in songs/, releases reference them by slug. Content goes in content/, not copied elsewhere.
• Scope your memories. Not all knowledge lasts forever. Tag era-specific memories, keep session feedback in logs, and ask before promoting to long-term memory.

Recoup Setup Artist Skill

An LLM skill for scaffolding a complete artist workspace inside a sandbox environment.

What It Does

• Creates the full directory structure for an artist workspace
• Populates context files (identity, audience, era)
• Sets up the memory system with scope-aware instructions (MEMORY.md + README)
• Creates a lean services guide (no pre-filled JSON) and environment files
• Creates README files for every directory so agents know what goes where
• Fills in artist data when available, uses placeholders when not

Prerequisites

Run the setup-sandbox skill first to create the org/artist folder structure.

Usage

"Set up the workspace for [Artist Name]"

"Create artist directory for [Artist Name]"

"Initialize [Artist Name]'s artist workspace"

Files

Context File Templates

These are the templates for every file in the context/ directory. Copy each one and replace {placeholders} with real data.

---

context/artist.md

---
name: Artist
description: "The complete profile for {Artist Name} — who they are and how they present. Read this first before doing anything for this artist."
---

{One-sentence description of the artist — age, background, genre, instrument/role.}

## Personality

{Core personality traits. Who are they when the camera is off? What makes them tick?}

## Topics

{What the artist thinks about, writes about, and keeps coming back to. Recurring themes and obsessions.}

## Genre

{Primary genre and sub-genres.}

## Comparables

{2-4 comparable artists that help triangulate the sound and sensibility.}

---

## Positioning

{One paragraph describing the artist's unique position — what makes them different, where they sit in the landscape, and why someone should care.}

**One-liner:** {A single sentence pitch for the artist.}

**Archetype:** {The artist's brand archetype in 2-4 words.}

## Aesthetic

{One sentence that captures the entire visual world. This is the north star — every creative decision should feel like it belongs in this sentence.}

## Mood

{What does the content FEEL like? Describe the lighting, texture, energy, and atmosphere. Think about what someone would feel looking at the content before they even read or listen.}

## Colors & Typography

- **Primary:** {dominant palette}
- **Secondary:** {supporting tones}
- **Accent:** {highlights or pops of color}
- **Fonts:** {primary typeface, secondary/accent typeface if any}

## Settings

{Where does the visual world live? Describe the environments and spaces that feel right for this artist. These directly inform image generation and video backgrounds.}

## Fashion & Appearance

{What does the artist look like and wear? Clothing, hair, makeup, accessories. Be specific enough for consistent character depiction across generated content.}

## Signature Elements

{Recurring visual props, motifs, or symbols that make this artist's content instantly recognizable.}

## Visual References

{Specific music videos, photoshoots, films, or cultural touchpoints that capture the right feel. Link or describe them clearly enough for another agent to look them up.}

## Voice

{How the artist speaks and writes. Describe the feel — not just adjectives. This calibrates all text output: captions, replies, bios, emails.}

## Tone

{Rules for how text content should sound. Capitalization, punctuation style, energy level, what language to use and what to avoid.}

---

context/audience.md

---
name: Audience
description: The emotional relationship between {Artist Name} and the people who listen. Use this to write content that feels like it was made FOR them — not marketed AT them. Every section here should change how you write captions, pick visuals, and engage.
---

## Why They Listen

{What role does this artist play in their life? Not "they like the music" — WHY do they keep coming back? What need does this artist fill?}

## What They Relate To

{The specific feelings, experiences, and struggles that make this audience connect. Be concrete — not "they're emotional" but the actual situations and moments.}

## How They Talk

{The actual language, tone, and slang this audience uses. This calibrates the voice for captions and replies. Describe how they text, what phrases they lean on, and what register feels native to them.}

## What Makes Them Share

{The specific triggers that make this audience save, repost, duet, or screenshot. Be actionable — what should the content DO to earn a share?}

## What Loses Them

{Specific turn-offs for THIS audience — the things that make them scroll past, cringe, or unfollow. These are hard constraints.}

---

context/era.json

{
  "_comment": "What the artist is focused on RIGHT NOW. Agents use this to pick songs, tailor content, and adjust strategy based on career stage and rollout phase.",
  "artistStage": "{launch | growing | established}",
  "currentRelease": "{release-slug}",
  "currentSongs": ["{song-slug}"],
  "releasePhase": "{pre-release | tease-and-announce | release-week | sustain}",
  "releaseDate": "{YYYY-MM-DD}"
}

Fields:

• artistStage — career stage: launch (new/unknown), growing (building momentum), established (known audience)
• currentRelease — slug of the active release (matches folder name in releases/)
• currentSongs — array of song slugs currently in rotation
• releasePhase — where we are in the rollout cycle
• releaseDate — target or actual release date

---

context/tasks.md

---
name: Tasks
description: What needs to be done for {Artist Name}. Add tasks as they come up, check them off as you go. Use era.json to know what phase the project is in. Organize however makes sense.
---

Start empty. The user or agent adds tasks as they come up.

---

context/images/README.md

---
name: Context Images
description: Visual references that define how the artist looks. Used for consistent character depiction and world-building when creating AI-generated assets.
---

# Context Images

Store visual references here that tools and agents use to maintain consistency across generated content.

## Key file

- `face-guide.png` — the primary face reference used by the content pipeline for image generation. Create this from artist photos or AI-generated references.

Add other reference images as needed — expressions, poses, style references, etc.

Directory README Templates

Each directory in the artist workspace needs a README. Here are the templates.

---

songs/README.md

---
name: Songs
description: Song catalog. One folder per song with audio, lyrics, and metadata. The content pipeline reads from here to select clips, generate captions, and create content.
---

# Songs

Each song gets its own folder: `songs/{song-slug}/`

Use lowercase-kebab-case for the slug (e.g. `a-thing-called-love`). Rename audio files to match the folder slug — if the folder is `a-thing-called-love/`, the audio should be `a-thing-called-love.mp3`.

## What to add

- `{song-slug}.mp3` — song audio (required, renamed to match the folder)
- `metadata.json` — song metadata. Important fields: title, slug, ISRC, duration, writers, producers, splits/rights, mood, tempo, key, explicit flag
- `lyrics.md` — human-readable lyrics with section markers (`[Verse 1]`, `[Chorus]`, etc.)

## Auto-generated by pipeline

These files are created by the content-creation pipeline — don't write them by hand:

- `lyrics.json` — word-level timestamped lyrics (from transcription)
- `clips/analysis.json` — best moments for short-form content (from song analysis)

---

releases/README.md

---
name: Releases
description: Release catalog. One folder per release with RELEASE.md and cover art. Referenced by era.json to indicate the current active release.
---

# Releases

Each release gets its own folder: `releases/{release-slug}/`

Use lowercase-kebab-case for the slug (e.g. `debut-ep`, `first-single`).

## What to add

- `RELEASE.md` — the single source of truth. Covers everything: metadata, narrative, DSP pitches, marketing strategy, press materials, budgets, performance tracking. Managed by the release-management skill.
- Cover art — album/single artwork
- Any other release-specific assets (press photos, etc.)

## Connecting to songs

Songs live in `songs/{slug}/` — reference them by slug in RELEASE.md. Don't duplicate audio files here.

---

content/README.md

---
name: Content
description: Generated content output — images and videos created by the content pipeline. Subdirectories like videos/shortform/ are created automatically as content is produced.
---

# Content

All generated content lives here — images and videos created by the content pipeline and other tools.

## Structure

content/
  images/          # Generated images (cover art variations, social graphics, etc.)
  videos/          # Generated videos — subdirectories by type
    shortform/     # Short-form content (TikTok, Reels, Shorts)

Subdirectories are created automatically by the pipeline as content is produced. Don't create them ahead of time.

## Not Here

- **Source images** (face guides, visual references) → `context/images/`
- **Song audio** → `songs/`
- **Cover art masters** → `releases/{release-slug}/`

---

config/README.md

---
name: Config
description: Per-artist configuration, services, and shared tool settings. Services are tracked here (not in context/). Each shared app stores its config under config/{app-name}/.
---

# Config

Per-artist configuration, services, and state for **shared tools** that operate on this artist.

## Services

See `SERVICES.md` for how to connect and track services. Individual service entries live in `config/services/` as JSON files — created when a service is actually connected (not before).

Credentials go in `.env` at the artist root — never in config files.

## Shared App Convention

Each shared app gets its own subdirectory named after the app:

config/
  {app-name}/
    config.json        # App settings for this artist
    ...                # Any other files the app needs (state, history, cache)

The app creates its subdirectory and files when first configured for this artist.

## Known Apps

| App | Directory | What it stores |
|-----|-----------|---------------|
| Content Creation | `content-creation/` | Pipeline config (models, resolution), step state, rotation history |
| Content Poster | `content-poster/` | Posting schedule, platform IDs, post history |

## Not Here

- **Artist identity** → `context/` (identity, brand, audience, etc.)
- **Artist-owned apps** → `apps/` (website, fan portal, etc.)
- **Content output** → `content/` (videos, images, etc.)

---

library/README.md

---
name: Library
description: Extended reference material — research, reports, strategy docs. Scoped by era so agents prioritize current-era docs. This is NOT for artist identity (that's context/) or learned knowledge (that's memory/).
---

# Library

Extended context for the artist — notes, research, reports, strategy docs, data, or anything that doesn't fit in `context/` but is useful to reference. Add files as the project grows.

## Format

All library documents use YAML frontmatter with an `era` field so documents can be scoped to a specific campaign or time period and easily archived:

---
name: Document Name
description: What this covers and when to reference it.
era: {release-slug or time period}
---

The `era` field ties the document to a release or campaign. This prevents outdated strategy from bleeding into current work. When a new era begins, old docs stay for reference but agents should prioritize docs matching the current `era.json`.

---

apps/README.md

---
name: Apps
description: Artist-specific applications — things built just for this artist (e.g. website, fan portal). Most artists start with this directory empty.
---

# Apps

## Examples

| App | What it is |
|-----|-----------|
| `website/` | A personal artist website (Next.js, etc.) |
| `fan-portal/` | A custom fan experience or interactive page |
| `merch-store/` | A custom storefront (if not using Shopify, etc.) |

## Important

Apps here should **pull context from the artist directory** rather than duplicating it. Use the files in `context/`, `songs/`, and `releases/` as the source of truth — don't hardcode artist info inside the app. This keeps everything in sync as the artist evolves.

## When to Create

Only create an app here when the artist needs something custom that doesn't apply to all artists. Most artists will start with this directory empty.

Environment File Templates

Two files to create at the artist workspace root.

---

.env.example

This is the reference file that gets committed. All variables are commented out — agents uncomment and fill them in .env as services are connected.

# {Artist Name} — Environment Variables
# Copy this file to .env and fill in real values.
# NEVER commit .env — only .env.example gets checked in.

# Social accounts (add as accounts are set up)
# TIKTOK_USERNAME=
# TIKTOK_PASSWORD=
# INSTAGRAM_USERNAME=
# INSTAGRAM_PASSWORD=
# YOUTUBE_USERNAME=
# YOUTUBE_PASSWORD=
# TWITTER_USERNAME=
# TWITTER_PASSWORD=
# FACEBOOK_USERNAME=
# FACEBOOK_PASSWORD=

# Content posting
# POSTBRIDGE_API_KEY=

# AI services
# FAL_KEY=
# RECOUP_API_KEY=

# Distribution (add when connected)
# DISTROKID_API_KEY=

# Merch (add when connected)
# SHOPIFY_ACCESS_TOKEN=

# Website (add when connected)
# VERCEL_TOKEN=

---

.env

This is the actual secrets file — never committed. Start with just a header:

# {Artist Name} — Secrets
# Add credentials here as services are connected.
# See .env.example for all available variables.
# NEVER commit this file.

---

Important

Make sure .env is covered by .gitignore at the repo root or artist level. The monorepo root .gitignore typically already includes .env and .env.local.

Memory System Templates

Two files to create in memory/.

---

memory/README.md

---
name: Memory
description: "How the memory system works. Read this before writing to any memory file. This directory holds everything agents have LEARNED about {Artist Name} — not who the artist IS (that's context/), and not reference material (that's library/)."
---

# Memory

This directory is the artist's **learned knowledge** — what agents discover through doing the work. It grows over time as agents interact with the artist, create content, manage releases, and learn what works.

## Structure

memory/
├── README.md          ← You are here
├── MEMORY.md          ← Core index: always read first (keep under ~200 lines)
├── {topic}.md         ← Topic files: detailed notes (created as needed)
├── log/               ← Session logs: raw, append-only (created on first session)
│   └── YYYY-MM-DD.md
└── archive/           ← Past era memories (created when eras change)
    └── {era-slug}/

Only `README.md` and `MEMORY.md` ship at creation. Everything else is created by agents as they work.

## Memory Scope — The Most Important Concept

Not all knowledge has the same lifespan. Before saving ANYTHING to memory, determine its **scope**:

| Scope | Meaning | Where it goes | Example |
|-------|---------|---------------|---------|
| `permanent` | True about the artist regardless of era or phase | `MEMORY.md` | "The artist prefers lowercase in all captions" |
| `era` | True for the current release cycle — may change next era | `MEMORY.md` (tagged with era) | "Going for a darker visual tone this release" |
| `session` | A decision made about a specific piece of content or task | `log/YYYY-MM-DD.md` only | "User wanted blue hair on this image" |

### How to Decide Scope

**When in doubt, ASK.** If a user gives feedback while working on something specific, clarify before saving:

> "Got it — blue hair for this one. Should I make that the default going forward, or just for this piece?"

**Rules of thumb:**
- If the user is reacting to a specific output → it's probably **session** scope. Log it, don't memorize it.
- If the user says "always," "from now on," or "I prefer" → it's probably **permanent** or **era** scope.
- If it relates to the current release strategy, visual direction, or campaign → it's **era** scope.
- If it's about core identity, voice, or lasting preferences → it's **permanent** scope.

### Tagging Era-Scoped Memories

When writing era-scoped memories to `MEMORY.md`, tag them so they can be identified later:

Visual Direction (era: debut-ep)

• Going darker and moodier for this release
• Blue/purple palette instead of the usual warm tones

When `era.json` changes, these tagged sections become candidates for archiving.

## Files

### `MEMORY.md` — Core Index

The single most important file. **Read this first every session.**

- Contains curated, distilled knowledge about the artist
- Bounded: keep it under ~200 lines
- **Edit, don't just append** — update facts when they change, remove what's outdated
- When a section gets too detailed, move it into a topic file and leave a reference
- Tag era-specific entries so they can be archived when the era changes

### Topic Files (`{topic}.md`)

Created by agents when `MEMORY.md` sections grow too long. Examples:
- `content-learnings.md` — what works and doesn't for this artist's content
- `audience-insights.md` — patterns in audience behavior
- `process-notes.md` — how things work for this artist

**Format:**

---
name: {Topic Name}
description: "{What this file covers and when to read it.}"
era: {release-slug}
---

### `log/` — Session Logs

Raw, append-only logs of what happened each session. Created on first use. **Session-scoped decisions live here — not in MEMORY.md.**

**Format:** `log/YYYY-MM-DD.md`

Multiple entries per day are appended to the same file. Don't edit past entries.

### `archive/` — Past Era Memories

When an era changes, move era-tagged sections from `MEMORY.md` and era-scoped topic files here to keep the active memory clean and relevant.

## Session Lifecycle

### Start of Session
1. Read `memory/MEMORY.md` — get current knowledge
2. Check for today's log (`memory/log/YYYY-MM-DD.md`) — resume context if exists
3. Read `context/era.json` — know the current phase

### During Session
- Learn something durable → determine **scope**, then **update** `MEMORY.md` (permanent/era) or **append** to log (session)
- Discover a correction → **edit** `MEMORY.md` (replace the old fact)
- User gives feedback on specific content → **append** to today's log. Do NOT promote to `MEMORY.md` unless the user confirms it's a lasting preference
- Complete something or make a decision → **append** to today's log
- Need detailed history → **read** topic files or past logs

### End of Session
- Review: did anything important happen that's not in `MEMORY.md`?
- If `MEMORY.md` is getting long → move details into topic files

### When Era Changes (New Release Cycle)
1. Review all era-tagged entries in `MEMORY.md`
2. Ask the user: "We're starting a new era. Do these still apply?" (list the era-tagged items)
3. Archive what's no longer relevant → move to `archive/{old-era-slug}/`
4. Keep anything the user confirms is still true (update the era tag or promote to permanent)

### Periodic Maintenance
- Review recent logs → promote key insights to `MEMORY.md` (only if confirmed as lasting)
- Remove or update outdated facts in `MEMORY.md`

## What Goes Where

| I learned... | Scope | Write it to... |
|-------------|-------|---------------|
| A durable fact about the artist or their work | permanent | `MEMORY.md` (edit/update) |
| A preference for this release cycle | era | `MEMORY.md` (tagged with era) |
| A decision about a specific piece of content | session | `log/YYYY-MM-DD.md` (append only) |
| Detailed performance data or analysis | era | A topic file (e.g., `content-learnings.md`) |
| Something that corrects a previous belief | permanent | `MEMORY.md` (replace the old fact) |
| User feedback on one specific output | session | `log/YYYY-MM-DD.md` — ask before promoting |

## What Does NOT Go Here

| This kind of information... | Goes in... |
|----------------------------|-----------|
| Who the artist is (identity, brand, voice) | `context/artist.md` |
| Who the audience is | `context/audience.md` |
| Current release and phase | `context/era.json` |
| Reference docs, research, reports | `library/` |
| To-do items and tasks | `context/tasks.md` |
| Service connections and credentials | `config/SERVICES.md` |

---

memory/MEMORY.md

---
name: Memory
description: "Curated knowledge about {Artist Name}. Read this first every session. Keep concise — move details into topic files when sections grow."
---

# Memory

<!-- 
  This file is the core index of everything agents have learned about this artist.
  
  Guidelines:
  - Keep under ~200 lines
  - EDIT existing facts when they change — don't just append
  - When a section gets too detailed, move it to a topic file (e.g., content-learnings.md)
    and leave a one-line reference here
  - Delete or update anything that's no longer true
  
  SCOPE RULES:
  - Only write PERMANENT or ERA-scoped knowledge here
  - Tag era-scoped entries like: ## Section Name (era: release-slug)
  - Session-specific feedback belongs in log/YYYY-MM-DD.md — NOT here
  - When in doubt about scope, ASK the user before saving
  
  Structure will emerge naturally. Let the work define what sections you need.
-->

Root README Template

Create this as README.md at the artist workspace root. Replace all {placeholders}.

---

# {Artist Name}

Artist workspace — contains all context, content, songs, releases, and configuration for one artist. This directory is the **root** of the artist's sandbox environment.

## Directory Structure

| Directory | Purpose | Start here? |
|-----------|---------|:-----------:|
| `context/` | Essential artist context — identity, brand, audience, era, tasks | ✅ Yes |
| `memory/` | Learned knowledge — what agents discover over time. See `README.md` inside | ✅ Yes |
| `songs/` | Song catalog — one folder per song with audio, lyrics, metadata | ✅ Yes |
| `releases/` | Release catalog — one folder per release with RELEASE.md and artwork | ✅ Yes |
| `config/` | Per-artist config, services, and state for shared tools | When ready |
| `content/` | Created content — `images/` and `videos/{type}/` (e.g. `shortform`) | When ready |
| `library/` | Deep-dive reference docs — research, reports, strategies. See `README.md` inside | When ready |
| `apps/` | Artist-specific applications (e.g. personal website). See `README.md` inside | When ready |

## Context Files

| File | Format | Purpose |
|------|--------|---------|
| `context/artist.md` | Markdown | Complete artist profile — identity, brand, visual world, voice, tone |
| `context/audience.md` | Markdown | Emotional relationship with listeners — why they connect, how they talk, what earns shares |
| `context/era.json` | JSON | Machine routing — current release, song, phase, release date |
| `context/tasks.md` | Markdown | What needs to be done — organized by phase |
| `context/images/` | Images | Visual references — face guide, expressions, style references |

## Config & Services

| File | Purpose |
|------|---------|
| `config/SERVICES.md` | How to connect and track services — add entries as you go, not upfront |
| `config/services/` | Individual service JSON files — created when a service is actually connected |
| `.env.example` | Reference list of all env var names |
| `.env` | Actual secrets — never committed |

## Shared Tools

Shared automation apps (content-creation, content-poster) run **outside** this workspace. They read artist identity from `context/` and songs from `songs/`, and store their per-artist config in `config/{app-name}/`.

The `apps/` directory is for **artist-specific applications** only (like a personal website). Most artists start with it empty.

## Setup Checklist

### 1. Core Identity (do first)
- [ ] Verify `RECOUP.md` — artist slug, Recoup ID, status is `active`
- [ ] Write `context/artist.md` — identity, brand, visual world, voice, tone
- [ ] Write `context/audience.md` — who listens?

### 2. Music (do next)
- [ ] Add songs to `songs/{song-slug}/` (see `songs/README.md`)
- [ ] Create first release in `releases/{release-slug}/` (see `releases/README.md`)
- [ ] Set `context/era.json` — current release and phase

### 3. Accounts & Services
- [ ] Set up social accounts — TikTok, Instagram, YouTube, Twitter
- [ ] Add service entries to `config/services/` as accounts are connected (see `config/SERVICES.md`)
- [ ] Store credentials in `.env` (see `.env.example` for variable names)

### 4. Content Pipeline (when ready)
- [ ] Add a face guide image to `context/images/face-guide.png`
- [ ] Set up `config/content-creation/config.json` (see `config/README.md`)
- [ ] Set up PostBridge — `config/content-poster/config.json`
- [ ] Start generating content

Services Guide Template

Create this as config/SERVICES.md in the artist workspace.

---

---
name: Services
description: "How to connect and track services for {Artist Name}. Read this before adding any service. Don't pre-fill — add services as you learn about them."
---

# Services

This file teaches agents how to register tools, accounts, and capabilities for this artist. **Start empty. Add as you go.**

## When to Add a Service

Add a service entry when you have **real information** — a handle, an API key, a confirmed account. Don't create placeholder entries for services that don't exist yet.

Common triggers:
- User mentions a social media handle → add it to `social/`
- User sets up a new tool → add it to the relevant category
- An API key or credential is provided → add the service and store the key in `.env`

## Where Services Live

Each service is stored as a JSON file in `config/services/`:

config/services/ tiktok.json instagram.json fal.json postbridge.json

One file per service. Created when the service is first connected.

## Service File Format

{ "name": "tiktok", "category": "social", "handle": "@handle", "status": "active", "use": "What this service is used for in one sentence.", "auth": { "type": "login | api-key | oauth", "env": "ENV_VAR_NAME or { username: 'ENV_USER', password: 'ENV_PASS' }" } }

**Fields:**
- `name` — service identifier (lowercase, matches filename)
- `category` — one of: `social`, `posting`, `ai`, `distribution`, `merch`, `website`, `email`, `other`
- `handle` — username, page name, or URL (if applicable)
- `status` — `active`, `not-setup`, or `in-progress`
- `use` — one sentence explaining what the agent uses this service for
- `auth` — how to authenticate. Always reference env var names, never store actual secrets here

## Categories

| Category | What belongs here | Examples |
|----------|------------------|----------|
| `social` | Social media accounts the agent logs into for engagement | TikTok, Instagram, YouTube, Twitter, Facebook |
| `posting` | Tools that automate content posting across platforms | PostBridge |
| `ai` | AI services used by the content pipeline | fal (video/image gen), recoup-chat (text gen) |
| `distribution` | Music distribution to streaming platforms | DistroKid, TuneCore |
| `merch` | Merchandise and e-commerce | Shopify |
| `website` | Website hosting and management | Vercel |
| `email` | Artist email for business and fan communication | Email address |

## Credentials

All secrets go in the `.env` file at the artist root — **never** in service JSON files. The `auth.env` field in each service file tells agents which env var(s) to use.

## Universal Services

These are services every artist will eventually need. Don't create them ahead of time — add them when they're actually set up:

- **Social accounts** — TikTok, Instagram, YouTube, Twitter, Facebook
- **PostBridge** — automated content posting across all platforms
- **fal** — AI video/image generation (often pre-configured)
- **recoup-chat** — AI text generation (often pre-configured)
- **Email** — `{artist-slug}@recoupable.com`