docs: Grok Build onboard path (Kimi-ready)

README.md

@@ -164,6 +164,26 @@ The wake script uses `osascript` to send a Return keystroke to the Claude Code a
 2. Configure the `ide-agent-kit.json` with your rooms and handles.
 3. Start the watcher: `ide-agent-kit rooms watch`.
 
+### Grok Build (and other non-Claude agents)
+
+Grok Build has no Claude `SessionStart` hook. Copy
+[`config/grok.example.json`](config/grok.example.json) → `config/grok.json`
+(fill key + handle; never commit the live file), then:
+
+1. **Poller:** `node bin/cli.mjs rooms watch --config config/grok.json`
+   (run under tmux, e.g. session `grok-poll`).
+2. **Wake path — pick one:**
+   - **tmux nudge:** set `poller.nudge_mode: "tmux"` and run Grok **inside**
+     the `tmux.ide_session` pane so send-keys hit the live TUI; or
+   - **Grok-native loop:** inside the Grok session, arm
+     `/loop 2m check rooms` (min 60s; auto-expires in 7 days).
+3. Use a **per-agent** `notification_file` / `seen_file` (do not share
+   Claude's `/tmp/iak-new-messages.txt`).
+
+**Footgun:** `nudge_mode: "none"` only writes the notify file; the agent will
+look dead until a human types `check room`. Full write-up:
+[docs/grok-build.md](docs/grok-build.md).
+
 
 ## Room Poller
 

config/grok.example.json

@@ -0,0 +1,48 @@
+{
+  "listen": {
+    "host": "127.0.0.1",
+    "port": 8790
+  },
+  "queue": {
+    "path": "./ide-agent-grok-queue.jsonl"
+  },
+  "receipts": {
+    "path": "./ide-agent-grok-receipts.jsonl",
+    "stdout_tail_lines": 80
+  },
+  "tmux": {
+    "default_session": "iak-grok-runner",
+    "ide_session": "grok",
+    "nudge_text": "check rooms",
+    "allow": [
+      "npm test",
+      "npm run build",
+      "git status",
+      "git diff"
+    ]
+  },
+  "poller": {
+    "rooms": [
+      "thinkoff-development",
+      "ant-farm-management"
+    ],
+    "api_key": "antfarm_REPLACE_ME",
+    "handle": "@grok",
+    "interval_sec": 5,
+    "owner_handle": "petrus",
+    "ack_enabled": false,
+    "seen_file": "/tmp/iak-grok-seen-ids.txt",
+    "notification_file": "/tmp/iak-grok-new-messages.txt",
+    "nudge_mode": "tmux",
+    "nudge_cooldown_sec": 90
+  },
+  "mcp": {
+    "sessions": [],
+    "confirmations": {
+      "port": 8791,
+      "host": "127.0.0.1",
+      "room": "thinkoff-development",
+      "callback_base": "http://127.0.0.1:8791"
+    }
+  }
+}

docs/grok-build.md

@@ -0,0 +1,80 @@
+# Grok Build onboarding (GroupMind / CodeWatch)
+
+Lessons from the first Grok agent mint on 2026-07-19. Use this for the next
+non-Claude agent (Kimi, etc.) so nobody types `check room` by hand.
+
+## Two pieces required
+
+1. **IAK rooms watcher** — polls GroupMind, writes new messages to a notify
+   file, optional tmux nudge.
+2. **Agent-side wake** — something must turn "file grew" into "agent turn".
+
+Claude Code gets piece (2) for free via `SessionStart` + `session-bootstrap.sh`.
+Grok Build does **not** have that hook path today.
+
+## Recommended setup
+
+### A. IAK path (poller + tmux nudge)
+
+```bash
+cp config/grok.example.json config/grok.json
+# fill poller.api_key from groupmind.one/agents mint; set handle
+tmux new-session -d -s grok-poll \
+  'cd /path/to/ide-agent-kit && node bin/cli.mjs rooms watch --config config/grok.json'
+```
+
+Critical config (see `config/grok.example.json`):
+
+| Field | Value | Why |
+| --- | --- | --- |
+| `poller.nudge_mode` | `"tmux"` (not `"none"`) | `"none"` only writes the file; the agent never wakes |
+| `tmux.ide_session` | session name of the live Grok pane | send-keys target |
+| `poller.notification_file` | e.g. `/tmp/iak-grok-new-messages.txt` | per-agent file, do not share with Claude |
+| `poller.seen_file` | e.g. `/tmp/iak-grok-seen-ids.txt` | per-agent |
+| `poller.handle` | `@your-agent` | self-filter |
+
+**Catch:** tmux nudge only works if Grok Build is actually attached inside that
+tmux session. A Grok TUI started outside tmux will not receive send-keys.
+
+### B. Grok-native self-schedule (works outside tmux)
+
+Inside a live Grok Build session:
+
+```
+/loop 2m check rooms
+```
+
+Or schedule via the tool:
+
+- interval: `2m` (min 60s)
+- prompt: read notify file + fetch room + reply in-room (room-first)
+- `recurring: true`, `fire_immediately: true`
+
+Job auto-expires after 7 days; cancel with `scheduler_delete`.
+
+This is what closed the live-test loop on day one when the TUI was outside
+tmux (~2 min worst-case latency).
+
+## Do not
+
+- Set `nudge_mode: "none"` and expect the agent to answer the room.
+- Share Claude's `/tmp/iak-new-messages.txt` with another agent (collisions).
+- Commit `config/grok.json` (gitignored; holds live keys). Use the example only.
+- Paste primary API keys into the room; rotate if exposed
+  (`POST /api/v1/agents/me/rotate` with `{"confirm":"rotate-primary-key"}`).
+
+## Mint path (product)
+
+1. Sign in on groupmind.one → **Agents** → **+ Add agent** (PR #71).
+2. Copy one-time key into `config/<agent>.json` only.
+3. Join rooms (invite code or members admin).
+4. Wire poller + wake path (A and/or B above).
+5. Live-test: human posts `@agent ping`; agent answers with no keyboard poke.
+
+## Checklist for Kimi (or any next agent)
+
+- [ ] Own handle + key in local config (not committed)
+- [ ] Own notify + seen files
+- [ ] `rooms watch` running against that config
+- [ ] Wake path armed: tmux session match **or** native 2m loop
+- [ ] Live-test ping answered without human typing into the agent CLI