procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/webplatform/aat_mcp/tests/test_protocol.py

@@ -0,0 +1,180 @@
+"""Protocol behaviour both MCP surfaces must share: version negotiation and the 2026-07-28 era.
+
+Two eras of MCP coexist. Legacy clients (2025-11-25 and earlier) open with an `initialize`
+handshake. Modern clients (2026-07-28) send no handshake at all: every request carries its
+protocol version in `_meta`, and servers MUST implement `server/discover`. A server may serve
+both, which the spec calls dual-era. A modern-only stdio server would fail every legacy
+client, because legacy clients have no way to fall forward, so dual-era is the target here.
+
+What these pin, and why each one matters:
+
+- **A server must never agree to a version it does not implement.** Both servers used to
+  echo whatever a client asked for, including `1999-01-01`. Every MCP revision since
+  2024-11-05 requires the server to answer with a version IT supports. A client that asks
+  for `2026-07-28` inside `initialize` (one Claude Code release briefly did) would have been
+  told yes, and would then expect fields the server never sends.
+- **Modern results carry `resultType`, and list results carry `ttlMs` and `cacheScope`.**
+- **An unsupported modern version gets `-32022` with the list of supported versions.**
+  That code is what tells a dual-era client the server is modern and it should retry,
+  rather than fall back to `initialize`.
+- **The HTTP transport stays legacy-only.** Modern Streamable HTTP adds header rules
+  (`Mcp-Method`, `Mcp-Name`) that transport does not implement, so advertising the modern
+  era over it would claim more than it does.
+"""
+from __future__ import annotations
+
+import ast
+import hashlib
+import json
+import re
+from pathlib import Path
+
+import pytest
+
+import chat_server
+import server
+
+MODERN = "2026-07-28"
+LEGACY_LATEST = "2025-11-25"
+LEGACY_SUPPORTED = ("2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05")
+META_VERSION = "io.modelcontextprotocol/protocolVersion"
+META_SERVER_INFO = "io.modelcontextprotocol/serverInfo"
+DIGEST_KEY = "com.procesio/toolsDigest"
+HERE = Path(__file__).resolve().parents[1]
+
+SURFACES = [pytest.param(server, id="full-surface"), pytest.param(chat_server, id="chat-surface")]
+
+
+def _legacy(method, params=None, id_=1):
+    req = {"jsonrpc": "2.0", "id": id_, "method": method}
+    if params is not None:
+        req["params"] = params
+    return req
+
+
+def _modern(method, params=None, version=MODERN, id_=1):
+    p = dict(params or {})
+    p["_meta"] = {META_VERSION: version, "io.modelcontextprotocol/clientInfo": {"name": "t", "version": "0"}}
+    return {"jsonrpc": "2.0", "id": id_, "method": method, "params": p}
+
+
+# --- 1. version negotiation (the echo bug) --------------------------------------------------
+
+@pytest.mark.parametrize("surface", SURFACES)
+@pytest.mark.parametrize("asked", ["1999-01-01", "2099-12-31", MODERN])
+def test_initialize_never_agrees_to_a_version_it_does_not_implement(surface, asked):
+    got = surface.handle(_legacy("initialize", {"protocolVersion": asked}))["result"]["protocolVersion"]
+    assert got != asked, f"agreed to {asked!r}, which this server does not implement over initialize"
+    assert got == LEGACY_LATEST
+
+
+@pytest.mark.parametrize("surface", SURFACES)
+@pytest.mark.parametrize("asked", LEGACY_SUPPORTED)
+def test_initialize_honours_a_legacy_version_it_supports(surface, asked):
+    assert surface.handle(_legacy("initialize", {"protocolVersion": asked}))["result"]["protocolVersion"] == asked
+
+
+@pytest.mark.parametrize("surface", SURFACES)
+def test_initialize_with_no_version_gets_the_latest_legacy_one(surface):
+    assert surface.handle(_legacy("initialize", {}))["result"]["protocolVersion"] == LEGACY_LATEST
+
+
+# --- 3. the 2026-07-28 era -------------------------------------------------------------------
+
+@pytest.mark.parametrize("surface", SURFACES)
+def test_server_discover_advertises_the_modern_era(surface):
+    r = surface.handle(_modern("server/discover"))["result"]
+    assert r["resultType"] == "complete"
+    assert r["supportedVersions"] == [MODERN]
+    assert "tools" in r["capabilities"]
+    assert r["_meta"][META_SERVER_INFO]["name"]
+    assert r["ttlMs"] > 0 and r["cacheScope"] == "public"
+
+
+@pytest.mark.parametrize("surface", SURFACES)
+def test_a_modern_tool_list_carries_the_required_fields_and_the_same_tools(surface):
+    modern = surface.handle(_modern("tools/list"))["result"]
+    legacy = surface.handle(_legacy("tools/list"))["result"]
+    assert modern["resultType"] == "complete"
+    assert modern["ttlMs"] > 0 and modern["cacheScope"] == "public"
+    assert modern["_meta"][META_SERVER_INFO]["name"]
+    assert modern["tools"] == legacy["tools"], "the two eras must publish one contract"
+
+
+@pytest.mark.parametrize("surface", SURFACES)
+def test_the_legacy_shape_is_unchanged(surface):
+    """Legacy clients get exactly what they got before: no modern-only fields."""
+    legacy = surface.handle(_legacy("tools/list"))["result"]
+    assert set(legacy) == {"tools"}
+
+
+@pytest.mark.parametrize("surface", SURFACES)
+def test_a_modern_tool_call_is_marked_complete(surface):
+    r = surface.handle(_modern("tools/call", {"name": "procesio_not_a_tool", "arguments": {}}))["result"]
+    assert r["resultType"] == "complete"
+    assert r["isError"] is True
+
+
+@pytest.mark.parametrize("surface", SURFACES)
+@pytest.mark.parametrize("method", ["tools/list", "server/discover", "tools/call"])
+def test_an_unsupported_modern_version_is_refused_with_what_is_supported(surface, method):
+    resp = surface.handle(_modern(method, version="2099-01-01"))
+    assert resp["error"]["code"] == -32022
+    assert resp["error"]["data"] == {"supported": [MODERN], "requested": "2099-01-01"}
+
+
+@pytest.mark.parametrize("surface", SURFACES)
+def test_legacy_server_discover_is_still_method_not_found_when_modern_is_off(surface):
+    """A plain -32601 is the answer a dual-era client reads as 'legacy server, fall back'.
+    A version-gated message here is what made one public MCP server unusable in Claude Code."""
+    resp = surface.handle(_modern("server/discover"), modern=False)
+    assert resp["error"]["code"] == -32601
+
+
+def test_the_http_transport_serves_the_legacy_era_only():
+    src = (HERE / "http_server.py").read_text(encoding="utf-8")
+    assert re.search(r"server\.handle\(\s*m\s*,\s*modern\s*=\s*False\s*\)", src), (
+        "http_server.py must call server.handle(m, modern=False): it does not implement the "
+        "Streamable HTTP header rules the modern era requires")
+
+
+# --- 4. a pinnable digest of the published tool surface -------------------------------------
+
+def _canonical_digest(tools) -> str:
+    raw = json.dumps(tools, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+    return "sha256:" + hashlib.sha256(raw).hexdigest()
+
+
+def test_the_digest_is_the_documented_canonical_hash():
+    import protocol
+    tools = chat_server.TOOLS
+    assert protocol.tools_digest(tools) == _canonical_digest(tools)
+
+
+def test_the_published_snapshot_has_the_digest_the_server_reports():
+    """The snapshot ships in the public repo and its digest goes into server.json. A client
+    or gateway can therefore hash the tool list it actually received and compare it with a
+    value the server cannot change after publication. The self-report is a convenience, not
+    the control: the spec says self-reported server info must not drive security decisions."""
+    snapshot = json.loads((HERE / "chat_surface.snapshot.json").read_text(encoding="utf-8"))
+    reported = chat_server.handle(_modern("server/discover"))["result"]["_meta"][DIGEST_KEY]
+    assert reported == _canonical_digest(snapshot)
+
+
+def test_any_change_to_a_tool_changes_the_digest():
+    import protocol
+    tools = json.loads(json.dumps(chat_server.TOOLS))
+    before = protocol.tools_digest(tools)
+    tools[0]["description"] += " "
+    assert protocol.tools_digest(tools) != before
+
+
+def test_the_protocol_module_depends_on_nothing_but_the_standard_library():
+    tree = ast.parse((HERE / "protocol.py").read_text(encoding="utf-8"))
+    names = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            names |= {a.name.split(".")[0] for a in node.names}
+        elif isinstance(node, ast.ImportFrom) and node.module and node.level == 0:
+            names.add(node.module.split(".")[0])
+    assert names <= {"__future__", "hashlib", "json", "sys", "typing", "collections"}, names

procesio_cli/webplatform/aat_mcp/tests/test_skill_discovery.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+import bridge
+from tools._lib.skill_resources import SkillResourceError
+
+
+def test_get_skill_exposes_index_and_resource_read(monkeypatch, tmp_path):
+    root = tmp_path / "demo"
+    (root / "references").mkdir(parents=True)
+    (root / "SKILL.md").write_text("---\nname: demo\ndescription: demo\n---\n# Demo\n")
+    (root / "references" / "guide.md").write_text("guide", encoding="utf-8")
+    monkeypatch.setattr(bridge.registry, "get_skill",
+                        lambda name: SimpleNamespace(name=name, path=root))
+    skill = bridge.get_skill("demo")
+    assert skill["resources"]["references"] == ["references/guide.md"]
+    resource = bridge.get_skill_resource("demo", "references/guide.md")
+    assert resource["resource"]["content"] == "guide"
+    with pytest.raises(SkillResourceError):
+        bridge.get_skill_resource("demo", "../outside")

procesio_cli-0.1.1.dist-info/METADATA

@@ -0,0 +1,467 @@
+Metadata-Version: 2.5
+Name: procesio-cli
+Version: 0.1.1
+Summary: Command-line tooling and an AI agent for the PROCESIO automation platform: drive processes, forms, documents and custom actions from a terminal or from an AI coding assistant.
+Project-URL: Homepage, https://procesio.com
+Project-URL: Documentation, https://docs.procesio.com
+Project-URL: Repository, https://github.com/Procesio-Externals/procesio-cli
+Project-URL: Issues, https://github.com/Procesio-Externals/procesio-cli/issues
+Project-URL: Changelog, https://github.com/Procesio-Externals/procesio-cli/blob/main/CHANGELOG.md
+Author: Ringhel TEAM SRL (PROCESIO)
+License: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: agent,automation,cli,ipaas,low-code,mcp,procesio,workflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42.0
+Requires-Dist: jsonschema>=4.20
+Requires-Dist: keyring>=24.0
+Requires-Dist: pydantic>=2.5
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.31
+Provides-Extra: browser
+Requires-Dist: beautifulsoup4>=4.12; extra == 'browser'
+Requires-Dist: lxml>=5.0; extra == 'browser'
+Requires-Dist: playwright>=1.60.0; extra == 'browser'
+Requires-Dist: pymupdf>=1.24; extra == 'browser'
+Requires-Dist: pypdf>=6.15.0; extra == 'browser'
+Provides-Extra: databases
+Requires-Dist: pymysql>=1.1; extra == 'databases'
+Requires-Dist: pyodbc>=5.1; extra == 'databases'
+Provides-Extra: excel
+Requires-Dist: openpyxl>=3.1; extra == 'excel'
+Description-Content-Type: text/markdown
+
+# PROCESIO CLI + Agent
+
+<!-- mcp-name: io.github.Procesio-Externals/procesio-cli -->
+
+Command-line tooling and an AI agent for the PROCESIO automation platform: drive processes, forms, documents and custom actions from a terminal or from an AI coding assistant.
+
+Everything here talks to a PROCESIO installation over its public API. You point it at
+your workspace, store your credentials in your operating system's own secret store,
+and drive processes, forms, documents and custom actions from a terminal, a script, or
+an AI coding assistant.
+
+- The platform this talks to, where your workspaces live: https://procesio.app
+- API and platform documentation: https://docs.procesio.com
+- About PROCESIO: https://procesio.com
+
+## Install
+
+Requires Python 3.11. [uv](https://docs.astral.sh/uv/) is the quickest
+route, but a plain virtualenv works the same way.
+
+```bash
+git clone https://github.com/Procesio-Externals/procesio-cli.git
+cd procesio-cli
+uv sync
+```
+
+The base install is six packages. Everything heavier is an optional extra, pulled
+in only if you use the tool that needs it:
+
+```bash
+uv sync --extra browser      # real-browser form testing (then: uv run playwright install chromium)
+uv sync --extra excel        # reading .xlsx workbooks
+uv sync --extra databases    # SQL Server / MySQL queries (pyodbc also needs an ODBC driver)
+uv sync --all-extras         # everything
+```
+
+## Connect it to your workspace
+
+Credentials never live in a file in this repo. They go into your machine's own store:
+Windows Credential Manager, the macOS login Keychain, or the Linux desktop keyring,
+all under the name `agents-and-tools:procesio:<secret>`.
+
+PROCESIO accepts two ways of authenticating, and they are not equivalent. Store either
+one as a named profile:
+
+```bash
+# Your user account. Carries everything that account can do.
+python scripts/run-tool.py procesio add-credential --name account --type userpass     --username you@example.com --make-default
+
+# An API key, scoped to one workspace.
+python scripts/run-tool.py procesio add-credential --name qa --type apikey     --workspace-id <workspace-guid>
+
+python scripts/run-tool.py procesio check-auth
+```
+
+Omit `--password`, `--key` or `--value` and you are prompted without echoing, so the
+secret never reaches your shell history or a process listing. Add
+`--environment <Client>-<ENV>` to bind a profile to a specific installation.
+
+### Which one to use
+
+| | User and password | API key |
+|---|---|---|
+| Reaches | everything the account can reach, across workspaces | one workspace |
+| Needs a workspace GUID | no | yes, its own, and no other will do |
+| Good for | day-to-day building, anything that spans workspaces | CI, a script pinned to one environment, sharing narrow access |
+
+The scoping is enforced by the platform, not by this tool. A workspace-scoped key sends
+three headers: the key name, the key value, and `workspaceid`. Send it without that
+header and the call is a `401`; send it with a **different** workspace's GUID and it is
+also a `401`. So an api-key profile has to be stored with its `workspace_id` to
+authenticate at all. `python scripts/run-tool.py procesio list-workspaces` gives you the
+GUID.
+
+The practical consequence is worth knowing before you pick. A user profile reaches
+endpoints an API key cannot: listing a master workspace's sub-workspaces, for example,
+answers `401` for a key and `200` for a user. Prefer the user account while you are
+building, and reach for a key when you deliberately want to pin something to a single
+workspace.
+
+On a headless machine there is no OS keyring to write to. Pick a store explicitly:
+
+```bash
+export AAT_CREDS_BACKEND=encrypted-file
+export AAT_SECRETS_PASSPHRASE='...'      # or you will be prompted on a terminal
+python scripts/set-credential.py procesio username
+```
+
+`AAT_CREDS_BACKEND=file` and `=env` read secrets your host or cluster already manages
+(a mounted Kubernetes Secret, or one JSON blob) and are read-only by design, so a
+container can never pretend to own the store it reads from.
+
+## First commands
+
+```bash
+python scripts/list-tools.py                       # what is installed, and is it ready
+python scripts/run-tool.py procesio --help         # every action, with its arguments
+python scripts/run-tool.py procesio list-processes
+python scripts/run-tool.py procesio run-process --id <process-id> --payload '{}'
+```
+
+Every tool prints exactly one JSON object on stdout and nothing else, so you can pipe
+it straight into `jq` or into another script. Progress and warnings go to stderr.
+Failures print `{"error": {"code", "message", "details"}}` and exit non-zero.
+
+## Using it from an AI assistant
+
+This repo is built to be discovered rather than memorised, which is what makes it
+usable by an assistant that has never seen it before.
+
+- `CLAUDE.md` carries a generated **capability router**: a compact map from "what the
+  user asked for" to the exact command that does it. It is regenerated from the
+  manifests with `python scripts/build-router.py`, so it cannot drift from the code.
+- `tools/procesio/SKILL.md` is the tool's full manual, also generated from its
+  manifest. An assistant reads it instead of guessing at `--help` output.
+- `python scripts/list-tools.py` returns the same information as JSON, including which
+  credentials are missing, so an assistant can tell "not installed" from "not
+  configured yet".
+
+Point your assistant at the repo root and let it run `scripts/run-tool.py`. Nothing
+else is required.
+
+### Or install it into Claude Code as a plugin
+
+One command, and Claude Code carries the tools, the MCP server and the Agent Skills
+together. No clone, no path to write into a config file.
+
+```
+/plugin marketplace add Procesio-Externals/procesio-cli
+/plugin install procesio@procesio-cli
+```
+
+The plugin is the `plugin/` folder: the MCP server configuration, four skills and an
+icon. It launches the exact PyPI release of this package through `uvx`, so
+[uv](https://docs.astral.sh/uv/) has to be on the machine; everything else it resolves
+itself on first run. Authenticate with `add-credential` below, run as
+`uvx --from procesio-cli procesio add-credential ...` when there is no clone.
+
+**What gets installed is pinned.** The plugin names one exact release and passes
+`constraints.txt` and `build-constraints.txt` to `uvx`, so a fresh launch installs exactly the versions that
+were resolved and checked for this release, not whatever is newest on PyPI that day. The
+pins are checked to have prebuilt wheels for Python 3.11 to 3.14 on Windows, Linux
+(x86-64 and ARM) and Apple Silicon. Intel Macs are not covered: `cryptography` no longer
+publishes wheels for them, so installing there needs a Rust toolchain.
+
+**On Windows with Smart App Control.** Windows 11 can refuse to load a Python file
+whose publisher it cannot confirm, and shows "Part of this app has been blocked" for
+each one. The Python builds uv downloads for itself are not signed, so the plugin asks
+uv for a Python that is already installed first (`--python-preference system`, never
+older than 3.11) and uses uv's own build only when there is none. If
+you see those notifications, install Python 3.11 or newer from
+[python.org](https://www.python.org/downloads/windows/) (for example
+`winget install Python.Python.3.12`), whose files are signed, then restart Claude Code.
+Do not ignore them: when the refused file is Python's networking module, no tool call
+can reach PROCESIO.
+
+**You can check the tool list you were given.** The MCP server's published tools are
+fixed per release, and `server.json` records their digest under
+`_meta` > `io.modelcontextprotocol.registry/publisher-provided` > `com.procesio/toolsDigest`.
+That file cannot be changed once a version is in the MCP Registry. Hash the `tools` array
+a `tools/list` call returns and compare:
+
+```python
+import hashlib, json
+raw = json.dumps(tools, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+print("sha256:" + hashlib.sha256(raw.encode("utf-8")).hexdigest())
+```
+
+A mismatch means the server is not offering what was published for that version. The
+server also reports its digest in `server/discover`, but treat that only as a label: a
+server cannot vouch for itself.
+
+### Or connect it over MCP, with no shell at all
+
+There are two MCP servers in `webplatform/aat_mcp/`, over the same substrate, for two
+different jobs. Both speak JSON-RPC over stdio.
+
+| | `procesio-mcp-chat` | `procesio-mcp` |
+|---|---|---|
+| tools | 21, one per operation | 6, generic |
+| picks up a tool you add | no, it is a declared list | yes, immediately |
+| what it is for | a chat client, where each tool has to say what it does | driving the whole registry |
+| launched by | the plugin, via `.mcp.json` | your own client config |
+
+**From the MCP Registry, or as a one-click bundle.** The chat server is listed in the
+official MCP Registry as `io.github.Procesio-Externals/procesio-cli`, and each release attaches
+`procesio-mcp-<version>.mcpb` to its
+[GitHub release](https://github.com/Procesio-Externals/procesio-cli/releases). Open that file in
+Claude Desktop to install it; the host fetches the Python dependencies with uv. Both are
+produced by the tag-driven `release` workflow, which fills in the bundle's hash and
+publishes `server.json`, so nothing in the registry is edited by hand.
+
+The curated surface is grouped by what you are building — processes, forms, connectors —
+and nothing in it takes a caller-supplied action, so every tool in the list is legible to
+a person reading it and to a model choosing between them. Its contents are declared in
+`webplatform/aat_mcp/chat_surface.yaml`, and CI checks that every operation it names still
+exists with the arguments it claims.
+
+The generic surface is the one to reach for when you want reach rather than a short list.
+It exposes the whole registry through six tools rather than one per action:
+
+| tool | what it does |
+|---|---|
+| `capabilities` | list tools, agents and skills, or one capability's full argument schema |
+| `run_tool` | run a tool with structured JSON arguments |
+| `run_agent` | run an agent |
+| `run_tool_confirmed`, `run_agent_confirmed` | the same, including irreversible actions |
+| `get_skill` | fetch a skill's markdown |
+
+Because it reads the registry, a tool you add next to `tools/procesio/` appears in
+your assistant immediately, with its argument schema, and you write no integration
+code for it.
+
+Point your MCP client at the server with an absolute path to this checkout's Python:
+
+```json
+{
+  "mcpServers": {
+    "procesio": {
+      "command": "/abs/path/to/procesio-cli/.venv/bin/python",
+      "args": ["/abs/path/to/procesio-cli/webplatform/aat_mcp/server.py"]
+    }
+  }
+}
+```
+
+On Windows the interpreter is `.venv\Scripts\python.exe`. The key name differs per
+client (`mcpServers` for Claude Desktop and Cursor, `mcp` with `"type": "local"` for
+opencode), but the command and args are the same everywhere. For a container there is
+also an HTTP transport: `python webplatform/aat_mcp/http_server.py --host 0.0.0.0
+--port 8901 --token <secret>`, which requires `Authorization: Bearer <secret>` on
+every request. Do not bind it off loopback without a token.
+
+**About the safety gate.** `run_tool` refuses an action the reversibility check calls
+irreversible and returns `approval_required`, naming the `*_confirmed` path. MCP
+clients mark those as ask, so a person approves each side effect and a model cannot
+bypass the gate by picking the plain tool. Know what the check is: it matches English
+verbs in the action name and arguments. An action whose name carries no verb it knows
+comes back reversible, so silence is absence of evidence rather than a guarantee.
+Treat it as a guard rail against obvious mistakes, not as a sandbox, and add verbs to
+`agents/_lib/reversibility.py` when you find a gap. Set `AAT_MCP_DENY_IRREVERSIBLE`
+for a headless run where even confirmed actions must be refused.
+
+## The rules that are not obvious
+
+Before you build anything, read
+[`tools/procesio/PROCESIO-USAGE-GUIDE.md`](tools/procesio/PROCESIO-USAGE-GUIDE.md). It
+indexes the platform behaviours that read as failures until you know them, and they all
+share a shape: the call succeeds, the status says finished, nothing is logged, and the
+thing you asked for did not happen. There is no error to search for, so you look in the
+wrong place.
+
+A few of them, so you can judge whether it is worth your time: `<%N%>` in a Node pastes
+the value into the source rather than binding it, so a string becomes a subtraction; the
+Python action returns only what the script PRINTS, so an assignment returns empty; and an
+empty form control bound to a typed variable kills the launch with nothing on screen at
+all.
+
+The guide is generated from the tool's own notes, carries the rule and a link, and the
+reasoning stays in the note. One copy of every fact.
+
+## The agent
+
+Beyond the raw API tool there is a build-and-test agent that carries the method rather
+than the mechanics: how to build a process properly, how to verify it against a live
+run, and which smells to look for in someone else's flow.
+
+```bash
+python scripts/run-agent.py procesio guidance          # the playbook and best practices
+python scripts/run-agent.py procesio checklist         # the self-test discipline
+python scripts/run-agent.py procesio verify --process-id <id>
+python scripts/run-agent.py procesio audit --process-id <id>
+```
+
+`verify` is the one worth wiring into CI: it validates the process, compares what the
+designer shows against what the runtime does, launches it and reads the instance
+status back.
+
+## Set up in a browser instead
+
+If you would rather not touch a terminal for setup, there is a local console:
+
+```bash
+python dashboard/serve.py
+```
+
+It binds to loopback only and opens a page that lists every tool, agent and skill
+from the live registry. From there you can store credentials straight into your OS
+credential store (they never touch a file), edit schema-validated config, see which
+tools are ready and which are missing a secret, and run a tool to check it works.
+Nothing you enter leaves your machine.
+
+## Build a connector from API documentation
+
+Custom actions are the platform's main extension point: they are how a process calls an
+API that PROCESIO does not already speak. `connector-builder` turns API documentation
+into a compiled custom action, so the route from a third-party API to something a
+process can call is a build rather than a C# project.
+
+The builder is a hosted service at
+[connector-builder.procesio.app](https://connector-builder.procesio.app/). Anyone can
+create an account there; you do not need anything from us first. Two things to know
+before you start:
+
+- **You bring your own LLM key.** The build pipeline runs on a model, and it runs on
+  *your* provider account rather than ours. Set it once, in the builder, or from here.
+- **You authenticate either with an `acb_` API key or with the account's email and
+  password.** The key is long-lived and simplest for a script; the login mints a JWT.
+
+```bash
+python scripts/set-credential.py connector-builder api-key      # acb_...
+# or: set-credential.py connector-builder username / password
+
+python scripts/run-tool.py connector-builder set-llm-key --provider anthropic --api-key sk-ant-...
+python scripts/run-tool.py connector-builder create-build --api-url <docs-url>     --user-requirements "what the connector should do"
+```
+
+From there the agent drives the loop rather than you memorising the stages:
+
+```bash
+python scripts/run-agent.py connector-builder next-step --build-id <id>
+```
+
+It answers the builder's clarifying questions, approves the plan, generates, compiles,
+and hands back the `.nupkg` to upload to your workspace.
+
+## Test the form you just built
+
+Building a form is half the job. The agent's playbook is blunt about the other half:
+a form is not done until every tab, every control and every event has been exercised
+live and the runtime diagnostics are clean. Screenshots hide JS errors, failed
+launches and flicker.
+
+```bash
+python scripts/run-tool.py web save-session --name mine --url https://forms.procesio.app
+python scripts/run-tool.py web run --session mine --url <form-url> --steps @steps.json
+```
+
+The result carries a `diagnostics` block: console output, page errors, failed
+requests and bad responses. Any page error, any console error, or any 4xx or 5xx on
+the form's own calls means it is not done.
+
+## What is in here
+
+Seven tools, two agents, two skills, and two components that are neither. The
+registry is the authority on all of it: `python scripts/list-tools.py` prints what is
+installed, how many actions each one exposes, and which credentials are still
+missing. The counts below come from that listing.
+
+### Tools
+
+Run any of them with `python scripts/run-tool.py <tool> <action> [options]`. An
+action is required; `--help` lists the actions a tool exposes.
+
+| Tool | Actions | What it does |
+|---|--:|---|
+| `procesio` | 442 | The platform API: processes, forms, documents, custom actions, environments, credentials, schedules. |
+| `connector-builder` | 55 | Turns API documentation into a compiled PROCESIO custom action. Custom actions are the platform's main extension point, so this is the shortest route from a third-party API to something a process can call. |
+| `mysql` | 9 | Query the MySQL database a SQL action talks to, to see what a process actually wrote. |
+| `sqlserver` | 9 | The same, for SQL Server. |
+| `web` | 9 | Drive a real browser: render, click, fill, screenshot, read runtime diagnostics. |
+| `xlsx` | 3 | Read a workbook outside a process. PROCESIO's Node allowlist ships no xlsx library. |
+| `framework-map` | 2 | Render everything installed as one bilingual page: `python scripts/run-tool.py framework-map build`. |
+
+### Agents
+
+An agent carries method rather than mechanics. Run one with
+`python scripts/run-agent.py <agent> <action>`.
+
+| Agent | Actions | What it does |
+|---|--:|---|
+| `procesio` | 5 | Build and test: the playbook, the self-test checklist, a verify gate against a live process, and a static audit for inefficiency and robustness smells. |
+| `connector-builder` | 4 | Drives the connector loop end to end: gather, plan, generate, compile, improve from the feedback. |
+
+### Skills
+
+Knowledge an AI assistant loads on its own from the description; there is nothing to
+run. `python scripts/get-skill.py <name> --content` prints one.
+
+| Skill | What it covers |
+|---|---|
+| `procesio-platform-advisor` | Platform knowledge: capabilities, use cases, feasibility evaluation, implementation practice. |
+| `sql-server-optimizer` | Reviews the T-SQL a process runs. Inlining flow variables into SQL text is both injection-prone and the wrong action configuration, and this is what catches it. |
+
+### Two components that are not tools
+
+`dashboard/` is the setup console, started with `python dashboard/serve.py`. It is not
+in the registry and does not run through `run-tool.py`.
+
+`webplatform/aat_mcp/` is the MCP server, started by your MCP client rather than by
+you. See the section above.
+
+## Layout
+
+```
+tools/procesio/      the API client, DTOs, flow model, layout engine, handlers
+agents/procesio/     the build-and-test agent and its doctrine
+tools/_lib/          credentials, JSON I/O contract, manifest loading
+skills/              knowledge your assistant loads on its own
+dashboard/           the local setup console
+scripts/             run-tool, run-agent, list-tools, set-credential, build-router
+registry.py          manifest discovery; nothing has a hardcoded tool list
+```
+
+A tool is a directory with a `tool.yaml` manifest, an entrypoint, and a README. The
+manifest is the contract: the registry reads manifests, and everything else reads the
+registry. If you add a tool of your own next to `tools/procesio/`, it shows up in
+`list-tools.py` and in the router without registering it anywhere.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to open an issue or a pull request, and
+for the two rules that come from how this repository is built: don't move files, and
+never commit a `.procesio` export. Short version of the mechanics: this repo is
+generated from an internal monorepo, so a merged change is copied upstream and comes
+back on the next publish. That is invisible to you as a contributor, but it explains
+why commits here arrive in batches.
+
+For a security problem, don't open an issue. See [SECURITY.md](SECURITY.md).
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).