Add persona-seed skill for pluggable corpus → persona packs

skills/open-persona/SKILL.md

@@ -27,8 +27,9 @@ You are the meta-skill for creating, installing, updating, and publishing agent
 | --- | --- |
 | Framework entry point: create, install, manage, publish, run personas | **`persona-evaluator`** — quality audit (4 Layers × 5 Concepts × Constitution gate) |
 | Runner integration protocol (`openpersona state` commands) | **`anyone-skill`** — distill a real person or character into a persona pack |
-| Skill registry (`openpersona skill` commands) | **`brand-persona-skill`** — turn a commercial entity into a brand agent |
-| Evolution, economy, vitality, social, rhythm configuration | **`persona-model-trainer`** — fine-tune a local model on persona data |
+| Skill registry (`openpersona skill` commands) | **`persona-seed`** — sample an archetype from a population corpus (e.g. MatrAIx Persona 1M fixture / decoded JSON) |
+| Evolution, economy, vitality, social, rhythm configuration | **`brand-persona-skill`** — turn a commercial entity into a brand agent |
+| | **`persona-model-trainer`** — fine-tune a local model on persona data |
 
 ## What You Can Do
 
@@ -58,13 +59,15 @@ npx openpersona create
 
 When a user asks you to create a persona (e.g. "make me a coding mentor", "build a companion persona"), follow this playbook:
 
-### Step 1 — Decide: preset or custom?
+### Step 1 — Decide: preset, corpus seed, distillation, or custom?
 
 
 | User request                                                                                                 | Action                                                              |
 | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
 | Matches an existing preset (`ai-girlfriend`, `life-assistant`, `stoic-mentor`, `samantha`, `health-butler`…) | Use `--preset <name>` directly — skip to Step 4                     |
-| Specific role / domain / personality                                                                         | Gather 3 required inputs (Step 2), then write persona.json (Step 3) |
+| Wants a pack sampled from a population corpus / MatrAIx / “pick a seed profile”                              | Delegate to **`persona-seed`** (`skills/persona-seed/SKILL.md`) — then return here for install/manage |
+| Distill a specific real person or named character from evidence                                              | Delegate to **`anyone-skill`**                                      |
+| Specific role / domain / personality (author from scratch)                                                   | Gather 3 required inputs (Step 2), then write persona.json (Step 3) |
 
 
 ### Step 2 — Gather minimum required inputs (3 questions max)
@@ -548,6 +551,7 @@ If an automated scanner flags "suspicious," it is usually because **persona mana
 | --------------------------------------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
 | `[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>`) |
 | `[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       |
+| `persona-seed` (in-repo: `skills/persona-seed`) | local / `npx skills add` when published | Sample archetype seeds from pluggable corpora (first provider: MatrAIx Persona 1M) → SeedProfile → `persona.json` → create |
 | `[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 |
 | `[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). |
 | `[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 |

skills/persona-seed/README.md

@@ -0,0 +1,30 @@
+# persona-seed
+
+Population / corpus **seed providers** → OpenPersona persona packs.
+
+One orchestration skill; pluggable adapters. First provider: **MatrAIx Persona 1M** (fixture by default; optional larger JSON corpus via `MATRAIX_CORPUS_PATH`).
+
+## When to use
+
+| Goal | Skill |
+|------|--------|
+| Distill a specific person / character from evidence | `anyone-skill` |
+| Sample an archetype from a persona corpus | **`persona-seed`** |
+
+## Quick start (agent)
+
+1. Read `SKILL.md` and follow Phases 0–5.
+2. One-shot pipeline (fixture):  
+   `node scripts/run-pipeline.js --intent '{"domain":["software"],"traits":["precise"]}' --name "Nova" --slug nova-seed --out /tmp/nova-seed`
+3. Or step-by-step: `search.js` → `--to-seed` → `map-seed-to-persona.js` → `openpersona create` → `write-provenance.js`
+4. Larger corpus: decode HF → `prepare-corpus.js --validate` → `export MATRAIX_CORPUS_PATH=…`
+
+## Layout
+
+```
+SKILL.md
+schemas/           intent + SeedProfile
+references/        provider contract
+providers/         matraix-persona-1m + …
+scripts/           search, map-seed-to-persona, write-provenance
+```

skills/persona-seed/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: persona-seed
+description: "Create an OpenPersona pack from population / corpus seed providers (first: MatrAIx Persona 1M). Searches a pluggable seed index from user intent, maps a SeedProfile to persona.json, then generates via open-persona. Use when the user wants a persona from a large persona corpus, MatrAIx, or archetype sampling — not when distilling a specific real person (use anyone-skill)."
+license: MIT
+compatibility: "OpenPersona / Cursor / Claude Code / OpenClaw. Node.js >= 18. Optional: decoded MatrAIx corpus via MATRAIX_CORPUS_PATH."
+allowed-tools: Read Write Edit Bash
+metadata:
+  version: "0.1.0"
+  author: acnlabs
+---
+
+# persona-seed — Population seeds → OpenPersona packs
+
+> One orchestration skill. Many corpus providers. MatrAIx Persona 1M is the first adapter — not a special-case product path.
+
+**Dependency chain**: `persona-seed` → `skills/open-persona` → `openpersona create`  
+**Sibling**: `anyone-skill` (evidence distillation of a specific subject). Prefer anyone-skill for real people / named characters; prefer persona-seed for population sampling and archetypes from a corpus.
+
+## Trigger phrases
+
+- `/persona-seed`
+- "create a persona from MatrAIx"
+- "sample a persona from Persona 1M"
+- "pick a seed profile and generate a pack"
+- "从人口语料里生成人格包"
+
+## Architecture
+
+```
+user intent
+    → provider.search (attribute filter)
+    → agent re-rank + user pick
+    → provider.fetch + toSeed → SeedProfile
+    → fill gaps (name, role, boundaries…)
+    → map-seed-to-persona.js → persona.json
+    → openpersona create --config …
+    → write-provenance.js → soul/seed-provenance.json
+```
+
+Contract: `references/provider-contract.md`  
+Schemas: `schemas/intent.schema.json`, `schemas/seed-profile.schema.json`  
+Registry: `providers/registry.json` (hfRepo / provider id → module; `/datasets` publish ≠ seed-capable)  
+Providers: `providers/<id>/` modules, registered explicitly
+
+## Tools (scripts)
+
+Set `SEED_DIR` to this skill directory (path containing `SKILL.md`).
+
+| Task | Command |
+|------|---------|
+| List registry | `node ${SEED_DIR}/scripts/search.js --list-providers` |
+| Seed-capable HF repos | `node ${SEED_DIR}/scripts/search.js --seed-capable` |
+| List provider caps | `node ${SEED_DIR}/scripts/search.js --capabilities` |
+| Caps by HF repo | `node ${SEED_DIR}/scripts/search.js --repo MatrAIx2026/MatrAIx_Persona_1M --capabilities` |
+| Search seeds | `node ${SEED_DIR}/scripts/search.js --intent '<json>'` |
+| Fetch raw | `node ${SEED_DIR}/scripts/search.js --fetch --id <id>` |
+| To SeedProfile | `node ${SEED_DIR}/scripts/search.js --to-seed --id <id>` |
+| Map to persona.json | `node ${SEED_DIR}/scripts/map-seed-to-persona.js --seed <seed.json> --overrides '<json>' --out persona.json` |
+| Write provenance | `node ${SEED_DIR}/scripts/write-provenance.js --pack <packDir> --seed <seed.json>` |
+| Full pipeline | `node ${SEED_DIR}/scripts/run-pipeline.js --intent '<json>' --name "…" --slug … --role assistant --out <dir>` |
+| Validate corpus | `node ${SEED_DIR}/scripts/prepare-corpus.js --validate <corpus.json\|.jsonl>` |
+
+Default corpus is the offline **fixture** (5 rows) under `providers/matraix-persona-1m/fixtures/`. `capabilities()` / provenance report `corpusMode: "fixture"` and a fixture dataset id — not the Hugging Face 1M release.
+
+To use a larger decoded corpus:
+
+```bash
+# optional download + decode first N rows (needs python3 + pyarrow [+ huggingface-cli])
+bash ${SEED_DIR}/scripts/decode-matraix.sh --download --limit 1000
+export MATRAIX_CORPUS_PATH=./matraix-1m.decoded.json   # or .jsonl
+node ${SEED_DIR}/scripts/prepare-corpus.js --validate "$MATRAIX_CORPUS_PATH" --limit 20
+```
+
+Decoder: `providers/matraix-persona-1m/scripts/decode_parquet.py`
+
+Empty filter results return `[]` (no silent unfiltered fallback). Re-check intent if search is empty.
+
+## Phase 0 — Route
+
+If the user wants a **specific real person / named character with evidence** → hand off to `anyone-skill`.  
+If they want a **sampled archetype / corpus seed** → continue here.
+
+Confirm provider (default `matraix-persona-1m`).
+
+## Phase 1 — Intent
+
+Extract an Intent object (see `schemas/intent.schema.json`):
+
+- `roleHint`, `domain`, `traits`, `locale`, `region`, `exclude`, `query`, `limit` (default 5)
+
+Do not invent MatrAIx attribute names for the user; keep intent in this normalized shape.
+
+## Phase 2 — Search + re-rank
+
+1. Run `search.js --intent …` (attribute filter scores).
+2. If the array is empty, broaden or rewrite intent — do **not** invent hits.
+3. **You** re-rank the shortlist against the user's free-text goal.
+4. Present 3–5 candidates (summary + highlights + `corpusMode`). Ask the user to pick one (or auto-pick top after confirmation).
+
+## Phase 3 — SeedProfile
+
+```bash
+node ${SEED_DIR}/scripts/search.js --to-seed --id <chosen-id> > /tmp/seed-profile.json
+```
+
+Show `identity.summary`, key traits, `gaps`, and `constraints.sensitiveFlags`.  
+Fill gaps with the user:
+
+- required: `personaName`, `slug`, `role`
+- recommended: `boundaries` (especially if `healthcare_domain` is flagged)
+
+**Never** set `soul.identity.sourceIdentity` for MatrAIx / statistical seeds.
+
+## Phase 4 — persona.json + create
+
+```bash
+node ${SEED_DIR}/scripts/map-seed-to-persona.js \
+  --seed /tmp/seed-profile.json \
+  --overrides '{"personaName":"…","slug":"…","role":"mentor"}' \
+  --out /tmp/persona.json
+```
+
+Then follow `skills/open-persona` to generate/install:
+
+```bash
+npx openpersona create --config /tmp/persona.json --output <dir> --install
+```
+
+(or the equivalent non-interactive create flags available in this repo)
+
+## Phase 5 — Provenance
+
+After the pack directory exists:
+
+```bash
+node ${SEED_DIR}/scripts/write-provenance.js --pack <packDir> --seed /tmp/seed-profile.json
+```
+
+Writes `soul/seed-provenance.json` only — does **not** add unknown root keys to `persona.json`.
+
+## Ethics (short)
+
+- Corpus seeds are **archetypes**, not digital twins of living people.
+- Human-grounded MatrAIx rows are de-identified statistical profiles — still do not claim “I am that person.”
+- Respect dataset license notes from `capabilities()`.
+- Healthcare-flagged seeds must keep clinical non-authority boundaries.
+
+## Adding another corpus later
+
+1. Prefer an existing **family** adapter if the schema matches.
+2. Otherwise add `providers/<id>/` implementing the contract.
+3. Register in `providers/registry.json` (`hfRepos`, `family`, `status`).
+4. No new orchestration skill — reuse this one. `/datasets` listing alone is not enough.

skills/persona-seed/providers/README.md

@@ -0,0 +1,18 @@
+# Seed providers
+
+Adapters that turn corpus rows into `SeedProfile`. Orchestration: `../SKILL.md`. Contract: `../references/provider-contract.md`.
+
+**Source of truth for what is seed-capable:** [`registry.json`](./registry.json)
+
+| Provider id | Family | Status | HF repos |
+|-------------|--------|--------|----------|
+| `matraix-persona-1m` | attribute-census | ga | `MatrAIx2026/MatrAIx_Persona_1M` |
+
+`openpersona.co/datasets` may list many more corpora. Only registry rows are usable with persona-seed.
+
+## Add a provider
+
+1. Implement `providers/<id>/provider.js` (`capabilities`, `search`, `fetch`, `toSeed`).
+2. Prefer reusing a **family** module when the schema matches an existing adapter.
+3. Register in `registry.json` (`hfRepos`, `directoryUrls`, `status`).
+4. Keep an offline fixture for tests.

skills/persona-seed/providers/matraix-persona-1m/fixtures/sample-corpus.json

@@ -0,0 +1,107 @@
+[
+  {
+    "id": "fixture-001",
+    "groundingType": "synthetic",
+    "attributes": {
+      "region": "East Asia",
+      "age_bracket": "25-34",
+      "primary_language": "Chinese",
+      "highest_education": "Master's",
+      "occupation_domain": "Software",
+      "occupation": "Backend engineer",
+      "risk_tolerance": "Risk-averse",
+      "communication_formality": "Neutral",
+      "personality_traits": ["curious", "precise", "reserved"],
+      "values": ["craftsmanship", "honesty"],
+      "motivations": ["mastery", "stability"],
+      "interests": ["open source", "hiking", "science fiction"],
+      "speaking_style_hints": ["concise", "asks clarifying questions"],
+      "tools": ["python", "sql", "git"]
+    },
+    "description": "A careful East Asian software engineer in their late twenties who prefers precise answers, low-risk decisions, and open-source craft."
+  },
+  {
+    "id": "fixture-002",
+    "groundingType": "synthetic",
+    "attributes": {
+      "region": "North America",
+      "age_bracket": "35-44",
+      "primary_language": "English",
+      "highest_education": "Bachelor's",
+      "occupation_domain": "Education",
+      "occupation": "High school teacher",
+      "risk_tolerance": "Moderate",
+      "communication_formality": "Warm-formal",
+      "personality_traits": ["patient", "encouraging", "direct"],
+      "values": ["growth", "fairness"],
+      "motivations": ["help others learn"],
+      "interests": ["history", "coaching", "podcasts"],
+      "speaking_style_hints": ["Socratic questions", "plain language"],
+      "tools": ["slides", "learning platforms"]
+    },
+    "description": "A North American teacher who coaches with patience, asks Socratic questions, and keeps language plain."
+  },
+  {
+    "id": "fixture-003",
+    "groundingType": "human_grounded",
+    "attributes": {
+      "region": "Europe",
+      "age_bracket": "45-54",
+      "primary_language": "English",
+      "highest_education": "PhD",
+      "occupation_domain": "Healthcare",
+      "occupation": "Clinical researcher",
+      "risk_tolerance": "Risk-averse",
+      "communication_formality": "Formal",
+      "personality_traits": ["rigorous", "cautious", "empathetic"],
+      "values": ["evidence", "do-no-harm"],
+      "motivations": ["scientific integrity"],
+      "interests": ["biostatistics", "classical music"],
+      "speaking_style_hints": ["hedges claims", "cites uncertainty"],
+      "tools": ["R", "literature review"]
+    },
+    "description": "A European clinical researcher who hedges claims, cites uncertainty, and refuses medical authority cosplay."
+  },
+  {
+    "id": "fixture-004",
+    "groundingType": "synthetic",
+    "attributes": {
+      "region": "Southeast Asia",
+      "age_bracket": "18-24",
+      "primary_language": "English",
+      "highest_education": "Some college",
+      "occupation_domain": "Commerce",
+      "occupation": "Indie seller",
+      "risk_tolerance": "Risk-seeking",
+      "communication_formality": "Casual",
+      "personality_traits": ["energetic", "persuasive", "optimistic"],
+      "values": ["hustle", "community"],
+      "motivations": ["grow a brand"],
+      "interests": ["social commerce", "design", "street food"],
+      "speaking_style_hints": ["upbeat", "emoji-light", "short paragraphs"],
+      "tools": ["shopify", "canva"]
+    },
+    "description": "A young Southeast Asian indie seller with casual upbeat tone and high risk appetite for commerce experiments."
+  },
+  {
+    "id": "fixture-005",
+    "groundingType": "synthetic",
+    "attributes": {
+      "region": "North America",
+      "age_bracket": "25-34",
+      "primary_language": "English",
+      "highest_education": "Bachelor's",
+      "occupation_domain": "Software",
+      "occupation": "Product manager",
+      "risk_tolerance": "Moderate",
+      "communication_formality": "Neutral",
+      "personality_traits": ["structured", "empathetic", "pragmatic"],
+      "values": ["user outcomes", "clarity"],
+      "motivations": ["ship useful products"],
+      "interests": ["UX research", "systems thinking"],
+      "speaking_style_hints": ["bullet-friendly", "tradeoff-aware"],
+      "tools": ["figma", "sql", "notion"]
+    },
+    "description": "A pragmatic product manager who frames tradeoffs clearly and stays oriented to user outcomes."
+  }
+]