fix(examples): stabilize learning examples for fdo runtime and docs

.gitignore

@@ -212,3 +212,5 @@ dist
 # npm audit files
 .*-audit.json
 
+# Local-only working docs
+docs-local/

README.md

@@ -29,11 +29,12 @@ Plugin metadata is also part of the host contract. In particular, `metadata.icon
 
 For the detailed render/runtime contract, see [docs/RENDER_RUNTIME_CONTRACT.md](./docs/RENDER_RUNTIME_CONTRACT.md).
 
-Roadmaps:
+Further documentation:
 
-- production hardening and completed durability work: [docs/PRODUCTION_GRADE_TODO.md](./docs/PRODUCTION_GRADE_TODO.md)
-- longer-term platform vision for DevOps/SRE/operator workflows: [docs/REVOLUTIONARY_PLUGIN_SYSTEM_TODO.md](./docs/REVOLUTIONARY_PLUGIN_SYSTEM_TODO.md)
-- concrete FDO host/editor/AI handoff for the current Phase 1 golden path: [docs/PHASE_1_FDO_ALIGNMENT_PROMPT.md](./docs/PHASE_1_FDO_ALIGNMENT_PROMPT.md)
+- 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)
+- API stability policy: [docs/API_STABILITY.md](./docs/API_STABILITY.md)
 
 ## Features
 
@@ -138,7 +139,7 @@ See `examples/08-privileged-actions-plugin.ts` for the low-level host privileged
 
 See `examples/09-operator-plugin.ts` for a curated operator helper example for a known tool family built on scoped host process execution.
 
-For FDO-side Monaco/editor/AI alignment on these example priorities, use `docs/PHASE_1_FDO_ALIGNMENT_PROMPT.md`.
+For public SDK guidance, follow the fixture-first and curated-helper-first recommendation order documented in [docs/OPERATOR_PLUGIN_PATTERNS.md](./docs/OPERATOR_PLUGIN_PATTERNS.md).
 
 The SDK also provides curated operator presets for common DevOps/SRE tooling such as Docker, kubectl, Helm, Terraform, Ansible, AWS CLI, gcloud, Azure CLI, Podman, Kustomize, GitHub CLI, Git, Vault, and Nomad, while still supporting generic custom scopes for host-specific tools.
 

docs/EXAMPLES_AND_FIXTURES.md

@@ -0,0 +1,81 @@
+# Examples And Fixtures
+
+This guide defines the public, stable example surface for `@anikitenko/fdo-sdk`.
+
+If you are starting a new plugin, prefer the fixture set under `examples/fixtures/` before the numbered learning examples.
+
+## Recommended Starting Order
+
+1. `examples/fixtures/minimal-plugin.fixture.ts`
+   Use when you need the smallest valid plugin scaffold.
+2. `examples/fixtures/error-handling-plugin.fixture.ts`
+   Use when you need deterministic render fallback behavior.
+3. `examples/fixtures/storage-plugin.fixture.ts`
+   Use when you need plugin-scoped storage with graceful JSON-store handling.
+4. `examples/fixtures/advanced-ui-plugin.fixture.ts`
+   Use when you need richer UI composition with DOM helpers.
+5. `examples/fixtures/operator-kubernetes-plugin.fixture.ts`
+   Use when building a `kubectl`-style operator plugin.
+6. `examples/fixtures/operator-terraform-plugin.fixture.ts`
+   Use when building a Terraform preview/apply plugin.
+7. `examples/fixtures/operator-custom-tool-plugin.fixture.ts`
+   Use when you need a host-specific scoped tool that is not covered by a curated operator preset.
+
+The numbered examples under `examples/01-...` to `examples/09-...` are learning references. They are not the default production starting point.
+
+## Production-Grade Rules
+
+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.
+- For UI-to-backend calls, use the real bridge contract:
+
+```ts
+const result = await window.createBackendReq("UI_MESSAGE", {
+  handler: "plugin.handlerName",
+  content: {},
+});
+```
+
+- For known operator tool families, prefer:
+  - `createOperatorToolCapabilityPreset(...)`
+  - `requestOperatorTool(...)`
+- For multi-step operator flows, prefer:
+  - `requestScopedWorkflow(...)`
+- For host-specific or non-curated tools, prefer:
+  - `requestScopedProcessExec(...)`
+- For privileged or operator plugins, declare expected capabilities in code via `declareCapabilities()`.
+
+## Validation Expectations
+
+The examples surface is considered stable only when all of the following stay true:
+
+- `npm run test:examples` passes
+- public example docs do not reference local-only or internal planning files
+- public example docs do not reference stale docs domains
+- `createBackendReq(...)` examples reflect the real `UI_MESSAGE` handler pattern
+- the canonical fixtures remain the primary recommended starting point
+
+## Canonical Operator Patterns
+
+For operator plugins, the recommended order is:
+
+1. start from the closest fixture
+2. use curated capability presets for known tool families
+3. use `requestOperatorTool(...)` for single-action known-tool execution
+4. use `requestScopedWorkflow(...)` for preview/apply or inspect/act flows
+5. use `requestScopedProcessExec(...)` for host-specific internal tools
+6. use lower-level transport helpers only when transport-level control is explicitly required
+
+For more detail, see [OPERATOR_PLUGIN_PATTERNS.md](./OPERATOR_PLUGIN_PATTERNS.md).
+
+## Public Documentation Links
+
+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)
+- [RENDER_RUNTIME_CONTRACT.md](./RENDER_RUNTIME_CONTRACT.md)
+- [INJECTED_LIBRARIES.md](./INJECTED_LIBRARIES.md)
+- [API_STABILITY.md](./API_STABILITY.md)

docs/INJECTED_LIBRARIES.md

@@ -147,20 +147,25 @@ These helper functions are injected into the iframe UI runtime `window` object.
 
 ### `createBackendReq(type, data)`
 
-Creates a request to your plugin's backend handler.
+Creates a request to your plugin's backend transport.
 
 **Parameters:**
-- `type` (string): The function name to call on the backend
+- `type` (string): The backend transport type
 - `data` (any, optional): The data to send to the backend
 
 **Returns:** `Promise<any>` - The response from the backend
 
 **Example:**
 ```javascript
-const result = await window.createBackendReq('getUserData', { userId: 123 });
+const result = await window.createBackendReq("UI_MESSAGE", {
+    handler: "plugin.getUserData",
+    content: { userId: 123 }
+});
 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.
+
 ### `waitForElement(selector, callback, timeout)`
 
 Waits for an element to appear in the DOM.
@@ -317,11 +322,10 @@ export default class GridLayoutPlugin extends FDO_SDK {
 
 ```javascript
 export default class DataPlugin extends FDO_SDK {
-    async fetchData() {
-        const data = await window.createBackendReq('getData', { 
-            filter: 'active' 
+    init() {
+        PluginRegistry.registerHandler("data.getActive", async (content) => {
+            return { filter: content?.filter ?? "active", items: [] };
         });
-        return data;
     }
 
     render() {
@@ -330,8 +334,9 @@ export default class DataPlugin extends FDO_SDK {
             <script>
                 window.waitForElement('#data-container', async (element) => {
                     try {
-                        const data = await window.createBackendReq('getData', { 
-                            filter: 'active' 
+                        const data = await window.createBackendReq("UI_MESSAGE", {
+                            handler: "data.getActive",
+                            content: { filter: "active" }
                         });
                         element.innerHTML = JSON.stringify(data, null, 2);
                     } catch (error) {

docs/OPERATOR_PLUGIN_PATTERNS.md

@@ -37,7 +37,7 @@ When choosing an operator authoring pattern, prefer this order:
 
 This ordering is intentional. It is the default path AI tooling and documentation should recommend first.
 
-For FDO-side Monaco/editor/capability-UX/AI alignment on this ordering, use [docs/PHASE_1_FDO_ALIGNMENT_PROMPT.md](./PHASE_1_FDO_ALIGNMENT_PROMPT.md).
+This recommendation order is the public SDK authoring guidance and should be preserved across docs, examples, and host/editor integrations.
 
 ## Execution Pattern