From 1e3fd3c3f51d0c3f38718c8479005d4dd3580749 Mon Sep 17 00:00:00 2001 From: Ruslan Strazhnyk Date: Tue, 4 Aug 2026 14:17:17 +0200 Subject: [PATCH] docs: correct the version story and add diagrams for orchestration, lifecycle, and family MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README's headline section was titled "What is new in v1.21" while the latest release is v1.22.1, and it listed `--local` standalone mode among the v1.21 items even though the CHANGELOG puts it in v1.22.0. Split the section by release and attribute each feature correctly. v1.22.1's cloud MCP routing fix was not mentioned anywhere in the README. It is the reason tool calls made through the local MCP server are now visible to the platform at all, so it belongs in the headline list rather than only the changelog. docs/COMMANDS.md carried the same stale v1.21 reference. Add three SVG diagrams, sharing the house style used by the qmax-mcp architecture diagram so the org's repos read as one family: - orchestration.svg replaces the ASCII flow in the README. It makes the point the prose has to work hardest to convey: the picker chooses a backend, but mode — not backend — decides which tools exist. The equivalent ASCII tree already lives in docs/ORCHESTRATION.md, so nothing is lost for plain-text readers. - lifecycle.svg gives the "what qmax-code can do" bullets a shape, and shows which lane survives in standalone mode. - family.svg places qmax-code among free-qa-skills, qmax-mcp, 9lives, and qmax-local-agent. That positioning existed nowhere public. Also add a release badge and pin the Go badge to 1.24+, matching the build requirement already stated under Install. --- README.md | 49 ++++++++++++++++---------- docs/COMMANDS.md | 2 +- docs/img/family.svg | 59 +++++++++++++++++++++++++++++++ docs/img/lifecycle.svg | 60 +++++++++++++++++++++++++++++++ docs/img/orchestration.svg | 72 ++++++++++++++++++++++++++++++++++++++ 5 files changed, 223 insertions(+), 19 deletions(-) create mode 100644 docs/img/family.svg create mode 100644 docs/img/lifecycle.svg create mode 100644 docs/img/orchestration.svg diff --git a/README.md b/README.md index 4e54acb..cb00b3e 100644 --- a/README.md +++ b/README.md @@ -15,9 +15,10 @@ # qmax-code +[![Latest release](https://img.shields.io/github/v/release/Quality-Max/qmax-code?label=release&color=217a45)](https://github.com/Quality-Max/qmax-code/releases/latest) [![License: FSL-1.1-ALv2](https://img.shields.io/badge/license-FSL--1.1--ALv2-2ea44f.svg)](LICENSE) [![Future License: Apache 2.0](https://img.shields.io/badge/future%20license-Apache%202.0-blue.svg)](LICENSE) -[![Made with Go](https://img.shields.io/badge/made%20with-Go-00ADD8.svg)](https://go.dev/) +[![Made with Go](https://img.shields.io/badge/made%20with-Go%201.24+-00ADD8.svg)](https://go.dev/) [![Announcement](https://img.shields.io/badge/announcement-2026--05--01-7c6cf0.svg)](https://qualitymax.io/blog/qmax-code-open-source) [![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-support-yellow?logo=buymeacoffee)](https://buymeacoffee.com/qualitymax) @@ -34,6 +35,16 @@ Use the built-in agent with Anthropic, Cerebras, or Ollama, or use **orchestration mode** to run Claude Code, Codex, or OpenCode with the same qmax QA tools through MCP. +![Five open QualityMax tools and where qmax-code sits among them](docs/img/family.svg) + +qmax-code is the terminal agent that drives a QA session. It sits alongside +[free-qa-skills](https://github.com/Quality-Max/free-qa-skills) (read-only +audits inside a coding agent), [qmax-mcp](https://github.com/Quality-Max/qmax-mcp) +(scan a page, generate a repro, run it locally), +[9lives](https://github.com/Quality-Max/9lives) (heal broken selectors), and +[qmax-local-agent](https://github.com/Quality-Max/qmax-local-agent) (let the +cloud reach a private network). Only hosted QualityMax needs an account. + > **License:** Source-available under the > [Functional Source License (FSL-1.1-ALv2)](LICENSE), created by > [Sentry](https://fsl.software). It is free for non-competing use, including @@ -42,6 +53,8 @@ QA tools through MCP. ## What qmax-code can do +![Plan, generate, execute, review, and ship, over a local repository lane](docs/img/lifecycle.svg) + - **Plan and manage QA work:** list and manage projects and test cases, enhance cases, find coverage gaps, and import requirements or repositories. - **Generate and execute tests:** create Playwright, pytest, Go, and Rust tests; @@ -64,11 +77,24 @@ Some advanced surfaces—k6, QTML, framework export/trigger operations, and background-job health—remain experimental and are only exposed when `QMAX_EXPERIMENTAL=1`. -## What is new in v1.21 +## What is new + +### v1.22 -- **Standalone local-only mode:** start with `--local` (or persist +- **Cloud-routed MCP tool calls (v1.22.1):** `serve --mcp` now routes + authenticated QualityMax tool calls through the cloud MCP endpoint instead of + calling the REST API directly. Calls made through the local MCP server were + previously invisible to the platform — they set no trace context, so they + produced no session history — and they returned UI-shaped REST payloads + carrying every script's full source. Browser login now mints an + MCP-compatible token, so the routing works immediately after sign-in. +- **Standalone local-only mode (v1.22.0):** start with `--local` (or persist `local_only=true`) to skip QualityMax onboarding and expose only workspace - file, command, and planning tools. + file, command, and planning tools. MCP children inherit the mode, and + execution-time checks reject direct calls to hidden QualityMax tools. + +### v1.21 + - **Exposure Receipts:** every session that makes an outbound LLM or QualityMax API request writes a signed local egress manifest that can be inspected and verified offline. @@ -188,20 +214,7 @@ a separate model and it does not create several agents. It selects which inference engine handles the conversation while keeping qmax-code as the host for terminal UX, QualityMax context, and tools. -```text -you - │ - ▼ -qmax-code REPL ── /orch chooses one backend - │ - ├─ built-in loop: Anthropic API / Cerebras / Ollama - │ - └─ CLI agent: Claude Code / Codex / OpenCode - │ - └─ embedded qmax MCP server - ├─ connected: QualityMax + local QA tools - └─ --local: workspace tools only -``` +![The /orch picker selects one backend; mode decides which tools exist](docs/img/orchestration.svg) For CLI backends, qmax-code launches the selected agent as a subprocess and serves qmax tools through its embedded MCP server. On first activation you diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index 5c01fac..0ea06d9 100644 --- a/docs/COMMANDS.md +++ b/docs/COMMANDS.md @@ -1,6 +1,6 @@ # Command reference -This reference describes the qmax-code v1.21 command-line and interactive +This reference describes the qmax-code v1.22 command-line and interactive surfaces. Run `qmax-code --help` for the flags compiled into your installed version and `/help` for its REPL commands. diff --git a/docs/img/family.svg b/docs/img/family.svg new file mode 100644 index 0000000..363a33e --- /dev/null +++ b/docs/img/family.svg @@ -0,0 +1,59 @@ + + Where qmax-code sits among the QualityMax tools + free-qa-skills audits, qmax-mcp proves one change, 9lives repairs broken tests, qmax-code orchestrates the session from a terminal, qmax-local-agent gives the cloud reach into a private network, and hosted QualityMax manages the QA program. Only the hosted service requires an account. + + + Five open tools, one QA program + + + AUDIT + free-qa-skills + 27 read-only QA skills, run + inside a coding agent + + + PROVE + qmax-mcp + scan a page, generate a repro, + run it locally. No account. + + + REPAIR + 9lives + heal broken selectors and + show a diff for approval + + + ORCHESTRATE — YOU ARE HERE + qmax-code + the terminal agent that drives + the session, connected or local + + + REACH + qmax-local-agent + lets the cloud run tests inside + a private network or CI runner + + + MANAGE — ACCOUNT REQUIRED + Hosted QualityMax + projects, suites, runs, + and observability + + Skills find issues · qmax-mcp proves a change · 9lives repairs the test · qmax-code runs the session · hosted QualityMax keeps the program + Everything except the amber card works without a QualityMax account. + diff --git a/docs/img/lifecycle.svg b/docs/img/lifecycle.svg new file mode 100644 index 0000000..e4e1fbe --- /dev/null +++ b/docs/img/lifecycle.svg @@ -0,0 +1,60 @@ + + What qmax-code covers across the QA lifecycle + Five connected stages — plan, generate, execute, review, ship — sitting on top of a local repository lane that also works without a QualityMax account. + + + + + + + + One agent across the QA lifecycle + + + PLAN + projects and test cases + coverage gaps + requirement imports + + + + GENERATE + Playwright · pytest + Go · Rust + from crawls or cases + + + + EXECUTE + cloud browser runs + native Go/Rust runner + or locally + + + + REVIEW + quality and coverage + security and risk + saved preferences + + + + SHIP + open test PRs + generate a GitHub + Actions workflow + + + Local repository lane — read, edit, search, run allowlisted commands and tests + This lane is what standalone --local mode keeps. The stages above need a QualityMax connection. + diff --git a/docs/img/orchestration.svg b/docs/img/orchestration.svg new file mode 100644 index 0000000..1207f06 --- /dev/null +++ b/docs/img/orchestration.svg @@ -0,0 +1,72 @@ + + qmax-code orchestration mode + The /orch picker selects one inference backend for a qmax-code turn: the built-in agent loop running Anthropic, Cerebras, or Ollama, or a CLI subprocess running Claude Code, Codex, or OpenCode, which receives qmax tools through an embedded MCP server. Connected or standalone mode decides which tools exist, independently of the backend. + + + + + + + + One picker. Six backends. The same qmax tools. + + + you + + + + + qmax-code REPL + terminal UX · tool policy · QualityMax context + + + + + /orch + backend · model · effort + + + + + + BUILT-IN AGENT LOOP + + Anthropic API + + Cerebras + + Ollama + qmax-code runs the tool loop itself + + + CLI SUBPROCESS + + Claude Code + + Codex + + OpenCode + qmax tools arrive through the embedded MCP server + + + + + + WHICH TOOLS EXIST IS SET BY MODE, NOT BY BACKEND + connected: QualityMax + local QA tools · --local: workspace tools only +