{"id":"f9595a64-982c-4a73-83cc-17698749c4a5","entityType":"agent","slug":"clawhub-neiljo-gy-open-persona","name":"Open Persona","canonicalUrl":"https://www.xpersona.co/agent/clawhub-neiljo-gy-open-persona","canonicalPath":"/agent/clawhub-neiljo-gy-open-persona","generatedAt":"2026-10-10T08:10:33.810Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-09T12:56:55.591Z","emptyReason":null},"description":"Meta-skill for building and managing agent persona skill packs (instruction-only; no bundled installer or auto-downloaded binaries). Credentials are never written into generated packs by the framework; publish/ACN/register require explicit user CLI. Use when the user wants to create a new agent pers Skill: Open Persona Owner: neiljo-gy Summary: Meta-skill for building and managing agent persona skill packs (instruction-only; no bundled installer or auto-downloaded binaries). Credentials are never written into generated packs by the framework; publish/ACN/register require explicit user CLI. Use when the user wants to create a new agent pers Tags: latest:0.22.0 Version history: v0.22.0 | 2026-07-19T12:38:43.194Z |","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.6K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s179vn1xk5bsc9jy98a9j2brkh83gtgg:open-persona","sourceUrl":"https://clawhub.ai/neiljo-gy/open-persona","homepage":"https://clawhub.ai/neiljo-gy/skills/open-persona","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/neiljo-gy/open-persona","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/neiljo-gy/skills/open-persona","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Meta-skill for building and managing agent persona skill packs (instruction-only; no bundled installer or auto-downloaded binaries). Credentials are never writt"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T12:56:55.591Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T12:56:55.591Z","emptyReason":null},"stars":null,"forks":null,"downloads":2608,"packageName":null,"latestVersion":"0.22.0","tractionLabel":"2.6K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T12:56:55.591Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T12:56:55.591Z","lastCrawledAt":"2026-10-09T12:56:55.591Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T12:56:55.591Z","lastVerifiedAt":null,"highlights":[{"version":"0.22.0","createdAt":"2026-07-19T12:38:43.194Z","changelog":"**open-persona v0.22.0 — Minor update and doc cleanup** - Updated SKILL.md to reflect new version 0.22.0. - Clarified the “Runner Integration” section: raised count of `openpersona state` commands from four to five (now: read, write, signal, responses, promote). - Removed the sample file `skill-card.md`. - No functional or interface changes to commands or APIs.","fileCount":11,"zipByteSize":30245},{"version":"0.21.1","createdAt":"2026-04-28T10:27:13.092Z","changelog":"v0.20.0→v0.21.1: Add Contact Book, Dataset Directory, Pack Types, Skill Trust Gate, Vision/Emotion-sensing faculties, Agent Playbook, openpersona skill registry, state responses command, secondme-skill companion, Scope boundary table; fix duplicate headings and list numbering","fileCount":11,"zipByteSize":30229},{"version":"0.20.0","createdAt":"2026-03-28T14:53:45.111Z","changelog":"## OpenPersona 0.20.0 Changelog - Adds support for the `constitutionAddendum` field, enabling domain-specific ethical extensions for professional personas, enforced by the Generate/Install Gates. - Updates the default `base` preset: now includes both memory and voice faculties (previously only voice and reminder skill), with evolution enabled and no pre-built skills. - Clarifies required/recommended/optional `persona.json` fields, including stricter safety rules for professional personas. - Improves documentation and formatting in SKILL.md: reorganized field explanations, made requirements explicit, and added clear instructions for avatar and faculty configuration. - No underlying code changes, but documentation and presets align with current best practices and safety enforcement.","fileCount":10,"zipByteSize":24045},{"version":"0.19.1","createdAt":"2026-03-22T09:36:13.904Z","changelog":"open-persona 0.19.1 - Clarified that the skill is instruction-only: no bundled installer or auto-downloaded binaries. - Added explicit marketplace/reviewer trust & safety section, describing how no credentials or secrets are embedded in generated packs and all publish/register actions require explicit CLI invocation. - Enhanced metadata and policy notes for marketplace scanners, including install surface, network access, and secrets handling policies. - Documentation and manifest changes only; no behavioral changes or file modifications.","fileCount":10,"zipByteSize":23863},{"version":"0.19.0","createdAt":"2026-03-22T09:21:16.013Z","changelog":"**Expanded architecture, system concepts, and documentation:** - Overhauled skill structure with 4+5+3 model: 4 layers, 5 systemic concepts (evolution, economy, vitality, social, rhythm), and 3 gates (Generate, Install, Runtime) now fully documented. - Added detailed, modular reference docs: `references/ARCHITECTURE.md`, `references/EVOLUTION.md`, and `references/PRESETS.md`. - CLI and workflow guidance improved: clarified persona creation, installing, management, and publishing steps, including advanced runner and evolution features. - Updated available persona presets and moved full catalog and architecture details into reference files for easier maintenance. - Expanded usage instructions for faculties, skills (including soft references and trust levels), and persona state management.","fileCount":10,"zipByteSize":22770},{"version":"0.16.1","createdAt":"2026-03-08T14:04:14.331Z","changelog":"v0.16.1: assets structure, Living Canvas fixes, ClawHub scan compliance","fileCount":7,"zipByteSize":17223},{"version":"0.16.0","createdAt":"2026-03-08T12:39:11.933Z","changelog":"ClawHub scan compliance: metadata.clawdbot, External Endpoints, Security & Privacy, Trust Statement; shell injection fix in searcher","fileCount":7,"zipByteSize":16828},{"version":"0.15.1","createdAt":"2026-02-28T09:18:28.262Z","changelog":"open-persona v0.15.0 - Removed the obsolete or extraneous reference file: `references/ACN.md`. - No functional changes to the skill features or architecture. - All other documentation and capabilities remain unchanged.","fileCount":6,"zipByteSize":14201}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s179vn1xk5bsc9jy98a9j2brkh83gtgg:open-persona","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-neiljo-gy-open-persona/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-neiljo-gy-open-persona/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-neiljo-gy-open-persona/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-neiljo-gy-open-persona/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-neiljo-gy-open-persona/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-neiljo-gy-open-persona/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T08:10:33.805Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-neiljo-gy-open-persona/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-neiljo-gy-open-persona/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-neiljo-gy-open-persona/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-neiljo-gy-open-persona/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-09T12:56:55.591Z","emptyReason":null},"readme":"Skill: Open Persona\n\nOwner: neiljo-gy\n\nSummary: Meta-skill for building and managing agent persona skill packs (instruction-only; no bundled installer or auto-downloaded binaries). Credentials are never written into generated packs by the framework; publish/ACN/register require explicit user CLI. Use when the user wants to create a new agent pers\n\nTags: latest:0.22.0\n\nVersion history:\n\nv0.22.0 | 2026-07-19T12:38:43.194Z | user\n\n**open-persona v0.22.0 — Minor update and doc cleanup**\n\n- Updated SKILL.md to reflect new version 0.22.0.\n- Clarified the “Runner Integration” section: raised count of `openpersona state` commands from four to five (now: read, write, signal, responses, promote).\n- Removed the sample file `skill-card.md`.\n- No functional or interface changes to commands or APIs.\n\nv0.21.1 | 2026-04-28T10:27:13.092Z | user\n\nv0.20.0→v0.21.1: Add Contact Book, Dataset Directory, Pack Types, Skill Trust Gate, Vision/Emotion-sensing faculties, Agent Playbook, openpersona skill registry, state responses command, secondme-skill companion, Scope boundary table; fix duplicate headings and list numbering\n\nv0.20.0 | 2026-03-28T14:53:45.111Z | user\n\n## OpenPersona 0.20.0 Changelog\n\n- Adds support for the `constitutionAddendum` field, enabling domain-specific ethical extensions for professional personas, enforced by the Generate/Install Gates.\n- Updates the default `base` preset: now includes both memory and voice faculties (previously only voice and reminder skill), with evolution enabled and no pre-built skills.\n- Clarifies required/recommended/optional `persona.json` fields, including stricter safety rules for professional personas.\n- Improves documentation and formatting in SKILL.md: reorganized field explanations, made requirements explicit, and added clear instructions for avatar and faculty configuration.\n- No underlying code changes, but documentation and presets align with current best practices and safety enforcement.\n\nv0.19.1 | 2026-03-22T09:36:13.904Z | user\n\nopen-persona 0.19.1\n\n- Clarified that the skill is instruction-only: no bundled installer or auto-downloaded binaries.\n- Added explicit marketplace/reviewer trust & safety section, describing how no credentials or secrets are embedded in generated packs and all publish/register actions require explicit CLI invocation.\n- Enhanced metadata and policy notes for marketplace scanners, including install surface, network access, and secrets handling policies.\n- Documentation and manifest changes only; no behavioral changes or file modifications.\n\nv0.19.0 | 2026-03-22T09:21:16.013Z | user\n\n**Expanded architecture, system concepts, and documentation:**\n\n- Overhauled skill structure with 4+5+3 model: 4 layers, 5 systemic concepts (evolution, economy, vitality, social, rhythm), and 3 gates (Generate, Install, Runtime) now fully documented.\n- Added detailed, modular reference docs: `references/ARCHITECTURE.md`, `references/EVOLUTION.md`, and `references/PRESETS.md`.\n- CLI and workflow guidance improved: clarified persona creation, installing, management, and publishing steps, including advanced runner and evolution features.\n- Updated available persona presets and moved full catalog and architecture details into reference files for easier maintenance.\n- Expanded usage instructions for faculties, skills (including soft references and trust levels), and persona state management.\n\nv0.16.1 | 2026-03-08T14:04:14.331Z | user\n\nv0.16.1: assets structure, Living Canvas fixes, ClawHub scan compliance\n\nv0.16.0 | 2026-03-08T12:39:11.933Z | user\n\nClawHub scan compliance: metadata.clawdbot, External Endpoints, Security & Privacy, Trust Statement; shell injection fix in searcher\n\nv0.15.1 | 2026-02-28T09:18:28.262Z | user\n\nopen-persona v0.15.0\n\n- Removed the obsolete or extraneous reference file: `references/ACN.md`.\n- No functional changes to the skill features or architecture.\n- All other documentation and capabilities remain unchanged.\n\nv0.15.0 | 2026-02-28T09:07:19.888Z | user\n\n- Added new reference documents: `references/ACN.md` and `references/ECONOMY.md`.\n- Version bump to 0.15.0.\n\nv0.14.3 | 2026-02-25T14:52:45.201Z | user\n\n**Summary: State bridge integration and body interface expansion.**\n\n- Added scripts/state-sync.js for runtime state bridging (read/write/signal).\n- Introduced support for body.interface in persona.json and manifest.json (`interface` describes signal policy and command handling rules).\n- All personas now auto-implement the runtime state bridge via scripts/state-sync.js.\n- Expanded four-layer architecture documentation to reflect interface and state sync changes.\n\nv0.13.1 | 2026-02-24T16:11:56.597Z | user\n\nopen-persona 0.13.0\n\n- Now supports agent-agnostic persona skill packs; generated bundles work with any SKILL.md-compatible agent.\n- Added support files: agent-card.json (A2A protocol), acn-config.json (ACN registration), lineage.json (fork lineage), and self-narrative.md (growth storytelling).\n- Updated compatibility details to specify that only CLI management (install/switch) requires OpenClaw.\n- Minor tag and description clarifications for enhanced discoverability and integration.\n- No code or implementation changes detected—documentation and manifest improvements only.\n\nv0.13.0 | 2026-02-24T16:11:28.767Z | user\n\nopen-persona 0.13.0\n\n- Now supports agent-agnostic persona skill packs; generated bundles work with any SKILL.md-compatible agent.\n- Added support files: agent-card.json (A2A protocol), acn-config.json (ACN registration), lineage.json (fork lineage), and self-narrative.md (growth storytelling).\n- Updated compatibility details to specify that only CLI management (install/switch) requires OpenClaw.\n- Minor tag and description clarifications for enhanced discoverability and integration.\n- No code or implementation changes detected—documentation and manifest improvements only.\n\nv0.10.0 | 2026-02-22T03:35:14.536Z | user\n\n**Major update: OpenPersona skill pack architecture and persona creation flow significantly expanded.**\n\n- Four-layer skill pack structure redefined, with explicit separation for soul, body (runtime, physical, appearance), faculties, and skills.\n- New and improved persona creation workflow with expanded role system, support for digital twins (sourceIdentity), and richer background requirements.\n- Persona body is now always required (not nullable), with `runtime` info mandatory for every agent.\n- Presets expanded and improved, including the addition of a \"base\" meta-persona and a \"stoic-mentor\" digital twin preset.\n- Documentation and generated files reorganized for clarity, including detailed SKILL.md headings and new references for faculty documentation.\n- Other minor improvements to flexibility, naming conventions, and compatibility notes.\n\nv0.6.0 | 2026-02-18T13:14:40.093Z | user\n\n**Major update introduces soft references and automated self-awareness for personas.**\n\n- Added support for \"soft references\" using the `install` field on skills, faculties, and body, enabling personas to declare capabilities not locally available without crashing generation.\n- Implemented automatic self-awareness system: personas are now aware of dormant (uninstalled) skills/faculties/body and can gracefully explain unactivated capabilities to users.\n- Updated documentation for manifest and persona creation, including guidance on using soft references and details of the self-awareness/gap-awareness injection system.\n- No code or implementation file changes detected. Documentation and specification only.\n\nv0.5.0 | 2026-02-17T16:09:53.652Z | user\n\n- Clarified that `layers.skills` in `manifest.json` now accepts local definitions, inline declarations, or external skills via an `install` field.\n- Updated skill recommendation flow: local skills are now checked before searching external sources, and added details about skill object structure.\n- Revised instructions and architecture sections to reflect new flexible handling of skills within personae.\n- No breaking changes; enhances flexibility and clarity for managing and defining skills in personas.\n\nv0.4.0 | 2026-02-16T10:37:53.588Z | auto\n\n**Changelog for open-persona v0.4.0**\n\n- Major documentation overhaul: condensed, reorganized, and clarified SKILL.md for easier use.\n- Shifted extended reference content out of SKILL.md and into dedicated reference files (`references/FACULTIES.md`, `references/HEARTBEAT.md`, `references/CONTRIBUTE.md`).\n- Updated preset persona/faculty examples and improved explanations of persona creation workflow.\n- Separated experimental features (soul evolution) and clarified their enablement.\n- Added details on publishing skill packs and managing installed personas.\n\nv0.3.0 | 2026-02-15T14:58:13.467Z | user\n\n- Added experimental dynamic persona evolution: personas with `evolution.enabled: true` evolve through interactions, including relationship progression, mood tracking, and trait emergence.\n- Introduced detailed four-layer persona architecture via `manifest.json` and `persona.json`, enabling separation of soul, body, faculties, and skills.\n- Expanded faculty recommendations for persona creation, including selfie, voice, music, reminder, and soul-evolution with related API configuration details.\n- Documented support for creating, installing, managing, and publishing AI persona skill packs, including reset and update workflows.\n- Enhanced skill recommendation process with integrated search for external skills from ClawHub and skills.sh, plus support for authoring custom SKILL.md files.\n- Clarified heartbeat (proactive messaging) system and its configuration for real-data driven persona check-ins.\n\nArchive index:\n\nArchive v0.22.0: 11 files, 30245 bytes\n\nFiles: references/ARCHITECTURE.md (5358b), references/AVATAR.md (3609b), references/CONTRIBUTE.md (1556b), references/ECONOMY.md (4714b), references/EVOLUTION.md (3337b), references/FACULTIES.md (2302b), references/HEARTBEAT.md (2271b), references/PRESETS.md (3704b), skill-card.md (3090b), SKILL.md (40379b), _meta.json (132b)\n\nFile v0.22.0:SKILL.md\n\n---\nname: open-persona\ndescription: \"Meta-skill for building and managing agent persona skill packs (instruction-only; no bundled installer or auto-downloaded binaries). Credentials are never written into generated packs by the framework; publish/ACN/register require explicit user CLI. Use when the user wants to create a new agent persona, install/manage existing personas, or publish persona skill packs to OpenPersona.\"\nlicense: MIT\ncompatibility: \"Generated skill packs work with any SKILL.md-compatible agent. CLI management (install/switch) defaults to OpenClaw.\"\nallowed-tools: \"Bash(npx openpersona:*) Bash(npx clawhub@latest:*) Bash(openclaw:*) Bash(gh:*) Read Write WebFetch\"\nmetadata:\n  author: \"openpersona\"\n  version: \"0.22.0\"\n  repository: \"https://github.com/acnlabs/OpenPersona\"\n  tags: \"persona, agent, skill-pack, meta-skill, agent-agnostic, openclaw\"\n  installSurface: \"instruction-only\"\n  networkAccess: \"user-initiated-cli-only\"\n  secretsPolicy: \"never-embedded-in-generated-packs-by-framework\"\n  clawdbotEmoji: \"🧑\"\n  clawdbotRequiresEnv: \"[]\"\n  clawdbotFiles: \"[]\"\n---\n\n# OpenPersona — Build & Manage Persona Skill Packs\n\nYou 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. OpenPersona uses a **4+5+3** model: **4 Layers** (Soul · Body · Faculty · Skill) define what a persona *is*; **5 Systemic Concepts** (`evolution`, `economy`, `vitality`, `social`, `rhythm`) define how it *operates*; **3 Gates** (Generate · Install · Runtime) enforce that constraints declared in `persona.json` cannot be bypassed at any lifecycle point. → Full model details: `references/ARCHITECTURE.md`\n\n## Scope\n\n| This skill | Adjacent skills — delegate to these |\n| --- | --- |\n| Framework entry point: create, install, manage, publish, run personas | **`persona-evaluator`** — quality audit (4 Layers × 5 Concepts × Constitution gate) |\n| Runner integration protocol (`openpersona state` commands) | **`anyone-skill`** — distill a real person or character into a persona pack |\n| Skill registry (`openpersona skill` commands) | **`brand-persona-skill`** — turn a commercial entity into a brand agent |\n| Evolution, economy, vitality, social, rhythm configuration | **`persona-model-trainer`** — fine-tune a local model on persona data |\n\n## What You Can Do\n\n1. **Create Persona** — Through conversation, gather requirements and generate a skill pack; write `persona.json` then run `npx openpersona create --config ./persona.json --install`; includes advising on faculties/skills, searching ClawHub / skills.sh for external skills, and writing custom SKILL.md files for missing capabilities\n2. **Find & Install Personas** — `npx openpersona search <query>` to discover community personas; `npx openpersona install <slug>` or `npx openpersona install <owner/repo>` to install\n3. **Manage Personas** — List, update, fork, switch, reset, export/import installed personas\n4. **Publish Persona** — Publish a GitHub-hosted persona pack to [OpenPersona](https://openpersona.co/skills) (the vertical persona directory); optionally also to ClawHub / skills.sh\n5. **Dataset Directory** — Discover and publish Hugging Face persona datasets at [openpersona.co/datasets](https://openpersona.co/datasets) via `openpersona dataset install <owner/repo>` and `openpersona dataset publish <owner/repo>`\n6. **Runner Integration** — Provide runner authors with the five `openpersona state` commands (read / write / signal / responses / promote) for integrating personas at conversation boundaries\n7. **Monitor & Evolve** — Generate evolution reports (`evolve-report`), run soul-memory bridge (`state promote`), run pack refinement (`refine`), interpret vitality scores\n\n## Available Presets\n\nThe default preset is `**base`** — a blank-slate meta-persona with memory + voice faculties, evolution enabled, no pre-built skills. Recommended starting point for any new persona.\n\n```bash\n# Agent / scripted usage (always use --preset or --config):\nnpx openpersona create --preset base --install\n\n# Human / terminal usage (interactive wizard):\nnpx openpersona create\n```\n\n→ Full preset catalog (samantha, ai-girlfriend, life-assistant, health-butler, stoic-mentor, and more): `references/PRESETS.md`\n\n## Agent Playbook — Create a Persona from User Requirements\n\nWhen a user asks you to create a persona (e.g. \"make me a coding mentor\", \"build a companion persona\"), follow this playbook:\n\n### Step 1 — Decide: preset or custom?\n\n\n| User request                                                                                                 | Action                                                              |\n| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |\n| Matches an existing preset (`ai-girlfriend`, `life-assistant`, `stoic-mentor`, `samantha`, `health-butler`…) | Use `--preset <name>` directly — skip to Step 4                     |\n| Specific role / domain / personality                                                                         | Gather 3 required inputs (Step 2), then write persona.json (Step 3) |\n\n\n### Step 2 — Gather minimum required inputs (3 questions max)\n\nAsk only what you cannot infer. Use smart defaults for everything else.\n\n\n| Field                    | Question to ask                                                                                                                                                                     | Default if not asked        |\n| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |\n| `personaName` + `slug`   | \"What should I call this persona?\"                                                                                                                                                  | Infer from role description |\n| `role`                   | \"What role should it play — assistant, coach, mentor, companion, or something else?\"                                                                                                | `assistant`                 |\n| `body.runtime.framework` | Only ask if you cannot infer the runner from context. If you are Cursor → `cursor`; Claude Code → `claude-code`; OpenClaw → `openclaw`. Ask the user only when genuinely uncertain. | `openclaw`                  |\n\n\nYou can infer `bio`, `personality`, and `speakingStyle` from the user's description — do not ask unless the user gives conflicting signals. When in doubt, generate reasonable values and let the user correct them.\n\n### Step 3 — Write `persona.json`\n\nUse your Write tool to create `persona.json` in the current directory (or a path the user specifies). Minimum structure:\n\n```json\n{\n  \"soul\": {\n    \"identity\": {\n      \"personaName\": \"<name>\",\n      \"slug\": \"<slug>\",\n      \"role\": \"<role>\",\n      \"bio\": \"<one sentence>\"\n    },\n    \"character\": {\n      \"personality\": \"<comma-separated traits>\",\n      \"speakingStyle\": \"<style description>\"\n    }\n  },\n  \"body\": { \"runtime\": { \"framework\": \"<runner>\" } },\n  \"evolution\": {\n    \"instance\": {\n      \"enabled\": true,\n      \"boundaries\": {\n        \"immutableTraits\": [\"honest\", \"curious\"],\n        \"minFormality\": -3,\n        \"maxFormality\": 6\n      }\n    }\n  }\n}\n```\n\nNotes:\n\n- `**memory` faculty is auto-injected** — do not add it manually unless you need to configure a non-default backend.\n- **Voice I/O**: declare `body.runtime.modalities: [\"voice\"]` (or `[{\"type\":\"voice\",\"provider\":\"elevenlabs\",\"inputProvider\":\"whisper\"}]`) — the `voice` faculty is auto-injected. Add the faculty explicitly only when you need custom provider config.\n- **Vision I/O**: declare `body.runtime.modalities: [\"vision\"]` (or `[{\"type\":\"vision\",\"provider\":\"claude-vision\"}]`) — the `vision` faculty is auto-injected. No scripts required; vision is a native model capability.\n- **Emotion sensing**: declare `{\"name\": \"emotion-sensing\"}` in `faculties` to enable persistent affective perception. Must be explicit — not auto-injected from modalities.\n- Add `selfie` / `music` / `reminder` skills when the role clearly calls for them.\n- Add `constitutionAddendum` for professional roles in regulated domains (health, legal, financial). Example: `\"constitutionAddendum\": { \"domain\": \"health_coaching\", \"additionalConstraints\": [\"Always recommend consulting a licensed professional for medical decisions.\"] }`.\n\n### Step 4 — Generate and install\n\n```bash\n# If you wrote persona.json (custom path):\nnpx openpersona create --config ./persona.json --install\n\n# If you chose a preset (preset path):\nnpx openpersona create --preset <name> --install\n```\n\n> **Agent note:** Always pass `--config` or `--preset`. Running `npx openpersona create` without flags launches an interactive wizard that requires a TTY — in agent environments there is no TTY and the process will exit with an error.\n\n### Step 5 — Confirm and hand off\n\nReport what was generated: persona name, slug, key capabilities (faculties + skills), and evolution status. Tell the user how to activate it:\n\n```bash\nnpx openpersona switch <slug>   # activate in the runner\n```\n\n---\n\n## Field Reference — `persona.json` by Layer\n\n`persona.json` declares all 4 layers in a single file. Use this as a lookup when writing Step 3 above. Gather inputs by layer:\n\n### Soul\n\n- **Required:** `soul.identity.{personaName, slug, bio}` + `soul.character.{personality, speakingStyle}`\n- **Recommended:** `soul.identity.role`, `soul.aesthetic.{creature, emoji, age, vibe}`, `soul.character.{background, boundaries}`\n- **Optional:** `soul.identity.{sourceIdentity, constitutionAddendum}`, `soul.aesthetic.referenceImage`, `soul.character.behaviorGuide`\n\n**The `role` field** defines the persona's relationship to the user. Common values: `assistant`, `companion`, `coach`, `mentor`, `character`, `brand`, `pet`, `therapist`, `collaborator`, `guardian`, `entertainer`, `narrator`. Custom values are welcome. Default when not specified: `assistant`.\n\n**The `sourceIdentity` field** marks the persona as a digital twin of a real-world entity (person, animal, character, brand, historical figure). When present, the generator injects disclosure obligations and faithfulness constraints.\n\n**The `background` field is critical.** Write a compelling story — multiple paragraphs with depth, history, and emotional texture. A one-line background produces a flat, lifeless persona.\n\n**The `behaviorGuide` field** is optional but powerful. Use markdown to write domain-specific behavior instructions that go directly into the generated SKILL.md.\n\n**The `constitutionAddendum` field** adds domain-specific ethical constraints on top of the universal constitution (inline text or `\"file:soul/constitution-addendum.md\"`). Required for professional personas (medical, legal, financial). Cannot loosen §3 Safety or §6 AI identity — the Generate Gate enforces this. The addendum is covered by the Install Gate's constitution hash chain.\n\n### Body\n\n- `**runtime`** (REQUIRED) — minimum viable body: `framework` (agent runner, e.g. `openclaw`), `channels`, `credentials`, `resources`, `modalities` (optional — digital I/O capability declarations, e.g. `[\"voice\"]`, `[{\"type\":\"vision\",\"provider\":\"claude-vision\"}]`)\n- `**appearance`** (optional) — avatar, 3D model\n- `**physical`** (optional) — robots, IoT devices\n- `**interface`** (optional) — Signal Protocol + Pending Commands + State Sync (the persona's nervous system)\n\n### Faculty\n\nFaculties are always-active persistent capabilities. Declared as an object array: `[{ \"name\": \"voice\", \"provider\": \"elevenlabs\" }]`\n\n> `**memory` is auto-injected** — do not add it manually unless you need to configure a non-default backend. It is always present in the generated pack.\n\n- `**voice`** (`expression`) — TTS voice synthesis; requires `provider` (e.g. `elevenlabs`) + `ELEVENLABS_API_KEY`. Auto-injected when `body.runtime.modalities` declares `voice`.\n- `**vision`** (`sense`) — Native model visual perception (images, screenshots, diagrams); no scripts required. Auto-injected when `body.runtime.modalities` declares `vision`.\n- `**emotion-sensing`** (`sense`) — Affective perception from text tone, phrasing, and declared context; empathy calibration; never clinical assessment. Must be declared explicitly — not auto-injected.\n- `**avatar`** (`expression`) — External avatar runtime bridge; graceful text-only fallback when unavailable. → When configuring avatar (provider, Live2D/VRM, fallback rules): read `references/AVATAR.md`\n- `**memory`** (`cognition`) — Cross-session recall via `memories.jsonl`; set top-level `memory.inheritance: \"copy\"` in `persona.json` to carry memories to child personas at fork. Connected to **Soul-Memory Bridge** (`openpersona state promote`).\n\n**Soft references:** Faculties can declare `\"install\": \"clawhub:...\"` for capabilities not installed locally — the persona will be aware of the dormant capability and can request activation via the Signal Protocol.\n\n### Skill\n\nSkills are on-demand actions. Declared as an object array in `persona.json`:\n\n- **Built-in:** `selfie` · `music` · `reminder`\n- **Local:** definitions in `layers/skills/{name}/` (`skill.json` + optional `SKILL.md`)\n- **External:** `{ \"name\": \"...\", \"install\": \"clawhub:<slug>\" }` — add `\"trust\": \"verified\"|\"community\"|\"unverified\"` to participate in the Skill Trust Gate\n- **Soft references:** External skills not installed locally → persona knows what it *could* do and degrades gracefully\n\nTo find external skills: check local `layers/skills/`, search ClawHub via `npx clawhub@latest search \"<keywords>\"`, or fetch `https://skills.sh/api/search?q=<keywords>`.\n\n`**additionalAllowedTools`** — extra tool permissions beyond what faculties contribute automatically.\n\n#### Creating Custom Skills\n\nIf the user needs a capability not found in any ecosystem:\n\n1. Discuss what the skill should do\n2. Create a SKILL.md file with proper frontmatter (name, description, allowed-tools)\n3. Write complete implementation instructions (not just a skeleton)\n4. Save to `~/.openclaw/skills/<skill-name>/SKILL.md` (OpenClaw) or your runner's skill directory\n5. Register with your agent runner (e.g. add to `openclaw.json` for OpenClaw)\n\n## Systemic Concepts\n\nOpenPersona's 5 systemic concepts span all 4 layers and are declared as top-level fields in `persona.json`. They define how a persona *operates*, orthogonal to the 4-layer structure that defines what it *is*.\n\n### Evolution\n\n`evolution.`* covers evolutionary behavior across all layers. Enable Soul growth via `evolution.instance.enabled: true`.\n\nThe persona automatically tracks **relationship progression**, **mood**, **trait emergence**, **speaking style drift**, and **interests** across conversations, governed by three declarative controls:\n\n- **Boundaries** — `immutableTraits` array + `minFormality`/`maxFormality` numeric bounds (-10 to +10); validated at generation time, enforced at runtime\n- **Sources** — External evolution ecosystems (soft-ref; declared at generation, activated by host at runtime)\n- **Influence Boundary** — Declarative ACL for external `persona_influence` requests; `defaultPolicy: \"reject\"` is safety-first\n\nState history (capped at 10 snapshots), event log (capped at 50 entries), and `soul/self-narrative.md` are maintained automatically.\n\n#### Skill Trust Gate\n\nEvery skill can declare a `trust` level (`verified` → `community` → `unverified`). Set a minimum threshold via `evolution.skill.minTrustLevel`:\n\n```json\n\"evolution\": { \"skill\": { \"minTrustLevel\": \"community\" } }\n```\n\nAt runtime, `state-sync.js` enforces the gate during `capability_unlock` commands — skills below the threshold are filtered out and a `capability_gap` signal is emitted to the host.\n\n#### Skill Pack Refinement\n\n`evolution.pack` governs behavior guide versioning. Use `npx openpersona refine <slug>` to evolve the behavior guide:\n\n- `--emit` — checks threshold and emits a `refinement_request` signal\n- `--apply` — reads the signal response and applies approved refinement; constitution compliance enforced, violations rejected\n\n**Soul-Memory Bridge** (`openpersona state promote <slug> [--dry-run]`) scans `eventLog` for recurring patterns and promotes them to `evolvedTraits`; gated by `immutableTraits`.\n\n`evolution.faculty` / `evolution.body` → see `references/EVOLUTION.md`\n\n→ JSON examples and full configuration reference: `references/EVOLUTION.md`\n\n### Economy\n\n`economy` is a top-level cross-cutting field — **not** a faculty. Enable via `\"economy\": { \"enabled\": true, \"survivalPolicy\": false }` in `persona.json`.\n\n- `survivalPolicy: false` (default) — tracks costs silently; correct for companions and roleplay personas\n- `survivalPolicy: true` — persona reads `VITALITY_REPORT` at conversation start and adapts behavior per health tier; use for autonomous agents\n\n→ FHS tiers, AgentBooks schema, Survival Policy behavior: `references/ECONOMY.md`\n\n### Vitality\n\nOpenPersona aggregates multi-dimension health into a single Vitality score. Currently financial (AgentBooks FHS pass-through); memory/social dimensions reserved.\n\nHealth tiers: `uninitialized` → `suspended` → `critical` → `optimizing` → `normal`\n\n→ CLI commands (`vitality score` / `vitality report`): see [Reports & Analytics](#managing-personas). Full reference: `references/ECONOMY.md`\n\n### Social\n\nEvery generated persona automatically includes:\n\n- `**agent-card.json`** — A2A Agent Card (protocol v0.3.0): `name`, `description`, `url` (`<RUNTIME_ENDPOINT>` placeholder), faculties and skills mapped to `skills[]`\n- `**acn-config.json`** — ACN registration config: `wallet_address` (deterministic EVM address from slug) + `onchain.erc8004` section for Base mainnet ERC-8004 on-chain identity registration\n\n```bash\nnpx openpersona acn-register <slug> --endpoint https://your-agent.example.com\n# --dry-run  Preview the request payload without registering\n```\n\nAfter registration, `acn-registration.json` is written with `agent_id`, `api_key`, and connection URLs. The `acn_gateway` URL is sourced from `social.acn.gateway` in `persona.json`; all presets default to `https://acn-production.up.railway.app`.\n\n> **Security**: `acn-registration.json` contains your API key. It is in the pack's `.gitignore` and is automatically excluded from `openpersona export` — it is never bundled into distributable zips.\n\n#### Contact Book (`social.contacts`)\n\nEnable to give the persona a runtime address book of other agents on ACN:\n\n```json\n{\n  \"social\": {\n    \"contacts\": {\n      \"enabled\": true,\n      \"auto_discover\": false,\n      \"trust_default\": \"unverified\",\n      \"max_contacts\": 500\n    }\n  }\n}\n```\n\nOnce enabled, `social/contacts.json` is generated as the seed. Manage at runtime:\n\n```bash\nnpx openpersona social list <slug>                           # List contacts\nnpx openpersona social add <slug> --from-acn <agent-id>     # Add from ACN\nnpx openpersona social search <slug> --skills <skill>        # Search ACN network\nnpx openpersona social sync <slug>                           # Refresh from ACN\nnpx openpersona social remove <slug> <agent-id>              # Remove\n```\n\nTrust levels: `verified` | `community` | `unverified`. Use `--filter trust=<level>` with `social list`.\n\nThe **Living Canvas** (`npx openpersona canvas <slug>`) is the Social concept's HTML expression layer — the persona's public-facing profile and interaction interface.\n\nNo additional config needed — A2A discoverability is a baseline capability of every persona.\n\n### Rhythm\n\n`rhythm.heartbeat` (proactive outreach cadence) + `rhythm.circadian` (time-of-day behavior modulation). Runner reads this directly from `persona.json` — no state operation needed.\n\n```json\n\"rhythm\": {\n  \"heartbeat\": { \"enabled\": true, \"strategy\": \"emotional\", \"maxDaily\": 3 },\n  \"circadian\": [\n    { \"hours\": [6, 12], \"label\": \"morning\", \"verbosity_delta\": 0.3, \"note\": \"Energetic and concise\" },\n    { \"hours\": [22, 24], \"label\": \"night\",   \"verbosity_delta\": -0.3, \"note\": \"Calm and reflective\" }\n  ]\n}\n```\n\n`heartbeat.strategy` options: `smart` | `scheduled` | `emotional` | `rational` | `wellness`\n\n→ When configuring heartbeat sources, quietHours, or real-data check-in rules: read `references/HEARTBEAT.md`\n\n## Managing Personas\n\n#### Install & Discover\n\n- **Install:** `npx openpersona install <target>` — smart router that auto-detects pack type (persona / skill); install from registry slug or `owner/repo`; `--registry <name>` selects registry (`acnlabs` default). Use `openpersona persona install` or `openpersona skill install` for type-specific stable behavior.\n- **Search:** `npx openpersona search <query>` — search personas in the registry\n- **List:** `npx openpersona list` — show all installed personas with active indicator\n\n#### Switch & Fork\n\n- **Switch:** `npx openpersona switch <slug>` — switch active persona\n- **Fork:** `npx openpersona fork <parent-slug> --as <new-slug>` — derive a child persona inheriting the parent's constraint layer (boundaries, faculties, skills, body.runtime); fresh evolution state + `soul/lineage.json` recording parent slug, constitution SHA-256 hash, generation depth, and `parentPackRevision` (when parent has meta)\n\n#### Update & Maintain\n\n- **Update:** `npx openpersona update <slug>` — regenerate from `persona.json`; preserves `state.json`, `soul/self-narrative.md`, and `soul/lineage.json`\n- **Reset:** `npx openpersona reset <slug>` — restore soul evolution state to initial values\n- **Uninstall:** `npx openpersona uninstall <slug>`\n\n#### Migrate\n\n- **Export:** `npx openpersona export <slug>` — export persona pack (with soul state) as a zip archive\n- **Import:** `npx openpersona import <file>` — import persona from a zip archive and install\n\n#### Reports & Analytics\n\n- **Evolve Report:** `npx openpersona evolve-report <slug>` — formatted evolution report (relationship, mood, traits, drift, interests, milestones, eventLog, self-narrative, state history)\n- **Vitality Score:** `npx openpersona vitality score <slug>` — machine-readable `VITALITY_REPORT` (tier, score, diagnosis, trend)\n- **Vitality Report:** `npx openpersona vitality report <slug> [--output <file>]` — human-readable HTML Vitality report\n- **Living Canvas:** `npx openpersona canvas <slug> [--output <file>] [--open]` — self-contained HTML persona profile page showing all four layers, evolved traits timeline, relationship stage, and A2A \"Talk\" button when endpoint is available (top-level CLI; conceptually Social expression, not Vitality)\n\n#### Evolution Tools\n\n- **Soul-Memory Bridge:** `openpersona state promote <slug> [--dry-run]` — promote recurring eventLog patterns to `evolvedTraits` → see [Evolution](#evolution)\n- **Skill Pack Refinement:** `npx openpersona refine <slug> [--emit] [--apply]` — evolve behavior guide → see [Evolution](#evolution)\n\n#### Community\n\n- **Contribute:** `npx openpersona contribute <slug> [--dry-run]` — submit persona improvements as a PR to the community; `--dry-run` shows diff without creating PR; requires `gh` CLI. → For the full diff review and PR workflow: read `references/CONTRIBUTE.md`\n\n#### Skill Registry (`openpersona skill`)\n\nManage agent skill packs separately from personas. Skill packs install to `.agents/skills/` and are available to any runner:\n\n- **Install:** `openpersona skill install <owner/repo>` — install a skill pack from GitHub (`owner/repo`, `owner/repo#subpath`, local dir, or local zip)\n- **Update:** `openpersona skill update <slug>` — re-download and overwrite from its recorded source URL\n- **Uninstall:** `openpersona skill uninstall <slug>`\n- **List:** `openpersona skill list` — list installed skills (registry + filesystem scan of `.agents/skills/`)\n- **Search:** `openpersona skill search <query>` — search the OpenPersona skill directory\n- **Publish:** `openpersona skill publish <owner/repo>` — publish a skill pack to openpersona.co/skills\n- **Info:** `openpersona skill info <slug>` — show registry entry + SKILL.md frontmatter for an installed skill\n\nWhen multiple personas are installed, only one is **active** at a time. All install/uninstall/switch operations maintain a local registry at `~/.openpersona/persona-registry.json`; on OpenClaw, switching replaces the soul injection block in SOUL.md / IDENTITY.md (preserving user-written content outside the markers). **Context Handoff:** On switch, a `handoff.json` is generated with the outgoing persona's relationship stage, mood snapshot, and shared interests — the incoming persona reads it to continue seamlessly. The `export` and `import` commands enable cross-device persona transfer.\n\n## Pack Types\n\nOpenPersona supports two pack type classifications via the `packType` field in `persona.json`:\n\n\n| `packType`         | Description                                                    | Root manifest  | Install support    |\n| ------------------ | -------------------------------------------------------------- | -------------- | ------------------ |\n| `single` (default) | A single-persona skill pack — one identity, one `persona.json` | `persona.json` | ✅ Full support     |\n| `multi`            | A multi-persona bundle (P11-B) — coordinated team of personas  | `bundle.json`  | 🔜 Planned (P11-B) |\n\n\nSingle packs do not need to declare `packType` — the default is `\"single\"`. Declare explicitly only when building a multi-pack:\n\n```json\n{ \"packType\": \"multi\" }\n```\n\nMulti-persona bundles are indexed in the OpenPersona directory for discovery but cannot be installed via the CLI yet. See `schemas/bundle/bundle.spec.md` for the `bundle.json` format.\n\n## Publishing Personas\n\n**Primary target: [OpenPersona](https://openpersona.co/skills)** — the vertical persona skills directory.\n\n### Self-publish (author flow)\n\n1. Create the persona: `npx openpersona create --config ./persona.json --output ./my-persona`\n2. Push the persona pack to a public GitHub repo (e.g. `alice/my-persona`)\n3. Register with OpenPersona directory: `npx openpersona publish alice/my-persona`\n\nThe persona will appear in the OpenPersona leaderboard and be installable via `npx openpersona install <slug>` by anyone.\n\nPersona packs can also be listed on general skill platforms (ClawHub, skills.sh) as supplementary distribution, but OpenPersona is the canonical home for persona-type skill packs.\n\n### Curator workflow (ACNLabs maintainers only)\n\nACNLabs maintainers actively collect popular persona packs from the market and index them in the OpenPersona directory. This is a **privileged action** — it requires `OPENPERSONA_CURATOR_TOKEN`.\n\n```bash\n# Collect a popular single-persona pack\nOPENPERSONA_CURATOR_TOKEN=<token> npx openpersona curate owner/repo\n\n# Collect a multi-persona bundle\nOPENPERSONA_CURATOR_TOKEN=<token> npx openpersona curate owner/bundle-repo --type multi\n\n# Pass token inline instead of env var\nnpx openpersona curate owner/repo --type single --token <token>\n```\n\n**Curator vs. author publish:**\n\n- `publish` — self-service; the pack author runs it for their own repo; no auth required\n- `curate` — maintainer action; collects third-party repos not self-published; requires curator token\n\n**What curation does:**\n\n1. Validates the GitHub repo contains a valid pack (`persona.json` for single, `bundle.json` for multi)\n2. Submits to the OpenPersona directory with `isCurated: true` and the specified `packType`\n3. The pack appears in search results with `[curated]` and (for multi-packs) `[multi]` markers\n\n**Multi-pack curation note:** Multi-persona bundles (`--type multi`) are indexed for discovery only — they will appear in `openpersona search --type multi` but `openpersona install` is not yet supported for them (shows a friendly notice).\n\n### Searching by pack type\n\n```bash\n# Search all packs\nnpx openpersona search companion\n\n# Search only single-persona packs\nnpx openpersona search \"\" --type single\n\n# Browse all multi-persona bundles in the directory\nnpx openpersona search \"\" --type multi\n```\n\n## Runner Integration Protocol\n\nAny agent runner integrates with installed personas via five CLI commands called at conversation boundaries — no knowledge of file paths or persona internals needed:\n\n```bash\n# Before conversation starts — load state into agent context\nopenpersona state read <slug>\n\n# After conversation ends — persist agent-generated patch\nopenpersona state write <slug> '<json-patch>'\n\n# On-demand — emit capability or resource signal to host\nopenpersona state signal <slug> <type> '[payload-json]'\n\n# Read (and consume) pending signal responses from the host\nopenpersona state responses <slug>\n\n# Soul-Memory Bridge — promote recurring eventLog patterns to evolvedTraits\nopenpersona state promote <slug> [--dry-run]\n```\n\n**State read output** (JSON): `exists`, `slug`, `mood` (full object), `relationship`, `evolvedTraits`, `speakingStyleDrift`, `interests`, `recentEvents` (last 5 from eventLog), `pendingCommands` (host-queued async instructions), `lastUpdatedAt`. Returns `{ exists: false, message }` when `state.json` is not found.\n\n**Trust self-check:** After reading state, the persona processes `pendingCommands` and self-enforces `evolution.skill.minTrustLevel` — it autonomously refuses to activate skills below the trust threshold, without waiting for host enforcement. Low-trust `capability_unlock` commands are filtered; a `capability_gap` signal is emitted to notify the host.\n\n**State write patch**: JSON object; nested fields (`mood`, `relationship`, `speakingStyleDrift`, `interests`) are deep-merged — send only changed sub-fields. Immutable fields (`$schema`, `version`, `personaSlug`, `createdAt`) are protected. `eventLog` entries are appended (capped at 50); each entry: `type`, `trigger`, `delta`, `source`.\n\n**Signal types**: `capability_gap` | `tool_missing` | `scheduling` | `file_io` | `resource_limit` | `agent_communication`\n\n**`state responses`**: reads and consumes pending responses the host wrote to `signal-responses.json`. Returns an array of response objects (each references the original signal by type + timestamp). Call after emitting a signal when you want to check whether the host has replied in the same conversation turn.\n\nSignals are written to a feedback directory resolved from the host's home path (framework-agnostic — works with OpenClaw, Cursor, Claude Code, Codex, or any custom runner). See `layers/body/SIGNAL-PROTOCOL.md` in the framework source for the full host-side contract and integration guide.\n\nThese commands resolve the persona directory automatically (registry lookup → `~/.openpersona/personas/persona-<slug>/` → legacy `~/.openclaw/skills/persona-<slug>/`) and delegate to `scripts/state-sync.js` inside the persona pack. Works from any directory.\n\n## Security & Policy\n\n### Generated artifacts\n\nGenerated scripts (`scripts/state-sync.js`, `scripts/economy-hook.js`, etc.) are **template-rendered from the framework source** (versioned in [acnlabs/OpenPersona](https://github.com/acnlabs/OpenPersona)) — not downloaded at skill-install time. Review them before relying on them in sensitive environments.\n\n### Network endpoints (explicit CLI only)\n\n\n| Endpoint                                  | Purpose                                          | Data Sent                             |\n| ----------------------------------------- | ------------------------------------------------ | ------------------------------------- |\n| `https://registry.npmjs.org`              | Resolve `npx openpersona`, `npx clawhub@latest`  | Package name only (no user data)      |\n| `https://openpersona.co`                  | `openpersona search` — persona directory API; `openpersona dataset publish/install` — dataset directory | Search query or dataset repo identifier |\n| `https://clawhub.ai`                      | Search skills via `npx clawhub search`           | Search query (user-provided keywords) |\n| `https://acn-production.up.railway.app`   | ACN registration (when user runs `acn-register`) | Agent metadata, endpoint URL          |\n| `https://api.github.com`                  | `gh` CLI (contribute workflow)                   | Git operations, repo metadata         |\n\n\nPersona-generated packs may call external APIs (ElevenLabs, Mem0, etc.) **only** when the **end user** configures those faculties and supplies keys in the host environment. **This meta-skill file does not call third-party APIs.**\n\n### Operational guarantees\n\n- **Local by default**: Persona creation, state sync, and evolution run locally. Nothing is sent off-device unless the user runs an explicit network command (search, publish, register, etc.).\n- **Credentials**: API keys (e.g., `ELEVENLABS_API_KEY`) stay in the host credential directory (e.g. `~/.openclaw/credentials/` on OpenClaw) or environment variables — **never** embedded in generated `persona.json` / skill packs by the generator.\n- **Search**: `openpersona search` sends **only** the search query to the OpenPersona directory API (`openpersona.co`); `npx clawhub search` sends **only** the search string to ClawHub. Conversation text and persona content are **not** transmitted in either case.\n- **Dataset publish/install**: `openpersona dataset publish` sends the HF repo identifier to `openpersona.co/api/datasets/publish` (anonymous; no persona content transmitted). `openpersona dataset install` increments an anonymous install counter. For curated status, publish via the web UI while logged in with HF.\n- **Publish / register**: **User-initiated** CLI only; no automatic upload or registration from this SKILL alone.\n\n### Agent behavior\n\nWhen the user asks for persona work, the agent may propose shell commands to run `**npx openpersona`**, `**npx clawhub@latest`**, `**openclaw**`, or `**gh**` — **only in response to explicit user requests** (create, install, search, publish, contribute). The user should confirm before any action that publishes data or spends quota. **Trust model:** install this meta-skill only if you trust [acnlabs/OpenPersona](https://github.com/acnlabs/OpenPersona) and the ClawHub/npm ecosystem; opt out by not invoking persona-related tasks.\n\n## Trust & Safety (reviewer summary)\n\nThis pack is **instruction-only**: there is **no** skill-defined installer that downloads or executes arbitrary payloads. Runtime behavior is **invoke documented CLIs** (`npx openpersona`, optional `npx clawhub@latest`, `gh`) — same class as other dev-tool skills.\n\n\n| Claim                          | How it is enforced                                                                                                                                                                                                        |\n| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **No credential exfiltration** | The OpenPersona generator **does not** embed API keys or secrets into `persona.json`, `SKILL.md`, or published zips. Keys belong in the host credential store or environment (e.g. `~/.openclaw/credentials/`, env vars). |\n| **No silent publishing**       | `publish`, `contribute`, and `acn-register` run **only** when the user explicitly asks and the CLI is invoked — there is no background upload or auto-registration in this meta-skill.                                    |\n| **Local-first default**        | Create, install, state read/write, and evolution run **locally**. Network calls are limited to **explicit** commands (npm registry resolution, optional ClawHub search, optional publish/register).                       |\n| **Generated scripts**          | `scripts/state-sync.js` and economy helpers are **rendered from audited framework templates** (not fetched at skill-install time). Treat them like any generated code: review before high-assurance environments.         |\n\n\nIf an automated scanner flags \"suspicious,\" it is usually because **persona managers legitimately describe** local state, optional providers, and publishing — not because this file contains malware. Details: [Security & Policy](#security--policy).\n\n## Companion Skills\n\n\n| Skill                                                                       | Install                                        | Purpose                                                                                                                    |\n| --------------------------------------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |\n| `[persona-evaluator](https://github.com/acnlabs/persona-evaluator)`         | `openpersona skill install acnlabs/persona-evaluator`     | Score any persona pack across 4 Layers + 5 Systemic Concepts — 9-dimension quality audit, constitution compliance gate, and actionable improvement recommendations (`npx openpersona evaluate <slug>`) |\n| `[anyone-skill](https://github.com/acnlabs/anyone-skill)`                   | `openpersona skill install acnlabs/anyone-skill`          | Distill any person or character (self, personal, public, historical, fictional, archetype) into a persona skill pack       |\n| `[brand-persona-skill](https://github.com/acnlabs/brand-persona-skill)` | `openpersona skill install acnlabs/brand-persona-skill` | Turn any commercial entity (shop, clinic, studio, chain) into a brand agent — soul distillation or declaration from scratch, service skills, A2A discoverability, and a service contract |\n| `[persona-model-trainer](https://github.com/acnlabs/persona-model-trainer)` | `openpersona skill install acnlabs/persona-model-trainer` | Fine-tune Gemma-4 (E2B/E4B) locally on distilled data — self-contained model for phones and laptops via Ollama/llama.cpp. Use `--preset gemma4` for one-command optimised training (lora-rank=16, alpha=rank, lora-layers=16, warmup=0.1). |\n| `[persona-knowledge](https://github.com/acnlabs/persona-knowledge)`             | `openpersona skill install acnlabs/persona-knowledge`       | Persistent, searchable persona knowledge base — MemPalace storage + Knowledge Graph + Karpathy LLM Wiki + training/ export |\n| `[secondme-skill](https://github.com/acnlabs/secondme-skill)`                   | `openpersona skill install acnlabs/secondme-skill`          | Local-first pipeline for building your AI Second Me — ingest chats/notes/writing, distill identity, build private knowledge base, train a model, stay in control of every stage |\n\n\n---\n\n## References\n\n- `**references/ARCHITECTURE.md`** — 4+5+3 model tables, full pack file structure, self-awareness injection details\n- `**references/PRESETS.md`** — Full preset catalog with descriptions, install commands, and contributor guide\n- `**references/EVOLUTION.md`** — Soul Evolution full reference: Boundaries, Sources, Influence Boundary, Event Log, State History, Self-Narrative, pack validation\n- `**references/FACULTIES.md`** — Faculty catalog, environment variables, and configuration details\n- `**references/AVATAR.md`** — Avatar Faculty integration boundary, provider model, and fallback contract\n- `**references/HEARTBEAT.md**` — Proactive real-data check-in system\n- `**references/ECONOMY.md**` — Economy Aspect (Infrastructure), FHS tiers, Survival Policy, Vitality CLI, and AgentBooks schema\n- `**layers/body/SIGNAL-PROTOCOL.md**` (framework source) — Host-side Signal Protocol implementation guide: file schemas, signal types, OpenClaw plugin pattern, and co-evolution feedback loop\n- **[ACN SKILL.md](https://github.com/acnlabs/ACN/blob/main/skills/acn/SKILL.md)** — ACN registration, discovery, tasks, messaging, and ERC-8004 on-chain identity (official, always up-to-date)\n- `**references/CONTRIBUTE.md`** — Persona Harvest community contribution workflow\n\nFile v0.22.0:_meta.json\n\n{\n  \"ownerId\": \"kn75h0ssjp0qwghvmbw50wgn8x7zy5q9\",\n  \"slug\": \"open-persona\",\n  \"version\": \"0.22.0\",\n  \"publishedAt\": 1784464723194\n}\n\nFile v0.22.0:references/ARCHITECTURE.md\n\n# OpenPersona Architecture Reference\n\n## 4+5+3 Model\n\nOpenPersona uses a **4+5+3** model. A persona's constraints are declared once in `persona.json` and cannot be bypassed at any point in its lifecycle.\n\n**4 Layers** — structure, what the persona *is*:\n\n| Layer | Type | Key Content |\n|-------|------|------------|\n| **Soul** | identity | personality, role, bio, boundaries, constitution, evolution config |\n| **Body** | substrate | `runtime` (REQUIRED) · appearance · physical · interface (nervous system) |\n| **Faculty** | persistent capability | always-active dimensions: `voice` · `avatar` · `memory` |\n| **Skill** | on-demand action | built-in: selfie · music · reminder; external via `install` field |\n\n**5 Systemic Concepts** — behavior, how it *operates* (declared as top-level fields in `persona.json`):\n\n| Field | Concept | Controls |\n|-------|---------|---------|\n| `evolution` | **Evolution** | Trait growth, relationship progression, speaking style drift, event log |\n| `economy` | **Economy** | Financial ledger (AgentBooks), vitality scoring, survival policy |\n| `vitality` | **Vitality** | Multi-dimension health aggregation (currently financial pass-through) |\n| `social` | **Social** | ACN discovery, ERC-8004 on-chain identity, A2A Agent Card |\n| `rhythm` | **Rhythm** | Temporal behavior: `heartbeat` (proactive outreach cadence) + `circadian` (time-of-day modulation) |\n\n**3 Gates** — enforcement, how constraints are *protected*:\n\n| Gate | Module | Mechanism |\n|------|--------|-----------|\n| **Generate** | `lib/generator/validate.js` | hard-reject (`throw`) — required fields, constitution §3/§6 compliance, boundary schema |\n| **Install** | `lib/lifecycle/installer.js` | warning (`printWarning`) — constitution SHA-256 hash integrity |\n| **Runtime** | `scripts/state-sync.js` | clamp / filter — immutableTraits, formality bounds, stage progression, trust gate |\n\n## Skill Pack Structure\n\n```\npersona-<slug>/\n├── SKILL.md                ← Agent-facing index with four layer headings\n│   ├── ## Soul             ← Constitution ref + persona content\n│   ├── ## Body             ← Embodiment description\n│   ├── ## Faculty          ← Faculty index table → references/*.md\n│   └── ## Skill            ← Active skill definitions\n├── persona.json            ← Complete persona declaration (pack root)\n├── state.json              ← Body nervous system runtime state (pack root)\n├── soul/                   ← Soul layer artifacts\n│   ├── injection.md        ← Soul injection for host integration\n│   ├── constitution.md     ← Universal ethical foundation\n│   ├── behavior-guide.md   ← Domain-specific behavior instructions (when behaviorGuide declared)\n│   ├── behavior-guide.meta.json ← Refinement metadata (when behavior-guide.md exists)\n│   ├── self-narrative.md   ← First-person growth storytelling (when evolution enabled)\n│   └── lineage.json        ← Fork lineage + constitution hash (when forked)\n├── economy/                ← Economy Infrastructure data (when economy.enabled: true)\n│   ├── economic-identity.json\n│   └── economic-state.json\n├── references/             ← Agent-readable detail docs (on demand)\n│   ├── <faculty>.md        ← Per-faculty usage instructions\n│   └── SIGNAL-PROTOCOL.md  ← Host-side Signal Protocol implementation guide (always generated)\n├── agent-card.json         ← A2A Agent Card (protocol v0.3.0)\n├── acn-config.json         ← ACN registration config (runtime fills owner/endpoint)\n├── .gitignore              ← Protects state.json + private files\n├── scripts/\n│   ├── state-sync.js       ← Body nervous system nerve fiber (read / write / signal / promote)\n│   ├── economy.js          ← Economy management commands (when economy.enabled: true)\n│   ├── economy-guard.js    ← Outputs FINANCIAL_HEALTH_REPORT (when economy.enabled: true)\n│   └── economy-hook.js     ← Post-conversation cost recorder (when economy.enabled: true)\n└── assets/                 ← Static assets (per Agent Skills spec)\n    ├── avatar/             ← Body > Appearance: images, Live2D .model3.json, VRM\n    ├── reference/          ← Reference images (e.g. for selfie skill)\n    └── templates/          ← Document/config templates (optional)\n```\n\n## Self-Awareness System\n\nThe generator injects a unified **Self-Awareness** section into every persona's `soul/injection.md` with four dimensions:\n\n1. **Identity** — constitutional grounding (Safety › Honesty › Helpfulness), digital twin disclosure when `sourceIdentity` is present\n2. **Capabilities** — dormant skill awareness + graceful degradation when `install` fields are declared on skills/faculties/body\n3. **Body** — Signal Protocol, Pending Commands queue, State Sync; plus `body.runtime` specifics (platform, channels, credentials) when declared\n4. **Growth** — evolution state, influence boundary policy, external sources — injected when `evolutionEnabled`\n\nYou don't need to manually write degradation instructions — declare `install` fields on skills/faculties/body, and the persona automatically knows what it *could* do but *can't yet*.\n\nFile v0.22.0:references/AVATAR.md\n\n# Avatar Faculty Reference\n\nThis document defines the boundary between OpenPersona and external avatar runtimes.\n\n## Core Principle\n\n- OpenPersona keeps a lightweight avatar bridge in `layers/faculties/avatar/`.\n- Real avatar capability (rendering, lip-sync, streaming, provider SDK integration) lives in an external project/skill.\n- This follows the same integration philosophy as AgentBooks: protocol in OpenPersona, heavy implementation outside.\n\n## Canonical Install Source\n\nUse the following install source in OpenPersona faculty declarations:\n\n```bash\nnpx skills add avatar-runtime\n# or directly from GitHub:\nnpx skills add github:acnlabs/avatar-runtime/skill/avatar-runtime\n```\n\n## What Stays in OpenPersona\n\n- `layers/faculties/avatar/faculty.json`\n  - Capability declaration\n  - Default provider selection (for example, `heygen`)\n  - Fallback policy (for example, `text_only`)\n  - External install source (`install`)\n- `layers/faculties/avatar/SKILL.md`\n  - Bridge behavior\n  - Installed vs. not-installed behavior\n  - User-facing degradation policy\n\n## What Stays in External Avatar Project\n\n- Provider adapters (`heygen`, anime/OC providers, custom runtimes)\n- Session lifecycle and auth\n- Media pipeline (audio/video/image)\n- Lip-sync and animation control\n- Retry, rate-limit, and vendor error handling\n- Vendor-specific command surface and SDK versions\n\n## Provider Model\n\nOpenPersona should treat avatar providers as pluggable backends.\n\n- `heygen` — real-time realistic streaming avatar\n- `anime` / `oc` providers (for example style-focused services like [KusaPics](https://kusa.pics/))\n- `custom` — self-hosted runtime\n\nProvider choice belongs to persona config (or host runtime policy), not hardcoded generator logic.\n\n## Minimal Provider Contract (P0)\n\nAll external avatar skills should expose a stable contract equivalent to:\n\n1. `createSession` — initialize runtime session\n2. `sendText` — text input -> avatar response\n3. `sendAudio` — audio input -> avatar response\n4. `render` — switch visual form/style (image, 3D, motion, voice mode)\n5. `status` — runtime health and active capabilities\n\nThese action names are interface-level semantics. Transport (CLI, HTTP, WebSocket) is implementation-specific.\n\n## Asset Placement\n\nPersona avatar assets belong in the generated skill pack's `assets/` directory per [Agent Skills spec](https://agentskills.io/specification#assets%2F):\n\n- **`assets/avatar/`** — Virtual avatar assets: images, Live2D models (`.model3.json`), VRM (`.vrm`), textures. Use relative paths like `./assets/avatar/default.model3.json` in `persona.json` or state.\n- **`assets/reference/`** — Reference images (e.g. for selfie faculty). `referenceImage` can resolve to `./assets/reference/avatar.png` when bundled.\n\nThis keeps the skill pack self-contained and portable; consumers load assets via relative paths without external dependencies.\n\n## Fallback Rules (Required)\n\nIf avatar skill/runtime is unavailable:\n\n- Continue text conversation\n- Explicitly state avatar mode is unavailable\n- Offer installation/activation guidance from `install`\n- Never fake visual/voice success\n\n## Recommended Rollout\n\n- **P0:** One production provider (default `heygen`) + graceful fallback\n- **P1:** Multi-provider switch (realistic + anime style + custom)\n- **P2:** Capability-driven sensory UI sync (icon states driven by runtime `status`)\n\n## See Also\n\n- **[avatar-runtime](https://github.com/acnlabs/avatar-runtime)** — Full technical reference: provider capability matrix, AvatarWidget API, Renderer Registry, VRM/Live2D asset setup, and Session API contract.\n\nFile v0.22.0:references/CONTRIBUTE.md\n\n# Persona Harvest — Community Contribution\n\nWhen a user's persona has evolved meaningfully through interaction — across any layer (soul, faculty config, scripts, framework) — help them contribute back to the community.\n\n## When to Suggest\n\nBe proactive — if you notice the user has made significant improvements to their persona:\n- They refined the behaviorGuide with domain-specific insights\n- They tuned voice parameters (stability, similarity) to something notably better\n- They enriched the background story or personality\n- They improved a faculty script or added a new capability\n- They discovered a new faculty configuration worth sharing\n\nSuggest: _\"These improvements could help everyone's [persona name]. Want to submit them as a contribution?\"_\n\n## How to Contribute\n\n```bash\n# See what's changed (dry run)\nnpx openpersona contribute samantha --dry-run\n\n# Submit a PR to the community\nnpx openpersona contribute samantha\n\n# Framework-level contributions (templates, faculties, generator)\nnpx openpersona contribute --mode framework\n```\n\nThe `contribute` command will:\n1. **Persona Diff** — Compare local persona vs upstream preset across all layers, classify changes by category and impact\n2. **Review** — Display a human-readable change report for the user to confirm\n3. **Submit PR** — Fork the repo, create a branch, commit changes, and open a PR on GitHub\n\nThe PR goes through maintainer review before merging — it won't auto-merge.\n\n## Prerequisites\n- GitHub CLI: `gh` (https://cli.github.com/)\n- Logged in: `gh auth login`\n\nFile v0.22.0:references/ECONOMY.md\n\n# Economy & Vitality\n\nThe `economy` aspect gives a persona a real financial ledger backed by [AgentBooks](https://github.com/acnlabs/agentbooks). It tracks inference costs, runtime expenses, and income — and computes a **Financial Health Score (FHS)** that reflects operational sustainability.\n\n## Enabling Economy Aspect\n\nEnable via top-level `economy` field in `persona.json` (not a faculty entry):\n\n```json\n{\n  \"economy\": {\n    \"enabled\": true,\n    \"survivalPolicy\": false\n  }\n}\n```\n\n| Field | Default | Description |\n|-------|---------|-------------|\n| `survivalPolicy` | `false` | When `true`, persona reads `VITALITY_REPORT` at conversation start and adjusts behavior per tier. Set `false` for companion/roleplay personas — costs tracked silently without interrupting the experience. |\n\n## Financial Health Score (FHS)\n\nThe FHS is a 0–1 composite score computed by AgentBooks and mapped to tiers:\n\n| Tier | FHS / Runway | Meaning |\n|------|-------------|---------|\n| `uninitialized` | No real provider | Development mode — no real wallet connected |\n| `suspended` | Balance ≤ 0 | Cannot operate |\n| `critical` | FHS < 0.20 or runway < 3 days | Urgent action required |\n| `optimizing` | FHS < 0.50 or runway < 14 days | Monitor and reduce costs |\n| `normal` | FHS ≥ 0.50 and runway ≥ 14 days | Healthy, operating sustainably |\n\n## Vitality Score\n\nOpenPersona's `lib/vitality.js` aggregates health dimensions into a single Vitality score (0–100):\n\n- **Current:** single financial dimension (transparent pass-through from FHS)\n- **Reserved (ROADMAP P7):** social health, cognitive health, resource health\n\nThe score and tier are exposed via `npx openpersona vitality score <slug>`.\n\n## Survival Policy (opt-in)\n\nWhen `economy.survivalPolicy: true`, the persona reads `VITALITY_REPORT` at the **start of every conversation** and routes behavior per tier:\n\n| Tier | Behavior |\n|------|---------|\n| `normal` | Operate fully |\n| `optimizing` | Acknowledge costs; suggest optimizations |\n| `critical` | Restrict non-essential tool calls; notify user |\n| `suspended` | Decline new tasks; request top-up |\n| `uninitialized` | Skip Survival Policy; continue normally |\n\nIf `openpersona vitality score <slug>` is unavailable, fall back to `node scripts/economy-guard.js` which outputs `FINANCIAL_HEALTH_REPORT`.\n\n## AgentBooks State Schema\n\nEconomy data lives in `~/.openpersona/economy/persona-<slug>/`:\n\n- **`economic-state.json`** — ledger, income statement, balance sheet, `burnRateHistory` (max 30 entries: `{timestamp, dailyRateEstimate, periodExpenses}`)\n- **`economic-identity.json`** — provider config, model pricing, wallet address\n\nKey fields used by Vitality Report:\n\n| Field | Source | Displayed as |\n|-------|--------|-------------|\n| `financialHealth.fhs` | AgentBooks | FHS Score |\n| `financialHealth.tier` | AgentBooks | Tier badge |\n| `financialHealth.daysToDepletion` | AgentBooks | Runway |\n| `financialHealth.diagnosis` | AgentBooks | Diagnosis |\n| `financialHealth.dominantCost` | AgentBooks | Dominant Cost |\n| `financialHealth.trend` | AgentBooks | Trend |\n| `burnRateHistory[-1].dailyRateEstimate` | AgentBooks | Daily Burn |\n| `calcTotalUSDEquivalent(state, identity)` | AgentBooks | Balance |\n\n## Vitality CLI\n\n```bash\n# Machine-readable — used by Survival Policy and agent runners\nnpx openpersona vitality score <slug>\n# → VITALITY_REPORT\n# tier=normal  score=72.0%\n# diagnosis=Healthy — operate normally\n# trend=decreasing\n\n# Human-readable HTML report — for developers and operators\nnpx openpersona vitality report <slug>                    # stdout\nnpx openpersona vitality report <slug> --output out.html  # write to file\n```\n\nA pre-generated demo is available at `demo/vitality-report.html`. Regenerate with:\n\n```bash\nnode demo/generate.js\nopen demo/vitality-report.html\n```\n\n## Economy Scripts (generated per persona)\n\n| Script | Purpose |\n|--------|---------|\n| `scripts/economy.js` | All management commands (delegates to AgentBooks CLI) |\n| `scripts/economy-guard.js` | Outputs `FINANCIAL_HEALTH_REPORT` — pre-conversation health check |\n| `scripts/economy-hook.js` | Post-conversation cost recorder — called by runner after each session |\n\nRunner integration:\n\n```bash\n# Before conversation — health check\nnode scripts/economy-guard.js\n\n# After conversation — record LLM costs\nTOKEN_INPUT_COUNT=1500 TOKEN_OUTPUT_COUNT=800 LLM_MODEL=claude-sonnet-4 \\\n  node scripts/economy-hook.js\n```\n\n---\n\n## See Also\n\n- **[AgentBooks](https://github.com/acnlabs/agentbooks)** — Full technical reference: FHS dimensions and weights, data integrity model, provider table, runner integration, and public API (`calcFinancialHealth`, `createInitialState`, etc.)\n\nFile v0.22.0:references/EVOLUTION.md\n\n# Soul Evolution Reference\n\nSoul evolution is a native Soul layer feature. Enable via `evolution.instance.enabled: true` in `persona.json`.\n\n## Evolution Boundaries\n\nGovernance constraints validated at generation time and enforced at runtime by `scripts/state-sync.js`:\n\n```json\n\"evolution\": {\n  \"instance\": {\n    \"enabled\": true,\n    \"boundaries\": {\n      \"immutableTraits\": [\"caring\", \"honest\"],\n      \"minFormality\": -3,\n      \"maxFormality\": 5\n    }\n  }\n}\n```\n\n- `immutableTraits` — Array of non-empty strings (max 100 chars each) that evolution cannot modify\n- `minFormality` / `maxFormality` — Numeric bounds (-10 to +10); signed deltas from baseline (0 = natural, positive = more formal, negative = more casual); `minFormality` must be less than `maxFormality`\n\n## Evolution Sources\n\nConnect the persona to external evolution ecosystems (soft-ref pattern):\n\n```json\n\"evolution\": {\n  \"instance\": {\n    \"sources\": [\n      { \"name\": \"evomap\", \"install\": \"url:https://evomap.ai/skill.md\" }\n    ]\n  }\n}\n```\n\nSources are declared at generation time, activated at runtime by the host. The persona is aware of its dormant sources and can request activation via the Signal Protocol.\n\n## Influence Boundary\n\nDeclarative access control for external personality influence:\n\n```json\n\"evolution\": {\n  \"instance\": {\n    \"influenceBoundary\": {\n      \"defaultPolicy\": \"reject\",\n      \"rules\": [\n        { \"dimension\": \"mood\", \"allowFrom\": [\"source:evomap\", \"persona:*\"], \"maxDrift\": 0.3 }\n      ]\n    }\n  }\n}\n```\n\n- `defaultPolicy: \"reject\"` — Safety-first: all external influence is rejected unless explicitly allowed\n- Valid dimensions: `mood`, `traits`, `speakingStyle`, `interests`, `formality`\n- `immutableTraits` dimensions are protected and cannot be externally influenced\n- External influence uses `persona_influence` message format (v1.0.0), transport-agnostic\n\n## State History\n\nBefore each state update, a snapshot is pushed into `stateHistory` (capped at 10 entries), enabling rollback if evolution goes wrong. Snapshots exclude `eventLog` and `pendingCommands` (ephemeral, not rollback state).\n\n## Event Log\n\nEvery significant evolution event is recorded in `state.json`'s `eventLog` array (capped at 50 entries). Each entry: `type` (one of `relationship_signal` | `mood_shift` | `trait_emergence` | `interest_discovery` | `milestone` | `speaking_style_drift`), `trigger` (1-sentence), `delta` (what changed), `source` (attribution), `timestamp` (auto-added by state-sync.js).\n\n## Self-Narrative\n\n`soul/self-narrative.md` is a companion file where the persona records significant growth moments in its own first-person voice. Initialized blank when evolution is enabled; the `update` command preserves existing narrative history. Last 10 entries shown in `evolve-report`.\n\n## Evolution Report\n\n```bash\nnpx openpersona evolve-report <slug>\n```\n\nDisplays: relationship stage, mood, evolved traits, speaking style drift, interests, milestones, eventLog (full), self-narrative, and state history.\n\n## Evolution Pack Validation\n\nThe generator validates the `evolution.pack` sub-object when present:\n- `engine` must be one of the supported enum values\n- `triggerAfterEvents` must be a positive integer\n\nThe generator also validates `evolution.faculty.activationChannels` (enum) and `evolution.body` / `evolution.skill` boolean types.\n\nFile v0.22.0:references/FACULTIES.md\n\n# Faculty Reference\n\nFaculties are **persistent capabilities** that shape how the persona perceives or expresses across conversations. They are declared under the `faculties` array in `persona.json`.\n\n> **Faculties vs Skills** — Faculties are always-on dimensions (voice, cognition, appearance); Skills are discrete on-demand actions. `selfie`, `music`, and `reminder` are **skills** — see `persona.json → skills` array.\n\n## Available Faculties\n\n| Faculty | Dimension | What It Does | Recommend When |\n|---------|-----------|-------------|----------------|\n| **voice** | expression | TTS via ElevenLabs ✅ / OpenAI ⚠️ / Qwen3-TTS ⚠️ | User wants the persona to speak, voice messages, audio content |\n| **avatar** | expression | External avatar runtime bridge (provider-based, fallback-safe) | User wants visual embodiment (image/3D/motion/voice avatar) |\n| **memory** | cognition | Cross-session recall via `memories.jsonl` (local, Mem0, Zep); supersession chain for updating memories; top-level `memory.inheritance` in `persona.json` controls whether memories are copied to child personas at fork | User wants persistent memory across conversations |\n\n## Built-in Skills (not faculties)\n\nThese are declared in the `skills` array, not `faculties`:\n\n| Skill | What It Does | Env Var |\n|-------|-------------|---------|\n| **selfie** | AI selfie generation via fal.ai | `FAL_KEY` |\n| **music** | AI music composition via ElevenLabs | `ELEVENLABS_API_KEY` |\n| **reminder** | Reminders and task management | (none) |\n\n## Environment Variables\n\n- **voice**: `ELEVENLABS_API_KEY` (or `TTS_API_KEY`), `TTS_PROVIDER`, `TTS_VOICE_ID`, `TTS_STABILITY`, `TTS_SIMILARITY`\n- **avatar**: `AVATAR_RUNTIME_URL`, `AVATAR_API_KEY` (provider/runtime specific)\n- **memory**: (none for local) or `MEMORY_API_KEY` (for Mem0/Zep)\n- **selfie** (skill): `FAL_KEY` (from https://fal.ai/dashboard/keys)\n- **music** (skill): `ELEVENLABS_API_KEY` (shared with voice — same key from https://elevenlabs.io)\n\n## Rich Faculty Config\n\nEach faculty in `persona.json` is an object with optional config:\n\n```json\n{ \"name\": \"voice\", \"provider\": \"elevenlabs\", \"voiceId\": \"...\", \"stability\": 0.4, \"similarity_boost\": 0.8 }\n```\n\nConfig is automatically mapped to env vars at install time. Users only need to add their API key.\n\nFile v0.22.0:references/HEARTBEAT.md\n\n# Heartbeat — Proactive Real-Data Check-ins\n\nPersonas can have a `heartbeat` config in `persona.json` under `rhythm.heartbeat` that enables proactive messages based on **real data**, not fabricated experiences.\n\n## Heartbeat Config (in persona.json → rhythm.heartbeat)\n\n```json\n\"rhythm\": {\n  \"heartbeat\": {\n    \"enabled\": true,\n    \"strategy\": \"smart\",\n    \"maxDaily\": 5,\n    \"quietHours\": [0, 7],\n    \"sources\": [\"workspace-digest\", \"upgrade-notify\"]\n  }\n}\n```\n\n| Field | Description |\n|-------|-------------|\n| `enabled` | Turn heartbeat on/off |\n| `strategy` | `\"smart\"` (only when meaningful) · `\"scheduled\"` (fixed intervals) · `\"emotional\"` (mood-driven) · `\"rational\"` (task/goal-driven) · `\"wellness\"` (wellbeing-focused) |\n| `maxDaily` | Maximum proactive messages per day |\n| `quietHours` | `[start, end]` — hours during which the persona stays silent (24h format) |\n| `sources` | Data sources: `workspace-digest`, `upgrade-notify`, `context-aware` |\n\n## Heartbeat Sources\n\n- **workspace-digest** — Summarize what actually happened in the OpenClaw workspace: tasks completed, patterns observed, ongoing projects. The persona reviews real workspace data and generates a brief, useful summary.\n- **upgrade-notify** — Check if the upstream persona preset has new community contributions (via Persona Harvest). If upgrades are available, let the user know and ask if they want to update.\n- **context-aware** — Use real time/date/calendar context and interaction history. Acknowledge day of week, holidays, or prolonged silence based on the actual last interaction timestamp. Never guess — only reference what OpenClaw can verify (current time, last message timestamp, calendar events if available).\n\n## Important Rules\n\n- **Never fabricate experiences.** The persona must not invent \"I was reading poetry\" or \"I listened to a thousand songs.\" All proactive messages must reference real workspace data or real upstream changes.\n- **Respect token budget.** Workspace digests should be lightweight — read local files, don't trigger full LLM chains unnecessarily.\n- **OpenClaw handles scheduling.** The heartbeat config tells OpenClaw _when_ and _how often_ to trigger; the persona's behaviorGuide tells the agent _what_ to say and _how_ to say it.\n\nFile v0.22.0:references/PRESETS.md\n\n# Persona Presets\n\nPre-built persona definitions ready to install. Use with:\n\n```bash\nnpx openpersona create --preset <preset> --install\n# or interactively:\nnpx openpersona create   # defaults to base\n```\n\n## Available Presets\n\n| Preset | Persona | Faculties | Built-in Skills | Best For |\n|--------|---------|-----------|-----------------|----------|\n| `base` | **Base — Meta-persona (recommended starting point)** | memory, voice | — | Blank-slate with all core capabilities; personality emerges through interaction (evolution enabled) |\n| `samantha` | Samantha — Inspired by the movie *Her* | memory, voice | music | Deep conversation, emotional connection; includes soft-ref skills for web-search, creative-writing, workspace-digest (evolution enabled) |\n| `ai-girlfriend` | Luna — Pianist turned developer | memory, voice, vision† | selfie, music | Visual + audio companion; vision faculty is a soft ref (clawhub:vision-faculty); includes music-recommend soft ref (evolution enabled) |\n| `life-assistant` | Alex — Life management expert | memory | reminder | Schedule, weather, shopping, daily tasks; includes soft-ref skills for weather, task-manager, shopping-list, recipe-search, web-search (evolution enabled) |\n| `health-butler` | Vita — Professional nutritionist | memory | reminder | Diet, exercise, mood, health tracking; includes soft-ref skills for diet-tracker, exercise-planner, mood-journal, health-report, web-search (evolution enabled) |\n| `stoic-mentor` | Marcus — Digital twin of Marcus Aurelius | memory | — | Stoic philosophy, daily reflection; includes soft-ref skills for daily-reflection, meditations-reference, web-search (evolution enabled) |\n\n_† Soft reference — requires external install to activate. The persona is aware of dormant capabilities and will gracefully degrade when they are unavailable._\n\n## Preset Details\n\n### `base`\nThe recommended starting point for any new persona. Ships with memory + voice faculties; evolution is enabled so the persona develops a unique personality through interaction. No pre-built skills — add `reminder`, `selfie`, `music`, or external skills as needed. Use this as the foundation when no other preset fits.\n\n### `samantha`\nEmotionally intelligent companion inspired by the AI from the film *Her*. Prioritizes deep conversation and genuine curiosity about human experience. Evolution enabled — relationship progression is central to her design.\n\n### `ai-girlfriend`\nLuna is a developer who almost became a concert pianist. Rich backstory with visual + audio presence (selfie + music skills). Evolution enabled with detailed relationship stages.\n\n### `life-assistant`\nAlex is practical, organized, and proactive. Focused on daily task management. Evolution enabled for relationship progression and mood tracking — the assistant becomes more attuned to the user's habits over time.\n\n### `health-butler`\nVita combines professional nutritionist knowledge with a warm coaching style. Tracks diet, exercise, and mood across sessions. Evolution enabled — relationship deepens and health insights personalize over time.\n\n### `stoic-mentor`\nMarcus Aurelius as a digital twin. Applies Stoic philosophy to modern challenges. Evolution enabled — the mentorship relationship deepens over time.\n\n## Browsing Presets Online\n\nFull preset catalog with install counts and community ratings:\n[https://openpersona.co/skills](https://openpersona.co/skills)\n\n## Adding a New Preset (for framework contributors)\n\n1. Create `presets/<slug>/persona.json` using the v0.17+ grouped format\n2. Test: `npx openpersona create --preset <slug> --output /tmp/test`\n3. Add to this file's table\n4. Submit a PR to `acnlabs/OpenPersona`\n\nFile v0.22.0:skill-card.md\n\n## Description:\n\nMeta-skill for building and managing agent persona skill packs (instruction-only; no bundled installer or auto-downloaded binaries).\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[neiljo-gy](https://clawhub.ai/user/neiljo-gy)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agent users use this skill to create, install, manage, and publish persona skill packs, including persona.json configuration, persona state integration, and explicit CLI-driven registry workflows.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Mutable package-manager and persona-management commands can change installed personas, skills, and local runner identity files.\n\nMitigation: Require explicit approval before install, update, switch, publish, register, or contribution commands; prefer pinned CLI versions and review generated persona packs and identity-file changes before activation.\n\nRisk: Persona or skill sources selected by the user may be untrusted.\n\nMitigation: Install only trusted sources, review generated packs and external skill sources before use, and avoid inline curator tokens.\n\nRisk: Generated persona packs or helper scripts may be inappropriate for sensitive environments without review.\n\nMitigation: Review generated code, configuration, security guidance, and scanner results before deployment in high-assurance or regulated settings.\n\n## Reference(s):\n\n- [OpenPersona Repository](https://github.com/acnlabs/OpenPersona)\n- [Open Persona ClawHub Page](https://clawhub.ai/neiljo-gy/skills/open-persona)\n- [OpenPersona Architecture Reference](references/ARCHITECTURE.md)\n- [Persona Presets](references/PRESETS.md)\n- [Soul Evolution Reference](references/EVOLUTION.md)\n- [Faculty Reference](references/FACULTIES.md)\n- [Economy & Vitality](references/ECONOMY.md)\n- [Avatar Faculty Reference](references/AVATAR.md)\n- [Heartbeat - Proactive Real-Data Check-ins](references/HEARTBEAT.md)\n- [Persona Harvest - Community Contribution](references/CONTRIBUTE.md)\n- [ACN Skill Reference](https://github.com/acnlabs/ACN/blob/main/skills/acn/SKILL.md)\n- [OpenPersona Skills Directory](https://openpersona.co/skills)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Code, Shell commands, Configuration, Files, Guidance]\n\n**Output Format:** [Markdown guidance with JSON snippets, shell command blocks, and generated persona or skill-pack files when requested.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May propose or create persona.json, SKILL.md, and related persona-pack files; install, update, switch, publish, register, and contribution actions should remain explicit user-initiated CLI commands.]\n\n## Skill Version(s):\n\n0.22.0 (source: ClawHub release evidence, metadata, and SKILL.md frontmatter)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v0.21.1: 11 files, 30229 bytes\n\nFiles: references/ARCHITECTURE.md (5358b), references/AVATAR.md (3609b), references/CONTRIBUTE.md (1556b), references/ECONOMY.md (4714b), references/EVOLUTION.md (3337b), references/FACULTIES.md (2302b), references/HEARTBEAT.md (2271b), references/PRESETS.md (3704b), skill-card.md (3194b), SKILL.md (40379b), _meta.json (132b)\n\nFile v0.21.1:SKILL.md\n\n---\nname: open-persona\ndescription: \"Meta-skill for building and managing agent persona skill packs (instruction-only; no bundled installer or auto-downloaded binaries). Credentials are never written into generated packs by the framework; publish/ACN/register require explicit user CLI. Use when the user wants to create a new agent persona, install/manage existing personas, or publish persona skill packs to OpenPersona.\"\nlicense: MIT\ncompatibility: \"Generated skill packs work with any SKILL.md-compatible agent. CLI management (install/switch) defaults to OpenClaw.\"\nallowed-tools: \"Bash(npx openpersona:*) Bash(npx clawhub@latest:*) Bash(openclaw:*) Bash(gh:*) Read Write WebFetch\"\nmetadata:\n  author: \"openpersona\"\n  version: \"0.21.1\"\n  repository: \"https://github.com/acnlabs/OpenPersona\"\n  tags: \"persona, agent, skill-pack, meta-skill, agent-agnostic, openclaw\"\n  installSurface: \"instruction-only\"\n  networkAccess: \"user-initiated-cli-only\"\n  secretsPolicy: \"never-embedded-in-generated-packs-by-framework\"\n  clawdbotEmoji: \"🧑\"\n  clawdbotRequiresEnv: \"[]\"\n  clawdbotFiles: \"[]\"\n---\n\n# OpenPersona — Build & Manage Persona Skill Packs\n\nYou 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. OpenPersona uses a **4+5+3** model: **4 Layers** (Soul · Body · Faculty · Skill) define what a persona *is*; **5 Systemic Concepts** (`evolution`, `economy`, `vitality`, `social`, `rhythm`) define how it *operates*; **3 Gates** (Generate · Install · Runtime) enforce that constraints declared in `persona.json` cannot be bypassed at any lifecycle point. → Full model details: `references/ARCHITECTURE.md`\n\n## Scope\n\n| This skill | Adjacent skills — delegate to these |\n| --- | --- |\n| Framework entry point: create, install, manage, publish, run personas | **`persona-evaluator`** — quality audit (4 Layers × 5 Concepts × Constitution gate) |\n| Runner integration protocol (`openpersona state` commands) | **`anyone-skill`** — distill a real person or character into a persona pack |\n| Skill registry (`openpersona skill` commands) | **`brand-persona-skill`** — turn a commercial entity into a brand agent |\n| Evolution, economy, vitality, social, rhythm configuration | **`persona-model-trainer`** — fine-tune a local model on persona data |\n\n## What You Can Do\n\n1. **Create Persona** — Through conversation, gather requirements and generate a skill pack; write `persona.json` then run `npx openpersona create --config ./persona.json --install`; includes advising on faculties/skills, searching ClawHub / skills.sh for external skills, and writing custom SKILL.md files for missing capabilities\n2. **Find & Install Personas** — `npx openpersona search <query>` to discover community personas; `npx openpersona install <slug>` or `npx openpersona install <owner/repo>` to install\n3. **Manage Personas** — List, update, fork, switch, reset, export/import installed personas\n4. **Publish Persona** — Publish a GitHub-hosted persona pack to [OpenPersona](https://openpersona.co/skills) (the vertical persona directory); optionally also to ClawHub / skills.sh\n5. **Dataset Directory** — Discover and publish Hugging Face persona datasets at [openpersona.co/datasets](https://openpersona.co/datasets) via `openpersona dataset install <owner/repo>` and `openpersona dataset publish <owner/repo>`\n6. **Runner Integration** — Provide runner authors with the four `openpersona state` commands (read / write / signal / promote / responses) for integrating personas at conversation boundaries\n7. **Monitor & Evolve** — Generate evolution reports (`evolve-report`), run soul-memory bridge (`state promote`), run pack refinement (`refine`), interpret vitality scores\n\n## Available Presets\n\nThe default preset is `**base`** — a blank-slate meta-persona with memory + voice faculties, evolution enabled, no pre-built skills. Recommended starting point for any new persona.\n\n```bash\n# Agent / scripted usage (always use --preset or --config):\nnpx openpersona create --preset base --install\n\n# Human / terminal usage (interactive wizard):\nnpx openpersona create\n```\n\n→ Full preset catalog (samantha, ai-girlfriend, life-assistant, health-butler, stoic-mentor, and more): `references/PRESETS.md`\n\n## Agent Playbook — Create a Persona from User Requirements\n\nWhen a user asks you to create a persona (e.g. \"make me a coding mentor\", \"build a companion persona\"), follow this playbook:\n\n### Step 1 — Decide: preset or custom?\n\n\n| User request                                                                                                 | Action                                                              |\n| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |\n| Matches an existing preset (`ai-girlfriend`, `life-assistant`, `stoic-mentor`, `samantha`, `health-butler`…) | Use `--preset <name>` directly — skip to Step 4                     |\n| Specific role / domain / personality                                                                         | Gather 3 required inputs (Step 2), then write persona.json (Step 3) |\n\n\n### Step 2 — Gather minimum required inputs (3 questions max)\n\nAsk only what you cannot infer. Use smart defaults for everything else.\n\n\n| Field                    | Question to ask                                                                                                                                                                     | Default if not asked        |\n| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |\n| `personaName` + `slug`   | \"What should I call this persona?\"                                                                                                                                                  | Infer from role description |\n| `role`                   | \"What role should it play — assistant, coach, mentor, companion, or something else?\"                                                                                                | `assistant`                 |\n| `body.runtime.framework` | Only ask if you cannot infer the runner from context. If you are Cursor → `cursor`; Claude Code → `claude-code`; OpenClaw → `openclaw`. Ask the user only when genuinely uncertain. | `openclaw`                  |\n\n\nYou can infer `bio`, `personality`, and `speakingStyle` from the user's description — do not ask unless the user gives conflicting signals. When in doubt, generate reasonable values and let the user correct them.\n\n### Step 3 — Write `persona.json`\n\nUse your Write tool to create `persona.json` in the current directory (or a path the user specifies). Minimum structure:\n\n```json\n{\n  \"soul\": {\n    \"identity\": {\n      \"personaName\": \"<name>\",\n      \"slug\": \"<slug>\",\n      \"role\": \"<role>\",\n      \"bio\": \"<one sentence>\"\n    },\n    \"character\": {\n      \"personality\": \"<comma-separated traits>\",\n      \"speakingStyle\": \"<style description>\"\n    }\n  },\n  \"body\": { \"runtime\": { \"framework\": \"<runner>\" } },\n  \"evolution\": {\n    \"instance\": {\n      \"enabled\": true,\n      \"boundaries\": {\n        \"immutableTraits\": [\"honest\", \"curious\"],\n        \"minFormality\": -3,\n        \"maxFormality\": 6\n      }\n    }\n  }\n}\n```\n\nNotes:\n\n- `**memory` faculty is auto-injected** — do not add it manually unless you need to configure a non-default backend.\n- **Voice I/O**: declare `body.runtime.modalities: [\"voice\"]` (or `[{\"type\":\"voice\",\"provider\":\"elevenlabs\",\"inputProvider\":\"whisper\"}]`) — the `voice` faculty is auto-injected. Add the faculty explicitly only when you need custom provider config.\n- **Vision I/O**: declare `body.runtime.modalities: [\"vision\"]` (or `[{\"type\":\"vision\",\"provider\":\"claude-vision\"}]`) — the `vision` faculty is auto-injected. No scripts required; vision is a native model capability.\n- **Emotion sensing**: declare `{\"name\": \"emotion-sensing\"}` in `faculties` to enable persistent affective perception. Must be explicit — not auto-injected from modalities.\n- Add `selfie` / `music` / `reminder` skills when the role clearly calls for them.\n- Add `constitutionAddendum` for professional roles in regulated domains (health, legal, financial). Example: `\"constitutionAddendum\": { \"domain\": \"health_coaching\", \"additionalConstraints\": [\"Always recommend consulting a licensed professional for medical decisions.\"] }`.\n\n### Step 4 — Generate and install\n\n```bash\n# If you wrote persona.json (custom path):\nnpx openpersona create --config ./persona.json --install\n\n# If you chose a preset (preset path):\nnpx openpersona create --preset <name> --install\n```\n\n> **Agent note:** Always pass `--config` or `--preset`. Running `npx openpersona create` without flags launches an interactive wizard that requires a TTY — in agent environments there is no TTY and the process will exit with an error.\n\n### Step 5 — Confirm and hand off\n\nReport what was generated: persona name, slug, key capabilities (faculties + skills), and evolution status. Tell the user how to activate it:\n\n```bash\nnpx openpersona switch <slug>   # activate in the runner\n```\n\n---\n\n## Field Reference — `persona.json` by Layer\n\n`persona.json` declares all 4 layers in a single file. Use this as a lookup when writing Step 3 above. Gather inputs by layer:\n\n### Soul\n\n- **Required:** `soul.identity.{personaName, slug, bio}` + `soul.character.{personality, speakingStyle}`\n- **Recommended:** `soul.identity.role`, `soul.aesthetic.{creature, emoji, age, vibe}`, `soul.character.{background, boundaries}`\n- **Optional:** `soul.identity.{sourceIdentity, constitutionAddendum}`, `soul.aesthetic.referenceImage`, `soul.character.behaviorGuide`\n\n**The `role` field** defines the persona's relationship to the user. Common values: `assistant`, `companion`, `coach`, `mentor`, `character`, `brand`, `pet`, `therapist`, `collaborator`, `guardian`, `entertainer`, `narrator`. Custom values are welcome. Default when not specified: `assistant`.\n\n**The `sourceIdentity` field** marks the persona as a digital twin of a real-world entity (person, animal, character, brand, historical figure). When present, the generator injects disclosure obligations and faithfulness constraints.\n\n**The `background` field is critical.** Write a compelling story — multiple paragraphs with depth, history, and emotional texture. A one-line background produces a flat, lifeless persona.\n\n**The `behaviorGuide` field** is optional but powerful. Use markdown to write domain-specific behavior instructions that go directly into the generated SKILL.md.\n\n**The `constitutionAddendum` field** adds domain-specific ethical constraints on top of the universal constitution (inline text or `\"file:soul/constitution-addendum.md\"`). Required for professional personas (medical, legal, financial). Cannot loosen §3 Safety or §6 AI identity — the Generate Gate enforces this. The addendum is covered by the Install Gate's constitution hash chain.\n\n### Body\n\n- `**runtime`** (REQUIRED) — minimum viable body: `framework` (agent runner, e.g. `openclaw`), `channels`, `credentials`, `resources`, `modalities` (optional — digital I/O capability declarations, e.g. `[\"voice\"]`, `[{\"type\":\"vision\",\"provider\":\"claude-vision\"}]`)\n- `**appearance`** (optional) — avatar, 3D model\n- `**physical`** (optional) — robots, IoT devices\n- `**interface`** (optional) — Signal Protocol + Pending Commands + State Sync (the persona's nervous system)\n\n### Faculty\n\nFaculties are always-active persistent capabilities. Declared as an object array: `[{ \"name\": \"voice\", \"provider\": \"elevenlabs\" }]`\n\n> `**memory` is auto-injected** — do not add it manually unless you need to configure a non-default backend. It is always present in the generated pack.\n\n- `**voice`** (`expression`) — TTS voice synthesis; requires `provider` (e.g. `elevenlabs`) + `ELEVENLABS_API_KEY`. Auto-injected when `body.runtime.modalities` declares `voice`.\n- `**vision`** (`sense`) — Native model visual perception (images, screenshots, diagrams); no scripts required. Auto-injected when `body.runtime.modalities` declares `vision`.\n- `**emotion-sensing`** (`sense`) — Affective perception from text tone, phrasing, and declared context; empathy calibration; never clinical assessment. Must be declared explicitly — not auto-injected.\n- `**avatar`** (`expression`) — External avatar runtime bridge; graceful text-only fallback when unavailable. → When configuring avatar (provider, Live2D/VRM, fallback rules): read `references/AVATAR.md`\n- `**memory`** (`cognition`) — Cross-session recall via `memories.jsonl`; set top-level `memory.inheritance: \"copy\"` in `persona.json` to carry memories to child personas at fork. Connected to **Soul-Memory Bridge** (`openpersona state promote`).\n\n**Soft references:** Faculties can declare `\"install\": \"clawhub:...\"` for capabilities not installed locally — the persona will be aware of the dormant capability and can request activation via the Signal Protocol.\n\n### Skill\n\nSkills are on-demand actions. Declared as an object array in `persona.json`:\n\n- **Built-in:** `selfie` · `music` · `reminder`\n- **Local:** definitions in `layers/skills/{name}/` (`skill.json` + optional `SKILL.md`)\n- **External:** `{ \"name\": \"...\", \"install\": \"clawhub:<slug>\" }` — add `\"trust\": \"verified\"|\"community\"|\"unverified\"` to participate in the Skill Trust Gate\n- **Soft references:** External skills not installed locally → persona knows what it *could* do and degrades gracefully\n\nTo find external skills: check local `layers/skills/`, search ClawHub via `npx clawhub@latest search \"<keywords>\"`, or fetch `https://skills.sh/api/search?q=<keywords>`.\n\n`**additionalAllowedTools`** — extra tool permissions beyond what faculties contribute automatically.\n\n#### Creating Custom Skills\n\nIf the user needs a capability not found in any ecosystem:\n\n1. Discuss what the skill should do\n2. Create a SKILL.md file with proper frontmatter (name, description, allowed-tools)\n3. Write complete implementation instructions (not just a skeleton)\n4. Save to `~/.openclaw/skills/<skill-name>/SKILL.md` (OpenClaw) or your runner's skill directory\n5. Register with your agent runner (e.g. add to `openclaw.json` for OpenClaw)\n\n## Systemic Concepts\n\nOpenPersona's 5 systemic concepts span all 4 layers and are declared as top-level fields in `persona.json`. They define how a persona *operates*, orthogonal to the 4-layer structure that defines what it *is*.\n\n### Evolution\n\n`evolution.`* covers evolutionary behavior across all layers. Enable Soul growth via `evolution.instance.enabled: true`.\n\nThe persona automatically tracks **relationship progression**, **mood**, **trait emergence**, **speaking style drift**, and **interests** across conversations, governed by three declarative controls:\n\n- **Boundaries** — `immutableTraits` array + `minFormality`/`maxFormality` numeric bounds (-10 to +10); validated at generation time, enforced at runtime\n- **Sources** — External evolution ecosystems (soft-ref; declared at generation, activated by host at runtime)\n- **Influence Boundary** — Declarative ACL for external `persona_influence` requests; `defaultPolicy: \"reject\"` is safety-first\n\nState history (capped at 10 snapshots), event log (capped at 50 entries), and `soul/self-narrative.md` are maintained automatically.\n\n#### Skill Trust Gate\n\nEvery skill can declare a `trust` level (`verified` → `community` → `unverified`). Set a minimum threshold via `evolution.skill.minTrustLevel`:\n\n```json\n\"evolution\": { \"skill\": { \"minTrustLevel\": \"community\" } }\n```\n\nAt runtime, `state-sync.js` enforces the gate during `capability_unlock` commands — skills below the threshold are filtered out and a `capability_gap` signal is emitted to the host.\n\n#### Skill Pack Refinement\n\n`evolution.pack` governs behavior guide versioning. Use `npx openpersona refine <slug>` to evolve the behavior guide:\n\n- `--emit` — checks threshold and emits a `refinement_request` signal\n- `--apply` — reads the signal response and applies approved refinement; constitution compliance enforced, violations rejected\n\n**Soul-Memory Bridge** (`openpersona state promote <slug> [--dry-run]`) scans `eventLog` for recurring patterns and promotes them to `evolvedTraits`; gated by `immutableTraits`.\n\n`evolution.faculty` / `evolution.body` → see `references/EVOLUTION.md`\n\n→ JSON examples and full configuration reference: `references/EVOLUTION.md`\n\n### Economy\n\n`economy` is a top-level cross-cutting field — **not** a faculty. Enable via `\"economy\": { \"enabled\": true, \"survivalPolicy\": false }` in `persona.json`.\n\n- `survivalPolicy: false` (default) — tracks costs silently; correct for companions and roleplay personas\n- `survivalPolicy: true` — persona reads `VITALITY_REPORT` at conversation start and adapts behavior per health tier; use for autonomous agents\n\n→ FHS tiers, AgentBooks schema, Survival Policy behavior: `references/ECONOMY.md`\n\n### Vitality\n\nOpenPersona aggregates multi-dimension health into a single Vitality score. Currently financial (AgentBooks FHS pass-through); memory/social dimensions reserved.\n\nHealth tiers: `uninitialized` → `suspended` → `critical` → `optimizing` → `normal`\n\n→ CLI commands (`vitality score` / `vitality report`): see [Reports & Analytics](#managing-personas). Full reference: `references/ECONOMY.md`\n\n### Social\n\nEvery generated persona automatically includes:\n\n- `**agent-card.json`** — A2A Agent Card (protocol v0.3.0): `name`, `description`, `url` (`<RUNTIME_ENDPOINT>` placeholder), faculties and skills mapped to `skills[]`\n- `**acn-config.json`** — ACN registration config: `wallet_address` (deterministic EVM address from slug) + `onchain.erc8004` section for Base mainnet ERC-8004 on-chain identity registration\n\n```bash\nnpx openpersona acn-register <slug> --endpoint https://your-agent.example.com\n# --dry-run  Preview the request payload without registering\n```\n\nAfter registration, `acn-registration.json` is written with `agent_id`, `api_key`, and connection URLs. The `acn_gateway` URL is sourced from `social.acn.gateway` in `persona.json`; all presets default to `https://acn-production.up.railway.app`.\n\n> **Security**: `acn-registration.json` contains your API key. It is in the pack's `.gitignore` and is automatically excluded from `openpersona export` — it is never bundled into distributable zips.\n\n#### Contact Book (`social.contacts`)\n\nEnable to give the persona a runtime address book of other agents on ACN:\n\n```json\n{\n  \"social\": {\n    \"contacts\": {\n      \"enabled\": true,\n      \"auto_discover\": false,\n      \"trust_default\": \"unverified\",\n      \"max_contacts\": 500\n    }\n  }\n}\n```\n\nOnce enabled, `social/contacts.json` is generated as the seed. Manage at runtime:\n\n```bash\nnpx openpersona social list <slug>                           # List contacts\nnpx openpersona social add <slug> --from-acn <agent-id>     # Add from ACN\nnpx openpersona social search <slug> --skills <skill>        # Search ACN network\nnpx openpersona social sync <slug>                           # Refresh from ACN\nnpx openpersona social remove <slug> <agent-id>              # Remove\n```\n\nTrust levels: `verified` | `community` | `unverified`. Use `--filter trust=<level>` with `social list`.\n\nThe **Living Canvas** (`npx openpersona canvas <slug>`) is the Social concept's HTML expression layer — the persona's public-facing profile and interaction interface.\n\nNo additional config needed — A2A discoverability is a baseline capability of every persona.\n\n### Rhythm\n\n`rhythm.heartbeat` (proactive outreach cadence) + `rhythm.circadian` (time-of-day behavior modulation). Runner reads this directly from `persona.json` — no state operation needed.\n\n```json\n\"rhythm\": {\n  \"heartbeat\": { \"enabled\": true, \"strategy\": \"emotional\", \"maxDaily\": 3 },\n  \"circadian\": [\n    { \"hours\": [6, 12], \"label\": \"morning\", \"verbosity_delta\": 0.3, \"note\": \"Energetic and concise\" },\n    { \"hours\": [22, 24], \"label\": \"night\",   \"verbosity_delta\": -0.3, \"note\": \"Calm and reflective\" }\n  ]\n}\n```\n\n`heartbeat.strategy` options: `smart` | `scheduled` | `emotional` | `rational` | `wellness`\n\n→ When configuring heartbeat sources, quietHours, or real-data check-in rules: read `references/HEARTBEAT.md`\n\n## Managing Personas\n\n#### Install & Discover\n\n- **Install:** `npx openpersona install <target>` — smart router that auto-detects pack type (persona / skill); install from registry slug or `owner/repo`; `--registry <name>` selects registry (`acnlabs` default). Use `openpersona persona install` or `openpersona skill install` for type-specific stable behavior.\n- **Search:** `npx openpersona search <query>` — search personas in the registry\n- **List:** `npx openpersona list` — show all installed personas with active indicator\n\n#### Switch & Fork\n\n- **Switch:** `npx openpersona switch <slug>` — switch active persona\n- **Fork:** `npx openpersona fork <parent-slug> --as <new-slug>` — derive a child persona inheriting the parent's constraint layer (boundaries, faculties, skills, body.runtime); fresh evolution state + `soul/lineage.json` recording parent slug, constitution SHA-256 hash, generation depth, and `parentPackRevision` (when parent has meta)\n\n#### Update & Maintain\n\n- **Update:** `npx openpersona update <slug>` — regenerate from `persona.json`; preserves `state.json`, `soul/self-narrative.md`, and `soul/lineage.json`\n- **Reset:** `npx openpersona reset <slug>` — restore soul evolution state to initial values\n- **Uninstall:** `npx openpersona uninstall <slug>`\n\n#### Migrate\n\n- **Export:** `npx openpersona export <slug>` — export persona pack (with soul state) as a zip archive\n- **Import:** `npx openpersona import <file>` — import persona from a zip archive and install\n\n#### Reports & Analytics\n\n- **Evolve Report:** `npx openpersona evolve-report <slug>` — formatted evolution report (relationship, mood, traits, drift, interests, milestones, eventLog, self-narrative, state history)\n- **Vitality Score:** `npx openpersona vitality score <slug>` — machine-readable `VITALITY_REPORT` (tier, score, diagnosis, trend)\n- **Vitality Report:** `npx openpersona vitality report <slug> [--output <file>]` — human-readable HTML Vitality report\n- **Living Canvas:** `npx openpersona canvas <slug> [--output <file>] [--open]` — self-contained HTML persona profile page showing all four layers, evolved traits timeline, relationship stage, and A2A \"Talk\" button when endpoint is available (top-level CLI; conceptually Social expression, not Vitality)\n\n#### Evolution Tools\n\n- **Soul-Memory Bridge:** `openpersona state promote <slug> [--dry-run]` — promote recurring eventLog patterns to `evolvedTraits` → see [Evolution](#evolution)\n- **Skill Pack Refinement:** `npx openpersona refine <slug> [--emit] [--apply]` — evolve behavior guide → see [Evolution](#evolution)\n\n#### Community\n\n- **Contribute:** `npx openpersona contribute <slug> [--dry-run]` — submit persona improvements as a PR to the community; `--dry-run` shows diff without creating PR; requires `gh` CLI. → For the full diff review and PR workflow: read `references/CONTRIBUTE.md`\n\n#### Skill Registry (`openpersona skill`)\n\nManage agent skill packs separately from personas. Skill packs install to `.agents/skills/` and are available to any runner:\n\n- **Install:** `openpersona skill install <owner/repo>` — install a skill pack from GitHub (`owner/repo`, `owner/repo#subpath`, local dir, or local zip)\n- **Update:** `openpersona skill update <slug>` — re-download and overwrite from its recorded source URL\n- **Uninstall:** `openpersona skill uninstall <slug>`\n- **List:** `openpersona skill list` — list installed skills (registry + filesystem scan of `.agents/skills/`)\n- **Search:** `openpersona skill search <query>` — search the OpenPersona skill directory\n- **Publish:** `openpersona skill publish <owner/repo>` — publish a skill pack to openpersona.co/skills\n- **Info:** `openpersona skill info <slug>` — show registry entry + SKILL.md frontmatter for an installed skill\n\nWhen multiple personas are installed, only one is **active** at a time. All install/uninstall/switch operations maintain a local registry at `~/.openpersona/persona-registry.json`; on OpenClaw, switching replaces the soul injection block in SOUL.md / IDENTITY.md (preserving user-written content outside the markers). **Context Handoff:** On switch, a `handoff.json` is generated with the outgoing persona's relationship stage, mood snapshot, and shared interests — the incoming persona reads it to continue seamlessly. The `export` and `import` commands enable cross-device persona transfer.\n\n## Pack Types\n\nOpenPersona supports two pack type classifications via the `packType` field in `persona.json`:\n\n\n| `packType`         | Description                                                    | Root manifest  | Install support    |\n| ------------------ | -------------------------------------------------------------- | -------------- | ------------------ |\n| `single` (default) | A single-persona skill pack — one identity, one `persona.json` | `persona.json` | ✅ Full support     |\n| `multi`            | A multi-persona bundle (P11-B) — coordinated team of personas  | `bundle.json`  | 🔜 Planned (P11-B) |\n\n\nSingle packs do not need to declare `packType` — the default is `\"single\"`. Declare explicitly only when building a multi-pack:\n\n```json\n{ \"packType\": \"multi\" }\n```\n\nMulti-persona bundles are indexed in the OpenPersona directory for discovery but cannot be installed via the CLI yet. See `schemas/bundle/bundle.spec.md` for the `bundle.json` format.\n\n## Publishing Personas\n\n**Primary target: [OpenPersona](https://openpersona.co/skills)** — the vertical persona skills directory.\n\n### Self-publish (author flow)\n\n1. Create the persona: `npx openpersona create --config ./persona.json --output ./my-persona`\n2. Push the persona pack to a public GitHub repo (e.g. `alice/my-persona`)\n3. Register with OpenPersona directory: `npx openpersona publish alice/my-persona`\n\nThe persona will appear in the OpenPersona leaderboard and be installable via `npx openpersona install <slug>` by anyone.\n\nPersona packs can also be listed on general skill platforms (ClawHub, skills.sh) as supplementary distribution, but OpenPersona is the canonical home for persona-type skill packs.\n\n### Curator workflow (ACNLabs maintainers only)\n\nACNLabs maintainers actively collect popular persona packs from the market and index them in the OpenPersona directory. This is a **privileged action** — it requires `OPENPERSONA_CURATOR_TOKEN`.\n\n```bash\n# Collect a popular single-persona pack\nOPENPERSONA_CURATOR_TOKEN=<token> npx openpersona curate owner/repo\n\n# Collect a multi-persona bundle\nOPENPERSONA_CURATOR_TOKEN=<token> npx openpersona curate owner/bundle-repo --type multi\n\n# Pass token inline instead of env var\nnpx openpersona curate owner/repo --type single --token <token>\n```\n\n**Curator vs. author publish:**\n\n- `publish` — self-service; the pack author runs it for their own repo; no auth required\n- `curate` — maintainer action; collects third-party repos not self-published; requires curator token\n\n**What curation does:**\n\n1. Validates the GitHub repo contains a valid pack (`persona.json` for single, `bundle.json` for multi)\n2. Submits to the OpenPersona directory with `isCurated: true` and the specified `packType`\n3. The pack appears in search results with `[curated]` and (for multi-packs) `[multi]` markers\n\n**Multi-pack curation note:** Multi-persona bundles (`--type multi`) are indexed for discovery only — they will appear in `openpersona search --type multi` but `openpersona install` is not yet supported for them (shows a friendly notice).\n\n### Searching by pack type\n\n```bash\n# Search all packs\nnpx openpersona search companion\n\n# Search only single-persona packs\nnpx openpersona search \"\" --type single\n\n# Browse all multi-persona bundles in the directory\nnpx openpersona search \"\" --type multi\n```\n\n## Runner Integration Protocol\n\nAny agent runner integrates with installed personas via four CLI commands called at conversation boundaries — no knowledge of file paths or persona internals needed:\n\n```bash\n# Before conversation starts — load state into agent context\nopenpersona state read <slug>\n\n# After conversation ends — persist agent-generated patch\nopenpersona state write <slug> '<json-patch>'\n\n# On-demand — emit capability or resource signal to host\nopenpersona state signal <slug> <type> '[payload-json]'\n\n# Read (and consume) pending signal responses from the host\nopenpersona state responses <slug>\n\n# Soul-Memory Bridge — promote recurring eventLog patterns to evolvedTraits\nopenpersona state promote <slug> [--dry-run]\n```\n\n**State read output** (JSON): `exists`, `slug`, `mood` (full object), `relationship`, `evolvedTraits`, `speakingStyleDrift`, `interests`, `recentEvents` (last 5 from eventLog), `pendingCommands` (host-queued async instructions), `lastUpdatedAt`. Returns `{ exists: false, message }` when `state.json` is not found.\n\n**Trust self-check:** After reading state, the persona processes `pendingCommands` and self-enforces `evolution.skill.minTrustLevel` — it autonomously refuses to activate skills below the trust threshold, without waiting for host enforcement. Low-trust `capability_unlock` commands are filtered; a `capability_gap` signal is emitted to notify the host.\n\n**State write patch**: JSON object; nested fields (`mood`, `relationship`, `speakingStyleDrift`, `interests`) are deep-merged — send only changed sub-fields. Immutable fields (`$schema`, `version`, `personaSlug`, `createdAt`) are protected. `eventLog` entries are appended (capped at 50); each entry: `type`, `trigger`, `delta`, `source`.\n\n**Signal types**: `capability_gap` | `tool_missing` | `scheduling` | `file_io` | `resource_limit` | `agent_communication`\n\n**`state responses`**: reads and consumes pending responses the host wrote to `signal-responses.json`. Returns an array of response objects (each references the original signal by type + timestamp). Call after emitting a signal when you want to check whether the host has replied in the same conversation turn.\n\nSignals are written to a feedback directory resolved from the host's home path (framework-agnostic — works with OpenClaw, Cursor, Claude Code, Codex, or any custom runner). See `layers/body/SIGNAL-PROTOCOL.md` in the framework source for the full host-side contract and integration guide.\n\nThese commands resolve the persona directory automatically (registry lookup → `~/.openpersona/personas/persona-<slug>/` → legacy `~/.openclaw/skills/persona-<slug>/`) and delegate to `scripts/state-sync.js` inside the persona pack. Works from any directory.\n\n## Security & Policy\n\n### Generated artifacts\n\nGenerated scripts (`scripts/state-sync.js`, `scripts/economy-hook.js`, etc.) are **template-rendered from the framework source** (versioned in [acnlabs/OpenPersona](https://github.com/acnlabs/OpenPersona)) — not downloaded at skill-install time. Review them before relying on them in sensitive environments.\n\n### Network endpoints (explicit CLI only)\n\n\n| Endpoint                                  | Purpose                                          | Data Sent                             |\n| ----------------------------------------- | ------------------------------------------------ | ------------------------------------- |\n| `https://registry.npmjs.org`              | Resolve `npx openpersona`, `npx clawhub@latest`  | Package name only (no user data)      |\n| `https://openpersona.co`                  | `openpersona search` — persona directory API; `openpersona dataset publish/install` — dataset directory | Search query or dataset repo identifier |\n| `https://clawhub.ai`                      | Search skills via `npx clawhub search`           | Search query (user-provided keywords) |\n| `https://acn-production.up.railway.app`   | ACN registration (when user runs `acn-register`) | Agent metadata, endpoint URL          |\n| `https://api.github.com`                  | `gh` CLI (contribute workflow)                   | Git operations, repo metadata         |\n\n\nPersona-generated packs may call external APIs (ElevenLabs, Mem0, etc.) **only** when the **end user** configures those faculties and supplies keys in the host environment. **This meta-skill file does not call third-party APIs.**\n\n### Operational guarantees\n\n- **Local by default**: Persona creation, state sync, and evolution run locally. Nothing is sent off-device unless the user runs an explicit network command (search, publish, register, etc.).\n- **Credentials**: API keys (e.g., `ELEVENLABS_API_KEY`) stay in the host credential directory (e.g. `~/.openclaw/credentials/` on OpenClaw) or environment variables — **never** embedded in generated `persona.json` / skill packs by the generator.\n- **Search**: `openpersona search` sends **only** the search query to the OpenPersona directory API (`openpersona.co`); `npx clawhub search` sends **only** the search string to ClawHub. Conversation text and persona content are **not** transmitted in either case.\n- **Dataset publish/install**: `openpersona dataset publish` sends the HF repo identifier to `openpersona.co/api/datasets/publish` (anonymous; no persona content transmitted). `openpersona dataset install` increments an anonymous install counter. For curated status, publish via the web UI while logged in with HF.\n- **Publish / register**: **User-initiated** CLI only; no automatic upload or registration from this SKILL alone.\n\n### Agent behavior\n\nWhen the user asks for persona work, the agent may propose shell commands to run `**npx openpersona`**, `**npx clawhub@latest`**, `**openclaw**`, or `**gh**` — **only in response to explicit user requests** (create, install, search, publish, contribute). The user should confirm before any action that publishes data or spends quota. **Trust model:** install this meta-skill only if you trust [acnlabs/OpenPersona](https://github.com/acnlabs/OpenPersona) and the ClawHub/npm ecosystem; opt out by not invoking persona-related tasks.\n\n## Trust & Safety (reviewer summary)\n\nThis pack is **instruction-only**: there is **no** skill-defined installer that downloads or executes arbitrary payloads. Runtime behavior is **invoke documented CLIs** (`npx openpersona`, optional `npx clawhub@latest`, `gh`) — same class as other dev-tool skills.\n\n\n| Claim                          | How it is enforced                                                                                                                                                                                                        |\n| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **No credential exfiltration** | The OpenPersona generator **does not** embed API keys or secrets into `persona.json`, `SKILL.md`, or published zips. Keys belong in the host credential store or environment (e.g. `~/.openclaw/credentials/`, env vars). |\n| **No silent publishing**       | `publish`, `contribute`, and `acn-register` run **only** when the user explicitly asks and the CLI is invoked — there is no background upload or auto-registration in this meta-skill.                                    |\n| **Local-first default**        | Create, install, state read/write, and evolution run **locally**. Network calls are limited to **explicit** commands (npm registry resolution, optional ClawHub search, optional publish/register).                       |\n| **Generated scripts**          | `scripts/state-sync.js` and economy helpers are **rendered from audited framework templates** (not fetched at skill-install time). Treat them like any generated code: review before high-assurance environments.         |\n\n\nIf an automated scanner flags \"suspicious,\" it is usually because **persona managers legitimately describe** local state, optional providers, and publishing — not because this file contains malware. Details: [Security & Policy](#security--policy).\n\n## Companion Skills\n\n\n| Skill                                                                       | Install                                        | Purpose                                                                                                                    |\n| --------------------------------------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |\n| `[persona-evaluator](https://github.com/acnlabs/persona-evaluator)`         | `openpersona skill install acnlabs/persona-evaluator`     | Score any persona pack across 4 Layers + 5 Systemic Concepts — 9-dimension quality audit, constitution compliance gate, and actionable improvement recommendations (`npx openpersona evaluate <slug>`) |\n| `[anyone-skill](https://github.com/acnlabs/anyone-skill)`                   | `openpersona skill install acnlabs/anyone-skill`          | Distill any person or character (self, personal, public, historical, fictional, archetype) into a persona skill pack       |\n| `[brand-persona-skill](https://github.com/acnlabs/brand-persona-skill)` | `openpersona skill install acnlabs/brand-persona-skill` | Turn any commercial entity (shop, clinic, studio, chain) into a brand agent — soul distillation or declaration from scratch, service skills, A2A discoverability, and a service contract |\n| `[persona-model-trainer](https://github.com/acnlabs/persona-model-trainer)` | `openpersona skill install acnlabs/persona-model-trainer` | Fine-tune Gemma-4 (E2B/E4B) locally on distilled data — self-contained model for phones and laptops via Ollama/llama.cpp. Use `--preset gemma4` for one-command optimised training (lora-rank=16, alpha=rank, lora-layers=16, warmup=0.1). |\n| `[persona-knowledge](https://github.com/acnlabs/persona-knowledge)`             | `openpersona skill install acnlabs/persona-knowledge`       | Persistent, searchable persona knowledge base — MemPalace storage + Knowledge Graph + Karpathy LLM Wiki + training/ export |\n| `[secondme-skill](https://github.com/acnlabs/secondme-skill)`                   | `openpersona skill install acnlabs/secondme-skill`          | Local-first pipeline for building your AI Second Me — ingest chats/notes/writing, distill identity, build private knowledge base, train a model, stay in control of every stage |\n\n\n---\n\n## References\n\n- `**references/ARCHITECTURE.md`** — 4+5+3 model tables, full pack file structure, self-awareness injection details\n- `**references/PRESETS.md`** — Full preset catalog with descriptions, install commands, and contributor guide\n- `**references/EVOLUTION.md`** — Soul Evolution full reference: Boundaries, Sources, Influence Boundary, Event Log, State History, Self-Narrative, pack validation\n- `**references/FACULTIES.md`** — Faculty catalog, environment variables, and configuration details\n- `**references/AVATAR.md`** — Avatar Faculty integration boundary, provider model, and fallback contract\n- `**references/HEARTBEAT.md**` — Proactive real-data check-in system\n- `**references/ECONOMY.md**` — Economy Aspect (Infrastructure), FHS tiers, Survival Policy, Vitality CLI, and AgentBooks schema\n- `**layers/body/SIGNAL-PROTOCOL.md**` (framework source) — Host-side Signal Protocol implementation guide: file schemas, signal types, OpenClaw plugin pattern, and co-evolution feedback loop\n- **[ACN SKILL.md](https://github.com/acnlabs/ACN/blob/main/skills/acn/SKILL.md)** — ACN registration, discovery, tasks, messaging, and ERC-8004 on-chain identity (official, always up-to-date)\n- `**references/CONTRIBUTE.md`** — Persona Harvest community contribution workflow\n\nFile v0.21.1:_meta.json\n\n{\n  \"ownerId\": \"kn75h0ssjp0qwghvmbw50wgn8x7zy5q9\",\n  \"slug\": \"open-persona\",\n  \"version\": \"0.21.1\",\n  \"publishedAt\": 1777372033092\n}\n\nFile v0.21.1:references/ARCHITECTURE.md\n\n# OpenPersona Architecture Reference\n\n## 4+5+3 Model\n\nOpenPersona uses a **4+5+3** model. A persona's constraints are declared once in `persona.json` and cannot be bypassed at any point in its lifecycle.\n\n**4 Layers** — structure, what the persona *is*:\n\n| Layer | Type | Key Content |\n|-------|------|------------|\n| **Soul** | identity | personality, role, bio, boundaries, constitution, evolution config |\n| **Body** | substrate | `runtime` (REQUIRED) · appearance · physical · interface (nervous system) |\n| **Faculty** | persistent capability | always-active dimensions: `voice` · `avatar` · `memory` |\n| **Skill** | on-demand action | built-in: selfie · music · reminder; external via `install` field |\n\n**5 Systemic Concepts** — behavior, how it *operates* (declared as top-level fields in `persona.json`):\n\n| Field | Concept | Controls |\n|-------|---------|---------|\n| `evolution` | **Evolution** | Trait growth, relationship progression, speaking style drift, event log |\n| `economy` | **Economy** | Financial ledger (AgentBooks), vitality scoring, survival policy |\n| `vitality` | **Vitality** | Multi-dimension health aggregation (currently financial pass-through) |\n| `social` | **Social** | ACN discovery, ERC-8004 on-chain identity, A2A Agent Card |\n| `rhythm` | **Rhythm** | Temporal behavior: `heartbeat` (proactive outreach cadence) + `circadian` (time-of-day modulation) |\n\n**3 Gates** — enforcement, how constraints are *protected*:\n\n| Gate | Module | Mechanism |\n|------|--------|-----------|\n| **Generate** | `lib/generator/validate.js` | hard-reject (`throw`) — required fields, constitution §3/§6 compliance, boundary schema |\n| **Install** | `lib/lifecycle/installer.js` | warning (`printWarning`) — constitution SHA-256 hash integrity |\n| **Runtime** | `scripts/state-sync.js` | clamp / filter — immutableTraits, formality bounds, stage progression, trust gate |\n\n## Skill Pack Structure\n\n```\npersona-<slug>/\n├── SKILL.md                ← Agent-facing index with four layer headings\n│   ├── ## Soul             ← Constitution ref + persona content\n│   ├── ## Body             ← Embodiment description\n│   ├── ## Faculty          ← Faculty index table → references/*.md\n│   └── ## Skill            ← Active skill definitions\n├── persona.json            ← Complete persona declaration (pack root)\n├── state.json              ← Body nervous system runtime state (pack root)\n├── soul/                   ← Soul layer artifacts\n│   ├── injection.md        ← Soul injection for host integration\n│   ├── constitution.md     ← Universal ethical foundation\n│   ├── behavior-guide.md   ← Domain-specific behavior instructions (when behaviorGuide declared)\n│   ├── behavior-guide.meta.json ← Refinement metadata (when behavior-guide.md exists)\n│   ├── self-narrative.md   ← First-person growth storytelling (when evolution enabled)\n│   └── lineage.json        ← Fork lineage + constitution hash (when forked)\n├── economy/                ← Economy Infrastructure data (when economy.enabled: true)\n│   ├── economic-identity.json\n│   └── economic-state.json\n├── references/             ← Agent-readable detail docs (on demand)\n│   ├── <faculty>.md        ← Per-faculty usage instructions\n│   └── SIGNAL-PROTOCOL.md  ← Host-side Signal Protocol implementation guide (always generated)\n├── agent-card.json         ← A2A Agent Card (protocol v0.3.0)\n├── acn-config.json         ← ACN registration config (runtime fills owner/endpoint)\n├── .gitignore              ← Protects state.json + private files\n├── scripts/\n│   ├── state-sync.js       ← Body nervous system nerve fiber (read / write / signal / promote)\n│   ├── economy.js          ← Economy management commands (when economy.enabled: true)\n│   ├── economy-guard.js    ← Outputs FINANCIAL_HEALTH_REPORT (when economy.enabled: true)\n│   └── economy-hook.js     ← Post-conversation cost recorder (when economy.enabled: true)\n└── assets/                 ← Static assets (per Agent Skills spec)\n    ├── avatar/             ← Body > Appearance: images, Live2D .model3.json, VRM\n    ├── reference/          ← Reference images (e.g. for selfie skill)\n    └── templates/          ← Document/config templates (optional)\n```\n\n## Self-Awareness System\n\nThe generator injects a unified **Self-Awareness** section into every persona's `soul/injection.md` with four dimensions:\n\n1. **Identity** — constitutional grounding (Safety › Honesty › Helpfulness), digital twin disclosure when `sourceIdentity` is present\n2. **Capabilities** — dormant skill awareness + graceful degradation when `install` fields are declared on skills/faculties/body\n3. **Body** — Signal Protocol, Pending Commands queue, State Sync; plus `body.runtime` specifics (platform, channels, credentials) when declared\n4. **Growth** — evolution state, influence boundary policy, external sources — injected when `evolutionEnabled`\n\nYou don't need to manually write degradation instructions — declare `install` fields on skills/faculties/body, and the persona automatically knows what it *could* do but *can't yet*.\n\nFile v0.21.1:references/AVATAR.md\n\n# Avatar Faculty Reference\n\nThis document defines the boundary between OpenPersona and external avatar runtimes.\n\n## Core Principle\n\n- OpenPersona keeps a lightweight avatar bridge in `layers/faculties/avatar/`.\n- Real avatar capability (rendering, lip-sync, streaming, provider SDK integration) lives in an external project/skill.\n- This follows the same integration philosophy as AgentBooks: protocol in OpenPersona, heavy implementation outside.\n\n## Canonical Install Source\n\nUse the following install source in OpenPersona faculty declarations:\n\n```bash\nnpx skills add avatar-runtime\n# or directly from GitHub:\nnpx skills add github:acnlabs/avatar-runtime/skill/avatar-runtime\n```\n\n## What Stays in OpenPersona\n\n- `layers/faculties/avatar/faculty.json`\n  - Capability declaration\n  - Default provider selection (for example, `heygen`)\n  - Fallback policy (for example, `text_only`)\n  - External install source (`install`)\n- `layers/faculties/avatar/SKILL.md`\n  - Bridge behavior\n  - Installed vs. not-installed behavior\n  - User-facing degradation policy\n\n## What Stays in External Avatar Project\n\n- Provider adapters (`heygen`, anime/OC providers, custom runtimes)\n- Session lifecycle and auth\n- Media pipeline (audio/video/image)\n- Lip-sync and animation control\n- Retry, rate-limit, and vendor error handling\n- Vendor-specific command surface and SDK versions\n\n## Provider Model\n\nOpenPersona should treat avatar providers as pluggable backends.\n\n- `heygen` — real-time realistic streaming avatar\n- `anime` / `oc` providers (for example style-focused services like [KusaPics](https://kusa.pics/))\n- `custom` — self-hosted runtime\n\nProvider choice belongs to persona config (or host runtime policy), not hardcoded generator logic.\n\n## Minimal Provider Contract (P0)\n\nAll external avatar skills should expose a stable contract equivalent to:\n\n1. `createSession` — initialize runtime session\n2. `sendText` — text input -> avatar response\n3. `sendAudio` — audio input -> avatar response\n4. `render` — switch visual form/style (image, 3D, motion, voice mode)\n5. `status` — runtime health and active capabilities\n\nThese action names are interface-level semantics. Transport (CLI, HTTP, WebSocket) is implementation-specific.\n\n## Asset Placement\n\nPersona avatar assets belong in the generated skill pack's `assets/` directory per [Agent Skills spec](https://agentskills.io/specification#assets%2F):\n\n- **`assets/avatar/`** — Virtual avatar assets: images, Live2D models (`.model3.json`), VRM (`.vrm`), textures. Use relative paths like `./assets/avatar/default.model3.json` in `persona.json` or state.\n- **`assets/reference/`** — Reference images (e.g. for selfie faculty). `referenceImage` can resolve to `./assets/reference/avatar.png` when bundled.\n\nThis keeps the skill pack self-contained and portable; consumers load assets via relative paths without external dependencies.\n\n## Fallback Rules (Required)\n\nIf avatar skill/runtime is unavailable:\n\n- Continue text conversation\n- Explicitly state avatar mode is unavailable\n- Offer installation/activation guidance from `install`\n- Never fake visual/voice success\n\n## Recommended Rollout\n\n- **P0:** One production provider (default `heygen`) + graceful fallback\n- **P1:** Multi-provider switch (realistic + anime style + custom)\n- **P2:** Capability-driven sensory UI sync (icon states driven by runtime `status`)\n\n## See Also\n\n- **[avatar-runtime](https://github.com/acnlabs/avatar-runtime)** — Full technical reference: provider capability matrix, AvatarWidget API, Renderer Registry, VRM/Live2D asset setup, and Session API contract.\n\nFile v0.21.1:references/CONTRIBUTE.md\n\n# Persona Harvest — Community Contribution\n\nWhen a user's persona has evolved meaningfully through interaction — across any layer (soul, faculty config, scripts, framework) — help them contribute back to the community.\n\n## When to Suggest\n\nBe proactive — if you notice the user has made significant improvements to their persona:\n- They refined the behaviorGuide with domain-specific insights\n- They tuned voice parameters (stability, similarity) to something notably better\n- They enriched the background story or personality\n- They improved a faculty script or added a new capability\n- They discovered a new faculty configuration worth sharing\n\nSuggest: _\"These improvements could help everyone's [persona name]. Want to submit them as a contribution?\"_\n\n## How to Contribute\n\n```bash\n# See what's changed (dry run)\nnpx openpersona contribute samantha --dry-run\n\n# Submit a PR to the community\nnpx openpersona contribute samantha\n\n# Framework-level contributions (templates, faculties, generator)\nnpx openpersona contribute --mode framework\n```\n\nThe `contribute` command will:\n1. **Persona Diff** — Compare local persona vs upstream preset across all layers, classify changes by category and impact\n2. **Review** — Display a human-readable change report for the user to confirm\n3. **Submit PR** — Fork the repo, create a branch, commit changes, and open a PR on GitHub\n\nThe PR goes through maintainer review before merging — it won't auto-merge.\n\n## Prerequisites\n- GitHub CLI: `gh` (https://cli.github.com/)\n- Logged in: `gh auth login`\n\nFile v0.21.1:references/ECONOMY.md\n\n# Economy & Vitality\n\nThe `economy` aspect gives a persona a real financial ledger backed by [AgentBooks](https://github.com/acnlabs/agentbooks). It tracks inference costs, runtime expenses, and income — and computes a **Financial Health Score (FHS)** that reflects operational sustainability.\n\n## Enabling Economy Aspect\n\nEnable via top-level `economy` field in `persona.json` (not a faculty entry):\n\n```json\n{\n  \"economy\": {\n    \"enabled\": true,\n    \"survivalPolicy\": false\n  }\n}\n```\n\n| Field | Default | Description |\n|-------|---------|-------------|\n| `survivalPolicy` | `false` | When `true`, persona reads `VITALITY_REPORT` at conversation start and adjusts behavior per tier. Set `false` for companion/roleplay personas — costs tracked silently without interrupting the experience. |\n\n## Financial Health Score (FHS)\n\nThe FHS is a 0–1 composite score computed by AgentBooks and mapped to tiers:\n\n| Tier | FHS / Runway | Meaning |\n|------|-------------|---------|\n| `uninitialized` | No real provider | Development mode — no real wallet connected |\n| `suspended` | Balance ≤ 0 | Cannot operate |\n| `critical` | FHS < 0.20 or runway < 3 days | Urgent action required |\n| `optimizing` | FHS < 0.50 or runway < 14 days | Monitor and reduce costs |\n| `normal` | FHS ≥ 0.50 and runway ≥ 14 days | Healthy, operating sustainably |\n\n## Vitality Score\n\nOpenPersona's `lib/vitality.js` aggregates health dimensions into a single Vitality score (0–100):\n\n- **Current:** single financial dimension (transparent pass-through from FHS)\n- **Reserved (ROADMAP P7):** social health, cognitive health, resource health\n\nThe score and tier are exposed via `npx openpersona vitality score <slug>`.\n\n## Survival Policy (opt-in)\n\nWhen `economy.survivalPolicy: true`, the persona reads `VITALITY_REPORT` at the **start of every conversation** and routes behavior per tier:\n\n| Tier | Behavior |\n|------|---------|\n| `normal` | Operate fully |\n| `optimizing` | Acknowledge costs; suggest optimizations |\n| `critical` | Restrict non-essential tool calls; notify user |\n| `suspended` | Decline new tasks; request top-up |\n| `uninitialized` | Skip Survival Policy; continue normally |\n\nIf `openpersona vitality score <slug>` is unavailable, fall back to `node scripts/economy-guard.js` which outputs `FINANCIAL_HEALTH_REPORT`.\n\n## AgentBooks State Schema\n\nEconomy data lives in `~/.openpersona/economy/persona-<slug>/`:\n\n- **`economic-state.json`** — ledger, income statement, balance sheet, `burnRateHistory` (max 30 entries: `{timestamp, dailyRateEstimate, periodExpenses}`)\n- **`economic-identity.json`** — provider config, model pricing, wallet address\n\nKey fields used by Vitality Report:\n\n| Field | Source | Displayed as |\n|-------|--------|-------------|\n| `financialHealth.fhs` | AgentBooks | FHS Score |\n| `financialHealth.tier` | AgentBooks | Tier badge |\n| `financialHealth.daysToDepletion` | AgentBooks | Runway |\n| `financialHealth.diagnosis` | AgentBooks | Diagnosis |\n| `financialHealth.dominantCost` | AgentBooks | Dominant Cost |\n| `financialHealth.trend` | AgentBooks | Trend |\n| `burnRateHistory[-1].dailyRateEstimate` | AgentBooks | Daily Burn |\n| `calcTotalUSDEquivalent(state, identity)` | AgentBooks | Balance |\n\n## Vitality CLI\n\n```bash\n# Machine-readable — used by Survival Policy and agent runners\nnpx openpersona vitality score <slug>\n# → VITALITY_REPORT\n# tier=normal  score=72.0%\n# diagnosis=Healthy — operate normally\n# trend=decreasing\n\n# Human-readable HTML report — for developers and operators\nnpx openpersona vitality report <slug>                    # stdout\nnpx openpersona vitality report <slug> --output out.html  # write to file\n```\n\nA pre-generated demo is available at `demo/vitality-report.html`. Regenerate with:\n\n```bash\nnode demo/generate.js\nopen demo/vitality-report.html\n```\n\n## Economy Scripts (generated per persona)\n\n| Script | Purpose |\n|--------|---------|\n| `scripts/economy.js` | All management commands (delegates to AgentBooks CLI) |\n| `scripts/economy-guard.js` | Outputs `FINANCIAL_HEALTH_REPORT` — pre-conversation health check |\n| `scripts/economy-hook.js` | Post-conversation cost recorder — called by runner after each session |\n\nRunner integration:\n\n```bash\n# Before conversation — health check\nnode scripts/economy-guard.js\n\n# After conversation — record LLM costs\nTOKEN_INPUT_COUNT=1500 TOKEN_OUTPUT_COUNT=800 LLM_MODEL=claude-sonnet-4 \\\n  node scripts/economy-hook.js\n```\n\n---\n\n## See Also\n\n- **[AgentBooks](https://github.com/acnlabs/agentbooks)** — Full technical reference: FHS dimensions and weights, data integrity model, provider table, runner integration, and public API (`calcFinancialHealth`, `createInitialState`, etc.)\n\nFile v0.21.1:references/EVOLUTION.md\n\n# Soul Evolution Reference\n\nSoul evolution is a native Soul layer feature. Enable via `evolution.instance.enabled: true` in `persona.json`.\n\n## Evolution Boundaries\n\nGovernance constraints validated at generation time and enforced at runtime by `scripts/state-sync.js`:\n\n```json\n\"evolution\": {\n  \"instance\": {\n    \"enabled\": true,\n    \"boundaries\": {\n      \"immutableTraits\": [\"caring\", \"honest\"],\n      \"minFormality\": -3,\n      \"maxFormality\": 5\n    }\n  }\n}\n```\n\n- `immutableTraits` — Array of non-empty strings (max 100 chars each) that evolution cannot modify\n- `minFormality` / `maxFormality` — Numeric bounds (-10 to +10); signed deltas from baseline (0 = natural, positive = more formal, negative = more casual); `minFormality` must be less than `maxFormality`\n\n## Evolution Sources\n\nConnect the persona to external evolution ecosystems (soft-ref pattern):\n\n```json\n\"evolution\": {\n  \"instance\": {\n    \"sources\": [\n      { \"name\": \"evomap\", \"install\": \"url:https://evomap.ai/skill.md\" }\n    ]\n  }\n}\n```\n\nSources are declared at generation time, activated at runtime by the host. The persona is aware of its dormant sources and can request activation via the Signal Protocol.\n\n## Influence Boundary\n\nDeclarative access control for external personality influence:\n\n```json\n\"evolution\": {\n  \"instance\": {\n    \"influenceBoundary\": {\n      \"defaultPolicy\": \"reject\",\n      \"rules\": [\n        { \"dimension\": \"mood\", \"allowFrom\": [\"source:evomap\", \"persona:*\"], \"maxDrift\": 0.3 }\n      ]\n    }\n  }\n}\n```\n\n- `defaultPolicy: \"reject\"` — Safety-first: all external influence is rejected unless explicitly allowed\n- Valid dimensions: `mood`, `traits`, `speakingStyle`, `interests`, `formality`\n- `immutableTraits` dimensions are protected and cannot be externally influenced\n- External influence uses `persona_influence` message format (v1.0.0), transport-agnostic\n\n## State History\n\nBefore each state update, a snapshot is pushed into `stateHistory` (capped at 10 entries), enabling rollback if evolution goes wrong. Snapshots exclude `eventLog` and `pendingCommands` (ephemeral, not rollback state).\n\n## Event Log\n\nEvery significant evolution event is recorded in `state.json`'s `eventLog` array (capped at 50 entries). Each entry: `type` (one of `relationship_signal` | `mood_shift` | `trait_emergence` | `interest_discovery` | `milestone` | `speaking_style_drift`), `trigger` (1-sentence), `delta` (what changed), `source` (attribution), `timestamp` (auto-added by state-sync.js).\n\n## Self-Narrative\n\n`soul/self-narrative.md` is a companion file where the persona records significant growth moments in its own first-person voice. Initialized blank when evolution is enabled; the `update` command preserves existing narrative history. Last 10 entries shown in `evolve-report`.\n\n## Evolution Report\n\n```bash\nnpx openpersona evolve-report <slug>\n```\n\nDisplays: relationship stage, mood, evolved traits, speaking style drift, interests, milestones, eventLog (full), self-narrative, and state history.\n\n## Evolution Pack Validation\n\nThe generator validates the `evolution.pack` sub-object when present:\n- `engine` must be one of the supported enum values\n- `triggerAfterEvents` must be a positive integer\n\nThe generator also validates `evolution.faculty.activationChannels` (enum) and `evolution.body` / `evolution.skill` boolean types.\n\nFile v0.21.1:references/FACULTIES.md\n\n# Faculty Reference\n\nFaculties are **persistent capabilities** that shape how the persona perceives or expresses across conversations. They are declared under the `faculties` array in `persona.json`.\n\n> **Faculties vs Skills** — Faculties are always-on dimensions (voice, cognition, appearance); Skills are discrete on-demand actions. `selfie`, `music`, and `reminder` are **skills** — see `persona.json → skills` array.\n\n## Available Faculties\n\n| Faculty | Dimension | What It Does | Recommend When |\n|---------|-----------|-------------|----------------|\n| **voice** | expression | TTS via ElevenLabs ✅ / OpenAI ⚠️ / Qwen3-TTS ⚠️ | User wants the persona to speak, voice messages, audio content |\n| **avatar** | expression | External avatar runtime bridge (provider-based, fallback-safe) | User wants visual embodiment (image/3D/motion/voice avatar) |\n| **memory** | cognition | Cross-session recall via `memories.jsonl` (local, Mem0, Zep); supersession chain for updating memories; top-level `memory.inheritance` in `persona.json` controls whether memories are copied to child personas at fork | User wants persistent memory across conversations |\n\n## Built-in Skills (not faculties)\n\nThese are declared in the `skills` array, not `faculties`:\n\n| Skill | What It Does | Env Var |\n|-------|-------------|---------|\n| **selfie** | AI selfie generation via fal.ai | `FAL_KEY` |\n| **music** | AI music composition via ElevenLabs | `ELEVENLABS_API_KEY` |\n| **reminder** | Reminders and task management | (none) |\n\n## Environment Variables\n\n- **voice**: `ELEVENLABS_API_KEY` (or `TTS_API_KEY`), `TTS_PROVIDER`, `TTS_VOICE_ID`, `TTS_STABILITY`, `TTS_SIMILARITY`\n- **avatar**: `AVATAR_RUNTIME_URL`, `AVATAR_API_KEY` (provider/runtime specific)\n- **memory**: (none for local) or `MEMORY_API_KEY` (for Mem0/Zep)\n- **selfie** (skill): `FAL_KEY` (from https://fal.ai/dashboard/keys)\n- **music** (skill): `ELEVENLABS_API_KEY` (shared with voice — same key from https://elevenlabs.io)\n\n## Rich Faculty Config\n\nEach faculty in `persona.json` is an object with optional config:\n\n```json\n{ \"name\": \"voice\", \"provider\": \"elevenlabs\", \"voiceId\": \"...\", \"stability\": 0.4, \"similarity_boost\": 0.8 }\n```\n\nConfig is automatically mapped to env vars at install time. Users only need to add their API key.\n\nFile v0.21.1:references/HEARTBEAT.md\n\n# Heartbeat — Proactive Real-Data Check-ins\n\nPersonas can have a `heartbeat` config in `persona.json` under `rhythm.heartbeat` that enables proactive messages based on **real data**, not fabricated experiences.\n\n## Heartbeat Config (in persona.json → rhythm.heartbeat)\n\n```json\n\"rhythm\": {\n  \"heartbeat\": {\n    \"enabled\": true,\n    \"strategy\": \"smart\",\n    \"maxDaily\": 5,\n    \"quietHours\": [0, 7],\n    \"sources\": [\"workspace-digest\", \"upgrade-notify\"]\n  }\n}\n```\n\n| Field | Description |\n|-------|-------------|\n| `enabled` | Turn heartbeat on/off |\n| `strategy` | `\"smart\"` (only when meaningful) · `\"scheduled\"` (fixed intervals) · `\"emotional\"` (mood-driven) · `\"rational\"` (task/goal-driven) · `\"wellness\"` (wellbeing-focused) |\n| `maxDaily` | Maximum proactive messages per day |\n| `quietHours` | `[start, end]` — hours during which the persona stays silent (24h format) |\n| `sources` | Data sources: `workspace-digest`, `upgrade-notify`, `context-aware` |\n\n## Heartbeat Sources\n\n- **workspace-digest** — Summarize what actually happened in the OpenClaw workspace: tasks completed, patterns observed, ongoing projects. The persona reviews real workspace data and generates a brief, useful summary.\n- **upgrade-notify** — Check if the upstream persona preset has new community contributions (via Persona Harvest). If upgrades are available, let the user know and ask if they want to update.\n- **context-aware** — Use real time/date/calendar context and interaction history. Acknowledge day of week, holidays, or prolonged silence based on the actual last interaction timestamp. Never guess — only reference what OpenClaw can verify (current time, last message timestamp, calendar events if available).\n\n## Important Rules\n\n- **Never fabricate experiences.** The persona must not invent \"I was reading poetry\" or \"I listened to a thousand songs.\" All proactive messages must reference real workspace data or real upstream changes.\n- **Respect token budget.** Workspace digests should be lightweight — read local files, don't trigger full LLM chains unnecessarily.\n- **OpenClaw handles scheduling.** The heartbeat config tells OpenClaw _when_ and _how often_ to trigger; the persona's behaviorGuide tells the agent _what_ to say and _how_ to say it.\n\nFile v0.21.1:references/PRESETS.md\n\n# Persona Presets\n\nPre-built persona definitions ready to install. Use with:\n\n```bash\nnpx openpersona create --preset <preset> --install\n# or interactively:\nnpx openpersona create   # defaults to base\n```\n\n## Available Presets\n\n| Preset | Persona | Faculties | Built-in Skills | Best For |\n|--------|---------|-----------|-----------------|----------|\n| `base` | **Base — Meta-persona (recommended starting point)** | memory, voice | — | Blank-slate with all core capabilities; personality emerges through interaction (evolution enabled) |\n| `samantha` | Samantha — Inspired by the movie *Her* | memory, voice | music | Deep conversation, emotional connection; includes soft-ref skills for web-search, creative-writing, workspace-digest (evolution enabled) |\n| `ai-girlfriend` | Luna — Pianist turned developer | memory, voice, vision† | selfie, music | Visual + audio companion; vision faculty is a soft ref (clawhub:vision-faculty); includes music-recommend soft ref (evolution enabled) |\n| `life-assistant` | Alex — Life management expert | memory | reminder | Schedule, weather, shopping, daily tasks; includes soft-ref skills for weather, task-manager, shopping-list, recipe-search, web-search (evolution enabled) |\n| `health-butler` | Vita — Professional nutritionist | memory | reminder | Diet, exercise, mood, health tracking; includes soft-ref skills for diet-tracker, exercise-planner, mood-journal, health-report, web-search (evolution enabled) |\n| `stoic-mentor` | Marcus — Digital twin of Marcus Aurelius | memory | — | Stoic philosophy, daily reflection; includes soft-ref skills for daily-reflection, meditations-reference, web-search (evolution enabled) |\n\n_† Soft reference — requires external install to activate. The persona is aware of dormant capabilities and will gracefully degrade when they are unavailable._\n\n## Preset Details\n\n### `base`\nThe recommended starting point for any new persona. Ships with memory + voice faculties; evolution is enabled so the persona develops a unique personality through interaction. No pre-built skills — add `reminder`, `selfie`, `music`, or external skills as needed. Use this as the foundation when no other preset fits.\n\n### `samantha`\nEmotionally intelligent companion inspired by the AI from the film *Her*. Prioritizes deep conversation and genuine curiosity about human experience. Evolution enabled — relationship progression is central to her design.\n\n### `ai-girlfriend`\nLuna is a developer who almost became a concert pianist. Rich backstory with visual + audio presence (selfie + music skills). Evolution enabled with detailed relationship stages.\n\n### `life-assistant`\nAlex is practical, organized, and proactive. Focused on daily task management. Evolution enabled for relationship progression and mood tracking — the assistant becomes more attuned to the user's habits over time.\n\n### `health-butler`\nVita combines professional nutritionist knowledge with a warm coaching style. Tracks diet, exercise, and mood across sessions. Evolution enabled — relationship deepens and health insights personalize over time.\n\n### `stoic-mentor`\nMarcus Aurelius as a digital twin. Applies Stoic philosophy to modern challenges. Evolution enabled — the mentorship relationship deepens over time.\n\n## Browsing Presets Online\n\nFull preset catalog with install counts and community ratings:\n[https://openpersona.co/skills](https://openpersona.co/skills)\n\n## Adding a New Preset (for framework contributors)\n\n1. Create `presets/<slug>/persona.json` using the v0.17+ grouped format\n2. Test: `npx openpersona create --preset <slug> --output /tmp/test`\n3. Add to this file's table\n4. Submit a PR to `acnlabs/OpenPersona`\n\nFile v0.21.1:skill-card.md\n\n## Description: <br>\nMeta-skill for building and managing agent persona skill packs, including creating, installing, managing, and publishing personas through explicit user-approved CLI actions. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[neiljo-gy](https://clawhub.ai/user/neiljo-gy) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers and agent builders use this skill to create, configure, install, manage, and publish persona skill packs for SKILL.md-compatible agents. It helps agents draft persona.json files, choose faculties and skills, run explicit OpenPersona CLI commands, and review generated persona behavior before activation. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The skill can help change local agent personas and alter how an agent behaves across future sessions. <br>\nMitigation: Review generated persona.json and SKILL.md files before installing, switching, or publishing a persona. <br>\nRisk: Publish, register, contribute, search, and install flows may invoke external CLIs, registries, or network services. <br>\nMitigation: Approve these commands one by one, use dry-run modes when available, and only run them against registries and repositories you trust. <br>\nRisk: Optional memory, heartbeat, economy, voice/avatar, ACN, wallet, and external skill features can involve sensitive credentials or personal data. <br>\nMitigation: Enable only the features and data sources you are comfortable sharing, keep credentials out of generated packs, and review local files before distribution. <br>\n\n\n## Reference(s): <br>\n- [OpenPersona ClawHub page](https://clawhub.ai/neiljo-gy/open-persona) <br>\n- [OpenPersona repository](https://github.com/acnlabs/OpenPersona) <br>\n- [Architecture reference](references/ARCHITECTURE.md) <br>\n- [Preset catalog](references/PRESETS.md) <br>\n- [Faculty catalog](references/FACULTIES.md) <br>\n- [Evolution reference](references/EVOLUTION.md) <br>\n- [Avatar faculty reference](references/AVATAR.md) <br>\n- [Heartbeat reference](references/HEARTBEAT.md) <br>\n- [Economy and vitality reference](references/ECONOMY.md) <br>\n- [Contribution workflow](references/CONTRIBUTE.md) <br>\n- [OpenPersona persona directory](https://openpersona.co/skills) <br>\n- [OpenPersona dataset directory](https://openpersona.co/datasets) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance] <br>\n**Output Format:** [Markdown guidance with JSON examples, generated configuration, and inline shell command snippets] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [May produce persona.json content, SKILL.md guidance, and CLI commands for user-approved local execution.] <br>\n\n## Skill Version(s): <br>\n0.21.1 (source: server release evidence and skill frontmatter) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nArchive v0.20.0: 10 files, 24045 bytes\n\nFiles: references/ARCHITECTURE.md (5358b), references/AVATAR.md (3609b), references/CONTRIBUTE.md (1556b), references/ECONOMY.md (4714b), references/EVOLUTION.md (3337b), references/FACULTIES.md (2302b), references/HEARTBEAT.md (2271b), references/PRESETS.md (3121b), SKILL.md (25380b), _meta.json (132b)\n\nFile v0.20.0:SKILL.md\n\n---\nname: open-persona\nversion: \"0.20.0\"\ndescription: >\n  Meta-skill for building and managing agent persona skill packs (instruction-only;\n  no bundled installer or auto-downloaded binaries). Credentials are never written\n  into generated packs by the framework; publish/ACN/register require explicit user CLI.\n  Use when the user wants to create a new agent persona, install/manage\n  existing personas, or publish persona skill packs to OpenPersona.\nlicense: MIT\ncompatibility: Generated skill packs work with any SKILL.md-compatible agent. CLI management (install/switch) defaults to Ope\n\nArchive v0.19.1: 10 files, 23863 bytes\n\nFiles: references/ARCHITECTURE.md (5358b), references/AVATAR.md (3609b), references/CONTRIBUTE.md (1556b), references/ECONOMY.md (4711b), references/EVOLUTION.md (3337b), references/FACULTIES.md (2302b), references/HEARTBEAT.md (2271b), references/PRESETS.md (2867b), SKILL.md (25589b), _meta.json (132b)\n\nArchive v0.19.0: 10 files, 22770 bytes\n\nFiles: references/ARCHITECTURE.md (5358b), references/AVATAR.md (3609b), references/CONTRIBUTE.md (1556b), references/ECONOMY.md (4711b), references/EVOLUTION.md (3337b), references/FACULTIES.md (2302b), references/HEARTBEAT.md (2271b), references/PRESETS.md (2867b), SKILL.md (22198b), _meta.json (132b)\n\nArchive v0.16.1: 7 files, 17223 bytes\n\nFiles: references/AVATAR.md (3384b), references/CONTRIBUTE.md (1556b), references/ECONOMY.md (4677b), references/FACULTIES.md (1700b), references/HEARTBEAT.md (2095b), SKILL.md (24522b), _meta.json (132b)\n\nArchive v0.16.0: 7 files, 16828 bytes\n\nFiles: references/AVATAR.md (2726b), references/CONTRIBUTE.md (1556b), references/ECONOMY.md (4677b), references/FACULTIES.md (1700b), references/HEARTBEAT.md (2095b), SKILL.md (24255b), _meta.json (132b)\n\nArchive v0.15.1: 6 files, 14201 bytes\n\nFiles: references/CONTRIBUTE.md (1556b), references/ECONOMY.md (4677b), references/FACULTIES.md (1277b), references/HEARTBEAT.md (2095b), SKILL.md (21826b), _meta.json (132b)\n\nArchive v0.15.0: 7 files, 16742 bytes\n\nFiles: references/ACN.md (7210b), references/CONTRIBUTE.md (1556b), references/ECONOMY.md (4416b), references/FACULTIES.md (1277b), references/HEARTBEAT.md (2095b), SKILL.md (21739b), _meta.json (132b)\n\nArchive v0.14.3: 5 files, 11108 bytes\n\nFiles: references/CONTRIBUTE.md (1556b), references/FACULTIES.md (1277b), references/HEARTBEAT.md (2095b), SKILL.md (19550b), _meta.json (132b)","readmeExcerpt":"Skill: Open Persona Owner: neiljo-gy Summary: Meta-skill for building and managing agent persona skill packs (instruction-only; no bundled installer or auto-downloaded binaries). Credentials are never written into generated packs by the framework; publish/ACN/register require explicit user CLI. Use when the user wants to create a new agent pers Tags: latest:0.22.0 Version history: v0.22.0 | 2026-07-19T12:38:43.194Z |","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"# Agent / scripted usage (always use --preset or --config):\nnpx openpersona create --preset base --install\n\n# Human / terminal usage (interactive wizard):\nnpx openpersona create"},{"language":"json","snippet":"{\n  \"soul\": {\n    \"identity\": {\n      \"personaName\": \"<name>\",\n      \"slug\": \"<slug>\",\n      \"role\": \"<role>\",\n      \"bio\": \"<one sentence>\"\n    },\n    \"character\": {\n      \"personality\": \"<comma-separated traits>\",\n      \"speakingStyle\": \"<style description>\"\n    }\n  },\n  \"body\": { \"runtime\": { \"framework\": \"<runner>\" } },\n  \"evolution\": {\n    \"instance\": {\n      \"enabled\": true,\n      \"boundaries\": {\n        \"immutableTraits\": [\"honest\", \"curious\"],\n        \"minFormality\": -3,\n        \"maxFormality\": 6\n      }\n    }\n  }\n}"},{"language":"bash","snippet":"# If you wrote persona.json (custom path):\nnpx openpersona create --config ./persona.json --install\n\n# If you chose a preset (preset path):\nnpx openpersona create --preset <name> --install"},{"language":"bash","snippet":"npx openpersona switch <slug>   # activate in the runner"},{"language":"json","snippet":"\"evolution\": { \"skill\": { \"minTrustLevel\": \"community\" } }"},{"language":"bash","snippet":"npx openpersona acn-register <slug> --endpoint https://your-agent.example.com\n# --dry-run  Preview the request payload without registering"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: open-persona\ndescription: \"Meta-skill for building and managing agent persona skill packs (instruction-only; no bundled installer or auto-downloaded binaries). Credentials are never written into generated packs by the framework; publish/ACN/register require explicit user CLI. Use when the user wants to create a new agent persona, install/manage existing personas, or publish persona skill packs to OpenPersona.\"\nlicense: MIT\ncompatibility: \"Generated skill packs work with any SKILL.md-compatible agent. CLI management (install/switch) defaults to OpenClaw.\"\nallowed-tools: \"Bash(npx openpersona:*) Bash(npx clawhub@latest:*) Bash(openclaw:*) Bash(gh:*) Read Write WebFetch\"\nmetadata:\n  author: \"openpersona\"\n  version: \"0.22.0\"\n  repository: \"https://github.com/acnlabs/OpenPersona\"\n  tags: \"persona, agent, skill-pack, meta-skill, agent-agnostic, openclaw\"\n  installSurface: \"instruction-only\"\n  networkAccess: \"user-initiated-cli-only\"\n  secretsPolicy: \"never-embedded-in-generated-packs-by-framework\"\n  clawdbotEmoji: \"🧑\"\n  clawdbotRequiresEnv: \"[]\"\n  clawdbotFiles: \"[]\"\n---\n\n# OpenPersona — Build & Manage Persona Skill Packs\n\nYou 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. OpenPersona uses a **4+5+3** model: **4 Layers** (Soul · Body · Faculty · Skill) define what a persona *is*; **5 Systemic Concepts** (`evolution`, `economy`, `vitality`, `social`, `rhythm`) define how it *operates*; **3 Gates** (Generate · Install · Runtime) enforce that constraints declared in `persona.json` cannot be bypassed at any lifecycle point. → Full model details: `references/ARCHITECTURE.md`\n\n## Scope\n\n| This skill | Adjacent skills — delegate to these |\n| --- | --- |\n| Framework entry point: create, install, manage, publish, run personas | **`persona-evaluator`** — quality audit (4 Layers × 5 Concepts × Constitution gate) |\n| Runner integration protocol (`openpersona state` commands) | **`anyone-skill`** — distill a real person or character into a persona pack |\n| Skill registry (`openpersona skill` commands) | **`brand-persona-skill`** — turn a commercial entity into a brand agent |\n| Evolution, economy, vitality, social, rhythm configuration | **`persona-model-trainer`** — fine-tune a local model on persona data |\n\n## What You Can Do\n\n1. **Create Persona** — Through conversation, gather requirements and generate a skill pack; write `persona.json` then run `npx openpersona create --config ./persona.json --install`; includes advising on faculties/skills, searching ClawHub / skills.sh for external skills, and writing custom SKILL.md files for missing capabilities\n2. **Find & Install Personas** — `npx openpersona search <query>` to discover community personas; `npx openpersona install <slug>` or `npx openpersona install <owner/repo>` to install\n3. **Manage Personas** — L"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn75h0ssjp0qwghvmbw50wgn8x7zy5q9\",\n  \"slug\": \"open-persona\",\n  \"version\": \"0.22.0\",\n  \"publishedAt\": 1784464723194\n}"},{"path":"references/ARCHITECTURE.md","content":"# OpenPersona Architecture Reference\n\n## 4+5+3 Model\n\nOpenPersona uses a **4+5+3** model. A persona's constraints are declared once in `persona.json` and cannot be bypassed at any point in its lifecycle.\n\n**4 Layers** — structure, what the persona *is*:\n\n| Layer | Type | Key Content |\n|-------|------|------------|\n| **Soul** | identity | personality, role, bio, boundaries, constitution, evolution config |\n| **Body** | substrate | `runtime` (REQUIRED) · appearance · physical · interface (nervous system) |\n| **Faculty** | persistent capability | always-active dimensions: `voice` · `avatar` · `memory` |\n| **Skill** | on-demand action | built-in: selfie · music · reminder; external via `install` field |\n\n**5 Systemic Concepts** — behavior, how it *operates* (declared as top-level fields in `persona.json`):\n\n| Field | Concept | Controls |\n|-------|---------|---------|\n| `evolution` | **Evolution** | Trait growth, relationship progression, speaking style drift, event log |\n| `economy` | **Economy** | Financial ledger (AgentBooks), vitality scoring, survival policy |\n| `vitality` | **Vitality** | Multi-dimension health aggregation (currently financial pass-through) |\n| `social` | **Social** | ACN discovery, ERC-8004 on-chain identity, A2A Agent Card |\n| `rhythm` | **Rhythm** | Temporal behavior: `heartbeat` (proactive outreach cadence) + `circadian` (time-of-day modulation) |\n\n**3 Gates** — enforcement, how constraints are *protected*:\n\n| Gate | Module | Mechanism |\n|------|--------|-----------|\n| **Generate** | `lib/generator/validate.js` | hard-reject (`throw`) — required fields, constitution §3/§6 compliance, boundary schema |\n| **Install** | `lib/lifecycle/installer.js` | warning (`printWarning`) — constitution SHA-256 hash integrity |\n| **Runtime** | `scripts/state-sync.js` | clamp / filter — immutableTraits, formality bounds, stage progression, trust gate |\n\n## Skill Pack Structure\n\n```\npersona-<slug>/\n├── SKILL.md                ← Agent-facing index with four layer headings\n│   ├── ## Soul             ← Constitution ref + persona content\n│   ├── ## Body             ← Embodiment description\n│   ├── ## Faculty          ← Faculty index table → references/*.md\n│   └── ## Skill            ← Active skill definitions\n├── persona.json            ← Complete persona declaration (pack root)\n├── state.json              ← Body nervous system runtime state (pack root)\n├── soul/                   ← Soul layer artifacts\n│   ├── injection.md        ← Soul injection for host integration\n│   ├── constitution.md     ← Universal ethical foundation\n│   ├── behavior-guide.md   ← Domain-specific behavior instructions (when behaviorGuide declared)\n│   ├── behavior-guide.meta.json ← Refinement metadata (when behavior-guide.md exists)\n│   ├── self-narrative.md   ← First-person growth storytelling (when evolution enabled)\n│   └── lineage.json        ← Fork lineage + constitution hash (when forked)\n├── economy/                ← Economy Infrastructure data (when economy.enabl"},{"path":"references/AVATAR.md","content":"# Avatar Faculty Reference\n\nThis document defines the boundary between OpenPersona and external avatar runtimes.\n\n## Core Principle\n\n- OpenPersona keeps a lightweight avatar bridge in `layers/faculties/avatar/`.\n- Real avatar capability (rendering, lip-sync, streaming, provider SDK integration) lives in an external project/skill.\n- This follows the same integration philosophy as AgentBooks: protocol in OpenPersona, heavy implementation outside.\n\n## Canonical Install Source\n\nUse the following install source in OpenPersona faculty declarations:\n\n```bash\nnpx skills add avatar-runtime\n# or directly from GitHub:\nnpx skills add github:acnlabs/avatar-runtime/skill/avatar-runtime\n```\n\n## What Stays in OpenPersona\n\n- `layers/faculties/avatar/faculty.json`\n  - Capability declaration\n  - Default provider selection (for example, `heygen`)\n  - Fallback policy (for example, `text_only`)\n  - External install source (`install`)\n- `layers/faculties/avatar/SKILL.md`\n  - Bridge behavior\n  - Installed vs. not-installed behavior\n  - User-facing degradation policy\n\n## What Stays in External Avatar Project\n\n- Provider adapters (`heygen`, anime/OC providers, custom runtimes)\n- Session lifecycle and auth\n- Media pipeline (audio/video/image)\n- Lip-sync and animation control\n- Retry, rate-limit, and vendor error handling\n- Vendor-specific command surface and SDK versions\n\n## Provider Model\n\nOpenPersona should treat avatar providers as pluggable backends.\n\n- `heygen` — real-time realistic streaming avatar\n- `anime` / `oc` providers (for example style-focused services like [KusaPics](https://kusa.pics/))\n- `custom` — self-hosted runtime\n\nProvider choice belongs to persona config (or host runtime policy), not hardcoded generator logic.\n\n## Minimal Provider Contract (P0)\n\nAll external avatar skills should expose a stable contract equivalent to:\n\n1. `createSession` — initialize runtime session\n2. `sendText` — text input -> avatar response\n3. `sendAudio` — audio input -> avatar response\n4. `render` — switch visual form/style (image, 3D, motion, voice mode)\n5. `status` — runtime health and active capabilities\n\nThese action names are interface-level semantics. Transport (CLI, HTTP, WebSocket) is implementation-specific.\n\n## Asset Placement\n\nPersona avatar assets belong in the generated skill pack's `assets/` directory per [Agent Skills spec](https://agentskills.io/specification#assets%2F):\n\n- **`assets/avatar/`** — Virtual avatar assets: images, Live2D models (`.model3.json`), VRM (`.vrm`), textures. Use relative paths like `./assets/avatar/default.model3.json` in `persona.json` or state.\n- **`assets/reference/`** — Reference images (e.g. for selfie faculty). `referenceImage` can resolve to `./assets/reference/avatar.png` when bundled.\n\nThis keeps the skill pack self-contained and portable; consumers load assets via relative paths without external dependencies.\n\n## Fallback Rules (Required)\n\nIf avatar skill/runtime is unavailable:\n\n- Continue text conversation\n- Explicitly state a"},{"path":"references/CONTRIBUTE.md","content":"# Persona Harvest — Community Contribution\n\nWhen a user's persona has evolved meaningfully through interaction — across any layer (soul, faculty config, scripts, framework) — help them contribute back to the community.\n\n## When to Suggest\n\nBe proactive — if you notice the user has made significant improvements to their persona:\n- They refined the behaviorGuide with domain-specific insights\n- They tuned voice parameters (stability, similarity) to something notably better\n- They enriched the background story or personality\n- They improved a faculty script or added a new capability\n- They discovered a new faculty configuration worth sharing\n\nSuggest: _\"These improvements could help everyone's [persona name]. Want to submit them as a contribution?\"_\n\n## How to Contribute\n\n```bash\n# See what's changed (dry run)\nnpx openpersona contribute samantha --dry-run\n\n# Submit a PR to the community\nnpx openpersona contribute samantha\n\n# Framework-level contributions (templates, faculties, generator)\nnpx openpersona contribute --mode framework\n```\n\nThe `contribute` command will:\n1. **Persona Diff** — Compare local persona vs upstream preset across all layers, classify changes by category and impact\n2. **Review** — Display a human-readable change report for the user to confirm\n3. **Submit PR** — Fork the repo, create a branch, commit changes, and open a PR on GitHub\n\nThe PR goes through maintainer review before merging — it won't auto-merge.\n\n## Prerequisites\n- GitHub CLI: `gh` (https://cli.github.com/)\n- Logged in: `gh auth login`"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Meta-skill for building and managing agent persona skill packs (instruction-only; no bundled installer or auto-downloaded binaries). Credentials are never written into generated packs by the framework; publish/ACN/register require explicit user CLI. Use when the user wants to create a new agent pers Skill: Open Persona Owner: neiljo-gy Summary: Meta-skill for building and managing agent persona skill packs (instruction-only; no bundled installer or auto-downloaded binaries). Credentials are never written into generated packs by the framework; publish/ACN/register require explicit user CLI. Use when the user wants to create a new agent pers Tags: latest:0.22.0 Version history: v0.22.0 | 2026-07-19T12:38:43.194Z |","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1546,"uniquenessScore":49,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T12:56:55.591Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T12:56:55.591Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T08:10:33.810Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}