@bevel-software/platform-core-backend 0.33.0 → 0.35.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 (602) hide show
  1. package/agent-guide/access-control.md +146 -289
  2. package/agent-guide/conventions.md +23 -25
  3. package/agent-guide/directory-structure.md +72 -120
  4. package/agent-guide/drafts-and-change-requests.md +92 -0
  5. package/agent-guide/for-git-users.md +47 -0
  6. package/agent-guide/glossary.md +36 -0
  7. package/agent-guide/how-agents-find-things.md +49 -0
  8. package/agent-guide/html-views.md +239 -8
  9. package/agent-guide/new-knowledge-base.md +9 -8
  10. package/agent-guide/skills.md +67 -42
  11. package/agent-guide/start-here.md +65 -0
  12. package/agent-guide/tool-manuals.md +133 -155
  13. package/agent-guide/tools.md +67 -0
  14. package/agent-guide/where-a-new-file-goes.md +45 -28
  15. package/dist/core/catalog-revision.d.ts +12 -1
  16. package/dist/core/catalog-revision.d.ts.map +1 -1
  17. package/dist/core/catalog-revision.js +23 -3
  18. package/dist/core/catalog-revision.js.map +1 -1
  19. package/dist/core/core-ports.d.ts +41 -0
  20. package/dist/core/core-ports.d.ts.map +1 -1
  21. package/dist/core/core-ports.js.map +1 -1
  22. package/dist/core/create-core-server.d.ts.map +1 -1
  23. package/dist/core/create-core-server.js +15 -8
  24. package/dist/core/create-core-server.js.map +1 -1
  25. package/dist/core/create-core-services.d.ts +22 -5
  26. package/dist/core/create-core-services.d.ts.map +1 -1
  27. package/dist/core/create-core-services.js +44 -16
  28. package/dist/core/create-core-services.js.map +1 -1
  29. package/dist/core/lifecycle.d.ts +16 -0
  30. package/dist/core/lifecycle.d.ts.map +1 -1
  31. package/dist/core/lifecycle.js +12 -2
  32. package/dist/core/lifecycle.js.map +1 -1
  33. package/dist/index.d.ts +1 -1
  34. package/dist/index.d.ts.map +1 -1
  35. package/dist/index.js.map +1 -1
  36. package/dist/modules/access/access-control.interface.d.ts +39 -9
  37. package/dist/modules/access/access-control.interface.d.ts.map +1 -1
  38. package/dist/modules/access/access-control.service.d.ts +15 -3
  39. package/dist/modules/access/access-control.service.d.ts.map +1 -1
  40. package/dist/modules/access/access-control.service.js +239 -75
  41. package/dist/modules/access/access-control.service.js.map +1 -1
  42. package/dist/modules/access/access-mutation.service.d.ts +22 -24
  43. package/dist/modules/access/access-mutation.service.d.ts.map +1 -1
  44. package/dist/modules/access/access-mutation.service.js +48 -51
  45. package/dist/modules/access/access-mutation.service.js.map +1 -1
  46. package/dist/modules/access/access-view.d.ts.map +1 -1
  47. package/dist/modules/access/access-view.js +12 -11
  48. package/dist/modules/access/access-view.js.map +1 -1
  49. package/dist/modules/access/access.routes.d.ts +3 -0
  50. package/dist/modules/access/access.routes.d.ts.map +1 -1
  51. package/dist/modules/access/access.routes.js +58 -33
  52. package/dist/modules/access/access.routes.js.map +1 -1
  53. package/dist/modules/access/groups-admin.routes.d.ts.map +1 -1
  54. package/dist/modules/access/groups-admin.routes.js +4 -2
  55. package/dist/modules/access/groups-admin.routes.js.map +1 -1
  56. package/dist/modules/access/groups-admin.service.d.ts +44 -13
  57. package/dist/modules/access/groups-admin.service.d.ts.map +1 -1
  58. package/dist/modules/access/groups-admin.service.js +80 -38
  59. package/dist/modules/access/groups-admin.service.js.map +1 -1
  60. package/dist/modules/access/groups-edit.d.ts +1 -1
  61. package/dist/modules/access/groups-edit.d.ts.map +1 -1
  62. package/dist/modules/access/groups-edit.js +1 -1
  63. package/dist/modules/access/groups-edit.js.map +1 -1
  64. package/dist/modules/access/index.d.ts +1 -1
  65. package/dist/modules/access/index.d.ts.map +1 -1
  66. package/dist/modules/access/reference-scan.d.ts +116 -24
  67. package/dist/modules/access/reference-scan.d.ts.map +1 -1
  68. package/dist/modules/access/reference-scan.js +305 -44
  69. package/dist/modules/access/reference-scan.js.map +1 -1
  70. package/dist/modules/access/roles-admin.service.d.ts +17 -8
  71. package/dist/modules/access/roles-admin.service.d.ts.map +1 -1
  72. package/dist/modules/access/roles-admin.service.js +32 -23
  73. package/dist/modules/access/roles-admin.service.js.map +1 -1
  74. package/dist/modules/access-model/access-grammar.d.ts +35 -10
  75. package/dist/modules/access-model/access-grammar.d.ts.map +1 -1
  76. package/dist/modules/access-model/access-grammar.js +60 -20
  77. package/dist/modules/access-model/access-grammar.js.map +1 -1
  78. package/dist/modules/access-model/access-splice.d.ts +22 -18
  79. package/dist/modules/access-model/access-splice.d.ts.map +1 -1
  80. package/dist/modules/access-model/access-splice.js +20 -14
  81. package/dist/modules/access-model/access-splice.js.map +1 -1
  82. package/dist/modules/access-model/group-files.d.ts +1 -0
  83. package/dist/modules/access-model/group-files.d.ts.map +1 -1
  84. package/dist/modules/access-model/group-files.js +5 -1
  85. package/dist/modules/access-model/group-files.js.map +1 -1
  86. package/dist/modules/agent-guide/agent-guide.d.ts +47 -7
  87. package/dist/modules/agent-guide/agent-guide.d.ts.map +1 -1
  88. package/dist/modules/agent-guide/agent-guide.js +103 -13
  89. package/dist/modules/agent-guide/agent-guide.js.map +1 -1
  90. package/dist/modules/agent-guide/agent-guide.tools.d.ts +6 -2
  91. package/dist/modules/agent-guide/agent-guide.tools.d.ts.map +1 -1
  92. package/dist/modules/agent-guide/agent-guide.tools.js +46 -22
  93. package/dist/modules/agent-guide/agent-guide.tools.js.map +1 -1
  94. package/dist/modules/agent-guide/guide-budget.d.ts +48 -0
  95. package/dist/modules/agent-guide/guide-budget.d.ts.map +1 -0
  96. package/dist/modules/agent-guide/guide-budget.js +67 -0
  97. package/dist/modules/agent-guide/guide-budget.js.map +1 -0
  98. package/dist/modules/agent-guide/index.d.ts +2 -1
  99. package/dist/modules/agent-guide/index.d.ts.map +1 -1
  100. package/dist/modules/agent-guide/index.js +2 -1
  101. package/dist/modules/agent-guide/index.js.map +1 -1
  102. package/dist/modules/agent-instructions/compose.d.ts +3 -1
  103. package/dist/modules/agent-instructions/compose.d.ts.map +1 -1
  104. package/dist/modules/agent-instructions/compose.js +7 -1
  105. package/dist/modules/agent-instructions/compose.js.map +1 -1
  106. package/dist/modules/agent-instructions/shared-file-rules.d.ts +5 -1
  107. package/dist/modules/agent-instructions/shared-file-rules.d.ts.map +1 -1
  108. package/dist/modules/agent-instructions/shared-file-rules.js +26 -9
  109. package/dist/modules/agent-instructions/shared-file-rules.js.map +1 -1
  110. package/dist/modules/agent-scope/agent-scope.contract.d.ts +67 -0
  111. package/dist/modules/agent-scope/agent-scope.contract.d.ts.map +1 -0
  112. package/dist/modules/agent-scope/agent-scope.contract.js +27 -0
  113. package/dist/modules/agent-scope/agent-scope.contract.js.map +1 -0
  114. package/dist/modules/agent-scope/connection-scope.d.ts +111 -0
  115. package/dist/modules/agent-scope/connection-scope.d.ts.map +1 -0
  116. package/dist/modules/agent-scope/connection-scope.js +165 -0
  117. package/dist/modules/agent-scope/connection-scope.js.map +1 -0
  118. package/dist/modules/agent-scope/index.d.ts +3 -0
  119. package/dist/modules/agent-scope/index.d.ts.map +1 -0
  120. package/dist/modules/agent-scope/index.js +3 -0
  121. package/dist/modules/agent-scope/index.js.map +1 -0
  122. package/dist/modules/audit/agent-audit.service.d.ts.map +1 -1
  123. package/dist/modules/audit/agent-audit.service.js +2 -0
  124. package/dist/modules/audit/agent-audit.service.js.map +1 -1
  125. package/dist/modules/audit/audit.contract.d.ts +6 -0
  126. package/dist/modules/audit/audit.contract.d.ts.map +1 -1
  127. package/dist/modules/audit/audit.contract.js.map +1 -1
  128. package/dist/modules/auth/account-admission.d.ts +12 -0
  129. package/dist/modules/auth/account-admission.d.ts.map +1 -1
  130. package/dist/modules/auth/account-admission.js +15 -0
  131. package/dist/modules/auth/account-admission.js.map +1 -1
  132. package/dist/modules/auth/auth.middleware.d.ts +27 -1
  133. package/dist/modules/auth/auth.middleware.d.ts.map +1 -1
  134. package/dist/modules/auth/auth.middleware.js +42 -4
  135. package/dist/modules/auth/auth.middleware.js.map +1 -1
  136. package/dist/modules/auth/auth.routes.d.ts +13 -9
  137. package/dist/modules/auth/auth.routes.d.ts.map +1 -1
  138. package/dist/modules/auth/auth.routes.js +35 -29
  139. package/dist/modules/auth/auth.routes.js.map +1 -1
  140. package/dist/modules/auth/auth.service.d.ts +55 -6
  141. package/dist/modules/auth/auth.service.d.ts.map +1 -1
  142. package/dist/modules/auth/auth.service.js +128 -34
  143. package/dist/modules/auth/auth.service.js.map +1 -1
  144. package/dist/modules/auth/index.d.ts +1 -1
  145. package/dist/modules/auth/index.d.ts.map +1 -1
  146. package/dist/modules/auth/index.js +1 -1
  147. package/dist/modules/auth/index.js.map +1 -1
  148. package/dist/modules/auth/oidc-auth-provider.d.ts.map +1 -1
  149. package/dist/modules/auth/oidc-auth-provider.js +2 -9
  150. package/dist/modules/auth/oidc-auth-provider.js.map +1 -1
  151. package/dist/modules/code-mode/code-mode.tool.js +2 -2
  152. package/dist/modules/code-mode/code-mode.tool.js.map +1 -1
  153. package/dist/modules/connection-probe/connection-probe.service.d.ts +0 -12
  154. package/dist/modules/connection-probe/connection-probe.service.d.ts.map +1 -1
  155. package/dist/modules/connection-probe/connection-probe.service.js +1 -38
  156. package/dist/modules/connection-probe/connection-probe.service.js.map +1 -1
  157. package/dist/modules/database/core-schema.d.ts +68 -0
  158. package/dist/modules/database/core-schema.d.ts.map +1 -1
  159. package/dist/modules/database/core-schema.js +33 -0
  160. package/dist/modules/database/core-schema.js.map +1 -1
  161. package/dist/modules/declared-variables/declared-variables.routes.d.ts +8 -1
  162. package/dist/modules/declared-variables/declared-variables.routes.d.ts.map +1 -1
  163. package/dist/modules/declared-variables/declared-variables.routes.js +13 -2
  164. package/dist/modules/declared-variables/declared-variables.routes.js.map +1 -1
  165. package/dist/modules/embed/embed.tools.d.ts.map +1 -1
  166. package/dist/modules/embed/embed.tools.js +5 -0
  167. package/dist/modules/embed/embed.tools.js.map +1 -1
  168. package/dist/modules/kb-fs/index.d.ts +2 -0
  169. package/dist/modules/kb-fs/index.d.ts.map +1 -1
  170. package/dist/modules/kb-fs/index.js +1 -0
  171. package/dist/modules/kb-fs/index.js.map +1 -1
  172. package/dist/modules/kb-fs/locking-filesystem.d.ts.map +1 -1
  173. package/dist/modules/kb-fs/locking-filesystem.js +7 -1
  174. package/dist/modules/kb-fs/locking-filesystem.js.map +1 -1
  175. package/dist/modules/kb-fs/repo-path.d.ts +26 -6
  176. package/dist/modules/kb-fs/repo-path.d.ts.map +1 -1
  177. package/dist/modules/kb-fs/repo-path.js +22 -7
  178. package/dist/modules/kb-fs/repo-path.js.map +1 -1
  179. package/dist/modules/kb-fs/tmp-ref.d.ts +36 -0
  180. package/dist/modules/kb-fs/tmp-ref.d.ts.map +1 -0
  181. package/dist/modules/kb-fs/tmp-ref.js +76 -0
  182. package/dist/modules/kb-fs/tmp-ref.js.map +1 -0
  183. package/dist/modules/mcp/mcp-auth.middleware.d.ts +7 -0
  184. package/dist/modules/mcp/mcp-auth.middleware.d.ts.map +1 -1
  185. package/dist/modules/mcp/mcp-auth.middleware.js +14 -1
  186. package/dist/modules/mcp/mcp-auth.middleware.js.map +1 -1
  187. package/dist/modules/mcp/mcp.routes.d.ts +7 -1
  188. package/dist/modules/mcp/mcp.routes.d.ts.map +1 -1
  189. package/dist/modules/mcp/mcp.routes.js +39 -4
  190. package/dist/modules/mcp/mcp.routes.js.map +1 -1
  191. package/dist/modules/mcp/mcp.service.d.ts +11 -0
  192. package/dist/modules/mcp/mcp.service.d.ts.map +1 -1
  193. package/dist/modules/mcp/mcp.service.js +74 -48
  194. package/dist/modules/mcp/mcp.service.js.map +1 -1
  195. package/dist/modules/mcp/oauth/bevel-oauth-provider.d.ts +24 -1
  196. package/dist/modules/mcp/oauth/bevel-oauth-provider.d.ts.map +1 -1
  197. package/dist/modules/mcp/oauth/bevel-oauth-provider.js +45 -10
  198. package/dist/modules/mcp/oauth/bevel-oauth-provider.js.map +1 -1
  199. package/dist/modules/mcp/oauth/oauth-consent.routes.d.ts +9 -0
  200. package/dist/modules/mcp/oauth/oauth-consent.routes.d.ts.map +1 -1
  201. package/dist/modules/mcp/oauth/oauth-consent.routes.js +34 -1
  202. package/dist/modules/mcp/oauth/oauth-consent.routes.js.map +1 -1
  203. package/dist/modules/plugins/index.d.ts +1 -1
  204. package/dist/modules/plugins/index.d.ts.map +1 -1
  205. package/dist/modules/plugins/index.js.map +1 -1
  206. package/dist/modules/plugins/plugin-links.d.ts +18 -2
  207. package/dist/modules/plugins/plugin-links.d.ts.map +1 -1
  208. package/dist/modules/plugins/plugin-links.js.map +1 -1
  209. package/dist/modules/plugins/plugins.routes.d.ts +5 -1
  210. package/dist/modules/plugins/plugins.routes.d.ts.map +1 -1
  211. package/dist/modules/plugins/plugins.routes.js +32 -5
  212. package/dist/modules/plugins/plugins.routes.js.map +1 -1
  213. package/dist/modules/secrets-vault/db-secrets-vault.service.d.ts +11 -1
  214. package/dist/modules/secrets-vault/db-secrets-vault.service.d.ts.map +1 -1
  215. package/dist/modules/secrets-vault/db-secrets-vault.service.js +159 -24
  216. package/dist/modules/secrets-vault/db-secrets-vault.service.js.map +1 -1
  217. package/dist/modules/secrets-vault/index.d.ts +1 -1
  218. package/dist/modules/secrets-vault/index.d.ts.map +1 -1
  219. package/dist/modules/secrets-vault/index.js +1 -1
  220. package/dist/modules/secrets-vault/index.js.map +1 -1
  221. package/dist/modules/secrets-vault/secrets-vault.contract.d.ts +53 -11
  222. package/dist/modules/secrets-vault/secrets-vault.contract.d.ts.map +1 -1
  223. package/dist/modules/secrets-vault/secrets-vault.contract.js +27 -0
  224. package/dist/modules/secrets-vault/secrets-vault.contract.js.map +1 -1
  225. package/dist/modules/secrets-vault/secrets-vault.routes.d.ts +9 -0
  226. package/dist/modules/secrets-vault/secrets-vault.routes.d.ts.map +1 -1
  227. package/dist/modules/secrets-vault/secrets-vault.routes.js +100 -42
  228. package/dist/modules/secrets-vault/secrets-vault.routes.js.map +1 -1
  229. package/dist/modules/settings/oidc-check.d.ts.map +1 -1
  230. package/dist/modules/settings/oidc-check.js +5 -17
  231. package/dist/modules/settings/oidc-check.js.map +1 -1
  232. package/dist/modules/skills/index.d.ts +3 -3
  233. package/dist/modules/skills/index.d.ts.map +1 -1
  234. package/dist/modules/skills/index.js +0 -2
  235. package/dist/modules/skills/index.js.map +1 -1
  236. package/dist/modules/skills/skills.contract.d.ts +16 -0
  237. package/dist/modules/skills/skills.contract.d.ts.map +1 -1
  238. package/dist/modules/skills/skills.service.d.ts.map +1 -1
  239. package/dist/modules/skills/skills.service.js +6 -1
  240. package/dist/modules/skills/skills.service.js.map +1 -1
  241. package/dist/modules/skills/skills.tools.d.ts.map +1 -1
  242. package/dist/modules/skills/skills.tools.js +25 -13
  243. package/dist/modules/skills/skills.tools.js.map +1 -1
  244. package/dist/modules/tool-auth/external-api-key.interface.d.ts +11 -0
  245. package/dist/modules/tool-auth/external-api-key.interface.d.ts.map +1 -1
  246. package/dist/modules/tool-auth/external-api-key.interface.js.map +1 -1
  247. package/dist/modules/tool-auth/external-api-key.service.d.ts +1 -0
  248. package/dist/modules/tool-auth/external-api-key.service.d.ts.map +1 -1
  249. package/dist/modules/tool-auth/external-api-key.service.js +4 -1
  250. package/dist/modules/tool-auth/external-api-key.service.js.map +1 -1
  251. package/dist/modules/tool-auth/index.d.ts +1 -1
  252. package/dist/modules/tool-auth/index.d.ts.map +1 -1
  253. package/dist/modules/tool-auth/internal-token.service.d.ts +9 -0
  254. package/dist/modules/tool-auth/internal-token.service.d.ts.map +1 -1
  255. package/dist/modules/tool-auth/internal-token.service.js +1 -0
  256. package/dist/modules/tool-auth/internal-token.service.js.map +1 -1
  257. package/dist/modules/tool-auth/tool-auth.middleware.d.ts +27 -3
  258. package/dist/modules/tool-auth/tool-auth.middleware.d.ts.map +1 -1
  259. package/dist/modules/tool-auth/tool-auth.middleware.js +32 -6
  260. package/dist/modules/tool-auth/tool-auth.middleware.js.map +1 -1
  261. package/dist/modules/tool-helpers/tool-context.d.ts +7 -0
  262. package/dist/modules/tool-helpers/tool-context.d.ts.map +1 -1
  263. package/dist/modules/tool-helpers/tool-context.js +3 -0
  264. package/dist/modules/tool-helpers/tool-context.js.map +1 -1
  265. package/dist/modules/tool-helpers/tool-def.js +1 -1
  266. package/dist/modules/tool-helpers/tool-def.js.map +1 -1
  267. package/dist/modules/tool-helpers/tool-handler.d.ts +15 -0
  268. package/dist/modules/tool-helpers/tool-handler.d.ts.map +1 -1
  269. package/dist/modules/tool-helpers/tool-handler.js +19 -0
  270. package/dist/modules/tool-helpers/tool-handler.js.map +1 -1
  271. package/dist/modules/tool-helpers/tool.contract.d.ts +10 -0
  272. package/dist/modules/tool-helpers/tool.contract.d.ts.map +1 -1
  273. package/dist/modules/tool-helpers/tool.contract.js.map +1 -1
  274. package/dist/modules/tool-helpers/validate-token.d.ts +3 -1
  275. package/dist/modules/tool-helpers/validate-token.d.ts.map +1 -1
  276. package/dist/modules/tool-helpers/validate-token.js +1 -1
  277. package/dist/modules/tool-helpers/validate-token.js.map +1 -1
  278. package/dist/modules/tool-manuals/index.d.ts +3 -3
  279. package/dist/modules/tool-manuals/index.d.ts.map +1 -1
  280. package/dist/modules/tool-manuals/index.js +0 -2
  281. package/dist/modules/tool-manuals/index.js.map +1 -1
  282. package/dist/modules/tool-manuals/mcp-json-discovery.d.ts +7 -1
  283. package/dist/modules/tool-manuals/mcp-json-discovery.d.ts.map +1 -1
  284. package/dist/modules/tool-manuals/mcp-json-discovery.js +69 -38
  285. package/dist/modules/tool-manuals/mcp-json-discovery.js.map +1 -1
  286. package/dist/modules/tool-manuals/tool-manuals.contract.d.ts +46 -6
  287. package/dist/modules/tool-manuals/tool-manuals.contract.d.ts.map +1 -1
  288. package/dist/modules/tool-manuals/tool-manuals.routes.d.ts +7 -1
  289. package/dist/modules/tool-manuals/tool-manuals.routes.d.ts.map +1 -1
  290. package/dist/modules/tool-manuals/tool-manuals.routes.js +41 -4
  291. package/dist/modules/tool-manuals/tool-manuals.routes.js.map +1 -1
  292. package/dist/modules/tool-manuals/tool-manuals.service.d.ts +24 -13
  293. package/dist/modules/tool-manuals/tool-manuals.service.d.ts.map +1 -1
  294. package/dist/modules/tool-manuals/tool-manuals.service.js +138 -59
  295. package/dist/modules/tool-manuals/tool-manuals.service.js.map +1 -1
  296. package/dist/modules/tool-manuals/tool-manuals.tools.d.ts +8 -2
  297. package/dist/modules/tool-manuals/tool-manuals.tools.d.ts.map +1 -1
  298. package/dist/modules/tool-manuals/tool-manuals.tools.js +56 -20
  299. package/dist/modules/tool-manuals/tool-manuals.tools.js.map +1 -1
  300. package/dist/modules/tool-registry/manual.routes.d.ts +8 -1
  301. package/dist/modules/tool-registry/manual.routes.d.ts.map +1 -1
  302. package/dist/modules/tool-registry/manual.routes.js +27 -7
  303. package/dist/modules/tool-registry/manual.routes.js.map +1 -1
  304. package/dist/modules/tool-registry/tool.contract.d.ts +7 -0
  305. package/dist/modules/tool-registry/tool.contract.d.ts.map +1 -1
  306. package/dist/modules/tool-registry/tool.contract.js.map +1 -1
  307. package/dist/modules/workflow/agent-tools/workflow.tools.d.ts.map +1 -1
  308. package/dist/modules/workflow/agent-tools/workflow.tools.js +36 -27
  309. package/dist/modules/workflow/agent-tools/workflow.tools.js.map +1 -1
  310. package/dist/modules/workflow/git/git.service.d.ts +2 -2
  311. package/dist/modules/workflow/git/git.service.d.ts.map +1 -1
  312. package/dist/modules/workflow/git/git.service.js +20 -35
  313. package/dist/modules/workflow/git/git.service.js.map +1 -1
  314. package/dist/modules/workflow/workflow.service.d.ts +2 -1
  315. package/dist/modules/workflow/workflow.service.d.ts.map +1 -1
  316. package/dist/modules/workflow/workflow.service.js +3 -0
  317. package/dist/modules/workflow/workflow.service.js.map +1 -1
  318. package/dist/modules/workspace/agent-access.gate.d.ts +1 -1
  319. package/dist/modules/workspace/agent-access.gate.d.ts.map +1 -1
  320. package/dist/modules/workspace/agent-access.gate.js +1 -1
  321. package/dist/modules/workspace/agent-access.gate.js.map +1 -1
  322. package/dist/modules/workspace/file-readers/doc-extract.service.d.ts +28 -4
  323. package/dist/modules/workspace/file-readers/doc-extract.service.d.ts.map +1 -1
  324. package/dist/modules/workspace/file-readers/doc-extract.service.js +61 -40
  325. package/dist/modules/workspace/file-readers/doc-extract.service.js.map +1 -1
  326. package/dist/modules/workspace/index.d.ts +8 -0
  327. package/dist/modules/workspace/index.d.ts.map +1 -1
  328. package/dist/modules/workspace/index.js +8 -0
  329. package/dist/modules/workspace/index.js.map +1 -1
  330. package/dist/modules/workspace/nul-scan.d.ts +19 -0
  331. package/dist/modules/workspace/nul-scan.d.ts.map +1 -0
  332. package/dist/modules/workspace/nul-scan.js +55 -0
  333. package/dist/modules/workspace/nul-scan.js.map +1 -0
  334. package/dist/modules/workspace/pattern-matcher.contract.d.ts +110 -27
  335. package/dist/modules/workspace/pattern-matcher.contract.d.ts.map +1 -1
  336. package/dist/modules/workspace/pattern-matcher.contract.js +30 -13
  337. package/dist/modules/workspace/pattern-matcher.contract.js.map +1 -1
  338. package/dist/modules/workspace/ripgrep-search.d.ts +54 -0
  339. package/dist/modules/workspace/ripgrep-search.d.ts.map +1 -0
  340. package/dist/modules/workspace/ripgrep-search.js +657 -0
  341. package/dist/modules/workspace/ripgrep-search.js.map +1 -0
  342. package/dist/modules/workspace/ripgrep-version.d.ts +15 -0
  343. package/dist/modules/workspace/ripgrep-version.d.ts.map +1 -0
  344. package/dist/modules/workspace/ripgrep-version.js +31 -0
  345. package/dist/modules/workspace/ripgrep-version.js.map +1 -0
  346. package/dist/modules/workspace/startup/beside-checkout.d.ts +8 -5
  347. package/dist/modules/workspace/startup/beside-checkout.d.ts.map +1 -1
  348. package/dist/modules/workspace/startup/beside-checkout.js +14 -5
  349. package/dist/modules/workspace/startup/beside-checkout.js.map +1 -1
  350. package/dist/modules/workspace/worker-pool.d.ts +3 -4
  351. package/dist/modules/workspace/worker-pool.d.ts.map +1 -1
  352. package/dist/modules/workspace/worker-pool.js.map +1 -1
  353. package/dist/modules/workspace/workspace-tmp.d.ts +146 -0
  354. package/dist/modules/workspace/workspace-tmp.d.ts.map +1 -0
  355. package/dist/modules/workspace/workspace-tmp.js +435 -0
  356. package/dist/modules/workspace/workspace-tmp.js.map +1 -0
  357. package/dist/modules/workspace/workspace.routes.d.ts.map +1 -1
  358. package/dist/modules/workspace/workspace.routes.js +5 -26
  359. package/dist/modules/workspace/workspace.routes.js.map +1 -1
  360. package/dist/modules/workspace/workspace.service.d.ts +47 -6
  361. package/dist/modules/workspace/workspace.service.d.ts.map +1 -1
  362. package/dist/modules/workspace/workspace.service.js +86 -6
  363. package/dist/modules/workspace/workspace.service.js.map +1 -1
  364. package/dist/modules/workspace/workspace.tools.d.ts +3 -2
  365. package/dist/modules/workspace/workspace.tools.d.ts.map +1 -1
  366. package/dist/modules/workspace/workspace.tools.js +531 -137
  367. package/dist/modules/workspace/workspace.tools.js.map +1 -1
  368. package/dist/shared/oauth-token-error.d.ts +23 -0
  369. package/dist/shared/oauth-token-error.d.ts.map +1 -0
  370. package/dist/shared/oauth-token-error.js +47 -0
  371. package/dist/shared/oauth-token-error.js.map +1 -0
  372. package/dist/shared/path-order.d.ts +28 -8
  373. package/dist/shared/path-order.d.ts.map +1 -1
  374. package/dist/shared/path-order.js +37 -8
  375. package/dist/shared/path-order.js.map +1 -1
  376. package/dist/shared/read-capped.d.ts +19 -0
  377. package/dist/shared/read-capped.d.ts.map +1 -0
  378. package/dist/shared/read-capped.js +45 -0
  379. package/dist/shared/read-capped.js.map +1 -0
  380. package/migrations/0022_session_version.sql +6 -0
  381. package/migrations/0023_agent_path.sql +3 -0
  382. package/migrations/meta/0022_snapshot.json +2360 -0
  383. package/migrations/meta/0023_snapshot.json +2378 -0
  384. package/migrations/meta/_journal.json +14 -0
  385. package/package.json +4 -3
  386. package/src/__tests__/hexis-catalog.ts +144 -0
  387. package/src/__tests__/pg-scratch.test.ts +69 -0
  388. package/src/__tests__/pg-scratch.ts +31 -0
  389. package/src/__tests__/real-disk.ts +21 -0
  390. package/src/__tests__/slow-ripgrep.ts +65 -0
  391. package/src/__tests__/tokens.ts +19 -0
  392. package/src/__tests__/tool-manuals.ts +32 -0
  393. package/src/__tests__/tool-wiring.ts +25 -0
  394. package/src/core/__tests__/boot-without-ripgrep.test.ts +34 -0
  395. package/src/core/__tests__/catalog-revision.test.ts +89 -0
  396. package/src/core/__tests__/damaged-document.tools.test.ts +2 -2
  397. package/src/core/__tests__/gated-boot.test.ts +8 -1
  398. package/src/core/__tests__/lifecycle.test.ts +46 -13
  399. package/src/core/__tests__/oauth-sign-in-real-file.test.ts +179 -0
  400. package/src/core/catalog-revision.ts +24 -2
  401. package/src/core/core-ports.ts +42 -0
  402. package/src/core/create-core-server.ts +14 -1
  403. package/src/core/create-core-services.ts +62 -15
  404. package/src/core/lifecycle.ts +26 -2
  405. package/src/index.ts +1 -1
  406. package/src/modules/access/__tests__/access-control.admin-root-floor.test.ts +12 -0
  407. package/src/modules/access/__tests__/access-control.colliding-name-cases.test.ts +113 -0
  408. package/src/modules/access/__tests__/access-control.frontmatter-head.test.ts +117 -0
  409. package/src/modules/access/__tests__/access-control.group-named-admin.test.ts +122 -0
  410. package/src/modules/access/__tests__/access-control.preview-relocation.test.ts +50 -0
  411. package/src/modules/access/__tests__/access-declarations.test.ts +19 -0
  412. package/src/modules/access/__tests__/access-groups.test.ts +55 -22
  413. package/src/modules/access/__tests__/access-mutation.service.test.ts +85 -59
  414. package/src/modules/access/__tests__/access-restrict-here.test.ts +7 -5
  415. package/src/modules/access/__tests__/access.routes.admins.test.ts +1 -0
  416. package/src/modules/access/__tests__/access.routes.batch.test.ts +2 -0
  417. package/src/modules/access/__tests__/access.routes.folder-governs.test.ts +2 -0
  418. package/src/modules/access/__tests__/access.routes.group-grant.test.ts +50 -14
  419. package/src/modules/access/__tests__/access.routes.overrides.test.ts +2 -1
  420. package/src/modules/access/__tests__/access.routes.proposal-branch.test.ts +1 -0
  421. package/src/modules/access/__tests__/access.routes.prospective.test.ts +52 -10
  422. package/src/modules/access/__tests__/access.routes.revoke.test.ts +18 -13
  423. package/src/modules/access/__tests__/access.routes.unknown-email.test.ts +2 -0
  424. package/src/modules/access/__tests__/grant-sources.test.ts +20 -15
  425. package/src/modules/access/__tests__/groups-admin.routes.test.ts +61 -0
  426. package/src/modules/access/__tests__/groups-admin.service.test.ts +211 -18
  427. package/src/modules/access/__tests__/holder-changes.test.ts +127 -0
  428. package/src/modules/access/__tests__/reference-scan.test.ts +366 -14
  429. package/src/modules/access/__tests__/roles-admin.security.test.ts +1 -1
  430. package/src/modules/access/__tests__/roles-admin.service.test.ts +43 -22
  431. package/src/modules/access/__tests__/roles-capabilities.test.ts +6 -2
  432. package/src/modules/access/__tests__/roles.routes.test.ts +1 -1
  433. package/src/modules/access/access-control.interface.ts +43 -10
  434. package/src/modules/access/access-control.service.ts +250 -72
  435. package/src/modules/access/access-mutation.service.ts +48 -53
  436. package/src/modules/access/access-view.ts +12 -10
  437. package/src/modules/access/access.routes.ts +66 -37
  438. package/src/modules/access/groups-admin.routes.ts +4 -2
  439. package/src/modules/access/groups-admin.service.ts +114 -44
  440. package/src/modules/access/groups-edit.ts +1 -1
  441. package/src/modules/access/index.ts +1 -1
  442. package/src/modules/access/reference-scan.ts +319 -46
  443. package/src/modules/access/roles-admin.service.ts +43 -26
  444. package/src/modules/access/synced-groups-writer.ts +1 -1
  445. package/src/modules/access-model/__tests__/access-grammar.test.ts +38 -1
  446. package/src/modules/access-model/__tests__/access-splice.test.ts +50 -8
  447. package/src/modules/access-model/access-grammar.ts +65 -20
  448. package/src/modules/access-model/access-splice.ts +31 -23
  449. package/src/modules/access-model/group-files.ts +5 -0
  450. package/src/modules/agent-guide/__tests__/agent-guide.test.ts +110 -25
  451. package/src/modules/agent-guide/__tests__/agent-guide.tools.test.ts +38 -11
  452. package/src/modules/agent-guide/__tests__/guide-budget.test.ts +95 -0
  453. package/src/modules/agent-guide/__tests__/guide-eval.test.ts +182 -0
  454. package/src/modules/agent-guide/__tests__/guide-matches-code.test.ts +263 -0
  455. package/src/modules/agent-guide/__tests__/tool-surface.json +514 -0
  456. package/src/modules/agent-guide/__tests__/tool-surface.test.ts +75 -0
  457. package/src/modules/agent-guide/agent-guide.tools.ts +51 -22
  458. package/src/modules/agent-guide/agent-guide.ts +120 -13
  459. package/src/modules/agent-guide/guide-budget.ts +73 -0
  460. package/src/modules/agent-guide/index.ts +12 -0
  461. package/src/modules/agent-instructions/__tests__/shared-file-rules.test.ts +5 -4
  462. package/src/modules/agent-instructions/compose.ts +7 -1
  463. package/src/modules/agent-instructions/shared-file-rules.ts +27 -9
  464. package/src/modules/agent-scope/__tests__/agent-surfaces.connect-as.test.ts +421 -0
  465. package/src/modules/agent-scope/__tests__/connection-scope.test.ts +46 -0
  466. package/src/modules/agent-scope/__tests__/in-memory-kb.ts +148 -0
  467. package/src/modules/agent-scope/agent-scope.contract.ts +83 -0
  468. package/src/modules/agent-scope/connection-scope.ts +199 -0
  469. package/src/modules/agent-scope/index.ts +15 -0
  470. package/src/modules/audit/agent-audit.service.ts +2 -0
  471. package/src/modules/audit/audit.contract.ts +6 -0
  472. package/src/modules/auth/__tests__/auth.middleware.test.ts +30 -2
  473. package/src/modules/auth/__tests__/auth.routes.test.ts +71 -5
  474. package/src/modules/auth/__tests__/auth.service.test.ts +90 -9
  475. package/src/modules/auth/__tests__/password-change-sessions.pg.test.ts +269 -0
  476. package/src/modules/auth/account-admission.ts +19 -0
  477. package/src/modules/auth/auth.middleware.ts +45 -4
  478. package/src/modules/auth/auth.routes.ts +46 -29
  479. package/src/modules/auth/auth.service.ts +135 -34
  480. package/src/modules/auth/index.ts +2 -0
  481. package/src/modules/auth/oidc-auth-provider.ts +2 -9
  482. package/src/modules/code-mode/code-mode.tool.ts +2 -2
  483. package/src/modules/connection-probe/__tests__/connection-probe.service.test.ts +5 -24
  484. package/src/modules/connection-probe/connection-probe.service.ts +1 -34
  485. package/src/modules/database/__tests__/session-version-migration.pg.test.ts +133 -0
  486. package/src/modules/database/core-schema.ts +33 -0
  487. package/src/modules/declared-variables/__tests__/declared-variables.route.test.ts +44 -1
  488. package/src/modules/declared-variables/declared-variables.routes.ts +12 -1
  489. package/src/modules/embed/__tests__/embed.tools.test.ts +12 -0
  490. package/src/modules/embed/embed.tools.ts +5 -0
  491. package/src/modules/kb-fs/__tests__/locking-filesystem.test.ts +25 -0
  492. package/src/modules/kb-fs/__tests__/repo-path.test.ts +53 -8
  493. package/src/modules/kb-fs/index.ts +2 -0
  494. package/src/modules/kb-fs/locking-filesystem.ts +7 -1
  495. package/src/modules/kb-fs/repo-path.ts +33 -7
  496. package/src/modules/kb-fs/tmp-ref.ts +81 -0
  497. package/src/modules/mcp/__tests__/connect-as.pg.test.ts +137 -0
  498. package/src/modules/mcp/__tests__/mcp-auth.middleware.test.ts +29 -5
  499. package/src/modules/mcp/__tests__/mcp-routes-harness.ts +8 -0
  500. package/src/modules/mcp/__tests__/mcp.connect-as.test.ts +195 -0
  501. package/src/modules/mcp/__tests__/mcp.routes.connect-as.test.ts +192 -0
  502. package/src/modules/mcp/__tests__/oauth-consent.connect-as.test.ts +146 -0
  503. package/src/modules/mcp/mcp-auth.middleware.ts +19 -2
  504. package/src/modules/mcp/mcp.routes.ts +39 -3
  505. package/src/modules/mcp/mcp.service.ts +112 -52
  506. package/src/modules/mcp/oauth/bevel-oauth-provider.ts +46 -8
  507. package/src/modules/mcp/oauth/oauth-consent.routes.ts +41 -1
  508. package/src/modules/plugins/__tests__/plugins.tools.test.ts +38 -2
  509. package/src/modules/plugins/index.ts +1 -1
  510. package/src/modules/plugins/plugin-links.ts +19 -2
  511. package/src/modules/plugins/plugins.routes.ts +35 -4
  512. package/src/modules/secrets-vault/__tests__/connect-pending.route.test.ts +113 -0
  513. package/src/modules/secrets-vault/__tests__/db-secrets-vault.oauth.test.ts +430 -3
  514. package/src/modules/secrets-vault/__tests__/oauth-live-declaration.route.test.ts +218 -0
  515. package/src/modules/secrets-vault/__tests__/oauth-return-to.route.test.ts +39 -6
  516. package/src/modules/secrets-vault/db-secrets-vault.service.ts +170 -27
  517. package/src/modules/secrets-vault/index.ts +1 -1
  518. package/src/modules/secrets-vault/secrets-vault.contract.ts +61 -11
  519. package/src/modules/secrets-vault/secrets-vault.routes.ts +114 -42
  520. package/src/modules/settings/oidc-check.ts +5 -18
  521. package/src/modules/skills/__tests__/skills.service.test.ts +34 -0
  522. package/src/modules/skills/index.ts +7 -2
  523. package/src/modules/skills/skills.contract.ts +17 -0
  524. package/src/modules/skills/skills.service.ts +5 -1
  525. package/src/modules/skills/skills.tools.ts +45 -14
  526. package/src/modules/tool-auth/__tests__/external-api-key.service.test.ts +4 -0
  527. package/src/modules/tool-auth/external-api-key.interface.ts +11 -1
  528. package/src/modules/tool-auth/external-api-key.service.ts +5 -2
  529. package/src/modules/tool-auth/index.ts +1 -1
  530. package/src/modules/tool-auth/internal-token.service.ts +10 -0
  531. package/src/modules/tool-auth/tool-auth.middleware.ts +45 -3
  532. package/src/modules/tool-helpers/__tests__/agent-roles-write.test.ts +19 -11
  533. package/src/modules/tool-helpers/__tests__/can-write.tools.test.ts +3 -1
  534. package/src/modules/tool-helpers/__tests__/route-tool-schemas.catalog.test.ts +38 -0
  535. package/src/modules/tool-helpers/tool-context.ts +10 -0
  536. package/src/modules/tool-helpers/tool-def.ts +1 -1
  537. package/src/modules/tool-helpers/tool-handler.ts +34 -0
  538. package/src/modules/tool-helpers/tool.contract.ts +10 -0
  539. package/src/modules/tool-helpers/validate-token.ts +4 -2
  540. package/src/modules/tool-manuals/__tests__/tool-manuals.archive.route.test.ts +80 -4
  541. package/src/modules/tool-manuals/__tests__/tool-manuals.mcp-oauth.test.ts +197 -11
  542. package/src/modules/tool-manuals/__tests__/tool-manuals.service.test.ts +42 -0
  543. package/src/modules/tool-manuals/__tests__/tool-manuals.tools.test.ts +99 -8
  544. package/src/modules/tool-manuals/index.ts +6 -2
  545. package/src/modules/tool-manuals/mcp-json-discovery.ts +73 -34
  546. package/src/modules/tool-manuals/tool-manuals.contract.ts +40 -6
  547. package/src/modules/tool-manuals/tool-manuals.routes.ts +40 -3
  548. package/src/modules/tool-manuals/tool-manuals.service.ts +169 -61
  549. package/src/modules/tool-manuals/tool-manuals.tools.ts +81 -25
  550. package/src/modules/tool-registry/__tests__/tool-description-length.test.ts +6 -113
  551. package/src/modules/tool-registry/manual.routes.ts +26 -5
  552. package/src/modules/tool-registry/tool.contract.ts +7 -0
  553. package/src/modules/workflow/__tests__/workflow.service.facade.test.ts +1 -1
  554. package/src/modules/workflow/__tests__/workflow.service.sync.test.ts +1 -1
  555. package/src/modules/workflow/agent-tools/__tests__/workflow.tools.test.ts +54 -3
  556. package/src/modules/workflow/agent-tools/workflow.tools.ts +36 -27
  557. package/src/modules/workflow/git/__tests__/git.service.list-branches.test.ts +130 -3
  558. package/src/modules/workflow/git/git.service.ts +29 -48
  559. package/src/modules/workflow/workflow.service.ts +5 -0
  560. package/src/modules/workspace/__tests__/git-internals.security.test.ts +2 -2
  561. package/src/modules/workspace/__tests__/holds-nul.test.ts +66 -0
  562. package/src/modules/workspace/__tests__/rest-tool-arguments.test.ts +3 -3
  563. package/src/modules/workspace/__tests__/ripgrep-search.test.ts +570 -0
  564. package/src/modules/workspace/__tests__/ripgrep-version.test.ts +29 -0
  565. package/src/modules/workspace/__tests__/workspace-tmp.tools.test.ts +928 -0
  566. package/src/modules/workspace/__tests__/workspace.routes.read-gate.test.ts +17 -37
  567. package/src/modules/workspace/__tests__/workspace.service.read-filter.test.ts +20 -8
  568. package/src/modules/workspace/__tests__/workspace.tools.agents-file.test.ts +10 -12
  569. package/src/modules/workspace/__tests__/workspace.tools.branch-errors.test.ts +22 -10
  570. package/src/modules/workspace/__tests__/workspace.tools.test.ts +549 -162
  571. package/src/modules/workspace/agent-access.gate.ts +1 -1
  572. package/src/modules/workspace/file-readers/__tests__/doc-extract.service.test.ts +10 -0
  573. package/src/modules/workspace/file-readers/doc-extract.service.ts +71 -38
  574. package/src/modules/workspace/index.ts +20 -0
  575. package/src/modules/workspace/nul-scan.ts +50 -0
  576. package/src/modules/workspace/pattern-matcher.contract.ts +123 -32
  577. package/src/modules/workspace/ripgrep-search.ts +715 -0
  578. package/src/modules/workspace/ripgrep-version.ts +35 -0
  579. package/src/modules/workspace/startup/__tests__/beside-checkout.test.ts +11 -0
  580. package/src/modules/workspace/startup/beside-checkout.ts +13 -5
  581. package/src/modules/workspace/worker-pool.ts +3 -4
  582. package/src/modules/workspace/workspace-tmp.ts +457 -0
  583. package/src/modules/workspace/workspace.routes.ts +6 -27
  584. package/src/modules/workspace/workspace.service.ts +92 -15
  585. package/src/modules/workspace/workspace.tools.ts +574 -176
  586. package/src/shared/__tests__/read-capped.test.ts +68 -0
  587. package/src/shared/oauth-token-error.ts +46 -0
  588. package/src/shared/path-order.ts +37 -8
  589. package/src/shared/read-capped.ts +40 -0
  590. package/starter-packs/engineering/Plugins/engineering-starter/access.md +1 -1
  591. package/starter-packs/general/Plugins/general-starter/access.md +1 -1
  592. package/starter-packs/operations/Plugins/operations-starter/access.md +1 -1
  593. package/starter-packs/sales/Plugins/sales-starter/access.md +1 -1
  594. package/starter-packs/support/Plugins/support-starter/access.md +1 -1
  595. package/agent-guide/finding-things.md +0 -7
  596. package/agent-guide/introduction.md +0 -27
  597. package/dist/modules/workspace/bounded-matcher.d.ts +0 -73
  598. package/dist/modules/workspace/bounded-matcher.d.ts.map +0 -1
  599. package/dist/modules/workspace/bounded-matcher.js +0 -200
  600. package/dist/modules/workspace/bounded-matcher.js.map +0 -1
  601. package/src/modules/workspace/__tests__/bounded-matcher.test.ts +0 -213
  602. package/src/modules/workspace/bounded-matcher.ts +0 -271
package/agent-guide/html-views.md CHANGED
@@ -3,7 +3,13 @@
3
3
  An `.html` (or `.htm`) file in the knowledge base is a live page: the app shows
4
4
  it in a sandboxed frame, scripts and all. Write one when a reader is better
5
5
  served by something interactive — a dashboard, a filterable table, a chart —
6
- than by a markdown document.
6
+ than by a markdown document. Plain HTML with inline CSS and JavaScript is
7
+ enough; no skill or template is needed.
8
+
9
+ **Data written into the page is governed by the page's access.** A tool call
10
+ answers each viewer only what they may read; bytes in the file reach everyone
11
+ who may read the page, so never copy in data from a source fewer people may
12
+ read.
7
13
 
8
14
  ### The frame
9
15
 
@@ -15,6 +21,10 @@ than by a markdown document.
15
21
  `<object>`, `<embed>`, `<base>` and `<meta>` are removed. Write CSS in a
16
22
  `<style>` element and code in an inline `<script>`. An image is a `data:`
17
23
  URL.
24
+ - **The body is the page.** The app shows the sanitised contents of `<body>`
25
+ in a document of its own: `<style>` and inline `<script>` in `<head>` are
26
+ kept, moved to the start of the body; everything else in `<head>` and the
27
+ attributes on `<html>` and `<body>` are ignored.
18
28
  - **Scripts run as ES modules**, in source order, after the document is
19
29
  parsed: `document.getElementById` works without waiting for
20
30
  `DOMContentLoaded`, top-level `await` works, and a top-level declaration is
@@ -28,11 +38,17 @@ than by a markdown document.
28
38
 
29
39
  ### `window.bevel`
30
40
 
31
- Core puts four members on it:
41
+ Core puts five members on it:
32
42
 
33
43
  - `window.bevel.openNode(href)` — follow `href` as if the reader had clicked a
34
44
  link to it.
35
45
  - `window.bevel.navigate(href)` — the same function under a second name.
46
+ - `window.bevel.branch` — the branch the page is viewed on, as a string: a
47
+ page that reads its data through the tools and links to what they name
48
+ does both there, so the same page shows a draft's data on the draft and the
49
+ released data on the default branch. `null` where the host has no branch
50
+ for the page (a page embedded on another site); read it as `window.bevel?.branch
51
+ ?? '<default branch>'` so the page still works there.
36
52
  - `window.bevel.tools` — the viewer's tools, or `null` where there are none
37
53
  (next section).
38
54
  - `window.bevel.requireTools()` — ask for the tools when the page cannot work
@@ -80,7 +96,7 @@ assume it is there:
80
96
  ```js
81
97
  const tools = window.bevel?.tools;
82
98
  if (tools) {
83
- const file = await tools.callTool('read_file', { body: { branch: 'main', path: '{{knowledgeBaseDir}}/Foo.md' } });
99
+ const file = await tools.callTool('read_file', { body: { branch: '{{defaultBranch}}', path: '{{knowledgeBaseDir}}/Foo.md' } });
84
100
  // …show it
85
101
  } else {
86
102
  // …render without it
@@ -125,7 +141,7 @@ the app; the page never sees it.
125
141
  const input = document.getElementById('briefing');
126
142
  input.addEventListener('change', async () => {
127
143
  const answer = await window.bevel.tools.uploadFile(input.files[0], {
128
- branch: 'main',
144
+ branch: '{{defaultBranch}}',
129
145
  destination: '{{knowledgeBaseDir}}/Campaigns/Easter',
130
146
  });
131
147
  // answer.files[0].path is where it landed
@@ -147,11 +163,209 @@ if (await window.bevel?.requireTools?.()) {
147
163
  }
148
164
  ```
149
165
 
166
+ ### Live data: a page that stays still while it loads
167
+
168
+ A page that reads its data through `window.bevel.tools` waits on several
169
+ calls before it has anything to show. Write it so the reader never sees the
170
+ page change shape, never sees a half-loaded board as if it were the answer,
171
+ and never loses the board they were reading:
172
+
173
+ - **Render the final page shell in the markup, before any data.** Headings,
174
+ columns, panels and the controls are in the HTML itself, with their size
175
+ reserved in CSS (a grid, a `min-height` per region). The loading treatment —
176
+ placeholder rows, `aria-busy="true"` — sits **inside** the data regions.
177
+ Never start with one "Loading…" line that the script later swaps for the
178
+ whole page: that swap is a full-page layout change, and the first thing the
179
+ reader sees looks broken.
180
+ - **Publish one consistent dataset at a time.** Collect every read into local
181
+ variables first; when ALL of them have succeeded, update every data region
182
+ from that one dataset in one synchronous step. Until then show no counts,
183
+ no cards and no empty columns: "0" or "None" is an answer only a finished
184
+ dataset may give.
185
+ - **Refresh keeps the current board.** A refresh leaves the last published
186
+ dataset on screen, shows a small refreshing state (a status line, the
187
+ Refresh button disabled) and publishes the replacement only when it is
188
+ complete. Never return to the loading placeholders.
189
+ - **A failed read fails the whole load, visibly.** If any read the page needs
190
+ rejects, publish nothing from that load: keep the shell (first load) or the
191
+ last good dataset (refresh), say what failed — the rejection carries the
192
+ tool's own message — and offer a Retry button that runs the same load
193
+ again. Never show the reads that did succeed as if they were the whole
194
+ board.
195
+ - **Read in bounded parallel once the paths are known.** List first
196
+ (`list_files`, `grep`), then read the files it named with a small fixed
197
+ number of `callTool` reads in flight at a time — four is plenty — rather
198
+ than one after another or all at once. Read tools run at once with no
199
+ prompt.
200
+ - **Load with `callTool`, not `callToolChain`.** A chain may write, so the app
201
+ asks the viewer before it runs: a page that loads through `callToolChain`
202
+ shows its reader a "wants to write" card for a read.
203
+ - **The reads are the viewer's own.** Every call answers with exactly what
204
+ the person viewing the page may read: `list_files` and `grep` leave out
205
+ what they may not, and `read_file` of such a file rejects. Build the board
206
+ from what the calls return; never try to widen it (another identity, a
207
+ copied dataset) — the same page shows each reader their own board.
208
+ - **Link to what the tools named by the path they answered.** A path a tool
209
+ answers (`read_file`'s `path`, a listing's `path`) starts with the checkout
210
+ folder, `{{kbDirName}}/Data/Tickets/A.md`, and knows nothing of where the
211
+ page sits. Link to it on the branch the page read it from, each segment of
212
+ the path encoded on its own — `'/workspace/' + encodeURIComponent(BRANCH)
213
+ + '/' + path.split('/').map(encodeURIComponent).join('/')` — so a card and
214
+ its data come from one branch and a name carrying `#`, `?` or `%` stays
215
+ in the path rather than ending the URL at it; a root-relative `'/' +
216
+ path.split('/').map(encodeURIComponent).join('/')` opens it on the branch
217
+ the page is viewed on instead (see *How a link resolves*). Never put the
218
+ checkout folder in front of a path a tool answered: it is already there.
219
+
220
+ A complete page that follows these rules — plain HTML and one inline script,
221
+ no build step and no framework:
222
+
223
+ ```html
224
+ <!doctype html>
225
+ <html>
226
+ <head>
227
+ <style>
228
+ body { font: 14px system-ui, sans-serif; margin: 16px; }
229
+ .board { display: grid; grid-template-columns: repeat(3, 1fr); gap: 12px; }
230
+ .column { min-height: 320px; border: 1px solid #ddd; padding: 8px; }
231
+ .column li { min-height: 20px; padding: 6px; list-style: none; }
232
+ #status.error { color: #b00020; }
233
+ </style>
234
+ </head>
235
+ <body>
236
+ <header>
237
+ <h1>Tickets</h1>
238
+ <button id="refresh" type="button" disabled>Refresh</button>
239
+ <span id="status" role="status">Loading…</span>
240
+ <button id="retry" type="button" hidden>Retry</button>
241
+ </header>
242
+ <main id="board" class="board" aria-busy="true">
243
+ <section class="column" data-status="todo"><h2>To do <span class="count"></span></h2><ul><li class="placeholder"></li><li class="placeholder"></li></ul></section>
244
+ <section class="column" data-status="doing"><h2>Doing <span class="count"></span></h2><ul><li class="placeholder"></li><li class="placeholder"></li></ul></section>
245
+ <section class="column" data-status="done"><h2>Done <span class="count"></span></h2><ul><li class="placeholder"></li><li class="placeholder"></li></ul></section>
246
+ </main>
247
+ <script>
248
+ // The branch the page is viewed on: its data and its links both come from
249
+ // there, so the page on a draft shows the draft's tickets. Outside the app
250
+ // (no bridge) it reads the default branch.
251
+ const BRANCH = window.bevel?.branch ?? 'main';
252
+ const FOLDER = 'Data/Tickets';
253
+ const READS_IN_FLIGHT = 4;
254
+ const tools = window.bevel?.tools;
255
+ const board = document.getElementById('board');
256
+ const statusLine = document.getElementById('status');
257
+ const refreshButton = document.getElementById('refresh');
258
+ const retryButton = document.getElementById('retry');
259
+ let published = false;
260
+
261
+ /** The text under `# <heading>` in a node's markdown, whatever its line endings. */
262
+ function field(markdown, heading) {
263
+ const lines = markdown.split(/\r?\n/);
264
+ const at = lines.indexOf('# ' + heading);
265
+ if (at < 0) return '';
266
+ const end = lines.findIndex((line, i) => i > at && line.startsWith('# '));
267
+ return lines.slice(at + 1, end < 0 ? undefined : end).join('\n').trim();
268
+ }
269
+
270
+ /**
271
+ * `fn` over `items`, at most `limit` at a time. After a failure no new item
272
+ * starts; it rejects with the first failure once the calls in flight have
273
+ * settled, so a Retry never overlaps the load that failed.
274
+ */
275
+ async function mapBounded(items, limit, fn) {
276
+ const results = new Array(items.length);
277
+ let next = 0;
278
+ let failure = null;
279
+ async function worker() {
280
+ while (!failure && next < items.length) {
281
+ const i = next++;
282
+ try {
283
+ results[i] = await fn(items[i]);
284
+ } catch (error) {
285
+ failure ??= { error };
286
+ }
287
+ }
288
+ }
289
+ await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
290
+ if (failure) throw failure.error;
291
+ return results;
292
+ }
293
+
294
+ /** The whole dataset, or a rejection. Touches no element. */
295
+ async function readTickets() {
296
+ const listing = await tools.callTool('list_files', { body: { branch: BRANCH, path: FOLDER } });
297
+ const paths = listing.entries
298
+ .filter((entry) => entry.type === 'file' && entry.name.endsWith('.md'))
299
+ .map((entry) => `${FOLDER}/${entry.name}`);
300
+ return mapBounded(paths, READS_IN_FLIGHT, async (path) => {
301
+ const file = await tools.callTool('read_file', { body: { branch: BRANCH, path } });
302
+ // `file.path` is the path as the tool names it, checkout folder first.
303
+ return { path: file.path, name: field(file.content, 'Name') || path, status: field(file.content, 'Status').toLowerCase() };
304
+ });
305
+ }
306
+
307
+ /** Every data region from one dataset, in one synchronous step. */
308
+ function publish(tickets) {
309
+ for (const column of board.querySelectorAll('.column')) {
310
+ const mine = tickets.filter((ticket) => ticket.status === column.dataset.status);
311
+ column.querySelector('.count').textContent = `(${mine.length})`;
312
+ const items = mine.map((ticket) => {
313
+ const link = document.createElement('a');
314
+ // Each segment encoded on its own: a name with `#` in it stays a name.
315
+ link.href = '/workspace/' + encodeURIComponent(BRANCH) + '/' + ticket.path.split('/').map(encodeURIComponent).join('/');
316
+ link.textContent = ticket.name;
317
+ const item = document.createElement('li');
318
+ item.append(link);
319
+ return item;
320
+ });
321
+ if (items.length === 0) {
322
+ const none = document.createElement('li');
323
+ none.textContent = 'None';
324
+ items.push(none);
325
+ }
326
+ column.querySelector('ul').replaceChildren(...items);
327
+ }
328
+ published = true;
329
+ }
330
+
331
+ async function load() {
332
+ refreshButton.disabled = true;
333
+ retryButton.hidden = true;
334
+ board.setAttribute('aria-busy', 'true');
335
+ statusLine.className = '';
336
+ statusLine.textContent = published ? 'Refreshing…' : 'Loading…';
337
+ try {
338
+ publish(await readTickets());
339
+ statusLine.textContent = `Updated ${new Date().toLocaleTimeString()}`;
340
+ } catch (error) {
341
+ statusLine.className = 'error';
342
+ statusLine.textContent = (published ? 'Could not refresh; showing the last loaded board. ' : 'Could not load the tickets. ') + error.message;
343
+ retryButton.hidden = false;
344
+ } finally {
345
+ board.setAttribute('aria-busy', 'false');
346
+ refreshButton.disabled = false;
347
+ }
348
+ }
349
+
350
+ refreshButton.addEventListener('click', load);
351
+ retryButton.addEventListener('click', load);
352
+ if (tools) {
353
+ load();
354
+ } else {
355
+ board.setAttribute('aria-busy', 'false');
356
+ statusLine.textContent = 'Open this page in Bevel to load the tickets.';
357
+ }
358
+ </script>
359
+ </body>
360
+ </html>
361
+ ```
362
+
150
363
  ### Links written in the markup
151
364
 
152
365
  An `<a href>` in the page keeps its address only when it is one of these:
153
366
 
154
367
  - a document of the knowledge base, `.md`, `.html` or `.htm`, with or without a heading — `../Knowledge/Alice.md#goal`, `Q3-Report.html`, `Notes.htm`
368
+ - a root-relative path to such a document, from the checkout folder — `/{{kbDirName}}/Data/Tickets/A.md`
155
369
  - an absolute workspace URL — `/workspace/main/{{knowledgeBaseDir}}/Alice.md`
156
370
  - an external address — `https://example.com/docs`, `http://example.com`, `mailto:team@example.com`
157
371
  - a bare fragment, a place in this page — `#totals`, `#`
@@ -177,10 +391,22 @@ or `window.bevel.navigate(href)`:
177
391
  top" link. The page's own address does not change, so `hashchange` never
178
392
  fires: a page that routes by hash handles its own clicks.
179
393
  - **A relative path** resolves against the folder of the page's own file and
180
- opens that file in the app: from `{{knowledgeBaseDir}}/Reports/Q3.html`,
181
- `../Knowledge/Alice.md#goal` opens `{{knowledgeBaseDir}}/Knowledge/Alice.md`
182
- at its `goal` heading.
183
- - **`/workspace/<branch>/<path>`** opens that file on that branch.
394
+ opens that file in the app, in a new tab, leaving the page where it is:
395
+ from `{{knowledgeBaseDir}}/Reports/Q3.html`, `../Knowledge/Alice.md#goal`
396
+ opens `{{knowledgeBaseDir}}/Knowledge/Alice.md` at its `goal` heading. A
397
+ path that names the page's own file with a fragment (`Q3.html#totals`
398
+ from `Q3.html`) scrolls the page, as `#totals` does.
399
+ - **A root-relative path**, `/{{kbDirName}}/<path>`, opens that file on the
400
+ page's own branch, in a new tab, from a page in any folder. A path a tool
401
+ answered (`read_file`'s `path`, a listing's `path`) already starts with the
402
+ checkout folder, so it is linked as `'/' +
403
+ path.split('/').map(encodeURIComponent).join('/')` — each segment encoded
404
+ on its own, so a name carrying `#`, `?` or `%` stays a name — never with
405
+ the folder put in front of it again; a path the page composed itself,
406
+ without that prefix, gets `'/{{kbDirName}}/'` in front. A link the page's
407
+ script creates after load is kept as written.
408
+ - **`/workspace/<branch>/<path>`** opens that file on that branch, in a new
409
+ tab.
184
410
  - **An external address** (`http:`, `https:`, `mailto:`) opens in a new tab.
185
411
  A call from a script may also open `tel:`, `sms:`, `geo:` and a
186
412
  protocol-relative `//host/path` address in a new tab, though a link
@@ -191,3 +417,8 @@ or `window.bevel.navigate(href)`:
191
417
  A click that a handler of the page has already cancelled with
192
418
  `event.preventDefault()` is left to that handler: the bridge neither scrolls
193
419
  nor opens anything for it.
420
+
421
+ A click on a link with Ctrl, Cmd or Shift held, or with the middle button,
422
+ opens its destination in a new tab, as a browser does with a link: a bare
423
+ fragment opens the page's own file at that section in a new tab, and the
424
+ page stays where it is.
package/agent-guide/new-knowledge-base.md CHANGED
@@ -1,21 +1,22 @@
1
1
  ## A new knowledge base
2
2
 
3
3
  When `start_session` answers with a `firstRun` note, this knowledge base is
4
- new: `{{kbDirName}}/{{knowledgeBaseDir}}/` has no pages yet, the starter guide
5
- aside. The person has most likely just connected you, and you are the quickest way to
6
- fill it. The note stops coming once real pages exist.
4
+ new: `{{kbDirName}}/{{knowledgeBaseDir}}/` holds nothing but its starter guide
5
+ and any starter pages nobody has changed yet. The person has most likely just
6
+ connected you, and you are the quickest way to fill it. The note stops coming
7
+ once real pages exist.
7
8
 
8
9
  - **Offer once per conversation, in a sentence or two.** For example: "Your
9
- Hexis knowledge base is connected and almost empty. Want me to draft a few
10
- pages about your company — what you do, your customers, your products, your
11
- glossary? Give me your website or tell me a bit, and I'll write them for you
12
- to review."
10
+ knowledge base is connected and almost empty. Want me to draft a few pages
11
+ about your company (what you do, your customers, your products, your
12
+ glossary)? Give me your website or tell me a bit, and I'll write them for
13
+ you to review."
13
14
  - **Never in the way.** If they asked for something else, do that first and
14
15
  make the offer in one line at the end. If they decline, drop it.
15
16
  - **Draft from what they give you.** Read the website they name, or work from
16
17
  what they tell you, and ask when something essential is missing rather than
17
18
  inventing it. Good first pages: About the company, Customers, Products,
18
- Glossary, How we work. Say where each fact came from (see Conventions).
19
+ Glossary, How we work. Say where each fact came from (see `conventions`).
19
20
  - **Write them with the normal tools** (`write_file`, `write_files`) as
20
21
  markdown under `{{kbDirName}}/{{knowledgeBaseDir}}/`, one page per subject.
21
22
  Leave the starter guide as it is. A write you are refused says whether you
package/agent-guide/skills.md CHANGED
@@ -1,55 +1,80 @@
1
1
  ## Skills (`{{skillsDir}}/<scope>/…/<skill>/SKILL.md`, or `{{pluginsDir}}/<Plugin>/skills/<skill>/SKILL.md`)
2
2
 
3
3
  A skill is a folder holding a `SKILL.md` and whatever files it needs. Shared
4
- skills live under `{{skillsDir}}/`, organised by ownership; a skill that belongs to
5
- exactly one plugin may live inside that plugin's `skills/` folder instead.
6
- Skill names are unique across the whole catalog, whichever home they have.
7
- The frontmatter names it, declares which tools it may use, and may carry a
8
- version:
4
+ skills live under `{{skillsDir}}/`, organised by ownership; a skill that
5
+ belongs to one plugin alone may live in that plugin's `skills/` folder. Skill
6
+ names are unique across the catalog. The frontmatter names the skill, says
7
+ when to use it, and may list tools and a version:
9
8
 
10
9
  ```yaml
11
10
  ---
12
11
  name: weekly-newsletter
13
- description: Drafts the Friday newsletter for review.
12
+ description: "Use when someone asks for the Friday newsletter: drafts it for review."
14
13
  allowed-tools: [slack_post_message]
15
14
  metadata:
16
15
  version: "1.4.0"
17
16
  ---
18
17
  ```
19
18
 
20
- The body is the instructions, in plain markdown. `allowed-tools` entries are
21
- tool names from the `.tool` manuals and MCP servers of the plugins that hold
22
- the skill, and the agent client's own tools beside them (`Bash`, `Read`,
23
- `Bash(git:*)` and the like, which the platform leaves to the client).
24
- `metadata.version` is semver; `list_skills` reports it, and
25
- `get_skill` with a `version` loads the skill as it was when it last declared
26
- that version (omit `version` for the latest). Any other `metadata` keys are
27
- the author's own notes — the catalog carries the file as it is and acts on
28
- none of them.
29
-
30
- Before offering to change a skill, read its `canWrite`: `list_skills` judges
31
- the `SKILL.md`; `get_skill` judges every file of the skill unless `file` is
32
- passed, in which case it judges only that file — a bundled file's `true` is
33
- not the skill's; both by the default branch's rules whichever branch you
34
- read. `canWrite: false` means use a branch and a change request; do not
35
- offer a direct write (see *Direct writes vs change requests* under **Access
36
- control**).
37
-
38
- A `SKILL.md` committed on the default branch is listed and loadable from the
39
- very next `list_skills` or `get_skill`, on the connection you already have:
40
- the released catalog is cached briefly and dropped the moment the default
41
- branch changes, so the next request reads the workspace again.
42
- See *A released tool or skill is live within ten seconds* under **Tool
43
- Manuals** for the one caveat (an MCP client that caches the prompt list it
44
- was given at connect time must re-list — the prompt-list-changed notification
45
- that tells it to arrives with the connection's next catalog check, which is
46
- within ten seconds on a connection in use and at its next use on an idle
47
- one).
48
-
49
- **How skills reach agents.** Through the MCP server (`list_skills`,
50
- `get_skill`), or as native plugins: every user can clone a git remote from
51
- the app's external-agent page that holds a plugin marketplace compiled from
52
- exactly the skills they may read — one plugin per plugin here, a
53
- `skills-and-knowledge` plugin for the rest plus this knowledge base's MCP
54
- server, and `hexis-all`, one plugin holding every skill they may read and
55
- the MCP server, for a single install.
19
+ - **The frontmatter is YAML.** Quote a value that contains `: ` or starts
20
+ with a special character, as above, or the description comes out empty and
21
+ nobody finds the skill. Read it back with `get_skill` after writing.
22
+ - **`description` is how the skill is found**: agents load a skill when its
23
+ description fits the task. Say when to use it, in the words people use.
24
+ - **`allowed-tools`** names the tools the skill uses: any of the platform's
25
+ tools, a plugin's (as `<server>_<tool>`), and the client's own (`Bash`,
26
+ `Read`, `Bash(git:*)`). The platform warns about a name it does not know,
27
+ and enforces nothing.
28
+ - **`metadata.version`** (or a top-level `version`) is reported by
29
+ `list_skills`; `get_skill` with `version` loads the skill as it was when it
30
+ last declared that version. Other `metadata` keys are the author's notes.
31
+
32
+ The body is the instructions, in plain markdown.
33
+
34
+ **A skill on a draft is not live.** The app's skills page, the prompts and
35
+ `list_skills` without `branch` show only the released catalog, read from
36
+ `{{defaultBranch}}`, so a skill on a draft "doesn't exist" there until it is
37
+ merged. To try it, pass the draft: `list_skills({ body: { branch: "<draft>" } })`,
38
+ then `get_skill({ body: { name: "weekly-newsletter", branch: "<draft>" } })`.
39
+ A skill that differs from the released one comes back with `unmerged: true`,
40
+ and its body opens with a line saying it is not approved. Once merged, it is
41
+ in the next `list_skills` or `get_skill`; a client that cached the prompt list
42
+ when it connected must reconnect to show it as a prompt.
43
+
44
+ Before offering to change a skill, check its `canWrite` (see `access-control`).
45
+
46
+ **How skills reach agents.** Through this server (prompts, `list_skills`,
47
+ `get_skill`), or as native plugins: each person can install a plugin
48
+ marketplace from the app's external agent page, compiled from exactly the
49
+ skills they may read.
50
+
51
+ ### A skill that needs tools checks them first
52
+
53
+ A skill that calls another service fails for anyone who has not signed in, or
54
+ before the tool is merged. Make its first step a check, and stop with a plain
55
+ instruction rather than a failed call:
56
+
57
+ ```markdown
58
+ ## Before you start
59
+ Call `list_tool_setup`. Find the Jira tool. If a variable with `scope: user`
60
+ shows `userConfigured: false` (or `authorized: false` for a sign-in), stop and
61
+ say: "Open the Connect page in <app> and sign in to Jira, then ask me again."
62
+ If the tool is missing altogether, say it is not available to them yet and who
63
+ to ask.
64
+ ```
65
+
66
+ ### A guided skill for people who are not technical
67
+
68
+ When a skill is for someone who is not an engineer, such as turning an idea
69
+ into a ticket, write it to lead them:
70
+
71
+ - **One question per message**, the most important first. Never a list of
72
+ five.
73
+ - **Propose, then ask them to confirm.** "I would call it 'Search: filter by
74
+ date'. Is that right?" is easier to answer than "What is the title?".
75
+ - **A checklist for "specified enough"** in the skill (who it is for, what
76
+ should happen, how we know it works), and stop asking once it is met.
77
+ - **Plain words.** No platform terms (branch, change request, frontmatter,
78
+ tool names); show the result in their language before you create anything.
79
+ - **Check its tools first** (above), so the conversation does not end in an
80
+ error after ten questions.
package/agent-guide/start-here.md ADDED
@@ -0,0 +1,65 @@
1
+ ## Start here
2
+
3
+ You are connected to this organisation's knowledge base: its documents, and
4
+ the skills and tools its teams have approved, with access set per folder. To
5
+ the people you work with it is not a Git repository: say "knowledge base",
6
+ "draft" and "change request", and do not explain it as "a Git repo". If they
7
+ ask how it compares, see `for-git-users`.
8
+
9
+ **Read this once per conversation.** Then fetch only the section a task needs,
10
+ `get_agent_guide({ body: { section: "<id>" } })`, and do not reload the whole
11
+ guide. When you start a sub-agent, pass it the rules below and the one section
12
+ its task needs.
13
+
14
+ ### Before your first call
15
+
16
+ - **Every file tool takes `branch`.** `{{defaultBranch}}` is the default
17
+ branch: what is live for everyone. Work in progress lives on a draft branch.
18
+ For example:
19
+ `read_file({ body: { branch: "{{defaultBranch}}", path: "{{kbDirName}}/{{knowledgeBaseDir}}/Overview.md" } })`.
20
+ - **Copy each tool's `Call:` line.** It is generated from the tool's own
21
+ schema and shows the shape that tool takes, with every required argument;
22
+ optional ones are in the schema. A call with a missing or unknown argument
23
+ is refused, and the refusal shows the tool's interface.
24
+ - **Pass `sessionId` only where a tool lists it.** Over MCP, call
25
+ `start_session` once and pass its id to the tools whose arguments include
26
+ `sessionId`. Other tools refuse it.
27
+ - **`grep` takes RE2-style regular expressions** (ripgrep): no look-around
28
+ and no backreferences.
29
+ - **Paths sit under `{{kbDirName}}/`**, as in
30
+ `{{kbDirName}}/{{knowledgeBaseDir}}/Overview.md`. A path without that prefix
31
+ is placed under it.
32
+
33
+ ### What is live, and what is only on a draft
34
+
35
+ Work on a draft is visible to you, and to anyone who opens that draft in the
36
+ app: its change request, once you open one, shows every changed file.
37
+ **Skills and tools go live only once they are on `{{defaultBranch}}`**,
38
+ merged through a change request or written there directly by someone allowed
39
+ to. Until then the app's skills page, `list_skills` without `branch` and the
40
+ tool list do not show them, and "doesn't exist" means "not merged yet". To see
41
+ a skill on a draft, pass the draft as `branch` to `list_skills` or
42
+ `get_skill`.
43
+
44
+ ### Which section answers what
45
+
46
+ | Question | Section |
47
+ |---|---|
48
+ | What does my agent see when it connects, and how does it find the rest? | `how-agents-find-things` |
49
+ | How is this like Git, and how is it not? Why can't I delete this? | `for-git-users` |
50
+ | What is a plugin, a skill, a tool, a secret, a role, a group? | `glossary` |
51
+ | What do the platform's folders hold? | `directory-structure` |
52
+ | Where does a new file go? How do I lay out a team's first project? | `where-a-new-file-goes` |
53
+ | What may the file tools do: content kinds, write modes, moves, deletes? | `working-with-files` |
54
+ | Who may read or change what: roles, groups, `access.md`? | `access-control` |
55
+ | How do I propose, sync or delete a draft, or settle a conflict? | `drafts-and-change-requests` |
56
+ | How do I write a skill, or one for people who are not technical? | `skills` |
57
+ | When can I use a tool, and what does it need set up? | `tools` |
58
+ | How do I add a tool: `.tool` files, `mcp.json`, sign-ins? | `tool-manuals` |
59
+ | How do I build an interactive HTML page? | `html-views` |
60
+ | How are pages named, linked and sourced? | `conventions` |
61
+ | The knowledge base is empty: what now? | `new-knowledge-base` |
62
+
63
+ A deployment may add sections of its own: `sections` in this answer lists
64
+ every one. `get_agent_guide({ body: { section: "all" } })` returns the whole
65
+ guide.