[markscott-ms]

Description

Part 2 of 4 of the CALM Hub extensions framework design for #3396. #3520 had all of this in one PR. It is now a stack of PRs, so that each part gets a better review.

Stack (merge in this order):

1. docs(calm-hub): propose extension runtime and security ADRs #3579 ADRs 0009–0012: runtime and security
2. docs(calm-hub): propose extension UI, CLI and MCP ADRs #3580 ADRs 0013–0014: UI, CLI and MCP ← this PR
3. docs(calm-hub): propose architecture validation and store write seam ADRs #3581 ADRs 0015–0016: validation and write seam
4. docs(calm-hub): model the CALM Hub extensions design in CALM #3582 CALM architecture

ADR	Decision
0013	Tiered UI: Hub-rendered blocks by default, a cross-origin iframe later, no Module Federation (Q3)
0014	Generic calm hub ext dispatch in the CLI, and one MCP tool for each command

Finding that changes the plan: X-Frame-Options: DENY applies to all routes, so Hub cannot frame a page that it serves.

Not yet verified: a step-0 spike must test ToolManager in a native image. ADR 0014 gives the fallback.

All ADRs are Proposed.

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 Documentation update
• 🎨 Code style/formatting changes
• ♻️ Refactoring (no functional changes)
• ⚡ Performance improvements
• ✅ Test additions or updates
• 🔧 Chore (maintenance, dependencies, CI, etc.)

Affected Components

• CLI (cli/)
• Schema (calm/)
• CALM AI (calm-ai/)
• CALM Hub (calm-hub/)
• CALM Hub UI (calm-hub-ui/)
• CALM Lab (calm-lab/)
• CALM Models (calm-models/)
• CALM Server (calm-server/)
• CALM Studio (calm-studio/)
• CALM Widgets (calm-widgets/)
• CALMGuard (calm-guard/)
• Documentation (docs/)
• Shared (shared/)
• VS Code Extension (calm-plugins/vscode/)
• Dependencies
• CI/CD

Commit Message Format ✅

docs(calm-hub): propose extension UI, CLI and MCP ADRs

Testing

• I have tested my changes locally
• I have added/updated unit tests
• All existing tests pass

This PR adds documentation only. It changes no code.

Checklist

• My commits follow the conventional commit format
• I have updated documentation if necessary
• I have added tests for my changes (if applicable)
• My changes follow the project's coding standards

[rocketstack-matt]

Review of ADR 0013. I agree with blocks first, a cross-origin iframe tier later, and no Module Federation. I ask for these changes before acceptance:

1. Remove the trusted same-origin mount tier (L51–53). Any script in Hub's origin can read the OIDC token in Web Storage. An operator flag does not change that. Keep mount for Hub's own code until the token is out of Web Storage.
2. Make Deployments a decorator view, not a mount extension (L67–68). As CALM Hub UI: show all decorators with one generic view, not type-specific implementations #3620 asks, show deployment decorators as a diagram overlay and in the generic Decorators view, and remove DeploymentPanel. ?tab=deployments can redirect to that view. Then nothing needs mount now.
3. Add a tier under blocks for decorator views that Hub draws (L69–74). A generic decorator view, one overlay engine for nodes and edges (one status field mapped to ok/warn/error/info), and a mapping from decorator data to block types. A manifest declares these as decorator-views, with no route. Many Add an extensions framework to CALM Hub #3396 stories (cost, risk, ownership, runtime status) then need no UI code.

Smaller points:

• L36: limit designer-tab to views that a service computes on request. Stored results should be decorators, so the CLI, MCP and VS Code see them too.
• L40–43: publish the block JSON Schema, versioned by hubApi, so the VS Code plugin (Add an Extensions Framework to CALM VS Code Plugin #3499) can use it.
• Point 3 needs a manifest contribution with no route. Since 0009–0012 are approved, that can be a small amendment to 0012 in this PR or a follow-up.