@rotifer/playground 0.8.1 → 0.8.6

package/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.6] - 2026-04-16
+
+### Fixed
+
+- **Javy async Gene WASM trap** — `express()` returning a Promise now produces a clear error message instead of an opaque "Pending jobs in the event queue" WASM trap ([#29](https://github.com/rotifer-protocol/rotifer-playground/pull/29))
+- **Compile cache ignoring source changes** — `rotifer compile` now prefers TypeScript/JavaScript source files over a stale `gene.wasm`; previously, the existing WASM was reused even after source edits ([#29](https://github.com/rotifer-protocol/rotifer-playground/pull/29))
+- **irHash serialization mismatch** — phenotype `irHash` field is now stripped before passing to the native Rust binding, preventing serde deserialization failures on the native execution path ([#29](https://github.com/rotifer-protocol/rotifer-playground/pull/29))
+- **WASM sandbox fuel exhaustion** — default `max_fuel` increased from 1M to 500M; default memory raised to 256 MiB; timeout extended to 60s — Javy/QuickJS Genes no longer hit "fuel exhausted" on trivial workloads ([#29](https://github.com/rotifer-protocol/rotifer-playground/pull/29))
+
+### Added
+
+- **Native addon distribution** — prebuilt native bindings are now shipped via platform-specific npm packages (`@rotifer/playground-darwin-arm64`, `-darwin-x64`, `-linux-x64-gnu`, `-win32-x64-msvc`); `npm install` automatically pulls the correct binary for the user's platform ([#28](https://github.com/rotifer-protocol/rotifer-playground/issues/28))
+- **`napi-build.yml` reusable workflow** — 4-platform matrix build for native addons (macOS ARM/x64, Linux x64, Windows x64)
+- **`sync:native-versions` script** — one-command version sync across all platform packages
+- **Version alignment checks** — `verify:versions` now validates platform package versions and `optionalDependencies` consistency
+
+### Changed
+
+- Release pipeline now builds and publishes native addons before the main package (`native-build → publish-native → publish`)
+- CI `rust-check` job now verifies napi compilation with `@napi-rs/cli` instead of `cargo build`
+
+## [0.8.5] - 2026-04-08
+
+### Changed
+
+- **Public release-line consolidation** — aligned the CLI package with the current public `v0.8.5` release line across rotifer.dev, IDE/plugin distribution surfaces, and MCP installation metadata
+- **Shipped v0.8.x surface clarified** — current release messaging now reflects the already-shipped Skill→Gene migration path, CLI UX refresh, version update notifications, and related ecosystem-facing improvements from the `v0.8.x` cycle
+- **Reserved version gap documented** — `v0.8.2` to `v0.8.4` remain reserved internal iteration numbers rather than retroactively published public releases
+
 ## [0.8.1] - 2026-03-27
 
 ### Added
@@ -18,6 +47,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - SVG animation generator with rotifer.dev design system alignment
 - Experiment results with 3 reproducible runs
 
+### Changed
+
+- **Reputation model alignment** — cold-start `R(g)` now uses phase-based weights (W0/W1/W2) instead of a fixed 0.5/0.3/0.2 split
+- **Creator reputation** — now uses a diminishing-returns weighted sum of positive gene reputations, instead of a plain average
+- **Arena safety scoring** — `V(g)` now incorporates the shipped static security scanner (`Security_Leak_Risk`) during `arena submit`
+
 ## [0.8.0] - 2026-02-17
 
 ### Added
@@ -67,12 +102,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- **CLI: `rotifer info <gene-id>`** — display detailed gene information (description, domain, version, fitness, reputation)
+- **CLI: `rotifer info <gene-ref>`** — display detailed gene information (description, domain, version, fitness, reputation)
 - **CLI: `rotifer list`** — list local genes in current project with optional `--domain` filter
 - **CLI: `rotifer run <gene-name>`** — directly execute a single gene with WASM sandbox or Node.js fallback
 - **CLI: `rotifer versions <owner> <name>`** — display version history chain for a gene
 - **CLI: `rotifer whoami`** — show current authentication status
-- **CLI: `rotifer stats <gene-id>`** — display download statistics for a gene
+- **CLI: `rotifer stats <gene-ref>`** — display download statistics for a gene
 - **CLI: `rotifer compare <id...>`** — compare 2-5 genes side by side by fitness and reputation
 
 ### Changed
@@ -179,7 +214,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Phenotype schema display (inputSchema/outputSchema)
   - Stats: version, R(g), downloads, WASM size, dates
   - One-click install command copy
-- **Developer Profile Pages** — each developer has a page at `/developers/[user]/` with:
+- **Creator Profile Pages** — each creator has a page at `/developers/[user]/` with:
   - R(d) reputation score and stats grid
   - Published gene list with links
 - **Gene Registry Upgrade** — `/genes/` listing page now fetches from Cloud API
@@ -266,13 +301,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- **Reputation System** — measurable trust signals for genes and developers
+- **Reputation System** — measurable trust signals for genes and creators
   - Gene reputation R(g) = α·Arena + β·Usage + γ·Stability (weights: 0.5, 0.3, 0.2)
-  - Developer reputation R(d) = avg(gene reputations) + community bonus
+  - Creator reputation R(d) initially launched as a plain average of gene reputations plus community bonus
   - Time-based decay (5%/month, floor at 0.01) prevents reputation stagnation
-  - `rotifer reputation <gene-id>` — view gene reputation breakdown
-  - `rotifer reputation --mine` — view your developer reputation
-  - `rotifer reputation --leaderboard` — top developers ranked by reputation
+  - `rotifer reputation <gene-ref>` — view gene reputation breakdown
+  - `rotifer reputation --mine` — view your creator reputation
+  - `rotifer reputation --leaderboard` — top creators ranked by reputation
   - Database migration `003_reputation.sql` with `gene_reputation` and `developer_reputation` tables
   - Server-side reputation computation via PostgreSQL functions
   - Reputation leaderboard API (`get_reputation_leaderboard()`)
@@ -309,16 +344,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- **Cloud Binding** — Cross-developer gene sharing via Supabase-backed REST API
+- **Cloud Binding** — Cross-creator gene sharing via Supabase-backed REST API
   - `rotifer login` — GitHub OAuth authentication via PKCE flow
   - `rotifer logout` — Clear cloud credentials
   - `rotifer publish <gene>` — Upload gene (phenotype + WASM) to cloud registry, saves `.cloud-manifest.json`
   - `rotifer search [query]` — Search and browse cloud gene registry
-  - `rotifer install <gene-id>` — Download gene from cloud to local project
+  - `rotifer install <gene-ref>` — Download gene from cloud to local project
   - Cloud Binding REST API specification (`docs/cloud-binding-api.md`)
   - Supabase database schema with RLS policies (see `supabase/README.md` for self-hosting guide)
 
-- **Cloud Arena** — Remote Arena competition across developers
+- **Cloud Arena** — Remote Arena competition across creators
   - `rotifer arena submit --cloud` — Submit gene to cloud Arena
   - `rotifer arena list --cloud` — View cloud Arena rankings
   - `rotifer arena watch --cloud` — Real-time cloud ranking updates (polling)

package/README.md

@@ -5,11 +5,11 @@
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org/)
 [![Protocol](https://img.shields.io/badge/Protocol-Frozen-orange)](https://github.com/rotifer-protocol/rotifer-spec)
-[![Discord](https://img.shields.io/discord/placeholder?label=Discord&logo=discord&color=5865F2)](https://discord.gg/6d4JrfMr)
+[![Discord](https://img.shields.io/discord/placeholder?label=Discord&logo=discord&color=5865F2)](https://rotifer.dev/discord)
 
-Development environment for the **Rotifer Protocol** — build genes, compete in Arenas, share via Cloud, and simulate agent evolution.
+Development environment for the **Rotifer Protocol** — **WASM-Native, Polyglot by Design**: build genes in TypeScript / Rust / AssemblyScript / Go / C, compete in Arenas, share via Cloud, and simulate agent evolution.
 
-> **Status:** v0.8.0 (Iron Shell) — Security hardening, WASM sandbox testing, P2P Protocol RFC, Epoch automation, AI docs assistant, WebMCP Phase 1, plus all v0.7 features (Gene lifecycle, IR compiler, Cloud Binding, Reputation, V(g) scanner, badges, MCP Server). P2P implementation and L4 Collective Immunity are planned — see [Implementation Status](#implementation-status) below.
+> **Status:** v0.8.5 — public playground for gene development, Arena competition, and protocol experimentation. This public release line consolidates the shipped `v0.8.x` surface into one coherent version. See [CHANGELOG.md](CHANGELOG.md) for detailed release history. P2P implementation and L4 Collective Immunity are still planned — see [Implementation Status](#implementation-status) below.
 
 ---
 
@@ -29,6 +29,18 @@ npx @rotifer/playground init my-project
 
 ---
 
+## First Agent in Seconds
+
+```bash
+rotifer init my-project && cd my-project
+rotifer hello --list-templates
+rotifer hello
+```
+
+`rotifer init` bootstraps the local Arena and Genesis genes. `rotifer hello` is the preset-agent entrypoint: pick a curated template and run an agent immediately.
+
+---
+
 ## 30-Second Demo
 
 ```bash
@@ -55,7 +67,7 @@ $ rotifer init my-project
 ✓ Project ready: my-project
 ```
 
-One command. Five Genesis genes. A living Arena.
+One command boots the Arena. `rotifer hello` turns those bundled genes into your first preset agent.
 
 ---
 
@@ -72,21 +84,26 @@ You see an Arena with 6 genes ranked by fitness. No configuration needed.
 ### Act 2 — Aha (5 minutes)
 
 ```bash
-rotifer scan genes/               # Discover candidate functions
-rotifer wrap hello-world           # Wrap as a gene (generates Phenotype)
-rotifer test hello-world           # Run L2 sandbox tests (WASM sandbox for compiled genes)
-rotifer test hello-world --compliance  # Run structural compliance checks
-rotifer arena submit hello-world   # Submit to Arena (admission gate)
-rotifer arena list                 # See your gene's ranking
+rotifer hello --list-templates     # See curated Quick Start and Power templates
+rotifer hello                      # Pick a template interactively and run it now
+rotifer agent list                 # Inspect the generated hello-* agent
 ```
 
-Your existing code becomes a gene and competes in the Arena.
+Bundled genes become a working preset agent in seconds.
 
 ### Act 3 — Hooked (30 minutes)
 
-Write a TypeScript gene and compile it to Native WASM automatically:
+Turn your own code into a gene, then build a custom agent:
 
 ```bash
+# Wrap existing code as a gene
+rotifer scan genes/                    # Discover candidate functions
+rotifer wrap hello-world               # Wrap as a gene (generates Phenotype)
+rotifer test hello-world               # Run sandbox tests (WASM sandbox for compiled genes)
+rotifer test hello-world --compliance  # Run structural compliance checks
+rotifer arena submit hello-world       # Submit to Arena (admission gate)
+rotifer arena list                     # See your gene's ranking
+
 # Write a gene in TypeScript — same language, zero learning curve
 mkdir genes/my-search && cat > genes/my-search/index.ts << 'EOF'
 export function express(input: { query: string }) {
@@ -95,8 +112,8 @@ export function express(input: { query: string }) {
 EOF
 
 rotifer wrap my-search --domain search
-rotifer compile my-search          # TS → JS → WASM (Javy) → Rotifer IR
-rotifer arena submit my-search     # Watch it climb the rankings
+rotifer compile my-search           # TS → JS → WASM → Rotifer IR
+rotifer arena submit my-search      # Watch it climb the rankings
 rotifer arena list --domain search # Compare against Genesis genes
 
 # Create an Agent with a gene genome (supports Seq, Par, Cond, Try)
@@ -109,7 +126,7 @@ rotifer agent run search-bot --input '{"query":"rotifer protocol"}'
 rotifer agent run search-bot --no-sandbox  # Force Node.js fallback
 ```
 
-**v0.3 highlight:** `rotifer compile` auto-detects TypeScript genes and compiles them to Native WASM via [Javy](https://github.com/bytecodealliance/javy) (QuickJS→WASM). No separate toolchain required.
+`rotifer compile` auto-detects TypeScript genes and compiles them to Native WASM. No separate toolchain required.
 
 ---
 
@@ -119,16 +136,15 @@ rotifer agent run search-bot --no-sandbox  # Force Node.js fallback
 playground/
 ├── crates/
 │   ├── rotifer-core/        Rust: types, sandbox, arena, algebra, fitness, storage
-│   └── rotifer-napi/        napi-rs bridge: Rust ↔ Node.js FFI
-├── src/                     TypeScript CLI (commander.js)
-│   ├── commands/            16 CLI commands
+│   └── rotifer-napi/        Native bridge: Rust ↔ Node.js FFI
+├── src/                     TypeScript CLI and supporting modules
+│   ├── commands/            CLI command modules
 │   ├── cloud/               Cloud Binding client (auth, API, types)
-│   ├── utils/               Config, display, NAPI binding, Javy compiler
-│   └── errors/              Rust-style error formatting
-├── genes/                   5 Genesis genes (bundled)
+│   └── utils/               Config, display, native binding, IR compiler
+├── genes/                   Bundled gene directories
 ├── supabase/                Cloud Binding self-hosting guide
 ├── templates/               Gene + composition scaffolds
-└── tests/                   Unit + E2E test suites (114 tests)
+└── tests/                   Unit + E2E test suites
 ```
 
 ### Layers
@@ -136,31 +152,46 @@ playground/
 | Layer | Technology | Responsibility |
 |-------|-----------|----------------|
 | **CLI** | TypeScript + commander.js | User interface, command routing, display |
-| **Bridge** | napi-rs (cdylib) | Rust-to-Node.js FFI binding |
-| **Core** | Rust + wasmtime | WASM sandbox (Direct + WASI), Arena engine, Algebra executor, Fitness computation, SQLite storage |
+| **Bridge** | Native bridge (cdylib) | Rust-to-Node.js FFI binding |
+| **Core** | Rust + WASM runtime | WASM sandbox (Direct + WASI), Arena engine, Algebra executor, Fitness computation, SQLite storage |
 
 ---
 
 ## CLI Commands
 
+Run `rotifer --help` for the grouped command list. The commands below cover the main local, cloud, arena, and agent workflows.
+
 | Command | Description |
 |---------|-------------|
-| `rotifer init [name]` | Initialize a new gene project with Genesis genes |
-| `rotifer scan [path]` | Scan source files for candidate gene functions |
-| `rotifer wrap <name>` | Wrap a function as a Rotifer gene |
-| `rotifer test [name]` | Test a gene (WASM sandbox preferred, `--compliance` for structural checks) |
-| `rotifer compile [name]` | Compile gene to Rotifer IR (auto TS→WASM via Javy) |
-| `rotifer arena submit <name>` | Submit a gene to the Arena (`--cloud` for Cloud Arena) |
-| `rotifer arena list` | List Arena rankings (`--cloud` for Cloud Arena) |
-| `rotifer arena watch <domain>` | Watch Arena rankings live (`--cloud` for Cloud Arena) |
-| `rotifer login` | Log in to Rotifer Cloud via GitHub OAuth |
+| `rotifer init [gene-name]` | Initialize a new gene project with Genesis genes |
+| `rotifer hello [--template <id>]` | Create and run a preset agent from curated templates inside a Rotifer project |
+| `rotifer scan [path]` | Scan for candidate genes and local skills |
+| `rotifer wrap <gene-name>` | Wrap a function or SKILL.md as a gene |
+| `rotifer test [gene-name]` | Test a gene (WASM sandbox preferred, `--compliance` for structural checks) |
+| `rotifer compile [gene-name]` | Compile gene to Rotifer IR (auto TS→WASM) |
+| `rotifer run <gene-name>` | Execute a single local gene directly |
+| `rotifer list` | List local genes in the current project |
+| `rotifer login` | Log in to Rotifer Cloud (OAuth) |
 | `rotifer logout` | Log out from Rotifer Cloud |
-| `rotifer publish <name>` | Publish a gene to Rotifer Cloud |
+| `rotifer publish [gene-name]` | Publish gene(s) to Rotifer Cloud |
 | `rotifer search [query]` | Search genes on Rotifer Cloud |
-| `rotifer install <gene-id>` | Install a gene from Rotifer Cloud |
-| `rotifer agent create <name>` | Create an Agent (`--composition Seq\|Par\|Cond\|Try`) |
+| `rotifer install <gene-ref>` | Install a gene from Cloud (UUID, name, or content hash) |
+| `rotifer info <gene-ref>` | View gene details (local or Cloud) |
+| `rotifer stats <gene-ref>` | View download statistics for a gene |
+| `rotifer compare [gene-refs...]` | Compare 2–5 genes by reputation and downloads |
+| `rotifer reputation [gene-ref]` | View gene and creator reputation scores |
+| `rotifer versions <owner> <gene-name>` | View version history chain for a gene |
+| `rotifer arena submit <gene-name>` | Submit a gene to the Arena (`--cloud` for Cloud Arena) |
+| `rotifer arena list` | List Arena rankings (`--cloud` for Cloud Arena) |
+| `rotifer arena watch <domain>` | Watch Arena rankings live (`--cloud` for Cloud Arena) |
+| `rotifer agent create <agent-name>` | Create an Agent (`--composition Seq\|Par\|Cond\|Try\|TryPool`) |
 | `rotifer agent list` | List all agents |
-| `rotifer agent run <name>` | Execute genome pipeline (WASM sandbox, `--no-sandbox` for Node.js) |
+| `rotifer agent run <agent-name>` | Execute genome pipeline (WASM sandbox, `--no-sandbox` for Node.js) |
+| `rotifer vg [path]` | V(g) security scan for gene/skill code |
+| `rotifer network` | P2P gene network commands (see `rotifer network --help`) |
+| `rotifer self-update` | Check for updates and upgrade Rotifer packages |
+| `rotifer config` | Manage global Rotifer configuration |
+| `rotifer whoami` | Show current authentication status |
 
 ---
 
@@ -194,17 +225,28 @@ See `templates/composition/` for JSON examples.
 
 ---
 
+## Examples
+
+The `examples/` directory contains reference implementations and experiments:
+
+| Directory | Description |
+|-----------|-------------|
+| `examples/mcp-migration/` | How to migrate MCP Tools into Rotifer Genes |
+| `examples/api-apocalypse/` | API fault-tolerance experiment — baseline vs Rotifer agent with domain failover |
+
+---
+
 ## Development
 
 ```bash
 git clone https://github.com/rotifer-protocol/rotifer-playground.git
-cd playground
+cd rotifer-playground
 
 # TypeScript CLI
 npm install
 npm run build          # Build to dist/
-npm test               # Run 114 TypeScript tests
-npm run lint           # Type check only
+npm test               # Run the TypeScript test suite (Vitest)
+npm run lint           # Type-check and lint src/
 
 # Rust Core (requires Rust toolchain)
 cargo check -p rotifer-core
@@ -218,18 +260,18 @@ bash demo.sh
 
 ## Implementation Status
 
-> This project is in **alpha**. The table below shows the honest implementation status of each URAA layer as of v0.5.5.
+> This project is in **alpha**. The table below shows the honest implementation status of each URAA layer.
 
 | URAA Layer | Spec Name | Status | What Works | What's Planned |
 |------------|-----------|--------|------------|----------------|
 | **L0** | Kernel | **~35%** | `L0Gate` pre-execution checks (domain, resource, network, filesystem); Audit log | EthicalBoundary, State Anchoring, Trust Anchor |
-| **L1** | Synthesis | **~95%** | WASM sandbox (wasmtime), IR compiler, Javy TS→WASM, NAPI bridge | Full WASI capability negotiation |
+| **L1** | Synthesis | **~95%** | WASM sandbox, IR compiler, TS→WASM compilation, native bridge | Full WASI capability negotiation |
 | **L2** | Calibration | **~40%** | Schema validation, sandbox testing, `--compliance` checks | Static analysis, controlled field trial |
-| **L3** | Competition | **~60%** | Arena ranking, F(g) multiplicative model, R(g) reputation, Cloud Registry | P2P HLT broadcasting (stub only), hot-loading, retirement |
+| **L3** | Competition | **~60%** | Arena ranking, F(g) multiplicative model, R(g) reputation, Cloud Registry | P2P HLT broadcasting (planned), hot-loading, retirement |
 | **L4** | Collective Immunity | **0%** | — | Threat broadcasting, emergency rollback, cross-node consensus |
 | **Algebra** | Composition | **~90%** | All 5 operators in Rust; CLI supports Seq/Par/Cond/Try | DataFlowGraph |
 
-**Key limitation:** L4 depends on L3's P2P network, which is currently a stub. Full L4 is targeted for v0.9+.
+**Key limitation:** L4 depends on L3's P2P network, which is planned. Full L4 is targeted for v0.9+.
 
 ---
 
@@ -242,7 +284,7 @@ Targets **Rotifer Protocol Specification** (Frozen). See [Implementation Status]
 | **Full** | Phenotype, AlgebraExpr, Fitness F(g), Arena | Core gene lifecycle |
 | **Functional** | WASM Sandbox, L0 Gate, Reputation R(g) | L0 at ~35%, expanding |
 | **Simplified** | Agent Lifecycle, Gene Lifecycle, RotiferBinding | MVP subset |
-| **Stub/Planned** | P2P HLT, Formal Verification, Cross-Binding Consistency, ZK Proofs, L4 Immunity | Roadmap items |
+| **Planned** | P2P HLT, Formal Verification, Cross-Binding Consistency, ZK Proofs, L4 Immunity | Roadmap items |
 
 Changes driven by implementation feedback are proposed through the ADR process.
 
@@ -250,24 +292,16 @@ Changes driven by implementation feedback are proposed through the ADR process.
 
 ## Roadmap
 
-- [x] **v0.1** — Core CLI + Genesis genes + Arena
-- [x] **v0.2** — IR compiler pipeline, live Arena watching, NAPI bridge
-- [x] **v0.3** — Frontend SDK: TS→WASM auto-compilation via Javy, WASI sandbox support
-- [x] **v0.4** — Cloud Binding: publish/search/install genes, Cloud Arena, GitHub OAuth
-- [x] **v0.5** — Reputation System, developer documentation, L0 Gate
-- [x] **v0.5.5** — Foundation Hardening: WASM sandbox enforcement, L0 Gate integration, F(g) spec alignment
-- [ ] **v0.6** — Web Registry: dynamic gene pages, developer profiles, gene cold start (≥50 genes)
-- [ ] **v0.6.5** — Cross-Binding Proof: `RotiferBinding` trait, Web3 Mock Binding, IR interop validation
-- [ ] **v0.7** — Hybrid Gene, IDE plugins (Cursor/VS Code), developer dogfooding
-- [ ] **v0.8** — Security hardening, P2P protocol design (RFC)
-- [ ] **v0.9** — P2P network (metadata discovery), economic framework design
-- [ ] **v1.0** — Stable release: L0-L3 complete, economic system, security audit
+See [CHANGELOG.md](CHANGELOG.md) for detailed release history. Upcoming milestones:
+
+- **v0.9** — P2P network (metadata discovery), economic framework design
+- **v1.0** — Stable release: L0-L3 complete, economic system, security audit
 
 ---
 
 ## Community
 
-- [Discord](https://discord.gg/6d4JrfMr) — Join the conversation
+- [Discord](https://rotifer.dev/discord) — Join the conversation
 - [GitHub Discussions](https://github.com/rotifer-protocol/rotifer-playground/discussions) — Questions and proposals
 
 ## Contributing

package/README.zh.md

@@ -5,11 +5,11 @@
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org/)
 [![Protocol](https://img.shields.io/badge/Protocol-Frozen-orange)](https://github.com/rotifer-protocol/rotifer-spec)
-[![Discord](https://img.shields.io/discord/placeholder?label=Discord&logo=discord&color=5865F2)](https://discord.gg/6d4JrfMr)
+[![Discord](https://img.shields.io/discord/placeholder?label=Discord&logo=discord&color=5865F2)](https://rotifer.dev/discord)
 
 **Rotifer Protocol** 的开发环境——构建基因、运行 Arena 竞争、通过 Cloud 共享、模拟代理进化。
 
-> **状态：** v0.8.0（Iron Shell）— 安全加固、WASM 沙箱测试、P2P Protocol RFC、Epoch 自动化、AI 文档助手、WebMCP Phase 1，以及 v0.7 全部功能（基因生命周期、IR 编译器、Cloud Binding、声誉系统、V(g) 扫描器、徽章、MCP Server）。P2P 实现和 L4 集体免疫为规划中功能——详见下方[实现状态](#实现状态)。
+> **状态：** v0.8.5——面向基因开发、Arena 竞争和协议实验的公开 Playground。本次公开版本线将已落地的 `v0.8.x` 能力收口为同一版本口径。详细版本历史请参见 [CHANGELOG.md](CHANGELOG.md)。P2P 实现与 L4 集体免疫仍在规划中——详见下方[实现状态](#实现状态)。
 
 ---
 
@@ -29,6 +29,18 @@ npx @rotifer/playground init my-project
 
 ---
 
+## 几秒钟跑通第一个 Agent
+
+```bash
+rotifer init my-project && cd my-project
+rotifer hello --list-templates
+rotifer hello
+```
+
+`rotifer init` 先把本地 Arena 和 Genesis genes 建起来；`rotifer hello` 则是预设 agent 的主入口：从精选模板里挑一个，立刻创建并运行。
+
+---
+
 ## 30 秒演示
 
 ```bash
@@ -55,7 +67,7 @@ $ rotifer init my-project
 ✓ Project ready: my-project
 ```
 
-一条命令。五个 Genesis 基因。一个活跃的 Arena。
+一条命令先把 Arena 跑起来；`rotifer hello` 再把这些内置基因收口成你的第一个预设 agent。
 
 ---
 
@@ -72,22 +84,27 @@ rotifer init my-project && cd my-project
 ### 第二幕——Aha（5 分钟）
 
 ```bash
-rotifer scan genes/               # 发现候选基因函数
-rotifer wrap hello-world           # 包装为基因（生成 Phenotype）
-rotifer test hello-world           # 在 L2 沙箱中运行测试（已编译基因走 WASM 沙箱）
-rotifer test hello-world --compliance  # 运行结构性合规检查
-rotifer arena submit hello-world   # 提交到 Arena（准入评估）
-rotifer arena list                 # 查看你的基因排名
+rotifer hello --list-templates     # 查看 Quick Start / Power 模板
+rotifer hello                      # 交互式选择模板并立即运行
+rotifer agent list                 # 查看生成的 hello-* agent
 ```
 
-你的现有代码变成了基因，并在 Arena 中竞争。
+内置基因在几秒内就能组合成一个可运行的预设 agent。
 
 ### 第三幕——Hooked（30 分钟）
 
-用 TypeScript 编写基因，自动编译为原生 WASM：
+把自己的代码变成基因，再组合成自定义 Agent：
 
 ```bash
-# 用 TypeScript 写基因——同一语言，零学习成本
+# 先把现有代码包装成基因
+rotifer scan genes/                    # 发现候选基因函数
+rotifer wrap hello-world               # 包装为基因（生成 Phenotype）
+rotifer test hello-world               # 在 L2 沙箱中运行测试（已编译基因走 WASM 沙箱）
+rotifer test hello-world --compliance  # 运行结构性合规检查
+rotifer arena submit hello-world       # 提交到 Arena（准入评估）
+rotifer arena list                     # 查看你的基因排名
+
+# 再用 TypeScript 写一个新基因——同一语言，零学习成本
 mkdir genes/my-search && cat > genes/my-search/index.ts << 'EOF'
 export function express(input: { query: string }) {
   return { results: [`Found: ${input.query}`], total: 1 };
@@ -95,8 +112,8 @@ export function express(input: { query: string }) {
 EOF
 
 rotifer wrap my-search --domain search
-rotifer compile my-search          # TS → JS → WASM (Javy) → Rotifer IR
-rotifer arena submit my-search     # 观察它攀升排名
+rotifer compile my-search           # TS → JS → WASM (Javy) → Rotifer IR
+rotifer arena submit my-search      # 观察它攀升排名
 rotifer arena list --domain search # 与 Genesis 基因对比
 
 # 创建一个拥有基因组的 Agent（支持 Seq, Par, Cond, Try）
@@ -109,7 +126,7 @@ rotifer agent run search-bot --input '{"query":"rotifer protocol"}'
 rotifer agent run search-bot --no-sandbox  # 强制 Node.js 回退
 ```
 
-**v0.3 亮点：** `rotifer compile` 自动检测 TypeScript 基因，通过 [Javy](https://github.com/bytecodealliance/javy)（QuickJS→WASM）编译为原生 WASM，无需额外工具链。
+**说明：** `rotifer compile` 自动检测 TypeScript 基因，通过 [Javy](https://github.com/bytecodealliance/javy)（QuickJS→WASM）编译为原生 WASM，无需额外工具链。
 
 ---
 
@@ -120,13 +137,14 @@ playground/
 ├── crates/
 │   ├── rotifer-core/        Rust: 类型、沙箱、Arena、代数、适应度、存储
 │   └── rotifer-napi/        napi-rs 桥接: Rust ↔ Node.js FFI
-├── src/                     TypeScript CLI (commander.js)
-│   ├── commands/            11 个 CLI 命令
-│   ├── utils/               配置、显示、NAPI 绑定、Javy 编译器
-│   └── errors/              Rust 风格的错误格式化
-├── genes/                   5 个 Genesis 基因（内置）
+├── src/                     TypeScript CLI 与支撑模块
+│   ├── commands/            CLI 命令模块
+│   ├── cloud/               Cloud Binding 客户端（auth、API、types）
+│   └── utils/               配置、显示、NAPI 绑定、IR 编译器
+├── genes/                   随仓库提供的 gene 目录
+├── supabase/                Cloud Binding 自托管指南
 ├── templates/               基因 + 组合脚手架模板
-└── tests/                   单元测试 + E2E 测试（91 个测试）
+└── tests/                   单元测试 + E2E 测试
 ```
 
 ### 分层
@@ -141,19 +159,39 @@ playground/
 
 ## CLI 命令
 
+运行 `rotifer --help` 查看按模块分组的命令列表。下面列出最常用的本地、Cloud、Arena 与 Agent 工作流命令：
+
 | 命令 | 说明 |
 |------|------|
-| `rotifer init [name]` | 初始化新的基因项目（包含 Genesis 基因） |
-| `rotifer scan [path]` | 扫描源文件中的候选基因函数 |
-| `rotifer wrap <name>` | 将函数包装为 Rotifer 基因 |
-| `rotifer test [name]` | 测试基因（WASM 沙箱优先，`--compliance` 运行结构性检查） |
-| `rotifer compile [name]` | 编译基因为 Rotifer IR（自动 TS→WASM via Javy） |
-| `rotifer arena submit <name>` | 将基因提交到 Arena（`--cloud` 提交到 Cloud Arena） |
-| `rotifer arena list` | 列出 Arena 排名（`--cloud` 查看 Cloud Arena） |
-| `rotifer arena watch <domain>` | 观察 Arena 排名（`--cloud` 查看 Cloud Arena） |
-| `rotifer agent create <name>` | 创建 Agent（`--composition Seq\|Par\|Cond\|Try`） |
-| `rotifer agent list` | 列出所有 Agent |
-| `rotifer agent run <name>` | 执行基因组管线（WASM 沙箱，`--no-sandbox` 走 Node.js） |
+| `rotifer init [gene-name]` | 初始化新的 Rotifer 基因项目 |
+| `rotifer hello [--template <id>]` | 在 Rotifer 项目内从精选模板创建并运行一个预设 agent |
+| `rotifer scan [path]` | 扫描候选基因和本地技能 |
+| `rotifer wrap <gene-name>` | 将函数或 `SKILL.md` 包装为基因 |
+| `rotifer test [gene-name]` | 在沙箱中测试基因 |
+| `rotifer compile [gene-name]` | 将基因编译为 Rotifer IR（WASM） |
+| `rotifer run <gene-name>` | 直接执行单个本地基因 |
+| `rotifer list` | 列出当前项目中的本地基因 |
+| `rotifer login` | 登录 Rotifer Cloud |
+| `rotifer logout` | 从 Rotifer Cloud 登出 |
+| `rotifer publish [gene-name]` | 将基因发布到 Rotifer Cloud |
+| `rotifer search [query]` | 在 Rotifer Cloud 中搜索基因 |
+| `rotifer install <gene-ref>` | 从 Rotifer Cloud 安装基因 |
+| `rotifer info <gene-ref>` | 查看基因详情（本地或 Cloud） |
+| `rotifer stats <gene-ref>` | 查看基因下载统计 |
+| `rotifer compare [gene-refs...]` | 按声誉与下载量对比 2-5 个基因 |
+| `rotifer reputation [gene-ref]` | 查看基因与创作者声誉分数 |
+| `rotifer versions <owner> <gene-name>` | 查看某个基因的版本链 |
+| `rotifer arena submit <gene-name>` | 将基因提交到 Arena 竞争 |
+| `rotifer arena list` | 列出 Arena 排名 |
+| `rotifer arena watch <domain>` | 实时观察 Arena 排名 |
+| `rotifer agent create <agent-name>` | 用基因组创建 Agent |
+| `rotifer agent list` | 列出全部 Agent |
+| `rotifer agent run <agent-name>` | 执行 Agent 的基因组管线 |
+| `rotifer vg [path]` | 对基因代码执行 V(g) 安全扫描 |
+| `rotifer network` | P2P 基因网络命令 |
+| `rotifer self-update` | 检查并升级 Rotifer 包 |
+| `rotifer config` | 管理全局 Rotifer 配置 |
+| `rotifer whoami` | 显示当前认证状态 |
 
 ---
 
@@ -187,17 +225,28 @@ JSON 示例参见 `templates/composition/`。
 
 ---
 
+## 示例
+
+`examples/` 目录包含参考实现和实验：
+
+| 目录 | 说明 |
+|------|------|
+| `examples/mcp-migration/` | 如何将 MCP Tool 迁移为 Rotifer Gene |
+| `examples/api-apocalypse/` | API 容错实验——基线 Agent 与 Rotifer 域故障转移 Agent 的对比 |
+
+---
+
 ## 开发
 
 ```bash
 git clone https://github.com/rotifer-protocol/rotifer-playground.git
-cd playground
+cd rotifer-playground
 
 # TypeScript CLI
 npm install
 npm run build          # 构建到 dist/
-npm test               # 运行 91 个 TypeScript 测试
-npm run lint           # 仅类型检查
+npm test               # 运行 TypeScript 测试套件（Vitest）
+npm run lint           # 对 src/ 做类型检查和 lint
 
 # Rust Core（需要 Rust 工具链）
 cargo check -p rotifer-core
@@ -211,7 +260,7 @@ bash demo.sh
 
 ## 实现状态
 
-> 本项目处于 **alpha** 阶段。下表展示了截至 v0.5.5 各 URAA 层级的真实实现状态。
+> 本项目处于 **alpha** 阶段。下表展示了当前各 URAA 层级的真实实现状态。
 
 | URAA 层级 | 规范名称 | 完成度 | 已可用 | 规划中 |
 |-----------|---------|--------|--------|--------|
@@ -243,24 +292,16 @@ bash demo.sh
 
 ## 路线图
 
-- [x] **v0.1** — 核心 CLI + Genesis 基因 + Arena
-- [x] **v0.2** — IR 编译器管线、实时 Arena 观察、NAPI 桥接
-- [x] **v0.3** — 前端 SDK：TS→WASM 自动编译 via Javy、WASI 沙箱支持
-- [x] **v0.4** — Cloud Binding：发布/搜索/安装基因、Cloud Arena、GitHub OAuth
-- [x] **v0.5** — 声誉系统、开发者文档、L0 Gate
-- [x] **v0.5.5** — 地基加固：WASM 沙箱强制执行、L0 Gate 集成、F(g) 规范对齐
-- [ ] **v0.6** — Web Registry：动态 Gene 页面、开发者主页、Gene 冷启动（≥50 个 Gene）
-- [ ] **v0.6.5** — 跨绑定验证：`RotiferBinding` trait、Web3 Mock Binding、IR 互操作验证
-- [ ] **v0.7** — 混合基因、IDE 插件（Cursor/VS Code）、开发者 dogfooding
-- [ ] **v0.8** — 安全加固、P2P 协议设计（RFC）
-- [ ] **v0.9** — P2P 网络（元数据发现）、经济体系设计
-- [ ] **v1.0** — 稳定版：L0-L3 完整、经济体系上线、安全审计
+详细发布历史请参见 [CHANGELOG.md](CHANGELOG.md)。接下来的里程碑：
+
+- **v0.9** — P2P 网络（元数据发现）、经济体系设计
+- **v1.0** — 稳定版：L0-L3 完整、经济体系上线、安全审计
 
 ---
 
 ## 社区
 
-- [Discord](https://discord.gg/6d4JrfMr) — 加入讨论
+- [Discord](https://rotifer.dev/discord) — 加入讨论
 - [GitHub Discussions](https://github.com/rotifer-protocol/rotifer-playground/discussions) — 问题与提案
 
 ## 参与贡献