@tritard/waterbrother 0.16.41 → 0.16.43

package/README.md

@@ -266,6 +266,7 @@ Shared project foundation is now live:
 - inspect it with `waterbrother room status`
 - control conversation vs execution with `waterbrother room mode chat|plan|execute`
 - manage collaborators with `waterbrother room members`, `waterbrother room invites`, `waterbrother room invite`, `waterbrother room invite accept`, and `waterbrother room remove`
+- inspect recent collaboration activity with `waterbrother room events`
 - manage the shared backlog with `waterbrother room tasks`, `waterbrother room task add`, and `waterbrother room task move`
 - assign, claim, and discuss shared work with `waterbrother room task assign`, `waterbrother room task claim`, `waterbrother room task comment`, and `waterbrother room task history`
 - choose a shared execution preset with `waterbrother room runtime <profile>`
@@ -295,7 +296,8 @@ Current Telegram behavior:
 - pending pairings are explicit and expire automatically after 12 hours unless approved
 - paired Telegram users drive the same live session and permissions as the terminal operator when the TUI bridge is attached
 - Telegram now supports remote workspace control with `/cwd`, `/use <path>`, `/desktop`, and `/new-project <name>`
-- shared projects now support `/room`, `/members`, `/invites`, `/tasks`, `/mode`, `/claim`, `/release`, `/invite`, `/accept-invite`, `/approve-invite`, `/reject-invite`, `/remove-member`, `/room-runtime`, and `/task ...` from Telegram
+- shared projects now support `/room`, `/events`, `/members`, `/invites`, `/whoami`, `/people`, `/tasks`, `/mode`, `/claim`, `/release`, `/invite`, `/accept-invite`, `/approve-invite`, `/reject-invite`, `/remove-member`, `/room-runtime`, and `/task ...` from Telegram
+- Telegram now supports `/whoami` for Telegram-id and shared-room membership visibility, plus `/events` for recent shared-room activity
 - `/room` now includes pending invite count plus task ownership summaries
 - local `/status` now includes `sharedRoom` with pending invites, task ownership summary, and recent shared-room event activity
 - the TUI now prints a small Roundtable event feed when new shared-room activity lands

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tritard/waterbrother",
-  "version": "0.16.41",
+  "version": "0.16.43",
   "description": "Waterbrother: bring-your-own-model coding CLI with local tools, sessions, operator modes, and approval controls",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -81,6 +81,7 @@ import {
   formatSharedProjectStatus,
   getSharedTaskHistory,
   getSharedProjectPaths,
+  listSharedEvents,
   listSharedInvites,
   listSharedMembers,
   listSharedTasks,
@@ -178,6 +179,7 @@ const INTERACTIVE_COMMANDS = [
   { name: "/share-project", description: "Enable shared-project mode in the current cwd" },
   { name: "/unshare-project", description: "Disable shared-project mode in the current cwd" },
   { name: "/room", description: "Show shared room status for the current project" },
+  { name: "/room events", description: "Show recent Roundtable room events" },
   { name: "/room members", description: "List shared-project members" },
   { name: "/room invites", description: "List pending shared-project invites" },
   { name: "/room add <id> [owner|editor|observer]", description: "Add or update a shared-project member" },
@@ -4047,6 +4049,22 @@ async function runRoomCommand(positional, { cwd = process.cwd(), asJson = false,
     return;
   }
 
+  if (sub === "events") {
+    const events = await listSharedEvents(cwd, 12);
+    if (asJson) {
+      printData({ ok: true, events }, true);
+      return;
+    }
+    if (!events.length) {
+      console.log("No recent shared-room events");
+      return;
+    }
+    for (const event of events) {
+      console.log(`${event.createdAt}\t${event.type}\t${event.actorName || event.actorId || "-"}\t${event.text}`);
+    }
+    return;
+  }
+
   if (sub === "tasks") {
     const tasks = await listSharedTasks(cwd);
     if (asJson) {
@@ -4296,7 +4314,7 @@ async function runRoomCommand(positional, { cwd = process.cwd(), asJson = false,
     return;
   }
 
-  throw new Error("Usage: waterbrother room status|members|invites|add <member-id> [owner|editor|observer] [display name]|invite <member-id> [owner|editor|observer] [display name]|invite approve <invite-id>|invite accept <invite-id>|invite reject <invite-id>|remove <member-id>|tasks|task add <text>|task assign <id> <member-id>|task claim <id>|task move <id> <open|active|blocked|done>|task comment <id> <text>|task history <id>|runtime [<name>|clear]|mode <chat|plan|execute>|claim|release");
+  throw new Error("Usage: waterbrother room status|events|members|invites|add <member-id> [owner|editor|observer] [display name]|invite <member-id> [owner|editor|observer] [display name]|invite approve <invite-id>|invite accept <invite-id>|invite reject <invite-id>|remove <member-id>|tasks|task add <text>|task assign <id> <member-id>|task claim <id>|task move <id> <open|active|blocked|done>|task comment <id> <text>|task history <id>|runtime [<name>|clear]|mode <chat|plan|execute>|claim|release");
 }
 
 async function runMcpCommand(positional, runtime, { cwd, asJson = false } = {}) {
@@ -8241,6 +8259,15 @@ Be concrete about surfaces — name actual pages/flows. Choose the best stack fo
       continue;
     }
 
+    if (line === "/room events") {
+      try {
+        await runRoomCommand(["room", "events"], { cwd: context.cwd, asJson: false, runtime: context.runtime, currentSession, agent, context });
+      } catch (error) {
+        console.log(`room events failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      continue;
+    }
+
     if (line === "/room tasks") {
       try {
         await runRoomCommand(["room", "tasks"], { cwd: context.cwd, asJson: false, runtime: context.runtime, currentSession, agent, context });

package/src/gateway.js

@@ -8,7 +8,7 @@ import { createSession, listSessions, loadSession, saveSession } from "./session
 import { DEFAULT_PENDING_PAIRING_TTL_MINUTES, loadGatewayBridge, loadGatewayState, prunePendingPairings, saveGatewayBridge, saveGatewayState } from "./gateway-state.js";
 import { getGatewayStatus, getChannelSpec } from "./channels.js";
 import { canonicalizeLoosePath } from "./path-utils.js";
-import { acceptSharedInvite, addSharedTask, approveSharedInvite, assignSharedTask, claimSharedOperator, claimSharedTask, commentSharedTask, createSharedInvite, getSharedTaskHistory, listSharedInvites, listSharedTasks, loadSharedProject, moveSharedTask, rejectSharedInvite, releaseSharedOperator, setSharedRoom, setSharedRoomMode, setSharedRuntimeProfile, removeSharedMember } from "./shared-project.js";
+import { acceptSharedInvite, addSharedTask, approveSharedInvite, assignSharedTask, claimSharedOperator, claimSharedTask, commentSharedTask, createSharedInvite, getSharedTaskHistory, listSharedEvents, listSharedInvites, listSharedTasks, loadSharedProject, moveSharedTask, rejectSharedInvite, releaseSharedOperator, setSharedRoom, setSharedRoomMode, setSharedRuntimeProfile, removeSharedMember } from "./shared-project.js";
 import { buildSelfAwarenessManifest, formatAboutWaterbrother, formatSelfState, resolveLocalConceptQuestion } from "./self-awareness.js";
 
 const execFileAsync = promisify(execFile);
@@ -27,9 +27,12 @@ const TELEGRAM_COMMANDS = [
   { command: "state", description: "Show current Waterbrother self-awareness state" },
   { command: "run", description: "Execute an explicit remote prompt" },
   { command: "status", description: "Show the linked remote session" },
+  { command: "whoami", description: "Show your Telegram identity and room membership" },
+  { command: "people", description: "Show recently seen Telegram people in this chat" },
   { command: "cwd", description: "Show the current remote working directory" },
   { command: "runtime", description: "Show active runtime status" },
   { command: "room", description: "Show shared room status" },
+  { command: "events", description: "Show recent shared room events" },
   { command: "members", description: "List shared room members" },
   { command: "invites", description: "List pending shared room invites" },
   { command: "tasks", description: "List shared Roundtable tasks" },
@@ -204,12 +207,15 @@ function buildRemoteHelp() {
     "<code>/state</code> show current Waterbrother self-awareness state",
     "<code>/run &lt;prompt&gt;</code> execute an explicit remote request",
     "<code>/status</code> show the current linked remote session",
+    "<code>/whoami</code> show your Telegram identity and room membership",
+    "<code>/people</code> list recent Telegram users in this chat for easier invites",
     "<code>/cwd</code> show the current remote working directory",
     "<code>/use &lt;path&gt;</code> switch the linked session to another directory",
     "<code>/desktop</code> switch the linked session to <code>~/Desktop</code>",
     "<code>/new-project &lt;name&gt;</code> create a folder on Desktop and switch into it",
     "<code>/runtime</code> show active provider/model/runtime state",
     "<code>/room</code> show shared project room status",
+    "<code>/events</code> show recent shared room events",
     "<code>/members</code> list shared project members",
     "<code>/tasks</code> list shared project tasks",
     "<code>/task add &lt;text&gt;</code> add a shared Roundtable task",
@@ -220,7 +226,8 @@ function buildRemoteHelp() {
     "<code>/task history &lt;id&gt;</code> show task history and comments",
     "<code>/room-runtime</code> or <code>/room-runtime &lt;name|clear&gt;</code> inspect or set the shared room runtime profile",
     "<code>/invites</code> list pending shared invites",
-    "<code>/invite &lt;user-id&gt; [owner|editor|observer]</code> create a pending shared-project invite",
+    "<code>/invite &lt;user-id|@username&gt; [owner|editor|observer]</code> create a pending shared-project invite",
+    "reply to a teammate and use <code>/invite [owner|editor|observer]</code> to invite that person directly",
     "<code>/accept-invite &lt;invite-id&gt;</code> accept your own pending invite",
     "<code>/approve-invite &lt;invite-id&gt;</code> approve a pending invite",
     "<code>/reject-invite &lt;invite-id&gt;</code> reject a pending invite",
@@ -388,6 +395,79 @@ function formatTelegramInvitesMarkup(invites = []) {
   ].join("\n");
 }
 
+function formatTelegramEventsMarkup(events = []) {
+  if (!events.length) {
+    return "<b>Recent room events</b>\n• none";
+  }
+  return [
+    "<b>Recent room events</b>",
+    ...events.map((event) => {
+      const actor = String(event.actorName || event.actorId || "").trim();
+      const when = String(event.createdAt || "").trim();
+      return `• ${actor ? `${escapeTelegramHtml(actor)} — ` : ""}${escapeTelegramHtml(event.text || "")}${when ? `\n  <code>${escapeTelegramHtml(when)}</code>` : ""}`;
+    })
+  ].join("\n");
+}
+
+function formatTelegramWhoamiMarkup({ message, member = null, invites = [], sharedEnabled = false }) {
+  const from = message?.from || {};
+  const userId = String(from.id || "").trim();
+  const username = String(from.username || "").trim();
+  const displayName = [from.first_name, from.last_name].filter(Boolean).join(" ").trim() || username || userId;
+  const pending = invites.filter((invite) => String(invite.memberId || "").trim() === userId);
+  const lines = [
+    "<b>Telegram identity</b>",
+    `name: <code>${escapeTelegramHtml(displayName)}</code>`,
+    `user id: <code>${escapeTelegramHtml(userId)}</code>`,
+    `username: <code>${escapeTelegramHtml(username || "none")}</code>`
+  ];
+  if (!sharedEnabled) {
+    lines.push("shared room: <code>off</code>");
+    lines.push("This project is not shared yet. Start with <code>waterbrother project share</code>.");
+    return lines.join("\n");
+  }
+  lines.push(`shared member: <code>${member ? "yes" : "no"}</code>`);
+  if (member) {
+    lines.push(`role: <code>${escapeTelegramHtml(member.role || "editor")}</code>`);
+  }
+  if (pending.length) {
+    lines.push("<b>Pending invites you can accept</b>");
+    lines.push(...pending.map((invite) => `• <code>${escapeTelegramHtml(invite.id)}</code> <i>(${escapeTelegramHtml(invite.role || "editor")})</i>`));
+    lines.push("Use <code>/accept-invite &lt;invite-id&gt;</code> to join the shared room.");
+  } else {
+    lines.push("No pending Waterbrother room invite for this Telegram user id.");
+  }
+  lines.push("Use <code>/people</code> in a shared chat to see recent Telegram ids and usernames you can invite.");
+  return lines.join("\n");
+}
+
+function formatTelegramPeopleMarkup({ people = [], project = null }) {
+  if (!people.length) {
+    return [
+      "<b>Recent Telegram people</b>",
+      "• none",
+      "Talk in the shared chat first, then run <code>/people</code> again."
+    ].join("\n");
+  }
+  const members = Array.isArray(project?.members) ? project.members : [];
+  const pendingInvites = Array.isArray(project?.pendingInvites) ? project.pendingInvites : [];
+  return [
+    "<b>Recent Telegram people</b>",
+    ...people.map((person) => {
+      const member = members.find((entry) => String(entry?.id || "").trim() === person.userId);
+      const pendingInvite = pendingInvites.find((entry) => String(entry?.memberId || "").trim() === person.userId);
+      const bits = [`<code>${escapeTelegramHtml(person.userId)}</code>`];
+      if (person.usernameHandle) bits.push(`@${escapeTelegramHtml(person.usernameHandle)}`);
+      bits.push(escapeTelegramHtml(person.displayName || person.userId));
+      if (member?.role) bits.push(`<i>member:${escapeTelegramHtml(member.role)}</i>`);
+      else if (pendingInvite?.id) bits.push(`<i>pending:${escapeTelegramHtml(pendingInvite.id)}</i>`);
+      else if (person.paired) bits.push("<i>paired</i>");
+      return `• ${bits.join(" ")}`;
+    }),
+    "Invite by id, by @username, or by replying to a message with <code>/invite [role]</code>."
+  ].join("\n");
+}
+
 function formatTelegramTasksMarkup(tasks = []) {
   if (!tasks.length) {
     return "<b>Shared tasks</b>\n• none";
@@ -484,12 +564,15 @@ function suggestTaskText(text = "") {
 
 function parseInviteCommand(text) {
   const parts = String(text || "").trim().split(/\s+/).filter(Boolean);
-  const userId = String(parts[1] || "").trim();
+  let target = String(parts[1] || "").trim();
   let role = "editor";
-  if (parts[2] && ["owner", "editor", "observer"].includes(String(parts[2]).toLowerCase())) {
+  if (target && ["owner", "editor", "observer"].includes(target.toLowerCase())) {
+    role = target.toLowerCase();
+    target = "";
+  } else if (parts[2] && ["owner", "editor", "observer"].includes(String(parts[2]).toLowerCase())) {
     role = String(parts[2]).toLowerCase();
   }
-  return { userId, role };
+  return { target, role };
 }
 
 function extractRetryDelayMs(error, attempt) {
@@ -674,12 +757,100 @@ class TelegramGateway {
     await saveGatewayState("telegram", this.state);
   }
 
+  describeTelegramUser(from = {}) {
+    const userId = String(from?.id || "").trim();
+    const usernameHandle = String(from?.username || "").trim();
+    const displayName = [from?.first_name, from?.last_name].filter(Boolean).join(" ").trim() || usernameHandle || userId;
+    return { userId, usernameHandle, displayName };
+  }
+
+  listKnownChatPeople(message) {
+    const chatId = String(message?.chat?.id || "").trim();
+    const byId = new Map();
+    const upsert = (person = {}) => {
+      const userId = String(person.userId || person.id || "").trim();
+      if (!userId) return;
+      const existing = byId.get(userId) || { userId, usernameHandle: "", displayName: userId, paired: false };
+      byId.set(userId, {
+        ...existing,
+        ...person,
+        userId,
+        usernameHandle: String(person.usernameHandle || existing.usernameHandle || "").trim(),
+        displayName: String(person.displayName || existing.displayName || userId).trim() || userId,
+        paired: person.paired === true || existing.paired === true
+      });
+    };
+
+    for (const [userId, peer] of Object.entries(this.state.peers || {})) {
+      if (String(peer?.chatId || "").trim() !== chatId) continue;
+      upsert({
+        userId,
+        usernameHandle: String(peer?.usernameHandle || "").trim(),
+        displayName: String(peer?.displayName || peer?.username || userId).trim(),
+        paired: true,
+        lastSeenAt: String(peer?.lastSeenAt || "").trim()
+      });
+    }
+
+    for (const [userId, pending] of Object.entries(this.state.pendingPairings || {})) {
+      if (String(pending?.chatId || "").trim() !== chatId) continue;
+      upsert({
+        userId,
+        usernameHandle: String(pending?.usernameHandle || "").trim(),
+        displayName: String(pending?.displayName || pending?.username || userId).trim(),
+        paired: false,
+        lastSeenAt: String(pending?.lastSeenAt || pending?.firstSeenAt || "").trim()
+      });
+    }
+
+    const current = this.describeTelegramUser(message?.from || {});
+    if (current.userId) upsert({ ...current, paired: this.isAuthorizedUser(message?.from) === true });
+    const replied = this.describeTelegramUser(message?.reply_to_message?.from || {});
+    if (replied.userId) upsert({ ...replied, paired: this.isAuthorizedUser(message?.reply_to_message?.from) === true });
+
+    return [...byId.values()].sort((a, b) => {
+      const aSeen = Date.parse(a.lastSeenAt || "") || 0;
+      const bSeen = Date.parse(b.lastSeenAt || "") || 0;
+      return bSeen - aSeen || a.displayName.localeCompare(b.displayName);
+    });
+  }
+
+  resolveInviteTarget(message, target) {
+    const value = String(target || "").trim();
+    const known = this.listKnownChatPeople(message);
+    const replied = this.describeTelegramUser(message?.reply_to_message?.from || {});
+
+    if (!value) {
+      if (replied.userId) {
+        const match = known.find((person) => person.userId === replied.userId) || replied;
+        return { userId: replied.userId, displayName: match.displayName || replied.displayName };
+      }
+      throw new Error("Usage: /invite <user-id|@username> [owner|editor|observer], or reply to someone with /invite [role]");
+    }
+
+    if (/^\d+$/.test(value)) {
+      const match = known.find((person) => person.userId === value);
+      return { userId: value, displayName: match?.displayName || value };
+    }
+
+    const normalized = value.replace(/^@/, "").trim().toLowerCase();
+    const byUsername = known.filter((person) => String(person.usernameHandle || "").trim().toLowerCase() === normalized);
+    if (byUsername.length === 1) {
+      return { userId: byUsername[0].userId, displayName: byUsername[0].displayName || byUsername[0].userId };
+    }
+    if (byUsername.length > 1) {
+      throw new Error(`Multiple Telegram users matched @${normalized}. Use /people and invite by numeric id.`);
+    }
+    throw new Error(`Unknown Telegram user reference: ${value}. Use /people to list recent users in this chat.`);
+  }
+
   async addPendingPairing(message) {
-    const userId = String(message?.from?.id || "").trim();
-    const username = [message?.from?.username, message?.from?.first_name, message?.from?.last_name].filter(Boolean).join(" ").trim();
+    const { userId, usernameHandle, displayName } = this.describeTelegramUser(message?.from || {});
     this.state.pendingPairings[userId] = {
       userId,
-      username,
+      username: displayName,
+      usernameHandle,
+      displayName,
       chatId: String(message.chat.id),
       firstSeenAt: this.state.pendingPairings[userId]?.firstSeenAt || new Date().toISOString(),
       lastSeenAt: new Date().toISOString(),
@@ -714,14 +885,15 @@ class TelegramGateway {
   }
 
   async ensurePeerSession(message) {
-    const userId = String(message?.from?.id || "").trim();
-    const username = [message?.from?.username, message?.from?.first_name, message?.from?.last_name].filter(Boolean).join(" ").trim();
+    const { userId, usernameHandle, displayName } = this.describeTelegramUser(message?.from || {});
     const existing = this.getPeerState(userId);
     if (existing?.sessionId) {
       this.state.peers[userId] = {
         ...existing,
         chatId: String(message.chat.id),
-        username,
+        username: displayName,
+        usernameHandle,
+        displayName,
         sessions: upsertSessionHistory(existing.sessions, existing.sessionId),
         lastSeenAt: new Date().toISOString(),
         lastMessageId: message.message_id
@@ -744,7 +916,9 @@ class TelegramGateway {
     this.state.peers[userId] = {
       sessionId: session.id,
       chatId: String(message.chat.id),
-      username,
+      username: displayName,
+      usernameHandle,
+      displayName,
       sessions: upsertSessionHistory([], session.id),
       linkedAt: new Date().toISOString(),
       lastSeenAt: new Date().toISOString(),
@@ -773,7 +947,9 @@ class TelegramGateway {
       ...previous,
       sessionId: session.id,
       chatId: String(message.chat.id),
-      username: [message?.from?.username, message?.from?.first_name, message?.from?.last_name].filter(Boolean).join(" ").trim(),
+      username: this.describeTelegramUser(message?.from || {}).displayName,
+      usernameHandle: this.describeTelegramUser(message?.from || {}).usernameHandle,
+      displayName: this.describeTelegramUser(message?.from || {}).displayName,
       sessions: upsertSessionHistory(previous.sessions, session.id),
       linkedAt: new Date().toISOString(),
       lastSeenAt: new Date().toISOString(),
@@ -804,7 +980,9 @@ class TelegramGateway {
       ...previous,
       sessionId: session.id,
       chatId: String(message.chat.id),
-      username: [message?.from?.username, message?.from?.first_name, message?.from?.last_name].filter(Boolean).join(" ").trim(),
+      username: this.describeTelegramUser(message?.from || {}).displayName,
+      usernameHandle: this.describeTelegramUser(message?.from || {}).usernameHandle,
+      displayName: this.describeTelegramUser(message?.from || {}).displayName,
       sessions: upsertSessionHistory(previous.sessions, session.id),
       linkedAt: previous.linkedAt || new Date().toISOString(),
       lastSeenAt: new Date().toISOString(),
@@ -928,7 +1106,9 @@ class TelegramGateway {
       id: requestId,
       chatId: String(message.chat.id),
       userId: String(message?.from?.id || ""),
-      username: [message?.from?.username, message?.from?.first_name, message?.from?.last_name].filter(Boolean).join(" ").trim(),
+      username: this.describeTelegramUser(message?.from || {}).displayName,
+      usernameHandle: this.describeTelegramUser(message?.from || {}).usernameHandle,
+      displayName: this.describeTelegramUser(message?.from || {}).displayName,
       sessionId: String(sessionId || "").trim(),
       text: String(promptText || "").trim(),
       runtimeProfile: String(project?.runtimeProfile || "").trim(),
@@ -1152,6 +1332,30 @@ class TelegramGateway {
       return;
     }
 
+    if (text === "/whoami") {
+      const { project } = await this.bindSharedRoomForMessage(message, sessionId);
+      const invites = project?.enabled ? await listSharedInvites(sessionCwd).catch(() => []) : [];
+      const member = Array.isArray(project?.members)
+        ? project.members.find((entry) => String(entry?.id || "").trim() === userId) || null
+        : null;
+      await this.sendMessage(
+        message.chat.id,
+        formatTelegramWhoamiMarkup({ message, member, invites, sharedEnabled: project?.enabled === true }),
+        message.message_id
+      );
+      return;
+    }
+
+    if (text === "/people") {
+      const { project } = await this.bindSharedRoomForMessage(message, sessionId);
+      await this.sendMessage(
+        message.chat.id,
+        formatTelegramPeopleMarkup({ people: this.listKnownChatPeople(message), project }),
+        message.message_id
+      );
+      return;
+    }
+
     if (text === "/status") {
       await this.sendMessage(
         message.chat.id,
@@ -1195,6 +1399,21 @@ class TelegramGateway {
       return;
     }
 
+    if (text === "/events") {
+      const { session, project } = await this.bindSharedRoomForMessage(message, sessionId);
+      if (!project?.enabled) {
+        await this.sendMessage(message.chat.id, "This project is not shared.", message.message_id);
+        return;
+      }
+      try {
+        const events = await listSharedEvents(session.cwd || this.cwd, 12);
+        await this.sendMessage(message.chat.id, formatTelegramEventsMarkup(events), message.message_id);
+      } catch (error) {
+        await this.sendMessage(message.chat.id, escapeTelegramHtml(error instanceof Error ? error.message : String(error)), message.message_id);
+      }
+      return;
+    }
+
     if (text === "/tasks") {
       const { session, project } = await this.bindSharedRoomForMessage(message, sessionId);
       if (!project?.enabled) {
@@ -1316,20 +1535,18 @@ class TelegramGateway {
         await this.sendMessage(message.chat.id, "This project is not shared.", message.message_id);
         return;
       }
-      const { userId: nextUserId, role } = parseInviteCommand(text);
-      if (!nextUserId) {
-        await this.sendMessage(message.chat.id, "Usage: /invite <user-id> [owner|editor|observer]", message.message_id);
-        return;
-      }
+      const { target, role } = parseInviteCommand(text);
       try {
+        const inviteTarget = this.resolveInviteTarget(message, target);
         const result = await createSharedInvite(
           session.cwd || this.cwd,
-          { id: nextUserId, role, name: nextUserId, paired: true },
+          { id: inviteTarget.userId, role, name: inviteTarget.displayName || inviteTarget.userId, paired: true },
           { actorId: userId, actorName: peer?.username || [message?.from?.first_name, message?.from?.last_name].filter(Boolean).join(" ").trim() || userId }
         );
         await this.sendMessage(
           message.chat.id,
-          `Created pending invite <code>${escapeTelegramHtml(result.invite.id)}</code> for <code>${escapeTelegramHtml(result.invite.memberId)}</code> <i>(${escapeTelegramHtml(result.invite.role)})</i>`,
+          `Created pending invite <code>${escapeTelegramHtml(result.invite.id)}</code> for <code>${escapeTelegramHtml(result.invite.memberId)}</code> <i>(${escapeTelegramHtml(result.invite.role)})</i>
+Ask them to run <code>/whoami</code> and then <code>/accept-invite ${escapeTelegramHtml(result.invite.id)}</code>.`,
           message.message_id
         );
       } catch (error) {

package/src/self-awareness.js

@@ -98,6 +98,223 @@ function buildProjectMapSummary({ entries = [], packageJson = null, sharedProjec
   };
 }
 
+function collectSources(...groups) {
+  return [...new Set(groups.flat().filter(Boolean))];
+}
+
+function commandEntry(id, summary, commands = [], options = {}) {
+  return {
+    id,
+    summary,
+    commands,
+    surfaces: options.surfaces || ["shell", "tui", "telegram"],
+    keywords: options.keywords || [id],
+    sources: options.sources || []
+  };
+}
+
+function capabilityEntry(id, summary, options = {}) {
+  return {
+    id,
+    summary,
+    keywords: options.keywords || [id],
+    sources: options.sources || []
+  };
+}
+
+function workflowEntry(id, summary, steps = [], options = {}) {
+  return {
+    id,
+    summary,
+    steps,
+    keywords: options.keywords || [id],
+    sources: options.sources || []
+  };
+}
+
+function buildCommandRegistry({ sourceHints = {}, sharedRoom = {} } = {}) {
+  return [
+    commandEntry("share-project", "Enable shared-project mode in the current repo and create Roundtable state files.", [
+      "waterbrother project share",
+      "/share-project"
+    ], { keywords: ["share project", "shared project", "enable roundtable", "enable shared room"], sources: [sourceHints.roundtableDocs, sourceHints.sharedState] }),
+    commandEntry("room-status", "Inspect the shared room, recent events, members, invites, tasks, and runtime.", [
+      "waterbrother room status",
+      "waterbrother room events",
+      "/room",
+      "/events"
+    ], { keywords: ["roundtable", "shared room", "room status", "events"], sources: [sourceHints.roundtableDocs, sourceHints.sharedState] }),
+    commandEntry("room-membership", "Manage shared-room invites and membership.", [
+      "waterbrother room invite <member-id> [owner|editor|observer]",
+      "waterbrother room invite accept <invite-id>",
+      "/invite <user-id|@username> [owner|editor|observer]",
+      "/accept-invite <invite-id>",
+      "/whoami",
+      "/people"
+    ], { keywords: ["invite", "partner", "teammate", "collaborator", "member", "accept invite"], sources: [sourceHints.roundtableDocs, sourceHints.telegramDocs, sourceHints.sharedState] }),
+    commandEntry("room-mode", "Set whether a shared room is chatting, planning, or executing.", [
+      "waterbrother room mode <chat|plan|execute>",
+      "/mode <chat|plan|execute>",
+      "/run <prompt>"
+    ], { keywords: ["room mode", "execute mode", "plan mode", "chat mode", "group execution"], sources: [sourceHints.roundtableDocs, sourceHints.telegramDocs] }),
+    commandEntry("room-operator", "Claim or release the active operator lock for shared execution.", [
+      "waterbrother room claim",
+      "waterbrother room release",
+      "/claim",
+      "/release"
+    ], { keywords: ["claim", "release", "operator", "lock", "active operator"], sources: [sourceHints.roundtableDocs, sourceHints.sharedState] }),
+    commandEntry("room-tasks", "Inspect and manage the shared Roundtable task queue.", [
+      "waterbrother room tasks",
+      "waterbrother room task add <text>",
+      "waterbrother room task assign <id> <member-id>",
+      "waterbrother room task move <id> <open|active|blocked|done>",
+      "/tasks",
+      "/task add <text>",
+      "/task assign <id> <member-id>",
+      "/task claim <id>",
+      "/task move <id> <open|active|blocked|done>"
+    ], { keywords: ["task", "tasks", "backlog", "assign task", "roundtable task"], sources: [sourceHints.roundtableDocs, sourceHints.sharedState] }),
+    commandEntry("new-project", "Create a new project and switch the live session into it.", [
+      "/new-project <name>",
+      "/desktop",
+      "/use <path>"
+    ], { keywords: ["new project", "make project", "create project", "desktop project"], sources: [sourceHints.readme, sourceHints.telegramDocs] }),
+    commandEntry("runtime-profiles", "Inspect or select named runtime presets for local and shared execution.", [
+      "waterbrother runtime-profiles list",
+      "waterbrother room runtime [name|clear]",
+      "/runtime-profiles",
+      "/room-runtime <name|clear>"
+    ], { keywords: ["runtime profile", "runtime profiles", "provider preset", "shared room runtime"], sources: [sourceHints.readme, sourceHints.roundtableDocs] }),
+    commandEntry("telegram-gateway", "Inspect and run the Telegram messaging gateway.", [
+      "waterbrother gateway status",
+      "waterbrother gateway run telegram",
+      "waterbrother gateway stop",
+      "/gateway"
+    ], { keywords: ["telegram", "gateway", "messaging", "telegram adapter"], sources: [sourceHints.telegramDocs] }),
+    commandEntry("self-awareness", "Inspect Waterbrother's own repo/runtime understanding.", [
+      "waterbrother about",
+      "waterbrother capabilities",
+      "waterbrother project-map",
+      "waterbrother state",
+      "/about",
+      "/capabilities",
+      "/project-map",
+      "/state"
+    ], { keywords: ["about", "capabilities", "state", "project map", "self awareness", "what are you"], sources: [sourceHints.readme, sourceHints.commandsDocs] })
+  ];
+}
+
+function buildCapabilityRegistry({ sourceHints = {}, sharedRoom = {} } = {}) {
+  const sharedEnabled = sharedRoom.enabled === true;
+  return [
+    capabilityEntry("interactive-terminal", "Interactive terminal coding with sessions, approvals, tools, receipts, and local repo awareness.", { keywords: ["terminal", "tui", "interactive", "coding cli"], sources: [sourceHints.readme] }),
+    capabilityEntry("telegram-bridge", `Telegram messaging gateway with ${sharedEnabled ? "live TUI bridging and shared-room controls" : "pairing, remote sessions, and shared-room support when enabled"}.`, { keywords: ["telegram", "bot", "bridge", "remote control", "messaging"], sources: [sourceHints.telegramDocs] }),
+    capabilityEntry("shared-projects", `${sharedEnabled ? "Shared-project collaboration is enabled in this repo." : "Shared-project collaboration is available and currently disabled in this repo."} It uses one room, explicit roles, room modes, an operator lock, Roundtable tasks, and a shared runtime.`, { keywords: ["roundtable", "shared project", "shared room", "collaboration"], sources: [sourceHints.roundtableDocs, sourceHints.sharedState] }),
+    capabilityEntry("runtime-profiles", "Bring-your-own-model runtime switching with named runtime profiles and room-level shared runtime selection.", { keywords: ["runtime", "profiles", "provider", "model", "byom"], sources: [sourceHints.readme, sourceHints.roundtableDocs] }),
+    capabilityEntry("session-persistence", "Persisted sessions that store cwd, runtime state, and messages for local and Telegram resumes.", { keywords: ["session", "sessions", "resume", "history"], sources: [sourceHints.readme, sourceHints.sharedState] }),
+    capabilityEntry("self-awareness", "Local self-awareness generated from repo state, docs, product metadata, shared-room state, and live runtime context.", { keywords: ["self awareness", "know itself", "what are you", "harness", "code base"], sources: [sourceHints.readme, sourceHints.sharedState, sourceHints.commandsDocs] })
+  ];
+}
+
+function buildWorkflowRegistry({ sourceHints = {} } = {}) {
+  return [
+    workflowEntry("invite-partner", "Add a partner to a shared Telegram collaboration room.", [
+      "Add the human to the Telegram group/chat itself using normal Telegram controls.",
+      "Enable shared-project mode with waterbrother project share if the repo is not shared yet.",
+      "Use /people or /whoami to discover Telegram ids already seen in the room.",
+      "Create a Waterbrother shared-room invite with waterbrother room invite <member-id> [owner|editor|observer] or /invite <user-id|@username> [owner|editor|observer].",
+      "Have the invited person accept with waterbrother room invite accept <invite-id> or /accept-invite <invite-id>."
+    ], { keywords: ["invite partner", "invite teammate", "add collaborator", "join shared room"], sources: [sourceHints.roundtableDocs, sourceHints.telegramDocs, sourceHints.sharedState] }),
+    workflowEntry("make-project", "Create a new project and optionally make it collaborative.", [
+      "Use /new-project <name> in the TUI or Telegram to create a Desktop project and switch into it.",
+      "If prompted in the TUI, choose whether the new project should be shared.",
+      "Use waterbrother project share afterward if you want to enable Roundtable on an existing repo.",
+      "Set room mode and claim the operator lock before shared execution."
+    ], { keywords: ["make new project", "create project", "new project", "start project"], sources: [sourceHints.readme, sourceHints.roundtableDocs, sourceHints.telegramDocs] }),
+    workflowEntry("shared-execution", "Run shared work safely in Telegram groups.", [
+      "Use /mode execute for the shared room when the group is ready to act.",
+      "Owners or editors claim the operator lock with /claim or waterbrother room claim.",
+      "In Telegram groups, explicit execution should use /run <prompt>.",
+      "Use /events, /room, and /tasks to keep the group synchronized."
+    ], { keywords: ["shared execution", "group execute", "work together in telegram", "run in group"], sources: [sourceHints.roundtableDocs, sourceHints.telegramDocs, sourceHints.sharedState] })
+  ];
+}
+
+function summarizeRoomState(sharedRoom = {}) {
+  if (!sharedRoom.enabled) {
+    return "Shared room is off in this repo.";
+  }
+  const bits = [`Shared room is enabled in ${sharedRoom.roomMode || "chat"} mode.`];
+  if (sharedRoom.runtimeProfile) bits.push(`Room runtime profile: ${sharedRoom.runtimeProfile}.`);
+  bits.push(`Members: ${sharedRoom.memberCount || 0}, pending invites: ${sharedRoom.pendingInviteCount || 0}, tasks: ${sharedRoom.taskCount || 0}.`);
+  if (sharedRoom.activeOperator?.id) bits.push(`Active operator: ${sharedRoom.activeOperator.name || sharedRoom.activeOperator.id}.`);
+  return bits.join(" ");
+}
+
+function normalizeQuestion(text = "") {
+  return String(text || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9\s/-]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function scoreEntry(question, entry) {
+  const q = normalizeQuestion(question);
+  const qTokens = new Set(q.split(" ").filter(Boolean));
+  let score = 0;
+  for (const keyword of entry.keywords || []) {
+    const normalized = normalizeQuestion(keyword);
+    if (!normalized) continue;
+    if (q.includes(normalized)) score += Math.max(2, normalized.split(" ").length * 2);
+    const tokens = normalized.split(" ").filter(Boolean);
+    if (tokens.length > 1 && tokens.every((token) => qTokens.has(token))) {
+      score += tokens.length + 1;
+    }
+  }
+  if (entry.id && q.includes(normalizeQuestion(entry.id))) score += 2;
+  return score;
+}
+
+function findBestEntries(question, entries = [], minimumScore = 2) {
+  return entries
+    .map((entry) => ({ entry, score: scoreEntry(question, entry) }))
+    .filter((item) => item.score >= minimumScore)
+    .sort((a, b) => b.score - a.score)
+    .map((item) => item.entry);
+}
+
+function renderWorkflowAnswer(workflow, roomState, capability, commands) {
+  const lines = [workflow.summary, ...workflow.steps.map((step, index) => `${index + 1}. ${step}`)];
+  if (commands.length) {
+    lines.push("Relevant commands:");
+    for (const command of commands.slice(0, 2)) {
+      lines.push(...command.commands.map((value) => `- ${value}`));
+    }
+  }
+  if (roomState) lines.push(roomState);
+  if (capability) lines.push(`Context: ${capability.summary}`);
+  const sources = collectSources(workflow.sources, capability?.sources || [], ...commands.map((entry) => entry.sources || []));
+  if (sources.length) lines.push(`sources: ${sources.join(", ")}`);
+  return lines.join("\n");
+}
+
+function renderConceptAnswer({ subject, capability, commands = [], roomState, extra = [] }) {
+  const lines = [subject];
+  if (capability) lines.push(capability.summary);
+  if (roomState) lines.push(roomState);
+  if (commands.length) {
+    lines.push("Relevant commands:");
+    for (const entry of commands.slice(0, 3)) {
+      lines.push(...entry.commands.map((value) => `- ${value}`));
+    }
+  }
+  if (extra.length) lines.push(...extra);
+  const sources = collectSources(capability?.sources || [], ...commands.map((entry) => entry.sources || []));
+  if (sources.length) lines.push(`sources: ${sources.join(", ")}`);
+  return lines.join("\n");
+}
+
 export async function buildSelfAwarenessManifest({ cwd, runtime = {}, currentSession = null } = {}) {
   const [packageJson, readme, memoryText, roundtableText, sharedProject, product, git, entries] = await Promise.all([
     readJson(path.join(cwd, "package.json")),
@@ -117,6 +334,26 @@ export async function buildSelfAwarenessManifest({ cwd, runtime = {}, currentSes
   };
 
   const projectMap = buildProjectMapSummary({ entries, packageJson, sharedProject, product });
+  const sourceHints = {
+    readme: await exists(path.join(cwd, "README.md")) ? "README.md" : "",
+    projectMemory: await exists(path.join(cwd, "WATERBROTHER.md")) ? "WATERBROTHER.md" : "",
+    roundtable: await exists(path.join(cwd, "ROUNDTABLE.md")) ? "ROUNDTABLE.md" : "",
+    sharedState: sharedProject ? ".waterbrother/shared.json" : "",
+    telegramDocs: docsPresence.telegram ? "channels/telegram/index.html" : "",
+    roundtableDocs: docsPresence.roundtable ? "roundtable/index.html" : "",
+    commandsDocs: await exists(path.join(cwd, "commands", "index.html")) ? "commands/index.html" : ""
+  };
+  const sharedRoom = sharedProject
+    ? {
+        enabled: true,
+        roomMode: sharedProject.roomMode || "chat",
+        runtimeProfile: sharedProject.runtimeProfile || "",
+        memberCount: Array.isArray(sharedProject.members) ? sharedProject.members.length : 0,
+        pendingInviteCount: Array.isArray(sharedProject.pendingInvites) ? sharedProject.pendingInvites.length : 0,
+        taskCount: Array.isArray(sharedProject.tasks) ? sharedProject.tasks.length : 0,
+        activeOperator: sharedProject.activeOperator || null
+      }
+    : { enabled: false };
   const manifest = {
     version: 1,
     generatedAt: new Date().toISOString(),
@@ -154,17 +391,7 @@ export async function buildSelfAwarenessManifest({ cwd, runtime = {}, currentSes
       roundtableTitle: firstHeading(roundtableText) || "",
       projectMap
     },
-    sharedRoom: sharedProject
-      ? {
-          enabled: true,
-          roomMode: sharedProject.roomMode || "chat",
-          runtimeProfile: sharedProject.runtimeProfile || "",
-          memberCount: Array.isArray(sharedProject.members) ? sharedProject.members.length : 0,
-          pendingInviteCount: Array.isArray(sharedProject.pendingInvites) ? sharedProject.pendingInvites.length : 0,
-          taskCount: Array.isArray(sharedProject.tasks) ? sharedProject.tasks.length : 0,
-          activeOperator: sharedProject.activeOperator || null
-        }
-      : { enabled: false },
+    sharedRoom,
     product: product
       ? {
           name: product.name || "",
@@ -172,13 +399,18 @@ export async function buildSelfAwarenessManifest({ cwd, runtime = {}, currentSes
           surfaceCount: Array.isArray(product.surfaces) ? product.surfaces.length : 0
         }
       : null,
-    sourceHints: {
-      readme: await exists(path.join(cwd, "README.md")) ? "README.md" : "",
-      projectMemory: await exists(path.join(cwd, "WATERBROTHER.md")) ? "WATERBROTHER.md" : "",
-      roundtable: await exists(path.join(cwd, "ROUNDTABLE.md")) ? "ROUNDTABLE.md" : "",
-      sharedState: sharedProject ? ".waterbrother/shared.json" : "",
-      telegramDocs: docsPresence.telegram ? "channels/telegram/index.html" : "",
-      roundtableDocs: docsPresence.roundtable ? "roundtable/index.html" : ""
+    sourceHints,
+    knowledge: {
+      harness: {
+        surface: "waterbrother",
+        runtimeSurface: "local terminal",
+        messagingSurfaces: ["telegram"],
+        liveBridge: true,
+        sharedRoomSummary: summarizeRoomState(sharedRoom)
+      },
+      commands: buildCommandRegistry({ sourceHints, sharedRoom }),
+      capabilities: buildCapabilityRegistry({ sourceHints, sharedRoom }),
+      workflows: buildWorkflowRegistry({ sourceHints })
     }
   };
 
@@ -202,7 +434,8 @@ export function buildSelfAwarenessMemoryBlock(manifest = {}) {
     `- git branch: ${manifest.identity?.git?.branch || "none"}`,
     `- runtime: ${manifest.runtime?.provider || "unknown"}/${manifest.runtime?.model || "unknown"}`,
     `- shared room: ${manifest.sharedRoom?.enabled ? `${manifest.sharedRoom.roomMode || "chat"} mode` : "off"}`,
-    `- capabilities: ${(manifest.features?.capabilities || []).join(", ")}`
+    `- capabilities: ${(manifest.features?.capabilities || []).join(", ")}`,
+    `- harness: ${manifest.knowledge?.harness?.sharedRoomSummary || "local terminal"}`
   ];
   return lines.filter(Boolean).join("\n");
 }
@@ -210,7 +443,8 @@ export function buildSelfAwarenessMemoryBlock(manifest = {}) {
 export function formatCapabilitiesSummary(manifest = {}) {
   return JSON.stringify({
     identity: manifest.identity,
-    capabilities: manifest.features?.capabilities || [],
+    capabilities: manifest.knowledge?.capabilities || manifest.features?.capabilities || [],
+    commands: (manifest.knowledge?.commands || []).map((entry) => ({ id: entry.id, commands: entry.commands })),
     channels: manifest.features?.channels || [],
     sharedRoomEnabled: manifest.sharedRoom?.enabled === true
   }, null, 2);
@@ -239,13 +473,15 @@ export function formatAboutWaterbrother(manifest = {}) {
     manifest.sourceHints?.readme,
     manifest.sourceHints?.roundtableDocs,
     manifest.sourceHints?.telegramDocs,
-    manifest.sourceHints?.sharedState
+    manifest.sourceHints?.sharedState,
+    manifest.sourceHints?.commandsDocs
   ].filter(Boolean);
   return [
     `Waterbrother is ${manifest.identity?.description || "a local coding CLI."}`,
     `repo: ${manifest.identity?.repoName || "-"}`,
     `cwd: ${manifest.identity?.cwd || "-"}`,
     `capabilities: ${(manifest.features?.capabilities || []).join(", ") || "-"}`,
+    `harness: ${manifest.knowledge?.harness?.sharedRoomSummary || "local terminal"}`,
     sources.length ? `sources: ${sources.join(", ")}` : ""
   ].filter(Boolean).join("\n");
 }
@@ -255,121 +491,76 @@ export function resolveLocalConceptQuestion(text = "", manifest = {}) {
   const lower = input.toLowerCase();
   if (!lower) return null;
 
-  const mentionsRoundtable = /\bround[\s-]?table\b/.test(lower);
   const asksWhatIs = /^(what('| i)?s|what is|tell me about|explain)\b/.test(lower) || /\bwhat is\b/.test(lower);
-  const asksHowToUseRoundtable = mentionsRoundtable && /\b(how do i|how to|add to|join|use|set up|enable|create)\b/.test(lower);
-  const asksHowToInvitePartner = /\b(invite|add)\b/.test(lower) && /\b(partner|teammate|teammates|teammember|collaborator|member)\b/.test(lower);
-  const asksHowToShareProject = /\b(how do i|how to|share)\b/.test(lower) && /\b(this project|project)\b/.test(lower);
-  const asksHowToMakeProject = /\b(how do i|how to|make|create|start)\b/.test(lower) && /\b(new project|project)\b/.test(lower);
-  const sourcesFor = (...keys) => keys.map((key) => manifest.sourceHints?.[key]).filter(Boolean);
-  const withSources = (lines, sources = []) => [
-    ...lines,
-    ...(sources.length ? [`sources: ${sources.join(", ")}`] : [])
-  ].join("\n");
-  if (mentionsRoundtable && asksWhatIs) {
-    const sources = sourcesFor("roundtableDocs", "sharedState", "roundtable");
-    return withSources([
-      "Roundtable is Waterbrother’s shared-project collaboration model.",
-      "It ties one project to one shared room with explicit room modes, member roles, operator lock, tasks, invites, and shared runtime selection."
-    ], sources);
-  }
-
-  if (asksHowToUseRoundtable) {
-    const sources = sourcesFor("roundtableDocs", "sharedState", "roundtable");
-    return withSources([
-      "To add to Roundtable, first enable shared-project mode in the repo with `waterbrother project share`.",
-      "Then use `waterbrother room invite <member-id> [owner|editor|observer]` to create member invites, `waterbrother room tasks` / `waterbrother room task add <text>` to work the shared backlog, and `waterbrother room mode <chat|plan|execute>` plus `waterbrother room claim` when you want one operator to execute.",
-      "In Telegram, the equivalent shared-room commands are `/room`, `/invite`, `/tasks`, `/task add`, `/mode`, `/claim`, and `/accept-invite`."
-    ], sources);
-  }
-
-  if (asksHowToInvitePartner) {
-    const sources = sourcesFor("roundtableDocs", "telegramDocs", "sharedState");
-    return withSources([
-      "To collaborate with a Telegram partner, there are two separate steps.",
-      "First, add the human to the Telegram group/chat itself using normal Telegram controls.",
-      "Second, add them to the Waterbrother shared room with `waterbrother room invite <member-id> [owner|editor|observer]` or `/invite <user-id> [owner|editor|observer]`.",
-      "Then the invited person accepts with `waterbrother room invite accept <invite-id>` or `/accept-invite <invite-id>`.",
-      "If this repo is not shared yet, start with `waterbrother project share`."
-    ], sources);
-  }
-
-  if (asksHowToShareProject) {
-    const sources = sourcesFor("roundtableDocs", "sharedState");
-    return withSources([
-      "To share the current project, run `waterbrother project share` in the repo.",
-      "In an interactive terminal, Waterbrother will guide room mode, room runtime profile, and the first invite.",
-      "After that, use `waterbrother room status`, `waterbrother room invite <member-id> [owner|editor|observer]`, and `waterbrother room mode <chat|plan|execute>` to manage collaboration."
-    ], sources);
-  }
+  const asksHow = /\b(how do i|how to|use|set up|enable|create|share|join|invite|make|start|add)\b/.test(lower);
+  const asksCapabilities = /\bwhat can you do\b/.test(lower) || /\bcapabilities\b/.test(lower) || /\bwhat do you support\b/.test(lower);
+  const asksProjectMap = /\bwhat is this project\b/.test(lower) || /\bwhat repo is this\b/.test(lower) || /\bwhat codebase is this\b/.test(lower);
+  const asksIdentity = /\bwhat is waterbrother\b/.test(lower) || /\bwho are you\b/.test(lower) || /\bwhat are you\b/.test(lower);
+  const mentionsRoundtable = /\bround[\s-]?table\b/.test(lower);
+  const mentionsSharedRoom = /\bshared room\b/.test(lower) || /\bshared project\b/.test(lower);
 
-  if (asksHowToMakeProject) {
-    const sources = sourcesFor("roundtableDocs", "telegramDocs", "readme");
-    return withSources([
-      "To make a new project from the TUI, use `/new-project <name>`.",
-      "That creates a folder on `~/Desktop/<name>`, switches the live session into it, and now asks whether the new project should be shared.",
-      "From Telegram, use `/new-project <name>` to create the folder and switch the linked session there. Then use `waterbrother project share` or the TUI sharing prompt if you want collaboration enabled."
-    ], sources);
-  }
+  const commands = manifest.knowledge?.commands || buildCommandRegistry({ sourceHints: manifest.sourceHints || {}, sharedRoom: manifest.sharedRoom || {} });
+  const capabilities = manifest.knowledge?.capabilities || buildCapabilityRegistry({ sourceHints: manifest.sourceHints || {}, sharedRoom: manifest.sharedRoom || {} });
+  const workflows = manifest.knowledge?.workflows || buildWorkflowRegistry({ sourceHints: manifest.sourceHints || {} });
+  const roomState = manifest.knowledge?.harness?.sharedRoomSummary || summarizeRoomState(manifest.sharedRoom || {});
+  const matchingWorkflows = findBestEntries(input, workflows, asksHow ? 2 : 4);
+  const matchingCommands = findBestEntries(input, commands, 2);
+  const matchingCapabilities = findBestEntries(input, capabilities, 2);
 
-  if ((/\bshared project\b/.test(lower) || /\bshared room\b/.test(lower) || /\broom mode\b/.test(lower)) && asksWhatIs) {
-    const sources = sourcesFor("sharedState", "roundtableDocs", "roundtable");
-    return withSources([
-      "A shared project links the current repo to one collaboration room with explicit member roles, room mode, operator lock, tasks, invites, and shared runtime state.",
-      `Current room mode: ${manifest.sharedRoom?.roomMode || "chat"}. Shared enabled: ${manifest.sharedRoom?.enabled ? "yes" : "no"}.`
-    ], sources);
-  }
-
-  if ((/\bwhat can you do\b/.test(lower) || /\bcapabilities\b/.test(lower) || /\bwhat do you support\b/.test(lower))) {
+  if (asksCapabilities) {
     return formatCapabilitiesSummary(manifest);
   }
 
-  if ((/\bwhat is this project\b/.test(lower) || /\bwhat repo is this\b/.test(lower) || /\bwhat codebase is this\b/.test(lower))) {
+  if (asksProjectMap) {
     return formatProjectMap(manifest);
   }
 
-  if (/\bwhat is waterbrother\b/.test(lower) || /\bwho are you\b/.test(lower) || /\bwhat are you\b/.test(lower)) {
+  if (asksIdentity) {
     return formatAboutWaterbrother(manifest);
   }
 
-  if (/\btelegram\b/.test(lower) && asksWhatIs) {
-    const sources = sourcesFor("telegramDocs", "sharedState");
-    return withSources([
-      "Telegram is Waterbrother’s first live messaging adapter.",
-      "It supports pairing, live TUI bridging, shared-room commands, task operations, and room execution gating."
-    ], sources);
-  }
-
-  if ((/\bgateway\b/.test(lower) || /\bmessaging gateway\b/.test(lower)) && asksWhatIs) {
-    const sources = sourcesFor("telegramDocs", "sharedState");
-    return withSources([
-      "The gateway is Waterbrother’s channel runtime for messaging surfaces like Telegram.",
-      "It handles pairing, routing, live TUI bridging, remote sessions, shared-room commands, and delivery state."
-    ], sources);
+  if (asksWhatIs && mentionsRoundtable) {
+    return renderConceptAnswer({
+      subject: "Roundtable is Waterbrother's shared-project collaboration model.",
+      capability: matchingCapabilities[0] || capabilities.find((entry) => entry.id === "shared-projects") || null,
+      commands: matchingCommands.length ? matchingCommands : commands.filter((entry) => ["room-status", "room-membership", "room-tasks"].includes(entry.id)),
+      roomState,
+      extra: ["It ties one project to one room with explicit roles, room modes, an operator lock, Roundtable tasks, and shared runtime state."]
+    });
   }
 
-  if ((/\bruntime profile\b/.test(lower) || /\bruntime profiles\b/.test(lower)) && asksWhatIs) {
-    const sources = sourcesFor("readme", "sharedState");
-    return withSources([
-      "Runtime profiles are saved Waterbrother provider/model/runtime configurations.",
-      "A shared room can also pin a room-level runtime profile that Telegram execution inherits when present."
-    ], sources);
+  if (asksWhatIs && mentionsSharedRoom) {
+    return renderConceptAnswer({
+      subject: "A shared project links the current repo to one collaboration room with explicit shared-room state.",
+      capability: matchingCapabilities[0] || capabilities.find((entry) => entry.id === "shared-projects") || null,
+      commands: matchingCommands.length ? matchingCommands : commands.filter((entry) => ["room-status", "room-mode", "room-operator"].includes(entry.id)),
+      roomState,
+      extra: ["That shared room carries member roles, room mode, operator lock, tasks, invites, and shared runtime state."]
+    });
   }
 
-  if ((/\bapproval\b/.test(lower) || /\bapprovals\b/.test(lower)) && asksWhatIs) {
-    const sources = sourcesFor("readme", "telegramDocs");
-    return withSources([
-      "Approvals are Waterbrother’s safety gate for risky actions and scope changes.",
-      "Local TUI runs can use the normal approval flow, while Telegram fallback runs still use approval=never when no live TUI host is attached."
-    ], sources);
+  if (asksHow && matchingWorkflows.length) {
+    return renderWorkflowAnswer(
+      matchingWorkflows[0],
+      roomState,
+      matchingCapabilities[0] || null,
+      matchingCommands
+    );
   }
 
-  if ((/\bsession\b/.test(lower) || /\bsessions\b/.test(lower)) && asksWhatIs) {
-    const sources = sourcesFor("readme", "sharedState");
-    return withSources([
-      "Sessions are Waterbrother’s persisted work threads.",
-      "They store cwd, runtime state, messages, and can be resumed locally or through Telegram-linked remote control."
-    ], sources);
+  if (asksWhatIs || matchingCommands.length || matchingCapabilities.length) {
+    const subject = asksWhatIs
+      ? `Local Waterbrother context for: ${input}`
+      : "Local Waterbrother context";
+    return renderConceptAnswer({
+      subject,
+      capability: matchingCapabilities[0] || null,
+      commands: matchingCommands,
+      roomState,
+      extra: manifest.runtime?.provider || manifest.runtime?.model
+        ? [`Active runtime: ${manifest.runtime.provider || "unknown"}/${manifest.runtime.model || "unknown"}.`]
+        : []
+    });
   }
 
   return null;

package/src/shared-project.js

@@ -456,6 +456,17 @@ export async function listSharedInvites(cwd) {
   return project.pendingInvites || [];
 }
 
+export async function listSharedEvents(cwd, limit = 12) {
+  const project = await loadSharedProject(cwd);
+  requireSharedProject(project);
+  const max = Number.isFinite(Number(limit)) && Number(limit) > 0 ? Math.max(1, Math.floor(Number(limit))) : 12;
+  return Array.isArray(project.recentEvents)
+    ? [...project.recentEvents]
+        .sort((a, b) => String(b.createdAt || "").localeCompare(String(a.createdAt || "")))
+        .slice(0, max)
+    : [];
+}
+
 export async function upsertSharedMember(cwd, member = {}, options = {}) {
   const existing = await loadSharedProject(cwd);
   requireOwner(existing, options.actorId);