fix: point caching at setup-kapi's parse cache and update the kapi up examples

[asgeirf]

Merge after kapi 1.2.0 is published. The kapi up example relies on neokapi/setup-kapi@v1 installing a release with kapi up, which its latest default does only once 1.2.0 is stable.

Summary

• Caching. The action has no cache step. The README's "Caching" recipe restored .kapi/cache, a path kapi 1.2 never writes, so it cached nothing. The section now sends callers to setup-kapi's cache-tm (on by default for a project with a kapi.yaml, since setup-kapi v1.5.0), which carries kapi's parse cache at .kapi/work/cache/docs. It also says to leave the rest of .kapi/work/ out of any cache.
• Why the action itself caches nothing. setup-kapi already saves and restores that exact path, keyed by kapi version, ref, job and run. A second cache here would save the same directory under another key on every job. Anything wider (store.db, the unit state) changes what kapi status, kapi check --ship and kapi up report when restored, as fix: cache the parse cache kapi 1.2 writes, not retired paths setup-kapi#8 showed.
• kapi up example. It passes the credential a run needs: auth-token to setup-kapi for a recipe with a bowrain: block, or ANTHROPIC_API_KEY for a local run. Without either, kapi up on 1.2.0-rc32 exits 1 with no saved credentials found. The README also names the recipe's bowrain: block (not server:), the current gates (voice, terminology, rule-based checks), and the unit state kapi commit writes under .kapi/state/ (not .kapi-state.json).
• Tests.
  • KAPI_VERSION moves from 1.2.0-rc29 to 1.2.0-rc32, and the fixture recipe from fixture.kapi to kapi.yaml.
  • New test-parse-cache-save and test-parse-cache-restore jobs run the action through setup-kapi with project-dir: test/fixture. They check that the parse cache is where setup-kapi saves it, that nothing is at .kapi/cache, and that a later job finds the restored cache before the action runs.

Evidence

Local, kapi 1.2.0-rc32 on the action's own fixture:

• status, check --ship, up --plan and up --json never create .kapi/cache.
• With a kapi.yaml recipe they write .kapi/work/cache/docs/{index.db,parts-*.log} and .kapi/work/store.db.
• kapi up --plan --json still reports missingTarget, tmExact, aiRemaining and tokenEstimate, so the plan outputs keep working.

The must-fail run of main's README recipe and the green run of this branch are linked in a comment below.

Proposed tag

v1.5.1. No input, output or step of the action changes; this is a documentation and test fix.

Notes

action.yml still names "a brand, terminology, QA, or coverage gate" in its gate-unmet summary. It is left as is here, because changing the action's output text belongs in its own release.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VRid8i4qnuNfE7Lio73Uu4

[asgeirf]

Evidence from real runs.

This branch: Test run 34952598537 passed all nine jobs with kapi 1.2.0-rc32, including the new parse cache: written where setup-kapi saves it and parse cache: restored before the action runs.

Must fail, main's README recipe: run 34952636892, from the throwaway branch test/main-readme-cache-must-fail, followed the "Caching" section on main with kapi 1.2.0-rc32.

• Save job: kapi wrote only test/fixture/.kapi/work/store.db. The cache step then reported:

  Path Validation Error: Path(s) specified in the action for caching do(es) not exist, hence no cache is being saved.
  

• Restore job:

  Cache not found for input keys: kapi-cache-34952636892, kapi-cache-
  cache-hit=
  ##[error]Process completed with exit code 1.
  

  It failed on test -d test/fixture/.kapi/cache.

The recipe on main caches nothing on kapi 1.2, which is what this PR replaces.