Gui: Add IntentFrame Control Plane (port 9720) with operator UI and Docker test harness

.github/workflows/pr.yml

@@ -80,6 +80,12 @@ jobs:
           uv run --package intentframe-integrations-cli python tests/intentframe_integrations/test_scoped_governance_yaml.py
           uv run --package intentframe-integrations-cli python tests/intentframe_integrations/test_actions_manifest.py
 
+      - name: Control plane unit tests
+        run: |
+          uv run --package intentframe-control-plane python tests/intentframe_control_plane/test_lifecycle.py
+          uv run --package intentframe-control-plane python tests/intentframe_control_plane/test_read_models.py
+          uv run --package intentframe-control-plane python tests/intentframe_control_plane/test_server.py
+
       - name: Hermes gateway unit tests
         run: |
           uv run --package intentframe-integrations-cli python tests/hermes_gateway/test_isolation.py
@@ -109,6 +115,8 @@ jobs:
           npm ci
           npm run build
           test -f if-integration-clients/typescript/dist/index.js
+          cd intentframe-control-plane/web && npm ci && npm run build
+          test -f ../src/intentframe_control_plane/static/index.html
 
   docker-install:
     name: Docker install (curl | bash)

CONTRIBUTING.md

@@ -25,10 +25,22 @@ git clone https://github.com/intentframe/agent-integrations.git
 cd agent-integrations
 uv sync --all-packages
 npm ci && npm run build
+cd intentframe-control-plane/web && npm ci && npm run build
 ```
 
 The dev launcher is `./bin/intentframe-integrations`.
 
+### Control plane frontend
+
+When you change `intentframe-control-plane/web/`, rebuild and **commit** the output:
+
+```bash
+cd intentframe-control-plane/web && npm run build
+git add ../src/intentframe_control_plane/static/
+```
+
+Static assets under `src/intentframe_control_plane/static/` are git-tracked so installs and Docker work without Node.js. CI verifies `static/index.html` exists after build.
+
 ## Running tests
 
 ```bash
@@ -49,17 +61,21 @@ Install regression tests:
 bash tests/install/test_ref_resolution.sh
 bash tests/install/test_installer_bootstrap_docker.sh
 bash tests/install/test_installer_curl_docker.sh
+bash tests/docker/test_control_plane_smoke.sh   # local throwaway CP lifecycle smoke
 ```
 
 ## Project structure
 
 | Path | Purpose |
 |------|---------|
 | `intentframe-integrations-cli/` | User-facing CLI |
+| `intentframe-control-plane/` | Operator UI (React) + FastAPI server on :9720 |
 | `if-integration-backend/` | Validate-only IntentFrame runtime supervisor |
 | `if-integration-clients/` | Bridge clients (Python + TypeScript) |
 | `integrations/hermes/` | Hermes plugin, adapter, governance templates |
 | `integrations/_template/` | Scaffold for new agent integrations |
+| `tests/intentframe_control_plane/` | Control plane lifecycle + API unit tests |
+| `tests/docker/` | Production-like Docker user journey (CP :9720 + chat :9119) |
 | `tests/` | Unit, install, Docker, and gateway E2E tests |
 
 Use `uv sync --all-packages` from the repo root. Do not install workspace members

README.md

@@ -68,22 +68,24 @@ No git clone required:
 curl -fsSL https://github.com/intentframe/agent-integrations/raw/main/scripts/install-hermes-plugin.sh | bash
 ```
 
-Then run Hermes with IntentFrame:
+Then open the IntentFrame Control Plane (started by the installer):
+
+```text
+http://127.0.0.1:9720
+```
+
+Use it to configure keys, start the enforcement stack, manage governed tools, and load policy.
+
+Hermes chat (separate, after the stack is up):
 
 ```bash
-export OPENAI_API_KEY=sk-...
-intentframe-integrations up hermes
 hermes dashboard
 ```
 
-Open:
-
 ```text
-http://localhost:9119/chat
+http://127.0.0.1:9119/chat
 ```
 
-Ask Hermes to run a terminal command. If the tool is governed, IntentFrame validates it before Hermes executes it.
-
 ---
 
 ## See It Work
@@ -248,6 +250,12 @@ curl -fsSL https://github.com/intentframe/agent-integrations/raw/main/scripts/in
 curl -fsSL https://github.com/intentframe/agent-integrations/raw/main/scripts/install-hermes-plugin.sh | bash -s -- --headless
 ```
 
+**Skip control plane during install** (Docker/CI — entrypoint starts it separately):
+
+```bash
+curl -fsSL .../install-hermes-plugin.sh | bash -s -- --headless --no-control-plane
+```
+
 From a git clone (same flags):
 
 ```bash
@@ -257,7 +265,7 @@ bash scripts/install-hermes-plugin.sh --headless
 **Pinned release** (script URL and pack ref should match):
 
 ```bash
-curl -fsSL https://github.com/intentframe/agent-integrations/raw/v0.2.0/scripts/install-hermes-plugin.sh | bash -s -- --ref v0.2.0
+curl -fsSL https://github.com/intentframe/agent-integrations/raw/v0.2.1/scripts/install-hermes-plugin.sh | bash -s -- --ref v0.2.1
 ```
 
 After headless install, set `OPENAI_API_KEY` (and run `hermes setup` if chat returns 401). Then the same [three commands](#run-three-commands) as below.
@@ -310,16 +318,18 @@ Full tables (what is / is not removed): [docs/hermes-cli.md#uninstall](docs/herm
 
 ## Status and Resources
 
-**Current release:** [v0.2.0](https://github.com/intentframe/agent-integrations/releases/tag/v0.2.0)  
+**Current release:** [v0.2.1](https://github.com/intentframe/agent-integrations/releases/tag/v0.2.1)  
 **Integration maturity:** Hermes plugin + adapter + CLI; Docker E2E; known uninstall caveats on root/FHS — [limitations](docs/hermes-known-limitations.md).
 
 ### Documentation
 
 | Doc | Audience |
 |-----|----------|
+| [docs/intentframe-control-plane.md](docs/intentframe-control-plane.md) | Operator UI — ports, frontend, health checks, Docker |
 | [docs/hermes-cli.md](docs/hermes-cli.md) | CLI commands — governance, policy, gateway, env vars |
 | [docs/hermes-known-limitations.md](docs/hermes-known-limitations.md) | Install/uninstall caveats and roadmap |
 | [docs/hermes-intentframe-integration-guide.md](docs/hermes-intentframe-integration-guide.md) | Architecture, adding tools, troubleshooting |
+| [tests/docker/README.md](tests/docker/README.md) | Docker user journey (:9720 control plane + :9119 chat) |
 | [tests/docker/logs/](tests/docker/logs/README.md) | Captured Docker chat + gating audit sessions (example probes) |
 | [integrations/hermes/README.md](integrations/hermes/README.md) | Monorepo dev reference |
 | [IntentFrame](https://github.com/intentframe/intentframe) | Core runtime — threat model, principles, Actor SDK |
@@ -342,10 +352,12 @@ uv sync --all-packages
 | Path | Purpose |
 |------|---------|
 | `intentframe-integrations-cli/` | `intentframe-integrations` CLI |
+| `intentframe-control-plane/` | Operator UI (React + FastAPI on :9720) |
 | `integrations/hermes/` | Plugin, adapter, governance templates |
 | `integrations/_template/` | Scaffold for adding a new agent integration |
 | `if-integration-backend/` | IntentFrame runtime supervisor |
 | `if-integration-clients/` | Bridge clients (Python + TypeScript) |
+| `tests/intentframe_control_plane/` | Control plane unit tests |
 | `tests/hermes_gateway/` | Opt-in gateway E2E (isolated sandbox) |
 | `tests/docker/` | Production-like Docker user journey |
 | `tests/docker/logs/` | Captured manual gating sessions (chat + audit trail) |

RELEASE.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.2.0",
-  "tag": "v0.2.0",
+  "version": "0.2.1",
+  "tag": "v0.2.1",
   "product": "agent-integrations",
-  "description": "IntentFrame Hermes integration pack release metadata. Tag v0.2.0 should match this file."
+  "description": "IntentFrame Hermes integration pack release metadata. Tag v0.2.1 should match this file."
 }

docs/hermes-cli.md

@@ -29,6 +29,8 @@ Skips Hermes setup wizard and browser engine. You must set `OPENAI_API_KEY` your
 curl -fsSL https://github.com/intentframe/agent-integrations/raw/main/scripts/install-hermes-plugin.sh | bash -s -- --headless
 ```
 
+Docker test harness also passes `--no-control-plane` so the entrypoint can bind `0.0.0.0:9720` before starting the UI. See [tests/docker/README.md](../tests/docker/README.md).
+
 From a git clone:
 
 ```bash
@@ -44,7 +46,7 @@ Use the **same ref** in the script URL and `--ref` (or `REF=`). `VERSION=` is a
 |------|---------|
 | Latest | `curl -fsSL …/raw/main/scripts/install-hermes-plugin.sh \| bash` |
 | Branch (pre-merge) | `curl -fsSL …/raw/my-branch/… \| bash -s -- --ref my-branch --headless` |
-| Release tag | `curl -fsSL …/raw/v0.2.0/… \| bash -s -- --ref v0.2.0` |
+| Release tag | `curl -fsSL …/raw/v0.2.1/… \| bash -s -- --ref v0.2.1` |
 | Commit SHA | `curl -fsSL …/raw/<sha>/… \| bash -s -- --ref <sha>` |
 
 After install, `intentframe-integrations doctor hermes` shows the pinned ref from `~/.intentframe/agent-integrations/.install-manifest.json`.
@@ -90,13 +92,23 @@ command -v hermes
 
 ## Happy path
 
+After [install](hermes-cli.md#install), the installer starts the **IntentFrame Control Plane** at `http://127.0.0.1:9720`.
+
 ```bash
+# Control plane (operator UI — started by installer)
+open http://127.0.0.1:9720
+
+# From Control Plane or CLI: start enforcement stack
 export OPENAI_API_KEY=sk-...
 intentframe-integrations up hermes      # backend + adapter + gateway
-hermes dashboard                        # http://localhost:9119/chat
-intentframe-integrations stop           # tear down
+
+# Hermes chat (separate from control plane)
+hermes dashboard                        # http://127.0.0.1:9119/chat
+intentframe-integrations stop           # enforcement stack only (not control plane)
 ```
 
+See [intentframe-control-plane.md](intentframe-control-plane.md) for port registry and lifecycle.
+
 ## Command overview
 
 ### Install and integrate
@@ -262,6 +274,29 @@ Runtime file: `~/.intentframe/integrations/hermes/policy.yaml`
 
 Policy changes apply immediately — no gateway restart.
 
+### Control plane (operator UI)
+
+Separate from Hermes dashboard. Default: `http://127.0.0.1:9720`. One uvicorn process serves the React UI and `/api/*`.
+
+```bash
+intentframe-integrations control-plane start [--host HOST] [--port PORT]
+intentframe-integrations control-plane stop      # UI only — does not stop enforcement stack
+intentframe-integrations control-plane status
+intentframe-integrations control-plane serve     # foreground dev (no PID file)
+```
+
+`intentframe-integrations stop` stops the **enforcement stack only** — not the control plane.
+
+Machine-readable output (scripting):
+
+```bash
+intentframe-integrations status --json
+intentframe-integrations governance list hermes --json
+intentframe-integrations policy show hermes --json
+```
+
+See [intentframe-control-plane.md](intentframe-control-plane.md) for frontend build, health checks, and Docker.
+
 ### Other
 
 ```bash
@@ -286,6 +321,15 @@ Written to `~/.hermes/.env` on install (plugin paths):
 | `HERMES_BIN` | Override Hermes binary |
 | `HERMES_HOME` | Hermes config dir (default `~/.hermes`) |
 
+Written to `~/.intentframe/.env` on install (control plane):
+
+| Variable | Purpose |
+|----------|---------|
+| `INTENTFRAME_CONTROL_PLANE_HOST` | Bind host (default `127.0.0.1`; Docker uses `0.0.0.0`) |
+| `INTENTFRAME_CONTROL_PLANE_PORT` | UI port (default `9720`) |
+| `INTENTFRAME_CONTROL_PLANE_TOKEN` | Optional bearer token for `/api/*` |
+| `INTENTFRAME_CONTROL_PLANE_ALLOW_REMOTE` | Set `1` to allow binding `0.0.0.0` / non-loopback (Docker) |
+
 Shell exports win over `agent.json` defaults (`setdefault` in `load_and_activate_pack`).
 
 `gateway start hermes` logs the effective governance path on stderr:

docs/hermes-known-limitations.md

@@ -46,7 +46,7 @@ The installer supports git **branches**, **tags**, and **commit SHAs** via `--re
 |------|---------|
 | Latest (default) | `curl …/raw/main/scripts/install-hermes-plugin.sh \| bash` |
 | Pre-merge / branch | `curl …/raw/my-branch/… \| bash -s -- --ref my-branch --headless` |
-| Stable release | `curl …/raw/v0.2.0/… \| bash -s -- --ref v0.2.0` |
+| Stable release | `curl …/raw/v0.2.1/… \| bash -s -- --ref v0.2.1` |
 | Locked / reproducible | `curl …/raw/<commit-sha>/… \| bash -s -- --ref <commit-sha>` |
 
 Install provenance is written to `~/.intentframe/agent-integrations/.install-manifest.json` and shown by `intentframe-integrations doctor hermes`.