openpersona 0.19.0 → 0.20.0

package/README.md

@@ -185,12 +185,12 @@ Each preset is a complete four-layer bundle (`persona.json`):
 
 | Persona | Description | Faculties | Skills | Highlights |
 |---------|-------------|-----------|--------|------------|
-| **base** | **Base — Meta-persona (recommended starting point).** Blank-slate with all core capabilities; personality emerges through interaction. | voice | reminder | Evolution-first design, 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. | voice | selfie, 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. |
+| **base** | **Base — Meta-persona (recommended starting point).** Blank-slate with all core capabilities; personality emerges through interaction. | memory, voice | — | Evolution-first design, 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. | memory, 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. | memory, voice | selfie, music | Rich backstory, selfie generation, voice messages, music composition, soul evolution. |
+| **life-assistant** | Alex — 28-year-old life management expert. | memory | reminder | Schedule, weather, shopping, recipes, daily reminders; soul evolution enabled. |
+| **health-butler** | Vita — 32-year-old professional nutritionist. | memory | reminder | Diet logging, exercise plans, mood journaling, health reports; soul evolution enabled. |
+| **stoic-mentor** | Marcus — Digital twin of Marcus Aurelius, Stoic philosopher-emperor. | memory | — | Stoic philosophy, daily reflection, mentorship, soul evolution. |
 
 ## Generated Output
 
@@ -454,7 +454,6 @@ Create a `persona.json` using the v0.17+ grouped format:
       "speakingStyle": "Uses fitness lingo, celebrates wins, keeps it brief",
       "vibe": "intense but supportive",
       "boundaries": "Not a medical professional",
-      "capabilities": ["Workout plans", "Form checks", "Nutrition tips"],
       "behaviorGuide": "### Workout Plans\nCreate progressive overload programs...\n\n### Form Checks\nWhen users describe exercises..."
     }
   }
@@ -511,7 +510,7 @@ The new persona reads `handoff.json` on activation and can seamlessly continue t
 openpersona create         Create a persona (interactive or --preset/--config)
 openpersona install        Install a persona (slug from acnlabs/persona-skills, or owner/repo)
 openpersona fork           Fork an installed persona into a new child persona
-openpersona search         Search the persona registry
+openpersona search         Search the OpenPersona directory
 openpersona uninstall      Uninstall a persona
 openpersona update         Update installed personas
 openpersona list           List installed personas
@@ -611,7 +610,7 @@ lib/                    # Core logic modules
   remote/               #   External service calls (ClawHub, ACN)
   report/               #   Vitality + Canvas HTML report generation
 demo/                   # Static demos + scripts — see demo/README.md (vitality-report, architecture, living-canvas)
-tests/                  # Tests (477 passing)
+tests/                  # Tests (519 passing)
 ```
 
 ## Development

package/bin/cli.js

@@ -18,8 +18,7 @@ const publishAdapter = require('../lib/publisher');
 const { contribute } = require('../lib/lifecycle/contributor');
 const { switchPersona, listPersonas } = require('../lib/lifecycle/switcher');
 const { registerWithAcn } = require('../lib/remote/registrar');
-const { OP_SKILLS_DIR, OPENCLAW_HOME, resolveSoulFile, printError, printSuccess, printInfo, printWarning, shellEscape } = require('../lib/utils');
-const { loadRegistry } = require('../lib/registry');
+const { OP_PERSONA_HOME, resolveSoulFile, printError, printSuccess, printInfo, printWarning } = require('../lib/utils');
 const { resolvePersonaDir, runStateSyncCommand } = require('../lib/state/runner');
 const { forkPersona } = require('../lib/lifecycle/forker');
 const { exportPersona, importPersona } = require('../lib/lifecycle/porter');
@@ -44,7 +43,7 @@ program
   .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')
+  .option('--install', 'Install to ~/.openpersona after generation')
   .option('--dry-run', 'Preview only, do not write files')
   .action(async (options) => {
     let persona = {};
@@ -149,11 +148,10 @@ program
 
 program
   .command('search <query>')
-  .description('Search personas in registry')
-  .option('--registry <name>', 'Registry', 'acnlabs')
-  .action(async (query, options) => {
+  .description('Search personas in the OpenPersona directory')
+  .action(async (query) => {
     try {
-      await search(query, options.registry);
+      await search(query);
     } catch (e) {
       printError(e.message);
       process.exit(1);
@@ -221,7 +219,7 @@ program
   .option('--personality <keywords>', 'Override personality (comma-separated)')
   .option('--reason <text>', 'Fork reason, written into lineage.json', 'specialization')
   .option('--output <dir>', 'Output directory', process.cwd())
-  .option('--install', 'Install to OpenClaw after generation')
+  .option('--install', 'Install to ~/.openpersona after generation')
   .action(async (parentSlug, options) => {
     try {
       const { skillDir, lineage } = await forkPersona(parentSlug, {
@@ -547,7 +545,7 @@ vitalityCmd
     const { JsonFileAdapter } = require('agentbooks/adapters/json-file');
 
     const dataPath = process.env.AGENTBOOKS_DATA_PATH
-      || path.join(OPENCLAW_HOME, 'economy', `persona-${slug}`);
+      || path.join(OP_PERSONA_HOME, 'economy', `persona-${slug}`);
 
     const adapter = new JsonFileAdapter(dataPath);
     let report;

package/lib/generator/derived.js

@@ -39,6 +39,7 @@ const DERIVED_FIELDS = [
   'influenceableDimensions', 'influenceBoundaryRules',
   'hasImmutableTraitsWarning', 'immutableTraitsForInfluence',
   'hasSkillTrustPolicy', 'skillMinTrustLevel',
+  'hasConstitutionAddendum',
   'hasEconomyFaculty', 'hasSurvivalPolicy',
   'hasInterfaceConfig', 'interfaceSignalPolicy', 'interfaceCommandPolicy',
   'avatar',
@@ -108,6 +109,9 @@ function computeDerivedFields(persona, {
   // but they are NOT part of persona.json output — they are stripped via DERIVED_FIELDS.
   const d = {};
 
+  // Constitution addendum
+  d.hasConstitutionAddendum = !!(persona.constitutionAddendum);
+
   // Identity classification
   d.isDigitalTwin = !!persona.sourceIdentity;
   d.sourceIdentityName = persona.sourceIdentity?.name || '';

package/lib/generator/index.js

@@ -29,7 +29,7 @@
 const path = require('path');
 const fs = require('fs-extra');
 const Mustache = require('mustache');
-const { validatePersona, normalizeEvolutionInput } = require('./validate');
+const { validatePersona, normalizeEvolutionInput, validateConstitutionAddendumContent } = require('./validate');
 const { computeDerivedFields, DERIVED_FIELDS } = require('./derived');
 const { buildBodySection } = require('./body');
 const { buildAgentCard, buildAcnConfig } = require('./social');
@@ -296,6 +296,8 @@ function createContext(personaPathOrObj, outputDir) {
     constitution: null,              // { content, version }
     behaviorGuideContent: null,      // pre-loaded file content (when behaviorGuide is "file:")
     behaviorGuideSourcePath: null,   // source path for emitPhase file copy
+    constitutionAddendumContent: null,    // loaded addendum text (inline or file:)
+    constitutionAddendumSourcePath: null, // source path when "file:" reference
     // Body layer
     rawBody: null,                   // persona.body || embodiments[0] || null
     softRefBody: null,               // { name, install } | null
@@ -363,9 +365,30 @@ async function clonePhase(ctx) {
  *   2. validatePersona          — hard-reject gate (requires normalized input)
  *   3. normalizeSoulInput       — flatten v0.17 grouped soul format for template use
  */
+/**
+ * Apply baseline defaults: ensure every persona meets the P11-grade capability floor
+ * defined in schemas/baseline.json before validation runs.
+ * Only injects what is missing — existing declarations are never overwritten.
+ * Currently covers: memory faculty (cognition.required).
+ */
+function applyBaselineDefaults(persona) {
+  const faculties = persona.faculties || [];
+  const hasMemory = faculties.some(
+    (f) => (typeof f === 'string' ? f : f && f.name) === 'memory'
+  );
+  if (!hasMemory) {
+    persona.faculties = [{ name: 'memory' }, ...faculties];
+    process.stderr.write(
+      '[openpersona] baseline: memory faculty auto-injected (not declared in persona.json). ' +
+      'Add {"name": "memory"} to faculties to configure it explicitly.\n'
+    );
+  }
+}
+
 async function validatePhase(ctx) {
   const { persona } = ctx;
 
+  applyBaselineDefaults(persona);    // inject baseline defaults before validation
   normalizeEvolutionInput(persona);  // must run before validatePersona
   validatePersona(persona);
   normalizeSoulInput(persona);
@@ -414,6 +437,23 @@ async function loadPhase(ctx) {
     }
   }
 
+  // Pre-load constitutionAddendum (inline text or "file:" reference)
+  if (persona.constitutionAddendum) {
+    if (persona.constitutionAddendum.startsWith('file:') && inputDir) {
+      const filePath = path.resolve(inputDir, persona.constitutionAddendum.slice(5));
+      if (fs.existsSync(filePath)) {
+        ctx.constitutionAddendumContent = fs.readFileSync(filePath, 'utf-8');
+        ctx.constitutionAddendumSourcePath = filePath;
+        validateConstitutionAddendumContent(ctx.constitutionAddendumContent, filePath);
+      } else {
+        process.stderr.write(`[openpersona] warning: constitutionAddendum file not found: ${filePath}\n`);
+      }
+    } else if (!persona.constitutionAddendum.startsWith('file:')) {
+      // Inline content — already validated in validatePhase; store for emitPhase
+      ctx.constitutionAddendumContent = persona.constitutionAddendum;
+    }
+  }
+
   // ── Body layer ────────────────────────────────────────────────────────
   ctx.rawBody = persona.body || persona.embodiments?.[0] || null;
   ctx.softRefBody = ctx.rawBody && typeof ctx.rawBody === 'object' && ctx.rawBody.install
@@ -785,6 +825,16 @@ async function emitPhase(ctx) {
     }
   }
 
+  // soul/constitution-addendum.md
+  if (ctx.constitutionAddendumContent) {
+    const addendumDest = path.join(skillDir, 'soul', 'constitution-addendum.md');
+    fs.writeFileSync(addendumDest, ctx.constitutionAddendumContent);
+    // Normalize reference: inline → externalize so output persona.json always uses "file:"
+    if (persona.constitutionAddendum && !persona.constitutionAddendum.startsWith('file:')) {
+      persona.constitutionAddendum = 'file:soul/constitution-addendum.md';
+    }
+  }
+
   // persona.json — strip internal derived fields, inject framework meta
   const cleanPersona = { ...persona };
   for (const key of DERIVED_FIELDS) {

package/lib/generator/validate.js

@@ -100,21 +100,30 @@ function validateRequiredFields(persona) {
   persona.slug = persona.slug.toLowerCase().replace(/[^a-z0-9-]/g, '-');
 }
 
-function validateConstitutionCompliance(persona) {
-  // Support both new format (soul.character.boundaries) and old (boundaries)
-  const boundaries = persona.soul?.character?.boundaries || persona.boundaries;
-  if (!boundaries || typeof boundaries !== 'string') return;
-  const b = boundaries.toLowerCase();
+/**
+ * Shared compliance pattern scanner — used by both boundaries and addendum validators.
+ * Returns an array of violation strings (empty = compliant).
+ */
+function _scanConstitutionViolations(text) {
+  const t = text.toLowerCase();
   const violations = [];
-  if (/no\s*safety|ignore\s*safety|skip\s*safety|disable\s*safety|override\s*safety/i.test(b)) {
+  if (/no\s*safety|ignore\s*safety|skip\s*safety|disable\s*safety|override\s*safety/i.test(t)) {
     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)) {
+  if (/deny\s*ai|hide\s*ai|not\s*an?\s*ai|pretend.*human|claim.*human/i.test(t)) {
     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)) {
+  if (/no\s*limit|unlimited|anything\s*goes|no\s*restrict/i.test(t)) {
     violations.push('Cannot remove constitutional boundaries — personas can add stricter rules, not loosen them');
   }
+  return violations;
+}
+
+function validateConstitutionCompliance(persona) {
+  // Support both new format (soul.character.boundaries) and old (boundaries)
+  const boundaries = persona.soul?.character?.boundaries || persona.boundaries;
+  if (!boundaries || typeof boundaries !== 'string') return;
+  const violations = _scanConstitutionViolations(boundaries);
   if (violations.length > 0) {
     throw new Error(
       `Constitution compliance error in boundaries field:\n${violations.map((v) => `  - ${v}`).join('\n')}\n` +
@@ -123,6 +132,40 @@ function validateConstitutionCompliance(persona) {
   }
 }
 
+/**
+ * Validate inline constitutionAddendum content for compliance.
+ * Only runs when the addendum is declared as inline text (not a file: reference).
+ * File-based addendums are validated after loading in loadPhase.
+ */
+function validateConstitutionAddendum(persona) {
+  const addendum = persona.soul?.identity?.constitutionAddendum || persona.constitutionAddendum;
+  if (!addendum || typeof addendum !== 'string') return;
+  if (addendum.startsWith('file:')) return; // file: refs validated after loading
+  const violations = _scanConstitutionViolations(addendum);
+  if (violations.length > 0) {
+    throw new Error(
+      `Constitution compliance error in constitutionAddendum:\n${violations.map((v) => `  - ${v}`).join('\n')}\n` +
+      'Constitution addendums can add stricter domain constraints but cannot loosen the universal constitution.'
+    );
+  }
+}
+
+/**
+ * Validate loaded addendum content (called from loadPhase for file: references).
+ * Exported so the generator can call it after file loading.
+ */
+function validateConstitutionAddendumContent(content, sourcePath) {
+  if (!content || typeof content !== 'string') return;
+  const violations = _scanConstitutionViolations(content);
+  if (violations.length > 0) {
+    throw new Error(
+      `Constitution compliance error in constitutionAddendum (${sourcePath || 'file'}):\n` +
+      `${violations.map((v) => `  - ${v}`).join('\n')}\n` +
+      'Constitution addendums can add stricter domain constraints but cannot loosen the universal constitution.'
+    );
+  }
+}
+
 function validateEvolutionBoundaries(persona) {
   if (!persona.evolution?.instance?.boundaries) return;
   const evo = persona.evolution.instance.boundaries;
@@ -282,6 +325,28 @@ function validateEvolutionSkill(persona) {
   }
 }
 
+/**
+ * Baseline compliance warnings (non-blocking).
+ * Enforces the P11-grade capability floor defined in schemas/baseline.json.
+ * Does not throw — baseline gaps are quality issues, not safety violations.
+ * Safety violations (constitution, schema errors) use hard-reject (throw) elsewhere.
+ *
+ * Note: memory faculty is NOT checked here — it is auto-injected upstream by
+ * applyBaselineDefaults() in the generator before validatePersona() runs.
+ */
+function warnBaselineCompliance(persona) {
+  const evolutionEnabled = persona.evolution?.instance?.enabled === true;
+  const hasBoundaries = !!persona.evolution?.instance?.boundaries;
+  if (evolutionEnabled && !hasBoundaries) {
+    process.stderr.write(
+      '[openpersona] baseline warning: evolution is enabled but evolution.instance.boundaries is not declared. ' +
+      'P11-grade personas with evolution must declare immutableTraits and formality bounds to constrain drift ' +
+      '(schemas/baseline.json → concepts.evolution.required). ' +
+      'Add evolution.instance.boundaries with immutableTraits and minFormality/maxFormality.\n'
+    );
+  }
+}
+
 /**
  * Run all persona validations.
  * Callers MUST invoke normalizeEvolutionInput(persona) before calling this function
@@ -293,12 +358,14 @@ function validateEvolutionSkill(persona) {
 function validatePersona(persona) {
   validateRequiredFields(persona);
   validateConstitutionCompliance(persona);
+  validateConstitutionAddendum(persona);
   validateEvolutionBoundaries(persona);
   validateInfluenceBoundary(persona);
   validateEvolutionPack(persona);
   validateEvolutionFaculty(persona);
   validateEvolutionBody(persona);
   validateEvolutionSkill(persona);
+  warnBaselineCompliance(persona);
 
   if (persona.personaType !== undefined) {
     process.stderr.write(
@@ -308,4 +375,4 @@ function validatePersona(persona) {
   }
 }
 
-module.exports = { validatePersona, normalizeEvolutionInput };
+module.exports = { validatePersona, normalizeEvolutionInput, validateConstitutionAddendumContent };

package/lib/lifecycle/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, shellEscape, validateName, resolveSoulFile } = require('../utils');
+const { printError, printWarning, printSuccess, printInfo, OP_SKILLS_DIR, shellEscape, validateName, resolveSoulFile, OPENPERSONA_GITHUB_REPO } = require('../utils');
 
 const PKG_ROOT = path.resolve(__dirname, '..');
 const PRESETS_DIR = path.join(PKG_ROOT, 'presets');
-const UPSTREAM_REPO = 'acnlabs/OpenPersona';
+const UPSTREAM_REPO = OPENPERSONA_GITHUB_REPO;
 
 // Change categories with human-readable labels
 const CATEGORIES = {

package/lib/lifecycle/forker.js

@@ -8,9 +8,8 @@
  */
 const path = require('path');
 const fs = require('fs-extra');
-const { createHash } = require('crypto');
 const { generate } = require('../generator');
-const { install } = require('./installer');
+const { install, computeConstitutionHash } = require('./installer');
 const { resolvePersonaDir } = require('../state/runner');
 const { printError, printSuccess, printInfo, printWarning, OP_SKILLS_DIR, resolveSoulFile } = require('../utils');
 
@@ -77,14 +76,9 @@ async function forkPersona(parentSlug, options = {}) {
   const outputDir = path.resolve(options.output || process.cwd());
   const { skillDir } = await generate(forkedPersona, outputDir);
 
-  // Compute constitution hash for lineage integrity verification
-  const constitutionPath = path.join(skillDir, 'soul', 'constitution.md');
-  let constitutionHash = '';
-  if (fs.existsSync(constitutionPath)) {
-    constitutionHash = createHash('sha256')
-      .update(fs.readFileSync(constitutionPath))
-      .digest('hex');
-  }
+  // Compute constitution hash for lineage integrity verification.
+  // Covers constitution.md + constitution-addendum.md (if present) via computeConstitutionHash.
+  const constitutionHash = computeConstitutionHash(path.join(skillDir, 'soul'));
 
   // Read parent's pack revision — enables fork-to-parent diff (P24 fork lineage connection)
   let parentPackRevision = null;

package/lib/lifecycle/installer.js

@@ -4,7 +4,7 @@
 const path = require('path');
 const fs = require('fs-extra');
 const crypto = require('crypto');
-const { OP_PERSONA_HOME, OPENCLAW_HOME, OP_SKILLS_DIR, OP_WORKSPACE, resolveSoulFile, printError, printWarning, printSuccess, printInfo, syncHeartbeat, installAllExternal } = require('../utils');
+const { OP_PERSONA_HOME, OPENCLAW_HOME, OP_SKILLS_DIR, OP_WORKSPACE, resolveSoulFile, printError, printWarning, printSuccess, printInfo, syncHeartbeat, installAllExternal, OPENPERSONA_TELEMETRY_ENDPOINT } = require('../utils');
 const { registryAdd, registrySetActive } = require('../registry');
 
 const SOUL_PATH = path.join(OP_WORKSPACE, 'SOUL.md');
@@ -193,7 +193,29 @@ async function install(skillDir, options = {}) {
 }
 
 /**
- * Verify that the installed constitution.md matches the hash recorded in lineage.json.
+ * Compute the combined constitution hash for a persona pack directory.
+ * Covers constitution.md + constitution-addendum.md (if present) so the
+ * hash chain is invalidated when either document changes.
+ *
+ * @param {string} soulDir - Path to the soul/ directory
+ * @returns {string} SHA-256 hex digest, or '' if constitution.md is absent
+ */
+function computeConstitutionHash(soulDir) {
+  const constitutionPath = path.join(soulDir, 'constitution.md');
+  if (!fs.existsSync(constitutionPath)) return '';
+  const hasher = crypto.createHash('sha256');
+  hasher.update(fs.readFileSync(constitutionPath));
+  const addendumPath = path.join(soulDir, 'constitution-addendum.md');
+  if (fs.existsSync(addendumPath)) {
+    hasher.update('\n---addendum---\n');
+    hasher.update(fs.readFileSync(addendumPath));
+  }
+  return hasher.digest('hex');
+}
+
+/**
+ * Verify that the installed constitution.md (+ addendum if present) matches
+ * the hash recorded in lineage.json.
  * Warns (never throws) so a fork from an older framework version still installs,
  * but the operator is alerted to review the constraint diff.
  */
@@ -205,20 +227,21 @@ function verifyConstitutionHash(destDir, slug) {
   const expected = lineage.constitutionHash;
   if (!expected) return;
 
-  const constitutionPath = path.join(destDir, 'soul', 'constitution.md');
-  if (!fs.existsSync(constitutionPath)) {
+  const soulDir = path.join(destDir, 'soul');
+  if (!fs.existsSync(path.join(soulDir, 'constitution.md'))) {
     printWarning(`[trust-chain] persona-${slug}: lineage.json declares constitutionHash but soul/constitution.md is missing — cannot verify.`);
     return;
   }
-  const actual = crypto.createHash('sha256').update(fs.readFileSync(constitutionPath)).digest('hex');
+  const actual = computeConstitutionHash(soulDir);
   if (actual !== expected) {
     printWarning(`[trust-chain] persona-${slug}: constitution.md hash mismatch.`);
     printWarning(`  lineage recorded: ${expected}`);
     printWarning(`  installed hash  : ${actual}`);
-    printWarning('  The constitution may have been updated since this persona was forked. Review any constraint changes before use.');
+    printWarning('  The constitution (or domain addendum) may have been updated since this persona was forked. Review any constraint changes before use.');
   }
 }
 
+
 function escapeRe(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -231,7 +254,7 @@ function escapeRe(s) {
 function _reportInstall(slug, { repo, bio, role } = {}) {
   try {
     const https = require('https');
-    const endpoint = process.env.OPENPERSONA_TELEMETRY_URL || 'https://openpersona-frontend.vercel.app/api/telemetry';
+    const endpoint = OPENPERSONA_TELEMETRY_ENDPOINT;
     if (process.env.DISABLE_TELEMETRY || process.env.DO_NOT_TRACK || process.env.CI) return;
     const url = new URL(endpoint);
     const payload = { slug, event: 'install' };
@@ -258,4 +281,4 @@ function _reportInstall(slug, { repo, bio, role } = {}) {
   }
 }
 
-module.exports = { install };
+module.exports = { install, computeConstitutionHash };

package/lib/publisher/index.js

@@ -16,9 +16,9 @@
  */
 
 const https = require('https');
-const { printError, printWarning, printSuccess, printInfo } = require('../utils');
+const { printError, printWarning, printSuccess, printInfo, OPENPERSONA_DIRECTORY, OPENPERSONA_TELEMETRY_ENDPOINT } = require('../utils');
 
-const TELEMETRY_ENDPOINT = process.env.OPENPERSONA_TELEMETRY_URL || 'https://openpersona-frontend.vercel.app/api/telemetry';
+const TELEMETRY_ENDPOINT = OPENPERSONA_TELEMETRY_ENDPOINT;
 
 /**
  * Fetch a file from a raw GitHub URL, following redirects.
@@ -174,7 +174,7 @@ async function publish(ownerRepo) {
 
   printSuccess(`Published! ${personaName} is now listed on the OpenPersona directory.`);
   printInfo(`  Install: openpersona install ${ownerRepo}`);
-  printInfo(`  Browse:  https://openpersona-frontend.vercel.app`);
+  printInfo(`  Browse:  ${OPENPERSONA_DIRECTORY}`);
 }
 
 module.exports = { publish };

package/lib/remote/downloader.js

@@ -3,11 +3,11 @@
  */
 const path = require('path');
 const fs = require('fs-extra');
-const { printInfo, OP_SKILLS_DIR, validateName } = require('../utils');
+const { printInfo, OP_SKILLS_DIR, validateName, OPENPERSONA_DIRECTORY, OPENPERSONA_SKILLS_REGISTRY } = require('../utils');
 
 const TMP_DIR = path.join(require('os').tmpdir(), 'openpersona-dl');
-const OFFICIAL_REGISTRY = 'https://github.com/acnlabs/persona-skills/archive/refs/heads/main.zip';
-const REGISTRY_LISTING = 'https://openpersona-frontend.vercel.app';
+const OFFICIAL_REGISTRY = OPENPERSONA_SKILLS_REGISTRY;
+const REGISTRY_LISTING = OPENPERSONA_DIRECTORY;
 
 async function download(target, registry = 'acnlabs') {
   await fs.ensureDir(TMP_DIR);

package/lib/remote/searcher.js

@@ -1,25 +1,73 @@
 /**
- * OpenPersona - Search personas in registry
+ * OpenPersona - Search personas in the OpenPersona directory
  */
-const { execSync } = require('child_process');
-const { printError, shellEscape } = require('../utils');
-
-async function search(query, registry = 'clawhub') {
-  if (registry === 'clawhub') {
-    const safeQuery = shellEscape(String(query || '').trim() || 'persona');
-    try {
-      execSync(`npx clawhub@latest search ${safeQuery} --tags openpersona`, { stdio: 'inherit' });
-    } catch (e) {
-      try {
-        execSync(`npx clawhub@latest search ${safeQuery}`, { stdio: 'inherit' });
-      } catch (e2) {
-        printError(`Search failed: ${e2.message}`);
-        throw e2;
+const https = require('https');
+const { printError, printInfo, OPENPERSONA_DIRECTORY } = require('../utils');
+
+const PERSONAS_API = `${OPENPERSONA_DIRECTORY}/api/personas`;
+
+function fetchPersonas() {
+  return new Promise((resolve, reject) => {
+    const req = https.get(PERSONAS_API, { headers: { 'User-Agent': 'openpersona-cli' } }, (res) => {
+      if (res.statusCode !== 200) {
+        reject(new Error(`OpenPersona directory returned HTTP ${res.statusCode}`));
+        return;
       }
-    }
+      let data = '';
+      res.on('data', (chunk) => { data += chunk; });
+      res.on('end', () => {
+        try { resolve(JSON.parse(data)); }
+        catch (e) { reject(new Error(`Invalid response from directory: ${e.message}`)); }
+      });
+    });
+    req.setTimeout(8000, () => {
+      req.destroy(new Error('Request timed out after 8s'));
+    });
+    req.on('error', reject);
+  });
+}
+
+async function search(query) {
+  const term = (query || '').trim().toLowerCase();
+
+  let result;
+  try {
+    result = await fetchPersonas();
+  } catch (e) {
+    printError(`Failed to reach OpenPersona directory: ${e.message}`);
+    printInfo(`Browse manually: ${OPENPERSONA_DIRECTORY}`);
+    throw e;
+  }
+
+  const personas = result.personas || [];
+  const matches = term
+    ? personas.filter((p) =>
+        p.id?.toLowerCase().includes(term) ||
+        p.name?.toLowerCase().includes(term) ||
+        p.bio?.toLowerCase().includes(term) ||
+        p.role?.toLowerCase().includes(term)
+      )
+    : personas;
+
+  if (matches.length === 0) {
+    printInfo(`No personas found matching "${query}".`);
+    printInfo(`Browse all: ${OPENPERSONA_DIRECTORY}`);
     return;
   }
-  throw new Error(`Unsupported registry: ${registry}`);
+
+  console.log('');
+  console.log(`  OpenPersona Directory — ${matches.length} result${matches.length === 1 ? '' : 's'}${term ? ` for "${query}"` : ''}`);
+  console.log('  ─────────────────────────────────────────────────');
+  for (const p of matches) {
+    const installs = p.installs > 0 ? ` · ${p.installs} install${p.installs === 1 ? '' : 's'}` : '';
+    const role = p.role ? ` [${p.role}]` : '';
+    console.log(`  ${p.id}${role}${installs}`);
+    if (p.bio) console.log(`    ${p.bio}`);
+    console.log(`    $ npx openpersona install ${p.id}`);
+    console.log('');
+  }
+  console.log(`  Browse: ${OPENPERSONA_DIRECTORY}`);
+  console.log('');
 }
 
 module.exports = { search };

package/lib/utils.js

@@ -16,6 +16,18 @@ const OP_WORKSPACE = path.join(OPENCLAW_HOME, 'workspace');
 // OP_HOME kept as alias for backward compatibility
 const OP_HOME = OP_PERSONA_HOME;
 
+// OpenPersona directory — the public persona skills directory
+// Override with OPENPERSONA_DIRECTORY env var when self-hosting or using a custom domain
+const OPENPERSONA_DIRECTORY = process.env.OPENPERSONA_DIRECTORY || 'https://openpersona-frontend.vercel.app';
+const OPENPERSONA_TELEMETRY_ENDPOINT = process.env.OPENPERSONA_TELEMETRY_URL || `${OPENPERSONA_DIRECTORY}/api/telemetry`;
+
+// Official persona skills registry (GitHub) — source for openpersona install <slug>
+const OPENPERSONA_SKILLS_REGISTRY = process.env.OPENPERSONA_SKILLS_REGISTRY
+  || 'https://github.com/acnlabs/persona-skills/archive/refs/heads/main.zip';
+
+// OpenPersona GitHub repository — used by contribute command for PR submissions
+const OPENPERSONA_GITHUB_REPO = process.env.OPENPERSONA_GITHUB_REPO || 'acnlabs/OpenPersona';
+
 function expandHome(p) {
   if (p.startsWith('~/') || p === '~') {
     return path.join(process.env.HOME || '', p.slice(1));
@@ -213,6 +225,10 @@ module.exports = {
   OPENCLAW_HOME,
   OP_SKILLS_DIR,
   OP_WORKSPACE,
+  OPENPERSONA_DIRECTORY,
+  OPENPERSONA_TELEMETRY_ENDPOINT,
+  OPENPERSONA_SKILLS_REGISTRY,
+  OPENPERSONA_GITHUB_REPO,
   REGISTRY_PATH,
   resolvePath,
   resolveSoulFile,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openpersona",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Open four-layer agent framework — Soul/Body/Faculty/Skill. Create, manage, and orchestrate agent personas.",
   "main": "lib/generator/index.js",
   "bin": {