updating docs (#161)

Author: andrewkenreich

content/agents/workspace-mcp-quickstart.md

@@ -68,7 +68,24 @@ http://127.0.0.1:8787/mcp
 
 The script installs `uv` if needed, then runs `workspace-mcp` from the OpenBB Workspace MCP source archive.
 
-For advanced options (custom host/port, forks, branches, or local checkouts), see the [Workspace MCP repository](https://github.com/OpenBB-finance/workspace-mcp).
+### Passing options to the installer
+
+The one-line installers forward any arguments after `--` straight to `workspace-mcp`, so you can set options like `--cors-allow`, `--host`, or `--port` without installing the binary separately.
+
+**macOS, Linux, WSL, and Git Bash** — add `-s --` after `sh`, then the flags:
+
+```bash
+curl -LsSf https://raw.githubusercontent.com/OpenBB-finance/workspace-mcp/main/scripts/run.sh \
+  | sh -s -- --cors-allow https://your-origin.openbb.co
+```
+
+**Windows PowerShell** — append the flags to the run command:
+
+```powershell
+powershell -ExecutionPolicy Bypass -Command "Invoke-RestMethod https://raw.githubusercontent.com/OpenBB-finance/workspace-mcp/main/scripts/run.ps1 | Invoke-Expression" -- --cors-allow https://your-origin.openbb.co
+```
+
+See the [configuration reference](#configuration-reference) for the full list of options you can pass this way. For other advanced options (forks, branches, or local checkouts), see the [Workspace MCP repository](https://github.com/OpenBB-finance/workspace-mcp).
 
 ## 2. Check sidecar health
 
@@ -124,7 +141,14 @@ Open OpenBB Workspace in your browser and connect the local companion:
 
 By default, the sidecar allows CORS requests from `https://pro.openbb.co` and loopback origins such as `http://localhost:1420` and `http://127.0.0.1:1420`.
 
-For a different Workspace origin, pass `--cors-allow`:
+For a different Workspace origin, pass `--cors-allow`. If you started the sidecar with the one-line installer, forward the flag through `sh -s --`:
+
+```bash
+curl -LsSf https://raw.githubusercontent.com/OpenBB-finance/workspace-mcp/main/scripts/run.sh \
+  | sh -s -- --cors-allow https://example.openbb.dev
+```
+
+If you run the binary directly, pass it the same way:
 
 ```bash
 workspace-mcp --cors-allow https://example.openbb.dev

content/workspace/developers/json-specs/apps-json-reference.md

@@ -59,6 +59,20 @@ For example:
 ]
 ```
 
+#### Tagging widgets and tabs in prompts
+
+A prompt can reference a specific widget so the agent knows exactly which data to use. Use the `@[id:WIDGET_ID]` mention syntax inside the prompt string, where `WIDGET_ID` is the backend widget's id. When the prompt is rendered in OpenBB Workspace, the mention resolves to a chip showing the widget's name (for example, `@Peer Comparison`).
+
+For example, to tag a backend widget called "Peer Comparison" with the id `peer_comparison`:
+
+```json
+"prompts": [
+    "Compare $SYMBOL to its peers using @[id:peer_comparison] — which fundamentals stand out?"
+]
+```
+
+When rendered, `@[id:peer_comparison]` resolves to a `@Peer Comparison` chip. If the referenced widget is not available — for example, the backend is not connected — the mention falls through and displays as the raw `@[id:...]` string.
+
 Each MCP server entry contains:
 - `name`: Display name for the MCP server
 - `description`: Short description of what the server provides

content/workspace/developers/widget-types/html.md

@@ -19,10 +19,12 @@ import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
 
 <HeadTitle title="HTML | OpenBB Workspace Docs" />
 
-HTML widgets provide control over visualization design through server-rendered HTML, enabling the creation of custom styled dashboards and data displays. 
+HTML widgets provide control over visualization design through server-rendered HTML, enabling the creation of custom styled dashboards and data displays.
 
-:::warning Security Note
-HTML widgets render static HTML content only. JavaScript code within the HTML will not be executed for security reasons. All interactivity must be achieved through server-side logic and HTML/CSS features only.
+JavaScript inside the returned HTML **does execute**, so you can build interactive controls — buttons, inputs, event handlers — directly in the widget. To push a parameter value from an HtmlViewer widget back to Workspace (for example, to drive other widgets on the dashboard), dispatch a `CustomEvent` and let the injected bridge forward it; see [Pushing parameters back to Workspace](./iframe#pushing-parameters-back-to-workspace).
+
+:::note
+Treat HTML widgets like any other code you run: only render markup and scripts you trust. The page runs in the embedded context, so avoid injecting unsanitized third-party content into the HTML you return.
 :::
 
 <img className="pro-border-gradient" width="800" alt="HTML Widget Example" src="https://openbb-cms.directus.app/assets/8234f346-6b2e-49b2-b5de-7150c770a756.png" />
@@ -211,13 +213,11 @@ def html_widget():
             <button class="button" onclick="alert('Refreshing data...')">Refresh Dashboard</button>
         </div>
     </div>
-    
-    <!-- Note: JavaScript will not execute in HTML widgets for security reasons -->
-    <!-- This script tag is included only as an example - it will not run -->
+
     <script>
-        // This JavaScript code will NOT execute
-        // HTML widgets only render static HTML and CSS
-        // All dynamic behavior must be implemented server-side
+        // JavaScript inside an HTML widget executes, so event handlers like the
+        // onclick above run as written. You can also dispatch the parameter-bridge
+        // CustomEvent here to push values back to Workspace.
     </script>
 </body>
 </html>
@@ -230,18 +230,18 @@ The gridData parameter specifies the widget's size in the OpenBB Workspace grid
 
 **Complete Design Control**: HTML widgets allow extensive customization through HTML markup and inline CSS styling, enabling the creation of professional-grade interfaces that match your organization's branding and design requirements.
 
-**Server-Side Rendering**: All content is generated server-side, ensuring security while allowing dynamic HTML generation based on real-time data, calculations, and API responses from your backend.
+**Server-Side Rendering**: Content is generated server-side, allowing dynamic HTML generation based on real-time data, calculations, and API responses from your backend.
+
+**Client-Side Interactivity**: JavaScript in the returned HTML executes, so you can add event handlers, build interactive controls, and push parameter updates back to Workspace through the [parameter bridge](./iframe#pushing-parameters-back-to-workspace).
 
 **Rich Styling Options**: Leverage the full power of inline CSS for advanced styling including animations, gradients, responsive layouts, and professional visual design that creates engaging dashboard experiences.
 
-**Data Integration**: Generate HTML content dynamically on the server based on live data sources, enabling real-time portfolio monitoring, market data display, and dynamic performance tracking through server-side updates.
+**Data Integration**: Generate HTML content dynamically on the server based on live data sources, enabling real-time portfolio monitoring, market data display, and dynamic performance tracking.
 
 ## Best Practices
 
 - Use semantic HTML structure for accessibility and maintainability
 - Implement responsive design patterns using CSS flexbox and grid layouts
-- Generate all dynamic content server-side before returning the HTML response
-- Use CSS animations and transitions for visual effects instead of JavaScript
-- Handle all data fetching and processing in the Python backend before rendering
-- Consider using HTML forms with server endpoints for user interactions
-- Refresh widgets periodically to update data rather than relying on client-side updates
+- Generate data-heavy content server-side before returning the HTML response, and use client-side JavaScript for interactivity
+- Only render markup and scripts you trust; avoid injecting unsanitized third-party content into the returned HTML
+- Use the [parameter bridge](./iframe#pushing-parameters-back-to-workspace) to drive other dashboard widgets from a control in the widget

content/workspace/developers/widget-types/iframe.md

@@ -188,6 +188,74 @@ The bridge below is the complete client side of the protocol — announce on loa
 })();
 ```
 
+## Pushing parameters back to Workspace
+
+The protocol messages above cover the **inbound** direction — Workspace pushing parameter values *into* the iframe with `openbb-params-update`. The parameter bridge is the **outbound** direction: a widget pushes a new parameter value *back to* Workspace. Workspace persists the update and re-sends it to every widget [grouped](../json-specs/apps-json-reference) on that parameter, so one widget can drive the rest of the dashboard.
+
+This lets you build interactive controls — a ticker selector, a date picker, a set of buttons — inside a widget and have the rest of the dashboard react to them.
+
+### The update message
+
+Send an `openbb:widget-params:update` message. Either update all params at once:
+
+```js
+{ type: "openbb:widget-params:update", params: { ticker: "NVDA" } }
+```
+
+…or a single named param:
+
+```js
+{ type: "openbb:widget-params:update", paramName: "ticker", value: "NVDA" }
+```
+
+For the update to propagate, the receiving widgets must share the same `paramName` and be in the same group. In `apps.json`, group the widgets with a `param` group on that parameter:
+
+```json
+"groups": [
+  {
+    "name": "Group 1",
+    "type": "param",
+    "paramName": "ticker",
+    "widgetIds": ["mock_quote", "bridge_iframe"],
+    "defaultValue": "AAPL"
+  }
+]
+```
+
+### Sending the message: iframe vs. HtmlViewer
+
+How you send the message depends on the widget type, because the two forward it differently:
+
+- **`iframe`** — the embedded page posts the message **directly** to the parent with `window.parent.postMessage(...)`.
+- **`html` (HtmlViewer)** — the page dispatches a **`CustomEvent`**; the bridge script Workspace injects into the HtmlViewer forwards it for you. The page must **not** `postMessage` itself.
+
+**Iframe widget** — post the update straight to the parent window:
+
+```js
+function pick(ticker) {
+  const msg = { type: "openbb:widget-params:update", params: { ticker } };
+  (window.top || window.parent).postMessage(msg, "*");
+}
+```
+
+**HtmlViewer widget** — dispatch a `CustomEvent` and let the injected bridge forward it (with the security token). Do not call `postMessage` directly:
+
+```js
+function pick(ticker) {
+  window.dispatchEvent(new CustomEvent("openbb:widget-params:update", {
+    detail: { type: "openbb:widget-params:update", params: { ticker } }
+  }));
+}
+```
+
+After Workspace persists the update, it re-sends the new value to every widget in the group, which then re-fetch with the new parameter — the full round-trip from one widget's button click to the whole group updating.
+
+:::note
+The HtmlViewer (`type: "html"`) outbound bridge relies on the page's JavaScript running so it can dispatch the `CustomEvent`. JavaScript in an [HTML widget](./html) executes, so the page's event handlers run as written.
+:::
+
+A complete working backend showing both paths (mock data, no API keys) is in the [iframe parameter bridge example](https://github.com/OpenBB-finance/backends-for-openbb/tree/main/widget-examples/iframe-bridge-example).
+
 ## Auto-connecting an MCP server
 
 Set `storage.mcpUrl` in the widget definition to attach an MCP server automatically when the iframe mounts. Its tools become available to Copilot with no manual setup: