@runalabs/rill-cli 0.1.20 → 0.1.22

package/README.md

@@ -87,18 +87,33 @@ The default API is `https://userill.dev`. `RILL_API_URL` changes it; the global
 ## First recording
 
 ```sh
-rill record start --url https://example.com --title "Checkout verification"
-# Save recordingId and connect your browser tool to the returned cdpUrl.
-# Perform the flow in the existing recorded page.
+rill browser connect
+# Open the connection link in Chrome, then choose your app tab in Rill.
+rill --human record start --title "Checkout verification"
+# Perform the steps yourself in that tab; see the agent-operated example below.
 rill record stop <recording-id>
 rill inspect https://userill.dev/s/<share-secret>
 ```
 
-Start returns `recordingId`, `cdpUrl`, `status`, `bodyCaptureEnabled`, and `maxDurationSeconds`. Stop finalizes capture, uploads frames and diagnostics for remote encoding, and waits for playback. Confirm `status: "ready"` and a non-null `shareUrl` before returning the evidence link. Local capture finishing does not establish remote readiness.
+Start returns `recordingId`, `browserAttachment`, `status`, `bodyCaptureEnabled`, and `maxDurationSeconds`. A managed or direct CDP recording also returns `cdpUrl`. Stop finalizes capture, uploads frames and diagnostics for remote encoding, and waits for playback. Confirm `status: "ready"` and a non-null `shareUrl` before returning the evidence link. Local capture finishing does not establish remote readiness.
 
 New browser recordings include a visible cursor and click pulses by default. In Rill Settings → Cursor appearance, workspace members can turn them off or choose an accent color. The CLI reads this preference when starting a recording; it is baked into the video and does not change existing recordings. Use an updated CLI and recorder daemon to capture the overlay.
 
-### Connect Playwright
+### Record the browser you already use
+
+Install [Rill for Chrome](https://chromewebstore.google.com/detail/rill-for-chrome/ehpjlnjimoljofijlkkdiefpcmiimdbp) once. The CLI also packages its matching extension archive for manual setup. For the existing-tab path, run `rill browser connect`, open the returned link in Chrome and click **Connect Chrome**. Rill opens beside your page. Switch to your website and click **Connect this tab**. HTTP and HTTPS sites are supported, including localhost. Setup is remembered and multiple takes reuse the approved tab.
+
+`record start` keeps its normal managed-browser behavior and does not require an extension. Choose `--browser existing` to record the tab connected through Rill for Chrome; that explicit mode fails with connection guidance when no tab is selected. Capture does not click, type, evaluate scripts, intercept navigation, or change the viewport. Sign-in state stays in Chrome; site credentials are never extracted or exported. Request bodies and headers are not captured. Console text is bounded and heuristically redacted; visible page content remains in the video.
+
+For an agent-operated recording, first establish that its existing controller is on the selected target. Inspect `rill --json browser status` and match the returned Chrome tab/target ID with the controller's own selected tab. Then use `rill record start --browser existing --operator agent --controller-target <target-id>`. This matches target identity; it does not certify that an arbitrary agent can drive the browser. If the host cannot expose that identity or control the tab, explain the limitation and offer human operation instead. Rill supplies capture rather than a second controller.
+
+Capture starts only after a frame has been saved. Stopping leaves the tab connected for the next take. A lost connection saves the captured part and marks interruption; upload retry reuses those bytes. New tabs/popups are outside capture and produce a coverage note. DevTools or tab closure can interrupt capture. Inactivity disconnects tab access after an hour; device setup remains saved. Use `rill browser disconnect` to end access. Chrome can still require its own permissions.
+
+Choose a fresh browser explicitly with `rill record start --browser new --url <url>`. Local encoding is available on that managed/CDP path; the Chrome extension path uses remote encoding. Existing CLI limits, workspace access, recording lifecycle, recovery, and player still apply. Native extension/controller coexistence and provider playback must be verified separately from protocol tests.
+
+### Connect Playwright to an explicitly created browser
+
+Use `rill record start --browser new --url <url>` only when the task calls for a fresh browser and your controller supports its connection.
 
 Start also returns `browserAttachment` with the CDP endpoint, protocol, Playwright method, and attachment instructions. Browser tools must explicitly support attaching to that endpoint; Rill does not automatically expose its browser to every tool.
 
@@ -254,7 +269,7 @@ Explicit `--json` or `--pretty` takes precedence over `--human`. Use `--pretty`
 rill whoami
 rill whoami --json
 rill --human doctor
-rill --human record start --url https://example.com --title "Smoke test" --headed
+rill --human record start --browser new --url https://example.com --title "Smoke test" --headed
 rill --human record stop <recording-id>
 rill --human record status <recording-id>
 ```