OLS-0000 Sync .ai/spec with current code

.ai/spec/health-report.md

@@ -0,0 +1,95 @@
+# Spec health report
+
+Last evaluated: 2026-08-31
+Trigger: post-milestone: spec-drift alignment sweep
+Layout: software (.ai/spec/)
+
+## Stale
+
+Fixed in this pass:
+
+- **`what/system-overview.md` rule 13** — readiness was described as the
+  `/readyz` endpoint returning a non-2xx status. Actual code
+  (`src/components/ReadinessAlert.tsx`) polls `/readiness` via
+  `consoleFetchJSON` and checks a JSON `{ ready: boolean }` body, re-polling
+  every 10s until ready. Endpoint name and mechanism corrected.
+
+- **`what/chat.md` rule 8 event table** — listed `reasoning` and
+  `skill_selected` events as "consumed with no-op handling — payload is never
+  rendered, logged, or passed to `console.warn`." No handler for these events
+  exists anywhere in `src/` (never has, per `git log -S`); they fall through to
+  the default `console.warn` branch in `Prompt.tsx`. Rows removed; added a note
+  that any unlisted event is treated as unrecognized and warned.
+
+- **`what/tools.md` Planned Changes** — OLS-1556 (tool display), OLS-2598 (MCP
+  Apps), OLS-2722 (OLS Tool UI extensibility) are all shipped and documented as
+  current behavior (rules 1-7, 15-27; code: `ResponseTools.tsx`, `MCPApp.tsx`,
+  `OlsToolUIs.tsx`, `useToolUIMapping.ts`, `ols.tool-ui` extension). Removed
+  from planned.
+
+- **`what/system-overview.md` Planned Changes** — removed OLS-2598 and
+  OLS-2722 (shipped, see above) and OLS-2816 / OLS-2826 (shipped:
+  `useOpenOLS` implements `submitImmediately` + `hidePrompt`; chat.md rules 28
+  and 29 document them as current).
+
+- **`what/attachments.md` Planned Changes** — removed OLS-2116 (ManagedCluster
+  "Attach cluster info" + ManagedClusterInfo fetch shipped in `Prompt.tsx`;
+  rule 13 documents it) and OLS-1896 (ACM Application/ApplicationSet detection
+  shipped in `useLocationContext.ts`; rule 1 documents it).
+
+- **`how/streaming.md` module map** — attributed the `QUERY_ENDPOINT` constant
+  to `src/config.ts`. It is actually defined in `src/components/Prompt.tsx`
+  (`getApiUrl('/v1/streaming_query')`); `config.ts` only provides `getApiUrl`.
+  Corrected.
+
+- **`how/components.md` module map** — listed a `Modal.tsx` "reusable modal
+  wrapper" that does not exist. Replaced with the actual generic dialog,
+  `ConfirmationModal.tsx` (used by `ImportAction.tsx`).
+
+## Missing
+
+Fixed in this pass:
+
+- **`how/project-structure.md` Plugin -> OLS Service table** — the `/readiness`
+  endpoint (polled by `ReadinessAlert`) was absent. Added a `GET /readiness`
+  row.
+
+## Structural concerns
+
+None. what/ vs how/ separation is clean; no behavioral rules leaked into how/
+files and vice versa.
+
+## Findability issues
+
+None. README quick-start, cross-reference, and what//how/ index tables list
+every spec file that exists (7 what/, 4 how/). The `decisions/` ADR directory
+is self-describing.
+
+## No issues (verified current)
+
+- `what/plugin-api.md` — console-extensions.json matches (5 extensions: flag,
+  context-provider, dashboards detail, redux-reducer, action/provider);
+  `useOpenOLS` signature matches rule 5.
+- `how/state-management.md` — 27 actions in the `ActionType` enum match the
+  "27 actions" claim; state shape and action table match `redux-reducers.ts`.
+- `how/streaming.md` event dispatch — matches the `Prompt.tsx` event chain
+  (start, token, end, tool_call, approval_required, tool_result,
+  history_compression_start/end, error, default warn) including the
+  `tool_meta.ui.resourceUri` / `tool_meta.olsUi.id` extraction.
+- API endpoint constants across `config.ts` consumers verified against code.
+- Still-accurate PLANNED items left untouched: OLS-2743 (rebrand), OLS-2700
+  (agent mode), OLS-2608 / OLS-2609 (PromQL embeds), OLS-2065 (ACM policy
+  violations), OLS-2284 (cluster info on Nodes/Add-ons tabs) — none of these
+  are present in the code.
+
+## Deliberately NOT changed
+
+- `how/components.md` module map is a curated subset of the component tree
+  (chat/tool/attachment focus). Utility components like `ReadinessAlert`,
+  `WelcomeNotice`, `CopyAction`, `OverviewDetail`, etc. are intentionally
+  omitted there and fully listed in `how/project-structure.md`. Not drift.
+- `what/tools.md` rule 15 phrasing ("uiResourceUri and serverName in its
+  `tool_meta`") — `serverName` actually comes from the top-level `server_name`
+  field, not `tool_meta`. This is a how/ detail already documented correctly in
+  `streaming.md`; the behavioral intent (both must be present) holds, so the
+  what/ rule was left as-is to avoid leaking implementation detail.

.ai/spec/how/components.md

@@ -22,7 +22,7 @@ PatternFly 6 and the PatternFly AI Chatbot library.
 | `AttachLogModal.tsx` | Modal | Log selection for attachment |
 | `AttachmentsSizeAlert.tsx` | Alert | Warning for large attachments |
 | `ErrorBoundary.tsx` | Utility | React error boundary |
-| `Modal.tsx` | Utility | Reusable modal wrapper |
+| `ConfirmationModal.tsx` | Utility | Generic confirmation dialog (used by `ImportAction`) |
 
 ## Data Flow
 

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

@@ -230,6 +230,7 @@ In development, `start-console.sh` configures an additional proxy from the conso
 | Method | Path | Purpose |
 |---|---|---|
 | POST | `/authorized` | Authorization check |
+| GET | `/readiness` | Service readiness poll (drives `ReadinessAlert`); returns JSON `{ ready: boolean }` |
 | POST | `/v1/streaming_query` | Submit query, receive SSE stream |
 | GET | `/v1/feedback/status` | Check if feedback is enabled |
 | POST | `/v1/feedback` | Submit user feedback |

.ai/spec/how/streaming.md

@@ -8,9 +8,9 @@ All stream processing logic lives in `src/components/Prompt.tsx` within the
 
 | Path | Purpose |
 |---|---|
-| `src/components/Prompt.tsx` | Stream initiation, SSE reading, event parsing, Redux dispatch for all event types |
+| `src/components/Prompt.tsx` | Stream initiation, SSE reading, event parsing, Redux dispatch for all event types. Defines the `QUERY_ENDPOINT` constant (`getApiUrl('/v1/streaming_query')`) |
 | `src/redux-actions.ts` | Actions dispatched during streaming: `setConversationID`, `chatHistoryUpdateByID`, `chatHistoryUpdateTool` |
-| `src/config.ts` | `QUERY_ENDPOINT` constant built from `getApiUrl()` |
+| `src/config.ts` | `getApiUrl(path)` helper used to build `QUERY_ENDPOINT` |
 | `src/error.ts` | `getFetchErrorMessage()` for error extraction |
 
 ## Data Flow

.ai/spec/what/attachments.md

@@ -144,7 +144,5 @@ sending.
 
 | Jira Key | Summary |
 |---|---|
-| 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 |
 | OLS-2284 | ACM: Add "Attach cluster info" option for Nodes and Add-ons tabs |

.ai/spec/what/chat.md

@@ -53,10 +53,11 @@ and first-time user experience.
    | `tool_result` | `id`, `content`, `status`, `server_name`, `structured_content`, `tool_meta` | Update tool with execution result |
    | `history_compression_start` | (none) | Show compression-in-progress indicator |
    | `history_compression_end` | `duration_ms` | Show compression-complete indicator with duration |
-   | `reasoning` | `reasoning` | Chain-of-thought chunk; consumed with no-op handling — payload is never rendered, logged, or passed to `console.warn` |
-   | `skill_selected` | `name` | Skill matched to query; consumed with no-op handling — payload is never rendered, logged, or passed to `console.warn` |
    | `error` | error details | Display error alert, stop streaming |
 
+   Any event type not listed above is unrecognized and logged via
+   `console.warn` (see `how/streaming.md`).
+
 9. Token updates to the UI must be throttled to prevent excessive re-renders
    during streaming. Updates must use trailing-edge throttling so the final
    token is always rendered.

.ai/spec/what/system-overview.md

@@ -65,12 +65,13 @@ product is being rebranded to "Red Hat OpenShift Intelligent Assistant."
 
 13. A `ReadinessAlert` component is displayed in the chat content area when
     the OLS service is not ready or unavailable. Readiness is determined
-    globally (not per-response) via the `/readyz` endpoint, polled
-    periodically by the plugin. The alert appears when the endpoint returns
-    a non-2xx status or is unreachable. It disappears when a subsequent poll
-    returns a 2xx response (readiness restored). Request-level errors during
-    streaming do not control the `ReadinessAlert`; those surface as inline
-    alerts on the affected response entry instead.
+    globally (not per-response) via the `/readiness` endpoint, which returns
+    a JSON body with a `ready` boolean. The plugin polls the endpoint and
+    shows the alert while the response is not `ready` (or the request fails
+    or is unreachable), re-polling every 10 seconds until readiness is
+    reported. Once `ready` is `true` the alert is hidden. Request-level
+    errors during streaming do not control the `ReadinessAlert`; those
+    surface as inline alerts on the affected response entry instead.
 
 ### Query Modes
 
@@ -176,10 +177,6 @@ Environment variables (development only):
 | Jira Key | Summary |
 |---|---|
 | OLS-2743 | Rebranding to "Red Hat OpenShift Intelligent Assistant" |
-| OLS-2598 | MCP Apps support in OLS console |
 | OLS-2700 | Allow users to choose agent mode (PF6 only) |
-| OLS-2722 | OLS Tool UI extensibility from external plugins |
 | OLS-2608 | Embed PromQL QueryBrowser in OLS responses |
 | OLS-2609 | Embed PromQL scalar values in OLS responses |
-| OLS-2816 | Option to immediately submit prompt when opening OLS programmatically |
-| OLS-2826 | Hide the initial prompt when opening OLS programmatically |

.ai/spec/what/tools.md

@@ -151,8 +151,6 @@ interactive MCP App UIs and OLS-native tool visualizations.
 
 ## Planned Changes
 
-| Jira Key | Summary |
-|---|---|
-| 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 |
+None currently planned. Tool call display (OLS-1556), MCP Apps support
+(OLS-2598), and OLS Tool UI extensibility (OLS-2722) have all shipped and
+are documented as current behavior above.