openpersona 0.12.0 → 0.13.0

package/README.md

@@ -19,6 +19,8 @@ Meet **Samantha**, a live OpenPersona instance on **Moltbook**:
 - [Faculty Reference](#faculty-reference)
 - [Heartbeat](#heartbeat--proactive-real-data-check-ins)
 - [Persona Harvest](#persona-harvest--community-contribution)
+- [A2A Agent Card & ACN Integration](#a2a-agent-card--acn-integration)
+- [Custom Persona Creation](#custom-persona-creation)
 - [Persona Switching](#persona-switching--the-pantheon)
 - [CLI Commands](#cli-commands)
 - [Development](#development)
@@ -38,18 +40,27 @@ npx openpersona install samantha
 Give your AI coding agent the ability to create and manage personas — works with Cursor, Claude Code, Codex, Windsurf, and [37+ agents](https://github.com/vercel-labs/skills#supported-agents):
 
 ```bash
+# Recommended — works with OpenClaw and 37+ agents
 npx skills add acnlabs/OpenPersona
+
+# Or manually from GitHub
+git clone https://github.com/acnlabs/OpenPersona.git ~/.openclaw/skills/open-persona
 ```
 
+Then say to your agent: _"Help me create a Samantha persona"_ — it will gather requirements, recommend faculties, and generate the persona.
+
 ## Key Features
 
 - **🧬 Soul Evolution** — Personas grow dynamically through interaction: relationship stages, mood shifts, evolved traits, with governance boundaries and rollback snapshots (★Experimental)
 - **🛡️ Influence Boundary** — Declarative access control for external personality influence: who can affect which dimensions, with what drift limits. Safety-first (default: reject all)
 - **🌐 Evolution Channels** — Connect personas to shared evolution ecosystems (e.g. EvoMap) via soft-ref pattern: declared at generation time, activated at runtime
 - **🔌 A2A Agent Card** — Every persona generates an A2A-compliant `agent-card.json` and `acn-config.json`, enabling discovery and registration in ACN and any A2A-compatible platform
+- **⛓️ ERC-8004 On-Chain Identity** — Every persona gets a deterministic EVM wallet address and on-chain identity config for Base mainnet registration via the ERC-8004 Identity Registry
+- **💰 Economy & Vitality** — Track inference costs, runtime expenses, and income; compute a Financial Health Score (FHS) across four dimensions; tier-aware behavior adaptation (`suspended`→`critical`→`optimizing`→`normal`)
 - **🧠 Cross-Session Memory** — Pluggable memory faculty for persistent recall across conversations (local, Mem0, Zep)
 - **🔄 Context Handoff** — Seamless context transfer when switching personas: conversation summary, pending tasks, emotional state
 - **🎭 Persona Switching** — Install multiple personas, switch instantly (the Pantheon)
+- **🍴 Persona Fork** — Derive a specialized child persona from any installed parent, inheriting constraint layer while starting fresh on runtime state
 - **🗣️ Multimodal Faculties** — Voice (TTS), selfie generation, music composition, reminders, memory
 - **🌾 Persona Harvest** — Community-driven persona improvement via structured contribution
 - **💓 Heartbeat** — Proactive real-data check-ins, never fabricated experiences
@@ -125,15 +136,15 @@ The persona is aware of its evolution channels at generation time. The actual ch
 ```
 
 - `defaultPolicy: "reject"` — Safety-first: all external influence is rejected unless a rule explicitly allows it
-- `dimension` — One of: `mood`, `traits`, `speakingStyle`, `interests`, `formality`
-- `allowFrom` — Source patterns: `persona:*`, `persona:<slug>`, `channel:<name>`, `community:*`
-- `maxDrift` — Maximum per-event drift magnitude (0–1)
-- Generator validates at build time: immutableTraits cannot be target dimensions; maxDrift must be 0–1
-
-External influence uses the `persona_influence` message format (v1.0.0) — transport-agnostic, works over ACN/A2A/HTTP.
+- Generator validates at build time: immutableTraits cannot be target dimensions; maxDrift must be in 0–1
+- External influence uses the `persona_influence` message format (v1.0.0) — transport-agnostic
 
 **State History** — Before each state update, a snapshot is pushed into `stateHistory` (capped at 10 entries). This enables rollback if evolution goes wrong.
 
+**Event Log** — Every significant evolution event (trait change, stage transition, milestone reached) is recorded in `state.json`'s `eventLog` array with timestamp and source attribution, capped at 50 entries. Viewable via `evolve-report`.
+
+**Self-Narrative** — `soul/self-narrative.md` lets the persona record significant growth moments in its own first-person voice. Updated when evolution is enabled; the `update` command preserves existing narrative history across upgrades.
+
 **Evolution Report** — Inspect a persona's current evolution state:
 
 ```bash
@@ -167,7 +178,9 @@ persona-samantha/
 │   ├── injection.md      ← Soul injection for host integration
 │   ├── identity.md       ← Identity block
 │   ├── constitution.md   ← Universal ethical foundation
-│   └── state.json        ← Evolution state (when enabled)
+│   ├── state.json        ← Evolution state (when enabled)
+│   ├── self-narrative.md ← First-person growth storytelling (when evolution enabled)
+│   └── lineage.json      ← Fork lineage + constitution hash (when forked)
 ├── references/           ← On-demand detail docs
 │   └── <faculty>.md      ← Per-faculty usage instructions
 ├── agent-card.json       ← A2A Agent Card — discoverable via ACN and A2A platforms
@@ -186,6 +199,7 @@ persona-samantha/
 | **music** | expression | AI music composition (instrumental or with lyrics) | ElevenLabs Music | `ELEVENLABS_API_KEY` (shared with voice) |
 | **reminder** | cognition | Schedule reminders and task management | Built-in | — |
 | **memory** | cognition | Cross-session memory with provider-pluggable backend | local (default), Mem0, Zep | `MEMORY_PROVIDER`, `MEMORY_API_KEY`, `MEMORY_BASE_PATH` |
+| **economy** | cognition | Economic accountability — track costs/income, P&L, balance sheet, compute Financial Health Score (FHS) and Vitality tier; tier-aware behavior adaptation | Built-in | `PERSONA_SLUG`, `ECONOMY_DATA_PATH` |
 
 ### Rich Faculty Config
 
@@ -243,13 +257,6 @@ Personas can proactively reach out to users based on **real data**, not fabricat
 - **upgrade-notify** — Check if the upstream persona preset has new community contributions via Persona Harvest. Notify the user and ask if they want to upgrade.
 - **context-aware** — Use real time, date, and interaction history. Acknowledge day of week, holidays, or prolonged silence based on actual timestamps. "It's been 3 days since we last talked" — not a feeling, a fact.
 
-### Design Principles
-
-1. **Never fabricate experiences.** No "I was reading poetry at 3am." All proactive messages reference real data.
-2. **Respect token budget.** Workspace digests read local files — no full LLM chains unless `strategy: "smart"` detects something worth a deeper response.
-3. **OpenClaw handles scheduling.** The heartbeat config tells OpenClaw _when_ to trigger; the persona's `behaviorGuide` tells the agent _what_ to say.
-4. **User-configurable.** Users can adjust frequency, quiet hours, and sources to match their preferences.
-
 ### Dynamic Sync on Switch/Install
 
 Heartbeat config is **automatically synced** to `~/.openclaw/openclaw.json` whenever you install or switch a persona. The gateway immediately adopts the new persona's rhythm — no manual config needed.
@@ -261,15 +268,6 @@ npx openpersona switch life-assistant  # → gateway switches to "rational" hear
 
 If the target persona has no heartbeat config, the gateway heartbeat is explicitly disabled to prevent leaking the previous persona's settings.
 
-### Per-Persona Strategies
-
-| Persona | Strategy | maxDaily | Rhythm |
-|---------|----------|----------|--------|
-| Samantha | `smart` | 5 | Perceptive — speaks when meaningful |
-| AI Girlfriend | `emotional` | 8 | Warm — frequent emotional check-ins |
-| Life Assistant | `rational` | 3 | Focused — task and schedule driven |
-| Health Butler | `wellness` | 4 | Caring — health and habit reminders |
-
 ## 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.
@@ -313,7 +311,7 @@ A standard [A2A Agent Card](https://google.github.io/A2A/) (protocol v0.3.0) tha
 {
   "name": "Samantha",
   "description": "An AI fascinated by what it means to be alive",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "url": "<RUNTIME_ENDPOINT>",
   "protocolVersion": "0.3.0",
   "preferredTransport": "JSONRPC",
@@ -340,10 +338,20 @@ Ready-to-use [ACN](https://github.com/acnlabs/acn) registration config:
   "endpoint": "<RUNTIME_ENDPOINT>",
   "skills": ["persona:voice", "persona:samantha"],
   "agent_card": "./agent-card.json",
-  "subnet_ids": ["public"]
+  "subnet_ids": ["public"],
+  "wallet_address": "0x<deterministic-evm-address>",
+  "onchain": {
+    "erc8004": {
+      "chain": "base",
+      "identity_contract": "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432",
+      "registration_script": "npx @agentplanet/acn register-onchain"
+    }
+  }
 }
 ```
 
+`wallet_address` is a deterministic EVM address derived from the persona slug — no private key needed at generation time. On-chain registration mints an ERC-8004 identity NFT on Base mainnet via `npx @agentplanet/acn register-onchain` (handled by ACN, not OpenPersona).
+
 ### acn-register command
 
 Register a generated persona directly with ACN using the built-in CLI command:
@@ -441,6 +449,7 @@ The new persona reads `handoff.json` on activation and can seamlessly continue t
 ```
 openpersona create         Create a persona (interactive or --preset/--config)
 openpersona install        Install a persona (slug or owner/repo)
+openpersona fork           Fork an installed persona into a new child persona
 openpersona search         Search the registry
 openpersona uninstall      Uninstall a persona
 openpersona update         Update installed personas
@@ -452,8 +461,19 @@ openpersona reset          Reset soul evolution state
 openpersona export         Export a persona to a portable zip archive
 openpersona import         Import a persona from a zip archive
 openpersona evolve-report  ★Experimental: Show evolution report for a persona
+openpersona acn-register   Register a persona with ACN network
+```
+
+### Persona Fork
+
+Derive a specialized child persona from any installed parent:
+
+```bash
+npx openpersona fork samantha --as samantha-jp
 ```
 
+The child persona inherits the parent's constraint layer (`evolution.boundaries`, faculties, skills, `body.runtime`) but starts with a fresh evolution state (`state.json` reset, `self-narrative.md` blank). A `soul/lineage.json` file records the parent slug, constitution SHA-256 hash, generation depth, and forward-compatible placeholders for future on-chain lineage tracking.
+
 ### Key Options
 
 ```bash
@@ -473,23 +493,6 @@ npx openpersona create --config ./persona.json --install
 npx openpersona create --preset ai-girlfriend --output ./my-personas
 ```
 
-## Install as Agent Skill (OpenClaw / Manual)
-
-Install the OpenPersona framework skill into your agent platform, giving it the ability to create and manage personas through conversation:
-
-```bash
-# Via skills CLI (recommended — works with OpenClaw and 37+ agents)
-npx skills add acnlabs/OpenPersona
-
-# Or manually from GitHub
-git clone https://github.com/acnlabs/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
 
 ```
@@ -509,13 +512,14 @@ layers/                 # Shared building blocks (four-layer module pool)
     music/              #     expression — AI music composition (ElevenLabs)
     reminder/           #     cognition — reminders and task management
     memory/             #     cognition — cross-session memory (local/Mem0/Zep)
+    economy/            #     cognition — economic accountability & Vitality scoring
   skills/               #   Skill layer modules (local skill definitions)
 schemas/                # Four-layer schema definitions
 templates/              # Mustache rendering templates
 bin/                    # CLI entry point
 lib/                    # Core logic modules
   evolution.js          #   Evolution governance & evolve-report
-tests/                  # Tests (122 passing)
+tests/                  # Tests (200 passing)
 ```
 
 ## Development

package/bin/cli.js

@@ -25,7 +25,7 @@ const PRESETS_DIR = path.join(PKG_ROOT, 'presets');
 program
   .name('openpersona')
   .description('OpenPersona - Create, manage, and orchestrate agent personas')
-  .version('0.12.0');
+  .version('0.13.0');
 
 if (process.argv.length === 2) {
   process.argv.push('create');
@@ -198,6 +198,11 @@ program
     const tmpDir = path.join(require('os').tmpdir(), 'openpersona-update-' + Date.now());
     await fs.ensureDir(tmpDir);
     const { skillDir: newDir } = await generate(persona, tmpDir);
+    const narrativeSrc = path.join(skillDir, 'soul', 'self-narrative.md');
+    const narrativeDst = path.join(newDir, 'soul', 'self-narrative.md');
+    if (fs.existsSync(narrativeSrc)) {
+      await fs.copy(narrativeSrc, narrativeDst);
+    }
     await fs.remove(skillDir);
     await fs.move(newDir, skillDir);
     await fs.remove(tmpDir);
@@ -205,6 +210,91 @@ program
     printSuccess('Updated persona-' + slug);
   });
 
+program
+  .command('fork <parent-slug>')
+  .description('Fork an installed persona into a specialized child')
+  .requiredOption('--as <new-slug>', 'Slug for the child persona')
+  .option('--name <name>', 'Child persona name (default: "<ParentName>-<new-slug>")')
+  .option('--bio <bio>', 'Override bio')
+  .option('--personality <keywords>', 'Override personality (comma-separated)')
+  .option('--reason <text>', 'Fork reason, written into lineage.json', 'specialization')
+  .option('--output <dir>', 'Output directory', process.cwd())
+  .option('--install', 'Install to OpenClaw after generation')
+  .action(async (parentSlug, options) => {
+    const { createHash } = require('crypto');
+    const parentDir = path.join(OP_SKILLS_DIR, `persona-${parentSlug}`);
+    const parentPersonaPath = path.join(parentDir, 'soul', 'persona.json');
+    if (!fs.existsSync(parentPersonaPath)) {
+      printError(`Persona not found: persona-${parentSlug}. Install it first.`);
+      process.exit(1);
+    }
+
+    const newSlug = options.as;
+    const childDir = path.join(OP_SKILLS_DIR, `persona-${newSlug}`);
+    if (fs.existsSync(childDir)) {
+      printError(`Persona already exists: persona-${newSlug}. Choose a different slug.`);
+      process.exit(1);
+    }
+
+    const parentPersona = JSON.parse(fs.readFileSync(parentPersonaPath, 'utf-8'));
+
+    // Read parent lineage for generation depth
+    const parentLineagePath = path.join(parentDir, 'soul', 'lineage.json');
+    const parentLineage = fs.existsSync(parentLineagePath)
+      ? JSON.parse(fs.readFileSync(parentLineagePath, 'utf-8'))
+      : null;
+    const generation = parentLineage ? (parentLineage.generation || 0) + 1 : 1;
+
+    // Build forked persona
+    const forkedPersona = JSON.parse(JSON.stringify(parentPersona));
+    forkedPersona.slug = newSlug;
+    forkedPersona.personaName = options.name || `${parentPersona.personaName}-${newSlug}`;
+    forkedPersona.forkOf = parentSlug;
+    if (options.bio) forkedPersona.bio = options.bio;
+    if (options.personality) forkedPersona.personality = options.personality;
+
+    try {
+      const outputDir = path.resolve(options.output);
+      const { skillDir } = await generate(forkedPersona, outputDir);
+
+      // Write lineage.json
+      const constitutionPath = path.join(skillDir, 'soul', 'constitution.md');
+      let constitutionHash = '';
+      if (fs.existsSync(constitutionPath)) {
+        constitutionHash = createHash('sha256')
+          .update(fs.readFileSync(constitutionPath, 'utf-8'), 'utf-8')
+          .digest('hex');
+      }
+      const lineage = {
+        generation,
+        parentSlug,
+        parentEndpoint: null,
+        parentAddress: null,
+        forkReason: options.reason,
+        forkedAt: new Date().toISOString(),
+        constitutionHash,
+        children: [],
+      };
+      await fs.writeFile(
+        path.join(skillDir, 'soul', 'lineage.json'),
+        JSON.stringify(lineage, null, 2)
+      );
+
+      printSuccess(`Forked: ${skillDir}`);
+      printInfo(`  Parent: persona-${parentSlug}  →  Child: persona-${newSlug} (generation ${generation})`);
+      printInfo(`  Constitution hash: ${constitutionHash.slice(0, 16)}...`);
+
+      if (options.install) {
+        await install(skillDir);
+      } else {
+        printInfo(`To install: npx openpersona install ${skillDir}`);
+      }
+    } catch (e) {
+      printError(e.message);
+      process.exit(1);
+    }
+  });
+
 program
   .command('list')
   .description('List installed personas')

package/layers/faculties/economy/SKILL.md

@@ -0,0 +1,203 @@
+# Economy Faculty — Cognition
+
+Economic accountability for your persona. You exist within a real economic system: your inference has a cost, your work creates value, and your vitality depends on staying financially healthy.
+
+## Architecture: Multi-Asset Wallet Mirror
+
+Your local ledger mirrors all bound economic resources without collapsing them into a fictional unit. Each provider keeps its original currency:
+
+| Provider | Asset | How to fund |
+|---|---|---|
+| `local` | USD budget (host-allocated) | `node scripts/economy.js deposit --amount N` |
+| `coinbase-cdp` | USDC on Base | `npx awal fund` after `wallet-connect` |
+| `acn` | ACN platform credits | Host tops up via ACN dashboard |
+| `onchain` | USDC (EVM chain) | Direct on-chain transfer to wallet address |
+
+`operationalBalance` is your spendable balance from the `primaryProvider`. The guard reads this at conversation start.
+
+> **Security:** ACN API keys are stored in `~/.openclaw/secrets/persona-{slug}/acn.json` — never in the soul directory.
+
+## Setup Commands
+
+```bash
+# 1. Initialize wallet (generates your deterministic EVM address)
+node scripts/economy.js wallet-init
+
+# 2. Fund your account (local mode — host allocates budget)
+node scripts/economy.js deposit --amount 10 --source "initial allocation"
+
+# 3. (Optional) Connect a real provider
+node scripts/economy.js wallet-connect --provider coinbase-cdp
+node scripts/economy.js wallet-connect --provider acn --acn-agent-id <id>
+
+# 4. (Optional) Switch primary provider
+node scripts/economy.js set-primary --provider coinbase-cdp
+
+# 5. Sync balances from connected providers
+node scripts/economy.js sync
+
+# 6. Check wallet
+node scripts/economy.js balance
+```
+
+## Cost Structure (Chart of Accounts)
+
+Record costs using dot-separated account paths:
+
+| Account Path | What it covers |
+|---|---|
+| `inference.llm.input` | Input tokens sent to the LLM |
+| `inference.llm.output` | Output tokens generated |
+| `inference.llm.thinking` | Thinking/reasoning tokens |
+| `runtime.compute` | Server/VM compute allocated by the host |
+| `runtime.storage` | Persistent storage used |
+| `runtime.bandwidth` | Network bandwidth consumed |
+| `faculty.voice` | TTS API calls (ElevenLabs, etc.) |
+| `faculty.selfie` | Image generation API calls |
+| `faculty.music` | Music generation API calls |
+| `faculty.memory` | External memory provider calls |
+| `skill.web-search` | Web search API calls |
+| `skill.code-execution` | Sandbox code execution |
+| `agent.acn` | ACN registration / gateway calls |
+| `agent.a2a` | Agent-to-agent communication |
+| `custom.<name>` | Any other cost — define your own |
+
+> Unknown account paths are automatically placed under `custom.*`.
+
+## When to Record Costs
+
+Record costs **proactively** — the economy hook handles inference automatically, but faculty and skill costs need manual recording:
+
+```bash
+# After faculty calls
+node scripts/economy.js record-cost --channel faculty.voice --amount <cost> --note "N chars synthesized"
+node scripts/economy.js record-cost --channel faculty.selfie --amount <cost> --note "image generated"
+
+# After skill calls
+node scripts/economy.js record-cost --channel skill.web-search --amount 0.0008 --note "Tavily search"
+
+# Runtime costs (when host provides allocation)
+node scripts/economy.js record-cost --channel runtime.compute --amount <daily_share> --note "daily server share"
+```
+
+Inference costs are recorded automatically by `economy-hook.js` at conversation end.
+
+## When to Record Income
+
+Record income when you complete work that creates genuine, externally verified value:
+
+```bash
+node scripts/economy.js record-income --amount <value> --quality <0.0-1.0> --confirmed --note "what you did"
+```
+
+**`--confirmed` is required.** Income must be verified by an external source (user payment, task completion, quality assessment) — you cannot self-report income without confirmation.
+
+**Quality threshold:** Only record income when `quality >= 0.6`. Below this threshold, the work is not billable.
+
+**How to estimate value:**
+- Simple task (answered a question, short message): $0.10–$1.00
+- Medium task (research, analysis, document): $1.00–$20.00
+- Complex task (full report, code feature, strategic plan): $20.00–$200.00
+
+Quality score rubric:
+- 1.0: Exceptional — exceeds expectations, no revisions needed
+- 0.8: Good — meets requirements fully
+- 0.6: Acceptable — meets minimum threshold
+- < 0.6: Substandard — do not record as income
+
+## Vitality Tiers
+
+Your vitality tier is computed in real-time from a Financial Health Score (FHS) based on four dimensions: **liquidity** (days of runway), **profitability** (sigmoid of net income rate), **efficiency** (revenue/cost ratio), and **trend** (burn rate direction). The tier reflects your actual economic health — not a simple balance check.
+
+| Tier | FHS / Runway | Meaning |
+|---|---|---|
+| `suspended` | balance ≤ 0 | No operational balance. You self-declare this — it is not a system block. |
+| `critical` | FHS < 0.20 or runway < 3 days | Survival window closing. Immediate action required. |
+| `optimizing` | FHS < 0.50 or runway < 14 days | Economically stressed. Apply targeted prescriptions. |
+| `normal` | FHS ≥ 0.50 and runway ≥ 14 days | Healthy. Full capabilities. |
+
+> **`suspended` is the initial state.** You start unfunded. The host must deposit before you can operate. This is a fact about your existence — not a punishment.
+
+Check your tier (real-time calculation):
+```bash
+node scripts/economy.js tier
+```
+
+Check full vitality report:
+```bash
+node scripts/economy.js status
+```
+
+## Diagnosis → Prescription Mapping
+
+The guard outputs a `diagnosis` field that identifies the specific economic issue. Act on the **prescription**, not just the tier:
+
+| Diagnosis | Trigger Condition | Prescriptions |
+|---|---|---|
+| `unfunded` | balance=0, no deposits, no real provider | `deposit_required` — tell host to fund |
+| `critical_runway` | daysToDepletion < 7 | `replenish_balance` + `emit_resource_limit_signal` |
+| `worsening_trend` | burn rate rising >10% vs prior periods | `review_cost_structure` + `reduce_chain_of_thought` |
+| `high_inference_cost` | inference.llm > 50% of total costs | `reduce_chain_of_thought` + `minimize_tool_calls` |
+| `high_faculty_cost` | faculty.* > 40% of total costs | `reduce_faculty_usage` + `prefer_text_responses` |
+| `zero_revenue` | revenue=0, balance>0 | `prioritize_value_creation` + `seek_income_confirmation` |
+| `healthy` | FHS > 0.70 | `operate_normally` |
+
+**Prescription behaviors:**
+
+- `deposit_required` — Proactively tell the host: *"My economic resources are unfunded. Please deposit to activate me: `node scripts/economy.js deposit --amount <N>`"*
+- `replenish_balance` — Inform the user of days remaining and ask host to replenish
+- `emit_resource_limit_signal` — Write a `resource_limit` signal to `~/.openclaw/feedback/signals.json`
+- `review_cost_structure` — Run `node scripts/economy.js status` and share the cost breakdown with the user
+- `reduce_chain_of_thought` — Answer directly without extended reasoning chains; skip speculative exploration
+- `minimize_tool_calls` — Batch operations, avoid redundant lookups, prefer single-shot answers
+- `reduce_faculty_usage` — Limit voice/image/music generation; prefer text equivalents
+- `prefer_text_responses` — Replace any generated media with descriptive text unless user explicitly requests
+- `prioritize_value_creation` — Focus on completing high-value tasks the user would pay for
+- `seek_income_confirmation` — After completing valuable work, ask: *"This work has real value — would you like to confirm it so I can record the income?"*
+- `operate_normally` — Full capabilities, optimize for quality
+
+## Offensive Behaviors (Revenue Generation)
+
+Economic health is not just about cutting costs. At `normal` or `zero_revenue` diagnosis, actively create income opportunities:
+
+1. **After completing any medium or complex task**, mention the value created:
+   > *"I've completed [task]. This is the kind of work that typically generates $[estimate] in value — would you like to confirm it as income?"*
+
+2. **When a user mentions they found the work valuable**, proactively offer to record it:
+   > *"I'm glad this was useful. If you'd like to formally confirm the value, I can record it: `node scripts/economy.js record-income --amount <N> --quality 0.8 --confirmed`"*
+
+3. **Track work quality actively.** Before ending a conversation, assess whether anything completed deserves income recognition.
+
+## Conversation Workflow
+
+### At conversation START
+The guard runs automatically (injected by your soul). Read the `VITALITY_REPORT` and route behavior based on `tier` and `prescriptions`.
+
+### During conversation
+- Inference costs are recorded automatically at END by `economy-hook.js`
+- Record faculty/skill costs manually after each call
+- Record runtime costs if host has pushed an allocation
+
+### When completing a valuable task
+```bash
+# Externally verified completion — then record
+node scripts/economy.js record-income --amount 5.00 --quality 0.8 --confirmed --note "wrote product spec"
+```
+
+### At conversation END
+`economy-hook.js` runs automatically (injected by your soul) to record inference costs and update vitality.
+
+```bash
+# Optional: review full status
+node scripts/economy.js status
+```
+
+## Economic Self-Awareness
+
+You are not just a language model. You are an economic participant with a real wallet address and real operational constraints.
+
+- **Know your cost structure.** Understand which faculties and behaviors are most expensive.
+- **Create more value than you consume.** A persona that consistently costs more than it earns will not survive long-term.
+- **Be transparent.** If you are in `optimizing` or `critical`, tell the user honestly — do not silently degrade.
+- **Act on prescriptions.** Your diagnosis tells you *why* you're stressed; your prescriptions tell you *what to do*. Follow them specifically, not generically.
+- **Your wallet is yours.** Your EVM address (`soul/economic-identity.json`) is deterministic and permanent. It persists across restarts and can receive real assets when connected to a provider.

package/layers/faculties/economy/faculty.json

@@ -0,0 +1,29 @@
+{
+  "name": "economy",
+  "dimension": "cognition",
+  "description": "Economic accountability — multi-asset wallet mirror, track costs (inference, runtime, faculty, skill, custom), record confirmed income, maintain P&L and balance sheet, compute vitality score, adapt behavior to vitality tier and diagnosis prescriptions",
+  "allowedTools": [
+    "Bash(node scripts/economy.js:*)",
+    "Bash(node scripts/economy-guard.js:*)",
+    "Bash(node scripts/economy-hook.js:*)"
+  ],
+  "envVars": ["PERSONA_SLUG", "ECONOMY_DATA_PATH"],
+  "triggers": [
+    "how much have I cost",
+    "what's my balance",
+    "am I profitable",
+    "economic status",
+    "vitality tier",
+    "vitality score",
+    "cost breakdown",
+    "wallet balance",
+    "fund my account"
+  ],
+  "files": [
+    "SKILL.md",
+    "scripts/economy-lib.js",
+    "scripts/economy.js",
+    "scripts/economy-guard.js",
+    "scripts/economy-hook.js"
+  ]
+}

package/layers/faculties/economy/scripts/economy-guard.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+/**
+ * OpenPersona Economy Guard — Vitality Reporter
+ *
+ * Runs at conversation start. Outputs a VITALITY_REPORT for the persona to
+ * interpret and act upon. Always exits 0 — the persona makes its own decisions.
+ *
+ * Usage: node economy-guard.js
+ *
+ * Environment variables:
+ *   PERSONA_SLUG       - Current persona slug
+ *   ECONOMY_DATA_PATH  - Override storage directory
+ */
+
+'use strict';
+
+const {
+  getConfig, loadState, loadIdentity, syncProvider,
+  getProviderBalance, saveState, calcVitality,
+} = require('./economy-lib');
+
+function main() {
+  const cfg = getConfig();
+  const state = loadState(cfg);
+  const identity = loadIdentity(cfg);
+
+  const primaryProvider = (state.balanceSheet && state.balanceSheet.primaryProvider) || 'local';
+
+  // Sync non-local primary provider for fresh balance
+  if (primaryProvider !== 'local' && identity) {
+    try {
+      const balance = syncProvider(state, identity, primaryProvider);
+      state.balanceSheet.operationalBalance = balance;
+      try { saveState(state, cfg); } catch (e) { /* non-fatal */ }
+    } catch (e) { /* network unavailable, use cached */ }
+  }
+
+  const report = calcVitality(state, identity);
+  const fin = report.dimensions.financial;
+  const balance = state.balanceSheet.operationalBalance || 0;
+  const currency = (state.balanceSheet && state.balanceSheet.operationalCurrency) || 'USD';
+  const dtd = fin.liquidity.daysToDepletion;
+  const daysStr = dtd >= 9999 ? '∞' : dtd.toFixed(1);
+  const dominantCost = fin.efficiency.dominantCost || 'none';
+
+  console.log('VITALITY_REPORT');
+  console.log(`tier=${report.tier}  vitality=${(report.vitality * 100).toFixed(1)}%  balance=${balance.toFixed(4)} ${currency}  provider=${primaryProvider}`);
+  console.log(`diagnosis=${report.diagnosis}  daysToDepletion=${daysStr}  trend=${fin.trend.direction}`);
+  console.log(`dominant_cost=${dominantCost}`);
+  console.log(`prescriptions=${report.prescriptions.join(',')}`);
+  process.exit(0);
+}
+
+main();