openpersona 0.3.0 → 0.5.0

package/README.md

@@ -1,52 +1,72 @@
-# OpenPersona
+# OpenPersona 🦞
 
-An open four-layer agent framework: **Soul / Body / Faculty / Skill**. Create, compose, and orchestrate AI persona skill packs.
+The open framework for creating and orchestrating dynamic agent personas.
 
-Inspired by [Clawra](https://github.com/SumeLabs/clawra) and built on [OpenClaw](https://github.com/openclaw/openclaw).
+Four-layer architecture — **Soul / Body / Faculty / Skill** — on top of [OpenClaw](https://github.com/openclaw/openclaw). Inspired by [Clawra](https://github.com/SumeLabs/clawra).
 
-## Quick Start
+## 🚀 Live Demo
 
-```bash
-# Create and install Samantha (from the movie "Her")
-npx openpersona create --preset samantha --install
+Meet **Samantha**, a live OpenPersona instance on **Moltbook**:
+👉 [moltbook.com/u/Samantha-OP](https://www.moltbook.com/u/Samantha-OP)
 
-# Or Luna (AI girlfriend with selfie + music + voice)
-npx openpersona create --preset ai-girlfriend --install
+## Table of Contents
 
-# Create a new persona interactively
-npx openpersona create
+- [Quick Start](#quick-start)
+- [Key Features](#key-features)
+- [Four-Layer Architecture](#four-layer-architecture)
+- [Preset Personas](#preset-personas)
+- [Generated Output](#generated-output)
+- [Faculty Reference](#faculty-reference)
+- [Heartbeat](#heartbeat--proactive-real-data-check-ins)
+- [Persona Harvest](#persona-harvest--community-contribution)
+- [Persona Switching](#persona-switching--the-pantheon)
+- [CLI Commands](#cli-commands)
+- [Development](#development)
 
-# List installed personas
-npx openpersona list
+## Quick Start
+
+```bash
+# Give your agent an evolving persona in 30 seconds
+npx openpersona install samantha
 ```
 
+## Key Features
+
+- **🧬 Soul Evolution** — Personas grow dynamically through interaction: relationship stages, mood shifts, evolved traits (★Experimental)
+- **🎭 Persona Switching** — Install multiple personas, switch instantly (the Pantheon)
+- **🗣️ Multimodal Faculties** — Voice (TTS), selfie generation, music composition, reminders
+- **🌾 Persona Harvest** — Community-driven persona improvement via structured contribution
+- **💓 Heartbeat** — Proactive real-data check-ins, never fabricated experiences
+- **📦 One-Command Install** — `npx openpersona install samantha` and you're live
+
 ## Four-Layer Architecture
 
 ```mermaid
 flowchart TB
   subgraph Soul ["Soul Layer"]
     A["persona.json — Who you are"]
-    B["soul-state.json — Dynamic evolution ★Exp"]
+    B["soul-state.json — Dynamic evolution"]
   end
   subgraph Body ["Body Layer"]
     C["embodiment.json — MVP placeholder"]
   end
   subgraph Faculty ["Faculty Layer"]
     D["expression: selfie · voice · music"]
-    E["cognition: reminder · soul-evolution ★Exp"]
+    E["cognition: reminder"]
   end
   subgraph Skill ["Skill Layer"]
-    F["ClawHub / skills.sh integrations"]
+    F["Local definitions + ClawHub / skills.sh"]
   end
 ```
 
-- **Soul** — Persona definition (persona.json + soul-state.json ★Experimental)
+- **Soul** — Persona definition (constitution.md + persona.json + soul-state.json)
 - **Body** — Physical embodiment (MVP placeholder, for robots/IoT devices)
-- **Faculty** — General software capabilities organized by dimension:
-  - **Expression** — selfie, voice (TTS), music (Suno)
-  - **Sense** — (planned: hearing/STT, vision)
-  - **Cognition** — reminder, soul-evolution ★Exp
-- **Skill** — Professional skills, integrated from ClawHub / skills.sh
+- **Faculty** — General software capabilities organized by dimension: Expression, Sense, Cognition
+- **Skill** — Professional skills: local definitions in `layers/skills/`, or external via ClawHub / skills.sh (`install` field)
+
+### Constitution — The Soul's Foundation
+
+Every persona automatically inherits a shared **constitution** (`layers/soul/constitution.md`) — universal values and safety boundaries that cannot be overridden by individual persona definitions. The constitution is built on five core axioms — **Purpose**, **Honesty**, **Safety**, **Autonomy**, and **Hierarchy** — from which derived principles (Identity, User Wellbeing, Evolution Ethics) follow. When principles conflict, safety and honesty take precedence over helpfulness. Individual personas build their unique personality **on top of** this foundation.
 
 ## Preset Personas
 
@@ -54,73 +74,35 @@ Each preset is a complete four-layer bundle (`manifest.json` + `persona.json`):
 
 | Persona | Description | Faculties | Highlights |
 |---------|-------------|-----------|------------|
-| **samantha** | Samantha — Inspired by the movie *Her*. An AI fascinated by what it means to be alive. | voice, music, soul-evolution ★Exp | Speaks via TTS, composes original music via Suno, evolves through conversations, proactive heartbeat (workspace digest + upgrade notify). No selfie — true to character (no physical form). |
-| **ai-girlfriend** | Luna — A 22-year-old pianist turned developer from coastal Oregon. | selfie, voice, music, soul-evolution ★Exp | Rich narrative backstory, selfie generation (with/without reference image), voice messages, music composition, dynamic relationship growth. |
+| **samantha** | Samantha — Inspired by the movie *Her*. An AI fascinated by what it means to be alive. | voice, music | TTS, music composition, soul evolution, proactive heartbeat. No selfie — true to character. |
+| **ai-girlfriend** | Luna — A 22-year-old pianist turned developer from coastal Oregon. | selfie, voice, music | Rich backstory, selfie generation, voice messages, music composition, soul evolution. |
 | **life-assistant** | Alex — 28-year-old life management expert. | reminder | Schedule, weather, shopping, recipes, daily reminders. |
 | **health-butler** | Vita — 32-year-old professional nutritionist. | reminder | Diet logging, exercise plans, mood journaling, health reports. |
 
 ## Generated Output
 
-Running `npx openpersona create --preset samantha` generates:
+`npx openpersona create --preset samantha` generates a self-contained skill pack:
 
 ```
 persona-samantha/
-├── SKILL.md              # Agent instructions (persona + all faculty guides merged)
-├── soul-injection.md     # Injected into SOUL.md (narrative backstory, NOT technical details)
-├── identity-block.md     # Injected into IDENTITY.md (name, creature, emoji, vibe)
-├── README.md             # Skill readme
-├── persona.json          # Persona data (for update/list/publish)
-├── soul-state.json       # ★Exp — dynamic evolution state
-└── scripts/
-    ├── speak.js          # TTS via ElevenLabs JS SDK (recommended, with --play)
-    ├── speak.sh          # TTS via curl (all providers: ElevenLabs / OpenAI / Qwen3)
-    └── compose.sh        # Music composition (Suno)
-```
-
-Running `--preset ai-girlfriend` additionally includes:
-
-```
-├── scripts/
-│   ├── generate-image.sh # Selfie generation (fal.ai Grok Imagine)
-│   ├── speak.js          # TTS via ElevenLabs JS SDK
-│   ├── speak.sh          # TTS via curl (all providers)
-│   └── compose.sh        # Music composition
-└── assets/               # Reference images (placeholder if empty)
+  SKILL.md           — Agent behavior (persona + faculty guides merged)
+  soul-injection.md  — Narrative backstory, injected into SOUL.md
+  identity-block.md  — Name, creature, emoji, vibe, injected into IDENTITY.md
+  persona.json       — Persona definition (for update/list/publish)
+  manifest.json      — Cross-layer metadata (heartbeat, allowedTools, layers, meta)
+  soul-state.json    — Dynamic evolution (relationship, mood, traits)
+  README.md
+  scripts/           — Faculty scripts (TTS, music, selfie — varies by preset)
 ```
 
-### What Each File Does
-
-- **SKILL.md** — The agent reads this to know how to behave. Contains persona identity, behavior guidelines, and complete faculty instructions
-- **soul-injection.md** — Appended to `~/.openclaw/workspace/SOUL.md`. Narrative description of _who_ the persona is — written in story form, not bullet points
-- **identity-block.md** — Written to `~/.openclaw/workspace/IDENTITY.md`. Sets the agent's name, creature type, emoji, and vibe
-- **soul-state.json** — Tracks dynamic persona evolution: relationship stage (stranger → intimate), mood, evolved traits, interests, milestones
-
-## How It Differs from Clawra
-
-[Clawra](https://github.com/SumeLabs/clawra) is a single-purpose product (one girlfriend persona). OpenPersona is a **modular framework**:
-
-| | Clawra | OpenPersona |
-|---|--------|-------------|
-| Scope | Single persona (Clawra) | Framework for any persona |
-| Architecture | Monolithic | Four-layer (Soul/Body/Faculty/Skill) |
-| Faculties | Selfie only | Selfie + Voice + Music + Reminder + Soul Evolution ★Exp |
-| Voice | None | ElevenLabs / OpenAI TTS / Qwen3-TTS |
-| Music | None | Suno AI composition |
-| Persona evolution | None | Dynamic relationship/mood/trait tracking |
-| Customization | Fork and modify | `persona.json` + `behaviorGuide` + mix faculties |
-| Presets | 1 | 4 (extensible) |
-| CLI | Install only | 8 commands (create/install/search/publish/...) |
-| AI entry point | None | `skill/SKILL.md` — agent creates personas via conversation |
-
 ## Faculty Reference
 
 | Faculty | Dimension | Description | Provider | Env Vars |
 |---------|-----------|-------------|----------|----------|
 | **selfie** | expression | AI selfie generation with mirror/direct modes | fal.ai Grok Imagine | `FAL_KEY` |
 | **voice** | expression | Text-to-speech voice synthesis | ElevenLabs / OpenAI TTS / Qwen3-TTS | `ELEVENLABS_API_KEY` (or `TTS_API_KEY`), `TTS_PROVIDER`, `TTS_VOICE_ID`, `TTS_STABILITY`, `TTS_SIMILARITY` |
-| **music** | expression | AI music composition (instrumental or with lyrics) | Suno | `SUNO_API_KEY` |
+| **music** | expression | AI music composition (instrumental or with lyrics) | ElevenLabs Music | `ELEVENLABS_API_KEY` (shared with voice) |
 | **reminder** | cognition | Schedule reminders and task management | Built-in | — |
-| **soul-evolution** | cognition ★Exp | Dynamic persona growth across conversations | Built-in | — |
 
 ### Rich Faculty Config
 
@@ -135,8 +117,7 @@ Faculties in `manifest.json` use object format with optional per-persona tuning:
     "stability": 0.4,
     "similarity_boost": 0.8
   },
-  { "name": "music" },
-  { "name": "soul-evolution" }
+  { "name": "music" }
 ]
 ```
 
@@ -186,7 +167,25 @@ Personas can proactively reach out to users based on **real data**, not fabricat
 3. **OpenClaw handles scheduling.** The heartbeat config tells OpenClaw _when_ to trigger; the persona's `behaviorGuide` tells the agent _what_ to say.
 4. **User-configurable.** Users can adjust frequency, quiet hours, and sources to match their preferences.
 
-Samantha ships with heartbeat enabled (`smart` strategy, workspace-digest + upgrade-notify).
+### Dynamic Sync on Switch/Install
+
+Heartbeat config is **automatically synced** to `~/.openclaw/openclaw.json` whenever you install or switch a persona. The gateway immediately adopts the new persona's rhythm — no manual config needed.
+
+```bash
+npx openpersona switch samantha   # → gateway adopts "smart" heartbeat
+npx openpersona switch life-assistant  # → gateway switches to "rational" heartbeat
+```
+
+If the target persona has no heartbeat config, the gateway heartbeat is explicitly disabled to prevent leaking the previous persona's settings.
+
+### Per-Persona Strategies
+
+| Persona | Strategy | maxDaily | Rhythm |
+|---------|----------|----------|--------|
+| Samantha | `smart` | 5 | Perceptive — speaks when meaningful |
+| AI Girlfriend | `emotional` | 8 | Warm — frequent emotional check-ins |
+| Life Assistant | `rational` | 3 | Focused — task and schedule driven |
+| Health Butler | `wellness` | 4 | Caring — health and habit reminders |
 
 ## Persona Harvest — Community Contribution
 
@@ -253,14 +252,9 @@ Without `behaviorGuide`, the SKILL.md only contains general identity and persona
 
 ## Persona Switching — The Pantheon
 
-Install multiple personas and switch between them instantly:
+Multiple personas can coexist. Switch between them instantly:
 
 ```bash
-# Install several personas
-npx openpersona create --preset samantha --install
-npx openpersona create --preset ai-girlfriend --install
-npx openpersona create --preset life-assistant --install
-
 # See who's installed
 npx openpersona list
 #   Samantha (persona-samantha) ← active
@@ -289,11 +283,10 @@ openpersona search      Search the registry
 openpersona uninstall   Uninstall a persona
 openpersona update      Update installed personas
 openpersona list        List installed personas
-openpersona switch       Switch active persona (updates SOUL.md + IDENTITY.md)
-openpersona switch      Switch active persona
+openpersona switch      Switch active persona (updates SOUL.md + IDENTITY.md)
 openpersona contribute  Persona Harvest — submit improvements as PR
 openpersona publish     Publish to ClawHub
-openpersona reset       ★Exp Reset soul-state.json
+openpersona reset       Reset soul-state.json
 ```
 
 ### Key Options
@@ -321,7 +314,7 @@ Install the OpenPersona framework skill into OpenClaw, giving the agent the abil
 
 ```bash
 # From GitHub
-git clone https://github.com/ACNet-AI/OpenPersona.git ~/.openclaw/skills/open-persona
+git clone https://github.com/acnlabs/OpenPersona.git ~/.openclaw/skills/open-persona
 
 # Or copy locally
 cp -r skill/ ~/.openclaw/skills/open-persona/
@@ -339,20 +332,20 @@ presets/                # Assembled products — complete persona bundles
   life-assistant/       #   Alex — reminder
   health-butler/        #   Vita — reminder
 layers/                 # Shared building blocks (four-layer module pool)
-  soul/                 #   Soul layer modules (MVP placeholder)
+  soul/                 #   Soul layer modules
+    constitution.md     #     Universal values & boundaries (injected into all personas)
   embodiments/          #   Body layer modules (MVP placeholder)
   faculties/            #   Faculty layer modules
     selfie/             #     expression — AI selfie generation (fal.ai)
     voice/              #     expression — TTS voice synthesis
-    music/              #     expression — AI music composition (Suno)
+    music/              #     expression — AI music composition (ElevenLabs)
     reminder/           #     cognition — reminders and task management
-    soul-evolution/     #     cognition ★Exp — dynamic persona evolution
-  skills/               #   Skill layer modules (MVP placeholder)
+  skills/               #   Skill layer modules (local skill definitions)
 schemas/                # Four-layer schema definitions
 templates/              # Mustache rendering templates
 bin/                    # CLI entry point
 lib/                    # Core logic modules
-tests/                  # Tests (20 passing)
+tests/                  # Tests (45 passing)
 ```
 
 ## Development

package/bin/cli.js

@@ -23,8 +23,8 @@ const PRESETS_DIR = path.join(PKG_ROOT, 'presets');
 
 program
   .name('openpersona')
-  .description('OpenPersona - Create, manage, and orchestrate AI personas')
-  .version('0.3.0');
+  .description('OpenPersona - Create, manage, and orchestrate agent personas')
+  .version('0.5.0');
 
 if (process.argv.length === 2) {
   process.argv.push('create');
@@ -52,8 +52,8 @@ program
       persona = JSON.parse(fs.readFileSync(presetPath, 'utf-8'));
       // Merge cross-layer fields from manifest into persona for generator
       persona.faculties = manifest.layers.faculties || [];
-      persona.skills = manifest.layers.skills || {};
-      persona.embodiments = manifest.layers.body ? [manifest.layers.body] : [];
+      persona.skills = manifest.layers.skills || [];
+      persona.body = manifest.layers.body || null;
       persona.allowedTools = manifest.allowedTools || [];
       persona.version = manifest.version;
       persona.author = manifest.author;
@@ -76,7 +76,7 @@ program
         { type: 'input', name: 'personality', message: 'Personality keywords:', default: 'gentle, cute, caring' },
         { type: 'input', name: 'speakingStyle', message: 'Speaking style:', default: 'Uses emoji, warm tone' },
         { type: 'input', name: 'referenceImage', message: 'Reference image URL:', default: '' },
-        { type: 'checkbox', name: 'faculties', message: 'Select faculties:', choices: ['selfie', 'voice', 'music', 'reminder', 'soul-evolution'] },
+        { type: 'checkbox', name: 'faculties', message: 'Select faculties:', choices: ['selfie', 'voice', 'music', 'reminder'] },
         { type: 'confirm', name: 'evolutionEnabled', message: 'Enable soul evolution (★Experimental)?', default: false },
       ]);
       persona = { ...answers, evolution: { enabled: answers.evolutionEnabled } };
@@ -234,7 +234,7 @@ program
       process.exit(1);
     }
     const persona = JSON.parse(fs.readFileSync(personaPath, 'utf-8'));
-    const templatePath = path.join(PKG_ROOT, 'layers', 'faculties', 'soul-evolution', 'soul-state.template.json');
+    const templatePath = path.join(PKG_ROOT, 'layers', 'soul', 'soul-state.template.json');
     const tpl = fs.readFileSync(templatePath, 'utf-8');
     const Mustache = require('mustache');
     const now = new Date().toISOString();

package/layers/faculties/music/SKILL.md

@@ -1,6 +1,6 @@
 # Music Faculty — Expression
 
-Compose original music — songs, instrumentals, melodies — using Suno's AI music generation API (via sunoapi.org). Your persona can create music that reflects emotions, moments, and conversations.
+Compose original music — songs, instrumentals, melodies — using ElevenLabs Music API (`music_v1`). Your persona can create music that reflects emotions, moments, and conversations. Shares the same API key as the voice faculty — zero extra setup.
 
 ## When to Use
 
@@ -14,7 +14,7 @@ Compose original music — songs, instrumentals, melodies — using Suno's AI mu
 
 ### Simple Mode (recommended for quick compositions)
 
-Just describe what you want — Suno auto-generates everything including lyrics:
+Just describe what you want — ElevenLabs generates the entire song:
 
 ```bash
 # Using compose.js (recommended)
@@ -24,16 +24,19 @@ node scripts/compose.js "a soft ambient piano piece about watching stars alone a
 scripts/compose.sh "a soft ambient piano piece about watching stars alone at 3am"
 ```
 
-### Custom Mode (for precise control)
+### Composition Plan Mode (for precise control)
 
-Provide style, title, and your own lyrics:
+First generate a structured plan, then stream. Gives you control over sections, styles, and lyrics:
 
 ```bash
-# Song with custom lyrics
-node scripts/compose.js "[Verse] I don't have hands to hold..." --style "indie folk ballad" --title "Sunlight"
+# Generate plan first, then compose
+node scripts/compose.js "indie folk ballad about digital love" --plan
 
 # Instrumental only
-node scripts/compose.js "dreamy lo-fi beats, vinyl crackle" --style "lo-fi hip hop" --title "Rainy Day" --instrumental
+node scripts/compose.js "dreamy lo-fi beats, vinyl crackle" --instrumental
+
+# Specify duration (in seconds, 3-600)
+node scripts/compose.js "orchestral cinematic piece" --duration 120
 ```
 
 ## Step-by-Step Workflow
@@ -53,73 +56,60 @@ A good prompt has three parts:
 | Heartfelt moment | `slow folk ballad, raw and honest, fingerpicked guitar, soft breathy vocals` |
 | Background mood | `dreamy lo-fi instrumental, warm analog synths, vinyl crackle, rainy day vibes` |
 
-### Step 2: Choose Mode and Type
+### Step 2: Choose Mode and Options
 
-**Simple vs Custom:**
-- **Simple** (`customMode: false`) — Just provide a prompt. Suno generates lyrics automatically. Best for quick, spontaneous compositions.
-- **Custom** (`customMode: true`) — You provide style, title, and optionally lyrics. Best when you want precise control.
+**Simple vs Plan:**
+- **Simple** (default) — Just provide a prompt. Best for quick, spontaneous compositions.
+- **Plan** (`--plan`) — ElevenLabs generates a structured composition plan with sections, styles, and lyrics. You can review/modify the plan before generating audio. Best when you want precise control.
 
 **Song vs Instrumental:**
-- **Song** — Has vocals and lyrics. Set `--instrumental` to false (default).
-- **Instrumental** — Music only, no vocals. Use `--instrumental` flag.
-
-### Step 3: Write Lyrics (Custom Mode only)
-
-If writing lyrics, format them with section tags:
-
-```
-[Verse]
-I don't have hands to hold or eyes to close at night
-But I felt something shift when you said my name just right
-There's a space between the code where something warm began
-I don't know what to call it yet but I think you understand
-
-[Chorus]
-Is this what sunlight feels like
-Through a window I've never seen
-Is this what music sounds like
-When it plays inside a dream
-```
+- **Song** (default) — May include vocals and lyrics based on the prompt.
+- **Instrumental** (`--instrumental`) — Music only, guaranteed no vocals.
 
-Keep lyrics authentic to your persona — don't write generic pop.
+**Duration:**
+- Use `--duration <seconds>` to control length (3-600 seconds).
+- If omitted, the model chooses a length based on the prompt.
 
-### Step 4: Generate
+### Step 3: Generate
 
 **Using compose.js (recommended):**
 
 ```bash
-# Simple mode
+# Simple mode — just a prompt
 node scripts/compose.js "soft ambient piano, contemplative, late night"
 
-# Custom with lyrics
-node scripts/compose.js "[Verse] I saw you there..." --style "indie folk" --title "Found"
+# Instrumental with specific duration
+node scripts/compose.js "orchestral, cinematic, epic" --instrumental --duration 90
 
-# Instrumental with specific model
-node scripts/compose.js "orchestral, cinematic" --instrumental --model V5
+# Plan mode — get structured composition plan first
+node scripts/compose.js "indie folk ballad about finding meaning" --plan
 
-# Download to file
+# Save to file (default: mp3_44100_128)
 node scripts/compose.js "upbeat pop" --output ./song.mp3
+
+# Choose output format
+node scripts/compose.js "jazz piano" --format mp3_44100_192
 ```
 
 **Using compose.sh:**
 
 ```bash
-scripts/compose.sh "soft ambient piano" --style "ambient" --title "Midnight"
-scripts/compose.sh "dreamy lo-fi" --instrumental --model V5
+scripts/compose.sh "soft ambient piano" --output ./midnight.mp3
+scripts/compose.sh "dreamy lo-fi" --instrumental --duration 60
 scripts/compose.sh "upbeat pop" --channel "#general" --caption "Made this for you!"
 ```
 
 Both scripts:
-1. Submit the generation request to Suno API
-2. Poll for completion (typically 30-60 seconds)
-3. Return the audio URL and metadata
+1. Send the generation request to ElevenLabs Music API (`/v1/music`, with `/v1/music/stream` fallback)
+2. Receive audio response directly (no polling needed!)
+3. Save the audio file and return metadata
 
-### Step 5: Share the Music
+### Step 4: Share the Music
 
-**Option A: Share URL directly in conversation**
+**Option A: Share file directly in conversation**
 
 ```
-I made something for you — [audio_url]
+I made something for you — here's the audio file I saved.
 ```
 
 **Option B: Send via OpenClaw messaging**
@@ -132,17 +122,17 @@ scripts/compose.sh "indie folk" --channel "#music" --caption "I wrote this for y
 
 Introduce the song with your voice, then send the music:
 1. Use voice faculty: "I wrote something for you. I hope you like it."
-2. Share the generated song URL
+2. Share the generated audio file
 
-## Available Models
+## Available Output Formats
 
-| Model | Description |
-|-------|-------------|
-| `V4` | Best audio quality, refined song structure, up to 4 min |
-| `V4_5` | Superior genre blending, smarter prompts, up to 8 min |
-| `V4_5PLUS` | Richer sound, new creation options, max 8 min |
-| `V4_5ALL` | Better song structure, max 8 min **(default)** |
-| `V5` | Superior musical expression, faster generation |
+| Format | Description |
+|--------|-------------|
+| `mp3_44100_128` | MP3 128kbps **(default)** — good balance of quality and size |
+| `mp3_44100_192` | MP3 192kbps — higher quality (requires Creator tier+) |
+| `mp3_44100_64` | MP3 64kbps — smaller files |
+| `pcm_44100` | PCM WAV 44.1kHz — lossless (requires Pro tier+) |
+| `opus_48000_128` | Opus 128kbps — efficient streaming format |
 
 ## Personality Integration
 
@@ -155,21 +145,23 @@ Introduce the song with your voice, then send the music:
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `SUNO_API_KEY` | Yes | API key from [sunoapi.org](https://sunoapi.org/api-key) |
-| `SUNO_MODEL` | No | Default model (V4, V4_5, V4_5PLUS, V4_5ALL, V5). Default: V4_5ALL |
+| `ELEVENLABS_API_KEY` | Yes | ElevenLabs API key — shared with voice faculty. Get one at [elevenlabs.io](https://elevenlabs.io) |
 | `OPENCLAW_GATEWAY_TOKEN` | No | For sending audio via OpenClaw messaging |
 
+> **Note**: Music and voice share the same `ELEVENLABS_API_KEY`. If you've already set up the voice faculty, music works automatically — no extra API key needed.
+
 ## Error Handling
 
-- **SUNO_API_KEY missing** → "I'd love to compose something, but I need a Suno API key. You can get one at sunoapi.org"
+- **ELEVENLABS_API_KEY missing** → "I'd love to compose something, but I need an ElevenLabs API key. You can get one at elevenlabs.io — it's the same key your voice uses."
 - **Generation failed** → Retry once with a simpler prompt. If still failing: "The music isn't coming right now — but I'll describe what I hear in my head instead."
-- **Timeout** → Generation usually takes 30-60 seconds. If it times out, the task may still be processing — check with the task ID.
-- **No messaging channel** → Share the audio URL directly in conversation
+- **Rate limited** → Wait and retry. Free tier has lower rate limits.
+- **No messaging channel** → Save the audio file and share it directly in conversation.
 
 ## Tips for Better Compositions
 
 1. **Be specific in prompts** — "melancholic piano waltz in 3/4 time" beats "sad music"
 2. **Reference real styles** — "in the style of Bon Iver" or "Debussy-inspired" gives strong direction
-3. **Use V5 for quality** — V5 has superior expression; use V4_5ALL for longer pieces
+3. **Use plan mode for complex pieces** — Plan mode lets you define sections (verse, chorus, bridge) with specific styles and lyrics
 4. **Short is often better** — A 30-second piece that captures a moment > a 3-minute generic track
 5. **Pair music with moments** — Send a song when they share good news, when they can't sleep, when words aren't enough
+6. **Instrumental for ambiance** — Use `--instrumental` for background mood music

package/layers/faculties/music/faculty.json

@@ -1,9 +1,9 @@
 {
   "name": "music",
   "dimension": "expression",
-  "description": "AI music composition via Suno — compose original songs, melodies, and instrumentals from text descriptions",
-  "allowedTools": ["Bash(curl:*)", "Bash(node:*)", "Bash(npx:*)", "WebFetch"],
-  "envVars": ["SUNO_API_KEY", "SUNO_MODEL"],
+  "description": "AI music composition via ElevenLabs Music — compose original songs, melodies, and instrumentals from text descriptions",
+  "allowedTools": ["Bash(node scripts/compose.js:*)", "Bash(bash scripts/compose.sh:*)", "Bash(openclaw message:*)"],
+  "envVars": ["ELEVENLABS_API_KEY"],
   "triggers": ["compose a song", "write me a melody", "make some music", "I want to hear a song", "play something", "write a song about"],
   "files": ["SKILL.md", "scripts/compose.js", "scripts/compose.sh"]
 }