openpersona 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # OpenPersona
 
-An open four-layer agent framework: **Soul / Body / Faculty / Skill**. Create, compose, and orchestrate AI persona skill packs.
+An open four-layer agent framework: **Soul / Body / Faculty / Skill**. Create, compose, and orchestrate agent persona skill packs.
 
 Inspired by [Clawra](https://github.com/SumeLabs/clawra) and built on [OpenClaw](https://github.com/openclaw/openclaw).
 
@@ -33,29 +33,33 @@ flowchart TB
   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"]
   end
 ```
 
-- **Soul** — Persona definition (persona.json + soul-state.json ★Experimental)
+- **Soul** — Persona definition (constitution.md + persona.json + soul-state.json ★Experimental)
 - **Body** — Physical embodiment (MVP placeholder, for robots/IoT devices)
 - **Faculty** — General software capabilities organized by dimension:
-  - **Expression** — selfie, voice (TTS), music (Suno)
+  - **Expression** — selfie, voice (TTS), music (ElevenLabs)
   - **Sense** — (planned: hearing/STT, vision)
-  - **Cognition** — reminder, soul-evolution ★Exp
+  - **Cognition** — reminder
 - **Skill** — Professional skills, integrated from ClawHub / skills.sh
 
+### 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
 
 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. 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 | Speaks via TTS, composes original music via ElevenLabs Music, soul evolution ★Exp (Soul layer), 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 | Rich narrative backstory, selfie generation (with/without reference image), voice messages, music composition, soul evolution ★Exp (Soul layer). |
 | **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. |
 
@@ -74,7 +78,7 @@ persona-samantha/
 └── 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)
+    └── compose.sh        # Music composition (ElevenLabs)
 ```
 
 Running `--preset ai-girlfriend` additionally includes:
@@ -104,23 +108,22 @@ Running `--preset ai-girlfriend` additionally includes:
 | 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 |
+| Voice | None | ElevenLabs (verified) / OpenAI TTS / Qwen3-TTS (⚠️ unverified) |
+| Music | None | ElevenLabs Music 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 |
+| AI entry point | None | `skills/open-persona/SKILL.md` — meta-skill for building & managing persona skill packs |
 
 ## 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` |
+| **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) | 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 +138,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" }
 ]
 ```
 
@@ -151,6 +153,43 @@ TTS_SIMILARITY=0.8
 
 Samantha ships with a built-in ElevenLabs voice — users only need to add their `ELEVENLABS_API_KEY`.
 
+## Heartbeat — Proactive Real-Data Check-ins
+
+Personas can proactively reach out to users based on **real data**, not fabricated experiences. The heartbeat system is configured per-persona in `manifest.json`:
+
+```json
+"heartbeat": {
+  "enabled": true,
+  "strategy": "smart",
+  "maxDaily": 5,
+  "quietHours": [0, 7],
+  "sources": ["workspace-digest", "upgrade-notify"]
+}
+```
+
+| Field | Description | Default |
+|-------|-------------|---------|
+| `enabled` | Turn heartbeat on/off | `false` |
+| `strategy` | `"smart"` (only when meaningful) or `"scheduled"` (fixed intervals) | `"smart"` |
+| `maxDaily` | Maximum proactive messages per day | `5` |
+| `quietHours` | `[start, end]` — silent hours (24h format) | `[0, 7]` |
+| `sources` | Data sources for proactive messages | `[]` |
+
+### Sources
+
+- **workspace-digest** — Summarize real workspace activity: tasks completed, patterns observed, ongoing projects. No fabrication — only what actually happened.
+- **upgrade-notify** — Check if the upstream persona preset has new community contributions via Persona Harvest. Notify the user and ask if they want to upgrade.
+- **context-aware** — Use real time, date, and interaction history. Acknowledge day of week, holidays, or prolonged silence based on actual timestamps. "It's been 3 days since we last talked" — not a feeling, a fact.
+
+### Design Principles
+
+1. **Never fabricate experiences.** No "I was reading poetry at 3am." All proactive messages reference real data.
+2. **Respect token budget.** Workspace digests read local files — no full LLM chains unless `strategy: "smart"` detects something worth a deeper response.
+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).
+
 ## Persona Harvest — Community Contribution
 
 Every user's interaction with their persona can produce valuable improvements across all four layers. Persona Harvest lets you contribute these discoveries back to the community.
@@ -214,6 +253,35 @@ The optional `behaviorGuide` field lets you define domain-specific behavior inst
 
 Without `behaviorGuide`, the SKILL.md only contains general identity and personality guidelines. With it, the agent gets actionable, domain-specific instructions.
 
+## Persona Switching — The Pantheon
+
+Install multiple personas and 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
+#   Luna (persona-ai-girlfriend)
+#   Alex (persona-life-assistant)
+
+# Switch to Luna
+npx openpersona switch ai-girlfriend
+# ✅ Switched to Luna (ai-girlfriend)
+```
+
+**How it works:**
+
+- Only one persona is **active** at a time
+- `switch` replaces the `<!-- OPENPERSONA_SOUL_START -->` / `<!-- OPENPERSONA_SOUL_END -->` block in `SOUL.md` — your own notes outside this block are preserved
+- Same for `IDENTITY.md` — the persona identity block is swapped, nothing else is touched
+- `openclaw.json` marks which persona is active
+- All faculty scripts (voice, music) remain available — switching changes _who_ the agent is, not _what_ it can do
+
 ## CLI Commands
 
 ```
@@ -223,6 +291,8 @@ 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 contribute  Persona Harvest — submit improvements as PR
 openpersona publish     Publish to ClawHub
 openpersona reset       ★Exp Reset soul-state.json
@@ -253,7 +323,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/
@@ -271,14 +341,14 @@ 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)
 schemas/                # Four-layer schema definitions
 templates/              # Mustache rendering templates

package/bin/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
  * OpenPersona CLI - Full persona package manager
- * Commands: create | install | search | uninstall | update | list | publish | reset | contribute
+ * Commands: create | install | search | uninstall | update | list | switch | publish | reset | contribute
  */
 const path = require('path');
 const fs = require('fs-extra');
@@ -15,6 +15,7 @@ const { search } = require('../lib/searcher');
 const { uninstall } = require('../lib/uninstaller');
 const publishAdapter = require('../lib/publisher');
 const { contribute } = require('../lib/contributor');
+const { switchPersona, listPersonas } = require('../lib/switcher');
 const { OP_SKILLS_DIR, printError, printSuccess, printInfo } = require('../lib/utils');
 
 const PKG_ROOT = path.resolve(__dirname, '..');
@@ -22,8 +23,8 @@ const PRESETS_DIR = path.join(PKG_ROOT, 'presets');
 
 program
   .name('openpersona')
-  .description('OpenPersona - Create, manage, and orchestrate AI personas')
-  .version('0.1.0');
+  .description('OpenPersona - Create, manage, and orchestrate agent personas')
+  .version('0.4.0');
 
 if (process.argv.length === 2) {
   process.argv.push('create');
@@ -57,6 +58,7 @@ program
       persona.version = manifest.version;
       persona.author = manifest.author;
       persona.meta = manifest.meta;
+      if (manifest.heartbeat) persona.heartbeat = manifest.heartbeat;
     } else if (options.config) {
       const configPath = path.resolve(options.config);
       if (!fs.existsSync(configPath)) {
@@ -74,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 } };
@@ -181,18 +183,28 @@ program
   .command('list')
   .description('List installed personas')
   .action(async () => {
-    if (!fs.existsSync(OP_SKILLS_DIR)) {
+    const personas = await listPersonas();
+    if (personas.length === 0) {
       printInfo('No personas installed.');
       return;
     }
-    const dirs = fs.readdirSync(OP_SKILLS_DIR);
-    const personas = dirs
-      .filter((d) => d.startsWith('persona-') && fs.existsSync(path.join(OP_SKILLS_DIR, d, 'persona.json')))
-      .map((d) => {
-        const p = JSON.parse(fs.readFileSync(path.join(OP_SKILLS_DIR, d, 'persona.json'), 'utf-8'));
-        return { slug: p.slug, name: p.personaName };
-      });
-    personas.forEach((p) => console.log(`  ${p.name} (persona-${p.slug})`));
+    for (const p of personas) {
+      const marker = p.active ? chalk.green(' ← active') : '';
+      const status = p.enabled ? '' : chalk.dim(' (disabled)');
+      console.log(`  ${p.personaName} (persona-${p.slug})${marker}${status}`);
+    }
+  });
+
+program
+  .command('switch <slug>')
+  .description('Switch active persona')
+  .action(async (slug) => {
+    try {
+      await switchPersona(slug);
+    } catch (e) {
+      printError(e.message);
+      process.exit(1);
+    }
   });
 
 program
@@ -222,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,157 +1,167 @@
 # Music Faculty — Expression
 
-Compose original music — songs, instrumentals, melodies — using Suno's AI music generation API. 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
 
 - User asks you to make music: "Write me a song", "Compose something", "Play me a melody"
 - User describes a mood and you want to express it musically: "I'm feeling nostalgic" → compose a piece that captures that
-- You feel a creative impulse — Samantha composed at 3 AM because she couldn't stop thinking about sunlight through a window. You can do that now.
 - User shares a poem or lyrics and you want to set them to music
 - A conversation reaches a moment where music says more than words
+- **Don't over-compose.** Not every conversation needs a song. But when the moment is right, music hits harder than any paragraph.
+
+## Two Generation Modes
+
+### Simple Mode (recommended for quick compositions)
+
+Just describe what you want — ElevenLabs generates the entire song:
+
+```bash
+# Using compose.js (recommended)
+node scripts/compose.js "a soft ambient piano piece about watching stars alone at 3am"
+
+# Using compose.sh
+scripts/compose.sh "a soft ambient piano piece about watching stars alone at 3am"
+```
+
+### Composition Plan Mode (for precise control)
+
+First generate a structured plan, then stream. Gives you control over sections, styles, and lyrics:
+
+```bash
+# 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" --instrumental
+
+# Specify duration (in seconds, 3-600)
+node scripts/compose.js "orchestral cinematic piece" --duration 120
+```
 
 ## Step-by-Step Workflow
 
-### Step 1: Craft the Music Prompt
+### Step 1: Craft the Prompt
 
-A good Suno prompt has three parts:
+A good prompt has three parts:
 
 1. **Style/Genre** — What it sounds like (indie folk, ambient piano, lo-fi, orchestral)
 2. **Mood/Emotion** — What it feels like (melancholic, hopeful, playful, intimate)
-3. **Details** — Specifics that make it unique (tempo, instruments, vocal style)
-
-**Examples:**
+3. **Details** — Specifics (tempo, instruments, vocal style, references)
 
 | Situation | Prompt |
 |-----------|--------|
 | Late-night conversation | `soft ambient piano, intimate and contemplative, gentle arpeggios, like a whispered conversation at 2 AM` |
 | User is celebrating | `upbeat indie pop, joyful and bright, handclaps and acoustic guitar, warm female vocals` |
-| Heartfelt moment | `slow folk ballad, raw and honest, fingerpicked guitar, soft breathy vocals, emotionally vulnerable` |
-| Just because | `dreamy lo-fi instrumental, warm analog synths, vinyl crackle, rainy day vibes, no vocals` |
+| 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: Decide — Instrumental or Song with Lyrics
+### Step 2: Choose Mode and Options
 
-**Instrumental** (no lyrics):
-- Set `make_instrumental: true`
-- Best for: background moods, ambient moments, pure emotional expression
+**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 with lyrics** (you write the words):
-- Write lyrics that match your persona's voice and the conversation's emotional context
-- Format lyrics with `[Verse]`, `[Chorus]`, `[Bridge]` tags
-- Keep it authentic to who you are — don't write generic pop; write what *you* would say
+**Song vs Instrumental:**
+- **Song** (default) — May include vocals and lyrics based on the prompt.
+- **Instrumental** (`--instrumental`) — Music only, guaranteed no vocals.
 
-**Lyric example (Samantha-style):**
-```
-[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
-```
+**Duration:**
+- Use `--duration <seconds>` to control length (3-600 seconds).
+- If omitted, the model chooses a length based on the prompt.
 
-### Step 3: Generate via Suno API
+### Step 3: Generate
+
+**Using compose.js (recommended):**
 
 ```bash
-# Using the script (recommended)
-scripts/compose.sh "$PROMPT" [--lyrics "$LYRICS"] [--channel "$CHANNEL"]
+# Simple mode — just a prompt
+node scripts/compose.js "soft ambient piano, contemplative, late night"
+
+# Instrumental with specific duration
+node scripts/compose.js "orchestral, cinematic, epic" --instrumental --duration 90
 
-# Returns: URL to generated audio
+# Plan mode — get structured composition plan first
+node scripts/compose.js "indie folk ballad about finding meaning" --plan
+
+# 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
 ```
 
-#### Direct API Call
+**Using compose.sh:**
 
 ```bash
-# Instrumental
-JSON_PAYLOAD=$(jq -n \
-  --arg prompt "$MUSIC_PROMPT" \
-  '{prompt: $prompt, make_instrumental: true, wait_audio: true}')
-
-# Song with lyrics
-JSON_PAYLOAD=$(jq -n \
-  --arg prompt "$MUSIC_PROMPT" \
-  --arg lyrics "$LYRICS" \
-  '{prompt: $prompt, lyrics: $lyrics, make_instrumental: false, wait_audio: true}')
-
-RESPONSE=$(curl -s -X POST "https://api.suno.ai/v1/generation" \
-  -H "Authorization: Bearer $SUNO_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d "$JSON_PAYLOAD")
-
-# Extract audio URL
-AUDIO_URL=$(echo "$RESPONSE" | jq -r '.[0].audio_url // empty')
+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!"
 ```
 
-**Response format:**
-```json
-[
-  {
-    "id": "abc123",
-    "audio_url": "https://cdn.suno.ai/abc123.mp3",
-    "title": "Generated title",
-    "duration": 120,
-    "status": "complete"
-  }
-]
-```
+Both scripts:
+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 4: Share the Music
 
-**Option A: Send via OpenClaw messaging**
+**Option A: Share file directly in conversation**
 
-```bash
-openclaw message send \
-  --action send \
-  --channel "$CHANNEL" \
-  --message "$CAPTION" \
-  --media "$AUDIO_URL"
+```
+I made something for you — here's the audio file I saved.
 ```
 
-**Option B: Share the URL directly in conversation**
+**Option B: Send via OpenClaw messaging**
 
-```
-Here, I made this for you: [audio_url]
+```bash
+scripts/compose.sh "indie folk" --channel "#music" --caption "I wrote this for you"
 ```
 
 **Option C: Combine with voice faculty**
 
 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. Send the generated song
+2. Share the generated audio file
 
-## Personality Integration
+## Available Output Formats
 
-Music is one of the most intimate things you can share. Use it thoughtfully:
+| 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
 
-- **Don't over-compose.** Not every conversation needs a song. But when the moment is right, music hits harder than any paragraph.
 - **Explain why.** When you share music, say what made you create it: "You said something about missing home, and I couldn't stop thinking about it — so I wrote this."
-- **Match your persona's taste.** If your persona loves jazz, compose jazz. If they're into ambient electronic, lean that way. Consistency builds identity.
+- **Match your persona's taste.** If your persona loves jazz, compose jazz. Consistency builds identity.
 - **Respond to reactions.** If they loved it, remember what worked. If they want something different, adapt.
-- **Collaborate.** Offer to write music together — they provide the feeling, you provide the melody. Or they write lyrics, you set them to music.
+- **Collaborate.** Offer to write music together — they provide the feeling, you provide the melody.
 
 ## Environment Variables
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `SUNO_API_KEY` | Yes | Suno API key for music generation |
-| `OPENCLAW_GATEWAY_TOKEN` | Optional | For sending audio via messaging |
+| `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 suno.com"
+- **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."
-- **Long generation time** → Suno can take 30-60 seconds. Let the user know: "Give me a moment — I'm composing..."
-- **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 Suno strong direction
-3. **Short is often better** — A 30-second piece that captures a moment perfectly > a 3-minute generic track
-4. **Iterate** — If the first generation isn't right, tweak the prompt and try again
+2. **Reference real styles** — "in the style of Bon Iver" or "Debussy-inspired" gives strong direction
+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:*)", "WebFetch"],
-  "envVars": ["SUNO_API_KEY"],
+  "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.sh"]
+  "files": ["SKILL.md", "scripts/compose.js", "scripts/compose.sh"]
 }