@cbartens/bkit 6.0.0 → 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 (375) hide show
  1. package/.bkit/README.md +154 -151
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +17 -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 +108 -107
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +154 -151
  11. package/.bkit/core/.bkit/authoring.md +714 -84
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +281 -193
  14. package/.bkit/core/.bkit/comparison.md +43 -41
  15. package/.bkit/core/.bkit/install.md +154 -84
  16. package/.bkit/core/.bkit/jsonl.md +193 -130
  17. package/.bkit/core/.bkit/pipeline.md +114 -114
  18. package/.bkit/core/.bkit/prompts.md +272 -165
  19. package/.bkit/core/.bkit/providers.md +457 -271
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +529 -256
  22. package/.bkit/core/.bkit/trackers.md +80 -52
  23. package/.bkit/core/.bkit/workflows.md +589 -504
  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 +5 -73
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +127 -105
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -70
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +94 -72
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +99 -78
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +140 -82
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +98 -72
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +121 -96
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +157 -76
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +113 -71
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +75 -72
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +122 -76
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +85 -74
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +75 -68
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +101 -70
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +164 -83
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -86
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +264 -88
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +118 -93
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +139 -86
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +110 -81
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +99 -74
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +105 -77
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +104 -80
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +131 -58
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +123 -100
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +98 -53
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -52
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -54
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +124 -68
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +95 -70
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +169 -73
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +206 -96
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +77 -70
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +162 -114
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +113 -71
  68. package/.bkit/core/docs/templates/bkit-plan.md +138 -132
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +65 -2
  71. package/.bkit/core/engine/checks/after/index.ts +12 -2
  72. package/.bkit/core/engine/checks/after/tools.ts +80 -33
  73. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  74. package/.bkit/core/engine/checks/before/env.ts +1 -1
  75. package/.bkit/core/engine/checks/before/index.ts +7 -0
  76. package/.bkit/core/engine/checks/before/repo.ts +40 -0
  77. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  78. package/.bkit/core/engine/checks/tips/catalogue.ts +68 -17
  79. package/.bkit/core/engine/checks/tips/detect.ts +32 -0
  80. package/.bkit/core/engine/checks/tips/index.ts +47 -6
  81. package/.bkit/core/engine/cli.ts +238 -84
  82. package/.bkit/core/engine/commands/analysis.ts +128 -76
  83. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  84. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  85. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  86. package/.bkit/core/engine/commands/install/uninstall.ts +21 -27
  87. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  88. package/.bkit/core/engine/commands/land.ts +126 -11
  89. package/.bkit/core/engine/commands/lib.ts +303 -6
  90. package/.bkit/core/engine/commands/registry.ts +6 -2
  91. package/.bkit/core/engine/commands/setup/setup.ts +1 -0
  92. package/.bkit/core/engine/commands/stats.ts +91 -35
  93. package/.bkit/core/engine/commands/workflow/branches.ts +1477 -117
  94. package/.bkit/core/engine/commands/workflow/challenge.ts +114 -39
  95. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  96. package/.bkit/core/engine/commands/workflow/context.ts +433 -55
  97. package/.bkit/core/engine/commands/workflow/counters.ts +244 -39
  98. package/.bkit/core/engine/commands/workflow/decisions.ts +61 -17
  99. package/.bkit/core/engine/commands/workflow/disk.ts +237 -55
  100. package/.bkit/core/engine/commands/workflow/fids.ts +19 -1
  101. package/.bkit/core/engine/commands/workflow/issues.ts +6 -0
  102. package/.bkit/core/engine/commands/workflow/ledgers.ts +458 -18
  103. package/.bkit/core/engine/commands/workflow/locks.ts +2 -0
  104. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +124 -15
  105. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  106. package/.bkit/core/engine/commands/workflow/prs.ts +12 -3
  107. package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
  108. package/.bkit/core/engine/commands/workflow/roadmap.ts +56 -15
  109. package/.bkit/core/engine/commands/workflow/run-facts.ts +22 -31
  110. package/.bkit/core/engine/commands/workflow/runs.ts +652 -34
  111. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -0
  112. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  113. package/.bkit/core/engine/commands/workflow/status.ts +200 -17
  114. package/.bkit/core/engine/commands/workflow/step-table.ts +75 -33
  115. package/.bkit/core/engine/commands/workflow/steps.ts +635 -24
  116. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  117. package/.bkit/core/engine/commands/workflow/summary.ts +192 -46
  118. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  119. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  120. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  121. package/.bkit/core/engine/commands/workflow/tests.ts +1285 -356
  122. package/.bkit/core/engine/commands/workflow/workflows.ts +228 -43
  123. package/.bkit/core/engine/commands/workflow/worktrees.ts +389 -47
  124. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  125. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  126. package/.bkit/core/engine/install/manifest.ts +60 -12
  127. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  128. package/.bkit/core/engine/install/modules/cloud.ts +3 -3
  129. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  130. package/.bkit/core/engine/install/modules/core.ts +956 -52
  131. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  132. package/.bkit/core/engine/install/modules/opencode.ts +16 -4
  133. package/.bkit/core/engine/install/template-notes.ts +130 -0
  134. package/.bkit/core/engine/install/version-file.ts +3 -2
  135. package/.bkit/core/engine/install/write.ts +5 -0
  136. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  137. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  138. package/.bkit/core/engine/ledgers/status.ts +160 -9
  139. package/.bkit/core/engine/ledgers/telemetry.ts +158 -21
  140. package/.bkit/core/engine/render/hosts.ts +114 -14
  141. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  142. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  143. package/.bkit/core/engine/shared/egress.ts +1 -1
  144. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  145. package/.bkit/core/engine/shared/settings.ts +92 -17
  146. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  147. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  148. package/.bkit/core/engine/tools/grammar-density.ts +1 -1
  149. package/.bkit/core/engine/tools/instructions-sources.ts +15 -17
  150. package/.bkit/core/engine/tools/instructions.ts +94 -43
  151. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  152. package/.bkit/core/hooks/gateguard-engine.js +53 -29
  153. package/.bkit/core/hooks/guardrails-shell.js +4 -4
  154. package/.bkit/core/hooks/guardrails-tiers.js +3 -3
  155. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  156. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  157. package/.bkit/core/hooks/readguard-engine.js +29 -10
  158. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  159. package/.bkit/core/prompts/bkit-audit-generate.md +187 -116
  160. package/.bkit/core/prompts/bkit-build-challenge-1.md +56 -37
  161. package/.bkit/core/prompts/bkit-build-challenge-2.md +65 -45
  162. package/.bkit/core/prompts/bkit-build-install-skills.md +38 -29
  163. package/.bkit/core/prompts/bkit-build-plan-convert.md +43 -32
  164. package/.bkit/core/prompts/bkit-build-plan-current.md +49 -39
  165. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +79 -55
  166. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  167. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  168. package/.bkit/core/prompts/bkit-build-plan-verify.md +87 -50
  169. package/.bkit/core/prompts/bkit-debug-abort-handover.md +36 -35
  170. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +96 -64
  171. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +54 -45
  172. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +42 -33
  173. package/.bkit/core/prompts/bkit-debug-failure-soak.md +53 -37
  174. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +35 -30
  175. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +34 -29
  176. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +32 -28
  177. package/.bkit/core/prompts/bkit-design-generate.md +68 -52
  178. package/.bkit/core/prompts/bkit-design-organise.md +73 -35
  179. package/.bkit/core/prompts/bkit-design-review-1.md +58 -54
  180. package/.bkit/core/prompts/bkit-design-review-2.md +54 -50
  181. package/.bkit/core/prompts/bkit-design-spike.md +54 -47
  182. package/.bkit/core/prompts/bkit-design-update.md +42 -31
  183. package/.bkit/core/prompts/bkit-plan-generate.md +76 -58
  184. package/.bkit/core/prompts/bkit-plan-review-1.md +63 -49
  185. package/.bkit/core/prompts/bkit-plan-review-2.md +60 -48
  186. package/.bkit/core/prompts/bkit-plan-scope-check.md +53 -46
  187. package/.bkit/core/prompts/bkit-plan-update.md +70 -52
  188. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +82 -50
  189. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +80 -45
  190. package/.bkit/core/prompts/bkit-ship-update-docs.md +35 -29
  191. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +55 -49
  192. package/.bkit/core/prompts/bkit-utility-update-decisions.md +76 -49
  193. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +70 -41
  194. package/.bkit/core/prompts/bkit-utility-update-documentation.md +33 -30
  195. package/.bkit/core/prompts/bkit-utility-update-failures.md +73 -43
  196. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +77 -50
  197. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +77 -45
  198. package/.bkit/core/prompts/bkit-utility-update-tracker.md +144 -68
  199. package/.bkit/core/workflows/bkit-auto.md +53 -30
  200. package/.bkit/core/workflows/bkit-build.md +635 -304
  201. package/.bkit/core/workflows/bkit-debug.md +301 -148
  202. package/.bkit/core/workflows/bkit-design.md +167 -95
  203. package/.bkit/core/workflows/bkit-plan.md +172 -84
  204. package/.bkit/core/workflows/bkit-ship.md +299 -152
  205. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  206. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  207. package/.bkit/shared/.claude/settings.json +3 -0
  208. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  209. package/.bkit/shared/.codex/hooks.json +20 -0
  210. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  211. package/.bkit/shared/.opencode/opencode.json +1 -1
  212. package/.bkit/shared/CLAUDE.md +5 -1
  213. package/.bkit/shared/GEMINI.md +4 -1
  214. package/.bkit/shared/docs/architecture.md +4 -7
  215. package/.bkit/shared/docs/data-schema.md +4 -7
  216. package/.bkit/shared/docs/deployments.md +239 -166
  217. package/.bkit/shared/docs/design.md +11 -12
  218. package/.bkit/shared/docs/noise.md +8 -7
  219. package/.bkit/shared/docs/observability.md +5 -8
  220. package/.bkit/shared/docs/security.md +35 -17
  221. package/.bkit/shared/docs/setup.md +29 -18
  222. package/.bkit/shared/docs/technology.md +3 -6
  223. package/.bkit/shared/docs/testing.md +282 -176
  224. package/.bkit/shared/gitignore +6 -2
  225. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  226. package/.bkit/templates/.cursor/Dockerfile +12 -8
  227. package/.bkit/templates/.cursor/environment.json +1 -1
  228. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  229. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +24 -12
  230. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  231. package/.bkit/templates/.github/renovate.json5 +34 -6
  232. package/.bkit/templates/.github/workflows/bkit-ci.yml +53 -50
  233. package/.bkit/templates/.github/workflows/bkit-cloud.yml +13 -14
  234. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  235. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  236. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  237. package/.bkit/templates/.husky/pre-commit +2 -2
  238. package/.bkit/templates/.husky/pre-push +95 -35
  239. package/.bkit/templates/.prettierignore +6 -7
  240. package/.bkit/templates/.vale.ini +27 -27
  241. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  242. package/.bkit/templates/context/bkit-expo.md +70 -52
  243. package/.bkit/templates/context/bkit-github.md +93 -56
  244. package/.bkit/templates/context/bkit-inngest.md +21 -15
  245. package/.bkit/templates/context/bkit-maestro.md +22 -16
  246. package/.bkit/templates/context/bkit-playwright.md +23 -17
  247. package/.bkit/templates/context/bkit-resend.md +12 -10
  248. package/.bkit/templates/context/bkit-sentry.md +30 -20
  249. package/.bkit/templates/context/bkit-serena.md +8 -7
  250. package/.bkit/templates/context/bkit-stripe.md +14 -13
  251. package/.bkit/templates/context/bkit-supabase.md +16 -13
  252. package/.bkit/templates/context/bkit-tavily.md +14 -11
  253. package/.bkit/templates/context/bkit-vercel.md +27 -18
  254. package/.bkit/templates/docs/capabilities.md +15 -14
  255. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  256. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  257. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  258. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  259. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  260. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  261. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  262. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  263. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  264. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  265. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  266. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +9 -1
  267. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  268. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  269. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  270. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  271. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  272. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  273. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  274. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  275. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  276. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  277. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  278. package/.bkit/templates/slop-scan.config.json +9 -2
  279. package/CHANGELOG.md +119 -0
  280. package/README.md +250 -76
  281. package/dist/checks/after/auth.js +36 -33
  282. package/dist/checks/after/ci-yml.js +52 -2
  283. package/dist/checks/after/index.js +12 -4
  284. package/dist/checks/after/tools.js +73 -33
  285. package/dist/checks/before/context-fetch.js +218 -33
  286. package/dist/checks/before/env.js +1 -1
  287. package/dist/checks/before/index.js +6 -2
  288. package/dist/checks/before/repo.js +35 -1
  289. package/dist/checks/status-holes.js +739 -114
  290. package/dist/checks/tips/catalogue.js +59 -17
  291. package/dist/checks/tips/detect.js +30 -0
  292. package/dist/checks/tips/index.js +48 -6
  293. package/dist/cli.js +222 -84
  294. package/dist/commands/analysis.js +77 -53
  295. package/dist/commands/ci/ci.js +302 -25
  296. package/dist/commands/ci/pins.js +142 -0
  297. package/dist/commands/ci/push-gate.js +194 -0
  298. package/dist/commands/install/uninstall.js +23 -27
  299. package/dist/commands/install/upgrade.js +21 -11
  300. package/dist/commands/land.js +126 -10
  301. package/dist/commands/lib.js +244 -5
  302. package/dist/commands/registry.js +6 -2
  303. package/dist/commands/setup/setup.js +1 -0
  304. package/dist/commands/stats.js +69 -30
  305. package/dist/commands/workflow/branches.js +1232 -111
  306. package/dist/commands/workflow/challenge.js +90 -37
  307. package/dist/commands/workflow/completeness.js +97 -0
  308. package/dist/commands/workflow/context.js +371 -51
  309. package/dist/commands/workflow/counters.js +206 -40
  310. package/dist/commands/workflow/decisions.js +60 -17
  311. package/dist/commands/workflow/disk.js +213 -55
  312. package/dist/commands/workflow/fids.js +18 -1
  313. package/dist/commands/workflow/issues.js +6 -0
  314. package/dist/commands/workflow/ledgers.js +372 -21
  315. package/dist/commands/workflow/locks.js +2 -0
  316. package/dist/commands/workflow/plan-blocks.js +78 -14
  317. package/dist/commands/workflow/plans.js +205 -0
  318. package/dist/commands/workflow/prs.js +12 -3
  319. package/dist/commands/workflow/repo.js +6 -0
  320. package/dist/commands/workflow/roadmap.js +50 -17
  321. package/dist/commands/workflow/run-facts.js +23 -28
  322. package/dist/commands/workflow/runs.js +530 -33
  323. package/dist/commands/workflow/runtime.js +3 -0
  324. package/dist/commands/workflow/skills.js +1 -0
  325. package/dist/commands/workflow/status.js +166 -19
  326. package/dist/commands/workflow/step-table.js +61 -29
  327. package/dist/commands/workflow/steps.js +542 -26
  328. package/dist/commands/workflow/summary-findings.js +117 -0
  329. package/dist/commands/workflow/summary.js +154 -41
  330. package/dist/commands/workflow/tasks.js +378 -0
  331. package/dist/commands/workflow/test-blocks.js +231 -0
  332. package/dist/commands/workflow/tests-changed.js +172 -0
  333. package/dist/commands/workflow/tests.js +1013 -321
  334. package/dist/commands/workflow/workflows.js +191 -38
  335. package/dist/commands/workflow/worktrees.js +310 -42
  336. package/dist/install/cloud-env.js +233 -99
  337. package/dist/install/context-ci-workflow.js +85 -0
  338. package/dist/install/manifest.js +57 -12
  339. package/dist/install/modules/antigravity.js +3 -2
  340. package/dist/install/modules/cloud.js +3 -3
  341. package/dist/install/modules/codex.js +12 -2
  342. package/dist/install/modules/core.js +851 -53
  343. package/dist/install/modules/cursor.js +6 -6
  344. package/dist/install/modules/opencode.js +11 -5
  345. package/dist/install/template-notes.js +116 -0
  346. package/dist/install/version-file.js +3 -2
  347. package/dist/ledgers/compact.js +87 -0
  348. package/dist/ledgers/journal.js +233 -0
  349. package/dist/ledgers/status.js +115 -5
  350. package/dist/ledgers/telemetry.js +121 -17
  351. package/dist/render/hosts.js +100 -14
  352. package/dist/shared/bkit-latest.js +26 -4
  353. package/dist/shared/dep-updater.js +49 -0
  354. package/dist/shared/egress.js +1 -1
  355. package/dist/shared/package-manager.js +6 -0
  356. package/dist/shared/settings.js +59 -10
  357. package/dist/shared/timeouts.js +2 -0
  358. package/dist/tools/cli-doc.js +97 -0
  359. package/dist/tools/grammar-density.js +1 -1
  360. package/dist/tools/instructions-sources.js +15 -16
  361. package/dist/tools/instructions.js +83 -39
  362. package/package.json +58 -42
  363. package/.bkit/core/.bkit/lite.md +0 -73
  364. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -172
  365. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -124
  366. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  367. package/dist/commands/workflow/workstreams.js +0 -149
  368. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  369. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  370. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  371. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  372. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  373. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  374. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  375. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -2,23 +2,30 @@
2
2
 
3
3
  {{BKIT_MANAGED_MARKER}}
4
4
 
5
- First-time install and upgrade, install lifecycle, uninstall and recovery. Ships in the package at `node_modules/@cbartens/bkit/.bkit/core/.bkit/install.md` and is mirrored into the consumer repo at `.bkit/install.md`. Ongoing ops and triggering workflows: `.bkit/README.md`.
5
+ > [!CAUTION]
6
+ > **Purpose:** This file covers first-time install and upgrade, the install lifecycle, uninstall and recovery. It ships in the package at `node_modules/@cbartens/bkit/.bkit/core/.bkit/install.md` and is mirrored into the consumer repo at `.bkit/install.md`. Ongoing ops and triggering workflows are in `.bkit/README.md`.
7
+ >
8
+ > **Rules:**
9
+ >
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`.
6
13
 
7
14
  > [!IMPORTANT]
8
- > **bkit installs from npmjs.** `@cbartens/bkit` is public on `https://registry.npmjs.org`; `pnpm add -D @cbartens/bkit` resolves with no registry mapping, PAT, or CI/Vercel env.
15
+ > **bkit installs from npmjs.** `@cbartens/bkit` is public on `https://registry.npmjs.org`, so `pnpm add -D @cbartens/bkit` resolves with no registry mapping, PAT, or CI / Vercel env.
9
16
 
10
17
  ## Quick install / upgrade — paste into your AI
11
18
 
12
- Two paste blocks below — **install** (first time) and **upgrade** (already on bkit). Both end the same way: apply advisories, reconcile templates, verify with `bkit check`.
19
+ There are two paste blocks below: install (first time) and upgrade (already on bkit). Both end the same way: apply advisories, reconcile templates, and verify with `bkit check`.
13
20
 
14
21
  ### Install — first time
15
22
 
16
- No token or registry setup is needed — `@cbartens/bkit` is public on npmjs. Copy the block below into Claude Code / Cursor / Codex / Antigravity / opencode.
23
+ No token or registry setup is needed, because `@cbartens/bkit` is public on npmjs. Copy the block below into Claude / Codex / Antigravity / Cursor / OpenCode.
17
24
 
18
25
  ````text
19
26
  Install the latest `@cbartens/bkit` in this repo and finish setup.
20
27
  1. `@cbartens/bkit` is public on npmjs — no registry mapping, no PAT, no env. Confirmed.
21
- 2. Install and seed hosts in one Bash call (`bkit install` requires named modules — core implicit; pick the hosts this repo uses from `--claude --cursor --codex --antigravity --opencode=<provider>`, provider = `openrouter` | `ollama` | `opencode-zen` | `opencode-go`; if `bkit` not on PATH use `pnpm bkit`):
28
+ 2. Install and seed hosts in one Bash call (`bkit install` requires named modules — core implicit; pick the hosts this repo uses from `--claude --codex --antigravity --cursor --opencode=<provider>`, provider = `openrouter` | `ollama` | `opencode-zen` | `opencode-go`; if `bkit` not on PATH use `pnpm bkit`):
22
29
  ```bash
23
30
  pnpm add -D @cbartens/bkit@latest && \
24
31
  bkit install --claude --cursor
@@ -26,12 +33,13 @@ Install the latest `@cbartens/bkit` in this repo and finish setup.
26
33
  Writes `.agents/`, `.claude/`, `.cursor/` and the `bkit:gate:*` `package.json` scripts, and copies the templates (CI workflow, hooks, tool configs) into `.bkit/templates/` without applying them. `.bkit/templates.md` lists each template plus the tool scripts and devDeps the gates chain.
27
34
  3. Read `.bkit/advisories.md` end-to-end. For every `[advisory]`/`[blocker]`: apply its **Action** unless truly N/A. If you skip, state advisory id and why. Then § Setup tips: follow each tip's **Agent steps** unless the person declines it.
28
35
  4. Read `.bkit/templates.md`, then compare each template in `.bkit/templates/` (CI workflows, git hooks, lint and Vale configs, Cursor config, dependency updaters, etc.) with this repo. bkit never applies templates, so adoption is your job: adopt unless adoption would break existing functionality. For any template not adopted, state which and why.
29
- 5. Re-run `bkit check` (or `pnpm bkit check`). Fix remaining drift/advisories you can. End with: resolved version, advisories applied, advisories skipped (with reasons), templates adopted/skipped (with reasons).
36
+ 5. Reconcile every permanent skill through `.agents/skills.md` § Install / Update, including the project's own rows. Verify each skill file and installer-generated lock entry, and review its activation boundaries.
37
+ 6. Re-run `bkit check` (or `pnpm bkit check`). Fix remaining drift/advisories you can. End with: resolved version, advisories applied, advisories skipped (with reasons), templates adopted/skipped (with reasons), skills reconciled or incomplete (with errors).
30
38
  ````
31
39
 
32
40
  ### Upgrade — already installed
33
41
 
34
- Same paste block ships in `.bkit/README.md` (mirrored into consumer repos on install — keep both in sync when editing). Copy when the repo already has `@cbartens/bkit`. Prefer `bkit upgrade --latest` (bumps the package **and** resyncs managed files) — do **not** only `pnpm add`.
42
+ Copy this block when the repo already has `@cbartens/bkit`. Prefer `bkit upgrade --latest`, which bumps the package and resyncs the managed files. Do not run only `pnpm add`.
35
43
 
36
44
  ````text
37
45
  Upgrade `@cbartens/bkit` to the latest version in this repo and finish the resync.
@@ -42,12 +50,13 @@ Upgrade `@cbartens/bkit` to the latest version in this repo and finish the resyn
42
50
  Do **not** only `pnpm add @cbartens/bkit@latest` — that refreshes the package without resyncing managed files.
43
51
  2. Read `.bkit/advisories.md` end-to-end. For every `[advisory]`/`[blocker]`: apply its **Action** unless truly N/A. If you skip, state advisory id and why. Then § Setup tips: follow each tip's **Agent steps** unless the person declines it.
44
52
  3. Read the template changes `bkit upgrade` printed (or `git diff .bkit/templates`), then `.bkit/templates.md`. bkit never applies templates, so adoption is your job: adopt each change unless it would break existing functionality. For any change not adopted, state which and why.
45
- 4. Re-run `bkit check` (or `pnpm bkit check`). Fix remaining drift/advisories you can. End with: resolved version, advisories applied, advisories skipped (with reasons), templates adopted/skipped (with reasons).
53
+ 4. Reconcile every permanent skill through `.agents/skills.md` § Install / Update, including the project's own rows. Verify each skill file and installer-generated lock entry, and review its activation boundaries.
54
+ 5. Re-run `bkit check` (or `pnpm bkit check`). Fix remaining drift/advisories you can. End with: resolved version, advisories applied, advisories skipped (with reasons), templates adopted/skipped (with reasons), skills reconciled or incomplete (with errors).
46
55
  ````
47
56
 
48
57
  ## Install
49
58
 
50
- bkit is published publicly on **npmjs** (`https://registry.npmjs.org`). Add to a consumer repo:
59
+ bkit is published publicly on npmjs (`https://registry.npmjs.org`). Add it to a consumer repo:
51
60
 
52
61
  ```bash
53
62
  pnpm add -D @cbartens/bkit
@@ -63,13 +72,14 @@ Run these in order on a brand-new consumer repo.
63
72
  | 1 | `pnpm add -D @cbartens/bkit` — no token, no registry mapping | this section |
64
73
  | 2 | Run `bkit install --claude --cursor` to seed both hosts (writes `.bkit/.env.example`; `.envrc` is a template in `.bkit/templates/`) | this section |
65
74
  | 3 | Set up direnv + `.bkit/.env` for `BKIT_GH_TOKEN` (GitHub MCP), `BKIT_LINEAR_API_KEY` or `BKIT_JIRA_API_KEY` — no registry token | [§ Local env setup](#local-env-setup) |
66
- | 4 | Push to a feature branch and verify CI runs green | — |
75
+ | 4 | Reconcile permanent third-party skills and their lock entries | `.agents/skills.md` § Install / Update |
76
+ | 5 | Push to a feature branch and verify CI runs green | — |
67
77
 
68
- No CI step, secret, `.npmrc` mapping or Vercel env is needed — CI reaches npmjs anonymously.
78
+ No CI step, secret, `.npmrc` mapping or Vercel env is needed, because CI reaches npmjs anonymously.
69
79
 
70
80
  ### Then in the consumer repo
71
81
 
72
- `bkit install` requires you to name modules (at least one) — bare `bkit install` errors. Core (stack-agnostic foundation) always implicit. Re-run / `bkit upgrade` after package updates. Use `bkit check` as CI drift gate.
82
+ `bkit install` requires you to name at least one module, and a bare `bkit install` errors. Core (the stack-agnostic foundation) is always implicit. Re-run it, or run `bkit upgrade`, after package updates. Use `bkit check` as the CI drift gate.
73
83
 
74
84
  > **Shell alias (add once to `~/.zshrc` or `~/.bashrc`, then `source ~/.zshrc`)**
75
85
  >
@@ -77,19 +87,19 @@ No CI step, secret, `.npmrc` mapping or Vercel env is needed — CI reaches npmj
77
87
  > alias bkit='pnpm bkit'
78
88
  > ```
79
89
  >
80
- > Type `bkit <verb>` from anywhere in repo. Without alias, prefix with `pnpm`: `pnpm bkit install --claude`. `bkit doctor` emits advisory if alias not detected.
90
+ > Type `bkit <verb>` from anywhere in the repo. Without the alias, prefix with `pnpm`: `pnpm bkit install --claude`. `bkit doctor` emits an advisory if it does not detect the alias.
81
91
 
82
92
  ```bash
83
93
  # Name the host(s) + stack you want — core is implicit. Hosts compose.
84
94
  bkit install --claude # .claude/** + CLAUDE.md + core
85
- bkit install --cursor # .cursor/** + core
86
95
  bkit install --codex # Codex CLI host + core
87
- bkit install --antigravity # Google Antigravity host + core
88
- bkit install --opencode=opencode-go # additive opencode host (opencode-native gateway) + core
89
- # opencode provider: openrouter | ollama | opencode-zen | opencode-go
96
+ bkit install --antigravity # Antigravity host + core
97
+ bkit install --cursor # .cursor/** + core
98
+ bkit install --opencode=opencode-go # additive OpenCode host (OpenCode-native gateway) + core
99
+ # OpenCode provider: openrouter | ollama | opencode-zen | opencode-go
90
100
 
91
101
  # A bare install errors — name at least one module, or a tracker:
92
- bkit install # ✗ error: requires ≥1 module flag
102
+ bkit install # ✗ error: requires >=1 module flag
93
103
  bkit install --tracker=github # tracker alone: re-renders every installed host
94
104
 
95
105
  # Ongoing sync — re-render everything installed at the CURRENT version (offline)
@@ -102,24 +112,27 @@ bkit upgrade --latest # newest published; or --to=<version> t
102
112
  bkit check
103
113
  ```
104
114
 
105
- **Module flags** (composable; symmetric install ↔ uninstall): `--claude` `--cursor` `--codex` `--antigravity` `--opencode=<provider>`. The CI workflow, the Vale config, the tool configs, the git hooks, the slop-scan type-suppression plugin (`scripts/slop/bkit-slop-type-suppression.mjs`), and the tool `package.json` scripts and devDeps are templates you copy from `.bkit/templates/` (`.bkit/templates.md`). Core, implicit on every install, seeds the `bkit:gate:*` / `bkit:deps:*` scripts every workflow runs (add-if-missing; a name already present is never touched); point their values at your stack, see `.bkit/README.md` § Required tools. Any other module flag is an unknown-flag error.
115
+ **Module flags** (composable; install and uninstall are symmetric): `--claude` `--codex` `--antigravity` `--cursor` `--opencode=<provider>`. Any other module flag is an unknown-flag error.
116
+
117
+ - The CI workflow, the Vale config, the tool configs, the git hooks, the slop-scan type-suppression plugin (`scripts/slop/bkit-slop-type-suppression.mjs`), and the tool `package.json` scripts and devDeps are templates you copy from `.bkit/templates/` (`.bkit/templates.md`).
118
+ - Core, implicit on every install, seeds the `bkit:gate:*` / `bkit:deps:*` scripts every workflow runs. It adds them only if missing, and never touches a name that is already present. Point their values at your stack (see `.bkit/README.md` § Required tools).
106
119
 
107
- **Opt-in flags:** `--tracker=github|linear|jira`, `--auto=claude|cursor|opencode` (cloud agents), `--opencode=<provider>` (additive opencode execution host — `openrouter`, `ollama`, `opencode-zen`, `opencode-go`). Dependency updaters: copy an example and own it. See [§ Optional post-install decisions](#optional-post-install-decisions).
120
+ **Opt-in flags:** `--tracker=github|linear|jira`, `--auto=claude|cursor|opencode` (cloud agents), `--opencode=<provider>` (additive OpenCode execution host: `openrouter`, `ollama`, `opencode-zen`, `opencode-go`). For dependency updaters, copy an example and own it. See [§ Optional post-install decisions](#optional-post-install-decisions).
108
121
 
109
122
  ### Payload view links — `.bkit/core` + `.bkit/shared`
110
123
 
111
- Install and upgrade create two **relative symlinks** into the installed package, so the payload sources (workflows, prompts, hooks) are browsable in-repo: `.bkit/core` → `../node_modules/@cbartens/bkit/.bkit/core`, same shape for `shared`. Views, not copies — always the installed version, zero drift. Rules:
124
+ Install and upgrade create two relative symlinks into the installed package, so the payload sources (workflows, prompts, hooks) can be browsed in the repo: `.bkit/core` → `../node_modules/@cbartens/bkit/.bkit/core`, and the same shape for `shared`. They are views, not copies, so they always show the installed version with zero drift. Rules:
112
125
 
113
- - Both paths sit in the `.gitignore` managed block — they dangle on a fresh clone or in CI (no `node_modules`); `bkit install` / `upgrade` recreates them. A missing or mis-pointed link is never `bkit check` drift (links join no WriteSet).
114
- - The `bkit` binary reads its payload from the package regardless; the links are browse-only. Editors resolve them to the `node_modules/…` paths.
115
- - A real directory at either path is never clobbered (advisory `payload-link-real-dir`) — remove it yourself and re-run install to get the link. A platform that refuses symlinks (Windows without Developer Mode) falls back to a junction, then to advisory `payload-link-failed` — never a failure.
116
- - `bkit uninstall` removes the links (symlinks only — consumer content stays).
126
+ - Both paths sit in the `.gitignore` managed block. They dangle on a fresh clone or in CI (no `node_modules`), and `bkit install` / `upgrade` recreates them. A missing or mis-pointed link is never `bkit check` drift, because links join no WriteSet.
127
+ - The `bkit` binary reads its payload from the package regardless, so the links are browse-only. Editors resolve them to the `node_modules/…` paths.
128
+ - A real directory at either path is never clobbered (advisory `payload-link-real-dir`). Remove it yourself and re-run install to get the link. A platform that refuses symlinks (Windows without Developer Mode) falls back to a junction, then to advisory `payload-link-failed`, and never fails.
129
+ - `bkit uninstall` removes the links. It removes symlinks only, and consumer content stays.
117
130
 
118
- > **⚠️ Moving bkit versions: use `bkit upgrade --latest` (or `--to=<version>`).** Bumps `@cbartens/bkit` **and** resyncs `.agents/` payload + `.bkit/version` pin in one atomic step — two can never drift apart. Bare `pnpm add @cbartens/bkit` (or Renovate/Dependabot bump) only refreshes `package.json` + lockfile — does **not** resync; skipping resync reds CI on `bkit check` drift gate. If you bump package separately, run `bkit upgrade` afterward and commit resync alongside version bump in same PR. A target equal to the installed version re-renders in place, unless `package.json` declares `@cbartens/bkit` by a non-registry spec (`file:` tarball, `link:`, `workspace:`, `npm:` alias, git, URL, path) — then it still runs `pnpm add` to swap in the published package.
131
+ > **Moving bkit versions: use `bkit upgrade --latest` (or `--to=<version>`).** It bumps `@cbartens/bkit` and resyncs the `.agents/` payload + `.bkit/version` pin in one atomic step, so the two can never drift apart. A bare `pnpm add @cbartens/bkit` (or a Renovate / Dependabot bump) only refreshes `package.json` + the lockfile and does not resync. Skipping the resync reds CI on the `bkit check` drift gate. If you bump the package separately, run `bkit upgrade` afterward and commit the resync alongside the version bump in the same PR. A target equal to the installed version re-renders in place. The exception is when `package.json` declares `@cbartens/bkit` by a non-registry spec (`file:` tarball, `link:`, `workspace:`, `npm:` alias, git, URL, path): then it still runs `pnpm add` to swap in the published package.
119
132
 
120
133
  ### Local env setup
121
134
 
122
- Two flows — pick one. Both put `BKIT_GH_TOKEN` in shell for the GitHub MCP server; Linear repos also need `BKIT_LINEAR_API_KEY`, Jira repos `BKIT_JIRA_API_KEY` (`.bkit/trackers.md` § jira — setup and notes). Use `gh auth login` for CLI.
135
+ There are two flows. Pick one. Both put `BKIT_GH_TOKEN` in the shell for the GitHub MCP server. Linear repos also need `BKIT_LINEAR_API_KEY`, and Jira repos need `BKIT_JIRA_API_KEY` (`.bkit/trackers.md` § jira — setup and notes). Use `gh auth login` for the CLI.
123
136
 
124
137
  #### Flow A — Shell export (quickest, no extra deps)
125
138
 
@@ -133,11 +146,11 @@ export BKIT_JIRA_API_KEY=<Atlassian MCP V2 scoped token> # Jira MCP
133
146
  source ~/.zshrc # or: source ~/.bashrc
134
147
  ```
135
148
 
136
- Pros: one step, no install. Cons: tokens in every shell on machine; no per-repo scoping.
149
+ Pros: one step, no install. Cons: the tokens are in every shell on the machine, with no per-repo scoping.
137
150
 
138
151
  #### Flow B — direnv + `.bkit/.env` (recommended for daily use)
139
152
 
140
- `bkit install` writes `.bkit/.env.example` (placeholders + permission notes; bkit owns it and overwrites edits — real values go in `.bkit/.env`). `.envrc` (`dotenv_if_exists .bkit/.env`) is a template: copy it from `.bkit/templates/.envrc`. direnv loads `.bkit/.env` on `cd`, unloads on leave — tokens scoped to repo.
153
+ `bkit install` writes `.bkit/.env.example` (placeholders + permission notes). bkit owns that file and overwrites edits, so real values go in `.bkit/.env`. `.envrc` (`dotenv_if_exists .bkit/.env`) is a template: copy it from `.bkit/templates/.envrc`. direnv loads `.bkit/.env` on `cd` and unloads it when you leave, so the tokens are scoped to the repo.
141
154
 
142
155
  ```bash
143
156
  # 1. One-time per machine — install direnv
@@ -159,21 +172,34 @@ echo "len=${#BKIT_GH_TOKEN}" # non-ze
159
172
  gh auth status # gh CLI uses keyring, not BKIT_GH_TOKEN
160
173
  ```
161
174
 
162
- After step 4, restart open Claude Code / Cursor sessions in this repo so new env reaches MCP servers.
175
+ After step 4, restart any open Claude / Cursor sessions in this repo, so the new env reaches the MCP servers.
163
176
 
164
- `.bkit/.env` gitignored — never commit. Cloud sessions (Claude Code on the web, Cursor Background Agents): set same names in respective online dashboards; see `.bkit/cloud.md` § Environment variables. `bkit install` / `bkit check` advisories detect missing direnv, blank required keys, un-allowed `.envrc` — follow whichever fires.
177
+ `.bkit/.env` is gitignored. NEVER commit it. For cloud sessions (Claude on the web, Cursor Background Agents), set the same names in each host's online dashboard (see `.bkit/cloud.md` § Tokens by session type). `bkit install` / `bkit check` advisories detect a missing direnv, blank required keys and an un-allowed `.envrc`. Follow whichever fires.
165
178
 
166
- ## Cloud agent environments (Claude Code on the web + Cursor Background Agents)
179
+ ## Cloud agent environments (Claude on the web + Cursor Background Agents)
167
180
 
168
- bkit ships repo-side scaffolding for both cloud agents. Opt-in `bkit install --auto=claude` writes no file; the per-session install hook (`.claude/hooks/bkit-cloud-bootstrap.sh`), the phase-routed `.github/workflows/bkit-cloud.yml` and the Cursor cloud image files (`.cursor/Dockerfile`, `.cursor/environment.json`) are templates in `.bkit/templates/` that you copy and own. (`.cursor/hooks.json` — Linear preflight wiring — ships with `--cursor`, not `--auto`.) Install without `--auto` ships zero cloud footprint. **Online-dashboard** half (Claude env in `claude.ai/code`, Cursor env vars in `Cursor → Settings → Background Agents`) configured once per machine / account.
181
+ bkit ships repo-side scaffolding for both cloud agents:
169
182
 
170
- For **post-CI auto-routing** (ship-vs-debug after CI), bkit ships a single `.github/workflows/bkit-cloud.yml` template with TWO runtime-gated dispatch jobs — **claude** job (`claude-code-action`, runs when the `ANTHROPIC_API_KEY` repo secret is set, or keyless via the `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables) and **opencode** job (`opencode run` CLI, runs when `OPENCODE_PROVIDER_KEY` set) — plus `/bkit-auto` slash command both clouds invoke from single source (Cursor wires via dashboard trigger; no GHA on Cursor side). `bkit install --auto=opencode` requires `tracker=github`.
183
+ - The opt-in `bkit install --auto=claude` writes no file.
184
+ - The per-session install hook (`.claude/hooks/bkit-cloud-bootstrap.sh`), the phase-routed `.github/workflows/bkit-cloud.yml` and the Cursor cloud image files (`.cursor/Dockerfile`, `.cursor/environment.json`) are templates in `.bkit/templates/` that you copy and own.
185
+ - `.cursor/hooks.json` (the Linear preflight wiring) ships with `--cursor`, not `--auto`.
186
+ - An install without `--auto` ships zero cloud footprint.
171
187
 
172
- Full recipe + paste-in setup script + env-var inventory + Cursor dashboard config + consumer customisation patterns: `.bkit/cloud.md`. Host-delta matrix: `.bkit/providers.md` § Runtime environment.
188
+ You configure the online-dashboard half (the Claude env in `claude.ai/code`, the Cursor env vars in `Cursor → Settings → Background Agents`) once per machine / account.
189
+
190
+ For post-CI auto-routing (ship-vs-debug after CI), bkit ships a single `.github/workflows/bkit-cloud.yml` template with two runtime-gated dispatch jobs, plus a `/bkit-auto` slash command that both clouds invoke from a single source:
191
+
192
+ - The **claude** job (`claude-code-action`) runs when the `ANTHROPIC_API_KEY` repo secret is set, or keyless through the `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables.
193
+ - The **OpenCode** job (`opencode run` CLI) runs when `OPENCODE_PROVIDER_KEY` is set.
194
+ - Cursor wires the slash command through a dashboard trigger, with no GHA on the Cursor side.
195
+
196
+ `bkit install --auto=opencode` requires `tracker=github`.
197
+
198
+ `.bkit/cloud.md` holds the full recipe, the paste-in setup script, the env-var inventory, the Cursor dashboard config and the consumer customisation patterns. The host-delta matrix is in `.bkit/providers.md` § Runtime environment.
173
199
 
174
200
  ## JSON ownership model — deep-containment
175
201
 
176
- `.claude/settings.json` and `.cursor/hooks.json` managed via **deep-containment**. bkit declares scope (full template JSON tree) that must be present as subset of consumer document. Consumer-added keys outside template tree survive every `bkit install` byte-identically — no special key or wrapper required.
202
+ `.claude/settings.json` and `.cursor/hooks.json` are managed through **deep-containment**: bkit declares a scope (the full template JSON tree) that must be present as a subset of the consumer's document. Consumer-added keys outside the template tree survive every `bkit install` byte-identically, with no special key or wrapper required.
177
203
 
178
204
  ```json
179
205
  // .claude/settings.json
@@ -188,13 +214,13 @@ Full recipe + paste-in setup script + env-var inventory + Cursor dashboard confi
188
214
  }
189
215
  ```
190
216
 
191
- In this example, `hooks.SessionStart` is bkit-declared scope (from template). `hooks.Stop` and `failClosed` are consumer-added — bkit never touches them.
217
+ In this example, `hooks.SessionStart` is bkit-declared scope (from the template). `hooks.Stop` and `failClosed` are consumer-added, and bkit never touches them.
192
218
 
193
219
  **Rules:**
194
220
 
195
- - Consumer keys outside template tree survive every `bkit install` byte-identically.
196
- - `bkit install` uses `deepContains(template, consumer)` — every template leaf present. On drift, deep-merges template-wins; consumer-only siblings preserved.
197
- - `bkit check` surfaces `tier2-json-drift` advisory when `deepContains` fails and **exits 1** (CI drift gate); writes nothing — consumer reviews and re-runs `bkit install` to reconverge.
221
+ - Consumer keys outside the template tree survive every `bkit install` byte-identically.
222
+ - `bkit install` uses `deepContains(template, consumer)`, which checks that every template leaf is present. On drift, it deep-merges with the template winning, and consumer-only siblings are preserved.
223
+ - `bkit check` surfaces the `tier2-json-drift` advisory when `deepContains` fails, and exits 1 (CI drift gate). It writes nothing. The consumer reviews and re-runs `bkit install` to reconverge.
198
224
  - `.cursor/hooks.json` uses Cursor v1 keyed-object schema: `{"version": 1, "hooks": {"sessionStart": [...], "sessionStop": [...]}}`.
199
225
 
200
226
  ## Install lifecycle
@@ -203,7 +229,7 @@ In this example, `hooks.SessionStart` is bkit-declared scope (from template). `h
203
229
 
204
230
  **Phase 1 — Preflight (read-only, before any writes)**
205
231
 
206
- bkit checks preconditions and known advisory patterns before touching any file. Blocker fires → install exits 1 immediately with formatted `[blocker]` line and zero writes. Advisories accumulated for Phase 3.
232
+ bkit checks preconditions and known advisory patterns before touching any file. When a blocker fires, install exits 1 immediately with a formatted `[blocker]` line and zero writes. Advisories are collected for Phase 3.
207
233
 
208
234
  <!-- prettier-ignore -->
209
235
  | Severity | When |
@@ -219,35 +245,60 @@ Module dispatch writes managed files.
219
245
 
220
246
  **Phase 3 — Post-install (re-detect + unified output)**
221
247
 
222
- After writes, bkit re-runs credential and environment checks — some only accurate post-install (e.g. the `bkit:gate:*` scripts core just seeded into `package.json`). The table also lists the module advisories that render in the same checklist.
248
+ After the writes, bkit re-runs the credential and environment checks, because some are only accurate after install (for example the `bkit:gate:*` scripts core just seeded into `package.json`). The table also lists the module advisories that render in the same checklist.
223
249
 
224
250
  <!-- prettier-ignore -->
225
251
  | `id` | When |
226
252
  | --- | --- |
227
253
  | `bkit-managed-duplicate` | A managed markdown file holds an older unmarked copy of its block outside `bkit:start`/`bkit:end`: the block's `# ` title plus 10+ of its long lines verbatim, fenced code ignored. Install never updates that copy. Names each file and title line; delete the copy. |
228
- | `gh-mcp-token-unset-shell` / `gh-mcp-token-empty-shell` | `BKIT_GH_TOKEN` (GitHub MCP auth) unset/empty in shell while a `github` MCP server is configured — the whole tracker/PR/board MCP surface fails to connect. Suppressed in CI. |
254
+ | `gh-mcp-token-unset-shell` / `gh-mcp-token-empty-shell` | `BKIT_GH_TOKEN` (GitHub MCP auth) unset / empty in shell while a `github` MCP server is configured — the whole tracker/PR/board MCP surface fails to connect. Suppressed in CI. |
229
255
  | `tracker-setup-none` / `-github` / `-linear` / `-jira` | Optional post-install decision — which issue tracker is wired (`bkit.tracker.default`). `none` nudges `bkit install --tracker=…`. See [§ Optional post-install decisions](#optional-post-install-decisions). |
230
256
  | `github-project-board-sync-unconfigured` | GitHub tracker active but Projects v2 board sync is half-configured (`bkit.tracker.github.project` empty, absent or not a board URL, and/or `.mcp.json` lacks the `projects` toolset) — sync silently no-ops. Silence with `bkit.tracker.github.project: false`. |
231
257
  | `github-project-token-scope` | A board is configured but `BKIT_GH_TOKEN` cannot reach it: a classic token lacks the `project` scope, or a fine-grained token's board query returns nothing. Board moves fall back to the MCP. Checked live via `gh`; skipped on cloud / CI. |
232
258
  | `dep-updater-absent` | No Renovate or Dependabot config. Copy one example and own it. `bkit.dependencies.updater: "none"` silences this. See [§ Optional post-install decisions](#optional-post-install-decisions). |
233
259
  | `dep-updater-both` | Both updater configs are present. Keep one. |
260
+ | `dep-updater-unset` | Blocker. One updater's config is present but `bkit.dependencies.updater` does not name it (empty or unrecognised). Set it, or run `bkit upgrade`, which fills an empty value. |
261
+ | `dep-updater-mismatch` | Blocker. `bkit.dependencies.updater` names one updater (or `none`) while the other's config is present, or names an updater with no config. Fix the value or the config. |
234
262
  | `cloud-router-none` / `cloud-router` | Optional post-install decision — post-CI auto-routing (`bkit.cloud.agent`). `none` (undecided) nudges `bkit install --auto=<variant>`, except under the jira tracker (local runs only); `cloud-router` is informational once `bkit-cloud.yml` is present. See [§ Optional post-install decisions](#optional-post-install-decisions). |
235
263
  | `actions-write-permissions-missing` | `bkit-cloud.yml` present but repo Actions permissions are read-only / PR creation disabled — `actions/checkout` + `gh pr create` 403. Repo-level check; org policy can override. |
236
- | `opencode-setup` | opencode host installed (`--opencode=<provider>`) — names the provider key to set (e.g. `BKIT_OPENROUTER_API_KEY`; `BKIT_OPENCODE_API_KEY` for `opencode-zen` / `opencode-go`), confirms the pre-seeded base URL, and notes all four providers ship curated per-agent pins (re-pin via `.bkit/prompts.md` § Model Overrides). Verify with `bkit doctor` + `bkit status`. |
264
+ | `opencode-setup` | OpenCode host installed (`--opencode=<provider>`) — names the provider key to set (e.g. `BKIT_OPENROUTER_API_KEY`; `BKIT_OPENCODE_API_KEY` for `opencode-zen` / `opencode-go`), confirms the pre-seeded base URL, and notes all four providers ship curated per-agent pins (re-pin via `.bkit/prompts.md` § Model Overrides). Verify with `bkit doctor` + `bkit status`. |
265
+ | `vale-not-installed` | `bkit:lint:prose` runs `bkit ci prose` but vale is not on PATH, so the prose gate fails |
237
266
  | `vale-package-not-synced` | vale on PATH but `.vale/styles/write-good/` absent |
238
267
  | `gate-missing-called-scripts` | A `bkit:gate:*` script still at bkit's default chains a script `package.json` does not declare (e.g. `typecheck`, `format:check`, `test`). Add it (`.bkit/templates.md` lists the tool scripts and devDeps) or rewrite the gate. |
239
- | `gate-commit-repeats-push` | `bkit:gate:format` (pre-commit) runs a script the push gate runs again (e.g. `lint:prose`), so it runs on every commit and again on the push. Drop it from `bkit:gate:format`. |
268
+ | `gate-commit-repeats-push` | `bkit:gate:format` (pre-commit) runs a script the push gate runs again (e.g. `bkit:lint:prose`), so it runs on every commit and again on the push. Drop it from `bkit:gate:format`. |
240
269
  | `gate-noop` | A `bkit:gate:*` script is empty or cannot fail (`true`, `:`, `exit 0`, `echo …`), so every agent run and push passes it. Warn-only, at install, `bkit check` and `bkit upgrade`, on every branch. Point it at real checks, or delete it and run `bkit upgrade` to restore bkit's default. |
241
270
  | `gate-tier-not-wired` | `package.json` declares a deeper test tier (`test:integration`, `test:e2e`, `test:live`) that no `bkit:gate:*` script runs; the advisory prints the gate line to add. |
242
271
  | `test-file-script-missing` | `package.json` does not declare `bkit:test:file`, so `/bkit-build` reports test-first as not enforced. The advisory prints the script contract and a Vitest line. |
272
+ | `lint-file-script-missing` | `package.json` declares `bkit:test:file` but not `bkit:lint:file`, so `bkit tests red` records a group's reds before the linter sees the tests, and a lint fix after it changes a frozen test file, which the code step's `steps finish` refuses. The advisory prints the script contract and ESLint / Ruff lines. |
273
+ | `gate-changed-script-missing` | `package.json` does not declare `bkit:gate:changed`, so build and debug agents run a whole gate after every change instead of checking only the changed files. The advisory prints the script contract and a Vitest + ESLint line. Silence it with `bkit.advisories.ignore`. |
274
+
275
+ Every `gate-*` advisory ends with what a gate may run, which bkit cannot check: no test that needs a deployed boundary or remote service outside the two `…-e2e` gates (`.bkit/workflows.md` § Local gate scripts).
243
276
 
244
- Phase 1 and Phase 3 findings merged and deduplicated by `id` (Phase 3 wins on conflict — re-detection more accurate post-write). Zero findings → no banner.
277
+ Phase 1 and Phase 3 findings are merged and deduplicated by `id`. Phase 3 wins on conflict, because re-detection is more accurate after the writes. Zero findings → no banner.
245
278
 
246
- **`bkit check` (dry-run)** runs Phase 1 and Phase 3 (read-only) — same advisory set as `bkit install` minus writes. Changes no managed file (regenerates `.bkit/advisories.md` artifact) and **exits 1 when any managed-file write would occur** in installed module — Tier-2 JSON deep-containment or markered-block drift, whole-file byte-equal mismatch, **host agent/command mirror content drift** (would-write / orphan delete), or when any file bkit writes (rendered agents / commands / skills, managed blocks, owned whole files) carries a stale managed-version marker (`bkit-managed-stale`). Gate covers the **installed** module set ({core, claude, cursor, codex, antigravity} plus **opencode**, each detected by sentinel files: a host's `agents/` dir; antigravity any of `.agents/plugins/bkit/{plugin.json,hooks.json,agents,skills,hooks}`, so a deleted plugin manifest is reported as a missing file, not an absent host; `bkit status` uses the same detection). A missing `bkit:gate:*` name counts as a write. antigravity gated: `.agents/plugins/bkit/**` (plugin manifest, hooks, agents, skills) and root `GEMINI.md`. opencode gated: `.opencode/opencode.json` (provider block + the recorded tracker's `mcp` entry + permission sandbox; another tracker's `mcp` entry the consumer edited, kept by a tracker switch, is not drift — `mcp-extra-server-linear--opencode-opencode-json` advises removing it) and the `bkit-gateguard.js` / `bkit-readguard.js` plugins drift fail `check` — render inputs fall back to installed provider (`package.json` `bkit.providers.opencode.default`, authoritative for `opencode-zen` / `opencode-go`; all installed providers tracked in `bkit.providers.opencode.installed: string[]`) and recorded tracker, so clean install across providers checks green (no false drift). Remaining **opt-in** module (cloud) is not drift-gated. A missing bkit-owned hook file also fails `check`, one line per file naming it and the `bkit install` flag that restores it: the hook files of every installed host (`.claude/hooks/*`, `.cursor/hooks/*`, `.codex/hooks/*`, `.agents/plugins/bkit/hooks/*`, `.opencode/plugin/bkit-gateguard.js`, `.opencode/plugin/bkit-readguard.js`) — the hook commands skip a missing file (`test -f … || true`), so without this the guard would be off with no signal. Updater configs are not bkit files, so `bkit check` does not report them. Phase 3 stays read-only through read-only detector paths, not by being skipped.
279
+ **`bkit check` (dry-run)** runs Phase 1 and Phase 3 (read-only): the same advisory set as `bkit install`, minus the writes. It changes no managed file (it regenerates the `.bkit/advisories.md` artifact), and it exits 1 when any managed-file write would occur in an installed module:
247
280
 
248
- **`bkit upgrade`** (not `--dry-run`) ends with the same read-only pass as `bkit check`: prints the checklist and rewrites `.bkit/advisories.md` (`Mode: upgrade`). Drift and blockers it finds are reported only — upgrade's exit code is unchanged.
281
+ - Tier-2 JSON deep-containment or markered-block drift.
282
+ - A whole-file byte-equal mismatch.
283
+ - Host agent / command mirror content drift (would-write / orphan delete).
284
+ - Any file bkit writes (rendered agents / commands / skills, managed blocks, owned whole files) carrying a stale managed-version marker (`bkit-managed-stale`).
285
+ - A missing `bkit:gate:*` name, which counts as a write.
249
286
 
250
- **`PreflightFinding` shape** — stable contract for downstream tooling:
287
+ The gate covers the installed module set ({core, claude, cursor, codex, antigravity} plus OpenCode). Each module is detected by sentinel files: for a host, its `agents/` dir, and for antigravity, any of `.agents/plugins/bkit/{plugin.json,hooks.json,agents,skills,hooks}`, so a deleted plugin manifest is reported as a missing file, not an absent host. `bkit status` uses the same detection.
288
+
289
+ - **antigravity gated:** `.agents/plugins/bkit/**` (plugin manifest, hooks, agents, skills) and the root `GEMINI.md`.
290
+ - **OpenCode gated:** Drift in `.opencode/opencode.json` (the provider block + the recorded tracker's `mcp` entry + the permission sandbox) and in the `bkit-gateguard.js` / `bkit-readguard.js` / `bkit-rules.js` plugins fails `check`.
291
+ - Another tracker's `mcp` entry that the consumer edited, kept by a tracker switch, is not drift. `mcp-extra-server-linear--opencode-opencode-json` advises removing it.
292
+ - Render inputs fall back to the installed provider (`package.json` `bkit.providers.opencode.default`, authoritative for `opencode-zen` / `opencode-go`; all installed providers are tracked in `bkit.providers.opencode.installed: string[]`) and the recorded tracker, so a clean install across providers checks green, with no false drift.
293
+ - The remaining opt-in module (cloud) is not drift-gated.
294
+
295
+ A missing bkit-owned hook file also fails `check`, with one line per file naming it and the `bkit install` flag that restores it. This covers the hook files of every installed host (`.claude/hooks/*`, `.cursor/hooks/*`, `.codex/hooks/*`, `.agents/plugins/bkit/hooks/*`, `.opencode/plugin/bkit-gateguard.js`, `.opencode/plugin/bkit-readguard.js`, `.opencode/plugin/bkit-rules.js`). The hook commands skip a missing file (`test -f … || true`), so without this check the guard would be off with no signal.
296
+
297
+ Updater configs are not bkit files, so `bkit check` does not report them. Phase 3 stays read-only through read-only detector paths, not by being skipped.
298
+
299
+ **`bkit upgrade`** (not `--dry-run`) ends with the same read-only pass as `bkit check`: it prints the checklist and rewrites `.bkit/advisories.md` (`Mode: upgrade`). It only reports the drift and blockers it finds, and upgrade's exit code is unchanged.
300
+
301
+ **`PreflightFinding` shape** — a stable contract for downstream tooling:
251
302
 
252
303
  ```typescript
253
304
  interface PreflightFinding {
@@ -258,9 +309,9 @@ interface PreflightFinding {
258
309
  }
259
310
  ```
260
311
 
261
- Findings render as `--- i/N [severity] id ---` with `Detect:` and `Action:` lines. The console banner and the `.bkit/advisories.md` artifact render the same text — copy either into a coding assistant to apply fixes in sequence. After the findings, both list every firing setup tip (§ Setup tips).
312
+ Findings render as `--- i/N [severity] id ---` with `Detect:` and `Action:` lines. The console banner and the `.bkit/advisories.md` artifact render the same text, so copy either into a coding assistant to apply the fixes in sequence. After the findings, both list every firing setup tip (§ Setup tips).
262
313
 
263
- **Dismissing an advisory (per package).** A detector can be right in general and still fire where the condition is deliberately not applicable — a rule-linter whose test titles mention `@live`, an integration lane mocked by design. Opt the owning package out in its `package.json`:
314
+ **Dismissing an advisory (per package).** A detector can be right in general and still fire where the condition is deliberately not applicable, such as a rule-linter whose test titles mention `@live`, or an integration lane mocked by design. Opt the owning package out in its `package.json`:
264
315
 
265
316
  ```json
266
317
  {
@@ -273,20 +324,20 @@ Findings render as `--- i/N [severity] id ---` with `Detect:` and `Action:` line
273
324
  <!-- prettier-ignore -->
274
325
  | Rule | Behaviour |
275
326
  | --- | --- |
276
- | Scope | Per package, read from the **owning** package's `package.json` — the package holding the test file for `tagged-tests-no-ci-home`, the repo root for `test-integration-env-not-asserted` (the only manifest it reads). A sibling package with a real finding stays flagged. |
327
+ | Scope | Per package, read from the owning package's `package.json` — the package holding the test file for `tagged-tests-no-ci-home`, the repo root for `test-integration-env-not-asserted` (the only manifest it reads). A sibling package with a real finding stays flagged. |
277
328
  | Severity | Advisory only. A `blocker` is never suppressible, whatever the manifest says. |
278
329
  | Visibility | The console banner and `.bkit/advisories.md` carry one suppressed-advisory line per dismissal (`N advisory` / `N advisories`), so a stale opt-out cannot hide a finding silently. |
279
330
  | Coverage | Per package: `tagged-tests-no-ci-home` and `test-integration-env-not-asserted`. Repo root: every setup tip id and every advisory a tip reuses (§ Setup tips). No other advisory is suppressible; an id matching no advisory or tip is ignored. |
280
331
 
281
332
  ## Optional post-install decisions
282
333
 
283
- Two capabilities **opt-in** — never wired by plain host/tooling install. Default install never enables them; post-install advisory banner nudges you to choose, once. Each recorded in `package.json` (`bkit.tracker.default`, `bkit.cloud.agent`) so the nudge knows whether you've decided or deliberately opted out.
334
+ Two capabilities are opt-in, and a plain host / tooling install never wires them. The default install never enables them, and the post-install advisory banner nudges you to choose, once. Each choice is recorded in `package.json` (`bkit.tracker.default`, `bkit.cloud.agent`), so the nudge knows whether you've decided or deliberately opted out.
284
335
 
285
336
  <!-- prettier-ignore -->
286
337
  | Decision | Default | Opt-in command | Advisory when unset |
287
338
  | --- | --- | --- | --- |
288
339
  | **Issue tracker** | `none` (workflows run; tracker calls are no-ops) | `bkit install --tracker=github` (`BKIT_GH_TOKEN`) `--tracker=linear` (`BKIT_LINEAR_API_KEY`) or `--tracker=jira` (`BKIT_JIRA_API_KEY` + `bkit.tracker.jira.site` / `bkit.tracker.jira.project`) | `tracker-setup-none` |
289
- | **Cloud agents** | none (zero cloud footprint) | `bkit install --auto=claude\|cursor\|opencode` — records the choice and points at the copy-and-own templates: `.claude/hooks/bkit-cloud-bootstrap.sh` (claude), the `bkit-cloud.yml` (claude + opencode jobs, secret-gated) and the Cursor Dockerfile/environment.json | `cloud-router-none` |
340
+ | **Cloud agents** | none (zero cloud footprint) | `bkit install --auto=claude\|cursor\|opencode` — records the choice and points at the copy-and-own templates: `.claude/hooks/bkit-cloud-bootstrap.sh` (claude), the `bkit-cloud.yml` (claude + OpenCode jobs, secret-gated) and the Cursor Dockerfile/environment.json | `cloud-router-none` |
290
341
 
291
342
  **Dependency updater.** Copy one example and own it.
292
343
 
@@ -297,28 +348,38 @@ Two capabilities **opt-in** — never wired by plain host/tooling install. Defau
297
348
  | Renovate self-hosted runner | `.bkit/templates/.github/workflows/bkit-renovate.yml` |
298
349
  | Dependabot | `.bkit/templates/.github/dependabot.yml` |
299
350
 
300
- Use one. `bkit.dependencies.updater: "none"` skips the install-time absence advisory. Setup: `docs/deployments.md` § Dependency updaters.
351
+ Use one, and record it in `bkit.dependencies.updater` (`"renovate"` / `"dependabot"`). Install and upgrade fill an empty value from the config present. `"none"` skips the install-time absence advisory. `bkit check` emits `dep-updater-absent` and `dep-updater-both`, and blocks on `dep-updater-unset` / `dep-updater-mismatch` when the value and the configs disagree. Setup: `docs/deployments.md` § Dependency updaters.
301
352
 
302
- **Security scan.** Updater only offers fixes once a fixed release exists. To fail CI on known-vulnerable packages, risky config or committed secrets, copy `.bkit/templates/.github/workflows/bkit-trivy.yml` and own it. No advisory; `bkit tips` suggests it. Setup: `.bkit/templates.md` § Trivy.
353
+ **Security scan.** An updater only offers fixes once a fixed release exists. To fail CI on known-vulnerable packages, risky config or committed secrets, copy `.bkit/templates/.github/workflows/bkit-trivy.yml` and own it. It also runs daily, and you accept findings in `.trivyignore.yaml`. There is no advisory, and `bkit tips` suggests it. Setup: `.bkit/templates.md` § Trivy.
303
354
 
304
- **Test lint.** JS / TS repos, to fail `lint` on a test that cannot fail (no assertion, branch inside a test, unawaited promise): copy and own `.bkit/templates/.oxlintrc.json`, add `oxlint` + `oxlint-tsgolint`, set `lint` to `oxlint -c .oxlintrc.json --type-aware --deny-warnings`. No advisory; `bkit tips` suggests it. Setup: `.bkit/templates.md` § Oxlint.
355
+ **Test lint.** In JS / TS repos, to fail `lint` on a test that cannot fail (no assertion, a branch inside a test, an unawaited promise):
305
356
 
306
- **All templates.** Copy and own, never installed. Catalog and install steps: `.bkit/templates.md`.
357
+ 1. Copy and own `.bkit/templates/.oxlintrc.json`.
358
+ 2. Add `oxlint` + `oxlint-tsgolint`.
359
+ 3. Set `lint` to `oxlint -c .oxlintrc.json --type-aware --deny-warnings`.
360
+
361
+ There is no advisory, and `bkit tips` suggests it. Setup: `.bkit/templates.md` § Oxlint.
362
+
363
+ **All templates.** You copy and own them, and they are never installed. Catalog and install steps: `.bkit/templates.md`.
307
364
 
308
365
  **Why opt-in, not part of a default install:**
309
366
 
310
- - **Tracker** wires real credentials and MCP servers into workflows — consumer must choose provider; bkit can't guess.
311
- - **Cloud agents** run through the phase-routed `bkit-cloud.yml` template (auto-dispatches bkit-ship on CI pass, bkit-debug on CI fail; plan/build via `workflow_dispatch`; design is local-only) plus cloud env scaffolding (`.claude/hooks/bkit-cloud-bootstrap.sh`, and the `.cursor/Dockerfile` + `.cursor/environment.json` templates). Workflow carries claude job and opencode job, each runtime-gated on provider secret — inert without key: claude needs the `ANTHROPIC_API_KEY` repo secret or the federation repo variables (+ Claude GitHub App), opencode needs `OPENCODE_PROVIDER_KEY`. Both need GitHub Actions write permissions, GitHub tracker, and (Cursor half) dashboard trigger — tracker itself opt-in. Env scaffolding inert until Claude/Cursor cloud env wired in dashboard. Autonomous routing by default, wired to unconfigured tracker, is wrong default — install without `--auto` ships zero cloud footprint.
367
+ - **Tracker** wires real credentials and MCP servers into workflows, so the consumer must choose the provider. bkit can't guess.
368
+ - **Cloud agents** run through the phase-routed `bkit-cloud.yml` template plus the cloud env scaffolding (`.claude/hooks/bkit-cloud-bootstrap.sh`, and the `.cursor/Dockerfile` + `.cursor/environment.json` templates). The template auto-dispatches bkit-ship on CI pass and bkit-debug on CI fail, and runs design / plan / build only through `workflow_dispatch`.
369
+ - The workflow carries a claude job and an OpenCode job, each runtime-gated on its provider secret, so each is inert without its key. claude needs the `ANTHROPIC_API_KEY` repo secret or the federation repo variables (+ the Claude GitHub App). OpenCode needs `OPENCODE_PROVIDER_KEY`.
370
+ - Both need GitHub Actions write permissions, the GitHub tracker, and (for the Cursor half) a dashboard trigger, and the tracker itself is opt-in.
371
+ - The env scaffolding is inert until the Claude / Cursor cloud env is wired in the dashboard.
372
+ - Autonomous routing by default, wired to an unconfigured tracker, is the wrong default, so an install without `--auto` ships zero cloud footprint.
312
373
 
313
374
  **How to decide:**
314
375
 
315
- 1. Run `bkit install --claude --cursor` (or whichever modules you want). Post-install banner lists `tracker-setup-none`, `dep-updater-absent`, `cloud-router-none` if undecided.
316
- 2. Pick tracker: `bkit install --tracker=github` (or `linear` / `jira`). Needs no host flag; re-renders every installed host. Persisted to `bkit.tracker.default`; future installs preserve (switching free).
317
- 3. Copy one updater example (table above). Land Renovate config on the default branch before installing the App.
318
- 4. Enable cloud agents: `bkit install --auto=claude|cursor|opencode`. Persisted to `bkit.cloud.agent`; install prints secrets + permissions + dashboard checklist (`bkit-auto-setup`). Shipped `bkit-cloud.yml` carries claude job (`ANTHROPIC_API_KEY` repo secret or federation repo variables — `.bkit/cloud.md` § Claude — workload identity federation) and opencode job (`OPENCODE_PROVIDER_KEY`), each runtime-gated.
319
- 5. **To opt out and silence the nudge**, set the field to `"none"` in `package.json` (`bkit.tracker.default` / `bkit.dependencies.updater` / `bkit.cloud.agent`). Advisory stays quiet. The `""` install seeds means undecided and keeps the nudge.
376
+ 1. Run `bkit install --claude --cursor` (or whichever modules you want). If you have not decided yet, the post-install banner lists `tracker-setup-none`, `dep-updater-absent` and `cloud-router-none`.
377
+ 2. Pick a tracker: `bkit install --tracker=github` (or `linear` / `jira`). It needs no host flag, and it re-renders every installed host. The choice is persisted to `bkit.tracker.default`, and future installs preserve it (switching is free).
378
+ 3. Copy one updater example (table above). Land the Renovate config on the default branch before installing the App. The next `bkit install` / `bkit upgrade` sets `bkit.dependencies.updater` to it.
379
+ 4. Enable cloud agents: `bkit install --auto=claude|cursor|opencode`. The choice is persisted to `bkit.cloud.agent`, and install prints the secrets + permissions + dashboard checklist (`bkit-auto-setup`). The shipped `bkit-cloud.yml` carries a claude job (`ANTHROPIC_API_KEY` repo secret or federation repo variables, see `.bkit/cloud.md` § Claude — workload identity federation) and an OpenCode job (`OPENCODE_PROVIDER_KEY`), each runtime-gated.
380
+ 5. **To opt out and silence the nudge**, set the field to `"none"` in `package.json` (`bkit.tracker.default` / `bkit.dependencies.updater` / `bkit.cloud.agent`). The advisory then stays quiet. The `""` that install seeds means undecided, and keeps the nudge.
320
381
 
321
- Tracker and cloud agents reverse by re-running install with the other flag. Updater files stay until you delete them.
382
+ To reverse the tracker or cloud-agent choice, re-run install with the other flag. Updater files stay until you delete them.
322
383
 
323
384
  **GitHub notifications.** bkit's agents comment as you, so every workflow those comments trigger notifies you, even ones that skip. To see only failures: GitHub → Settings → Notifications → System → Actions → "Only notify for failed workflows".
324
385
 
@@ -336,7 +397,7 @@ bkit tips --all # every firing tip
336
397
  <!-- prettier-ignore -->
337
398
  | Rule | Behaviour |
338
399
  | --- | --- |
339
- | Order | One fixed priority list. `--workflow=<name>` moves the tips that matter in that workflow to the front: tracker, GitHub token, `.bkit/.env` and direnv matter in every workflow, so they lead until fixed; then e.g. context-fetch for debug, Husky / slop-scan / Oxlint for build, CI workflow / cloud for ship, Serena / CI workflow / graphify / updater / Trivy for `audit`, Serena for `utility`. |
400
+ | Order | One fixed priority list. The upgrade tip (a newer bkit is out, per the answer `bkit repo info` caches) comes first everywhere, since an outdated bkit runs old workflow text, and no `bkit.advisories.ignore` entry silences it. `--workflow=<name>` moves the tips that matter in that workflow to the front: tracker, GitHub token, `.bkit/.env` and direnv matter in every workflow, so they lead until fixed; then e.g. context-fetch for debug, Husky / slop-scan / Oxlint for build, CI workflow / cloud for ship, Serena / CI workflow / graphify / updater / Trivy for `audit`, Serena for `utility`. |
340
401
  | Detection | Local only — files, settings, environment; no network. A tip clears once its local half exists; dashboard steps live in the tip text. |
341
402
  | Reuse | A tip for a gap an advisory already detects calls that advisory's detector — tip and advisory never disagree. |
342
403
  | Artifact | `bkit install` / `check` / `upgrade` / `doctor` list every firing tip, with its id, in `.bkit/advisories.md` § Setup tips and the console banner: line, why, caution, ask-your-agent sentence, agent steps. |
@@ -346,7 +407,7 @@ bkit tips --all # every firing tip
346
407
 
347
408
  ## Doctor
348
409
 
349
- `bkit doctor` is **diagnostic verb** — runs Phase 1 preflight + Phase 3 credential detectors, exits 0. Changes no managed file; like `bkit check` regenerates `.bkit/advisories.md` artifact (creates `.bkit/` if absent — repo that never installed bkit gains that one file).
410
+ `bkit doctor` is the **diagnostic verb**: it runs the Phase 1 preflight + Phase 3 credential detectors, and exits 0. It changes no managed file. Like `bkit check`, it regenerates the `.bkit/advisories.md` artifact, and it creates `.bkit/` if absent, so a repo that never installed bkit gains that one file.
350
411
 
351
412
  ```bash
352
413
  # Diagnose drift without running install
@@ -355,16 +416,17 @@ bkit doctor
355
416
 
356
417
  Use `bkit doctor` to:
357
418
 
358
- - Check `BKIT_GH_TOKEN` presence in shell (GitHub MCP auth) and the cloud-router claude credential (`ANTHROPIC_API_KEY` repo secret or federation repo variables; flags a key shadowing federation and an adopted `bkit-cloud.yml` too old for federation).
359
- - Surface `bkit-version-pin-stale` advisory (installed version ahead of `.bkit/version`).
360
- - Preview all advisories `bkit install` would show post-install, without triggering writes.
361
- - Verify environment ready before `bkit install` on new machine.
419
+ - Check that `BKIT_GH_TOKEN` is present in the shell (GitHub MCP auth), and check the cloud-router claude credential (`ANTHROPIC_API_KEY` repo secret or federation repo variables). It also flags a key shadowing federation, and an adopted `bkit-cloud.yml` too old for federation.
420
+ - Surface the `bkit-version-pin-stale` advisory (installed version ahead of `.bkit/version`).
421
+ - Preview all the advisories `bkit install` would show after install, without triggering writes.
422
+ - Verify the environment is ready before `bkit install` on a new machine.
362
423
  - Detect macOS GUI-isolation (`bkit cursor` / `bkit opencode`): see `.bkit/providers.md` § macOS GUI-isolation.
363
- `bkit doctor` always exits 0. Advisories found → printed in same checklist banner format as `bkit install`. None found → prints `[bkit-doctor] No advisories found.`
424
+
425
+ `bkit doctor` always exits 0. When it finds advisories, it prints them in the same checklist banner format as `bkit install`. When it finds none, it prints `[bkit-doctor] No advisories found.`
364
426
 
365
427
  ## Uninstall
366
428
 
367
- `bkit uninstall` surgically removes bkit-managed content while preserving consumer customisations. The `.bkit/core` / `.bkit/shared` payload view links go with a full/core uninstall (symlinks only — a real directory at either path is consumer content and stays).
429
+ `bkit uninstall` surgically removes bkit-managed content while preserving consumer customisations. The `.bkit/core` / `.bkit/shared` payload view links go with a full / core uninstall. It removes symlinks only, because a real directory at either path is consumer content and stays.
368
430
 
369
431
  ```bash
370
432
  # Uninstall EVERYTHING — all modules, including the cloud add-on if present.
@@ -396,43 +458,51 @@ bkit uninstall --nuke --yes
396
458
  | Format | Behaviour |
397
459
  | --- | --- |
398
460
  | `fully-managed` | Always deleted (bkit owns 100% of the file). |
399
- | `markered-text` | bkit block stripped; consumer content above/below preserved. File deleted if only whitespace remains — or, for a bkit-seeded markdown file (`AGENTS.md`/`CLAUDE.md`), if only its `# Title` heading husk remains. |
461
+ | `markered-text` | bkit block stripped; consumer content above / below preserved. File deleted if only whitespace remains — or, for a bkit-seeded markdown file (`AGENTS.md`/`CLAUDE.md`), if only its `# Title` heading husk remains. |
400
462
  | `byte-equal-text` | Deleted only if current hash matches the hash `.bkit/version` recorded when bkit last wrote it (`canonicalHashes`). Consumer modifications → preserved. `canonicalHashes` is internal state `bkit check` does not verify: a hand-edited or corrupted entry makes uninstall keep that file as consumer-modified (`--force` deletes it anyway) and upgrade's whole-file diff report a conflict instead of updating it. Rendered `.bkit/*.md` skip that diff: upgrade always re-renders them, and `bkit check` flags a hand edit. |
401
463
  | `json` | bkit's keys stripped; consumer keys preserved. `.mcp.json` / `.cursor/mcp.json`: only bkit's tracker entry is removed, and only while it still equals the template. `.opencode/opencode.json`: every `mcp` tracker entry (`github`, `linear`, `jira`) and every `provider` block of a supported provider is removed while it still equals what install renders — all the earlier installs left, not just the active one; an edited entry is kept whole. File deleted when nothing is left. |
402
464
 
403
465
  ### Idempotency
404
466
 
405
- Running `bkit uninstall` twice is safe — subsequent runs skip absent files and produce zero writes.
467
+ Running `bkit uninstall` twice is safe, because later runs skip absent files and produce zero writes.
406
468
 
407
469
  ### What a full uninstall preserves
408
470
 
409
- Bare uninstall removes bkit-managed files and strips bkit-managed blocks, but **not** guaranteed zero-footprint wipe. `docs/`: bkit's block (managed marker included) is stripped from every installed `docs/*.md` — a file holding nothing else is deleted — and the owned `docs/templates/bkit-*.md` are deleted. Deliberately leaves: everything outside `bkit:start` / `bkit:end` in `docs/*.md`, `.agents/context.md`, `.agents/skills.md` and the other managed-block files; your own files in `docs/` and `docs/templates/`; every file you copied from `.bkit/templates/`; any owned whole-file the consumer modified (hash mismatch → preserved); generated artefacts not manifest-tracked (`.bkit/advisories.md`, `.bkit/friction.jsonl`, the newest-release cache `.git/bkit-latest-version.json`). Use `--nuke` to force-remove every manifest-listed bkit file regardless of consumer modifications; generated artefacts still yours to delete by hand.
471
+ A bare uninstall removes bkit-managed files and strips bkit-managed blocks, but it is not a guaranteed zero-footprint wipe. In `docs/`, bkit's block (managed marker included) is stripped from every installed `docs/*.md`, a file holding nothing else is deleted, and the owned `docs/templates/bkit-*.md` are deleted. It deliberately leaves:
472
+
473
+ - everything outside `bkit:start` / `bkit:end` in `docs/*.md`, `.agents/context.md`, `.agents/skills.md` and the other managed-block files;
474
+ - your own files in `docs/` and `docs/templates/`;
475
+ - every file you copied from `.bkit/templates/`;
476
+ - any owned whole-file the consumer modified (hash mismatch → preserved);
477
+ - generated artefacts that are not manifest-tracked (`.bkit/advisories.md`, `.bkit/friction.jsonl`, the newest-release cache `.git/bkit-latest-version.json`).
478
+
479
+ Use `--nuke` to force-remove every manifest-listed bkit file regardless of consumer modifications. The generated artefacts are still yours to delete by hand.
410
480
 
411
481
  ## Phase 3 exit-1 and recovery
412
482
 
413
- When `bkit install` detects **blocker-severity** finding in Phase 3 (e.g. `owned-hook-missing` — a bkit-owned hook file is gone, so the guard or setup step it holds does not run), exits 1 and prints single-line recovery command:
483
+ When `bkit install` detects a blocker-severity finding in Phase 3 (for example `owned-hook-missing`: a bkit-owned hook file is gone, so the guard or setup step it holds does not run), it exits 1 and prints a single-line recovery command:
414
484
 
415
485
  ```
416
486
  [bkit-install] 1 Phase 3 blocker(s) detected. Recovery:
417
487
  bkit uninstall <flags> && <fix the issue> && bkit install <flags>
418
488
  ```
419
489
 
420
- Advisories (non-blockers) informational only — do not trigger exit-1.
490
+ Advisories (non-blockers) are informational only, and do not trigger exit-1.
421
491
 
422
492
  ### --auto-revert
423
493
 
424
- Add `--auto-revert` to `bkit install` to automatically run `bkit uninstall` in-process when Phase 3 blocker fires:
494
+ Add `--auto-revert` to `bkit install` to automatically run `bkit uninstall` in-process when a Phase 3 blocker fires:
425
495
 
426
496
  ```bash
427
497
  bkit install --auto-revert
428
498
  ```
429
499
 
430
- Useful in CI scripts to guarantee clean state on failure.
500
+ This is useful in CI scripts to guarantee a clean state on failure.
431
501
 
432
502
  ## Install staging directory
433
503
 
434
- `bkit install` renders derived files (e.g. `.opencode/opencode.json`) into `.bkit-staging/` scratch directory before merging into consumer destinations. Scratch directory cleaned up after every run — success and failure alike — never persists in committed consumer repo state.
504
+ `bkit install` renders derived files (for example `.opencode/opencode.json`) into the `.bkit-staging/` scratch directory before merging them into the consumer destinations. The scratch directory is cleaned up after every run, on success and failure alike, and never persists in committed consumer repo state.
435
505
 
436
- **Not a cross-module transaction.** Modules write directly to destinations — `bkit install` not atomic across modules: failure partway (e.g. hand-broken `.claude/settings.json` makes JSON merge throw) leaves earlier-module files written and `.bkit/version` unpinned. Error surfaced, not swallowed.
506
+ **Not a cross-module transaction.** Modules write directly to their destinations, so `bkit install` is not atomic across modules. A failure partway (for example a hand-broken `.claude/settings.json` that makes the JSON merge throw) leaves the earlier modules' files written and `.bkit/version` unpinned. The error is surfaced, not swallowed.
437
507
 
438
- **Recovery is re-run.** `bkit install` idempotent — fix offending file and re-run to complete. `bkit uninstall` removes whatever was written.
508
+ **Recovery is re-run.** `bkit install` is idempotent: fix the offending file and re-run to complete. `bkit uninstall` removes whatever was written.