markkit 0.1.1__tar.gz → 0.2.0__tar.gz

markkit-0.2.0/.agents/skills/maintain/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: maintain
+description: Analyze, fix, validate, and ship Markkit maintenance through green CI and merge. Trigger on run maintenance, maintain, maintainace, or maintaiance; use analysis-only mode only when explicitly requested.
+user_invocable: true
+metadata:
+  internal: true
+---
+
+# Markkit maintenance
+
+A request to run maintenance authorizes the full outcome: analyze the repository,
+fix findings, validate, push, open a PR, resolve review/CI failures, and squash-merge
+when every required check is green. A local commit or a list of follow-up issues
+is not completion. Explicit analysis-only requests omit edits and shipping.
+
+Read `knowledge/operations/maintenance.md` and execute its checklist, then use the
+`ship` skill. Sync from latest `origin/main` before editing. Split independent
+fixes into separate small PRs (one for structure/docs, one per behavior fix).
+
+Keep findings in the active pass and fix root causes. A large diff, missing audit,
+failed local check, or long build is work to complete, not a reason to defer.
+Never weaken tests, resource limits, or `deny.toml` policy to ship an upgrade.
+If the newest upstream version breaks a security contract, establish that, keep
+the newest safe version with a tested and documented pin, and finish the pass.
+
+Audit CI definitions, not only results: run the Workflow credential audit in
+`knowledge/operations/maintenance.md` against `.github/workflows/` (top-level
+`permissions`, `persist-credentials: false`, secrets via step `env:` only, no
+`pull_request_target`/`workflow_run`/`issue_comment`, no `${{ github.event.* }}`
+inside `run:`). A finding there is a fix in this pass.
+
+Smoke test real-world shaped input, not only fixtures: run the CLI on indented,
+multi-block HTML and on each office format, and read the output.
+
+Only stop for a missing permission, unavailable service, or user decision that
+cannot be resolved within the task. Report evidence and continue independent work.
+Never merge red CI or claim success while a required check is unfinished.
+
+Finish by appending a factual entry to the Pass record in
+`knowledge/operations/maintenance.md` and a `knowledge/log.md` entry. The final
+response names the merged PRs, key fixes, verification, and accepted constraints.

{markkit-0.1.1 → markkit-0.2.0}/.agents/skills/process-issues/SKILL.md

@@ -1,3 +1,11 @@
+---
+name: process-issues
+description: Resolve open GitHub issues for Markkit, one shipped PR per issue. Trigger when user says process issues, work through issues, resolve issues, or handle open issues.
+user_invocable: true
+metadata:
+  internal: true
+---
+
 Process open GitHub issues and resolve them via merged pull requests.
 
 ## Qualifying Issues
@@ -29,7 +37,7 @@ One issue = one PR. No bundling. No skipping.
 
 ### 4. Ship
 - Use the `/ship` skill for:
-  - Spec updates
+  - Knowledge updates (`knowledge/`)
   - Quality gates
   - PR creation
   - CI verification

markkit-0.2.0/.agents/skills/ship/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: ship
+description: Run the full Markkit ship flow — verify quality, ensure test coverage, update artifacts, smoke test, push, create PR, merge when CI is green, and confirm main is green after merge. Trigger when user says ship, ship it, fix and ship, asks to push and merge a branch, or runs maintenance.
+user_invocable: true
+metadata:
+  internal: true
+---
+
+Run the full ship flow: verify quality, ensure test coverage, update artifacts,
+smoke test, then push, create PR, merge when CI is green, and verify `main`.
+
+Implements the Shipping definition and Pre-PR Checklist in `AGENTS.md`. "Ship" =
+change landed on `main`, every CI check green on the PR and on the merge commit,
+tested, ready to release. Execute ALL phases, not just push/merge.
+
+## Arguments
+
+- `$ARGUMENTS` - Optional: what is being shipped (PR title/body context, scopes checks)
+
+## Phase 1: Pre-flight
+
+1. Confirm not on `main`
+2. Detached `HEAD` with task changes: create a branch first
+3. Uncommitted changes belong to the task: keep going, validate and commit them. Unrelated: stop and tell the user
+4. `git config user.name`/`user.email` are human (see `AGENTS.md` Commit Attribution)
+5. Branch's PR already merged: restart branch from `origin/main`, new PR; never stack on merged history
+
+## Phase 2: Test Coverage
+
+Review `git diff origin/main...HEAD` and `git log origin/main..HEAD`:
+
+1. Identify every changed code path
+2. `just test`; fix failures
+3. Add missing tests:
+   - **Positive**: happy path, valid input
+   - **Negative**: invalid input, errors, boundaries, limits
+   - **Security**: parsing, limits, or URL fetching changes add tests per
+     `knowledge/security/threat-model.md` and update its Test Coverage map
+   - **Golden fixtures**: HTML conversion changes add `tests/fixtures/html/<name>.{html,md}`
+   - **Bindings**: exported API changes extend the smoke calls in `python.yml` / `js.yml` (no binding test suites yet)
+4. `just test` green
+
+## Phase 3: Artifact Updates
+
+Skip what isn't affected.
+
+1. **Knowledge** (`knowledge/`): update affected concepts in the same change; add a `knowledge/log.md` entry; `just check-okf`
+2. **Threat model**: new input surface or limit → new/updated entry, keep `T*`/`S*` ids stable
+3. **AGENTS.md**: new commands, knowledge concepts, workflow changes
+4. **README.md / docs/**: user-facing behavior, flags, API
+5. **Binding READMEs**: exported function changes in `markkit-python` / `markkit-js`
+6. **CHANGELOG.md**: Unreleased entry for user-facing changes (release notes come from it)
+
+## Phase 3b: Simplification
+
+Duplication, deep nesting, dead code, unclear names, needless abstraction. If changed, back to Phase 2.
+
+## Phase 3c: Security Review
+
+1. Untrusted input validated and bounded before use (size, depth, counts)
+2. No unbounded allocation driven by attacker-controlled headers or sizes
+3. Errors don't leak raw input or internal paths
+4. No code execution paths (scripts, macros, formulas, entities)
+5. `unsafe` justified and sound
+
+Fix, add regression tests, update the threat model.
+
+## Phase 3d: Design Quality
+
+Real domain types over stringly-typed interfaces; specific error variants; no
+compatibility shims (fix call sites); no premature generics; visibility protects
+invariants. If refactored, back to Phase 2.
+
+## Phase 4: Smoke Testing
+
+1. CLI: `just run extract --file <file>` on realistic input (indented HTML, office docs); read the output
+2. Examples: `just examples`
+3. Bindings or core changed: build them (`maturin develop` / `napi build`) and call the changed function
+4. Packaging changed (`Cargo.toml` metadata, features, included files): `just publish-dry-run`
+
+Issues found: fix, back to Phase 2.
+
+## Phase 5: Quality Gates
+
+```bash
+git fetch origin main && git rebase origin/main
+just pre-pr
+```
+
+- Resolve rebase conflicts, rerun affected checks; ask only when a conflict needs a user decision
+- Fix root causes; never bypass hooks or weaken tests/audit policy
+
+## Phase 6: Push and PR
+
+```bash
+git push -u origin <branch>
+```
+
+Existing PR for the branch: update title/body if needed. Otherwise create one:
+
+- **Title**: conventional commit style
+- **Body**: `.github/pull_request_template.md`; functional change and impact, not a file walkthrough
+- **Evidence**: Before / After (CLI output, test results); say so when nothing observable changed
+
+## Phase 7: CI and Merge
+
+- Wait for CI with bounded checks (`gh pr checks` or GitHub MCP); elapsed time alone is not a blocker
+- "Green" = every check on the PR passed: `ci.yml` aggregate `Check`, `coverage.yml`, and
+  `python.yml` / `js.yml` when path-triggered. Pending or cancelled is not green
+- Failure: read logs, fix root cause, push, wait again. Red on `main` too: fix it here or
+  in a prerequisite PR; never merge over it
+- All checks green and review threads resolved: squash-merge, confirm the PR state is merged.
+  Enabling auto-merge alone is not completion
+- **NEVER** merge red CI
+
+## Phase 8: Post-merge Verification
+
+Shipping ends on `main`, not at the merge button.
+
+1. Find the push-triggered runs for the squash commit on `main` (`ci.yml`, `coverage.yml`,
+   path-triggered `python.yml` / `js.yml`); wait until they finish
+2. Any red: fix forward immediately (new branch from `origin/main`, new PR, same flow); not shipped until green
+3. Report: merged PR URL, merge commit, `main` CI result, and whether `CHANGELOG.md`
+   Unreleased is ready for a release (`knowledge/operations/release-process.md`)
+
+## Rules
+
+- Phases 2-4 are the quality core; never skip them
+- Not done until Phase 8 confirms `main` green
+- "Fix and ship": implement first, then ship
+- Partial issue coverage: `Part of #N`, not `Closes #N`
+- Ship ≠ release: don't tag or publish unless asked ("Create release v0.X.Y")

markkit-0.2.0/.claude/commands/maintain.md

@@ -0,0 +1,10 @@
+Analyze, fix, and ship Markkit maintenance. "Run maintenance" (including
+"maintainace" and "maintaiance") requests the complete shipped outcome.
+
+Read `.agents/skills/maintain/SKILL.md`, execute the checklist in
+`knowledge/operations/maintenance.md`, then run `.agents/skills/ship/SKILL.md`
+through green CI and squash-merge. `$ARGUMENTS` may scope the maintenance area;
+an explicit analysis-only request is the only exception to fixing and shipping.
+
+Do not replace fixes, audits, or validation with deferral issues or stop at a
+local commit. Preserve security contracts, fix CI failures, never merge red checks.

markkit-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,20 @@
+## What changed
+Describe the change functionally — what behavior changes and its impact on users
+or callers. Lead with outcomes; don't walk through code locations, the diff shows
+where and how. Keep any code-level notes short and specific.
+
+## Why
+Problem or motivation.
+
+## Before / After
+Show the effect with evidence. Include before and after whenever behavior changes —
+CLI/API output, logs, metrics, or screenshots for UI (attach working screenshots
+when possible). For changes with no observable behavior (pure refactor, docs), say so.
+
+## Risk
+- Low / Medium / High
+- What can break
+
+## Checklist
+- [ ] Tests added or updated
+- [ ] Backward compatibility considered

markkit-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,160 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+env:
+  CARGO_TERM_COLOR: always
+  RUSTFLAGS: -Dwarnings
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@v2
+      - name: Check formatting
+        run: cargo fmt --all -- --check
+      - name: Clippy
+        run: cargo clippy --workspace --all-targets -- -D warnings
+      - name: Build docs
+        run: cargo doc --workspace --no-deps
+        env:
+          RUSTDOCFLAGS: -Dwarnings
+      # OKF v0.2 conformance of knowledge/. okf-lint enforces the spec;
+      # check_okf.py enforces bundle-local conventions it does not cover.
+      # Keep the version and --max-line-length in lockstep with the justfile.
+      - name: Install okf-lint
+        run: cargo install okf-lint --version 0.1.1 --locked
+      - name: Check knowledge bundle (OKF)
+        run: |
+          python3 scripts/check_okf.py knowledge
+          okf-lint knowledge --max-line-length 10000
+      - name: Test repo scripts
+        run: python3 -m unittest discover -s scripts/tests -p 'test_*.py'
+
+  audit:
+    name: Audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Install cargo-audit
+        run: cargo install cargo-audit
+      - name: Install cargo-deny
+        run: cargo install cargo-deny
+      - name: Security audit
+        run: cargo audit
+      - name: License and dependency check
+        run: cargo deny check
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - name: Run tests
+        run: cargo test --workspace
+      - name: Run tests (all features)
+        run: cargo test --workspace --all-features
+      - name: Rust OCR model integration
+        env:
+          MARKKIT_OCR_MODEL_DIR: ${{ github.workspace }}/target/ocr-models
+          RTEN_NUM_THREADS: '1'
+          RAYON_NUM_THREADS: '1'
+        run: |
+          python3 scripts/prepare_ocr_models.py
+          cargo test --release -p markkit --features pdf-ocr-ocrs --test pdf_ocr ocrs_recognizes_scanned_text_with_source_word_geometry -- --include-ignored
+      - name: Run tests (office formats, no HTTP client)
+        run: |
+          if cargo tree -p markkit -e normal | grep -E 'reqwest|hyper'; then
+            echo "HTTP client leaked into the default feature set"
+            exit 1
+          fi
+          # Always-on formats (text, CSV, notebooks) must keep every limit with no format feature.
+          cargo test -p markkit --no-default-features
+          cargo test -p markkit --no-default-features --features docx,spreadsheet,markdown,email,odt,epub
+          if cargo tree -p markkit --no-default-features --features docx,spreadsheet,markdown,email,odt,epub -e normal | grep -E 'reqwest|hyper'; then
+            echo "HTTP client leaked into the docx,spreadsheet,markdown,email,odt,epub feature set"
+            exit 1
+          fi
+          if cargo tree -p markkit --no-default-features --features docx,spreadsheet -e normal | grep -E 'tokio'; then
+            echo "tokio leaked into the docx,spreadsheet feature set"
+            exit 1
+          fi
+          if cargo tree -p markkit -e normal | grep -E 'tokio'; then
+            echo "tokio leaked into the default feature set"
+            exit 1
+          fi
+      - name: Run examples
+        run: |
+          for ex in basic custom_selectors configuration ir_access transforms; do
+            cargo run -q -p markkit --example "$ex"
+          done
+          cargo run -q -p markkit --features tool --example agent_tool
+
+  wasm:
+    # Browser package @everruns/markkit-wasm: build the wasm32-unknown-unknown
+    # bundle and run its headless Node tests. See knowledge/runtimes/wasm-package.md.
+    name: WASM web package
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: wasm32-unknown-unknown
+      - uses: Swatinem/rust-cache@v2
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24.22.1"
+      - name: Check core for wasm32 (no warnings)
+        run: cargo check -p markkit --no-default-features --features html,docx,spreadsheet,markdown,tool --target wasm32-unknown-unknown
+      - name: Install wasm-bindgen-cli (matches Cargo.lock)
+        run: bash scripts/install-wasm-bindgen.sh
+      - name: Build package
+        run: bash crates/markkit-wasm/scripts/build.sh release
+      - name: Integration tests (headless Node)
+        run: node --test crates/markkit-wasm/__test__/*.test.mjs
+      - name: Verify npm archive contents
+        run: |
+          cd crates/markkit-wasm/pkg
+          npm pack --dry-run --json --ignore-scripts > "$RUNNER_TEMP/wasm-pack.json"
+          node -e 'const files=new Set(require(process.argv[1])[0].files.map(f=>f.path)); for (const f of ["index.js","index.d.ts","markkit_wasm.js","markkit_wasm_bg.wasm","README.md"]) if(!files.has(f)) throw Error("archive lacks "+f)' "$RUNNER_TEMP/wasm-pack.json"
+
+  check:
+    name: Check
+    needs: [lint, audit, test, wasm]
+    runs-on: ubuntu-latest
+    if: always()
+    steps:
+      - name: All jobs passed
+        run: |
+          if [[ "${{ needs.lint.result }}" != "success" ]] || \
+             [[ "${{ needs.audit.result }}" != "success" ]] || \
+             [[ "${{ needs.test.result }}" != "success" ]] || \
+             [[ "${{ needs.wasm.result }}" != "success" ]]; then
+            echo "One or more jobs failed"
+            exit 1
+          fi

{markkit-0.1.1 → markkit-0.2.0}/.github/workflows/coverage.yml

@@ -6,18 +6,25 @@ on:
   pull_request:
     branches: [main]
 
+permissions:
+  contents: read
+
 jobs:
   coverage:
     name: Code Coverage
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
       - uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
       - name: Install cargo-tarpaulin
         run: cargo install cargo-tarpaulin
       - name: Generate coverage
-        run: cargo tarpaulin --workspace --out xml
+        # llvm engine: the default ptrace engine segfaults on multi-threaded
+        # tokio socket tests (tests/url_security.rs)
+        run: cargo tarpaulin --workspace --engine llvm --out xml
       - name: Upload coverage
         uses: codecov/codecov-action@v4
         with:

markkit-0.2.0/.github/workflows/fuzz.yml

@@ -0,0 +1,74 @@
+name: Fuzz
+
+# Nightly cargo-fuzz run of every target in crates/markkit/fuzz (too slow
+# for PRs). Each target checks the S17 output oracle, not just "no panic".
+# Crashes upload as artifacts; reproduce with
+#   cargo +nightly fuzz run <target> <artifact>   (from crates/markkit)
+# See knowledge/security/fuzzing.md.
+
+on:
+  schedule:
+    - cron: "0 3 * * *"
+  workflow_dispatch:
+    inputs:
+      duration:
+        description: "Seconds per target (positive integer)"
+        required: false
+        default: "300"
+
+permissions:
+  contents: read
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  fuzz:
+    name: Fuzz ${{ matrix.target }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    strategy:
+      fail-fast: false
+      matrix:
+        target: [html, document, docx_xml, xlsx_xml, xlsb_bin, ods_xml, xls_biff, pdf, markdown, csv, render_ir]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@nightly
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: crates/markkit/fuzz
+      - name: Install cargo-fuzz
+        run: cargo install cargo-fuzz --locked
+      - name: Cache corpus
+        uses: actions/cache@v4
+        with:
+          path: crates/markkit/fuzz/corpus/${{ matrix.target }}
+          key: fuzz-corpus-${{ matrix.target }}-${{ github.run_id }}
+          restore-keys: fuzz-corpus-${{ matrix.target }}-
+      - name: Run ${{ matrix.target }}
+        working-directory: crates/markkit
+        env:
+          TARGET: ${{ matrix.target }}
+          DURATION_INPUT: ${{ github.event.inputs.duration || '300' }}
+        run: |
+          # workflow_dispatch input: validate before it reaches the shell.
+          if ! [[ "$DURATION_INPUT" =~ ^[1-9][0-9]{0,4}$ ]]; then
+            echo "::error::duration must be a positive integer (max 5 digits), got: $DURATION_INPUT"
+            exit 1
+          fi
+          # New inputs go to the first (cached) dir; the rest are read-only seeds.
+          mkdir -p "fuzz/corpus/$TARGET"
+          seeds=()
+          [ -d "fuzz/seeds/$TARGET" ] && seeds+=("fuzz/seeds/$TARGET")
+          [ "$TARGET" = html ] && seeds+=(tests/fixtures/html)
+          cargo +nightly fuzz run -O "$TARGET" "fuzz/corpus/$TARGET" "${seeds[@]}" -- \
+            -max_total_time="$DURATION_INPUT" -max_len=65536 -print_final_stats=1
+      - name: Upload crashes
+        if: failure()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: fuzz-crashes-${{ matrix.target }}
+          path: crates/markkit/fuzz/artifacts/${{ matrix.target }}
+          retention-days: 30

{markkit-0.1.1 → markkit-0.2.0}/.github/workflows/js.yml

@@ -12,12 +12,17 @@ on:
       - "crates/markkit-js/**"
       - "crates/markkit/**"
 
+permissions:
+  contents: read
+
 jobs:
   build:
     name: Build Node.js bindings
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
       - uses: dtolnay/rust-toolchain@stable
       - uses: actions/setup-node@v4
         with:
@@ -28,6 +33,8 @@ jobs:
         run: cd crates/markkit-js && npx --no-install napi build --release --platform
       - name: Verify build preserved the patched lockfile
         run: git diff --exit-code -- Cargo.lock
+      - name: Binding tests
+        run: cd crates/markkit-js && node --test __test__/*.test.cjs
       - name: Verify installed npm package
         run: |
           cd crates/markkit-js

{markkit-0.1.1 → markkit-0.2.0}/.github/workflows/nightly.yml

@@ -5,12 +5,17 @@ on:
     - cron: "0 4 * * *"
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   nightly:
     name: Nightly checks
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
       - uses: dtolnay/rust-toolchain@nightly
         with:
           components: rustfmt, clippy

markkit-0.2.0/.github/workflows/public-benchmarks.yml

@@ -0,0 +1,74 @@
+name: Public benchmarks
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  schedule:
+    - cron: "30 5 * * *"
+  workflow_dispatch:
+    inputs:
+      scope:
+        description: "Dataset selection (test quality is report-only)"
+        type: choice
+        options: [pr, dev, test]
+        default: pr
+
+permissions:
+  contents: read
+
+concurrency:
+  group: public-benchmarks-${{ github.ref }}-${{ github.event_name }}
+  cancel-in-progress: true
+
+jobs:
+  benchmark:
+    name: Public benchmark regressions
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    env:
+      # Input is data, never shell code; prepare/run additionally validate choices.
+      BENCHMARK_SCOPE: ${{ github.event_name == 'schedule' && 'dev' || inputs.scope || 'pr' }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - name: Cache verified corpora
+        uses: actions/cache@v4
+        with:
+          path: |
+            target/public-benchmarks/wcxb
+            target/public-benchmarks/agentdocbench
+          key: public-corpora-${{ hashFiles('scripts/public_benchmarks/pins.json', 'scripts/public_benchmarks/*corpus.json', 'scripts/public_benchmarks/agentdocbench-assets.json') }}-${{ env.BENCHMARK_SCOPE }}
+          restore-keys: public-corpora-${{ hashFiles('scripts/public_benchmarks/pins.json', 'scripts/public_benchmarks/*corpus.json', 'scripts/public_benchmarks/agentdocbench-assets.json') }}-
+      - name: Install scorer dependencies
+        run: python3 -m pip install --require-hashes -r scripts/public_benchmarks/requirements.txt
+      - name: Test benchmark contracts
+        run: python3 -m unittest discover -s scripts/tests -p 'test_public_benchmarks.py'
+      - name: Build release CLI
+        run: cargo build --locked --release -p markkit-cli
+      - name: Install verified Mira host
+        run: python3 scripts/public_benchmarks/install_mira.py
+      - name: Prepare pinned input selection
+        run: python3 scripts/public_benchmarks/prepare.py --scope "$BENCHMARK_SCOPE"
+      - name: Run and gate through Mira
+        run: python3 scripts/public_benchmarks/run.py --scope "$BENCHMARK_SCOPE" --mira target/public-benchmarks/bin/mira
+      - name: Job summary
+        if: always()
+        run: |
+          report="target/public-benchmarks/report-$BENCHMARK_SCOPE/summary.md"
+          if [ -f "$report" ]; then cat "$report" >> "$GITHUB_STEP_SUMMARY"; fi
+      - name: Upload reports and provenance
+        if: always()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: public-benchmarks-${{ env.BENCHMARK_SCOPE }}
+          path: target/public-benchmarks/report-${{ env.BENCHMARK_SCOPE }}/
+          if-no-files-found: warn
+          retention-days: 14