From 5f8a1388687af3ee098185d9ad44c1d234ea775d Mon Sep 17 00:00:00 2001
From: Gabi Simons <gabi@qwibit.ai>
Date: Mon, 20 Apr 2026 10:59:55 +0000
Subject: [PATCH] docs(skills): update add-matrix skill

- Install steps aligned with add-linear/add-github pattern (fetch,
  copy, import, install pkg, build)
- Add Matrix-specific step: patch @beeper/chat-adapter-matrix ESM
  imports (inline node one-liner, idempotent)
- Cover bot-account requirement (can't DM yourself), access-token
  and username/password auth paths, optional invite auto-join /
  E2EE / device-id settings
---
 .claude/skills/add-matrix/SKILL.md | 85 +++++++++++++++++++++++++-----
 1 file changed, 71 insertions(+), 14 deletions(-)

diff --git a/.claude/skills/add-matrix/SKILL.md b/.claude/skills/add-matrix/SKILL.md
index 7a6ea0f..cf6da75 100644
--- a/.claude/skills/add-matrix/SKILL.md
+++ b/.claude/skills/add-matrix/SKILL.md
@@ -47,7 +47,29 @@ import './matrix.js';
 pnpm install @beeper/chat-adapter-matrix@0.2.0
 ```
 
-### 5. Build
+### 5. Patch matrix-js-sdk ESM imports
+
+The adapter's published dist references `matrix-js-sdk/lib/...` without `.js`
+extensions, which fails under Node 22 strict ESM resolution. Add the missing
+extensions (idempotent — safe to re-run):
+
+```bash
+node -e '
+  const fs = require("fs"), path = require("path");
+  const root = "node_modules/.pnpm";
+  const dir = fs.readdirSync(root).find(d => d.startsWith("@beeper+chat-adapter-matrix@"));
+  if (!dir) { console.log("Matrix adapter not installed"); process.exit(0); }
+  const f = path.join(root, dir, "node_modules/@beeper/chat-adapter-matrix/dist/index.js");
+  fs.writeFileSync(f, fs.readFileSync(f, "utf8").replace(
+    /from "(matrix-js-sdk\/lib\/[^"]+?)(?<!\.js)"/g, "from \"$1.js\""
+  ));
+  console.log("Patched", f);
+'
+```
+
+Re-run this after every `pnpm install` that touches the adapter.
+
+### 6. Build
 
 ```bash
 pnpm run build
@@ -55,25 +77,60 @@ pnpm run build
 
 ## Credentials
 
-1. Register a bot account on your Matrix homeserver (e.g., via Element)
-2. Get the homeserver URL (e.g., `https://matrix.org` or your self-hosted URL)
-3. Get an access token:
-   - In Element: **Settings** > **Help & About** > **Access Token** (advanced)
-   - Or via API: `curl -XPOST 'https://matrix.org/_matrix/client/r0/login' -d '{"type":"m.login.password","user":"botuser","password":"..."}'`
-4. Note the bot's user ID (e.g., `@botuser:matrix.org`)
+The bot needs its own Matrix account — separate from the user's account. This is required because Matrix cannot send DMs to yourself.
 
-### Configure environment
+### Create a bot account
 
-Add to `.env`:
+1. Open [app.element.io](https://app.element.io) in a private/incognito window (or sign out first)
+2. Register a new account for the bot (e.g. `andybot` on matrix.org)
+3. Note the bot's user ID (e.g. `@andybot:matrix.org`)
+
+### Choose an auth method
+
+**Option A: Username + Password (simpler)**
+
+No extra steps — just use the bot account's credentials directly. The adapter logs in automatically.
+
+```bash
+MATRIX_BASE_URL=https://matrix.org
+MATRIX_USERNAME=andybot
+MATRIX_PASSWORD=your-bot-password
+MATRIX_USER_ID=@andybot:matrix.org
+MATRIX_BOT_USERNAME=Andy
+```
+
+**Option B: Access Token (recommended for production)**
+
+Get an access token from Element: sign into the bot account → **Settings** > **Help & About** > **Access Token** (under Advanced). Or via API:
+
+```bash
+curl -XPOST 'https://matrix.org/_matrix/client/r0/login' \
+  -d '{"type":"m.login.password","user":"andybot","password":"..."}'
+```
 
 ```bash
 MATRIX_BASE_URL=https://matrix.org
 MATRIX_ACCESS_TOKEN=your-access-token
-MATRIX_USER_ID=@botuser:matrix.org
-MATRIX_BOT_USERNAME=botuser
+MATRIX_USER_ID=@andybot:matrix.org
+MATRIX_BOT_USERNAME=Andy
 ```
 
-Sync to container: `mkdir -p data/env && cp .env data/env/env`
+### Optional settings
+
+```bash
+MATRIX_INVITE_AUTOJOIN=true                    # Auto-accept room invites (default: true)
+MATRIX_INVITE_AUTOJOIN_ALLOWLIST=@you:matrix.org  # Only accept invites from these users
+MATRIX_RECOVERY_KEY=your-recovery-key          # Enable E2EE cross-signing
+MATRIX_DEVICE_ID=NANOCLAW01                    # Stable device ID across restarts
+```
+
+### Configure environment
+
+Add the chosen env vars to `.env`, then sync:
+
+```bash
+mkdir -p data/env && cp .env data/env/env
+```
 
 ## Next Steps
 
@@ -85,7 +142,7 @@ Otherwise, run `/manage-channels` to wire this channel to an agent group.
 
 - **type**: `matrix`
 - **terminology**: Matrix has "rooms." A room can be a group chat or a direct message. Rooms have internal IDs (like `!abc123:matrix.org`) and optional aliases (like `#general:matrix.org`).
-- **how-to-find-id**: In Element, click the room name > Settings > Advanced — the "Internal room ID" is the platform ID (starts with `!`). Or use a room alias like `#general:matrix.org`.
+- **how-to-find-id**: For DMs, use the bot's `openDM` to resolve the room automatically. For group rooms, in Element click the room name > Settings > Advanced — the "Internal room ID" is the platform ID (starts with `!`). Or use a room alias like `#general:matrix.org`.
 - **supports-threads**: partial (some clients support threads, but not all — treat as no for reliability)
-- **typical-use**: Interactive chat — rooms or direct messages
+- **typical-use**: Interactive chat — rooms or direct messages. Requires a separate bot account (the agent cannot DM users from their own account).
 - **default-isolation**: Same agent group for rooms where you're the primary user. Separate agent group for rooms with different communities or sensitive contexts.