@cbartens/bkit 5.0.3 → 5.2.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 (212) hide show
  1. package/.bkit/README.md +14 -10
  2. package/.bkit/core/.agents/docs.md +1 -0
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +93 -0
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +137 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +72 -0
  6. package/.bkit/core/.agents/rules.md +10 -6
  7. package/.bkit/core/.agents/shortcuts.md +73 -0
  8. package/.bkit/core/.agents/skills.md +5 -3
  9. package/.bkit/core/.bkit/LICENSE.md +18 -140
  10. package/.bkit/core/.bkit/README.md +13 -9
  11. package/.bkit/core/.bkit/cloud.md +12 -15
  12. package/.bkit/core/.bkit/comparison.md +68 -16
  13. package/.bkit/core/.bkit/install.md +36 -11
  14. package/.bkit/core/.bkit/jsonl.md +0 -1
  15. package/.bkit/core/.bkit/prompts.md +83 -81
  16. package/.bkit/core/.bkit/providers.md +110 -28
  17. package/.bkit/core/.bkit/templates.md +42 -13
  18. package/.bkit/core/.bkit/workflows.md +64 -42
  19. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +4 -3
  20. package/.bkit/core/.claude/hooks/bkit-readguard.cjs +60 -0
  21. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +8 -6
  22. package/.bkit/core/.codex/hooks/bkit-readguard.cjs +58 -0
  23. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +12 -19
  24. package/.bkit/core/.cursor/hooks/bkit-readguard.cjs +59 -0
  25. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +73 -22
  26. package/.bkit/core/.opencode/plugin/bkit-readguard.js +126 -0
  27. package/.bkit/core/AGENTS.md +11 -0
  28. package/.bkit/core/docs/templates/bkit-audit-adoption.md +2 -2
  29. package/.bkit/core/docs/templates/bkit-plan.md +6 -3
  30. package/.bkit/core/engine/checks/after/auth.ts +32 -0
  31. package/.bkit/core/engine/checks/after/github.ts +4 -4
  32. package/.bkit/core/engine/checks/after/index.ts +36 -50
  33. package/.bkit/core/engine/checks/after/managed.ts +44 -1
  34. package/.bkit/core/engine/checks/before/index.ts +5 -4
  35. package/.bkit/core/engine/checks/before/mcp.ts +60 -54
  36. package/.bkit/core/engine/checks/status-holes.ts +1 -1
  37. package/.bkit/core/engine/checks/tips/catalogue.ts +356 -0
  38. package/.bkit/core/engine/checks/tips/detect.ts +144 -0
  39. package/.bkit/core/engine/checks/tips/index.ts +174 -0
  40. package/.bkit/core/engine/cli.ts +82 -18
  41. package/.bkit/core/engine/commands/install/check.ts +2 -0
  42. package/.bkit/core/engine/commands/install/doctor.ts +14 -1
  43. package/.bkit/core/engine/commands/install/install.ts +59 -9
  44. package/.bkit/core/engine/commands/install/uninstall.ts +59 -34
  45. package/.bkit/core/engine/commands/install/upgrade.ts +30 -28
  46. package/.bkit/core/engine/commands/launch.ts +33 -11
  47. package/.bkit/core/engine/commands/tips.ts +16 -0
  48. package/.bkit/core/engine/commands/workflow/prs.ts +20 -2
  49. package/.bkit/core/engine/commands/workflow/runs.ts +82 -18
  50. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -0
  51. package/.bkit/core/engine/commands/workflow/steps.ts +1 -0
  52. package/.bkit/core/engine/commands/workflow/tests.ts +647 -4
  53. package/.bkit/core/engine/commands/workflow/workstreams.ts +4 -4
  54. package/.bkit/core/engine/install/cloud-env.ts +7 -21
  55. package/.bkit/core/engine/install/hosts.ts +21 -0
  56. package/.bkit/core/engine/install/managed-block.ts +36 -0
  57. package/.bkit/core/engine/install/manifest.ts +83 -5
  58. package/.bkit/core/engine/install/modules/antigravity.ts +266 -0
  59. package/.bkit/core/engine/install/modules/claude.ts +6 -6
  60. package/.bkit/core/engine/install/modules/cloud.ts +2 -2
  61. package/.bkit/core/engine/install/modules/codex.ts +8 -5
  62. package/.bkit/core/engine/install/modules/core.ts +30 -10
  63. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  64. package/.bkit/core/engine/install/modules/index.ts +33 -6
  65. package/.bkit/core/engine/install/modules/opencode.ts +4 -4
  66. package/.bkit/core/engine/install/payload-links.ts +6 -10
  67. package/.bkit/core/engine/install/placeholders.ts +1 -1
  68. package/.bkit/core/engine/install/version-file.ts +17 -9
  69. package/.bkit/core/engine/install/write.ts +68 -1
  70. package/.bkit/core/engine/ledgers/telemetry.ts +0 -2
  71. package/.bkit/core/engine/render/hosts.ts +174 -1
  72. package/.bkit/core/engine/render/models.ts +10 -0
  73. package/.bkit/core/engine/shared/package-roots.ts +8 -10
  74. package/.bkit/core/hooks/antigravity-hook.js +67 -0
  75. package/.bkit/core/hooks/gateguard-edit-payload.js +4 -4
  76. package/.bkit/core/hooks/gateguard-engine.js +16 -6
  77. package/.bkit/core/hooks/guardrails-read.js +23 -0
  78. package/.bkit/core/hooks/readguard-engine.js +259 -0
  79. package/.bkit/core/hooks/readguard-payload.js +67 -0
  80. package/.bkit/core/prompts/bkit-audit-generate.md +2 -1
  81. package/.bkit/core/prompts/bkit-build-challenge-1.md +2 -1
  82. package/.bkit/core/prompts/bkit-build-challenge-2.md +2 -1
  83. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +2 -1
  84. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +2 -1
  85. package/.bkit/core/prompts/bkit-build-challenge-tests.md +2 -1
  86. package/.bkit/core/prompts/bkit-build-install-skills.md +7 -5
  87. package/.bkit/core/prompts/bkit-build-plan-current.md +2 -1
  88. package/.bkit/core/prompts/bkit-build-plan-execute.md +6 -2
  89. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +2 -1
  90. package/.bkit/core/prompts/bkit-build-plan-verify.md +12 -4
  91. package/.bkit/core/prompts/bkit-build-summary.md +2 -1
  92. package/.bkit/core/prompts/bkit-debug-abort-handover.md +2 -1
  93. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +2 -1
  94. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +2 -1
  95. package/.bkit/core/prompts/bkit-debug-failure-soak.md +2 -1
  96. package/.bkit/core/prompts/bkit-debug-summary.md +2 -1
  97. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +2 -1
  98. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +2 -1
  99. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +2 -1
  100. package/.bkit/core/prompts/bkit-design-generate.md +10 -5
  101. package/.bkit/core/prompts/bkit-design-organise.md +2 -1
  102. package/.bkit/core/prompts/bkit-design-review-1.md +2 -1
  103. package/.bkit/core/prompts/bkit-design-review-2.md +2 -1
  104. package/.bkit/core/prompts/bkit-design-spike.md +2 -1
  105. package/.bkit/core/prompts/bkit-design-summary.md +2 -1
  106. package/.bkit/core/prompts/bkit-design-update.md +2 -1
  107. package/.bkit/core/prompts/bkit-plan-complexity-check.md +2 -1
  108. package/.bkit/core/prompts/bkit-plan-complexity-split.md +4 -3
  109. package/.bkit/core/prompts/bkit-plan-generate.md +2 -1
  110. package/.bkit/core/prompts/bkit-plan-review-1.md +2 -1
  111. package/.bkit/core/prompts/bkit-plan-review-2.md +2 -1
  112. package/.bkit/core/prompts/bkit-plan-review-3.md +2 -1
  113. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +3 -2
  114. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +3 -2
  115. package/.bkit/core/prompts/bkit-plan-summary.md +2 -1
  116. package/.bkit/core/prompts/bkit-plan-update.md +3 -2
  117. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +2 -1
  118. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +2 -1
  119. package/.bkit/core/prompts/bkit-ship-summary.md +2 -1
  120. package/.bkit/core/prompts/bkit-ship-update-docs.md +2 -1
  121. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +2 -1
  122. package/.bkit/core/prompts/bkit-utility-update-decisions.md +2 -1
  123. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +2 -1
  124. package/.bkit/core/prompts/bkit-utility-update-documentation.md +2 -1
  125. package/.bkit/core/prompts/bkit-utility-update-failures.md +2 -1
  126. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +2 -1
  127. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -3
  128. package/.bkit/core/workflows/bkit-auto.md +1 -1
  129. package/.bkit/core/workflows/bkit-build.md +35 -21
  130. package/.bkit/core/workflows/bkit-debug.md +31 -22
  131. package/.bkit/core/workflows/bkit-design.md +83 -38
  132. package/.bkit/core/workflows/bkit-plan.md +10 -2
  133. package/.bkit/core/workflows/bkit-ship.md +10 -2
  134. package/.bkit/shared/.agents/plugins/bkit/hooks.json +36 -0
  135. package/.bkit/shared/.agents/plugins/bkit/plugin.json +5 -0
  136. package/.bkit/shared/.claude/settings.json +19 -0
  137. package/.bkit/shared/.codex/hooks.json +21 -0
  138. package/.bkit/shared/.cursor/hooks.json +6 -1
  139. package/.bkit/shared/.opencode/opencode.json +1 -1
  140. package/.bkit/shared/GEMINI.md +11 -0
  141. package/.bkit/shared/docs/deployments.md +1 -1
  142. package/.bkit/shared/docs/security.md +3 -3
  143. package/.bkit/shared/docs/testing.md +12 -1
  144. package/.bkit/templates/.github/dependabot.yml +6 -0
  145. package/.bkit/templates/.github/renovate.json5 +3 -3
  146. package/.bkit/templates/.github/workflows/bkit-ci.yml +24 -13
  147. package/.bkit/templates/.github/workflows/bkit-cloud.yml +5 -5
  148. package/.bkit/templates/.prettierignore +4 -1
  149. package/.bkit/templates/context/bkit-expo.md +22 -13
  150. package/.bkit/templates/context/bkit-github.md +20 -6
  151. package/.bkit/templates/context/bkit-inngest.md +10 -4
  152. package/.bkit/templates/context/bkit-maestro.md +5 -5
  153. package/.bkit/templates/context/bkit-playwright.md +3 -3
  154. package/.bkit/templates/context/bkit-sentry.md +6 -5
  155. package/.bkit/templates/context/bkit-stripe.md +31 -8
  156. package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +65 -19
  157. package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +34 -0
  158. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +33 -12
  159. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +54 -0
  160. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +2 -2
  161. package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +76 -6
  162. package/.bkit/templates/slop-scan.config.json +10 -3
  163. package/CHANGELOG.md +62 -0
  164. package/LICENSE.md +21 -161
  165. package/README.md +66 -35
  166. package/dist/checks/after/auth.js +28 -0
  167. package/dist/checks/after/github.js +4 -4
  168. package/dist/checks/after/index.js +29 -45
  169. package/dist/checks/after/managed.js +41 -1
  170. package/dist/checks/before/index.js +5 -4
  171. package/dist/checks/before/mcp.js +53 -53
  172. package/dist/checks/status-holes.js +1 -1
  173. package/dist/checks/tips/catalogue.js +297 -0
  174. package/dist/checks/tips/detect.js +130 -0
  175. package/dist/checks/tips/index.js +146 -0
  176. package/dist/cli.js +68 -17
  177. package/dist/commands/install/check.js +2 -0
  178. package/dist/commands/install/doctor.js +9 -1
  179. package/dist/commands/install/install.js +49 -8
  180. package/dist/commands/install/uninstall.js +61 -34
  181. package/dist/commands/install/upgrade.js +31 -33
  182. package/dist/commands/launch.js +27 -11
  183. package/dist/commands/tips.js +10 -0
  184. package/dist/commands/workflow/prs.js +13 -1
  185. package/dist/commands/workflow/runs.js +74 -18
  186. package/dist/commands/workflow/runtime.js +8 -0
  187. package/dist/commands/workflow/steps.js +1 -0
  188. package/dist/commands/workflow/tests.js +541 -4
  189. package/dist/commands/workflow/workstreams.js +4 -4
  190. package/dist/install/cloud-env.js +3 -14
  191. package/dist/install/hosts.js +22 -0
  192. package/dist/install/managed-block.js +36 -0
  193. package/dist/install/manifest.js +79 -4
  194. package/dist/install/modules/antigravity.js +225 -0
  195. package/dist/install/modules/claude.js +6 -6
  196. package/dist/install/modules/cloud.js +2 -2
  197. package/dist/install/modules/codex.js +8 -5
  198. package/dist/install/modules/core.js +21 -6
  199. package/dist/install/modules/cursor.js +6 -6
  200. package/dist/install/modules/index.js +17 -6
  201. package/dist/install/modules/opencode.js +4 -4
  202. package/dist/install/payload-links.js +5 -5
  203. package/dist/install/placeholders.js +1 -1
  204. package/dist/install/version-file.js +12 -3
  205. package/dist/install/write.js +61 -2
  206. package/dist/render/hosts.js +149 -1
  207. package/dist/render/models.js +9 -0
  208. package/dist/shared/package-roots.js +8 -11
  209. package/package.json +8 -8
  210. package/.bkit/core/LICENSE.md +0 -149
  211. package/.bkit/shared/LICENSE.md +0 -22
  212. package/.bkit/templates/LICENSE.md +0 -22
@@ -22,8 +22,9 @@
22
22
  | --- | --- | --- | --- | --- | --- | --- |
23
23
  | Claude Code | canonical | `.claude/agents/` | `.claude/commands/` | `.claude/settings.json` | `.claude/hooks/` (registered in settings) | `bkit install --claude` |
24
24
  | Cursor | derived | `.cursor/agents/` | `.cursor/commands/` | `.cursor/settings.json` + `.cursor/environment.json` + `.cursor/Dockerfile` (templates, `.bkit/templates.md`) | `.cursor/hooks/` (registered in `.cursor/hooks.json`) | `bkit install --cursor` |
25
- | opencode | additive (opt-in) | `.opencode/agents/` | `.opencode/commands/` | `.opencode/opencode.json` | `.opencode/plugin/bkit-gateguard.js` (PreToolUse) | `bkit install --opencode=<provider>` |
26
- | Codex CLI | additive (opt-in) | `.codex/agents/` (TOML) | none — skills (below) | none (`openai` = reserved built-in id) | `.codex/hooks/bkit-gateguard.cjs` + `.codex/hooks/bkit-guardrails.cjs` (PreToolUse `apply_patch` / `Bash`, via `.codex/hooks.json`) | `bkit install --codex` |
25
+ | opencode | additive (opt-in) | `.opencode/agents/` | `.opencode/commands/` | `.opencode/opencode.json` | `.opencode/plugin/bkit-gateguard.js` + `.opencode/plugin/bkit-readguard.js` (tool execute hooks) | `bkit install --opencode=<provider>` |
26
+ | Codex CLI | additive (opt-in) | `.codex/agents/` (TOML) | none — skills (below) | none (`openai` = reserved built-in id) | `.codex/hooks/bkit-gateguard.cjs` + `.codex/hooks/bkit-guardrails.cjs` + `.codex/hooks/bkit-readguard.cjs` (PreToolUse `apply_patch` / `Bash`, PreCompact, via `.codex/hooks.json`) | `bkit install --codex` |
27
+ | Google Antigravity | additive (opt-in) | `.agents/plugins/bkit/agents/` | none — skills (plugin, below) | `GEMINI.md` (workspace rule) | `.agents/plugins/bkit/hooks/bkit-gateguard.cjs` + `.agents/plugins/bkit/hooks/bkit-guardrails.cjs` + `.agents/plugins/bkit/hooks/bkit-readguard.cjs` (PreToolUse `write_to_file` / `replace_file_content` / `view_file` / `run_command`, via `.agents/plugins/bkit/hooks.json`) | `bkit install --antigravity` |
27
28
 
28
29
  **Two axes — host != provider.** **Host** = program reading what bkit writes, identified by its dir (`.claude/`, `.cursor/`, `.opencode/`, `.codex/`). **Provider** = gateway tokens are bought through. Model IDs are per-provider → `prompts.md` § Models = one column per PROVIDER (shared provider = one column, never two). Thinking depth is per-host (field name + ladder set by host config format: `effort:` claude/cursor, a `variant:` field opencode, `model_reasoning_effort` codex) → § Effort = one column per HOST. Neither table grows as hosts x providers.
29
30
 
@@ -35,6 +36,7 @@
35
36
  | Claude Code | `anthropic` | Claude subscription = cheapest path to Claude models |
36
37
  | Cursor | `cursor` | Cursor subscription covers its whole catalog |
37
38
  | Codex CLI | `openai` | ChatGPT subscription |
39
+ | Google Antigravity | `google` | Antigravity free tier / Google subscription — cheapest path to Gemini |
38
40
  | opencode | **pick one**: `openrouter`, `ollama`, `opencode-zen`, `opencode-go` | no subscription — BYO key, so the choice is yours |
39
41
 
40
42
  Subscription-bearing host → pinned, nullary flag (`--claude`, `--codex`). BYO-key host → pluggable, flag names the provider (`--opencode=<provider>`). Per-model deviation → consumer `## Model Overrides` below `bkit:end`; no provider override.
@@ -45,13 +47,26 @@ Subscription-bearing host → pinned, nullary flag (`--claude`, `--codex`). BYO-
45
47
  | Concern | On Codex |
46
48
  | --- | --- |
47
49
  | Agent files | `.codex/agents/*.toml` (TOML, not markdown). Required: `name`, `description`, `developer_instructions`. Pin + rung: `model`, `model_reasoning_effort`. |
48
- | Workflows = SKILLS, invoked `$bkit-design` | no project-scoped command surface — custom prompts are `~/.codex/prompts` only, not repo-shared, deprecated for skills (upstream declined repo-scoped prompts). bkit renders `.agents/skills/bkit-<workflow>/SKILL.md`, on Codex's skill path (`$REPO_ROOT/.agents/skills`). `.agents/` is shared → visible to every host. |
50
+ | Workflows = SKILLS, invoked `$bkit-design` | no project-scoped command surface — custom prompts are `~/.codex/prompts` only, not repo-shared, deprecated for skills (upstream declined repo-scoped prompts). bkit renders `.agents/skills/bkit-<workflow>/SKILL.md`, on Codex's skill path (`$REPO_ROOT/.agents/skills`). This path is Codex's; Antigravity ships its own skills in a plugin (`.agents/plugins/bkit/skills/`). |
49
51
  | `tools:` not enforced | No per-agent tool allowlist upstream; `sandbox_mode` cannot substitute — every bkit agent is write-capable, so all would be `workspace-write`. Each agent gets the full built-in tool set regardless of declared `tools:`. GateGuard still gates, as everywhere. |
50
52
 
51
53
  > **GateGuard needs the `.codex/` layer TRUSTED.** Codex loads project-local hooks only once trusted. Until then the hook is installed and never fires — present, proving nothing. Same for `bkit-guardrails.cjs`.
52
54
  >
53
55
  > **Codex cannot prompt.** It parses `permissionDecision: "ask"` but does not implement it — an ask is recorded as an error and the call proceeds. `bkit-guardrails.cjs` therefore blocks the `deny` tier for real and emits the `ask` tier as advisory `additionalContext`: the gate fires and informs, it cannot stop the command. Every ask-tier command is already PROHIBITED in all five workflow headers, so no bkit workflow reaches one. Asserted in `.bkit/core/engine/install/modules/index.integration.test.ts`.
54
56
 
57
+ ### Google Antigravity — installs as a workspace plugin
58
+
59
+ <!-- prettier-ignore -->
60
+ | Concern | On Antigravity |
61
+ | --- | --- |
62
+ | Install layout | the whole host is a workspace **plugin** at `.agents/plugins/bkit/` (`plugin.json` + `skills/` + `agents/` + `hooks.json` + `hooks/`) — Antigravity's own packaging surface, activated per project. `.agents/` root stays the dedicated Codex install. |
63
+ | Workflows = SKILLS at `.agents/plugins/bkit/skills/bkit-<workflow>/SKILL.md` | Antigravity auto-discovers a workspace plugin's `skills/`. Codex's workflow skills stay at `.agents/skills/bkit-*/`; with both hosts installed Antigravity's selector lists both sets (accepted; `antigravity-codex-skill-overlap` advisory names which to pick). |
64
+ | Prompt files + no native subagent tool | prompts at `.agents/plugins/bkit/agents/*.md` — frontmatter `name`/`description`, model pin from § Models `Google` column, `effort` from § Effort `Antigravity` column, `tools:` respelled to Antigravity tool names. The orchestrator loads each with `view_file` and runs it in-session; isolated runs use `run_command` (`agy`). `**Subagent:** @name` respells to `` `view_file` `.agents/plugins/bkit/agents/name.md` `` rather than a `/name` slash command. |
65
+
66
+ > **Antigravity tool names differ from Claude's.** `Read`→`view_file`, `Write`→`write_to_file`, `Edit`→`replace_file_content`, `Bash`→`run_command`, `Grep`→`grep_search`, `Glob`→`list_dir`, `WebSearch`→`search_web`, `WebFetch`→`read_url`. `mcp__<server>__<tool>` keeps its spelling. `applyAntigravityPrompt` / `antigravityToolsBlock` (`.bkit/core/engine/render/hosts.ts`) apply the map at render.
67
+ >
68
+ > **GateGuard + ReadGuard + guardrails wired from `.agents/plugins/bkit/hooks.json`** (PreToolUse on `write_to_file` / `replace_file_content` / `view_file` / `run_command`). Same fail-open engines as the other hosts on Antigravity's own contract, live-verified on the agy CLI: stdin `{ conversationId, toolCall: { name, args }, workspacePaths }`, stdout `{ decision, reason }`. Only a `deny`'s reason reaches the model, so every advisory denies the call once with the advisory as the reason and lets the identical retry through; the guardrails deny tier blocks every time; its ask tier is Antigravity's own `ask`. Guardrails also gates `view_file` secret reads (§ Permissions / auto-approve). A `PreInvocation` entry in `hooks.json` stops every hook in the file from firing — bkit registers none. Plugin hook commands run with the plugin dir (`.agents/plugins/bkit/`) as cwd, so each command tries `hooks/<file>` first, then `.agents/plugins/bkit/hooks/<file>`.
69
+
55
70
  **Explicit host axis (no implicit full):** `bkit install` requires ≥1 module flag — bare `bkit install` errors. Every host explicit; hosts compose: `bkit install --claude --cursor --opencode=opencode-zen` installs all three (+ implicit core). `--opencode` cannot render without `=<provider>` (strict allowlist). Switch providers: re-run install. All hosts render from `.bkit/`; run state in `status.jsonl` + plan docs + tracker (never host session) — phase/resumed run moves across hosts/providers mid-feature with identical gates + per-agent pins: hit limit on one, continue on another. `bkit status` → installed hosts + active providers; `bkit doctor` → credentials + tool reachability.
56
71
 
57
72
  **Cheap models inside an IDE — no extension needed.** A host is its dir, not the window its process runs in. `bkit install --claude --cursor --opencode=openrouter` + opencode in the IDE's integrated terminal = every agent pin, GateGuard and the full workflow on OpenRouter while editing in Cursor. Supported path when the Claude subscription is spent.
@@ -60,7 +75,7 @@ Subscription-bearing host → pinned, nullary flag (`--claude`, `--codex`). BYO-
60
75
 
61
76
  **Additive multi-provider install:** `bkit install --opencode=<provider>` additive — second provider adds block to `opencode.json`, keeps first. Agent frontmatter (`model:`) re-renders to last-installed (active) provider; other blocks stay for interactive switch/overrides. Installed providers → `bkit.opencodeProviders: string[]` in `package.json`; active → `bkit.opencodeProvider`. `bkit status` lists all, marks active; `bkit doctor` checks all credentials. Remove one: `bkit uninstall --opencode=<provider>` (surgical — block + array; if active removed, re-point via `bkit install --opencode=<new>` or `bkit upgrade`). `bkit uninstall --opencode` (bare) tears down entire opencode host.
62
77
 
63
- New host — row above + `run<Host>Module` (`.bkit/core/engine/install/modules/<host>.ts`) + manifest block (`.bkit/core/engine/install/manifest.ts`) + `.bkit/core/.<host>/hooks/` (the host config JSON in `.bkit/shared/.<host>/`) + GateGuard case in `.bkit/core/engine/audits/hooks/gateguard-parity.integration.test.ts`. New provider also needs `GATEWAY_COLUMN` (`.bkit/core/engine/render/models.ts`) + a curated `prompts.md` § Models column.
78
+ New host — row above + `run<Host>Module` (`.bkit/core/engine/install/modules/<host>.ts`) + manifest block (`.bkit/core/engine/install/manifest.ts`) + `.bkit/core/.<host>/hooks/` (the host config JSON in `.bkit/shared/.<host>/`) + GateGuard case in `.bkit/core/engine/audits/hooks/gateguard-parity.integration.test.ts` + ReadGuard case in `.bkit/core/engine/audits/hooks/readguard-parity.integration.test.ts`. New provider also needs `GATEWAY_COLUMN` (`.bkit/core/engine/render/models.ts`) + a curated `prompts.md` § Models column.
64
79
 
65
80
  ---
66
81
 
@@ -84,7 +99,7 @@ bkit opencode # /Applications/opencode.app/Contents/MacOS/opencode
84
99
 
85
100
  **`bkit doctor` check:** reports `.bkit/.env` keys with non-empty file value but absent from `process.env` (= Dock/Finder session); advisory → `bkit cursor` / `bkit opencode`.
86
101
 
87
- **launchctl fallback (opt-in, not recommended):** exposes key to launchd apps current session only (not persistent across reboots). Manual re-run after restart + manual rotation — prefer launcher verbs.
102
+ **launchctl fallback (opt-in, not recommended):** exposes key to EVERY app in the login session (not only the intended one; not persistent across reboots). Manual re-run after restart + manual rotation/removal — prefer launcher verbs.
88
103
 
89
104
  ```bash
90
105
  launchctl setenv BKIT_GH_TOKEN "$BKIT_GH_TOKEN"
@@ -104,6 +119,7 @@ Persistent variant: `RunAtLoad` LaunchAgent plist (`~/Library/LaunchAgents/`) wi
104
119
  | Claude | `Agent` | `@` | `@bkit-build-plan-execute` invoked via `Agent` tool |
105
120
  | Cursor | `Task` | `/` | `/bkit-build-plan-execute` invoked via `Task` tool |
106
121
  | opencode | `/` (slash command) | `/` | `/bkit-build-plan-execute` invoked via opencode slash command |
122
+ | Antigravity | `view_file` (in-session prompt load) | `.agents/plugins/bkit/agents/` | `view_file` `.agents/plugins/bkit/agents/bkit-build-plan-execute.md` |
107
123
 
108
124
  **Transform (Claude → Cursor, command bodies):**
109
125
 
@@ -259,17 +275,21 @@ Both hosts: `/<filename-without-ext>` (`/bkit-build`, `/bkit-plan`, etc.). Ident
259
275
  <!-- prettier-ignore -->
260
276
  | Part | Shared by | Holds |
261
277
  | --- | --- | --- |
262
- | `gateguard-engine.js` | Claude, Cursor, Codex, opencode `gateguard` | gate-config table, checklists, docs advisory, dedup state, `firstTouchAdvice` |
278
+ | `gateguard-engine.js` | Claude, Cursor, Codex, Google Antigravity, opencode `gateguard` | gate-config table, checklists, docs advisory, dedup state, `firstTouchAdvice` |
263
279
  | `gateguard-edit-payload.js` | Claude, Cursor `gateguard` | `Edit` / `Write` / `MultiEdit` payload adapter `bkitGateguard(payload)` |
264
- | `guardrails-shell.js` | Claude, Cursor, Codex `guardrails` | segment parsing, curl / wget host allowlist, shell-as-edit-channel detection |
265
- | `guardrails-tiers.js` | Cursor, Codex `guardrails` | deny rules, ask patterns, `classifyShell` precedence |
280
+ | `readguard-engine.js` | Claude, Cursor, Codex, Google Antigravity, opencode `readguard` | shell-read parser, line-range log per (session, agent), repeat-read note, `resetReadLog` |
281
+ | `readguard-payload.js` | Claude, Cursor, Codex, Google Antigravity `readguard` | read / shell payload adapter `bkitReadguard(payload)`; compaction event → reset |
282
+ | `antigravity-hook.js` | Google Antigravity `gateguard`, `guardrails`, `readguard` | Antigravity envelope → Claude-family shape (`fromAntigravityPayload`), call signature, deny-once advisory delivery (`adviseOnce`) |
283
+ | `guardrails-shell.js` | Claude, Cursor, Codex, Google Antigravity `guardrails` | segment parsing, curl / wget host allowlist, shell-as-edit-channel detection |
284
+ | `guardrails-tiers.js` | Cursor, Codex, Google Antigravity `guardrails` | deny rules, ask patterns, `classifyShell` precedence |
285
+ | `guardrails-read.js` | Cursor, Google Antigravity `guardrails` | `classifyRead`: deny `*.pem` / `*.p12` / `id_rsa`, ask `.env` / `.env.*` (not `.env.example`) |
266
286
  | `preflight-linear.sh` | Claude, Cursor `preflight` | Linear key / issue checks, GraphQL query, `bkit:auto` + terminal-state guards |
267
287
 
268
- Per host, outside the parts: Claude `gateguard` / `guardrails` — `require` + `hookSpecificOutput` driver, guardrails advisory-only; Cursor — `{ permission }` output, guardrails read gate (`.pem` / `.env`), gateguard workspace-relative path resolve; Codex — `apply_patch` envelope parser, ask tier emitted as advisory; opencode — ES module, `write` / `edit` / `patch` vocabulary, checklist appended to the tool result in `execute.after` + throw from `execute.before` to block (2.0 exposes no pre-edit context hook, and stderr does not reach the model); `preflight` — trigger (Claude `LINEAR_ISSUE_ID`, Cursor `is_background_agent` + `.bkit/.runtime-cursor` marker), Claude-only Darwin brew check, `emit_context` shape.
288
+ Per host, outside the parts: Claude `gateguard` / `guardrails` — `require` + `hookSpecificOutput` driver, guardrails advisory-only; Cursor — `{ permission }` output, guardrails `Read|TabRead` path extraction, gateguard workspace-relative path resolve; Codex — `apply_patch` envelope parser, ask tier emitted as advisory; Google Antigravity — `antigravity-hook.js` envelope conversion + deny-once delivery, `{ decision, reason }` driver, `write_to_file` / `replace_file_content` edit tools (path `TargetFile`), `view_file` and `run_command` (`CommandLine`); opencode — ES module, `write` / `edit` / `patch` (`apply_patch`) vocabulary, every `*** Add|Update|Delete File:` / `*** Move to:` target of a `patchText` checked (deny mode blocks if any target is a first touch), checklist appended to the tool result in `execute.after` + throw from `execute.before` to block (2.0 exposes no pre-edit context hook, and stderr does not reach the model); `preflight` — trigger (Claude `LINEAR_ISSUE_ID`, Cursor `is_background_agent` + `.bkit/.runtime-cursor` marker), Claude-only Darwin brew check, `emit_context` shape.
269
289
 
270
290
  ### GateGuard
271
291
 
272
- Advisory hook, on all four hosts (Claude Code, Cursor, Codex, opencode). Claude / Cursor / Codex inject the checklist pre-edit (PreToolUse); opencode 2.0 exposes no pre-edit context hook, so it appends the checklist to the tool result in the post-execute hook — the first edit's result, not a pre-edit gate — and reserves the pre-execute hook for deny mode. First file touch per session → investigation checklist; gate-config paths (JS/TS: tsconfig/eslint/prettier/vitest/jest/vale/slop/lint-staged; Python: pyproject.toml/ruff/flake8/mypy; Go: golangci; Rust: clippy/rustfmt) → "fix code, don't weaken gate" advisory, except under a consumer's `.bkit/templates/` (reference copies; in bkit's own repo, package name `@cbartens/bkit`, that folder is the template source and stays guarded); new-file writes → reuse-over-duplicate nudge; `docs/**.md` (not `docs/plans/`) → density advisory appended. **fail-open**, **subagents included**, dedup `(session, file)` via OS-temp state, 24h TTL.
292
+ Advisory hook, on all five hosts (Claude Code, Cursor, Codex, Google Antigravity, opencode). Claude / Cursor / Codex inject the checklist pre-edit (PreToolUse); Antigravity denies the first edit of a file once with the checklist as the reason (the only text its hooks deliver to the model) and allows the retry; opencode 2.0 exposes no pre-edit context hook, so it appends the checklist to the tool result in the post-execute hook — the first edit's result, not a pre-edit gate — and reserves the pre-execute hook for deny mode. First file touch per session → investigation checklist; gate-config paths (JS/TS: tsconfig/eslint/prettier/vitest/jest/vale/slop/lint-staged; Python: ruff.toml/.ruff.toml/.flake8/mypy.ini/.mypy.ini/pylintrc/.pylintrc/pytest.ini; Go: golangci; Rust: clippy.toml/.clippy.toml/rustfmt.toml/.rustfmt.toml; mixed-purpose manifests such as package.json, pyproject.toml, setup.cfg, tox.ini are not matched) → "fix code, don't weaken gate" advisory, except under a consumer's `.bkit/templates/` (reference copies; in bkit's own repo, package name `@cbartens/bkit`, that folder is the template source and stays guarded); new-file writes → reuse-over-duplicate nudge; `docs/**.md` (not `docs/plans/`) → density advisory appended. **fail-open**, **subagents included**, dedup `(session, agent, file)` via OS-temp state, 24h TTL.
273
293
 
274
294
  <!-- prettier-ignore -->
275
295
  | Host | Implementation | File | Registration |
@@ -278,37 +298,53 @@ Advisory hook, on all four hosts (Claude Code, Cursor, Codex, opencode). Claude
278
298
  | opencode | `bkit-gateguard.js` (ESM) | `.opencode/plugin/bkit-gateguard.js` | `.opencode/opencode.json` → `plugin` array, spec `./plugin/bkit-gateguard.js` (config-file-relative; opencode 2.0 reads a bare `.opencode/…` spec as an npm package and fails to load — the plugin also auto-loads from `.opencode/plugin/`) |
279
299
  | Cursor | `bkit-gateguard.cjs` (CJS) — managed block generated from the same parts as the Claude twin, so byte-identical | `.cursor/hooks/bkit-gateguard.cjs` | `.cursor/hooks.json` → `preToolUse` (matcher `Write`), no `failClosed` — an advisory hook that fails closed would block the edit it only meant to comment on |
280
300
  | Codex | `bkit-gateguard.cjs` (CJS) — Claude's stdin/stdout contract; parses the `apply_patch` envelope for target paths | `.codex/hooks/bkit-gateguard.cjs` | `.codex/hooks.json` → `hooks.PreToolUse` on `apply_patch` |
301
+ | Antigravity | `bkit-gateguard.cjs` (CJS) — Antigravity's `{ toolCall, conversationId }` stdin / `{ decision, reason }` stdout; `write_to_file` / `replace_file_content` edit tools, path from `args.TargetFile` | `.agents/plugins/bkit/hooks/bkit-gateguard.cjs` | `.agents/plugins/bkit/hooks.json` → `hooks.PreToolUse` on `write_to_file\|replace_file_content` |
281
302
  | Cursor | `bkit-guardrails.cjs` (CJS) — destructive-op / secret-exposure gates, the Cursor equivalent of Claude's `permissions` and opencode's `permission` map | `.cursor/hooks/bkit-guardrails.cjs` | `.cursor/hooks.json` → `beforeShellExecution` + `preToolUse` (`Read\|TabRead`), both `failClosed` |
282
303
 
283
304
  **Ownership:** both GateGuard files — and Cursor's `bkit-guardrails.cjs` — are **markered-text** (slash-comment: `// bkit:start` / `// bkit:end`). bkit owns only the advisory engine between the markers and reconverges it on every install / upgrade; the driver around it — Claude's stdin read + single `emit()`, opencode's exported `plugin` — is consumer-owned from first install onward, so consumer advisories survive upgrades. bkit's block is pure (no stdin, no stdout / stderr, no top-level call): Claude Code parses hook stdout as one JSON document, so two emitters would produce `{...}{...}` and the whole hook's output — bkit's included — is discarded. Marker-less file on upgrade → hash matches a bkit release: replaced wholesale; hash unknown: block appended plus printed wiring instructions. Uninstall strips the block, leaving the consumer's driver working. `bkit-guardrails.cjs` follows the identical split: bkit owns `bkitGuardrails(payload)`, which returns a decision object or `null` for no-opinion, and the consumer owns the stdin read and the single `emit()`.
284
305
 
285
306
  **Modes (env):** unset → advisory _[default]_; `BKIT_GATEGUARD=off` → disabled; `BKIT_GATEGUARD=deny` → deny first touch (checklist as reason), allow retry. `BKIT_ALLOW_CONFIG_EDIT=1` suppresses gate-config advisory.
286
307
 
287
- **Subagents:** not exempt on any host. A subagent edit is an edit, and dedup is per (session, file) with a subagent carrying its own session id, so it gets its own checklist. No host reads a subagent marker (Claude's `agent_id`, opencode's `parentID`); Cursor's payload carries none.
308
+ **Subagents:** not exempt on any host; dedup is per (session, agent, file) wherever the host names the agent. Claude Code — a subagent shares its parent's `session_id`; its `agent_id` keys its own dedup, so it gets its own checklist. opencode — a subagent runs in its own session. Codex — tool payloads carry the parent's `session_id` inside a subagent and no agent id; Cursor — no subagent marker; Antigravity — no native subagents (prompts run in-session; `agy` runs are their own conversation). On Codex and Cursor a subagent editing a file its parent already touched gets no checklist.
309
+
310
+ **Deny mode, per host:** Claude and Codex `permissionDecision: "deny"` with the checklist as `permissionDecisionReason`; Antigravity `decision: "deny"` with the checklist as `reason` — the same as its advisory mode; Cursor `permission: "deny"` with the checklist as `agent_message` (`user_message` goes to the human, not the model); opencode throws from `execute.before` — the only hook that can block — and appends the checklist to the tool result in `execute.after`, because 2.0 exposes no pre-edit context hook and stderr does not reach the model. Same behaviour, three delivery mechanisms across five hosts; asserted uniformly in `.bkit/core/engine/audits/hooks/gateguard-parity.integration.test.ts`.
288
311
 
289
- **Deny mode, per host:** Claude and Codex `permissionDecision: "deny"` with the checklist as `permissionDecisionReason`; Cursor `permission: "deny"` with the checklist as `agent_message` (`user_message` goes to the human, not the model); opencode throws from `execute.before` — the only hook that can block — and appends the checklist to the tool result in `execute.after`, because 2.0 exposes no pre-edit context hook and stderr does not reach the model. Same behaviour, three delivery mechanisms across four hosts; asserted uniformly in `.bkit/core/engine/audits/hooks/gateguard-parity.integration.test.ts`.
312
+ **Divergence budget:** every host's block carries `hooks/gateguard-engine.js` verbatim, and the Claude and Cursor blocks are byte-identical (both test-asserted on the generated hooks). opencode's differs only where the runtime forces it — ES module rather than CJS, tool vocabulary `write`/`edit`/`patch` rather than `Edit`/`Write`/`MultiEdit`, plus a `patchText` envelope parser for `patch`. Codex's differs only in its payload — every edit arrives as `apply_patch` with a V4A envelope and no file path, so its block carries the envelope parser (Add / Update / Delete / Move-to targets). Antigravity's differs in its tool vocabulary (`write_to_file` / `replace_file_content`), its `TargetFile` extraction and the `antigravity-hook.js` contract part. Every advisory string, gate-config pattern and docs-path rule is identical across all five.
290
313
 
291
- **Divergence budget:** every host's block carries `hooks/gateguard-engine.js` verbatim, and the Claude and Cursor blocks are byte-identical (both test-asserted on the generated hooks). opencode's differs only where the runtime forces it — ES module rather than CJS, tool vocabulary `write`/`edit`/`patch` rather than `Edit`/`Write`/`MultiEdit`. Codex's differs only in its payload — every edit arrives as `apply_patch` with a V4A envelope and no file path, so its block carries the envelope parser. Every advisory string, gate-config pattern and docs-path rule is identical across all four.
314
+ ### ReadGuard
315
+
316
+ Advisory repeat-read hook, on all five hosts. A read of a line range the same agent already read in this conversation, file unchanged since (same mtime + size), gets a note: use the earlier output; re-read only if it left context (summarised, or read by another agent). Tracks read-tool calls (`offset` / `limit`, `StartLine` / `EndLine`; no limit → first 2000 lines, opencode → whole file) and plain shell reads — `cat FILE`, `sed -n 'A,Bp' FILE`, `head` / `tail` with a line count; pipes, lists, redirects, substitutions, globs and other programs are not tracked. Ranges merge per file; a changed file starts a fresh log. **fail-open**, never blocks, log in OS temp (`bkit-readguard/`), 24h TTL. `BKIT_READGUARD=off` → disabled.
317
+
318
+ <!-- prettier-ignore -->
319
+ | Host | File | Registration | Delivery | Log key | Reset on summary |
320
+ | --- | --- | --- | --- | --- | --- |
321
+ | Claude Code | `.claude/hooks/bkit-readguard.cjs` | `.claude/settings.json` → `PreToolUse` (`Read\|Bash`) + `PreCompact` | `additionalContext`, before the read | `session_id` + `agent_id` | `PreCompact` |
322
+ | Cursor | `.cursor/hooks/bkit-readguard.cjs` | `.cursor/hooks.json` → `preToolUse` (`Read\|Shell`) + `preCompact`, no `failClosed` | `additional_context` on an allow, before the read | `conversation_id` | `preCompact` |
323
+ | Codex | `.codex/hooks/bkit-readguard.cjs` | `.codex/hooks.json` → `PreToolUse` (`Bash`) + `PreCompact` | `additionalContext`, before the read | `session_id` | `PreCompact` |
324
+ | Antigravity | `.agents/plugins/bkit/hooks/bkit-readguard.cjs` | `.agents/plugins/bkit/hooks.json` → `PreToolUse` (`view_file\|run_command`) | deny once with the note as `reason`, before the read; the identical retry passes | `conversationId` | none — no compaction hook |
325
+ | opencode | `.opencode/plugin/bkit-readguard.js` | `.opencode/opencode.json` → `plugin` array | appended to the tool result in `execute.after`, after the read | `sessionID` | 1.x `session.compacted` event; 2.0 none — no event subscription for plugins |
326
+
327
+ **Gaps:** Codex has no read tool, so shell reads only. Codex, Cursor and Antigravity tool payloads carry no subagent id, and Codex subagents share the parent `session_id`, so a subagent can be told about its parent's read — the note's re-read clause covers it. Antigravity and opencode 2.0 never reset on a summary — same clause. opencode's note arrives with the repeated read, not before it; Antigravity's costs one extra call (the retry). Shared code: `readguard-engine.js` everywhere, `readguard-payload.js` on the four CJS hosts plus `antigravity-hook.js` on Antigravity; the Claude, Cursor and Codex managed blocks are byte-identical (test-asserted in `.bkit/core/engine/audits/hooks/readguard-parity.integration.test.ts`). Ownership as § GateGuard.
292
328
 
293
329
  ---
294
330
 
295
331
  ## Permissions / auto-approve
296
332
 
297
333
  <!-- prettier-ignore -->
298
- | Concern | Claude | Cursor | opencode |
299
- | --- | --- | --- | --- |
300
- | File / secrets | `.claude/settings.json` → `permissions.{allow,deny,ask}` (`Read(./**/*.pem)` deny; `.env` variants ask; `.env.example` allow) | `.cursor/hooks/bkit-guardrails.cjs` via `preToolUse` (`Read\|TabRead`) — same deny/ask policy | `.opencode/opencode.json` → `permission.read` map |
301
- | Shell / destructive | `permissions.deny` / `ask` on force-push (not `--force-with-lease`), `rm -rf /*`, publish, destructive git/gh, etc. Shell `curl` / `wget` are not gated here — `permissions` cannot match a URL host, so only the `WebFetch` TOOL is allowlisted | `.cursor/hooks/bkit-guardrails.cjs` via `beforeShellExecution` — same deny/ask policy | `permission.bash` deny/ask map (same rules) |
302
- | Network fetch | `WebSearch` + tooling `WebFetch(domain:…)`; install/upgrade enriches from the shipped egress registry union consumer `allowed-domains` in `.agents/context.md` (stack hosts never shipped), recording what it wrote so it can later prune it | `curl`/`wget` ask unless host ∈ `.cursor/allowlist.json` (tooling ∪ consumer domains) | `websearch` allow; `webfetch` URL map (`"*": ask` → `*{domain}*: allow`) for the fetch tool **and** `curl *`/`wget *` ask → `curl *{domain}*`/`wget *{domain}*` allow for shell, from the same allowlist (baked into `opencode.json`) |
303
- | Granularity | Per-tool glob | Hook script (project-scoped, failClosed) | Per-path / per-command glob in `permission` |
304
- | Modes | `defaultMode: default \| acceptEdits \| plan \| bypassPermissions` | Implicit per-mode (Composer / Agent / Background) | `opencode --auto` + permission defaults |
305
- | MCP server config | `.mcp.json` at repo root (`mcpServers.<name>.url`) | `.cursor/mcp.json` (same `mcpServers.<name>.url` shape) | `.opencode/opencode.json` → `mcp` |
306
- | MCP tool approval | `permissions.allow` `mcp__<s>__*` from consumer `mcp-servers` (§ MCP servers) | Generated `.cursor/cli.json` `Mcp(<s>:*)` | `permission` `"<s>_*": "allow"` |
307
- | Local-only (not shipped) | `.claude/settings.local.json` (`additionalDirectories`, extra allows) | Cursor project/user settings / MCP as needed | `~/.config/opencode/opencode.json` → `permission.external_directory` |
334
+ | Concern | Claude | Cursor | opencode | Codex | Antigravity |
335
+ | --- | --- | --- | --- | --- | --- |
336
+ | File / secrets | `.claude/settings.json` → `permissions.{allow,deny,ask}` (`Read(./**/*.pem)` deny; `.env` variants ask; `.env.example` allow) | `.cursor/hooks/bkit-guardrails.cjs` via `preToolUse` (`Read\|TabRead`) — same deny/ask policy | `.opencode/opencode.json` → `permission.read` map | **none** — no file-read tool (reads run through `Bash`); `bkit-guardrails.cjs` gates shell tiers only, so `cat .env` passes. Deferral `codex-read-tier-gates-not-wired-file-read-tool-name-unverified` | `.agents/plugins/bkit/hooks/bkit-guardrails.cjs` via `PreToolUse` (`view_file`, path `AbsolutePath`) — same deny/ask policy; ask = Antigravity's own `ask`. Shell reads (`cat .env`) ungated |
337
+ | Shell / destructive | `permissions.deny` / `ask` on force-push (not `--force-with-lease`), `rm -rf /*`, publish, destructive git/gh, etc. Shell `curl` / `wget` are not gated here — `permissions` cannot match a URL host, so only the `WebFetch` TOOL is allowlisted | `.cursor/hooks/bkit-guardrails.cjs` via `beforeShellExecution` — same deny/ask policy | `permission.bash` deny/ask map (same rules) | `.codex/hooks/bkit-guardrails.cjs` via `PreToolUse` (`Bash`) — deny blocks; ask emitted as advisory `additionalContext`, command runs (Codex cannot prompt) | same hook via `PreToolUse` (`run_command`) — deny blocks every time; ask = Antigravity's own `ask` |
338
+ | Network fetch | `WebSearch` + tooling `WebFetch(domain:…)`; install/upgrade enriches from the shipped egress registry union consumer `allowed-domains` in `.agents/context.md` (stack hosts never shipped), recording what it wrote so it can later prune it | `curl`/`wget` ask unless host ∈ `.cursor/allowlist.json` (tooling ∪ consumer domains) | `websearch` allow; `webfetch` URL map (`"*": ask` → `*{domain}*: allow`) for the fetch tool **and** `curl *`/`wget *` ask → `curl *{domain}*`/`wget *{domain}*` allow for shell, from the same allowlist (baked into `opencode.json`) | `curl`/`wget` off `.cursor/allowlist.json` → advisory `additionalContext`, command runs | `curl`/`wget` off `.cursor/allowlist.json` → denied once with the advisory, retry passes; `read_url` / `search_web` ungated |
339
+ | Granularity | Per-tool glob | Hook script (project-scoped, failClosed) | Per-path / per-command glob in `permission` | Hook script (project-scoped, fail-open; fires only once `.codex/` is trusted) | Hook script (workspace plugin, fail-open) |
340
+ | Modes | `defaultMode: default \| acceptEdits \| plan \| bypassPermissions` | Implicit per-mode (Composer / Agent / Background) | `opencode --auto` + permission defaults | host defaults — bkit writes no `.codex/config.toml` | host defaults — bkit ships none |
341
+ | MCP server config | `.mcp.json` at repo root (`mcpServers.<name>.url`) | `.cursor/mcp.json` (same `mcpServers.<name>.url` shape) | `.opencode/opencode.json` → `mcp` | none written | none written |
342
+ | MCP tool approval | `permissions.allow` `mcp__<s>__*` from consumer `mcp-servers` (§ MCP servers) | Generated `.cursor/cli.json` `Mcp(<s>:*)` | `permission` `"<s>_*": "allow"` | none — no project-level MCP approval file | none written |
343
+ | Local-only (not shipped) | `.claude/settings.local.json` (`additionalDirectories`, extra allows) | Cursor project/user settings / MCP as needed | `~/.config/opencode/opencode.json` → `permission.external_directory` | `~/.codex/config.toml` | user-level settings |
308
344
 
309
- **Install behaviour:** template drops, host-specific encoding of the **same** shared policy. No single canonical JSON — three native forms kept in lockstep. Machine-local paths stay out of templates.
345
+ **Install behaviour:** template drops, host-specific encoding of the **same** shared policy. No single canonical JSON — each host's native form kept in lockstep; asserted in `.bkit/core/engine/install/modules/index.integration.test.ts` § permissions-parity. Machine-local paths stay out of templates.
310
346
 
311
- ### Network allowlist — one source, four hosts
347
+ ### Network allowlist — one source, five hosts
312
348
 
313
349
  **Source of truth:** bkit's own hosts come from the egress registry (`.bkit/core/engine/shared/egress.ts`) and must never be re-declared. Stack domains come from consumer `.agents/context.md` → `<!-- allowed-domains:start -->` **after** `<!-- bkit:end -->` (apex domains). Never ship Vercel/Supabase/Sentry/etc. into every consumer.
314
350
 
@@ -318,9 +354,10 @@ Advisory hook, on all four hosts (Claude Code, Cursor, Codex, opencode). Claude
318
354
  | Host | Where the allowlist lives | Why that shape |
319
355
  | --- | --- | --- |
320
356
  | **Claude** | `.claude/settings.json` `WebFetch(domain:…)` allow rules; shell fetches host-checked by `.claude/hooks/bkit-guardrails.cjs` (advisory) | Claude has a first-class settings permission model. No separate allowlist file. Shell `curl` is not domain-gated at all — Claude rules match a command prefix, not a URL host, so `curl` runs under `Bash(*)` with `deny` + the auto-mode classifier as backstops. Prefer `WebFetch` for allowlisted hosts; context-fetch uses `curl` / CLI under `Bash(*)`. |
321
- | **OpenCode** | Baked into `.opencode/opencode.json`: `permission.webfetch` URL map (`"*": "ask"` then `*{domain}*: allow`) for the fetch tool, and `permission.bash` `curl *`/`wget *` **ask** then `curl *{domain}*`/`wget *{domain}*` **allow** for shell fetch (last-match-wins on both) | Both fetch surfaces are domain-gated, so an allowlisted host does not prompt whichever path the agent takes. `webfetch` matches the resource against the requested URL, `bash` against the command string. No separate allowlist file. |
357
+ | **OpenCode** | Baked into `.opencode/opencode.json`: `permission.webfetch` URL map (`"*": "ask"` then `*{domain}*: allow`) for the fetch tool, and `permission.bash` `curl *`/`wget *` **ask** then `curl *{domain}*`/`wget *{domain}*` **allow** for shell fetch (last-match-wins on both) | Both fetch surfaces are domain-gated, so an allowlisted host does not prompt whichever path the agent takes. `webfetch` matches the resource against the requested URL, `bash` against the command string. **Looser than Claude's `domain:`:** OpenCode globs match the whole string (`*` → `.*`, crossing `/` `?` `@`), so `*{domain}*` allows the domain anywhere in the URL or command — apex and every subdomain, but also `https://evil.tld/?x={domain}`. Accepted risk: no OpenCode glob covers subdomains without it. No separate allowlist file. |
322
358
  | **Cursor** | Generated `.cursor/allowlist.json` read at **runtime** by `.cursor/hooks/bkit-guardrails.cjs` | Cursor has no project settings equivalent to Claude `permissions` / OpenCode `permission` for curl host globs. Parity is a **hook** (`beforeShellExecution`): ask on `curl`/`wget` unless the command contains a host from the allowlist. The JSON is Cursor-only by design (IDE-scoped artifact under `.cursor/`, not `.bkit/`). |
323
359
  | **Codex** | Reads the same `.cursor/allowlist.json` at runtime via `.codex/hooks/bkit-guardrails.cjs` | Codex has no project-level permission file. The hook host-parses `curl`/`wget` and emits an advisory `ask` — Codex cannot prompt, so the allowlist informs rather than enforces. |
360
+ | **Antigravity** | Reads the same `.cursor/allowlist.json` at runtime via `.agents/plugins/bkit/hooks/bkit-guardrails.cjs` | Antigravity has no project-level permission file. The hook host-parses `curl`/`wget` on the `run_command` matcher and denies a non-allowlisted fetch once with the advisory as the reason; the retry passes. |
324
361
 
325
362
  **Do not hand-edit** `.cursor/allowlist.json` — regenerate via install/upgrade after changing `allowed-domains`. Missing file ⇒ the hook resolves no hosts and every host reads as unknown; there is deliberately no list embedded in the hook, because a second copy drifts from the registry silently.
326
363
 
@@ -351,12 +388,57 @@ Both hosts: same `mcpServers` shape; files differ:
351
388
 
352
389
  Both: `"type": "http"`, `"url": "https://api.githubcopilot.com/mcp/"`, `"headers": { "Authorization": "Bearer ${BKIT_GH_TOKEN}" }`. `${BKIT_GH_TOKEN}` at session start — must be in shell (local) or dashboard env (cloud). See `.bkit/cloud.md` § MCP issue-tracker integration for full JSON.
353
390
 
354
- **bkit owns one entry per file.** In `.mcp.json` / `.cursor/mcp.json` bkit owns only `mcpServers.<tracker>`: an absent file gets the tracker-filtered render; in an existing file install and upgrade reset that one entry to the template and keep every other key, in its order (malformed JSON stops the install). `bkit check` reports a pending reset. Tracker `none` owns no entry. A tracker switch (e.g. `--tracker=linear` → `--tracker=github`) adds the new entry and leaves the old one. Uninstall removes bkit's entry while it still equals the template. Advisories: `mcp-missing-server-<name>` (file lacks needed server), `mcp-extra-server-<name>` (bkit-managed server the configured tracker does not use). Consumer-added MCP servers never flagged.
391
+ **bkit owns one entry per file.** In `.mcp.json` / `.cursor/mcp.json` bkit owns only `mcpServers.<tracker>`: an absent file gets the tracker-filtered render; in an existing file install and upgrade reset that one entry to the template and keep every other key, in its order (malformed JSON stops the install). `bkit check` reports a pending reset. Tracker `none` owns no entry. A tracker switch (e.g. `--tracker=linear` → `--tracker=github`) adds the new entry and leaves the old one. Uninstall removes bkit's entry while it still equals the template. Advisories: `mcp-missing-server-<name>` (file lacks the configured tracker's server; `none` needs none), `mcp-extra-server-<name>` (`linear` entry while the configured tracker is not `linear`; also checked in `.opencode/opencode.json` `mcp`). `github` never flagged as extra: every phase workflow's gh MCP fallback (PR / CI / merge when `gh` is unavailable) calls it — under `linear` / `none`, add it by hand to keep that fallback. Consumer-added MCP servers never flagged.
355
392
 
356
393
  > Note: `mcpServers` in `.claude/settings.json` silently ignored for server defs — only `.mcp.json` (project) or `claude mcp add` (user) take effect. Tool-permission `allow` (`mcp__github__*`) remain in settings.
357
394
 
358
395
  ---
359
396
 
397
+ ## Context compaction
398
+
399
+ bkit ships no compaction setting; each host auto-summarises near the model's full window by default. To summarise earlier (e.g. 300,000 tokens), set it per host below. Effective threshold = min(setting, model window).
400
+
401
+ <!-- prettier-ignore -->
402
+ | Host | Setting | Subagents | Notes |
403
+ | --- | --- | --- | --- |
404
+ | Claude Code | `.claude/settings.json` → `"autoCompactWindow": 300000` (range 100,000–1,000,000 or `"auto"`) — install / upgrade keep keys bkit does not own | inherit it; agent files also accept `autoCompactWindow` frontmatter | per person: `.claude/settings.local.json`; env `CLAUDE_CODE_AUTO_COMPACT_WINDOW` beats every settings file |
405
+ | Codex CLI | `.codex/config.toml` → `model_auto_compact_token_limit = 300000`, above the first `[table]` header (below one, the key belongs to that table and does nothing) | inherit it (agent role files drop the key) | read only once the project is trusted; one run: `codex -c model_auto_compact_token_limit=N`; above 90% of the model window, Codex uses 90% |
406
+ | opencode | none — no absolute-count trigger. Auto-compaction fires at the model's input (else context) limit minus `compaction.buffer` (default 10%, min 16,000) | same settings | per model: `providers.<id>.models.<model>.limit.input` (or `limit.context` when the catalog gives no input limit) ≈ target + buffer. Not `compaction.buffer`: one global buffer large enough for a 1M model goes negative on 128k–200k models and compacts before nearly every call |
407
+ | Cursor | none — trigger fixed server-side | — | manual `/summarize` |
408
+ | Google Antigravity | none — threshold internal, no setting / env reaches it | — | manual `/compact` |
409
+
410
+ **Floor:** keep the window well above the largest single tool result plus the recent turns kept after a summary. Claude Code ends an agent whose context refills to the limit within 3 turns of a summary, 3 times in a row (`Autocompact is thrashing`).
411
+
412
+ ## MCP project scope
413
+
414
+ A remote MCP server that can see a whole account makes agents look up account and project IDs before every task. Lock its URL to one project and those lookup tools disappear; calls default to that project. Lock it in every host file that declares the server (`.mcp.json`, `.cursor/mcp.json`, `.opencode/opencode.json`, `.codex/config.toml`).
415
+
416
+ <!-- prettier-ignore -->
417
+ | Service | Locked URL | Effect |
418
+ | --- | --- | --- |
419
+ | Sentry | `https://mcp.sentry.dev/mcp/<org>/<project>` | `find_organizations` / `find_projects` hidden |
420
+ | Supabase | `https://mcp.supabase.com/mcp?project_ref=<ref>&read_only=true` | `list_projects` hidden; `read_only` runs SQL as a read-only database user |
421
+ | Vercel | `https://mcp.vercel.com/<team>/<project>` | calls default to that team and project |
422
+
423
+ Only servers in the repo's own files lock this way; claude.ai connectors cannot be locked per repo (§ claude.ai connectors). The `mcp-scope` setup tip fires on an unlocked URL for a service in this table.
424
+
425
+ ## claude.ai connectors
426
+
427
+ Claude Code loads every connector on the person's claude.ai account in every repo, and re-sends their tool names on every request whether used or not. `"disableClaudeAiConnectors": true` in `.claude/settings.json` stops that for the repo.
428
+
429
+ <!-- prettier-ignore -->
430
+ | Aspect | Detail |
431
+ | --- | --- |
432
+ | Stops | claude.ai connectors in Claude Code sessions for this repo — terminal and desktop app |
433
+ | Keeps | the repo's `.mcp.json` servers (bkit's tracker server included), `claude mcp add` servers, and the connectors themselves in claude.ai / desktop-app chats and cloud routines |
434
+ | Before | move anything agents reach through a connector onto `.mcp.json` (§ MCP project scope), a context-fetch block or the provider CLI |
435
+ | Per person | `false` in `.claude/settings.local.json` turns connectors back on |
436
+ | Verify | `/context` before and after |
437
+
438
+ bkit ships no default: the setting also hides each person's own connectors (mail, drive, …), and install / upgrade keep keys bkit does not own, so a shipped `true` could not be turned off in `.claude/settings.json`. The `claude-connectors` setup tip fires on a Claude Code repo that sets neither value.
439
+
440
+ ---
441
+
360
442
  ## Runtime environment (cloud agents)
361
443
 
362
444
  > Setup recipe + alignment: `.bkit/cloud.md`. This section = host-diff matrix only.
@@ -405,7 +487,7 @@ Installed provider catalog changes. Look up model IDs before pinning in `.openco
405
487
 
406
488
  **opencode-zen / opencode-go — two OpenCode built-in providers.** Both emit minimal `provider.<id>` with only `options.apiKey: "{env:BKIT_OPENCODE_API_KEY}"` (no npm driver, no baseURL). OpenCode resolves from models.dev — Go Qwen/MiniMax use Anthropic `/messages`, not openai-compatible `/chat/completions`. Zen keyed `opencode`; Go `opencode-go`. `bkit install --opencode=opencode-zen` (or `=opencode-go`) → `bkit.opencodeProvider` in `package.json`; legacy `opencode` → `opencode-zen` via `OPENCODE_PROVIDER_ALIASES`. Reinstall **replaces** seeded block (heals hijacked npm/baseURL). Set `BKIT_OPENCODE_API_KEY` in `.bkit/.env` (<https://opencode.ai/auth>). Columns from **models.dev**.
407
489
 
408
- **All four providers ship curated columns.** Tier design — **per-tier quality target, cheapest sufficient pin**. A tier cell is not "the same rung of this provider's ladder": it is the cheapest model that **reaches that tier's Claude score**, and reaching means _approaching_ — it does not have to beat it. Targets are the LiveBench Agentic Coding scores on the board below (opus `claude-opus-5` **65.2**, sonnet `claude-sonnet-5` **59.4**, haiku `claude-haiku-5-5` **~51**). The opus and sonnet targets stay the 5.0 scores although the 5.5 pins are on the CSV: `claude-opus-5-5` lands level at `xhigh` (65.4), and the `claude-sonnet-5-5` rows don't read cleanly (see the board). The haiku target is Haiku 5.5 at `xhigh`, the closest measured rung to the `high` effort the summary writers run at. Where a provider's ceiling sits under the sonnet target, opus+sonnet **collapse onto that ceiling** — spreading them across two rungs buys nothing and costs quality on the sonnet half. Where a cheap model already clears the haiku target, the haiku cell **stays cheap** — a $5/task flagship serving a read-and-emit summariser is waste, not safety.
490
+ **All four opencode providers ship curated columns.** Tier design — **per-tier quality target, cheapest sufficient pin**. A tier cell is not "the same rung of this provider's ladder": it is the cheapest model that **reaches that tier's Claude score**, and reaching means _approaching_ — it does not have to beat it. Targets are the LiveBench Agentic Coding scores on the board below (opus `claude-opus-5` **65.2**, sonnet `claude-sonnet-5` **59.4**, haiku `claude-haiku-5-5` **~51**). The opus and sonnet targets stay the 5.0 scores although the 5.5 pins are on the CSV: `claude-opus-5-5` lands level at `xhigh` (65.4), and the `claude-sonnet-5-5` rows don't read cleanly (see the board). The haiku target is Haiku 5.5 at `xhigh`, the closest measured rung to the `high` effort the summary writers run at. Where a provider's ceiling sits under the sonnet target, opus+sonnet **collapse onto that ceiling** — spreading them across two rungs buys nothing and costs quality on the sonnet half. Where a cheap model already clears the haiku target, the haiku cell **stays cheap** — a $5/task flagship serving a read-and-emit summariser is waste, not safety.
409
491
 
410
492
  ### Selecting pins
411
493
 
@@ -12,6 +12,30 @@
12
12
  > - `bkit install` and `bkit upgrade` never write these files and never overwrite a copy.
13
13
  > - Adapt app roots, workspace package scope, rules JSON. Examples use `apps/web`, `apps/mobile`, `packages/api`, `@scope`.
14
14
 
15
+ ## What each template is for
16
+
17
+ Adoption order = `bkit tips` order. Sections below: install steps and traps.
18
+
19
+ <!-- prettier-ignore -->
20
+ | Template | What it's for | Skip it and |
21
+ | --- | --- | --- |
22
+ | direnv | Loads `.bkit/.env` tokens whenever the project opens. | Saved tokens never load; every sign-in fails while the file looks right. |
23
+ | Serena | Agents look code up like an editor ("where is this defined, what uses it?"). Read-only. | Agents grep and read whole files: more accidental changes, more correction rounds, higher token cost. |
24
+ | CI workflow + CI scripts | Runs every check on GitHub on every change; one capstone check gates merge; `/bkit-ship` waits for it. | "Shipped" means merged, not checked. |
25
+ | Git hooks (Husky) | Same checks locally on commit and push, in seconds. | Failures surface minutes later in CI, after the agent moved on. |
26
+ | Prettier ignore list | One formatting baseline; stops Prettier reformatting bkit's managed files. | Reviews fill with spacing noise; every bkit upgrade shows false changes. |
27
+ | slop-scan | Flags net-new junk code AI tends to write (filler, dead code, type escapes). | Junk passes skim review and piles up. |
28
+ | Vale | Prose lint for docs and agent instructions. | Padded, vague docs every agent re-reads on every run. |
29
+ | lint-staged | Formats only the staged files inside the commit hook. | Commit hook does nothing, or is slow enough to get skipped. |
30
+ | Cloud-agent workflow + SessionStart hook | CI result starts a cloud agent: ship on green, debug on red; hook installs the cloud toolchain. | Every next step needs a local session. |
31
+ | Context-fetch blocks | `/bkit-debug` reads real CI logs, runtime errors and web results. | Debug guesses from code; real errors stay hidden. |
32
+ | Secrets sync | One local file → every secret store; proves copies match without printing values. | Hand-copied secrets drift: "works for me, broken in production". |
33
+ | graphify | Code map (`docs/capabilities.md`) agents check before building something again. | Agents rediscover structure each run; ripple effects missed. |
34
+ | Dependabot / Renovate | Small grouped update PRs; pinned Actions; security fixes skip the queue. | Updates pile into one large risky upgrade. |
35
+ | Prettier tables | One edited cell = one changed row in the diff. | A one-word table edit diffs as the whole table. |
36
+ | Cursor editor + cloud agent | Format-on-save, recommended extensions, Cursor cloud-agent image. | Cursor edits miss project formatting; no Cursor cloud agent. |
37
+ | Launchd GUI env | macOS apps opened from the Dock get the same tokens as the terminal. | Dock-launched editors start signed out. |
38
+
15
39
  ## Contract
16
40
 
17
41
  <!-- prettier-ignore -->
@@ -37,7 +61,6 @@
37
61
  | Prettier tables | `.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs` | `scripts/prettier/` | that file |
38
62
  | Context-fetch blocks | `.bkit/templates/context/bkit-<provider>.md` | below `<!-- bkit:end -->` in `.agents/context.md` | the blocks you use |
39
63
  | Cloud SessionStart hook | `.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh` | `.claude/hooks/bkit-cloud-bootstrap.sh` | that file |
40
- | Licence | `.bkit/templates/LICENSE.md` | — | read it; the copies in `.bkit/templates/` are MIT-0 |
41
64
 
42
65
  Placeholders. Copies keep them raw; replace each in your copy:
43
66
 
@@ -47,7 +70,7 @@ Placeholders. Copies keep them raw; replace each in your copy:
47
70
  | `{{DEFAULT_BRANCH}}` | `bkit-ci.yml` (`on.push` / `on.pull_request` branches; stub comments) | your default branch | `origin/HEAD`, else `main` |
48
71
  | `{{NODE_VERSION}}` | `bkit-ci.yml` (`actions/setup-node` `node-version`, both lanes) | your Node major, or swap the line for `node-version-file: .nvmrc` | `.nvmrc`, then `engines.node`, then `22` |
49
72
  | `{{CLOUD_RUNNER}}` | `bkit-cloud.yml` (`runs-on`, all three jobs) | a runner label | `ubuntu-latest` |
50
- | `{{SCRIPT_PATH}}` | `ai.bkit.launchd.plist` (`ProgramArguments`) | absolute path to the loader script, outside a TCC-protected folder (see § Launchd GUI environment) | `/path/to/repo/scripts/launchd/bkit-launchd-env.sh` |
73
+ | `{{SCRIPT_PATH}}` | `ai.bkit.launchd.plist` (`ProgramArguments`) | absolute path to the loader script, outside a TCC-protected folder (see § Launchd GUI environment) | `/Users/<you>/.config/bkit/bkit-launchd-env.sh` |
51
74
  | `{{ENV_FILE}}` | `ai.bkit.launchd.plist` (`ProgramArguments`, `WatchPaths`) | absolute path to your env file | `/Users/<you>/.config/bkit/launchd.env` |
52
75
 
53
76
  - `bkit install` / `bkit upgrade` refresh `.bkit/templates/` to the package's templates, unsubstituted. `bkit check` fails on a stale copy. `bkit uninstall` removes the folder, never an adopted copy.
@@ -64,18 +87,18 @@ Placeholders. Copies keep them raw; replace each in your copy:
64
87
  <!-- prettier-ignore -->
65
88
  | File | Fits | `context=` | Fetches | Secret / non-secret env | Domains | CLI (provision) |
66
89
  | --- | --- | --- | --- | --- | --- | --- |
67
- | `github.md` | GitHub Actions | `ci`, `diff` | `ci`: failing run: failed jobs / steps, `::error` annotations, failed-step logs; `diff`: `git diff --stat` since the last green CI run on trunk | `GH_TOKEN` / `BASELINE_BRANCH`, `BASELINE_WORKFLOW` (`diff`) | — | `gh` (base tool) |
68
- | `playwright.md` | Playwright on GitHub Actions | `e2e` | failing run's report artifact, failing specs first | `GH_TOKEN` / `E2E_ARTIFACT`, `E2E_JOB_RE` | — | `gh` (base tool) |
69
- | `maestro.md` | Maestro iOS and Android lanes on GitHub Actions | `e2e` | every failed Maestro job's full log, sliced to the result steps | `GH_TOKEN` / `MAESTRO_JOB_RE`, `MAESTRO_STEPS` | — | `gh` (base tool) |
90
+ | `github.md` | GitHub Actions | `ci`, `diff` | `ci`: failing run: failed jobs / steps, `::error` annotations, failed-step logs tail-bounded per failed job; `diff`: `git diff --stat` (capped) since the last green CI run on trunk | `GH_TOKEN` / `CI_LOG_TAIL`; `BASELINE_BRANCH`, `BASELINE_WORKFLOW`, `DIFF_STAT_N` (`diff`) | — | `gh` (base tool) |
91
+ | `playwright.md` | Playwright on GitHub Actions | `e2e` | failing run's report artifact, failing specs first; inlined files, lines and binary paths capped | `GH_TOKEN` / `E2E_ARTIFACT`, `E2E_JOB_RE`, `E2E_MAX_FILES`, `E2E_MAX_LINES`, `E2E_MAX_BIN` | — | `gh` (base tool) |
92
+ | `maestro.md` | Maestro iOS and Android lanes on GitHub Actions | `e2e` | every failed Maestro job's log, sliced to the result steps, each slice tail-bounded | `GH_TOKEN` / `MAESTRO_JOB_RE`, `MAESTRO_STEPS`, `MAESTRO_LOG_TAIL` | — | `gh` (base tool) |
70
93
  | `tavily.md` | any | `web` | web search for upstream causes (untrusted output) | `BKIT_TAVILY_API_KEY` / `QUERY` | — | — |
71
- | `sentry.md` | Sentry | `runtime` | unresolved issues, last 24 h; trace / window recipes | `SENTRY_AUTH_TOKEN` / `SENTRY_ORG`, `SENTRY_PROJECT`, `SENTRY_HOST` | `sentry.io` | — |
94
+ | `sentry.md` | Sentry | `runtime` | unresolved issues seen in a window (organization issues endpoint), optional environment; trace / window recipes | `SENTRY_AUTH_TOKEN` / `SENTRY_ORG`, `SENTRY_PROJECT`, `SENTRY_HOST`, `SENTRY_SINCE`, `SENTRY_ENV`, `SENTRY_N` | `sentry.io` | — |
72
95
  | `vercel.md` | Vercel | `runtime` | serverless + edge error / fatal logs in a window | `VERCEL_TOKEN` / `VERCEL_SCOPE`, `VERCEL_ENV` | `vercel.com` | `vercel` (yes) |
73
96
  | `supabase.md` | hosted Supabase | `runtime` | Postgres `ERROR` / `FATAL` / `PANIC` lines | `SUPABASE_ACCESS_TOKEN` / `SUPABASE_PROJECT_ID` | `supabase.com` | — |
74
- | `stripe.md` | Stripe | `runtime` | failure / dispute / refund events | `STRIPE_SECRET_KEY` / — | `stripe.com` | — |
97
+ | `stripe.md` | Stripe | `runtime` | failure / dispute / refund events, filtered by type and window at the source | `STRIPE_SECRET_KEY` / `STRIPE_N`, `STRIPE_SINCE_S` | `stripe.com` | — |
75
98
  | `resend.md` | Resend | `runtime` | bounced / complained / failed / delayed sends | `RESEND_API_KEY` / — | `resend.com` | — |
76
- | `inngest.md` | Inngest Cloud | `runtime` | `inngest/function.failed` events | `INNGEST_SIGNING_KEY` / — | `inngest.com` | — |
99
+ | `inngest.md` | Inngest Cloud | `runtime` | `inngest/function.failed` events in a window | `INNGEST_SIGNING_KEY` / `INNGEST_N`, `SINCE_ISO`, `INNGEST_ENV` | `inngest.com` | — |
77
100
  | `cloudrun.md` | Google Cloud Run | `runtime` | container errors + memory-limit kills | `GCP_CLIENT_EMAIL`, `GCP_PRIVATE_KEY` (headless) / `GCP_PROJECT_ID`, `GCP_SERVICE` | `googleapis.com`, `google.com` | `gcloud` (yes) |
78
- | `expo.md` | Expo EAS Build + EAS Workflows (Maestro) | `runtime`, `e2e` | `runtime`: build status + errored-build log lines; `e2e`: per-flow exceptions, JUnit, screenshots, Maestro commands, hierarchy dumps, XCUITest + JS console | `EXPO_TOKEN` / `EXPO_APP_DIR` | `expo.dev`, `googleapis.com` (`runtime`), `eascdn.net` (`e2e`) | `eas` (yes) |
101
+ | `expo.md` | Expo EAS Build + EAS Workflows (Maestro) | `runtime`, `e2e` | `runtime`: build status + errored-build log lines (capped per build); `e2e`: failed jobs' per-flow exceptions, JUnit (capped), screenshots, Maestro commands, hierarchy dumps, XCUITest + JS console | `EXPO_TOKEN` / `EXPO_APP_DIR`, `EAS_PLATFORM`, `EAS_PROFILE`, `EAS_LOG_N` (`runtime`); `EAS_WF_FILE`, `EAS_JUNIT_N` (`e2e`) | `expo.dev`, `googleapis.com` (`runtime`), `eascdn.net` (`e2e`) | `eas` (yes) |
79
102
  | `serena.md` | Serena MCP server | — | nothing: provision only, installs `serena` in cloud | — | — | `uv` (yes) |
80
103
 
81
104
  MCP names listed: `sentry` / `Sentry`, `vercel` / `Vercel`, `supabase` / `Supabase`, `inngest`, `serena`. Every tool on a listed server runs without a prompt, writes included — list only servers you trust with that.
@@ -140,6 +163,7 @@ pnpm add -D prettier@^3.5.3 slop-scan@^0.3.0 lint-staged@^17.0.0 husky@^9.1.7
140
163
  - `slop:delta` runs `bkit ci slop` (bkit devDep on `PATH` through the package script). CI passes the base sha as its one bare argument.
141
164
  - `lint:prose` runs `bkit ci prose`: Vale over every `*.md` outside `node_modules/`. Narrow it with repeatable `--glob=<pattern>` (`*`, `**`, `?`, relative to the repo root), e.g. `bkit ci prose --glob='docs/*.md' --glob='.agents/*.md'`.
142
165
  - Non-Node stack → point each gate at your own commands; keep the gate names.
166
+ - `bkit:test:file` (not seeded; `test-file-script-missing` until declared) runs ONE test file — bkit appends its repo-relative path — and writes a JUnit report to `$BKIT_TEST_REPORT`; `/bkit-build` reads it for test-first. Vitest: `"bkit:test:file": "vitest run --reporter=default --reporter=junit --outputFile.junit=\"$BKIT_TEST_REPORT\""`. Call the runner directly, not through a caching task runner.
143
167
 
144
168
  ## CI workflow — `bkit-ci.yml`
145
169
 
@@ -260,12 +284,15 @@ launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.bkit.launchd.plist
260
284
  launchctl getenv BKIT_OPENROUTER_API_KEY # bootstrap proof
261
285
  ```
262
286
 
263
- - `WatchPaths` re-runs the loader on every env-file write → rotate a token by editing the file, no re-bootstrap.
287
+ - `WatchPaths` re-runs the loader on every env-file write → rotate a token by editing the value, revoke it by deleting the line or emptying the value (`KEY=""`); no re-bootstrap.
288
+ - Loader loads `BKIT_*` keys only (others logged as skipped). An empty value runs `launchctl unsetenv`. Loaded key names are recorded in `.launchd-loaded-keys` next to the env file (mode 600; `BKIT_LAUNCHD_STATE` overrides the path); a recorded key missing from the env file is unset on the next run.
289
+ - One failing key is logged and skipped; the rest still load and the loader exits 1. A failed unset stays recorded and retries on the next run.
264
290
  - Log `~/Library/Logs/bkit-launchd.log` records key names only, never values. `BKIT_LAUNCHD_LOG` and `BKIT_LAUNCHD_ENV` override the log and env-file defaults.
265
291
  - Loader self-skips (log line + `exit 0`) when the env file is absent or `launchctl` is off `PATH` (Linux CI).
266
292
  - launchd cannot exec a loader under `~/Documents`, `~/Desktop` or `~/Downloads`: macOS TCC denies it and `/tmp/bkit-launchd.log` reads `Operation not permitted`. Repo under one of those → keep the adopted copy in git but place the loader launchd runs at `~/.config/bkit/bkit-launchd-env.sh` (or another unprotected path) and point `{{SCRIPT_PATH}}` there.
267
293
  - Env-file rules: blank lines and `#` comments ignored; optional `export ` prefix; key must match `[A-Za-z0-9_]`; matching surrounding quotes stripped from the value.
268
- - `launchctl setenv` reaches apps launched after the load; a running app keeps its environment until relaunch.
294
+ - `launchctl setenv` reaches apps launched after the load; a running app keeps its environment until relaunch (set and unset alike).
295
+ - **Exposure:** `launchctl setenv` makes every loaded token visible to every app started in the login session, not only the app that needs it. Load only tokens you accept that for; prefer `bkit cursor` / `bkit opencode` (per-process env) where possible.
269
296
  - Remove: `launchctl bootout gui/$UID ~/Library/LaunchAgents/ai.bkit.launchd.plist`.
270
297
 
271
298
  ## Cursor — `settings.json`, `environment.json`, `Dockerfile`
@@ -335,7 +362,7 @@ PyPI name `serena-agent`, CLI `serena`. PyPI `serena` is an unrelated package.
335
362
 
336
363
  ## graphify — map
337
364
 
338
- On-demand only — not an MCP server, installed skill, CI job, or git hook. Agents read `docs/capabilities.md`; audit templates that need the graph build it via `scripts/graphify/bkit-graphify.sh`. Only tracked output: `docs/capabilities.md`. Mermaid views: `docs/graphify-out/reports/graph-packages.mmd`, `graph-modules.mmd`. Reference: https://github.com/Graphify-Labs/graphify.
365
+ On-demand only — not an installed skill or git hook. graphify ships an MCP server (`graphify-mcp`, stdio default); it stays unwired because its answers come from the `graph.json` snapshot and build/debug agents invalidate the graph faster than it rebuilds — Serena (no index to go stale) owns the agent surface. The one CI touch is the self-skipping register-freshness gate below: on pushes it installs a pinned graphify and runs `pnpm graph:check`, forcing `docs/capabilities.md` to be current. Agents read `docs/capabilities.md`; audit templates that need the graph build it via `scripts/graphify/bkit-graphify.sh`. Only tracked output: `docs/capabilities.md`. Mermaid views: `docs/graphify-out/reports/graph-packages.mmd`, `graph-modules.mmd`. Reference: https://github.com/Graphify-Labs/graphify.
339
366
 
340
367
  ```bash
341
368
  uv tool install "graphifyy[sql]"
@@ -371,6 +398,8 @@ graphify-out/
371
398
  ```
372
399
 
373
400
  - Paste `scripts/graphify/bkit-graph-pre-push.sh` at the end of your `.husky/pre-push`, below the bkit lines. Warn-only: does not run graphify, does not block push.
401
+ - `.github/workflows/bkit-ci.yml` ships `Check Capability Register` (push events): installs pinned graphify and runs `pnpm graph:check`, so a stale register fails CI. Self-skips without `scripts/graphify/bkit-graphify.sh`; bump `GRAPHIFY_SPEC` and refresh the register in the same change.
402
+ - graphify's MCP server is opt-in: install `graphifyy[mcp]` (`mcp` + `starlette`; HTTP transport also needs `uvicorn`) and pass the graph path explicitly — `graphify-mcp` defaults to `graphify-out/graph.json`, not the pinned `docs/graphify-out/graph.json`. Snapshot-dated answers suit audit/orientation, never build or debug.
374
403
  - `.graphifyignore` merges `.gitignore`.
375
404
  - Keep `package.json` in corpus — excluding it drops workspace `name` fields graphify resolves package imports with; graph still looks complete.
376
405
  - Keep `tsconfig.json` out; graphify reads `paths` regardless.
@@ -383,7 +412,7 @@ graphify-out/
383
412
  | `pnpm graph:clean` | Same, after deleting `docs/graphify-out/`. Required after any tsconfig `paths` change. `--force` does not invalidate the module-resolution cache. |
384
413
  | `pnpm graph:update` | Re-extract changed files, then recluster. |
385
414
  | `pnpm graph:rollup` | Package and module views, plus `docs/capabilities.md`. |
386
- | `pnpm graph:check` | Rebuild and fail if `docs/capabilities.md` is not what this tree produces. Run from a clean checkout before the dev → main PR. |
415
+ | `pnpm graph:check` | Rebuild and fail if `docs/capabilities.md` is not what this tree produces. Shipped as a self-skipping CI step (push events); enabled in bkit's own CI. |
387
416
  | `pnpm graph:scoped [path]` | One subtree. Default `apps/web/src`. |
388
417
  | `pnpm graph:graphml` | Opt-in GraphML for Gephi / yEd. |
389
418