highhxcli 0.1.0__tar.gz → 0.3.2__tar.gz

highhxcli-0.3.2/CHANGELOG.md

@@ -0,0 +1,147 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+The format follows [Keep a Changelog](https://keepachangelog.com/) and the
+project uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-09-27
+
+Two plans, one platform: **Free** is deterministic HighhX; **Pro** adds the AI agent and AI
+computer use on top of the same tools, safety, confirmation, verification and audit.
+
+### Terminal identity
+
+- **The HighhX knight**: terminal-native brand art (Unicode quadrant blocks, ASCII fallback;
+  full 26x31 and compact 13x15) shown by `highhx` on a terminal and at the start of
+  `highhx agent`, sized to the terminal (`HIGHHX_BANNER=full|compact|off`, `HIGHHX_ASCII`).
+
+### Reliability and security hardening
+
+- Platform: AI stream state and rate limits live in the database (migration 0003), so any
+  instance can resume, replay or cancel a stream; dead instances' streams end with a retryable
+  error; tested with two instances sharing only the database (SQLite and PostgreSQL).
+- Providers: cancellation aborts the upstream socket immediately; inactivity timeouts; SDK
+  retries only before streaming; truncated streams are errors, not answers; raw transport errors
+  are normalised — tested through the real Anthropic, OpenAI and Gemini SDKs over HTTP.
+- Browser: a lost DevTools answer is an *unknown* outcome that is never repeated (also after a
+  reconnect); per-call timeouts now fire when the browser is silent; waits for navigations
+  started by an action; page-text changes count for verification; sockets closed on crashes.
+- OCR is available as a read-only `screen` source; OCR and accessibility subprocesses (and
+  their children) are killed on cancellation.
+- Migration names are validated before use in SQL (MySQL backslash escaping); project XML
+  manifests with DTDs/entities are refused; health checks only speak http(s).
+
+### Features
+
+- **Shared safety layer** (`highhx/safety`) for Free automation and the agent: semantic
+  classification of commands (parsed pipelines, `sh -c`, `sudo`, force pushes, destructive SQL,
+  installs, publishing, credentials, permissions, security controls, remote code, production)
+  and UI actions (role/type/structure and multilingual labels); explicit confirmation panel;
+  single-use HMAC approval tickets bound to the exact action; blocked catastrophic actions;
+  redacted audit log (`highhx audit`).
+- **Computer use** (`highhx/computer`): semantic observations, finite action candidates,
+  observe → act → re-observe → verify runtime with recovery; Chrome/Chromium/Edge/Brave via
+  DevTools; macOS Accessibility; OCR via tesseract. Free: `highhx computer …` commands and YAML
+  flows; Pro: `computer_observe`, `computer_act`, `browser_open`, `app_open` agent tools.
+- `highhx do "<request>"`: deterministic plain-language requests without AI.
+- `highhx agent stop`: kill switch that cancels model requests, retries, tools and their child
+  processes.
+- Model calls: exponential backoff with jitter, bounded attempts, circuit breaker, per-attempt
+  idempotency keys; tools are never retried automatically.
+- Resumable streaming: SSE event ids, `Last-Event-ID` resume without re-calling the model,
+  duplicate suppression, remote cancellation.
+- CLI ↔ platform protocol versioning (`X-HighhX-Protocol: 1.1`, 426 on incompatibility).
+- Agent session state machine (`created`, `running`, `waiting_for_confirmation`, `completed`,
+  `failed`, `cancelled`, `closed`) enforced on CLI and platform; single-process session leases.
+- Tool results carry structured `error_code` and `verified`; per-tool timeouts.
+- Prompt-injection defence: tool output and external content framed as untrusted data.
+
+### Changed
+
+- All Pro AI goes through the HighhX platform (authenticated, entitled, metered). The
+  client-side bring-your-own-key path was removed; `--provider` selects the gateway upstream.
+- Platform 0.2.0: Alembic migrations (upgrades 0.1.0 databases in place), token expiry and
+  rotation, account suspension, subscription expiry with grace, out-of-order and concurrent
+  webhook handling, `invoice.paid` renewals, idempotent metering, per-account concurrency limit,
+  computer-use entitlement check, upstream fallbacks, `/readyz`, optional CORS.
+
+### Fixed
+
+- Stripe: the webhook handler fetched subscriptions with a POST (which updates them); it now
+  uses GET. Subscription events now record the Stripe customer, so later invoice events apply.
+- Concurrent HighhX processes opening a fresh state database raced on migrations; migrations now
+  run under an exclusive lock.
+- Agent file edits invalidate stale Python bytecode.
+
+## [0.2.0] - 2026-09-27
+
+### Features
+
+- **HighhX Pro — `highhx agent`**: an AI developer agent in the terminal. Describe the task in plain
+  language; the agent inspects the project, proposes a plan (approve / revise), works through
+  HighhX's own capabilities as tools — code search and edits, tests, lint/type checks, fixers,
+  builds, dependencies, git, security scans, doctor/diagnose/repair, workflows, deployments and
+  rollbacks — verifies the result and summarises it. Live progress (✓ / ✗ per step), streamed
+  Markdown answers, diffs for every file change, `/undo`, and slash commands (`/help`, `/status`,
+  `/plan`, `/context`, `/model`, `/mode`, `/history`, `/changes`, `/memory`, `/usage`, `/clear`, `/quit`).
+- The agent reuses the existing safety system: every command goes through `Engine.run` (risk
+  classification, `policies.yaml`, approvals, history); agent actions have policy names
+  (`agent:write`, `agent:exec`, `agent:deploy:<target>` …); approval modes `ask` (default),
+  `auto-edit` and `read-only`; deployments and rollbacks always ask.
+- Provider abstraction with streaming adapters for the managed HighhX gateway (default), Anthropic,
+  OpenAI and Google Gemini (bring your own key: `pip install "highhxcli[ai]"`).
+- Sessions and transcripts are saved (`highhx agent --continue`, `--resume ID`, `highhx agent sessions`);
+  per-project memory in `.highhx/memory.md`; project instructions from `HIGHHX.md` / `AGENTS.md`.
+- `highhx agent "…"` handles one request non-interactively (pipes, CI, `--json`).
+- HighhX platform integration: `highhx login` (browser device flow or `--with-token`), `highhx logout`,
+  `highhx account` (`status`, `plans`, `usage`, `upgrade`, `billing`, `settings`).
+- `agent:` section in `.highhx/config.yaml` (provider, model, approval, max_steps, effort, instructions).
+- A bare `highhx` now suggests the next step (`highhx init`, or signing in for Pro).
+- New exit code 10: HighhX account required, or the plan does not include the feature.
+- `server/`: the HighhX Platform backend (FastAPI + SQLAlchemy; SQLite or PostgreSQL) — accounts,
+  device sign-in, hashed API tokens, Free/Pro entitlements, the metered AI gateway, projects,
+  agent-session sync, Stripe checkout/portal/webhooks, rate limiting and security headers.
+
+### Security
+
+- The agent never reads or writes secret files (`.env*`, private keys, credential files), cannot
+  leave the project root (symlinks included), cannot modify `.git/` or HighhX state, and honours
+  `forbidden_files`. Tool output is redacted before it reaches the model or the transcript.
+- Platform credentials are stored per user with mode 0600; plain http is refused except for localhost.
+
+## [0.1.0] - 2026-09-26
+
+### Features
+
+- Project detection for Python, Node.js, React, Next.js, Flutter/Dart, Java, C/C++, Go, Rust, Docker, databases and monorepos.
+- `highhx init` with per-stack templates for config, environment, policies and workflows.
+- Execution engine: streaming output, timeouts, cancellation, retries with exponential backoff, parallel execution, graceful shutdown.
+- Workflow engine: dependency graphs, parallel stages, conditions, variables, outputs, approvals, retries, timeouts, reusable workflows, dry-run, validation and graphs.
+- Risk classification and approvals with non-bypassable rules; project policies.
+- Environment profiles with `.env` files, validation and masked secrets.
+- Dependencies, testing (with coverage/changed/watch), building, artifacts and cleanup.
+- Git helpers, semantic versioning, changelog generation from Conventional Commits, releases and publishing.
+- Deployment targets (local, Docker, SSH, Kubernetes, Terraform, plugins) with preflight, health checks, state tracking and rollback.
+- Local security checks: secrets, permissions, configuration, workflows, policies and dependency audits.
+- Services, ports, Docker Compose and database (SQLite, PostgreSQL, MySQL) management.
+- Plugins with manifests, declarative contributions and integrity-checked code.
+- Execution history, redacted logs, tracing, reports, doctor, diagnose and repair.
+
+### Security
+
+- Plugin code runs only for contents trusted per user (`highhx plugin trust`); a repository cannot enable its own plugin code. Plugins containing symlinks are rejected and plugin names are validated.
+- All output — including `--json` documents and captured command output — is redacted.
+- Isolated plugin commands never receive environment-profile values.
+- Values substituted into deploy commands are restricted to a safe character set.
+- Hardened risk rules (wrapped shells, split `rm` flags, fork bombs, raw device writes, `find -delete`, `docker rm`, `shred`/`truncate`).
+- Duplicate YAML keys are rejected.
+
+### Reliability
+
+- Workflow step output is written to execution logs; retries, step transitions and approval decisions are logged.
+- `--json` always emits exactly one JSON document.
+- An unreadable state database is diagnosed and can be repaired (`highhx repair`).
+- `mysqldump` runs with `--no-tablespaces`, so backups work without the PROCESS privilege.
+- Global `--profile` was renamed `--config-profile` so it no longer collides with `env --profile`.

highhxcli-0.1.0/README.md → highhxcli-0.3.2/PKG-INFO

@@ -1,10 +1,61 @@
+Metadata-Version: 2.5
+Name: highhxcli
+Version: 0.3.2
+Summary: HighhX — the developer command center CLI, with HighhX Pro: an AI developer agent in your terminal.
+Author: HighhX contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,automation,cli,coding-agent,developer-tools,devops,workflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Provides-Extra: ai
+Requires-Dist: anthropic>=1.0; extra == 'ai'
+Requires-Dist: google-genai>=1.20; extra == 'ai'
+Requires-Dist: openai>=1.40; extra == 'ai'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=1.0; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: anthropic>=1.0; extra == 'dev'
+Requires-Dist: coverage[toml]>=7.4; extra == 'dev'
+Requires-Dist: google-genai>=1.20; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: openai>=1.40; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: gemini
+Requires-Dist: google-genai>=1.20; extra == 'gemini'
+Provides-Extra: openai
+Requires-Dist: openai>=1.40; extra == 'openai'
+Description-Content-Type: text/markdown
+
 # HighhX
 
-**HighhX is a local-first developer command center.** One CLI — `highhx` — detects
+**HighhX is a developer command center for your terminal.** One CLI — `highhx` — detects
 your project, runs your workflows, manages environments, dependencies, tests,
 builds, git, releases, deployments, services and databases, and keeps a searchable
 history of everything it did. Every risky action is classified and needs approval.
 
+| | |
+|---|---|
+| **HighhX Free** | Deterministic HighhX: the full developer CLI plus browser/desktop automation with known targets (`highhx computer`, `highhx do`). Local, no account, no AI. |
+| **HighhX Pro** | Everything in Free plus `highhx agent` — an AI developer agent that plans, changes code, runs your tools, operates browsers and apps (AI computer use), recovers from failures and verifies the result. |
+
+Free and Pro share one execution platform: the same tools, safety policy, confirmations,
+verification and audit trail. The AI only chooses actions; it never gets its own way to run them.
+
 ```text
 $ highhx doctor
 
@@ -28,6 +79,7 @@ Suggested actions
 - [Why HighhX](#why-highhx)
 - [Installation](#installation)
 - [Quick start](#quick-start)
+- [HighhX Pro: the AI developer agent](#highhx-pro-the-ai-developer-agent)
 - [Commands](#commands)
 - [Workflows](#workflows)
 - [Configuration](#configuration)
@@ -42,8 +94,10 @@ Most projects accumulate a pile of scripts, Makefile targets, README snippets an
 CI YAML that only half the team remembers. HighhX gives every project the same
 front door:
 
-- **Local-first and offline-first.** No cloud backend, no account, no API keys, no AI.
-  Everything — history, logs, deployment state — lives in `.highhx/` on your machine.
+- **Local-first CLI.** Every Free command works without an account or network.
+  History, logs and deployment state live in `.highhx/` on your machine.
+- **An AI agent that uses your real tools (Pro).** `highhx agent` works through HighhX's
+  own commands and safety system — not a chatbot pasting shell snippets.
 - **Detects instead of asking.** Python (pip/uv/poetry/pdm/pipenv), Node (npm/pnpm/yarn/bun),
   React, Next.js, Flutter/Dart, Java (Maven/Gradle), C/C++ (CMake/Make), Go, Rust, Docker,
   common databases and monorepos — from real manifests and lockfiles, not file extensions.
@@ -105,12 +159,105 @@ highhx logs            # output of the last execution (secrets redacted)
 └── logs/                # execution logs (git-ignored)
 ```
 
+## HighhX Pro: the AI developer agent
+
+```text
+$ highhx agent
+
+     ▗█▖
+     ▐▀▌
+    ▗ ▄ ▖
+   ▗▚▐█▌▞▖
+  ▗▚█▐█▌█▞▖      HighhX v0.3.0
+   ▟█▐█▌█▙       AI Developer Agent · Pro
+  ▐▐█▌█▐█▌▌      ~/code/shop
+  █▗▜▌█▐▛▖█
+  █▐▙▘█▝▟▌█
+  ▐▐▜▌▄▐▛▌▌
+ ▗▝▐▐▌█▐▌▌▘▖
+ █▙▝█▌█▐█▘▟█
+▜▙▜█▖▘█▝▗█▛▟▛
+ ▀█▟▀ █ ▀▙█▀
+   ▀▌ █ ▐▀
+
+Project   shop
+Stack     Python, FastAPI
+Branch    main
+Status    clean
+AI        Connected HighhX (managed)
+
+What would you like me to do? (/help for commands)
+
+❯ run all the tests and fix whatever fails
+
+╭─ Plan ───────────────────────────────────────────╮
+│  1. Run the test suite                           │
+│  2. Investigate the failures                     │
+│  3. Fix the root cause                           │
+│  4. Re-run tests, lint and type checks           │
+╰─ Get the test suite green ───────────────────────╯
+Proceed? [Y/n]
+
+✓ Run tests — 3 tests failing (4.1s)
+✓ Read src/shop/cart.py — 88 lines
+⚠ Action requires approval
+  Edit src/shop/cart.py (+2 -1)
+  …diff…
+Proceed? [y/N/a=always this session] y
+✓ Edit src/shop/cart.py — +2 -1
+✓ Run tests — Tests passing — 48 passed (pytest) (4.3s)
+✓ Run checks — all checks passed
+
+Fixed the discount rounding in `cart.total()` (it rounded before applying tax).
+All 48 tests pass; lint and type checks are clean.
+
+4 steps  ·  1 file changed (/undo)  ·  38.2k tokens  ·  41s
+```
+
+Ask for what you want in plain language — *explain how this project works*, *find and
+fix the bugs*, *add authentication*, *find security issues*, *why is the application
+crashing?*, *prepare this project for release*, *deploy this*. The agent inspects the
+project, proposes a plan for multi-step work, uses HighhX's capabilities as tools
+(code search and edits, tests, checks, fixers, builds, dependencies, git, security scans,
+doctor/diagnose/repair, workflows, deploy and rollback), verifies what it did and
+summarises it.
+
+- **Same safety system.** Commands run through the HighhX engine: risk classification,
+  `policies.yaml`, approvals and history. File edits show a diff and ask (unless you
+  choose `--mode auto-edit`); pushes, deploys and rollbacks always ask; production
+  deploys need typed confirmation. The agent cannot leave the project, read secret files
+  or touch `.git/`. `--mode read-only` investigates without changing anything.
+- **Slash commands.** `/help` `/status` `/plan` `/context` `/model` `/mode` `/history`
+  `/changes` `/undo` `/memory` `/usage` `/clear` `/quit`.
+- **Sessions.** Saved per project: `highhx agent --continue`, `--resume ID`, `highhx agent sessions`.
+- **Scriptable.** `highhx agent "…"` outside a terminal (or with `--json`) handles one request
+  and exits — `--yes --mode auto-edit` for unattended runs in CI.
+- **Providers.** All Pro AI goes through the HighhX platform (authenticated, plan-checked,
+  metered); choose the upstream — Anthropic, OpenAI or Gemini — with `highhx account settings`
+  or `/model`. No provider key is needed on your machine.
+- **Kill switch.** `highhx agent stop` (or Ctrl+C) cancels the model request, retries, running
+  commands and their child processes immediately.
+- **Computer use.** The agent observes browsers and apps semantically and chooses among valid
+  actions; see [docs/computer-use.md](docs/computer-use.md).
+
+```bash
+highhx login                 # browser sign-in (creates your account)
+highhx account upgrade       # HighhX Pro checkout
+highhx agent                 # interactive
+highhx agent "why is the application crashing?"
+```
+
+Guides: [docs/agent.md](docs/agent.md) · [docs/computer-use.md](docs/computer-use.md) · [docs/platform.md](docs/platform.md).
+
 ## Commands
 
 Full reference with every option: [docs/commands.md](docs/commands.md).
 
 | Area | Commands |
 |---|---|
+| HighhX Pro | `agent` `agent sessions` `agent models` `agent stop` |
+| Automation (no AI) | `do` `computer status/open/observe/click/type/select/press/scroll/run` `computer browser start/stop` |
+| Account | `login` `logout` `account` `account plans/usage/upgrade/billing/settings` |
 | Project | `init` `status` `info` `dev` `start` `stop` `restart` `check` |
 | Code & tasks | `run <workflow>` `exec <command>` `script <name>` `task <name>` `watch` `fix` |
 | Dependencies | `deps` `deps install` `deps update` `deps outdated` `deps audit` `deps clean` |
@@ -121,7 +268,7 @@ Full reference with every option: [docs/commands.md](docs/commands.md).
 | Security | `security` `security scan/secrets/deps/config/report` |
 | Containers & data | `docker up/down/logs` `services` `ports` `db status/migrate/seed/backup/restore` |
 | Workflows & automation | `workflow list/validate/create/graph` `schedule` `hook` `trigger` `watchers` |
-| Observability | `logs [--follow]` `history [id]` `report` `trace` |
+| Observability | `logs [--follow]` `history [id]` `audit` `report` `trace` |
 | Extensibility & team | `plugin list/install/remove/update/search/trust` `config` `policy` `workspace` `profile` |
 | Diagnostics | `doctor` `diagnose` `repair` `debug` |
 
@@ -272,6 +419,10 @@ Details: [docs/security.md](docs/security.md).
 - **Secrets.** Secret values are never printed: `env` masks them, logs and history are
   redacted (known secret values plus token patterns), and `security secrets` reports
   file/line/type only. New `.env` files get owner-only permissions and are git-ignored.
+- **The agent.** Uses the same engine, policies and approvals as you do, plus path
+  confinement, secret-file protection and redaction of everything sent to the model.
+  Agent actions have policy names (`agent:write`, `agent:exec`, `agent:deploy:<target>` …)
+  so `policies.yaml` can restrict or forbid them.
 - **No claims.** `highhx security` reports concrete findings from local checks. An empty
   report does not mean a project is secure, and HighhX never says it is.
 
@@ -280,12 +431,15 @@ Report vulnerabilities in HighhX itself as described in [SECURITY.md](SECURITY.m
 ## Development
 
 ```bash
-pip install -e ".[dev]"
-pytest                 # unit, integration, security and end-to-end tests
+pip install -e ".[dev]" -e "./server[dev]"
+pytest                 # CLI: unit, integration, security and end-to-end tests
+(cd server && pytest)  # platform API + live CLI ↔ platform integration tests
 ruff check . && ruff format --check .
 mypy                   # strict typing of src/highhx
 ```
 
+The HighhX Platform backend lives in [`server/`](server/README.md).
+
 Architecture: [docs/architecture.md](docs/architecture.md) · Development guide:
 [docs/development.md](docs/development.md) · Troubleshooting: [docs/troubleshooting.md](docs/troubleshooting.md).
 

highhxcli-0.1.0/PKG-INFO → highhxcli-0.3.2/README.md

@@ -1,40 +1,18 @@
-Metadata-Version: 2.5
-Name: highhxcli
-Version: 0.1.0
-Summary: HighhX — a local-first, offline-first developer operations command center.
-Author: HighhX contributors
-License-Expression: MIT
-License-File: LICENSE
-Keywords: automation,cli,developer-tools,devops,workflow
-Classifier: Development Status :: 4 - Beta
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Software Development :: Build Tools
-Requires-Python: >=3.11
-Requires-Dist: click>=8.1
-Requires-Dist: pyyaml>=6.0
-Requires-Dist: rich>=13.7
-Provides-Extra: dev
-Requires-Dist: coverage[toml]>=7.4; extra == 'dev'
-Requires-Dist: mypy>=1.10; extra == 'dev'
-Requires-Dist: pytest>=8.0; extra == 'dev'
-Requires-Dist: ruff>=0.5; extra == 'dev'
-Requires-Dist: types-pyyaml; extra == 'dev'
-Description-Content-Type: text/markdown
-
 # HighhX
 
-**HighhX is a local-first developer command center.** One CLI — `highhx` — detects
+**HighhX is a developer command center for your terminal.** One CLI — `highhx` — detects
 your project, runs your workflows, manages environments, dependencies, tests,
 builds, git, releases, deployments, services and databases, and keeps a searchable
 history of everything it did. Every risky action is classified and needs approval.
 
+| | |
+|---|---|
+| **HighhX Free** | Deterministic HighhX: the full developer CLI plus browser/desktop automation with known targets (`highhx computer`, `highhx do`). Local, no account, no AI. |
+| **HighhX Pro** | Everything in Free plus `highhx agent` — an AI developer agent that plans, changes code, runs your tools, operates browsers and apps (AI computer use), recovers from failures and verifies the result. |
+
+Free and Pro share one execution platform: the same tools, safety policy, confirmations,
+verification and audit trail. The AI only chooses actions; it never gets its own way to run them.
+
 ```text
 $ highhx doctor
 
@@ -58,6 +36,7 @@ Suggested actions
 - [Why HighhX](#why-highhx)
 - [Installation](#installation)
 - [Quick start](#quick-start)
+- [HighhX Pro: the AI developer agent](#highhx-pro-the-ai-developer-agent)
 - [Commands](#commands)
 - [Workflows](#workflows)
 - [Configuration](#configuration)
@@ -72,8 +51,10 @@ Most projects accumulate a pile of scripts, Makefile targets, README snippets an
 CI YAML that only half the team remembers. HighhX gives every project the same
 front door:
 
-- **Local-first and offline-first.** No cloud backend, no account, no API keys, no AI.
-  Everything — history, logs, deployment state — lives in `.highhx/` on your machine.
+- **Local-first CLI.** Every Free command works without an account or network.
+  History, logs and deployment state live in `.highhx/` on your machine.
+- **An AI agent that uses your real tools (Pro).** `highhx agent` works through HighhX's
+  own commands and safety system — not a chatbot pasting shell snippets.
 - **Detects instead of asking.** Python (pip/uv/poetry/pdm/pipenv), Node (npm/pnpm/yarn/bun),
   React, Next.js, Flutter/Dart, Java (Maven/Gradle), C/C++ (CMake/Make), Go, Rust, Docker,
   common databases and monorepos — from real manifests and lockfiles, not file extensions.
@@ -135,12 +116,105 @@ highhx logs            # output of the last execution (secrets redacted)
 └── logs/                # execution logs (git-ignored)
 ```
 
+## HighhX Pro: the AI developer agent
+
+```text
+$ highhx agent
+
+     ▗█▖
+     ▐▀▌
+    ▗ ▄ ▖
+   ▗▚▐█▌▞▖
+  ▗▚█▐█▌█▞▖      HighhX v0.3.0
+   ▟█▐█▌█▙       AI Developer Agent · Pro
+  ▐▐█▌█▐█▌▌      ~/code/shop
+  █▗▜▌█▐▛▖█
+  █▐▙▘█▝▟▌█
+  ▐▐▜▌▄▐▛▌▌
+ ▗▝▐▐▌█▐▌▌▘▖
+ █▙▝█▌█▐█▘▟█
+▜▙▜█▖▘█▝▗█▛▟▛
+ ▀█▟▀ █ ▀▙█▀
+   ▀▌ █ ▐▀
+
+Project   shop
+Stack     Python, FastAPI
+Branch    main
+Status    clean
+AI        Connected HighhX (managed)
+
+What would you like me to do? (/help for commands)
+
+❯ run all the tests and fix whatever fails
+
+╭─ Plan ───────────────────────────────────────────╮
+│  1. Run the test suite                           │
+│  2. Investigate the failures                     │
+│  3. Fix the root cause                           │
+│  4. Re-run tests, lint and type checks           │
+╰─ Get the test suite green ───────────────────────╯
+Proceed? [Y/n]
+
+✓ Run tests — 3 tests failing (4.1s)
+✓ Read src/shop/cart.py — 88 lines
+⚠ Action requires approval
+  Edit src/shop/cart.py (+2 -1)
+  …diff…
+Proceed? [y/N/a=always this session] y
+✓ Edit src/shop/cart.py — +2 -1
+✓ Run tests — Tests passing — 48 passed (pytest) (4.3s)
+✓ Run checks — all checks passed
+
+Fixed the discount rounding in `cart.total()` (it rounded before applying tax).
+All 48 tests pass; lint and type checks are clean.
+
+4 steps  ·  1 file changed (/undo)  ·  38.2k tokens  ·  41s
+```
+
+Ask for what you want in plain language — *explain how this project works*, *find and
+fix the bugs*, *add authentication*, *find security issues*, *why is the application
+crashing?*, *prepare this project for release*, *deploy this*. The agent inspects the
+project, proposes a plan for multi-step work, uses HighhX's capabilities as tools
+(code search and edits, tests, checks, fixers, builds, dependencies, git, security scans,
+doctor/diagnose/repair, workflows, deploy and rollback), verifies what it did and
+summarises it.
+
+- **Same safety system.** Commands run through the HighhX engine: risk classification,
+  `policies.yaml`, approvals and history. File edits show a diff and ask (unless you
+  choose `--mode auto-edit`); pushes, deploys and rollbacks always ask; production
+  deploys need typed confirmation. The agent cannot leave the project, read secret files
+  or touch `.git/`. `--mode read-only` investigates without changing anything.
+- **Slash commands.** `/help` `/status` `/plan` `/context` `/model` `/mode` `/history`
+  `/changes` `/undo` `/memory` `/usage` `/clear` `/quit`.
+- **Sessions.** Saved per project: `highhx agent --continue`, `--resume ID`, `highhx agent sessions`.
+- **Scriptable.** `highhx agent "…"` outside a terminal (or with `--json`) handles one request
+  and exits — `--yes --mode auto-edit` for unattended runs in CI.
+- **Providers.** All Pro AI goes through the HighhX platform (authenticated, plan-checked,
+  metered); choose the upstream — Anthropic, OpenAI or Gemini — with `highhx account settings`
+  or `/model`. No provider key is needed on your machine.
+- **Kill switch.** `highhx agent stop` (or Ctrl+C) cancels the model request, retries, running
+  commands and their child processes immediately.
+- **Computer use.** The agent observes browsers and apps semantically and chooses among valid
+  actions; see [docs/computer-use.md](docs/computer-use.md).
+
+```bash
+highhx login                 # browser sign-in (creates your account)
+highhx account upgrade       # HighhX Pro checkout
+highhx agent                 # interactive
+highhx agent "why is the application crashing?"
+```
+
+Guides: [docs/agent.md](docs/agent.md) · [docs/computer-use.md](docs/computer-use.md) · [docs/platform.md](docs/platform.md).
+
 ## Commands
 
 Full reference with every option: [docs/commands.md](docs/commands.md).
 
 | Area | Commands |
 |---|---|
+| HighhX Pro | `agent` `agent sessions` `agent models` `agent stop` |
+| Automation (no AI) | `do` `computer status/open/observe/click/type/select/press/scroll/run` `computer browser start/stop` |
+| Account | `login` `logout` `account` `account plans/usage/upgrade/billing/settings` |
 | Project | `init` `status` `info` `dev` `start` `stop` `restart` `check` |
 | Code & tasks | `run <workflow>` `exec <command>` `script <name>` `task <name>` `watch` `fix` |
 | Dependencies | `deps` `deps install` `deps update` `deps outdated` `deps audit` `deps clean` |
@@ -151,7 +225,7 @@ Full reference with every option: [docs/commands.md](docs/commands.md).
 | Security | `security` `security scan/secrets/deps/config/report` |
 | Containers & data | `docker up/down/logs` `services` `ports` `db status/migrate/seed/backup/restore` |
 | Workflows & automation | `workflow list/validate/create/graph` `schedule` `hook` `trigger` `watchers` |
-| Observability | `logs [--follow]` `history [id]` `report` `trace` |
+| Observability | `logs [--follow]` `history [id]` `audit` `report` `trace` |
 | Extensibility & team | `plugin list/install/remove/update/search/trust` `config` `policy` `workspace` `profile` |
 | Diagnostics | `doctor` `diagnose` `repair` `debug` |
 
@@ -302,6 +376,10 @@ Details: [docs/security.md](docs/security.md).
 - **Secrets.** Secret values are never printed: `env` masks them, logs and history are
   redacted (known secret values plus token patterns), and `security secrets` reports
   file/line/type only. New `.env` files get owner-only permissions and are git-ignored.
+- **The agent.** Uses the same engine, policies and approvals as you do, plus path
+  confinement, secret-file protection and redaction of everything sent to the model.
+  Agent actions have policy names (`agent:write`, `agent:exec`, `agent:deploy:<target>` …)
+  so `policies.yaml` can restrict or forbid them.
 - **No claims.** `highhx security` reports concrete findings from local checks. An empty
   report does not mean a project is secure, and HighhX never says it is.
 
@@ -310,12 +388,15 @@ Report vulnerabilities in HighhX itself as described in [SECURITY.md](SECURITY.m
 ## Development
 
 ```bash
-pip install -e ".[dev]"
-pytest                 # unit, integration, security and end-to-end tests
+pip install -e ".[dev]" -e "./server[dev]"
+pytest                 # CLI: unit, integration, security and end-to-end tests
+(cd server && pytest)  # platform API + live CLI ↔ platform integration tests
 ruff check . && ruff format --check .
 mypy                   # strict typing of src/highhx
 ```
 
+The HighhX Platform backend lives in [`server/`](server/README.md).
+
 Architecture: [docs/architecture.md](docs/architecture.md) · Development guide:
 [docs/development.md](docs/development.md) · Troubleshooting: [docs/troubleshooting.md](docs/troubleshooting.md).