@cbartens/bkit 5.1.0 → 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 (194) hide show
  1. package/.bkit/README.md +11 -7
  2. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +39 -50
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +74 -56
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +72 -0
  5. package/.bkit/core/.agents/rules.md +8 -4
  6. package/.bkit/core/.agents/shortcuts.md +1 -1
  7. package/.bkit/core/.bkit/LICENSE.md +18 -140
  8. package/.bkit/core/.bkit/README.md +10 -6
  9. package/.bkit/core/.bkit/cloud.md +12 -15
  10. package/.bkit/core/.bkit/comparison.md +66 -14
  11. package/.bkit/core/.bkit/install.md +31 -8
  12. package/.bkit/core/.bkit/jsonl.md +0 -1
  13. package/.bkit/core/.bkit/prompts.md +14 -13
  14. package/.bkit/core/.bkit/providers.md +90 -26
  15. package/.bkit/core/.bkit/templates.md +38 -11
  16. package/.bkit/core/.bkit/workflows.md +63 -41
  17. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +4 -3
  18. package/.bkit/core/.claude/hooks/bkit-readguard.cjs +60 -0
  19. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +8 -6
  20. package/.bkit/core/.codex/hooks/bkit-readguard.cjs +58 -0
  21. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +12 -19
  22. package/.bkit/core/.cursor/hooks/bkit-readguard.cjs +59 -0
  23. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +73 -22
  24. package/.bkit/core/.opencode/plugin/bkit-readguard.js +126 -0
  25. package/.bkit/core/docs/templates/bkit-audit-adoption.md +2 -2
  26. package/.bkit/core/docs/templates/bkit-plan.md +6 -3
  27. package/.bkit/core/engine/checks/after/auth.ts +32 -0
  28. package/.bkit/core/engine/checks/after/github.ts +4 -4
  29. package/.bkit/core/engine/checks/after/index.ts +36 -50
  30. package/.bkit/core/engine/checks/after/managed.ts +40 -0
  31. package/.bkit/core/engine/checks/before/index.ts +5 -4
  32. package/.bkit/core/engine/checks/before/mcp.ts +60 -54
  33. package/.bkit/core/engine/checks/status-holes.ts +1 -1
  34. package/.bkit/core/engine/checks/tips/catalogue.ts +356 -0
  35. package/.bkit/core/engine/checks/tips/detect.ts +144 -0
  36. package/.bkit/core/engine/checks/tips/index.ts +174 -0
  37. package/.bkit/core/engine/cli.ts +57 -9
  38. package/.bkit/core/engine/commands/install/doctor.ts +5 -1
  39. package/.bkit/core/engine/commands/install/install.ts +39 -9
  40. package/.bkit/core/engine/commands/install/uninstall.ts +32 -18
  41. package/.bkit/core/engine/commands/install/upgrade.ts +15 -28
  42. package/.bkit/core/engine/commands/launch.ts +33 -11
  43. package/.bkit/core/engine/commands/tips.ts +16 -0
  44. package/.bkit/core/engine/commands/workflow/runs.ts +57 -16
  45. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -0
  46. package/.bkit/core/engine/commands/workflow/steps.ts +1 -0
  47. package/.bkit/core/engine/commands/workflow/tests.ts +647 -4
  48. package/.bkit/core/engine/commands/workflow/workstreams.ts +4 -4
  49. package/.bkit/core/engine/install/cloud-env.ts +7 -21
  50. package/.bkit/core/engine/install/hosts.ts +21 -0
  51. package/.bkit/core/engine/install/managed-block.ts +36 -0
  52. package/.bkit/core/engine/install/manifest.ts +46 -4
  53. package/.bkit/core/engine/install/modules/antigravity.ts +8 -7
  54. package/.bkit/core/engine/install/modules/claude.ts +6 -6
  55. package/.bkit/core/engine/install/modules/cloud.ts +2 -2
  56. package/.bkit/core/engine/install/modules/codex.ts +5 -5
  57. package/.bkit/core/engine/install/modules/core.ts +23 -9
  58. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  59. package/.bkit/core/engine/install/modules/opencode.ts +4 -4
  60. package/.bkit/core/engine/install/payload-links.ts +6 -10
  61. package/.bkit/core/engine/install/placeholders.ts +1 -1
  62. package/.bkit/core/engine/install/version-file.ts +17 -9
  63. package/.bkit/core/engine/install/write.ts +68 -1
  64. package/.bkit/core/engine/ledgers/telemetry.ts +0 -2
  65. package/.bkit/core/engine/shared/package-roots.ts +8 -10
  66. package/.bkit/core/hooks/antigravity-hook.js +67 -0
  67. package/.bkit/core/hooks/gateguard-edit-payload.js +4 -4
  68. package/.bkit/core/hooks/gateguard-engine.js +16 -6
  69. package/.bkit/core/hooks/guardrails-read.js +23 -0
  70. package/.bkit/core/hooks/readguard-engine.js +259 -0
  71. package/.bkit/core/hooks/readguard-payload.js +67 -0
  72. package/.bkit/core/prompts/bkit-audit-generate.md +1 -0
  73. package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -0
  74. package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -0
  75. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -0
  76. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -0
  77. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -0
  78. package/.bkit/core/prompts/bkit-build-install-skills.md +1 -0
  79. package/.bkit/core/prompts/bkit-build-plan-current.md +1 -0
  80. package/.bkit/core/prompts/bkit-build-plan-execute.md +5 -1
  81. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -0
  82. package/.bkit/core/prompts/bkit-build-plan-verify.md +11 -3
  83. package/.bkit/core/prompts/bkit-build-summary.md +1 -0
  84. package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -0
  85. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -0
  86. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -0
  87. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -0
  88. package/.bkit/core/prompts/bkit-debug-summary.md +1 -0
  89. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +1 -0
  90. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +1 -0
  91. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +1 -0
  92. package/.bkit/core/prompts/bkit-design-generate.md +9 -4
  93. package/.bkit/core/prompts/bkit-design-organise.md +1 -0
  94. package/.bkit/core/prompts/bkit-design-review-1.md +1 -0
  95. package/.bkit/core/prompts/bkit-design-review-2.md +1 -0
  96. package/.bkit/core/prompts/bkit-design-spike.md +1 -0
  97. package/.bkit/core/prompts/bkit-design-summary.md +1 -0
  98. package/.bkit/core/prompts/bkit-design-update.md +1 -0
  99. package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -0
  100. package/.bkit/core/prompts/bkit-plan-complexity-split.md +3 -2
  101. package/.bkit/core/prompts/bkit-plan-generate.md +1 -0
  102. package/.bkit/core/prompts/bkit-plan-review-1.md +1 -0
  103. package/.bkit/core/prompts/bkit-plan-review-2.md +1 -0
  104. package/.bkit/core/prompts/bkit-plan-review-3.md +1 -0
  105. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +2 -1
  106. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +2 -1
  107. package/.bkit/core/prompts/bkit-plan-summary.md +1 -0
  108. package/.bkit/core/prompts/bkit-plan-update.md +2 -1
  109. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -0
  110. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -0
  111. package/.bkit/core/prompts/bkit-ship-summary.md +1 -0
  112. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -0
  113. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +1 -0
  114. package/.bkit/core/prompts/bkit-utility-update-decisions.md +1 -0
  115. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +1 -0
  116. package/.bkit/core/prompts/bkit-utility-update-documentation.md +1 -0
  117. package/.bkit/core/prompts/bkit-utility-update-failures.md +1 -0
  118. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +1 -0
  119. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +1 -0
  120. package/.bkit/core/workflows/bkit-build.md +33 -21
  121. package/.bkit/core/workflows/bkit-debug.md +29 -22
  122. package/.bkit/core/workflows/bkit-design.md +81 -38
  123. package/.bkit/core/workflows/bkit-plan.md +8 -2
  124. package/.bkit/core/workflows/bkit-ship.md +8 -2
  125. package/.bkit/shared/.agents/plugins/bkit/hooks.json +13 -3
  126. package/.bkit/shared/.claude/settings.json +19 -0
  127. package/.bkit/shared/.codex/hooks.json +21 -0
  128. package/.bkit/shared/.cursor/hooks.json +6 -1
  129. package/.bkit/shared/.opencode/opencode.json +1 -1
  130. package/.bkit/shared/docs/deployments.md +1 -1
  131. package/.bkit/shared/docs/testing.md +12 -1
  132. package/.bkit/templates/.github/dependabot.yml +6 -0
  133. package/.bkit/templates/.github/renovate.json5 +3 -3
  134. package/.bkit/templates/.github/workflows/bkit-ci.yml +0 -13
  135. package/.bkit/templates/.github/workflows/bkit-cloud.yml +5 -5
  136. package/.bkit/templates/.prettierignore +1 -1
  137. package/.bkit/templates/context/bkit-expo.md +22 -13
  138. package/.bkit/templates/context/bkit-github.md +20 -6
  139. package/.bkit/templates/context/bkit-inngest.md +10 -4
  140. package/.bkit/templates/context/bkit-maestro.md +5 -5
  141. package/.bkit/templates/context/bkit-playwright.md +3 -3
  142. package/.bkit/templates/context/bkit-sentry.md +6 -5
  143. package/.bkit/templates/context/bkit-stripe.md +31 -8
  144. package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +65 -19
  145. package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +34 -0
  146. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +33 -12
  147. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +54 -0
  148. package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +76 -6
  149. package/.bkit/templates/slop-scan.config.json +7 -2
  150. package/CHANGELOG.md +42 -0
  151. package/LICENSE.md +21 -161
  152. package/README.md +58 -28
  153. package/dist/checks/after/auth.js +28 -0
  154. package/dist/checks/after/github.js +4 -4
  155. package/dist/checks/after/index.js +29 -45
  156. package/dist/checks/after/managed.js +40 -1
  157. package/dist/checks/before/index.js +5 -4
  158. package/dist/checks/before/mcp.js +53 -53
  159. package/dist/checks/status-holes.js +1 -1
  160. package/dist/checks/tips/catalogue.js +297 -0
  161. package/dist/checks/tips/detect.js +130 -0
  162. package/dist/checks/tips/index.js +146 -0
  163. package/dist/cli.js +47 -9
  164. package/dist/commands/install/doctor.js +5 -1
  165. package/dist/commands/install/install.js +27 -7
  166. package/dist/commands/install/uninstall.js +31 -16
  167. package/dist/commands/install/upgrade.js +15 -32
  168. package/dist/commands/launch.js +27 -11
  169. package/dist/commands/tips.js +10 -0
  170. package/dist/commands/workflow/runs.js +52 -16
  171. package/dist/commands/workflow/runtime.js +8 -0
  172. package/dist/commands/workflow/steps.js +1 -0
  173. package/dist/commands/workflow/tests.js +541 -4
  174. package/dist/commands/workflow/workstreams.js +4 -4
  175. package/dist/install/cloud-env.js +3 -14
  176. package/dist/install/hosts.js +22 -0
  177. package/dist/install/managed-block.js +36 -0
  178. package/dist/install/manifest.js +45 -4
  179. package/dist/install/modules/antigravity.js +8 -7
  180. package/dist/install/modules/claude.js +6 -6
  181. package/dist/install/modules/cloud.js +2 -2
  182. package/dist/install/modules/codex.js +5 -5
  183. package/dist/install/modules/core.js +14 -5
  184. package/dist/install/modules/cursor.js +6 -6
  185. package/dist/install/modules/opencode.js +4 -4
  186. package/dist/install/payload-links.js +5 -5
  187. package/dist/install/placeholders.js +1 -1
  188. package/dist/install/version-file.js +12 -3
  189. package/dist/install/write.js +61 -2
  190. package/dist/shared/package-roots.js +8 -11
  191. package/package.json +4 -6
  192. package/.bkit/core/LICENSE.md +0 -149
  193. package/.bkit/shared/LICENSE.md +0 -22
  194. package/.bkit/templates/LICENSE.md +0 -22
@@ -47,6 +47,38 @@ export function hasGithubMcpServer(cwd: string): boolean {
47
47
  return false;
48
48
  }
49
49
 
50
+ /**
51
+ * BKIT_GH_TOKEN unset or empty in the shell while a `github` MCP server is configured.
52
+ * Never in CI. The GitHub MCP server authenticates with `Authorization: Bearer
53
+ * ${BKIT_GH_TOKEN}` in .mcp.json, which powers the entire tracker + PR + Projects MCP
54
+ * surface.
55
+ */
56
+ export function detectGhMcpToken(cwd: string): PreflightFinding | null {
57
+ if (!hasGithubMcpServer(cwd) || process.env.CI) return null;
58
+ const status = detectShellGhMcpToken();
59
+ if (status === "missing") {
60
+ return {
61
+ id: "gh-mcp-token-unset-shell",
62
+ severity: "advisory",
63
+ detect:
64
+ "BKIT_GH_TOKEN is not set in the shell environment (undefined). The GitHub MCP server authenticates with `Authorization: Bearer ${BKIT_GH_TOKEN}` — without it, every tracker, PR, and board MCP call fails to connect.",
65
+ action:
66
+ "Set BKIT_GH_TOKEN in .bkit/.env (canonical local-secrets file, gitignored), then `direnv allow` and restart your editor so MCP servers pick it up:\n\n cp .bkit/.env.example .bkit/.env # if not already done\n # edit .bkit/.env — set BKIT_GH_TOKEN=<PAT>\n direnv allow\n\nUse a fine-grained PAT when every target repo sits under one owner (Contents, Pull requests, Issues, and Actions read & write, plus organization-scoped Projects read & write if you use board sync); use a classic PAT when one token must span owners (scopes repo / workflow / read:org / project / security_events). Generate at: https://github.com/settings/personal-access-tokens (fine-grained) or https://github.com/settings/tokens (classic). In cloud sessions (Claude Code web / Cursor Background Agents) set BKIT_GH_TOKEN in the dashboard env vars instead — repo files are not read for secrets there.",
67
+ };
68
+ }
69
+ if (status === "empty") {
70
+ return {
71
+ id: "gh-mcp-token-empty-shell",
72
+ severity: "advisory",
73
+ detect:
74
+ 'BKIT_GH_TOKEN is set to an empty string (BKIT_GH_TOKEN=""). The GitHub MCP server sends an empty bearer token and fails to authenticate — distinct from unset, same effect.',
75
+ action:
76
+ "Set a non-empty BKIT_GH_TOKEN in .bkit/.env (fine-grained PAT for one owner, or classic across owners; Contents / Pull requests / Issues / Actions read & write), then `direnv allow` and restart your editor so MCP servers reload.",
77
+ };
78
+ }
79
+ return null;
80
+ }
81
+
50
82
  /**
51
83
  * Detect whether a named secret is set on the consumer's GitHub repo.
52
84
  * Returns "present" | "missing" | "unknown".
@@ -88,7 +88,7 @@ export function readConsumerIssueTracker(cwd: string): IssueTracker {
88
88
  /**
89
89
  * Emit a tracker-specific setup advisory.
90
90
  *
91
- * - `github` → GitHub tracker: MCP auth is browser OAuth — no PAT needed for tracker calls.
91
+ * - `github` → GitHub tracker: the GitHub MCP server authenticates with `BKIT_GH_TOKEN`; `gh` uses `gh auth login`.
92
92
  * - `linear` → existing Linear setup message (BKIT_LINEAR_API_KEY + LINEAR_ISSUE_ID).
93
93
  * - `none` → prompt to run `bkit install --tracker=github` or `--tracker=linear`.
94
94
  *
@@ -108,7 +108,7 @@ export function buildTrackerSetupAdvisory(cwd: string): PreflightFinding | null
108
108
  detect:
109
109
  "bkit tracker is configured as `github`. GitHub Issues + Projects v2 is the active tracker.",
110
110
  action:
111
- "GitHub tracker: MCP auth is browser OAuth — run `gh auth login` once for CLI surface. No PAT needed for tracker calls. The GitHub MCP server uses OAuth automatically on first tool call. Ensure the `github` MCP server is configured in `.mcp.json` and `.cursor/mcp.json`.",
111
+ "GitHub tracker: the GitHub MCP server authenticates with `BKIT_GH_TOKEN` (fine-grained PAT for one owner, classic PAT across owners) — set it in `.bkit/.env`, then `direnv allow`. Unset → every tracker and PR MCP call fails. The `gh` CLI signs in separately: run `gh auth login` once. Ensure the `github` MCP server is configured in `.mcp.json` and `.cursor/mcp.json`.",
112
112
  };
113
113
  }
114
114
 
@@ -133,7 +133,7 @@ export function buildTrackerSetupAdvisory(cwd: string): PreflightFinding | null
133
133
  detect:
134
134
  "bkit tracker is not configured (`bkit.issueTracker` absent). Workflows run but every tracker call is a no-op.",
135
135
  action:
136
- 'Optional post-install decision. Run `bkit install --tracker=github` (recommended) or `bkit install --tracker=linear` to enable tracker integration. GitHub tracker uses browser OAuth — no PAT required. Linear tracker requires `BKIT_LINEAR_API_KEY` in `.bkit/.env`. To opt out and silence this advisory, set `bkit.issueTracker` to `"none"` in package.json.',
136
+ 'Optional post-install decision. Run `bkit install --tracker=github` (recommended) or `bkit install --tracker=linear` to enable tracker integration. GitHub tracker requires `BKIT_GH_TOKEN` in `.bkit/.env` (fine-grained PAT for one owner, classic PAT across owners). Linear tracker requires `BKIT_LINEAR_API_KEY` in `.bkit/.env`. To opt out and silence this advisory, set `bkit.issueTracker` to `"none"` in package.json.',
137
137
  };
138
138
  }
139
139
 
@@ -399,7 +399,7 @@ export function buildCloudSetupAdvisory(cwd: string): PreflightFinding | null {
399
399
  severity: "advisory",
400
400
  detect:
401
401
  "Cloud agents: post-CI auto-routing is active (`.github/workflows/bkit-cloud.yml` present). The Claude GitHub App is required — run `/install-github-app` (Claude Code CLI) once if not already done.",
402
- action: `The workflow requires: the \`ANTHROPIC_API_KEY\` repo secret, the Claude GitHub App (\`/install-github-app\`), and GitHub Actions write permissions (org AND repo). See the \`bkit-auto-setup\` advisory (emitted by \`bkit install --auto=claude\`) and bkit's \`cloud.md\` § Post-CI auto-routing for the full checklist.`,
402
+ action: `The workflow requires: the \`ANTHROPIC_API_KEY\` repo secret, the Claude GitHub App (\`/install-github-app\`), and GitHub Actions write permissions (org AND repo). See the \`bkit-auto-setup\` advisory (emitted by \`bkit install --auto=claude\`) and bkit's \`cloud.md\` § Post-CI auto-routing for the full checklist.\n\nbkit's agents comment as you, so every workflow those comments trigger notifies you, even ones that skip. To see only failures: GitHub → Settings → Notifications → System → Actions → "Only notify for failed workflows".`,
403
403
  };
404
404
  }
405
405
 
@@ -13,14 +13,8 @@ import {
13
13
  } from "../before/env.js";
14
14
  import { getPkgRoot } from "../../shared/package-roots.js";
15
15
  import { detectOpencodeYmlProviderDrift } from "../../install/modules/opencode.js";
16
- import { TEMPLATES_POINTER } from "../../install/template-copies.js";
17
- import { detectManagedStale } from "./managed.js";
18
- import {
19
- buildCloudDashboardsAdvisory,
20
- detectCiRouterSecrets,
21
- detectShellGhMcpToken,
22
- hasGithubMcpServer,
23
- } from "./auth.js";
16
+ import { detectManagedDuplicate, detectManagedStale } from "./managed.js";
17
+ import { buildCloudDashboardsAdvisory, detectCiRouterSecrets, detectGhMcpToken } from "./auth.js";
24
18
  import {
25
19
  buildCloudSetupAdvisory,
26
20
  buildGithubProjectAdvisory,
@@ -48,6 +42,12 @@ import {
48
42
  detectTurboIntegrationInputs,
49
43
  } from "./ci-yml.js";
50
44
  import { type SuppressionNote, type SuppressionReporter } from "./suppression.js";
45
+ import {
46
+ dropTipSilencedAdvisories,
47
+ setupTipsChecklistLines,
48
+ setupTipsMarkdownLines,
49
+ } from "../tips/index.js";
50
+ import type { SetupTip } from "../tips/catalogue.js";
51
51
 
52
52
  // ---------------------------------------------------------------------------
53
53
  // formatChecklist — pure renderer
@@ -90,26 +90,27 @@ export function suppressedNoteLines(suppressed: SuppressionNote[]): string[] {
90
90
 
91
91
  /**
92
92
  * Format a list of findings into the post-install console checklist.
93
- * Returns `""` when findings AND suppressed are both empty — callers can `if (banner)` to
94
- * stay silent. No console.log inside — caller logs.
93
+ * Returns `""` when findings, suppressed and tips are all empty — callers can `if (banner)`
94
+ * to stay silent. No console.log inside — caller logs.
95
95
  *
96
- * Same content as `renderAdvisoriesMarkdown`: title, summary, agent instructions
97
- * and template pointer are the shared strings; only the separators differ from
98
- * the markdown form.
96
+ * Same content as `renderAdvisoriesMarkdown`: title, summary, agent instructions and
97
+ * setup tips are the shared strings; only the separators differ from the markdown form.
99
98
  *
100
99
  * Format per finding:
101
100
  * --- i/N [severity] id ---
102
101
  * Detect: ...
103
102
  * Action: ...
104
103
  *
105
- * `suppressed` is appended as its own block (see `suppressedNoteLines`) — a dismissed
106
- * advisory stays visible even when nothing else fired.
104
+ * `tips` follow the findings as the Setup tips block; `suppressed` is appended as its own
105
+ * block (see `suppressedNoteLines`) — a dismissed advisory or tip stays visible even when
106
+ * nothing else fired.
107
107
  */
108
108
  export function formatChecklist(
109
109
  findings: PreflightFinding[],
110
110
  suppressed: SuppressionNote[] = [],
111
+ tips: readonly SetupTip[] = [],
111
112
  ): string {
112
- if (findings.length === 0 && suppressed.length === 0) return "";
113
+ if (findings.length === 0 && suppressed.length === 0 && tips.length === 0) return "";
113
114
 
114
115
  const banner = "=".repeat(58);
115
116
  const total = findings.length;
@@ -125,8 +126,6 @@ export function formatChecklist(
125
126
  lines.push("");
126
127
  lines.push(ADVISORIES_AGENT_INSTRUCTIONS);
127
128
  lines.push("");
128
- lines.push(TEMPLATES_POINTER);
129
- lines.push("");
130
129
  }
131
130
 
132
131
  for (let i = 0; i < findings.length; i++) {
@@ -137,6 +136,8 @@ export function formatChecklist(
137
136
  lines.push("");
138
137
  }
139
138
 
139
+ lines.push(...setupTipsChecklistLines(tips));
140
+
140
141
  const suppressedLines = suppressedNoteLines(suppressed);
141
142
  if (suppressedLines.length > 0) {
142
143
  lines.push(...suppressedLines);
@@ -158,13 +159,14 @@ export type AdvisoriesMode = "install" | "check" | "doctor";
158
159
  /**
159
160
  * Render findings as a markdown artifact suitable for `.bkit/advisories.md`.
160
161
  * Renders the SAME content as `formatChecklist` (shared title, summary, agent
161
- * instructions, template pointer and suppressed block) in markdown form, so the file can
162
+ * instructions, setup tips and suppressed block) in markdown form, so the file can
162
163
  * be referenced and revisited between installs. Overwritten on every run.
163
164
  */
164
165
  export function renderAdvisoriesMarkdown(
165
166
  findings: PreflightFinding[],
166
167
  opts: { mode: AdvisoriesMode; version: string },
167
168
  suppressed: SuppressionNote[] = [],
169
+ tips: readonly SetupTip[] = [],
168
170
  ): string {
169
171
  const lines: string[] = [];
170
172
  // This is a generated, gitignored artifact — not authored prose. Advisory
@@ -184,7 +186,7 @@ export function renderAdvisoriesMarkdown(
184
186
  );
185
187
  lines.push("");
186
188
 
187
- if (findings.length === 0 && suppressed.length === 0) {
189
+ if (findings.length === 0 && suppressed.length === 0 && tips.length === 0) {
188
190
  lines.push("**No advisories.** Last run was clean.");
189
191
  lines.push("");
190
192
  return lines.join("\n");
@@ -195,8 +197,6 @@ export function renderAdvisoriesMarkdown(
195
197
  lines.push("");
196
198
  lines.push(`> ${ADVISORIES_AGENT_INSTRUCTIONS}`);
197
199
  lines.push("");
198
- lines.push(`> ${TEMPLATES_POINTER}`);
199
- lines.push("");
200
200
  }
201
201
 
202
202
  const total = findings.length;
@@ -210,6 +210,8 @@ export function renderAdvisoriesMarkdown(
210
210
  lines.push("");
211
211
  }
212
212
 
213
+ lines.push(...setupTipsMarkdownLines(tips));
214
+
213
215
  const suppressedLines = suppressedNoteLines(suppressed);
214
216
  if (suppressedLines.length > 0) {
215
217
  lines.push(...suppressedLines);
@@ -232,6 +234,7 @@ export function writeAdvisoriesArtifact(
232
234
  version: string;
233
235
  logPrefix: string;
234
236
  suppressed?: SuppressionNote[];
237
+ tips?: readonly SetupTip[];
235
238
  },
236
239
  ): void {
237
240
  const dir = path.join(opts.cwd, ".bkit");
@@ -245,6 +248,7 @@ export function writeAdvisoriesArtifact(
245
248
  version: opts.version,
246
249
  },
247
250
  opts.suppressed ?? [],
251
+ opts.tips ?? [],
248
252
  );
249
253
  fs.writeFileSync(filePath, content);
250
254
  const n = findings.length;
@@ -350,32 +354,13 @@ export function runPostInstallCheck(
350
354
  const managedStale = detectManagedStale(cwd);
351
355
  if (managedStale) phase3.push(managedStale);
352
356
 
353
- // BKIT_GH_TOKEN shell env — authenticates the GitHub MCP server
354
- // (`Authorization: Bearer ${BKIT_GH_TOKEN}` in .mcp.json), which powers the entire
355
- // tracker + PR + Projects MCP surface. Only flags when a github MCP server is
356
- // configured, and never in CI.
357
- if (hasGithubMcpServer(cwd) && !process.env.CI) {
358
- const ghMcpTokenStatus = detectShellGhMcpToken();
359
- if (ghMcpTokenStatus === "missing") {
360
- phase3.push({
361
- id: "gh-mcp-token-unset-shell",
362
- severity: "advisory",
363
- detect:
364
- "BKIT_GH_TOKEN is not set in the shell environment (undefined). The GitHub MCP server authenticates with `Authorization: Bearer ${BKIT_GH_TOKEN}` — without it, every tracker, PR, and board MCP call fails to connect.",
365
- action:
366
- "Set BKIT_GH_TOKEN in .bkit/.env (canonical local-secrets file, gitignored), then `direnv allow` and restart your editor so MCP servers pick it up:\n\n cp .bkit/.env.example .bkit/.env # if not already done\n # edit .bkit/.env — set BKIT_GH_TOKEN=<PAT>\n direnv allow\n\nUse a fine-grained PAT when every target repo sits under one owner (Contents, Pull requests, Issues, and Actions read & write, plus organization-scoped Projects read & write if you use board sync); use a classic PAT when one token must span owners (scopes repo / workflow / read:org / project / security_events). Generate at: https://github.com/settings/personal-access-tokens (fine-grained) or https://github.com/settings/tokens (classic). In cloud sessions (Claude Code web / Cursor Background Agents) set BKIT_GH_TOKEN in the dashboard env vars instead — repo files are not read for secrets there.",
367
- });
368
- } else if (ghMcpTokenStatus === "empty") {
369
- phase3.push({
370
- id: "gh-mcp-token-empty-shell",
371
- severity: "advisory",
372
- detect:
373
- 'BKIT_GH_TOKEN is set to an empty string (BKIT_GH_TOKEN=""). The GitHub MCP server sends an empty bearer token and fails to authenticate — distinct from unset, same effect.',
374
- action:
375
- "Set a non-empty BKIT_GH_TOKEN in .bkit/.env (fine-grained PAT for one owner, or classic across owners; Contents / Pull requests / Issues / Actions read & write), then `direnv allow` and restart your editor so MCP servers reload.",
376
- });
377
- }
378
- }
357
+ // Older unmarked copy of a managed markdown block left outside its markers.
358
+ const managedDuplicate = detectManagedDuplicate(cwd);
359
+ if (managedDuplicate) phase3.push(managedDuplicate);
360
+
361
+ // BKIT_GH_TOKEN shell env — authenticates the GitHub MCP server.
362
+ const ghMcpToken = detectGhMcpToken(cwd);
363
+ if (ghMcpToken) phase3.push(ghMcpToken);
379
364
 
380
365
  // Main branch protection — bkit's PR-base gates (build Step 17, ship Step 2)
381
366
  // assert feat/* PRs target dev. Enforcing it at the GitHub layer needs branch
@@ -525,6 +510,7 @@ export function runPostInstallCheck(
525
510
  const phase3Ids = new Set(deduped.map((f) => f.id));
526
511
  const filteredPreflight = dedupedPreflight.filter((f) => !phase3Ids.has(f.id));
527
512
 
528
- // Final order: preflight advisories (that weren't superseded) first, then Phase 3
529
- return [...filteredPreflight, ...deduped];
513
+ // Final order: preflight advisories (that weren't superseded) first, then Phase 3.
514
+ // An advisory a setup tip reuses goes quiet with that tip (`bkit.ignoreAdvisories`).
515
+ return dropTipSilencedAdvisories([...filteredPreflight, ...deduped], cwd, onSuppressed);
530
516
  }
@@ -11,8 +11,11 @@ import { readManagedVersion } from "../../install/version-file.js";
11
11
  import { getPkgRoot } from "../../shared/package-roots.js";
12
12
  import {
13
13
  detectMarkerStyle,
14
+ extractManagedBlock,
14
15
  findLineAnchoredMarkers,
16
+ findUnmarkedCopy,
15
17
  selectMarkers,
18
+ stripManagedBlock,
16
19
  } from "../../install/managed-block.js";
17
20
  import { listStampedFiles } from "../../install/modules/index.js";
18
21
 
@@ -162,6 +165,43 @@ export function detectManagedStale(
162
165
  };
163
166
  }
164
167
 
168
+ // ---------------------------------------------------------------------------
169
+ // detectManagedDuplicate — an older unmarked copy kept beside a managed markdown block
170
+ // ---------------------------------------------------------------------------
171
+
172
+ /**
173
+ * Managed markdown blocks whose file also holds an older, unmarked copy of the block outside
174
+ * the markers (findUnmarkedCopy). Install never touches content outside the markers, so that
175
+ * copy stays at the version it was left at while agents read it beside the live block.
176
+ * Advisory: the match is a heuristic. Null when no stamped file has one.
177
+ */
178
+ export function detectManagedDuplicate(cwd: string): PreflightFinding | null {
179
+ const copies: string[] = [];
180
+ for (const { path: rel, scope } of listStampedFiles(cwd)) {
181
+ if (scope !== "block" || !rel.endsWith(".md")) continue;
182
+ const abs = path.join(cwd, rel);
183
+ if (!fs.existsSync(abs)) continue;
184
+ const content = fs.readFileSync(abs, "utf-8");
185
+ const block = extractManagedBlock(content);
186
+ if (block === null) continue;
187
+ const title = findUnmarkedCopy(stripManagedBlock(content), block);
188
+ if (title === null) continue;
189
+ const lines = content.split("\n");
190
+ const start = lines.indexOf(selectMarkers("html-comment")[0]);
191
+ const end = lines.indexOf(selectMarkers("html-comment")[1]);
192
+ const line = lines.findIndex((l, i) => l === title && (i < start || i > end)) + 1;
193
+ copies.push(`${rel} (\`${title}\` at line ${line})`);
194
+ }
195
+ if (copies.length === 0) return null;
196
+ return {
197
+ id: "bkit-managed-duplicate",
198
+ severity: "advisory",
199
+ detect: `${copies.length} bkit-managed file(s) hold an older bkit copy outside their \`bkit:start\`/\`bkit:end\` block: ${copies.join(", ")}. Install never updates text outside the markers, so agents read that stale copy beside the live block.`,
200
+ action:
201
+ "In each file, delete the old copy: the run of lines starting at the named title line, up to `<!-- bkit:start -->` (or from just after `<!-- bkit:end -->` when the copy sits below). Keep any lines you wrote yourself by moving them below `<!-- bkit:end -->`. Then run `pnpm bkit check` again.",
202
+ };
203
+ }
204
+
165
205
  // ---------------------------------------------------------------------------
166
206
  // Owned hook files — `bkit check` fails when one is missing
167
207
  // ---------------------------------------------------------------------------
@@ -185,15 +185,16 @@ export function runPreflight(
185
185
  const bkitNotOnPath = detectBkitNotOnPath();
186
186
  if (bkitNotOnPath) advisories.push(bkitNotOnPath);
187
187
 
188
- // Missing MCP server advisory — one finding per missing required key, per file.
189
- // Tracker-aware: when issueTracker === "github", only github MCP server is required
190
- // (the Linear gate is a no-op on the GitHub tracker; the gate runs in workflow Step 1 via MCP).
191
- // Extra MCP server advisory — one finding per bkit-managed server that the
188
+ // Missing MCP server advisory — one finding per missing required key, per file: the
189
+ // resolved tracker's own server (none → nothing required), matching what install writes.
190
+ // Extra MCP server advisory — one finding per bkit-written tracker-only server that the
192
191
  // resolved tracker does not use (e.g. a stale `linear` entry under `github`).
192
+ // opencode.json is drift-gated, so only the extra check runs there (map key `mcp`).
193
193
  for (const relPath of [".mcp.json", ".cursor/mcp.json"]) {
194
194
  advisories.push(...detectMissingMcpServers(cwd, relPath, resolvedTracker));
195
195
  advisories.push(...detectExtraMcpServers(cwd, relPath, resolvedTracker));
196
196
  }
197
+ advisories.push(...detectExtraMcpServers(cwd, ".opencode/opencode.json", resolvedTracker, "mcp"));
197
198
 
198
199
  // [mcp-env] detectors run in Phase 3 (runPostInstallCheck in checks/after/index.ts),
199
200
  // not here: the .bkit/.env.example scaffold exists only after writes. Detectors are
@@ -6,24 +6,47 @@ import { parseJson } from "../../shared/json.js";
6
6
  import type { IssueTracker } from "../../install/manifest.js";
7
7
  import type { PreflightFinding } from "./index.js";
8
8
 
9
- // ---------------------------------------------------------------------------
10
- // Advisory: missing MCP server entries in .mcp.json / .cursor/mcp.json
11
- // ---------------------------------------------------------------------------
9
+ /** Every MCP server key bkit writes; `requiredMcpServersForTracker` picks the required subset. */
10
+ const BKIT_MCP_SERVERS: readonly string[] = ["linear", "github"];
12
11
 
13
- /** Every MCP server key bkit manages; `requiredMcpServersForTracker` picks the required subset. */
14
- const REQUIRED_MCP_SERVERS: readonly string[] = ["linear", "github"];
12
+ /**
13
+ * bkit-written servers a workflow step calls under every tracker, so never flagged as extra:
14
+ * the workflows' gh MCP fallback (PR / CI / merge when `gh` is unavailable) calls `github`.
15
+ */
16
+ const TRACKER_INDEPENDENT_MCP_SERVERS: readonly string[] = ["github"];
17
+
18
+ /** The key holding the server map: `mcpServers` in `.mcp.json` / `.cursor/mcp.json`, `mcp` in `.opencode/opencode.json`. */
19
+ export type McpServerMapKey = "mcpServers" | "mcp";
15
20
 
16
21
  /**
17
- * Return the MCP server keys required for a given issue tracker.
18
- *
19
- * - `github` → only `github` MCP server required (Linear gate is a no-op on GitHub tracker).
20
- * - `linear` → both `linear` and `github` required (Linear tracker still dispatches via GitHub PR).
21
- * - `none` → `github` only (tracker calls are no-ops; GitHub surface still needed for PR ops).
22
+ * Return the MCP server keys required for a given issue tracker — exactly the entry the
23
+ * install renderers write: the tracker's own server (`none` → none).
22
24
  */
23
25
  export function requiredMcpServersForTracker(tracker: IssueTracker): readonly string[] {
24
- if (tracker === "github") return ["github"];
25
- if (tracker === "linear") return ["linear", "github"];
26
- return ["github"]; // none — only GitHub for PR surface
26
+ return tracker === "none" ? [] : [tracker];
27
+ }
28
+
29
+ /**
30
+ * Read the server map under `mapKey` of the JSON file at `relPath`.
31
+ * `undefined` → file absent or malformed (callers skip); `null` → file present, no map.
32
+ */
33
+ function readMcpServerMap(
34
+ cwd: string,
35
+ relPath: string,
36
+ mapKey: McpServerMapKey,
37
+ ): Record<string, unknown> | null | undefined {
38
+ const absPath = path.join(cwd, relPath);
39
+ if (!fs.existsSync(absPath)) return undefined;
40
+ const parsed = parseJson(fs.readFileSync(absPath, "utf-8"));
41
+ if (!parsed.ok || typeof parsed.value !== "object" || parsed.value === null) return undefined;
42
+ const map = (parsed.value as Record<string, unknown>)[mapKey];
43
+ return map !== null && typeof map === "object" && !Array.isArray(map)
44
+ ? (map as Record<string, unknown>)
45
+ : null;
46
+ }
47
+
48
+ function advisoryPathSlug(relPath: string): string {
49
+ return relPath.replace(/[^a-z0-9]/gi, "-");
27
50
  }
28
51
 
29
52
  /**
@@ -44,22 +67,11 @@ export function detectMissingMcpServers(
44
67
  relPath: string,
45
68
  issueTracker: IssueTracker,
46
69
  ): PreflightFinding[] {
47
- const absPath = path.join(cwd, relPath);
48
- if (!fs.existsSync(absPath)) return [];
49
-
50
- const parsed = parseJson(fs.readFileSync(absPath, "utf-8"));
51
- if (!parsed.ok || typeof parsed.value !== "object" || parsed.value === null) return []; // malformed JSON — skip silently
52
- const doc = parsed.value as Record<string, unknown>;
53
-
54
- const mcpServers =
55
- doc.mcpServers !== null && typeof doc.mcpServers === "object" && !Array.isArray(doc.mcpServers)
56
- ? (doc.mcpServers as Record<string, unknown>)
57
- : null;
58
-
59
- const requiredServers = requiredMcpServersForTracker(issueTracker);
70
+ const mcpServers = readMcpServerMap(cwd, relPath, "mcpServers");
71
+ if (mcpServers === undefined) return [];
60
72
 
61
73
  const findings: PreflightFinding[] = [];
62
- for (const key of requiredServers) {
74
+ for (const key of requiredMcpServersForTracker(issueTracker)) {
63
75
  if (mcpServers && Object.prototype.hasOwnProperty.call(mcpServers, key)) continue;
64
76
  const urlHint =
65
77
  key === "linear"
@@ -68,7 +80,7 @@ export function detectMissingMcpServers(
68
80
  ? `"url": "https://api.githubcopilot.com/mcp/"`
69
81
  : `"url": "<server-url>"`;
70
82
  findings.push({
71
- id: `mcp-missing-server-${key}-${relPath.replace(/[^a-z0-9]/gi, "-")}`,
83
+ id: `mcp-missing-server-${key}-${advisoryPathSlug(relPath)}`,
72
84
  severity: "advisory",
73
85
  detect: `${relPath} is missing the ${key} MCP server in mcpServers.`,
74
86
  action: `[mcp] ${relPath} is missing the ${key} MCP server. Add it to mcpServers: {"${key}": {${urlHint}}}`,
@@ -78,17 +90,21 @@ export function detectMissingMcpServers(
78
90
  }
79
91
 
80
92
  /**
81
- * Advisory: one finding per bkit-managed MCP server that is present in the file
82
- * but NOT required by the resolved tracker (the symmetric counterpart to
83
- * `detectMissingMcpServers`). Catches the stale-leftover case — e.g. a repo
84
- * switched to `--tracker=github` but still carries the `linear` entry.
93
+ * Advisory: one finding per bkit-written MCP server that is present in the file but NOT
94
+ * required by the resolved tracker (the symmetric counterpart to `detectMissingMcpServers`).
95
+ * Catches the stale-leftover case — e.g. a repo switched to `--tracker=github` but still
96
+ * carrying the `linear` entry.
97
+ *
98
+ * Only flags tracker-only servers bkit itself writes (`BKIT_MCP_SERVERS` minus
99
+ * `TRACKER_INDEPENDENT_MCP_SERVERS`). Consumer-added MCP servers (custom tooling, other
100
+ * providers) are never flagged for removal.
85
101
  *
86
- * Only flags servers bkit itself manages (`REQUIRED_MCP_SERVERS`). Consumer-added
87
- * MCP servers (custom tooling, other providers) are never flagged for removal.
102
+ * `mapKey` names the server map: `mcpServers` (`.mcp.json`, `.cursor/mcp.json`) or `mcp`
103
+ * (`.opencode/opencode.json`).
88
104
  *
89
105
  * Semantics:
90
- * - File absent / malformed / no mcpServers → return []
91
- * - bkit-managed server present but not in `requiredMcpServersForTracker(tracker)` → one advisory
106
+ * - File absent / malformed / no server map → return []
107
+ * - tracker-only server present but not in `requiredMcpServersForTracker(tracker)` → one advisory
92
108
  *
93
109
  * Follows `[context] Message` advisory format.
94
110
  */
@@ -96,31 +112,21 @@ export function detectExtraMcpServers(
96
112
  cwd: string,
97
113
  relPath: string,
98
114
  issueTracker: IssueTracker,
115
+ mapKey: McpServerMapKey = "mcpServers",
99
116
  ): PreflightFinding[] {
100
- const absPath = path.join(cwd, relPath);
101
- if (!fs.existsSync(absPath)) return [];
102
-
103
- const parsed = parseJson(fs.readFileSync(absPath, "utf-8"));
104
- if (!parsed.ok || typeof parsed.value !== "object" || parsed.value === null) return []; // malformed JSON — skip silently
105
- const doc = parsed.value as Record<string, unknown>;
106
-
107
- const mcpServers =
108
- doc.mcpServers !== null && typeof doc.mcpServers === "object" && !Array.isArray(doc.mcpServers)
109
- ? (doc.mcpServers as Record<string, unknown>)
110
- : null;
111
- if (!mcpServers) return [];
117
+ const servers = readMcpServerMap(cwd, relPath, mapKey);
118
+ if (!servers) return [];
112
119
 
113
120
  const allowed = requiredMcpServersForTracker(issueTracker);
114
121
  const findings: PreflightFinding[] = [];
115
- // Only consider servers bkit manages — never flag consumer-added MCP servers.
116
- for (const key of REQUIRED_MCP_SERVERS) {
117
- if (allowed.includes(key)) continue;
118
- if (!Object.prototype.hasOwnProperty.call(mcpServers, key)) continue;
122
+ for (const key of BKIT_MCP_SERVERS) {
123
+ if (allowed.includes(key) || TRACKER_INDEPENDENT_MCP_SERVERS.includes(key)) continue;
124
+ if (!Object.prototype.hasOwnProperty.call(servers, key)) continue;
119
125
  findings.push({
120
- id: `mcp-extra-server-${key}-${relPath.replace(/[^a-z0-9]/gi, "-")}`,
126
+ id: `mcp-extra-server-${key}-${advisoryPathSlug(relPath)}`,
121
127
  severity: "advisory",
122
128
  detect: `${relPath} has the ${key} MCP server but the ${issueTracker} tracker does not use it.`,
123
- action: `[mcp] ${relPath} carries the ${key} MCP server, which is not used by the ${issueTracker} tracker. Remove the "${key}" entry from mcpServers.`,
129
+ action: `[mcp] ${relPath} carries the ${key} MCP server, which is not used by the ${issueTracker} tracker. Remove the "${key}" entry from ${mapKey}.`,
124
130
  });
125
131
  }
126
132
  return findings;
@@ -2,7 +2,7 @@
2
2
  //
3
3
  // A fail-open advisory that compares the set of ship steps RECORDED in a
4
4
  // status.jsonl against the set of steps the workflow PROSE says should be
5
- // there. It derives its expected set from .bkit/workflows/bkit-ship.md at
5
+ // there. It derives its expected set from .bkit/core/workflows/bkit-ship.md at
6
6
  // runtime (headings + step:"ship-*" literals) — NEVER a hand-maintained table
7
7
  // (decision 384-tier3-promotion).
8
8
  //