@phren/cli 0.2.15 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (392) hide show
  1. package/README.md +2 -2
  2. package/dist/agent-instructions.d.ts +12 -0
  3. package/dist/agent-instructions.js +52 -0
  4. package/dist/bridge/agent-hook-stores.d.ts +32 -0
  5. package/dist/bridge/agent-hook-stores.js +67 -0
  6. package/dist/bridge/agent-hooks.d.ts +195 -2
  7. package/dist/bridge/agent-hooks.js +1049 -38
  8. package/dist/bridge/canary.d.ts +27 -0
  9. package/dist/bridge/canary.js +189 -0
  10. package/dist/bridge/changes.d.ts +57 -0
  11. package/dist/bridge/changes.js +403 -0
  12. package/dist/bridge/client.d.ts +3 -0
  13. package/dist/bridge/client.js +36 -0
  14. package/dist/bridge/code-note.d.ts +23 -0
  15. package/dist/bridge/code-note.js +51 -0
  16. package/dist/bridge/code-routes.d.ts +151 -0
  17. package/dist/bridge/code-routes.js +442 -0
  18. package/dist/bridge/codex-threads.d.ts +27 -0
  19. package/dist/bridge/codex-threads.js +442 -0
  20. package/dist/bridge/command.d.ts +7 -0
  21. package/dist/bridge/command.js +50 -5
  22. package/dist/bridge/computer-names.d.ts +4 -0
  23. package/dist/bridge/computer-names.js +16 -0
  24. package/dist/bridge/computers.d.ts +9 -0
  25. package/dist/bridge/computers.js +111 -0
  26. package/dist/bridge/context.d.ts +14 -0
  27. package/dist/bridge/context.js +149 -0
  28. package/dist/bridge/dispatch-command.d.ts +3 -0
  29. package/dist/bridge/dispatch-command.js +93 -0
  30. package/dist/bridge/dispatch-hosts.d.ts +23 -0
  31. package/dist/bridge/dispatch-hosts.js +25 -0
  32. package/dist/bridge/dispatch-returns.d.ts +125 -0
  33. package/dist/bridge/dispatch-returns.js +283 -0
  34. package/dist/bridge/dispatch-tree.d.ts +54 -0
  35. package/dist/bridge/dispatch-tree.js +198 -0
  36. package/dist/bridge/dispatch.d.ts +210 -0
  37. package/dist/bridge/dispatch.js +286 -0
  38. package/dist/bridge/enroll.d.ts +31 -0
  39. package/dist/bridge/enroll.js +236 -0
  40. package/dist/bridge/fanout-messages.d.ts +74 -0
  41. package/dist/bridge/fanout-messages.js +230 -0
  42. package/dist/bridge/fanouts.d.ts +160 -0
  43. package/dist/bridge/fanouts.js +702 -0
  44. package/dist/bridge/file-range.d.ts +16 -0
  45. package/dist/bridge/file-range.js +90 -0
  46. package/dist/bridge/files.d.ts +20 -0
  47. package/dist/bridge/files.js +54 -0
  48. package/dist/bridge/git-publish.d.ts +23 -0
  49. package/dist/bridge/git-publish.js +145 -0
  50. package/dist/bridge/git-worktrees.d.ts +21 -0
  51. package/dist/bridge/git-worktrees.js +150 -0
  52. package/dist/bridge/git.d.ts +54 -0
  53. package/dist/bridge/git.js +552 -0
  54. package/dist/bridge/grants.d.ts +31 -0
  55. package/dist/bridge/grants.js +181 -0
  56. package/dist/bridge/hand-off.d.ts +79 -0
  57. package/dist/bridge/hand-off.js +151 -0
  58. package/dist/bridge/health.d.ts +128 -0
  59. package/dist/bridge/health.js +260 -0
  60. package/dist/bridge/herdr.d.ts +79 -6
  61. package/dist/bridge/herdr.js +292 -27
  62. package/dist/bridge/hook-main.js +2 -0
  63. package/dist/bridge/install.d.ts +28 -1
  64. package/dist/bridge/install.js +225 -38
  65. package/dist/bridge/launch-worktree.d.ts +21 -0
  66. package/dist/bridge/launch-worktree.js +70 -0
  67. package/dist/bridge/limits.d.ts +20 -0
  68. package/dist/bridge/limits.js +65 -0
  69. package/dist/bridge/locate.d.ts +16 -0
  70. package/dist/bridge/locate.js +75 -0
  71. package/dist/bridge/metrics.d.ts +29 -0
  72. package/dist/bridge/metrics.js +71 -0
  73. package/dist/bridge/model-switch.d.ts +35 -0
  74. package/dist/bridge/model-switch.js +250 -0
  75. package/dist/bridge/models.d.ts +46 -0
  76. package/dist/bridge/models.js +257 -0
  77. package/dist/bridge/opencode-approvals.d.ts +6 -0
  78. package/dist/bridge/opencode-approvals.js +60 -0
  79. package/dist/bridge/pane-text.d.ts +15 -0
  80. package/dist/bridge/pane-text.js +23 -0
  81. package/dist/bridge/peers.d.ts +27 -0
  82. package/dist/bridge/peers.js +130 -0
  83. package/dist/bridge/projects.d.ts +12 -1
  84. package/dist/bridge/projects.js +268 -20
  85. package/dist/bridge/protocol.d.ts +35 -2
  86. package/dist/bridge/protocol.js +61 -7
  87. package/dist/bridge/push.d.ts +83 -0
  88. package/dist/bridge/push.js +199 -0
  89. package/dist/bridge/questions.d.ts +38 -0
  90. package/dist/bridge/questions.js +205 -0
  91. package/dist/bridge/schedule-format.d.ts +103 -0
  92. package/dist/bridge/schedule-format.js +266 -0
  93. package/dist/bridge/schedule-launch.d.ts +11 -0
  94. package/dist/bridge/schedule-launch.js +169 -0
  95. package/dist/bridge/schedule-watch.d.ts +54 -0
  96. package/dist/bridge/schedule-watch.js +255 -0
  97. package/dist/bridge/schedules.d.ts +48 -0
  98. package/dist/bridge/schedules.js +205 -0
  99. package/dist/bridge/server-launch.d.ts +14 -0
  100. package/dist/bridge/server-launch.js +218 -0
  101. package/dist/bridge/server-overview.d.ts +45 -0
  102. package/dist/bridge/server-overview.js +102 -0
  103. package/dist/bridge/server-pane-routes.d.ts +36 -0
  104. package/dist/bridge/server-pane-routes.js +479 -0
  105. package/dist/bridge/server-routes.d.ts +108 -0
  106. package/dist/bridge/server-routes.js +556 -0
  107. package/dist/bridge/server-stream.d.ts +46 -0
  108. package/dist/bridge/server-stream.js +253 -0
  109. package/dist/bridge/server.d.ts +3 -15
  110. package/dist/bridge/server.js +162 -264
  111. package/dist/bridge/session-servers.d.ts +24 -0
  112. package/dist/bridge/session-servers.js +136 -0
  113. package/dist/bridge/side-questions.d.ts +74 -0
  114. package/dist/bridge/side-questions.js +252 -0
  115. package/dist/bridge/simulators.d.ts +28 -0
  116. package/dist/bridge/simulators.js +198 -0
  117. package/dist/bridge/speech-transcribe.d.ts +24 -0
  118. package/dist/bridge/speech-transcribe.js +124 -0
  119. package/dist/bridge/speech.d.ts +35 -0
  120. package/dist/bridge/speech.js +98 -0
  121. package/dist/bridge/steps.d.ts +13 -0
  122. package/dist/bridge/steps.js +222 -0
  123. package/dist/bridge/tab-activity.d.ts +18 -0
  124. package/dist/bridge/tab-activity.js +99 -0
  125. package/dist/bridge/terminal-choice.d.ts +64 -0
  126. package/dist/bridge/terminal-choice.js +281 -0
  127. package/dist/bridge/transcript-claude.d.ts +22 -0
  128. package/dist/bridge/transcript-claude.js +353 -0
  129. package/dist/bridge/transcript-codex.d.ts +30 -0
  130. package/dist/bridge/transcript-codex.js +282 -0
  131. package/dist/bridge/transcript-copilot.d.ts +4 -0
  132. package/dist/bridge/transcript-copilot.js +14 -0
  133. package/dist/bridge/transcript-opencode.d.ts +5 -0
  134. package/dist/bridge/transcript-opencode.js +26 -0
  135. package/dist/bridge/transcript-preview.d.ts +96 -0
  136. package/dist/bridge/transcript-preview.js +491 -0
  137. package/dist/bridge/transcripts.d.ts +81 -4
  138. package/dist/bridge/transcripts.js +332 -67
  139. package/dist/bridge/transport.d.ts +3 -0
  140. package/dist/bridge/transport.js +96 -15
  141. package/dist/bridge/uploads.d.ts +15 -0
  142. package/dist/bridge/uploads.js +44 -2
  143. package/dist/bridge/usage.d.ts +124 -0
  144. package/dist/bridge/usage.js +859 -0
  145. package/dist/bridge-hook.mjs +46545 -21051
  146. package/dist/cli/actions.js +14 -1
  147. package/dist/cli/config-policy.js +25 -0
  148. package/dist/cli/config-proactivity.d.ts +3 -1
  149. package/dist/cli/config-proactivity.js +35 -3
  150. package/dist/cli/config.js +4 -1
  151. package/dist/cli/extract.d.ts +0 -8
  152. package/dist/cli/extract.js +4 -7
  153. package/dist/cli/govern.js +5 -2
  154. package/dist/cli/hooks-globs.js +1 -1
  155. package/dist/cli/hooks.d.ts +1 -1
  156. package/dist/cli/hooks.js +9 -7
  157. package/dist/cli/namespaces-projects.js +12 -6
  158. package/dist/cli/namespaces-store.js +37 -6
  159. package/dist/cli/namespaces-tasks.js +1 -1
  160. package/dist/cli/schedules.d.ts +1 -0
  161. package/dist/cli/schedules.js +164 -0
  162. package/dist/cli/session-background.js +1 -1
  163. package/dist/cli/session-git.d.ts +8 -5
  164. package/dist/cli/session-git.js +45 -120
  165. package/dist/cli/session-start.js +3 -1
  166. package/dist/cli/session-stop.js +19 -8
  167. package/dist/cli/team.js +13 -10
  168. package/dist/cli-handlers.d.ts +1 -1
  169. package/dist/cli-handlers.js +8 -4
  170. package/dist/cli-help.d.ts +5 -4
  171. package/dist/cli-help.js +15 -15
  172. package/dist/cli-registry.d.ts +4 -1
  173. package/dist/cli-registry.js +119 -6
  174. package/dist/content/archive.js +2 -2
  175. package/dist/content/citation.d.ts +11 -0
  176. package/dist/content/citation.js +18 -0
  177. package/dist/content/learning.js +2 -0
  178. package/dist/content/summarize.d.ts +14 -15
  179. package/dist/content/summarize.js +60 -5
  180. package/dist/content/validate.d.ts +17 -4
  181. package/dist/content/validate.js +200 -122
  182. package/dist/core/project-registry.d.ts +26 -0
  183. package/dist/core/project-registry.js +573 -0
  184. package/dist/core/project.js +2 -3
  185. package/dist/data/access.d.ts +16 -1
  186. package/dist/data/access.js +31 -3
  187. package/dist/data/tasks.d.ts +18 -3
  188. package/dist/data/tasks.js +8 -7
  189. package/dist/entrypoint.js +44 -10
  190. package/dist/fanout/adapters/claude.d.ts +2 -0
  191. package/dist/fanout/adapters/claude.js +7 -0
  192. package/dist/fanout/adapters/codex.d.ts +2 -0
  193. package/dist/fanout/adapters/codex.js +9 -0
  194. package/dist/fanout/adapters/opencode.d.ts +4 -0
  195. package/dist/fanout/adapters/opencode.js +9 -0
  196. package/dist/fanout/adapters/types.d.ts +21 -0
  197. package/dist/fanout/adapters/types.js +3 -0
  198. package/dist/fanout/command.d.ts +2 -0
  199. package/dist/fanout/command.js +78 -0
  200. package/dist/fanout/launcher.d.ts +27 -0
  201. package/dist/fanout/launcher.js +156 -0
  202. package/dist/fanout/opencode-serve.d.ts +24 -0
  203. package/dist/fanout/opencode-serve.js +191 -0
  204. package/dist/fanout/picker.d.ts +91 -0
  205. package/dist/fanout/picker.js +51 -0
  206. package/dist/fanout/usage.d.ts +5 -0
  207. package/dist/fanout/usage.js +51 -0
  208. package/dist/fanout/watchdog.d.ts +10 -0
  209. package/dist/fanout/watchdog.js +27 -0
  210. package/dist/filenames.d.ts +9 -0
  211. package/dist/filenames.js +11 -0
  212. package/dist/finding/context.js +4 -22
  213. package/dist/generated/memory-ui-graph.browser.js +525 -419
  214. package/dist/governance/policy-constants.d.ts +11 -0
  215. package/dist/governance/policy-constants.js +9 -0
  216. package/dist/governance/policy.d.ts +5 -8
  217. package/dist/governance/policy.js +11 -8
  218. package/dist/graph-core/camera.d.ts +24 -0
  219. package/dist/graph-core/camera.js +18 -0
  220. package/dist/graph-core/index.d.ts +2 -0
  221. package/dist/graph-core/index.js +2 -0
  222. package/dist/graph-core/labels.d.ts +77 -0
  223. package/dist/graph-core/labels.js +124 -0
  224. package/dist/graph-core/model.d.ts +13 -0
  225. package/dist/graph-core/model.js +33 -0
  226. package/dist/graph-core/types.d.ts +2 -0
  227. package/dist/home-paths.d.ts +7 -0
  228. package/dist/home-paths.js +21 -0
  229. package/dist/hooks.d.ts +3 -15
  230. package/dist/hooks.js +14 -1
  231. package/dist/index.js +24 -2
  232. package/dist/init/guard-globals.d.ts +1 -1
  233. package/dist/init/guard-globals.js +4 -4
  234. package/dist/init/init-configure.js +3 -3
  235. package/dist/init/init-uninstall.js +15 -5
  236. package/dist/init/init-walkthrough.js +1 -1
  237. package/dist/init/init.js +26 -6
  238. package/dist/init/management-preset.d.ts +1 -1
  239. package/dist/init/management-preset.js +2 -2
  240. package/dist/init/preferences.js +1 -1
  241. package/dist/init/self-wiring.js +1 -1
  242. package/dist/init/setup.d.ts +3 -26
  243. package/dist/init/setup.js +68 -593
  244. package/dist/init/shared.js +2 -0
  245. package/dist/init/store-gitignore.d.ts +1 -6
  246. package/dist/init/store-gitignore.js +2 -8
  247. package/dist/init/teardown.d.ts +1 -1
  248. package/dist/init/teardown.js +2 -2
  249. package/dist/link/context-imports.d.ts +15 -0
  250. package/dist/link/context-imports.js +101 -0
  251. package/dist/link/context.js +1 -1
  252. package/dist/link/doctor.d.ts +22 -1
  253. package/dist/link/doctor.js +128 -58
  254. package/dist/link/link.js +29 -61
  255. package/dist/link/refresh.js +2 -2
  256. package/dist/link/skills.js +26 -5
  257. package/dist/machine-identity.d.ts +3 -0
  258. package/dist/machine-identity.js +6 -0
  259. package/dist/mcp/profile.d.ts +2 -19
  260. package/dist/mcp/profile.js +64 -22
  261. package/dist/memory-ui-graph.runtime.js +525 -419
  262. package/dist/modules/code-package.d.ts +16 -0
  263. package/dist/modules/code-package.js +160 -0
  264. package/dist/modules/command.d.ts +2 -0
  265. package/dist/modules/command.js +67 -0
  266. package/dist/modules/config.d.ts +4 -0
  267. package/dist/modules/config.js +70 -0
  268. package/dist/modules/manifest.d.ts +41 -0
  269. package/dist/modules/manifest.js +1 -0
  270. package/dist/modules/provision.d.ts +3 -0
  271. package/dist/modules/provision.js +84 -0
  272. package/dist/modules/registry.d.ts +16 -0
  273. package/dist/modules/registry.js +250 -0
  274. package/dist/modules/runtime.d.ts +15 -0
  275. package/dist/modules/runtime.js +59 -0
  276. package/dist/package-metadata.js +10 -2
  277. package/dist/phren-dotenv.js +4 -2
  278. package/dist/phren-paths.d.ts +3 -2
  279. package/dist/phren-paths.js +4 -5
  280. package/dist/profile-store.js +43 -8
  281. package/dist/project-config.d.ts +19 -1
  282. package/dist/project-config.js +29 -3
  283. package/dist/project-topics.d.ts +1 -0
  284. package/dist/project-topics.js +13 -10
  285. package/dist/provider-adapters.js +1 -4
  286. package/dist/query-correlation.js +6 -6
  287. package/dist/session/artifacts.js +5 -5
  288. package/dist/session/checkpoints.js +5 -0
  289. package/dist/session/utils.d.ts +2 -2
  290. package/dist/session/utils.js +6 -6
  291. package/dist/shared/content.d.ts +1 -1
  292. package/dist/shared/content.js +1 -1
  293. package/dist/shared/data-utils.js +1 -1
  294. package/dist/shared/fragment-graph.d.ts +1 -1
  295. package/dist/shared/fragment-graph.js +5 -5
  296. package/dist/shared/index.js +48 -7
  297. package/dist/shared/retrieval.d.ts +18 -3
  298. package/dist/shared/retrieval.js +101 -12
  299. package/dist/shared/search-fallback.js +4 -6
  300. package/dist/shared/sqljs.d.ts +2 -0
  301. package/dist/shared/sqljs.js +4 -2
  302. package/dist/shared.d.ts +0 -1
  303. package/dist/shared.js +0 -1
  304. package/dist/shell/input.d.ts +1 -5
  305. package/dist/shell/input.js +16 -10
  306. package/dist/shell/palette.d.ts +2 -2
  307. package/dist/shell/palette.js +3 -7
  308. package/dist/shell/render.d.ts +3 -1
  309. package/dist/shell/render.js +4 -4
  310. package/dist/shell/shell.js +4 -1
  311. package/dist/shell/types.d.ts +1 -0
  312. package/dist/shell/types.js +4 -0
  313. package/dist/shell/view.d.ts +0 -4
  314. package/dist/shell/view.js +19 -27
  315. package/dist/skill/registry.js +25 -17
  316. package/dist/skill/state.d.ts +3 -0
  317. package/dist/skill/state.js +13 -7
  318. package/dist/status.js +38 -17
  319. package/dist/store-registry.d.ts +44 -18
  320. package/dist/store-registry.js +169 -60
  321. package/dist/store-weight.d.ts +1 -6
  322. package/dist/store-weight.js +4 -2
  323. package/dist/sync/auth-doctor.d.ts +8 -0
  324. package/dist/sync/auth-doctor.js +27 -0
  325. package/dist/sync/auth.d.ts +27 -0
  326. package/dist/sync/auth.js +114 -0
  327. package/dist/sync/conflict-resolve.d.ts +9 -0
  328. package/dist/sync/conflict-resolve.js +146 -0
  329. package/dist/sync/git-state.d.ts +4 -0
  330. package/dist/sync/git-state.js +49 -0
  331. package/dist/sync/outcome.d.ts +34 -0
  332. package/dist/sync/outcome.js +57 -0
  333. package/dist/sync/pull.d.ts +15 -7
  334. package/dist/sync/pull.js +84 -35
  335. package/dist/sync/store-merge.d.ts +29 -0
  336. package/dist/sync/store-merge.js +137 -0
  337. package/dist/sync/task-merge.d.ts +22 -0
  338. package/dist/sync/task-merge.js +158 -0
  339. package/dist/task/github.js +1 -1
  340. package/dist/task/lifecycle.d.ts +5 -0
  341. package/dist/task/lifecycle.js +67 -23
  342. package/dist/terminal-text.d.ts +5 -0
  343. package/dist/terminal-text.js +11 -0
  344. package/dist/test-global-setup.js +7 -0
  345. package/dist/tool-registry.d.ts +1 -1
  346. package/dist/tool-registry.js +3 -1
  347. package/dist/tools/code.d.ts +3 -0
  348. package/dist/tools/code.js +186 -0
  349. package/dist/tools/config.js +8 -0
  350. package/dist/tools/data.js +14 -7
  351. package/dist/tools/dispatch.d.ts +2 -0
  352. package/dist/tools/dispatch.js +66 -0
  353. package/dist/tools/finding.d.ts +11 -0
  354. package/dist/tools/finding.js +180 -123
  355. package/dist/tools/ops.js +5 -2
  356. package/dist/tools/search.js +21 -8
  357. package/dist/tools/session.js +21 -22
  358. package/dist/tools/tasks.js +8 -2
  359. package/dist/tools/types.d.ts +2 -2
  360. package/dist/tools/types.js +2 -2
  361. package/dist/ui/assets.js +1 -1
  362. package/dist/ui/data.js +14 -15
  363. package/dist/ui/deep-void.d.ts +1 -1
  364. package/dist/ui/deep-void.js +0 -1
  365. package/dist/ui/graph-chrome.d.ts +1 -1
  366. package/dist/ui/graph-chrome.js +51 -0
  367. package/dist/ui/page.js +5 -5
  368. package/dist/ui/scripts.js +67 -30
  369. package/dist/ui/server.js +52 -7
  370. package/dist/update.js +22 -11
  371. package/dist/utils-fts.js +1 -0
  372. package/dist/utils-helpers.d.ts +7 -0
  373. package/dist/utils-helpers.js +17 -0
  374. package/dist/utils.d.ts +1 -1
  375. package/dist/utils.js +1 -1
  376. package/package.json +49 -7
  377. package/plugins/opencode/phren-transcript.js +340 -0
  378. package/starter/README.md +4 -4
  379. package/starter/global/{CLAUDE.md → AGENTS.md} +2 -2
  380. package/starter/global/skills/conductor/SKILL.md +106 -0
  381. package/starter/global/skills/fanout/SKILL.md +20 -0
  382. package/starter/global/skills/phren-discover/SKILL.md +6 -6
  383. package/starter/global/skills/phren-init/SKILL.md +4 -4
  384. package/starter/global/skills/phren-sync/SKILL.md +3 -3
  385. package/starter/templates/frontend/reference/README.md +1 -1
  386. package/starter/templates/library/reference/README.md +1 -1
  387. package/starter/templates/monorepo/reference/README.md +1 -1
  388. package/starter/templates/python-project/reference/README.md +1 -1
  389. /package/starter/templates/frontend/{CLAUDE.md → AGENTS.md} +0 -0
  390. /package/starter/templates/library/{CLAUDE.md → AGENTS.md} +0 -0
  391. /package/starter/templates/monorepo/{CLAUDE.md → AGENTS.md} +0 -0
  392. /package/starter/templates/python-project/{CLAUDE.md → AGENTS.md} +0 -0
@@ -2,11 +2,11 @@ import * as crypto from "crypto";
2
2
  import * as fs from "fs";
3
3
  import * as path from "path";
4
4
  import { debugLog } from "./shared.js";
5
- import { withFileLock } from "./shared/governance.js";
5
+ import { withFileLock } from "./governance/locks.js";
6
6
  import { STOP_WORDS, errorMessage, extractKeywords, isValidProjectName } from "./utils.js";
7
7
  import { storeAwareProjectPath } from "./store-routing.js";
8
8
  import { walkDirectory } from "./shared/data-utils.js";
9
- import { FINDINGS_FILENAME } from "./data/access.js";
9
+ import { FINDINGS_FILENAME } from "./filenames.js";
10
10
  const TOPIC_CONFIG_FILENAME = "topic-config.json";
11
11
  const AUTO_TOPIC_MARKER_RE = /^<!--\s*phren:auto-topic(?:\s+slug=([a-z0-9_-]+))?\s*-->$/;
12
12
  const ARCHIVED_SECTION_RE = /^## Archived (\d{4}-\d{2}-\d{2})$/;
@@ -57,7 +57,7 @@ const SOFTWARE_TOPICS = [
57
57
  slug: "architecture",
58
58
  label: "Architecture",
59
59
  description: "System shape, module boundaries, design patterns, and structural decisions.",
60
- keywords: ["architecture", "design", "pattern", "layer", "module", "system", "structure", "microservice", "monolith", "event-driven", "plugin"],
60
+ keywords: ["architecture", "design", "pattern", "layer", "module", "system", "structure", "microservice", "monolith", "event-driven"],
61
61
  },
62
62
  {
63
63
  slug: "debugging",
@@ -81,7 +81,7 @@ const SOFTWARE_TOPICS = [
81
81
  slug: "data",
82
82
  label: "Data",
83
83
  description: "Data models, serialization, parsing, validation, and data flow details.",
84
- keywords: ["data", "model", "schema", "serialize", "deserialize", "json", "csv", "transform", "validate", "parse", "format", "encode"],
84
+ keywords: ["data", "serialize", "deserialize", "json", "csv", "transform", "validate", "parse", "format", "encode"],
85
85
  },
86
86
  {
87
87
  slug: "mobile",
@@ -93,7 +93,7 @@ const SOFTWARE_TOPICS = [
93
93
  slug: "ai_ml",
94
94
  label: "AI / ML",
95
95
  description: "Models, embeddings, prompts, inference, and ML-specific systems.",
96
- keywords: ["ai", "ml", "model", "embedding", "vector", "llm", "prompt", "token", "inference", "training", "neural", "gpt", "claude"],
96
+ keywords: ["ai", "ml", "model", "embedding", "vector", "llm", "prompt", "inference", "training", "neural", "gpt", "claude"],
97
97
  },
98
98
  {
99
99
  slug: "general",
@@ -115,7 +115,7 @@ const DOMAIN_TOPICS = {
115
115
  slug: "production",
116
116
  label: "Production",
117
117
  description: "Session workflow, recording choices, and production techniques.",
118
- keywords: ["production", "recording", "session", "tracking", "workflow", "arrangement", "producer"],
118
+ keywords: ["production", "recording", "session", "tracking", "workflow", "producer"],
119
119
  },
120
120
  {
121
121
  slug: "mixing",
@@ -259,7 +259,7 @@ const DOMAIN_TOPICS = {
259
259
  slug: "style",
260
260
  label: "Style",
261
261
  description: "Tone, diction, constraints, and stylistic direction.",
262
- keywords: ["style", "tone", "voice", "diction", "register", "aesthetic"],
262
+ keywords: ["style", "tone", "diction", "register", "aesthetic"],
263
263
  },
264
264
  {
265
265
  slug: "research",
@@ -412,7 +412,7 @@ function countByTerm(terms) {
412
412
  }
413
413
  function readTopicInputContent(phrenPath, project) {
414
414
  const parts = [];
415
- for (const file of ["CLAUDE.md", FINDINGS_FILENAME]) {
415
+ for (const file of ["AGENTS.md", FINDINGS_FILENAME]) {
416
416
  const filePath = storeAwareProjectPath(phrenPath, project, file);
417
417
  if (!filePath || !fs.existsSync(filePath))
418
418
  continue;
@@ -570,8 +570,11 @@ export function readProjectTopics(phrenPath, project) {
570
570
  const normalized = ensureGeneralTopic(normalizeTopics(parsed.topics));
571
571
  const validationError = validateTopics(normalized);
572
572
  if (validationError) {
573
+ // Falling back silently made a rejected config indistinguishable from having
574
+ // none: `get_config topic` reported source "default" while the file sat
575
+ // plainly on disk, and the only trace was a debug line. Return the reason.
573
576
  debugLog(`readProjectTopics: invalid ${configPath}: ${validationError}`);
574
- return { source: "default", topics: builtinTopics };
577
+ return { source: "default", topics: builtinTopics, error: validationError };
575
578
  }
576
579
  return { source: "custom", topics: normalized, domain: typeof parsed.domain === "string" ? parsed.domain : undefined };
577
580
  }
@@ -898,7 +901,7 @@ function tokenizeSuggestionTerms(text) {
898
901
  }
899
902
  function collectSuggestionCorpus(phrenPath, project) {
900
903
  const parts = [];
901
- for (const file of ["CLAUDE.md", "summary.md", FINDINGS_FILENAME]) {
904
+ for (const file of ["AGENTS.md", "summary.md", FINDINGS_FILENAME]) {
902
905
  const filePath = storeAwareProjectPath(phrenPath, project, file);
903
906
  if (!filePath || !fs.existsSync(filePath))
904
907
  continue;
@@ -1,10 +1,7 @@
1
1
  import * as fs from "fs";
2
- import * as os from "os";
3
2
  import * as path from "path";
3
+ import { homeDir } from "./phren-paths.js";
4
4
  export const HOOK_TOOL_NAMES = ["claude", "copilot", "cursor", "codex"];
5
- function homeDir(env = process.env) {
6
- return env.HOME || env.USERPROFILE || os.homedir();
7
- }
8
5
  function joinPortable(base, ...parts) {
9
6
  const usePosix = base.startsWith("/") && !base.includes("\\");
10
7
  if (usePosix) {
@@ -86,10 +86,10 @@ export function markCorrelationsHelpful(phrenPath, sessionId, docKey) {
86
86
  debugLog(`query-correlation mark-helpful failed: ${errorMessage(err)}`);
87
87
  }
88
88
  }
89
- /**
90
- * Tokenize a keyword string for overlap comparison.
91
- */
92
- function tokenize(text) {
89
+ /** Lowercased whitespace-separated keywords for overlap comparison. Unlike the
90
+ * search fallback it keeps punctuation and does not stem: correlation keys
91
+ * are stored keyword strings, compared as written. */
92
+ function keywordSet(text) {
93
93
  return new Set(text
94
94
  .toLowerCase()
95
95
  .split(/\s+/)
@@ -113,14 +113,14 @@ export function getCorrelatedDocs(phrenPath, keywords, limit = 3) {
113
113
  const lines = raw.split("\n").filter(Boolean);
114
114
  // Only look at last RECENT_WINDOW entries to keep it fast
115
115
  const recent = lines.slice(-RECENT_WINDOW);
116
- const queryTokens = tokenize(keywords);
116
+ const queryTokens = keywordSet(keywords);
117
117
  if (queryTokens.size === 0)
118
118
  return [];
119
119
  const docScores = new Map();
120
120
  for (const line of recent) {
121
121
  try {
122
122
  const entry = JSON.parse(line);
123
- const entryTokens = tokenize(entry.keywords);
123
+ const entryTokens = keywordSet(entry.keywords);
124
124
  // Calculate overlap between current query and past query
125
125
  let overlap = 0;
126
126
  for (const t of queryTokens) {
@@ -2,13 +2,13 @@ import * as crypto from "crypto";
2
2
  import * as fs from "fs";
3
3
  import * as path from "path";
4
4
  import { withFileLock } from "../shared/governance.js";
5
- import { atomicWriteJson, debugError, readSessionStateFile, scanSessionFiles, sessionFileForId, sessionsDir, writeSessionStateFile, } from "./utils.js";
5
+ import { atomicWriteJson, debugError, readSessionStateFile, scanSessionFiles, sessionFileForId, runtimeSessionsDir, writeSessionStateFile, } from "./utils.js";
6
6
  function normalizeSummary(summary) {
7
7
  const trimmed = summary?.trim();
8
8
  return trimmed ? trimmed : undefined;
9
9
  }
10
10
  function sessionMessagesFileForId(phrenPath, sessionId) {
11
- return path.join(sessionsDir(phrenPath), `session-${sessionId}-messages.json`);
11
+ return path.join(runtimeSessionsDir(phrenPath), `session-${sessionId}-messages.json`);
12
12
  }
13
13
  function inferProjectForSession(phrenPath, sessionId) {
14
14
  return readSessionState(phrenPath, sessionId)?.project;
@@ -53,7 +53,7 @@ function parseSessionMessagesSnapshot(filePath) {
53
53
  }
54
54
  }
55
55
  function listSessionMessageSnapshots(phrenPath) {
56
- const dir = sessionsDir(phrenPath);
56
+ const dir = runtimeSessionsDir(phrenPath);
57
57
  let entries;
58
58
  try {
59
59
  entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -88,7 +88,7 @@ function listSessionMessageSnapshots(phrenPath) {
88
88
  return snapshots;
89
89
  }
90
90
  export function lastSummaryPath(phrenPath) {
91
- return path.join(sessionsDir(phrenPath), "last-summary.json");
91
+ return path.join(runtimeSessionsDir(phrenPath), "last-summary.json");
92
92
  }
93
93
  export function readLastSummary(phrenPath) {
94
94
  try {
@@ -129,7 +129,7 @@ export function findMostRecentSummaryWithProject(phrenPath, project) {
129
129
  if (fastPath && (!project || fastPath.project === project)) {
130
130
  return fastPath;
131
131
  }
132
- const dir = sessionsDir(phrenPath);
132
+ const dir = runtimeSessionsDir(phrenPath);
133
133
  const results = scanSessionFiles(dir, readSessionStateFile, (state) => typeof state.summary === "string" && state.summary.trim().length > 0, { errorScope: "findMostRecentSummaryWithProject" });
134
134
  if (!project) {
135
135
  if (results.length === 0)
@@ -1,3 +1,4 @@
1
+ import { moduleEnabled } from "../modules/runtime.js";
1
2
  import * as fs from "fs";
2
3
  import * as path from "path";
3
4
  import { errorMessage } from "../utils.js";
@@ -51,6 +52,8 @@ function readCheckpointFile(filePath) {
51
52
  }
52
53
  }
53
54
  export function writeTaskCheckpoint(phrenPath, checkpoint) {
55
+ if (!moduleEnabled(phrenPath, "tasks"))
56
+ return;
54
57
  const filePath = checkpointPath(phrenPath, checkpoint.project, checkpoint.taskId);
55
58
  const normalizedCheckpoint = {
56
59
  ...checkpoint,
@@ -59,6 +62,8 @@ export function writeTaskCheckpoint(phrenPath, checkpoint) {
59
62
  atomicWriteJson(filePath, normalizedCheckpoint);
60
63
  }
61
64
  export function listTaskCheckpoints(phrenPath, project) {
65
+ if (!moduleEnabled(phrenPath, "tasks"))
66
+ return [];
62
67
  const dir = checkpointDir(phrenPath);
63
68
  let files;
64
69
  try {
@@ -1,3 +1,4 @@
1
+ export { sessionsDir } from "../phren-paths.js";
1
2
  /**
2
3
  * Write JSON to a file atomically using temp-file + rename.
3
4
  * Ensures the parent directory exists before writing.
@@ -17,7 +18,7 @@ export interface SessionState {
17
18
  /** When true, this session was created by the coding agent runtime. */
18
19
  agentCreated?: boolean;
19
20
  }
20
- export declare function sessionsDir(phrenPath: string): string;
21
+ export declare function runtimeSessionsDir(phrenPath: string): string;
21
22
  export declare function sessionFileForId(phrenPath: string, sessionId: string): string;
22
23
  export declare function isSessionStateFileName(name: string): boolean;
23
24
  export declare function readSessionStateFile(file: string): SessionState | null;
@@ -43,4 +44,3 @@ export declare function scanSessionFiles<T>(dir: string, parse: (filePath: strin
43
44
  includeMtime?: boolean;
44
45
  errorScope?: string;
45
46
  }): SessionFileEntry<T>[];
46
- export {};
@@ -1,23 +1,23 @@
1
1
  import * as fs from "fs";
2
2
  import * as path from "path";
3
3
  import { errorMessage } from "../utils.js";
4
+ // The experimental agent imports the sessions directory from here.
5
+ export { sessionsDir } from "../phren-paths.js";
6
+ import { atomicWriteText } from "../phren-paths.js";
4
7
  /**
5
8
  * Write JSON to a file atomically using temp-file + rename.
6
9
  * Ensures the parent directory exists before writing.
7
10
  */
8
11
  export function atomicWriteJson(filePath, data) {
9
- fs.mkdirSync(path.dirname(filePath), { recursive: true });
10
- const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
11
- fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2) + "\n");
12
- fs.renameSync(tmpPath, filePath);
12
+ atomicWriteText(filePath, JSON.stringify(data, null, 2) + "\n");
13
13
  }
14
- export function sessionsDir(phrenPath) {
14
+ export function runtimeSessionsDir(phrenPath) {
15
15
  const dir = path.join(phrenPath, ".runtime", "sessions");
16
16
  fs.mkdirSync(dir, { recursive: true });
17
17
  return dir;
18
18
  }
19
19
  export function sessionFileForId(phrenPath, sessionId) {
20
- return path.join(sessionsDir(phrenPath), `session-${sessionId}.json`);
20
+ return path.join(runtimeSessionsDir(phrenPath), `session-${sessionId}.json`);
21
21
  }
22
22
  export function isSessionStateFileName(name) {
23
23
  return name.startsWith("session-") &&
@@ -1,4 +1,4 @@
1
- export { type ConsolidationNeeded, type ConsolidationStatus, checkConsolidationNeeded, validateFindingsFormat, stripTaskDoneSection, validateTaskFormat, extractConflictVersions, mergeFindings, mergeTask, autoMergeConflicts, } from "../content/validate.js";
1
+ export { type ConsolidationNeeded, type ConsolidationStatus, checkConsolidationNeeded, validateFindingsFormat, stripTaskDoneSection, validateTaskFormat, extractConflictVersions, mergeFindings, mergeTask, isAutoMergeableStorePath, autoMergeConflicts, } from "../content/validate.js";
2
2
  export { filterTrustedFindings, filterTrustedFindingsDetailed, } from "../content/citation.js";
3
3
  export { scanForSecrets, resolveCoref, isDuplicateFinding, detectConflicts, extractDynamicEntities, checkSemanticDedup, checkSemanticConflicts, } from "../content/dedup.js";
4
4
  export { countActiveFindings, autoArchiveToReference, } from "../content/archive.js";
@@ -1,5 +1,5 @@
1
1
  // Barrel re-export. Internal code imports from the specific modules directly.
2
- export { checkConsolidationNeeded, validateFindingsFormat, stripTaskDoneSection, validateTaskFormat, extractConflictVersions, mergeFindings, mergeTask, autoMergeConflicts, } from "../content/validate.js";
2
+ export { checkConsolidationNeeded, validateFindingsFormat, stripTaskDoneSection, validateTaskFormat, extractConflictVersions, mergeFindings, mergeTask, isAutoMergeableStorePath, autoMergeConflicts, } from "../content/validate.js";
3
3
  export { filterTrustedFindings, filterTrustedFindingsDetailed, } from "../content/citation.js";
4
4
  export { scanForSecrets, resolveCoref, isDuplicateFinding, detectConflicts, extractDynamicEntities, checkSemanticDedup, checkSemanticConflicts, } from "../content/dedup.js";
5
5
  export { countActiveFindings, autoArchiveToReference, } from "../content/archive.js";
@@ -1,7 +1,7 @@
1
1
  import * as fs from "fs";
2
2
  import * as path from "path";
3
3
  import { phrenErr, PhrenError, phrenOk, parsePhrenErrorCode, } from "../shared.js";
4
- import { withFileLock as withFileLockRaw } from "./governance.js";
4
+ import { withFileLock as withFileLockRaw } from "../governance/locks.js";
5
5
  import { isValidProjectName, safeProjectPath, errorMessage } from "../utils.js";
6
6
  import { resolveProject } from "../store-routing.js";
7
7
  export function withSafeLock(filePath, fn) {
@@ -34,7 +34,7 @@ export declare function extractFragmentNames(content: string): string[];
34
34
  */
35
35
  export declare function ensureGlobalEntitiesTable(db: SqlJsDatabase): void;
36
36
  /**
37
- * Prime CLAUDE.md fragments per project for a single build pass.
37
+ * Prime AGENTS.md fragments per project for a single build pass.
38
38
  * During an active build, extractAndLinkFragments resolves user fragments from this
39
39
  * in-memory map and avoids per-file sync stat/read calls.
40
40
  */
@@ -152,7 +152,7 @@ export function ensureGlobalEntitiesTable(db) {
152
152
  }
153
153
  }
154
154
  /**
155
- * Parse user-defined fragment names from CLAUDE.md frontmatter.
155
+ * Parse user-defined fragment names from AGENTS.md frontmatter.
156
156
  * Looks for: <!-- phren:fragments: Redis,MyService,InternalAPI -->
157
157
  * Also supports legacy: <!-- phren:entities: ... -->
158
158
  *
@@ -175,7 +175,7 @@ function readUserDefinedFragmentsFromDisk(claudeMdPath) {
175
175
  return { mtime: stat.mtimeMs, fragments };
176
176
  }
177
177
  /**
178
- * Prime CLAUDE.md fragments per project for a single build pass.
178
+ * Prime AGENTS.md fragments per project for a single build pass.
179
179
  * During an active build, extractAndLinkFragments resolves user fragments from this
180
180
  * in-memory map and avoids per-file sync stat/read calls.
181
181
  */
@@ -187,7 +187,7 @@ export function beginUserFragmentBuildCache(phrenPath, projects) {
187
187
  // it goes through path.join: concatenating with "/" reads fine on Windows
188
188
  // but produces a mixed-separator string that no other code path matches.
189
189
  const cacheKey = `${phrenPath}/${project}`;
190
- const claudeMdPath = path.join(phrenPath, project, "CLAUDE.md");
190
+ const claudeMdPath = path.join(phrenPath, project, "AGENTS.md");
191
191
  try {
192
192
  const loaded = readUserDefinedFragmentsFromDisk(claudeMdPath);
193
193
  if (!loaded) {
@@ -214,7 +214,7 @@ export function endUserFragmentBuildCache(phrenPath) {
214
214
  _activeBuildCacheKeyPrefix = null;
215
215
  }
216
216
  function parseUserDefinedFragments(phrenPath, project) {
217
- const claudeMdPath = path.join(phrenPath, project, "CLAUDE.md");
217
+ const claudeMdPath = path.join(phrenPath, project, "AGENTS.md");
218
218
  const cacheKey = `${phrenPath}/${project}`;
219
219
  try {
220
220
  // Active build path: no sync I/O in per-file extraction.
@@ -319,7 +319,7 @@ export function extractAndLinkFragments(db, content, sourceDoc, phrenPath) {
319
319
  for (const phrase of capitalizedPhrases) {
320
320
  fragmentNames.push(phrase);
321
321
  }
322
- // Add user-defined fragments from CLAUDE.md frontmatter
322
+ // Add user-defined fragments from AGENTS.md frontmatter
323
323
  if (phrenPath) {
324
324
  const projectMatch = sourceDoc.match(/^([^/]+)\//);
325
325
  if (projectMatch) {
@@ -1,3 +1,5 @@
1
+ import { moduleSnapshot } from "../modules/runtime.js";
2
+ import { skillEnabled } from "../modules/provision.js";
1
3
  import * as fs from "fs";
2
4
  import * as path from "path";
3
5
  import * as os from "os";
@@ -153,6 +155,7 @@ async function _drainEmbQueue() {
153
155
  }
154
156
  }
155
157
  const FILE_TYPE_MAP = {
158
+ "agents.md": "claude",
156
159
  "claude.md": "claude",
157
160
  "summary.md": "summary",
158
161
  "findings.md": "findings",
@@ -299,7 +302,7 @@ function computePhrenHash(phrenPath, profile, preGlobbed) {
299
302
  matched.add(f);
300
303
  }
301
304
  for (const f of matched) {
302
- if (ownership === "repo-managed" && path.basename(f).toLowerCase() === "claude.md")
305
+ if (ownership === "repo-managed" && path.basename(f).toLowerCase() === "agents.md")
303
306
  continue;
304
307
  files.push(path.join(dir, f));
305
308
  }
@@ -516,7 +519,7 @@ function getRepoManagedInstructionEntries(phrenPath, project) {
516
519
  const repoDir = getProjectSourcePath(phrenPath, project);
517
520
  if (!repoDir)
518
521
  return [];
519
- const candidates = ["CLAUDE.md", path.join(".claude", "CLAUDE.md")];
522
+ const candidates = ["AGENTS.md", "CLAUDE.md", path.join(".claude", "CLAUDE.md")];
520
523
  const entries = [];
521
524
  for (const relFile of candidates) {
522
525
  const fullPath = path.join(repoDir, relFile);
@@ -541,6 +544,7 @@ function globAllFiles(phrenPath, profile) {
541
544
  for (const dir of projectDirs) {
542
545
  const projectName = path.basename(dir);
543
546
  const storePath = path.dirname(dir);
547
+ const modules = moduleSnapshot(storePath, profile);
544
548
  const config = readProjectConfig(storePath, projectName);
545
549
  const ownership = getProjectOwnershipMode(storePath, projectName, config);
546
550
  const mdFilesSet = new Set();
@@ -558,10 +562,14 @@ function globAllFiles(phrenPath, profile) {
558
562
  const relFiles = [...mdFilesSet].sort();
559
563
  for (const relFile of relFiles) {
560
564
  const filename = path.basename(relFile);
561
- if (ownership === "repo-managed" && filename.toLowerCase() === "claude.md")
565
+ if (ownership === "repo-managed" && ["agents.md", "claude.md"].includes(filename.toLowerCase()))
562
566
  continue;
563
567
  const fullPath = path.join(dir, relFile);
564
568
  const type = classifyFile(filename, relFile);
569
+ if (type === "task" && !modules.has("tasks"))
570
+ continue;
571
+ if (relFile.startsWith("skills/") && !skillEnabled(storePath, relFile.split("/")[1], profile))
572
+ continue;
565
573
  entries.push({ fullPath, project: projectName, filename, type, relFile });
566
574
  allAbsolutePaths.push(fullPath);
567
575
  }
@@ -577,6 +585,8 @@ function globAllFiles(phrenPath, profile) {
577
585
  if (fs.existsSync(globalSkillsDir)) {
578
586
  const skillFiles = globSync("**/*.md", { cwd: globalSkillsDir, nodir: true });
579
587
  for (const relFile of skillFiles) {
588
+ if (!skillEnabled(phrenPath, relFile.split("/")[0], profile))
589
+ continue;
580
590
  const fullPath = path.join(globalSkillsDir, relFile);
581
591
  const filename = path.basename(relFile);
582
592
  entries.push({ fullPath, project: "global", filename, type: "skill", relFile: `skills/${relFile}` });
@@ -646,7 +656,7 @@ function extractLegacyTopicSlug(entry) {
646
656
  * Build-scoped memo for `readProjectTopics()`.
647
657
  *
648
658
  * `readProjectTopics` derives adaptive topics by reading and tokenising the
649
- * *whole* project corpus — CLAUDE.md, FINDINGS.md and every reference/*.md —
659
+ * *whole* project corpus — AGENTS.md, FINDINGS.md and every reference/*.md —
650
660
  * on each call (see `buildTopicContentSignal` in project-topics.ts). It is
651
661
  * called once per reference document, so a project with R reference docs read
652
662
  * and tokenised its own corpus R times per rebuild. Measured on a 1892-file
@@ -776,6 +786,11 @@ export function updateFileInIndex(db, filePath, phrenPath) {
776
786
  const project = rel.split(path.sep)[0];
777
787
  const relFile = rel.split(path.sep).slice(1).join(path.sep);
778
788
  const type = classifyFile(filename, relFile);
789
+ const modules = moduleSnapshot(phrenPath);
790
+ if (type === "task" && !modules.has("tasks"))
791
+ return;
792
+ if (relFile.startsWith("skills/") && !skillEnabled(phrenPath, relFile.split("/")[1]))
793
+ return;
779
794
  const entry = { fullPath: resolvedPath, project, filename, type, relFile };
780
795
  // Single read feeds the insert, fragment extraction and the content hash.
781
796
  const raw = readFileOrNull(resolvedPath);
@@ -1683,7 +1698,7 @@ function isDbOpen(db) {
1683
1698
  }
1684
1699
  export async function buildIndex(phrenPath, profile, options = {}) {
1685
1700
  const debounceMs = getIndexDebounceMs();
1686
- const buildKey = `${phrenPath}|${profile ?? ""}`;
1701
+ const buildKey = storeCacheKey(phrenPath, profile);
1687
1702
  if (!options.force &&
1688
1703
  debounceMs > 0 &&
1689
1704
  _lastBuiltDb !== null &&
@@ -1721,8 +1736,10 @@ function ftsCacheRoot() {
1721
1736
  * Identity therefore has to live in the path.
1722
1737
  */
1723
1738
  function storeCacheKey(phrenPath, profile) {
1739
+ const generations = [...new Set([phrenPath, ...getAllStoreProjectDirs(phrenPath, profile).map(dir => path.dirname(dir))])]
1740
+ .sort().map(store => moduleSnapshot(store, profile).generation).join("|");
1724
1741
  return crypto.createHash("sha1")
1725
- .update(`${path.resolve(phrenPath)}|${profile ?? ""}`)
1742
+ .update(`${path.resolve(phrenPath)}|${profile ?? ""}|${generations}`)
1726
1743
  .digest("hex")
1727
1744
  .slice(0, 16);
1728
1745
  }
@@ -1948,6 +1965,24 @@ export function findFtsCacheForPath(phrenPath, profile) {
1948
1965
  }
1949
1966
  return { exists: false };
1950
1967
  }
1968
+ /**
1969
+ * The nearest ancestor of `dir` (itself included) that is a git checkout named
1970
+ * `project`, compared case-insensitively. Used only when a project's
1971
+ * registered source folder doesn't exist on this machine.
1972
+ */
1973
+ function localCheckoutNamed(dir, project) {
1974
+ const wanted = project.toLowerCase();
1975
+ let current = dir;
1976
+ for (;;) {
1977
+ if (path.basename(current).toLowerCase() === wanted && fs.existsSync(path.join(current, ".git"))) {
1978
+ return current;
1979
+ }
1980
+ const parent = path.dirname(current);
1981
+ if (parent === current)
1982
+ return null;
1983
+ current = parent;
1984
+ }
1985
+ }
1951
1986
  export function detectProject(phrenPath, cwd, profile) {
1952
1987
  const manifest = readRootManifest(phrenPath);
1953
1988
  if (manifest?.installMode === "project-local") {
@@ -1963,8 +1998,14 @@ export function detectProject(phrenPath, cwd, profile) {
1963
1998
  // Try the project's own store path first (handles team store projects),
1964
1999
  // then fall back to primary phrenPath
1965
2000
  const storePhrenPath = path.dirname(dir);
1966
- const sourcePath = getProjectSourcePath(storePhrenPath, projectName)
2001
+ const configuredPath = getProjectSourcePath(storePhrenPath, projectName)
1967
2002
  || getProjectSourcePath(phrenPath, projectName);
2003
+ // The store is shared between computers, so the registered folder may be
2004
+ // another machine's (e.g. /home/other/Projects/x). When it doesn't exist
2005
+ // here, fall back to the checkout on this machine named after the project.
2006
+ const sourcePath = configuredPath && fs.existsSync(configuredPath)
2007
+ ? configuredPath
2008
+ : localCheckoutNamed(resolvedCwd, projectName) ?? configuredPath;
1968
2009
  if (!sourcePath)
1969
2010
  continue;
1970
2011
  // Exact first. Then case-insensitive: a sourcePath written on a
@@ -28,6 +28,23 @@ export declare function wantsTasks(prompt: string, intent: ReturnType<typeof det
28
28
  export declare function detectTaskIntent(prompt: string): "debug" | "review" | "build" | "docs" | "skill" | "general";
29
29
  export declare function fileRelevanceBoost(filePath: string, changedFiles: Set<string>): number;
30
30
  export declare function branchMatchBoost(content: string, branch: string | undefined): number;
31
+ /** A doc's bullets (with their continuation lines) or, with none, its
32
+ * paragraphs: the unit relevance is judged on. Topic archives are one doc
33
+ * with hundreds of bullets, so a whole-file score matches almost anything. */
34
+ export declare function contentChunks(content: string, maxChunks?: number): string[];
35
+ export interface ChunkMatch {
36
+ chunk: string;
37
+ distinct: number;
38
+ rarity: number;
39
+ }
40
+ /** The doc's best chunk for this prompt: most summed keyword rarity among
41
+ * chunks with the most distinct keyword matches. */
42
+ export declare function bestChunkMatch(queryTokens: string[], doc: Pick<DocRow, "content">, rarity?: Map<string, number>): ChunkMatch | null;
43
+ /** How rare each prompt token is across the index: normalised IDF, 1 for a
44
+ * token in one doc, near 0 for one in every doc. One FTS count per token. */
45
+ /** `tokenRarity` for a prompt's keywords, tokenised as the floor tokenises them. */
46
+ export declare function promptRarity(db: SqlJsDatabase | null | undefined, keywords: string): Map<string, number>;
47
+ export declare function tokenRarity(db: SqlJsDatabase | null | undefined, queryTokens: string[]): Map<string, number>;
31
48
  /**
32
49
  * Item 4: Reciprocal Rank Fusion — merges ranked result lists from multiple search tiers.
33
50
  * Documents appearing in multiple tiers get a higher combined score.
@@ -35,8 +52,6 @@ export declare function branchMatchBoost(content: string, branch: string | undef
35
52
  */
36
53
  /** @internal Exported for tests. */
37
54
  export declare function rrfMerge(tiers: DocRow[][], k?: number): DocRow[];
38
- /** @internal Exported for tests. */
39
- export declare function shouldRunVectorExpansion(rows: DocRow[] | null, prompt: string, desiredResults?: number): boolean;
40
55
  declare function approximateTokens(text: string): number;
41
56
  export declare function filterTaskByPriority(items: string[], allowedPriorities?: string[]): string[];
42
57
  export declare function searchDocuments(db: SqlJsDatabase, safeQuery: string, prompt: string, keywords: string, detectedProject: string | null, searchAllProjects?: boolean, phrenPath?: string): DocRow[] | null;
@@ -141,7 +156,7 @@ export { DEFAULT_MIN_QUERY_RELEVANCE };
141
156
  export declare function applyRelevanceFloor(rows: DocRow[], keywords: string, gitCtx: {
142
157
  branch?: string;
143
158
  changedFiles?: Set<string>;
144
- } | null, detectedProject: string | null, floor?: number): DocRow[];
159
+ } | null, detectedProject: string | null, floor?: number, rarity?: Map<string, number>): DocRow[];
145
160
  export declare function selectSnippets(rows: DocRow[], keywords: string, tokenBudget: number, lineBudget: number, charBudget: number): {
146
161
  selected: SelectedSnippet[];
147
162
  usedTokens: number;