[codex] Clarify automation compare output

README.md

@@ -140,7 +140,7 @@ When you have a failed run and a known-good run for the same Browser Use task,
 use `browsertrace compare <failed_run_id> <success_run_id> --json` to locate
 the first divergent action, URL, status, or error field.
 
-For automation-oriented usage notes, see
+For the complete automation recipe, see
 [JSON CLI checks for automation](examples/#json-cli-checks-for-automation).
 
 For compact AI/coding-agent troubleshooting context, use
@@ -638,8 +638,8 @@ For concise contributor expectations and a welcoming baseline, read
 To choose the right bug, feature, integration, or cloud/team template, use the
 [issue template chooser](https://github.com/aaronlab/browsertrace/issues/new/choose).
 Before opening a PR, use the [pull request template](.github/PULL_REQUEST_TEMPLATE.md)
-and include a linked issue and test commands. It also asks you to inspect
-`git diff --stat` and `git diff --summary` for unexpected deleted or renamed files.
+and include a linked issue and test commands, plus a quick `git diff --stat` and
+`git diff --summary` review for unexpected deleted or renamed files.
 For security-sensitive reports or private trace data, follow
 [SECURITY.md](SECURITY.md) before sharing details publicly.
 

docs/integrations.html

@@ -347,7 +347,7 @@ <h2 id="aos-mapping">AOS mapping research</h2>
             <td data-label="BrowserTrace field">Status and error</td>
             <td data-label="Closest AOS shape"><code>steps/toolCallResult</code> with <code>isError</code></td>
             <td data-label="Status">partially mapped</td>
-            <td data-label="Current note">Document the research-only <code>toolCallResult</code> result shape as run status, step status, error message/type when available, action/tool label, step id, and public export/redaction state; this remains a research mapping, not an AOS compliance claim.</td>
+            <td data-label="Current note">A useful research-only <code>toolCallResult</code> result shape should include run status, step status, error type/message when available, action or tool label, step id, and redaction/export state; this is not an AOS compliance claim.</td>
           </tr>
           <tr>
             <td data-label="BrowserTrace field">Screenshot or future video artifact</td>

examples/README.md

@@ -266,6 +266,11 @@ Expected output:
 - `browsertrace list --status failed --json` prints recent failed runs as JSON, including run IDs and status values you can feed into automation.
 - `browsertrace show <run_id> --json` prints one run as JSON, including run details and step timeline data for that run.
 
+When the local BrowserTrace UI is running, scripts, dashboards, or automation
+checks can also call `GET /api/compare/<failed_run_id>/<success_run_id>` for
+the same first-divergence JSON payload shown by
+`browsertrace compare <failed_run_id> <success_run_id> --json`.
+
 For compact AI/coding-agent troubleshooting context, use
 [`docs/llms.txt`](../docs/llms.txt); it includes JSON CLI checks, project links,
 and prompts.

tests/test_metadata.py

@@ -665,13 +665,15 @@ def test_integrations_page_includes_aos_mapping_research_table():
     assert rows["Action label or tool call"][2] == "partially mapped"
     assert rows["Status and error"][1] == "steps/toolCallResult with isError"
     assert rows["Status and error"][2] == "partially mapped"
-    assert "research-only toolCallResult result shape" in rows["Status and error"][3]
+    assert "research-only" in rows["Status and error"][3]
+    assert "toolCallResult" in rows["Status and error"][3]
+    assert "result shape" in rows["Status and error"][3]
     assert "run status" in rows["Status and error"][3]
     assert "step status" in rows["Status and error"][3]
-    assert "error message/type" in rows["Status and error"][3]
-    assert "action/tool label" in rows["Status and error"][3]
+    assert "error type/message" in rows["Status and error"][3]
+    assert "action or tool label" in rows["Status and error"][3]
     assert "step id" in rows["Status and error"][3]
-    assert "public export/redaction state" in rows["Status and error"][3]
+    assert "redaction/export state" in rows["Status and error"][3]
     assert "not an AOS compliance claim" in rows["Status and error"][3]
     assert rows["Screenshot or future video artifact"][1] == (
         "FileWithUri preferred over inline FileWithBytes"
@@ -1635,6 +1637,9 @@ def test_readme_links_contributor_guide_near_contributing():
     assert "Before starting a good first issue" in contributing_section
     assert "comment on it first" in contributing_section
     assert "maintainers can treat it as claimed" in contributing_section
+    assert "[pull request template](.github/PULL_REQUEST_TEMPLATE.md)" in contributing_section
+    assert "git diff --stat" in contributing_section
+    assert "git diff --summary" in contributing_section
     assert "[good first issue queue]" in contributing_section
     assert good_first_issue_url in contributing_section
     assert contributing_section.count(good_first_issue_url) == 1
@@ -2558,6 +2563,10 @@ def test_readme_explains_isolated_trace_storage_near_install_tag():
         "By default, BrowserTrace stores local traces under `~/.browsertrace/`; "
         "set `BROWSERTRACE_HOME` to use an isolated trace store"
     ) in install_section
+    assert (
+        "[isolated trace storage recipe](examples/#testing-with-isolated-trace-storage)"
+        in install_section
+    )
     assert 'pip install "browsertrace[ui]"' in install_section
     assert "hosted sharing" not in readme
 
@@ -3168,6 +3177,9 @@ def test_examples_readme_includes_json_cli_checks_recipe():
 
     assert "### JSON CLI checks for automation" in troubleshooting_section
     assert "scripts, CI, or AI/coding-agent troubleshooting" in troubleshooting_section
+    assert "GET /api/compare/<failed_run_id>/<success_run_id>" in troubleshooting_section
+    assert "first-divergence JSON payload" in troubleshooting_section
+    assert "browsertrace compare <failed_run_id> <success_run_id> --json" in troubleshooting_section
     assert recipe in troubleshooting_section
     assert 'pip install "browsertrace[ui]"' in examples_readme
     assert "hosted sharing" not in examples_readme