@cbartens/bkit 5.5.1 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (425) hide show
  1. package/.bkit/README.md +167 -154
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +18 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +112 -102
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +167 -154
  11. package/.bkit/core/.bkit/authoring.md +747 -0
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +283 -195
  14. package/.bkit/core/.bkit/comparison.md +45 -43
  15. package/.bkit/core/.bkit/install.md +166 -95
  16. package/.bkit/core/.bkit/jsonl.md +339 -196
  17. package/.bkit/core/.bkit/pipeline.md +142 -145
  18. package/.bkit/core/.bkit/prompts.md +295 -264
  19. package/.bkit/core/.bkit/providers.md +460 -277
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +530 -256
  22. package/.bkit/core/.bkit/trackers.md +116 -65
  23. package/.bkit/core/.bkit/workflows.md +742 -618
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +6 -80
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +128 -130
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -94
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +96 -98
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +100 -103
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +141 -107
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +99 -97
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +122 -121
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +158 -101
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +114 -96
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +76 -97
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +123 -101
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +86 -99
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +76 -93
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +102 -95
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +165 -108
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -109
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +265 -113
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +119 -118
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +140 -111
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +111 -106
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +100 -99
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +107 -103
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +105 -105
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +134 -85
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +124 -125
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +99 -78
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -76
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -78
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +125 -93
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +97 -96
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +170 -98
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +207 -121
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +78 -95
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +163 -139
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +114 -96
  68. package/.bkit/core/docs/templates/bkit-plan.md +158 -281
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +104 -31
  71. package/.bkit/core/engine/checks/after/github.ts +95 -17
  72. package/.bkit/core/engine/checks/after/index.ts +21 -8
  73. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  74. package/.bkit/core/engine/checks/after/tools.ts +125 -123
  75. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  76. package/.bkit/core/engine/checks/before/env.ts +3 -3
  77. package/.bkit/core/engine/checks/before/files.ts +5 -4
  78. package/.bkit/core/engine/checks/before/index.ts +25 -1
  79. package/.bkit/core/engine/checks/before/repo.ts +208 -2
  80. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  81. package/.bkit/core/engine/checks/tips/catalogue.ts +82 -20
  82. package/.bkit/core/engine/checks/tips/detect.ts +66 -0
  83. package/.bkit/core/engine/checks/tips/index.ts +52 -11
  84. package/.bkit/core/engine/cli.ts +251 -130
  85. package/.bkit/core/engine/commands/analysis.ts +282 -199
  86. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  87. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  88. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  89. package/.bkit/core/engine/commands/comply.ts +77 -103
  90. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  91. package/.bkit/core/engine/commands/install/install.ts +57 -18
  92. package/.bkit/core/engine/commands/install/uninstall.ts +86 -55
  93. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  94. package/.bkit/core/engine/commands/land.ts +139 -18
  95. package/.bkit/core/engine/commands/lib.ts +381 -22
  96. package/.bkit/core/engine/commands/registry.ts +10 -2
  97. package/.bkit/core/engine/commands/setup/setup.ts +8 -7
  98. package/.bkit/core/engine/commands/stats.ts +260 -0
  99. package/.bkit/core/engine/commands/tips.ts +10 -5
  100. package/.bkit/core/engine/commands/workflow/branches.ts +2215 -176
  101. package/.bkit/core/engine/commands/workflow/challenge.ts +748 -0
  102. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  103. package/.bkit/core/engine/commands/workflow/context.ts +1249 -47
  104. package/.bkit/core/engine/commands/workflow/counters.ts +483 -95
  105. package/.bkit/core/engine/commands/workflow/decisions.ts +585 -0
  106. package/.bkit/core/engine/commands/workflow/disk.ts +238 -56
  107. package/.bkit/core/engine/commands/workflow/fids.ts +811 -33
  108. package/.bkit/core/engine/commands/workflow/issues.ts +413 -64
  109. package/.bkit/core/engine/commands/workflow/ledgers.ts +1333 -36
  110. package/.bkit/core/engine/commands/workflow/locks.ts +28 -2
  111. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +691 -0
  112. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  113. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  114. package/.bkit/core/engine/commands/workflow/prs.ts +178 -33
  115. package/.bkit/core/engine/commands/workflow/repo.ts +66 -8
  116. package/.bkit/core/engine/commands/workflow/roadmap.ts +72 -22
  117. package/.bkit/core/engine/commands/workflow/run-facts.ts +492 -0
  118. package/.bkit/core/engine/commands/workflow/runs.ts +827 -79
  119. package/.bkit/core/engine/commands/workflow/runtime.ts +25 -1
  120. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  121. package/.bkit/core/engine/commands/workflow/status.ts +329 -33
  122. package/.bkit/core/engine/commands/workflow/step-table.ts +381 -0
  123. package/.bkit/core/engine/commands/workflow/steps.ts +841 -105
  124. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  125. package/.bkit/core/engine/commands/workflow/summary.ts +544 -0
  126. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  127. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  128. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  129. package/.bkit/core/engine/commands/workflow/tests.ts +2124 -330
  130. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  131. package/.bkit/core/engine/commands/workflow/workflows.ts +1197 -235
  132. package/.bkit/core/engine/commands/workflow/worktrees.ts +543 -24
  133. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  134. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  135. package/.bkit/core/engine/install/manifest.ts +67 -17
  136. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  137. package/.bkit/core/engine/install/modules/cloud.ts +24 -16
  138. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  139. package/.bkit/core/engine/install/modules/core.ts +1196 -45
  140. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  141. package/.bkit/core/engine/install/modules/opencode.ts +18 -6
  142. package/.bkit/core/engine/install/template-notes.ts +130 -0
  143. package/.bkit/core/engine/install/version-file.ts +9 -4
  144. package/.bkit/core/engine/install/write.ts +5 -0
  145. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  146. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  147. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  148. package/.bkit/core/engine/ledgers/status.ts +249 -21
  149. package/.bkit/core/engine/ledgers/telemetry.ts +1397 -253
  150. package/.bkit/core/engine/render/hosts.ts +118 -14
  151. package/.bkit/core/engine/render/models.ts +12 -0
  152. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  153. package/.bkit/core/engine/shared/branches.ts +4 -1
  154. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  155. package/.bkit/core/engine/shared/egress.ts +8 -1
  156. package/.bkit/core/engine/shared/json.ts +25 -7
  157. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  158. package/.bkit/core/engine/shared/settings.ts +243 -31
  159. package/.bkit/core/engine/shared/text.ts +361 -0
  160. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  161. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  162. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  163. package/.bkit/core/engine/tools/instructions-sources.ts +832 -0
  164. package/.bkit/core/engine/tools/instructions.ts +1802 -0
  165. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  166. package/.bkit/core/hooks/gateguard-engine.js +54 -29
  167. package/.bkit/core/hooks/guardrails-shell.js +4 -5
  168. package/.bkit/core/hooks/guardrails-tiers.js +10 -4
  169. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  170. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  171. package/.bkit/core/hooks/readguard-engine.js +29 -10
  172. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  173. package/.bkit/core/prompts/bkit-audit-generate.md +202 -94
  174. package/.bkit/core/prompts/bkit-build-challenge-1.md +76 -34
  175. package/.bkit/core/prompts/bkit-build-challenge-2.md +85 -38
  176. package/.bkit/core/prompts/bkit-build-install-skills.md +50 -28
  177. package/.bkit/core/prompts/bkit-build-plan-convert.md +85 -0
  178. package/.bkit/core/prompts/bkit-build-plan-current.md +59 -36
  179. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +101 -36
  180. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  181. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  182. package/.bkit/core/prompts/bkit-build-plan-verify.md +104 -43
  183. package/.bkit/core/prompts/bkit-debug-abort-handover.md +47 -32
  184. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +109 -57
  185. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +65 -39
  186. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +53 -31
  187. package/.bkit/core/prompts/bkit-debug-failure-soak.md +65 -34
  188. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +46 -31
  189. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +45 -31
  190. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +43 -30
  191. package/.bkit/core/prompts/bkit-design-generate.md +80 -46
  192. package/.bkit/core/prompts/bkit-design-organise.md +83 -32
  193. package/.bkit/core/prompts/bkit-design-review-1.md +70 -50
  194. package/.bkit/core/prompts/bkit-design-review-2.md +65 -46
  195. package/.bkit/core/prompts/bkit-design-spike.md +64 -40
  196. package/.bkit/core/prompts/bkit-design-update.md +53 -28
  197. package/.bkit/core/prompts/bkit-plan-generate.md +101 -29
  198. package/.bkit/core/prompts/bkit-plan-review-1.md +78 -41
  199. package/.bkit/core/prompts/bkit-plan-review-2.md +78 -35
  200. package/.bkit/core/prompts/bkit-plan-scope-check.md +116 -0
  201. package/.bkit/core/prompts/bkit-plan-update.md +86 -31
  202. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +94 -50
  203. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +91 -41
  204. package/.bkit/core/prompts/bkit-ship-update-docs.md +45 -24
  205. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +65 -49
  206. package/.bkit/core/prompts/bkit-utility-update-decisions.md +87 -42
  207. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +81 -37
  208. package/.bkit/core/prompts/bkit-utility-update-documentation.md +43 -25
  209. package/.bkit/core/prompts/bkit-utility-update-failures.md +84 -37
  210. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +88 -42
  211. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +92 -39
  212. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -60
  213. package/.bkit/core/workflows/bkit-auto.md +89 -58
  214. package/.bkit/core/workflows/bkit-build.md +967 -517
  215. package/.bkit/core/workflows/bkit-debug.md +555 -387
  216. package/.bkit/core/workflows/bkit-design.md +319 -283
  217. package/.bkit/core/workflows/bkit-plan.md +319 -342
  218. package/.bkit/core/workflows/bkit-ship.md +525 -328
  219. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  220. package/.bkit/shared/.bkit/.env.example +2 -2
  221. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  222. package/.bkit/shared/.claude/settings.json +14 -0
  223. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  224. package/.bkit/shared/.codex/hooks.json +20 -0
  225. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  226. package/.bkit/shared/.cursor/mcp.json +1 -1
  227. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  228. package/.bkit/shared/.gitattributes +1 -1
  229. package/.bkit/shared/.mcp.json +1 -1
  230. package/.bkit/shared/.opencode/opencode.json +12 -1
  231. package/.bkit/shared/CLAUDE.md +6 -2
  232. package/.bkit/shared/GEMINI.md +5 -2
  233. package/.bkit/shared/docs/architecture.md +4 -7
  234. package/.bkit/shared/docs/data-schema.md +4 -7
  235. package/.bkit/shared/docs/deployments.md +241 -168
  236. package/.bkit/shared/docs/design.md +11 -12
  237. package/.bkit/shared/docs/noise.md +8 -7
  238. package/.bkit/shared/docs/observability.md +5 -8
  239. package/.bkit/shared/docs/security.md +35 -17
  240. package/.bkit/shared/docs/setup.md +29 -18
  241. package/.bkit/shared/docs/technology.md +3 -6
  242. package/.bkit/shared/docs/testing.md +289 -174
  243. package/.bkit/shared/gitignore +6 -2
  244. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  245. package/.bkit/templates/.cursor/Dockerfile +12 -8
  246. package/.bkit/templates/.cursor/environment.json +1 -1
  247. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  248. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +45 -12
  249. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  250. package/.bkit/templates/.github/renovate.json5 +34 -6
  251. package/.bkit/templates/.github/workflows/bkit-ci.yml +54 -51
  252. package/.bkit/templates/.github/workflows/bkit-cloud.yml +34 -33
  253. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  254. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  255. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  256. package/.bkit/templates/.husky/pre-commit +2 -2
  257. package/.bkit/templates/.husky/pre-push +96 -36
  258. package/.bkit/templates/.prettierignore +6 -0
  259. package/.bkit/templates/.vale.ini +27 -27
  260. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  261. package/.bkit/templates/context/bkit-expo.md +70 -52
  262. package/.bkit/templates/context/bkit-github.md +93 -56
  263. package/.bkit/templates/context/bkit-inngest.md +21 -15
  264. package/.bkit/templates/context/bkit-maestro.md +22 -16
  265. package/.bkit/templates/context/bkit-playwright.md +23 -17
  266. package/.bkit/templates/context/bkit-resend.md +12 -10
  267. package/.bkit/templates/context/bkit-sentry.md +30 -20
  268. package/.bkit/templates/context/bkit-serena.md +8 -7
  269. package/.bkit/templates/context/bkit-stripe.md +14 -13
  270. package/.bkit/templates/context/bkit-supabase.md +16 -13
  271. package/.bkit/templates/context/bkit-tavily.md +14 -11
  272. package/.bkit/templates/context/bkit-vercel.md +27 -18
  273. package/.bkit/templates/docs/capabilities.md +15 -14
  274. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  275. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  276. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  277. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  278. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  279. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  280. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  281. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  282. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  283. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  284. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  285. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +10 -2
  286. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  287. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  288. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  289. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  290. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  291. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  292. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  293. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  294. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  295. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  296. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  297. package/.bkit/templates/slop-scan.config.json +9 -2
  298. package/CHANGELOG.md +231 -0
  299. package/README.md +278 -89
  300. package/dist/checks/after/auth.js +36 -33
  301. package/dist/checks/after/ci-yml.js +91 -30
  302. package/dist/checks/after/github.js +91 -17
  303. package/dist/checks/after/index.js +22 -11
  304. package/dist/checks/after/suppression.js +8 -5
  305. package/dist/checks/after/tools.js +111 -114
  306. package/dist/checks/before/context-fetch.js +218 -33
  307. package/dist/checks/before/env.js +3 -3
  308. package/dist/checks/before/files.js +5 -3
  309. package/dist/checks/before/index.js +20 -3
  310. package/dist/checks/before/repo.js +197 -2
  311. package/dist/checks/status-holes.js +739 -114
  312. package/dist/checks/tips/catalogue.js +70 -19
  313. package/dist/checks/tips/detect.js +62 -0
  314. package/dist/checks/tips/index.js +51 -9
  315. package/dist/cli.js +234 -124
  316. package/dist/commands/analysis.js +174 -141
  317. package/dist/commands/ci/ci.js +302 -25
  318. package/dist/commands/ci/pins.js +142 -0
  319. package/dist/commands/ci/push-gate.js +194 -0
  320. package/dist/commands/comply.js +54 -91
  321. package/dist/commands/install/doctor.js +2 -2
  322. package/dist/commands/install/install.js +50 -19
  323. package/dist/commands/install/uninstall.js +82 -55
  324. package/dist/commands/install/upgrade.js +21 -11
  325. package/dist/commands/land.js +137 -17
  326. package/dist/commands/lib.js +295 -21
  327. package/dist/commands/registry.js +10 -2
  328. package/dist/commands/setup/setup.js +8 -7
  329. package/dist/commands/stats.js +175 -0
  330. package/dist/commands/tips.js +7 -3
  331. package/dist/commands/workflow/branches.js +1873 -152
  332. package/dist/commands/workflow/challenge.js +609 -0
  333. package/dist/commands/workflow/completeness.js +97 -0
  334. package/dist/commands/workflow/context.js +1045 -46
  335. package/dist/commands/workflow/counters.js +385 -86
  336. package/dist/commands/workflow/decisions.js +484 -0
  337. package/dist/commands/workflow/disk.js +214 -56
  338. package/dist/commands/workflow/fids.js +706 -33
  339. package/dist/commands/workflow/issues.js +349 -59
  340. package/dist/commands/workflow/ledgers.js +1123 -37
  341. package/dist/commands/workflow/locks.js +26 -2
  342. package/dist/commands/workflow/plan-blocks.js +501 -0
  343. package/dist/commands/workflow/plan-versions.js +22 -0
  344. package/dist/commands/workflow/plans.js +205 -0
  345. package/dist/commands/workflow/prs.js +154 -35
  346. package/dist/commands/workflow/repo.js +58 -8
  347. package/dist/commands/workflow/roadmap.js +58 -23
  348. package/dist/commands/workflow/run-facts.js +421 -0
  349. package/dist/commands/workflow/runs.js +670 -72
  350. package/dist/commands/workflow/runtime.js +15 -1
  351. package/dist/commands/workflow/skills.js +1 -0
  352. package/dist/commands/workflow/status.js +282 -34
  353. package/dist/commands/workflow/step-table.js +308 -0
  354. package/dist/commands/workflow/steps.js +703 -96
  355. package/dist/commands/workflow/summary-findings.js +117 -0
  356. package/dist/commands/workflow/summary.js +388 -0
  357. package/dist/commands/workflow/tasks.js +378 -0
  358. package/dist/commands/workflow/test-blocks.js +231 -0
  359. package/dist/commands/workflow/tests-changed.js +172 -0
  360. package/dist/commands/workflow/tests.js +1695 -305
  361. package/dist/commands/workflow/tracker.js +983 -0
  362. package/dist/commands/workflow/workflows.js +1014 -222
  363. package/dist/commands/workflow/worktrees.js +432 -26
  364. package/dist/install/cloud-env.js +233 -99
  365. package/dist/install/context-ci-workflow.js +85 -0
  366. package/dist/install/manifest.js +64 -17
  367. package/dist/install/modules/antigravity.js +3 -2
  368. package/dist/install/modules/cloud.js +25 -16
  369. package/dist/install/modules/codex.js +12 -2
  370. package/dist/install/modules/core.js +1090 -48
  371. package/dist/install/modules/cursor.js +6 -6
  372. package/dist/install/modules/opencode.js +13 -7
  373. package/dist/install/template-notes.js +116 -0
  374. package/dist/install/version-file.js +9 -4
  375. package/dist/ledgers/compact.js +87 -0
  376. package/dist/ledgers/journal.js +233 -0
  377. package/dist/ledgers/migrate.js +81 -0
  378. package/dist/ledgers/status.js +176 -13
  379. package/dist/ledgers/telemetry.js +1010 -125
  380. package/dist/render/hosts.js +104 -14
  381. package/dist/render/models.js +12 -0
  382. package/dist/shared/bkit-latest.js +26 -4
  383. package/dist/shared/branches.js +3 -1
  384. package/dist/shared/dep-updater.js +49 -0
  385. package/dist/shared/egress.js +8 -1
  386. package/dist/shared/json.js +20 -7
  387. package/dist/shared/package-manager.js +6 -0
  388. package/dist/shared/settings.js +181 -24
  389. package/dist/shared/text.js +333 -0
  390. package/dist/shared/timeouts.js +2 -0
  391. package/dist/tools/cli-doc.js +97 -0
  392. package/dist/tools/grammar-density.js +183 -0
  393. package/dist/tools/instructions-sources.js +720 -0
  394. package/dist/tools/instructions.js +1623 -0
  395. package/package.json +156 -51
  396. package/.bkit/core/.bkit/lite.md +0 -73
  397. package/.bkit/core/engine/commands/harvest.ts +0 -459
  398. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -166
  399. package/.bkit/core/engine/tools/wording.ts +0 -748
  400. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  401. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  402. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  403. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -76
  404. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  405. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  406. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  407. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  408. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  409. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  410. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  411. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  412. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  413. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  414. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  415. package/dist/commands/harvest.js +0 -353
  416. package/dist/commands/workflow/workstreams.js +0 -143
  417. package/dist/tools/wording.js +0 -680
  418. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  419. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  420. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  421. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  422. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  423. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  424. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  425. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -1,73 +1,75 @@
1
- # Cloud agent environments — Claude Code on the web + Cursor Cloud Agents + opencode
1
+ # Cloud agent environments — Claude on the web + Codex Cloud + Cursor Cloud Agents + OpenCode
2
2
 
3
3
  {{BKIT_MANAGED_MARKER}}
4
4
 
5
5
  > [!CAUTION]
6
- > **Purpose:** Canonical reference for Claude Code on the web (mobile / web), Cursor Cloud Agents, and opencode cloud runners. Claude + opencode → **GitHub** tracker (unified `bkit-cloud.yml`); Cursor → **Linear**; **Jira** → local runs only (no Jira-side cloud trigger). Not interchangeable per repo — pick agent matching your tracker (see § Cloud-agent support matrix).
6
+ > **Purpose:** The canonical reference for Claude on the web (mobile / web), Codex Cloud, Cursor Cloud Agents and OpenCode cloud runners. Environments do not depend on the tracker: every generated `<host>/bkit-cloud.md` carries the same env block (`BKIT_GH_TOKEN` plus whatever `.envrc` resolves, tracker keys included) for any tracker. Dispatch pairs each agent with one tracker: Claude and OpenCode with GitHub (one unified `bkit-cloud.yml`), and Cursor with Linear. Jira and Codex Cloud have no bkit dispatch, so you launch those runs by hand (§ Cloud-agent support matrix).
7
7
  >
8
8
  > **Rules:**
9
9
  >
10
- > - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
11
- > - Describe current state / rules, not reasons / history; state what to do, not why.
12
- > - Ships to consumers: describe the current setup only. NEVER an internal identifier (tracker issue number, ledger key, review-finding id) and NEVER project history — decisions belong in `docs/decisions.jsonl`, incidents in `docs/knowledge.jsonl`.
13
- > - Claude env config → Claude app; Cursor → `.cursor/` in-repo. Both have in-repo SessionStart guard.
14
- > - Update when either cloud's pre-installed toolchain or default allowlist changes. Sources: `code.claude.com/docs/en/claude-code-on-the-web` + `cursor.com/docs/cloud-agent/setup`.
10
+ > - Follow `.bkit/authoring.md` § All Agent-Read Files and § Docs when you edit this file.
11
+ > - This file ships to every project that installs bkit. Describe the current setup only.
12
+ > - Leave out internal labels, such as tracker issue numbers, ledger keys and review-finding ids, and leave out project history. Decisions go in `docs/decisions.jsonl`, and incidents go in `docs/knowledge.jsonl`.
13
+ > - Claude's environment config lives in the Claude app, and Cursor's lives in `.cursor/` in the repo. Both have an in-repo SessionStart guard.
14
+ > - Update this file when any of the three clouds' pre-installed toolchain or default allowlist changes. The sources are `code.claude.com/docs/en/claude-code-on-the-web`, `cursor.com/docs/cloud-agent/setup` and `learn.chatgpt.com/docs/environments/cloud-environments`.
15
15
 
16
16
  ## Scope
17
17
 
18
- > **Host-delta matrix:** `.bkit/providers.md` § Runtime environment (cloud agents). Canonical "what differs" for Claude vs Cursor cloud agents. This file = paste-in setup recipe, alignment guarantees, sharing-across-repos pattern, caveats.
18
+ > **Host-delta matrix:** `.bkit/providers.md` § Runtime environment (cloud agents) is the canonical home for what differs between Claude and Cursor cloud agents. This file holds the paste-in setup recipe, the alignment guarantees, the pattern for sharing across repos, and the caveats.
19
19
 
20
20
  ## Cloud-agent support matrix (read first)
21
21
 
22
- Three cloud stacks — each agent pairs with one tracker. Pick row for agent you run:
22
+ Dispatch pairs each agent with one tracker, while the environments (`<host>/bkit-cloud.md`) work with any tracker. Pick the row for the agent you run:
23
23
 
24
24
  <!-- prettier-ignore -->
25
25
  | Agent (the agent, not the editor) | Ways to launch a cloud agent | Tracker | not supported |
26
26
  | --- | --- | --- | --- |
27
- | **Claude Code** (terminal — any IDE host) | **A)** Claude iOS / desktop app → Claude-on-web env (`.claude/hooks/bkit-cloud-bootstrap.sh` + the env defined in `claude.ai/code`) · **B)** manual `workflow_dispatch` on `bkit-cloud.yml` (pick phase + issue) · **C)** GitHub CI pass/fail → `bkit-cloud.yml` claude job · **D)** `@claude` mention on a GitHub issue / PR (`/install-github-app` required — **base requirement** for `cloud=claude`) | **GitHub** | **Linear** |
28
- | **opencode** (GitHub runner) | **A)** manual `workflow_dispatch` on `bkit-cloud.yml` (pick phase + issue) · **B)** GitHub CI pass/fail → `bkit-cloud.yml` opencode job (requires `OPENCODE_PROVIDER_KEY` secret) · **C)** reactive `/oc` comment handler (self-installed, not bkit — see § Reactive comment handlers) | **GitHub** | **Linear** |
29
- | **Cursor** (native agent) | **A)** Cursor's built-in cloud-agent launch · **B)** Cursor's GitHub integration on PR events (CI pass/fail) · **C)** Linear → Cursor integration | **Linear** (+ GitHub PR events) | **GitHub Projects / Issues** |
27
+ | **Claude** (terminal — any IDE host) | **A)** Claude iOS / desktop app → Claude-on-web env (`.claude/hooks/bkit-cloud-bootstrap.sh` + the env defined in `claude.ai/code`) · **B)** manual `workflow_dispatch` on `bkit-cloud.yml` (pick phase + issue) · **C)** GitHub CI pass / fail → `bkit-cloud.yml` claude job · **D)** `@claude` mention on a GitHub issue / PR (needs `/install-github-app`, the base requirement for `cloud=claude`) | GitHub | Linear |
28
+ | **Codex** (Codex Cloud) | **A)** ChatGPT Codex → task on the env from `.codex/bkit-cloud.md` (manual; no bkit dispatch) | any (tracker MCP + env block) | bkit-triggered runs |
29
+ | **Cursor** (native agent) | **A)** Cursor's built-in cloud-agent launch · **B)** Cursor's GitHub integration on PR events (CI pass / fail) · **C)** Linear → Cursor integration | Linear (+ GitHub PR events) | GitHub Projects / Issues |
30
+ | **OpenCode** (GitHub runner) | **A)** manual `workflow_dispatch` on `bkit-cloud.yml` (pick phase + issue) · **B)** GitHub CI pass / fail → `bkit-cloud.yml` OpenCode job (requires `OPENCODE_PROVIDER_KEY` secret) · **C)** reactive `/oc` comment handler (self-installed, not bkit's: § Reactive comment handlers) | GitHub | Linear |
30
31
 
31
- **Unified file — additive coexistence:** Claude + opencode share one `bkit-cloud.yml`: a `context` job resolves the phase once, then two runner jobs, each runtime-gated on its credential (claude: `ANTHROPIC_API_KEY` secret or federation variables; opencode: `OPENCODE_PROVIDER_KEY`). Both jobs can fire on same CI event — both credentials → both agents; one → one agent. Cursor separate (no GH Action; native triggers). **Cursor cloud ↔ Linear.**
32
+ **Unified file — additive coexistence:** Claude and OpenCode share one `bkit-cloud.yml`. A `context` job resolves the phase once, and two runner jobs follow, each gated at run time on its own credential: the claude job on the `ANTHROPIC_API_KEY` secret or the federation variables, and the OpenCode job on `OPENCODE_PROVIDER_KEY`. Both jobs can fire on the same CI event. With both credentials set, both agents run, and with one set, only that agent runs. Cursor is separate: it has no GitHub Action and uses its native triggers. Cursor cloud pairs with Linear.
32
33
 
33
- **Manual dispatch (Claude or opencode, path A):** GitHub → **Actions** → **bkit-cloud** → **Run workflow** → `phase` (`ship` / `debug` / `design` / `plan` / `build`) + `issue`. On-demand/smoke-test for `design` / `plan` / `build`; `ship` / `debug` normally CI-fired. Dispatched `design` runs headless (`runtimeHeadless` = true on a GitHub runner): Grill asks nothing, records each recommended answer as `Assumed, not confirmed`, and records the draft acceptance scenario as not reviewed by a human. Dispatched `/bkit-auto` orchestrator → matching phase skill → brief from GitHub issue (MCP).
34
+ **Manual dispatch (Claude or OpenCode, path A):** GitHub → **Actions** → **bkit-cloud** → **Run workflow**, then pick `phase` (`ship` / `debug` / `design` / `plan` / `build`) and `issue`. Use it on demand, or as a smoke test, for `design` / `plan` / `build`. `ship` / `debug` normally fire from CI. A dispatched `design` runs headless (`runtimeHeadless` = true on a GitHub runner): Grill asks nothing, records each recommended answer as `Assumed, not confirmed`, and records the draft acceptance scenario as not reviewed by a human. A dispatched `/bkit-auto` orchestrator hands off to the matching phase skill, which takes its brief from the GitHub issue through the MCP.
34
35
 
35
36
  ### Reactive comment handlers (`claude.yml` + `opencode.yml`) — separately managed, not bkit
36
37
 
37
- `.github/workflows/claude.yml` (the `@claude` handler) and `.github/workflows/opencode.yml` (the `/oc` handler) are **not bkit's**. Each is generated — and re-generated — by its own vendor tool; bkit ships **no template** for either, and `bkit install` / `upgrade` never writes, rewrites, or drift-gates them (both are absent from the bkit manifest). They coexist **additively** with `bkit-cloud.yml` (the CI-completion + `workflow_dispatch` lane, which bkit ships as a template): a comment fires the vendor handler; a CI run fires `bkit-cloud.yml`.
38
+ `.github/workflows/claude.yml` (the `@claude` handler) and `.github/workflows/opencode.yml` (the `/oc` handler) are not bkit's. Each is generated, and regenerated, by its own vendor tool. bkit ships no template for either, and `bkit install` / `upgrade` never writes, rewrites or drift-gates them: neither is in the bkit manifest. They coexist additively with `bkit-cloud.yml`, the CI-completion and `workflow_dispatch` lane, which bkit ships as a template. A comment fires the vendor handler, and a CI run fires `bkit-cloud.yml`.
38
39
 
39
40
  <!-- prettier-ignore -->
40
41
  | Reactive handler (not bkit) | Installed by (vendor tool) | Auth | Launch a bkit phase |
41
42
  | --- | --- | --- | --- |
42
- | `.github/workflows/claude.yml` | `/install-github-app` (Claude Code CLI → official Claude GitHub App) | OIDC as the App (`bkit-cloud.yml` grants `id-token: write`; no App installed → OIDC error at boot) | comment `@claude /bkit-plan` (or any phase) on an issue / PR |
43
- | `.github/workflows/opencode.yml` | `opencode github install` (opencode CLI) | your provider key (`BKIT_OPENCODE_API_KEY` / `BKIT_OPENROUTER_API_KEY` / etc.) — no App, no OIDC | comment `/oc` or `/opencode` on an issue / PR |
43
+ | `.github/workflows/claude.yml` | `/install-github-app` (Claude CLI → official Claude GitHub App) | OIDC as the App (`bkit-cloud.yml` grants `id-token: write`; no App installed → OIDC error at boot) | comment `@claude /bkit-plan` (or any phase) on an issue / PR |
44
+ | `.github/workflows/opencode.yml` | `opencode github install` (OpenCode CLI) | your provider key (`BKIT_OPENCODE_API_KEY` / `BKIT_OPENROUTER_API_KEY` / etc.) — no App, no OIDC | comment `/oc` or `/opencode` on an issue / PR |
44
45
 
45
- **You maintain these files — bkit does not.** `opencode.yml` hardcodes a `model:` + provider-secret `env:`; keep both in sync with your installed opencode provider. `bkit check` + postinstall raise a non-fatal advisory when they drift (hand-fix — bkit will not rewrite the file). No equivalent check for `claude.yml` (its `@claude` handler is provider-fixed to Claude). For Claude, the `@claude` path is the **base requirement** for `cloud=claude` — enable with `bkit install --auto=claude` (GitHub tracker only); the App also gives the runner a GitHub identity for the `mcp__github__*` surface.
46
+ You maintain these files, not bkit. `opencode.yml` hardcodes a `model:` and a provider-secret `env:`. Keep both in sync with your installed OpenCode provider. `bkit check` and postinstall raise a non-fatal advisory when they drift. Fix the file by hand, because bkit will not rewrite it. `claude.yml` has no equivalent check, because its `@claude` handler is fixed to Claude as its provider. For Claude, the `@claude` path is the base requirement for `cloud=claude`. Enable it with `bkit install --auto=claude`, which works with the GitHub tracker only. The App also gives the runner a GitHub identity for the `mcp__github__*` surface.
46
47
 
47
48
  ## What lives where (orient first)
48
49
 
49
50
  <!-- prettier-ignore -->
50
51
  | Configuration | Lives in the repo (bkit-managed) | Lives in the online dashboard (manual, one-time) |
51
52
  | --- | --- | --- |
52
- | **Claude Code on the web** | `.claude/hooks/bkit-preflight.sh` (tracker opt-in guard) + `.claude/hooks/bkit-cloud-bootstrap.sh` (per-session install — copy-and-own template, adopt it from `.bkit/templates/`) | `claude.ai/code` → environment selector → **+ Add environment**: name, **setup script** (paste from § Setup script), **environment variables** (`BKIT_GH_TOKEN` — Claude pairs with the **GitHub** tracker, so no `BKIT_LINEAR_API_KEY`), **network access** (`Trusted`) |
53
- | **Cursor Cloud Agents** | `.cursor/Dockerfile` + `.cursor/environment.json` (`install` / `start` / `terminals[]` / `env`), both copied from bkit's templates and owned by the repo, + `.cursor/hooks.json` (wires preflight `failClosed: true`) + `.cursor/hooks/bkit-preflight.sh` (Linear guard) | Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents`) → your environment → **Secrets** tab, as **Runtime Secret**s: `BKIT_LINEAR_API_KEY`, `BKIT_GH_TOKEN`. (`LINEAR_ISSUE_ID` injected per-session by the integration — don't hardcode.) |
53
+ | **Claude on the web** | `.claude/hooks/bkit-preflight.sh` (tracker opt-in guard) + `.claude/hooks/bkit-cloud-bootstrap.sh` (per-session install — copy-and-own template, adopt it from `.bkit/templates/`) | `claude.ai/code` → environment selector → **+ Add environment**: name, **setup script** (paste from § Setup script), **environment variables** (paste block from `.claude/bkit-cloud.md`), **network access** (`Custom`, list from the same doc) |
54
+ | **Codex Cloud** | `.codex/hooks.json` + `.codex/hooks/*` (unproven in cloud tasks — § Codex Cloud) + `.agents/skills/bkit-*` | ChatGPT → **Settings > Codex Cloud > Environments** → **Create environment**: repo, **Install script**, **Environment variables**, **Internet access** — all pasted from `.codex/bkit-cloud.md` |
55
+ | **Cursor Cloud Agents** | `.cursor/Dockerfile` + `.cursor/environment.json` (`install` / `start` / `terminals[]` / `env`), both copied from bkit's templates and owned by the repo, + `.cursor/hooks.json` (wires preflight `failClosed: true`) + `.cursor/hooks/bkit-preflight.sh` (Linear guard) | Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents`) → your environment → **Secrets** tab, as **Runtime Secret**s: paste block from `.cursor/bkit-cloud.md`. (The integration injects `LINEAR_ISSUE_ID` / `GITHUB_ISSUE_ID` per session, so don't hardcode them.) |
54
56
 
55
- **Rule of thumb:** env vars / auth tokens → online dashboard (out of git). Scripts / Dockerfile / install hooks → repo.
57
+ **Rule of thumb:** env vars and auth tokens go in the online dashboard, out of git. Scripts, the Dockerfile and install hooks go in the repo.
56
58
 
57
59
  **Alignment guarantees bkit enforces:**
58
60
 
59
- - Same Node (24.21.0, sha256-checked, from nodejs.org) on both clouds — web setup script and `.cursor/Dockerfile` carry the identical `NODE_VERSION` + `NODE_SHA256` pair.
60
- - Same vale version (3.9.1) pre-installed on both clouds.
61
- - pnpm via corepack on both. Pastes pre-warm bkit's pin (`10.34.4`), but corepack resolves **each repo's own `packageManager`** in-repo — one setup script serves any pnpm pin; pre-warm version not load-bearing.
62
- - gh CLI on both: web setup script installs a pinned, sha256-checked binary (`GH_VERSION`, same `github.com` release-download style as vale); GitHub-Actions runner ships pre-installed. Auth shared via `bkit-cloud-bootstrap.sh` (`gh auth login --with-token` with `BKIT_GH_TOKEN`, skipped when `GITHUB_TOKEN` already auths on runner).
63
- - Same opt-in-guard pattern — opt-in label `bkit:auto` — wrapped in `<!-- bkit:start --> ... <!-- bkit:end -->` (bkit-managed in consumer repos). Label `bkit:auto` on both trackers.
61
+ - Both clouds run the same Node (24.21.0, sha256-checked, from nodejs.org): the web setup script and `.cursor/Dockerfile` carry the identical `NODE_VERSION` + `NODE_SHA256` pair.
62
+ - Both clouds have the same vale version (3.9.1) pre-installed.
63
+ - Both get pnpm through corepack. The web setup script pre-warms the pnpm version in your `package.json` `packageManager`, and `.cursor/Dockerfile` pre-warms its `PNPM_VERSION` build argument. Inside the repo, corepack resolves the repo's own `packageManager` either way, so one setup script serves any pnpm pin, and the pre-warmed version only warms the cache.
64
+ - Both have the gh CLI. The web setup script installs a pinned, sha256-checked binary (`GH_VERSION`, downloaded from a `github.com` release the same way as vale), and the GitHub-Actions runner ships with it pre-installed. Auth is shared through `bkit-cloud-bootstrap.sh`, which runs `gh auth login --with-token` with `BKIT_GH_TOKEN` and skips it when `GITHUB_TOKEN` already authenticates on the runner.
65
+ - Both use the same opt-in guard pattern, keyed on the opt-in label `bkit:auto` and wrapped in `<!-- bkit:start --> ... <!-- bkit:end -->` (bkit-managed in consumer repos). The label is `bkit:auto` on both trackers.
64
66
 
65
67
  ## Background
66
68
 
67
- Both clouds run Ubuntu 24.04 (4 vCPU / 16 GB RAM / 30 GB disk class). Pre-installed inventories differ:
69
+ Both clouds run Ubuntu 24.04 (4 vCPU / 16 GB RAM / 30 GB disk class). What comes pre-installed differs:
68
70
 
69
71
  <!-- prettier-ignore -->
70
- | Pre-installed | Claude Code on the web | Cursor Cloud Agents (after bkit Dockerfile) |
72
+ | Pre-installed | Claude on the web | Cursor Cloud Agents (after bkit Dockerfile) |
71
73
  | --- | --- | --- |
72
74
  | Node | 20 + 22 — setup script adds 24 (checksum-pinned, into `/usr/local`, first on `PATH`) | 24 (template default, checksum-pinned; match your `engines.node` / `.nvmrc`) |
73
75
  | Package manager | pnpm + bun (latest) | pnpm (corepack-pinned in `.cursor/Dockerfile`; each repo's `packageManager` honored in-repo) |
@@ -75,90 +77,109 @@ Both clouds run Ubuntu 24.04 (4 vCPU / 16 GB RAM / 30 GB disk class). Pre-instal
75
77
  | Databases | Postgres 16, Redis 7 | Not installed (add to Dockerfile if needed) |
76
78
  | Docker | Yes (host engine) | N/A — we are inside Docker |
77
79
  | Utilities | git, jq, ripgrep | git, jq |
78
- | `gh` CLI | **Not pre-installed** — setup script adds it | Added via Dockerfile (pinned release tarball, sha256-checked) |
79
- | `vale` | **Not pre-installed** — setup script adds 3.9.1 | Added via Dockerfile (3.9.1) |
80
+ | `gh` CLI | Not pre-installed: the setup script adds it | Added via Dockerfile (pinned release tarball, sha256-checked) |
81
+ | `vale` | Not pre-installed: the setup script adds 3.9.1 | Added via Dockerfile (3.9.1) |
80
82
  | Playwright | Not pre-installed | Not installed (commented example in the consumer section of `.cursor/Dockerfile`) |
81
83
 
82
- Two halves of customisation:
84
+ Customisation comes in two halves:
83
85
 
84
- - **Cloud-side install** (one-time, cached): Claude → setup script in app. Cursor → `.cursor/Dockerfile`.
85
- - **Repo-side install** (per-session, lockfile-aware): Claude → `.claude/hooks/bkit-cloud-bootstrap.sh`. Cursor → `.cursor/environment.json` `install` field.
86
+ - **Cloud-side install** (one-time, cached): Claude uses the setup script in the app, and Cursor uses `.cursor/Dockerfile`.
87
+ - **Repo-side install** (per-session, lockfile-aware): Claude uses `.claude/hooks/bkit-cloud-bootstrap.sh`, and Cursor uses the `install` field of `.cursor/environment.json`.
86
88
 
87
- # Claude Code on the web
89
+ **Failed provision recipes:** Every host runs each `context-fetch:provision` recipe on its own. The Claude setup script and the Codex install script run them inline, and the Claude session hook and the Cursor `install` run them through `bkit context provision`. A failing recipe never fails setup. Setup names it, with its last error line, in the setup log and in the closing `cloud setup done` line, and lists it in `.bkit/.unavailable`, one `<name>: <reason>` line per recipe. The file is removed when no recipe fails. The Claude session hook prints that file into the session's context, and `.agents/rules.md` § Cloud setup gaps tells every agent to read it.
90
+
91
+ # Claude on the web
88
92
 
89
93
  > [!TIP]
90
- > **No manual copy needed.** `bkit install --claude` writes `.claude/bkit-cloud.md` — this recipe with repo env-var **values resolved from `.envrc`** (`unset`s dropped, `BKIT_ANTHROPIC_API_KEY` omitted to protect subscription billing). Open file, paste each block into Claude app. Gitignored (holds real secrets); regenerates on every install and upgrade. Reference below documents each field it fills.
94
+ > **No manual copy needed.** `bkit install --claude` writes `.claude/bkit-cloud.md`: this recipe, with the repo's env-var values resolved from `.envrc`. Variables that file `unset`s are dropped, and `BKIT_ANTHROPIC_API_KEY` is left out to protect subscription billing. Open the file and paste each block into the Claude app. The file is gitignored because it holds real secrets, and it regenerates on every install and upgrade. The reference below documents each field it fills.
91
95
 
92
96
  ## Where config lives
93
97
 
94
- Open `claude.ai/code` → environment selector → **+ Add environment**. Three surfaces: setup script (bash, root, once, snapshotted), environment variables (`.env` format, plaintext, visible to anyone with edit access), network access (`None` / `Trusted` / `Full` / `Custom`).
98
+ Open `claude.ai/code` → environment selector → **+ Add environment**. It has three surfaces: the setup script (bash, run as root, once, then snapshotted), environment variables (`.env` format, plaintext, visible to anyone with edit access) and network access (`None` / `Trusted` / `Full` / `Custom`).
95
99
 
96
100
  ## In-repo side
97
101
 
98
- - `.claude/hooks/bkit-preflight.sh` — Tracker opt-in guard. Skips silently when tracker issue ID env var unset (IDE sessions). Non-zero exit informational only on Claude (`SessionStart` cannot block); agent reads `HARD STOP` text from `additionalContext`.
99
- - `.claude/hooks/bkit-cloud-bootstrap.sh` — runs `pnpm install --frozen-lockfile` + `vale sync` when `CLAUDE_CODE_REMOTE=true`; then, through the just-installed bkit (`bkit runtime detect` gh probe, `bkit context list-blocks` provision recipes, read with `jq`), gh auth and context-fetch CLI provisioning — skipped with a loud log line when bkit or `jq` is missing. No-op locally.
100
- - Both registered in `.claude/settings.json` under `hooks.SessionStart`.
102
+ - `.claude/hooks/bkit-preflight.sh` — the tracker opt-in guard plus the rules-read advisory, as one JSON document (`.bkit/providers.md` § Rules-read advisory). When the tracker issue ID env var is unset, as in an IDE session, it prints the advisory alone and exits 0. On Claude a non-zero exit is informational only, because `SessionStart` cannot block. The agent reads the `HARD STOP` text from `additionalContext`.
103
+ - `.claude/hooks/bkit-cloud-bootstrap.sh` — when `CLAUDE_CODE_REMOTE=true`, runs `pnpm install --frozen-lockfile` and `vale sync`, then gh auth, then context-fetch CLI provisioning through the just-installed bkit (`bkit context provision`). When bkit is missing, it skips provisioning with a loud log line. A failed recipe's `.bkit/.unavailable` line goes to stdout, and so into the session's context. Locally the hook does nothing.
104
+ - Both are registered in `.claude/settings.json` under `hooks.SessionStart`.
101
105
 
102
- Ships with repo — don't paste into app.
106
+ These ship with the repo. Do not paste them into the app.
103
107
 
104
108
  ## What to paste into the Claude app
105
109
 
106
110
  ### Name
107
111
 
108
- Name environment **after the repo** — one env per repo, secrets isolated (§ Sharing across repos). Setup script identical across repos.
112
+ Name the environment after the repo: one environment per repo keeps secrets isolated (§ Sharing across repos). The setup script is identical across repos.
109
113
 
110
- Identical across repos: **setup-script body**, **network policy**, bkit **baseline token name** (`BKIT_GH_TOKEN`) — only values change. Rest of env-vars box is **this repo's own**, copied from env-var files per `.envrc` (§ Environment variables).
114
+ The setup-script body, the network policy and bkit's baseline token name (`BKIT_GH_TOKEN`) are identical across repos, and only the values change. The rest of the env-vars box is this repo's own, copied from the env-var files that `.envrc` follows (§ Tokens by session type).
111
115
 
112
116
  ### Network access
113
117
 
114
- Always `Custom` — the rendered list carries bkit's own shipped hosts (trackers, registries, agent + provider APIs, the search host a `context=web` block calls) whether or not the repo declares anything. Select **Custom**, tick **Also include default list of common package managers** (EXTENDS trusted defaults — package registries, GitHub, cloud SDKs — never replaces them), paste domains bkit renders into `.claude/bkit-cloud.md` § Network access into **Allowed domains**. Declare only what bkit cannot see: log-backend/API hosts the implicit CLI blocks reach (`vercel` / `gcloud`) plus app production + preview/dev domains — apex-only, expanded by `bkit install` to `<domain>` + `*.<domain>` and unioned with the derived set. Under `Trusted` those hosts unreachable → cloud `/bkit-debug` gets no runtime logs; e2e can't hit deployment.
118
+ Always choose `Custom`, because the rendered list carries bkit's own shipped hosts (trackers, registries, agent and provider APIs, and the search host a `context=web` block calls) whether or not the repo declares anything:
119
+
120
+ 1. Select **Custom**.
121
+ 2. Tick **Also include default list of common package managers**. It extends the trusted defaults (package registries, GitHub, cloud SDKs) and never replaces them.
122
+ 3. Paste the domains bkit renders into `.claude/bkit-cloud.md` § Network access into **Allowed domains**.
123
+
124
+ Declare only what bkit cannot see: the log-backend and API hosts that the implicit CLI blocks reach (`vercel` / `gcloud`), plus the app's production and preview / dev domains. Declare apex domains only. `bkit install` expands each one to `<domain>` + `*.<domain>` and unions them with the derived set. Under `Trusted` those hosts are unreachable, so a cloud `/bkit-debug` gets no runtime logs and e2e tests can't reach the deployment.
115
125
 
116
- No `allowed-domains` block still needs `Custom`: `Trusted` does not reach bkit's own tracker MCP, provider catalog or search hosts. Ticking **Also include default list of common package managers** keeps npm, the vale tarball on `objects.githubusercontent.com`, Docker Hub and PyPI. Raise to `Full` only for open-internet tasks.
126
+ A repo with no `allowed-domains` block still needs `Custom`, because `Trusted` does not reach bkit's own tracker MCP, provider catalog or search hosts. Ticking **Also include default list of common package managers** keeps npm, the vale tarball on `objects.githubusercontent.com`, Docker Hub and PyPI. Raise the setting to `Full` only for open-internet tasks.
117
127
 
118
128
  ### Setup script
119
129
 
120
- `bkit install` generates copy-paste-ready setup script into `.claude/bkit-cloud.md` § Setup script — resolved for this repo, with cache-bust line, base-tool installs, any `context-fetch:provision` recipes. **Paste that**, not hand-copied snippet: stale copy drifts (hard-pinned pnpm can seed version known to break `bkit` download; `apt install gh` unreliable — gh not in default repos).
130
+ `bkit install` generates a copy-paste-ready setup script into `.claude/bkit-cloud.md` § Setup script. It is resolved for this repo, with the cache-bust line, the base-tool installs and any `context-fetch:provision` recipes. Paste that, not a hand-copied snippet, because a stale copy drifts: a hard-pinned pnpm can seed a version known to break the `bkit` download, and `apt install gh` is unreliable because gh is not in the default repos.
121
131
 
122
- What it does and why split from in-repo hook:
132
+ What the script does, and why it is split from the in-repo hook:
123
133
 
124
- - **`# cache-bust <date>-<n>`** first line generator writes (`bkit install` / `bkit upgrade` re-stamp). Snapshot keyed on setup script exact text — only job is to change: new date (or bumped same-day counter) forces fresh snapshot on next paste, re-pulling any unpinned tool a `context-fetch:provision` recipe installs, plus base-image drift even when rest byte-identical. Leave in place — do not hand-edit.
125
- - **Base tools (Node, vale, gh, jq)** install once into snapshot from upstream releases, each pinned to a version and checked with `sha256sum -c` before it is unpacked or made executable (the `# renovate:` comment above each `*_VERSION` lets Renovate bump the pin) — Node 24 from the nodejs.org `linux-x64` tarball into `/usr/local`, then `/usr/local/bin` prepended to `PATH` so corepack and every later step run on it (bkit needs Node >=24; image ships 20 + 22); `gh` from the `cli/cli` release tarball (not `apt`), `jq` because `curl`-based context-fetch blocks pipe through it. Node, gh and vale pins match `.cursor/Dockerfile`. Binaries cloud lacks but laptop has — not repo-level hook.
126
- - **pnpm corepack pre-warm** seeds one pnpm into snapshot via `corepack enable` (no hard-pinned version). In-repo, corepack resolves repo's `packageManager` (fetching if differs) — one setup script serves any pnpm pin; pre-warm is warm cache.
127
- - `pnpm install` and `vale sync` **not** here — belong in `.claude/hooks/bkit-cloud-bootstrap.sh` for resumed sessions when lockfile/styles drifted; each repo installs own deps.
134
+ - **`# cache-bust <date>-<n>`** is the first line the generator writes, and `bkit install` / `bkit upgrade` re-stamp it. The snapshot is keyed on the setup script's exact text, so the line's only job is to change. A new date, or a bumped same-day counter, forces a fresh snapshot on the next paste. That re-pulls any unpinned tool a `context-fetch:provision` recipe installs, and picks up base-image drift, even when the rest of the script is byte-identical. Leave the line in place, and do not edit it by hand.
135
+ - **Base tools (Node, vale, gh, jq)** install once into the snapshot from upstream releases. Each is pinned to a version and checked with `sha256sum -c` before it is unpacked or made executable. The `# renovate:` comment above each `*_VERSION` lets Renovate bump the pin.
136
+ - Node 24 comes from the nodejs.org `linux-x64` tarball into `/usr/local`, and `/usr/local/bin` is prepended to `PATH` so corepack and every later step run on it. bkit needs Node >=24, and the image ships 20 + 22.
137
+ - `gh` comes from the `cli/cli` release tarball, not `apt`.
138
+ - `jq` is installed because `curl`-based context-fetch blocks pipe through it.
139
+ - The Node, gh and vale pins match `.cursor/Dockerfile`.
140
+ - These are binaries the cloud lacks but a laptop has, so they belong here, not in a repo-level hook.
141
+ - **pnpm corepack pre-warm** seeds one pnpm into the snapshot: `corepack enable && corepack prepare pnpm@<version> --activate`, with the version read from your `package.json` `packageManager`. With no `packageManager` pin, the line is a bare `corepack enable`. Inside the repo, corepack resolves the repo's `packageManager` and fetches it if it differs, so one setup script serves any pnpm pin. The pre-warm only warms the cache.
142
+ - `pnpm install` and `vale sync` are not here. They belong in `.claude/hooks/bkit-cloud-bootstrap.sh`, so a resumed session picks up a drifted lockfile or styles, and each repo installs its own deps.
128
143
 
129
- Keep total runtime under ~5 minutes or snapshot won't build.
144
+ Keep the total runtime under ~5 minutes, or the snapshot won't build.
130
145
 
131
146
  #### Workspace trust + auto-mode config
132
147
 
133
- `permissions.allow` / `permissions.additionalDirectories` in `.claude/settings.json` **grant** capability — applied only after the workspace trust dialog, never shown in a cloud (`-p` / SDK) session. `deny` / `ask` unaffected (restrict-only). Untrusted → every `allow` row ignored; sole notice one stderr line no cloud session surfaces.
148
+ `permissions.allow` / `permissions.additionalDirectories` in `.claude/settings.json` grant capability. Claude applies them only after the workspace trust dialog, which a cloud (`-p` / SDK) session never shows. `deny` / `ask` are unaffected, because they only restrict. In an untrusted workspace every `allow` row is ignored, and the only notice is one stderr line that no cloud session surfaces.
134
149
 
135
- Setup script writes both host-side, after the `jq` install:
150
+ The setup script writes both of these on the host side, after the `jq` install:
136
151
 
137
152
  <!-- prettier-ignore -->
138
153
  | Written | Where | Why setup script |
139
154
  | --- | --- | --- |
140
- | `projects[<repo path>].hasTrustDialogAccepted = true` | `~/.claude.json` | Settings resolve **before** `SessionStart` (hook too late); `.claude/` is a protected path (in-session write refused). Setup script = root, pre-clone, pre-Claude, snapshotted. |
141
- | `autoMode.environment` — `"$defaults"` first, `Host containment` entry, network-allowlist hosts | `~/.claude/settings.json` | Classifier reads `autoMode` from user / managed settings **only** — never `.claude/settings.json` / `.claude/settings.local.json`. Not shippable in-repo. |
155
+ | `projects[<repo path>].hasTrustDialogAccepted = true` | `~/.claude.json` | Settings resolve before `SessionStart`, so a hook is too late, and `.claude/` is a protected path, so an in-session write is refused. The setup script runs as root, before the clone and before Claude, and is snapshotted. |
156
+ | `autoMode.environment` — `"$defaults"` first, `Host containment` entry, network-allowlist hosts | `~/.claude/settings.json` | The classifier reads `autoMode` from user / managed settings only, never from `.claude/settings.json` / `.claude/settings.local.json`, so it cannot ship in the repo. |
142
157
 
143
- Both `jq`-merge, never clobber; `autoMode.environment` seeded `//=` (consumer list never overwritten). Omit `"$defaults"` → **whole built-in list discarded** for that section (incl. `Trusted repo`); renderer always emits it.
158
+ Both writes merge with `jq` and never clobber. `autoMode.environment` is seeded with `//=`, so a consumer's list is never overwritten. If `"$defaults"` is omitted, the whole built-in list for that section is discarded, `Trusted repo` included, so the renderer always emits it.
144
159
 
145
- Neither file is committable: `~/.claude/settings.json` resolves outside the repo tree; a git-**tracked** `.claude/settings.local.json` counts as repository-supplied, same trust gate.
160
+ Neither file can be committed. `~/.claude/settings.json` resolves outside the repo tree, and a git-tracked `.claude/settings.local.json` counts as repository-supplied, so it sits behind the same trust gate.
146
161
 
147
- Baked path `/home/user/<repo-name>` = observation of the current image, **not** a contract (no env var names the repo root). `.claude/hooks/bkit-cloud-bootstrap.sh` re-checks the discovered git root each session and warns on mismatch — diagnosis only, no repair. Fix: re-paste setup script.
162
+ The baked path `/home/user/<repo-name>` is an observation of the current image, not a contract: no env var names the repo root. `.claude/hooks/bkit-cloud-bootstrap.sh` re-checks the discovered git root each session and warns on a mismatch. It only diagnoses, and does not repair. To fix a mismatch, re-paste the setup script.
148
163
 
149
- Auto mode drops blanket `Bash(*)` on entry (narrow rows survive) → cloud auto-mode sessions run on classifier verdicts + `autoMode.environment`, not the allow list. Default classifier trust = working repo + remotes; every context-fetch host external until named. `Host containment` default assumes an open-internet dev machine.
164
+ Auto mode drops a blanket `Bash(*)` on entry, while narrow rows survive, so cloud auto-mode sessions run on the classifier's verdicts and `autoMode.environment`, not on the allow list. By default the classifier trusts the working repo and its remotes, and every context-fetch host counts as external until it is named. The default `Host containment` entry assumes an open-internet dev machine.
150
165
 
151
166
  ### Environment variables
152
167
 
153
- Minimum:
168
+ The minimum:
154
169
 
155
170
  ```
156
171
  BKIT_GH_TOKEN=<PAT — fine-grained for one owner, classic across owners; see permissions below>
157
172
  ```
158
173
 
159
- Claude pairs with **GitHub** tracker (see § Cloud-agent support matrix) — no `BKIT_LINEAR_API_KEY` / `LINEAR_ISSUE_ID`. Set `BKIT_GH_TOKEN` for GitHub MCP; authenticate `gh` via `gh auth login --with-token` in bootstrap hook (env vars not visible during setup script — see § Notes).
174
+ Tracker keys (`BKIT_LINEAR_API_KEY`, `BKIT_JIRA_API_KEY`) join the block whenever `.envrc` resolves them, so the block is the same for every tracker. Set `BKIT_GH_TOKEN` for the GitHub MCP, and authenticate `gh` with `gh auth login --with-token` in the bootstrap hook, because env vars are not visible during the setup script (see § Notes).
160
175
 
161
- Optional (context-fetch — only if you use `.agents/context.md` blocks, e.g. copied from `.bkit/templates/context/`; tokens below are **examples**, set whatever operator creds your enabled blocks need. Cloud-dashboard entries, not `.bkit/.env` — that file is bkit/agent tooling only. Non-secret selectors (`VERCEL_SCOPE` / `SUPABASE_PROJECT_ID`) commit in copied block so cloud agents inherit without dashboard entry. CLIs install from each block's `context-fetch:provision` sibling):
176
+ Optional, for context-fetch:
177
+
178
+ - You need these only if you use `.agents/context.md` blocks, for example ones copied from `.bkit/templates/context/`.
179
+ - The tokens below are examples. Set whatever operator creds your enabled blocks need.
180
+ - They are cloud-dashboard entries, not `.bkit/.env` entries, because that file is for bkit / agent tooling only.
181
+ - Non-secret selectors (`VERCEL_SCOPE` / `SUPABASE_PROJECT_ID`) are committed in the copied block, so cloud agents inherit them without a dashboard entry.
182
+ - The CLIs install from each block's `context-fetch:provision` sibling.
162
183
 
163
184
  ```
164
185
  VERCEL_TOKEN=<Vercel access token — https://vercel.com/account/settings/tokens>
@@ -167,7 +188,10 @@ SUPABASE_ACCESS_TOKEN=<Supabase Management API token — https://supabase.com/da
167
188
 
168
189
  #### `BKIT_GH_TOKEN` — token permissions
169
190
 
170
- **Choose the token type by how many owners it covers:** a **fine-grained** PAT reaches only resources under **one** resource owner (a user or an org) — use it when every target repo is under that owner; use a **classic** PAT when one token must span **more than one owner** (two or more orgs, or a user + an org), since fine-grained PATs cannot access multiple organizations. Fine-grained: mandatory expiry, repo-scoped blast radius — preferred when it fits (env vars are plaintext). Classic: scopes `repo`, `workflow`, `read:org`, `project`, `security_events` (+ `user:email` for Renovate authorship); keep the expiry short; an org may block classic (403) and SAML SSO orgs need the token authorized per org.
191
+ **Choose the token type by how many owners it covers:** A fine-grained PAT reaches only resources under one resource owner (a user or an org). Use it when every target repo is under that owner. Use a classic PAT when one token must span more than one owner (two or more orgs, or a user + an org), since fine-grained PATs cannot access multiple organizations.
192
+
193
+ - **Fine-grained:** It has a mandatory expiry and a repo-scoped blast radius. Prefer it when it fits, because env vars are plaintext.
194
+ - **Classic:** Give it the scopes `repo`, `workflow`, `read:org`, `project`, `security_events` (+ `user:email` for Renovate authorship), and keep the expiry short. An org may block classic tokens (403), and SAML SSO orgs need the token authorized per org.
171
195
 
172
196
  <!-- prettier-ignore -->
173
197
  | Permission | Level | What it unlocks |
@@ -177,30 +201,30 @@ SUPABASE_ACCESS_TOKEN=<Supabase Management API token — https://supabase.com/da
177
201
  | Issues | Read & write | `gh issue` |
178
202
  | Actions | Read & write | `gh run view` logs, `gh workflow run` |
179
203
  | Workflows | Read & write | `gh workflow` (edit `.github/workflows/*`) |
180
- | Projects (org) | Read & write | GitHub Projects v2 board status sync (`bkit.github.project`) — org-owned boards only; see note |
204
+ | Projects (org) | Read & write | GitHub Projects v2 board status sync (`bkit.tracker.github.project`) — org-owned boards only; see note |
181
205
  | Metadata | Read | mandatory, auto-included |
182
206
 
183
- `gh` does **not** read `BKIT_GH_TOKEN` — pipe once after session start: `printf '%s' "$BKIT_GH_TOKEN" | gh auth login --with-token` (e.g. in `.claude/hooks/bkit-cloud-bootstrap.sh`). Locally, `gh auth login` and leave `GH_TOKEN` unset so keyring not overridden.
207
+ `gh` does not read `BKIT_GH_TOKEN`. Pipe it in once after the session starts: `printf '%s' "$BKIT_GH_TOKEN" | gh auth login --with-token` (for example in `.claude/hooks/bkit-cloud-bootstrap.sh`). Locally, run `gh auth login` and leave `GH_TOKEN` unset, so the keyring is not overridden.
184
208
 
185
- > **Projects v2 board sync (`bkit.github.project`):** **Projects** permission is **Organization** permission (table row above) — appears only when token **resource owner is the org**, _not_ personal account; org may require token **approved**. Under token UI **Organizations** tab, not Repository permissions; governs `…/orgs/{org}/projectsV2/…`. User-owned (personal-account) boards unreachable by fine-grained PATs — see below.
209
+ > **Projects v2 board sync (`bkit.tracker.github.project`):** The Projects permission is an Organization permission (table row above). It appears only when the token's resource owner is the org, not a personal account, and the org may require the token to be approved. It sits under the token UI's Organizations tab, not under Repository permissions, and it governs `…/orgs/{org}/projectsV2/…`. Fine-grained PATs cannot reach user-owned (personal-account) boards (see below).
186
210
 
187
211
  #### When classic is still required
188
212
 
189
213
  - **More than one repo across owners.** A fine-grained PAT is limited to a single resource owner (one user or one org), so it cannot cover two or more orgs, or a user plus an org. Classic reaches every repo your user can.
190
- - **Cross-repo work in single cloud session.** Fine-grained PATs only see allowlist; classic sees everything your user can.
191
- - **User-owned (personal-account) Projects v2 boards.** Fine-grained PATs expose Projects only as _organization_ permission — personal boards unreachable. Classic PAT with `project` scope, or move board under org.
214
+ - **Cross-repo work in single cloud session.** Fine-grained PATs see only their allowlist, while classic sees everything your user can.
215
+ - **User-owned (personal-account) Projects v2 boards.** Fine-grained PATs expose Projects only as an organization permission, so personal boards are unreachable. Use a classic PAT with `project` scope, or move the board under an org.
192
216
 
193
217
  #### Notes
194
218
 
195
- - Claude app warns "don't add secrets" — env vars visible to anyone with edit rights. Personal account = just you; team account = treat as low-trust.
196
- - Earlier auto-compaction: set `autoCompactWindow` in committed `.claude/settings.json` (`.bkit/providers.md` § Context compaction) — applies to cloud sessions as-is; no env var.
197
- - **Env vars set in Claude app are not visible inside setup script.** Injected only after Claude Code starts → `SessionStart` hooks + interactive shell, not snapshot build. Tool needing token to bootstrap must inline it — leak you want to avoid. Avoided today: vale / gh / corepack don't need auth.
219
+ - The Claude app warns "don't add secrets", because env vars are visible to anyone with edit rights. On a personal account that is just you. Treat a team account as low-trust.
220
+ - For earlier auto-compaction, set `autoCompactWindow` in the committed `.claude/settings.json` (`.bkit/providers.md` § Context compaction). It applies to cloud sessions as-is, with no env var.
221
+ - **Env vars set in the Claude app are not visible inside the setup script.** They are injected only after Claude starts, so they reach `SessionStart` hooks and the interactive shell, not the snapshot build. A tool that needs a token to bootstrap would have to inline it, which is the leak you want to avoid. Today that is avoided, because vale / gh / corepack don't need auth.
198
222
 
199
- ## Environment variables
223
+ ## Tokens by session type
200
224
 
201
225
  Token management by session type:
202
226
 
203
- - **Local sessions** — bkit writes `.bkit/.env.example` (token placeholders); `.envrc` (`dotenv_if_exists .bkit/.env`) is a template: copy `.bkit/templates/.envrc`. Copy `.env.example` → `.bkit/.env`, fill tokens, `direnv allow`. direnv auto-exports `BKIT_GH_TOKEN`, `BKIT_LINEAR_API_KEY` on repo entry — no manual `source` or shell-rc export. `.bkit/.env` gitignored; never commit.
227
+ - **Local sessions** — bkit writes `.bkit/.env.example` (token placeholders). `.envrc` (`dotenv_if_exists .bkit/.env`) is a template: copy `.bkit/templates/.envrc`. Copy `.env.example` → `.bkit/.env`, fill in the tokens and run `direnv allow`. direnv auto-exports `BKIT_GH_TOKEN` and `BKIT_LINEAR_API_KEY` when you enter the repo, with no manual `source` or shell-rc export. `.bkit/.env` is gitignored. NEVER commit it.
204
228
 
205
229
  ```bash
206
230
  cp .bkit/.env.example .bkit/.env
@@ -208,19 +232,28 @@ Token management by session type:
208
232
  direnv allow
209
233
  ```
210
234
 
211
- - **Cloud sessions** (Claude Code on the web, Cursor Cloud Agents) — `.bkit/.env` absent in cloud containers. Set same names (`BKIT_GH_TOKEN`, `BKIT_LINEAR_API_KEY`) in respective dashboards: Claude app → environment selector → Environment variables; Cursor Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents`) → your environment → **Secrets** tab (as **Runtime Secret**s). Dashboard lists in sections below = canonical reference for names.
235
+ - **Cloud sessions** (Claude on the web, Codex Cloud, Cursor Cloud Agents) — `.bkit/.env` is absent in cloud containers. Set the same names (`BKIT_GH_TOKEN`, `BKIT_LINEAR_API_KEY`) in each host's dashboard:
236
+ - Claude app → environment selector → Environment variables.
237
+ - Cursor Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents`) → your environment → **Secrets** tab (as **Runtime Secret**s).
238
+ - ChatGPT → **Settings > Codex Cloud > Environments** → **Environment variables**.
239
+
240
+ Each host's generated `<host>/bkit-cloud.md` is the paste-ready block.
212
241
 
213
- **Beyond bkit tokens** — populate rest from _that repo's_ env-var files `.envrc` sources (e.g. `.bkit/.env`, then app `.env.local`). Don't hand-pick from memory; **copy from those files, following `.envrc`**:
242
+ **Beyond bkit tokens:** Fill in the rest from the env-var files that the repo's `.envrc` sources (for example `.bkit/.env`, then the app's `.env.local`). Don't hand-pick from memory. Copy from those files, following `.envrc`:
214
243
 
215
- - **Drop every var `.envrc` `unset`s** — deliberately kept out of repo shell (e.g. prod cache creds flipping unit tests off mock branch, or project ref mis-naming local stack); no place in cloud env.
216
- - **Skip session-hijacking keys — notably `BKIT_ANTHROPIC_API_KEY`** — redirects Claude Code model calls onto API-key billing, not subscription. Same for any var re-pointing agent's own auth.
217
- - **Values, not selectors.** Non-secret selectors (`VERCEL_SCOPE`, `SUPABASE_PROJECT_ID`, …) stay committed in-repo (§ observability / MCP blocks) — no dashboard entry.
244
+ - **Drop every var `.envrc` `unset`s.** These are kept out of the repo shell on purpose (for example prod cache creds that flip unit tests off the mock branch, or a project ref that mis-names the local stack), and they have no place in the cloud env.
245
+ - **Skip session-hijacking keys — notably `BKIT_ANTHROPIC_API_KEY`.** It redirects Claude model calls onto API-key billing instead of the subscription. The same goes for any var that re-points the agent's own auth.
246
+ - **Values, not selectors.** Non-secret selectors (`VERCEL_SCOPE`, `SUPABASE_PROJECT_ID`, …) stay committed in the repo (§ observability / MCP blocks) and get no dashboard entry.
218
247
 
219
248
  ## MCP issue-tracker integration
220
249
 
221
- bkit wires the chosen tracker's MCP server (`bkit.issueTracker`) into `.mcp.json` at repo root (project-shared, read by Claude Code `/mcp` UI). Cursor reads same shape from `.cursor/mcp.json`. All **remote HTTP MCPs** — no docker. GitHub: `BKIT_GH_TOKEN` PAT in the `Authorization` header — no OAuth. Linear: OAuth on first use — Claude Code launches browser auth on first server touch, stores token in own secret store. Jira: `BKIT_JIRA_API_TOKEN` scoped token in the `Authorization` header — no OAuth.
250
+ bkit wires the chosen tracker's MCP server (`bkit.tracker.default`) into `.mcp.json` at the repo root (project-shared, read by the Claude `/mcp` UI). Cursor reads the same shape from `.cursor/mcp.json`. All of them are remote HTTP MCPs, with no docker:
222
251
 
223
- > Note: `mcpServers` in `.claude/settings.json` silently ignored by Claude Code — definitions only from `.mcp.json` (project) or `claude mcp add` (user scope). `mcp__<name>__*` in `.claude/settings.json` `permissions.allow` are tool-permission allowlists — different concern, remain there.
252
+ - GitHub: the `BKIT_GH_TOKEN` PAT in the `Authorization` header, with no OAuth.
253
+ - Linear: OAuth on first use. Claude launches browser auth the first time it touches the server and stores the token in its own secret store.
254
+ - Jira: the `BKIT_JIRA_API_KEY` scoped token in the `Authorization` header, with no OAuth.
255
+
256
+ > Note: Claude silently ignores `mcpServers` in `.claude/settings.json`. It takes definitions only from `.mcp.json` (project) or `claude mcp add` (user scope). The `mcp__<name>__*` entries in `.claude/settings.json` `permissions.allow` are tool-permission allowlists, a different concern, and they stay there.
224
257
 
225
258
  ```json
226
259
  "mcpServers": {
@@ -233,85 +266,114 @@ bkit wires the chosen tracker's MCP server (`bkit.issueTracker`) into `.mcp.json
233
266
  "jira": {
234
267
  "type": "http",
235
268
  "url": "https://mcp.atlassian.com/v2/mcp",
236
- "headers": { "Authorization": "Bearer ${BKIT_JIRA_API_TOKEN}" }
269
+ "headers": { "Authorization": "Bearer ${BKIT_JIRA_API_KEY}" }
237
270
  }
238
271
  }
239
272
  ```
240
273
 
241
- `"type": "http"` required — without it Claude Code defaults to stdio transport and rejects entry for missing `command`.
274
+ `"type": "http"` is required. Without it, Claude defaults to the stdio transport and rejects the entry for a missing `command`.
242
275
 
243
- - **GitHub** — official GitHub MCP at `api.githubcopilot.com` (not gated by Copilot subscription). Surface: `issue_write`, `add_issue_comment`, `label_write`, `projects_write`, etc. Used under GitHub provider. Endpoint does **not** support OAuth DCR → auth via `Authorization: Bearer ${BKIT_GH_TOKEN}` (MCP-only env var — see § Environment variables and KN-CORE-8).
244
- - **Linear** — full Linear workspace surface (`get_issue`, `save_issue`, `save_comment`, `list_*`). Used when `bkit.issueTracker` = `linear`. OAuth (Dynamic Client Registration) — browser flow on first use, no env var.
245
- - **Jira** — Atlassian Rovo MCP at `mcp.atlassian.com/v2/mcp`. Surface: `getJiraIssue`, `editJiraIssue`, `transitionJiraIssue`, `addOrEditJiraIssueComment`, `searchJiraIssuesUsingJql`, `executeRead` / `executeWrite`. Used when `bkit.issueTracker` = `jira`. Auth via `Authorization: Bearer ${BKIT_JIRA_API_TOKEN}` — a scoped **Atlassian MCP V2** token; org admin must allow API-token sign-in (`.bkit/trackers.md` § jira — setup and notes).
276
+ - **GitHub** — the official GitHub MCP at `api.githubcopilot.com` (not gated by a Copilot subscription). Its surface includes `issue_write`, `add_issue_comment`, `label_write`, `projects_write` and more. It is used under the GitHub provider. The endpoint does not support OAuth DCR, so auth goes through `Authorization: Bearer ${BKIT_GH_TOKEN}` (an MCP-only env var, see § Environment variables).
277
+ - **Linear** — the full Linear workspace surface (`get_issue`, `save_issue`, `save_comment`, `list_*`). It is used when `bkit.tracker.default` = `linear`. Auth is OAuth (Dynamic Client Registration): a browser flow on first use, with no env var.
278
+ - **Jira** — the Atlassian Rovo MCP at `mcp.atlassian.com/v2/mcp`. Its surface is `getJiraIssue`, `editJiraIssue`, `transitionJiraIssue`, `addOrEditJiraIssueComment`, `searchJiraIssuesUsingJql` and `executeRead` / `executeWrite`. It is used when `bkit.tracker.default` = `jira`. Auth goes through `Authorization: Bearer ${BKIT_JIRA_API_KEY}`, a scoped **Atlassian MCP V2** token, and the org admin must allow API-token sign-in (`.bkit/trackers.md` § jira — setup and notes).
246
279
 
247
280
  **Auth flow per server:**
248
281
 
249
- - **GitHub:** Claude Code substitutes `${BKIT_GH_TOKEN}` from environment at session start. Unset → server fails. Set in shell (`export BKIT_GH_TOKEN=...`) or cloud dashboard.
250
- - **Linear:** Claude Code prompts browser authorize on first use; token in Claude's secret store. No further action.
251
- - **Jira:** Claude Code substitutes `${BKIT_JIRA_API_TOKEN}` from environment at session start. Unset or classic token → every Jira call fails.
282
+ - **GitHub:** Claude substitutes `${BKIT_GH_TOKEN}` from the environment at session start. If it is unset, the server fails. Set it in the shell (`export BKIT_GH_TOKEN=...`) or the cloud dashboard.
283
+ - **Linear:** Claude asks you to authorize in the browser on first use, and keeps the token in Claude's secret store. No further action is needed.
284
+ - **Jira:** Claude substitutes `${BKIT_JIRA_API_KEY}` from the environment at session start. If it is unset or a classic token, every Jira call fails.
252
285
 
253
- **`gh auth login` required for gh CLI surface** (PR creation, branch ops, git push). Locally, keyring — do not export `GH_TOKEN` from `.bkit/.env`. Cloud/headless: `bkit-cloud-bootstrap.sh` runs `printf '%s' "$BKIT_GH_TOKEN" | gh auth login --with-token` at SessionStart (guarded by the `bkit runtime detect` gh probe, no-ops on Actions runner where `GITHUB_TOKEN` auths) — no manual step. Same PAT value fine; different env-var name keeps local `gh` on keyring.
286
+ **`gh auth login` is required for the gh CLI surface** (PR creation, branch ops, git push). Locally, gh uses the keyring, so do not export `GH_TOKEN` from `.bkit/.env`. In cloud / headless sessions, `bkit-cloud-bootstrap.sh` runs `printf '%s' "$BKIT_GH_TOKEN" | gh auth login --with-token` at SessionStart, so there is no manual step. The `bkit runtime detect` gh probe guards that step, and it does nothing on an Actions runner, where `GITHUB_TOKEN` authenticates. The same PAT value is fine. The different env-var name keeps the local `gh` on the keyring.
254
287
 
255
- **Cloud sessions** (Claude on the web, Cursor Cloud Agents): GitHub MCP reads `BKIT_GH_TOKEN` from dashboard — set alongside `BKIT_LINEAR_API_KEY` under Linear. Linear MCP OAuth on first touch, same as local. Jira: no cloud sessions (local runs only).
288
+ **Cloud sessions** (Claude on the web, Codex Cloud, Cursor Cloud Agents): The GitHub MCP reads `BKIT_GH_TOKEN`, and the Jira MCP reads `BKIT_JIRA_API_KEY`, from the dashboard env vars. The Linear MCP runs OAuth on first touch, the same as locally. Jira has no cloud dispatch, so a manually launched session reaches Jira once `BKIT_JIRA_API_KEY` is set.
256
289
 
257
290
  ## After saving the Claude env
258
291
 
259
- 1. Trigger session: `claude --remote "echo ready"` from repo, or tap env in iOS app.
260
- 2. First session slow (setup script + snapshot). Subsequent sessions start from snapshot.
261
- 3. Verify in-session: `vale --version && gh --version && pnpm -v && which corepack`.
262
- 4. Verify workspace trust on the discovered root — `true` = `allow` rows apply; `MISSING` = clone path differs from the baked one (§ Workspace trust + auto-mode config):
292
+ 1. Trigger a session: run `claude --remote "echo ready"` from the repo, or tap the environment in the iOS app.
293
+ 2. The first session is slow (setup script + snapshot). Later sessions start from the snapshot.
294
+ 3. Verify in the session: `vale --version && gh --version && pnpm -v && which corepack`.
295
+ 4. Verify workspace trust on the discovered root. `true` means the `allow` rows apply, and `MISSING` means the clone path differs from the baked one (§ Workspace trust + auto-mode config):
263
296
 
264
297
  ```bash
265
298
  jq -r --arg p "$(git rev-parse --show-toplevel)" \
266
299
  '.projects[$p].hasTrustDialogAccepted // "MISSING"' "${CLAUDE_CONFIG_DIR:-$HOME}/.claude.json"
267
300
  ```
268
301
 
269
- 5. Snapshot rebuilds when setup-script body changes, allowed-hosts list changes, or ~7-day TTL expires. Editing env vars or in-repo hook scripts does **not** invalidate snapshot.
270
- 6. **Force rebuild without semantic changes**: add `# cache-bust YYYY-MM-DD-N` comment at top of setup script.
302
+ 5. The snapshot rebuilds when the setup-script body changes, the allowed-hosts list changes, or the ~7-day TTL expires. Editing env vars or in-repo hook scripts does not invalidate the snapshot.
303
+ 6. **Force rebuild without semantic changes**: run `bkit install` or `bkit upgrade`, which re-stamps the `# cache-bust` line, then paste the new setup script.
304
+
305
+ # Codex Cloud
306
+
307
+ > [!TIP]
308
+ > **Nothing to hand-assemble.** `bkit install --codex` writes `.codex/bkit-cloud.md`, the
309
+ > twin of `.claude/bkit-cloud.md`: the install script, the env block resolved from `.envrc` (the same
310
+ > block as the other hosts, for any tracker) and the network list. The file is gitignored and chmod 600 because it holds real
311
+ > secrets. It regenerates on every install / upgrade, and `bkit uninstall --codex` deletes it.
312
+
313
+ ## What to paste
314
+
315
+ ChatGPT → **Settings > Codex Cloud > Environments** → **Create environment** → pick the repo → name it after the repo (one env per repo, § Sharing across repos):
316
+
317
+ <!-- prettier-ignore -->
318
+ | Field | Paste from `.codex/bkit-cloud.md` |
319
+ | --- | --- |
320
+ | **Install script** | § Install script — Claude setup script's pinned toolchain (Node, vale, gh, jq; sliced from the Claude template at install, never a second copy of the pins), corepack pnpm, context-fetch provision recipes, then `pnpm install --frozen-lockfile`, `vale sync` (if `.vale.ini`), non-blocking `gh auth login --with-token` from `BKIT_GH_TOKEN` |
321
+ | **Environment variables** | § Environment variables — `.env` block (**Paste your .env or type a key**) |
322
+ | **Internet access** | § Network access — keep **Enable package manager domains**, paste the list into **Additional allowed domains** (`*.` entries untested on Codex: its docs list exact hosts, and a root domain also allows `www`). **Enable all public internet access** = open egress |
323
+
324
+ ## Env vars vs network secrets
325
+
326
+ - **Environment variables** reach every program as-is, so put every bkit token here (MCP servers, `gh`, `pnpm` and bkit read the process env).
327
+ - **Network secrets** (Key / Value / **Allowed domains**): Programs see a placeholder. The proxy substitutes the real value only on requests to allowed domains, during setup and tasks. This fits a token used only in HTTP headers to known hosts, and breaks any token a program reads directly (`gh auth login --with-token`).
328
+ - **Personal vault** shares a secret across **All environments** or **Selected environments**, for a token several repos reuse.
329
+
330
+ ## Hooks in cloud tasks
331
+
332
+ Repo skills (`.agents/skills/bkit-*`, `$bkit-design`) load in cloud tasks. Codex's cloud docs do not say whether `.codex/hooks.json` runs there, so GateGuard, ReadGuard, guardrails and the rules advisory are unproven in cloud tasks. Review cloud diffs as unguarded. Locally they fire only once the `.codex/` layer is trusted (`.bkit/providers.md` § Codex CLI — three deviations).
271
333
 
272
334
  # Cursor Cloud Agents
273
335
 
274
- > Cursor calls these **Cloud Agents**; secrets live in the **Secrets tab** of the Cloud
336
+ > Cursor calls these **Cloud Agents**. Secrets live in the **Secrets tab** of the Cloud
275
337
  > Agents dashboard (`cursor.com/dashboard/cloud-agents`). The webhook field is
276
338
  > `is_background_agent`. This doc uses "Cloud Agents" throughout.
277
339
 
278
340
  > [!TIP]
279
341
  > **No manual copy needed for the dashboard secrets.** `bkit install --cursor` writes
280
- > `.cursor/bkit-cloud.md` — the twin of `.claude/bkit-cloud.md`, with the Cursor secrets block
281
- > **resolved from `.envrc`** (Linear tracker adds `BKIT_LINEAR_API_KEY`). Open it, then in the
342
+ > `.cursor/bkit-cloud.md`, the twin of `.claude/bkit-cloud.md`, with the Cursor secrets block
343
+ > resolved from `.envrc` (the same block as the Claude side, for any tracker). Open it, then in the
282
344
  > Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents`) → your environment → **Secrets**
283
- > tab, add each as a **Runtime Secret** (loaded as an env var, redacted from the agent's transcript).
284
- > Gitignored (holds real secrets); regenerates on every install/upgrade. The toolchain
285
- > half is the committed `.cursor/Dockerfile` + `.cursor/environment.json` (nothing to
286
- > paste) — same tools, same versions as the Claude setup script.
345
+ > tab, add each entry as a **Runtime Secret** (loaded as an env var, redacted from the agent's transcript).
346
+ > The file is gitignored because it holds real secrets, and it regenerates on every install/upgrade. The toolchain
347
+ > half is the committed `.cursor/Dockerfile` + `.cursor/environment.json`, with nothing to
348
+ > paste. It has the same tools, at the same versions, as the Claude setup script.
287
349
 
288
350
  ## Where config lives
289
351
 
290
- Everything in repo under `.cursor/`. bkit ships canonical content for all four files:
352
+ Everything lives in the repo under `.cursor/`. bkit ships canonical content for all four files:
291
353
 
292
354
  <!-- prettier-ignore -->
293
355
  | File | Role | bkit ownership |
294
356
  | --- | --- | --- |
295
357
  | `.cursor/Dockerfile` | Cloud image — vale + gh + Node 24 (template default) + pnpm (corepack-pinned); Node, gh and vale are version-pinned and sha256-checked; browsers etc. added by the consumer | Template: copy from `.bkit/templates/.cursor/Dockerfile`; yours after |
296
- | `.cursor/environment.json` | Build pointer + per-snapshot `install` hook (`pnpm install --frozen-lockfile` + `vale sync` if `.vale.ini`) | Template: copy from `.bkit/templates/.cursor/environment.json`; yours after |
358
+ | `.cursor/environment.json` | Build pointer + per-snapshot `install` hook (`pnpm install --frozen-lockfile` + `vale sync` if `.vale.ini` + `pnpm exec bkit context provision`) | Template: copy from `.bkit/templates/.cursor/environment.json`; yours after |
297
359
  | `.cursor/hooks.json` | Wires `sessionStart` → `bkit-preflight.sh` (`failClosed: true`) | Tier 2 contained JSON |
298
- | `.cursor/hooks/bkit-preflight.sh` | Tracker opt-in guard — `bkit:auto` label + non-terminal status. Skips silently on IDE sessions | Tier 2 contained (bkit:start/end markers) |
360
+ | `.cursor/hooks/bkit-preflight.sh` | Tracker opt-in guard — `bkit:auto` label + non-terminal status — plus the rules-read advisory (`.bkit/providers.md` § Rules-read advisory). IDE session → the advisory alone, exit 0 | Tier 2 contained (bkit:start / end markers) |
299
361
 
300
362
  ## How GitHub dispatch works
301
363
 
302
- GitHub dispatch uses Cursor Automations "Pull request label changed" trigger — no Linear webhook.
364
+ GitHub dispatch uses the Cursor Automations "Pull request label changed" trigger, with no Linear webhook.
303
365
 
304
- **Prerequisites:** Cursor GitHub App installed on consumer repo or org.
366
+ **Prerequisites:** The Cursor GitHub App is installed on the consumer repo or org.
305
367
 
306
368
  **Trigger flow:**
307
369
 
308
- 1. `bkit-build` writes `bkit:auto` as static PR label (opt-in marker). Corresponding GitHub issue must also carry `bkit:auto` (runtime kill switch — remove to stop dispatch).
309
- 2. Phase label (`bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`) added to PR by workflow. Cursor reads label for workflow dispatch.
310
- 3. Cursor Automations fires on "Pull request label changed" → spawns Background Agent session against repo.
311
- 4. `sessionStart` fires `bkit-preflight.sh`. With `failClosed: true`, non-zero exit hard-stops agent.
312
- 5. `GITHUB_ISSUE_ID` injected from PR body metadata marker `<!-- bkit:issue=#NNN -->` — router extracts at dispatch time.
370
+ 1. `bkit-build` writes `bkit:auto` as a static PR label (the opt-in marker). The matching GitHub issue must also carry `bkit:auto`, which is the runtime kill switch: remove it to stop dispatch.
371
+ 2. The workflow adds the phase label (`bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`) to the PR. Cursor reads the label for workflow dispatch.
372
+ 3. Cursor Automations fires on "Pull request label changed" → spawns a Background Agent session against the repo. The Automation's prompt must contain `bkit-auto`, because `AGENTS.md` routes only a `bkit-{command}` prompt, and `.bkit/router.md` reads the phase from the issue's labels.
373
+ 4. `sessionStart` fires `bkit-preflight.sh`. With `failClosed: true`, a non-zero exit hard-stops the agent.
374
+ 5. `GITHUB_ISSUE_ID` is injected from the PR body metadata marker `<!-- bkit:issue=#NNN -->`, which the router extracts at dispatch time.
313
375
 
314
- **Constraint:** `/bkit-design` and `/bkit-plan` have no PR → local-IDE-only on Cursor cloud with GitHub tracker. Run locally via Claude Code or Cursor IDE.
376
+ **Constraint:** `/bkit-design` and `/bkit-plan` have no PR, so on Cursor cloud with the GitHub tracker they are local-IDE-only. Run them locally through Claude or the Cursor IDE.
315
377
 
316
378
  **Required env vars (GitHub tracker):**
317
379
 
@@ -319,29 +381,34 @@ GitHub dispatch uses Cursor Automations "Pull request label changed" trigger —
319
381
  BKIT_GH_TOKEN=<PAT — fine-grained for one owner, classic across owners; same permissions as the Claude side>
320
382
  ```
321
383
 
322
- `GITHUB_ISSUE_ID` injected per-session — do not hardcode. No `BKIT_LINEAR_API_KEY` or `LINEAR_ISSUE_ID` for tracker calls (GitHub MCP auth = `BKIT_GH_TOKEN` above; `gh` uses `gh auth login` locally or `--with-token` in cloud bootstrap).
384
+ `GITHUB_ISSUE_ID` is injected per session, so do not hardcode it. Tracker calls need no `BKIT_LINEAR_API_KEY` or `LINEAR_ISSUE_ID`: the GitHub MCP authenticates with `BKIT_GH_TOKEN` above, and `gh` uses `gh auth login` locally or `--with-token` in the cloud bootstrap.
323
385
 
324
386
  ## How Linear dispatch works
325
387
 
326
- `@cursor` is **Cursor's native Linear integration**, not bkit — bkit does not intercept mention or run own Linear webhook. Spawned agent picks up bkit because every Cursor cloud agent reads root `AGENTS.md`, routing `/bkit-*` slash command to matching workflow in `.bkit/core/workflows/`.
388
+ `@cursor` is Cursor's native Linear integration, not bkit. bkit does not intercept the mention or run its own Linear webhook. The spawned agent picks up bkit because every Cursor cloud agent reads the root `AGENTS.md`, which sends a `bkit-{command}` prompt to `.bkit/router.md` → matching workflow.
327
389
 
328
- 1. Assign Linear issue to **Cursor** (integration user) or comment `@cursor /bkit-design ISSUE-NNN` — Cursor's standard Linear integration.
329
- 2. Cursor webhook → background agent against repo with `is_background_agent: true` and `LINEAR_ISSUE_ID` set.
330
- 3. `sessionStart` fires `bkit-preflight.sh`. With `failClosed: true`, non-zero exit hard-stops agent before work.
331
- 4. Preflight skips on IDE sessions (`is_background_agent !== true`) — local Cursor IDE unaffected.
390
+ 1. Comment `@cursor bkit-auto ISSUE-NNN` (phase from the issue's labels) or `@cursor /bkit-design ISSUE-NNN`, which is Cursor's standard Linear integration. Assigning the issue to **Cursor** alone starts no workflow, because its prompt names no `bkit-{command}`.
391
+ 2. The Cursor webhook → a background agent against the repo, with `is_background_agent: true` and `LINEAR_ISSUE_ID` set.
392
+ 3. `sessionStart` fires `bkit-preflight.sh`. With `failClosed: true`, a non-zero exit hard-stops the agent before work.
393
+ 4. Preflight skips IDE sessions (`is_background_agent !== true`), so the local Cursor IDE is unaffected.
332
394
 
333
395
  ## Required env vars (Cursor side)
334
396
 
335
- Set in the Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents` → your environment → **Secrets** tab) as **Runtime Secret**s (loaded as env vars, redacted from the agent's transcript), **not** in `.cursor/environment.json`:
397
+ Set these in the Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents` → your environment → **Secrets** tab) as **Runtime Secret**s (loaded as env vars, redacted from the agent's transcript), not in `.cursor/environment.json`:
336
398
 
337
399
  ```
338
- BKIT_LINEAR_API_KEY=<Linear personal API key — bkit-preflight.sh calls the GraphQL API>
339
400
  BKIT_GH_TOKEN=<PAT — fine-grained for one owner, classic across owners; same permissions as the Claude side>
340
401
  ```
341
402
 
342
- `LINEAR_ISSUE_ID` injected per-session by Cursor / Linear integration — do not hardcode.
403
+ Add every tracker key `.envrc` resolves. Under Linear that is `BKIT_LINEAR_API_KEY` (a Linear personal API key, because `bkit-preflight.sh` calls the GraphQL API). The Cursor / Linear integration injects `LINEAR_ISSUE_ID` per session, so do not hardcode it.
343
404
 
344
- Optional (context-fetch — only if you use `.agents/context.md` blocks, e.g. copied from `.bkit/templates/context/`; tokens below are **examples**, set whatever operator creds your enabled blocks need. Cloud-dashboard entries, not `.bkit/.env` — bkit/agent tooling only. Non-secret selectors (`VERCEL_SCOPE` / `SUPABASE_PROJECT_ID`) commit in copied block so cloud agents inherit without dashboard entry. CLIs install from each block's `context-fetch:provision` sibling):
405
+ Optional, for context-fetch:
406
+
407
+ - You need these only if you use `.agents/context.md` blocks, for example ones copied from `.bkit/templates/context/`.
408
+ - The tokens below are examples. Set whatever operator creds your enabled blocks need.
409
+ - They are cloud-dashboard entries, not `.bkit/.env` entries, because that file is for bkit / agent tooling only.
410
+ - Non-secret selectors (`VERCEL_SCOPE` / `SUPABASE_PROJECT_ID`) are committed in the copied block, so cloud agents inherit them without a dashboard entry.
411
+ - The CLIs install from each block's `context-fetch:provision` sibling.
345
412
 
346
413
  ```
347
414
  VERCEL_TOKEN=<Vercel access token — https://vercel.com/account/settings/tokens>
@@ -350,66 +417,73 @@ SUPABASE_ACCESS_TOKEN=<Supabase Management API token — https://supabase.com/da
350
417
 
351
418
  ## Network access (Cursor side)
352
419
 
353
- Cloud Agents get network access by default; egress is configurable in the dashboard → **Security**: **Allow all** / **Default + allowlist** / **Allowlist only**, at user / environment / team scope. Analogue of Claude's `Trusted` / `Custom`, but the allowlist is **deliberately narrower** — Cursor warns a broad `*.` wildcard opens egress far wider than intended, so add the **specific** subdomains you need rather than a wildcard. `.cursor/bkit-cloud.md` § Network access lists the derived hosts union any declared `allowed-domains`, as exact hosts (no auto-`*.` expansion, unlike the Claude side).
420
+ Cloud Agents get network access by default. Egress is configurable in the dashboard → **Security**: **Allow all** / **Default + allowlist** / **Allowlist only**, at user / environment / team scope. This is the analogue of Claude's `Trusted` / `Custom`. `.cursor/bkit-cloud.md` § Network access lists bkit's derived hosts exactly, and each declared `allowed-domains` entry as the domain plus its `*.` wildcard, like the Claude side, so the subdomains a declared CLI or API calls (`api.vercel.com` under `vercel.com`) are reachable. A declared shared hosting platform (`vercel.app`, `supabase.co`, the rest of `MULTI_TENANT_APEXES` in `.bkit/core/engine/shared/egress.ts`) is widened too, with a note: its wildcard reaches every tenant on the platform, the exfiltration path Cursor's docs warn about. To narrow it, declare the exact hosts you call there instead (`myapp.vercel.app`, `logging.googleapis.com`).
354
421
 
355
422
  ## After modifying `.cursor/*`
356
423
 
357
- 1. Run `pnpm bkit install` (this repo) or `pnpm install && pnpm bkit install` (consumer) to regenerate mirrors.
358
- 2. Commit changes.
359
- 3. **First Cursor session after Dockerfile changes slow** — image rebuilds. Subsequent sessions reuse cached layers.
360
- 4. Verify in-session: `vale --version && gh --version && pnpm -v && python3 --version`.
424
+ 1. Run `pnpm install && pnpm bkit install` to regenerate the mirrors.
425
+ 2. Commit the changes.
426
+ 3. **The first Cursor session after Dockerfile changes is slow**, because the image rebuilds. Later sessions reuse the cached layers.
427
+ 4. Verify in the session: `vale --version && gh --version && pnpm -v && python3 --version`.
361
428
 
362
429
  # Sharing across repos
363
430
 
364
431
  ## Claude — one environment per repo
365
432
 
366
- Each repo gets **own** Claude environment, named after repo. Reason: **secrets, not mechanics**.
433
+ Each repo gets its own Claude environment, named after the repo. The reason is secrets, not mechanics.
434
+
435
+ **Secrets are per-repo.** App tokens (Supabase, Stripe, Vercel, …) differ per repo. Even bkit tokens differ in scope: a fine-grained `BKIT_GH_TOKEN` is scoped to one resource owner / repo, and covering different owners needs one classic PAT, which cannot be per-repo. One Claude environment holds one value per name, so a shared environment forces either a mega-scoped PAT across repos (a wide blast radius) or one repo's secrets leaking into the rest. Per-repo environments isolate secrets.
436
+
437
+ Shared across repos (copy, don't re-derive), non-secret only:
367
438
 
368
- **Secrets are per-repo.** App tokens (Supabase, Stripe, Vercel, …) differ per repo; even bkit tokens differ in _scope_ (a fine-grained `BKIT_GH_TOKEN` is scoped to one resource owner / repo; covering different owners needs one classic PAT, which cannot be per-repo). One Claude environment = one value per name — shared env forces mega-scoped PAT across repos (wide blast radius) or one repo's secrets leaking into rest. Per-repo envs isolate secrets.
439
+ - **Setup script** — generic binaries only (Node, vale, gh, jq, pnpm via corepack). The repo-specific install is left to the committed `bkit-cloud-bootstrap.sh` (lockfile → `pnpm install`, `.vale.ini` → `vale sync`). One body fits every repo.
440
+ - **bkit baseline token name** (`BKIT_GH_TOKEN`) + **network policy** (`Custom`) — the same everywhere, while the values differ. The repo's other env vars are not shared. Copy them from the repo's own env files, following `.envrc`: drop the `unset`s and skip `BKIT_ANTHROPIC_API_KEY` (§ Tokens by session type).
441
+ - **Non-secret selectors** (`VERCEL_SCOPE`, `SUPABASE_PROJECT_ID`) stay committed in the repo (§ Tokens by session type), never in the dashboard.
369
442
 
370
- Shared across repos (copy, don't re-derive) — non-secret only:
443
+ ## Codex — one environment per repo
371
444
 
372
- - **Setup script** — generic binaries only (Node, vale, gh, jq, pnpm via corepack); repo-specific install deferred to committed `bkit-cloud-bootstrap.sh` (lockfile → `pnpm install`, `.vale.ini` → `vale sync`). One body fits every repo.
373
- - **bkit baseline token _name_** (`BKIT_GH_TOKEN`) + **network policy** (`Trusted`) — same everywhere, values differ. Repo _other_ env vars **not** shared: copy from own env files per `.envrc` — drop `unset`s, skip `BKIT_ANTHROPIC_API_KEY` (§ Environment variables).
374
- - **Non-secret selectors** (`VERCEL_SCOPE`, `SUPABASE_PROJECT_ID`) stay committed in-repo (§ Environment variables), never in dashboard.
445
+ The rule is the same as for Claude: a per-repo environment with per-repo secrets. The install script is identical across repos, because the repo-specific steps guard themselves on `pnpm-lock.yaml` / `.vale.ini`. For a token shared on purpose, use the **Personal vault** scoped to **Selected environments**, not a mega-scoped PAT.
375
446
 
376
447
  ## Cursor — byte-identical Dockerfile
377
448
 
378
- Cursor environment-resolution order: (1) `.cursor/environment.json` in repo, (2) personal saved environment in Cursor account, (3) team saved environment. Three sharing patterns:
449
+ Cursor resolves the environment in this order: (1) `.cursor/environment.json` in the repo, (2) a personal saved environment in the Cursor account, (3) a team saved environment. There are three sharing patterns:
379
450
 
380
- 1. **In-repo copy (bkit default).** Each consumer repo carries `.cursor/Dockerfile` + `.cursor/environment.json`, copied from bkit's templates and owned by the repo. Functionally equivalent Cursor envs across consumers; bkit ships base-toolchain updates as template changes the consumer adopts.
381
- 2. **Personal saved environment (cross-repo).** Don't commit `.cursor/environment.json`; configure single environment in Cursor account dashboard. Cursor falls back for any session. Like any cross-repo environment — one secret set for all repos; prefer per-repo default (#1) when repos have distinct secrets.
382
- 3. **Multi-repo environment.** Cursor binds one environment to multiple repos cloned into same agent VM. Cross-repo work but agent sees all selected repos — different security boundary.
451
+ 1. **In-repo copy (bkit default).** Each consumer repo carries `.cursor/Dockerfile` + `.cursor/environment.json`, copied from bkit's templates and owned by the repo. Cursor environments are functionally equivalent across consumers, and bkit ships base-toolchain updates as template changes the consumer adopts.
452
+ 2. **Personal saved environment (cross-repo).** Don't commit `.cursor/environment.json`. Configure a single environment in the Cursor account dashboard, and Cursor falls back to it for any session. Like any cross-repo environment, it holds one secret set for all repos. Prefer the per-repo default (#1) when repos have distinct secrets.
453
+ 3. **Multi-repo environment.** Cursor binds one environment to multiple repos cloned into the same agent VM. This allows cross-repo work, but the agent sees all selected repos, which is a different security boundary.
383
454
 
384
- When bkit reference Dockerfile changes (e.g. vale bump):
455
+ When bkit's reference Dockerfile changes (for example a vale bump):
385
456
 
386
- - Consumer `.cursor/Dockerfile` **never** written by bkit (it is the consumer's copy of a template).
457
+ - bkit never writes the consumer's `.cursor/Dockerfile`, because it is the consumer's copy of a template.
387
458
  - `bkit upgrade` refreshes `.bkit/templates/.cursor/Dockerfile` and names it in its changed-templates list.
388
- - Consumer diffs the refreshed template against their copy and merges what they want.
459
+ - The consumer diffs the refreshed template against their copy and merges what they want.
389
460
 
390
461
  ## What every consumer repo needs to do
391
462
 
392
- 1. `pnpm bkit install` — bkit-managed toolchain updates land in the written payload; `.claude/hooks/bkit-cloud-bootstrap.sh` is a copy-and-own template, so diff it against `.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh` when `bkit upgrade` lists that path and merge what you want. `.cursor/Dockerfile` is your copy of a template: diff it against `.bkit/templates/.cursor/Dockerfile` when `bkit upgrade` lists that path.
393
- 2. Set `BKIT_LINEAR_API_KEY`, `BKIT_GH_TOKEN` as **Runtime Secret**s in the Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents` → your environment → **Secrets** tab). Paste-ready values are in `.cursor/bkit-cloud.md`.
394
- 3. Add Claude environment **named after repo** at `claude.ai/code`; paste recipe from § Claude Code on the web (one environment per repo — secrets per-repo).
463
+ 1. Run `pnpm bkit install`. bkit-managed toolchain updates land in the written payload.
464
+ - `.claude/hooks/bkit-cloud-bootstrap.sh` is a copy-and-own template. When `bkit upgrade` lists that path, diff your copy against `.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh` and merge what you want.
465
+ - `.cursor/Dockerfile` is your copy of a template. Diff it against `.bkit/templates/.cursor/Dockerfile` when `bkit upgrade` lists that path.
466
+ 2. Set the `.cursor/bkit-cloud.md` block as **Runtime Secret**s in the Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents` → your environment → **Secrets** tab).
467
+ 3. Add a Claude environment named after the repo at `claude.ai/code`, and paste the recipe from § Claude on the web (one environment per repo, because secrets are per-repo).
468
+ Codex: do the same at **Settings > Codex Cloud > Environments**, pasted from `.codex/bkit-cloud.md` (§ Codex Cloud).
395
469
  4. Customise `.cursor/Dockerfile` Node version (`NODE_VERSION` + `NODE_SHA256`) / Playwright / extra system deps. Keep the `bkit toolchain` section as the template ships it, so a template diff stays readable.
396
470
 
397
471
  # Post-CI auto-routing
398
472
 
399
- After `bkit-build` Step 18 close-workflow pushes CI-trigger commit (`chore({FID}): close-workflow`, no skip tags) and exits, post-CI router decides ship vs. debug and dispatches matching skill in fresh cloud session — no operator action between CI completion and dispatched session.
473
+ After `bkit-build` Step 16 close-workflow pushes the CI-trigger commit (`chore({FID}): close-workflow`, no skip tags) and exits, the post-CI router decides ship vs. debug and dispatches the matching skill in a fresh cloud session. No operator action is needed between CI completion and the dispatched session.
400
474
 
401
- Routing **logic** in single bkit-managed slash-command orchestrator (`.bkit/core/workflows/bkit-auto.md`, mirrored to `.claude/commands/bkit-auto.md` + `.cursor/commands/bkit-auto.md` on each `pnpm bkit install`). Routing **trigger** wired separately per IDE — different event surfaces.
475
+ The routing logic lives in a single bkit-managed slash-command orchestrator (`.bkit/core/workflows/bkit-auto.md`, mirrored to `.claude/commands/bkit-auto.md` + `.cursor/commands/bkit-auto.md` on each `pnpm bkit install`). The routing trigger is wired separately per IDE, because each IDE has different event surfaces.
402
476
 
403
477
  ## What lives where (post-CI half)
404
478
 
405
479
  <!-- prettier-ignore -->
406
480
  | | Lives in the repo (bkit-managed) | Lives in the online dashboard / GitHub (manual, one-time) |
407
481
  | --- | --- | --- |
408
- | **Claude** | `.github/workflows/bkit-cloud.yml` — `claude` job (opt-in via `bkit install --auto=claude`; GitHub-tracker only). Two-tier gate: (1) free tier — job `if: contains(head_commit.message, 'bkit [auto route]')` (zero runner minutes for non-opted-in commits); (2) cheap tier — in-job `gh issue view {ISSUE} --json labels` re-checks `bkit:auto` (live kill switch); then dispatches `claude-code-action` as the Claude GitHub App (OIDC, `id-token: write`). | Claude credential: GitHub repo secret `ANTHROPIC_API_KEY` (`.bkit/.env` holds the same value as `BKIT_ANTHROPIC_API_KEY`) **or** keyless federation repo variables (§ Claude — workload identity federation). Claude GitHub App required (`/install-github-app`). The linked **GitHub issue** must carry `bkit:auto`. |
409
- | **opencode** | Same `.github/workflows/bkit-cloud.yml` — `opencode` job (opt-in via `bkit install --auto=opencode`; GitHub-tracker only). Same two-tier gate (same file, separate job). Dispatches via `opencode run "/bkit-auto $PHASE $ARG"`. No `id-token: write` — no OIDC; uses `github.token` for repo ops. | GitHub repo secret: `OPENCODE_PROVIDER_KEY` (set to your provider API key). Provider model committed in `.opencode/opencode.json`. The linked **GitHub issue** must carry `bkit:auto`. |
410
- | **Cursor** | Nothing — Cursor cloud agents have native triggers. | Cursor → Cloud Agents dashboard → Triggers → + Add trigger. Event: CI workflow completion on `feat/**` branches. Prompt (paste **literally**, no edits): `/bkit-auto $CI_STATUS $PR_NUMBER`. Concurrency: latest-supersedes. |
482
+ | **Claude** | `.github/workflows/bkit-cloud.yml` — `claude` job (opt-in via `bkit install --auto=claude`; GitHub-tracker only). Two-tier gate: (1) free tier — job `if: contains(head_commit.message, 'bkit [auto route]')` (zero runner minutes for non-opted-in commits); (2) cheap tier — in-job `gh issue view {ISSUE} --json labels` re-checks `bkit:auto` (live kill switch); then dispatches `claude-code-action` as the Claude GitHub App (OIDC, `id-token: write`). | Claude credential: GitHub repo secret `ANTHROPIC_API_KEY` (`.bkit/.env` holds the same value as `BKIT_ANTHROPIC_API_KEY`) or keyless federation repo variables (§ Claude — workload identity federation). Claude GitHub App required (`/install-github-app`). The linked **GitHub issue** must carry `bkit:auto`. |
483
+ | **Cursor** | Nothing — Cursor cloud agents have native triggers. | Cursor → Cloud Agents dashboard → Triggers → + Add trigger. Event: CI workflow completion on `feat/**` branches. Prompt (paste literally, no edits): `/bkit-auto $CI_STATUS $PR_NUMBER`. Concurrency: latest-supersedes. |
484
+ | **OpenCode** | Same `.github/workflows/bkit-cloud.yml` — `opencode` job (opt-in via `bkit install --auto=opencode`; GitHub-tracker only). Same two-tier gate (same file, separate job). Dispatches via `opencode run "/bkit-auto $PHASE $ARG"`. No `id-token: write` — no OIDC; uses `github.token` for repo ops. | GitHub repo secret: `OPENCODE_PROVIDER_KEY` (set to your provider API key). Provider model committed in `.opencode/opencode.json`. The linked **GitHub issue** must carry `bkit:auto`. |
411
485
 
412
- **Why dashboard prompt never needs re-pasting:** Cursor substitutes `$CI_STATUS` and `$PR_NUMBER` from event payload at dispatch. Pasted string generic and timeless. When bkit routing logic evolves, only mirrored `.cursor/commands/bkit-auto.md` changes — dashboard untouched.
486
+ **Why the dashboard prompt never needs re-pasting:** Cursor substitutes `$CI_STATUS` and `$PR_NUMBER` from the event payload at dispatch, so the pasted string is generic and timeless. When bkit's routing logic evolves, only the mirrored `.cursor/commands/bkit-auto.md` changes, and the dashboard stays untouched.
413
487
 
414
488
  ## Cursor dashboard — exact paste
415
489
 
@@ -419,32 +493,39 @@ Routing **logic** in single bkit-managed slash-command orchestrator (`.bkit/core
419
493
 
420
494
  ## Claude — required GitHub Actions permissions
421
495
 
422
- Flip **both** org and repo before first router run — else `actions/checkout` 403s with `Write access to repository not granted`. Workflow declares `permissions: contents: write` at workflow scope, but org/repo "Workflow permissions" ceiling overrides — repo cannot exceed org.
496
+ Flip the setting on both the org and the repo before the first router run. Otherwise `actions/checkout` 403s with `Write access to repository not granted`. The workflow declares `permissions: contents: write` at workflow scope, but the org / repo "Workflow permissions" ceiling overrides it, and the repo cannot exceed the org.
423
497
 
424
498
  - **Org**: `https://github.com/organizations/{ORG}/settings/actions` → Workflow permissions → **Read and write permissions** + tick **Allow GitHub Actions to create and approve pull requests**.
425
- - **Repo**: `https://github.com/{ORG}/{REPO}/settings/actions` → same section, same two settings. Apply at repo too — inheriting from org not automatic.
499
+ - **Repo**: `https://github.com/{ORG}/{REPO}/settings/actions` → the same section, the same two settings. Apply them at the repo too, because inheriting from the org is not automatic.
426
500
 
427
- `workflow_run`-triggered runs do **not** inherit parent CI workflow's `permissions:` block (only fork-PR tokens get narrowed) — parent CI at `contents: read` fine.
501
+ `workflow_run`-triggered runs do not inherit the parent CI workflow's `permissions:` block (only fork-PR tokens get narrowed), so a parent CI at `contents: read` is fine.
428
502
 
429
503
  ## bkit-cloud.yml — required GitHub repo credentials
430
504
 
431
505
  <!-- prettier-ignore -->
432
506
  | Secret / variable | Job | Why | Scope |
433
507
  | --- | --- | --- | --- |
434
- | `ANTHROPIC_API_KEY` secret | `claude` | `claude-code-action` authenticates against Anthropic. | API key with Claude Code access. Omit when using federation. |
508
+ | `ANTHROPIC_API_KEY` secret | `claude` | `claude-code-action` authenticates against Anthropic. | API key with Claude access. Omit when using federation. |
435
509
  | `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` variables | `claude` | Keyless alternative: the action trades the job's GitHub OIDC token for a short-lived Claude API token. | IDs, not secrets — repo **variables**. Optional `ANTHROPIC_SERVICE_ACCOUNT_ID` / `ANTHROPIC_WORKSPACE_ID`. § Claude — workload identity federation. |
436
510
  | `OPENCODE_PROVIDER_KEY` | `opencode` | Fanned out to every cloud provider's env var name (`BKIT_OPENROUTER_API_KEY`, `BKIT_OLLAMA_API_KEY`, `BKIT_OPENCODE_API_KEY`) so the `.opencode/opencode.json` `{env:VAR}` reference resolves whichever provider is installed. | Provider API key for whichever provider you configured. |
437
511
 
438
- A `context` job (`Check runner credentials` step) checks both credentials and resolves phase + arg once, no-op unless `package.json` `bkit.issueTracker` is `github` or unset (Linear cloud runs start from Cursor's Linear integration; Jira runs locally only); each runner job needs it and runs only when its own credential is set. Claude credential = `ANTHROPIC_API_KEY`, or **both** federation variables (one alone → `::notice::` naming the missing one, claude no-op). Only claude credential → claude job only. Only `OPENCODE_PROVIDER_KEY` → opencode only. Both → both jobs (additive coexistence). **No `BKIT_LINEAR_API_KEY`** — `bkit-cloud.yml` GitHub-tracker only for both jobs. Workflow grants `id-token: write` per-job for claude only (Claude GitHub App + federation token exchange; opencode no OIDC).
512
+ A `context` job (`Check runner credentials` step) checks both credentials and resolves the phase + arg once. It does nothing unless `package.json` `bkit.tracker.default` is `github` or unset, because Linear cloud runs start from Cursor's Linear integration and Jira runs locally only. Each runner job needs it, and runs only when its own credential is set:
513
+
514
+ - The Claude credential is `ANTHROPIC_API_KEY`, or both federation variables. With only one of the two variables set, the job prints a `::notice::` naming the missing one, and the claude job does nothing.
515
+ - Only the claude credential set → only the claude job runs.
516
+ - Only `OPENCODE_PROVIDER_KEY` set → only the OpenCode job runs.
517
+ - Both set → both jobs run (additive coexistence).
518
+
519
+ No `BKIT_LINEAR_API_KEY` is needed, because `bkit-cloud.yml` is GitHub-tracker only for both jobs. The workflow grants `id-token: write` per job, for claude only (Claude GitHub App + federation token exchange). OpenCode has no OIDC.
439
520
 
440
521
  ## Claude — workload identity federation
441
522
 
442
- Keyless claude job: no long-lived `ANTHROPIC_API_KEY` stored in GitHub. `claude-code-action` asks GitHub for the job's OIDC token (issuer `https://token.actions.githubusercontent.com`, audience `https://api.anthropic.com`), Anthropic checks it against a federation rule, returns a short-lived Claude API token. Action refreshes it in the background on long runs.
523
+ The keyless claude job stores no long-lived `ANTHROPIC_API_KEY` in GitHub. `claude-code-action` asks GitHub for the job's OIDC token (issuer `https://token.actions.githubusercontent.com`, audience `https://api.anthropic.com`). Anthropic checks it against a federation rule and returns a short-lived Claude API token. The action refreshes it in the background on long runs.
443
524
 
444
525
  **Setup (one-time):**
445
526
 
446
- 1. Claude Console → **Settings → Workload identity → Connect workload → GitHub Actions**. Creates the federation issuer, a service account, and a federation rule.
447
- 2. Scope the rule to this repo's default branch — `bkit-cloud.yml` runs from it (`workflow_run` + `workflow_dispatch`):
527
+ 1. Claude Console → **Settings → Workload identity → Connect workload → GitHub Actions**. This creates the federation issuer, a service account, and a federation rule.
528
+ 2. Scope the rule to this repo's default branch, because `bkit-cloud.yml` runs from it (`workflow_run` + `workflow_dispatch`):
448
529
  - `subject_prefix`: `repo:<owner>/<repo>:ref:refs/heads/<default-branch>`
449
530
  - claims: `repository_owner` = `<owner>`, `ref` = `refs/heads/<default-branch>`
450
531
  - to limit the rule to `bkit-cloud.yml`, add claim `workflow_ref` = `<owner>/<repo>/.github/workflows/bkit-cloud.yml@refs/heads/<default-branch>`. GitHub's token carries it; Anthropic's docs do not list it as matchable. Without it, every workflow on the default branch matches the rule.
@@ -454,70 +535,77 @@ Keyless claude job: no long-lived `ANTHROPIC_API_KEY` stored in GitHub. `claude-
454
535
  gh variable set ANTHROPIC_ORGANIZATION_ID --body='<organization-uuid>'
455
536
  # optional: ANTHROPIC_SERVICE_ACCOUNT_ID (svac_...), ANTHROPIC_WORKSPACE_ID
456
537
  ```
457
- 4. Delete the key if one is set: `gh secret delete ANTHROPIC_API_KEY`. **A set key wins over federation** — the action uses the key and federation never runs. `bkit check` flags both-set (`anthropic-api-key-shadows-federation`).
538
+ 4. Delete the key if one is set: `gh secret delete ANTHROPIC_API_KEY`. **A set key wins over federation:** the action uses the key, and federation never runs. `bkit check` flags both being set (`anthropic-api-key-shadows-federation`).
458
539
 
459
- **Adopted copy predates federation:** variables set but `.github/workflows/bkit-cloud.yml` lacks the `anthropic_federation_rule_id:` input → claude job sees no credential. `bkit check` flags it (`anthropic-federation-template-stale`); re-copy from `.bkit/templates/.github/workflows/bkit-cloud.yml`, re-apply local edits (`runs-on`).
540
+ **Adopted copy predates federation:** The variables are set, but `.github/workflows/bkit-cloud.yml` lacks the `anthropic_federation_rule_id:` input, so the claude job sees no credential. `bkit check` flags it (`anthropic-federation-template-stale`). Re-copy from `.bkit/templates/.github/workflows/bkit-cloud.yml`, then re-apply your local edits (`runs-on`).
460
541
 
461
- **401 from token exchange:** Anthropic returns `401 Authentication failed` whichever check failed. Console → Workload identity → authentication history shows the deny reason per attempt; `match_subject_prefix` = the run's `sub` doesn't match the rule's `subject_prefix` — fix or widen the rule. A job on a non-default branch or an `environment:` has a different subject (`...:ref:refs/heads/<branch>` / `...:environment:<name>`).
542
+ **401 from token exchange:** Anthropic returns `401 Authentication failed` whichever check failed. Console → Workload identity → authentication history shows the deny reason per attempt. `match_subject_prefix` means the run's `sub` doesn't match the rule's `subject_prefix`: fix or widen the rule. A job on a non-default branch or an `environment:` has a different subject (`...:ref:refs/heads/<branch>` / `...:environment:<name>`).
462
543
 
463
- Slash command body already in checked-out repo (mirrored to `.claude/commands/bkit-auto.md` and `.opencode/commands/bkit-auto.md` at dev time via `bkit install`). Repo git/gh ops use auto-provided `github.token` scoped by workflow `permissions:` block.
544
+ The slash command body is already in the checked-out repo (mirrored to `.claude/commands/bkit-auto.md` and `.opencode/commands/bkit-auto.md` at dev time by `bkit install`). Repo git / gh ops use the auto-provided `github.token`, scoped by the workflow's `permissions:` block.
464
545
 
465
546
  ## Branch-aware routing
466
547
 
467
- `bkit-cloud.yml`'s `workflow_run` trigger covers `feat/**` and `dev`. `main` is never auto-routed — `dev` -> `main` promotion stays manual.
548
+ `bkit-cloud.yml`'s `workflow_run` trigger covers `feat/**` and `dev`. `main` is never auto-routed, so `dev` → `main` promotion stays manual.
468
549
 
469
550
  <!-- prettier-ignore -->
470
551
  | CI trigger | success | failure |
471
552
  | --- | --- | --- |
472
- | `feat/**` (pre-merge) | -> `/bkit-ship` | -> `/bkit-debug` |
473
- | `dev` (post-merge) | no-op — the merge already happened | -> `/bkit-debug {FID}` (capped) |
553
+ | `feat/**` (pre-merge) | → `/bkit-ship` | → `/bkit-debug` |
554
+ | `dev` (post-merge) | no-op — the merge already happened | → `/bkit-debug {FID}` (capped) |
474
555
  | `main` | manual only | manual only |
475
556
 
476
- **Build still running (`feat/**`):** before dispatch, read the branch's `docs/plans/*/logs/{FID}/status.jsonl` from `origin`:
557
+ **Build still running (`feat/**`):** Before dispatch, read the branch's `docs/plans/*/logs/{FID}/status.jsonl` from `origin`:
477
558
 
478
- - `build` `workflow-started`, no later `workflow-done` / `workflow-failed`, newest build row < 30 min old → `/bkit-build` owns the branch → no-op.
479
- - Newest build row >= 30 min old → abandoned → dispatch.
480
- - No file / unreadable → dispatch.
559
+ - A `build` `workflow-started` row with no later `workflow-done` / `workflow-failed`, and the newest build row < 30 min old → `/bkit-build` owns the branch → no-op.
560
+ - The newest build row >= 30 min old → abandoned → dispatch.
561
+ - No file, or an unreadable one → dispatch.
481
562
 
482
- The post-merge `dev` surface reuses the same free-tier gate: `/bkit-ship` threads ` bkit [auto route]` onto the PR squash-merge `--subject` when the issue carries `bkit:auto`, so the commit that lands on `dev` — and triggers post-merge CI — already carries the marker the gate checks.
563
+ The post-merge `dev` surface reuses the same free-tier gate. When the issue carries `bkit:auto`, `/bkit-ship` threads ` bkit [auto route]` onto the PR squash-merge `--subject`, so the commit that lands on `dev`, and triggers post-merge CI, already carries the marker the gate checks.
483
564
 
484
565
  ## Routing decision (router orchestrator)
485
566
 
486
- Slash command takes two args: `$CI_STATUS` ∈ `{success, failure, pass, fail}` (normalised) and `$ARG` — a PR number (pre-merge) or a `{FID}` slug (post-merge `dev`, no open PR). Then:
567
+ The slash command takes two args: `$CI_STATUS` in `success|failure|pass|fail` (normalised), and `$ARG`, which is a PR number (pre-merge) or a `{FID}` slug (post-merge `dev`, no open PR). Then:
487
568
 
488
- 1. PR-number arg: reads `gh pr view $ARG` for `headRefName`, `headRefOid`, `state`. Refuses non-open PRs. Slug arg: skips the PR lookup entirely.
489
- 2. Extracts `{FID}` from the head branch (`feat/{FID}` convention). Slug arg: `{ARG}` is the `{FID}`, allowlist-asserted before use. On the `dev` surface the workflow recovers it from the squash-merge commit scope (`feat({FID}): …`, tracker-agnostic), falling back to the linked PR body's `bkit:fid=` marker; either path failing → no-op, no dispatch.
490
- 3. Stale-run guard. Pre-merge: compares latest CI run's `headSha` against the PR's current `headRefOid`. Post-merge `dev`: compares the most recently COMPLETED `dev` CI run's `headSha` against the triggering run's head SHA — a `git rev-parse origin/dev` comparison would mismatch on every legitimate dispatch, because ship's terminal close commit lands on `dev` while that CI run is still going. Close commits carry `[skip ci]`, so they never trigger CI and never become that most-recent-completed head. An empty run list fails open (dispatches).
491
- 4. Opt-in gate: refuses dispatch unless linked GitHub issue carries `bkit:auto` label.
492
- 5. Appends `bkit-auto → /bkit-{ship,debug}` line to GitHub issue / PR comment thread.
493
- 6. Invokes `/bkit-ship {FID}` (CI pass) or `/bkit-debug {FID} DEBUG_MODE=pr` (CI fail) via `Skill` / `Task` tool. Dispatched skill owns session lifecycle from there.
569
+ 1. With a PR-number arg, it reads `gh pr view $ARG` for `headRefName`, `headRefOid`, `state`, and refuses non-open PRs. With a slug arg, it skips the PR lookup entirely.
570
+ 2. It extracts `{FID}` from the head branch (`feat/{FID}` convention). With a slug arg, `{ARG}` is the `{FID}`, allowlist-asserted before use. On the `dev` surface the workflow recovers it from the squash-merge commit scope (`feat({FID}): …`, tracker-agnostic), and falls back to the linked PR body's `bkit:fid=` marker. If either path fails → no-op, no dispatch.
571
+ 3. Stale-run guard. Pre-merge, it compares the latest CI run's `headSha` against the PR's current `headRefOid`. Post-merge on `dev`, it compares the most recently completed `dev` CI run's `headSha` against the triggering run's head SHA. A `git rev-parse origin/dev` comparison would mismatch on every legitimate dispatch, because ship's terminal close commit lands on `dev` while that CI run is still going. Close commits carry `[skip ci]`, so they never trigger CI and never become that most-recent-completed head. An empty run list fails open (dispatches).
572
+ 4. Opt-in gate: it refuses dispatch unless the linked GitHub issue carries the `bkit:auto` label.
573
+ 5. It appends a `bkit-auto → /bkit-{ship,debug}` line to the GitHub issue / PR comment thread.
574
+ 6. It invokes `/bkit-ship {FID}` (CI pass) or `/bkit-debug {FID} DEBUG_MODE=pr` (CI fail) through the `Skill` / `Task` tool. The dispatched skill owns the session lifecycle from there.
494
575
 
495
- Skip conditions emit single GitHub-comment no-op line and exit 0 — only real failures (missing args, GitHub API unreachable, malformed state) take Failure Path.
576
+ Skip conditions emit a single GitHub-comment no-op line and exit 0. Only real failures (missing args, GitHub API unreachable, malformed state) take the Failure Path.
496
577
 
497
578
  ## Operating notes
498
579
 
499
- - **Loop bound (pre-merge `feat/**`):** `/bkit-debug` enforces `MAX_DEBUG_ATTEMPT = 3` internally; router never counts attempts. After three red CI runs, debug fires handover path and stops dispatching.
500
- - **Loop bound (`dev`):** `MAX_DEV_DISPATCH_ATTEMPTS = 3` distinct failed CI SHAs per `{FID}`, all-time. This is the surface that needs a cross-session cap: `/bkit-debug` adopts `dev` in place, so its fix push re-reds `dev` CI and re-triggers this same router. Checked and written by the ctx step of `bkit-cloud.yml`'s `context` job immediately before dispatch — the in-session counters reset on every new cloud dispatch and cannot bound a cross-session loop. The counter row (`type: "dev-dispatch"`) is committed to `dev` with `[skip ci]` before dispatch, and its presence on `origin/dev` is verified after one retry — a row landing nowhere durable would degrade the cap to unbounded. Exhausted → no-op + `::notice::` for operator review (delete the rows in `status.jsonl` to reset).
501
- - **GHA 6 h cap:** `3 x ~3600s` per debug attempt = well under GHA runner ceiling. Ship is short.
502
- - **Concurrency:** `cancel-in-progress` is `true` for `feat/**` (latest-wins) and `false` for `dev`, so an in-flight `/bkit-debug` finishes instead of being cancelled mid-run with a half-written `status.jsonl` or a held worktree lock. GHA queues at most one pending run per group; the queued run re-checks the dispatch cap when it starts, so the same `{FID}` needs no manual re-trigger. Cursor dashboard trigger → "latest-supersedes." Ship squash-merge atomic — mid-run cancels cannot corrupt PR state.
503
- - **`bkit-auto-dev` is one concurrency group for all FIDs.** GHA resolves `concurrency.group` from trigger-payload context before the ctx step derives the `{FID}`, so the group cannot be keyed on it. Two different FIDs failing `dev` CI near-simultaneously → queue-collapse can drop the older, different FID's pending run. The stale-run guard detects it (its head SHA no longer matches the most-recent-completed `dev` CI run) and writes a `dev-dispatch-dropped` row to the job summary plus a `::warning::`, rather than discarding it silently. Job summary, not a committed `status.jsonl`: this branch is only reached because `dev` already advanced, so committing the row would usually be a non-fast-forward and be lost in exactly the case it records.
504
- - **Both clouds together:** nothing stops Claude + Cursor dispatching against same PR — they'd race. Pick one IDE per repo as auto-router (recommended: Claude via GHA, runner-resident and Anthropic-maintained). Leave Cursor for ad-hoc Linear-dispatch work.
580
+ - **Loop bound (pre-merge `feat/**`):** `/bkit-debug` enforces `bkit.workflows.debug.fix` and `.soak` `maxAttempts` internally, counted across every debug run of the feature. The router never counts attempts. Once the fix attempts are used up, debug switches to soak. Once the soak attempts are used up, it takes the Failure Path (handover) and stops.
581
+ - **Loop bound (`dev`):** The cap is `bkit.workflows.debug.fix.maxAttempts` + `bkit.workflows.debug.soak.maxAttempts` (2 + 2 by default) distinct failed CI SHAs per `{FID}`, all-time. Every debug run makes at least one attempt, so more dispatches could never run one.
582
+ - The router reads both values from `package.json` with `jq`, because bkit is not installed at that point. It falls back to 2 for a missing or bad value, as the engine does.
583
+ - This is the surface that needs a cross-session cap. `/bkit-debug` adopts `dev` in place, so its fix push re-reds `dev` CI and re-triggers this same router.
584
+ - The ctx step of `bkit-cloud.yml`'s `context` job checks and writes the cap immediately before dispatch, so a run that could not record its own attempts is still bounded.
585
+ - The counter row (`type: "dev-dispatch"`) is committed to `dev` with `[skip ci]` before dispatch, and its presence on `origin/dev` is verified after one retry. A row that lands nowhere durable would make the cap unbounded.
586
+ - When the cap is used up → no-op + `::notice::` for operator review. Delete the rows in `status.jsonl` to reset it.
587
+ - **GitHub Actions runtime limit:** The host's job limit still applies. bkit bounds attempts and command waits, and sets no universal workflow-step deadline; the attempt count alone does not bound the job's duration.
588
+ - **Concurrency:** `cancel-in-progress` is `true` for `feat/**` (latest-wins) and `false` for `dev`, so an in-flight `/bkit-debug` finishes instead of being cancelled mid-run with a half-written `status.jsonl` or a held worktree lock. GHA queues at most one pending run per group. The queued run re-checks the dispatch cap when it starts, so the same `{FID}` needs no manual re-trigger. The Cursor dashboard trigger is "latest-supersedes." The ship squash-merge is atomic, so mid-run cancels cannot corrupt PR state.
589
+ - **`bkit-auto-dev` is one concurrency group for all FIDs.** GHA resolves `concurrency.group` from the trigger-payload context before the ctx step derives the `{FID}`, so the group cannot be keyed on it. When two different FIDs fail `dev` CI near-simultaneously, queue-collapse can drop the older, different FID's pending run. The stale-run guard detects it (its head SHA no longer matches the most-recent-completed `dev` CI run) and writes a `dev-dispatch-dropped` row to the job summary plus a `::warning::`, rather than discarding it silently. The row goes to the job summary, not a committed `status.jsonl`, because this branch is reached only when `dev` has already advanced. Committing the row would usually be a non-fast-forward, and the row would be lost in exactly the case it records.
590
+ - **Both clouds together:** Nothing stops Claude + Cursor from dispatching against the same PR, and they would race. Pick one IDE per repo as the auto-router. The recommendation is Claude via GHA, which is runner-resident and Anthropic-maintained. Leave Cursor for ad-hoc Linear-dispatch work.
505
591
 
506
592
  # Caveats (both clouds)
507
593
 
508
- - **No secrets store yet (Claude).** Env vars and setup-script body plaintext in Claude app. Rotate PATs regularly.
509
- - **Env vars do not reach Claude setup script.** Auth at snapshot-build time must be inlined — leak you want to avoid. Design around it: public binaries in setup script; defer auth-bearing work to SessionStart hook.
510
- - **Cache invalidation is body-based (Claude).** Editing env-vars block or repo-side hook scripts doesn't trigger rebuild. Use `# cache-bust YYYY-MM-DD-N` to force one.
511
- - **Husky runs on `pnpm install`** (repos that adopted the `.husky/*` templates). `prepare` registers git hooks during install. The pre-commit hook (`bkit:gate:format` → `lint-staged`) runs when agent commits. `slop-scan` devDep → PATH via `node_modules/.bin`; `vale` system binary → setup script (Claude) or Dockerfile (Cursor).
512
- - **Bun proxy issues (Claude).** Bun known proxy issues with cloud security proxy. bkit uses pnpm — unaffected; flag for bun consumers.
513
- - **Custom base image not supported (Claude).** Escape hatch: `docker compose` sidecars. Not needed for bkit stack today.
514
- - **Cursor image cache layer-based.** Reorder `RUN` lines carefully — frequently-changing line above slow one invalidates cache below.
515
- - **GitHub App vs `/web-setup` (Claude).** Auto-fix PRs require GitHub App. `/web-setup` (sync `gh` token to Claude account) enough for clone + push, not auto-fix.
516
- - **IP allowlists** on org GitHub / Anthropic accounts block cloud sessions — contact support to exempt managed infra.
594
+ - **No secrets store yet (Claude).** Env vars and the setup-script body are plaintext in the Claude app. Rotate PATs regularly.
595
+ - **Env vars do not reach Claude setup script.** Auth at snapshot-build time would have to be inlined, which is the leak you want to avoid. Design around it: put public binaries in the setup script, and leave auth-bearing work to the SessionStart hook.
596
+ - **Cache invalidation is body-based (Claude).** Editing the env-vars block or the repo-side hook scripts doesn't trigger a rebuild. To force one, run `bkit install` or `bkit upgrade`, which re-stamps the `# cache-bust` line, then paste the new setup script.
597
+ - **Husky runs on `pnpm install`** (repos that adopted the `.husky/*` templates). `prepare` registers git hooks during install. The pre-commit hook (`bkit:gate:format` → `lint-staged`) runs when the agent commits. The `slop-scan` devDep reaches PATH through `node_modules/.bin`. The `vale` system binary comes from the setup script (Claude) or the Dockerfile (Cursor).
598
+ - **Bun proxy issues (Claude).** Bun has known proxy issues with the cloud security proxy. bkit uses pnpm, so it is unaffected. Flag this for bun consumers.
599
+ - **Custom base image not supported (Claude).** The escape hatch is `docker compose` sidecars. The bkit stack does not need it today.
600
+ - **Cursor image cache layer-based.** Reorder `RUN` lines carefully, because a frequently-changing line above a slow one invalidates the cache below it.
601
+ - **GitHub App vs `/web-setup` (Claude).** Auto-fix PRs require the GitHub App. `/web-setup` (syncs the `gh` token to the Claude account) is enough for clone + push, but not for auto-fix.
602
+ - **IP allowlists** on org GitHub / Anthropic accounts block cloud sessions. Contact support to exempt managed infra.
603
+ - **Hooks unproven (Codex Cloud).** Cloud tasks have no documented hook support, so there is no GateGuard / guardrails guarantee there (§ Codex Cloud → Hooks in cloud tasks).
517
604
 
518
605
  # Sources
519
606
 
520
607
  - Anthropic docs: <https://code.claude.com/docs/en/claude-code-on-the-web>
608
+ - Codex Cloud environments: <https://learn.chatgpt.com/docs/environments/cloud-environments>
521
609
  - Cursor Cloud Agents: <https://cursor.com/docs/cloud-agent/setup>
522
- - Zenn article on Claude env-var/setup-script gotcha: <https://zenn.dev/harieshokunin/articles/b1064354319ce2?locale=en>
610
+ - Zenn article on Claude env-var / setup-script gotcha: <https://zenn.dev/harieshokunin/articles/b1064354319ce2?locale=en>
523
611
  - Managed Agents environments (separate product, similar shape): <https://platform.claude.com/docs/en/managed-agents/environments>