@cbartens/bkit 5.1.0 → 5.2.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 (193) 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 +92 -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 +10 -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/.prettierignore +1 -1
  136. package/.bkit/templates/context/bkit-expo.md +22 -13
  137. package/.bkit/templates/context/bkit-github.md +20 -6
  138. package/.bkit/templates/context/bkit-inngest.md +10 -4
  139. package/.bkit/templates/context/bkit-maestro.md +5 -5
  140. package/.bkit/templates/context/bkit-playwright.md +3 -3
  141. package/.bkit/templates/context/bkit-sentry.md +6 -5
  142. package/.bkit/templates/context/bkit-stripe.md +31 -8
  143. package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +65 -19
  144. package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +34 -0
  145. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +33 -12
  146. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +54 -0
  147. package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +76 -6
  148. package/.bkit/templates/slop-scan.config.json +7 -2
  149. package/CHANGELOG.md +50 -0
  150. package/LICENSE.md +21 -161
  151. package/README.md +61 -28
  152. package/dist/checks/after/auth.js +28 -0
  153. package/dist/checks/after/github.js +4 -4
  154. package/dist/checks/after/index.js +29 -45
  155. package/dist/checks/after/managed.js +40 -1
  156. package/dist/checks/before/index.js +5 -4
  157. package/dist/checks/before/mcp.js +53 -53
  158. package/dist/checks/status-holes.js +1 -1
  159. package/dist/checks/tips/catalogue.js +297 -0
  160. package/dist/checks/tips/detect.js +130 -0
  161. package/dist/checks/tips/index.js +146 -0
  162. package/dist/cli.js +47 -9
  163. package/dist/commands/install/doctor.js +5 -1
  164. package/dist/commands/install/install.js +27 -7
  165. package/dist/commands/install/uninstall.js +31 -16
  166. package/dist/commands/install/upgrade.js +15 -32
  167. package/dist/commands/launch.js +27 -11
  168. package/dist/commands/tips.js +10 -0
  169. package/dist/commands/workflow/runs.js +52 -16
  170. package/dist/commands/workflow/runtime.js +8 -0
  171. package/dist/commands/workflow/steps.js +1 -0
  172. package/dist/commands/workflow/tests.js +541 -4
  173. package/dist/commands/workflow/workstreams.js +4 -4
  174. package/dist/install/cloud-env.js +3 -14
  175. package/dist/install/hosts.js +22 -0
  176. package/dist/install/managed-block.js +36 -0
  177. package/dist/install/manifest.js +45 -4
  178. package/dist/install/modules/antigravity.js +8 -7
  179. package/dist/install/modules/claude.js +6 -6
  180. package/dist/install/modules/cloud.js +2 -2
  181. package/dist/install/modules/codex.js +5 -5
  182. package/dist/install/modules/core.js +14 -5
  183. package/dist/install/modules/cursor.js +6 -6
  184. package/dist/install/modules/opencode.js +4 -4
  185. package/dist/install/payload-links.js +5 -5
  186. package/dist/install/placeholders.js +1 -1
  187. package/dist/install/version-file.js +12 -3
  188. package/dist/install/write.js +61 -2
  189. package/dist/shared/package-roots.js +8 -11
  190. package/package.json +4 -6
  191. package/.bkit/core/LICENSE.md +0 -149
  192. package/.bkit/shared/LICENSE.md +0 -22
  193. 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,6 +14,7 @@ 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";
@@ -49,6 +50,7 @@ export const CLASSIC_VERBS: ReadonlySet<string> = new Set([
49
50
  "harvest",
50
51
  "analysis",
51
52
  "telemetry",
53
+ "tips",
52
54
  "cursor",
53
55
  "opencode",
54
56
  "help",
@@ -67,6 +69,7 @@ export type Verb =
67
69
  | "harvest"
68
70
  | "analysis"
69
71
  | "telemetry"
72
+ | "tips"
70
73
  | "help";
71
74
 
72
75
  // ---------------------------------------------------------------------------
@@ -119,7 +122,7 @@ export interface ParsedArgs {
119
122
  upgradeFlags: UpgradeFlags;
120
123
  /** Issue tracker selected via `--tracker=<name>`. null = not specified (use manifest field or default). */
121
124
  tracker: IssueTracker | null;
122
- /** Cloud variant selected via `--auto=claude|cursor`. null = not specified. */
125
+ /** Cloud variant selected via `--auto=<variant>` (see CLOUD_VARIANTS). null = not specified. */
123
126
  cloudVariant: CloudVariant | null;
124
127
  /**
125
128
  * opencode provider selected via `--opencode=<provider>`. null = not specified.
@@ -139,6 +142,10 @@ export interface ParsedArgs {
139
142
  * Only populated when verb === "telemetry". null = not specified / not applicable.
140
143
  */
141
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;
142
149
  }
143
150
 
144
151
  export interface UninstallFlags {
@@ -168,7 +175,7 @@ export interface UpgradeFlags {
168
175
  // Bare module-flag tokens accepted on the CLI. `opencode` (value-bearing) is
169
176
  // intercepted by a dedicated branch in parseArgs before this set is consulted; the
170
177
  // generic check only ever validates claude/cursor/codex. `full`, `core` and `cloud`
171
- // 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.
172
179
  // There is no dependency-updater flag. Copy an example; CI warns when none is present.
173
180
  const MODULE_FLAGS = new Set<ModuleFlag>(["claude", "cursor", "opencode", "codex", "antigravity"]);
174
181
 
@@ -262,6 +269,9 @@ export function parseArgs(argv: string[]): ParsedArgs {
262
269
  } else if (firstArg === "telemetry") {
263
270
  verb = "telemetry";
264
271
  args.shift();
272
+ } else if (firstArg === "tips") {
273
+ verb = "tips";
274
+ args.shift();
265
275
  } else if (firstArg === "cursor" || firstArg === "opencode") {
266
276
  verb = firstArg as Verb;
267
277
  args.shift();
@@ -289,6 +299,8 @@ export function parseArgs(argv: string[]): ParsedArgs {
289
299
  let opencodeProvider: string | null = null;
290
300
  let complyPhase: ComplyPhase | null = null;
291
301
  let telemetrySubverb: TelemetrySubverb | null = null;
302
+ let tipsAll = false;
303
+ let tipsWorkflow: ComplyPhase | null = null;
292
304
 
293
305
  // For `telemetry` verb: extract the sub-verb from the first remaining positional arg
294
306
  if (verb === "telemetry") {
@@ -363,7 +375,7 @@ export function parseArgs(argv: string[]): ParsedArgs {
363
375
  process.exit(1);
364
376
  }
365
377
 
366
- // Value-bearing flag: --auto=<claude|cursor> — cloud-agent (auto-dispatch) lane;
378
+ // Value-bearing flag: --auto=<variant> (CLOUD_VARIANTS) — cloud-agent (auto-dispatch) lane;
367
379
  // sets the internal `cloud` module. Bare `--auto` (no variant) is accepted only on
368
380
  // uninstall (variant read from package.json).
369
381
  if (flag === "auto") {
@@ -437,6 +449,24 @@ export function parseArgs(argv: string[]): ParsedArgs {
437
449
  continue;
438
450
  }
439
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
+
440
470
  // Uninstall-specific flags (accepted for all verbs that use them)
441
471
  if (flag === "dry-run") {
442
472
  uninstallFlags.dryRun = true;
@@ -531,6 +561,8 @@ export function parseArgs(argv: string[]): ParsedArgs {
531
561
  opencodeProvider,
532
562
  complyPhase,
533
563
  telemetrySubverb,
564
+ tipsAll,
565
+ tipsWorkflow,
534
566
  };
535
567
  }
536
568
 
@@ -542,7 +574,8 @@ Usage:
542
574
  bkit install <module-flags> Install (or re-sync) the named modules + the implicit
543
575
  core foundation. At least one module flag is REQUIRED —
544
576
  a bare \`bkit install\` errors (name the modules below).
545
- Hosts compose: --claude --cursor --codex --opencode=<provider>.
577
+ Hosts compose: --claude --cursor --codex --antigravity
578
+ --opencode=<provider>.
546
579
  bkit check Dry-run — drift-check everything already installed (no
547
580
  module flags). Exits 1 when a managed file needs
548
581
  re-rendering. Copies under .bkit/templates/ are refreshed by
@@ -569,6 +602,13 @@ Usage:
569
602
  targeted uninstall leaves core untouched.
570
603
  bkit doctor Read-only preflight + post-install advisory replay.
571
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.
572
612
  bkit status Read-only host/provider status. Reports current host+provider
573
613
  (sampled from .opencode/opencode.json, .claude/, .cursor/).
574
614
  Writes nothing. Exits 0.
@@ -638,14 +678,15 @@ Module flags (composable; symmetric install ↔ uninstall):
638
678
  Provider value is REQUIRED. Supported: openrouter, ollama,
639
679
  opencode-zen, opencode-go (opencode-native gateways;
640
680
  auth via BKIT_OPENCODE_API_KEY).
641
- Ships .opencode/** (agents, commands, opencode.json, bkit-gateguard.js).
681
+ Ships .opencode/** (agents, commands, opencode.json, bkit-gateguard.js,
682
+ bkit-readguard.js).
642
683
  Configure your provider key; verify with \`bkit doctor\`. All installed
643
684
  providers tracked in bkit.opencodeProviders.
644
685
  --codex Codex CLI host. BARE flag — takes no value: Codex runs on one gateway
645
686
  (openai), so only --opencode is provider-pluggable. Ships .codex/agents/*.toml
646
- + .codex/hooks.json + .codex/hooks/bkit-gateguard.cjs, plus the workflow skills
647
- (.agents/skills/bkit-*/). Codex loads project-local hooks ONLY once the
648
- .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.
649
690
  --antigravity Google Antigravity IDE host. BARE flag — takes no value: Antigravity runs
650
691
  on one gateway (google). Installs as a workspace PLUGIN at
651
692
  .agents/plugins/bkit/ — plugin.json + skills/bkit-*/SKILL.md (workflow
@@ -753,7 +794,7 @@ export function validateModuleFlagsForVerb(
753
794
  return (
754
795
  "[bkit] `bkit install` requires at least one module flag. Name what to install: " +
755
796
  "--claude, --cursor, --codex, --antigravity, --opencode=<provider> (plus opt-in " +
756
- "--auto=<claude|cursor>). Run `bkit help` for usage."
797
+ `--auto=<${CLOUD_VARIANTS.join("|")}>). Run \`bkit help\` for usage.`
757
798
  );
758
799
  }
759
800
  if ((verb === "check" || verb === "upgrade") && moduleFlags.size > 0) {
@@ -790,6 +831,8 @@ export async function main() {
790
831
  opencodeProvider,
791
832
  complyPhase,
792
833
  telemetrySubverb,
834
+ tipsAll,
835
+ tipsWorkflow,
793
836
  } = parseArgs(process.argv.slice(2));
794
837
 
795
838
  // A bare `bkit` (no arguments) means no command was given: print usage and exit non-zero
@@ -825,6 +868,11 @@ export async function main() {
825
868
  return;
826
869
  }
827
870
 
871
+ if (verb === "tips") {
872
+ runTipsCommand(tipsAll, tipsWorkflow);
873
+ return;
874
+ }
875
+
828
876
  // Launcher verbs — exec the GUI app binary with .bkit/.env merged into the env
829
877
  // so that MCP token placeholders (BKIT_GH_TOKEN, BKIT_OPENCODE_API_KEY, …) resolve correctly
830
878
  // even when launched from the Dock/Finder (macOS GUI-isolation).
@@ -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
  /**
@@ -157,7 +158,9 @@ export async function runDoctor(
157
158
  }
158
159
  }
159
160
 
160
- const banner = formatChecklist(allFindings, suppressed);
161
+ const { tips, suppressed: suppressedTips } = collectTips(process.cwd());
162
+ suppressed.push(...suppressedTips);
163
+ const banner = formatChecklist(allFindings, suppressed, tips);
161
164
  if (banner) {
162
165
  console.log(banner);
163
166
  } else {
@@ -169,6 +172,7 @@ export async function runDoctor(
169
172
  version: getInstallingVersion(),
170
173
  logPrefix: LOG_PREFIX,
171
174
  suppressed,
175
+ tips,
172
176
  });
173
177
 
174
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 {
@@ -222,6 +223,26 @@ export function detectOpencodeProviders(cwd: string): string[] {
222
223
  return [];
223
224
  }
224
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
+
225
246
  /** `bkit install`, and `bkit check` (the same pipeline, dry-run). */
226
247
  export async function runInstall(
227
248
  args: Pick<
@@ -349,9 +370,7 @@ export async function runInstall(
349
370
  }
350
371
 
351
372
  // Seed preflight advisories into ctx so modules can accumulate into the same list.
352
- const advisories: import("../../checks/before/index.js").PreflightFinding[] = [
353
- ...preflightAdvisories,
354
- ];
373
+ const advisories: PreflightFinding[] = [...preflightAdvisories];
355
374
 
356
375
  const ws: WriteSet = { writes: [] };
357
376
  const postDispatch: Array<() => void> = [];
@@ -490,15 +509,17 @@ export async function runInstall(
490
509
  // banner above. `check` (dryRun) wrote nothing, so its Phase 1 findings already describe
491
510
  // the current state and are kept as-is. Module-accumulated advisories (pushed during
492
511
  // dispatch) are preserved; only the Phase 1 seeds are replaced, in their original order.
512
+ let postWriteBlockers: PreflightFinding[] = [];
493
513
  if (!dryRun) {
494
- const moduleAdvisories = advisories.slice(preflightAdvisories.length);
495
- const { advisories: freshPreflightAdvisories } = runPreflight(
514
+ const refreshed = refreshPreflightAfterWrites(
496
515
  effectiveModules,
497
516
  process.cwd(),
498
- undefined,
499
517
  issueTracker,
518
+ preflightAdvisories.length,
519
+ advisories,
500
520
  );
501
- ctx.advisories = [...freshPreflightAdvisories, ...moduleAdvisories];
521
+ ctx.advisories = refreshed.advisories;
522
+ postWriteBlockers = refreshed.blockers;
502
523
  }
503
524
 
504
525
  // --- Phase 3: Post-install checks (re-detect + unified output) ---
@@ -517,12 +538,20 @@ export async function runInstall(
517
538
  }
518
539
  const suppressed: SuppressionNote[] = [];
519
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
+ }
520
547
  // check only: install has just written every hook file of the modules it dispatched, and a
521
548
  // missing bkit-cloud-bootstrap.sh after `install --claude` is not that run's fault.
522
549
  const missingHooks = dryRun ? findMissingOwnedHooks(process.cwd(), effectiveModules) : [];
523
550
  const missingHooksFinding = detectOwnedHookMissing(missingHooks);
524
551
  if (missingHooksFinding) postFindings.push(missingHooksFinding);
525
- const banner = formatChecklist(postFindings, suppressed);
552
+ const { tips, suppressed: suppressedTips } = collectTips(process.cwd());
553
+ suppressed.push(...suppressedTips);
554
+ const banner = formatChecklist(postFindings, suppressed, tips);
526
555
  if (banner) console.log(banner);
527
556
  writeAdvisoriesArtifact(postFindings, {
528
557
  cwd: process.cwd(),
@@ -530,6 +559,7 @@ export async function runInstall(
530
559
  version: getInstallingVersion(),
531
560
  logPrefix: LOG_PREFIX,
532
561
  suppressed,
562
+ tips,
533
563
  });
534
564
 
535
565
  // Check mode: exit 1 on drift (see reportCheckDrift).
@@ -96,6 +96,8 @@ export interface UninstallResult {
96
96
  deleted: string[];
97
97
  stripped: string[];
98
98
  preserved: string[];
99
+ /** Manifest-listed files already missing on disk (`skip-absent`) — nothing done. */
100
+ absent: string[];
99
101
  decisions: FileSummary[];
100
102
  dryRun: boolean;
101
103
  }
@@ -494,6 +496,7 @@ export async function runUninstall(
494
496
  deleted: [],
495
497
  stripped: [],
496
498
  preserved: [],
499
+ absent: [],
497
500
  decisions: [],
498
501
  dryRun: ctx.dryRun,
499
502
  };
@@ -532,7 +535,14 @@ export async function runUninstall(
532
535
  const absPath = path.join(ctx.cwd, summary.file);
533
536
 
534
537
  switch (summary.decision) {
535
- case "skip-absent":
538
+ case "skip-absent": {
539
+ result.absent.push(summary.file);
540
+ if (!ctx.dryRun) {
541
+ console.log(`${ctx.logPrefix} absent: ${summary.file} (${summary.reason})`);
542
+ }
543
+ break;
544
+ }
545
+
536
546
  case "skip-modified":
537
547
  case "skip-unknown":
538
548
  case "preserve": {
@@ -702,7 +712,8 @@ export async function runUninstall(
702
712
 
703
713
  // Clean up .agents/ bkit-prefix mirror files
704
714
  // (.claude/commands/bkit-*.md, .claude/agents/bkit-*.md, .opencode/agents/bkit-*.md, etc.)
705
- if (!ctx.dryRun) {
715
+ // A dry run lists the same paths in result.deleted and removes nothing.
716
+ {
706
717
  const mirrorDirs = [
707
718
  // Each host's mirror dirs are gated on its own module so a targeted
708
719
  // uninstall (e.g. --claude / --auto) leaves other hosts
@@ -728,9 +739,9 @@ export async function runUninstall(
728
739
  // .toml as well as .md: codex agent mirrors are TOML.
729
740
  if (!f.startsWith("bkit-") || !(f.endsWith(".md") || f.endsWith(".toml"))) continue;
730
741
  const absFile = path.join(absDir, f);
731
- fs.rmSync(absFile, { force: true });
742
+ if (!ctx.dryRun) fs.rmSync(absFile, { force: true });
732
743
  result.deleted.push(path.join(dir, f));
733
- console.log(`${ctx.logPrefix} delete mirror: ${path.join(dir, f)}`);
744
+ if (!ctx.dryRun) console.log(`${ctx.logPrefix} delete mirror: ${path.join(dir, f)}`);
734
745
  }
735
746
  } catch (err) {
736
747
  console.error(`${ctx.logPrefix} error cleaning up ${dir}: ${(err as Error).message}`);
@@ -755,9 +766,11 @@ export async function runUninstall(
755
766
  if (!d.startsWith("bkit-")) continue;
756
767
  const abs = path.join(absDir, d);
757
768
  if (!fs.statSync(abs).isDirectory()) continue;
758
- fs.rmSync(abs, { recursive: true, force: true });
769
+ if (!ctx.dryRun) fs.rmSync(abs, { recursive: true, force: true });
759
770
  result.deleted.push(path.join(skillsDir, d));
760
- console.log(`${ctx.logPrefix} delete mirror: ${path.join(skillsDir, d)}`);
771
+ if (!ctx.dryRun) {
772
+ console.log(`${ctx.logPrefix} delete mirror: ${path.join(skillsDir, d)}`);
773
+ }
761
774
  }
762
775
  } catch (err) {
763
776
  const msg = (err as Error).message;
@@ -876,6 +889,7 @@ export async function runUninstall(
876
889
  ctx.cwd,
877
890
  existing.canonicalHashes,
878
891
  {},
892
+ result.deleted,
879
893
  );
880
894
  if (pruned > 0) {
881
895
  console.log(
@@ -1023,16 +1037,16 @@ export async function runUninstallCommand(
1023
1037
  const moduleList = [...modules] as ModuleName[];
1024
1038
  console.log(`${LOG_PREFIX} Running uninstall${uninstallCtx.dryRun ? " (dry-run)" : ""}...`);
1025
1039
  const result = await runUninstall(moduleList, uninstallCtx);
1026
- const totalDeleted = result.deleted.length;
1027
- const totalStripped = result.stripped.length;
1028
- const totalPreserved = result.preserved.length;
1029
- if (uninstallCtx.dryRun) {
1030
- console.log(
1031
- `${LOG_PREFIX} [dry-run] Would delete: ${totalDeleted}, strip: ${totalStripped}, preserve: ${totalPreserved}`,
1032
- );
1033
- } else {
1034
- console.log(
1035
- `${LOG_PREFIX} Done. Deleted: ${totalDeleted}, stripped: ${totalStripped}, preserved: ${totalPreserved}`,
1036
- );
1037
- }
1040
+ console.log(uninstallSummaryLine(result, LOG_PREFIX));
1041
+ }
1042
+
1043
+ /** The closing totals line of an uninstall run (dry-run wording when `result.dryRun`). */
1044
+ export function uninstallSummaryLine(result: UninstallResult, logPrefix: string): string {
1045
+ const deleted = result.deleted.length;
1046
+ const stripped = result.stripped.length;
1047
+ const preserved = result.preserved.length;
1048
+ const absent = result.absent.length;
1049
+ return result.dryRun
1050
+ ? `${logPrefix} [dry-run] Would delete: ${deleted}, strip: ${stripped}, preserve: ${preserved}, already absent: ${absent}`
1051
+ : `${logPrefix} Done. Deleted: ${deleted}, stripped: ${stripped}, preserved: ${preserved}, already absent: ${absent}`;
1038
1052
  }