lme-python 0.2.1__tar.gz → 0.2.3__tar.gz

lme_python-0.2.3/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: x4g4p3x

{lme_python-0.2.1 → lme_python-0.2.3}/.github/workflows/audit.yml

@@ -28,7 +28,7 @@ jobs:
           toolchain: stable
 
       - name: Install cargo-audit
-        uses: taiki-e/install-action@c44f6b046f1c29ae5918b1e0bfdbb2f1813836fd # v2
+        uses: taiki-e/install-action@84f5ac3124727fb3d284d4d22ee9ab3654fd09a6 # v2
         with:
           tool: cargo-audit@0.22.1
 
@@ -48,7 +48,7 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           python-version: "3.11"
           enable-cache: true

{lme_python-0.2.1 → lme_python-0.2.3}/.github/workflows/benchmarks.yml

@@ -18,6 +18,7 @@ on:
 permissions:
   contents: write
   id-token: write
+  pages: write
 
 env:
   CARGO_TERM_COLOR: always
@@ -200,3 +201,78 @@ jobs:
           echo "Cross-language benchmark script failed with exit code ${{ steps.cross_language_run.outputs.status }}." >&2
           exit 1
 
+  pages:
+    name: Publish Benchmark Dashboard
+    runs-on: ubuntu-latest
+    needs:
+      - criterion
+      - cross-language
+    if: >
+      always() &&
+      needs.criterion.result == 'success' &&
+      needs.cross-language.result == 'success' &&
+      (github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags/'))
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    concurrency:
+      group: pages
+      cancel-in-progress: true
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.11"
+
+      - name: Download cross-language artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: cross-language-${{ github.sha }}
+          path: site-input
+
+      - name: Resolve release URL
+        id: release_url
+        run: |
+          if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
+            echo "value=${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/releases/tag/${GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT"
+          else
+            echo "value=" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build benchmark dashboard
+        run: |
+          set -euo pipefail
+          mkdir -p site
+          cp -R docs/. site/
+          extra=()
+          fair_json="$(find site-input -name 'fair-rust-julia-*.json' -print -quit || true)"
+          cross_json="$(find site-input -name 'cross-language-*.json' -print -quit || true)"
+          if [ -n "${fair_json}" ]; then
+            extra+=(--ci-fair-json "${fair_json}" --fair-asset-name "fair-rust-julia-${GITHUB_SHA}.json")
+          fi
+          if [ -n "${cross_json}" ]; then
+            extra+=(--cross-language-json "${cross_json}" --cross-language-asset-name "cross-language-${GITHUB_SHA}.json")
+          fi
+          python3 scripts/build_benchmark_site.py \
+            --output-dir site/benchmarks/data \
+            --run-url "${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}" \
+            --release-url "${{ steps.release_url.outputs.value }}" \
+            --criterion-asset-name "criterion-${GITHUB_SHA}.tar.gz" \
+            --ref-name "${GITHUB_REF_NAME}" \
+            "${extra[@]+"${extra[@]}"}"
+
+      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site
+
+      - name: Deploy to GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
+

{lme_python-0.2.1 → lme_python-0.2.3}/.github/workflows/cache-prime.yml

@@ -54,7 +54,7 @@ jobs:
         if: matrix.os == 'macos-latest'
         run: echo "OPENBLAS_TARGET=ARMV8" >> "$GITHUB_ENV"
       - name: Cache Rust dependencies
-        uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+        uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2
         with:
           shared-key: ci-v2-${{ runner.os }}-rust-test
           cache-workspace-crates: ${{ runner.os != 'Linux' }}
@@ -76,7 +76,7 @@ jobs:
       - name: Install OpenBLAS
         run: sudo apt-get update && sudo apt-get install -y libopenblas-dev
       - name: Cache production-load Rust dependencies
-        uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+        uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2
         with:
           shared-key: ci-v2-${{ runner.os }}-rust-release
           cache-workspace-crates: true
@@ -105,11 +105,17 @@ jobs:
         if: matrix.os == 'macos-latest'
         run: echo "OPENBLAS_TARGET=ARMV8" >> "$GITHUB_ENV"
       - name: Cache Python Rust dependencies
-        uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+        uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2
         with:
           shared-key: ci-${{ runner.os }}-python
           workspaces: python -> target
       - name: Compile Python binding dependencies
+        if: matrix.os != 'macos-latest'
         env:
           PYO3_PYTHON: python
         run: cargo build --release --manifest-path python/Cargo.toml
+      - name: Compile Python binding dependencies (macOS)
+        if: matrix.os == 'macos-latest'
+        uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1
+        with:
+          args: --release --out python/dist --manifest-path python/Cargo.toml

{lme_python-0.2.1 → lme_python-0.2.3}/.github/workflows/ci.yml

@@ -34,6 +34,10 @@ jobs:
           python-version: "3.11"
       - name: Validate legal notices and provenance
         run: python3 scripts/ci/lme_ci.py legal
+      - name: Validate Markdown links
+        run: python3 scripts/ci/lme_ci.py docs-links
+      - name: Validate benchmark dashboard data
+        run: python3 scripts/ci/lme_ci.py benchmark-site --check
       - name: Validate completion score claims
         run: python3 scripts/ci/lme_ci.py completion-check
 
@@ -54,7 +58,7 @@ jobs:
       - name: Install OpenBLAS
         run: sudo apt-get update && sudo apt-get install -y libopenblas-dev
       - name: Cache Rust dependencies
-        uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+        uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2
         with:
           shared-key: ci-v2-${{ runner.os }}-rust-test
           save-if: ${{ github.event_name == 'pull_request' || github.ref == 'refs/heads/master' }}
@@ -111,7 +115,7 @@ jobs:
           toolchain: stable
 
       - name: Cache Rust dependencies
-        uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+        uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2
         with:
           shared-key: ci-v2-${{ runner.os }}-rust-test
           cache-workspace-crates: true
@@ -139,7 +143,7 @@ jobs:
         run: sudo apt-get update && sudo apt-get install -y libopenblas-dev
 
       - name: Restore Rust dependencies
-        uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+        uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2
         with:
           shared-key: ci-v2-${{ runner.os }}-rust-release
           cache-workspace-crates: true
@@ -167,13 +171,13 @@ jobs:
       - name: Install OpenBLAS
         run: sudo apt-get update && sudo apt-get install -y libopenblas-dev
       - name: Cache Python Rust dependencies
-        uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+        uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2
         with:
           shared-key: ci-${{ runner.os }}-python
           workspaces: python -> target
           save-if: ${{ matrix.python-version == '3.11' && (github.event_name == 'pull_request' || github.ref == 'refs/heads/master') }}
       - name: Set up uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           python-version: ${{ matrix.python-version }}
           enable-cache: true
@@ -181,7 +185,7 @@ jobs:
 
       - name: Python bindings (canonical editable identity + isolated wheel)
         if: matrix.python-version == '3.11'
-        run: python scripts/ci/lme_ci.py python --python-version ${{ matrix.python-version }}
+        run: python scripts/ci/lme_ci.py python --python-version ${{ matrix.python-version }} --examples
 
       - name: Python bindings (isolated wheel compatibility)
         if: matrix.python-version != '3.11'
@@ -203,19 +207,19 @@ jobs:
         if: matrix.os == 'macos-latest'
         run: echo "OPENBLAS_TARGET=ARMV8" >> "$GITHUB_ENV"
       - name: Cache Python Rust dependencies
-        uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+        uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2
         with:
           shared-key: ci-${{ runner.os }}-python
           workspaces: python -> target
           save-if: ${{ github.event_name == 'pull_request' || github.ref == 'refs/heads/master' }}
       - name: Set up uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           python-version: "3.11"
           enable-cache: true
           cache-dependency-glob: "python/uv.lock"
       - name: Python bindings (isolated wheel OS compatibility)
-        run: python scripts/ci/lme_ci.py python --python-version 3.11 --wheel-only
+        run: python scripts/ci/lme_ci.py python --python-version 3.11 --wheel-only --examples
 
   publish-crate:
     name: Publish Rust crate after CI
@@ -236,7 +240,7 @@ jobs:
     secrets: inherit
 
   publish-python:
-    name: Publish Python artifacts after CI
+    name: Dispatch Python release after CI
     if: startsWith(github.ref, 'refs/tags/v')
     needs:
       - release-policy
@@ -247,8 +251,19 @@ jobs:
       - python-bindings-versions
       - python-bindings-os
     permissions:
-      contents: write
-      id-token: write
-    uses: ./.github/workflows/python-release.yml
-    with:
-      publish: true
+      actions: write
+      contents: read
+    runs-on: ubuntu-latest
+    steps:
+      - name: Dispatch verified Python release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_SHA: ${{ github.sha }}
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          gh workflow run python-release.yml \
+            --repo "${GITHUB_REPOSITORY}" \
+            --ref master \
+            -f release_tag="${RELEASE_TAG}" \
+            -f release_sha="${RELEASE_SHA}" \
+            -f publish=true

{lme_python-0.2.1 → lme_python-0.2.3}/.github/workflows/fuzz-smoke.yml

@@ -31,7 +31,7 @@ jobs:
       - name: Install cargo-fuzz
         run: cargo install cargo-fuzz@0.13.2 --locked
 
-      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+      - uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2
         with:
           workspaces: fuzz
 

lme_python-0.2.3/.github/workflows/pages.yml

@@ -0,0 +1,56 @@
+name: GitHub Pages
+
+# Publishes the static dashboard from checked-in docs/ plus regenerated JSON.
+# Tag/manual benchmark runs can overlay CI artifacts via benchmarks.yml.
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - "docs/**"
+      - "benchmarks/*.json"
+      - "scripts/build_benchmark_site.py"
+      - "scripts/ci/lme_ci.py"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build dashboard
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.11"
+
+      - name: Assemble site
+        run: python3 scripts/ci/lme_ci.py benchmark-site --site-dir site
+
+      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site
+
+  deploy:
+    name: Deploy
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - id: deploy
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

{lme_python-0.2.1 → lme_python-0.2.3}/.github/workflows/python-release.yml

@@ -1,28 +1,96 @@
 name: Build and Publish Python Wheels
 
-# CI calls this workflow after every release-tag validation job succeeds.
-# workflow_dispatch remains available for non-publishing artifact builds.
+# CI dispatches this top-level workflow after every release-tag validation job
+# succeeds. PyPI Trusted Publishing does not support publishing from a reusable
+# workflow with attestations, so this workflow must retain its own identity.
 on:
-  workflow_call:
+  workflow_dispatch:
     inputs:
+      release_tag:
+        description: Validated v* tag to build; blank builds the selected ref
+        required: false
+        type: string
+        default: ""
+      release_sha:
+        description: Exact validated commit for a publishing run
+        required: false
+        type: string
+        default: ""
       publish:
-        description: Publish the built artifacts for a validated release tag
+        description: Publish the verified release tag to PyPI
         required: false
         type: boolean
         default: false
-  workflow_dispatch:
 
 permissions:
   contents: read
 
+env:
+  RELEASE_REF: ${{ inputs.release_tag || github.ref }}
+
 jobs:
+  verify-release:
+    name: Verify release target
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          ref: ${{ env.RELEASE_REF }}
+
+      - name: Verify validated tag and package versions
+        if: inputs.publish
+        env:
+          RELEASE_SHA: ${{ inputs.release_sha }}
+          RELEASE_TAG: ${{ inputs.release_tag }}
+        run: |
+          set -euo pipefail
+
+          if [[ ! "${RELEASE_TAG}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z.-]+)?$ ]]; then
+            echo "Publishing requires an explicit semantic v* release tag." >&2
+            exit 1
+          fi
+          if [[ ! "${RELEASE_SHA}" =~ ^[0-9a-f]{40}$ ]]; then
+            echo "Publishing requires the exact 40-character validated commit SHA." >&2
+            exit 1
+          fi
+
+          actual_sha="$(git rev-list -n 1 "refs/tags/${RELEASE_TAG}")"
+          if [[ "${actual_sha}" != "${RELEASE_SHA}" ]]; then
+            echo "Tag ${RELEASE_TAG} resolves to ${actual_sha}, not validated SHA ${RELEASE_SHA}." >&2
+            exit 1
+          fi
+          if [[ "$(git rev-parse HEAD)" != "${RELEASE_SHA}" ]]; then
+            echo "Checked-out release does not match validated SHA ${RELEASE_SHA}." >&2
+            exit 1
+          fi
+
+          python - "${RELEASE_TAG#v}" <<'PY'
+          import pathlib
+          import sys
+          import tomllib
+
+          expected = sys.argv[1]
+          manifests = (pathlib.Path("Cargo.toml"), pathlib.Path("python/Cargo.toml"))
+          for manifest in manifests:
+              with manifest.open("rb") as stream:
+                  actual = tomllib.load(stream)["package"]["version"]
+              if actual != expected:
+                  raise SystemExit(
+                      f"{manifest}: package version {actual!r} does not match tag {expected!r}"
+                  )
+          PY
+
   linux:
+    needs: verify-release
     runs-on: ubuntu-latest
     strategy:
       matrix:
         target: [x86_64, aarch64]
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ env.RELEASE_REF }}
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: '3.10'
@@ -59,12 +127,15 @@ jobs:
           path: dist
 
   windows:
+    needs: verify-release
     runs-on: windows-latest
     strategy:
       matrix:
         target: [x64]
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ env.RELEASE_REF }}
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: '3.10'
@@ -89,12 +160,15 @@ jobs:
           path: dist
 
   macos:
+    needs: verify-release
     runs-on: macos-latest
     strategy:
       matrix:
         target: [x86_64, aarch64]
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ env.RELEASE_REF }}
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: '3.10'
@@ -124,9 +198,12 @@ jobs:
           path: dist
 
   sdist:
+    needs: verify-release
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ env.RELEASE_REF }}
       - uses: dtolnay/rust-toolchain@4cda84d5c5c54efe2404f9d843567869ab1699d4 # stable
         with:
           toolchain: stable
@@ -147,14 +224,16 @@ jobs:
     name: Publish to PyPI
     needs: [linux, windows, macos, sdist]
     runs-on: ubuntu-latest
-    # Only CI's validated release-tag call can enable publication.
-    if: "inputs.publish && startsWith(github.ref, 'refs/tags/v')"
+    # Publication requires the explicit opt-in and exact tag/SHA verification above.
+    if: inputs.publish
     environment: pypi
     permissions:
       id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
       contents: write  # needed to create GitHub Release
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ env.RELEASE_REF }}
 
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
@@ -174,9 +253,10 @@ jobs:
           done
 
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # release/v1
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
 
       - name: Upload to GitHub Release
-        uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
+        uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3.0.3
         with:
           files: dist/*
+          tag_name: ${{ inputs.release_tag }}

{lme_python-0.2.1 → lme_python-0.2.3}/AGENTS.md

@@ -10,6 +10,7 @@ Use the smallest validation tier that proves the change is sound, then run the e
 | Python bindings | `task lint:python`, `task python` |
 | CI, manifests, release tooling | `task preflight`; use `task ci` before a release or broad refactor |
 | R / Julia comparison scripts | `task lint:comparisons`; use `task lint:comparisons:required` when the formatters are installed |
+| Documentation or portable examples | `task docs:check` (includes dashboard JSON drift); use `task consumer:smoke` when install or example behavior changes |
 | LMM throughput paths (`src/math.rs`, `src/optimizer.rs`) | Read [OPTIMIZATION.md](OPTIMIZATION.md) and run the applicable fair-harness cases |
 | Completion score files: `README.md`, `REPO_COMPLETION_BY_AREA.md`, `completion_manifest.json`, or `scripts/ci/check_completion_score.py` | `task completion:check` |
 
@@ -19,10 +20,10 @@ For a change that crosses several rows, run every applicable check. Full Rust in
 
 The completion headline in [README.md](README.md) and every percentage in [REPO_COMPLETION_BY_AREA.md](REPO_COMPLETION_BY_AREA.md) are generated claims, not values to edit by hand.
 
-- [completion_manifest.json](completion_manifest.json) is the source of truth: it declares binary scope commitments, their weights, and evidence paths.
-- `task completion:check` validates evidence-path existence, score arithmetic, report rows, and the README headline.
-- A completion item may be marked complete only when its stated evidence is current. Partial or stale evidence earns zero.
-- Do not raise a score merely because an API exists, a focused benchmark passes, or the stated scope has been narrowed. Update the manifest and supporting evidence in the same change.
+- [completion_manifest.json](completion_manifest.json) is the source of truth: it declares binary scope commitments, their weights, locked `scope` strings, evidence paths, and a `gap` for every incomplete criterion.
+- `task completion:check` validates schema version 2 (names, scopes, gaps), evidence-path existence, score arithmetic, report rows, and the README headline.
+- A completion item may be marked complete only when its **locked scope** is met and its stated evidence is current. Partial, stale, or substituted evidence earns zero.
+- Do not raise a score merely because an API exists, a focused benchmark passes, or the stated scope has been narrowed or replaced. Do not edit `scope` to make an existing artifact pass. Update the manifest and supporting evidence in the same change.
 
 `task ci` runs this check automatically. Run it directly whenever a completion-related file changes.
 
@@ -70,11 +71,11 @@ Use `--no-verify` only when explicitly necessary; report the bypass and the chec
 
 ## CI and release boundaries
 
-GitHub Actions validation runs automatically on pull requests and `v*` tags, and can be manually dispatched. Ordinary non-PR branch pushes do not receive the hosted validation matrix automatically. A lightweight cache-prime workflow runs when Rust dependency inputs change on `master` and weekly so new PRs can reuse trusted dependency artifacts. Pull requests run the full matrix except the four ignored heavy production-load cases. The tag CI calls the crates.io and PyPI workflows only after every validation job succeeds; the publishing workflows do not listen to tags independently.
+GitHub Actions validation runs automatically on pull requests and `v*` tags, and can be manually dispatched. Ordinary non-PR branch pushes do not receive the hosted validation matrix automatically. A lightweight cache-prime workflow runs when Rust dependency inputs change on `master` and weekly so new PRs can reuse trusted dependency artifacts. Pull requests run the full matrix except the four ignored heavy production-load cases. The tag CI calls the crates.io workflow and dispatches the top-level PyPI workflow only after every validation job succeeds; the publishing workflows do not listen to tags independently. The PyPI workflow must remain top-level because Trusted Publishing attestations do not support a reusable publishing workflow.
 
 External GitHub Actions are pinned to full commit SHAs, with the readable release line retained as a comment. Dependabot proposes grouped weekly pin updates; do not replace SHA pins with mutable tags. Dependency audits and libFuzzer smoke tests run weekly in addition to their release/manual entry points.
 
-- `task ci` mirrors the core hosted flow: Rust tests, Python bindings, lint, all-targets check, legal checks, doctests, docs, and the completion-score check.
+- `task ci` mirrors the core hosted flow: Rust tests, Python bindings, portable consumer examples, lint, all-targets check, legal checks, documentation/link verification, and the completion-score check.
 - Hosted-only coverage includes the multi-OS matrix, Python 3.10–3.13, production-load gates, and `pip-audit`.
 - After changing BLAS target tables or release workflows, run `task ci` locally or manually dispatch CI before tagging; macOS Apple Silicon BLAS is not exercised on Windows/Linux.
 - Benchmark workflow coverage requiring R or Julia belongs in the tag/manual workflow. `task benchmarks:preflight` runs the Rust smoke plus the R smoke when R/lme4 is available.
@@ -93,8 +94,20 @@ For repository-metadata token issues, set `REPO_ADMIN_TOKEN` locally and run `ta
 | `task ci` / `task ci:fast` | Core CI mirror / reuse the editable Python environment and skip the isolated-wheel pass |
 | `task audit` / `task legal` | Security audit / provenance and license checks |
 | `task completion:check` | Verify the manifest-derived completion score and published markers |
+| `task docs:check` / `task consumer:smoke` | Validate docs/links/API examples / run clean-install Rust and Python workflows |
+| `task benchmarks:site` | Regenerate `docs/benchmarks/data/latest.json` from checked-in reference JSON |
 | `task benchmarks:fair-rust-julia` | Fair fit-only Rust vs MixedModels.jl timing when Julia packages are installed |
 | `task benchmarks:perf-breakdown` | Rust phase timings against Julia optimizer evaluation counts |
+| `task benchmarks:external-timings` | Fair-ish `nlmer`, post-fit inference, and Python FFI timings vs R when available |
+| `task explorations` | Standalone native-parser AST, θ-grid, and MCP exploration examples |
 | `task lint:comparisons` | Optional R/Julia comparison formatting check |
 
 Run `python scripts/ci/lme_ci.py --help` for the complete command list. See [CONTRIBUTING.md](CONTRIBUTING.md) for contributor workflow and [RELEASING.md](RELEASING.md) for release steps.
+
+## Cursor Cloud specific instructions
+
+This repo is a pure Rust library (`lme-rs`) plus a PyO3/maturin Python binding (`lme_python`); there are no servers or long-running services. "Running the app" means building the crate and running examples/tests. See the command reference above for the canonical `task` aliases.
+
+- Toolchain comes from `mise` (per [mise.toml](mise.toml): Rust stable, Python 3.11, `uv`, `task`, `lefthook`). The startup update script runs `mise install`. Interactive shells auto-activate mise via `~/.bashrc`. In a non-interactive shell where `mise`/`task`/`uv` aren't on `PATH`, run `eval "$($HOME/.local/bin/mise activate bash --shims)"` first (or invoke tools with `$HOME/.local/bin/mise exec -- <cmd>`).
+- On x86_64 the core crate links Intel MKL statically via `ndarray-linalg`, so no `gfortran`/system BLAS is needed; the first `cargo build`/`task test:fast` compiles MKL and takes a few minutes (subsequent builds are cached). Examples must be run with `--release` (e.g. `cargo run --release --example sleepstudy`) — a debug build is very slow.
+- Python bindings gotcha: `uv sync` / `task ci` / `task python` reinstall the venv and **uninstall** the maturin-built `lme_python` before rebuilding it. If you run a bare `uv sync` (or interrupt `task python` before its maturin step), `import lme_python` breaks; restore it with `cd python && uv run --no-sync maturin develop --release` (or re-run `task python`). Run Python examples from `python/` via `uv run --no-sync python examples/<name>.py`.