docs(boost): address review feedback on PRD and OpenSpec specifications

workspaces/boost/AGENTS.md

@@ -0,0 +1,110 @@
+# AGENTS.md
+
+## Project overview
+
+Boost is a clean-room reimplementation of the Augment agentic developer portal for Red Hat Developer Hub (RHDH). It is a Backstage plugin workspace — not a fork of Augment. The project context, design principles, and relationship to Augment are documented in `specifications/boost-context.md`. Read that file before making any implementation decisions.
+
+## Specification-driven development
+
+This workspace uses a specification-first approach. Before writing code, read the relevant specifications:
+
+```
+workspaces/boost/
+├── specifications/                # Product requirements
+│   ├── boost-context.md           # Project rationale, 12 design principles, upstream monitoring
+│   └── prd/                       # Product Requirements Documents (one per capability area)
+│       ├── use-case-index.md      # All 25 use cases at a glance
+│       ├── ai-chat-interaction-experience.md
+│       ├── agent-creation-discovery.md
+│       ├── pluggable-ai-platform-architecture.md
+│       ├── platform-operations-deployment.md
+│       └── security-safety-governance.md
+├── openspec/                      # Implementation specifications
+│   └── changes/                   # One directory per capability area:
+│       ├── ai-chat-interaction-experience/
+│       ├── agent-creation-discovery/
+│       ├── pluggable-ai-platform-architecture/
+│       ├── platform-operations-deployment/
+│       └── security-safety-governance/
+│           ├── proposal.md        # What and why
+│           ├── design.md          # Architecture decisions
+│           ├── tasks.md           # Implementation task breakdown
+│           └── specs/             # Behavioral specs (Given/When/Then)
+└── plugins/                       # Plugin packages (implementation target)
+```
+
+When implementing an issue:
+
+1. Read `specifications/boost-context.md` for design principles — these are non-negotiable
+2. Find the relevant PRD in `specifications/prd/` for product requirements
+3. Find the matching change in `openspec/changes/` for design decisions, task breakdown, and behavioral specs
+4. The `specs/` subdirectories contain acceptance criteria as scenarios — implementation must satisfy these
+
+## Architecture rules
+
+### Backstage-native services only
+
+Use Backstage `cacheService`, `permissions`, `httpAuth`, `configApi`, and `catalogApi`. Never build custom equivalents. All caches use `coreServices.cache` — no raw `Map<>` caches.
+
+### Provider isolation
+
+Each AI provider (`boost-backend-module-llamastack`, `boost-backend-module-kagenti`) is a separate `createBackendModule`. Providers must not import from each other. Shared types live in `boost-common`.
+
+### Capability checks, not identity checks
+
+Frontend rendering decisions use `ProviderCapabilities` interface checks. Never use `providerId === 'string'` comparisons.
+
+### Permissions as sole authorization
+
+All authorization decisions use `permissions.authorize()` with fine-grained permissions (`boost.agent.*`, `boost.tool.*`, `boost.kagenti.admin`). No custom route-level authorization logic.
+
+### Schema-driven validation
+
+Config validation uses Zod schemas as single source of truth. TypeScript types are generated from Zod. No hand-written validators.
+
+### Catalog entities for domain objects
+
+Agents, tools, models, MCP servers, and vector stores are Backstage catalog entities — not in-memory caches. Entity providers emit standard catalog entities.
+
+## Code conventions
+
+### Package structure
+
+| Package                           | Purpose                                                              |
+| --------------------------------- | -------------------------------------------------------------------- |
+| `boost-frontend`                  | Chat UI, agent gallery, admin panels, composable routable extensions |
+| `boost-common`                    | Shared types, permissions, `boostAiProviderServiceRef`               |
+| `boost-backend`                   | Core routes, services, middleware, ProviderManager                   |
+| `boost-backend-module-llamastack` | Llama Stack provider module                                          |
+| `boost-backend-module-kagenti`    | Kagenti provider module                                              |
+| `llamastack-entity-provider`      | Independently deployable catalog entity provider                     |
+| `kagenti-entity-provider`         | Independently deployable catalog entity provider                     |
+
+### Naming
+
+- Config namespace: `boost.*` (e.g., `boost.features.agentCreation`, `boost.security.mode`)
+- Permission names: `boost.agent.*`, `boost.tool.*`, `boost.kagenti.admin`, `boost.access`, `boost.admin`
+- Resource types: `boost-agent`, `boost-tool`
+- DB tables: `boost_admin_config`, `boost_sessions`, `boost_messages`, `boost_feedback`
+- Extension point: `boostProviderExtensionPoint`
+- Service ref: `boostAiProviderServiceRef`
+- Plugin ID: `boost` (used in `createBackendModule({ pluginId: 'boost', ... })`)
+
+### Testing
+
+Every feature ships with tests. Integration tests use real database and cache backends, not mocks.
+
+### Frontend
+
+- Composable routable extensions with `React.lazy()` at extension boundaries
+- PatternFly design system components consistent with RHDH
+- WCAG 2.1 AA accessibility
+- Feature flags via `boost.features.*` in `app-config.yaml`
+
+## What not to do
+
+- Do not reference the `workspaces/augment/` codebase for implementation patterns — boost is a clean-room build
+- Do not use `augment` as a prefix for any new identifiers (config keys, permissions, tables, etc.)
+- Do not create raw `Map<>` caches — always use `coreServices.cache`
+- Do not add authorization checks outside `permissions.authorize()`
+- Do not add provider ID string checks in the frontend

workspaces/boost/openspec/changes/agent-creation-discovery/design.md

@@ -2,17 +2,17 @@
 
 ## Context
 
-Boost models AI domain objects (agents, tools, models, MCP servers, vector stores) as Backstage catalog entities from the start, informed by augment's experience. Augment managed these entirely in plugin-internal caches — four separate in-memory stores with duplicate caches, no discoverability, and no catalog-level RBAC. Boost uses catalog entity providers from day one, with existing Backstage kinds (`Component`, `Resource`) and a migration path to upstream `AIContext` and `API v1alpha2` kinds when available.
+Boost models AI domain objects (agents, tools, models, MCP servers, vector stores) as Backstage catalog entities from the start. The Augment reference prototype managed these entirely in plugin-internal caches; boost uses catalog entity providers from day one, with existing Backstage kinds (`Component`, `Resource`) and a path to upstream `AIContext` and `API v1alpha2` kinds when available.
 
 Boost implements the 4-stage agent lifecycle (Draft → Pending → Published → Archived) from the start — no legacy stage mappings needed.
 
 Boost integrates with an external skills marketplace (provided by a separate workspace) as a consumer, proxying browse/filter requests and handling local deployment of selected skills-based agents.
 
 ## Goals
 
-- AI domain objects as Backstage catalog entities from day one (using existing kinds with upstream migration path)
+- AI domain objects as Backstage catalog entities from day one (using existing kinds with upstream kind path)
 - No in-memory caches for domain objects — catalog is the source of truth
-- Entity providers packaged as an independent RHDH dynamic plugin module
+- Entity providers packaged as independent RHDH dynamic plugin modules
 - Toolscope as a standalone package with injectable cache adapter
 - 4-stage lifecycle model with ownership semantics from the start
 - Integration with external skills marketplace for agent discovery and deployment
@@ -25,42 +25,44 @@ Boost integrates with an external skills marketplace (provided by a separate wor
 
 ## Decisions
 
-### Decision 1: Use existing kinds with fallback to upstream
+### Decision 1: Use upstream kinds where available, existing kinds as fallback
 
-Use `kind: Component, spec.type: ai-agent` for agents and `kind: Resource, spec.type: ai-model|mcp-server|vector-store|ai-tool` for infrastructure resources. When upstream `AIContext` and `API v1alpha2` land, migrate to those kinds. Custom `CatalogProcessor` validators support both during transition. Tools are added as `kind: Resource, spec.type: ai-tool` to enable tool lifecycle permissions via catalog RBAC.
+Use `kind: Component, spec.type: ai-agent` for agents. For MCP servers, prefer `kind: API, spec.type: mcp-server` using the upstream `McpServerApiEntity` from `@backstage/plugin-catalog-backend-module-ai-model` ([backstage#34016](https://github.com/backstage/backstage/pull/34016), merged) — fall back to `kind: Resource, spec.type: mcp-server` if the model module is not installed. Use `kind: Resource` for models (`ai-model`), vector stores (`vector-store`), and Kagenti tools (`ai-tool`). When upstream `AIContext` lands, adopt it for agents. Custom `CatalogProcessor` validators support both current and future kinds during transitions.
 
 ### Decision 2: Entity providers as independently deployable backend services
 
 Entity providers are separate packages registered as Backstage backend services, each independently deployable as an RHDH dynamic plugin:
 
-- `kagenti-entity-provider` — `KagentiAgentEntityProvider` (5m), `KagentiToolEntityProvider` (5m)
-- `llamastack-entity-provider` — `LlamaStackModelEntityProvider` (60s), `LlamaStackAgentEntityProvider` (5m)
-- Core plugin: `McpEntityProvider` (5m), `VectorStoreEntityProvider` (10m) — cross-cutting
+- `kagenti-entity-provider` — `KagentiAgentEntityProvider`, `KagentiToolEntityProvider`
+- `llamastack-entity-provider` — `LlamaStackModelEntityProvider`, `LlamaStackAgentEntityProvider`
+- Core plugin: `McpEntityProvider`, `VectorStoreEntityProvider` — cross-cutting
+
+**Two-layer polling model:** Backstage's catalog infrastructure polls entity providers on its own schedule. Independently, each entity provider manages its own upstream refresh interval — how often it fetches from the external API (Kagenti, Llama Stack). When Backstage polls the entity provider, the provider returns its most recently cached upstream data rather than blocking on a live API call every time. The upstream refresh interval is configurable via `app-config.yaml` (defaults: 60s for models, 5m for agents/tools/MCP servers, 10m for vector stores).
 
 **Standalone mode:** Install entity providers without boost to get catalog discoverability for teams already using Llama Stack or Kagenti.
 
 **Composed mode:** Boost provider modules compose these same packages internally — one install gives you AI capabilities + catalog entities.
 
 Packages live at `rhdh-plugins/workspaces/boost/plugins/llamastack-entity-provider` and `kagenti-entity-provider`.
 
-### Decision 3: Gradual cache elimination
+### Decision 3: Catalog as source of truth from the start
 
-Phase 1: EntityProviders emit entities alongside existing caches (dual-write). Phase 2: Frontend/backend consumers switch to catalog API queries. Phase 3: Remove in-memory caches. This avoids a big-bang migration.
+Boost uses catalog entities as the primary source of truth for AI domain objects. There is no dual-write phase — entity providers emit entities directly and frontend/backend consumers query the catalog API.
 
 ### Decision 4: toolscope extraction as standalone npm package
 
-The `services/toolscope/` subsystem (29 files) has zero Backstage dependencies. Extracted as `@augment/toolscope` with injectable `CacheAdapter` interface — default in-memory adapter for standalone use, Backstage adapter wrapping `coreServices.cache`.
+The toolscope subsystem (29 files) has zero Backstage dependencies. Packaged as `@boost/toolscope` with injectable `CacheAdapter` interface — default in-memory adapter for standalone use, Backstage adapter wrapping `coreServices.cache`.
 
 ### Decision 5: 4-stage lifecycle with ownership
 
 Agents follow the 4-stage lifecycle from the start: Draft → Pending → Published → Archived. No legacy stage mappings or normalization layers — boost has no prior model to be compatible with. The `createdBy` field is set at registration and drives visibility filtering, action gating, and self-approval prevention. Cascading delete detects agent source and cleans up across corresponding stores.
 
 ### Decision 6: Skills marketplace integration (consumer only)
 
-Augment integrates with an external skills marketplace provided by a separate workspace. Augment proxies browse/filter requests to the external catalog and owns only the deployment side: K8s manifest generation with OCI init containers, namespace scoping, and deployment progress tracking. Deployed skills carry `framework: 'docsclaw'` and `chatEndpoint` for direct routing. Deployed skills appear in the gallery with a skill badge. Skills catalog entities will eventually be emitted by the catalog module alongside other agent entities.
+Boost integrates with an external skills marketplace provided by a separate workspace. Boost proxies browse/filter requests to the external catalog and owns only the deployment side: K8s manifest generation with OCI init containers, namespace scoping, and deployment progress tracking. Deployed skills carry `framework: 'docsclaw'` and `chatEndpoint` for direct routing. Deployed skills appear in the gallery with a skill badge. Skills catalog entities will eventually be emitted by the catalog module alongside other agent entities.
 
 ## Risks
 
 - **Catalog polling latency vs. cache TTL:** Catalog entities update on provider schedules, not on-demand. Mitigated by keeping short poll intervals for models (60s) and offering manual refresh.
-- **Upstream kind availability:** `AIContext` may not be ready. Mitigated by starting with existing kinds and designing for migration.
-- **Upstream augment data import:** If boost ever needs to import agent data from augment, a one-time migration script would map 5-stage values to 4-stage. This is not a runtime concern.
+- **Upstream kind availability:** `AIContext` may not be ready. Mitigated by starting with existing kinds and designing for smooth adoption.
+- **Upstream augment data import:** If boost ever needs to import agent data from augment, a one-time script would map augment's stage values to boost's 4-stage model. This is not a runtime concern.

workspaces/boost/openspec/changes/agent-creation-discovery/proposal.md

@@ -2,31 +2,59 @@
 
 ## Why
 
-An agentic AI platform is only as valuable as its agents. Augment supports four creation paths (no-code, template, DevSpaces, import), a gallery for discovery, and MCP tool connectivity. These form the supply side of the agent ecosystem.
+An agentic AI platform is only as valuable as its agents. Boost supports four creation paths (no-code, template, DevSpaces, import), a gallery for discovery, and MCP tool connectivity. These form the supply side of the agent ecosystem.
 
-The current implementation manages agents, MCP servers, and models entirely within plugin-internal caches and databases. These domain objects are natural candidates for Backstage catalog entities, which would provide discoverability, ownership, lifecycle management, and catalog-level RBAC — capabilities the current approach cannot offer.
+Boost models agents, MCP servers, models, and other AI domain objects as Backstage catalog entities from the start, providing discoverability, ownership, lifecycle management, and catalog-level RBAC that plugin-internal caches cannot offer.
 
-## What Changes
+## What Boost Builds
 
-### Current Capabilities (retroactive documentation)
+### Agent Gallery & Discovery
 
 - Browse and select agents via gallery (Kagenti) or router delegation (Llama Stack)
-- Four agent creation paths: no-code builder, Software Template, DevSpaces, import
-- MCP tool server registration with 4-level auth chain
-- Agent lifecycle: draft → registered → deployed (published=true)
 - Unified `ChatAgent` model merging agents from all providers
 
-### Architectural Improvements (from tech debt analysis)
+### Agent Creation Paths
+
+- Four creation paths: no-code builder, Software Template, DevSpaces, import
+- All paths produce agents visible in the gallery and available in chat
+
+### MCP Tool Connectivity
+
+- MCP tool server registration with 4-level auth chain
+- Per-agent tool scoping via configuration
+
+### Catalog Entity Providers
+
+- `EntityProvider` for AI agents (maps to upstream `AIContext` initiative; uses `kind: Component, spec.type: ai-agent` until upstream kinds land)
+- `EntityProvider` for AI models (`kind: Resource, spec.type: ai-model`)
+- `EntityProvider` for MCP servers (maps to upstream `API Discriminated Union v1alpha2`; uses `kind: Resource, spec.type: mcp-server`)
+- `EntityProvider` for vector stores (`kind: Resource, spec.type: vector-store`)
+- `EntityProvider` for AI tools (`kind: Resource, spec.type: ai-tool`)
+
+Entity providers are independently deployable as RHDH dynamic plugins — teams using Llama Stack or Kagenti can get catalog discoverability without installing the full boost plugin.
+
+### 4-Stage Agent Lifecycle
+
+- Draft → Pending → Published → Archived from day one
+- `createdBy` ownership drives visibility filtering, action gating, and self-approval prevention
+- Cascading delete detects agent source and cleans up across corresponding stores
+
+### Toolscope as Standalone Package
+
+- `@boost/toolscope` with zero Backstage dependencies (29 files)
+- Injectable `CacheAdapter` interface — default in-memory adapter for standalone use, Backstage adapter wrapping `coreServices.cache`
+
+### Skills Marketplace Integration
 
-- Create catalog `EntityProvider` for AI agents (maps to upstream `AIContext` initiative)
-- Create catalog `EntityProvider` for MCP servers (maps to upstream `API Discriminated Union v1alpha2`)
-- Create catalog `EntityProvider` for AI models (currently duplicated in caches #3 and #4)
-- Create catalog `EntityProvider` for vector stores
-- Extract `toolscope/` as standalone package (zero Backstage dependencies)
+- Consumer of external skills marketplace (provided by a separate workspace)
+- Proxy browse/filter requests to external catalog
+- K8s manifest generation with OCI init containers for skill deployment
 
 ## Impact
 
-- New: `plugin-augment-backend-module-catalog-agents` (EntityProvider for agents)
-- New: `plugin-augment-backend-module-catalog-mcp` (EntityProvider for MCP servers)
-- `plugins/augment-backend/src/providers/` — remove agent card and model caches in favor of catalog
-- `plugins/augment-backend/src/services/toolscope/` — extract as standalone package
+- `plugins/boost-backend/` — entity providers for MCP servers and vector stores (cross-cutting)
+- `plugins/boost-backend-module-kagenti/` — composes `kagenti-entity-provider` internally
+- `plugins/boost-backend-module-llamastack/` — composes `llamastack-entity-provider` internally
+- New: `plugins/kagenti-entity-provider/` — independently deployable catalog entities
+- New: `plugins/llamastack-entity-provider/` — independently deployable catalog entities
+- New: `packages/toolscope/` — standalone toolscope package

workspaces/boost/openspec/changes/agent-creation-discovery/specs/agent-gallery/spec.md

@@ -25,7 +25,7 @@ A full-featured agent browsing experience for the Kagenti provider.
 
 #### Scenario: First visit auto-open
 
-- **WHEN** a user visits Augment with Kagenti provider and no agent is selected
+- **WHEN** a user visits Boost with Kagenti provider and no agent is selected
 - **THEN** the agent catalog dialog auto-opens
 
 ### Requirement: Unified Agent List