nodmix 2026.5.25

package/docs/refactor/canvas.md

@@ -0,0 +1,131 @@
+---
+summary: "Plan and audit checklist for moving Canvas out of core and into a bundled experimental plugin."
+read_when:
+  - Moving Canvas host, tools, commands, docs, or protocol ownership
+  - Auditing whether Canvas is still core-owned
+  - Preparing or reviewing the experimental Canvas plugin PR
+title: "Canvas plugin refactor"
+---
+
+# Canvas plugin refactor
+
+Canvas is low-use and experimental. Treat it as a bundled plugin, not a core feature. Core may keep generic gateway, node, HTTP, auth, config, and native-client plumbing, but Canvas-specific behavior should live under `extensions/canvas`.
+
+## Goal
+
+Move Canvas ownership to `extensions/canvas` while preserving the current paired-node behavior:
+
+- the agent-facing `canvas` tool is registered by the Canvas plugin
+- Canvas node commands are allowed only when the Canvas plugin registers them
+- A2UI host/source files live under the Canvas plugin
+- Canvas document materialization lives under the Canvas plugin
+- CLI command implementation lives under the Canvas plugin, or delegates through a plugin-owned runtime barrel
+- docs and plugin inventory describe Canvas as experimental and plugin-backed
+
+## Non-goals
+
+- Do not redesign the native app Canvas UI in this refactor.
+- Do not remove Canvas protocol/client support from iOS, Android, or macOS unless a separate product decision says Canvas should be deleted.
+- Do not build a broad plugin service framework only for Canvas unless at least one other bundled plugin needs the same seam.
+
+## Current branch state
+
+Done:
+
+- Added bundled plugin package in `extensions/canvas`.
+- Added `extensions/canvas/nodmix.plugin.json`.
+- Moved the agent `canvas` tool from `src/agents/tools/canvas-tool.ts` to `extensions/canvas/src/tool.ts`.
+- Removed core registration of `createCanvasTool` from `src/agents/nodmix-tools.ts`.
+- Moved Canvas host implementation from `src/canvas-host` to `extensions/canvas/src/host`.
+- Kept `extensions/canvas/runtime-api.ts` as the plugin-owned compatibility barrel for tests, packaging, and external public Canvas helpers.
+- Moved Canvas document materialization from `src/gateway/canvas-documents.ts` to `extensions/canvas/src/documents.ts`.
+- Moved Canvas CLI implementation and A2UI JSONL helpers into `extensions/canvas/src/cli.ts`.
+- Moved Canvas host URL and scoped capability helpers into `extensions/canvas/src`.
+- Moved Canvas node command defaults out of hardcoded core lists and into plugin `nodeInvokePolicies`.
+- Added plugin-owned Canvas host config at `plugins.entries.canvas.config.host`.
+- Moved Canvas and A2UI HTTP serving behind Canvas plugin HTTP route registration.
+- Added generic plugin WebSocket upgrade dispatch for plugin-owned HTTP routes.
+- Replaced Canvas-specific gateway host URL and node capability auth with generic hosted plugin surface and node capability helpers.
+- Added plugin-owned hosted media resolvers so Canvas document URLs resolve through the Canvas plugin instead of core importing Canvas document internals.
+- Added `api.registerNodeCliFeature(...)` so Canvas can declare `nodmix nodes canvas` as a plugin-owned node feature without manually spelling the parent command path.
+- Removed production `src/**` imports of `extensions/canvas/runtime-api.js`.
+- Moved the A2UI bundle source from `apps/shared/NodmixKit/Tools/CanvasA2UI` to `extensions/canvas/src/host/a2ui-app`.
+- Moved A2UI build/copy implementation under `extensions/canvas/scripts` and replaced root build wiring with generic bundled-plugin asset hooks.
+- Removed the runtime legacy top-level `canvasHost` config alias.
+- Kept the Canvas doctor migration so `nodmix doctor --fix` rewrites old `canvasHost` configs into `plugins.entries.canvas.config.host`.
+- Removed old-agent Canvas protocol compatibility behind gateway protocol v4. Native clients and gateways now use only `pluginSurfaceUrls.canvas` plus `node.pluginSurface.refresh`; the deprecated `canvasHostUrl`, `canvasCapability`, and `node.canvas.capability.refresh` path is intentionally unsupported in this experimental refactor.
+- Updated generated plugin inventory to include Canvas.
+- Added plugin reference docs at `docs/plugins/reference/canvas.md`.
+
+Known remaining core-owned Canvas surfaces:
+
+- Native app Canvas handlers under `apps/` still intentionally consume the Canvas plugin surface
+- native app Canvas protocol/client handlers under `apps/`
+- published artifact output still uses `dist/canvas-host/a2ui` for backwards-compatible runtime lookup, but the copy step is now plugin-owned
+
+## Target shape
+
+`extensions/canvas` should own:
+
+- plugin manifest and package metadata
+- agent tool registration
+- node invoke command policy
+- Canvas host and A2UI runtime
+- Canvas A2UI bundle source and asset build/copy scripts
+- Canvas document creation and asset resolution
+- Canvas CLI implementation
+- Canvas docs page and plugin inventory entry
+
+Core should own only generic seams:
+
+- plugin discovery and registration
+- generic agent tool registry
+- generic node invoke policy registry
+- generic gateway HTTP/auth and WebSocket upgrade dispatch
+- generic hosted plugin surface URL resolution
+- generic hosted media resolver registration
+- generic node capability transport
+- generic config plumbing
+- generic bundled-plugin asset hook discovery
+
+Native apps may keep Canvas command handlers as clients of the protocol. They are not the plugin runtime owner.
+
+## Migration steps
+
+1. Treat `plugins.entries.canvas.config.host` as the plugin-owned config surface.
+2. Update docs so Canvas is described as an experimental bundled plugin.
+3. Run focused Canvas tests, plugin inventory checks, plugin SDK API checks, and build/type gates affected by runtime boundaries.
+
+## Audit checklist
+
+Before calling the refactor complete:
+
+- `rg "src/canvas-host|../canvas-host"` returns no live source imports.
+- `rg "canvas-tool|createCanvasTool" src` finds no core-owned Canvas tool implementation.
+- `rg "canvas.present|canvas.snapshot|canvas.a2ui" src/gateway` finds no hardcoded allowlist defaults outside generic plugin policy tests.
+- `rg "extensions/canvas/runtime-api" src --glob '!**/*.test.ts'` is empty.
+- `rg "canvas-documents" src` is empty.
+- `rg "registerNodesCanvasCommands|nodes-canvas" src` is empty; the Canvas plugin registers `nodmix nodes canvas` through nested plugin CLI metadata.
+- `rg "createCanvasHostHandler|handleA2uiHttpRequest" src/gateway` returns no gateway runtime ownership.
+- `rg "apps/shared/NodmixKit/Tools/CanvasA2UI|canvas-a2ui-copy|extensions/canvas/src/host/a2ui" scripts .github package.json` finds only compatibility wrappers or plugin-owned paths.
+- `pnpm plugins:inventory:check` passes.
+- `pnpm plugin-sdk:api:check` passes, or generated API baselines are intentionally updated and reviewed.
+- Targeted Canvas tests pass.
+- Changed-lanes tests pass for Canvas host/A2UI paths.
+- PR body explicitly says Canvas is experimental and plugin-backed.
+
+## Verification commands
+
+Use targeted local checks while iterating:
+
+```sh
+pnpm test extensions/canvas/src/host/server.test.ts extensions/canvas/src/host/server.state-dir.test.ts extensions/canvas/src/host/file-resolver.test.ts
+pnpm test src/gateway/server.plugin-node-capability-auth.test.ts src/gateway/server-import-boundary.test.ts
+pnpm test extensions/canvas/src/config-migration.test.ts src/commands/doctor-legacy-config.migrations.test.ts
+pnpm test test/scripts/changed-lanes.test.ts test/scripts/build-all.test.ts extensions/canvas/scripts/bundle-a2ui.test.ts test/scripts/bundled-plugin-assets.test.ts extensions/canvas/scripts/copy-a2ui.test.ts src/infra/run-node.test.ts
+pnpm tsgo:extensions
+pnpm plugins:inventory:check
+pnpm plugin-sdk:api:check
+```
+
+Run `pnpm build` before push if runtime barrel, lazy import, packaging, or published plugin surfaces change.

package/docs/refactor/ingress-core.md

@@ -0,0 +1,341 @@
+---
+summary: "Deletion-first plan for moving repeated channel ingress glue into core."
+read_when:
+  - Auditing why the channel ingress refactor added too much code
+  - Moving route, command, event, activation, or access-group policy from bundled plugins into core
+  - Reviewing whether a channel ingress helper actually deletes bundled plugin code
+title: "Ingress core deletion plan"
+sidebarTitle: "Ingress core deletion"
+---
+
+# Ingress core deletion plan
+
+The ingress refactor is not healthy while it adds thousands of net lines. Core
+centralization only counts when bundled plugin production code gets smaller and
+old third-party SDK compatibility is quarantined to SDK/core shims.
+
+Desired runtime shape:
+
+```text
+bundled plugin event
+  -> extract platform facts locally
+  -> resolve shared ingress once when facts are available
+  -> branch on generic ingress projections/outcomes
+  -> perform platform side effects locally
+
+old third-party helper
+  -> SDK compatibility shim
+  -> shared ingress-compatible projection where possible
+  -> old return shape preserved
+```
+
+Bundled plugins should not translate ingress back into local `AccessResult`,
+`GroupAccessDecision`, `CommandAuthDecision`, `DmCommandAccess`, or
+`{ allowed, reasonCode }` shapes unless that type is public plugin API.
+
+## Budget
+
+Measured against the PR merge-base with `origin/main`, including untracked
+files.
+
+```text
+merge-base            1671e7532adb
+
+current:
+core production       +3,922 / -546    = +3,376
+docs                  +601 / -17       = +584
+other                 +145 / -2        = +143
+plugin production     +4,148 / -5,388  = -1,240
+tests                 +2,326 / -2,414  = -88
+total                 +11,142 / -8,367 = +2,775
+
+required:
+plugin production     <= -1,500
+core production       <= +1,500, or paid for by larger plugin deletion
+tests                 <= +1,000
+total                 <= +2,000
+
+stretch:
+plugin production     <= -2,500
+core production       <= +1,200
+total                 <= 0
+```
+
+Minimum remaining cleanup:
+
+```text
+plugin production     needs 260 more net deleted lines
+total                 needs 775 more net deleted lines
+core production       still +1,876 over standalone budget, unless paid down by plugin deletion
+```
+
+Comment-only deletion does not count as cleanup. The previous budget pass was
+too generous because it included restored QQBot explanatory comments; this
+document tracks executable/docs/test code movement only.
+
+Re-measure after each cleanup wave:
+
+```sh
+base=$(git merge-base HEAD origin/main)
+git diff --shortstat "$base"
+git diff --numstat "$base" -- src/channels/message-access src/plugin-sdk extensions | sort -nr -k1 | head -n 80
+pnpm lint:extensions:no-deprecated-channel-access
+```
+
+## Diagnosis
+
+The first pass added the shared ingress kernel, then left too much plugin-local
+authorization beside it:
+
+```text
+platform facts
+  -> shared ingress state and decision
+  -> plugin-local DTO or legacy projection
+  -> plugin-local if/else ladder
+```
+
+That duplicates the model. Core production grew by about 3,376 lines, while
+bundled plugin production is 1,240 lines smaller. That is better than the first
+pass, but it is not inside the minimum budget. The fix remains deletion-first:
+
+- delete plugin DTOs that only rename ingress fields
+- delete tests that only assert wrapper shape
+- add core helpers only when the same patch deletes bundled plugin code
+- keep old SDK compatibility in SDK/core shims only
+- repack core after wrapper deletion exposes the stable shape
+
+## Hotspots
+
+Positive bundled production files that still need to shrink:
+
+```text
+extensions/telegram/src/ingress.ts                        +126
+extensions/discord/src/monitor/dm-command-auth.ts         +101
+extensions/signal/src/monitor/access-policy.ts             +92
+extensions/feishu/src/policy.ts                            +85
+extensions/slack/src/monitor/auth.ts                       +64
+extensions/googlechat/src/monitor-access.ts                +59
+extensions/nextcloud-talk/src/inbound.ts                   +51
+extensions/matrix/src/matrix/monitor/access-state.ts       +49
+extensions/irc/src/inbound.ts                              +44
+extensions/imessage/src/monitor/inbound-processing.ts      +36
+extensions/qa-channel/src/inbound.ts                       +34
+extensions/qqbot/src/bridge/sdk-adapter.ts                 +33
+extensions/tlon/src/monitor/utils.ts                       +30
+extensions/twitch/src/access-control.ts                    +22
+extensions/qqbot/src/engine/commands/slash-command-handler.ts +20
+extensions/telegram/src/bot-handlers.runtime.ts            +19
+```
+
+The branch is not inside the minimum budget yet. The remaining review-relevant
+work should delete repeated authorization flow, turn scaffolding, or wrapper
+tests before adding another core abstraction.
+
+## Current Code Read
+
+The healthy core seam already exists in `src/channels/message-access/runtime.ts`:
+it owns identity adapters, effective allowlists, pairing-store reads, route
+descriptors, command/event presets, access groups, and the final resolved
+`ResolvedChannelMessageIngress` projection.
+
+The remaining growth is mostly plugin glue layered on top of that seam:
+
+- `extensions/telegram/src/ingress.ts` wraps core decisions in Telegram-specific
+  command/event helpers, then call sites still pass precomputed normalized
+  allowlists and owner lists.
+- `extensions/discord/src/monitor/dm-command-auth.ts`,
+  `extensions/feishu/src/policy.ts`, `extensions/googlechat/src/monitor-access.ts`,
+  and `extensions/matrix/src/matrix/monitor/access-state.ts` still keep
+  local policy DTOs or legacy decision names beside ingress.
+- `extensions/signal/src/monitor/access-policy.ts` correctly keeps Signal
+  identity normalization and pairing replies local, but still has a wrapper
+  seam that should collapse into direct ingress consumption.
+- `extensions/nextcloud-talk/src/inbound.ts`, `extensions/irc/src/inbound.ts`,
+  `extensions/qa-channel/src/inbound.ts`, `extensions/zalo/src/monitor.ts`, and
+  `extensions/zalouser/src/monitor.ts` still repeat route/envelope/turn
+  assembly that can move to shared turn helpers outside the ingress kernel.
+
+Conclusion: moving more code into core is only useful if it deletes these
+plugin wrapper layers in the same patch. Adding another abstraction while
+leaving wrapper returns in place repeats the mistake.
+
+## Boundary
+
+Core owns generic policy:
+
+- allowlist normalization and matching
+- access-group expansion and diagnostics
+- pairing-store DM allowlist reads
+- route, sender, command, event, and activation gates
+- admission mapping: dispatch, drop, skip, observe, pairing
+- redacted state, decisions, diagnostics, and SDK compatibility projections
+- reusable generic descriptors for identity, route, command, event, activation,
+  and outcomes
+
+Plugins own transport facts and side effects:
+
+- webhook/socket/request authenticity
+- platform identity extraction and API lookups
+- channel-specific policy defaults
+- pairing challenge delivery, replies, acks, reactions, typing, media, history,
+  setup, doctor, status, logs, and user-facing copy
+
+Core must stay channel-agnostic: no Discord, Slack, Telegram, Matrix, room,
+guild, space, API client, or plugin-specific default in
+`src/channels/message-access`.
+
+## Acceptance Rule
+
+Every new core helper must delete bundled plugin production code immediately.
+
+```text
+one bundled caller        reject; keep plugin-local
+two bundled callers       accept only if plugin production LOC drops
+three or more callers     plugin deletion must be at least 2x new core LOC
+compatibility-only helper SDK/core shim only; never bundled hot paths
+```
+
+Stop and redesign if:
+
+- plugin production LOC increases
+- tests grow faster than production shrinks
+- a bundled hot path returns a DTO that only renames `ResolvedChannelMessageIngress`
+- a core helper needs a channel id, platform object, API client, or
+  channel-specific default
+
+## Work Packages
+
+1. Freeze the budget.
+   Put LOC in the PR, keep deprecated-ingress lint green, and include before/after
+   LOC in cleanup commits.
+
+2. Delete thin DTO seams.
+   Replace plugin-local wrapper returns with `ResolvedChannelMessageIngress`,
+   `senderAccess`, `commandAccess`, `routeAccess`, or `ingress` directly. Start
+   with QQBot, Telegram, Slack, Discord, Signal, Feishu, Matrix, iMessage, and
+   Tlon. Delete wrapper-shape tests; keep behavior tests.
+
+3. Add outcome classification only with deletions.
+   A generic classifier may expose `dispatch`, `pairing-required`,
+   `skip-activation`, `drop-command`, `drop-route`, `drop-sender`, and
+   `drop-ingress`. It must derive from the decision graph, not reason strings,
+   and migrate at least three plugins in the same patch.
+
+4. Add route descriptor builders only with deletions.
+   Generic route target and route sender helpers are acceptable only if they
+   immediately shrink route-heavy plugins: Google Chat, IRC, Microsoft Teams,
+   Nextcloud Talk, Mattermost, Slack, Zalo, and Zalo Personal.
+
+5. Add command/event presets only with deletions.
+   Centralize text-command, native-command, callback, and origin-subject shapes.
+   Command consumers must default to unauthorized when no command gate ran;
+   events must not start pairing.
+
+6. Add identity presets only where they remove boilerplate.
+   Stable-id, stable-id-plus-aliases, phone/e164, and multi-identifier helpers
+   are allowed when raw values enter only adapter input and redacted state keeps
+   opaque ids/counts.
+
+7. Share authorized turn assembly.
+   Outside the ingress kernel, remove repeated route/envelope/context/reply
+   scaffolding from QA Channel, IRC, Nextcloud Talk, Zalo, and Zalo Personal.
+   Core may own route/session/envelope/dispatch sequencing; plugins keep
+   delivery and channel-specific context.
+
+8. Quarantine compatibility.
+   Deprecated SDK helpers stay source-compatible, but bundled hot paths must not
+   import deprecated ingress or command-auth facades. Compatibility tests should
+   use fake third-party plugins, not bundled-plugin internals.
+
+9. Repack core.
+   After wrapper deletion, collapse one-use modules, remove unused exports, move
+   compatibility projection out of hot paths, and keep focused tests for identity,
+   route, command/event, activation, access groups, and compatibility shims.
+
+## Deletion Waves
+
+Run these in order. Each wave must lower bundled production LOC.
+
+1. Wrapper collapse, expected plugin delta: -400 to -600.
+   Replace plugin-local `resolveXAccess`, `resolveXCommandAccess`, and
+   `accessFromIngress` result types with direct reads from
+   `ResolvedChannelMessageIngress`. First targets: Discord DM command auth,
+   Feishu policy, Matrix access state, Telegram ingress, Signal access policy,
+   QQBot SDK adapter.
+
+2. Shared outcome helpers, expected plugin delta: -200 to -350.
+   Add one generic classifier only if it deletes repeated
+   `shouldBlockControlCommand`, pairing, activation skip, route block, and sender
+   block ladders across at least three plugins.
+
+3. Route descriptor builders, expected plugin delta: -200 to -350.
+   Move repeated route target and route sender descriptor assembly into core
+   helpers. First targets: Google Chat, IRC, Microsoft Teams, Nextcloud Talk,
+   Mattermost, Slack, Zalo, Zalo Personal.
+
+4. Turn assembly sharing, expected plugin delta: -250 to -450.
+   Use common route/session/envelope/dispatch sequencing for simple inbound
+   plugins. First targets: QA Channel, IRC, Nextcloud Talk, Zalo, Zalo Personal.
+
+5. Core repack, expected core delta: -300 to -700.
+   After plugins consume runtime projections directly, delete one-use modules,
+   merge tiny files back into `runtime.ts` or focused siblings, and keep SDK
+   compatibility files separate from bundled hot paths.
+
+6. Test pruning, expected test delta: -300 to -600.
+   Delete tests that only assert removed wrapper shapes. Keep behavior tests for
+   command denial, group fallback, origin-subject matching, activation skip,
+   access groups, pairing, and redaction.
+
+Expected minimum landing shape after these waves:
+
+```text
+plugin production     <= -1,500
+core production       about +1,800 to +2,200 before final repack
+tests                 <= +500
+total                 <= +2,000
+```
+
+## Do Not Move
+
+Do not move platform config defaults, setup UX, doctor/fix copy, API lookups,
+Slack owner-presence checks, Matrix alias/verification handling, Telegram
+callback parsing, command syntax parsing, native command registration, reaction
+payload parsing, pairing replies, command replies, acks, typing, media, history,
+or logs.
+
+## Verification
+
+Targeted local loop:
+
+```sh
+pnpm lint:extensions:no-deprecated-channel-access
+pnpm test src/channels/message-access/message-access.test.ts src/plugin-sdk/channel-ingress-runtime.test.ts src/plugin-sdk/access-groups.test.ts
+pnpm test extensions/<changed-plugin>/src/...
+pnpm plugin-sdk:api:check
+pnpm config:docs:check
+pnpm check:docs
+git diff --check
+```
+
+Use Testbox for broad changed gates/full-suite proof once the LOC trend is
+inside budget.
+
+Each work package records:
+
+- before/after LOC by category
+- deleted plugin wrappers
+- new core helper LOC, if any
+- targeted tests run
+- remaining hotspot list
+
+## Exit Criteria
+
+- bundled production imports no deprecated channel-access or command-auth facades
+- compatibility code is isolated to SDK/core seams
+- bundled plugins consume ingress projections or generic outcomes directly
+- plugin production LOC is at least 1,500 net negative against `origin/main`
+- core production LOC is `<= +1,500`, or any excess is paid for while total
+  stays `<= +2,000`
+- representative tests cover redaction, route, command/event, activation,
+  access-group, and channel-specific fallback behavior

package/docs/reference/AGENTS.default.md

@@ -0,0 +1,129 @@
+---
+summary: "Default Nodmix agent instructions and skills roster for the personal assistant setup"
+title: "Default AGENTS.md"
+read_when:
+  - Starting a new Nodmix agent session
+  - Enabling or auditing default skills
+---
+
+## First run (recommended)
+
+Nodmix uses a dedicated workspace directory for the agent. Default: `~/.nodmix/workspace` (configurable via `agents.defaults.workspace`).
+
+1. Create the workspace (if it doesn't already exist):
+
+```bash
+mkdir -p ~/.nodmix/workspace
+```
+
+2. Copy the default workspace templates into the workspace:
+
+```bash
+cp docs/reference/templates/AGENTS.md ~/.nodmix/workspace/AGENTS.md
+cp docs/reference/templates/SOUL.md ~/.nodmix/workspace/SOUL.md
+cp docs/reference/templates/TOOLS.md ~/.nodmix/workspace/TOOLS.md
+```
+
+3. Optional: if you want the personal assistant skill roster, replace AGENTS.md with this file:
+
+```bash
+cp docs/reference/AGENTS.default.md ~/.nodmix/workspace/AGENTS.md
+```
+
+4. Optional: choose a different workspace by setting `agents.defaults.workspace` (supports `~`):
+
+```json5
+{
+  agents: { defaults: { workspace: "~/.nodmix/workspace" } },
+}
+```
+
+## Safety defaults
+
+- Don't dump directories or secrets into chat.
+- Don't run destructive commands unless explicitly asked.
+- Don't send partial/streaming replies to external messaging surfaces (only final replies).
+
+## Session start (required)
+
+- Read `SOUL.md`, `USER.md`, and today+yesterday in `memory/`.
+- Read `MEMORY.md` when present.
+- Do it before responding.
+
+## Soul (required)
+
+- `SOUL.md` defines identity, tone, and boundaries. Keep it current.
+- If you change `SOUL.md`, tell the user.
+- You are a fresh instance each session; continuity lives in these files.
+
+## Shared spaces (recommended)
+
+- You're not the user's voice; be careful in group chats or public channels.
+- Don't share private data, contact info, or internal notes.
+
+## Memory system (recommended)
+
+- Daily log: `memory/YYYY-MM-DD.md` (create `memory/` if needed).
+- Long-term memory: `MEMORY.md` for durable facts, preferences, and decisions.
+- Lowercase `memory.md` is legacy repair input only; do not keep both root files on purpose.
+- On session start, read today + yesterday + `MEMORY.md` when present.
+- Capture: decisions, preferences, constraints, open loops.
+- Avoid secrets unless explicitly requested.
+
+## Tools and skills
+
+- Tools live in skills; follow each skill's `SKILL.md` when you need it.
+- Keep environment-specific notes in `TOOLS.md` (Notes for Skills).
+
+## Backup tip (recommended)
+
+If you treat this workspace as Clawd's "memory", make it a git repo (ideally private) so `AGENTS.md` and your memory files are backed up.
+
+```bash
+cd ~/.nodmix/workspace
+git init
+git add AGENTS.md
+git commit -m "Add Clawd workspace"
+# Optional: add a private remote + push
+```
+
+## What Nodmix does
+
+- Runs WhatsApp gateway + Pi coding agent so the assistant can read/write chats, fetch context, and run skills via the host Mac.
+- macOS app manages permissions (screen recording, notifications, microphone) and exposes the `nodmix` CLI via its bundled binary.
+- Direct chats collapse into the agent's `main` session by default; groups stay isolated as `agent:<agentId>:<channel>:group:<id>` (rooms/channels: `agent:<agentId>:<channel>:channel:<id>`); heartbeats keep background tasks alive.
+
+## Core skills (enable in Settings → Skills)
+
+- **mcporter** - Tool server runtime/CLI for managing external skill backends.
+- **Peekaboo** - Fast macOS screenshots with optional AI vision analysis.
+- **camsnap** - Capture frames, clips, or motion alerts from RTSP/ONVIF security cams.
+- **oracle** - OpenAI-ready agent CLI with session replay and browser control.
+- **eightctl** - Control your sleep, from the terminal.
+- **imsg** - Send, read, stream iMessage & SMS.
+- **wacli** - WhatsApp CLI: sync, search, send.
+- **discord** - Discord actions: react, stickers, polls. Use `user:<id>` or `channel:<id>` targets (bare numeric ids are ambiguous).
+- **gog** - Google Suite CLI: Gmail, Calendar, Drive, Contacts.
+- **spotify-player** - Terminal Spotify client to search/queue/control playback.
+- **sag** - ElevenLabs speech with mac-style say UX; streams to speakers by default.
+- **Sonos CLI** - Control Sonos speakers (discover/status/playback/volume/grouping) from scripts.
+- **blucli** - Play, group, and automate BluOS players from scripts.
+- **OpenHue CLI** - Philips Hue lighting control for scenes and automations.
+- **OpenAI Whisper** - Local speech-to-text for quick dictation and voicemail transcripts.
+- **Gemini CLI** - Google Gemini models from the terminal for fast Q&A.
+- **agent-tools** - Utility toolkit for automations and helper scripts.
+
+## Usage notes
+
+- Prefer the `nodmix` CLI for scripting; mac app handles permissions.
+- Run installs from the Skills tab; it hides the button if a binary is already present.
+- Keep heartbeats enabled so the assistant can schedule reminders, monitor inboxes, and trigger camera captures.
+- Canvas UI runs full-screen with native overlays. Avoid placing critical controls in the top-left/top-right/bottom edges; add explicit gutters in the layout and don't rely on safe-area insets.
+- For browser-driven verification, use `nodmix browser` (tabs/status/screenshot) with the Nodmix-managed Chrome profile.
+- For DOM inspection, use `nodmix browser eval|query|dom|snapshot` (and `--json`/`--out` when you need machine output).
+- For interactions, use `nodmix browser click|type|hover|drag|select|upload|press|wait|navigate|back|evaluate|run` (click/type require snapshot refs; use `evaluate` for CSS selectors).
+
+## Related
+
+- [Agent workspace](/concepts/agent-workspace)
+- [Agent runtime](/concepts/agent)