From 2263ecd872eba0f73954b2d97b70bab7ef6a470a Mon Sep 17 00:00:00 2001
From: Anthony Ronning <101225832+AnthonyRonning@users.noreply.github.com>
Date: Wed, 28 Oct 2026 06:42:59 +0000
Subject: [PATCH 1/3] docs: add the change-maple-ci skill

A first read for agents changing, triggering or debugging CI: the hard
rules with their reasons, how plan, lanes and ci-ok fit together, what
runs on PRs, master, nightly and dispatch, the ci:* labels and re-run
semantics, how to add a lane, local validation, common failures, and
the release boundary. References hold the design reasoning, the lane
and guard-test detail, and a debugging guide. lanes.py and
plan.py explain stay the source of truth for volatile lists.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .agents/skills/change-maple-ci/SKILL.md       | 258 ++++++++++++++++++
 .../skills/change-maple-ci/agents/openai.yaml |   4 +
 .../change-maple-ci/references/changing-ci.md | 255 +++++++++++++++++
 .../change-maple-ci/references/debugging.md   |  97 +++++++
 .../change-maple-ci/references/design.md      | 251 +++++++++++++++++
 5 files changed, 865 insertions(+)
 create mode 100644 .agents/skills/change-maple-ci/SKILL.md
 create mode 100644 .agents/skills/change-maple-ci/agents/openai.yaml
 create mode 100644 .agents/skills/change-maple-ci/references/changing-ci.md
 create mode 100644 .agents/skills/change-maple-ci/references/debugging.md
 create mode 100644 .agents/skills/change-maple-ci/references/design.md

diff --git a/.agents/skills/change-maple-ci/SKILL.md b/.agents/skills/change-maple-ci/SKILL.md
new file mode 100644
index 000000000..a5d7c264b
--- /dev/null
+++ b/.agents/skills/change-maple-ci/SKILL.md
@@ -0,0 +1,258 @@
+---
+name: change-maple-ci
+description: Change, trigger, or debug Maple's GitHub Actions CI. Covers the ci.yml lane planner (scripts/ci/plan.py, scripts/ci/lanes.py), the one required check ci-ok, ci:* labels (ci:full, ci:package, ci:windows, ci:ios, ci:android, ci:research-dev-macos, ci:eif), re-runs, ci.yml dispatch, nightly runs, runners and override variables, caches, timeouts, the pre-commit hook, guard and contract tests, and red or slow runs. Use it to add or change a lane or workflow, to get Windows, packaging, iOS, Android or EIF evidence on a PR, to decide what runs on a PR and what on master, or to explain why a check ran, did not run, or failed. Use release-maple for releases, signing and publication.
+---
+
+# Change Maple CI
+
+Load this skill before you edit `.github/`, `scripts/ci/`, `.githooks/` or
+the root flake checks, or when you need a CI result a PR does not get by
+default. [CI](../../../docs/ci.md) is the human reference;
+[repository workflows](../../../docs/repository-workflows.md) owns caches,
+contracts and the signed builds. Code beats any list here:
+`scripts/ci/lanes.py` is the source of truth for lanes, paths, labels,
+events, runners and timeouts. Ask the planner instead of guessing:
+
+```sh
+python3 scripts/ci/plan.py explain --base origin/master --head HEAD
+```
+
+## Hard rules
+
+1. **Keep every PR's `ci-ok` well under 10 minutes.** Path-select a lane on
+   pull requests only if its warm runs finish in about 8 minutes. Slower work
+   runs by label, nightly, or as master's real builds. Why: the team ships
+   many small PRs, and slow lanes crept back in one path selector at a time.
+2. **Keep master deployable.** Merge only with `ci-ok` green. When master goes
+   red, fix forward or revert first. Why: master pushes start signed builds
+   and feed the next release.
+3. **Add checks only as lanes in `scripts/ci/lanes.py`, each with a
+   `scripts/ci/test_plan.py` case.** Never add `paths:` to `ci.yml`, a new
+   workflow that runs on pull requests, another required check, or a bespoke
+   guard script. Why: one table drives CI, the pre-commit hook and
+   `just lane`, and `ci-ok` must report on every PR.
+4. **Never put `[skip ci]`, `[ci skip]` or similar in a commit message or PR
+   title.** Why: master plans each push from the previous commit, so a
+   skipped commit is never checked.
+5. **Pull requests never save an Actions cache, and master runs are never
+   cancelled.** Why: a PR can rewrite its own YAML, so its caches are
+   untrusted, and a cancelled master commit is never verified.
+6. **A lane saves caches only into its own runner vendor's store. `ci.yml`
+   never writes a key that a release restores.** Why: Blacksmith and GitHub
+   cannot read each other's caches, and releases restore their keys by prefix.
+7. **A failing `test_contracts.py` or `test_workflow_policy.py` means your
+   change is wrong.** Never edit `release.yml`, a publisher, a signing
+   environment, PCR approvals or OpenSecret approval gating to make a check
+   pass. Why: releases, update feeds and EIF approvals trust those seams.
+8. **Never rename `agent-desktop-build.yml`, `ios-dev-testflight.yml`, or a
+   workflow, job or artifact that a publisher or the release preflight looks
+   up.** Why: run numbers are build numbers, and consumers find producers by
+   name.
+9. **Never push to `master`, and never dispatch or re-run a signing or
+   publishing workflow, to try a CI change.** Why: a master push can sign
+   builds and upload to TestFlight. Re-running or dispatching `ci.yml` is fine.
+10. **Keep fat LTO for Agent release builds, and do not propose thin LTO.**
+    Why: the owner chose smaller downloads over a faster master build.
+11. **Treat OpenSecret CI as reproducible TEE infrastructure.** Keep every EIF
+    builder that writes FlakeHub on one runner class. Keep `os-eif` to
+    same-repository PRs to `master`. Never give OIDC or FlakeHub to a new job.
+    Why: PCR reproducibility depends on identical, trusted builders.
+12. **Test behaviour, or a contract another file consumes. Never test a
+    workflow's or script's text, and never hand-copy lists of names.** Why:
+    text tests break on harmless edits and catch nothing.
+13. **Do not add process.** Add no approval steps, required checks or safety
+    switches unless the owner asks. Why: a team of four wants fast
+    iteration, and master's push run plus fixing forward is the backstop.
+
+The reasons in full are in [design](references/design.md).
+
+## How CI works
+
+Every `ci.yml` run has three stages:
+
+1. **`plan`** runs `plan.py github`. It diffs the change, matches each path
+   against `lanes.py`, and adds lanes for the PR's labels. Its job summary
+   lists each selected lane with its reason.
+2. **Lanes** run in the generic `nix` and `windows` matrix jobs. A lane that
+   needs services, OIDC, artifacts or another workflow's cache gets a special
+   job named after it. Every lane runs `plan.py run <id>`.
+3. **`ci-ok`** runs `plan.py verdict`. It passes when every selected lane
+   succeeded and nothing unselected failed. It is the only required check.
+
+Selection rules:
+
+- A PR is judged on its own diff from the merge base. Each layer of a stack
+  gets its own `ci-ok`.
+- Root and component-level docs, READMEs and hooks, and `.agents/**`, are
+  inert: they select no lane but what the OpenSecret selector routes. Deeper
+  files can be build inputs, so a README inside a crate selects its lanes.
+- A path that no lane owns selects every lane, label-only builds included. So
+  does a diff the planner cannot compute (a new branch or a force-push).
+- Editing `ci.yml`, `.github/actions/**`, `plan.py` or `lanes.py` selects
+  every gate lane. It never selects the slow `gate=False` lanes.
+- A selection error fails a PR's `plan`; master, nightly and dispatch runs
+  select every lane instead.
+
+| Trigger | What runs |
+| --- | --- |
+| Pull request (any base) | Lanes selected by paths and labels. A new push cancels the superseded run. `opensecret-eif.yml`, `pages-preview-build.yml`, `auth-pages-ci.yml` and `proxy-rust.yml` may also run on matching paths. They are advisory, not required. |
+| Merge | Auto-merge is on. There is no merge queue and no up-to-date rule (`ci.yml` already handles `merge_group` if a queue is ever enabled). The master push run catches semantic conflicts. |
+| Master push | `ci.yml` runs the push lanes, adding the full Agent Linux and macOS suites for Agent changes. The Research and Auth PR lanes do not run here; their master workflows cover them. The run is never cancelled and saves caches. Also: signed builds (Agent: Prod only), release-evidence workflows and CodeQL. |
+| Nightly (UTC) | 04:17 `ci.yml` nightly lanes: full Windows suite, packaging rehearsals, `deps-*` advisories, cache refresh. 05:28 CodeQL. 05:47 `nightly.yml`: Bun audits, the SQLCipher provider suite on three OSes, and the single `ci-nightly` issue. 10:37 Agent Dev desktop builds, which the issue does not cover. |
+| Dispatch | `ci.yml` with lane ids ([below](#dispatch-ciyml)). |
+
+## Trigger what you need
+
+### Labels
+
+Most PRs need no label. A label adds lanes to that PR's plan. The `labels=`
+fields in `lanes.py` are authoritative.
+
+| Label | Adds | Use when |
+| --- | --- | --- |
+| `ci:windows` | Agent Windows Clippy (already on every Agent PR), the native updater tests, the full Windows suite | Path, filesystem, process or terminal code behaves differently on Windows |
+| `ci:package` | Unsigned Agent packages and Research desktop bundles on all three OSes, plus the Research Dev macOS app | Packaging or release scripts, flakes, toolchains, or bundled assets, entitlements or updater metadata change |
+| `ci:ios`, `ci:android` | The Research iOS simulator or Android build | Research changes reach native mobile code or mobile-only plugins that their paths do not select |
+| `ci:research-dev-macos` | The unsigned Research Dev app | Research Dev OAuth profile work |
+| `ci:eif` | Dev and prod OpenSecret EIF candidates (`os-eif`) | The selector misses a measured input. Works only on a same-repository PR to `master` that edits no PCR approval |
+| `ci:full` | Every PR lane except `os-eif` | Toolchain, lockfile-wide or risky cross-cutting changes before merge |
+
+- Adding a label starts nothing. Push, or use **Re-run all jobs**: `plan`
+  reads labels when it runs.
+- **Re-run failed jobs** reuses the earlier `plan`, with its old lanes,
+  labels and quarantine.
+- Labelled builds can take 15 to 90 minutes, and every push re-runs them while
+  the label stays. Remove it once you have the evidence.
+- Labels act only on `pull_request` runs. iOS, Android and EIF builds are
+  also path-selected by their native or measured inputs.
+
+### Dispatch `ci.yml`
+
+```sh
+gh workflow run ci.yml --ref <branch> -f lanes=agent-full-windows,deps-sdk
+```
+
+- `lanes` takes comma-separated ids. `all`, the default, runs every lane
+  active for dispatch.
+- `os-eif` cannot be dispatched. Any id that is not a dispatch lane, a typo
+  included, does not fail: the plan falls back to every dispatch lane,
+  packaging builds included. Check ids in `lanes.py` first.
+- Dispatch runs never save caches, so they warm nothing. Never use one to
+  satisfy a PR's `ci-ok`; use labels.
+
+### Master-only builds
+
+Signed builds never run on PRs; never push to `master` to get one.
+`agent-desktop-build.yml` builds Agent Prod packages on pushes that change
+Agent inputs (`plan.py only agent-desktop`) and Dev packages nightly; a
+dispatch signs both. Research signed builds follow
+`scripts/ci/change_detection.py`. These belong to the release process
+([boundary](#production-boundary)).
+
+## Change CI
+
+[Changing CI](references/changing-ci.md) has the field reference, special
+jobs, runners, caches and guard tests. In short:
+
+1. Edit one `Lane(...)` in `lanes.py`. `paths` are its own inputs (the hook
+   reads only these), `also` is CI-only fan-out to consumers, and
+   `pr_paths=()` makes it label-only on PRs.
+2. Add a `test_plan.py` case: which paths and labels select it on a PR and on
+   a push, and whether it runs nightly.
+3. Prefer the `nix` and `windows` matrices. Keep the work in a script or
+   `just` recipe so `just lane <id>` runs it anywhere.
+4. Own or mark inert every new path. The OpenSecret selector runs every
+   OpenSecret lane for a new top-level directory too.
+5. Check a lane's warm duration before path-selecting it on PRs. Over about
+   8 minutes, use `pr_paths=()` with a label, nightly, or master.
+
+- **Runners.** Blacksmith for compiles people wait on, free GitHub runners
+  for light or unwatched work, GitHub-hosted for attestation, signing,
+  verification and Windows install smokes ([CI runners](../../../docs/ci.md#runners)).
+  The `CI_*_RUNNER` repository variables move lanes in an outage, no PR needed.
+- **Caches.** Lane caches use `Swatinem/rust-cache` with prefix `ci-v2`. Only
+  master pushes and the nightly run save them. Never let an action save
+  implicitly on a PR path.
+- **Timeouts.** Size them for a cold run on the home runner, never for warm
+  times. The 10-minute rule decides which lanes PRs wait on; it is not a
+  timeout.
+- **Never touch to go green:** release and publisher workflows,
+  `ci_evidence.py`, signing environments, `pcr*.json`,
+  `opensecret_change_detection.py`, or the allowlists in the policy and
+  contract tests (adding an entry is an owner decision).
+
+## Validate before pushing
+
+Run from the repository root:
+
+```sh
+python3 scripts/ci/plan.py lint                      # every file classified; ci.yml matches the table
+python3 scripts/ci/plan.py explain --base origin/master --head HEAD
+python3 scripts/ci/plan.py explain --event push --base origin/master --head HEAD
+just lane <id>    # each selected lane this OS can run
+just lane repo    # every root flake check, for .github, scripts/ci, flake or hook edits
+```
+
+For a faster loop on `scripts/ci` or workflow edits:
+
+```sh
+nix develop --no-update-lock-file .#ci -c python3 -I -m unittest discover -s scripts/ci -p 'test_*.py'
+SYS=$(nix eval --impure --raw --expr builtins.currentSystem)
+nix build --no-link --no-update-lock-file .#checks.$SYS.ci-scripts .#checks.$SYS.workflows .#checks.$SYS.release-gates
+```
+
+- Docs and skills are inert, so a docs-only PR runs no docs check. After
+  editing them, run `just lane repo` (or `ci-scripts`) yourself.
+- `explain` also reads paths from stdin. It ignores labels, quarantine and
+  the `os-eif` candidate rules, and has no schedule or dispatch event.
+- `lint` also reads untracked, unignored files: a stray scratch file is an
+  unclassified path. The tests need yq-go, which the `.#ci` shell provides.
+- macOS and Windows lanes need those OSes. `os-sdk-e2e` needs local
+  PostgreSQL. `os-eif` needs Linux ARM64 and `EIF_MODE=dev` or `prod`.
+
+## Debug a red or slow run
+
+Read `plan`'s summary first: it says which lanes ran and why. `ci-ok`'s error
+names the failing job; for `nix` or `windows`, open the row named after the
+lane. Then follow [debugging](references/debugging.md). The common cases:
+
+| Symptom | Response |
+| --- | --- |
+| Nix setup fails with HTTP 416, `SSL_read` or "no substituter" from `cache.nixos.org` | Transient network fault. Re-run the job |
+| "Lost communication with the server", or a runner that vanished | Lost runner. Re-run failed jobs |
+| `plan` failed on a PR | Usually a label read failure: **Re-run all jobs**. A `CI_QUARANTINE` typo fails every run until the variable is fixed |
+| Many more lanes than expected | Unclassified path or unusable diff. Classify the path in `lanes.py` |
+| The lane you edited did not run | CI edits select gate lanes only. Add its label, then **Re-run all jobs** |
+| A lane slower than usual | Cold cache after a lockfile, toolchain, prefix or runner-image change. The next master save warms it; do not cut the timeout |
+| Heavy lanes queued for many minutes | Runner pool burst. Set `CI_LINUX_HEAVY_RUNNER=blacksmith-16vcpu-ubuntu-2404` (or another `CI_*_RUNNER`), **Re-run all jobs**, and unset it afterwards |
+| `repo` fails a policy or contract test | Your change broke a rule or seam. Read the failing assertion and fix the change |
+| Agent native Windows suite fails in a store test | Known intermittent flake. Re-run once; a repeat goes to the `ci-nightly` issue |
+
+## Production boundary
+
+CI decides whether a change is safe to merge. It never releases, signs,
+publishes or deploys. That work belongs to `$release-maple` and the guides
+below, and each step needs the owner's explicit go.
+
+- A workflow, `scripts/ci` or Nix change on `master` makes the next Research
+  release wait for fresh evidence. Tell the release owner.
+- CodeQL is outside `ci-ok`; the release preflight needs its newest finished
+  scan to be green.
+- An `agent-desktop-build.yml` dispatch, a signed build or any publisher is a
+  production action. Ask before running one.
+
+| For | Read |
+| --- | --- |
+| Research releases, TestFlight, App Store and Play handoffs | [`$release-maple`](../release-maple/SKILL.md) |
+| Contracts CI keeps with releases | [Repository workflows](../../../docs/repository-workflows.md#contracts) |
+| Signing environments | [App signing environments](../../../docs/app-signing-environments.md) |
+| Pages and Auth publication | [Pages deployments](../../../docs/pages-deployments.md) |
+| Agent packages and updates | [Agent desktop builds](../../../apps/maple-agent/docs/desktop-builds.md), [Agent update publication](../../../services/agent-updates/README.md#publication-and-authority) |
+| SDK publication | [SDK publishing](../../../docs/sdk-publishing.md#run-a-release) |
+| OpenSecret EIFs and PCR approvals | [EIF CI and release](../../../services/opensecret/docs/nitro-deploy.md#ci-approval-checks), [PCR compatibility](../../../services/opensecret/docs/pcr-compatibility.md) |
+
+## References
+
+- [Design](references/design.md): why CI has this shape.
+- [Changing CI](references/changing-ci.md): lane fields, special jobs, runners, caches, the hook, guard tests.
+- [Debugging](references/debugging.md): re-run semantics, failure signatures, cold caches, fail-over.
diff --git a/.agents/skills/change-maple-ci/agents/openai.yaml b/.agents/skills/change-maple-ci/agents/openai.yaml
new file mode 100644
index 000000000..74fb3e666
--- /dev/null
+++ b/.agents/skills/change-maple-ci/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Change Maple CI"
+  short_description: "Change, trigger and debug the ci.yml lanes"
+  default_prompt: "Use $change-maple-ci to change, trigger or debug this Maple CI check."
diff --git a/.agents/skills/change-maple-ci/references/changing-ci.md b/.agents/skills/change-maple-ci/references/changing-ci.md
new file mode 100644
index 000000000..67c355155
--- /dev/null
+++ b/.agents/skills/change-maple-ci/references/changing-ci.md
@@ -0,0 +1,255 @@
+# Changing CI
+
+Paths are relative to the repository root. `scripts/ci/lanes.py` and
+`scripts/ci/plan.py` are short; read them before a non-trivial change.
+
+## Lane fields
+
+| Field | Meaning |
+| --- | --- |
+| `id` | Lane id, which is also the check name |
+| `paths` | The lane's own inputs. They select it in CI, and the hook selects its `hook` component from these alone |
+| `also` | CI-only fan-out to consumers (for example, the Rust SDK selects Agent lanes). The hook ignores it |
+| `pr_paths` | `None`: PRs use `paths + also`. `()`: never path-selected on PRs (label only), while push and nightly still use `paths + also`. A tuple: a narrower PR selector |
+| `labels` | PR labels that add the lane (default `ci:full`) |
+| `events` | Events the lane is active for (`GATE`, `PR_SIDE`, `PR_AND_NIGHTLY`, `NOT_NIGHTLY`, or a custom set) |
+| `job` | `nix` or `windows` (the generic matrices), or the id of a special `ci.yml` job |
+| `runner` | A `Runner(label, variable)` constant from the top of `lanes.py` |
+| `flake`, `workdir`, `run`, `env` | `plan.py run` runs `cd <workdir> && <run>` under `bash -euo pipefail`, inside `nix develop --no-update-lock-file <flake>` when set. On Windows it uses Git Bash from `PATH`, without Nix |
+| `cache`, `workspaces`, `cache_files`, `cache_targets` | rust-cache shared key, workspaces, toolchain pins hashed into the key, and whether to cache `target/` (False keeps only the Cargo home) |
+| `timeout` | Minutes |
+| `gate` | Selected when CI infrastructure changes. Set `False` for slow builds |
+| `opensecret` | The `opensecret_change_detection.py` output that selects the lane |
+| `submodules` | Recursive submodules with full blobless history (Nix needs `revCount`) |
+| `hook` | Pre-commit component that runs the same checks locally |
+| `restore` | Read-only restore of a cache another workflow writes |
+
+Event sets:
+
+- `PR_SIDE` lanes never run on master pushes, because other workflows cover
+  master: Research web and Rust, Research platform builds, and Auth.
+- `NOT_NIGHTLY` is for lanes `nightly.yml` already covers.
+- `PR_AND_NIGHTLY` is for slow lanes whose cache the nightly run saves, such
+  as packaging and the full Windows suite.
+
+## How selection works
+
+- Globs: `**` spans directories, `*` stays within one segment, and a leading
+  `!` excludes paths from the globs listed with it. Matching is full-path.
+- **PR diff:** `git diff --no-renames` from the merge base, so a rename also
+  selects its old path. **Push diff:** `before..after`. With no usable diff
+  (a new branch, a force-push, or a missing SHA), every active lane runs.
+- **Inert paths** (`INERT`) select only what the OpenSecret selector routes
+  them to. Root and component docs, READMEs, hooks and `.agents/**` are
+  inert. Deeper files are not, because the Agent compiles nested `SKILL.md`
+  files. A script you add under `.agents/skills/<name>/scripts/` is inert and
+  unchecked unless you exclude it from `INERT` and give it a lane, as
+  `release-maple/scripts/**` has.
+- **Unclassified paths** select every active lane and ignore `pr_paths`, so a
+  PR waits on the label-only builds too. `lint` also fails until the path is
+  owned or inert.
+- **CI infrastructure** (`CI_INFRA`: `ci.yml`, `.github/actions/**`,
+  `plan.py`, `lanes.py`) selects every lane with `gate=True`.
+- **Labels** add active lanes on `pull_request` only. `plan` reads them
+  through `gh api` when it runs, and a read failure fails the PR's plan.
+- **Dispatch:** `lanes` is a comma list or `all`. A name that is not active
+  for dispatch makes selection fail, and dispatch then runs every dispatch
+  lane.
+- **Schedule:** every lane active for `schedule`.
+- **`os-eif`** is kept only for a `pull_request` with base `master`, a head
+  repository equal to this repository, and a usable diff. It is dropped when
+  any path edits a PCR approval.
+
+`plan.py explain` calls the same selection with no labels and no `os-eif`
+filter. For label behaviour, read the `labels=` fields or run the
+`test_plan.py` helpers:
+
+```sh
+python3 -c 'import sys; sys.path.insert(0, "scripts/ci"); import plan; print(sorted(plan.select("pull_request", ["docs/x.md"], ["ci:package"])))'
+```
+
+## Add or change a matrix lane
+
+1. Add the `Lane(...)` to `LANES`, next to its component's lanes.
+2. Put the command in a script under `scripts/ci/` or a component `just`
+   recipe. `run` should be one short line.
+3. Choose `paths` from what the command reads. Use `also` only for consumers
+   that build this lane's inputs from the tree.
+4. Choose the PR exposure:
+   - default for a fast lane;
+   - `pr_paths=()` plus a label for anything slower than about 8 minutes;
+   - `gate=False` if a CI edit should not run it.
+5. Add a `test_plan.py` case. Use the helpers `selected(paths, event,
+   labels)` and `active(event)`. Assert the PR and push selection, the
+   labels, and nightly membership. Follow the existing classes, for example
+   `AgentLaneTests`.
+6. If the lane has a `hook`, add a `hook_selected <name>` branch to
+   `.githooks/pre-commit`. `test_plan.py` checks that one exists.
+7. Run `plan.py lint`, `just lane <id>` and `just lane repo`.
+
+## Add or change a special job
+
+A special job is for services, OIDC, artifacts, or another workflow's cache.
+Its id is the lane's `job`. `plan.py lint` and policy tests 7 to 9 check the
+following:
+
+- `if: fromJSON(needs.plan.outputs.lanes)['<id>']`, plus any extra guard the
+  planner also applies. For `os-eif`, change the job's `if:` and the
+  planner's candidate rule together.
+- `runs-on` exactly `${{ vars.<VARIABLE> || '<label>' }}` when the runner has
+  an override variable, otherwise the plain label. `timeout-minutes` equals
+  the lane's `timeout`.
+- Add it to `ci-ok`'s `needs`.
+- Declare a new runner label in `.github/actionlint.yaml`.
+- Put the work in `plan.py run <id>` or a script, not inline YAML.
+- Guard cache saves to master `push` or `schedule` and to the home vendor
+  (`startsWith(runner.name, 'blacksmith')`, or its negation for a GitHub
+  home). Restore-only caches use `actions/cache/restore`.
+- Check out with `persist-credentials: false`. Any full history must use
+  `filter: blob:none`; full checkouts on Blacksmith can otherwise take
+  minutes.
+
+Never rename the matrix jobs' `name: ${{ matrix.id }}`. The quarantine
+verdict maps job names to lane ids.
+
+## Runners and overrides
+
+The `Runner` constants at the top of `lanes.py` are authoritative.
+[CI runners](../../../../docs/ci.md#runners) explains each choice.
+
+| Constant | Override variable |
+| --- | --- |
+| `LINUX` (Blacksmith 8 vCPU) | `CI_LINUX_RUNNER` |
+| `LINUX_HEAVY` (Blacksmith 32 vCPU) | `CI_LINUX_HEAVY_RUNNER` |
+| `MACOS` (Blacksmith macOS) | `CI_MACOS_RUNNER` |
+| `WINDOWS` (Blacksmith Windows) | `CI_WINDOWS_RUNNER` |
+| `GITHUB_WINDOWS` (`maple-windows-2025-16core`) | `CI_WINDOWS_GITHUB_RUNNER`, read only by special jobs |
+| `GITHUB`, `GITHUB_WINDOWS_FREE`, `EIF_BUILDER`, inline `ubuntu-24.04-arm` | none |
+
+- Matrix lanes resolve their runner when `plan` runs. A new matrix variable
+  must be passed in the `plan` step's `env`; `lint` checks this.
+- An override to the other vendor restores what it can and saves nothing.
+  Failover runners are often slower, while timeouts are sized for the home
+  runner.
+- Never move signing, attestation or verification jobs, the updater tests or
+  install smokes to Blacksmith, and never move one EIF builder alone.
+
+## Caches
+
+- Lane caches are rust-cache with `prefix-key: ci-v2`. Bumping the prefix or
+  a lane's `cache` name, editing `cache_files`, or changing any
+  `CARGO*`/`RUST*` variable in the step's environment (including `ci.yml`'s
+  top-level `env`) makes the next run cold. Its PR stays cold on every push,
+  because PRs never save.
+- Only master `push` and `schedule` runs save, through `save-if` and
+  `matrix.cache_save` (the vendor rule).
+- `ci.yml` may read another workflow's cache only with
+  `actions/cache/restore`, and only for a key a push-only workflow saves.
+- Never write a release-reserved prefix (`<os>-sccache-`, `xcode-cache-`,
+  `maple-dev-xcode`, `release-onnxruntime-ios-`, `<os>-bun-`, `<os>-gradle-`,
+  `ci-v1-agent-release-`) from `ci.yml` or a PR job.
+- Turn off implicit saves on PR paths: setup-bun `no-cache: true`, Trivy
+  `cache: "false"`, and no Magic Nix Cache.
+- After a lockfile change, master's first save deletes the lane's target
+  first, so that master run is slower than its PR.
+
+## Timeouts
+
+Size `timeout` for a cold run on the home runner, with headroom. Agent lint
+and test use 40 minutes although warm runs take about 3. A timeout protects
+against hangs; the 10-minute rule decides PR exposure. `test_7` requires a
+timeout on every non-protected job.
+
+## The pre-commit hook
+
+`./setup-hooks.sh` sets `core.hooksPath` to `.githooks`. The hook runs
+`plan.py hook --staged`, then each selected component's own hook inside its
+flake: formatting, lint, type checks and unit tests only. It uses only
+`paths`, never `also` or `CI_INFRA`. Preview it with
+`printf '%s\n' <path> | python3 scripts/ci/plan.py hook`. The environment
+switches are `MAPLE_HOOK_SKIP`, `MAPLE_HOOK_FULL`, `MAPLE_HOOK_NO_NIX` and
+`MAPLE_HOOK_ONLY`. See [the hook](../../../../docs/repository-workflows.md#pre-commit-hook).
+
+## Guard tests
+
+All run in the `repo` lane, through the flake checks `ci-scripts`,
+`workflows` and `release-gates`.
+
+- **`test_plan.py`** covers selection, labels, events, the verdict,
+  quarantine, cache rules, the hook mapping and `plan.py lint`.
+- **`test_workflow_policy.py`** holds rules for every workflow:
+  1. no `pull_request_target`, and a fixed set of PR workflows;
+  2. actions pinned to commits;
+  3. no persisted checkout credentials;
+  4. read-only workflow permissions;
+  5. secrets only in their protected environment;
+  6. a pinned, verified Nix install;
+  7. a timeout on every job;
+  8. `ci-ok` always reports and needs every job;
+  9. declared runner labels.
+
+  It also checks that PRs never save caches and that only the listed jobs
+  write GitHub's store.
+- **`test_contracts.py`** imports the code on the other side of each seam.
+
+| Contract | Protects | If it fails |
+| --- | --- | --- |
+| C1 | One `Release` workflow; listeners check their producer's success, repository and event; release jobs gated | You touched a release trigger or listener. Revert it |
+| C2 | The Agent publisher and signature probe trust `agent-desktop-build.yml` jobs, artifacts, runners and events | You renamed or moved a signed Agent job. Revert it |
+| C3 | Release evidence jobs run on master pushes and never cancel | You changed an evidence workflow's trigger, job or concurrency |
+| C4 | Release cache ownership, exact Agent release keys, lane-family isolation, Dev TestFlight build numbers | You wrote or overlapped a release cache key |
+| C5 | The EIF event gate, mismatch semantics, OIDC and FlakeHub jobs, one builder class, a manual EIF release | You changed an EIF job, runner or guard |
+| C6 | Each protected environment has fixed consumer jobs; `windows-signing` is GitHub-hosted | You added, moved or renamed an `environment:` |
+| C7 | Docs name only existing workflow files and display names | A doc names a missing `.yml` file, or a backticked or bold name before "workflow" that is not a display name |
+
+C7 reads `docs/**`, every component `docs/`, `.agents/**`, and every README,
+AGENTS and CLAUDE file. Docs are inert, so it runs only when `repo` is
+selected or nightly; run it yourself after doc edits.
+
+## Other workflows
+
+- Only `ci.yml`, `opensecret-eif.yml`, `pages-preview-build.yml`,
+  `auth-pages-ci.yml` and `proxy-rust.yml` may run on pull requests
+  (`PULL_REQUEST_WORKFLOWS`). Adding one is an owner decision.
+- The release-evidence workflows (`frontend-tests.yml`, `rust-tests.yml`,
+  `web-build.yml`, `desktop-build.yml`, `android-build.yml`,
+  `mobile-build.yml`, `codeql.yml`) feed the release preflight. Do not fold
+  them into `ci.yml`, rename their jobs, or change their `paths:` without the
+  release owner.
+- `pages-preview-build.yml` and `auth-pages-ci.yml` are producers that
+  `pages-publish.yml` and `auth-pages-dev-publish.yml` trust by name and
+  artifact. They overlap `research-web` and `auth` on purpose: the publishers
+  need their artifacts, while `ci-ok` needs the lanes.
+- `rust-tests.yml` is the only writer of `research-rust`'s cache.
+- The Nix version is pinned in every workflow, protected ones included. A Nix
+  bump therefore touches release files; make it a separate PR for the owner.
+
+## OpenSecret changes
+
+- Never edit `pcr*.json` or `opensecret_change_detection.py` to clear a
+  check. A new top-level directory makes the selector run every OpenSecret
+  lane. Adding it to the selector's `KNOWN_INDEPENDENT_PREFIXES` is an
+  OpenSecret change, reviewed as one.
+- For EIF checkout, Nix, cache or runner changes, prove that narHash,
+  drvPaths and PCRs match the last master `eif-trusted` run, on fresh hosted
+  runners. Get the PR evidence with `ci:eif` and **Re-run all jobs**.
+- Read [CI approval checks](../../../../services/opensecret/docs/nitro-deploy.md#ci-approval-checks)
+  and the [cache policy](../../../../services/opensecret/docs/nitro-deploy.md#binary-caches-and-cold-run-validation)
+  first.
+
+## Run lanes locally
+
+`just lane <id>` runs exactly what CI runs. Limits:
+
+- macOS lanes need macOS and the pinned Xcode (`scripts/ci/select-xcode.py`).
+- Windows lanes need Windows with the toolchain from
+  `.github/actions/setup-agent-windows`.
+- `os-sdk-e2e` needs PostgreSQL on `127.0.0.1:5432` with the credentials in
+  `scripts/ci/opensecret-sdk-e2e.sh`.
+- `os-helpers` needs Docker that can build `linux/arm64`.
+- `os-eif` needs Linux ARM64 and `EIF_MODE=dev` or `prod`.
+
+`just lane repo` runs every root flake check. To run one, use
+`nix build --no-link --no-update-lock-file ".#checks.$(nix eval --impure --raw --expr builtins.currentSystem).<name>"`,
+where `<name>` is `ci-scripts`, `workflows`, `release-gates`, `pages` or
+`pcr-compatibility`.
diff --git a/.agents/skills/change-maple-ci/references/debugging.md b/.agents/skills/change-maple-ci/references/debugging.md
new file mode 100644
index 000000000..bb3f2ab81
--- /dev/null
+++ b/.agents/skills/change-maple-ci/references/debugging.md
@@ -0,0 +1,97 @@
+# Debugging red or slow CI
+
+Start with the facts the run already has:
+
+- **`plan`'s job summary** ("Lanes for this …") lists every selected lane and
+  its first reason. If a lane is missing or unexpected, the answer is there.
+- **`ci-ok`'s log** names each job that did not finish as planned, for
+  example `nix (selected): failure`. Matrix entries are named after their
+  lanes, so open the failing row with that lane id.
+- **`plan.py explain`** reproduces the path selection locally (no labels).
+
+## Re-run semantics
+
+| Action | Re-plans? | Use for |
+| --- | --- | --- |
+| Push a commit | Yes | Code fixes; also picks up new labels and variables |
+| **Re-run all jobs** | Yes: `plan` reads the PR's current labels and repository variables | After adding a label, or changing `CI_QUARANTINE` or a `CI_*_RUNNER` variable |
+| **Re-run failed jobs** | No: reuses the old `plan` outputs (lanes, matrix runners, quarantine) | Infrastructure flakes in a lane |
+| Dispatch `ci.yml` | Its own plan from the `lanes` input | Running lanes on a branch outside a PR. It never saves caches |
+
+Adding a label never starts a run by itself. That is deliberate: a label
+event could otherwise post a fresh green `ci-ok` on a commit whose real run
+failed.
+
+A new push to a PR cancels the superseded run, and the new `plan` waits for
+the cancellation to finish. Rapid re-pushes each add about a minute.
+
+## Failure signatures
+
+| Signature | Cause | Response |
+| --- | --- | --- |
+| Nix setup fails: `HTTP error 416`, `SSL_read`, or "is required, but there is no substituter" | Transient `cache.nixos.org` error. Setup has no automatic retry | Re-run the failed job |
+| "lost communication with the server", or a job that vanished mid-run | Lost runner | Re-run failed jobs. On `agent-desktop-build.yml`, re-running in the same run keeps the build number; publication still belongs to the release owner |
+| `plan` fails with `lane selection failed` on a PR | A label read through `gh api` failed, or the event payload was unusable | **Re-run all jobs** |
+| `plan` fails on every event, master included | `CI_QUARANTINE` names an unknown lane or `repo` | Fix or clear the variable |
+| `plan` succeeds but selects every lane | An unclassified path, or no usable diff (new branch, force-push) | Own or mark inert the path in `lanes.py`; `plan.py lint` lists it |
+| A dispatch ran every lane | A lane id that is not active for dispatch (`os-eif`, or a typo) | Check ids in `lanes.py`. For `os-eif`, add `ci:eif` to the PR and **Re-run all jobs** |
+| The `ci.yml` job you edited did not run | CI edits select gate lanes only; slow special jobs are `gate=False` | Add the lane's label, then **Re-run all jobs** |
+| A lane is skipped and `ci-ok` fails with `(selected): skipped` | A special job's `if:` disagrees with the planner | Make the job's `if:` match the planner rule |
+| `os-eif` did not run on an OpenSecret PR | Fork, base not `master`, a PCR approval edit, or no EIF input | Expected. `opensecret-eif.yml` compares approvals; `ci:eif` works only on same-repository PRs to `master` |
+| `repo` fails `test_workflow_policy` or `test_contracts` | Your change crossed a policy or a release seam | Fix the change; see the contract table in [changing CI](changing-ci.md#guard-tests) |
+| `repo` fails C7 on an unrelated PR | An earlier docs-only merge named a missing workflow; docs PRs do not run `repo` | Fix the doc reference |
+| `agent-lint` fails `check-rust` | The Agent flake's rustc no longer equals the Windows rustup pin | Bump `AGENT_WINDOWS_RUST` and `setup-agent-windows` together |
+| Agent native Windows suite (`agent-full-windows`) fails in a SQLite store test with a locked file or a disconnected channel | Known intermittent flake on Windows | Re-run once. A repeat goes to the `ci-nightly` issue; do not quarantine it to merge |
+| An EIF comparison on master reports a mismatch | Measured inputs changed; approval is a release step | A notice, not a failure. Do not edit approvals |
+
+## Slow runs
+
+- **Cold cache.** The first run after any of these is cold:
+  - a lockfile change (a prefix fallback restores the nearest entry);
+  - a new cache prefix, lane `cache` name or `cache_files` pin;
+  - a change to a `CARGO*` or `RUST*` variable;
+  - a runner image with a new preinstalled Rust or MSVC.
+
+  PRs never save, so the PR stays cold until master or the nightly run saves.
+  Do not shrink timeouts to warm times.
+- **Nightly-only caches.** `agent-full-windows` and the `agent-package-*`
+  lanes save only from the 04:17 UTC nightly run. A labelled run right after
+  a lockfile change restores by prefix and is slower.
+- **Agent master builds.** The exact-key release cache misses on any
+  `Cargo.lock` change, version bumps included, and fat LTO bounds the link.
+  The master Agent build is slow by design; it does not gate PRs.
+- **Queued jobs.** If `agent-lint` or `agent-test` sit queued while other
+  Blacksmith jobs start, the 32-vCPU pool is bursting. Set the repository
+  variable `CI_LINUX_HEAVY_RUNNER=blacksmith-16vcpu-ubuntu-2404` (same
+  vendor, so caches still work), use **Re-run all jobs**, and unset the
+  variable afterwards. The same pattern applies to the other `CI_*_RUNNER`
+  variables in an outage. Changing repository variables needs admin rights,
+  so ask the owner if you lack them.
+- **Slow checkouts.** Full-history checkouts on Blacksmith are slow without
+  `filter: blob:none`. Every full-history checkout in CI uses it; keep it.
+
+## Nightly failures
+
+The 04:17 `ci.yml` run and the 05:47 `nightly.yml` run report through one
+`ci-nightly` issue: `nightly.yml` opens or updates it, and a green night
+closes it. A missing or unfinished `ci.yml` nightly run counts as a failure,
+and active quarantines keep the issue open. The 05:28 CodeQL scan and the
+10:37 Agent Dev desktop build are not in the issue; their failures show only
+as red checks on the master commit.
+
+## Quarantine
+
+Setting `CI_QUARANTINE=<lane>` turns that lane's failure into a warning in
+`ci-ok` while it keeps running. It needs no PR and applies at the next plan.
+Use it only when the owner asks; fix the lane instead. A typo fails every
+plan, and `repo` cannot be quarantined.
+
+## Release-adjacent signals
+
+- A master merge that touches `.github/`, `scripts/ci/` or Nix makes older
+  Research evidence unusable. The next Research release needs a push that
+  runs the evidence workflows again. Tell the release owner; do not work
+  around `ci_evidence.py`.
+- `services/agent-updates/**` changes select every signed Research build on
+  master. Never push to `master` to test them.
+- A red CodeQL scan blocks the next release, not `ci-ok`.
diff --git a/.agents/skills/change-maple-ci/references/design.md b/.agents/skills/change-maple-ci/references/design.md
new file mode 100644
index 000000000..a5cda953a
--- /dev/null
+++ b/.agents/skills/change-maple-ci/references/design.md
@@ -0,0 +1,251 @@
+# Why Maple CI has this shape
+
+Each section gives a design choice, the reason for it, and the code that
+enforces it. Read the matching section before you argue for changing a rule.
+
+## One workflow, one planner, one table
+
+A check is one `Lane(...)` in `scripts/ci/lanes.py`. Three readers share that
+table:
+
+- `plan.py github`, which is `ci.yml`'s `plan` job;
+- `plan.py hook`, which is `.githooks/pre-commit`;
+- `just lane <id>`, which is `plan.py run`.
+
+CI, the hook and local runs therefore execute the same command string and
+cannot drift. Separate workflows with their own `paths:` filters and change
+selectors drift apart and multiply check rows. A planner can do what
+`paths:` filters cannot:
+
+- An unknown path runs every lane.
+- A selection error fails closed on a PR. On master, nightly and dispatch it
+  runs everything.
+- Labels are read live.
+- Every choice is explained in the job summary.
+
+Special jobs exist only where a generic step list cannot do the work:
+services (`os-sdk-e2e`), OIDC (`os-eif`), artifacts (packaging, iOS, desktop)
+or another workflow's cache (`research-rust`). Unselected matrix lanes never
+appear as check rows. Keeping each lane's work in a script or recipe means it
+also runs outside GitHub Actions.
+
+## One required check
+
+The lanes differ per PR, so no lane can be required by name. `ci.yml` has no
+`paths:` filter, so `ci-ok` reports on every PR and never stalls as "waiting
+for status". The verdict is "selected means success". A skipped result passes
+only for an unselected job, so a lane skipped by a broken `if:` cannot pass
+silently. `ci-ok` runs `if: always()` and needs every other job.
+`test_8_ci_always_reports_one_verdict` and `plan.py lint` enforce this.
+
+## Merging without a queue or an up-to-date rule
+
+The `master` branch rules require `ci-ok` and no other status check.
+Auto-merge is on. There is no merge queue, and branches need not be up to
+date. Either would add a
+second full `ci-ok` run to every merge and fight stacked PRs. Master instead
+re-verifies every push, and the team fixes forward. `ci.yml` already handles
+`merge_group`, so a queue is a settings change if it is ever needed.
+
+## The 10-minute rule
+
+Every PR must reach `ci-ok` well under 10 minutes. A lane is path-selected on
+PRs only if its warm runs finish in about 8 minutes. Packaging rehearsals,
+desktop bundles, the full native suites and Windows harnesses run only by
+label, nightly, or as master's real signed builds. Master's
+`agent-desktop-build.yml`, `desktop-build.yml` and the other signed workflows
+already build the real artifacts on every relevant push. A PR rehearsal adds
+waiting, not coverage.
+
+No code enforces this rule; there is no timing guard. Slow lanes crept back
+before, one path selector at a time, until PRs waited 35 to 45 minutes. Check
+a lane's warm duration (the run history of its check row) before you
+path-select it.
+
+`test_plan.py` pins the current choices. Packaging is label-only, and the
+full suites run on master, nightly and by label. Research iOS and Android are
+still path-selected by their native inputs, and `os-eif` by measured
+OpenSecret inputs. They are slower, but they are the only PR proof for those
+inputs.
+
+## Pull requests never save caches
+
+- A PR author can edit the YAML, so a PR-written cache could poison what
+  master or a release later restores. Ref scoping is the real boundary:
+  Blacksmith's Actions-cache branch protection must stay on. "PRs never save"
+  is hygiene on top.
+- PR-scoped entries once filled GitHub's cache store and froze every save.
+- GitHub's store evicts the least recently used entries, which could push out
+  the caches releases restore.
+- A PR cache serves only that PR's next push. Master caches serve every PR.
+
+`save-if` in `ci.yml` allows only master `push` and `schedule`. The policy test
+`test_pull_requests_never_save_caches…` also checks dispatch and queue runs,
+and actions that save implicitly (setup-bun, Magic Nix Cache, Trivy). There
+are two deliberate exceptions, and neither writes the Actions cache that
+master reads:
+
+- `opensecret-eif.yml`'s unprivileged `eif` job writes only its own
+  branch-scoped Actions cache.
+- The same-repository PR `os-eif` candidate pushes to FlakeHub, a Nix binary
+  cache, through job-scoped OIDC.
+
+## Master runs are never cancelled
+
+Master plans each push from `before..after`. A cancelled run means that diff
+is never verified, because the next push checks only its own diff. Master runs
+also save the caches and produce release evidence. The release preflight
+never prefers an older green run over a newer failed or pending one, and
+contract C3 forbids cancelling the evidence workflows. The signed Agent
+workflow uses a per-run group, so pending packages are never discarded; its
+run number is the build number.
+
+## No skip tokens
+
+`[skip ci]` on a master commit means that commit's diff is never planned. A
+PR title becomes the squash commit message, so the rule covers titles too.
+A skipped PR run also leaves the required `ci-ok` unreported. No code guards
+this; `AGENTS.md` states the rule.
+
+## Runners
+
+Standard GitHub-hosted runners are free for this public repository.
+Blacksmith and the org's 16-core GitHub Windows runner are billed per minute.
+
+| Work | Runner class | Why |
+| --- | --- | --- |
+| Compiles people wait on: Agent lint and test, macOS lanes, Windows Clippy, Research Rust, OpenSecret Rust | Blacksmith | Fast, and caches stay warm in Blacksmith's store. The two heaviest Agent lanes use the 32-vCPU class, about twice as fast cold as 8 vCPU |
+| `plan`, `ci-ok`, `repo`, SDK, proxy, web, services, `deps-*`, `os-pcr`, `os-flake-check`, CodeQL | Free GitHub Linux | Light work, or nobody waits on it |
+| Agent native Windows suites (`agent-windows-updater`, `agent-full-windows`) | Free `windows-2025` | Blacksmith's Windows workspace has an inherited write ACE that the updater's storage validation rejects. The reparse tests need the symlink privilege GitHub grants. 16 cores only add queueing to a short suite |
+| `agent-package-windows`, `research-desktop-windows`, release `build-windows` | `maple-windows-2025-16core` | Install smokes need GitHub's image; the bundles gain from cores |
+| Agent master Windows build | Blacksmith Windows | The fat-LTO link is single-threaded, so 16 cores are no faster |
+| Attestation, signing, verification, TestFlight submission | GitHub-hosted | The Agent publisher verifies attestations with `--deny-self-hosted-runners`, and Blacksmith counts as self-hosted. `windows-signing`'s Azure trust names GitHub-hosted runners (C6). Signing and verify jobs restore no cache |
+| `os-helpers`, proxy arm64 image | Free `ubuntu-24.04-arm` | No heavy compile |
+| Every EIF builder that uses FlakeHub | `blacksmith-16vcpu-ubuntu-2404-arm` | One class for PR candidates, master checks and the release build (C5). `opensecret-eif.yml`'s unprivileged fork job stays on `ubuntu-24.04-arm` |
+
+The override variables (`CI_LINUX_RUNNER`, `CI_LINUX_HEAVY_RUNNER`,
+`CI_MACOS_RUNNER`, `CI_WINDOWS_RUNNER`, `CI_WINDOWS_GITHUB_RUNNER`) move lanes
+in an outage or a queue burst without a PR. They are unset by default. The
+EIF builder, `os-helpers` and the free Windows suites have none on purpose.
+C5 pins the EIF builder; the others have no better fallback.
+
+## Cache stores and keys
+
+- **Vendor stores.** Blacksmith runners use Blacksmith's Actions-cache store,
+  and GitHub runners use GitHub's. Neither reads the other's. A lane
+  therefore saves only into its home runner's store. During a fail-over it
+  restores what it can and saves nothing, so it never plants unreadable
+  entries that use up quota. GitHub's store also holds what releases restore
+  and evicts by recent use, so the jobs allowed to write it are pinned
+  (`GITHUB_STORE_WRITERS`, `GITHUB_STORE_LANES`). Moving a job across vendors
+  orphans its cache, and its next run is cold.
+- **Lane caches (`ci-v2`).** The key is the lane's cache name, a hash of its
+  toolchain pins (`cache_files`), and rust-cache's own hash of the runner's
+  rustc and `CARGO*`/`RUST*` variables. All of these must match exactly.
+  rust-cache adds the lockfile hash, which may differ: after a lockfile
+  change, the newest entry of the same lane and toolchain restores by prefix.
+  A saving master run without an exact hit first deletes the lane's target
+  directory, so each saved cache holds one dependency graph.
+- **`agent-cargo-home`.** `agent-supply-chain` and `agent-provider` only
+  resolve the Agent graph. They share a Cargo-home-only cache (registry and
+  git sources, no target), so they stop re-cloning large git dependencies.
+- **Release caches stay exact.** The signed Agent builders restore and save
+  only `ci-v1-agent-release-<os>-<hash of both lockfiles>`, with no
+  `restore-keys`. A prefix fallback could carry a removed crate's build output
+  into a signed binary. Only Prod pushes save it; the nightly Dev and dispatch
+  builds only restore it. No `ci.yml` lane reads it. A `Cargo.lock` change,
+  version bumps included, makes the next master Agent build fully cold. That
+  cost is known and accepted.
+- **Reserved prefixes.** `release.yml` restores `<os>-sccache-`,
+  `xcode-cache-`, `release-onnxruntime-ios-`, `<os>-bun-` and `<os>-gradle-`
+  by prefix. Only the signed master workflows write them. `ci.yml` only
+  restores keys that master saves. No lane family shares a prefix with a
+  release family, or a new key would hijack the release's fallback (C4).
+
+## Fat LTO and the packaging rehearsals
+
+The owner chose fat LTO with one codegen unit for Agent release builds
+(`apps/maple-agent/Cargo.toml`), because download size matters. Thin LTO
+measured clearly larger binaries. Do not re-pitch it. The consequence is a
+master Agent build of roughly 25 minutes, mostly single-threaded compile and
+link, which bigger runners do not speed up. The `ci:package` rehearsals
+deliberately build thin LTO (`FAST_RELEASE` in `lanes.py`) into their own
+`ci-v1-agent-package-*` caches. They prove the packaging, not the optimizer.
+Only the nightly master run saves those caches.
+
+## Agent Dev builds run nightly
+
+`agent-desktop-build.yml` builds Prod on master pushes, Dev nightly at 10:37
+UTC, and both on dispatch. Prod no longer waits on, or gets skipped by, a
+failed Dev leg, and each push saves a full Dev build set. The nightly run can
+never be published, because the publisher accepts only `push` and
+`workflow_dispatch` runs. The hour avoids the other scheduled runs and the
+top of the hour. Research iOS Dev TestFlight stays on push.
+
+## CodeQL only has to be "not red"
+
+The release preflight needs the newest finished CodeQL scan of the release
+commit, or an ancestor, to be green. A running or cancelled scan neither
+helps nor blocks; a red one blocks. This keeps the security signal without
+making every release wait for a fresh scan. CodeQL runs on master pushes,
+nightly and on dispatch, grouped per SHA and never cancelled. It stays on the
+free runner because nothing waits on it. It is not part of `ci-ok`.
+
+## Dependency audits run on their own inputs
+
+The `deps-*` cargo-deny lanes run when their manifest, lockfile or
+`deny.toml` changes, with `ci:full`, and nightly. CI edits never select them.
+A newly published advisory in an unrelated crate must not turn unrelated PRs
+red; the nightly run reports it. `agent-supply-chain` and `sdk-ts` still
+audit whenever they are selected.
+
+## OpenSecret EIF checks
+
+- **One runner class.** The PR candidate (`os-eif`), the trusted master
+  comparison (`opensecret-eif.yml`'s `eif-trusted`) and the release build
+  (`opensecret-eif-release.yml`) all fill or read the FlakeHub cache. Keeping
+  them on one class means no untested builder variable reaches store paths
+  that feed PCR reproducibility. Move all three together or none. C5 and
+  `plan.py lint` enforce this.
+- **Strict only where approvals are edited.** A source change alters PCRs by
+  design, and approval is a manual release step. On master a mismatch (exit
+  code 3) is an "approval pending" notice with the built PCRs. A PR that
+  edits `pcrDev*` or `pcrProd*` claims those measurements, so a mismatch for
+  that mode fails. Every other non-zero exit fails, so build errors cannot
+  hide. Approval status is not part of `ci-ok`.
+- **`os-eif` runs only for same-repository PRs to `master` that edit no
+  approval.** The job mints OIDC to write FlakeHub, which fork code must never
+  get. When a PR edits approvals, `opensecret-eif.yml` compares instead. The
+  job's `if:` repeats the planner's rule; change both together.
+- **The selector is imported verbatim.** `opensecret_change_detection.py`
+  routes every changed path, docs included. Changing its prefixes changes
+  what `opensecret-eif.yml` checks, so treat it as an OpenSecret change.
+- **Prove reproducibility, not just green.** For any change to an EIF
+  builder's checkout, Nix or flake inputs, show that narHash, drvPaths and
+  PCRs match the last master `eif-trusted` run. Check on fresh hosted runners,
+  not a warm local Nix store. A master mismatch is only a notice, so CI would
+  not catch the drift for you.
+
+## Tests: behaviour and contracts, not text
+
+Tests that assert a script's or workflow's text break on harmless renames and
+rewording and catch no behaviour. A hand-copied list of required test names
+breaks on the next rename. Test
+what the planner selects, or the contract another file consumes:
+`test_contracts.py` imports `publisher.py`, `ci_evidence.py` and the
+signature probe rather than copying their rules. Derive any list a test
+needs.
+
+The policy and contract tests do keep a few deliberate security allowlists:
+`PULL_REQUEST_WORKFLOWS`, `GITHUB_STORE_WRITERS`, `GITHUB_STORE_LANES`,
+`OIDC_JOBS`, `FLAKEHUB_JOBS`, `CONSUMERS` and `ENVIRONMENTS`. They are not
+hand-copied lists. Adding an entry widens a trust boundary, so it is an owner
+decision.
+
+## Quarantine
+
+`CI_QUARANTINE` (a repository variable) keeps a broken lane running and
+visible without failing `ci-ok`. It exists for emergencies; do not reach for
+it to merge a change. Fix the lane, or ask the owner. `repo` cannot be
+quarantined, because it enforces the policy and contract tests. See
+[CI quarantine](../../../../docs/ci.md#quarantine).

From 51cae9e7df0790042fa2ef577585b7aa49d26a6f Mon Sep 17 00:00:00 2001
From: Anthony Ronning <101225832+AnthonyRonning@users.noreply.github.com>
Date: Wed, 28 Oct 2026 06:50:06 +0000
Subject: [PATCH 2/3] docs: align CI guidance with the code and point to
 change-maple-ci

- docs/ci.md: name the advisory PR workflows, the merge model (no queue,
  no up-to-date rule), master's push lane set, nightly times, dispatch
  limits, Re-run all jobs for labels, explain's limits, local lane
  prerequisites, the 10-minute rule, FlakeHub writes, and one runner
  table that owns lane runners.
- docs/repository-workflows.md: MAPLE_HOOK_NO_NIX, FlakeHub writes from
  same-repository EIF builds, the EIF builder class and fork job, the
  Pages producer pins, and a runner table for the signed workflows; drop
  the duplicated updater-lane definition.
- AGENTS.md: route shared CI to $change-maple-ci and keep the CI rules
  short.
- Fix stale claims: Agent packaging rehearsals are label-only on PRs, the
  macOS archive scan runs on signed master builds, master no longer warms
  the fork EIF cache, Rust SDK and proxy routing for Research, the Windows
  bundle inventory, the store benchmark is not in CI, the provider suite
  runs on three OSes only nightly, proxy container builds on PRs, Research
  Windows PR staging, and os-eif in the OpenSecret skills.
- Replace duplicated lane summaries in component docs and skills with
  pointers, and use just lane repo for the root flake checks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .agents/skills/develop-maple-agent/SKILL.md   |  33 +++---
 .../review-opensecret-security/SKILL.md       |  21 ++--
 .agents/skills/validate-maple/SKILL.md        |   2 +-
 .../references/automated-checks.md            |   9 +-
 .../validate-opensecret/references/checks.md  |  17 +--
 AGENTS.md                                     |  34 +++---
 apps/maple-agent/README.md                    |  13 ++-
 apps/maple-agent/crates/store-bench/README.md |   9 +-
 apps/maple-agent/docs/desktop-builds.md       |  27 ++---
 .../docs/local-store-encryption.md            |   6 +-
 apps/maple-agent/docs/release-profiles.md     |   6 +-
 apps/maple-agent/docs/updates.md              |  16 +--
 apps/maple-auth/AGENTS.md                     |   2 +-
 apps/maple-research/README.md                 |   4 +-
 .../docs/development-contracts.md             |  10 +-
 .../docs/research-dev-desktop.md              |   4 +-
 .../src-tauri/resources/windows/README.md     |  11 +-
 docs/app-signing-environments.md              |   8 +-
 docs/ci.md                                    | 101 ++++++++++++------
 docs/development-environments.md              |   2 +-
 docs/ios-dev-testflight.md                    |   2 +-
 docs/opensecret-import.md                     |  28 +++--
 docs/pages-deployments.md                     |   9 +-
 docs/repository-workflows.md                  |  98 +++++++++--------
 proxy/README.md                               |   9 +-
 services/opensecret/docs/nitro-deploy.md      |   4 +-
 26 files changed, 272 insertions(+), 213 deletions(-)

diff --git a/.agents/skills/develop-maple-agent/SKILL.md b/.agents/skills/develop-maple-agent/SKILL.md
index a6ece143f..9767da348 100644
--- a/.agents/skills/develop-maple-agent/SKILL.md
+++ b/.agents/skills/develop-maple-agent/SKILL.md
@@ -35,26 +35,21 @@ build and performance evidence. Root `just agent-check`, `agent-build`, and
 `agent-dev` enter this component environment. The repository pre-commit hook
 runs `just ci-lint` and `just ci-test` (the `agent-lint` and `agent-test` CI
 lanes) in this shell when Agent files are staged; `MAPLE_HOOK_FULL=1` adds
-`just ci-extra`, the rest of `just ci`. Root `nix flake check
---no-update-lock-file` additionally validates workflow selection and security
-contracts when CI, Nix, or routing changes.
+`just ci-extra`, the rest of `just ci`. Root `just lane repo` additionally
+validates workflow selection and security contracts when CI, Nix, or routing
+changes.
 
 Agent has its own Cargo and Nix lockfiles. CI selects Agent for proxy runtime
 changes and for Rust SDK build inputs, both path dependencies it builds from
-the tree, but not for TypeScript SDK changes. Component-only
-changes should not unnecessarily select Research packaging. Agent lanes live in
-`scripts/ci/lanes.py`, with fixtures in `scripts/ci/test_plan.py`; root
-`just lane <id>` runs one locally. PRs run `agent-lint`, `agent-test`,
-`agent-macos` and Windows Clippy (`agent-windows`), plus the native Windows
-updater tests for updater paths, `agent-supply-chain` and `agent-provider` for
-dependency inputs, and an unsigned Dev package rehearsal for packaging inputs.
-Labels `ci:windows`, `ci:package` and `ci:full` add lanes when a change carries
-Windows or packaging risk its paths do not show
-([labels](../../../docs/ci.md#labels)); master adds the full Linux and macOS
-suites, and the full Windows suite runs nightly. On master,
-`.github/workflows/agent-desktop-build.yml` builds signed Prod packages for
-pushes that change `AGENT_DESKTOP` inputs, Dev packages nightly, and both on
-every manual dispatch.
+the tree, but not for TypeScript SDK changes. Agent lanes live in
+`scripts/ci/lanes.py`; root `just lane <id>` runs one locally. Every Agent PR
+runs Linux lint and tests plus macOS and Windows Clippy; updater and
+dependency inputs add the native Windows updater tests and supply-chain
+checks. Packaging rehearsals and the full suites run by label (`ci:package`,
+`ci:windows`, `ci:full`), nightly, or on master. Load
+`$change-maple-ci` for what each label adds and how to trigger it, and
+[desktop builds](../../../apps/maple-agent/docs/desktop-builds.md) for the
+signed master packages.
 
 Linux Nix packages use a pure source fileset rooted at the monorepo, including
 the sibling SDK/proxy source and SDK assets. Validate it when adding a new local dependency
@@ -113,9 +108,7 @@ platform-specific signed installed-update rehearsal. Linux uses user-owned tar
 bundles and a separate v2 wire schema, preserving the shipped macOS v1 feed;
 one release may update both platforms to the same version.
 Windows x64 Dev/Prod installers are built by the same desktop workflow, with
-master Authenticode signing through the existing `windows-signing` environment;
-like macOS and Linux, master pushes build only Prod, the nightly run builds
-Dev, and a manual dispatch builds both.
+master Authenticode signing through the existing `windows-signing` environment.
 Windows Prod uses its signed v3 update feed and generation tar bundle; its
 signed NSIS setup remains the manual installation download. Normal publication
 includes Windows through the same protected publisher as macOS and Linux,
diff --git a/.agents/skills/review-opensecret-security/SKILL.md b/.agents/skills/review-opensecret-security/SKILL.md
index a672e69d4..4c3a103ce 100644
--- a/.agents/skills/review-opensecret-security/SKILL.md
+++ b/.agents/skills/review-opensecret-security/SKILL.md
@@ -132,17 +132,20 @@ Load `$validate-opensecret` and run the tiers reached by the diff. Report local,
 database, provider, client, build/artifact, and live evidence separately.
 
 Local artifact builds and read-only PCR comparison are validation when in
-scope. Root backend CI validates Rust, Nix checks, and SDK compatibility. A
-separate ARM64 workflow compares dev/prod EIF
-measurements on explicit approved-PCR JSON edits in PRs, relevant master
-changes, and manual runs. Do not require ordinary backend PRs to update
+scope. Root backend CI validates Rust, Nix checks, and SDK compatibility.
+`ci.yml`'s `os-eif` lane builds dev/prod EIF candidates for same-repository
+PRs to `master` without comparing approvals. `opensecret-eif.yml` compares
+dev/prod EIF measurements on explicit approved-PCR JSON edits in PRs,
+relevant master changes, and manual runs. Do not require ordinary backend PRs to update
 approvals. A master mismatch is a pending-approval notice with the built PCRs;
 do not hide it or turn it into a pass without that notice. Master push/manual
-runs and same-repository PR comparisons receive OIDC for FlakeHub caching;
-fork PRs and non-master manual refs use GitHub's branch-scoped cache without
-OIDC. Review event/ref guards and the PR head-repository equality check,
-including missing metadata, cache provenance, and default-branch versus PR
-cache scope. Same-repository PR code is intentionally trusted to write FlakeHub.
+runs, same-repository PR comparisons and the `os-eif` candidate receive OIDC
+for FlakeHub caching; fork PRs and non-master manual refs use GitHub's
+branch-scoped cache without OIDC. Review event/ref guards and the PR
+head-repository equality check, including missing metadata, cache
+provenance, and default-branch versus PR cache scope. For `os-eif`, the
+planner's candidate rule in `scripts/ci/plan.py` and the job's `if:` in
+`ci.yml` must agree. Same-repository PR code is intentionally trusted to write FlakeHub.
 Cache writes never authorize approval changes, signing, EIF releases, or
 deployment. A passing comparison is not live
 deployment evidence or proof that both public PCR locations are synchronized.
diff --git a/.agents/skills/validate-maple/SKILL.md b/.agents/skills/validate-maple/SKILL.md
index 52c315c2c..274277908 100644
--- a/.agents/skills/validate-maple/SKILL.md
+++ b/.agents/skills/validate-maple/SKILL.md
@@ -15,7 +15,7 @@ Follow [development environments](../../../docs/development-environments.md).
 Any backend change, heavy feature, or specific frontend/backend/log/billing
 interaction uses an isolated linked Local stack. Small frontend work may
 intentionally use hosted Dev with a valid Dev account/login. Keep effective
-API/project, auth route, account, and dependent services in the selected lane.
+API/project, auth route, account, and dependent services in the selected environment.
 A debug build, simulator, or package does not prove Local.
 
 Use the union of checks for changed boundaries; add relevant lower-level
diff --git a/.agents/skills/validate-maple/references/automated-checks.md b/.agents/skills/validate-maple/references/automated-checks.md
index ae5d10636..467cbce18 100644
--- a/.agents/skills/validate-maple/references/automated-checks.md
+++ b/.agents/skills/validate-maple/references/automated-checks.md
@@ -113,10 +113,10 @@ A component check or image build is not runtime evidence.
 ### Repository configuration checks
 
 ```bash
-nix flake check --no-update-lock-file
+just lane repo
 ```
 
-This validates pinned tool versions, GitHub Actions syntax, and release metadata. Run it for changes to `flake.nix`, `flake.lock`, workflows, CI scripts, or release configuration. It is not a substitute for product tests.
+This runs every root flake check (`nix flake check`): pinned tool versions, GitHub Actions syntax and policy, CI scripts, release contracts and metadata. Run it for changes to `flake.nix`, `flake.lock`, workflows, CI scripts, release configuration, or docs that name workflows. It is not a substitute for product tests.
 
 Do not cite the pre-commit hook as complete proof: it runs only the format, lint, type-check, and unit-test lanes for the components whose files are staged, and never the integration suites, cargo-deny, `nix flake check`, or packaging.
 
@@ -124,6 +124,8 @@ Do not cite the pre-commit hook as complete proof: it runs only the format, lint
 
 Use these commands to mirror PR artifact builds (the `research-desktop-*`, `research-android` and
 `research-ios` lanes; `just lane <id>` runs one). Then launch and smoke the result separately.
+iOS and Android lanes run on PRs that touch their native inputs; desktop bundles run only with
+the `ci:package` label ([CI labels](../../../../docs/ci.md#labels)).
 
 These scripts deliberately hide local `.env*` files and compile fixed PR
 endpoint profiles. Their artifacts are PR packaging evidence; they do not prove
@@ -144,10 +146,11 @@ MAPLE_TAURI_FAKE_UPDATER_SIGNING=1 nix develop --no-update-lock-file .#desktop-l
 
 ### Windows desktop
 
-Run on real Windows from Git Bash/MSYS:
+Run on real Windows from Git Bash/MSYS. The lane then verifies the build's proof manifests:
 
 ```bash
 ./scripts/ci/desktop-windows-pr.sh
+./scripts/ci/verify-release-artifacts.sh ./apps/maple-research/frontend/src-tauri/target windows
 ```
 
 ### Android
diff --git a/.agents/skills/validate-opensecret/references/checks.md b/.agents/skills/validate-opensecret/references/checks.md
index 2ce1298b4..78923a548 100644
--- a/.agents/skills/validate-opensecret/references/checks.md
+++ b/.agents/skills/validate-opensecret/references/checks.md
@@ -74,8 +74,8 @@ database suites, including OAuth settings preservation, callback selection,
 and Google/GitHub callback completion through the real V1 encryption middleware
 and V2 gateway. Completion tests exchange synthetic credentials only with
 local mock token/user-info endpoints, verify the originally selected callback
-after settings change, and reject replay without another exchange. The SDK
-integration workflow runs this helper too. These fixtures do not prove a live
+after settings change, and reject replay without another exchange. The
+`os-sdk-e2e` lane in `ci.yml` runs this helper too. These fixtures do not prove a live
 OAuth provider flow, a released SDK or application, or a data conversion from
 representative old rows.
 
@@ -157,10 +157,12 @@ nix build --no-link --no-write-lock-file '.?submodules=1#default'
 PCR reference/history updates remain operator-controlled release work.
 Read-only EIF construction and PCR comparison are validation when in scope.
 Root backend CI runs the component flake checks but does not build the
-default package. The separate root EIF approval workflow builds dev/prod
-and compares generated measurements on PRs that explicitly edit the four
-approved PCR JSON files, relevant backend/TEE or approval changes to master,
-and manual runs. Ordinary backend PRs do not require new PCR approvals. A PR
+default package. `ci.yml`'s `os-eif` lane builds dev/prod EIF candidates for
+same-repository PRs to `master` that change measured inputs (or carry
+`ci:eif`) without editing approvals; it reports PCRs and compares nothing.
+`opensecret-eif.yml` builds dev/prod and compares generated measurements on
+PRs that explicitly edit the four approved PCR JSON files, relevant
+backend/TEE or approval changes to master, and manual runs. Ordinary backend PRs do not require new PCR approvals. A PR
 fails on a mismatch only in an environment whose approval files it edits; a
 master mismatch passes with a notice and the built PCRs, meaning the revision
 awaits approval. The check script exits 3 for a mismatch and with another
@@ -177,7 +179,8 @@ For EIF cache/workflow changes, follow
 FlakeHub OIDC for master and same-repository PRs, with forks and other manual
 refs on the unprivileged GitHub cache path. Verify actual authentication,
 custom-kernel substitution, and timing on fresh hosted ARM64 master and
-same-repository PR runs, then fork reuse of the GitHub cache warmed by master.
+same-repository PR runs, and check fork runs separately for cache misses and
+cold-build duration; master does not guarantee a warm cache for forks.
 Local store hits and skipped PR jobs cannot establish hosted cache performance
 or cross-organization access.
 
diff --git a/AGENTS.md b/AGENTS.md
index 9ce244322..e1b65bccc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,7 +15,7 @@ out of the task.
 | `proxy/` | [Proxy guide](proxy/README.md); `$develop-maple-proxy` for the separate OpenAI-compatible relay |
 | `services/opensecret/` | [Backend guide](services/opensecret/AGENTS.md); `$develop-opensecret` and its API/provider/validation/security skills |
 | `services/updates/` | [Updater guide](services/updates/README.md); preserve deployed identity and installed-client metadata compatibility |
-| Shared CI, Nix, hooks, docs | [CI](docs/ci.md) and [repository workflows](docs/repository-workflows.md); root `scripts/`, `.github/`, `.agents/`, flake, Just and repository metadata |
+| Shared CI, Nix, hooks, docs | `$change-maple-ci` to change, trigger or debug CI; [CI](docs/ci.md) and [repository workflows](docs/repository-workflows.md); root `scripts/`, `.github/`, `.agents/`, flake, Just and repository metadata |
 
 ## Choose the development environment
 
@@ -67,12 +67,11 @@ or hook pass does not prove runtime integration.
 
 ### Pre-commit hook
 
-`./setup-hooks.sh` enables component-selected fast gates. Research Rust runs
-formatting and tests; strict Clippy is a separate optional diagnostic, absent
-from current Research CI/hook. Hooks do not run integration, cargo-deny, flake
-checks, or packaging. Read [hook details](docs/repository-workflows.md#pre-commit-hook)
-when those boundaries change; run `just lane repo` (the root `nix flake check`)
-for flake, workflow, CI-script, or release-configuration changes.
+`./setup-hooks.sh` enables component-selected fast gates; they do not run
+integration, cargo-deny, flake checks, or packaging
+([hook details](docs/repository-workflows.md#pre-commit-hook)). Run
+`just lane repo` (the root `nix flake check`) for flake, workflow, CI-script,
+release-configuration or documentation changes.
 
 Routine development never authorizes signing, releases, store uploads, deployment,
 or live-service changes. A master push can start signed builds/TestFlight uploads;
@@ -83,20 +82,23 @@ and installed-client raw URLs. Never change approvals to clear ordinary PR check
 
 ## CI rules for agents
 
-- `ci-ok` is the one required check; [CI](docs/ci.md) explains its lanes and labels.
-- Add or change checks only through `scripts/ci/lanes.py`, as lanes with a
+Load `$change-maple-ci` before changing, triggering or debugging CI; it holds
+the full rules and their reasons. In short:
+
+- `ci-ok` is the one required check. Without labels, every PR reaches it well
+  under 10 minutes; slower builds run only by `ci:*` label, nightly, or on master.
+- Add or change checks only as lanes in `scripts/ci/lanes.py`, each with a
   `test_plan.py` case; no new side workflows or bespoke guard scripts.
 - Never put `[skip ci]`, `[ci skip]` or similar in a commit or PR title: master
   plans each push from the previous commit, so a skipped commit is never checked.
-- Never write tests that assert a script's or workflow's text; test behavior, or
-  a contract another file consumes (`test_contracts.py`). Never hand-copy lists
-  of test names; a required list must be derived, not maintained.
-- Pull requests never save caches, and master runs are never cancelled.
+- Test behavior, or a contract another file consumes; never a script's or
+  workflow's text, and never hand-copied lists of names.
+- Pull requests never save an Actions cache, and master runs are never cancelled.
 - Never edit release or publisher workflows, signing environments, or OpenSecret
   approval gating to clear a check; a failing contract test means fix the change.
-- Run `just lane <id>` for the lanes your change selects before pushing.
-- Defaults cover ordinary PRs. Add a `ci:*` label when the change carries
-  platform or packaging risk its paths do not show ([labels](docs/ci.md#labels)).
+- Run `just lane <id>` for the lanes your change selects before pushing. Add a
+  `ci:*` label when the change carries platform or packaging risk its paths do
+  not show ([labels](docs/ci.md#labels)).
 
 ## Maintaining this guidance
 
diff --git a/apps/maple-agent/README.md b/apps/maple-agent/README.md
index aad39d0ad..57e72e30d 100644
--- a/apps/maple-agent/README.md
+++ b/apps/maple-agent/README.md
@@ -347,9 +347,10 @@ user-local tar bundles.
 
 The root also offers `just agent-check`, `just agent-build`, and
 `just agent-dev`. Native development on macOS requires full Xcode at
-`/Applications/Xcode.app`; Linux libraries come from Nix. Windows CI uses the
-same Rust version resolved by the component’s pinned `flake.lock`, with
-Cargo commands from this directory. The statically linked SQLCipher/OpenSSL
+`/Applications/Xcode.app`; Linux libraries come from Nix. Windows has no Nix:
+`.github/actions/setup-agent-windows` pins the Rust version that the
+component's `flake.lock` resolves, and the `agent-lint` lane fails if the two
+differ. Cargo commands run from this directory. The statically linked SQLCipher/OpenSSL
 build needs Perl; Nix supplies it on macOS/Linux. Windows needs native Windows
 Perl (for example Strawberry Perl), rather than MSYS Perl. NASM enables the
 provider's assembly path when available; its build supports a no-assembly fallback.
@@ -633,10 +634,8 @@ change the desktop theme. Parser, environment-scrubbing and palette precedence
 tests run in the ordinary app test suite.
 
 The root `ci.yml` runs this component's lanes (`scripts/ci/lanes.py`) when
-Agent or its shared Rust dependencies change: format, lint and tests on Linux
-and clippy on macOS and Windows for every PR, the full Linux and macOS suites
-on master, and the full Windows suite nightly. Root `just lane <id>` runs one
-lane as CI does. `just ci` is the full local format, lint, build and test gate;
+Agent or its shared Rust dependencies change; [CI](../../docs/ci.md) lists the
+tiers and labels. Root `just lane <id>` runs one lane as CI does. `just ci` is the full local format, lint, build and test gate;
 `just release` separately validates the optimized binary. PR jobs have no signing or publishing credentials. See the
 root agent guide for shared checks.
 
diff --git a/apps/maple-agent/crates/store-bench/README.md b/apps/maple-agent/crates/store-bench/README.md
index d12c567a5..18234e0d1 100644
--- a/apps/maple-agent/crates/store-bench/README.md
+++ b/apps/maple-agent/crates/store-bench/README.md
@@ -12,7 +12,8 @@ nix develop --no-update-lock-file . -c just store-bench-ci
 nix develop --no-update-lock-file . -c just store-bench
 ```
 
-The CI fixture has 40 tasks / 8,000 entries, including a 2,000-entry hot task.
+The small `store-bench-ci` fixture has 40 tasks / 8,000 entries, including a
+2,000-entry hot task.
 The full fixture has 2,000 tasks / 1,000,000 entries, including a 100,000-entry
 hot task and a 20,000-entry long task. The deterministic generator adapts the
 research harness's shape to current typed Pi messages. It creates real user
@@ -64,13 +65,13 @@ Each JSON result has a sibling SHA-256 file and records engine/provider
 versions, source revision/dirty state, executable digest, OS/CPU/memory, load,
 dataset identity and settings. No synthetic database or key is uploaded.
 
-## References and CI
+## References
 
 `scripts/evaluate.py` requires both modes, the canonical seed/scale, all
 scenarios and their sample counts, effective durability settings, and indexed
 plans with and without statistics. Missing scenarios cannot silently remove a
-slow operation. Linux CI compares medians at 10x its actual Linux reference;
-the `macos-full` profile uses 2x its actual macOS reference. Platform
+slow operation. The `linux-ci` profile compares medians at 10x its recorded
+Linux reference; the `macos-full` profile uses 2x its recorded macOS reference. Platform
 mismatches are rejected. Native Mac small runs can use `--profile linux-ci
 --diagnostic` to validate workload evidence without comparing or recording a
 Linux runner gate.
diff --git a/apps/maple-agent/docs/desktop-builds.md b/apps/maple-agent/docs/desktop-builds.md
index 7cc0b3b1e..75d091f22 100644
--- a/apps/maple-agent/docs/desktop-builds.md
+++ b/apps/maple-agent/docs/desktop-builds.md
@@ -8,9 +8,9 @@ diff; an unusable diff or a selector error builds. No master run is
 cancelled, so every Agent push gets its own packages. A later push without Agent
 changes does not retry a failed run: re-run its failed jobs, dispatch, or fix
 forward. The unsigned Dev packaging rehearsals in `ci.yml`
-(`agent-package-linux`, `agent-package-macos`, `agent-package-windows`) run
-nightly and on pull requests with the `ci:package` label; add it when a PR
-changes packaging or release scripts, the Agent flake or the toolchains.
+(`agent-package-*`) run nightly and on pull requests with the `ci:package`
+label ([CI labels](../../../docs/ci.md#labels)); add it when a PR changes
+packaging or release scripts, the Agent flake or the toolchains.
 
 Unrelated master commits have no new Agent artifacts. Existing downloads keep
 their original source SHA and provenance; they are never relabeled as a newer
@@ -25,9 +25,8 @@ per-user NSIS installers requiring Windows 10 version 1703 (build 15063) or late
 imported by GPUI; see Microsoft's [Windows ICU version history](https://learn.microsoft.com/en-us/windows/win32/intl/international-components-for-unicode--icu-).
 Trusted master
 packages use the existing Azure publisher to Authenticode-sign the application,
-embedded uninstaller and final installer. Pull requests that change those
-Windows packaging inputs, or carry the `ci:package` label, build, install and
-smoke-test an unsigned Dev installer.
+embedded uninstaller and final installer. Pull requests with the
+`ci:package` label build, install and smoke-test an unsigned Dev installer.
 
 | Profile | Application | macOS bundle ID | Configuration/data namespace | Update delivery |
 | --- | --- | --- | --- | --- |
@@ -192,7 +191,9 @@ return validation; package metadata alone does not prove those browser flows.
 
 ## Packaging commands
 
-From `apps/maple-agent`, using the pinned component shell:
+From `apps/maple-agent`, using the pinned component shell (`just
+package-rehearsal` runs the host platform's sequence, as the `agent-package-*`
+lanes do):
 
 ```sh
 nix develop --no-update-lock-file . -c ./scripts/build-release.sh dev
@@ -208,10 +209,12 @@ continues to use the macOS feed. Dev has no update feed on either platform.
 Both platforms retain one release version and source commit; separate feed
 paths preserve compatibility with existing macOS clients.
 
-Windows builds run on `blacksmith-8vcpu-windows-2025` with the pinned Rust/MSVC
-environment from `.github/actions/setup-agent-windows` and
-`RUSTFLAGS='-D warnings -C target-feature=+crt-static'`; signing stays on
-GitHub's `windows-2025`. `build-release.sh` selects the explicit x64 MSVC target
+Windows builds use the pinned Rust/MSVC environment from
+`.github/actions/setup-agent-windows` and
+`RUSTFLAGS='-D warnings -C target-feature=+crt-static'`. Master's unsigned
+build compiles on Blacksmith Windows; signing, verification and the
+`ci:package` rehearsal's install smoke run on GitHub's Windows image
+([CI runners](../../../docs/ci.md#runners)). `build-release.sh` selects the explicit x64 MSVC target
 so host build tools keep their normal linkage, then stages the exact resulting
 executable.
 From the component directory in Git Bash on Windows:
@@ -231,7 +234,7 @@ a separate credential-free verifier.
 The exact five final files, build number, source/profile and fixed tar inventory
 are checked before attestation and again after download. The tar is generated
 from the same extracted installer generation, so its signed executable and
-all public notice/descriptor bytes match. Native preflight checks destination
+all public license/descriptor bytes match. Native preflight checks destination
 and code trust before installed files or registration change; a durable manual
 install intent permits safe interrupted-install recovery. Unsigned Prod must
 refuse before modification; unsigned Dev remains a positive install/GUI/uninstall
diff --git a/apps/maple-agent/docs/local-store-encryption.md b/apps/maple-agent/docs/local-store-encryption.md
index 4f1e0dbeb..90404b5fe 100644
--- a/apps/maple-agent/docs/local-store-encryption.md
+++ b/apps/maple-agent/docs/local-store-encryption.md
@@ -86,8 +86,10 @@ macOS's native-TLS activation with Linux's backend selection creates a false
 OpenSSL edge. The build verifier additionally checks each target's actual Cargo
 feature graph. The signed-source verifier regenerates the amalgamation and
 compares its bytes, allowing only the source crate's documented WASM guard.
-CI is configured to run released rusqlite's suite against this static provider
-on all three platforms. Local macOS results do not substitute for Linux or Windows.
+The `Nightly` workflow runs released rusqlite's suite against this static
+provider on Linux, macOS and Windows; pull requests and master pushes that
+change the provider inputs run it on Linux (`agent-provider`). Local macOS
+results do not substitute for Linux or Windows.
 
 On 2026-10-21, the local pinned macOS shell passed the released rusqlite 0.40.2
 `modern-full` suite against the patched provider: 334 passing tests and three
diff --git a/apps/maple-agent/docs/release-profiles.md b/apps/maple-agent/docs/release-profiles.md
index c12406083..7a64a1d66 100644
--- a/apps/maple-agent/docs/release-profiles.md
+++ b/apps/maple-agent/docs/release-profiles.md
@@ -95,9 +95,9 @@ The final Windows package artifact has exactly five files: the signed manual
 installer, its versioned updater `.tar.gz`, `build-info.json`, `manifest.json`
 and `SHA256SUMS`. The manifest binds the positive decimal Actions build number,
 source, profile, installer and updater names. The bundle's
-`maple-agent-windows/` root contains the signed application, public build and
-bundle descriptors, license and the fixed notice/wordlist inventory. It omits
-the uninstaller.
+`maple-agent-windows/` root contains exactly the signed application, the
+public build and bundle descriptors, and the license. It omits the
+uninstaller.
 
 Windows installations keep a stable signed root launcher and uninstaller, plus
 immutable generation payloads under `versions/<version>-<build>/`. A native
diff --git a/apps/maple-agent/docs/updates.md b/apps/maple-agent/docs/updates.md
index d603a53cf..78ca3b0d1 100644
--- a/apps/maple-agent/docs/updates.md
+++ b/apps/maple-agent/docs/updates.md
@@ -332,22 +332,22 @@ cd apps/maple-agent
 nix develop --no-update-lock-file -c just ci
 ```
 
-Workflow and configuration changes also require the root pinned
-`nix flake check --no-update-lock-file`. Focused core and installer tests cover
+Workflow and configuration changes also require root `just lane repo` (the
+pinned `nix flake check`). Focused core and installer tests cover
 signature, schema, anti-rollback, interrupted downloads, saved-state tampering,
 archive/path attacks, staging integrity, replacement receipts and lock exclusion.
-Prod macOS packaging also runs the real installer archive scanner against each
-produced unsigned PR or signed master `.app.tar.gz`, binding the scanned bytes to
+Signed Prod macOS packaging on master also runs the real installer archive
+scanner against each produced `.app.tar.gz`, binding the scanned bytes to
 the package checksum before final upload/attestation. BSDtar host metadata is
 explicitly omitted during creation; signed file contents and existing native
 signature/notarization checks remain intact.
 They do not prove Developer ID distribution, deployed service behavior, or a
 successful real package update.
 
-The `agent-windows-updater` lane in `ci.yml` runs `cargo test -p
-maple-agent-updater --locked --no-fail-fast -- --test-threads=1` on Windows, with no signing or publication
-credentials: the native filesystem, trust rejection, transaction and recovery
-tests and the bootstrap component test. These fixtures do not establish
+The `ci.yml` `agent-windows-updater` lane runs the updater's native Windows
+tests with no signing or publication credentials: the filesystem, trust
+rejection, transaction and recovery tests and the bootstrap component test.
+These fixtures do not establish
 official Maple signatures, installed A-to-B updates, visible GUI or paired
 remote-upgrade behavior. Record those qualifications separately from a green
 component job or an installer consumer.
diff --git a/apps/maple-auth/AGENTS.md b/apps/maple-auth/AGENTS.md
index 3ba995319..267fba76a 100644
--- a/apps/maple-auth/AGENTS.md
+++ b/apps/maple-auth/AGENTS.md
@@ -11,7 +11,7 @@ Use the root `.#ci` Nix shell (Bun and Node match CI). See [README.md](README.md
 for development, component checks and the fixed Dev/Prod build profiles. Run
 `scripts/ci/auth-ci.sh` for format, lint, type checking, and tests. The root hook
 routes this app to `.githooks/pre-commit`. Run the auth build when source,
-configuration or dependencies change, and root `nix flake check` for workflow
+configuration or dependencies change, and root `just lane repo` for workflow
 or shared CI changes. Do not overwrite ignored environment files.
 
 The required `VITE_AUTH_ENVIRONMENT` selector fixes the backend, project and PCR
diff --git a/apps/maple-research/README.md b/apps/maple-research/README.md
index c20332a04..c814bcedb 100644
--- a/apps/maple-research/README.md
+++ b/apps/maple-research/README.md
@@ -153,8 +153,8 @@ nix develop --no-update-lock-file .#ci -c ./scripts/ci/rust.sh
 # PR-configured web artifact
 MAPLE_WEB_ENVIRONMENT=pr nix develop --no-update-lock-file .#ci -c ./scripts/ci/web.sh
 
-# Nix/toolchain/workflow metadata; not application tests
-nix flake check --no-update-lock-file
+# Nix/toolchain/workflow metadata (every root flake check); not application tests
+just lane repo
 ```
 
 There is no general checked-in browser, packaged-app, or React-to-Tauri-command
diff --git a/apps/maple-research/docs/development-contracts.md b/apps/maple-research/docs/development-contracts.md
index aff1c930f..bbf413c62 100644
--- a/apps/maple-research/docs/development-contracts.md
+++ b/apps/maple-research/docs/development-contracts.md
@@ -40,10 +40,12 @@ checks for every affected client path.
 The Maple Proxy source lives under `proxy/`. From the repository root,
 run its Rust commands through
 `nix develop --no-update-lock-file ./proxy -c bash -lc 'cd proxy && ...'`;
-the root `ci.yml` `proxy` lane owns proxy CI. Proxy runtime changes select desktop
-builds; SDK-only changes do not, since Research builds the SDK source its own
-manifests select. Container, test, documentation, and standalone lockfile
-changes remain independent.
+the root `ci.yml` `proxy` lane owns proxy CI. Proxy runtime and Rust SDK build
+changes select `research-rust` on PRs and the signed native builds on master,
+because the Research shell builds both from the tree. TypeScript SDK changes
+select no app build, since Research builds the SDK its own manifests select.
+Container, test, documentation, and standalone lockfile changes remain
+independent.
 
 ## Code ownership and placement
 
diff --git a/apps/maple-research/docs/research-dev-desktop.md b/apps/maple-research/docs/research-dev-desktop.md
index 9ca9a1a42..14780599e 100644
--- a/apps/maple-research/docs/research-dev-desktop.md
+++ b/apps/maple-research/docs/research-dev-desktop.md
@@ -72,8 +72,8 @@ under `target/research-dev/cargo` rather than replacing ordinary desktop outputs
 Only this explicit local command builds the Dev RPM; existing PR/release package
 jobs and production identities are unchanged.
 
-Older `ci-desktop-pr` RPMs use Dev services but retain the production `maple`
-package identity. They do **not** install beside production. Restore the website
+Ordinary Research PR package RPMs (the `research-desktop-linux` lane) use Dev
+services but retain the production `maple` package identity. They do **not** install beside production. Restore the website
 RPM to that slot separately; for equal versions use `sudo dnf reinstall ./<rpm>`,
 or `sudo dnf downgrade ./<rpm>` if the website version is older. Sign in again if
 needed; do not copy credentials between the two apps. No automatic data migration
diff --git a/apps/maple-research/frontend/src-tauri/resources/windows/README.md b/apps/maple-research/frontend/src-tauri/resources/windows/README.md
index 6b00d67c0..796c90638 100644
--- a/apps/maple-research/frontend/src-tauri/resources/windows/README.md
+++ b/apps/maple-research/frontend/src-tauri/resources/windows/README.md
@@ -43,7 +43,8 @@ must be staged here **before `bun tauri build`** on Windows.
 
 ## CI staging
 
-The Windows PR and signed release workflows stage these automatically through
+The `research-desktop-windows` CI lane (on pull requests with `ci:package`)
+and the signed builds stage these automatically through
 `scripts/ci/desktop-windows-pr.sh` and `scripts/ci/desktop-windows-release.sh`
 before the Tauri build. Those scripts use:
 
@@ -58,10 +59,10 @@ field. The staging script therefore rejects ARM64EC markers and only copies
 native AMD64 runtime DLLs into the installer payload.
 
 The PR build emits `target/reproducibility/desktop-pr-windows-*.sha256` proof
-manifests. The signed release build emits
-`target/reproducibility/desktop-release-windows-*.sha256` proof manifests after
-the installer is Authenticode-signed and the final Tauri updater `.sig` is
-generated. CI verifies those manifests from uploaded artifacts.
+manifests, which the same lane verifies after the build. The signed release
+build emits `target/reproducibility/desktop-release-windows-*.sha256` proof
+manifests after the installer is Authenticode-signed and the final Tauri
+updater `.sig` is generated; CI verifies those from uploaded artifacts.
 
 For a **local** Windows build, run `scripts/provide-windows-onnxruntime.sh`
 first (it exports `ORT_DYLIB_PATH`), then run the same staging helper:
diff --git a/docs/app-signing-environments.md b/docs/app-signing-environments.md
index 66f8669ea..0df7fc13a 100644
--- a/docs/app-signing-environments.md
+++ b/docs/app-signing-environments.md
@@ -92,11 +92,11 @@ and bucket remain independent; Research's workflow and configuration are unchang
 
 `apple-signing` remains automatic for now because Maple Dev and production iOS
 share its credentials. Gating this environment would also interrupt the
-automatic Maple Dev TestFlight lane, potentially at both its build and upload
+automatic Maple Dev TestFlight workflow, potentially at both its build and upload
 jobs. Production iOS therefore remains an explicit exception until the
 credentials are separated. A second GitHub environment containing a copy of
 the same production-capable key would not close that boundary: the automatic
-development lane must lose access to production-capable credentials first.
+development workflow must lose access to production-capable credentials first.
 Do not switch a workflow to a new environment before its credentials and
 policies are ready.
 
@@ -112,8 +112,8 @@ or incomplete migration must leave the working source credentials intact.
 Rerunning an old workflow revision that predates these environment declarations
 will no longer have signing access; use a current reviewed revision instead.
 
-`nix flake check --no-update-lock-file` checks workflow syntax and the signing
-job boundaries. The manual `Check app signing credentials` workflow checks
+`just lane repo` (the root `nix flake check`) checks workflow syntax and the
+signing job boundaries. The manual `Check app signing credentials` workflow checks
 credential availability without signing, building, or publishing anything. Only
 jobs using an environment with required reviewers, such as `zapstore-publishing`,
 pause for approval. Run it on `master`; a run from a feature branch should be
diff --git a/docs/ci.md b/docs/ci.md
index 1e9fd3c78..d66984ac3 100644
--- a/docs/ci.md
+++ b/docs/ci.md
@@ -1,10 +1,14 @@
 # CI
 
-`.github/workflows/ci.yml` runs every check a pull request needs. Its one
-verdict, `ci-ok`, is the required status check: it passes when every lane the
-planner selected succeeded, and an unselected lane may only be skipped. Signed
-builds, publication, caches and the contracts CI keeps are in
-[repository workflows](repository-workflows.md).
+`.github/workflows/ci.yml` runs every required pull-request check. Its one
+verdict, `ci-ok`, is the only required status check: it passes when every
+lane the planner selected succeeded, and an unselected lane may only be
+skipped. `opensecret-eif.yml`, `pages-preview-build.yml`, `auth-pages-ci.yml`
+and `proxy-rust.yml` also run on matching pull requests; they are advisory
+and not part of `ci-ok`. Signed builds, publication, caches and the contracts
+CI keeps are in [repository workflows](repository-workflows.md). Agents
+changing or triggering CI load
+[`$change-maple-ci`](../.agents/skills/change-maple-ci/SKILL.md).
 
 ## How lanes are chosen
 
@@ -13,12 +17,15 @@ consumers it fans out to (`also`), events, labels, runner, Nix shell, command
 and timeout. `scripts/ci/plan.py` (the `plan` job) selects lanes from the diff:
 
 - A pull request is judged on its own diff from the merge base with its base
-  branch, so each layer of a stack gets its own `ci-ok`. A merge-queue group
-  uses its base and head; a master push uses `before..after`.
+  branch, so each layer of a stack gets its own `ci-ok`. A master push uses
+  `before..after`. (`ci.yml` also handles a merge-queue group, by its base and
+  head, but the repository has no merge queue.) Without a usable diff, such
+  as a new branch or a force-push, every lane runs.
 - Docs, guides and component hooks select no lane but those the OpenSecret
   selector routes them to (below). A path that no lane owns selects every
-  lane. Editing `ci.yml`, the planner or `.github/actions/` selects every gate
-  lane.
+  lane, the label-only builds included. Editing `ci.yml`, the planner or
+  `.github/actions/` selects every gate lane, but not the slow builds that
+  run only by label.
 - If selection fails on a pull request, `plan` and `ci-ok` fail; master,
   nightly and dispatch runs select every lane instead.
 - OpenSecret lanes are selected by `scripts/ci/opensecret_change_detection.py`,
@@ -37,14 +44,22 @@ The `plan` job summary lists each selected lane and why. To preview locally:
 python3 scripts/ci/plan.py explain --base origin/master --head HEAD
 ```
 
+`explain` also reads paths from stdin, and `--event push` shows master's
+selection. It applies no labels and lists `os-eif` for any EIF input, without
+the same-repository, base-`master` and approval-edit checks.
+
 ## Tiers
 
 | When | What runs |
 | --- | --- |
-| Pull request, merge queue | Selected lanes, each a few minutes; the iOS and Android builds when their native inputs change. Desktop bundles and packaging rehearsals never block a PR; add `ci:package` to run them. A new push cancels the superseded run. |
-| Master push | The selected lanes again (for Agent inputs, also the full Agent suites on Linux and macOS), the signed builds (Agent: Prod only), the release-evidence workflows and CodeQL. Never cancelled. |
-| Nightly | `ci.yml` runs its nightly lanes on the master tip, Rust advisories and the Agent's native Windows suites included, which also refreshes their caches. `nightly.yml` runs the Bun advisories and the SQLCipher provider suite on every OS. Failures and [quarantined lanes](#quarantine) open or update one `ci-nightly` issue; a green night closes it. Separately, at 10:37 UTC, `agent-desktop-build.yml` builds, signs and verifies the Agent Dev packages; the `ci-nightly` issue does not cover it. |
-| On demand | PR labels (below), or a `ci.yml` dispatch with comma-separated lane ids or `all`. |
+| Pull request | Selected lanes, each a few minutes; the iOS and Android builds when their native inputs change, and the OpenSecret EIF candidate for measured inputs. Desktop bundles and packaging rehearsals never block a PR; add `ci:package` to run them. A new push cancels the superseded run. |
+| Master push | The selected lanes that also run on push: the Research web, Rust and platform lanes and `auth` run only on pull requests, because `frontend-tests.yml`, `rust-tests.yml`, `web-build.yml`, the signed builds and `auth-pages-ci.yml` cover master. Agent inputs add the full Agent suites on Linux and macOS. Also the signed builds (Agent: Prod only), the release-evidence workflows and CodeQL. Never cancelled. |
+| Nightly (UTC) | At 04:17 `ci.yml` runs its nightly lanes on the master tip, Rust advisories, packaging rehearsals and the Agent's native Windows suites included, which also refreshes their caches. At 05:47 `nightly.yml` runs the Bun advisories and the SQLCipher provider suite on every OS. Failures and [quarantined lanes](#quarantine) open or update one `ci-nightly` issue; a green night closes it. CodeQL runs at 05:28. At 10:37 `agent-desktop-build.yml` builds, signs and verifies the Agent Dev packages; the `ci-nightly` issue covers neither of these. |
+| On demand | PR labels (below), or a `ci.yml` dispatch with comma-separated lane ids or `all`. Dispatch runs never save caches. `os-eif` cannot be dispatched: an id that is not a dispatch lane, a typo included, makes the run fall back to every dispatch lane. |
+
+`master` requires `ci-ok` and auto-merge is on. Branches need not be up to
+date, so master's own push run is the check for conflicts between pull
+requests that each passed alone.
 
 ## Labels
 
@@ -58,12 +73,14 @@ a change could break something only those builds reveal, for example:
 - `ci:ios` or `ci:android` for Research changes that reach native mobile code or mobile-only plugins;
 - `ci:full` for toolchain, lockfile-wide or other risky cross-cutting changes before merge.
 
-Add the label, then re-run the CI workflow (or push): `plan` reads labels when it runs.
+Add the label, then push or use **Re-run all jobs**: `plan` reads labels when
+it runs, and re-running only the failed jobs reuses the earlier plan. Every
+later push runs the labelled lanes again until the label is removed.
 
 | Label | Adds |
 | --- | --- |
 | `ci:full` | Every lane except the OpenSecret EIF candidate |
-| `ci:package` | Unsigned Agent and Research desktop packages on every OS |
+| `ci:package` | Unsigned Agent and Research desktop packages on every OS, and the unsigned Research Dev app |
 | `ci:windows` | The Agent's Windows Clippy, native updater tests and full Windows suite |
 | `ci:ios`, `ci:android` | The Research iOS simulator or Android build |
 | `ci:research-dev-macos` | The unsigned Research Dev app |
@@ -75,9 +92,13 @@ Add the label, then re-run the CI workflow (or push): `plan` reads labels when i
 lane's command in its pinned Nix shell, exactly as `ci.yml` does. macOS lanes
 need macOS and use its selected Xcode (CI pins it with
 `scripts/ci/select-xcode.py`), Windows lanes need Windows with the toolchain
-from `.github/actions/setup-agent-windows`, `os-sdk-e2e` needs a local PostgreSQL
-and `os-eif` needs Linux on ARM64. Before pushing a workflow, CI-script or
-flake change, run `just lane repo` (every root flake check). The
+from `.github/actions/setup-agent-windows`, `os-sdk-e2e` needs PostgreSQL on
+`127.0.0.1:5432` with the credentials in `scripts/ci/opensecret-sdk-e2e.sh`,
+`os-helpers` needs Docker that builds `linux/arm64`, and `os-eif` needs Linux
+on ARM64 and `EIF_MODE=dev` or `prod`. Before pushing a workflow, CI-script,
+flake or documentation change, run `just lane repo` (every root flake check):
+docs select no lane, so a docs-only pull request does not run the check that
+docs name only existing workflows. The
 [pre-commit hook](repository-workflows.md#pre-commit-hook) runs the fast part
 of the lanes your staged files select.
 
@@ -102,8 +123,13 @@ of the lanes your staged files select.
 ## Rules
 
 - Never add `paths:` to `ci.yml`; `ci-ok` must report on every pull request.
-- Pull requests never save caches (one branch-scoped exception, outside
-  `ci.yml`, is listed under [caches](repository-workflows.md#caches)). Master
+- Without labels, every pull request reaches `ci-ok` well under 10 minutes. A lane slower
+  than about 8 minutes runs only by label, nightly, or as master's real
+  builds; check its warm duration before selecting it by path on pull
+  requests.
+- Pull requests never save an Actions cache (one branch-scoped exception,
+  outside `ci.yml`, is listed under [caches](repository-workflows.md#caches));
+  same-repository EIF candidates may push to FlakeHub. Master
   and nightly runs save lane caches into the store of the lane's own runner
   vendor: Blacksmith's, or GitHub's for the Agent lanes on GitHub's Windows
   image. A lane cache must match the lane's toolchain exactly; after a
@@ -131,15 +157,26 @@ variable when the lane is fixed.
 
 ## Runners
 
-Lanes use Blacksmith runners or GitHub-hosted runners; the runner
-constants are at the top of `scripts/ci/lanes.py`. During an outage, set the
-repository variable `CI_LINUX_RUNNER`, `CI_LINUX_HEAVY_RUNNER`,
-`CI_MACOS_RUNNER` or `CI_WINDOWS_RUNNER` to another label; no pull request is
-needed. `agent-package-windows`, which needs GitHub's image, and, for speed,
-`research-desktop-windows` run on the org's 16-core GitHub-hosted runner
-`maple-windows-2025-16core` (billed by the minute);
-`CI_WINDOWS_GITHUB_RUNNER=windows-2025` moves them back to the standard runner,
-which uses the same cache store. The native Windows test suites,
-`agent-windows-updater` and `agent-full-windows` (nightly, or by label), use
-the free standard `windows-2025`. A runner from the other vendor never
-saves a cache.
+The `Runner` constants at the top of `scripts/ci/lanes.py` assign every lane
+its runner; `plan.py lint` keeps `ci.yml`'s special jobs in step. Standard
+GitHub-hosted runners are free for this public repository; Blacksmith and the
+org's 16-core GitHub runner are billed by the minute.
+
+| Runner | Lanes | Why |
+| --- | --- | --- |
+| `blacksmith-8vcpu-ubuntu-2404`, `blacksmith-6vcpu-macos-26`, `blacksmith-8vcpu-windows-2025` | Most compiling lanes, for example Research Rust, OpenSecret Rust, every macOS lane and the Agent's Windows Clippy | Fast, with warm caches in Blacksmith's store |
+| `blacksmith-32vcpu-ubuntu-2404` | `agent-lint`, `agent-test` | The heaviest cold builds |
+| `ubuntu-latest`, `ubuntu-24.04-arm` | Lighter lanes, for example `repo`, SDK, proxy, Research web, services, `deps-*` and `os-pcr` | Free, and fast enough without Blacksmith |
+| `windows-2025` | `agent-windows-updater`, `agent-full-windows` | Blacksmith's Windows workspace inherits a foreign write ACE that the updater's storage validation rejects, and the reparse tests need the symlink privilege GitHub's runner grants |
+| `maple-windows-2025-16core` | `agent-package-windows` (its install smoke needs GitHub's image), `research-desktop-windows` (for speed) | Same image and cache store as `windows-2025`, with more cores |
+| `blacksmith-16vcpu-ubuntu-2404-arm` | `os-eif` | The release EIF builder's class ([contracts](repository-workflows.md#contracts)) |
+
+During an outage or a queue burst, set the repository variable
+`CI_LINUX_RUNNER`, `CI_LINUX_HEAVY_RUNNER`, `CI_MACOS_RUNNER`,
+`CI_WINDOWS_RUNNER` or `CI_WINDOWS_GITHUB_RUNNER` to another label; no pull
+request is needed, and it applies when `plan` next runs (**Re-run all jobs**).
+`CI_WINDOWS_GITHUB_RUNNER=windows-2025` moves the 16-core lanes to the
+standard runner, which uses the same cache store. A runner from the other
+vendor never saves a cache. The EIF builder, `os-helpers` and the free
+Windows suites have no override. Runners of the signed and release workflows
+are in [repository workflows](repository-workflows.md#runners-and-toolchains).
diff --git a/docs/development-environments.md b/docs/development-environments.md
index 5aea989a0..21b5a0b8f 100644
--- a/docs/development-environments.md
+++ b/docs/development-environments.md
@@ -1,7 +1,7 @@
 # Development environments and authentication
 
 Choose the environment for the task before setup, implementation, or smoke
-testing. Keep the chosen lane through API, client/project ID, auth origin,
+testing. Keep the chosen environment through API, client/project ID, auth origin,
 account, billing/flags, and runtime configuration.
 
 | Environment | Use | Required setup/evidence |
diff --git a/docs/ios-dev-testflight.md b/docs/ios-dev-testflight.md
index afb4cba9e..991a0baac 100644
--- a/docs/ios-dev-testflight.md
+++ b/docs/ios-dev-testflight.md
@@ -74,7 +74,7 @@ and retain hosted-flow-before-native-build ordering for future handoff changes.
 `master` always builds. Other branches, forks, pull requests, tags, and GitHub
 Releases cannot enter this workflow's signing or upload jobs. The independent production
 `mobile-build.yml` keeps its change selection,
-artifact names, and TestFlight destination. Its own serial lane also supports
+artifact names, and TestFlight destination. Its own serial queue also supports
 a master-only manual dispatch to force a fresh production build.
 
 The development workflow calls the shared `scripts/ci/ios-release.sh` with
diff --git a/docs/opensecret-import.md b/docs/opensecret-import.md
index 31931459c..49429af8d 100644
--- a/docs/opensecret-import.md
+++ b/docs/opensecret-import.md
@@ -51,23 +51,19 @@ a disposable database; it no longer fetches an external backend revision.
 This advances that lane from the former pinned commit
 `d26eb6bd54d50cc8e6b2967f647a94c61da913da` to the imported source.
 
-PR jobs have read-only repository contents permission and use hosted runners,
-without signing/deployment credentials. Ordinary backend CI has no EIF
-publisher or deployment step. Signed-PCR validation is the lightweight
-monorepo-root `pcr-compatibility` Nix check (the `os-pcr` lane, when PCR tooling
-or approvals change) and the manual publication procedure, not a standalone
-backend dev-shell job. A separate
-ARM64 EIF workflow compares dev/prod measurements on PRs explicitly editing
-approved PCR JSON, relevant backend/TEE or approval changes to master, and manual runs.
+PR jobs have read-only repository contents permission, without
+signing/deployment credentials. Ordinary backend CI has no EIF publisher or
+deployment step. Signed-PCR validation is the lightweight monorepo-root
+`pcr-compatibility` Nix check (the `os-pcr` lane, when PCR tooling or
+approvals change) and the manual publication procedure. The `os-eif` lane
+builds dev/prod EIF candidates for same-repository PRs to `master`, and
+`opensecret-eif.yml` compares measurements against the approved PCRs.
 Ordinary backend PRs do not fail merely because approvals have not been
-updated. A master mismatch is reported as pending approval (a notice with the
-built PCRs), not a failure.
-Master and same-repository PR EIF checks receive OIDC for FlakeHub Cache and
-also populate GitHub's branch-scoped Nix cache. Fork PRs and non-master manual
-runs have no OIDC and use only GitHub caching; master runs warm the
-default-branch cache for forks. Legacy cross-organization cache access does not
-transfer automatically; follow the
-[cache validation policy](../services/opensecret/docs/nitro-deploy.md#binary-caches-and-cold-run-validation).
+updated; a master mismatch is a pending-approval notice, not a failure.
+[CI approval checks](../services/opensecret/docs/nitro-deploy.md#ci-approval-checks)
+and the [cache policy](../services/opensecret/docs/nitro-deploy.md#binary-caches-and-cold-run-validation)
+own the details, including which jobs receive OIDC for FlakeHub. Legacy
+cross-organization cache access does not transfer automatically.
 Backend-only changes do not select Research or Agent application packaging.
 
 An external workspace manager may own local backend selection, generated
diff --git a/docs/pages-deployments.md b/docs/pages-deployments.md
index 0ba1d7e3b..5649b1860 100644
--- a/docs/pages-deployments.md
+++ b/docs/pages-deployments.md
@@ -156,7 +156,7 @@ Offline checks from the repository root (use the host system for a local check):
 
 ```bash
 nix build --no-update-lock-file --no-link --print-build-logs .#checks.x86_64-linux.pages
-nix flake check --no-update-lock-file
+just lane repo
 MAPLE_WEB_ENVIRONMENT=pr nix develop --no-update-lock-file .#ci -c ./scripts/ci/web.sh
 ```
 
@@ -171,7 +171,7 @@ maintained and tested within Auth. Research retains its built-in web auth,
 existing SDK pin, and native entry URLs. Neither an Auth change nor an Auth
 publication requires a Research release.
 
-| Lane | Source and configuration | Result |
+| Workflow | Source and configuration | Result |
 | --- | --- | --- |
 | `Auth Pages CI` | PRs targeting any base, including forks and stacked branches; relevant master pushes; optional master dispatch; `dev` profile | Standalone Auth checks/build; internal PR and master runs produce `maple-auth-development-RUN-ATTEMPT` with manifest profile `auth-dev` |
 | `Auth Pages build` | Manual dispatch on protected `master`; `release` profile | `maple-auth-production-RUN-ATTEMPT` artifact with manifest profile `auth-release` |
@@ -179,8 +179,9 @@ publication requires a Research release.
 | `Publish Auth Dev Pages` — stable | Automatically follows successful master `Auth Pages CI`; optional manual recovery selecting run/attempt | `maple-auth-dev` / `maple-auth-dev.pages.dev`, ref and environment `auth-pages-development`, public URL `https://auth-dev.maple.ai` |
 | `Publish Auth Dev Pages` — PR | Automatically follows a successful current internal PR head, including stacked PRs | `pr-N` preview on `maple-auth-dev`, a distinct Auth deployment status and PR comment; does not advance either Auth production ref |
 
-The Dev producer reuses the existing Auth CI job rather than running a second
-test/build lane. Push and PR path filters cover Auth source, its build scripts,
+The Dev producer is `Auth Pages CI` itself: its job runs `auth-ci.sh` and
+builds the artifact. On pull requests, `ci.yml`'s `auth` lane runs the same
+`auth-ci.sh` for `ci-ok`, so the checks run twice by design. Push and PR path filters cover Auth source, its build scripts,
 the artifact tooling and shared Nix inputs; a newer PR head cancels an older
 build. The Pages and publisher tests run in `ci.yml`'s `repo` lane. Unrelated application changes
 alone do not trigger it. PR checkout and manifest use the exact PR head SHA,
diff --git a/docs/repository-workflows.md b/docs/repository-workflows.md
index 747b3f437..e2f285d47 100644
--- a/docs/repository-workflows.md
+++ b/docs/repository-workflows.md
@@ -3,8 +3,9 @@
 Read this reference when changing hooks, workflows, caches, runners or
 publication configuration. [CI](ci.md) explains the pull-request checks: the
 single required check `ci-ok`, the tiers, labels, the lane table in
-`scripts/ci/lanes.py`, running a lane locally and adding one. Commands and
-paths are relative to the monorepo root.
+`scripts/ci/lanes.py`, lane runners, running a lane locally and adding one.
+Agents load [`$change-maple-ci`](../.agents/skills/change-maple-ci/SKILL.md).
+Commands and paths are relative to the monorepo root.
 
 ## Pre-commit hook
 
@@ -24,17 +25,20 @@ Research Rust runs formatting and tests, without Clippy; repository changes
 run actionlint on staged workflows and the `scripts/ci` tests. Integration
 suites, cargo-deny, `nix flake check` and packaging stay in CI.
 `MAPLE_HOOK_FULL=1` runs slower variants where they exist, `MAPLE_HOOK_ONLY=a,b`
-restricts the components, and `MAPLE_HOOK_SKIP=1` or `git commit --no-verify`
-skips the hook. `scripts/ci/test_plan.py` keeps the hook's components and its
+restricts the components, `MAPLE_HOOK_NO_NIX=1` runs from `PATH` even with
+Nix installed, and `MAPLE_HOOK_SKIP=1` or `git commit --no-verify` skips the
+hook. `scripts/ci/test_plan.py` keeps the hook's components and its
 branches in step with the lane table.
 
 ## Caches
 
-- Pull requests restore caches and never save one. The one exception is
-  `opensecret-eif.yml`'s `eif` job (fork PRs that edit PCR approvals, and
+- Pull requests restore Actions caches and never save one. The one exception
+  is `opensecret-eif.yml`'s `eif` job (fork PRs that edit PCR approvals, and
   manual runs outside `master`): without FlakeHub credentials, its Nix store
   goes to the run's branch-scoped Actions cache, which `master` and other
-  pull requests cannot read.
+  pull requests cannot read. Same-repository PR EIF builds (`ci.yml`'s
+  `os-eif` and `opensecret-eif.yml`'s `eif-trusted`) push to the FlakeHub Nix
+  cache by design ([cache policy](../services/opensecret/docs/nitro-deploy.md#binary-caches-and-cold-run-validation)).
 - Lane caches (`Swatinem/rust-cache`, prefix `ci-v2`) are keyed by lane and
   toolchain pins (the workspace's `flake.lock`, and OpenSecret's
   `rust-toolchain.toml`), which must match exactly, then by rust-cache's
@@ -113,13 +117,23 @@ the other side of each contract. A failure means the workflow change is wrong:
 4. The signed master builds write the release cache keys above, and
    `ios-dev-testflight.yml`'s run number is the Maple Dev build number: never
    rename that file.
-5. OpenSecret EIF builds use the release builder's runner class, and only the
-   listed jobs receive `id-token: write` or use FlakeHub. An EIF approval
+5. Every OpenSecret EIF builder that uses FlakeHub (`ci.yml`'s `os-eif`,
+   `opensecret-eif.yml`'s `eif-trusted` and the release build) runs on the
+   release builder's runner class, and only the listed jobs receive
+   `id-token: write` or use FlakeHub. The unprivileged fork job stays on
+   `ubuntu-24.04-arm`. An EIF approval
    mismatch fails only where that environment's approval files are edited
    (or a manual run outside `master`); on master it is a notice.
 6. Each protected environment has a fixed set of consumer jobs;
    `windows-signing` runs only on GitHub-hosted runners.
-7. Docs, guides and READMEs name only workflows that exist.
+7. Docs, guides and READMEs name only workflows that exist. Docs select no
+   lane, so this runs with the `repo` lane and nightly; run `just lane repo`
+   after editing docs.
+
+The Pages and Auth publishers also trust their producers
+(`pages-preview-build.yml`, `pages-production-build.yml`,
+`auth-pages-ci.yml`, `auth-pages-build.yml`) by file, artifact name and
+gates; `test_pages_workflows.py` and `test_pages_auth_workflows.py` pin them.
 
 `scripts/ci/test_workflow_policy.py` holds the rules every workflow keeps: no
 `pull_request_target`, and a fixed set of workflows that run on pull requests;
@@ -164,18 +178,12 @@ merging source.
 
 ## Agent Windows updater checks
 
-The `agent-windows-updater` lane runs `cargo test -p maple-agent-updater
---locked --no-fail-fast -- --test-threads=1` on GitHub's free Windows image:
-the updater's native filesystem, Authenticode-rejection, transaction and
-recovery tests, and the bootstrap integration test, which compiles the app's
-`windows_bootstrap.rs`. It runs when a pull request or master push changes
-the updater crate, that file, the Agent workspace's `Cargo.lock` or
-`Cargo.toml`, the Windows toolchain or CI itself, with `ci:windows` or
-`ci:full`, and nightly; master runs save its cache. Like every `windows`
-matrix lane it has no signing credential or protected environment. The
-reparse tests need the symlink privilege GitHub's runner grants. A pass
-qualifies no official signature, signed installed
-upgrade, visible GUI or paired remote upgrade.
+The `agent-windows-updater` lane (see `scripts/ci/lanes.py` for what selects
+it) runs the updater's native filesystem, Authenticode-rejection, transaction
+and recovery tests and the bootstrap integration test on GitHub's Windows
+image. Like every `windows` matrix lane it has no signing credential or
+protected environment. A pass qualifies no official signature, signed
+installed upgrade, visible GUI or paired remote upgrade.
 
 The manual `agent-windows-signature-probe.yml` takes an exact historical
 producer run, attempt and source and the artifact's ZIP and PE digests. It
@@ -225,28 +233,30 @@ caps Bash heredoc pipes at 512 bytes, and larger bodies use a temporary file.
 
 ## Runners and toolchains
 
-Compilation runs on Blacksmith runners (ARM64 `blacksmith-6vcpu-macos-26` for
-macOS); lane runners are the constants in `scripts/ci/lanes.py`. The signed
-Research macOS, Linux, Android and iOS builds compile and sign on Blacksmith.
-Artifact verifiers, TestFlight submission, and the Agent's signing and
-attestation use GitHub-hosted runners. Windows builds that compile run on the
-org's 16-core GitHub-hosted runner `maple-windows-2025-16core`: the release's
-`build-windows`, the Agent packaging rehearsal and the Research Windows PR
-package ([CI runners](ci.md#runners)). The unsigned Agent master build compiles
-on `blacksmith-8vcpu-windows-2025`: its fat-LTO link runs on one thread, so 16
-cores are no faster. The signed Research master build and the Agent's native
-suites (`agent-windows-updater`, and `agent-full-windows` nightly or by label)
-use GitHub's free standard `windows-2025`, like the short signing and verify
-jobs. Jobs that compile and
-sign install the pinned Artifact Signing module before compiling, so a failed
-module download fails early; the module's own NuGet packages and the Azure
-login still come after the compile. The installer retries the PowerShell
-Gallery and its CDN and accepts only the pinned SHA-256. Rust, MSVC, Perl and
-the linker are pinned by `.github/actions/setup-agent-windows` for the Agent.
-Blacksmith's Windows workspace inherits a foreign write ACE that the updater's
-storage validation rejects, so the updater tests and install smokes stay on
-GitHub's image; `blacksmith-8vcpu-windows-2025` runs the Agent Windows Clippy
-lane and the unsigned Agent master build.
+[CI runners](ci.md#runners) assigns the `ci.yml` lanes. The signed and
+release workflows use:
+
+| Work | Runner |
+| --- | --- |
+| Research macOS, Linux, Android and iOS builds, which compile and sign (master and release); `rust-tests.yml`; the Agent's unsigned master builds | Blacksmith (`blacksmith-6vcpu-macos-26`, `blacksmith-8vcpu-ubuntu-2404`, `blacksmith-8vcpu-windows-2025`) |
+| Release `build-windows` | `maple-windows-2025-16core` |
+| Signed Research Windows master build; Agent Windows signing and verification | `windows-2025` |
+| Artifact verifiers, TestFlight submission, the Agent's signing and attestation, CodeQL, web and frontend evidence, proxy release rehearsal | Other GitHub-hosted runners |
+| EIF builders that use FlakeHub | `blacksmith-16vcpu-ubuntu-2404-arm` |
+
+The Agent's signing and attestation, `windows-signing` jobs and every artifact
+verifier stay GitHub-hosted: the Agent publisher rejects self-hosted signers,
+Blacksmith counts as self-hosted, and verifiers run fresh. The Agent's
+unsigned master Windows build compiles on Blacksmith because its fat-LTO link
+runs on one thread, so 16 cores are no faster. Blacksmith's Windows workspace
+inherits a foreign write ACE that the updater's storage validation rejects,
+so the updater tests and install smokes stay on GitHub's image. Jobs that
+compile and sign install the pinned Artifact Signing module before compiling,
+so a failed module download fails early; the module's own NuGet packages and
+the Azure login still come after the compile. The installer retries the
+PowerShell Gallery and its CDN and accepts only the pinned SHA-256. Rust,
+MSVC, Perl and the linker are pinned by `.github/actions/setup-agent-windows`
+for the Agent.
 
 Research desktop and iOS builds select Xcode 26.5 (`17F42`) from
 [`scripts/ci/apple-toolchain.json`](../scripts/ci/apple-toolchain.json) through
diff --git a/proxy/README.md b/proxy/README.md
index 06293a04d..069a2f5f1 100644
--- a/proxy/README.md
+++ b/proxy/README.md
@@ -587,9 +587,12 @@ environment:
 ### Docker Images & CI/CD
 
 The source lives under [`proxy/`](https://github.com/MaplePrivacyLabs/Maple/tree/master/proxy)
-in the Maple repository. The root `ci.yml` workflow runs locked Rust checks,
-supply-chain policy, and non-publishing container builds for proxy changes
-(lanes `proxy`, `deps-proxy`, `proxy-container` and, on `master`,
+in the Maple repository. The root `ci.yml` workflow runs locked Rust checks
+for proxy changes (lane `proxy`), supply-chain policy when the proxy's
+manifest, lockfile or `deny.toml` changes (`deps-proxy`), and non-publishing
+container builds: on pull requests only when `proxy/Dockerfile` or
+`.dockerignore` changes (`proxy-container`), and on `master` for both
+architectures whenever container inputs change (`proxy-container`,
 `proxy-container-arm64`). After every successful stable Maple Release, a separate serialized
 publisher compares the checked-in proxy version with the previous stable Maple
 Release and rejects changed container inputs without a version bump. Version
diff --git a/services/opensecret/docs/nitro-deploy.md b/services/opensecret/docs/nitro-deploy.md
index 4cae64e90..7eebe5c24 100644
--- a/services/opensecret/docs/nitro-deploy.md
+++ b/services/opensecret/docs/nitro-deploy.md
@@ -75,8 +75,8 @@ artifact's `pcr.json`; the deployment verifier rejects anything else.
 ## CI approval checks
 
 The root `ci.yml` `os-eif` lane builds dev/prod EIF candidates on Linux ARM64
-for same-repository PRs that change measured inputs without editing PCR
-approvals. The candidate job explicitly realizes and inspects the exact user
+for same-repository PRs to `master` that change measured inputs (or carry the
+`ci:eif` label) without editing PCR approvals. The candidate job explicitly realizes and inspects the exact user
 initramfs passed to the EIF builder, including when the final EIF comes from cache,
 resolves its entrypoint's CA path, and reports the archived bundle's hash and
 affected-root check alongside the EIF hash and PCRs. The archived CA bytes

From 338af42e71ccc0db2954dd5c5a8589a0092db6e9 Mon Sep 17 00:00:00 2001
From: Anthony Ronning <101225832+AnthonyRonning@users.noreply.github.com>
Date: Wed, 28 Oct 2026 07:30:03 +0000
Subject: [PATCH 3/3] docs: fix CI skill and docs after review

Keep the docs PR free of build inputs: restore the store-bench and Research
Windows resource READMEs, and the Auth and Research command lines that were
already correct, so merging starts no signed build or Auth deployment.

Skill: typical PR selections, both pr_paths=() and gate=False for slow
lanes, re-run and auto-merge mechanics, failover runners, the
agent-desktop-build dispatch command, hook wiring for existing components,
the merge-base push preview, narrower runner, cache and evidence claims, and
no stale flake rows. Docs: os-eif reports approval need, explain applies the
approval-edit rule, PR cache exceptions, proxy and Rust SDK routing, the
Research Dev re-run advice, and develop-maple routes to change-maple-ci.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .agents/skills/change-maple-ci/SKILL.md       | 268 +++++++++---------
 .../change-maple-ci/references/changing-ci.md | 119 ++++----
 .../change-maple-ci/references/debugging.md   |  54 ++--
 .../change-maple-ci/references/design.md      | 129 +++++----
 .agents/skills/develop-maple/SKILL.md         |   1 +
 .../review-opensecret-security/SKILL.md       |  38 +--
 .../validate-opensecret/references/checks.md  |  23 +-
 AGENTS.md                                     |   8 +-
 apps/maple-agent/README.md                    |  16 +-
 apps/maple-agent/crates/store-bench/README.md |   9 +-
 apps/maple-agent/docs/desktop-builds.md       |  13 +-
 apps/maple-auth/AGENTS.md                     |   2 +-
 apps/maple-research/README.md                 |   4 +-
 .../docs/development-contracts.md             |  11 +-
 .../docs/research-dev-desktop.md              |  18 +-
 .../src-tauri/resources/windows/README.md     |  11 +-
 docs/app-signing-environments.md              |  10 +-
 docs/ci.md                                    |  53 ++--
 docs/pages-deployments.md                     |  13 +-
 docs/repository-workflows.md                  |  17 +-
 proxy/README.md                               |  10 +-
 services/opensecret/docs/nitro-deploy.md      |   3 +-
 22 files changed, 455 insertions(+), 375 deletions(-)

diff --git a/.agents/skills/change-maple-ci/SKILL.md b/.agents/skills/change-maple-ci/SKILL.md
index a5d7c264b..1b5b34a10 100644
--- a/.agents/skills/change-maple-ci/SKILL.md
+++ b/.agents/skills/change-maple-ci/SKILL.md
@@ -1,12 +1,12 @@
 ---
 name: change-maple-ci
-description: Change, trigger, or debug Maple's GitHub Actions CI. Covers the ci.yml lane planner (scripts/ci/plan.py, scripts/ci/lanes.py), the one required check ci-ok, ci:* labels (ci:full, ci:package, ci:windows, ci:ios, ci:android, ci:research-dev-macos, ci:eif), re-runs, ci.yml dispatch, nightly runs, runners and override variables, caches, timeouts, the pre-commit hook, guard and contract tests, and red or slow runs. Use it to add or change a lane or workflow, to get Windows, packaging, iOS, Android or EIF evidence on a PR, to decide what runs on a PR and what on master, or to explain why a check ran, did not run, or failed. Use release-maple for releases, signing and publication.
+description: Change, trigger or debug Maple's GitHub Actions CI - the ci.yml lane planner (scripts/ci/plan.py, lanes.py), the required ci-ok check, ci:* labels, re-runs, runners, caches, the hook and guard tests. Use it to add or change a lane or workflow, to get platform, packaging or EIF evidence on a PR, or to explain why a check ran, did not run, failed or was slow. Releases and signing belong to release-maple.
 ---
 
 # Change Maple CI
 
 Load this skill before you edit `.github/`, `scripts/ci/`, `.githooks/` or
-the root flake checks, or when you need a CI result a PR does not get by
+the root flake checks, or when a PR needs a CI result it does not get by
 default. [CI](../../../docs/ci.md) is the human reference;
 [repository workflows](../../../docs/repository-workflows.md) owns caches,
 contracts and the signed builds. Code beats any list here:
@@ -20,49 +20,50 @@ python3 scripts/ci/plan.py explain --base origin/master --head HEAD
 ## Hard rules
 
 1. **Keep every PR's `ci-ok` well under 10 minutes.** Path-select a lane on
-   pull requests only if its warm runs finish in about 8 minutes. Slower work
-   runs by label, nightly, or as master's real builds. Why: the team ships
-   many small PRs, and slow lanes crept back in one path selector at a time.
-2. **Keep master deployable.** Merge only with `ci-ok` green. When master goes
+   PRs only if its warm runs take about 8 minutes or less; slower work runs by
+   label, nightly, or as master's real builds. `research-ios`,
+   `research-android` and `os-eif` are owner-accepted exceptions, the only PR
+   proof for their inputs. Why: slow lanes crept back one selector at a time.
+2. **Keep master deployable.** Merge only with `ci-ok` green; when master goes
    red, fix forward or revert first. Why: master pushes start signed builds
    and feed the next release.
-3. **Add checks only as lanes in `scripts/ci/lanes.py`, each with a
-   `scripts/ci/test_plan.py` case.** Never add `paths:` to `ci.yml`, a new
-   workflow that runs on pull requests, another required check, or a bespoke
-   guard script. Why: one table drives CI, the pre-commit hook and
+3. **Add checks only as lanes in `lanes.py`, each with a `test_plan.py`
+   case.** Never add `paths:` to `ci.yml`, a new PR workflow, another required
+   check, or a bespoke guard script. Why: one table drives CI, the hook and
    `just lane`, and `ci-ok` must report on every PR.
-4. **Never put `[skip ci]`, `[ci skip]` or similar in a commit message or PR
-   title.** Why: master plans each push from the previous commit, so a
-   skipped commit is never checked.
-5. **Pull requests never save an Actions cache, and master runs are never
-   cancelled.** Why: a PR can rewrite its own YAML, so its caches are
-   untrusted, and a cancelled master commit is never verified.
-6. **A lane saves caches only into its own runner vendor's store. `ci.yml`
-   never writes a key that a release restores.** Why: Blacksmith and GitHub
-   cannot read each other's caches, and releases restore their keys by prefix.
+4. **Never put `[skip ci]` or similar in a commit message or PR title.** Why:
+   master plans each push from the previous commit, so a skipped commit is
+   never checked.
+5. **Lanes never save a cache on a PR, and master runs are never
+   cancelled.** Why: a PR can rewrite its own YAML, and a cancelled master
+   commit is never verified. The EIF jobs' branch-scoped exceptions are in
+   [design](references/design.md#pull-requests-never-save-caches).
+6. **A lane saves only into its own runner vendor's cache store, and `ci.yml`
+   never writes a key a release restores.** Why: Blacksmith and GitHub cannot
+   read each other's caches, and releases restore their keys by prefix.
 7. **A failing `test_contracts.py` or `test_workflow_policy.py` means your
-   change is wrong.** Never edit `release.yml`, a publisher, a signing
-   environment, PCR approvals or OpenSecret approval gating to make a check
-   pass. Why: releases, update feeds and EIF approvals trust those seams.
+   change is wrong.** Never edit release or publisher workflows,
+   `ci_evidence.py`, signing environments, `pcr*.json`,
+   `opensecret_change_detection.py` or the tests' allowlists to pass. Why:
+   releases, update feeds and EIF approvals trust those seams.
 8. **Never rename `agent-desktop-build.yml`, `ios-dev-testflight.yml`, or a
-   workflow, job or artifact that a publisher or the release preflight looks
-   up.** Why: run numbers are build numbers, and consumers find producers by
-   name.
-9. **Never push to `master`, and never dispatch or re-run a signing or
-   publishing workflow, to try a CI change.** Why: a master push can sign
-   builds and upload to TestFlight. Re-running or dispatching `ci.yml` is fine.
-10. **Keep fat LTO for Agent release builds, and do not propose thin LTO.**
-    Why: the owner chose smaller downloads over a faster master build.
-11. **Treat OpenSecret CI as reproducible TEE infrastructure.** Keep every EIF
-    builder that writes FlakeHub on one runner class. Keep `os-eif` to
-    same-repository PRs to `master`. Never give OIDC or FlakeHub to a new job.
-    Why: PCR reproducibility depends on identical, trusted builders.
-12. **Test behaviour, or a contract another file consumes. Never test a
-    workflow's or script's text, and never hand-copy lists of names.** Why:
-    text tests break on harmless edits and catch nothing.
-13. **Do not add process.** Add no approval steps, required checks or safety
-    switches unless the owner asks. Why: a team of four wants fast
-    iteration, and master's push run plus fixing forward is the backstop.
+   workflow, job or artifact a publisher or the release preflight looks up.**
+   Why: run numbers are build numbers; consumers find producers by name.
+9. **Never push to `master`, or dispatch or re-run a signing or publishing
+   workflow, to try a CI change.** Why: a master push can sign builds and
+   upload to TestFlight. Re-running `ci.yml` is fine.
+10. **Keep fat LTO for Agent release builds; do not propose thin LTO.** Why:
+    the owner chose smaller downloads over a faster master build.
+11. **Treat OpenSecret CI as reproducible TEE infrastructure.** Keep every
+    FlakeHub EIF builder on one runner class, `os-eif` on same-repository PRs
+    to `master`, and OIDC and FlakeHub away from new jobs. Why: PCR
+    reproducibility depends on identical, trusted builders.
+12. **Test behaviour, or a contract another file consumes.** Assert parsed
+    structure and evaluated conditions; never grep prose or comments, and
+    never hand-copy lists of names. Why: text tests break on harmless edits.
+13. **Do not add process:** no approval steps, required checks or safety
+    switches unless the owner asks. Why: a small team wants fast iteration,
+    and master's push run plus fixing forward is the backstop.
 
 The reasons in full are in [design](references/design.md).
 
@@ -70,14 +71,14 @@ The reasons in full are in [design](references/design.md).
 
 Every `ci.yml` run has three stages:
 
-1. **`plan`** runs `plan.py github`. It diffs the change, matches each path
-   against `lanes.py`, and adds lanes for the PR's labels. Its job summary
-   lists each selected lane with its reason.
-2. **Lanes** run in the generic `nix` and `windows` matrix jobs. A lane that
-   needs services, OIDC, artifacts or another workflow's cache gets a special
-   job named after it. Every lane runs `plan.py run <id>`.
-3. **`ci-ok`** runs `plan.py verdict`. It passes when every selected lane
-   succeeded and nothing unselected failed. It is the only required check.
+1. **`plan`** (`plan.py github`) diffs the change, matches each path against
+   `lanes.py`, adds lanes for the PR's labels, and lists each with its reason
+   in the job summary.
+2. **Lanes** run in the generic `nix` and `windows` matrices through
+   `plan.py run <id>`. A lane that needs services, OIDC, artifacts or another
+   workflow's cache gets a special job named after it.
+3. **`ci-ok`** (`plan.py verdict`), the only required check, passes when every
+   selected lane succeeded and nothing unselected failed.
 
 Selection rules:
 
@@ -89,16 +90,31 @@ Selection rules:
 - A path that no lane owns selects every lane, label-only builds included. So
   does a diff the planner cannot compute (a new branch or a force-push).
 - Editing `ci.yml`, `.github/actions/**`, `plan.py` or `lanes.py` selects
-  every gate lane. It never selects the slow `gate=False` lanes.
+  every gate lane, whatever its `pr_paths`. It never selects `gate=False`
+  lanes.
 - A selection error fails a PR's `plan`; master, nightly and dispatch runs
   select every lane instead.
 
+Typical PR selections (confirm with `explain`):
+
+| Change | Lanes |
+| --- | --- |
+| Agent source | `agent-lint`, `agent-test` (Linux), `agent-macos`, `agent-windows` (Clippy). Warm `ci-ok` in about 5 minutes; `agent-windows` is the long pole |
+| Agent `Cargo.lock` or `Cargo.toml` | Those four, plus `agent-windows-updater`, `agent-supply-chain`, `agent-provider` |
+| Agent packaging or installer scripts | Only the four; packaging needs `ci:package` |
+| Research frontend; Research `src-tauri` | `research-web`; `research-rust` |
+| TypeScript SDK | `sdk-ts`, `os-sdk-e2e` |
+| Rust SDK source | The four Agent lanes, `sdk-rust`, `proxy`, `research-rust`, `os-sdk-e2e` |
+| OpenSecret source | `os-rust`, `os-sdk-e2e`, `os-flake-check`, and `os-eif` on a candidate PR |
+| `ci.yml`, `plan.py`, `lanes.py`, `.github/actions/**` | Every gate lane |
+| Root or component docs, `.agents/**` | Nothing |
+
 | Trigger | What runs |
 | --- | --- |
-| Pull request (any base) | Lanes selected by paths and labels. A new push cancels the superseded run. `opensecret-eif.yml`, `pages-preview-build.yml`, `auth-pages-ci.yml` and `proxy-rust.yml` may also run on matching paths. They are advisory, not required. |
+| Pull request | Lanes selected by paths and labels. A new push cancels the superseded run. A few advisory workflows also run on matching paths ([CI](../../../docs/ci.md)); they are not part of `ci-ok`. |
 | Merge | Auto-merge is on. There is no merge queue and no up-to-date rule (`ci.yml` already handles `merge_group` if a queue is ever enabled). The master push run catches semantic conflicts. |
-| Master push | `ci.yml` runs the push lanes, adding the full Agent Linux and macOS suites for Agent changes. The Research and Auth PR lanes do not run here; their master workflows cover them. The run is never cancelled and saves caches. Also: signed builds (Agent: Prod only), release-evidence workflows and CodeQL. |
-| Nightly (UTC) | 04:17 `ci.yml` nightly lanes: full Windows suite, packaging rehearsals, `deps-*` advisories, cache refresh. 05:28 CodeQL. 05:47 `nightly.yml`: Bun audits, the SQLCipher provider suite on three OSes, and the single `ci-nightly` issue. 10:37 Agent Dev desktop builds, which the issue does not cover. |
+| Master push | `ci.yml` runs the push lanes, adding `agent-full-linux` and `agent-full-macos` for Agent changes. The Research and Auth PR lanes do not run here; their master workflows cover them. The run is never cancelled and saves caches. Also: signed builds (Agent: Prod only), release-evidence workflows and CodeQL. |
+| Nightly (UTC) | 04:17 `ci.yml` nightly lanes: `agent-full-*`, packaging rehearsals, `deps-*` advisories, cache refresh. 05:28 CodeQL. 05:47 `nightly.yml`: Bun audits, the SQLCipher provider suite on three OSes, and the single `ci-nightly` issue. 10:37 Agent Dev desktop builds, which the issue does not cover. |
 | Dispatch | `ci.yml` with lane ids ([below](#dispatch-ciyml)). |
 
 ## Trigger what you need
@@ -110,21 +126,21 @@ fields in `lanes.py` are authoritative.
 
 | Label | Adds | Use when |
 | --- | --- | --- |
-| `ci:windows` | Agent Windows Clippy (already on every Agent PR), the native updater tests, the full Windows suite | Path, filesystem, process or terminal code behaves differently on Windows |
+| `ci:windows` | The native updater tests and the full Windows suite (Windows Clippy already runs on every Agent PR) | Path, filesystem, process or terminal code behaves differently on Windows |
 | `ci:package` | Unsigned Agent packages and Research desktop bundles on all three OSes, plus the Research Dev macOS app | Packaging or release scripts, flakes, toolchains, or bundled assets, entitlements or updater metadata change |
 | `ci:ios`, `ci:android` | The Research iOS simulator or Android build | Research changes reach native mobile code or mobile-only plugins that their paths do not select |
 | `ci:research-dev-macos` | The unsigned Research Dev app | Research Dev OAuth profile work |
 | `ci:eif` | Dev and prod OpenSecret EIF candidates (`os-eif`) | The selector misses a measured input. Works only on a same-repository PR to `master` that edits no PCR approval |
-| `ci:full` | Every PR lane except `os-eif` | Toolchain, lockfile-wide or risky cross-cutting changes before merge |
+| `ci:full` | Every PR lane except `os-eif`, the full Agent suites included | Toolchain, lockfile-wide or risky cross-cutting changes before merge |
 
-- Adding a label starts nothing. Push, or use **Re-run all jobs**: `plan`
-  reads labels when it runs.
-- **Re-run failed jobs** reuses the earlier `plan`, with its old lanes,
-  labels and quarantine.
-- Labelled builds can take 15 to 90 minutes, and every push re-runs them while
-  the label stays. Remove it once you have the evidence.
-- Labels act only on `pull_request` runs. iOS, Android and EIF builds are
-  also path-selected by their native or measured inputs.
+- Adding a label starts nothing: `plan` reads labels when it runs. Push, or
+  use **Re-run all jobs**, which GitHub offers only on a finished run: cancel
+  a running PR run first. With auto-merge on, a run planned before the label
+  can still pass `ci-ok` and merge the PR without the labelled lanes.
+- **Re-run failed jobs** reuses the earlier `plan`: old lanes, labels and
+  quarantine.
+- Labelled builds take well over 10 minutes, and every push re-runs them
+  while the label stays. Remove it once you have the evidence.
 
 ### Dispatch `ci.yml`
 
@@ -132,21 +148,23 @@ fields in `lanes.py` are authoritative.
 gh workflow run ci.yml --ref <branch> -f lanes=agent-full-windows,deps-sdk
 ```
 
-- `lanes` takes comma-separated ids. `all`, the default, runs every lane
-  active for dispatch.
-- `os-eif` cannot be dispatched. Any id that is not a dispatch lane, a typo
-  included, does not fail: the plan falls back to every dispatch lane,
-  packaging builds included. Check ids in `lanes.py` first.
-- Dispatch runs never save caches, so they warm nothing. Never use one to
-  satisfy a PR's `ci-ok`; use labels.
+- `lanes` takes comma-separated ids; `all` (the default) runs every dispatch
+  lane. So does any id that is not a dispatch lane, a typo or `os-eif`
+  included: the plan falls back instead of failing. Check ids in `lanes.py`.
+- Dispatch runs never save caches. Their `ci-ok` lands on the branch's head
+  commit and may count as an open PR's required check, so never dispatch on
+  a branch with an open PR; use labels.
 
 ### Master-only builds
 
 Signed builds never run on PRs; never push to `master` to get one.
 `agent-desktop-build.yml` builds Agent Prod packages on pushes that change
-Agent inputs (`plan.py only agent-desktop`) and Dev packages nightly; a
-dispatch signs both. Research signed builds follow
-`scripts/ci/change_detection.py`. These belong to the release process
+Agent inputs (`plan.py only agent-desktop`) and Dev packages nightly. For Dev
+packages, download the newest nightly run's `maple-agent-dev-*` artifacts
+(kept 30 days). With the owner's go,
+`gh workflow run agent-desktop-build.yml --ref master` builds and signs Dev
+and Prod now, and its Prod packages are publishable. Research signed builds
+follow `scripts/ci/change_detection.py`. These belong to the release process
 ([boundary](#production-boundary)).
 
 ## Change CI
@@ -155,8 +173,7 @@ dispatch signs both. Research signed builds follow
 jobs, runners, caches and guard tests. In short:
 
 1. Edit one `Lane(...)` in `lanes.py`. `paths` are its own inputs (the hook
-   reads only these), `also` is CI-only fan-out to consumers, and
-   `pr_paths=()` makes it label-only on PRs.
+   reads only these), `also` is CI-only fan-out to consumers.
 2. Add a `test_plan.py` case: which paths and labels select it on a PR and on
    a push, and whether it runs nightly.
 3. Prefer the `nix` and `windows` matrices. Keep the work in a script or
@@ -164,22 +181,19 @@ jobs, runners, caches and guard tests. In short:
 4. Own or mark inert every new path. The OpenSecret selector runs every
    OpenSecret lane for a new top-level directory too.
 5. Check a lane's warm duration before path-selecting it on PRs. Over about
-   8 minutes, use `pr_paths=()` with a label, nightly, or master.
-
-- **Runners.** Blacksmith for compiles people wait on, free GitHub runners
-  for light or unwatched work, GitHub-hosted for attestation, signing,
-  verification and Windows install smokes ([CI runners](../../../docs/ci.md#runners)).
-  The `CI_*_RUNNER` repository variables move lanes in an outage, no PR needed.
-- **Caches.** Lane caches use `Swatinem/rust-cache` with prefix `ci-v2`. Only
-  master pushes and the nightly run save them. Never let an action save
-  implicitly on a PR path.
-- **Timeouts.** Size them for a cold run on the home runner, never for warm
-  times. The 10-minute rule decides which lanes PRs wait on; it is not a
-  timeout.
-- **Never touch to go green:** release and publisher workflows,
-  `ci_evidence.py`, signing environments, `pcr*.json`,
-  `opensecret_change_detection.py`, or the allowlists in the policy and
-  contract tests (adding an entry is an owner decision).
+   8 minutes, set both `pr_paths=()` and `gate=False`: with `pr_paths=()`
+   alone, a CI edit still selects it on PRs. It then runs by label (default
+   `ci:full`), on master pushes and nightly; `events=PR_AND_NIGHTLY` also
+   drops master pushes.
+
+- **Runners.** Blacksmith for compiles people wait on; free GitHub runners
+  for light work; GitHub-hosted for the Agent's signing and attestation,
+  `windows-signing`, artifact verifiers, and the Windows updater tests and
+  install smokes ([CI runners](../../../docs/ci.md#runners)).
+- **Caches.** rust-cache, prefix `ci-v2`; only master pushes and the nightly
+  run save. Never let an action save implicitly on a PR path.
+- **Timeouts.** Size them for a cold run on the home runner. The 10-minute
+  rule decides PR exposure; it is not a timeout.
 
 ## Validate before pushing
 
@@ -188,68 +202,62 @@ Run from the repository root:
 ```sh
 python3 scripts/ci/plan.py lint                      # every file classified; ci.yml matches the table
 python3 scripts/ci/plan.py explain --base origin/master --head HEAD
-python3 scripts/ci/plan.py explain --event push --base origin/master --head HEAD
+python3 scripts/ci/plan.py explain --event push --base "$(git merge-base origin/master HEAD)" --head HEAD
 just lane <id>    # each selected lane this OS can run
-just lane repo    # every root flake check, for .github, scripts/ci, flake or hook edits
-```
-
-For a faster loop on `scripts/ci` or workflow edits:
-
-```sh
-nix develop --no-update-lock-file .#ci -c python3 -I -m unittest discover -s scripts/ci -p 'test_*.py'
-SYS=$(nix eval --impure --raw --expr builtins.currentSystem)
-nix build --no-link --no-update-lock-file .#checks.$SYS.ci-scripts .#checks.$SYS.workflows .#checks.$SYS.release-gates
+just lane repo    # every root flake check, for .github, scripts/ci, flake, hook or doc edits
 ```
 
 - Docs and skills are inert, so a docs-only PR runs no docs check. After
-  editing them, run `just lane repo` (or `ci-scripts`) yourself.
-- `explain` also reads paths from stdin. It ignores labels, quarantine and
-  the `os-eif` candidate rules, and has no schedule or dispatch event.
+  editing them, run `just lane repo` yourself.
+- `explain` also reads paths from stdin. It ignores labels and quarantine,
+  has no schedule or dispatch event, and lists `os-eif` for any EIF input
+  without the same-repository and base-`master` checks.
 - `lint` also reads untracked, unignored files: a stray scratch file is an
-  unclassified path. The tests need yq-go, which the `.#ci` shell provides.
-- macOS and Windows lanes need those OSes. `os-sdk-e2e` needs local
-  PostgreSQL. `os-eif` needs Linux ARM64 and `EIF_MODE=dev` or `prod`.
+  unclassified path. Lanes that need macOS, Windows, PostgreSQL or ARM64 are
+  listed in [changing CI](references/changing-ci.md#run-lanes-locally).
 
 ## Debug a red or slow run
 
-Read `plan`'s summary first: it says which lanes ran and why. `ci-ok`'s error
-names the failing job; for `nix` or `windows`, open the row named after the
-lane. Then follow [debugging](references/debugging.md). The common cases:
+Read `plan`'s summary first, then `ci-ok`'s error, which names the failing
+job (for `nix` or `windows`, open the row named after the lane).
+[Debugging](references/debugging.md) has the signatures and fail-over steps.
 
 | Symptom | Response |
 | --- | --- |
-| Nix setup fails with HTTP 416, `SSL_read` or "no substituter" from `cache.nixos.org` | Transient network fault. Re-run the job |
-| "Lost communication with the server", or a runner that vanished | Lost runner. Re-run failed jobs |
 | `plan` failed on a PR | Usually a label read failure: **Re-run all jobs**. A `CI_QUARANTINE` typo fails every run until the variable is fixed |
 | Many more lanes than expected | Unclassified path or unusable diff. Classify the path in `lanes.py` |
 | The lane you edited did not run | CI edits select gate lanes only. Add its label, then **Re-run all jobs** |
-| A lane slower than usual | Cold cache after a lockfile, toolchain, prefix or runner-image change. The next master save warms it; do not cut the timeout |
-| Heavy lanes queued for many minutes | Runner pool burst. Set `CI_LINUX_HEAVY_RUNNER=blacksmith-16vcpu-ubuntu-2404` (or another `CI_*_RUNNER`), **Re-run all jobs**, and unset it afterwards |
+| A lane slower than usual, or queued | Cold cache or a runner pool burst; see [slow runs](references/debugging.md#slow-runs). Do not cut the timeout |
 | `repo` fails a policy or contract test | Your change broke a rule or seam. Read the failing assertion and fix the change |
-| Agent native Windows suite fails in a store test | Known intermittent flake. Re-run once; a repeat goes to the `ci-nightly` issue |
+| Any other unexplained failure | Re-run the failed job once (infrastructure faults are common). A repeat is real: fix it |
 
 ## Production boundary
 
-CI decides whether a change is safe to merge. It never releases, signs,
-publishes or deploys. That work belongs to `$release-maple` and the guides
+CI decides whether a change is safe to merge; it never releases, signs,
+publishes or deploys. That work belongs to the release owner and the guides
 below, and each step needs the owner's explicit go.
 
-- A workflow, `scripts/ci` or Nix change on `master` makes the next Research
-  release wait for fresh evidence. Tell the release owner.
+- A master change to any path outside `ci_evidence.unrelated_path` (anything
+  but `apps/maple-agent/`, `docs/`, `.agents/` and root `AGENTS.md`) makes
+  older Research evidence unusable. A release gets fresh evidence from its
+  version-bump push, so never merge such a change between a bump and its
+  release; tell the release owner.
+- Files below a component's root, READMEs included, are build inputs: on
+  master they can start signed Agent or Research builds.
 - CodeQL is outside `ci-ok`; the release preflight needs its newest finished
   scan to be green.
-- An `agent-desktop-build.yml` dispatch, a signed build or any publisher is a
-  production action. Ask before running one.
-
-| For | Read |
-| --- | --- |
-| Research releases, TestFlight, App Store and Play handoffs | [`$release-maple`](../release-maple/SKILL.md) |
-| Contracts CI keeps with releases | [Repository workflows](../../../docs/repository-workflows.md#contracts) |
-| Signing environments | [App signing environments](../../../docs/app-signing-environments.md) |
-| Pages and Auth publication | [Pages deployments](../../../docs/pages-deployments.md) |
-| Agent packages and updates | [Agent desktop builds](../../../apps/maple-agent/docs/desktop-builds.md), [Agent update publication](../../../services/agent-updates/README.md#publication-and-authority) |
-| SDK publication | [SDK publishing](../../../docs/sdk-publishing.md#run-a-release) |
-| OpenSecret EIFs and PCR approvals | [EIF CI and release](../../../services/opensecret/docs/nitro-deploy.md#ci-approval-checks), [PCR compatibility](../../../services/opensecret/docs/pcr-compatibility.md) |
+- An `agent-desktop-build.yml` dispatch or re-run, a signed build or any
+  publisher is a production action. Ask the release owner before running one.
+
+Read [`$release-maple`](../release-maple/SKILL.md),
+[contracts](../../../docs/repository-workflows.md#contracts),
+[signing environments](../../../docs/app-signing-environments.md),
+[Pages](../../../docs/pages-deployments.md),
+[Agent builds](../../../apps/maple-agent/docs/desktop-builds.md),
+[Agent updates](../../../services/agent-updates/README.md#publication-and-authority),
+[SDK publishing](../../../docs/sdk-publishing.md#run-a-release),
+[EIF CI](../../../services/opensecret/docs/nitro-deploy.md#ci-approval-checks)
+and [PCR compatibility](../../../services/opensecret/docs/pcr-compatibility.md).
 
 ## References
 
diff --git a/.agents/skills/change-maple-ci/references/changing-ci.md b/.agents/skills/change-maple-ci/references/changing-ci.md
index 67c355155..50e5ad868 100644
--- a/.agents/skills/change-maple-ci/references/changing-ci.md
+++ b/.agents/skills/change-maple-ci/references/changing-ci.md
@@ -7,10 +7,10 @@ Paths are relative to the repository root. `scripts/ci/lanes.py` and
 
 | Field | Meaning |
 | --- | --- |
-| `id` | Lane id, which is also the check name |
+| `id` | Lane id and check name (a special job may add a suffix, such as `os-eif (dev)`) |
 | `paths` | The lane's own inputs. They select it in CI, and the hook selects its `hook` component from these alone |
 | `also` | CI-only fan-out to consumers (for example, the Rust SDK selects Agent lanes). The hook ignores it |
-| `pr_paths` | `None`: PRs use `paths + also`. `()`: never path-selected on PRs (label only), while push and nightly still use `paths + also`. A tuple: a narrower PR selector |
+| `pr_paths` | `None`: PRs use `paths + also`. `()`: no PR path selection (labels, and CI edits unless `gate=False`), while push and nightly still use `paths + also`. A tuple: a narrower PR selector |
 | `labels` | PR labels that add the lane (default `ci:full`) |
 | `events` | Events the lane is active for (`GATE`, `PR_SIDE`, `PR_AND_NIGHTLY`, `NOT_NIGHTLY`, or a custom set) |
 | `job` | `nix` or `windows` (the generic matrices), or the id of a special `ci.yml` job |
@@ -18,7 +18,7 @@ Paths are relative to the repository root. `scripts/ci/lanes.py` and
 | `flake`, `workdir`, `run`, `env` | `plan.py run` runs `cd <workdir> && <run>` under `bash -euo pipefail`, inside `nix develop --no-update-lock-file <flake>` when set. On Windows it uses Git Bash from `PATH`, without Nix |
 | `cache`, `workspaces`, `cache_files`, `cache_targets` | rust-cache shared key, workspaces, toolchain pins hashed into the key, and whether to cache `target/` (False keeps only the Cargo home) |
 | `timeout` | Minutes |
-| `gate` | Selected when CI infrastructure changes. Set `False` for slow builds |
+| `gate` | Selected when CI infrastructure changes, whatever `pr_paths` says. Set `False` for slow builds |
 | `opensecret` | The `opensecret_change_detection.py` output that selects the lane |
 | `submodules` | Recursive submodules with full blobless history (Nix needs `revCount`) |
 | `hook` | Pre-commit component that runs the same checks locally |
@@ -60,9 +60,9 @@ Event sets:
   repository equal to this repository, and a usable diff. It is dropped when
   any path edits a PCR approval.
 
-`plan.py explain` calls the same selection with no labels and no `os-eif`
-filter. For label behaviour, read the `labels=` fields or run the
-`test_plan.py` helpers:
+`plan.py explain` calls the same selection with no labels. It drops `os-eif`
+for an approval edit but skips the same-repository and base-`master` checks.
+For label behaviour, read the `labels=` fields or call `plan.select`:
 
 ```sh
 python3 -c 'import sys; sys.path.insert(0, "scripts/ci"); import plan; print(sorted(plan.select("pull_request", ["docs/x.md"], ["ci:package"])))'
@@ -75,39 +75,47 @@ python3 -c 'import sys; sys.path.insert(0, "scripts/ci"); import plan; print(sor
    recipe. `run` should be one short line.
 3. Choose `paths` from what the command reads. Use `also` only for consumers
    that build this lane's inputs from the tree.
-4. Choose the PR exposure:
-   - default for a fast lane;
-   - `pr_paths=()` plus a label for anything slower than about 8 minutes;
-   - `gate=False` if a CI edit should not run it.
-5. Add a `test_plan.py` case. Use the helpers `selected(paths, event,
-   labels)` and `active(event)`. Assert the PR and push selection, the
-   labels, and nightly membership. Follow the existing classes, for example
-   `AgentLaneTests`.
-6. If the lane has a `hook`, add a `hook_selected <name>` branch to
-   `.githooks/pre-commit`. `test_plan.py` checks that one exists.
+4. Choose the PR exposure. The default suits a fast lane. Over about 8
+   minutes warm, set both `pr_paths=()` and `gate=False`: with `pr_paths=()`
+   alone, a CI edit still selects it on PRs. It then runs by label (default
+   `ci:full`), on master pushes and nightly; `events=PR_AND_NIGHTLY` also
+   drops master pushes.
+5. Add a `test_plan.py` case. Use the helpers
+   `selected(paths, event, labels)` and `active(event)`. Assert the PR and
+   push selection, the labels, and nightly membership. Follow the existing
+   classes, for example `AgentLaneTests`.
+6. If the lane reuses an existing `hook` component (for example `sdk_ts`),
+   add its command to that component's own hook (`sdk/.githooks/pre-commit`).
+   A new component name also needs a `hook_selected <name>` branch in
+   `.githooks/pre-commit`; `test_plan.py` checks that one exists. Never add a
+   check inside `scripts/ci/build-sdk-publish.sh`: the SDK publishers run it.
 7. Run `plan.py lint`, `just lane <id>` and `just lane repo`.
 
 ## Add or change a special job
 
 A special job is for services, OIDC, artifacts, or another workflow's cache.
-Its id is the lane's `job`. `plan.py lint` and policy tests 7 to 9 check the
-following:
+Its id is the lane's `job`. Checked by `plan.py lint` and the policy tests:
+
+- `runs-on` exactly `${{ vars.<VARIABLE> || '<label>' }}` when the runner has
+  an override variable, otherwise the plain label; `timeout-minutes` equals
+  the lane's `timeout` (lint).
+- `ci-ok` needs it (test 8); a new runner label is declared in
+  `.github/actionlint.yaml` (test 9 and lint); checkouts use
+  `persist-credentials: false` (test 3).
+- Cache saves are guarded to master `push` or `schedule` and to the home
+  vendor (`startsWith(runner.name, 'blacksmith')`, or its negation for a
+  GitHub home); restore-only caches use `actions/cache/restore` (the cache
+  tests).
+
+By convention, not checked:
 
 - `if: fromJSON(needs.plan.outputs.lanes)['<id>']`, plus any extra guard the
-  planner also applies. For `os-eif`, change the job's `if:` and the
+  planner also applies. A mismatch shows only at run time, as `ci-ok`'s
+  `(selected): skipped`. For `os-eif`, change the job's `if:` and the
   planner's candidate rule together.
-- `runs-on` exactly `${{ vars.<VARIABLE> || '<label>' }}` when the runner has
-  an override variable, otherwise the plain label. `timeout-minutes` equals
-  the lane's `timeout`.
-- Add it to `ci-ok`'s `needs`.
-- Declare a new runner label in `.github/actionlint.yaml`.
-- Put the work in `plan.py run <id>` or a script, not inline YAML.
-- Guard cache saves to master `push` or `schedule` and to the home vendor
-  (`startsWith(runner.name, 'blacksmith')`, or its negation for a GitHub
-  home). Restore-only caches use `actions/cache/restore`.
-- Check out with `persist-credentials: false`. Any full history must use
-  `filter: blob:none`; full checkouts on Blacksmith can otherwise take
-  minutes.
+- The work lives in `plan.py run <id>` or a script, not inline YAML.
+- A full-history checkout uses `filter: blob:none`, as every one in `ci.yml`
+  does; full checkouts on Blacksmith can otherwise take minutes.
 
 Never rename the matrix jobs' `name: ${{ matrix.id }}`. The quarantine
 verdict maps job names to lane ids.
@@ -131,8 +139,9 @@ The `Runner` constants at the top of `lanes.py` are authoritative.
 - An override to the other vendor restores what it can and saves nothing.
   Failover runners are often slower, while timeouts are sized for the home
   runner.
-- Never move signing, attestation or verification jobs, the updater tests or
-  install smokes to Blacksmith, and never move one EIF builder alone.
+- Never move the Agent's signing or attestation jobs, `windows-signing`
+  jobs, artifact verifiers, the updater tests or install smokes to
+  Blacksmith, and never move one EIF builder alone.
 
 ## Caches
 
@@ -140,16 +149,15 @@ The `Runner` constants at the top of `lanes.py` are authoritative.
   a lane's `cache` name, editing `cache_files`, or changing any
   `CARGO*`/`RUST*` variable in the step's environment (including `ci.yml`'s
   top-level `env`) makes the next run cold. Its PR stays cold on every push,
-  because PRs never save.
+  because lanes never save on PRs.
 - Only master `push` and `schedule` runs save, through `save-if` and
   `matrix.cache_save` (the vendor rule).
 - `ci.yml` may read another workflow's cache only with
   `actions/cache/restore`, and only for a key a push-only workflow saves.
-- Never write a release-reserved prefix (`<os>-sccache-`, `xcode-cache-`,
-  `maple-dev-xcode`, `release-onnxruntime-ios-`, `<os>-bun-`, `<os>-gradle-`,
-  `ci-v1-agent-release-`) from `ci.yml` or a PR job.
-- Turn off implicit saves on PR paths: setup-bun `no-cache: true`, Trivy
-  `cache: "false"`, and no Magic Nix Cache.
+- Never write a release-reserved prefix (`test_contracts.RESERVED_PREFIXES`,
+  plus `ci-v1-agent-release-`) from `ci.yml` or a PR job.
+- Turn off implicit saves on PR paths: setup-bun `no-cache: true` and no
+  Magic Nix Cache (both checked), and Trivy `cache: "false"` (convention).
 - After a lockfile change, master's first save deletes the lane's target
   first, so that master run is slower than its PR.
 
@@ -188,8 +196,8 @@ All run in the `repo` lane, through the flake checks `ci-scripts`,
   8. `ci-ok` always reports and needs every job;
   9. declared runner labels.
 
-  It also checks that PRs never save caches and that only the listed jobs
-  write GitHub's store.
+  It also checks that no PR path saves a cache master reads, and that only
+  the listed jobs write GitHub's store.
 - **`test_contracts.py`** imports the code on the other side of each seam.
 
 | Contract | Protects | If it fails |
@@ -208,14 +216,11 @@ selected or nightly; run it yourself after doc edits.
 
 ## Other workflows
 
-- Only `ci.yml`, `opensecret-eif.yml`, `pages-preview-build.yml`,
-  `auth-pages-ci.yml` and `proxy-rust.yml` may run on pull requests
-  (`PULL_REQUEST_WORKFLOWS`). Adding one is an owner decision.
-- The release-evidence workflows (`frontend-tests.yml`, `rust-tests.yml`,
-  `web-build.yml`, `desktop-build.yml`, `android-build.yml`,
-  `mobile-build.yml`, `codeql.yml`) feed the release preflight. Do not fold
-  them into `ci.yml`, rename their jobs, or change their `paths:` without the
-  release owner.
+- Only the workflows in `test_workflow_policy.PULL_REQUEST_WORKFLOWS` may run
+  on pull requests. Adding one is an owner decision.
+- The release-evidence workflows (`ci_evidence.WORKFLOWS`) feed the release
+  preflight. Do not fold them into `ci.yml`, rename their jobs, or change
+  their `paths:` without the release owner.
 - `pages-preview-build.yml` and `auth-pages-ci.yml` are producers that
   `pages-publish.yml` and `auth-pages-dev-publish.yml` trust by name and
   artifact. They overlap `research-web` and `auth` on purpose: the publishers
@@ -232,7 +237,8 @@ selected or nightly; run it yourself after doc edits.
   OpenSecret change, reviewed as one.
 - For EIF checkout, Nix, cache or runner changes, prove that narHash,
   drvPaths and PCRs match the last master `eif-trusted` run, on fresh hosted
-  runners. Get the PR evidence with `ci:eif` and **Re-run all jobs**.
+  runners. Get the PR evidence with `ci:eif`, then push or **Re-run all
+  jobs** on a finished run.
 - Read [CI approval checks](../../../../services/opensecret/docs/nitro-deploy.md#ci-approval-checks)
   and the [cache policy](../../../../services/opensecret/docs/nitro-deploy.md#binary-caches-and-cold-run-validation)
   first.
@@ -249,7 +255,12 @@ selected or nightly; run it yourself after doc edits.
 - `os-helpers` needs Docker that can build `linux/arm64`.
 - `os-eif` needs Linux ARM64 and `EIF_MODE=dev` or `prod`.
 
-`just lane repo` runs every root flake check. To run one, use
-`nix build --no-link --no-update-lock-file ".#checks.$(nix eval --impure --raw --expr builtins.currentSystem).<name>"`,
-where `<name>` is `ci-scripts`, `workflows`, `release-gates`, `pages` or
-`pcr-compatibility`.
+`just lane repo` runs every root flake check. A faster loop for `scripts/ci`
+or workflow edits:
+
+```sh
+nix develop --no-update-lock-file .#ci -c python3 -I -m unittest discover -s scripts/ci -p 'test_*.py'
+SYS=$(nix eval --impure --raw --expr builtins.currentSystem)
+nix eval --no-update-lock-file --json ".#checks.$SYS" --apply builtins.attrNames   # the check names
+nix build --no-link --no-update-lock-file .#checks.$SYS.ci-scripts .#checks.$SYS.workflows .#checks.$SYS.release-gates
+```
diff --git a/.agents/skills/change-maple-ci/references/debugging.md b/.agents/skills/change-maple-ci/references/debugging.md
index bb3f2ab81..a671453bf 100644
--- a/.agents/skills/change-maple-ci/references/debugging.md
+++ b/.agents/skills/change-maple-ci/references/debugging.md
@@ -14,23 +14,25 @@ Start with the facts the run already has:
 | Action | Re-plans? | Use for |
 | --- | --- | --- |
 | Push a commit | Yes | Code fixes; also picks up new labels and variables |
-| **Re-run all jobs** | Yes: `plan` reads the PR's current labels and repository variables | After adding a label, or changing `CI_QUARANTINE` or a `CI_*_RUNNER` variable |
+| **Re-run all jobs** | Yes: `plan` reads the PR's current labels and repository variables | After adding a label, or changing `CI_QUARANTINE` or a `CI_*_RUNNER` variable. GitHub offers it only on a finished run: cancel a running PR run first, never a master run |
 | **Re-run failed jobs** | No: reuses the old `plan` outputs (lanes, matrix runners, quarantine) | Infrastructure flakes in a lane |
 | Dispatch `ci.yml` | Its own plan from the `lanes` input | Running lanes on a branch outside a PR. It never saves caches |
 
 Adding a label never starts a run by itself. That is deliberate: a label
 event could otherwise post a fresh green `ci-ok` on a commit whose real run
-failed.
+failed. With auto-merge on, a run planned before the label can still pass
+`ci-ok` and merge the PR without the labelled lanes; push or cancel it before
+it finishes.
 
 A new push to a PR cancels the superseded run, and the new `plan` waits for
-the cancellation to finish. Rapid re-pushes each add about a minute.
+the cancellation to finish, so rapid re-pushes each add some delay.
 
 ## Failure signatures
 
 | Signature | Cause | Response |
 | --- | --- | --- |
 | Nix setup fails: `HTTP error 416`, `SSL_read`, or "is required, but there is no substituter" | Transient `cache.nixos.org` error. Setup has no automatic retry | Re-run the failed job |
-| "lost communication with the server", or a job that vanished mid-run | Lost runner | Re-run failed jobs. On `agent-desktop-build.yml`, re-running in the same run keeps the build number; publication still belongs to the release owner |
+| "lost communication with the server", or a job that vanished mid-run | Lost runner | Re-run failed jobs. On `agent-desktop-build.yml` (signed builds), ask the release owner first; a re-run in the same run keeps the build number |
 | `plan` fails with `lane selection failed` on a PR | A label read through `gh api` failed, or the event payload was unusable | **Re-run all jobs** |
 | `plan` fails on every event, master included | `CI_QUARANTINE` names an unknown lane or `repo` | Fix or clear the variable |
 | `plan` succeeds but selects every lane | An unclassified path, or no usable diff (new branch, force-push) | Own or mark inert the path in `lanes.py`; `plan.py lint` lists it |
@@ -41,13 +43,15 @@ the cancellation to finish. Rapid re-pushes each add about a minute.
 | `repo` fails `test_workflow_policy` or `test_contracts` | Your change crossed a policy or a release seam | Fix the change; see the contract table in [changing CI](changing-ci.md#guard-tests) |
 | `repo` fails C7 on an unrelated PR | An earlier docs-only merge named a missing workflow; docs PRs do not run `repo` | Fix the doc reference |
 | `agent-lint` fails `check-rust` | The Agent flake's rustc no longer equals the Windows rustup pin | Bump `AGENT_WINDOWS_RUST` and `setup-agent-windows` together |
-| Agent native Windows suite (`agent-full-windows`) fails in a SQLite store test with a locked file or a disconnected channel | Known intermittent flake on Windows | Re-run once. A repeat goes to the `ci-nightly` issue; do not quarantine it to merge |
 | An EIF comparison on master reports a mismatch | Measured inputs changed; approval is a release step | A notice, not a failure. Do not edit approvals |
+| Any other failure you cannot explain | Possibly an infrastructure fault | Re-run the failed job once. A repeat is real: fix it, and do not quarantine it to merge |
 
 ## Slow runs
 
 - **Cold cache.** The first run after any of these is cold:
-  - a lockfile change (a prefix fallback restores the nearest entry);
+  - a lockfile change: a prefix fallback restores the nearest entry (a
+    workspace version bump still hits rust-cache lanes exactly, but not
+    `research-rust`, `research-android` or the packaging caches);
   - a new cache prefix, lane `cache` name or `cache_files` pin;
   - a change to a `CARGO*` or `RUST*` variable;
   - a runner image with a new preinstalled Rust or MSVC.
@@ -63,12 +67,19 @@ the cancellation to finish. Rapid re-pushes each add about a minute.
 - **Queued jobs.** If `agent-lint` or `agent-test` sit queued while other
   Blacksmith jobs start, the 32-vCPU pool is bursting. Set the repository
   variable `CI_LINUX_HEAVY_RUNNER=blacksmith-16vcpu-ubuntu-2404` (same
-  vendor, so caches still work), use **Re-run all jobs**, and unset the
-  variable afterwards. The same pattern applies to the other `CI_*_RUNNER`
-  variables in an outage. Changing repository variables needs admin rights,
-  so ask the owner if you lack them.
+  vendor, so caches still work) and unset it afterwards. For the 8-vCPU
+  lanes, `CI_LINUX_RUNNER=blacksmith-16vcpu-ubuntu-2404` keeps Blacksmith's
+  store. In a Blacksmith-wide outage use `ubuntu-latest` (or `macos-26`,
+  `windows-2025`): cold, saves nothing, slower.
+  - Matrix lanes take their runner from `plan`, so re-plan: cancel a PR run,
+    then **Re-run all jobs**. Never cancel a master run; the variable applies
+    from the next push. Special jobs read the variable when they are queued.
+  - Changing repository variables needs admin rights, so ask the owner if
+    you lack them.
 - **Slow checkouts.** Full-history checkouts on Blacksmith are slow without
-  `filter: blob:none`. Every full-history checkout in CI uses it; keep it.
+  `filter: blob:none`. Every full-history checkout in `ci.yml` uses it; keep
+  it. Adding it to other workflows (`opensecret-eif*.yml`, `release.yml`,
+  publishers) is an OpenSecret or release change.
 
 ## Nightly failures
 
@@ -81,17 +92,22 @@ as red checks on the master commit.
 
 ## Quarantine
 
-Setting `CI_QUARANTINE=<lane>` turns that lane's failure into a warning in
-`ci-ok` while it keeps running. It needs no PR and applies at the next plan.
-Use it only when the owner asks; fix the lane instead. A typo fails every
-plan, and `repo` cannot be quarantined.
+`CI_QUARANTINE` is for emergencies the owner asks for; fix the lane instead
+([design](design.md#quarantine), [CI](../../../../docs/ci.md#quarantine)).
 
 ## Release-adjacent signals
 
-- A master merge that touches `.github/`, `scripts/ci/` or Nix makes older
-  Research evidence unusable. The next Research release needs a push that
-  runs the evidence workflows again. Tell the release owner; do not work
-  around `ci_evidence.py`.
+- A master merge that touches any path outside `ci_evidence.unrelated_path`
+  (anything but `apps/maple-agent/`, `docs/`, `.agents/` and root
+  `AGENTS.md`) makes older Research evidence unusable. A release's
+  version-bump push re-runs the evidence workflows, so the risk is a merge
+  between a bump and its release. Tell the release owner; do not work around
+  `ci_evidence.py`.
+- Files below a component's root, READMEs included, are build inputs. On
+  master they start signed builds: an Agent one through
+  `plan.py only agent-desktop`, a Research one through `change_detection.py`.
+  A partial Research build (one platform only) is not usable release
+  evidence either.
 - `services/agent-updates/**` changes select every signed Research build on
   master. Never push to `master` to test them.
 - A red CodeQL scan blocks the next release, not `ci-ok`.
diff --git a/.agents/skills/change-maple-ci/references/design.md b/.agents/skills/change-maple-ci/references/design.md
index a5cda953a..9cde80bec 100644
--- a/.agents/skills/change-maple-ci/references/design.md
+++ b/.agents/skills/change-maple-ci/references/design.md
@@ -12,8 +12,9 @@ table:
 - `plan.py hook`, which is `.githooks/pre-commit`;
 - `just lane <id>`, which is `plan.py run`.
 
-CI, the hook and local runs therefore execute the same command string and
-cannot drift. Separate workflows with their own `paths:` filters and change
+CI and `just lane` run the same command. The hook picks components from the
+same paths but runs each component's faster subset (format, lint, type checks
+and unit tests). Separate workflows with their own `paths:` filters and change
 selectors drift apart and multiply check rows. A planner can do what
 `paths:` filters cannot:
 
@@ -42,8 +43,8 @@ silently. `ci-ok` runs `if: always()` and needs every other job.
 
 The `master` branch rules require `ci-ok` and no other status check.
 Auto-merge is on. There is no merge queue, and branches need not be up to
-date. Either would add a
-second full `ci-ok` run to every merge and fight stacked PRs. Master instead
+date. Either would add a second full `ci-ok` run to every merge and fight
+stacked PRs. Master instead
 re-verifies every push, and the team fixes forward. `ci.yml` already handles
 `merge_group`, so a queue is a settings change if it is ever needed.
 
@@ -58,9 +59,9 @@ already build the real artifacts on every relevant push. A PR rehearsal adds
 waiting, not coverage.
 
 No code enforces this rule; there is no timing guard. Slow lanes crept back
-before, one path selector at a time, until PRs waited 35 to 45 minutes. Check
-a lane's warm duration (the run history of its check row) before you
-path-select it.
+before, one path selector at a time. Check a lane's warm duration (the run
+history of its check row) before you path-select it. A slow lane needs both
+`pr_paths=()` and `gate=False`, or every CI edit still selects it on PRs.
 
 `test_plan.py` pins the current choices. Packaging is label-only, and the
 full suites run on master, nightly and by label. Research iOS and Android are
@@ -81,14 +82,16 @@ inputs.
 
 `save-if` in `ci.yml` allows only master `push` and `schedule`. The policy test
 `test_pull_requests_never_save_caches…` also checks dispatch and queue runs,
-and actions that save implicitly (setup-bun, Magic Nix Cache, Trivy). There
-are two deliberate exceptions, and neither writes the Actions cache that
-master reads:
+and every cache-writing action in `CACHE_WRITERS`, including the implicit
+savers setup-bun and Magic Nix Cache. The EIF jobs are the deliberate
+exceptions, and none of them writes the Actions cache that master reads:
 
 - `opensecret-eif.yml`'s unprivileged `eif` job writes only its own
   branch-scoped Actions cache.
-- The same-repository PR `os-eif` candidate pushes to FlakeHub, a Nix binary
-  cache, through job-scoped OIDC.
+- The same-repository PR builders (`ci.yml`'s `os-eif`,
+  `opensecret-eif.yml`'s `eif-trusted`) push to FlakeHub, a Nix binary cache,
+  through job-scoped OIDC. When FlakeHub does not initialize, the cache
+  action falls back to the run's branch-scoped Actions cache.
 
 ## Master runs are never cancelled
 
@@ -111,23 +114,39 @@ this; `AGENTS.md` states the rule.
 
 Standard GitHub-hosted runners are free for this public repository.
 Blacksmith and the org's 16-core GitHub Windows runner are billed per minute.
-
-| Work | Runner class | Why |
-| --- | --- | --- |
-| Compiles people wait on: Agent lint and test, macOS lanes, Windows Clippy, Research Rust, OpenSecret Rust | Blacksmith | Fast, and caches stay warm in Blacksmith's store. The two heaviest Agent lanes use the 32-vCPU class, about twice as fast cold as 8 vCPU |
-| `plan`, `ci-ok`, `repo`, SDK, proxy, web, services, `deps-*`, `os-pcr`, `os-flake-check`, CodeQL | Free GitHub Linux | Light work, or nobody waits on it |
-| Agent native Windows suites (`agent-windows-updater`, `agent-full-windows`) | Free `windows-2025` | Blacksmith's Windows workspace has an inherited write ACE that the updater's storage validation rejects. The reparse tests need the symlink privilege GitHub grants. 16 cores only add queueing to a short suite |
-| `agent-package-windows`, `research-desktop-windows`, release `build-windows` | `maple-windows-2025-16core` | Install smokes need GitHub's image; the bundles gain from cores |
-| Agent master Windows build | Blacksmith Windows | The fat-LTO link is single-threaded, so 16 cores are no faster |
-| Attestation, signing, verification, TestFlight submission | GitHub-hosted | The Agent publisher verifies attestations with `--deny-self-hosted-runners`, and Blacksmith counts as self-hosted. `windows-signing`'s Azure trust names GitHub-hosted runners (C6). Signing and verify jobs restore no cache |
-| `os-helpers`, proxy arm64 image | Free `ubuntu-24.04-arm` | No heavy compile |
-| Every EIF builder that uses FlakeHub | `blacksmith-16vcpu-ubuntu-2404-arm` | One class for PR candidates, master checks and the release build (C5). `opensecret-eif.yml`'s unprivileged fork job stays on `ubuntu-24.04-arm` |
-
-The override variables (`CI_LINUX_RUNNER`, `CI_LINUX_HEAVY_RUNNER`,
-`CI_MACOS_RUNNER`, `CI_WINDOWS_RUNNER`, `CI_WINDOWS_GITHUB_RUNNER`) move lanes
-in an outage or a queue burst without a PR. They are unset by default. The
-EIF builder, `os-helpers` and the free Windows suites have none on purpose.
-C5 pins the EIF builder; the others have no better fallback.
+[CI runners](../../../../docs/ci.md#runners) assigns each lane; the reasons:
+
+- **Compiles people wait on run on Blacksmith.** They are fast, and their
+  caches stay warm in Blacksmith's store. `agent-lint` and `agent-test` use
+  the 32-vCPU class, about twice as fast cold as 8 vCPU.
+- **Light or unwatched work runs on free GitHub runners:** `plan`, `ci-ok`,
+  `repo`, SDK, proxy, web, services, `deps-*`, `os-pcr`, `os-flake-check` and
+  CodeQL.
+- **The Agent's native Windows suites run on free `windows-2025`.**
+  Blacksmith's Windows workspace has an inherited write ACE that the
+  updater's storage validation rejects, and the reparse tests need the
+  symlink privilege GitHub grants. 16 cores only add queueing to a short
+  suite.
+- **Windows packaging (`agent-package-windows`, `research-desktop-windows`,
+  release `build-windows`) uses `maple-windows-2025-16core`.** Install smokes
+  need GitHub's image, and the bundles gain from cores.
+- **The Agent's master Windows build runs on Blacksmith Windows.** The
+  fat-LTO link is single-threaded, so 16 cores are no faster.
+- **The Agent's signing and attestation, `windows-signing` jobs and artifact
+  verifiers are GitHub-hosted.** The Agent publisher verifies attestations
+  with `--deny-self-hosted-runners`, and Blacksmith counts as self-hosted.
+  `windows-signing`'s Azure trust names GitHub-hosted runners (C6).
+  Verifiers run fresh and restore no cache. Research's macOS, Linux, iOS and
+  Android signed builds compile and sign on Blacksmith.
+- **Every EIF builder that uses FlakeHub runs on
+  `blacksmith-16vcpu-ubuntu-2404-arm`:** one class for PR candidates, master
+  checks and the release build (C5). `opensecret-eif.yml`'s unprivileged fork
+  job stays on `ubuntu-24.04-arm`.
+
+The override variables (`CI_*_RUNNER`) move lanes in an outage or a queue
+burst without a PR. They are unset by default. The EIF builder, `os-helpers`
+and the free Windows suites have none on purpose: C5 pins the EIF builder,
+and the others have no better fallback.
 
 ## Cache stores and keys
 
@@ -142,8 +161,11 @@ C5 pins the EIF builder; the others have no better fallback.
 - **Lane caches (`ci-v2`).** The key is the lane's cache name, a hash of its
   toolchain pins (`cache_files`), and rust-cache's own hash of the runner's
   rustc and `CARGO*`/`RUST*` variables. All of these must match exactly.
-  rust-cache adds the lockfile hash, which may differ: after a lockfile
-  change, the newest entry of the same lane and toolchain restores by prefix.
+  rust-cache adds the lockfile hash of third-party crates, which may differ:
+  a workspace version bump still hits exactly, and after any other lockfile
+  change the newest entry of the same lane and toolchain restores by prefix.
+  Caches keyed on the raw `Cargo.lock` (`research-rust`, `research-android`
+  and the `agent-package-*` caches) restore by prefix after a bump too.
   A saving master run without an exact hit first deletes the lane's target
   directory, so each saved cache holds one dependency graph.
 - **`agent-cargo-home`.** `agent-supply-chain` and `agent-provider` only
@@ -156,31 +178,31 @@ C5 pins the EIF builder; the others have no better fallback.
   builds only restore it. No `ci.yml` lane reads it. A `Cargo.lock` change,
   version bumps included, makes the next master Agent build fully cold. That
   cost is known and accepted.
-- **Reserved prefixes.** `release.yml` restores `<os>-sccache-`,
-  `xcode-cache-`, `release-onnxruntime-ios-`, `<os>-bun-` and `<os>-gradle-`
-  by prefix. Only the signed master workflows write them. `ci.yml` only
-  restores keys that master saves. No lane family shares a prefix with a
-  release family, or a new key would hijack the release's fallback (C4).
+- **Reserved prefixes.** `release.yml` restores the families in
+  `test_contracts.RESERVED_PREFIXES` by prefix. Only the signed master
+  workflows write them. `ci.yml` only restores keys that master saves. No
+  lane family shares a prefix with a release family, or a new key would
+  hijack the release's fallback (C4).
 
 ## Fat LTO and the packaging rehearsals
 
 The owner chose fat LTO with one codegen unit for Agent release builds
 (`apps/maple-agent/Cargo.toml`), because download size matters. Thin LTO
-measured clearly larger binaries. Do not re-pitch it. The consequence is a
-master Agent build of roughly 25 minutes, mostly single-threaded compile and
-link, which bigger runners do not speed up. The `ci:package` rehearsals
-deliberately build thin LTO (`FAST_RELEASE` in `lanes.py`) into their own
-`ci-v1-agent-package-*` caches. They prove the packaging, not the optimizer.
-Only the nightly master run saves those caches.
+measured clearly larger binaries. The consequence is a slow master Agent
+build, mostly single-threaded compile and link, which bigger runners do not
+speed up. The `ci:package` rehearsals deliberately build thin LTO
+(`FAST_RELEASE` in `lanes.py`) into their own `ci-v1-agent-package-*` caches.
+They prove the packaging, not the optimizer. Only the nightly master run
+saves those caches.
 
 ## Agent Dev builds run nightly
 
 `agent-desktop-build.yml` builds Prod on master pushes, Dev nightly at 10:37
 UTC, and both on dispatch. Prod no longer waits on, or gets skipped by, a
-failed Dev leg, and each push saves a full Dev build set. The nightly run can
-never be published, because the publisher accepts only `push` and
-`workflow_dispatch` runs. The hour avoids the other scheduled runs and the
-top of the hour. Research iOS Dev TestFlight stays on push.
+failed Dev leg, and pushes no longer spend runner time on Dev packages. The
+nightly run can never be published, because the publisher accepts only
+`push` and `workflow_dispatch` runs. The hour avoids the other scheduled runs
+and the top of the hour. Research iOS Dev TestFlight stays on push.
 
 ## CodeQL only has to be "not red"
 
@@ -228,13 +250,14 @@ audit whenever they are selected.
 
 ## Tests: behaviour and contracts, not text
 
-Tests that assert a script's or workflow's text break on harmless renames and
-rewording and catch no behaviour. A hand-copied list of required test names
-breaks on the next rename. Test
-what the planner selects, or the contract another file consumes:
-`test_contracts.py` imports `publisher.py`, `ci_evidence.py` and the
-signature probe rather than copying their rules. Derive any list a test
-needs.
+Tests that grep a script's or workflow's prose or comments break on harmless
+renames and rewording and catch no behaviour. A hand-copied list of required
+test names breaks on the next rename. Test what the planner selects, or the
+contract another file consumes: `test_contracts.py` imports `publisher.py`,
+`ci_evidence.py` and the signature probe rather than copying their rules.
+Where a seam depends on exact structure, a contract test asserts the parsed
+YAML fields and conditions (for example the clean step's `run` lines or the
+EIF `sign` job's `if:`). Derive any list a test needs.
 
 The policy and contract tests do keep a few deliberate security allowlists:
 `PULL_REQUEST_WORKFLOWS`, `GITHUB_STORE_WRITERS`, `GITHUB_STORE_LANES`,
diff --git a/.agents/skills/develop-maple/SKILL.md b/.agents/skills/develop-maple/SKILL.md
index f264297eb..7f787747c 100644
--- a/.agents/skills/develop-maple/SKILL.md
+++ b/.agents/skills/develop-maple/SKILL.md
@@ -59,6 +59,7 @@ Load the matching workflow when the task crosses it:
 - `$develop-opensecret-sdk` or `$develop-maple-proxy`: their owned source/contracts.
 - `$review-maple-security`: a trust-boundary change or security review.
 - `$validate-maple`: validation beyond the focused loop and before handoff.
+- `$change-maple-ci`: CI lanes, labels, re-runs, or red or slow CI.
 - `$release-maple`: explicitly authorized publication only.
 
 ## Focused loop and handoff
diff --git a/.agents/skills/review-opensecret-security/SKILL.md b/.agents/skills/review-opensecret-security/SKILL.md
index 4c3a103ce..2bfbb274c 100644
--- a/.agents/skills/review-opensecret-security/SKILL.md
+++ b/.agents/skills/review-opensecret-security/SKILL.md
@@ -134,27 +134,27 @@ database, provider, client, build/artifact, and live evidence separately.
 Local artifact builds and read-only PCR comparison are validation when in
 scope. Root backend CI validates Rust, Nix checks, and SDK compatibility.
 `ci.yml`'s `os-eif` lane builds dev/prod EIF candidates for same-repository
-PRs to `master` without comparing approvals. `opensecret-eif.yml` compares
-dev/prod EIF measurements on explicit approved-PCR JSON edits in PRs,
-relevant master changes, and manual runs. Do not require ordinary backend PRs to update
-approvals. A master mismatch is a pending-approval notice with the built PCRs;
-do not hide it or turn it into a pass without that notice. Master push/manual
-runs, same-repository PR comparisons and the `os-eif` candidate receive OIDC
-for FlakeHub caching; fork PRs and non-master manual refs use GitHub's
-branch-scoped cache without OIDC. Review event/ref guards and the PR
-head-repository equality check, including missing metadata, cache
-provenance, and default-branch versus PR cache scope. For `os-eif`, the
-planner's candidate rule in `scripts/ci/plan.py` and the job's `if:` in
-`ci.yml` must agree. Same-repository PR code is intentionally trusted to write FlakeHub.
-Cache writes never authorize approval changes, signing, EIF releases, or
-deployment. A passing comparison is not live
+PRs to `master` and reports whether approval is needed, without failing on a
+mismatch. `opensecret-eif.yml` compares dev/prod EIF measurements on explicit
+approved-PCR JSON edits in PRs, relevant master changes, and manual runs. Do
+not require ordinary backend PRs to update approvals. A master mismatch is a
+pending-approval notice with the built PCRs; do not hide it or turn it into a
+pass without that notice. Master push/manual runs, same-repository PR
+comparisons and the `os-eif` candidate receive OIDC for FlakeHub caching; fork
+PRs and non-master manual refs use GitHub's branch-scoped cache without OIDC.
+Review event/ref guards and the PR head-repository equality check, including
+missing metadata, cache provenance, and default-branch versus PR cache scope.
+For `os-eif`, the planner's candidate rule in `scripts/ci/plan.py` and the
+job's `if:` in `ci.yml` must agree. Same-repository PR code is intentionally
+trusted to write FlakeHub. Cache writes never authorize approval changes,
+signing, EIF releases, or deployment. A passing comparison is not live
 deployment evidence or proof that both public PCR locations are synchronized.
 Use `docs/pcr-compatibility.md` for manual signed-PCR validation and legacy
-publication. Require explicit authorization for PCR
-reference/history mutation, signing, KMS/IAM changes, shared or remote
-migrations, artifact transfer, enclave or remote-service lifecycle, secret
-writes, staging, deployment, or release actions. Inspect recipes before
-deciding whether they are read-only.
+publication. Require explicit authorization for PCR reference/history
+mutation, signing, KMS/IAM changes, shared or remote migrations, artifact
+transfer, enclave or remote-service lifecycle, secret writes, staging,
+deployment, or release actions. Inspect recipes before deciding whether they
+are read-only.
 
 ## Report the review
 
diff --git a/.agents/skills/validate-opensecret/references/checks.md b/.agents/skills/validate-opensecret/references/checks.md
index 78923a548..aeff96439 100644
--- a/.agents/skills/validate-opensecret/references/checks.md
+++ b/.agents/skills/validate-opensecret/references/checks.md
@@ -71,13 +71,13 @@ OPENSECRET_DEV_POSTGRES=0 OPENSECRET_DEV_ENV=0 OPENSECRET_DEV_CONTAINERS=0 \
 
 The helper proves an empty-database migration and the selected local synthetic
 database suites, including OAuth settings preservation, callback selection,
-and Google/GitHub callback completion through the real V1 encryption middleware
-and V2 gateway. Completion tests exchange synthetic credentials only with
-local mock token/user-info endpoints, verify the originally selected callback
-after settings change, and reject replay without another exchange. The
-`os-sdk-e2e` lane in `ci.yml` runs this helper too. These fixtures do not prove a live
-OAuth provider flow, a released SDK or application, or a data conversion from
-representative old rows.
+and Google/GitHub callback completion through the real V1 encryption
+middleware and V2 gateway. Completion tests exchange synthetic credentials
+only with local mock token/user-info endpoints, verify the originally selected
+callback after settings change, and reject replay without another exchange.
+The `os-sdk-e2e` lane in `ci.yml` runs this helper too. These fixtures do not
+prove a live OAuth provider flow, a released SDK or application, or a data
+conversion from representative old rows.
 
 For a data migration, separately build an upgrade-shaped disposable database
 with representative pre-change rows and verify restart, rollback, and retry
@@ -159,10 +159,11 @@ Read-only EIF construction and PCR comparison are validation when in scope.
 Root backend CI runs the component flake checks but does not build the
 default package. `ci.yml`'s `os-eif` lane builds dev/prod EIF candidates for
 same-repository PRs to `master` that change measured inputs (or carry
-`ci:eif`) without editing approvals; it reports PCRs and compares nothing.
-`opensecret-eif.yml` builds dev/prod and compares generated measurements on
-PRs that explicitly edit the four approved PCR JSON files, relevant
-backend/TEE or approval changes to master, and manual runs. Ordinary backend PRs do not require new PCR approvals. A PR
+`ci:eif`) without editing approvals; it reports PCR0 and whether approval is
+needed, and never fails on a mismatch. `opensecret-eif.yml` builds dev/prod
+and compares generated measurements on PRs that explicitly edit the four
+approved PCR JSON files, relevant backend/TEE or approval changes to master,
+and manual runs. Ordinary backend PRs do not require new PCR approvals. A PR
 fails on a mismatch only in an environment whose approval files it edits; a
 master mismatch passes with a notice and the built PCRs, meaning the revision
 awaits approval. The check script exits 3 for a mismatch and with another
diff --git a/AGENTS.md b/AGENTS.md
index e1b65bccc..504b6a7d3 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -85,15 +85,17 @@ and installed-client raw URLs. Never change approvals to clear ordinary PR check
 Load `$change-maple-ci` before changing, triggering or debugging CI; it holds
 the full rules and their reasons. In short:
 
-- `ci-ok` is the one required check. Without labels, every PR reaches it well
-  under 10 minutes; slower builds run only by `ci:*` label, nightly, or on master.
+- `ci-ok` is the one required check. Without labels, every PR must reach it
+  well under 10 minutes; slower builds run only by `ci:*` label, nightly, or
+  on master.
 - Add or change checks only as lanes in `scripts/ci/lanes.py`, each with a
   `test_plan.py` case; no new side workflows or bespoke guard scripts.
 - Never put `[skip ci]`, `[ci skip]` or similar in a commit or PR title: master
   plans each push from the previous commit, so a skipped commit is never checked.
 - Test behavior, or a contract another file consumes; never a script's or
   workflow's text, and never hand-copied lists of names.
-- Pull requests never save an Actions cache, and master runs are never cancelled.
+- Lanes never save a cache on a pull request (the EIF jobs' branch-scoped
+  exceptions are in the skill), and master runs are never cancelled.
 - Never edit release or publisher workflows, signing environments, or OpenSecret
   approval gating to clear a check; a failing contract test means fix the change.
 - Run `just lane <id>` for the lanes your change selects before pushing. Add a
diff --git a/apps/maple-agent/README.md b/apps/maple-agent/README.md
index 57e72e30d..9ea121c5a 100644
--- a/apps/maple-agent/README.md
+++ b/apps/maple-agent/README.md
@@ -350,10 +350,11 @@ The root also offers `just agent-check`, `just agent-build`, and
 `/Applications/Xcode.app`; Linux libraries come from Nix. Windows has no Nix:
 `.github/actions/setup-agent-windows` pins the Rust version that the
 component's `flake.lock` resolves, and the `agent-lint` lane fails if the two
-differ. Cargo commands run from this directory. The statically linked SQLCipher/OpenSSL
-build needs Perl; Nix supplies it on macOS/Linux. Windows needs native Windows
-Perl (for example Strawberry Perl), rather than MSYS Perl. NASM enables the
-provider's assembly path when available; its build supports a no-assembly fallback.
+differ. Cargo commands run from this directory. The statically linked
+SQLCipher/OpenSSL build needs Perl; Nix supplies it on macOS/Linux. Windows
+needs native Windows Perl (for example Strawberry Perl), rather than MSYS
+Perl. NASM enables the provider's assembly path when available; its build
+supports a no-assembly fallback.
 
 For an OpenSecret managed workspace, run its `bin/maple-agent` launcher
 instead of launching the binary directly. It sources private
@@ -635,9 +636,10 @@ tests run in the ordinary app test suite.
 
 The root `ci.yml` runs this component's lanes (`scripts/ci/lanes.py`) when
 Agent or its shared Rust dependencies change; [CI](../../docs/ci.md) lists the
-tiers and labels. Root `just lane <id>` runs one lane as CI does. `just ci` is the full local format, lint, build and test gate;
-`just release` separately validates the optimized binary. PR jobs have no signing or publishing credentials. See the
-root agent guide for shared checks.
+tiers and labels. Root `just lane <id>` runs one lane as CI does. `just ci` is
+the full local format, lint, build and test gate; `just release` separately
+validates the optimized binary. PR jobs have no signing or publishing
+credentials. See the root agent guide for shared checks.
 
 Two by-hand checks complement the automated ones: the
 [scenario checklist](docs/scenario-checklist.md), one scenario per feature
diff --git a/apps/maple-agent/crates/store-bench/README.md b/apps/maple-agent/crates/store-bench/README.md
index 18234e0d1..d12c567a5 100644
--- a/apps/maple-agent/crates/store-bench/README.md
+++ b/apps/maple-agent/crates/store-bench/README.md
@@ -12,8 +12,7 @@ nix develop --no-update-lock-file . -c just store-bench-ci
 nix develop --no-update-lock-file . -c just store-bench
 ```
 
-The small `store-bench-ci` fixture has 40 tasks / 8,000 entries, including a
-2,000-entry hot task.
+The CI fixture has 40 tasks / 8,000 entries, including a 2,000-entry hot task.
 The full fixture has 2,000 tasks / 1,000,000 entries, including a 100,000-entry
 hot task and a 20,000-entry long task. The deterministic generator adapts the
 research harness's shape to current typed Pi messages. It creates real user
@@ -65,13 +64,13 @@ Each JSON result has a sibling SHA-256 file and records engine/provider
 versions, source revision/dirty state, executable digest, OS/CPU/memory, load,
 dataset identity and settings. No synthetic database or key is uploaded.
 
-## References
+## References and CI
 
 `scripts/evaluate.py` requires both modes, the canonical seed/scale, all
 scenarios and their sample counts, effective durability settings, and indexed
 plans with and without statistics. Missing scenarios cannot silently remove a
-slow operation. The `linux-ci` profile compares medians at 10x its recorded
-Linux reference; the `macos-full` profile uses 2x its recorded macOS reference. Platform
+slow operation. Linux CI compares medians at 10x its actual Linux reference;
+the `macos-full` profile uses 2x its actual macOS reference. Platform
 mismatches are rejected. Native Mac small runs can use `--profile linux-ci
 --diagnostic` to validate workload evidence without comparing or recording a
 Linux runner gate.
diff --git a/apps/maple-agent/docs/desktop-builds.md b/apps/maple-agent/docs/desktop-builds.md
index 75d091f22..57b2a2b0e 100644
--- a/apps/maple-agent/docs/desktop-builds.md
+++ b/apps/maple-agent/docs/desktop-builds.md
@@ -191,9 +191,10 @@ return validation; package metadata alone does not prove those browser flows.
 
 ## Packaging commands
 
-From `apps/maple-agent`, using the pinned component shell (`just
-package-rehearsal` runs the host platform's sequence, as the `agent-package-*`
-lanes do):
+From `apps/maple-agent`, using the pinned component shell
+(`just package-rehearsal` runs this sequence with extra macOS or Linux
+verification, as the `agent-package-linux` and `agent-package-macos` lanes
+do; Windows uses the commands below):
 
 ```sh
 nix develop --no-update-lock-file . -c ./scripts/build-release.sh dev
@@ -214,9 +215,9 @@ Windows builds use the pinned Rust/MSVC environment from
 `RUSTFLAGS='-D warnings -C target-feature=+crt-static'`. Master's unsigned
 build compiles on Blacksmith Windows; signing, verification and the
 `ci:package` rehearsal's install smoke run on GitHub's Windows image
-([CI runners](../../../docs/ci.md#runners)). `build-release.sh` selects the explicit x64 MSVC target
-so host build tools keep their normal linkage, then stages the exact resulting
-executable.
+([CI runners](../../../docs/ci.md#runners)). `build-release.sh` selects the
+explicit x64 MSVC target so host build tools keep their normal linkage, then
+stages the exact resulting executable.
 From the component directory in Git Bash on Windows:
 
 ```sh
diff --git a/apps/maple-auth/AGENTS.md b/apps/maple-auth/AGENTS.md
index 267fba76a..3ba995319 100644
--- a/apps/maple-auth/AGENTS.md
+++ b/apps/maple-auth/AGENTS.md
@@ -11,7 +11,7 @@ Use the root `.#ci` Nix shell (Bun and Node match CI). See [README.md](README.md
 for development, component checks and the fixed Dev/Prod build profiles. Run
 `scripts/ci/auth-ci.sh` for format, lint, type checking, and tests. The root hook
 routes this app to `.githooks/pre-commit`. Run the auth build when source,
-configuration or dependencies change, and root `just lane repo` for workflow
+configuration or dependencies change, and root `nix flake check` for workflow
 or shared CI changes. Do not overwrite ignored environment files.
 
 The required `VITE_AUTH_ENVIRONMENT` selector fixes the backend, project and PCR
diff --git a/apps/maple-research/README.md b/apps/maple-research/README.md
index c814bcedb..c20332a04 100644
--- a/apps/maple-research/README.md
+++ b/apps/maple-research/README.md
@@ -153,8 +153,8 @@ nix develop --no-update-lock-file .#ci -c ./scripts/ci/rust.sh
 # PR-configured web artifact
 MAPLE_WEB_ENVIRONMENT=pr nix develop --no-update-lock-file .#ci -c ./scripts/ci/web.sh
 
-# Nix/toolchain/workflow metadata (every root flake check); not application tests
-just lane repo
+# Nix/toolchain/workflow metadata; not application tests
+nix flake check --no-update-lock-file
 ```
 
 There is no general checked-in browser, packaged-app, or React-to-Tauri-command
diff --git a/apps/maple-research/docs/development-contracts.md b/apps/maple-research/docs/development-contracts.md
index bbf413c62..b25842f39 100644
--- a/apps/maple-research/docs/development-contracts.md
+++ b/apps/maple-research/docs/development-contracts.md
@@ -41,11 +41,12 @@ The Maple Proxy source lives under `proxy/`. From the repository root,
 run its Rust commands through
 `nix develop --no-update-lock-file ./proxy -c bash -lc 'cd proxy && ...'`;
 the root `ci.yml` `proxy` lane owns proxy CI. Proxy runtime and Rust SDK build
-changes select `research-rust` on PRs and the signed native builds on master,
-because the Research shell builds both from the tree. TypeScript SDK changes
-select no app build, since Research builds the SDK its own manifests select.
-Container, test, documentation, and standalone lockfile changes remain
-independent.
+changes select `research-rust` on PRs, because the Research shell builds both
+from the tree. On master, Rust SDK build changes select every signed native
+build and proxy runtime changes the signed desktop builds. TypeScript SDK
+changes select no app build, since Research builds the SDK its own manifests
+select. Container, test, documentation, and standalone lockfile changes
+remain independent.
 
 ## Code ownership and placement
 
diff --git a/apps/maple-research/docs/research-dev-desktop.md b/apps/maple-research/docs/research-dev-desktop.md
index 14780599e..a485f2311 100644
--- a/apps/maple-research/docs/research-dev-desktop.md
+++ b/apps/maple-research/docs/research-dev-desktop.md
@@ -73,11 +73,12 @@ Only this explicit local command builds the Dev RPM; existing PR/release package
 jobs and production identities are unchanged.
 
 Ordinary Research PR package RPMs (the `research-desktop-linux` lane) use Dev
-services but retain the production `maple` package identity. They do **not** install beside production. Restore the website
-RPM to that slot separately; for equal versions use `sudo dnf reinstall ./<rpm>`,
-or `sudo dnf downgrade ./<rpm>` if the website version is older. Sign in again if
-needed; do not copy credentials between the two apps. No automatic data migration
-or deletion is performed by the Dev build.
+services but retain the production `maple` package identity. They do **not**
+install beside production. Restore the website RPM to that slot separately;
+for equal versions use `sudo dnf reinstall ./<rpm>`, or
+`sudo dnf downgrade ./<rpm>` if the website version is older. Sign in again
+if needed; do not copy credentials between the two apps. No automatic data
+migration or deletion is performed by the Dev build.
 
 ### macOS
 
@@ -106,9 +107,10 @@ local-install rehearsal package, not a signed release or deployment. The lane
 checks out the exact PR head; tie the downloaded package and its profile hashes
 to that source run and checkout log when recording test evidence.
 
-The lane runs when a PR carries `ci:research-dev-macos` (or `ci:package`).
-Labels are read when the run starts: add the label, then re-run the `CI`
-workflow. `ci:package` also runs the `research-desktop-*` bundles.
+The lane runs when a PR carries `ci:research-dev-macos` (or `ci:package` or
+`ci:full`). Labels are read when the run's `plan` job starts: add the label,
+then push or use **Re-run all jobs** on a finished run (**Re-run failed jobs**
+keeps the old plan). `ci:package` also runs the `research-desktop-*` bundles.
 
 The different bundle ID separates the WebView's stored credentials and Tauri's
 app config/data directories from the production app. Dev does not run the old
diff --git a/apps/maple-research/frontend/src-tauri/resources/windows/README.md b/apps/maple-research/frontend/src-tauri/resources/windows/README.md
index 796c90638..6b00d67c0 100644
--- a/apps/maple-research/frontend/src-tauri/resources/windows/README.md
+++ b/apps/maple-research/frontend/src-tauri/resources/windows/README.md
@@ -43,8 +43,7 @@ must be staged here **before `bun tauri build`** on Windows.
 
 ## CI staging
 
-The `research-desktop-windows` CI lane (on pull requests with `ci:package`)
-and the signed builds stage these automatically through
+The Windows PR and signed release workflows stage these automatically through
 `scripts/ci/desktop-windows-pr.sh` and `scripts/ci/desktop-windows-release.sh`
 before the Tauri build. Those scripts use:
 
@@ -59,10 +58,10 @@ field. The staging script therefore rejects ARM64EC markers and only copies
 native AMD64 runtime DLLs into the installer payload.
 
 The PR build emits `target/reproducibility/desktop-pr-windows-*.sha256` proof
-manifests, which the same lane verifies after the build. The signed release
-build emits `target/reproducibility/desktop-release-windows-*.sha256` proof
-manifests after the installer is Authenticode-signed and the final Tauri
-updater `.sig` is generated; CI verifies those from uploaded artifacts.
+manifests. The signed release build emits
+`target/reproducibility/desktop-release-windows-*.sha256` proof manifests after
+the installer is Authenticode-signed and the final Tauri updater `.sig` is
+generated. CI verifies those manifests from uploaded artifacts.
 
 For a **local** Windows build, run `scripts/provide-windows-onnxruntime.sh`
 first (it exports `ORT_DYLIB_PATH`), then run the same staging helper:
diff --git a/docs/app-signing-environments.md b/docs/app-signing-environments.md
index 0df7fc13a..4effeba34 100644
--- a/docs/app-signing-environments.md
+++ b/docs/app-signing-environments.md
@@ -113,11 +113,11 @@ Rerunning an old workflow revision that predates these environment declarations
 will no longer have signing access; use a current reviewed revision instead.
 
 `just lane repo` (the root `nix flake check`) checks workflow syntax and the
-signing job boundaries. The manual `Check app signing credentials` workflow checks
-credential availability without signing, building, or publishing anything. Only
-jobs using an environment with required reviewers, such as `zapstore-publishing`,
-pause for approval. Run it on `master`; a run from a feature branch should be
-rejected by the environment policies.
+signing job boundaries. The manual `Check app signing credentials` workflow
+checks credential availability without signing, building, or publishing
+anything. Only jobs using an environment with required reviewers, such as
+`zapstore-publishing`, pause for approval. Run it on `master`; a run from a
+feature branch should be rejected by the environment policies.
 
 Server-side environment policies and secret placement must also
 be verified through GitHub; a source test cannot enforce repository settings.
diff --git a/docs/ci.md b/docs/ci.md
index d66984ac3..1eba71e17 100644
--- a/docs/ci.md
+++ b/docs/ci.md
@@ -1,13 +1,13 @@
 # CI
 
 `.github/workflows/ci.yml` runs every required pull-request check. Its one
-verdict, `ci-ok`, is the only required status check: it passes when every
-lane the planner selected succeeded, and an unselected lane may only be
-skipped. `opensecret-eif.yml`, `pages-preview-build.yml`, `auth-pages-ci.yml`
-and `proxy-rust.yml` also run on matching pull requests; they are advisory
-and not part of `ci-ok`. Signed builds, publication, caches and the contracts
-CI keeps are in [repository workflows](repository-workflows.md). Agents
-changing or triggering CI load
+verdict, `ci-ok`, is the only required status check: it passes when every lane
+the planner selected succeeded, and an unselected lane may only be skipped.
+`auth-pages-ci.yml` and `proxy-rust.yml` also run on matching pull requests,
+and `opensecret-eif.yml` and `pages-preview-build.yml` on matching pull
+requests to `master`; they are advisory and not part of `ci-ok`. Signed
+builds, publication, caches and the contracts CI keeps are in [repository
+workflows](repository-workflows.md). Agents changing or triggering CI load
 [`$change-maple-ci`](../.agents/skills/change-maple-ci/SKILL.md).
 
 ## How lanes are chosen
@@ -42,11 +42,14 @@ The `plan` job summary lists each selected lane and why. To preview locally:
 
 ```sh
 python3 scripts/ci/plan.py explain --base origin/master --head HEAD
+python3 scripts/ci/plan.py explain --event push --base "$(git merge-base origin/master HEAD)" --head HEAD
 ```
 
-`explain` also reads paths from stdin, and `--event push` shows master's
-selection. It applies no labels and lists `os-eif` for any EIF input, without
-the same-repository, base-`master` and approval-edit checks.
+The second command shows what master would run after the merge; a push diff
+does not use the merge base, so pass it yourself. `explain` also reads paths
+from stdin. It applies no labels, and it lists `os-eif` for any EIF input
+without the same-repository and base-`master` checks (it does drop it for a
+PCR approval edit).
 
 ## Tiers
 
@@ -123,18 +126,20 @@ of the lanes your staged files select.
 ## Rules
 
 - Never add `paths:` to `ci.yml`; `ci-ok` must report on every pull request.
-- Without labels, every pull request reaches `ci-ok` well under 10 minutes. A lane slower
-  than about 8 minutes runs only by label, nightly, or as master's real
-  builds; check its warm duration before selecting it by path on pull
-  requests.
-- Pull requests never save an Actions cache (one branch-scoped exception,
-  outside `ci.yml`, is listed under [caches](repository-workflows.md#caches));
-  same-repository EIF candidates may push to FlakeHub. Master
-  and nightly runs save lane caches into the store of the lane's own runner
-  vendor: Blacksmith's, or GitHub's for the Agent lanes on GitHub's Windows
-  image. A lane cache must match the lane's toolchain exactly; after a
-  lockfile change, a run restores the newest one by prefix, and master
-  rebuilds the lane's target from scratch before it saves.
+- Without labels, every pull request must reach `ci-ok` well under 10
+  minutes. A lane slower than about 8 minutes stays off the pull-request
+  path: it runs only by label, nightly, or as master's real builds. Check its
+  warm duration before selecting it by path on pull requests.
+- Lanes never save a cache on a pull request; only master pushes and the
+  nightly run do, into the store of the lane's own runner vendor:
+  Blacksmith's, or GitHub's for the Agent lanes on GitHub's Windows image.
+  The EIF jobs are the exceptions: on pull requests they may write
+  branch-scoped Actions-cache entries that master cannot read, and
+  same-repository EIF builds push to FlakeHub
+  ([caches](repository-workflows.md#caches)). A lane cache must match the
+  lane's toolchain exactly; after a lockfile change, a run restores the
+  newest one by prefix, and master rebuilds the lane's target from scratch
+  before it saves.
 - Never cancel master, signed, evidence or nightly runs.
 - Never edit the release or publisher workflows, signing environments or
   OpenSecret approval gating to clear a check. A failing contract test means
@@ -174,7 +179,9 @@ org's 16-core GitHub runner are billed by the minute.
 During an outage or a queue burst, set the repository variable
 `CI_LINUX_RUNNER`, `CI_LINUX_HEAVY_RUNNER`, `CI_MACOS_RUNNER`,
 `CI_WINDOWS_RUNNER` or `CI_WINDOWS_GITHUB_RUNNER` to another label; no pull
-request is needed, and it applies when `plan` next runs (**Re-run all jobs**).
+request is needed. Matrix lanes pick it up when `plan` next runs (**Re-run
+all jobs** on a finished run, or the next push); special jobs read it when
+they are queued.
 `CI_WINDOWS_GITHUB_RUNNER=windows-2025` moves the 16-core lanes to the
 standard runner, which uses the same cache store. A runner from the other
 vendor never saves a cache. The EIF builder, `os-helpers` and the free
diff --git a/docs/pages-deployments.md b/docs/pages-deployments.md
index 5649b1860..fdffd0736 100644
--- a/docs/pages-deployments.md
+++ b/docs/pages-deployments.md
@@ -181,12 +181,13 @@ publication requires a Research release.
 
 The Dev producer is `Auth Pages CI` itself: its job runs `auth-ci.sh` and
 builds the artifact. On pull requests, `ci.yml`'s `auth` lane runs the same
-`auth-ci.sh` for `ci-ok`, so the checks run twice by design. Push and PR path filters cover Auth source, its build scripts,
-the artifact tooling and shared Nix inputs; a newer PR head cancels an older
-build. The Pages and publisher tests run in `ci.yml`'s `repo` lane. Unrelated application changes
-alone do not trigger it. PR checkout and manifest use the exact PR head SHA,
-not GitHub's synthetic merge SHA. Forks retain the unprivileged CI checks but
-do not produce a publishable artifact. Each publisher executes trusted master
+`auth-ci.sh` for `ci-ok`, so the checks run twice by design. Push and PR path
+filters cover Auth source, its build scripts, the artifact tooling and shared
+Nix inputs; a newer PR head cancels an older build. The Pages and publisher
+tests run in `ci.yml`'s `repo` lane. Unrelated application changes alone do
+not trigger it. PR checkout and manifest use the exact PR head SHA, not
+GitHub's synthetic merge SHA. Forks retain the unprivileged CI checks but do
+not produce a publishable artifact. Each publisher executes trusted master
 tooling in a separate `workflow_run` job; PR code never receives publication
 credentials.
 
diff --git a/docs/repository-workflows.md b/docs/repository-workflows.md
index e2f285d47..3102e24cd 100644
--- a/docs/repository-workflows.md
+++ b/docs/repository-workflows.md
@@ -32,13 +32,16 @@ branches in step with the lane table.
 
 ## Caches
 
-- Pull requests restore Actions caches and never save one. The one exception
-  is `opensecret-eif.yml`'s `eif` job (fork PRs that edit PCR approvals, and
-  manual runs outside `master`): without FlakeHub credentials, its Nix store
+- Pull requests restore Actions caches, and no pull-request write reaches a
+  cache `master` reads. The exceptions are the EIF jobs.
+  `opensecret-eif.yml`'s `eif` job (fork PRs that edit PCR approvals, and
+  manual runs outside `master`) has no FlakeHub credentials, so its Nix store
   goes to the run's branch-scoped Actions cache, which `master` and other
   pull requests cannot read. Same-repository PR EIF builds (`ci.yml`'s
   `os-eif` and `opensecret-eif.yml`'s `eif-trusted`) push to the FlakeHub Nix
-  cache by design ([cache policy](../services/opensecret/docs/nitro-deploy.md#binary-caches-and-cold-run-validation)).
+  cache by design, and fall back to the branch-scoped Actions cache when
+  FlakeHub does not initialize
+  ([cache policy](../services/opensecret/docs/nitro-deploy.md#binary-caches-and-cold-run-validation)).
 - Lane caches (`Swatinem/rust-cache`, prefix `ci-v2`) are keyed by lane and
   toolchain pins (the workspace's `flake.lock`, and OpenSecret's
   `rust-toolchain.toml`), which must match exactly, then by rust-cache's
@@ -76,7 +79,8 @@ branches in step with the lane table.
   workspace crates, which Cargo rebuilds). No `ci.yml` lane reads it. The
   Agent packaging lanes build thin LTO into their own
   `ci-v1-agent-package-<os>-*` caches, which only the nightly master run
-  saves. Signing, attestation and verification jobs restore nothing.
+  saves. The Agent's signing, attestation and verification jobs restore
+  nothing.
 
 ## Concurrency
 
@@ -241,7 +245,8 @@ release workflows use:
 | Research macOS, Linux, Android and iOS builds, which compile and sign (master and release); `rust-tests.yml`; the Agent's unsigned master builds | Blacksmith (`blacksmith-6vcpu-macos-26`, `blacksmith-8vcpu-ubuntu-2404`, `blacksmith-8vcpu-windows-2025`) |
 | Release `build-windows` | `maple-windows-2025-16core` |
 | Signed Research Windows master build; Agent Windows signing and verification | `windows-2025` |
-| Artifact verifiers, TestFlight submission, the Agent's signing and attestation, CodeQL, web and frontend evidence, proxy release rehearsal | Other GitHub-hosted runners |
+| Artifact verifiers, TestFlight submission, the Agent's signing and attestation, CodeQL, web and frontend evidence | Other GitHub-hosted runners |
+| Proxy release builds and their PR rehearsal (`proxy-rust.yml`) | GitHub-hosted Linux and Windows, Blacksmith macOS |
 | EIF builders that use FlakeHub | `blacksmith-16vcpu-ubuntu-2404-arm` |
 
 The Agent's signing and attestation, `windows-signing` jobs and every artifact
diff --git a/proxy/README.md b/proxy/README.md
index 069a2f5f1..47657c704 100644
--- a/proxy/README.md
+++ b/proxy/README.md
@@ -589,11 +589,11 @@ environment:
 The source lives under [`proxy/`](https://github.com/MaplePrivacyLabs/Maple/tree/master/proxy)
 in the Maple repository. The root `ci.yml` workflow runs locked Rust checks
 for proxy changes (lane `proxy`), supply-chain policy when the proxy's
-manifest, lockfile or `deny.toml` changes (`deps-proxy`), and non-publishing
-container builds: on pull requests only when `proxy/Dockerfile` or
-`.dockerignore` changes (`proxy-container`), and on `master` for both
-architectures whenever container inputs change (`proxy-container`,
-`proxy-container-arm64`). After every successful stable Maple Release, a separate serialized
+manifest, lockfile or `deny.toml`, or the Rust SDK manifest, changes
+(`deps-proxy`), and non-publishing container builds: on pull requests only
+when `proxy/Dockerfile` or `.dockerignore` changes (`proxy-container`), and
+on `master` for both architectures whenever container inputs change
+(`proxy-container`, `proxy-container-arm64`). After every successful stable Maple Release, a separate serialized
 publisher compares the checked-in proxy version with the previous stable Maple
 Release and rejects changed container inputs without a version bump. Version
 `0.3.3` remains the explicit unbackfilled migration baseline. A new or missing
diff --git a/services/opensecret/docs/nitro-deploy.md b/services/opensecret/docs/nitro-deploy.md
index 7eebe5c24..8566c768a 100644
--- a/services/opensecret/docs/nitro-deploy.md
+++ b/services/opensecret/docs/nitro-deploy.md
@@ -76,7 +76,8 @@ artifact's `pcr.json`; the deployment verifier rejects anything else.
 
 The root `ci.yml` `os-eif` lane builds dev/prod EIF candidates on Linux ARM64
 for same-repository PRs to `master` that change measured inputs (or carry the
-`ci:eif` label) without editing PCR approvals. The candidate job explicitly realizes and inspects the exact user
+`ci:eif` label) without editing PCR approvals. The candidate job explicitly
+realizes and inspects the exact user
 initramfs passed to the EIF builder, including when the final EIF comes from cache,
 resolves its entrypoint's CA path, and reports the archived bundle's hash and
 affected-root check alongside the EIF hash and PCRs. The archived CA bytes