@acryldev/plugin-context 0.0.0-stage → 0.1.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 (284) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +12 -2
  3. package/docs/README.md +160 -0
  4. package/docs/delivery/local-live.md +113 -0
  5. package/docs/delivery/marketplace.md +16 -0
  6. package/docs/docs.json +2836 -0
  7. package/docs/extending/agent-preset.md +37 -0
  8. package/docs/extending/chat-command.md +28 -0
  9. package/docs/extending/client-slot.md +135 -0
  10. package/docs/extending/config-schema.md +7 -0
  11. package/docs/extending/cordis-core.md +63 -0
  12. package/docs/extending/desktop-app.md +53 -0
  13. package/docs/extending/desktop-main.md +25 -0
  14. package/docs/extending/event-hook.md +14 -0
  15. package/docs/extending/host-route.md +33 -0
  16. package/docs/extending/llm-adapter.md +38 -0
  17. package/docs/extending/packaging.md +53 -0
  18. package/docs/extending/prompt-contribution.md +9 -0
  19. package/docs/extending/service.md +13 -0
  20. package/docs/extending/skill-provider.md +9 -0
  21. package/docs/extending/state-and-persistence.md +71 -0
  22. package/docs/extending/three-role-capability.md +33 -0
  23. package/docs/extending/tool-plugin.md +24 -0
  24. package/docs/extending/tui-command.md +8 -0
  25. package/docs/extending/tui-components.md +61 -0
  26. package/docs/extending/ui-branding.md +43 -0
  27. package/docs/extending/ui-components.md +56 -0
  28. package/docs/extending/ui-customization.md +41 -0
  29. package/docs/extending/ui-library.md +66 -0
  30. package/docs/extending/ui-theme.md +55 -0
  31. package/docs/extending/workspace-tab.md +50 -0
  32. package/docs/maps/events.md +108 -0
  33. package/docs/maps/mount-points.md +154 -0
  34. package/docs/maps/slot-contracts.md +3376 -0
  35. package/docs/maps/taxonomy.md +306 -0
  36. package/docs/maps/theme-tokens.md +115 -0
  37. package/docs/maps/ui-components.md +26 -0
  38. package/docs/reference/cookbook/adding-a-package.md +174 -0
  39. package/docs/reference/cookbook/adding-a-remote-api.md +199 -0
  40. package/docs/reference/cookbook/adding-a-settings-card.md +74 -0
  41. package/docs/reference/cookbook/adding-a-tool.md +103 -0
  42. package/docs/reference/cookbook/adding-an-llm-adapter.md +45 -0
  43. package/docs/reference/cookbook/extension-cookbook.md +134 -0
  44. package/docs/reference/cordis-api/context.md +366 -0
  45. package/docs/reference/cordis-api/events.md +209 -0
  46. package/docs/reference/cordis-api/fiber.md +377 -0
  47. package/docs/reference/cordis-api/inherited.md +40 -0
  48. package/docs/reference/cordis-api/registry.md +154 -0
  49. package/docs/reference/cordis-api/service.md +104 -0
  50. package/docs/reference/cordis-guides/cordis-usage-cheatsheet.md +167 -0
  51. package/docs/reference/cordis-guides/cordis_system_guide_for_coding_agents.md +4666 -0
  52. package/docs/reference/cordis-guides/development-canvas-plugin.md +109 -0
  53. package/docs/reference/cordis-guides/hello-world-plugin-guide.md +517 -0
  54. package/docs/reference/harness/agent-lifecycle.md +93 -0
  55. package/docs/reference/harness/architecture.md +168 -0
  56. package/docs/reference/harness/capability-seams.md +675 -0
  57. package/docs/reference/harness/config-catalog.md +4523 -0
  58. package/docs/reference/harness/cordis-primer.md +47 -0
  59. package/docs/reference/harness/defensive-patterns.md +35 -0
  60. package/docs/reference/harness/event-producer-consumer.md +111 -0
  61. package/docs/reference/harness/glossary.md +47 -0
  62. package/docs/reference/harness/tool-catalog.md +2721 -0
  63. package/docs/reference/harness/tool-execution-pipeline.md +67 -0
  64. package/docs/reference/subsystems/README.md +75 -0
  65. package/docs/reference/subsystems/agent-team.md +233 -0
  66. package/docs/reference/subsystems/approval.md +172 -0
  67. package/docs/reference/subsystems/attachment.md +363 -0
  68. package/docs/reference/subsystems/boot.md +324 -0
  69. package/docs/reference/subsystems/browser-use.md +69 -0
  70. package/docs/reference/subsystems/client-modules.md +186 -0
  71. package/docs/reference/subsystems/client-resources.md +94 -0
  72. package/docs/reference/subsystems/commands.md +225 -0
  73. package/docs/reference/subsystems/compaction.md +286 -0
  74. package/docs/reference/subsystems/computer-use.md +58 -0
  75. package/docs/reference/subsystems/conversation.md +287 -0
  76. package/docs/reference/subsystems/core.md +1107 -0
  77. package/docs/reference/subsystems/credentials.md +497 -0
  78. package/docs/reference/subsystems/deliverables.md +180 -0
  79. package/docs/reference/subsystems/extensions.md +386 -0
  80. package/docs/reference/subsystems/feedback.md +402 -0
  81. package/docs/reference/subsystems/filesystem.md +532 -0
  82. package/docs/reference/subsystems/goal.md +315 -0
  83. package/docs/reference/subsystems/invariants.md +90 -0
  84. package/docs/reference/subsystems/jobs.md +501 -0
  85. package/docs/reference/subsystems/llm-streaming.md +1131 -0
  86. package/docs/reference/subsystems/lsp.md +204 -0
  87. package/docs/reference/subsystems/mcp.md +141 -0
  88. package/docs/reference/subsystems/office-to-pdf.md +89 -0
  89. package/docs/reference/subsystems/otel.md +46 -0
  90. package/docs/reference/subsystems/permission-presets.md +169 -0
  91. package/docs/reference/subsystems/persistence.md +418 -0
  92. package/docs/reference/subsystems/plan.md +89 -0
  93. package/docs/reference/subsystems/product-telemetry.md +81 -0
  94. package/docs/reference/subsystems/ptc-runtime.md +234 -0
  95. package/docs/reference/subsystems/sandbox.md +223 -0
  96. package/docs/reference/subsystems/schedule.md +545 -0
  97. package/docs/reference/subsystems/scope.md +61 -0
  98. package/docs/reference/subsystems/session-projection.md +358 -0
  99. package/docs/reference/subsystems/session-query.md +511 -0
  100. package/docs/reference/subsystems/session-reference.md +226 -0
  101. package/docs/reference/subsystems/session-telemetry.md +214 -0
  102. package/docs/reference/subsystems/session-title.md +206 -0
  103. package/docs/reference/subsystems/session.md +1300 -0
  104. package/docs/reference/subsystems/settings.md +157 -0
  105. package/docs/reference/subsystems/shell.md +316 -0
  106. package/docs/reference/subsystems/sidebar-right.md +160 -0
  107. package/docs/reference/subsystems/skills.md +354 -0
  108. package/docs/reference/subsystems/slots.md +201 -0
  109. package/docs/reference/subsystems/spill.md +126 -0
  110. package/docs/reference/subsystems/ssh.md +137 -0
  111. package/docs/reference/subsystems/storage.md +262 -0
  112. package/docs/reference/subsystems/subagent.md +762 -0
  113. package/docs/reference/subsystems/subprocess.md +323 -0
  114. package/docs/reference/subsystems/system-prompt.md +226 -0
  115. package/docs/reference/subsystems/terminal.md +186 -0
  116. package/docs/reference/subsystems/todo.md +34 -0
  117. package/docs/reference/subsystems/token-meter.md +108 -0
  118. package/docs/reference/subsystems/tools.md +749 -0
  119. package/docs/reference/subsystems/typert.md +489 -0
  120. package/docs/reference/subsystems/user-questions.md +309 -0
  121. package/docs/reference/subsystems/voice-input.md +166 -0
  122. package/docs/reference/subsystems/web-client.md +102 -0
  123. package/docs/reference/subsystems/web-server.md +228 -0
  124. package/docs/reference/subsystems/web.md +208 -0
  125. package/docs/reference/subsystems/webhook.md +72 -0
  126. package/docs/reference/subsystems/workflow.md +280 -0
  127. package/docs/reference/subsystems/workspace.md +661 -0
  128. package/docs/start-here/blueprints.md +33 -0
  129. package/docs/start-here/this-runtime.md +84 -0
  130. package/docs/start-here/troubleshooting.md +29 -0
  131. package/docs/start-here/trust-and-safety.md +39 -0
  132. package/docs/start-here/verify-before-done.md +46 -0
  133. package/example-plugins/README.md +45 -0
  134. package/example-plugins/packages/agent-preset-reviewer/agent.cordis.yml +18 -0
  135. package/example-plugins/packages/agent-preset-reviewer/preset.yml +3 -0
  136. package/example-plugins/packages/capability-swap-consumer/cordis.patch.yml +3 -0
  137. package/example-plugins/packages/capability-swap-consumer/index.js +14 -0
  138. package/example-plugins/packages/capability-swap-consumer/package.json +25 -0
  139. package/example-plugins/packages/capability-swap-provider-loud/cordis.patch.yml +3 -0
  140. package/example-plugins/packages/capability-swap-provider-loud/index.js +20 -0
  141. package/example-plugins/packages/capability-swap-provider-loud/package.json +25 -0
  142. package/example-plugins/packages/capability-swap-provider-quiet/cordis.patch.yml +3 -0
  143. package/example-plugins/packages/capability-swap-provider-quiet/index.js +20 -0
  144. package/example-plugins/packages/capability-swap-provider-quiet/package.json +25 -0
  145. package/example-plugins/packages/chat-command-basic/cordis.patch.yml +3 -0
  146. package/example-plugins/packages/chat-command-basic/index.js +26 -0
  147. package/example-plugins/packages/chat-command-basic/package.json +25 -0
  148. package/example-plugins/packages/client-chat-message-action/client.js +46 -0
  149. package/example-plugins/packages/client-chat-message-action/cordis.patch.yml +3 -0
  150. package/example-plugins/packages/client-chat-message-action/index.js +9 -0
  151. package/example-plugins/packages/client-chat-message-action/package.json +31 -0
  152. package/example-plugins/packages/client-slot-header-action/client.js +57 -0
  153. package/example-plugins/packages/client-slot-header-action/cordis.patch.yml +3 -0
  154. package/example-plugins/packages/client-slot-header-action/index.js +13 -0
  155. package/example-plugins/packages/client-slot-header-action/package.json +31 -0
  156. package/example-plugins/packages/client-slot-sidebar-tab/client.js +57 -0
  157. package/example-plugins/packages/client-slot-sidebar-tab/cordis.patch.yml +3 -0
  158. package/example-plugins/packages/client-slot-sidebar-tab/index.js +9 -0
  159. package/example-plugins/packages/client-slot-sidebar-tab/package.json +32 -0
  160. package/example-plugins/packages/client-theme-override/client.js +52 -0
  161. package/example-plugins/packages/client-theme-override/cordis.patch.yml +3 -0
  162. package/example-plugins/packages/client-theme-override/index.js +9 -0
  163. package/example-plugins/packages/client-theme-override/package.json +30 -0
  164. package/example-plugins/packages/client-tool-view/client.js +47 -0
  165. package/example-plugins/packages/client-tool-view/cordis.patch.yml +3 -0
  166. package/example-plugins/packages/client-tool-view/index.js +24 -0
  167. package/example-plugins/packages/client-tool-view/package.json +34 -0
  168. package/example-plugins/packages/client-ui-components/client.js +77 -0
  169. package/example-plugins/packages/client-ui-components/cordis.patch.yml +3 -0
  170. package/example-plugins/packages/client-ui-components/index.js +9 -0
  171. package/example-plugins/packages/client-ui-components/package.json +31 -0
  172. package/example-plugins/packages/client-ui-library/client.js +715 -0
  173. package/example-plugins/packages/client-ui-library/cordis.patch.yml +3 -0
  174. package/example-plugins/packages/client-ui-library/index.js +9 -0
  175. package/example-plugins/packages/client-ui-library/package.json +37 -0
  176. package/example-plugins/packages/client-workspace-tab/client.js +72 -0
  177. package/example-plugins/packages/client-workspace-tab/cordis.patch.yml +3 -0
  178. package/example-plugins/packages/client-workspace-tab/index.js +9 -0
  179. package/example-plugins/packages/client-workspace-tab/package.json +30 -0
  180. package/example-plugins/packages/config-schema-basic/cordis.patch.yml +3 -0
  181. package/example-plugins/packages/config-schema-basic/index.js +19 -0
  182. package/example-plugins/packages/config-schema-basic/package.json +25 -0
  183. package/example-plugins/packages/desktop-main-profile-info/cordis.patch.yml +3 -0
  184. package/example-plugins/packages/desktop-main-profile-info/index.js +22 -0
  185. package/example-plugins/packages/desktop-main-profile-info/package.json +25 -0
  186. package/example-plugins/packages/event-hook-basic/cordis.patch.yml +3 -0
  187. package/example-plugins/packages/event-hook-basic/index.js +17 -0
  188. package/example-plugins/packages/event-hook-basic/package.json +22 -0
  189. package/example-plugins/packages/generated-capability-template/cordis.patch.yml +3 -0
  190. package/example-plugins/packages/generated-capability-template/index.js +16 -0
  191. package/example-plugins/packages/generated-capability-template/package.json +42 -0
  192. package/example-plugins/packages/host-route-basic/cordis.patch.yml +3 -0
  193. package/example-plugins/packages/host-route-basic/index.js +20 -0
  194. package/example-plugins/packages/host-route-basic/package.json +29 -0
  195. package/example-plugins/packages/lifecycle-function-basic/cordis.patch.yml +3 -0
  196. package/example-plugins/packages/lifecycle-function-basic/index.js +12 -0
  197. package/example-plugins/packages/lifecycle-function-basic/package.json +15 -0
  198. package/example-plugins/packages/lifecycle-function-hot-shim/cordis.patch.yml +3 -0
  199. package/example-plugins/packages/lifecycle-function-hot-shim/impl.js +5 -0
  200. package/example-plugins/packages/lifecycle-function-hot-shim/index.js +18 -0
  201. package/example-plugins/packages/lifecycle-function-hot-shim/package.json +23 -0
  202. package/example-plugins/packages/lifecycle-hooks-observer/cordis.patch.yml +3 -0
  203. package/example-plugins/packages/lifecycle-hooks-observer/index.js +23 -0
  204. package/example-plugins/packages/lifecycle-hooks-observer/package.json +22 -0
  205. package/example-plugins/packages/llm-adapter-echo/cordis.patch.yml +3 -0
  206. package/example-plugins/packages/llm-adapter-echo/index.js +42 -0
  207. package/example-plugins/packages/llm-adapter-echo/package.json +25 -0
  208. package/example-plugins/packages/prompt-assemble-hook/cordis.patch.yml +3 -0
  209. package/example-plugins/packages/prompt-assemble-hook/index.js +22 -0
  210. package/example-plugins/packages/prompt-assemble-hook/package.json +22 -0
  211. package/example-plugins/packages/prompt-contribution-basic/cordis.patch.yml +3 -0
  212. package/example-plugins/packages/prompt-contribution-basic/index.js +18 -0
  213. package/example-plugins/packages/prompt-contribution-basic/package.json +22 -0
  214. package/example-plugins/packages/service-consumer-greeter/cordis.patch.yml +3 -0
  215. package/example-plugins/packages/service-consumer-greeter/index.js +14 -0
  216. package/example-plugins/packages/service-consumer-greeter/package.json +22 -0
  217. package/example-plugins/packages/service-provider-greeter/cordis.patch.yml +3 -0
  218. package/example-plugins/packages/service-provider-greeter/index.js +22 -0
  219. package/example-plugins/packages/service-provider-greeter/package.json +25 -0
  220. package/example-plugins/packages/settings-section-basic/cordis.patch.yml +3 -0
  221. package/example-plugins/packages/settings-section-basic/index.js +34 -0
  222. package/example-plugins/packages/settings-section-basic/package.json +26 -0
  223. package/example-plugins/packages/skill-provider-basic/cordis.patch.yml +3 -0
  224. package/example-plugins/packages/skill-provider-basic/index.js +31 -0
  225. package/example-plugins/packages/skill-provider-basic/package.json +22 -0
  226. package/example-plugins/packages/state-host-store/client.js +57 -0
  227. package/example-plugins/packages/state-host-store/cordis.patch.yml +3 -0
  228. package/example-plugins/packages/state-host-store/index.js +90 -0
  229. package/example-plugins/packages/state-host-store/package.json +31 -0
  230. package/example-plugins/packages/state-workspace-file/cordis.patch.yml +3 -0
  231. package/example-plugins/packages/state-workspace-file/index.js +52 -0
  232. package/example-plugins/packages/state-workspace-file/package.json +25 -0
  233. package/example-plugins/packages/tool-basic/cordis.patch.yml +3 -0
  234. package/example-plugins/packages/tool-basic/index.js +25 -0
  235. package/example-plugins/packages/tool-basic/package.json +25 -0
  236. package/example-plugins/packages/tool-policy-hook/cordis.patch.yml +3 -0
  237. package/example-plugins/packages/tool-policy-hook/index.js +28 -0
  238. package/example-plugins/packages/tool-policy-hook/package.json +25 -0
  239. package/example-plugins/packages/tui-command-basic/cordis.patch.yml +3 -0
  240. package/example-plugins/packages/tui-command-basic/index.js +24 -0
  241. package/example-plugins/packages/tui-command-basic/package.json +22 -0
  242. package/example-plugins/packages/tui-overlay-themed/cordis.patch.yml +3 -0
  243. package/example-plugins/packages/tui-overlay-themed/index.js +65 -0
  244. package/example-plugins/packages/tui-overlay-themed/package.json +25 -0
  245. package/example-plugins/packages/tui-ui-library/cordis.patch.yml +3 -0
  246. package/example-plugins/packages/tui-ui-library/index.js +73 -0
  247. package/example-plugins/packages/tui-ui-library/package.json +29 -0
  248. package/example-plugins/packages/web-page-branding/cordis.patch.yml +3 -0
  249. package/example-plugins/packages/web-page-branding/index.js +31 -0
  250. package/example-plugins/packages/web-page-branding/package.json +22 -0
  251. package/example-plugins/scenarios.json +11 -0
  252. package/index.js +384 -0
  253. package/lib/blend-apply.js +107 -0
  254. package/lib/blend-capture.js +249 -0
  255. package/lib/blend-ledger.js +76 -0
  256. package/lib/contract.js +5 -0
  257. package/lib/install.js +516 -0
  258. package/lib/lookup.js +67 -0
  259. package/lib/manifest.js +56 -0
  260. package/lib/pack-root.js +22 -0
  261. package/lib/provenance.js +110 -0
  262. package/lib/publish.js +64 -0
  263. package/lib/reconcile.js +83 -0
  264. package/lib/router.js +55 -0
  265. package/lib/scopes.js +82 -0
  266. package/lib/skills.js +54 -0
  267. package/lib/stage.js +157 -0
  268. package/lib/verify.js +77 -0
  269. package/package.json +58 -3
  270. package/scripts/lib/indexes.mjs +45 -0
  271. package/scripts/lib/manifest.mjs +127 -0
  272. package/scripts/lib/maps.mjs +482 -0
  273. package/skills/acryl-add-provider-or-capability/SKILL.md +12 -0
  274. package/skills/acryl-add-ui/SKILL.md +18 -0
  275. package/skills/acryl-build-plugin/SKILL.md +21 -0
  276. package/skills/acryl-change-plugin/SKILL.md +16 -0
  277. package/skills/acryl-desktop-shell/SKILL.md +12 -0
  278. package/skills/acryl-diagnose-plugin/SKILL.md +10 -0
  279. package/skills/acryl-fix-plugin/SKILL.md +12 -0
  280. package/skills/acryl-improve-ui/SKILL.md +10 -0
  281. package/skills/acryl-remove-plugin/SKILL.md +11 -0
  282. package/skills/acryl-restyle-ui/SKILL.md +14 -0
  283. package/skills/acryl-share-plugin/SKILL.md +23 -0
  284. package/skills/acryl-tui-ui/SKILL.md +12 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 acrylblends
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,13 @@
1
- # Temporary Holding Version
1
+ # @acryldev/plugin-context
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Extension Context Pack: routed docs, verified examples and authoring skills that let the ACRYL agent write its own plugins (spec 037).
4
+
5
+ ## Install
6
+
7
+ ```sh
8
+ npm install @acryldev/plugin-context
9
+ ```
10
+
11
+ ## Source and license
12
+
13
+ Part of [ACRYL](https://github.com/acryldev/acryl): [`plugins/plugin-context`](https://github.com/acryldev/acryl/tree/main/plugins/plugin-context). MIT license.
package/docs/README.md ADDED
@@ -0,0 +1,160 @@
1
+ # ACRYL plugin docs
2
+
3
+ <!-- Generated from docs.json by scripts/build-manifest.mjs. Do not edit here. -->
4
+
5
+ Read the file for your topic BEFORE implementing. Read it completely, follow its
6
+ cross-references and the example it names. Do not guess from memory of a similar
7
+ plugin. Verified working examples: `../example-plugins/README.md`.
8
+
9
+ ## Start here
10
+
11
+ | Doc | Read it when | Surfaces | Applies |
12
+ | --- | --- | --- | --- |
13
+ | [This runtime: how ACRYL plugins are built, loaded and delivered](start-here/this-runtime.md) | Always first: the layers, the plugin and package contracts, and the two delivery paths. | tui web desktop | all |
14
+ | [Blueprints, Blends and the blank canvas](start-here/blueprints.md) | When the instance may be the blank canvas, when the user wants the product branded as their own, or when capturing what was grown as a Blend. | tui web desktop | all |
15
+ | [Verify before you say it works](start-here/verify-before-done.md) | Before claiming a plugin works, stating a live fiber state, or delivering a package. | tui web desktop | all |
16
+ | [Troubleshooting](start-here/troubleshooting.md) | A plugin is PENDING, FAILED, invisible or running stale code: symptom table and where to look. | tui web desktop | all |
17
+ | [Trust and safety: plugins run with the user's permissions](start-here/trust-and-safety.md) | Before writing or installing any plugin: what it can do, the rules for the agent, and what ACRYL does and does not protect. | tui web desktop | all |
18
+
19
+ ## Extending ACRYL (by plugin type)
20
+
21
+ | Doc | Read it when | Surfaces | Applies |
22
+ | --- | --- | --- | --- |
23
+ | [Changing how ACRYL looks: what, where, how live (all surfaces)](extending/ui-customization.md) | ANY request about colors, fonts, branding, logo, layout, look and feel or restyling: what each surface allows and what needs a rebuild. | tui web desktop | all |
24
+ | [Ready-made UI components: build with the app's own library](extending/ui-components.md) | Before building ANY UI: the themed component library you can require today (Button, Modal, Input, Switch, Tag, ...) and the terminal equivalents. | tui web desktop | all |
25
+ | [ACRYL UI library: build screens from ready components](extending/ui-library.md) | Any Web or Desktop UI that has forms, settings, lists, dialogs or tabs: use @acryldev/ui instead of hand-styling; semantic color roles for your own colors. | web desktop tui | all |
26
+ | [Cordis building blocks and where each is documented](extending/cordis-core.md) | You are unsure which Cordis or harness mechanism to use: the model in ten lines and a table from what you are building to its doc and reference. | tui web desktop | all |
27
+ | [Client slots: add UI to the Web and Desktop app (panel, button, tab, dashboard)](extending/client-slot.md) | The plugin needs any UI in the app: a top-bar button, a panel, a sidebar tab, a board, a dashboard; also keyboard shortcuts and a custom card for a tool call. | web desktop | all |
28
+ | [Workspace tab types: add a new kind of tab (whiteboard, board, viewer)](extending/workspace-tab.md) | The user wants a new kind of tab in the workspace (a whiteboard, a board of their own, a viewer): a plugin registers a tab type that appears in the + menu, the command palette and Settings > Tabs. | web desktop | all |
29
+ | [Tool plugins: give the agent a new capability](extending/tool-plugin.md) | The feature is something the agent should be able to DO (call an API, read a source, run an action). | tui web desktop | all |
30
+ | [Services: provide a capability, consume it, optional dependencies](extending/service.md) | Plugins must share a capability, or a plugin is PENDING on a missing service. | tui web desktop | all |
31
+ | [Events: listen, emit, intercept (waterfall)](extending/event-hook.md) | The feature reacts to, or intercepts, things that happen in the runtime. | tui web desktop | all |
32
+ | [Plugin configuration (Schemastery)](extending/config-schema.md) | The plugin needs validated settings. | tui web desktop | all |
33
+ | [Prompt contributions: add to the agent system prompt](extending/prompt-contribution.md) | The feature changes what the agent is told or how it behaves. | tui web desktop | all |
34
+ | [Skills: on-demand instructions for the agent](extending/skill-provider.md) | The feature is reusable instructions the agent loads only when needed. | tui web desktop | all |
35
+ | [Host routes: an HTTP API for a web or desktop plugin](extending/host-route.md) | A client UI needs a backend endpoint, or state must be shared across devices. | web desktop | all |
36
+ | [State and persistence: where a plugin keeps its data](extending/state-and-persistence.md) | A plugin must remember something: notes, todos, preferences, a cache, anything that should survive a reload or be shared between Web and Desktop. | tui web desktop | all |
37
+ | [Terminal commands: slash commands with an overlay](extending/tui-command.md) | The feature is a terminal (tui) command or overlay. | tui | all |
38
+ | [LLM adapters: connect a new model provider](extending/llm-adapter.md) | Connect a new model provider route: the stream protocol and a working network-free adapter. | tui web desktop | all |
39
+ | [Packaging a plugin, and generated capabilities](extending/packaging.md) | Writing package.json and the patch, sharing the plugin, or recording a generated capability's permissions and provenance. | tui web desktop | all |
40
+ | [Three-role capability: definition, providers, consumers](extending/three-role-capability.md) | Several interchangeable implementations of one capability that consumers must not care about; swapping providers. | tui web desktop | all |
41
+ | [Profile and install services (desktopProfiles, desktopPnpm, livePluginActivation)](extending/desktop-main.md) | A plugin needs the active profile, package operations or live activation of another plugin. | tui web desktop | all |
42
+ | [Agent presets and personas](extending/agent-preset.md) | A different session composition (tools, prompt, skills) or identity, such as a reviewer or a minimal agent. | tui web desktop | all |
43
+ | [Chat slash commands](extending/chat-command.md) | A /command the user types in the chat that runs on the host without the model (reload, export, toggle). | tui web desktop | all |
44
+ | [Theme, colors and fonts (Web and Desktop client theme service)](extending/ui-theme.md) | Change colors, surfaces, accent, fonts or text size of the Web or Desktop app: overrideTokens, register, setFontSize. | web desktop | all |
45
+ | [Branding: logo, name, tab title, favicon, page shell](extending/ui-branding.md) | Rebrand the app: brand slots, the tab or window title, favicon, page background, and what is native or compiled-in. | tui web desktop | all |
46
+ | [The Desktop (Electron) app: structure and what a plugin can or cannot change](extending/desktop-app.md) | Any Desktop request: main process versus renderer, modes, files for window chrome, icon, menu, tray, and what needs a rebuild. | desktop | all |
47
+ | [The terminal UI: pi-tui components, theming, branding](extending/tui-components.md) | Build or restyle terminal UI: the Component contract, built-in components, palette, width safety, and what is compiled into the CLI. | tui | all |
48
+
49
+ ## Delivery
50
+
51
+ | Doc | Read it when | Surfaces | Applies |
52
+ | --- | --- | --- | --- |
53
+ | [Deliver a plugin live: local install, no restart](delivery/local-live.md) | The plugin is written and must become live now; a plugin must be CHANGED, FIXED, IMPROVED or REMOVED; acryl_install_plugin returned an error; or the plugin is PENDING, FAILED or not visible. | tui web desktop | all |
54
+ | [Delivering through the marketplace](delivery/marketplace.md) | The user wants to share or publish a plugin: readiness checks and the human publish step. | tui web desktop | all |
55
+
56
+ ## Maps (generated)
57
+
58
+ | Doc | Read it when | Surfaces | Applies |
59
+ | --- | --- | --- | --- |
60
+ | [Mount points per surface: where UI and host extensions attach (CLI, Web, Desktop)](maps/mount-points.md) | You must decide WHERE something mounts: which slot, terminal overlay, host service or Desktop frame, and which surface supports it. | tui web desktop | all |
61
+ | [Theme tokens: every design token you can override (Web and Desktop)](maps/theme-tokens.md) | You want to change colors, surfaces, borders, buttons or fonts of the Web or Desktop app: the exact token names with light and dark values. | web desktop | all |
62
+ | [UI component libraries available today (web primitives, pi-tui) and the gap](maps/ui-components.md) | You are about to build UI: which ready-made components exist on each surface so you do not hand-style. | tui web desktop | all |
63
+ | [Lifecycle events: where a plugin can hook the agent (prompt, request, stream, session)](maps/events.md) | You want to intercept or observe the agent lifecycle: prompt construction, the provider request, streaming, tool policy, session events. | tui web desktop | all |
64
+ | [Slot contracts: register options, props, taken keys and an example for every client slot](maps/slot-contracts.md) | You fill a client slot that needs more than name, id and order: its exact register options, the props your component gets, and a worked example. | web desktop | all |
65
+ | [Plugin taxonomy: every plugin type and every shipped plugin, per surface](maps/taxonomy.md) | You want the full list of plugin types, which surfaces have them, whether an agent can author one, and real shipped plugins to study. | tui web desktop | all |
66
+
67
+ ## Reference (synced)
68
+
69
+ | Doc | Read it when | Surfaces | Applies |
70
+ | --- | --- | --- | --- |
71
+ | [Harness subsystems: Subsystems](reference/subsystems/README.md) | English \| [中文](README.zh.md) | tui web desktop | partial |
72
+ | [Harness subsystems: Agent Teams](reference/subsystems/agent-team.md) | English \| [中文](agent-team.zh.md) | tui web desktop | partial |
73
+ | [Harness subsystems: User Approval](reference/subsystems/approval.md) | English \| [中文](approval.zh.md) | tui web desktop | partial |
74
+ | [Harness subsystems: Durable Attachments](reference/subsystems/attachment.md) | English \| [中文](attachment.zh.md) | tui web desktop | partial |
75
+ | [Harness subsystems: Profile management](reference/subsystems/boot.md) | English \| [中文](boot.zh.md) | tui web desktop | partial |
76
+ | [Harness subsystems: Browser use](reference/subsystems/browser-use.md) | English \| [中文](browser-use.zh.md) | tui web desktop | partial |
77
+ | [Harness subsystems: Client Modules](reference/subsystems/client-modules.md) | English \| [中文](client-modules.zh.md) | tui web desktop | partial |
78
+ | [Harness subsystems: Client Resources](reference/subsystems/client-resources.md) | English \| [中文](client-resources.zh.md) | tui web desktop | partial |
79
+ | [Harness subsystems: Human Commands](reference/subsystems/commands.md) | English \| [中文](commands.zh.md) | tui web desktop | partial |
80
+ | [Harness subsystems: Compaction](reference/subsystems/compaction.md) | English \| [中文](compaction.zh.md) | tui web desktop | partial |
81
+ | [Harness subsystems: Computer use](reference/subsystems/computer-use.md) | English \| [中文](computer-use.zh.md) | tui web desktop | partial |
82
+ | [Harness subsystems: Conversation assembly](reference/subsystems/conversation.md) | English \| [中文](conversation.zh.md) | tui web desktop | partial |
83
+ | [Harness subsystems: Core](reference/subsystems/core.md) | English \| [中文](core.zh.md) | tui web desktop | partial |
84
+ | [Harness subsystems: User Credentials](reference/subsystems/credentials.md) | English \| [中文](credentials.zh.md) | tui web desktop | partial |
85
+ | [Harness subsystems: Deliverables](reference/subsystems/deliverables.md) | English \| [中文](deliverables.zh.md) | tui web desktop | partial |
86
+ | [Harness subsystems: Extensions](reference/subsystems/extensions.md) | English \| [中文](extensions.zh.md) | tui web desktop | partial |
87
+ | [Harness subsystems: Message Feedback](reference/subsystems/feedback.md) | English \| [中文](feedback.zh.md) | tui web desktop | partial |
88
+ | [Harness subsystems: Filesystem](reference/subsystems/filesystem.md) | English \| [中文](filesystem.zh.md) | tui web desktop | partial |
89
+ | [Harness subsystems: Same-session goals](reference/subsystems/goal.md) | English \| [中文](goal.zh.md) | tui web desktop | partial |
90
+ | [Harness subsystems: Runtime Invariants](reference/subsystems/invariants.md) | English \| [中文](invariants.zh.md) | tui web desktop | partial |
91
+ | [Harness subsystems: Background Job Runtime](reference/subsystems/jobs.md) | English \| [中文](jobs.zh.md) | tui web desktop | partial |
92
+ | [Harness subsystems: LLM Streaming](reference/subsystems/llm-streaming.md) | English \| [中文](llm-streaming.zh.md) | tui web desktop | partial |
93
+ | [Harness subsystems: LSP navigation](reference/subsystems/lsp.md) | English \| [中文](lsp.zh.md) | tui web desktop | partial |
94
+ | [Harness subsystems: MCP](reference/subsystems/mcp.md) | English \| [中文](mcp.zh.md) | tui web desktop | partial |
95
+ | [Harness subsystems: Office to PDF](reference/subsystems/office-to-pdf.md) | English \| [中文](office-to-pdf.zh.md) | tui web desktop | partial |
96
+ | [Harness subsystems: OTel reporting](reference/subsystems/otel.md) | English \| [中文](otel.zh.md) | tui web desktop | partial |
97
+ | [Harness subsystems: Permission Presets](reference/subsystems/permission-presets.md) | English \| [中文](permission-presets.zh.md) | tui web desktop | partial |
98
+ | [Harness subsystems: Session Persistence](reference/subsystems/persistence.md) | English \| [中文](persistence.zh.md) | tui web desktop | partial |
99
+ | [Harness subsystems: Plan Mode](reference/subsystems/plan.md) | English \| [中文](plan.zh.md) | tui web desktop | partial |
100
+ | [Harness subsystems: Product telemetry](reference/subsystems/product-telemetry.md) | English \| [中文](product-telemetry.zh.md) | tui web desktop | partial |
101
+ | [Harness subsystems: PTC runtime](reference/subsystems/ptc-runtime.md) | English \| [中文](ptc-runtime.zh.md) | tui web desktop | partial |
102
+ | [Harness subsystems: Process Sandbox](reference/subsystems/sandbox.md) | English \| [中文](sandbox.zh.md) | tui web desktop | partial |
103
+ | [Harness subsystems: Host-wide Schedule](reference/subsystems/schedule.md) | English \| [中文](schedule.zh.md) | tui web desktop | partial |
104
+ | [Harness subsystems: Scoped Registration](reference/subsystems/scope.md) | English \| [中文](scope.zh.md) | tui web desktop | partial |
105
+ | [Harness subsystems: Session Projections](reference/subsystems/session-projection.md) | English \| [中文](session-projection.zh.md) | tui web desktop | partial |
106
+ | [Harness subsystems: Session Query](reference/subsystems/session-query.md) | English \| [中文](session-query.zh.md) | tui web desktop | partial |
107
+ | [Harness subsystems: Session References](reference/subsystems/session-reference.md) | English \| [中文](session-reference.zh.md) | tui web desktop | partial |
108
+ | [Harness subsystems: SessionTelemetryBackend](reference/subsystems/session-telemetry.md) | English \| [中文](session-telemetry.zh.md) | tui web desktop | partial |
109
+ | [Harness subsystems: Session Titles](reference/subsystems/session-title.md) | English \| [中文](session-title.zh.md) | tui web desktop | partial |
110
+ | [Harness subsystems: Sessions](reference/subsystems/session.md) | English \| [中文](session.zh.md) | tui web desktop | partial |
111
+ | [Harness subsystems: Plugin Configuration Forms](reference/subsystems/settings.md) | English \| [中文](settings.zh.md) | tui web desktop | partial |
112
+ | [Harness subsystems: Shell Executor](reference/subsystems/shell.md) | English \| [中文](shell.zh.md) | tui web desktop | partial |
113
+ | [Harness subsystems: Right Sidebar](reference/subsystems/sidebar-right.md) | English \| [中文](sidebar-right.zh.md) | tui web desktop | partial |
114
+ | [Harness subsystems: Skills](reference/subsystems/skills.md) | English \| [中文](skills.zh.md) | tui web desktop | partial |
115
+ | [Harness subsystems: Web Client Slots](reference/subsystems/slots.md) | English \| [中文](slots.zh.md) | tui web desktop | partial |
116
+ | [Harness subsystems: Spill Storage](reference/subsystems/spill.md) | English \| [中文](spill.zh.md) | tui web desktop | partial |
117
+ | [Harness subsystems: SSH](reference/subsystems/ssh.md) | English \| [中文](ssh.zh.md) | tui web desktop | partial |
118
+ | [Harness subsystems: Storage](reference/subsystems/storage.md) | English \| [中文](storage.zh.md) | tui web desktop | partial |
119
+ | [Harness subsystems: Subagent](reference/subsystems/subagent.md) | English \| [中文](subagent.zh.md) | tui web desktop | partial |
120
+ | [Harness subsystems: Subprocess](reference/subsystems/subprocess.md) | English \| [中文](subprocess.zh.md) | tui web desktop | partial |
121
+ | [Harness subsystems: System Prompt Assembly](reference/subsystems/system-prompt.md) | English \| [中文](system-prompt.zh.md) | tui web desktop | partial |
122
+ | [Harness subsystems: Persistent PTY Sessions](reference/subsystems/terminal.md) | English \| [中文](terminal.zh.md) | tui web desktop | partial |
123
+ | [Harness subsystems: Todo](reference/subsystems/todo.md) | English \| [中文](todo.zh.md) | tui web desktop | partial |
124
+ | [Harness subsystems: Token Meter](reference/subsystems/token-meter.md) | English \| [中文](token-meter.zh.md) | tui web desktop | partial |
125
+ | [Harness subsystems: Tools](reference/subsystems/tools.md) | English \| [中文](tools.zh.md) | tui web desktop | partial |
126
+ | [Harness subsystems: Typert remote calls](reference/subsystems/typert.md) | English \| [中文](typert.zh.md) | tui web desktop | partial |
127
+ | [Harness subsystems: User Interaction](reference/subsystems/user-questions.md) | English \| [中文](user-questions.zh.md) | tui web desktop | partial |
128
+ | [Harness subsystems: Voice input](reference/subsystems/voice-input.md) | English \| [中文](voice-input.zh.md) | tui web desktop | partial |
129
+ | [Harness subsystems: Web Client architecture](reference/subsystems/web-client.md) | English \| [中文](web-client.zh.md) | tui web desktop | partial |
130
+ | [Harness subsystems: HTTP Server](reference/subsystems/web-server.md) | English \| [中文](web-server.zh.md) | tui web desktop | partial |
131
+ | [Harness subsystems: Web Access](reference/subsystems/web.md) | English \| [中文](web.zh.md) | tui web desktop | partial |
132
+ | [Harness subsystems: Webhook runtime](reference/subsystems/webhook.md) | English \| [中文](webhook.zh.md) | tui web desktop | partial |
133
+ | [Harness subsystems: Workflow](reference/subsystems/workflow.md) | English \| [中文](workflow.zh.md) | tui web desktop | partial |
134
+ | [Harness subsystems: Workspaces](reference/subsystems/workspace.md) | English \| [中文](workspace.zh.md) | tui web desktop | partial |
135
+ | [Cordis API: Context](reference/cordis-api/context.md) | Run `pnpm run gen-cordis-catalog` to regenerate. --> | tui web desktop | partial |
136
+ | [Cordis API: Events](reference/cordis-api/events.md) | Run `pnpm run gen-cordis-catalog` to regenerate. --> | tui web desktop | partial |
137
+ | [Cordis API: Fiber](reference/cordis-api/fiber.md) | Run `pnpm run gen-cordis-catalog` to regenerate. --> | tui web desktop | partial |
138
+ | [Cordis API: Inherited Cordis API](reference/cordis-api/inherited.md) | Run `pnpm run gen-cordis-catalog` to regenerate. --> | tui web desktop | partial |
139
+ | [Cordis API: Registry](reference/cordis-api/registry.md) | Run `pnpm run gen-cordis-catalog` to regenerate. --> | tui web desktop | partial |
140
+ | [Cordis API: Service](reference/cordis-api/service.md) | Run `pnpm run gen-cordis-catalog` to regenerate. --> | tui web desktop | partial |
141
+ | [Harness cookbook: Cookbook: adding a workspace package](reference/cookbook/adding-a-package.md) | English \| [中文](adding-a-package.zh.md) | tui web desktop | partial |
142
+ | [Harness cookbook: Cookbook: adding a Remote API](reference/cookbook/adding-a-remote-api.md) | English \| [中文](adding-a-remote-api.zh.md) | tui web desktop | partial |
143
+ | [Harness cookbook: Cookbook: live configuration forms](reference/cookbook/adding-a-settings-card.md) | English \| [中文](adding-a-settings-card.zh.md) | tui web desktop | partial |
144
+ | [Harness cookbook: Tool authoring reference](reference/cookbook/adding-a-tool.md) | English \| [中文](adding-a-tool.zh.md) | tui web desktop | partial |
145
+ | [Harness cookbook: Cookbook: adding an LLM adapter](reference/cookbook/adding-an-llm-adapter.md) | English \| [中文](adding-an-llm-adapter.zh.md) | tui web desktop | partial |
146
+ | [Harness cookbook: Cookbook: extension plugin shapes](reference/cookbook/extension-cookbook.md) | English \| [中文](extension-cookbook.zh.md) | tui web desktop | partial |
147
+ | [Harness architecture: Cordis Primer](reference/harness/cordis-primer.md) | English \| [中文](cordis-primer.zh.md) | tui web desktop | partial |
148
+ | [Harness architecture: Capability Seams And Core Services](reference/harness/capability-seams.md) | Run `pnpm run gen-doc-graphs` to regenerate. --> | tui web desktop | partial |
149
+ | [Harness architecture: Glossary](reference/harness/glossary.md) | English \| [中文](glossary.zh.md) | tui web desktop | partial |
150
+ | [Harness architecture: Defensive patterns](reference/harness/defensive-patterns.md) | English \| [中文](defensive-patterns.zh.md) | tui web desktop | partial |
151
+ | [Harness architecture: Event Producer And Consumer Matrix](reference/harness/event-producer-consumer.md) | Run `pnpm run gen-doc-graphs` to regenerate. --> | tui web desktop | partial |
152
+ | [Harness architecture: Tool Execution Pipeline](reference/harness/tool-execution-pipeline.md) | Run `pnpm run gen-doc-graphs` to regenerate. --> | tui web desktop | partial |
153
+ | [Harness architecture: Agent Turn And Step Lifecycle](reference/harness/agent-lifecycle.md) | Run `pnpm run gen-doc-graphs` to regenerate. --> | tui web desktop | partial |
154
+ | [Harness architecture: DeepSeek Harness Architecture](reference/harness/architecture.md) | English \| [中文](architecture.zh.md) | tui web desktop | partial |
155
+ | [Harness architecture: Plugin Config Catalog](reference/harness/config-catalog.md) | Run `pnpm run gen-config-catalog` to regenerate. --> | tui web desktop | partial |
156
+ | [Harness architecture: Tool Schema Catalog](reference/harness/tool-catalog.md) | Run `pnpm run gen-tool-catalog` to regenerate. --> | tui web desktop | partial |
157
+ | [Cordis guides: Cordis usage cheatsheet (source-validated)](reference/cordis-guides/cordis-usage-cheatsheet.md) | Cordis is a **meta-framework**: it knows nothing about LLMs, agents, tools, sessions, or shell. | tui web desktop | partial |
158
+ | [Cordis guides: Cordis System Guide for Coding Agents](reference/cordis-guides/cordis_system_guide_for_coding_agents.md) | **Path convention:** Unless an ACRYL/root path is written explicitly, paths such | tui web desktop | partial |
159
+ | [Cordis guides: Hello World: a Cordis plugin for this DSH Desktop repository](reference/cordis-guides/hello-world-plugin-guide.md) | This guide is the smallest practical path from one JavaScript module to a | tui web desktop | partial |
160
+ | [Cordis guides: Development Canvas as a standalone Cordis plugin](reference/cordis-guides/development-canvas-plugin.md) | Development Canvas follows the same law as the rest of ACRYL: **everything is a | tui web desktop | partial |
@@ -0,0 +1,113 @@
1
+ # Deliver a plugin live: local install
2
+
3
+ Goal: the user asks for a feature, you write a plugin, it appears without a restart.
4
+
5
+ 1. Write the package in `<the workspace you are working in>/.acryl-plugins/<plugin-name>/` (create it with your normal
6
+ file tools; never inside the pack or the profile). Copy the closest example from `../example-plugins/README.md` and change it.
7
+ Always pass the tool the ABSOLUTE path of that directory.
8
+ 2. Call the **`acryl_install_plugin`** tool with the package directory. It checks the package
9
+ (bundle patch, `exports` including `./package.json`, a client bundle if `dsh.client` is set), runs
10
+ `dsh plugin add file:<dir>`, live-activates it, and **removes it again if activation fails**.
11
+ 3. Read the result. `ok: true` with status `active` means the host part is live. If the result has a
12
+ `next` note (a UI plugin), do not ask for a reload: the UI mounts live in open windows within a second or two (measured on the packaged Desktop and on Web). Only if the user says it is missing, suggest one reload (Web: page; Desktop: window, Cmd/Ctrl+R).
13
+ 4. On an error the result names the stage (`check`, `install`, `activate`) and the real message. Fix that
14
+ cause and call the tool again; the tool already undid a failed install.
15
+
16
+ ## Changing, fixing, improving or removing a plugin
17
+
18
+ 1. Call `acryl_list_plugins` to find the plugin and the directory it was installed from. Edit the files there.
19
+ 2. Call `acryl_install_plugin` with that directory again. It detects the existing plugin, takes it down, re-installs the
20
+ changed files and mounts a fresh instance ("action": "updated").
21
+ 3. **Browser code (`client.js`)**: the new file is served after a page reload. Tell the user to reload.
22
+ 4. **Host code (`index.js` and what it imports)**: updates take effect in the running process AUTOMATICALLY, like pi.dev's reload.
23
+ Node caches modules by URL, so the installer installs a small staged copy: a generated entry wrapper that, on every
24
+ activation, imports the newest versioned copy of your code (`acryl-v-*`), so `index.js` and every file it imports are
25
+ evaluated fresh. The result says `"hostReload": "automatic"`. You do not write or maintain any shim; your source folder
26
+ is never modified. Limits: a change to `inject` (or the `Config` schema) is only fully applied after an app restart (the
27
+ wrapper logs a warning); a class-form `apply` (`export { MyService as apply }`) keeps its first version; a plugin whose
28
+ entry is not a JavaScript ES module (`"type": "module"`) cannot be staged and the result then carries a `warning`. A plugin
29
+ that carries its own hot shim (the legacy pattern in `lifecycle-function-hot-shim`) is installed as written. A plugin whose
30
+ host half is empty (a UI-only plugin) has nothing to reload.
31
+ 5. To delete a plugin call `acryl_remove_plugin` with its package name (UI plugins: tell the user to reload).
32
+
33
+ To improve or change UI, edit `client.js` and update as above. Never edit files inside the profile's `node_modules`
34
+ or the pack; always the source directory that `acryl_list_plugins` reports.
35
+
36
+ ## Marketplace
37
+
38
+ You cannot publish. Publishing is public and irreversible, so it is always a human decision. Prepare the
39
+ package for it (`extending/packaging.md`: `acryl-package` keyword, `acryl` manifest, GitHub `repository`,
40
+ `license`) and tell the user what remains. Installing from the marketplace is the user's normal flow.
41
+
42
+ ## Failure states
43
+
44
+ - `PENDING`: an `inject` names a service nothing provides. Provide it; do not delete the `inject`.
45
+ - `FAILED`: `apply()` threw. Read the real error; do not retry unchanged code.
46
+ - Installed but not live: `exports` lacks `./package.json` (the tool checks this).
47
+ - UI not visible: the page has not been reloaded, or `client.js` failed to load (check the browser console
48
+ for the wrapper `id` and any `import`/JSX in the file).
49
+
50
+ ## Where plugins live: the source folder is the truth
51
+
52
+ An extension is source code first, a running plugin second, and a package only later (this is pi.dev's model, adapted). The install list in the profile is
53
+ derived state: it can be thrown away and rebuilt from the source folders.
54
+
55
+ | Scope | Folder | Who sees it |
56
+ | --- | --- | --- |
57
+ | project | `<workspace>/.acryl-plugins/<name>/` | that project only; commit it to the project's git repository |
58
+ | global | `<ACRYL home>/plugins/<name>/` (`~/.acryl/plugins/`) | every project and every surface (Web, Desktop, CLI) running against this ACRYL home |
59
+
60
+ - Discovery is one level deep: a folder that has a `package.json` is a plugin; folders inside it are just its files.
61
+ - The same folder reached by two spellings (a symlink, `../`) is one plugin. If a project and a global plugin share a package name, the project one
62
+ wins and the global one is reported as SHADOWED.
63
+ - Lifecycle: write source, then `acryl_verify_plugin`, then `acryl_install_plugin` (live), then edit and re-install (update), then `git commit`, and only later publish
64
+ (`start-here/trust-and-safety.md`: publishing is the human's decision). An update never needs the package manager when nothing changed (see below).
65
+ - Three different kinds of storage, never mixed: the plugin's SOURCE (a folder, in git), its ACTIVATION (the profile's install list, derived), and its
66
+ RUNTIME DATA (what it remembers: see `../extending/state-and-persistence.md`). Never store data in the source folder and never serialize a running plugin.
67
+ - Manifest: the `acryl` block of `package.json` (the same block the marketplace reads; there is no second `extension.json`) carries `apiVersion` (an integer; refused when the
68
+ runtime provides an older API) and `permissions` (from a fixed list: `fs.read`, `fs.write`, `net`, `shell`, `secrets`, `ui`). The permissions are shown to the human on the `NEW,
69
+ not installed` line before `/reload new`. They are declarative: declare what the code really does, and expect the human to check; they are not enforced by a sandbox.
70
+ - Startup: when the app starts, installed GLOBAL plugins whose source changed are re-installed automatically (nobody but the user writes to that folder). A changed PROJECT plugin
71
+ is only reported in the log (a `git pull` can change code that would then run with the user's permissions), a missing source is reported, and new folders are never installed
72
+ without `/reload new`.
73
+
74
+ ## Local or from the marketplace: the origin of an install
75
+
76
+ `acryl_list_plugins` tells every installed plugin's origin, derived from what the profile already records (nothing extra is written, so it cannot drift):
77
+
78
+ | Origin | Meaning | What you can do | Reproduced elsewhere from |
79
+ | --- | --- | --- | --- |
80
+ | `local` | built here from a source folder (`file:` install); has `source`, `scope` (project, global, external) and, when staged, the `contentHash` | edit the source, `acryl_install_plugin`, `/reload` | the source folder (its content hash) |
81
+ | `registry` | installed from npm through the marketplace; has the resolved `version` and the lockfile `integrity` digest | nothing: it is managed by the market, do not look for a source folder | name and version |
82
+ | `git`, `linked` | a git URL, or a workspace/link checkout | reported only | the URL / the checkout |
83
+
84
+ The prompt's installed-plugins note lists the local ones with their source and names the marketplace ones as managed, so you do not try to edit them.
85
+
86
+ ## Capturing everything as a Blend
87
+
88
+ `/blend snapshot` (typed by the human) writes the running composition to `<workspace>/.acryl/blend/`: `blend.yaml` (the manifest, valid against the Blends format), `blend.lock.json`
89
+ (exact versions and digests: marketplace plugins by version and integrity, local plugins by sha256) and `plugins/<name>/` (the source of every local plugin, vendored so the
90
+ result is self-contained). Commit it to git to persist and share it. `/blend verify` checks it against its own lock, offline. `/blend apply` (typed by the human, it installs code) re-creates it in another
91
+ workspace or app: it verifies first, places each local plugin in `<workspace>/.acryl-plugins/` (never overwriting a folder that differs), installs marketplace plugins at the locked version and undoes any whose
92
+ integrity does not match the lock, and is safe to repeat. The summary shows the permissions each local module requests.
93
+ `/blend ledger` shows the history: once a workspace has captured a Blend, every install, update and removal of a plugin there (by you or by the agent) appends one line to
94
+ `.acryl/blend/ledger.jsonl` with who did it and the version and content digest. Lines are never rewritten and each carries the hash of the line before it, so `/blend verify` detects an edited or removed line. Plugin data, secrets and ACRYL's own runtime plugins
95
+ are not captured; anything that could not be captured is listed. Design: `specs/036-cordis-ecosystem-and-acryl-blends/blend-instance-design.md`.
96
+
97
+ ## /reload
98
+
99
+ The human types `/reload` in the chat. Source is authoritative, so it makes the installs match their source folders and prints one line per plugin
100
+ with its scope:
101
+
102
+ - source unchanged: `unchanged` (nothing runs, a working plugin is not restarted); source changed: re-installed (same checks and rollback as `acryl_install_plugin`);
103
+ - source folder gone: `STALE` (not a failure); `/reload remove-stale`, typed by the human, removes it. Nothing is removed automatically;
104
+ - a NEW plugin folder in either scope is only listed ("NEW, not installed"): installing it takes `/reload new`, typed by the human, because a plugin runs
105
+ with the user's permissions and a cloned repository can contain one (see `../start-here/trust-and-safety.md`);
106
+ - a global plugin with the same package name as a project one is `SHADOWED` and not loaded.
107
+
108
+ UI changes still need a page (Web) or window (Desktop) reload; the command says so only when something was installed or removed.
109
+
110
+ ## What you see in your context
111
+
112
+ Each turn the prompt carries a live `acryl:installed-plugins` note listing the installed local plugins, whether each is mounted, and its source
113
+ folder, so after an install, update or removal you can see the current state without calling `acryl_list_plugins`.
@@ -0,0 +1,16 @@
1
+ # Delivering through the marketplace
2
+
3
+ Local install (`delivery.local-live`) is the default: the plugin is live immediately. Use the marketplace path
4
+ only when the user wants to share the plugin.
5
+
6
+ 1. Make sure the plugin works locally first (installed, live, verified).
7
+ 2. Add catalog metadata to `package.json`: `"keywords": ["acryl-package"]` (exact), a GitHub `repository`,
8
+ a `license`, a `version`, no `"private": true`, and optionally
9
+ `"acryl": { "schemaVersion": 1, "artifacts": { "plugins": ["./index.js"] } }`.
10
+ 3. Call `acryl_prepare_publish` with the ABSOLUTE package directory. It runs the install checks, the catalog
11
+ checks and `npm pack --dry-run` (no credentials, nothing uploaded) and returns the exact errors to fix, or
12
+ `readyForHumanPublish: true`.
13
+ 4. Tell the user it is ready. **You cannot publish and must not try**: the user runs `npm publish --access public`
14
+ with their own npm login. The marketplace lists it after its next catalog refresh.
15
+
16
+ Never put tokens or credentials in the package or in a chat message.