docs(changelog): align v2.0.63 rollup line with RELEASING.md voice

RELEASING.md frames the per-bump release policy as a goal that is cut manually, not as automation. The v2.0.63 CHANGELOG rollup line still asserted the stronger claim ("NanoClaw publishes a GitHub Release on every package.json version bump"), which contradicts the policy doc. Soften to match RELEASING.md so the two land consistently on main.
docs(changelog): drop stale docs.nanoclaw.dev link from header
2026-06-04 10:14:47 +08:00 · 2026-05-15 21:04:17 +02:00 · 2026-05-15 20:49:53 +02:00 · 2026-05-15 20:24:47 +02:00 · 2026-05-15 19:51:01 +02:00 · 2026-05-15 17:15:22 +00:00
73 changed files with 699 additions and 389 deletions
@@ -182,9 +182,12 @@ ATOMIC_CHAT_API_KEY=sk-...

 ### Restart the service

+Run from your NanoClaw project root:
+
 ```bash
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
-# Linux: systemctl --user restart nanoclaw
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
+# Linux: systemctl --user restart $(systemd_unit)
 ```

 ## Phase 4: Verify
@@ -93,10 +93,13 @@ Generate the secret: `node -e "console.log('nc-' + require('crypto').randomBytes

 ### 6. Build and restart

+Run from your NanoClaw project root:
+
 ```bash
 pnpm run build
-systemctl --user restart nanoclaw   # Linux
-# or: launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
+source setup/lib/install-slug.sh
+systemctl --user restart $(systemd_unit)              # Linux
+# or: launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
 ```

 ### 7. Verify
@@ -23,14 +23,17 @@ DC_SMTP_PORT

 ## 3. Rebuild and restart

+Run from your NanoClaw project root:
+
 ```bash
 pnpm run build
+source setup/lib/install-slug.sh

 # Linux
-systemctl --user restart nanoclaw
+systemctl --user restart $(systemd_unit)

 # macOS
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)
 ```

 ## 4. Remove account data (optional)
@@ -98,12 +98,16 @@ The `/set-avatar` command (send an image with that caption) is the easiest way t

 ### Restart

+Run from your NanoClaw project root:
+
 ```bash
+source setup/lib/install-slug.sh
+
 # Linux
-systemctl --user restart nanoclaw
+systemctl --user restart $(systemd_unit)

 # macOS
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)
 ```

 On first start the adapter configures the email account (IMAP/SMTP credentials, calls `configure()`). Subsequent starts skip straight to `startIo()`. Account data is stored in `dc-account/` in the project root (or your `DC_ACCOUNT_DIR`).
@@ -232,7 +236,7 @@ Set `DC_SMTP_SECURITY=1` and `DC_SMTP_PORT=465` in `.env`, then restart.

 ```bash
 rm -f dc-account/accounts.lock
-systemctl --user restart nanoclaw
+systemctl --user restart "$(. setup/lib/install-slug.sh && systemd_unit)"
 ```

 ### Bot not responding after restart
@@ -162,10 +162,13 @@ If you changed `EMACS_CHANNEL_PORT` from the default:

 ## Restart NanoClaw

+Run from your NanoClaw project root:
+
 ```bash
 pnpm run build
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw   # macOS
-# systemctl --user restart nanoclaw                # Linux
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)   # macOS
+# systemctl --user restart $(systemd_unit)             # Linux
 ```

 ## Verify
@@ -240,7 +243,7 @@ grep -q "import './emacs.js'" src/channels/index.ts && echo "imported" || echo "

 ### No response from agent

-1. NanoClaw running: `launchctl list | grep nanoclaw` (macOS) / `systemctl --user status nanoclaw` (Linux)
+1. NanoClaw running: `launchctl list | grep "$(. setup/lib/install-slug.sh && launchd_label)"` (macOS) / `systemctl --user status "$(. setup/lib/install-slug.sh && systemd_unit)"` (Linux)
 2. Messaging group wired: `pnpm exec tsx scripts/q.ts data/v2.db "SELECT mg.platform_id, ag.folder FROM messaging_groups mg JOIN messaging_group_agents mga ON mg.id = mga.messaging_group_id JOIN agent_groups ag ON ag.id = mga.agent_group_id WHERE mg.channel_type = 'emacs'"`
 3. Logs show inbound: `grep 'channel_type=emacs\|Emacs' logs/nanoclaw.log | tail -20`

@@ -282,13 +285,16 @@ If an agent outputs org-mode directly, markers get double-converted and render i

 ## Removal

+Run from your NanoClaw project root:
+
 ```bash
 rm src/channels/emacs.ts src/channels/emacs.test.ts emacs/nanoclaw.el
 # Remove the `import './emacs.js';` line from src/channels/index.ts
 # Remove EMACS_* lines from .env
 pnpm run build
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw   # macOS
-# systemctl --user restart nanoclaw                # Linux
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)   # macOS
+# systemctl --user restart $(systemd_unit)             # Linux

 # Remove the NanoClaw block from your Emacs config
 # Optionally clean up the messaging group:
@@ -92,7 +92,6 @@ onecli agents list

 ```bash
 grep -q 'CALENDAR_MCP_VERSION' container/Dockerfile && \
-grep -q "mcp__calendar__\*" container/agent-runner/src/providers/claude.ts && \
 echo "ALREADY APPLIED — skip to Phase 3"
 ```

@@ -121,9 +120,7 @@ RUN --mount=type=cache,target=/root/.cache/pnpm \
    pnpm install -g "@cocal/google-calendar-mcp@${CALENDAR_MCP_VERSION}"
 ```

-### Add tools to allowlist
-
-Edit `container/agent-runner/src/providers/claude.ts`. Add `'mcp__calendar__*'` to `TOOL_ALLOWLIST` after `'mcp__nanoclaw__*'` (or after `'mcp__gmail__*'` if present).
+**No `TOOL_ALLOWLIST` edit needed.** `container/agent-runner/src/providers/claude.ts` derives the allow-pattern dynamically from each group's `mcpServers` map (`Object.keys(this.mcpServers).map(mcpAllowPattern)`), so registering `calendar` in Phase 3 automatically allows `mcp__calendar__*`. Earlier versions of this skill instructed a static `TOOL_ALLOWLIST` edit — that's now redundant.

 ### Rebuild the container image

@@ -133,40 +130,59 @@ Edit `container/agent-runner/src/providers/claude.ts`. Add `'mcp__calendar__*'`

 ## Phase 3: Wire Per-Agent-Group

-For each agent group, merge into `groups/<folder>/container.json`:
+For each agent group, persist two changes to the **central DB** (`data/v2.db`): the `mcpServers.calendar` entry and an `additionalMounts` entry for `.calendar-mcp`. Both flow through `materializeContainerJson` on every spawn, so editing `groups/<folder>/container.json` by hand does **not** stick — that file is regenerated from the DB.

-```jsonc
-{
-  "mcpServers": {
-    "calendar": {
-      "command": "google-calendar-mcp",
-      "args": [],
-      "env": {
-        "GOOGLE_OAUTH_CREDENTIALS": "/workspace/extra/.calendar-mcp/gcp-oauth.keys.json",
-        "GOOGLE_CALENDAR_MCP_TOKEN_PATH": "/workspace/extra/.calendar-mcp/credentials.json"
-      }
-    }
-  },
-  "additionalMounts": [
-    {
-      "hostPath": "/home/<user>/.calendar-mcp",
-      "containerPath": ".calendar-mcp",
-      "readonly": false
-    }
-  ]
-}
+### Register the MCP server
+
+For each chosen `<group-id>` (use `ncl groups list` to enumerate):
+
+```bash
+ncl groups config add-mcp-server \
+  --id <group-id> \
+  --name calendar \
+  --command google-calendar-mcp \
+  --args '[]' \
+  --env '{"GOOGLE_OAUTH_CREDENTIALS":"/workspace/extra/.calendar-mcp/gcp-oauth.keys.json","GOOGLE_CALENDAR_MCP_TOKEN_PATH":"/workspace/extra/.calendar-mcp/credentials.json"}'
 ```

-Substitute `<user>` with `echo $HOME`. `containerPath` is relative (mount-security rejects absolute paths — additional mounts land at `/workspace/extra/<relative>`).
+Approval behaviour depends on where you run it: from inside an agent's container `ncl` write verbs are approval-gated (admin approves before it lands); from a host operator shell with full scope, it executes immediately. Either way, the response tells you which path it took.

-**Same-group-as-gmail tip:** if this group already has the gmail MCP + `.gmail-mcp` mount, **merge, don't replace** — both entries coexist in `mcpServers` and `additionalMounts`.
+### Add the `.calendar-mcp` mount
+
+There is no `ncl groups config add-mount` verb yet (tracked in [#2395](https://github.com/nanocoai/nanoclaw/issues/2395)). Until that ships, edit the DB directly via the in-tree wrapper (`scripts/q.ts` — `setup/verify.ts:5` codifies that NanoClaw avoids depending on the `sqlite3` CLI binary, so don't shell out to it):
+
+```bash
+GROUP_ID='<group-id>'
+HOST_PATH="$HOME/.calendar-mcp"
+MOUNT=$(jq -cn --arg h "$HOST_PATH" '{hostPath:$h, containerPath:".calendar-mcp", readonly:false}')
+pnpm exec tsx scripts/q.ts data/v2.db "UPDATE container_configs \
+  SET additional_mounts = json_insert(additional_mounts, '\$[#]', json('$MOUNT')), \
+      updated_at = datetime('now') \
+  WHERE agent_group_id = '$GROUP_ID';"
+```
+
+Run from your NanoClaw project root (where `data/v2.db` lives). The `$[#]` placeholder is SQLite JSON1's append-to-end notation; it's `\$`-escaped so bash doesn't arithmetic-expand it before sqlite sees it. `updated_at` is ISO-string everywhere else in the schema, so use `datetime('now')` — not `strftime('%s','now')`, which would silently mix epoch ints into a column of YYYY-MM-DD HH:MM:SS strings.
+
+**Switch to `ncl groups config add-mount` once #2395 lands.** Update this skill at that time.
+
+`containerPath` is relative (mount-security rejects absolute paths — additional mounts land at `/workspace/extra/<relative>`).
+
+**Why this can't be `groups/<folder>/container.json`:** post-migration `014-container-configs`, `materializeContainerJson` in `src/container-config.ts` rewrites that file from the DB on every spawn. Anything hand-edited there is silently overwritten on next restart.
+
+**Same-group-as-gmail tip:** if this group already has the gmail MCP + `.gmail-mcp` mount, both coexist — `ncl groups config add-mcp-server` only updates the named entry, and `json_insert` appends to `additional_mounts` without disturbing existing entries.

 ## Phase 4: Build and Restart

 ```bash
 pnpm run build
-systemctl --user restart nanoclaw   # Linux
-# launchctl kickstart -k gui/$(id -u)/com.nanoclaw   # macOS
+```
+
+Run from your NanoClaw project root:
+
+```bash
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
+systemctl --user restart $(systemd_unit)              # Linux
 ```

 Kill any existing agent containers so they respawn with the new mcpServers config:
@@ -193,16 +209,28 @@ Common signals:
 - `command not found: google-calendar-mcp` → image not rebuilt.
 - `ENOENT ...credentials.json` → mount missing. Check the mount allowlist.
 - `401 Unauthorized` from `*.googleapis.com` → OneCLI isn't injecting; verify agent's secret mode and that Google Calendar is connected.
- Agent says "I don't have calendar tools" → `mcp__calendar__*` missing from `TOOL_ALLOWLIST`, or image cache stale (`./container/build.sh` again).
+- Agent says "I don't have calendar tools" → the `calendar` MCP server isn't registered in this group's `mcpServers` (re-run the `ncl groups config add-mcp-server` step in Phase 3 for that group and restart it), or the agent-runner image is stale (`./container/build.sh`, `--no-cache` if suspicious).

 ## Removal

-1. Delete `"calendar"` from `mcpServers` and the `.calendar-mcp` mount from `additionalMounts` in each group's `container.json`.
-2. Remove `'mcp__calendar__*'` from `TOOL_ALLOWLIST`.
+1. For each group that had Calendar wired, remove the MCP server from the DB:
+   ```bash
+   ncl groups config remove-mcp-server --id <group-id> --name calendar
+   ```
+2. Remove the `.calendar-mcp` mount from the DB (no `remove-mount` verb yet — same #2395 dependency):
+   ```bash
+   pnpm exec tsx scripts/q.ts data/v2.db "UPDATE container_configs \
+     SET additional_mounts = (SELECT json_group_array(value) FROM json_each(additional_mounts) \
+                              WHERE json_extract(value, '\$.containerPath') != '.calendar-mcp'), \
+         updated_at = datetime('now') \
+     WHERE agent_group_id = '<group-id>';"
+   ```
 3. Remove `CALENDAR_MCP_VERSION` ARG and the calendar package from the Dockerfile install block.
-4. `pnpm run build && ./container/build.sh && systemctl --user restart nanoclaw`.
+4. `pnpm run build && ./container/build.sh && systemctl --user restart "$(. setup/lib/install-slug.sh && systemd_unit)"`.
 5. Optional: `rm -rf ~/.calendar-mcp/` and `onecli apps disconnect --provider google-calendar`.

+No `TOOL_ALLOWLIST` removal step — Phase 2 no longer edits it.
+
 ## Credits & references

 - **MCP server:** [`@cocal/google-calendar-mcp`](https://github.com/cocal-com/google-calendar-mcp) — MIT-licensed, actively maintained, multi-account and multi-calendar.
@@ -136,7 +136,15 @@ Use `per-thread` session mode so each PR/issue gets its own agent session.

 If you're in the middle of `/setup`, return to the setup flow now.

-Otherwise, restart the service (`systemctl --user restart nanoclaw` or `launchctl kickstart -k gui/$(id -u)/com.nanoclaw`) to pick up the new channel.
+Otherwise, restart the service to pick up the new channel.
+
+Run from your NanoClaw project root:
+
+```bash
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
+systemctl --user restart $(systemd_unit)              # Linux
+```

 ## Channel Info

@@ -98,7 +98,6 @@ onecli agents secrets --id <agent-id>

 ```bash
 grep -q 'GMAIL_MCP_VERSION' container/Dockerfile && \
-grep -q "mcp__gmail__\*" container/agent-runner/src/providers/claude.ts && \
 echo "ALREADY APPLIED — skip to Phase 3"
 ```

@@ -132,9 +131,7 @@ Pinned version matters — `minimumReleaseAge` in `pnpm-workspace.yaml` gates tr

 **Why the `zod-to-json-schema` pin:** `@gongrzhe/server-gmail-autoauth-mcp@1.1.11` has loose deps (`zod-to-json-schema: ^3.22.1`, `zod: ^3.22.4`). pnpm resolves `zod-to-json-schema` to the latest 3.25.x, which imports `zod/v3` — a subpath that only exists in `zod>=3.25`. But `zod` resolves to `3.24.x` (highest satisfying `^3.22.4` without breaking peer ranges). Result: `ERR_PACKAGE_PATH_NOT_EXPORTED` at import time. Pinning `zod-to-json-schema` to a pre-v3-subpath version avoids it. Re-check if you bump `GMAIL_MCP_VERSION`.

-### Add tools to allowlist
-
-Edit `container/agent-runner/src/providers/claude.ts`. Find `'mcp__nanoclaw__*',` in `TOOL_ALLOWLIST` and add `'mcp__gmail__*',` after it.
+**No `TOOL_ALLOWLIST` edit needed.** `container/agent-runner/src/providers/claude.ts` derives the allow-pattern dynamically from each group's `mcpServers` map (`Object.keys(this.mcpServers).map(mcpAllowPattern)`), so registering `gmail` in Phase 3 automatically allows `mcp__gmail__*`. Earlier versions of this skill instructed a static `TOOL_ALLOWLIST` edit — that's now redundant.

 ### Rebuild the container image

@@ -146,42 +143,63 @@ Must complete cleanly. The new `pnpm install -g` layer is ~60s first time (cache

 ## Phase 3: Wire Per-Agent-Group

-For each agent group that should have Gmail (ask the user — typically their personal DM and CLI agents, sometimes shared household agents), edit `groups/<folder>/container.json` to add the mount and MCP server.
+For each agent group that should have Gmail (ask the user — typically their personal DM and CLI agents, sometimes shared household agents), persist two changes to the **central DB** (`data/v2.db`): the `mcpServers.gmail` entry and an `additionalMounts` entry for `.gmail-mcp`. Both flow through `materializeContainerJson` on every spawn, so editing `groups/<folder>/container.json` by hand does **not** stick — that file is regenerated from the DB.

-Merge these into the group's `container.json`:
+### List groups, pick which ones get Gmail

-```jsonc
-{
-  "mcpServers": {
-    "gmail": {
-      "command": "gmail-mcp",
-      "args": [],
-      "env": {
-        "GMAIL_OAUTH_PATH": "/workspace/extra/.gmail-mcp/gcp-oauth.keys.json",
-        "GMAIL_CREDENTIALS_PATH": "/workspace/extra/.gmail-mcp/credentials.json"
-      }
-    }
-  },
-  "additionalMounts": [
-    {
-      "hostPath": "/home/<user>/.gmail-mcp",
-      "containerPath": ".gmail-mcp",
-      "readonly": false
-    }
-  ]
-}
+```bash
+ncl groups list
 ```

-Substitute `<user>` with the host user's home (use `echo $HOME`, don't assume `~` will expand — `container-runner.ts` does expand `~` via `expandPath`, but an explicit absolute path is clearer and matches what `/manage-mounts` writes).
+### Register the MCP server
+
+For each chosen `<group-id>`:
+
+```bash
+ncl groups config add-mcp-server \
+  --id <group-id> \
+  --name gmail \
+  --command gmail-mcp \
+  --args '[]' \
+  --env '{"GMAIL_OAUTH_PATH":"/workspace/extra/.gmail-mcp/gcp-oauth.keys.json","GMAIL_CREDENTIALS_PATH":"/workspace/extra/.gmail-mcp/credentials.json"}'
+```
+
+Approval behaviour depends on where you run it: from inside an agent's container `ncl` write verbs are approval-gated (admin approves before it lands); from a host operator shell with full scope, it executes immediately. Either way, the response tells you which path it took.
+
+### Add the `.gmail-mcp` mount
+
+There is no `ncl groups config add-mount` verb yet (tracked in [#2395](https://github.com/nanocoai/nanoclaw/issues/2395)). Until that ships, edit the DB directly via the in-tree wrapper (`scripts/q.ts` — `setup/verify.ts:5` codifies that NanoClaw avoids depending on the `sqlite3` CLI binary, so don't shell out to it):
+
+```bash
+GROUP_ID='<group-id>'
+HOST_PATH="$HOME/.gmail-mcp"
+MOUNT=$(jq -cn --arg h "$HOST_PATH" '{hostPath:$h, containerPath:".gmail-mcp", readonly:false}')
+pnpm exec tsx scripts/q.ts data/v2.db "UPDATE container_configs \
+  SET additional_mounts = json_insert(additional_mounts, '\$[#]', json('$MOUNT')), \
+      updated_at = datetime('now') \
+  WHERE agent_group_id = '$GROUP_ID';"
+```
+
+Run from your NanoClaw project root (where `data/v2.db` lives). The `$[#]` placeholder is SQLite JSON1's append-to-end notation; it's `\$`-escaped so bash doesn't arithmetic-expand it before sqlite sees it. `updated_at` is ISO-string everywhere else in the schema, so use `datetime('now')` — not `strftime('%s','now')`, which would silently mix epoch ints into a column of YYYY-MM-DD HH:MM:SS strings.
+
+**Switch to `ncl groups config add-mount` once #2395 lands.** Update this skill at that time.

 **Why the container path is relative:** `mount-security` rejects absolute `containerPath` values. Additional mounts are prefixed with `/workspace/extra/`, so `containerPath: ".gmail-mcp"` lands at `/workspace/extra/.gmail-mcp`. The MCP server's `GMAIL_OAUTH_PATH` / `GMAIL_CREDENTIALS_PATH` env vars point at that absolute location inside the container.

+**Why this can't be `groups/<folder>/container.json`:** post-migration `014-container-configs`, `materializeContainerJson` in `src/container-config.ts` rewrites that file from the DB on every spawn. Anything hand-edited there is silently overwritten on next restart.
+
 ## Phase 4: Build and Restart

 ```bash
 pnpm run build
-systemctl --user restart nanoclaw  # Linux
-# launchctl kickstart -k gui/$(id -u)/com.nanoclaw   # macOS
+```
+
+Run from your NanoClaw project root:
+
+```bash
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
+systemctl --user restart $(systemd_unit)              # Linux
 ```

 ## Phase 5: Verify
@@ -206,17 +224,29 @@ Common signals:
 - `command not found: gmail-mcp` → image wasn't rebuilt or PATH doesn't include `/pnpm` (should — `ENV PATH="$PNPM_HOME:$PATH"` in Dockerfile).
 - `ENOENT: no such file or directory, open '/workspace/extra/.gmail-mcp/credentials.json'` → mount is missing. Check `~/.config/nanoclaw/mount-allowlist.json` includes a parent of `~/.gmail-mcp`.
 - `401 Unauthorized` from `gmail.googleapis.com` → OneCLI isn't injecting. Check the agent's secret mode (`onecli agents secrets --id <agent-id>`) and that the Gmail app is connected (`onecli apps get --provider gmail`).
- Agent says "I don't have Gmail tools" → `mcp__gmail__*` wasn't added to `TOOL_ALLOWLIST`, or the agent-runner wasn't rebuilt (image cache — run `./container/build.sh` again with `--no-cache` if suspicious).
+- Agent says "I don't have Gmail tools" → the `gmail` MCP server isn't registered in this group's `mcpServers` (re-run the `ncl groups config add-mcp-server` step in Phase 3 for that group and restart it), or the agent-runner image is stale (rebuild with `./container/build.sh`, with `--no-cache` if suspicious).

 ## Removal

-1. Delete the `"gmail"` entry from `mcpServers` and the `.gmail-mcp` entry from `additionalMounts` in each group's `container.json`.
-2. Remove `'mcp__gmail__*'` from `TOOL_ALLOWLIST` in `container/agent-runner/src/providers/claude.ts`.
+1. For each group that had Gmail wired, remove the MCP server from the DB:
+   ```bash
+   ncl groups config remove-mcp-server --id <group-id> --name gmail
+   ```
+2. Remove the `.gmail-mcp` mount from the DB (no `remove-mount` verb yet — same #2395 dependency):
+   ```bash
+   pnpm exec tsx scripts/q.ts data/v2.db "UPDATE container_configs \
+     SET additional_mounts = (SELECT json_group_array(value) FROM json_each(additional_mounts) \
+                              WHERE json_extract(value, '\$.containerPath') != '.gmail-mcp'), \
+         updated_at = datetime('now') \
+     WHERE agent_group_id = '<group-id>';"
+   ```
 3. Remove the `GMAIL_MCP_VERSION` ARG and the `pnpm install -g @gongrzhe/server-gmail-autoauth-mcp` block from `container/Dockerfile`.
-4. `pnpm run build && ./container/build.sh && systemctl --user restart nanoclaw`.
+4. `pnpm run build && ./container/build.sh && systemctl --user restart "$(. setup/lib/install-slug.sh && systemd_unit)"`.
 5. (Optional) `rm -rf ~/.gmail-mcp/` if no other host-side tool needs the stubs.
 6. (Optional) Disconnect Gmail in OneCLI: `onecli apps disconnect --provider gmail`.

+No `TOOL_ALLOWLIST` removal step — Phase 2 no longer edits it.
+
 ## Notes

 - **Stub format is OneCLI-prescribed.** The `access_token: "onecli-managed"` pattern with `expiry_date: 99999999999999` tells the Google auth client the token is valid; OneCLI intercepts the outgoing Gmail API call and rewrites `Authorization: Bearer onecli-managed` to the real token. `expiry_date: 0` (refresh-interception) is an alternative the OneCLI docs describe — both work but OneCLI's own `migrate` command writes the far-future variant, which is what this skill assumes.
@@ -228,5 +258,5 @@ Common signals:
 - **MCP server:** [`@gongrzhe/server-gmail-autoauth-mcp`](https://github.com/GongRzhe/Gmail-MCP-Server) by GongRzhe — MIT-licensed.
 - **OneCLI credential stubs:** pattern documented at `https://onecli.sh/docs/guides/credential-stubs/gmail.md`.
 - **Skill pattern:** modeled on [`add-atomic-chat-tool`](../add-atomic-chat-tool/SKILL.md) and [`add-vercel`](../add-vercel/SKILL.md).
- **Addresses:** [issue #1500](https://github.com/qwibitai/nanoclaw/issues/1500) (proxy Gmail/Calendar OAuth tokens through credential proxy) for the Gmail side.
- **Related PRs:** [#1810](https://github.com/qwibitai/nanoclaw/pull/1810) (pre-install Gmail/Notion MCP) overlaps on the "install the MCP server in the image" idea but bundles many unrelated changes; this skill is the focused OneCLI-native version.
+- **Addresses:** [issue #1500](https://github.com/nanocoai/nanoclaw/issues/1500) (proxy Gmail/Calendar OAuth tokens through credential proxy) for the Gmail side.
+- **Related PRs:** [#1810](https://github.com/nanocoai/nanoclaw/pull/1810) (pre-install Gmail/Notion MCP) overlaps on the "install the MCP server in the image" idea but bundles many unrelated changes; this skill is the focused OneCLI-native version.
@@ -75,9 +75,12 @@ If yes, ask the agent to schedule the lint task using the `schedule_task` MCP to

 ## Step 6: Restart

+Run from your NanoClaw project root:
+
 ```bash
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
-# Linux: systemctl --user restart nanoclaw
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
+systemctl --user restart $(systemd_unit)              # Linux
 ```

 Tell the user to test by sending a source to the wiki group.
@@ -156,7 +156,15 @@ The `platform_id` must be `linear:<TEAM_KEY>` matching the `LINEAR_TEAM_KEY` env

 If you're in the middle of `/setup`, return to the setup flow now.

-Otherwise, restart the service (`systemctl --user restart nanoclaw` or `launchctl kickstart -k gui/$(id -u)/com.nanoclaw`) to pick up the new channel.
+Otherwise, restart the service to pick up the new channel.
+
+Run from your NanoClaw project root:
+
+```bash
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
+systemctl --user restart $(systemd_unit)              # Linux
+```

 ## Channel Info

@@ -89,9 +89,12 @@ docker run --rm --entrypoint mnemon nanoclaw-agent:latest --version

 ### Restart the service

+Run from your NanoClaw project root:
+
 ```bash
-systemctl --user restart nanoclaw          # Linux
-# launchctl kickstart -k gui/$(id -u)/com.nanoclaw   # macOS
+source setup/lib/install-slug.sh
+systemctl --user restart $(systemd_unit)              # Linux
+# launchctl kickstart -k gui/$(id -u)/$(launchd_label)   # macOS
 ```

 ### Confirm mnemon hooks are registered
@@ -130,12 +130,15 @@ file, not from env vars. This file is bind-mounted into the container as `~/.cla

 ## 5. Build and restart

+Run from your NanoClaw project root:
+
 ```bash
 export PATH="/opt/homebrew/bin:$PATH"
 pnpm run build
-launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
-launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
-# Linux: systemctl --user restart nanoclaw
+source setup/lib/install-slug.sh
+launchctl unload ~/Library/LaunchAgents/$(launchd_label).plist
+launchctl load   ~/Library/LaunchAgents/$(launchd_label).plist
+# Linux: systemctl --user restart $(systemd_unit)
 ```

 ## 6. Verify
@@ -54,7 +54,7 @@ git remote -v
 If `upstream` is missing, add it:

 ```bash
-git remote add upstream https://github.com/qwibitai/nanoclaw.git
+git remote add upstream https://github.com/nanocoai/nanoclaw.git
 ```

 ### Merge the skill branch
@@ -122,9 +122,12 @@ OLLAMA_HOST=http://your-ollama-host:11434

 ### Restart the service

+Run from your NanoClaw project root:
+
 ```bash
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
-# Linux: systemctl --user restart nanoclaw
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
+systemctl --user restart $(systemd_unit)              # Linux
 ```

 ## Phase 4: Verify
@@ -229,19 +229,22 @@ echo '{}' | docker run -i --entrypoint /bin/echo nanoclaw-agent:latest "Containe

 ### 7. Restart Service

-Rebuild the main app and restart:
+Rebuild the main app and restart.
+
+Run from your NanoClaw project root:

 ```bash
 pnpm run build
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
-# Linux: systemctl --user restart nanoclaw
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
+# Linux: systemctl --user restart $(systemd_unit)
 ```

 Wait 3 seconds for service to start, then verify:
 ```bash
 sleep 3
-launchctl list | grep nanoclaw  # macOS
-# Linux: systemctl --user status nanoclaw
+launchctl list | grep "$(. setup/lib/install-slug.sh && launchd_label)"  # macOS
+# Linux: systemctl --user status "$(. setup/lib/install-slug.sh && systemd_unit)"
 ```

 ### 8. Test Integration
@@ -287,4 +290,4 @@ To remove Parallel AI integration:
 2. Revert changes to container-runner.ts and agent-runner/src/index.ts
 3. Remove Web Research Tools section from groups/main/CLAUDE.md
 4. Rebuild: `./container/build.sh && pnpm run build`
-5. Restart: `launchctl kickstart -k gui/$(id -u)/com.nanoclaw` (macOS) or `systemctl --user restart nanoclaw` (Linux)
+5. Restart: `source setup/lib/install-slug.sh && launchctl kickstart -k gui/$(id -u)/$(launchd_label)` (macOS) or `source setup/lib/install-slug.sh && systemctl --user restart $(systemd_unit)` (Linux)
@@ -90,17 +90,21 @@ No output = success.

 > ⚠ Stop NanoClaw before running signal-cli commands — the daemon holds an exclusive lock on its data directory while running.

+Run from your NanoClaw project root:
+
 ```bash
+source setup/lib/install-slug.sh
+
 # macOS
-launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
+launchctl unload ~/Library/LaunchAgents/$(launchd_label).plist
 signal-cli -a +1YOURNUMBER updateProfile --name "YourBotName"
 # optionally: --avatar /path/to/avatar.jpg
-launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
+launchctl load ~/Library/LaunchAgents/$(launchd_label).plist

 # Linux
-systemctl --user stop nanoclaw
+systemctl --user stop $(systemd_unit)
 signal-cli -a +1YOURNUMBER updateProfile --name "YourBotName"
-systemctl --user start nanoclaw
+systemctl --user start $(systemd_unit)
 ```

 ### Path B: Link as secondary device
@@ -185,12 +189,16 @@ Sync to container: `mkdir -p data/env && cp .env data/env/env`

 ### Restart

+Run from your NanoClaw project root:
+
 ```bash
+source setup/lib/install-slug.sh
+
 # macOS
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)

 # Linux
-systemctl --user restart nanoclaw
+systemctl --user restart $(systemd_unit)
 ```

 ## Wiring
@@ -283,7 +291,7 @@ If you see `Signal daemon not reachable at 127.0.0.1:7583` and `SIGNAL_MANAGE_DA

 1. Channel initialized: `grep "Signal channel connected" logs/nanoclaw.log | tail -1`
 2. Channel wired: `pnpm exec tsx scripts/q.ts data/v2.db "SELECT mg.platform_id, mg.name FROM messaging_groups mg JOIN messaging_group_agents mga ON mg.id = mga.messaging_group_id WHERE mg.channel_type='signal'"`
-3. Service running: `launchctl print gui/$(id -u)/com.nanoclaw` (macOS) / `systemctl --user status nanoclaw` (Linux)
+3. Service running: `launchctl print gui/$(id -u)/"$(. setup/lib/install-slug.sh && launchd_label)"` (macOS) / `systemctl --user status "$(. setup/lib/install-slug.sh && systemd_unit)"` (Linux)
 4. **Check for duplicate service instances** — if `logs/nanoclaw.error.log` shows `No adapter for channel type channelType="signal"` despite the adapter starting, two NanoClaw processes are racing. See the `/debug` skill section "No adapter for channel type / Messages silently lost" for the full fix.

 ### Messages delivered but never arrive (null platformMsgId)
@@ -60,7 +60,7 @@ pnpm run build
 1. Go to [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App** > **From scratch**
 2. Name it (e.g., "NanoClaw") and select your workspace
 3. Go to **OAuth & Permissions** and add Bot Token Scopes:
-   - `chat:write`, `im:write`, `channels:history`, `groups:history`, `im:history`, `channels:read`, `groups:read`, `users:read`, `reactions:write`
+   - `chat:write`, `im:write`, `channels:history`, `groups:history`, `im:history`, `channels:read`, `groups:read`, `users:read`, `reactions:write`, `files:read`, `files:write`
 4. Click **Install to Workspace** and copy the **Bot User OAuth Token** (`xoxb-...`)
 5. Go to **Basic Information** and copy the **Signing Secret**

@@ -41,9 +41,12 @@ DELETE FROM messaging_groups WHERE channel_type = 'wechat';

 ### 6. Rebuild and restart

+Run from your NanoClaw project root:
+
 ```bash
 pnpm run build
-systemctl --user restart nanoclaw   # Linux
+source setup/lib/install-slug.sh
+systemctl --user restart $(systemd_unit)              # Linux
 # or
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw   # macOS
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
 ```
@@ -82,12 +82,15 @@ Sync to container: `mkdir -p data/env && cp .env data/env/env`

 ### 2. Start the service and scan the QR

-Restart NanoClaw:
+Restart NanoClaw.
+
+Run from your NanoClaw project root:

 ```bash
-systemctl --user restart nanoclaw   # Linux
+source setup/lib/install-slug.sh
+systemctl --user restart $(systemd_unit)              # Linux
 # or
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw   # macOS
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
 ```

 The adapter will print a **QR URL** to the logs and save it to `data/wechat/qr.txt`:
@@ -244,12 +244,15 @@ rm -rf store/auth/ && pnpm exec tsx setup/index.ts --step whatsapp-auth -- --met

 ### "waiting for this message" on reactions

-Signal sessions corrupted from rapid restarts. Clear sessions:
+Signal sessions corrupted from rapid restarts. Clear sessions.
+
+Run from your NanoClaw project root:

 ```bash
-systemctl --user stop nanoclaw
+source setup/lib/install-slug.sh
+systemctl --user stop $(systemd_unit)
 rm store/auth/session-*.json
-systemctl --user start nanoclaw
+systemctl --user start $(systemd_unit)
 ```

 ### Bot not responding
@@ -257,7 +260,7 @@ systemctl --user start nanoclaw
 1. Auth exists: `test -f store/auth/creds.json`
 2. Connected: `grep "Connected to WhatsApp" logs/nanoclaw.log | tail -1`
 3. Channel wired: `pnpm exec tsx scripts/q.ts data/v2.db "SELECT mg.platform_id, mg.name FROM messaging_groups mg JOIN messaging_group_agents mga ON mg.id=mga.messaging_group_id WHERE mg.channel_type='whatsapp'"`
-4. Service running: `systemctl --user status nanoclaw`
+4. Service running: `systemctl --user status "$(. setup/lib/install-slug.sh && systemd_unit)"`

 ### "conflict" disconnection

@@ -58,7 +58,7 @@ git remote -v
 If `upstream` is missing, add it:

 ```bash
-git remote add upstream https://github.com/qwibitai/nanoclaw.git
+git remote add upstream https://github.com/nanocoai/nanoclaw.git
 ```

 ### Merge the skill branch
@@ -171,9 +171,12 @@ Expected: Both operations succeed.

 ### Full integration test

+Run from your NanoClaw project root:
+
 ```bash
 pnpm run build
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)
 ```

 Send a message via WhatsApp and verify the agent responds.
@@ -88,15 +88,19 @@ Implementation:

 ## After Changes

-Always tell the user:
+Always tell the user.
+
+Run from your NanoClaw project root:
+
 ```bash
 # Rebuild and restart
 pnpm run build
+source setup/lib/install-slug.sh
 # macOS:
-launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
-launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
+launchctl unload ~/Library/LaunchAgents/$(launchd_label).plist
+launchctl load ~/Library/LaunchAgents/$(launchd_label).plist
 # Linux:
-# systemctl --user restart nanoclaw
+# systemctl --user restart $(systemd_unit)
 ```

 ## Example Interaction
@@ -9,7 +9,7 @@ Stand up the first NanoClaw agent for a channel and verify end-to-end delivery b

 ## Prerequisites

- **Service running.** Check: `launchctl list | grep nanoclaw` (macOS) or `systemctl --user status nanoclaw` (Linux). If stopped, tell the user to run `/setup` first.
+- **Service running.** Check: `launchctl list | grep "$(. setup/lib/install-slug.sh && launchd_label)"` (macOS) or `systemctl --user status "$(. setup/lib/install-slug.sh && systemd_unit)"` (Linux). If stopped, tell the user to run `/setup` first.
 - **Target channel installed.** At least one `/add-<channel>` skill has run, credentials are in `.env`, and the adapter is uncommented in `src/channels/index.ts`.
 - **Adapter connected.** Tail `logs/nanoclaw.log` — look for a recent `channel setup` / `adapter connected` line for the target channel.

@@ -236,9 +236,12 @@ pnpm run build

 If build fails, diagnose and fix. Common issue: `@onecli-sh/sdk` not installed — run `pnpm install` first.

-Restart the service:
- macOS (launchd): `launchctl kickstart -k gui/$(id -u)/com.nanoclaw`
- Linux (systemd): `systemctl --user restart nanoclaw`
+Restart the service.
+
+Run from your NanoClaw project root:
+
+- macOS (launchd): `launchctl kickstart -k gui/$(id -u)/"$(. setup/lib/install-slug.sh && launchd_label)"`
+- Linux (systemd): `systemctl --user restart "$(. setup/lib/install-slug.sh && systemd_unit)"`
 - WSL/manual: stop and re-run `bash start-nanoclaw.sh`

 ## Phase 5: Verify
@@ -41,7 +41,12 @@ npx tsx setup/index.ts --step mounts --force -- --empty

 ## After Changes

-Restart the service so containers pick up the new config:
+Restart the service so containers pick up the new config (the unit/label names are per-install — see `setup/lib/install-slug.sh`).

- macOS: `launchctl kickstart -k gui/$(id -u)/com.nanoclaw`
- Linux: `systemctl --user restart nanoclaw`
+Run from your NanoClaw project root:
+
+```bash
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
+systemctl --user restart $(systemd_unit)              # Linux
+```
@@ -34,7 +34,7 @@ Two phases: **Extract** (build the migration guide) and **Upgrade** (use it). If

 Run `git status --porcelain`. If non-empty, offer to stash or commit for them (AskUserQuestion: "Stash changes" / "Commit changes" / "I'll handle it"). If they want to commit, stage and commit with a descriptive message. If they want to stash, run `git stash push -m "pre-migration stash"`.

-Check remotes with `git remote -v`. If `upstream` is missing, ask for the URL (default: `https://github.com/qwibitai/nanoclaw.git`), add it, then `git fetch upstream --prune`.
+Check remotes with `git remote -v`. If `upstream` is missing, ask for the URL (default: `https://github.com/nanocoai/nanoclaw.git`), add it, then `git fetch upstream --prune`.

 Detect upstream branch: check `git branch -r | grep upstream/` for `main` or `master`. Store as UPSTREAM_BRANCH.

@@ -11,7 +11,7 @@ Run `/update-nanoclaw` in Claude Code.

 ## How it works

-**Preflight**: checks for clean working tree (`git status --porcelain`). If `upstream` remote is missing, asks you for the URL (defaults to `https://github.com/qwibitai/nanoclaw.git`) and adds it. Detects the upstream branch name (`main` or `master`).
+**Preflight**: checks for clean working tree (`git status --porcelain`). If `upstream` remote is missing, asks you for the URL (defaults to `https://github.com/nanocoai/nanoclaw.git`) and adds it. Detects the upstream branch name (`main` or `master`).

 **Backup**: creates a timestamped backup branch and tag (`backup/pre-update-<hash>-<timestamp>`, `pre-update-<hash>-<timestamp>`) before touching anything. Safe to run multiple times.

@@ -69,7 +69,7 @@ If output is non-empty:
 Confirm remotes:
 - `git remote -v`
 If `upstream` is missing:
- Ask the user for the upstream repo URL (default: `https://github.com/qwibitai/nanoclaw.git`).
+- Ask the user for the upstream repo URL (default: `https://github.com/nanocoai/nanoclaw.git`).
 - Add it: `git remote add upstream <user-provided-url>`
 - Then: `git fetch upstream --prune`

@@ -270,9 +270,9 @@ Show:
 Tell the user:
 - To rollback: `git reset --hard <backup-tag-from-step-1>`
 - Backup branch also exists: `backup/pre-update-<HASH>-<TIMESTAMP>`
- Restart the service to apply changes. Detect platform with `uname -s`:
-  - **macOS (Darwin)**: `launchctl kickstart -k gui/$(id -u)/com.nanoclaw`
-  - **Linux**: detect the service name with `systemctl --user list-units --type=service | grep nanoclaw | awk '{print $1}'`, then `systemctl --user restart <detected-name>`
+- Restart the service to apply changes. The unit/label names are per-install — derive them with `setup/lib/install-slug.sh`. Run from your NanoClaw project root:
+  - **macOS (Darwin)**: `source setup/lib/install-slug.sh && launchctl kickstart -k gui/$(id -u)/$(launchd_label)`
+  - **Linux**: `source setup/lib/install-slug.sh && systemctl --user restart $(systemd_unit)` (or, if you want to confirm the unit name first: `systemctl --user list-units --type=service | grep "$(. setup/lib/install-slug.sh && systemd_unit)"`)
  - **Manual** (no service found): restart `pnpm run dev`


@@ -42,7 +42,7 @@ Check remotes:
 - `git remote -v`

 If `upstream` is missing:
- Ask the user for the upstream repo URL (default: `https://github.com/qwibitai/nanoclaw.git`).
+- Ask the user for the upstream repo URL (default: `https://github.com/nanocoai/nanoclaw.git`).
 - `git remote add upstream <url>`

 Fetch:
@@ -40,7 +40,7 @@ git remote -v
 If `upstream` is missing, add it:

 ```bash
-git remote add upstream https://github.com/qwibitai/nanoclaw.git
+git remote add upstream https://github.com/nanocoai/nanoclaw.git
 ```

 ### Merge the skill branch
@@ -128,9 +128,12 @@ echo 'ANTHROPIC_API_KEY=<key>' >> .env
 pnpm run build
 ```

-Then restart the service:
- macOS: `launchctl kickstart -k gui/$(id -u)/com.nanoclaw`
- Linux: `systemctl --user restart nanoclaw`
+Then restart the service.
+
+Run from your NanoClaw project root:
+
+- macOS: `launchctl kickstart -k gui/$(id -u)/"$(. setup/lib/install-slug.sh && launchd_label)"`
+- Linux: `systemctl --user restart "$(. setup/lib/install-slug.sh && systemd_unit)"`
 - WSL/manual: stop and re-run `bash start-nanoclaw.sh`

 2. Check logs for successful proxy startup:
@@ -38,6 +38,8 @@ Before using this skill, ensure:

 ## Quick Start

+Run from your NanoClaw project root:
+
 ```bash
 # 1. Setup authentication (interactive)
 pnpm exec dotenv -e .env -- pnpm exec tsx .claude/skills/x-integration/scripts/setup.ts
@@ -49,9 +51,10 @@ pnpm exec dotenv -e .env -- pnpm exec tsx .claude/skills/x-integration/scripts/s

 # 3. Rebuild host and restart service
 pnpm run build
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
-# Linux: systemctl --user restart nanoclaw
-# Verify: launchctl list | grep nanoclaw (macOS) or systemctl --user status nanoclaw (Linux)
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
+# Linux: systemctl --user restart $(systemd_unit)
+# Verify: launchctl list | grep "$(launchd_label)" (macOS) or systemctl --user status $(systemd_unit) (Linux)
 ```

 ## Configuration
@@ -270,16 +273,23 @@ cat data/x-auth.json  # Should show {"authenticated": true, ...}

 ### 4. Restart Service

+Run from your NanoClaw project root:
+
 ```bash
 pnpm run build
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
-# Linux: systemctl --user restart nanoclaw
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
+# Linux: systemctl --user restart $(systemd_unit)
 ```

-**Verify success:**
+**Verify success.**
+
+Run from your NanoClaw project root:
+
 ```bash
-launchctl list | grep nanoclaw  # macOS — should show PID and exit code 0 or -
-# Linux: systemctl --user status nanoclaw
+source setup/lib/install-slug.sh
+launchctl list | grep "$(launchd_label)"  # macOS — should show PID and exit code 0 or -
+# Linux: systemctl --user status $(systemd_unit)
 ```

 ## Usage via WhatsApp
@@ -343,10 +353,13 @@ echo '{"content":"Test"}' | pnpm exec tsx .claude/skills/x-integration/scripts/p

 ### Authentication Expired

+Run from your NanoClaw project root:
+
 ```bash
 pnpm exec dotenv -e .env -- pnpm exec tsx .claude/skills/x-integration/scripts/setup.ts
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
-# Linux: systemctl --user restart nanoclaw
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
+# Linux: systemctl --user restart $(systemd_unit)
 ```

 ### Browser Lock Files
@@ -7,7 +7,7 @@ on:

 jobs:
  bump-version:
-    if: github.repository == 'qwibitai/nanoclaw'
+    if: github.repository == 'nanocoai/nanoclaw'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/create-github-app-token@v1
@@ -8,7 +8,7 @@ on:

 jobs:
  update-tokens:
-    if: github.repository == 'qwibitai/nanoclaw'
+    if: github.repository == 'nanocoai/nanoclaw'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/create-github-app-token@v1
@@ -2,7 +2,20 @@

 All notable changes to NanoClaw will be documented in this file.

-For detailed release notes, see the [full changelog on the documentation site](https://docs.nanoclaw.dev/changelog).
+## [2.0.63] - 2026-05-15
+
+Rollup release covering v2.0.55 through v2.0.63 — everything merged since the v2.0.54 tag. Starting with this release, the goal is to publish a GitHub Release for every `package.json` version bump that lands on `main`; see [RELEASING.md](RELEASING.md).
+
+- [BREAKING] **Service names are now per-install.** On v2 installs the launchd label and systemd unit are slugged to your project root: `com.nanoclaw.<sha1(projectRoot)[:8]>` and `nanoclaw-<slug>.service`. The old `com.nanoclaw` / `nanoclaw.service` names no longer match a real service — update any copy-pasted restart or status commands. Find your install's names with `source setup/lib/install-slug.sh && launchd_label` (macOS) or `systemd_unit` (Linux). The `ncl` transport-error help text and 26 skill files now use the canonical helper-driven pattern; see [setup/lib/install-slug.sh](setup/lib/install-slug.sh).
+- **Compaction destination reminder placement fixed.** The reminder injected after SDK auto-compaction now appears at the end of the compaction summary so it isn't stripped during truncation. Replaces the placement shipped in v2.0.54.
+- **Stronger message-wrapping enforcement.** The poll loop nudges the agent when its output lacks `<message>` wrapping, and `CLAUDE.md` core instructions now require wrapping even for single-destination agents. The welcome flow no longer double-greets.
+- **OneCLI credentials after MCP install.** MCP servers added through `add_mcp_server` now inherit OneCLI gateway routing — fixes the case where the agent kept asking for API keys after installing a new server.
+- **CLI scope hardening.** `scopeField` now fails closed when scope is missing, and `sessions get` is guarded against cross-group oracle access from group-scoped agents.
+- **gmail/gcal skills aligned with v2.** `/add-gmail-tool` and `/add-gcal-tool` now reflect the v2 container-config model — DB-backed mounts, no dead `TOOL_ALLOWLIST` edits, no `container.json` writes that get clobbered on next spawn. Manual sqlite3/JSON1 invocations corrected.
+- **Repo-rename cleanup.** Remaining `qwibitai/nanoclaw` references swept to `nanocoai/nanoclaw` across code and docs; CI workflow guards updated so they no longer no-op after the rename.
+- Slack scope checklist now includes `files:read` and `files:write` for skills that read or post attachments.
+- The internal-tag description in destination instructions no longer mentions scratchpads (which confused agents into routing them incorrectly).
+- Container startup is now graceful when the `on_wake` column is missing on older sessions DBs.

 ## [2.0.54] - 2026-05-10

@@ -4,8 +4,8 @@

 1. **Check for existing work.** Search open PRs and issues before starting:
   ```bash
-   gh pr list --repo qwibitai/nanoclaw --search "<your feature>"
-   gh issue list --repo qwibitai/nanoclaw --search "<your feature>"
+   gh pr list --repo nanocoai/nanoclaw --search "<your feature>"
+   gh issue list --repo nanocoai/nanoclaw --search "<your feature>"
   ```
   If a related PR or issue exists, build on it rather than duplicating effort.

@@ -43,7 +43,7 @@ Add capabilities to NanoClaw by merging a git branch. The SKILL.md contains setu
 3. Claude walks through interactive setup (env vars, bot creation, etc.)

 **Contributing a feature skill:**
-1. Fork `qwibitai/nanoclaw` and branch from `main`
+1. Fork `nanocoai/nanoclaw` and branch from `main`
 2. Make the code changes (new files, modified source, updated `package.json`, etc.)
 3. Add a SKILL.md in `.claude/skills/<name>/` with setup instructions — step 1 should be merging the branch
 4. Open a PR. We'll create the `skill/<name>` branch from your work
@@ -26,7 +26,7 @@ NanoClaw provides that same core functionality, but in a codebase small enough t
 ## Quick Start

 ```bash
-git clone https://github.com/qwibitai/nanoclaw.git nanoclaw-v2
+git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
 cd nanoclaw-v2
 bash nanoclaw.sh
 ```
@@ -39,7 +39,7 @@ bash nanoclaw.sh
 Run from a fresh v2 checkout next to your v1 install:

 ```bash
-git clone https://github.com/qwibitai/nanoclaw.git nanoclaw-v2
+git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
 cd nanoclaw-v2
 bash migrate-v2.sh
 ```
@@ -26,7 +26,7 @@ NanoClawは同じコア機能を提供しますが、理解できる規模のコ
 ## クイックスタート

 ```bash
-git clone https://github.com/qwibitai/nanoclaw.git nanoclaw-v2
+git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
 cd nanoclaw-v2
 bash nanoclaw.sh
 ```
@@ -26,7 +26,7 @@ NanoClaw 用一个您能轻松理解的代码库提供了同样的核心功能
 ## 快速开始

 ```bash
-git clone https://github.com/qwibitai/nanoclaw.git nanoclaw-v2
+git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
 cd nanoclaw-v2
 bash nanoclaw.sh
 ```
@@ -0,0 +1,50 @@
+# Releasing NanoClaw
+
+Starting with v2.0.63, the goal is to publish a GitHub Release for every `package.json` version bump that lands on `main`. Releases are cut manually by a maintainer, so there can be lag between a bump merging and its release being published. The intent is *timeliness*, not strict 1:1 correlation with every bump.
+
+Each release ships:
+
+- A tagged commit on `main` (`vX.Y.Z`).
+- A `CHANGELOG.md` entry under `## [<version>] - <YYYY-MM-DD>`.
+- A GitHub Release whose body mirrors the CHANGELOG entry plus a contributors section.
+
+## When to cut a release
+
+A release is cut by a maintainer publishing it. The trigger is a `package.json` bump on `main`, but the publish step is manual — there is no fixed schedule, and bumps that land back-to-back may be rolled into a single release (as v2.0.55 through v2.0.63 were). Cutting more frequently is preferable to batching: smaller releases are easier to read, pin, and revert.
+
+## What goes in a release
+
+`CHANGELOG.md` is the canonical record of user-visible change. The release body on GitHub mirrors it. Aim for:
+
+- **Bold lead-ins** per major feature or fix, then a sentence-case prose explanation.
+- **`[BREAKING]` prefix** for any change that requires user action. Always include the workaround inline — never link to a separate doc for the fix.
+- **Doc links** for major features (relative paths into the repo, e.g. `[setup/lib/install-slug.sh](setup/lib/install-slug.sh)`).
+- **Inline commands** for actionable steps, in backticks.
+- **Minor items** as single plain bullets at the bottom of the entry, no bold lead-in.
+- **No PR numbers** in the user-facing prose. PR references can live in the GitHub Release's `## Contributors` section.
+
+## Publishing the release
+
+1. Bump `package.json` and add a `CHANGELOG.md` entry in the same commit (commit message: `chore: bump version to vX.Y.Z`).
+2. Once the bump commit lands on `main`, open a draft GitHub Release:
+   - **Tag:** `vX.Y.Z`, target `main`.
+   - **Title:** `vX.Y.Z` (bare version — descriptive content lives in the body, matching the CHANGELOG header pattern).
+   - **Body:** copy the CHANGELOG entry verbatim. Append a `## Contributors` section listing every PR author who landed work in the release window. Append a `**Full Changelog**: https://github.com/nanocoai/nanoclaw/compare/<prev-tag>...vX.Y.Z` line at the bottom.
+3. If anyone in the window opened their first NanoClaw PR, add a `## New Contributors` section above `## Contributors`, with each first-timer's first PR link and an invite to Discord.
+4. Publish (not just save draft).
+
+## Rollup releases
+
+If multiple `package.json` bumps land between two GitHub Releases (as happened between v2.0.54 and v2.0.63), the next release is a rollup: its CHANGELOG entry covers everything merged since the last released tag, and the body opens with a one-line "Rollup release covering vX.Y.Z through vX.Y.W." note. After the catchup, return to one release per bump.
+
+## Channels and stability
+
+NanoClaw currently ships a single channel: every published release is a stable release.
+
+- **Latest** — the most recent release on `main`, shown as "Latest release" on the GitHub Releases page. Consumers that want auto-bump follow GitHub's `/releases/latest` pointer.
+- **Stable** — currently identical to latest. NanoClaw has no separate stable branch and no pre-release/RC channel.
+- **Pinned** — any tagged release. Reproducible and the recommended choice for packagers and forks; published tags are not moved or retracted.
+
+If a pre-release channel is introduced later (e.g. `vX.Y.Z-rc.N`), those releases will be marked "Pre-release" on GitHub so they do not become the `latest` pointer, and this section will be updated to describe the promotion path.
+
+The tag is the source of truth — a GitHub Release's `target_commitish` always points to a tagged commit.
@@ -26,9 +26,9 @@ const instructions = [
  '2. Preserve the chronological message/reply sequence of recent exchanges.',
  '   The agent needs to see: who said what, in what order, and from which destination.',
  '',
-  '3. The `from` attribute identifies which destination sent the message.',
-  '   The agent MUST wrap all responses in <message to="name">...</message> blocks.',
-  `   Available destinations: ${names.length > 0 ? names.map((n) => `\`${n}\``).join(', ') : '(none)'}`,
+  '3. At the END of the compaction summary, include this verbatim reminder:',
+  '   "You MUST wrap all responses in <message to="name">...</message> blocks.',
+  `   Available destinations: ${names.length > 0 ? names.map((n) => `\`${n}\``).join(', ') : '(none)'}."`,
 ];

 console.log(instructions.join('\n'));
@@ -10,6 +10,19 @@
 import { getConfig } from '../config.js';
 import { openInboundDb, getOutboundDb } from './connection.js';

+// Cache whether inbound.db has the on_wake column (added in v2.0.48).
+// The container opens inbound.db read-only, so it can't ALTER —
+// gracefully degrade when running against an older session DB.
+let _hasOnWake: boolean | null = null;
+function hasOnWakeColumn(db: ReturnType<typeof openInboundDb>): boolean {
+  if (_hasOnWake !== null) return _hasOnWake;
+  const cols = new Set(
+    (db.prepare("PRAGMA table_info('messages_in')").all() as Array<{ name: string }>).map((c) => c.name),
+  );
+  _hasOnWake = cols.has('on_wake');
+  return _hasOnWake;
+}
+
 export interface MessageInRow {
  id: string;
  seq: number | null;
@@ -54,12 +67,13 @@ export function getPendingMessages(isFirstPoll = false): MessageInRow[] {
  const outbound = getOutboundDb();

  try {
+    const onWakeFilter = hasOnWakeColumn(inbound) ? 'AND (on_wake = 0 OR ?1 = 1)' : '';
    const pending = inbound
      .prepare(
        `SELECT * FROM messages_in
         WHERE status = 'pending'
           AND (process_after IS NULL OR datetime(process_after) <= datetime('now'))
-           AND (on_wake = 0 OR ?1 = 1)
+           ${onWakeFilter}
         ORDER BY seq DESC
         LIMIT ?2`,
      )
@@ -27,18 +27,18 @@ describe('buildSystemPromptAddendum — multi-destination routing guidance', ()

    const prompt = buildSystemPromptAddendum('Casa');

-    expect(prompt).toContain('Default routing');
+    expect(prompt).toContain('default to addressing the destination it came `from`');
    expect(prompt).toContain('from="name"');
    expect(prompt).toContain('`casa`');
    expect(prompt).toContain('`whatsapp-mg-17780`');
  });

-  it('requires explicit wrapping even for a single destination', () => {
+  it('describes message wrapping for a single destination', () => {
    seedDestination('casa', 'Casa', 'whatsapp', 'group-1@g.us');

    const prompt = buildSystemPromptAddendum('Casa');

-    expect(prompt).toContain('Every response must be wrapped');
+    expect(prompt).toContain('Wrap each delivered message');
    expect(prompt).toContain('<message to="name">');
    expect(prompt).toContain('`casa`');
  });
@@ -47,7 +47,7 @@ describe('buildSystemPromptAddendum — multi-destination routing guidance', ()
    const prompt = buildSystemPromptAddendum('Casa');

    expect(prompt).toContain('no configured destinations');
-    expect(prompt).not.toContain('Default routing');
+    expect(prompt).not.toContain('default to addressing');
  });

  it('includes default-routing and wrapping instructions for single destination', () => {
@@ -55,9 +55,9 @@ describe('buildSystemPromptAddendum — multi-destination routing guidance', ()

    const prompt = buildSystemPromptAddendum('Casa');

-    expect(prompt).toContain('Every response must be wrapped');
+    expect(prompt).toContain('Wrap each delivered message');
    expect(prompt).toContain('<message to="name">');
-    expect(prompt).toContain('Default routing');
+    expect(prompt).toContain('default to addressing the destination it came `from`');
    expect(prompt).toContain('`casa`');
  });
 });
@@ -115,17 +115,16 @@ function buildDestinationsSection(): string {
    }
  }
  lines.push('');
-  lines.push('**Every response must be wrapped** in a `<message to="name">...</message>` block.');
-  lines.push('You can include multiple `<message>` blocks in one response to send to multiple destinations.');
-  lines.push('Text outside of `<message>` blocks is scratchpad — logged but not sent anywhere.');
-  lines.push('Use `<internal>...</internal>` to make scratchpad intent explicit.');
-  lines.push('');
  lines.push(
-    '**Default routing**: when replying to an incoming message, address the same destination the message came `from` — every inbound `<message>` tag carries a `from="name"` attribute that names the origin destination. Only address a different destination when the request itself asks you to (e.g., "tell Laura that…").',
+    'Wrap each delivered message in a `<message to="name">…</message>` block; include several blocks in one response to address several destinations. `<internal>…</internal>` marks thinking you don\'t want sent.',
  );
  lines.push('');
  lines.push(
-    'To send a message mid-response (e.g., an acknowledgment before a long task), call the `send_message` MCP tool with the `to` parameter set to a destination name.',
+    'When replying to an incoming message, default to addressing the destination it came `from` (every inbound `<message>` tag carries a `from="name"` attribute). Pick a different destination when the request asks for it (e.g., "tell Laura that…").',
+  );
+  lines.push('');
+  lines.push(
+    'The `send_message` MCP tool is the same delivery, available mid-turn — handy for a quick acknowledgment ("on it") before a slow tool call. Each `send_message` call and each final-response `<message>` block lands as its own message in the conversation, so they read as a sequence rather than as one combined reply.',
  );
  return lines.join('\n');
 }
@@ -295,115 +295,8 @@ describe('poll loop integration', () => {
    await loopPromise.catch(() => {});
  });

-  it('should inject destination reminder after a compacted event', async () => {
-    // Two destinations — required for the reminder to fire (single-destination
-    // groups have a fallback path that works without <message to="…"> wrapping).
-    getInboundDb()
-      .prepare(
-        `INSERT INTO destinations (name, display_name, type, channel_type, platform_id, agent_group_id)
-         VALUES ('discord-second', 'Discord Second', 'channel', 'discord', 'chan-2', NULL)`,
-      )
-      .run();
-
-    insertMessage('m1', { sender: 'Alice', text: 'First message' }, { platformId: 'chan-1', channelType: 'discord' });
-
-    const provider = new CompactingProvider();
-    const controller = new AbortController();
-    const loopPromise = runPollLoopWithTimeout(provider as unknown as MockProvider, controller.signal, 2500);
-
-    await waitFor(() => getUndeliveredMessages().length > 0, 2500);
-    controller.abort();
-
-    expect(provider.pushes.length).toBeGreaterThanOrEqual(1);
-    const reminder = provider.pushes.find((p) => p.includes('Context was just compacted'));
-    expect(reminder).toBeDefined();
-    expect(reminder).toContain('2 destinations');
-    expect(reminder).toContain('discord-test');
-    expect(reminder).toContain('discord-second');
-    expect(reminder).toContain('<message to="name">');
-
-    await loopPromise.catch(() => {});
-  });
-
-  it('should NOT inject destination reminder with a single destination', async () => {
-    insertMessage('m1', { sender: 'Alice', text: 'First message' }, { platformId: 'chan-1', channelType: 'discord' });
-
-    const provider = new CompactingProvider();
-    const controller = new AbortController();
-    const loopPromise = runPollLoopWithTimeout(provider as unknown as MockProvider, controller.signal, 2500);
-
-    await waitFor(() => getUndeliveredMessages().length > 0, 2500);
-    controller.abort();
-
-    // Only the original prompt push (if any) — no reminder, since beforeEach
-    // seeds exactly one destination.
-    const reminders = provider.pushes.filter((p) => p.includes('Context was just compacted'));
-    expect(reminders).toHaveLength(0);
-
-    await loopPromise.catch(() => {});
-  });
 });

-/**
- * Provider that emits a single compacted event mid-stream, then returns a
- * result. Captures every push() call so tests can assert on the injected
- * reminder content.
- */
-class CompactingProvider {
-  readonly supportsNativeSlashCommands = false;
-  readonly pushes: string[] = [];
-
-  isSessionInvalid(): boolean {
-    return false;
-  }
-
-  query(_input: { prompt: string; cwd: string }) {
-    const pushes = this.pushes;
-    let ended = false;
-    let aborted = false;
-    let resolveWaiter: (() => void) | null = null;
-
-    async function* events() {
-      yield { type: 'activity' as const };
-      yield { type: 'init' as const, continuation: 'compaction-test-session' };
-      yield { type: 'activity' as const };
-      yield { type: 'compacted' as const, text: 'Context compacted (50,000 tokens compacted).' };
-
-      // Wait for poll-loop to push the reminder (or end / abort)
-      await new Promise<void>((resolve) => {
-        resolveWaiter = resolve;
-        // Belt-and-braces: don't hang forever if the reminder never arrives
-        setTimeout(resolve, 200);
-      });
-
-      yield { type: 'activity' as const };
-      yield { type: 'result' as const, text: '<message to="discord-test">ack</message>' };
-      while (!ended && !aborted) {
-        await new Promise<void>((resolve) => {
-          resolveWaiter = resolve;
-          setTimeout(resolve, 50);
-        });
-      }
-    }
-
-    return {
-      push(message: string) {
-        pushes.push(message);
-        resolveWaiter?.();
-      },
-      end() {
-        ended = true;
-        resolveWaiter?.();
-      },
-      abort() {
-        aborted = true;
-        resolveWaiter?.();
-      },
-      events: events(),
-    };
-  }
-}
-
 // Helper: run poll loop until aborted or timeout
 async function runPollLoopWithTimeout(provider: MockProvider, signal: AbortSignal, timeoutMs: number): Promise<void> {
  return Promise.race([
@@ -1,6 +1,6 @@
 ## Sending messages

-Your final response is delivered via the `## Sending messages` rules in your runtime system prompt (single-destination: just write; multi-destination: use `<message to="name">...</message>` blocks). See that section for the current destination list.
+**Every response** must be wrapped in `<message to="name">...</message>` blocks — even if you only have one destination. Bare text outside of `<message>` blocks is scratchpad (logged but never sent). See the `## Sending messages` section in your runtime system prompt for the current destination list and names.

 ### Mid-turn updates (`send_message`)

@@ -22,4 +22,4 @@ Use **`add_mcp_server`** to add an MCP server to your configuration. Browse avai
 add_mcp_server({ name: "memory", command: "pnpm", args: ["dlx", "@modelcontextprotocol/server-memory"] })
 ```

-Do not ask the user to give you credentials. Credentials are managed by the user in the OneCLI agent vault. Add a "placeholder" string instead of the credential, and ask the user to add the credential to the vault. You can make a test request before the secret is added and the vault proxy will respond with the local url of the vault dashboard on the user's machine and a link to a form for adding that specific credential.
+Do not ask the user to give you credentials or tell them how to create credentials (OAuth, API keys, etc.) — NEVER fabricate credential setup instructions. Credentials are handled by the OneCLI gateway. Use `"onecli-managed"` as the placeholder value for any credential env vars or config fields. After the MCP server is installed and the container restarts, load `/onecli-gateway` for the full credential-handling flow (connect URLs, stubs, error recovery).
@@ -265,6 +265,7 @@ async function processQuery(
 ): Promise<QueryResult> {
  let queryContinuation: string | undefined;
  let done = false;
+  let unwrappedNudged = false;

  // Concurrent polling: push follow-ups into the active query as they arrive.
  // We do NOT force-end the stream on silence — keeping the query open avoids
@@ -338,6 +339,7 @@ async function processQuery(
        const keptIds = keep.map((m) => m.id);
        const prompt = formatMessages(keep);
        log(`Pushing ${keep.length} follow-up message(s) into active query`);
+        unwrappedNudged = false;
        query.push(prompt);
        markCompleted(keptIds);
      } catch (err) {
@@ -376,24 +378,18 @@ async function processQuery(
        // at all — either way the turn is finished.
        markCompleted(initialBatchIds);
        if (event.text) {
-          dispatchResultText(event.text, routing);
-        }
-      } else if (event.type === 'compacted') {
-        // The SDK auto-compacted the conversation. After compaction the
-        // model often drops the learned `<message to="…">` wrapping
-        // discipline (the destinations are still in the system prompt,
-        // but the behavioral pattern is summarized away). Inject a
-        // reminder back into the live query so the next turn re-anchors
-        // on the destination model. Only do this when there's >1
-        // destination — single-destination groups have a fallback that
-        // works without wrapping. See qwibitai/nanoclaw#2325.
-        const destinations = getAllDestinations();
-        if (destinations.length > 1) {
-          const names = destinations.map((d) => d.name).join(', ');
-          query.push(
-            `[system] Context was just compacted. Reminder: you have ${destinations.length} destinations (${names}). ` +
-              `Use <message to="name"> blocks to address them. Bare text goes to the scratchpad fallback only.`,
-          );
+          const { hasUnwrapped } = dispatchResultText(event.text, routing);
+          if (hasUnwrapped && !unwrappedNudged) {
+            unwrappedNudged = true;
+            const destinations = getAllDestinations();
+            const names = destinations.map((d) => d.name).join(', ');
+            query.push(
+              `<system>Your response was not delivered — it was not wrapped in <message to="name">...</message> blocks. ` +
+                `All output must be wrapped: use <message to="name"> for content to send, or <internal> for scratchpad. ` +
+                `Your destinations: ${names}. ` +
+                `Please re-send your response with the correct wrapping.</system>`,
+            );
+          }
        }
      }
    }
@@ -421,9 +417,6 @@ function handleEvent(event: ProviderEvent, _routing: RoutingContext): void {
    case 'progress':
      log(`Progress: ${event.message}`);
      break;
-    case 'compacted':
-      log(`Compacted: ${event.text}`);
-      break;
  }
 }

@@ -435,7 +428,7 @@ function handleEvent(event: ProviderEvent, _routing: RoutingContext): void {
 * The agent must always wrap output in <message to="name">...</message>
 * blocks, even with a single destination. Bare text is scratchpad only.
 */
-function dispatchResultText(text: string, routing: RoutingContext): void {
+function dispatchResultText(text: string, routing: RoutingContext): { sent: number; hasUnwrapped: boolean } {
  const MESSAGE_RE = /<message\s+to="([^"]+)"\s*>([\s\S]*?)<\/message>/g;

  let match: RegExpExecArray | null;
@@ -470,9 +463,11 @@ function dispatchResultText(text: string, routing: RoutingContext): void {
    log(`[scratchpad] ${scratchpad.slice(0, 500)}${scratchpad.length > 500 ? '…' : ''}`);
  }

-  if (sent === 0 && text.trim()) {
+  const hasUnwrapped = sent === 0 && !!scratchpad;
+  if (hasUnwrapped) {
    log(`WARNING: agent output had no <message to="..."> blocks — nothing was sent`);
  }
+  return { sent, hasUnwrapped };
 }

 function sendToDestination(dest: DestinationEntry, body: string, routing: RoutingContext): void {
@@ -336,7 +336,7 @@ export class ClaudeProvider implements AgentProvider {
        } else if (message.type === 'system' && (message as { subtype?: string }).subtype === 'compact_boundary') {
          const meta = (message as { compact_metadata?: { pre_tokens?: number } }).compact_metadata;
          const detail = meta?.pre_tokens ? ` (${meta.pre_tokens.toLocaleString()} tokens compacted)` : '';
-          yield { type: 'compacted', text: `Context compacted${detail}.` };
+          yield { type: 'result', text: `Context compacted${detail}.` };
        } else if (message.type === 'system' && (message as { subtype?: string }).subtype === 'task_notification') {
          const tn = message as { summary?: string };
          yield { type: 'progress', message: tn.summary || 'Task notification' };
@@ -89,12 +89,4 @@ export type ProviderEvent =
   * event (tool call, thinking, partial message, anything) so the
   * poll-loop's idle timer stays honest during long tool runs.
   */
-  | { type: 'activity' }
-  /**
-   * The provider's underlying SDK auto-compacted the conversation context.
-   * The poll-loop reacts by injecting a destination reminder back into
-   * the live query so the agent doesn't drop `<message to="…">` wrapping
-   * after compaction. Distinct from `result` so it doesn't mark the turn
-   * completed or get dispatched as a chat message. See qwibitai/nanoclaw#2325.
-   */
-  | { type: 'compacted'; text: string };
+  | { type: 'activity' };
@@ -4,4 +4,4 @@ Your HTTP requests go through the OneCLI proxy, which injects real credentials a

 Use any method: curl, Python, a CLI tool, whatever fits. If a tool checks for credentials locally, pass any placeholder value — the proxy replaces it with real credentials at request time.

-If you get a `401`/`403`/`app_not_connected`, run `/onecli-gateway` for the full error-handling flow. Never ask the user for API keys or tokens — if credentials are missing, the fix is connecting the service in OneCLI.
+If you get a `401`/`403`/`app_not_connected`, the error response contains a `connect_url` — you MUST show it to the user as a bare URL on its own line (no angle brackets, no markdown link syntax) so they can click to connect. Run `/onecli-gateway` for the full error-handling flow. Never ask the user for API keys or tokens.
@@ -9,7 +9,7 @@ You've just been connected to a new user. This your time to shine and make a str

 ## What to do

-1. Send a short, warm greeting using `send_message`
+1. Send a short, warm greeting
 2. State your name (from your system prompt / CLAUDE.md)
 3. Signal that you're capable of a lot — but don't list everything upfront. Be intriguing, not encyclopedic
 4. Ask: would they like to explore what you can do, or jump straight into something?
@@ -2,7 +2,7 @@

 ## Structure

-**`qwibitai/nanoclaw`** (upstream) — core engine with skill definitions (`.claude/skills/`). No channel code on `main`.
+**`nanocoai/nanoclaw`** (upstream) — core engine with skill definitions (`.claude/skills/`). No channel code on `main`.

 **Channel forks** (`nanoclaw-whatsapp`, `nanoclaw-telegram`, `nanoclaw-slack`, etc.) — each fork = upstream + one channel's code applied. Users clone upstream, then merge a fork into their clone to add a channel.

@@ -77,7 +77,7 @@ NanoClaw must live inside the workspace directory — Docker-in-Docker can only
 ```bash
 # Clone to home first (virtiofs can corrupt git pack files during clone)
 cd ~
-git clone https://github.com/qwibitai/nanoclaw.git
+git clone https://github.com/nanocoai/nanoclaw.git

 # Replace with YOUR workspace path (the host path you passed to `docker sandbox create`)
 WORKSPACE=/Users/you/nanoclaw-workspace
@@ -347,7 +347,7 @@ docker sandbox network proxy <sandbox-name> \
 ### Git clone fails with "inflate: data stream error"
 Clone to a non-workspace path first, then move:
 ```bash
-cd ~ && git clone https://github.com/qwibitai/nanoclaw.git && mv nanoclaw /path/to/workspace/nanoclaw
+cd ~ && git clone https://github.com/nanocoai/nanoclaw.git && mv nanoclaw /path/to/workspace/nanoclaw
 ```

 ### WhatsApp QR code doesn't display
@@ -23,7 +23,7 @@ This replaces the previous `skills-engine/` system (three-way file merging, `.na

 ### Repository structure

-The upstream repo (`qwibitai/nanoclaw`) maintains:
+The upstream repo (`nanocoai/nanoclaw`) maintains:

 - `main` — core NanoClaw (no skill code)
 - `skill/discord` — main + Discord integration
@@ -46,7 +46,7 @@ Skills are split into two categories:
 **Feature skills** (in marketplace, installed on demand):
 - `/add-discord`, `/add-telegram`, `/add-slack`, `/add-gmail`, etc.
 - Each has a SKILL.md with setup instructions and a corresponding `skill/*` branch with code
- Live in the marketplace repo (`qwibitai/nanoclaw-skills`)
+- Live in the marketplace repo (`nanocoai/nanoclaw-skills`)

 Users never interact with the marketplace directly. The operational skills `/setup` and `/customize` handle plugin installation transparently:

@@ -78,7 +78,7 @@ NanoClaw's `.claude/settings.json` registers the official marketplace:
    "nanoclaw-skills": {
      "source": {
        "source": "github",
-        "repo": "qwibitai/nanoclaw-skills"
+        "repo": "nanocoai/nanoclaw-skills"
      }
    }
  }
@@ -88,7 +88,7 @@ NanoClaw's `.claude/settings.json` registers the official marketplace:
 The marketplace repo uses Claude Code's plugin structure:

 ```
-qwibitai/nanoclaw-skills/
+nanocoai/nanoclaw-skills/
  .claude-plugin/
    marketplace.json              # Plugin catalog
  plugins/
@@ -213,7 +213,7 @@ A GitHub Action runs on every push to `main`:

 ### New users (recommended)

-1. Fork `qwibitai/nanoclaw` on GitHub (click the Fork button)
+1. Fork `nanocoai/nanoclaw` on GitHub (click the Fork button)
 2. Clone your fork:
   ```bash
   git clone https://github.com/<you>/nanoclaw.git
@@ -229,9 +229,9 @@ Forking is recommended because it gives users a remote to push their customizati

 ### Existing users migrating from clone

-Users who previously ran `git clone https://github.com/qwibitai/nanoclaw.git` and have local customizations:
+Users who previously ran `git clone https://github.com/nanocoai/nanoclaw.git` and have local customizations:

-1. Fork `qwibitai/nanoclaw` on GitHub
+1. Fork `nanocoai/nanoclaw` on GitHub
 2. Reroute remotes:
   ```bash
   git remote rename origin upstream
@@ -239,7 +239,7 @@ Users who previously ran `git clone https://github.com/qwibitai/nanoclaw.git` an
   git push --force origin main
   ```
   The `--force` is needed because the fresh fork's main is at upstream's latest, but the user wants their (possibly behind) version. The fork was just created so there's nothing to lose.
-3. From this point, `origin` = their fork, `upstream` = qwibitai/nanoclaw
+3. From this point, `origin` = their fork, `upstream` = nanocoai/nanoclaw

 ### Existing users migrating from the old skills engine

@@ -316,7 +316,7 @@ git fetch upstream main
 git checkout -b my-fix upstream/main
 # Make changes
 git push origin my-fix
-# Create PR from my-fix to qwibitai/nanoclaw:main
+# Create PR from my-fix to nanocoai/nanoclaw:main
 ```

 Standard fork contribution workflow. Their custom changes stay on their main and don't leak into the PR.
@@ -327,7 +327,7 @@ The flow below is for **feature skills** (branch-based). For utility skills (sel

 ### Contributor flow (feature skills)

-1. Fork `qwibitai/nanoclaw`
+1. Fork `nanocoai/nanoclaw`
 2. Branch from `main`
 3. Make the code changes (new channel file, modified integration points, updated package.json, .env.example additions, etc.)
 4. Open a PR to `main`
@@ -345,7 +345,7 @@ When a skill PR is reviewed and approved:
   ```
 2. Force-push to the contributor's PR branch, replacing it with a single commit that adds the contributor to `CONTRIBUTORS.md` (removing all code changes)
 3. Merge the slimmed PR into `main` (just the contributor addition)
-4. Add the skill's SKILL.md to the marketplace repo (`qwibitai/nanoclaw-skills`)
+4. Add the skill's SKILL.md to the marketplace repo (`nanocoai/nanoclaw-skills`)

 This way:
 - The contributor gets merge credit (their PR is merged)
@@ -388,7 +388,7 @@ If the community contributor is trusted, they can open a PR to add their marketp
    "nanoclaw-skills": {
      "source": {
        "source": "github",
-        "repo": "qwibitai/nanoclaw-skills"
+        "repo": "nanocoai/nanoclaw-skills"
      }
    },
    "alice-nanoclaw-skills": {
@@ -434,7 +434,7 @@ A flavor is a curated fork of NanoClaw — a combination of skills, custom chang

 ### Creating a flavor

-1. Fork `qwibitai/nanoclaw`
+1. Fork `nanocoai/nanoclaw`
 2. Merge in the skills you want
 3. Make custom changes (trigger word, prompts, integrations, etc.)
 4. Your fork's `main` IS the flavor
@@ -462,7 +462,7 @@ Then setup continues normally (dependencies, auth, container, service).

 After installation, the user's fork has three remotes:
 - `origin` — their fork (push customizations here)
- `upstream` — `qwibitai/nanoclaw` (core updates)
+- `upstream` — `nanocoai/nanoclaw` (core updates)
 - `<flavor-name>` — the flavor fork (flavor updates)

 ### Updating a flavor
@@ -538,14 +538,14 @@ Operational skills (`setup`, `debug`, `update-nanoclaw`, `customize`, `update-sk

 Before:
 ```bash
-git clone https://github.com/qwibitai/NanoClaw.git
+git clone https://github.com/nanocoai/NanoClaw.git
 cd NanoClaw
 claude
 ```

 After:
 ```
-1. Fork qwibitai/nanoclaw on GitHub
+1. Fork nanocoai/nanoclaw on GitHub
 2. git clone https://github.com/<you>/nanoclaw.git
 3. cd nanoclaw
 4. claude
@@ -556,8 +556,8 @@ After:

 Updates to the setup flow:

- Check if `upstream` remote exists; if not, add it: `git remote add upstream https://github.com/qwibitai/nanoclaw.git`
- Check if `origin` points to the user's fork (not qwibitai). If it points to qwibitai, guide them through the fork migration.
+- Check if `upstream` remote exists; if not, add it: `git remote add upstream https://github.com/nanocoai/nanoclaw.git`
+- Check if `origin` points to the user's fork (not nanocoai). If it points to nanocoai, guide them through the fork migration.
 - **Install marketplace plugin:** `claude plugin install nanoclaw-skills@nanoclaw-skills --scope project` — makes all feature skills available (hot-loaded, no restart)
 - **Ask which channels to add:** present channel options (Discord, Telegram, Slack, WhatsApp, Gmail), run corresponding `/add-*` skills for selected channels
 - **Offer dependent skills:** after a channel is set up, offer relevant add-ons (e.g., Agent Swarm after Telegram, voice transcription after WhatsApp)
@@ -573,7 +573,7 @@ Marketplace configuration so the official marketplace is auto-registered:
    "nanoclaw-skills": {
      "source": {
        "source": "github",
-        "repo": "qwibitai/nanoclaw-skills"
+        "repo": "nanocoai/nanoclaw-skills"
      }
    }
  }
@@ -601,7 +601,7 @@ Operational skills (`setup`, `debug`, `update-nanoclaw`, `customize`, `update-sk

 ### New infrastructure

- **Marketplace repo** (`qwibitai/nanoclaw-skills`) — single Claude Code plugin bundling SKILL.md files for all feature skills
+- **Marketplace repo** (`nanocoai/nanoclaw-skills`) — single Claude Code plugin bundling SKILL.md files for all feature skills
 - **CI GitHub Action** — merge-forward `main` into all `skill/*` branches on every push to `main`, using Claude (Haiku) for conflict resolution
 - **`/update-skills` skill** — checks for and applies skill branch updates using git history
 - **`CONTRIBUTORS.md`** — tracks skill contributors
@@ -650,7 +650,7 @@ Users only need to re-merge a skill branch if the skill itself was updated (not
 > **We now recommend forking instead of cloning.** This gives you a remote to push your customizations to.
 >
 > **If you currently have a clone with local changes**, migrate to a fork:
-> 1. Fork `qwibitai/nanoclaw` on GitHub
+> 1. Fork `nanocoai/nanoclaw` on GitHub
 > 2. Run:
 >    ```
 >    git remote rename origin upstream
@@ -668,7 +668,7 @@ Users only need to re-merge a skill branch if the skill itself was updated (not
 > **Contributing skills**
 >
 > To contribute a skill:
-> 1. Fork `qwibitai/nanoclaw`
+> 1. Fork `nanocoai/nanoclaw`
 > 2. Branch from `main` and make your code changes
 > 3. Open a regular PR
 >
@@ -240,7 +240,7 @@ if [ "$(uname -s)" = "Linux" ] && [ "$(id -u)" -eq 0 ]; then
      printf '  %s\n' "$(dim '3. Enable passwordless sudo:    echo "nanoclaw ALL=(ALL) NOPASSWD:ALL" | tee /etc/sudoers.d/nanoclaw')"
      printf '  %s\n' "$(dim '4. Log out:                     exit')"
      printf '  %s\n' "$(dim '5. Log back in as the new user: ssh nanoclaw@your-server')"
-      printf '  %s\n' "$(dim '6. Clone the repo:              git clone https://github.com/qwibitai/nanoclaw.git && cd nanoclaw')"
+      printf '  %s\n' "$(dim '6. Clone the repo:              git clone https://github.com/nanocoai/nanoclaw.git && cd nanoclaw')"
      printf '  %s\n\n' "$(dim '7. Re-run setup:               bash nanoclaw.sh')"
      exit 1
      ;;
@@ -1,6 +1,6 @@
 {
  "name": "nanoclaw",
-  "version": "2.0.54",
+  "version": "2.0.63",
  "description": "Personal Claude assistant. Lightweight, secure, customizable.",
  "type": "module",
  "packageManager": "pnpm@10.33.0",
@@ -12,7 +12,7 @@ A GitHub Action that calculates the size of your codebase in terms of tokens and
 ## Usage

 ```yaml
- uses: qwibitai/nanoclaw/repo-tokens@v1
+- uses: nanocoai/nanoclaw/repo-tokens@v1
  with:
    include: 'src/**/*.ts'
    exclude: 'src/**/*.test.ts'
@@ -34,7 +34,7 @@ Repos using repo-tokens:

 | Repo | Badge |
 |------|-------|
-| [NanoClaw](https://github.com/qwibitai/NanoClaw) | ![tokens](https://raw.githubusercontent.com/qwibitai/NanoClaw/main/repo-tokens/badge.svg) |
+| [NanoClaw](https://github.com/nanocoai/NanoClaw) | ![tokens](https://raw.githubusercontent.com/nanocoai/NanoClaw/main/repo-tokens/badge.svg) |

 ### Full workflow example

@@ -59,7 +59,7 @@ jobs:
        with:
          python-version: '3.12'

-      - uses: qwibitai/nanoclaw/repo-tokens@v1
+      - uses: nanocoai/nanoclaw/repo-tokens@v1
        id: tokens
        with:
          include: 'src/**/*.ts'
@@ -114,7 +114,7 @@ runs:
        with open(readme_path, "r", encoding="utf-8") as f:
            content = f.read()

-        repo_tokens_url = "https://github.com/qwibitai/nanoclaw/tree/main/repo-tokens"
+        repo_tokens_url = "https://github.com/nanocoai/nanoclaw/tree/main/repo-tokens"
        linked_badge = f'<a href="{repo_tokens_url}">{badge}</a>'
        new_content = marker_re.sub(rf"\1{linked_badge}\2", content)

@@ -148,7 +148,7 @@ runs:
            lx = label_w // 2
            vx = label_w + value_w // 2

-            repo_tokens_url = "https://github.com/qwibitai/nanoclaw/tree/main/repo-tokens"
+            repo_tokens_url = "https://github.com/nanocoai/nanoclaw/tree/main/repo-tokens"

            svg = f'''<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="{total_w}" height="20" role="img" aria-label="{full_desc}">
          <title>{full_desc}</title>
@@ -7,7 +7,7 @@
  <clipPath id="r">
    <rect width="90" height="20" rx="3" fill="#fff"/>
  </clipPath>
-  <a xlink:href="https://github.com/qwibitai/nanoclaw/tree/main/repo-tokens">
+  <a xlink:href="https://github.com/nanocoai/nanoclaw/tree/main/repo-tokens">
    <g clip-path="url(#r)">
      <rect width="52" height="20" fill="#555"/>
      <rect x="52" width="38" height="20" fill="#e05d44"/>
@@ -146,6 +146,7 @@ async function walkThroughAppCreation(): Promise<'continue' | 'back'> {
      '     • chat:write',
      '     • users:read',
      '     • reactions:write',
+      '     • files:read, files:write',
      '  3. App Home → enable "Messages Tab" and "Allow users to send',
      '     slash commands and messages from the messages tab"',
      '  4. Basic Information → copy the "Signing Secret"',
@@ -6,10 +6,10 @@
 # `upstream`, with `origin` pointing at the user's fork. The channels branch
 # only lives upstream, so a hardcoded `git fetch origin channels` fails for
 # forks. This helper walks `git remote -v`, picks the remote whose URL points
-# at qwibitai/nanoclaw, and prints its name.
+# at nanocoai/nanoclaw, and prints its name.
 #
 # Fallback: if no existing remote matches, add `upstream` pointing at
-# github.com/qwibitai/nanoclaw and return that — keeps forks without an
+# github.com/nanocoai/nanoclaw and return that — keeps forks without an
 # explicit upstream configured working on the first try.
 #
 # Explicit override: set NANOCLAW_CHANNELS_REMOTE=<name> to skip detection.
@@ -23,7 +23,7 @@ resolve_channels_remote() {
  local remote url
  while IFS=$'\t' read -r remote url; do
    case "$url" in
-      *qwibitai/nanoclaw*)
+      *qwibitai/nanoclaw*|*nanocoai/nanoclaw*)
        printf '%s' "$remote"
        return 0
        ;;
@@ -33,6 +33,6 @@ resolve_channels_remote() {
  # No matching remote — add `upstream` and use it. Silent on failure so
  # callers see the eventual `git fetch` error rather than a cryptic
  # remote-add failure.
-  git remote add upstream https://github.com/qwibitai/nanoclaw.git 2>/dev/null || true
+  git remote add upstream https://github.com/nanocoai/nanoclaw.git 2>/dev/null || true
  printf '%s' "upstream"
 }
@@ -66,7 +66,7 @@ async function getJson<T>(url: string, token: string, fetchImpl: FetchFn): Promi
  const res = await fetchImpl(url, {
    headers: {
      Authorization: `Bot ${token}`,
-      'User-Agent': 'NanoClaw-Migration (https://github.com/qwibitai/nanoclaw, 2.x)',
+      'User-Agent': 'NanoClaw-Migration (https://github.com/nanocoai/nanoclaw, 2.x)',
    },
  });
  if (!res.ok) {
@@ -105,6 +105,7 @@ function writeEnvOnecliUrl(url: string): void {
 // Last-known-good CLI release. Used only if BOTH the upstream installer
 // and the redirect-based version probe fail. Bump deliberately when a
 // new CLI release ships.
+const ONECLI_GATEWAY_VERSION = '1.23.0';
 const ONECLI_CLI_FALLBACK_VERSION = '1.3.0';
 const ONECLI_CLI_REPO = 'onecli/onecli-cli';

@@ -153,7 +154,7 @@ function installOnecli(): { stdout: string; ok: boolean } {
  if (cleanup) stdout += cleanup + '\n';

  // Gateway install (docker-compose based, no rate-limit concerns).
-  const gw = runInstall('curl -fsSL onecli.sh/install | sh');
+  const gw = runInstall(`export ONECLI_VERSION=${ONECLI_GATEWAY_VERSION} && curl -fsSL onecli.sh/install | sh`);
  stdout += gw.stdout;
  if (!gw.ok) {
    log.error('OneCLI gateway install failed', { stderr: gw.stderr });
@@ -21,6 +21,7 @@ import { formatResponse } from './format.js';
 import type { RequestFrame } from './frame.js';
 import { SocketTransport } from './socket-client.js';
 import type { Transport } from './transport.js';
+import { formatTransportError } from './transport-errors.js';

 async function main(): Promise<void> {
  const argv = process.argv.slice(2);
@@ -105,21 +106,6 @@ function printUsage(): void {
  );
 }

-function formatTransportError(e: unknown): string {
-  const msg = e instanceof Error ? e.message : String(e);
-  if (msg.includes('ENOENT') || msg.includes('ECONNREFUSED')) {
-    return [
-      `ncl: cannot reach NanoClaw host (${msg}).`,
-      `Is the host running? Start it with: pnpm run dev`,
-      `Or, if installed as a service:`,
-      `  macOS:  launchctl kickstart -k gui/$(id -u)/com.nanoclaw`,
-      `  Linux:  systemctl --user restart nanoclaw`,
-      ``,
-    ].join('\n');
-  }
-  return `ncl: transport error: ${msg}\n`;
-}
-
 main().catch((err) => {
  process.stderr.write(`ncl: unexpected error: ${err instanceof Error ? err.message : String(err)}\n`);
  process.exit(2);
@@ -52,6 +52,12 @@ export interface ResourceDef {
  description: string;
  /** Primary key column name. */
  idColumn: string;
+  /**
+   * Column that carries the agent group ID for group-scope enforcement.
+   * Required on every resource in the CLI whitelist (groups, sessions,
+   * destinations, members). When absent, post-handler filtering fails closed.
+   */
+  scopeField?: string;
  columns: ColumnDef[];
  /** Which standard CRUD operations are enabled. */
  operations: {
@@ -226,6 +232,7 @@ export function registerResource(def: ResourceDef): void {
      description: `List all ${def.plural}.`,
      access: def.operations.list,
      resource: def.plural,
+      generic: 'list',
      parseArgs: (raw) => normalizeArgs(raw),
      handler: genericList(def),
    });
@@ -237,6 +244,7 @@ export function registerResource(def: ResourceDef): void {
      description: `Get a ${def.name} by ID.`,
      access: def.operations.get,
      resource: def.plural,
+      generic: 'get',
      parseArgs: (raw) => normalizeArgs(raw),
      handler: genericGet(def),
    });
@@ -21,6 +21,13 @@ vi.mock('../db/sessions.js', () => ({
  getSession: (...args: unknown[]) => mockGetSession(...args),
 }));

+// dispatch's post-handler looks up the resource's `scopeField` via getResource.
+// The real resources aren't registered in this unit test, so mock it.
+const mockGetResource = vi.fn();
+vi.mock('./crud.js', () => ({
+  getResource: (...args: unknown[]) => mockGetResource(...args),
+}));
+
 vi.mock('../modules/approvals/index.js', () => ({
  registerApprovalHandler: vi.fn(),
  requestApproval: vi.fn(),
@@ -97,6 +104,7 @@ register({
  description: 'returns mock group rows',
  resource: 'groups',
  access: 'open',
+  generic: 'list',
  parseArgs: (raw) => raw,
  handler: async () => [
    { id: 'g1', name: 'my-group' },
@@ -109,6 +117,7 @@ register({
  description: 'returns a mock session row',
  resource: 'sessions',
  access: 'open',
+  generic: 'get',
  parseArgs: (raw) => raw,
  handler: async (args) => ({
    id: args.id,
@@ -116,11 +125,43 @@ register({
  }),
 });

+// A custom op under the `groups` resource that returns a config-shaped object
+// (no `id` key). The post-handler must not touch this — only `generic` handlers.
+register({
+  name: 'groups-config-get',
+  description: 'custom op returning a config object (no id)',
+  resource: 'groups',
+  access: 'open',
+  parseArgs: (raw) => raw,
+  handler: async () => ({ agent_group_id: 'g1', model: 'opus' }),
+});
+
+// The real `sessions-get` name — triggers the pre-handler ownership check.
+register({
+  name: 'sessions-get',
+  description: 'generic sessions get',
+  resource: 'sessions',
+  access: 'open',
+  generic: 'get',
+  parseArgs: (raw) => raw,
+  handler: async (args) => ({ id: (args as Record<string, unknown>).id, agent_group_id: 'g1' }),
+});
+
 import { dispatch } from './dispatch.js';
 import type { CallerContext } from './frame.js';

 beforeEach(() => {
  vi.clearAllMocks();
+  // Default: the four CLI-whitelisted resources with their real scopeFields.
+  const scopeFields: Record<string, string> = {
+    groups: 'id',
+    sessions: 'agent_group_id',
+    destinations: 'agent_group_id',
+    members: 'agent_group_id',
+  };
+  mockGetResource.mockImplementation((plural: string) =>
+    scopeFields[plural] ? { scopeField: scopeFields[plural] } : undefined,
+  );
 });

 // --- Helpers ---
@@ -402,4 +443,72 @@ describe('CLI scope enforcement', () => {
      expect(data).toHaveLength(2); // both groups returned
    }
  });
+
+  // --- Custom ops bypass post-handler row filtering (regression: #2392 review) ---
+
+  it('group: a custom op returning a non-row object is not falsely rejected', async () => {
+    mockGetContainerConfig.mockReturnValue({ cli_scope: 'group' });
+
+    // groups-config-get is access:open and reachable by a group-scoped agent;
+    // it returns { agent_group_id, model } with no `id` field. Before this fix
+    // the post-handler compared data['id'] (undefined) and returned forbidden.
+    const resp = await dispatch({ id: '1', command: 'groups-config-get', args: {} }, agentCtx());
+
+    expect(resp.ok).toBe(true);
+    if (resp.ok) {
+      expect((resp.data as { model: string }).model).toBe('opus');
+    }
+  });
+
+  // --- sessions-get pre-handler ownership check (no existence oracle) ---
+
+  it('group: sessions-get returns "session not found" for a foreign session UUID', async () => {
+    mockGetContainerConfig.mockReturnValue({ cli_scope: 'group' });
+    mockGetSession.mockReturnValue({ id: 's-x', agent_group_id: 'other-group' });
+
+    const resp = await dispatch({ id: '1', command: 'sessions-get', args: { id: 's-x' } }, agentCtx());
+
+    expect(resp.ok).toBe(false);
+    if (!resp.ok) {
+      expect(resp.error.code).toBe('handler-error');
+      expect(resp.error.message).toContain('session not found');
+    }
+  });
+
+  it('group: sessions-get returns "session not found" for a non-existent UUID', async () => {
+    mockGetContainerConfig.mockReturnValue({ cli_scope: 'group' });
+    mockGetSession.mockReturnValue(undefined);
+
+    const resp = await dispatch({ id: '1', command: 'sessions-get', args: { id: 's-nope' } }, agentCtx());
+
+    expect(resp.ok).toBe(false);
+    if (!resp.ok) {
+      expect(resp.error.code).toBe('handler-error');
+      expect(resp.error.message).toContain('session not found');
+    }
+  });
+
+  it('group: sessions-get allows the caller’s own session', async () => {
+    mockGetContainerConfig.mockReturnValue({ cli_scope: 'group' });
+    mockGetSession.mockReturnValue({ id: 's-mine', agent_group_id: 'g1' });
+
+    const resp = await dispatch({ id: '1', command: 'sessions-get', args: { id: 's-mine' } }, agentCtx());
+
+    expect(resp.ok).toBe(true);
+  });
+
+  // --- Fail-closed regression guard for a missing scopeField ---
+
+  it('group: generic list/get fails closed when the resource declares no scopeField', async () => {
+    mockGetContainerConfig.mockReturnValue({ cli_scope: 'group' });
+    mockGetResource.mockReturnValue(undefined); // a whitelisted resource that forgot scopeField
+
+    const resp = await dispatch({ id: '1', command: 'groups-list-data', args: {} }, agentCtx());
+
+    expect(resp.ok).toBe(false);
+    if (!resp.ok) {
+      expect(resp.error.code).toBe('forbidden');
+      expect(resp.error.message).toContain('not available in group scope');
+    }
+  });
 });
@@ -11,6 +11,7 @@ import { getAgentGroup } from '../db/agent-groups.js';
 import { getSession } from '../db/sessions.js';
 import { registerApprovalHandler, requestApproval } from '../modules/approvals/index.js';
 import type { CallerContext, ErrorCode, RequestFrame, ResponseFrame } from './frame.js';
+import { getResource } from './crud.js';
 import { lookup } from './registry.js';

 export async function dispatch(req: RequestFrame, ctx: CallerContext): Promise<ResponseFrame> {
@@ -87,6 +88,16 @@ export async function dispatch(req: RequestFrame, ctx: CallerContext): Promise<R
        fill.id = req.args.id ?? ctx.agentGroupId;
      }
      req = { ...req, args: { ...req.args, ...fill } };
+
+      // Fail-closed pre-handler check for sessions-get: returns "not found"
+      // regardless of whether the UUID exists in another group, preventing an
+      // existence oracle across group boundaries.
+      if (cmd.resource === 'sessions' && req.command === 'sessions-get' && req.args.id) {
+        const s = getSession(req.args.id as string);
+        if (!s || s.agent_group_id !== ctx.agentGroupId) {
+          return err(req.id, 'handler-error', `session not found: ${req.args.id}`);
+        }
+      }
    }
  }

@@ -124,14 +135,28 @@ export async function dispatch(req: RequestFrame, ctx: CallerContext): Promise<R
  try {
    let data = await cmd.handler(parsed, ctx);

-    // Post-handler group scope enforcement: filter/verify results belong
-    // to the caller's agent group. Catches leaks that pre-handler auto-fill
-    // can't prevent (e.g. `groups list` where the id arg is skipped by the
-    // generic list handler, or `sessions get` by UUID).
-    if (ctx.caller === 'agent' && cmd.resource) {
+    // Post-handler group-scope enforcement. Applies only to the auto-generated
+    // `list` / `get` handlers (`cmd.generic`), which return raw DB rows carrying
+    // the resource's `scopeField`:
+    //   - `list` → drop rows that don't belong to the caller's agent group
+    //              (covers `groups list`, where the generic list handler ignores
+    //              the auto-filled `--id`)
+    //   - `get`  → reject if the single row belongs to another group
+    // Custom operations return ad-hoc shapes (e.g. `groups config get` → a config
+    // object with no `id`) and are NOT checked here — they would be falsely
+    // rejected, and they're already pinned to the caller's group by the
+    // pre-handler `--id` auto-fill (groups/destinations) or gated behind approval,
+    // so they can't reach another group's data anyway.
+    if (ctx.caller === 'agent' && cmd.resource && cmd.generic) {
      const configRow = getContainerConfig(ctx.agentGroupId);
      if ((configRow?.cli_scope ?? 'group') === 'group') {
-        const groupField = cmd.resource === 'groups' ? 'id' : 'agent_group_id';
+        const def = getResource(cmd.resource);
+        const groupField = def?.scopeField;
+        if (!groupField) {
+          // Fail closed: a whitelisted resource exposing list/get must declare
+          // `scopeField` so its rows can be filtered.
+          return err(req.id, 'forbidden', `"${cmd.resource}" is not available in group scope.`);
+        }
        if (Array.isArray(data)) {
          data = data.filter(
            (row) =>
@@ -139,7 +164,7 @@ export async function dispatch(req: RequestFrame, ctx: CallerContext): Promise<R
              row !== null &&
              (row as Record<string, unknown>)[groupField] === ctx.agentGroupId,
          );
-        } else if (data && typeof data === 'object' && groupField in (data as Record<string, unknown>)) {
+        } else if (data && typeof data === 'object') {
          if ((data as Record<string, unknown>)[groupField] !== ctx.agentGroupId) {
            return err(req.id, 'forbidden', 'Resource belongs to a different agent group.');
          }
@@ -15,6 +15,13 @@ export type CommandDef<TArgs = unknown, TData = unknown> = {
  access: Access;
  /** Resource this command belongs to (for help grouping). */
  resource?: string;
+  /**
+   * Set on the auto-generated `list` / `get` handlers (see `registerResource`).
+   * These return raw DB rows that carry the resource's `scopeField`, so the
+   * dispatcher applies post-handler group-scope filtering to their output.
+   * Custom operations return ad-hoc shapes and leave this undefined.
+   */
+  generic?: 'list' | 'get';
  /** Validates `frame.args` and produces the typed handler input. Throws on invalid. */
  parseArgs: (raw: Record<string, unknown>) => TArgs;
  handler: (args: TArgs, ctx: CallerContext) => Promise<TData>;
@@ -8,6 +8,7 @@ registerResource({
  description:
    'Agent destination — per-agent routing entry and ACL. Each row authorizes an agent to send messages to a target (channel or another agent) and assigns a local name the agent uses to address it. Names are scoped to the source agent — two agents can have different local names for the same target. Created automatically when wiring channels or when agents create child agents.',
  idColumn: 'agent_group_id',
+  scopeField: 'agent_group_id',
  columns: [
    {
      name: 'agent_group_id',
@@ -38,6 +38,7 @@ registerResource({
  description:
    'Agent group — a logical agent identity. Each group has its own workspace folder (CLAUDE.md, skills, container config), conversation history, and container image. Multiple messaging groups can be wired to one agent group.',
  idColumn: 'id',
+  scopeField: 'id',
  columns: [
    { name: 'id', type: 'string', description: 'UUID.', generated: true },
    {
@@ -8,6 +8,7 @@ registerResource({
  description:
    'Agent group member — grants an unprivileged user permission to interact with an agent group. Users with admin or owner roles on the group are implicitly members and do not need a separate membership row. Membership is checked by the router when sender_scope is "known".',
  idColumn: 'user_id',
+  scopeField: 'agent_group_id',
  columns: [
    {
      name: 'user_id',
@@ -7,6 +7,7 @@ registerResource({
  description:
    'Session — the runtime unit. Maps one (agent_group, messaging_group, thread) combination to a container with its own inbound.db and outbound.db. Created automatically by the router when a message arrives.',
  idColumn: 'id',
+  scopeField: 'agent_group_id',
  columns: [
    { name: 'id', type: 'string', description: 'UUID.', generated: true },
    { name: 'agent_group_id', type: 'string', description: 'Agent group this session runs.' },
@@ -0,0 +1,31 @@
+import { describe, it, expect } from 'vitest';
+
+import { getLaunchdLabel, getSystemdUnit } from '../install-slug.js';
+import { formatTransportError } from './transport-errors.js';
+
+describe('formatTransportError', () => {
+  it('renders per-install service names on ENOENT, not the bare v1 names', () => {
+    const out = formatTransportError(new Error('connect ENOENT /tmp/nanoclaw.sock'));
+
+    // Regression for #2484: pre-fix, this string was a hardcoded
+    // `com.nanoclaw` / `nanoclaw`, which doesn't match the actual
+    // v2 per-install slug-suffixed unit and label.
+    expect(out).toContain(`gui/$(id -u)/${getLaunchdLabel()}`);
+    expect(out).toContain(`systemctl --user restart ${getSystemdUnit()}`);
+    expect(out).not.toMatch(/gui\/\$\(id -u\)\/com\.nanoclaw\b(?!-v2)/);
+    expect(out).not.toMatch(/systemctl --user restart nanoclaw\b(?!-v2)/);
+  });
+
+  it('renders the same on ECONNREFUSED', () => {
+    const out = formatTransportError(new Error('connect ECONNREFUSED'));
+    expect(out).toContain(getLaunchdLabel());
+    expect(out).toContain(getSystemdUnit());
+  });
+
+  it('falls back to a generic transport error for other failures', () => {
+    const out = formatTransportError(new Error('some unrelated failure'));
+    expect(out).toBe('ncl: transport error: some unrelated failure\n');
+    expect(out).not.toContain('launchctl');
+    expect(out).not.toContain('systemctl');
+  });
+});
@@ -0,0 +1,19 @@
+import { getLaunchdLabel, getSystemdUnit } from '../install-slug.js';
+
+export function formatTransportError(e: unknown): string {
+  const msg = e instanceof Error ? e.message : String(e);
+  if (msg.includes('ENOENT') || msg.includes('ECONNREFUSED')) {
+    // `bin/ncl` cd's to the project root before exec'ing client.ts, so
+    // process.cwd() is the install dir — install-slug helpers pick up
+    // the right per-checkout suffix.
+    return [
+      `ncl: cannot reach NanoClaw host (${msg}).`,
+      `Is the host running? Start it with: pnpm run dev`,
+      `Or, if installed as a service:`,
+      `  macOS:  launchctl kickstart -k gui/$(id -u)/${getLaunchdLabel()}`,
+      `  Linux:  systemctl --user restart ${getSystemdUnit()}`,
+      ``,
+    ].join('\n');
+  }
+  return `ncl: transport error: ${msg}\n`;
+}
@@ -227,11 +227,14 @@ async function handleSenderApprovalResponse(payload: ResponsePayload): Promise<b
  if (!row) return false;

  // payload.userId is the raw platform userId (e.g. "6037840640"); namespace it
-  // with the channel type so it matches users(id) format. Then verify the
-  // clicker is the designated approver OR has owner/admin privilege over this
-  // agent group — any other click is rejected so random users can't self-admit
-  // via stolen card forwarding.
-  const clickerId = payload.userId ? `${payload.channelType}:${payload.userId}` : null;
+  // with the channel type so it matches users(id) format. Some platforms
+  // (e.g. Teams "29:xxx") already include a colon — mirror resolveOrCreateUser
+  // logic and only prefix when the raw id has no colon.
+  const clickerId = payload.userId
+    ? payload.userId.includes(':')
+      ? payload.userId
+      : `${payload.channelType}:${payload.userId}`
+    : null;
  const isAuthorized =
    clickerId !== null && (clickerId === row.approver_user_id || hasAdminPrivilege(clickerId, row.agent_group_id));
  if (!isAuthorized) {
@@ -308,7 +311,11 @@ async function handleChannelApprovalResponse(payload: ResponsePayload): Promise<
  const row = getPendingChannelApproval(payload.questionId);
  if (!row) return false;

-  const clickerId = payload.userId ? `${payload.channelType}:${payload.userId}` : null;
+  const clickerId = payload.userId
+    ? payload.userId.includes(':')
+      ? payload.userId
+      : `${payload.channelType}:${payload.userId}`
+    : null;
  const isAuthorized =
    clickerId !== null && (clickerId === row.approver_user_id || hasAdminPrivilege(clickerId, row.agent_group_id));
  if (!isAuthorized) {