docs(step-05): clarify how retrieval works and correct inaccurate claims

[Pierre Malarme (pmalarme)]

Why

Step 5 leaned on the phrase "grounds every turn" without ever defining a turn, which left the most surprising behaviour of semantic mode undocumented. The provider fires once per turn, but it builds its query by joining every replayed user and assistant message — and because a grounded answer quotes the record it used, each reply feeds the previous destination back into the next query.

Working through a real debugging session on this step also surfaced several claims in the doc that don't survive reading the provider source.

What changed

Explaining the mechanism

• A "What's a turn?" definition, and an explicit split between when the provider runs (per turn) and what it searches with (the replayed conversation).
• A captured [RAG] query=... hits=... trace plus a Playground screenshot showing turn 2's query carrying the whole of turn 1's answer.
• A note that context providers leave no trace in View run info, since they shape the request rather than the model's output, with an optional debug-provider snippet.
• A three-way comparison of retrieval shapes: semantic provider, agentic + Foundry IQ, and retrieval as an MCP tool.

Corrections (each verified against agent_framework_azure_ai_search or Azure docs)

• sourceName / sourceLink are never surfaced — _extract_document_text injects content prefixed with [Source: <id>], so the record id is the citation handle. Removed the promises that answers "cite" records.
• Disabling RAG by unsetting AZURE_AI_SEARCH_ENDPOINT cannot work: the running process already read it, and a restart without it fails fast with KeyError. Now says to comment out context_providers and ask in a New Session, so the earlier answer isn't replayed.
• The canary token is a strong signal, not proof — it lives in a public template repo.
• Foundry IQ does not change which identity reaches Search when you call it from your own code; only Foundry Agent Service's managed integration uses the project MI.
• retrieval_reasoning_effort="minimal" skips LLM query planning (Learn), so the agentic snippets get a managed knowledge base but no sub-query decomposition.
• top_k is read only by the semantic path — it was a no-op in both agentic snippets.
• The agentic walkthrough referenced the wrong step, used context_providers.append(...) where it meant to swap, understated the role needed to create a knowledge base, and misdescribed how to get the preview SDK into the container.

Other

• New troubleshooting entry for a city that's in destinations.json but not in the index — the failure that looks identical to crowd-out.
• The manifest section is split into per-concern blocks with block-style tags, matching Step 4 and removing the horizontal scroll caused by a long inline tags: [...] line.
• The MCP tool sketch validates against an allowlist rather than forwarding caller text into search_text, where -, |, and * are query operators.
• The agentic and MCP paths are marked 🧪 experimental, following the convention already used in steps 08 and 09.

Scope

Documentation only — .workshop/docs/steps/05-rag.md plus one new asset. No change to travel_assistant/ code, .workshop/solutions/, or .workshop/step_files/; the new variants are explicitly optional sketches, so the source-of-truth rule is satisfied.

Validation

• python .workshop/scripts/lint_steps.py → 0 failures (2 pre-existing warnings)
• python -m pytest .workshop/scripts/tests → 154 passed
• render_readme.py --step 5 inspected; all cross-reference anchors resolve against the rendered headings
• Three rubber-duck review rounds; findings fixed or explicitly scoped out