@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
@@ -0,0 +1,109 @@
1
+ <!-- Synced from acryl:docs/cordisplugins/development-canvas-plugin.md @ 7968b4ff5d. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Development Canvas as a standalone Cordis plugin
4
+
5
+ Development Canvas follows the same law as the rest of ACRYL: **everything is a
6
+ plugin**. It is not a Desktop subpath, a Desktop child plugin, or unconditional
7
+ logic inside the Electron bootstrap.
8
+
9
+ **Provenance note**: the package has since been extracted out of this
10
+ workspace entirely (`acryldev/acryl-development-canvas` on GitHub, published
11
+ to npm) and is no longer a pnpm workspace member here - Desktop no longer
12
+ force-loads it by default. It is a Market-install-only plugin, same as any
13
+ third-party bundle. The design and Fiber-ownership description below still
14
+ holds; the `pnpm --filter acryl-development-canvas` commands referenced
15
+ further down only work from a checkout of that separate repo.
16
+
17
+ ## Package and composition
18
+
19
+ Canvas owns the independent `acryl-development-canvas` PNPM workspace and
20
+ package. Its bundle patch contributes one stable Loader row:
21
+
22
+ ```yaml
23
+ - id: acryl-development-canvas
24
+ name: acryl-development-canvas
25
+ ```
26
+
27
+ The package root is the Host plugin. The package also declares `dsh.client` and
28
+ exports `./client`, so the DSH Client module graph derives the browser plugin
29
+ from the same enabled Loader entry.
30
+
31
+ A profile patch can disable the whole capability without editing either
32
+ package:
33
+
34
+ ```yaml
35
+ - id: acryl-development-canvas
36
+ disabled: true
37
+ ```
38
+
39
+ ## Host Fiber
40
+
41
+ `acryl-development-canvas/src/index.ts` hard-injects `webServer`. One
42
+ `ctx.effect()` owns the private PTY registry and all same-origin routes.
43
+
44
+ Activation is transactional. If any route registration fails, every earlier
45
+ registration is removed before the error escapes. Normal disposal removes
46
+ routes first and then awaits all PTY processes and subscriptions reaching
47
+ quiescence.
48
+
49
+ The PTY registry stays an internal module rather than becoming a Service. No
50
+ neighboring plugin consumes it, so exposing it would create a shallow,
51
+ hypothetical seam.
52
+
53
+ ## Client Fiber and Desktop seam
54
+
55
+ Desktop owns only the advanced frame. That frame declares the single/root
56
+ `desktop.main` slot and contributes the upstream conversation at priority 100.
57
+
58
+ The independent Canvas Client plugin uses:
59
+
60
+ ```ts
61
+ export const inject = ['slots']
62
+
63
+ ctx.slots.inject('desktop.main', () => {
64
+ // register Canvas at priority 0
65
+ // return cleanup for the slot, styles, and PTY client owner
66
+ })
67
+ ```
68
+
69
+ Canvas therefore wins while its Client Fiber and the slot declaration are both
70
+ live. Removing Canvas unregisters its priority-0 entry, and the Desktop
71
+ conversation fallback becomes visible automatically. There is no status route,
72
+ polling timer, global presence store, or React import from Desktop to Canvas.
73
+
74
+ The declaration effect owns a `CanvasPtyClient`. It tracks every Host session
75
+ opened by that Client activation. Disposal closes all tracked sessions and also
76
+ closes a late session whose asynchronous start settles during teardown.
77
+
78
+ ## Current functional scope
79
+
80
+ One active tab fills the main content area. `+` opens terminal/agent, file, or
81
+ browser tabs. Terminal and agent tabs use `node-pty` with xterm.js rendering,
82
+ byte input, ANSI/alternate-screen support, and resize propagation.
83
+
84
+ The hardcoded coding-agent command list remains transitional transport R&D. It
85
+ must not become room identity, relay, resume, or orchestration. Those concerns
86
+ will use the later `acrAgentControl` capability.
87
+
88
+ File tabs remain an in-memory editor. Browser tabs remain sandboxed HTTP(S)
89
+ iframes. Neither limitation belongs in the Desktop shell.
90
+
91
+ ## Lifecycle verification
92
+
93
+ The standalone package tests cover:
94
+
95
+ - Host plugin name and `inject` contract;
96
+ - rollback after partial route activation;
97
+ - route and process cleanup;
98
+ - real TTY allocation, byte input, and resize;
99
+ - Client-owned session cleanup, including late start settlement;
100
+ - Canvas priority replacing and then restoring the conversation fallback;
101
+ - tab state behavior.
102
+
103
+ Run:
104
+
105
+ ```sh
106
+ corepack pnpm --filter acryl-development-canvas run check
107
+ corepack pnpm --filter acryl-desktop run verify:loader
108
+ corepack pnpm --filter acryl-desktop run verify:profile
109
+ ```
@@ -0,0 +1,517 @@
1
+ <!-- Synced from acryl:docs/cordisplugins/hello-world-plugin-guide.md @ 043fa47bf8. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Hello World: a Cordis plugin for this DSH Desktop repository
4
+
5
+ > **Status:** R&D learning fixture and coding-agent onboarding material. This
6
+ > is not an ACRYL product feature or milestone.
7
+
8
+ This guide is the smallest practical path from one JavaScript module to a
9
+ profile-installed DSH plugin. It targets the versions pinned by this checkout:
10
+ DSH Desktop `2.0.2` and `@deepseek-ai/cordis` `4.0.1` (see the
11
+ [Desktop package manifest](../../acryl-desktop/package.json)). The pinned
12
+ DeepSeek Harness source is the authority when an ecosystem tutorial disagrees
13
+ with this guide.
14
+
15
+ That distinction matters: Harness vendors and locally hardens Cordis, and
16
+ renames its packages into the `@deepseek-ai/*` scope. Do not mechanically copy
17
+ examples that import `cordis`, import `@cordisjs/*`, or use an older `ctx.use`
18
+ API. The fork provenance and local modifications are recorded in the pinned
19
+ [vendor manifest](../../deepseek-harness/vendor/README.md); this checkout is at
20
+ [Harness source commit `b150a551b8d4`](https://github.com/deepseek-ai/deepseek-harness/tree/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e).
21
+
22
+ ## The model in one minute
23
+
24
+ A **plugin** is a lifecycle-managed module. In the common module form it
25
+ exports `apply(ctx, config?)`; the Loader calls `apply` when the plugin's hard
26
+ dependencies are available. A **bundle** is the installable npm package that
27
+ ships one configuration patch which inserts that plugin into a DSH
28
+ composition. A **profile** is the user's runnable, ordered list of bundles plus
29
+ its own final patch.
30
+
31
+ For an ordinary installable third-party plugin, these are separate things:
32
+
33
+ ```text
34
+ profile
35
+ -> lists bundle package in dsh.profile.bundles
36
+ -> bundle declares dsh.bundle.patch
37
+ -> cordis.patch.yml inserts a Loader row
38
+ -> Loader imports the plugin module
39
+ -> Cordis calls apply(ctx)
40
+ ```
41
+
42
+ Desktop uses the same bundle and Loader contracts, but its launcher inserts the
43
+ Desktop-owned layer into each generation instead of persisting that package in
44
+ the user's bundle list. The three registration paths below must not be mixed.
45
+
46
+ ## Path 1: one-off source overlay for learning
47
+
48
+ The [current official first-plugin tutorial](https://deepseek-harness.github.io/deepseek-harness/en/develop/basic/)
49
+ creates a TypeScript source module and a separate overlay file:
50
+
51
+ ```yaml
52
+ # scratch-plugin/cordis.yml
53
+ - insert:
54
+ - id: hello-world
55
+ name: '/absolute/path/to/acryl/scratch-plugin/src/my-plugin.ts'
56
+ ```
57
+
58
+ From the pinned `deepseek-harness/` source workspace, the tutorial launches the
59
+ Web profile with:
60
+
61
+ ```sh
62
+ corepack pnpm dsh web --patch /absolute/path/to/acryl/scratch-plugin/cordis.yml
63
+ ```
64
+
65
+ This is an ephemeral development overlay. It does not create a package, does
66
+ not add a dependency to a profile, and does not edit
67
+ `dsh.profile.bundles`. The module path must be absolute: the patch file's
68
+ location does not change the profile directory from which Loader module names
69
+ resolve. The pinned source says the same in the
70
+ [first Harness plugin walkthrough](../../deepseek-harness/docs/user/develop/basic/index.md).
71
+
72
+ Use this path to prove `apply(ctx)` runs. Use Path 2 when the plugin should be
73
+ installed, removed, updated, or shared.
74
+
75
+ ## Path 2: ordinary third-party bundle and profile registration
76
+
77
+ Use plain ESM JavaScript for the first exercise. It avoids a build step and
78
+ makes the actual runtime contract visible.
79
+
80
+ ```text
81
+ dsh-hello-world/
82
+ ├── package.json
83
+ ├── index.js
84
+ └── cordis.patch.yml
85
+ ```
86
+
87
+ `package.json`:
88
+
89
+ ```json
90
+ {
91
+ "name": "dsh-hello-world",
92
+ "version": "0.1.0",
93
+ "private": true,
94
+ "type": "module",
95
+ "main": "./index.js",
96
+ "exports": "./index.js",
97
+ "files": ["index.js", "cordis.patch.yml"],
98
+ "dsh": {
99
+ "bundle": {
100
+ "patch": "./cordis.patch.yml"
101
+ }
102
+ }
103
+ }
104
+ ```
105
+
106
+ `index.js`:
107
+
108
+ ```js
109
+ export const name = 'hello-world'
110
+
111
+ export function apply(ctx) {
112
+ ctx.logger.info('[hello-world] Hello from Cordis!')
113
+ }
114
+ ```
115
+
116
+ `cordis.patch.yml`:
117
+
118
+ ```yaml
119
+ - insert:
120
+ - id: hello-world
121
+ name: dsh-hello-world
122
+ ```
123
+
124
+ That is a complete Host plugin bundle. `name` in `index.js` is optional
125
+ diagnostic metadata. The row's `name` is the package specifier that the Loader
126
+ imports. Keep the row `id` stable and distinctive so later patches and HMR can
127
+ identify it. The exact three-file shape is also the one taught by the pinned
128
+ [DSH publishing tutorial](../../deepseek-harness/docs/user/develop/basic/publish.md).
129
+
130
+ Do not omit `dsh.bundle.patch`. A package without that declaration can be
131
+ installed as a plain dependency, but `dsh plugin` will not add it as an active
132
+ profile layer. Also ship the referenced patch in `files`; a manifest that
133
+ points at a file excluded from the tarball is not a usable bundle.
134
+
135
+ ### Run it in the current Desktop setup
136
+
137
+ The outer repository is a Yarn 4 workspace; the pinned
138
+ `deepseek-harness/` checkout remains its own pnpm workspace. From the repository
139
+ root, prepare the supported toolchains and build Desktop with the root scripts:
140
+
141
+ ```sh
142
+ corepack pnpm install --frozen-lockfile
143
+ corepack pnpm upstream:install
144
+ corepack pnpm upstream:build
145
+ corepack pnpm build
146
+ ```
147
+
148
+ Start the graphical application only when you intend to open it:
149
+
150
+ ```sh
151
+ corepack pnpm dev
152
+ ```
153
+
154
+ In DSH Desktop, choose **Open DSH Terminal**. That terminal supplies the pinned
155
+ `dsh`, `pnpm`, and Node shims and defaults bare plugin commands to the active
156
+ profile. From the directory containing `dsh-hello-world/`, run:
157
+
158
+ ```sh
159
+ dsh plugin add ./dsh-hello-world
160
+ dsh --dump-config
161
+ ```
162
+
163
+ The dump should contain the `dsh-hello-world` layer and the `hello-world` row.
164
+ Restart Desktop after adding, removing, or updating a bundle; bundle membership
165
+ is fixed for a running generation. Then inspect the Desktop log for
166
+ `[hello-world] Hello from Cordis!`. Remove the exercise with:
167
+
168
+ ```sh
169
+ dsh plugin remove dsh-hello-world
170
+ ```
171
+
172
+ An explicit profile is equivalent when using an ordinary DSH terminal:
173
+
174
+ ```sh
175
+ dsh plugin --profile desktop add ./dsh-hello-world
176
+ dsh --profile desktop --dump-config
177
+ dsh plugin --profile desktop remove dsh-hello-world
178
+ ```
179
+
180
+ The product command deliberately forwards package work to pnpm in the selected
181
+ profile and reconciles `dsh.profile.bundles`; do not replace it with `pnpm add`
182
+ in the outer PNPM workspace. Relative `file:`/`link:` paths are anchored to the
183
+ directory in which `dsh plugin` was invoked. The implementation is documented
184
+ in the pinned [CLI reference](../../deepseek-harness/apps/cli/reference/README.md)
185
+ and [plugin command source](../../deepseek-harness/apps/cli/src/plugin.ts).
186
+
187
+ For a headless repository confidence check, run the existing complete profile
188
+ Loader smoke (it uses a real profile-local third-party package fixture and does
189
+ not open Electron):
190
+
191
+ ```sh
192
+ corepack pnpm --filter acryl-desktop run build
193
+ corepack pnpm --filter acryl-desktop run verify:profile
194
+ ```
195
+
196
+ That smoke validates the current Desktop composition and public Host services;
197
+ it does not replace a focused test for the behavior of your own plugin. See the
198
+ [fixture](../../acryl-desktop/tests/fixtures/desktop-host-services-smoke-plugin/index.js)
199
+ and [smoke runner](../../acryl-desktop/scripts/verify-profile-boot.mjs).
200
+
201
+ ## Path 3: ACRYL Desktop's built-in registration
202
+
203
+ This repository's Desktop shell is not discovered through a special Electron
204
+ plugin registry. It is registered through normal DSH package and Cordis
205
+ surfaces:
206
+
207
+ 1. The package export `acryl-desktop` maps to `lib/index.js`, whose source
208
+ is [src/index.ts](../../acryl-desktop/src/index.ts) and exports the Host
209
+ plugin's `name`, `inject`, schema, and `apply(ctx, config)`.
210
+ 2. The package manifest declares
211
+ `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` and ships the
212
+ patch; see [package.json](../../acryl-desktop/package.json).
213
+ 3. [cordis.patch.yml](../../acryl-desktop/cordis.patch.yml) inserts the
214
+ `desktop-shell` row with `name: acryl-desktop`, plus the Desktop-owned
215
+ Hello World, terminal, development-canvas, diagnostics, notification, pnpm,
216
+ profile, and update rows through exported package subpaths. The learning
217
+ proof is implemented by
218
+ [src/hello-world.ts](../../acryl-desktop/src/hello-world.ts), exported
219
+ as `acryl-desktop/hello-world`, and registered under the stable
220
+ `desktop-hello-world` row.
221
+ 4. During profile preparation, the launcher reads that patch and inserts it
222
+ immediately after `@deepseek-ai/dsh-web-app`; it does not persist the
223
+ Desktop package into the selected profile's bundle list. See the exact
224
+ composition in [profile.ts](../../acryl-desktop/src/profile.ts).
225
+
226
+ The Host row is part of both compatibility and advanced generations. The
227
+ package also declares an ordinary Web Client face exported at `./client`.
228
+ Its [Client entry](../../acryl-desktop/src/client/index.ts) registers the
229
+ shared Desktop contributions in both modes and mounts the Desktop-owned layout
230
+ and root presentation only when `environment.mode === 'advanced'`. Thus mode
231
+ changes presentation composition, not the Cordis plugin contract.
232
+
233
+ Electron changes the **launch path**: it selects a profile, provides
234
+ generation-scoped native services, boots the Host root, and loads the ordinary
235
+ loopback Web surface in a sandboxed BrowserWindow. It does not change how a
236
+ plugin declares `apply`, config, `inject`, services, effects, package exports,
237
+ or Loader rows. Third-party Host plugins and Web Client modules therefore keep
238
+ using standard DSH contracts in both modes. The repository
239
+ [Desktop architecture](../architecture.md) and
240
+ [package architecture](../../acryl-desktop/README.md) own this boundary.
241
+
242
+ ### Compatibility requirements for a future ACRYL rename
243
+
244
+ A future product/package rename should treat the DSH composition format as a
245
+ compatibility contract, not as branding to rewrite freely. Retain:
246
+
247
+ - the `dsh.bundle.patch` manifest shape and a shipped patch file;
248
+ - loadable package exports for every module specifier named by patch rows;
249
+ - coherent `dsh.client` metadata and a loadable `./client` export for the
250
+ browser face;
251
+ - stable Loader row ids, because user and home patches address those ids;
252
+ - `dsh.profile.bundles`, profile-local dependencies, layer order, and ordinary
253
+ `dsh plugin` reconciliation semantics;
254
+ - migration or compatibility aliases for persisted old package names and patch
255
+ module specifiers if the npm identity changes;
256
+ - compatibility exports for the public `profile-service` and `pnpm` contract
257
+ paths while third-party consumers migrate.
258
+
259
+ In other words, ACRYL may rename the application and its package, but an existing
260
+ profile must still resolve its recorded bundle identities and every exported
261
+ specifier referenced by the effective patch-or be migrated explicitly before
262
+ boot. Do not invent an ACRYL-only plugin manifest. The pinned
263
+ [profile implementation](../../deepseek-harness/packages/boot/app-boot/src/profile.ts),
264
+ [plugin command](../../deepseek-harness/apps/cli/src/plugin.ts), and
265
+ [publishing tutorial](../../deepseek-harness/docs/user/develop/basic/publish.md)
266
+ define the compatibility surface to preserve.
267
+
268
+ ## Lifecycle rule: every effect must reverse
269
+
270
+ The Hello World module acquires no external resource, so it needs no disposer.
271
+ As soon as a plugin starts a timer, watcher, socket, subprocess, external
272
+ subscription, or native registration, acquire it inside `ctx.effect()` and
273
+ return its cleanup:
274
+
275
+ ```js
276
+ export const name = 'hello-heartbeat'
277
+
278
+ export function apply(ctx) {
279
+ ctx.effect(() => {
280
+ const timer = setInterval(() => {
281
+ ctx.logger.info('[hello-heartbeat] still active')
282
+ }, 5_000)
283
+
284
+ return () => clearInterval(timer)
285
+ }, 'hello-world heartbeat')
286
+ }
287
+ ```
288
+
289
+ Cordis-owned registrations such as `ctx.on(...)`, child plugins created with
290
+ `ctx.plugin(...)`, and services are already effects. Raw platform resources are
291
+ not. A plugin can unload during HMR, a patch edit, generation shutdown, or loss
292
+ of a required service; cleanup must work in every case. If teardown operations
293
+ must be ordered, keep them in one async disposer and await them in sequence,
294
+ because separate async disposers may run concurrently. The pinned
295
+ [lifecycle tutorial](../../deepseek-harness/docs/cordis-tutorial/02-lifecycle-and-effects.md)
296
+ defines these semantics.
297
+
298
+ ## Services and `inject` are different concepts
299
+
300
+ A **service** is a named callable capability supplied by a provider. `inject`
301
+ is a consumer's declaration that one or more services are hard dependencies.
302
+ It is not a startup-order hint.
303
+
304
+ ```js
305
+ // Consumer plugin
306
+ export const name = 'hello-consumer'
307
+ export const inject = ['greeter']
308
+
309
+ export function apply(ctx) {
310
+ ctx.logger.info(ctx.greeter.greet('ACRYL'))
311
+ }
312
+ ```
313
+
314
+ Cordis keeps this consumer `PENDING` until a provider registers `greeter`.
315
+ Inside `apply`, `ctx.greeter` is therefore available. If the provider later
316
+ unloads, Cordis unloads the consumer and reverses its effects; if the service
317
+ returns, the consumer activates again. Loader row order does not provide this
318
+ guarantee-service availability does. For a capability the plugin can live
319
+ without, omit it from `inject` and probe it at the use site:
320
+
321
+ ```js
322
+ export function apply(ctx) {
323
+ const metrics = ctx.get('metrics')
324
+ metrics?.record('hello_world_loaded', 1)
325
+ }
326
+ ```
327
+
328
+ Use a service when another plugin needs to invoke a stable capability. Use an
329
+ event when other plugins only need to observe or intercept something without a
330
+ direct capability call. Prefer a `Service` subclass when publishing a typed,
331
+ callable API; declaration merging supplies TypeScript safety, while the runtime
332
+ service registration supplies the capability. The complete provider/consumer
333
+ pattern is in the pinned [services tutorial](../../deepseek-harness/docs/cordis-tutorial/03-services.md).
334
+
335
+ Do not access `ctx.someService` without declaring it as a hard injection.
336
+ Cordis's guard may reject undeclared service access. Conversely, do not add an
337
+ optional service to `inject` merely to avoid an `undefined` check: doing so can
338
+ turn an otherwise healthy plugin into a permanently pending one.
339
+
340
+ ## Optional typed configuration
341
+
342
+ The zero-config Hello World is the right first plugin. When deployments need a
343
+ tunable greeting, export a TypeScript `Config` type and a same-named
344
+ Schemastery schema; Cordis validates the row config and fills schema defaults
345
+ before `apply` runs:
346
+
347
+ ```ts
348
+ import type { Context } from '@deepseek-ai/cordis'
349
+ import Schema from '@deepseek-ai/schemastery'
350
+
351
+ export interface Config {
352
+ greeting: string
353
+ }
354
+
355
+ export const Config: Schema<Config> = Schema.object({
356
+ greeting: Schema.string().default('Hello from Cordis!'),
357
+ })
358
+
359
+ export function apply(ctx: Context, config: Config): void {
360
+ ctx.logger.info(`[hello-world] ${config.greeting}`)
361
+ }
362
+ ```
363
+
364
+ ```yaml
365
+ - insert:
366
+ - id: hello-world
367
+ name: dsh-hello-world
368
+ config:
369
+ greeting: Hello from ACRYL!
370
+ ```
371
+
372
+ Do not export a plain object under `Config`; Cordis expects a Standard
373
+ Schema-compatible schema. A TypeScript package must publish built JavaScript
374
+ and declarations. A Git install fetches source, so its `prepare` build requires
375
+ an explicit pnpm `allowBuilds` grant; an npm release or built tarball avoids
376
+ that install-time build. See the pinned
377
+ [configuration guide](../../deepseek-harness/docs/user/develop/basic/config.md)
378
+ and [publishing guide](../../deepseek-harness/docs/user/develop/basic/publish.md).
379
+
380
+ ## `cordis.patch.yml`, bundles, and profile layers
381
+
382
+ For an installed plugin, `cordis.patch.yml` belongs to the **bundle** and the
383
+ bundle's `package.json` points to it through `dsh.bundle.patch`. `dsh plugin`
384
+ then adds the package to the selected profile's ordered
385
+ `dsh.profile.bundles`. The effective DSH configuration applies:
386
+
387
+ 1. bundle patches in profile order;
388
+ 2. the profile's own `cordis.patch.yml`;
389
+ 3. `$DSH_HOME/cordis.patch.yml`;
390
+ 4. explicit `--patch` overlays in command-line order.
391
+
392
+ Later layers win per Loader row. A patch replaces a row's complete `config`
393
+ value rather than deep-merging it, so an override must restate every config key
394
+ that row still needs. In this Desktop, the launcher prepares the chosen Web
395
+ profile, keeps third-party bundle order, inserts the Desktop layer into the
396
+ generation, and boots from an empty include root; the exact implementation is
397
+ in [profile.ts](../../acryl-desktop/src/profile.ts).
398
+
399
+ ## Failure diagnostics
400
+
401
+ ### The plugin prints nothing
402
+
403
+ First run `dsh --dump-config` for the active profile.
404
+
405
+ - No bundle layer: verify `package.json` contains a valid `dsh.bundle.patch`,
406
+ the patch is shipped, and the package appears in the profile's
407
+ `dsh.profile.bundles`. Install through `dsh plugin`, not raw root PNPM.
408
+ - Layer exists but row is absent: check the YAML patch shape and row `id`.
409
+ - Row exists but module is unresolved: check the exact package/path spelling
410
+ and package exports. A resolution error can occur before a console logger is
411
+ observing startup, so “no message” is not proof the module loaded.
412
+ - Row is disabled: inspect later profile, home, and `--patch` layers.
413
+ - Bundle was just added/removed/updated: restart the profile generation.
414
+
415
+ ### The fiber is `PENDING`
416
+
417
+ `PENDING` is a valid lifecycle state: at least one hard injected service is not
418
+ available yet. It is not fixed by moving the row earlier in YAML. Compare every
419
+ name in `inject` with an actual provider in the same service realm. Remove an
420
+ injection only if the capability is truly optional; otherwise mount the correct
421
+ provider. A pending fiber does not keep Node alive, so an otherwise empty
422
+ headless composition can exit successfully without running `apply`.
423
+
424
+ For a focused diagnosis, temporarily add a diagnostic plugin that enumerates
425
+ `ctx.registry`, checks `fiber.state === FiberState.PENDING`, and prints the
426
+ fiber names. The pinned
427
+ [composition/HMR tutorial](../../deepseek-harness/docs/cordis-tutorial/06-composition-and-hmr.md)
428
+ contains a runnable diagnostic. In an agent profile that explicitly composes
429
+ the optional Cordis inspection toolset, use its advertised read-only inspect
430
+ providers; do not assume those tools exist in every shipped profile.
431
+
432
+ ### The fiber is `FAILED`
433
+
434
+ `apply` threw, configuration validation failed, a service name collided, or
435
+ the composed rows are invalid. Read the first cause, not only the later
436
+ dependent `PENDING` symptoms. Common causes are a plain-object `Config`, an
437
+ undeclared `ctx.service` access, duplicate Loader row ids, or two providers
438
+ publishing the same non-isolated service name. Desktop rejects duplicate row
439
+ ids before boot; choose a package-qualified id rather than overwriting another
440
+ plugin accidentally.
441
+
442
+ ### It works once, then duplicates behavior after reload
443
+
444
+ The plugin created process/page state outside `apply`, or acquired an external
445
+ resource without an effect disposer. Move acquisition into `ctx.effect()` and
446
+ make cleanup idempotent. Never retain a Desktop service, BrowserWindow, timer,
447
+ or subprocess handle across a generation restart.
448
+
449
+ ### It works in Desktop but not ordinary DSH-or the reverse
450
+
451
+ The only supported third-party Desktop Host services are `desktopProfiles` and
452
+ `desktopPnpm`, exported by `acryl-desktop/profile-service` and
453
+ `acryl-desktop/pnpm`. A Desktop-only plugin may hard-inject them. A plugin
454
+ that must also run under ordinary DSH should detect `desktopProfiles` with
455
+ `ctx.get(...)` and mount its Desktop adapter inside a nested
456
+ `ctx.inject(['desktopPnpm'], ...)`, while retaining an ordinary DSH fallback.
457
+ Do not infer the Desktop profile from argv, settings, a URL, or `$DSH_HOME`.
458
+ The exact supported boundary and teardown semantics are in the
459
+ [Desktop plugin-service contract](../../acryl-desktop/docs/plugin-services.md)
460
+ and the repository's [plugin-development note](../plugin-development.md).
461
+
462
+ ## Current contracts versus proposals
463
+
464
+ Safe dependencies for a plugin in this checkout are:
465
+
466
+ - the pinned `@deepseek-ai/cordis` plugin, lifecycle, service, injection,
467
+ event, and Loader contracts;
468
+ - DSH package contracts documented by the pinned source;
469
+ - normal `dsh.bundle`, profile, and patch semantics;
470
+ - for Desktop-specific Host code, only `desktopProfiles` and `desktopPnpm` as
471
+ documented above;
472
+ - for browser UI, ordinary DSH Host routes/RPC plus Web Client metadata,
473
+ services, and slots-not Electron APIs or a new renderer IPC system.
474
+
475
+ Do **not** code against the proposed Community Fabric manifest, Host Descriptor,
476
+ capability negotiation, unified event vocabulary, compatibility badge, effect
477
+ ledger, or conformance API. Community Fabric is currently a documentation-only
478
+ RFC with no runtime, SDK, or released schema in this workspace; working plugins
479
+ still use existing DSH/Cordis APIs. See its explicit
480
+ [status statement](../../dsh-community-fabric/README.md).
481
+
482
+ The Community Market is a real Desktop component, but catalog membership is
483
+ discovery metadata-not proof of safety or compatibility. Its current boundary
484
+ and the reviewed dshfind/1024Store adapters are documented in the
485
+ [Market README](../../cordis-plugin-market/README.md). The public
486
+ [dshfind repository](https://github.com/hikariming/dshfind) describes a catalog
487
+ generated from the `dsh-plugin` GitHub topic, while
488
+ [DSH 1024Store](https://github.com/imsai-sh/awesome-deepseek-harness-plugins)
489
+ checks basic repository structure such as `package.json`, `dsh.bundle`, and the
490
+ declared patch path. Its own contribution contract explicitly describes this
491
+ as static validation rather than runtime or security validation
492
+ ([catalog contribution rules](https://github.com/imsai-sh/awesome-deepseek-harness-plugins/blob/90e3f5852663daa116ca310518eb8c01dec56151/CONTRIBUTING.md)).
493
+ Use [dshfind.com](https://dshfind.com/en) and
494
+ [deepseek1024.com](https://deepseek1024.com) to discover candidates, then
495
+ inspect the candidate's source, exact version, lifecycle scripts, bundle
496
+ manifest, patch, dependencies, and compatibility before installing it.
497
+ Directory inclusion is neither a security audit nor a replacement for the
498
+ pinned DSH contracts. In particular, dshfind learning material currently
499
+ contains examples from a different Cordis/API snapshot; treat it as conceptual
500
+ secondary reading and translate every technical detail back to the pinned DSH
501
+ source.
502
+
503
+ ## Primary references used
504
+
505
+ - [Current official first-plugin tutorial](https://deepseek-harness.github.io/deepseek-harness/en/develop/basic/)
506
+ - [Pinned first Harness plugin](../../deepseek-harness/docs/user/develop/basic/index.md)
507
+ - [Pinned package-and-profile tutorial](../../deepseek-harness/docs/user/develop/basic/publish.md)
508
+ - [Pinned Cordis first-plugin tutorial](../../deepseek-harness/docs/cordis-tutorial/01-first-plugin.md)
509
+ - [Pinned lifecycle/effects tutorial](../../deepseek-harness/docs/cordis-tutorial/02-lifecycle-and-effects.md)
510
+ - [Pinned services tutorial](../../deepseek-harness/docs/cordis-tutorial/03-services.md)
511
+ - [Pinned Loader implementation notes](../../deepseek-harness/vendor/loader/README.md)
512
+ - [Repository Cordis architecture specification](../cordis/cordis_spec.md)
513
+ - [Desktop public plugin services](../../acryl-desktop/docs/plugin-services.md)
514
+
515
+ Repository discovery for this guide used direct source reads because the
516
+ codebase knowledge graph was unavailable. No file under the pinned
517
+ `deepseek-harness/` checkout was modified.