Part 9 optional operations-assistant step is not independently reproducible

[jongalloway]

Issue type

documentation

Requested priority

P2 - A workaround exists, an optional path is broken, or significant drift exists

Workshop area

Part 9 - Adding AI to an Existing App

Summary

Part 9 optional Step 3 asks attendees to create a capped SearchTelemetry queue, register it, modify ProductDiscovery, add an operations assistant, and build an Operations page, but it does not provide the complete source or enough implementation detail to reproduce the answer without consulting eShopLite/.

Steps 1 and 2 are literal attendee exercises; Step 3 currently switches to an incomplete mixture of prose and fragments without clearly stating that the answer snapshot is required.

Attendee or instructor impact

The optional local-model concept is useful, but an attendee who chooses to implement it must invent concurrency, queue-capping, telemetry-recording, dependency-injection, prompt, and UI details. Different implementations may not match the expected behavior or snapshot.

The workaround is to read or copy the completed answer project, which weakens the exercise and is not stated as a requirement.

Reproduction or proposed change

1. Copy Part 09 - Adding AI to an Existing App/eShopLite-start/ to a scratch directory.
2. Complete required Steps 1 and 2 using only the README.
3. Attempt optional Step 3 without opening the completed eShopLite/ snapshot.
4. Implement the requested SearchTelemetry.cs, service registration, ProductDiscovery changes, local keyed client, OperationsAssistant, and Operations page.

The README does not provide the complete implementation needed to reproduce:

• the capped telemetry data structure and synchronization behavior;
• how searches are recorded in ProductDiscovery;
• the full operations-assistant prompt and response flow;
• the complete Operations.razor component;
• all navigation and dependency-injection changes.

Proposed change: choose one of these explicit modes.

1. Hands-on option: provide complete source blocks and exact edits for every Step 3 file, as Steps 1 and 2 do.
2. Exploration option: label Step 3 as read-only exploration, direct attendees to the specific completed files, and remove instructions that imply they can build it independently from the prose.

Retain the existing rule that testing must not download a model automatically; instructors should provide a configured Foundry Local or Ollama endpoint.

Expected outcome

The optional section is either fully reproducible from the README or clearly presented as an answer-key walkthrough rather than an implementation exercise.

Validation

• Start from a fresh tracked-file copy of eShopLite-start.
• Complete Step 3 using only the chosen documentation path.
• Build in Release with zero warnings.
• Configure an existing local OpenAI-compatible endpoint without downloading a model.
• Generate search telemetry through the storefront.
• Confirm the Operations page summarizes the captured searches.
• Confirm required Steps 1 and 2 remain unchanged and functional.

Dependencies and related issues

The required Part 9 flow fixed by #633 now passes. This issue is limited to optional Step 3. The separate Aspire-version PR may affect project package versions but should not change the documentation completeness requirement.

[jongalloway]

Revalidated in the 2026-09-13 end-to-end run at commit 6040eaf. Required Part 9 Steps 1 and 2 remain independently reproducible and pass, but optional Step 3 still requires the completed eShopLite/ answer snapshot for the capped telemetry queue, recording flow, operations assistant, DI wiring, and Operations page. The configured local endpoint was unavailable, so runtime local-model validation was skipped without downloading a model; the documentation-completeness finding is independent of endpoint availability.