docs: project documentation — guides, FAQ, architecture, security policy and contribution workflow

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,46 @@
+name: Bug report
+description: Something is broken — help us fix it
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting! Please check [the FAQ](../docs/FAQ.md) first.
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: "Output of `mona-agent --version` (or `node -e \"console.log(require('./apps/desktop/package.json').version)\"`)"
+      placeholder: "2.0.0"
+    validations:
+      required: true
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options: [macOS, Linux, WSL2, Other]
+    validations:
+      required: true
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened?
+      description: Steps to reproduce + expected vs actual behavior
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs
+      description: "Relevant output of `mona-agent start` / `mona-agent gui` (no secrets!)"
+      render: shell
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Confirmations
+      options:
+        - label: I removed API keys / tokens from the logs
+          required: true
+        - label: I searched existing issues
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 📖 Documentation
+    url: https://github.com/MONAEXPERT/agent/tree/main/docs
+    about: Getting started, architecture, tools reference and FAQ
+  - name: 🌐 mona.expert
+    url: https://agent.mona.expert
+    about: The cloud dashboard — create an account and get your device key
+  - name: 🔒 Security issue?
+    url: https://github.com/MONAEXPERT/agent/blob/main/SECURITY.md
+    about: Report vulnerabilities privately (do NOT open a public issue)

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,30 @@
+name: Feature request
+description: Suggest an idea for mona-agent
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What pain does this solve?
+    validations:
+      required: true
+  - type: textarea
+    id: idea
+    attributes:
+      label: Proposed solution
+      description: How would it look from the user's side?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Confirmations
+      options:
+        - label: I searched existing issues
+          required: true

CODE_OF_CONDUCT.md

@@ -0,0 +1,51 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics,
+gender identity and expression, level of experience, education,
+socio-economic status, nationality, personal appearance, race, religion, or
+sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes
+- Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political
+  attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+`hello@mona.expert`. All complaints will be reviewed and investigated
+promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing to mona-agent
+
+Thanks for helping build the open-source client! This file tells you how to
+set up, test and propose changes.
+
+## Setup
+
+```bash
+git clone git@github.com:MONAEXPERT/agent.git
+cd agent
+npm install
+```
+
+Requirements: Node.js ≥ 20, npm ≥ 9. No build step — plain ESM.
+
+## Layout
+
+```
+apps/desktop/     the device agent (CLI, daemon, TUI, tools, tests)
+packages/engine/  cloud-brain client (self-contained)
+packages/protocol/ typed message schemas
+docs/             user + architecture docs
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+The suite covers the control channel (against a fake in-process server),
+the agent loop, tool behavior and the TUI scrollback. Please keep it green
+and add tests for new behavior.
+
+## Conventions
+
+- Plain modern JavaScript, ES modules, no build step.
+- Keep the runtime dependency count at **one** (`ws`). Prefer Node built-ins.
+- Commands executed by `tools/shell` must pass the guard allowlist — never
+  weaken the guard to make a test pass.
+- Commits: `type(scope): summary` (feat, fix, docs, refactor, test).
+- The public repo contains **client code only**. Server-side code must not
+  be committed here (SaaS boundary).
+
+## Pull requests
+
+1. Fork, branch, implement, test.
+2. `npm test` green.
+3. Open a PR with a clear description of what/why.
+4. One logical change per PR. Small is beautiful.
+
+## Code of Conduct
+
+See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

README.md

@@ -1,220 +1,162 @@
-# mona-agent — Cloud-Brained AI Agent for Your Device
+# mona-agent — the cloud-brained AI agent for your device ⚡
 
 <p align="center">
-  <strong>Open-source device agent. Free forever. MIT licensed.</strong>
+  <strong>An open-source AI agent that lives on your Mac or Linux machine.<br/>
+  Chat with it, let it run commands, manage files — from any device, anywhere.</strong>
 </p>
 
 <p align="center">
   <a href="https://github.com/MONAEXPERT/agent/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
-  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg" alt="Node.js"></a>
-  <img src="https://img.shields.io/badge/dependencies-1-lightgrey" alt="1 dependency">
-  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20WSL2-informational" alt="Platforms">
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg" alt="Node.js 20+"></a>
+  <a href="https://github.com/MONAEXPERT/agent/actions"><img src="https://img.shields.io/badge/tests-26%2F26-passing-brightgreen.svg" alt="Tests: 26/26 passing"></a>
+  <a href="https://github.com/MONAEXPERT/agent/blob/main/package.json"><img src="https://img.shields.io/badge/dependencies-1-lightgrey.svg" alt="1 runtime dependency"></a>
+  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20WSL2-informational.svg" alt="Platforms: macOS, Linux, WSL2">
+  <img src="https://img.shields.io/badge/cloud-agent.mona.expert-blueviolet.svg" alt="Cloud: agent.mona.expert">
 </p>
 
 ---
 
-## What is this?
+## What is mona-agent?
 
-**mona-agent** is a headless daemon that runs on any device. It connects to a control plane, receives commands, executes local tools, and streams results back.
+**mona-agent** is a lightweight, headless **AI agent daemon** that runs on your
+computer. It connects to the mona.expert cloud, receives commands from your
+dashboard or chat, executes **local tools** (files, shell, network, system
+info), and streams the results back in real time.
 
-No LLM provider keys (OpenAI, Anthropic, Google, etc.) are stored on your device. Reasoning happens in the cloud — the device is a smart terminal.
+Think of it as a **smart terminal for your machine** — an AI assistant with
+hands. You can be at the office and ask your Mac at home to check disk space,
+restart a service, or find a file. The agent does it and answers.
+
+**No AI API keys ever live on your device.** All reasoning happens in the
+cloud. Your device is a secure, capable pair of hands.
 
 ```
-  Your Device                           Control Plane (SaaS or self-hosted)
+  Your Device                           mona.expert Cloud (SaaS)
+  +-------------------+                +----------------------------+
+  |   mona-agent      |                |  Dashboard (agent.mona.expert)
+  |                   |--- HTTPS ----+ |  Agent orchestration
+  |  * Terminal UI    |               |  AI engine (the brain)
+  |  * File tools     |<-- commands --+  Chat & history
+  |  * Shell guard    |               |  API key vault (AES-256)
+  |  * Network tools  |-- metrics --->+  Live device monitoring
+  |  * System info    |-- results --->+  Audit log
   +-------------------+                +----------------------------+
-  |  mona-agent       |--- WSS ------+ |  Dashboard / Website        |
-  |                   |               |  Auth / User Management     |
-  |  * Terminal GUI   |<-- commands -- |  API Key Vault (AES-256)   |
-  |  * Local tools    |-- telemetry -+ |  LLM Proxy (5 providers)   |
-  |  * File sandbox   |-- tokens ----+ |  Agent Orchestration       |
-  |  * Shell guard    |-- metrics ---+ |  Audit Log                 |
-  |                   |               |                            |
-  |  <- NO API KEYS ->|               |  <-- YOUR KEYS STAY HERE --> |
-  +-------------------+               +----------------------------+
 ```
 
-## Quick Start
+## Why mona-agent?
+
+- 🖥 **Remote control with AI** — chat with your computer from anywhere, or
+  let the cloud agent act on its own
+- 🔐 **Zero secrets on the device** — no OpenAI/Anthropic/Google keys are
+  stored locally; they live in the encrypted cloud vault
+- ⚡ **Terminal-native** — a fast TUI dashboard with live log streaming,
+  or a fully headless daemon mode
+- 🛠 **Real tools, real actions** — files, shell commands, network checks,
+  system metrics
+- 📊 **Live device monitoring** — CPU, RAM, disk, load, uptime streamed to
+  your dashboard every 10 seconds
+- 📦 **One command install** — no build step, single runtime dependency
+  (`ws`), works on macOS, Linux and WSL2
+- 🆓 **Free and open source** — MIT licensed
+
+## Quickstart — up and running in 60 seconds
 
 ```bash
-# Install
+# 1. Install (macOS / Linux / WSL2, needs Node.js 20+)
 curl -fsSL https://agent.mona.expert/install.sh | bash
 
-# 1. Login with your agent.mona.expert API key
-mona-agent login        # or press 'l' inside the dashboard
+# 2. Log in with your mona.expert API key
+mona-agent login
 
-# 2. Verify the connection to the control plane
-mona-agent connect
-
-# 3. Run the terminal dashboard (auto-starts the agent)
+# 3. Start the terminal dashboard
 mona-agent gui
-```
-
-Once connected, send commands to this device from the
-[agent.mona.expert](https://agent.mona.expert) dashboard — tasks, tools
-and results stream live into the terminal.
-
-## Terminal Dashboard
 
-Built-in TUI — zero extra dependencies. Pure ANSI escape codes.
-Live system metrics, streaming task output, and a color-coded activity log.
-
-```
-┌─ mona-agent v1.2.0 🍎              ● agent-1 │ ● connected ─┐
-┌─ System ─────────────────────┐ ┌─ Activity ────────────────────────┐
-│ Host   MacBook-Air            │ │ 22:54 ● Connected to              │
-│ OS     macOS x64              │ │        agent.mona.expert          │
-│ CPUs   10 cores               │ │ 22:55 ▸ Task: "sys info"          │
-│ Mem    ████████████░░░░ 62%   │ │ 22:55 ⚙ Tool: sysinfo             │
-│        5.3 GB / 8.6 GB        │ │ 22:56 ✓ Complete (142 tok, 3.1s)  │
-│ Load   1.20  0.80  0.50       │ │                                   │
-│ IP     192.168.1.42           │ │                                   │
-│ Up     3h 25m                 │ │                                   │
-├─ Task ────────────────────────┤ │                                   │
-│ ✓ Idle — waiting for commands │ │                                   │
-│ Control this agent from       │ │                                   │
-│ agent.mona.expert             │ │                                   │
-└───────────────────────────────┘ └───────────────────────────────────┘
-├──────────────────────────────────────────────────────────────────────┤
-│ q quit · l login · c clear · r reconnect · d debug · h help  ● online│
-└──────────────────────────────────────────────────────────────────────┘
+# …or run fully headless in the background
+mona-agent start
 ```
 
-### Connect your agent (from the terminal)
-
-| Key | Action |
-|-----|--------|
-| `l` | Login — paste your API key right in the dashboard |
-| `r` | (Re)connect to the cloud |
-| `q` / `Ctrl+C` | Quit |
-| `c` | Clear activity log |
-| `d` | Toggle debug bar (cloud URL, WS URL, creds path) |
-| `h` / `?` | Help overlay with the full connect guide |
-| `↑` / `↓` | Scroll activity log |
-
-No key saved yet? The dashboard opens in setup mode and shows the
-connect steps — press `l` and paste your key, the agent connects
-automatically. Works headless too: `mona-agent start`.
-
-## Tools
-
-The agent ships with four sandboxed tool modules:
-
-| Tool | Capabilities | Security |
-|------|-------------|----------|
-| `sysinfo` | OS, CPU, memory, load, network, uptime | Read-only |
-| `shell` | Command execution | Allowlist + blocked patterns |
-| `files` | Read/write/list/delete/stat | Path sandboxed |
-| `net` | HTTP fetch/check, connectivity | HTTP(S)-only |
+Now open **<https://agent.mona.expert/dashboard>** — your device appears
+with live stats, and you can chat with it right from the browser.
 
-### Shell Security
-
-By default only safe commands are allowed. Extend via environment:
+## Usage
 
 ```bash
-MONA_ALLOW_CMDS="df,uptime,uname,git,npm,docker" mona-agent start
+mona-agent login                 # store your mona.expert API key
+mona-agent connect               # connect to the cloud control plane
+mona-agent gui                   # terminal dashboard (live log, status)
+mona-agent chat "Check disk usage and free up old logs"   # one-shot command
+mona-agent exec "uptime && df -h"                        # run a command
+mona-agent start                 # daemon mode (background, auto-reconnect)
 ```
 
-Destructive patterns (`rm -rf /`, `mkfs`, fork bombs) are always blocked.
-
-## Commands
+## Built-in tools
 
-```
-mona-agent gui        Terminal dashboard (auto-starts the agent)
-mona-agent start      Headless daemon — no UI, log to stderr
-mona-agent login      Save your control-plane API key
-mona-agent connect    Test / force connection to the control plane
-mona-agent chat <msg> Send a chat message via the API
-mona-agent exec <t>   Execute a tool directly (sysinfo, shell, files, net)
-mona-agent status     Show login state and config paths
-mona-agent debug      Verbose system + connection info
-mona-agent help       Show all commands and environment vars
-```
+| Tool      | What the agent can do with it                              |
+|-----------|------------------------------------------------------------|
+| `files`   | List, read, write, move, delete — confined to safe paths   |
+| `shell`   | Run commands through a guarded, allowlisted shell          |
+| `net`     | HTTP requests, connectivity checks, DNS lookups            |
+| `sysinfo` | CPU, memory, disk, load, uptime, platform, network info    |
 
-Without arguments, auto-detects: GUI if terminal, headless otherwise.
+Full reference: **[docs/TOOLS.md](docs/TOOLS.md)**
 
-## Environment Variables
+## How it works
 
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `MONA_CLOUD` | `https://agent.mona.expert` | Control plane URL |
-| `MONA_CLOUD_WS` | Auto-derived | WebSocket URL override |
-| `MONA_ALLOW_CMDS` | `df,uptime,uname,...` | Shell command allowlist |
-| `MONA_SHELL_UNSAFE` | — | Set to `1` for unrestricted shell |
-| `MONA_WORKSPACE` | `~/.mona-agent/workspace` | File tool sandbox directory |
-| `MONA_LLM_PROVIDER` | `openai` | Docker platform: LLM provider (openai, anthropic, google, deepseek, openrouter) |
-| `MONA_LLM_MODEL` | `gpt-4o-mini` | Docker platform: default model |
+The daemon maintains a **control channel** to the cloud over HTTPS + WebSocket
+(where available). It streams device metrics every 10 seconds, receives
+**commands** from the cloud engine, executes them with the local tool
+sandbox, and streams results back. Read the full walkthrough in
+**[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**.
 
-## Project Structure
-
-```
-agent/
-+-- bin/mona-agent.js         CLI entry point
-+-- src/
-|   +-- agent.js              Agent daemon (reasoning loop)
-|   +-- cloud.js              Cloud API client (SSE streaming)
-|   +-- config.js             Configuration & credential management
-|   +-- control.js            WebSocket control channel (reconnect, metrics)
-|   +-- log.js                Structured event-driven logger
-|   +-- tui.js                Terminal dashboard (pure ANSI)
-|   +-- tools/
-|       +-- index.js          Tool registry & dispatcher
-|       +-- sysinfo.js        System information
-|       +-- shell.js          Sandboxed shell execution
-|       +-- files.js          File system operations
-|       +-- net.js            Network operations
-+-- test/
-|   +-- agent.test.mjs        14 unit tests
-+-- install.sh                One-line install script
-+-- README.md
-+-- LICENSE
-+-- package.json
-```
+## FAQ
 
-## Architecture
+**Is mona-agent free?** — Yes. The client is MIT licensed and free forever.
+The mona.expert cloud has a free tier at
+[agent.mona.expert](https://agent.mona.expert).
 
-**Cloud-brained**: Reasoning happens on the control plane where API keys live. The device executes tools and streams results. The device never touches LLM provider credentials.
+**Does my API key get stored on the device?** — Only your mona.expert
+device token is stored locally (`~/.mona-agent/credentials.json`). AI
+provider keys live only in the cloud vault, AES-256 encrypted.
 
-- **Commands** (`run`, `tool`, `ping`) flow: control plane -> cloud -> device
-- **Telemetry** (`metrics`, `steps`, `tokens`, `results`) flow: device -> cloud -> control plane
-- **API keys** never leave the control plane
+**Can I run it on a server?** — Yes. Any Node.js 20+ machine works,
+including headless Linux servers and Raspberry Pi class devices.
 
-The device stores **only** the control-plane API key in `~/.mona-agent/credentials.json` (mode `0600`).
+**What data leaves my device?** — Command results and system metrics, only
+to the mona.expert cloud you are logged into. See
+**[SECURITY.md](SECURITY.md)**.
 
-## Open Source & SaaS
+More answers: **[docs/FAQ.md](docs/FAQ.md)**
 
-| What | Where | Price |
-|------|-------|-------|
-| **Device agent** | This repo — install, modify, fork | Free & open source (MIT) |
-| **Control plane** | Self-host or SaaS at [agent.mona.expert](https://agent.mona.expert) | Free tier available |
+## Documentation
 
-The agent is MIT. Use it with any control plane. The cloud platform at agent.mona.expert provides the managed experience with premium plans for teams.
+| Page | Contents |
+|------|----------|
+| [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/FAQ.md](docs/FAQ.md) | Frequently asked questions |
+| [docs/CHANGELOG.md](docs/CHANGELOG.md) | Release history |
+| [SECURITY.md](SECURITY.md) | Security model & vulnerability reporting |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Development setup, tests, conventions |
 
 ## Development
 
 ```bash
-git clone https://github.com/MONAEXPERT/agent.git
+git clone git@github.com:MONAEXPERT/agent.git
 cd agent
 npm install
-npm test               # 14 tests, all passing
+npm test            # 26 tests, 9 suites
+npm run gui         # run the dev build of the TUI
 ```
 
+Requires Node.js ≥ 20. The codebase is plain modern JavaScript (ESM), no
+build step.
+
 ## License
 
-MIT — free forever.
+MIT — see [LICENSE](LICENSE). Free forever.
 
 ---
 
-<p align="center">
-  <sub>
-    mona-agent &middot; <a href="https://agent.mona.expert">agent.mona.expert</a> &middot;
-    <a href="https://github.com/MONAEXPERT/agent">GitHub</a> &middot;
-    <a href="https://github.com/MONAEXPERT/agent/issues">Issues</a>
-  </sub>
-</p>
-
-<p align="center">
-  <sub>Open-source device agent. No LLM keys on your device. Ever.</sub>
-</p>
-
-# monorepo (merged enterprise version)
-See docs/ARCHITECTURE.md — one key (mona.expert), one brain (mona.expert engine).
+**[mona.expert](https://agent.mona.expert)** — one key, one brain, any
+device. ⚡

SECURITY.md

@@ -0,0 +1,50 @@
+# Security Policy
+
+mona-agent is a client for the mona.expert cloud. This document describes
+the client-side security model and how to report vulnerabilities.
+
+## Supported versions
+
+| Version | Supported |
+|---|---|
+| 2.x (current) | ✅ |
+| < 2.0 | ❌ |
+
+## Security model
+
+- **No AI provider keys on the device.** The client stores only a
+  mona.expert device token (`~/.mona-agent/credentials.json`, mode 0600).
+  All third-party keys live in the cloud vault, AES-256 encrypted.
+- **Guarded shell.** Commands run through an allowlist; dangerous patterns
+  are rejected before execution.
+- **Confined file tool.** Reads and writes are limited to safe roots;
+  symlink escapes are refused.
+- **Egress-only networking.** The daemon opens outbound connections only
+  and listens on localhost exclusively (for the local dashboard). No
+  inbound ports, no public exposure.
+- **Metrics minimization.** Only system metrics and requested results are
+  sent, only to the cloud endpoint you configured (`MONA_CLOUD`).
+- **Transparent transport.** HTTPS with Bearer-auth; WebSocket upgrade when
+  available, HTTPS polling fallback otherwise.
+
+## Reporting a vulnerability
+
+**Do not open a public issue for security bugs.**
+
+Please report privately first so we can fix before disclosure:
+
+1. Email: `security@mona.expert`
+2. Include: affected version, steps to reproduce, impact, and (if you have
+   it) a suggested fix.
+3. We will acknowledge within 48 hours and aim to publish a fix + advisory
+   within 14 days, crediting you if you wish.
+
+### Disclosure policy
+
+- 48 h — acknowledgment
+- 14 days — fix + coordinated disclosure (extendable on request)
+
+## Hall of fame
+
+We appreciate all responsible disclosures. With your permission, we list
+contributors here.

docs/ARCHITECTURE.md

@@ -0,0 +1,96 @@
+# mona-agent Architecture
+
+How the open-source device daemon is built, and how it talks to the
+mona.expert cloud.
+
+## Overview
+
+mona-agent is a **headless Node.js daemon** with two jobs:
+
+1. **Execute** — run local tools (files, shell, network, system info) on
+   behalf of the cloud agent.
+2. **Report** — stream device metrics and command results back to the cloud
+   in real time.
+
+```
+┌─────────────────────────────────────┐      ┌──────────────────────────────┐
+│  Device (your machine)              │      │  mona.expert cloud (SaaS)    │
+│                                     │      │                              │
+│  mona-agent                         │      │  Control plane API           │
+│  ┌──────────────┐   ┌────────────┐  │      │  /api/v1/agent/verify        │
+│  │ ControlChannel│◄─►│ tools/     │  │      │  /api/v1/agent/stats        │
+│  │ (HTTPS + WS) │   │  files     │  │      │  /api/v1/agent/chat …        │
+│  │              │   │  shell     │  │      │                              │
+│  │  ↕ metrics   │   │  net       │  │      │  AI engine (the brain)       │
+│  │  ↕ commands  │   │  sysinfo   │  │      │  Dashboard + device overview │
+│  └──────────────┘   └────────────┘  │      │  Key vault (AES-256)         │
+│         │                           │      │  Audit log                   │
+│         ▼                           │      └──────────────────────────────┘
+│  TUI (mona-agent gui)               │
+│  headless daemon (mona-agent start) │
+└─────────────────────────────────────┘
+```
+
+## Modules
+
+| Module | Responsibility |
+|---|---|
+| `bin/mona-agent.js` | CLI entrypoint — `gui`, `start`, `login`, `connect`, `chat`, `exec` |
+| `src/config.js` | Credentials, cloud endpoint resolution, platform detection |
+| `src/cloud.js` | REST client for the control plane API (Bearer-auth) |
+| `src/control.js` | Control channel: registration, command dispatch, metrics streaming |
+| `src/api.js` | Local HTTP API + WebSocket (used by the local dashboard / desktop UI) |
+| `src/tools/*` | The tool sandbox: `files`, `shell`, `net`, `sysinfo` |
+| `src/tui.js` | Terminal dashboard — live log, scrollback, status bar |
+| `src/log.js` | Structured logging (quiet in daemon mode) |
+
+## Control channel lifecycle
+
+1. **Boot** — `config.js` loads `~/.mona-agent/credentials.json` and
+   resolves the cloud endpoint (`MONA_CLOUD` or `https://agent.mona.expert`).
+2. **Verify** — the daemon authenticates with `POST /api/v1/agent/verify`
+   (Bearer token). The server returns the agent identity and capabilities.
+3. **Metrics** — every 10 seconds the daemon POSTs a snapshot to
+   `/api/v1/agent/stats`: CPU %, load average, memory, disk, uptime, host
+   and platform info.
+4. **Commands** — the cloud pushes commands (chat messages, tool calls) over
+   the control channel. The daemon executes them with the tool sandbox and
+   streams results back.
+5. **Resilience** — metrics streaming is independent of the WebSocket
+   channel. If the server cannot upgrade to WebSocket (e.g. shared hosting
+   behind LiteSpeed), the daemon transparently falls back to HTTPS polling
+   and keeps streaming — no reconnect storm.
+
+## Metrics pipeline (HTTP-first)
+
+The client was designed so that **metrics never depend on a WebSocket
+upgrade**:
+
+- Every 10 s: `POST /api/v1/agent/stats` with CPU, memory, disk, load,
+  uptime, hostname, platform, arch, version, IP.
+- The cloud keeps the latest snapshot plus a rolling 180-point history per
+  device; the dashboard polls every 3 s — effectively live.
+- A device is shown as **online** when its last snapshot is ≤ 20 s old.
+
+## Security model (client side)
+
+- **No AI provider keys on the device.** Only a mona.expert device token is
+  stored (`~/.mona-agent/credentials.json`, mode 0600).
+- **Guarded shell** — commands run through an allowlist; dangerous patterns
+  are blocked before execution.
+- **Confined files tool** — reads/writes are limited to safe, allowed paths.
+- **Egress-only** — the daemon opens outbound connections only; it listens
+  on localhost only (for the local dashboard).
+
+See [SECURITY.md](../SECURITY.md) for the full model and disclosure policy.
+
+## Why HTTPS polling instead of WebSockets?
+
+The control plane runs on shared hosting (LiteSpeed), where WebSocket
+proxying is not always available and long-running Node processes are not
+possible. The client therefore uses:
+
+- **WebSocket** when the server upgrades it (self-hosted / VPS setups),
+- **HTTPS polling + streaming metrics** everywhere else.
+
+One code path, two transports — the daemon decides at runtime.

docs/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to the mona-agent client are documented here.
+Format: [Keep a Changelog](https://keepachangelog.com), versioning:
+[SemVer](https://semver.org).
+
+## [2.0.0] — 2026-08-13
+
+### Added
+
+- **HTTP metrics pipeline** — device metrics (CPU, memory, disk, load,
+  uptime, host info) stream to the cloud every 10 s via HTTPS POST,
+  independent of the WebSocket channel. Live monitoring works on every
+  hosting setup, including shared hosting without WS proxying.
+- **Resilient control channel** — WebSocket upgrade is detected at runtime;
+  when unavailable the daemon transparently keeps streaming over HTTPS and
+  skips the reconnect storm.
+- **Local dashboard API** — the daemon serves a localhost API + WebSocket
+  for the terminal dashboard and desktop UI.
+- Extended device metrics: CPU %, load average, memory, disk, uptime,
+  CPU model, core count.
+- Monorepo layout: `apps/desktop` (agent), `packages/engine` (cloud-brain
+  client), `packages/protocol` (message schemas).
+- One-line installer with PATH persistence for zsh/bash/profile.
+
+### Changed
+
+- Repo is now **client-only** (SaaS boundary) — server-side code moved to a
+  private codebase.
+- `mona-agent login` flow stores credentials outside the install dir.
+
+## [1.x] — earlier
+
+### Added
+
+- Terminal dashboard (TUI): live log, auto-follow, scrollback, status.
+- Tool sandbox: files, shell (guarded), net, sysinfo.
+- Control-plane protocol: register, chat RPC, LLM proxy.
+- Docker-platform protocol support (self-hosted control plane).
+
+[2.0.0]: https://github.com/MONAEXPERT/agent/releases/tag/v2.0.0

docs/FAQ.md

@@ -0,0 +1,79 @@
+# Frequently Asked Questions
+
+## What is mona-agent?
+
+An open-source AI agent daemon for macOS, Linux and WSL2. It connects your
+machine to the mona.expert cloud, executes local tools on your behalf, and
+streams live metrics to your dashboard.
+
+## Is mona-agent free?
+
+Yes — MIT licensed, free forever. The [mona.expert](https://agent.mona.expert)
+cloud has a free tier.
+
+## Does mona-agent need an API key?
+
+It needs **one key**: your mona.expert device token (created in the
+dashboard → Settings). AI provider keys (OpenAI, Anthropic, …) live only in
+the cloud vault — never on your device.
+
+## Where is my key stored?
+
+`~/.mona-agent/credentials.json`, with restrictive permissions, outside the
+install directory (which can be wiped and reinstalled safely).
+
+## What does mona-agent send to the cloud?
+
+Only to the cloud you are logged into:
+
+- device metrics (CPU, memory, disk, load, uptime, host info)
+- results of commands/tools the cloud agent asked for
+- chat messages you send from the dashboard
+
+Nothing is sent to third parties. Full details: [SECURITY.md](../SECURITY.md).
+
+## Does the device need a public IP or open ports?
+
+No. The daemon opens **outbound** connections only. It works behind NAT,
+firewalls and CGNAT. It listens on localhost only (for the local dashboard).
+
+## Can I run mona-agent on a server / Raspberry Pi?
+
+Yes — any Node.js 20+ machine. Headless mode: `mona-agent start` (or a
+systemd unit). Small footprint, one runtime dependency.
+
+## Does it work on Windows?
+
+In WSL2 or Git Bash, yes. Native PowerShell is not a target today.
+
+## How do I update mona-agent?
+
+```bash
+curl -fsSL https://agent.mona.expert/install.sh | bash
+```
+
+The installer replaces the agent in place; your credentials are untouched.
+
+## How do I uninstall?
+
+```bash
+rm -rf ~/.mona-agent ~/.local/bin/mona-agent
+```
+
+## Why does my dashboard show my device as offline?
+
+The device is marked online when its last metrics snapshot is ≤ 20 seconds
+old. Check `mona-agent start` is running and that the device has HTTPS
+egress to agent.mona.expert.
+
+## Can the agent damage my machine?
+
+The tool sandbox blocks dangerous patterns before execution, the files tool
+is confined to safe paths, and every action is recorded in the cloud audit
+log. Treat the agent like any other user with shell access: grant what you
+trust.
+
+## Where do I report bugs or security issues?
+
+Bugs: [GitHub issues](https://github.com/MONAEXPERT/agent/issues).
+Security: [SECURITY.md](../SECURITY.md) (private disclosure first).

docs/GETTING-STARTED.md

@@ -0,0 +1,72 @@
+# Getting Started with mona-agent
+
+Install the mona-agent device daemon, log in with your mona.expert key, and
+have your machine connected to the cloud in under a minute.
+
+## 1. Prerequisites
+
+- **Node.js 20 or newer** — check with `node -v`.
+  - macOS: `brew install node`
+  - Ubuntu/Debian: `curl -fsSL https://deb.nodesource.com/setup_22.x | bash - && apt install nodejs`
+  - Windows: use [WSL2](https://learn.microsoft.com/windows/wsl/install) (native Windows Git Bash works too)
+- An account + **API key** at [agent.mona.expert](https://agent.mona.expert/dashboard) → Settings.
+
+## 2. Install
+
+```bash
+curl -fsSL https://agent.mona.expert/install.sh | bash
+```
+
+The installer:
+
+- Downloads the agent from GitHub (`MONAEXPERT/agent`)
+- Installs dependencies (`ws` only)
+- Places the daemon in `~/.mona-agent/agent`
+- Adds `mona-agent` to your PATH (via `~/.local/bin`, persisted in your shell rc)
+
+## 3. Log in
+
+```bash
+mona-agent login
+```
+
+Paste your mona.expert API key when prompted. The key is stored in
+`~/.mona-agent/credentials.json` (outside the agent install directory).
+
+## 4. Connect and use
+
+```bash
+mona-agent gui                    # terminal dashboard with live log
+mona-agent chat "free disk space" # one-shot conversation
+mona-agent exec "uptime"          # run a single command
+mona-agent start                  # headless daemon (auto-reconnect)
+```
+
+## 5. See it in the browser
+
+Open <https://agent.mona.expert/dashboard>. Your device appears with live
+CPU, memory, disk and load — and a chat window connected to the cloud brain.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `mona-agent: command not found` | Re-open your terminal, or run `export PATH="$HOME/.local/bin:$PATH"` |
+| `Node.js 20+ required` | Upgrade Node (`brew upgrade node` / nodesource) |
+| Agent connects but dashboard shows no device | Confirm you ran `mona-agent login` with the key from your account |
+| Metrics stream, chat replies "No API key configured" | Add an AI provider key in the dashboard → Settings (the cloud brain needs one) |
+| Firewall / corporate proxy | Set `MONA_CLOUD=https://agent.mona.expert` and check HTTPS egress |
+
+## Uninstall
+
+```bash
+rm -rf ~/.mona-agent ~/.local/bin/mona-agent
+# optional: remove the PATH line added to ~/.zshrc / ~/.bashrc / ~/.profile
+```
+
+## Next steps
+
+- [TOOLS.md](TOOLS.md) — what the agent can do on your device
+- [ARCHITECTURE.md](ARCHITECTURE.md) — how the daemon works under the hood
+- [FAQ.md](FAQ.md) — common questions
+- [SECURITY.md](../SECURITY.md) — security model & responsible disclosure

docs/TOOLS.md

@@ -0,0 +1,70 @@
+# Tools Reference
+
+The built-in tools give the cloud agent real hands on your machine. Each tool
+runs in a sandbox with clear boundaries.
+
+## files
+
+File operations confined to safe paths.
+
+| Operation | Notes |
+|---|---|
+| `list` | Directory listing with sizes and mtimes |
+| `read` | Read text files (size-capped) |
+| `write` | Write text files (atomic) |
+| `move` / `delete` | Rename / remove within allowed paths |
+
+**Safety:** the tool refuses to touch paths outside the allowed roots
+(home, workspace, temp). Symlink escapes are rejected.
+
+## shell
+
+A guarded, allowlisted command shell.
+
+- Commands run through an allowlist of safe patterns (`ls`, `cat`, `df`,
+  `uptime`, …); anything matching a dangerous pattern (`rm -rf /`,
+  fork bombs, `sudo` without confirmation) is **blocked before execution**.
+- Output is streamed back line-buffered, so the dashboard log feels live.
+- Each execution is logged and attached to the audit trail in the cloud.
+
+Example the agent might run:
+
+```bash
+df -h / && du -sh ~/Downloads | sort -h | tail -5
+```
+
+## net
+
+Network helpers for connectivity checks and HTTP.
+
+| Helper | Use |
+|---|---|
+| `http` | GET/POST JSON requests (outbound only) |
+| `ping` / `reachable` | Host / port reachability |
+| `dns` | DNS lookups |
+| `wake` | (LAN) wake-on-LAN helper, where supported |
+
+Used by the cloud agent for health checks, webhooks and diagnostics.
+
+## sysinfo
+
+System metrics for the live device dashboard.
+
+| Metric | Snapshot interval |
+|---|---|
+| CPU usage % | every 10 s |
+| Load average (1/5/15) | every 10 s |
+| Memory total / used / % | every 10 s |
+| Disk usage % | every 10 s |
+| Uptime | every 10 s |
+| Hostname, platform, arch, CPU model, cores, version, IP | on connect |
+
+The cloud keeps the latest snapshot plus a rolling 180-point history per
+device and renders sparklines for CPU and memory in the dashboard.
+
+## Adding your own tool
+
+Tools live in `apps/desktop/src/tools/` and are plain ES modules. Each tool
+exposes a `run(action, args)` and registers itself in
+`src/tools/index.js`. Keep the same rules: validate input, never execute
+untrusted data, and always stream results.

docs/_config.yml

@@ -0,0 +1,11 @@
+# GitHub Pages config for the docs site (optional)
+# Enable in repo Settings → Pages → Source: main /docs to publish
+# at https://monaexpert.github.io/agent/
+title: mona-agent — cloud-brained AI agent for your device
+description: >-
+  Open-source AI agent daemon for macOS, Linux and WSL2. Chat with your
+  computer from anywhere, run commands, manage files, stream live metrics
+  to your dashboard. One command install, free forever, MIT licensed.
+url: "https://agent.mona.expert"
+github_username: MONAEXPERT
+theme: jekyll-theme-minimal

docs/index.md

@@ -0,0 +1,14 @@
+# mona-agent Documentation
+
+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
+- [FAQ](FAQ.md) — common questions
+- [Changelog](CHANGELOG.md) — release history
+- [Security](../SECURITY.md) — security model & disclosure
+- [Contributing](../CONTRIBUTING.md) — development setup
+
+**Cloud:** [agent.mona.expert](https://agent.mona.expert) ·
+**Repo:** [MONAEXPERT/agent](https://github.com/MONAEXPERT/agent)