@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,160 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/sidebar-right.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Right Sidebar
4
+
5
+ English | [中文](sidebar-right.zh.md)
6
+
7
+ The right Sidebar is the Web Client's per-Session docking surface: a column of panes and tabs beside the conversation in which addressed content - a workspace file, a directory tree, the product's own pages - opens, splits, floats, and closes. [`dsh-client-ui-sidebar-right`](../../packages/client/ui-sidebar-right/README.md) owns the surface, the tab-type registry, and the navigation service; [`dsh-client-ui-dockkit`](../../packages/client/ui-dockkit/README.md) is its internal layout engine; [`dsh-client-resources`](../../packages/client/resources/README.md) turns addresses into live values for any component; [`dsh-api-workspace-files`](../../packages/api/workspace-files/README.md) provides both the Host workspace service and the Client `file` resource provider.
8
+
9
+ This page is the reference for the subsystem's contracts: addresses, tab-type registration, the navigation service, the extension slots and their owner props, the resource model, the Workspace Files service, the shipped types, and what is deliberately not built. How the layout engine, the frame, and the surface fit together is in the [Agent Note](../../.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.md); slot mechanics are in the [Slots reference](slots.md).
10
+
11
+ ## Position and ownership
12
+
13
+ One docking surface exists per Session, held in a session-scoped slot store and drawn by `rightbar.session`. The root-scoped `rightbar` controller retains separate seats for the selected Session and background Sessions with initialized `keepMounted` bodies; only the foreground Conversation is visible. Reload restores saved layouts ([state](../../packages/client/ui-sidebar-right/README.md#state)). The surface's every change is one recorded history entry computed by the kit's pure planners; a docked pane never stays empty, and an empty root pane receives the default page selected from registered guide entries.
14
+
15
+ A tab type is two registrations that share the definition's `id`: a static definition in `ctx.sidebarRightTabs` saying which addresses its `kind` opens, and a keyed slot registration supplying its body. The framework injects `useTabInfo()` for live Sidebar, pane and tab information; each type keeps its own state in its slot store. Packages import each other's declarations only as types.
16
+
17
+ | Package | Role |
18
+ |---|---|
19
+ | [`client/ui-sidebar-right`](../../packages/client/ui-sidebar-right/README.md) | The panel and rail seats, the layout store, `ctx.sidebarRightTabs`, `ctx.sidebarRight`, the Tab domain, the guide type |
20
+ | [`client/ui-dockkit`](../../packages/client/ui-dockkit/README.md) | Pure layout engine and React surface; an internal dependency of `ui-sidebar-right`, not a stable interface |
21
+ | [`client/resources`](../../packages/client/resources/README.md) | `ctx.resources`, `useResource`, the protocol → value roster `ResourceProtocolMap` |
22
+ | [`api/workspace-files`](../../packages/api/workspace-files/README.md) | Host `ctx.workspaceFiles`, the `workspaceFiles` Remote namespace, and the Client `file` resource provider |
23
+ | [`util/workspace-path`](../../packages/util/workspace-path/README.md) | The file address grammar: `fileAddressFor`, `parseFileAddress` |
24
+ | [`client/ui-sidebar-documentpreview`](../../packages/client/ui-sidebar-documentpreview/README.md), [`client/ui-sidebar-files`](../../packages/client/ui-sidebar-files/README.md), [`client/ui-sidebar-browser`](../../packages/client/ui-sidebar-browser/README.md) | The shipped `text`, `files`, and `browser` types |
25
+
26
+ ## Addresses
27
+
28
+ Every tab is opened by an address string, and the address is the tab's content identity. Two families exist.
29
+
30
+ A **resource address** is a `dsh-resource://<type>/…` URL. The host names the resource protocol - the key of `ResourceProtocolMap` - and everything after it is the protocol's own path; one scheme serves every protocol, so adding a protocol adds a host, never a scheme. The `file` protocol's path opens with its scope: `session/<sessionId>` followed by the path relative to that session's workspace root (`dsh-resource://file/session/abc/src/notes.txt`), or `absolute` followed by the absolute path with its leading `/` dropped (`dsh-resource://file/absolute/home/ys/notes.txt`, `dsh-resource://file/absolute/C:/x/y.txt` on Windows). Every id and path segment is component-encoded, with `:` kept literal for drive letters. `fileAddressFor(sessionId, cwd, path)` builds one - a relative path or an absolute path inside the workspace becomes `session`-relative, any other absolute path becomes `absolute` - and `parseFileAddress(address)` reads it back or returns `undefined` ([grammar](../../packages/util/workspace-path/README.md)).
31
+
32
+ A **page address** is what the Sidebar records for a tab opened by kind rather than by resource: `sidebar://<kind>`, written by the Sidebar itself when `openTab(kind)` runs. Callers never build one - the guide and the file tree are opened as `openTab('guide')` and `openTab('files')` - and no other navigation address exists ([not built](#not-built)).
33
+
34
+ Tab identity is the pair `(kind, address)`: the registry's claim uses the address verbatim as the record's `contentId`, so opening the same address through the same type finds the existing tab, and the same address through two types is two tabs.
35
+
36
+ ## Tab-type registration
37
+
38
+ `ctx.sidebarRightTabs.register(definition)` registers one implementation of a type for the caller's lifetime and returns the disposer; the caller holds it inside its own `ctx.effect`, so an implementation lives exactly as long as the plugin that contributed it, and a second registration of the same `id` throws ([extension seats](../../packages/client/ui-sidebar-right/README.md#extension-seats)). The definition is static: no runtime hook, nothing per tab or per session.
39
+
40
+ | Field | Meaning |
41
+ |---|---|
42
+ | `id` | The implementation's identity, unique across every registration; a package name is the natural value (`@deepseek-ai/dsh-client-ui-sidebar-files`). It is the key the body and title register under. |
43
+ | `kind` | The type's discriminator: what its tabs are, and what `openTab` names. Not unique - an extension may take over a builtin's kind. The shipped kinds are `guide`, `text`, `files`. |
44
+ | `patterns` | Optional resource-address globs the type recognizes; a page type opened by kind omits them. A pattern containing `:` matches the whole address (`dsh-resource://file/**`); one without matches the URL's path at any depth (`*.md`), and an address that is not a URL matches no such pattern. Matching is case-insensitive and does not hide dotfiles; the syntax is picomatch's POSIX dialect. |
45
+ | `priority` | One of three literal bands: `extension` (the default and the highest: a type from outside the product outranks every shipped viewer), `builtin` (types shipped with the product), `fallback` (plain-content viewers anything more specific should beat). |
46
+ | `canOpen(address)` | Optional synchronous veto of a glob match; it runs on every routing decision. |
47
+ | `title(address)` | The chip's text, captured into the layout record when the tab opens and never rewritten. |
48
+ | `keepMounted` | Optional lazy retention of visited bodies across hiding, Session switches and docking; the owning View holds the Session reference. |
49
+ | `guide` | Optional entry boxes for the guide page: `{ order, title(), description?(), icon? }`. Picking a box opens the contributing type as a page; omit to stay off the page. |
50
+
51
+ Routing is a ranked claim. `candidates(address)` ranks the types whose patterns match and whose `canOpen` does not veto: by band, then by the length of the longest matched pattern, then by registration order. `claim(address, kind?)` picks the first candidate, or the named `kind` outright - its globs are skipped, its `canOpen` still applies - and returns `{ kind, contentId: address, title }`. An address no type claims throws: it is a wiring mistake, not a user error.
52
+
53
+ One `kind` may carry one `builtin` and one `extension` registration at the same time. The extension is the one in force for claims, `get(kind)`, `openTab(kind)`, and the guide page, and the seat finds a tab's body and title under the definition in force's `id`, so no slot priority is involved; when the extension unregisters, the builtin resumes. Every other collision on a kind, and every duplicate `id`, throws.
54
+
55
+ ```ts ignore-check
56
+ import type { Context } from '@deepseek-ai/cordis'
57
+ import type {} from '@deepseek-ai/dsh-client-ui-sidebar-right/client'
58
+
59
+ export const inject = ['sidebarRightTabs', 'slots']
60
+
61
+ export function apply(ctx: Context): void {
62
+ ctx.effect(() => ctx.sidebarRightTabs.register({
63
+ id: '@acme/dsh-client-ui-image',
64
+ kind: 'image',
65
+ patterns: ['*.png', '*.jpg', '*.gif', '*.svg'],
66
+ canOpen: address => address.startsWith('dsh-resource://file/'),
67
+ title: address => address.slice(address.lastIndexOf('/') + 1),
68
+ }), 'image type')
69
+ ctx.effect(() => ctx.slots.inject('sidebar.right.pane.tab', () => ctx.slots.register(
70
+ { name: 'sidebar.right.pane.tab', key: '@acme/dsh-client-ui-image' },
71
+ ImageBody,
72
+ )), 'image body')
73
+ }
74
+ ```
75
+
76
+ ## Navigation: `ctx.sidebarRight`
77
+
78
+ Two opens are the navigation controller, and every way into the column calls one of them: `openResource(address, options?)` for a `dsh-resource://` address - the conversation's file links, a tool row's line reference, a file tree's rows - and `openTab(kind, options?)` for a page - the strip's add control, a guide entry box, or an HTTP(S) link in Assistant Markdown. Both run four steps as one history entry - claim (the registry ranks the resource's types, or the named `kind`'s implementation in force answers); focus a tab already showing the same `(kind, address)`; otherwise seat a new tab; expand the column - and then record the navigation in the Tab domain ([service](../../packages/client/ui-sidebar-right/README.md#ctxsidebarright)). Content the user cannot see is not opened, so a collapsed column expands in the same step. `openResource` throws for an address outside `dsh-resource://` or one no type claims; `openTab` throws for a kind nothing registered: both are wiring mistakes, not user errors.
79
+
80
+ | Option | Meaning |
81
+ |---|---|
82
+ | `paneId` | Land a new tab in this pane; default is the active docked pane (the first docked pane while a floating pane is active). |
83
+ | `replaceTab` | Take this tab's pane and strip slot, closing it in the same step; a floating tab lends no place, so the new tab lands as if unplaced. |
84
+ | `revealIfOpened` | Default `true`: a tab already showing the same `(kind, address)` is focused and handed `params`. `false` opens another tab regardless. |
85
+ | `preferNewPane` | Prefer a new docked pane under the normal pane budget and room rule; fall back to the target pane when it cannot split. Ignored with `replaceTab`. |
86
+ | `kind` (`openResource` only) | Name the opening type instead of ranking claims; its implementation in force opens the address, and its `canOpen` still applies. |
87
+ | `params` | Navigation parameters for the body, delivered as `navigation.params`. `openResource` types them by resource type through the merge-extensible `SidebarRightResourceParamsMap` (the text preview declares `{ line?: number }`); `openTab<K>` types them by kind through `SidebarRightTabParamsMap`, `undefined` for a kind that declares none; a body reads `SidebarRightNavigationParams`, the union of both. Values are JSON-shaped by convention and not validated at run time. |
88
+
89
+ Placement is the caller's option, never a type's property. The conversation calls `openResource(fileAddressFor(sessionId, cwd, path))` and, from a `read` tool row, adds `{ params: { line } }` from the call's 1-based `offset`; a guide entry box calls `tab.actions.openTab(entry.kind, { replaceTab: true })`; a file-tree row calls `tab.actions.openResource(address)`; the strip's add control calls `openTab('guide', { paneId, revealIfOpened: false })`.
90
+
91
+ `close(tabId)` closes a tab; `active()` returns the active pane's active tab; `isExpanded()` and `toggleExpanded()` read and flip the column, the flip recorded in the sequence. Reads answer for the no-Session case with `undefined` or `false`; writes need a mounted Session surface and throw without one rather than write into a surface nobody draws.
92
+
93
+ `focus(tabId)` makes a tab its pane's active tab; `split(paneId?)` splits the active docked pane, or the named one, and returns the new pane's id - or `undefined`, recording nothing, when the pane budget or the column's width forbids a split; `float(tabId, rect?)` lifts a tab into a floating pane; `dock(paneId)` returns a floating pane to the docked area. All four run the store's existing actions and record one history entry each; a target that does not exist or is already in the requested state is a no-op, and like `open` they throw without a mounted Session surface. `TabId`, `PaneId`, `TabRecord`, and `FloatRect` are re-exported from the package's `/client` entry so a caller needs no dockkit import.
94
+
95
+ `focusedTarget(element?)` captures the visible page under live DOM focus, including an embedding iframe; outside or stale sidebar markup yields no target. `commandTarget(element?)` also permits the mounted Session's active dock pane for an open initiated outside the sidebar. A `SidebarRightTarget` captures Session, pane, host, tab occurrence, and navigation revision. `isTargetCurrent(target)` checks that identity before execution, so reopening a record or navigating it invalidates a captured action; it never retargets to another page. See the [controller methods](../../packages/client/ui-sidebar-right/src/client/service.ts) for close and placement outcomes.
96
+
97
+ ## Slots and owner props
98
+
99
+ The Sidebar declares four extension slots; its document tab declares the additional keyed document body below ([hierarchy](slots.md)).
100
+
101
+ | Slot | Cardinality | Purpose |
102
+ |---|---|---|
103
+ | `sidebar.right.pane.tab` | keyed by the definition's `id`, Session scope | One tab's body. The seat dispatches a tab to the `id` of its kind's implementation in force, so the registrant receives every tab of its kind, docked or floating. A kind whose implementation registered no body renders the owner's "nothing can view this" notice. |
104
+ | `sidebar.right.pane.tab.title` | keyed by the definition's `id`, Session scope | The chip's title, with the same owner share as the body. Optional: without an entry the chip shows the `title(address)` text captured at open time; a type with a live title reads its own store here. |
105
+ | `sidebar.right.tab.guide` | chain, Session scope | Replaces the guide tab's contents without replacing the tab; the first non-declining entry takes the body, otherwise the shipped guide renders. |
106
+ | `sidebar.right.tab.menu.item` | list, Session scope | Content-level actions appended after the kit's own layout actions. An item that acts must call the owner's `dismiss()`. |
107
+ | `sidebar.right.tab.document` | keyed by the document implementation's `id`, Session scope | The selected file renderer inside the document tab; the parent owns shared loading and toolbar controls. |
108
+
109
+ A body, title and guide replacement receive the framework-injected `useTabInfo()`. It returns `{ sidebar, panel, tab }`: `sidebar` holds `expanded` and `fullscreen`, `panel.id` names the containing pane, and `tab` contains its record fields plus `visible`, `navigation`, `signal`, and `actions`. All tabs require a foreground Session. Docked bodies also require expansion and selection; docked titles require expansion; foreground floats survive collapse. `signal` aborts when the record disappears or the plugin unloads, not on hiding or Session switching. `tab.actions` provides `openResource`, `openTab`, and `close`, bound to the tab's own Session. Open placement defaults to its current pane; `revealIfOpened` defaults to `true`, and `replaceTab: true` replaces this record in the same history entry. Menu entries retain plain `tab` and `dismiss` owner parameters.
110
+
111
+ `navigation.revision` increments on every navigation to the tab whether or not `params` changed, so a body can act on "navigated again" alone; it is `1` for a tab opened by address and `0` for a record nobody opened by address - a seeded guide, or a tab restored by undo. The Tab domain holds one occurrence per open record: a record that appears is pinned in the resource model, so switching tabs unmounts a body without dropping its content; a record that vanishes is aborted and dropped; a record restored by undo is a new occurrence ([Tab domain](../../packages/client/ui-sidebar-right/README.md#the-tab-domain)).
112
+
113
+ `tab.actions.bindCommands(commands)` contributes `SidebarRightTabCommands`, currently an optional `refresh` callback, for the mounted body. Omitted operations are unavailable; the returned disposer releases that registration without removing a newer body's commands. The tab lifetime also releases them. `tab.refreshShortcut` supplies the effective refresh catalog entry for page controls; it is optional when no entry is available. These fields are declared in the [slot owner types](../../packages/client/ui-sidebar-right/src/client/contract/slots.ts).
114
+
115
+ ## Document renderers
116
+
117
+ The `text` tab is the shared Document Preview owner. Its [root registration](../../packages/client/ui-sidebar-documentpreview/src/client/index.ts) declares `sidebar.right.tab.document` and provides `ctx.documentPreviews`. A renderer registers `DocumentPreviewDefinition` metadata in its own effect, then waits through `ctx.slots.inject('sidebar.right.tab.document', ...)` and registers its component with `key: definition.id` and its locale namespace. A renderer registers its own body and can reuse shared presentation through its child slots. Changing the renderer does not change the tab or resource address; the [extension decision](../../.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.md) separates preview policy from resource ownership.
118
+
119
+ The [registry](../../packages/client/ui-sidebar-documentpreview/src/client/document/registry.ts) records unique `id`, `extensions`, localized `title()`, `loading`, optional `priority`, and optional `wrap`. Case-insensitive suffix matching ranks `extension` (the default) before `builtin`, then longer suffixes before shorter ones, then registration order. Unlike tab-kind replacement, the registry keeps all implementations available; the toolbar lists matching alternatives and remembers the selection per tab. Unknown extensions use plain text. Suffixes declared in `binaryExtensions` suppress the plain-text alternative, as described in the [package README](../../packages/client/ui-sidebar-documentpreview/README.md#what-it-registers). `loading` is `text-pages`, `bytes-complete`, or `renderer`; `wrap` advertises support for the shared source-wrap control.
120
+
121
+ [`DocumentPreviewProps`](../../packages/client/ui-sidebar-documentpreview/src/client/document/contract.ts) derives from `PropsRuntime<'sidebar.right.tab.document'>`. The owner supplies the original `resourceAddress`, `content`, current `wrap`, and `addResource` / `setResources` dependency callbacks: text content is `{ kind: 'text', text, pages: [{ offset, text, lines }], eof }`, with cumulative `text`; complete bytes are `{ kind: 'bytes', data }`, with `Uint8Array<ArrayBuffer>` data. These transient buffers are borrowed read-only and must not enter durable layout or Session JSON. PDF copies the bytes before Worker transfer, preserving the owner's buffer. The child receives the same framework-bound `useTabInfo` and the global metadata-only `useResource`. The parent reads text through `remote.workspaceFiles.read` and bytes through `remote.workspaceFiles.readBytes`, and owns page appends, per-tab refresh, and loading status. HTML passes `baseFile` to the same byte reader; Host code resolves paths. Markdown and code retain one incremental renderer across appends and settle at EOF; HTML and PDF receive complete bytes.
122
+
123
+ Preview records its loaded version and the version observed when a read starts. Automatic refresh defaults to enabled; initial member metadata establishes a baseline, and later changes reload the tab. Refresh rereads only that tab, without changing shared metadata or another tab's content. Reads are non-transactional; versions are opaque equality tokens, not ordered timestamps ([resource observation and Preview RPC](../../.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.md)).
124
+
125
+ A renderer that owns loading receives `{ kind: 'renderer', revision, loaded, failed, reload }` instead of file bytes. The body invokes its injected face, cancels on revision changes and unmount, and reports its displayed source version through `loaded(version)`. A failed load calls `failed()` so a later file change can retry. The parent ignores stale reports and retains the shared reload and source-change controls. Office uses this mode to request [Host-rendered PDFs](office-to-pdf.md); its face writes converted bytes, font metadata, and failures to its own store, while its body renders a nested PDF view. `OfficeFontAction` renders the missing-font warning before reload through `sidebar.right.tab.document.action`. The [package README](../../packages/client/ui-sidebar-documentpreview/README.md#what-it-registers) defines the loading lifecycle.
126
+
127
+ ## Resource model
128
+
129
+ The model is documented in [Client Resources](client-resources.md); this section states what the Sidebar relies on. A resource is one address, and a resource address is a `dsh-resource://<type>/…` URL whose lower-cased host is the protocol key. The protocol's owning client package registers one provider with `ctx.resources.register(provider)` for its own lifetime; a second provider for the same protocol throws ([provide a protocol](../../packages/client/resources/README.md#provide-a-protocol)). A provider is `{ protocol, open(address, { signal }) }`: `open` yields `RemoteResult` frames - the current state first, one frame per later change - and stops when `signal` aborts; a failure is an `{ ok: false, error }` frame, never a throw, and a throw inside the stream is a programming error the model does not catch.
130
+
131
+ `useResource<P>(address)` is a global standard prop on every slot component, whatever its scope. It returns `{ status, value, failure }`: `none` when the address's protocol has no provider or the address is not a resource address (`sidebar://guide` names no resource), `loading` until the first frame, `live` with the latest `ok` value, `failed` with the latest frame's failure beside the last value. ([read a resource](../../packages/client/resources/README.md#read-a-resource)).
132
+
133
+ A resource stays open while it has a holder - a subscribed `useResource` or a `ctx.resources.pin(address, signal)`; the first holder opens the provider's stream, later holders share it and read the latest value at once, and the last release aborts the stream and discards the value. Streams carry metadata, not content: the `file` value is `{ absolutePath, version, bytes? }`, and a consumer reads file text itself, by page, through the Workspace Files service ([lifecycle](../../packages/client/resources/README.md#lifecycle)).
134
+
135
+ ## Workspace Files
136
+
137
+ The Host `ctx.workspaceFiles` service and generated `workspaceFiles` Remote namespace read files allowed by the Session filesystem backend: `stat(path)` returns `{ absolutePath, version, bytes? }`; `read(path, { offset?, limit? })` returns one page of lines (`offset` 1-based, `limit` capped by the configured page size) as `{ …stat, offset, text, eof }`; `readBytes(path, { range?, baseFile? })` returns a complete file under `maxFileBytes` or a byte window under `maxBytes` as `{ …stat, offset, data, eof }` with native `Uint8Array` data. Its optional `range` uses 0-based `offset` and a byte `length`; `baseFile` resolves the relative target from another file’s directory. `list(path)` remains inside the workspace root and returns a directory's direct children (`name`, `type: 'file' | 'directory' | 'other'`, `size?`) cut to the configured cap with `truncated` set. `changes(path)` watches one target; the Host determines its type and confines directories to the workspace. It yields `{ kind: 'ready' }` once subscribed, then `{ kind: 'change', change }` frames whose payload is `{ absolutePath, version }` or `{ absolutePath, absent: true }` ([README](../../packages/api/workspace-files/README.md#use-this-package)). File reads reject final symlinks and enforce transfer caps; `read` additionally requires UTF-8 text. Failures use `workspace-file/*` codes ([failures](../../packages/api/workspace-files/README.md)).
138
+
139
+ [`dsh-api-workspace-files`](../../packages/api/workspace-files/README.md) registers the `file` provider, with `ResourceProtocolMap.file` directly naming `WorkspaceFileStat`. A Session address carries the authorizing Session and a relative or absolute path, passed unchanged to the Host for resolution. The provider waits for Host `ready` before stat and filters changes by `stat.absolutePath`. Bare `absolute` addresses have no authorizing Session and fail with `workspace-file/unknown-workspace`, without borrowing current or Tab Session. Any UI, including Global components, shares the observation for the same complete address. Preview's Remote callbacks use the Session in that address; `remote.workspaceFiles.readBytes` returns native bytes through Connection's binary RPC transport.
140
+
141
+ ## Shipped types
142
+
143
+ - **`guide`** - `builtin`, opened as `openTab('guide')`. A muted compass sits above one capsule per contributed `guide` entry, in `order`; short lists show registered descriptions, and every missing icon uses the shipped placeholder. Picking a capsule opens the contributing type as a page in the guide tab's place. A pane holds at most one guide tab, and the strip's add control appears only while its pane has none. A new pane receives the registered default page: the sole guide entry directly, or the guide when the entry count is not one ([guide](../../packages/client/ui-sidebar-right/README.md#the-guide)).
144
+ - **`text`** - `fallback`, `dsh-resource://file/**`, claiming Session addresses only. Document Preview observes metadata through `useResource<'file'>`, loads content through Remote callbacks, and owns renderer selection, the toolbar, per-tab refresh, scroll, and source navigation; unknown extensions render as plain text ([README](../../packages/client/ui-sidebar-documentpreview/README.md)).
145
+ - **`files`** - `builtin`, opened as `openTab('files')`. The workspace directory tree, listed lazily through `list` and watched by expanded directory, opening a file with `tab.actions.openResource(fileAddressFor(sessionId, root, path))` into its own pane ([README](../../packages/client/ui-sidebar-files/README.md)).
146
+ - **`browser`** - multi-instance `builtin`, opened as `openTab('browser', { params: { url? } })`. Chat's [link preference](../../packages/client/ui-chat/README.md) controls whether Assistant Markdown opens HTTP(S) links here. It accepts public and loopback HTTP(S) targets under the default sandbox, rejects local files in favor of Document Preview, and uses application-known iframe history ([README](../../packages/client/ui-sidebar-browser/README.md)).
147
+ - **`subagentchat`** - `builtin`, `dsh-resource://subagentchat/session/<child>?parent=<parent>&mode=<mode>`. An explicitly addressed subagent Conversation retained by the resource provider and rendered through the shared Conversation Factory ([README](../../packages/client/ui-subagent/README.md)).
148
+
149
+ <a id="not-built"></a>
150
+ ## Not built
151
+
152
+ - Persistence: layout state is memory-only; a reload starts every session collapsed, and no session's tabs are visible from another.
153
+ - A read-only layout snapshot or subscription on `ctx.sidebarRight`: the service exposes operations only, and dockkit's `LayoutState`/`LayoutOp` are internal.
154
+ - A capability-discovery array (`features`) on the service.
155
+ - An `option` priority band for tab types: nothing lists a tab type without letting it claim.
156
+ - Retitling a record: `title(address)` is captured once; a live chip comes from the title slot, not from the record.
157
+ - Naming a tab implementation when opening: `openResource` names a kind at most; document-renderer selection belongs to the file tab's toolbar.
158
+ - An address lookup on the service (`find`): a caller opens with `revealIfOpened` and lets the surface de-duplicate.
159
+ - Navigation addresses beyond the Sidebar's own `sidebar://<kind>` bookkeeping; their grammar waits for the navigation controller as a whole.
160
+ - A user-facing undo and general cross-type content navigation stack ([deferred](../../.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.md#deferred)); Browser owns only its own page history.
@@ -0,0 +1,354 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/skills.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Skills
4
+
5
+ English | [中文](skills.zh.md)
6
+
7
+ The [skill capability family](../../packages/skill) includes the Service Definition ([dsh-skill](../../packages/skill/skill), `ctx.skills`), the local Service Provider ([dsh-skill-filesystem](../../packages/skill/skill-filesystem)), optional packaged providers ([dsh-skill-badge](../../packages/skill/skill-badge), [dsh-skill-office](../../packages/skill/skill-office), and the Windows ACL diagnosis provider in [dsh-sandbox-windows-acl](../../packages/sandbox/sandbox-windows-acl)), and the Consumer ([dsh-tool-skill](../../packages/skill/tool-skill)). The registry merges provider catalogs across its host and per-scope layers; providers contribute local or packaged skills; the Consumer owns the initial and replacement catalogs plus the model-facing `skill` tool. Skills are optional instructions, not session events, so their vocabulary lives here rather than in [core.md](core.md).
8
+
9
+ Source: [`packages/skill/skill/src/index.ts`](../../packages/skill/skill/src/index.ts), [`packages/skill/skill-filesystem/src/index.ts`](../../packages/skill/skill-filesystem/src/index.ts), [`packages/skill/skill-badge/src/index.ts`](../../packages/skill/skill-badge/src/index.ts), [`packages/skill/skill-office/src/index.ts`](../../packages/skill/skill-office/src/index.ts), [`packages/sandbox/sandbox-windows-acl/src/acl-skill.ts`](../../packages/sandbox/sandbox-windows-acl/src/acl-skill.ts), and [`packages/skill/tool-skill/src/index.ts`](../../packages/skill/tool-skill/src/index.ts).
10
+
11
+ ## Provider registry
12
+
13
+ `ctx.skills` combines local, embedded, remote, or other providers. Registration is synchronous; remote initialization and discovery belong in awaited `list()`. Provider objects, options, and candidates are borrowed readonly, while semantic fields are validated.
14
+
15
+ The registry is host+per-scope layered, the shape the [tools registry](tools.md) established over [dsh-scope](../../packages/core/scope): a registration files into the layer of its calling context's scope, so host rows and repository plugins land in the global layer while a plugin mounted by an agent preset's standing composition lands in that preset's layer, and provider names are unique per layer rather than process-wide. A read merges the global layer with the viewing scope's chain - the nearest layer's entry wins a duplicate skill name outright, and the rank order below decides duplicates only within one layer. Discovery caches are keyed by the resolved scope chain, so re-parenting a scope (a blank-session recompose) is visible to the next read without a registry mutation.
16
+
17
+ Within one layer, duplicate names resolve by rank, provider order, then local order; summaries sort by name. A rejected `list()` is logged and omitted from an incomplete observation, while an explicit incomplete observation contributes usable candidates without making the result cacheable; malformed candidates fail fast. Each provider factory receives a registration-scoped control whose `invalidate()` clears completed catalogs only while that exact registration remains active and whose signal aborts on failed registration or disposal. An in-flight discovery retries once when its provider generation changes; a second change returns the latest candidates incomplete and uncached. Provider and runtime mutations emit the unfiltered `skills/change` invalidation event; it carries no diff, so consumers refetch `snapshot()` with their own lookup options.
18
+
19
+ An array returned by `SkillProvider.list()` is complete-discovery shorthand. `SkillProviderObservation` lets a provider expose candidates that remain directly loadable while reporting that the observation is not authoritative.
20
+
21
+ ```ts type-equiv
22
+ /** Provider candidates plus whether the current discovery is authoritative. */
23
+ interface SkillProviderObservation {
24
+ /** Candidates available from the current provider discovery. */
25
+ readonly candidates: readonly SkillCandidate[]
26
+ /** Whether discovery completed and these candidates may be cached. */
27
+ readonly complete: boolean
28
+ }
29
+ ```
30
+
31
+ ```ts type-equiv
32
+ /** Provider interface for one source of skills, such as local directories or a remote registry. */
33
+ interface SkillProvider {
34
+ /** Unique provider name in the `ctx.skills` registry. */
35
+ readonly name: string
36
+ /**
37
+ * List available skill candidates for the current lookup context. Provider
38
+ * plugins register synchronously during `apply()`; remote initialization,
39
+ * authentication, and discovery are awaited inside this method. Implementations
40
+ * should settle promptly when `options.signal` aborts.
41
+ * @param options - lookup options; `cwd` selects workspace-sensitive skills and `signal` cancels work.
42
+ * @returns provider candidates as a complete-array shorthand, or an explicit
43
+ * observation when usable candidates came from incomplete discovery.
44
+ */
45
+ readonly list: (options: SkillLookupOptions) => Promise<readonly SkillCandidate[] | SkillProviderObservation>
46
+ /**
47
+ * Load a complete skill body for a previously listed candidate.
48
+ * @param candidate - the winning candidate originally returned by this provider.
49
+ * @param options - lookup options; `cwd` selects workspace-sensitive skills and `signal` cancels work.
50
+ * @returns the full skill body, or `undefined` if it is no longer loadable.
51
+ */
52
+ readonly get: (candidate: SkillCandidate, options: SkillLookupOptions) => Promise<SkillDefinition | undefined>
53
+ }
54
+ ```
55
+
56
+ ```ts type-equiv
57
+ /** Registration-scoped lifecycle and invalidation capability borrowed by one provider. */
58
+ interface SkillProviderControl {
59
+ /** Aborts if registration fails or when the exact provider registration is disposed. */
60
+ readonly signal: AbortSignal
61
+ /** Invalidate completed catalogs and notify consumers only while the exact registration remains active. */
62
+ readonly invalidate: () => void
63
+ }
64
+ ```
65
+
66
+ ## Local discovery priority
67
+
68
+ The shipped local provider scans roots in rank order:
69
+
70
+ | Rank | Source | Root |
71
+ |---|---|---|
72
+ | 100 | `project-dsh` | `<projectRoot>/.dsh/skills` |
73
+ | 200 | `project-agents` | `<projectRoot>/.agents/skills` |
74
+ | 300 | `custom` | `Config.customSkillDirs` |
75
+ | 400 | `user-dsh` | `<dshHome>/skills` |
76
+ | 500 | `user-agents` | `<agentsHome>/skills` |
77
+ | 600 | `bundled` | `Config.bundledSkillDir` when configured |
78
+
79
+ The project root is the nearest ancestor containing `.git`; without one, the current cwd is used. When `ctx.fs` is available, the git-root walk probes `.git` through the filesystem service so remote or sandboxed workspaces do not fall back to the host filesystem boundary. The user DSH root skips its `.system` child. The local provider does not synthesize built-in system skills; deployments supply packaged skills through configured bundled roots or dedicated providers.
80
+
81
+ `dsh-skill-badge` registers one immutable `bundled` candidate at `BUNDLED_SKILL_RANK` and exposes its packaged asset directory through `resourceBase`. The shipped CLI declares the plugin disabled, so enabling its composition row is an explicit opt-in.
82
+
83
+ Chokidar watches existing roots for direct bundle/flat-entry additions and removals plus direct skill-entry changes. A missing root is followed one absent path segment at a time from its nearest existing ancestor until Chokidar can attach. Resource files below a bundle are not catalog changes. Model-facing `write` and `edit` observations synchronously invalidate the provider when their target is catalog-relevant, while the host watcher covers IDE, Git, shell, and external-process mutations. Watcher failures make the current observation incomplete without hiding readable candidates from direct loads; project-scoped watchers use a configured bounded LRU.
84
+
85
+ ## Skill identity
86
+
87
+ Skill names are kebab-case (`^[a-z0-9]+(?:-[a-z0-9]+)*$`). The local provider accepts directory bundles (`<name>/SKILL.md`) and flat Markdown files (`<name>.md`). Nested recursive `**/SKILL.md` discovery is not supported.
88
+
89
+ ```ts type-equiv
90
+ /** Origin bucket for a skill contribution. The value is prompt-visible metadata, not precedence by itself. */
91
+ type SkillSource = 'project-dsh' | 'project-agents' | 'runtime' | 'user-dsh' | 'user-agents' | 'custom' | 'bundled' | (string & {})
92
+ ```
93
+
94
+ ## Summaries, candidates, and complete definitions
95
+
96
+ `SkillSummary` is the registry's invocation-neutral summary shape. Consumers choose which entries and fields to render; the model session catalog uses only model-invocable `name` and `description`, never the body or absolute file path. `SkillInvocationPolicy` normalizes the two independent invocation controls into positive booleans, and every resolved summary, candidate, and definition carries it without turning arbitrary frontmatter into the domain model.
97
+
98
+ ```ts type-equiv
99
+ /** Invocation controls shared by skill discovery consumers. */
100
+ interface SkillInvocationPolicy {
101
+ /** Whether model-facing catalogs and loaders include this skill. */
102
+ readonly modelInvocable: boolean
103
+ /** Whether human-facing command catalogs and loaders include this skill. */
104
+ readonly userInvocable: boolean
105
+ }
106
+ ```
107
+
108
+ ```ts type-equiv
109
+ /** Invocation-neutral skill metadata returned by `ctx.skills.list()`. */
110
+ interface SkillSummary {
111
+ /** Absolute instruction file path when supplied by the provider; absent for virtual skills. */
112
+ readonly path?: string
113
+ /** Kebab-case identifier used to address the skill. */
114
+ readonly name: string
115
+ /** Short routing description shown by discovery consumers. */
116
+ readonly description: string
117
+ /** Optional extra routing guidance. */
118
+ readonly whenToUse?: string
119
+ /** Resolved model and user invocation controls. */
120
+ readonly invocation: SkillInvocationPolicy
121
+ /** Discovery source that produced this winning skill. */
122
+ readonly source: SkillSource
123
+ /** Provider that owns this skill body. */
124
+ readonly provider: string
125
+ /** Provider-specific base for relative resources. */
126
+ readonly resourceBase?: SkillResourceBase
127
+ }
128
+ ```
129
+
130
+ `ctx.skills.list()` preserves all four policy combinations. `isModelInvocable(skill)` and `isUserInvocable(skill)` read the corresponding required field. A model-only skill sets `{ modelInvocable: true, userInvocable: false }`, a user-only skill sets `{ modelInvocable: false, userInvocable: true }`, and setting both fields to `false` keeps the skill available only through trusted `ctx.skills.get()` callers. The local provider reads the exact kebab-case frontmatter keys `disable-model-invocation` and `user-invocable`, defaults omitted fields to `true`, and projects every parsed skill into this normalized policy.
131
+
132
+ `SkillCatalogSnapshot` distinguishes authoritative absence from transient provider failure or a catalog that kept changing during discovery. `skills` contains the sorted invocation-neutral summaries collected in that observation; `complete` is true only when every registered provider completed without a concurrent catalog revision. Incomplete snapshots are not cached, allowing each consumer to retain its last-good filtered catalog and retry.
133
+
134
+ ```ts type-equiv
135
+ /** One catalog observation plus whether discovery completed within a stable catalog revision. */
136
+ interface SkillCatalogSnapshot {
137
+ /** Sorted invocation-neutral summaries collected in this observation. */
138
+ readonly skills: SkillSummary[]
139
+ /** Whether every registered provider completed without a concurrent catalog revision. */
140
+ readonly complete: boolean
141
+ }
142
+ ```
143
+
144
+ `SkillCandidate` is the provider-to-registry shape. `locator` is opaque provider state; the registry only stores it and gives it back to the winning provider's `get()`.
145
+
146
+ ```ts type-equiv
147
+ /** Provider catalog entry used by the registry to merge and later load skills. */
148
+ interface SkillCandidate extends SkillSummary {
149
+ /** Lower ranks win duplicate skill names before provider registration order is considered. */
150
+ readonly rank: number
151
+ /** Opaque provider-owned handle passed back to `provider.get()`. */
152
+ readonly locator: unknown
153
+ /** Parsed optional metadata object from provider-specific skill frontmatter. */
154
+ readonly metadata?: Readonly<Record<string, unknown>>
155
+ }
156
+ ```
157
+
158
+ `SkillDefinition` is the complete parsed result returned by `ctx.skills.get()` and used by the `skill` tool. `resourceBase` tells the tool how to render relative-resource guidance for local, URL, or provider-managed skills.
159
+
160
+ ```ts type-equiv
161
+ /** Optional provider-specific base used by loaded skill bodies to resolve relative resources. */
162
+ type SkillResourceBase =
163
+ | { readonly kind: 'directory'; readonly path: string }
164
+ | { readonly kind: 'url'; readonly url: string }
165
+ | { readonly kind: 'opaque'; readonly description: string }
166
+ ```
167
+
168
+ ```ts type-equiv
169
+ /** Complete parsed skill definition, including the body loaded by `ctx.skills.get()`. */
170
+ interface SkillDefinition extends SkillSummary {
171
+ /** Markdown instruction body after any provider-specific metadata removal. */
172
+ readonly content: string
173
+ /** Parsed optional metadata object from frontmatter. */
174
+ readonly metadata?: Readonly<Record<string, unknown>>
175
+ }
176
+ ```
177
+
178
+ Runtime skill inputs may omit invocation controls and the provider label. The registry resolves both defaults once, then uses the same complete definition shape and first-wins collection order as providers. The returned disposer removes the contribution and invalidates discovery caches.
179
+
180
+ ```ts type-equiv
181
+ /** Runtime skill contribution accepted by `ctx.skills.register()`. */
182
+ type SkillRegistration = Omit<SkillDefinition, 'invocation' | 'provider'> & {
183
+ /** Invocation controls; omission permits both model and user surfaces. */
184
+ readonly invocation?: SkillInvocationPolicy
185
+ /** Provider label; omission uses the registry-owned runtime provider. */
186
+ readonly provider?: string
187
+ }
188
+ ```
189
+
190
+ ## Lookup and configuration
191
+
192
+ Skill lookup is cwd-sensitive because providers may expose workspace-local skills, and its optional signal cancels provider work for the caller. Registry reads additionally take the viewing scope - consumers pass the calling agent, which is its own scope key - through `SkillViewOptions`; the registry consumes `scope` for layer selection, and providers read only their `SkillLookupOptions` contract from the same borrowed options object. Cancellation is checked before and after catalog selection, including cache hits, and races both discovery and full-definition loading. If no git root is found, the local provider treats the supplied cwd itself as the project root.
193
+
194
+ Full definitions are not cached by the registry. Each `get()` calls the winning provider with the selected candidate, so the local provider rereads the current body. A definition whose name no longer matches that candidate is rejected and invalidates the exact provider for rediscovery.
195
+
196
+ ```ts type-equiv
197
+ /** Caller context used for cwd-sensitive and abortable provider work. */
198
+ interface SkillLookupOptions {
199
+ /** Workspace selector for the current lookup. */
200
+ readonly cwd?: string | undefined
201
+ /** Abort discovery or loading work for the current caller. */
202
+ readonly signal?: AbortSignal | undefined
203
+ }
204
+ ```
205
+
206
+ ```ts type-equiv
207
+ /**
208
+ * Registry read options: provider lookup context plus the viewing scope.
209
+ * The registry consumes `scope` to select layers; providers receive the same
210
+ * borrowed options object and read only their {@link SkillLookupOptions}
211
+ * contract from it.
212
+ */
213
+ interface SkillViewOptions extends SkillLookupOptions {
214
+ /** Viewing scope (the calling agent); omitted reads the global layer alone. */
215
+ readonly scope?: ScopeKey | undefined
216
+ }
217
+ ```
218
+
219
+ The registry owns only its discovery-cache bound. The local provider owns filesystem roots (`dshHome`, `agentsHome`, `customSkillDirs`, and optional `bundledSkillDir`/`DSH_BUNDLED_SKILL_DIR`) plus watcher enablement, polling, stability, symlink, and project-capacity controls. The consumer owns its catalog description bound. Exact defaults and validation are in the generated [config catalog](../config-catalog.md).
220
+
221
+ ```ts type-equiv
222
+ /** Skill registry configuration. */
223
+ interface Config {
224
+ /** Maximum number of completed cwd/provider catalogs kept in memory. */
225
+ readonly collectCacheMaxEntries?: number
226
+ }
227
+ ```
228
+
229
+ ## Session catalog and tool contract
230
+
231
+ `dsh-tool-skill` injects the initial durable user-role `<system-reminder>` at the first `agent/pre-step` of a live session that observes a non-empty complete view. The catalog contains sorted skill `name` and normalized, XML-escaped `description` only; it omits bodies, paths, sources, providers, and routing hints. Discovery forwards the step's abort signal through `SkillLookupOptions`. `catalogDescriptionMaxLength` is the consumer config for the description bound, with default `500` and integer minimum `3`.
232
+
233
+ Before each later model step, the consumer applies exact tool visibility and digests the exact rendered entries between the `<available_skills>` tags from a complete snapshot. It derives the comparison baseline from the same entries in the newest recognizable visible catalog message sourced by the plugin. A changed digest appends a durable full replacement through `agent.inject()`; deleting every skill appends an explicit empty replacement. Incomplete snapshots preserve the last-good model view. If compaction hides every historical catalog message, the next complete snapshot re-establishes the current catalog; an empty view with no prior catalog emits nothing. These catalog messages are session history, not World State.
234
+
235
+ The model-facing `skill({ name })` tool validates the kebab-case name, finds the summary in the invocation-neutral catalog, rejects it before loading unless `isModelInvocable` permits access, then rereads the complete definition for the calling agent cwd and rechecks the policy before returning content. It reports an unresolved skill as unknown or no longer available and returns a tool result containing `<skill_content name="...">`, `<skill_resources>`, and `<skill_instructions>`. `resourceBase` resolves explicitly referenced scripts, references, and assets only as needed; the loaded result does not enumerate a skill directory. Body-only edits therefore change later tool calls without producing catalog messages or rewriting earlier tool results.
236
+
237
+ ## Browser Session catalog
238
+
239
+ `SkillListRequest` addresses one Session by `sessionId`; `SkillListValue` returns the user-invocable entries with name, description, optional usage guidance, and model-invocation availability. `SessionSkillCatalog` reads the Session cwd and recorded preset without activating an Agent. A live Agent may supply its scoped registry, while a cold Session uses the preset's standing scope.
240
+
241
+ <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
242
+
243
+ <a id="cordis-surface"></a>
244
+
245
+ ## Cordis API
246
+
247
+ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) - the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
248
+
249
+ <a id="ctxsessionskillcatalog--sessionskillcatalog"></a>
250
+
251
+ ### `ctx.sessionSkillCatalog` - `SessionSkillCatalog`
252
+
253
+ Host service backing `ctx.remote.skills` without activating a cold Agent.
254
+
255
+ ```ts cordis-catalog
256
+ /**
257
+ * List the user-invocable skills visible to one Session composition.
258
+ * @param request - Session identity whose cwd and preset select the catalog view.
259
+ * @param signal - caller lifetime carried by the Remote transport; admitted catalog reads retain their existing completion semantics.
260
+ * @returns user-invocable skill metadata without loading skill bodies.
261
+ * @throws RemoteError when the Session cannot be inspected or no registry can serve it.
262
+ */
263
+ @Remote async list(request: SkillListRequest, signal: AbortSignal): Promise<SkillListValue>
264
+ ```
265
+
266
+ Source: [`packages/api/session-controller/src/skill-catalog.ts`](../../packages/api/session-controller/src/skill-catalog.ts)
267
+
268
+ <a id="ctxskills--skillregistry"></a>
269
+
270
+ ### `ctx.skills` - `SkillRegistry`
271
+
272
+ Layered registry of skill providers, the host+per-scope shape the tools registry established. A registration files into the layer of its calling context's scope (scopeOf): host rows and repository plugins land in the global layer, while a plugin mounted by an agent preset's standing composition lands in that preset's layer. A read merges the global layer with the viewing scope's chain - the nearest layer's entry wins a duplicate name outright, and the rank order decides duplicates only within one layer. It exposes sorted invocation-neutral summaries and loads full skill bodies on demand.
273
+
274
+ ```ts cordis-catalog
275
+ /**
276
+ * Register a borrowed same-process provider synchronously during plugin
277
+ * apply, into the calling context's layer: a scoped context (an agent
278
+ * preset's standing mount) registers for that scope alone, an unscoped
279
+ * context registers globally. Duplicate names within one layer and reserved
280
+ * names throw; remote initialization belongs in `list()`. Fiber disposal
281
+ * unregisters the provider and invalidates catalog caches.
282
+ * @param create - synchronous factory receiving this registration's lifecycle and invalidation control.
283
+ * @returns the exact Cordis effect disposer that unregisters this provider;
284
+ * composite effects may yield it directly to preserve teardown ordering.
285
+ */
286
+ registerProvider(create: (control: SkillProviderControl) => SkillProvider): () => void
287
+
288
+ /**
289
+ * Register a borrowed readonly runtime skill into the calling context's
290
+ * layer. Project entries outrank runtime entries, which outrank user
291
+ * entries, within one layer. Same-name runtime entries in one layer are
292
+ * first-wins; a duplicate logs a warning and receives a no-op disposer so
293
+ * it cannot remove the winner.
294
+ * @param skill - the skill definition input; omitted invocation and provider fields receive defaults.
295
+ * @returns the exact Cordis effect disposer, preserving composite teardown order and invalidating caches.
296
+ */
297
+ register(skill: SkillRegistration): () => void
298
+
299
+ /**
300
+ * List invocation-neutral skill summaries for a workspace. Consumers apply
301
+ * model or user invocation policy at their operational boundary. Lookup
302
+ * options and provider candidates are readonly same-process values borrowed
303
+ * throughout discovery.
304
+ * @param options - view options; `scope` selects the viewing agent's layers, `cwd` selects project roots, and `signal` cancels discovery.
305
+ * @returns all sorted winning summaries.
306
+ */
307
+ async list(options: SkillViewOptions = {}): Promise<SkillSummary[]>
308
+
309
+ /**
310
+ * Observe the current invocation-neutral catalog and whether discovery completed within a stable revision.
311
+ * Incomplete observations are never cached, allowing consumers to retain last-good state and
312
+ * retry on their next request boundary.
313
+ * @param options - view options; `scope` selects the viewing agent's layers, `cwd` selects project roots, and `signal` cancels discovery.
314
+ * @returns sorted summaries plus discovery-completeness state.
315
+ */
316
+ async snapshot(options: SkillViewOptions = {}): Promise<SkillCatalogSnapshot>
317
+
318
+ /**
319
+ * Load and validate the winning candidate, passing its opaque discovery locator back to the
320
+ * provider. Cancellation is rechecked after selection, including cache hits, and raced against
321
+ * loading so an uncooperative provider cannot hang the caller.
322
+ * @param name - kebab-case skill name.
323
+ * @param options - view options; `scope` selects the viewing agent's layers,
324
+ * `cwd` selects workspace-sensitive skills, and `signal` cancels work.
325
+ * @returns the full skill, including body content, or `undefined`.
326
+ */
327
+ async get(name: string, options: SkillViewOptions = {}): Promise<SkillDefinition | undefined>
328
+ ```
329
+
330
+ Source: [`packages/skill/skill/src/index.ts`](../../packages/skill/skill/src/index.ts)
331
+
332
+ <a id="skills-events"></a>
333
+
334
+ ### `skills/*` events
335
+
336
+ <a id="skillschange--emit"></a>
337
+
338
+ #### `skills/change` - emit
339
+
340
+ A skill provider, runtime contribution, or provider-backed catalog may have changed. This is an unfiltered invalidation notification; consumers refetch the catalog for their own lookup options. Listener failures are contained and cannot veto the registry mutation.
341
+
342
+ ```ts cordis-catalog
343
+ /**
344
+ * A skill provider, runtime contribution, or provider-backed catalog may
345
+ * have changed. This is an unfiltered invalidation notification; consumers
346
+ * refetch the catalog for their own lookup options. Listener failures are
347
+ * contained and cannot veto the registry mutation.
348
+ * @mode emit
349
+ */
350
+ 'skills/change'(): void
351
+ ```
352
+
353
+ Source: [`packages/skill/skill/src/index.ts`](../../packages/skill/skill/src/index.ts)
354
+ <!-- END GENERATED cordis-surface -->