@vpxa/kb 0.1.13 → 0.1.16

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 (490) hide show
  1. package/README.md +65 -12
  2. package/package.json +14 -7
  3. package/packages/analyzers/dist/blast-radius-analyzer.d.ts +17 -21
  4. package/packages/analyzers/dist/blast-radius-analyzer.js +5 -12
  5. package/packages/analyzers/dist/dependency-analyzer.d.ts +31 -28
  6. package/packages/analyzers/dist/dependency-analyzer.js +6 -9
  7. package/packages/analyzers/dist/diagram-generator.d.ts +12 -9
  8. package/packages/analyzers/dist/diagram-generator.js +2 -4
  9. package/packages/analyzers/dist/entry-point-analyzer.d.ts +39 -36
  10. package/packages/analyzers/dist/entry-point-analyzer.js +4 -6
  11. package/packages/analyzers/dist/index.d.ts +12 -14
  12. package/packages/analyzers/dist/index.js +1 -1
  13. package/packages/analyzers/dist/knowledge-producer.d.ts +34 -26
  14. package/packages/analyzers/dist/knowledge-producer.js +17 -15
  15. package/packages/analyzers/dist/pattern-analyzer.d.ts +14 -11
  16. package/packages/analyzers/dist/pattern-analyzer.js +2 -5
  17. package/packages/analyzers/dist/regex-call-graph.d.ts +6 -13
  18. package/packages/analyzers/dist/regex-call-graph.js +1 -1
  19. package/packages/analyzers/dist/structure-analyzer.d.ts +13 -10
  20. package/packages/analyzers/dist/structure-analyzer.js +2 -4
  21. package/packages/analyzers/dist/symbol-analyzer.d.ts +13 -9
  22. package/packages/analyzers/dist/symbol-analyzer.js +9 -13
  23. package/packages/analyzers/dist/ts-call-graph.d.ts +16 -14
  24. package/packages/analyzers/dist/ts-call-graph.js +1 -1
  25. package/packages/analyzers/dist/types.d.ts +82 -80
  26. package/packages/analyzers/dist/types.js +1 -0
  27. package/packages/chunker/dist/call-graph-extractor.d.ts +15 -12
  28. package/packages/chunker/dist/call-graph-extractor.js +1 -1
  29. package/packages/chunker/dist/chunker-factory.d.ts +16 -4
  30. package/packages/chunker/dist/chunker-factory.js +1 -1
  31. package/packages/chunker/dist/chunker.interface.d.ts +8 -5
  32. package/packages/chunker/dist/chunker.interface.js +1 -0
  33. package/packages/chunker/dist/code-chunker.d.ts +16 -13
  34. package/packages/chunker/dist/code-chunker.js +11 -14
  35. package/packages/chunker/dist/extractors/call-extractor.d.ts +24 -0
  36. package/packages/chunker/dist/extractors/call-extractor.js +1 -0
  37. package/packages/chunker/dist/extractors/entry-point-detector.d.ts +14 -0
  38. package/packages/chunker/dist/extractors/entry-point-detector.js +1 -0
  39. package/packages/chunker/dist/extractors/import-extractor.d.ts +14 -0
  40. package/packages/chunker/dist/extractors/import-extractor.js +1 -0
  41. package/packages/chunker/dist/extractors/pattern-detector.d.ts +14 -0
  42. package/packages/chunker/dist/extractors/pattern-detector.js +1 -0
  43. package/packages/chunker/dist/extractors/scope-resolver.d.ts +26 -0
  44. package/packages/chunker/dist/extractors/scope-resolver.js +1 -0
  45. package/packages/chunker/dist/extractors/symbol-extractor.d.ts +14 -0
  46. package/packages/chunker/dist/extractors/symbol-extractor.js +1 -0
  47. package/packages/chunker/dist/extractors/types.d.ts +36 -0
  48. package/packages/chunker/dist/extractors/types.js +1 -0
  49. package/packages/chunker/dist/generic-chunker.d.ts +14 -11
  50. package/packages/chunker/dist/generic-chunker.js +5 -5
  51. package/packages/chunker/dist/index.d.ts +19 -8
  52. package/packages/chunker/dist/index.js +1 -1
  53. package/packages/chunker/dist/markdown-chunker.d.ts +16 -13
  54. package/packages/chunker/dist/markdown-chunker.js +3 -10
  55. package/packages/chunker/dist/wasm/languages.d.ts +18 -0
  56. package/packages/chunker/dist/wasm/languages.js +1 -0
  57. package/packages/chunker/dist/wasm/query-executor.d.ts +70 -0
  58. package/packages/chunker/dist/wasm/query-executor.js +1 -0
  59. package/packages/chunker/dist/wasm/runtime.d.ts +44 -0
  60. package/packages/chunker/dist/wasm/runtime.js +1 -0
  61. package/packages/chunker/dist/wasm/types.d.ts +84 -0
  62. package/packages/chunker/dist/wasm/types.js +1 -0
  63. package/packages/chunker/dist/wasm-chunker.d.ts +23 -0
  64. package/packages/chunker/dist/wasm-chunker.js +6 -0
  65. package/packages/chunker/src/queries/go/calls.scm +11 -0
  66. package/packages/chunker/src/queries/go/entry-points.scm +20 -0
  67. package/packages/chunker/src/queries/go/imports.scm +6 -0
  68. package/packages/chunker/src/queries/go/patterns.scm +25 -0
  69. package/packages/chunker/src/queries/go/symbols.scm +26 -0
  70. package/packages/chunker/src/queries/java/calls.scm +10 -0
  71. package/packages/chunker/src/queries/java/entry-points.scm +27 -0
  72. package/packages/chunker/src/queries/java/imports.scm +11 -0
  73. package/packages/chunker/src/queries/java/patterns.scm +27 -0
  74. package/packages/chunker/src/queries/java/symbols.scm +28 -0
  75. package/packages/chunker/src/queries/javascript/calls.scm +21 -0
  76. package/packages/chunker/src/queries/javascript/entry-points.scm +31 -0
  77. package/packages/chunker/src/queries/javascript/imports.scm +32 -0
  78. package/packages/chunker/src/queries/javascript/patterns.scm +28 -0
  79. package/packages/chunker/src/queries/javascript/symbols.scm +52 -0
  80. package/packages/chunker/src/queries/python/calls.scm +11 -0
  81. package/packages/chunker/src/queries/python/entry-points.scm +21 -0
  82. package/packages/chunker/src/queries/python/imports.scm +14 -0
  83. package/packages/chunker/src/queries/python/patterns.scm +25 -0
  84. package/packages/chunker/src/queries/python/symbols.scm +17 -0
  85. package/packages/chunker/src/queries/rust/calls.scm +20 -0
  86. package/packages/chunker/src/queries/rust/entry-points.scm +7 -0
  87. package/packages/chunker/src/queries/rust/imports.scm +26 -0
  88. package/packages/chunker/src/queries/rust/patterns.scm +18 -0
  89. package/packages/chunker/src/queries/rust/symbols.scm +73 -0
  90. package/packages/chunker/src/queries/typescript/calls.scm +21 -0
  91. package/packages/chunker/src/queries/typescript/entry-points.scm +48 -0
  92. package/packages/chunker/src/queries/typescript/imports.scm +35 -0
  93. package/packages/chunker/src/queries/typescript/patterns.scm +47 -0
  94. package/packages/chunker/src/queries/typescript/symbols.scm +79 -0
  95. package/packages/chunker/wasm/tree-sitter-go.wasm +0 -0
  96. package/packages/chunker/wasm/tree-sitter-java.wasm +0 -0
  97. package/packages/chunker/wasm/tree-sitter-javascript.wasm +0 -0
  98. package/packages/chunker/wasm/tree-sitter-python.wasm +0 -0
  99. package/packages/chunker/wasm/tree-sitter-rust.wasm +0 -0
  100. package/packages/chunker/wasm/tree-sitter-typescript.wasm +0 -0
  101. package/packages/chunker/wasm/tree-sitter.wasm +0 -0
  102. package/packages/cli/dist/commands/analyze.d.ts +6 -3
  103. package/packages/cli/dist/commands/analyze.js +2 -3
  104. package/packages/cli/dist/commands/context-cmds.d.ts +6 -3
  105. package/packages/cli/dist/commands/context-cmds.js +1 -1
  106. package/packages/cli/dist/commands/environment.d.ts +6 -3
  107. package/packages/cli/dist/commands/environment.js +1 -2
  108. package/packages/cli/dist/commands/execution.d.ts +6 -3
  109. package/packages/cli/dist/commands/execution.js +1 -1
  110. package/packages/cli/dist/commands/graph.d.ts +6 -3
  111. package/packages/cli/dist/commands/graph.js +5 -6
  112. package/packages/cli/dist/commands/init/adapters.d.ts +28 -0
  113. package/packages/cli/dist/commands/init/adapters.js +1 -0
  114. package/packages/cli/dist/commands/init/config.d.ts +10 -0
  115. package/packages/cli/dist/commands/init/config.js +3 -0
  116. package/packages/cli/dist/commands/init/constants.d.ts +18 -0
  117. package/packages/cli/dist/commands/init/constants.js +1 -0
  118. package/packages/cli/dist/commands/init/curated.d.ts +7 -0
  119. package/packages/cli/dist/commands/init/curated.js +1 -0
  120. package/packages/cli/dist/commands/init/global.d.ts +34 -0
  121. package/packages/cli/dist/commands/init/global.js +5 -0
  122. package/packages/cli/dist/commands/init/index.d.ts +28 -0
  123. package/packages/cli/dist/commands/init/index.js +5 -0
  124. package/packages/cli/dist/commands/init/scaffold.d.ts +23 -0
  125. package/packages/cli/dist/commands/init/scaffold.js +1 -0
  126. package/packages/cli/dist/commands/init/templates.d.ts +9 -0
  127. package/packages/cli/dist/commands/init/templates.js +165 -0
  128. package/packages/cli/dist/commands/knowledge.d.ts +6 -3
  129. package/packages/cli/dist/commands/knowledge.js +1 -1
  130. package/packages/cli/dist/commands/search.d.ts +6 -3
  131. package/packages/cli/dist/commands/search.js +1 -8
  132. package/packages/cli/dist/commands/system.d.ts +6 -3
  133. package/packages/cli/dist/commands/system.js +4 -7
  134. package/packages/cli/dist/commands/workspace.d.ts +6 -3
  135. package/packages/cli/dist/commands/workspace.js +1 -2
  136. package/packages/cli/dist/context.d.ts +7 -5
  137. package/packages/cli/dist/context.js +1 -1
  138. package/packages/cli/dist/helpers.d.ts +51 -48
  139. package/packages/cli/dist/helpers.js +5 -5
  140. package/packages/cli/dist/index.d.ts +4 -2
  141. package/packages/cli/dist/index.js +2 -2
  142. package/packages/cli/dist/kb-init.d.ts +48 -51
  143. package/packages/cli/dist/kb-init.js +1 -1
  144. package/packages/cli/dist/types.d.ts +8 -6
  145. package/packages/cli/dist/types.js +1 -0
  146. package/packages/core/dist/constants.d.ts +58 -34
  147. package/packages/core/dist/constants.js +1 -1
  148. package/packages/core/dist/content-detector.d.ts +8 -8
  149. package/packages/core/dist/content-detector.js +1 -1
  150. package/packages/core/dist/errors.d.ts +15 -13
  151. package/packages/core/dist/errors.js +1 -1
  152. package/packages/core/dist/global-registry.d.ts +62 -0
  153. package/packages/core/dist/global-registry.js +1 -0
  154. package/packages/core/dist/index.d.ts +7 -6
  155. package/packages/core/dist/index.js +1 -1
  156. package/packages/core/dist/logger.d.ts +19 -8
  157. package/packages/core/dist/logger.js +1 -1
  158. package/packages/core/dist/types.d.ts +107 -92
  159. package/packages/core/dist/types.js +1 -0
  160. package/packages/embeddings/dist/embedder.interface.d.ts +22 -20
  161. package/packages/embeddings/dist/embedder.interface.js +1 -0
  162. package/packages/embeddings/dist/index.d.ts +3 -3
  163. package/packages/embeddings/dist/index.js +1 -1
  164. package/packages/embeddings/dist/onnx-embedder.d.ts +21 -23
  165. package/packages/embeddings/dist/onnx-embedder.js +1 -1
  166. package/packages/enterprise-bridge/dist/cache.d.ts +28 -0
  167. package/packages/enterprise-bridge/dist/cache.js +1 -0
  168. package/packages/enterprise-bridge/dist/er-client.d.ts +37 -0
  169. package/packages/enterprise-bridge/dist/er-client.js +1 -0
  170. package/packages/enterprise-bridge/dist/evolution-collector.d.ts +62 -0
  171. package/packages/enterprise-bridge/dist/evolution-collector.js +1 -0
  172. package/packages/enterprise-bridge/dist/index.d.ts +8 -0
  173. package/packages/enterprise-bridge/dist/index.js +1 -0
  174. package/packages/enterprise-bridge/dist/policy-store.d.ts +45 -0
  175. package/packages/enterprise-bridge/dist/policy-store.js +1 -0
  176. package/packages/enterprise-bridge/dist/push-adapter.d.ts +23 -0
  177. package/packages/enterprise-bridge/dist/push-adapter.js +1 -0
  178. package/packages/enterprise-bridge/dist/result-merger.d.ts +14 -0
  179. package/packages/enterprise-bridge/dist/result-merger.js +1 -0
  180. package/packages/enterprise-bridge/dist/types.d.ts +81 -0
  181. package/packages/enterprise-bridge/dist/types.js +1 -0
  182. package/packages/indexer/dist/file-hasher.d.ts +5 -3
  183. package/packages/indexer/dist/file-hasher.js +1 -1
  184. package/packages/indexer/dist/filesystem-crawler.d.ts +23 -21
  185. package/packages/indexer/dist/filesystem-crawler.js +1 -1
  186. package/packages/indexer/dist/graph-extractor.d.ts +9 -13
  187. package/packages/indexer/dist/graph-extractor.js +1 -1
  188. package/packages/indexer/dist/incremental-indexer.d.ts +49 -44
  189. package/packages/indexer/dist/incremental-indexer.js +1 -1
  190. package/packages/indexer/dist/index.d.ts +5 -5
  191. package/packages/indexer/dist/index.js +1 -1
  192. package/packages/server/dist/api.d.ts +3 -8
  193. package/packages/server/dist/api.js +1 -1
  194. package/packages/server/dist/config.d.ts +6 -3
  195. package/packages/server/dist/config.js +1 -1
  196. package/packages/server/dist/cross-workspace.d.ts +43 -0
  197. package/packages/server/dist/cross-workspace.js +1 -0
  198. package/packages/server/dist/curated-manager.d.ts +80 -78
  199. package/packages/server/dist/curated-manager.js +5 -10
  200. package/packages/server/dist/index.d.ts +1 -2
  201. package/packages/server/dist/index.js +1 -1
  202. package/packages/server/dist/replay-interceptor.d.ts +6 -7
  203. package/packages/server/dist/replay-interceptor.js +1 -1
  204. package/packages/server/dist/resources/resources.d.ts +7 -4
  205. package/packages/server/dist/resources/resources.js +2 -2
  206. package/packages/server/dist/server.d.ts +37 -25
  207. package/packages/server/dist/server.js +1 -1
  208. package/packages/server/dist/tools/analyze.tools.d.ts +14 -11
  209. package/packages/server/dist/tools/analyze.tools.js +1 -3
  210. package/packages/server/dist/tools/audit.tool.d.ts +8 -5
  211. package/packages/server/dist/tools/audit.tool.js +1 -4
  212. package/packages/server/dist/tools/bridge.tools.d.ts +34 -0
  213. package/packages/server/dist/tools/bridge.tools.js +15 -0
  214. package/packages/server/dist/tools/evolution.tools.d.ts +7 -0
  215. package/packages/server/dist/tools/evolution.tools.js +5 -0
  216. package/packages/server/dist/tools/forge.tools.d.ts +13 -12
  217. package/packages/server/dist/tools/forge.tools.js +10 -13
  218. package/packages/server/dist/tools/forget.tool.d.ts +7 -4
  219. package/packages/server/dist/tools/forget.tool.js +1 -7
  220. package/packages/server/dist/tools/graph.tool.d.ts +7 -4
  221. package/packages/server/dist/tools/graph.tool.js +4 -5
  222. package/packages/server/dist/tools/list.tool.d.ts +7 -4
  223. package/packages/server/dist/tools/list.tool.js +2 -8
  224. package/packages/server/dist/tools/lookup.tool.d.ts +7 -4
  225. package/packages/server/dist/tools/lookup.tool.js +2 -9
  226. package/packages/server/dist/tools/onboard.tool.d.ts +8 -5
  227. package/packages/server/dist/tools/onboard.tool.js +2 -2
  228. package/packages/server/dist/tools/policy.tools.d.ts +7 -0
  229. package/packages/server/dist/tools/policy.tools.js +2 -0
  230. package/packages/server/dist/tools/produce.tool.d.ts +6 -3
  231. package/packages/server/dist/tools/produce.tool.js +2 -2
  232. package/packages/server/dist/tools/read.tool.d.ts +7 -4
  233. package/packages/server/dist/tools/read.tool.js +2 -6
  234. package/packages/server/dist/tools/reindex.tool.d.ts +10 -7
  235. package/packages/server/dist/tools/reindex.tool.js +3 -2
  236. package/packages/server/dist/tools/remember.tool.d.ts +8 -4
  237. package/packages/server/dist/tools/remember.tool.js +3 -5
  238. package/packages/server/dist/tools/replay.tool.d.ts +6 -3
  239. package/packages/server/dist/tools/replay.tool.js +2 -6
  240. package/packages/server/dist/tools/search.tool.d.ts +10 -5
  241. package/packages/server/dist/tools/search.tool.js +6 -22
  242. package/packages/server/dist/tools/status.tool.d.ts +12 -4
  243. package/packages/server/dist/tools/status.tool.js +2 -3
  244. package/packages/server/dist/tools/toolkit.tools.d.ts +36 -35
  245. package/packages/server/dist/tools/toolkit.tools.js +20 -24
  246. package/packages/server/dist/tools/update.tool.d.ts +7 -4
  247. package/packages/server/dist/tools/update.tool.js +1 -6
  248. package/packages/server/dist/tools/utility.tools.d.ts +15 -15
  249. package/packages/server/dist/tools/utility.tools.js +10 -23
  250. package/packages/server/dist/version-check.d.ts +5 -2
  251. package/packages/server/dist/version-check.js +1 -1
  252. package/packages/store/dist/graph-store.interface.d.ts +89 -87
  253. package/packages/store/dist/graph-store.interface.js +1 -0
  254. package/packages/store/dist/index.d.ts +6 -6
  255. package/packages/store/dist/index.js +1 -1
  256. package/packages/store/dist/lance-store.d.ts +37 -31
  257. package/packages/store/dist/lance-store.js +1 -1
  258. package/packages/store/dist/sqlite-graph-store.d.ts +43 -47
  259. package/packages/store/dist/sqlite-graph-store.js +13 -13
  260. package/packages/store/dist/store-factory.d.ts +11 -8
  261. package/packages/store/dist/store-factory.js +1 -1
  262. package/packages/store/dist/store.interface.d.ts +47 -47
  263. package/packages/store/dist/store.interface.js +1 -0
  264. package/packages/tools/dist/audit.d.ts +61 -62
  265. package/packages/tools/dist/audit.js +4 -5
  266. package/packages/tools/dist/batch.d.ts +20 -18
  267. package/packages/tools/dist/batch.js +1 -1
  268. package/packages/tools/dist/changelog.d.ts +29 -27
  269. package/packages/tools/dist/changelog.js +2 -2
  270. package/packages/tools/dist/check.d.ts +42 -39
  271. package/packages/tools/dist/check.js +2 -2
  272. package/packages/tools/dist/checkpoint.d.ts +17 -15
  273. package/packages/tools/dist/checkpoint.js +1 -2
  274. package/packages/tools/dist/codemod.d.ts +35 -33
  275. package/packages/tools/dist/codemod.js +2 -2
  276. package/packages/tools/dist/compact.d.ts +34 -38
  277. package/packages/tools/dist/compact.js +2 -2
  278. package/packages/tools/dist/data-transform.d.ts +10 -8
  279. package/packages/tools/dist/data-transform.js +1 -1
  280. package/packages/tools/dist/dead-symbols.d.ts +29 -26
  281. package/packages/tools/dist/dead-symbols.js +2 -2
  282. package/packages/tools/dist/delegate.d.ts +26 -24
  283. package/packages/tools/dist/delegate.js +1 -5
  284. package/packages/tools/dist/diff-parse.d.ts +24 -22
  285. package/packages/tools/dist/diff-parse.js +3 -3
  286. package/packages/tools/dist/digest.d.ts +43 -46
  287. package/packages/tools/dist/digest.js +4 -5
  288. package/packages/tools/dist/dogfood-log.d.ts +49 -0
  289. package/packages/tools/dist/dogfood-log.js +2 -0
  290. package/packages/tools/dist/encode.d.ts +11 -9
  291. package/packages/tools/dist/encode.js +1 -1
  292. package/packages/tools/dist/env-info.d.ts +25 -23
  293. package/packages/tools/dist/env-info.js +1 -1
  294. package/packages/tools/dist/eval.d.ts +13 -11
  295. package/packages/tools/dist/eval.js +2 -3
  296. package/packages/tools/dist/evidence-map.d.ts +64 -62
  297. package/packages/tools/dist/evidence-map.js +2 -3
  298. package/packages/tools/dist/file-cache.d.ts +41 -0
  299. package/packages/tools/dist/file-cache.js +3 -0
  300. package/packages/tools/dist/file-summary.d.ts +50 -30
  301. package/packages/tools/dist/file-summary.js +2 -2
  302. package/packages/tools/dist/file-walk.d.ts +6 -4
  303. package/packages/tools/dist/file-walk.js +1 -1
  304. package/packages/tools/dist/find-examples.d.ts +26 -22
  305. package/packages/tools/dist/find-examples.js +3 -3
  306. package/packages/tools/dist/find.d.ts +39 -41
  307. package/packages/tools/dist/find.js +1 -1
  308. package/packages/tools/dist/forge-classify.d.ts +35 -39
  309. package/packages/tools/dist/forge-classify.js +2 -2
  310. package/packages/tools/dist/forge-ground.d.ts +58 -61
  311. package/packages/tools/dist/forge-ground.js +1 -1
  312. package/packages/tools/dist/git-context.d.ts +22 -20
  313. package/packages/tools/dist/git-context.js +3 -3
  314. package/packages/tools/dist/graph-query.d.ts +75 -79
  315. package/packages/tools/dist/graph-query.js +1 -1
  316. package/packages/tools/dist/guide.d.ts +14 -12
  317. package/packages/tools/dist/guide.js +1 -1
  318. package/packages/tools/dist/health.d.ts +13 -11
  319. package/packages/tools/dist/health.js +2 -2
  320. package/packages/tools/dist/http-request.d.ts +20 -18
  321. package/packages/tools/dist/http-request.js +1 -1
  322. package/packages/tools/dist/index.d.ts +55 -53
  323. package/packages/tools/dist/index.js +1 -1
  324. package/packages/tools/dist/lane.d.ts +28 -26
  325. package/packages/tools/dist/lane.js +6 -7
  326. package/packages/tools/dist/measure.d.ts +34 -30
  327. package/packages/tools/dist/measure.js +2 -2
  328. package/packages/tools/dist/onboard.d.ts +29 -27
  329. package/packages/tools/dist/onboard.js +17 -41
  330. package/packages/tools/dist/parse-output.d.ts +48 -46
  331. package/packages/tools/dist/parse-output.js +2 -2
  332. package/packages/tools/dist/path-resolver.d.ts +4 -2
  333. package/packages/tools/dist/path-resolver.js +1 -1
  334. package/packages/tools/dist/process-manager.d.ts +18 -16
  335. package/packages/tools/dist/process-manager.js +1 -1
  336. package/packages/tools/dist/queue.d.ts +28 -26
  337. package/packages/tools/dist/queue.js +1 -2
  338. package/packages/tools/dist/regex-test.d.ts +26 -24
  339. package/packages/tools/dist/regex-test.js +1 -1
  340. package/packages/tools/dist/rename.d.ts +28 -26
  341. package/packages/tools/dist/rename.js +2 -2
  342. package/packages/tools/dist/replay.d.ts +33 -31
  343. package/packages/tools/dist/replay.js +4 -6
  344. package/packages/tools/dist/response-envelope.d.ts +32 -30
  345. package/packages/tools/dist/response-envelope.js +1 -1
  346. package/packages/tools/dist/schema-validate.d.ts +15 -13
  347. package/packages/tools/dist/schema-validate.js +1 -1
  348. package/packages/tools/dist/scope-map.d.ts +45 -48
  349. package/packages/tools/dist/scope-map.js +1 -1
  350. package/packages/tools/dist/snippet.d.ts +26 -25
  351. package/packages/tools/dist/snippet.js +1 -1
  352. package/packages/tools/dist/stash.d.ts +13 -11
  353. package/packages/tools/dist/stash.js +1 -2
  354. package/packages/tools/dist/stratum-card.d.ts +27 -28
  355. package/packages/tools/dist/stratum-card.js +3 -5
  356. package/packages/tools/dist/symbol.d.ts +31 -26
  357. package/packages/tools/dist/symbol.js +3 -3
  358. package/packages/tools/dist/test-run.d.ts +19 -16
  359. package/packages/tools/dist/test-run.js +2 -2
  360. package/packages/tools/dist/text-utils.d.ts +6 -4
  361. package/packages/tools/dist/text-utils.js +2 -2
  362. package/packages/tools/dist/time-utils.d.ts +15 -13
  363. package/packages/tools/dist/time-utils.js +1 -1
  364. package/packages/tools/dist/trace.d.ts +26 -21
  365. package/packages/tools/dist/trace.js +2 -2
  366. package/packages/tools/dist/truncation.d.ts +6 -4
  367. package/packages/tools/dist/truncation.js +6 -13
  368. package/packages/tools/dist/watch.d.ts +28 -26
  369. package/packages/tools/dist/watch.js +1 -1
  370. package/packages/tools/dist/web-fetch.d.ts +35 -33
  371. package/packages/tools/dist/web-fetch.js +6 -12
  372. package/packages/tools/dist/web-search.d.ts +16 -14
  373. package/packages/tools/dist/web-search.js +1 -1
  374. package/packages/tools/dist/workset.d.ts +19 -17
  375. package/packages/tools/dist/workset.js +1 -2
  376. package/packages/tui/dist/App-CYLNJLr6.js +2 -0
  377. package/packages/tui/dist/App.d.ts +11 -6
  378. package/packages/tui/dist/App.js +1 -450
  379. package/packages/tui/dist/CuratedPanel-sYdZAICX.js +2 -0
  380. package/packages/tui/dist/LogPanel-DtMnoyXT.js +3 -0
  381. package/packages/tui/dist/SearchPanel-DREo6zgt.js +2 -0
  382. package/packages/tui/dist/StatusPanel-2ex8fLOO.js +2 -0
  383. package/packages/tui/dist/chunk-D6axbAb-.js +2 -0
  384. package/packages/tui/dist/devtools-DUyj952l.js +7 -0
  385. package/packages/tui/dist/embedder.interface-D4ew0HPW.d.ts +28 -0
  386. package/packages/tui/dist/index-B9VpfVPP.d.ts +13 -0
  387. package/packages/tui/dist/index.d.ts +3 -19
  388. package/packages/tui/dist/index.js +1 -476
  389. package/packages/tui/dist/jsx-runtime-Cof-kwFn.js +316 -0
  390. package/packages/tui/dist/panels/CuratedPanel.d.ts +11 -6
  391. package/packages/tui/dist/panels/CuratedPanel.js +1 -371
  392. package/packages/tui/dist/panels/LogPanel.d.ts +7 -3
  393. package/packages/tui/dist/panels/LogPanel.js +1 -449
  394. package/packages/tui/dist/panels/SearchPanel.d.ts +14 -8
  395. package/packages/tui/dist/panels/SearchPanel.js +1 -372
  396. package/packages/tui/dist/panels/StatusPanel.d.ts +11 -6
  397. package/packages/tui/dist/panels/StatusPanel.js +1 -371
  398. package/packages/tui/dist/store.interface-CnY6SPOH.d.ts +150 -0
  399. package/scaffold/adapters/claude-code.mjs +20 -0
  400. package/scaffold/adapters/copilot.mjs +320 -0
  401. package/scaffold/copilot/agents/Architect-Reviewer-Alpha.agent.md +21 -0
  402. package/scaffold/copilot/agents/Architect-Reviewer-Beta.agent.md +21 -0
  403. package/scaffold/copilot/agents/Documenter.agent.md +42 -0
  404. package/scaffold/copilot/agents/Orchestrator.agent.md +104 -0
  405. package/scaffold/copilot/agents/Planner.agent.md +54 -0
  406. package/scaffold/copilot/agents/Refactor.agent.md +36 -0
  407. package/scaffold/copilot/agents/Researcher-Alpha.agent.md +20 -0
  408. package/scaffold/copilot/agents/Researcher-Beta.agent.md +20 -0
  409. package/scaffold/copilot/agents/Researcher-Delta.agent.md +20 -0
  410. package/scaffold/copilot/agents/Researcher-Gamma.agent.md +20 -0
  411. package/scaffold/definitions/agents.mjs +165 -0
  412. package/scaffold/definitions/bodies.mjs +292 -0
  413. package/scaffold/definitions/hooks.mjs +43 -0
  414. package/scaffold/definitions/models.mjs +56 -0
  415. package/scaffold/definitions/plugins.mjs +24 -0
  416. package/scaffold/definitions/prompts.mjs +145 -0
  417. package/scaffold/definitions/protocols.mjs +322 -0
  418. package/scaffold/definitions/tools.mjs +176 -0
  419. package/scaffold/general/agents/Architect-Reviewer-Alpha.agent.md +21 -0
  420. package/scaffold/general/agents/Architect-Reviewer-Beta.agent.md +21 -0
  421. package/scaffold/general/agents/Code-Reviewer-Alpha.agent.md +12 -0
  422. package/scaffold/general/agents/Code-Reviewer-Beta.agent.md +12 -0
  423. package/scaffold/general/agents/Debugger.agent.md +31 -0
  424. package/scaffold/general/agents/Documenter.agent.md +42 -0
  425. package/scaffold/general/agents/Explorer.agent.md +50 -0
  426. package/scaffold/general/agents/Frontend.agent.md +29 -0
  427. package/scaffold/general/agents/Implementer.agent.md +31 -0
  428. package/scaffold/general/agents/Orchestrator.agent.md +104 -0
  429. package/scaffold/general/agents/Planner.agent.md +55 -0
  430. package/scaffold/general/agents/README.md +57 -0
  431. package/scaffold/general/agents/Refactor.agent.md +36 -0
  432. package/scaffold/general/agents/Researcher-Alpha.agent.md +20 -0
  433. package/scaffold/general/agents/Researcher-Beta.agent.md +20 -0
  434. package/scaffold/general/agents/Researcher-Delta.agent.md +20 -0
  435. package/scaffold/general/agents/Researcher-Gamma.agent.md +20 -0
  436. package/scaffold/general/agents/Security.agent.md +42 -0
  437. package/scaffold/general/agents/_shared/adr-protocol.md +91 -0
  438. package/scaffold/general/agents/_shared/architect-reviewer-base.md +50 -0
  439. package/scaffold/general/agents/_shared/code-agent-base.md +88 -0
  440. package/scaffold/general/agents/_shared/code-reviewer-base.md +54 -0
  441. package/scaffold/general/agents/_shared/decision-protocol.md +27 -0
  442. package/scaffold/general/agents/_shared/forge-protocol.md +46 -0
  443. package/scaffold/general/agents/_shared/researcher-base.md +61 -0
  444. package/scaffold/general/agents/templates/adr-template.md +27 -0
  445. package/scaffold/general/agents/templates/execution-state.md +25 -0
  446. package/scaffold/general/prompts/ask.prompt.md +20 -0
  447. package/scaffold/general/prompts/debug.prompt.md +25 -0
  448. package/scaffold/general/prompts/design.prompt.md +22 -0
  449. package/scaffold/general/prompts/implement.prompt.md +26 -0
  450. package/scaffold/general/prompts/plan.prompt.md +24 -0
  451. package/scaffold/general/prompts/review.prompt.md +31 -0
  452. package/scaffold/generate.mjs +74 -0
  453. package/skills/adr-skill/SKILL.md +329 -0
  454. package/skills/adr-skill/assets/templates/adr-madr.md +89 -0
  455. package/skills/adr-skill/assets/templates/adr-readme.md +20 -0
  456. package/skills/adr-skill/assets/templates/adr-simple.md +46 -0
  457. package/skills/adr-skill/references/adr-conventions.md +95 -0
  458. package/skills/adr-skill/references/examples.md +193 -0
  459. package/skills/adr-skill/references/review-checklist.md +77 -0
  460. package/skills/adr-skill/references/template-variants.md +52 -0
  461. package/skills/adr-skill/scripts/bootstrap_adr.js +259 -0
  462. package/skills/adr-skill/scripts/new_adr.js +391 -0
  463. package/skills/adr-skill/scripts/set_adr_status.js +169 -0
  464. package/skills/brainstorming/SKILL.md +259 -0
  465. package/skills/brainstorming/scripts/frame-template.html +365 -0
  466. package/skills/brainstorming/scripts/helper.js +216 -0
  467. package/skills/brainstorming/scripts/server.cjs +9 -0
  468. package/skills/brainstorming/scripts/server.src.cjs +249 -0
  469. package/skills/brainstorming/spec-document-reviewer-prompt.md +49 -0
  470. package/skills/brainstorming/visual-companion.md +430 -0
  471. package/skills/c4-architecture/SKILL.md +295 -0
  472. package/skills/c4-architecture/references/advanced-patterns.md +552 -0
  473. package/skills/c4-architecture/references/c4-syntax.md +492 -0
  474. package/skills/c4-architecture/references/common-mistakes.md +437 -0
  475. package/skills/knowledge-base/SKILL.md +100 -10
  476. package/skills/lesson-learned/SKILL.md +105 -0
  477. package/skills/lesson-learned/references/anti-patterns.md +55 -0
  478. package/skills/lesson-learned/references/se-principles.md +109 -0
  479. package/skills/requirements-clarity/SKILL.md +324 -0
  480. package/skills/session-handoff/SKILL.md +189 -0
  481. package/skills/session-handoff/references/handoff-template.md +139 -0
  482. package/skills/session-handoff/references/resume-checklist.md +80 -0
  483. package/skills/session-handoff/scripts/check_staleness.js +269 -0
  484. package/skills/session-handoff/scripts/create_handoff.js +299 -0
  485. package/skills/session-handoff/scripts/list_handoffs.js +113 -0
  486. package/skills/session-handoff/scripts/validate_handoff.js +241 -0
  487. package/packages/chunker/dist/treesitter-chunker.d.ts +0 -47
  488. package/packages/chunker/dist/treesitter-chunker.js +0 -8
  489. package/packages/cli/dist/commands/init.d.ts +0 -10
  490. package/packages/cli/dist/commands/init.js +0 -308
package/skills/brainstorming/visual-companion.md ADDED
@@ -0,0 +1,430 @@
1
+ # Visual Companion Guide
2
+
3
+ Browser-based visual brainstorming companion for showing mockups, diagrams, and options.
4
+
5
+ ## Quick Reference
6
+
7
+ The browser is a **general-purpose visual canvas** — use it for any content that benefits from visual presentation: diagrams, mockups, explanations, comparisons, and interactive selections.
8
+
9
+ ### Server Lifecycle
10
+
11
+ | What | How | Format |
12
+ |------|-----|--------|
13
+ | Start server | Set `BRAINSTORM_DIR`, run `node scripts/server.cjs` in background | Reads URL from `$BRAINSTORM_DIR/.server-info` |
14
+ | Push a screen | Write an `.html` file to `$BRAINSTORM_DIR/` | Content fragment — no `<html>` or `<head>` needed |
15
+ | Read user picks | Read `$BRAINSTORM_DIR/.events` (JSON lines) | `{"type":"click","choice":"A","text":"...","selected":true}` |
16
+ | Read all state | Read `$BRAINSTORM_DIR/.session-state.json` | `{"currentScreen":"file.html","selections":{...}}` |
17
+ | Show waiting screen | Push HTML with centered `.subtitle` text | Clears stale content when returning to terminal |
18
+ | End session | Kill the node process or let 30-min idle timeout | Files persist in `.brainstorm/` |
19
+
20
+ ### Content Types You Can Show
21
+
22
+ | What | How | Example Use |
23
+ |------|-----|-------------|
24
+ | **Explanatory content** | `<h2>`, `<p>`, `.section`, `.subtitle` | Describe an architecture, explain a concept |
25
+ | **Diagrams** | ASCII art in `<pre>`, SVG, or HTML boxes with arrows | Data flow, state machines, system topology |
26
+ | **Mockups / wireframes** | `.mockup` + `.mockup-header` + `.mockup-body` | UI layouts, component structure, page wireframes |
27
+ | **Side-by-side comparison** | `.split` (2-column grid) | Compare before/after, two layout options |
28
+ | **Pros / cons** | `.pros-cons` > `.pros` + `.cons` | Evaluate a trade-off visually |
29
+ | **Wireframe elements** | `.mock-nav`, `.mock-sidebar`, `.mock-content`, `.mock-button`, `.mock-input`, `.placeholder` | Build interactive-looking wireframes |
30
+ | **Single-select options** | `.options` > `.option` (`.letter` + `.content`) | Pick one from A/B/C |
31
+ | **Multi-select options** | `.options[data-multiselect]` > `.option` | Toggle multiple choices |
32
+ | **Visual cards** | `.cards` > `.card` (`.card-image` + `.card-body`) | Compare visual designs side-by-side |
33
+ | **Any HTML** | Standard HTML + inline styles | Anything the above classes don't cover |
34
+
35
+ ### Diagram Rule
36
+
37
+ > **Never use ASCII box-drawing characters** (`┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼`) for diagrams. LLMs cannot reliably count characters to align box edges. Use one of these instead:
38
+
39
+ | Diagram type | Approach | Why |
40
+ |-------------|----------|-----|
41
+ | Boxes and arrows | **HTML/CSS `<div>` with borders** | Browser handles alignment — always pixel-perfect |
42
+ | Simple linear flow | **ASCII arrows only** (`──▶`, `▼`, `│`) | No boxes to misalign. LLMs handle this fine |
43
+
44
+ ### Minimal Templates
45
+
46
+ **Diagram with HTML boxes (recommended):**
47
+ ```html
48
+ <h2>How Data Flows</h2>
49
+ <p class="subtitle">Request lifecycle through the system</p>
50
+ <div class="mockup">
51
+ <div class="mockup-header">Architecture</div>
52
+ <div class="mockup-body">
53
+ <div style="display:flex;flex-direction:column;align-items:center;gap:12px">
54
+ <div style="display:flex;align-items:center;gap:0">
55
+ <div style="border:2px solid var(--accent);border-radius:6px;padding:8px 16px;text-align:center;min-width:110px"><b>Client</b></div>
56
+ <span style="color:var(--accent);padding:0 6px">──▶</span>
57
+ <div style="border:2px solid var(--accent);border-radius:6px;padding:8px 16px;text-align:center;min-width:110px"><b>API Gateway</b></div>
58
+ <span style="color:var(--accent);padding:0 6px">──▶</span>
59
+ <div style="border:2px solid var(--accent);border-radius:6px;padding:8px 16px;text-align:center;min-width:110px"><b>Auth Service</b></div>
60
+ </div>
61
+ <div style="color:var(--accent)">▼</div>
62
+ <div style="display:flex;align-items:center;gap:0">
63
+ <div style="border:2px solid var(--accent);border-radius:6px;padding:8px 16px;text-align:center;min-width:110px"><b>Router</b></div>
64
+ <span style="color:var(--accent);padding:0 6px">──▶</span>
65
+ <div style="border:2px solid var(--accent);border-radius:6px;padding:8px 16px;text-align:center;min-width:110px"><b>Worker Queue</b></div>
66
+ </div>
67
+ <div style="color:var(--accent)">▼</div>
68
+ <div style="border:2px solid var(--success);border-radius:6px;padding:8px 16px;text-align:center;min-width:110px"><b>Database</b></div>
69
+ </div>
70
+ </div>
71
+ </div>
72
+ ```
73
+
74
+ **Diagram with simple ASCII arrows (also safe):**
75
+ ```html
76
+ <div class="mockup">
77
+ <div class="mockup-header">Architecture</div>
78
+ <div class="mockup-body">
79
+ <pre style="color:var(--accent);font-size:14px;line-height:2">
80
+ Client ──▶ API Gateway ──▶ Auth Service
81
+ │ │
82
+ ▼ ▼
83
+ Router ──────▶ Worker Queue
84
+ │
85
+ ▼
86
+ Database</pre>
87
+ </div>
88
+ </div>
89
+ ```
90
+
91
+ **Side-by-side comparison:**
92
+ ```html
93
+ <h2>Before vs After</h2>
94
+ <div class="split">
95
+ <div class="mockup">
96
+ <div class="mockup-header">Current</div>
97
+ <div class="mockup-body"><!-- current layout --></div>
98
+ </div>
99
+ <div class="mockup">
100
+ <div class="mockup-header">Proposed</div>
101
+ <div class="mockup-body"><!-- proposed layout --></div>
102
+ </div>
103
+ </div>
104
+ ```
105
+
106
+ **Single-select:**
107
+ ```html
108
+ <h2>Pick one</h2>
109
+ <div class="options">
110
+ <div class="option"><div class="letter">A</div><div class="content"><h3>First</h3><p>Description</p></div></div>
111
+ <div class="option"><div class="letter">B</div><div class="content"><h3>Second</h3><p>Description</p></div></div>
112
+ </div>
113
+ ```
114
+
115
+ **Multi-select:**
116
+ ```html
117
+ <h2>Pick any that apply</h2>
118
+ <div class="options" data-multiselect>
119
+ <div class="option"><div class="letter">A</div><div class="content"><h3>First</h3><p>Description</p></div></div>
120
+ <div class="option"><div class="letter">B</div><div class="content"><h3>Second</h3><p>Description</p></div></div>
121
+ </div>
122
+ ```
123
+
124
+ ## When to Use
125
+
126
+ Decide per-question, not per-session. The test: **would the user understand this better by seeing it than reading it?**
127
+
128
+ **Use the browser** when the content itself is visual:
129
+
130
+ - **UI mockups** — wireframes, layouts, navigation structures, component designs
131
+ - **Architecture diagrams** — system components, data flow, relationship maps
132
+ - **Side-by-side visual comparisons** — comparing two layouts, two color schemes, two design directions
133
+ - **Design polish** — when the question is about look and feel, spacing, visual hierarchy
134
+ - **Spatial relationships** — state machines, flowcharts, entity relationships rendered as diagrams
135
+
136
+ **Use the terminal** when the content is text or tabular:
137
+
138
+ - **Requirements and scope questions** — "what does X mean?", "which features are in scope?"
139
+ - **Conceptual A/B/C choices** — picking between approaches described in words
140
+ - **Tradeoff lists** — pros/cons, comparison tables
141
+ - **Technical decisions** — API design, data modeling, architectural approach selection
142
+ - **Clarifying questions** — anything where the answer is words, not a visual preference
143
+
144
+ A question *about* a UI topic is not automatically a visual question. "What kind of wizard do you want?" is conceptual — use the terminal. "Which of these wizard layouts feels right?" is visual — use the browser.
145
+
146
+ ## How It Works
147
+
148
+ The server watches a directory for HTML files and serves the newest one to the browser. You write HTML content — explanations, diagrams, mockups, comparisons, interactive selections, or any visual — and the user sees it in their browser. When the page includes clickable options, selections are recorded to a `.events` file that you read on your next turn.
149
+
150
+ **Content fragments vs full documents:** If your HTML file starts with `<!DOCTYPE` or `<html`, the server serves it as-is (just injects the helper script). Otherwise, the server automatically wraps your content in the frame template — adding the header, CSS theme, selection indicator, and all interactive infrastructure. **Write content fragments by default.** Only write full documents when you need complete control over the page.
151
+
152
+ ## Starting a Session
153
+
154
+ The server is a Node.js script (`scripts/server.cjs`) configured via environment variables. Create a session directory, set env vars, and launch with `node` directly — no shell wrapper needed.
155
+
156
+ **Environment variables:**
157
+
158
+ | Variable | Required | Default | Description |
159
+ |----------|----------|---------|-------------|
160
+ | `BRAINSTORM_DIR` | Yes | `/tmp/brainstorm` | Session directory for HTML files and events |
161
+ | `BRAINSTORM_HOST` | No | `127.0.0.1` | Bind host |
162
+ | `BRAINSTORM_URL_HOST` | No | `localhost` | Hostname shown in returned URL |
163
+ | `BRAINSTORM_PORT` | No | Random high port | Port to listen on |
164
+
165
+ **Steps:**
166
+
167
+ 1. Create session directory: `<project>/.brainstorm/<session-id>/`
168
+ 2. Set `BRAINSTORM_DIR` to that path
169
+ 3. Run `node scripts/server.cjs` as a background process
170
+ 4. Read `$BRAINSTORM_DIR/.server-info` to get the URL and port
171
+
172
+ ```
173
+ # Returns in .server-info:
174
+ {"type":"server-started","port":52341,"url":"http://localhost:52341",
175
+ "screen_dir":"/path/to/project/.brainstorm/12345-1706000000"}
176
+ ```
177
+
178
+ Save `screen_dir` from the response. The server auto-opens the browser on start. If the user can't see the page, remind them of the URL from `.server-info`. Use `--no-auto-open` to disable.
179
+
180
+ **Finding connection info:** The server writes its startup JSON to `$SCREEN_DIR/.server-info`. Read that file to get the URL and port. When using a project directory, check `<project>/.brainstorm/` for the session directory.
181
+
182
+ **Note:** Use a project-relative session directory so mockups persist in `.brainstorm/` and survive server restarts. Without it, files go to `/tmp` and get cleaned up. Remind the user to add `.brainstorm/` to `.gitignore` if it's not already there.
183
+
184
+ **Platform notes:**
185
+
186
+ - **All platforms:** Launch `node scripts/server.cjs` as a background process. On Windows (PowerShell), set env vars with `$env:BRAINSTORM_DIR = "..."` before running. On macOS/Linux, use `BRAINSTORM_DIR=... node scripts/server.cjs &`.
187
+ - **Codex / remote environments:** If background processes are reaped, use the tool's background execution mechanism (e.g., `isBackground: true`).
188
+ - **Remote/containerized setups:** Set `BRAINSTORM_HOST=0.0.0.0` and `BRAINSTORM_URL_HOST=localhost` to bind non-loopback.
189
+
190
+ The server auto-exits after 30 minutes of inactivity.
191
+
192
+ ## The Loop
193
+
194
+ 1. **Check server is alive**, then **write HTML** to a new file in `screen_dir`:
195
+ - Before each write, check that `$SCREEN_DIR/.server-info` exists. If it doesn't (or `.server-stopped` exists), the server has shut down — restart it with `node scripts/server.cjs` before continuing. The server auto-exits after 30 minutes of inactivity.
196
+ - Use semantic filenames: `platform.html`, `visual-style.html`, `layout.html`
197
+ - **Never reuse filenames** — each screen gets a fresh file
198
+ - Use Write tool — **never use cat/heredoc** (dumps noise into terminal)
199
+ - Server automatically serves the newest file
200
+
201
+ 2. **Tell user what to expect and end your turn:**
202
+ - The browser auto-opens on server start. If the user closed it, remind them of the URL from `.server-info`
203
+ - Give a brief text summary of what's on screen (e.g., "Showing 3 layout options for the homepage")
204
+ - Ask them to respond in the terminal: "Take a look and let me know what you think. Click to select an option if you'd like."
205
+
206
+ 3. **On your next turn** — after the user responds in the terminal:
207
+ - Read `$SCREEN_DIR/.events` if it exists — this contains the user's browser interactions (clicks, selections) as JSON lines
208
+ - Merge with the user's terminal text to get the full picture
209
+ - The terminal message is the primary feedback; `.events` provides structured interaction data
210
+
211
+ 4. **Iterate or advance** — if feedback changes current screen, write a new file (e.g., `layout-v2.html`). Only move to the next question when the current step is validated.
212
+
213
+ 5. **Unload when returning to terminal** — when the next step doesn't need the browser (e.g., a clarifying question, a tradeoff discussion), push a waiting screen to clear the stale content:
214
+
215
+ ```html
216
+ <!-- filename: waiting.html (or waiting-2.html, etc.) -->
217
+ <div style="display:flex;align-items:center;justify-content:center;min-height:60vh">
218
+ <p class="subtitle">Continuing in terminal...</p>
219
+ </div>
220
+ ```
221
+
222
+ This prevents the user from staring at a resolved choice while the conversation has moved on. When the next visual question comes up, push a new content file as usual.
223
+
224
+ 6. Repeat until done.
225
+
226
+ ## Writing Content Fragments
227
+
228
+ Write just the content that goes inside the page. The server wraps it in the frame template automatically (header, theme CSS, selection indicator, and all interactive infrastructure).
229
+
230
+ **Minimal example:**
231
+
232
+ ```html
233
+ <h2>Which layout works better?</h2>
234
+ <p class="subtitle">Consider readability and visual hierarchy</p>
235
+
236
+ <div class="options">
237
+ <div class="option" data-choice="a" onclick="toggleSelect(this)">
238
+ <div class="letter">A</div>
239
+ <div class="content">
240
+ <h3>Single Column</h3>
241
+ <p>Clean, focused reading experience</p>
242
+ </div>
243
+ </div>
244
+ <div class="option" data-choice="b" onclick="toggleSelect(this)">
245
+ <div class="letter">B</div>
246
+ <div class="content">
247
+ <h3>Two Column</h3>
248
+ <p>Sidebar navigation with main content</p>
249
+ </div>
250
+ </div>
251
+ </div>
252
+ ```
253
+
254
+ That's it. No `<html>`, no CSS, no `<script>` tags needed. The server provides all of that.
255
+
256
+ ## CSS Classes Available
257
+
258
+ The frame template provides these CSS classes for your content:
259
+
260
+ ### Options (A/B/C choices)
261
+
262
+ ```html
263
+ <div class="options">
264
+ <div class="option" data-choice="a" onclick="toggleSelect(this)">
265
+ <div class="letter">A</div>
266
+ <div class="content">
267
+ <h3>Title</h3>
268
+ <p>Description</p>
269
+ </div>
270
+ </div>
271
+ </div>
272
+ ```
273
+
274
+ **Multi-select:** Add `data-multiselect` to the container to let users select multiple options. Each click toggles the item. The indicator bar shows the count.
275
+
276
+ ```html
277
+ <div class="options" data-multiselect>
278
+ <!-- same option markup — users can select/deselect multiple -->
279
+ </div>
280
+ ```
281
+
282
+ ### Cards (visual designs)
283
+
284
+ ```html
285
+ <div class="cards">
286
+ <div class="card" data-choice="design1" onclick="toggleSelect(this)">
287
+ <div class="card-image"><!-- mockup content --></div>
288
+ <div class="card-body">
289
+ <h3>Name</h3>
290
+ <p>Description</p>
291
+ </div>
292
+ </div>
293
+ </div>
294
+ ```
295
+
296
+ ### Mockup container
297
+
298
+ ```html
299
+ <div class="mockup">
300
+ <div class="mockup-header">Preview: Dashboard Layout</div>
301
+ <div class="mockup-body"><!-- your mockup HTML --></div>
302
+ </div>
303
+ ```
304
+
305
+ ### Split view (side-by-side)
306
+
307
+ ```html
308
+ <div class="split">
309
+ <div class="mockup"><!-- left --></div>
310
+ <div class="mockup"><!-- right --></div>
311
+ </div>
312
+ ```
313
+
314
+ ### Pros/Cons
315
+
316
+ ```html
317
+ <div class="pros-cons">
318
+ <div class="pros"><h4>Pros</h4><ul><li>Benefit</li></ul></div>
319
+ <div class="cons"><h4>Cons</h4><ul><li>Drawback</li></ul></div>
320
+ </div>
321
+ ```
322
+
323
+ ### Mock elements (wireframe building blocks)
324
+
325
+ ```html
326
+ <div class="mock-nav">Logo | Home | About | Contact</div>
327
+ <div style="display: flex;">
328
+ <div class="mock-sidebar">Navigation</div>
329
+ <div class="mock-content">Main content area</div>
330
+ </div>
331
+ <button class="mock-button">Action Button</button>
332
+ <input class="mock-input" placeholder="Input field">
333
+ <div class="placeholder">Placeholder area</div>
334
+ ```
335
+
336
+ ### Typography and sections
337
+
338
+ - `h2` — page title
339
+ - `h3` — section heading
340
+ - `.subtitle` — secondary text below title
341
+ - `.section` — content block with bottom margin
342
+ - `.label` — small uppercase label text
343
+
344
+ ## Browser Events Format
345
+
346
+ When the user clicks options in the browser, their interactions are recorded to `$SCREEN_DIR/.events` (one JSON object per line). The file is cleared automatically when you push a new screen.
347
+
348
+ ```jsonl
349
+ {"type":"click","choice":"a","text":"Option A - Simple Layout","timestamp":1706000101}
350
+ {"type":"click","choice":"c","text":"Option C - Complex Grid","timestamp":1706000108}
351
+ {"type":"click","choice":"b","text":"Option B - Hybrid","timestamp":1706000115}
352
+ ```
353
+
354
+ The full event stream shows the user's exploration path — they may click multiple options before settling. The last `choice` event is typically the final selection, but the pattern of clicks can reveal hesitation or preferences worth asking about.
355
+
356
+ If `.events` doesn't exist, the user didn't interact with the browser — use only their terminal text.
357
+
358
+ ## WebSocket Transport
359
+
360
+ The server supports WebSocket connections on the same port as HTTP. The browser client connects via WebSocket for instant updates:
361
+
362
+ - **New file detected** — server broadcasts `{"type":"new-file","name":"..."}` — page reloads instantly
363
+ - **User clicks option** — POST to `/events` as before, server also broadcasts via WebSocket
364
+
365
+ If the WebSocket connection fails (older browser, network issue), the client automatically falls back to polling every 1.5s, preserving backward compatibility.
366
+
367
+ ## Session State
368
+
369
+ Selections persist across page reloads in `.session-state.json` (in the session directory):
370
+
371
+ - All screens the user has seen
372
+ - All current selections per screen (deselected items are removed)
373
+ - Current screen name and last update timestamp
374
+
375
+ On page load, the client fetches `GET /state` and restores prior selections. The agent can also read `.session-state.json` for a cumulative view of user choices across the session.
376
+
377
+ ## Design Tips
378
+
379
+ - **Scale fidelity to the question** — wireframes for layout, polish for polish questions
380
+ - **Explain the question on each page** — "Which layout feels more professional?" not just "Pick one"
381
+ - **Iterate before advancing** — if feedback changes current screen, write a new version
382
+ - **2-4 options max** per screen
383
+ - **Use real content when it matters** — for a photography portfolio, use actual images (Unsplash). Placeholder content obscures design issues.
384
+ - **Keep mockups simple** — focus on layout and structure, not pixel-perfect design
385
+
386
+ ## File Naming
387
+
388
+ - Use semantic names: `platform.html`, `visual-style.html`, `layout.html`
389
+ - Never reuse filenames — each screen must be a new file
390
+ - For iterations: append version suffix like `layout-v2.html`, `layout-v3.html`
391
+ - Server serves newest file by modification time
392
+
393
+ ## Cleaning Up
394
+
395
+ Kill the Node.js server process (or let the 30-minute idle timeout handle it). Mockup files persist in `.brainstorm/` for later reference. Only `/tmp` sessions get deleted on cleanup.
396
+
397
+ ## Reference
398
+
399
+ - Server (bundled, self-contained): `scripts/server.cjs` — run this, no `npm install` needed
400
+ - Server source (dev): `scripts/server.src.cjs` — requires `pnpm install` at project root
401
+ - Frame template (CSS reference): `scripts/frame-template.html`
402
+ - Helper script (client-side): `scripts/helper.js`
403
+
404
+ ## Future: Blocking Tool Call Pattern (Design Note)
405
+
406
+ > **Status:** Design note only — not implemented. Captured for future reference.
407
+
408
+ ### Concept
409
+
410
+ Instead of the current async loop (write file → user interacts → agent reads on next turn), a blocking MCP tool could unify the interaction into a single agent turn:
411
+
412
+ 1. Agent calls `await_user_selection({ screen: "platform.html", timeout: 120000 })`
413
+ 2. Tool starts WebSocket server, writes HTML, opens browser
414
+ 3. Tool **blocks** (does not return to the LLM)
415
+ 4. User makes selections in browser → WebSocket resolves
416
+ 5. Tool returns `{ selections: [...] }` to the LLM
417
+ 6. Agent continues in the **same turn** with the user's choices
418
+
419
+ ### Benefits
420
+
421
+ - No turn boundary between showing options and receiving feedback
422
+ - Agent can chain multiple visual questions in one turn
423
+ - Closer to a "native" interactive experience
424
+
425
+ ### Constraints
426
+
427
+ - Requires MCP tool to support long-running blocking calls
428
+ - Timeout handling is critical (user may never interact)
429
+ - VS Code Copilot Chat may have turn-level timeouts that conflict
430
+ - Must still fall back gracefully if browser doesn't connect