opensteer 0.8.9 → 0.8.10

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

@@ -1,22 +1,10 @@
-# Opensteer Request Workflow
+# Request Plan Pipeline
 
 If you haven't decided whether this workflow applies, see the task triage in SKILL.md.
 
-Use this workflow when the deliverable is a custom API, a replayable request plan, or a lower-overhead path than full browser automation.
+## The Deliverable
 
-## Sections
-
-- [Critical Rules](#critical-rules)
-- [Standard Loop](#standard-loop)
-- [Transport Selection](#transport-selection)
-- [SDK Flow](#sdk-flow)
-- [CLI Equivalents](#cli-equivalents)
-- [Transport Probing](#transport-probing)
-- [Auth Token Acquisition](#auth-token-acquisition)
-- [Input Formats](#input-formats)
-- [Practical Guidance](#practical-guidance)
-- [When To Use Request Capture vs DOM Extraction](#when-to-use-request-capture-vs-dom-extraction)
-- [Error Recovery](#error-recovery)
+The deliverable is a **persisted request plan** that works via `request.execute`. `rawRequest()` is a diagnostic probe — its output is never the final answer. You are not done until `request.execute` returns valid data from a stored plan.
 
 ## Critical Rules
 
@@ -26,19 +14,6 @@ Use this workflow when the deliverable is a custom API, a replayable request pla
 4. `clearNetwork()` permanently removes records with tombstoning. Cleared records cannot be resurrected by late-arriving browser events.
 5. `waitForNetwork()` watches for NEW records only. It snapshots existing records and polls for ones that were not present at the start. It does NOT return historical matches.
 
-## Standard Loop
-
-1. Trigger the real browser action that causes the request inside a stable workspace.
-2. Name the important navigation or interaction with `captureNetwork` on the action itself.
-3. Inspect the captured traffic with `queryNetwork()` and isolate the relevant records.
-4. Use `tagNetwork()` to label interesting records for later lookup if you want extra manual labels.
-5. Probe the request with `rawRequest()` — try `direct-http` first, then `context-http`.
-6. Infer a request plan from the probed record — pass `transport` if you proved portability.
-7. Add recipes or auth recipes if replay needs deterministic setup.
-8. Replay the plan from code — works immediately, no extra steps.
-
-This workflow should carry equal weight with DOM automation. Use it whenever the browser page is only the launcher for the real target request.
-
 ## Transport Selection
 
 - `direct-http`: the request is replayable without a browser.
@@ -48,234 +23,378 @@ This workflow should carry equal weight with DOM automation. Use it whenever the
 
 When in doubt, start with browser-backed capture first. Opensteer treats browser-backed replay as a first-class path, not a fallback.
 
-## SDK Flow
+## Pipeline Phases
 
-1. Start a workspace-backed browser flow and tag navigation.
+Work through each phase in order. Do NOT skip phases. Each phase has exit criteria — verify them before proceeding.
 
-```ts
-await opensteer.open();
-await opensteer.goto({
-  url: "https://example.com/app",
-  captureNetwork: "page-load",
-});
+### Phase 1: Capture
 
-await opensteer.click({
-  description: "load products",
-  captureNetwork: "products-load",
-});
+Trigger the real browser action that causes the request. Name the capture.
+
+```bash
+opensteer open https://example.com/app --workspace demo
+opensteer run page.goto --workspace demo \
+  --input-json '{"url":"https://example.com/app","captureNetwork":"page-load"}'
 ```
 
-2. Inspect the captured traffic.
+For interactions that trigger API calls (search, filter, load-more):
 
-```ts
-const records = await opensteer.queryNetwork({
-  capture: "products-load",
-  includeBodies: true,
-  limit: 20,
-});
+```bash
+opensteer run dom.click --workspace demo \
+  --input-json '{"target":{"kind":"description","description":"load products"},"captureNetwork":"products-load"}'
 ```
 
-3. Probe the request — try `direct-http` first to test portability.
-
-```ts
-const response = await opensteer.rawRequest({
-  transport: "direct-http",
-  url: "https://example.com/api/products",
-  method: "POST",
-  body: {
-    json: { page: 1 },
-  },
-});
-// If direct-http returns 200, the API is portable (no browser needed).
-// If it fails, try context-http — the API needs browser session state.
+**EXIT CRITERIA:** You have at least one named capture. If `queryNetwork` returns empty after capture, see Error Recovery.
+
+### Phase 2: Discover
+
+Query captured traffic to isolate the API calls worth replaying. Ignore static assets, analytics, and third-party scripts.
+
+```bash
+opensteer run network.query --workspace demo \
+  --input-json '{"capture":"products-load","includeBodies":true,"limit":20}'
 ```
 
-4. Infer a request plan — pass `transport` if you proved portability.
+Examine the results. Look for first-party JSON APIs — requests returning `application/json` with data relevant to the task.
 
-```ts
-await opensteer.inferRequestPlan({
-  recordId: response.recordId,
-  key: "products.search",
-  version: "v1",
-  transport: "direct-http", // use the transport you proved works
-});
+If the first query is too broad, filter by hostname, path, or method:
+
+```bash
+opensteer run network.query --workspace demo \
+  --input-json '{"capture":"products-load","hostname":"api.example.com","method":"GET","includeBodies":true,"limit":10}'
 ```
 
-5. Tag additional records if you want extra manual labels on top of the action capture name.
+**EXIT CRITERIA:** You have identified at least one candidate API URL with its method, recordId, and response shape.
+
+### Phase 3: Probe (Diagnostic Only)
 
-```ts
-await opensteer.tagNetwork({
-  tag: "products-load",
-});
+`rawRequest()` is a diagnostic tool. Use it to determine:
+1. Which transport works (`direct-http` vs `context-http`)
+2. Whether the API returns the expected data shape
+3. Whether auth headers are actually required
+
+`rawRequest()` output is NOT the deliverable. Do NOT return rawRequest results to the user as the final answer. Always proceed to Phase 4.
+
+Test portability — try `direct-http` first:
+
+```bash
+opensteer run request.raw --workspace demo \
+  --input-json '{"transport":"direct-http","url":"https://api.example.com/products","method":"GET"}'
 ```
 
-Network history is SQLite-backed. Records are written to SQLite only for actions that opt into `captureNetwork`, or when later persisted by network inspection flows. The database initializes on first use.
+If `direct-http` returns 200, the API is portable. If it fails (403/401), try `context-http`:
+
+```bash
+opensteer run request.raw --workspace demo \
+  --input-json '{"transport":"context-http","url":"https://api.example.com/products","method":"GET"}'
+```
+
+**EXIT CRITERIA:** You know which transport works and have a successful response. Note the `recordId` from the probe response — you will use it in Phase 4.
+
+### Phase 4: Infer Plan
 
-6. Replay the plan from code.
+Create a request plan from the probed record. Pass the `transport` you proved works.
 
-```ts
-const result = await opensteer.request("products.search", {
-  query: { q: "laptop" },
-});
+```bash
+opensteer run request-plan.infer --workspace demo \
+  --input-json '{"recordId":"<recordId-from-phase-3>","key":"products.search","version":"v1","transport":"direct-http"}'
 ```
 
-7. Add a recipe or auth recipe if replay needs deterministic setup.
+If you proved `direct-http` works, always pass `transport: "direct-http"` so the plan is portable.
+
+If `inferRequestPlan` throws "registry record already exists", bump the version (e.g., `v2`).
+
+**EXIT CRITERIA:** Plan is persisted. You can verify with `request-plan.get`.
 
-```ts
-await opensteer.runRecipe({
-  key: "products.setup",
-});
+### Phase 5: Validate Auth Classification
 
-await opensteer.runAuthRecipe({
-  key: "products.auth",
-});
+`inferRequestPlan` records auth metadata by observing headers on the captured request. This is **often wrong**. If the browser sent an `Authorization` header, the plan records `auth.strategy: "bearer-token"` even if the API works without auth.
+
+**MANDATORY VALIDATION:**
+
+1. Read the inferred plan:
+
+```bash
+opensteer run request-plan.get --workspace demo \
+  --input-json '{"key":"products.search","version":"v1"}'
 ```
 
-## CLI Equivalents
+2. Check the `auth` field in `payload`. If `auth` is absent or `undefined`, auth is not detected — skip to Phase 6.
+
+3. If `auth.strategy` is set, test whether the API actually needs it. Run a raw request to the same URL with NO auth headers:
 
 ```bash
-opensteer open https://example.com/app --workspace demo
-opensteer run page.goto --workspace demo \
-  --input-json '{"url":"https://example.com/app","captureNetwork":"page-load"}'
-opensteer click --workspace demo --description "load products"
-  # or with captureNetwork: opensteer run dom.click --workspace demo \
-  #   --input-json '{"target":{"kind":"description","description":"load products"},"captureNetwork":"products-load"}'
-opensteer run network.query --workspace demo \
-  --input-json '{"capture":"products-load","includeBodies":true,"limit":20}'
 opensteer run request.raw --workspace demo \
-  --input-json '{"transport":"direct-http","url":"https://example.com/api/products","method":"POST","body":{"json":{"page":1}}}'
-opensteer run request-plan.infer --workspace demo \
-  --input-json '{"recordId":"rec_123","key":"products.search","version":"v1","transport":"direct-http"}'
-opensteer run request.execute --workspace demo \
-  --input-json '{"key":"products.search","query":{"q":"laptop"}}'
+  --input-json '{"transport":"direct-http","url":"<the-api-url>","method":"GET"}'
 ```
 
-## Transport Probing
+4. If it returns 200 without auth headers, auth is **spurious** — the browser attached a token the API doesn't enforce. Rewrite the plan with corrected auth:
 
-Test each discovered API with multiple transports to determine portability:
+```bash
+opensteer run request-plan.write --workspace demo \
+  --input-json '{
+    "key":"products.search",
+    "version":"v1",
+    "tags":["products","search"],
+    "provenance":{"source":"manual","notes":"Auth removed — API is public, bearer token was incidental."},
+    "payload":{
+      ...existing payload with auth field removed...
+    }
+  }'
+```
+
+Copy the full existing `payload` from `request-plan.get`, remove or null out the `auth` field, and write it back.
+
+5. If the no-auth probe returns 401/403, auth IS required. Keep the auth classification and proceed. You will create an auth recipe in Phase 8 after testing the plan.
+
+**EXIT CRITERIA:** The plan's `auth` field accurately reflects whether auth is required.
+
+### Phase 6: Annotate Parameters
+
+`inferRequestPlan` dumps all query and body parameters into `defaultQuery`/`defaultBody` without distinguishing variable from fixed.
+
+1. Read the plan with `request-plan.get`.
 
-```ts
-const direct = await opensteer.rawRequest({
-  transport: "direct-http",
-  url: discoveredUrl,
-  method: "GET",
-});
+2. Examine each parameter in `defaultQuery`:
+   - **Variable:** values that change per invocation — search terms, page numbers, offsets, dates, user-specific IDs
+   - **Fixed:** values constant for this API — site keys, platform identifiers, API versions, channel strings
 
-const context = await opensteer.rawRequest({
-  transport: "context-http",
-  url: discoveredUrl,
-  method: "GET",
-});
+3. Rewrite the plan with the `parameters` field annotating variable inputs:
+
+```bash
+opensteer run request-plan.write --workspace demo \
+  --input-json '{
+    "key":"products.search",
+    "version":"v1",
+    "payload":{
+      ...existing payload...,
+      "parameters":[
+        {"name":"keyword","in":"query","required":true,"description":"Search term"},
+        {"name":"count","in":"query","defaultValue":"24","description":"Results per page"},
+        {"name":"offset","in":"query","defaultValue":"0","description":"Pagination offset"}
+      ]
+    }
+  }'
 ```
 
-If `direct-http` returns 200, the API is portable and does not need a browser for future calls. If only `context-http` works, the API depends on browser session state.
+Variable params remain in `defaultQuery` as initial values. The `parameters` field documents which ones a caller should override via `request.execute` input.
+
+**EXIT CRITERIA:** The plan's `parameters` field lists all variable inputs with descriptions.
+
+### Phase 7: Test Plan
 
-After proving portability, infer the plan with an explicit transport override:
+Execute the plan through `request.execute`, NOT `rawRequest`:
 
-```ts
-await opensteer.inferRequestPlan({
-  recordId: records.records[0]!.id,
-  key: "products.search.portable",
-  version: "v1",
-  transport: "direct-http",
-});
+```bash
+opensteer run request.execute --workspace demo \
+  --input-json '{"key":"products.search","version":"v1","query":{"keyword":"laptop","count":"10"}}'
 ```
 
+**GATE:**
+- If `request.execute` returns valid data → proceed to Phase 9 (Done).
+- If `request.execute` returns 401/403 and Phase 5 confirmed auth is required → proceed to Phase 8 (Auth Recipe).
+- If `request.execute` fails with another error → see Error Recovery.
+
+### Phase 8: Auth Recipe (Conditional)
+
+Enter this phase ONLY if Phase 5 confirmed auth is genuinely required AND Phase 7 failed with 401/403.
+
+#### Step 8a: Discover Auth Endpoint
+
+Search captured traffic for OAuth, token, or login endpoints:
+
 ```bash
-opensteer run request-plan.infer --workspace demo \
-  --input-json '{"recordId":"rec_123","key":"products.search.portable","version":"v1","transport":"direct-http"}'
+opensteer run network.query --workspace demo \
+  --input-json '{"path":"/oauth","includeBodies":true,"limit":10}'
+opensteer run network.query --workspace demo \
+  --input-json '{"path":"/token","includeBodies":true,"limit":10}'
+opensteer run network.query --workspace demo \
+  --input-json '{"path":"/auth","includeBodies":true,"limit":10}'
 ```
 
-## Auth Token Acquisition
-
-When you discover an auth endpoint, acquire a token and use it to probe for data APIs that may be behind auth:
-
-```ts
-const tokenResp = await opensteer.rawRequest({
-  transport: "direct-http",
-  url: "https://example.com/api/oauth/token?scope=guest",
-  method: "POST",
-});
-
-let parsed = tokenResp.data;
-if (parsed === undefined) {
-  const body = tokenResp.response.body;
-  if (!body) {
-    throw new Error("Token response had no body");
-  }
-  parsed = JSON.parse(Buffer.from(body.data, "base64").toString("utf8"));
-}
-
-const token = String((parsed as { access_token: unknown }).access_token);
-
-const authed = await opensteer.rawRequest({
-  transport: "direct-http",
-  url: "https://example.com/api/products",
-  method: "GET",
-  headers: [{ name: "Authorization", value: `Bearer ${token}` }],
-});
+Examine responses to find the endpoint that returns an access token.
+
+#### Step 8b: Probe Auth Endpoint
+
+Test the auth endpoint with `request.raw`:
+
+```bash
+opensteer run request.raw --workspace demo \
+  --input-json '{
+    "transport":"direct-http",
+    "url":"https://example.com/api/oauth/token",
+    "method":"POST",
+    "body":{"json":{"grant_type":"client_credentials"}}
+  }'
 ```
 
-## Input Formats
+Verify it returns a token. Note the response shape (e.g., `{ "access_token": "..." }`).
 
-`rawRequest` expects specific shapes:
+#### Step 8c: Create Auth Recipe
 
-- `headers`: array of `[{ name, value }]`, not `{ key: value }`.
-- `body`: one of `{ json: { ... } }`, `{ text: "..." }`, or `{ base64: "..." }`. Not raw strings.
-- `request.execute` semantic input includes `key` inside the JSON object. The SDK convenience wrapper `opensteer.request(key, input)` adds that for you.
+Write an auth recipe that acquires a fresh token and maps it to request headers:
 
-## Practical Guidance
+```bash
+opensteer run auth-recipe.write --workspace demo \
+  --input-json '{
+    "key":"example.auth",
+    "version":"v1",
+    "payload":{
+      "description":"Acquire bearer token for example.com API",
+      "steps":[
+        {
+          "kind":"directRequest",
+          "request":{
+            "url":"https://example.com/api/oauth/token",
+            "transport":"direct-http",
+            "method":"POST",
+            "body":{"json":{"grant_type":"client_credentials"}}
+          },
+          "capture":{
+            "bodyJsonPointer":{"pointer":"/access_token","saveAs":"token"}
+          }
+        }
+      ],
+      "outputs":{
+        "headers":{"Authorization":"Bearer {{token}}"}
+      }
+    }
+  }'
+```
 
-Mandatory steps:
+**Recipe step types you can use:**
+- `directRequest` — HTTP request outside the browser (portable, no session needed)
+- `sessionRequest` — HTTP request using browser session state (cookies, etc.)
+- `request` — generic request step
+- `readCookie` — read a browser cookie value, `saveAs` a variable
+- `readStorage` — read localStorage/sessionStorage, `saveAs` a variable
+- `evaluate` — run JavaScript in the page, `saveAs` a variable
+- `waitForNetwork` — wait for a network request matching filters
+- `waitForCookie` — wait for a cookie to appear
+- `goto` — navigate to a URL (e.g., trigger a login page)
+- `solveCaptcha` — solve a CAPTCHA challenge
 
-- MUST use `goto({ url, captureNetwork })` to name navigation capture. `captureNetwork` is NOT supported on `open()`. In the CLI, this means `opensteer run page.goto --input-json ...`.
-- MUST query by capture first (`queryNetwork({ capture })`), then query all traffic to catch async requests.
-- MUST probe every discovered first-party API with transport tests. Do NOT just log URLs.
-- Only actions with `captureNetwork` are persisted at action time. Use `tagNetwork({ tag })` when you want to label already-persisted records for later lookup.
-- `queryNetwork({ ...filters })` always reads from the persisted store. It works the same whether the browser session is active or closed.
+Each step can have a `capture` field to extract values from the response. The `outputs` field maps captured variables to `headers`, `query`, `params`, or `body` overrides applied to the request plan at execution time.
 
-Common mistakes:
+#### Step 8d: Bind Auth Recipe to Plan
 
-- Do NOT pass headers as `{key: value}`. MUST use `[{name, value}]` arrays.
-- Do NOT pass body as a raw string. MUST wrap it in `{json: {...}}`, `{text: "..."}`, or `{base64: "..."}`.
-- Do NOT skip auth probing. If you find an OAuth endpoint, get a token and re-probe with it.
-- Do NOT treat "no data API found" as failure. It is a valid reverse-engineering conclusion that justifies DOM fallback.
-- Do NOT mix up recipes and auth recipes. They are separate registries and can reuse the same key/version independently.
+Update the plan to reference the auth recipe:
 
-Additional guidance:
+```bash
+opensteer run request-plan.get --workspace demo \
+  --input-json '{"key":"products.search","version":"v1"}'
+```
 
-- Capture the browser action first if authentication, cookies, or minted tokens may matter.
-- Probe with `direct-http` first. If it works, pass `transport: "direct-http"` to `inferRequestPlan` so the plan is portable. If it fails, fall back to `context-http`.
-- `inferRequestPlan()` throws if the key+version already exists. Catch the error or bump the version.
-- Inferred plans are immediately usable — `request.execute` works right after inference.
-- Use recipes when the request plan needs deterministic setup work. Use auth recipes when the setup is specifically auth refresh or login state.
-- Stay in the DOM workflow only when the rendered page itself is the deliverable. Move here when the request is the durable artifact.
+Read the current payload, then write it back with the `auth.recipe` binding:
 
-## When To Use Request Capture vs DOM Extraction
+```bash
+opensteer run request-plan.write --workspace demo \
+  --input-json '{
+    "key":"products.search",
+    "version":"v1",
+    "payload":{
+      ...existing payload...,
+      "auth":{
+        "strategy":"bearer-token",
+        "recipe":{"key":"example.auth","version":"v1"},
+        "failurePolicy":{"on":"status","status":"401","action":"recover"}
+      }
+    }
+  }'
+```
+
+The `failurePolicy` tells the plan to automatically re-run the auth recipe when a 401 is received.
+
+#### Step 8e: Test Authenticated Plan
+
+```bash
+opensteer run request.execute --workspace demo \
+  --input-json '{"key":"products.search","version":"v1","query":{"keyword":"laptop"}}'
+```
 
-See the task triage decision tree in SKILL.md for when to choose this workflow vs DOM extraction.
+The auth recipe fires automatically before the request. If it still fails, inspect the token response shape and fix the recipe.
+
+**EXIT CRITERIA:** `request.execute` returns valid data with the auth recipe attached.
+
+### Phase 9: Done
+
+Close the browser session:
+
+```bash
+opensteer close --workspace demo
+```
+
+The plan persists in the workspace registry and (if cloud mode) in Convex. Future callers can replay it with `request.execute` without opening a browser.
 
 ## Error Recovery
 
-**`queryNetwork()` returns empty records:**
+### `request.execute` returns 400 Bad Request
+
+1. Read the plan: `request-plan.get`
+2. Compare the plan's `defaultQuery`, `defaultBody`, and `defaultHeaders` against the original captured request from Phase 2
+3. Identify the discrepancy — missing required parameter, wrong content-type, malformed body
+4. Fix the plan with `request-plan.write`
+5. Re-test with `request.execute`
+6. If still failing after 2 fix attempts, use `request.raw` to isolate which specific parameter causes the 400 — remove params one at a time
+
+### `request.execute` returns 401/403 Unauthorized
+
+1. Was auth classification validated in Phase 5? If not, go back to Phase 5.
+2. If auth is confirmed needed, enter Phase 8 (Auth Recipe).
+3. If an auth recipe exists but fails, inspect the token response — the token may have expired, the scope may be wrong, or the grant type may differ.
+
+### `request.execute` returns 404 Not Found
+
+1. The API path may have changed since capture. Re-capture traffic (Phase 1) and re-discover (Phase 2).
+2. Check if the URL uses path parameters that were hardcoded during inference. These may need to be templated.
+
+### `request.execute` returns 500 Server Error
+
+This is the API server's problem, not a plan problem. Retry once. If persistent, document and report to the user.
+
+### `inferRequestPlan` throws "registry record already exists"
+
+The key+version combination is already registered. Bump the version string (e.g., `v1` → `v2`).
+
+### `queryNetwork()` returns empty records
+
 - Verify `captureNetwork` was set on the action that triggered the request (not on `open()`).
-- Re-trigger the action. Records are auto-persisted, so re-triggering will capture new records.
+- Re-trigger the action with `captureNetwork`. Records are auto-persisted on actions that opt in.
 - Broaden filters: try removing `tag` and querying by `hostname` or `path` instead.
 - Check that the request actually fired — some SPAs lazy-load data or use WebSocket instead of HTTP.
 
-**`rawRequest()` returns non-200 or errors:**
+### `rawRequest()` returns non-200
+
+This is diagnostic information. Use it to decide transport and debug, not as a final answer.
 - If `direct-http` fails with 403/401: the API requires session state. Try `context-http`.
-- If `context-http` fails: the API may require specific cookies or tokens. Check for auth endpoints in the captured traffic.
+- If `context-http` fails: the API may require specific cookies or tokens. Check for auth endpoints in captured traffic.
 - If the response body is empty: decode `response.body.data` with `Buffer.from(data, "base64").toString("utf8")` — the parsed `data` field may not be populated.
-- If the request times out: increase `timeoutMs` or check that the target server is reachable.
 
-**`waitForNetwork()` times out:**
-- `waitForNetwork()` only matches records that appear AFTER the call starts. If the request already fired, it will not be found.
-- Ensure the triggering action (click, scroll, etc.) happens AFTER calling `waitForNetwork()`, or use `queryNetwork()` instead for already-captured records.
-- Increase `timeoutMs` if the request is slow.
+### `waitForNetwork()` times out
 
-**`inferRequestPlan()` throws "registry record already exists":**
-- The key+version combination is already registered. Either use a new version string or catch the error.
+- `waitForNetwork()` only matches records that appear AFTER the call starts. If the request already fired, use `queryNetwork()` instead.
+- Ensure the triggering action happens AFTER calling `waitForNetwork()`.
 
-**`tagNetwork()` returns `taggedCount: 0`:**
-- No records matched the filters. Verify the records exist with `queryNetwork()` using the same filters first.
+## Input Formats
+
+`rawRequest` and recipe steps expect specific shapes:
+
+- `headers`: array of `[{ name, value }]`, not `{ key: value }`. Exception: recipe step `request` fields accept `{ key: value }` objects.
+- `body`: one of `{ json: { ... } }`, `{ text: "..." }`, or `{ base64: "..." }`. Not raw strings.
+- `request.execute` input includes `key` inside the JSON object. The SDK convenience wrapper `opensteer.request(key, input)` adds that for you.
+
+## Practical Guidance
+
+Mandatory steps:
+- MUST use `goto({ url, captureNetwork })` to name navigation capture. `captureNetwork` is NOT supported on `open()`.
+- MUST query by capture first, then query all traffic to catch async requests.
+- MUST probe every discovered first-party API with transport tests. Do NOT just log URLs.
+- The deliverable is a persisted plan. `rawRequest()` output is never the final answer.
+
+Common mistakes:
+- Stopping at `rawRequest` output and returning it to the user. Always proceed to `inferRequestPlan` and `request.execute`.
+- Trusting inferred auth metadata without validation. Always run Phase 5.
+- Passing headers as `{key: value}` to `rawRequest`. MUST use `[{name, value}]` arrays.
+- Passing body as a raw string to `rawRequest`. MUST wrap in `{json: {...}}`, `{text: "..."}`, or `{base64: "..."}`.
+- Skipping parameter annotation. Variable params should be documented in the plan's `parameters` field.
+- Not closing the browser after completing the pipeline. Always run `opensteer close` when done.