milaidy 1.0.0

package/docs/cli/reset.md

@@ -0,0 +1,17 @@
+---
+summary: "CLI reference for `milaidy reset` (reset local state/config)"
+read_when:
+  - You want to wipe local state while keeping the CLI installed
+  - You want a dry-run of what would be removed
+title: "reset"
+---
+
+# `milaidy reset`
+
+Reset local config/state (keeps the CLI installed).
+
+```bash
+milaidy reset
+milaidy reset --dry-run
+milaidy reset --scope config+creds+sessions --yes --non-interactive
+```

package/docs/cli/sandbox.md

@@ -0,0 +1,152 @@
+---
+title: Sandbox CLI
+summary: "Manage sandbox containers and inspect effective sandbox policy"
+read_when: "You are managing sandbox containers or debugging sandbox/tool-policy behavior."
+status: active
+---
+
+# Sandbox CLI
+
+Manage Docker-based sandbox containers for isolated agent execution.
+
+## Overview
+
+Milaidy can run agents in isolated Docker containers for security. The `sandbox` commands help you manage these containers, especially after updates or configuration changes.
+
+## Commands
+
+### `milaidy sandbox explain`
+
+Inspect the **effective** sandbox mode/scope/workspace access, sandbox tool policy, and elevated gates (with fix-it config key paths).
+
+```bash
+milaidy sandbox explain
+milaidy sandbox explain --session agent:main:main
+milaidy sandbox explain --agent work
+milaidy sandbox explain --json
+```
+
+### `milaidy sandbox list`
+
+List all sandbox containers with their status and configuration.
+
+```bash
+milaidy sandbox list
+milaidy sandbox list --browser  # List only browser containers
+milaidy sandbox list --json     # JSON output
+```
+
+**Output includes:**
+
+- Container name and status (running/stopped)
+- Docker image and whether it matches config
+- Age (time since creation)
+- Idle time (time since last use)
+- Associated session/agent
+
+### `milaidy sandbox recreate`
+
+Remove sandbox containers to force recreation with updated images/config.
+
+```bash
+milaidy sandbox recreate --all                # Recreate all containers
+milaidy sandbox recreate --session main       # Specific session
+milaidy sandbox recreate --agent mybot        # Specific agent
+milaidy sandbox recreate --browser            # Only browser containers
+milaidy sandbox recreate --all --force        # Skip confirmation
+```
+
+**Options:**
+
+- `--all`: Recreate all sandbox containers
+- `--session <key>`: Recreate container for specific session
+- `--agent <id>`: Recreate containers for specific agent
+- `--browser`: Only recreate browser containers
+- `--force`: Skip confirmation prompt
+
+**Important:** Containers are automatically recreated when the agent is next used.
+
+## Use Cases
+
+### After updating Docker images
+
+```bash
+# Pull new image
+docker pull milaidy-sandbox:latest
+docker tag milaidy-sandbox:latest milaidy-sandbox:bookworm-slim
+
+# Update config to use new image
+# Edit config: agents.defaults.sandbox.docker.image (or agents.list[].sandbox.docker.image)
+
+# Recreate containers
+milaidy sandbox recreate --all
+```
+
+### After changing sandbox configuration
+
+```bash
+# Edit config: agents.defaults.sandbox.* (or agents.list[].sandbox.*)
+
+# Recreate to apply new config
+milaidy sandbox recreate --all
+```
+
+### After changing setupCommand
+
+```bash
+milaidy sandbox recreate --all
+# or just one agent:
+milaidy sandbox recreate --agent family
+```
+
+### For a specific agent only
+
+```bash
+# Update only one agent's containers
+milaidy sandbox recreate --agent alfred
+```
+
+## Why is this needed?
+
+**Problem:** When you update sandbox Docker images or configuration:
+
+- Existing containers continue running with old settings
+- Containers are only pruned after 24h of inactivity
+- Regularly-used agents keep old containers running indefinitely
+
+**Solution:** Use `milaidy sandbox recreate` to force removal of old containers. They'll be recreated automatically with current settings when next needed.
+
+Tip: prefer `milaidy sandbox recreate` over manual `docker rm`. It uses the
+Gateway’s container naming and avoids mismatches when scope/session keys change.
+
+## Configuration
+
+Sandbox settings live in `~/.milaidy/milaidy.json` under `agents.defaults.sandbox` (per-agent overrides go in `agents.list[].sandbox`):
+
+```jsonc
+{
+  "agents": {
+    "defaults": {
+      "sandbox": {
+        "mode": "all", // off, non-main, all
+        "scope": "agent", // session, agent, shared
+        "docker": {
+          "image": "milaidy-sandbox:bookworm-slim",
+          "containerPrefix": "milaidy-sbx-",
+          // ... more Docker options
+        },
+        "prune": {
+          "idleHours": 24, // Auto-prune after 24h idle
+          "maxAgeDays": 7, // Auto-prune after 7 days
+        },
+      },
+    },
+  },
+}
+```
+
+## See Also
+
+- [Sandbox Documentation](/gateway/sandboxing)
+- [Agent Configuration](/concepts/agent-workspace)
+- [Doctor Command](/gateway/doctor) - Check sandbox setup

package/docs/cli/security.md

@@ -0,0 +1,26 @@
+---
+summary: "CLI reference for `milaidy security` (audit and fix common security footguns)"
+read_when:
+  - You want to run a quick security audit on config/state
+  - You want to apply safe “fix” suggestions (chmod, tighten defaults)
+title: "security"
+---
+
+# `milaidy security`
+
+Security tools (audit + optional fixes).
+
+Related:
+
+- Security guide: [Security](/gateway/security)
+
+## Audit
+
+```bash
+milaidy security audit
+milaidy security audit --deep
+milaidy security audit --fix
+```
+
+The audit warns when multiple DM senders share the main session and recommends **secure DM mode**: `session.dmScope="per-channel-peer"` (or `per-account-channel-peer` for multi-account channels) for shared inboxes.
+It also warns when small models (`<=300B`) are used without sandboxing and with web/browser tools enabled.

package/docs/cli/sessions.md

@@ -0,0 +1,16 @@
+---
+summary: "CLI reference for `milaidy sessions` (list stored sessions + usage)"
+read_when:
+  - You want to list stored sessions and see recent activity
+title: "sessions"
+---
+
+# `milaidy sessions`
+
+List stored conversation sessions.
+
+```bash
+milaidy sessions
+milaidy sessions --active 120
+milaidy sessions --json
+```

package/docs/cli/setup.md

@@ -0,0 +1,29 @@
+---
+summary: "CLI reference for `milaidy setup` (initialize config + workspace)"
+read_when:
+  - You’re doing first-run setup without the full onboarding wizard
+  - You want to set the default workspace path
+title: "setup"
+---
+
+# `milaidy setup`
+
+Initialize `~/.milaidy/milaidy.json` and the agent workspace.
+
+Related:
+
+- Getting started: [Getting started](/start/getting-started)
+- Wizard: [Onboarding](/start/onboarding)
+
+## Examples
+
+```bash
+milaidy setup
+milaidy setup --workspace ~/.milaidy/workspace
+```
+
+To run the wizard via setup:
+
+```bash
+milaidy setup --wizard
+```

package/docs/cli/skills.md

@@ -0,0 +1,26 @@
+---
+summary: "CLI reference for `milaidy skills` (list/info/check) and skill eligibility"
+read_when:
+  - You want to see which skills are available and ready to run
+  - You want to debug missing binaries/env/config for skills
+title: "skills"
+---
+
+# `milaidy skills`
+
+Inspect skills (bundled + workspace + managed overrides) and see what’s eligible vs missing requirements.
+
+Related:
+
+- Skills system: [Skills](/tools/skills)
+- Skills config: [Skills config](/tools/skills-config)
+- ClawHub installs: [ClawHub](/tools/clawhub)
+
+## Commands
+
+```bash
+milaidy skills list
+milaidy skills list --eligible
+milaidy skills info <name>
+milaidy skills check
+```

package/docs/cli/status.md

@@ -0,0 +1,26 @@
+---
+summary: "CLI reference for `milaidy status` (diagnostics, probes, usage snapshots)"
+read_when:
+  - You want a quick diagnosis of channel health + recent session recipients
+  - You want a pasteable “all” status for debugging
+title: "status"
+---
+
+# `milaidy status`
+
+Diagnostics for channels + sessions.
+
+```bash
+milaidy status
+milaidy status --all
+milaidy status --deep
+milaidy status --usage
+```
+
+Notes:
+
+- `--deep` runs live probes (WhatsApp Web + Telegram + Discord + Google Chat + Slack + Signal).
+- Output includes per-agent session stores when multiple agents are configured.
+- Overview includes Gateway + node host service install/runtime status when available.
+- Overview includes update channel + git SHA (for source checkouts).
+- Update info surfaces in the Overview; if an update is available, status prints a hint to run `milaidy update` (see [Updating](/install/updating)).

package/docs/cli/system.md

@@ -0,0 +1,60 @@
+---
+summary: "CLI reference for `milaidy system` (system events, heartbeat, presence)"
+read_when:
+  - You want to enqueue a system event without creating a cron job
+  - You need to enable or disable heartbeats
+  - You want to inspect system presence entries
+title: "system"
+---
+
+# `milaidy system`
+
+System-level helpers for the Gateway: enqueue system events, control heartbeats,
+and view presence.
+
+## Common commands
+
+```bash
+milaidy system event --text "Check for urgent follow-ups" --mode now
+milaidy system heartbeat enable
+milaidy system heartbeat last
+milaidy system presence
+```
+
+## `system event`
+
+Enqueue a system event on the **main** session. The next heartbeat will inject
+it as a `System:` line in the prompt. Use `--mode now` to trigger the heartbeat
+immediately; `next-heartbeat` waits for the next scheduled tick.
+
+Flags:
+
+- `--text <text>`: required system event text.
+- `--mode <mode>`: `now` or `next-heartbeat` (default).
+- `--json`: machine-readable output.
+
+## `system heartbeat last|enable|disable`
+
+Heartbeat controls:
+
+- `last`: show the last heartbeat event.
+- `enable`: turn heartbeats back on (use this if they were disabled).
+- `disable`: pause heartbeats.
+
+Flags:
+
+- `--json`: machine-readable output.
+
+## `system presence`
+
+List the current system presence entries the Gateway knows about (nodes,
+instances, and similar status lines).
+
+Flags:
+
+- `--json`: machine-readable output.
+
+## Notes
+
+- Requires a running Gateway reachable by your current config (local or remote).
+- System events are ephemeral and not persisted across restarts.

package/docs/cli/tui.md

@@ -0,0 +1,23 @@
+---
+summary: "CLI reference for `milaidy tui` (terminal UI connected to the Gateway)"
+read_when:
+  - You want a terminal UI for the Gateway (remote-friendly)
+  - You want to pass url/token/session from scripts
+title: "tui"
+---
+
+# `milaidy tui`
+
+Open the terminal UI connected to the Gateway.
+
+Related:
+
+- TUI guide: [TUI](/tui)
+
+## Examples
+
+```bash
+milaidy tui
+milaidy tui --url ws://127.0.0.1:18789 --token <token>
+milaidy tui --session main --deliver
+```

package/docs/cli/uninstall.md

@@ -0,0 +1,17 @@
+---
+summary: "CLI reference for `milaidy uninstall` (remove gateway service + local data)"
+read_when:
+  - You want to remove the gateway service and/or local state
+  - You want a dry-run first
+title: "uninstall"
+---
+
+# `milaidy uninstall`
+
+Uninstall the gateway service + local data (CLI remains).
+
+```bash
+milaidy uninstall
+milaidy uninstall --all --yes
+milaidy uninstall --dry-run
+```

package/docs/cli/update.md

@@ -0,0 +1,98 @@
+---
+summary: "CLI reference for `milaidy update` (safe-ish source update + gateway auto-restart)"
+read_when:
+  - You want to update a source checkout safely
+  - You need to understand `--update` shorthand behavior
+title: "update"
+---
+
+# `milaidy update`
+
+Safely update Milaidy and switch between stable/beta/dev channels.
+
+If you installed via **npm/pnpm** (global install, no git metadata), updates happen via the package manager flow in [Updating](/install/updating).
+
+## Usage
+
+```bash
+milaidy update
+milaidy update status
+milaidy update wizard
+milaidy update --channel beta
+milaidy update --channel dev
+milaidy update --tag beta
+milaidy update --no-restart
+milaidy update --json
+milaidy --update
+```
+
+## Options
+
+- `--no-restart`: skip restarting the Gateway service after a successful update.
+- `--channel <stable|beta|dev>`: set the update channel (git + npm; persisted in config).
+- `--tag <dist-tag|version>`: override the npm dist-tag or version for this update only.
+- `--json`: print machine-readable `UpdateRunResult` JSON.
+- `--timeout <seconds>`: per-step timeout (default is 1200s).
+
+Note: downgrades require confirmation because older versions can break configuration.
+
+## `update status`
+
+Show the active update channel + git tag/branch/SHA (for source checkouts), plus update availability.
+
+```bash
+milaidy update status
+milaidy update status --json
+milaidy update status --timeout 10
+```
+
+Options:
+
+- `--json`: print machine-readable status JSON.
+- `--timeout <seconds>`: timeout for checks (default is 3s).
+
+## `update wizard`
+
+Interactive flow to pick an update channel and confirm whether to restart the Gateway
+after updating (default is to restart). If you select `dev` without a git checkout, it
+offers to create one.
+
+## What it does
+
+When you switch channels explicitly (`--channel ...`), Milaidy also keeps the
+install method aligned:
+
+- `dev` → ensures a git checkout (default: `~/milaidy`, override with `MILAIDY_GIT_DIR`),
+  updates it, and installs the global CLI from that checkout.
+- `stable`/`beta` → installs from npm using the matching dist-tag.
+
+## Git checkout flow
+
+Channels:
+
+- `stable`: checkout the latest non-beta tag, then build + doctor.
+- `beta`: checkout the latest `-beta` tag, then build + doctor.
+- `dev`: checkout `main`, then fetch + rebase.
+
+High-level:
+
+1. Requires a clean worktree (no uncommitted changes).
+2. Switches to the selected channel (tag or branch).
+3. Fetches upstream (dev only).
+4. Dev only: preflight lint + TypeScript build in a temp worktree; if the tip fails, walks back up to 10 commits to find the newest clean build.
+5. Rebases onto the selected commit (dev only).
+6. Installs deps (pnpm preferred; npm fallback).
+7. Builds + builds the Control UI.
+8. Runs `milaidy doctor` as the final “safe update” check.
+9. Syncs plugins to the active channel (dev uses bundled extensions; stable/beta uses npm) and updates npm-installed plugins.
+
+## `--update` shorthand
+
+`milaidy --update` rewrites to `milaidy update` (useful for shells and launcher scripts).
+
+## See also
+
+- `milaidy doctor` (offers to run update first on git checkouts)
+- [Development channels](/install/development-channels)
+- [Updating](/install/updating)
+- [CLI reference](/cli)

package/docs/cli/voicecall.md

@@ -0,0 +1,34 @@
+---
+summary: "CLI reference for `milaidy voicecall` (voice-call plugin command surface)"
+read_when:
+  - You use the voice-call plugin and want the CLI entry points
+  - You want quick examples for `voicecall call|continue|status|tail|expose`
+title: "voicecall"
+---
+
+# `milaidy voicecall`
+
+`voicecall` is a plugin-provided command. It only appears if the voice-call plugin is installed and enabled.
+
+Primary doc:
+
+- Voice-call plugin: [Voice Call](/plugins/voice-call)
+
+## Common commands
+
+```bash
+milaidy voicecall status --call-id <id>
+milaidy voicecall call --to "+15555550123" --message "Hello" --mode notify
+milaidy voicecall continue --call-id <id> --message "Any questions?"
+milaidy voicecall end --call-id <id>
+```
+
+## Exposing webhooks (Tailscale)
+
+```bash
+milaidy voicecall expose --mode serve
+milaidy voicecall expose --mode funnel
+milaidy voicecall unexpose
+```
+
+Security note: only expose the webhook endpoint to networks you trust. Prefer Tailscale Serve over Funnel when possible.

package/docs/cli/webhooks.md

@@ -0,0 +1,25 @@
+---
+summary: "CLI reference for `milaidy webhooks` (webhook helpers + Gmail Pub/Sub)"
+read_when:
+  - You want to wire Gmail Pub/Sub events into Milaidy
+  - You want webhook helper commands
+title: "webhooks"
+---
+
+# `milaidy webhooks`
+
+Webhook helpers and integrations (Gmail Pub/Sub, webhook helpers).
+
+Related:
+
+- Webhooks: [Webhook](/automation/webhook)
+- Gmail Pub/Sub: [Gmail Pub/Sub](/automation/gmail-pubsub)
+
+## Gmail
+
+```bash
+milaidy webhooks gmail setup --account you@example.com
+milaidy webhooks gmail run
+```
+
+See [Gmail Pub/Sub documentation](/automation/gmail-pubsub) for details.