@tritard/waterbrother 0.16.32 → 0.16.34

package/README.md

@@ -273,6 +273,19 @@ Shared project foundation is now live:
 - shared project metadata lives in `.waterbrother/shared.json`
 - human collaboration notes live in `ROUNDTABLE.md`
 
+Waterbrother self-awareness is now live:
+- `waterbrother about`
+- `waterbrother capabilities`
+- `waterbrother project-map`
+- `waterbrother state`
+- interactive:
+  - `/about`
+  - `/capabilities`
+  - `/project-map`
+  - `/state`
+- Waterbrother now writes `.waterbrother/self-awareness.json`
+- local questions like `what is roundtable?` are answered from repo state before generic model fallback
+
 Current Telegram behavior:
 - if the TUI is open, Telegram prompts are injected into the live TUI session and the work is visible in the terminal
 - if no live TUI session is attached, Telegram falls back to a remote run with `approval=never`
@@ -283,6 +296,8 @@ Current Telegram behavior:
 - 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
 - `/room` now includes pending invite count plus task ownership summaries
+- local `/status` now includes `sharedRoom` with pending invites, task ownership summary, and recent task activity
+- Telegram now posts a Roundtable ownership notice when shared task ownership changes via assign/claim/move
 - shared Telegram execution only runs when the shared room is in `execute` mode
 - room administration is owner-only, and only owners/editors can hold the operator lock
 - `/room` status now shows the active executor surface plus provider/model/runtime identity

package/package.json

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

package/src/agent.js

@@ -33,6 +33,10 @@ When you use tools:
   - cite the specific files or directories inspected
   - prefer concise subsystem summaries over long essays
   - do not offer a follow-up options menu unless asked
+- For questions about Waterbrother itself, Roundtable, Telegram integration, or the current local repo:
+  - answer from local project state, project memory, and repo files first
+  - do not ask generic clarification questions if the answer is already present locally
+  - if you read local files to answer, name the specific files you used
 - For simple file or folder listing requests:
   - return a direct literal list unless the user asked for categorization or commentary
   - keep the response compact and avoid editorial summaries

package/src/cli.js

@@ -57,6 +57,16 @@ import { runQualityChecks, formatQualityFindings, buildQualityFixPrompt } from "
 import { scanForInitiatives, formatInitiatives, buildInitiativeFixPrompt } from "./initiative.js";
 import { formatPlanForDisplay } from "./planner.js";
 import { parseCharterFromGoal, runExperimentLoop, formatExperimentSummary, gitReturnToBranch } from "./experiment.js";
+import {
+  buildSelfAwarenessManifest,
+  buildSelfAwarenessMemoryBlock,
+  formatAboutWaterbrother,
+  formatCapabilitiesSummary,
+  formatProjectMap,
+  formatSelfState,
+  resolveLocalConceptQuestion,
+  saveSelfAwarenessManifest
+} from "./self-awareness.js";
 import {
   addSharedTask,
   acceptSharedInvite,
@@ -100,6 +110,10 @@ const INTERACTIVE_COMMANDS = [
   { name: "/exit", description: "Exit interactive mode" },
   { name: "/quit", description: "Exit interactive mode" },
   { name: "/status", description: "Show runtime state" },
+  { name: "/about", description: "Show Waterbrother self-description from local state" },
+  { name: "/capabilities", description: "Show Waterbrother capabilities from local state" },
+  { name: "/project-map", description: "Show repo/codebase map from local state" },
+  { name: "/state", description: "Show full Waterbrother self-awareness state" },
   { name: "/whoami", description: "Show current operator identity and behavior" },
   { name: "/session", description: "Show current session metadata" },
   { name: "/sessions", description: "List recent sessions" },
@@ -317,6 +331,10 @@ Usage:
   waterbrother room mode <chat|plan|execute>
   waterbrother room claim
   waterbrother room release
+  waterbrother about
+  waterbrother capabilities
+  waterbrother project-map
+  waterbrother state
   waterbrother mcp list
   waterbrother commit [--push]
   waterbrother pr [--branch=<name>]
@@ -1875,6 +1893,18 @@ async function readProjectMemory(cwd) {
   };
 }
 
+async function refreshSelfAwareness(context, currentSession = null) {
+  const manifest = await buildSelfAwarenessManifest({
+    cwd: context.cwd,
+    runtime: context.runtime,
+    currentSession
+  });
+  context.runtime.selfAwareness = manifest;
+  context.runtime.selfAwarenessBlock = buildSelfAwarenessMemoryBlock(manifest);
+  await saveSelfAwarenessManifest(context.cwd, manifest).catch(() => {});
+  return manifest;
+}
+
 async function initProjectMemory(cwd) {
   const memoryPath = getProjectMemoryPath(cwd);
   try {
@@ -2652,10 +2682,23 @@ function buildRoomStatusPayload(project, runtime = null, currentSession = null)
     const assignee = String(task?.assignedTo || "").trim() || "unassigned";
     taskSummary.byAssignee[assignee] = (taskSummary.byAssignee[assignee] || 0) + 1;
   }
+  const recentActivity = tasks
+    .flatMap((task) => (Array.isArray(task.history) ? task.history.map((entry) => ({
+      taskId: task.id,
+      taskText: task.text,
+      type: entry.type,
+      text: entry.text,
+      actorId: entry.actorId || "",
+      actorName: entry.actorName || "",
+      createdAt: entry.createdAt || ""
+    })) : []))
+    .sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)))
+    .slice(0, 5);
   return {
     ...project,
     pendingInviteCount: Array.isArray(project.pendingInvites) ? project.pendingInvites.length : 0,
     taskSummary,
+    recentActivity,
     executor: {
       surface: "local-tui",
       roomRuntimeProfile: project.runtimeProfile || "",
@@ -3830,6 +3873,54 @@ async function runProjectCommand(positional, { cwd = process.cwd(), asJson = fal
   throw new Error("Usage: waterbrother project share|unshare");
 }
 
+async function runSelfAwarenessCommand(positional, { cwd = process.cwd(), asJson = false, runtime = null, currentSession = null } = {}) {
+  const sub = String(positional[0] || "state").trim().toLowerCase();
+  const manifest = await buildSelfAwarenessManifest({ cwd, runtime: runtime || {}, currentSession });
+  await saveSelfAwarenessManifest(cwd, manifest).catch(() => {});
+
+  if (sub === "about") {
+    const payload = { ok: true, about: formatAboutWaterbrother(manifest), manifest };
+    if (asJson) {
+      printData(payload, true);
+      return;
+    }
+    console.log(payload.about);
+    return;
+  }
+
+  if (sub === "capabilities") {
+    const payload = { ok: true, manifest };
+    if (asJson) {
+      printData(payload, true);
+      return;
+    }
+    console.log(formatCapabilitiesSummary(manifest));
+    return;
+  }
+
+  if (sub === "project-map") {
+    const payload = { ok: true, manifest };
+    if (asJson) {
+      printData(payload, true);
+      return;
+    }
+    console.log(formatProjectMap(manifest));
+    return;
+  }
+
+  if (sub === "state") {
+    const payload = { ok: true, manifest };
+    if (asJson) {
+      printData(payload, true);
+      return;
+    }
+    console.log(formatSelfState(manifest));
+    return;
+  }
+
+  throw new Error("Usage: waterbrother about|capabilities|project-map|state");
+}
+
 async function runRoomCommand(positional, { cwd = process.cwd(), asJson = false, runtime = null, currentSession = null, agent = null, context = null } = {}) {
   const sub = String(positional[1] || "status").trim().toLowerCase();
   const operator = getLocalOperatorIdentity();
@@ -5174,6 +5265,23 @@ async function runTextTurnInteractive({
   spinnerLabel = "thinking...",
   extraExecutionContext = null
 }) {
+  await refreshSelfAwareness(context, currentSession).catch(() => {});
+  const refreshedMemoryParts = [
+    context.runtime.selfAwarenessBlock || "",
+    context.runtime.projectMemory?.promptText || "",
+    context.runtime.episodicMemory || "",
+    context.runtime.product ? buildProductContext(context.runtime.product) : ""
+  ].filter(Boolean);
+  if (refreshedMemoryParts.length > 0) {
+    agent.setMemory(refreshedMemoryParts.join("\n\n"));
+  }
+  const localConceptAnswer = resolveLocalConceptQuestion(promptText, context.runtime.selfAwareness);
+  if (localConceptAnswer) {
+    printAssistantOutput(localConceptAnswer);
+    await saveCurrentSession(currentSession, agent);
+    return true;
+  }
+
   const readOnlyRoots = extractExplicitReadOnlyRoots(promptText, context.cwd);
   const writeRoots = extractExplicitWriteRoots(promptText, context.cwd);
   const effectivePromptText = maybeRewriteExplicitInspectionPrompt(promptText, readOnlyRoots);
@@ -6449,7 +6557,9 @@ async function promptLoop(agent, session, context) {
   } catch {}
 
   // Combine all memory sources
+  await refreshSelfAwareness(context, currentSession).catch(() => {});
   const memoryParts = [
+    context.runtime.selfAwarenessBlock || "",
     context.runtime.projectMemory?.promptText || "",
     context.runtime.episodicMemory || "",
     context.runtime.product ? buildProductContext(context.runtime.product) : ""
@@ -7557,7 +7667,8 @@ Be concrete about surfaces — name actual pages/flows. Choose the best stack fo
             sessionApprovals: approvals,
             sessionApprovalsSummary: formatSessionApprovalsSummary(approvals),
             messageCount: agent.getSessionMessages().length,
-            mcp: mcpStatus
+            mcp: mcpStatus,
+            sharedRoom: await loadSharedProject(context.cwd).then((project) => buildRoomStatusPayload(project, context.runtime, currentSession)).catch(() => ({ enabled: false }))
           },
           null,
           2
@@ -7566,6 +7677,42 @@ Be concrete about surfaces — name actual pages/flows. Choose the best stack fo
       continue;
     }
 
+    if (line === "/about") {
+      try {
+        await runSelfAwarenessCommand(["about"], { cwd: context.cwd, asJson: false, runtime: context.runtime, currentSession });
+      } catch (error) {
+        console.log(`about failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      continue;
+    }
+
+    if (line === "/capabilities") {
+      try {
+        await runSelfAwarenessCommand(["capabilities"], { cwd: context.cwd, asJson: false, runtime: context.runtime, currentSession });
+      } catch (error) {
+        console.log(`capabilities failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      continue;
+    }
+
+    if (line === "/project-map") {
+      try {
+        await runSelfAwarenessCommand(["project-map"], { cwd: context.cwd, asJson: false, runtime: context.runtime, currentSession });
+      } catch (error) {
+        console.log(`project-map failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      continue;
+    }
+
+    if (line === "/state") {
+      try {
+        await runSelfAwarenessCommand(["state"], { cwd: context.cwd, asJson: false, runtime: context.runtime, currentSession });
+      } catch (error) {
+        console.log(`state failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      continue;
+    }
+
     if (line === "/session") {
       const mcpStatus = agent.toolRuntime.getMcpStatus();
       const approvals = agent.toolRuntime.getSessionApprovals ? agent.toolRuntime.getSessionApprovals() : { allowShellCommands: [], allowTools: [] };
@@ -9989,6 +10136,61 @@ export async function runCli(argv) {
   let { userConfig, config } = await loadConfigLayers(startupCwd);
   let runtime = resolveRuntimeConfig(config, configOverrides);
   runtime.autoCompactThreshold = normalizeAutoCompactThreshold(runtime.autoCompactThreshold);
+  const knownCommands = new Set([
+    "chat",
+    "exec",
+    "review",
+    "resume",
+    "config",
+    "sessions",
+    "models",
+    "runtime-profiles",
+    "channels",
+    "project",
+    "about",
+    "capabilities",
+    "project-map",
+    "state",
+    "room",
+    "gateway",
+    "mcp",
+    "onboarding",
+    "vision",
+    "update",
+    "doctor",
+    "commit",
+    "pr"
+  ]);
+  const canReadPromptFromStdin =
+    Boolean(flags.pipe) ||
+    command === "chat" ||
+    command === "exec" ||
+    command === "review" ||
+    command === "resume" ||
+    (positional.length > 0 && !knownCommands.has(command));
+  let earlyPrompt = "";
+  if (flags.prompt) {
+    earlyPrompt = String(flags.prompt).trim();
+  } else if (command === "chat" || command === "exec" || command === "review") {
+    earlyPrompt = positional.slice(1).join(" ").trim();
+  } else if (positional.length > 0 && !knownCommands.has(command)) {
+    earlyPrompt = positional.join(" ").trim();
+  } else if (!process.stdin.isTTY && canReadPromptFromStdin) {
+    earlyPrompt = (await readStdinIfNeeded()) || "";
+  }
+  if (earlyPrompt) {
+    const earlyManifest = await buildSelfAwarenessManifest({ cwd: startupCwd, runtime });
+    const earlyLocalConceptAnswer = resolveLocalConceptQuestion(earlyPrompt, earlyManifest);
+    if (earlyLocalConceptAnswer) {
+      await saveSelfAwarenessManifest(startupCwd, earlyManifest).catch(() => {});
+      if (asJson) {
+        printData({ content: earlyLocalConceptAnswer, usage: null, sessionId: null, model: runtime.model || "" }, true);
+      } else {
+        console.log(earlyLocalConceptAnswer);
+      }
+      return;
+    }
+  }
 
   if (command === "doctor") {
     await runDoctorCommand({ runtime, cwd: startupCwd, asJson });
@@ -10015,6 +10217,11 @@ export async function runCli(argv) {
     return;
   }
 
+  if (command === "about" || command === "capabilities" || command === "project-map" || command === "state") {
+    await runSelfAwarenessCommand([command], { cwd: startupCwd, asJson, runtime });
+    return;
+  }
+
   if (command === "room") {
     await runRoomCommand(positional, { cwd: startupCwd, asJson, runtime });
     return;
@@ -10173,6 +10380,16 @@ export async function runCli(argv) {
   });
 
   agent.hydrateFromSessionMessages(session.messages || []);
+  const initialSelfAwareness = await buildSelfAwarenessManifest({ cwd, runtime, currentSession: session });
+  runtime.selfAwareness = initialSelfAwareness;
+  runtime.selfAwarenessBlock = buildSelfAwarenessMemoryBlock(initialSelfAwareness);
+  await saveSelfAwarenessManifest(cwd, initialSelfAwareness).catch(() => {});
+  agent.setMemory(
+    [
+      runtime.selfAwarenessBlock || "",
+      runtime.projectMemory?.promptText || ""
+    ].filter(Boolean).join("\n\n")
+  );
 
   if (flags["print-session-id"]) {
     console.log(session.id);
@@ -10182,33 +10399,7 @@ export async function runCli(argv) {
   const pipeMode = Boolean(flags.pipe);
   const outputFormat = String(flags["output-format"] || "text").toLowerCase();
   const machineReadableOutput = outputFormat === "json" || outputFormat === "stream-json";
-  const knownCommands = new Set([
-    "chat",
-    "exec",
-    "review",
-    "resume",
-    "config",
-    "sessions",
-    "models",
-    "channels",
-    "gateway",
-    "mcp",
-    "onboarding",
-    "vision",
-    "update",
-    "doctor",
-    "commit",
-    "pr"
-  ]);
-  const canReadPromptFromStdin =
-    pipeMode ||
-    command === "chat" ||
-    command === "exec" ||
-    command === "review" ||
-    command === "resume" ||
-    (positional.length > 0 && !knownCommands.has(command));
-
-  let oneShotPrompt = "";
+  let oneShotPrompt = earlyPrompt || "";
   if (promptFlag) {
     oneShotPrompt = promptFlag;
   } else if (command === "chat" || command === "exec" || command === "review") {
@@ -10219,9 +10410,11 @@ export async function runCli(argv) {
   } else if (positional.length > 0 && !knownCommands.has(command)) {
     oneShotPrompt = positional.join(" ").trim();
   } else if (!process.stdin.isTTY && canReadPromptFromStdin) {
-    const stdinPrompt = await readStdinIfNeeded();
-    if (stdinPrompt) {
-      oneShotPrompt = stdinPrompt;
+    if (!oneShotPrompt) {
+      const stdinPrompt = await readStdinIfNeeded();
+      if (stdinPrompt) {
+        oneShotPrompt = stdinPrompt;
+      }
     }
   }
 
@@ -10260,6 +10453,15 @@ export async function runCli(argv) {
   const exactShellCommand = extractExactShellCommand(oneShotPrompt);
 
   if (oneShotPrompt) {
+    const localConceptAnswer = resolveLocalConceptQuestion(oneShotPrompt, runtime.selfAwareness);
+    if (localConceptAnswer) {
+      if (outputFormat === "json") {
+        console.log(JSON.stringify({ content: localConceptAnswer, usage: null, sessionId: session.id, model: agent.getModel() }, null, 2));
+      } else {
+        console.log(sanitizeTerminalText(localConceptAnswer));
+      }
+      return;
+    }
     if (exactShellCommand) {
       await runExactShellTurn({
         agent,

package/src/gateway.js

@@ -411,6 +411,23 @@ function formatTelegramTaskHistoryMarkup(result) {
   return lines.join("\n");
 }
 
+function buildTaskOwnershipNotice(task, { action = "updated", previousAssignee = "", previousState = "" } = {}) {
+  if (!task) return "";
+  const bits = [
+    "<b>Roundtable update</b>",
+    `<code>${escapeTelegramHtml(task.id || "")}</code> ${escapeTelegramHtml(task.text || "")}`
+  ];
+  if (action === "assign") {
+    bits.push(`owner: <code>${escapeTelegramHtml(previousAssignee || "unassigned")}</code> → <code>${escapeTelegramHtml(task.assignedTo || "unassigned")}</code>`);
+  } else if (action === "claim") {
+    bits.push(`claimed by <code>${escapeTelegramHtml(task.assignedTo || "unassigned")}</code>`);
+  } else if (action === "move") {
+    bits.push(`state: <code>${escapeTelegramHtml(previousState || "open")}</code> → <code>${escapeTelegramHtml(task.state || "open")}</code>`);
+    if (task.assignedTo) bits.push(`owner: <code>${escapeTelegramHtml(task.assignedTo)}</code>`);
+  }
+  return bits.join("\n");
+}
+
 function classifyTelegramGroupIntent(text = "") {
   const normalized = String(text || "").trim();
   const lower = normalized.toLowerCase();
@@ -1395,8 +1412,11 @@ class TelegramGateway {
         return;
       }
       try {
+        const before = (project?.tasks || []).find((task) => task.id === taskId) || null;
         const result = await moveSharedTask(session.cwd || this.cwd, taskId, state, { actorId: userId });
         await this.sendMessage(message.chat.id, `Moved shared task <code>${escapeTelegramHtml(result.task.id)}</code> to <code>${escapeTelegramHtml(result.task.state)}</code>`, message.message_id);
+        const notice = buildTaskOwnershipNotice(result.task, { action: "move", previousAssignee: before?.assignedTo || "", previousState: before?.state || "" });
+        if (notice) await this.sendMessage(message.chat.id, notice, null, { parseMode: "HTML" });
       } catch (error) {
         await this.sendMessage(message.chat.id, escapeTelegramHtml(error instanceof Error ? error.message : String(error)), message.message_id);
       }
@@ -1415,8 +1435,11 @@ class TelegramGateway {
         return;
       }
       try {
+        const before = (project?.tasks || []).find((task) => task.id === taskId) || null;
         const result = await assignSharedTask(session.cwd || this.cwd, taskId, memberId, { actorId: userId });
         await this.sendMessage(message.chat.id, `Assigned shared task <code>${escapeTelegramHtml(result.task.id)}</code> to <code>${escapeTelegramHtml(memberId)}</code>`, message.message_id);
+        const notice = buildTaskOwnershipNotice(result.task, { action: "assign", previousAssignee: before?.assignedTo || "" });
+        if (notice) await this.sendMessage(message.chat.id, notice, null, { parseMode: "HTML" });
       } catch (error) {
         await this.sendMessage(message.chat.id, escapeTelegramHtml(error instanceof Error ? error.message : String(error)), message.message_id);
       }
@@ -1482,6 +1505,8 @@ class TelegramGateway {
       try {
         const result = await claimSharedTask(session.cwd || this.cwd, taskId, { actorId: userId });
         await this.sendMessage(message.chat.id, `Claimed shared task <code>${escapeTelegramHtml(result.task.id)}</code>`, message.message_id);
+        const notice = buildTaskOwnershipNotice(result.task, { action: "claim" });
+        if (notice) await this.sendMessage(message.chat.id, notice, null, { parseMode: "HTML" });
       } catch (error) {
         await this.sendMessage(message.chat.id, escapeTelegramHtml(error instanceof Error ? error.message : String(error)), message.message_id);
       }

package/src/self-awareness.js

@@ -0,0 +1,291 @@
+import { execFile as execFileCb } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { loadProduct } from "./product.js";
+import { loadSharedProject } from "./shared-project.js";
+
+const execFile = promisify(execFileCb);
+const SELF_AWARENESS_FILE = path.join(".waterbrother", "self-awareness.json");
+
+async function readJson(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+async function readText(filePath) {
+  try {
+    return await fs.readFile(filePath, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function firstHeading(markdown = "") {
+  const match = String(markdown || "").match(/^#\s+(.+)$/m);
+  return match ? String(match[1] || "").trim() : "";
+}
+
+async function detectGit(cwd) {
+  try {
+    const { stdout: root } = await execFile("git", ["rev-parse", "--show-toplevel"], { cwd, timeout: 10000 });
+    const { stdout: branch } = await execFile("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd, timeout: 10000 });
+    const { stdout: status } = await execFile("git", ["status", "--short"], { cwd, timeout: 10000, maxBuffer: 1024 * 1024 });
+    return {
+      root: String(root || "").trim(),
+      branch: String(branch || "").trim(),
+      dirty: Boolean(String(status || "").trim())
+    };
+  } catch {
+    return { root: "", branch: "", dirty: false };
+  }
+}
+
+async function listTopLevelEntries(cwd) {
+  try {
+    const entries = await fs.readdir(cwd, { withFileTypes: true });
+    return entries
+      .filter((entry) => !entry.name.startsWith("."))
+      .slice(0, 14)
+      .map((entry) => ({
+        name: entry.name,
+        kind: entry.isDirectory() ? "dir" : "file"
+      }));
+  } catch {
+    return [];
+  }
+}
+
+function detectCapabilities(cwd, sharedProject, docsPresence = {}) {
+  const capabilities = [
+    "BYOM runtime profiles",
+    "provider/model switching",
+    "interactive terminal coding",
+    "session persistence",
+    "Telegram messaging gateway"
+  ];
+  if (sharedProject?.enabled) capabilities.push("Roundtable shared projects");
+  if (docsPresence.roundtable) capabilities.push("Roundtable collaboration docs");
+  if (docsPresence.telegram) capabilities.push("Telegram integration docs");
+  return capabilities;
+}
+
+function buildProjectMapSummary({ entries = [], packageJson = null, sharedProject = null, product = null }) {
+  const keyFiles = [];
+  if (packageJson?.name) keyFiles.push("package.json");
+  if (entries.some((entry) => entry.name === "README.md")) keyFiles.push("README.md");
+  if (entries.some((entry) => entry.name === "WATERBROTHER.md")) keyFiles.push("WATERBROTHER.md");
+  if (entries.some((entry) => entry.name === "ROUNDTABLE.md")) keyFiles.push("ROUNDTABLE.md");
+  if (entries.some((entry) => entry.name === "src")) keyFiles.push("src/");
+  if (entries.some((entry) => entry.name === "assets")) keyFiles.push("assets/");
+  return {
+    keyFiles,
+    shared: sharedProject?.enabled === true,
+    product: product?.name || "",
+    topLevel: entries
+  };
+}
+
+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")),
+    readText(path.join(cwd, "README.md")),
+    readText(path.join(cwd, "WATERBROTHER.md")),
+    readText(path.join(cwd, "ROUNDTABLE.md")),
+    loadSharedProject(cwd),
+    loadProduct(cwd),
+    detectGit(cwd),
+    listTopLevelEntries(cwd)
+  ]);
+
+  const docsPresence = {
+    integrations: await exists(path.join(cwd, "integrations", "index.html")),
+    roundtable: await exists(path.join(cwd, "roundtable", "index.html")),
+    telegram: await exists(path.join(cwd, "channels", "telegram", "index.html"))
+  };
+
+  const projectMap = buildProjectMapSummary({ entries, packageJson, sharedProject, product });
+  const manifest = {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    identity: {
+      name: "Waterbrother",
+      description: "Bring-your-own-model local coding CLI with sessions, approvals, messaging, and shared project collaboration.",
+      cwd,
+      repoName: packageJson?.name || path.basename(cwd),
+      readmeTitle: firstHeading(readme) || "",
+      git
+    },
+    runtime: {
+      provider: runtime.provider || "",
+      model: runtime.model || "",
+      designModel: runtime.designModel || "",
+      agentProfile: runtime.agentProfile || "",
+      runtimeProfile: currentSession?.runtimeProfile || "",
+      toolsEnabled: runtime.enableTools !== false,
+      traceMode: runtime.traceMode || "",
+      receiptMode: runtime.receiptMode || ""
+    },
+    features: {
+      capabilities: detectCapabilities(cwd, sharedProject, docsPresence),
+      docsPresence,
+      channels: ["telegram", "discord", "signal"],
+      sharedProjectEnabled: sharedProject?.enabled === true
+    },
+    project: {
+      packageName: packageJson?.name || "",
+      packageVersion: packageJson?.version || "",
+      packageType: packageJson?.type || "",
+      scripts: Object.keys(packageJson?.scripts || {}).slice(0, 10),
+      readmeTitle: firstHeading(readme) || "",
+      projectMemoryTitle: firstHeading(memoryText) || "",
+      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 },
+    product: product
+      ? {
+          name: product.name || "",
+          type: product.type || "",
+          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" : ""
+    }
+  };
+
+  return manifest;
+}
+
+export async function saveSelfAwarenessManifest(cwd, manifest) {
+  const target = path.join(cwd, SELF_AWARENESS_FILE);
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await fs.writeFile(target, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+  return target;
+}
+
+export function buildSelfAwarenessMemoryBlock(manifest = {}) {
+  const lines = [
+    "Waterbrother self-awareness",
+    `- identity: ${manifest.identity?.name || "Waterbrother"}`,
+    `- description: ${manifest.identity?.description || ""}`,
+    `- repo: ${manifest.identity?.repoName || ""}`,
+    `- cwd: ${manifest.identity?.cwd || ""}`,
+    `- 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(", ")}`
+  ];
+  return lines.filter(Boolean).join("\n");
+}
+
+export function formatCapabilitiesSummary(manifest = {}) {
+  return JSON.stringify({
+    identity: manifest.identity,
+    capabilities: manifest.features?.capabilities || [],
+    channels: manifest.features?.channels || [],
+    sharedRoomEnabled: manifest.sharedRoom?.enabled === true
+  }, null, 2);
+}
+
+export function formatProjectMap(manifest = {}) {
+  return JSON.stringify({
+    repo: manifest.identity?.repoName || "",
+    cwd: manifest.identity?.cwd || "",
+    git: manifest.identity?.git || {},
+    packageName: manifest.project?.packageName || "",
+    scripts: manifest.project?.scripts || [],
+    topLevel: manifest.project?.projectMap?.topLevel || [],
+    keyFiles: manifest.project?.projectMap?.keyFiles || [],
+    sharedProject: manifest.sharedRoom || { enabled: false },
+    product: manifest.product || null
+  }, null, 2);
+}
+
+export function formatSelfState(manifest = {}) {
+  return JSON.stringify(manifest, null, 2);
+}
+
+export function formatAboutWaterbrother(manifest = {}) {
+  const sources = [
+    manifest.sourceHints?.readme,
+    manifest.sourceHints?.roundtableDocs,
+    manifest.sourceHints?.telegramDocs,
+    manifest.sourceHints?.sharedState
+  ].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(", ") || "-"}`,
+    sources.length ? `sources: ${sources.join(", ")}` : ""
+  ].filter(Boolean).join("\n");
+}
+
+export function resolveLocalConceptQuestion(text = "", manifest = {}) {
+  const input = String(text || "").trim();
+  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);
+  if (mentionsRoundtable && asksWhatIs) {
+    const sources = [manifest.sourceHints?.roundtableDocs, manifest.sourceHints?.sharedState, manifest.sourceHints?.roundtable].filter(Boolean);
+    return [
+      "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: ${sources.join(", ")}`
+    ].join("\n");
+  }
+
+  if ((/\bwhat can you do\b/.test(lower) || /\bcapabilities\b/.test(lower) || /\bwhat do you support\b/.test(lower))) {
+    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))) {
+    return formatProjectMap(manifest);
+  }
+
+  if (/\bwhat is waterbrother\b/.test(lower) || /\bwho are you\b/.test(lower) || /\bwhat are you\b/.test(lower)) {
+    return formatAboutWaterbrother(manifest);
+  }
+
+  if (/\btelegram\b/.test(lower) && asksWhatIs) {
+    const sources = [manifest.sourceHints?.telegramDocs, manifest.sourceHints?.sharedState].filter(Boolean);
+    return [
+      "Telegram is Waterbrother’s first live messaging adapter.",
+      "It supports pairing, live TUI bridging, shared-room commands, task operations, and room execution gating.",
+      `sources: ${sources.join(", ")}`
+    ].join("\n");
+  }
+
+  return null;
+}