@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
@@ -0,0 +1,174 @@
1
+ // checks/tips/index.ts — collect the firing setup tips and render them for `bkit tips`, the
2
+ // console checklist and `.bkit/advisories.md`. Catalogue + priority: ./catalogue.ts.
3
+
4
+ import type { PreflightFinding } from "../before/index.js";
5
+ import {
6
+ ignoredAdvisoryIds,
7
+ type SuppressionNote,
8
+ type SuppressionReporter,
9
+ } from "../after/suppression.js";
10
+ import type { ComplyPhase } from "../../cli.js";
11
+ import { SETUP_TIPS, type SetupTip } from "./catalogue.js";
12
+
13
+ /** Tips `bkit tips` prints without `--all` or `--workflow`. */
14
+ export const TIPS_CAP = 3;
15
+
16
+ /** Tips a workflow prints at its close (`bkit tips --workflow=<name>`). */
17
+ export const WORKFLOW_TIPS_CAP = 1;
18
+
19
+ /** Section heading in the console checklist and `.bkit/advisories.md`. */
20
+ export const SETUP_TIPS_HEADING = "Setup tips";
21
+
22
+ /** Opening line of `bkit tips` output, by how many tips it prints. */
23
+ export const tipsIntro = (n: number) =>
24
+ n === 1 ? "Setup tip for a smoother next run:" : "Setup tips for a smoother next run:";
25
+
26
+ /** Where the full tip list lives. */
27
+ export const TIPS_DETAILS_POINTER =
28
+ "Details for every tip: .bkit/advisories.md § Setup tips (refreshed by `bkit check`).";
29
+
30
+ /** Intro of the Setup tips section: who reads which field, and how to silence a tip. */
31
+ export const TIPS_SECTION_INTRO =
32
+ "Things not set up yet, most useful first. For the person: each tip says what goes wrong today and a sentence to ask your agent. For an AI agent: follow each tip's Agent steps unless the person declines it. Silence a tip by adding its id to `bkit.ignoreAdvisories` in package.json. Full template catalogue: .bkit/templates.md.";
33
+
34
+ /** True when advisory `id` matches catalogue pattern `pattern` (trailing `*` = prefix). */
35
+ export function matchesAdvisory(pattern: string, id: string): boolean {
36
+ return pattern.endsWith("*") ? id.startsWith(pattern.slice(0, -1)) : id === pattern;
37
+ }
38
+
39
+ /** True when `ignored` names the tip's id or any advisory id it reuses. */
40
+ export function isTipSilenced(tip: SetupTip, ignored: ReadonlySet<string>): boolean {
41
+ if (ignored.has(tip.id)) return true;
42
+ const patterns = tip.advisories ?? [];
43
+ return [...ignored].some((id) => patterns.some((p) => matchesAdvisory(p, id)));
44
+ }
45
+
46
+ export interface TipsResult {
47
+ /** Firing tips, in priority order. */
48
+ tips: SetupTip[];
49
+ /** Firing tips the root `bkit.ignoreAdvisories` silenced. */
50
+ suppressed: SuppressionNote[];
51
+ }
52
+
53
+ /** Every firing tip in priority order, minus the ones the root package.json silences. */
54
+ export function collectTips(cwd: string, catalogue: readonly SetupTip[] = SETUP_TIPS): TipsResult {
55
+ const ignored = ignoredAdvisoryIds(cwd);
56
+ const tips: SetupTip[] = [];
57
+ const suppressed: SuppressionNote[] = [];
58
+ for (const tip of catalogue) {
59
+ if (!tip.fires(cwd)) continue;
60
+ if (isTipSilenced(tip, ignored)) suppressed.push({ id: tip.id, scope: "." });
61
+ else tips.push(tip);
62
+ }
63
+ return { tips, suppressed };
64
+ }
65
+
66
+ /**
67
+ * Drop advisory findings whose tip the root package.json silenced, so one
68
+ * `bkit.ignoreAdvisories` entry silences a tip and the advisories it reuses. Blockers are
69
+ * never dropped.
70
+ */
71
+ export function dropTipSilencedAdvisories(
72
+ findings: PreflightFinding[],
73
+ cwd: string,
74
+ onSuppressed?: SuppressionReporter,
75
+ catalogue: readonly SetupTip[] = SETUP_TIPS,
76
+ ): PreflightFinding[] {
77
+ const ignored = ignoredAdvisoryIds(cwd);
78
+ if (ignored.size === 0) return findings;
79
+ const patterns = catalogue
80
+ .filter((tip) => isTipSilenced(tip, ignored))
81
+ .flatMap((tip) => tip.advisories ?? []);
82
+ return findings.filter((f) => {
83
+ if (f.severity !== "advisory" || !patterns.some((p) => matchesAdvisory(p, f.id))) return true;
84
+ onSuppressed?.({ id: f.id, scope: "." });
85
+ return false;
86
+ });
87
+ }
88
+
89
+ /** One tip as numbered terminal lines: title, then line, ask and caution indented. */
90
+ function tipTextLines(tip: SetupTip, n: number): string[] {
91
+ const lines = [`${n}. ${tip.title}`, ` ${tip.line}`, ` Ask your agent: "${tip.ask}"`];
92
+ if (tip.caution) lines.push(` Caution: ${tip.caution}`);
93
+ return lines;
94
+ }
95
+
96
+ /** One tip as markdown paragraphs for a workflow's `## Setup Tips` section. */
97
+ function tipMarkdownLines(tip: SetupTip): string[] {
98
+ const lines = [`**${tip.title}.** ${tip.line}`, "", `Ask your agent: "${tip.ask}"`];
99
+ if (tip.caution) lines.push("", `Caution: ${tip.caution}`);
100
+ return lines;
101
+ }
102
+
103
+ /**
104
+ * `tips` with the ones that matter in `workflow` first, each group in catalogue order.
105
+ * Comms tips name every workflow, so they stay first everywhere.
106
+ */
107
+ export function orderForWorkflow(tips: readonly SetupTip[], workflow: ComplyPhase): SetupTip[] {
108
+ const own = tips.filter((t) => t.workflows?.includes(workflow));
109
+ return [...own, ...tips.filter((t) => !own.includes(t))];
110
+ }
111
+
112
+ /**
113
+ * `bkit tips` output, then where the rest live. `""` when no tip fires.
114
+ * - `workflow`: the `WORKFLOW_TIPS_CAP` tips that matter most in that workflow, as
115
+ * markdown paragraphs with no intro or numbers — the workflow appends them under its
116
+ * own `## Setup Tips` heading.
117
+ * - neither: the top `TIPS_CAP` tips as a numbered terminal list.
118
+ * - `all`: every tip as a numbered list (in the workflow's order when `workflow` is set).
119
+ */
120
+ export function formatTips(
121
+ tips: readonly SetupTip[],
122
+ opts: { all?: boolean; workflow?: ComplyPhase | null } = {},
123
+ ): string {
124
+ if (tips.length === 0) return "";
125
+ const ordered = opts.workflow ? orderForWorkflow(tips, opts.workflow) : [...tips];
126
+ const cap = opts.workflow ? WORKFLOW_TIPS_CAP : TIPS_CAP;
127
+ const shown = opts.all ? ordered : ordered.slice(0, cap);
128
+ const rest = tips.length - shown.length;
129
+ const more = rest > 0 ? `${rest} more: \`bkit tips --all\`. ` : "";
130
+
131
+ if (opts.workflow && !opts.all) {
132
+ const lines: string[] = [];
133
+ for (const tip of shown) lines.push(...tipMarkdownLines(tip), "");
134
+ lines.push(`${more}${TIPS_DETAILS_POINTER}`);
135
+ return lines.join("\n");
136
+ }
137
+
138
+ const lines = [tipsIntro(shown.length), ""];
139
+ shown.forEach((tip, i) => lines.push(...tipTextLines(tip, i + 1), ""));
140
+ if (more) lines.push(more.trimEnd());
141
+ lines.push(TIPS_DETAILS_POINTER);
142
+ return lines.join("\n");
143
+ }
144
+
145
+ /** The Setup tips block of the console checklist. `[]` when no tip fires. */
146
+ export function setupTipsChecklistLines(tips: readonly SetupTip[]): string[] {
147
+ if (tips.length === 0) return [];
148
+ const lines = [`--- ${SETUP_TIPS_HEADING} ---`, TIPS_SECTION_INTRO, ""];
149
+ tips.forEach((tip, i) => {
150
+ lines.push(`${i + 1}. ${tip.title} (${tip.id})`);
151
+ lines.push(` ${tip.line}`);
152
+ lines.push(` Why: ${tip.why}`);
153
+ if (tip.caution) lines.push(` Caution: ${tip.caution}`);
154
+ lines.push(` Ask your agent: "${tip.ask}"`);
155
+ lines.push(` Agent steps: ${tip.steps}`);
156
+ lines.push("");
157
+ });
158
+ return lines;
159
+ }
160
+
161
+ /** The `## Setup tips` section of `.bkit/advisories.md`. `[]` when no tip fires. */
162
+ export function setupTipsMarkdownLines(tips: readonly SetupTip[]): string[] {
163
+ if (tips.length === 0) return [];
164
+ const lines = [`## ${SETUP_TIPS_HEADING}`, "", `> ${TIPS_SECTION_INTRO}`, ""];
165
+ tips.forEach((tip, i) => {
166
+ lines.push(`### ${i + 1}. ${tip.title} (\`${tip.id}\`)`, "");
167
+ lines.push(tip.line, "");
168
+ lines.push(`**Why:** ${tip.why}`, "");
169
+ if (tip.caution) lines.push(`**Caution:** ${tip.caution}`, "");
170
+ lines.push(`**Ask your agent:** "${tip.ask}"`, "");
171
+ lines.push(`**Agent steps:** ${tip.steps}`, "");
172
+ });
173
+ return lines;
174
+ }
@@ -14,13 +14,15 @@ import { runComplyCommand } from "./commands/comply.js";
14
14
  import { runHarvestCommand } from "./commands/harvest.js";
15
15
  import { runAnalysisCommand } from "./commands/analysis.js";
16
16
  import { runTelemetryCommand } from "./commands/telemetry.js";
17
+ import { runTipsCommand } from "./commands/tips.js";
17
18
  import { runUpgradeCommand } from "./commands/install/upgrade.js";
18
19
  import { runUninstallCommand } from "./commands/install/uninstall.js";
19
20
  import { runInstall } from "./commands/install/install.js";
20
21
  import { OPTIN_MODULES } from "./install/manifest.js";
21
22
  import { OPENCODE_PROVIDERS } from "./shared/egress.js";
22
23
 
23
- export type ModuleFlag = "core" | "claude" | "cursor" | "opencode" | "codex" | "cloud";
24
+ export type ModuleFlag =
25
+ "core" | "claude" | "cursor" | "opencode" | "codex" | "antigravity" | "cloud";
24
26
 
25
27
  /** Cloud-agent variant chosen via `--auto=<variant>`. */
26
28
  export const CLOUD_VARIANTS = ["claude", "cursor", "opencode"] as const;
@@ -48,6 +50,7 @@ export const CLASSIC_VERBS: ReadonlySet<string> = new Set([
48
50
  "harvest",
49
51
  "analysis",
50
52
  "telemetry",
53
+ "tips",
51
54
  "cursor",
52
55
  "opencode",
53
56
  "help",
@@ -66,6 +69,7 @@ export type Verb =
66
69
  | "harvest"
67
70
  | "analysis"
68
71
  | "telemetry"
72
+ | "tips"
69
73
  | "help";
70
74
 
71
75
  // ---------------------------------------------------------------------------
@@ -118,7 +122,7 @@ export interface ParsedArgs {
118
122
  upgradeFlags: UpgradeFlags;
119
123
  /** Issue tracker selected via `--tracker=<name>`. null = not specified (use manifest field or default). */
120
124
  tracker: IssueTracker | null;
121
- /** Cloud variant selected via `--auto=claude|cursor`. null = not specified. */
125
+ /** Cloud variant selected via `--auto=<variant>` (see CLOUD_VARIANTS). null = not specified. */
122
126
  cloudVariant: CloudVariant | null;
123
127
  /**
124
128
  * opencode provider selected via `--opencode=<provider>`. null = not specified.
@@ -138,6 +142,10 @@ export interface ParsedArgs {
138
142
  * Only populated when verb === "telemetry". null = not specified / not applicable.
139
143
  */
140
144
  telemetrySubverb: TelemetrySubverb | null;
145
+ /** `bkit tips --all`: print every firing tip, not just the top three. */
146
+ tipsAll: boolean;
147
+ /** `bkit tips --workflow=<name>`: the workflow whose tips go first; it prints one. */
148
+ tipsWorkflow: ComplyPhase | null;
141
149
  }
142
150
 
143
151
  export interface UninstallFlags {
@@ -167,9 +175,9 @@ export interface UpgradeFlags {
167
175
  // Bare module-flag tokens accepted on the CLI. `opencode` (value-bearing) is
168
176
  // intercepted by a dedicated branch in parseArgs before this set is consulted; the
169
177
  // generic check only ever validates claude/cursor/codex. `full`, `core` and `cloud`
170
- // are NOT accepted as bare flags: use `--auto=<claude|cursor>`; core is implicit.
178
+ // are NOT accepted as bare flags: use `--auto=<variant>`; core is implicit.
171
179
  // There is no dependency-updater flag. Copy an example; CI warns when none is present.
172
- const MODULE_FLAGS = new Set<ModuleFlag>(["claude", "cursor", "opencode", "codex"]);
180
+ const MODULE_FLAGS = new Set<ModuleFlag>(["claude", "cursor", "opencode", "codex", "antigravity"]);
173
181
 
174
182
  // ALL_MODULES — every non-opt-in module, core first. Used to expand a bare/full
175
183
  // uninstall (which additionally pulls in the opt-in add-ons below for zero footprint).
@@ -261,6 +269,9 @@ export function parseArgs(argv: string[]): ParsedArgs {
261
269
  } else if (firstArg === "telemetry") {
262
270
  verb = "telemetry";
263
271
  args.shift();
272
+ } else if (firstArg === "tips") {
273
+ verb = "tips";
274
+ args.shift();
264
275
  } else if (firstArg === "cursor" || firstArg === "opencode") {
265
276
  verb = firstArg as Verb;
266
277
  args.shift();
@@ -288,6 +299,8 @@ export function parseArgs(argv: string[]): ParsedArgs {
288
299
  let opencodeProvider: string | null = null;
289
300
  let complyPhase: ComplyPhase | null = null;
290
301
  let telemetrySubverb: TelemetrySubverb | null = null;
302
+ let tipsAll = false;
303
+ let tipsWorkflow: ComplyPhase | null = null;
291
304
 
292
305
  // For `telemetry` verb: extract the sub-verb from the first remaining positional arg
293
306
  if (verb === "telemetry") {
@@ -362,7 +375,7 @@ export function parseArgs(argv: string[]): ParsedArgs {
362
375
  process.exit(1);
363
376
  }
364
377
 
365
- // Value-bearing flag: --auto=<claude|cursor> — cloud-agent (auto-dispatch) lane;
378
+ // Value-bearing flag: --auto=<variant> (CLOUD_VARIANTS) — cloud-agent (auto-dispatch) lane;
366
379
  // sets the internal `cloud` module. Bare `--auto` (no variant) is accepted only on
367
380
  // uninstall (variant read from package.json).
368
381
  if (flag === "auto") {
@@ -411,6 +424,12 @@ export function parseArgs(argv: string[]): ParsedArgs {
411
424
  );
412
425
  process.exit(1);
413
426
  }
427
+ if (flag.startsWith("antigravity=")) {
428
+ console.error(
429
+ `[bkit] --antigravity takes no value (got ${JSON.stringify("--" + flag)}). Antigravity runs on one gateway (google), so the flag is bare: --antigravity. Only --opencode is provider-pluggable.`,
430
+ );
431
+ process.exit(1);
432
+ }
414
433
  if (flag.startsWith("opencode=")) {
415
434
  const rawValue = flag.slice("opencode=".length);
416
435
  if (!rawValue) {
@@ -430,6 +449,24 @@ export function parseArgs(argv: string[]): ParsedArgs {
430
449
  continue;
431
450
  }
432
451
 
452
+ // Tips-only flags: --all prints every firing tip; --workflow=<name> puts the tips that
453
+ // matter in that workflow first and prints one.
454
+ if (flag === "all" && verb === "tips") {
455
+ tipsAll = true;
456
+ continue;
457
+ }
458
+ if (flag.startsWith("workflow=") && verb === "tips") {
459
+ const value = flag.slice("workflow=".length);
460
+ tipsWorkflow = parseComplyPhase(value);
461
+ if (tipsWorkflow === null) {
462
+ console.error(
463
+ `[bkit] Unknown workflow: "${value}". Valid values: ${COMPLY_PHASES.join(", ")}`,
464
+ );
465
+ process.exit(1);
466
+ }
467
+ continue;
468
+ }
469
+
433
470
  // Uninstall-specific flags (accepted for all verbs that use them)
434
471
  if (flag === "dry-run") {
435
472
  uninstallFlags.dryRun = true;
@@ -524,6 +561,8 @@ export function parseArgs(argv: string[]): ParsedArgs {
524
561
  opencodeProvider,
525
562
  complyPhase,
526
563
  telemetrySubverb,
564
+ tipsAll,
565
+ tipsWorkflow,
527
566
  };
528
567
  }
529
568
 
@@ -535,7 +574,8 @@ Usage:
535
574
  bkit install <module-flags> Install (or re-sync) the named modules + the implicit
536
575
  core foundation. At least one module flag is REQUIRED —
537
576
  a bare \`bkit install\` errors (name the modules below).
538
- Hosts compose: --claude --cursor --codex --opencode=<provider>.
577
+ Hosts compose: --claude --cursor --codex --antigravity
578
+ --opencode=<provider>.
539
579
  bkit check Dry-run — drift-check everything already installed (no
540
580
  module flags). Exits 1 when a managed file needs
541
581
  re-rendering. Copies under .bkit/templates/ are refreshed by
@@ -562,6 +602,13 @@ Usage:
562
602
  targeted uninstall leaves core untouched.
563
603
  bkit doctor Read-only preflight + post-install advisory replay.
564
604
  Diagnose token surfaces and config drift. Exits 0.
605
+ bkit tips [--workflow=<name>] [--all]
606
+ Setup tips: what this repo has not set up yet, most useful
607
+ first, each with a sentence to ask your agent. Top three
608
+ by default; --workflow=design|plan|build|debug|ship puts
609
+ the tips that matter there first and prints one (each
610
+ workflow runs this at its close); --all lists every one.
611
+ Local checks only. Exits 0.
565
612
  bkit status Read-only host/provider status. Reports current host+provider
566
613
  (sampled from .opencode/opencode.json, .claude/, .cursor/).
567
614
  Writes nothing. Exits 0.
@@ -612,12 +659,12 @@ Usage:
612
659
 
613
660
  Core (implicit — no flag; installed/upgraded on every install):
614
661
  AGENTS.md (cross-host dispatch router), .agents/rules.md + .agents/context.md +
615
- .agents/docs.md + .agents/skills.md managed blocks, .gitignore + .gitattributes managed
616
- blocks, docs/, .bkit/*.md, .bkit/version, the template copies in .bkit/templates/, and
617
- the bkit:gate:* / bkit:deps:* package.json scripts every workflow runs (added when
618
- missing, never overwritten, left by uninstall). The tool scripts those gates chain
619
- (typecheck, lint, format:check, lint:prose, slop:delta) and their devDeps are yours
620
- to add: see .bkit/templates.md.
662
+ .agents/docs.md + .agents/shortcuts.md + .agents/skills.md managed blocks, .gitignore +
663
+ .gitattributes managed blocks, docs/, .bkit/*.md, .bkit/version, the template copies in
664
+ .bkit/templates/, and the bkit:gate:* / bkit:deps:* package.json scripts every workflow
665
+ runs (added when missing, never overwritten, left by uninstall). The tool scripts those
666
+ gates chain (typecheck, lint, format:check, lint:prose, slop:delta) and their devDeps are
667
+ yours to add: see .bkit/templates.md.
621
668
 
622
669
  Module flags (composable; symmetric install ↔ uninstall):
623
670
  --claude .claude/agents/ + .claude/commands/ (byte-identical mirror) + CLAUDE.md
@@ -631,14 +678,22 @@ Module flags (composable; symmetric install ↔ uninstall):
631
678
  Provider value is REQUIRED. Supported: openrouter, ollama,
632
679
  opencode-zen, opencode-go (opencode-native gateways;
633
680
  auth via BKIT_OPENCODE_API_KEY).
634
- Ships .opencode/** (agents, commands, opencode.json, bkit-gateguard.js).
681
+ Ships .opencode/** (agents, commands, opencode.json, bkit-gateguard.js,
682
+ bkit-readguard.js).
635
683
  Configure your provider key; verify with \`bkit doctor\`. All installed
636
684
  providers tracked in bkit.opencodeProviders.
637
685
  --codex Codex CLI host. BARE flag — takes no value: Codex runs on one gateway
638
686
  (openai), so only --opencode is provider-pluggable. Ships .codex/agents/*.toml
639
- + .codex/hooks.json + .codex/hooks/bkit-gateguard.cjs, plus the workflow skills
640
- (.agents/skills/bkit-*/). Codex loads project-local hooks ONLY once the
641
- .codex/ layer is trusted — until then GateGuard is installed and never fires.
687
+ + .codex/hooks.json + .codex/hooks/bkit-{gateguard,guardrails,readguard}.cjs,
688
+ plus the workflow skills (.agents/skills/bkit-*/). Codex loads project-local
689
+ hooks ONLY once the .codex/ layer is trusted — until then they never fire.
690
+ --antigravity Google Antigravity IDE host. BARE flag — takes no value: Antigravity runs
691
+ on one gateway (google). Installs as a workspace PLUGIN at
692
+ .agents/plugins/bkit/ — plugin.json + skills/bkit-*/SKILL.md (workflow
693
+ skills) + agents/bkit-*.md (subagent prompts) + hooks.json + hooks/*.cjs,
694
+ keeping .agents/ root Codex's. Plus root GEMINI.md. There is no native
695
+ subagent tool: the orchestrator loads each prompt with view_file and runs
696
+ it in-session.
642
697
 
643
698
  Dependency updaters (copy an example and own it):
644
699
  .bkit/templates/.github/renovate.json5
@@ -682,6 +737,8 @@ Uninstall flags:
682
737
  Examples:
683
738
  bkit install --claude .claude/** + CLAUDE.md + core.
684
739
  bkit install --claude --cursor Both hosts + core.
740
+ bkit install --codex Codex CLI host (agents + workflow skills + hooks).
741
+ bkit install --antigravity Google Antigravity host (workspace plugin under .agents/plugins/bkit/ + GEMINI.md).
685
742
  bkit install --opencode=opencode-zen opencode host (Zen built-in gateway, additive).
686
743
  bkit install --opencode=opencode-go opencode host (Go built-in gateway, additive).
687
744
  bkit install --opencode=openrouter add openrouter alongside an opencode gateway.
@@ -736,8 +793,8 @@ export function validateModuleFlagsForVerb(
736
793
  if (verb === "install" && moduleFlags.size === 0) {
737
794
  return (
738
795
  "[bkit] `bkit install` requires at least one module flag. Name what to install: " +
739
- "--claude, --cursor, --codex, --opencode=<provider> (plus opt-in " +
740
- "--auto=<claude|cursor>). Run `bkit help` for usage."
796
+ "--claude, --cursor, --codex, --antigravity, --opencode=<provider> (plus opt-in " +
797
+ `--auto=<${CLOUD_VARIANTS.join("|")}>). Run \`bkit help\` for usage.`
741
798
  );
742
799
  }
743
800
  if ((verb === "check" || verb === "upgrade") && moduleFlags.size > 0) {
@@ -774,6 +831,8 @@ export async function main() {
774
831
  opencodeProvider,
775
832
  complyPhase,
776
833
  telemetrySubverb,
834
+ tipsAll,
835
+ tipsWorkflow,
777
836
  } = parseArgs(process.argv.slice(2));
778
837
 
779
838
  // A bare `bkit` (no arguments) means no command was given: print usage and exit non-zero
@@ -809,6 +868,11 @@ export async function main() {
809
868
  return;
810
869
  }
811
870
 
871
+ if (verb === "tips") {
872
+ runTipsCommand(tipsAll, tipsWorkflow);
873
+ return;
874
+ }
875
+
812
876
  // Launcher verbs — exec the GUI app binary with .bkit/.env merged into the env
813
877
  // so that MCP token placeholders (BKIT_GH_TOKEN, BKIT_OPENCODE_API_KEY, …) resolve correctly
814
878
  // even when launched from the Dock/Finder (macOS GUI-isolation).
@@ -30,6 +30,8 @@ export function detectInstalledModules(cwd: string): Set<ModuleFlag> {
30
30
  if (fs.existsSync(path.join(cwd, ".cursor", "agents"))) mods.add("cursor");
31
31
  if (fs.existsSync(path.join(cwd, ".opencode", "agents"))) mods.add("opencode");
32
32
  if (fs.existsSync(path.join(cwd, ".codex", "agents"))) mods.add("codex");
33
+ if (fs.existsSync(path.join(cwd, ".agents", "plugins", "bkit", "plugin.json")))
34
+ mods.add("antigravity");
33
35
  return mods;
34
36
  }
35
37
 
@@ -19,6 +19,7 @@ import {
19
19
  writeAdvisoriesArtifact,
20
20
  } from "../../checks/after/index.js";
21
21
  import type { SuppressionNote } from "../../checks/after/suppression.js";
22
+ import { collectTips } from "../../checks/tips/index.js";
22
23
  import { parseDotenv } from "../../install/cloud-env.js";
23
24
 
24
25
  /**
@@ -97,6 +98,11 @@ export function runStatus(cwd: string, logPrefix: string): void {
97
98
  const codexDir = path.join(cwd, ".codex");
98
99
  const codexPresent = fs.existsSync(codexDir);
99
100
 
101
+ // --- antigravity host ---
102
+ const antigravityPresent = fs.existsSync(
103
+ path.join(cwd, ".agents", "plugins", "bkit", "plugin.json"),
104
+ );
105
+
100
106
  const opencodeStatus = opencodePresent
101
107
  ? `INSTALLED (${providerLabel}: ${opencodeProviderDisplay} / model: ${opencodeModel})`
102
108
  : "absent (run: bkit install --opencode=<provider>)";
@@ -104,6 +110,9 @@ export function runStatus(cwd: string, logPrefix: string): void {
104
110
  console.log(
105
111
  `${logPrefix} codex: ${codexPresent ? "INSTALLED (provider: openai)" : "absent (run: bkit install --codex)"}`,
106
112
  );
113
+ console.log(
114
+ `${logPrefix} antigravity: ${antigravityPresent ? "INSTALLED (provider: google)" : "absent (run: bkit install --antigravity)"}`,
115
+ );
107
116
 
108
117
  // --- summary ---
109
118
  const installedHosts = [
@@ -111,6 +120,7 @@ export function runStatus(cwd: string, logPrefix: string): void {
111
120
  cursorPresent ? "cursor" : null,
112
121
  opencodePresent ? "opencode" : null,
113
122
  codexPresent ? "codex" : null,
123
+ antigravityPresent ? "antigravity" : null,
114
124
  ].filter(Boolean);
115
125
  console.log(
116
126
  `${logPrefix} Installed hosts: ${installedHosts.length > 0 ? installedHosts.join(", ") : "none"}`,
@@ -148,7 +158,9 @@ export async function runDoctor(
148
158
  }
149
159
  }
150
160
 
151
- const banner = formatChecklist(allFindings, suppressed);
161
+ const { tips, suppressed: suppressedTips } = collectTips(process.cwd());
162
+ suppressed.push(...suppressedTips);
163
+ const banner = formatChecklist(allFindings, suppressed, tips);
152
164
  if (banner) {
153
165
  console.log(banner);
154
166
  } else {
@@ -160,6 +172,7 @@ export async function runDoctor(
160
172
  version: getInstallingVersion(),
161
173
  logPrefix: LOG_PREFIX,
162
174
  suppressed,
175
+ tips,
163
176
  });
164
177
 
165
178
  // opencode host diagnostics: report required tools and cred presence per provider.
@@ -16,7 +16,7 @@ import {
16
16
  import { LOG_PREFIX, setLogPrefix } from "../../shared/log-prefix.js";
17
17
  import type { ParsedArgs } from "../../cli.js";
18
18
  import { detectInstalledModules, reportCheckDrift } from "./check.js";
19
- import { runPreflight } from "../../checks/before/index.js";
19
+ import { runPreflight, type PreflightFinding } from "../../checks/before/index.js";
20
20
  import {
21
21
  formatChecklist,
22
22
  readChangelogVersionDelta,
@@ -24,6 +24,7 @@ import {
24
24
  writeAdvisoriesArtifact,
25
25
  } from "../../checks/after/index.js";
26
26
  import type { SuppressionNote } from "../../checks/after/suppression.js";
27
+ import { collectTips } from "../../checks/tips/index.js";
27
28
  import { findMissingOwnedHooks, detectOwnedHookMissing } from "../../checks/after/managed.js";
28
29
  import { resolveTokens } from "../../install/placeholders.js";
29
30
  import {
@@ -31,6 +32,7 @@ import {
31
32
  parseModelLookup,
32
33
  applyModelOverrides,
33
34
  buildOpencodeModelLookup,
35
+ buildAntigravityModelLookup,
34
36
  parseEffortMap,
35
37
  } from "../../render/models.js";
36
38
  import { getBkitDocsRoot } from "../../shared/package-roots.js";
@@ -116,6 +118,7 @@ export function modulesToCliFlags(
116
118
  if (mods.has("cursor")) out.push("--cursor");
117
119
  if (mods.has("opencode")) out.push(`--opencode=${opencodeProvider ?? "<provider>"}`);
118
120
  if (mods.has("codex")) out.push("--codex");
121
+ if (mods.has("antigravity")) out.push("--antigravity");
119
122
  if (mods.has("cloud")) out.push(`--auto=${cloudVariant ?? "<variant>"}`);
120
123
  return out.join(" ");
121
124
  }
@@ -220,6 +223,26 @@ export function detectOpencodeProviders(cwd: string): string[] {
220
223
  return [];
221
224
  }
222
225
 
226
+ /**
227
+ * Re-run Phase 1 detection after the writes. The Phase 1 advisory seeds (the first
228
+ * `seedCount` entries of `current`) are replaced by the fresh ones; advisories pushed by
229
+ * modules during dispatch are kept. Fresh blockers are returned so the caller fails on them.
230
+ */
231
+ export function refreshPreflightAfterWrites(
232
+ modules: Set<ModuleFlag>,
233
+ cwd: string,
234
+ issueTracker: IssueTracker | undefined,
235
+ seedCount: number,
236
+ current: PreflightFinding[],
237
+ ): { advisories: PreflightFinding[]; blockers: PreflightFinding[] } {
238
+ const moduleAdvisories = current.slice(seedCount);
239
+ const fresh = runPreflight(modules, cwd, undefined, issueTracker);
240
+ return {
241
+ advisories: [...fresh.advisories, ...moduleAdvisories],
242
+ blockers: fresh.blockers,
243
+ };
244
+ }
245
+
223
246
  /** `bkit install`, and `bkit check` (the same pipeline, dry-run). */
224
247
  export async function runInstall(
225
248
  args: Pick<
@@ -300,6 +323,7 @@ export async function runInstall(
300
323
  let modelLookup: Map<string, string> = new Map();
301
324
  let opencodeModelLookup: Map<string, string> = new Map();
302
325
  let codexModelLookup: Map<string, string> = new Map();
326
+ let antigravityModelLookup: Map<string, string> = new Map();
303
327
  let effortMap: EffortMap = new Map();
304
328
  const promptsMdPath = path.join(getBkitDocsRoot(), "prompts.md");
305
329
  const consumerPromptsMdPath = path.join(process.cwd(), ".bkit", "prompts.md");
@@ -333,13 +357,20 @@ export async function runInstall(
333
357
  }
334
358
  applyModelOverrides(codexModelLookup, "openai", consumerPromptsMdPath);
335
359
  }
360
+ if (effectiveModules.has("antigravity")) {
361
+ // Antigravity is nullary — one gateway (`google`), so there is nothing to detect.
362
+ try {
363
+ antigravityModelLookup = buildAntigravityModelLookup(promptsMdPath);
364
+ } catch {
365
+ // Not fatal — antigravity module will fail per-file if a model is missing
366
+ }
367
+ applyModelOverrides(antigravityModelLookup, "google", consumerPromptsMdPath);
368
+ }
336
369
  effortMap = parseEffortMap(promptsMdPath);
337
370
  }
338
371
 
339
372
  // Seed preflight advisories into ctx so modules can accumulate into the same list.
340
- const advisories: import("../../checks/before/index.js").PreflightFinding[] = [
341
- ...preflightAdvisories,
342
- ];
373
+ const advisories: PreflightFinding[] = [...preflightAdvisories];
343
374
 
344
375
  const ws: WriteSet = { writes: [] };
345
376
  const postDispatch: Array<() => void> = [];
@@ -426,6 +457,7 @@ export async function runInstall(
426
457
  modelLookup,
427
458
  opencodeModelLookup,
428
459
  codexModelLookup,
460
+ antigravityModelLookup,
429
461
  effortMap,
430
462
  opencodeProvider: renderOpencodeProvider,
431
463
  advisories,
@@ -436,6 +468,13 @@ export async function runInstall(
436
468
  cloudVariant,
437
469
  // Stamped into every rendered agent + command as the managed-version marker.
438
470
  version: getInstallingVersion(),
471
+ // Full host set for this run: dispatched ∪ already-on-disk. Read by the Antigravity
472
+ // module to warn when Codex is also installed (both hosts' `bkit-*` workflow skills
473
+ // then surface in Antigravity's skill selector).
474
+ installedModules: new Set<ModuleFlag>([
475
+ ...effectiveModules,
476
+ ...detectInstalledModules(process.cwd()),
477
+ ]),
439
478
  };
440
479
 
441
480
  // --- Phase 2: Install (current behaviour — dispatch modules) ---
@@ -470,15 +509,17 @@ export async function runInstall(
470
509
  // banner above. `check` (dryRun) wrote nothing, so its Phase 1 findings already describe
471
510
  // the current state and are kept as-is. Module-accumulated advisories (pushed during
472
511
  // dispatch) are preserved; only the Phase 1 seeds are replaced, in their original order.
512
+ let postWriteBlockers: PreflightFinding[] = [];
473
513
  if (!dryRun) {
474
- const moduleAdvisories = advisories.slice(preflightAdvisories.length);
475
- const { advisories: freshPreflightAdvisories } = runPreflight(
514
+ const refreshed = refreshPreflightAfterWrites(
476
515
  effectiveModules,
477
516
  process.cwd(),
478
- undefined,
479
517
  issueTracker,
518
+ preflightAdvisories.length,
519
+ advisories,
480
520
  );
481
- ctx.advisories = [...freshPreflightAdvisories, ...moduleAdvisories];
521
+ ctx.advisories = refreshed.advisories;
522
+ postWriteBlockers = refreshed.blockers;
482
523
  }
483
524
 
484
525
  // --- Phase 3: Post-install checks (re-detect + unified output) ---
@@ -497,12 +538,20 @@ export async function runInstall(
497
538
  }
498
539
  const suppressed: SuppressionNote[] = [];
499
540
  const postFindings = runPostInstallCheck(ctx.advisories, process.cwd(), suppressed);
541
+ if (postWriteBlockers.length > 0) {
542
+ console.log(
543
+ `${LOG_PREFIX} Preflight blockers appeared after the writes — files are already written; fix the blocker and re-run.`,
544
+ );
545
+ postFindings.unshift(...postWriteBlockers);
546
+ }
500
547
  // check only: install has just written every hook file of the modules it dispatched, and a
501
548
  // missing bkit-cloud-bootstrap.sh after `install --claude` is not that run's fault.
502
549
  const missingHooks = dryRun ? findMissingOwnedHooks(process.cwd(), effectiveModules) : [];
503
550
  const missingHooksFinding = detectOwnedHookMissing(missingHooks);
504
551
  if (missingHooksFinding) postFindings.push(missingHooksFinding);
505
- const banner = formatChecklist(postFindings, suppressed);
552
+ const { tips, suppressed: suppressedTips } = collectTips(process.cwd());
553
+ suppressed.push(...suppressedTips);
554
+ const banner = formatChecklist(postFindings, suppressed, tips);
506
555
  if (banner) console.log(banner);
507
556
  writeAdvisoriesArtifact(postFindings, {
508
557
  cwd: process.cwd(),
@@ -510,6 +559,7 @@ export async function runInstall(
510
559
  version: getInstallingVersion(),
511
560
  logPrefix: LOG_PREFIX,
512
561
  suppressed,
562
+ tips,
513
563
  });
514
564
 
515
565
  // Check mode: exit 1 on drift (see reportCheckDrift).