feat(boost): add AI Catalog frontend architecture and OpenSpec

Add frontend architecture specification and OpenSpec change for the
AI Catalog Discovery UI (RHDHPLAN-1509). This is the first frontend
feature for the boost workspace.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: rohitkrai03

workspaces/boost/openspec/changes/ai-catalog-frontend/.openspec.yaml

@@ -0,0 +1,3 @@
+schema: spec-driven
+created: 2026-06-30
+status: draft

workspaces/boost/openspec/changes/ai-catalog-frontend/design.md

@@ -0,0 +1,140 @@
+# Design: AI Catalog Frontend
+
+## Context
+
+Boost has a backend with 30+ API routes and 9 plugin packages but no frontend. The AI Catalog is the first frontend feature. The plugin architecture must support future domains (chat, admin, agent gallery) without restructuring.
+
+## Goals
+
+- NFS-only frontend plugin using Backstage Blueprints
+- Browse page for marketplace-style AI asset discovery
+- Entity page extensions for asset details and adoption actions
+- Dev app shell for local development
+- BUI component library for new UI components
+
+## Non-Goals
+
+- Chat UI, admin panels, or agent gallery (future domains)
+- Custom entity detail pages (use existing catalog pages)
+- RHDH dynamic plugin packaging (Scalprum/export-dynamic deferred)
+- Custom search collator for global search (rely on default catalog indexing)
+
+## Decisions
+
+### Decision 1: NFS-only plugin, no legacy entry point
+
+This is a new plugin with no existing consumers. The default export from `src/index.ts` is `createFrontendPlugin`. No `src/alpha.tsx`, no `createPlugin` from `@backstage/core-plugin-api`.
+
+### Decision 2: Standalone browse page + entity extensions
+
+Two surface types:
+
+- `PageBlueprint` at `/ai-catalog` for the card grid browse view. The existing catalog table at `/catalog` does not support card layout, category grouping, or inline adoption actions — a dedicated page is needed.
+- `EntityCardBlueprint` and `EntityContentBlueprint` on existing catalog entity pages for AI-specific cards and tabs. No custom detail page.
+
+### Decision 3: catalogApiRef for data, BoostApiClient for download proxy only
+
+The browse page queries AI assets through the standard `catalogApiRef` — no custom boost backend routes for browsing. The only custom backend interaction is the download proxy route for git-hosted asset ZIP downloads.
+
+### Decision 4: Single isAiAsset filter, components handle kind differences
+
+One `isAiAsset(entity)` condition filter for all entity page Blueprints. The filter checks entity kind and `spec.type` against the AI asset entity model (see below). Individual components handle kind-specific rendering differences internally — e.g., the download card checks `spec.location.type` and renders nothing when absent.
+
+### Decision 5: Client-side pagination
+
+`catalogApi.getEntities()` returns the full matching dataset. Client-side pagination is sufficient for the Dev Preview target of ~500 assets. If catalogs grow beyond this, the hook internals can switch to `queryEntities` (cursor-based) without changing components.
+
+### Decision 6: BUI for UI components, PatternFly chatbot for future chat
+
+BUI (`@backstage/ui`) is the component library for all new UI. MUI v5 as fallback where BUI lacks coverage. PatternFly AI chatbot (`@patternfly/chatbot`) is reserved for the future chat domain to maintain consistency with Lightspeed.
+
+### Decision 7: RBAC graceful degradation
+
+Permission checks for `ai-catalog.asset.read.usage-docs` default to allow when the permission is not yet registered (RHDHPLAN-1508 not built). Content is shown, and enforcement activates automatically when RBAC lands.
+
+## Entity Model
+
+Backstage v1.51.0 introduced `AiResource` kind and `API` with `spec.type: mcp-server` via `@backstage/plugin-catalog-backend-module-ai-model`. Boost uses upstream kinds where available:
+
+| Category | Entity Kind | spec.type | Notes |
+|---|---|---|---|
+| Skills | AiResource | skill | Upstream. disciplines, categories, agents, dependsOn |
+| Rules | AiResource | rule | Upstream. category (required), rationale (required) |
+| MCP Servers | API | mcp-server | Upstream. spec.remotes list |
+| Agents | Component | ai-agent | Boost-defined |
+| Models | Resource | ai-model | Boost-defined. RFC #33060 pending |
+| Tools | Resource | ai-tool | Boost-defined (Kagenti) |
+| Vector Stores | Resource | vector-store | Boost-defined |
+
+## Components
+
+### AiCatalogPage
+Browse page with card grid, search, and filters. PluginHeader provided by the framework.
+- Card grid grouped by category with responsive layout
+- Debounced keyword search (300ms)
+- Filter controls: category, lifecycle, tags, owner, source connector (AND logic)
+- Filter/search state in URL query params
+- Pagination, sort (name, last updated)
+- Loading skeletons, empty state with clear-filters, error state with retry
+
+### AiAssetCard
+Card displaying key metadata for one AI asset. Used in the browse grid.
+- Name, truncated description, category icon/badge, lifecycle badge
+- Tags, owner, version, source connector indicator
+- Click navigates to catalog entity detail page
+
+### AiAssetSummaryCard
+EntityCardBlueprint on entity overview. Shows AI-specific metadata.
+- Category badge, current/recommended version, source attribution, lifecycle
+
+### DownloadAdoptCard
+EntityCardBlueprint on entity overview. Conditional on spec.location.type.
+- git: Download button triggers ZIP download via backend proxy
+- oci: docker/podman toggle with copyable pull command
+- Absent: card not rendered
+
+### VersionListCard
+EntityCardBlueprint on entity overview. Shows all versions of the asset.
+- Current/recommended highlighted
+- Click navigates to that version's entity page
+
+### UsageTab
+EntityContentBlueprint tab. RBAC-gated usage documentation.
+- With usage-docs permission: TechDocs content or external links
+- Without permission: "Contact owner for access" affordance
+
+## Design Reference
+
+UX prototype: https://agentic-524bde.pages.redhat.com/skill-marketplace/overview (VPN required)
+
+## Acceptance Criteria
+
+### AiCatalogPage
+- Developer sees card grid grouped by category at /ai-catalog
+- Search filters cards within 300ms
+- Multiple filters narrow results with AND logic
+- Filter state in URL survives refresh and is shareable
+- Empty state when no match; error state when catalog unreachable
+- Keyboard navigable through all interactive elements
+
+### AiAssetCard
+- Card displays all metadata fields from entity
+- Click navigates to catalog entity detail page
+
+### AiAssetSummaryCard
+- Renders on AI asset entity pages only
+- Shows category, version, source, lifecycle
+
+### DownloadAdoptCard
+- Download button on git assets triggers ZIP download
+- Docker/podman toggle on OCI assets with copyable pull command
+- Not rendered when spec.location.type absent
+
+### VersionListCard
+- Shows all versions; current highlighted
+- Click navigates to version's entity page
+
+### UsageTab
+- Renders TechDocs when annotation present; external links as fallback
+- Shows "Contact owner" when user lacks usage-docs permission
+- Tab only appears on AI asset entities

workspaces/boost/openspec/changes/ai-catalog-frontend/proposal.md

@@ -0,0 +1,39 @@
+# Proposal: AI Catalog Frontend
+
+## Why
+
+Developers need a single place to discover AI agents, skills, MCP servers, AI models, and model servers available in their organization. These assets are already registered in the Backstage Software Catalog via ingestion connectors (RHDHPLAN-1507, 1510–1512), but the generic catalog table view is not optimized for marketplace-style discovery — card layout, category grouping, contextual filtering, and download/copy actions are absent.
+
+The existing catalog entity detail pages provide metadata, TechDocs, and relationships out of the box. Rather than rebuilding detail pages, the frontend extends them with AI-specific cards and tabs using NFS Blueprints.
+
+## What Boost Builds
+
+### AI Catalog Browse Page
+
+A standalone page at `/ai-catalog` with a card grid for discovering AI assets:
+
+- Cards grouped by category (skills, rules, MCP servers, agents, models)
+- Search bar with debounced keyword filtering
+- Multi-faceted filter controls (category, lifecycle, tags, owner, source connector)
+- Pagination, sort, loading/empty/error states
+- Card click navigates to the existing catalog entity detail page
+
+### Entity Page Extensions
+
+NFS Blueprint extensions that render on catalog entity pages for AI assets:
+
+- AI Asset Summary Card — category, version, source, lifecycle
+- Download/Adopt Card — ZIP download for git assets, docker/podman pull command for OCI assets
+- Version List Card — all versions with navigation
+- Usage Tab — RBAC-gated usage documentation (TechDocs or external links)
+
+### Dev App Shell
+
+`packages/app` and `packages/backend` for local development and testing, following the adoption-insights/orchestrator pattern.
+
+## Impact
+
+- `plugins/boost/` — new NFS frontend plugin
+- `packages/app/` — new dev app shell
+- `packages/backend/` — new dev backend
+- `boost-backend` — new download proxy route (`GET /api/boost/catalog/download`)

workspaces/boost/openspec/changes/ai-catalog-frontend/specs/browse-view/spec.md

@@ -0,0 +1,87 @@
+# Browse View
+
+> **Status: Draft** — Pre-implementation specification. Subject to change during implementation.
+
+The AI Catalog browse page provides marketplace-style discovery for AI assets registered in the Backstage Software Catalog.
+
+## Requirements
+
+### Requirement: Card Grid Display
+
+AI assets render as a card grid grouped by category.
+
+#### Scenario: Browse page loads with assets
+
+- **WHEN** the developer navigates to `/ai-catalog`
+- **THEN** the page displays a card grid of AI asset entities from the catalog
+- **AND** cards are grouped by category (skills, rules, MCP servers, agents, models)
+- **AND** each card shows name, description, category badge, lifecycle, tags, owner, version, and source
+
+#### Scenario: Card navigation to entity detail
+
+- **WHEN** the developer clicks an asset card
+- **THEN** the browser navigates to the catalog entity detail page for that entity (e.g., `/catalog/default/airesource/my-skill`)
+- **AND** the browse page state is preserved for back navigation
+
+#### Scenario: Responsive layout
+
+- **WHEN** the viewport is desktop width
+- **THEN** the card grid renders 3 columns
+- **WHEN** the viewport is mobile width
+- **THEN** the card grid renders 1 column
+
+### Requirement: Keyword Search
+
+The search bar filters visible cards by keyword.
+
+#### Scenario: Search filters cards
+
+- **WHEN** the developer types a keyword in the search bar
+- **THEN** cards are filtered within 300ms (debounced)
+- **AND** matching is against entity name, description, and tags
+
+#### Scenario: Search state in URL
+
+- **WHEN** the developer types a search term
+- **THEN** the search term is reflected in the URL query params (`?q=...`)
+- **AND** loading the URL directly reproduces the same filtered view
+
+### Requirement: Multi-Faceted Filters
+
+Filter controls narrow the card grid by entity metadata.
+
+#### Scenario: Filters combine as AND
+
+- **WHEN** the developer selects category "skill" AND lifecycle "production"
+- **THEN** only cards matching both criteria are shown
+
+#### Scenario: Filter state in URL
+
+- **WHEN** filters are active
+- **THEN** filter state is persisted in URL query params
+- **AND** the URL is shareable and survives page refresh
+- **AND** back/forward browser navigation updates filters correctly
+
+#### Scenario: Clear filters
+
+- **WHEN** the developer clears all filters
+- **THEN** the URL resets to the base path
+- **AND** the full unfiltered card grid is restored
+
+### Requirement: Loading, Empty, and Error States
+
+#### Scenario: Loading state
+
+- **WHEN** the catalog API request is in progress
+- **THEN** skeleton cards are shown as loading placeholders
+
+#### Scenario: Empty state
+
+- **WHEN** no assets match the current filters
+- **THEN** the page shows "No AI assets match your filters" with a clear-filters action
+
+#### Scenario: Error state
+
+- **WHEN** the catalog API is unreachable
+- **THEN** the page shows an error message with a Retry button
+- **AND** the error does not crash the RHDH shell (error boundary)

workspaces/boost/openspec/changes/ai-catalog-frontend/specs/entity-extensions/spec.md

@@ -0,0 +1,95 @@
+# Entity Page Extensions
+
+> **Status: Draft** — Pre-implementation specification. Subject to change during implementation.
+
+NFS Blueprint extensions that render on existing catalog entity pages for AI assets. All extensions use the `isAiAsset` condition filter and do not render on non-AI entities.
+
+## Requirements
+
+### Requirement: AI Asset Summary Card
+
+#### Scenario: Summary card renders on AI entity
+
+- **WHEN** a developer views a catalog entity page for an AI asset
+- **THEN** the AI Asset Summary Card shows the entity's category badge, current version, source connector attribution, and lifecycle state
+
+#### Scenario: Summary card absent on non-AI entity
+
+- **WHEN** a developer views a catalog entity page for a non-AI entity (e.g., a regular Component or API)
+- **THEN** the AI Asset Summary Card is not rendered
+
+### Requirement: Download/Adopt Card
+
+#### Scenario: Git asset download
+
+- **WHEN** the entity has `spec.location.type: git`
+- **THEN** the card shows a Download button
+- **AND** clicking the button triggers a ZIP download via the backend proxy
+- **AND** a loading indicator is shown during download
+- **AND** an error toast is shown on failure
+
+#### Scenario: OCI asset pull command
+
+- **WHEN** the entity has `spec.location.type: oci`
+- **THEN** the card shows a docker/podman segmented toggle
+- **AND** the pull command is displayed below the toggle using `spec.location.target`
+- **AND** switching the toggle instantly updates the displayed command
+- **AND** the Copy button copies the currently displayed command to clipboard
+
+#### Scenario: No location type
+
+- **WHEN** the entity does not have `spec.location.type`
+- **THEN** the Download/Adopt Card is not rendered
+
+### Requirement: Version List Card
+
+#### Scenario: Version list with navigation
+
+- **WHEN** the entity has multiple versions (linked by shared asset identifier)
+- **THEN** the Version List Card shows all versions
+- **AND** the current/recommended version is visually highlighted
+- **AND** clicking a version navigates to that version's catalog entity page
+
+### Requirement: Usage Tab
+
+#### Scenario: TechDocs available
+
+- **WHEN** the entity has the `backstage.io/techdocs-ref` annotation
+- **THEN** the Usage tab renders TechDocs content for the entity
+
+#### Scenario: TechDocs not available
+
+- **WHEN** the entity does not have the TechDocs annotation
+- **THEN** the Usage tab renders external links (source registry, repository, download location) from entity metadata
+
+#### Scenario: RBAC gated — permission granted
+
+- **WHEN** the user has the `ai-catalog.asset.read.usage-docs` permission (or the permission is not yet registered)
+- **THEN** the Usage tab shows full usage content
+
+#### Scenario: RBAC gated — permission denied
+
+- **WHEN** the user has `ai-catalog.asset.read` but not `ai-catalog.asset.read.usage-docs`
+- **THEN** the Usage tab shows a "Contact owner for access" affordance instead of usage content
+
+#### Scenario: Tab visibility
+
+- **WHEN** a developer views a non-AI entity page
+- **THEN** the Usage tab is not present in the entity page tabs
+
+### Requirement: Backend Download Proxy
+
+#### Scenario: Successful download
+
+- **WHEN** the frontend calls `GET /api/boost/catalog/download` with a valid entity ref
+- **THEN** the backend resolves `spec.location.target`, authenticates to GitHub via Backstage SCM integrations, and streams the ZIP archive response
+
+#### Scenario: Unauthorized download
+
+- **WHEN** the user lacks catalog entity read permission for the requested entity
+- **THEN** the backend returns 403
+
+#### Scenario: Download failure
+
+- **WHEN** the GitHub API is unreachable or returns an error
+- **THEN** the backend returns an appropriate error status with a message