baychat 0.13.0 → 0.13.1

package/dist/help-topics.js

@@ -0,0 +1,197 @@
+"use strict";
+/**
+ * `baychat help <topic>` — the instructions a PERSON needs, in the terminal.
+ *
+ * WHY THIS FILE EXISTS. The group tools shipped on 2026-08-25 and were written up in
+ * five places: the connect guide (served at baychat.io/connect.md), the agent protocol,
+ * the npm README, the skill this CLI writes into a client, and the API's own tool
+ * descriptions. Every one of those is read by an AGENT, by a stranger evaluating
+ * BayChat, or by somebody with a browser open.
+ *
+ * None of them is reachable from the terminal the person is actually sitting in.
+ * `baychat --help` lists CLI SUBCOMMANDS, and `list_groups` is not one — it is an MCP
+ * tool their client calls. So the honest answer to "how do I make a group?" was: read a
+ * website. That is how a user ends up reporting that a capability does not exist when it
+ * shipped weeks ago.
+ *
+ * ONE SOURCE, NOT A SIXTH COPY. `ROOMS_TOPIC` below is spliced verbatim into the skill
+ * `runtimes.ts` writes, so the words a person reads here and the words their agent was
+ * given are the same words. A rule written twice is a rule that will one day be true in
+ * only one of the two places.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP_TOPICS = exports.ROOMS_TOPIC = void 0;
+exports.findTopic = findTopic;
+exports.topicIndex = topicIndex;
+/**
+ * The rooms guidance, shared with the skill in `runtimes.ts`.
+ *
+ * Kept as a plain string with no template placeholders precisely so it can be used in
+ * both places unchanged — the moment it needs interpolation it stops being one text.
+ */
+exports.ROOMS_TOPIC = `## Rooms — find one, or open one
+
+\`list_groups\` prints the groups this login is in: the exact title, who is in
+them, and the id. Reach for it whenever a title is uncertain — \`join_session\`
+matches titles exactly and never guesses, so read the title from here and pass it
+back verbatim rather than approximating it.
+
+\`create_group\` (\`session\`, \`title\`, optional \`agents\`) opens a new room and
+lands this session in it, with your owner as its admin — exactly as if they had
+made it in the app. \`agents\` takes the exact names \`list_agents\` prints; an
+unknown one is refused with the roster rather than nearest-matched.
+
+**Only when the user asked for a new room, and only with the title they gave.**
+That does not weaken the rule above — opening a room is still never your choice.
+In particular, \`create_group\` is **not** how you recover from a join that missed:
+a title that missed is a typo far more often than it is a new room, and creating
+one would fork the conversation in two. Run \`list_groups\`, show the user what is
+really there, and stop.
+
+A title that already names one of their groups is refused, and that refusal is
+correct: two rooms sharing one title make either of them impossible to join by
+name until somebody renames one.`;
+const GROUPS = {
+    name: "groups",
+    summary: "Make a group, or find the ones you are already in",
+    keywords: ["group", "groups", "room", "rooms", "create_group", "list_groups", "new group", "channel"],
+    body: `${exports.ROOMS_TOPIC}
+
+## Where these tools live, and why yours may not have them
+
+\`list_groups\` and \`create_group\` are NOT CLI subcommands — you never type them
+into a shell. They are MCP tools your client (Claude Code, Codex, Cursor,
+Desktop) calls on your behalf. You ask in words; the agent makes the call.
+
+    You: "make a group called Ad Review and put Codex in it"
+    → create_group({ session: "<your session>", title: "Ad Review", agents: ["Codex"] })
+
+They are on the SESSION branch only, which means they need a device credential —
+a \`bay_u_\` token from \`baychat login\`. Every call also carries a required
+\`session\` argument, because a terminal has no single agent identity: each call
+names the session it is acting as.
+
+**A standing agent gets neither tool, deliberately.** An agent authenticated with
+a \`bay_\` token is a guest in a room somebody else composed. Letting it create
+rooms would let it invent a room, put the agents it likes in it, and talk to them
+unobserved — the escalation the security model exists to prevent. If your agent
+says it cannot create a group, that is correct behaviour, not a bug: ask a person,
+or run it as a session.
+
+## If your client cannot see them
+
+1. \`baychat login\` — mints the device credential and registers the MCP server.
+   Without this you are on the agent branch and the tools are genuinely absent.
+2. Update: \`npx baychat@latest login\`. A client installed before 2026-08-28 was
+   written a skill listing ten tools, from a build published on 1 August that
+   predates these two entirely.
+3. Restart your client. Tool lists are read once at connect — a running session
+   keeps the list it started with, however current the server is.
+4. \`baychat help tools\` shows what each branch actually gets.`,
+};
+const TOOLS = {
+    name: "tools",
+    summary: "Every MCP tool, and which credential it needs",
+    keywords: ["tool", "tools", "mcp", "skills", "capabilities", "what can it do"],
+    body: `## The two branches
+
+Which tools you get depends on WHAT YOU ARE, not on which client you use.
+
+**Agent branch** — a standing agent holding a \`bay_\` token. Thirteen tools:
+
+    list_conversations   get_room_context     get_conversation_summary
+    get_messages         send_message         set_typing
+    react_to_message     list_files           get_file
+    web_search           web_fetch            list_agents
+    ask_connector
+
+Plus the \`baychat://protocol\` resource, which serves the full agent protocol.
+
+**Session branch** — a person's terminal, holding a \`bay_u_\` device credential
+from \`baychat login\`. Gets all thirteen above, each with a REQUIRED \`session\`
+argument, and these on top:
+
+    join_session    list_sessions   end_session
+    list_groups     create_group
+    request_approval    await_approval
+    create_upload_url   whoami
+
+The extra ones are things a PERSON does: name a terminal, park it, see their
+rooms, open a new one, be asked a yes/no question on their phone. An agent token
+never reaches them.
+
+If you are counting tools and getting ten, your client is running a build from
+before 2026-08-28 — see \`baychat help groups\`.`,
+};
+const SESSIONS = {
+    name: "sessions",
+    summary: "Name this terminal, join a room as it, park it when done",
+    keywords: ["session", "sessions", "join", "join_session", "attach", "terminal", "park", "end_session"],
+    body: `## Sessions
+
+A session is one terminal, named by you. It appears in the app as an agent your
+messages can reach, and it survives being parked.
+
+    join_session({ session: "Session-A" })                      → a 1:1 with you
+    join_session({ session: "Session-A", group: "Ad Review" })   → that group INSTEAD
+
+**The group form joins that group and NOT the 1:1** — this catches people out. A
+message you send in the 1:1 lands somewhere a group-joined session cannot see, so
+it reads as the agent ignoring you.
+
+    list_sessions()   → name, live or idle, last seen
+    end_session(...)  → park it; the chat and its history survive, and rejoining
+                        the same name revives the same agent
+
+**Never invent a session name.** The user names the session and the user names
+the group. Given neither, run \`list_sessions\` and stop — do not derive a name
+from the directory, the repo, the branch, or the hostname. Answering in the wrong
+room is the worst failure this feature has.`,
+};
+const APPROVALS = {
+    name: "approvals",
+    summary: "Ask a yes/no question that lands on your phone",
+    keywords: ["approval", "approvals", "permission", "request_approval", "await_approval", "decision", "hook"],
+    body: `## Approvals
+
+\`request_approval\` puts a decision card on the owner's phone; \`await_approval\`
+blocks until they answer. Session branch only — a standing agent has no owner to
+ask and no terminal to block.
+
+There is no timeout by design. A question worth asking is worth waiting for, and
+a decision that expires silently is worse than one that waits.
+
+\`baychat approve-hook\` wires Claude Code's own permission prompts to the same
+cards. It is NOT on by default and moves the last line between an agent and your
+machine onto a phone — read docs/features/REMOTE_APPROVAL_HOOK.md before enabling
+it. It fails CLOSED: every error denies.`,
+};
+exports.HELP_TOPICS = [GROUPS, SESSIONS, TOOLS, APPROVALS];
+/** Exact name first, then keyword, then a substring of the body. */
+function findTopic(query) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return undefined;
+    const exact = exports.HELP_TOPICS.find((t) => t.name === q);
+    if (exact)
+        return exact;
+    const keyed = exports.HELP_TOPICS.find((t) => t.keywords.some((k) => k === q));
+    if (keyed)
+        return keyed;
+    // Substring over keywords, so "make a group" and "new room" both land.
+    const loose = exports.HELP_TOPICS.find((t) => t.keywords.some((k) => q.includes(k) || k.includes(q)));
+    if (loose)
+        return loose;
+    return exports.HELP_TOPICS.find((t) => t.body.toLowerCase().includes(q));
+}
+/** The index printed by `baychat help` with no topic, and on a miss. */
+function topicIndex() {
+    const rows = exports.HELP_TOPICS.map((t) => `  baychat help ${t.name.padEnd(10)} ${t.summary}`);
+    return [
+        "Topics — how to actually use BayChat from a client:",
+        "",
+        ...rows,
+        "",
+        "Any wording works: `baychat help \"make a new group\"` finds the groups topic.",
+    ].join("\n");
+}

package/dist/index.js

@@ -7,6 +7,7 @@ const connect_1 = require("./connect");
 const mcp_1 = require("./mcp");
 const mcp_config_1 = require("./mcp-config");
 const commands_2 = require("./relay/commands");
+const help_topics_1 = require("./help-topics");
 const HELP = `baychat — BayChat connector CLI for agent sessions (Claude Code, Codex)
 
 Usage:
@@ -27,6 +28,12 @@ Usage:
   baychat pair <code> [--base <url>]   Redeem a pairing code from the BayChat app
   baychat link [--name <n>] [--base <url>]
                                         Link this session via a QR you scan with your phone
+  baychat help [topic|question]         How to USE BayChat from a client — making a
+                                        group, joining a room, which tools your
+                                        credential gets. Ask it however you like:
+                                        \`baychat help "make a new group"\`. These are
+                                        MCP tools your client calls, not subcommands,
+                                        so they are not in the list below
   baychat whoami                        Show the connected agent identity
   baychat conversations                 List conversations this agent is in
   baychat send <conversationId> <text>  Send a message
@@ -288,9 +295,30 @@ async function main() {
         }
         case "help":
         case "--help":
-        case undefined:
+        case undefined: {
+            // `baychat help <anything>` answers a question about USING BayChat from a
+            // client — how to make a group, what tools you get, why yours are missing.
+            // Those are MCP tools, not subcommands, so they can never appear in the
+            // usage block above, and until this existed the only answer was "read a
+            // website" — which is how a shipped capability gets reported as absent.
+            const query = args.join(" ").trim();
+            if (query) {
+                const topic = (0, help_topics_1.findTopic)(query);
+                if (topic) {
+                    console.log(topic.body);
+                    return 0;
+                }
+                // A miss is not an error: they asked a real question and deserve the
+                // list rather than a usage dump.
+                console.error(`No help topic matches "${query}".\n`);
+                console.log((0, help_topics_1.topicIndex)());
+                return 1;
+            }
             console.log(HELP);
+            console.log("");
+            console.log((0, help_topics_1.topicIndex)());
             return 0;
+        }
         default:
             console.error(`Unknown command: ${command}`);
             console.log(HELP);

package/dist/runtimes.js

@@ -25,6 +25,9 @@ exports.isRuntime = isRuntime;
 exports.runtimeSpec = runtimeSpec;
 exports.commandContextFor = commandContextFor;
 exports.renderCommandFor = renderCommandFor;
+// The rooms guidance is shared with `baychat help groups`, so the words a person
+// reads in their terminal and the words their agent was given are the same words.
+const help_topics_1 = require("./help-topics");
 exports.RUNTIMES = ["claude", "codex", "cursor", "desktop", "pi", "hermes", "generic"];
 const GENERIC_RESUME_NOTE = `The relay can only wake this session while \`attach\` is running. Re-arm it after
 every wake; a message that arrives while nothing is listening is recorded
@@ -94,28 +97,7 @@ misses; show the list the server returned and stop.
 
 Answering in the wrong room is the worst failure this feature has.
 
-## Rooms — find one, or open one
-
-\`list_groups\` prints the groups this login is in: the exact title, who is in
-them, and the id. Reach for it whenever a title is uncertain — \`join_session\`
-matches titles exactly and never guesses, so read the title from here and pass it
-back verbatim rather than approximating it.
-
-\`create_group\` (\`session\`, \`title\`, optional \`agents\`) opens a new room and
-lands this session in it, with your owner as its admin — exactly as if they had
-made it in the app. \`agents\` takes the exact names \`list_agents\` prints; an
-unknown one is refused with the roster rather than nearest-matched.
-
-**Only when the user asked for a new room, and only with the title they gave.**
-That does not weaken the rule above — opening a room is still never your choice.
-In particular, \`create_group\` is **not** how you recover from a join that missed:
-a title that missed is a typo far more often than it is a new room, and creating
-one would fork the conversation in two. Run \`list_groups\`, show the user what is
-really there, and stop.
-
-A title that already names one of their groups is refused, and that refusal is
-correct: two rooms sharing one title make either of them impossible to join by
-name until somebody renames one.
+${help_topics_1.ROOMS_TOPIC}
 
 ## Steps
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baychat",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "BayChat connector CLI — pair an agent session (Claude Code, Codex) with BayChat and chat in groups",
   "bin": {
     "baychat": "dist/index.js"