opensteer 0.8.15 → 0.8.17

package/skills/opensteer/references/cli-reference.md

@@ -1,118 +0,0 @@
-# Opensteer CLI Reference
-
-Use the CLI for fast exploration before writing SDK code.
-
-## Quickstart
-
-```bash
-opensteer open https://example.com --workspace demo
-opensteer snapshot action --workspace demo
-opensteer input 5 laptop --workspace demo --persist "search input" --capture-network search
-opensteer click 7 --workspace demo --persist "search button" --capture-network search
-opensteer snapshot extraction --workspace demo
-opensteer extract '{"items":[{"name":{"element":13},"price":{"element":14}},{"name":{"element":22},"price":{"element":23}}]}' \
-  --workspace demo --persist "search results"
-opensteer close --workspace demo
-```
-
-## What To Read From Snapshots
-
-`snapshot action` and `snapshot extraction` return filtered HTML in the `html` field.
-
-- Read the `html` string.
-- Find `c="N"` markers in that HTML.
-- Use those numbers as positional `element` ids in CLI commands and extraction schemas.
-- Re-snapshot after navigation before using new element numbers.
-
-## Core Commands
-
-### Session and Pages
-
-```bash
-opensteer open https://example.com --workspace demo
-opensteer goto https://example.com/search --workspace demo --capture-network page-load
-opensteer snapshot action --workspace demo
-opensteer snapshot extraction --workspace demo
-opensteer tab list --workspace demo
-opensteer tab 2 --workspace demo
-opensteer tab close 2 --workspace demo
-opensteer close --workspace demo
-```
-
-### DOM Actions
-
-```bash
-opensteer click 7 --workspace demo --persist "primary button"
-opensteer hover 7 --workspace demo --persist "primary button"
-opensteer input 5 "search term" --workspace demo --persist "search input" --press-enter
-opensteer scroll down 400 --workspace demo
-opensteer scroll down 400 --workspace demo --element 12 --persist "results list"
-opensteer extract '{"title":{"element":3},"url":{"source":"current_url"}}' --workspace demo \
-  --persist "page summary"
-```
-
-Rules:
-
-- `--persist` caches reusable DOM targets and extraction descriptors by persist key.
-- `extract <schema> [--persist <key>]` accepts the schema positionally and optionally saves it for replay.
-- There is no CLI `--selector`, `--description` target flag, `--text`, or `--input-json`.
-
-### Network Discovery
-
-```bash
-opensteer network query --workspace demo --capture search
-opensteer network query --workspace demo --hostname api.example.com --limit 20
-opensteer network detail rec_123 --workspace demo
-opensteer replay rec_123 --workspace demo
-opensteer replay rec_123 --workspace demo --query keyword=headphones --query count=10
-opensteer fetch https://api.example.com/search --workspace demo --query keyword=laptop
-```
-
-`network query` is intentionally short:
-
-- one compact block per record
-- record id
-- method and status
-- resource type
-- URL
-- request and response body summaries when useful
-
-Use `network detail` when you need headers, cookies sent, request body previews, response body previews, GraphQL metadata, or redirect chains.
-
-### Browser State
-
-```bash
-opensteer cookies --workspace demo
-opensteer cookies example.com --workspace demo
-opensteer storage example.com --workspace demo
-opensteer state example.com --workspace demo
-```
-
-Use these when replay needs cookies, storage-backed tokens, hidden fields, or globals.
-
-### Browser Admin
-
-```bash
-opensteer browser status --workspace demo
-opensteer browser clone --workspace github-sync --source-user-data-dir "$HOME/Library/Application Support/Google/Chrome" --source-profile-directory Default
-opensteer browser reset --workspace github-sync
-opensteer browser delete --workspace github-sync
-opensteer record https://example.com --workspace demo
-```
-
-## Recommended Exploration Loop
-
-1. `opensteer open`
-2. `opensteer goto ... --capture-network <label>` or a DOM action with `--capture-network`
-3. `opensteer network query`
-4. `opensteer network detail <recordId>`
-5. `opensteer replay <recordId>`
-6. `opensteer cookies` / `storage` / `state` if needed
-7. `opensteer close`
-
-## Common Mistakes
-
-- Starting API discovery with `snapshot` instead of `captureNetwork`.
-- Parsing the old `counters` metadata instead of reading the `html` string.
-- Trying to use removed surfaces such as `opensteer run`, `--input-json`, `--selector`, or `--description` target flags.
-- Forgetting to re-snapshot after navigation.

package/skills/opensteer/references/request-workflow.md

@@ -1,153 +0,0 @@
-# Opensteer Request Workflow
-
-Use this workflow when the task is to understand, validate, or reuse a site API.
-
-The deliverable is working TypeScript that uses `session.fetch()` or other SDK primitives. The deliverable is not a registry artifact or a raw replay dump.
-
-## Core Rules
-
-1. Capture real browser traffic instead of guessing request shapes.
-2. Use the filtered summaries first. Only drill into details when needed.
-3. Let `replay` tell you what transport works.
-4. Keep the final artifact as code, not as shell history.
-
-## Workflow
-
-### 1. Capture
-
-Trigger the real browser action that causes the request.
-
-```bash
-opensteer open https://example.com --workspace demo
-opensteer goto https://example.com/search --workspace demo --capture-network page-load
-opensteer input 5 laptop --workspace demo --persist "search input" --capture-network search
-opensteer click 7 --workspace demo --persist "search button" --capture-network search
-```
-
-Use meaningful capture labels. They make the next step much easier.
-
-### 2. Discover
-
-Scan the captured traffic.
-
-```bash
-opensteer network query --workspace demo --capture search
-opensteer network query --workspace demo --capture search --hostname api.example.com
-opensteer network query --workspace demo --capture search --url search --limit 20
-```
-
-Look for first-party JSON requests that actually carry the data you want. Ignore static assets, analytics, and third-party noise.
-
-### 3. Inspect
-
-Inspect the most promising record deeply.
-
-```bash
-opensteer network detail rec_123 --workspace demo
-```
-
-Read:
-
-- URL and method
-- request headers
-- cookies sent
-- request body preview
-- response headers
-- response body preview
-- GraphQL metadata when present
-- redirect chains when present
-
-### 4. Test
-
-Replay the captured request.
-
-```bash
-opensteer replay rec_123 --workspace demo
-opensteer replay rec_123 --workspace demo --query keyword=headphones --query count=10
-opensteer replay rec_123 --workspace demo --variables '{"keyword":"headphones"}'
-```
-
-Use the working transport that `replay` discovers as input to your final SDK code.
-
-### 5. Trace Dependencies
-
-If replay fails or returns `401`/`403`, inspect the surrounding state.
-
-```bash
-opensteer network query --workspace demo --before rec_123 --limit 50
-opensteer cookies example.com --workspace demo
-opensteer storage example.com --workspace demo
-opensteer state example.com --workspace demo
-```
-
-Use these to answer:
-
-- which cookies matter
-- which tokens live in storage
-- whether hidden fields or globals provide CSRF values or nonces
-- which earlier requests set the relevant state
-
-### 6. Write Code
-
-Translate what worked into plain TypeScript.
-
-```ts
-import { Opensteer } from "opensteer";
-
-const opensteer = new Opensteer({
-  workspace: "demo",
-  rootDir: process.cwd(),
-});
-
-async function ensureSession() {
-  const cookies = await opensteer.cookies("example.com");
-  if (cookies.has("session")) {
-    return;
-  }
-  await opensteer.goto("https://example.com");
-}
-
-export async function searchProducts(keyword: string) {
-  await ensureSession();
-
-  const response = await opensteer.fetch("https://api.example.com/search", {
-    query: {
-      keyword,
-      count: 24,
-    },
-  });
-
-  return response.json();
-}
-```
-
-If exploration showed a required transport, carry it into `fetch()`:
-
-```ts
-const response = await opensteer.fetch("https://api.example.com/search", {
-  query: { keyword: "laptop" },
-  transport: "matched-tls",
-});
-```
-
-## Common Cases
-
-### GraphQL
-
-- `network query` should surface the operation name next to the URL.
-- `network detail` should show operation type, operation name, and variables.
-- `replay --variables '{...}'` is the fastest way to test new inputs.
-
-### Redirect or Auth Chains
-
-Start with `network detail` on the failing request. If it shows redirects or challenge notes, inspect earlier records with `--before`.
-
-### Hidden Form Tokens
-
-Use `state example.com --workspace demo` when the request depends on hidden fields or globals that do not show up cleanly in cookies or storage alone.
-
-## What Not To Do
-
-- Do not stop at `network query` when the user asked for reusable code.
-- Do not bypass Opensteer with raw Playwright when Opensteer already captured the request.
-- Do not dump giant raw response blobs into the prompt when the filtered summaries already show the useful shape.

package/skills/opensteer/references/sdk-reference.md

@@ -1,157 +0,0 @@
-# Opensteer SDK Reference
-
-Use the SDK when the result should become reusable TypeScript in the repository.
-
-## Construction
-
-```ts
-import { Opensteer } from "opensteer";
-
-const opensteer = new Opensteer({
-  workspace: "demo",
-  rootDir: process.cwd(),
-});
-```
-
-Key options:
-
-- `workspace`: persistent repo-local browser state
-- `rootDir`: where `.opensteer` lives
-- `browser`: local browser mode or attach config
-- `provider`: cloud config when applicable
-
-## DOM Automation
-
-Explore with the CLI first. Use the snapshot `html` output to find `c="N"` element numbers.
-
-Persist a DOM action target during exploration:
-
-```ts
-await opensteer.click({
-  element: 3,
-  persist: "primary button",
-});
-
-await opensteer.input({
-  element: 7,
-  persist: "search input",
-  text: "laptop",
-  pressEnter: true,
-});
-```
-
-Replay it later without element numbers:
-
-```ts
-await opensteer.click({ persist: "primary button" });
-await opensteer.input({ persist: "search input", text: "laptop", pressEnter: true });
-```
-
-Persist works for extraction too:
-
-```ts
-const summary = await opensteer.extract({
-  persist: "page summary",
-  schema: {
-    title: { selector: "title" },
-    url: { source: "current_url" },
-  },
-});
-```
-
-Rules:
-
-- Use `persist` for reusable DOM targets and extraction descriptors.
-- Use `selector` only as a low-level escape hatch.
-
-## Network Discovery
-
-```ts
-await opensteer.goto("https://example.com/search", {
-  captureNetwork: "search",
-});
-
-const records = await opensteer.network.query({
-  capture: "search",
-  limit: 20,
-});
-
-const detail = await opensteer.network.detail(records.records[0]!.recordId);
-const replay = await opensteer.network.replay(records.records[0]!.recordId, {
-  query: { keyword: "headphones" },
-});
-```
-
-Use:
-
-- `network.query()` to shortlist requests
-- `network.detail()` to inspect one request deeply
-- `network.replay()` to confirm the transport and response shape
-
-## Browser State
-
-```ts
-const cookies = await opensteer.cookies("example.com");
-const localStorage = await opensteer.storage("example.com", "local");
-const sessionStorage = await opensteer.storage("example.com", "session");
-const browserState = await opensteer.state("example.com");
-```
-
-`cookies()` returns a small cookie-jar helper:
-
-```ts
-cookies.has("session");
-cookies.get("session");
-cookies.getAll();
-cookies.serialize();
-```
-
-## Session-Aware Fetch
-
-`fetch()` is the main replay primitive for final code.
-
-```ts
-const response = await opensteer.fetch("https://api.example.com/search", {
-  query: {
-    keyword: "laptop",
-    count: 24,
-  },
-});
-
-const data = await response.json();
-```
-
-If exploration showed a required transport:
-
-```ts
-const response = await opensteer.fetch("https://api.example.com/search", {
-  query: { keyword: "laptop" },
-  transport: "matched-tls",
-});
-```
-
-## Browser Admin
-
-```ts
-const status = await opensteer.browser.status();
-
-if (!status.live) {
-  await opensteer.browser.clone({
-    sourceUserDataDir: "/Users/me/Library/Application Support/Google/Chrome",
-    sourceProfileDirectory: "Default",
-  });
-}
-```
-
-## Recommended Rules
-
-- Explore with the CLI first, then write reusable SDK code.
-- Use `captureNetwork` on the real browser actions that trigger the traffic.
-- Let `replay` tell you the required transport instead of guessing.
-- Keep the final artifact as code, not as shell commands or giant logs.
-
-## What Not To Do
-
-- Do not build new abstractions on top of simple `fetch()` code unless the task really needs them.
-- Do not bypass Opensteer with raw Playwright when Opensteer already captured the request.
-- Do not dump giant raw response blobs into logs or prompts when the filtered previews already show the useful structure.