Position the docs around the neutral core, not pi

README.md

@@ -1,9 +1,13 @@
 # loop
 
-Browser tools for your agent, built on [pi](https://github.com/earendil-works/pi).
+Browser tools for your agent. The agent can be a [pi](https://github.com/earendil-works/pi)
+`Agent` or `AgentHarness` — or your coding harness through a plugin — with Eve and
+AI SDK bindings anticipated next. Kernel Loop supplies the tools, the
+[Kernel cloud browser](https://kernel.sh/) they run against, and the per-model
+compatibility knowledge.
 
-Point any model at a [Kernel cloud browser](https://kernel.sh/): pick the tools,
-get plain agent objects back, and run whatever loop you already have.
+Point any model at a Kernel browser: pick the tools, get plain agent objects
+back, and run whatever loop you already have.
 
 ```ts
 import { loop } from "@onkernel/loop";
@@ -16,8 +20,10 @@ const { model, agentTools, models } = kb.compile({
 });
 ```
 
-Already in pi? Install the extension instead and keep pi's session, UI, and
-model selection:
+The extension is the other half of the workflow: a harness is where you find
+out which tools and which model actually work for a use case, and the SDK is
+what you deploy into your production agent. Same catalog, same tool identities,
+same model knowledge on both sides, so the hand-off is lossless:
 
 ```bash
 pi install npm:@onkernel/loop
@@ -44,22 +50,24 @@ This repo does all of that and stops there. `@onkernel/loop` represents the
 provider differences as an explicit, identity-keyed tool catalog; you choose the
 exact tools, and provider transforms compose only the declarations and request
 fields those identities require. It does not supply an agent class, a session
-format, or a front-end — your framework already has those.
+format, or a front-end — your framework already has those. Tool identities
+(`kloop.*.v1`) and model-facing names are byte-identical across bindings, so
+transcripts and evals stay comparable wherever the same catalog runs.
 
 ---
 
 ## Workspace
 
 ```
 packages/
-├── loop/       # @onkernel/loop      - tools, catalog compilation, pi bindings, pi extension
+├── loop/       # @onkernel/loop      - framework-neutral core, pi binding, pi extension
 └── ptywright/  # @onkernel/ptywright - development-only PTY/TUI test infrastructure
 ```
 
 | Entry point | What it ships |
 | --- | --- |
-| `@onkernel/loop` | Canonical actions, tool factories/toolsets, catalog compilation, the tool menu, and Kernel-browser execution. |
-| `@onkernel/loop/pi` | `attach()`: binds a Kernel browser and compiles a (model, tools) pair into plain pi objects, plus model resolution and provider adapters. |
+| `@onkernel/loop` | The framework-neutral core: canonical actions, tool factories/toolsets, catalog compilation, the tool menu, and Kernel-browser execution. Imports nothing from pi — a unit test enforces the boundary. |
+| `@onkernel/loop/pi` | The pi binding — the first of the framework bindings (`./eve` and `./ai-sdk` are the anticipated next). `attach()` binds a Kernel browser and compiles a (model, tools) pair into plain pi objects, plus model resolution and provider adapters. |
 | `pi.extensions` | A pi extension contributing those tools to pi's own agent session. |
 | [`@onkernel/ptywright`](packages/ptywright) | Development-only PTY/TUI test infrastructure. |
 
@@ -143,12 +151,12 @@ per-tool verdict.
 
 ## How it works
 
-1. **Model layer** — `@onkernel/loop/pi` opens pi-ai's whole model catalog and
-   composes provider declarations, headers, and payload transforms around it.
-   Catalog compilation is declaration-only: it never sees an executor.
-2. **Execution layer** — `@onkernel/loop` materializes the caller's exact
+1. **Execution layer** — `@onkernel/loop` materializes the caller's exact
    catalog over one shared resource pool and executes canonical actions through
    Kernel's computer API or a raw-CDP browser executor.
+2. **Model layer** — `@onkernel/loop/pi` opens pi-ai's whole model catalog and
+   composes provider declarations, headers, and payload transforms around that
+   core. Catalog compilation is declaration-only: it never sees an executor.
 3. **Transport** — the compiled catalog derives `model.api` from the selected
    tools, so a provider-native surface reaches the wire with the transport,
    headers, and payload shape it requires.

docs/architecture.md

@@ -35,7 +35,9 @@ both explicitly and may use pi's orchestration primitives directly.
   `modelSupportsDeferredTools` interprets pi compat flags, and the published
   `loop` namespace composes `loop.providers.anthropic.supports` over core's
   declarations), transport derivation, the provider adapters, provider retry,
-  and header composition.
+  and header composition. `./pi` is the first binding; `./eve` and `./ai-sdk`
+  are the anticipated next, sharing the same identities and tool names so
+  transcripts stay comparable across frameworks.
 - `src/pi-extension/` contributes these tools to a pi session that pi itself
   owns. It is the one consumer that uses neither `attach()` nor the harness: pi
   owns the model collection and the agent loop, so the extension takes the two

package.json

@@ -1,7 +1,7 @@
 {
   "name": "cua",
   "version": "0.1.0",
-  "description": "Kernel-cloud-browser computer-use: tools, catalog compilation, and pi bindings",
+  "description": "Browser tools for your agent: framework-neutral tool catalog, per-model compilation, Kernel-browser execution, and a pi binding",
   "type": "module",
   "private": true,
   "workspaces": [

packages/loop/README.md

@@ -1,10 +1,11 @@
 # `@onkernel/loop`
 
-Kernel browser computer-use for pi: tool declarations, per-model catalog
-compilation, Kernel-browser execution, the `attach()` binding for
-`@earendil-works/pi-agent-core`, and a pi extension.
+Browser tools for your agent: a framework-neutral core (tool declarations,
+per-model catalog compilation, Kernel-browser execution) plus a pi binding
+(`attach()` for `@earendil-works/pi-agent-core`) and a pi extension.
 
-Two entry points:
+One package, two entry points: the neutral core and the pi binding — the first
+binding; Eve and AI SDK are anticipated next.
 
 | import | what it is |
 | --- | --- |
@@ -466,6 +467,11 @@ browser they run against, and the provider wiring provider-native surfaces need.
 It does not start a second model loop, and it adds no implicit screenshots or
 prompt instructions.
 
+The extension is not a lesser version of the SDK; it is the other half of the
+workflow. Experiment in the harness to find which tools and model fit a use
+case, then deploy the same catalog — same identities, same names — through
+`attach()` in your production agent.
+
 ```sh
 pi install npm:@onkernel/loop
 

packages/loop/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@onkernel/loop",
   "version": "0.11.0",
-  "description": "Kernel browser computer-use tools, catalog compilation, and pi bindings",
+  "description": "Browser tools for your agent: framework-neutral tool catalog, per-model compilation, Kernel-browser execution, and a pi binding + extension",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",