lanyue-llk · Oct 10, 2026 · Oct 10, 2026 · Oct 10, 2026 · Oct 10, 2026 · Oct 10, 2026
diff --git a/.agents/skills/README.md b/.agents/skills/README.md
@@ -0,0 +1,19 @@
+# Skill sources and updates
+
+`benchmark-report` and `benchmark-editorial` are maintained by this project. `humanizer` and `humanizer-chinese` are vendored dependencies:
+
+| Skill | Upstream | Installed source |
+| --- | --- | --- |
+| Humanizer | [blader/humanizer](https://github.com/blader/humanizer) | [Commit, version and hashes](humanizer/SOURCE.json) |
+| Humanizer Chinese | [jiji262/humanizer-chinese](https://github.com/jiji262/humanizer-chinese) | [Commit, version and hashes](humanizer-chinese/SOURCE.json) |
+
+Keep upstream `SKILL.md` and `LICENSE` bytes unchanged. `SOURCE.json` is project-maintained provenance and is not an upstream file. Put project-specific language, evidence and report requirements in `AGENTS.md` or the project-owned benchmark skills. Propose general improvements upstream rather than maintaining a private fork inside a vendored skill.
+
+To update either dependency:
+
+1. Resolve the upstream default branch to a full commit ID, inspect its changes and license, and download `SKILL.md` and `LICENSE` from that same commit.
+2. Replace the two files without translating, reformatting or adding project instructions. Include any newly required upstream support files in the provenance inventory.
+3. Update `SOURCE.json` with the repository URL, ref, commit, upstream version, retrieval date, license and SHA-256 of every copied file. Link to the pinned commit when reviewing the change. An unchanged upstream HEAD needs no invented version bump.
+4. Run `uv run --frozen --extra test python -m pytest tests/test_skill_sources.py -q` and verify the copied bytes against the downloaded upstream files. The offline test detects local drift; the upstream comparison establishes origin.
+
+Never execute downloaded upstream scripts as part of a skill update. Read the updated skill before applying it. Preserve copyright notices and check project integration for changed instructions.
diff --git a/.agents/skills/humanizer-chinese/SOURCE.json b/.agents/skills/humanizer-chinese/SOURCE.json
@@ -1,13 +1,13 @@
 {
   "repository": "https://github.com/jiji262/humanizer-chinese",
+  "ref": "main",
   "commit": "1d6c08e10fbfe0e1b36ac784834451c6aae0a92c",
   "version": "1.0.0",
   "license": "MIT",
-  "retrieved_on": "2026-09-10",
+  "retrieved_on": "2026-10-10",
   "unmodified_upstream_files": {
     "SKILL.md": "d582f32dd18f5dfcba881a65b8718ab293761ec6ea0a5fad14d81e2fe0899c1a",
     "LICENSE": "6e85ff980e3ecad4e609970f0d732785a5326086810ba11ed169208b65ca09c6"
   },
-  "hash_algorithm": "sha256",
-  "integration": "Repository-local dependency of benchmark-editorial. Chinese prose uses humanizer-chinese; English prose uses the existing sibling humanizer. No upstream scripts or global installation."
+  "hash_algorithm": "sha256"
 }
diff --git a/.agents/skills/humanizer/SKILL.md b/.agents/skills/humanizer/SKILL.md
diff --git a/.agents/skills/humanizer/SOURCE.json b/.agents/skills/humanizer/SOURCE.json
@@ -0,0 +1,13 @@
+{
+  "repository": "https://github.com/blader/humanizer",
+  "ref": "main",
+  "commit": "225a6f39ac85f76ee48dbad772ea4abe4ed6c9d8",
+  "version": "3.1.0",
+  "license": "MIT",
+  "retrieved_on": "2026-10-10",
+  "unmodified_upstream_files": {
+    "SKILL.md": "0612f1dfb1672b0ea9b97e139bf1f06cabe98d8b27424fe8ff01e1fb4cc99cad",
+    "LICENSE": "4ac4810254ab36d45419141aeb8e69bf50652cfafe5b2dab947d06d44e5cbf96"
+  },
+  "hash_algorithm": "sha256"
+}
diff --git a/.env.example b/.env.example
@@ -19,9 +19,9 @@ MOLI_1_0_6_BINARY=moli-1.0.6
 MOLI_1_1_3_BINARY=moli-1.1.3
 LIGHTPANDA_BINARY=lightpanda
 OBSCURA_BINARY=obscura
-# Pin the exact executable used by the cohort; do not leave this blank or rely
-# on Playwright's mutable bundled-browser fallback.
-CHROMIUM_BINARY=/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
+# Optional for the local quickstart, which can use Playwright's installed browser.
+# Formal cohorts must set the exact executable and bind its identity in their config.
+CHROMIUM_BINARY=
 # Cloudflare Browser Run constructs the account-scoped Kitesurf CDP endpoint
 # from these values. Do not persist an Authorization header or token in evidence.
 CLOUDFLARE_ACCOUNT_ID=

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -10,6 +10,23 @@ on:
   pull_request:
 
 jobs:
+  base-python:
+    name: Base CLI / Python ${{ matrix.python }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.7.8"
+      - run: uv sync --frozen --python "${{ matrix.python }}" --extra test
+      - run: uv run --frozen --python "${{ matrix.python }}" --no-sync python -m pytest tests/test_portable_cli.py tests/test_cli_scope.py tests/test_web_fetch_quickstart.py -q
   test:
     runs-on: ubuntu-latest
     steps:

diff --git a/CITATION.cff b/CITATION.cff
@@ -0,0 +1,11 @@
+cff-version: 1.2.0
+message: "If you use Browser Eval in your work, please cite this repository."
+type: software
+title: Browser Eval
+authors:
+  - name: Browser Eval contributors
+repository-code: "https://github.com/lexmount/browser-eval"
+url: "https://github.com/lexmount/browser-eval"
+version: 0.1.0
+date-released: 2026-10-10
+license: MIT
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,37 +1,67 @@
 # Contributing
 
-PRs are welcome for browser adapters, task definitions, tests, scoring fixes, documentation and README translations. Run the offline example in [README](README.md), then read the relevant track guide. For bug reports, include the task ID, adapter type, versions, OS, reproduction command and sanitized errors. Do not include credentials or session data.
+PRs are welcome for adapters, tasks, tests, scoring fixes, documentation and translations. Run the [offline example](README.md#quickstart), then open the guide for the track you want to change.
 
-## Language
+## Report a bug
 
-English is the primary language for documentation, contribution guidance and automated review. Keep the English README and [Chinese README](docs/README.zh-CN.md) aligned when changing setup or usage. Additional README translations are welcome; other documentation does not need a translated copy. Preserve original task text, source quotations and frozen acceptance artifacts. Report languages follow their track's build contract.
+Include the task ID, method and versions, OS, command and sanitized error. Remove keys, cookies and session data.
 
-## Implementation and evidence
+## Make a change
 
-Extend existing execution, scoring, aggregation and report modules. Select browsers, versions and cohort sizes through configuration or registries rather than copying runners or renderers. Commands belong in `scripts/`; reusable logic belongs in `harness/`.
+| Change | Where it belongs |
+| --- | --- |
+| Browser or provider adapter | Existing execution modules; see the [provider contract](docs/provider-contract.md) |
+| Task requirements | Dataset configuration, applied to every method |
+| Scoring fix | Shared scorer, scenario regressions and a recorded correction reason |
+| New browser, version or sample size | Configuration or registry; reuse the runner and renderer |
+| Reusable logic | `harness/`; `scripts/` stays a thin command entry point |
 
-Behavior changes need scenario tests for both accepted and rejected inputs. Scoring corrections also need regression controls through the shared scorer and revision provenance. Do not patch stored verdicts. Refactoring must not re-certify historical measurements or certificates.
+Test both accepted and rejected scenarios. Fix scoring rules rather than editing saved verdicts. Refactoring must preserve historical measurements and certificates.
 
-## Checks
+Write documentation in English. Keep the [Chinese README](docs/README.zh-CN.md) aligned when setup or usage changes; other docs do not need duplicate translations. Preserve original task text, quotations and frozen acceptance inputs. Reports follow their track's language settings.
 
-Run `make ci` before submitting. Development tests use Node.js 22, including `node:module.stripTypeScriptTypes`; the base Python example does not need Node.js. `make lint-check` checks basic Python errors across the repository and applies the full configured Ruff rules to the declared tracks. Both are part of CI.
+## Run the checks
 
-`make ci` includes `make package-check`: build a source archive, build a wheel from it, then test base and optional installations outside the checkout. The gate checks current modules and declared resources byte for byte, TypeScript tool bridging, synthetic TEDS revisions, LangChain extraction and Crawl4AI downloads against local HTTP fixtures. It rejects missing, stale or extra installed files. Use `make package-check` separately when changing distribution configuration.
+```bash
+make setup-test
+make ci
+```
+
+Development checks use Python 3.11 and Node.js 22. The base example does not need Node.js.
+
+| Check | What it covers |
+| --- | --- |
+| `make lint-check` | Basic Python errors across the repository and configured Ruff rules for the declared tracks |
+| `make package-check` | Source archive → wheel → base/optional installation outside the checkout |
+| `make test-reference-inputs` | Strict historical-input checks after importing [approved reference copies](docs/reference-inputs.md) |
+| Track release gate | Evidence, report presentation and browser checks before packaging or publishing |
+
+`make ci` includes linting and package checks. It runs without historical pages: only tests requiring absent historical inputs are skipped. Corrupt installed inputs fail; strict reference mode also fails on missing or incomplete sets.
 
-For report releases, also run the track's full release gate. Inspect success and failure details, evidence dialogs and return navigation at desktop and narrow widths in both themes. Real-service requirements are documented in the track guides.
+For report releases, open success and failure details, evidence dialogs and return links on desktop and narrow viewports in both themes. Real services need the environments listed in their track guides.
 
-Tests do not download historical pages. Install approved external inputs using the [reference-input guide](docs/reference-inputs.md), then run `make test-reference-inputs` for historical checks. Strict mode rejects missing, changed or incomplete inputs before tests start. Ordinary mode skips only checks requiring absent historical inputs; corrupt installed inputs still fail.
+<details>
+<summary>What the package gate tests</summary>
 
-## Distribution boundaries
+The gate builds a source archive, then a wheel from that archive. It compares installed modules and resources byte for byte and exercises TypeScript tool bridges, synthetic TEDS revisions, LangChain extraction and Crawl4AI downloads against local HTTP fixtures, including HTTP failures. Missing, stale or extra installed files fail the gate. Node tests use `node:module.stripTypeScriptTypes`.
 
-Do not commit `.env`, tokens, cookies, provider outputs, run directories, generated reports or private review records. Retain third-party origins, versions and licenses. Adding a task definition does not grant redistribution rights to its source page.
+</details>
 
-For the first public release, export the reviewed current tree and initialize a new public history. Do not push development history that still contains externalized source material; deleting a current file does not remove earlier copies.
+## Keep private data out of Git
+
+Do not commit `.env`, tokens, cookies, provider outputs, run directories, generated reports or private reviews. Keep third-party sources, versions and licenses. A task definition does not grant permission to redistribute its source page.
+
+<details>
+<summary>Maintainer reference: source exports and historical inputs</summary>
+
+A current-source export excludes old commits that may still contain externalized material. Review development history before distributing it; deleting a current file does not remove its earlier copies.
 
 ```sh
 git archive --format=tar.gz --output=/tmp/browser-eval-source.tar.gz HEAD
 ```
 
 The archive excludes `.git`, untracked files and local installations. Extract it, follow README setup and run `make ci` with an empty `BROWSER_EVAL_DATA_HOME`. Historical certifier sources retained by manifests are read-only, hash-bound text inputs, not executable entry points or dependencies on old Git commits. See [third-party content](THIRD_PARTY.md) and [reference inputs](docs/reference-inputs.md).
 
-Optional Claude review requires maintainers to set `ENABLE_CLAUDE_REVIEW=true` and `CLAUDE_CODE_OAUTH_TOKEN`. Ordinary CI needs neither. Review runs on disposable GitHub-hosted runners without personal machine paths.
+</details>
+
+Optional Claude review requires `ENABLE_CLAUDE_REVIEW=true` and `CLAUDE_CODE_OAUTH_TOKEN`. Ordinary CI needs neither. Review uses disposable GitHub-hosted runners.