docs: examples and integrations — boot units, health check, automation recipes

README.md

@@ -134,8 +134,11 @@ More answers: **[docs/FAQ.md](docs/FAQ.md)**
 | [docs/GETTING-STARTED.md](docs/GETTING-STARTED.md) | Install, login, first steps, troubleshooting |
 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Daemon internals, control channel, metrics pipeline |
 | [docs/TOOLS.md](docs/TOOLS.md) | Tool-by-tool reference with examples |
+| [docs/EXAMPLES.md](docs/EXAMPLES.md) | Automation recipes — cron, watchdogs, backups |
+| [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md) | Cloud API, scheduling, boot persistence |
 | [docs/FAQ.md](docs/FAQ.md) | Frequently asked questions |
 | [docs/CHANGELOG.md](docs/CHANGELOG.md) | Release history |
+| [examples/](examples) | launchd & systemd units, health check script |
 | [SECURITY.md](SECURITY.md) | Security model & vulnerability reporting |
 | [CONTRIBUTING.md](CONTRIBUTING.md) | Development setup, tests, conventions |
 

docs/EXAMPLES.md

@@ -0,0 +1,78 @@
+# Examples & Recipes
+
+Real things people do with mona-agent. Copy, adapt, enjoy.
+
+## Check on your machine from your phone
+
+1. `mona-agent start` on the machine (or install the launchd/systemd unit
+   from [examples/](../examples)).
+2. Open <https://agent.mona.expert/dashboard> on your phone.
+3. Chat: *"How's the disk looking?"* — the agent reads `df -h`, and the
+   dashboard shows live CPU/memory sparklines.
+
+## Morning briefing with cron
+
+Get a daily summary of your home server in your dashboard before coffee:
+
+```cron
+# ~/.config/cron.d/mona (or: crontab -e)
+30 7 * * *  $HOME/.local/bin/mona-agent chat "Summarize disk usage, uptime and any failed systemd units."
+```
+
+The reply lands in the dashboard chat history, timestamped.
+
+## Watchdog — alert when a service dies
+
+Ask the agent every 10 minutes; it pings the service and only reports
+problems (the cloud keeps the conversation context):
+
+```cron
+*/10 * * * *  $HOME/.local/bin/mona-agent chat "Check nginx is answering on :80. Only reply if something is wrong."
+```
+
+## Nightly log cleanup
+
+```cron
+10 3 * * *  $HOME/.local/bin/mona-agent exec "find ~/logs -name '*.log' -mtime +14 -delete && echo cleaned"
+```
+
+## Health check from any shell
+
+```bash
+mona-agent connect          # force a connection test: health, auth, agents
+```
+
+`connect` reports cloud reachability, key validity and the agent list —
+ideal for install verification and support tickets.
+
+## Drive a script from the dashboard
+
+Anything you can put in a script, the agent can run it for you:
+
+```bash
+#!/usr/bin/env bash
+# backup.sh — daily offsite backup, called from the dashboard chat
+tar czf - ~/projects | gpg -c --batch --passphrase-file ~/.backup-pass -o /mnt/backup/projects.tgz.gpg
+```
+
+Say *"run backup.sh"* in the chat; the guarded shell executes it and
+streams the result back to your browser.
+
+## Headless Raspberry Pi companion
+
+The agent runs on any Node.js 20+ box:
+
+```bash
+curl -fsSL https://agent.mona.expert/install.sh | bash
+mona-agent login
+mona-agent start          # survives reboots via the systemd unit in examples/
+```
+
+Then manage the Pi from the dashboard: temperature, storage, running
+services — with live metrics and chat.
+
+## More
+
+- [INTEGRATIONS.md](INTEGRATIONS.md) — the cloud REST API and scheduling
+- [TOOLS.md](TOOLS.md) — the built-in tool sandbox
+- [examples/](../examples) — launchd & systemd units, health check script

docs/INTEGRATIONS.md

@@ -0,0 +1,67 @@
+# Integrations
+
+mona-agent is designed to be glued into whatever you already run.
+
+## Cloud REST API (client view)
+
+The daemon talks to the control plane at `https://agent.mona.expert` over
+HTTPS with Bearer auth. From a client perspective the endpoints are:
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/api/v1/agent/health` | Cloud health / uptime check |
+| GET | `/api/v1/agent/verify` | Validate the device token |
+| POST | `/api/v1/agent/chat/:agentId` | Send a chat message, get a reply |
+| POST | `/api/v1/agent/tool/:agentId` | Execute a tool directly |
+| GET | `/api/v1/agent/agents` | List your agents |
+| POST | `/api/v1/agent/think` | Streaming reasoning (SSE) |
+| POST | `/api/v1/agent/stats` | Device metrics snapshot (every 10 s) |
+
+The client picks the right base URL and paths automatically
+(`MONA_CLOUD` overrides the default).
+
+## Boot persistence
+
+Keep the daemon alive across reboots:
+
+- **macOS** — install [examples/macos/com.monaexpert.agent.plist](../examples/macos/com.monaexpert.agent.plist)
+  into `~/Library/LaunchAgents/` and `launchctl load` it.
+- **Linux (systemd)** — drop [examples/linux/mona-agent.service](../examples/linux/mona-agent.service)
+  into `~/.config/systemd/user/` and `systemctl --user enable --now mona-agent`.
+- **cron fallback** — `@reboot $HOME/.local/bin/mona-agent start`
+
+## Scheduling
+
+The agent plays nicely with cron (see [EXAMPLES.md](EXAMPLES.md) for
+recipes). One-liners:
+
+```bash
+mona-agent chat "…"   # ask the cloud brain, answer in dashboard history
+mona-agent exec "…"   # run a guarded command, stream the output
+```
+
+## Health checks
+
+- **Interactive** — `mona-agent connect` runs the full connectivity test
+  (health, auth, agent list) and prints the result.
+- **Scripted** — parse `mona-agent connect` exit code in your monitoring:
+
+```bash
+if mona-agent connect; then echo "agent ok"; else echo "agent degraded"; fi
+```
+
+## Webhooks & outbound calls
+
+The `net` tool lets the agent call your webhooks, health endpoints or
+notification services (outbound HTTPS only):
+
+```bash
+mona-agent exec "curl -fsS https://hc-ping.com/<your-uuid>"
+```
+
+## Building on the client
+
+- `packages/engine` — the cloud-brain client (self-contained)
+- `packages/protocol` — typed message schemas shared with the cloud
+
+Both are MIT licensed; reuse them freely.

docs/index.md

@@ -5,10 +5,13 @@ Open-source cloud-brained AI agent for your device — macOS, Linux, WSL2.
 - [Getting started](GETTING-STARTED.md) — install in 60 seconds
 - [Architecture](ARCHITECTURE.md) — how the daemon works
 - [Tools reference](TOOLS.md) — files, shell, net, sysinfo
+- [Examples & recipes](EXAMPLES.md) — cron jobs, watchdogs, backups
+- [Integrations](INTEGRATIONS.md) — cloud API, scheduling, boot persistence
 - [FAQ](FAQ.md) — common questions
 - [Changelog](CHANGELOG.md) — release history
 - [Security](../SECURITY.md) — security model & disclosure
 - [Contributing](../CONTRIBUTING.md) — development setup
+- [examples/](../examples) — launchd & systemd units, health check script
 
 **Cloud:** [agent.mona.expert](https://agent.mona.expert) ·
 **Repo:** [MONAEXPERT/agent](https://github.com/MONAEXPERT/agent)

examples/README.md

@@ -0,0 +1,11 @@
+# Examples
+
+Copy-paste helpers for running mona-agent in production.
+
+| Directory | Contents |
+|---|---|
+| [macos/](macos) | LaunchAgent plist — auto-start on login, keep-alive |
+| [linux/](linux) | systemd user unit — boot persistence with auto-restart |
+| [scripts/](scripts) | `healthcheck.sh` — end-to-end install verification |
+
+More recipes: [../docs/EXAMPLES.md](../docs/EXAMPLES.md)

examples/linux/README.md

@@ -0,0 +1,28 @@
+# Run mona-agent as a systemd user service on Linux
+
+## Install
+
+```bash
+mkdir -p ~/.config/systemd/user
+cp mona-agent.service ~/.config/systemd/user/
+systemctl --user daemon-reload
+systemctl --user enable --now mona-agent
+```
+
+## Useful commands
+
+```bash
+systemctl --user status mona-agent   # running? recent log lines
+journalctl --user -u mona-agent -f   # follow the log
+systemctl --user restart mona-agent  # restart after updates
+```
+
+## Uninstall
+
+```bash
+systemctl --user disable --now mona-agent
+rm ~/.config/systemd/user/mona-agent.service
+```
+
+Requires `mona-agent` on your PATH (`~/.local/bin`, set by the installer)
+and a systemd user session (standard on desktop distros).

examples/linux/mona-agent.service

@@ -0,0 +1,13 @@
+[Unit]
+Description=mona-agent — cloud-brained AI agent for this device
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=%h/.local/bin/mona-agent start
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=default.target

examples/macos/README.md

@@ -0,0 +1,28 @@
+# Run mona-agent automatically on macOS
+
+Install this LaunchAgent to start mona-agent when you log in and keep it
+running (auto-restart on crash).
+
+## Install
+
+```bash
+mkdir -p ~/Library/LaunchAgents
+cp com.monaexpert.agent.plist ~/Library/LaunchAgents/
+launchctl load ~/Library/LaunchAgents/com.monaexpert.agent.plist
+```
+
+## Verify
+
+```bash
+launchctl list | grep monaexpert
+mona-agent connect    # should report cloud reachable, key valid
+```
+
+## Uninstall
+
+```bash
+launchctl unload ~/Library/LaunchAgents/com.monaexpert.agent.plist
+rm ~/Library/LaunchAgents/com.monaexpert.agent.plist
+```
+
+Requires `mona-agent` on your PATH (`~/.local/bin`, set by the installer).

examples/macos/com.monaexpert.agent.plist

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!-- mona-agent LaunchAgent — keeps the device agent running on login -->
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.monaexpert.agent</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>/bin/zsh</string>
+        <string>-c</string>
+        <string>exec $HOME/.local/bin/mona-agent start</string>
+    </array>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>KeepAlive</key>
+    <true/>
+
+    <!-- Logs: ~/Library/Logs/mona-agent.log -->
+    <key>StandardOutPath</key>
+    <string>/tmp/mona-agent.log</string>
+    <key>StandardErrorPath</key>
+    <string>/tmp/mona-agent.log</string>
+</dict>
+</plist>

examples/scripts/healthcheck.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# healthcheck.sh — verify a mona-agent installation end to end.
+# Usage: bash healthcheck.sh   (exit 0 = ok, 1 = problem found)
+set -u
+
+RED='\033[31m'; GREEN='\033[32m'; RESET='\033[0m'
+fail=0
+
+say()  { printf '%s\n' "$*"; }
+ok()   { printf "  ${GREEN}ok${RESET}  %s\n" "$*"; }
+bad()  { printf "  ${RED}bad${RESET} %s\n" "$*"; fail=1; }
+
+say "mona-agent health check"
+
+# 1. Binary on PATH
+if command -v mona-agent >/dev/null 2>&1; then
+  ok "mona-agent on PATH ($(command -v mona-agent))"
+else
+  bad "mona-agent not on PATH — run the installer: curl -fsSL https://agent.mona.expert/install.sh | bash"
+  exit 1
+fi
+
+# 2. Node.js version
+if node -v 2>/dev/null | grep -qE '^v(2[0-9]|[3-9][0-9])\.'; then
+  ok "Node.js $(node -v)"
+else
+  bad "Node.js 20+ required (found: $(node -v 2>/dev/null || echo none))"
+fi
+
+# 3. Credentials present
+if [ -f "$HOME/.mona-agent/credentials.json" ]; then
+  ok "credentials.json present"
+else
+  bad "not logged in — run: mona-agent login"
+fi
+
+# 4. Process running
+if pgrep -f "mona-agent.*(start|gui)" >/dev/null 2>&1; then
+  ok "daemon process running (pid $(pgrep -f "mona-agent.*(start|gui)" | head -1))"
+else
+  bad "daemon not running — start with: mona-agent start"
+fi
+
+# 5. Cloud connectivity + key validity
+if mona-agent connect >/tmp/mona-health.$$.log 2>&1; then
+  ok "cloud connection ok (health, auth, agents)"
+else
+  bad "cloud connection failed:"
+  sed 's/^/      /' /tmp/mona-health.$$.log | tail -8
+fi
+rm -f /tmp/mona-health.$$.log
+
+say ""
+if [ "$fail" -eq 0 ]; then
+  say "${GREEN}All checks passed.${RESET}"
+else
+  say "${RED}Some checks failed — see above.${RESET}"
+fi
+exit "$fail"