docs: clarify public orchestration and connection ownership

AGENTS.md

@@ -33,12 +33,15 @@ Preserve these invariants:
 - Allow multiple grants, but reject conflicting exclusive leases without queuing or preemption.
 - Treat provider recovery as bounded and recoverable; treat broker death as revocation of all live
   authority.
-- Keep Chrome APIs and tab-selection policy out of CDB.
-- Keep URL and navigation-grant policy out of CDB. The embedding broker may scope different
-  principals differently while they share one target.
+- Keep Chrome APIs in the optional extension Chrome adapter and tab-selection policy in the host.
+- Keep navigation presets in the optional broker package, outside the protocol kernel. Hosts may
+  impose additional restrictions on principals sharing one target.
 - Keep MCP definitions transport-neutral. The embedding host owns the MCP server and passes its
   authenticated session through as principal identity.
 - Return structured errors with retry hints where retry can succeed.
+- Reuse the connection-bound Devframe handle for peer replacement, subscriptions and cancellation.
+  Preserve per-principal sessions and the host's ownership of the shared transport.
+- Keep notification state headless; theme and DOM behavior belong to the optional renderer.
 
 The user-visible access levels are `observe`, `inspect`, `interact`, `debug`, and `unsafe`. Do not
 silently downgrade a requested level.

ARCHITECTURE.md

@@ -73,6 +73,43 @@ on startup failure and shutdown. The optional panel consumes an existing managem
 instantiates a broker. Registry aggregation, tool ownership/routing, MCP lifecycle and WebMCP
 publication remain with the embedding application.
 
+The connection-bound `createCdbConnection` handle attaches to an existing peer. It owns lazy
+browser subscriptions, logical-session readiness, reconnect fencing and operation cancellation.
+Hosts keep one handle per principal and forward connection replacement and loss. Ordinary host
+traffic need not await browser readiness. Disposing this handle releases CDB resources without
+closing the shared transport.
+
+```mermaid
+flowchart LR
+  Host[Host configuration and process lifecycle] --> Peer[Existing authenticated RPC peer]
+  Peer --> Connection[CDB connection-bound handle]
+  Connection --> Service[CDB Devframe service]
+  Service --> Broker[CDB broker and authority stores]
+  Provider[Extension provider] --> Peer
+  Broker --> Tools[Per-principal semantic tool sessions]
+  Host --> Catalogue[Host catalogue and routing]
+  Catalogue --> Service
+  UI[Host renderer and approval policy] --> Panel[Public CDB panel]
+  Panel --> Connection
+```
+
+```mermaid
+sequenceDiagram
+  participant Host
+  participant Handle as CDB connection handle
+  participant Peer as Authenticated peer
+  Host->>Handle: attach(peer)
+  Note over Host,Peer: Ordinary host traffic remains available
+  Host->>Handle: watch or browser operation
+  Handle->>Peer: Subscribe / establish principal readiness
+  Host->>Handle: disconnected()
+  Note over Handle: Fence callbacks and cancel affected operations
+  Host->>Handle: attach(replacementPeer)
+  Handle->>Peer: Resume the same principal when needed
+  Host->>Handle: dispose()
+  Note over Host,Peer: Host retains ownership of transport shutdown
+```
+
 ### Grant request coordinator
 
 `createGrantRequestCoordinator` stores the authenticated logical session, principal, requested
@@ -97,6 +134,11 @@ successful CDP pointer commands into sanitized visual events and renders an isol
 temporary favicon. The host owns installation, messaging, current grant state, and navigation
 reinjection.
 
+The notification controller is headless. The optional Shadow DOM renderer supplies the default
+light/dark theme, typed CSS-variable customization and runtime theme updates without rebuilding
+controls. Hosts choose branding, placement and approval callbacks. A host using Devframe
+notifications uses its message API instead of injecting the default renderer.
+
 ### Automation providers
 
 The core automation contract normalizes snapshot, find, inspect, and semantic action requests. An

README.md

@@ -7,6 +7,12 @@ and event subscriptions independent from Chrome extension APIs.
 An embedding host composes CDB as a library. CDB does not discover browser tabs, start application
 servers, or own an application's MCP lifecycle.
 
+The optional broker, Devframe and Chrome adapters compose reusable orchestration around that
+protocol. Embed them in an existing host or run the [standalone example](examples/devframe/README.md).
+For an existing Devframe connection, use the [connection-bound handle](packages/devframe/README.md#connection-bound-clients)
+to keep subscriptions, principal readiness and cancellation out of application connection code.
+Host-wide enablement, configuration persistence and tool catalogue ownership remain host decisions.
+
 ## Place in a browser-control stack
 
 ```text