milaidy 1.0.0

package/docs/start/onboarding.md

@@ -0,0 +1,258 @@
+---
+summary: "Unified onboarding flow for Milaidy powered by ElizaOS"
+read_when:
+  - Setting up Milaidy for the first time
+  - Understanding the onboarding assistant
+  - Implementing auth or identity setup
+title: "Onboarding"
+---
+
+# Onboarding
+
+This document describes the unified onboarding flow for Milaidy, powered by the
+ElizaOS runtime. The flow works across CLI, macOS app, and conversational modes,
+providing a smooth "day 0" experience.
+
+## Quick Start
+
+The fastest way to get started:
+
+```bash
+# Install Milaidy
+npm install -g milaidy
+
+# Run the onboarding wizard
+milaidy onboard
+
+# Or start chatting immediately via the Control UI
+milaidy dashboard
+```
+
+## Onboarding Modes
+
+Milaidy supports three onboarding modes:
+
+| Mode | Best For | Entry Point |
+|------|----------|-------------|
+| **CLI Interactive** | Terminal users, servers | `milaidy onboard` |
+| **macOS App** | Desktop users | Milaidy.app first launch |
+| **Non-Interactive** | CI/CD, automation | `milaidy onboard --non-interactive` |
+
+## Flow Overview
+
+### Step-by-Step Guide
+
+1. **Welcome + Security Notice**
+   - Review the security notice
+   - Accept terms to proceed
+
+2. **Gateway Mode Selection**
+   - **Local (default):** Gateway runs on your machine
+   - **Remote:** Connect to a Gateway elsewhere via SSH/Tailnet
+   - **Configure later:** Skip setup temporarily
+
+3. **Model/Auth Configuration**
+   - Select your AI provider (Anthropic, OpenAI, Google, etc.)
+   - Provide API key or complete OAuth flow
+   - Credentials stored securely in `~/.milaidy/credentials/`
+
+4. **Workspace Setup**
+   - Default: `~/.milaidy/workspace`
+   - Seeds bootstrap files (`AGENTS.md`, `BOOTSTRAP.md`, etc.)
+   - Configurable via `--workspace` flag
+
+5. **Gateway Configuration**
+   - Port (default: 18789)
+   - Bind address (loopback, LAN, or all interfaces)
+   - Auth mode (token recommended)
+   - Optional Tailscale exposure
+
+6. **Channel Setup** (optional)
+   - Telegram, Discord, WhatsApp, Slack, Signal, etc.
+   - Each channel prompts for its required credentials
+   - See [Channels](/channels) for details
+
+7. **Plugin Auto-Enable**
+   - ElizaOS plugins auto-enable based on detected secrets
+   - Configure allow/deny lists via `character.json`
+   - See [Plugins](/concepts/plugins) for details
+
+8. **Skills Installation** (optional)
+   - Install recommended skills from ClawHub
+   - Configure node package manager (npm/pnpm)
+
+9. **Daemon Installation** (optional)
+   - macOS: LaunchAgent
+   - Linux: systemd user unit
+
+10. **Health Check + Finish**
+    - Verifies Gateway connectivity
+    - Opens onboarding chat session
+
+## CLI Mode
+
+```bash
+# Full interactive onboarding
+milaidy onboard
+
+# QuickStart (uses defaults)
+milaidy onboard --quickstart
+
+# Advanced (full control over every step)
+milaidy onboard --advanced
+
+# Reconfigure existing setup
+milaidy configure
+```
+
+### Non-Interactive Mode
+
+For scripting and automation:
+
+```bash
+milaidy onboard --non-interactive \
+  --mode local \
+  --auth-choice apiKey \
+  --anthropic-api-key "$ANTHROPIC_API_KEY" \
+  --gateway-port 18789 \
+  --gateway-bind loopback \
+  --install-daemon \
+  --daemon-runtime node \
+  --skip-skills
+```
+
+Add `--json` for machine-readable output.
+
+## macOS App Mode
+
+The macOS app provides a native onboarding experience:
+
+1. **Welcome + Security Notice** - SwiftUI native view
+2. **Gateway Selection** - Local / Remote / Configure later
+3. **Auth (OAuth)** - Browser-based OAuth with PKCE
+4. **Setup Wizard** - Gateway-driven (same logic as CLI)
+5. **Permissions** - TCC prompts (Notifications, Accessibility, etc.)
+6. **CLI Installation** - Optional global CLI install
+7. **Onboarding Chat** - Dedicated session for first-run guidance
+
+### macOS Permissions
+
+The app requests TCC permissions for:
+
+- Notifications
+- Accessibility
+- Screen Recording
+- Microphone / Speech Recognition
+- Automation (AppleScript)
+
+## Conversational Onboarding
+
+After initial setup, the agent can guide you through additional configuration
+via natural conversation:
+
+```
+You: I want to set up Telegram
+Agent: I'll help you configure Telegram. First, you'll need a bot token from @BotFather...
+```
+
+The agent uses ElizaOS actions to:
+- Validate credentials
+- Update configuration
+- Test connections
+- Guide troubleshooting
+
+## Agent Bootstrap Ritual
+
+On first agent run, Milaidy bootstraps the workspace:
+
+1. Seeds template files:
+   - `AGENTS.md` - Agent guidelines
+   - `TOOLS.md` - Tool configuration
+   - `IDENTITY.md` - Agent identity
+   - `USER.md` - User preferences
+   - `HEARTBEAT.md` - Heartbeat instructions
+   - `MEMORY.md` - Memory workflow
+   - `BOOTSTRAP.md` - First-run instructions (removed after onboarding)
+
+2. Runs a short Q&A ritual (one question at a time)
+
+3. Writes personalization to:
+   - `IDENTITY.md` - Agent personality
+   - `USER.md` - User preferences
+
+4. Removes `BOOTSTRAP.md` when complete (runs once)
+
+## Secret Management
+
+During onboarding, secrets are stored in multiple locations:
+
+| Location | Purpose |
+|----------|---------|
+| `~/.milaidy/.env` | Environment variables for daemon |
+| `~/.milaidy/credentials/` | OAuth tokens, API keys |
+| `character.settings.secrets` | Per-character secrets |
+
+See [Secrets](/concepts/secrets) for canonical key names and validation.
+
+## Remote Mode
+
+When connecting to a remote Gateway:
+
+1. Credentials and workspace live **on the remote host**
+2. Use SSH tunneling or Tailnet for loopback-only Gateways
+3. Configure via:
+   - `~/.milaidy/credentials/oauth.json`
+   - `~/.milaidy/agents/<agentId>/agent/auth-profiles.json`
+
+Discovery hints:
+- macOS: Bonjour (`dns-sd`)
+- Linux: Avahi (`avahi-browse`)
+
+## Gmail Hooks (Optional)
+
+Gmail Pub/Sub setup is a manual step:
+
+```bash
+milaidy webhooks gmail setup --account you@gmail.com
+```
+
+See [Gmail Pub/Sub](/automation/gmail-pubsub) for details.
+
+## Troubleshooting
+
+### Reset Onboarding
+
+```bash
+# Reset config only
+milaidy onboard --reset
+
+# Full reset (config + credentials + sessions)
+milaidy doctor --reset
+```
+
+### Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| Gateway won't start | Check port 18789 availability |
+| OAuth fails | Ensure browser can open, paste `code#state` value |
+| Channel not connecting | Verify credentials, run `milaidy channels status` |
+| Skills not loading | Check `skills.entries` in config, run `milaidy doctor` |
+
+### Doctor Command
+
+```bash
+# Diagnose configuration issues
+milaidy doctor
+
+# Fix common problems automatically
+milaidy doctor --fix
+```
+
+## Related Docs
+
+- [CLI Wizard](/start/wizard) - Detailed wizard options
+- [Secrets](/concepts/secrets) - Secret key management
+- [Plugins](/concepts/plugins) - ElizaOS plugin system
+- [Gateway Configuration](/gateway/configuration) - Advanced Gateway setup
+- [Channels](/channels) - Channel configuration

package/docs/start/pairing.md

@@ -0,0 +1,86 @@
+---
+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 Milaidy security posture
+title: "Pairing"
+---
+
+# Pairing
+
+“Pairing” is Milaidy’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: [Security](/gateway/security)
+
+## 1) DM pairing (inbound chat access)
+
+When a channel 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: [Security](/gateway/security)
+
+Pairing codes:
+
+- 8 characters, uppercase, no ambiguous chars (`0O1I`).
+- **Expire after 1 hour**. The bot only sends the pairing message when a new request is created (roughly once per hour per sender).
+- Pending DM pairing requests are capped at **3 per channel** by default; additional requests are ignored until one expires or is approved.
+
+### Approve a sender
+
+```bash
+milaidy pairing list telegram
+milaidy pairing approve telegram <CODE>
+```
+
+Supported channels: `telegram`, `whatsapp`, `signal`, `imessage`, `discord`, `slack`, `msteams`, `googlechat`.
+
+### Where the state lives
+
+Stored under `~/.milaidy/credentials/`:
+
+- Pending requests: `<channel>-pairing.json`
+- Approved allowlist store: `<channel>-allowFrom.json`
+
+Treat these as sensitive (they gate access to your assistant).
+
+## 2) Node device pairing (iOS/Android/macOS/headless nodes)
+
+Nodes connect to the Gateway as **devices** with `role: node`. The Gateway
+creates a device pairing request that must be approved.
+
+### Approve a node device
+
+```bash
+milaidy devices list
+milaidy devices approve <requestId>
+milaidy devices reject <requestId>
+```
+
+### Where the state lives
+
+Stored under `~/.milaidy/devices/`:
+
+- `pending.json` (short-lived; pending requests expire)
+- `paired.json` (paired devices + tokens)
+
+### Notes
+
+- The legacy `node.pair.*` API (CLI: `milaidy nodes pending/approve`) is a
+  separate gateway-owned pairing store. WS nodes still require device pairing.
+
+## Related docs
+
+- Security model + prompt injection: [Security](/gateway/security)
+- Updating safely (run doctor): [Updating](/install/updating)
+- Channel configs:
+  - Telegram: [Telegram](/channels/telegram)
+  - WhatsApp: [WhatsApp](/channels/whatsapp)
+  - Signal: [Signal](/channels/signal)
+  - BlueBubbles (iMessage): [BlueBubbles](/channels/bluebubbles)
+  - iMessage (legacy): [iMessage](/channels/imessage)
+  - Discord: [Discord](/channels/discord)
+  - Slack: [Slack](/channels/slack)

package/docs/start/quickstart.md

@@ -0,0 +1,81 @@
+---
+summary: "Install Milaidy, onboard the Gateway, and pair your first channel."
+read_when:
+  - You want the fastest path from install to a working Gateway
+title: "Quick start"
+---
+
+<Note>
+Milaidy requires Node 22 or newer.
+</Note>
+
+## Install
+
+<Tabs>
+  <Tab title="npm">
+    ```bash
+    npm install -g milaidy@latest
+    ```
+  </Tab>
+  <Tab title="pnpm">
+    ```bash
+    pnpm add -g milaidy@latest
+    ```
+  </Tab>
+</Tabs>
+
+## Onboard and run the Gateway
+
+<Steps>
+  <Step title="Onboard and install the service">
+    ```bash
+    milaidy onboard --install-daemon
+    ```
+  </Step>
+  <Step title="Pair WhatsApp">
+    ```bash
+    milaidy channels login
+    ```
+  </Step>
+  <Step title="Start the Gateway">
+    ```bash
+    milaidy gateway --port 18789
+    ```
+  </Step>
+</Steps>
+
+After onboarding, the Gateway runs via the user service. You can still run it manually with `milaidy gateway`.
+
+<Info>
+Switching between npm and git installs later is easy. Install the other flavor and run
+`milaidy doctor` to update the gateway service entrypoint.
+</Info>
+
+## From source (development)
+
+```bash
+git clone https://github.com/milaidy/milaidy.git
+cd milaidy
+pnpm install
+pnpm ui:build # auto-installs UI deps on first run
+pnpm build
+milaidy onboard --install-daemon
+```
+
+If you do not have a global install yet, run onboarding via `pnpm milaidy ...` from the repo.
+
+## Multi instance quickstart (optional)
+
+```bash
+MILAIDY_CONFIG_PATH=~/.milaidy/a.json \
+MILAIDY_STATE_DIR=~/.milaidy-a \
+milaidy gateway --port 19001
+```
+
+## Send a test message
+
+Requires a running Gateway.
+
+```bash
+milaidy message send --target +15555550123 --message "Hello from Milaidy"
+```

package/docs/start/setup.md

@@ -0,0 +1,149 @@
+---
+summary: "Setup guide: keep your Milaidy setup tailored while staying up-to-date"
+read_when:
+  - Setting up a new machine
+  - You want “latest + greatest” without breaking your personal setup
+title: "Setup"
+---
+
+# Setup
+
+Last updated: 2026-01-01
+
+## TL;DR
+
+- **Tailoring lives outside the repo:** `~/.milaidy/workspace` (workspace) + `~/.milaidy/milaidy.json` (config).
+- **Stable workflow:** install the macOS app; let it run the bundled Gateway.
+- **Bleeding edge workflow:** run the Gateway yourself via `pnpm gateway:watch`, then let the macOS app attach in Local mode.
+
+## Prereqs (from source)
+
+- Node `>=22`
+- `pnpm`
+- Docker (optional; only for containerized setup/e2e — see [Docker](/install/docker))
+
+## Tailoring strategy (so updates don’t hurt)
+
+If you want “100% tailored to me” _and_ easy updates, keep your customization in:
+
+- **Config:** `~/.milaidy/milaidy.json` (JSON/JSON5-ish)
+- **Workspace:** `~/.milaidy/workspace` (skills, prompts, memories; make it a private git repo)
+
+Bootstrap once:
+
+```bash
+milaidy setup
+```
+
+From inside this repo, use the local CLI entry:
+
+```bash
+milaidy setup
+```
+
+If you don’t have a global install yet, run it via `pnpm milaidy setup`.
+
+## Stable workflow (macOS app first)
+
+1. Install + launch **Milaidy.app** (menu bar).
+2. Complete the onboarding/permissions checklist (TCC prompts).
+3. Ensure Gateway is **Local** and running (the app manages it).
+4. Link surfaces (example: WhatsApp):
+
+```bash
+milaidy channels login
+```
+
+5. Sanity check:
+
+```bash
+milaidy health
+```
+
+If onboarding is not available in your build:
+
+- Run `milaidy setup`, then `milaidy channels login`, then start the Gateway manually (`milaidy gateway`).
+
+## Bleeding edge workflow (Gateway in a terminal)
+
+Goal: work on the TypeScript Gateway, get hot reload, keep the macOS app UI attached.
+
+### 0) (Optional) Run the macOS app from source too
+
+If you also want the macOS app on the bleeding edge:
+
+```bash
+./apps/shared/scripts/restart-mac.sh
+```
+
+### 1) Start the dev Gateway
+
+```bash
+pnpm install
+pnpm gateway:watch
+```
+
+`gateway:watch` runs the gateway in watch mode and reloads on TypeScript changes.
+
+### 2) Point the macOS app at your running Gateway
+
+In **Milaidy.app**:
+
+- Connection Mode: **Local**
+  The app will attach to the running gateway on the configured port.
+
+### 3) Verify
+
+- In-app Gateway status should read **“Using existing gateway …”**
+- Or via CLI:
+
+```bash
+milaidy health
+```
+
+### Common footguns
+
+- **Wrong port:** Gateway WS defaults to `ws://127.0.0.1:18789`; keep app + CLI on the same port.
+- **Where state lives:**
+  - Credentials: `~/.milaidy/credentials/`
+  - Sessions: `~/.milaidy/agents/<agentId>/sessions/`
+  - Logs: `/tmp/milaidy/`
+
+## Credential storage map
+
+Use this when debugging auth or deciding what to back up:
+
+- **WhatsApp**: `~/.milaidy/credentials/whatsapp/<accountId>/creds.json`
+- **Telegram bot token**: config/env or `channels.telegram.tokenFile`
+- **Discord bot token**: config/env (token file not yet supported)
+- **Slack tokens**: config/env (`channels.slack.*`)
+- **Pairing allowlists**: `~/.milaidy/credentials/<channel>-allowFrom.json`
+- **Model auth profiles**: `~/.milaidy/agents/<agentId>/agent/auth-profiles.json`
+- **Legacy OAuth import**: `~/.milaidy/credentials/oauth.json`
+  More detail: [Security](/gateway/security#credential-storage-map).
+
+## Updating (without wrecking your setup)
+
+- Keep `~/.milaidy/workspace` and `~/.milaidy/` as “your stuff”; don’t put personal prompts/config into the `milaidy` repo.
+- Updating source: `git pull` + `pnpm install` (when lockfile changed) + keep using `pnpm gateway:watch`.
+
+## Linux (systemd user service)
+
+Linux installs use a systemd **user** service. By default, systemd stops user
+services on logout/idle, which kills the Gateway. Onboarding attempts to enable
+lingering for you (may prompt for sudo). If it’s still off, run:
+
+```bash
+sudo loginctl enable-linger $USER
+```
+
+For always-on or multi-user servers, consider a **system** service instead of a
+user service (no lingering needed). See [Gateway runbook](/gateway) for the systemd notes.
+
+## Related docs
+
+- [Gateway runbook](/gateway) (flags, supervision, ports)
+- [Gateway configuration](/gateway/configuration) (config schema + examples)
+- [Discord](/channels/discord) and [Telegram](/channels/telegram) (reply tags + replyToMode settings)
+- [Milaidy assistant setup](/start/milaidy)
+- [macOS app](/platforms/macos) (gateway lifecycle)