docs(harness-ui): clarify live-run bridge positioning

Reframe the package as Studio’s reusable AG-UI live-run bridge and distinguish the standalone CLI as an advanced integration surface. Document its scope and non-goals, direct visual users to Studio, and fix the embedded example to provide the required executor factory.

Validated with git diff --check and npx vitest run test/skills-docs/doc-link-graph.test.mjs.

Co-authored-by: Codex (GPT 5.6 Sol) <codex@openai.com>

Author: phodal

packages/harness-ui/README.md

@@ -1,19 +1,28 @@
 # @qoder-ai/harness-ui
 
-The AG-UI protocol adapter for [`@qoder-ai/harness`](../harness/README.md).
-It turns a `.harness` assembly into an [AG-UI](https://docs.ag-ui.com/)
-endpoint: any AG-UI-compatible frontend (CopilotKit, a TUI, or the companion
-[`@qoder-ai/harness-studio`](../harness-studio/README.md)) can start runs and
-render them live.
+The reusable live-run bridge between [`@qoder-ai/harness`](../harness/README.md)
+and browser-facing [AG-UI](https://docs.ag-ui.com/) clients.
+
+Despite the historical package name, this package does **not** contain visual
+components or an end-user application. It owns the bounded protocol boundary
+that compiles and resolves one Harness run, projects neutral `HarnessRunEvent`
+values into AG-UI events, and optionally serves them over local HTTP/SSE.
+
+Most users should start with
+[`@qoder-ai/harness-studio`](../harness-studio/README.md), the actual React
+control plane. Studio embeds this bridge under `/agui` and adds the Debugger,
+run timeline, Tool Call inspection, permissions, cancellation, evidence, and
+workspace experience. Use `@qoder-ai/harness-ui` directly when building a
+custom AG-UI client or embedding the run bridge in another local server.
 
 ## How it fits
 
 ```text
 .harness ── @qoder-ai/harness ── HarnessRunEvent (neutral lifecycle)
                                         │
-                        translate.ts: neutral → AG-UI events
+                   @qoder-ai/harness-ui: AG-UI projection + SSE
                                         │
-                        server.ts: POST /agui → SSE stream
+              custom AG-UI client ◄─────┴─────► Harness Studio
 ```
 
 The executor's `HarnessRunEmitter` already guarantees a well-formed
@@ -25,14 +34,48 @@ run ends with either `RUN_FINISHED` or `RUN_ERROR`, never both.
 
 Retained tool output is bounded to 64 KiB. Failed or truncated results emit a
 namespaced `harness.tool-result-meta` custom event after `TOOL_CALL_RESULT`;
-browser clients can import its constant and value type from the browser-safe
+bounded runtime-protocol evidence uses `harness.protocol-event`. Browser
+clients can import both constants and their value types from the browser-safe
 `@qoder-ai/harness-ui/protocol` entrypoint.
 
 This package implements the AG-UI **wire format** with local types instead of
 depending on the pre-stable `@ag-ui/core`; conformance is asserted by tests
 on the emitted JSON.
 
-## Serve a harness
+## Scope
+
+This package owns:
+
+- deterministic `HarnessRunEvent` to AG-UI event translation;
+- a browser-safe AG-UI wire contract and Harness custom-event types;
+- SSE encoding and incremental decoding;
+- compile, source-lock, resolve, execute, and terminal-event orchestration with
+  an injected executor factory;
+- a local `POST /agui` handler with bounded requests, origin checks, and
+  fail-closed remote-bind policy.
+
+It does not own React components, Studio state or layout, persisted sessions,
+multi-turn conversation state, Agent discovery, remote authentication, or a
+production gateway. `RunAgentInput` is intentionally used as a bounded one-run
+request: the latest user message supplies the prompt, while Studio or another
+embedding host owns the surrounding workspace and interaction lifecycle.
+
+## Use Harness Studio
+
+For the supported visual workflow, run Studio with a Harness file:
+
+```sh
+npx @qoder-ai/harness-studio --harness my-agent.harness
+```
+
+Studio serves its own UI and embeds this package's handler on the same local
+origin. See the [Harness Studio README](../harness-studio/README.md) for its
+Debugger, evidence, workspace, and ACP Agent routes.
+
+## Serve the bridge directly
+
+The standalone command is an advanced integration surface for a custom
+AG-UI-compatible frontend; it is not a separate Better Harness UI:
 
 ```sh
 npx @qoder-ai/harness-ui serve my-agent.harness --port 3210
@@ -42,10 +85,9 @@ npx @qoder-ai/harness-ui serve my-agent.harness --port 3210
   The prompt is the latest user message.
 - `GET /healthz` — liveness probe.
 
-The server binds to `127.0.0.1` and is a local development surface. Runs
-execute through the same v0.3 executors as the core package (Qoder SDK by
-default), so the executor honesty rules and redaction guarantees apply
-unchanged.
+The server binds to `127.0.0.1` and is a local integration surface. Its CLI
+selects the same v0.3 Qoder or Pi executors as the core package, so the executor
+honesty rules and redaction guarantees apply unchanged.
 
 A skill declared with `source "./skills/x"` is delivered from disk, not
 merely referenced: the server locks and reads it against `--source-root`,
@@ -68,22 +110,28 @@ a non-loopback Host just because the Origin matches it. Keep the default
 loopback bind unless a trusted gateway supplies authentication and transport
 security.
 
-## Embed in code
+## Embed the run bridge
 
 ```ts
 import { runHarnessAgui } from "@qoder-ai/harness-ui";
+import { QoderSdkExecutor } from "@qoder-ai/harness/exec";
 
 await runHarnessAgui({
   source,               // .harness source text
   prompt: "Explain the repository in one sentence.",
   threadId: "thread-1",
   runId: "run-1",
   onEvent: (event) => console.log(event.type),
+  executorFactory: ({ onRunEvent }) =>
+    new QoderSdkExecutor({ onRunEvent }),
 });
 ```
 
-`executorFactory` injects a custom or scripted executor — that is also how
-the tests run without a live SDK.
+The library entrypoint never selects a concrete host executor implicitly.
+`executorFactory` keeps host wiring with the embedding application and also
+allows deterministic scripted executors in tests. Server embedders can mount
+`handleAguiRun` on an existing Node HTTP server instead of opening a second
+listener.
 
 ## Development