App Dashboard Contract¶

The App Dashboard is the canonical owner/operator surface every Mozaiks app can expose. It is not App Zero-specific. App Zero is the richest first consumer, but the contract belongs in OSS so generated apps, customer workspaces, hosted apps, and self-hosted apps share the same management model.

Dashboard Scopes¶

Mozaiks has two dashboard levels:

The Workspace Dashboard answers cross-app questions: what apps exist, what needs attention, where cost is coming from, and which shared integrations are ready. The App Dashboard answers app-specific questions: what is being built, what is branded, what is launched, who can use it, and what workflows or support threads need attention.

Canonical File¶

Apps declare dashboard structure in:

app/dashboard/dashboard.yaml

At runtime the active app root is already app/, so framework loaders resolve:

dashboard/dashboard.yaml

The schema version is:

schema_version: mozaiks.dashboard.v1

When the file is missing, Studio uses the OSS default manifest. App-owned files can overlay the default with extends: default and override portals by id. The dashboard/ directory is a canonical app-root plane, and app/provenance.yaml can reference dashboard/dashboard.yaml as the app's dashboard overlay.

Ownership Boundaries¶

The dashboard manifest may reference workflow sequences, but it does not define them. The sequence must already exist in extension_registry.json.

Manifest Shape¶

schema_version: mozaiks.dashboard.v1
extends: default

workspace:
  portals:
    - id: portfolio
      label: Apps
      route: /apps
      icon: apps
      order: 0
      panels:
        - id: portfolio
          type: app_portfolio_table
          title: Apps

app:
  portals:
    - id: building
      label: Building
      route: /apps/:appId/building
      icon: hammer
      order: 10
      capabilities: [build_requests, artifact_versions, approval_queue]
      panels:
        - id: requests
          type: build_requests
          title: Build state
        - id: artifacts
          type: artifact_timeline
          title: Build versions
        - id: approvals
          type: approval_queue
          title: Approvals

Canonical App Portals¶

The default App Dashboard lanes are:

An app does not have to show every portal. Capability packs and app-specific overlays can disable a portal or add panels.

Determinism Rules¶

• Portal ids, panel ids, capabilities, and action ids are stable lowercase identifiers.
• Portal routes are app-local paths. App-scoped portal routes include :appId.
• Panels use known panel types. Arbitrary JSX is only allowed through the explicit custom_component panel type.
• Workflow launch actions reference existing workflow ids or workflow sequence ids; they do not inline routing graphs.
• Module actions use <module_id>.<action_id> targets and must bind to actions declared in module.yaml.
• The manifest is declarative. It contains no secrets, provider credentials, payment-provider ids, or hosted-product internals.

Runtime Primitives¶

The OSS runtime provides:

• mozaiksai.core.dashboard.DashboardManifest
• load_dashboard_manifest(app_root)
• build_default_dashboard_manifest()
• build_dashboard_shell_routes(manifest)
• validate_dashboard_manifest_routes(manifest, route_pages)
• GET /api/studio/dashboard
• DashboardPortalPage, the generic factory UI renderer for manifest-declared portal panels

build_dashboard_shell_routes() is a migration bridge for clients that still consume route-manifest-shaped entries. Existing ui/route_manifest.json pages remain valid while the Dashboard Portal renderer is adopted.

DashboardPortalPage reads the active mozaiks.dashboard.v1 manifest through /api/studio/dashboard, matches the current route to an enabled portal, then renders known panel types against Studio data. The generic renderer currently covers summary, next step, portal links, build requests, artifact timelines, approval queues, and explicitly declared workflow launch panels. Apps should mount it by declaring a normal route-manifest entry with component: DashboardPortalPage; they should not copy the factory page into their workspace to activate a default portal.

The OSS dashboard contract intentionally stops at build/review management. Collaborative development product behavior such as proposal discussion, voting, community moderation, and proprietary approval policy belongs in app-owned modules and app-specific routes. Apps can surface a compact admin summary through module_panel_ref or custom_component panels, but those product semantics are not generic Factory/Studio defaults.

validate_dashboard_manifest_routes() is the CI contract for apps that mount concrete Studio pages. It validates that every enabled dashboard portal points to a registered route, every portal intended for navigation is visible in the matching workspace-studio or app-studio route group, and every visible Studio navigation route has a matching enabled dashboard portal. Planned portals should stay enabled: false until their route and product surface exist.

Multimodal Integration¶

Generated media is a dashboard capability, not a dashboard architecture. Branding, Launch, and Growth portals can use the OSS media primitives to show generated images, promoted assets, campaign media, and landing page visuals. The user-facing operation is still deterministic: review an asset, promote it to a target, or launch a workflow sequence.

Cleanup Direction¶

The long-term target is:

1. Keep extension_registry.json limited to workflow routing and sequences.
2. Keep admin_registry.yaml limited to AdminPortal extension pages.
3. Keep route_manifest.json as concrete route mounting, not the semantic App Dashboard source.
4. Move App Studio portal definitions into dashboard/dashboard.yaml.
5. Let generated apps customize dashboards through manifest overlays and capability-contributed panels instead of bespoke hardcoded dashboard pages.