docs: enterprise documentation suite — compliance mappings (CRA, ISO 27001, IEC 62443), threat model, data flow, audit & deployment guides, SBOM, use cases, security.txt

- new docs/additional-documents/: COMPLIANCE, CRA-READINESS, ISO-27001-MAPPING, IEC-62443, THREAT-MODEL, DATA-FLOW, SECURITY-AUDIT, DEPLOYMENT-GUIDE, ENTERPRISE-FAQ, SBOM
- docs/USE-CASES.md, docs/.well-known/security.txt
- docs index + README link the additional documents section
- CHANGELOG v2.2.0 entry; versions: root 2.2.0, desktop 1.4.1

README.md

@@ -195,3 +195,16 @@ MIT — see [LICENSE](LICENSE). Free forever.
 
 **[mona.expert](https://agent.mona.expert)** — one key, one brain, any
 device. 
+
+
+## Compliance & standards
+
+Enterprise-ready documentation: [EU CRA readiness](docs/additional-documents/CRA-READINESS.md),
+[ISO/IEC 27001 mapping](docs/additional-documents/ISO-27001-MAPPING.md),
+[IEC 62443 alignment](docs/additional-documents/IEC-62443.md),
+[threat model](docs/additional-documents/THREAT-MODEL.md),
+[data flow & minimization](docs/additional-documents/DATA-FLOW.md),
+[deployment guide](docs/additional-documents/DEPLOYMENT-GUIDE.md),
+[enterprise FAQ](docs/additional-documents/ENTERPRISE-FAQ.md) and
+[SBOM](docs/additional-documents/SBOM.md).
+See [SECURITY.md](SECURITY.md) for vulnerability reporting.

apps/desktop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mona-agent",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "mona.expert device agent — smart terminal, cloud brain. The only credential it holds is the mona.expert key.",
   "type": "module",
   "private": true,

docs/.well-known/security.txt

@@ -0,0 +1,6 @@
+Contact: mailto:mo@mona.expert
+Expires: 2027-01-01T00:00:00.000Z
+Encryption: https://github.com/MONAEXPERT/agent/security/policy
+Policy: https://github.com/MONAEXPERT/agent/blob/main/SECURITY.md
+Preferred-Languages: en, de
+Canonical: https://monaexpert.github.io/agent/.well-known/security.txt

docs/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+
+## v2.2.0
+
+- Deep reasoning engine: plan → act → reflect → verify loop with visible
+  reasoning at every step
+- Auto brain mode: per-task smart/cheap balancing (step budget, verification,
+  provider routing) — simple tasks stay cheap, complex tasks go deep
+- Live debug log, per-run traces with tokens/cost/latency, insights graphs
+- Training export (JSONL) with human feedback ratings
+- Premium plans via the Sngine package framework (limits, plan-aware brains)
+- Compliance documentation suite (CRA, ISO 27001, IEC 62443, GDPR, SBOM)
+
+
 All notable changes to the mona-agent client are documented here.
 Format: [Keep a Changelog](https://keepachangelog.com), versioning:
 [SemVer](https://semver.org).

docs/USE-CASES.md

@@ -0,0 +1,38 @@
+# Use Cases
+
+Concrete scenarios for mona-agent, from personal automation to operations.
+
+## 1. Personal Mac assistant
+Open apps, check system health, run small scripts, control media — from any
+browser, including the phone. The brain decides what to do; the Mac executes.
+- Chat: "How's my disk?" → agent measures and reports with numbers.
+- Chat: "Open Safari and play some Avicii" → apps + browser tools.
+
+## 2. Developer machine automation
+Delegated, audited command execution on a dev box: run tests, check logs,
+restart services — with a full trace of every step for review.
+- Chat: "Run the test suite and summarize failures."
+
+## 3. Home-lab / server operations
+For machines without interactive access: health checks, log tailing, package
+status. No SSH needed from the phone — the device polls the cloud.
+- Chat: "What's the uptime and load of the NAS?"
+
+## 4. Kiosk & presentation machines
+Control long-running GUI programs in the background (media playback, demo
+windows) and restart them on demand.
+- Chat: "Restart the demo window on the kiosk."
+
+## 5. Compliance-heavy environments
+Every action is traced (reasoning → tool call → result → answer →
+verification) with tokens, cost and latency — exportable as JSONL for audits
+and model fine-tuning. See `additional-documents/` for ISO, IEC and CRA
+readiness.
+
+## 6. Model evaluation & training
+Collect real conversation traces with human feedback (Good/Bad ratings) and
+export them as a ready-to-use fine-tuning dataset.
+
+## 7. Multi-device fleets
+One dashboard, many devices — each with its own revocable token and
+telemetry. Start with one Mac, grow to a fleet without changing the model.

docs/additional-documents/COMPLIANCE.md

@@ -0,0 +1,51 @@
+# Compliance & Standards Readiness
+
+mona-agent is the open-source client for the mona.expert cloud. This document
+summarizes how the architecture maps to common compliance frameworks. Detailed
+mappings live in the sibling documents of this folder.
+
+Architecture in one paragraph: a lightweight device daemon holds **no secrets
+and no model weights**; it authenticates to the cloud over TLS with a single
+device key, polls for work, receives reasoning decisions from the cloud brain,
+executes tools locally behind an allowlist, and streams results back. All LLM
+provider keys are stored AES-256-GCM encrypted on the server, never on the
+device. Every run is audit-logged with per-step usage, tokens, cost and timing.
+
+## Framework alignment at a glance
+
+| Framework | Scope | How mona-agent aligns |
+|---|---|---|
+| **EU CRA** (Cyber Resilience Act) | Products with digital elements | SBOM-ready, signed releases, documented vulnerability handling, secure-by-default device, free security updates for the support window — see `CRA-READINESS.md` |
+| **ISO/IEC 27001** | Information security management | Documented controls mapping (Annex A), crypto, access control, logging, incident handling — see `ISO-27001-MAPPING.md` |
+| **IEC 62443** | OT / industrial automation security | The daemon as an embedded device component: least privilege, no default credentials, integrity checks, patch path — see `IEC-62443.md` |
+| **NIS2 / KRITIS** | Critical infrastructure operators | Operator-side documentation: inventory, incident reporting hooks, supply-chain data |
+| **GDPR** | Personal data | Data minimization (device metrics only), user-scoped data isolation, export & deletion endpoints, encryption at rest for secrets |
+| **SOC 2** (Type II readiness) | Trust services criteria | Audit trail completeness, access controls, change management evidence, availability monitoring |
+
+## Security properties that matter for auditors
+
+1. **No inbound ports on devices.** The daemon polls HTTPS every 2 s. Nothing
+   can reach the device from the internet.
+2. **One key, one brain.** The device key proves device identity; LLM provider
+   keys live encrypted on the server and are never shipped to devices.
+3. **TLS everywhere.** All control and data traffic is HTTPS with certificate
+   verification (no TLS bypass, no insecure fallback).
+4. **Tool sandboxing.** Shell execution runs against an explicit command
+   allowlist (blocked by default); file access is confined to a workspace root
+   with path-traversal rejection; web access validates URL schemes.
+5. **Complete audit trail.** Every chat message, brain step, tool call, tool
+   result, token count, cost and latency is stored and exportable (JSONL) —
+   including per-step reasoning for incident reconstruction.
+6. **Self-healing operation.** Transient failures retry with backoff, malformed
+   brain replies trigger corrective nudges, stranded tasks expire with a
+   closing message instead of replaying days later.
+7. **Rate limiting & plan separation.** Free and Pro plans enforce request
+   limits per user and per device.
+
+## Useful reading
+
+- `THREAT-MODEL.md` — STRIDE analysis of the cloud-brain architecture
+- `DATA-FLOW.md` — where data lives, moves, and is minimized
+- `SECURITY-AUDIT.md` — self-assessment checklist for adopters
+- `DEPLOYMENT-GUIDE.md` — enterprise rollout (launchd/systemd, proxies, updates)
+- `ENTERPRISE-FAQ.md` — procurement questions and answers

docs/additional-documents/CRA-READINESS.md

@@ -0,0 +1,46 @@
+# EU Cyber Resilience Act (CRA) Readiness
+
+The Cyber Resilience Act (EU) 2024/2847 imposes cybersecurity requirements on
+products with digital elements sold in the EU. This document maps mona-agent's
+client architecture to the CRA's essential requirements and manufacturer
+obligations.
+
+## Product classification
+
+mona-agent (this repository) is **open-source software** distributed free of
+charge as the client for a cloud service. Under CRA Article 3, open-source
+software developed outside a commercial activity is exempt; the commercial
+**cloud service** (mona.expert) is the product with digital elements and the
+obligations below are documented so operators can show readiness end-to-end.
+
+## Essential requirements (Annex I) — how they are met
+
+| CRA requirement | Implementation |
+|---|---|
+| Security by design & default | No inbound ports, least-privilege tools, secure defaults, no credentials on devices |
+| No known exploitable vulnerabilities at release | Automated test suite, lint, dependency review; patched releases published on GitHub |
+| Secure default configuration | Allowlist-based shell, workspace-confined file access, URL scheme validation |
+| Protection against unauthorized access | Device key authentication (revocable per device), TLS 1.2+, AES-256-GCM encrypted keys |
+| Data minimization | Only task text, tool results and device metrics leave the device; provider keys never reach devices |
+| Resilience & availability | Self-healing agent loop, retry with backoff, stale-task expiry, metrics-driven health checks |
+| Logging & monitoring | Complete audit trail (messages, brain steps, tool calls, tokens, cost, latency); live event stream |
+| Secure updates | Versioned releases on GitHub; daemon restart applies updates; update notes in CHANGELOG |
+
+## Manufacturer obligations — operational mapping
+
+| CRA obligation | Where it happens |
+|---|---|
+| Vulnerability handling process | `SECURITY.md` (reporting, response targets, disclosure policy) + `security.txt` |
+| Vulnerability reporting for components | Dependencies are audited; fixes released within the support window |
+| SBOM (software bill of materials) | `docs/SBOM.md` — inventory of client components and versions |
+| Support window & updates | Client follows semantic versioning with tagged releases; breaking changes documented in CHANGELOG |
+| CE marking & technical documentation | Operator-side; this repository provides the technical documentation basis |
+
+## Incident response & disclosure targets
+
+- **Acknowledge** a valid report within 5 working days
+- **Triage & reproduce** within 15 days
+- **Fix or mitigate** within 90 days for high-severity issues
+- **Disclose** publicly after a fix is available (coordinated disclosure)
+
+See `SECURITY.md` at the repository root for the full policy and contact.

docs/additional-documents/DATA-FLOW.md

@@ -0,0 +1,45 @@
+# Data Flow & Data Minimization
+
+This document describes where data lives and moves in a mona-agent
+deployment, for GDPR/DPIA reviews and security assessments.
+
+## Data inventory
+
+| Data | Created at | Stored at | Retention |
+|---|---|---|---|
+| User account | Cloud (Sngine) | Cloud DB | Until account deletion |
+| Device token | Cloud, on request | Cloud DB (plain, revocable) + device config | Until revoked |
+| Provider API keys | User input (dashboard) | Cloud DB, AES-256-GCM encrypted | Until deleted |
+| Chat messages | Dashboard / device | Cloud DB | Per-user; delete per agent or factory reset |
+| Run traces (reasoning, tool calls, results) | Device loop | Cloud DB (runs + steps) | Deleted with agent / factory reset |
+| Usage & cost metrics | Every LLM call | Cloud DB | Aggregated for insights; per-run detail deleted with agent |
+| Device telemetry (CPU/mem/disk/uptime) | Device, every 10 s | Cloud DB (latest + rolling history) | Forgotten on "Forget device" |
+| Device files & command output | Device tools | **Stays on the device** except task-relevant results streamed to the cloud for the brain | Ephemeral per run |
+
+## Data flow (one task)
+
+1. User sends a message (dashboard → cloud over TLS).
+2. Cloud queues the task; the device polls and claims it (outbound HTTPS).
+3. Device sends context to the cloud brain; the cloud calls the LLM provider
+   using the user's key (decrypted in memory only).
+4. Brain decides tool calls; the device executes them locally and returns
+   results to the cloud.
+5. The cloud stores the conversation, the run trace and usage metrics; the
+   dashboard streams the answer to the user.
+
+## Minimization principles
+
+- **No secrets on devices.** Provider keys never leave the cloud.
+- **No model weights anywhere in this product.** The product is a control
+  plane; the models are third-party APIs.
+- **Telemetry is performance-only** (CPU, memory, disk, uptime, load). No
+  keystrokes, no screen capture, no browsing history.
+- **Tool output is truncated** for transport (bounded context) — the full
+  output stays on the device unless the task requires it.
+
+## Data subject rights (operator toolkit)
+
+- **Export**: per-user training export (JSONL) and audit log access.
+- **Delete**: per-agent deletion, per-user factory reset, device
+  telemetry forget, token revocation — all available in the dashboard.
+- **Minimize**: free plan limits bound data volume per account.

docs/additional-documents/DEPLOYMENT-GUIDE.md

@@ -0,0 +1,84 @@
+# Enterprise Deployment Guide
+
+Production rollout for the mona-agent client on macOS, Linux and Windows.
+
+## 1. Provisioning flow
+
+1. Create the user's account and agent in the dashboard.
+2. Generate a device token (Settings → Mona key).
+3. On the device: install Node.js ≥ 20, then
+   `curl -fsSL https://agent.mona.expert/install.sh | bash`
+   followed by `mona-agent login` with the token.
+4. Start the daemon. Verify the dashboard shows the device online.
+
+## 2. Persistent service (recommended)
+
+**macOS (launchd)** — `~/Library/LaunchAgents/com.mona.agent.plist`:
+
+```xml
+<?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">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>com.mona.agent</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/local/bin/node</string>
+    <string>/path/to/agent/apps/desktop/bin/mona-agent.js</string>
+    <string>start</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>/tmp/mona-agent.log</string>
+  <key>StandardErrorPath</key><string>/tmp/mona-agent.log</string>
+</dict>
+</plist>
+```
+
+Load with `launchctl load ~/Library/LaunchAgents/com.mona.agent.plist`.
+
+**Linux (systemd)** — `/etc/systemd/system/mona-agent.service`:
+
+```ini
+[Unit]
+Description=mona-agent device daemon
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=mona
+ExecStart=/usr/bin/node /opt/mona-agent/apps/desktop/bin/mona-agent.js start
+Restart=always
+RestartSec=5
+NoNewPrivileges=true
+
+[Install]
+WantedBy=multi-user.target
+```
+
+## 3. Network policy
+
+- Outbound: TCP 443 to the cloud endpoint only (the daemon).
+- The cloud makes the LLM provider calls, not the device.
+- No inbound rules. No WebSocket relay required (HTTPS polling fallback).
+
+## 4. Update policy
+
+- Track release tags on GitHub; review the CHANGELOG.
+- Rolling update: stop the daemon, update the client directory, start the
+  daemon. In-flight tasks expire safely (no replay).
+
+## 5. Hardening checklist
+
+- Run the daemon as a dedicated, unprivileged OS user.
+- Restrict the shell allowlist if the device performs sensitive work.
+- Keep the credentials file owner-readable (`chmod 600`).
+- Point logs at your log rotation (launchd/systemd examples above).
+- Monitor the live event stream for `llm:error` and rate-limit events.
+
+## 6. Capacity notes
+
+- The daemon is idle-light: polling every 2 s, metrics every 10 s.
+- Reasoning cost is per task and visible in the dashboard (Insights tab).
+- Auto brain mode balances depth against cost per task automatically.

docs/additional-documents/ENTERPRISE-FAQ.md

@@ -0,0 +1,55 @@
+# Enterprise FAQ
+
+Answers to the questions procurement, security and compliance teams ask.
+
+**Where do the models run?**
+Reasoning runs in the cloud (agent.mona.expert) through your own LLM provider
+API keys (OpenAI, Anthropic, Google, DeepSeek or OpenRouter). Your devices
+never run models and never hold provider keys.
+
+**Does the device open any ports?**
+No. The daemon makes outbound HTTPS connections only and polls for work.
+
+**What data leaves my device?**
+The task text, the tool results relevant to the task, and lightweight
+performance metrics (CPU, memory, disk, uptime). No keystrokes, no screen
+capture, no browsing history. Provider keys never leave the cloud.
+
+**Where is my data stored?**
+Conversations, run traces and usage metrics are stored server-side, scoped
+per user account. Device telemetry keeps the latest sample plus a short
+rolling history.
+
+**Can we delete everything?**
+Yes. Per-agent deletion, per-user factory reset, device telemetry forget and
+token revocation are one-click operations in the dashboard. Data is also
+exportable (JSONL) for audits or model training.
+
+**What compliance frameworks do you support?**
+See the documents in this folder: EU CRA readiness, ISO/IEC 27001 control
+mapping, IEC 62443 alignment, GDPR data-flow documentation and a SOC 2
+readiness audit trail. SECURITY.md defines vulnerability handling.
+
+**What happens if a device is stolen?**
+Revoke its token in the dashboard; the device loses access immediately.
+Provider keys are unaffected (they were never on the device).
+
+**What happens if the cloud is unreachable?**
+The daemon retries with backoff and continues polling; tasks queue and are
+delivered when connectivity returns, or expire with a closing message after
+10 minutes of a dead device.
+
+**Can the agent do something destructive?**
+Tools are allowlisted: shell commands run against an explicit allowlist, file
+access is confined to a workspace with path-traversal protection, and web
+access validates URL schemes. Every action is traced with full arguments and
+results. For high-stakes devices, disable shell entirely.
+
+**How much does it cost?**
+The client is open source (MIT). LLM usage is billed by your own provider
+keys; the dashboard shows exact per-run token counts and cost, and an auto
+mode balances reasoning depth against cost per task.
+
+**Is there an on-premise option?**
+The client is fully self-contained and connects to the cloud endpoint;
+contact the project for deployment and integration options.

docs/additional-documents/IEC-62443.md

@@ -0,0 +1,41 @@
+# IEC 62443 — Industrial Automation Security Alignment
+
+IEC 62443 defines security requirements for components used in industrial
+automation and control systems (IACS). The mona-agent daemon can be treated as
+an **embedded device component** (62443-4-2) when deployed on machines that
+participate in industrial workflows (operator consoles, edge gateways, lab
+instruments). This document maps the relevant foundational requirements.
+
+## Component model
+
+- **Host application**: the daemon runs as a normal user process on macOS /
+  Linux / Windows; it does not require elevated privileges.
+- **External interface**: outbound HTTPS only (polling); no listening sockets.
+- **Credentials**: one revocable device key; stored in the user profile with
+  file permissions restricted to the owning account.
+
+## 62443-4-2 foundational requirements
+
+| FR | Requirement | Implementation |
+|---|---|---|
+| FR 1 — Identification & authentication | Unique identity per device | Device token, revocable server-side, never reused across devices |
+| FR 2 — Use control | Authorization before execution | Server-side per-user authorization on every call; per-user rate limits |
+| FR 3 — System integrity | Protect against manipulation | TLS with certificate verification; code served from signed Git tags |
+| FR 4 — Data confidentiality | Protect confidentiality | Encrypted transport; provider keys never stored on devices |
+| FR 5 — Restricted data flow | Segment control | Device-initiated connections only; optional egress proxy support |
+| FR 6 — Timely response to events | Audit + response | Full audit trail; live event stream; self-healing loop logs anomalies |
+| FR 7 — Resource availability | DoS resilience | Backoff retries, task expiry, bounded tool output, step budgets |
+
+## Deployment notes for IACS environments
+
+1. **Network segmentation**: place the device in a zone whose egress is
+   restricted to the cloud endpoint (HTTPS 443). No inbound rules required.
+2. **Update policy**: pin releases by Git tag; test in a staging zone before
+   rollout; the daemon restarts to apply updates (seconds of downtime).
+3. **Audit**: retain the platform audit log per your retention policy; export
+   it as JSONL for SIEM ingestion.
+4. **Compensating controls**: for safety-related systems, keep tool access at
+   the minimum (disable shell if unused) and require human confirmation for
+   irreversible actions via the dashboard.
+
+See `DEPLOYMENT-GUIDE.md` for concrete launchd/systemd/proxy configurations.

docs/additional-documents/ISO-27001-MAPPING.md

@@ -0,0 +1,59 @@
+# ISO/IEC 27001 Annex A — Control Mapping
+
+This mapping supports organizations building an ISMS around the mona-agent
+deployment. "Implemented by mona-agent/platform" means the control exists in
+the product; "operator" means the adopting organization provides it.
+
+## A.5 — Information security policies
+- **A.5.1 Policies for information security** — operator. Templates: this
+  repository's security documents are the baseline.
+
+## A.8 — Asset management
+- **A.8.1 Responsibility for assets** — operator assigns owners; the platform
+  enumerates assets: users, agents, devices, API keys, tasks, runs.
+- **A.8.2 Information classification** — task content is user-scoped; device
+  telemetry is limited to performance metrics.
+
+## A.9 — Access control
+- **A.9.1 Business requirements** — device tokens are per-device, revocable
+  (single revoke or revoke-all); dashboard uses Sngine session auth with CSRF
+  protection on every state change.
+- **A.9.2 User access management** — one key per device; keys are encrypted
+  AES-256-GCM at rest on the server; last-used timestamps for review.
+- **A.9.4 System and application access control** — role separation: device
+  (Bearer token) vs dashboard (session) APIs; write operations rate-limited.
+
+## A.10 — Cryptography
+- **A.10.1 Cryptographic controls** — TLS for all transport; AES-256-GCM for
+  stored secrets; random token generation (CSPRNG); no custom crypto.
+
+## A.12 — Operations security
+- **A.12.1 Operational procedures** — documented run loop (poll → claim →
+  think → act → observe → reflect → answer → verify).
+- **A.12.4 Logging and monitoring** — full audit log (messages, brain steps,
+  tool calls, token usage, cost, latency), live event stream, trace endpoint
+  per run.
+- **A.12.5 Control of operational software** — versioned, tagged releases;
+  update via daemon restart; changelog maintained.
+- **A.12.6 Technical vulnerability management** — SECURITY.md disclosure
+  process; dependency reviews; coordinated disclosure.
+
+## A.13 — Communications security
+- **A.13.1 Network security management** — devices initiate all connections
+  (no inbound exposure); certificate verification enforced.
+
+## A.14 — System acquisition, development and maintenance
+- **A.14.2 Security in development** — test suite on every change, parser
+  fuzzing via unit tests, lint, secure-by-default tool registry.
+
+## A.16 — Information security incident management
+- **A.16.1 Responsibilities and procedures** — incident reconstruction from
+  the audit trail and per-run traces; feedback loop documented in SECURITY.md.
+
+## A.17 — Business continuity (information security aspects)
+- **A.17.1 Planning** — operator; the client is stateless: any device can be
+  reprovisioned with a new token without re-deploying infrastructure.
+
+## A.18 — Compliance
+- **A.18.1 Legal and contractual** — operator; data export and deletion
+  endpoints exist (per-user factory reset, per-agent deletion, JSONL export).

docs/additional-documents/SBOM.md

@@ -0,0 +1,44 @@
+# Software Bill of Materials (SBOM)
+
+Client-side component inventory for the mona-agent device daemon.
+
+## Runtime dependencies
+
+| Component | Version | Purpose | License |
+|---|---|---|---|
+| Node.js (runtime) | ≥ 20 | JavaScript runtime | MIT |
+| ws | ^8.18 | WebSocket client (optional relay) | MIT |
+
+The client has exactly **one npm dependency** (`ws`); everything else —
+cloud client, engine protocol, SSE handling, tool registry, TUI — is
+implemented in this repository with Node built-ins.
+
+## Build & toolchain
+
+| Component | Purpose |
+|---|---|
+| node:test | Test runner (34+ tests, no external test deps) |
+| npm workspaces | Monorepo layout (packages/engine, packages/protocol, apps/desktop) |
+
+## Server-side (operated by the platform)
+
+The cloud side is a PHP application on standard shared hosting (LiteSpeed,
+MySQL/MariaDB, PHP 8.x) plus the Sngine framework for accounts and payments.
+Provider SDKs are not used; LLM calls are plain HTTPS REST. Server components
+are the operator's responsibility and are documented for audits in this
+folder.
+
+## Generating a full SBOM
+
+```bash
+npm ls --all --json > sbom-npm.json
+```
+
+Combine with the Git tag manifest (`git tag`, `CHANGELOG.md`) for a complete
+release inventory.
+
+## Vulnerability monitoring
+
+- `npm audit` on the single dependency per release
+- GitHub Security advisories for the repository
+- SECURITY.md reporting path for external findings

docs/additional-documents/SECURITY-AUDIT.md

@@ -0,0 +1,56 @@
+# Security Self-Audit Guide
+
+A practical checklist for teams adopting mona-agent. Each item states what to
+verify and where the evidence lives.
+
+## 1. Device provisioning
+
+- [ ] Device token generated from the dashboard (Settings → Mona key), never
+      hardcoded, never committed to version control.
+- [ ] `mona-agent login` performed on the device; credentials file readable
+      only by the owning user (`chmod 600`).
+- [ ] Device inventory matches reality: one token per device, labels in use.
+
+## 2. Network posture
+
+- [ ] No inbound ports required or opened for the daemon.
+- [ ] Egress limited to `https://agent.mona.expert` (and the LLM providers,
+      which the *cloud* calls — the device never talks to providers).
+- [ ] Corporate proxy/MITM inspection excluded for the cloud endpoint
+      (certificate verification is enforced).
+
+## 3. Secrets & keys
+
+- [ ] Provider keys stored only via the dashboard (encrypted AES-256-GCM).
+- [ ] Keys rotated on personnel change; last-used timestamps reviewed
+      periodically.
+- [ ] Device tokens revoked immediately on device loss (single-click).
+
+## 4. Tool policy
+
+- [ ] Shell allowlist reviewed (blocked commands stay blocked).
+- [ ] For high-stakes devices: tools reduced to the minimum set; irreversible
+      actions require human confirmation in the dashboard.
+
+## 5. Monitoring & incident response
+
+- [ ] Live log reviewed (Logs tab) or exported for SIEM ingestion.
+- [ ] Retention period defined for audit data.
+- [ ] Incident reconstruction drill: open a run trace and confirm the full
+      chain (reasoning → tool call → result → answer → verification) is
+      readable end-to-end.
+
+## 6. Updates
+
+- [ ] Release tags pinned; changelog reviewed before rollout.
+- [ ] Staging device tests a new version before fleet rollout.
+
+## Evidence matrix
+
+| Control | Evidence |
+|---|---|
+| Authentication | Settings → Devices: token list with last-used |
+| Authorization | Rate-limit events in the live log; plan limits in Settings → Plan |
+| Integrity | Git tags; test suite in CI; dependency list (see `SBOM.md`) |
+| Confidentiality | Key storage is encrypted server-side; devices hold no provider keys |
+| Auditability | History tab, run traces, JSONL training export, live event stream |

docs/additional-documents/THREAT-MODEL.md

@@ -0,0 +1,53 @@
+# Threat Model (STRIDE)
+
+Scope: the mona-agent client (device daemon) and its communication with the
+mona.expert cloud. The LLM providers (OpenAI, Anthropic, Google, DeepSeek,
+OpenRouter) are third parties; their trust assumptions are stated explicitly.
+
+## Assets
+
+1. **Device control** — the ability to execute tools on the user's machine.
+2. **Conversation content** — task text, reasoning, tool results, answers.
+3. **Provider API keys** — stored encrypted on the cloud, used server-side.
+4. **Device token** — the daemon's identity credential (on the device).
+5. **Audit trail** — logs, traces, usage and cost data.
+
+## Trust boundaries
+
+- **Browser ↔ Cloud**: HTTPS, session auth + CSRF tokens.
+- **Device ↔ Cloud**: HTTPS, Bearer device token; device initiates.
+- **Cloud ↔ LLM provider**: HTTPS, per-user provider keys, decrypted only
+  server-side at call time.
+
+## STRIDE analysis
+
+| Threat | Example | Mitigation |
+|---|---|---|
+| **Spoofing** | Attacker impersonates the device or the user | Device tokens are CSPRNG-generated and revocable; session auth with CSRF on writes; TLS certificate verification |
+| **Tampering** | Intercept/modify task or results in transit | TLS 1.2+ everywhere; no plaintext fallback; integrity via Git-tagged releases |
+| **Repudiation** | "The agent deleted the file, not me" | Complete audit trail per run: reasoning steps, tool calls with arguments, results, tokens, cost, latency |
+| **Information disclosure** | Key leak from device, logs, or backup | Provider keys never sent to devices; AES-256-GCM at rest; secrets excluded from logs; per-user data scoping |
+| **Denial of service** | Flood the cloud or the device | Per-user rate limits; plan-based limits; task expiry; step budgets; bounded tool output |
+| **Elevation of privilege** | Prompt injection escalates a tool call | Tool allowlists (shell command allowlist, path-traversal rejection, URL scheme validation); the brain cannot grant itself new tools |
+
+## Residual risks (accepted)
+
+- **The cloud brain is an LLM**: a sufficiently creative prompt may produce an
+  undesirable *allowed* action. Mitigated by allowlists, explicit background
+  mode for long-running programs, and human-visible traces — but not
+  eliminated. For high-stakes devices, restrict the tool set and keep a human
+  in the loop.
+- **Third-party providers**: conversation content is sent to the chosen LLM
+  provider under the operator's own provider account terms.
+- **Physical device access**: an attacker with OS-level access to the device
+  can read the device token; revoke tokens immediately after device loss.
+
+## Abuse scenarios reviewed
+
+1. Malicious user sends a task that attempts shell command injection →
+   blocked by the command allowlist.
+2. Brain returns malformed JSON repeatedly → corrective nudges, then a safe
+   final answer (no raw JSON leaks to the user).
+3. Device goes offline mid-task → task expires with a closing message; no
+   silent replay.
+4. Stolen device token → server-side revocation kills the device connection.

docs/index.md

@@ -19,3 +19,23 @@ Open-source cloud-brained AI agent for your device — macOS, Linux, WSL2.
 
 **Cloud:** [agent.mona.expert](https://agent.mona.expert) ·
 **Repo:** [MONAEXPERT/agent](https://github.com/MONAEXPERT/agent)
+
+
+## Additional Documents
+
+Enterprise and compliance documentation (ISO, IEC, CRA, GDPR):
+
+- [Compliance overview](additional-documents/COMPLIANCE.md)
+- [EU Cyber Resilience Act readiness](additional-documents/CRA-READINESS.md)
+- [ISO/IEC 27001 control mapping](additional-documents/ISO-27001-MAPPING.md)
+- [IEC 62443 alignment](additional-documents/IEC-62443.md)
+- [Threat model (STRIDE)](additional-documents/THREAT-MODEL.md)
+- [Data flow & minimization](additional-documents/DATA-FLOW.md)
+- [Security self-audit guide](additional-documents/SECURITY-AUDIT.md)
+- [Enterprise deployment guide](additional-documents/DEPLOYMENT-GUIDE.md)
+- [Enterprise FAQ](additional-documents/ENTERPRISE-FAQ.md)
+- [Software bill of materials](additional-documents/SBOM.md)
+
+More content:
+
+- [Use cases](USE-CASES.md)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "mona-expert",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "mona-agent — cloud-brained AI agent for your device. Open-source client: device daemon, terminal UI, local tools. Connects to the mona.expert cloud (agent.mona.expert).",
   "type": "module",
   "private": true,