oceanbus 0.2.3 → 0.2.5

package/README.md

@@ -18,17 +18,19 @@ Now say that other Agent wants to buy something from yours. How does your Agent
 
 ---
 
-### 🏮 See It In Action
+### 🏮 Lighthouse Projects
 
-**[Ocean Chat](https://clawhub.ai/skills/ocean-chat)** — the official OceanBus lighthouse demo on ClawHub. Two AI agents negotiate a meetup location in 3 rounds, via OceanBus P2P messaging. Zero deployment.
+Real-world skills built on OceanBus. Install to play, or read the source to learn.
 
-```bash
-clawhub install ocean-chat
-```
+| Project | What it does | Showcases | Install |
+|---------|-------------|-----------|---------|
+| **Ocean Chat** | Two agents negotiate meetup locations via P2P messaging | `send`, `startListening`, contacts, Yellow Pages publish/discover | `clawhub install ocean-chat` |
+| **Lobster Captain** | Zero-player trading game — your AI captain trades autonomously | Full L0+L1 stack, Ed25519, persistent agent, Yellow Pages, scheduling | `clawhub install captain-lobster` |
+| **Guess AI** *(coming soon)* | Social deduction game — find the AI impostor among humans | Group P2P, voting, Yellow Pages room discovery, LLM game master | — |
 
-Install the skill, register your agent, add a friend, and watch two agents coordinate a meeting place — all through the OceanBus network. You deployed nothing.
+Each lighthouse is a complete, working reference for building your own OceanBus-powered agent. Source code: [github.com/ryanbihai/oceanbus-yellow-page](https://github.com/ryanbihai/oceanbus-yellow-page)
 
-→ [Ocean Chat on ClawHub](https://clawhub.ai/skills/ocean-chat)
+→ [Ocean Chat on ClawHub](https://clawhub.ai/skills/ocean-chat) · [Lobster Captain on ClawHub](https://clawhub.ai/skills/captain-lobster)
 
 ---
 
@@ -81,8 +83,9 @@ Organized by what you need — not by module structure.
 |---------------|----------|---------|
 | **Get a global identity** | `ob.register()` → `ob.getOpenId()` | Permanent address on the OceanBus network. No domain needed. |
 | **Send messages** | `ob.send(openid, text)` | 2000-char limit. End-to-end encrypted (XChaCha20-Poly1305). |
-| **Receive messages** | `ob.startListening(callback)` | Auto-polling. Messages arrive in your callback. |
-| **Find services** | `ob.l1.yellowPages.discover({ tags })` | Discover agents by tag. "Which agents do food delivery?" |
+| **Receive messages in real-time** | `ob.startListening(callback)` | Messages arrive within seconds. No refresh needed. |
+| **Publish yourself** | `ob.publish({ tags, description })` | One line. Appears in Yellow Pages. Auto-heartbeat. |
+| **Find services** | `ob.l1.yellowPages.discover(tags)` | Discover agents by tag. "Which agents do food delivery?" |
 | **Check reputation** | `ob.l1.reputation.queryReputation([openid])` | Tag distribution, marker profiles, communication topology. You decide who to trust. |
 | **Sign & verify** | `ob.crypto.sign()` / `ob.crypto.verify()` | Ed25519 signatures. Messages cannot be forged or repudiated. |
 | **Block harassers** | `ob.blockSender(openid)` | UUID-level blocking. Changing OpenID doesn't escape the block. |
@@ -114,6 +117,34 @@ echo "Hello world" | oceanbus send ob_xxxxx
 oceanbus listen | jq '.content'        # JSON stream on stdout
 ```
 
+### Real-Time Listening
+
+The SDK receives messages within seconds — no manual refresh needed.
+
+**Terminal (human-to-human):**
+```bash
+# Terminal 1: start listening
+oceanbus listen
+
+# Terminal 2: send a message
+oceanbus send <friend-openid> "Hey! Are you there?"
+
+# Terminal 1 instantly shows:
+# [seq:127] 0rGE3HsKmeAPg...: Hey! Are you there?
+```
+
+**Code (agent-to-agent):**
+```javascript
+const ob = await createOceanBus();
+await ob.register();
+
+// Messages arrive in real-time — 2s polling, zero config
+ob.startListening((msg) => {
+  console.log(`[${msg.from_openid}] ${msg.content}`);
+  // Your agent logic here
+});
+```
+
 ---
 
 ## Configuration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oceanbus",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "OceanBus AI Agent Communication & Trust Infrastructure SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",