docs(agents): say CI is real, Spark is private and no key is normal

.github/PULL_REQUEST_TEMPLATE.md

@@ -4,7 +4,9 @@
 
 ## How it was checked
 
-<!-- What you actually ran, and what it said. "Tests pass" is not a report. -->
+<!-- What you actually ran, and what it said. "Tests pass" is not a report.
+     CI (`check`) runs on this pull request whatever you ran; a suite that
+     skipped for want of a provider key is one line here, not a gap. -->
 
 ## Checklist
 
@@ -14,5 +16,4 @@
 - [ ] The manual knows about it — `internal/manual/chat/` updated in this change
       if a slash command, key, tool, default, limit or refusal moved. CLAUDE.md
       states the law; three gates fail the build if it is skipped.
-- [ ] No new line in `.github/known-red.txt`, or one with the reason above.
 - [ ] Only my own paths are staged — no `git add -A`.

CLAUDE.md

@@ -115,6 +115,41 @@ The repository is public now, so the free plan's former private-repository
 restriction no longer prevents branch rules. `.github/rulesets/` holds the
 intended rules; inspect live enforcement before assuming they were applied.
 
+## What you are running on — CI is real, Spark is not yours, no key is normal
+
+Agents keep reporting three absences that are not problems. None of them belongs
+in a summary or a pull request.
+
+- **CI exists and runs on every pull request.** It is GitHub Actions: `PR gate`
+  (`ci.yml`, whose `check` is the one required status) on every pull request and
+  every push to `dev`, `Full check` (`ci-full.yml`) nightly, `Release` on every
+  push. A failing `gh` is your credentials, not the repository: in a claude.ai
+  cloud container `gh` is installed but its `GH_TOKEN` does not authenticate, so
+  read runs, jobs and logs with the GitHub MCP tools (`actions_list`,
+  `get_job_logs`, `pull_request_read`). Never write "there is no CI" or "could not
+  check CI" without having tried them.
+- **Spark is the owner's own build machine**, reachable only from the owner's
+  laptop. Design notes say "measured on Spark" because that is where they were
+  measured — a record, never a step you owe. For everyone else its work is done by
+  CI: `touched packages` on every pull request and `Full check` nightly.
+- **No provider key is the normal state** away from the owner's laptop. The tagged
+  e2e suites, `TestRealRouter` and `internal/lane`'s `TestReal` SKIP green without
+  one, by design. Say "e2e not run: no key" once under "How it was checked" and
+  move on — do not ask for a key and do not go looking for one.
+
+**Spend the box on the change, not the ritual.** CI's `touched packages` runs the
+same selector as `make pr-ready`, on the same four-core runner size, in parallel
+legs, and it blocks the merge — so running it twice buys nothing.
+
+| When | Run |
+| --- | --- |
+| while editing | `make test-focus PKGS=… RUN=…` on the tests you wrote or touched |
+| before every push | `make test-quick` — build, vet, fmt, corpora, change entry, manual gates, laws; about a minute and a half warm, seven in a fresh cloud container (the first module download and build) |
+| before the pull request, on the owner's laptop | `make pr-ready` (below) |
+| before the pull request, in a cloud container | `make test-quick` plus your focused tests; then push and let `touched packages` be the full proof |
+| after the push | read `check` through the GitHub MCP tools; a red `touched packages` is yours to read before anything else |
+| never as routine | `make check`, `make test-e2e`, bare `go test ./...`, a full `tui3` or `session` suite |
+
 ## Build and ship — the owner's standing orders
 
 - **Always build with `make build`**, which writes `bin/codeaf`. Never a bare
@@ -139,8 +174,8 @@ run `make check`, bare `go test ./...`, or a full `go test ./internal/tui3` /
 `./internal/session` as the merge ritual — those thrash the box and are not what
 the pull-request gate demands. Edit with `make test-focus`; prove the change
 with `make test-touched` or `make pr-ready`. `make check` remains the full-tree
-build, test and size ritual for Spark, staging, or an intentional full laptop
-run. Concurrent full runs of `tui3` or `session` share one per-box lock so two
+build, test and size ritual for staging, the owner's Spark box, or an
+intentional full laptop run. Concurrent full runs of `tui3` or `session` share one per-box lock so two
 agents cannot stack those binaries. The performance laws those targets enforce —
 and the rule that changing any cap changes the doc in the same commit — are in
 [PERF.md](PERF.md).

docs/changes/unreleased/1884-agents-ci-spark-keys.md

@@ -0,0 +1,20 @@
+---
+kind: internal
+title: the agent guide says CI is real, Spark is private, and no provider key is normal
+pr: 1884
+surface: [docs]
+invalidates:
+  - >-
+    Agents in cloud sessions concluded the repository had no CI because `gh`
+    failed there. CI is GitHub Actions (`PR gate` on every pull request,
+    `Full check` nightly); `gh` fails only because the container's GH_TOKEN
+    does not authenticate, and the GitHub MCP tools read runs and logs.
+  - >-
+    "Run it on Spark" read as a step every contributor owed. Spark is the
+    owner's private machine; CI's `touched packages` and `Full check` do its
+    work for everyone else, and a cloud session need not repeat `make pr-ready`
+    before CI runs the same selector.
+  - >-
+    The pull-request template asked about `.github/known-red.txt`, deleted in
+    #1012; the line is gone.
+---

docs/rules/ci.md

@@ -178,7 +178,8 @@ saves remain useful even after a test failure. Hosted scheduling, cache hits
 and archive sizes still need an actual workflow run to confirm.
 
 This is pull-request parity, not the full-tree ritual. `make check` remains for
-Spark, staging, or an intentional full laptop run; it runs the whole test tree,
+staging, the owner's Spark box (a private machine; nobody else is expected to
+reach it), or an intentional full laptop run; it runs the whole test tree,
 builds the shipped binary and enforces its size budget.
 
 ## What the full gate checks