milaidy 1.0.0

package/docs/cli/approvals.md

@@ -0,0 +1,50 @@
+---
+summary: "CLI reference for `milaidy approvals` (exec approvals for gateway or node hosts)"
+read_when:
+  - You want to edit exec approvals from the CLI
+  - You need to manage allowlists on gateway or node hosts
+title: "approvals"
+---
+
+# `milaidy approvals`
+
+Manage exec approvals for the **local host**, **gateway host**, or a **node host**.
+By default, commands target the local approvals file on disk. Use `--gateway` to target the gateway, or `--node` to target a specific node.
+
+Related:
+
+- Exec approvals: [Exec approvals](/tools/exec-approvals)
+- Nodes: [Nodes](/nodes)
+
+## Common commands
+
+```bash
+milaidy approvals get
+milaidy approvals get --node <id|name|ip>
+milaidy approvals get --gateway
+```
+
+## Replace approvals from a file
+
+```bash
+milaidy approvals set --file ./exec-approvals.json
+milaidy approvals set --node <id|name|ip> --file ./exec-approvals.json
+milaidy approvals set --gateway --file ./exec-approvals.json
+```
+
+## Allowlist helpers
+
+```bash
+milaidy approvals allowlist add "~/Projects/**/bin/rg"
+milaidy approvals allowlist add --agent main --node <id|name|ip> "/usr/bin/uptime"
+milaidy approvals allowlist add --agent "*" "/usr/bin/uname"
+
+milaidy approvals allowlist remove "~/Projects/**/bin/rg"
+```
+
+## Notes
+
+- `--node` uses the same resolver as `milaidy nodes` (id, name, ip, or id prefix).
+- `--agent` defaults to `"*"`, which applies to all agents.
+- The node host must advertise `system.execApprovals.get/set` (macOS app or headless node host).
+- Approvals files are stored per host at `~/.milaidy/exec-approvals.json`.

package/docs/cli/browser.md

@@ -0,0 +1,107 @@
+---
+summary: "CLI reference for `milaidy browser` (profiles, tabs, actions, extension relay)"
+read_when:
+  - You use `milaidy browser` and want examples for common tasks
+  - You want to control a browser running on another machine via a node host
+  - You want to use the Chrome extension relay (attach/detach via toolbar button)
+title: "browser"
+---
+
+# `milaidy browser`
+
+Manage Milaidy’s browser control server and run browser actions (tabs, snapshots, screenshots, navigation, clicks, typing).
+
+Related:
+
+- Browser tool + API: [Browser tool](/tools/browser)
+- Chrome extension relay: [Chrome extension](/tools/chrome-extension)
+
+## Common flags
+
+- `--url <gatewayWsUrl>`: Gateway WebSocket URL (defaults to config).
+- `--token <token>`: Gateway token (if required).
+- `--timeout <ms>`: request timeout (ms).
+- `--browser-profile <name>`: choose a browser profile (default from config).
+- `--json`: machine-readable output (where supported).
+
+## Quick start (local)
+
+```bash
+milaidy browser --browser-profile chrome tabs
+milaidy browser --browser-profile milaidy start
+milaidy browser --browser-profile milaidy open https://example.com
+milaidy browser --browser-profile milaidy snapshot
+```
+
+## Profiles
+
+Profiles are named browser routing configs. In practice:
+
+- `milaidy`: launches/attaches to a dedicated Milaidy-managed Chrome instance (isolated user data dir).
+- `chrome`: controls your existing Chrome tab(s) via the Chrome extension relay.
+
+```bash
+milaidy browser profiles
+milaidy browser create-profile --name work --color "#FF5A36"
+milaidy browser delete-profile --name work
+```
+
+Use a specific profile:
+
+```bash
+milaidy browser --browser-profile work tabs
+```
+
+## Tabs
+
+```bash
+milaidy browser tabs
+milaidy browser open https://docs.milaidy.ai
+milaidy browser focus <targetId>
+milaidy browser close <targetId>
+```
+
+## Snapshot / screenshot / actions
+
+Snapshot:
+
+```bash
+milaidy browser snapshot
+```
+
+Screenshot:
+
+```bash
+milaidy browser screenshot
+```
+
+Navigate/click/type (ref-based UI automation):
+
+```bash
+milaidy browser navigate https://example.com
+milaidy browser click <ref>
+milaidy browser type <ref> "hello"
+```
+
+## Chrome extension relay (attach via toolbar button)
+
+This mode lets the agent control an existing Chrome tab that you attach manually (it does not auto-attach).
+
+Install the unpacked extension to a stable path:
+
+```bash
+milaidy browser extension install
+milaidy browser extension path
+```
+
+Then Chrome → `chrome://extensions` → enable “Developer mode” → “Load unpacked” → select the printed folder.
+
+Full guide: [Chrome extension](/tools/chrome-extension)
+
+## Remote browser control (node host proxy)
+
+If the Gateway runs on a different machine than the browser, run a **node host** on the machine that has Chrome/Brave/Edge/Chromium. The Gateway will proxy browser actions to that node (no separate browser control server required).
+
+Use `gateway.nodes.browser.mode` to control auto-routing and `gateway.nodes.browser.node` to pin a specific node if multiple are connected.
+
+Security + remote setup: [Browser tool](/tools/browser), [Remote access](/gateway/remote), [Tailscale](/gateway/tailscale), [Security](/gateway/security)

package/docs/cli/channels.md

@@ -0,0 +1,79 @@
+---
+summary: "CLI reference for `milaidy channels` (accounts, status, login/logout, logs)"
+read_when:
+  - You want to add/remove channel accounts (WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage)
+  - You want to check channel status or tail channel logs
+title: "channels"
+---
+
+# `milaidy channels`
+
+Manage chat channel accounts and their runtime status on the Gateway.
+
+Related docs:
+
+- Channel guides: [Channels](/channels/index)
+- Gateway configuration: [Configuration](/gateway/configuration)
+
+## Common commands
+
+```bash
+milaidy channels list
+milaidy channels status
+milaidy channels capabilities
+milaidy channels capabilities --channel discord --target channel:123
+milaidy channels resolve --channel slack "#general" "@jane"
+milaidy channels logs --channel all
+```
+
+## Add / remove accounts
+
+```bash
+milaidy channels add --channel telegram --token <bot-token>
+milaidy channels remove --channel telegram --delete
+```
+
+Tip: `milaidy channels add --help` shows per-channel flags (token, app token, signal-cli paths, etc).
+
+## Login / logout (interactive)
+
+```bash
+milaidy channels login --channel whatsapp
+milaidy channels logout --channel whatsapp
+```
+
+## Troubleshooting
+
+- Run `milaidy status --deep` for a broad probe.
+- Use `milaidy doctor` for guided fixes.
+- `milaidy channels list` prints `Claude: HTTP 403 ... user:profile` → usage snapshot needs the `user:profile` scope. Use `--no-usage`, or provide a claude.ai session key (`CLAUDE_WEB_SESSION_KEY` / `CLAUDE_WEB_COOKIE`), or re-auth via Claude Code CLI.
+
+## Capabilities probe
+
+Fetch provider capability hints (intents/scopes where available) plus static feature support:
+
+```bash
+milaidy channels capabilities
+milaidy channels capabilities --channel discord --target channel:123
+```
+
+Notes:
+
+- `--channel` is optional; omit it to list every channel (including extensions).
+- `--target` accepts `channel:<id>` or a raw numeric channel id and only applies to Discord.
+- Probes are provider-specific: Discord intents + optional channel permissions; Slack bot + user scopes; Telegram bot flags + webhook; Signal daemon version; MS Teams app token + Graph roles/scopes (annotated where known). Channels without probes report `Probe: unavailable`.
+
+## Resolve names to IDs
+
+Resolve channel/user names to IDs using the provider directory:
+
+```bash
+milaidy channels resolve --channel slack "#general" "@jane"
+milaidy channels resolve --channel discord "My Server/#support" "@someone"
+milaidy channels resolve --channel matrix "Project Room"
+```
+
+Notes:
+
+- Use `--kind user|group|auto` to force the target type.
+- Resolution prefers active matches when multiple entries share the same name.

package/docs/cli/config.md

@@ -0,0 +1,50 @@
+---
+summary: "CLI reference for `milaidy config` (get/set/unset config values)"
+read_when:
+  - You want to read or edit config non-interactively
+title: "config"
+---
+
+# `milaidy config`
+
+Config helpers: get/set/unset values by path. Run without a subcommand to open
+the configure wizard (same as `milaidy configure`).
+
+## Examples
+
+```bash
+milaidy config get browser.executablePath
+milaidy config set browser.executablePath "/usr/bin/google-chrome"
+milaidy config set agents.defaults.heartbeat.every "2h"
+milaidy config set agents.list[0].tools.exec.node "node-id-or-name"
+milaidy config unset tools.web.search.apiKey
+```
+
+## Paths
+
+Paths use dot or bracket notation:
+
+```bash
+milaidy config get agents.defaults.workspace
+milaidy config get agents.list[0].id
+```
+
+Use the agent list index to target a specific agent:
+
+```bash
+milaidy config get agents.list
+milaidy config set agents.list[1].tools.exec.node "node-id-or-name"
+```
+
+## Values
+
+Values are parsed as JSON5 when possible; otherwise they are treated as strings.
+Use `--json` to require JSON5 parsing.
+
+```bash
+milaidy config set agents.defaults.heartbeat.every "0m"
+milaidy config set gateway.port 19001 --json
+milaidy config set channels.whatsapp.groups '["*"]' --json
+```
+
+Restart the gateway after edits.

package/docs/cli/configure.md

@@ -0,0 +1,33 @@
+---
+summary: "CLI reference for `milaidy configure` (interactive configuration prompts)"
+read_when:
+  - You want to tweak credentials, devices, or agent defaults interactively
+title: "configure"
+---
+
+# `milaidy configure`
+
+Interactive prompt to set up credentials, devices, and agent defaults.
+
+Note: The **Model** section now includes a multi-select for the
+`agents.defaults.models` allowlist (what shows up in `/model` and the model picker).
+
+Tip: `milaidy config` without a subcommand opens the same wizard. Use
+`milaidy config get|set|unset` for non-interactive edits.
+
+Related:
+
+- Gateway configuration reference: [Configuration](/gateway/configuration)
+- Config CLI: [Config](/cli/config)
+
+Notes:
+
+- Choosing where the Gateway runs always updates `gateway.mode`. You can select "Continue" without other sections if that is all you need.
+- Channel-oriented services (Slack/Discord/Matrix/Microsoft Teams) prompt for channel/room allowlists during setup. You can enter names or IDs; the wizard resolves names to IDs when possible.
+
+## Examples
+
+```bash
+milaidy configure
+milaidy configure --section models --section channels
+```

package/docs/cli/cron.md

@@ -0,0 +1,42 @@
+---
+summary: "CLI reference for `milaidy cron` (schedule and run background jobs)"
+read_when:
+  - You want scheduled jobs and wakeups
+  - You’re debugging cron execution and logs
+title: "cron"
+---
+
+# `milaidy cron`
+
+Manage cron jobs for the Gateway scheduler.
+
+Related:
+
+- Cron jobs: [Cron jobs](/automation/cron-jobs)
+
+Tip: run `milaidy cron --help` for the full command surface.
+
+Note: isolated `cron add` jobs default to `--announce` delivery. Use `--no-deliver` to keep
+output internal. `--deliver` remains as a deprecated alias for `--announce`.
+
+Note: one-shot (`--at`) jobs delete after success by default. Use `--keep-after-run` to keep them.
+
+## Common edits
+
+Update delivery settings without changing the message:
+
+```bash
+milaidy cron edit <job-id> --announce --channel telegram --to "123456789"
+```
+
+Disable delivery for an isolated job:
+
+```bash
+milaidy cron edit <job-id> --no-deliver
+```
+
+Announce to a specific channel:
+
+```bash
+milaidy cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
+```

package/docs/cli/dashboard.md

@@ -0,0 +1,16 @@
+---
+summary: "CLI reference for `milaidy dashboard` (open the Control UI)"
+read_when:
+  - You want to open the Control UI with your current token
+  - You want to print the URL without launching a browser
+title: "dashboard"
+---
+
+# `milaidy dashboard`
+
+Open the Control UI using your current auth.
+
+```bash
+milaidy dashboard
+milaidy dashboard --no-open
+```

package/docs/cli/devices.md

@@ -0,0 +1,67 @@
+---
+summary: "CLI reference for `milaidy devices` (device pairing + token rotation/revocation)"
+read_when:
+  - You are approving device pairing requests
+  - You need to rotate or revoke device tokens
+title: "devices"
+---
+
+# `milaidy devices`
+
+Manage device pairing requests and device-scoped tokens.
+
+## Commands
+
+### `milaidy devices list`
+
+List pending pairing requests and paired devices.
+
+```
+milaidy devices list
+milaidy devices list --json
+```
+
+### `milaidy devices approve <requestId>`
+
+Approve a pending device pairing request.
+
+```
+milaidy devices approve <requestId>
+```
+
+### `milaidy devices reject <requestId>`
+
+Reject a pending device pairing request.
+
+```
+milaidy devices reject <requestId>
+```
+
+### `milaidy devices rotate --device <id> --role <role> [--scope <scope...>]`
+
+Rotate a device token for a specific role (optionally updating scopes).
+
+```
+milaidy devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write
+```
+
+### `milaidy devices revoke --device <id> --role <role>`
+
+Revoke a device token for a specific role.
+
+```
+milaidy devices revoke --device <deviceId> --role node
+```
+
+## Common options
+
+- `--url <url>`: Gateway WebSocket URL (defaults to `gateway.remote.url` when configured).
+- `--token <token>`: Gateway token (if required).
+- `--password <password>`: Gateway password (password auth).
+- `--timeout <ms>`: RPC timeout.
+- `--json`: JSON output (recommended for scripting).
+
+## Notes
+
+- Token rotation returns a new token (sensitive). Treat it like a secret.
+- These commands require `operator.pairing` (or `operator.admin`) scope.

package/docs/cli/directory.md

@@ -0,0 +1,63 @@
+---
+summary: "CLI reference for `milaidy directory` (self, peers, groups)"
+read_when:
+  - You want to look up contacts/groups/self ids for a channel
+  - You are developing a channel directory adapter
+title: "directory"
+---
+
+# `milaidy directory`
+
+Directory lookups for channels that support it (contacts/peers, groups, and “me”).
+
+## Common flags
+
+- `--channel <name>`: channel id/alias (required when multiple channels are configured; auto when only one is configured)
+- `--account <id>`: account id (default: channel default)
+- `--json`: output JSON
+
+## Notes
+
+- `directory` is meant to help you find IDs you can paste into other commands (especially `milaidy message send --target ...`).
+- For many channels, results are config-backed (allowlists / configured groups) rather than a live provider directory.
+- Default output is `id` (and sometimes `name`) separated by a tab; use `--json` for scripting.
+
+## Using results with `message send`
+
+```bash
+milaidy directory peers list --channel slack --query "U0"
+milaidy message send --channel slack --target user:U012ABCDEF --message "hello"
+```
+
+## ID formats (by channel)
+
+- WhatsApp: `+15551234567` (DM), `1234567890-1234567890@g.us` (group)
+- Telegram: `@username` or numeric chat id; groups are numeric ids
+- Slack: `user:U…` and `channel:C…`
+- Discord: `user:<id>` and `channel:<id>`
+- Matrix (plugin): `user:@user:server`, `room:!roomId:server`, or `#alias:server`
+- Microsoft Teams (plugin): `user:<id>` and `conversation:<id>`
+- Zalo (plugin): user id (Bot API)
+- Zalo Personal / `zalouser` (plugin): thread id (DM/group) from `zca` (`me`, `friend list`, `group list`)
+
+## Self (“me”)
+
+```bash
+milaidy directory self --channel zalouser
+```
+
+## Peers (contacts/users)
+
+```bash
+milaidy directory peers list --channel zalouser
+milaidy directory peers list --channel zalouser --query "name"
+milaidy directory peers list --channel zalouser --limit 50
+```
+
+## Groups
+
+```bash
+milaidy directory groups list --channel zalouser
+milaidy directory groups list --channel zalouser --query "work"
+milaidy directory groups members --channel zalouser --group-id <id>
+```

package/docs/cli/dns.md

@@ -0,0 +1,23 @@
+---
+summary: "CLI reference for `milaidy dns` (wide-area discovery helpers)"
+read_when:
+  - You want wide-area discovery (DNS-SD) via Tailscale + CoreDNS
+  - You’re setting up split DNS for a custom discovery domain (example: milaidy.internal)
+title: "dns"
+---
+
+# `milaidy dns`
+
+DNS helpers for wide-area discovery (Tailscale + CoreDNS). Currently focused on macOS + Homebrew CoreDNS.
+
+Related:
+
+- Gateway discovery: [Discovery](/gateway/discovery)
+- Wide-area discovery config: [Configuration](/gateway/configuration)
+
+## Setup
+
+```bash
+milaidy dns setup
+milaidy dns setup --apply
+```

package/docs/cli/docs.md

@@ -0,0 +1,15 @@
+---
+summary: "CLI reference for `milaidy docs` (search the live docs index)"
+read_when:
+  - You want to search the live Milaidy docs from the terminal
+title: "docs"
+---
+
+# `milaidy docs`
+
+Search the live docs index.
+
+```bash
+milaidy docs browser extension
+milaidy docs sandbox allowHostControl
+```

package/docs/cli/doctor.md

@@ -0,0 +1,41 @@
+---
+summary: "CLI reference for `milaidy doctor` (health checks + guided repairs)"
+read_when:
+  - You have connectivity/auth issues and want guided fixes
+  - You updated and want a sanity check
+title: "doctor"
+---
+
+# `milaidy doctor`
+
+Health checks + quick fixes for the gateway and channels.
+
+Related:
+
+- Troubleshooting: [Troubleshooting](/gateway/troubleshooting)
+- Security audit: [Security](/gateway/security)
+
+## Examples
+
+```bash
+milaidy doctor
+milaidy doctor --repair
+milaidy doctor --deep
+```
+
+Notes:
+
+- Interactive prompts (like keychain/OAuth fixes) only run when stdin is a TTY and `--non-interactive` is **not** set. Headless runs (cron, Telegram, no terminal) will skip prompts.
+- `--fix` (alias for `--repair`) writes a backup to `~/.milaidy/milaidy.json.bak` and drops unknown config keys, listing each removal.
+
+## macOS: `launchctl` env overrides
+
+If you previously ran `launchctl setenv MILAIDY_GATEWAY_TOKEN ...` (or `...PASSWORD`), that value overrides your config file and can cause persistent “unauthorized” errors.
+
+```bash
+launchctl getenv MILAIDY_GATEWAY_TOKEN
+launchctl getenv MILAIDY_GATEWAY_PASSWORD
+
+launchctl unsetenv MILAIDY_GATEWAY_TOKEN
+launchctl unsetenv MILAIDY_GATEWAY_PASSWORD
+```