openpersona 0.4.0 → 0.6.0

package/README.md

@@ -1,32 +1,51 @@
-# OpenPersona
+# OpenPersona 🦞
 
-An open four-layer agent framework: **Soul / Body / Faculty / Skill**. Create, compose, and orchestrate agent 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"]
@@ -36,17 +55,14 @@ flowchart TB
     E["cognition: reminder"]
   end
   subgraph Skill ["Skill Layer"]
-    F["ClawHub / skills.sh integrations"]
+    F["Local definitions + ClawHub / skills.sh"]
   end
 ```
 
-- **Soul** — Persona definition (constitution.md + 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 (ElevenLabs)
-  - **Sense** — (planned: hearing/STT, vision)
-  - **Cognition** — reminder
-- **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
 
@@ -58,70 +74,33 @@ 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 | 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). |
+| **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 (ElevenLabs)
-```
-
-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 (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 | `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` |
+| **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 | — |
 
@@ -188,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
 
@@ -255,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
@@ -291,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
@@ -349,12 +340,12 @@ layers/                 # Shared building blocks (four-layer module pool)
     voice/              #     expression — TTS voice synthesis
     music/              #     expression — AI music composition (ElevenLabs)
     reminder/           #     cognition — reminders and task management
-  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 (56 passing)
 ```
 
 ## Development

package/bin/cli.js

@@ -24,7 +24,7 @@ const PRESETS_DIR = path.join(PKG_ROOT, 'presets');
 program
   .name('openpersona')
   .description('OpenPersona - Create, manage, and orchestrate agent personas')
-  .version('0.4.0');
+  .version('0.6.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;

package/layers/skills/README.md

@@ -1,33 +1,62 @@
-# Skill Layer — Shared Modules
+# Skills Layer
 
-Pre-built skill templates and scaffolds for persona capabilities.
+This directory holds **local skill definitions** — reusable skill packs that any persona can reference by name in its `manifest.json`.
 
-## MVP Status
+## Structure
 
-Currently empty. The Skill layer primarily integrates external skills from [ClawHub](https://clawhub.com) and [skills.sh](https://skills.sh) via `manifest.json` references.
+```
+layers/skills/
+  {skill-name}/
+    skill.json    ← Metadata: name, description, allowedTools, triggers
+    SKILL.md      ← Behavior guide for the AI agent
+```
+
+## How It Works
+
+When a persona's `manifest.json` declares a skill by name:
+
+```json
+{ "name": "weather" }
+```
+
+The generator resolves it through this chain:
+
+1. **Local definition** — `layers/skills/weather/skill.json` (if exists, use its metadata + SKILL.md content)
+2. **Inline fields** — `description`, `trigger` written directly in manifest
+3. **Empty fallback** — skill name only, no description (Agent judges usage by name alone)
 
-## Roadmap
+## Adding a Skill
 
-- **Skill templates** — Scaffolds for common skill patterns (e.g., data-tracking, API-integration)
-- **Skill bundles** — Curated skill combinations for specific persona types (e.g., "companion-bundle", "assistant-bundle")
+Skills here are **framework-curated capabilities**, not necessarily self-implemented. A skill can:
 
-## How Skills Work
+- Be a full local implementation (skill.json + SKILL.md)
+- Be a thin wrapper referencing external tools
+- Adapt an existing market skill to the OpenPersona four-layer model
 
-Skills are declared in `presets/*/manifest.json` under `layers.skills`:
+### Required: `skill.json`
 
 ```json
 {
-  "layers": {
-    "skills": {
-      "clawhub": ["some-skill-slug"],
-      "skillssh": ["owner/repo"]
-    }
-  }
+  "name": "weather",
+  "description": "Query current weather conditions and forecasts",
+  "allowedTools": ["WebFetch", "Bash(curl:*)"],
+  "triggers": ["weather", "forecast", "outdoor plans"]
 }
 ```
 
-The installer automatically runs `npx clawhub install` or `npx skills add` for each declared skill.
+### Optional: `SKILL.md`
+
+Detailed behavior instructions injected into the generated persona SKILL.md as a full section (instead of a table row).
+
+## Relationship to Other Layers
+
+All four layers are categories of capabilities:
 
-## Contributing
+| Layer | What it provides |
+|-------|-----------------|
+| Soul | Identity, personality, ethical boundaries |
+| Body | Physical/virtual embodiment |
+| Faculty | Perception & expression (voice, selfie, music) |
+| **Skill** | **Actions the agent can take** |
 
-To add a shared skill template, create a directory here with a SKILL.md and any supporting files.
+Skills declared in `manifest.json` can reference local definitions here, or exist purely as inline declarations — the framework handles both.

package/lib/generator.js

@@ -9,6 +9,7 @@ const { resolvePath, printError } = require('./utils');
 const PKG_ROOT = path.resolve(__dirname, '..');
 const TEMPLATES_DIR = path.join(PKG_ROOT, 'templates');
 const FACULTIES_DIR = path.join(PKG_ROOT, 'layers', 'faculties');
+const SKILLS_DIR = path.join(PKG_ROOT, 'layers', 'skills');
 const CONSTITUTION_PATH = path.join(PKG_ROOT, 'layers', 'soul', 'constitution.md');
 
 const BASE_ALLOWED_TOOLS = ['Bash(openclaw:*)', 'Read', 'Write'];
@@ -60,6 +61,28 @@ function loadFaculty(name) {
   return faculty;
 }
 
+/**
+ * Load a skill definition from layers/skills/{name}/.
+ * Returns the full skill object if found, or null if not found (fallback to inline).
+ */
+function loadSkill(name) {
+  const skillDir = path.join(SKILLS_DIR, name);
+  const skillJsonPath = path.join(skillDir, 'skill.json');
+  if (!fs.existsSync(skillJsonPath)) {
+    return null; // No local definition — use inline manifest fields
+  }
+  const skill = JSON.parse(fs.readFileSync(skillJsonPath, 'utf-8'));
+  skill._dir = skillDir;
+
+  // Load SKILL.md content if available
+  const skillMdPath = path.join(skillDir, 'SKILL.md');
+  if (fs.existsSync(skillMdPath)) {
+    skill._content = fs.readFileSync(skillMdPath, 'utf-8');
+  }
+
+  return skill;
+}
+
 function buildBackstory(persona) {
   const parts = [];
   parts.push(`You are ${persona.personaName}, ${persona.bio}.`);
@@ -203,8 +226,29 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
     persona.facultyConfigs = facultyConfigs;
   }
 
+  // Body layer — detect soft-ref (declared with install but not locally available)
+  const rawBody = persona.body || persona.embodiments?.[0] || null;
+  const softRefBody = rawBody && typeof rawBody === 'object' && rawBody.install
+    ? { name: rawBody.name || 'body', install: rawBody.install }
+    : null;
+
   const faculties = facultyNames;
-  const loadedFaculties = faculties.map((name) => loadFaculty(name));
+  // Load faculties — external ones (with install) may not exist locally yet
+  const loadedFaculties = [];
+  const softRefFaculties = [];
+  for (let i = 0; i < faculties.length; i++) {
+    const name = faculties[i];
+    const entry = rawFaculties[i];
+    if (entry.install) {
+      try {
+        loadedFaculties.push(loadFaculty(name));
+      } catch {
+        softRefFaculties.push({ name, install: entry.install });
+      }
+    } else {
+      loadedFaculties.push(loadFaculty(name));
+    }
+  }
 
   // Derived fields
   persona.backstory = buildBackstory(persona);
@@ -237,6 +281,70 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
   const skillTpl = loadTemplate('skill');
   const readmeTpl = loadTemplate('readme');
 
+  // Skill layer — resolve before template rendering so soul-injection can reference soft-ref state
+  const rawSkills = Array.isArray(persona.skills) ? persona.skills : [];
+  const validSkills = rawSkills.filter((s) => s && typeof s === 'object' && s.name);
+
+  const skillCache = new Map();
+  for (const s of validSkills) {
+    if (!skillCache.has(s.name)) {
+      skillCache.set(s.name, loadSkill(s.name));
+    }
+  }
+
+  const resolvedSkills = validSkills.map((s) => {
+    const local = skillCache.get(s.name);
+    const hasInstall = !!s.install;
+    const isResolved = !!local;
+
+    let status;
+    if (isResolved) {
+      status = 'resolved';
+    } else if (hasInstall) {
+      status = 'soft-ref';
+    } else {
+      status = 'inline-only';
+    }
+
+    return {
+      name: s.name,
+      description: local?.description || s.description || '',
+      trigger: local?.triggers?.join(', ') || s.trigger || '',
+      hasContent: !!local?._content,
+      content: local?._content || '',
+      status,
+      install: s.install || '',
+      isSoftRef: status === 'soft-ref',
+    };
+  });
+
+  const activeSkills = resolvedSkills.filter((s) => !s.isSoftRef);
+  const softRefSkills = resolvedSkills.filter((s) => s.isSoftRef);
+
+  // Collect allowed tools from skills with local definitions
+  for (const [, local] of skillCache) {
+    if (local?.allowedTools) {
+      local.allowedTools.forEach((t) => {
+        if (!persona.allowedTools.includes(t)) {
+          persona.allowedTools.push(t);
+        }
+      });
+    }
+  }
+  persona.allowedToolsStr = persona.allowedTools.join(' ');
+
+  // Self-Awareness System — unified gap detection across all layers
+  persona.hasSoftRefSkills = softRefSkills.length > 0;
+  persona.softRefSkillNames = softRefSkills.map((s) => s.name).join(', ');
+  persona.hasSoftRefFaculties = softRefFaculties.length > 0;
+  persona.softRefFacultyNames = softRefFaculties.map((f) => f.name).join(', ');
+  persona.hasSoftRefBody = !!softRefBody;
+  persona.softRefBodyName = softRefBody?.name || '';
+  persona.softRefBodyInstall = softRefBody?.install || '';
+  persona.heartbeatExpected = persona.heartbeat?.enabled === true;
+  persona.heartbeatStrategy = persona.heartbeat?.strategy || 'smart';
+  persona.hasSelfAwareness = persona.hasSoftRefSkills || persona.hasSoftRefFaculties || persona.hasSoftRefBody || persona.heartbeatExpected;
+
   const soulInjection = Mustache.render(soulTpl, persona);
   const identityBlock = Mustache.render(identityTpl, persona);
   const facultyBlocks = loadedFaculties
@@ -253,6 +361,18 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
     constitutionContent: constitution.content,
     constitutionVersion: constitution.version,
     facultyContent: facultyBlocks,
+    hasSkills: activeSkills.length > 0,
+    hasSkillTable: activeSkills.filter((s) => !s.hasContent).length > 0,
+    skillEntries: activeSkills.filter((s) => !s.hasContent),
+    skillBlocks: activeSkills.filter((s) => s.hasContent),
+    hasSoftRefSkills: softRefSkills.length > 0,
+    softRefSkills,
+    hasSoftRefFaculties: softRefFaculties.length > 0,
+    softRefFaculties,
+    hasSoftRefBody: !!softRefBody,
+    softRefBodyName: softRefBody?.name || '',
+    softRefBodyInstall: softRefBody?.install || '',
+    hasExpectedCapabilities: softRefSkills.length > 0 || softRefFaculties.length > 0 || !!softRefBody,
   });
   const readmeMd = Mustache.render(readmeTpl, persona);
 
@@ -282,6 +402,10 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
     'skillContent', 'description', 'evolutionEnabled', 'hasSelfie', 'allowedToolsStr',
     'author', 'version', 'facultyConfigs', 'defaults',
     '_dir', 'heartbeat',
+    'hasSoftRefSkills', 'softRefSkillNames',
+    'hasSoftRefFaculties', 'softRefFacultyNames',
+    'hasSoftRefBody', 'softRefBodyName', 'softRefBodyInstall',
+    'heartbeatExpected', 'heartbeatStrategy', 'hasSelfAwareness',
   ];
   const cleanPersona = { ...persona };
   for (const key of DERIVED_FIELDS) {
@@ -289,7 +413,7 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
   }
   cleanPersona.meta = cleanPersona.meta || {};
   cleanPersona.meta.framework = 'openpersona';
-  cleanPersona.meta.frameworkVersion = cleanPersona.meta.frameworkVersion || '0.4.0';
+  cleanPersona.meta.frameworkVersion = cleanPersona.meta.frameworkVersion || '0.6.0';
 
   // Build defaults from facultyConfigs (rich faculty config → env var mapping)
   const envDefaults = { ...(persona.defaults?.env || {}) };
@@ -304,9 +428,9 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
       } else if (fname === 'selfie') {
         if (cfg.apiKey) envDefaults.FAL_KEY = cfg.apiKey;
       } else if (fname === 'music') {
-                // Music shares ELEVENLABS_API_KEY with voice — no extra key needed
-                if (cfg.apiKey) envDefaults.ELEVENLABS_API_KEY = cfg.apiKey;
-              }
+        // Music shares ELEVENLABS_API_KEY with voice — no extra key needed
+        if (cfg.apiKey) envDefaults.ELEVENLABS_API_KEY = cfg.apiKey;
+      }
     }
   }
   if (Object.keys(envDefaults).length > 0) {
@@ -320,6 +444,25 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
 
   await fs.writeFile(path.join(skillDir, 'persona.json'), JSON.stringify(cleanPersona, null, 2));
 
+  // manifest.json — cross-layer metadata (heartbeat, allowedTools, meta, etc.)
+  const manifest = {
+    name: persona.slug,
+    version: persona.version || '0.1.0',
+    author: persona.author || 'openpersona',
+    layers: {
+      soul: './persona.json',
+      body: persona.body || persona.embodiments?.[0] || null,
+      faculties: rawFaculties,
+      skills: persona.skills || [],
+    },
+    allowedTools: cleanPersona.allowedTools || [],
+  };
+  if (persona.heartbeat) {
+    manifest.heartbeat = persona.heartbeat;
+  }
+  manifest.meta = cleanPersona.meta || { framework: 'openpersona', frameworkVersion: '0.6.0' };
+  await fs.writeFile(path.join(skillDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
+
   // soul-state.json (if evolution enabled)
   if (evolutionEnabled) {
     const soulStateTpl = fs.readFileSync(

package/lib/installer.js

@@ -3,7 +3,7 @@
  */
 const path = require('path');
 const fs = require('fs-extra');
-const { OP_HOME, OP_SKILLS_DIR, OP_WORKSPACE, printError, printWarning, printSuccess, printInfo } = require('./utils');
+const { OP_HOME, OP_SKILLS_DIR, OP_WORKSPACE, printError, printWarning, printSuccess, printInfo, syncHeartbeat, installAllExternal } = require('./utils');
 
 const SOUL_PATH = path.join(OP_WORKSPACE, 'SOUL.md');
 const IDENTITY_PATH = path.join(OP_WORKSPACE, 'IDENTITY.md');
@@ -80,6 +80,16 @@ async function install(skillDir, options = {}) {
       val.active = (key === `persona-${slug}`);
     }
   }
+
+  // Sync heartbeat from persona's manifest into global config
+  const manifestPath = path.join(destDir, 'manifest.json');
+  const { synced, heartbeat } = syncHeartbeat(config, manifestPath);
+  if (synced) {
+    printSuccess(`Heartbeat synced: strategy=${heartbeat.strategy}, maxDaily=${heartbeat.maxDaily}`);
+  } else {
+    printInfo('Heartbeat disabled (persona has no heartbeat config)');
+  }
+
   await fs.writeFile(OPENCLAW_JSON, JSON.stringify(config, null, 2));
 
   // SOUL.md injection (using generic markers for clean switching)
@@ -119,34 +129,13 @@ async function install(skillDir, options = {}) {
     printSuccess('Updated IDENTITY.md');
   }
 
-  // Install external skills (skills.clawhub, skills.skillssh)
-  // Security: validate skill names to prevent shell injection
-  const SAFE_SKILL_NAME = /^[a-zA-Z0-9@][a-zA-Z0-9@/_.-]*$/;
-  const { execSync } = require('child_process');
-  const clawhub = persona.skills?.clawhub || [];
-  const skillssh = persona.skills?.skillssh || [];
-  for (const s of clawhub) {
-    if (!SAFE_SKILL_NAME.test(s)) {
-      printWarning(`Skipping invalid ClawHub skill name: ${s}`);
-      continue;
-    }
-    try {
-      execSync(`npx clawhub@latest install ${s}`, { stdio: 'inherit' });
-      printSuccess(`Installed ClawHub skill: ${s}`);
-    } catch (e) {
-      printWarning(`Failed to install ClawHub skill ${s}: ${e.message}`);
-    }
-  }
-  for (const s of skillssh) {
-    if (!SAFE_SKILL_NAME.test(s)) {
-      printWarning(`Skipping invalid skills.sh name: ${s}`);
-      continue;
-    }
+  // Install external dependencies across all four layers (read from manifest, not persona.json)
+  if (fs.existsSync(manifestPath)) {
     try {
-      execSync(`npx skills add ${s}`, { stdio: 'inherit' });
-      printSuccess(`Installed skills.sh: ${s}`);
-    } catch (e) {
-      printWarning(`Failed to install skills.sh ${s}: ${e.message}`);
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+      installAllExternal(manifest.layers || {});
+    } catch {
+      // Malformed manifest — skip external installs
     }
   }