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.

Directory Composition¶

AppsDirectory, exported through @mozaiks/factory-app-ui, accepts an already authorized app list and optional navigationForApp callbacks. Hosts with a paged data source can supply:

• pagination: { page, hasNext, hasPrevious, onNext, onPrevious, onRetry };
• controlled searchValue / onSearchChange and activeFilter / onFilterChange pairs;
• loading and error for the current request.

With pagination, the host owns querying, cursor state, search and filtering. The directory renders the supplied page without filtering its rows again, labels counts as belonging to that page, and provides Previous/Next and retry controls. Loading preserves the search controls and disables page navigation. Without pagination, the existing local portfolio search, filters and summary remain available. The shared component does not define hosted app ownership, provider calls, or the host's paging API.

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.

App-owned Management Composition¶

@mozaiks/factory-app-ui exports AppsDirectory and DashboardPortalPage for app-owned composition around the shared Studio presentation. AppsDirectory accepts apps, loading, error, an optional deleteApp callback, and an optional navigationForApp(app) callback returning primaryAction and dashboardHref. Without that callback, the standard Studio directory retains its existing navigation. Without a delete callback, it offers no delete action.

An app whose management record differs from the Factory record must resolve that relationship through its own authorized data source. Its wrapper can pass targetAppId and buildRegistryId to DashboardPortalPage: Studio finds that exact target and verifies its Factory registry association before loading build data. The route's appId remains the management selector for portal navigation; workflow launches use the resolved Factory record's execution host and build registry. No identity is rewritten or inferred from another identifier.

Ordinary Studio routes need no wrapper or extra props. Workspace-scoped portal routes have no appId and require no selected-app lookup. Product wrappers must preserve that workspace behavior and show an unavailable or unlinked state when their own authorized record cannot resolve a Factory target.

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.