From 8ac8a812f6e6c1727a193a950263305a28778d1c Mon Sep 17 00:00:00 2001
From: anikitenko <alexvwan@gmail.com>
Date: Sun, 19 Apr 2026 00:44:23 +0300
Subject: [PATCH 1/2] fix(examples): fix 2 test

---
 Assistant.md                                  |  485 +++
 CHANGELOG.md                                  |   46 +
 README.md                                     |  179 +-
 bin/fdo-sdk.js                                |   37 +
 docs/API_STABILITY.md                         |   32 +
 docs/ARCHITECTURE.md                          |    7 +-
 docs/EXAMPLES_AND_FIXTURES.md                 |   26 +
 docs/EXTENSION_POINTS.md                      |    8 +
 docs/HOST_PRIVILEGED_ACTIONS_CONTRACT.md      |   70 +-
 docs/INJECTED_LIBRARIES.md                    |   18 +
 docs/OPERATOR_PLUGIN_PATTERNS.md              |   26 +-
 docs/QUICK_REFERENCE.md                       |    8 +
 docs/RENDER_RUNTIME_CONTRACT.md               |   77 +-
 docs/SAFE_PLUGIN_AUTHORING.md                 |  134 +-
 docs/SHAREPOINT_PROVIDER_HOST_CONTRACT.md     |   92 +
 examples/03-persistence-plugin.ts             |    6 +-
 examples/07-injected-libraries-demo.ts        |   46 +-
 examples/08-privileged-actions-plugin.ts      |   17 +-
 examples/09-operator-plugin.ts                |   15 +-
 examples/10-system-file-plugin.ts             |   28 +-
 .../11-hosts-manager-plugin/HostsLogic.ts     |   47 +
 examples/11-hosts-manager-plugin/index.ts     |  447 ++
 .../11-hosts-manager-plugin/styles/style.css  |  341 ++
 examples/12-git-operations-plugin.ts          | 3792 +++++++++++++++++
 examples/13-service-content-hub-plugin.ts     | 2509 +++++++++++
 examples/README.md                            |   92 +-
 .../operator-custom-tool-plugin.fixture.ts    |   22 +-
 .../operator-kubernetes-plugin.fixture.ts     |   22 +-
 .../operator-terraform-plugin.fixture.ts      |   22 +-
 examples/fixtures/storage-plugin.fixture.ts   |    6 +-
 package.json                                  |    6 +
 scripts/fdo-sdk-migrate.mjs                   |  236 +
 scripts/verify-docs.mjs                       |  183 +-
 src/DOMButton.ts                              |   23 +-
 src/FDOInterface.ts                           |   12 +-
 src/PluginRegistry.ts                         |   47 +-
 src/index.ts                                  |   77 +-
 src/types.ts                                  |  329 ++
 src/utils/aiTooling.ts                        |   41 +
 src/utils/capabilities.ts                     |  386 +-
 src/utils/contracts.ts                        |   22 +
 src/utils/diagnosticTemplates.ts              |  157 +
 src/utils/editorSupport.ts                    |  126 +
 src/utils/fixtureRuntimeMatrix.ts             |  183 +
 src/utils/handshake.ts                        |  169 +
 src/utils/migrationCodemod.ts                 |  133 +
 src/utils/pluginDoctor.ts                     |  338 ++
 src/utils/privilegedResponses.ts              |   93 +-
 src/utils/privilegedTransport.ts              |   79 +
 src/utils/renderOnLoad.ts                     |  399 ++
 src/utils/storageTooling.ts                   |   38 +
 src/version.ts                                |   20 +
 tests/DOMButton.test.ts                       |   15 +
 tests/PluginRegistry.test.ts                  |   21 +-
 tests/contracts.test.ts                       |   38 +-
 tests/examples.service-content-hub.test.ts    |  359 ++
 tests/examples.system-file.test.ts            |   26 +
 tests/index.test.ts                           |   72 +-
 tests/utils/capabilities.test.ts              |  144 +-
 tests/utils/editorSupport.test.ts             |   86 +
 tests/utils/fixtureRuntimeMatrix.test.ts      |   49 +
 tests/utils/handshake.test.ts                 |   97 +
 tests/utils/migrationCodemod.test.ts          |   57 +
 tests/utils/pluginDoctor.test.ts              |  168 +
 tests/utils/pluginDoctorPanel.test.ts         |   98 +
 tests/utils/privilegedResponses.test.ts       |   46 +
 tests/utils/privilegedTransport.test.ts       |   95 +
 tests/utils/renderOnLoad.test.ts              |  199 +
 tests/utils/storageTooling.test.ts            |   25 +
 webpack.config.cjs                            |    5 +
 70 files changed, 13258 insertions(+), 96 deletions(-)
 create mode 100644 Assistant.md
 create mode 100755 bin/fdo-sdk.js
 create mode 100644 docs/SHAREPOINT_PROVIDER_HOST_CONTRACT.md
 create mode 100644 examples/11-hosts-manager-plugin/HostsLogic.ts
 create mode 100644 examples/11-hosts-manager-plugin/index.ts
 create mode 100644 examples/11-hosts-manager-plugin/styles/style.css
 create mode 100644 examples/12-git-operations-plugin.ts
 create mode 100644 examples/13-service-content-hub-plugin.ts
 create mode 100644 scripts/fdo-sdk-migrate.mjs
 create mode 100644 src/utils/aiTooling.ts
 create mode 100644 src/utils/diagnosticTemplates.ts
 create mode 100644 src/utils/editorSupport.ts
 create mode 100644 src/utils/fixtureRuntimeMatrix.ts
 create mode 100644 src/utils/handshake.ts
 create mode 100644 src/utils/migrationCodemod.ts
 create mode 100644 src/utils/pluginDoctor.ts
 create mode 100644 src/utils/renderOnLoad.ts
 create mode 100644 src/utils/storageTooling.ts
 create mode 100644 src/version.ts
 create mode 100644 tests/examples.service-content-hub.test.ts
 create mode 100644 tests/examples.system-file.test.ts
 create mode 100644 tests/utils/editorSupport.test.ts
 create mode 100644 tests/utils/fixtureRuntimeMatrix.test.ts
 create mode 100644 tests/utils/handshake.test.ts
 create mode 100644 tests/utils/migrationCodemod.test.ts
 create mode 100644 tests/utils/pluginDoctor.test.ts
 create mode 100644 tests/utils/pluginDoctorPanel.test.ts
 create mode 100644 tests/utils/renderOnLoad.test.ts
 create mode 100644 tests/utils/storageTooling.test.ts

diff --git a/Assistant.md b/Assistant.md
new file mode 100644
index 0000000..15ce2bb
--- /dev/null
+++ b/Assistant.md
@@ -0,0 +1,485 @@
+# Assistant Guide
+
+This file is a concise, assistant-facing guide for working with `@anikitenko/fdo-sdk`.
+It is intended for Mintlify or other docs surfaces that need one high-signal overview instead of many separate internal documents.
+
+## What This SDK Is
+
+`@anikitenko/fdo-sdk` is an SDK for building FDO desktop application plugins.
+
+The SDK spans two runtimes:
+
+- Backend/plugin runtime
+  - plugin class lifecycle
+  - handler registration
+  - storage
+  - logging
+  - host IPC
+- Iframe UI runtime
+  - UI returned by `render()`
+  - browser DOM access
+  - host-injected helpers and UI libraries
+  - sandboxed iframe execution managed by FDO
+
+The most important rule is: plugin backend logic and plugin UI logic do not run in the same environment.
+
+## Core Mental Model
+
+Treat `render()` output as UI source for the FDO iframe render pipeline, not as arbitrary raw HTML inserted directly into the host page.
+
+That means:
+
+- `render()` must synchronously return a string
+- `renderOnLoad()` may synchronously return:
+  - a string
+  - a function
+  - a `defineRenderOnLoad(...)` payload
+- FDO serializes and transports these pieces separately
+- UI code runs later inside a sandboxed iframe
+
+If you are generating UI with SDK DOM helpers and expect helper-generated styles to work, you must wrap the final helper output with `renderHTML(...)`.
+
+## Start Here
+
+Recommended order for understanding and building plugins:
+
+1. Read `README.md`
+2. Read `docs/RENDER_RUNTIME_CONTRACT.md`
+3. Read `docs/SAFE_PLUGIN_AUTHORING.md`
+4. Read `docs/EXTENSION_POINTS.md`
+5. Study `examples/fixtures/minimal-plugin.fixture.ts`
+6. Then move to numbered examples in `examples/`
+
+## Minimal Plugin Shape
+
+Every plugin should provide:
+
+- `metadata`
+- `init()`
+- `render()`
+
+Typical shape:
+
+```ts
+import { FDO_SDK, FDOInterface, PluginMetadata } from "@anikitenko/fdo-sdk";
+
+export default class MyPlugin extends FDO_SDK implements FDOInterface {
+  private readonly _metadata: PluginMetadata = {
+    name: "My Plugin",
+    version: "1.0.0",
+    author: "Your Name",
+    description: "Plugin description",
+    icon: "cog",
+  };
+
+  get metadata(): PluginMetadata {
+    return this._metadata;
+  }
+
+  init(): void {
+    this.info("plugin initialized");
+  }
+
+  render(): string {
+    return `<div>Hello World</div>`;
+  }
+}
+```
+
+## Metadata Rules
+
+Plugin metadata is part of the host contract.
+
+Rules:
+
+- define full metadata: `name`, `version`, `author`, `description`, `icon`
+- prefer a stable `metadata.id` if your host/plugin flow supports it
+- `metadata.icon` must be a valid BlueprintJS v6 icon name
+
+## Backend Runtime Rules
+
+Use backend runtime for:
+
+- `init()`
+- registering handlers
+- stores
+- logging
+- diagnostics
+- host-mediated privileged actions
+
+Do not assume browser-only globals or injected UI libraries exist here.
+
+Do not use iframe-specific APIs in backend/bootstrap paths.
+
+## Iframe UI Runtime Rules
+
+Use iframe runtime for:
+
+- DOM access
+- event binding
+- `window.createBackendReq(...)`
+- host-injected helpers
+- UI libraries injected by FDO
+
+Common helpers available in iframe runtime:
+
+- `window.createBackendReq(...)`
+- `window.waitForElement(...)`
+- `window.executeInjectedScript(...)`
+- `window.addGlobalEventListener(...)`
+- `window.removeGlobalEventListener(...)`
+- `window.applyClassToSelector(...)`
+
+Common injected libraries:
+
+- Notyf
+- Highlight.js
+- ACE
+- Split Grid
+- FontAwesome
+- Pure CSS
+
+Do not assume these libraries exist in backend runtime or failure/bootstrap paths.
+
+## Safe Markup Rules
+
+The iframe render pipeline is JSX-like and stricter than “whatever a browser would parse.”
+
+Important rules:
+
+- prefer JSX-safe void tags like `<br />`
+- avoid inline `<style>` blocks in `render()`
+- escape literal `{` and `}` in code samples
+- avoid embedding raw JSON or object literals directly in JSX-visible markup
+- avoid rendering guard-sensitive runtime tokens in display text when plain text works
+
+For untrusted or user-provided text:
+
+- use `DOMText` helpers
+- do not pass untrusted strings as raw child markup into generic DOM helpers
+
+## DOM Helper Rules
+
+DOM helpers accept compatibility aliases such as:
+
+- `className`
+- `htmlFor`
+- `readOnly`
+
+But final output is normalized to native HTML attributes:
+
+- `class`
+- `for`
+- `readonly`
+
+When both are provided, native HTML form wins.
+
+If helper-generated styling is expected, this is mandatory:
+
+```ts
+return semantic.renderHTML(content);
+```
+
+## Recommended `renderOnLoad()` Pattern
+
+Prefer `defineRenderOnLoadActions(...)` for complex UI wiring.
+
+Why:
+
+- typed handler map
+- declarative bindings
+- better failure behavior
+- easier editor/template integration
+
+Recommended baseline:
+
+```ts
+renderOnLoad() {
+  return defineRenderOnLoadActions({
+    handlers: {
+      runAction: async () => {
+        await window.createBackendReq("UI_MESSAGE", {
+          handler: "plugin.runAction",
+          content: {},
+        });
+      },
+    },
+    bindings: [
+      { selector: "#run", event: "click", handler: "runAction", required: true, preventDefault: true },
+    ],
+    strict: true,
+    language: "typescript",
+  });
+}
+```
+
+## Handlers
+
+Use `PluginRegistry.registerHandler(name, handler)` for UI-to-backend calls.
+
+Good handler properties:
+
+- stable names
+- explicit payload expectations
+- boundary validation when needed
+- deterministic error handling
+
+Avoid:
+
+- hidden handler side effects
+- ad hoc message shape drift
+- relying on tests as the only source of contract truth
+
+## Storage
+
+Supported store patterns:
+
+- `PluginRegistry.useStore("default")`
+  - plugin-scoped in-memory store
+- `PluginRegistry.useStore("json")`
+  - plugin-scoped persistent store
+  - requires configured storage root
+  - requires capability grants
+
+JSON store requirements:
+
+- storage root configured via `PluginRegistry.configureStorage({ rootDir })` or `FDO_SDK_STORAGE_ROOT`
+- host-granted capabilities:
+  - `storage`
+  - `storage.json`
+
+Important safety rule:
+
+- do not call `PluginRegistry.useStore(...)` in class field initializers
+- acquire stores lazily or inside `init()`/handlers
+
+Recommended lazy pattern:
+
+```ts
+private sessionStore?: StoreType;
+
+private getSessionStore(): StoreType {
+  if (!this.sessionStore) {
+    this.sessionStore = PluginRegistry.useStore("default");
+  }
+  return this.sessionStore;
+}
+```
+
+## Logging And Diagnostics
+
+Preferred logging APIs on `FDO_SDK`:
+
+- `this.log(...)`
+- `this.info(...)`
+- `this.warn(...)`
+- `this.debug(...)`
+- `this.verbose(...)`
+- `this.silly(...)`
+- `this.error(error)`
+- `this.event(name, payload)`
+
+Use structured logs and correlation IDs for handler and privileged-action flows.
+
+## Capability Model
+
+Privileged features are capability-gated by the host.
+Plugins may declare intent, but host grants are authoritative.
+
+Common capability families:
+
+- `storage`
+- `storage.json`
+- `system.network`
+- `system.network.https`
+- `system.network.http`
+- `system.network.websocket`
+- `system.network.tcp`
+- `system.network.udp`
+- `system.network.dns`
+- `system.network.scope.<scope-id>`
+- `system.clipboard.read`
+- `system.clipboard.write`
+- `system.hosts.write`
+- `system.fs.scope.<scope-id>`
+- `system.process.exec`
+- `system.process.scope.<scope-id>`
+- `sudo.prompt`
+
+Best practice:
+
+- implement `declareCapabilities()`
+- still use runtime capability checks for actual authorization
+
+## Privileged Actions
+
+Host-mediated privileged actions are the supported path for operations outside normal plugin boundaries.
+
+Current action families:
+
+- `system.clipboard.read`
+- `system.clipboard.write`
+- `system.hosts.write`
+- `system.fs.mutate`
+- `system.process.exec`
+- `system.workflow.run`
+
+Preferred SDK helpers:
+
+- `validateHostPrivilegedActionRequest(...)`
+- `requestPrivilegedAction(...)`
+- `requestPrivilegedActionFromEnvelope(...)`
+- `formatPrivilegedActionError(...)`
+- `createClipboardReadRequest(...)`
+- `createClipboardWriteRequest(...)`
+- `createFilesystemMutateActionRequest(...)`
+- `createProcessExecActionRequest(...)`
+
+Recommended response envelope:
+
+```ts
+type PrivilegedActionResponse =
+  | { ok: true; correlationId: string; result?: unknown }
+  | { ok: false; correlationId: string; error: string; code?: string };
+```
+
+Do not show only raw `response.error`.
+Use `formatPrivilegedActionError(...)` so users see:
+
+- correlation ID
+- code
+- stderr/stdout when present
+- exit code
+- command/cwd when present
+
+## Extension Points
+
+Supported extension points:
+
+- lifecycle methods
+  - `init()`
+  - `render()`
+  - `renderOnLoad()`
+- `PluginRegistry.registerHandler(...)`
+- `PluginRegistry.useStore(...)`
+- `PluginRegistry.registerStore(...)`
+- `QuickActionMixin`
+- `SidePanelMixin`
+- DOM helper modules
+
+Avoid depending on:
+
+- private registry internals
+- communicator internals
+- `_`-prefixed store internals
+- undocumented host implementation details
+
+## Anti-Patterns
+
+Avoid these:
+
+- using iframe-only globals in backend code
+- doing heavy work in `render()`
+- constructor-driven host/runtime side effects
+- calling stores too early in field initializers
+- assuming JSON storage exists without root config
+- depending on undocumented internals as public API
+- embedding unsafe raw user text into generated markup
+
+## Examples
+
+Recommended examples and fixtures:
+
+- `examples/fixtures/minimal-plugin.fixture.ts`
+- `examples/01-basic-plugin.ts`
+- `examples/05-advanced-dom-plugin.ts`
+- `examples/08-privileged-actions-plugin.ts`
+- `examples/09-operator-plugin.ts`
+- `examples/10-system-file-plugin.ts`
+
+Production-oriented fixtures:
+
+- `examples/fixtures/operator-kubernetes-plugin.fixture.ts`
+- `examples/fixtures/operator-terraform-plugin.fixture.ts`
+- `examples/fixtures/operator-custom-tool-plugin.fixture.ts`
+
+## SharePoint And Connector Example
+
+Example 13 is a production-oriented connector example.
+
+Important architectural split:
+
+- Host is transport/session infrastructure
+- Plugin is responsible for provider-specific parsing and UX
+
+For connector-style plugins, the practical rule is:
+
+- host owns session storage and request execution
+- plugin interprets provider responses
+- plugin decides pending/authenticated UI state
+- plugin explicitly persists credentials/session auth into host
+- host remains API-agnostic
+
+The example uses generic broker concepts such as:
+
+- auth broker
+- content broker
+- browser broker
+- session request bridge
+
+Do not hardcode service-specific logic into the host if it belongs to plugin-owned provider behavior.
+
+## Security Model
+
+Key security expectations:
+
+- plugin UI runs in a sandboxed iframe
+- capability grants are host-managed
+- privileged actions are explicit and validated
+- network access is capability-gated and scope-gated
+- host/plugin boundaries should stay explicit
+
+Practical safety rule:
+
+- prefer explicit contracts over convenience inference
+- boundary code should not silently reinterpret provider-specific payloads when plugin can provide explicit state
+
+## API Stability
+
+Use documented contracts as primary sources:
+
+- `README.md`
+- `docs/ARCHITECTURE.md`
+- `docs/RENDER_RUNTIME_CONTRACT.md`
+- `docs/SAFE_PLUGIN_AUTHORING.md`
+- `docs/EXTENSION_POINTS.md`
+- `docs/HOST_PRIVILEGED_ACTIONS_CONTRACT.md`
+- `docs/API_STABILITY.md`
+
+Do not infer public SDK guarantees from internal tests or host implementation details alone.
+
+## Assistant Behavior Guidance
+
+When helping users with this SDK:
+
+- distinguish backend runtime from iframe runtime early
+- prefer fixture-first guidance for new plugin authors
+- recommend `defineRenderOnLoadActions(...)` for UI event wiring
+- recommend host-mediated privileged APIs instead of ad hoc shell/filesystem escape patterns
+- recommend capability declarations plus runtime checks
+- keep host generic and move provider-specific behavior into plugins
+- treat `renderHTML(...)` as mandatory whenever styled DOM helper output is used
+- avoid telling users to rely on arbitrary third-party imports in iframe runtime
+
+## Source Documents
+
+This file is derived from:
+
+- `README.md`
+- `docs/ARCHITECTURE.md`
+- `docs/RENDER_RUNTIME_CONTRACT.md`
+- `docs/SAFE_PLUGIN_AUTHORING.md`
+- `docs/HOST_PRIVILEGED_ACTIONS_CONTRACT.md`
+- `docs/EXTENSION_POINTS.md`
+- `docs/QUICK_REFERENCE.md`
+- `docs/SHAREPOINT_PROVIDER_HOST_CONTRACT.md`
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ae247a0..6f5f3c1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -139,6 +139,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - Release automation is managed by Release Please (`.github/workflows/release-please.yml`), including automated versioning and changelog updates on release PRs.
+- Added first-class network capability helpers:
+  - `createNetworkScopeCapability(scopeId)`
+  - `requireNetworkScopeCapability(scopeId, action)`
+  - `createNetworkCapabilityBundle({ transports, scopeId })` object signature (array signature remains supported for backward compatibility)
+- Added first-class render-on-load authoring helpers:
+  - `defineRenderOnLoad(source, options?)`
+  - `defineRenderOnLoadActions({ handlers, bindings, ... })`
+  - `createRenderOnLoadActionsSource({ handlers, bindings, ... })`
+  - `resolveRenderOnLoadSource(output)`
+  - `getRenderOnLoadMonacoTypeDefinitions()`
+  - `getRenderOnLoadMonacoHints()`
+- `renderOnLoad()` now supports synchronous string, function, or `defineRenderOnLoad(...)` module payloads, normalized by SDK transport serialization.
+- Updated plugin-init capability validation to accept `system.network.scope.<scope-id>` IDs.
+- Added `extractPrivilegedActionRequest(...)` to safely unwrap privileged requests from direct request objects, backend envelopes, or `UI_MESSAGE` success payloads shaped like `{ ok, result: { correlationId, request } }`.
+- Added `requestPrivilegedActionFromEnvelope(...)` as the canonical privileged transport pipeline helper (`envelope -> extract -> request -> formatted error`), with optional `throwOnError` mode.
+- Updated low-level privileged examples and operator fixtures to extract the validated request object before calling the raw `requestPrivilegedAction` host bridge.
+- Deprecated passing full backend envelope objects directly into the raw `requestPrivilegedAction` bridge. Migration snippet:
+
+```ts
+const envelopeOrRequest = await window.createBackendReq("UI_MESSAGE", {
+  handler: "plugin.buildPrivilegedRequest",
+  content: {},
+});
+
+const requestPayload = extractPrivilegedActionRequest(envelopeOrRequest);
+const response = await window.createBackendReq("requestPrivilegedAction", requestPayload);
+```
+- Added `runCapabilityPreflight(...)` for deterministic declared-vs-granted capability diagnostics and remediation generation, and integrated declared-capability preflight into `PluginRegistry` diagnostics/init logging.
+- Added `createPluginDoctorReport(...)` for host-side structured diagnostics triage (severity findings, remediation strings, and normalized status).
+- Added docs snippet CI verification support in `verify:docs`:
+  - fenced snippets tagged with `verify` are compile-checked
+  - fenced snippets tagged with `verify runtime` also run a sandbox runtime smoke check
+- Added SDK/FDO handshake contract helpers:
+  - `getSdkHandshake()` with `sdkVersion`, `apiVersion`, `capabilitySchemaVersion`, and `featureFlags`
+  - `getSdkFeatureFlags()` for feature-flag-only checks
+- Included handshake payload in diagnostics (`PluginRegistry.getDiagnostics()`), so hosts can gate compatibility without ad hoc version probing.
+- Added code-based remediation template helpers for host “copy exact fix” UX:
+  - `getDiagnosticFixTemplate(code)`
+  - `listDiagnosticFixTemplates()`
+  - `formatDiagnosticExactFix(code)`
+- Added migration codemod command surfaces for legacy plugin updates:
+  - `fdo-sdk migrate ...` (bin command)
+  - `npm run migrate -- ...` (repo script)
+- Added programmatic codemod helper `applySdkMigrationCodemod(source)` and migration rules for:
+  - legacy privileged envelope extraction fallback chain
+  - deprecated `PluginRegistry.configureCapabilityPolicy(...)`
 
 ## [1.0.19] - 2025-11-11
 
diff --git a/README.md b/README.md
index ccf8f56..c79023b 100644
--- a/README.md
+++ b/README.md
@@ -22,7 +22,10 @@ The supported lifecycle contract is synchronous:
 
 - `init()` performs setup
 - `render()` returns a UI string
-- `renderOnLoad()` optionally returns an on-load string
+- `renderOnLoad()` optionally returns:
+  - an on-load string source
+  - an on-load function (`() => void`) serialized by SDK
+  - a `defineRenderOnLoad(...)` module payload
 - the SDK serializes those values for host transport separately
 
 DOM helper rule:
@@ -42,6 +45,8 @@ Further documentation:
 - safe authoring guide: [docs/SAFE_PLUGIN_AUTHORING.md](./docs/SAFE_PLUGIN_AUTHORING.md)
 - operator plugin guidance: [docs/OPERATOR_PLUGIN_PATTERNS.md](./docs/OPERATOR_PLUGIN_PATTERNS.md)
 - examples and fixtures guide: [docs/EXAMPLES_AND_FIXTURES.md](./docs/EXAMPLES_AND_FIXTURES.md)
+- SharePoint/generic connector host contract: [docs/SHAREPOINT_PROVIDER_HOST_CONTRACT.md](./docs/SHAREPOINT_PROVIDER_HOST_CONTRACT.md)
+- plugin gap register: [docs/PLUGIN_DEVELOPMENT_GAP_REGISTER.md](docs-local/PLUGIN_DEVELOPMENT_GAP_REGISTER.md)
 - API stability policy: [docs/API_STABILITY.md](./docs/API_STABILITY.md)
 
 ## Features
@@ -165,7 +170,16 @@ The SDK uses explicit host-granted capabilities from `PLUGIN_INIT.content.capabi
 
 Core capabilities:
 
-- `storage.json` - required for `PluginRegistry.useStore("json")`
+- `storage` - base capability family for plugin-managed persistent storage backends
+- `storage.json` - JSON backend leaf capability, required with `storage` for `PluginRegistry.useStore("json")`
+- `system.network` - base capability family for runtime network access
+- `system.network.https` - required for outbound HTTPS requests (`fetch("https://...")`)
+- `system.network.http` - required for outbound plaintext HTTP requests (`fetch("http://...")`)
+- `system.network.websocket` - required for outbound `WebSocket` connections
+- `system.network.tcp` - required for raw TCP socket modules
+- `system.network.udp` - required for raw UDP socket modules
+- `system.network.dns` - required for DNS modules/APIs
+- `system.network.scope.<scope-id>` - host-defined destination scope required together with network base + transport capabilities
 - `sudo.prompt` - required for `runWithSudo(...)`
 - `system.clipboard.read` - required for host-mediated clipboard reads
 - `system.clipboard.write` - required for host-mediated clipboard writes
@@ -193,18 +207,49 @@ Public helpers exported from root package:
 - `createProcessExecActionRequest(...)`
 - `createProcessScopeCapability(...)`
 - `createPrivilegedActionBackendRequest(...)`
+- `extractPrivilegedActionRequest(...)`
 - `requestPrivilegedAction(...)`
+- `getSdkHandshake(...)`
+- `getSdkFeatureFlags(...)`
+- `evaluateSdkHandshakeCompatibility(...)`
+- `isSdkHandshakeCompatible(...)`
+- `createPluginDoctorReport(...)`
+- `createPluginDoctorPanelModel(...)`
+- `getFixtureRuntimeMatrix(...)`
+- `listFixtureRuntimeMatrixCases(...)`
+- `getFixtureRuntimeMatrixCase(...)`
+- `getDiagnosticFixTemplate(...)`
+- `listDiagnosticFixTemplates(...)`
+- `formatDiagnosticExactFix(...)`
+- `applySdkMigrationCodemod(...)`
+- `defineRenderOnLoad(...)`
+- `defineRenderOnLoadActions(...)`
+- `listRenderOnLoadTemplates(...)`
+- `getRenderOnLoadTemplate(...)`
+- `createRenderOnLoadActionsSource(...)`
+- `resolveRenderOnLoadSource(...)`
+- `getRenderOnLoadMonacoTypeDefinitions(...)`
+- `getRenderOnLoadMonacoHints(...)`
+- `formatPrivilegedActionError(...)`
+- `getInlinePrivilegedActionErrorFormatterSource(...)`
 - `createClipboardReadRequest(...)`
 - `createClipboardWriteRequest(...)`
 - `requestClipboardRead(...)`
 - `requestClipboardWrite(...)`
+- `createStorageCapabilityPreset(...)`
+- `getStorageCapabilityPreset(...)`
+- `listStorageCapabilityPresets(...)`
 - `createScopedProcessExecActionRequest(...)`
 - `requestScopedProcessExec(...)`
 - `createProcessCapabilityBundle(...)`
+- `createNetworkCapabilityBundle(...)`
+- `createNetworkScopeCapability(...)`
+- `createStorageCapabilityBundle(...)`
 - `createWorkflowCapabilityBundle(...)`
 - `createFilesystemCapabilityBundle(...)`
 - `describeCapability(...)`
 - `parseMissingCapabilityError(...)`
+- `requireNetworkScopeCapability(...)`
 - `getOperatorToolPreset(...)`
 - `listOperatorToolPresets(...)`
 - `createOperatorToolCapabilityPreset(...)`
@@ -331,19 +376,91 @@ Plugin identity is still attached in structured log metadata (`pluginId`, `compo
 - The SDK exposes a reserved diagnostics handler: `PluginRegistry.DIAGNOSTICS_HANDLER` (`"__sdk.getDiagnostics"`).
 - Hosts can query runtime health/capabilities/notifications via a `UI_MESSAGE` request without adding custom plugin handlers.
 - Diagnostics include capability grant and usage/denial counters for permission auditing.
+- Diagnostics also include a handshake contract (`sdkVersion`, `apiVersion`, `capabilitySchemaVersion`, `featureFlags`) for host compatibility gating.
+- For deterministic compatibility gating, use `evaluateSdkHandshakeCompatibility(diagnostics.handshake, expectations)` before enabling host features that depend on specific SDK capability schema or feature flags.
+- For host-side triage UX, use `createPluginDoctorReport(diagnostics)` to get structured findings with severity, remediation, and status (`healthy`, `needs-attention`, `degraded`).
+- For host panel rendering, use `createPluginDoctorPanelModel(report)` to get prioritized findings, section grouping, and exact-fix text (`formatDiagnosticExactFix` integrated).
+- For deterministic “copy exact fix” UX by error code, use `getDiagnosticFixTemplate(code)` or `formatDiagnosticExactFix(code)`.
 
 Example host request payload:
 
-```typescript
-{
+```typescript verify
+const requestEnvelope = {
   message: "UI_MESSAGE",
   content: {
     handler: "__sdk.getDiagnostics",
-    content: { notificationsLimit: 20 }
+    content: { notificationsLimit: 20 },
+  },
+};
+```
+
+Plugin Doctor example:
+
+```typescript verify
+import { createPluginDoctorPanelModel, createPluginDoctorReport } from "@anikitenko/fdo-sdk";
+
+async function loadDoctorReport() {
+  const diagnostics = await window.createBackendReq("UI_MESSAGE", {
+    handler: "__sdk.getDiagnostics",
+    content: { notificationsLimit: 20 },
+  });
+
+  const capabilitySchemaVersion = (diagnostics as any)?.handshake?.capabilitySchemaVersion;
+  if (capabilitySchemaVersion !== "1.0.0") {
+    console.warn("Host/SDK capability schema mismatch", { capabilitySchemaVersion });
   }
+
+  const report = createPluginDoctorReport(diagnostics as any, {
+    includeInfo: true,
+    includeNotificationFindings: true,
+    handshake: {
+      expectedContractVersion: "1.0.0",
+      expectedApiVersion: "1.0.0",
+      expectedCapabilitySchemaVersion: "1.0.0",
+      requiredFeatureFlags: ["diagnosticsHandler", "pluginDoctorReport"],
+    },
+  });
+  return createPluginDoctorPanelModel(report, {
+    maxPrioritizedFindings: 8,
+  });
 }
 ```
 
+## Fixture Runtime Matrix (Host CI)
+
+- The SDK exposes a versioned fixture smoke contract for host CI wiring:
+  - `getFixtureRuntimeMatrix()`
+  - `listFixtureRuntimeMatrixCases()`
+  - `getFixtureRuntimeMatrixCase(id)`
+- Each entry defines the canonical fixture path plus expected smoke probes (`init`, `render`, `renderOnLoad`, `uiMessage` handlers).
+- Use this contract in FDO CI to avoid hardcoded fixture handler lists drifting from SDK fixtures.
+
+Example:
+
+```typescript verify
+import { getFixtureRuntimeMatrix } from "@anikitenko/fdo-sdk";
+
+const matrix = getFixtureRuntimeMatrix();
+for (const fixtureCase of matrix.cases) {
+  console.log(fixtureCase.id, fixtureCase.fixturePath, fixtureCase.probes.uiMessage.length);
+}
+```
+
+## RenderOnLoad Templates
+
+- Use `listRenderOnLoadTemplates()` for host/editor template pickers.
+- Use `getRenderOnLoadTemplate(id)` to load one deterministic template by id.
+- Template entries include `context` (`runtime-source` or `plugin-method`) and `language` to drive editor UX.
+
+```typescript verify
+import { getRenderOnLoadTemplate, listRenderOnLoadTemplates } from "@anikitenko/fdo-sdk";
+
+const templates = listRenderOnLoadTemplates({ context: "plugin-method" });
+const defaultTemplate = getRenderOnLoadTemplate("method-define-render-on-load-actions");
+
+console.log(templates.length, defaultTemplate?.language);
+```
+
 ## Development
 
 ### Building
@@ -369,6 +486,58 @@ npm run test:coverage # Run tests with coverage report
 npm run coverage:open # Open coverage report in browser
 ```
 
+Documentation snippet verification:
+
+- `npm run verify:docs` validates links and banned references
+- fenced code blocks tagged with `verify` are compile-checked
+- fenced code blocks tagged with `verify runtime` also run a minimal sandbox runtime smoke check
+
+### Migration Codemod
+
+Use the SDK migration command to update legacy plugin patterns:
+
+```bash
+npm run migrate -- --target ./examples
+npm run migrate -- --target ./examples --write
+```
+
+Published-package command:
+
+```bash
+fdo-sdk migrate --target ./my-plugin --write
+```
+
+FDO-wrapper command (when the host exposes SDK tooling through `fdo`):
+
+```bash
+fdo sdk migrate --target ./my-plugin --write
+```
+
+Current migration rules include:
+
+- legacy privileged envelope fallback chain to `extractPrivilegedActionRequest(...)`
+- deprecated `PluginRegistry.configureCapabilityPolicy(...)` to `configureCapabilities(...)`
+
+### Migration + Versioning Loop (Required)
+
+Keep migration and versioning in one loop for every behavior-affecting change:
+
+1. Run migration dry-run in the target plugin set:
+   - `npm run migrate -- --target ./examples`
+   - or `fdo sdk migrate --target ./examples`
+2. Apply migrations:
+   - `npm run migrate -- --target ./examples --write`
+   - or `fdo sdk migrate --target ./examples --write`
+3. Validate:
+   - `npm test`
+   - `npm run test:examples`
+   - `npm run verify:docs`
+4. Version correctly:
+   - patch: internal fix, no public behavior change
+   - minor: additive API/behavior or deprecation with migration note
+   - major: breaking contract/removal
+5. Publish and confirm FDO consumes the expected SDK version before final validation.
+
 ### Publishing
 
 The package includes strict verification gates before publishing:
diff --git a/bin/fdo-sdk.js b/bin/fdo-sdk.js
new file mode 100755
index 0000000..0822c53
--- /dev/null
+++ b/bin/fdo-sdk.js
@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+const path = require("node:path");
+const process = require("node:process");
+const { pathToFileURL } = require("node:url");
+
+async function main() {
+    const [, , command, ...args] = process.argv;
+    if (command === "--help" || command === "-h" || !command) {
+        process.stdout.write([
+            "fdo-sdk",
+            "",
+            "Usage:",
+            "  fdo-sdk migrate [--target <path>] [--write]",
+            "",
+            "Commands:",
+            "  migrate   Run SDK migration codemods for plugin/source files.",
+        ].join("\n") + "\n");
+        return;
+    }
+
+    if (command !== "migrate") {
+        throw new Error(`Unknown command "${command}". Run "fdo-sdk --help" for usage.`);
+    }
+
+    const scriptPath = path.resolve(__dirname, "../scripts/fdo-sdk-migrate.mjs");
+    const scriptModule = await import(pathToFileURL(scriptPath).href);
+    if (typeof scriptModule.run !== "function") {
+        throw new Error("Migration script does not export run(...).");
+    }
+    await scriptModule.run(args);
+}
+
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`fdo-sdk command failed: ${message}\n`);
+    process.exit(1);
+});
diff --git a/docs/API_STABILITY.md b/docs/API_STABILITY.md
index b3acde6..4b6d31f 100644
--- a/docs/API_STABILITY.md
+++ b/docs/API_STABILITY.md
@@ -27,6 +27,23 @@ This document defines which SDK surfaces are stable contracts versus internal im
   - `renderOnLoad()`
   - `serializeRender()`
   - `serializeRenderOnLoad()`
+- Render-on-load authoring helpers:
+  - `defineRenderOnLoad(...)`
+  - `resolveRenderOnLoadSource(...)`
+  - `listRenderOnLoadTemplates(...)`
+  - `getRenderOnLoadTemplate(...)`
+  - `getRenderOnLoadMonacoTypeDefinitions(...)`
+  - `getRenderOnLoadMonacoHints(...)`
+- Fixture runtime matrix helpers:
+  - `getFixtureRuntimeMatrix(...)`
+  - `listFixtureRuntimeMatrixCases(...)`
+  - `getFixtureRuntimeMatrixCase(...)`
+- Handshake compatibility helpers:
+  - `evaluateSdkHandshakeCompatibility(...)`
+  - `isSdkHandshakeCompatible(...)`
+- Plugin doctor helpers:
+  - `createPluginDoctorReport(...)`
+  - `createPluginDoctorPanelModel(...)`
 - Optional declared capability surface:
   - `declareCapabilities()`
 - Public plugin contracts:
@@ -76,6 +93,21 @@ This document defines which SDK surfaces are stable contracts versus internal im
 - Internal changes:
   - unrestricted unless they alter documented stable behavior
 
+## Migration And Versioning Loop
+
+Treat migration and semver as one required release loop:
+
+1. Run migration dry-run on real plugin targets:
+   - `fdo sdk migrate --target ./plugins`
+   - or `fdo-sdk migrate --target ./plugins`
+2. Apply codemods (`--write`) and re-run tests/validation.
+3. Choose semver bump by compatibility impact:
+   - patch for non-contract fixes
+   - minor for additive changes/deprecations with migration notes
+   - major for breaking contract changes/removals
+4. Ensure changelog/release notes include explicit migration guidance.
+5. Validate the host (FDO) is running the intended SDK version before sign-off.
+
 ## Guidance For AI Tooling
 
 Treat these files as source-of-truth contracts first:
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 6b440d0..f519f57 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -28,7 +28,8 @@ Primary plugin lifecycle:
   - returns UI source string
   - serialized for host transport via explicit SDK methods
 - `renderOnLoad()`:
-  - optional string payload for UI on-load behavior
+  - optional payload for UI on-load behavior
+  - supported authoring forms: source string, function, or `defineRenderOnLoad(...)` module
 
 Transport helpers:
 
@@ -81,9 +82,11 @@ Store lifecycle hooks are supported:
 
 Runtime permission model:
 
-- privileged SDK features are capability-gated (`storage.json`, `sudo.prompt`, `system.hosts.write`, `system.fs.scope.<scope-id>`, `system.process.exec`, `system.process.scope.<scope-id>`)
+- privileged SDK features are capability-gated (`storage`, `storage.<backend>` such as `storage.json`, `system.network`, `system.network.<transport>` such as `system.network.https`, `sudo.prompt`, `system.hosts.write`, `system.fs.scope.<scope-id>`, `system.process.exec`, `system.process.scope.<scope-id>`)
 - host grants are configured via `PluginRegistry.configureCapabilities(...)` (usually through validated `PLUGIN_INIT` payload)
 - diagnostics include granted capabilities and usage/denial counters for auditing
+- diagnostics also include SDK handshake metadata (`sdkVersion`, `apiVersion`, capability schema version, feature flags) for host compatibility gating
+- hosts should evaluate this handshake contract with `evaluateSdkHandshakeCompatibility(...)` instead of ad hoc version checks
 
 Host-mediated privileged actions:
 
diff --git a/docs/EXAMPLES_AND_FIXTURES.md b/docs/EXAMPLES_AND_FIXTURES.md
index 8f029c7..0349eb6 100644
--- a/docs/EXAMPLES_AND_FIXTURES.md
+++ b/docs/EXAMPLES_AND_FIXTURES.md
@@ -33,6 +33,7 @@ Use these rules for examples, fixtures, and AI-generated plugin scaffolds:
 
 - Keep backend orchestration in plugin methods and registered handlers.
 - Keep `renderOnLoad()` thin and UI-focused.
+- Do not call `PluginRegistry.useStore(...)` in class-field initializers; acquire stores lazily or in `init()` after metadata is available.
 - If `render()` uses styled SDK DOM-helper output, wrap the final helper markup with `renderHTML(...)`.
 - Treat `renderHTML(...)` as mandatory for styled DOM-helper output because it emits the extracted goober CSS alongside the markup.
 - Treat DOM helpers as the preferred SDK pattern for general structured UI.
@@ -62,6 +63,10 @@ const result = await window.createBackendReq("UI_MESSAGE", {
 });
 ```
 
+- If a backend handler returns a privileged-action envelope from `createPrivilegedActionBackendRequest(...)`, extract the validated request object before calling the raw `requestPrivilegedAction` bridge. Prefer `extractPrivilegedActionRequest(envelopeOrRequest)`. If you need fallback compatibility, use `envelope?.result?.request ?? envelope?.request ?? envelope` and keep `envelope?.result?.correlationId ?? envelope?.correlationId` only for diagnostics/fallback display.
+- For non-`ok` privileged responses, format errors with `formatPrivilegedActionError(...)` so users get correlation IDs and host process diagnostics (`stderr`, `stdout`, `exitCode`, command, `cwd`) when available.
+- In `renderOnLoad()` string runtimes, use `getInlinePrivilegedActionErrorFormatterSource()` to inline the same formatter function.
+
 - For known operator tool families, prefer:
   - `createOperatorToolCapabilityPreset(...)`
   - `requestOperatorTool(...)`
@@ -70,6 +75,9 @@ const result = await window.createBackendReq("UI_MESSAGE", {
 - For host-specific or non-curated tools, prefer:
   - `requestScopedProcessExec(...)`
 - For privileged or operator plugins, declare expected capabilities in code via `declareCapabilities()`.
+- AI provider globals should follow one canonical host naming scheme:
+  - assistants list: `globalThis.__FDO_AI_LIST_ASSISTANTS`
+  - AI request: `globalThis.__FDO_AI_REQUEST`
 
 ## Validation Expectations
 
@@ -82,6 +90,23 @@ The examples surface is considered stable only when all of the following stay tr
 - DOM-helper examples that rely on helper-generated styles call `renderHTML(...)`
 - the canonical fixtures remain the primary recommended starting point
 
+## Fixture Runtime Matrix Contract
+
+Use the SDK fixture runtime matrix helpers as the source of truth for host CI smoke coverage:
+
+- `getFixtureRuntimeMatrix()`
+- `listFixtureRuntimeMatrixCases()`
+- `getFixtureRuntimeMatrixCase(id)`
+
+The contract is versioned and lists:
+
+- canonical fixture path
+- required lifecycle probes (`init`, `render`, `renderOnLoad`)
+- canonical `UI_MESSAGE` handler probes
+- required capabilities when relevant (for example storage/operator fixtures)
+
+Host CI should consume this matrix instead of hardcoding fixture handler IDs or capability expectations.
+
 ## Canonical Operator Patterns
 
 For operator plugins, the recommended order is:
@@ -101,6 +126,7 @@ These are the public guides that should stay stable for generated docs sites:
 
 - [SAFE_PLUGIN_AUTHORING.md](./SAFE_PLUGIN_AUTHORING.md)
 - [OPERATOR_PLUGIN_PATTERNS.md](./OPERATOR_PLUGIN_PATTERNS.md)
+- [PLUGIN_DEVELOPMENT_GAP_REGISTER.md](../docs-local/PLUGIN_DEVELOPMENT_GAP_REGISTER.md)
 - [RENDER_RUNTIME_CONTRACT.md](./RENDER_RUNTIME_CONTRACT.md)
 - [INJECTED_LIBRARIES.md](./INJECTED_LIBRARIES.md)
 - [API_STABILITY.md](./API_STABILITY.md)
diff --git a/docs/EXTENSION_POINTS.md b/docs/EXTENSION_POINTS.md
index 0d22141..cee2fe1 100644
--- a/docs/EXTENSION_POINTS.md
+++ b/docs/EXTENSION_POINTS.md
@@ -26,6 +26,9 @@ This document defines the supported ways to extend plugins with `@anikitenko/fdo
 
 - `PluginRegistry.useStore("default")` for scoped in-memory state
 - `PluginRegistry.useStore("json")` for scoped persistent state
+  - requires host capability grants: `storage` + `storage.json`
+- `createStorageCapabilityPreset("storageJSON")` for a curated JSON-storage capability preset
+- `createStorageCapabilityBundle("json")` for custom backend-driven storage capability bundle creation
 - `PluginRegistry.registerStore(name, storeOrFactory)` for custom store integrations
 - `PluginRegistry.configureStorage({ rootDir })` for persistent storage root
 - `PluginRegistry.configureCapabilities({ granted })` for host-managed grants to privileged SDK features
@@ -34,11 +37,14 @@ This document defines the supported ways to extend plugins with `@anikitenko/fdo
 
 - `QuickActionMixin` for quick action definitions
 - `SidePanelMixin` for side panel definitions
+- `listRenderOnLoadTemplates(...)` / `getRenderOnLoadTemplate(...)` for deterministic host/editor on-load templates
 
 ### Error Handling
 
 - `@handleError()` for controlled error handling behavior
 - optional `errorUIRenderer` for render fallback UI
+- `formatPrivilegedActionError(response, options?)` for stable privileged-action error messages
+- `getInlinePrivilegedActionErrorFormatterSource()` for `renderOnLoad()` string runtimes
 
 ### Logging And Diagnostics
 
@@ -46,6 +52,8 @@ This document defines the supported ways to extend plugins with `@anikitenko/fdo
 - `this.error(error)` for error logs
 - `this.event(name, payload)` for structured events with correlation IDs
 - `PluginRegistry.DIAGNOSTICS_HANDLER` (`"__sdk.getDiagnostics"`) for host diagnostics requests over `UI_MESSAGE`
+- `createPluginDoctorReport(diagnostics, options?)` for host-side structured triage findings derived from diagnostics
+- `createPluginDoctorPanelModel(report, options?)` for prioritized, sectioned panel-ready findings with exact-fix text
 
 ## Anti-Patterns To Avoid
 
diff --git a/docs/HOST_PRIVILEGED_ACTIONS_CONTRACT.md b/docs/HOST_PRIVILEGED_ACTIONS_CONTRACT.md
index 95cca17..49febd1 100644
--- a/docs/HOST_PRIVILEGED_ACTIONS_CONTRACT.md
+++ b/docs/HOST_PRIVILEGED_ACTIONS_CONTRACT.md
@@ -30,6 +30,8 @@ Validated by SDK helper:
   - `createClipboardWriteRequest(text, reason?)`
   - `requestClipboardRead(reasonOrOptions?, options?)`
   - `requestClipboardWrite(text, reasonOrOptions?, options?)`
+  - `formatPrivilegedActionError(response, options?)`
+  - `getInlinePrivilegedActionErrorFormatterSource()`
 
 ## Request Shape
 
@@ -96,10 +98,25 @@ const response = await requestPrivilegedAction(request, {
 if (response?.ok) {
   // success path
 } else {
-  // deterministic error path with correlationId + error + code
+  const message = formatPrivilegedActionError(response, {
+    context: "Filesystem mutate action failed",
+  });
+  // deterministic error path with correlationId + error + code + process details when present
 }
 ```
 
+For `renderOnLoad()` string runtimes, use the inline-source helper:
+
+```ts
+const formatPrivilegedActionErrorSource = getInlinePrivilegedActionErrorFormatterSource();
+return `
+(() => {
+  const formatPrivilegedActionError = ${formatPrivilegedActionErrorSource};
+  // use formatPrivilegedActionError(response, { context, fallbackCorrelationId })
+})();
+`;
+```
+
 If you need the stable request envelope without sending it yet:
 
 ```ts
@@ -108,6 +125,57 @@ const payload = createPrivilegedActionBackendRequest(request, {
 });
 ```
 
+If your iframe UI fetches that envelope through `UI_MESSAGE`, prefer the canonical pipeline helper:
+
+```ts verify
+import { requestPrivilegedActionFromEnvelope } from "@anikitenko/fdo-sdk";
+
+async function runPrivilegedPipeline() {
+  const envelopeOrRequest = await window.createBackendReq("UI_MESSAGE", {
+    handler: "plugin.buildPrivilegedRequest",
+    content: {},
+  });
+
+  const { response, errorMessage } = await requestPrivilegedActionFromEnvelope(envelopeOrRequest, {
+    context: "Privileged action failed",
+  });
+
+  if (!response.ok) {
+    console.error(errorMessage);
+  }
+}
+```
+
+If you need low-level control, call `extractPrivilegedActionRequest(...)` + `window.createBackendReq("requestPrivilegedAction", requestPayload)` manually.
+
+The helper safely unwraps all currently supported shapes:
+
+```ts
+input.result.request
+input.request
+direct request
+```
+
+Compatibility fallback if you are not using the helper yet:
+
+```ts
+const requestPayload = envelope?.result?.request ?? envelope?.request ?? envelope;
+const correlationId = envelope?.result?.correlationId ?? envelope?.correlationId;
+```
+
+The stable rule for envelope-based handlers is:
+
+- backend handler may return `{ correlationId, request }`
+- `UI_MESSAGE` transport may wrap that again as `{ ok, result: { correlationId, request } }`
+- raw host privileged-action bridge should receive `request`
+- preserve `correlationId` in UI diagnostics separately if you need it for fallback/error display
+
+Deprecated behavior:
+
+- passing the full backend envelope directly into `requestPrivilegedAction` is deprecated
+- this compatibility may exist temporarily in some hosts, but SDK examples should not rely on it
+- a future major release may remove compatibility for forwarding raw envelope objects
+
 ```ts
 {
   action: "system.fs.mutate",
diff --git a/docs/INJECTED_LIBRARIES.md b/docs/INJECTED_LIBRARIES.md
index 451958f..bf96529 100644
--- a/docs/INJECTED_LIBRARIES.md
+++ b/docs/INJECTED_LIBRARIES.md
@@ -211,6 +211,24 @@ console.log(result);
 
 For production plugins, register handlers in `init()` and call them through `UI_MESSAGE`. Do not assume arbitrary handler names are transport types.
 
+If a `UI_MESSAGE` handler returns a privileged-action envelope for `requestPrivilegedAction`, extract the validated request object before sending it to the host bridge:
+
+```javascript
+const envelopeOrRequest = await window.createBackendReq("UI_MESSAGE", {
+    handler: "plugin.buildPrivilegedRequest",
+    content: { /* handler payload */ }
+});
+
+const requestPayload =
+    envelopeOrRequest?.result?.request ??
+    envelopeOrRequest?.request ??
+    envelopeOrRequest;
+
+const response = await window.createBackendReq("requestPrivilegedAction", requestPayload);
+```
+
+Do not pass the entire backend envelope object directly into `requestPrivilegedAction`.
+
 ### `waitForElement(selector, callback, timeout)`
 
 Waits for an element to appear in the DOM.
diff --git a/docs/OPERATOR_PLUGIN_PATTERNS.md b/docs/OPERATOR_PLUGIN_PATTERNS.md
index ffa288f..f6d8da1 100644
--- a/docs/OPERATOR_PLUGIN_PATTERNS.md
+++ b/docs/OPERATOR_PLUGIN_PATTERNS.md
@@ -106,6 +106,7 @@ The host should map each scope to:
 import {
   createPrivilegedActionBackendRequest,
   createProcessExecActionRequest,
+  formatPrivilegedActionError,
   isPrivilegedActionErrorResponse,
   isPrivilegedActionSuccessResponse,
   requestPrivilegedAction,
@@ -130,7 +131,10 @@ const response = await requestPrivilegedAction(request, {
 if (isPrivilegedActionSuccessResponse(response)) {
   // response.result
 } else if (isPrivilegedActionErrorResponse(response)) {
-  // response.error + response.code
+  const message = formatPrivilegedActionError(response, {
+    context: "Operator tool request failed",
+  });
+  // stable correlation id + code + stderr/stdout details when present
 }
 ```
 
@@ -146,6 +150,26 @@ const payload = createPrivilegedActionBackendRequest(request, {
 
 For serialized `renderOnLoad()` handlers, prefer the self-contained `requestPrivilegedAction(...)` helper over manually building `window.createBackendReq("requestPrivilegedAction", ...)`.
 
+If you do use the raw bridge after fetching a backend-built envelope through `UI_MESSAGE`, extract the validated request object first:
+
+```ts
+const envelopeOrRequest = await window.createBackendReq("UI_MESSAGE", {
+  handler: "operator.buildRequest",
+  content: {},
+});
+
+const requestPayload = extractPrivilegedActionRequest(envelopeOrRequest);
+const response = await window.createBackendReq("requestPrivilegedAction", requestPayload);
+```
+
+Do not forward the full backend envelope object directly into the raw host bridge.
+
+For `renderOnLoad()` string runtimes, use:
+
+- `getInlinePrivilegedActionErrorFormatterSource()`
+- assign `const formatPrivilegedActionError = ${formatPrivilegedActionErrorSource};`
+- format all error responses with a stable context and fallback correlation id
+
 ## Capability Presets
 
 For common tool families, prefer SDK capability presets over manually repeating strings:
diff --git a/docs/QUICK_REFERENCE.md b/docs/QUICK_REFERENCE.md
index 619ee43..709268c 100644
--- a/docs/QUICK_REFERENCE.md
+++ b/docs/QUICK_REFERENCE.md
@@ -13,6 +13,14 @@ const response = await window.createBackendReq("UI_MESSAGE", {
   content: { data },
 });
 
+// If handler returns a privileged-action envelope:
+const requestPayload =
+  response?.result?.request ??
+  response?.request ??
+  response;
+const privileged = await window.createBackendReq("requestPrivilegedAction", requestPayload);
+// For non-ok responses, prefer SDK formatPrivilegedActionError(...) in plugin code.
+
 // DOM Utilities
 window.waitForElement('#my-element', (el) => { /* ... */ });
 window.applyClassToSelector('my-class', '#target');
diff --git a/docs/RENDER_RUNTIME_CONTRACT.md b/docs/RENDER_RUNTIME_CONTRACT.md
index 1f3ae12..dffe391 100644
--- a/docs/RENDER_RUNTIME_CONTRACT.md
+++ b/docs/RENDER_RUNTIME_CONTRACT.md
@@ -185,7 +185,10 @@ render(): string {
 The SDK now keeps that separation explicit:
 
 - `render()` returns the plugin's UI string
-- `renderOnLoad()` optionally returns the plugin's on-load script/function string
+- `renderOnLoad()` optionally returns:
+  - source string
+  - function (`() => void`)
+  - `defineRenderOnLoad(...)` module
 - serialization for the host transport is handled by explicit SDK methods rather than by mutating plugin lifecycle methods at construction time
 
 ## Supported Lifecycle Contract
@@ -194,9 +197,79 @@ The supported public contract in the SDK is:
 
 - `init()` performs plugin setup
 - `render()` synchronously returns a string
-- `renderOnLoad()` optionally synchronously returns a string
+- `renderOnLoad()` optionally synchronously returns a string, function, or `defineRenderOnLoad(...)` module
 - `serializeRender()` and `serializeRenderOnLoad()` are transport helpers used by the SDK/host boundary
 
+Recommended authoring pattern:
+
+```ts
+import { defineRenderOnLoad } from "@anikitenko/fdo-sdk";
+
+renderOnLoad() {
+  return defineRenderOnLoad(() => {
+    const button = document.getElementById("run");
+    button?.addEventListener("click", async () => {
+      await window.createBackendReq("UI_MESSAGE", {
+        handler: "plugin.run",
+        content: {},
+      });
+    });
+  }, {
+    language: "typescript",
+    description: "typed on-load handler",
+  });
+}
+```
+
+For production plugins with many UI actions, prefer declarative binding generation instead of hand-written listener wiring strings:
+
+```ts verify
+import { defineRenderOnLoadActions } from "@anikitenko/fdo-sdk";
+
+const onLoadModule = defineRenderOnLoadActions({
+  setup: () => {
+    // optional setup hook before listeners attach
+  },
+  handlers: {
+    runInspect: async () => {
+      await window.createBackendReq("UI_MESSAGE", {
+        handler: "plugin.inspect",
+        content: {},
+      });
+    },
+  },
+  bindings: [
+    { selector: "#inspect-button", event: "click", handler: "runInspect", preventDefault: true },
+  ],
+  language: "typescript",
+  strict: true,
+});
+```
+
+Recommendation: for new plugins, treat `defineRenderOnLoadActions(...)` as the default path for UI event wiring. Use plain `defineRenderOnLoad(...)` when you need heavily custom runtime logic that does not fit selector/event bindings.
+
+For host/editor template pickers, use:
+
+- `listRenderOnLoadTemplates(...)`
+- `getRenderOnLoadTemplate(id)`
+
+Template entries include context (`runtime-source` vs `plugin-method`) and language metadata for deterministic editor UX.
+
+Minimal runtime-check snippet used by docs CI:
+
+```ts verify runtime
+(() => {
+  const marker = { invoked: false };
+  const run = () => {
+    marker.invoked = true;
+  };
+  run();
+  if (!marker.invoked) {
+    throw new Error("runtime marker was not invoked");
+  }
+})();
+```
+
 Plugin authors should override:
 
 - `init()`
diff --git a/docs/SAFE_PLUGIN_AUTHORING.md b/docs/SAFE_PLUGIN_AUTHORING.md
index 4c9411b..6a85cca 100644
--- a/docs/SAFE_PLUGIN_AUTHORING.md
+++ b/docs/SAFE_PLUGIN_AUTHORING.md
@@ -93,6 +93,80 @@ Log destination:
 - in FDO host runtime this is typically `PLUGIN_HOME/logs/`
 - plugin identity is preserved in structured log metadata rather than an extra nested log folder
 
+## Privileged Error Formatting Rule
+
+Do not surface raw `response.error` only. Use the SDK formatter so users see correlation IDs and host process details (`stderr`, `stdout`, `exitCode`, `command`, `cwd`) when present.
+
+Use in normal runtime code:
+
+```ts
+const message = formatPrivilegedActionError(response, {
+  context: "Operator request failed",
+  fallbackCorrelationId: envelopeCorrelationId,
+});
+```
+
+Use in `renderOnLoad()` string runtimes:
+
+```ts
+const formatPrivilegedActionErrorSource = getInlinePrivilegedActionErrorFormatterSource();
+return `
+(() => {
+  const formatPrivilegedActionError = ${formatPrivilegedActionErrorSource};
+  // use formatter for all non-ok privileged responses
+})();
+`;
+```
+
+Preferred authoring form when possible:
+
+```ts
+renderOnLoad() {
+  return defineRenderOnLoad(() => {
+    // browser-only UI logic
+  }, { language: "typescript" });
+}
+```
+
+The SDK normalizes this to string source at transport boundary, so host behavior remains compatible while plugin authoring stays typed.
+
+When `renderOnLoad()` needs multiple UI bindings, prefer `defineRenderOnLoadActions(...)` over hand-written long listener strings. It gives typed handler/binding configuration and consistent runtime guard behavior (selector mismatch, unknown handler id, async handler failure).
+
+Production baseline for new plugins:
+
+- Default to `defineRenderOnLoadActions(...)` for event wiring.
+- Use `strict: true` so missing selectors and unknown handlers fail fast during development.
+- Keep `setup` focused on state/bootstrap only; put user interactions in declarative `bindings`.
+
+```ts
+renderOnLoad() {
+  return defineRenderOnLoadActions({
+    handlers: {
+      runStatus: async () => {
+        await window.createBackendReq("UI_MESSAGE", {
+          handler: "gitOps.v1.runStatus",
+          content: {},
+        });
+      },
+    },
+    bindings: [
+      { selector: "#git-run-status", event: "click", handler: "runStatus", preventDefault: true, required: true },
+    ],
+    strict: true,
+    language: "typescript",
+  });
+}
+```
+
+For host/editor template pickers, use `listRenderOnLoadTemplates(...)` and `getRenderOnLoadTemplate(id)` instead of hardcoded renderOnLoad snippets.
+
+For host UX that needs deterministic “copy exact fix” guidance by error code, use:
+
+- `getDiagnosticFixTemplate(code)`
+- `formatDiagnosticExactFix(code)`
+
+These helpers provide stable remediation templates for common failure codes such as capability denial, process spawn/exit failures, empty backend responses, and handshake compatibility issues.
+
 ## Metadata Rules
 
 - Define full `metadata` (`name`, `version`, `author`, `description`, `icon`)
@@ -109,12 +183,52 @@ Log destination:
 
 If storage root is missing, JSON store requests throw by design.
 
+Initialization order safety (critical):
+
+- Do not call `PluginRegistry.useStore(...)` in class-field initializers.
+- Acquire stores lazily (helper getter) or inside `init()`/handlers after metadata is ready.
+- Reason: some host/runtime validations read plugin metadata during store acquisition. If store calls run before metadata assignment, startup can fail with errors like `Plugin metadata must be an object.` and terminate the plugin process.
+
+Recommended pattern:
+
+```ts
+private sessionStore?: StoreType;
+
+private getSessionStore(): StoreType {
+  if (!this.sessionStore) {
+    this.sessionStore = PluginRegistry.useStore("default");
+  }
+  return this.sessionStore;
+}
+
+init(): void {
+  const store = this.getSessionStore();
+  // use store safely here
+}
+```
+
 ## Capability Grants (Host-Managed)
 
 Privileged SDK features are capability-gated. The host should grant capabilities at init-time through `PLUGIN_INIT.content.capabilities`.
 
+- `storage`:
+  base storage capability family; required with any concrete storage backend capability
 - `storage.json`:
-  required for `PluginRegistry.useStore("json")`
+  JSON backend leaf capability; required with `storage` for `PluginRegistry.useStore("json")`
+- `system.network`:
+  base network capability family; required with concrete network transport capabilities
+- `system.network.https`:
+  required for outbound HTTPS requests (for example `fetch("https://...")`)
+- `system.network.http`:
+  required for outbound plaintext HTTP requests (for example `fetch("http://...")`)
+- `system.network.websocket`:
+  required for outbound `WebSocket` usage
+- `system.network.tcp`:
+  required for raw TCP socket modules/APIs
+- `system.network.udp`:
+  required for raw UDP socket modules/APIs
+- `system.network.dns`:
+  required for DNS modules/APIs
 - `sudo.prompt`:
   required for `runWithSudo(...)`
 - `system.clipboard.read`:
@@ -196,6 +310,7 @@ For capability remediation and diagnostics, the SDK now also provides:
 - `createFilesystemCapabilityBundle(...)`
 - `describeCapability(...)`
 - `parseMissingCapabilityError(...)`
+- `runCapabilityPreflight(...)`
 
 This lets plugin authors and AI tooling distinguish:
 
@@ -214,6 +329,23 @@ declareCapabilities() {
 
 This allows hosts to compare declared capabilities with granted capabilities during preflight, before a user reaches a rare or deep action path.
 
+Recommended explicit preflight pattern in plugin backend code:
+
+```ts
+const declared = this.declareCapabilities();
+const report = runCapabilityPreflight({
+  declared,
+  granted: initCapabilitiesFromHost,
+  action: "initialize plugin runtime",
+});
+
+if (!report.ok) {
+  // surface report.summary + report.remediations in init diagnostics/logs
+}
+```
+
+`PluginRegistry.callInit()` already logs declared-capability preflight diagnostics, but calling `runCapabilityPreflight(...)` directly is useful when you want a deterministic report object for custom UI, telemetry, or AI-assisted remediation.
+
 ## Many-Command Troubleshooting Best Practice
 
 If a plugin needs to run many tool commands, do not default to:
diff --git a/docs/SHAREPOINT_PROVIDER_HOST_CONTRACT.md b/docs/SHAREPOINT_PROVIDER_HOST_CONTRACT.md
new file mode 100644
index 0000000..f341a2d
--- /dev/null
+++ b/docs/SHAREPOINT_PROVIDER_HOST_CONTRACT.md
@@ -0,0 +1,92 @@
+# Connector Broker Host Contract (Example 13)
+
+This document defines the provider-agnostic host contract used by `examples/13-service-content-hub-plugin.ts`.
+Use the same contract for SharePoint, Dropbox, Google Drive, Confluence, and internal APIs.
+
+## Security Model
+
+- Plugin never receives raw OAuth access/refresh tokens.
+- Host owns OAuth, token refresh, token storage, and secret rotation.
+- Plugin receives only opaque `sessionId` and normalized content payloads.
+- Host enforces provider policy and endpoint allowlists before every connector call.
+- Host logs correlation IDs for each auth/content operation.
+
+## Host Globals
+
+Primary generic globals:
+
+- `globalThis.__FDO_AUTH_BROKER`
+- `globalThis.__FDO_CONTENT_BROKER`
+
+Backward-compatible aliases:
+
+- `globalThis.__FDO_CONNECTOR_AUTH`
+- `globalThis.__FDO_CONNECTOR_CONTENT`
+- `globalThis.__FDO_SHAREPOINT_PROVIDER`
+- `globalThis.__FDO_SHAREPOINT`
+
+Optional browser policy broker:
+
+- `globalThis.__FDO_BROWSER_BROKER.open({ url, policy })`
+
+## Auth Broker Contract
+
+```ts
+type AuthBroker = {
+  start(input: { providerId: string; accountHint?: string; endpointUrl?: string }): Promise<{ sessionId: string; accountId?: string }>;
+  refresh(input: { providerId: string; sessionId: string }): Promise<{ sessionId?: string }>;
+  logout(input: { providerId: string; sessionId: string }): Promise<void>;
+};
+```
+
+## Content Broker Contract
+
+```ts
+type ContentBroker = {
+  request(input: {
+    providerId: string;
+    sessionId: string;
+    operation: "list-workspaces" | "list-items" | "search-items" | "create-share-link" | string;
+    endpointUrl?: string;
+    workspaceId?: string;
+    path?: string;
+    query?: string;
+    itemId?: string;
+    scope?: "organization" | "anonymous";
+    type?: "view" | "edit";
+    limit?: number;
+    cursor?: string;
+  }): Promise<{ items?: Item[]; webUrl?: string; nextCursor?: string; page?: { nextCursor?: string } } | Item[]>;
+};
+
+type Item = {
+  id: string;
+  name: string;
+  kind: "site" | "folder" | "file" | "workspace";
+  webUrl: string;
+  parentPath?: string;
+  lastModifiedAt?: string;
+};
+```
+
+## Required Capabilities
+
+- `system.network`
+- `system.network.https`
+- `system.network.scope.external-services`
+- `storage`
+- `storage.json`
+- `system.ai`
+- `system.ai.assistants.list`
+- `system.ai.request`
+- `system.clipboard.write`
+
+## Error Taxonomy (Recommended)
+
+- `AUTH_REQUIRED`
+- `AUTH_TOKEN_EXPIRED`
+- `AUTH_SCOPE_DENIED`
+- `ENDPOINT_URL_INVALID`
+- `PROVIDER_TRANSIENT`
+
+For transient errors (429/5xx/timeouts), host should retry with capped backoff and return a stable user-safe message.
diff --git a/examples/03-persistence-plugin.ts b/examples/03-persistence-plugin.ts
index b2e007a..c5aba05 100644
--- a/examples/03-persistence-plugin.ts
+++ b/examples/03-persistence-plugin.ts
@@ -24,7 +24,7 @@
  * 5. Clear and record session data through explicit UI actions
  */
 
-import { FDO_SDK, FDOInterface, PluginMetadata, PluginRegistry } from "@anikitenko/fdo-sdk";
+import { FDO_SDK, FDOInterface, PluginCapability, PluginMetadata, PluginRegistry } from "@anikitenko/fdo-sdk";
 
 declare global {
   interface Window {
@@ -86,6 +86,10 @@ export default class PersistencePlugin extends FDO_SDK implements FDOInterface {
     return this._metadata;
   }
 
+  declareCapabilities(): PluginCapability[] {
+    return ["storage", "storage.json"];
+  }
+
   /**
    * Initialize the plugin and set up storage.
    * 
diff --git a/examples/07-injected-libraries-demo.ts b/examples/07-injected-libraries-demo.ts
index 0b7b32d..6131862 100644
--- a/examples/07-injected-libraries-demo.ts
+++ b/examples/07-injected-libraries-demo.ts
@@ -12,15 +12,7 @@
  * - This example intentionally uses plain markup so the focus stays on injected globals and iframe runtime behavior
  */
 
-import {
-    createClipboardReadRequest,
-    createClipboardWriteRequest,
-    FDO_SDK,
-    FDOInterface,
-    PluginMetadata,
-    PluginCapability,
-    PluginRegistry,
-} from "@anikitenko/fdo-sdk";
+import { createClipboardReadRequest, createClipboardWriteRequest, FDO_SDK, FDOInterface, getInlinePrivilegedActionErrorFormatterSource, PluginMetadata, PluginCapability, PluginRegistry, extractPrivilegedActionRequest } from "@anikitenko/fdo-sdk";
 
 export default class InjectedLibrariesDemoPlugin extends FDO_SDK implements FDOInterface {
     private readonly _metadata: PluginMetadata = {
@@ -216,9 +208,11 @@ class Plugin extends FDO_SDK &#123;
     }
 
     renderOnLoad(): string {
+        const formatPrivilegedActionErrorSource = getInlinePrivilegedActionErrorFormatterSource();
         return `
             (() => {
                 const output = document.getElementById("helper-output");
+                const formatPrivilegedActionError = ${formatPrivilegedActionErrorSource};
                 const setOutput = (html) => {
                     if (output) {
                         output.innerHTML = html;
@@ -296,21 +290,26 @@ new MyPlugin();\`, 1);
                         const content = editor.getValue();
                         setOutput("Preparing clipboard request...");
                         try {
-                            const request = await window.createBackendReq("UI_MESSAGE", {
+                            const envelopeOrRequest = await window.createBackendReq("UI_MESSAGE", {
                                 handler: "demo.getClipboardWriteRequest",
                                 content: { text: content }
                             });
-                            const response = await window.createBackendReq("requestPrivilegedAction", {
-                                correlationId: \`clipboard-\${Date.now()}\`,
-                                request
-                            });
+                            const requestPayload = extractPrivilegedActionRequest(envelopeOrRequest);
+                            const fallbackCorrelationId = envelopeOrRequest?.result?.correlationId
+                                ?? envelopeOrRequest?.correlationId
+                                ?? "unknown";
+                            const response = await window.createBackendReq("requestPrivilegedAction", requestPayload);
 
                             if (response && response.ok) {
                                 notyf.success("Editor content copied to clipboard.");
                                 setOutput(\`<strong>Clipboard Response:</strong><br /><pre>\${JSON.stringify(response, null, 2)}</pre>\`);
                             } else {
                                 notyf.error("Clipboard write was denied.");
-                                setOutput(\`<strong>Clipboard Error:</strong><br /><pre>\${JSON.stringify(response, null, 2)}</pre>\`);
+                                const message = formatPrivilegedActionError(response, {
+                                    context: "Clipboard write failed",
+                                    fallbackCorrelationId
+                                });
+                                setOutput(\`<strong>Clipboard Error:</strong><br /><pre>\${message}</pre><br /><strong>Raw Response:</strong><br /><pre>\${JSON.stringify(response, null, 2)}</pre>\`);
                             }
                         } catch (error) {
                             const message = error instanceof Error ? error.message : String(error);
@@ -322,21 +321,26 @@ new MyPlugin();\`, 1);
                     bindClick("read-clipboard-btn", async () => {
                         setOutput("Preparing clipboard read request...");
                         try {
-                            const request = await window.createBackendReq("UI_MESSAGE", {
+                            const envelopeOrRequest = await window.createBackendReq("UI_MESSAGE", {
                                 handler: "demo.getClipboardReadRequest",
                                 content: {}
                             });
-                            const response = await window.createBackendReq("requestPrivilegedAction", {
-                                correlationId: \`clipboard-\${Date.now()}\`,
-                                request
-                            });
+                            const requestPayload = extractPrivilegedActionRequest(envelopeOrRequest);
+                            const fallbackCorrelationId = envelopeOrRequest?.result?.correlationId
+                                ?? envelopeOrRequest?.correlationId
+                                ?? "unknown";
+                            const response = await window.createBackendReq("requestPrivilegedAction", requestPayload);
 
                             if (response && response.ok) {
                                 notyf.success("Clipboard content loaded.");
                                 setOutput(\`<strong>Clipboard Read Response:</strong><br /><pre>\${JSON.stringify(response, null, 2)}</pre>\`);
                             } else {
                                 notyf.error("Clipboard read was denied.");
-                                setOutput(\`<strong>Clipboard Read Error:</strong><br /><pre>\${JSON.stringify(response, null, 2)}</pre>\`);
+                                const message = formatPrivilegedActionError(response, {
+                                    context: "Clipboard read failed",
+                                    fallbackCorrelationId
+                                });
+                                setOutput(\`<strong>Clipboard Read Error:</strong><br /><pre>\${message}</pre><br /><strong>Raw Response:</strong><br /><pre>\${JSON.stringify(response, null, 2)}</pre>\`);
                             }
                         } catch (error) {
                             const message = error instanceof Error ? error.message : String(error);
diff --git a/examples/08-privileged-actions-plugin.ts b/examples/08-privileged-actions-plugin.ts
index 90b7bca..a742b51 100644
--- a/examples/08-privileged-actions-plugin.ts
+++ b/examples/08-privileged-actions-plugin.ts
@@ -2,8 +2,10 @@ import {
     createFilesystemMutateActionRequest,
     createFilesystemScopeCapability,
     createPrivilegedActionBackendRequest,
+    extractPrivilegedActionRequest,
     FDOInterface,
     FDO_SDK,
+    getInlinePrivilegedActionErrorFormatterSource,
     PluginCapability,
     PluginRegistry,
     PluginMetadata,
@@ -71,10 +73,12 @@ export class PrivilegedActionsPlugin extends FDO_SDK implements FDOInterface {
     }
 
     renderOnLoad(): string {
+        const formatPrivilegedActionErrorSource = getInlinePrivilegedActionErrorFormatterSource();
         return `
             (() => {
                 const button = document.getElementById("run-privileged-action");
                 const resultBox = document.getElementById("result-box");
+                const formatPrivilegedActionError = ${formatPrivilegedActionErrorSource};
 
                 if (!button || !resultBox) {
                     return;
@@ -96,7 +100,8 @@ export class PrivilegedActionsPlugin extends FDO_SDK implements FDOInterface {
                         });
 
                         const typedEnvelope = envelope;
-                        const response = await window.createBackendReq("requestPrivilegedAction", typedEnvelope);
+                        const requestPayload = extractPrivilegedActionRequest(typedEnvelope);
+                        const response = await window.createBackendReq("requestPrivilegedAction", requestPayload);
 
                         if (response && response.ok) {
                             setResult({
@@ -107,10 +112,16 @@ export class PrivilegedActionsPlugin extends FDO_SDK implements FDOInterface {
                             return;
                         }
 
+                        const fallbackCorrelationId = typedEnvelope?.result?.correlationId
+                            ?? typedEnvelope?.correlationId
+                            ?? "unknown";
                         setResult({
                             status: "error",
-                            correlationId: response?.correlationId ?? typedEnvelope?.correlationId ?? "unknown",
-                            error: response?.error ?? "Unknown host error",
+                            correlationId: response?.correlationId ?? fallbackCorrelationId,
+                            error: formatPrivilegedActionError(response, {
+                                context: "Privileged action failed",
+                                fallbackCorrelationId,
+                            }),
                             code: response?.code ?? "UNKNOWN",
                         });
                     } catch (error) {
diff --git a/examples/09-operator-plugin.ts b/examples/09-operator-plugin.ts
index d26b3bf..d7e536e 100644
--- a/examples/09-operator-plugin.ts
+++ b/examples/09-operator-plugin.ts
@@ -2,8 +2,10 @@ import {
     createOperatorToolActionRequest,
     createOperatorToolCapabilityPreset,
     createPrivilegedActionBackendRequest,
+    extractPrivilegedActionRequest,
     FDOInterface,
     FDO_SDK,
+    getInlinePrivilegedActionErrorFormatterSource,
     getOperatorToolPreset,
     PluginCapability,
     PluginMetadata,
@@ -64,10 +66,12 @@ export default class OperatorPluginExample extends FDO_SDK implements FDOInterfa
     }
 
     renderOnLoad(): string {
+        const formatPrivilegedActionErrorSource = getInlinePrivilegedActionErrorFormatterSource();
         return `
             (() => {
                 const button = document.getElementById("run-docker-status");
                 const output = document.getElementById("operator-result-box");
+                const formatPrivilegedActionError = ${formatPrivilegedActionErrorSource};
 
                 if (!button || !output) {
                     return;
@@ -88,7 +92,8 @@ export default class OperatorPluginExample extends FDO_SDK implements FDOInterfa
                             content: {},
                         });
 
-                        const response = await window.createBackendReq("requestPrivilegedAction", envelope);
+                        const requestPayload = extractPrivilegedActionRequest(envelope);
+                        const response = await window.createBackendReq("requestPrivilegedAction", requestPayload);
 
                         if (response && response.ok) {
                             setOutput({
@@ -99,10 +104,14 @@ export default class OperatorPluginExample extends FDO_SDK implements FDOInterfa
                             return;
                         }
 
+                        const fallbackCorrelationId = envelope?.result?.correlationId ?? envelope?.correlationId ?? "unknown";
                         setOutput({
                             status: "error",
-                            correlationId: response?.correlationId ?? envelope?.correlationId ?? "unknown",
-                            error: response?.error ?? "Unknown host error",
+                            correlationId: response?.correlationId ?? fallbackCorrelationId,
+                            error: formatPrivilegedActionError(response, {
+                                context: "Operator request failed",
+                                fallbackCorrelationId,
+                            }),
                             code: response?.code ?? "UNKNOWN",
                         });
                     } catch (error) {
diff --git a/examples/10-system-file-plugin.ts b/examples/10-system-file-plugin.ts
index b6e6dfa..eeed3d2 100644
--- a/examples/10-system-file-plugin.ts
+++ b/examples/10-system-file-plugin.ts
@@ -2,8 +2,10 @@ import {
     createFilesystemMutateActionRequest,
     createFilesystemScopeCapability,
     createPrivilegedActionBackendRequest,
+    extractPrivilegedActionRequest,
     FDOInterface,
     FDO_SDK,
+    getInlinePrivilegedActionErrorFormatterSource,
     PluginCapability,
     PluginMetadata,
     PluginRegistry,
@@ -89,10 +91,12 @@ export default class SystemFilePlugin extends FDO_SDK implements FDOInterface {
     }
 
     renderOnLoad(): string {
+        const formatPrivilegedActionErrorSource = getInlinePrivilegedActionErrorFormatterSource();
         return `
             (() => {
                 const button = document.getElementById("run-system-file-action");
                 const resultBox = document.getElementById("system-file-result");
+                const formatPrivilegedActionError = ${formatPrivilegedActionErrorSource};
 
                 if (!button || !resultBox) {
                     return;
@@ -108,12 +112,25 @@ export default class SystemFilePlugin extends FDO_SDK implements FDOInterface {
                     setResult("Building privileged-action envelope...");
 
                     try {
-                        const envelope = await window.createBackendReq("UI_MESSAGE", {
+                        const envelopeResponse = await window.createBackendReq("UI_MESSAGE", {
                             handler: "${SystemFilePlugin.HANDLER}",
                             content: {},
                         });
 
-                        const response = await window.createBackendReq("requestPrivilegedAction", envelope);
+                        const requestPayload = extractPrivilegedActionRequest(envelopeResponse);
+                        const envelopeCorrelationId = envelopeResponse?.result?.correlationId ?? envelopeResponse?.correlationId ?? "unknown";
+
+                        if (!requestPayload || typeof requestPayload !== "object") {
+                            setResult({
+                                status: "error",
+                                correlationId: envelopeCorrelationId,
+                                error: "Backend handler did not return a privileged request envelope.",
+                                code: "PLUGIN_BACKEND_EMPTY_RESPONSE",
+                            });
+                            return;
+                        }
+
+                        const response = await window.createBackendReq("requestPrivilegedAction", requestPayload);
 
                         if (response && response.ok) {
                             setResult({
@@ -126,8 +143,11 @@ export default class SystemFilePlugin extends FDO_SDK implements FDOInterface {
 
                         setResult({
                             status: "error",
-                            correlationId: response?.correlationId ?? envelope?.correlationId ?? "unknown",
-                            error: response?.error ?? "Unknown host error",
+                            correlationId: response?.correlationId ?? envelopeCorrelationId,
+                            error: formatPrivilegedActionError(response, {
+                                context: "System file action failed",
+                                fallbackCorrelationId: envelopeCorrelationId,
+                            }),
                             code: response?.code ?? "UNKNOWN",
                         });
                     } catch (error) {
diff --git a/examples/11-hosts-manager-plugin/HostsLogic.ts b/examples/11-hosts-manager-plugin/HostsLogic.ts
new file mode 100644
index 0000000..e29e093
--- /dev/null
+++ b/examples/11-hosts-manager-plugin/HostsLogic.ts
@@ -0,0 +1,47 @@
+import { HostsRecord } from "@anikitenko/fdo-sdk";
+
+export interface HostEnvironment {
+    id: string;
+    name: string;
+    active: boolean;
+    records: HostsRecord[];
+}
+
+export class HostsLogic {
+    private environments: HostEnvironment[] = [
+        {
+            id: "local-dev",
+            name: "Local Development",
+            active: true,
+            records: [
+                { address: "127.0.0.1", hostname: "dev.local", comment: "Main dev entry" },
+                { address: "127.0.0.1", hostname: "api.local" }
+            ]
+        },
+        {
+            id: "staging",
+            name: "Staging Environment",
+            active: false,
+            records: [
+                { address: "192.168.1.50", hostname: "staging.myapp.com" }
+            ]
+        }
+    ];
+
+    getEnvironments(): HostEnvironment[] {
+        return this.environments;
+    }
+
+    toggleEnvironment(id: string): void {
+        const env = this.environments.find(e => e.id === id);
+        if (env) {
+            env.active = !env.active;
+        }
+    }
+
+    getActiveRecords(): HostsRecord[] {
+        return this.environments
+            .filter(e => e.active)
+            .flatMap(e => e.records);
+    }
+}
diff --git a/examples/11-hosts-manager-plugin/index.ts b/examples/11-hosts-manager-plugin/index.ts
new file mode 100644
index 0000000..6daec97
--- /dev/null
+++ b/examples/11-hosts-manager-plugin/index.ts
@@ -0,0 +1,447 @@
+import {
+    DOM,
+    createHostsWriteActionRequest,
+    createPrivilegedActionBackendRequest,
+    extractPrivilegedActionRequest,
+    FDOInterface,
+    FDO_SDK,
+    getInlinePrivilegedActionErrorFormatterSource,
+    PluginCapability,
+    PluginMetadata,
+    PluginRegistry,
+} from "@anikitenko/fdo-sdk";
+import { HostsLogic } from "./HostsLogic";
+// @ts-ignore
+import css from "./styles/style.css";
+
+/**
+ * Learning example 11: Multi-file Hosts Manager.
+ *
+ * This example demonstrates:
+ * 1. Multi-file plugin structure (index.ts, HostsLogic.ts, styles/style.css).
+ * 2. Real-world use case: Managing /etc/hosts (SwitchHosts style).
+ * 3. CSS-object import compiled by host + DOM helper class generation.
+ * 4. Advanced state management and privileged action requests.
+ */
+export default class HostsManagerPlugin extends FDO_SDK implements FDOInterface {
+    private static readonly APPLY_HANDLER = "hostsManager.v1.apply";
+    private static readonly TOGGLE_HANDLER = "hostsManager.v1.toggle";
+    private static readonly GET_DATA_HANDLER = "hostsManager.v1.getData";
+    private static readonly SELECT_HANDLER = "hostsManager.v1.select";
+
+    private readonly logic = new HostsLogic();
+    private readonly dom = new DOM();
+    private readonly classes = this.buildClassNames(css as Record<string, unknown>);
+    private selectedEnvironmentId = this.logic.getEnvironments()[0]?.id ?? "";
+
+    private readonly _metadata: PluginMetadata = {
+        name: "HostsManager",
+        version: "1.0.0",
+        author: "FDO Explorer",
+        description: "A real-world multi-file example for managing host environments.",
+        icon: "social-network",
+    };
+
+    get metadata(): PluginMetadata {
+        return this._metadata;
+    }
+
+    declareCapabilities(): PluginCapability[] {
+        return ["system.hosts.write"];
+    }
+
+    private buildClassNames(styles: Record<string, unknown>): Record<string, string> {
+        const classNames: Record<string, string> = {};
+
+        for (const [key, styleObject] of Object.entries(styles)) {
+            if (!key || key.startsWith("@")) {
+                continue;
+            }
+            if (!styleObject || typeof styleObject !== "object") {
+                continue;
+            }
+            classNames[key] = this.dom.createClassFromStyle(styleObject as Record<string, string>);
+        }
+
+        return classNames;
+    }
+
+    private cls(name: string): string {
+        return this.classes[name] ?? "";
+    }
+
+    init(): void {
+        this.info("Hosts Manager Plugin Initialized");
+
+        PluginRegistry.registerHandler(HostsManagerPlugin.SELECT_HANDLER, (data: { id?: string }) => {
+            const id = typeof data?.id === "string" ? data.id : "";
+            if (!id) {
+                return {
+                    ok: false,
+                    error: "Missing environment id.",
+                };
+            }
+            this.selectedEnvironmentId = id;
+            return {
+                ok: true,
+                selectedEnvironmentId: this.selectedEnvironmentId,
+                environments: this.logic.getEnvironments(),
+            };
+        });
+
+        PluginRegistry.registerHandler(HostsManagerPlugin.TOGGLE_HANDLER, (data: { id?: string }) => {
+            const id = typeof data?.id === "string" ? data.id : "";
+            if (!id) {
+                return {
+                    ok: false,
+                    error: "Missing environment id.",
+                };
+            }
+            this.logic.toggleEnvironment(id);
+            this.selectedEnvironmentId = id;
+            return {
+                ok: true,
+                selectedEnvironmentId: this.selectedEnvironmentId,
+                environments: this.logic.getEnvironments(),
+            };
+        });
+
+        PluginRegistry.registerHandler(HostsManagerPlugin.GET_DATA_HANDLER, () => {
+            return {
+                ok: true,
+                selectedEnvironmentId: this.selectedEnvironmentId,
+                environments: this.logic.getEnvironments(),
+            };
+        });
+
+        PluginRegistry.registerHandler(HostsManagerPlugin.APPLY_HANDLER, () => {
+            const activeRecords = this.logic.getActiveRecords();
+            const request = createHostsWriteActionRequest({
+                action: "system.hosts.write",
+                payload: {
+                    records: activeRecords,
+                    tag: "fdo-managed",
+                    dryRun: false
+                }
+            });
+
+            return createPrivilegedActionBackendRequest(request, {
+                correlationIdPrefix: "hosts-mgr"
+            });
+        });
+    }
+
+    render(): string {
+        const content = `
+            <div class="${this.cls("hostsManager")}">
+                <header class="${this.cls("chromeBar")}">
+                    <div class="${this.cls("chromeLeft")}">
+                        <span class="${this.cls("chromeDot")} ${this.cls("chromeDotRed")}"></span>
+                        <span class="${this.cls("chromeDot")} ${this.cls("chromeDotYellow")}"></span>
+                        <span class="${this.cls("chromeDot")} ${this.cls("chromeDotGreen")}"></span>
+                        <span class="${this.cls("chromeGlyph")}">▣</span>
+                        <span class="${this.cls("chromeGlyph")}">+</span>
+                    </div>
+                    <div class="${this.cls("chromeCenter")}">
+                        <span class="${this.cls("chromeFileIcon")}">📄</span>
+                        <strong class="${this.cls("chromeTitle")}">my</strong>
+                    </div>
+                    <div class="${this.cls("chromeRight")}">
+                        <button id="hosts-refresh-btn" class="${this.cls("toolbarButton")}" type="button">Refresh</button>
+                        <button id="hosts-apply-btn" class="${this.cls("toolbarButton")} ${this.cls("applyButton")}" type="button">Apply</button>
+                    </div>
+                </header>
+
+                <div class="${this.cls("layout")}">
+                    <aside class="${this.cls("sidebar")}">
+                        <div class="${this.cls("sidebarHeader")}">
+                            <span class="${this.cls("sidebarIcon")}">🖥</span>
+                            <strong class="${this.cls("sidebarTitle")}">System Hosts</strong>
+                        </div>
+                        <div id="env-list" class="${this.cls("environmentList")}">
+                            <p class="${this.cls("emptyState")}">Loading environments...</p>
+                        </div>
+                    </aside>
+
+                    <section class="${this.cls("editorPane")}">
+                        <div class="${this.cls("editorHeader")}">
+                            <span class="${this.cls("editorFileIcon")}">📄</span>
+                            <strong id="hosts-preview-title" class="${this.cls("editorTitle")}">my</strong>
+                        </div>
+                        <div id="hosts-preview" class="${this.cls("codeViewport")}">
+                            <p class="${this.cls("emptyState")}">Loading preview...</p>
+                        </div>
+                    </section>
+                </div>
+
+                <div id="status-display" class="${this.cls("statusArea")}"></div>
+            </div>
+        `;
+
+        return this.dom.renderHTML(content);
+    }
+
+    renderOnLoad(): string {
+        const formatPrivilegedActionErrorSource = getInlinePrivilegedActionErrorFormatterSource();
+        return `
+            (() => {
+                const envList = document.getElementById("env-list");
+                const preview = document.getElementById("hosts-preview");
+                const previewTitle = document.getElementById("hosts-preview-title");
+                const applyBtn = document.getElementById("hosts-apply-btn");
+                const refreshBtn = document.getElementById("hosts-refresh-btn");
+                const statusDisplay = document.getElementById("status-display");
+                const formatPrivilegedActionError = ${formatPrivilegedActionErrorSource};
+
+                if (!envList || !preview || !previewTitle || !applyBtn || !refreshBtn || !statusDisplay) {
+                    return;
+                }
+
+                const classes = {
+                    environmentRow: "${this.cls("environmentRow")}",
+                    environmentRowSelected: "${this.cls("environmentRowSelected")}",
+                    environmentMeta: "${this.cls("environmentMeta")}",
+                    environmentName: "${this.cls("environmentName")}",
+                    environmentIcon: "${this.cls("environmentIcon")}",
+                    environmentPath: "${this.cls("environmentPath")}",
+                    environmentControls: "${this.cls("environmentControls")}",
+                    toggleButton: "${this.cls("toggleButton")}",
+                    toggleButtonActive: "${this.cls("toggleButtonActive")}",
+                    toggleKnob: "${this.cls("toggleKnob")}",
+                    toggleKnobActive: "${this.cls("toggleKnobActive")}",
+                    codeLine: "${this.cls("codeLine")}",
+                    lineNumber: "${this.cls("lineNumber")}",
+                    codeText: "${this.cls("codeText")}",
+                    codeComment: "${this.cls("codeComment")}",
+                    codeIp: "${this.cls("codeIp")}",
+                    codeHost: "${this.cls("codeHost")}",
+                    statusSuccess: "${this.cls("statusSuccess")}",
+                    statusError: "${this.cls("statusError")}",
+                    emptyState: "${this.cls("emptyState")}",
+                };
+
+                let selectedEnvironmentId = "${this.selectedEnvironmentId}";
+                let currentEnvironments = [];
+
+                const escapeHtml = (value) =>
+                    String(value ?? "")
+                        .replace(/&/g, "&amp;")
+                        .replace(/</g, "&lt;")
+                        .replace(/>/g, "&gt;")
+                        .replace(/"/g, "&quot;")
+                        .replace(/'/g, "&#39;");
+
+                const showStatus = (message, isError = false) => {
+                    statusDisplay.innerHTML = \`
+                        <div class="\${isError ? classes.statusError : classes.statusSuccess}">
+                            \${escapeHtml(message)}
+                        </div>
+                    \`;
+                };
+
+                const formatHostLine = (line) => {
+                    if (!line.trim()) {
+                        return \`<span class="\${classes.codeText}">&nbsp;</span>\`;
+                    }
+
+                    if (line.trim().startsWith("#")) {
+                        return \`<span class="\${classes.codeComment}">\${escapeHtml(line)}</span>\`;
+                    }
+
+                    const parts = line.trim().split(/\\s+/);
+                    const ip = parts.shift() || "";
+                    const host = parts.join(" ");
+                    return \`
+                        <span class="\${classes.codeIp}">\${escapeHtml(ip)}</span>
+                        <span class="\${classes.codeHost}">\${escapeHtml(host)}</span>
+                    \`;
+                };
+
+                const renderPreview = () => {
+                    const selected = currentEnvironments.find((env) => env.id === selectedEnvironmentId);
+                    previewTitle.textContent = selected ? selected.name : "my";
+
+                    const activeRecords = currentEnvironments
+                        .filter((env) => env.active)
+                        .flatMap((env) => env.records || []);
+
+                    const lines = [
+                        "##",
+                        "# Host Database",
+                        "#",
+                        "# localhost is used to configure the loopback interface",
+                        "# when the system is booting. Do not change this entry.",
+                        "##",
+                        "127.0.0.1 localhost",
+                        "255.255.255.255 broadcasthost",
+                        "::1 localhost",
+                        "",
+                        "# --- FDO Managed Records ---",
+                    ];
+
+                    activeRecords.forEach((record) => {
+                        const comment = record.comment ? \` # \${record.comment}\` : "";
+                        lines.push(\`\${record.address} \${record.hostname}\${comment}\`);
+                    });
+
+                    if (activeRecords.length === 0) {
+                        lines.push("# no active environments");
+                    }
+
+                    preview.innerHTML = lines.map((line, index) => \`
+                        <div class="\${classes.codeLine}">
+                            <span class="\${classes.lineNumber}">\${index + 1}</span>
+                            \${formatHostLine(line)}
+                        </div>
+                    \`).join("");
+                };
+
+                const selectEnvironment = async (id) => {
+                    if (!id) {
+                        return;
+                    }
+
+                    selectedEnvironmentId = id;
+                    const response = await window.createBackendReq("UI_MESSAGE", {
+                        handler: "${HostsManagerPlugin.SELECT_HANDLER}",
+                        content: { id }
+                    });
+
+                    if (response && response.environments) {
+                        currentEnvironments = response.environments;
+                        renderEnvironmentList();
+                        renderPreview();
+                    }
+                };
+
+                const toggleEnvironment = async (id) => {
+                    if (!id) {
+                        return;
+                    }
+
+                    const response = await window.createBackendReq("UI_MESSAGE", {
+                        handler: "${HostsManagerPlugin.TOGGLE_HANDLER}",
+                        content: { id }
+                    });
+
+                    if (response && response.environments) {
+                        selectedEnvironmentId = response.selectedEnvironmentId || id;
+                        currentEnvironments = response.environments;
+                        renderEnvironmentList();
+                        renderPreview();
+                    }
+                };
+
+                const renderEnvironmentList = () => {
+                    if (!currentEnvironments.length) {
+                        envList.innerHTML = \`<p class="\${classes.emptyState}">No environments available.</p>\`;
+                        return;
+                    }
+
+                    envList.innerHTML = currentEnvironments.map((env, index) => \`
+                        <div class="\${classes.environmentRow} \${env.id === selectedEnvironmentId ? classes.environmentRowSelected : ""}" data-select-id="\${env.id}">
+                            <div class="\${classes.environmentMeta}">
+                                <div class="\${classes.environmentName}">
+                                    <span class="\${classes.environmentIcon}">\${index === 0 ? "📄" : "🌐"}</span>
+                                    <span>\${escapeHtml(env.name)}</span>
+                                </div>
+                                <div class="\${classes.environmentPath}">
+                                    \${escapeHtml(env.id)} - \${Array.isArray(env.records) ? env.records.length : 0} entries
+                                </div>
+                            </div>
+                            <div class="\${classes.environmentControls}">
+                                <button
+                                    class="\${classes.toggleButton} \${env.active ? classes.toggleButtonActive : ""}"
+                                    type="button"
+                                    data-toggle-id="\${env.id}"
+                                    aria-pressed="\${env.active ? "true" : "false"}"
+                                    title="\${env.active ? "Disable" : "Enable"} \${escapeHtml(env.name)}"
+                                >
+                                    <span class="\${classes.toggleKnob} \${env.active ? classes.toggleKnobActive : ""}"></span>
+                                </button>
+                            </div>
+                        </div>
+                    \`).join('');
+
+                    envList.querySelectorAll("[data-select-id]").forEach((row) => {
+                        row.addEventListener("click", async () => {
+                            const id = row.getAttribute("data-select-id");
+                            await selectEnvironment(id);
+                        });
+                    });
+
+                    envList.querySelectorAll("[data-toggle-id]").forEach((btn) => {
+                        btn.addEventListener("click", async (event) => {
+                            event.stopPropagation();
+                            const id = btn.getAttribute("data-toggle-id");
+                            await toggleEnvironment(id);
+                        });
+                    });
+                };
+
+                const reloadData = async () => {
+                    const response = await window.createBackendReq("UI_MESSAGE", {
+                        handler: "${HostsManagerPlugin.GET_DATA_HANDLER}",
+                        content: {}
+                    });
+                    if (response && response.environments) {
+                        selectedEnvironmentId = response.selectedEnvironmentId || response.environments[0]?.id || selectedEnvironmentId;
+                        currentEnvironments = response.environments;
+                        renderEnvironmentList();
+                        renderPreview();
+                        showStatus("Environment data refreshed.");
+                    }
+                };
+
+                refreshBtn.addEventListener("click", () => {
+                    void reloadData();
+                });
+
+                applyBtn.addEventListener("click", async () => {
+                    applyBtn.disabled = true;
+                    const originalText = applyBtn.textContent;
+                    applyBtn.textContent = "Applying...";
+                    
+                    try {
+                        const envelope = await window.createBackendReq("UI_MESSAGE", {
+                            handler: "${HostsManagerPlugin.APPLY_HANDLER}",
+                            content: {}
+                        });
+
+                        const correlationId =
+                            envelope?.result?.correlationId
+                            ?? envelope?.correlationId
+                            ?? "";
+                        const requestPayload = extractPrivilegedActionRequest(envelope);
+                        if (!requestPayload || typeof requestPayload !== "object") {
+                            showStatus("Apply failed: malformed privileged request payload.", true);
+                            return;
+                        }
+                        const result = await window.createBackendReq("requestPrivilegedAction", requestPayload);
+                        
+                        if (result && result.ok) {
+                            const suffix = correlationId ? \` Correlation ID: \${correlationId}\` : "";
+                            showStatus(\`Hosts file applied successfully.\${suffix}\`);
+                            await reloadData();
+                        } else {
+                            showStatus(formatPrivilegedActionError(result, {
+                                context: "Hosts apply failed",
+                                fallbackCorrelationId: correlationId || "unknown",
+                            }), true);
+                        }
+                    } catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        showStatus("IPC Error: " + message, true);
+                    } finally {
+                        applyBtn.disabled = false;
+                        applyBtn.textContent = originalText || "Apply";
+                    }
+                });
+
+                void reloadData();
+            })();
+        `;
+    }
+}
+
+new HostsManagerPlugin();
diff --git a/examples/11-hosts-manager-plugin/styles/style.css b/examples/11-hosts-manager-plugin/styles/style.css
new file mode 100644
index 0000000..8c9046d
--- /dev/null
+++ b/examples/11-hosts-manager-plugin/styles/style.css
@@ -0,0 +1,341 @@
+.hostsManager {
+    height: 100%;
+    min-height: 560px;
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+    border: 1px solid #b7bac4;
+    border-radius: 14px;
+    background: #d6d7df;
+    color: #1f2430;
+    font-family: "SF Pro Text", "Segoe UI", -apple-system, BlinkMacSystemFont, sans-serif;
+    box-shadow: 0 18px 36px rgba(31, 36, 48, 0.14);
+}
+
+.chromeBar {
+    min-height: 54px;
+    display: grid;
+    grid-template-columns: 1fr auto 1fr;
+    align-items: center;
+    gap: 10px;
+    padding: 0 14px;
+    border-bottom: 1px solid #babdc8;
+    background: #ececef;
+}
+
+.chromeLeft {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+}
+
+.chromeCenter {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 8px;
+    justify-self: center;
+    color: #1c2230;
+    font-size: 18px;
+    font-weight: 600;
+}
+
+.chromeRight {
+    display: inline-flex;
+    align-items: center;
+    justify-self: end;
+    gap: 8px;
+}
+
+.chromeDot {
+    width: 11px;
+    height: 11px;
+    border-radius: 999px;
+    display: inline-block;
+}
+
+.chromeDotRed {
+    background: #ff5f57;
+    border: 1px solid #e0443e;
+}
+
+.chromeDotYellow {
+    background: #ffbd2f;
+    border: 1px solid #d09a25;
+}
+
+.chromeDotGreen {
+    background: #28c840;
+    border: 1px solid #1ea933;
+}
+
+.chromeGlyph {
+    color: #2b3040;
+    font-size: 22px;
+    line-height: 1;
+}
+
+.chromeFileIcon {
+    font-size: 19px;
+}
+
+.chromeTitle {
+    font-size: 22px;
+    line-height: 1;
+    letter-spacing: 0.01em;
+}
+
+.toolbarButton {
+    border: 1px solid #b8bbc7;
+    border-radius: 8px;
+    background: #fcfcfd;
+    color: #2a2f3f;
+    font-size: 12px;
+    font-weight: 600;
+    padding: 5px 11px;
+    cursor: pointer;
+}
+
+.toolbarButton:hover {
+    background: #f3f5fa;
+}
+
+.toolbarButton:disabled {
+    opacity: 0.62;
+    cursor: not-allowed;
+}
+
+.applyButton {
+    border-color: #5f8ee6;
+    background: #5f8ee6;
+    color: #ffffff;
+}
+
+.applyButton:hover {
+    background: #4b7ddf;
+}
+
+.layout {
+    flex: 1;
+    min-height: 0;
+    display: grid;
+    grid-template-columns: minmax(280px, 34%) 1fr;
+}
+
+.sidebar {
+    min-height: 0;
+    background: #d2d4dd;
+    border-right: 1px solid #bdc0cb;
+}
+
+.sidebarHeader {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    padding: 22px 20px 12px;
+    color: #202635;
+}
+
+.sidebarIcon {
+    font-size: 28px;
+    line-height: 1;
+}
+
+.sidebarTitle {
+    font-size: 30px;
+    font-weight: 500;
+    line-height: 1.1;
+    letter-spacing: -0.02em;
+}
+
+.environmentList {
+    padding: 8px 12px 18px;
+    overflow: auto;
+    height: calc(100% - 74px);
+}
+
+.environmentRow {
+    display: flex;
+    justify-content: space-between;
+    gap: 10px;
+    align-items: center;
+    border: 1px solid transparent;
+    border-radius: 11px;
+    padding: 10px 12px;
+    color: #262c3a;
+    cursor: pointer;
+}
+
+.environmentRow:hover {
+    border-color: #a8b7d3;
+    background: #c8d1e3;
+}
+
+.environmentRowSelected {
+    border-color: #9cb5dd;
+    background: linear-gradient(130deg, #d7e5f6, #c5d8f1);
+}
+
+.environmentMeta {
+    min-width: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 3px;
+}
+
+.environmentName {
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    font-size: 16px;
+    font-weight: 500;
+    line-height: 1.15;
+}
+
+.environmentIcon {
+    font-size: 18px;
+    line-height: 1;
+}
+
+.environmentPath {
+    font-size: 12px;
+    color: #5f6472;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+.environmentControls {
+    display: flex;
+    align-items: center;
+}
+
+.toggleButton {
+    width: 38px;
+    height: 22px;
+    border: 1px solid #979ca8;
+    border-radius: 999px;
+    background: #b7bcc8;
+    cursor: pointer;
+    padding: 2px;
+    display: inline-flex;
+    align-items: center;
+    justify-content: flex-start;
+}
+
+.toggleButtonActive {
+    border-color: #89b78c;
+    background: #b7ddb9;
+}
+
+.toggleKnob {
+    width: 16px;
+    height: 16px;
+    border-radius: 999px;
+    background: #8f949f;
+    transition: transform 0.14s ease;
+}
+
+.toggleKnobActive {
+    background: #4f9c53;
+    transform: translateX(16px);
+}
+
+.editorPane {
+    min-height: 0;
+    display: flex;
+    flex-direction: column;
+    background: #efefef;
+}
+
+.editorHeader {
+    min-height: 52px;
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 0 22px;
+    border-bottom: 1px solid #cdced7;
+    color: #1b2231;
+}
+
+.editorFileIcon {
+    font-size: 20px;
+}
+
+.editorTitle {
+    font-size: 28px;
+    line-height: 1;
+    font-weight: 500;
+    letter-spacing: -0.02em;
+}
+
+.codeViewport {
+    flex: 1;
+    min-height: 0;
+    overflow: auto;
+    padding: 10px 0 20px;
+    background: #f8f8f8;
+}
+
+.codeLine {
+    min-height: 34px;
+    display: grid;
+    grid-template-columns: 64px minmax(0, 1fr);
+    align-items: baseline;
+    gap: 18px;
+    padding: 0 16px;
+    font-family: "SF Mono", "Menlo", "Consolas", monospace;
+    font-size: 28px;
+    letter-spacing: -0.02em;
+    line-height: 1.2;
+}
+
+.lineNumber {
+    text-align: right;
+    color: #8f8f96;
+    user-select: none;
+}
+
+.codeText {
+    color: #232734;
+}
+
+.codeComment {
+    color: #009114;
+}
+
+.codeIp {
+    color: #1f67c8;
+}
+
+.codeHost {
+    color: #12141d;
+    margin-left: 14px;
+}
+
+.statusArea {
+    min-height: 42px;
+    display: flex;
+    align-items: center;
+    padding: 4px 14px 10px;
+    border-top: 1px solid #c7c9d3;
+    background: #ececef;
+}
+
+.statusSuccess {
+    color: #1f6330;
+    font-size: 13px;
+    font-weight: 600;
+}
+
+.statusError {
+    color: #9e1f1f;
+    font-size: 13px;
+    font-weight: 600;
+}
+
+.emptyState {
+    margin: 0;
+    color: #6e7280;
+    font-size: 13px;
+}
diff --git a/examples/12-git-operations-plugin.ts b/examples/12-git-operations-plugin.ts
new file mode 100644
index 0000000..042698d
--- /dev/null
+++ b/examples/12-git-operations-plugin.ts
@@ -0,0 +1,3792 @@
+import {
+    createAICapabilityPreset,
+    createNetworkCapabilityBundle,
+    createOperatorToolActionRequest,
+    createOperatorToolCapabilityPreset,
+    defineRenderOnLoad,
+    createStorageCapabilityPreset,
+    createPrivilegedActionBackendRequest,
+    DOM,
+    DOMButton,
+    DOMInput,
+    DOMNested,
+    DOMSemantic,
+    DOMText,
+    FDOInterface,
+    FDO_SDK,
+    PluginCapability,
+    PluginMetadata,
+    PluginRegistry,
+    QuickAction,
+    runCapabilityPreflight,
+    requireCapability,
+    requireNetworkScopeCapability,
+    SidePanelConfig,
+    StoreType,
+} from "@anikitenko/fdo-sdk";
+
+type GitOperationId =
+    | "status"
+    | "branches"
+    | "log"
+    | "diffStat"
+    | "showHead"
+    | "fetch"
+    | "pullFFOnly"
+    | "commitStaged";
+
+type GitOperationDefinition = {
+    title: string;
+    args: string[];
+    reason: string;
+    timeoutMs: number;
+};
+
+type GitStatusSummary = {
+    branch: string;
+    aheadBehind: string;
+    staged: number;
+    modified: number;
+    untracked: number;
+    conflicts: number;
+    isClean: boolean;
+    stagedFiles: string[];
+};
+
+const GIT_OPERATIONS: Record<GitOperationId, GitOperationDefinition> = {
+    status: {
+        title: "Repository Status",
+        args: ["status", "--porcelain=v2", "--branch"],
+        reason: "collect repository status summary for troubleshooting dashboard",
+        timeoutMs: 10000,
+    },
+    branches: {
+        title: "Branch Overview",
+        args: ["branch", "-vv"],
+        reason: "inspect local branches and upstream tracking state",
+        timeoutMs: 10000,
+    },
+    log: {
+        title: "Recent Commits",
+        args: ["log", "--oneline", "--decorate", "-n", "15"],
+        reason: "inspect recent commit history for context",
+        timeoutMs: 10000,
+    },
+    diffStat: {
+        title: "Working Tree Diff Summary",
+        args: ["diff", "--stat", "--compact-summary"],
+        reason: "inspect changed files footprint before mutation commands",
+        timeoutMs: 10000,
+    },
+    showHead: {
+        title: "HEAD Metadata",
+        args: ["show", "--stat", "--no-patch", "HEAD"],
+        reason: "inspect latest commit metadata for quick diagnostics",
+        timeoutMs: 10000,
+    },
+    fetch: {
+        title: "Fetch All Remotes",
+        args: ["fetch", "--all", "--prune"],
+        reason: "synchronize remote refs before branch and pull workflows",
+        timeoutMs: 15000,
+    },
+    pullFFOnly: {
+        title: "Pull (Fast-Forward Only)",
+        args: ["pull", "--ff-only"],
+        reason: "safely update current branch without merge commits",
+        timeoutMs: 20000,
+    },
+    commitStaged: {
+        title: "Commit Staged Changes",
+        args: ["commit", "-m", "<message>"],
+        reason: "persist staged repository changes with explicit commit message",
+        timeoutMs: 20000,
+    },
+};
+
+export default class GitOperationsPlugin extends FDO_SDK implements FDOInterface {
+    private static readonly BUILD_ID = "git-ops-2026-04-16-r3";
+    private static readonly PREPARE_HANDLER = "gitOps.v1.prepare";
+    private static readonly BUILD_REQUEST_HANDLER = "gitOps.v1.buildRequest";
+    private static readonly SAVE_REPO_PATH_HANDLER = "gitOps.v1.saveRepoPath";
+    private static readonly PREFETCH_ORIGINAL_REPO_REQUEST_HANDLER = "gitOps.v1.prefetchOriginalRepoRequest";
+    private static readonly PREFETCH_ORIGINAL_REPO_HANDLER = "gitOps.v1.prefetchOriginalRepo";
+    private static readonly BUILD_COMMIT_REQUEST_HANDLER = "gitOps.v1.buildCommitRequest";
+    private static readonly AI_ASSIST_HANDLER = "fdo.ai.request.v1";
+    private static readonly AI_ASSISTANTS_LIST_HANDLER = "fdo.ai.assistants.list.v1";
+    private static readonly QUICK_STATUS_HANDLER = "gitOps.v1.quick.status";
+    private static readonly QUICK_SNAPSHOT_HANDLER = "gitOps.v1.quick.snapshot";
+    private static readonly QUICK_PREFETCH_HANDLER = "gitOps.v1.quick.prefetch";
+    private static readonly SIDE_PANEL_CONSOLE_HANDLER = "gitOps.v1.sidePanel.console";
+    private static readonly SIDE_PANEL_RECENT_HANDLER = "gitOps.v1.sidePanel.recent";
+    private static readonly SIDE_PANEL_PROFILES_HANDLER = "gitOps.v1.sidePanel.profiles";
+    private static readonly ORIGINAL_CONFIGURED_REPO_PUBLIC_KEY = "fdo.public.git.originalConfiguredRepository";
+    private static readonly NETWORK_SCOPE_ID = "public-web-secure";
+
+    private static readonly STORAGE_KEYS = {
+        REPO_PATH: "gitOps:repoPath",
+        ORIGINAL_CONFIGURED_REPO_PATH: "gitOps:originalConfiguredRepoPath",
+        ORIGINAL_CONFIGURED_REPO_PUBLIC_KEY: "gitOps:originalConfiguredRepoPublicKey",
+        LAST_ACTION: "gitOps:lastAction",
+    } as const;
+
+    private readonly _metadata: PluginMetadata = {
+        name: "Git Operations Plugin",
+        version: "1.0.0",
+        author: "FDO SDK",
+        description: "One-file Git operations dashboard using scoped operator execution, DOM helpers, and injected iframe libraries.",
+        icon: "git-repo",
+    };
+
+    private readonly dom = new DOM();
+    private readonly classNames = this.buildClassNames();
+    private readonly gitCommand = this.resolveGitCommand();
+    private readonly declaredCapabilities: PluginCapability[] = this.buildDeclaredCapabilities();
+    private sessionStore?: StoreType;
+    private persistentStore?: StoreType;
+    private handlersRegistered = false;
+    private jsonStoreAvailable = false;
+    private persistentStoreDiagnostic = "";
+    private repoPathForRender = this.getDefaultRepoPath();
+
+    constructor() {
+        super();
+        this.registerHandlers();
+    }
+
+    get metadata(): PluginMetadata {
+        return this._metadata;
+    }
+
+    declareCapabilities(): PluginCapability[] {
+        return [...this.declaredCapabilities];
+    }
+
+    defineQuickActions(): QuickAction[] {
+        return [
+            {
+                name: "Git Status",
+                subtitle: "Run repository status in current path",
+                icon: "dashboard",
+                message_type: GitOperationsPlugin.QUICK_STATUS_HANDLER,
+            },
+            {
+                name: "Git Snapshot",
+                subtitle: "Run status, branches, log, diff, show",
+                icon: "history",
+                message_type: GitOperationsPlugin.QUICK_SNAPSHOT_HANDLER,
+            },
+            {
+                name: "Prefetch Original Repo",
+                subtitle: "Resolve remote origin and metadata",
+                icon: "cloud-download",
+                message_type: GitOperationsPlugin.QUICK_PREFETCH_HANDLER,
+            },
+        ];
+    }
+
+    defineSidePanel(): SidePanelConfig {
+        return {
+            icon: "git-repo",
+            label: "Git Ops",
+            submenu_list: [
+                {
+                    id: "git-console",
+                    name: "Console",
+                    message_type: GitOperationsPlugin.SIDE_PANEL_CONSOLE_HANDLER,
+                },
+                {
+                    id: "git-recent",
+                    name: "Recent Runs",
+                    message_type: GitOperationsPlugin.SIDE_PANEL_RECENT_HANDLER,
+                },
+                {
+                    id: "git-profiles",
+                    name: "Repo Profiles",
+                    message_type: GitOperationsPlugin.SIDE_PANEL_PROFILES_HANDLER,
+                },
+            ],
+        };
+    }
+
+    private buildDeclaredCapabilities(): PluginCapability[] {
+        return [
+            ...createOperatorToolCapabilityPreset("git"),
+            ...createAICapabilityPreset("host.ai"),
+            ...createNetworkCapabilityBundle({
+                transports: ["https"],
+                scopeId: GitOperationsPlugin.NETWORK_SCOPE_ID,
+            }),
+            // Mirrors host capability model: storage base + storage.json backend leaf.
+            ...createStorageCapabilityPreset("storageJSON"),
+        ];
+    }
+
+    private getGrantedCapabilities(): PluginCapability[] {
+        try {
+            const diagnostics = PluginRegistry.getDiagnostics({ notificationsLimit: 0 });
+            const granted = diagnostics?.capabilities?.permissions?.granted;
+            if (Array.isArray(granted)) {
+                return granted as PluginCapability[];
+            }
+        } catch {
+            // Ignore diagnostics lookup errors and treat as no granted capabilities.
+        }
+
+        return [];
+    }
+
+    private cls(name: string): string {
+        return this.classNames[name] ?? "";
+    }
+
+    private getFallbackStore(): StoreType {
+        if (!this.sessionStore) {
+            // Default store must stay non-gated and safe for startup/render paths.
+            this.sessionStore = PluginRegistry.useStore("default");
+        }
+        return this.sessionStore;
+    }
+
+    private ensurePersistentStore(): void {
+        if (this.persistentStore) {
+            return;
+        }
+
+        try {
+            this.persistentStore = PluginRegistry.useStore("json");
+            this.jsonStoreAvailable = true;
+            this.persistentStoreDiagnostic = "";
+        } catch (error) {
+            this.jsonStoreAvailable = false;
+            const reason = error instanceof Error ? error.message : String(error);
+            this.persistentStoreDiagnostic = this.sanitizeStorageErrorReason(reason) || "JSON store is not available.";
+            this.warn(
+                "Git operations plugin: JSON store unavailable. Grant capabilities 'storage' and 'storage.json' and configure storage root via PluginRegistry.configureStorage({ rootDir }) or FDO_SDK_STORAGE_ROOT. Using session fallback for repository path.",
+                { error }
+            );
+        }
+    }
+
+    private runDeclaredCapabilityPreflight(action: string): void {
+        const report = runCapabilityPreflight({
+            action,
+            declared: this.declaredCapabilities,
+            granted: this.getGrantedCapabilities(),
+        });
+
+        if (report.ok) {
+            return;
+        }
+
+        this.warn(`Git operations plugin capability preflight warning: ${report.summary}`, {
+            action: report.action,
+            missingCapabilities: report.missing.map((entry) => entry.capability),
+            remediations: report.remediations,
+        });
+    }
+
+    private getStorageDiagnostic(): string {
+        return this.persistentStoreDiagnostic
+            || "JSON persistent store is currently unavailable in this runtime session.";
+    }
+
+    private sanitizeStorageErrorReason(reason: string): string {
+        const trimmed = String(reason || "").trim();
+        if (!trimmed) {
+            return "";
+        }
+        if (
+            trimmed.includes('Capability "storage" is required')
+            || trimmed.includes('Capability "storage.json" is required')
+        ) {
+            return "JSON persistent store is unavailable in the current capability session.";
+        }
+        return trimmed;
+    }
+
+    private getRuntimeProcess(): {
+        platform?: string;
+        cwd?: () => string;
+        env?: Record<string, string | undefined>;
+    } | null {
+        const candidate = (globalThis as { process?: unknown }).process;
+        if (!candidate || typeof candidate !== "object") {
+            return null;
+        }
+        return candidate as {
+            platform?: string;
+            cwd?: () => string;
+            env?: Record<string, string | undefined>;
+        };
+    }
+
+    private getRuntimeRequire(): ((moduleName: string) => unknown) | null {
+        const candidate = (globalThis as { require?: unknown }).require;
+        if (typeof candidate === "function") {
+            return candidate as (moduleName: string) => unknown;
+        }
+
+        // Some host/bundled runtimes do not expose require on globalThis.
+        // Probe common Node-compatible fallbacks so path validation remains reliable.
+        try {
+            const dynamicRequire = Function("return (typeof require === 'function') ? require : null;")() as unknown;
+            if (typeof dynamicRequire === "function") {
+                return dynamicRequire as (moduleName: string) => unknown;
+            }
+        } catch {
+            // Ignore and continue probing.
+        }
+
+        try {
+            const moduleRef = Function("return (typeof module !== 'undefined') ? module : null;")() as
+                | { require?: unknown }
+                | null;
+            if (moduleRef && typeof moduleRef.require === "function") {
+                return moduleRef.require as (moduleName: string) => unknown;
+            }
+        } catch {
+            // Ignore and continue probing.
+        }
+
+        return null;
+    }
+
+    private getRuntimePlatform(): string {
+        const runtimeProcess = this.getRuntimeProcess();
+        const platform = runtimeProcess?.platform;
+        return typeof platform === "string" && platform.trim()
+            ? platform.trim()
+            : "unknown";
+    }
+
+    private isAbsolutePath(value: string): boolean {
+        if (!value) {
+            return false;
+        }
+        return /^([a-zA-Z]:[\\/]|\\\\|\/)/.test(value);
+    }
+
+    private normalizeInputPath(rawValue: string): string {
+        const trimmed = rawValue.trim();
+        const withoutQuotes =
+            (trimmed.startsWith("\"") && trimmed.endsWith("\""))
+            || (trimmed.startsWith("'") && trimmed.endsWith("'"))
+                ? trimmed.slice(1, -1).trim()
+                : trimmed;
+
+        if (withoutQuotes.startsWith("file://")) {
+            try {
+                const url = new URL(withoutQuotes);
+                const decoded = decodeURIComponent(url.pathname || "");
+                if (this.getRuntimePlatform() === "win32") {
+                    const normalized = decoded.replace(/^\/([a-zA-Z]:)/, "$1").replace(/\//g, "\\");
+                    return normalized;
+                }
+                return decoded || withoutQuotes;
+            } catch {
+                return withoutQuotes;
+            }
+        }
+
+        if (withoutQuotes === "~" || withoutQuotes.startsWith("~/") || withoutQuotes.startsWith("~\\")) {
+            const runtimeProcess = this.getRuntimeProcess();
+            const home = runtimeProcess?.env
+                ? (this.getRuntimePlatform() === "win32"
+                    ? runtimeProcess.env["USERPROFILE"] ?? runtimeProcess.env["HOME"] ?? ""
+                    : runtimeProcess.env["HOME"] ?? "")
+                : "";
+            if (home && this.isAbsolutePath(home)) {
+                const suffix = withoutQuotes.slice(1);
+                if (!suffix) {
+                    return home;
+                }
+                if (home.endsWith("/") || home.endsWith("\\")) {
+                    return `${home}${suffix.replace(/^[/\\]/, "")}`;
+                }
+                return `${home}${suffix}`;
+            }
+        }
+
+        return withoutQuotes;
+    }
+
+    private fileExists(pathValue: string): boolean {
+        const runtimeRequire = this.getRuntimeRequire();
+        if (!runtimeRequire) {
+            return false;
+        }
+        try {
+            const fsModule = runtimeRequire("fs") as { existsSync?: (target: string) => boolean };
+            if (!fsModule || typeof fsModule.existsSync !== "function") {
+                return false;
+            }
+            return fsModule.existsSync(pathValue);
+        } catch {
+            return false;
+        }
+    }
+
+    private isExecutableFile(pathValue: string): boolean {
+        const runtimeRequire = this.getRuntimeRequire();
+        if (!runtimeRequire) {
+            return false;
+        }
+
+        try {
+            const fsModule = runtimeRequire("fs") as {
+                accessSync?: (target: string, mode?: number) => void;
+                constants?: { X_OK?: number };
+            };
+            if (!fsModule || typeof fsModule.accessSync !== "function") {
+                return this.fileExists(pathValue);
+            }
+            const executeMode = typeof fsModule.constants?.X_OK === "number"
+                ? fsModule.constants.X_OK
+                : undefined;
+            fsModule.accessSync(pathValue, executeMode);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    private isLikelyDirectoryPath(pathValue: string): boolean {
+        const runtimeRequire = this.getRuntimeRequire();
+        if (!runtimeRequire) {
+            return true;
+        }
+        try {
+            const fsModule = runtimeRequire("fs") as {
+                statSync?: (target: string) => { isDirectory?: () => boolean };
+            };
+            if (!fsModule || typeof fsModule.statSync !== "function") {
+                return true;
+            }
+            const stat = fsModule.statSync(pathValue);
+            return typeof stat?.isDirectory === "function" ? stat.isDirectory() : true;
+        } catch {
+            return true;
+        }
+    }
+
+    private getDefaultRepoPath(): string {
+        const runtimeProcess = this.getRuntimeProcess();
+        const homeCandidate = runtimeProcess?.env
+            ? (
+                this.getRuntimePlatform() === "win32"
+                    ? runtimeProcess.env["USERPROFILE"] ?? runtimeProcess.env["HOME"] ?? ""
+                    : runtimeProcess.env["HOME"] ?? ""
+            )
+            : "";
+        if (typeof homeCandidate === "string" && this.isAbsolutePath(homeCandidate)) {
+            return homeCandidate;
+        }
+
+        const cwdCandidate = typeof runtimeProcess?.cwd === "function" ? runtimeProcess.cwd() : "";
+        if (
+            typeof cwdCandidate === "string"
+            && this.isAbsolutePath(cwdCandidate)
+            && !cwdCandidate.includes("/plugin-data/")
+            && !cwdCandidate.includes("\\plugin-data\\")
+        ) {
+            return cwdCandidate;
+        }
+        return this.getRuntimePlatform() === "win32" ? "C:\\" : "/";
+    }
+
+    private getExecutableDirectory(pathValue: string): string {
+        const normalized = pathValue.replace(/[\\/]+/g, "/");
+        const lastSlash = normalized.lastIndexOf("/");
+        return lastSlash > 0 ? normalized.slice(0, lastSlash) : "";
+    }
+
+    private buildClassNames(): Record<string, string> {
+        const tokens: Record<string, Record<string, unknown>> = {
+            page: {
+                fontFamily: "\"Inter\", \"Segoe UI\", sans-serif",
+                color: "#12202f",
+                background: "linear-gradient(180deg, #f4f8ff 0%, #eef4ff 100%)",
+                border: "1px solid #d8e2f7",
+                borderRadius: "14px",
+                padding: "20px",
+                display: "flex",
+                flexDirection: "column",
+                gap: "14px",
+            },
+            top: {
+                display: "flex",
+                justifyContent: "space-between",
+                gap: "12px",
+                alignItems: "flex-start",
+                flexWrap: "wrap",
+            },
+            headingWrap: {
+                display: "flex",
+                flexDirection: "column",
+                gap: "4px",
+            },
+            heading: {
+                margin: "0",
+                fontSize: "24px",
+                lineHeight: "1.2",
+                letterSpacing: "-0.01em",
+            },
+            subtitle: {
+                margin: "0",
+                fontSize: "13px",
+                color: "#4b607b",
+            },
+            badge: {
+                alignSelf: "flex-start",
+                padding: "6px 10px",
+                borderRadius: "999px",
+                background: "#dde9ff",
+                color: "#2f4d82",
+                fontSize: "12px",
+                fontWeight: "600",
+            },
+            controls: {
+                background: "#ffffff",
+                border: "1px solid #d8e1f1",
+                borderRadius: "12px",
+                padding: "14px",
+                display: "flex",
+                flexDirection: "column",
+                gap: "10px",
+            },
+            label: {
+                fontSize: "12px",
+                color: "#4f6079",
+                fontWeight: "600",
+            },
+            inputRow: {
+                display: "flex",
+                gap: "10px",
+                alignItems: "center",
+                flexWrap: "wrap",
+            },
+            input: {
+                flex: "1",
+                minWidth: "260px",
+                border: "1px solid #c4d4f0",
+                borderRadius: "8px",
+                padding: "8px 10px",
+                fontSize: "13px",
+                color: "#15283b",
+                background: "#fbfdff",
+            },
+            buttonRow: {
+                display: "flex",
+                gap: "8px",
+                flexWrap: "wrap",
+            },
+            commitRow: {
+                display: "flex",
+                gap: "8px",
+                alignItems: "center",
+                flexWrap: "wrap",
+            },
+            button: {
+                border: "1px solid #b8caeb",
+                background: "#f9fbff",
+                color: "#27456f",
+                borderRadius: "8px",
+                padding: "7px 10px",
+                fontSize: "12px",
+                fontWeight: "600",
+                cursor: "pointer",
+                transition: "all 120ms ease",
+                "&:hover": {
+                    background: "#edf3ff",
+                },
+                "&:disabled": {
+                    opacity: "0.6",
+                    cursor: "not-allowed",
+                    background: "#f4f6fb",
+                },
+            },
+            buttonTiny: {
+                border: "1px solid #b9c8df",
+                background: "#f7f9fc",
+                color: "#2d4769",
+                borderRadius: "7px",
+                padding: "5px 8px",
+                fontSize: "11px",
+                fontWeight: "600",
+                cursor: "pointer",
+                "&:hover": {
+                    background: "#ebf1fb",
+                },
+                "&:disabled": {
+                    opacity: "0.65",
+                    cursor: "not-allowed",
+                },
+            },
+            aiPromptInput: {
+                flex: "1",
+                minWidth: "280px",
+                border: "1px solid #c7d5ee",
+                borderRadius: "7px",
+                padding: "5px 8px",
+                fontSize: "11px",
+                color: "#203550",
+                background: "#fbfdff",
+            },
+            buttonPrimary: {
+                borderColor: "#2f63c6",
+                background: "#2f63c6",
+                color: "#ffffff",
+                "&:hover": {
+                    background: "#2353af",
+                },
+            },
+            meta: {
+                margin: "0",
+                fontSize: "12px",
+                color: "#647b9b",
+            },
+            panels: {
+                display: "grid",
+                gridTemplateColumns: "minmax(260px, 320px) minmax(0, 1fr)",
+                gap: "12px",
+                minHeight: "360px",
+            },
+            panel: {
+                background: "#ffffff",
+                border: "1px solid #d8e1f1",
+                borderRadius: "12px",
+                padding: "12px",
+                display: "flex",
+                flexDirection: "column",
+                gap: "10px",
+                minHeight: "0",
+            },
+            panelTitle: {
+                margin: "0",
+                fontSize: "13px",
+                textTransform: "uppercase",
+                letterSpacing: "0.06em",
+                color: "#4c617f",
+            },
+            summaryGrid: {
+                display: "grid",
+                gridTemplateColumns: "repeat(2, minmax(0, 1fr))",
+                gap: "8px",
+            },
+            summaryItem: {
+                border: "1px solid #d8e4fa",
+                borderRadius: "10px",
+                padding: "8px",
+                background: "#f8fbff",
+                display: "flex",
+                flexDirection: "column",
+                gap: "2px",
+            },
+            summaryLabel: {
+                fontSize: "11px",
+                color: "#5f7698",
+                textTransform: "uppercase",
+                letterSpacing: "0.05em",
+            },
+            summaryValue: {
+                fontSize: "18px",
+                fontWeight: "700",
+                color: "#1e3860",
+            },
+            summaryHint: {
+                margin: "0",
+                fontSize: "12px",
+                color: "#5f7493",
+                lineHeight: "1.4",
+            },
+            historyWrap: {
+                borderTop: "1px solid #e3ebfa",
+                paddingTop: "10px",
+                display: "flex",
+                flexDirection: "column",
+                gap: "8px",
+            },
+            historyHeader: {
+                display: "flex",
+                alignItems: "center",
+                justifyContent: "space-between",
+                gap: "8px",
+            },
+            historyTitle: {
+                margin: "0",
+                fontSize: "12px",
+                textTransform: "uppercase",
+                letterSpacing: "0.06em",
+                color: "#4d6384",
+            },
+            historyList: {
+                display: "flex",
+                flexDirection: "column",
+                gap: "6px",
+                maxHeight: "180px",
+                overflow: "auto",
+            },
+            historyItem: {
+                border: "1px solid #d9e5fa",
+                borderRadius: "8px",
+                background: "#f8fbff",
+                padding: "7px 8px",
+                display: "flex",
+                flexDirection: "column",
+                gap: "2px",
+            },
+            historyPrimary: {
+                margin: "0",
+                fontSize: "12px",
+                fontWeight: "600",
+                color: "#1a365e",
+            },
+            historyMeta: {
+                margin: "0",
+                fontSize: "11px",
+                color: "#587196",
+            },
+            historyStatusOk: {
+                color: "#17683e",
+            },
+            historyStatusFailed: {
+                color: "#8a2b2b",
+            },
+            outputWrap: {
+                flex: "1",
+                minHeight: "0",
+                background: "#0f172a",
+                borderRadius: "10px",
+                overflow: "auto",
+                border: "1px solid #1d2d4b",
+            },
+            output: {
+                margin: "0",
+                padding: "12px",
+                minHeight: "320px",
+                color: "#dbeafe",
+                fontSize: "12px",
+                lineHeight: "1.5",
+                fontFamily: "\"SFMono-Regular\", \"Menlo\", \"Consolas\", monospace",
+                whiteSpace: "pre-wrap",
+                wordBreak: "break-word",
+            },
+            commandBarBackdrop: {
+                position: "fixed",
+                inset: "0",
+                background: "rgba(5, 11, 24, 0.62)",
+                display: "none",
+                alignItems: "flex-start",
+                justifyContent: "center",
+                paddingTop: "10vh",
+                zIndex: "9999",
+                "&[data-open=\"true\"]": {
+                    display: "flex",
+                },
+            },
+            commandBarPanel: {
+                width: "min(880px, calc(100vw - 28px))",
+                maxHeight: "76vh",
+                background: "#ffffff",
+                border: "1px solid #cfdcf5",
+                borderRadius: "14px",
+                boxShadow: "0 24px 64px rgba(9, 20, 40, 0.28)",
+                display: "flex",
+                flexDirection: "column",
+                overflow: "hidden",
+            },
+            commandBarHeader: {
+                display: "flex",
+                alignItems: "center",
+                gap: "10px",
+                padding: "12px",
+                borderBottom: "1px solid #e1e9f9",
+                background: "#f7faff",
+            },
+            commandBarInput: {
+                flex: "1",
+                border: "1px solid #c6d5f2",
+                borderRadius: "10px",
+                padding: "9px 12px",
+                fontSize: "13px",
+                color: "#13253b",
+                background: "#ffffff",
+            },
+            commandBarHint: {
+                margin: "0",
+                fontSize: "11px",
+                color: "#60779b",
+                whiteSpace: "nowrap",
+            },
+            commandBarList: {
+                overflow: "auto",
+                padding: "8px",
+                display: "flex",
+                flexDirection: "column",
+                gap: "8px",
+            },
+            commandBarItem: {
+                border: "1px solid #d7e3fa",
+                background: "#fbfdff",
+                borderRadius: "10px",
+                padding: "10px",
+                display: "flex",
+                flexDirection: "column",
+                gap: "4px",
+                cursor: "pointer",
+                textAlign: "left",
+                transition: "all 120ms ease",
+                "&:hover": {
+                    background: "#eff5ff",
+                    borderColor: "#b5caf2",
+                },
+                "&[data-selected=\"true\"]": {
+                    background: "#e8f1ff",
+                    borderColor: "#7ea5ea",
+                },
+            },
+            commandBarItemTitle: {
+                margin: "0",
+                fontSize: "13px",
+                fontWeight: "700",
+                color: "#163257",
+            },
+            commandBarItemMeta: {
+                margin: "0",
+                fontSize: "11px",
+                color: "#5e769b",
+                textTransform: "uppercase",
+                letterSpacing: "0.05em",
+            },
+            commandBarEmpty: {
+                margin: "10px 6px",
+                fontSize: "12px",
+                color: "#60779b",
+            },
+        };
+
+        const classes: Record<string, string> = {};
+        for (const [key, style] of Object.entries(tokens)) {
+            classes[key] = this.dom.createClassFromStyle(style as Record<string, string>);
+        }
+        return classes;
+    }
+
+    private resolveGitCommand(): string {
+        const candidates = this.getRuntimePlatform() === "win32"
+            ? [
+                "C:\\Program Files\\Git\\bin\\git.exe",
+                "C:\\Program Files\\Git\\cmd\\git.exe",
+                "C:\\Program Files (x86)\\Git\\bin\\git.exe",
+                "C:\\Program Files (x86)\\Git\\cmd\\git.exe",
+            ]
+            : [
+                "/usr/bin/git",
+                "/usr/local/bin/git",
+                "/opt/homebrew/bin/git",
+            ];
+
+        const runtimeRequire = this.getRuntimeRequire();
+        if (!runtimeRequire) {
+            return candidates[0];
+        }
+
+        const runtimeProcess = this.getRuntimeProcess();
+        const pathValue = runtimeProcess?.env?.PATH ?? "";
+        const separator = this.getRuntimePlatform() === "win32" ? ";" : ":";
+        const pathEntries = pathValue
+            .split(separator)
+            .map((entry) => entry.trim())
+            .filter(Boolean)
+            .map((entry) => entry.replace(/[\\/]+$/, ""));
+
+        const pathOrderedCandidates = candidates
+            .map((candidate) => ({
+                candidate,
+                dir: this.getExecutableDirectory(candidate),
+            }))
+            .sort((left, right) => {
+                const leftIndex = pathEntries.findIndex((entry) => entry === left.dir);
+                const rightIndex = pathEntries.findIndex((entry) => entry === right.dir);
+                if (leftIndex === -1 && rightIndex === -1) return 0;
+                if (leftIndex === -1) return 1;
+                if (rightIndex === -1) return -1;
+                return leftIndex - rightIndex;
+            })
+            .map((entry) => entry.candidate);
+
+        for (const candidate of pathOrderedCandidates) {
+            if (this.isExecutableFile(candidate)) {
+                return candidate;
+            }
+        }
+
+        return candidates[0];
+    }
+
+    private resolveRepoPath(rawValue: unknown): string {
+        const requestedRaw = typeof rawValue === "string" && rawValue.trim()
+            ? rawValue
+            : this.getDefaultRepoPath();
+        const requested = this.normalizeInputPath(requestedRaw);
+        const canCheckFilesystem = this.getRuntimeRequire() !== null;
+
+        if (!this.isAbsolutePath(requested)) {
+            throw new Error(`Repository path must be absolute: ${requested}`);
+        }
+        if (canCheckFilesystem && !this.fileExists(requested)) {
+            throw new Error(`Repository path does not exist: ${requested}`);
+        }
+        if (!this.isLikelyDirectoryPath(requested)) {
+            throw new Error(`Repository path must point to a directory: ${requested}`);
+        }
+
+        return requested;
+    }
+
+    private buildReadRemoteOriginRequest(repoPath: string) {
+        return createPrivilegedActionBackendRequest(
+            createOperatorToolActionRequest("git", {
+                command: this.gitCommand,
+                args: ["config", "--get", "remote.origin.url"],
+                cwd: repoPath,
+                timeoutMs: 8000,
+                dryRun: false,
+                reason: `read remote.origin.url through host-mediated scoped Git execution (repository path: ${repoPath})`,
+            }),
+            { correlationIdPrefix: "git-prefetch-origin" }
+        );
+    }
+
+    private parseGitHubRepositoryFromRemote(remoteUrl: string): {
+        owner: string;
+        repository: string;
+        remoteUrl: string;
+        apiUrl: string;
+        htmlUrl: string;
+    } | null {
+        const normalized = String(remoteUrl || "").trim();
+        if (!normalized) {
+            return null;
+        }
+
+        const sshMatch = normalized.match(/^git@github\.com:([^/]+)\/([^/]+?)(?:\.git)?$/i);
+        const httpsMatch = normalized.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/i);
+        const match = sshMatch ?? httpsMatch;
+        if (!match) {
+            return null;
+        }
+
+        const owner = match[1].trim();
+        const repository = match[2].trim();
+        if (!owner || !repository) {
+            return null;
+        }
+
+        return {
+            owner,
+            repository,
+            remoteUrl: `https://github.com/${owner}/${repository}`,
+            apiUrl: `https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repository)}`,
+            htmlUrl: `https://github.com/${owner}/${repository}`,
+        };
+    }
+
+    private normalizeRemoteToHttpsUrl(remoteUrl: string): string {
+        const normalized = String(remoteUrl || "").trim();
+        if (!normalized) {
+            return "";
+        }
+
+        if (/^https:\/\//i.test(normalized)) {
+            return normalized.replace(/\.git$/i, "");
+        }
+
+        const sshScpStyleMatch = normalized.match(/^git@([^:]+):(.+?)(?:\.git)?$/i);
+        if (sshScpStyleMatch) {
+            const host = sshScpStyleMatch[1].trim();
+            const path = sshScpStyleMatch[2].trim().replace(/^\//, "");
+            if (host && path) {
+                return `https://${host}/${path}`;
+            }
+        }
+
+        try {
+            const parsed = new URL(normalized);
+            if (parsed.protocol === "ssh:" || parsed.protocol === "git+ssh:") {
+                const pathname = parsed.pathname.replace(/^\/+/, "").replace(/\.git$/i, "");
+                const host = parsed.hostname;
+                if (host && pathname) {
+                    return `https://${host}/${pathname}`;
+                }
+            }
+        } catch {
+            return "";
+        }
+
+        return "";
+    }
+
+    private async prefetchRemoteRepositoryMetadata(remoteOriginUrlInput: string): Promise<Record<string, unknown>> {
+        requireCapability("system.network", "prefetch original configured repository metadata");
+        requireCapability("system.network.https", "prefetch original configured repository metadata");
+        requireNetworkScopeCapability(
+            GitOperationsPlugin.NETWORK_SCOPE_ID,
+            "prefetch original configured repository metadata"
+        );
+
+        const remoteOriginUrl = String(remoteOriginUrlInput || "").trim();
+        if (!remoteOriginUrl) {
+            throw new Error(
+                "Repository metadata prefetch failed: direct Git config inspection is unavailable in this runtime. Run scoped Git remote-origin request first and pass remoteOriginUrl."
+            );
+        }
+        const runtimeFetch = (globalThis as { fetch?: (...args: unknown[]) => Promise<unknown> }).fetch;
+        if (typeof runtimeFetch !== "function") {
+            throw new Error("Runtime fetch API is unavailable; cannot prefetch repository metadata.");
+        }
+
+        const githubRepository = this.parseGitHubRepositoryFromRemote(remoteOriginUrl);
+        if (githubRepository) {
+            const rawResponse = await runtimeFetch(githubRepository.apiUrl, {
+                method: "GET",
+                headers: {
+                    Accept: "application/vnd.github+json",
+                    "User-Agent": "fdo-sdk-git-operations-plugin",
+                },
+            });
+
+            const response = rawResponse as {
+                ok?: boolean;
+                status?: number;
+                statusText?: string;
+                json?: () => Promise<unknown>;
+                text?: () => Promise<string>;
+            };
+
+            if (!response || response.ok !== true) {
+                const body = typeof response?.text === "function"
+                    ? String((await response.text()) || "").slice(0, 400)
+                    : "";
+                const status = typeof response?.status === "number" ? response.status : 0;
+                const statusText = typeof response?.statusText === "string" ? response.statusText : "unknown";
+                throw new Error(`Remote metadata request failed (${status} ${statusText}). ${body}`.trim());
+            }
+
+            if (typeof response.json !== "function") {
+                throw new Error("Remote metadata response does not expose a JSON parser.");
+            }
+
+            const payload = await response.json();
+            const data = typeof payload === "object" && payload !== null
+                ? payload as Record<string, unknown>
+                : {};
+
+            return {
+                provider: "github",
+                repository: `${githubRepository.owner}/${githubRepository.repository}`,
+                remoteOriginUrl,
+                normalizedRemoteUrl: githubRepository.remoteUrl,
+                apiUrl: githubRepository.apiUrl,
+                htmlUrl: typeof data.html_url === "string" && data.html_url.trim()
+                    ? data.html_url
+                    : githubRepository.htmlUrl,
+                defaultBranch: typeof data.default_branch === "string" ? data.default_branch : "",
+                visibility:
+                    typeof data.visibility === "string"
+                        ? data.visibility
+                        : (typeof data.private === "boolean" ? (data.private ? "private" : "public") : ""),
+                description: typeof data.description === "string" ? data.description : "",
+                stars: typeof data.stargazers_count === "number" ? data.stargazers_count : 0,
+                forks: typeof data.forks_count === "number" ? data.forks_count : 0,
+                openIssues: typeof data.open_issues_count === "number" ? data.open_issues_count : 0,
+                fetchedAt: new Date().toISOString(),
+            };
+        }
+
+        const normalizedRemoteUrl = this.normalizeRemoteToHttpsUrl(remoteOriginUrl);
+        if (!normalizedRemoteUrl) {
+            throw new Error(
+                `Remote origin "${remoteOriginUrl}" cannot be normalized to HTTPS for metadata prefetch.`
+            );
+        }
+
+        const rawResponse = await runtimeFetch(normalizedRemoteUrl, { method: "HEAD" });
+        const response = rawResponse as {
+            ok?: boolean;
+            status?: number;
+            statusText?: string;
+        };
+        const status = typeof response?.status === "number" ? response.status : 0;
+        const statusText = typeof response?.statusText === "string" ? response.statusText : "unknown";
+        if (!response || response.ok !== true) {
+            throw new Error(`Remote repository reachability check failed (${status} ${statusText}).`);
+        }
+
+        return {
+            provider: "generic",
+            remoteOriginUrl,
+            normalizedRemoteUrl,
+            status,
+            statusText,
+            reachable: true,
+            fetchedAt: new Date().toISOString(),
+        };
+    }
+
+    private getStoredRepoPath(): string {
+        const candidate = this.readState<string>(GitOperationsPlugin.STORAGE_KEYS.REPO_PATH) ?? "";
+        if (typeof candidate === "string" && this.isAbsolutePath(candidate.trim())) {
+            return candidate.trim();
+        }
+        return this.getDefaultRepoPath();
+    }
+
+    private getStoredRepoPathSafe(): string {
+        try {
+            return this.getStoredRepoPath();
+        } catch (error) {
+            this.warn("Failed to resolve stored repository path. Falling back to default path.", { error });
+            return this.getDefaultRepoPath();
+        }
+    }
+
+    private ensureOriginalConfiguredRepo(pathValue: string): {
+        originalConfiguredRepoPath: string;
+        originalConfiguredRepoPublicKey: string;
+        persistence: "persistent-json" | "session-fallback";
+    } {
+        const normalized = this.resolveRepoPath(pathValue);
+        const existingCandidate = this.readState<string>(GitOperationsPlugin.STORAGE_KEYS.ORIGINAL_CONFIGURED_REPO_PATH) ?? "";
+        const existing = typeof existingCandidate === "string" && this.isAbsolutePath(existingCandidate.trim())
+            ? existingCandidate.trim()
+            : "";
+
+        const originalConfiguredRepoPath = existing || normalized;
+        const pathPersistence = this.writeState(
+            GitOperationsPlugin.STORAGE_KEYS.ORIGINAL_CONFIGURED_REPO_PATH,
+            originalConfiguredRepoPath
+        );
+        const publicKeyPersistence = this.writeState(
+            GitOperationsPlugin.STORAGE_KEYS.ORIGINAL_CONFIGURED_REPO_PUBLIC_KEY,
+            GitOperationsPlugin.ORIGINAL_CONFIGURED_REPO_PUBLIC_KEY
+        );
+
+        return {
+            originalConfiguredRepoPath,
+            originalConfiguredRepoPublicKey: GitOperationsPlugin.ORIGINAL_CONFIGURED_REPO_PUBLIC_KEY,
+            persistence:
+                pathPersistence === "persistent-json" && publicKeyPersistence === "persistent-json"
+                    ? "persistent-json"
+                    : "session-fallback",
+        };
+    }
+
+    private saveRepoPath(pathValue: string): {
+        storedPath: string;
+        persistence: "persistent-json" | "session-fallback";
+        originalConfiguredRepoPath: string;
+        originalConfiguredRepoPublicKey: string;
+        originalConfiguredRepoPersistence: "persistent-json" | "session-fallback";
+    } {
+        const normalized = this.resolveRepoPath(pathValue);
+        const originalConfiguredRepo = this.ensureOriginalConfiguredRepo(normalized);
+        this.repoPathForRender = normalized;
+        const persistence = this.writeState(GitOperationsPlugin.STORAGE_KEYS.REPO_PATH, normalized);
+        this.writeState(
+            GitOperationsPlugin.STORAGE_KEYS.LAST_ACTION,
+            `${persistence === "persistent-json" ? "saved-repo-path" : "saved-repo-path-session"}:${normalized}`
+        );
+        return {
+            storedPath: normalized,
+            persistence,
+            originalConfiguredRepoPath: originalConfiguredRepo.originalConfiguredRepoPath,
+            originalConfiguredRepoPublicKey: originalConfiguredRepo.originalConfiguredRepoPublicKey,
+            originalConfiguredRepoPersistence: originalConfiguredRepo.persistence,
+        };
+    }
+
+    private readState<T = unknown>(key: string): T | undefined {
+        this.ensurePersistentStore();
+        if (this.persistentStore) {
+            try {
+                const persistentValue = this.persistentStore.get<T>(key);
+                if (persistentValue !== undefined) {
+                    return persistentValue;
+                }
+            } catch (error) {
+                this.warn("Persistent JSON store read failed. Falling back to session store.", { key, error });
+                this.persistentStore = undefined;
+                this.jsonStoreAvailable = false;
+                const reason = error instanceof Error ? error.message : String(error);
+                this.persistentStoreDiagnostic = this.sanitizeStorageErrorReason(reason) || "Persistent JSON store read failed.";
+            }
+        }
+
+        const fallbackStore = this.getFallbackStore();
+        return fallbackStore.get<T>(key);
+    }
+
+    private writeState<T = unknown>(key: string, value: T): "persistent-json" | "session-fallback" {
+        this.ensurePersistentStore();
+        const fallbackStore = this.getFallbackStore();
+        fallbackStore.set<T>(key, value);
+
+        if (this.persistentStore) {
+            try {
+                this.persistentStore.set<T>(key, value);
+                this.persistentStoreDiagnostic = "";
+                return "persistent-json";
+            } catch (error) {
+                this.warn("Persistent JSON store write failed. Falling back to session store.", { key, error });
+                this.persistentStore = undefined;
+                this.jsonStoreAvailable = false;
+                const reason = error instanceof Error ? error.message : String(error);
+                this.persistentStoreDiagnostic = this.sanitizeStorageErrorReason(reason) || "Persistent JSON store write failed.";
+            }
+        }
+
+        return "session-fallback";
+    }
+
+    private isOperationId(value: unknown): value is GitOperationId {
+        return typeof value === "string" && Object.prototype.hasOwnProperty.call(GIT_OPERATIONS, value);
+    }
+
+    private buildFallbackCommitMessage(input: {
+        summary?: unknown;
+        repoPath?: unknown;
+    }): string {
+        const summary = typeof input.summary === "object" && input.summary !== null
+            ? input.summary as Record<string, unknown>
+            : {};
+        const staged = typeof summary.staged === "number" ? summary.staged : 0;
+        const modified = typeof summary.modified === "number" ? summary.modified : 0;
+        const untracked = typeof summary.untracked === "number" ? summary.untracked : 0;
+        const branch = typeof summary.branch === "string" && summary.branch.trim()
+            ? summary.branch.trim()
+            : "current-branch";
+        const repoPath = typeof input.repoPath === "string" && input.repoPath.trim()
+            ? input.repoPath.trim()
+            : "repository";
+        const repoName = repoPath.split(/[\\/]/).filter(Boolean).pop() || "repo";
+
+        if (staged > 0 || modified > 0 || untracked > 0) {
+            return `chore(${repoName}): update working tree on ${branch} (staged:${staged} modified:${modified} untracked:${untracked})`;
+        }
+
+        return `chore(${repoName}): update repository changes on ${branch}`;
+    }
+
+    private registerHandlers(): void {
+        if (this.handlersRegistered) {
+            return;
+        }
+        this.handlersRegistered = true;
+
+        PluginRegistry.registerHandler(GitOperationsPlugin.PREPARE_HANDLER, () => {
+            try {
+                this.ensurePersistentStore();
+                const originalConfiguredRepo = this.ensureOriginalConfiguredRepo(this.repoPathForRender);
+                return {
+                    ok: true,
+                    gitCommand: this.gitCommand,
+                    defaultRepoPath: this.repoPathForRender,
+                    originalConfiguredRepoPath: originalConfiguredRepo.originalConfiguredRepoPath,
+                    originalConfiguredRepoPublicKey: originalConfiguredRepo.originalConfiguredRepoPublicKey,
+                    originalConfiguredRepoPersistence: originalConfiguredRepo.persistence,
+                    jsonStoreAvailable: this.jsonStoreAvailable,
+                    storageMode: this.jsonStoreAvailable ? "persistent-json" : "session-fallback",
+                    storageDiagnostic: this.jsonStoreAvailable ? "" : this.getStorageDiagnostic(),
+                    lastAction: this.readState<string>(GitOperationsPlugin.STORAGE_KEYS.LAST_ACTION) ?? "none",
+                    operations: Object.entries(GIT_OPERATIONS).map(([id, definition]) => ({
+                        id,
+                        title: definition.title,
+                        args: definition.args,
+                    })),
+                };
+            } catch (error) {
+                return {
+                    ok: false,
+                    code: "PREPARE_FAILED",
+                    error: error instanceof Error ? error.message : String(error),
+                    gitCommand: this.gitCommand,
+                    defaultRepoPath: this.getDefaultRepoPath(),
+                    originalConfiguredRepoPath: this.getDefaultRepoPath(),
+                    originalConfiguredRepoPublicKey: GitOperationsPlugin.ORIGINAL_CONFIGURED_REPO_PUBLIC_KEY,
+                    originalConfiguredRepoPersistence: this.jsonStoreAvailable ? "persistent-json" : "session-fallback",
+                    storageMode: this.jsonStoreAvailable ? "persistent-json" : "session-fallback",
+                    storageDiagnostic: this.jsonStoreAvailable ? "" : this.getStorageDiagnostic(),
+                    lastAction: "prepare-failed",
+                    operations: [],
+                };
+            }
+        });
+
+        PluginRegistry.registerHandler(GitOperationsPlugin.QUICK_STATUS_HANDLER, () => {
+            this.writeState(GitOperationsPlugin.STORAGE_KEYS.LAST_ACTION, "quick-action:status");
+            return {
+                ok: true,
+                intent: "run-operation",
+                operation: "status",
+                message: "Quick action registered. Open plugin to run Status.",
+            };
+        });
+
+        PluginRegistry.registerHandler(GitOperationsPlugin.QUICK_SNAPSHOT_HANDLER, () => {
+            this.writeState(GitOperationsPlugin.STORAGE_KEYS.LAST_ACTION, "quick-action:snapshot");
+            return {
+                ok: true,
+                intent: "run-snapshot",
+                message: "Quick action registered. Open plugin to run Snapshot.",
+            };
+        });
+
+        PluginRegistry.registerHandler(GitOperationsPlugin.QUICK_PREFETCH_HANDLER, () => {
+            this.writeState(GitOperationsPlugin.STORAGE_KEYS.LAST_ACTION, "quick-action:prefetch");
+            return {
+                ok: true,
+                intent: "prefetch-original-repo",
+                message: "Quick action registered. Open plugin to prefetch original repository.",
+            };
+        });
+
+        PluginRegistry.registerHandler(GitOperationsPlugin.SIDE_PANEL_CONSOLE_HANDLER, () => ({
+            ok: true,
+            intent: "open-console",
+            message: "Git console is ready.",
+        }));
+
+        PluginRegistry.registerHandler(GitOperationsPlugin.SIDE_PANEL_RECENT_HANDLER, () => ({
+            ok: true,
+            intent: "open-recent-runs",
+            lastAction: this.readState<string>(GitOperationsPlugin.STORAGE_KEYS.LAST_ACTION) ?? "none",
+        }));
+
+        PluginRegistry.registerHandler(GitOperationsPlugin.SIDE_PANEL_PROFILES_HANDLER, () => ({
+            ok: true,
+            intent: "open-repo-profiles",
+            currentRepo: this.readState<string>(GitOperationsPlugin.STORAGE_KEYS.REPO_PATH) ?? this.repoPathForRender,
+        }));
+
+        PluginRegistry.registerHandler(GitOperationsPlugin.SAVE_REPO_PATH_HANDLER, (data: unknown) => {
+            try {
+                const payload = typeof data === "object" && data !== null
+                    ? data as { cwd?: unknown }
+                    : {};
+                if (typeof payload.cwd !== "string" || !payload.cwd.trim()) {
+                    return {
+                        ok: false,
+                        code: "INVALID_REPO_PATH",
+                        error: "Repository path is required.",
+                    };
+                }
+                const result = this.saveRepoPath(payload.cwd);
+                return {
+                    ok: true,
+                    ...result,
+                    storageDiagnostic: result.persistence === "session-fallback" ? this.getStorageDiagnostic() : "",
+                };
+            } catch (error) {
+                return {
+                    ok: false,
+                    code: "SAVE_REPO_PATH_FAILED",
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        });
+
+        PluginRegistry.registerHandler(GitOperationsPlugin.PREFETCH_ORIGINAL_REPO_REQUEST_HANDLER, (data: unknown) => {
+            try {
+                const payload = typeof data === "object" && data !== null
+                    ? data as { cwd?: unknown }
+                    : {};
+                const fallbackCandidate = typeof payload.cwd === "string" && payload.cwd.trim()
+                    ? payload.cwd
+                    : this.repoPathForRender;
+                const result = this.ensureOriginalConfiguredRepo(fallbackCandidate);
+                const requestEnvelope = this.buildReadRemoteOriginRequest(result.originalConfiguredRepoPath);
+                this.writeState(
+                    GitOperationsPlugin.STORAGE_KEYS.LAST_ACTION,
+                    `prefetch-origin-request:${result.persistence}`
+                );
+                return {
+                    ok: true,
+                    ...result,
+                    requestEnvelope,
+                    storageDiagnostic: result.persistence === "session-fallback" ? this.getStorageDiagnostic() : "",
+                };
+            } catch (error) {
+                return {
+                    ok: false,
+                    code: "PREFETCH_ORIGINAL_REPO_REQUEST_FAILED",
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        });
+
+        PluginRegistry.registerHandler(GitOperationsPlugin.PREFETCH_ORIGINAL_REPO_HANDLER, async (data: unknown) => {
+            try {
+                const payload = typeof data === "object" && data !== null
+                    ? data as { cwd?: unknown; remoteOriginUrl?: unknown }
+                    : {};
+                const fallbackCandidate = typeof payload.cwd === "string" && payload.cwd.trim()
+                    ? payload.cwd
+                    : this.repoPathForRender;
+                const result = this.ensureOriginalConfiguredRepo(fallbackCandidate);
+                const remoteOriginUrl = typeof payload.remoteOriginUrl === "string"
+                    ? payload.remoteOriginUrl.trim()
+                    : "";
+                if (!remoteOriginUrl) {
+                    return {
+                        ok: true,
+                        ...result,
+                        remoteOriginUrl: "",
+                        remoteRepository: null,
+                        warning: "Remote origin URL is unavailable. Prefetch completed without metadata.",
+                        storageDiagnostic: result.persistence === "session-fallback" ? this.getStorageDiagnostic() : "",
+                    };
+                }
+                let remoteRepository: Record<string, unknown> | null = null;
+                let warning = "";
+                try {
+                    remoteRepository = await this.prefetchRemoteRepositoryMetadata(remoteOriginUrl);
+                } catch (metadataError) {
+                    warning = metadataError instanceof Error ? metadataError.message : String(metadataError);
+                }
+                this.repoPathForRender = result.originalConfiguredRepoPath;
+                this.writeState(GitOperationsPlugin.STORAGE_KEYS.REPO_PATH, result.originalConfiguredRepoPath);
+                this.writeState(
+                    GitOperationsPlugin.STORAGE_KEYS.LAST_ACTION,
+                    `prefetched-original-configured-repo:${result.persistence}`
+                );
+                return {
+                    ok: true,
+                    ...result,
+                    remoteOriginUrl,
+                    remoteRepository,
+                    warning: warning || undefined,
+                    storageDiagnostic: result.persistence === "session-fallback" ? this.getStorageDiagnostic() : "",
+                };
+            } catch (error) {
+                return {
+                    ok: false,
+                    code: "PREFETCH_ORIGINAL_REPO_FAILED",
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        });
+
+        PluginRegistry.registerHandler(GitOperationsPlugin.BUILD_REQUEST_HANDLER, (data: unknown) => {
+            try {
+                const payload = typeof data === "object" && data !== null
+                    ? data as { operation?: unknown; cwd?: unknown; dryRun?: unknown }
+                    : {};
+
+                if (!this.isOperationId(payload.operation)) {
+                    return {
+                        ok: false,
+                        code: "INVALID_OPERATION",
+                        error: "Unsupported Git operation requested.",
+                    };
+                }
+
+                const operation = payload.operation;
+                const definition = GIT_OPERATIONS[operation];
+                const cwd = this.resolveRepoPath(payload.cwd);
+                const dryRun = payload.dryRun === true;
+                const persisted = this.saveRepoPath(cwd);
+                const request = createOperatorToolActionRequest("git", {
+                    command: this.gitCommand,
+                    args: definition.args,
+                    cwd,
+                    timeoutMs: definition.timeoutMs,
+                    dryRun,
+                    reason: `${definition.reason} (repository path: ${cwd})`,
+                });
+                this.writeState(
+                    GitOperationsPlugin.STORAGE_KEYS.LAST_ACTION,
+                    `built-request:${operation}:${dryRun ? "dry-run:" : ""}${persisted.persistence}`
+                );
+
+                return createPrivilegedActionBackendRequest(request, {
+                    correlationIdPrefix: `git-${operation}`,
+                });
+            } catch (error) {
+                return {
+                    ok: false,
+                    code: "BUILD_REQUEST_FAILED",
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        });
+
+        PluginRegistry.registerHandler(GitOperationsPlugin.BUILD_COMMIT_REQUEST_HANDLER, (data: unknown) => {
+            try {
+                const payload = typeof data === "object" && data !== null
+                    ? data as { cwd?: unknown; message?: unknown; dryRun?: unknown }
+                    : {};
+                const cwd = this.resolveRepoPath(payload.cwd);
+                const message = typeof payload.message === "string" ? payload.message.trim() : "";
+                if (!message) {
+                    return {
+                        ok: false,
+                        code: "COMMIT_MESSAGE_REQUIRED",
+                        error: "Commit message is required.",
+                    };
+                }
+                const dryRun = payload.dryRun === true;
+                const persisted = this.saveRepoPath(cwd);
+                const args = dryRun
+                    ? ["commit", "--dry-run", "-m", message]
+                    : ["commit", "-m", message];
+                const request = createOperatorToolActionRequest("git", {
+                    command: this.gitCommand,
+                    args,
+                    cwd,
+                    timeoutMs: GIT_OPERATIONS.commitStaged.timeoutMs,
+                    dryRun,
+                    reason: `${GIT_OPERATIONS.commitStaged.reason} (repository path: ${cwd})`,
+                });
+                this.writeState(
+                    GitOperationsPlugin.STORAGE_KEYS.LAST_ACTION,
+                    `built-request:commitStaged:${dryRun ? "dry-run:" : ""}${persisted.persistence}`
+                );
+
+                return createPrivilegedActionBackendRequest(request, {
+                    correlationIdPrefix: "git-commit",
+                });
+            } catch (error) {
+                return {
+                    ok: false,
+                    code: "BUILD_COMMIT_REQUEST_FAILED",
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        });
+
+        const resolveAiAssistantsListRequest = (data: unknown) => {
+            try {
+                const payload = typeof data === "object" && data !== null
+                    ? data as { purpose?: unknown; provider?: unknown; model?: unknown }
+                    : {};
+                const purposeFilter = typeof payload.purpose === "string" ? payload.purpose.trim().toLowerCase() : "";
+                const providerFilter = typeof payload.provider === "string" ? payload.provider.trim().toLowerCase() : "";
+                const modelFilter = typeof payload.model === "string" ? payload.model.trim().toLowerCase() : "";
+                const listProvider = (globalThis as {
+                    __FDO_AI_LIST_ASSISTANTS?: ((input: {
+                        purpose?: string;
+                        provider?: string;
+                        model?: string;
+                    }) => unknown);
+                    __FDO_AI_ASSISTANTS?: unknown[] | { assistants?: unknown[] };
+                }).__FDO_AI_LIST_ASSISTANTS;
+                const staticAssistants = (globalThis as {
+                    __FDO_AI_ASSISTANTS?: unknown[] | { assistants?: unknown[] };
+                }).__FDO_AI_ASSISTANTS;
+
+                const normalize = (value: unknown) => {
+                    const raw = Array.isArray(value)
+                        ? value
+                        : (
+                            typeof value === "object"
+                            && value !== null
+                            && Array.isArray((value as { assistants?: unknown[] }).assistants)
+                                ? (value as { assistants?: unknown[] }).assistants || []
+                                : []
+                        );
+                    const seen = new Set<string>();
+                    const normalized = raw
+                        .map((item, index) => {
+                            if (typeof item !== "object" || item === null) {
+                                return null;
+                            }
+                            const record = item as Record<string, unknown>;
+                            const id = typeof record.id === "string" ? record.id.trim() : "";
+                            if (!id || seen.has(id)) {
+                                return null;
+                            }
+                            seen.add(id);
+                            const name = typeof record.name === "string" && record.name.trim()
+                                ? record.name.trim()
+                                : `assistant-${index + 1}`;
+                            const purpose = typeof record.purpose === "string" ? record.purpose.trim() : "";
+                            const provider = typeof record.provider === "string" ? record.provider.trim() : "";
+                            const model = typeof record.model === "string" ? record.model.trim() : "";
+                            const isDefault = record.default === true || record.isDefault === true;
+                            return {
+                                id,
+                                name,
+                                purpose,
+                                provider,
+                                model,
+                                default: isDefault,
+                            };
+                        })
+                        .filter((item): item is {
+                            id: string;
+                            name: string;
+                            purpose: string;
+                            provider: string;
+                            model: string;
+                            default: boolean;
+                        } => Boolean(item))
+                        .filter((item) => {
+                            if (purposeFilter && item.purpose.toLowerCase() !== purposeFilter) {
+                                return false;
+                            }
+                            if (providerFilter && item.provider.toLowerCase() !== providerFilter) {
+                                return false;
+                            }
+                            if (modelFilter && item.model.toLowerCase() !== modelFilter) {
+                                return false;
+                            }
+                            return true;
+                        })
+                        .sort((a, b) => {
+                            if (a.default !== b.default) {
+                                return a.default ? -1 : 1;
+                            }
+                            return a.name.localeCompare(b.name);
+                        })
+                        .slice(0, 100);
+                    return normalized;
+                };
+
+                const toResult = (value: unknown) => {
+                    const normalized = normalize(value);
+                    return {
+                        ok: true,
+                        source: typeof listProvider === "function" ? "fdo-ai-provider" : "fdo-ai-static",
+                        assistants: normalized,
+                    };
+                };
+
+                if (typeof listProvider === "function") {
+                    const result = listProvider({
+                        purpose: purposeFilter || undefined,
+                        provider: providerFilter || undefined,
+                        model: modelFilter || undefined,
+                    }) as unknown;
+
+                    if (result && typeof (result as Promise<unknown>).then === "function") {
+                        return (result as Promise<unknown>).then((resolved) => toResult(resolved));
+                    }
+
+                    return toResult(result);
+                }
+
+                if (Array.isArray(staticAssistants)) {
+                    return toResult(staticAssistants);
+                }
+                if (typeof staticAssistants === "object" && staticAssistants !== null) {
+                    return toResult(staticAssistants);
+                }
+
+                return {
+                    ok: true,
+                    source: "fallback",
+                    assistants: [],
+                    warning: "FDO AI assistants provider is not configured.",
+                };
+            } catch (error) {
+                return {
+                    ok: false,
+                    code: "AI_ASSISTANTS_LIST_FAILED",
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        };
+
+        PluginRegistry.registerHandler(GitOperationsPlugin.AI_ASSISTANTS_LIST_HANDLER, (data: unknown) => {
+            return resolveAiAssistantsListRequest(data);
+        });
+
+        const resolveAiAssistRequest = (data: unknown) => {
+            try {
+                const payload = typeof data === "object" && data !== null
+                    ? data as {
+                        task?: unknown;
+                        summary?: unknown;
+                        repoPath?: unknown;
+                        prompt?: unknown;
+                        commandOutput?: unknown;
+                        recentRuns?: unknown;
+                        assistantId?: unknown;
+                        assistantPurpose?: unknown;
+                        assistantProvider?: unknown;
+                        assistantModel?: unknown;
+                    }
+                    : {};
+                const task = typeof payload.task === "string" && payload.task.trim()
+                    ? payload.task.trim()
+                    : "commit-message";
+
+                const provider = (globalThis as {
+                    __FDO_AI_REQUEST?: ((input: {
+                        task: string;
+                        summary?: unknown;
+                        repoPath?: string;
+                        prompt?: string;
+                        commandOutput?: string;
+                        recentRuns?: unknown;
+                        assistantId?: string;
+                        assistantPurpose?: string;
+                        assistantProvider?: string;
+                        assistantModel?: string;
+                    }) => unknown);
+                    __FDO_AI_ASSISTANT?: ((input: {
+                        task: string;
+                        summary?: unknown;
+                        repoPath?: string;
+                        prompt?: string;
+                        commandOutput?: string;
+                        recentRuns?: unknown;
+                        assistantId?: string;
+                        assistantPurpose?: string;
+                        assistantProvider?: string;
+                        assistantModel?: string;
+                    }) => unknown);
+                }).__FDO_AI_REQUEST;
+                const legacyProvider = (globalThis as {
+                    __FDO_AI_ASSISTANT?: ((input: {
+                        task: string;
+                        summary?: unknown;
+                        repoPath?: string;
+                        prompt?: string;
+                        commandOutput?: string;
+                        recentRuns?: unknown;
+                        assistantId?: string;
+                        assistantPurpose?: string;
+                        assistantProvider?: string;
+                        assistantModel?: string;
+                    }) => unknown);
+                }).__FDO_AI_ASSISTANT;
+                const aiProvider = typeof provider === "function" ? provider : legacyProvider;
+
+                if (typeof aiProvider === "function") {
+                    const providerResult = aiProvider({
+                        task,
+                        summary: payload.summary,
+                        repoPath: typeof payload.repoPath === "string" ? payload.repoPath : undefined,
+                        prompt: typeof payload.prompt === "string" ? payload.prompt : undefined,
+                        commandOutput: typeof payload.commandOutput === "string" ? payload.commandOutput : undefined,
+                        recentRuns: payload.recentRuns,
+                        assistantId: typeof payload.assistantId === "string" ? payload.assistantId : undefined,
+                        assistantPurpose: typeof payload.assistantPurpose === "string" ? payload.assistantPurpose : undefined,
+                        assistantProvider: typeof payload.assistantProvider === "string" ? payload.assistantProvider : undefined,
+                        assistantModel: typeof payload.assistantModel === "string" ? payload.assistantModel : undefined,
+                    }) as unknown;
+
+                    if (providerResult && typeof (providerResult as Promise<unknown>).then === "function") {
+                        return (providerResult as Promise<unknown>).then((resolved) => {
+                            const candidate = typeof resolved === "object" && resolved !== null
+                                ? resolved as { message?: unknown; commitMessage?: unknown; text?: unknown }
+                                : {};
+                            const message = typeof candidate.commitMessage === "string"
+                                ? candidate.commitMessage.trim()
+                                : (
+                                    typeof candidate.message === "string"
+                                        ? candidate.message.trim()
+                                        : (typeof candidate.text === "string" ? candidate.text.trim() : "")
+                                );
+                            if (!message) {
+                                return {
+                                    ok: false,
+                                    code: "AI_ASSIST_EMPTY",
+                                    error: `FDO AI provider returned an empty response for task "${task}".`,
+                                };
+                            }
+                            return {
+                                ok: true,
+                                source: "fdo-ai",
+                                task,
+                                message,
+                                commitMessage: task === "commit-message" ? message : undefined,
+                            };
+                        });
+                    }
+
+                    const syncCandidate = typeof providerResult === "object" && providerResult !== null
+                        ? providerResult as { message?: unknown; commitMessage?: unknown; text?: unknown }
+                        : {};
+                    const syncMessage = typeof syncCandidate.commitMessage === "string"
+                        ? syncCandidate.commitMessage.trim()
+                        : (
+                            typeof syncCandidate.message === "string"
+                                ? syncCandidate.message.trim()
+                                : (typeof syncCandidate.text === "string" ? syncCandidate.text.trim() : "")
+                        );
+                    if (syncMessage) {
+                        return {
+                            ok: true,
+                            source: "fdo-ai",
+                            task,
+                            message: syncMessage,
+                            commitMessage: task === "commit-message" ? syncMessage : undefined,
+                        };
+                    }
+                }
+
+                if (task === "summarize-output") {
+                    const output = typeof payload.commandOutput === "string" ? payload.commandOutput : "";
+                    const firstLines = output
+                        .split(/\r?\n/)
+                        .map((line) => line.trim())
+                        .filter(Boolean)
+                        .slice(0, 4)
+                        .join(" | ");
+                    return {
+                        ok: true,
+                        source: "fallback",
+                        task,
+                        message: firstLines
+                            ? `Local summary: ${firstLines}`
+                            : "Local summary: no command output available yet.",
+                        warning: "FDO AI provider is not configured. Using local fallback summary.",
+                    };
+                }
+
+                if (task === "suggest-next-command") {
+                    const summary = typeof payload.summary === "object" && payload.summary !== null
+                        ? payload.summary as { conflicts?: unknown; modified?: unknown; untracked?: unknown; branch?: unknown }
+                        : {};
+                    const conflicts = typeof summary.conflicts === "number" ? summary.conflicts : 0;
+                    const modified = typeof summary.modified === "number" ? summary.modified : 0;
+                    const untracked = typeof summary.untracked === "number" ? summary.untracked : 0;
+                    const branch = typeof summary.branch === "string" ? summary.branch : "current branch";
+                    let suggestion = "Run status to refresh repository diagnostics.";
+                    if (conflicts > 0) {
+                        suggestion = "Resolve conflicts first, then run status and commit staged changes.";
+                    } else if (modified > 0 || untracked > 0) {
+                        suggestion = "Run diff stat, stage intended files, then commit staged changes.";
+                    } else {
+                        suggestion = `Working tree looks clean on ${branch}. Consider fetch --all --prune then pull --ff-only.`;
+                    }
+                    return {
+                        ok: true,
+                        source: "fallback",
+                        task,
+                        message: suggestion,
+                        warning: "FDO AI provider is not configured. Using local fallback suggestion.",
+                    };
+                }
+
+                return {
+                    ok: true,
+                    source: "fallback",
+                    task,
+                    message: this.buildFallbackCommitMessage({
+                        summary: payload.summary,
+                        repoPath: payload.repoPath,
+                    }),
+                    commitMessage: this.buildFallbackCommitMessage({
+                        summary: payload.summary,
+                        repoPath: payload.repoPath,
+                    }),
+                    warning: "FDO AI provider is not configured. Using local fallback response.",
+                };
+            } catch (error) {
+                return {
+                    ok: false,
+                    code: "AI_ASSIST_FAILED",
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        };
+
+        PluginRegistry.registerHandler(GitOperationsPlugin.AI_ASSIST_HANDLER, (data: unknown) => {
+            return resolveAiAssistRequest(data);
+        });
+    }
+
+    init(): void {
+        this.registerHandlers();
+        this.runDeclaredCapabilityPreflight("initialize git operations plugin runtime");
+
+        try {
+            const fallbackStore = this.getFallbackStore();
+            this.ensurePersistentStore();
+
+            const bootRepoPath = this.getStoredRepoPathSafe();
+            const originalConfiguredRepo = this.ensureOriginalConfiguredRepo(bootRepoPath);
+            this.repoPathForRender = bootRepoPath;
+            this.writeState(GitOperationsPlugin.STORAGE_KEYS.REPO_PATH, bootRepoPath);
+            this.writeState(GitOperationsPlugin.STORAGE_KEYS.LAST_ACTION, "initialized");
+            // Keep a volatile mirror for diagnostics fallback when JSON is unavailable mid-session.
+            fallbackStore.set(GitOperationsPlugin.STORAGE_KEYS.REPO_PATH, bootRepoPath);
+            fallbackStore.set(
+                GitOperationsPlugin.STORAGE_KEYS.ORIGINAL_CONFIGURED_REPO_PATH,
+                originalConfiguredRepo.originalConfiguredRepoPath
+            );
+            fallbackStore.set(
+                GitOperationsPlugin.STORAGE_KEYS.ORIGINAL_CONFIGURED_REPO_PUBLIC_KEY,
+                originalConfiguredRepo.originalConfiguredRepoPublicKey
+            );
+            fallbackStore.set(GitOperationsPlugin.STORAGE_KEYS.LAST_ACTION, "initialized");
+
+            this.info("Git operations plugin initialized", {
+                gitCommand: this.gitCommand,
+                repoPath: bootRepoPath,
+                jsonStoreAvailable: this.jsonStoreAvailable,
+                requestedCapabilities: this.declaredCapabilities,
+            });
+        } catch (error) {
+            this.warn("Git operations plugin initialized in degraded mode. Handlers remain available.", { error });
+        }
+    }
+
+    render(): string {
+        const defaultRepoPath = this.repoPathForRender || this.getDefaultRepoPath();
+        const text = new DOMText();
+        const nested = new DOMNested();
+        const semantic = new DOMSemantic();
+        const button = new DOMButton();
+        const input = new DOMInput(
+            "git-repo-path",
+            {
+                classes: [this.cls("input")],
+                disableDefaultClass: true,
+            },
+            { value: defaultRepoPath }
+        );
+        const commitMessageInput = new DOMInput(
+            "git-commit-message",
+            {
+                classes: [this.cls("input")],
+                disableDefaultClass: true,
+            },
+            { placeholder: "Commit message (required for staged commit)" }
+        );
+        const aiPromptInput = new DOMInput(
+            "git-ai-prompt",
+            {
+                classes: [this.cls("aiPromptInput")],
+                disableDefaultClass: true,
+            },
+            { placeholder: "Optional AI context (e.g., ticket, incident, rollout note)" }
+        );
+        const aiAssistantSelectInput = new DOMInput(
+            "git-ai-assistant-select",
+            {
+                classes: [this.cls("input")],
+                disableDefaultClass: true,
+            }
+        );
+
+        const createActionButton = (id: string, label: string, classes: string[] = [this.cls("button")]) => {
+            return button.createStaticButton(
+                label,
+                {
+                    classes: classes.filter(Boolean),
+                    disableDefaultClass: true,
+                },
+                id,
+                { type: "button" }
+            );
+        };
+
+        const summaryGrid = nested.createBlockDiv(
+            [],
+            {
+                classes: [this.cls("summaryGrid")],
+                disableDefaultClass: true,
+                customAttributes: {
+                    "data-summary-item-class": this.cls("summaryItem"),
+                    "data-summary-label-class": this.cls("summaryLabel"),
+                    "data-summary-value-class": this.cls("summaryValue"),
+                },
+            },
+            "git-summary-grid"
+        );
+
+        const outputCode = text.createCodeText(
+            "$ waiting for command...",
+            {
+                classes: ["language-bash"],
+                disableDefaultClass: true,
+            },
+            "git-output-code"
+        );
+
+        const content = nested.createBlockDiv(
+            [
+                nested.createBlockDiv(
+                    [
+                        nested.createBlockDiv(
+                            [
+                                text.createHText(
+                                    2,
+                                    "Git Operations Console",
+                                    {
+                                        classes: [this.cls("heading")],
+                                        disableDefaultClass: true,
+                                    }
+                                ),
+                                text.createPText(
+                                    "Analyze repository status, branch state, commit history, and diff footprint through host-scoped Git execution.",
+                                    {
+                                        classes: [this.cls("subtitle")],
+                                        disableDefaultClass: true,
+                                    }
+                                ),
+                            ],
+                            {
+                                classes: [this.cls("headingWrap")],
+                                disableDefaultClass: true,
+                            }
+                        ),
+                        text.createSpanText(
+                            "Injected libs: Notyf + Highlight.js",
+                            {
+                                classes: [this.cls("badge")],
+                                disableDefaultClass: true,
+                            }
+                        ),
+                    ],
+                    {
+                        classes: [this.cls("top")],
+                        disableDefaultClass: true,
+                    }
+                ),
+                nested.createBlockDiv(
+                    [
+                        text.createLabelText(
+                            "Repository path (absolute path required)",
+                            "git-repo-path",
+                            {
+                                classes: [this.cls("label")],
+                                disableDefaultClass: true,
+                            }
+                        ),
+                        nested.createBlockDiv(
+                            [input.createInput("text")],
+                            {
+                                classes: [this.cls("inputRow")],
+                                disableDefaultClass: true,
+                            }
+                        ),
+                        nested.createBlockDiv(
+                            [
+                                createActionButton("git-save-path", "Save Path"),
+                                createActionButton("git-prefetch-original", "Prefetch Original Repo"),
+                                createActionButton("git-run-status", "Status", [this.cls("button"), this.cls("buttonPrimary")]),
+                                createActionButton("git-run-branches", "Branches"),
+                                createActionButton("git-run-log", "Recent Log"),
+                                createActionButton("git-run-diff", "Diff Stat"),
+                                createActionButton("git-run-show", "Show HEAD"),
+                                createActionButton("git-run-fetch", "Fetch --all --prune"),
+                                createActionButton("git-run-pull", "Pull --ff-only"),
+                                createActionButton("git-run-commit", "Commit Staged", [this.cls("button"), this.cls("buttonPrimary")]),
+                                createActionButton("git-run-snapshot", "Run Snapshot"),
+                            ],
+                            {
+                                classes: [this.cls("buttonRow")],
+                                disableDefaultClass: true,
+                            }
+                        ),
+                        nested.createBlockDiv(
+                            [
+                                commitMessageInput.createInput("text"),
+                                aiPromptInput.createInput("text"),
+                                aiAssistantSelectInput.createSelect([
+                                    aiAssistantSelectInput.createOption("AI Assistant: loading...", "", true),
+                                ]),
+                                createActionButton("git-ai-refresh-assistants", "Reload Assistants", [this.cls("buttonTiny")]),
+                                createActionButton("git-ai-commit-message", "AI: Commit Message", [this.cls("buttonTiny")]),
+                                createActionButton("git-ai-summarize-output", "AI: Summarize Output", [this.cls("buttonTiny")]),
+                                createActionButton("git-ai-suggest-next", "AI: Suggest Next Step", [this.cls("buttonTiny")]),
+                            ],
+                            {
+                                classes: [this.cls("commitRow")],
+                                disableDefaultClass: true,
+                            }
+                        ),
+                        text.createPText(
+                            "Staged files: run Status to preview files included in AI commit message generation.",
+                            {
+                                classes: [this.cls("meta")],
+                                disableDefaultClass: true,
+                            },
+                            "git-staged-files"
+                        ),
+                        text.createPText(
+                            "Runtime not prepared yet.",
+                            {
+                                classes: [this.cls("meta")],
+                                disableDefaultClass: true,
+                            },
+                            "git-command-meta"
+                        ),
+                    ],
+                    {
+                        classes: [this.cls("controls")],
+                        disableDefaultClass: true,
+                    }
+                ),
+                nested.createBlockDiv(
+                    [
+                        semantic.createSection(
+                            [
+                                text.createHText(
+                                    3,
+                                    "Repository Summary",
+                                    {
+                                        classes: [this.cls("panelTitle")],
+                                        disableDefaultClass: true,
+                                    }
+                                ),
+                                summaryGrid,
+                                text.createPText(
+                                    "Run Status to populate summary diagnostics.",
+                                    {
+                                        classes: [this.cls("summaryHint")],
+                                        disableDefaultClass: true,
+                                    },
+                                    "git-summary-hint"
+                                ),
+                                nested.createBlockDiv(
+                                    [
+                                        nested.createBlockDiv(
+                                            [
+                                                text.createPText(
+                                                    "Recent Runs",
+                                                    {
+                                                        classes: [this.cls("historyTitle")],
+                                                        disableDefaultClass: true,
+                                                    }
+                                                ),
+                                            ],
+                                            {
+                                                classes: [this.cls("historyHeader")],
+                                                disableDefaultClass: true,
+                                            }
+                                        ),
+                                        nested.createBlockDiv(
+                                            [],
+                                            {
+                                                classes: [this.cls("historyList")],
+                                                disableDefaultClass: true,
+                                                customAttributes: {
+                                                    "data-item-class": this.cls("historyItem"),
+                                                    "data-primary-class": this.cls("historyPrimary"),
+                                                    "data-meta-class": this.cls("historyMeta"),
+                                                    "data-status-ok-class": this.cls("historyStatusOk"),
+                                                    "data-status-failed-class": this.cls("historyStatusFailed"),
+                                                },
+                                            },
+                                            "git-history-list"
+                                        ),
+                                    ],
+                                    {
+                                        classes: [this.cls("historyWrap")],
+                                        disableDefaultClass: true,
+                                    }
+                                ),
+                            ],
+                            {
+                                classes: [this.cls("panel")],
+                                disableDefaultClass: true,
+                            }
+                        ),
+                        semantic.createSection(
+                            [
+                                text.createHText(
+                                    3,
+                                    "Command Output",
+                                    {
+                                        classes: [this.cls("panelTitle")],
+                                        disableDefaultClass: true,
+                                    }
+                                ),
+                                nested.createBlockDiv(
+                                    [
+                                        nested.createBlockDiv(
+                                            [outputCode],
+                                            {
+                                                classes: [this.cls("output")],
+                                                disableDefaultClass: true,
+                                            }
+                                        ),
+                                    ],
+                                    {
+                                        classes: [this.cls("outputWrap")],
+                                        disableDefaultClass: true,
+                                    }
+                                ),
+                            ],
+                            {
+                                classes: [this.cls("panel")],
+                                disableDefaultClass: true,
+                            }
+                        ),
+                    ],
+                    {
+                        classes: [this.cls("panels")],
+                        disableDefaultClass: true,
+                    }
+                ),
+            ],
+            {
+                classes: [this.cls("page")],
+                disableDefaultClass: true,
+                customAttributes: {
+                    "data-prepare-handler": GitOperationsPlugin.PREPARE_HANDLER,
+                    "data-save-repo-path-handler": GitOperationsPlugin.SAVE_REPO_PATH_HANDLER,
+                    "data-prefetch-request-handler": GitOperationsPlugin.PREFETCH_ORIGINAL_REPO_REQUEST_HANDLER,
+                    "data-prefetch-handler": GitOperationsPlugin.PREFETCH_ORIGINAL_REPO_HANDLER,
+                    "data-build-request-handler": GitOperationsPlugin.BUILD_REQUEST_HANDLER,
+                    "data-build-commit-request-handler": GitOperationsPlugin.BUILD_COMMIT_REQUEST_HANDLER,
+                    "data-build-id": GitOperationsPlugin.BUILD_ID,
+                    "data-ai-assist-handler": GitOperationsPlugin.AI_ASSIST_HANDLER,
+                    "data-ai-assistants-list-handler": GitOperationsPlugin.AI_ASSISTANTS_LIST_HANDLER,
+                    "data-ai-assistant-purpose": "automation",
+                    "data-ai-assistant-id": "",
+                    "data-ai-assistant-provider": "",
+                    "data-ai-assistant-model": "",
+                    "data-original-public-key": GitOperationsPlugin.ORIGINAL_CONFIGURED_REPO_PUBLIC_KEY,
+                },
+            },
+            "git-ops-root"
+        );
+
+        return this.dom.renderHTML(content);
+    }
+
+    renderOnLoad() {
+        function gitOperationsRenderOnLoad(): void {
+            const root = document.getElementById("git-ops-root");
+            const repoInput = document.getElementById("git-repo-path") as HTMLInputElement | null;
+            const outputCode = document.getElementById("git-output-code") as HTMLElement | null;
+            const summaryGrid = document.getElementById("git-summary-grid") as HTMLElement | null;
+            const summaryHint = document.getElementById("git-summary-hint") as HTMLElement | null;
+            const commandMeta = document.getElementById("git-command-meta") as HTMLElement | null;
+            const savePathButton = document.getElementById("git-save-path") as HTMLButtonElement | null;
+            const prefetchOriginalButton = document.getElementById("git-prefetch-original") as HTMLButtonElement | null;
+            const statusButton = document.getElementById("git-run-status") as HTMLButtonElement | null;
+            const branchesButton = document.getElementById("git-run-branches") as HTMLButtonElement | null;
+            const logButton = document.getElementById("git-run-log") as HTMLButtonElement | null;
+            const diffButton = document.getElementById("git-run-diff") as HTMLButtonElement | null;
+            const showButton = document.getElementById("git-run-show") as HTMLButtonElement | null;
+            const fetchButton = document.getElementById("git-run-fetch") as HTMLButtonElement | null;
+            const pullButton = document.getElementById("git-run-pull") as HTMLButtonElement | null;
+            const commitButton = document.getElementById("git-run-commit") as HTMLButtonElement | null;
+            const aiRefreshAssistantsButton = document.getElementById("git-ai-refresh-assistants") as HTMLButtonElement | null;
+            const aiCommitMessageButton = document.getElementById("git-ai-commit-message") as HTMLButtonElement | null;
+            const aiSummarizeOutputButton = document.getElementById("git-ai-summarize-output") as HTMLButtonElement | null;
+            const aiSuggestNextButton = document.getElementById("git-ai-suggest-next") as HTMLButtonElement | null;
+            const commitMessageInput = document.getElementById("git-commit-message") as HTMLInputElement | null;
+            const aiPromptInput = document.getElementById("git-ai-prompt") as HTMLInputElement | null;
+            const aiAssistantSelect = document.getElementById("git-ai-assistant-select") as HTMLSelectElement | null;
+            const snapshotButton = document.getElementById("git-run-snapshot") as HTMLButtonElement | null;
+            const historyList = document.getElementById("git-history-list") as HTMLElement | null;
+            const stagedFilesHint = document.getElementById("git-staged-files") as HTMLElement | null;
+
+            if (
+                !root ||
+                !repoInput ||
+                !outputCode ||
+                !summaryGrid ||
+                !summaryHint ||
+                !commandMeta ||
+                !savePathButton ||
+                !prefetchOriginalButton ||
+                !statusButton ||
+                !branchesButton ||
+                !logButton ||
+                !diffButton ||
+                !showButton ||
+                !fetchButton ||
+                !pullButton ||
+                !commitButton ||
+                !aiRefreshAssistantsButton ||
+                !aiCommitMessageButton ||
+                !aiSummarizeOutputButton ||
+                !aiSuggestNextButton ||
+                !commitMessageInput ||
+                !aiPromptInput ||
+                !aiAssistantSelect ||
+                !snapshotButton ||
+                !historyList ||
+                !stagedFilesHint
+            ) {
+                return;
+            }
+
+            const readConfig = (attr: string, fallback: string): string => {
+                const value = root.getAttribute(attr);
+                return typeof value === "string" && value.trim() ? value.trim() : fallback;
+            };
+
+            const PREPARE_HANDLER = readConfig("data-prepare-handler", "gitOps.v1.prepare");
+            const SAVE_REPO_PATH_HANDLER = readConfig("data-save-repo-path-handler", "gitOps.v1.saveRepoPath");
+            const PREFETCH_REQUEST_HANDLER = readConfig(
+                "data-prefetch-request-handler",
+                "gitOps.v1.prefetchOriginalRepoRequest"
+            );
+            const PREFETCH_HANDLER = readConfig("data-prefetch-handler", "gitOps.v1.prefetchOriginalRepo");
+            const BUILD_REQUEST_HANDLER = readConfig("data-build-request-handler", "gitOps.v1.buildRequest");
+            const BUILD_COMMIT_REQUEST_HANDLER = readConfig("data-build-commit-request-handler", "gitOps.v1.buildCommitRequest");
+            const BUILD_ID = readConfig("data-build-id", "unknown");
+            const AI_ASSIST_HANDLER = readConfig("data-ai-assist-handler", "fdo.ai.request.v1");
+            const AI_ASSISTANTS_LIST_HANDLER = readConfig("data-ai-assistants-list-handler", "fdo.ai.assistants.list.v1");
+            const AI_ASSISTANT_ID = readConfig("data-ai-assistant-id", "");
+            const AI_ASSISTANT_PURPOSE = readConfig("data-ai-assistant-purpose", "automation");
+            const AI_ASSISTANT_PROVIDER = readConfig("data-ai-assistant-provider", "");
+            const AI_ASSISTANT_MODEL = readConfig("data-ai-assistant-model", "");
+            const ORIGINAL_CONFIGURED_REPO_PUBLIC_KEY = readConfig(
+                "data-original-public-key",
+                "fdo.public.git.originalConfiguredRepository"
+            );
+
+            const classes = {
+                summaryItem: summaryGrid.getAttribute("data-summary-item-class") || "",
+                summaryLabel: summaryGrid.getAttribute("data-summary-label-class") || "",
+                summaryValue: summaryGrid.getAttribute("data-summary-value-class") || "",
+            };
+
+            const operationCatalog: Record<string, { title: string; args: string[] }> = {
+                status: { title: "Status", args: ["status", "--porcelain=v2", "--branch"] },
+                branches: { title: "Branches", args: ["branch", "-vv"] },
+                log: { title: "Recent Log", args: ["log", "--oneline", "--decorate", "-n", "15"] },
+                diffStat: { title: "Diff Stat", args: ["diff", "--stat", "--compact-summary"] },
+                showHead: { title: "Show HEAD", args: ["show", "--stat", "--no-patch", "HEAD"] },
+                fetch: { title: "Fetch --all --prune", args: ["fetch", "--all", "--prune"] },
+                pullFFOnly: { title: "Pull --ff-only", args: ["pull", "--ff-only"] },
+                commitStaged: { title: "Commit Staged", args: ["commit", "-m", "<message>"] },
+            };
+
+            const buttons = [
+                savePathButton,
+                prefetchOriginalButton,
+                statusButton,
+                branchesButton,
+                logButton,
+                diffButton,
+                showButton,
+                fetchButton,
+                pullButton,
+                commitButton,
+                aiRefreshAssistantsButton,
+                aiCommitMessageButton,
+                aiSummarizeOutputButton,
+                aiSuggestNextButton,
+                snapshotButton,
+            ];
+
+            const historyClasses = {
+                item: historyList.getAttribute("data-item-class") || "",
+                primary: historyList.getAttribute("data-primary-class") || "",
+                meta: historyList.getAttribute("data-meta-class") || "",
+                ok: historyList.getAttribute("data-status-ok-class") || "",
+                failed: historyList.getAttribute("data-status-failed-class") || "",
+            };
+
+            type ExecutionHistoryEntry = {
+                id: string;
+                at: string;
+                commandId: string;
+                label: string;
+                category: string;
+                status: "ok" | "failed";
+                dryRun: boolean;
+                durationMs: number;
+                correlationId: string;
+                repoPath: string;
+                errorCode: string;
+                errorMessage: string;
+            };
+
+            type AiAssistantOption = {
+                id: string;
+                name: string;
+                purpose: string;
+                provider: string;
+                model: string;
+                isDefault: boolean;
+            };
+
+            const state: {
+                gitCommand: string;
+                lastStatus: null | GitStatusSummary;
+                storageMode: string;
+                storageDiagnostic: string;
+                originalConfiguredRepoPath: string;
+                originalConfiguredRepoPublicKey: string;
+                lastRemoteRepository: Record<string, unknown> | null;
+                executionHistory: ExecutionHistoryEntry[];
+                runtimePrepared: boolean;
+                aiAssistants: AiAssistantOption[];
+                aiAssistantsLoaded: boolean;
+                aiAssistantsLastLoadedAt: number;
+                aiAssistantsFetchSeq: number;
+                selectedAssistantId: string;
+            } = {
+                gitCommand: "git",
+                lastStatus: null,
+                storageMode: "unknown",
+                storageDiagnostic: "",
+                originalConfiguredRepoPath: "",
+                originalConfiguredRepoPublicKey: ORIGINAL_CONFIGURED_REPO_PUBLIC_KEY,
+                lastRemoteRepository: null,
+                executionHistory: [],
+                runtimePrepared: false,
+                aiAssistants: [],
+                aiAssistantsLoaded: false,
+                aiAssistantsLastLoadedAt: 0,
+                aiAssistantsFetchSeq: 0,
+                selectedAssistantId: AI_ASSISTANT_ID,
+            };
+
+            const notifier = typeof window.Notyf === "function"
+                ? new window.Notyf({ duration: 2600, position: { x: "right", y: "top" } })
+                : null;
+
+            const notifySuccess = (message: string) => {
+                if (notifier && typeof notifier.success === "function") {
+                    notifier.success(message);
+                }
+            };
+
+            const notifyError = (message: string) => {
+                if (notifier && typeof notifier.error === "function") {
+                    notifier.error(message);
+                }
+            };
+
+            const escapeHtml = (value: unknown): string =>
+                String(value ?? "")
+                    .replace(/&/g, "&amp;")
+                    .replace(/</g, "&lt;")
+                    .replace(/>/g, "&gt;")
+                    .replace(/"/g, "&quot;")
+                    .replace(/'/g, "&#39;");
+
+            const normalizeAssistantOption = (candidate: unknown, index: number): AiAssistantOption | null => {
+                if (typeof candidate !== "object" || candidate === null) {
+                    return null;
+                }
+                const record = candidate as Record<string, unknown>;
+                const id = typeof record.id === "string" ? record.id.trim() : "";
+                if (!id) {
+                    return null;
+                }
+                const name = typeof record.name === "string" && record.name.trim()
+                    ? record.name.trim()
+                    : `assistant-${index + 1}`;
+                const purpose = typeof record.purpose === "string" ? record.purpose.trim() : "";
+                const provider = typeof record.provider === "string" ? record.provider.trim() : "";
+                const model = typeof record.model === "string" ? record.model.trim() : "";
+                const isDefault = record.default === true || record.isDefault === true;
+                return {
+                    id,
+                    name,
+                    purpose,
+                    provider,
+                    model,
+                    isDefault,
+                };
+            };
+
+            const assistantLabel = (assistant: AiAssistantOption): string => {
+                const parts = [assistant.name];
+                const providerModel = [assistant.provider, assistant.model].filter(Boolean).join(" / ");
+                if (providerModel) {
+                    parts.push(providerModel);
+                }
+                if (assistant.purpose) {
+                    parts.push(`[${assistant.purpose}]`);
+                }
+                return parts.join(" · ");
+            };
+
+            const setAssistantLoadingState = (loading: boolean) => {
+                aiAssistantSelect.disabled = loading;
+                if (loading) {
+                    aiAssistantSelect.innerHTML = `<option value="">AI Assistant: loading...</option>`;
+                    aiAssistantSelect.value = "";
+                }
+            };
+
+            const renderAssistantOptions = () => {
+                const options = state.aiAssistants;
+                let nextSelected = options.find((item) => item.id === state.selectedAssistantId)?.id || "";
+                if (!nextSelected) {
+                    const byPurpose = options.find((item) => item.purpose === AI_ASSISTANT_PURPOSE);
+                    const byDefault = options.find((item) => item.isDefault);
+                    nextSelected = (byPurpose || byDefault || options[0] || { id: "" }).id || "";
+                }
+                state.selectedAssistantId = nextSelected;
+
+                if (options.length === 0) {
+                    aiAssistantSelect.innerHTML = `<option value="">AI Assistant: default routing (${escapeHtml(AI_ASSISTANT_PURPOSE || "automation")})</option>`;
+                    aiAssistantSelect.value = "";
+                    return;
+                }
+
+                const rows = [
+                    `<option value="">AI Assistant: default routing (${escapeHtml(AI_ASSISTANT_PURPOSE || "automation")})</option>`,
+                    ...options.map((item) => `<option value="${escapeHtml(item.id)}">${escapeHtml(assistantLabel(item))}</option>`),
+                ];
+                aiAssistantSelect.innerHTML = rows.join("");
+                aiAssistantSelect.value = state.selectedAssistantId;
+                aiAssistantSelect.disabled = false;
+            };
+
+            const resolveSelectedAssistant = (): AiAssistantOption | null => {
+                const selected = state.aiAssistants.find((item) => item.id === state.selectedAssistantId) || null;
+                if (selected) {
+                    return selected;
+                }
+                const byPurpose = state.aiAssistants.find((item) => item.purpose === AI_ASSISTANT_PURPOSE) || null;
+                const byDefault = state.aiAssistants.find((item) => item.isDefault) || null;
+                const fallback = byPurpose || byDefault || state.aiAssistants[0] || null;
+                state.selectedAssistantId = fallback?.id || "";
+                return fallback;
+            };
+
+            const fetchAssistants = async (silent = false, force = false): Promise<void> => {
+                const now = Date.now();
+                if (!force && state.aiAssistantsLoaded && now - state.aiAssistantsLastLoadedAt < 120000) {
+                    return;
+                }
+
+                const currentSeq = state.aiAssistantsFetchSeq + 1;
+                state.aiAssistantsFetchSeq = currentSeq;
+                if (!silent) {
+                    setAssistantLoadingState(true);
+                }
+                try {
+                    const response = await window.createBackendReq("UI_MESSAGE", {
+                        handler: AI_ASSISTANTS_LIST_HANDLER,
+                        content: {
+                            purpose: AI_ASSISTANT_PURPOSE || undefined,
+                            provider: AI_ASSISTANT_PROVIDER || undefined,
+                            model: AI_ASSISTANT_MODEL || undefined,
+                        },
+                    });
+
+                    if (response && (response.ok === false || response.success === false)) {
+                        const code = typeof response.code === "string" ? ` (${response.code})` : "";
+                        const message = typeof response.error === "string"
+                            ? response.error
+                            : "Failed to fetch AI assistants.";
+                        throw new Error(`${message}${code}`);
+                    }
+
+                    const rawAssistants: unknown[] = Array.isArray(response)
+                        ? response
+                        : (
+                            Array.isArray(response?.assistants)
+                                ? response.assistants
+                                : (Array.isArray(response?.items) ? response.items : [])
+                        );
+                    if (currentSeq !== state.aiAssistantsFetchSeq) {
+                        return;
+                    }
+
+                    const uniqueById = new Set<string>();
+                    state.aiAssistants = rawAssistants
+                        .map((item: unknown, index: number) => normalizeAssistantOption(item, index))
+                        .filter((item: AiAssistantOption | null): item is AiAssistantOption => Boolean(item))
+                        .filter((item) => {
+                            if (uniqueById.has(item.id)) {
+                                return false;
+                            }
+                            uniqueById.add(item.id);
+                            return true;
+                        })
+                        .sort((a, b) => {
+                            if (a.isDefault !== b.isDefault) {
+                                return a.isDefault ? -1 : 1;
+                            }
+                            return a.name.localeCompare(b.name);
+                        })
+                        .slice(0, 100);
+                    state.aiAssistantsLoaded = true;
+                    state.aiAssistantsLastLoadedAt = now;
+                    renderAssistantOptions();
+
+                    if (!silent) {
+                        const note = state.aiAssistants.length > 0
+                            ? `Loaded ${state.aiAssistants.length} AI assistant${state.aiAssistants.length > 1 ? "s" : ""}.`
+                            : "No AI assistants returned. Requests will use host default routing.";
+                        setMeta(note);
+                        notifySuccess("AI assistants refreshed");
+                    }
+                } catch (error) {
+                    if (!silent) {
+                        renderAssistantOptions();
+                    } else {
+                        aiAssistantSelect.disabled = false;
+                    }
+                    throw error;
+                } finally {
+                    if (!silent && currentSeq === state.aiAssistantsFetchSeq) {
+                        aiAssistantSelect.disabled = false;
+                    }
+                }
+            };
+
+            const formatIsoToLocal = (isoValue: string): string => {
+                const date = new Date(isoValue);
+                if (Number.isNaN(date.getTime())) {
+                    return isoValue;
+                }
+                return date.toLocaleString();
+            };
+
+            const parseErrorCodeFromMessage = (message: string): string => {
+                const match = message.match(/\(([A-Z0-9_]+)\)/);
+                return match ? match[1] : "";
+            };
+
+            const renderExecutionHistory = () => {
+                if (state.executionHistory.length === 0) {
+                    historyList.innerHTML = `
+                        <div class="${historyClasses.item}">
+                            <p class="${historyClasses.primary}">No command runs yet.</p>
+                            <p class="${historyClasses.meta}">Run a command or snapshot to populate timeline.</p>
+                        </div>
+                    `;
+                    return;
+                }
+
+                historyList.innerHTML = state.executionHistory
+                    .slice(0, 12)
+                    .map((entry) => {
+                        const statusClass = entry.status === "ok" ? historyClasses.ok : historyClasses.failed;
+                        const dryRunLabel = entry.dryRun ? "dry-run" : "apply";
+                        const correlationLabel = entry.correlationId || "unknown";
+                        const errorSuffix = entry.status === "failed" && entry.errorMessage
+                            ? ` | ${entry.errorMessage}`
+                            : "";
+                        return `
+                            <div class="${historyClasses.item}">
+                                <p class="${historyClasses.primary}">
+                                    ${escapeHtml(entry.label)} ·
+                                    <span class="${statusClass}">${escapeHtml(entry.status.toUpperCase())}</span>
+                                </p>
+                                <p class="${historyClasses.meta}">
+                                    ${escapeHtml(formatIsoToLocal(entry.at))} | ${escapeHtml(entry.category)} | ${escapeHtml(dryRunLabel)} | ${escapeHtml(String(entry.durationMs))}ms
+                                </p>
+                                <p class="${historyClasses.meta}">
+                                    repo: ${escapeHtml(entry.repoPath)} | correlation: ${escapeHtml(correlationLabel)}${escapeHtml(errorSuffix)}
+                                </p>
+                            </div>
+                        `;
+                    })
+                    .join("");
+            };
+
+            const pushExecutionHistory = (entry: Omit<ExecutionHistoryEntry, "id" | "at">) => {
+                state.executionHistory.unshift({
+                    id: `hist-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+                    at: new Date().toISOString(),
+                    ...entry,
+                });
+                if (state.executionHistory.length > 30) {
+                    state.executionHistory = state.executionHistory.slice(0, 30);
+                }
+                renderExecutionHistory();
+            };
+
+            const formatPrivilegedActionError = (
+                response: any,
+                options?: { context?: string; fallbackCorrelationId?: string }
+            ): string => {
+                const context = options?.context?.trim() || "Privileged action failed";
+                const fallbackCorrelationId = options?.fallbackCorrelationId?.trim() || "";
+                const correlationId = typeof response?.correlationId === "string" && response.correlationId.trim()
+                    ? response.correlationId.trim()
+                    : (fallbackCorrelationId || "unknown");
+                const errorMessage = typeof response?.error === "string" && response.error.trim()
+                    ? response.error.trim()
+                    : "Unknown host error";
+                const code = typeof response?.code === "string" && response.code.trim()
+                    ? ` (${response.code.trim()})`
+                    : "";
+                const stderr = typeof response?.result?.stderr === "string" ? response.result.stderr.trim() : "";
+                const stdout = typeof response?.result?.stdout === "string" ? response.result.stdout.trim() : "";
+                const detail = stderr || stdout;
+                const detailLabel = stderr ? "stderr" : "stdout";
+                const detailSuffix = detail ? `\n${detailLabel}: ${detail}` : "";
+                return `${context}${code}: ${errorMessage}${detailSuffix}\nCorrelation ID: ${correlationId}`;
+            };
+
+            const appendGitExecutionHints = (
+                baseMessage: string,
+                response: any,
+                options?: { cwdHint?: string }
+            ): string => {
+                const hints: string[] = [];
+                const code = typeof response?.code === "string" ? response.code.trim() : "";
+                const stderr = String(response?.result?.stderr || "");
+                const stdout = String(response?.result?.stdout || "");
+                const combined = `${stderr}\n${stdout}`.toLowerCase();
+                const cwdHint = typeof options?.cwdHint === "string" ? options.cwdHint.trim() : "";
+
+                if (code === "PROCESS_SPAWN_ENOENT" && cwdHint) {
+                    hints.push(
+                        `With process cwd execution, ENOENT can also mean the repository path does not exist or is inaccessible: ${cwdHint}`
+                    );
+                }
+
+                if (combined.includes("not a git repository")) {
+                    hints.push(
+                        "The selected path is not a Git repository. Verify the repository path points to a directory containing a .git folder."
+                    );
+                }
+
+                if (combined.includes("detected dubious ownership") || combined.includes("safe.directory")) {
+                    hints.push(
+                        `Git blocked access due to ownership safety checks. If this repository is trusted, run: git config --global --add safe.directory "${cwdHint || "<repo-path>"}"`
+                    );
+                }
+
+                if (combined.includes("index.lock") || combined.includes("another git process seems to be running")) {
+                    hints.push(
+                        "A Git lock file is present. Ensure no other Git process is running, then remove stale .git/index.lock if safe."
+                    );
+                }
+
+                if (combined.includes("authentication failed") || combined.includes("could not read username")
+                    || combined.includes("repository not found") || combined.includes("permission denied (publickey)")) {
+                    hints.push(
+                        "Remote authentication failed. Refresh credentials/SSH agent and verify remote access permissions."
+                    );
+                }
+
+                if (code === "PROCESS_TIMEOUT") {
+                    hints.push(
+                        "The command timed out. Increase timeoutMs for large repositories or run a narrower operation first."
+                    );
+                }
+
+                if (combined.includes("permission denied") && !combined.includes("publickey")) {
+                    hints.push(
+                        "Filesystem permission error. Verify read/execute access for the selected repository path."
+                    );
+                }
+
+                if (hints.length === 0) {
+                    return baseMessage;
+                }
+
+                const uniqueHints = Array.from(new Set(hints));
+                return `${baseMessage}\nHints:\n${uniqueHints.map((hint) => `- ${hint}`).join("\n")}`;
+            };
+
+            const resolveEnvelopeCorrelationId = (envelope: any): string => {
+                if (typeof envelope?.result?.correlationId === "string" && envelope.result.correlationId.trim()) {
+                    return envelope.result.correlationId.trim();
+                }
+                if (typeof envelope?.correlationId === "string" && envelope.correlationId.trim()) {
+                    return envelope.correlationId.trim();
+                }
+                return "";
+            };
+
+            const extractPrivilegedRequestPayload = (envelope: any, context: string) => {
+                const correlationId = resolveEnvelopeCorrelationId(envelope);
+                const requestPayload =
+                    envelope?.result?.request
+                    ?? envelope?.request
+                    ?? (typeof envelope?.action === "string" ? envelope : null);
+                if (!requestPayload || typeof requestPayload !== "object") {
+                    throw new Error(`${context} is missing a privileged request payload.`);
+                }
+
+                return {
+                    correlationId,
+                    requestPayload,
+                };
+            };
+
+            const executePrivilegedRequestEnvelope = async (
+                envelope: any,
+                options: { context: string; cwdHint?: string }
+            ) => {
+                const { correlationId, requestPayload } = extractPrivilegedRequestPayload(envelope, options.context);
+                const response = await window.createBackendReq("requestPrivilegedAction", requestPayload);
+                if (response && response.ok) {
+                    return {
+                        response,
+                        correlationId,
+                    };
+                }
+
+                const formatted = formatPrivilegedActionError(response, {
+                    context: options.context,
+                    fallbackCorrelationId: correlationId,
+                });
+                throw new Error(appendGitExecutionHints(formatted, response, { cwdHint: options.cwdHint }));
+            };
+
+            const setBusy = (busy: boolean) => {
+                buttons.forEach((button) => {
+                    button.disabled = busy;
+                });
+            };
+
+            const setMeta = (text: string) => {
+                commandMeta.textContent = text;
+            };
+
+            const applySyntaxHighlight = () => {
+                if (window.hljs && typeof window.hljs.highlightElement === "function") {
+                    if (outputCode && outputCode.dataset) {
+                        delete outputCode.dataset.highlighted;
+                    }
+                    outputCode.removeAttribute("data-highlighted");
+                    outputCode.classList.remove("hljs");
+                    window.hljs.highlightElement(outputCode);
+                }
+            };
+
+            const setOutput = (text: string) => {
+                outputCode.textContent = text;
+                applySyntaxHighlight();
+            };
+
+            const renderSummary = (status: typeof state.lastStatus) => {
+                if (!status) {
+                    summaryGrid.innerHTML = [
+                        ["Branch", "-"],
+                        ["Ahead/Behind", "-"],
+                        ["Staged", "0"],
+                        ["Modified", "0"],
+                        ["Untracked", "0"],
+                        ["Conflicts", "0"],
+                    ].map(([label, value]) => `
+                        <div class="${classes.summaryItem}">
+                            <div class="${classes.summaryLabel}">${escapeHtml(label)}</div>
+                            <div class="${classes.summaryValue}">${escapeHtml(value)}</div>
+                        </div>
+                    `).join("");
+                    summaryHint.textContent = "Run Status to populate summary diagnostics.";
+                    return;
+                }
+
+                summaryGrid.innerHTML = [
+                    ["Branch", status.branch || "(detached)"],
+                    ["Ahead/Behind", status.aheadBehind || "n/a"],
+                    ["Staged", String(status.staged)],
+                    ["Modified", String(status.modified)],
+                    ["Untracked", String(status.untracked)],
+                    ["Conflicts", String(status.conflicts)],
+                ].map(([label, value]) => `
+                    <div class="${classes.summaryItem}">
+                        <div class="${classes.summaryLabel}">${escapeHtml(label)}</div>
+                        <div class="${classes.summaryValue}">${escapeHtml(value)}</div>
+                    </div>
+                `).join("");
+
+                summaryHint.textContent = status.isClean
+                    ? "Working tree is clean."
+                    : "Working tree has pending changes.";
+            };
+
+            const renderStagedFilesHint = (status: typeof state.lastStatus) => {
+                if (!status || !Array.isArray(status.stagedFiles) || status.stagedFiles.length === 0) {
+                    stagedFilesHint.textContent = "Staged files: none detected. Stage changes before generating commit message.";
+                    return;
+                }
+                const preview = status.stagedFiles.slice(0, 6).join(", ");
+                const suffix = status.stagedFiles.length > 6 ? ` (+${status.stagedFiles.length - 6} more)` : "";
+                stagedFilesHint.textContent = `Staged files (${status.stagedFiles.length}): ${preview}${suffix}`;
+            };
+
+            const extractPorcelainPath = (line: string): string => {
+                const tabParts = line.split("\t").map((entry) => entry.trim()).filter(Boolean);
+                if (tabParts.length > 0) {
+                    return tabParts[tabParts.length - 1];
+                }
+                const tokens = line.trim().split(/\s+/);
+                return tokens.length > 0 ? tokens[tokens.length - 1] : "";
+            };
+
+            const parseStatusOutput = (stdout: string) => {
+                const stagedFiles = new Set<string>();
+                const status: GitStatusSummary = {
+                    branch: "",
+                    aheadBehind: "",
+                    staged: 0,
+                    modified: 0,
+                    untracked: 0,
+                    conflicts: 0,
+                    isClean: true,
+                    stagedFiles: [],
+                };
+
+                String(stdout || "")
+                    .split(/\r?\n/)
+                    .forEach((line) => {
+                        if (line.startsWith("# branch.head ")) {
+                            status.branch = line.slice("# branch.head ".length).trim();
+                            return;
+                        }
+                        if (line.startsWith("# branch.ab ")) {
+                            status.aheadBehind = line.slice("# branch.ab ".length).trim();
+                            return;
+                        }
+                        if (line.startsWith("? ")) {
+                            status.untracked += 1;
+                            status.isClean = false;
+                            return;
+                        }
+                        if (line.startsWith("u ")) {
+                            status.conflicts += 1;
+                            status.isClean = false;
+                            return;
+                        }
+                        if (line.startsWith("1 ") || line.startsWith("2 ")) {
+                            const parts = line.split(" ");
+                            const xy = parts[1] || "..";
+                            const stagedCode = xy.charAt(0);
+                            const workTreeCode = xy.charAt(1);
+                            if (stagedCode && stagedCode !== "." && stagedCode !== "?" && stagedCode !== " ") {
+                                status.staged += 1;
+                                status.isClean = false;
+                                const path = extractPorcelainPath(line);
+                                if (path) {
+                                    stagedFiles.add(path);
+                                }
+                            }
+                            if (workTreeCode && workTreeCode !== "." && workTreeCode !== " ") {
+                                status.modified += 1;
+                                status.isClean = false;
+                            }
+                        }
+                    });
+
+                status.stagedFiles = Array.from(stagedFiles).sort((left, right) => left.localeCompare(right));
+                return status;
+            };
+
+            const persistRepoPath = async (silent = false): Promise<string> => {
+                const repoPath = String(repoInput.value || "").trim();
+                if (!repoPath) {
+                    throw new Error("Repository path is required.");
+                }
+
+                const saveResult = await window.createBackendReq("UI_MESSAGE", {
+                    handler: SAVE_REPO_PATH_HANDLER,
+                    content: { cwd: repoPath },
+                });
+                if (saveResult && (saveResult.ok === false || saveResult.success === false)) {
+                    const code = typeof saveResult.code === "string" ? ` (${saveResult.code})` : "";
+                    const message = typeof saveResult.error === "string"
+                        ? saveResult.error
+                        : "Failed to persist repository path.";
+                    throw new Error(`${message}${code}`);
+                }
+
+                const storedPath = typeof saveResult?.storedPath === "string" ? saveResult.storedPath : repoPath;
+                const persistence = typeof saveResult?.persistence === "string" ? saveResult.persistence : state.storageMode;
+                const storageDiagnostic = typeof saveResult?.storageDiagnostic === "string"
+                    ? saveResult.storageDiagnostic.trim()
+                    : "";
+                const originalConfiguredRepoPath =
+                    typeof saveResult?.originalConfiguredRepoPath === "string" && saveResult.originalConfiguredRepoPath.trim()
+                        ? saveResult.originalConfiguredRepoPath.trim()
+                        : "";
+                const originalConfiguredRepoPublicKey =
+                    typeof saveResult?.originalConfiguredRepoPublicKey === "string" && saveResult.originalConfiguredRepoPublicKey.trim()
+                        ? saveResult.originalConfiguredRepoPublicKey.trim()
+                        : "";
+
+                repoInput.value = storedPath;
+                state.storageMode = persistence;
+                state.storageDiagnostic = storageDiagnostic;
+                if (originalConfiguredRepoPath) {
+                    state.originalConfiguredRepoPath = originalConfiguredRepoPath;
+                }
+                if (originalConfiguredRepoPublicKey) {
+                    state.originalConfiguredRepoPublicKey = originalConfiguredRepoPublicKey;
+                }
+
+                const prefetchHint = state.originalConfiguredRepoPath
+                    ? ` Original configured repository (public key ${state.originalConfiguredRepoPublicKey}): ${state.originalConfiguredRepoPath}.`
+                    : "";
+                setMeta(`Ready [build: ${BUILD_ID}]. Executable: ${state.gitCommand}. Repository path saved (${persistence}).${prefetchHint} No command executed yet.`);
+
+                if (!silent) {
+                    notifySuccess(`Repository path saved (${persistence})`);
+                }
+
+                return storedPath;
+            };
+
+            const prefetchOriginalRepoPath = async (silent = false): Promise<string> => {
+                const startedAt = Date.now();
+                let fallbackCwd = String(repoInput.value || "").trim();
+                try {
+                    fallbackCwd = await persistRepoPath(true);
+                    if (!fallbackCwd) {
+                        throw new Error("Repository path is required before prefetch.");
+                    }
+
+                    const requestBuildResponse = await window.createBackendReq("UI_MESSAGE", {
+                        handler: PREFETCH_REQUEST_HANDLER,
+                        content: { cwd: fallbackCwd },
+                    });
+
+                    if (requestBuildResponse && (requestBuildResponse.ok === false || requestBuildResponse.success === false)) {
+                        const code = typeof requestBuildResponse.code === "string" ? ` (${requestBuildResponse.code})` : "";
+                        const message = typeof requestBuildResponse.error === "string"
+                            ? requestBuildResponse.error
+                            : "Failed to prepare original configured repository prefetch request.";
+                        throw new Error(`${message}${code}`);
+                    }
+
+                    const originalConfiguredRepoPath =
+                        typeof requestBuildResponse?.originalConfiguredRepoPath === "string"
+                        && requestBuildResponse.originalConfiguredRepoPath.trim()
+                            ? requestBuildResponse.originalConfiguredRepoPath.trim()
+                            : "";
+                    if (!originalConfiguredRepoPath) {
+                        throw new Error("Original configured repository is unavailable.");
+                    }
+
+                    const originalConfiguredRepoPublicKey =
+                        typeof requestBuildResponse?.originalConfiguredRepoPublicKey === "string"
+                        && requestBuildResponse.originalConfiguredRepoPublicKey.trim()
+                            ? requestBuildResponse.originalConfiguredRepoPublicKey.trim()
+                            : state.originalConfiguredRepoPublicKey;
+                    const requestEnvelope =
+                        requestBuildResponse?.requestEnvelope && typeof requestBuildResponse.requestEnvelope === "object"
+                            ? requestBuildResponse.requestEnvelope
+                            : null;
+                    let remoteOriginUrl = "";
+                    if (requestEnvelope) {
+                        setMeta(`Resolving remote origin through scoped Git execution (${originalConfiguredRepoPath})...`);
+                        try {
+                            const { response: inspectResponse } = await executePrivilegedRequestEnvelope(requestEnvelope, {
+                                context: "Git remote origin inspection failed",
+                                cwdHint: originalConfiguredRepoPath,
+                            });
+                            const remoteOriginStdout = String(inspectResponse?.result?.stdout || "");
+                            remoteOriginUrl = remoteOriginStdout
+                                .split(/\r?\n/)
+                                .map((line) => line.trim())
+                                .find((line) => line.length > 0) || "";
+                        } catch (inspectError) {
+                            const inspectMessage = inspectError instanceof Error ? inspectError.message : String(inspectError);
+                            setMeta(`Remote origin inspection warning: ${inspectMessage}. Continuing without metadata.`);
+                        }
+                    } else {
+                        setMeta("Remote origin inspection envelope is missing. Continuing without metadata prefetch.");
+                    }
+
+                    const response = await window.createBackendReq("UI_MESSAGE", {
+                        handler: PREFETCH_HANDLER,
+                        content: {
+                            cwd: originalConfiguredRepoPath,
+                            remoteOriginUrl,
+                        },
+                    });
+                    if (response && (response.ok === false || response.success === false)) {
+                        const code = typeof response.code === "string" ? ` (${response.code})` : "";
+                        const message = typeof response.error === "string"
+                            ? response.error
+                            : "Failed to prefetch original configured repository.";
+                        throw new Error(`${message}${code}`);
+                    }
+
+                const resolvedOriginalConfiguredRepoPath =
+                    typeof response?.originalConfiguredRepoPath === "string" && response.originalConfiguredRepoPath.trim()
+                        ? response.originalConfiguredRepoPath.trim()
+                        : originalConfiguredRepoPath;
+                const resolvedOriginalConfiguredRepoPublicKey =
+                    typeof response?.originalConfiguredRepoPublicKey === "string" && response.originalConfiguredRepoPublicKey.trim()
+                        ? response.originalConfiguredRepoPublicKey.trim()
+                        : originalConfiguredRepoPublicKey;
+                const remoteRepository = response?.remoteRepository && typeof response.remoteRepository === "object"
+                    ? response.remoteRepository as Record<string, unknown>
+                    : null;
+                const prefetchWarning = typeof response?.warning === "string" ? response.warning.trim() : "";
+                const storageDiagnostic =
+                    typeof response?.storageDiagnostic === "string" && response.storageDiagnostic.trim()
+                        ? response.storageDiagnostic.trim()
+                        : "";
+                const persistence =
+                    typeof response?.persistence === "string" && response.persistence.trim()
+                        ? response.persistence.trim()
+                        : state.storageMode;
+
+                repoInput.value = resolvedOriginalConfiguredRepoPath;
+                state.originalConfiguredRepoPath = resolvedOriginalConfiguredRepoPath;
+                state.originalConfiguredRepoPublicKey = resolvedOriginalConfiguredRepoPublicKey;
+                state.lastRemoteRepository = remoteRepository;
+                state.storageMode = persistence;
+                state.storageDiagnostic = storageDiagnostic;
+
+                const warningSuffix = prefetchWarning
+                    ? ` Metadata prefetch warning: ${prefetchWarning}.`
+                    : "";
+                setMeta(
+                    `Ready [build: ${BUILD_ID}]. Executable: ${state.gitCommand}. Prefetched original configured repository ${resolvedOriginalConfiguredRepoPath} (public key ${resolvedOriginalConfiguredRepoPublicKey}, ${persistence}). Remote origin: ${remoteOriginUrl || "unavailable"}.${warningSuffix} No command executed yet.`
+                );
+                if (remoteRepository) {
+                    setOutput(`$ prefetched remote repository metadata\n\n${JSON.stringify(remoteRepository, null, 2)}`);
+                } else {
+                    const warningText = prefetchWarning
+                        ? `\nwarning: ${prefetchWarning}`
+                        : "";
+                    setOutput(`$ prefetch completed, but no remote repository metadata was returned.${warningText}`);
+                }
+
+                    if (!silent) {
+                        const repositoryLabel =
+                            remoteRepository && typeof remoteRepository.repository === "string" && remoteRepository.repository.trim()
+                                ? ` (${remoteRepository.repository})`
+                                : "";
+                        if (prefetchWarning) {
+                            notifyError(`Original repository prefetched with warning${repositoryLabel}: ${prefetchWarning}`);
+                        } else {
+                            notifySuccess(`Original configured repository prefetched${repositoryLabel}`);
+                        }
+                    }
+                    pushExecutionHistory({
+                        commandId: "prefetch",
+                        label: "Prefetch Original Repo",
+                        category: "profile",
+                        status: "ok",
+                        dryRun: false,
+                        durationMs: Date.now() - startedAt,
+                        correlationId: "",
+                        repoPath: resolvedOriginalConfiguredRepoPath,
+                        errorCode: "",
+                        errorMessage: "",
+                    });
+                    return resolvedOriginalConfiguredRepoPath;
+                } catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    pushExecutionHistory({
+                        commandId: "prefetch",
+                        label: "Prefetch Original Repo",
+                        category: "profile",
+                        status: "failed",
+                        dryRun: false,
+                        durationMs: Date.now() - startedAt,
+                        correlationId: "",
+                        repoPath: fallbackCwd || "(unknown)",
+                        errorCode: parseErrorCodeFromMessage(message),
+                        errorMessage: message,
+                    });
+                    const degradedPath = fallbackCwd || state.originalConfiguredRepoPath || String(repoInput.value || "").trim();
+                    setMeta(`Prefetch degraded [build: ${BUILD_ID}]: ${message}`);
+                    setOutput(`$ prefetch degraded\n\n${message}`);
+                    if (!silent) {
+                        notifyError(`Prefetch degraded: ${message}`);
+                    }
+                    return degradedPath;
+                }
+            };
+
+            const runOperation = async (
+                operationId: string,
+                options: { append?: boolean; silent?: boolean; dryRun?: boolean } = {}
+            ) => {
+                const { append = false, silent = false, dryRun = false } = options;
+                const operation = operationCatalog[operationId];
+                if (!operation) {
+                    throw new Error(`Unknown operation: ${operationId}`);
+                }
+                if (!state.runtimePrepared) {
+                    throw new Error("Runtime is not prepared yet. Wait for initialization to finish.");
+                }
+                const startedAt = Date.now();
+
+                let repoPath = "";
+                try {
+                    repoPath = await persistRepoPath(true);
+                    if (!append) {
+                        setOutput(`$ preparing ${operation.title}...\n`);
+                    }
+                    setMeta(`Running ${operation.title} in ${repoPath}...`);
+
+                    const envelope = await window.createBackendReq("UI_MESSAGE", {
+                        handler: BUILD_REQUEST_HANDLER,
+                        content: {
+                            operation: operationId,
+                            cwd: repoPath,
+                            dryRun,
+                        },
+                    });
+
+                    if (!envelope || typeof envelope !== "object") {
+                        throw new Error("Plugin backend did not return a structured privileged request envelope.");
+                    }
+
+                    const envelopeCorrelationId = resolveEnvelopeCorrelationId(envelope);
+                    const backendErrorCode = typeof envelope?.code === "string" ? envelope.code.trim() : "";
+                    const backendErrorText = typeof envelope?.error === "string" ? envelope.error.trim() : "";
+                    const backendFailed = (
+                        envelope?.ok === false
+                        || envelope?.success === false
+                        || Boolean(backendErrorCode)
+                        || Boolean(backendErrorText)
+                    );
+                    if (backendFailed) {
+                        const codeSuffix = backendErrorCode ? ` (${backendErrorCode})` : "";
+                        throw new Error(
+                            `Git request preparation failed${codeSuffix}: ${backendErrorText || "Plugin backend handler failed."}\nCorrelation ID: ${envelopeCorrelationId || "unknown"}`
+                        );
+                    }
+
+                    const { response } = await executePrivilegedRequestEnvelope(envelope, {
+                        context: "Git operation failed",
+                        cwdHint: repoPath,
+                    });
+
+                    const result = response.result || {};
+                    const stdout = String(result.stdout || "");
+                    const stderr = String(result.stderr || "");
+                    const header = [
+                        `$ ${result.command || state.gitCommand} ${Array.isArray(result.args) ? result.args.join(" ") : operation.args.join(" ")}`,
+                        `# cwd: ${result.cwd || repoPath}`,
+                        `# mode: ${dryRun ? "dry-run" : "apply"}`,
+                        `# correlationId: ${response.correlationId || envelopeCorrelationId || "unknown"}`,
+                    ].join("\n");
+                    const payload = stdout || stderr
+                        ? [stdout, stderr ? `[stderr]\n${stderr}` : ""].filter(Boolean).join("\n\n")
+                        : "(no output)";
+                    const block = `${header}\n\n${payload}`;
+
+                    if (append) {
+                        const previous = String(outputCode.textContent || "").trim();
+                        setOutput(`${previous}\n\n${block}`.trim());
+                    } else {
+                        setOutput(block);
+                    }
+
+                    if (operationId === "status") {
+                        state.lastStatus = parseStatusOutput(stdout);
+                        renderSummary(state.lastStatus);
+                        renderStagedFilesHint(state.lastStatus);
+                    }
+
+                    const finalCorrelationId = response.correlationId || envelopeCorrelationId || "unknown";
+                    pushExecutionHistory({
+                        commandId: operationId,
+                        label: operation.title,
+                        category: "operation",
+                        status: "ok",
+                        dryRun,
+                        durationMs: Date.now() - startedAt,
+                        correlationId: finalCorrelationId,
+                        repoPath: repoPath || "(unknown)",
+                        errorCode: "",
+                        errorMessage: "",
+                    });
+                    setMeta(`Last run: ${operation.title}${dryRun ? " [dry-run]" : ""} succeeded (correlation: ${finalCorrelationId}). Path persistence: ${state.storageMode}.`);
+                    if (!silent) {
+                        notifySuccess(`${operation.title}${dryRun ? " (dry-run)" : ""} completed`);
+                    }
+                } catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    pushExecutionHistory({
+                        commandId: operationId,
+                        label: operation.title,
+                        category: "operation",
+                        status: "failed",
+                        dryRun,
+                        durationMs: Date.now() - startedAt,
+                        correlationId: "",
+                        repoPath: repoPath || String(repoInput.value || "").trim() || "(unknown)",
+                        errorCode: parseErrorCodeFromMessage(message),
+                        errorMessage: message,
+                    });
+                    throw error;
+                }
+            };
+
+            const runSnapshot = async () => {
+                setBusy(true);
+                const startedAt = Date.now();
+                try {
+                    const sequence = ["status", "branches", "log", "diffStat", "showHead"] as const;
+                    setMeta("Running snapshot sequence (status, branches, log, diff stat, show head)...");
+                    setOutput("$ running Git snapshot sequence...");
+                    for (let index = 0; index < sequence.length; index += 1) {
+                        const operationId = sequence[index];
+                        await runOperation(operationId, { append: index > 0, silent: true });
+                    }
+                    setMeta(`Snapshot completed successfully. Path persistence: ${state.storageMode}.`);
+                    notifySuccess("Git snapshot completed");
+                    pushExecutionHistory({
+                        commandId: "snapshot",
+                        label: "Run Snapshot Sequence",
+                        category: "inspect",
+                        status: "ok",
+                        dryRun: false,
+                        durationMs: Date.now() - startedAt,
+                        correlationId: "",
+                        repoPath: String(repoInput.value || "").trim() || "(unknown)",
+                        errorCode: "",
+                        errorMessage: "",
+                    });
+                } catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    setOutput(`Snapshot failed:\n${message}`);
+                    setMeta(`Snapshot failed: ${message}`);
+                    notifyError("Snapshot failed");
+                    pushExecutionHistory({
+                        commandId: "snapshot",
+                        label: "Run Snapshot Sequence",
+                        category: "inspect",
+                        status: "failed",
+                        dryRun: false,
+                        durationMs: Date.now() - startedAt,
+                        correlationId: "",
+                        repoPath: String(repoInput.value || "").trim() || "(unknown)",
+                        errorCode: parseErrorCodeFromMessage(message),
+                        errorMessage: message,
+                    });
+                } finally {
+                    setBusy(false);
+                }
+            };
+
+            const requestAiAssistance = async (
+                task: "commit-message" | "summarize-output" | "suggest-next-command"
+            ): Promise<string> => {
+                const startedAt = Date.now();
+                try {
+                    if (!state.aiAssistantsLoaded) {
+                        await fetchAssistants(true);
+                    }
+                    const repoPath = String(repoInput.value || "").trim();
+                    const selectedAssistant = resolveSelectedAssistant();
+                    if (task === "commit-message" && (!state.lastStatus || state.lastStatus.staged === 0)) {
+                        throw new Error("No staged files detected. Run Status and stage changes before generating a commit message.");
+                    }
+                    const prompt = task === "commit-message"
+                        ? [
+                            "Generate a concise conventional-commit-style message for staged git changes.",
+                            "Use only staged files as scope context.",
+                            "Prefer imperative mood and keep it under 72 characters when possible.",
+                        ].join(" ")
+                        : (task === "summarize-output"
+                            ? [
+                                "Summarize the latest command output for an operator.",
+                                "Keep 3-5 short bullet points with key signals only.",
+                                "Do not generate commit messages.",
+                            ].join(" ")
+                            : [
+                                "Suggest the safest next Git command based on repository status/output.",
+                                "Include one concrete command plus brief reason.",
+                                "Do not generate commit messages.",
+                            ].join(" "));
+                    const outputText = String(outputCode.textContent || "");
+                    const response = await window.createBackendReq("UI_MESSAGE", {
+                        handler: AI_ASSIST_HANDLER,
+                        content: {
+                            task,
+                            repoPath,
+                            summary: {
+                                ...state.lastStatus,
+                                stagedFiles: Array.isArray(state.lastStatus?.stagedFiles) ? state.lastStatus.stagedFiles : [],
+                            },
+                            prompt: `${prompt} ${String(aiPromptInput.value || "").trim()}`.trim(),
+                            commandOutput: outputText,
+                            recentRuns: state.executionHistory.slice(0, 8),
+                            assistantId: selectedAssistant?.id || state.selectedAssistantId || undefined,
+                            assistantPurpose: AI_ASSISTANT_PURPOSE || "automation",
+                            assistantProvider: selectedAssistant?.provider || AI_ASSISTANT_PROVIDER || undefined,
+                            assistantModel: selectedAssistant?.model || AI_ASSISTANT_MODEL || undefined,
+                            stagedFiles: Array.isArray(state.lastStatus?.stagedFiles) ? state.lastStatus.stagedFiles : [],
+                        },
+                    });
+                    if (response && (response.ok === false || response.success === false)) {
+                        const code = typeof response.code === "string" ? ` (${response.code})` : "";
+                        const message = typeof response.error === "string"
+                            ? response.error
+                            : `AI assistance failed for task "${task}".`;
+                        throw new Error(`${message}${code}`);
+                    }
+
+                    const aiText = typeof response?.commitMessage === "string"
+                        ? response.commitMessage.trim()
+                        : (
+                            typeof response?.message === "string"
+                                ? response.message.trim()
+                                : (typeof response?.text === "string" ? response.text.trim() : "")
+                        );
+                    if (!aiText) {
+                        throw new Error(`AI provider returned an empty response for task "${task}".`);
+                    }
+
+                    if (task === "commit-message") {
+                        commitMessageInput.value = aiText;
+                    } else if (task === "summarize-output") {
+                        setOutput(`$ ai summary\n\n${aiText}`);
+                    } else if (task === "suggest-next-command") {
+                        setMeta(`AI suggestion: ${aiText}`);
+                    }
+                    const source = typeof response?.source === "string" ? response.source : "unknown";
+                    const warning = typeof response?.warning === "string" ? response.warning.trim() : "";
+                    const assistantInfo = selectedAssistant
+                        ? `${selectedAssistant.name} (${selectedAssistant.provider || "unknown"} / ${selectedAssistant.model || "default"})`
+                        : `host default (${AI_ASSISTANT_PURPOSE || "automation"})`;
+                    setMeta(`AI assistance completed for task "${task}" (${source}, assistant: ${assistantInfo}).`);
+                    if (warning) {
+                        notifyError(warning);
+                    } else {
+                        notifySuccess(`AI assistance completed (${task})`);
+                    }
+                    pushExecutionHistory({
+                        commandId: `ai:${task}`,
+                        label: `AI Assist (${task})`,
+                        category: "workspace",
+                        status: "ok",
+                        dryRun: false,
+                        durationMs: Date.now() - startedAt,
+                        correlationId: "",
+                        repoPath: repoPath || "(unknown)",
+                        errorCode: "",
+                        errorMessage: "",
+                    });
+                    return aiText;
+                } catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    pushExecutionHistory({
+                        commandId: `ai:${task}`,
+                        label: `AI Assist (${task})`,
+                        category: "workspace",
+                        status: "failed",
+                        dryRun: false,
+                        durationMs: Date.now() - startedAt,
+                        correlationId: "",
+                        repoPath: String(repoInput.value || "").trim() || "(unknown)",
+                        errorCode: parseErrorCodeFromMessage(message),
+                        errorMessage: message,
+                    });
+                    throw error;
+                }
+            };
+
+            const runCommitStaged = async (dryRun = false) => {
+                const startedAt = Date.now();
+                let repoPath = "";
+                const message = String(commitMessageInput.value || "").trim();
+                if (!message) {
+                    throw new Error("Commit message is required. Generate one with AI or enter it manually.");
+                }
+
+                try {
+                    repoPath = await persistRepoPath(true);
+                    setMeta(`Running commit in ${repoPath}...`);
+                    const envelope = await window.createBackendReq("UI_MESSAGE", {
+                        handler: BUILD_COMMIT_REQUEST_HANDLER,
+                        content: {
+                            cwd: repoPath,
+                            message,
+                            dryRun,
+                        },
+                    });
+
+                    if (!envelope || typeof envelope !== "object") {
+                        throw new Error("Plugin backend did not return a structured commit request envelope.");
+                    }
+
+                    const envelopeCorrelationId = resolveEnvelopeCorrelationId(envelope);
+                    const backendErrorCode = typeof envelope?.code === "string" ? envelope.code.trim() : "";
+                    const backendErrorText = typeof envelope?.error === "string" ? envelope.error.trim() : "";
+                    if (
+                        envelope?.ok === false
+                        || envelope?.success === false
+                        || Boolean(backendErrorCode)
+                        || Boolean(backendErrorText)
+                    ) {
+                        const codeSuffix = backendErrorCode ? ` (${backendErrorCode})` : "";
+                        throw new Error(
+                            `Commit request preparation failed${codeSuffix}: ${backendErrorText || "Plugin backend handler failed."}\nCorrelation ID: ${envelopeCorrelationId || "unknown"}`
+                        );
+                    }
+
+                    const { response } = await executePrivilegedRequestEnvelope(envelope, {
+                        context: "Git commit failed",
+                        cwdHint: repoPath,
+                    });
+                    const result = response.result || {};
+                    const stdout = String(result.stdout || "");
+                    const stderr = String(result.stderr || "");
+                    const header = [
+                        `$ ${result.command || state.gitCommand} ${Array.isArray(result.args) ? result.args.join(" ") : operationCatalog.commitStaged.args.join(" ")}`,
+                        `# cwd: ${result.cwd || repoPath}`,
+                        `# mode: ${dryRun ? "dry-run" : "apply"}`,
+                        `# correlationId: ${response.correlationId || envelopeCorrelationId || "unknown"}`,
+                    ].join("\n");
+                    const payload = stdout || stderr
+                        ? [stdout, stderr ? `[stderr]\n${stderr}` : ""].filter(Boolean).join("\n\n")
+                        : "(no output)";
+                    setOutput(`${header}\n\n${payload}`);
+
+                    pushExecutionHistory({
+                        commandId: "commitStaged",
+                        label: "Commit Staged Changes",
+                        category: "workspace",
+                        status: "ok",
+                        dryRun,
+                        durationMs: Date.now() - startedAt,
+                        correlationId: response.correlationId || envelopeCorrelationId || "unknown",
+                        repoPath: repoPath || "(unknown)",
+                        errorCode: "",
+                        errorMessage: "",
+                    });
+                    setMeta(`Commit ${dryRun ? "(dry-run) " : ""}completed successfully.`);
+                    notifySuccess(`Commit ${dryRun ? "(dry-run) " : ""}completed`);
+                } catch (error) {
+                    const errMessage = error instanceof Error ? error.message : String(error);
+                    pushExecutionHistory({
+                        commandId: "commitStaged",
+                        label: "Commit Staged Changes",
+                        category: "workspace",
+                        status: "failed",
+                        dryRun,
+                        durationMs: Date.now() - startedAt,
+                        correlationId: "",
+                        repoPath: repoPath || String(repoInput.value || "").trim() || "(unknown)",
+                        errorCode: parseErrorCodeFromMessage(errMessage),
+                        errorMessage: errMessage,
+                    });
+                    throw error;
+                }
+            };
+
+            const bindOperation = (button: HTMLButtonElement, operationId: string) => {
+                button.addEventListener("click", async () => {
+                    setBusy(true);
+                    try {
+                        await runOperation(operationId);
+                    } catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        setOutput(`Operation failed:\n${message}`);
+                        setMeta(`Last operation failed: ${message}`);
+                        notifyError("Git operation failed");
+                    } finally {
+                        setBusy(false);
+                    }
+                });
+            };
+
+            bindOperation(statusButton, "status");
+            bindOperation(branchesButton, "branches");
+            bindOperation(logButton, "log");
+            bindOperation(diffButton, "diffStat");
+            bindOperation(showButton, "showHead");
+            bindOperation(fetchButton, "fetch");
+            bindOperation(pullButton, "pullFFOnly");
+            commitButton.addEventListener("click", async () => {
+                setBusy(true);
+                try {
+                    await runCommitStaged(false);
+                } catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    setOutput(`Commit failed:\n${message}`);
+                    setMeta(`Commit failed: ${message}`);
+                    notifyError("Commit failed");
+                } finally {
+                    setBusy(false);
+                }
+            });
+            aiCommitMessageButton.addEventListener("click", async () => {
+                setBusy(true);
+                try {
+                    await requestAiAssistance("commit-message");
+                } catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    setMeta(`AI commit message generation failed: ${message}`);
+                    notifyError("AI commit message generation failed");
+                } finally {
+                    setBusy(false);
+                }
+            });
+            aiSummarizeOutputButton.addEventListener("click", async () => {
+                setBusy(true);
+                try {
+                    await requestAiAssistance("summarize-output");
+                } catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    setMeta(`AI output summary failed: ${message}`);
+                    notifyError("AI output summary failed");
+                } finally {
+                    setBusy(false);
+                }
+            });
+            aiSuggestNextButton.addEventListener("click", async () => {
+                setBusy(true);
+                try {
+                    await requestAiAssistance("suggest-next-command");
+                } catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    setMeta(`AI next-step suggestion failed: ${message}`);
+                    notifyError("AI next-step suggestion failed");
+                } finally {
+                    setBusy(false);
+                }
+            });
+            aiRefreshAssistantsButton.addEventListener("click", async () => {
+                setBusy(true);
+                try {
+                    await fetchAssistants(false, true);
+                } catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    setMeta(`AI assistant refresh failed: ${message}`);
+                    notifyError("AI assistant refresh failed");
+                } finally {
+                    setBusy(false);
+                }
+            });
+            aiAssistantSelect.addEventListener("change", () => {
+                state.selectedAssistantId = String(aiAssistantSelect.value || "").trim();
+                const selectedAssistant = state.aiAssistants.find((item) => item.id === state.selectedAssistantId) || null;
+                if (selectedAssistant) {
+                    setMeta(`AI assistant selected: ${selectedAssistant.name} (${selectedAssistant.provider || "unknown"} / ${selectedAssistant.model || "default"}).`);
+                    return;
+                }
+                setMeta(`AI assistant routing uses host default (${AI_ASSISTANT_PURPOSE || "automation"} purpose).`);
+            });
+
+            savePathButton.addEventListener("click", async () => {
+                setBusy(true);
+                try {
+                    await persistRepoPath(false);
+                } catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    setMeta(`Save path failed: ${message}`);
+                    notifyError("Failed to save repository path");
+                } finally {
+                    setBusy(false);
+                }
+            });
+
+            prefetchOriginalButton.addEventListener("click", async () => {
+                setBusy(true);
+                try {
+                    const originalPath = await prefetchOriginalRepoPath(false);
+                    repoInput.value = originalPath;
+                } catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    setMeta(`Prefetch failed: ${message}`);
+                    notifyError("Failed to prefetch original repository");
+                } finally {
+                    setBusy(false);
+                }
+            });
+
+            snapshotButton.addEventListener("click", () => {
+                void runSnapshot();
+            });
+
+            repoInput.addEventListener("blur", () => {
+                void persistRepoPath(true).catch(() => {
+                    // Keep blur-save best-effort; explicit Save button surfaces errors.
+                });
+            });
+
+            repoInput.addEventListener("keydown", (event: KeyboardEvent) => {
+                if (event.key === "Enter") {
+                    event.preventDefault();
+                    void persistRepoPath(false).catch((error) => {
+                        const message = error instanceof Error ? error.message : String(error);
+                        setMeta(`Save path failed: ${message}`);
+                    });
+                }
+            });
+
+            commitMessageInput.addEventListener("keydown", (event: KeyboardEvent) => {
+                if (event.key === "Enter") {
+                    event.preventDefault();
+                    setBusy(true);
+                    void runCommitStaged(event.shiftKey)
+                        .catch((error) => {
+                            const message = error instanceof Error ? error.message : String(error);
+                            setOutput(`Commit failed:\n${message}`);
+                            setMeta(`Commit failed: ${message}`);
+                            notifyError("Commit failed");
+                        })
+                        .finally(() => {
+                            setBusy(false);
+                        });
+                }
+            });
+
+            const prepareRuntime = async () => {
+                try {
+                    setMeta("Preparing runtime...");
+                    const response = await window.createBackendReq("UI_MESSAGE", {
+                        handler: PREPARE_HANDLER,
+                        content: {},
+                    });
+
+                    if (response && typeof response === "object") {
+                        if (response.ok === false || response.success === false) {
+                            const code = typeof response.code === "string" ? ` (${response.code})` : "";
+                            const errorText = typeof response.error === "string"
+                                ? response.error
+                                : "Unknown runtime preparation error.";
+                            setMeta(`Runtime preparation degraded${code}: ${errorText}`);
+                        }
+                        if (typeof response.gitCommand === "string" && response.gitCommand.trim()) {
+                            state.gitCommand = response.gitCommand.trim();
+                        }
+                        if (typeof response.defaultRepoPath === "string" && response.defaultRepoPath.trim()) {
+                            repoInput.value = response.defaultRepoPath.trim();
+                        }
+                        if (typeof response.storageMode === "string" && response.storageMode.trim()) {
+                            state.storageMode = response.storageMode.trim();
+                        }
+                        if (typeof response.storageDiagnostic === "string" && response.storageDiagnostic.trim()) {
+                            state.storageDiagnostic = response.storageDiagnostic.trim();
+                        } else {
+                            state.storageDiagnostic = "";
+                        }
+                        if (typeof response.originalConfiguredRepoPath === "string" && response.originalConfiguredRepoPath.trim()) {
+                            state.originalConfiguredRepoPath = response.originalConfiguredRepoPath.trim();
+                        }
+                        if (typeof response.originalConfiguredRepoPublicKey === "string" && response.originalConfiguredRepoPublicKey.trim()) {
+                            state.originalConfiguredRepoPublicKey = response.originalConfiguredRepoPublicKey.trim();
+                        }
+                        const lastAction = typeof response.lastAction === "string"
+                            ? response.lastAction.trim()
+                            : "none";
+                        const prefetchHint = state.originalConfiguredRepoPath
+                            ? ` Original configured repository (public key ${state.originalConfiguredRepoPublicKey}): ${state.originalConfiguredRepoPath}.`
+                            : "";
+                        setMeta(`Ready [build: ${BUILD_ID}]. Executable: ${state.gitCommand}. Storage mode: ${state.storageMode}.${prefetchHint} Last action: ${lastAction}. No command executed yet.`);
+                    } else {
+                        setMeta(`Ready [build: ${BUILD_ID}]. Executable: ${state.gitCommand}. Storage mode: ${state.storageMode}. No command executed yet.`);
+                    }
+
+                    state.runtimePrepared = true;
+                    renderSummary(null);
+                    renderStagedFilesHint(null);
+                    renderExecutionHistory();
+                    setOutput("$ runtime ready. choose an operation or run snapshot.");
+                    await fetchAssistants(true).catch((error) => {
+                        const message = error instanceof Error ? error.message : String(error);
+                        setMeta(`Ready [build: ${BUILD_ID}]. Executable: ${state.gitCommand}. Storage mode: ${state.storageMode}. Assistant discovery unavailable: ${message}`);
+                    });
+                } catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    setMeta(`Runtime preparation failed: ${message}`);
+                    setOutput(`Runtime preparation failed:\n${message}`);
+                }
+            };
+
+            void prepareRuntime();
+        }
+
+        return defineRenderOnLoad(gitOperationsRenderOnLoad, {
+            language: "typescript",
+            description: "Interactive iframe runtime wiring for Git operations, storage persistence, and scoped privileged action flows.",
+        });
+    }
+}
+
+new GitOperationsPlugin();
diff --git a/examples/13-service-content-hub-plugin.ts b/examples/13-service-content-hub-plugin.ts
new file mode 100644
index 0000000..75b4d65
--- /dev/null
+++ b/examples/13-service-content-hub-plugin.ts
@@ -0,0 +1,2509 @@
+import {
+    createAICapabilityPreset,
+    createClipboardWriteRequest,
+    DOMButton,
+    DOMInput,
+    createNetworkCapabilityBundle,
+    createStorageCapabilityPreset,
+    defineRenderOnLoadActions,
+    DOMNested,
+    DOMSemantic,
+    DOMText,
+    FDOInterface,
+    FDO_SDK,
+    PluginCapability,
+    PluginMetadata,
+    PluginRegistry,
+    QuickAction,
+    requireCapability,
+    requireNetworkScopeCapability,
+    runCapabilityPreflight,
+    SidePanelConfig,
+    StoreType,
+} from "@anikitenko/fdo-sdk";
+
+type ServiceContext = {
+    providerId: string;
+    accountId: string;
+    sessionId: string;
+    endpointUrl: string;
+    workspaceId: string;
+    path: string;
+    authClientId: string;
+    authTenantId: string;
+    authRedirectUri: string;
+    authScopes: string;
+    authDeviceCode: string;
+    authVerificationUri: string;
+    authVerificationUriComplete: string;
+    authUserCode: string;
+    authPollIntervalSeconds: number;
+    authCodeExpiresAt: string;
+};
+
+type ContentItem = {
+    id: string;
+    name: string;
+    kind: "site" | "workspace" | "folder" | "file";
+    webUrl: string;
+    parentPath?: string;
+    lastModifiedAt?: string;
+};
+
+type AuthBroker = {
+    start?: (input: { providerId: string; accountHint?: string; endpointUrl?: string }) => unknown;
+    refresh?: (input: { providerId: string; sessionId: string }) => unknown;
+    logout?: (input: { providerId: string; sessionId: string }) => unknown;
+};
+
+type ContentBroker = {
+    request?: (input: {
+        providerId: string;
+        sessionId: string;
+        operation: string;
+        endpointUrl?: string;
+        workspaceId?: string;
+        path?: string;
+        query?: string;
+        itemId?: string;
+        scope?: "organization" | "anonymous";
+        type?: "view" | "edit";
+        limit?: number;
+        cursor?: string;
+    }) => unknown;
+    invoke?: (input: {
+        providerId: string;
+        sessionId: string;
+        operation: string;
+        endpointUrl?: string;
+        workspaceId?: string;
+        path?: string;
+        query?: string;
+        itemId?: string;
+        scope?: "organization" | "anonymous";
+        type?: "view" | "edit";
+        limit?: number;
+        cursor?: string;
+    }) => unknown;
+    listWorkspaces?: (input: {
+        providerId: string;
+        sessionId: string;
+        endpointUrl?: string;
+        query?: string;
+        limit?: number;
+        cursor?: string;
+    }) => unknown;
+    listItems?: (input: {
+        providerId: string;
+        sessionId: string;
+        endpointUrl?: string;
+        workspaceId: string;
+        path?: string;
+        limit?: number;
+        cursor?: string;
+    }) => unknown;
+    search?: (input: {
+        providerId: string;
+        sessionId: string;
+        endpointUrl?: string;
+        workspaceId?: string;
+        query: string;
+        limit?: number;
+        cursor?: string;
+    }) => unknown;
+    createShareLink?: (input: {
+        providerId: string;
+        sessionId: string;
+        endpointUrl?: string;
+        itemId: string;
+        scope?: "organization" | "anonymous";
+        type?: "view" | "edit";
+    }) => unknown;
+};
+
+type OpenUrlBroker = {
+    open?: (input: { url: string; policy: "trusted-content-link" }) => unknown;
+};
+
+type SessionRequestBroker = {
+    request?: (input: {
+        sessionId: string;
+        method: string;
+        url: string;
+        query?: Record<string, string | number | boolean>;
+        headers?: Record<string, string>;
+        body?: unknown;
+    }) => unknown;
+};
+
+const DEFAULT_CONTEXT: ServiceContext = {
+    providerId: "sharepoint",
+    accountId: "",
+    sessionId: "",
+    endpointUrl: "",
+    workspaceId: "",
+    path: "/",
+    authClientId: "",
+    authTenantId: "common",
+    authRedirectUri: "http://localhost",
+    authScopes: "openid profile offline_access User.Read Files.Read.All Sites.Read.All",
+    authDeviceCode: "",
+    authVerificationUri: "",
+    authVerificationUriComplete: "",
+    authUserCode: "",
+    authPollIntervalSeconds: 5,
+    authCodeExpiresAt: "",
+};
+
+export default class ServiceContentHubPlugin extends FDO_SDK implements FDOInterface {
+    private static readonly BUILD_ID = "service-hub-2026-04-18-r3";
+    private static readonly NETWORK_SCOPE_ID = "external-services";
+    private static readonly PROVIDER_ENDPOINT_DEFAULTS: Record<string, string> = {
+        sharepoint: "https://graph.microsoft.com/v1.0",
+        dropbox: "https://api.dropboxapi.com/2",
+        gdrive: "https://www.googleapis.com/drive/v3",
+        confluence: "https://api.atlassian.com/ex/confluence",
+    };
+
+    private static readonly PREPARE_HANDLER = "serviceHub.v1.prepare";
+    private static readonly SAVE_CONTEXT_HANDLER = "serviceHub.v1.saveContext";
+    private static readonly AUTH_START_HANDLER = "serviceHub.v1.auth.start";
+    private static readonly AUTH_REFRESH_HANDLER = "serviceHub.v1.auth.refresh";
+    private static readonly AUTH_LOGOUT_HANDLER = "serviceHub.v1.auth.logout";
+    private static readonly LIST_WORKSPACES_HANDLER = "serviceHub.v1.content.listWorkspaces";
+    private static readonly LIST_ITEMS_HANDLER = "serviceHub.v1.content.listItems";
+    private static readonly SEARCH_ITEMS_HANDLER = "serviceHub.v1.content.search";
+    private static readonly CREATE_SHARE_LINK_HANDLER = "serviceHub.v1.content.createShareLink";
+    private static readonly BUILD_CLIPBOARD_WRITE_REQUEST_HANDLER = "serviceHub.v1.buildClipboardWriteRequest";
+    private static readonly OPEN_BROWSER_HANDLER = "serviceHub.v1.openBrowser";
+    private static readonly ADD_FAVORITE_HANDLER = "serviceHub.v1.addFavorite";
+    private static readonly AI_ASSIST_HANDLER = "fdo.ai.request.v1";
+    private static readonly AI_ASSISTANTS_LIST_HANDLER = "fdo.ai.assistants.list.v1";
+    private static readonly DEFAULT_AUTH_TENANT = "common";
+    private static readonly DEFAULT_AUTH_REDIRECT_URI = "http://localhost";
+    private static readonly DEFAULT_AUTH_SCOPES = "openid profile offline_access User.Read Files.Read.All Sites.Read.All";
+    private static readonly QUICK_OPEN_FAVORITES_HANDLER = "serviceHub.v1.quick.openFavorites";
+    private static readonly QUICK_SEARCH_HANDLER = "serviceHub.v1.quick.search";
+    private static readonly SIDE_PANEL_BROWSER_HANDLER = "serviceHub.v1.sidePanel.browser";
+    private static readonly SIDE_PANEL_RECENT_HANDLER = "serviceHub.v1.sidePanel.recent";
+    private static readonly SIDE_PANEL_SETTINGS_HANDLER = "serviceHub.v1.sidePanel.settings";
+
+    private static readonly STORAGE_KEYS = {
+        CONTEXT: "serviceHub:context",
+        FAVORITES: "serviceHub:favorites",
+        RECENT_ACTIVITY: "serviceHub:recentActivity",
+        LAST_CURSOR: "serviceHub:lastCursor",
+    } as const;
+
+    private readonly _metadata: PluginMetadata = {
+        name: "SharePoint Desktop Client Plugin",
+        version: "1.0.0",
+        author: "FDO SDK",
+        description: "SharePoint Online desktop client example with plugin-owned Microsoft login flow.",
+        icon: "applications",
+    };
+
+    private readonly declaredCapabilities: PluginCapability[] = [
+        ...createNetworkCapabilityBundle({
+            transports: ["https"],
+            scopeId: ServiceContentHubPlugin.NETWORK_SCOPE_ID,
+        }),
+        "system.network.scope.external-services",
+        ...createStorageCapabilityPreset("storageJSON"),
+        ...createAICapabilityPreset("host.ai"),
+        "system.clipboard.write",
+    ];
+
+    private sessionStore?: StoreType;
+    private persistentStore?: StoreType;
+    private jsonStoreAvailable = false;
+    private handlersRegistered = false;
+
+    constructor() {
+        super();
+        this.registerHandlers();
+    }
+
+    get metadata(): PluginMetadata {
+        return this._metadata;
+    }
+
+    declareCapabilities(): PluginCapability[] {
+        return [...this.declaredCapabilities];
+    }
+
+    defineQuickActions(): QuickAction[] {
+        return [
+            {
+                name: "Service Favorites",
+                subtitle: "Open pinned items from connected services",
+                icon: "star",
+                message_type: ServiceContentHubPlugin.QUICK_OPEN_FAVORITES_HANDLER,
+            },
+            {
+                name: "Service Search",
+                subtitle: "Focus search workflow",
+                icon: "search",
+                message_type: ServiceContentHubPlugin.QUICK_SEARCH_HANDLER,
+            },
+        ];
+    }
+
+    defineSidePanel(): SidePanelConfig {
+        return {
+            icon: "applications",
+            label: "Service Hub",
+            submenu_list: [
+                {
+                    id: "service-browser",
+                    name: "Browser",
+                    message_type: ServiceContentHubPlugin.SIDE_PANEL_BROWSER_HANDLER,
+                },
+                {
+                    id: "service-recent",
+                    name: "Recent",
+                    message_type: ServiceContentHubPlugin.SIDE_PANEL_RECENT_HANDLER,
+                },
+                {
+                    id: "service-settings",
+                    name: "Settings",
+                    message_type: ServiceContentHubPlugin.SIDE_PANEL_SETTINGS_HANDLER,
+                },
+            ],
+        };
+    }
+
+    init(): void {
+        this.registerHandlers();
+        this.ensurePersistentStore();
+        const report = runCapabilityPreflight({
+            action: "initialize service content hub plugin",
+            declared: this.declaredCapabilities,
+            granted: this.getGrantedCapabilities(),
+        });
+        if (!report.ok) {
+            this.warn(`Service hub capability preflight warning: ${report.summary}`, {
+                missing: report.missing.map((entry) => entry.capability),
+                remediations: report.remediations,
+            });
+        }
+    }
+
+    render(): string {
+        const text = new DOMText();
+        const nested = new DOMNested();
+        const semantic = new DOMSemantic();
+        const button = new DOMButton();
+
+        const contextInputs = nested.createBlockDiv(
+            [
+                new DOMInput("sh-workspace-id", {}, {
+                    placeholder: "SharePoint Site ID",
+                }).createInput("text"),
+                new DOMInput("sh-path", {}, {
+                    placeholder: "Path (/)",
+                }).createInput("text"),
+            ],
+            { style: { display: "grid", gridTemplateColumns: "repeat(2, minmax(220px, 1fr))", gap: "8px" } }
+        );
+        const sharePointSiteIdHelp = nested.createBlockDiv(
+            [
+                text.createPText(
+                    "SharePoint Site ID is not something you invent. It is the exact id returned by Microsoft Graph for one SharePoint site.",
+                    { style: { margin: "0", color: "#334155", fontSize: "12px" } }
+                ),
+                text.createPText(
+                    "Easiest way in this example: sign in, type part of the site name into Search query, click List Workspaces, then copy the id from the result you want.",
+                    { style: { margin: "0", color: "#334155", fontSize: "12px" } }
+                ),
+                text.createPText(
+                    "If you already know the SharePoint site URL, for example https://contoso.sharepoint.com/sites/Marketing, open Graph Explorer and run: GET /sites/contoso.sharepoint.com:/sites/Marketing. Then copy the id field from the response into this box.",
+                    { style: { margin: "0", color: "#334155", fontSize: "12px" } }
+                ),
+                text.createPText(
+                    "Why the id looks unusual: Graph site ids usually look like contoso.sharepoint.com,GUID,GUID. That is normal. The two GUID values are different internal identifiers, not a duplicate by mistake.",
+                    { style: { margin: "0", color: "#334155", fontSize: "12px" } }
+                ),
+            ],
+            {
+                style: {
+                    display: "grid",
+                    gap: "4px",
+                    background: "#f8fafc",
+                    border: "1px solid #cbd5e1",
+                    borderRadius: "8px",
+                    padding: "10px 12px",
+                },
+            }
+        );
+        const sharePointAuthInputs = nested.createBlockDiv(
+            [
+                new DOMInput("sh-auth-client-id", {}, {
+                    placeholder: "SharePoint App (client) ID",
+                }).createInput("text"),
+                new DOMInput("sh-auth-tenant-id", {}, {
+                    placeholder: "Tenant ID or domain (for example: organizations or your-tenant-id)",
+                }).createInput("text"),
+            ],
+            { style: { display: "grid", gridTemplateColumns: "repeat(2, minmax(280px, 420px))", gap: "8px" } }
+        );
+
+        const authActions = nested.createBlockDiv(
+            [
+                button.createStaticButton("Save Context", { classes: ["pure-button-primary"] }, "sh-save-context"),
+                button.createStaticButton("Sign in with Microsoft", { classes: ["pure-button-primary"] }, "sh-ms-login"),
+                button.createStaticButton("Auth Refresh", {}, "sh-auth-refresh"),
+                button.createStaticButton("Sign Out", {}, "sh-auth-logout"),
+            ],
+            { style: { display: "flex", gap: "8px", flexWrap: "wrap" } }
+        );
+        const sharePointSetupCard = nested.createBlockDiv(
+            [
+                text.createHText(3, "Microsoft Setup", { style: { margin: "0 0 6px 0" } }),
+                text.createPText(
+                    "1. Open portal.azure.com and go to Microsoft Entra ID -> App registrations.",
+                    { style: { margin: "0", color: "#334155", fontSize: "12px" } }
+                ),
+                text.createPText(
+                    "2. Create or open your app, then copy Application (client) ID from the Overview page.",
+                    { style: { margin: "0", color: "#334155", fontSize: "12px" } }
+                ),
+                text.createPText(
+                    "3. In Authentication, enable Public client/native access for the app registration.",
+                    { style: { margin: "0", color: "#334155", fontSize: "12px" } }
+                ),
+                text.createPText(
+                    "4. In API permissions, add delegated Microsoft Graph permissions such as User.Read, Files.Read.All, and Sites.Read.All.",
+                    { style: { margin: "0", color: "#334155", fontSize: "12px" } }
+                ),
+            ],
+            {
+                style: {
+                    display: "grid",
+                    gap: "4px",
+                    background: "#eef6ff",
+                    border: "1px solid #bfdbfe",
+                    borderRadius: "8px",
+                    padding: "12px",
+                },
+            }
+        );
+
+        const queryActions = nested.createBlockDiv(
+            [
+                button.createStaticButton("List Workspaces", {}, "sh-list-workspaces"),
+                button.createStaticButton("List Items", {}, "sh-list-items"),
+                button.createStaticButton("Next Page", {}, "sh-next-page"),
+                new DOMInput("sh-cursor", { style: { minWidth: "220px" } }, {
+                    placeholder: "Cursor (optional)",
+                }).createInput("text"),
+                new DOMInput("sh-search-query", { style: { minWidth: "240px" } }, {
+                    placeholder: "Search query...",
+                }).createInput("text"),
+                button.createStaticButton("Search", { classes: ["pure-button-primary"] }, "sh-search-items"),
+            ],
+            { style: { display: "flex", gap: "8px", flexWrap: "wrap" } }
+        );
+
+        const selectionActions = nested.createBlockDiv(
+            [
+                new DOMInput("sh-selected-item-id", { style: { minWidth: "320px" } }).createSelect([
+                    new DOMInput("sh-selected-item-id-option").createOption("Select a result row...", ""),
+                ]),
+                button.createStaticButton("Create Share Link", {}, "sh-create-share-link"),
+                button.createStaticButton("Open In Browser", {}, "sh-open-browser"),
+                button.createStaticButton("Copy Link", {}, "sh-copy-share-link"),
+                button.createStaticButton("Add Selected To Favorites", {}, "sh-add-favorite"),
+                button.createStaticButton("AI Summarize", {}, "sh-ai-summarize"),
+            ],
+            { style: { display: "flex", gap: "8px", flexWrap: "wrap" } }
+        );
+
+        const cards = nested.createBlockDiv(
+            [
+                nested.createBlockDiv(
+                    [
+                        text.createHText(3, "Favorites", { style: { margin: "0 0 8px 0" } }),
+                        nested.createBlockDiv([], {
+                            style: {
+                                background: "#f6f7f9",
+                                borderRadius: "6px",
+                                padding: "10px",
+                                minHeight: "120px",
+                            },
+                        }, "sh-favorites"),
+                    ]
+                ),
+                nested.createBlockDiv(
+                    [
+                        text.createHText(3, "Recent Activity", { style: { margin: "0 0 8px 0" } }),
+                        nested.createBlockDiv([], {
+                            style: {
+                                background: "#f6f7f9",
+                                borderRadius: "6px",
+                                padding: "10px",
+                                minHeight: "120px",
+                            },
+                        }, "sh-recent"),
+                    ]
+                ),
+            ],
+            { style: { display: "grid", gridTemplateColumns: "repeat(2, minmax(280px, 1fr))", gap: "12px" } }
+        );
+
+        const appBody = nested.createBlockDiv(
+            [
+                text.createHText(2, "SharePoint Desktop Client", { style: { margin: "0" } }),
+                text.createPText(
+                    "SharePoint Online example: the plugin owns Microsoft sign-in flow and the host remains session-transport infrastructure.",
+                    { style: { margin: "0", color: "#5f6b7c" } }
+                ),
+                text.createPText(
+                    "Microsoft Graph still requires an app registration in Microsoft Entra ID. Enter the Application (client) ID and tenant here, then use Log In with Microsoft. This example uses Microsoft device code flow, so there is no localhost redirect back into FDO.",
+                    { style: { margin: "0", color: "#5f6b7c", fontSize: "12px" } }
+                ),
+                sharePointSetupCard,
+                contextInputs,
+                sharePointSiteIdHelp,
+                sharePointAuthInputs,
+                authActions,
+                queryActions,
+                selectionActions,
+                text.createPText("Runtime not prepared yet.", { style: { margin: "0", color: "#5f6b7c" } }, "sh-meta"),
+                text.createPreText("No results yet.", {
+                    style: {
+                        margin: "0",
+                        minHeight: "220px",
+                        maxHeight: "420px",
+                        overflow: "auto",
+                        background: "#f6f7f9",
+                        padding: "12px",
+                        borderRadius: "6px",
+                    },
+                }, "sh-output"),
+                cards,
+            ],
+            { style: { padding: "16px", display: "grid", gap: "12px" } }
+        );
+
+        const app = nested.createBlockDiv([appBody], {
+            customAttributes: {
+                "data-build-id": ServiceContentHubPlugin.BUILD_ID,
+                "data-prepare-handler": ServiceContentHubPlugin.PREPARE_HANDLER,
+                "data-save-context-handler": ServiceContentHubPlugin.SAVE_CONTEXT_HANDLER,
+                "data-auth-start-handler": ServiceContentHubPlugin.AUTH_START_HANDLER,
+                "data-auth-refresh-handler": ServiceContentHubPlugin.AUTH_REFRESH_HANDLER,
+                "data-auth-logout-handler": ServiceContentHubPlugin.AUTH_LOGOUT_HANDLER,
+                "data-list-workspaces-handler": ServiceContentHubPlugin.LIST_WORKSPACES_HANDLER,
+                "data-list-items-handler": ServiceContentHubPlugin.LIST_ITEMS_HANDLER,
+                "data-search-items-handler": ServiceContentHubPlugin.SEARCH_ITEMS_HANDLER,
+                "data-create-share-link-handler": ServiceContentHubPlugin.CREATE_SHARE_LINK_HANDLER,
+                "data-copy-link-handler": ServiceContentHubPlugin.BUILD_CLIPBOARD_WRITE_REQUEST_HANDLER,
+                "data-open-browser-handler": ServiceContentHubPlugin.OPEN_BROWSER_HANDLER,
+                "data-add-favorite-handler": ServiceContentHubPlugin.ADD_FAVORITE_HANDLER,
+                "data-ai-assist-handler": ServiceContentHubPlugin.AI_ASSIST_HANDLER,
+                "data-ai-assistants-handler": ServiceContentHubPlugin.AI_ASSISTANTS_LIST_HANDLER,
+                "data-auth-client-id": "",
+                "data-auth-tenant-id": ServiceContentHubPlugin.DEFAULT_AUTH_TENANT,
+                "data-auth-redirect-uri": ServiceContentHubPlugin.DEFAULT_AUTH_REDIRECT_URI,
+                "data-auth-scopes": ServiceContentHubPlugin.DEFAULT_AUTH_SCOPES,
+            },
+        }, "service-hub-root");
+
+        return semantic.renderHTML(
+            semantic.createMain([app], { style: { padding: "0", margin: "0" } })
+        );
+    }
+
+    renderOnLoad() {
+        return defineRenderOnLoadActions({
+            setup: () => {
+                const root = document.getElementById("service-hub-root");
+                if (!root) {
+                    return;
+                }
+                const readConfig = (attr: string, fallback: string): string => {
+                    const value = root.getAttribute(attr);
+                    return typeof value === "string" && value.trim() ? value.trim() : fallback;
+                };
+                const byId = (id: string) => document.getElementById(id);
+                const readInput = (id: string) => {
+                    const element = byId(id) as HTMLInputElement | null;
+                    return element ? String(element.value || "").trim() : "";
+                };
+                const setText = (id: string, value: string) => {
+                    const element = byId(id);
+                    if (element) {
+                        element.textContent = value;
+                    }
+                };
+                const runtimeWindow = window as {
+                    Notyf?: new (options?: unknown) => {
+                        success: (message: string) => void;
+                        error: (message: string) => void;
+                    };
+                    waitForElement?: (selector: string, callback: () => void) => void;
+                };
+                if (typeof runtimeWindow.waitForElement === "function") {
+                    runtimeWindow.waitForElement("#sh-output", () => undefined);
+                }
+                const notifier = typeof runtimeWindow.Notyf === "function"
+                    ? new runtimeWindow.Notyf({ duration: 2400, position: { x: "right", y: "top" } })
+                    : null;
+                const notifySuccess = (message: string) => {
+                    notifier?.success(message);
+                };
+                const callBackend = async (handler: string, content: unknown) => {
+                    return window.createBackendReq("UI_MESSAGE", { handler, content });
+                };
+                const handlers = {
+                    prepare: readConfig("data-prepare-handler", "serviceHub.v1.prepare"),
+                    saveContext: readConfig("data-save-context-handler", "serviceHub.v1.saveContext"),
+                    authStart: readConfig("data-auth-start-handler", "serviceHub.v1.auth.start"),
+                    authRefresh: readConfig("data-auth-refresh-handler", "serviceHub.v1.auth.refresh"),
+                    authLogout: readConfig("data-auth-logout-handler", "serviceHub.v1.auth.logout"),
+                    listWorkspaces: readConfig("data-list-workspaces-handler", "serviceHub.v1.content.listWorkspaces"),
+                    listItems: readConfig("data-list-items-handler", "serviceHub.v1.content.listItems"),
+                    searchItems: readConfig("data-search-items-handler", "serviceHub.v1.content.search"),
+                    createShareLink: readConfig("data-create-share-link-handler", "serviceHub.v1.content.createShareLink"),
+                    copyLink: readConfig("data-copy-link-handler", "serviceHub.v1.buildClipboardWriteRequest"),
+                    openBrowser: readConfig("data-open-browser-handler", "serviceHub.v1.openBrowser"),
+                    addFavorite: readConfig("data-add-favorite-handler", "serviceHub.v1.addFavorite"),
+                    aiAssist: readConfig("data-ai-assist-handler", "fdo.ai.request.v1"),
+                    aiAssistants: readConfig("data-ai-assistants-handler", "fdo.ai.assistants.list.v1"),
+                };
+                const readAuthInput = (id: string, fallbackAttr: string, fallbackDefault: string) => {
+                    const value = readInput(id);
+                    if (value) return value;
+                    return readConfig(fallbackAttr, fallbackDefault);
+                };
+                const state = {
+                    busy: false,
+                    lastResults: [] as Array<Record<string, unknown>>,
+                    lastShareLink: "",
+                    aiAssistantId: "",
+                    activeOperation: "listWorkspaces" as "listWorkspaces" | "listItems" | "searchItems",
+                    nextCursor: "",
+                    authPending: false,
+                    isAuthenticated: false,
+                };
+                const syncAuthUi = () => {
+                    const authRefreshButton = byId("sh-auth-refresh") as HTMLButtonElement | null;
+                    const authLogoutButton = byId("sh-auth-logout") as HTMLButtonElement | null;
+                    if (authRefreshButton) {
+                        authRefreshButton.disabled = state.busy || (!state.authPending && !state.isAuthenticated);
+                    }
+                    if (authLogoutButton) {
+                        authLogoutButton.disabled = state.busy || !state.isAuthenticated;
+                    }
+                    [
+                        "sh-list-workspaces",
+                        "sh-list-items",
+                        "sh-next-page",
+                        "sh-search-items",
+                        "sh-create-share-link",
+                        "sh-open-browser",
+                        "sh-copy-share-link",
+                        "sh-add-favorite",
+                        "sh-ai-summarize",
+                    ].forEach((id) => {
+                        const button = byId(id) as HTMLButtonElement | null;
+                        if (button) {
+                            button.disabled = state.busy || !state.isAuthenticated;
+                        }
+                    });
+                };
+                const pickAuthSource = (payload: unknown): Record<string, unknown> => {
+                    if (!payload || typeof payload !== "object") {
+                        return {};
+                    }
+                    const record = payload as Record<string, unknown>;
+                    if (record.raw && typeof record.raw === "object") {
+                        return record.raw as Record<string, unknown>;
+                    }
+                    return record;
+                };
+                const renderRows = (items: Array<Record<string, unknown>>) => {
+                    if (!items.length) return "No items.";
+                    return items.slice(0, 200).map((item, index) => {
+                        const name = typeof item.name === "string" ? item.name : "(unnamed)";
+                        const kind = typeof item.kind === "string" ? item.kind : "item";
+                        const webUrl = typeof item.webUrl === "string" ? item.webUrl : "";
+                        return `${index + 1}. [${kind}] ${name}${webUrl ? `\n   ${webUrl}` : ""}`;
+                    }).join("\n");
+                };
+                const renderListCard = (id: string, items: Array<Record<string, unknown>>, empty: string) => {
+                    const node = byId(id);
+                    if (!node) return;
+                    if (!items.length) {
+                        node.innerHTML = `<p style="margin:0;color:#5f6b7c;">${empty}</p>`;
+                        return;
+                    }
+                    node.innerHTML = items.slice(0, 20).map((item) => {
+                        const primary = typeof item.name === "string"
+                            ? item.name
+                            : (typeof item.action === "string" ? item.action : "(entry)");
+                        const detail = typeof item.webUrl === "string"
+                            ? item.webUrl
+                            : (typeof item.detail === "string" ? item.detail : "");
+                        const at = typeof item.at === "string" ? item.at : "";
+                        return `<p style="margin:0 0 6px 0;"><strong>${primary}</strong>${detail ? `<br /><span>${detail}</span>` : ""}${at ? `<br /><span style="color:#5f6b7c;">${at}</span>` : ""}</p>`;
+                    }).join("");
+                };
+                const buildContextPayload = () => ({
+                    providerId: "sharepoint",
+                    endpointUrl: "https://graph.microsoft.com/v1.0",
+                    accountId: "",
+                    workspaceId: readInput("sh-workspace-id"),
+                    path: readInput("sh-path") || "/",
+                    authConfig: {
+                        clientId: readAuthInput("sh-auth-client-id", "data-auth-client-id", ""),
+                        tenantId: readAuthInput("sh-auth-tenant-id", "data-auth-tenant-id", "common"),
+                        redirectUri: readConfig("data-auth-redirect-uri", "http://localhost"),
+                        scopes: readConfig("data-auth-scopes", "openid profile offline_access User.Read Files.Read.All Sites.Read.All"),
+                    },
+                });
+                const currentCursor = () => readInput("sh-cursor");
+                const renderAuthInstructions = (payload: {
+                    message?: string;
+                    verificationUrl?: string;
+                    userCode?: string;
+                }) => {
+                    const parts = [
+                        payload.message || "Open Microsoft verification, enter the displayed code, finish approval, then click Auth Refresh.",
+                        payload.verificationUrl ? `Verification URL: ${payload.verificationUrl}` : "",
+                        payload.userCode ? `User code: ${payload.userCode}` : "",
+                    ].filter(Boolean);
+                    setText("sh-output", parts.join("\n\n"));
+                };
+                const setBusy = (busy: boolean) => {
+                    state.busy = busy;
+                    [
+                        "sh-save-context",
+                        "sh-ms-login",
+                    ].forEach((id) => {
+                        const button = byId(id) as HTMLButtonElement | null;
+                        if (button) button.disabled = busy;
+                    });
+                    syncAuthUi();
+                };
+                const asItems = (response: unknown): Array<Record<string, unknown>> => {
+                    if (Array.isArray(response)) return response as Array<Record<string, unknown>>;
+                    if (response && typeof response === "object" && Array.isArray((response as { items?: unknown[] }).items)) {
+                        return (response as { items: Array<Record<string, unknown>> }).items;
+                    }
+                    return [];
+                };
+                const setSelectionOptions = (items: Array<Record<string, unknown>>) => {
+                    const select = byId("sh-selected-item-id") as HTMLSelectElement | null;
+                    if (!select) return;
+                    const rows = ['<option value="">Select a result row...</option>'];
+                    items.slice(0, 300).forEach((item, index) => {
+                        const id = typeof item.id === "string" ? item.id : "";
+                        if (!id) return;
+                        const name = typeof item.name === "string" ? item.name : "(unnamed)";
+                        const kind = typeof item.kind === "string" ? item.kind : "item";
+                        rows.push(`<option value="${id}">${index + 1}. [${kind}] ${name}</option>`);
+                    });
+                    select.innerHTML = rows.join("");
+                };
+                const setCursor = (cursor: string) => {
+                    const node = byId("sh-cursor") as HTMLInputElement | null;
+                    if (node) {
+                        node.value = cursor;
+                    }
+                };
+                const readResponseCursor = (response: unknown) => {
+                    if (!response || typeof response !== "object") {
+                        return "";
+                    }
+                    const direct = typeof (response as { nextCursor?: unknown }).nextCursor === "string"
+                        ? String((response as { nextCursor: string }).nextCursor).trim()
+                        : "";
+                    if (direct) {
+                        return direct;
+                    }
+                    const nested = (response as { page?: { nextCursor?: unknown } }).page;
+                    return typeof nested?.nextCursor === "string" ? nested.nextCursor.trim() : "";
+                };
+                const getSelectedItem = (): Record<string, unknown> | undefined => {
+                    const selectedId = readInput("sh-selected-item-id");
+                    if (selectedId) {
+                        const selected = state.lastResults.find((entry) => typeof entry.id === "string" && entry.id === selectedId);
+                        if (selected) return selected;
+                    }
+                    return state.lastResults[0];
+                };
+                const assertOk = (response: unknown, fallback: string) => {
+                    if (response && typeof response === "object" && (response as { ok?: unknown }).ok === false) {
+                        const code = typeof (response as { code?: unknown }).code === "string"
+                            ? String((response as { code: string }).code).trim()
+                            : "";
+                        const correlationId = typeof (response as { correlationId?: unknown }).correlationId === "string"
+                            ? String((response as { correlationId: string }).correlationId).trim()
+                            : "";
+                        const message = String((response as { error?: unknown }).error || fallback);
+                        throw new Error(`${code ? `${code}: ` : ""}${message}${correlationId ? ` [${correlationId}]` : ""}`);
+                    }
+                };
+
+                (window as { __serviceHubRuntime?: unknown }).__serviceHubRuntime = {
+                    async prepare() {
+                        const response = await callBackend(handlers.prepare, {});
+                        const context = response && typeof response === "object" && (response as { context?: unknown }).context
+                            ? (response as { context: Record<string, unknown> }).context
+                            : {};
+                        const setInput = (id: string, value: unknown, fallback = "") => {
+                            const element = byId(id) as HTMLInputElement | null;
+                            if (!element) return;
+                            element.value = typeof value === "string" && value.trim() ? value : fallback;
+                        };
+                        setInput("sh-workspace-id", context.workspaceId, "");
+                        setInput("sh-path", context.path, "/");
+                        setInput("sh-auth-client-id", context.authClientId, readConfig("data-auth-client-id", ""));
+                        setInput("sh-auth-tenant-id", context.authTenantId, readConfig("data-auth-tenant-id", "common"));
+                        setInput("sh-cursor", (response as { cursor?: unknown }).cursor, "");
+                        state.isAuthenticated = typeof context.sessionId === "string" && context.sessionId.trim().length > 0;
+                        state.authPending = typeof context.authDeviceCode === "string" && context.authDeviceCode.trim().length > 0;
+                        syncAuthUi();
+                        renderListCard("sh-favorites", asItems((response as { favorites?: unknown }).favorites), "No favorites yet.");
+                        renderListCard("sh-recent", asItems((response as { recentActivity?: unknown }).recentActivity), "No recent activity.");
+                        if (state.isAuthenticated) {
+                            setText("sh-meta", `Authenticated. Session restored. [build: ${readConfig("data-build-id", "unknown")}]`);
+                        } else if (state.authPending) {
+                            setText("sh-meta", `Authorization pending. Finish Microsoft sign-in, then click Auth Refresh. [build: ${readConfig("data-build-id", "unknown")}]`);
+                        } else {
+                            setText("sh-meta", `Ready [build: ${readConfig("data-build-id", "unknown")}].`);
+                        }
+
+                        const assistants = await callBackend(handlers.aiAssistants, { purpose: "automation" });
+                        const list = asItems((assistants as { assistants?: unknown }).assistants ?? assistants);
+                        const first = list.find((entry) => typeof entry.id === "string" && entry.id.trim());
+                        state.aiAssistantId = first && typeof first.id === "string" ? first.id : "";
+                    },
+                    setBusy,
+                    setMeta: (value: string) => setText("sh-meta", value),
+                    setOutput: (value: string) => setText("sh-output", value),
+                    async saveContext() {
+                        const response = await callBackend(handlers.saveContext, buildContextPayload());
+                        assertOk(response, "Save context failed.");
+                        setText("sh-meta", "Context saved.");
+                        notifySuccess("Context saved");
+                    },
+                    async authStart() {
+                        const response = await callBackend(handlers.authStart, buildContextPayload());
+                        assertOk(response, "Auth start failed.");
+                        const envelope = response && typeof response === "object" ? response as Record<string, unknown> : {};
+                        const raw = pickAuthSource(envelope);
+                        const pickString = (...values: unknown[]) => {
+                            const candidate = values.find((value) => typeof value === "string" && String(value).trim());
+                            return typeof candidate === "string" ? candidate.trim() : "";
+                        };
+                        const sessionId = pickString(
+                            envelope.sessionId,
+                            envelope.session_id,
+                            envelope.sid,
+                            raw.sessionId,
+                            raw.session_id,
+                            raw.sid,
+                            (raw.session && typeof raw.session === "object" ? (raw.session as Record<string, unknown>).id : undefined),
+                        );
+                        const normalizedAuthorizationUrl = pickString(
+                            envelope.authorizationUrl,
+                            envelope.authUrl,
+                            envelope.loginUrl,
+                            envelope.redirectUrl,
+                            envelope.verificationUri,
+                            envelope.verificationUrl,
+                            envelope.webUrl,
+                            envelope.url,
+                            raw.authorizationUrl,
+                            raw.authorization_url,
+                            raw.authorizeUrl,
+                            raw.authorize_url,
+                            raw.authUrl,
+                            raw.auth_url,
+                            raw.loginUrl,
+                            raw.login_url,
+                            raw.redirectUrl,
+                            raw.redirect_url,
+                            raw.verificationUri,
+                            raw.verification_uri,
+                            raw.verificationUrl,
+                            raw.verification_url,
+                            raw.webUrl,
+                            raw.url,
+                            (raw.auth && typeof raw.auth === "object" ? (raw.auth as Record<string, unknown>).url : undefined),
+                        );
+                        const verificationUrl = pickString(
+                            envelope.verificationUriComplete,
+                            envelope.verificationUri,
+                            envelope.verificationUrl,
+                            raw.verification_uri_complete,
+                            raw.verificationUriComplete,
+                            raw.verification_uri,
+                            raw.verificationUri,
+                            raw.verification_url,
+                            raw.verificationUrl,
+                        );
+                        const userCode = pickString(
+                            envelope.userCode,
+                            raw.user_code,
+                            raw.userCode,
+                        );
+                        const brokerMessage = pickString(
+                            envelope.message,
+                            raw.message,
+                        );
+                        const pending = [
+                            envelope.pending,
+                            envelope.requiresInteraction,
+                            envelope.requiresUserAction,
+                            envelope.interactionRequired,
+                            envelope.needsRedirect,
+                            envelope.redirectRequired,
+                            raw.pending,
+                            raw.requiresInteraction,
+                            raw.requiresUserAction,
+                            raw.interactionRequired,
+                            raw.needsRedirect,
+                            raw.redirectRequired,
+                            raw.state === "pending",
+                            raw.state === "authorization_required",
+                            raw.status === "pending",
+                            raw.status === "authorization_required",
+                        ].some((value) => value === true);
+                        const authHint = typeof envelope.authHint === "string" ? envelope.authHint.trim() : "";
+                        const hasAuthTxnEnvelope = typeof envelope.authTxnId === "string" && envelope.authTxnId.trim().length > 0;
+                        const envelopeRawMissing = hasAuthTxnEnvelope && (!("raw" in envelope) || envelope.raw == null);
+                        const browserUrl = verificationUrl || normalizedAuthorizationUrl;
+                        const shouldRedirect = Boolean(browserUrl);
+                        if (shouldRedirect) {
+                            try {
+                                const parsed = new URL(browserUrl);
+                                if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+                                    throw new Error("Authorization URL must use http or https.");
+                                }
+                            } catch (error) {
+                                throw new Error(`Auth start returned invalid authorization URL: ${error instanceof Error ? error.message : String(error)}`);
+                            }
+                            const openResponse = await callBackend(handlers.openBrowser, { webUrl: browserUrl });
+                            assertOk(openResponse, "Open auth redirect failed.");
+                            renderAuthInstructions({
+                                message: brokerMessage,
+                                verificationUrl,
+                                userCode,
+                            });
+                            state.authPending = true;
+                            state.isAuthenticated = false;
+                            syncAuthUi();
+                            setText("sh-meta", verificationUrl
+                                ? "Microsoft verification page opened. Enter the code shown in the plugin, finish sign-in, then click Auth Refresh."
+                                : "Browser sign-in opened by plugin. Complete sign-in, then click Auth Refresh.");
+                            notifySuccess(verificationUrl ? "Microsoft verification opened" : "Redirect requested");
+                            return;
+                        }
+                        if (pending || envelopeRawMissing) {
+                            renderAuthInstructions({
+                                message: brokerMessage || authHint,
+                                verificationUrl,
+                                userCode,
+                            });
+                            state.authPending = true;
+                            state.isAuthenticated = false;
+                            syncAuthUi();
+                            setText(
+                                "sh-meta",
+                                verificationUrl
+                                    ? "Device auth initialized. Open Microsoft verification, approve access, then click Auth Refresh."
+                                    : (authHint
+                                        ? `Auth flow initialized, but host returned no redirect URL. ${authHint} Then click Auth Refresh.`
+                                        : "Auth flow initialized, but host returned no redirect URL. Complete provider auth externally, then click Auth Refresh.")
+                            );
+                            notifySuccess("Auth flow initialized");
+                            return;
+                        }
+                        if (sessionId && !pending) {
+                            state.authPending = false;
+                            state.isAuthenticated = true;
+                            syncAuthUi();
+                            setText("sh-meta", `Authenticated. Session: ${sessionId}`);
+                            notifySuccess("Authenticated");
+                            return;
+                        }
+                        throw new Error("Auth start did not return a session id or redirect URL.");
+                    },
+                    async nativeMicrosoftLogin() {
+                        await (window as { __serviceHubRuntime?: { authStart?: () => Promise<void> } }).__serviceHubRuntime?.authStart?.();
+                    },
+                    async authRefresh() {
+                        const response = await callBackend(handlers.authRefresh, buildContextPayload());
+                        assertOk(response, "Auth refresh failed.");
+                        const envelope = response && typeof response === "object" ? response as Record<string, unknown> : {};
+                        const pending = envelope.pending === true;
+                        const userCode = typeof envelope.userCode === "string" ? envelope.userCode.trim() : "";
+                        const verificationUrl = typeof envelope.verificationUri === "string"
+                            ? envelope.verificationUri.trim()
+                            : (typeof envelope.verificationUriComplete === "string" ? envelope.verificationUriComplete.trim() : "");
+                        const message = typeof envelope.message === "string" ? envelope.message.trim() : "";
+                        if (pending) {
+                            state.authPending = true;
+                            state.isAuthenticated = false;
+                            syncAuthUi();
+                            renderAuthInstructions({ message, verificationUrl, userCode });
+                            setText("sh-meta", "Authorization is still pending. Finish Microsoft sign-in, then click Auth Refresh again.");
+                            notifySuccess("Authorization pending");
+                            return;
+                        }
+                        const sessionId = typeof envelope.sessionId === "string" ? envelope.sessionId.trim() : "";
+                        state.authPending = false;
+                        state.isAuthenticated = true;
+                        syncAuthUi();
+                        setText("sh-meta", sessionId ? `Authenticated. Session: ${sessionId}` : "Authenticated.");
+                        notifySuccess("Authenticated");
+                    },
+                    async authLogout() {
+                        const response = await callBackend(handlers.authLogout, buildContextPayload());
+                        assertOk(response, "Auth logout failed.");
+                        state.authPending = false;
+                        state.isAuthenticated = false;
+                        syncAuthUi();
+                        setText("sh-meta", "Session closed.");
+                        notifySuccess("Session closed");
+                    },
+                    async listWorkspaces() {
+                        state.activeOperation = "listWorkspaces";
+                        const response = await callBackend(handlers.listWorkspaces, {
+                            ...buildContextPayload(),
+                            query: readInput("sh-search-query") || undefined,
+                            cursor: currentCursor() || undefined,
+                        });
+                        assertOk(response, "List workspaces failed.");
+                        const items = asItems(response);
+                        state.lastResults = items;
+                        state.nextCursor = readResponseCursor(response);
+                        setCursor(state.nextCursor);
+                        setSelectionOptions(items);
+                        setText("sh-output", renderRows(items));
+                        setText("sh-meta", `Listed ${items.length} workspaces.${state.nextCursor ? " Next page cursor available." : ""}`);
+                        notifySuccess(`Listed ${items.length} workspaces`);
+                    },
+                    async listItems() {
+                        state.activeOperation = "listItems";
+                        const response = await callBackend(handlers.listItems, {
+                            ...buildContextPayload(),
+                            cursor: currentCursor() || undefined,
+                        });
+                        assertOk(response, "List items failed.");
+                        const items = asItems(response);
+                        state.lastResults = items;
+                        state.nextCursor = readResponseCursor(response);
+                        setCursor(state.nextCursor);
+                        setSelectionOptions(items);
+                        setText("sh-output", renderRows(items));
+                        setText("sh-meta", `Listed ${items.length} items.${state.nextCursor ? " Next page cursor available." : ""}`);
+                        notifySuccess(`Listed ${items.length} items`);
+                    },
+                    async searchItems() {
+                        state.activeOperation = "searchItems";
+                        const response = await callBackend(handlers.searchItems, {
+                            ...buildContextPayload(),
+                            query: readInput("sh-search-query"),
+                            cursor: currentCursor() || undefined,
+                        });
+                        assertOk(response, "Search failed.");
+                        const items = asItems(response);
+                        state.lastResults = items;
+                        state.nextCursor = readResponseCursor(response);
+                        setCursor(state.nextCursor);
+                        setSelectionOptions(items);
+                        setText("sh-output", renderRows(items));
+                        setText("sh-meta", `Search returned ${items.length} item(s).${state.nextCursor ? " Next page cursor available." : ""}`);
+                        notifySuccess(`Search returned ${items.length} item(s)`);
+                    },
+                    async nextPage() {
+                        if (!state.nextCursor) {
+                            throw new Error("No next cursor available.");
+                        }
+                        setCursor(state.nextCursor);
+                        await (window as { __serviceHubRuntime?: { [key: string]: () => Promise<void> } }).__serviceHubRuntime?.[state.activeOperation]?.();
+                    },
+                    async createShareLink() {
+                        const selected = getSelectedItem();
+                        const itemId = selected && typeof selected.id === "string" ? selected.id : "";
+                        if (!itemId) throw new Error("No result selected. Run list/search first.");
+                        const response = await callBackend(handlers.createShareLink, {
+                            ...buildContextPayload(),
+                            itemId,
+                            scope: "organization",
+                            type: "view",
+                        });
+                        assertOk(response, "Create share link failed.");
+                        const link = response && typeof response === "object" && typeof (response as { webUrl?: unknown }).webUrl === "string"
+                            ? String((response as { webUrl: string }).webUrl).trim()
+                            : "";
+                        if (!link) throw new Error("Host returned empty share link.");
+                        state.lastShareLink = link;
+                        setText("sh-output", `${link}\n\n${String(byId("sh-output")?.textContent || "")}`);
+                        setText("sh-meta", "Share link created.");
+                        notifySuccess("Share link created");
+                    },
+                    async openInBrowser() {
+                        const selected = getSelectedItem();
+                        const webUrl = selected && typeof selected.webUrl === "string" ? selected.webUrl.trim() : "";
+                        if (!webUrl) {
+                            throw new Error("Selected result does not have a web URL.");
+                        }
+                        const response = await callBackend(handlers.openBrowser, { webUrl });
+                        assertOk(response, "Open in browser failed.");
+                        setText("sh-meta", "Browser open request sent to host.");
+                        notifySuccess("Open in browser requested");
+                    },
+                    async copyShareLink() {
+                        if (!state.lastShareLink) throw new Error("No share link available yet.");
+                        const requestPayload = await callBackend(handlers.copyLink, { text: state.lastShareLink });
+                        const response = await window.createBackendReq("requestPrivilegedAction", requestPayload);
+                        if (!response || typeof response !== "object" || (response as { ok?: unknown }).ok !== true) {
+                            throw new Error(String((response as { error?: unknown }).error || "Clipboard write failed."));
+                        }
+                        setText("sh-meta", "Share link copied to clipboard.");
+                        notifySuccess("Share link copied");
+                    },
+                    async addFavorite() {
+                        const selected = getSelectedItem();
+                        if (!selected) throw new Error("No result available to pin.");
+                        const response = await callBackend(handlers.addFavorite, { item: selected });
+                        assertOk(response, "Add favorite failed.");
+                        renderListCard("sh-favorites", asItems((response as { favorites?: unknown }).favorites), "No favorites yet.");
+                        setText("sh-meta", "Favorite added.");
+                        notifySuccess("Favorite added");
+                    },
+                    async summarizeWithAI() {
+                        const response = await callBackend(handlers.aiAssist, {
+                            task: "summarize-content-results",
+                            assistantPurpose: "automation",
+                            assistantId: state.aiAssistantId || undefined,
+                            prompt: "Summarize connector results for operator actionability.",
+                            summary: { count: state.lastResults.length },
+                            context: { results: state.lastResults.slice(0, 20) },
+                        });
+                        assertOk(response, "AI summarize failed.");
+                        const message = response && typeof response === "object"
+                            ? (typeof (response as { message?: unknown }).message === "string"
+                                ? String((response as { message: string }).message).trim()
+                                : "")
+                            : "";
+                        if (!message) throw new Error("AI response was empty.");
+                        setText("sh-output", `${message}\n\n---\n${String(byId("sh-output")?.textContent || "")}`);
+                        setText("sh-meta", "AI summary generated.");
+                        notifySuccess("AI summary generated");
+                    },
+                };
+                (window as {
+                    __serviceHubRunAction?: (action: string) => Promise<void>;
+                    __serviceHubRuntime?: Record<string, (...args: unknown[]) => Promise<void>> & {
+                        setBusy?: (value: boolean) => void;
+                        setMeta?: (value: string) => void;
+                    };
+                    Notyf?: new (options?: unknown) => { error: (value: string) => void };
+                }).__serviceHubRunAction = async (action: string) => {
+                    const runtime = (window as {
+                        __serviceHubRuntime?: Record<string, (...args: unknown[]) => Promise<void>> & {
+                            setBusy?: (value: boolean) => void;
+                            setMeta?: (value: string) => void;
+                        };
+                    }).__serviceHubRuntime;
+                    if (!runtime || typeof runtime[action] !== "function") {
+                        return;
+                    }
+                    runtime.setBusy?.(true);
+                    try {
+                        await runtime[action]();
+                    } catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        runtime.setMeta?.(`${action} failed: ${message}`);
+                        const runtimeWindow = window as {
+                            Notyf?: new (options?: unknown) => { error: (value: string) => void };
+                        };
+                        if (typeof runtimeWindow.Notyf === "function") {
+                            new runtimeWindow.Notyf({ duration: 3000, position: { x: "right", y: "top" } }).error(message);
+                        }
+                    } finally {
+                        runtime.setBusy?.(false);
+                    }
+                };
+
+                void (async () => {
+                    const runtime = (window as { __serviceHubRuntime?: { prepare?: () => Promise<void> } }).__serviceHubRuntime;
+                    if (runtime?.prepare) {
+                        await runtime.prepare();
+                    }
+                })().catch((error) => {
+                    setText("sh-meta", `Runtime prepare failed: ${error instanceof Error ? error.message : String(error)}`);
+                });
+            },
+            handlers: {
+                saveContext: async () => (window as { __serviceHubRunAction?: (action: string) => Promise<void> }).__serviceHubRunAction?.("saveContext"),
+                authStart: async () => (window as { __serviceHubRunAction?: (action: string) => Promise<void> }).__serviceHubRunAction?.("authStart"),
+                nativeMicrosoftLogin: async () => (window as { __serviceHubRunAction?: (action: string) => Promise<void> }).__serviceHubRunAction?.("nativeMicrosoftLogin"),
+                authRefresh: async () => (window as { __serviceHubRunAction?: (action: string) => Promise<void> }).__serviceHubRunAction?.("authRefresh"),
+                authLogout: async () => (window as { __serviceHubRunAction?: (action: string) => Promise<void> }).__serviceHubRunAction?.("authLogout"),
+                listWorkspaces: async () => (window as { __serviceHubRunAction?: (action: string) => Promise<void> }).__serviceHubRunAction?.("listWorkspaces"),
+                listItems: async () => (window as { __serviceHubRunAction?: (action: string) => Promise<void> }).__serviceHubRunAction?.("listItems"),
+                nextPage: async () => (window as { __serviceHubRunAction?: (action: string) => Promise<void> }).__serviceHubRunAction?.("nextPage"),
+                searchItems: async () => (window as { __serviceHubRunAction?: (action: string) => Promise<void> }).__serviceHubRunAction?.("searchItems"),
+                createShareLink: async () => (window as { __serviceHubRunAction?: (action: string) => Promise<void> }).__serviceHubRunAction?.("createShareLink"),
+                openInBrowser: async () => (window as { __serviceHubRunAction?: (action: string) => Promise<void> }).__serviceHubRunAction?.("openInBrowser"),
+                copyShareLink: async () => (window as { __serviceHubRunAction?: (action: string) => Promise<void> }).__serviceHubRunAction?.("copyShareLink"),
+                addFavorite: async () => (window as { __serviceHubRunAction?: (action: string) => Promise<void> }).__serviceHubRunAction?.("addFavorite"),
+                summarizeWithAI: async () => (window as { __serviceHubRunAction?: (action: string) => Promise<void> }).__serviceHubRunAction?.("summarizeWithAI"),
+                searchOnEnter: async ({ event }: { event: unknown }) => {
+                    const keyEvent = event as KeyboardEvent;
+                    if (!keyEvent || typeof keyEvent.key !== "string" || keyEvent.key !== "Enter") {
+                        return;
+                    }
+                    keyEvent.preventDefault();
+                    await (window as { __serviceHubRunAction?: (action: string) => Promise<void> }).__serviceHubRunAction?.("searchItems");
+                },
+            },
+            bindings: [
+                { selector: "#sh-save-context", event: "click", handler: "saveContext", required: true, preventDefault: true },
+                { selector: "#sh-ms-login", event: "click", handler: "nativeMicrosoftLogin", required: true, preventDefault: true },
+                { selector: "#sh-auth-refresh", event: "click", handler: "authRefresh", required: true, preventDefault: true },
+                { selector: "#sh-auth-logout", event: "click", handler: "authLogout", required: true, preventDefault: true },
+                { selector: "#sh-list-workspaces", event: "click", handler: "listWorkspaces", required: true, preventDefault: true },
+                { selector: "#sh-list-items", event: "click", handler: "listItems", required: true, preventDefault: true },
+                { selector: "#sh-next-page", event: "click", handler: "nextPage", required: true, preventDefault: true },
+                { selector: "#sh-search-items", event: "click", handler: "searchItems", required: true, preventDefault: true },
+                { selector: "#sh-create-share-link", event: "click", handler: "createShareLink", required: true, preventDefault: true },
+                { selector: "#sh-open-browser", event: "click", handler: "openInBrowser", required: true, preventDefault: true },
+                { selector: "#sh-copy-share-link", event: "click", handler: "copyShareLink", required: true, preventDefault: true },
+                { selector: "#sh-add-favorite", event: "click", handler: "addFavorite", required: true, preventDefault: true },
+                { selector: "#sh-ai-summarize", event: "click", handler: "summarizeWithAI", required: true, preventDefault: true },
+                { selector: "#sh-search-query", event: "keydown", handler: "searchOnEnter" },
+            ],
+            strict: true,
+            language: "typescript",
+            description: "Declarative runtime wiring for generic auth/content broker interactions.",
+        });
+    }
+
+    private ensurePersistentStore(): void {
+        if (this.persistentStore) {
+            return;
+        }
+        try {
+            this.persistentStore = PluginRegistry.useStore("json");
+            this.jsonStoreAvailable = true;
+        } catch {
+            this.jsonStoreAvailable = false;
+        }
+    }
+
+    private getFallbackStore(): StoreType {
+        if (!this.sessionStore) {
+            this.sessionStore = PluginRegistry.useStore("default");
+        }
+        return this.sessionStore;
+    }
+
+    private readState<T>(key: string, fallback: T): T {
+        this.ensurePersistentStore();
+        const store = this.persistentStore ?? this.getFallbackStore();
+        const value = store.get(key) as T | undefined;
+        return value === undefined ? fallback : value;
+    }
+
+    private writeState<T>(key: string, value: T): "persistent-json" | "session-fallback" {
+        this.ensurePersistentStore();
+        const store = this.persistentStore ?? this.getFallbackStore();
+        store.set(key, value);
+        return this.persistentStore ? "persistent-json" : "session-fallback";
+    }
+
+    private getGrantedCapabilities(): PluginCapability[] {
+        try {
+            const diagnostics = PluginRegistry.getDiagnostics({ notificationsLimit: 0 });
+            const granted = diagnostics?.capabilities?.permissions?.granted;
+            return Array.isArray(granted) ? granted as PluginCapability[] : [];
+        } catch {
+            return [];
+        }
+    }
+
+    private requireConnectorNetwork(action: string): void {
+        requireCapability("system.network", action);
+        requireCapability("system.network.https", action);
+        requireNetworkScopeCapability(ServiceContentHubPlugin.NETWORK_SCOPE_ID, action);
+    }
+
+    private normalizeContext(input: unknown): ServiceContext {
+        const payload = typeof input === "object" && input !== null ? input as Record<string, unknown> : {};
+        const persisted = this.readState<ServiceContext>(ServiceContentHubPlugin.STORAGE_KEYS.CONTEXT, DEFAULT_CONTEXT);
+        const authConfig = payload.authConfig && typeof payload.authConfig === "object"
+            ? payload.authConfig as Record<string, unknown>
+            : {};
+        const providerId = typeof payload.providerId === "string" && payload.providerId.trim()
+            ? payload.providerId.trim()
+            : (persisted.providerId || "sharepoint");
+        const endpointUrlRaw = typeof payload.endpointUrl === "string"
+            ? payload.endpointUrl.trim()
+            : (persisted.endpointUrl || "");
+        const authTenantId = (
+            typeof authConfig.tenantId === "string" && authConfig.tenantId.trim()
+                ? authConfig.tenantId.trim()
+                : (typeof payload.authTenantId === "string" && payload.authTenantId.trim()
+                    ? payload.authTenantId.trim()
+                    : (persisted.authTenantId || ""))
+        ) || ServiceContentHubPlugin.DEFAULT_AUTH_TENANT;
+        const authScopes = (
+            typeof authConfig.scopes === "string" && authConfig.scopes.trim()
+                ? authConfig.scopes.trim()
+                : (typeof payload.authScopes === "string" && payload.authScopes.trim()
+                    ? payload.authScopes.trim()
+                    : (persisted.authScopes || ""))
+        ) || ServiceContentHubPlugin.DEFAULT_AUTH_SCOPES;
+        return {
+            providerId,
+            accountId: typeof payload.accountId === "string"
+                ? payload.accountId.trim()
+                : (persisted.accountId || ""),
+            sessionId: typeof payload.sessionId === "string"
+                ? payload.sessionId.trim()
+                : (persisted.sessionId || ""),
+            endpointUrl: endpointUrlRaw || this.getDefaultEndpointUrl(providerId),
+            workspaceId: typeof payload.workspaceId === "string"
+                ? payload.workspaceId.trim()
+                : (persisted.workspaceId || ""),
+            path: typeof payload.path === "string" && payload.path.trim()
+                ? payload.path.trim()
+                : (persisted.path || "/"),
+            authClientId: typeof authConfig.clientId === "string"
+                ? authConfig.clientId.trim()
+                : (typeof payload.authClientId === "string"
+                    ? payload.authClientId.trim()
+                    : (persisted.authClientId || "")),
+            authTenantId,
+            authRedirectUri: typeof authConfig.redirectUri === "string"
+                ? authConfig.redirectUri.trim()
+                : (typeof payload.authRedirectUri === "string"
+                    ? payload.authRedirectUri.trim()
+                    : (persisted.authRedirectUri || "")),
+            authScopes,
+            authDeviceCode: typeof payload.authDeviceCode === "string"
+                ? payload.authDeviceCode.trim()
+                : (persisted.authDeviceCode || ""),
+            authVerificationUri: typeof payload.authVerificationUri === "string"
+                ? payload.authVerificationUri.trim()
+                : (persisted.authVerificationUri || ""),
+            authVerificationUriComplete: typeof payload.authVerificationUriComplete === "string"
+                ? payload.authVerificationUriComplete.trim()
+                : (persisted.authVerificationUriComplete || ""),
+            authUserCode: typeof payload.authUserCode === "string"
+                ? payload.authUserCode.trim()
+                : (persisted.authUserCode || ""),
+            authPollIntervalSeconds: Number.isFinite(Number(payload.authPollIntervalSeconds))
+                ? Number(payload.authPollIntervalSeconds)
+                : (Number.isFinite(Number(persisted.authPollIntervalSeconds)) ? Number(persisted.authPollIntervalSeconds) : 5),
+            authCodeExpiresAt: typeof payload.authCodeExpiresAt === "string"
+                ? payload.authCodeExpiresAt.trim()
+                : (persisted.authCodeExpiresAt || ""),
+        };
+    }
+
+    private getDefaultEndpointUrl(providerIdRaw: string): string {
+        const providerId = providerIdRaw.trim().toLowerCase();
+        return ServiceContentHubPlugin.PROVIDER_ENDPOINT_DEFAULTS[providerId] || "";
+    }
+
+    private normalizeItems(input: unknown): ContentItem[] {
+        const source: unknown[] = Array.isArray(input)
+            ? input
+            : (
+                Array.isArray((input as { items?: unknown[] })?.items)
+                    ? (input as { items: unknown[] }).items
+                    : (Array.isArray((input as { value?: unknown[] })?.value) ? (input as { value: unknown[] }).value : [])
+            );
+        return source
+            .map((candidate): ContentItem | null => {
+                if (!candidate || typeof candidate !== "object") return null;
+                const record = candidate as Record<string, unknown>;
+                const id = typeof record.id === "string" ? record.id.trim() : "";
+                const name = typeof record.name === "string"
+                    ? record.name.trim()
+                    : (typeof record.displayName === "string" ? String(record.displayName).trim() : "");
+                if (!id || !name) return null;
+                const kind = typeof record.kind === "string" ? record.kind.trim().toLowerCase() : "file";
+                return {
+                    id,
+                    name,
+                    kind: kind === "site" || kind === "workspace" || kind === "folder" || kind === "file" ? kind : "file",
+                    webUrl: typeof record.webUrl === "string" ? record.webUrl.trim() : "",
+                    parentPath: typeof record.parentPath === "string" ? record.parentPath.trim() : undefined,
+                    lastModifiedAt: typeof record.lastModifiedAt === "string" ? record.lastModifiedAt.trim() : undefined,
+                };
+            })
+            .filter((item): item is ContentItem => Boolean(item))
+            .slice(0, 500);
+    }
+
+    private normalizeCursor(input: unknown): string {
+        if (typeof (input as { cursor?: unknown })?.cursor === "string") {
+            return String((input as { cursor: string }).cursor).trim();
+        }
+        return "";
+    }
+
+    private readResponseCursor(input: unknown): string {
+        if (!input || typeof input !== "object") {
+            return "";
+        }
+        if (typeof (input as { ["@odata.nextLink"]?: unknown })["@odata.nextLink"] === "string") {
+            return String((input as { ["@odata.nextLink"]: string })["@odata.nextLink"]).trim();
+        }
+        if (typeof (input as { nextCursor?: unknown }).nextCursor === "string") {
+            return String((input as { nextCursor: string }).nextCursor).trim();
+        }
+        const page = (input as { page?: { nextCursor?: unknown } }).page;
+        if (page && typeof page.nextCursor === "string") {
+            return page.nextCursor.trim();
+        }
+        return "";
+    }
+
+    private getCorrelationId(prefix: string): string {
+        return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    }
+
+    private buildSharePointDeviceCodeStartRequest(context: ServiceContext): {
+        url: string;
+        method: string;
+        headers: Record<string, string>;
+        body: string;
+    } | null {
+        if (context.providerId.trim().toLowerCase() !== "sharepoint" || !context.authClientId) {
+            return null;
+        }
+        const tenantId = context.authTenantId || ServiceContentHubPlugin.DEFAULT_AUTH_TENANT;
+        const body = new URLSearchParams();
+        body.set("client_id", context.authClientId);
+        body.set("scope", context.authScopes || ServiceContentHubPlugin.DEFAULT_AUTH_SCOPES);
+        return {
+            url: `https://login.microsoftonline.com/${encodeURIComponent(tenantId)}/oauth2/v2.0/devicecode`,
+            method: "POST",
+            headers: {
+                "content-type": "application/x-www-form-urlencoded",
+            },
+            body: body.toString(),
+        };
+    }
+
+    private buildSharePointDeviceCodeRefreshRequest(context: ServiceContext): {
+        url: string;
+        method: string;
+        headers: Record<string, string>;
+        body: string;
+    } | null {
+        if (context.providerId.trim().toLowerCase() !== "sharepoint" || !context.authClientId || !context.authDeviceCode) {
+            return null;
+        }
+        const tenantId = context.authTenantId || ServiceContentHubPlugin.DEFAULT_AUTH_TENANT;
+        const body = new URLSearchParams();
+        body.set("grant_type", "urn:ietf:params:oauth:grant-type:device_code");
+        body.set("client_id", context.authClientId);
+        body.set("device_code", context.authDeviceCode);
+        return {
+            url: `https://login.microsoftonline.com/${encodeURIComponent(tenantId)}/oauth2/v2.0/token`,
+            method: "POST",
+            headers: {
+                "content-type": "application/x-www-form-urlencoded",
+            },
+            body: body.toString(),
+        };
+    }
+
+    private readDeviceCodeDetails(result: unknown): {
+        verificationUri: string;
+        verificationUriComplete: string;
+        userCode: string;
+        deviceCode: string;
+        message: string;
+        intervalSeconds: number;
+        expiresInSeconds: number;
+    } {
+        const record = result && typeof result === "object" ? result as Record<string, unknown> : {};
+        const raw = record.raw && typeof record.raw === "object" ? record.raw as Record<string, unknown> : {};
+        const pickString = (...values: unknown[]) => {
+            const candidate = values.find((value) => typeof value === "string" && String(value).trim());
+            return typeof candidate === "string" ? candidate.trim() : "";
+        };
+        const pickNumber = (...values: unknown[]) => {
+            const candidate = values.find((value) => Number.isFinite(Number(value)));
+            return candidate === undefined ? 0 : Number(candidate);
+        };
+        return {
+            verificationUri: pickString(record.verificationUri, raw.verification_uri, raw.verificationUri, raw.verification_url, raw.verificationUrl),
+            verificationUriComplete: pickString(record.verificationUriComplete, raw.verification_uri_complete, raw.verificationUriComplete),
+            userCode: pickString(record.userCode, raw.user_code, raw.userCode),
+            deviceCode: pickString(record.deviceCode, raw.device_code, raw.deviceCode),
+            message: pickString(record.message, raw.message),
+            intervalSeconds: pickNumber(record.intervalSeconds, raw.interval, raw.intervalSeconds) || 5,
+            expiresInSeconds: pickNumber(record.expiresInSeconds, raw.expires_in, raw.expiresIn),
+        };
+    }
+
+    private readExplicitSessionCredentials(result: unknown): null | {
+        auth: {
+            scheme: "bearer";
+            value: string;
+        };
+        credentials: {
+            accessToken: string;
+            refreshToken?: string;
+            idToken?: string;
+            tokenType: string;
+            scope?: string;
+            expiresAt?: string;
+        };
+    } {
+        const record = result && typeof result === "object" ? result as Record<string, unknown> : {};
+        const raw = record.raw && typeof record.raw === "object" ? record.raw as Record<string, unknown> : {};
+        const accessToken = typeof raw.access_token === "string" && raw.access_token.trim()
+            ? raw.access_token.trim()
+            : (typeof raw.accessToken === "string" && raw.accessToken.trim() ? raw.accessToken.trim() : "");
+        if (!accessToken) {
+            return null;
+        }
+        const refreshToken = typeof raw.refresh_token === "string" && raw.refresh_token.trim()
+            ? raw.refresh_token.trim()
+            : (typeof raw.refreshToken === "string" && raw.refreshToken.trim() ? raw.refreshToken.trim() : "");
+        const idToken = typeof raw.id_token === "string" && raw.id_token.trim()
+            ? raw.id_token.trim()
+            : (typeof raw.idToken === "string" && raw.idToken.trim() ? raw.idToken.trim() : "");
+        const tokenType = typeof raw.token_type === "string" && raw.token_type.trim()
+            ? raw.token_type.trim()
+            : (typeof raw.tokenType === "string" && raw.tokenType.trim() ? raw.tokenType.trim() : "Bearer");
+        const scope = typeof raw.scope === "string" && raw.scope.trim() ? raw.scope.trim() : "";
+        const expiresInCandidate = Number(
+            typeof raw.expires_in === "number" || typeof raw.expires_in === "string"
+                ? raw.expires_in
+                : raw.expiresIn
+        );
+        const expiresAt = Number.isFinite(expiresInCandidate) && expiresInCandidate > 0
+            ? new Date(Date.now() + expiresInCandidate * 1000).toISOString()
+            : "";
+        return {
+            auth: {
+                scheme: "bearer",
+                value: accessToken,
+            },
+            credentials: {
+                accessToken,
+                refreshToken: refreshToken || undefined,
+                idToken: idToken || undefined,
+                tokenType: tokenType || "Bearer",
+                scope: scope || undefined,
+                expiresAt: expiresAt || undefined,
+            },
+        };
+    }
+
+    private readAuthSessionId(result: unknown): string {
+        if (!result || typeof result !== "object") {
+            return "";
+        }
+        const record = result as Record<string, unknown>;
+        const direct = [
+            record.sessionId,
+            record.session_id,
+            record.sid,
+        ].find((candidate) => typeof candidate === "string" && String(candidate).trim());
+        if (typeof direct === "string") {
+            return direct.trim();
+        }
+        const raw = record.raw;
+        if (raw && typeof raw === "object") {
+            const nestedDirect = [
+                (raw as Record<string, unknown>).sessionId,
+                (raw as Record<string, unknown>).session_id,
+                (raw as Record<string, unknown>).sid,
+            ].find((candidate) => typeof candidate === "string" && String(candidate).trim());
+            if (typeof nestedDirect === "string") {
+                return nestedDirect.trim();
+            }
+        }
+        const nested = record.session;
+        if (nested && typeof nested === "object" && typeof (nested as { id?: unknown }).id === "string") {
+            return String((nested as { id: string }).id).trim();
+        }
+        if (raw && typeof raw === "object") {
+            const nestedRaw = (raw as Record<string, unknown>).session;
+            if (nestedRaw && typeof nestedRaw === "object" && typeof (nestedRaw as { id?: unknown }).id === "string") {
+                return String((nestedRaw as { id: string }).id).trim();
+            }
+        }
+        return "";
+    }
+
+    private readAuthRedirectUrl(result: unknown): string {
+        if (!result || typeof result !== "object") {
+            return "";
+        }
+        const record = result as Record<string, unknown>;
+        const direct = [
+            record.authorizationUrl,
+            record.authorization_url,
+            record.authorizeUrl,
+            record.authorize_url,
+            record.authUrl,
+            record.auth_url,
+            record.loginUrl,
+            record.login_url,
+            record.redirectUrl,
+            record.redirect_url,
+            record.verificationUri,
+            record.verification_uri,
+            record.verificationUrl,
+            record.verification_url,
+            record.webUrl,
+            record.url,
+        ].find((candidate) => typeof candidate === "string" && String(candidate).trim());
+        if (typeof direct === "string") {
+            return direct.trim();
+        }
+        const raw = record.raw;
+        if (raw && typeof raw === "object") {
+            const rawRecord = raw as Record<string, unknown>;
+            const nestedDirect = [
+                rawRecord.authorizationUrl,
+                rawRecord.authorization_url,
+                rawRecord.authorizeUrl,
+                rawRecord.authorize_url,
+                rawRecord.authUrl,
+                rawRecord.auth_url,
+                rawRecord.loginUrl,
+                rawRecord.login_url,
+                rawRecord.redirectUrl,
+                rawRecord.redirect_url,
+                rawRecord.verificationUri,
+                rawRecord.verification_uri,
+                rawRecord.verificationUrl,
+                rawRecord.verification_url,
+                rawRecord.webUrl,
+                rawRecord.url,
+            ].find((candidate) => typeof candidate === "string" && String(candidate).trim());
+            if (typeof nestedDirect === "string") {
+                return nestedDirect.trim();
+            }
+        }
+        const authBlock = record.auth;
+        if (authBlock && typeof authBlock === "object") {
+            const nested = [
+                (authBlock as Record<string, unknown>).authorizationUrl,
+                (authBlock as Record<string, unknown>).authorizeUrl,
+                (authBlock as Record<string, unknown>).authUrl,
+                (authBlock as Record<string, unknown>).loginUrl,
+                (authBlock as Record<string, unknown>).redirectUrl,
+                (authBlock as Record<string, unknown>).url,
+            ].find((candidate) => typeof candidate === "string" && String(candidate).trim());
+            if (typeof nested === "string") {
+                return nested.trim();
+            }
+        }
+        if (raw && typeof raw === "object") {
+            const rawAuthBlock = (raw as Record<string, unknown>).auth;
+            if (rawAuthBlock && typeof rawAuthBlock === "object") {
+                const nestedRaw = [
+                    (rawAuthBlock as Record<string, unknown>).authorizationUrl,
+                    (rawAuthBlock as Record<string, unknown>).authorizeUrl,
+                    (rawAuthBlock as Record<string, unknown>).authUrl,
+                    (rawAuthBlock as Record<string, unknown>).loginUrl,
+                    (rawAuthBlock as Record<string, unknown>).redirectUrl,
+                    (rawAuthBlock as Record<string, unknown>).url,
+                ].find((candidate) => typeof candidate === "string" && String(candidate).trim());
+                if (typeof nestedRaw === "string") {
+                    return nestedRaw.trim();
+                }
+            }
+        }
+        return "";
+    }
+
+    private validateEndpointUrl(endpointUrl: string): { ok: true } | { ok: false; code: string; error: string } {
+        if (!endpointUrl) {
+            return { ok: true };
+        }
+        try {
+            const parsed = new URL(endpointUrl);
+            if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+                return { ok: false, code: "ENDPOINT_URL_INVALID", error: "Endpoint URL must use http or https." };
+            }
+            return { ok: true };
+        } catch {
+            return { ok: false, code: "ENDPOINT_URL_INVALID", error: "Endpoint URL must be a valid absolute URL." };
+        }
+    }
+
+    private classifyBrokerError(error: unknown, fallbackCode: string): { code: string; message: string } {
+        const message = error instanceof Error ? error.message : String(error || "");
+        const normalized = message.toLowerCase();
+        if (/token.*expired|session.*expired|invalid.*token/.test(normalized)) {
+            return { code: "AUTH_TOKEN_EXPIRED", message };
+        }
+        if (/consent|scope|permission.*denied|forbidden|403/.test(normalized)) {
+            return { code: "AUTH_SCOPE_DENIED", message };
+        }
+        if (/auth.*required|401|unauthorized|login required/.test(normalized)) {
+            return { code: "AUTH_REQUIRED", message };
+        }
+        if (/throttl|429|temporar|timeout|econnreset|503|502|504|500/.test(normalized)) {
+            return { code: "PROVIDER_TRANSIENT", message };
+        }
+        return { code: fallbackCode, message };
+    }
+
+    private augmentSharePointAuthStartError(context: ServiceContext, message: string): string {
+        const normalized = String(message || "").toLowerCase();
+        if (!/auth_upstream_http_400|status 400|invalid_scope|unauthorized_client|invalid_request/.test(normalized)) {
+            return message;
+        }
+        const hints: string[] = [];
+        if (!context.authClientId) {
+            hints.push('set "SharePoint App (client) ID"');
+        }
+        if (!context.authTenantId || context.authTenantId === "common" || context.authTenantId === "organizations") {
+            hints.push('use your real tenant ID or tenant domain instead of "common"/"organizations" for a single-tenant app');
+        }
+        hints.push("enable Public client/native access in the Microsoft app registration");
+        hints.push("add delegated Microsoft Graph permissions User.Read, Files.Read.All, and Sites.Read.All");
+        return `${message} SharePoint device-code checklist: ${hints.join("; ")}.`;
+    }
+
+    private shouldRetryBrokerError(error: unknown): boolean {
+        const { code } = this.classifyBrokerError(error, "UNKNOWN");
+        return code === "PROVIDER_TRANSIENT";
+    }
+
+    private resolveAuthBroker(): AuthBroker | null {
+        const globalRecord = globalThis as {
+            __FDO_AUTH_BROKER?: unknown;
+            __FDO_CONNECTOR_AUTH?: unknown;
+        };
+        const broker = globalRecord.__FDO_AUTH_BROKER ?? globalRecord.__FDO_CONNECTOR_AUTH;
+        return broker && typeof broker === "object" ? broker as AuthBroker : null;
+    }
+
+    private resolveContentBroker(): ContentBroker | null {
+        const globalRecord = globalThis as {
+            __FDO_CONTENT_BROKER?: unknown;
+            __FDO_CONNECTOR_CONTENT?: unknown;
+            __FDO_SHAREPOINT_PROVIDER?: unknown;
+            __FDO_SHAREPOINT?: unknown;
+        };
+        const broker = globalRecord.__FDO_CONTENT_BROKER
+            ?? globalRecord.__FDO_CONNECTOR_CONTENT
+            ?? globalRecord.__FDO_SHAREPOINT_PROVIDER
+            ?? globalRecord.__FDO_SHAREPOINT;
+        return broker && typeof broker === "object" ? broker as ContentBroker : null;
+    }
+
+    private resolveOpenUrlBroker(): OpenUrlBroker | null {
+        const globalRecord = globalThis as {
+            __FDO_BROWSER_BROKER?: unknown;
+            __FDO_OPEN_EXTERNAL?: unknown;
+        };
+        const broker = globalRecord.__FDO_BROWSER_BROKER ?? globalRecord.__FDO_OPEN_EXTERNAL;
+        return broker && typeof broker === "object" ? broker as OpenUrlBroker : null;
+    }
+
+    private resolveSessionRequestBroker(): SessionRequestBroker | null {
+        const globalRecord = globalThis as {
+            __FDO_SESSION_REQUEST?: unknown;
+        };
+        const broker = globalRecord.__FDO_SESSION_REQUEST;
+        return broker && typeof broker === "object" ? broker as SessionRequestBroker : null;
+    }
+
+    private async callBroker<TInput extends Record<string, unknown>>(broker: unknown, methodName: string, input: TInput): Promise<unknown> {
+        const method = broker && typeof broker === "object" ? (broker as Record<string, unknown>)[methodName] : undefined;
+        if (typeof method !== "function") {
+            throw new Error(`Host broker method "${methodName}" is not available.`);
+        }
+        const result = (method as (payload: TInput) => unknown)(input);
+        if (result && typeof (result as Promise<unknown>).then === "function") {
+            return result as Promise<unknown>;
+        }
+        return result;
+    }
+
+    private async callBrokerWithRetry<TInput extends Record<string, unknown>>(
+        broker: unknown,
+        methodName: string,
+        input: TInput,
+        retries = 2
+    ): Promise<unknown> {
+        for (let attempt = 0; attempt <= retries; attempt += 1) {
+            try {
+                return await this.callBroker(broker, methodName, input);
+            } catch (error) {
+                if (attempt >= retries || !this.shouldRetryBrokerError(error)) {
+                    throw error;
+                }
+                await new Promise((resolve) => setTimeout(resolve, 200 * (attempt + 1)));
+            }
+        }
+        return null;
+    }
+
+    private async callContentOperation(
+        broker: ContentBroker | null,
+        operation: "list-workspaces" | "list-items" | "search-items" | "create-share-link",
+        input: {
+            providerId: string;
+            sessionId: string;
+            endpointUrl?: string;
+            workspaceId?: string;
+            path?: string;
+            query?: string;
+            itemId?: string;
+            scope?: "organization" | "anonymous";
+            type?: "view" | "edit";
+            limit?: number;
+            cursor?: string;
+        }
+    ): Promise<unknown> {
+        const providerId = String(input.providerId || "").trim().toLowerCase();
+        const payload = {
+            ...input,
+            operation,
+        };
+        if (broker && typeof broker.request === "function") {
+            return this.callBrokerWithRetry(broker, "request", payload);
+        }
+        if (broker && typeof broker.invoke === "function") {
+            return this.callBrokerWithRetry(broker, "invoke", payload);
+        }
+        const legacyMap: Record<string, string> = {
+            "list-workspaces": "listWorkspaces",
+            "list-items": "listItems",
+            "search-items": "search",
+            "create-share-link": "createShareLink",
+        };
+        if (broker) {
+            return this.callBrokerWithRetry(broker, legacyMap[operation], input);
+        }
+        if (providerId === "sharepoint") {
+            const sessionBroker = this.resolveSessionRequestBroker();
+            return this.callSharePointContentViaSessionRequest(sessionBroker, operation, input);
+        }
+        throw new Error(`Content broker is not available for provider "${providerId || "unknown"}".`);
+    }
+
+    private async callSharePointContentViaSessionRequest(
+        broker: SessionRequestBroker | null,
+        operation: "list-workspaces" | "list-items" | "search-items" | "create-share-link",
+        input: {
+            providerId: string;
+            sessionId: string;
+            endpointUrl?: string;
+            workspaceId?: string;
+            path?: string;
+            query?: string;
+            itemId?: string;
+            scope?: "organization" | "anonymous";
+            type?: "view" | "edit";
+            limit?: number;
+            cursor?: string;
+        }
+    ): Promise<unknown> {
+        if (!broker || typeof broker.request !== "function") {
+            throw new Error(
+                "Host content broker is unavailable and __FDO_SESSION_REQUEST.request is not exposed for SharePoint fallback."
+            );
+        }
+        const base = String(input.endpointUrl || "").trim().replace(/\/+$/, "");
+        if (!base) {
+            throw new Error("SharePoint fallback requires endpointUrl.");
+        }
+        if (!input.sessionId) {
+            throw new Error("SharePoint fallback requires sessionId.");
+        }
+        if (operation === "list-workspaces") {
+            const searchQuery = String(input.query || "").trim();
+            if (input.cursor && String(input.cursor).trim()) {
+                const response = await this.callBrokerWithRetry(broker, "request", {
+                    sessionId: input.sessionId,
+                    method: "GET",
+                    url: String(input.cursor).trim(),
+                });
+                const data = response && typeof response === "object" ? (response as { data?: unknown }).data : response;
+                return {
+                    items: Array.isArray((data as { value?: unknown[] })?.value) ? (data as { value: unknown[] }).value : [],
+                    nextCursor: typeof (data as { ["@odata.nextLink"]?: unknown })?.["@odata.nextLink"] === "string"
+                        ? String((data as { ["@odata.nextLink"]: string })["@odata.nextLink"]).trim()
+                        : "",
+                };
+            }
+            if (searchQuery) {
+                const response = await this.callBrokerWithRetry(broker, "request", {
+                    sessionId: input.sessionId,
+                    method: "GET",
+                    url: `${base}/sites`,
+                    query: {
+                        search: searchQuery,
+                        $top: input.limit || 100,
+                    },
+                });
+                const data = response && typeof response === "object" ? (response as { data?: unknown }).data : response;
+                return {
+                    items: Array.isArray((data as { value?: unknown[] })?.value) ? (data as { value: unknown[] }).value : [],
+                    nextCursor: typeof (data as { ["@odata.nextLink"]?: unknown })?.["@odata.nextLink"] === "string"
+                        ? String((data as { ["@odata.nextLink"]: string })["@odata.nextLink"]).trim()
+                        : "",
+                };
+            }
+            if (input.workspaceId) {
+                const encodedSiteId = encodeURIComponent(input.workspaceId);
+                const response = await this.callBrokerWithRetry(broker, "request", {
+                    sessionId: input.sessionId,
+                    method: "GET",
+                    url: `${base}/sites/${encodedSiteId}`,
+                });
+                const data = response && typeof response === "object" ? (response as { data?: unknown }).data : response;
+                return {
+                    items: data && typeof data === "object" ? [data as Record<string, unknown>] : [],
+                    nextCursor: "",
+                };
+            }
+            throw new Error("SharePoint workspace discovery requires either a search query or a SharePoint Site ID.");
+        }
+        if (operation === "list-items") {
+            if (!input.workspaceId) {
+                throw new Error("SharePoint list-items fallback requires workspaceId (site id).");
+            }
+            const encodedSiteId = encodeURIComponent(input.workspaceId);
+            const url = input.cursor && String(input.cursor).trim()
+                ? String(input.cursor).trim()
+                : `${base}/sites/${encodedSiteId}/drive/root/children`;
+            const response = await this.callBrokerWithRetry(broker, "request", {
+                sessionId: input.sessionId,
+                method: "GET",
+                url,
+                query: input.cursor ? undefined : { $top: input.limit || 300 },
+            });
+            const data = response && typeof response === "object" ? (response as { data?: unknown }).data : response;
+            return {
+                items: Array.isArray((data as { value?: unknown[] })?.value) ? (data as { value: unknown[] }).value : [],
+                nextCursor: typeof (data as { ["@odata.nextLink"]?: unknown })?.["@odata.nextLink"] === "string"
+                    ? String((data as { ["@odata.nextLink"]: string })["@odata.nextLink"]).trim()
+                    : "",
+            };
+        }
+        if (operation === "search-items") {
+            const url = input.cursor && String(input.cursor).trim() ? String(input.cursor).trim() : `${base}/sites`;
+            const response = await this.callBrokerWithRetry(broker, "request", {
+                sessionId: input.sessionId,
+                method: "GET",
+                url,
+                query: input.cursor ? undefined : {
+                    search: input.query || "*",
+                    $top: input.limit || 300,
+                },
+            });
+            const data = response && typeof response === "object" ? (response as { data?: unknown }).data : response;
+            return {
+                items: Array.isArray((data as { value?: unknown[] })?.value) ? (data as { value: unknown[] }).value : [],
+                nextCursor: typeof (data as { ["@odata.nextLink"]?: unknown })?.["@odata.nextLink"] === "string"
+                    ? String((data as { ["@odata.nextLink"]: string })["@odata.nextLink"]).trim()
+                    : "",
+            };
+        }
+        if (operation === "create-share-link") {
+            throw new Error("SharePoint share-link fallback requires a host content broker implementation.");
+        }
+        throw new Error(`Unsupported SharePoint fallback operation "${operation}".`);
+    }
+
+    private appendRecentActivity(action: string, detail: string): void {
+        const current = this.readState<Array<{ id: string; action: string; detail: string; at: string }>>(
+            ServiceContentHubPlugin.STORAGE_KEYS.RECENT_ACTIVITY,
+            []
+        );
+        current.unshift({
+            id: `act-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+            action,
+            detail,
+            at: new Date().toISOString(),
+        });
+        this.writeState(ServiceContentHubPlugin.STORAGE_KEYS.RECENT_ACTIVITY, current.slice(0, 80));
+    }
+
+    private registerHandlers(): void {
+        if (this.handlersRegistered) {
+            return;
+        }
+        this.handlersRegistered = true;
+
+        PluginRegistry.registerHandler(ServiceContentHubPlugin.PREPARE_HANDLER, () => ({
+            ok: true,
+            context: this.readState<ServiceContext>(ServiceContentHubPlugin.STORAGE_KEYS.CONTEXT, DEFAULT_CONTEXT),
+            favorites: this.readState<ContentItem[]>(ServiceContentHubPlugin.STORAGE_KEYS.FAVORITES, []),
+            recentActivity: this.readState<Array<{ id: string; action: string; detail: string; at: string }>>(
+                ServiceContentHubPlugin.STORAGE_KEYS.RECENT_ACTIVITY,
+                []
+            ),
+            cursor: this.readState<string>(ServiceContentHubPlugin.STORAGE_KEYS.LAST_CURSOR, ""),
+            storageMode: this.jsonStoreAvailable ? "persistent-json" : "session-fallback",
+        }));
+
+        PluginRegistry.registerHandler(ServiceContentHubPlugin.SAVE_CONTEXT_HANDLER, (data: unknown) => {
+            const context = this.normalizeContext(data);
+            if (!context.providerId) {
+                return { ok: false, code: "CONTEXT_INVALID", error: "Provider ID is required." };
+            }
+            const endpointValidation = this.validateEndpointUrl(context.endpointUrl);
+            if (!endpointValidation.ok) {
+                return { ok: false, code: endpointValidation.code, error: endpointValidation.error };
+            }
+            const persistence = this.writeState(ServiceContentHubPlugin.STORAGE_KEYS.CONTEXT, context);
+            this.appendRecentActivity("save-context", `${context.providerId}${context.accountId ? ` · ${context.accountId}` : ""}`);
+            return { ok: true, context, persistence };
+        });
+
+        PluginRegistry.registerHandler(ServiceContentHubPlugin.AUTH_START_HANDLER, async (data: unknown) => {
+            const correlationId = this.getCorrelationId("auth-start");
+            const context = this.normalizeContext(data);
+            try {
+                this.requireConnectorNetwork("start host auth session");
+                const endpointValidation = this.validateEndpointUrl(context.endpointUrl);
+                if (!endpointValidation.ok) {
+                    return { ok: false, code: endpointValidation.code, error: endpointValidation.error, correlationId };
+                }
+                const broker = this.resolveAuthBroker();
+                const authStartInput: Record<string, unknown> = {
+                    providerId: context.providerId,
+                    accountHint: context.accountId || undefined,
+                    endpointUrl: context.endpointUrl || undefined,
+                };
+                const sharePointDeviceCodeRequest = this.buildSharePointDeviceCodeStartRequest(context);
+                if (sharePointDeviceCodeRequest) {
+                    authStartInput.request = sharePointDeviceCodeRequest;
+                    authStartInput.endpointUrl = sharePointDeviceCodeRequest.url;
+                }
+                const result = await this.callBroker(broker, "start", authStartInput);
+                if (result && typeof result === "object" && (result as { ok?: unknown }).ok === false) {
+                    const errorRecord = result as { code?: unknown; error?: unknown };
+                    return {
+                        ok: false,
+                        code: typeof errorRecord.code === "string" ? errorRecord.code : "AUTH_START_FAILED",
+                        error: this.augmentSharePointAuthStartError(
+                            context,
+                            typeof errorRecord.error === "string" ? errorRecord.error : "Auth start failed."
+                        ),
+                        correlationId,
+                    };
+                }
+                const sessionId = this.readAuthSessionId(result);
+                const normalizedAuthorizationUrl = this.readAuthRedirectUrl(result);
+                const deviceCode = this.readDeviceCodeDetails(result);
+                const resultRecord = result && typeof result === "object" ? result as Record<string, unknown> : {};
+                const hasAuthTxnEnvelope = typeof resultRecord.authTxnId === "string" && resultRecord.authTxnId.trim().length > 0;
+                const envelopeRawMissing = hasAuthTxnEnvelope && (!("raw" in resultRecord) || resultRecord.raw == null);
+                if (deviceCode.verificationUri || deviceCode.verificationUriComplete) {
+                    const pendingContext = {
+                        ...context,
+                        sessionId: sessionId || context.sessionId,
+                        accountId: typeof (result as { accountId?: unknown })?.accountId === "string"
+                            ? String((result as { accountId: string }).accountId).trim()
+                            : context.accountId,
+                        authDeviceCode: deviceCode.deviceCode,
+                        authVerificationUri: deviceCode.verificationUri,
+                        authVerificationUriComplete: deviceCode.verificationUriComplete,
+                        authUserCode: deviceCode.userCode,
+                        authPollIntervalSeconds: deviceCode.intervalSeconds,
+                        authCodeExpiresAt: deviceCode.expiresInSeconds > 0
+                            ? new Date(Date.now() + deviceCode.expiresInSeconds * 1000).toISOString()
+                            : "",
+                    };
+                    this.writeState(ServiceContentHubPlugin.STORAGE_KEYS.CONTEXT, pendingContext);
+                    this.appendRecentActivity("auth-start", `${context.providerId} · device code issued`);
+                    return {
+                        ok: true,
+                        pending: true,
+                        ...pendingContext,
+                        verificationUri: deviceCode.verificationUri,
+                        verificationUriComplete: deviceCode.verificationUriComplete,
+                        userCode: deviceCode.userCode,
+                        message: deviceCode.message,
+                        authTxnId: hasAuthTxnEnvelope ? String(resultRecord.authTxnId) : undefined,
+                        correlationId,
+                    };
+                }
+                if (normalizedAuthorizationUrl) {
+                    const authUrlValidation = this.validateEndpointUrl(normalizedAuthorizationUrl);
+                    if (!authUrlValidation.ok) {
+                        return {
+                            ok: false,
+                            code: authUrlValidation.code,
+                            error: `Auth authorization URL invalid: ${authUrlValidation.error}`,
+                            correlationId,
+                        };
+                    }
+                    const pendingContext = {
+                        ...context,
+                        sessionId: sessionId || context.sessionId,
+                        accountId: typeof (result as { accountId?: unknown })?.accountId === "string"
+                            ? String((result as { accountId: string }).accountId).trim()
+                            : context.accountId,
+                    };
+                    this.writeState(ServiceContentHubPlugin.STORAGE_KEYS.CONTEXT, pendingContext);
+                    this.appendRecentActivity("auth-start", `${context.providerId} · redirect pending`);
+                    return {
+                        ok: true,
+                        pending: true,
+                        ...pendingContext,
+                        authorizationUrl: normalizedAuthorizationUrl,
+                        authTxnId: hasAuthTxnEnvelope ? String(resultRecord.authTxnId) : undefined,
+                        correlationId,
+                    };
+                }
+                if (envelopeRawMissing && sessionId) {
+                    const pendingContext = {
+                        ...context,
+                        sessionId,
+                        accountId: typeof (result as { accountId?: unknown })?.accountId === "string"
+                            ? String((result as { accountId: string }).accountId).trim()
+                            : context.accountId,
+                    };
+                    this.writeState(ServiceContentHubPlugin.STORAGE_KEYS.CONTEXT, pendingContext);
+                    this.appendRecentActivity("auth-start", `${context.providerId} · auth txn started (awaiting follow-up)`);
+                    return {
+                        ok: true,
+                        pending: true,
+                        ...pendingContext,
+                        authHint: context.providerId.trim().toLowerCase() === "sharepoint"
+                            ? "Device-code flow requires a Microsoft app registration with Public client/native access enabled."
+                            : "Provider-specific redirect details were not returned by host.",
+                        authTxnId: String(resultRecord.authTxnId),
+                        correlationId,
+                    };
+                }
+                if (!sessionId) {
+                    throw new Error("Auth broker returned neither session id nor authorization url.");
+                }
+                const nextContext = {
+                    ...context,
+                    sessionId,
+                    accountId: typeof (result as { accountId?: unknown })?.accountId === "string"
+                        ? String((result as { accountId: string }).accountId).trim()
+                        : context.accountId,
+                };
+                this.writeState(ServiceContentHubPlugin.STORAGE_KEYS.CONTEXT, nextContext);
+                this.appendRecentActivity("auth-start", `${context.providerId} · session created`);
+                return { ok: true, ...nextContext, correlationId };
+            } catch (error) {
+                const mapped = this.classifyBrokerError(error, "AUTH_START_FAILED");
+                return {
+                    ok: false,
+                    code: mapped.code,
+                    error: this.augmentSharePointAuthStartError(context, mapped.message),
+                    correlationId,
+                };
+            }
+        });
+
+        PluginRegistry.registerHandler(ServiceContentHubPlugin.AUTH_REFRESH_HANDLER, async (data: unknown) => {
+            const correlationId = this.getCorrelationId("auth-refresh");
+            try {
+                this.requireConnectorNetwork("refresh host auth session");
+                const context = this.normalizeContext(data);
+                if (!context.sessionId) {
+                    return { ok: false, code: "SESSION_REQUIRED", error: "Session id is required for refresh.", correlationId };
+                }
+                const broker = this.resolveAuthBroker();
+                const authRefreshInput: Record<string, unknown> = {
+                    providerId: context.providerId,
+                    sessionId: context.sessionId,
+                };
+                const sharePointDeviceCodeRequest = this.buildSharePointDeviceCodeRefreshRequest(context);
+                if (sharePointDeviceCodeRequest) {
+                    authRefreshInput.request = sharePointDeviceCodeRequest;
+                }
+                const result = await this.callBroker(broker, "refresh", authRefreshInput);
+                if (result && typeof result === "object" && (result as { ok?: unknown }).ok === false) {
+                    const resultRecord = result as Record<string, unknown>;
+                    const errorMessage = typeof resultRecord.error === "string" ? resultRecord.error.trim() : "Auth refresh failed.";
+                    if (
+                        context.providerId.trim().toLowerCase() === "sharepoint"
+                        && sharePointDeviceCodeRequest
+                        && /status 400|authorization_pending|slow_down|authorization_declined|bad_verification_code/i.test(errorMessage)
+                    ) {
+                        return {
+                            ok: true,
+                            pending: true,
+                            sessionId: context.sessionId,
+                            verificationUri: context.authVerificationUri,
+                            verificationUriComplete: context.authVerificationUriComplete,
+                            userCode: context.authUserCode,
+                            message: "Microsoft authorization is still pending. Finish sign-in in the browser, then click Auth Refresh again.",
+                            correlationId,
+                        };
+                    }
+                    return {
+                        ok: false,
+                        code: typeof resultRecord.code === "string" ? resultRecord.code : "AUTH_REFRESH_FAILED",
+                        error: errorMessage,
+                        correlationId,
+                    };
+                }
+                const nextSessionId = typeof (result as { sessionId?: unknown })?.sessionId === "string"
+                    ? String((result as { sessionId: string }).sessionId).trim()
+                    : context.sessionId;
+                const explicitSessionCredentials = this.readExplicitSessionCredentials(result);
+                if (explicitSessionCredentials) {
+                    const persistResult = await this.callBroker(broker, "refresh", {
+                        providerId: context.providerId,
+                        sessionId: nextSessionId,
+                        auth: explicitSessionCredentials.auth,
+                        credentials: explicitSessionCredentials.credentials,
+                    });
+                    if (persistResult && typeof persistResult === "object" && (persistResult as { ok?: unknown }).ok === false) {
+                        const persistRecord = persistResult as Record<string, unknown>;
+                        return {
+                            ok: false,
+                            code: typeof persistRecord.code === "string" ? persistRecord.code : "AUTH_REFRESH_FAILED",
+                            error: typeof persistRecord.error === "string" ? persistRecord.error : "Failed to persist plugin-parsed session credentials.",
+                            correlationId,
+                        };
+                    }
+                }
+                const nextContext = {
+                    ...context,
+                    sessionId: nextSessionId,
+                    authDeviceCode: "",
+                    authVerificationUri: "",
+                    authVerificationUriComplete: "",
+                    authUserCode: "",
+                    authCodeExpiresAt: "",
+                };
+                this.writeState(ServiceContentHubPlugin.STORAGE_KEYS.CONTEXT, nextContext);
+                this.appendRecentActivity("auth-refresh", context.providerId);
+                return { ok: true, ...nextContext, correlationId };
+            } catch (error) {
+                const mapped = this.classifyBrokerError(error, "AUTH_REFRESH_FAILED");
+                return { ok: false, code: mapped.code, error: mapped.message, correlationId };
+            }
+        });
+
+        PluginRegistry.registerHandler(ServiceContentHubPlugin.AUTH_LOGOUT_HANDLER, async (data: unknown) => {
+            const correlationId = this.getCorrelationId("auth-logout");
+            try {
+                this.requireConnectorNetwork("close host auth session");
+                const context = this.normalizeContext(data);
+                if (!context.sessionId) {
+                    return { ok: false, code: "SESSION_REQUIRED", error: "Session id is required for logout.", correlationId };
+                }
+                const broker = this.resolveAuthBroker();
+                await this.callBroker(broker, "logout", {
+                    providerId: context.providerId,
+                    sessionId: context.sessionId,
+                });
+                const cleared: ServiceContext = { ...context, sessionId: "" };
+                this.writeState(ServiceContentHubPlugin.STORAGE_KEYS.CONTEXT, cleared);
+                this.appendRecentActivity("auth-logout", context.providerId);
+                return { ok: true, correlationId };
+            } catch (error) {
+                const mapped = this.classifyBrokerError(error, "AUTH_LOGOUT_FAILED");
+                return { ok: false, code: mapped.code, error: mapped.message, correlationId };
+            }
+        });
+
+        PluginRegistry.registerHandler(ServiceContentHubPlugin.LIST_WORKSPACES_HANDLER, async (data: unknown) => {
+            const correlationId = this.getCorrelationId("list-workspaces");
+            try {
+                this.requireConnectorNetwork("list connector workspaces");
+                const context = this.normalizeContext(data);
+                if (!context.sessionId) {
+                    return { ok: false, code: "SESSION_REQUIRED", error: "Session id is required.", correlationId };
+                }
+                const endpointValidation = this.validateEndpointUrl(context.endpointUrl);
+                if (!endpointValidation.ok) {
+                    return { ok: false, code: endpointValidation.code, error: endpointValidation.error, correlationId };
+                }
+                const query = typeof (data as { query?: unknown })?.query === "string"
+                    ? String((data as { query: string }).query).trim()
+                    : "";
+                const cursor = this.normalizeCursor(data);
+                const broker = this.resolveContentBroker();
+                const result = await this.callContentOperation(broker, "list-workspaces", {
+                    providerId: context.providerId,
+                    sessionId: context.sessionId,
+                    endpointUrl: context.endpointUrl || undefined,
+                    query: query || undefined,
+                    limit: 100,
+                    cursor: cursor || undefined,
+                });
+                const items = this.normalizeItems(result);
+                const nextCursor = this.readResponseCursor(result);
+                this.writeState(ServiceContentHubPlugin.STORAGE_KEYS.LAST_CURSOR, nextCursor);
+                this.appendRecentActivity("list-workspaces", `${context.providerId} · ${items.length}`);
+                return { ok: true, items, nextCursor, page: { nextCursor }, correlationId };
+            } catch (error) {
+                const mapped = this.classifyBrokerError(error, "LIST_WORKSPACES_FAILED");
+                return { ok: false, code: mapped.code, error: mapped.message, correlationId };
+            }
+        });
+
+        PluginRegistry.registerHandler(ServiceContentHubPlugin.LIST_ITEMS_HANDLER, async (data: unknown) => {
+            const correlationId = this.getCorrelationId("list-items");
+            try {
+                this.requireConnectorNetwork("list connector items");
+                const context = this.normalizeContext(data);
+                if (!context.sessionId || !context.workspaceId) {
+                    return {
+                        ok: false,
+                        code: "CONTEXT_REQUIRED",
+                        error: "Session id and workspace id are required.",
+                        correlationId,
+                    };
+                }
+                const endpointValidation = this.validateEndpointUrl(context.endpointUrl);
+                if (!endpointValidation.ok) {
+                    return { ok: false, code: endpointValidation.code, error: endpointValidation.error, correlationId };
+                }
+                const cursor = this.normalizeCursor(data);
+                const broker = this.resolveContentBroker();
+                const result = await this.callContentOperation(broker, "list-items", {
+                    providerId: context.providerId,
+                    sessionId: context.sessionId,
+                    endpointUrl: context.endpointUrl || undefined,
+                    workspaceId: context.workspaceId,
+                    path: context.path || "/",
+                    limit: 300,
+                    cursor: cursor || undefined,
+                });
+                const items = this.normalizeItems(result);
+                const nextCursor = this.readResponseCursor(result);
+                this.writeState(ServiceContentHubPlugin.STORAGE_KEYS.LAST_CURSOR, nextCursor);
+                this.appendRecentActivity("list-items", `${context.workspaceId} · ${items.length}`);
+                return { ok: true, items, nextCursor, page: { nextCursor }, correlationId };
+            } catch (error) {
+                const mapped = this.classifyBrokerError(error, "LIST_ITEMS_FAILED");
+                return { ok: false, code: mapped.code, error: mapped.message, correlationId };
+            }
+        });
+
+        PluginRegistry.registerHandler(ServiceContentHubPlugin.SEARCH_ITEMS_HANDLER, async (data: unknown) => {
+            const correlationId = this.getCorrelationId("search");
+            try {
+                this.requireConnectorNetwork("search connector items");
+                const context = this.normalizeContext(data);
+                const query = typeof (data as { query?: unknown })?.query === "string"
+                    ? String((data as { query: string }).query).trim()
+                    : "";
+                if (!context.sessionId || !query) {
+                    return { ok: false, code: "SEARCH_INPUT_INVALID", error: "Session id and query are required.", correlationId };
+                }
+                const endpointValidation = this.validateEndpointUrl(context.endpointUrl);
+                if (!endpointValidation.ok) {
+                    return { ok: false, code: endpointValidation.code, error: endpointValidation.error, correlationId };
+                }
+                const cursor = this.normalizeCursor(data);
+                const broker = this.resolveContentBroker();
+                const result = await this.callContentOperation(broker, "search-items", {
+                    providerId: context.providerId,
+                    sessionId: context.sessionId,
+                    endpointUrl: context.endpointUrl || undefined,
+                    workspaceId: context.workspaceId || undefined,
+                    query,
+                    limit: 300,
+                    cursor: cursor || undefined,
+                });
+                const items = this.normalizeItems(result);
+                const nextCursor = this.readResponseCursor(result);
+                this.writeState(ServiceContentHubPlugin.STORAGE_KEYS.LAST_CURSOR, nextCursor);
+                this.appendRecentActivity("search", `${query} · ${items.length}`);
+                return { ok: true, items, nextCursor, page: { nextCursor }, correlationId };
+            } catch (error) {
+                const mapped = this.classifyBrokerError(error, "SEARCH_FAILED");
+                return { ok: false, code: mapped.code, error: mapped.message, correlationId };
+            }
+        });
+
+        PluginRegistry.registerHandler(ServiceContentHubPlugin.CREATE_SHARE_LINK_HANDLER, async (data: unknown) => {
+            const correlationId = this.getCorrelationId("share-link");
+            try {
+                this.requireConnectorNetwork("create connector share link");
+                const context = this.normalizeContext(data);
+                const itemId = typeof (data as { itemId?: unknown })?.itemId === "string"
+                    ? String((data as { itemId: string }).itemId).trim()
+                    : "";
+                if (!context.sessionId || !itemId) {
+                    return {
+                        ok: false,
+                        code: "SHARE_LINK_INPUT_INVALID",
+                        error: "Session id and item id are required.",
+                        correlationId,
+                    };
+                }
+                const endpointValidation = this.validateEndpointUrl(context.endpointUrl);
+                if (!endpointValidation.ok) {
+                    return { ok: false, code: endpointValidation.code, error: endpointValidation.error, correlationId };
+                }
+                const broker = this.resolveContentBroker();
+                const result = await this.callContentOperation(broker, "create-share-link", {
+                    providerId: context.providerId,
+                    sessionId: context.sessionId,
+                    endpointUrl: context.endpointUrl || undefined,
+                    itemId,
+                    scope: "organization",
+                    type: "view",
+                });
+                const webUrl = typeof (result as { webUrl?: unknown })?.webUrl === "string"
+                    ? String((result as { webUrl: string }).webUrl).trim()
+                    : "";
+                if (!webUrl) {
+                    throw new Error("Content broker returned empty share link.");
+                }
+                this.appendRecentActivity("create-share-link", itemId);
+                return { ok: true, webUrl, correlationId };
+            } catch (error) {
+                const mapped = this.classifyBrokerError(error, "CREATE_SHARE_LINK_FAILED");
+                return { ok: false, code: mapped.code, error: mapped.message, correlationId };
+            }
+        });
+
+        PluginRegistry.registerHandler(ServiceContentHubPlugin.OPEN_BROWSER_HANDLER, async (data: unknown) => {
+            const correlationId = this.getCorrelationId("open-browser");
+            try {
+                const webUrl = typeof (data as { webUrl?: unknown })?.webUrl === "string"
+                    ? String((data as { webUrl: string }).webUrl).trim()
+                    : "";
+                if (!webUrl) {
+                    return { ok: false, code: "OPEN_URL_INVALID", error: "Web URL is required.", correlationId };
+                }
+                const endpointValidation = this.validateEndpointUrl(webUrl);
+                if (!endpointValidation.ok) {
+                    return { ok: false, code: endpointValidation.code, error: endpointValidation.error, correlationId };
+                }
+                const broker = this.resolveOpenUrlBroker();
+                if (!broker || typeof broker.open !== "function") {
+                    return {
+                        ok: false,
+                        code: "BROWSER_BROKER_UNAVAILABLE",
+                        error: "Host browser broker is not available.",
+                        correlationId,
+                    };
+                }
+                await this.callBroker(broker, "open", {
+                    url: webUrl,
+                    policy: "trusted-content-link",
+                });
+                this.appendRecentActivity("open-browser", webUrl);
+                return { ok: true, correlationId };
+            } catch (error) {
+                const mapped = this.classifyBrokerError(error, "OPEN_BROWSER_FAILED");
+                return { ok: false, code: mapped.code, error: mapped.message, correlationId };
+            }
+        });
+
+        PluginRegistry.registerHandler(ServiceContentHubPlugin.BUILD_CLIPBOARD_WRITE_REQUEST_HANDLER, (data: unknown) => {
+            requireCapability("system.clipboard.write", "copy share link to clipboard");
+            const text = typeof (data as { text?: unknown })?.text === "string"
+                ? String((data as { text: string }).text).trim()
+                : "";
+            if (!text) {
+                return { ok: false, code: "CLIPBOARD_INPUT_INVALID", error: "Text is required." };
+            }
+            return createClipboardWriteRequest(text, "copy service share link");
+        });
+
+        PluginRegistry.registerHandler(ServiceContentHubPlugin.ADD_FAVORITE_HANDLER, (data: unknown) => {
+            const item = this.normalizeItems([(data as { item?: unknown })?.item])[0];
+            if (!item) {
+                return { ok: false, code: "FAVORITE_INPUT_INVALID", error: "Favorite item payload is invalid." };
+            }
+            const current = this.readState<ContentItem[]>(ServiceContentHubPlugin.STORAGE_KEYS.FAVORITES, []);
+            const next = [item, ...current.filter((entry) => entry.id !== item.id)].slice(0, 100);
+            this.writeState(ServiceContentHubPlugin.STORAGE_KEYS.FAVORITES, next);
+            this.appendRecentActivity("add-favorite", item.name);
+            return { ok: true, favorites: next };
+        });
+
+        PluginRegistry.registerHandler(ServiceContentHubPlugin.QUICK_OPEN_FAVORITES_HANDLER, () => ({
+            ok: true,
+            intent: "open-favorites",
+        }));
+        PluginRegistry.registerHandler(ServiceContentHubPlugin.QUICK_SEARCH_HANDLER, () => ({
+            ok: true,
+            intent: "focus-search",
+        }));
+        PluginRegistry.registerHandler(ServiceContentHubPlugin.SIDE_PANEL_BROWSER_HANDLER, () => ({
+            ok: true,
+            intent: "open-browser",
+        }));
+        PluginRegistry.registerHandler(ServiceContentHubPlugin.SIDE_PANEL_RECENT_HANDLER, () => ({
+            ok: true,
+            intent: "open-recent",
+        }));
+        PluginRegistry.registerHandler(ServiceContentHubPlugin.SIDE_PANEL_SETTINGS_HANDLER, () => ({
+            ok: true,
+            intent: "open-settings",
+        }));
+
+        PluginRegistry.registerHandler(ServiceContentHubPlugin.AI_ASSISTANTS_LIST_HANDLER, async (data: unknown) => {
+            const payload = typeof data === "object" && data !== null ? data as Record<string, unknown> : {};
+            try {
+                const provider = (globalThis as { __FDO_AI_LIST_ASSISTANTS?: ((input: unknown) => unknown) }).__FDO_AI_LIST_ASSISTANTS;
+                if (typeof provider !== "function") {
+                    return { ok: true, source: "fallback", assistants: [] };
+                }
+                const result = provider({
+                    purpose: typeof payload.purpose === "string" ? payload.purpose : "automation",
+                });
+                const resolved = result && typeof (result as Promise<unknown>).then === "function"
+                    ? await (result as Promise<unknown>)
+                    : result;
+                const assistants = Array.isArray((resolved as { assistants?: unknown[] })?.assistants)
+                    ? (resolved as { assistants: unknown[] }).assistants
+                    : (Array.isArray(resolved) ? resolved : []);
+                return { ok: true, source: "fdo-ai", assistants };
+            } catch (error) {
+                return { ok: false, code: "AI_ASSISTANTS_LIST_FAILED", error: error instanceof Error ? error.message : String(error) };
+            }
+        });
+
+        PluginRegistry.registerHandler(ServiceContentHubPlugin.AI_ASSIST_HANDLER, async (data: unknown) => {
+            const payload = typeof data === "object" && data !== null ? data as Record<string, unknown> : {};
+            try {
+                const provider = (globalThis as { __FDO_AI_REQUEST?: ((input: unknown) => unknown) }).__FDO_AI_REQUEST;
+                if (typeof provider === "function") {
+                    const result = provider(payload);
+                    const resolved = result && typeof (result as Promise<unknown>).then === "function"
+                        ? await (result as Promise<unknown>)
+                        : result;
+                    const message = typeof (resolved as { message?: unknown })?.message === "string"
+                        ? String((resolved as { message: string }).message).trim()
+                        : (
+                            typeof (resolved as { text?: unknown })?.text === "string"
+                                ? String((resolved as { text: string }).text).trim()
+                                : ""
+                        );
+                    if (message) {
+                        return { ok: true, source: "fdo-ai", message };
+                    }
+                }
+                const count = Number((payload.summary as { count?: unknown })?.count || 0);
+                return {
+                    ok: true,
+                    source: "fallback",
+                    message: `Local fallback summary: ${count} result(s). Configure __FDO_AI_REQUEST for richer output.`,
+                };
+            } catch (error) {
+                return { ok: false, code: "AI_ASSIST_FAILED", error: error instanceof Error ? error.message : String(error) };
+            }
+        });
+    }
+}
+
+new ServiceContentHubPlugin();
diff --git a/examples/README.md b/examples/README.md
index 5e5e482..fd0c08c 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -29,7 +29,7 @@ Primary authoring entry points:
 
 Use the operator fixtures for production-oriented DevOps/SRE/plugin authoring work.
 Use the non-operator fixtures for lifecycle, error-handling, storage, and UI composition baselines.
-For privileged/operator fixtures, prefer declaring expected capabilities in code via `declareCapabilities()` so host preflight checks can compare declared vs granted capabilities early.
+For privileged/operator fixtures, prefer declaring expected capabilities in code via `declareCapabilities()` so host preflight checks can compare declared vs granted capabilities early. For explicit diagnostics in plugin logic, use `runCapabilityPreflight({ declared, granted, action })`.
 
 ## Getting Started
 
@@ -48,10 +48,13 @@ The examples are still numbered to indicate learning progression:
 4. **04-ui-extensions-plugin.ts** - Quick actions and side panel integration
 5. **05-advanced-dom-plugin.ts** - Advanced DOM generation with styling
 6. **06-error-handling-plugin.ts** - Error handling and debugging techniques
-7. **07-injected-libraries-demo.ts** - Demonstrates host-injected iframe libraries, browser-only helpers, the `UI_MESSAGE` bridge pattern, and host-mediated clipboard read/write flows
+7. **07-injected-libraries-demo.ts** - Demonstrates host-injected iframe libraries, browser-only helpers, the `UI_MESSAGE` bridge pattern, and host-mediated clipboard read/write flows with extracted privileged request payloads
 8. **08-privileged-actions-plugin.ts** - Low-level host privileged action flow using `requestPrivilegedAction(...)` with correlation ids and stable response handling
 9. **09-operator-plugin.ts** - Curated operator helper example for a known tool family using operator request builders, declared preset capabilities, and host-mediated execution
 10. **10-system-file-plugin.ts** - Generic scoped filesystem mutation for a system file other than `/etc/hosts`, using `system.fs.mutate` and the same low-level privileged transport pattern as `08`
+11. **11-hosts-manager-plugin/** - Real-world multi-file example demonstrating CSS imports, advanced state management, and `/etc/hosts` management (SwitchHosts style)
+12. **12-git-operations-plugin.ts** - One-file Git operations command center using curated Git operator scope, host quick actions + side panel entries, injected iframe libraries, persisted repository-path preferences, and a prefetch flow for the original configured repository (`publicKey` + path stored in plugin storage) where `remote.origin.url` is resolved via host-mediated scoped Git execution before metadata fetch (`system.network` + `system.network.https` + `system.network.scope.public-web-secure`; no auto-run command on runtime preparation). Includes declared-capability preflight diagnostics, staged commit execution, generalized AI assist hooks (commit message generation, output summarization, next-step suggestions), recent-run timeline tracking, and centralized privileged-envelope execution/error handling in `renderOnLoad()`.
+13. **13-service-content-hub-plugin.ts** - Production-oriented generic connector example for SaaS/content services (SharePoint, Dropbox, Drive, Confluence, custom APIs) with host-managed auth/session broker + content broker pattern, provider-based endpoint defaults (overridable `endpointUrl`), cursor pagination, selectable result actions, open-in-browser host policy gate, share-link clipboard flow, AI summary hook, persisted context/favorites/recent activity, and declarative runtime wiring via `defineRenderOnLoadActions(...)` (`strict: true`).
 
 For operator-style plugins, prefer host-mediated `system.process.exec` with a narrow scope such as `system.process.scope.docker-cli`, `system.process.scope.kubectl`, `system.process.scope.terraform`, or another explicit tool-family scope rather than raw shell execution.
 
@@ -87,6 +90,65 @@ if (response?.ok) {
 }
 ```
 
+When backend handlers return a privileged-action envelope through `createPrivilegedActionBackendRequest(...)`, use the canonical pipeline helper:
+
+```ts
+const envelopeOrRequest = await window.createBackendReq("UI_MESSAGE", {
+  handler: "plugin.buildPrivilegedRequest",
+  content: {},
+});
+
+const { response, errorMessage } = await requestPrivilegedActionFromEnvelope(envelopeOrRequest, {
+  context: "Privileged action failed",
+});
+
+if (!response.ok) {
+  console.error(errorMessage);
+}
+```
+
+If you need low-level control, this remains valid:
+
+```ts
+const requestPayload = extractPrivilegedActionRequest(envelopeOrRequest);
+const response = await window.createBackendReq("requestPrivilegedAction", requestPayload);
+const message = formatPrivilegedActionError(response, { context: "Privileged action failed" });
+```
+
+For `renderOnLoad()` string runtimes, use:
+
+```ts
+const formatPrivilegedActionErrorSource = getInlinePrivilegedActionErrorFormatterSource();
+// inside the returned onLoad string:
+const formatPrivilegedActionError = ${formatPrivilegedActionErrorSource};
+```
+
+The helper safely unwraps all currently supported shapes:
+
+```ts
+input.result.request
+input.request
+direct request
+```
+
+If you are not using the helper yet, the current compatibility fallback is:
+
+```ts
+const envelope = await window.createBackendReq("UI_MESSAGE", {
+  handler: "plugin.buildPrivilegedRequest",
+  content: {},
+});
+
+const requestPayload = envelope?.result?.request ?? envelope?.request ?? envelope;
+const correlationId = envelope?.result?.correlationId ?? envelope?.correlationId;
+```
+
+Deprecated behavior:
+
+- passing the full backend envelope object directly into `requestPrivilegedAction` is incorrect
+- always pass the extracted validated request object instead
+```
+
 ## Injected Libraries
 
 The FDO application automatically injects several popular libraries that you can use without additional imports:
@@ -119,6 +181,32 @@ For detailed guidance on stable fixtures, public docs, and authoring expectation
 - **Solution**: Ensure all required methods (`init`, `render`) are implemented
 - **Solution**: Check that metadata is properly defined with all required fields
 
+### Plugin Exits On Startup (abnormal-exit / metadata error)
+
+- **Issue**: Utility/plugin process exits during startup, often with logs similar to:
+  - `Plugin metadata must be an object.`
+  - Electron `reason: abnormal-exit` and a non-zero exit code (for example `256`, raw status for exit code `1`)
+- **Root cause**: Calling `PluginRegistry.useStore(...)` in class-field initialization before metadata is available in runtime initialization order.
+- **Solution**: Do not initialize stores in class fields. Acquire stores lazily via helper getter or in `init()` after metadata is assigned.
+- **Solution**: Keep backend handlers fail-safe (`{ ok: false, code, error }`) for expected validation failures so UI can render errors without killing plugin startup.
+
+### Error Rendering Plugin: Invalid render payload
+
+- **Issue**: UI shows `Error rendering plugin` and `Invalid render payload`.
+- **Common root cause**: `render()` (or helper methods called by it) throws before returning a valid render string, often due to gated store access such as `PluginRegistry.useStore("json")` in render-time or class-field initialization paths.
+- **Solution**: Keep render-path storage safe:
+  - Use `default` store for non-gated/session access.
+  - Treat `json` store as optional and initialize it in `init()` with fallback.
+  - Avoid calling gated store APIs from class fields and direct render-path code.
+  - Use safe wrappers/fallback values in `render()` so it always returns a valid string.
+
+### Prefetch Fails Because Node `require()` Is Unavailable
+
+- **Issue**: Prefetch logic fails with runtime errors indicating `require()` or Node module loading is unavailable.
+- **Root cause**: Git/config inspection is being attempted in a runtime path that does not guarantee raw Node module loading.
+- **Solution**: Do not read `.git/config` directly through `require()` for UI-triggered flows. Build a host-mediated scoped Git process request (for example `git config --get remote.origin.url`), execute it through `requestPrivilegedAction`, then pass the resolved remote URL to backend metadata fetch logic.
+- **Design rule**: UI runtime must avoid Node assumptions; backend/host paths should use supported SDK contracts and scoped privileged execution for Git/system inspection.
+
 ### Storage Operations Fail
 
 - **Issue**: Data persistence errors (example 03)
diff --git a/examples/fixtures/operator-custom-tool-plugin.fixture.ts b/examples/fixtures/operator-custom-tool-plugin.fixture.ts
index 0c1103a..a32d374 100644
--- a/examples/fixtures/operator-custom-tool-plugin.fixture.ts
+++ b/examples/fixtures/operator-custom-tool-plugin.fixture.ts
@@ -1,12 +1,14 @@
 import {
   FDOInterface,
   FDO_SDK,
+  getInlinePrivilegedActionErrorFormatterSource,
   PluginCapability,
   PluginMetadata,
   PluginRegistry,
   createProcessCapabilityBundle,
   createPrivilegedActionBackendRequest,
   createScopedProcessExecActionRequest,
+  extractPrivilegedActionRequest,
 } from "@anikitenko/fdo-sdk";
 
 /**
@@ -73,10 +75,12 @@ export default class OperatorCustomToolFixturePlugin extends FDO_SDK implements
   }
 
   renderOnLoad(): string {
+    const formatPrivilegedActionErrorSource = getInlinePrivilegedActionErrorFormatterSource();
     return `
       (() => {
         const previewStatusButton = document.getElementById("custom-tool-preview-status");
         const output = document.getElementById("custom-tool-result");
+        const formatPrivilegedActionError = ${formatPrivilegedActionErrorSource};
 
         if (!previewStatusButton || !output) {
           return;
@@ -95,8 +99,22 @@ export default class OperatorCustomToolFixturePlugin extends FDO_SDK implements
               handler,
               content: {},
             });
-            const response = await window.createBackendReq("requestPrivilegedAction", envelope);
-            setOutput(response);
+            const fallbackCorrelationId = envelope?.result?.correlationId ?? envelope?.correlationId ?? "unknown";
+            const requestPayload = extractPrivilegedActionRequest(envelope);
+            const response = await window.createBackendReq("requestPrivilegedAction", requestPayload);
+            if (response && response.ok) {
+              setOutput(response);
+              return;
+            }
+            setOutput({
+              status: "error",
+              correlationId: response?.correlationId ?? fallbackCorrelationId,
+              message: formatPrivilegedActionError(response, {
+                context: "Custom tool request failed",
+                fallbackCorrelationId,
+              }),
+              response: response ?? null,
+            });
           } catch (error) {
             setOutput({
               error: error instanceof Error ? error.message : String(error),
diff --git a/examples/fixtures/operator-kubernetes-plugin.fixture.ts b/examples/fixtures/operator-kubernetes-plugin.fixture.ts
index 451d3a7..cb52dd1 100644
--- a/examples/fixtures/operator-kubernetes-plugin.fixture.ts
+++ b/examples/fixtures/operator-kubernetes-plugin.fixture.ts
@@ -3,8 +3,10 @@ import {
   createOperatorToolCapabilityPreset,
   createPrivilegedActionBackendRequest,
   createScopedWorkflowRequest,
+  extractPrivilegedActionRequest,
   FDOInterface,
   FDO_SDK,
+  getInlinePrivilegedActionErrorFormatterSource,
   getOperatorToolPreset,
   PluginCapability,
   PluginMetadata,
@@ -80,11 +82,13 @@ export default class OperatorKubernetesFixturePlugin extends FDO_SDK implements
   }
 
   renderOnLoad(): string {
+    const formatPrivilegedActionErrorSource = getInlinePrivilegedActionErrorFormatterSource();
     return `
       (() => {
         const previewObjectsButton = document.getElementById("kubectl-preview-objects");
         const inspectRestartWorkflowButton = document.getElementById("kubectl-inspect-restart-workflow");
         const output = document.getElementById("kubectl-workflow-result");
+        const formatPrivilegedActionError = ${formatPrivilegedActionErrorSource};
 
         if (!previewObjectsButton || !inspectRestartWorkflowButton || !output) {
           return;
@@ -103,8 +107,22 @@ export default class OperatorKubernetesFixturePlugin extends FDO_SDK implements
               handler,
               content: {},
             });
-            const response = await window.createBackendReq("requestPrivilegedAction", envelope);
-            setOutput(response);
+            const fallbackCorrelationId = envelope?.result?.correlationId ?? envelope?.correlationId ?? "unknown";
+            const requestPayload = extractPrivilegedActionRequest(envelope);
+            const response = await window.createBackendReq("requestPrivilegedAction", requestPayload);
+            if (response && response.ok) {
+              setOutput(response);
+              return;
+            }
+            setOutput({
+              status: "error",
+              correlationId: response?.correlationId ?? fallbackCorrelationId,
+              message: formatPrivilegedActionError(response, {
+                context: "Kubernetes operator request failed",
+                fallbackCorrelationId,
+              }),
+              response: response ?? null,
+            });
           } catch (error) {
             setOutput({
               error: error instanceof Error ? error.message : String(error),
diff --git a/examples/fixtures/operator-terraform-plugin.fixture.ts b/examples/fixtures/operator-terraform-plugin.fixture.ts
index dc8fd96..a255b3f 100644
--- a/examples/fixtures/operator-terraform-plugin.fixture.ts
+++ b/examples/fixtures/operator-terraform-plugin.fixture.ts
@@ -1,7 +1,9 @@
 import {
   createPrivilegedActionBackendRequest,
+  extractPrivilegedActionRequest,
   FDOInterface,
   FDO_SDK,
+  getInlinePrivilegedActionErrorFormatterSource,
   getOperatorToolPreset,
   PluginCapability,
   PluginMetadata,
@@ -80,11 +82,13 @@ export default class OperatorTerraformFixturePlugin extends FDO_SDK implements F
   }
 
   renderOnLoad(): string {
+    const formatPrivilegedActionErrorSource = getInlinePrivilegedActionErrorFormatterSource();
     return `
       (() => {
         const previewPlanButton = document.getElementById("terraform-preview-plan");
         const previewApplyWorkflowButton = document.getElementById("terraform-preview-apply-workflow");
         const output = document.getElementById("terraform-workflow-result");
+        const formatPrivilegedActionError = ${formatPrivilegedActionErrorSource};
         if (!previewPlanButton || !previewApplyWorkflowButton || !output) {
           return;
         }
@@ -102,8 +106,22 @@ export default class OperatorTerraformFixturePlugin extends FDO_SDK implements F
               handler,
               content: {},
             });
-            const response = await window.createBackendReq("requestPrivilegedAction", envelope);
-            setOutput(response);
+            const fallbackCorrelationId = envelope?.result?.correlationId ?? envelope?.correlationId ?? "unknown";
+            const requestPayload = extractPrivilegedActionRequest(envelope);
+            const response = await window.createBackendReq("requestPrivilegedAction", requestPayload);
+            if (response && response.ok) {
+              setOutput(response);
+              return;
+            }
+            setOutput({
+              status: "error",
+              correlationId: response?.correlationId ?? fallbackCorrelationId,
+              message: formatPrivilegedActionError(response, {
+                context: "Terraform operator request failed",
+                fallbackCorrelationId,
+              }),
+              response: response ?? null,
+            });
           } catch (error) {
             setOutput({
               error: error instanceof Error ? error.message : String(error),
diff --git a/examples/fixtures/storage-plugin.fixture.ts b/examples/fixtures/storage-plugin.fixture.ts
index f0e1b04..ba6ae27 100644
--- a/examples/fixtures/storage-plugin.fixture.ts
+++ b/examples/fixtures/storage-plugin.fixture.ts
@@ -1,4 +1,4 @@
-import { FDOInterface, FDO_SDK, PluginMetadata, PluginRegistry, StoreType } from "@anikitenko/fdo-sdk";
+import { FDOInterface, FDO_SDK, PluginCapability, PluginMetadata, PluginRegistry, StoreType } from "@anikitenko/fdo-sdk";
 
 /**
  * Scenario fixture: Scoped storage usage.
@@ -37,6 +37,10 @@ export default class StorageFixturePlugin extends FDO_SDK implements FDOInterfac
     return this._metadata;
   }
 
+  declareCapabilities(): PluginCapability[] {
+    return ["storage", "storage.json"];
+  }
+
   init(): void {
     const visitCount = (this.sessionStore.get<number>(this.VISITS_KEY) ?? 0) + 1;
     this.sessionStore.set(this.VISITS_KEY, visitCount);
diff --git a/package.json b/package.json
index 499a538..2062ebb 100644
--- a/package.json
+++ b/package.json
@@ -30,6 +30,9 @@
   "bugs": {
     "url": "https://github.com/anikitenko/fdo-sdk/issues"
   },
+  "bin": {
+    "fdo-sdk": "bin/fdo-sdk.js"
+  },
   "main": "dist/fdo-sdk.bundle.js",
   "types": "dist/@types/index.d.ts",
   "type": "commonjs",
@@ -42,6 +45,8 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "bin/**/*.js",
+    "scripts/fdo-sdk-migrate.mjs",
     "dist/**/*.d.ts",
     "dist/**/*.js",
     "dist/**/*.json",
@@ -57,6 +62,7 @@
     "verify:types:local": "node scripts/verify-types-local.mjs",
     "verify:types:pack": "node scripts/verify-types-pack.mjs",
     "verify:docs": "node scripts/verify-docs.mjs",
+    "migrate": "node scripts/fdo-sdk-migrate.mjs",
     "verify:pack": "npm run verify:types:pack",
     "prepack": "npm run build && npm run verify:types:local",
     "test": "vitest run",
diff --git a/scripts/fdo-sdk-migrate.mjs b/scripts/fdo-sdk-migrate.mjs
new file mode 100644
index 0000000..16f39db
--- /dev/null
+++ b/scripts/fdo-sdk-migrate.mjs
@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+import { readdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+
+const SUPPORTED_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
+const SKIP_DIRS = new Set(["node_modules", "dist", ".git", ".idea", "coverage"]);
+
+function printHelp() {
+  console.log([
+    "fdo-sdk migrate",
+    "",
+    "Usage:",
+    "  fdo-sdk migrate [--target <path>] [--write]",
+    "  node scripts/fdo-sdk-migrate.mjs [--target <path>] [--write]",
+    "",
+    "Options:",
+    "  --target <path>   Directory to scan (default: current working directory).",
+    "  --write           Apply changes in-place. Without this flag, command runs in dry-run mode.",
+    "  --help            Show this message.",
+    "",
+    "Rules:",
+    "  - replace legacy privileged envelope fallback chain with extractPrivilegedActionRequest(...)",
+    "  - replace deprecated PluginRegistry.configureCapabilityPolicy(...) with configureCapabilities(...)",
+  ].join("\n"));
+}
+
+function parseArgs(rawArgs) {
+  const options = {
+    target: process.cwd(),
+    write: false,
+  };
+
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index];
+
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+      continue;
+    }
+
+    if (arg === "--write") {
+      options.write = true;
+      continue;
+    }
+
+    if (arg === "--target") {
+      const value = rawArgs[index + 1];
+      if (!value) {
+        throw new Error("Missing value for --target");
+      }
+      options.target = path.resolve(value);
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--target=")) {
+      options.target = path.resolve(arg.slice("--target=".length));
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  return options;
+}
+
+function hasNamedImport(importList, importName) {
+  return importList
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .some((entry) => entry.split(/\s+as\s+/u)[0].trim() === importName);
+}
+
+function ensureExtractHelperImport(source) {
+  const importName = "extractPrivilegedActionRequest";
+  const moduleName = "@anikitenko/fdo-sdk";
+  const namedImportPattern = /import\s*\{([\s\S]*?)\}\s*from\s*["']@anikitenko\/fdo-sdk["'];?/u;
+  const namedImportMatch = source.match(namedImportPattern);
+
+  if (namedImportMatch) {
+    const existingNames = namedImportMatch[1] ?? "";
+    if (hasNamedImport(existingNames, importName)) {
+      return source;
+    }
+
+    const imports = existingNames
+      .split(",")
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+    imports.push(importName);
+    const replacement = `import { ${imports.join(", ")} } from "${moduleName}";`;
+    return source.replace(namedImportPattern, replacement);
+  }
+
+  const importLine = `import { ${importName} } from "${moduleName}";`;
+  const lines = source.split("\n");
+  let lastImportIndex = -1;
+
+  for (let index = 0; index < lines.length; index += 1) {
+    if (/^\s*import\s/u.test(lines[index])) {
+      lastImportIndex = index;
+    }
+  }
+
+  if (lastImportIndex >= 0) {
+    lines.splice(lastImportIndex + 1, 0, importLine);
+    return lines.join("\n");
+  }
+
+  return `${importLine}\n${source}`;
+}
+
+function applyMigrations(source) {
+  let output = source;
+  const ruleHits = [];
+
+  const privilegedPattern = /(\b(?:const|let|var)\s+[A-Za-z_$][\w$]*\s*=\s*)([A-Za-z_$][\w$]*)\s*\?\.\s*result\s*\?\.\s*request\s*\?\?\s*\2\s*\?\.\s*request\s*\?\?\s*\2(\s*;)/gu;
+  let privilegedCount = 0;
+  output = output.replace(privilegedPattern, (_match, declaration, envelopeVar, suffix) => {
+    privilegedCount += 1;
+    return `${declaration}extractPrivilegedActionRequest(${envelopeVar})${suffix}`;
+  });
+  if (privilegedCount > 0) {
+    output = ensureExtractHelperImport(output);
+    ruleHits.push({ rule: "privileged-envelope-extract-helper", count: privilegedCount });
+  }
+
+  const configurePattern = /\.configureCapabilityPolicy\s*\(/gu;
+  let configureCount = 0;
+  output = output.replace(configurePattern, () => {
+    configureCount += 1;
+    return ".configureCapabilities(";
+  });
+  if (configureCount > 0) {
+    ruleHits.push({ rule: "plugin-registry-configure-capabilities", count: configureCount });
+  }
+
+  return {
+    output,
+    changed: output !== source,
+    ruleHits,
+  };
+}
+
+async function walkFiles(targetDir) {
+  const info = await stat(targetDir);
+  if (!info.isDirectory()) {
+    return [targetDir];
+  }
+
+  const discovered = [];
+  const entries = await readdir(targetDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) {
+        continue;
+      }
+      discovered.push(...(await walkFiles(path.join(targetDir, entry.name))));
+      continue;
+    }
+
+    const ext = path.extname(entry.name).toLowerCase();
+    if (!SUPPORTED_EXTENSIONS.has(ext)) {
+      continue;
+    }
+    discovered.push(path.join(targetDir, entry.name));
+  }
+
+  return discovered;
+}
+
+export async function run(rawArgs = process.argv.slice(2)) {
+  const options = parseArgs(rawArgs);
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  const targetStat = await stat(options.target).catch(() => null);
+  if (!targetStat) {
+    throw new Error(`Target path does not exist: ${options.target}`);
+  }
+
+  const files = await walkFiles(options.target);
+  let changedFiles = 0;
+  const reportLines = [];
+
+  for (const filePath of files) {
+    const source = await readFile(filePath, "utf8");
+    const result = applyMigrations(source);
+    if (!result.changed) {
+      continue;
+    }
+
+    changedFiles += 1;
+    const relative = path.relative(process.cwd(), filePath) || filePath;
+    const rules = result.ruleHits
+      .map((entry) => `${entry.rule} x${entry.count}`)
+      .join(", ");
+    reportLines.push(`- ${relative}: ${rules}`);
+
+    if (options.write) {
+      await writeFile(filePath, result.output, "utf8");
+    }
+  }
+
+  const mode = options.write ? "write" : "dry-run";
+  console.log(`fdo-sdk migrate (${mode})`);
+  console.log(`Target: ${options.target}`);
+  console.log(`Scanned files: ${files.length}`);
+  console.log(`${options.write ? "Updated files" : "Files to update"}: ${changedFiles}`);
+  if (reportLines.length > 0) {
+    for (const line of reportLines) {
+      console.log(line);
+    }
+  }
+
+  if (!options.write && changedFiles > 0) {
+    console.log("Run again with --write to apply these changes.");
+  }
+}
+
+const isDirectExecution = process.argv[1]
+  ? pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url
+  : false;
+
+if (isDirectExecution) {
+  run().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`fdo-sdk migrate failed: ${message}`);
+    process.exit(1);
+  });
+}
diff --git a/scripts/verify-docs.mjs b/scripts/verify-docs.mjs
index 6e33bf2..f16fee7 100644
--- a/scripts/verify-docs.mjs
+++ b/scripts/verify-docs.mjs
@@ -1,5 +1,7 @@
 import { readFile, readdir, stat } from "node:fs/promises";
 import path from "node:path";
+import vm from "node:vm";
+import ts from "typescript";
 
 const repoRoot = process.cwd();
 const scanRoots = ["README.md", "docs", "examples"];
@@ -13,7 +15,10 @@ const bannedPatterns = [
 ];
 
 const markdownLinkPattern = /\[[^\]]+]\((?!https?:\/\/|mailto:|#)([^)]+)\)/g;
+const codeFencePattern = /```([^\n`]*)\n([\s\S]*?)```/g;
 const findings = [];
+let verifiedSnippetCount = 0;
+let runtimeCheckedSnippetCount = 0;
 
 async function walk(target) {
   const fullPath = path.join(repoRoot, target);
@@ -40,6 +45,138 @@ function resolveMarkdownTarget(fromFile, target) {
   return path.resolve(path.dirname(path.join(repoRoot, fromFile)), cleanTarget);
 }
 
+function getLineNumber(content, index) {
+  const prefix = content.slice(0, index);
+  return prefix.split("\n").length;
+}
+
+function parseFenceInfo(infoRaw) {
+  const info = String(infoRaw || "").trim().toLowerCase();
+  if (!info) {
+    return { language: "", tags: new Set() };
+  }
+
+  const parts = info.split(/\s+/).filter(Boolean);
+  const [language = ""] = parts;
+  return {
+    language,
+    tags: new Set(parts.slice(1)),
+  };
+}
+
+function mapLanguageToExtension(language) {
+  if (language === "ts" || language === "typescript") {
+    return "ts";
+  }
+  if (language === "js" || language === "javascript") {
+    return "js";
+  }
+  return null;
+}
+
+function formatTsDiagnostics(diagnostics) {
+  return diagnostics
+    .map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"))
+    .join(" | ");
+}
+
+function transpileSnippetOrThrow({ relativeFile, snippetIndex, language, source }) {
+  const ext = mapLanguageToExtension(language);
+  if (!ext) {
+    throw new Error(
+      `Snippet #${snippetIndex} in ${relativeFile} uses unsupported language "${language}" for docs verification.`
+    );
+  }
+
+  const result = ts.transpileModule(source, {
+    fileName: `${relativeFile}#snippet-${snippetIndex}.${ext}`,
+    reportDiagnostics: true,
+    compilerOptions: {
+      target: ts.ScriptTarget.ES2020,
+      module: ts.ModuleKind.ESNext,
+      moduleResolution: ts.ModuleResolutionKind.Bundler,
+      strict: true,
+      skipLibCheck: true,
+      lib: ["lib.es2020.d.ts", "lib.dom.d.ts"],
+    },
+  });
+
+  const errors = (result.diagnostics ?? []).filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error);
+  if (errors.length > 0) {
+    throw new Error(formatTsDiagnostics(errors));
+  }
+
+  return result.outputText;
+}
+
+function stripStaticImportsForRuntime(source) {
+  return source
+    .replace(/^\s*import[\s\S]*?from\s+["'][^"']+["'];?\s*$/gm, "")
+    .replace(/^\s*import\s+["'][^"']+["'];?\s*$/gm, "")
+    .replace(/^\s*export\s+/gm, "");
+}
+
+async function runRuntimeSnippetOrThrow({ source }) {
+  const runtimeSource = stripStaticImportsForRuntime(source);
+  if (/\bimport\s/u.test(runtimeSource) || /\bexport\s/u.test(runtimeSource)) {
+    throw new Error("runtime-check snippets must not contain unresolved import/export statements.");
+  }
+
+  const runtimeTranspile = ts.transpileModule(runtimeSource, {
+    fileName: "docs-runtime-check.ts",
+    reportDiagnostics: true,
+    compilerOptions: {
+      target: ts.ScriptTarget.ES2020,
+      module: ts.ModuleKind.ES2020,
+      strict: false,
+      skipLibCheck: true,
+      lib: ["lib.es2020.d.ts", "lib.dom.d.ts"],
+    },
+  });
+  const runtimeErrors = (runtimeTranspile.diagnostics ?? []).filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error);
+  if (runtimeErrors.length > 0) {
+    throw new Error(formatTsDiagnostics(runtimeErrors));
+  }
+
+  const context = vm.createContext({
+    console: {
+      log: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+    },
+    window: {
+      createBackendReq: async () => ({ ok: true }),
+      waitForElement: () => {},
+      addGlobalEventListener: () => {},
+      removeGlobalEventListener: () => {},
+      executeInjectedScript: () => {},
+      applyClassToSelector: () => {},
+    },
+    document: {
+      querySelector: () => null,
+      querySelectorAll: () => [],
+      getElementById: () => null,
+      createElement: () => ({ addEventListener: () => {}, dataset: {} }),
+    },
+    setTimeout,
+    clearTimeout,
+    Promise,
+    Error,
+  });
+
+  const script = new vm.Script(runtimeTranspile.outputText);
+  const result = script.runInContext(context, { timeout: 1500 });
+  if (result && typeof result.then === "function") {
+    await Promise.race([
+      result,
+      new Promise((_, reject) => {
+        setTimeout(() => reject(new Error("runtime-check snippet timed out.")), 1500);
+      }),
+    ]);
+  }
+}
+
 for (const root of scanRoots) {
   const files = await walk(root);
   for (const relativeFile of files) {
@@ -69,10 +206,52 @@ for (const root of scanRoots) {
           findings.push(`${relativeFile}: broken relative markdown link -> ${target}`);
         }
       }
+
+      let snippetIndex = 0;
+      for (const match of content.matchAll(codeFencePattern)) {
+        snippetIndex += 1;
+        const infoRaw = match[1] ?? "";
+        const source = match[2] ?? "";
+        const startIndex = match.index ?? 0;
+        const line = getLineNumber(content, startIndex);
+        const { language, tags } = parseFenceInfo(infoRaw);
+
+        if (!tags.has("verify")) {
+          continue;
+        }
+
+        verifiedSnippetCount += 1;
+        try {
+          transpileSnippetOrThrow({
+            relativeFile,
+            snippetIndex,
+            language,
+            source,
+          });
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          findings.push(`${relativeFile}:${line} snippet #${snippetIndex} compile check failed: ${message}`);
+          continue;
+        }
+
+        if (tags.has("runtime")) {
+          runtimeCheckedSnippetCount += 1;
+          try {
+            await runRuntimeSnippetOrThrow({ source });
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            findings.push(`${relativeFile}:${line} snippet #${snippetIndex} runtime check failed: ${message}`);
+          }
+        }
+      }
     }
   }
 }
 
+if (verifiedSnippetCount === 0) {
+  findings.push("No documentation snippets are tagged with `verify`. Add at least one fenced code block with `verify` tag.");
+}
+
 if (findings.length > 0) {
   console.error("Documentation verification failed:");
   for (const finding of findings) {
@@ -81,4 +260,6 @@ if (findings.length > 0) {
   process.exit(1);
 }
 
-console.log("Documentation verification passed.");
+console.log(
+  `Documentation verification passed. Verified snippets: ${verifiedSnippetCount}; runtime-checked snippets: ${runtimeCheckedSnippetCount}.`
+);
diff --git a/src/DOMButton.ts b/src/DOMButton.ts
index ea70536..f918066 100644
--- a/src/DOMButton.ts
+++ b/src/DOMButton.ts
@@ -31,5 +31,26 @@ export class DOMButton extends DOM {
         const props = this.combineProperties("pure-button", options, id)
         return this.createElement("button", {...props, onClick: onClick, ...otherProps}, label);
     }
-}
 
+    /**
+     * Creates a static button element without serializing an inline click handler.
+     * Use this for UI that binds listeners imperatively in renderOnLoad.
+     * @param label - The label of the button.
+     * @param options - The options to apply to the button.
+     * @param id - The id of the button.
+     * @param otherProps - Additional properties to apply to the button (e.g. type).
+     * @returns {string} - The rendered button element.
+     * @uiName Create static button
+     * @example <caption>Create a button and bind click in runtime code.</caption>
+     * const button = new DOMButton().createStaticButton("Run", { disableDefaultClass: true }, "run-btn", { type: "button" });
+     */
+    public createStaticButton(
+        label: string,
+        options: Partial<typeof DOM.DEFAULT_OPTIONS> = DOM.DEFAULT_OPTIONS,
+        id?: string,
+        otherProps?: Record<string, any>
+    ): string {
+        const props = this.combineProperties("pure-button", options, id);
+        return this.createElement("button", {...props, ...otherProps}, label);
+    }
+}
diff --git a/src/FDOInterface.ts b/src/FDOInterface.ts
index cdbb701..69ebe4e 100644
--- a/src/FDOInterface.ts
+++ b/src/FDOInterface.ts
@@ -1,17 +1,21 @@
 import {FDO_SDK} from "./index";
-import { PluginCapability } from "./types";
+import { PluginCapability, RenderOnLoadOutput } from "./types";
 
 /**
  * Public plugin contract for FDO SDK plugins.
  *
- * `render()` and `renderOnLoad()` are synchronous and return strings.
- * The SDK serializes those strings for host transport separately.
+ * `render()` is synchronous and returns a string.
+ * `renderOnLoad()` is synchronous and may return:
+ * - a string source
+ * - a function (serialized via `Function#toString`)
+ * - `defineRenderOnLoad(...)` module output
+ * The SDK serializes normalized source strings for host transport.
  */
 export interface FDOInterface {
     declareCapabilities?(): PluginCapability[];
     init(): void;
     render(): string;
-    renderOnLoad?(): string;
+    renderOnLoad?(): RenderOnLoadOutput;
 }
 
 export default FDOInterface;
diff --git a/src/PluginRegistry.ts b/src/PluginRegistry.ts
index 330415d..2e99312 100644
--- a/src/PluginRegistry.ts
+++ b/src/PluginRegistry.ts
@@ -21,8 +21,15 @@ import { createDefaultStore } from "./StoreDefault";
 import { createJsonStore } from "./StoreJson";
 import { validatePluginMetadata, validateSerializedRenderPayload } from "./utils/contracts";
 import { NotificationManager } from "./utils/NotificationManager";
-import { configureCapabilities, createCapabilityBundle, getCapabilityDiagnostics, requireCapability } from "./utils/capabilities";
+import {
+    configureCapabilities,
+    createCapabilityBundle,
+    getCapabilityDiagnostics,
+    requireStorageBackendCapability,
+    runCapabilityPreflight
+} from "./utils/capabilities";
 import { emitDeprecationWarning } from "./utils/deprecation";
+import { getSdkHandshake } from "./utils/handshake";
 
 type PluginWithMetadata = FDO_SDK & { metadata: PluginMetadata };
 type PluginWithQuickActions = FDO_SDK & { defineQuickActions: () => QuickAction[] };
@@ -105,7 +112,7 @@ export class PluginRegistry {
         const context = this.getStoreContext();
 
         if (storeName === "json") {
-            requireCapability("storage.json", "use the JSON persistent store");
+            requireStorageBackendCapability("json", "use the JSON persistent store");
         }
 
         if (!this.storeInstances[context.pluginId]) {
@@ -243,15 +250,19 @@ export class PluginRegistry {
         const sidePanelConfig = this.getSidePanelConfig();
         const permissions = getCapabilityDiagnostics();
         const declaredCapabilities = this.getDeclaredCapabilities();
-        const grantedSet = new Set(permissions.granted);
-        const declaredSet = new Set(declaredCapabilities);
-        const missingDeclared = declaredCapabilities.filter((capability) => !grantedSet.has(capability));
-        const undeclaredGranted = permissions.granted.filter((capability) => !declaredSet.has(capability));
+        const capabilityPreflight = runCapabilityPreflight({
+            declared: declaredCapabilities,
+            granted: permissions.granted,
+            action: "satisfy plugin declared capability contract",
+        });
+        const missingDeclared = capabilityPreflight.missing.map((entry) => entry.capability as any).filter((entry): entry is typeof declaredCapabilities[number] => typeof entry === "string");
+        const undeclaredGranted = capabilityPreflight.undeclaredGranted.map((entry) => entry.capability as any).filter((entry): entry is typeof permissions.granted[number] => typeof entry === "string");
 
         return {
             apiVersion: FDO_SDK.API_VERSION,
             pluginId,
             metadata,
+            handshake: getSdkHandshake(),
             health: {
                 status: this.diagnosticsState.errorCount > 0 ? "degraded" : "healthy",
                 startedAt: this.diagnosticsState.startedAt,
@@ -493,20 +504,30 @@ export class PluginRegistry {
             return;
         }
 
-        const grantedCapabilities = getCapabilityDiagnostics().granted;
-        const grantedSet = new Set(grantedCapabilities);
-        const missingCapabilities = declaredCapabilities.filter((capability) => !grantedSet.has(capability));
+        const preflight = runCapabilityPreflight({
+            declared: declaredCapabilities,
+            action: "initialize plugin runtime",
+        });
 
         this._logger.event("plugin.capabilities.declared", {
             declaredCapabilities,
-            grantedCapabilities,
-            missingCapabilities,
+            grantedCapabilities: preflight.granted,
+            missingCapabilities: preflight.missing.map((entry) => entry.capability),
+            remediations: preflight.remediations,
         });
 
-        if (missingCapabilities.length > 0) {
+        if (preflight.missing.length > 0) {
             this._logger.warn(
-                `Plugin declared capabilities that are not currently granted: ${missingCapabilities.join(", ")}.`
+                `Plugin declared capabilities that are not currently granted: ${preflight.missing.map((entry) => entry.capability).join(", ")}.`
             );
+            for (const remediation of preflight.remediations) {
+                this._logger.warn(`Capability preflight remediation: ${remediation}`);
+            }
+        } else {
+            this._logger.info("Plugin capability preflight passed for declared capabilities.", {
+                declaredCapabilities,
+                grantedCapabilities: preflight.granted,
+            });
         }
     }
 }
diff --git a/src/index.ts b/src/index.ts
index 2644ca3..fb23714 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -2,6 +2,9 @@ import {Logger} from "./Logger";
 import "./ambient/fdo-host";
 import {Communicator} from "./Communicator";
 import {PluginRegistry} from "./PluginRegistry";
+import type { RenderOnLoadOutput } from "./types";
+import { createNoopRenderOnLoadSource, resolveRenderOnLoadSource } from "./utils/renderOnLoad";
+import { SDK_API_VERSION } from "./version";
 
 export { atomicWriteFile, atomicWriteFileSync } from "./utils/atomic";
 export { BLUEPRINT_V6_ICON_NAMES, isBlueprintV6IconName } from "./utils/blueprintIcons";
@@ -17,16 +20,29 @@ export { pify } from "./utils/pify";
 export { runWithSudo } from "./utils/runWithSudo";
 export { emitDeprecationWarning, formatDeprecationMessage } from "./utils/deprecation";
 export {
+    createAICapabilityBundle,
     createCapabilityBundle,
     createFilesystemCapabilityBundle,
+    createNetworkCapabilityBundle,
+    createNetworkScopeCapability,
     createProcessCapabilityBundle,
+    createStorageCapabilityBundle,
     createWorkflowCapabilityBundle,
     describeCapability,
+    runCapabilityPreflight,
     parseMissingCapabilityError,
+    requireCapability,
     requireFilesystemScopeCapability,
+    requireNetworkScopeCapability,
     requireProcessScopeCapability,
+    requireStorageBackendCapability,
     requireWorkflowProcessCapabilities,
 } from "./utils/capabilities";
+export {
+    createAICapabilityPreset,
+    getAICapabilityPreset,
+    listAICapabilityPresets,
+} from "./utils/aiTooling";
 export {
     createClipboardReadActionRequest,
     createClipboardWriteActionRequest,
@@ -46,12 +62,16 @@ export {
 } from "./utils/clipboardTooling";
 export {
     createPrivilegedActionCorrelationId,
+    formatPrivilegedActionError,
+    getInlinePrivilegedActionErrorFormatterSource,
     isPrivilegedActionErrorResponse,
     isPrivilegedActionSuccessResponse,
     unwrapPrivilegedActionResponse,
 } from "./utils/privilegedResponses";
 export {
     createPrivilegedActionBackendRequest,
+    extractPrivilegedActionRequest,
+    requestPrivilegedActionFromEnvelope,
     requestPrivilegedAction,
 } from "./utils/privilegedTransport";
 export {
@@ -63,6 +83,11 @@ export {
     requestOperatorTool,
     requestScopedProcessExec,
 } from "./utils/operatorTooling";
+export {
+    createStorageCapabilityPreset,
+    getStorageCapabilityPreset,
+    listStorageCapabilityPresets,
+} from "./utils/storageTooling";
 export {
     createScopedWorkflowRequest,
     requestScopedWorkflow,
@@ -72,6 +97,45 @@ export {
     getFailedWorkflowSteps,
     summarizeWorkflowResult,
 } from "./utils/workflowDiagnostics";
+export { createPluginDoctorPanelModel, createPluginDoctorReport } from "./utils/pluginDoctor";
+export {
+    evaluateSdkHandshakeCompatibility,
+    getSdkFeatureFlags,
+    getSdkHandshake,
+    isSdkHandshakeCompatible,
+} from "./utils/handshake";
+export {
+    getFixtureRuntimeMatrix,
+    getFixtureRuntimeMatrixCase,
+    listFixtureRuntimeMatrixCases,
+} from "./utils/fixtureRuntimeMatrix";
+export {
+    formatDiagnosticExactFix,
+    getDiagnosticFixTemplate,
+    listDiagnosticFixTemplates,
+} from "./utils/diagnosticTemplates";
+export { applySdkMigrationCodemod } from "./utils/migrationCodemod";
+export {
+    createNoopRenderOnLoadSource,
+    createRenderOnLoadActionsSource,
+    defineRenderOnLoad,
+    defineRenderOnLoadActions,
+    getRenderOnLoadTemplate,
+    listRenderOnLoadTemplates,
+    getRenderOnLoadMonacoHints,
+    getRenderOnLoadMonacoTypeDefinitions,
+    isRenderOnLoadModule,
+    resolveRenderOnLoadSource,
+} from "./utils/renderOnLoad";
+export {
+    getEditorSupportBundle,
+    getEditorSupportMonacoPolicy,
+    getEditorSupportPackageJson,
+    getEditorSupportPackageManifest,
+    SDK_EDITOR_INDEX_TYPES_VIRTUAL_PATH,
+    SDK_EDITOR_MODULE_ID,
+    SDK_EDITOR_PACKAGE_JSON_VIRTUAL_PATH,
+} from "./utils/editorSupport";
 
 export * from "./FDOInterface";
 export * from "./PluginMetadata";
@@ -92,7 +156,7 @@ export * from "./DOMSemantic";
 export * from "./decorators/ErrorHandler";
 
 export class FDO_SDK {
-    public static readonly API_VERSION: string = "1.0.0"
+    public static readonly API_VERSION: string = SDK_API_VERSION
     static readonly TYPE_TAG = Symbol("FDO_SDK")
     private _logger: Logger = new Logger({ context: { component: "FDO_SDK" } })
     private loggerScope: string = "global";
@@ -116,9 +180,8 @@ export class FDO_SDK {
         throw error
     }
 
-    public renderOnLoad(): string {
-        const load = '() => {}'
-        return load.toString()
+    public renderOnLoad(): RenderOnLoadOutput {
+        return createNoopRenderOnLoadSource();
     }
 
     /**
@@ -143,10 +206,12 @@ export class FDO_SDK {
         const onLoadOutput = this.renderOnLoad() as unknown;
         if (this.isThenable(onLoadOutput)) {
             void onLoadOutput.catch((error: unknown) => this.logAsyncLifecycleError("renderOnLoad", error));
-            throw new Error("Method 'renderOnLoad' must return a synchronous string. Async on-load promises are not supported.");
+            throw new Error(
+                "Method 'renderOnLoad' must return a synchronous string, function, or defineRenderOnLoad(...) module. Async on-load promises are not supported."
+            );
         }
 
-        return JSON.stringify(onLoadOutput)
+        return JSON.stringify(resolveRenderOnLoadSource(onLoadOutput as RenderOnLoadOutput))
     }
 
     public log(message: string): void {
diff --git a/src/types.ts b/src/types.ts
index b8ffc34..78c2905 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -31,18 +31,113 @@ export type UIMessageRequest = {
     content?: unknown;
 };
 
+export type RenderOnLoadSource = string | (() => void);
+
+export type RenderOnLoadHintKind = "snippet" | "function" | "keyword" | "variable";
+
+export type RenderOnLoadHint = {
+    label: string;
+    insertText: string;
+    detail?: string;
+    documentation?: string;
+    kind?: RenderOnLoadHintKind;
+};
+
+export type RenderOnLoadLanguage = "javascript" | "typescript";
+
+export type RenderOnLoadTemplateContext = "runtime-source" | "plugin-method";
+
+export type RenderOnLoadTemplateId =
+    | "runtime-noop"
+    | "runtime-ui-message"
+    | "method-define-render-on-load"
+    | "method-define-render-on-load-actions";
+
+export type RenderOnLoadTemplate = {
+    id: RenderOnLoadTemplateId;
+    label: string;
+    description: string;
+    context: RenderOnLoadTemplateContext;
+    language: RenderOnLoadLanguage;
+    source: string;
+};
+
+export type RenderOnLoadTemplateListOptions = {
+    context?: RenderOnLoadTemplateContext;
+};
+
+export type RenderOnLoadModule = {
+    source: RenderOnLoadSource;
+    language?: RenderOnLoadLanguage;
+    hints?: RenderOnLoadHint[];
+    description?: string;
+};
+
+export type RenderOnLoadOutput = RenderOnLoadSource | RenderOnLoadModule;
+
+export type RenderOnLoadActionHandlerContext = {
+    event: unknown;
+    element: unknown;
+    window: unknown;
+    document: unknown;
+};
+
+export type RenderOnLoadActionHandler = string | ((context: RenderOnLoadActionHandlerContext) => void | Promise<void>);
+
+export type RenderOnLoadActionBinding = {
+    selector: string;
+    event: string;
+    handler: string;
+    preventDefault?: boolean;
+    stopPropagation?: boolean;
+    once?: boolean;
+    passive?: boolean;
+    capture?: boolean;
+    required?: boolean;
+};
+
+export type RenderOnLoadActionBindingsModuleOptions = {
+    handlers: Record<string, RenderOnLoadActionHandler>;
+    bindings: RenderOnLoadActionBinding[];
+    setup?: RenderOnLoadSource;
+    strict?: boolean;
+    language?: RenderOnLoadLanguage;
+    hints?: RenderOnLoadHint[];
+    description?: string;
+};
+
 export type PluginInitRequest = {
     apiVersion?: string;
     capabilities?: PluginCapability[];
 };
 
+export type StorageBackendCapability = `storage.${string}`;
+export type NetworkTransportCapability =
+    | "system.network.https"
+    | "system.network.http"
+    | "system.network.websocket"
+    | "system.network.tcp"
+    | "system.network.udp"
+    | "system.network.dns";
+export type NetworkScopeCapability = `system.network.scope.${string}`;
 export type FilesystemScopeCapability = `system.fs.scope.${string}`;
 export type ProcessScopeCapability = `system.process.scope.${string}`;
+export type AICapability =
+    | "system.ai"
+    | "system.ai.assistants.list"
+    | "system.ai.request";
 export type PluginCapability =
+    | "storage"
     | "storage.json"
+    | StorageBackendCapability
+    | AICapability
+    | "system.network"
+    | NetworkTransportCapability
+    | NetworkScopeCapability
     | "sudo.prompt"
     | "system.clipboard.read"
     | "system.clipboard.write"
+    | "system.host.write"
     | "system.hosts.write"
     | "system.process.exec"
     | FilesystemScopeCapability
@@ -226,6 +321,13 @@ export type PrivilegedActionResponse<TResult = unknown> =
     | PrivilegedActionSuccessResponse<TResult>
     | PrivilegedActionErrorResponse;
 
+export type PrivilegedActionErrorFormatOptions = {
+    context?: string;
+    fallbackCorrelationId?: string;
+    maxDetailLength?: number;
+    includeStdoutWhenStderrMissing?: boolean;
+};
+
 export type PrivilegedActionBackendRequest<TRequest extends HostPrivilegedActionRequest = HostPrivilegedActionRequest> = {
     correlationId: string;
     request: TRequest;
@@ -237,6 +339,20 @@ export type RequestPrivilegedActionOptions = {
     correlationIdPrefix?: string;
 };
 
+export type PrivilegedActionPipelineOptions = RequestPrivilegedActionOptions & {
+    context?: string;
+    fallbackCorrelationId?: string;
+    maxDetailLength?: number;
+    includeStdoutWhenStderrMissing?: boolean;
+    throwOnError?: boolean;
+};
+
+export type PrivilegedActionPipelineResult<TResult = unknown> = {
+    request: HostPrivilegedActionRequest;
+    response: PrivilegedActionResponse<TResult>;
+    errorMessage?: string;
+};
+
 export type OperatorToolPresetId =
     | "docker-cli"
     | "kubectl"
@@ -263,8 +379,30 @@ export type OperatorToolPresetDefinition = {
     typicalUseCases: string[];
 };
 
+export type StorageCapabilityPresetId = "storageJSON";
+
+export type StorageCapabilityPresetDefinition = {
+    id: StorageCapabilityPresetId;
+    label: string;
+    description: string;
+    backendId: string;
+    capabilities: ["storage", StorageBackendCapability];
+};
+
+export type AICapabilityPresetId = "host.ai";
+
+export type AICapabilityPresetDefinition = {
+    id: AICapabilityPresetId;
+    label: string;
+    description: string;
+    capabilities: ["system.ai", "system.ai.assistants.list", "system.ai.request"];
+};
+
 export type CapabilityCategory =
+    | "ai"
     | "storage"
+    | "network"
+    | "network-scope"
     | "sudo"
     | "clipboard"
     | "hosts"
@@ -289,6 +427,23 @@ export type MissingCapabilityDiagnostic = {
     remediation: string;
 };
 
+export type CapabilityPreflightMissingDiagnostic = MissingCapabilityDiagnostic & {
+    requiredCapabilities: string[];
+    missingPrerequisites: string[];
+    grantedPrerequisites: string[];
+};
+
+export type CapabilityPreflightReport = {
+    ok: boolean;
+    action: string;
+    declared: string[];
+    granted: string[];
+    missing: CapabilityPreflightMissingDiagnostic[];
+    undeclaredGranted: CapabilityDescriptor[];
+    remediations: string[];
+    summary: string;
+};
+
 export type UIMessageResponse = unknown | ErrorResponse;
 
 export type PluginInitResponse = {
@@ -381,10 +536,69 @@ export type PluginStoreDiagnostic = {
     version?: number;
 };
 
+export type SdkFeatureFlags = {
+    diagnosticsHandler: boolean;
+    pluginDoctorReport: boolean;
+    declaredCapabilityPreflight: boolean;
+    privilegedActionTransportPipeline: boolean;
+    renderOnLoadModuleAuthoring: boolean;
+    renderOnLoadDeclarativeActions: boolean;
+    editorSupportBundle: boolean;
+};
+
+export type SdkHandshake = {
+    contractVersion: string;
+    sdkVersion: string;
+    apiVersion: string;
+    capabilitySchemaVersion: string;
+    featureFlags: SdkFeatureFlags;
+};
+
+export type SdkHandshakeFeatureFlagName = keyof SdkFeatureFlags;
+
+export type SdkHandshakeCompatibilityOptions = {
+    expectedContractVersion?: string;
+    expectedApiVersion?: string;
+    expectedCapabilitySchemaVersion?: string;
+    requiredFeatureFlags?: SdkHandshakeFeatureFlagName[];
+    featureFlagSeverity?: "warning" | "error";
+    capabilitySchemaSeverity?: "warning" | "error";
+};
+
+export type SdkHandshakeCompatibilityIssueCode =
+    | "HANDSHAKE_CONTRACT_INCOMPATIBLE"
+    | "HANDSHAKE_API_INCOMPATIBLE"
+    | "HANDSHAKE_CAPABILITY_SCHEMA_MISMATCH"
+    | "HANDSHAKE_FEATURE_FLAG_MISSING";
+
+export type SdkHandshakeCompatibilityIssue = {
+    code: SdkHandshakeCompatibilityIssueCode;
+    severity: "warning" | "error";
+    message: string;
+    expected?: string;
+    received?: string;
+    featureFlag?: SdkHandshakeFeatureFlagName;
+};
+
+export type SdkHandshakeCompatibilityStatus = "compatible" | "needs-attention" | "incompatible";
+
+export type SdkHandshakeCompatibilityReport = {
+    ok: boolean;
+    status: SdkHandshakeCompatibilityStatus;
+    handshake: SdkHandshake;
+    counts: {
+        error: number;
+        warning: number;
+    };
+    issues: SdkHandshakeCompatibilityIssue[];
+    summary: string;
+};
+
 export type PluginDiagnostics = {
     apiVersion: string;
     pluginId: string;
     metadata: PluginMetadata | null;
+    handshake: SdkHandshake;
     health: {
         status: PluginHealthStatus;
         startedAt: string;
@@ -422,3 +636,118 @@ export type PluginDiagnostics = {
         recent: PluginDiagnosticNotification[];
     };
 };
+
+export type PluginDoctorSeverity = "error" | "warning" | "info";
+
+export type PluginDoctorCategory =
+    | "health"
+    | "capabilities"
+    | "handshake"
+    | "handlers"
+    | "stores"
+    | "notifications";
+
+export type PluginDoctorFinding = {
+    code: string;
+    severity: PluginDoctorSeverity;
+    category: PluginDoctorCategory;
+    message: string;
+    remediation?: string;
+    details?: Record<string, unknown>;
+};
+
+export type PluginDoctorStatus = "healthy" | "needs-attention" | "degraded";
+
+export type PluginDoctorOptions = {
+    includeInfo?: boolean;
+    includeNotificationFindings?: boolean;
+    capabilityAction?: string;
+    handshake?: SdkHandshakeCompatibilityOptions;
+};
+
+export type PluginDoctorReport = {
+    pluginId: string;
+    generatedAt: string;
+    status: PluginDoctorStatus;
+    summary: string;
+    counts: {
+        error: number;
+        warning: number;
+        info: number;
+    };
+    findings: PluginDoctorFinding[];
+};
+
+export type PluginDoctorPanelOptions = {
+    maxPrioritizedFindings?: number;
+    includeInfoFindings?: boolean;
+    includeExactFix?: boolean;
+};
+
+export type PluginDoctorPanelFinding = PluginDoctorFinding & {
+    priority: number;
+    isBlocking: boolean;
+    exactFix?: string;
+};
+
+export type PluginDoctorPanelSection = {
+    category: PluginDoctorCategory;
+    title: string;
+    counts: {
+        total: number;
+        error: number;
+        warning: number;
+        info: number;
+    };
+    findings: PluginDoctorPanelFinding[];
+};
+
+export type PluginDoctorPanelModel = {
+    pluginId: string;
+    generatedAt: string;
+    status: PluginDoctorStatus;
+    summary: string;
+    blocking: boolean;
+    counts: {
+        total: number;
+        error: number;
+        warning: number;
+        info: number;
+    };
+    prioritizedFindings: PluginDoctorPanelFinding[];
+    sections: PluginDoctorPanelSection[];
+};
+
+export type FixtureRuntimeUiMessageProbe = {
+    handler: string;
+    content?: Record<string, unknown>;
+    description?: string;
+};
+
+export type FixtureRuntimeMatrixCase = {
+    id: string;
+    title: string;
+    fixturePath: string;
+    description: string;
+    probes: {
+        init: true;
+        render: true;
+        renderOnLoad: boolean;
+        uiMessage: FixtureRuntimeUiMessageProbe[];
+    };
+    requiredCapabilities?: PluginCapability[];
+};
+
+export type FixtureRuntimeMatrix = {
+    contractVersion: "1";
+    cases: FixtureRuntimeMatrixCase[];
+};
+
+export type DiagnosticFixTemplate = {
+    code: string;
+    title: string;
+    summary: string;
+    exactFix: string;
+    steps: string[];
+    docs?: string[];
+};
diff --git a/src/utils/aiTooling.ts b/src/utils/aiTooling.ts
new file mode 100644
index 0000000..cf96c8a
--- /dev/null
+++ b/src/utils/aiTooling.ts
@@ -0,0 +1,41 @@
+import {
+    AICapabilityPresetDefinition,
+    AICapabilityPresetId,
+    PluginCapability,
+} from "../types";
+import { createAICapabilityBundle } from "./capabilities";
+
+const PRESET_CONFIG: Record<AICapabilityPresetId, Omit<AICapabilityPresetDefinition, "capabilities">> = {
+    "host.ai": {
+        id: "host.ai",
+        label: "Host AI Core",
+        description: "Host-routed AI assistants with discovery + request operations for multi-assistant plugin workflows.",
+    },
+};
+
+function withCapabilities(
+    preset: Omit<AICapabilityPresetDefinition, "capabilities">
+): AICapabilityPresetDefinition {
+    return {
+        ...preset,
+        capabilities: createAICapabilityBundle(["assistants.list", "request"]) as [
+            "system.ai",
+            "system.ai.assistants.list",
+            "system.ai.request",
+        ],
+    };
+}
+
+export function getAICapabilityPreset(presetId: AICapabilityPresetId): AICapabilityPresetDefinition {
+    return withCapabilities(PRESET_CONFIG[presetId]);
+}
+
+export function listAICapabilityPresets(): AICapabilityPresetDefinition[] {
+    return Object.keys(PRESET_CONFIG)
+        .sort((left, right) => left.localeCompare(right))
+        .map((presetId) => getAICapabilityPreset(presetId as AICapabilityPresetId));
+}
+
+export function createAICapabilityPreset(presetId: AICapabilityPresetId): PluginCapability[] {
+    return [...getAICapabilityPreset(presetId).capabilities];
+}
diff --git a/src/utils/capabilities.ts b/src/utils/capabilities.ts
index fd678b0..a9af0d5 100644
--- a/src/utils/capabilities.ts
+++ b/src/utils/capabilities.ts
@@ -1,4 +1,6 @@
 import {
+    CapabilityPreflightMissingDiagnostic,
+    CapabilityPreflightReport,
     CapabilityConfiguration,
     CapabilityDescriptor,
     MissingCapabilityDiagnostic,
@@ -15,26 +17,115 @@ const audit: CapabilityAudit = {
     usageCount: {},
     deniedCount: {},
 };
+const STORAGE_BACKEND_CAPABILITY_PREFIX = "storage.";
+const AI_CAPABILITY_PREFIX = "system.ai.";
+const AI_OPERATIONS = new Set(["assistants.list", "request"]);
+const NETWORK_CAPABILITY_PREFIX = "system.network.";
+const NETWORK_TRANSPORTS = new Set(["https", "http", "websocket", "tcp", "udp", "dns"]);
+const NETWORK_SCOPE_CAPABILITY_PREFIX = "system.network.scope.";
 const FILESYSTEM_SCOPE_CAPABILITY_PREFIX = "system.fs.scope.";
 const PROCESS_SCOPE_CAPABILITY_PREFIX = "system.process.scope.";
+const HOST_WRITE_CAPABILITY = "system.host.write";
+const HOSTS_WRITE_CAPABILITY = "system.hosts.write";
 const MISSING_CAPABILITY_ERROR_PATTERN = /^Capability "([^"]+)" is required to (.+)\. Configure PluginRegistry\.configureCapabilities\(\{ granted: \["[^"]+"\] \}\) in the host before plugin initialization\.$/;
 
 function increment(counter: Record<string, number>, key: string): void {
     counter[key] = (counter[key] ?? 0) + 1;
 }
 
+function normalizeCapabilityList(capabilities: Array<PluginCapability | string>): string[] {
+    return Array.from(
+        new Set(
+            capabilities
+                .map((entry) => String(entry || "").trim())
+                .filter(Boolean)
+        )
+    ).sort((left, right) => left.localeCompare(right));
+}
+
+function getCapabilityAliases(capability: string): string[] {
+    if (capability === HOST_WRITE_CAPABILITY) {
+        return [HOSTS_WRITE_CAPABILITY];
+    }
+    if (capability === HOSTS_WRITE_CAPABILITY) {
+        return [HOST_WRITE_CAPABILITY];
+    }
+    return [];
+}
+
 function normalizeScopeId(scopeId: string): string {
     return scopeId.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
 }
 
+function normalizeStorageBackendId(backendId: string): string {
+    return backendId.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
+function normalizeNetworkTransportId(transport: string): string {
+    return transport.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
 function buildMissingCapabilityErrorMessage(capability: PluginCapability, action: string): string {
     return `Capability "${capability}" is required to ${action}. Configure PluginRegistry.configureCapabilities({ granted: ["${capability}"] }) in the host before plugin initialization.`;
 }
 
+function getCapabilityPrerequisites(capability: string): string[] {
+    const prerequisites = new Set<string>();
+
+    if (capability.startsWith(STORAGE_BACKEND_CAPABILITY_PREFIX)) {
+        prerequisites.add("storage");
+    }
+
+    if (
+        capability.startsWith(AI_CAPABILITY_PREFIX)
+        && capability !== "system.ai"
+    ) {
+        prerequisites.add("system.ai");
+    }
+
+    if (capability.startsWith(PROCESS_SCOPE_CAPABILITY_PREFIX)) {
+        prerequisites.add("system.process.exec");
+    }
+
+    if (capability.startsWith(FILESYSTEM_SCOPE_CAPABILITY_PREFIX)) {
+        prerequisites.add(HOSTS_WRITE_CAPABILITY);
+    }
+
+    if (capability.startsWith(NETWORK_SCOPE_CAPABILITY_PREFIX)) {
+        prerequisites.add("system.network");
+    }
+
+    if (
+        capability.startsWith(NETWORK_CAPABILITY_PREFIX)
+        && capability !== "system.network"
+        && !capability.startsWith(NETWORK_SCOPE_CAPABILITY_PREFIX)
+    ) {
+        prerequisites.add("system.network");
+    }
+
+    prerequisites.delete(capability);
+    return Array.from(prerequisites).sort((left, right) => left.localeCompare(right));
+}
+
+function buildCapabilityPreflightRemediation(capability: string): string {
+    const prerequisites = getCapabilityPrerequisites(capability);
+    const requiredCapabilities = normalizeCapabilityList([capability, ...prerequisites]);
+    const snippet = requiredCapabilities.map((entry) => `"${entry}"`).join(", ");
+
+    if (prerequisites.length === 0) {
+        return `Grant "${capability}" in the host capability configuration before plugin initialization. Configure PluginRegistry.configureCapabilities({ granted: [${snippet}] }) in the host before plugin initialization.`;
+    }
+
+    return `Grant "${capability}" with prerequisite capabilities ${prerequisites.map((entry) => `"${entry}"`).join(", ")} before plugin initialization. Configure PluginRegistry.configureCapabilities({ granted: [${snippet}] }) in the host before plugin initialization.`;
+}
+
 export function configureCapabilities(configuration: CapabilityConfiguration): void {
     grantedCapabilities.clear();
     for (const capability of configuration.granted) {
         grantedCapabilities.add(capability);
+        for (const alias of getCapabilityAliases(capability)) {
+            grantedCapabilities.add(alias as PluginCapability);
+        }
     }
 }
 
@@ -44,6 +135,11 @@ export function requireCapability(capability: PluginCapability, action: string):
     if (grantedCapabilities.has(capability)) {
         return;
     }
+    for (const alias of getCapabilityAliases(capability)) {
+        if (grantedCapabilities.has(alias as PluginCapability)) {
+            return;
+        }
+    }
 
     increment(audit.deniedCount, capability);
     throw new Error(buildMissingCapabilityErrorMessage(capability, action));
@@ -57,11 +153,25 @@ export function requireProcessScopeCapability(scopeId: string, action: string):
     requireScopedCapability(scopeId, action, PROCESS_SCOPE_CAPABILITY_PREFIX, "Process");
 }
 
+export function requireNetworkScopeCapability(scopeId: string, action: string): void {
+    requireScopedCapability(scopeId, action, NETWORK_SCOPE_CAPABILITY_PREFIX, "Network");
+}
+
 export function requireWorkflowProcessCapabilities(scopeId: string, action: string): void {
     requireCapability("system.process.exec", action);
     requireProcessScopeCapability(scopeId, action);
 }
 
+export function requireStorageBackendCapability(backendId: string, action: string): void {
+    const normalizedBackend = normalizeStorageBackendId(backendId);
+    if (!normalizedBackend || !/[a-z0-9]/.test(normalizedBackend)) {
+        throw new Error("Storage backend id must contain at least one alphanumeric character.");
+    }
+
+    requireCapability("storage", action);
+    requireCapability(`${STORAGE_BACKEND_CAPABILITY_PREFIX}${normalizedBackend}` as PluginCapability, action);
+}
+
 function requireScopedCapability(
     scopeId: string,
     action: string,
@@ -87,7 +197,7 @@ export function createFilesystemCapabilityBundle(scopeId: string): PluginCapabil
     }
 
     return createCapabilityBundle([
-        "system.hosts.write",
+        HOSTS_WRITE_CAPABILITY,
         `${FILESYSTEM_SCOPE_CAPABILITY_PREFIX}${normalizedScope}` as PluginCapability,
     ]);
 }
@@ -108,16 +218,220 @@ export function createWorkflowCapabilityBundle(scopeId: string): PluginCapabilit
     return createProcessCapabilityBundle(scopeId);
 }
 
+export function createStorageCapabilityBundle(backendId: string): PluginCapability[] {
+    const normalizedBackend = normalizeStorageBackendId(backendId);
+    if (!normalizedBackend || !/[a-z0-9]/.test(normalizedBackend)) {
+        throw new Error("Storage backend id must contain at least one alphanumeric character.");
+    }
+
+    return createCapabilityBundle([
+        "storage",
+        `${STORAGE_BACKEND_CAPABILITY_PREFIX}${normalizedBackend}` as PluginCapability,
+    ]);
+}
+
+export function createAICapabilityBundle(
+    options:
+        | Array<"assistants.list" | "request">
+        | { operations?: Array<"assistants.list" | "request"> } = ["request"]
+): PluginCapability[] {
+    const operations = Array.isArray(options)
+        ? options
+        : (Array.isArray(options.operations) ? options.operations : ["request"]);
+    const normalizedOperations = Array.from(
+        new Set((Array.isArray(operations) ? operations : []).map((operation) => String(operation || "").trim().toLowerCase()))
+    );
+
+    if (normalizedOperations.length === 0) {
+        throw new Error("At least one AI capability operation is required.");
+    }
+
+    const capabilities: PluginCapability[] = ["system.ai"];
+    for (const operation of normalizedOperations) {
+        if (!AI_OPERATIONS.has(operation)) {
+            throw new Error(
+                `Unsupported AI capability operation "${operation}". Supported operations: ${Array.from(AI_OPERATIONS).join(", ")}.`
+            );
+        }
+        capabilities.push(`${AI_CAPABILITY_PREFIX}${operation}` as PluginCapability);
+    }
+
+    return createCapabilityBundle(capabilities);
+}
+
+export function createNetworkScopeCapability(scopeId: string): PluginCapability {
+    const normalizedScope = normalizeScopeId(scopeId);
+    if (!normalizedScope || !/[a-z0-9]/.test(normalizedScope)) {
+        throw new Error("Network scope id must contain at least one alphanumeric character.");
+    }
+    return `${NETWORK_SCOPE_CAPABILITY_PREFIX}${normalizedScope}` as PluginCapability;
+}
+
+export function createNetworkCapabilityBundle(
+    options:
+        | Array<"https" | "http" | "websocket" | "tcp" | "udp" | "dns">
+        | {
+            transports?: Array<"https" | "http" | "websocket" | "tcp" | "udp" | "dns">;
+            scopeId?: string;
+        } = ["https"]
+): PluginCapability[] {
+    const transports = Array.isArray(options)
+        ? options
+        : (Array.isArray(options.transports) ? options.transports : ["https"]);
+    const scopeId = Array.isArray(options) ? undefined : options.scopeId;
+    const normalizedTransports = Array.from(
+        new Set((Array.isArray(transports) ? transports : []).map((transport) => normalizeNetworkTransportId(transport)))
+    );
+
+    if (normalizedTransports.length === 0) {
+        throw new Error("At least one network transport capability is required.");
+    }
+
+    const capabilities: PluginCapability[] = ["system.network"];
+    for (const transport of normalizedTransports) {
+        if (!NETWORK_TRANSPORTS.has(transport)) {
+            throw new Error(
+                `Unsupported network transport capability "${transport}". Supported transports: ${Array.from(NETWORK_TRANSPORTS).join(", ")}.`
+            );
+        }
+        capabilities.push(`${NETWORK_CAPABILITY_PREFIX}${transport}` as PluginCapability);
+    }
+    if (typeof scopeId === "string" && scopeId.trim()) {
+        capabilities.push(createNetworkScopeCapability(scopeId));
+    }
+
+    return createCapabilityBundle(capabilities);
+}
+
 export function describeCapability(capability: PluginCapability | string): CapabilityDescriptor {
+    if (capability === "system.ai") {
+        return {
+            capability,
+            label: "AI",
+            description: "Base AI capability family for host-routed assistants.",
+            category: "ai",
+        };
+    }
+
+    if (capability === "system.ai.assistants.list") {
+        return {
+            capability,
+            label: "AI Assistants List",
+            description: "Allows the plugin to discover host-configured AI assistants for user selection/routing.",
+            category: "ai",
+        };
+    }
+
+    if (capability === "system.ai.request") {
+        return {
+            capability,
+            label: "AI Request",
+            description: "Allows the plugin to send task-oriented AI requests through host-selected assistants.",
+            category: "ai",
+        };
+    }
+
+    if (capability === "storage") {
+        return {
+            capability,
+            label: "Storage",
+            description: "Base capability family for plugin-managed persistent storage backends.",
+            category: "storage",
+        };
+    }
+
     if (capability === "storage.json") {
         return {
             capability,
-            label: "JSON Storage",
-            description: "Allows the plugin to use the persistent JSON store.",
+            label: "JSON Storage Backend",
+            description: "Allows the plugin to use the persistent JSON store backend (requires base capability \"storage\").",
+            category: "storage",
+        };
+    }
+
+    if (capability.startsWith(STORAGE_BACKEND_CAPABILITY_PREFIX)) {
+        const backendId = capability.slice(STORAGE_BACKEND_CAPABILITY_PREFIX.length);
+        return {
+            capability,
+            label: `Storage Backend: ${backendId}`,
+            description: `Allows the plugin to use the "${backendId}" persistent storage backend (requires base capability "storage").`,
             category: "storage",
         };
     }
 
+    if (capability === "system.network") {
+        return {
+            capability,
+            label: "Network",
+            description: "Base network capability family. Pair with concrete transport capabilities such as system.network.https.",
+            category: "network",
+        };
+    }
+
+    if (capability === "system.network.https") {
+        return {
+            capability,
+            label: "Network HTTPS",
+            description: "Allows outbound HTTPS requests through host-approved runtime network APIs.",
+            category: "network",
+        };
+    }
+
+    if (capability === "system.network.http") {
+        return {
+            capability,
+            label: "Network HTTP",
+            description: "Allows outbound plaintext HTTP requests through host-approved runtime network APIs.",
+            category: "network",
+        };
+    }
+
+    if (capability === "system.network.websocket") {
+        return {
+            capability,
+            label: "Network WebSocket",
+            description: "Allows outbound WebSocket connections through host-approved runtime network APIs.",
+            category: "network",
+        };
+    }
+
+    if (capability === "system.network.tcp") {
+        return {
+            capability,
+            label: "Network TCP",
+            description: "Allows raw TCP socket access through runtime network APIs.",
+            category: "network",
+        };
+    }
+
+    if (capability === "system.network.udp") {
+        return {
+            capability,
+            label: "Network UDP",
+            description: "Allows raw UDP socket access through runtime network APIs.",
+            category: "network",
+        };
+    }
+
+    if (capability === "system.network.dns") {
+        return {
+            capability,
+            label: "Network DNS",
+            description: "Allows direct DNS resolution APIs through runtime network modules.",
+            category: "network",
+        };
+    }
+
+    if (capability.startsWith(NETWORK_SCOPE_CAPABILITY_PREFIX)) {
+        const scopeId = capability.slice(NETWORK_SCOPE_CAPABILITY_PREFIX.length);
+        return {
+            capability,
+            label: `Network Scope: ${scopeId}`,
+            description: `Allows host-defined network scope access inside "${scopeId}". Pair with system.network and required transport capabilities.`,
+            category: "network-scope",
+        };
+    }
+
     if (capability === "sudo.prompt") {
         return {
             capability,
@@ -145,7 +459,7 @@ export function describeCapability(capability: PluginCapability | string): Capab
         };
     }
 
-    if (capability === "system.hosts.write") {
+    if (capability === HOSTS_WRITE_CAPABILITY || capability === HOST_WRITE_CAPABILITY) {
         return {
             capability,
             label: "Hosts Write",
@@ -207,7 +521,69 @@ export function parseMissingCapabilityError(error: unknown): MissingCapabilityDi
         category: descriptor.category,
         label: descriptor.label,
         description: descriptor.description,
-        remediation: `Grant "${capability}" in the host capability configuration before plugin initialization.`,
+        remediation: buildCapabilityPreflightRemediation(capability),
+    };
+}
+
+export function runCapabilityPreflight(options: {
+    declared: Array<PluginCapability | string>;
+    granted?: Array<PluginCapability | string>;
+    action?: string;
+}): CapabilityPreflightReport {
+    const action = typeof options.action === "string" && options.action.trim()
+        ? options.action.trim()
+        : "satisfy plugin declared capability preflight";
+    const declared = normalizeCapabilityList(Array.isArray(options.declared) ? options.declared : []);
+    const granted = normalizeCapabilityList(
+        Array.isArray(options.granted)
+            ? options.granted
+            : getCapabilityDiagnostics().granted
+    );
+    const declaredSet = new Set(declared);
+    const grantedSet = new Set(granted);
+
+    const missing: CapabilityPreflightMissingDiagnostic[] = declared
+        .filter((capability) => !grantedSet.has(capability))
+        .map((capability) => {
+            const descriptor = describeCapability(capability);
+            const prerequisites = getCapabilityPrerequisites(capability);
+            const requiredCapabilities = normalizeCapabilityList([capability, ...prerequisites]);
+            const missingPrerequisites = prerequisites.filter((entry) => !grantedSet.has(entry));
+            const grantedPrerequisites = prerequisites.filter((entry) => grantedSet.has(entry));
+
+            return {
+                capability,
+                action,
+                category: descriptor.category,
+                label: descriptor.label,
+                description: descriptor.description,
+                remediation: buildCapabilityPreflightRemediation(capability),
+                requiredCapabilities,
+                missingPrerequisites,
+                grantedPrerequisites,
+            };
+        });
+
+    const undeclaredGranted = granted
+        .filter((capability) => !declaredSet.has(capability))
+        .map((capability) => describeCapability(capability));
+
+    const remediations = Array.from(
+        new Set(missing.map((entry) => entry.remediation))
+    );
+    const summary = missing.length === 0
+        ? "All declared capabilities are granted."
+        : `Missing ${missing.length} declared capability${missing.length === 1 ? "" : "ies"} (${missing.map((entry) => entry.capability).join(", ")}).`;
+
+    return {
+        ok: missing.length === 0,
+        action,
+        declared,
+        granted,
+        missing,
+        undeclaredGranted,
+        remediations,
+        summary,
     };
 }
 
diff --git a/src/utils/contracts.ts b/src/utils/contracts.ts
index 6170624..e269b70 100644
--- a/src/utils/contracts.ts
+++ b/src/utils/contracts.ts
@@ -25,13 +25,26 @@ export interface PluginInitPayload {
 }
 
 const KNOWN_PLUGIN_CAPABILITIES = new Set<PluginCapability>([
+    "system.ai",
+    "system.ai.assistants.list",
+    "system.ai.request",
+    "storage",
     "storage.json",
+    "system.network",
+    "system.network.https",
+    "system.network.http",
+    "system.network.websocket",
+    "system.network.tcp",
+    "system.network.udp",
+    "system.network.dns",
     "sudo.prompt",
     "system.clipboard.read",
     "system.clipboard.write",
+    "system.host.write",
     "system.hosts.write",
     "system.process.exec",
 ]);
+const STORAGE_BACKEND_CAPABILITY_PREFIX = "storage.";
 const HOST_PRIVILEGED_ACTION_SYSTEM_CLIPBOARD_READ = "system.clipboard.read";
 const HOST_PRIVILEGED_ACTION_SYSTEM_CLIPBOARD_WRITE = "system.clipboard.write";
 const HOST_PRIVILEGED_ACTION_SYSTEM_HOSTS_WRITE = "system.hosts.write";
@@ -40,6 +53,7 @@ const HOST_PRIVILEGED_ACTION_SYSTEM_PROCESS_EXEC = "system.process.exec";
 const HOST_PRIVILEGED_ACTION_SYSTEM_WORKFLOW_RUN = "system.workflow.run";
 const FS_SCOPE_CAPABILITY_PREFIX = "system.fs.scope.";
 const PROCESS_SCOPE_CAPABILITY_PREFIX = "system.process.scope.";
+const NETWORK_SCOPE_CAPABILITY_PREFIX = "system.network.scope.";
 const WORKFLOW_KINDS = new Set(["process-sequence"]);
 const WORKFLOW_STEP_PHASES = new Set(["inspect", "preview", "mutate", "apply", "cleanup"]);
 const WORKFLOW_STEP_ERROR_BEHAVIORS = new Set(["abort", "continue"]);
@@ -223,8 +237,16 @@ export function validatePluginInitPayload(payload: unknown): PluginInitPayload {
         for (const capability of payload.capabilities) {
             if (
                 !KNOWN_PLUGIN_CAPABILITIES.has(capability as PluginCapability)
+                && !(
+                    capability.startsWith(STORAGE_BACKEND_CAPABILITY_PREFIX)
+                    && isValidScopeId(capability.slice(STORAGE_BACKEND_CAPABILITY_PREFIX.length))
+                )
                 && !capability.startsWith(FS_SCOPE_CAPABILITY_PREFIX)
                 && !capability.startsWith(PROCESS_SCOPE_CAPABILITY_PREFIX)
+                && !(
+                    capability.startsWith(NETWORK_SCOPE_CAPABILITY_PREFIX)
+                    && isValidScopeId(capability.slice(NETWORK_SCOPE_CAPABILITY_PREFIX.length))
+                )
             ) {
                 throw new Error(`Plugin init payload capability "${capability}" is not supported by this SDK version.`);
             }
diff --git a/src/utils/diagnosticTemplates.ts b/src/utils/diagnosticTemplates.ts
new file mode 100644
index 0000000..f76bd23
--- /dev/null
+++ b/src/utils/diagnosticTemplates.ts
@@ -0,0 +1,157 @@
+import { DiagnosticFixTemplate } from "../types";
+
+const FIX_TEMPLATES: Record<string, DiagnosticFixTemplate> = Object.freeze({
+    CAPABILITY_MISSING: {
+        code: "CAPABILITY_MISSING",
+        title: "Missing capability grant",
+        summary: "Host policy denied a required capability.",
+        exactFix: "Grant the required capability (and prerequisites) in PLUGIN_INIT.content.capabilities before plugin init.",
+        steps: [
+            "Identify the denied capability from the error response code/message.",
+            "Add that capability to host grant policy for the plugin.",
+            "If it is a scoped capability (for example system.process.scope.git), also grant required broad capability (for example system.process.exec).",
+            "Reinitialize the plugin and re-run the action.",
+        ],
+        docs: [
+            "docs/SAFE_PLUGIN_AUTHORING.md",
+            "docs/OPERATOR_PLUGIN_PATTERNS.md",
+        ],
+    },
+    PROCESS_SPAWN_ENOENT: {
+        code: "PROCESS_SPAWN_ENOENT",
+        title: "Process executable/spawn path issue",
+        summary: "Host process execution failed before command run.",
+        exactFix: "Validate executable allowlist path and command cwd; if cwd is invalid/missing, fix path selection before process execution.",
+        steps: [
+            "Confirm the executable exists on the host and is in the allowed scope policy.",
+            "Validate cwd path exists (missing cwd can surface as ENOENT).",
+            "Use host-managed scoped process execution and avoid hardcoded non-portable binary paths.",
+            "Retry with corrected path/cwd and review stderr/exit diagnostics.",
+        ],
+        docs: [
+            "docs/PLUGIN_DEVELOPMENT_GAP_REGISTER.md",
+            "docs/OPERATOR_PLUGIN_PATTERNS.md",
+        ],
+    },
+    PROCESS_EXIT_NON_ZERO: {
+        code: "PROCESS_EXIT_NON_ZERO",
+        title: "Process command failed",
+        summary: "Command ran but exited with non-zero status.",
+        exactFix: "Surface full host diagnostics (stderr/stdout/exitCode/command/cwd) and fix command arguments or environment.",
+        steps: [
+            "Display formatted error via formatPrivilegedActionError(...).",
+            "Inspect stderr and exitCode to identify command-level failure reason.",
+            "Validate command args/cwd/environment in backend request builder.",
+            "Add pre-checks for predictable failures (missing repo path, missing config, etc.).",
+        ],
+        docs: [
+            "docs/HOST_PRIVILEGED_ACTIONS_CONTRACT.md",
+            "docs/PLUGIN_DEVELOPMENT_GAP_REGISTER.md",
+        ],
+    },
+    PLUGIN_BACKEND_EMPTY_RESPONSE: {
+        code: "PLUGIN_BACKEND_EMPTY_RESPONSE",
+        title: "Backend handler returned no response",
+        summary: "Host received no envelope from plugin handler.",
+        exactFix: "Ensure every handler path returns a response envelope, including error branches.",
+        steps: [
+            "Verify handler is registered before UI_MESSAGE invocation.",
+            "Return explicit envelope on success and failure code paths.",
+            "Do not swallow exceptions without returning fallback response.",
+            "Use SDK helper builders when constructing privileged-action envelopes.",
+        ],
+        docs: [
+            "docs/SAFE_PLUGIN_AUTHORING.md",
+            "docs/PLUGIN_DEVELOPMENT_GAP_REGISTER.md",
+        ],
+    },
+    HANDSHAKE_API_INCOMPATIBLE: {
+        code: "HANDSHAKE_API_INCOMPATIBLE",
+        title: "SDK/Host API major mismatch",
+        summary: "Plugin SDK API major version is incompatible with host expectation.",
+        exactFix: "Align plugin SDK major version with host-supported API major before loading plugin.",
+        steps: [
+            "Compare diagnostics.handshake.apiVersion with host expected API major.",
+            "Upgrade plugin SDK or host runtime to matching major.",
+            "Rebuild plugin after SDK version alignment.",
+        ],
+        docs: [
+            "docs/ARCHITECTURE.md",
+            "docs/API_STABILITY.md",
+        ],
+    },
+    HANDSHAKE_CONTRACT_INCOMPATIBLE: {
+        code: "HANDSHAKE_CONTRACT_INCOMPATIBLE",
+        title: "SDK/Host handshake contract mismatch",
+        summary: "Plugin SDK handshake contract major version is incompatible with host expectation.",
+        exactFix: "Align host handshake contract expectation with the plugin SDK handshake major version before plugin load.",
+        steps: [
+            "Compare diagnostics.handshake.contractVersion with host-expected handshake contract major.",
+            "Upgrade host or plugin SDK so handshake contract majors match.",
+            "Re-run plugin diagnostics and compatibility checks after alignment.",
+        ],
+        docs: [
+            "docs/ARCHITECTURE.md",
+            "docs/API_STABILITY.md",
+        ],
+    },
+    HANDSHAKE_CAPABILITY_SCHEMA_MISMATCH: {
+        code: "HANDSHAKE_CAPABILITY_SCHEMA_MISMATCH",
+        title: "Capability schema version mismatch",
+        summary: "Host and SDK capability schema versions differ.",
+        exactFix: "Update host capability-schema mapping or SDK to a compatible schema version.",
+        steps: [
+            "Read diagnostics.handshake.capabilitySchemaVersion.",
+            "Compare with host capability schema expectation.",
+            "Add compatibility shim or update host/SDK so schema versions align.",
+        ],
+        docs: [
+            "docs/ARCHITECTURE.md",
+            "docs/SAFE_PLUGIN_AUTHORING.md",
+        ],
+    },
+    HANDSHAKE_FEATURE_FLAG_MISSING: {
+        code: "HANDSHAKE_FEATURE_FLAG_MISSING",
+        title: "Required SDK feature flag not available",
+        summary: "Host requested a capability path not advertised by plugin SDK feature flags.",
+        exactFix: "Gate host UX by handshake.featureFlags or upgrade SDK that implements the required feature.",
+        steps: [
+            "Inspect diagnostics.handshake.featureFlags in host diagnostics.",
+            "Disable or fallback unsupported host feature path.",
+            "Upgrade plugin SDK version to include required feature flag.",
+        ],
+        docs: [
+            "README.md",
+            "docs/ARCHITECTURE.md",
+        ],
+    },
+});
+
+function normalizeCode(code: string): string {
+    return String(code || "").trim().toUpperCase();
+}
+
+export function getDiagnosticFixTemplate(code: string): DiagnosticFixTemplate | null {
+    const normalized = normalizeCode(code);
+    if (!normalized) {
+        return null;
+    }
+
+    const template = FIX_TEMPLATES[normalized];
+    return template ? { ...template, steps: [...template.steps], docs: template.docs ? [...template.docs] : undefined } : null;
+}
+
+export function listDiagnosticFixTemplates(): DiagnosticFixTemplate[] {
+    return Object.keys(FIX_TEMPLATES)
+        .sort((left, right) => left.localeCompare(right))
+        .map((code) => getDiagnosticFixTemplate(code) as DiagnosticFixTemplate);
+}
+
+export function formatDiagnosticExactFix(code: string): string | null {
+    const template = getDiagnosticFixTemplate(code);
+    if (!template) {
+        return null;
+    }
+
+    return `${template.title}: ${template.exactFix}`;
+}
diff --git a/src/utils/editorSupport.ts b/src/utils/editorSupport.ts
new file mode 100644
index 0000000..7f13b2e
--- /dev/null
+++ b/src/utils/editorSupport.ts
@@ -0,0 +1,126 @@
+import { RenderOnLoadHint } from "../types";
+import { getRenderOnLoadMonacoHints, getRenderOnLoadMonacoTypeDefinitions } from "./renderOnLoad";
+
+export const SDK_EDITOR_MODULE_ID = "@anikitenko/fdo-sdk";
+export const SDK_EDITOR_PACKAGE_JSON_VIRTUAL_PATH = `/node_modules/${SDK_EDITOR_MODULE_ID}/package.json`;
+export const SDK_EDITOR_INDEX_TYPES_VIRTUAL_PATH = `/node_modules/${SDK_EDITOR_MODULE_ID}/index.d.ts`;
+
+export type EditorSupportPackageManifest = {
+    name: string;
+    private: boolean;
+    types: string;
+    exports: {
+        ".": {
+            types: string;
+            default: string;
+        };
+    };
+};
+
+export type EditorSupportBundle = {
+    moduleId: string;
+    packageManifest: EditorSupportPackageManifest;
+    packageJson: string;
+    renderOnLoadTypeDefinitions: string;
+    renderOnLoadHints: RenderOnLoadHint[];
+};
+
+export type EditorSupportMonacoPolicyOptions = {
+    hasSdkIndex: boolean;
+    namespaceFallbackTypeDefinitions?: string;
+};
+
+export type EditorSupportMonacoPolicy = {
+    moduleId: string;
+    hasSdkIndex: boolean;
+    shouldInjectPackageJson: boolean;
+    packageJsonVirtualPath: string;
+    packageJson: string;
+    indexTypesVirtualPath: string;
+    namespaceFallbackTypeDefinitions: string;
+    preferNamespaceFallback: true;
+    allowModuleFallback: false;
+    deprecatedModuleFallbackPattern: string;
+    guidance: string[];
+};
+
+const DEFAULT_EDITOR_SUPPORT_PACKAGE_MANIFEST: EditorSupportPackageManifest = {
+    name: SDK_EDITOR_MODULE_ID,
+    private: true,
+    types: "./index.d.ts",
+    exports: {
+        ".": {
+            types: "./index.d.ts",
+            default: "./dist/fdo-sdk.bundle.js",
+        },
+    },
+};
+
+export function getEditorSupportPackageManifest(
+    overrides: Partial<EditorSupportPackageManifest> = {}
+): EditorSupportPackageManifest {
+    return {
+        name: overrides.name ?? DEFAULT_EDITOR_SUPPORT_PACKAGE_MANIFEST.name,
+        private:
+            typeof overrides.private === "boolean"
+                ? overrides.private
+                : DEFAULT_EDITOR_SUPPORT_PACKAGE_MANIFEST.private,
+        types: overrides.types ?? DEFAULT_EDITOR_SUPPORT_PACKAGE_MANIFEST.types,
+        exports: {
+            ".": {
+                types:
+                    overrides.exports?.["."]?.types
+                    ?? DEFAULT_EDITOR_SUPPORT_PACKAGE_MANIFEST.exports["."].types,
+                default:
+                    overrides.exports?.["."]?.default
+                    ?? DEFAULT_EDITOR_SUPPORT_PACKAGE_MANIFEST.exports["."].default,
+            },
+        },
+    };
+}
+
+export function getEditorSupportPackageJson(
+    manifest: EditorSupportPackageManifest = getEditorSupportPackageManifest()
+): string {
+    return JSON.stringify(manifest, null, 2);
+}
+
+export function getEditorSupportBundle(): EditorSupportBundle {
+    const packageManifest = getEditorSupportPackageManifest();
+    return {
+        moduleId: SDK_EDITOR_MODULE_ID,
+        packageManifest,
+        packageJson: getEditorSupportPackageJson(packageManifest),
+        renderOnLoadTypeDefinitions: getRenderOnLoadMonacoTypeDefinitions(),
+        renderOnLoadHints: getRenderOnLoadMonacoHints(),
+    };
+}
+
+export function getEditorSupportMonacoPolicy(
+    options: EditorSupportMonacoPolicyOptions
+): EditorSupportMonacoPolicy {
+    const hasSdkIndex = options.hasSdkIndex === true;
+    const packageManifest = getEditorSupportPackageManifest();
+    const packageJson = getEditorSupportPackageJson(packageManifest);
+    const namespaceFallbackTypeDefinitions =
+        options.namespaceFallbackTypeDefinitions
+        ?? getRenderOnLoadMonacoTypeDefinitions();
+
+    return {
+        moduleId: SDK_EDITOR_MODULE_ID,
+        hasSdkIndex,
+        shouldInjectPackageJson: hasSdkIndex,
+        packageJsonVirtualPath: SDK_EDITOR_PACKAGE_JSON_VIRTUAL_PATH,
+        packageJson,
+        indexTypesVirtualPath: SDK_EDITOR_INDEX_TYPES_VIRTUAL_PATH,
+        namespaceFallbackTypeDefinitions,
+        preferNamespaceFallback: true,
+        allowModuleFallback: false,
+        deprecatedModuleFallbackPattern: `declare module "${SDK_EDITOR_MODULE_ID}"`,
+        guidance: [
+            "Use hasSdkIndex to decide editor fallback behavior.",
+            "Inject virtual package.json only when SDK index.d.ts is present.",
+            "Use namespace-only fallback for renderOnLoad typings; do not reintroduce module-level declare module fallback.",
+        ],
+    };
+}
diff --git a/src/utils/fixtureRuntimeMatrix.ts b/src/utils/fixtureRuntimeMatrix.ts
new file mode 100644
index 0000000..ceb4da5
--- /dev/null
+++ b/src/utils/fixtureRuntimeMatrix.ts
@@ -0,0 +1,183 @@
+import {
+    FixtureRuntimeMatrix,
+    FixtureRuntimeMatrixCase,
+    FixtureRuntimeUiMessageProbe,
+} from "../types";
+
+const FIXTURE_RUNTIME_MATRIX_CONTRACT_VERSION: FixtureRuntimeMatrix["contractVersion"] = "1";
+
+const FIXTURE_RUNTIME_MATRIX_CASES: ReadonlyArray<FixtureRuntimeMatrixCase> = [
+    {
+        id: "minimal",
+        title: "Fixture: Minimal Plugin",
+        fixturePath: "examples/fixtures/minimal-plugin.fixture.ts",
+        description: "Baseline lifecycle smoke without UI bridge handlers.",
+        probes: {
+            init: true,
+            render: true,
+            renderOnLoad: false,
+            uiMessage: [],
+        },
+    },
+    {
+        id: "error-handling",
+        title: "Fixture: Error Handling",
+        fixturePath: "examples/fixtures/error-handling-plugin.fixture.ts",
+        description: "Lifecycle + handler safety with deterministic UI_MESSAGE success/failure probes.",
+        probes: {
+            init: true,
+            render: true,
+            renderOnLoad: true,
+            uiMessage: [
+                {
+                    handler: "fixture.ok",
+                    content: { source: "fixture-ui" },
+                    description: "Success handler probe.",
+                },
+                {
+                    handler: "fixture.fail",
+                    content: {},
+                    description: "Failure handler probe.",
+                },
+            ],
+        },
+    },
+    {
+        id: "storage",
+        title: "Fixture: Storage",
+        fixturePath: "examples/fixtures/storage-plugin.fixture.ts",
+        description: "Store initialization, fallback behavior, and storage-focused UI_MESSAGE probes.",
+        probes: {
+            init: true,
+            render: true,
+            renderOnLoad: true,
+            uiMessage: [
+                {
+                    handler: "storageFixture.v2.getSnapshot",
+                    content: {},
+                },
+                {
+                    handler: "storageFixture.v2.savePreference",
+                    content: { theme: "dark" },
+                },
+                {
+                    handler: "storageFixture.v2.recordAction",
+                    content: { action: "storage-fixture-ui-click" },
+                },
+            ],
+        },
+        requiredCapabilities: ["storage", "storage.json"],
+    },
+    {
+        id: "operator-kubernetes",
+        title: "Fixture: Kubernetes Operator",
+        fixturePath: "examples/fixtures/operator-kubernetes-plugin.fixture.ts",
+        description: "Curated kubectl preset envelope probes for single-action + workflow paths.",
+        probes: {
+            init: true,
+            render: true,
+            renderOnLoad: true,
+            uiMessage: [
+                {
+                    handler: "kubectlFixture.v2.previewClusterObjects",
+                    content: {},
+                },
+                {
+                    handler: "kubectlFixture.v2.inspectAndRestartWorkflow",
+                    content: {},
+                },
+            ],
+        },
+        requiredCapabilities: ["system.process.exec", "system.process.scope.kubectl"],
+    },
+    {
+        id: "operator-terraform",
+        title: "Fixture: Terraform Operator",
+        fixturePath: "examples/fixtures/operator-terraform-plugin.fixture.ts",
+        description: "Curated terraform preset envelope probes for plan + preview/apply workflow paths.",
+        probes: {
+            init: true,
+            render: true,
+            renderOnLoad: true,
+            uiMessage: [
+                {
+                    handler: "terraformFixture.v2.previewPlan",
+                    content: {},
+                },
+                {
+                    handler: "terraformFixture.v2.previewApplyWorkflow",
+                    content: {},
+                },
+            ],
+        },
+        requiredCapabilities: ["system.process.exec", "system.process.scope.terraform"],
+    },
+    {
+        id: "operator-custom-tool",
+        title: "Fixture: Custom Operator Tool",
+        fixturePath: "examples/fixtures/operator-custom-tool-plugin.fixture.ts",
+        description: "Custom scoped process envelope probe for host-specific internal tools.",
+        probes: {
+            init: true,
+            render: true,
+            renderOnLoad: true,
+            uiMessage: [
+                {
+                    handler: "customToolFixture.v2.previewRunnerStatus",
+                    content: {},
+                },
+            ],
+        },
+        requiredCapabilities: ["system.process.exec", "system.process.scope.internal-runner"],
+    },
+];
+
+function cloneUiMessageProbe(probe: FixtureRuntimeUiMessageProbe): FixtureRuntimeUiMessageProbe {
+    return {
+        handler: probe.handler,
+        description: probe.description,
+        content: cloneRecord(probe.content),
+    };
+}
+
+function cloneRecord(record?: Record<string, unknown>): Record<string, unknown> | undefined {
+    if (!record) {
+        return undefined;
+    }
+    return JSON.parse(JSON.stringify(record)) as Record<string, unknown>;
+}
+
+function cloneMatrixCase(entry: FixtureRuntimeMatrixCase): FixtureRuntimeMatrixCase {
+    return {
+        id: entry.id,
+        title: entry.title,
+        fixturePath: entry.fixturePath,
+        description: entry.description,
+        probes: {
+            init: true,
+            render: true,
+            renderOnLoad: entry.probes.renderOnLoad,
+            uiMessage: entry.probes.uiMessage.map((probe) => cloneUiMessageProbe(probe)),
+        },
+        requiredCapabilities: entry.requiredCapabilities ? [...entry.requiredCapabilities] : undefined,
+    };
+}
+
+export function listFixtureRuntimeMatrixCases(): FixtureRuntimeMatrixCase[] {
+    return FIXTURE_RUNTIME_MATRIX_CASES.map((entry) => cloneMatrixCase(entry));
+}
+
+export function getFixtureRuntimeMatrixCase(id: string): FixtureRuntimeMatrixCase | null {
+    const entry = FIXTURE_RUNTIME_MATRIX_CASES.find((candidate) => candidate.id === id);
+    if (!entry) {
+        return null;
+    }
+    return cloneMatrixCase(entry);
+}
+
+export function getFixtureRuntimeMatrix(): FixtureRuntimeMatrix {
+    return {
+        contractVersion: FIXTURE_RUNTIME_MATRIX_CONTRACT_VERSION,
+        cases: listFixtureRuntimeMatrixCases(),
+    };
+}
diff --git a/src/utils/handshake.ts b/src/utils/handshake.ts
new file mode 100644
index 0000000..11a7af5
--- /dev/null
+++ b/src/utils/handshake.ts
@@ -0,0 +1,169 @@
+import {
+    SdkFeatureFlags,
+    SdkHandshake,
+    SdkHandshakeCompatibilityIssue,
+    SdkHandshakeCompatibilityOptions,
+    SdkHandshakeCompatibilityReport,
+    SdkHandshakeFeatureFlagName,
+} from "../types";
+import { SDK_API_VERSION, SDK_PACKAGE_VERSION } from "../version";
+
+const SDK_HANDSHAKE_CONTRACT_VERSION = "1.0.0";
+const SDK_CAPABILITY_SCHEMA_VERSION = "1.0.0";
+
+const SDK_FEATURE_FLAGS: SdkFeatureFlags = Object.freeze({
+    diagnosticsHandler: true,
+    pluginDoctorReport: true,
+    declaredCapabilityPreflight: true,
+    privilegedActionTransportPipeline: true,
+    renderOnLoadModuleAuthoring: true,
+    renderOnLoadDeclarativeActions: true,
+    editorSupportBundle: true,
+});
+
+export function getSdkFeatureFlags(): SdkFeatureFlags {
+    return { ...SDK_FEATURE_FLAGS };
+}
+
+export function getSdkHandshake(): SdkHandshake {
+    return {
+        contractVersion: SDK_HANDSHAKE_CONTRACT_VERSION,
+        sdkVersion: SDK_PACKAGE_VERSION,
+        apiVersion: SDK_API_VERSION,
+        capabilitySchemaVersion: SDK_CAPABILITY_SCHEMA_VERSION,
+        featureFlags: getSdkFeatureFlags(),
+    };
+}
+
+function parseMajor(version: string | undefined): number | null {
+    const value = String(version ?? "").trim();
+    if (!value) {
+        return null;
+    }
+
+    const match = value.match(/^(\d+)/u);
+    if (!match) {
+        return null;
+    }
+
+    const major = Number.parseInt(match[1], 10);
+    return Number.isFinite(major) ? major : null;
+}
+
+function createSummary(issues: SdkHandshakeCompatibilityIssue[]): string {
+    const errorCount = issues.filter((issue) => issue.severity === "error").length;
+    const warningCount = issues.filter((issue) => issue.severity === "warning").length;
+
+    if (errorCount === 0 && warningCount === 0) {
+        return "SDK handshake is compatible with host expectations.";
+    }
+
+    const parts = [
+        `${errorCount} error${errorCount === 1 ? "" : "s"}`,
+        `${warningCount} warning${warningCount === 1 ? "" : "s"}`,
+    ];
+    return `SDK handshake compatibility check found ${parts.join(" and ")}.`;
+}
+
+function toStatus(issues: SdkHandshakeCompatibilityIssue[]): SdkHandshakeCompatibilityReport["status"] {
+    if (issues.some((issue) => issue.severity === "error")) {
+        return "incompatible";
+    }
+    if (issues.some((issue) => issue.severity === "warning")) {
+        return "needs-attention";
+    }
+    return "compatible";
+}
+
+function requiredFlags(options: SdkHandshakeCompatibilityOptions): SdkHandshakeFeatureFlagName[] {
+    return Array.from(new Set(options.requiredFeatureFlags ?? []));
+}
+
+export function evaluateSdkHandshakeCompatibility(
+    handshake: SdkHandshake,
+    options: SdkHandshakeCompatibilityOptions = {}
+): SdkHandshakeCompatibilityReport {
+    const issues: SdkHandshakeCompatibilityIssue[] = [];
+
+    const expectedContractVersion = options.expectedContractVersion;
+    if (expectedContractVersion) {
+        const expectedMajor = parseMajor(expectedContractVersion);
+        const receivedMajor = parseMajor(handshake.contractVersion);
+
+        if (expectedMajor === null || receivedMajor === null || expectedMajor !== receivedMajor) {
+            issues.push({
+                code: "HANDSHAKE_CONTRACT_INCOMPATIBLE",
+                severity: "error",
+                message: "SDK handshake contract major version is incompatible with host expectation.",
+                expected: expectedContractVersion,
+                received: handshake.contractVersion,
+            });
+        }
+    }
+
+    const expectedApiVersion = options.expectedApiVersion;
+    if (expectedApiVersion) {
+        const expectedMajor = parseMajor(expectedApiVersion);
+        const receivedMajor = parseMajor(handshake.apiVersion);
+
+        if (expectedMajor === null || receivedMajor === null || expectedMajor !== receivedMajor) {
+            issues.push({
+                code: "HANDSHAKE_API_INCOMPATIBLE",
+                severity: "error",
+                message: "SDK API major version is incompatible with host expectation.",
+                expected: expectedApiVersion,
+                received: handshake.apiVersion,
+            });
+        }
+    }
+
+    const expectedCapabilitySchemaVersion = options.expectedCapabilitySchemaVersion;
+    if (
+        expectedCapabilitySchemaVersion
+        && handshake.capabilitySchemaVersion !== expectedCapabilitySchemaVersion
+    ) {
+        issues.push({
+            code: "HANDSHAKE_CAPABILITY_SCHEMA_MISMATCH",
+            severity: options.capabilitySchemaSeverity ?? "warning",
+            message: "SDK capability schema version does not match host expectation.",
+            expected: expectedCapabilitySchemaVersion,
+            received: handshake.capabilitySchemaVersion,
+        });
+    }
+
+    const featureFlagSeverity = options.featureFlagSeverity ?? "warning";
+    for (const featureFlag of requiredFlags(options)) {
+        if (handshake.featureFlags[featureFlag] !== true) {
+            issues.push({
+                code: "HANDSHAKE_FEATURE_FLAG_MISSING",
+                severity: featureFlagSeverity,
+                message: `Required SDK feature flag "${featureFlag}" is not enabled.`,
+                expected: "true",
+                received: String(handshake.featureFlags[featureFlag]),
+                featureFlag,
+            });
+        }
+    }
+
+    const status = toStatus(issues);
+    const report: SdkHandshakeCompatibilityReport = {
+        ok: status !== "incompatible",
+        status,
+        handshake,
+        counts: {
+            error: issues.filter((issue) => issue.severity === "error").length,
+            warning: issues.filter((issue) => issue.severity === "warning").length,
+        },
+        issues,
+        summary: createSummary(issues),
+    };
+
+    return report;
+}
+
+export function isSdkHandshakeCompatible(
+    handshake: SdkHandshake,
+    options: SdkHandshakeCompatibilityOptions = {}
+): boolean {
+    return evaluateSdkHandshakeCompatibility(handshake, options).ok;
+}
diff --git a/src/utils/migrationCodemod.ts b/src/utils/migrationCodemod.ts
new file mode 100644
index 0000000..aed78ed
--- /dev/null
+++ b/src/utils/migrationCodemod.ts
@@ -0,0 +1,133 @@
+export type SdkMigrationRuleId =
+    | "privileged-envelope-extract-helper"
+    | "plugin-registry-configure-capabilities";
+
+export type SdkMigrationChange = {
+    rule: SdkMigrationRuleId;
+    replacements: number;
+    description: string;
+};
+
+export type SdkMigrationResult = {
+    output: string;
+    changed: boolean;
+    changes: SdkMigrationChange[];
+};
+
+const SDK_IMPORT_MODULE = "@anikitenko/fdo-sdk";
+const EXTRACT_PRIVILEGED_ACTION_REQUEST = "extractPrivilegedActionRequest";
+
+function hasNamedImport(importList: string, importName: string): boolean {
+    return importList
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+        .some((entry) => entry.split(/\s+as\s+/u)[0].trim() === importName);
+}
+
+function ensureNamedImport(source: string, importName: string): { output: string; changed: boolean } {
+    const namedImportPattern = /import\s*\{([\s\S]*?)\}\s*from\s*["']@anikitenko\/fdo-sdk["'];?/u;
+    const namedImportMatch = source.match(namedImportPattern);
+
+    if (namedImportMatch) {
+        const existingNames = namedImportMatch[1] ?? "";
+        if (hasNamedImport(existingNames, importName)) {
+            return { output: source, changed: false };
+        }
+
+        const imports = existingNames
+            .split(",")
+            .map((entry) => entry.trim())
+            .filter(Boolean);
+        imports.push(importName);
+
+        const replacement = `import { ${imports.join(", ")} } from "${SDK_IMPORT_MODULE}";`;
+        const output = source.replace(namedImportPattern, replacement);
+        return { output, changed: true };
+    }
+
+    const importLine = `import { ${importName} } from "${SDK_IMPORT_MODULE}";`;
+    const lines = source.split("\n");
+    let lastImportIndex = -1;
+
+    for (let index = 0; index < lines.length; index += 1) {
+        if (/^\s*import\s/u.test(lines[index])) {
+            lastImportIndex = index;
+        }
+    }
+
+    if (lastImportIndex >= 0) {
+        lines.splice(lastImportIndex + 1, 0, importLine);
+        return { output: lines.join("\n"), changed: true };
+    }
+
+    return { output: `${importLine}\n${source}`, changed: true };
+}
+
+function applyPrivilegedEnvelopeExtractRule(source: string): {
+    output: string;
+    replacementCount: number;
+    importAdded: boolean;
+} {
+    const pattern = /(\b(?:const|let|var)\s+[A-Za-z_$][\w$]*\s*=\s*)([A-Za-z_$][\w$]*)\s*\?\.\s*result\s*\?\.\s*request\s*\?\?\s*\2\s*\?\.\s*request\s*\?\?\s*\2(\s*;)/gu;
+    let replacementCount = 0;
+
+    const replaced = source.replace(pattern, (_fullMatch, declaration: string, envelopeVar: string, suffix: string) => {
+        replacementCount += 1;
+        return `${declaration}${EXTRACT_PRIVILEGED_ACTION_REQUEST}(${envelopeVar})${suffix}`;
+    });
+
+    if (replacementCount === 0) {
+        return { output: source, replacementCount: 0, importAdded: false };
+    }
+
+    const withImport = ensureNamedImport(replaced, EXTRACT_PRIVILEGED_ACTION_REQUEST);
+    return {
+        output: withImport.output,
+        replacementCount,
+        importAdded: withImport.changed,
+    };
+}
+
+function applyConfigureCapabilitiesRule(source: string): { output: string; replacementCount: number } {
+    const pattern = /\.configureCapabilityPolicy\s*\(/gu;
+    let replacementCount = 0;
+    const output = source.replace(pattern, () => {
+        replacementCount += 1;
+        return ".configureCapabilities(";
+    });
+    return { output, replacementCount };
+}
+
+export function applySdkMigrationCodemod(source: string): SdkMigrationResult {
+    let output = source;
+    const changes: SdkMigrationChange[] = [];
+
+    const envelopeRule = applyPrivilegedEnvelopeExtractRule(output);
+    output = envelopeRule.output;
+    if (envelopeRule.replacementCount > 0) {
+        changes.push({
+            rule: "privileged-envelope-extract-helper",
+            replacements: envelopeRule.replacementCount,
+            description: envelopeRule.importAdded
+                ? "Replaced legacy privileged-envelope fallback chain and ensured extract helper import."
+                : "Replaced legacy privileged-envelope fallback chain.",
+        });
+    }
+
+    const configureRule = applyConfigureCapabilitiesRule(output);
+    output = configureRule.output;
+    if (configureRule.replacementCount > 0) {
+        changes.push({
+            rule: "plugin-registry-configure-capabilities",
+            replacements: configureRule.replacementCount,
+            description: "Replaced deprecated configureCapabilityPolicy(...) with configureCapabilities(...).",
+        });
+    }
+
+    return {
+        output,
+        changed: output !== source,
+        changes,
+    };
+}
diff --git a/src/utils/pluginDoctor.ts b/src/utils/pluginDoctor.ts
new file mode 100644
index 0000000..d828dc5
--- /dev/null
+++ b/src/utils/pluginDoctor.ts
@@ -0,0 +1,338 @@
+import {
+    PluginDoctorFinding,
+    PluginDoctorPanelFinding,
+    PluginDoctorPanelModel,
+    PluginDoctorPanelOptions,
+    PluginDoctorPanelSection,
+    PluginDoctorOptions,
+    PluginDoctorReport,
+    PluginDoctorSeverity,
+    PluginDiagnostics,
+    PluginDoctorCategory,
+} from "../types";
+import { runCapabilityPreflight } from "./capabilities";
+import { formatDiagnosticExactFix } from "./diagnosticTemplates";
+import { evaluateSdkHandshakeCompatibility } from "./handshake";
+
+function countFindings(findings: PluginDoctorFinding[], severity: PluginDoctorSeverity): number {
+    return findings.filter((finding) => finding.severity === severity).length;
+}
+
+const CATEGORY_TITLES: Record<PluginDoctorCategory, string> = {
+    health: "Health",
+    capabilities: "Capabilities",
+    handshake: "Handshake",
+    handlers: "Handlers",
+    stores: "Stores",
+    notifications: "Notifications",
+};
+
+const CATEGORY_ORDER: Record<PluginDoctorCategory, number> = {
+    health: 1,
+    capabilities: 2,
+    handshake: 3,
+    handlers: 4,
+    stores: 5,
+    notifications: 6,
+};
+
+const SEVERITY_PRIORITY: Record<PluginDoctorSeverity, number> = {
+    error: 300,
+    warning: 200,
+    info: 100,
+};
+
+function createSummary(report: PluginDoctorReport): string {
+    if (report.counts.error === 0 && report.counts.warning === 0) {
+        return "No error or warning findings. Plugin diagnostics look healthy.";
+    }
+
+    const parts = [
+        `${report.counts.error} error${report.counts.error === 1 ? "" : "s"}`,
+        `${report.counts.warning} warning${report.counts.warning === 1 ? "" : "s"}`,
+    ];
+    return `Plugin doctor found ${parts.join(" and ")}.`;
+}
+
+function resolveStatus(findings: PluginDoctorFinding[]): PluginDoctorReport["status"] {
+    if (findings.some((finding) => finding.severity === "error")) {
+        return "degraded";
+    }
+    if (findings.some((finding) => finding.severity === "warning")) {
+        return "needs-attention";
+    }
+    return "healthy";
+}
+
+function resolveFindingPriority(finding: PluginDoctorFinding, hasExactFix: boolean): number {
+    const base = SEVERITY_PRIORITY[finding.severity];
+    const exactFixBoost = hasExactFix ? 5 : 0;
+    return base + exactFixBoost;
+}
+
+function createPanelFinding(
+    finding: PluginDoctorFinding,
+    options: Required<PluginDoctorPanelOptions>
+): PluginDoctorPanelFinding {
+    const exactFix = options.includeExactFix ? formatDiagnosticExactFix(finding.code) ?? undefined : undefined;
+    return {
+        ...finding,
+        priority: resolveFindingPriority(finding, Boolean(exactFix)),
+        isBlocking: finding.severity === "error",
+        exactFix,
+    };
+}
+
+function comparePanelFindings(left: PluginDoctorPanelFinding, right: PluginDoctorPanelFinding): number {
+    if (right.priority !== left.priority) {
+        return right.priority - left.priority;
+    }
+    if (left.category !== right.category) {
+        return CATEGORY_ORDER[left.category] - CATEGORY_ORDER[right.category];
+    }
+    if (left.code !== right.code) {
+        return left.code.localeCompare(right.code);
+    }
+    return left.message.localeCompare(right.message);
+}
+
+function countPanelFindings(findings: PluginDoctorPanelFinding[], severity: PluginDoctorSeverity): number {
+    return findings.filter((entry) => entry.severity === severity).length;
+}
+
+function normalizePanelOptions(options: PluginDoctorPanelOptions): Required<PluginDoctorPanelOptions> {
+    return {
+        maxPrioritizedFindings: Math.max(1, options.maxPrioritizedFindings ?? 8),
+        includeInfoFindings: options.includeInfoFindings !== false,
+        includeExactFix: options.includeExactFix !== false,
+    };
+}
+
+export function createPluginDoctorReport(
+    diagnostics: PluginDiagnostics,
+    options: PluginDoctorOptions = {}
+): PluginDoctorReport {
+    const includeInfo = options.includeInfo !== false;
+    const includeNotificationFindings = options.includeNotificationFindings !== false;
+    const findings: PluginDoctorFinding[] = [];
+    const addFinding = (finding: PluginDoctorFinding): void => {
+        if (!includeInfo && finding.severity === "info") {
+            return;
+        }
+        findings.push(finding);
+    };
+
+    if (diagnostics.health.status === "degraded" || diagnostics.health.errorCount > 0) {
+        addFinding({
+            code: "HEALTH_DEGRADED",
+            severity: "error",
+            category: "health",
+            message: `Plugin health is degraded (errors: ${diagnostics.health.errorCount}).`,
+            details: {
+                lastErrorAt: diagnostics.health.lastErrorAt,
+                lastErrorMessage: diagnostics.health.lastErrorMessage,
+                initCount: diagnostics.health.initCount,
+                renderCount: diagnostics.health.renderCount,
+                handlerCount: diagnostics.health.handlerCount,
+            },
+            remediation: "Inspect the latest plugin error and fix the failing init/render/handler path before retrying.",
+        });
+    }
+
+    if (diagnostics.health.initCount === 0) {
+        addFinding({
+            code: "INIT_NOT_EXECUTED",
+            severity: "warning",
+            category: "health",
+            message: "Plugin init() has not completed yet.",
+            remediation: "Ensure the host sends PLUGIN_INIT and the plugin init path returns without throwing.",
+        });
+    }
+
+    if (diagnostics.health.renderCount === 0) {
+        addFinding({
+            code: "RENDER_NOT_EXECUTED",
+            severity: "info",
+            category: "health",
+            message: "Plugin render() has not completed yet.",
+            remediation: "Trigger plugin render once to verify render pipeline behavior.",
+        });
+    }
+
+    const preflight = runCapabilityPreflight({
+        declared: diagnostics.capabilities.declaration.declared,
+        granted: diagnostics.capabilities.permissions.granted,
+        action: options.capabilityAction ?? "satisfy plugin declared capability contract",
+    });
+
+    for (const missing of preflight.missing) {
+        addFinding({
+            code: "CAPABILITY_DECLARED_MISSING",
+            severity: "warning",
+            category: "capabilities",
+            message: `Declared capability "${missing.capability}" is not granted by host policy.`,
+            remediation: missing.remediation,
+            details: {
+                requiredCapabilities: missing.requiredCapabilities,
+                missingPrerequisites: missing.missingPrerequisites,
+                grantedPrerequisites: missing.grantedPrerequisites,
+            },
+        });
+    }
+
+    if (preflight.undeclaredGranted.length > 0) {
+        addFinding({
+            code: "CAPABILITY_GRANTED_UNDECLARED",
+            severity: "info",
+            category: "capabilities",
+            message: `Host granted ${preflight.undeclaredGranted.length} capability/capabilities not declared by plugin code.`,
+            remediation: "Align declareCapabilities() with host policy to keep plugin intent and grants synchronized.",
+            details: {
+                undeclaredGranted: preflight.undeclaredGranted.map((entry) => entry.capability),
+            },
+        });
+    }
+
+    if (options.handshake) {
+        const handshakeReport = evaluateSdkHandshakeCompatibility(diagnostics.handshake, options.handshake);
+        for (const issue of handshakeReport.issues) {
+            addFinding({
+                code: issue.code,
+                severity: issue.severity,
+                category: "handshake",
+                message: issue.message,
+                remediation: formatDiagnosticExactFix(issue.code) ?? undefined,
+                details: {
+                    expected: issue.expected,
+                    received: issue.received,
+                    featureFlag: issue.featureFlag,
+                    sdkVersion: diagnostics.handshake.sdkVersion,
+                    apiVersion: diagnostics.handshake.apiVersion,
+                    capabilitySchemaVersion: diagnostics.handshake.capabilitySchemaVersion,
+                },
+            });
+        }
+    }
+
+    const deniedEntries = Object.entries(diagnostics.capabilities.permissions.deniedCount)
+        .filter(([, deniedCount]) => typeof deniedCount === "number" && deniedCount > 0)
+        .sort(([left], [right]) => left.localeCompare(right));
+
+    if (deniedEntries.length > 0) {
+        addFinding({
+            code: "CAPABILITY_RUNTIME_DENIED",
+            severity: "warning",
+            category: "capabilities",
+            message: `Runtime denied ${deniedEntries.length} capability/capabilities during plugin execution.`,
+            remediation: "Grant the denied capabilities in host policy or remove denied code paths from plugin runtime.",
+            details: {
+                denied: deniedEntries.map(([capability, deniedCount]) => ({ capability, deniedCount })),
+            },
+        });
+    }
+
+    if (diagnostics.capabilities.registeredHandlers.length === 0) {
+        addFinding({
+            code: "HANDLERS_NOT_REGISTERED",
+            severity: "info",
+            category: "handlers",
+            message: "No plugin handlers are registered.",
+            remediation: "Register handlers in init() if your plugin expects UI_MESSAGE backend actions.",
+        });
+    }
+
+    if (includeNotificationFindings) {
+        if (diagnostics.notifications.count >= diagnostics.notifications.capacity) {
+            addFinding({
+                code: "NOTIFICATION_BUFFER_AT_CAPACITY",
+                severity: "warning",
+                category: "notifications",
+                message: "Notification buffer reached capacity; older messages may be dropped.",
+                remediation: "Increase notification buffer capacity in host runtime or reduce notification volume.",
+                details: {
+                    count: diagnostics.notifications.count,
+                    capacity: diagnostics.notifications.capacity,
+                },
+            });
+        }
+
+        const recentErrorNotifications = diagnostics.notifications.recent
+            .filter((entry) => entry.type === "error")
+            .length;
+        if (recentErrorNotifications > 0) {
+            addFinding({
+                code: "NOTIFICATIONS_RECENT_ERRORS",
+                severity: "warning",
+                category: "notifications",
+                message: `Recent notification stream includes ${recentErrorNotifications} error notification(s).`,
+                remediation: "Review recent notification errors and correlate them with plugin logs/correlation IDs.",
+            });
+        }
+    }
+
+    const report: PluginDoctorReport = {
+        pluginId: diagnostics.pluginId,
+        generatedAt: new Date().toISOString(),
+        status: resolveStatus(findings),
+        summary: "",
+        counts: {
+            error: countFindings(findings, "error"),
+            warning: countFindings(findings, "warning"),
+            info: countFindings(findings, "info"),
+        },
+        findings,
+    };
+    report.summary = createSummary(report);
+    return report;
+}
+
+export function createPluginDoctorPanelModel(
+    report: PluginDoctorReport,
+    options: PluginDoctorPanelOptions = {}
+): PluginDoctorPanelModel {
+    const normalizedOptions = normalizePanelOptions(options);
+    const panelFindings = report.findings
+        .filter((finding) => normalizedOptions.includeInfoFindings || finding.severity !== "info")
+        .map((finding) => createPanelFinding(finding, normalizedOptions))
+        .sort(comparePanelFindings);
+
+    const prioritizedFindings = panelFindings.slice(0, normalizedOptions.maxPrioritizedFindings);
+
+    const sectionMap = new Map<PluginDoctorCategory, PluginDoctorPanelFinding[]>();
+    for (const finding of panelFindings) {
+        if (!sectionMap.has(finding.category)) {
+            sectionMap.set(finding.category, []);
+        }
+        sectionMap.get(finding.category)?.push(finding);
+    }
+
+    const sections: PluginDoctorPanelSection[] = Array.from(sectionMap.entries())
+        .sort(([left], [right]) => CATEGORY_ORDER[left] - CATEGORY_ORDER[right])
+        .map(([category, findings]) => ({
+            category,
+            title: CATEGORY_TITLES[category],
+            counts: {
+                total: findings.length,
+                error: countPanelFindings(findings, "error"),
+                warning: countPanelFindings(findings, "warning"),
+                info: countPanelFindings(findings, "info"),
+            },
+            findings,
+        }));
+
+    return {
+        pluginId: report.pluginId,
+        generatedAt: report.generatedAt,
+        status: report.status,
+        summary: report.summary,
+        blocking: panelFindings.some((finding) => finding.isBlocking),
+        counts: {
+            total: panelFindings.length,
+            error: countPanelFindings(panelFindings, "error"),
+            warning: countPanelFindings(panelFindings, "warning"),
+            info: countPanelFindings(panelFindings, "info"),
+        },
+        prioritizedFindings,
+        sections,
+    };
+}
diff --git a/src/utils/privilegedResponses.ts b/src/utils/privilegedResponses.ts
index 3b4f717..1380042 100644
--- a/src/utils/privilegedResponses.ts
+++ b/src/utils/privilegedResponses.ts
@@ -1,4 +1,9 @@
-import { PrivilegedActionErrorResponse, PrivilegedActionResponse, PrivilegedActionSuccessResponse } from "../types";
+import {
+    PrivilegedActionErrorFormatOptions,
+    PrivilegedActionErrorResponse,
+    PrivilegedActionResponse,
+    PrivilegedActionSuccessResponse,
+} from "../types";
 
 export function createPrivilegedActionCorrelationId(prefix: string = "privileged-action"): string {
     const normalizedPrefix = prefix.trim().replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "privileged-action";
@@ -35,3 +40,89 @@ export function unwrapPrivilegedActionResponse<TResult = unknown>(
     }
     throw error;
 }
+
+export function formatPrivilegedActionError(
+    response: unknown,
+    options?: PrivilegedActionErrorFormatOptions
+): string {
+    const responseRecord = (response && typeof response === "object")
+        ? response as Record<string, unknown>
+        : {};
+    const context = typeof options?.context === "string" && options.context.trim().length > 0
+        ? options.context.trim()
+        : "Privileged action failed";
+    const fallbackCorrelationId = typeof options?.fallbackCorrelationId === "string"
+        ? options.fallbackCorrelationId
+        : "";
+    const correlationIdRaw = responseRecord["correlationId"];
+    const correlationId = typeof correlationIdRaw === "string" && correlationIdRaw.trim().length > 0
+        ? correlationIdRaw.trim()
+        : (fallbackCorrelationId.trim() || "unknown");
+    const errorRaw = responseRecord["error"];
+    const errorMessage = typeof errorRaw === "string" && errorRaw.trim().length > 0
+        ? errorRaw.trim()
+        : "Unknown host error";
+    const codeRaw = responseRecord["code"];
+    const codeSuffix = typeof codeRaw === "string" && codeRaw.trim().length > 0
+        ? ` (${codeRaw.trim()})`
+        : "";
+    const includeStdoutWhenStderrMissing = options?.includeStdoutWhenStderrMissing !== false;
+    const maxDetailLength = (
+        typeof options?.maxDetailLength === "number" && Number.isFinite(options.maxDetailLength) && options.maxDetailLength > 0
+    ) ? Math.trunc(options.maxDetailLength) : 1200;
+    const truncate = (value: string): string => value.length > maxDetailLength
+        ? `${value.slice(0, maxDetailLength)}...`
+        : value;
+
+    const resultRaw = responseRecord["result"];
+    const result = (resultRaw && typeof resultRaw === "object")
+        ? resultRaw as Record<string, unknown>
+        : null;
+    const stderrRaw = result?.["stderr"];
+    const stdoutRaw = result?.["stdout"];
+    const stderr = typeof stderrRaw === "string" ? stderrRaw.trim() : "";
+    const stdout = typeof stdoutRaw === "string" ? stdoutRaw.trim() : "";
+    const detailLines: string[] = [];
+
+    if (stderr) {
+        detailLines.push(`stderr: ${truncate(stderr)}`);
+    } else if (includeStdoutWhenStderrMissing && stdout) {
+        detailLines.push(`stdout: ${truncate(stdout)}`);
+    }
+
+    const exitCodeRaw = result?.["exitCode"];
+    if (typeof exitCodeRaw === "number" || typeof exitCodeRaw === "string") {
+        const exitCode = String(exitCodeRaw).trim();
+        if (exitCode.length > 0) {
+            detailLines.push(`exitCode: ${exitCode}`);
+        }
+    }
+
+    const commandRaw = result?.["command"];
+    const command = typeof commandRaw === "string" ? commandRaw.trim() : "";
+    const argsRaw = result?.["args"];
+    const args = Array.isArray(argsRaw)
+        ? argsRaw.filter((value) => typeof value === "string").map((value) => String(value))
+        : [];
+    if (command) {
+        const commandLine = args.length > 0
+            ? `${command} ${args.join(" ")}`
+            : command;
+        detailLines.push(`command: ${truncate(commandLine)}`);
+    }
+
+    const cwdRaw = result?.["cwd"];
+    const cwd = typeof cwdRaw === "string" ? cwdRaw.trim() : "";
+    if (cwd) {
+        detailLines.push(`cwd: ${truncate(cwd)}`);
+    }
+
+    const details = detailLines.length > 0
+        ? `\n${detailLines.join("\n")}`
+        : "";
+    return `${context}${codeSuffix}: ${errorMessage}${details}\nCorrelation ID: ${correlationId}`;
+}
+
+export function getInlinePrivilegedActionErrorFormatterSource(): string {
+    return `(${formatPrivilegedActionError.toString()})`;
+}
diff --git a/src/utils/privilegedTransport.ts b/src/utils/privilegedTransport.ts
index b15466c..aa47342 100644
--- a/src/utils/privilegedTransport.ts
+++ b/src/utils/privilegedTransport.ts
@@ -1,9 +1,13 @@
 import {
     HostPrivilegedActionRequest,
+    PrivilegedActionPipelineOptions,
+    PrivilegedActionPipelineResult,
     PrivilegedActionBackendRequest,
     PrivilegedActionResponse,
     RequestPrivilegedActionOptions,
 } from "../types";
+import { validateHostPrivilegedActionRequest } from "./contracts";
+import { formatPrivilegedActionError } from "./privilegedResponses";
 
 function resolvePrivilegedActionCorrelationId(options?: RequestPrivilegedActionOptions): string {
     if (options?.correlationId) {
@@ -27,6 +31,29 @@ export function createPrivilegedActionBackendRequest<TRequest extends HostPrivil
     };
 }
 
+export function extractPrivilegedActionRequest(
+    envelopeOrRequest: unknown
+): HostPrivilegedActionRequest {
+    const candidate = (
+        (typeof envelopeOrRequest === "object" && envelopeOrRequest !== null && "result" in envelopeOrRequest
+            ? (envelopeOrRequest as { result?: unknown }).result
+            : undefined) as { request?: unknown } | undefined
+    )?.request
+        ?? (typeof envelopeOrRequest === "object" && envelopeOrRequest !== null
+            ? (envelopeOrRequest as { request?: unknown }).request
+            : undefined)
+        ?? envelopeOrRequest;
+
+    try {
+        return validateHostPrivilegedActionRequest(candidate);
+    } catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(
+            `Could not extract a valid privileged action request from the provided envelope or request. ${reason}`
+        );
+    }
+}
+
 export async function requestPrivilegedAction<TResult = unknown, TRequest extends HostPrivilegedActionRequest = HostPrivilegedActionRequest>(
     request: TRequest,
     options?: RequestPrivilegedActionOptions
@@ -47,3 +74,55 @@ export async function requestPrivilegedAction<TResult = unknown, TRequest extend
     const handler = options?.handler ?? "requestPrivilegedAction";
     return runtimeWindow.createBackendReq(handler, payload) as Promise<PrivilegedActionResponse<TResult>>;
 }
+
+function resolveEnvelopeCorrelationId(envelopeOrRequest: unknown): string | undefined {
+    if (!envelopeOrRequest || typeof envelopeOrRequest !== "object") {
+        return undefined;
+    }
+
+    const resultCorrelationId = (envelopeOrRequest as { result?: { correlationId?: unknown } })
+        .result?.correlationId;
+    if (typeof resultCorrelationId === "string" && resultCorrelationId.trim().length > 0) {
+        return resultCorrelationId.trim();
+    }
+
+    const correlationId = (envelopeOrRequest as { correlationId?: unknown }).correlationId;
+    if (typeof correlationId === "string" && correlationId.trim().length > 0) {
+        return correlationId.trim();
+    }
+
+    return undefined;
+}
+
+export async function requestPrivilegedActionFromEnvelope<TResult = unknown>(
+    envelopeOrRequest: unknown,
+    options?: PrivilegedActionPipelineOptions
+): Promise<PrivilegedActionPipelineResult<TResult>> {
+    const request = extractPrivilegedActionRequest(envelopeOrRequest);
+    const response = await requestPrivilegedAction<TResult>(request, options);
+
+    if (response.ok) {
+        return { request, response };
+    }
+
+    const fallbackCorrelationId = options?.fallbackCorrelationId
+        ?? resolveEnvelopeCorrelationId(envelopeOrRequest);
+    const errorMessage = formatPrivilegedActionError(response, {
+        context: options?.context,
+        fallbackCorrelationId,
+        includeStdoutWhenStderrMissing: options?.includeStdoutWhenStderrMissing,
+        maxDetailLength: options?.maxDetailLength,
+    });
+
+    if (options?.throwOnError) {
+        const error = new Error(errorMessage) as Error & { response?: PrivilegedActionResponse<TResult> };
+        error.response = response;
+        throw error;
+    }
+
+    return {
+        request,
+        response,
+        errorMessage,
+    };
+}
diff --git a/src/utils/renderOnLoad.ts b/src/utils/renderOnLoad.ts
new file mode 100644
index 0000000..865b15f
--- /dev/null
+++ b/src/utils/renderOnLoad.ts
@@ -0,0 +1,399 @@
+import {
+    RenderOnLoadActionBinding,
+    RenderOnLoadActionBindingsModuleOptions,
+    RenderOnLoadActionHandler,
+    RenderOnLoadHint,
+    RenderOnLoadTemplate,
+    RenderOnLoadTemplateListOptions,
+    RenderOnLoadModule,
+    RenderOnLoadOutput,
+    RenderOnLoadSource,
+} from "../types";
+
+const DEFAULT_RENDER_ON_LOAD_SOURCE = "() => {}";
+
+const RENDER_ON_LOAD_TEMPLATES: ReadonlyArray<RenderOnLoadTemplate> = Object.freeze([
+    {
+        id: "runtime-noop",
+        label: "Runtime no-op",
+        description: "Smallest valid runtime on-load source.",
+        context: "runtime-source",
+        language: "javascript",
+        source: "(() => {})();",
+    },
+    {
+        id: "runtime-ui-message",
+        label: "Runtime UI_MESSAGE call",
+        description: "Bind a click handler and call backend UI_MESSAGE handler through the host bridge.",
+        context: "runtime-source",
+        language: "javascript",
+        source: `(() => {
+  const button = document.getElementById("run-action");
+  if (!button) return;
+  button.addEventListener("click", async () => {
+    const response = await window.createBackendReq("UI_MESSAGE", {
+      handler: "plugin.v1.runAction",
+      content: {},
+    });
+    console.log("UI_MESSAGE response", response);
+  });
+})();`,
+    },
+    {
+        id: "method-define-render-on-load",
+        label: "Method defineRenderOnLoad",
+        description: "Plugin method template using defineRenderOnLoad(() => ...).",
+        context: "plugin-method",
+        language: "typescript",
+        source: `renderOnLoad() {
+  return defineRenderOnLoad(() => {
+    const button = document.getElementById("run-action");
+    if (!button) return;
+    button.addEventListener("click", async () => {
+      const response = await window.createBackendReq("UI_MESSAGE", {
+        handler: "plugin.v1.runAction",
+        content: {},
+      });
+      console.log(response);
+    });
+  }, {
+    language: "typescript",
+  });
+}`,
+    },
+    {
+        id: "method-define-render-on-load-actions",
+        label: "Method defineRenderOnLoadActions",
+        description: "Plugin method template using declarative action bindings.",
+        context: "plugin-method",
+        language: "typescript",
+        source: `renderOnLoad() {
+  return defineRenderOnLoadActions({
+    handlers: {
+      run: async () => {
+        await window.createBackendReq("UI_MESSAGE", {
+          handler: "plugin.v1.runAction",
+          content: {},
+        });
+      },
+    },
+    bindings: [
+      {
+        selector: "#run-action",
+        event: "click",
+        handler: "run",
+      },
+    ],
+    strict: true,
+  });
+}`,
+    },
+]);
+
+function isRenderOnLoadFunction(value: unknown): value is () => void {
+    return typeof value === "function";
+}
+
+function resolveSourceExpression(source: RenderOnLoadSource): string {
+    return typeof source === "string" ? source : source.toString();
+}
+
+function resolveActionHandlerExpression(handler: RenderOnLoadActionHandler): string {
+    return typeof handler === "string" ? handler.trim() : handler.toString();
+}
+
+function normalizeActionBinding(binding: RenderOnLoadActionBinding): RenderOnLoadActionBinding {
+    const selector = String(binding.selector || "").trim();
+    const event = String(binding.event || "").trim();
+    const handler = String(binding.handler || "").trim();
+
+    if (!selector) {
+        throw new Error("Render-on-load action binding selector must be a non-empty string.");
+    }
+
+    if (!event) {
+        throw new Error(`Render-on-load action binding for selector "${selector}" must define a non-empty event.`);
+    }
+
+    if (!handler) {
+        throw new Error(`Render-on-load action binding for selector "${selector}" must define a non-empty handler id.`);
+    }
+
+    return {
+        selector,
+        event,
+        handler,
+        preventDefault: Boolean(binding.preventDefault),
+        stopPropagation: Boolean(binding.stopPropagation),
+        once: Boolean(binding.once),
+        passive: Boolean(binding.passive),
+        capture: Boolean(binding.capture),
+        required: binding.required !== false,
+    };
+}
+
+function normalizeActionHandlers(handlers: Record<string, RenderOnLoadActionHandler>): Record<string, string> {
+    const normalized: Record<string, string> = {};
+    for (const [handlerIdRaw, handlerSource] of Object.entries(handlers)) {
+        const handlerId = String(handlerIdRaw || "").trim();
+        if (!handlerId) {
+            throw new Error("Render-on-load action handlers must use non-empty handler ids.");
+        }
+
+        const expression = resolveActionHandlerExpression(handlerSource);
+        if (!expression) {
+            throw new Error(`Render-on-load action handler "${handlerId}" must provide a non-empty function source.`);
+        }
+
+        normalized[handlerId] = expression;
+    }
+
+    if (Object.keys(normalized).length === 0) {
+        throw new Error("Render-on-load action helper requires at least one handler.");
+    }
+
+    return normalized;
+}
+
+export function isRenderOnLoadModule(value: unknown): value is RenderOnLoadModule {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+
+    const candidate = value as RenderOnLoadModule;
+    return typeof candidate.source === "string" || isRenderOnLoadFunction(candidate.source);
+}
+
+export function defineRenderOnLoad(
+    source: RenderOnLoadSource,
+    options: Omit<RenderOnLoadModule, "source"> = {}
+): RenderOnLoadModule {
+    return {
+        source,
+        ...options,
+    };
+}
+
+export function createRenderOnLoadActionsSource(options: RenderOnLoadActionBindingsModuleOptions): string {
+    const strict = options.strict === true;
+    const normalizedHandlers = normalizeActionHandlers(options.handlers);
+    const normalizedBindings = (Array.isArray(options.bindings) ? options.bindings : [])
+        .map(normalizeActionBinding);
+
+    if (normalizedBindings.length === 0) {
+        throw new Error("Render-on-load action helper requires at least one binding.");
+    }
+
+    for (const binding of normalizedBindings) {
+        if (!normalizedHandlers[binding.handler]) {
+            throw new Error(
+                `Render-on-load action binding "${binding.selector}" references unknown handler "${binding.handler}".`
+            );
+        }
+    }
+
+    const handlersSource = Object.entries(normalizedHandlers)
+        .map(([handlerId, expression]) => `${JSON.stringify(handlerId)}: ${expression}`)
+        .join(",\n    ");
+    const setupExpression = options.setup ? resolveSourceExpression(options.setup) : "null";
+    const bindingsJson = JSON.stringify(normalizedBindings);
+
+    return `(() => {
+  const __fdoStrict = ${strict ? "true" : "false"};
+  const __fdoHandlers = {
+    ${handlersSource}
+  };
+  const __fdoBindings = ${bindingsJson};
+  const __fdoWarn = (message) => {
+    if (typeof console !== "undefined" && typeof console.warn === "function") {
+      console.warn(message);
+    }
+  };
+  const __fdoError = (message, error) => {
+    if (typeof console !== "undefined" && typeof console.error === "function") {
+      console.error(message, error);
+    }
+  };
+  const __fdoHandleFailure = (message, error) => {
+    if (__fdoStrict) {
+      const details = error instanceof Error ? error.message : String(error ?? "");
+      throw new Error(details ? \`\${message} \${details}\` : message);
+    }
+    __fdoError(message, error);
+  };
+  const __fdoInvokeHandler = (handlerId, event, element) => {
+    const handler = __fdoHandlers[handlerId];
+    if (typeof handler !== "function") {
+      __fdoHandleFailure(\`[FDO:onLoad] Unknown action handler "\${handlerId}".\`, null);
+      return;
+    }
+    try {
+      const result = handler({ event, element, window, document });
+      if (result && typeof result.then === "function") {
+        result.catch((error) => {
+          __fdoHandleFailure(\`[FDO:onLoad] Action handler "\${handlerId}" rejected.\`, error);
+        });
+      }
+    } catch (error) {
+      __fdoHandleFailure(\`[FDO:onLoad] Action handler "\${handlerId}" failed.\`, error);
+    }
+  };
+  const __fdoSetup = ${setupExpression};
+  if (__fdoSetup !== null && __fdoSetup !== undefined) {
+    if (typeof __fdoSetup === "function") {
+      try {
+        const setupResult = __fdoSetup();
+        if (setupResult && typeof setupResult.then === "function") {
+          setupResult.catch((error) => __fdoHandleFailure("[FDO:onLoad] Setup function rejected.", error));
+        }
+      } catch (error) {
+        __fdoHandleFailure("[FDO:onLoad] Setup function failed.", error);
+      }
+    } else {
+      __fdoWarn("[FDO:onLoad] Setup value is not a function and was ignored.");
+    }
+  }
+  for (const binding of __fdoBindings) {
+    const elements = Array.from(document.querySelectorAll(binding.selector));
+    if (elements.length === 0) {
+      if (binding.required) {
+        const message = \`[FDO:onLoad] No elements matched selector "\${binding.selector}" for event "\${binding.event}".\`;
+        if (__fdoStrict) {
+          throw new Error(message);
+        }
+        __fdoWarn(message);
+      }
+      continue;
+    }
+    const listenerOptions = {
+      capture: Boolean(binding.capture),
+      once: Boolean(binding.once),
+      passive: Boolean(binding.passive),
+    };
+    for (const element of elements) {
+      element.addEventListener(binding.event, (event) => {
+        if (binding.preventDefault) {
+          event.preventDefault();
+        }
+        if (binding.stopPropagation) {
+          event.stopPropagation();
+        }
+        __fdoInvokeHandler(binding.handler, event, element);
+      }, listenerOptions);
+    }
+  }
+})();`;
+}
+
+export function defineRenderOnLoadActions(options: RenderOnLoadActionBindingsModuleOptions): RenderOnLoadModule {
+    return defineRenderOnLoad(createRenderOnLoadActionsSource(options), {
+        language: options.language ?? "typescript",
+        hints: options.hints,
+        description: options.description
+            ?? "Declarative renderOnLoad action bindings generated by defineRenderOnLoadActions(...).",
+    });
+}
+
+export function resolveRenderOnLoadSource(output: RenderOnLoadOutput): string {
+    if (typeof output === "string") {
+        return output;
+    }
+
+    if (isRenderOnLoadFunction(output)) {
+        return output.toString();
+    }
+
+    if (isRenderOnLoadModule(output)) {
+        return resolveRenderOnLoadSource(output.source);
+    }
+
+    throw new Error(
+        "Method 'renderOnLoad' must return a synchronous string, function, or defineRenderOnLoad(...) module."
+    );
+}
+
+export function createNoopRenderOnLoadSource(): string {
+    return DEFAULT_RENDER_ON_LOAD_SOURCE;
+}
+
+function cloneRenderOnLoadTemplate(template: RenderOnLoadTemplate): RenderOnLoadTemplate {
+    return {
+        id: template.id,
+        label: template.label,
+        description: template.description,
+        context: template.context,
+        language: template.language,
+        source: template.source,
+    };
+}
+
+export function listRenderOnLoadTemplates(options: RenderOnLoadTemplateListOptions = {}): RenderOnLoadTemplate[] {
+    const context = options.context;
+    return RENDER_ON_LOAD_TEMPLATES
+        .filter((template) => !context || template.context === context)
+        .map((template) => cloneRenderOnLoadTemplate(template));
+}
+
+export function getRenderOnLoadTemplate(id: string): RenderOnLoadTemplate | null {
+    const normalizedId = String(id ?? "").trim();
+    if (!normalizedId) {
+        return null;
+    }
+
+    const template = RENDER_ON_LOAD_TEMPLATES.find((entry) => entry.id === normalizedId);
+    return template ? cloneRenderOnLoadTemplate(template) : null;
+}
+
+export function getRenderOnLoadMonacoTypeDefinitions(): string {
+    return [
+        "declare namespace FDOOnLoad {",
+        "  type BackendReq = (type: string, data?: unknown) => Promise<unknown>;",
+        "  type WaitForElement = (selector: string, callback: (element: Element) => void, timeout?: number) => void;",
+        "  interface Context {",
+        "    window: Window;",
+        "    document: Document;",
+        "    createBackendReq: BackendReq;",
+        "    waitForElement: WaitForElement;",
+        "    addGlobalEventListener: Window[\"addGlobalEventListener\"];",
+        "    removeGlobalEventListener: Window[\"removeGlobalEventListener\"];",
+        "    executeInjectedScript: Window[\"executeInjectedScript\"];",
+        "    applyClassToSelector: Window[\"applyClassToSelector\"];",
+        "    Notyf?: Window[\"Notyf\"];",
+        "    hljs?: Window[\"hljs\"];",
+        "    ace?: Window[\"ace\"];",
+        "  }",
+        "}",
+    ].join("\n");
+}
+
+export function getRenderOnLoadMonacoHints(): RenderOnLoadHint[] {
+    return [
+        {
+            kind: "snippet",
+            label: "UI_MESSAGE handler request",
+            insertText: "const response = await window.createBackendReq(\"UI_MESSAGE\", { handler: \"${1:handler.id}\", content: ${2:{}} });",
+            detail: "Call a backend handler through UI_MESSAGE bridge.",
+            documentation: "Use host-validated UI_MESSAGE bridge to communicate with backend handlers.",
+        },
+        {
+            kind: "snippet",
+            label: "waitForElement helper",
+            insertText: "window.waitForElement(\"${1:#selector}\", (element) => {\\n  ${2:// ...}\\n});",
+            detail: "Wait until selector appears in iframe DOM.",
+            documentation: "Use this helper instead of tight polling loops in on-load scripts.",
+        },
+        {
+            kind: "snippet",
+            label: "Notyf success toast",
+            insertText: "const notifier = new window.Notyf({ duration: 2500 });\\nnotifier.success(\"${1:Done}\");",
+            detail: "Show user feedback toast.",
+        },
+        {
+            kind: "snippet",
+            label: "Action binding pattern",
+            insertText: "document.querySelector(\"${1:#button}\")?.addEventListener(\"${2:click}\", (event) => {\\n  ${3:// ...}\\n});",
+            detail: "Bind a DOM event handler in on-load runtime.",
+            documentation: "For plugin TypeScript authoring, prefer SDK helper defineRenderOnLoadActions(...) over hand-written listener wiring.",
+        },
+    ];
+}
diff --git a/src/utils/storageTooling.ts b/src/utils/storageTooling.ts
new file mode 100644
index 0000000..ab9d16b
--- /dev/null
+++ b/src/utils/storageTooling.ts
@@ -0,0 +1,38 @@
+import {
+    PluginCapability,
+    StorageCapabilityPresetDefinition,
+    StorageCapabilityPresetId,
+} from "../types";
+import { createStorageCapabilityBundle } from "./capabilities";
+
+const PRESET_CONFIG: Record<StorageCapabilityPresetId, Omit<StorageCapabilityPresetDefinition, "capabilities">> = {
+    storageJSON: {
+        id: "storageJSON",
+        label: "Storage JSON",
+        description: "Persistent plugin JSON storage using the SDK-managed scoped JSON store backend.",
+        backendId: "json",
+    },
+};
+
+function withCapabilities(
+    preset: Omit<StorageCapabilityPresetDefinition, "capabilities">
+): StorageCapabilityPresetDefinition {
+    return {
+        ...preset,
+        capabilities: createStorageCapabilityBundle(preset.backendId) as ["storage", `storage.${string}`],
+    };
+}
+
+export function getStorageCapabilityPreset(presetId: StorageCapabilityPresetId): StorageCapabilityPresetDefinition {
+    return withCapabilities(PRESET_CONFIG[presetId]);
+}
+
+export function listStorageCapabilityPresets(): StorageCapabilityPresetDefinition[] {
+    return Object.keys(PRESET_CONFIG)
+        .sort((left, right) => left.localeCompare(right))
+        .map((presetId) => getStorageCapabilityPreset(presetId as StorageCapabilityPresetId));
+}
+
+export function createStorageCapabilityPreset(presetId: StorageCapabilityPresetId): PluginCapability[] {
+    return [...getStorageCapabilityPreset(presetId).capabilities];
+}
diff --git a/src/version.ts b/src/version.ts
new file mode 100644
index 0000000..7a07fdb
--- /dev/null
+++ b/src/version.ts
@@ -0,0 +1,20 @@
+declare const __FDO_SDK_PACKAGE_VERSION__: string | undefined;
+
+export const SDK_API_VERSION = "1.0.0";
+
+function resolveDefinedPackageVersion(): string | undefined {
+    if (typeof __FDO_SDK_PACKAGE_VERSION__ === "string" && __FDO_SDK_PACKAGE_VERSION__.trim().length > 0) {
+        return __FDO_SDK_PACKAGE_VERSION__.trim();
+    }
+
+    const envVersion = typeof process !== "undefined"
+        ? (process.env?.FDO_SDK_PACKAGE_VERSION ?? process.env?.npm_package_version)
+        : undefined;
+    if (typeof envVersion === "string" && envVersion.trim().length > 0) {
+        return envVersion.trim();
+    }
+
+    return undefined;
+}
+
+export const SDK_PACKAGE_VERSION = resolveDefinedPackageVersion() ?? "0.0.0-dev";
diff --git a/tests/DOMButton.test.ts b/tests/DOMButton.test.ts
index 14597a7..f41cc3a 100644
--- a/tests/DOMButton.test.ts
+++ b/tests/DOMButton.test.ts
@@ -31,4 +31,19 @@ describe("DOMButton", () => {
         const button = domButton.createButton("No Default", () => {}, { disableDefaultClass: true });
         expect(button.toString()).not.toContain("pure-button");
     });
+
+    it("should create a static button without inline onClick handler", () => {
+        const button = domButton.createStaticButton(
+            "Run",
+            { disableDefaultClass: true, classes: ["custom-action"] },
+            "run-button",
+            { type: "button" }
+        );
+
+        expect(button.toString()).toContain('id="run-button"');
+        expect(button.toString()).toContain('class="custom-action');
+        expect(button.toString()).toContain('type="button"');
+        expect(button.toString()).toContain(">Run</button>");
+        expect(button.toString()).not.toContain("onClick=");
+    });
 })
diff --git a/tests/PluginRegistry.test.ts b/tests/PluginRegistry.test.ts
index 8483f51..fcaa728 100644
--- a/tests/PluginRegistry.test.ts
+++ b/tests/PluginRegistry.test.ts
@@ -433,6 +433,9 @@ describe("PluginRegistry", () => {
         expect(diagnostics.apiVersion).toBe(FDO_SDK.API_VERSION);
         expect(diagnostics.pluginId).toBe("tests-diagnostics-plugin");
         expect(diagnostics.metadata?.name).toBe(plugin.metadata.name);
+        expect(diagnostics.handshake.apiVersion).toBe(FDO_SDK.API_VERSION);
+        expect(diagnostics.handshake.featureFlags.pluginDoctorReport).toBe(true);
+        expect(diagnostics.handshake.capabilitySchemaVersion).toBe("1.0.0");
         expect(diagnostics.health.status).toBe("healthy");
         expect(diagnostics.health.initCount).toBe(1);
         expect(diagnostics.health.renderCount).toBe(1);
@@ -530,7 +533,7 @@ describe("PluginRegistry", () => {
         test("should return specific store when using useStore with valid store name", () => {
             registerScopedPlugin();
             PluginRegistry.configureStorage({ rootDir: "/tmp/fdo-sdk-test-storage" });
-            PluginRegistry.configureCapabilities({ granted: ["storage.json"] });
+            PluginRegistry.configureCapabilities({ granted: ["storage", "storage.json"] });
             const store = PluginRegistry.useStore("json");
             expect(store).not.toBe(StoreJson);
             expect((store as any)._filePath).toContain("/tmp/fdo-sdk-test-storage/tests-scoped-plugin/store.json");
@@ -609,7 +612,7 @@ describe("PluginRegistry", () => {
 
         test("should require explicit storage root for json store", () => {
             registerScopedPlugin();
-            PluginRegistry.configureCapabilities({ granted: ["storage.json"] });
+            PluginRegistry.configureCapabilities({ granted: ["storage", "storage.json"] });
 
             expect(() => PluginRegistry.useStore("json")).toThrow(
                 "JSON store requires a configured storage root. Set PluginRegistry.configureStorage({ rootDir }) or FDO_SDK_STORAGE_ROOT."
@@ -619,18 +622,28 @@ describe("PluginRegistry", () => {
         test("should allow JSON store root from environment", () => {
             process.env.FDO_SDK_STORAGE_ROOT = "/tmp/fdo-sdk-env-storage";
             registerScopedPlugin();
-            PluginRegistry.configureCapabilities({ granted: ["storage.json"] });
+            PluginRegistry.configureCapabilities({ granted: ["storage", "storage.json"] });
 
             const store = PluginRegistry.useStore("json");
 
             expect((store as any)._filePath).toContain("/tmp/fdo-sdk-env-storage/tests-scoped-plugin/store.json");
         });
 
-        test("should require storage.json capability before creating json store", () => {
+        test("should require storage base capability before creating json store", () => {
             registerScopedPlugin();
             PluginRegistry.configureStorage({ rootDir: "/tmp/fdo-sdk-test-storage" });
             PluginRegistry.configureCapabilities({ granted: [] });
 
+            expect(() => PluginRegistry.useStore("json")).toThrow(
+                'Capability "storage" is required to use the JSON persistent store. Configure PluginRegistry.configureCapabilities({ granted: ["storage"] }) in the host before plugin initialization.'
+            );
+        });
+
+        test("should require storage backend leaf capability when base storage is granted", () => {
+            registerScopedPlugin();
+            PluginRegistry.configureStorage({ rootDir: "/tmp/fdo-sdk-test-storage" });
+            PluginRegistry.configureCapabilities({ granted: ["storage"] });
+
             expect(() => PluginRegistry.useStore("json")).toThrow(
                 'Capability "storage.json" is required to use the JSON persistent store. Configure PluginRegistry.configureCapabilities({ granted: ["storage.json"] }) in the host before plugin initialization.'
             );
diff --git a/tests/contracts.test.ts b/tests/contracts.test.ts
index 0917791..d016237 100644
--- a/tests/contracts.test.ts
+++ b/tests/contracts.test.ts
@@ -114,10 +114,38 @@ describe("SDK contract validators", () => {
         expect(validatePluginInitPayload(undefined)).toEqual({});
         expect(validatePluginInitPayload({
             apiVersion: "1.0.0",
-            capabilities: ["storage.json", "system.hosts.write", "system.fs.scope.etc-hosts", "system.process.exec", "system.process.scope.docker-cli"]
+            capabilities: [
+                "storage",
+                "storage.json",
+                "system.network",
+                "system.network.https",
+                "system.network.scope.public-web-secure",
+                "system.host.write",
+                "system.hosts.write",
+                "system.fs.scope.etc-hosts",
+                "system.process.exec",
+                "system.process.scope.docker-cli",
+            ]
         })).toEqual({
             apiVersion: "1.0.0",
-            capabilities: ["storage.json", "system.hosts.write", "system.fs.scope.etc-hosts", "system.process.exec", "system.process.scope.docker-cli"],
+            capabilities: [
+                "storage",
+                "storage.json",
+                "system.network",
+                "system.network.https",
+                "system.network.scope.public-web-secure",
+                "system.host.write",
+                "system.hosts.write",
+                "system.fs.scope.etc-hosts",
+                "system.process.exec",
+                "system.process.scope.docker-cli",
+            ],
+        });
+
+        expect(validatePluginInitPayload({
+            capabilities: ["storage", "storage.sqlite"]
+        })).toEqual({
+            capabilities: ["storage", "storage.sqlite"],
         });
     });
 
@@ -132,6 +160,12 @@ describe("SDK contract validators", () => {
         expect(() => validatePluginInitPayload({ capabilities: ["unknown.capability"] })).toThrow(
             'Plugin init payload capability "unknown.capability" is not supported by this SDK version.'
         );
+        expect(() => validatePluginInitPayload({ capabilities: ["storage."] })).toThrow(
+            'Plugin init payload capability "storage." is not supported by this SDK version.'
+        );
+        expect(() => validatePluginInitPayload({ capabilities: ["system.network.scope."] })).toThrow(
+            'Plugin init payload capability "system.network.scope." is not supported by this SDK version.'
+        );
     });
 
     test("validates host privileged action requests", () => {
diff --git a/tests/examples.service-content-hub.test.ts b/tests/examples.service-content-hub.test.ts
new file mode 100644
index 0000000..6589f4b
--- /dev/null
+++ b/tests/examples.service-content-hub.test.ts
@@ -0,0 +1,359 @@
+import { beforeAll, beforeEach, describe, expect, test, vi } from "vitest";
+import { PluginRegistry } from "../src/PluginRegistry";
+
+vi.mock("@anikitenko/fdo-sdk", async () => {
+    return await import("../src/index");
+});
+
+let ServiceContentHubPlugin: typeof import("../examples/13-service-content-hub-plugin").default;
+
+beforeAll(async () => {
+    (global as any).process.parentPort = {
+        on: vi.fn(),
+        postMessage: vi.fn(),
+    };
+    ServiceContentHubPlugin = (await import("../examples/13-service-content-hub-plugin")).default;
+});
+
+beforeEach(() => {
+    PluginRegistry.clearAllHandlers();
+    PluginRegistry.clearPlugin();
+    PluginRegistry.configureStorage({ rootDir: undefined });
+    PluginRegistry.configureCapabilities({ granted: [] });
+    delete (globalThis as { __FDO_CONTENT_BROKER?: unknown }).__FDO_CONTENT_BROKER;
+    delete (globalThis as { __FDO_AUTH_BROKER?: unknown }).__FDO_AUTH_BROKER;
+    delete (globalThis as { __FDO_AI_LIST_ASSISTANTS?: unknown }).__FDO_AI_LIST_ASSISTANTS;
+});
+
+describe("Service content hub example handlers", () => {
+    test("prepare uses session fallback when json store capability is unavailable", async () => {
+        new ServiceContentHubPlugin();
+
+        const response = await PluginRegistry.callHandler("serviceHub.v1.prepare", {});
+
+        expect(response).toMatchObject({
+            ok: true,
+            storageMode: "session-fallback",
+        });
+    });
+
+    test("list workspaces validates malformed endpoint url", async () => {
+        new ServiceContentHubPlugin();
+        PluginRegistry.configureCapabilities({
+            granted: ["system.network", "system.network.https", "system.network.scope.external-services"],
+        });
+
+        const response = await PluginRegistry.callHandler("serviceHub.v1.content.listWorkspaces", {
+            providerId: "custom-api",
+            sessionId: "session-1",
+            endpointUrl: "invalid-url",
+        });
+
+        expect(response).toMatchObject({
+            ok: false,
+            code: "ENDPOINT_URL_INVALID",
+        });
+    });
+
+    test("list workspaces retries transient provider failures and normalizes response", async () => {
+        new ServiceContentHubPlugin();
+        PluginRegistry.configureCapabilities({
+            granted: [
+                "system.network",
+                "system.network.https",
+                "system.network.scope.external-services",
+                "storage",
+            ],
+        });
+
+        const request = vi
+            .fn()
+            .mockRejectedValueOnce(new Error("429 throttled"))
+            .mockResolvedValueOnce({
+                items: [
+                    {
+                        id: "site-1",
+                        name: "Engineering",
+                        kind: "site",
+                        webUrl: "https://contoso.sharepoint.com/sites/engineering",
+                    },
+                ],
+                nextCursor: "cursor-2",
+            });
+        (globalThis as { __FDO_CONTENT_BROKER?: unknown }).__FDO_CONTENT_BROKER = { request };
+
+        const response = await PluginRegistry.callHandler("serviceHub.v1.content.listWorkspaces", {
+            providerId: "sharepoint",
+            sessionId: "session-1",
+            endpointUrl: "https://contoso.sharepoint.com",
+            query: "eng",
+        });
+
+        expect(request).toHaveBeenCalledTimes(2);
+        expect(response).toMatchObject({
+            ok: true,
+            nextCursor: "cursor-2",
+            items: [
+                {
+                    id: "site-1",
+                    name: "Engineering",
+                    kind: "site",
+                },
+            ],
+        });
+        expect((response as { correlationId?: unknown }).correlationId).toEqual(expect.stringMatching(/^list-workspaces-/));
+    });
+
+    test("sharepoint workspace fallback requires query or site id when no broker is available", async () => {
+        new ServiceContentHubPlugin();
+        PluginRegistry.configureCapabilities({
+            granted: [
+                "system.network",
+                "system.network.https",
+                "system.network.scope.external-services",
+                "storage",
+            ],
+        });
+
+        const request = vi.fn();
+        (globalThis as { __FDO_SESSION_REQUEST?: unknown }).__FDO_SESSION_REQUEST = { request };
+
+        const response = await PluginRegistry.callHandler("serviceHub.v1.content.listWorkspaces", {
+            providerId: "sharepoint",
+            sessionId: "session-1",
+            endpointUrl: "https://graph.microsoft.com/v1.0",
+        });
+
+        expect(request).not.toHaveBeenCalled();
+        expect(response).toMatchObject({
+            ok: false,
+            code: "LIST_WORKSPACES_FAILED",
+        });
+        expect((response as { error?: unknown }).error).toEqual(
+            expect.stringContaining("requires either a search query or a SharePoint Site ID")
+        );
+    });
+
+    test("ai assistants handler uses host canonical global name", async () => {
+        new ServiceContentHubPlugin();
+        (globalThis as { __FDO_AI_LIST_ASSISTANTS?: unknown }).__FDO_AI_LIST_ASSISTANTS = vi.fn().mockResolvedValue({
+            assistants: [{ id: "assistant-1", name: "Default Assistant" }],
+        });
+
+        const response = await PluginRegistry.callHandler("fdo.ai.assistants.list.v1", { purpose: "automation" });
+
+        expect(response).toMatchObject({
+            ok: true,
+            source: "fdo-ai",
+            assistants: [{ id: "assistant-1", name: "Default Assistant" }],
+        });
+    });
+
+    test("auth start requests sharepoint device code flow and returns pending verification payload", async () => {
+        new ServiceContentHubPlugin();
+        PluginRegistry.configureCapabilities({
+            granted: ["system.network", "system.network.https", "system.network.scope.external-services"],
+        });
+
+        const start = vi.fn().mockResolvedValue({
+            ok: true,
+            sessionId: "session-device-1",
+            authTxnId: "auth-txn-device-1",
+            raw: {
+                verification_uri: "https://microsoft.com/devicelogin",
+                user_code: "ABCD-EFGH",
+                device_code: "device-code-1",
+                interval: 5,
+                expires_in: 900,
+                message: "Open microsoft.com/devicelogin and enter the code.",
+            },
+            accountId: "user@contoso.com",
+        });
+        (globalThis as { __FDO_AUTH_BROKER?: unknown }).__FDO_AUTH_BROKER = { start };
+
+        const response = await PluginRegistry.callHandler("serviceHub.v1.auth.start", {
+            providerId: "sharepoint",
+            endpointUrl: "https://graph.microsoft.com/v1.0",
+            authConfig: {
+                clientId: "client-id-123",
+                tenantId: "common",
+            },
+        });
+
+        expect(start).toHaveBeenCalledTimes(1);
+        expect(start.mock.calls[0]?.[0]).toMatchObject({
+            providerId: "sharepoint",
+            endpointUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/devicecode",
+            request: {
+                url: "https://login.microsoftonline.com/common/oauth2/v2.0/devicecode",
+                method: "POST",
+                headers: {
+                    "content-type": "application/x-www-form-urlencoded",
+                },
+            },
+        });
+        expect(response).toMatchObject({
+            ok: true,
+            pending: true,
+            sessionId: "session-device-1",
+            accountId: "user@contoso.com",
+            verificationUri: "https://microsoft.com/devicelogin",
+            userCode: "ABCD-EFGH",
+        });
+    });
+
+    test("auth start keeps pending when broker marks interaction required with nested redirect url", async () => {
+        new ServiceContentHubPlugin();
+        PluginRegistry.configureCapabilities({
+            granted: ["system.network", "system.network.https", "system.network.scope.external-services"],
+        });
+
+        const start = vi.fn().mockResolvedValue({
+            requiresInteraction: true,
+            session: { id: "session-provisional-1" },
+            auth: { url: "https://idp.example.com/authorize?flow=device" },
+        });
+        (globalThis as { __FDO_AUTH_BROKER?: unknown }).__FDO_AUTH_BROKER = { start };
+
+        const response = await PluginRegistry.callHandler("serviceHub.v1.auth.start", {
+            providerId: "sharepoint",
+            endpointUrl: "https://graph.microsoft.com/v1.0",
+        });
+
+        expect(response).toMatchObject({
+            ok: true,
+            pending: true,
+            sessionId: "session-provisional-1",
+            authorizationUrl: "https://idp.example.com/authorize?flow=device",
+        });
+    });
+
+    test("auth start keeps pending when host transport wraps provider payload in raw", async () => {
+        new ServiceContentHubPlugin();
+        PluginRegistry.configureCapabilities({
+            granted: ["system.network", "system.network.https", "system.network.scope.external-services"],
+        });
+
+        const start = vi.fn().mockResolvedValue({
+            ok: true,
+            authTxnId: "auth-txn-1",
+            providerId: "sharepoint",
+            sessionId: "plugin-auth:session-1",
+            raw: {
+                authorizeUrl: "https://idp.example.com/oauth2/authorize?txn=abc",
+                state: "pending",
+            },
+        });
+        (globalThis as { __FDO_AUTH_BROKER?: unknown }).__FDO_AUTH_BROKER = { start };
+
+        const response = await PluginRegistry.callHandler("serviceHub.v1.auth.start", {
+            providerId: "sharepoint",
+            endpointUrl: "https://graph.microsoft.com/v1.0",
+        });
+
+        expect(response).toMatchObject({
+            ok: true,
+            pending: true,
+            sessionId: "plugin-auth:session-1",
+            authorizationUrl: "https://idp.example.com/oauth2/authorize?txn=abc",
+        });
+    });
+
+    test("auth start keeps pending when host returns transport envelope without raw payload", async () => {
+        new ServiceContentHubPlugin();
+        PluginRegistry.configureCapabilities({
+            granted: ["system.network", "system.network.https", "system.network.scope.external-services"],
+        });
+
+        const start = vi.fn().mockResolvedValue({
+            ok: true,
+            authTxnId: "auth-txn-2",
+            providerId: "sharepoint",
+            sessionId: "plugin-auth:session-2",
+            raw: null,
+        });
+        (globalThis as { __FDO_AUTH_BROKER?: unknown }).__FDO_AUTH_BROKER = { start };
+
+        const response = await PluginRegistry.callHandler("serviceHub.v1.auth.start", {
+            providerId: "sharepoint",
+            endpointUrl: "https://graph.microsoft.com/v1.0",
+        });
+
+        expect(response).toMatchObject({
+            ok: true,
+            pending: true,
+            sessionId: "plugin-auth:session-2",
+            authTxnId: "auth-txn-2",
+        });
+    });
+
+    test("auth refresh polls microsoft token endpoint for sharepoint device code flow", async () => {
+        new ServiceContentHubPlugin();
+        PluginRegistry.configureCapabilities({
+            granted: ["system.network", "system.network.https", "system.network.scope.external-services"],
+        });
+
+        const plugin = new ServiceContentHubPlugin();
+        await PluginRegistry.callHandler("serviceHub.v1.saveContext", {
+            providerId: "sharepoint",
+            endpointUrl: "https://graph.microsoft.com/v1.0",
+            sessionId: "session-device-2",
+            authConfig: {
+                clientId: "client-id-123",
+                tenantId: "organizations",
+            },
+            authDeviceCode: "device-code-2",
+            authVerificationUri: "https://microsoft.com/devicelogin",
+            authUserCode: "ZXCV-BNMQ",
+        });
+
+        void plugin;
+        const start = vi.fn().mockResolvedValue({
+            ok: true,
+            providerId: "sharepoint",
+            sessionId: "session-device-2",
+            raw: {
+                access_token: "token-123",
+                token_type: "Bearer",
+                expires_in: 3600,
+            },
+        });
+        (globalThis as { __FDO_AUTH_BROKER?: unknown }).__FDO_AUTH_BROKER = { refresh: start };
+
+        const response = await PluginRegistry.callHandler("serviceHub.v1.auth.refresh", {
+            providerId: "sharepoint",
+            endpointUrl: "https://graph.microsoft.com/v1.0",
+            sessionId: "session-device-2",
+        });
+
+        expect(start).toHaveBeenCalledTimes(2);
+        expect(start.mock.calls[0]?.[0]).toMatchObject({
+            providerId: "sharepoint",
+            sessionId: "session-device-2",
+            request: {
+                url: "https://login.microsoftonline.com/organizations/oauth2/v2.0/token",
+                method: "POST",
+                headers: {
+                    "content-type": "application/x-www-form-urlencoded",
+                },
+            },
+        });
+        expect(start.mock.calls[1]?.[0]).toMatchObject({
+            providerId: "sharepoint",
+            sessionId: "session-device-2",
+            auth: {
+                scheme: "bearer",
+                value: "token-123",
+            },
+            credentials: {
+                accessToken: "token-123",
+                tokenType: "Bearer",
+            },
+        });
+        expect(response).toMatchObject({
+            ok: true,
+            sessionId: "session-device-2",
+            authDeviceCode: "",
+        });
+    });
+});
diff --git a/tests/examples.system-file.test.ts b/tests/examples.system-file.test.ts
new file mode 100644
index 0000000..c75a4e7
--- /dev/null
+++ b/tests/examples.system-file.test.ts
@@ -0,0 +1,26 @@
+import { beforeAll, describe, expect, test, vi } from "vitest";
+
+vi.mock("@anikitenko/fdo-sdk", async () => {
+    return await import("../src/index");
+});
+
+let SystemFilePlugin: typeof import("../examples/10-system-file-plugin").default;
+
+beforeAll(async () => {
+    (global as any).process.parentPort = {
+        on: vi.fn(),
+        postMessage: vi.fn(),
+    };
+
+    SystemFilePlugin = (await import("../examples/10-system-file-plugin")).default;
+});
+
+describe("System file example", () => {
+    test("renderOnLoad extracts request payload from privileged envelope", () => {
+        const plugin = new SystemFilePlugin();
+        const onLoad = plugin.renderOnLoad();
+
+        expect(onLoad).toContain("extractPrivilegedActionRequest(envelopeResponse)");
+        expect(onLoad).not.toContain('createBackendReq("requestPrivilegedAction", envelope)');
+    });
+});
diff --git a/tests/index.test.ts b/tests/index.test.ts
index a6a3c27..5fd7d59 100644
--- a/tests/index.test.ts
+++ b/tests/index.test.ts
@@ -1,4 +1,4 @@
-import {FDO_SDK} from "../src";
+import {defineRenderOnLoad, FDO_SDK} from "../src";
 import { PluginRegistry } from "../src/PluginRegistry";
 import { Logger } from "../src/Logger";
 
@@ -24,6 +24,49 @@ class AsyncRejectRenderOnLoadPlugin extends FDO_SDK {
     }
 }
 
+class FunctionRenderOnLoadPlugin extends FDO_SDK {
+    public render(): string {
+        return "<div>ok</div>";
+    }
+
+    public renderOnLoad(): any {
+        return () => {
+            const element = document.getElementById("status");
+            if (element) {
+                element.textContent = "loaded";
+            }
+        };
+    }
+}
+
+class ModuleRenderOnLoadPlugin extends FDO_SDK {
+    public render(): string {
+        return "<div>ok</div>";
+    }
+
+    public renderOnLoad(): any {
+        return defineRenderOnLoad(() => {
+            const element = document.getElementById("status");
+            if (element) {
+                element.textContent = "loaded";
+            }
+        }, {
+            language: "typescript",
+            description: "typed on-load module",
+        });
+    }
+}
+
+class InvalidRenderOnLoadPlugin extends FDO_SDK {
+    public render(): string {
+        return "<div>ok</div>";
+    }
+
+    public renderOnLoad(): any {
+        return { unsupported: true };
+    }
+}
+
 describe("FDO_SDK", () => {
     let sdk: FDO_SDK;
     let mockLogger: vi.SpyInstance;
@@ -128,6 +171,24 @@ describe("FDO_SDK", () => {
         expect(sdk.serializeRenderOnLoad()).toBe(JSON.stringify('() => {}'));
     });
 
+    test("should serialize renderOnLoad function output explicitly", () => {
+        const plugin = new FunctionRenderOnLoadPlugin();
+        const serialized = plugin.serializeRenderOnLoad();
+        const source = JSON.parse(serialized);
+
+        expect(typeof source).toBe("string");
+        expect(source).toContain("document.getElementById(\"status\")");
+    });
+
+    test("should serialize defineRenderOnLoad module output explicitly", () => {
+        const plugin = new ModuleRenderOnLoadPlugin();
+        const serialized = plugin.serializeRenderOnLoad();
+        const source = JSON.parse(serialized);
+
+        expect(typeof source).toBe("string");
+        expect(source).toContain("document.getElementById(\"status\")");
+    });
+
     test("should log messages using log()", () => {
         sdk.log("Test message");
         expect(mockLogger).toHaveBeenCalledWith("Test message");
@@ -255,10 +316,17 @@ describe("FDO_SDK", () => {
         const errorSpy = vi.spyOn(Logger.prototype, "error").mockImplementation(() => {});
 
         expect(() => asyncPlugin.serializeRenderOnLoad()).toThrow(
-            "Method 'renderOnLoad' must return a synchronous string. Async on-load promises are not supported."
+            "Method 'renderOnLoad' must return a synchronous string, function, or defineRenderOnLoad(...) module. Async on-load promises are not supported."
         );
 
         await Promise.resolve();
         expect(errorSpy).toHaveBeenCalledWith(expect.objectContaining({ message: "async-onload-failure" }));
     });
+
+    test("should reject unsupported renderOnLoad outputs", () => {
+        const plugin = new InvalidRenderOnLoadPlugin();
+        expect(() => plugin.serializeRenderOnLoad()).toThrow(
+            "Method 'renderOnLoad' must return a synchronous string, function, or defineRenderOnLoad(...) module."
+        );
+    });
 });
diff --git a/tests/utils/capabilities.test.ts b/tests/utils/capabilities.test.ts
index afe51f0..822cbd2 100644
--- a/tests/utils/capabilities.test.ts
+++ b/tests/utils/capabilities.test.ts
@@ -1,15 +1,21 @@
 import {
     createCapabilityBundle,
     createFilesystemCapabilityBundle,
+    createNetworkCapabilityBundle,
+    createNetworkScopeCapability,
     createProcessCapabilityBundle,
+    createStorageCapabilityBundle,
     createWorkflowCapabilityBundle,
     describeCapability,
     parseMissingCapabilityError,
     configureCapabilities,
     getCapabilityDiagnostics,
+    runCapabilityPreflight,
     requireCapability,
     requireFilesystemScopeCapability,
+    requireNetworkScopeCapability,
     requireProcessScopeCapability,
+    requireStorageBackendCapability,
     requireWorkflowProcessCapabilities,
     resetCapabilityStateForTests,
 } from "../../src/utils/capabilities";
@@ -20,12 +26,15 @@ describe("capabilities", () => {
     });
 
     test("allows granted capabilities", () => {
-        configureCapabilities({ granted: ["storage.json"] });
+        configureCapabilities({ granted: ["storage", "storage.json"] });
+        expect(() => requireStorageBackendCapability("json", "write persistent state")).not.toThrow();
         expect(() => requireCapability("storage.json", "write persistent state")).not.toThrow();
 
         const diagnostics = getCapabilityDiagnostics();
-        expect(diagnostics.granted).toEqual(["storage.json"]);
-        expect(diagnostics.usageCount["storage.json"]).toBe(1);
+        expect(diagnostics.granted).toEqual(["storage", "storage.json"]);
+        expect(diagnostics.usageCount["storage"]).toBe(1);
+        expect(diagnostics.usageCount["storage.json"]).toBe(2);
+        expect(diagnostics.deniedCount["storage"]).toBeUndefined();
         expect(diagnostics.deniedCount["storage.json"]).toBeUndefined();
     });
 
@@ -41,6 +50,14 @@ describe("capabilities", () => {
         expect(diagnostics.deniedCount["sudo.prompt"]).toBe(1);
     });
 
+    test("treats host write capability aliases as equivalent", () => {
+        configureCapabilities({ granted: ["system.host.write"] });
+        expect(() => requireCapability("system.hosts.write", "write hosts data")).not.toThrow();
+
+        configureCapabilities({ granted: ["system.hosts.write"] });
+        expect(() => requireCapability("system.host.write", "write host-scoped data")).not.toThrow();
+    });
+
     test("validates and checks filesystem scope capabilities", () => {
         configureCapabilities({ granted: ["system.fs.scope.etc-hosts"] });
         expect(() => requireFilesystemScopeCapability("etc hosts", "mutate /etc/hosts")).not.toThrow();
@@ -57,6 +74,14 @@ describe("capabilities", () => {
         expect(diagnostics.usageCount["system.process.scope.docker-cli"]).toBe(1);
     });
 
+    test("validates and checks network scope capabilities", () => {
+        configureCapabilities({ granted: ["system.network.scope.public-web-secure"] });
+        expect(() => requireNetworkScopeCapability("public web secure", "reach approved public HTTPS endpoints")).not.toThrow();
+
+        const diagnostics = getCapabilityDiagnostics();
+        expect(diagnostics.usageCount["system.network.scope.public-web-secure"]).toBe(1);
+    });
+
     test("creates deduplicated capability bundles", () => {
         expect(createCapabilityBundle([
             "system.process.exec",
@@ -81,6 +106,23 @@ describe("capabilities", () => {
             "system.process.exec",
             "system.process.scope.terraform",
         ]);
+        expect(createStorageCapabilityBundle("json")).toEqual([
+            "storage",
+            "storage.json",
+        ]);
+        expect(createNetworkCapabilityBundle(["https"])).toEqual([
+            "system.network",
+            "system.network.https",
+        ]);
+        expect(createNetworkScopeCapability("public web secure")).toBe("system.network.scope.public-web-secure");
+        expect(createNetworkCapabilityBundle({
+            transports: ["https"],
+            scopeId: "public web secure",
+        })).toEqual([
+            "system.network",
+            "system.network.https",
+            "system.network.scope.public-web-secure",
+        ]);
     });
 
     test("requires existing process capabilities for scoped workflows", () => {
@@ -93,6 +135,20 @@ describe("capabilities", () => {
     });
 
     test("describes broad and scoped capabilities", () => {
+        expect(describeCapability("storage")).toEqual({
+            capability: "storage",
+            label: "Storage",
+            description: "Base capability family for plugin-managed persistent storage backends.",
+            category: "storage",
+        });
+
+        expect(describeCapability("storage.json")).toEqual({
+            capability: "storage.json",
+            label: "JSON Storage Backend",
+            description: 'Allows the plugin to use the persistent JSON store backend (requires base capability "storage").',
+            category: "storage",
+        });
+
         expect(describeCapability("system.clipboard.read")).toEqual({
             capability: "system.clipboard.read",
             label: "Clipboard Read",
@@ -114,6 +170,27 @@ describe("capabilities", () => {
             category: "process",
         });
 
+        expect(describeCapability("system.network")).toEqual({
+            capability: "system.network",
+            label: "Network",
+            description: "Base network capability family. Pair with concrete transport capabilities such as system.network.https.",
+            category: "network",
+        });
+
+        expect(describeCapability("system.network.https")).toEqual({
+            capability: "system.network.https",
+            label: "Network HTTPS",
+            description: "Allows outbound HTTPS requests through host-approved runtime network APIs.",
+            category: "network",
+        });
+
+        expect(describeCapability("system.network.scope.public-web-secure")).toEqual({
+            capability: "system.network.scope.public-web-secure",
+            label: "Network Scope: public-web-secure",
+            description: 'Allows host-defined network scope access inside "public-web-secure". Pair with system.network and required transport capabilities.',
+            category: "network-scope",
+        });
+
         expect(describeCapability("system.process.scope.kubectl")).toEqual({
             capability: "system.process.scope.kubectl",
             label: "Process Scope: kubectl",
@@ -122,6 +199,18 @@ describe("capabilities", () => {
         });
     });
 
+    test("requires storage base and backend capabilities for storage helpers", () => {
+        configureCapabilities({ granted: ["storage"] });
+        expect(() => requireStorageBackendCapability("json", "use persistent json backend")).toThrow(
+            'Capability "storage.json" is required to use persistent json backend. Configure PluginRegistry.configureCapabilities({ granted: ["storage.json"] }) in the host before plugin initialization.'
+        );
+
+        configureCapabilities({ granted: ["storage.json"] });
+        expect(() => requireStorageBackendCapability("json", "use persistent json backend")).toThrow(
+            'Capability "storage" is required to use persistent json backend. Configure PluginRegistry.configureCapabilities({ granted: ["storage"] }) in the host before plugin initialization.'
+        );
+    });
+
     test("parses missing capability errors into structured remediation", () => {
         let thrownError: unknown;
         try {
@@ -136,10 +225,57 @@ describe("capabilities", () => {
             category: "process",
             label: "Scoped Tool Execution",
             description: "Allows host-mediated execution of allowlisted operational tools when paired with a process scope capability.",
-            remediation: 'Grant "system.process.exec" in the host capability configuration before plugin initialization.',
+            remediation: 'Grant "system.process.exec" in the host capability configuration before plugin initialization. Configure PluginRegistry.configureCapabilities({ granted: ["system.process.exec"] }) in the host before plugin initialization.',
         });
     });
 
+    test("builds preflight diagnostics for missing capabilities and prerequisites", () => {
+        const report = runCapabilityPreflight({
+            declared: ["storage.json"],
+            granted: [],
+            action: "initialize plugin runtime",
+        });
+
+        expect(report.ok).toBe(false);
+        expect(report.summary).toBe("Missing 1 declared capability (storage.json).");
+        expect(report.missing).toEqual([
+            {
+                capability: "storage.json",
+                action: "initialize plugin runtime",
+                category: "storage",
+                label: "JSON Storage Backend",
+                description: 'Allows the plugin to use the persistent JSON store backend (requires base capability "storage").',
+                remediation: 'Grant "storage.json" with prerequisite capabilities "storage" before plugin initialization. Configure PluginRegistry.configureCapabilities({ granted: ["storage", "storage.json"] }) in the host before plugin initialization.',
+                requiredCapabilities: ["storage", "storage.json"],
+                missingPrerequisites: ["storage"],
+                grantedPrerequisites: [],
+            },
+        ]);
+        expect(report.remediations).toEqual([
+            'Grant "storage.json" with prerequisite capabilities "storage" before plugin initialization. Configure PluginRegistry.configureCapabilities({ granted: ["storage", "storage.json"] }) in the host before plugin initialization.',
+        ]);
+    });
+
+    test("reports undeclared granted capabilities in preflight output", () => {
+        const report = runCapabilityPreflight({
+            declared: ["system.process.exec"],
+            granted: ["system.process.exec", "system.process.scope.git"],
+            action: "validate declared capabilities",
+        });
+
+        expect(report.ok).toBe(true);
+        expect(report.summary).toBe("All declared capabilities are granted.");
+        expect(report.missing).toEqual([]);
+        expect(report.undeclaredGranted).toEqual([
+            {
+                capability: "system.process.scope.git",
+                label: "Process Scope: git",
+                description: 'Allows scoped process execution inside the "git" host policy.',
+                category: "process-scope",
+            },
+        ]);
+    });
+
     test("returns null for non-capability errors", () => {
         expect(parseMissingCapabilityError(new Error("something else"))).toBeNull();
     });
diff --git a/tests/utils/editorSupport.test.ts b/tests/utils/editorSupport.test.ts
new file mode 100644
index 0000000..beb536a
--- /dev/null
+++ b/tests/utils/editorSupport.test.ts
@@ -0,0 +1,86 @@
+import {
+    getEditorSupportBundle,
+    getEditorSupportMonacoPolicy,
+    getEditorSupportPackageJson,
+    getEditorSupportPackageManifest,
+    SDK_EDITOR_INDEX_TYPES_VIRTUAL_PATH,
+    SDK_EDITOR_MODULE_ID,
+    SDK_EDITOR_PACKAGE_JSON_VIRTUAL_PATH,
+} from "../../src/utils/editorSupport";
+
+describe("editor support helpers", () => {
+    test("returns default editor package manifest", () => {
+        const manifest = getEditorSupportPackageManifest();
+
+        expect(manifest.name).toBe(SDK_EDITOR_MODULE_ID);
+        expect(manifest.private).toBe(true);
+        expect(manifest.types).toBe("./index.d.ts");
+        expect(manifest.exports["."].types).toBe("./index.d.ts");
+    });
+
+    test("applies manifest overrides predictably", () => {
+        const manifest = getEditorSupportPackageManifest({
+            private: false,
+            exports: {
+                ".": {
+                    types: "./custom-index.d.ts",
+                    default: "./custom.js",
+                },
+            },
+        });
+
+        expect(manifest.private).toBe(false);
+        expect(manifest.exports["."].types).toBe("./custom-index.d.ts");
+        expect(manifest.exports["."].default).toBe("./custom.js");
+    });
+
+    test("serializes package manifest as JSON", () => {
+        const manifest = getEditorSupportPackageManifest();
+        const json = getEditorSupportPackageJson(manifest);
+        const parsed = JSON.parse(json);
+
+        expect(parsed).toEqual(manifest);
+    });
+
+    test("returns full editor support bundle", () => {
+        const bundle = getEditorSupportBundle();
+
+        expect(bundle.moduleId).toBe(SDK_EDITOR_MODULE_ID);
+        expect(bundle.packageJson).toContain("\"types\": \"./index.d.ts\"");
+        expect(bundle.renderOnLoadTypeDefinitions).toContain("declare namespace FDOOnLoad");
+        expect(Array.isArray(bundle.renderOnLoadHints)).toBe(true);
+        expect(bundle.renderOnLoadHints.length).toBeGreaterThan(0);
+    });
+
+    test("creates monaco policy that injects package.json when SDK index exists", () => {
+        const policy = getEditorSupportMonacoPolicy({ hasSdkIndex: true });
+
+        expect(policy.moduleId).toBe(SDK_EDITOR_MODULE_ID);
+        expect(policy.hasSdkIndex).toBe(true);
+        expect(policy.shouldInjectPackageJson).toBe(true);
+        expect(policy.packageJsonVirtualPath).toBe(SDK_EDITOR_PACKAGE_JSON_VIRTUAL_PATH);
+        expect(policy.indexTypesVirtualPath).toBe(SDK_EDITOR_INDEX_TYPES_VIRTUAL_PATH);
+        expect(policy.packageJson).toContain("\"name\": \"@anikitenko/fdo-sdk\"");
+    });
+
+    test("uses namespace-only fallback policy when SDK index is missing", () => {
+        const policy = getEditorSupportMonacoPolicy({ hasSdkIndex: false });
+
+        expect(policy.hasSdkIndex).toBe(false);
+        expect(policy.shouldInjectPackageJson).toBe(false);
+        expect(policy.preferNamespaceFallback).toBe(true);
+        expect(policy.allowModuleFallback).toBe(false);
+        expect(policy.namespaceFallbackTypeDefinitions).toContain("declare namespace FDOOnLoad");
+        expect(policy.namespaceFallbackTypeDefinitions).not.toContain("declare module \"@anikitenko/fdo-sdk\"");
+        expect(policy.deprecatedModuleFallbackPattern).toBe("declare module \"@anikitenko/fdo-sdk\"");
+    });
+
+    test("honors explicit namespace fallback overrides", () => {
+        const policy = getEditorSupportMonacoPolicy({
+            hasSdkIndex: false,
+            namespaceFallbackTypeDefinitions: "declare namespace FDOOnLoad { interface Marker {} }",
+        });
+
+        expect(policy.namespaceFallbackTypeDefinitions).toContain("interface Marker");
+    });
+});
diff --git a/tests/utils/fixtureRuntimeMatrix.test.ts b/tests/utils/fixtureRuntimeMatrix.test.ts
new file mode 100644
index 0000000..62ce213
--- /dev/null
+++ b/tests/utils/fixtureRuntimeMatrix.test.ts
@@ -0,0 +1,49 @@
+import {
+    getFixtureRuntimeMatrix,
+    getFixtureRuntimeMatrixCase,
+    listFixtureRuntimeMatrixCases,
+} from "../../src";
+
+describe("fixture runtime matrix helpers", () => {
+    test("returns versioned fixture runtime matrix with expected fixture ids", () => {
+        const matrix = getFixtureRuntimeMatrix();
+
+        expect(matrix.contractVersion).toBe("1");
+        expect(matrix.cases.map((entry) => entry.id)).toEqual([
+            "minimal",
+            "error-handling",
+            "storage",
+            "operator-kubernetes",
+            "operator-terraform",
+            "operator-custom-tool",
+        ]);
+    });
+
+    test("returns cloned fixture entries so callers cannot mutate source definitions", () => {
+        const cases = listFixtureRuntimeMatrixCases();
+        cases[0].title = "mutated";
+        cases[1].probes.uiMessage.push({ handler: "mutated.handler", content: {} });
+
+        const matrix = getFixtureRuntimeMatrix();
+        expect(matrix.cases[0].title).toBe("Fixture: Minimal Plugin");
+        expect(matrix.cases[1].probes.uiMessage.map((probe) => probe.handler)).toEqual([
+            "fixture.ok",
+            "fixture.fail",
+        ]);
+    });
+
+    test("returns null for unknown fixture case id", () => {
+        expect(getFixtureRuntimeMatrixCase("missing-case")).toBeNull();
+    });
+
+    test("returns the storage fixture case with required storage capabilities", () => {
+        const entry = getFixtureRuntimeMatrixCase("storage");
+        expect(entry).not.toBeNull();
+        expect(entry?.requiredCapabilities).toEqual(["storage", "storage.json"]);
+        expect(entry?.probes.uiMessage.map((probe) => probe.handler)).toEqual([
+            "storageFixture.v2.getSnapshot",
+            "storageFixture.v2.savePreference",
+            "storageFixture.v2.recordAction",
+        ]);
+    });
+});
diff --git a/tests/utils/handshake.test.ts b/tests/utils/handshake.test.ts
new file mode 100644
index 0000000..a2ceaa3
--- /dev/null
+++ b/tests/utils/handshake.test.ts
@@ -0,0 +1,97 @@
+import {
+    evaluateSdkHandshakeCompatibility,
+    FDO_SDK,
+    getSdkFeatureFlags,
+    getSdkHandshake,
+    isSdkHandshakeCompatible,
+} from "../../src";
+
+describe("sdk handshake helpers", () => {
+    test("returns deterministic handshake payload shape", () => {
+        const handshake = getSdkHandshake();
+
+        expect(handshake.contractVersion).toBe("1.0.0");
+        expect(handshake.capabilitySchemaVersion).toBe("1.0.0");
+        expect(handshake.apiVersion).toBe(FDO_SDK.API_VERSION);
+        expect(typeof handshake.sdkVersion).toBe("string");
+        expect(handshake.sdkVersion.length).toBeGreaterThan(0);
+    });
+
+    test("returns feature flags as a copy", () => {
+        const flags = getSdkFeatureFlags();
+        expect(flags).toEqual({
+            diagnosticsHandler: true,
+            pluginDoctorReport: true,
+            declaredCapabilityPreflight: true,
+            privilegedActionTransportPipeline: true,
+            renderOnLoadModuleAuthoring: true,
+            renderOnLoadDeclarativeActions: true,
+            editorSupportBundle: true,
+        });
+
+        flags.pluginDoctorReport = false;
+        expect(getSdkFeatureFlags().pluginDoctorReport).toBe(true);
+    });
+
+    test("reports incompatible status for API major mismatch", () => {
+        const handshake = getSdkHandshake();
+        const report = evaluateSdkHandshakeCompatibility(handshake, {
+            expectedApiVersion: "2.0.0",
+        });
+
+        expect(report.ok).toBe(false);
+        expect(report.status).toBe("incompatible");
+        expect(report.issues.some((issue) => issue.code === "HANDSHAKE_API_INCOMPATIBLE")).toBe(true);
+        expect(isSdkHandshakeCompatible(handshake, { expectedApiVersion: "2.0.0" })).toBe(false);
+    });
+
+    test("reports warning status for missing required feature flag by default", () => {
+        const handshake = getSdkHandshake();
+        const report = evaluateSdkHandshakeCompatibility(handshake, {
+            requiredFeatureFlags: ["pluginDoctorReport", "editorSupportBundle"],
+        });
+        expect(report.ok).toBe(true);
+        expect(report.status).toBe("compatible");
+
+        const downgraded = evaluateSdkHandshakeCompatibility(
+            {
+                ...handshake,
+                featureFlags: {
+                    ...handshake.featureFlags,
+                    pluginDoctorReport: false,
+                },
+            },
+            {
+                requiredFeatureFlags: ["pluginDoctorReport"],
+            }
+        );
+
+        expect(downgraded.ok).toBe(true);
+        expect(downgraded.status).toBe("needs-attention");
+        expect(downgraded.issues).toEqual([
+            {
+                code: "HANDSHAKE_FEATURE_FLAG_MISSING",
+                severity: "warning",
+                message: 'Required SDK feature flag "pluginDoctorReport" is not enabled.',
+                expected: "true",
+                received: "false",
+                featureFlag: "pluginDoctorReport",
+            },
+        ]);
+    });
+
+    test("supports strict mode for capability schema and feature flags", () => {
+        const handshake = getSdkHandshake();
+        const report = evaluateSdkHandshakeCompatibility(handshake, {
+            expectedCapabilitySchemaVersion: "2.0.0",
+            capabilitySchemaSeverity: "error",
+            requiredFeatureFlags: ["renderOnLoadDeclarativeActions"],
+            featureFlagSeverity: "error",
+        });
+
+        expect(report.ok).toBe(false);
+        expect(report.status).toBe("incompatible");
+        expect(report.counts.error).toBe(1);
+        expect(report.issues[0].code).toBe("HANDSHAKE_CAPABILITY_SCHEMA_MISMATCH");
+    });
+});
diff --git a/tests/utils/migrationCodemod.test.ts b/tests/utils/migrationCodemod.test.ts
new file mode 100644
index 0000000..18513cd
--- /dev/null
+++ b/tests/utils/migrationCodemod.test.ts
@@ -0,0 +1,57 @@
+import { applySdkMigrationCodemod } from "../../src/utils/migrationCodemod";
+
+describe("sdk migration codemod", () => {
+    test("replaces legacy privileged envelope fallback chain and injects helper import", () => {
+        const input = [
+            "async function run() {",
+            "  const envelope = await window.createBackendReq(\"UI_MESSAGE\", {});",
+            "  const requestPayload = envelope?.result?.request ?? envelope?.request ?? envelope;",
+            "  return requestPayload;",
+            "}",
+            "",
+        ].join("\n");
+
+        const result = applySdkMigrationCodemod(input);
+
+        expect(result.changed).toBe(true);
+        expect(result.output).toContain("import { extractPrivilegedActionRequest } from \"@anikitenko/fdo-sdk\";");
+        expect(result.output).toContain("const requestPayload = extractPrivilegedActionRequest(envelope);");
+        expect(result.changes.some((entry) => entry.rule === "privileged-envelope-extract-helper")).toBe(true);
+    });
+
+    test("extends existing sdk import without duplicating entries", () => {
+        const input = [
+            "import { requestPrivilegedAction } from \"@anikitenko/fdo-sdk\";",
+            "",
+            "const envelope = payload;",
+            "const requestPayload = envelope?.result?.request ?? envelope?.request ?? envelope;",
+            "",
+        ].join("\n");
+
+        const result = applySdkMigrationCodemod(input);
+        expect(result.changed).toBe(true);
+        expect(result.output).toContain("import { requestPrivilegedAction, extractPrivilegedActionRequest } from \"@anikitenko/fdo-sdk\";");
+    });
+
+    test("replaces deprecated configureCapabilityPolicy usage", () => {
+        const input = "PluginRegistry.configureCapabilityPolicy({ granted: [\"storage\", \"storage.json\"] });";
+        const result = applySdkMigrationCodemod(input);
+
+        expect(result.changed).toBe(true);
+        expect(result.output).toBe("PluginRegistry.configureCapabilities({ granted: [\"storage\", \"storage.json\"] });");
+        expect(result.changes.some((entry) => entry.rule === "plugin-registry-configure-capabilities")).toBe(true);
+    });
+
+    test("is idempotent when source already uses modern patterns", () => {
+        const input = [
+            "import { extractPrivilegedActionRequest } from \"@anikitenko/fdo-sdk\";",
+            "const requestPayload = extractPrivilegedActionRequest(envelope);",
+            "PluginRegistry.configureCapabilities({ granted: [] });",
+        ].join("\n");
+
+        const result = applySdkMigrationCodemod(input);
+        expect(result.changed).toBe(false);
+        expect(result.output).toBe(input);
+        expect(result.changes).toEqual([]);
+    });
+});
diff --git a/tests/utils/pluginDoctor.test.ts b/tests/utils/pluginDoctor.test.ts
new file mode 100644
index 0000000..908c1f0
--- /dev/null
+++ b/tests/utils/pluginDoctor.test.ts
@@ -0,0 +1,168 @@
+import {
+    createPluginDoctorReport,
+    getSdkHandshake,
+    PluginDiagnostics,
+} from "../../src";
+
+function createBaseDiagnostics(): PluginDiagnostics {
+    return {
+        apiVersion: "1.0.0",
+        pluginId: "tests-plugin",
+        metadata: {
+            id: "tests-plugin",
+            name: "Tests Plugin",
+            version: "1.0.0",
+            author: "Test",
+            description: "Test diagnostics",
+            icon: "cog",
+        },
+        handshake: getSdkHandshake(),
+        health: {
+            status: "healthy",
+            startedAt: new Date("2026-04-15T10:00:00.000Z").toISOString(),
+            initCount: 1,
+            renderCount: 1,
+            handlerCount: 1,
+            errorCount: 0,
+        },
+        capabilities: {
+            diagnosticsHandler: "__sdk.getDiagnostics",
+            registeredHandlers: ["ping"],
+            registeredStores: ["default", "json"],
+            quickActionsCount: 0,
+            hasSidePanel: false,
+            stores: [],
+            declaration: {
+                declared: ["system.process.exec", "system.process.scope.git"],
+                missing: [],
+                undeclaredGranted: [],
+            },
+            permissions: {
+                granted: ["system.process.exec", "system.process.scope.git"],
+                usageCount: {},
+                deniedCount: {},
+            },
+        },
+        notifications: {
+            count: 0,
+            capacity: 100,
+            recent: [],
+        },
+    };
+}
+
+describe("plugin doctor", () => {
+    test("returns healthy report when no errors or warnings exist", () => {
+        const report = createPluginDoctorReport(createBaseDiagnostics(), {
+            includeInfo: false,
+        });
+
+        expect(report.status).toBe("healthy");
+        expect(report.counts).toEqual({
+            error: 0,
+            warning: 0,
+            info: 0,
+        });
+        expect(report.findings).toEqual([]);
+        expect(report.summary).toBe("No error or warning findings. Plugin diagnostics look healthy.");
+    });
+
+    test("adds warning findings for missing declared capabilities with remediation", () => {
+        const diagnostics = createBaseDiagnostics();
+        diagnostics.capabilities.declaration.declared = ["storage.json"];
+        diagnostics.capabilities.permissions.granted = [];
+
+        const report = createPluginDoctorReport(diagnostics, {
+            includeInfo: false,
+        });
+        const capabilityFinding = report.findings.find((entry) => entry.code === "CAPABILITY_DECLARED_MISSING");
+
+        expect(report.status).toBe("needs-attention");
+        expect(report.counts.warning).toBe(1);
+        expect(capabilityFinding?.severity).toBe("warning");
+        expect(capabilityFinding?.remediation).toContain('Configure PluginRegistry.configureCapabilities({ granted: ["storage", "storage.json"] })');
+    });
+
+    test("marks report degraded when health diagnostics are degraded", () => {
+        const diagnostics = createBaseDiagnostics();
+        diagnostics.health.status = "degraded";
+        diagnostics.health.errorCount = 2;
+        diagnostics.health.lastErrorAt = new Date("2026-04-15T10:05:00.000Z").toISOString();
+        diagnostics.health.lastErrorMessage = "boom";
+        diagnostics.capabilities.permissions.deniedCount = {
+            "system.process.exec": 3,
+        };
+
+        const report = createPluginDoctorReport(diagnostics, {
+            includeInfo: false,
+        });
+
+        expect(report.status).toBe("degraded");
+        expect(report.counts.error).toBe(1);
+        expect(report.counts.warning).toBe(1);
+        expect(report.findings.some((entry) => entry.code === "HEALTH_DEGRADED")).toBe(true);
+        expect(report.findings.some((entry) => entry.code === "CAPABILITY_RUNTIME_DENIED")).toBe(true);
+    });
+
+    test("can suppress info and notification-stream findings via options", () => {
+        const diagnostics = createBaseDiagnostics();
+        diagnostics.capabilities.registeredHandlers = [];
+        diagnostics.capabilities.permissions.granted = [
+            "system.process.exec",
+            "system.process.scope.git",
+            "system.process.scope.kubectl",
+        ];
+        diagnostics.notifications.recent = [
+            {
+                message: "backend failure",
+                type: "error",
+                timestamp: new Date("2026-04-15T10:10:00.000Z").toISOString(),
+            },
+        ];
+        diagnostics.notifications.count = 100;
+        diagnostics.notifications.capacity = 100;
+
+        const report = createPluginDoctorReport(diagnostics, {
+            includeInfo: false,
+            includeNotificationFindings: false,
+        });
+
+        expect(report.status).toBe("healthy");
+        expect(report.findings).toEqual([]);
+    });
+
+    test("adds handshake findings when host expectations are not satisfied", () => {
+        const diagnostics = createBaseDiagnostics();
+        const report = createPluginDoctorReport(diagnostics, {
+            includeInfo: false,
+            handshake: {
+                expectedApiVersion: "2.0.0",
+                expectedCapabilitySchemaVersion: "2.0.0",
+                requiredFeatureFlags: ["pluginDoctorReport"],
+                capabilitySchemaSeverity: "error",
+            },
+        });
+
+        expect(report.status).toBe("degraded");
+        expect(report.counts.error).toBe(2);
+        expect(report.findings.some((entry) => entry.code === "HANDSHAKE_API_INCOMPATIBLE")).toBe(true);
+        expect(report.findings.some((entry) => entry.code === "HANDSHAKE_CAPABILITY_SCHEMA_MISMATCH")).toBe(true);
+    });
+
+    test("supports warning-only handshake findings", () => {
+        const diagnostics = createBaseDiagnostics();
+        diagnostics.handshake.featureFlags.pluginDoctorReport = false;
+        const report = createPluginDoctorReport(diagnostics, {
+            includeInfo: false,
+            handshake: {
+                requiredFeatureFlags: ["pluginDoctorReport"],
+            },
+        });
+
+        expect(report.status).toBe("needs-attention");
+        const finding = report.findings.find((entry) => entry.code === "HANDSHAKE_FEATURE_FLAG_MISSING");
+        expect(finding?.category).toBe("handshake");
+        expect(finding?.severity).toBe("warning");
+        expect(finding?.remediation).toContain("Required SDK feature flag not available");
+    });
+});
diff --git a/tests/utils/pluginDoctorPanel.test.ts b/tests/utils/pluginDoctorPanel.test.ts
new file mode 100644
index 0000000..6e02f50
--- /dev/null
+++ b/tests/utils/pluginDoctorPanel.test.ts
@@ -0,0 +1,98 @@
+import {
+    createPluginDoctorPanelModel,
+    createPluginDoctorReport,
+    getSdkHandshake,
+    PluginDiagnostics,
+} from "../../src";
+
+function createDiagnostics(): PluginDiagnostics {
+    return {
+        apiVersion: "1.0.0",
+        pluginId: "panel-tests-plugin",
+        metadata: {
+            id: "panel-tests-plugin",
+            name: "Panel Tests Plugin",
+            version: "1.0.0",
+            author: "Test",
+            description: "Test diagnostics",
+            icon: "cog",
+        },
+        handshake: getSdkHandshake(),
+        health: {
+            status: "degraded",
+            startedAt: new Date("2026-04-15T10:00:00.000Z").toISOString(),
+            initCount: 1,
+            renderCount: 1,
+            handlerCount: 1,
+            errorCount: 1,
+            lastErrorMessage: "boom",
+        },
+        capabilities: {
+            diagnosticsHandler: "__sdk.getDiagnostics",
+            registeredHandlers: [],
+            registeredStores: ["default"],
+            quickActionsCount: 0,
+            hasSidePanel: false,
+            stores: [],
+            declaration: {
+                declared: ["storage.json"],
+                missing: [],
+                undeclaredGranted: [],
+            },
+            permissions: {
+                granted: ["storage"],
+                usageCount: {},
+                deniedCount: {
+                    "system.process.exec": 2,
+                },
+            },
+        },
+        notifications: {
+            count: 100,
+            capacity: 100,
+            recent: [
+                {
+                    message: "runtime failed",
+                    type: "error",
+                    timestamp: new Date("2026-04-15T10:05:00.000Z").toISOString(),
+                },
+            ],
+        },
+    };
+}
+
+describe("plugin doctor panel model", () => {
+    test("builds deterministic prioritized findings with exact fix", () => {
+        const report = createPluginDoctorReport(createDiagnostics(), {
+            handshake: {
+                expectedApiVersion: "2.0.0",
+            },
+        });
+        const model = createPluginDoctorPanelModel(report);
+
+        expect(model.blocking).toBe(true);
+        expect(model.status).toBe("degraded");
+        expect(model.prioritizedFindings.length).toBeGreaterThan(0);
+        expect(model.prioritizedFindings[0].severity).toBe("error");
+        expect(model.prioritizedFindings.some((finding) => finding.code === "HANDSHAKE_API_INCOMPATIBLE")).toBe(true);
+        const handshakeFinding = model.prioritizedFindings.find((finding) => finding.code === "HANDSHAKE_API_INCOMPATIBLE");
+        expect(handshakeFinding?.exactFix).toContain("SDK/Host API major mismatch");
+    });
+
+    test("supports info filtering and prioritized limit", () => {
+        const report = createPluginDoctorReport(createDiagnostics(), {
+            includeInfo: true,
+            handshake: {
+                expectedApiVersion: "2.0.0",
+            },
+        });
+        const model = createPluginDoctorPanelModel(report, {
+            includeInfoFindings: false,
+            maxPrioritizedFindings: 2,
+        });
+
+        expect(model.counts.info).toBe(0);
+        expect(model.prioritizedFindings.length).toBe(2);
+        expect(model.sections.every((section) => section.findings.every((finding) => finding.severity !== "info"))).toBe(true);
+    });
+});
diff --git a/tests/utils/privilegedResponses.test.ts b/tests/utils/privilegedResponses.test.ts
index 7d42e2c..f6e1d2c 100644
--- a/tests/utils/privilegedResponses.test.ts
+++ b/tests/utils/privilegedResponses.test.ts
@@ -1,5 +1,7 @@
 import {
     createPrivilegedActionCorrelationId,
+    formatPrivilegedActionError,
+    getInlinePrivilegedActionErrorFormatterSource,
     isPrivilegedActionErrorResponse,
     isPrivilegedActionSuccessResponse,
     unwrapPrivilegedActionResponse,
@@ -53,4 +55,48 @@ describe("privileged response helpers", () => {
             code: "CAPABILITY_MISSING",
         })).toThrow("denied");
     });
+
+    test("formats privileged action errors with process result details", () => {
+        const message = formatPrivilegedActionError({
+            ok: false,
+            correlationId: "priv-42",
+            code: "PROCESS_EXIT_NON_ZERO",
+            error: "Process exited with code 128.",
+            result: {
+                stderr: "fatal: cannot change to '/missing/path': No such file or directory",
+                exitCode: 128,
+                command: "/usr/bin/git",
+                args: ["-C", "/missing/path", "status"],
+                cwd: "/Users/alexvwan",
+            },
+        }, { context: "Git operation failed" });
+
+        expect(message).toContain("Git operation failed (PROCESS_EXIT_NON_ZERO): Process exited with code 128.");
+        expect(message).toContain("stderr: fatal: cannot change to '/missing/path': No such file or directory");
+        expect(message).toContain("exitCode: 128");
+        expect(message).toContain("command: /usr/bin/git -C /missing/path status");
+        expect(message).toContain("cwd: /Users/alexvwan");
+        expect(message).toContain("Correlation ID: priv-42");
+    });
+
+    test("builds inline formatter source for renderOnLoad runtimes", () => {
+        const formatterFactory = Function(`return ${getInlinePrivilegedActionErrorFormatterSource()};`);
+        const formatter = formatterFactory() as (response: unknown, options?: { context?: string }) => string;
+
+        const message = formatter({
+            ok: false,
+            code: "CAPABILITY_MISSING",
+            error: "Missing capability",
+            result: {
+                stdout: "fallback output",
+            },
+        }, {
+            context: "Operator request failed",
+        });
+
+        expect(typeof formatter).toBe("function");
+        expect(message).toContain("Operator request failed (CAPABILITY_MISSING): Missing capability");
+        expect(message).toContain("stdout: fallback output");
+        expect(message).toContain("Correlation ID: unknown");
+    });
 });
diff --git a/tests/utils/privilegedTransport.test.ts b/tests/utils/privilegedTransport.test.ts
index 5465912..cbfefdc 100644
--- a/tests/utils/privilegedTransport.test.ts
+++ b/tests/utils/privilegedTransport.test.ts
@@ -1,6 +1,8 @@
 import {
     createFilesystemMutateActionRequest,
     createPrivilegedActionBackendRequest,
+    extractPrivilegedActionRequest,
+    requestPrivilegedActionFromEnvelope,
     requestPrivilegedAction,
 } from "../../src";
 
@@ -55,6 +57,44 @@ describe("privileged transport helpers", () => {
         });
     });
 
+    test("extracts request from wrapped UI_MESSAGE success payloads", () => {
+        const request = createRequest();
+
+        expect(extractPrivilegedActionRequest({
+            ok: true,
+            result: {
+                correlationId: "corr-1",
+                request,
+            },
+        })).toEqual(request);
+    });
+
+    test("extracts request from backend envelope payloads", () => {
+        const request = createRequest();
+
+        expect(extractPrivilegedActionRequest({
+            correlationId: "corr-2",
+            request,
+        })).toEqual(request);
+    });
+
+    test("accepts direct privileged action requests unchanged", () => {
+        const request = createRequest();
+
+        expect(extractPrivilegedActionRequest(request)).toEqual(request);
+    });
+
+    test("fails with a descriptive error for malformed envelopes", () => {
+        expect(() => extractPrivilegedActionRequest({
+            ok: true,
+            result: {
+                correlationId: "corr-3",
+            },
+        })).toThrow(
+            "Could not extract a valid privileged action request from the provided envelope or request."
+        );
+    });
+
     test("sends privileged action through the default host handler", async () => {
         const createBackendReq = vi.fn().mockResolvedValue({
             ok: true,
@@ -109,4 +149,59 @@ describe("privileged transport helpers", () => {
             "requestPrivilegedAction is only available in the plugin iframe runtime."
         );
     });
+
+    test("runs envelope pipeline and returns formatted error details on host denial", async () => {
+        const request = createRequest();
+        const createBackendReq = vi.fn().mockResolvedValue({
+            ok: false,
+            correlationId: "priv-100",
+            error: 'Process "git" exited with code 128.',
+            code: "PROCESS_EXIT_NON_ZERO",
+            result: {
+                command: "git",
+                args: ["status"],
+                cwd: "/tmp/missing-repo",
+                stderr: "fatal: not a git repository (or any of the parent directories): .git",
+                exitCode: 128,
+            },
+        });
+        globalThis.window = { createBackendReq } as unknown as Window;
+
+        const pipeline = await requestPrivilegedActionFromEnvelope({
+            ok: true,
+            result: {
+                correlationId: "backend-correlation",
+                request,
+            },
+        }, {
+            context: "Git operation failed",
+        });
+
+        expect(createBackendReq).toHaveBeenCalledWith("requestPrivilegedAction", {
+            correlationId: expect.stringMatching(/^privileged-action-\d+$/),
+            request,
+        });
+        expect(pipeline.request).toEqual(request);
+        expect(pipeline.response.ok).toBe(false);
+        expect(pipeline.errorMessage).toContain('Git operation failed (PROCESS_EXIT_NON_ZERO): Process "git" exited with code 128.');
+        expect(pipeline.errorMessage).toContain("stderr: fatal: not a git repository");
+        expect(pipeline.errorMessage).toContain("command: git status");
+        expect(pipeline.errorMessage).toContain("cwd: /tmp/missing-repo");
+        expect(pipeline.errorMessage).toContain("Correlation ID: priv-100");
+    });
+
+    test("pipeline helper can throw formatted errors for non-ok responses", async () => {
+        const createBackendReq = vi.fn().mockResolvedValue({
+            ok: false,
+            correlationId: "priv-200",
+            error: "denied",
+            code: "CAPABILITY_MISSING",
+        });
+        globalThis.window = { createBackendReq } as unknown as Window;
+
+        await expect(requestPrivilegedActionFromEnvelope(createRequest(), {
+            throwOnError: true,
+            context: "Privileged action failed",
+        })).rejects.toThrow("Privileged action failed (CAPABILITY_MISSING): denied");
+    });
 });
diff --git a/tests/utils/renderOnLoad.test.ts b/tests/utils/renderOnLoad.test.ts
new file mode 100644
index 0000000..8a61d51
--- /dev/null
+++ b/tests/utils/renderOnLoad.test.ts
@@ -0,0 +1,199 @@
+import {
+    createNoopRenderOnLoadSource,
+    createRenderOnLoadActionsSource,
+    defineRenderOnLoad,
+    defineRenderOnLoadActions,
+    getRenderOnLoadTemplate,
+    getRenderOnLoadMonacoHints,
+    getRenderOnLoadMonacoTypeDefinitions,
+    isRenderOnLoadModule,
+    listRenderOnLoadTemplates,
+    resolveRenderOnLoadSource,
+} from "../../src/utils/renderOnLoad";
+
+describe("renderOnLoad helpers", () => {
+    const originalWindow = globalThis.window;
+    const originalDocument = globalThis.document;
+
+    afterEach(() => {
+        if (originalWindow) {
+            globalThis.window = originalWindow;
+        } else {
+            delete (globalThis as { window?: Window }).window;
+        }
+
+        if (originalDocument) {
+            globalThis.document = originalDocument;
+        } else {
+            delete (globalThis as { document?: Document }).document;
+        }
+    });
+
+    test("creates default no-op source", () => {
+        expect(createNoopRenderOnLoadSource()).toBe("() => {}");
+    });
+
+    test("defines module from string source", () => {
+        const module = defineRenderOnLoad("() => console.log('ready')");
+        expect(isRenderOnLoadModule(module)).toBe(true);
+        expect(resolveRenderOnLoadSource(module)).toBe("() => console.log('ready')");
+    });
+
+    test("defines module from function source", () => {
+        const module = defineRenderOnLoad(() => {
+            const root = document.getElementById("root");
+            if (root) {
+                root.textContent = "ok";
+            }
+        });
+
+        const source = resolveRenderOnLoadSource(module);
+        expect(source).toContain("document.getElementById(\"root\")");
+    });
+
+    test("generates declarative action-binding module source", () => {
+        const module = defineRenderOnLoadActions({
+            handlers: {
+                save: ({ element }: any) => {
+                    (window as any).__saveCalls = ((window as any).__saveCalls ?? 0) + 1;
+                    element.dataset.bound = "true";
+                },
+            },
+            bindings: [
+                {
+                    selector: "#save-btn",
+                    event: "click",
+                    handler: "save",
+                    preventDefault: true,
+                    stopPropagation: true,
+                },
+            ],
+        });
+
+        const source = resolveRenderOnLoadSource(module);
+        expect(source).toContain("__fdoBindings");
+        expect(source).toContain("\"#save-btn\"");
+        expect(source).toContain("\"save\":");
+        expect(source).toContain("addEventListener");
+    });
+
+    test("binds and invokes declarative actions at runtime", () => {
+        const listeners: Array<{ callback: (event: any) => void }> = [];
+        const fakeElement = {
+            dataset: {} as Record<string, string>,
+            addEventListener: vi.fn((_event: string, callback: (event: any) => void) => {
+                listeners.push({ callback });
+            }),
+        };
+
+        globalThis.window = { __saveCalls: 0 } as unknown as Window;
+        globalThis.document = {
+            querySelectorAll: vi.fn().mockReturnValue([fakeElement]),
+        } as unknown as Document;
+
+        const source = createRenderOnLoadActionsSource({
+            setup: () => {
+                (window as any).__setupCalls = ((window as any).__setupCalls ?? 0) + 1;
+            },
+            handlers: {
+                save: ({ element }: any) => {
+                    (window as any).__saveCalls = ((window as any).__saveCalls ?? 0) + 1;
+                    element.dataset.bound = "true";
+                },
+            },
+            bindings: [{ selector: "#save-btn", event: "click", handler: "save" }],
+        });
+
+        new Function(source)();
+
+        expect((window as any).__setupCalls).toBe(1);
+        expect(fakeElement.addEventListener).toHaveBeenCalledTimes(1);
+        expect(listeners).toHaveLength(1);
+
+        const event = {
+            preventDefault: vi.fn(),
+            stopPropagation: vi.fn(),
+        };
+        listeners[0].callback(event);
+
+        expect((window as any).__saveCalls).toBe(1);
+        expect(fakeElement.dataset.bound).toBe("true");
+    });
+
+    test("throws when binding references an unknown handler", () => {
+        expect(() => createRenderOnLoadActionsSource({
+            handlers: {
+                save: () => {},
+            },
+            bindings: [{ selector: "#save-btn", event: "click", handler: "missing" }],
+        })).toThrow('references unknown handler "missing"');
+    });
+
+    test("throws in strict mode when required selector is missing", () => {
+        globalThis.window = {} as unknown as Window;
+        globalThis.document = {
+            querySelectorAll: vi.fn().mockReturnValue([]),
+        } as unknown as Document;
+
+        const source = createRenderOnLoadActionsSource({
+            strict: true,
+            handlers: {
+                save: () => {},
+            },
+            bindings: [{ selector: "#missing", event: "click", handler: "save", required: true }],
+        });
+
+        expect(() => new Function(source)()).toThrow('No elements matched selector "#missing"');
+    });
+
+    test("rejects unsupported output values", () => {
+        expect(() => resolveRenderOnLoadSource({ bad: true } as any)).toThrow(
+            "Method 'renderOnLoad' must return a synchronous string, function, or defineRenderOnLoad(...) module."
+        );
+    });
+
+    test("returns monaco typing and hint payloads", () => {
+        const typeDefs = getRenderOnLoadMonacoTypeDefinitions();
+        const hints = getRenderOnLoadMonacoHints();
+
+        expect(typeDefs).toContain("declare namespace FDOOnLoad");
+        expect(hints.length).toBeGreaterThan(0);
+        expect(hints[0]).toHaveProperty("label");
+        expect(hints[0]).toHaveProperty("insertText");
+    });
+
+    test("returns renderOnLoad templates and supports context filtering", () => {
+        const allTemplates = listRenderOnLoadTemplates();
+        expect(allTemplates.map((entry) => entry.id)).toEqual([
+            "runtime-noop",
+            "runtime-ui-message",
+            "method-define-render-on-load",
+            "method-define-render-on-load-actions",
+        ]);
+
+        const runtimeTemplates = listRenderOnLoadTemplates({ context: "runtime-source" });
+        expect(runtimeTemplates.map((entry) => entry.id)).toEqual([
+            "runtime-noop",
+            "runtime-ui-message",
+        ]);
+    });
+
+    test("returns a cloned template by id", () => {
+        const template = getRenderOnLoadTemplate("method-define-render-on-load-actions");
+        expect(template).not.toBeNull();
+        expect(template?.context).toBe("plugin-method");
+        expect(template?.source).toContain("defineRenderOnLoadActions");
+
+        if (template) {
+            template.source = "mutated";
+        }
+
+        const again = getRenderOnLoadTemplate("method-define-render-on-load-actions");
+        expect(again?.source).toContain("defineRenderOnLoadActions");
+    });
+
+    test("returns null for unknown renderOnLoad template id", () => {
+        expect(getRenderOnLoadTemplate("missing-template")).toBeNull();
+        expect(getRenderOnLoadTemplate("")).toBeNull();
+    });
+});
diff --git a/tests/utils/storageTooling.test.ts b/tests/utils/storageTooling.test.ts
new file mode 100644
index 0000000..0e7af5a
--- /dev/null
+++ b/tests/utils/storageTooling.test.ts
@@ -0,0 +1,25 @@
+import {
+    createStorageCapabilityPreset,
+    getStorageCapabilityPreset,
+    listStorageCapabilityPresets,
+} from "../../src";
+
+describe("storage tooling helpers", () => {
+    test("returns curated storage preset with capabilities", () => {
+        expect(getStorageCapabilityPreset("storageJSON")).toEqual({
+            id: "storageJSON",
+            label: "Storage JSON",
+            description: "Persistent plugin JSON storage using the SDK-managed scoped JSON store backend.",
+            backendId: "json",
+            capabilities: ["storage", "storage.json"],
+        });
+    });
+
+    test("lists storage capability presets", () => {
+        expect(listStorageCapabilityPresets().map((preset) => preset.id)).toEqual(["storageJSON"]);
+    });
+
+    test("creates storage capability preset bundle", () => {
+        expect(createStorageCapabilityPreset("storageJSON")).toEqual(["storage", "storage.json"]);
+    });
+});
diff --git a/webpack.config.cjs b/webpack.config.cjs
index 2d3f142..5bbbaf4 100644
--- a/webpack.config.cjs
+++ b/webpack.config.cjs
@@ -1,4 +1,6 @@
 const path = require('path');
+const webpack = require('webpack');
+const packageJson = require('./package.json');
 const DOMMetadataPlugin = require("./extract-dom-classes");
 
 module.exports = {
@@ -37,6 +39,9 @@ module.exports = {
         ]
     },
     plugins: [
+        new webpack.DefinePlugin({
+            __FDO_SDK_PACKAGE_VERSION__: JSON.stringify(packageJson.version),
+        }),
         new DOMMetadataPlugin({
             srcDir: "src",
             outFile: "dom-metadata.json",

From 6c00be57f63d8f356f8a950fe0212ab40c791943 Mon Sep 17 00:00:00 2001
From: anikitenko <alexvwan@gmail.com>
Date: Sun, 19 Apr 2026 00:45:10 +0300
Subject: [PATCH 2/2] fix(examples): one test missing

---
 tests/utils/diagnosticTemplates.test.ts | 38 +++++++++++++++++++++++++
 1 file changed, 38 insertions(+)
 create mode 100644 tests/utils/diagnosticTemplates.test.ts

diff --git a/tests/utils/diagnosticTemplates.test.ts b/tests/utils/diagnosticTemplates.test.ts
new file mode 100644
index 0000000..c2fcf54
--- /dev/null
+++ b/tests/utils/diagnosticTemplates.test.ts
@@ -0,0 +1,38 @@
+import {
+    formatDiagnosticExactFix,
+    getDiagnosticFixTemplate,
+    listDiagnosticFixTemplates,
+} from "../../src";
+
+describe("diagnostic fix templates", () => {
+    test("returns template for known code", () => {
+        const template = getDiagnosticFixTemplate("capability_missing");
+
+        expect(template).not.toBeNull();
+        expect(template?.code).toBe("CAPABILITY_MISSING");
+        expect(template?.exactFix).toContain("PLUGIN_INIT.content.capabilities");
+        expect(template?.steps.length).toBeGreaterThan(0);
+    });
+
+    test("returns null for unknown code", () => {
+        expect(getDiagnosticFixTemplate("UNKNOWN_CODE")).toBeNull();
+        expect(formatDiagnosticExactFix("UNKNOWN_CODE")).toBeNull();
+    });
+
+    test("formats exact fix line for known code", () => {
+        const line = formatDiagnosticExactFix("PROCESS_EXIT_NON_ZERO");
+        expect(line).toContain("Process command failed");
+        expect(line).toContain("Surface full host diagnostics");
+    });
+
+    test("lists templates in deterministic order", () => {
+        const templates = listDiagnosticFixTemplates();
+        expect(templates.length).toBeGreaterThanOrEqual(7);
+        const codes = templates.map((entry) => entry.code);
+        const sortedCodes = [...codes].sort((left, right) => left.localeCompare(right));
+        expect(codes).toEqual(sortedCodes);
+        expect(codes).toContain("HANDSHAKE_API_INCOMPATIBLE");
+        expect(codes).toContain("HANDSHAKE_CONTRACT_INCOMPATIBLE");
+        expect(codes).toContain("PLUGIN_BACKEND_EMPTY_RESPONSE");
+    });
+});