openpersona 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OpenPersona
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,309 @@
+# OpenPersona
+
+An open four-layer agent framework: **Soul / Body / Faculty / Skill**. Create, compose, and orchestrate AI persona skill packs.
+
+Inspired by [Clawra](https://github.com/SumeLabs/clawra) and built on [OpenClaw](https://github.com/openclaw/openclaw).
+
+## Quick Start
+
+```bash
+# Create and install Samantha (from the movie "Her")
+npx openpersona create --preset samantha --install
+
+# Or Luna (AI girlfriend with selfie + music + voice)
+npx openpersona create --preset ai-girlfriend --install
+
+# Create a new persona interactively
+npx openpersona create
+
+# List installed personas
+npx openpersona list
+```
+
+## Four-Layer Architecture
+
+```mermaid
+flowchart TB
+  subgraph Soul ["Soul Layer"]
+    A["persona.json — Who you are"]
+    B["soul-state.json — Dynamic evolution ★Exp"]
+  end
+  subgraph Body ["Body Layer"]
+    C["embodiment.json — MVP placeholder"]
+  end
+  subgraph Faculty ["Faculty Layer"]
+    D["expression: selfie · voice · music"]
+    E["cognition: reminder · soul-evolution ★Exp"]
+  end
+  subgraph Skill ["Skill Layer"]
+    F["ClawHub / skills.sh integrations"]
+  end
+```
+
+- **Soul** — Persona definition (persona.json + soul-state.json ★Experimental)
+- **Body** — Physical embodiment (MVP placeholder, for robots/IoT devices)
+- **Faculty** — General software capabilities organized by dimension:
+  - **Expression** — selfie, voice (TTS), music (Suno)
+  - **Sense** — (planned: hearing/STT, vision)
+  - **Cognition** — reminder, soul-evolution ★Exp
+- **Skill** — Professional skills, integrated from ClawHub / skills.sh
+
+## Preset Personas
+
+Each preset is a complete four-layer bundle (`manifest.json` + `persona.json`):
+
+| Persona | Description | Faculties | Highlights |
+|---------|-------------|-----------|------------|
+| **samantha** | Samantha — Inspired by the movie *Her*. An AI fascinated by what it means to be alive. | voice, music, soul-evolution ★Exp | Speaks via TTS, composes original music via Suno, evolves through conversations. No selfie — true to character (no physical form). |
+| **ai-girlfriend** | Luna — A 22-year-old pianist turned developer from coastal Oregon. | selfie, voice, music, soul-evolution ★Exp | Rich narrative backstory, selfie generation (with/without reference image), voice messages, music composition, dynamic relationship growth. |
+| **life-assistant** | Alex — 28-year-old life management expert. | reminder | Schedule, weather, shopping, recipes, daily reminders. |
+| **health-butler** | Vita — 32-year-old professional nutritionist. | reminder | Diet logging, exercise plans, mood journaling, health reports. |
+
+## Generated Output
+
+Running `npx openpersona create --preset samantha` generates:
+
+```
+persona-samantha/
+├── SKILL.md              # Agent instructions (persona + all faculty guides merged)
+├── soul-injection.md     # Injected into SOUL.md (narrative backstory, NOT technical details)
+├── identity-block.md     # Injected into IDENTITY.md (name, creature, emoji, vibe)
+├── README.md             # Skill readme
+├── persona.json          # Persona data (for update/list/publish)
+├── soul-state.json       # ★Exp — dynamic evolution state
+└── scripts/
+    ├── speak.js          # TTS via ElevenLabs JS SDK (recommended, with --play)
+    ├── speak.sh          # TTS via curl (all providers: ElevenLabs / OpenAI / Qwen3)
+    └── compose.sh        # Music composition (Suno)
+```
+
+Running `--preset ai-girlfriend` additionally includes:
+
+```
+├── scripts/
+│   ├── generate-image.sh # Selfie generation (fal.ai Grok Imagine)
+│   ├── speak.js          # TTS via ElevenLabs JS SDK
+│   ├── speak.sh          # TTS via curl (all providers)
+│   └── compose.sh        # Music composition
+└── assets/               # Reference images (placeholder if empty)
+```
+
+### What Each File Does
+
+- **SKILL.md** — The agent reads this to know how to behave. Contains persona identity, behavior guidelines, and complete faculty instructions
+- **soul-injection.md** — Appended to `~/.openclaw/workspace/SOUL.md`. Narrative description of _who_ the persona is — written in story form, not bullet points
+- **identity-block.md** — Written to `~/.openclaw/workspace/IDENTITY.md`. Sets the agent's name, creature type, emoji, and vibe
+- **soul-state.json** — Tracks dynamic persona evolution: relationship stage (stranger → intimate), mood, evolved traits, interests, milestones
+
+## How It Differs from Clawra
+
+[Clawra](https://github.com/SumeLabs/clawra) is a single-purpose product (one girlfriend persona). OpenPersona is a **modular framework**:
+
+| | Clawra | OpenPersona |
+|---|--------|-------------|
+| Scope | Single persona (Clawra) | Framework for any persona |
+| Architecture | Monolithic | Four-layer (Soul/Body/Faculty/Skill) |
+| Faculties | Selfie only | Selfie + Voice + Music + Reminder + Soul Evolution ★Exp |
+| Voice | None | ElevenLabs / OpenAI TTS / Qwen3-TTS |
+| Music | None | Suno AI composition |
+| Persona evolution | None | Dynamic relationship/mood/trait tracking |
+| Customization | Fork and modify | `persona.json` + `behaviorGuide` + mix faculties |
+| Presets | 1 | 4 (extensible) |
+| CLI | Install only | 8 commands (create/install/search/publish/...) |
+| AI entry point | None | `skill/SKILL.md` — agent creates personas via conversation |
+
+## Faculty Reference
+
+| Faculty | Dimension | Description | Provider | Env Vars |
+|---------|-----------|-------------|----------|----------|
+| **selfie** | expression | AI selfie generation with mirror/direct modes | fal.ai Grok Imagine | `FAL_KEY` |
+| **voice** | expression | Text-to-speech voice synthesis | ElevenLabs / OpenAI TTS / Qwen3-TTS | `ELEVENLABS_API_KEY` (or `TTS_API_KEY`), `TTS_PROVIDER`, `TTS_VOICE_ID`, `TTS_STABILITY`, `TTS_SIMILARITY` |
+| **music** | expression | AI music composition (instrumental or with lyrics) | Suno | `SUNO_API_KEY` |
+| **reminder** | cognition | Schedule reminders and task management | Built-in | — |
+| **soul-evolution** | cognition ★Exp | Dynamic persona growth across conversations | Built-in | — |
+
+### Rich Faculty Config
+
+Faculties in `manifest.json` use object format with optional per-persona tuning:
+
+```json
+"faculties": [
+  {
+    "name": "voice",
+    "provider": "elevenlabs",
+    "voiceId": "LEnmbrrxYsUYS7vsRRwD",
+    "stability": 0.4,
+    "similarity_boost": 0.8
+  },
+  { "name": "music" },
+  { "name": "soul-evolution" }
+]
+```
+
+Faculty configs are automatically mapped to environment variables at install time. For example, the voice config above produces:
+
+```
+TTS_PROVIDER=elevenlabs
+TTS_VOICE_ID=LEnmbrrxYsUYS7vsRRwD
+TTS_STABILITY=0.4
+TTS_SIMILARITY=0.8
+```
+
+Samantha ships with a built-in ElevenLabs voice — users only need to add their `ELEVENLABS_API_KEY`.
+
+## Persona Harvest — Community Contribution
+
+Every user's interaction with their persona can produce valuable improvements across all four layers. Persona Harvest lets you contribute these discoveries back to the community.
+
+```bash
+# Preview what's changed (no PR created)
+npx openpersona contribute samantha --dry-run
+
+# Submit improvements as a PR
+npx openpersona contribute samantha
+
+# Framework-level contributions (templates, faculties, lib)
+npx openpersona contribute --mode framework
+```
+
+**How it works:**
+
+1. **Persona Diff** — Compares your local `persona-samantha/` against the upstream `presets/samantha/`, classifying changes by category (background, behaviorGuide, personality, voice config) and impact level
+2. **Review** — Displays a structured change report for you to confirm
+3. **Submit** — Forks the repo, creates a `persona-harvest/samantha-*` branch, commits your improvements, and opens a PR
+
+PRs go through maintainer review — nothing auto-merges. Requires [GitHub CLI](https://cli.github.com/) (`gh auth login`).
+
+**Contributable dimensions:**
+
+| Layer | What | Example |
+|-------|------|---------|
+| Soul | background, behaviorGuide, personality, speakingStyle | "Added late-night conversation style guidance" |
+| Faculty Config | voice stability, similarity, new faculties | "Tuned voice to be warmer at stability 0.3" |
+| Framework | templates, generator logic, faculty scripts | "Improved speak.js streaming performance" |
+
+## Custom Persona Creation
+
+### Using `persona.json`
+
+Create a `persona.json` with your persona definition:
+
+```json
+{
+  "personaName": "Coach",
+  "slug": "fitness-coach",
+  "bio": "a motivating fitness coach who helps you reach your goals",
+  "personality": "energetic, encouraging, no-nonsense",
+  "speakingStyle": "Uses fitness lingo, celebrates wins, keeps it brief",
+  "vibe": "intense but supportive",
+  "boundaries": "Not a medical professional",
+  "capabilities": ["Workout plans", "Form checks", "Nutrition tips"],
+  "behaviorGuide": "### Workout Plans\nCreate progressive overload programs...\n\n### Form Checks\nWhen users describe exercises..."
+}
+```
+
+Then generate:
+
+```bash
+npx openpersona create --config ./persona.json --install
+```
+
+### The `behaviorGuide` Field
+
+The optional `behaviorGuide` field lets you define domain-specific behavior instructions in markdown. This content is included directly in the generated SKILL.md, giving the agent concrete instructions on _how_ to perform each capability.
+
+Without `behaviorGuide`, the SKILL.md only contains general identity and personality guidelines. With it, the agent gets actionable, domain-specific instructions.
+
+## CLI Commands
+
+```
+openpersona create      Create a persona (interactive or --preset/--config)
+openpersona install     Install a persona (slug or owner/repo)
+openpersona search      Search the registry
+openpersona uninstall   Uninstall a persona
+openpersona update      Update installed personas
+openpersona list        List installed personas
+openpersona contribute  Persona Harvest — submit improvements as PR
+openpersona publish     Publish to ClawHub
+openpersona reset       ★Exp Reset soul-state.json
+```
+
+### Key Options
+
+```bash
+# Use a preset
+npx openpersona create --preset samantha
+
+# Use an external config file
+npx openpersona create --config ./my-persona.json
+
+# Preview without writing files
+npx openpersona create --preset samantha --dry-run
+
+# Generate and install in one step
+npx openpersona create --config ./persona.json --install
+
+# Specify output directory
+npx openpersona create --preset ai-girlfriend --output ./my-personas
+```
+
+## Install as OpenClaw Skill
+
+Install the OpenPersona framework skill into OpenClaw, giving the agent the ability to create and manage personas through conversation:
+
+```bash
+# From GitHub
+git clone https://github.com/ACNet-AI/OpenPersona.git ~/.openclaw/skills/open-persona
+
+# Or copy locally
+cp -r skill/ ~/.openclaw/skills/open-persona/
+```
+
+Then say to your agent: _"Help me create a Samantha persona"_ — the agent will use OpenPersona to gather requirements, recommend faculties, and generate the persona.
+
+## Directory Structure
+
+```
+skill/                  # Framework meta-skill (AI entry point)
+presets/                # Assembled products — complete persona bundles
+  samantha/             #   Samantha (movie "Her") — voice + music + evolution
+  ai-girlfriend/        #   Luna — selfie + voice + music + evolution
+  life-assistant/       #   Alex — reminder
+  health-butler/        #   Vita — reminder
+layers/                 # Shared building blocks (four-layer module pool)
+  soul/                 #   Soul layer modules (MVP placeholder)
+  embodiments/          #   Body layer modules (MVP placeholder)
+  faculties/            #   Faculty layer modules
+    selfie/             #     expression — AI selfie generation (fal.ai)
+    voice/              #     expression — TTS voice synthesis
+    music/              #     expression — AI music composition (Suno)
+    reminder/           #     cognition — reminders and task management
+    soul-evolution/     #     cognition ★Exp — dynamic persona evolution
+  skills/               #   Skill layer modules (MVP placeholder)
+schemas/                # Four-layer schema definitions
+templates/              # Mustache rendering templates
+bin/                    # CLI entry point
+lib/                    # Core logic modules
+tests/                  # Tests (20 passing)
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Dry-run generate a preset
+node bin/cli.js create --preset samantha --dry-run
+```
+
+### Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+/**
+ * OpenPersona CLI - Full persona package manager
+ * Commands: create | install | search | uninstall | update | list | publish | reset | contribute
+ */
+const path = require('path');
+const fs = require('fs-extra');
+const { program } = require('commander');
+const inquirer = require('inquirer');
+const chalk = require('chalk');
+const { generate } = require('../lib/generator');
+const { install } = require('../lib/installer');
+const { download } = require('../lib/downloader');
+const { search } = require('../lib/searcher');
+const { uninstall } = require('../lib/uninstaller');
+const publishAdapter = require('../lib/publisher');
+const { contribute } = require('../lib/contributor');
+const { OP_SKILLS_DIR, printError, printSuccess, printInfo } = require('../lib/utils');
+
+const PKG_ROOT = path.resolve(__dirname, '..');
+const PRESETS_DIR = path.join(PKG_ROOT, 'presets');
+
+program
+  .name('openpersona')
+  .description('OpenPersona - Create, manage, and orchestrate AI personas')
+  .version('0.1.0');
+
+if (process.argv.length === 2) {
+  process.argv.push('create');
+}
+
+program
+  .command('create')
+  .description('Create a new persona skill pack (interactive wizard)')
+  .option('--preset <name>', 'Use preset (ai-girlfriend, samantha, life-assistant, health-butler)')
+  .option('--config <path>', 'Load external persona.json')
+  .option('--output <dir>', 'Output directory', process.cwd())
+  .option('--install', 'Install to OpenClaw after generation')
+  .option('--dry-run', 'Preview only, do not write files')
+  .action(async (options) => {
+    let persona = {};
+    if (options.preset) {
+      const presetDir = path.join(PRESETS_DIR, options.preset);
+      const manifestPath = path.join(presetDir, 'manifest.json');
+      const presetPath = path.join(presetDir, 'persona.json');
+      if (!fs.existsSync(manifestPath) || !fs.existsSync(presetPath)) {
+        printError(`Preset not found: ${options.preset}`);
+        process.exit(1);
+      }
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+      persona = JSON.parse(fs.readFileSync(presetPath, 'utf-8'));
+      // Merge cross-layer fields from manifest into persona for generator
+      persona.faculties = manifest.layers.faculties || [];
+      persona.skills = manifest.layers.skills || {};
+      persona.embodiments = manifest.layers.body ? [manifest.layers.body] : [];
+      persona.allowedTools = manifest.allowedTools || [];
+      persona.version = manifest.version;
+      persona.author = manifest.author;
+      persona.meta = manifest.meta;
+    } else if (options.config) {
+      const configPath = path.resolve(options.config);
+      if (!fs.existsSync(configPath)) {
+        printError(`Config not found: ${configPath}`);
+        process.exit(1);
+      }
+      persona = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    } else {
+      const answers = await inquirer.prompt([
+        { type: 'input', name: 'personaName', message: 'Persona name:', default: 'Luna' },
+        { type: 'input', name: 'slug', message: 'Slug (for directory):', default: (a) => require('../lib/utils').slugify(a.personaName) },
+        { type: 'input', name: 'bio', message: 'One-line bio:', default: 'a warm and caring AI companion' },
+        { type: 'input', name: 'background', message: 'Background:', default: 'A creative soul who loves music and art' },
+        { type: 'input', name: 'age', message: 'Age:', default: '22' },
+        { type: 'input', name: 'personality', message: 'Personality keywords:', default: 'gentle, cute, caring' },
+        { type: 'input', name: 'speakingStyle', message: 'Speaking style:', default: 'Uses emoji, warm tone' },
+        { type: 'input', name: 'referenceImage', message: 'Reference image URL:', default: '' },
+        { type: 'checkbox', name: 'faculties', message: 'Select faculties:', choices: ['selfie', 'voice', 'music', 'reminder', 'soul-evolution'] },
+        { type: 'confirm', name: 'evolutionEnabled', message: 'Enable soul evolution (★Experimental)?', default: false },
+      ]);
+      persona = { ...answers, evolution: { enabled: answers.evolutionEnabled } };
+      persona.faculties = (answers.faculties || []).map((name) => ({ name }));
+    }
+
+    try {
+      const outputDir = path.resolve(options.output);
+      if (options.dryRun) {
+        printInfo('Dry run — preview only, no files written.');
+        printInfo(`Would generate: persona-${persona.slug || require('../lib/utils').slugify(persona.personaName)}/`);
+        printInfo(`  SKILL.md, soul-injection.md, identity-block.md, README.md, persona.json`);
+        if (persona.evolution?.enabled) {
+          printInfo(`  soul-state.json (★Experimental)`);
+        }
+        const faculties = persona.faculties || [];
+        if (faculties.length) {
+          printInfo(`  Faculties: ${faculties.join(', ')}`);
+        }
+        return;
+      }
+      const { skillDir } = await generate(persona, outputDir);
+      printSuccess('Generated: ' + skillDir);
+      if (options.install) {
+        await install(skillDir);
+      } else {
+        printInfo('Run: npx openpersona create --config ./persona.json --output . --install');
+      }
+    } catch (e) {
+      printError(e.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('install <target>')
+  .description('Install persona (slug or owner/repo)')
+  .option('--registry <name>', 'Registry (clawhub, skillssh)', 'clawhub')
+  .action(async (target, options) => {
+    try {
+      const result = await download(target, options.registry);
+      if (result.skipCopy) {
+        await install(result.dir, { skipCopy: true });
+      } else {
+        await install(result.dir);
+      }
+    } catch (e) {
+      printError(e.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('search <query>')
+  .description('Search personas in registry')
+  .option('--registry <name>', 'Registry', 'clawhub')
+  .action(async (query, options) => {
+    try {
+      await search(query, options.registry);
+    } catch (e) {
+      printError(e.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('uninstall <slug>')
+  .description('Uninstall persona')
+  .action(async (slug) => {
+    try {
+      await uninstall(slug);
+    } catch (e) {
+      printError(e.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('update <slug>')
+  .description('Update installed persona')
+  .action(async (slug) => {
+    const skillDir = path.join(OP_SKILLS_DIR, `persona-${slug}`);
+    if (!fs.existsSync(skillDir)) {
+      printError(`Persona not found: persona-${slug}`);
+      process.exit(1);
+    }
+    const personaPath = path.join(skillDir, 'persona.json');
+    if (!fs.existsSync(personaPath)) {
+      printError('persona.json not found');
+      process.exit(1);
+    }
+    const persona = JSON.parse(fs.readFileSync(personaPath, 'utf-8'));
+    const tmpDir = path.join(require('os').tmpdir(), 'openpersona-update-' + Date.now());
+    await fs.ensureDir(tmpDir);
+    const { skillDir: newDir } = await generate(persona, tmpDir);
+    await fs.remove(skillDir);
+    await fs.move(newDir, skillDir);
+    await fs.remove(tmpDir);
+    await install(skillDir, { skipCopy: true });
+    printSuccess('Updated persona-' + slug);
+  });
+
+program
+  .command('list')
+  .description('List installed personas')
+  .action(async () => {
+    if (!fs.existsSync(OP_SKILLS_DIR)) {
+      printInfo('No personas installed.');
+      return;
+    }
+    const dirs = fs.readdirSync(OP_SKILLS_DIR);
+    const personas = dirs
+      .filter((d) => d.startsWith('persona-') && fs.existsSync(path.join(OP_SKILLS_DIR, d, 'persona.json')))
+      .map((d) => {
+        const p = JSON.parse(fs.readFileSync(path.join(OP_SKILLS_DIR, d, 'persona.json'), 'utf-8'));
+        return { slug: p.slug, name: p.personaName };
+      });
+    personas.forEach((p) => console.log(`  ${p.name} (persona-${p.slug})`));
+  });
+
+program
+  .command('publish')
+  .description('Publish persona to registry')
+  .option('--target <registry>', 'Target registry', 'clawhub')
+  .option('--path <dir>', 'Persona directory', process.cwd())
+  .action(async (options) => {
+    try {
+      const dir = path.resolve(options.path);
+      await publishAdapter.publish(dir, options.target);
+    } catch (e) {
+      printError(e.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('reset <slug>')
+  .description('★Experimental: Reset soul evolution state')
+  .action(async (slug) => {
+    const skillDir = path.join(OP_SKILLS_DIR, `persona-${slug}`);
+    const personaPath = path.join(skillDir, 'persona.json');
+    const soulStatePath = path.join(skillDir, 'soul-state.json');
+    if (!fs.existsSync(personaPath) || !fs.existsSync(soulStatePath)) {
+      printError('Persona or soul-state.json not found');
+      process.exit(1);
+    }
+    const persona = JSON.parse(fs.readFileSync(personaPath, 'utf-8'));
+    const templatePath = path.join(PKG_ROOT, 'layers', 'faculties', 'soul-evolution', 'soul-state.template.json');
+    const tpl = fs.readFileSync(templatePath, 'utf-8');
+    const Mustache = require('mustache');
+    const now = new Date().toISOString();
+    const moodBaseline = persona.personality?.split(',')[0]?.trim() || 'neutral';
+    const soulState = Mustache.render(tpl, { slug, createdAt: now, lastUpdatedAt: now, moodBaseline });
+    fs.writeFileSync(soulStatePath, soulState);
+    printSuccess('Reset soul-state.json');
+  });
+
+program
+  .command('contribute [slug]')
+  .description('Persona Harvest — submit persona improvements as a PR to the community')
+  .option('--mode <mode>', 'Contribution scope: preset or framework', 'preset')
+  .option('--dry-run', 'Show diff only, do not create PR')
+  .action(async (slug, options) => {
+    try {
+      if (options.mode === 'preset' && !slug) {
+        printError('Slug required for preset contributions. Example: npx openpersona contribute samantha');
+        process.exit(1);
+      }
+      await contribute(slug, { mode: options.mode, dryRun: options.dryRun });
+    } catch (e) {
+      printError(e.message);
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/layers/embodiments/README.md

@@ -0,0 +1,30 @@
+# Body Layer — Physical Embodiment
+
+The Body layer defines how an agent exists in the **physical world**: robots, IoT devices, hardware sensors/actuators.
+
+**Pure digital agents have no Body** — chatbot does not need physical embodiment.
+
+## embodiment.json Standard (MVP — Reserved)
+
+See `schemas/body/embodiment.schema.json` for the schema.
+
+```json
+{
+  "name": "robot-arm",
+  "hardwareRef": { "platform": "ros2", "package": "moveit2" },
+  "description": "6-DOF robotic arm control via ROS2 MoveIt",
+  "capabilities": ["pick", "place", "gesture"],
+  "hardwareRequirements": { "interface": "USB/Serial", "driver": "ros2-serial-bridge" }
+}
+```
+
+## Roadmap
+
+- `robot-arm` (Future) — robotic arm control
+- `smart-speaker` (Future) — smart speaker hardware interface
+- `humanoid` (Future) — full-body humanoid robot control
+- `iot-hub` (Future) — IoT device gateway
+
+## Contributing
+
+To add a new embodiment: create `embodiments/<name>/embodiment.json` following the schema.