@intent-systems/nexus 2026.1.5-3

package/docs/nodes.md

@@ -0,0 +1,157 @@
+---
+summary: "Nodes: pairing, capabilities, permissions, and CLI helpers for canvas/camera/screen/system"
+read_when:
+  - Pairing iOS/Android nodes to a gateway
+  - Using node canvas/camera for agent context
+  - Adding new node commands or CLI helpers
+---
+
+# Nodes
+
+A **node** is a companion device (iOS/Android today) that connects to the Gateway over the **Bridge** and exposes a command surface (e.g. `canvas.*`, `camera.*`, `system.*`) via `node.invoke`.
+
+macOS can also run in **node mode**: the menubar app connects to the Gateway’s bridge and exposes its local canvas/camera commands as a node (so `nexus nodes …` works against this Mac).
+
+## Pairing + status
+
+Pairing is gateway-owned and approval-based. See [`docs/gateway/pairing.md`](https://docs.nexus.bot/gateway/pairing) for the full flow.
+
+Quick CLI:
+
+```bash
+nexus nodes pending
+nexus nodes approve <requestId>
+nexus nodes reject <requestId>
+nexus nodes status
+nexus nodes describe --node <idOrNameOrIp>
+nexus nodes rename --node <idOrNameOrIp> --name "Kitchen iPad"
+```
+
+Notes:
+- `nodes rename` stores a display name override in the gateway pairing store.
+
+## Invoking commands
+
+Low-level (raw RPC):
+
+```bash
+nexus nodes invoke --node <idOrNameOrIp> --command canvas.eval --params '{"javaScript":"location.href"}'
+```
+
+Higher-level helpers exist for the common “give the agent a MEDIA attachment” workflows.
+
+## Screenshots (canvas snapshots)
+
+If the node is showing the Canvas (WebView), `canvas.snapshot` returns `{ format, base64 }`.
+
+CLI helper (writes to a temp file and prints `MEDIA:<path>`):
+
+```bash
+nexus nodes canvas snapshot --node <idOrNameOrIp> --format png
+nexus nodes canvas snapshot --node <idOrNameOrIp> --format jpg --max-width 1200 --quality 0.9
+```
+
+Simple shortcut (auto-picks a single connected node if possible):
+
+```bash
+nexus canvas snapshot --format png
+nexus canvas snapshot --format jpg --max-width 1200 --quality 0.9
+```
+
+## Photos + videos (node camera)
+
+Photos (`jpg`):
+
+```bash
+nexus nodes camera snap --node <idOrNameOrIp>            # default: both facings (2 MEDIA lines)
+nexus nodes camera snap --node <idOrNameOrIp> --facing front
+```
+
+Video clips (`mp4`):
+
+```bash
+nexus nodes camera clip --node <idOrNameOrIp> --duration 10s
+nexus nodes camera clip --node <idOrNameOrIp> --duration 3000 --no-audio
+```
+
+Notes:
+- The node must be **foregrounded** for `canvas.*` and `camera.*` (background calls return `NODE_BACKGROUND_UNAVAILABLE`).
+- Clip duration is clamped (currently `<= 60s`) to avoid oversized base64 payloads.
+- Android will prompt for `CAMERA`/`RECORD_AUDIO` permissions when possible; denied permissions fail with `*_PERMISSION_REQUIRED`.
+
+## Screen recordings (nodes)
+
+Nodes expose `screen.record` (mp4). Example:
+
+```bash
+nexus nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10
+nexus nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10 --no-audio
+```
+
+Notes:
+- `screen.record` requires the node app to be foregrounded.
+- Android will show the system screen-capture prompt before recording.
+- Screen recordings are clamped to `<= 60s`.
+- `--no-audio` disables microphone capture (supported on iOS/Android; macOS uses system capture audio).
+
+## Location (nodes)
+
+Nodes expose `location.get` when Location is enabled in settings.
+
+CLI helper:
+
+```bash
+nexus nodes location get --node <idOrNameOrIp>
+nexus nodes location get --node <idOrNameOrIp> --accuracy precise --max-age 15000 --location-timeout 10000
+```
+
+Notes:
+- Location is **off by default**.
+- “Always” requires system permission; background fetch is best-effort.
+- The response includes lat/lon, accuracy (meters), and timestamp.
+
+## SMS (Android nodes)
+
+Android nodes can expose `sms.send` when the user grants **SMS** permission and the device supports telephony.
+
+Low-level invoke:
+
+```bash
+nexus nodes invoke --node <idOrNameOrIp> --command sms.send --params '{"to":"+15555550123","message":"Hello from Nexus"}'
+```
+
+Notes:
+- The permission prompt must be accepted on the Android device before the capability is advertised.
+- Wi-Fi-only devices without telephony will not advertise `sms.send`.
+
+## System commands (mac node)
+
+The macOS node exposes `system.run` and `system.notify`.
+
+Examples:
+
+```bash
+nexus nodes run --node <idOrNameOrIp> -- echo "Hello from mac node"
+nexus nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"
+```
+
+Notes:
+- `system.run` returns stdout/stderr/exit code in the payload.
+- `system.notify` respects notification permission state on the macOS app.
+
+## Permissions map
+
+Nodes may include a `permissions` map in `node.list` / `node.describe`, keyed by permission name (e.g. `screenRecording`, `accessibility`) with boolean values (`true` = granted).
+
+## Mac node mode
+
+- The macOS menubar app connects to the Gateway bridge as a node (so `nexus nodes …` works against this Mac).
+- In remote mode, the app opens an SSH tunnel for the bridge port and connects to `localhost`.
+
+## Where to look in code
+
+- CLI wiring: `src/cli/nodes-cli.ts`
+- Canvas snapshot decoding/temp paths: `src/cli/nodes-canvas.ts`
+- Duration parsing for CLI: `src/cli/parse-duration.ts`
+- iOS node commands: `apps/ios/Sources/Model/NodeAppModel.swift`
+- Android node commands: `apps/android/app/src/main/java/com/nexus/android/node/*`

package/docs/onboarding-config-protocol.md

@@ -0,0 +1,34 @@
+---
+summary: "RPC protocol notes for onboarding wizard and config schema"
+read_when: "Changing onboarding wizard steps or config schema endpoints"
+---
+
+# Onboarding + Config Protocol
+
+Purpose: shared onboarding + config surfaces across CLI, macOS app, and Web UI.
+
+## Components
+- Wizard engine: `src/wizard` (session + prompts + onboarding state).
+- CLI: `src/commands/onboard-*.ts` uses the wizard with the CLI prompter.
+- Gateway RPC: wizard + config schema endpoints serve UI clients.
+- macOS: SwiftUI onboarding uses the wizard step model.
+- Web UI: config form renders from JSON Schema + hints.
+
+## Gateway RPC
+- `wizard.start` params: `{ mode?: "local"|"remote", workspace?: string }`
+- `wizard.next` params: `{ sessionId, answer?: { stepId, value? } }`
+- `wizard.cancel` params: `{ sessionId }`
+- `wizard.status` params: `{ sessionId }`
+- `config.schema` params: `{}`
+
+Responses (shape)
+- Wizard: `{ sessionId, done, step?, status?, error? }`
+- Config schema: `{ schema, uiHints, version, generatedAt }`
+
+## UI Hints
+- `uiHints` keyed by path; optional metadata (label/help/group/order/advanced/sensitive/placeholder).
+- Sensitive fields render as password inputs; no redaction layer.
+- Unsupported schema nodes fall back to the raw JSON editor.
+
+## Notes
+- This doc is the single place to track protocol refactors for onboarding/config.

package/docs/onboarding.md

@@ -0,0 +1,189 @@
+---
+summary: "Planned first-run onboarding flow for Nexus (local vs remote, OAuth auth, workspace bootstrap ritual)"
+read_when:
+  - Designing the macOS onboarding assistant
+  - Implementing Anthropic/OpenAI auth or identity setup
+---
+# Onboarding (macOS app)
+
+This doc describes the intended **first-run onboarding** for Nexus. The goal is a good “day 0” experience: pick where the Gateway runs, bind subscription auth (Anthropic or OpenAI) for the embedded agent runtime, and then let the **agent bootstrap itself** via a first-run ritual in the workspace.
+
+## Page order (high level)
+
+1) **Local vs Remote**
+2) **(Local only)** Connect subscription auth (Anthropic / OpenAI OAuth) — optional, but recommended
+3) **Connect Gmail (optional)** — run `nexus hooks gmail setup` to configure Pub/Sub hooks
+4) **Onboarding chat** — dedicated session where the agent introduces itself and guides setup
+
+## 1) Local vs Remote
+
+First question: where does the **Gateway** run?
+
+- **Local (this Mac):** onboarding can run OAuth flows and write OAuth credentials locally.
+- **Remote (over SSH/tailnet):** onboarding must not run OAuth locally, because credentials must exist on the **gateway host**.
+
+Gateway auth tip:
+- If you only use Nexus on this Mac (loopback gateway), keep auth **Off**.
+- Use **Token** for multi-machine access or non-loopback binds.
+
+Implementation note (2025-12-19): in local mode, the macOS app bundles the Gateway and enables it via a per-user launchd LaunchAgent (no global npm install/Node requirement for the user).
+
+## 2) Local-only: Connect subscription auth (Anthropic / OpenAI OAuth)
+
+This is the “bind Nexus to subscription auth” step. It is explicitly the **Anthropic (Claude Pro/Max)** or **OpenAI (ChatGPT/Codex)** OAuth flow, not a generic “login”.
+
+### Recommended: OAuth (Anthropic)
+
+The macOS app should:
+- Start the Anthropic OAuth (PKCE) flow in the user’s browser.
+- Ask the user to paste the `code#state` value.
+- Exchange it for tokens and write credentials to:
+  - `~/nexus/state/credentials/oauth.json` (file mode `0600`, directory mode `0700`)
+
+Why this location matters: it’s the Nexus-owned OAuth store.
+Nexus also imports `oauth.json` into the agent auth profile store (`~/nexus/state/agent/auth-profiles.json`) on first use.
+
+### Recommended: OAuth (OpenAI Codex)
+
+The macOS app should:
+- Start the OpenAI Codex OAuth (PKCE) flow in the user’s browser.
+- Auto-capture the callback on `http://127.0.0.1:1455/auth/callback` when possible.
+- If the callback fails, prompt the user to paste the redirect URL or code.
+- Store credentials in `~/nexus/state/credentials/oauth.json` (same OAuth store as Anthropic).
+- Set `agent.model` to `openai-codex/gpt-5.2` when the model is unset or `openai/*`.
+
+### Alternative: API key (instructions only)
+
+Offer an “API key” option, but for now it is **instructions only**:
+- Get an Anthropic API key.
+- Provide it to Nexus via your preferred mechanism (env/config).
+
+Note: environment variables are often confusing when the Gateway is launched by a GUI app (launchd environment != your shell).
+
+### Model safety rule
+
+Nexus should **always pass** `--model` when invoking the embedded agent (don’t rely on defaults).
+
+Example (CLI):
+
+```bash
+nexus agent --mode rpc --model anthropic/claude-opus-4-5 "<message>"
+```
+
+If the user skips auth, onboarding should be clear: the agent likely won’t respond until auth is configured.
+
+## 4) Onboarding chat (dedicated session)
+
+The onboarding flow now embeds the SwiftUI chat view directly. It uses a **special session key**
+(`onboarding`) so the “newborn agent” ritual stays separate from the main chat.
+
+This onboarding chat is where the agent:
+- follows the BOOTSTRAP prompt when identity is missing (one question at a time)
+- visits **soul.md** with the user and writes `SOUL.md` (values, tone, boundaries)
+- asks how the user wants to talk (web-only / WhatsApp / Telegram)
+- guides linking steps (including showing a QR inline for WhatsApp via the `whatsapp_login` tool)
+
+If identity already exists, the onboarding chat step is skipped.
+
+## 2.5) Optional: Connect Gmail
+
+The macOS onboarding includes an optional Gmail step. It runs:
+
+```bash
+nexus hooks gmail setup --account you@gmail.com
+```
+
+This writes the full `hooks.gmail` config, installs `gcloud` / `gog` / `tailscale`
+via Homebrew if needed, and configures the Pub/Sub push endpoint. After setup,
+restart the gateway so the internal Gmail watcher starts.
+
+Once setup is complete, the user can switch to the normal chat (`main`) via the menu bar panel.
+
+## 5) Agent bootstrap ritual (outside onboarding)
+
+We no longer collect identity in the onboarding wizard. Instead, the **first agent run** performs a playful bootstrap ritual using files in state:
+
+- Workspace is created implicitly (default `~/nexus/home`, configurable via `agent.workspace`) when local is selected,
+  but only if the folder is empty or already contains `AGENTS.md`.
+- Files are seeded: `~/nexus/AGENTS.md`, `state/nexus/onboarding/BOOTSTRAP.md`, and identity files in `state/`.
+- `BOOTSTRAP.md` tells the agent to keep it conversational:
+  - open with a cute hello
+  - ask **one question at a time** (no multi-question bombardment)
+  - offer a small set of suggestions where helpful (name, creature, emoji)
+  - wait for the user’s reply before asking the next question
+- The agent writes results to:
+  - `state/agents/{agent}/identity/IDENTITY.md` (agent name, vibe/creature, emoji)
+  - `state/user/identity/PROFILE.md` (who the user is + how they want to be addressed)
+  - `state/agents/{agent}/identity/SOUL.md` (identity, tone, boundaries — crafted from the soul.md prompt)
+  - `state/nexus/config.json` (structured identity defaults)
+- The bootstrap prompt remains, but `nexus status` stops showing it once identity exists.
+
+Identity data still feeds the same defaults as before:
+
+- outbound prefix emoji (`messages.responsePrefix`)
+- group mention patterns / wake words
+- default session intro (“You are Samantha…”)
+- macOS UI labels
+
+## 6) Workspace notes (no explicit onboarding step)
+
+The workspace is created automatically as part of agent bootstrap (no dedicated onboarding screen).
+
+Recommendation: treat the workspace as the agent’s “memory” and make it a git repo (ideally private) so identity + memories are backed up:
+
+```bash
+cd ~/nexus/home
+git init
+git add AGENTS.md
+git commit -m "Add agent workspace"
+```
+
+Daily memory lives under `memory/` in the workspace:
+- one file per day: `memory/YYYY-MM-DD.md`
+- read today + yesterday on session start
+- keep it short (durable facts, preferences, decisions; avoid secrets)
+
+## Remote mode note (why OAuth is hidden)
+
+If the Gateway runs on another machine, OAuth credentials must be created/stored on that host (where the agent runtime runs).
+
+For now, remote onboarding should:
+- explain why OAuth isn't shown
+- point the user at the credential location (`~/nexus/state/credentials/oauth.json`) and the auth profile store (`~/nexus/state/agent/auth-profiles.json`) on the gateway host
+- mention that the **bootstrap ritual happens on the gateway host** (same BOOTSTRAP/IDENTITY/USER files)
+
+### Manual credential setup
+
+On the gateway host, create `~/nexus/state/credentials/oauth.json` with this exact format:
+
+```json
+{
+  "anthropic": { "type": "oauth", "access": "sk-ant-oat01-...", "refresh": "sk-ant-ort01-...", "expires": 1767304352803 },
+  "openai-codex": { "type": "oauth", "access": "eyJhbGciOi...", "refresh": "oai-refresh-...", "expires": 1767304352803, "accountId": "acct_..." }
+}
+```
+
+Set permissions: `chmod 600 ~/nexus/state/credentials/oauth.json`
+
+**Note:** Nexus auto-imports from legacy pi-coding-agent paths (`~/.pi/agent/oauth.json`, etc.) but this does NOT work with Claude Code credentials — different file and format.
+
+### Using Claude Code credentials
+
+If Claude Code is installed on the gateway host, convert its credentials:
+
+```bash
+cat ~/.claude/.credentials.json | jq '{
+  anthropic: {
+    access: .claudeAiOauth.accessToken,
+    refresh: .claudeAiOauth.refreshToken,
+    expires: .claudeAiOauth.expiresAt
+  }
+}' > ~/nexus/state/credentials/oauth.json
+chmod 600 ~/nexus/state/credentials/oauth.json
+```
+
+| Claude Code field | Nexus field |
+|-------------------|---------------|
+| `accessToken` | `access` |
+| `refreshToken` | `refresh` |
+| `expiresAt` | `expires` |

package/docs/pairing.md

@@ -0,0 +1,85 @@
+---
+summary: "Pairing overview: approve who can DM you + which nodes can join"
+read_when:
+  - Setting up DM access control
+  - Pairing a new iOS/Android node
+  - Reviewing Nexus security posture
+---
+
+# Pairing
+
+“Pairing” is Nexus’s explicit **owner approval** step.
+It is used in two places:
+
+1) **DM pairing** (who is allowed to talk to the bot)
+2) **Node pairing** (which devices/nodes are allowed to join the gateway network)
+
+Security context: https://docs.nexus.bot/security
+
+## 1) DM pairing (inbound chat access)
+
+When a provider is configured with DM policy `pairing`, unknown senders get a short code and their message is **not processed** until you approve.
+
+Default DM policies are documented in: https://docs.nexus.bot/security
+
+### Approve a sender
+
+```bash
+nexus pairing list --provider telegram
+nexus pairing approve --provider telegram <CODE>
+```
+
+Supported providers: `telegram`, `whatsapp`, `signal`, `imessage`, `discord`, `slack`.
+
+### Where the state lives
+
+Stored under `~/nexus/state/credentials/`:
+- Pending requests: `<provider>-pairing.json`
+- Approved allowlist store: `<provider>-allowFrom.json`
+
+Treat these as sensitive (they gate access to your assistant).
+
+### Source of truth (code)
+
+- DM pairing storage + code generation: [`src/pairing/pairing-store.ts`](https://github.com/nexus/nexus/blob/main/src/pairing/pairing-store.ts)
+- CLI commands: [`src/cli/pairing-cli.ts`](https://github.com/nexus/nexus/blob/main/src/cli/pairing-cli.ts)
+
+## 2) Node pairing (iOS/Android nodes joining the gateway)
+
+Nodes (iOS/Android, future hardware, etc.) connect to the Gateway and request to join.
+The Gateway keeps an authoritative allowlist; new nodes require explicit approve/reject.
+
+### Approve a node
+
+```bash
+nexus nodes pending
+nexus nodes approve <requestId>
+```
+
+### Where the state lives
+
+Stored under `~/nexus/state/nodes/`:
+- `pending.json` (short-lived; pending requests expire)
+- `paired.json` (paired nodes + tokens)
+
+### Details
+
+Full protocol + design notes: https://docs.nexus.bot/gateway/pairing
+
+### Source of truth (code)
+
+- Node pairing store (pending/paired + token issuance): [`src/infra/node-pairing.ts`](https://github.com/nexus/nexus/blob/main/src/infra/node-pairing.ts)
+- Gateway methods/events (`node.pair.*`): [`src/gateway/server-methods/nodes.ts`](https://github.com/nexus/nexus/blob/main/src/gateway/server-methods/nodes.ts)
+- CLI: [`src/cli/nodes-cli.ts`](https://github.com/nexus/nexus/blob/main/src/cli/nodes-cli.ts)
+
+## Related docs
+
+- Security model + prompt injection: https://docs.nexus.bot/security
+- Updating safely (run doctor): https://docs.nexus.bot/updating
+- Provider configs:
+  - Telegram: https://docs.nexus.bot/telegram
+  - WhatsApp: https://docs.nexus.bot/whatsapp
+  - Signal: https://docs.nexus.bot/signal
+  - iMessage: https://docs.nexus.bot/imessage
+  - Discord: https://docs.nexus.bot/discord
+  - Slack: https://docs.nexus.bot/slack

package/docs/plans/cron-add-hardening.md

@@ -0,0 +1,72 @@
+---
+summary: "Harden cron.add input handling, align schemas, and improve cron UI/agent tooling"
+owner: "nexus"
+status: "complete"
+last_updated: "2026-01-05"
+---
+
+# Cron Add Hardening & Schema Alignment
+
+## Context
+Recent gateway logs show repeated `cron.add` failures with invalid parameters (missing `sessionTarget`, `wakeMode`, `payload`, and malformed `schedule`). This indicates that at least one client (likely the agent tool call path) is sending wrapped or partially specified job payloads. Separately, there is drift between cron provider enums in TypeScript, gateway schema, CLI flags, and UI form types, plus a UI mismatch for `cron.status` (expects `jobCount` while gateway returns `jobs`).
+
+## Goals
+- Stop `cron.add` INVALID_REQUEST spam by normalizing common wrapper payloads and inferring missing `kind` fields.
+- Align cron provider lists across gateway schema, cron types, CLI docs, and UI forms.
+- Make agent cron tool schema explicit so the LLM produces correct job payloads.
+- Fix the Control UI cron status job count display.
+- Add tests to cover normalization and tool behavior.
+
+## Non-goals
+- Change cron scheduling semantics or job execution behavior.
+- Add new schedule kinds or cron expression parsing.
+- Overhaul the UI/UX for cron beyond the necessary field fixes.
+
+## Findings (current gaps)
+- `CronPayloadSchema` in gateway excludes `signal` + `imessage`, while TS types include them.
+- Control UI CronStatus expects `jobCount`, but gateway returns `jobs`.
+- Agent cron tool schema allows arbitrary `job` objects, enabling malformed inputs.
+- Gateway strictly validates `cron.add` with no normalization, so wrapped payloads fail.
+
+## Proposed Approach
+1. **Normalize** incoming `cron.add` payloads (unwrap `data`/`job`, infer `schedule.kind` and `payload.kind`, default `wakeMode` + `sessionTarget` when safe).
+2. **Harden** the agent cron tool schema using the canonical gateway `CronAddParamsSchema` and normalize before sending to the gateway.
+3. **Align** provider enums and cron status fields across gateway schema, TS types, CLI descriptions, and UI form controls.
+4. **Test** normalization in gateway tests and tool behavior in agent tests.
+
+## Multi-phase Execution Plan
+
+### Phase 1 — Schema + type alignment
+- [x] Expand gateway `CronPayloadSchema` provider enum to include `signal` and `imessage`.
+- [x] Update CLI `--provider` descriptions to include `slack` (already supported by gateway).
+- [x] Update UI Cron payload/provider union types to include all supported providers.
+- [x] Fix UI CronStatus type to match gateway (`jobs` instead of `jobCount`).
+- [x] Update cron UI channel select to include Discord/Slack/Signal/iMessage.
+- [x] Update macOS CronJobEditor channel picker + enum to include Slack/Signal/iMessage.
+- [x] Document cron compatibility normalization policy in [`docs/cron.md`](https://docs.nexus.bot/cron).
+
+### Phase 2 — Input normalization + tooling hardening
+- [x] Add shared cron input normalization helpers (`normalizeCronJobCreate`/`normalizeCronJobPatch`).
+- [x] Apply normalization in gateway `cron.add` (and patch normalization in `cron.update`).
+- [x] Tighten agent cron tool schema to `CronAddParamsSchema` and normalize job/patch before sending.
+
+### Phase 3 — Tests
+- [x] Add gateway test covering wrapped `cron.add` payload normalization.
+- [x] Add cron tool test to assert normalization and defaulting for `cron.add`.
+- [x] Add gateway test covering `cron.update` normalization.
+- [x] Add UI + Swift conformance test for cron channels + status fields.
+
+### Phase 4 — Verification
+- [x] Run tests (full suite executed via `pnpm test -- cron-tool`).
+
+## Rollout/Monitoring
+- Watch gateway logs for reduced `cron.add` INVALID_REQUEST errors.
+- Confirm Control UI cron status shows job count after refresh.
+- If errors persist, extend normalization for additional common shapes (e.g., `schedule.at`, `payload.message` without `kind`).
+
+## Optional Follow-ups
+- Manual Control UI smoke: add cron job per provider + verify status job count.
+
+## Open Questions
+- Should `cron.add` accept explicit `state` from clients (currently disallowed by schema)?
+- Should we allow `webchat` as an explicit delivery provider (currently filtered in delivery resolution)?

package/docs/plans/group-policy-hardening.md

@@ -0,0 +1,121 @@
+# Engineering Execution Spec: groupPolicy Hardening (Telegram Allowlist Parity)
+
+**Date**: 2026-01-05  
+**Status**: Complete  
+**PR**: #216 (feat/whatsapp-group-policy)
+
+---
+
+## Executive Summary
+
+Follow-up hardening work ensures Telegram allowlists behave consistently across inbound group/DM filtering and outbound send normalization. The focus is on prefix parity (`telegram:` / `tg:`), case-insensitive matching for prefixes, and resilience to accidental whitespace in config entries. Documentation and tests were updated to reflect and lock in this behavior.
+
+---
+
+## Findings Analysis
+
+### [MED] F1: Telegram Allowlist Prefix Handling Is Case-Sensitive and Excludes `tg:`
+
+**Location**: `src/telegram/bot.ts`
+
+**Problem**: Inbound allowlist normalization only stripped a lowercase `telegram:` prefix. This rejected `TG:123` / `Telegram:123` and did not accept the `tg:` shorthand even though outbound send normalization already accepts `tg:` and case-insensitive prefixes.
+
+**Impact**:
+- DMs and group allowlists fail when users copy/paste prefixed IDs from logs or existing send format.
+- Behavior is inconsistent between inbound filtering and outbound send normalization.
+
+**Fix**: Normalize allowlist entries by trimming whitespace and stripping `telegram:` / `tg:` prefixes case-insensitively at pre-compute time.
+
+---
+
+### [LOW] F2: Allowlist Entries Are Not Trimmed
+
+**Location**: `src/telegram/bot.ts`
+
+**Problem**: Allowlist entries are not trimmed; accidental whitespace causes mismatches.
+
+**Fix**: Trim and drop empty entries while normalizing allowlist inputs.
+
+---
+
+## Implementation Phases
+
+### Phase 1: Normalize Telegram Allowlist Inputs
+
+**File**: `src/telegram/bot.ts`
+
+**Changes**:
+1. Trim allowlist entries and drop empty values.
+2. Strip `telegram:` / `tg:` prefixes case-insensitively.
+3. Simplify DM allowlist check to rely on normalized values.
+
+---
+
+### Phase 2: Add Coverage for Prefix + Whitespace
+
+**File**: `src/telegram/bot.test.ts`
+
+**Add Tests**:
+- DM allowlist accepts `TG:` prefix with surrounding whitespace.
+- Group allowlist accepts `TG:` prefix case-insensitively.
+
+---
+
+### Phase 3: Documentation Updates
+
+**Files**:
+- [`docs/groups.md`](https://docs.nexus.bot/groups)
+- [`docs/telegram.md`](https://docs.nexus.bot/telegram)
+
+**Changes**:
+- Document `tg:` alias and case-insensitive prefixes for Telegram allowlists.
+
+---
+
+### Phase 4: Verification
+
+1. Run targeted Telegram tests (`pnpm test -- src/telegram/bot.test.ts`).
+2. If time allows, run full suite (`pnpm test`).
+
+---
+
+## Files Modified
+
+| File | Change Type | Description |
+|------|-------------|-------------|
+| `src/telegram/bot.ts` | Fix | Trim allowlist values; strip `telegram:` / `tg:` prefixes case-insensitively |
+| `src/telegram/bot.test.ts` | Test | Add DM + group allowlist coverage for `TG:` prefix + whitespace |
+| [`docs/groups.md`](https://docs.nexus.bot/groups) | Docs | Mention `tg:` alias + case-insensitive prefixes |
+| [`docs/telegram.md`](https://docs.nexus.bot/telegram) | Docs | Mention `tg:` alias + case-insensitive prefixes |
+
+---
+
+## Success Criteria
+
+- [x] Telegram allowlist accepts `telegram:` / `tg:` prefixes case-insensitively.
+- [x] Telegram allowlist tolerates whitespace in config entries.
+- [x] DM and group allowlist tests cover prefixed cases.
+- [x] Docs updated to reflect allowlist formats.
+- [x] Targeted tests pass.
+- [x] Full test suite passes.
+
+---
+
+## Risk Assessment
+
+| Risk | Severity | Mitigation |
+|------|----------|------------|
+| Behavior change for malformed entries | Low | Normalization is additive and trims only whitespace |
+| Test fragility | Low | Isolated unit tests; no external dependencies |
+| Doc drift | Low | Updated docs alongside code |
+
+---
+
+## Estimated Complexity
+
+- **Phase 1**: Low (normalization helpers)
+- **Phase 2**: Low (2 new tests)
+- **Phase 3**: Low (doc edits)
+- **Phase 4**: Low (verification)
+
+**Total**: ~20 minutes