@draht/coding-agent 2026.5.12 → 2026.7.7-1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (680) hide show
  1. package/CHANGELOG.md +47 -0
  2. package/README.md +1 -4
  3. package/bin/draht-tools.cjs +3756 -1
  4. package/dist/bun/cli.d.ts.map +1 -1
  5. package/dist/bun/cli.js +4 -2
  6. package/dist/bun/cli.js.map +1 -1
  7. package/dist/bun/register-bedrock.d.ts.map +1 -1
  8. package/dist/bun/register-bedrock.js +1 -1
  9. package/dist/bun/register-bedrock.js.map +1 -1
  10. package/dist/bun/restore-sandbox-env.d.ts +17 -0
  11. package/dist/bun/restore-sandbox-env.d.ts.map +1 -0
  12. package/dist/bun/restore-sandbox-env.js +36 -0
  13. package/dist/bun/restore-sandbox-env.js.map +1 -0
  14. package/dist/cli/args.d.ts +9 -4
  15. package/dist/cli/args.d.ts.map +1 -1
  16. package/dist/cli/args.js +91 -38
  17. package/dist/cli/args.js.map +1 -1
  18. package/dist/cli/config-selector.d.ts +5 -3
  19. package/dist/cli/config-selector.d.ts.map +1 -1
  20. package/dist/cli/config-selector.js +1 -1
  21. package/dist/cli/config-selector.js.map +1 -1
  22. package/dist/cli/file-processor.d.ts.map +1 -1
  23. package/dist/cli/file-processor.js +13 -26
  24. package/dist/cli/file-processor.js.map +1 -1
  25. package/dist/cli/initial-message.d.ts +1 -1
  26. package/dist/cli/initial-message.d.ts.map +1 -1
  27. package/dist/cli/initial-message.js.map +1 -1
  28. package/dist/cli/list-models.d.ts +1 -1
  29. package/dist/cli/list-models.d.ts.map +1 -1
  30. package/dist/cli/list-models.js +7 -1
  31. package/dist/cli/list-models.js.map +1 -1
  32. package/dist/cli/project-trust.d.ts +10 -0
  33. package/dist/cli/project-trust.d.ts.map +1 -0
  34. package/dist/cli/project-trust.js +48 -0
  35. package/dist/cli/project-trust.js.map +1 -0
  36. package/dist/cli/session-picker.d.ts +3 -2
  37. package/dist/cli/session-picker.d.ts.map +1 -1
  38. package/dist/cli/session-picker.js +5 -4
  39. package/dist/cli/session-picker.js.map +1 -1
  40. package/dist/cli/startup-ui.d.ts +20 -0
  41. package/dist/cli/startup-ui.d.ts.map +1 -0
  42. package/dist/cli/startup-ui.js +184 -0
  43. package/dist/cli/startup-ui.js.map +1 -0
  44. package/dist/cli.d.ts.map +1 -1
  45. package/dist/cli.js +7 -4
  46. package/dist/cli.js.map +1 -1
  47. package/dist/config.d.ts +27 -13
  48. package/dist/config.d.ts.map +1 -1
  49. package/dist/config.js +284 -63
  50. package/dist/config.js.map +1 -1
  51. package/dist/core/agent-session-runtime.d.ts +45 -9
  52. package/dist/core/agent-session-runtime.d.ts.map +1 -1
  53. package/dist/core/agent-session-runtime.js +100 -33
  54. package/dist/core/agent-session-runtime.js.map +1 -1
  55. package/dist/core/agent-session-services.d.ts +6 -4
  56. package/dist/core/agent-session-services.d.ts.map +1 -1
  57. package/dist/core/agent-session-services.js +7 -4
  58. package/dist/core/agent-session-services.js.map +1 -1
  59. package/dist/core/agent-session.d.ts +55 -33
  60. package/dist/core/agent-session.d.ts.map +1 -1
  61. package/dist/core/agent-session.js +560 -492
  62. package/dist/core/agent-session.js.map +1 -1
  63. package/dist/core/auth-guidance.d.ts +5 -0
  64. package/dist/core/auth-guidance.d.ts.map +1 -0
  65. package/dist/core/auth-guidance.js +21 -0
  66. package/dist/core/auth-guidance.js.map +1 -0
  67. package/dist/core/auth-storage.d.ts +21 -13
  68. package/dist/core/auth-storage.d.ts.map +1 -1
  69. package/dist/core/auth-storage.js +48 -28
  70. package/dist/core/auth-storage.js.map +1 -1
  71. package/dist/core/bash-executor.d.ts +1 -15
  72. package/dist/core/bash-executor.d.ts.map +1 -1
  73. package/dist/core/bash-executor.js +10 -24
  74. package/dist/core/bash-executor.js.map +1 -1
  75. package/dist/core/builtins/subagent.d.ts.map +1 -1
  76. package/dist/core/builtins/subagent.js +1 -2
  77. package/dist/core/builtins/subagent.js.map +1 -1
  78. package/dist/core/compaction/branch-summarization.d.ts +9 -5
  79. package/dist/core/compaction/branch-summarization.d.ts.map +1 -1
  80. package/dist/core/compaction/branch-summarization.js +10 -4
  81. package/dist/core/compaction/branch-summarization.js.map +1 -1
  82. package/dist/core/compaction/compaction.d.ts +8 -7
  83. package/dist/core/compaction/compaction.d.ts.map +1 -1
  84. package/dist/core/compaction/compaction.js +56 -47
  85. package/dist/core/compaction/compaction.js.map +1 -1
  86. package/dist/core/compaction/index.d.ts +3 -3
  87. package/dist/core/compaction/index.d.ts.map +1 -1
  88. package/dist/core/compaction/index.js.map +1 -1
  89. package/dist/core/compaction/utils.d.ts +1 -1
  90. package/dist/core/compaction/utils.d.ts.map +1 -1
  91. package/dist/core/compaction/utils.js +1 -1
  92. package/dist/core/compaction/utils.js.map +1 -1
  93. package/dist/core/exec.d.ts.map +1 -1
  94. package/dist/core/exec.js.map +1 -1
  95. package/dist/core/experimental.d.ts +2 -0
  96. package/dist/core/experimental.d.ts.map +1 -0
  97. package/dist/core/experimental.js +4 -0
  98. package/dist/core/experimental.js.map +1 -0
  99. package/dist/core/export-html/ansi-to-html.d.ts.map +1 -1
  100. package/dist/core/export-html/ansi-to-html.js +1 -1
  101. package/dist/core/export-html/ansi-to-html.js.map +1 -1
  102. package/dist/core/export-html/index.d.ts +1 -1
  103. package/dist/core/export-html/index.d.ts.map +1 -1
  104. package/dist/core/export-html/index.js +13 -11
  105. package/dist/core/export-html/index.js.map +1 -1
  106. package/dist/core/export-html/template.css +69 -4
  107. package/dist/core/export-html/template.js +231 -57
  108. package/dist/core/export-html/tool-renderer.d.ts +0 -6
  109. package/dist/core/export-html/tool-renderer.d.ts.map +1 -1
  110. package/dist/core/export-html/tool-renderer.js +15 -2
  111. package/dist/core/export-html/tool-renderer.js.map +1 -1
  112. package/dist/core/export-html/vendor/marked.min.js +75 -3
  113. package/dist/core/extensions/index.d.ts +8 -8
  114. package/dist/core/extensions/index.d.ts.map +1 -1
  115. package/dist/core/extensions/index.js.map +1 -1
  116. package/dist/core/extensions/loader.d.ts +5 -6
  117. package/dist/core/extensions/loader.d.ts.map +1 -1
  118. package/dist/core/extensions/loader.js +98 -43
  119. package/dist/core/extensions/loader.js.map +1 -1
  120. package/dist/core/extensions/runner.d.ts +31 -12
  121. package/dist/core/extensions/runner.d.ts.map +1 -1
  122. package/dist/core/extensions/runner.js +248 -33
  123. package/dist/core/extensions/runner.js.map +1 -1
  124. package/dist/core/extensions/types.d.ts +191 -36
  125. package/dist/core/extensions/types.d.ts.map +1 -1
  126. package/dist/core/extensions/types.js.map +1 -1
  127. package/dist/core/extensions/wrapper.d.ts.map +1 -1
  128. package/dist/core/extensions/wrapper.js +2 -2
  129. package/dist/core/extensions/wrapper.js.map +1 -1
  130. package/dist/core/footer-data-provider.d.ts +7 -1
  131. package/dist/core/footer-data-provider.d.ts.map +1 -1
  132. package/dist/core/footer-data-provider.js +78 -54
  133. package/dist/core/footer-data-provider.js.map +1 -1
  134. package/dist/core/http-dispatcher.d.ts +22 -0
  135. package/dist/core/http-dispatcher.d.ts.map +1 -0
  136. package/dist/core/http-dispatcher.js +91 -0
  137. package/dist/core/http-dispatcher.js.map +1 -0
  138. package/dist/core/index.d.ts +9 -8
  139. package/dist/core/index.d.ts.map +1 -1
  140. package/dist/core/index.js +2 -1
  141. package/dist/core/index.js.map +1 -1
  142. package/dist/core/keybindings.d.ts +67 -2
  143. package/dist/core/keybindings.d.ts.map +1 -1
  144. package/dist/core/keybindings.js +59 -7
  145. package/dist/core/keybindings.js.map +1 -1
  146. package/dist/core/model-registry.d.ts +24 -5
  147. package/dist/core/model-registry.d.ts.map +1 -1
  148. package/dist/core/model-registry.js +188 -51
  149. package/dist/core/model-registry.js.map +1 -1
  150. package/dist/core/model-resolver.d.ts +12 -1
  151. package/dist/core/model-resolver.d.ts.map +1 -1
  152. package/dist/core/model-resolver.js +84 -39
  153. package/dist/core/model-resolver.js.map +1 -1
  154. package/dist/core/output-guard.d.ts +1 -0
  155. package/dist/core/output-guard.d.ts.map +1 -1
  156. package/dist/core/output-guard.js +52 -22
  157. package/dist/core/output-guard.js.map +1 -1
  158. package/dist/core/package-manager.d.ts +22 -4
  159. package/dist/core/package-manager.d.ts.map +1 -1
  160. package/dist/core/package-manager.js +455 -157
  161. package/dist/core/package-manager.js.map +1 -1
  162. package/dist/core/project-trust.d.ts +15 -0
  163. package/dist/core/project-trust.d.ts.map +1 -0
  164. package/dist/core/project-trust.js +59 -0
  165. package/dist/core/project-trust.js.map +1 -0
  166. package/dist/core/prompt-templates.d.ts +13 -11
  167. package/dist/core/prompt-templates.d.ts.map +1 -1
  168. package/dist/core/prompt-templates.js +67 -76
  169. package/dist/core/prompt-templates.js.map +1 -1
  170. package/dist/core/provider-attribution.d.ts +4 -0
  171. package/dist/core/provider-attribution.d.ts.map +1 -0
  172. package/dist/core/provider-attribution.js +72 -0
  173. package/dist/core/provider-attribution.js.map +1 -0
  174. package/dist/core/provider-display-names.d.ts +2 -0
  175. package/dist/core/provider-display-names.d.ts.map +1 -0
  176. package/dist/core/provider-display-names.js +36 -0
  177. package/dist/core/provider-display-names.js.map +1 -0
  178. package/dist/core/resolve-config-value.d.ts +13 -6
  179. package/dist/core/resolve-config-value.d.ts.map +1 -1
  180. package/dist/core/resolve-config-value.js +143 -22
  181. package/dist/core/resolve-config-value.js.map +1 -1
  182. package/dist/core/resource-loader.d.ts +36 -15
  183. package/dist/core/resource-loader.d.ts.map +1 -1
  184. package/dist/core/resource-loader.js +178 -79
  185. package/dist/core/resource-loader.js.map +1 -1
  186. package/dist/core/sdk.d.ts +34 -18
  187. package/dist/core/sdk.d.ts.map +1 -1
  188. package/dist/core/sdk.js +47 -16
  189. package/dist/core/sdk.js.map +1 -1
  190. package/dist/core/session-manager.d.ts +32 -14
  191. package/dist/core/session-manager.d.ts.map +1 -1
  192. package/dist/core/session-manager.js +366 -209
  193. package/dist/core/session-manager.js.map +1 -1
  194. package/dist/core/settings-manager.d.ts +62 -6
  195. package/dist/core/settings-manager.d.ts.map +1 -1
  196. package/dist/core/settings-manager.js +230 -40
  197. package/dist/core/settings-manager.js.map +1 -1
  198. package/dist/core/skills.d.ts +10 -10
  199. package/dist/core/skills.d.ts.map +1 -1
  200. package/dist/core/skills.js +13 -35
  201. package/dist/core/skills.js.map +1 -1
  202. package/dist/core/slash-commands.d.ts +1 -1
  203. package/dist/core/slash-commands.d.ts.map +1 -1
  204. package/dist/core/slash-commands.js +7 -4
  205. package/dist/core/slash-commands.js.map +1 -1
  206. package/dist/core/source-info.d.ts +1 -1
  207. package/dist/core/source-info.d.ts.map +1 -1
  208. package/dist/core/source-info.js.map +1 -1
  209. package/dist/core/system-prompt.d.ts +4 -4
  210. package/dist/core/system-prompt.d.ts.map +1 -1
  211. package/dist/core/system-prompt.js +20 -16
  212. package/dist/core/system-prompt.js.map +1 -1
  213. package/dist/core/telemetry.d.ts +3 -0
  214. package/dist/core/telemetry.d.ts.map +1 -0
  215. package/dist/core/telemetry.js +9 -0
  216. package/dist/core/telemetry.js.map +1 -0
  217. package/dist/core/timings.d.ts +4 -2
  218. package/dist/core/timings.d.ts.map +1 -1
  219. package/dist/core/timings.js +24 -14
  220. package/dist/core/timings.js.map +1 -1
  221. package/dist/core/tools/bash.d.ts +11 -16
  222. package/dist/core/tools/bash.d.ts.map +1 -1
  223. package/dist/core/tools/bash.js +187 -178
  224. package/dist/core/tools/bash.js.map +1 -1
  225. package/dist/core/tools/edit-diff.d.ts +26 -5
  226. package/dist/core/tools/edit-diff.d.ts.map +1 -1
  227. package/dist/core/tools/edit-diff.js +110 -23
  228. package/dist/core/tools/edit-diff.js.map +1 -1
  229. package/dist/core/tools/edit.d.ts +22 -24
  230. package/dist/core/tools/edit.d.ts.map +1 -1
  231. package/dist/core/tools/edit.js +201 -113
  232. package/dist/core/tools/edit.js.map +1 -1
  233. package/dist/core/tools/file-mutation-queue.d.ts.map +1 -1
  234. package/dist/core/tools/file-mutation-queue.js +27 -12
  235. package/dist/core/tools/file-mutation-queue.js.map +1 -1
  236. package/dist/core/tools/find.d.ts +7 -18
  237. package/dist/core/tools/find.d.ts.map +1 -1
  238. package/dist/core/tools/find.js +148 -101
  239. package/dist/core/tools/find.js.map +1 -1
  240. package/dist/core/tools/grep.d.ts +11 -30
  241. package/dist/core/tools/grep.d.ts.map +1 -1
  242. package/dist/core/tools/grep.js +23 -12
  243. package/dist/core/tools/grep.js.map +1 -1
  244. package/dist/core/tools/index.d.ts +26 -101
  245. package/dist/core/tools/index.d.ts.map +1 -1
  246. package/dist/core/tools/index.js +78 -52
  247. package/dist/core/tools/index.js.map +1 -1
  248. package/dist/core/tools/ls.d.ts +6 -15
  249. package/dist/core/tools/ls.d.ts.map +1 -1
  250. package/dist/core/tools/ls.js +12 -17
  251. package/dist/core/tools/ls.js.map +1 -1
  252. package/dist/core/tools/output-accumulator.d.ts +52 -0
  253. package/dist/core/tools/output-accumulator.d.ts.map +1 -0
  254. package/dist/core/tools/output-accumulator.js +184 -0
  255. package/dist/core/tools/output-accumulator.js.map +1 -0
  256. package/dist/core/tools/path-utils.d.ts +2 -0
  257. package/dist/core/tools/path-utils.d.ts.map +1 -1
  258. package/dist/core/tools/path-utils.js +40 -22
  259. package/dist/core/tools/path-utils.js.map +1 -1
  260. package/dist/core/tools/read.d.ts +7 -18
  261. package/dist/core/tools/read.d.ts.map +1 -1
  262. package/dist/core/tools/read.js +103 -52
  263. package/dist/core/tools/read.js.map +1 -1
  264. package/dist/core/tools/render-utils.d.ts +5 -2
  265. package/dist/core/tools/render-utils.d.ts.map +1 -1
  266. package/dist/core/tools/render-utils.js +18 -2
  267. package/dist/core/tools/render-utils.js.map +1 -1
  268. package/dist/core/tools/tool-definition-wrapper.d.ts.map +1 -1
  269. package/dist/core/tools/tool-definition-wrapper.js +2 -0
  270. package/dist/core/tools/tool-definition-wrapper.js.map +1 -1
  271. package/dist/core/tools/truncate.d.ts.map +1 -1
  272. package/dist/core/tools/truncate.js +12 -2
  273. package/dist/core/tools/truncate.js.map +1 -1
  274. package/dist/core/tools/write.d.ts +5 -14
  275. package/dist/core/tools/write.d.ts.map +1 -1
  276. package/dist/core/tools/write.js +27 -46
  277. package/dist/core/tools/write.js.map +1 -1
  278. package/dist/core/trust-manager.d.ts +36 -0
  279. package/dist/core/trust-manager.d.ts.map +1 -0
  280. package/dist/core/trust-manager.js +202 -0
  281. package/dist/core/trust-manager.js.map +1 -0
  282. package/dist/index.d.ts +33 -29
  283. package/dist/index.d.ts.map +1 -1
  284. package/dist/index.js +12 -9
  285. package/dist/index.js.map +1 -1
  286. package/dist/main.d.ts +5 -1
  287. package/dist/main.d.ts.map +1 -1
  288. package/dist/main.js +208 -93
  289. package/dist/main.js.map +1 -1
  290. package/dist/migrations.d.ts +2 -2
  291. package/dist/migrations.d.ts.map +1 -1
  292. package/dist/migrations.js +4 -4
  293. package/dist/migrations.js.map +1 -1
  294. package/dist/modes/index.d.ts +5 -5
  295. package/dist/modes/index.d.ts.map +1 -1
  296. package/dist/modes/index.js.map +1 -1
  297. package/dist/modes/interactive/assets/clankolas.png +0 -0
  298. package/dist/modes/interactive/components/assistant-message.d.ts +5 -1
  299. package/dist/modes/interactive/components/assistant-message.d.ts.map +1 -1
  300. package/dist/modes/interactive/components/assistant-message.js +37 -15
  301. package/dist/modes/interactive/components/assistant-message.js.map +1 -1
  302. package/dist/modes/interactive/components/bash-execution.d.ts +1 -1
  303. package/dist/modes/interactive/components/bash-execution.d.ts.map +1 -1
  304. package/dist/modes/interactive/components/bash-execution.js +3 -3
  305. package/dist/modes/interactive/components/bash-execution.js.map +1 -1
  306. package/dist/modes/interactive/components/bordered-loader.d.ts.map +1 -1
  307. package/dist/modes/interactive/components/bordered-loader.js +3 -0
  308. package/dist/modes/interactive/components/bordered-loader.js.map +1 -1
  309. package/dist/modes/interactive/components/config-selector.d.ts +36 -5
  310. package/dist/modes/interactive/components/config-selector.d.ts.map +1 -1
  311. package/dist/modes/interactive/components/config-selector.js +318 -36
  312. package/dist/modes/interactive/components/config-selector.js.map +1 -1
  313. package/dist/modes/interactive/components/countdown-timer.d.ts +2 -2
  314. package/dist/modes/interactive/components/countdown-timer.d.ts.map +1 -1
  315. package/dist/modes/interactive/components/countdown-timer.js +2 -2
  316. package/dist/modes/interactive/components/countdown-timer.js.map +1 -1
  317. package/dist/modes/interactive/components/custom-editor.d.ts +1 -1
  318. package/dist/modes/interactive/components/custom-editor.d.ts.map +1 -1
  319. package/dist/modes/interactive/components/custom-editor.js.map +1 -1
  320. package/dist/modes/interactive/components/custom-entry.d.ts +19 -0
  321. package/dist/modes/interactive/components/custom-entry.d.ts.map +1 -0
  322. package/dist/modes/interactive/components/custom-entry.js +52 -0
  323. package/dist/modes/interactive/components/custom-entry.js.map +1 -0
  324. package/dist/modes/interactive/components/custom-message.d.ts +2 -2
  325. package/dist/modes/interactive/components/custom-message.d.ts.map +1 -1
  326. package/dist/modes/interactive/components/custom-message.js.map +1 -1
  327. package/dist/modes/interactive/components/diff.d.ts.map +1 -1
  328. package/dist/modes/interactive/components/diff.js.map +1 -1
  329. package/dist/modes/interactive/components/earendil-announcement.d.ts.map +1 -1
  330. package/dist/modes/interactive/components/earendil-announcement.js.map +1 -1
  331. package/dist/modes/interactive/components/extension-editor.d.ts +3 -1
  332. package/dist/modes/interactive/components/extension-editor.d.ts.map +1 -1
  333. package/dist/modes/interactive/components/extension-editor.js +26 -9
  334. package/dist/modes/interactive/components/extension-editor.js.map +1 -1
  335. package/dist/modes/interactive/components/extension-input.d.ts.map +1 -1
  336. package/dist/modes/interactive/components/extension-input.js.map +1 -1
  337. package/dist/modes/interactive/components/extension-selector.d.ts +2 -0
  338. package/dist/modes/interactive/components/extension-selector.d.ts.map +1 -1
  339. package/dist/modes/interactive/components/extension-selector.js +8 -3
  340. package/dist/modes/interactive/components/extension-selector.js.map +1 -1
  341. package/dist/modes/interactive/components/first-time-setup.d.ts +25 -0
  342. package/dist/modes/interactive/components/first-time-setup.d.ts.map +1 -0
  343. package/dist/modes/interactive/components/first-time-setup.js +103 -0
  344. package/dist/modes/interactive/components/first-time-setup.js.map +1 -0
  345. package/dist/modes/interactive/components/footer.d.ts +4 -3
  346. package/dist/modes/interactive/components/footer.d.ts.map +1 -1
  347. package/dist/modes/interactive/components/footer.js +27 -7
  348. package/dist/modes/interactive/components/footer.js.map +1 -1
  349. package/dist/modes/interactive/components/index.d.ts +33 -31
  350. package/dist/modes/interactive/components/index.d.ts.map +1 -1
  351. package/dist/modes/interactive/components/index.js +2 -0
  352. package/dist/modes/interactive/components/index.js.map +1 -1
  353. package/dist/modes/interactive/components/keybinding-hints.d.ts +5 -0
  354. package/dist/modes/interactive/components/keybinding-hints.d.ts.map +1 -1
  355. package/dist/modes/interactive/components/keybinding-hints.js +19 -5
  356. package/dist/modes/interactive/components/keybinding-hints.js.map +1 -1
  357. package/dist/modes/interactive/components/login-dialog.d.ts +12 -2
  358. package/dist/modes/interactive/components/login-dialog.d.ts.map +1 -1
  359. package/dist/modes/interactive/components/login-dialog.js +45 -11
  360. package/dist/modes/interactive/components/login-dialog.js.map +1 -1
  361. package/dist/modes/interactive/components/model-selector.d.ts +2 -2
  362. package/dist/modes/interactive/components/model-selector.d.ts.map +1 -1
  363. package/dist/modes/interactive/components/model-selector.js +10 -6
  364. package/dist/modes/interactive/components/model-selector.js.map +1 -1
  365. package/dist/modes/interactive/components/oauth-selector.d.ts +18 -6
  366. package/dist/modes/interactive/components/oauth-selector.d.ts.map +1 -1
  367. package/dist/modes/interactive/components/oauth-selector.js +93 -25
  368. package/dist/modes/interactive/components/oauth-selector.js.map +1 -1
  369. package/dist/modes/interactive/components/scoped-models-selector.d.ts +5 -12
  370. package/dist/modes/interactive/components/scoped-models-selector.d.ts.map +1 -1
  371. package/dist/modes/interactive/components/scoped-models-selector.js +49 -31
  372. package/dist/modes/interactive/components/scoped-models-selector.js.map +1 -1
  373. package/dist/modes/interactive/components/session-selector.d.ts +2 -2
  374. package/dist/modes/interactive/components/session-selector.d.ts.map +1 -1
  375. package/dist/modes/interactive/components/session-selector.js +33 -14
  376. package/dist/modes/interactive/components/session-selector.js.map +1 -1
  377. package/dist/modes/interactive/components/settings-selector.d.ts +17 -0
  378. package/dist/modes/interactive/components/settings-selector.d.ts.map +1 -1
  379. package/dist/modes/interactive/components/settings-selector.js +301 -20
  380. package/dist/modes/interactive/components/settings-selector.js.map +1 -1
  381. package/dist/modes/interactive/components/skill-invocation-message.d.ts +1 -1
  382. package/dist/modes/interactive/components/skill-invocation-message.d.ts.map +1 -1
  383. package/dist/modes/interactive/components/skill-invocation-message.js.map +1 -1
  384. package/dist/modes/interactive/components/status-indicator.d.ts +28 -0
  385. package/dist/modes/interactive/components/status-indicator.d.ts.map +1 -0
  386. package/dist/modes/interactive/components/status-indicator.js +60 -0
  387. package/dist/modes/interactive/components/status-indicator.js.map +1 -0
  388. package/dist/modes/interactive/components/thinking-selector.d.ts.map +1 -1
  389. package/dist/modes/interactive/components/thinking-selector.js +1 -1
  390. package/dist/modes/interactive/components/thinking-selector.js.map +1 -1
  391. package/dist/modes/interactive/components/tool-execution.d.ts +6 -1
  392. package/dist/modes/interactive/components/tool-execution.d.ts.map +1 -1
  393. package/dist/modes/interactive/components/tool-execution.js +57 -14
  394. package/dist/modes/interactive/components/tool-execution.js.map +1 -1
  395. package/dist/modes/interactive/components/tree-selector.d.ts +1 -1
  396. package/dist/modes/interactive/components/tree-selector.d.ts.map +1 -1
  397. package/dist/modes/interactive/components/tree-selector.js +137 -13
  398. package/dist/modes/interactive/components/tree-selector.js.map +1 -1
  399. package/dist/modes/interactive/components/trust-selector.d.ts +23 -0
  400. package/dist/modes/interactive/components/trust-selector.d.ts.map +1 -0
  401. package/dist/modes/interactive/components/trust-selector.js +91 -0
  402. package/dist/modes/interactive/components/trust-selector.js.map +1 -0
  403. package/dist/modes/interactive/components/user-message-selector.d.ts +2 -2
  404. package/dist/modes/interactive/components/user-message-selector.d.ts.map +1 -1
  405. package/dist/modes/interactive/components/user-message-selector.js +8 -7
  406. package/dist/modes/interactive/components/user-message-selector.js.map +1 -1
  407. package/dist/modes/interactive/components/user-message.d.ts +6 -1
  408. package/dist/modes/interactive/components/user-message.d.ts.map +1 -1
  409. package/dist/modes/interactive/components/user-message.js +22 -8
  410. package/dist/modes/interactive/components/user-message.js.map +1 -1
  411. package/dist/modes/interactive/interactive-mode.d.ts +76 -19
  412. package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
  413. package/dist/modes/interactive/interactive-mode.js +1294 -494
  414. package/dist/modes/interactive/interactive-mode.js.map +1 -1
  415. package/dist/modes/interactive/model-search.d.ts +12 -0
  416. package/dist/modes/interactive/model-search.d.ts.map +1 -0
  417. package/dist/modes/interactive/model-search.js +15 -0
  418. package/dist/modes/interactive/model-search.js.map +1 -0
  419. package/dist/modes/interactive/theme/dark.json +5 -4
  420. package/dist/modes/interactive/theme/light.json +5 -4
  421. package/dist/modes/interactive/theme/theme-controller.d.ts +29 -0
  422. package/dist/modes/interactive/theme/theme-controller.d.ts.map +1 -0
  423. package/dist/modes/interactive/theme/theme-controller.js +102 -0
  424. package/dist/modes/interactive/theme/theme-controller.js.map +1 -0
  425. package/dist/modes/interactive/theme/theme-schema.json +2 -1
  426. package/dist/modes/interactive/theme/theme.d.ts +41 -3
  427. package/dist/modes/interactive/theme/theme.d.ts.map +1 -1
  428. package/dist/modes/interactive/theme/theme.js +183 -106
  429. package/dist/modes/interactive/theme/theme.js.map +1 -1
  430. package/dist/modes/print-mode.d.ts.map +1 -1
  431. package/dist/modes/print-mode.js +40 -20
  432. package/dist/modes/print-mode.js.map +1 -1
  433. package/dist/modes/rpc/rpc-client.d.ts +30 -5
  434. package/dist/modes/rpc/rpc-client.d.ts.map +1 -1
  435. package/dist/modes/rpc/rpc-client.js +87 -8
  436. package/dist/modes/rpc/rpc-client.js.map +1 -1
  437. package/dist/modes/rpc/rpc-mode.d.ts +2 -2
  438. package/dist/modes/rpc/rpc-mode.d.ts.map +1 -1
  439. package/dist/modes/rpc/rpc-mode.js +113 -31
  440. package/dist/modes/rpc/rpc-mode.js.map +1 -1
  441. package/dist/modes/rpc/rpc-types.d.ts +42 -4
  442. package/dist/modes/rpc/rpc-types.d.ts.map +1 -1
  443. package/dist/modes/rpc/rpc-types.js.map +1 -1
  444. package/dist/package-manager-cli.d.ts +6 -2
  445. package/dist/package-manager-cli.d.ts.map +1 -1
  446. package/dist/package-manager-cli.js +504 -25
  447. package/dist/package-manager-cli.js.map +1 -1
  448. package/dist/prompts/agents/build.md +38 -0
  449. package/dist/prompts/agents/plan.md +36 -0
  450. package/dist/prompts/agents/verify.md +36 -4
  451. package/dist/prompts/commands/brainstorm.md +162 -0
  452. package/dist/prompts/commands/discuss-phase.md +1 -1
  453. package/dist/prompts/commands/execute-phase.md +4 -1
  454. package/dist/prompts/commands/fix.md +12 -0
  455. package/dist/prompts/commands/init-project.md +1 -0
  456. package/dist/prompts/commands/map-codebase.md +15 -1
  457. package/dist/prompts/commands/new-project.md +1 -0
  458. package/dist/prompts/commands/next-milestone.md +2 -0
  459. package/dist/prompts/commands/orchestrate.md +4 -4
  460. package/dist/prompts/commands/plan-phase.md +5 -0
  461. package/dist/prompts/commands/quick.md +4 -0
  462. package/dist/prompts/commands/review.md +4 -1
  463. package/dist/prompts/commands/verify-work.md +10 -8
  464. package/dist/rpc-entry.d.ts +3 -0
  465. package/dist/rpc-entry.d.ts.map +1 -0
  466. package/dist/rpc-entry.js +10 -0
  467. package/dist/rpc-entry.js.map +1 -0
  468. package/dist/utils/ansi.d.ts +2 -0
  469. package/dist/utils/ansi.d.ts.map +1 -0
  470. package/dist/utils/ansi.js +52 -0
  471. package/dist/utils/ansi.js.map +1 -0
  472. package/dist/utils/changelog.d.ts +2 -1
  473. package/dist/utils/changelog.d.ts.map +1 -1
  474. package/dist/utils/changelog.js +78 -0
  475. package/dist/utils/changelog.js.map +1 -1
  476. package/dist/utils/child-process.d.ts +12 -5
  477. package/dist/utils/child-process.d.ts.map +1 -1
  478. package/dist/utils/child-process.js +33 -5
  479. package/dist/utils/child-process.js.map +1 -1
  480. package/dist/utils/clipboard-image.d.ts.map +1 -1
  481. package/dist/utils/clipboard-image.js +2 -2
  482. package/dist/utils/clipboard-image.js.map +1 -1
  483. package/dist/utils/clipboard-native.d.ts +3 -1
  484. package/dist/utils/clipboard-native.d.ts.map +1 -1
  485. package/dist/utils/clipboard-native.js +14 -8
  486. package/dist/utils/clipboard-native.js.map +1 -1
  487. package/dist/utils/clipboard.d.ts.map +1 -1
  488. package/dist/utils/clipboard.js +84 -45
  489. package/dist/utils/clipboard.js.map +1 -1
  490. package/dist/utils/deprecation.d.ts +4 -0
  491. package/dist/utils/deprecation.d.ts.map +1 -0
  492. package/dist/utils/deprecation.js +13 -0
  493. package/dist/utils/deprecation.js.map +1 -0
  494. package/dist/utils/exif-orientation.d.ts +1 -1
  495. package/dist/utils/exif-orientation.d.ts.map +1 -1
  496. package/dist/utils/exif-orientation.js.map +1 -1
  497. package/dist/utils/fs-watch.d.ts +5 -0
  498. package/dist/utils/fs-watch.d.ts.map +1 -0
  499. package/dist/utils/fs-watch.js +25 -0
  500. package/dist/utils/fs-watch.js.map +1 -0
  501. package/dist/utils/git.d.ts.map +1 -1
  502. package/dist/utils/git.js +54 -22
  503. package/dist/utils/git.js.map +1 -1
  504. package/dist/utils/html.d.ts +7 -0
  505. package/dist/utils/html.d.ts.map +1 -0
  506. package/dist/utils/html.js +40 -0
  507. package/dist/utils/html.js.map +1 -0
  508. package/dist/utils/image-convert.d.ts +1 -0
  509. package/dist/utils/image-convert.d.ts.map +1 -1
  510. package/dist/utils/image-convert.js +21 -15
  511. package/dist/utils/image-convert.js.map +1 -1
  512. package/dist/utils/image-process.d.ts +18 -0
  513. package/dist/utils/image-process.d.ts.map +1 -0
  514. package/dist/utils/image-process.js +83 -0
  515. package/dist/utils/image-process.js.map +1 -0
  516. package/dist/utils/image-resize-core.d.ts +30 -0
  517. package/dist/utils/image-resize-core.d.ts.map +1 -0
  518. package/dist/utils/image-resize-core.js +124 -0
  519. package/dist/utils/image-resize-core.js.map +1 -0
  520. package/dist/utils/image-resize-worker.d.ts +2 -0
  521. package/dist/utils/image-resize-worker.d.ts.map +1 -0
  522. package/dist/utils/image-resize-worker.js +31 -0
  523. package/dist/utils/image-resize-worker.js.map +1 -0
  524. package/dist/utils/image-resize.d.ts +7 -27
  525. package/dist/utils/image-resize.d.ts.map +1 -1
  526. package/dist/utils/image-resize.js +75 -115
  527. package/dist/utils/image-resize.js.map +1 -1
  528. package/dist/utils/json.d.ts +3 -0
  529. package/dist/utils/json.d.ts.map +1 -0
  530. package/dist/utils/json.js +7 -0
  531. package/dist/utils/json.js.map +1 -0
  532. package/dist/utils/mime.d.ts +1 -0
  533. package/dist/utils/mime.d.ts.map +1 -1
  534. package/dist/utils/mime.js +100 -16
  535. package/dist/utils/mime.js.map +1 -1
  536. package/dist/utils/open-browser.d.ts +9 -0
  537. package/dist/utils/open-browser.d.ts.map +1 -0
  538. package/dist/utils/open-browser.js +22 -0
  539. package/dist/utils/open-browser.js.map +1 -0
  540. package/dist/utils/paths.d.ts +25 -1
  541. package/dist/utils/paths.d.ts.map +1 -1
  542. package/dist/utils/paths.js +75 -2
  543. package/dist/utils/paths.js.map +1 -1
  544. package/dist/utils/pi-user-agent.d.ts +2 -0
  545. package/dist/utils/pi-user-agent.d.ts.map +1 -0
  546. package/dist/utils/pi-user-agent.js +5 -0
  547. package/dist/utils/pi-user-agent.js.map +1 -0
  548. package/dist/utils/shell.d.ts +11 -6
  549. package/dist/utils/shell.d.ts.map +1 -1
  550. package/dist/utils/shell.js +42 -26
  551. package/dist/utils/shell.js.map +1 -1
  552. package/dist/utils/syntax-highlight.d.ts +12 -0
  553. package/dist/utils/syntax-highlight.d.ts.map +1 -0
  554. package/dist/utils/syntax-highlight.js +118 -0
  555. package/dist/utils/syntax-highlight.js.map +1 -0
  556. package/dist/utils/tools-manager.d.ts.map +1 -1
  557. package/dist/utils/tools-manager.js +86 -10
  558. package/dist/utils/tools-manager.js.map +1 -1
  559. package/dist/utils/version-check.d.ts +15 -0
  560. package/dist/utils/version-check.d.ts.map +1 -0
  561. package/dist/utils/version-check.js +59 -0
  562. package/dist/utils/version-check.js.map +1 -0
  563. package/dist/utils/windows-self-update.d.ts +3 -0
  564. package/dist/utils/windows-self-update.d.ts.map +1 -0
  565. package/dist/utils/windows-self-update.js +77 -0
  566. package/dist/utils/windows-self-update.js.map +1 -0
  567. package/docs/compaction.md +12 -12
  568. package/docs/containerization.md +111 -0
  569. package/docs/custom-provider.md +187 -47
  570. package/docs/development.md +5 -5
  571. package/docs/docs.json +156 -0
  572. package/docs/extensions.md +520 -79
  573. package/docs/index.md +82 -0
  574. package/docs/json.md +4 -4
  575. package/docs/keybindings.md +24 -2
  576. package/docs/models.md +119 -17
  577. package/docs/packages.md +19 -11
  578. package/docs/prompt-templates.md +30 -2
  579. package/docs/providers.md +85 -23
  580. package/docs/quickstart.md +165 -0
  581. package/docs/rpc.md +99 -10
  582. package/docs/sdk.md +118 -50
  583. package/docs/security.md +55 -0
  584. package/docs/{session.md → session-format.md} +29 -19
  585. package/docs/sessions.md +145 -0
  586. package/docs/settings.md +71 -11
  587. package/docs/skills.md +16 -17
  588. package/docs/terminal-setup.md +44 -2
  589. package/docs/termux.md +4 -4
  590. package/docs/themes.md +3 -3
  591. package/docs/tmux.md +4 -2
  592. package/docs/tui.md +44 -4
  593. package/docs/usage.md +305 -0
  594. package/examples/extensions/README.md +1 -0
  595. package/examples/extensions/border-status-editor.ts +145 -0
  596. package/examples/extensions/built-in-tool-renderer.ts +3 -0
  597. package/examples/extensions/custom-compaction.ts +2 -1
  598. package/examples/extensions/custom-header.ts +1 -1
  599. package/examples/extensions/custom-provider-anthropic/index.ts +2 -2
  600. package/examples/extensions/custom-provider-anthropic/package-lock.json +2 -2
  601. package/examples/extensions/custom-provider-anthropic/package.json +2 -2
  602. package/examples/extensions/custom-provider-gitlab-duo/index.ts +63 -8
  603. package/examples/extensions/custom-provider-gitlab-duo/package.json +1 -1
  604. package/examples/extensions/custom-provider-gitlab-duo/test.ts +2 -2
  605. package/examples/extensions/doom-overlay/doom-component.ts +2 -2
  606. package/examples/extensions/doom-overlay/index.ts +1 -1
  607. package/examples/extensions/dynamic-resources/dynamic.json +1 -1
  608. package/examples/extensions/dynamic-tools.ts +2 -2
  609. package/examples/extensions/entry-renderer.ts +41 -0
  610. package/examples/extensions/git-merge-and-resolve.ts +115 -0
  611. package/examples/extensions/github-issue-autocomplete.ts +185 -0
  612. package/examples/extensions/gondolin/index.ts +531 -0
  613. package/examples/extensions/gondolin/package-lock.json +185 -0
  614. package/examples/extensions/gondolin/package.json +19 -0
  615. package/examples/extensions/handoff.ts +52 -14
  616. package/examples/extensions/input-transform-streaming.ts +39 -0
  617. package/examples/extensions/interactive-shell.ts +1 -1
  618. package/examples/extensions/notify.ts +2 -9
  619. package/examples/extensions/overlay-qa-tests.ts +240 -138
  620. package/examples/extensions/overlay-test.ts +7 -4
  621. package/examples/extensions/plan-mode/index.ts +87 -37
  622. package/examples/extensions/plan-mode/utils.ts +1 -1
  623. package/examples/extensions/preset.ts +46 -7
  624. package/examples/extensions/project-trust.ts +64 -0
  625. package/examples/extensions/prompt-customizer.ts +97 -0
  626. package/examples/extensions/provider-payload.ts +8 -4
  627. package/examples/extensions/qna.ts +3 -3
  628. package/examples/extensions/question.ts +34 -20
  629. package/examples/extensions/questionnaire.ts +43 -30
  630. package/examples/extensions/reload-runtime.ts +1 -1
  631. package/examples/extensions/sandbox/index.ts +6 -6
  632. package/examples/extensions/sandbox/package-lock.json +5 -5
  633. package/examples/extensions/sandbox/package.json +2 -2
  634. package/examples/extensions/shutdown-command.ts +1 -1
  635. package/examples/extensions/snake.ts +1 -1
  636. package/examples/extensions/space-invaders.ts +1 -1
  637. package/examples/extensions/structured-output.ts +65 -0
  638. package/examples/extensions/subagent/agents.ts +2 -2
  639. package/examples/extensions/subagent/index.ts +58 -29
  640. package/examples/extensions/summarize.ts +3 -2
  641. package/examples/extensions/tic-tac-toe.ts +1008 -0
  642. package/examples/extensions/titlebar-spinner.ts +2 -2
  643. package/examples/extensions/todo.ts +2 -2
  644. package/examples/extensions/tool-override.ts +1 -1
  645. package/examples/extensions/tools.ts +5 -0
  646. package/examples/extensions/truncated-tool.ts +1 -1
  647. package/examples/extensions/with-deps/index.ts +1 -1
  648. package/examples/extensions/with-deps/package-lock.json +2 -2
  649. package/examples/extensions/with-deps/package.json +3 -3
  650. package/examples/extensions/working-indicator.ts +123 -0
  651. package/examples/extensions/working-message-test.ts +25 -0
  652. package/examples/sdk/01-minimal.ts +14 -10
  653. package/examples/sdk/02-custom-model.ts +13 -9
  654. package/examples/sdk/03-custom-prompt.ts +32 -17
  655. package/examples/sdk/04-skills.ts +5 -2
  656. package/examples/sdk/05-tools.ts +23 -31
  657. package/examples/sdk/06-extensions.ts +14 -8
  658. package/examples/sdk/07-context-files.ts +5 -3
  659. package/examples/sdk/08-prompt-templates.ts +5 -2
  660. package/examples/sdk/09-api-keys-and-oauth.ts +8 -4
  661. package/examples/sdk/10-settings.ts +8 -6
  662. package/examples/sdk/11-sessions.ts +4 -0
  663. package/examples/sdk/12-full-control.ts +15 -19
  664. package/package.json +22 -16
  665. package/prompts/agents/build.md +38 -0
  666. package/prompts/agents/plan.md +36 -0
  667. package/prompts/agents/verify.md +36 -4
  668. package/prompts/commands/brainstorm.md +162 -0
  669. package/prompts/commands/discuss-phase.md +1 -1
  670. package/prompts/commands/execute-phase.md +4 -1
  671. package/prompts/commands/fix.md +12 -0
  672. package/prompts/commands/init-project.md +1 -0
  673. package/prompts/commands/map-codebase.md +15 -1
  674. package/prompts/commands/new-project.md +1 -0
  675. package/prompts/commands/next-milestone.md +2 -0
  676. package/prompts/commands/orchestrate.md +4 -4
  677. package/prompts/commands/plan-phase.md +5 -0
  678. package/prompts/commands/quick.md +4 -0
  679. package/prompts/commands/review.md +4 -1
  680. package/prompts/commands/verify-work.md +10 -8
package/docs/index.md ADDED
@@ -0,0 +1,82 @@
1
+ # Pi Documentation
2
+
3
+ Pi is a minimal terminal coding harness. It is designed to stay small at the core while being extended through TypeScript extensions, skills, prompt templates, themes, and pi packages.
4
+
5
+ ## Quick start
6
+
7
+ Install Pi with npm:
8
+
9
+ ```bash
10
+ npm install -g --ignore-scripts @draht/coding-agent
11
+ ```
12
+
13
+ `--ignore-scripts` disables dependency lifecycle scripts during install. Pi does not require install scripts for normal npm installs.
14
+
15
+ On Linux or macOS, you can also use the installer:
16
+
17
+ ```bash
18
+ curl -fsSL https://pi.dev/install.sh | sh
19
+ ```
20
+
21
+ To uninstall pi itself, use npm for curl and npm installs:
22
+
23
+ ```bash
24
+ npm uninstall -g @draht/coding-agent
25
+ ```
26
+
27
+ For pnpm, Yarn, or Bun installs, use the matching global remove command: `pnpm remove -g @draht/coding-agent`, `yarn global remove @draht/coding-agent`, or `bun uninstall -g @draht/coding-agent`.
28
+
29
+ Then run it in a project directory:
30
+
31
+ ```bash
32
+ pi
33
+ ```
34
+
35
+ Authenticate with `/login` for subscription providers, or set an API key such as `ANTHROPIC_API_KEY` before starting pi.
36
+
37
+ For the full first-run flow, see [Quickstart](quickstart.md).
38
+
39
+ ## Start here
40
+
41
+ - [Quickstart](quickstart.md) - install, authenticate, and run a first session.
42
+ - [Using Pi](usage.md) - interactive mode, slash commands, context files, and CLI reference.
43
+ - [Providers](providers.md) - subscription and API-key setup for built-in providers.
44
+ - [Security](security.md) - project trust, sandbox boundaries, and vulnerability reporting.
45
+ - [Containerization](containerization.md) - sandbox pi with OpenShell, Gondolin, or Docker.
46
+ - [Settings](settings.md) - global and project settings.
47
+ - [Keybindings](keybindings.md) - default shortcuts and custom keybindings.
48
+ - [Sessions](sessions.md) - session management, branching, and tree navigation.
49
+ - [Compaction](compaction.md) - context compaction and branch summarization.
50
+
51
+ ## Customization
52
+
53
+ - [Extensions](extensions.md) - TypeScript modules for tools, commands, events, and custom UI.
54
+ - [Skills](skills.md) - Agent Skills for reusable on-demand capabilities.
55
+ - [Prompt templates](prompt-templates.md) - reusable prompts that expand from slash commands.
56
+ - [Themes](themes.md) - built-in and custom terminal themes.
57
+ - [Pi packages](packages.md) - bundle and share extensions, skills, prompts, and themes.
58
+ - [Custom models](models.md) - add model entries for supported provider APIs.
59
+ - [Custom providers](custom-provider.md) - implement custom APIs and OAuth flows.
60
+
61
+ ## Programmatic usage
62
+
63
+ - [SDK](sdk.md) - embed pi in Node.js applications.
64
+ - [RPC mode](rpc.md) - integrate over stdin/stdout JSONL.
65
+ - [JSON event stream mode](json.md) - print mode with structured events.
66
+ - [TUI components](tui.md) - build custom terminal UI for extensions.
67
+
68
+ ## Reference
69
+
70
+ - [Session format](session-format.md) - JSONL session file format, entry types, and SessionManager API.
71
+
72
+ ## Platform setup
73
+
74
+ - [Windows](windows.md)
75
+ - [Termux on Android](termux.md)
76
+ - [tmux](tmux.md)
77
+ - [Terminal setup](terminal-setup.md)
78
+ - [Shell aliases](shell-aliases.md)
79
+
80
+ ## Development
81
+
82
+ - [Development](development.md) - local setup, project structure, and debugging.
package/docs/json.md CHANGED
@@ -8,7 +8,7 @@ Outputs all session events as JSON lines to stdout. Useful for integrating pi in
8
8
 
9
9
  ## Event Types
10
10
 
11
- Events are defined in [`AgentSessionEvent`](https://github.com/draht-dev/draht/blob/main/packages/coding-agent/src/core/agent-session.ts#L102):
11
+ Events are defined in [`AgentSessionEvent`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/agent-session.ts#L102):
12
12
 
13
13
  ```typescript
14
14
  type AgentSessionEvent =
@@ -22,7 +22,7 @@ type AgentSessionEvent =
22
22
 
23
23
  `queue_update` emits the full pending steering and follow-up queues whenever they change. `compaction_start` and `compaction_end` cover both manual and automatic compaction.
24
24
 
25
- Base events from [`AgentEvent`](https://github.com/draht-dev/draht/blob/main/packages/agent/src/types.ts#L179):
25
+ Base events from [`AgentEvent`](https://github.com/earendil-works/pi-mono/blob/main/packages/agent/src/types.ts#L179):
26
26
 
27
27
  ```typescript
28
28
  type AgentEvent =
@@ -44,12 +44,12 @@ type AgentEvent =
44
44
 
45
45
  ## Message Types
46
46
 
47
- Base messages from [`packages/ai/src/types.ts`](https://github.com/draht-dev/draht/blob/main/packages/ai/src/types.ts#L134):
47
+ Base messages from [`packages/ai/src/types.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/types.ts#L134):
48
48
  - `UserMessage` (line 134)
49
49
  - `AssistantMessage` (line 140)
50
50
  - `ToolResultMessage` (line 152)
51
51
 
52
- Extended messages from [`packages/coding-agent/src/core/messages.ts`](https://github.com/draht-dev/draht/blob/main/packages/coding-agent/src/core/messages.ts#L29):
52
+ Extended messages from [`packages/coding-agent/src/core/messages.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/messages.ts#L29):
53
53
  - `BashExecutionMessage` (line 29)
54
54
  - `CustomMessage` (line 46)
55
55
  - `BranchSummaryMessage` (line 55)
@@ -85,8 +85,8 @@ Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `ctrl+1
85
85
  | `app.interrupt` | `escape` | Cancel / abort |
86
86
  | `app.clear` | `ctrl+c` | Clear editor |
87
87
  | `app.exit` | `ctrl+d` | Exit (when editor empty) |
88
- | `app.suspend` | `ctrl+z` | Suspend to background |
89
- | `app.editor.external` | `ctrl+g` | Open in external editor (`$VISUAL` or `$EDITOR`) |
88
+ | `app.suspend` | `ctrl+z` (none on Windows) | Suspend to background |
89
+ | `app.editor.external` | `ctrl+g` | Open in external editor (`externalEditor`, `$VISUAL`, `$EDITOR`, Notepad on Windows, or `nano` elsewhere) |
90
90
  | `app.clipboard.pasteImage` | `ctrl+v` (`alt+v` on Windows) | Paste image from clipboard |
91
91
 
92
92
  ### Sessions
@@ -130,6 +130,26 @@ Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `ctrl+1
130
130
  | `app.tree.unfoldOrDown` | `ctrl+right`, `alt+right` | Unfold current branch segment, or jump to the next segment start or branch end |
131
131
  | `app.tree.editLabel` | `shift+l` | Edit the label on the selected tree node |
132
132
  | `app.tree.toggleLabelTimestamp` | `shift+t` | Toggle label timestamps in the tree |
133
+ | `app.tree.filter.default` | `ctrl+d` | Set tree filter to default view |
134
+ | `app.tree.filter.noTools` | `ctrl+t` | Toggle tree filter that hides tool results |
135
+ | `app.tree.filter.userOnly` | `ctrl+u` | Toggle tree filter that shows only user messages |
136
+ | `app.tree.filter.labeledOnly` | `ctrl+l` | Toggle tree filter that shows only labeled entries |
137
+ | `app.tree.filter.all` | `ctrl+a` | Toggle tree filter that shows all entries |
138
+ | `app.tree.filter.cycleForward` | `ctrl+o` | Cycle tree filter forward |
139
+ | `app.tree.filter.cycleBackward` | `shift+ctrl+o` | Cycle tree filter backward |
140
+
141
+ ### Scoped Models Selector
142
+
143
+ Used inside the scoped models selector (opened via `/scoped-models`).
144
+
145
+ | Keybinding id | Default | Description |
146
+ |--------|---------|-------------|
147
+ | `app.models.save` | `ctrl+s` | Save current model selection to settings |
148
+ | `app.models.enableAll` | `ctrl+a` | Enable all models (or all matching the current search) |
149
+ | `app.models.clearAll` | `ctrl+x` | Clear all models (or all matching the current search) |
150
+ | `app.models.toggleProvider` | `ctrl+p` | Toggle all models for the current provider |
151
+ | `app.models.reorderUp` | `alt+up` | Move the selected model up in the cycle order |
152
+ | `app.models.reorderDown` | `alt+down` | Move the selected model down in the cycle order |
133
153
 
134
154
  ## Custom Configuration
135
155
 
@@ -145,6 +165,8 @@ Create `~/.pi/agent/keybindings.json`:
145
165
 
146
166
  Each action can have a single key or an array of keys. User config overrides defaults.
147
167
 
168
+ On native Windows, `app.suspend` has no default binding because Windows terminals do not support Unix job control. If you bind it manually, pi shows a status message instead of suspending. In WSL, the normal Linux `ctrl+z`/`fg` behavior still applies.
169
+
148
170
  ### Emacs Example
149
171
 
150
172
  ```json
package/docs/models.md CHANGED
@@ -11,6 +11,7 @@ Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via `~/.pi/ag
11
11
  - [Model Configuration](#model-configuration)
12
12
  - [Overriding Built-in Providers](#overriding-built-in-providers)
13
13
  - [Per-model Overrides](#per-model-overrides)
14
+ - [Anthropic Messages Compatibility](#anthropic-messages-compatibility)
14
15
  - [OpenAI Compatibility](#openai-compatibility)
15
16
 
16
17
  ## Minimal Example
@@ -100,7 +101,7 @@ Use `google-generative-ai` with a `baseUrl` to add models from Google AI Studio,
100
101
  "my-google": {
101
102
  "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
102
103
  "api": "google-generative-ai",
103
- "apiKey": "GEMINI_API_KEY",
104
+ "apiKey": "$GEMINI_API_KEY",
104
105
  "models": [
105
106
  {
106
107
  "id": "gemma-4-31b-it",
@@ -142,22 +143,31 @@ Set `api` at provider level (default for all models) or model level (override pe
142
143
 
143
144
  ### Value Resolution
144
145
 
145
- The `apiKey` and `headers` fields support three formats:
146
+ The `apiKey` and `headers` fields support command execution, environment interpolation, and literals:
146
147
 
147
- - **Shell command:** `"!command"` executes and uses stdout
148
+ - **Shell command:** `"!command"` at the start executes the whole value as a command and uses stdout
148
149
  ```json
149
150
  "apiKey": "!security find-generic-password -ws 'anthropic'"
150
151
  "apiKey": "!op read 'op://vault/item/credential'"
151
152
  ```
152
- - **Environment variable:** Uses the value of the named variable
153
+ - **Environment interpolation:** `"$ENV_VAR"` or `"${ENV_VAR}"` uses the value of the named variable. Interpolation works inside larger literals.
153
154
  ```json
154
- "apiKey": "MY_API_KEY"
155
+ "apiKey": "$MY_API_KEY"
156
+ "apiKey": "${KEY_PREFIX}_${KEY_SUFFIX}"
157
+ ```
158
+ `$FOO_BAR` is the variable `FOO_BAR`; use `${FOO}_BAR` when `BAR` is literal text. Missing environment variables make the value unresolved.
159
+ - **Escapes:** `"$$"` emits a literal `"$"`; `"$!"` emits a literal `"!"` without triggering command execution.
160
+ ```json
161
+ "apiKey": "$$literal-dollar-prefix"
162
+ "apiKey": "$!literal-bang-prefix"
155
163
  ```
156
164
  - **Literal value:** Used directly
157
165
  ```json
158
166
  "apiKey": "sk-..."
159
167
  ```
160
168
 
169
+ Legacy uppercase env-var-like values such as `MY_API_KEY` are migrated to `$MY_API_KEY` on startup.
170
+
161
171
  For `models.json`, shell commands are resolved at request time. pi intentionally does not apply built-in TTL, stale reuse, or recovery logic for arbitrary commands. Different commands need different caching and failure strategies, and pi cannot infer the right one.
162
172
 
163
173
  If your command is slow, expensive, rate-limited, or should keep using a previous value on transient failures, wrap it in your own script or command that implements the caching or TTL behavior you want.
@@ -171,10 +181,10 @@ If your command is slow, expensive, rate-limited, or should keep using a previou
171
181
  "providers": {
172
182
  "custom-proxy": {
173
183
  "baseUrl": "https://proxy.example.com/v1",
174
- "apiKey": "MY_API_KEY",
184
+ "apiKey": "$MY_API_KEY",
175
185
  "api": "anthropic-messages",
176
186
  "headers": {
177
- "x-portkey-api-key": "PORTKEY_API_KEY",
187
+ "x-portkey-api-key": "$PORTKEY_API_KEY",
178
188
  "x-secret": "!op read 'op://vault/item/secret'"
179
189
  },
180
190
  "models": [...]
@@ -188,18 +198,61 @@ If your command is slow, expensive, rate-limited, or should keep using a previou
188
198
  | Field | Required | Default | Description |
189
199
  |-------|----------|---------|-------------|
190
200
  | `id` | Yes | — | Model identifier (passed to the API) |
191
- | `name` | No | `id` | Human-readable model label. Used for matching (`--model` patterns) and shown in model details/status text. |
201
+ | `name` | No | `id` | Human-readable model label. Used for matching (`--model` patterns) and shown as secondary model detail text. |
192
202
  | `api` | No | provider's `api` | Override provider's API for this model |
193
203
  | `reasoning` | No | `false` | Supports extended thinking |
204
+ | `thinkingLevelMap` | No | omitted | Maps pi thinking levels to provider values and marks unsupported levels (see below) |
194
205
  | `input` | No | `["text"]` | Input types: `["text"]` or `["text", "image"]` |
195
206
  | `contextWindow` | No | `128000` | Context window size in tokens |
196
207
  | `maxTokens` | No | `16384` | Maximum output tokens |
197
208
  | `cost` | No | all zeros | `{"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0}` (per million tokens) |
198
- | `compat` | No | provider `compat` | OpenAI compatibility overrides. Merged with provider-level `compat` when both are set. |
209
+ | `compat` | No | provider `compat` | Provider compatibility overrides. Merged with provider-level `compat` when both are set. |
199
210
 
200
211
  Current behavior:
201
- - `/model` and `--list-models` list entries by model `id`.
202
- - The configured `name` is used for model matching and detail/status text.
212
+ - `/model`, `--list-models`, and the interactive footer display entries by model `id`.
213
+ - The configured `name` is used for model matching and secondary model detail text. It does not replace the footer/status-bar model id.
214
+
215
+ ### Thinking Level Map
216
+
217
+ Use `thinkingLevelMap` on a model to describe model-specific thinking controls. Keys are pi thinking levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`.
218
+
219
+ Values are tristate:
220
+
221
+ | Value | Meaning |
222
+ |-------|---------|
223
+ | omitted | Level is supported and uses the provider's default mapping |
224
+ | string | Level is supported and this value is sent to the provider |
225
+ | `null` | Level is unsupported and hidden/skipped/clamped away |
226
+
227
+ Example for a model that only supports off, high, and max reasoning:
228
+
229
+ ```json
230
+ {
231
+ "id": "deepseek-v4-pro",
232
+ "reasoning": true,
233
+ "thinkingLevelMap": {
234
+ "minimal": null,
235
+ "low": null,
236
+ "medium": null,
237
+ "high": "high",
238
+ "xhigh": "max"
239
+ }
240
+ }
241
+ ```
242
+
243
+ Example for a model where thinking cannot be disabled:
244
+
245
+ ```json
246
+ {
247
+ "id": "always-thinking-model",
248
+ "reasoning": true,
249
+ "thinkingLevelMap": {
250
+ "off": null
251
+ }
252
+ }
253
+ ```
254
+
255
+ Migration: older configs that used `compat.reasoningEffortMap` should move that mapping to model-level `thinkingLevelMap`. Use `null` for levels that should not appear in the UI.
203
256
 
204
257
  ## Overriding Built-in Providers
205
258
 
@@ -224,7 +277,7 @@ To merge custom models into a built-in provider, include the `models` array:
224
277
  "providers": {
225
278
  "anthropic": {
226
279
  "baseUrl": "https://my-proxy.example.com/v1",
227
- "apiKey": "ANTHROPIC_API_KEY",
280
+ "apiKey": "$ANTHROPIC_API_KEY",
228
281
  "api": "anthropic-messages",
229
282
  "models": [...]
230
283
  }
@@ -267,8 +320,53 @@ Behavior notes:
267
320
  - `modelOverrides` are applied to built-in provider models.
268
321
  - Unknown model IDs are ignored.
269
322
  - You can combine provider-level `baseUrl`/`headers` with `modelOverrides`.
323
+ - Overriding `name` changes model matching and secondary detail text only; the footer and primary model lists continue to show the model `id`.
270
324
  - If `models` is also defined for a provider, custom models are merged after built-in overrides. A custom model with the same `id` replaces the overridden built-in model entry.
271
325
 
326
+ ## Anthropic Messages Compatibility
327
+
328
+ For providers or proxies using `api: "anthropic-messages"`, use `compat` to control Anthropic-specific request compatibility.
329
+
330
+ By default pi sends per-tool `eager_input_streaming: true`. If a proxy or Anthropic-compatible backend rejects that field, set `supportsEagerToolInputStreaming` to `false`. Pi will omit `tools[].eager_input_streaming` and send the legacy `fine-grained-tool-streaming-2025-05-14` beta header for tool-enabled requests instead.
331
+
332
+ Some Anthropic models require adaptive thinking (`thinking.type: "adaptive"` plus `output_config.effort`) instead of the legacy budget-based thinking payload. Built-in models set this automatically. For custom providers or aliases that route to those models, set `forceAdaptiveThinking` to `true`.
333
+
334
+ Some Anthropic-compatible providers emit thinking blocks with empty signatures and still expect them on replay. Set `allowEmptySignature` to `true` only for those providers; real Anthropic rejects empty thinking signatures.
335
+
336
+ ```json
337
+ {
338
+ "providers": {
339
+ "anthropic-proxy": {
340
+ "baseUrl": "https://proxy.example.com",
341
+ "api": "anthropic-messages",
342
+ "apiKey": "$ANTHROPIC_PROXY_KEY",
343
+ "compat": {
344
+ "supportsEagerToolInputStreaming": false,
345
+ "supportsLongCacheRetention": true,
346
+ "forceAdaptiveThinking": true,
347
+ "allowEmptySignature": true
348
+ },
349
+ "models": [
350
+ {
351
+ "id": "claude-opus-4-7",
352
+ "reasoning": true,
353
+ "input": ["text", "image"]
354
+ }
355
+ ]
356
+ }
357
+ }
358
+ }
359
+ ```
360
+
361
+ | Field | Description |
362
+ |-------|-------------|
363
+ | `supportsEagerToolInputStreaming` | Whether the provider accepts per-tool `eager_input_streaming`. Default: `true`. Set to `false` to omit that field and use the legacy fine-grained tool streaming beta header on tool-enabled requests. |
364
+ | `supportsLongCacheRetention` | Whether the provider accepts Anthropic long cache retention (`cache_control.ttl: "1h"`) when cache retention is `long`. Default: `true`. |
365
+ | `sendSessionAffinityHeaders` | Whether to send `x-session-affinity` from the session id when caching is enabled. Default: auto-detected for known providers. |
366
+ | `supportsCacheControlOnTools` | Whether the provider accepts Anthropic-style `cache_control` markers on tool definitions. Default: `true`. |
367
+ | `forceAdaptiveThinking` | Whether to send adaptive thinking (`thinking.type: "adaptive"` plus `output_config.effort`) for this model. Built-in adaptive models set this automatically. Default: `false`. |
368
+ | `allowEmptySignature` | Whether to replay empty thinking signatures as `signature: ""` instead of converting thinking to text. Default: `false`. |
369
+
272
370
  ## OpenAI Compatibility
273
371
 
274
372
  For providers with partial OpenAI compatibility, use the `compat` field.
@@ -297,18 +395,22 @@ For providers with partial OpenAI compatibility, use the `compat` field.
297
395
  | `supportsStore` | Provider supports `store` field |
298
396
  | `supportsDeveloperRole` | Use `developer` vs `system` role |
299
397
  | `supportsReasoningEffort` | Support for `reasoning_effort` parameter |
300
- | `reasoningEffortMap` | Map pi thinking levels to provider-specific `reasoning_effort` values |
301
398
  | `supportsUsageInStreaming` | Supports `stream_options: { include_usage: true }` (default: `true`) |
302
399
  | `maxTokensField` | Use `max_completion_tokens` or `max_tokens` |
303
400
  | `requiresToolResultName` | Include `name` on tool result messages |
304
401
  | `requiresAssistantAfterToolResult` | Insert an assistant message before a user message after tool results |
305
402
  | `requiresThinkingAsText` | Convert thinking blocks to plain text |
306
- | `thinkingFormat` | Use `reasoning_effort`, `zai`, `qwen`, or `qwen-chat-template` thinking parameters |
403
+ | `requiresReasoningContentOnAssistantMessages` | Include empty `reasoning_content` on all replayed assistant messages when reasoning is enabled |
404
+ | `thinkingFormat` | Use `reasoning_effort`, `openrouter`, `deepseek`, `together`, `zai`, `qwen`, or `qwen-chat-template` thinking parameters |
405
+ | `cacheControlFormat` | Use Anthropic-style `cache_control` markers on the system prompt, last tool definition, and last user/assistant text content. Currently only `anthropic` is supported. |
307
406
  | `supportsStrictMode` | Include the `strict` field in tool definitions |
407
+ | `supportsLongCacheRetention` | Whether the provider accepts long cache retention when cache retention is `long`: `prompt_cache_retention: "24h"` for OpenAI prompt caching, or `cache_control.ttl: "1h"` when `cacheControlFormat` is `anthropic`. Default: `true`. |
308
408
  | `openRouterRouting` | OpenRouter provider routing preferences. This object is sent as-is in the `provider` field of the [OpenRouter API request](https://openrouter.ai/docs/guides/routing/provider-selection). |
309
409
  | `vercelGatewayRouting` | Vercel AI Gateway routing config for provider selection (`only`, `order`) |
310
410
 
311
- `qwen` uses top-level `enable_thinking`. Use `qwen-chat-template` for local Qwen-compatible servers that require `chat_template_kwargs.enable_thinking`.
411
+ `openrouter` uses `reasoning: { effort }`. `together` uses `reasoning: { enabled }` and also `reasoning_effort` when `supportsReasoningEffort` is enabled. `qwen` uses top-level `enable_thinking`. Use `qwen-chat-template` for local Qwen-compatible servers that require `chat_template_kwargs.enable_thinking`.
412
+
413
+ `cacheControlFormat: "anthropic"` is for OpenAI-compatible providers that expose Anthropic-style prompt caching through `cache_control` markers on text content and tool definitions.
312
414
 
313
415
  Example:
314
416
 
@@ -317,7 +419,7 @@ Example:
317
419
  "providers": {
318
420
  "openrouter": {
319
421
  "baseUrl": "https://openrouter.ai/api/v1",
320
- "apiKey": "OPENROUTER_API_KEY",
422
+ "apiKey": "$OPENROUTER_API_KEY",
321
423
  "api": "openai-completions",
322
424
  "models": [
323
425
  {
@@ -367,7 +469,7 @@ Vercel AI Gateway example:
367
469
  "providers": {
368
470
  "vercel-ai-gateway": {
369
471
  "baseUrl": "https://ai-gateway.vercel.sh/v1",
370
- "apiKey": "AI_GATEWAY_API_KEY",
472
+ "apiKey": "$AI_GATEWAY_API_KEY",
371
473
  "api": "openai-completions",
372
474
  "models": [
373
475
  {
package/docs/packages.md CHANGED
@@ -27,11 +27,18 @@ pi install /absolute/path/to/package
27
27
  pi install ./relative/path/to/package
28
28
 
29
29
  pi remove npm:@foo/bar
30
- pi list # show installed packages from settings
31
- pi update # update all non-pinned packages
30
+ pi list # show installed packages from settings
31
+ pi update # update pi, update packages, and reconcile pinned git refs
32
+ pi update --extensions # update packages and reconcile pinned git refs only
33
+ pi update --self # update pi only
34
+ pi update --self --force # reinstall pi even if current
35
+ pi update npm:@foo/bar # update one package
36
+ pi update --extension npm:@foo/bar
32
37
  ```
33
38
 
34
- By default, `install` and `remove` write to global settings (`~/.pi/agent/settings.json`). Use `-l` to write to project settings (`.pi/settings.json`) instead. Project settings can be shared with your team, and pi installs any missing packages automatically on startup.
39
+ These commands manage pi packages, not the pi CLI installation. To uninstall pi itself, see [Quickstart](quickstart.md#uninstall).
40
+
41
+ By default, `install` and `remove` write to user settings (`~/.pi/agent/settings.json`). Use `-l` to write to project settings (`.pi/settings.json`) instead. Project settings can be shared with your team, and pi installs any missing packages automatically on startup after the project is trusted.
35
42
 
36
43
  To try a package without installing it, use `--extension` or `-e`. This installs to a temporary directory for the current run only:
37
44
 
@@ -51,8 +58,8 @@ npm:@scope/pkg@1.2.3
51
58
  npm:pkg
52
59
  ```
53
60
 
54
- - Versioned specs are pinned and skipped by `pi update`.
55
- - Global installs use `npm install -g`.
61
+ - Versioned specs are pinned and skipped by package updates (`pi update`, `pi update --extensions`).
62
+ - User installs go under `~/.pi/agent/npm/`.
56
63
  - Project installs go under `.pi/npm/`.
57
64
  - Set `npmCommand` in `settings.json` to pin npm package lookup and install operations to a specific wrapper command such as `mise` or `asdf`.
58
65
 
@@ -78,9 +85,10 @@ ssh://git@github.com/user/repo@v1
78
85
  - HTTPS and SSH URLs are both supported.
79
86
  - SSH URLs use your configured SSH keys automatically (respects `~/.ssh/config`).
80
87
  - For non-interactive runs (for example CI), you can set `GIT_TERMINAL_PROMPT=0` to disable credential prompts and set `GIT_SSH_COMMAND` (for example `ssh -o BatchMode=yes -o ConnectTimeout=5`) to fail fast.
81
- - Refs pin the package and skip `pi update`.
88
+ - Refs are pinned tags or commits. `pi update` and `pi update --extensions` do not move them to newer refs, but they do reconcile an existing clone to the configured ref.
89
+ - Use `pi install git:host/user/repo@new-ref` to update settings and move an existing package to a new pinned ref.
82
90
  - Cloned to `~/.pi/agent/git/<host>/<path>` (global) or `.pi/git/<host>/<path>` (project).
83
- - Runs `npm install` after clone or pull if `package.json` exists.
91
+ - When reconciliation changes the checkout, pi resets and cleans the clone, then runs `npm install` if `package.json` exists.
84
92
 
85
93
  **SSH examples:**
86
94
  ```bash
@@ -124,7 +132,7 @@ Paths are relative to the package root. Arrays support glob patterns and `!exclu
124
132
 
125
133
  ### Gallery Metadata
126
134
 
127
- The [package gallery](https://shittycodingagent.ai/packages) displays packages tagged with `pi-package`. Add `video` or `image` fields to show a preview:
135
+ The [package gallery](https://pi.dev/packages) displays packages tagged with `pi-package`. Add `video` or `image` fields to show a preview:
128
136
 
129
137
  ```json
130
138
  {
@@ -158,7 +166,7 @@ If no `pi` manifest is present, pi auto-discovers resources from these directori
158
166
 
159
167
  Third party runtime dependencies belong in `dependencies` in `package.json`. Dependencies that do not register extensions, skills, prompt templates, or themes also belong in `dependencies`. When pi installs a package from npm or git, it runs `npm install`, so those dependencies are installed automatically.
160
168
 
161
- Pi bundles core packages for extensions and skills. If you import any of these, list them in `peerDependencies` with a `"*"` range and do not bundle them: `@draht/ai`, `@draht/agent-core-core`, `@draht/coding-agent`, `@draht/tui`, `@sinclair/typebox`.
169
+ Pi bundles core packages for extensions and skills. If you import any of these, list them in `peerDependencies` with a `"*"` range and do not bundle them: `@draht/ai`, `@draht/agent-core`, `@draht/coding-agent`, `@draht/tui`, `typebox`.
162
170
 
163
171
  Other pi packages must be bundled in your tarball. Add them to `dependencies` and `bundledDependencies`, then reference their resources through `node_modules/` paths. Pi loads packages with separate module roots, so separate installs do not collide or share modules.
164
172
 
@@ -207,11 +215,11 @@ Filter what a package loads using the object form in settings:
207
215
 
208
216
  ## Enable and Disable Resources
209
217
 
210
- Use `pi config` to enable or disable extensions, skills, prompt templates, and themes from installed packages and local directories. Works for both global (`~/.pi/agent`) and project (`.pi/`) scopes.
218
+ Use `pi config` to enable or disable extensions, skills, prompt templates, and themes from installed packages and local directories. `pi config` starts in global settings (`~/.pi/agent/settings.json`); press Tab to switch between global and project-local modes. Use `pi config -l` to start in project overrides (`.pi/settings.json`) with inherited global resources dimmed.
211
219
 
212
220
  ## Scope and Deduplication
213
221
 
214
- Packages can appear in both global and project settings. If the same package appears in both, the project entry wins. Identity is determined by:
222
+ Packages can appear in both global and project settings. If the same package appears in both, the project entry wins unless the project entry has `autoload: false`, in which case it is applied as a delta over the global entry. Identity is determined by:
215
223
 
216
224
  - npm: package name
217
225
  - git: repository URL without ref
@@ -9,7 +9,7 @@ Prompt templates are Markdown snippets that expand into full prompts. Type `/nam
9
9
  Pi loads prompt templates from:
10
10
 
11
11
  - Global: `~/.pi/agent/prompts/*.md`
12
- - Project: `.pi/prompts/*.md`
12
+ - Project: `.pi/prompts/*.md` (only after the project is trusted)
13
13
  - Packages: `prompts/` directories or `pi.prompts` entries in `package.json`
14
14
  - Settings: `prompts` array with files or directories
15
15
  - CLI: `--prompt-template <path>` (repeatable)
@@ -30,6 +30,27 @@ Review the staged changes (`git diff --cached`). Focus on:
30
30
 
31
31
  - The filename becomes the command name. `review.md` becomes `/review`.
32
32
  - `description` is optional. If missing, the first non-empty line is used.
33
+ - `argument-hint` is optional. When set, the hint is displayed before the description in the autocomplete dropdown.
34
+
35
+ ### Argument Hints
36
+
37
+ Use `argument-hint` in frontmatter to show expected arguments in autocomplete. Use `<angle brackets>` for required arguments and `[square brackets]` for optional ones:
38
+
39
+ ```markdown
40
+ ---
41
+ description: Review PRs from URLs with structured issue and code analysis
42
+ argument-hint: "<PR-URL>"
43
+ ---
44
+ ```
45
+
46
+ This renders in the autocomplete dropdown as:
47
+
48
+ ```
49
+ → pr <PR-URL> — Review PRs from URLs with structured issue and code analysis
50
+ is <issue> — Analyze GitHub issues (bugs or feature requests)
51
+ wr [instructions] — Finish the current task end-to-end
52
+ cl — Audit changelog entries before release
53
+ ```
33
54
 
34
55
  ## Usage
35
56
 
@@ -43,10 +64,11 @@ Type `/` followed by the template name in the editor. Autocomplete shows availab
43
64
 
44
65
  ## Arguments
45
66
 
46
- Templates support positional arguments and simple slicing:
67
+ Templates support positional arguments, defaults, and simple slicing:
47
68
 
48
69
  - `$1`, `$2`, ... positional args
49
70
  - `$@` or `$ARGUMENTS` for all args joined
71
+ - `${1:-default}` uses arg 1 when present/non-empty, otherwise `default`
50
72
  - `${@:N}` for args from the Nth position (1-indexed)
51
73
  - `${@:N:L}` for `L` args starting at N
52
74
 
@@ -59,6 +81,12 @@ description: Create a component
59
81
  Create a React component named $1 with features: $@
60
82
  ```
61
83
 
84
+ Default values are useful for optional arguments:
85
+
86
+ ```markdown
87
+ Summarize the current state in ${1:-7} bullet points.
88
+ ```
89
+
62
90
  Usage: `/component Button "onClick handler" "disabled support"`
63
91
 
64
92
  ## Loading Rules