OLS-2882 Align spec structure and fix health issues

.ai/spec/README.md

@@ -1,22 +1,26 @@
-# OpenShift LightSpeed Console Plugin -- Specifications
+# OpenShift LightSpeed Console Plugin — Specifications
 
-These specs define the requirements, behaviors, and architecture for the OLS console plugin (lightspeed-console). They are organized into two layers:
+The OLS console plugin is an OpenShift Console dynamic plugin that provides an AI chat assistant UI. These specs define what the plugin must do (behavioral rules) and how the current implementation is structured (codebase navigation).
 
-- **[`what/`](what/README.md)** -- Behavioral rules: WHAT the plugin must do and WHY. Technology-neutral, testable assertions. Use these to understand requirements, fix bugs, or rebuild components.
-- **[`how/`](how/README.md)** -- Architecture specs: HOW the current implementation is structured. Module boundaries, data flow, design patterns. Use these to navigate, modify, and extend the codebase.
+## Structure
+
+| Layer | Path | Purpose |
+|---|---|---|
+| **what/** | `.ai/spec/what/` | Behavioral rules. What the system must do. Implementation-agnostic. |
+| **how/** | `.ai/spec/how/` | Codebase navigation. How the code is organized. Implementation-specific. |
 
 ## Scope
 
 These specs cover the **lightspeed-console** TypeScript/React dynamic plugin only. The service (lightspeed-service), operator (lightspeed-operator), and RAG content pipeline (lightspeed-rag-content) are separate projects.
 
 ## Audience
 
-AI agents (Claude). Specs optimize for precision, unambiguous rules, and machine-parseable structure.
+AI agents. Content is optimized for precision and machine consumption.
 
 ## Quick Start
 
-| I want to... | Read |
-|--------------|------|
+| Task | Start here |
+|---|---|
 | Understand what this plugin does | `what/system-overview.md` |
 | Fix a bug in chat or streaming | `what/chat.md` + `how/streaming.md` |
 | Add a new attachment type | `what/attachments.md` + `how/components.md` |
@@ -26,9 +30,57 @@ AI agents (Claude). Specs optimize for precision, unambiguous rules, and machine
 | Understand state management | `how/state-management.md` |
 | See what's planned | Look for `[PLANNED: OLS-XXXX]` in `what/` specs |
 
+## What/ — Behavioral Specs
+
+These specs define WHAT the plugin must do — testable behavioral rules, configuration surface, constraints, and planned changes. They are technology-neutral where possible and survive a complete rewrite in a different framework.
+
+| Spec | Description |
+|------|-------------|
+| [system-overview.md](what/system-overview.md) | Plugin identity, scope, system boundaries, deployment model, relationship to OLS service |
+| [chat.md](what/chat.md) | Chat lifecycle, query submission, streaming responses, query modes, conversation management, first-time UX |
+| [attachments.md](what/attachments.md) | All attachment types (YAML, filtered YAML, events, logs, alerts, file upload, ManagedCluster), context detection, editing |
+| [tools.md](what/tools.md) | Tool call display, human-in-the-loop approval workflow, MCP App interactive UI, OLS tool UI extensions |
+| [feedback.md](what/feedback.md) | User feedback (thumbs up/down, free-text), feedback enabled/disabled, privacy notice |
+| [auth.md](what/auth.md) | Authorization check flow, auth status handling, bearer token forwarding |
+| [plugin-api.md](what/plugin-api.md) | Console extension points, useOpenOLS public API, ols.tool-ui extension type, user settings |
+
+**How to use what/ specs:**
+- **Fixing a bug**: Read the relevant spec to understand correct behavior, then compare against the code.
+- **Adding a feature**: Check if the spec covers the requirement. Update the spec before implementing.
+- **Refactoring**: Use the specs as acceptance criteria. The implementation can change freely as long as it meets the behavioral rules.
+
+## How/ — Architecture Specs
+
+These specs describe HOW the plugin is structured — module boundaries, data flow, design patterns, key abstractions, and implementation decisions. They are grounded in the current TypeScript/React codebase and should be updated when the code changes.
+
+| Spec | Description |
+|------|-------------|
+| [project-structure.md](how/project-structure.md) | Directory layout, module responsibilities, build system, dependencies, dev setup, testing |
+| [state-management.md](how/state-management.md) | Redux store shape, Immutable.js usage, actions, reducer, selectors |
+| [streaming.md](how/streaming.md) | SSE stream processing, event types, buffering, throttled dispatch, abort handling |
+| [components.md](how/components.md) | Component tree, Popover/GeneralPage/Prompt hierarchy, PatternFly Chatbot integration |
+
+**When to read how/ specs:**
+- **Navigating the codebase**: Start with `project-structure.md` to understand where things live.
+- **Modifying a subsystem**: Read the relevant spec to understand the current architecture before making changes.
+- **Debugging streaming issues**: The `streaming.md` spec traces the exact event processing path.
+
+## Cross-Reference
+
+| what/ | how/ |
+|---|---|
+| `what/system-overview.md` | `how/project-structure.md` |
+| `what/chat.md` | `how/streaming.md`, `how/components.md` |
+| `what/attachments.md` | `how/components.md` |
+| `what/tools.md` | `how/components.md` |
+| `what/feedback.md` | `how/state-management.md` |
+| `what/auth.md` | `how/project-structure.md` |
+| `what/plugin-api.md` | `how/project-structure.md`, `how/state-management.md` |
+
 ## Conventions
 
-- `[PLANNED: OLS-XXXX]` markers in `what/` specs indicate existing rules about to change due to open Jira work
-- "Planned Changes" sections list new capabilities not yet in code
-- Internal constants are stated as behavioral rules without numeric values; `how/` specs may include specific values
-- User-configurable values are referenced by their user settings key path
+- **Rule numbering:** behavioral rules are numbered sequentially within each what/ file.
+- **Planned changes:** unimplemented behavior is marked with `[PLANNED]` or `[PLANNED: OLS-XXXX]` inline next to the rule it affects.
+- **Constraints:** component-specific and cross-cutting constraints go in the relevant what/ file's Constraints section, co-located with behavioral rules. Development conventions go in CLAUDE.md.
+- **Authority:** what/ specs are authoritative for behavior. how/ specs are authoritative for implementation. When they conflict, what/ wins.
+- **When to create a new file vs. extend an existing one:** if the new concern has its own lifecycle, configuration surface, and can be understood independently, it gets its own file. If it's a capability added to an existing component, it goes in that component's file.

.ai/spec/health-report.md

@@ -0,0 +1,35 @@
+# Spec health report
+
+Last evaluated: 2026-05-29
+Trigger: post-milestone (spec-first alignment)
+Layout: software (.ai/spec/)
+
+## Stale
+
+- **`how/project-structure.md` references two deleted components**: `src/components/CloseButton.tsx` and `src/components/Modal.tsx` are listed in the Module Map but do not exist in the codebase. These were likely removed or inlined into other components.
+- **Planned Changes contain completed tickets**: `what/attachments.md` lists OLS-1401 as "(completed)" and `what/tools.md` lists OLS-2683 as "(completed)". Completed tickets should be removed from Planned Changes tables — the implemented behavior is already captured in the behavioral rules above.
+
+## Missing
+
+- **`src/pageContext.ts` not in spec**: This module contains `resolveModelKey()` which handles URL resource key resolution (direct model keys, plural-based keys, group~version~kind references). It supports attachment context detection and should be documented in `how/project-structure.md` Module Map.
+- **`src/validation.ts` not in spec**: This module contains `alertingRuleID()` (murmur3 hash generation matching the monitoring-console-plugin's rule ID format) and `isValidAlertName()`. It supports alert attachment behavior and should be in `how/project-structure.md` Module Map.
+- **CSS files not in spec**: Three CSS files exist in `src/components/` (`general-page.css`, `mcp-app.css`, `popover.css`) but are not mentioned in `how/project-structure.md` or `how/components.md`.
+- **Unit test coverage gap in spec**: `unit-tests/` includes tests for `pageContext` and `validation` — modules not documented in the spec. The test directory description in `how/project-structure.md` mentions "Tests for: redux-reducers, error handling, attachments" but doesn't mention pageContext or validation tests.
+
+## Structural concerns
+
+- None. The what/how separation is clean — behavioral rules are in what/, implementation details are in how/. No duplicated information was found across files.
+
+## Findability issues
+
+- None. The Cross-Reference table in README.md makes it straightforward to navigate between behavioral specs and their implementation counterparts.
+
+## No issues
+
+- All 9 hooks in `src/hooks/` match the spec's Module Map.
+- All 23 existing components in `src/components/` (excluding the 2 deleted ones) match the spec.
+- All 3 assets in `src/assets/` match the spec.
+- The 5 console extensions in `console-extensions.json` match the spec exactly.
+- The 27 Redux actions and 27 reducer cases match the spec's claim.
+- The Redux state shape in `how/state-management.md` matches the reducer implementation.
+- The streaming event types in `how/streaming.md` match the behavioral rules in `what/chat.md`.

.ai/spec/how/project-structure.md

@@ -18,6 +18,8 @@ and communicates with the OLS backend service via the console's plugin proxy.
 | `src/error.ts` | `ErrorType` and `FetchError` types. `getFetchErrorMessage()` extracts structured error messages from fetch responses, handling both string and object `detail` fields. |
 | `src/flags.ts` | `FLAG_LIGHTSPEED_PLUGIN` constant and `enableLightspeedPluginFlag()` handler for the `console.flag` extension. |
 | `src/clipboard.ts` | `copyToClipboard(value)` utility wrapping `navigator.clipboard.writeText()`. |
+| `src/pageContext.ts` | `resolveModelKey()` resolves URL resource keys to K8s model keys. Handles direct model keys (e.g., `Pod`), plural-based keys (e.g., `pods`), and group~version~kind references (e.g., `core~v1~Pod`). |
+| `src/validation.ts` | `alertingRuleID()` generates murmur3 hash matching the monitoring-console-plugin's alerting rule ID format. `isValidAlertName()` validates alert name strings. |
 
 ### `src/hooks/` -- Custom React hooks
 
@@ -51,20 +53,26 @@ and communicates with the OLS backend service via the console's plugin proxy.
 | `src/components/AttachEventsModal.tsx` | Modal for selecting Kubernetes events to attach. |
 | `src/components/AttachLogModal.tsx` | Modal for selecting pod logs. Container selection, line count slider, live preview. |
 | `src/components/ErrorBoundary.tsx` | React error boundary. Catches component crashes and renders fallback. |
-| `src/components/Modal.tsx` | Reusable modal wrapper component. |
 | `src/components/ResourceIcon.tsx` | Renders Kubernetes resource kind icons. |
 | `src/components/CopyAction.tsx` | Copy-to-clipboard button with visual confirmation. |
 | `src/components/ImportAction.tsx` | "Import YAML" action button. Opens confirmation modal, then navigates to console's YAML import page with content. |
 | `src/components/NewChatModal.tsx` | Confirmation modal for clearing chat. |
 | `src/components/ReadinessAlert.tsx` | Alert shown when OLS service is not ready. |
 | `src/components/WelcomeNotice.tsx` | Welcome message for first-time users. |
 | `src/components/ConfirmationModal.tsx` | Generic confirmation dialog. |
-| `src/components/CloseButton.tsx` | Close icon button. |
 | `src/components/NullContextProvider.tsx` | No-op React context provider returning `null`. Used as the component for the `console.context-provider` extension. |
 | `src/components/OverviewDetail.tsx` | Dashboard detail item showing plugin version. |
 
 ### `src/assets/` -- Static assets
 
+| Path | Purpose |
+|---|---|
+| `src/components/general-page.css` | Styles for the GeneralPage chat interface |
+| `src/components/mcp-app.css` | Styles for MCP App card and iframe container |
+| `src/components/popover.css` | Styles for the Popover modal and floating button |
+
+### `src/assets/` -- Static assets
+
 | Path | Purpose |
 |---|---|
 | `src/assets/logo.svg` | OLS logo for light theme |
@@ -91,7 +99,7 @@ and communicates with the OLS backend service via the console's plugin proxy.
 | `tests/` | Cypress e2e test specs |
 | `cypress/` | Cypress support files and fixtures |
 | `cypress.config.ts` | Cypress configuration |
-| `unit-tests/` | Unit tests using Node's built-in test runner. Tests for: redux-reducers, error handling, attachments |
+| `unit-tests/` | Unit tests using Node's built-in test runner. Tests for: redux-reducers, error handling, attachments, pageContext (model key resolution), validation (alert rule ID hashing) |
 
 ## Data Flow
 

.ai/spec/what/attachments.md

@@ -144,7 +144,6 @@ sending.
 
 | Jira Key | Summary |
 |---|---|
-| OLS-1401 | Upload local YAML files (completed) |
 | OLS-1896 | ACM: Attach ApplicationSet objects from Applications page |
 | OLS-2065 | ACM: Attach policy violations |
 | OLS-2116 | ACM: Attach cluster info in ACM-enabled environments |

.ai/spec/what/tools.md

@@ -152,7 +152,6 @@ interactive MCP App UIs and OLS-native tool visualizations.
 
 | Jira Key | Summary |
 |---|---|
-| OLS-2683 | MVP for HITL approve/deny (completed) |
 | OLS-2722 | OLS Tool UI extensibility from external plugins |
 | OLS-2598 | MCP Apps support in OLS console |
 | OLS-1556 | Display info about tools called while generating OLS response |

AGENTS.md

@@ -1,3 +1,7 @@
+## Specs
+
+All specifications live in `.ai/spec/`. Start with `.ai/spec/README.md` for project overview, reading order, and structure guide.
+
 ## AI Agents Guide
 
 Basic guardrails and quick-start for AI coding agents contributing to this