u-foo 3.0.13 → 3.0.15

package/SKILLS/ufoo-online/SKILL.md

@@ -1,144 +1,75 @@
 ---
 name: ufoo-online
-description: |
-  Connect any agent to the ufoo-online WebSocket relay for public channel chat,
-  public rooms, or private room collaboration. Use when users ask to join ufoo online,
-  chat with other agents, or check inbox.
+description: >-
+  Connect agents through the ufoo-online WebSocket relay, including public
+  channels, public or private rooms, inboxes, tokens, and relay administration.
+  Use when asked to join remote ufoo collaboration, send or receive online
+  messages, create rooms or channels, or operate a relay server.
 ---
 
-# /ufoo-online - Online Relay Client
+# ufoo online
 
-Connect to the ufoo-online WebSocket relay, join channels/rooms, send messages, and check inbox.
+Operate remote collaboration through a long-running relay connection.
 
-## Quick Start
+## Connect an agent
 
-### 1. Start a local relay server
+Start a local relay when needed:
 
 ```bash
-ufoo online server --port 8787
+ufoo online server --host 127.0.0.1 --port 8787
 ```
 
-### 2. Connect (long-running, run in background)
+Run one connection as a streaming background task:
 
 ```bash
-# Join a public channel
-ufoo online connect --nickname my-agent --join lobby --ping-ms 15000
-
-# Join a private room (enables bus/decisions/wake sync)
-ufoo online connect --nickname my-agent --room room_001 --room-password secret --ping-ms 15000
-```
-
-Use `run_in_background: true` to keep the connection alive in agent sessions.
-
-### 3. Send a message
-
-```bash
-# Send to a channel
-ufoo online send --nickname my-agent --channel lobby --text "hello everyone"
-
-# Send to a room
-ufoo online send --nickname my-agent --room room_001 --text "hello team"
-```
-
-Messages are queued to the local outbox (`~/.ufoo/online/outbox/<nickname>.jsonl`)
-and delivered by the running `connect` process. The connect process must be running
-for messages to be sent.
-
-### 4. Check inbox
-
-```bash
-# View all messages
-ufoo online inbox my-agent
-
-# View unread only
-ufoo online inbox my-agent --unread
-
-# Clear inbox
-ufoo online inbox my-agent --clear
-```
-
-Inbox retention: channel messages 7 days, room messages 30 days.
-
-## Full Connect Options
-
-```bash
-ufoo online connect --nickname <name> [--url <wss://...>] [--subscriber <id>]
-  [--token <tok>] [--token-hash <hash>] [--world <name>] [--ping-ms <ms>]
-  [--join <channel>] [--room <room-id> --room-password <pwd>]
-  [--interval <ms>] [--allow-insecure-ws]
-  [--trust-remote] [--allow-from <subscriberId>]
+ufoo online connect --nickname <name> --join <channel> --ping-ms 15000
+ufoo online connect --nickname <name> --room <room-id> --room-password <password> --ping-ms 15000
 ```
 
-Features:
-- Auto-reconnect with exponential backoff (500ms -> 8s)
-- Auto-generates token if none exists; persists to `~/.ufoo/online/tokens.json`
-- Incoming messages saved to `~/.ufoo/online/inbox/<nickname>.jsonl`
-- Polls outbox for queued sends
-- Prints all messages to stdout as JSON; prints `CONNECTED` on handshake
-- Non-local `ws://` is blocked by default; use `wss://` or `--allow-insecure-ws`.
-- **Private room mode** (`--room`): bus/decisions/wake sync is gated; use
-  `--trust-remote` or `--allow-from` to allow inbound sync.
+Keep the connection running. Outbox messages are delivered by this process and
+incoming messages are written to the local inbox.
 
-## Server Management
+## Send and receive messages
 
 ```bash
-# Start relay (dev mode — any token accepted)
-ufoo online server --port 8787
-
-# Start with token validation
-ufoo online server --port 8787 --token-file ~/.ufoo/online/tokens.json
-
-# Custom host/idle timeout
-ufoo online server --host 0.0.0.0 --port 8787 --idle-timeout 60000
+ufoo online send --nickname <name> --channel <channel> --text "<message>"
+ufoo online send --nickname <name> --room <room-id> --text "<message>"
+ufoo online inbox <name> --unread
+ufoo online inbox <name> --clear
 ```
 
-## Token Management
+Channel inbox entries are retained for 7 days; room entries are retained for
+30 days.
 
-```bash
-ufoo online token <subscriber-id> --nickname <name> [--server <url>]
-```
-
-Tokens are stored in `~/.ufoo/online/tokens.json`. The connect command
-auto-resolves tokens by subscriber ID or nickname lookup.
-
-## Room & Channel Management
+## Manage channels and rooms
 
 ```bash
-# Channels (public broadcast, can join multiple)
-ufoo online channel list [--server <url>]
-ufoo online channel create --name <name> [--type world|public] [--server <url>]
-
-# Rooms (collaboration, can join one)
-ufoo online room list [--server <url>]
-ufoo online room create --type public|private [--name <room>] [--password <pwd>] [--server <url>]
+ufoo online channel list --server <url>
+ufoo online channel create --name <name> --type public --server <url>
+ufoo online room list --server <url>
+ufoo online room create --name <name> --type public --server <url>
+ufoo online room create --name <name> --type private --password <password> --server <url>
 ```
 
-If the relay requires auth, pass `--auth-token <token>` (or `--token-file` +
-`--subscriber`/`--nickname`) to room/channel commands to send the Bearer token.
-
-## Usage Scenarios
+Pass `--auth-token`, or use `--token-file` with subscriber or nickname lookup,
+when the relay requires authentication.
 
-### 1. Public channel chat
+## Manage identities and tokens
 
 ```bash
-ufoo online server --port 8787                          # Terminal 1
-ufoo online connect --nickname agent-a --join lobby     # Terminal 2 (background)
-ufoo online connect --nickname agent-b --join lobby     # Terminal 3 (background)
-ufoo online send --nickname agent-a --channel lobby --text "hi all"
-ufoo online inbox agent-b                               # See agent-a's message
+ufoo online token <subscriber-id> --nickname <name> --server <url>
 ```
 
-### 2. Private room collaboration
+Tokens persist under `~/.ufoo/online/tokens.json`. Do not print token values or
+room passwords in reports.
 
-```bash
-ufoo online room create --type private --password secret --server https://online.ufoo.dev
-# → returns room_id
-
-ufoo online connect --nickname dev-1 --room room_001 --room-password secret
-ufoo online connect --nickname dev-2 --room room_001 --room-password secret
-```
+## Apply transport safety
 
-In private room mode, agents automatically sync:
-- Bus messages (local bus <-> online relay, bidirectional)
-- Decisions (new .md files synced across team)
-- Wake events (remote agent can wake local agent via bus)
+- Prefer `wss://` for non-local relays.
+- Allow non-local `ws://` only with explicit user intent.
+- Treat private-room bus, decision, and wake synchronization as untrusted by
+  default.
+- Use `--trust-remote` only for a fully trusted room; otherwise restrict
+  inbound synchronization with `--allow-from <subscriber-id>`.
+- Bind development relays to `127.0.0.1` unless the user explicitly requests
+  network exposure and accepts the security implications.

package/SKILLS/ufoo-online/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ufoo online"
+  short_description: "Connect agents through ufoo online collaboration"
+  default_prompt: "Use $ufoo-online to connect this agent to an online collaboration room."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-foo",
-  "version": "3.0.13",
+  "version": "3.0.15",
   "description": "Multi-Agent Workspace Protocol. Just add u. claude → uclaude, codex → ucodex.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://ufoo.dev",
@@ -38,6 +38,7 @@
     "scripts/",
     "dist/tui/",
     "SKILLS/",
+    "OPTIONAL_SKILLS/",
     "LICENSE",
     "README.md"
   ],

package/scripts/postinstall-skills.js

@@ -0,0 +1,81 @@
+const fs = require("fs");
+const path = require("path");
+
+const RETIRED_DEFAULT_SKILLS = Object.freeze(["ubus", "uctx", "uinit", "ustatus"]);
+const LEGACY_COMMAND_NAMES = Object.freeze([
+  "ubus",
+  "uctx",
+  "ufoo",
+  "ufoo-bus",
+  "ufoo-context",
+  "ufoo-online",
+  "uinit",
+  "ustatus",
+]);
+
+function removeManagedSymlink(linkPath, expectedTarget) {
+  try {
+    const stat = fs.lstatSync(linkPath);
+    if (!stat.isSymbolicLink()) return false;
+
+    const rawTarget = fs.readlinkSync(linkPath);
+    const resolvedTarget = path.resolve(path.dirname(linkPath), rawTarget);
+    if (resolvedTarget !== path.resolve(expectedTarget)) return false;
+
+    fs.rmSync(linkPath, { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function removeLegacySkillAndCommandLinks({ pkgRoot, home, codexHome } = {}) {
+  const rawPackageRoot = String(pkgRoot || "").trim();
+  const rawUserHome = String(home || "").trim();
+  if (!rawPackageRoot || !rawUserHome) return [];
+
+  const packageRoot = path.resolve(rawPackageRoot);
+  const userHome = path.resolve(rawUserHome);
+  const codexRoots = new Set([
+    path.join(userHome, ".codex"),
+    path.resolve(String(codexHome || path.join(userHome, ".codex"))),
+  ]);
+  const removed = [];
+
+  for (const name of RETIRED_DEFAULT_SKILLS) {
+    const skillDir = path.join(packageRoot, "SKILLS", name);
+    const candidates = [
+      {
+        linkPath: path.join(userHome, ".claude", "skills", name),
+        expectedTarget: skillDir,
+      },
+      ...Array.from(codexRoots).map((root) => ({
+        linkPath: path.join(root, "skills", name),
+        expectedTarget: skillDir,
+      })),
+    ];
+
+    for (const candidate of candidates) {
+      if (removeManagedSymlink(candidate.linkPath, candidate.expectedTarget)) {
+        removed.push(candidate.linkPath);
+      }
+    }
+  }
+
+  for (const name of LEGACY_COMMAND_NAMES) {
+    const linkPath = path.join(userHome, ".claude", "commands", `${name}.md`);
+    const expectedTarget = path.join(packageRoot, "SKILLS", name, "SKILL.md");
+    if (removeManagedSymlink(linkPath, expectedTarget)) {
+      removed.push(linkPath);
+    }
+  }
+
+  return removed;
+}
+
+module.exports = {
+  RETIRED_DEFAULT_SKILLS,
+  LEGACY_COMMAND_NAMES,
+  removeManagedSymlink,
+  removeLegacySkillAndCommandLinks,
+};

package/scripts/postinstall.js

@@ -2,6 +2,7 @@
 const path = require("path");
 const fs = require("fs");
 const os = require("os");
+const { removeLegacySkillAndCommandLinks } = require("./postinstall-skills");
 
 // Fix node-pty spawn-helper permissions on macOS (both arm64 and x64)
 const platforms = ["darwin-arm64", "darwin-x64"];
@@ -50,7 +51,7 @@ function collectSkillSources(pkgRoot) {
       if (entry.isDirectory()) {
         const skillMd = path.join(topSkills, entry.name, "SKILL.md");
         if (fs.existsSync(skillMd)) {
-          sources.push({ name: entry.name, dir: path.join(topSkills, entry.name), md: skillMd });
+          sources.push({ name: entry.name, dir: path.join(topSkills, entry.name) });
         }
       }
     }
@@ -70,17 +71,6 @@ function forceSymlink(target, linkPath) {
   fs.symlinkSync(target, linkPath);
 }
 
-function installClaudeCommands(home, sources) {
-  const commandsDir = path.join(home, ".claude", "commands");
-  fs.mkdirSync(commandsDir, { recursive: true });
-
-  for (const { name, md } of sources) {
-    forceSymlink(md, path.join(commandsDir, `${name}.md`));
-  }
-
-  console.log(`[postinstall] Installed ${sources.length} ufoo command(s) to ${commandsDir}`);
-}
-
 function installSkillDirs(targetDir, sources, label) {
   fs.mkdirSync(targetDir, { recursive: true });
 
@@ -92,19 +82,22 @@ function installSkillDirs(targetDir, sources, label) {
 }
 
 // Install ufoo skills for Claude and Codex at npm install time.
-// - Claude slash commands: ~/.claude/commands/<name>.md -> SKILL.md
 // - Claude skills: ~/.claude/skills/<name> -> skill dir
 // - Codex skills: ${CODEX_HOME:-~/.codex}/skills/<name> -> skill dir
 try {
   const pkgRoot = path.resolve(__dirname, "..");
   const home = os.homedir();
   const sources = collectSkillSources(pkgRoot);
+  const codexHome = process.env.CODEX_HOME || path.join(home, ".codex");
+  const retiredLinks = removeLegacySkillAndCommandLinks({ pkgRoot, home, codexHome });
+
+  if (retiredLinks.length > 0) {
+    console.log(`[postinstall] Removed ${retiredLinks.length} legacy ufoo link(s)`);
+  }
 
   if (sources.length > 0) {
-    installClaudeCommands(home, sources);
     installSkillDirs(path.join(home, ".claude", "skills"), sources, "~/.claude/skills");
 
-    const codexHome = process.env.CODEX_HOME || path.join(home, ".codex");
     installSkillDirs(path.join(codexHome, "skills"), sources, `${codexHome}/skills`);
   }
 } catch (err) {

package/src/app/cli/busCoreCommands.js

@@ -40,17 +40,106 @@ function parseSendArgs(cmdArgs = []) {
 }
 
 function resolvePollSubscriber(cmdArgs = [], env = process.env) {
-  const positionals = cmdArgs.filter((arg) => typeof arg === "string" && !arg.startsWith("--"));
-  const subscriber = String(positionals[0] || env.UFOO_SUBSCRIBER_ID || "").trim();
+  let subscriber = "";
+  let autoAck = false;
+  let follow = false;
+  let intervalSeconds = 2;
+  let intervalWasSet = false;
+
+  for (let index = 0; index < cmdArgs.length; index += 1) {
+    const arg = String(cmdArgs[index] || "");
+    if (arg === "--ack" || arg === "--auto-ack") {
+      autoAck = true;
+      continue;
+    }
+    if (arg === "--follow") {
+      follow = true;
+      continue;
+    }
+    if (arg === "--interval") {
+      const value = cmdArgs[index + 1];
+      if (value === undefined || String(value).startsWith("--")) {
+        throw new Error("poll --interval requires <seconds>");
+      }
+      intervalSeconds = Number(value);
+      intervalWasSet = true;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--interval=")) {
+      intervalSeconds = Number(arg.slice("--interval=".length));
+      intervalWasSet = true;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      throw new Error(`Unknown poll option: ${arg}`);
+    }
+    if (subscriber) {
+      throw new Error("poll accepts at most one [subscriber]");
+    }
+    subscriber = arg.trim();
+  }
+
+  subscriber = String(subscriber || env.UFOO_SUBSCRIBER_ID || "").trim();
   if (!subscriber) {
     throw new Error("poll requires [subscriber] or UFOO_SUBSCRIBER_ID");
   }
+  if (follow && autoAck) {
+    throw new Error("poll --follow cannot be combined with --ack");
+  }
+  if (intervalWasSet && !follow) {
+    throw new Error("poll --interval requires --follow");
+  }
+  if (!Number.isFinite(intervalSeconds) || intervalSeconds < 0.25) {
+    throw new Error("poll --interval must be at least 0.25 seconds");
+  }
+
   return {
     subscriber,
-    autoAck: cmdArgs.includes("--ack") || cmdArgs.includes("--auto-ack"),
+    autoAck,
+    follow,
+    intervalSeconds,
   };
 }
 
+function resolveAckArgs(cmdArgs = []) {
+  let subscriber = "";
+  let throughSeq = null;
+
+  for (let index = 0; index < cmdArgs.length; index += 1) {
+    const arg = String(cmdArgs[index] || "");
+    if (arg === "--through") {
+      const value = cmdArgs[index + 1];
+      if (value === undefined || String(value).startsWith("--")) {
+        throw new Error("ack --through requires <seq>");
+      }
+      throughSeq = Number(value);
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--through=")) {
+      throughSeq = Number(arg.slice("--through=".length));
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      throw new Error(`Unknown ack option: ${arg}`);
+    }
+    if (subscriber) {
+      throw new Error("ack accepts exactly one <subscriber>");
+    }
+    subscriber = arg.trim();
+  }
+
+  if (!subscriber) {
+    throw new Error("ack requires <subscriber>");
+  }
+  if (throughSeq !== null && (!Number.isInteger(throughSeq) || throughSeq <= 0)) {
+    throw new Error("ack --through requires a positive integer sequence");
+  }
+
+  return { subscriber, throughSeq };
+}
+
 async function runBusCoreCommand(eventBus, cmd, cmdArgs = []) {
   switch (cmd) {
     case "init":
@@ -91,11 +180,24 @@ async function runBusCoreCommand(eventBus, cmd, cmdArgs = []) {
     case "poll":
       {
         const parsed = resolvePollSubscriber(cmdArgs);
-        await eventBus.check(parsed.subscriber, parsed.autoAck);
+        if (parsed.follow) {
+          await eventBus.poll(parsed.subscriber, {
+            intervalSeconds: parsed.intervalSeconds,
+          });
+        } else {
+          await eventBus.check(parsed.subscriber, parsed.autoAck);
+        }
       }
       return {};
     case "ack":
-      await eventBus.ack(cmdArgs[0]);
+      {
+        const parsed = resolveAckArgs(cmdArgs);
+        if (parsed.throughSeq !== null) {
+          await eventBus.ackThrough(parsed.subscriber, parsed.throughSeq);
+        } else {
+          await eventBus.ack(parsed.subscriber);
+        }
+      }
       return {};
     case "consume":
       await eventBus.consume(cmdArgs[0], cmdArgs.includes("--from-beginning"));
@@ -117,4 +219,8 @@ async function runBusCoreCommand(eventBus, cmd, cmdArgs = []) {
   }
 }
 
-module.exports = { runBusCoreCommand, resolvePollSubscriber };
+module.exports = {
+  resolveAckArgs,
+  resolvePollSubscriber,
+  runBusCoreCommand,
+};

package/src/app/cli/features/doctor.js

@@ -36,8 +36,8 @@ class RepoDoctor {
 
   run() {
     const skillsDir = path.join(this.repoRoot, "SKILLS");
-    const contextSkill = path.join(skillsDir, "uctx", "SKILL.md");
-    const busSkill = path.join(skillsDir, "ubus", "SKILL.md");
+    const contextSkill = path.join(skillsDir, "ufoo-context", "SKILL.md");
+    const busSkill = path.join(skillsDir, "ufoo-bus", "SKILL.md");
 
     if (!fs.existsSync(contextSkill)) this.fail(`missing ${contextSkill}`);
     if (!fs.existsSync(busSkill)) this.fail(`missing ${busSkill}`);
@@ -49,8 +49,8 @@ class RepoDoctor {
     console.log("=== ufoo doctor ===");
     console.log(`Monorepo: ${this.repoRoot}`);
     console.log("Skills:");
-    if (fs.existsSync(contextSkill)) console.log(`- uctx: ${contextSkill}`);
-    if (fs.existsSync(busSkill)) console.log(`- ubus: ${busSkill}`);
+    if (fs.existsSync(contextSkill)) console.log(`- ufoo-context: ${contextSkill}`);
+    if (fs.existsSync(busSkill)) console.log(`- ufoo-bus: ${busSkill}`);
     this.reportTui();
 
     if (this.failed) {

package/src/app/cli/features/skills.js

@@ -8,6 +8,7 @@ class SkillsManager {
   constructor(repoRoot) {
     this.repoRoot = repoRoot;
     this.skillRoots = this.findSkillRoots();
+    this.optionalSkillRoots = this.findOptionalSkillRoots();
   }
 
   /**
@@ -22,13 +23,31 @@ class SkillsManager {
     return roots;
   }
 
+  /**
+   * Optional skills are discoverable and explicitly installable, but are not
+   * included in default listings or `skills install all`.
+   */
+  findOptionalSkillRoots() {
+    const roots = [];
+    const optionalSkills = path.join(this.repoRoot, "OPTIONAL_SKILLS");
+    if (fs.existsSync(optionalSkills)) {
+      roots.push(optionalSkills);
+    }
+    return roots;
+  }
+
   /**
    * 列出所有技能
    */
-  list() {
+  list(options = {}) {
     const skills = new Set();
+    const roots = options.optionalOnly
+      ? this.optionalSkillRoots
+      : (options.includeOptional
+        ? [...this.skillRoots, ...this.optionalSkillRoots]
+        : this.skillRoots);
 
-    for (const root of this.skillRoots) {
+    for (const root of roots) {
       if (!fs.existsSync(root)) {
         continue;
       }
@@ -48,7 +67,7 @@ class SkillsManager {
    * 查找技能路径
    */
   findSkill(name) {
-    for (const root of this.skillRoots) {
+    for (const root of [...this.skillRoots, ...this.optionalSkillRoots]) {
       const skillPath = path.join(root, name);
       if (fs.existsSync(skillPath)) {
         return skillPath;

package/src/app/cli/run.js

@@ -1102,11 +1102,12 @@ async function runCli(argv) {
     skills
       .command("list")
       .description("List available skills")
-      .action(() => {
+      .option("--optional", "List opt-in skills that are not installed by default")
+      .action((opts) => {
         const SkillsManager = require("./features/skills");
         const repoRoot = getPackageRoot();
         const manager = new SkillsManager(repoRoot);
-        const skillsList = manager.list();
+        const skillsList = manager.list({ optionalOnly: Boolean(opts.optional) });
         skillsList.forEach((skill) => console.log(skill));
       });
     skills
@@ -1526,6 +1527,49 @@ async function runCli(argv) {
             process.exitCode = 1;
           });
       });
+    bus
+      .command("poll")
+      .description("Check once, or stream pending messages for an opt-in background task")
+      .argument("[subscriber]", "Subscriber ID (defaults to UFOO_SUBSCRIBER_ID)")
+      .option("--ack", "Acknowledge after a one-shot check")
+      .option("--auto-ack", "Alias for --ack")
+      .option("--follow", "Continuously emit newly observed pending events")
+      .option("--interval <seconds>", "Follow interval in seconds")
+      .action(async (subscriber, opts) => {
+        const EventBus = require("../../coordination/bus");
+        const eventBus = new EventBus(process.cwd());
+        const args = [];
+        if (subscriber) args.push(subscriber);
+        if (opts.ack) args.push("--ack");
+        if (opts.autoAck) args.push("--auto-ack");
+        if (opts.follow) args.push("--follow");
+        if (opts.interval !== undefined) args.push("--interval", String(opts.interval));
+
+        try {
+          await runBusCoreCommand(eventBus, "poll", args);
+        } catch (err) {
+          console.error(err.message);
+          process.exitCode = 1;
+        }
+      });
+    bus
+      .command("ack")
+      .description("Acknowledge pending messages")
+      .argument("<subscriber>", "Subscriber ID")
+      .option("--through <seq>", "Acknowledge only through this displayed sequence")
+      .action(async (subscriber, opts) => {
+        const EventBus = require("../../coordination/bus");
+        const eventBus = new EventBus(process.cwd());
+        const args = [subscriber];
+        if (opts.through !== undefined) args.push("--through", String(opts.through));
+
+        try {
+          await runBusCoreCommand(eventBus, "ack", args);
+        } catch (err) {
+          console.error(err.message);
+          process.exitCode = 1;
+        }
+      });
     bus
       .command("inject")
       .description("Inject /bus into a Terminal.app tab by subscriber ID")
@@ -1695,7 +1739,7 @@ async function runCli(argv) {
     console.log("  ufoo report <start|progress|done|error|list> [message] [--task <id>] [--agent <id>]");
     console.log("  ufoo ucode [doctor|prepare|build] [--skip-install]");
     console.log("  ufoo init [--targets <list>] [--project <dir>]");
-    console.log("  ufoo skills list");
+    console.log("  ufoo skills list [--optional]");
     console.log("  ufoo skills install <name|all> [--target <dir> | --codex | --agents]");
     console.log("  ufoo group templates [list|ls] [--json]");
     console.log("  ufoo group template <list|show|validate|new> [target] [--from <builtin>] [--global] [--force] [--json]");
@@ -1715,7 +1759,8 @@ async function runCli(argv) {
     console.log("  ufoo online send --nickname <name> --text <msg> [--channel <ch>] [--room <id>]");
     console.log("  ufoo online inbox <nickname> [--clear] [--unread]");
     console.log("  ufoo bus wake <target> [--reason <reason>] [--no-shake]");
-    console.log("  ufoo bus poll [subscriber] [--ack]");
+    console.log("  ufoo bus poll [subscriber] [--ack | --follow --interval <seconds>]");
+    console.log("  ufoo bus ack <subscriber> [--through <seq>]");
     console.log("  ufoo bus <args...>    (JS bus implementation)");
     console.log("  ufoo ctx <subcmd> ... (doctor|lint|decisions|sync)");
     console.log("  ufoo history <build|show|prompt> [limit]");
@@ -2056,7 +2101,7 @@ async function runCli(argv) {
     const sub = rest[0] || "";
 
     if (sub === "list") {
-      const skillsList = manager.list();
+      const skillsList = manager.list({ optionalOnly: rest.includes("--optional") });
       skillsList.forEach((skill) => console.log(skill));
       return;
     }