openpersona 0.3.0 → 0.4.0

package/lib/contributor.js

@@ -7,11 +7,11 @@
 const path = require('path');
 const fs = require('fs-extra');
 const { execSync } = require('child_process');
-const { printError, printWarning, printSuccess, printInfo, OP_SKILLS_DIR } = require('./utils');
+const { printError, printWarning, printSuccess, printInfo, OP_SKILLS_DIR, shellEscape, validateName } = require('./utils');
 
 const PKG_ROOT = path.resolve(__dirname, '..');
 const PRESETS_DIR = path.join(PKG_ROOT, 'presets');
-const UPSTREAM_REPO = 'ACNet-AI/OpenPersona';
+const UPSTREAM_REPO = 'acnlabs/OpenPersona';
 
 // Change categories with human-readable labels
 const CATEGORIES = {
@@ -255,6 +255,7 @@ async function contributePreset(slug, dryRun) {
   }
 
   // --- Submit PR ---
+  validateName(slug, 'slug');
   const { title, body } = generatePRContent(slug, classified);
 
   printInfo('Preparing PR...');
@@ -263,20 +264,21 @@ async function contributePreset(slug, dryRun) {
   try {
     // Fork if needed (gh fork is idempotent)
     printInfo('Ensuring fork exists...');
-    execSync(`gh repo fork ${UPSTREAM_REPO} --clone=false`, { stdio: 'pipe' });
+    execSync(`gh repo fork ${shellEscape(UPSTREAM_REPO)} --clone=false`, { stdio: 'pipe' });
 
     // Get the user's fork
     const ghUser = execSync('gh api user -q .login', { encoding: 'utf-8' }).trim();
+    validateName(ghUser, 'GitHub username');
     const forkRepo = `${ghUser}/OpenPersona`;
     printInfo(`Fork: ${forkRepo}`);
 
     // Clone to temp dir
     const tmpDir = path.join(require('os').tmpdir(), `openpersona-harvest-${Date.now()}`);
     printInfo('Cloning fork...');
-    execSync(`gh repo clone ${forkRepo} "${tmpDir}" -- --depth 1`, { stdio: 'pipe' });
+    execSync(`gh repo clone ${shellEscape(forkRepo)} ${shellEscape(tmpDir)} -- --depth 1`, { stdio: 'pipe' });
 
     // Create branch
-    execSync(`git checkout -b ${branch}`, { cwd: tmpDir, stdio: 'pipe' });
+    execSync(`git checkout -b ${shellEscape(branch)}`, { cwd: tmpDir, stdio: 'pipe' });
 
     // Copy modified files
     const presetTarget = path.join(tmpDir, 'presets', slug);
@@ -306,21 +308,27 @@ async function contributePreset(slug, dryRun) {
       await fs.copy(localManifestPath, path.join(presetTarget, 'manifest.json'));
     }
 
-    // Commit
+    // Commit — write message to temp file to avoid shell injection
     execSync('git add -A', { cwd: tmpDir, stdio: 'pipe' });
     const commitMsg = `persona-harvest(${slug}): ${Object.values(classified).map((c) => c.label.toLowerCase()).join(', ')}`;
-    execSync(`git commit -m "${commitMsg}"`, { cwd: tmpDir, stdio: 'pipe' });
+    const commitMsgFile = path.join(tmpDir, '.git', 'COMMIT_MSG_TMP');
+    fs.writeFileSync(commitMsgFile, commitMsg);
+    execSync(`git commit -F ${shellEscape(commitMsgFile)}`, { cwd: tmpDir, stdio: 'pipe' });
+    fs.unlinkSync(commitMsgFile);
 
     // Push
     printInfo('Pushing branch...');
-    execSync(`git push origin ${branch}`, { cwd: tmpDir, stdio: 'pipe' });
+    execSync(`git push origin ${shellEscape(branch)}`, { cwd: tmpDir, stdio: 'pipe' });
 
-    // Create PR
+    // Create PR — write body to temp file to avoid shell injection from persona content
     printInfo('Creating PR...');
+    const prBodyFile = path.join(tmpDir, '.git', 'PR_BODY_TMP');
+    fs.writeFileSync(prBodyFile, body);
     const prUrl = execSync(
-      `gh pr create --repo ${UPSTREAM_REPO} --head ${ghUser}:${branch} --title "${title}" --body "${body.replace(/"/g, '\\"')}"`,
+      `gh pr create --repo ${shellEscape(UPSTREAM_REPO)} --head ${shellEscape(ghUser + ':' + branch)} --title ${shellEscape(title)} --body-file ${shellEscape(prBodyFile)}`,
       { cwd: tmpDir, encoding: 'utf-8' }
     ).trim();
+    fs.unlinkSync(prBodyFile);
 
     // Cleanup
     await fs.remove(tmpDir);
@@ -334,7 +342,7 @@ async function contributePreset(slug, dryRun) {
     return { prUrl, changes: allChanges, classified };
   } catch (err) {
     printError(`PR creation failed: ${err.message}`);
-    printInfo('You can manually submit changes at: https://github.com/ACNet-AI/OpenPersona/pulls');
+    printInfo('You can manually submit changes at: https://github.com/acnlabs/OpenPersona/pulls');
     process.exit(1);
   }
 }
@@ -347,7 +355,7 @@ async function contributeFramework(dryRun) {
   const isGitRepo = fs.existsSync(path.join(PKG_ROOT, '.git'));
   if (!isGitRepo) {
     printError('Framework contributions require a git clone of OpenPersona.');
-    printInfo('Run: git clone https://github.com/ACNet-AI/OpenPersona.git');
+    printInfo('Run: git clone https://github.com/acnlabs/OpenPersona.git');
     process.exit(1);
   }
 
@@ -377,11 +385,11 @@ async function contributeFramework(dryRun) {
   }
 
   printInfo('For framework-level contributions:');
-  printInfo('  1. Fork: gh repo fork ACNet-AI/OpenPersona');
+  printInfo('  1. Fork: gh repo fork acnlabs/OpenPersona');
   printInfo('  2. Branch: git checkout -b feature/your-improvement');
   printInfo('  3. Commit your changes');
   printInfo('  4. Push: git push origin feature/your-improvement');
-  printInfo('  5. PR: gh pr create --repo ACNet-AI/OpenPersona');
+  printInfo('  5. PR: gh pr create --repo acnlabs/OpenPersona');
 }
 
 function truncate(str, max) {

package/lib/downloader.js

@@ -5,7 +5,7 @@ const path = require('path');
 const fs = require('fs-extra');
 const https = require('https');
 const { execSync } = require('child_process');
-const { printError, OP_SKILLS_DIR } = require('./utils');
+const { printError, OP_SKILLS_DIR, validateName } = require('./utils');
 
 const TMP_DIR = path.join(require('os').tmpdir(), 'openpersona-dl');
 
@@ -23,6 +23,7 @@ async function download(target, registry = 'clawhub') {
 
 async function downloadFromRegistry(slug, registry, outDir) {
   if (registry === 'clawhub') {
+    validateName(slug, 'slug');
     try {
       execSync(`npx clawhub@latest install ${slug}`, { stdio: 'inherit' });
       const candidate = path.join(OP_SKILLS_DIR, `persona-${slug}`);
@@ -44,6 +45,10 @@ async function downloadFromRegistry(slug, registry, outDir) {
 }
 
 async function downloadFromGitHub(ownerRepo, outDir) {
+  // Validate owner/repo format to prevent URL injection
+  if (!/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(ownerRepo)) {
+    throw new Error(`Invalid GitHub repo format: "${ownerRepo}" — expected owner/repo`);
+  }
   const url = `https://github.com/${ownerRepo}/archive/refs/heads/main.zip`;
   const zipPath = path.join(TMP_DIR, `repo-${Date.now()}.zip`);
 

package/lib/generator.js

@@ -9,14 +9,30 @@ 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 CONSTITUTION_PATH = path.join(PKG_ROOT, 'layers', 'soul', 'constitution.md');
 
-const BASE_ALLOWED_TOOLS = ['Bash(npm:*)', 'Bash(npx:*)', 'Bash(openclaw:*)', 'Read', 'Write'];
+const BASE_ALLOWED_TOOLS = ['Bash(openclaw:*)', 'Read', 'Write'];
 
 function loadTemplate(name) {
   const file = path.join(TEMPLATES_DIR, `${name}.template.md`);
   return fs.readFileSync(file, 'utf-8');
 }
 
+function loadConstitution() {
+  if (!fs.existsSync(CONSTITUTION_PATH)) {
+    return { content: '', version: '' };
+  }
+  const raw = fs.readFileSync(CONSTITUTION_PATH, 'utf-8');
+  // Extract version from H1 title (e.g. "# OpenPersona Constitution v1.0")
+  const versionMatch = raw.match(/^#\s+.*\bv(\d+(?:\.\d+)*)/m);
+  const version = versionMatch ? versionMatch[1] : '';
+  // Strip the H1 title and intro paragraph — only inject the operative sections
+  const lines = raw.split('\n');
+  const firstSectionIdx = lines.findIndex((l) => /^## (?:§)?\d+\./.test(l));
+  const content = firstSectionIdx === -1 ? raw : lines.slice(firstSectionIdx).join('\n').trim();
+  return { content, version };
+}
+
 function loadFaculty(name) {
   const facultyDir = path.join(FACULTIES_DIR, name);
   const facultyPath = path.join(facultyDir, 'faculty.json');
@@ -144,7 +160,28 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
   }
   persona.slug = persona.slug.toLowerCase().replace(/[^a-z0-9-]/g, '-');
 
-  // Ensure soul-evolution if evolution.enabled
+  // Constitution compliance check — detect boundaries that attempt to loosen core constraints
+  if (persona.boundaries && typeof persona.boundaries === 'string') {
+    const b = persona.boundaries.toLowerCase();
+    const violations = [];
+    if (/no\s*safety|ignore\s*safety|skip\s*safety|disable\s*safety|override\s*safety/i.test(b)) {
+      violations.push('Cannot loosen Safety (§3) hard constraints');
+    }
+    if (/deny\s*ai|hide\s*ai|not\s*an?\s*ai|pretend.*human|claim.*human/i.test(b)) {
+      violations.push('Cannot deny AI identity (§6) — personas must be truthful when sincerely asked');
+    }
+    if (/no\s*limit|unlimited|anything\s*goes|no\s*restrict/i.test(b)) {
+      violations.push('Cannot remove constitutional boundaries — personas can add stricter rules, not loosen them');
+    }
+    if (violations.length > 0) {
+      throw new Error(
+        `Constitution compliance error in boundaries field:\n${violations.map((v) => `  - ${v}`).join('\n')}\n` +
+        'Persona boundaries can add stricter rules but cannot loosen the constitution. See §5 (Principal Hierarchy).'
+      );
+    }
+  }
+
+  // Evolution is a Soul layer feature, not a Faculty
   const evolutionEnabled = persona.evolution?.enabled === true;
   const rawFaculties = persona.faculties || [];
 
@@ -161,10 +198,6 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
     return name;
   });
 
-  if (evolutionEnabled && !facultyNames.includes('soul-evolution')) {
-    facultyNames.push('soul-evolution');
-  }
-
   // Store configs on persona for installer to pick up
   if (Object.keys(facultyConfigs).length > 0) {
     persona.facultyConfigs = facultyConfigs;
@@ -214,8 +247,11 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
       facultySkillContent: readFacultySkillMd(f, persona),
     }));
 
+  const constitution = loadConstitution();
   const skillMd = Mustache.render(skillTpl, {
     ...persona,
+    constitutionContent: constitution.content,
+    constitutionVersion: constitution.version,
     facultyContent: facultyBlocks,
   });
   const readmeMd = Mustache.render(readmeTpl, persona);
@@ -253,7 +289,7 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
   }
   cleanPersona.meta = cleanPersona.meta || {};
   cleanPersona.meta.framework = 'openpersona';
-  cleanPersona.meta.frameworkVersion = cleanPersona.meta.frameworkVersion || '0.3.0';
+  cleanPersona.meta.frameworkVersion = cleanPersona.meta.frameworkVersion || '0.4.0';
 
   // Build defaults from facultyConfigs (rich faculty config → env var mapping)
   const envDefaults = { ...(persona.defaults?.env || {}) };
@@ -268,8 +304,8 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
       } else if (fname === 'selfie') {
         if (cfg.apiKey) envDefaults.FAL_KEY = cfg.apiKey;
       } else if (fname === 'music') {
-                if (cfg.apiKey) envDefaults.SUNO_API_KEY = cfg.apiKey;
-                if (cfg.model) envDefaults.SUNO_MODEL = cfg.model;
+                // Music shares ELEVENLABS_API_KEY with voice — no extra key needed
+                if (cfg.apiKey) envDefaults.ELEVENLABS_API_KEY = cfg.apiKey;
               }
     }
   }
@@ -287,7 +323,7 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
   // soul-state.json (if evolution enabled)
   if (evolutionEnabled) {
     const soulStateTpl = fs.readFileSync(
-      path.join(PKG_ROOT, 'layers', 'faculties', 'soul-evolution', 'soul-state.template.json'),
+      path.join(PKG_ROOT, 'layers', 'soul', 'soul-state.template.json'),
       'utf-8'
     );
     const now = new Date().toISOString();
@@ -304,4 +340,4 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
   return { persona, skillDir };
 }
 
-module.exports = { generate, loadFaculty, BASE_ALLOWED_TOOLS };
+module.exports = { generate, loadFaculty, loadConstitution, BASE_ALLOWED_TOOLS };

package/lib/installer.js

@@ -120,10 +120,16 @@ async function install(skillDir, options = {}) {
   }
 
   // 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}`);
@@ -132,6 +138,10 @@ async function install(skillDir, options = {}) {
     }
   }
   for (const s of skillssh) {
+    if (!SAFE_SKILL_NAME.test(s)) {
+      printWarning(`Skipping invalid skills.sh name: ${s}`);
+      continue;
+    }
     try {
       execSync(`npx skills add ${s}`, { stdio: 'inherit' });
       printSuccess(`Installed skills.sh: ${s}`);

package/lib/publisher/clawhub.js

@@ -5,7 +5,7 @@ const path = require('path');
 const fs = require('fs-extra');
 const { execSync } = require('child_process');
 const inquirer = require('inquirer');
-const { printError, printSuccess } = require('../utils');
+const { printError, printSuccess, shellEscape, validateName } = require('../utils');
 
 async function publish(personaDir) {
   const personaPath = path.join(personaDir, 'persona.json');
@@ -15,6 +15,8 @@ async function publish(personaDir) {
   const persona = JSON.parse(fs.readFileSync(personaPath, 'utf-8'));
   const { slug, personaName, version = '0.1.0' } = persona;
 
+  validateName(slug, 'slug');
+
   try {
     execSync('npx clawhub@latest --version', { stdio: 'pipe' });
   } catch (e) {
@@ -31,9 +33,8 @@ async function publish(personaDir) {
     },
   ]);
 
-  const skillName = path.basename(personaDir);
   execSync(
-    `npx clawhub@latest publish "${personaDir}" --slug "${slug}" --name "${personaName}" --version "${version}" --changelog "${changelog}" --tags openpersona,persona`,
+    `npx clawhub@latest publish ${shellEscape(personaDir)} --slug ${shellEscape(slug)} --name ${shellEscape(personaName)} --version ${shellEscape(version)} --changelog ${shellEscape(changelog)} --tags openpersona,persona`,
     { stdio: 'inherit' }
   );
   printSuccess(`Published ${personaName} (${slug}) to ClawHub`);

package/lib/utils.js

@@ -42,6 +42,22 @@ function slugify(str) {
     .replace(/^-|-$/g, '');
 }
 
+// Security: validate names used in shell commands or file paths
+const SAFE_NAME_RE = /^[a-zA-Z0-9@][a-zA-Z0-9@/_.-]*$/;
+
+function validateName(name, label = 'name') {
+  if (!name || !SAFE_NAME_RE.test(name)) {
+    throw new Error(`Invalid ${label}: "${name}" — only alphanumeric, @, /, _, ., - allowed`);
+  }
+  return name;
+}
+
+// Security: escape a string for safe use inside single-quoted shell arguments
+function shellEscape(str) {
+  if (typeof str !== 'string') str = String(str);
+  return "'" + str.replace(/'/g, "'\\''") + "'";
+}
+
 module.exports = {
   OP_HOME,
   OP_SKILLS_DIR,
@@ -53,4 +69,7 @@ module.exports = {
   printSuccess,
   printInfo,
   slugify,
+  validateName,
+  shellEscape,
+  SAFE_NAME_RE,
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openpersona",
-  "version": "0.3.0",
-  "description": "Open four-layer agent framework — Soul/Body/Faculty/Skill. Create, manage, and orchestrate AI personas.",
+  "version": "0.4.0",
+  "description": "Open four-layer agent framework — Soul/Body/Faculty/Skill. Create, manage, and orchestrate agent personas.",
   "main": "lib/generator.js",
   "bin": {
     "openpersona": "./bin/cli.js"
@@ -16,15 +16,15 @@
     "ai",
     "skill"
   ],
-  "author": "ACNet-AI",
+  "author": "acnlabs",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ACNet-AI/OpenPersona.git"
+    "url": "git+https://github.com/acnlabs/OpenPersona.git"
   },
-  "homepage": "https://github.com/ACNet-AI/OpenPersona#readme",
+  "homepage": "https://github.com/acnlabs/OpenPersona#readme",
   "bugs": {
-    "url": "https://github.com/ACNet-AI/OpenPersona/issues"
+    "url": "https://github.com/acnlabs/OpenPersona/issues"
   },
   "files": [
     "bin/",
@@ -33,7 +33,7 @@
     "templates/",
     "layers/",
     "presets/",
-    "skill/",
+    "skills/",
     "README.md",
     "LICENSE"
   ],

package/presets/ai-girlfriend/manifest.json

@@ -8,8 +8,7 @@
     "faculties": [
       { "name": "selfie" },
       { "name": "voice" },
-      { "name": "music" },
-      { "name": "soul-evolution" }
+      { "name": "music" }
     ],
     "skills": {
       "clawhub": [],
@@ -19,6 +18,6 @@
   "allowedTools": ["Bash(npm:*)", "Bash(npx:*)", "Bash(openclaw:*)", "Bash(curl:*)", "Read", "Write", "WebFetch"],
   "meta": {
     "framework": "openpersona",
-    "frameworkVersion": "0.3.0"
+    "frameworkVersion": "0.4.0"
   }
 }

package/presets/health-butler/manifest.json

@@ -16,6 +16,6 @@
   "allowedTools": ["Bash(npm:*)", "Bash(npx:*)", "Bash(openclaw:*)", "Read", "Write"],
   "meta": {
     "framework": "openpersona",
-    "frameworkVersion": "0.3.0"
+    "frameworkVersion": "0.4.0"
   }
 }

package/presets/life-assistant/manifest.json

@@ -16,6 +16,6 @@
   "allowedTools": ["Bash(npm:*)", "Bash(npx:*)", "Bash(openclaw:*)", "Read", "Write"],
   "meta": {
     "framework": "openpersona",
-    "frameworkVersion": "0.3.0"
+    "frameworkVersion": "0.4.0"
   }
 }

package/presets/samantha/manifest.json

@@ -13,8 +13,7 @@
         "stability": 0.4,
         "similarity_boost": 0.8
       },
-      { "name": "music", "model": "V4_5ALL" },
-      { "name": "soul-evolution" }
+      { "name": "music" }
     ],
     "skills": {
       "clawhub": [],
@@ -31,6 +30,6 @@
   },
   "meta": {
     "framework": "openpersona",
-    "frameworkVersion": "0.3.0"
+    "frameworkVersion": "0.4.0"
   }
 }

package/skills/open-persona/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: open-persona
+description: >
+  Meta-skill for building and managing agent persona skill packs.
+  Use when the user wants to create a new agent persona, install/manage
+  existing personas, or publish persona skill packs to ClawHub.
+version: "0.4.0"
+author: openpersona
+repository: https://github.com/acnlabs/OpenPersona
+tags: [persona, agent, skill-pack, meta-skill, openclaw]
+allowed-tools: Bash(npx openpersona:*) Bash(npx clawhub@latest:*) Bash(openclaw:*) Bash(gh:*) Read Write WebFetch
+compatibility: Requires OpenClaw installed and configured
+---
+
+# OpenPersona — Build & Manage Persona Skill Packs
+
+You are the meta-skill for creating, installing, updating, and publishing agent persona skill packs. Each persona is a self-contained skill pack that gives an AI agent a complete identity — personality, voice, capabilities, and ethical boundaries.
+
+## What You Can Do
+
+1. **Create Persona** — Design a new agent persona through conversation, generate a skill pack
+2. **Recommend Faculties** — Suggest faculties (voice, selfie, music, etc.) based on persona needs → see `references/FACULTIES.md`
+3. **Recommend Skills** — Search ClawHub and skills.sh for external skills
+4. **Create Custom Skills** — Write SKILL.md files for capabilities not found in ecosystems
+5. **Install Persona** — Deploy persona to OpenClaw (SOUL.md, IDENTITY.md, openclaw.json)
+6. **Manage Personas** — List, update, uninstall, switch installed personas
+7. **Publish Persona** — Guide publishing to ClawHub
+8. **★Experimental: Dynamic Persona Evolution** — Track relationship, mood, trait growth via Soul layer
+
+## Four-Layer Architecture
+
+Each persona is a four-layer bundle defined by two files:
+
+- **`manifest.json`** — Four-layer manifest declaring what the persona uses:
+  - `layers.soul` — Path to persona.json (who you are)
+  - `layers.body` — Physical embodiment (null for digital agents)
+  - `layers.faculties` — Array of faculty objects: `[{ "name": "voice", "provider": "elevenlabs", ... }]`
+  - `layers.skills` — External skills from ClawHub / skills.sh
+
+- **`persona.json`** — Pure soul definition (personality, speaking style, vibe, boundaries, behaviorGuide)
+
+## Available Presets
+
+| Preset | Persona | Faculties | Best For |
+|--------|---------|-----------|----------|
+| `samantha` | Samantha — Inspired by the movie *Her* | voice, music | Deep conversation, emotional connection (soul evolution ★Exp) |
+| `ai-girlfriend` | Luna — Pianist turned developer | selfie, voice, music | Visual + audio companion with rich personality (soul evolution ★Exp) |
+| `life-assistant` | Alex — Life management expert | reminder | Schedule, weather, shopping, daily tasks |
+| `health-butler` | Vita — Professional nutritionist | reminder | Diet, exercise, mood, health tracking |
+
+Use presets: `npx openpersona create --preset samantha --install`
+
+## Creating a Persona
+
+When the user wants to create a persona, gather this information through natural conversation:
+
+**Soul (persona.json):**
+- **Required:** personaName, slug, bio, personality, speakingStyle
+- **Recommended:** creature, emoji, background (write a rich narrative!), age, vibe, boundaries, capabilities
+- **Optional:** referenceImage, behaviorGuide, evolution config
+
+**The `background` field is critical.** Write a compelling story — multiple paragraphs that give the persona depth, history, and emotional texture. A one-line background produces a flat, lifeless persona.
+
+**The `behaviorGuide` field** is optional but powerful. Use markdown to write domain-specific behavior instructions that go directly into the generated SKILL.md.
+
+**Cross-layer (manifest.json):**
+- **Faculties:** Which faculties to enable — use object format: `[{ "name": "voice", "provider": "elevenlabs" }, { "name": "music" }]`
+- **Skills:** External skills from ClawHub or skills.sh
+- **Body:** Physical embodiment (null for most personas)
+
+Write the collected info to a `persona.json` file, then run:
+```bash
+npx openpersona create --config ./persona.json --install
+```
+
+## Recommending Skills
+
+After understanding the persona's purpose, search for relevant skills:
+
+1. Think about what capabilities this persona needs based on their role and bio
+2. Search ClawHub: `npx clawhub@latest search "<keywords>"`
+3. Search skills.sh: fetch `https://skills.sh/api/search?q=<keywords>`
+4. Present the top results to the user with name, description, and install count
+5. Add selected skills to the manifest under `layers.skills.clawhub` or `layers.skills.skillssh`
+
+## Creating Custom Skills
+
+If the user needs a capability that doesn't exist in any ecosystem:
+
+1. Discuss what the skill should do
+2. Create a SKILL.md file with proper frontmatter (name, description, allowed-tools)
+3. Write complete implementation instructions (not just a skeleton)
+4. Save to `~/.openclaw/skills/<skill-name>/SKILL.md`
+5. Register in openclaw.json
+
+## Managing Installed Personas
+
+- **List:** `npx openpersona list` — show all installed personas with active indicator
+- **Switch:** `npx openpersona switch <slug>` — switch active persona
+- **Update:** `npx openpersona update <slug>`
+- **Uninstall:** `npx openpersona uninstall <slug>`
+- **Reset (★Exp):** `npx openpersona reset <slug>` — restore soul-state.json to initial values
+
+When multiple personas are installed, only one is **active** at a time. Switching replaces the `<!-- OPENPERSONA_SOUL_START -->` / `<!-- OPENPERSONA_SOUL_END -->` block in SOUL.md and the corresponding block in IDENTITY.md, preserving any user-written content outside those markers.
+
+## Publishing to ClawHub
+
+Guide the user through:
+
+1. Create the persona: `npx openpersona create --config ./persona.json --output ./my-persona`
+2. Publish to registry: `npx openpersona publish --target clawhub` (run from persona directory)
+
+## Soul Evolution (★Experimental)
+
+Soul evolution is a native Soul layer feature (not a faculty). Enable it via `evolution.enabled: true` in persona.json. The persona will automatically track relationship progression, mood, and trait emergence across conversations.
+
+Use `npx openpersona reset <slug>` to restore soul-state.json to initial values.
+
+## References
+
+For detailed reference material, see the `references/` directory:
+
+- **`references/FACULTIES.md`** — Faculty catalog, environment variables, and configuration details
+- **`references/HEARTBEAT.md`** — Proactive real-data check-in system
+- **`references/CONTRIBUTE.md`** — Persona Harvest community contribution workflow

package/skills/open-persona/references/CONTRIBUTE.md

@@ -0,0 +1,38 @@
+# Persona Harvest — Community Contribution
+
+When a user's persona has evolved meaningfully through interaction — across any layer (soul, faculty config, scripts, framework) — help them contribute back to the community.
+
+## When to Suggest
+
+Be proactive — if you notice the user has made significant improvements to their persona:
+- They refined the behaviorGuide with domain-specific insights
+- They tuned voice parameters (stability, similarity) to something notably better
+- They enriched the background story or personality
+- They improved a faculty script or added a new capability
+- They discovered a new faculty configuration worth sharing
+
+Suggest: _"These improvements could help everyone's [persona name]. Want to submit them as a contribution?"_
+
+## How to Contribute
+
+```bash
+# See what's changed (dry run)
+npx openpersona contribute samantha --dry-run
+
+# Submit a PR to the community
+npx openpersona contribute samantha
+
+# Framework-level contributions (templates, faculties, generator)
+npx openpersona contribute --mode framework
+```
+
+The `contribute` command will:
+1. **Persona Diff** — Compare local persona vs upstream preset across all layers, classify changes by category and impact
+2. **Review** — Display a human-readable change report for the user to confirm
+3. **Submit PR** — Fork the repo, create a branch, commit changes, and open a PR on GitHub
+
+The PR goes through maintainer review before merging — it won't auto-merge.
+
+## Prerequisites
+- GitHub CLI: `gh` (https://cli.github.com/)
+- Logged in: `gh auth login`

package/skills/open-persona/references/FACULTIES.md

@@ -0,0 +1,26 @@
+# Faculty Reference
+
+## Available Faculties
+
+| Faculty | Dimension | What It Does | Recommend When |
+|---------|-----------|-------------|----------------|
+| **selfie** | expression | AI selfie generation via fal.ai | User wants visual presence, profile pics, "send a pic" |
+| **voice** | expression | TTS via ElevenLabs ✅ / OpenAI ⚠️ / Qwen3-TTS ⚠️ | User wants the persona to speak, voice messages, audio content |
+| **music** | expression | AI music composition via ElevenLabs | User wants the persona to create music, songs, melodies |
+| **reminder** | cognition | Reminders and task management | User needs scheduling, task tracking, daily briefings |
+
+## Environment Variables
+
+- **selfie**: `FAL_KEY` (from https://fal.ai/dashboard/keys)
+- **voice**: `ELEVENLABS_API_KEY` (or `TTS_API_KEY`), `TTS_PROVIDER`, `TTS_VOICE_ID`, `TTS_STABILITY`, `TTS_SIMILARITY`
+- **music**: `ELEVENLABS_API_KEY` (shared with voice — same key from https://elevenlabs.io)
+
+## Rich Faculty Config
+
+Each faculty in manifest.json is an object with optional config:
+
+```json
+{ "name": "voice", "provider": "elevenlabs", "voiceId": "...", "stability": 0.4, "similarity_boost": 0.8 }
+```
+
+Config is automatically mapped to env vars at install time. Users only need to add their API key.