docs: refresh optional setup helper refs

docs/plugins/building-plugins.md

@@ -38,6 +38,12 @@ falls back to npm automatically.
   </Card>
 </CardGroup>
 
+If a channel plugin is optional and may not be installed when onboarding/setup
+runs, use `createOptionalChannelSetupSurface(...)` from
+`openclaw/plugin-sdk/channel-setup`. It produces a setup adapter + wizard pair
+that advertises the install requirement and fails closed on real config writes
+until the plugin is installed.
+
 ## Quick start: tool plugin
 
 This walkthrough creates a minimal plugin that registers an agent tool. Channel

docs/plugins/sdk-channel-plugins.md

@@ -93,10 +93,22 @@ For setup specifically:
   delegated setup-proxy builders
 - `openclaw/plugin-sdk/setup-adapter-runtime` is the narrow env-aware adapter
   seam for `createEnvPatchedAccountSetupAdapter`
+- `openclaw/plugin-sdk/channel-setup` covers the optional-install setup
+  builders plus a few setup-safe primitives:
+  `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`,
+  `createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`,
+  `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, and
+  `splitSetupEntries`
 - use the broader `openclaw/plugin-sdk/setup` seam only when you also need the
   heavier shared setup/config helpers such as
   `moveSingleAccountChannelSectionToDefaultAccount(...)`
 
+If your channel only wants to advertise "install this plugin first" in setup
+surfaces, prefer `createOptionalChannelSetupSurface(...)`. The generated
+adapter/wizard fail closed on config writes and finalization, and they reuse
+the same install-required message across validation, finalize, and docs-link
+copy.
+
 For other hot channel paths, prefer the narrow helpers over broader legacy
 surfaces:
 

docs/plugins/sdk-migration.md

@@ -163,12 +163,12 @@ Current bundled provider examples:
   | `plugin-sdk/setup` | Shared setup wizard helpers | Allowlist prompts, setup status builders |
   | `plugin-sdk/setup-runtime` | Setup-time runtime helpers | Lookup-note helpers, `promptResolvedAllowFrom`, `splitSetupEntries`, delegated setup proxies |
   | `plugin-sdk/setup-adapter-runtime` | Setup adapter helpers | `createEnvPatchedAccountSetupAdapter` |
-  | `plugin-sdk/setup-tools` | Setup tooling helpers | CLI/archive/docs helpers for setup/install flows |
+  | `plugin-sdk/setup-tools` | Setup tooling helpers | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
   | `plugin-sdk/account-core` | Multi-account helpers | Account list/config/action-gate helpers |
   | `plugin-sdk/account-id` | Account-id helpers | `DEFAULT_ACCOUNT_ID`, account-id normalization |
   | `plugin-sdk/account-resolution` | Account lookup helpers | Account lookup + default-fallback helpers |
   | `plugin-sdk/account-helpers` | Narrow account helpers | Account list/account-action helpers |
-  | `plugin-sdk/channel-setup` | Setup wizard adapters | `createOptionalChannelSetupSurface` |
+  | `plugin-sdk/channel-setup` | Setup wizard adapters | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, plus `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
   | `plugin-sdk/channel-pairing` | DM pairing primitives | `createChannelPairingController` |
   | `plugin-sdk/channel-reply-pipeline` | Reply prefix + typing wiring | `createChannelReplyPipeline` |
   | `plugin-sdk/channel-config-helpers` | Config adapter factories | `createHybridChannelConfigAdapter` |

docs/plugins/sdk-overview.md

@@ -73,11 +73,11 @@ explicitly promotes one as public.
     | --- | --- |
     | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
     | `plugin-sdk/config-schema` | Root `openclaw.json` Zod schema export (`OpenClawSchema`) |
-    | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface` |
+    | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, plus `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
     | `plugin-sdk/setup` | Shared setup wizard helpers, allowlist prompts, setup status builders |
     | `plugin-sdk/setup-runtime` | `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
     | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
-    | `plugin-sdk/setup-tools` | Setup CLI/archive/docs helpers |
+    | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
     | `plugin-sdk/account-core` | Multi-account config/action-gate helpers, default-account fallback helpers |
     | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, account-id normalization helpers |
     | `plugin-sdk/account-resolution` | Account lookup + default-fallback helpers |

docs/plugins/sdk-setup.md

@@ -296,7 +296,7 @@ For hot setup-only paths, prefer the narrow setup helper seams over the broader
 | ---------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `plugin-sdk/setup-runtime`         | setup-time runtime helpers that stay available in `setupEntry` / deferred channel startup | `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
 | `plugin-sdk/setup-adapter-runtime` | environment-aware account setup adapters                                                  | `createEnvPatchedAccountSetupAdapter`                                                                                                                                        |
-| `plugin-sdk/setup-tools`           | setup/install CLI/archive/docs helpers                                                    | `formatCliCommand`, `detectBinary`, `extractArchive`, `formatDocsLink`                                                                                                       |
+| `plugin-sdk/setup-tools`           | setup/install CLI/archive/docs helpers                                                    | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR`                                                                |
 
 Use the broader `plugin-sdk/setup` seam when you want the full shared setup
 toolbox, including config-patch helpers such as
@@ -444,6 +444,29 @@ const setupSurface = createOptionalChannelSetupSurface({
 // Returns { setupAdapter, setupWizard }
 ```
 
+`plugin-sdk/channel-setup` also exposes the lower-level
+`createOptionalChannelSetupAdapter(...)` and
+`createOptionalChannelSetupWizard(...)` builders when you only need one half of
+that optional-install surface.
+
+The generated optional adapter/wizard fail closed on real config writes. They
+reuse one install-required message across `validateInput`,
+`applyAccountConfig`, and `finalize`, and append a docs link when `docsPath` is
+set.
+
+For binary-backed setup UIs, prefer the shared delegated helpers instead of
+copying the same binary/status glue into every channel:
+
+- `createDetectedBinaryStatus(...)` for status blocks that vary only by labels,
+  hints, scores, and binary detection
+- `createCliPathTextInput(...)` for path-backed text inputs
+- `createDelegatedSetupWizardStatusResolvers(...)`,
+  `createDelegatedPrepare(...)`, `createDelegatedFinalize(...)`, and
+  `createDelegatedResolveConfigured(...)` when `setupEntry` needs to forward to
+  a heavier full wizard lazily
+- `createDelegatedTextInputShouldPrompt(...)` when `setupEntry` only needs to
+  delegate a `textInputs[*].shouldPrompt` decision
+
 ## Publishing and installing
 
 **External plugins:** publish to [ClawHub](/tools/clawhub) or npm, then install: