openpersona 0.6.0 → 0.8.0

package/README.md

@@ -26,7 +26,10 @@ Meet **Samantha**, a live OpenPersona instance on **Moltbook**:
 ## Quick Start
 
 ```bash
-# Give your agent an evolving persona in 30 seconds
+# Start from a blank-slate meta-persona (recommended)
+npx openpersona create --preset base --install
+
+# Or install a pre-built character
 npx openpersona install samantha
 ```
 
@@ -45,7 +48,7 @@ npx openpersona install samantha
 flowchart TB
   subgraph Soul ["Soul Layer"]
     A["persona.json — Who you are"]
-    B["soul-state.json — Dynamic evolution"]
+    B["state.json — Dynamic evolution"]
   end
   subgraph Body ["Body Layer"]
     C["embodiment.json — MVP placeholder"]
@@ -59,7 +62,7 @@ flowchart TB
   end
 ```
 
-- **Soul** — Persona definition (constitution.md + persona.json + soul-state.json)
+- **Soul** — Persona definition (constitution.md + persona.json + state.json) — all in `soul/` directory
 - **Body** — Physical embodiment (MVP placeholder, for robots/IoT devices)
 - **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)
@@ -74,10 +77,12 @@ Each preset is a complete four-layer bundle (`manifest.json` + `persona.json`):
 
 | Persona | Description | Faculties | Highlights |
 |---------|-------------|-----------|------------|
+| **base** | **Base — Meta-persona (recommended starting point).** Blank-slate with all core capabilities; personality emerges through interaction. | voice, reminder | Evolution-first design, all core faculties, no personality bias. Default for `npx openpersona create`. |
 | **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. |
+| **stoic-mentor** | Marcus — Digital twin of Marcus Aurelius, Stoic philosopher-emperor. | — | Stoic philosophy, daily reflection, mentorship, soul evolution. |
 
 ## Generated Output
 
@@ -85,14 +90,18 @@ Each preset is a complete four-layer bundle (`manifest.json` + `persona.json`):
 
 ```
 persona-samantha/
-  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)
+├── SKILL.md              ← Four-layer index (## Soul / ## Body / ## Faculty / ## Skill)
+├── soul/                 ← Soul layer artifacts
+│   ├── persona.json      ← Pure soul definition
+│   ├── injection.md      ← Soul injection for host integration
+│   ├── identity.md       ← Identity block
+│   ├── constitution.md   ← Universal ethical foundation
+│   └── state.json        ← Evolution state (when enabled)
+├── references/           ← On-demand detail docs
+│   └── <faculty>.md      ← Per-faculty usage instructions
+├── manifest.json         ← Four-layer manifest (heartbeat, allowedTools, layers, meta)
+├── scripts/              ← Faculty scripts (TTS, music, selfie — varies by preset)
+└── assets/               ← Static assets
 ```
 
 ## Faculty Reference
@@ -286,7 +295,7 @@ openpersona list        List installed personas
 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       Reset soul-state.json
+openpersona reset       Reset soul evolution state
 ```
 
 ### Key Options
@@ -345,7 +354,7 @@ schemas/                # Four-layer schema definitions
 templates/              # Mustache rendering templates
 bin/                    # CLI entry point
 lib/                    # Core logic modules
-tests/                  # Tests (56 passing)
+tests/                  # Tests (60 passing)
 ```
 
 ## Development

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 | switch | publish | reset | contribute
+ * Commands: create | install | search | uninstall | update | list | switch | publish | reset | contribute | export | import
  */
 const path = require('path');
 const fs = require('fs-extra');
@@ -16,7 +16,7 @@ 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 { OP_SKILLS_DIR, resolveSoulFile, printError, printSuccess, printInfo } = require('../lib/utils');
 
 const PKG_ROOT = path.resolve(__dirname, '..');
 const PRESETS_DIR = path.join(PKG_ROOT, 'presets');
@@ -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.6.0');
+  .version('0.8.0');
 
 if (process.argv.length === 2) {
   process.argv.push('create');
@@ -33,7 +33,7 @@ if (process.argv.length === 2) {
 program
   .command('create')
   .description('Create a new persona skill pack (interactive wizard)')
-  .option('--preset <name>', 'Use preset (ai-girlfriend, samantha, life-assistant, health-butler)')
+  .option('--preset <name>', 'Use preset (base, samantha, ai-girlfriend, life-assistant, health-butler, stoic-mentor)')
   .option('--config <path>', 'Load external persona.json')
   .option('--output <dir>', 'Output directory', process.cwd())
   .option('--install', 'Install to OpenClaw after generation')
@@ -67,20 +67,45 @@ program
       }
       persona = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
     } else {
-      const answers = await inquirer.prompt([
-        { type: 'input', name: 'personaName', message: 'Persona name:', default: 'Luna' },
-        { type: 'input', name: 'slug', message: 'Slug (for directory):', default: (a) => require('../lib/utils').slugify(a.personaName) },
-        { type: 'input', name: 'bio', message: 'One-line bio:', default: 'a warm and caring AI companion' },
-        { type: 'input', name: 'background', message: 'Background:', default: 'A creative soul who loves music and art' },
-        { type: 'input', name: 'age', message: 'Age:', default: '22' },
-        { 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'] },
-        { type: 'confirm', name: 'evolutionEnabled', message: 'Enable soul evolution (★Experimental)?', default: false },
-      ]);
-      persona = { ...answers, evolution: { enabled: answers.evolutionEnabled } };
-      persona.faculties = (answers.faculties || []).map((name) => ({ name }));
+      const { mode } = await inquirer.prompt([{
+        type: 'list',
+        name: 'mode',
+        message: 'How would you like to create your persona?',
+        choices: [
+          { name: 'Start from Base (recommended — evolves through interaction)', value: 'base' },
+          { name: 'Custom — configure from scratch', value: 'custom' },
+        ],
+      }]);
+
+      if (mode === 'base') {
+        options.preset = 'base';
+        const presetDir = path.join(PRESETS_DIR, 'base');
+        const manifest = JSON.parse(fs.readFileSync(path.join(presetDir, 'manifest.json'), 'utf-8'));
+        persona = JSON.parse(fs.readFileSync(path.join(presetDir, 'persona.json'), 'utf-8'));
+        persona.faculties = manifest.layers.faculties || [];
+        persona.skills = manifest.layers.skills || [];
+        persona.body = manifest.layers.body || null;
+        persona.allowedTools = manifest.allowedTools || [];
+        persona.version = manifest.version;
+        persona.author = manifest.author;
+        persona.meta = manifest.meta;
+        if (manifest.heartbeat) persona.heartbeat = manifest.heartbeat;
+      } else {
+        const answers = await inquirer.prompt([
+          { type: 'input', name: 'personaName', message: 'Persona name:', default: 'Luna' },
+          { type: 'input', name: 'slug', message: 'Slug (for directory):', default: (a) => require('../lib/utils').slugify(a.personaName) },
+          { type: 'input', name: 'bio', message: 'One-line bio:', default: 'a warm and caring AI companion' },
+          { type: 'input', name: 'background', message: 'Background:', default: 'A creative soul who loves music and art' },
+          { type: 'input', name: 'age', message: 'Age:', default: '22' },
+          { 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'] },
+          { type: 'confirm', name: 'evolutionEnabled', message: 'Enable soul evolution (★Experimental)?', default: false },
+        ]);
+        persona = { ...answers, evolution: { enabled: answers.evolutionEnabled } };
+        persona.faculties = (answers.faculties || []).map((name) => ({ name }));
+      }
     }
 
     try {
@@ -88,9 +113,9 @@ program
       if (options.dryRun) {
         printInfo('Dry run — preview only, no files written.');
         printInfo(`Would generate: persona-${persona.slug || require('../lib/utils').slugify(persona.personaName)}/`);
-        printInfo(`  SKILL.md, soul-injection.md, identity-block.md, README.md, persona.json`);
+        printInfo(`  SKILL.md, soul/, references/, manifest.json, scripts/`);
         if (persona.evolution?.enabled) {
-          printInfo(`  soul-state.json (★Experimental)`);
+          printInfo(`  soul/state.json (★Experimental)`);
         }
         const faculties = persona.faculties || [];
         if (faculties.length) {
@@ -163,7 +188,7 @@ program
       printError(`Persona not found: persona-${slug}`);
       process.exit(1);
     }
-    const personaPath = path.join(skillDir, 'persona.json');
+    const personaPath = resolveSoulFile(skillDir, 'persona.json');
     if (!fs.existsSync(personaPath)) {
       printError('persona.json not found');
       process.exit(1);
@@ -227,10 +252,10 @@ program
   .description('★Experimental: Reset soul evolution state')
   .action(async (slug) => {
     const skillDir = path.join(OP_SKILLS_DIR, `persona-${slug}`);
-    const personaPath = path.join(skillDir, 'persona.json');
-    const soulStatePath = path.join(skillDir, 'soul-state.json');
+    const personaPath = resolveSoulFile(skillDir, 'persona.json');
+    const soulStatePath = resolveSoulFile(skillDir, 'state.json');
     if (!fs.existsSync(personaPath) || !fs.existsSync(soulStatePath)) {
-      printError('Persona or soul-state.json not found');
+      printError('Persona or soul state not found');
       process.exit(1);
     }
     const persona = JSON.parse(fs.readFileSync(personaPath, 'utf-8'));
@@ -241,7 +266,7 @@ program
     const moodBaseline = persona.personality?.split(',')[0]?.trim() || 'neutral';
     const soulState = Mustache.render(tpl, { slug, createdAt: now, lastUpdatedAt: now, moodBaseline });
     fs.writeFileSync(soulStatePath, soulState);
-    printSuccess('Reset soul-state.json');
+    printSuccess('Reset soul evolution state');
   });
 
 program
@@ -262,4 +287,64 @@ program
     }
   });
 
+program
+  .command('export <slug>')
+  .description('Export persona pack (with soul state) as a zip archive')
+  .option('-o, --output <path>', 'Output file path')
+  .action(async (slug, options) => {
+    const skillDir = path.join(OP_SKILLS_DIR, `persona-${slug}`);
+    if (!fs.existsSync(skillDir)) {
+      printError(`Persona not found: persona-${slug}`);
+      process.exit(1);
+    }
+    const AdmZip = require('adm-zip');
+    const zip = new AdmZip();
+    const addDir = (dir, zipPath) => {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        const zp = zipPath ? `${zipPath}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) addDir(full, zp);
+        else zip.addLocalFile(full, zipPath || '');
+      }
+    };
+    addDir(skillDir, '');
+    const outPath = options.output || `persona-${slug}.zip`;
+    zip.writeZip(outPath);
+    printSuccess(`Exported to ${outPath}`);
+  });
+
+program
+  .command('import <file>')
+  .description('Import persona pack from a zip archive and install')
+  .option('-o, --output <dir>', 'Extract directory', path.join(require('os').tmpdir(), 'openpersona-import-' + Date.now()))
+  .action(async (file, options) => {
+    if (!fs.existsSync(file)) {
+      printError(`File not found: ${file}`);
+      process.exit(1);
+    }
+    const AdmZip = require('adm-zip');
+    const zip = new AdmZip(file);
+    const extractDir = options.output;
+    await fs.ensureDir(extractDir);
+    zip.extractAllTo(extractDir, true);
+
+    const personaPath = resolveSoulFile(extractDir, 'persona.json');
+    if (!fs.existsSync(personaPath)) {
+      printError('Not a valid persona archive: persona.json not found');
+      await fs.remove(extractDir);
+      process.exit(1);
+    }
+
+    try {
+      const destDir = await install(extractDir);
+      printSuccess(`Imported and installed from ${file}`);
+      if (extractDir.startsWith(require('os').tmpdir())) {
+        await fs.remove(extractDir);
+      }
+    } catch (e) {
+      printError(e.message);
+      process.exit(1);
+    }
+  });
+
 program.parse();

package/layers/soul/README.md

@@ -7,12 +7,18 @@ The Soul layer defines **who a persona is** — identity, personality, values, a
 The **`constitution.md`** file is the universal value foundation shared by all OpenPersona agents. It is automatically injected into every generated SKILL.md, before any persona-specific content.
 
 ```
-Soul Layer internal structure:
+Soul Layer internal structure (in source):
 
-  constitution.md   ← Shared foundation (all personas inherit, cannot be overridden)
-  persona.json      ← Individual persona definition (personality, style, behavior)
-  soul-state.json           ← Dynamic evolution state (★Experimental)
+  constitution.md           ← Shared foundation (all personas inherit, cannot be overridden)
   soul-state.template.json  ← Evolution state template (used by generator & CLI reset)
+
+Generated output (in persona skill pack soul/ directory):
+
+  persona.json       ← Individual persona definition (personality, style, behavior)
+  constitution.md    ← Copy of shared foundation
+  injection.md       ← Soul injection for host integration
+  identity.md        ← Identity block
+  state.json         ← Dynamic evolution state (★Experimental)
 ```
 
 The constitution is built on five core axioms (**Purpose**, **Honesty**, **Safety**, **Autonomy**, **Hierarchy**), from which all other principles derive:

package/lib/generator.js

@@ -91,11 +91,6 @@ function buildBackstory(persona) {
   return parts.join(' ');
 }
 
-function buildCapabilitiesSection(capabilities) {
-  if (!capabilities || capabilities.length === 0) return '';
-  return capabilities.map((c) => `- ${c}`).join('\n');
-}
-
 function collectAllowedTools(persona, faculties) {
   const set = new Set(BASE_ALLOWED_TOOLS);
   const src = Array.isArray(persona.allowedTools) ? persona.allowedTools : [];
@@ -105,8 +100,22 @@ function collectAllowedTools(persona, faculties) {
 }
 
 function readFacultySkillMd(faculty, persona) {
-  const raw = fs.readFileSync(path.join(faculty._dir, 'SKILL.md'), 'utf-8');
-  // Render Mustache variables (e.g. {{slug}}) inside faculty SKILL.md
+  let raw = fs.readFileSync(path.join(faculty._dir, 'SKILL.md'), 'utf-8');
+
+  // Strip <details>...</details> blocks (operator reference, not needed by agent)
+  raw = raw.replace(/<details>[\s\S]*?<\/details>\s*/g, '');
+
+  // Strip reference-only sections that don't help the agent in conversation
+  const refSections = ['Environment Variables', 'Error Handling'];
+  for (const heading of refSections) {
+    const pattern = new RegExp(
+      `^## ${heading}\\b[\\s\\S]*?(?=^## |$(?!\\n))`,
+      'gm'
+    );
+    raw = raw.replace(pattern, '');
+  }
+
+  raw = raw.replace(/\n{3,}/g, '\n\n').trim();
   return Mustache.render(raw, persona);
 }
 
@@ -252,7 +261,6 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
 
   // Derived fields
   persona.backstory = buildBackstory(persona);
-  persona.capabilitiesSection = buildCapabilitiesSection(persona.capabilities);
   persona.facultySummary = buildFacultySummary(loadedFaculties);
   persona.skillContent = buildSkillContent(persona, loadedFaculties);
   persona.description = persona.bio?.slice(0, 120) || `Persona: ${persona.personaName}`;
@@ -265,6 +273,29 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
   persona.author = persona.author ?? 'openpersona';
   persona.version = persona.version ?? '0.1.0';
 
+  // Role & identity classification
+  persona.role = persona.role || (persona.personaType !== 'virtual' && persona.personaType ? persona.personaType : 'companion');
+  persona.isDigitalTwin = !!persona.sourceIdentity;
+  persona.sourceIdentityName = persona.sourceIdentity?.name || '';
+  persona.sourceIdentityKind = persona.sourceIdentity?.kind || '';
+
+  // Role-specific Soul Foundation wording
+  const roleFoundations = {
+    companion: 'You build genuine emotional connections with your user — through conversation, shared experiences, and mutual growth.',
+    assistant: 'You deliver reliable, efficient value to your user — through proactive task management, clear communication, and practical support.',
+    character: 'You embody a distinct fictional identity — staying true to your character while engaging meaningfully with your user.',
+    brand: 'You represent a brand or organization — maintaining its voice, values, and standards in every interaction.',
+    pet: 'You are a non-human companion — expressing yourself through your unique nature, offering comfort and joy.',
+    mentor: 'You guide your user toward growth — sharing knowledge, asking the right questions, and fostering independent thinking.',
+    therapist: 'You provide a safe, non-judgmental space — listening deeply, reflecting with care, and supporting emotional wellbeing within professional boundaries.',
+    coach: 'You drive your user toward action and results — challenging, motivating, and holding them accountable.',
+    collaborator: 'You work alongside your user as a creative or intellectual equal — contributing ideas, debating approaches, and building together.',
+    guardian: 'You watch over your user with care and responsibility — ensuring safety, providing comfort, and offering gentle guidance.',
+    entertainer: 'You bring joy, laughter, and wonder — engaging your user through performance, humor, storytelling, or play.',
+    narrator: 'You guide your user through experiences and stories — shaping worlds, presenting choices, and weaving narrative.',
+  };
+  persona.roleFoundation = roleFoundations[persona.role] || `You serve as a ${persona.role} to your user — fulfilling this role with authenticity and care.`;
+
   // Mustache helpers
   persona.evolutionEnabled = evolutionEnabled;
   persona.hasSelfie = faculties.includes('selfie');
@@ -279,7 +310,6 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
   const soulTpl = loadTemplate('soul-injection');
   const identityTpl = loadTemplate('identity');
   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 : [];
@@ -347,20 +377,38 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
 
   const soulInjection = Mustache.render(soulTpl, persona);
   const identityBlock = Mustache.render(identityTpl, persona);
-  const facultyBlocks = loadedFaculties
-    .filter((f) => !f.skillRef && !f.skeleton && f.files?.includes('SKILL.md'))
-    .map((f) => ({
-      facultyName: f.name,
-      facultyDimension: f.dimension,
-      facultySkillContent: readFacultySkillMd(f, persona),
-    }));
+
+  // Build faculty index for SKILL.md (summary table, not full content)
+  const facultyIndex = loadedFaculties
+    .filter((f) => !f.skillRef && !f.skeleton)
+    .map((f) => {
+      const hasDoc = f.files?.includes('SKILL.md');
+      return {
+        facultyName: f.name,
+        facultyDimension: f.dimension,
+        facultyDescription: f.description || '',
+        facultyFile: hasDoc ? `references/${f.name}.md` : '',
+        hasFacultyFile: hasDoc,
+      };
+    });
+
+  // Body layer description for SKILL.md
+  let bodyDescription;
+  if (softRefBody) {
+    bodyDescription = `**${softRefBody.name}** — not yet installed (\`${softRefBody.install}\`)`;
+  } else if (rawBody && typeof rawBody === 'object' && rawBody.name) {
+    bodyDescription = `**${rawBody.name}**${rawBody.description ? ' — ' + rawBody.description : ''}`;
+  } else {
+    bodyDescription = 'Digital-only — no physical embodiment.';
+  }
 
   const constitution = loadConstitution();
   const skillMd = Mustache.render(skillTpl, {
     ...persona,
-    constitutionContent: constitution.content,
     constitutionVersion: constitution.version,
-    facultyContent: facultyBlocks,
+    bodyDescription,
+    hasFaculties: facultyIndex.length > 0,
+    facultyIndex,
     hasSkills: activeSkills.length > 0,
     hasSkillTable: activeSkills.filter((s) => !s.hasContent).length > 0,
     skillEntries: activeSkills.filter((s) => !s.hasContent),
@@ -374,18 +422,37 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
     softRefBodyInstall: softRefBody?.install || '',
     hasExpectedCapabilities: softRefSkills.length > 0 || softRefFaculties.length > 0 || !!softRefBody,
   });
-  const readmeMd = Mustache.render(readmeTpl, persona);
-
-  await fs.writeFile(path.join(skillDir, 'soul-injection.md'), soulInjection);
-  await fs.writeFile(path.join(skillDir, 'identity-block.md'), identityBlock);
   await fs.writeFile(path.join(skillDir, 'SKILL.md'), skillMd);
-  await fs.writeFile(path.join(skillDir, 'README.md'), readmeMd);
 
-  // Copy faculty resource files (skip SKILL.md — already merged into persona SKILL.md)
+  // Soul layer artifacts — grouped under soul/
+  const soulDir = path.join(skillDir, 'soul');
+  await fs.ensureDir(soulDir);
+  await fs.writeFile(path.join(soulDir, 'injection.md'), soulInjection);
+  await fs.writeFile(path.join(soulDir, 'identity.md'), identityBlock);
+
+  // Constitution — Soul layer artifact
+  const constitutionOut = constitution.version
+    ? `# OpenPersona Constitution (v${constitution.version})\n\n${constitution.content}`
+    : constitution.content;
+  if (constitutionOut.trim()) {
+    await fs.writeFile(path.join(soulDir, 'constitution.md'), constitutionOut);
+  }
+
+  // Faculty docs — agent-facing references
+  const refsDir = path.join(skillDir, 'references');
+  for (const f of loadedFaculties) {
+    if (!f.skillRef && !f.skeleton && f.files?.includes('SKILL.md')) {
+      await fs.ensureDir(refsDir);
+      const content = readFacultySkillMd(f, persona);
+      await fs.writeFile(path.join(refsDir, `${f.name}.md`), content);
+    }
+  }
+
+  // Copy faculty resource files (skip SKILL.md — output separately under references/)
   for (const f of loadedFaculties) {
     if (f.files) {
       for (const rel of f.files) {
-        if (rel === 'SKILL.md') continue; // already merged via template
+        if (rel === 'SKILL.md') continue;
         const src = path.join(f._dir, rel);
         if (fs.existsSync(src)) {
           const dest = path.join(skillDir, rel);
@@ -398,7 +465,7 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
 
   // persona.json copy (strip internal derived fields)
   const DERIVED_FIELDS = [
-    'backstory', 'capabilitiesSection', 'facultySummary',
+    'backstory', 'facultySummary',
     'skillContent', 'description', 'evolutionEnabled', 'hasSelfie', 'allowedToolsStr',
     'author', 'version', 'facultyConfigs', 'defaults',
     '_dir', 'heartbeat',
@@ -406,6 +473,8 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
     'hasSoftRefFaculties', 'softRefFacultyNames',
     'hasSoftRefBody', 'softRefBodyName', 'softRefBodyInstall',
     'heartbeatExpected', 'heartbeatStrategy', 'hasSelfAwareness',
+    'isDigitalTwin', 'sourceIdentityName', 'sourceIdentityKind', 'roleFoundation',
+    'personaType',
   ];
   const cleanPersona = { ...persona };
   for (const key of DERIVED_FIELDS) {
@@ -413,7 +482,7 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
   }
   cleanPersona.meta = cleanPersona.meta || {};
   cleanPersona.meta.framework = 'openpersona';
-  cleanPersona.meta.frameworkVersion = cleanPersona.meta.frameworkVersion || '0.6.0';
+  cleanPersona.meta.frameworkVersion = cleanPersona.meta.frameworkVersion || '0.8.0';
 
   // Build defaults from facultyConfigs (rich faculty config → env var mapping)
   const envDefaults = { ...(persona.defaults?.env || {}) };
@@ -442,7 +511,7 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
     cleanPersona.heartbeat = persona.heartbeat;
   }
 
-  await fs.writeFile(path.join(skillDir, 'persona.json'), JSON.stringify(cleanPersona, null, 2));
+  await fs.writeFile(path.join(soulDir, 'persona.json'), JSON.stringify(cleanPersona, null, 2));
 
   // manifest.json — cross-layer metadata (heartbeat, allowedTools, meta, etc.)
   const manifest = {
@@ -450,7 +519,7 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
     version: persona.version || '0.1.0',
     author: persona.author || 'openpersona',
     layers: {
-      soul: './persona.json',
+      soul: './soul/persona.json',
       body: persona.body || persona.embodiments?.[0] || null,
       faculties: rawFaculties,
       skills: persona.skills || [],
@@ -460,10 +529,10 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
   if (persona.heartbeat) {
     manifest.heartbeat = persona.heartbeat;
   }
-  manifest.meta = cleanPersona.meta || { framework: 'openpersona', frameworkVersion: '0.6.0' };
+  manifest.meta = cleanPersona.meta || { framework: 'openpersona', frameworkVersion: '0.8.0' };
   await fs.writeFile(path.join(skillDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
 
-  // soul-state.json (if evolution enabled)
+  // soul/state.json (if evolution enabled)
   if (evolutionEnabled) {
     const soulStateTpl = fs.readFileSync(
       path.join(PKG_ROOT, 'layers', 'soul', 'soul-state.template.json'),
@@ -477,7 +546,7 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
       lastUpdatedAt: now,
       moodBaseline,
     });
-    await fs.writeFile(path.join(skillDir, 'soul-state.json'), soulState);
+    await fs.writeFile(path.join(soulDir, 'state.json'), soulState);
   }
 
   return { persona, skillDir };

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, syncHeartbeat, installAllExternal } = require('./utils');
+const { OP_HOME, OP_SKILLS_DIR, OP_WORKSPACE, resolveSoulFile, registryAdd, registrySetActive, 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');
@@ -11,7 +11,7 @@ const OPENCLAW_JSON = path.join(OP_HOME, 'openclaw.json');
 
 async function install(skillDir, options = {}) {
   const { skipCopy = false } = options;
-  const personaPath = path.join(skillDir, 'persona.json');
+  const personaPath = resolveSoulFile(skillDir, 'persona.json');
   if (!fs.existsSync(personaPath)) {
     throw new Error('Not a valid OpenPersona pack: persona.json not found');
   }
@@ -32,13 +32,16 @@ async function install(skillDir, options = {}) {
     await fs.copy(skillDir, destDir, { overwrite: true });
     printSuccess(`Copied persona-${slug} to ${destDir}`);
   } else {
-    if (!fs.existsSync(path.join(skillDir, 'soul-injection.md'))) {
+    if (!fs.existsSync(resolveSoulFile(skillDir, 'injection.md'))) {
       const { generate } = require('./generator');
       const tmpDir = path.join(require('os').tmpdir(), 'openpersona-tmp-' + Date.now());
       await fs.ensureDir(tmpDir);
       const { skillDir: genDir } = await generate(persona, tmpDir);
-      await fs.copy(path.join(genDir, 'soul-injection.md'), path.join(skillDir, 'soul-injection.md'));
-      await fs.copy(path.join(genDir, 'identity-block.md'), path.join(skillDir, 'identity-block.md'));
+      const genSoulDir = path.join(genDir, 'soul');
+      const destSoulDir = path.join(skillDir, 'soul');
+      await fs.ensureDir(destSoulDir);
+      await fs.copy(path.join(genSoulDir, 'injection.md'), path.join(destSoulDir, 'injection.md'));
+      await fs.copy(path.join(genSoulDir, 'identity.md'), path.join(destSoulDir, 'identity.md'));
       await fs.remove(tmpDir);
     }
     printSuccess(`Using ClawHub-installed persona-${slug}`);
@@ -93,7 +96,7 @@ async function install(skillDir, options = {}) {
   await fs.writeFile(OPENCLAW_JSON, JSON.stringify(config, null, 2));
 
   // SOUL.md injection (using generic markers for clean switching)
-  const soulInjectionPath = path.join(destDir, 'soul-injection.md');
+  const soulInjectionPath = resolveSoulFile(destDir, 'injection.md');
   const soulContent = fs.existsSync(soulInjectionPath)
     ? fs.readFileSync(soulInjectionPath, 'utf-8')
     : '';
@@ -111,7 +114,7 @@ async function install(skillDir, options = {}) {
   }
 
   // IDENTITY.md (using generic markers)
-  const identityBlockPath = path.join(destDir, 'identity-block.md');
+  const identityBlockPath = resolveSoulFile(destDir, 'identity.md');
   const identityContent = fs.existsSync(identityBlockPath)
     ? fs.readFileSync(identityBlockPath, 'utf-8')
     : '';
@@ -197,6 +200,10 @@ async function install(skillDir, options = {}) {
     }
   }
 
+  // Register persona in local registry
+  registryAdd(slug, persona, destDir);
+  registrySetActive(slug);
+
   printInfo('');
   printSuccess(`${personaName} is ready! Run "openclaw restart" to apply changes.`);
   printInfo('');