@cbartens/bkit 5.0.0 → 5.0.1

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 (61) hide show
  1. package/.bkit/README.md +10 -14
  2. package/.bkit/core/.bkit/README.md +9 -13
  3. package/.bkit/core/.bkit/cloud.md +15 -24
  4. package/.bkit/core/.bkit/comparison.md +4 -1
  5. package/.bkit/core/.bkit/install.md +54 -149
  6. package/.bkit/core/.bkit/jsonl.md +5 -5
  7. package/.bkit/core/.bkit/templates.md +2 -3
  8. package/.bkit/core/.bkit/workflows.md +7 -3
  9. package/.bkit/core/engine/checks/after/auth.ts +16 -114
  10. package/.bkit/core/engine/checks/after/ci-yml.ts +36 -74
  11. package/.bkit/core/engine/checks/after/index.ts +156 -182
  12. package/.bkit/core/engine/checks/after/suppression.ts +53 -0
  13. package/.bkit/core/engine/checks/before/env.ts +4 -18
  14. package/.bkit/core/engine/checks/before/files.ts +2 -0
  15. package/.bkit/core/engine/cli.ts +4 -8
  16. package/.bkit/core/engine/commands/install/doctor.ts +9 -2
  17. package/.bkit/core/engine/commands/install/install.ts +24 -2
  18. package/.bkit/core/engine/commands/install/uninstall.ts +23 -0
  19. package/.bkit/core/engine/commands/install/upgrade.ts +14 -3
  20. package/.bkit/core/engine/commands/lib.ts +4 -3
  21. package/.bkit/core/engine/install/cloud-env.ts +0 -1
  22. package/.bkit/core/engine/install/modules/cloud.ts +2 -3
  23. package/.bkit/core/engine/install/modules/core.ts +33 -13
  24. package/.bkit/core/engine/install/payload-links.ts +150 -0
  25. package/.bkit/core/engine/install/template-copies.ts +1 -1
  26. package/.bkit/core/engine/shared/egress.ts +1 -1
  27. package/.bkit/core/workflows/bkit-debug.md +19 -12
  28. package/.bkit/shared/.bkit/.env.example +2 -24
  29. package/.bkit/shared/docs/deployments.md +2 -7
  30. package/.bkit/shared/docs/security.md +1 -1
  31. package/.bkit/shared/gitignore +5 -0
  32. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +0 -5
  33. package/.bkit/templates/.cursor/Dockerfile +1 -1
  34. package/.bkit/templates/.cursor/environment.json +1 -1
  35. package/.bkit/templates/.github/renovate.json5 +0 -15
  36. package/.bkit/templates/.github/workflows/bkit-ci.yml +2 -22
  37. package/.bkit/templates/.github/workflows/bkit-cloud.yml +0 -2
  38. package/.bkit/templates/.github/workflows/bkit-renovate.yml +0 -5
  39. package/CHANGELOG.md +17 -0
  40. package/README.md +5 -6
  41. package/dist/checks/after/auth.js +16 -108
  42. package/dist/checks/after/ci-yml.js +30 -67
  43. package/dist/checks/after/index.js +136 -152
  44. package/dist/checks/after/suppression.js +39 -0
  45. package/dist/checks/before/env.js +4 -14
  46. package/dist/checks/before/files.js +2 -0
  47. package/dist/cli.js +4 -8
  48. package/dist/commands/install/doctor.js +4 -2
  49. package/dist/commands/install/install.js +16 -2
  50. package/dist/commands/install/uninstall.js +24 -0
  51. package/dist/commands/install/upgrade.js +14 -3
  52. package/dist/commands/lib.js +4 -3
  53. package/dist/install/cloud-env.js +0 -1
  54. package/dist/install/modules/cloud.js +2 -3
  55. package/dist/install/modules/core.js +33 -13
  56. package/dist/install/payload-links.js +119 -0
  57. package/dist/install/template-copies.js +1 -1
  58. package/dist/shared/egress.js +1 -1
  59. package/package.json +2 -2
  60. package/.bkit/core/engine/checks/after/vercel.ts +0 -101
  61. package/dist/checks/after/vercel.js +0 -102
package/.bkit/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # bkit — Agent Workflow System
2
2
 
3
- <!-- bkit:managed v5.0.0 — PolyForm Noncommercial 1.0.0 / Small Business 1.0.0 (https://polyformproject.org/licenses/) — do not edit; run `bkit upgrade` to refresh -->
3
+ <!-- bkit:managed v5.0.1 — PolyForm Noncommercial 1.0.0 / Small Business 1.0.0 (https://polyformproject.org/licenses/) — do not edit; run `bkit upgrade` to refresh -->
4
4
 
5
5
  **bkit** wires Claude Code (and Cursor) into five-phase tracker-integrated cycle: `/bkit-design` → `/bkit-plan` → `/bkit-build` → `/bkit-debug` → `/bkit-ship`. Hosts additive: `.claude/` + `.cursor/` always render (direct Anthropic); `bkit install --opencode=<provider>` adds opencode for non-Anthropic backends — four providers: `openrouter`, `ollama`, `opencode-zen` + `opencode-go` (opencode-native gateways; auth via `BKIT_OPENCODE_API_KEY`) — same harness, inference backend only changes (see `.bkit/providers.md` § Hosts + Providers).
6
6
 
@@ -162,25 +162,19 @@ Full Linear ↔ Cursor setup: <https://linear.app/docs/cursor>.
162
162
 
163
163
  `.agents/` = **canonical**. `bkit install` regenerates host outputs (`.claude/**`, `.cursor/**`) and rewrites bkit-managed blocks across consumer repo.
164
164
 
165
- First-time install, `BKIT_GH_TOKEN_INSTALL` / `.npmrc` / GHA / Vercel auth, uninstall: `.bkit/install.md`. Ongoing ops below.
165
+ First-time install and upgrade, uninstall: `.bkit/install.md`. Ongoing ops below.
166
166
 
167
167
  ### Upgrade — paste into your AI
168
168
 
169
- Prefer `bkit upgrade --latest` (bumps package **and** resyncs managed files) — do **not** only `pnpm add`. Replace `<ENV-FILE-PATH>` if token not already loaded (direnv / `.bkit/.env`).
169
+ Prefer `bkit upgrade --latest` (bumps package **and** resyncs managed files) — do **not** only `pnpm add`.
170
170
 
171
171
  ````text
172
172
  Upgrade `@cbartens/bkit` to the latest version in this repo and finish the resync.
173
- 1. Ensure `BKIT_GH_TOKEN_INSTALL` is available for the GitHub Packages bump. If not already in the environment, load without leaking (`source` is a shell builtin — not file I/O). `source` and the command MUST be the SAME Bash invocation:
174
- ```bash
175
- set -a; source <ENV-FILE-PATH> 2>/dev/null; set +a; \
176
- pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL" && \
177
- bkit upgrade --latest
178
- ```
179
- If token already exported (direnv / shell profile), skip `source`:
173
+ 1. Bump and resync in one step (no token — npmjs is public). If `bkit` is not on PATH, use `pnpm bkit`:
180
174
  ```bash
181
175
  bkit upgrade --latest
182
176
  ```
183
- If `bkit` not on PATH: `pnpm bkit upgrade --latest`. Do **not** only `pnpm add @cbartens/bkit@latest` — that refreshes the package without resyncing managed files.
177
+ Do **not** only `pnpm add @cbartens/bkit@latest` — that refreshes the package without resyncing managed files.
184
178
  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.
185
179
  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.
186
180
  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).
@@ -248,6 +242,7 @@ Comment prefixes (`# `, `// `) before markers preserved on block updates.
248
242
  | `docs/templates/bkit-*.md` | core | `.bkit/core/docs/templates/` | Tier 2 html-comment |
249
243
  | `.gitattributes` | core | `.bkit/shared/.gitattributes` | Tier 2 html-comment (`merge=union` for the append-only ledgers) |
250
244
  | `.bkit/templates/**` | — | the whole `.bkit/templates/` root | Raw copies, refreshed on every install and upgrade; never hashed. Upgrade prints the changed paths. |
245
+ | `.bkit/{core,shared}` | core | symlink into `node_modules/@cbartens/bkit/.bkit/{core,shared}` | View link, not a copy — browse the payload in-repo; always the installed version. Gitignored (dangles on a fresh clone / CI; install recreates). A real directory is never clobbered; `bkit uninstall` removes the link. |
251
246
  | `.bkit/{cloud,comparison,install,jsonl,LICENSE,providers,prompts,trackers,workflows,README}.md` | core | `.bkit/core/.bkit/` | Tier 1 (canonical-overwrite). The reference docs agents read at runtime, plus `LICENSE.md`: the PolyForm pair and Required Notice that travel with every file bkit writes (PolyForm's Notices section). |
252
247
  | `.claude/commands/bkit-*.md` | claude | `.bkit/core/workflows/` (byte-identical) | Host pass — always overwrite |
253
248
  | `.claude/agents/bkit-*.md` | claude | `.bkit/core/prompts/` (byte-identical) | Host pass — always overwrite |
@@ -386,13 +381,14 @@ Installed list: `.agents/skills.md`. Skills in `.agents/skills/` not listed →
386
381
 
387
382
  ### In the installed package, not your repo
388
383
 
389
- `bkit install` does not copy these out of `node_modules`. Read them at the path below — a
390
- bare `.bkit/comparison.md` or `.bkit/core/prompts/` in your own repo will not resolve.
384
+ `bkit install` does not copy these out of `node_modules`. Read them at the path below — or
385
+ in-repo through the `.bkit/core` / `.bkit/shared` view links install creates (symlinks into
386
+ the package, so editors resolve them to the `node_modules/…` paths).
391
387
 
392
388
  <!-- prettier-ignore -->
393
389
  | File | Purpose |
394
390
  | --- | --- |
395
- | `.bkit/install.md` | First-time install, auth (`BKIT_GH_TOKEN_INSTALL` / `.npmrc` / GHA / Vercel), install lifecycle, uninstall |
391
+ | `.bkit/install.md` | First-time install and upgrade, install lifecycle, uninstall |
396
392
  | `.bkit/comparison.md` | Pipeline reference + comparison to agentic design patterns / peer frameworks |
397
393
  | `node_modules/@cbartens/bkit/.bkit/core/workflows/` | Canonical slash-command source (rendered into `.claude/commands/`, `.cursor/commands/`, `.opencode/commands/`) |
398
394
  | `node_modules/@cbartens/bkit/.bkit/core/prompts/` | Canonical subagent source (rendered into `.claude/agents/`, `.cursor/agents/`, `.opencode/agents/`) |
@@ -162,25 +162,19 @@ Full Linear ↔ Cursor setup: <https://linear.app/docs/cursor>.
162
162
 
163
163
  `.agents/` = **canonical**. `bkit install` regenerates host outputs (`.claude/**`, `.cursor/**`) and rewrites bkit-managed blocks across consumer repo.
164
164
 
165
- First-time install, `BKIT_GH_TOKEN_INSTALL` / `.npmrc` / GHA / Vercel auth, uninstall: `.bkit/install.md`. Ongoing ops below.
165
+ First-time install and upgrade, uninstall: `.bkit/install.md`. Ongoing ops below.
166
166
 
167
167
  ### Upgrade — paste into your AI
168
168
 
169
- Prefer `bkit upgrade --latest` (bumps package **and** resyncs managed files) — do **not** only `pnpm add`. Replace `<ENV-FILE-PATH>` if token not already loaded (direnv / `.bkit/.env`).
169
+ Prefer `bkit upgrade --latest` (bumps package **and** resyncs managed files) — do **not** only `pnpm add`.
170
170
 
171
171
  ````text
172
172
  Upgrade `@cbartens/bkit` to the latest version in this repo and finish the resync.
173
- 1. Ensure `BKIT_GH_TOKEN_INSTALL` is available for the GitHub Packages bump. If not already in the environment, load without leaking (`source` is a shell builtin — not file I/O). `source` and the command MUST be the SAME Bash invocation:
174
- ```bash
175
- set -a; source <ENV-FILE-PATH> 2>/dev/null; set +a; \
176
- pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL" && \
177
- bkit upgrade --latest
178
- ```
179
- If token already exported (direnv / shell profile), skip `source`:
173
+ 1. Bump and resync in one step (no token — npmjs is public). If `bkit` is not on PATH, use `pnpm bkit`:
180
174
  ```bash
181
175
  bkit upgrade --latest
182
176
  ```
183
- If `bkit` not on PATH: `pnpm bkit upgrade --latest`. Do **not** only `pnpm add @cbartens/bkit@latest` — that refreshes the package without resyncing managed files.
177
+ Do **not** only `pnpm add @cbartens/bkit@latest` — that refreshes the package without resyncing managed files.
184
178
  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.
185
179
  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.
186
180
  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).
@@ -248,6 +242,7 @@ Comment prefixes (`# `, `// `) before markers preserved on block updates.
248
242
  | `docs/templates/bkit-*.md` | core | `.bkit/core/docs/templates/` | Tier 2 html-comment |
249
243
  | `.gitattributes` | core | `.bkit/shared/.gitattributes` | Tier 2 html-comment (`merge=union` for the append-only ledgers) |
250
244
  | `.bkit/templates/**` | — | the whole `.bkit/templates/` root | Raw copies, refreshed on every install and upgrade; never hashed. Upgrade prints the changed paths. |
245
+ | `.bkit/{core,shared}` | core | symlink into `node_modules/@cbartens/bkit/.bkit/{core,shared}` | View link, not a copy — browse the payload in-repo; always the installed version. Gitignored (dangles on a fresh clone / CI; install recreates). A real directory is never clobbered; `bkit uninstall` removes the link. |
251
246
  | `.bkit/{cloud,comparison,install,jsonl,LICENSE,providers,prompts,trackers,workflows,README}.md` | core | `.bkit/core/.bkit/` | Tier 1 (canonical-overwrite). The reference docs agents read at runtime, plus `LICENSE.md`: the PolyForm pair and Required Notice that travel with every file bkit writes (PolyForm's Notices section). |
252
247
  | `.claude/commands/bkit-*.md` | claude | `.bkit/core/workflows/` (byte-identical) | Host pass — always overwrite |
253
248
  | `.claude/agents/bkit-*.md` | claude | `.bkit/core/prompts/` (byte-identical) | Host pass — always overwrite |
@@ -386,13 +381,14 @@ Installed list: `.agents/skills.md`. Skills in `.agents/skills/` not listed →
386
381
 
387
382
  ### In the installed package, not your repo
388
383
 
389
- `bkit install` does not copy these out of `node_modules`. Read them at the path below — a
390
- bare `.bkit/comparison.md` or `.bkit/core/prompts/` in your own repo will not resolve.
384
+ `bkit install` does not copy these out of `node_modules`. Read them at the path below — or
385
+ in-repo through the `.bkit/core` / `.bkit/shared` view links install creates (symlinks into
386
+ the package, so editors resolve them to the `node_modules/…` paths).
391
387
 
392
388
  <!-- prettier-ignore -->
393
389
  | File | Purpose |
394
390
  | --- | --- |
395
- | `.bkit/install.md` | First-time install, auth (`BKIT_GH_TOKEN_INSTALL` / `.npmrc` / GHA / Vercel), install lifecycle, uninstall |
391
+ | `.bkit/install.md` | First-time install and upgrade, install lifecycle, uninstall |
396
392
  | `.bkit/comparison.md` | Pipeline reference + comparison to agentic design patterns / peer frameworks |
397
393
  | `node_modules/@cbartens/bkit/.bkit/core/workflows/` | Canonical slash-command source (rendered into `.claude/commands/`, `.cursor/commands/`, `.opencode/commands/`) |
398
394
  | `node_modules/@cbartens/bkit/.bkit/core/prompts/` | Canonical subagent source (rendered into `.claude/agents/`, `.cursor/agents/`, `.opencode/agents/`) |
@@ -49,15 +49,15 @@ Three cloud stacks — each agent pairs with one tracker. Pick row for agent you
49
49
  <!-- prettier-ignore -->
50
50
  | Configuration | Lives in the repo (bkit-managed) | Lives in the online dashboard (manual, one-time) |
51
51
  | --- | --- | --- |
52
- | **Claude Code on the web** | `.claude/hooks/bkit-preflight.sh` (tracker opt-in guard) + `.claude/hooks/bkit-cloud-bootstrap.sh` (per-session install — copy-and-own template, adopt it from `.bkit/templates/`) | `claude.ai/code` → environment selector → **+ Add environment**: name, **setup script** (paste from § Setup script), **environment variables** (`BKIT_GH_TOKEN`, `BKIT_GH_TOKEN_INSTALL`, `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70` — Claude pairs with the **GitHub** tracker, so no `BKIT_LINEAR_API_KEY`), **network access** (`Trusted`) |
53
- | **Cursor Cloud Agents** | `.cursor/Dockerfile` + `.cursor/environment.json` (`install` / `start` / `terminals[]` / `env`), both copied from bkit's templates and owned by the repo, + `.cursor/hooks.json` (wires preflight `failClosed: true`) + `.cursor/hooks/bkit-preflight.sh` (Linear guard) | Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents`) → your environment → **Secrets** tab, as **Runtime Secret**s: `BKIT_LINEAR_API_KEY`, `BKIT_GH_TOKEN`, `BKIT_GH_TOKEN_INSTALL`. (`LINEAR_ISSUE_ID` injected per-session by the integration — don't hardcode.) |
52
+ | **Claude Code on the web** | `.claude/hooks/bkit-preflight.sh` (tracker opt-in guard) + `.claude/hooks/bkit-cloud-bootstrap.sh` (per-session install — copy-and-own template, adopt it from `.bkit/templates/`) | `claude.ai/code` → environment selector → **+ Add environment**: name, **setup script** (paste from § Setup script), **environment variables** (`BKIT_GH_TOKEN`, `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70` — Claude pairs with the **GitHub** tracker, so no `BKIT_LINEAR_API_KEY`), **network access** (`Trusted`) |
53
+ | **Cursor Cloud Agents** | `.cursor/Dockerfile` + `.cursor/environment.json` (`install` / `start` / `terminals[]` / `env`), both copied from bkit's templates and owned by the repo, + `.cursor/hooks.json` (wires preflight `failClosed: true`) + `.cursor/hooks/bkit-preflight.sh` (Linear guard) | Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents`) → your environment → **Secrets** tab, as **Runtime Secret**s: `BKIT_LINEAR_API_KEY`, `BKIT_GH_TOKEN`. (`LINEAR_ISSUE_ID` injected per-session by the integration — don't hardcode.) |
54
54
 
55
55
  **Rule of thumb:** env vars / auth tokens → online dashboard (out of git). Scripts / Dockerfile / install hooks → repo.
56
56
 
57
57
  **Alignment guarantees bkit enforces:**
58
58
 
59
59
  - Same vale version (3.9.1) pre-installed on both clouds.
60
- - pnpm via corepack on both. Pastes pre-warm bkit's pin (`10.34.3`), but corepack resolves **each repo's own `packageManager`** in-repo — one setup script serves any pnpm pin; pre-warm version not load-bearing.
60
+ - pnpm via corepack on both. Pastes pre-warm bkit's pin (`10.34.4`), but corepack resolves **each repo's own `packageManager`** in-repo — one setup script serves any pnpm pin; pre-warm version not load-bearing.
61
61
  - gh CLI on both: web setup script installs latest binary (same `github.com` release-download style as vale); GitHub-Actions runner ships pre-installed. Auth shared via `bkit-cloud-bootstrap.sh` (`gh auth login --with-token` with `BKIT_GH_TOKEN`, skipped when `GITHUB_TOKEN` already auths on runner).
62
62
  - Same opt-in-guard pattern — opt-in label `bkit:auto` — wrapped in `<!-- bkit:start --> ... <!-- bkit:end -->` (bkit-managed in consumer repos). Label `bkit:auto` on both trackers.
63
63
 
@@ -95,7 +95,7 @@ Open `claude.ai/code` → environment selector → **+ Add environment**. Three
95
95
  ## In-repo side
96
96
 
97
97
  - `.claude/hooks/bkit-preflight.sh` — Tracker opt-in guard. Skips silently when tracker issue ID env var unset (IDE sessions). Non-zero exit informational only on Claude (`SessionStart` cannot block); agent reads `HARD STOP` text from `additionalContext`.
98
- - `.claude/hooks/bkit-cloud-bootstrap.sh` — writes GH Packages auth token to pnpm user-level config (`BKIT_GH_TOKEN_INSTALL`), then `pnpm install --frozen-lockfile` + `vale sync` when `CLAUDE_CODE_REMOTE=true`; then, through the just-installed bkit (`bkit runtime detect` gh probe, `bkit context list-blocks` provision recipes, read with `jq`), gh auth and context-fetch CLI provisioning — skipped with a loud log line when bkit or `jq` is missing. No-op locally. Set `BKIT_GH_TOKEN_INSTALL` in cloud dashboard env.
98
+ - `.claude/hooks/bkit-cloud-bootstrap.sh` — runs `pnpm install --frozen-lockfile` + `vale sync` when `CLAUDE_CODE_REMOTE=true`; then, through the just-installed bkit (`bkit runtime detect` gh probe, `bkit context list-blocks` provision recipes, read with `jq`), gh auth and context-fetch CLI provisioning — skipped with a loud log line when bkit or `jq` is missing. No-op locally.
99
99
  - Both registered in `.claude/settings.json` under `hooks.SessionStart`.
100
100
 
101
101
  Ships with repo — don't paste into app.
@@ -106,13 +106,13 @@ Ships with repo — don't paste into app.
106
106
 
107
107
  Name environment **after the repo** — one env per repo, secrets isolated (§ Sharing across repos). Setup script identical across repos.
108
108
 
109
- Identical across repos: **setup-script body**, **network policy**, bkit **baseline token names** (`BKIT_GH_TOKEN`, `BKIT_GH_TOKEN_INSTALL`, `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`) — only values change. Rest of env-vars box is **this repo's own**, copied from env-var files per `.envrc` (§ Environment variables).
109
+ Identical across repos: **setup-script body**, **network policy**, bkit **baseline token names** (`BKIT_GH_TOKEN`, `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`) — only values change. Rest of env-vars box is **this repo's own**, copied from env-var files per `.envrc` (§ Environment variables).
110
110
 
111
111
  ### Network access
112
112
 
113
113
  Always `Custom` — the rendered list carries bkit's own shipped hosts (trackers, registries, agent + provider APIs, the search host a `context=web` block calls) whether or not the repo declares anything. Select **Custom**, tick **Also include default list of common package managers** (EXTENDS trusted defaults — package registries, GitHub, cloud SDKs — never replaces them), paste domains bkit renders into `.claude/bkit-cloud.md` § Network access into **Allowed domains**. Declare only what bkit cannot see: log-backend/API hosts the implicit CLI blocks reach (`vercel` / `gcloud`) plus app production + preview/dev domains — apex-only, expanded by `bkit install` to `<domain>` + `*.<domain>` and unioned with the derived set. Under `Trusted` those hosts unreachable → cloud `/bkit-debug` gets no runtime logs; e2e can't hit deployment.
114
114
 
115
- No `allowed-domains` block still needs `Custom`: `Trusted` does not reach bkit's own tracker MCP, provider catalog or search hosts. Ticking **Also include default list of common package managers** keeps npm, GitHub Packages, the vale tarball on `objects.githubusercontent.com`, Docker Hub and PyPI. Raise to `Full` only for open-internet tasks.
115
+ No `allowed-domains` block still needs `Custom`: `Trusted` does not reach bkit's own tracker MCP, provider catalog or search hosts. Ticking **Also include default list of common package managers** keeps npm, the vale tarball on `objects.githubusercontent.com`, Docker Hub and PyPI. Raise to `Full` only for open-internet tasks.
116
116
 
117
117
  ### Environment variables
118
118
 
@@ -120,7 +120,6 @@ Minimum:
120
120
 
121
121
  ```
122
122
  BKIT_GH_TOKEN=<fine-grained PAT — see permissions below>
123
- BKIT_GH_TOKEN_INSTALL=<classic PAT with read:packages>
124
123
  CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70
125
124
  ```
126
125
 
@@ -133,12 +132,6 @@ VERCEL_TOKEN=<Vercel access token — https://vercel.com/account/settings/tokens
133
132
  SUPABASE_ACCESS_TOKEN=<Supabase Management API token — https://supabase.com/dashboard/account/tokens>
134
133
  ```
135
134
 
136
- Release-only:
137
-
138
- ```
139
- GITHUB_TOKEN=<classic PAT with write:packages + repo>
140
- ```
141
-
142
135
  #### `BKIT_GH_TOKEN` — fine-grained PAT permissions
143
136
 
144
137
  Use **fine-grained** PAT scoped to target repo (or each consumer repo, comma-separated). Mandatory expiry, repo-scoped blast radius — wins given env vars are plaintext.
@@ -160,7 +153,6 @@ Use **fine-grained** PAT scoped to target repo (or each consumer repo, comma-sep
160
153
 
161
154
  #### When classic is still required
162
155
 
163
- - **`pnpm publish` to GitHub Packages.** Fine-grained packages support has edge cases on user-owned packages. Classic PAT (`write:packages` + `repo`) in `GITHUB_TOKEN`, separate from `BKIT_GH_TOKEN`. Release-flow sessions only.
164
156
  - **Cross-repo work in single cloud session.** Fine-grained PATs only see allowlist; classic sees everything your user can.
165
157
  - **User-owned (personal-account) Projects v2 boards.** Fine-grained PATs expose Projects only as _organization_ permission — personal boards unreachable. Classic PAT with `project` scope, or move board under org.
166
158
 
@@ -207,15 +199,15 @@ Auto mode drops blanket `Bash(*)` on entry (narrow rows survive) → cloud auto-
207
199
 
208
200
  Token management by session type:
209
201
 
210
- - **Local sessions** — bkit writes `.bkit/.env.example` (token placeholders); `.envrc` (`dotenv_if_exists .bkit/.env`) is a template: copy `.bkit/templates/.envrc`. Copy `.env.example` → `.bkit/.env`, fill tokens, `direnv allow`. direnv auto-exports `BKIT_GH_TOKEN`, `BKIT_GH_TOKEN_INSTALL`, `BKIT_LINEAR_API_KEY` on repo entry — no manual `source` or shell-rc export. `.bkit/.env` gitignored; never commit.
202
+ - **Local sessions** — bkit writes `.bkit/.env.example` (token placeholders); `.envrc` (`dotenv_if_exists .bkit/.env`) is a template: copy `.bkit/templates/.envrc`. Copy `.env.example` → `.bkit/.env`, fill tokens, `direnv allow`. direnv auto-exports `BKIT_GH_TOKEN`, `BKIT_LINEAR_API_KEY` on repo entry — no manual `source` or shell-rc export. `.bkit/.env` gitignored; never commit.
211
203
 
212
204
  ```bash
213
205
  cp .bkit/.env.example .bkit/.env
214
- # edit .bkit/.env — fill in BKIT_GH_TOKEN, BKIT_GH_TOKEN_INSTALL, BKIT_LINEAR_API_KEY
206
+ # edit .bkit/.env — fill in BKIT_GH_TOKEN, BKIT_LINEAR_API_KEY
215
207
  direnv allow
216
208
  ```
217
209
 
218
- - **Cloud sessions** (Claude Code on the web, Cursor Cloud Agents) — `.bkit/.env` absent in cloud containers. Set same names (`BKIT_GH_TOKEN`, `BKIT_GH_TOKEN_INSTALL`, `BKIT_LINEAR_API_KEY`) in respective dashboards: Claude app → environment selector → Environment variables; Cursor Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents`) → your environment → **Secrets** tab (as **Runtime Secret**s). Dashboard lists in sections below = canonical reference for names.
210
+ - **Cloud sessions** (Claude Code on the web, Cursor Cloud Agents) — `.bkit/.env` absent in cloud containers. Set same names (`BKIT_GH_TOKEN`, `BKIT_LINEAR_API_KEY`) in respective dashboards: Claude app → environment selector → Environment variables; Cursor Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents`) → your environment → **Secrets** tab (as **Runtime Secret**s). Dashboard lists in sections below = canonical reference for names.
219
211
 
220
212
  **Beyond bkit tokens** — populate rest from _that repo's_ env-var files `.envrc` sources (e.g. `.bkit/.env`, then app `.env.local`). Don't hand-pick from memory; **copy from those files, following `.envrc`**:
221
213
 
@@ -252,7 +244,7 @@ bkit wires two MCP servers into `.mcp.json` at repo root (project-shared, read b
252
244
 
253
245
  **`gh auth login` required for gh CLI surface** (PR creation, branch ops, git push). Locally, keyring — do not export `GH_TOKEN` from `.bkit/.env`. Cloud/headless: `bkit-cloud-bootstrap.sh` runs `printf '%s' "$BKIT_GH_TOKEN" | gh auth login --with-token` at SessionStart (guarded by the `bkit runtime detect` gh probe, no-ops on Actions runner where `GITHUB_TOKEN` auths) — no manual step. Same PAT value fine; different env-var name keeps local `gh` on keyring.
254
246
 
255
- **Cloud sessions** (Claude on the web, Cursor Cloud Agents): Linear MCP OAuth on first touch, same as local. GitHub MCP reads `BKIT_GH_TOKEN` from dashboard — set alongside `BKIT_LINEAR_API_KEY` and `BKIT_GH_TOKEN_INSTALL`.
247
+ **Cloud sessions** (Claude on the web, Cursor Cloud Agents): Linear MCP OAuth on first touch, same as local. GitHub MCP reads `BKIT_GH_TOKEN` from dashboard — set alongside `BKIT_LINEAR_API_KEY`.
256
248
 
257
249
  ## After saving the Claude env
258
250
 
@@ -294,7 +286,7 @@ Everything in repo under `.cursor/`. bkit ships canonical content for all four f
294
286
  | File | Role | bkit ownership |
295
287
  | --- | --- | --- |
296
288
  | `.cursor/Dockerfile` | Cloud image — vale + gh + Node 20 (template default) + pnpm (corepack-pinned); browsers etc. added by the consumer | Template: copy from `.bkit/templates/.cursor/Dockerfile`; yours after |
297
- | `.cursor/environment.json` | Build pointer + per-snapshot `install` hook (`pnpm config set …:_authToken=$BKIT_GH_TOKEN_INSTALL` + `pnpm install --frozen-lockfile` + `vale sync` if `.vale.ini`) | Template: copy from `.bkit/templates/.cursor/environment.json`; yours after |
289
+ | `.cursor/environment.json` | Build pointer + per-snapshot `install` hook (`pnpm install --frozen-lockfile` + `vale sync` if `.vale.ini`) | Template: copy from `.bkit/templates/.cursor/environment.json`; yours after |
298
290
  | `.cursor/hooks.json` | Wires `sessionStart` → `bkit-preflight.sh` (`failClosed: true`) | Tier 2 contained JSON |
299
291
  | `.cursor/hooks/bkit-preflight.sh` | Tracker opt-in guard — `bkit:auto` label + non-terminal status. Skips silently on IDE sessions | Tier 2 contained (bkit:start/end markers) |
300
292
 
@@ -320,7 +312,7 @@ GitHub dispatch uses Cursor Automations "Pull request label changed" trigger —
320
312
  BKIT_GH_TOKEN=<fine-grained PAT — same permissions as the Claude side>
321
313
  ```
322
314
 
323
- `GITHUB_ISSUE_ID` injected per-session — do not hardcode. No `BKIT_LINEAR_API_KEY`, `LINEAR_ISSUE_ID`, or `BKIT_GH_TOKEN_INSTALL` for tracker calls (MCP auth = browser OAuth; `gh` uses `gh auth login` locally or `--with-token` in cloud bootstrap).
315
+ `GITHUB_ISSUE_ID` injected per-session — do not hardcode. No `BKIT_LINEAR_API_KEY` or `LINEAR_ISSUE_ID` for tracker calls (MCP auth = browser OAuth; `gh` uses `gh auth login` locally or `--with-token` in cloud bootstrap).
324
316
 
325
317
  ## How Linear dispatch works
326
318
 
@@ -338,7 +330,6 @@ Set in the Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents` → your
338
330
  ```
339
331
  BKIT_LINEAR_API_KEY=<Linear personal API key — bkit-preflight.sh calls the GraphQL API>
340
332
  BKIT_GH_TOKEN=<fine-grained PAT — same permissions as the Claude side>
341
- BKIT_GH_TOKEN_INSTALL=<classic PAT with read:packages — consumer repos only>
342
333
  ```
343
334
 
344
335
  `LINEAR_ISSUE_ID` injected per-session by Cursor / Linear integration — do not hardcode.
@@ -372,7 +363,7 @@ Each repo gets **own** Claude environment, named after repo. Reason: **secrets,
372
363
  Shared across repos (copy, don't re-derive) — non-secret only:
373
364
 
374
365
  - **Setup script** — generic binaries only (vale, gh, pnpm via corepack); repo-specific install deferred to committed `bkit-cloud-bootstrap.sh` (lockfile → `pnpm install`, `.vale.ini` → `vale sync`). One body fits every repo.
375
- - **bkit baseline token _names_** (`BKIT_GH_TOKEN`, `BKIT_GH_TOKEN_INSTALL`, `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`) + **network policy** (`Trusted`) — same everywhere, values differ. Repo _other_ env vars **not** shared: copy from own env files per `.envrc` — drop `unset`s, skip `BKIT_ANTHROPIC_API_KEY` (§ Environment variables).
366
+ - **bkit baseline token _names_** (`BKIT_GH_TOKEN`, `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`) + **network policy** (`Trusted`) — same everywhere, values differ. Repo _other_ env vars **not** shared: copy from own env files per `.envrc` — drop `unset`s, skip `BKIT_ANTHROPIC_API_KEY` (§ Environment variables).
376
367
  - **Non-secret selectors** (`VERCEL_SCOPE`, `SUPABASE_PROJECT_ID`) stay committed in-repo (§ Environment variables), never in dashboard.
377
368
 
378
369
  ## Cursor — byte-identical Dockerfile
@@ -392,7 +383,7 @@ When bkit reference Dockerfile changes (e.g. vale bump):
392
383
  ## What every consumer repo needs to do
393
384
 
394
385
  1. `pnpm bkit install` — bkit-managed toolchain updates land in the written payload; `.claude/hooks/bkit-cloud-bootstrap.sh` is a copy-and-own template, so diff it against `.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh` when `bkit upgrade` lists that path and merge what you want. `.cursor/Dockerfile` is your copy of a template: diff it against `.bkit/templates/.cursor/Dockerfile` when `bkit upgrade` lists that path.
395
- 2. Set `BKIT_LINEAR_API_KEY`, `BKIT_GH_TOKEN`, `BKIT_GH_TOKEN_INSTALL` as **Runtime Secret**s in the Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents` → your environment → **Secrets** tab). Paste-ready values are in `.cursor/bkit-cloud.md`.
386
+ 2. Set `BKIT_LINEAR_API_KEY`, `BKIT_GH_TOKEN` as **Runtime Secret**s in the Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents` → your environment → **Secrets** tab). Paste-ready values are in `.cursor/bkit-cloud.md`.
396
387
  3. Add Claude environment **named after repo** at `claude.ai/code`; paste recipe from § Claude Code on the web (one environment per repo — secrets per-repo).
397
388
  4. Customise `.cursor/Dockerfile` Node major / Playwright / extra system deps. Keep the `bkit toolchain` section as the template ships it, so a template diff stays readable.
398
389
 
@@ -438,7 +429,7 @@ Flip **both** org and repo before first router run — else `actions/checkout` 4
438
429
 
439
430
  A `context` job checks both secrets and resolves phase + arg once; each runner job needs it and runs only when its own secret is set. Only `ANTHROPIC_API_KEY` → claude job only. Only `OPENCODE_PROVIDER_KEY` → opencode only. Both → both jobs (additive coexistence). **No `BKIT_LINEAR_API_KEY`** — `bkit-cloud.yml` GitHub-tracker only for both jobs. Workflow grants `id-token: write` per-job for claude only (opencode no OIDC).
440
431
 
441
- Neither job needs `BKIT_GH_TOKEN_INSTALL`. Slash command body already in checked-out repo (mirrored to `.claude/commands/bkit-auto.md` and `.opencode/commands/bkit-auto.md` at dev time via `bkit install`). Repo git/gh ops use auto-provided `github.token` scoped by workflow `permissions:` block.
432
+ Slash command body already in checked-out repo (mirrored to `.claude/commands/bkit-auto.md` and `.opencode/commands/bkit-auto.md` at dev time via `bkit install`). Repo git/gh ops use auto-provided `github.token` scoped by workflow `permissions:` block.
442
433
 
443
434
  ## Branch-aware routing
444
435
 
@@ -197,6 +197,8 @@ Output: PR to `dev`. Heaviest phase — most steps verify rather than produce. C
197
197
 
198
198
  Output: remediated commit on feature branch. Two modes — normal (diagnose → remediate localisable failure) and soak (one accumulating-context instrument-or-fix loop for non-localisable / runtime-only failures). Normal escalates to soak when diagnose can't localise, or normal loop exhausts three strategies; observation logging (`[DEBUG-OBSERVE]`) inside soak, stripped before fix ships.
199
199
 
200
+ **Context fetch.** Per failed attempt, `/bkit-debug` runs each `context-fetch` bash block below `<!-- bkit:end -->` in `.agents/context.md` — failing CI logs, the diff since the last green run, end-to-end reports, runtime errors (Sentry, Vercel, Supabase, Stripe and more) and web search (Tavily) — writing one artifact per context and narrating `CHECKED` / `SELF-SKIPPED` / `NOT CONFIGURED` before fetching. Fail-soft and block-driven: bkit hardcodes no CI host, workflow filename or test framework, and a context with no block is never read as a clean result.
201
+
200
202
  **Normal mode**
201
203
 
202
204
  <!-- prettier-ignore -->
@@ -287,7 +289,7 @@ Benchmark: Antonio Gulli's _Agentic Design Patterns: A Hands-On Guide to Buildin
287
289
  | Exception Handling & Recovery | Already does | Universal failure path, bounded retries (3), 3600s timeouts, runaway-turn caps, human handover. |
288
290
  | Human-in-the-Loop | Already does | Mandatory hard stops after design / plan / ship; "recommend, do not decide." |
289
291
  | Resource-Aware Optimization | Already does | Effort-to-model tiering with explicit per-agent pins. |
290
- | Context Engineering | Already does | Phase doc-matrix, lazy-load, output caps, stubbed-output pattern. |
292
+ | Context Engineering | Already does | Phase doc-matrix, lazy-load, output caps, stubbed-output pattern; consumer `context-fetch` blocks add CI, diff, e2e, runtime and web signal in debug. |
291
293
  | Memory Management | Partial | Filesystem and grep episodic memory (`status.jsonl`, knowledge / decisions). No vector retrieval, by scale choice. |
292
294
  | Learning & Adaptation | Partial | `friction.jsonl` drives human-reviewed prompt edits; entries carry confidence, scope, and last-confirmed fields. No auto prompt-tuning — deliberate, to keep humans in the loop. |
293
295
  | Goal Setting & Monitoring | Partial | Issue = goal, phase labels = state, verdicts = criteria. No measurable per-task Definition of Done yet. |
@@ -305,6 +307,7 @@ Benchmark: Antonio Gulli's _Agentic Design Patterns: A Hands-On Guide to Buildin
305
307
  - **Cross-model diversity where breadth beats depth.** Design brainstorm, design review, plan scope-check groups pair Opus + Sonnet (Grok + Composer on Cursor) → two reasoners review same work. Depth-sensitive lenses (plan review, build challenge) stay on top tier.
306
308
  - **Resume-from-state as single source of truth.** `status.jsonl` makes every run inspectable and restartable; book treats this only obliquely under memory.
307
309
  - **Human-in-the-loop as non-negotiable.** Hard stops after design / plan / ship; book treats HITL as one option.
310
+ - **Fail-soft external context in debug.** Provider-agnostic `context-fetch` blocks (CI logs, diff, e2e, runtime, web) feed `/bkit-debug`; each self-skips to a narrated `CHECKED` / `SELF-SKIPPED` / `NOT CONFIGURED` state, so a context with no block is never read as a clean result.
308
311
  - **Explicit per-agent model pins.** Immune to session-default drift.
309
312
  - **Provider- and host-portable execution.** Per-agent pins → `bkit install --opencode=<provider>` adds opencode host alongside Claude/Cursor — harness unchanged; inference backend moves. Same five-phase gated parallel pipeline on four providers (OpenRouter, Ollama, opencode Zen + Go gateways). Curated per-agent pins; models mirror Claude tier by default, CoT reasoners swapped for convergent-reasoning agents (debug/risk). See `.bkit/providers.md` § Hosts + Providers.
310
313
  - **Cross-host/provider continuity.** State in `status.jsonl`, plan/design docs under `docs/plans/`, tracker issue — not vendor session. Every host renders from same `.bkit/` source → phase or resumed run moves across IDE/provider mid-feature with identical gates, hooks, per-agent pins: exhaust Claude weekly limit or free-tier quota → continue on another host, no re-setup. Single-vendor frameworks tie run to starting session.