@rotifer/playground 0.8.1 → 0.8.5

package/CHANGELOG.md

@@ -5,6 +5,14 @@ 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.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 +26,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 +81,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 +193,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 +280,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 +323,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.
 
-> **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.
 
 ---
 
@@ -74,7 +74,7 @@ You see an Arena with 6 genes ranked by fitness. No configuration needed.
 ```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           # 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
@@ -95,7 +95,7 @@ export function express(input: { query: string }) {
 EOF
 
 rotifer wrap my-search --domain search
-rotifer compile my-search          # TS → JS → WASM (Javy) → Rotifer IR
+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
 
@@ -109,7 +109,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 +119,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 +135,45 @@ 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 CLI has **18** primary top-level commands (Development, Cloud, the first four Discovery commands, and Arena & Agents). Six more top-level commands complete the tree: `versions` (Discovery), then `vg`, `network`, `self-update`, `config`, and `whoami` (Tools / Other)—**24** names total.
+
 | 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 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 +207,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 +242,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 +266,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 +274,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 集体免疫仍在规划中——详见下方[实现状态](#实现状态)。
 
 ---
 
@@ -109,7 +109,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 +120,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 +142,38 @@ playground/
 
 ## CLI 命令
 
+运行 `rotifer --help` 查看按模块分组的命令列表。常用命令如下：
+
 | 命令 | 说明 |
 |------|------|
-| `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 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 +207,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 +242,7 @@ bash demo.sh
 
 ## 实现状态
 
-> 本项目处于 **alpha** 阶段。下表展示了截至 v0.5.5 各 URAA 层级的真实实现状态。
+> 本项目处于 **alpha** 阶段。下表展示了当前各 URAA 层级的真实实现状态。
 
 | URAA 层级 | 规范名称 | 完成度 | 已可用 | 规划中 |
 |-----------|---------|--------|--------|--------|
@@ -243,24 +274,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) — 问题与提案
 
 ## 参与贡献

package/dist/cloud/auth.d.ts

@@ -12,9 +12,15 @@ export declare function isLoggedIn(): boolean;
 export declare function requireAuth(): Promise<CloudCredentials>;
 export declare function generateCodeVerifier(): string;
 export declare function generateCodeChallenge(verifier: string): string;
+export declare const OAUTH_CALLBACK_HOST = "127.0.0.1";
+export declare function buildOAuthCallbackUrl(port: number, path?: string): string;
 /**
- * Start a local HTTP server to receive the OAuth callback.
- * Handles both PKCE flow (?code=...) and implicit flow (#access_token=...).
+ * Start a local OAuth callback server on a random port (127.0.0.1:0).
+ * Returns the bound port immediately so the caller can construct the auth URL,
+ * plus a promise that resolves when the callback arrives.
  */
-export declare function waitForOAuthCallback(port?: number): Promise<string>;
+export declare function startOAuthCallbackServer(): Promise<{
+    port: number;
+    waitForCallback: Promise<string>;
+}>;
 //# sourceMappingURL=auth.d.ts.map

package/dist/cloud/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/cloud/auth.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAe,MAAM,YAAY,CAAC;AAqChE,wBAAgB,eAAe,IAAI,gBAAgB,GAAG,IAAI,CAazD;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CA4C1D;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAK7D;AAED,wBAAgB,gBAAgB,IAAI,IAAI,CAMvC;AAED,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAS7D;AAED,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,GAAE,MAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CA+DzE"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/cloud/auth.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAe,MAAM,YAAY,CAAC;AAoChE,wBAAgB,eAAe,IAAI,gBAAgB,GAAG,IAAI,CAazD;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CA4C1D;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAM7D;AAED,wBAAgB,gBAAgB,IAAI,IAAI,CAMvC;AAED,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAS7D;AAED,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,eAAO,MAAM,mBAAmB,cAAc,CAAC;AAE/C,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAoB,GAAG,MAAM,CAEtF;AAED;;;;GAIG;AACH,wBAAsB,wBAAwB,IAAI,OAAO,CAAC;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;CAClC,CAAC,CAwED"}

package/dist/cloud/auth.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.OAUTH_CALLBACK_HOST = void 0;
 exports.loadCredentials = loadCredentials;
 exports.refreshTokenIfNeeded = refreshTokenIfNeeded;
 exports.saveCredentials = saveCredentials;
@@ -8,17 +9,17 @@ exports.isLoggedIn = isLoggedIn;
 exports.requireAuth = requireAuth;
 exports.generateCodeVerifier = generateCodeVerifier;
 exports.generateCodeChallenge = generateCodeChallenge;
-exports.waitForOAuthCallback = waitForOAuthCallback;
+exports.buildOAuthCallbackUrl = buildOAuthCallbackUrl;
+exports.startOAuthCallbackServer = startOAuthCallbackServer;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_http_1 = require("node:http");
 const node_crypto_1 = require("node:crypto");
 const types_js_1 = require("./types.js");
+const private_fs_js_1 = require("../utils/private-fs.js");
 const ROTIFER_HOME = (0, node_path_1.join)(process.env.HOME || process.env.USERPROFILE || "/tmp", ".rotifer");
 function ensureRotiferHome() {
-    if (!(0, node_fs_1.existsSync)(ROTIFER_HOME)) {
-        (0, node_fs_1.mkdirSync)(ROTIFER_HOME, { recursive: true });
-    }
+    (0, private_fs_js_1.ensurePrivateDir)(ROTIFER_HOME);
 }
 function credentialsPath() {
     return (0, node_path_1.join)(ROTIFER_HOME, types_js_1.CREDENTIALS_FILE);
@@ -105,6 +106,7 @@ function saveCredentials(creds) {
     (0, node_fs_1.writeFileSync)(credentialsPath(), JSON.stringify(creds, null, 2) + "\n", {
         mode: 0o600,
     });
+    (0, private_fs_js_1.tightenPrivateFile)(credentialsPath());
 }
 function clearCredentials() {
     const path = credentialsPath();
@@ -130,14 +132,26 @@ function generateCodeVerifier() {
 function generateCodeChallenge(verifier) {
     return (0, node_crypto_1.createHash)("sha256").update(verifier).digest("base64url");
 }
+exports.OAUTH_CALLBACK_HOST = "127.0.0.1";
+function buildOAuthCallbackUrl(port, path = "/callback") {
+    return `http://${exports.OAUTH_CALLBACK_HOST}:${port}${path}`;
+}
 /**
- * Start a local HTTP server to receive the OAuth callback.
- * Handles both PKCE flow (?code=...) and implicit flow (#access_token=...).
+ * Start a local OAuth callback server on a random port (127.0.0.1:0).
+ * Returns the bound port immediately so the caller can construct the auth URL,
+ * plus a promise that resolves when the callback arrives.
  */
-function waitForOAuthCallback(port = 9876) {
+async function startOAuthCallbackServer() {
     return new Promise((resolve, reject) => {
+        let callbackResolve;
+        let callbackReject;
+        const waitForCallback = new Promise((res, rej) => {
+            callbackResolve = res;
+            callbackReject = rej;
+        });
         const server = (0, node_http_1.createServer)((req, res) => {
-            const url = new URL(req.url || "/", `http://localhost:${port}`);
+            const boundPort = server.address()?.port || 0;
+            const url = new URL(req.url || "/", buildOAuthCallbackUrl(boundPort));
             if (url.pathname === "/callback/token") {
                 const token = url.searchParams.get("access_token");
                 const refresh = url.searchParams.get("refresh_token");
@@ -147,7 +161,7 @@ function waitForOAuthCallback(port = 9876) {
                         "<p>You can close this window and return to the terminal.</p>" +
                         "</body></html>");
                     server.close();
-                    resolve(`implicit:${token}:${refresh || ""}`);
+                    callbackResolve(`implicit:${token}:${refresh || ""}`);
                     return;
                 }
             }
@@ -158,7 +172,7 @@ function waitForOAuthCallback(port = 9876) {
                     "<p>You can close this window and return to the terminal.</p>" +
                     "</body></html>");
                 server.close();
-                resolve(code);
+                callbackResolve(code);
             }
             else {
                 res.writeHead(200, { "Content-Type": "text/html" });
@@ -178,15 +192,16 @@ if (window.location.hash) {
 </script><noscript>Enable JavaScript to complete login.</noscript></body></html>`);
             }
         });
-        server.listen(port, () => {
-            // Server ready
+        server.listen(0, exports.OAUTH_CALLBACK_HOST, () => {
+            const addr = server.address();
+            resolve({ port: addr.port, waitForCallback });
         });
         server.on("error", (err) => {
             reject(new Error(`Failed to start callback server: ${err.message}`));
         });
         setTimeout(() => {
             server.close();
-            reject(new Error("Login timed out after 120 seconds"));
+            callbackReject(new Error("Login timed out after 120 seconds"));
         }, 120_000);
     });
 }