Documentation remediation: repair broken links, fill missing media slots, and correct web search documentation

[paullizer]

Summary

The documentation site has two classes of decay that need a coordinated fix, plus one page whose content is factually out of date with the application.

The docs/how-to/*.md pages were renamed and relocated to docs/guides/*.md (snake_case to kebab-case) during the documentation site redesign (#1293). Jekyll redirects were added for the site, but repository-relative markdown links in README.md and the deployer READMEs still point at the old file paths. Those links resolve to 404 on GitHub, where Jekyll redirects do not apply. Separately, a large number of media slots registered by the redesign were never filled, and the use-web-search documentation still describes the retired Bing Web Search API rather than the Azure AI Foundry agent path that is actually implemented.

No documentation content was lost. Every page reported as "missing" exists under its new path.

Scope

1. Broken repository-relative links (46 of 183 checked)

Location	Count	Nature
README.md	3	docs/how-to/upgrade_paths.md (x2), docs/how-to/docker_customization.md
deployers/bicep/README.md	2	old docs/how-to/ paths
deployers/terraform/ReadMe.md	4	old docs/how-to/ paths, ../README.md
deployers/azurecli/README.md	2	../README.md should be ../../README.md
docs/explanation/features/v*/, docs/explanation/fixes/v*/	34	archived version-stamped docs linking siblings that were never migrated

Correct targets: docs/guides/upgrade-paths.md, docs/guides/docker-customization.md, docs/guides/enterprise-networking.md.

2. Broken site URLs (6 real, of 625 relative_url links checked)

• /application_scaling/ (x3) in docs/index.md, docs/start/about.md, docs/guides/admin-operate-simplechat.md. Source page no longer exists; content moved to /guides/scale-simplechat-on-azure/.
• /reference/admin_configuration/ (x2) in docs/guides/configure-branding-and-support-settings.md and docs/reference/features.md, plus 10 additional occurrences in docs/_data/features.yml. Correct target is /admin_configuration/.
• /how-to/model_endpoint_identity_setup/ (x1) in docs/explanation/features/v0.241.001/WORKSPACE_MULTI_ENDPOINTS.md.

3. Missing documentation media (146 of 170 registered slots are empty)

Group	Empty slots
guides/* images	63 across 30 pages
reference/actions/* configuration screenshots	27 (one per action page)
reference/chat-controls.md	9
admin/* overview screenshots	4
Video posters	43 (all 43 also have no video URL)

Only 17 image slots are currently filled. 328 images already exist under docs/images/ (127 at the root, 187 under latest-release, 14 under admin-settings), and a significant portion of the root images map directly onto empty slots, so a reuse pass should close a meaningful share before any new capture work begins.

4. Web search documentation is factually stale

docs/guides/use-web-search.md and its companions describe "Bing web search". The Bing Web Search API was removed in v0.229.001. The implemented path is an Azure AI Foundry agent using Grounding with Bing Search, configured through web_search_agent.other_settings.azure_ai_foundry.agent_id.

The documentation also understates a privacy property that the code guarantees. build_web_search_query_text() in route_backend_chats.py returns only the trimmed current user message; conversation history, workspace documents, uploaded file contents, and system prompts are never sent to the external search boundary. This was deliberately hardened in v0.241.022 (WEB_SEARCH_EGRESS_HARDENING_FIX) and should be a prominent, explicit section rather than a passing sentence.

Affected files: docs/guides/use-web-search.md, docs/guides/index.md, docs/features.md, docs/reference/chat-controls.md, docs/admin/knowledge.md.

Acceptance Criteria

• A functional_tests/test_docs_link_integrity.py test fails on any broken relative .md link across README.md, docs/, and deployers/, and on any unresolved relative_url page link, including URLs declared in docs/_data/features.yml and _config.yml navigation.
• All 12 broken links in README.md and the deployer READMEs resolve.
• All 6 broken site URLs resolve, and the 10 features.yml occurrences are corrected.
• Old URLs continue to resolve via redirect_from on the destination pages so existing bookmarks and external links do not break.
• The 34 archived links are either repointed to a valid target or unlinked, preserving the prose.
• docs/guides/use-web-search.md correctly describes the Azure AI Foundry agent path, carries a dedicated section stating exactly what data leaves the application, documents the Deep Research multi-query nuance, and reproduces the Grounding with Bing Search compliance-boundary notice.
• Existing images under docs/images/ are reused for every slot where a suitable capture already exists, before new screenshots are taken.
• A repeatable capture harness exists under scripts/, reusing the established ui_tests Playwright conventions (SIMPLECHAT_UI_BASE_URL, SIMPLECHAT_UI_STORAGE_STATE, SIMPLECHAT_UI_ADMIN_STORAGE_STATE).
• Remaining screenshots are captured and committed in batches of 20.
• A deliberate decision is recorded for the 43 video slots: either branded poster frames are generated, or the slots are removed from pages that will not receive a recording.
• docs/_data/app_surface.yml is regenerated, and test_docs_app_surface_coverage.py, test_docs_site_quality.py, and the new link-integrity test all pass.
• application/single_app/config.py version and deployers/version.txt are bumped, and release notes are updated.

Notes

Delivered in phases so each is independently reviewable and committable:

1. Phase 0 - link and media integrity test (the regression guard; without it these links re-break in a few releases).
2. Phase 1 - the 12 README.md and deployer links. Touches deployers/**, so deployers/version.txt is bumped.
3. Phase 2 - the 6 site URLs and features.yml.
4. Phase 3 - web search documentation rewrite.
5. Phase 4 - archived link cleanup.
6. Phase 5 - reuse existing images for empty slots (no capture cost).
7. Phase 6 - Playwright capture harness.
8. Phase 7 - screenshot capture in batches of 20, one commit per batch.
9. Phase 8 - video poster decision.
10. Phase 9 - version bump, full test pass, release notes.

Related to #1293, which introduced the reorganization and registered the media slots.

[paullizer]

Progress: Phases 0-4 complete (v0.261.003)

Regression guards added

• functional_tests/test_docs_link_integrity.py - fails on any broken relative markdown link across README.md, docs/, and deployers/; on any unresolved Jekyll relative_url page link; on URLs in docs/_data/features.yml; and on media includes naming an unregistered slot. Outstanding screenshots are reported but never fail the run, per docs_coverage.instructions.md.
• functional_tests/test_docs_web_search_accuracy.py - ties the published privacy claim to the implementation. If build_web_search_query_text ever starts folding conversation history back into the outbound query, the test fails and names the pages that must be corrected with it.
• functional_tests/test_docs_release_notes_integrity.py - see the recovery section below.

Broken links repaired (46 of 183)

All 46 now resolve. Repository-relative links: 12 in README.md and the deployer READMEs, remapped from docs/how-to/<snake_case>.md to docs/guides/<kebab-case>.md, plus the ../README.md -> ../../README.md correction in the Azure CLI and Terraform deployers. A stale path in deployers/azurecli/deploy-simplechat.ps1 output text was corrected too.

Archived links: 34 across 15 per-version engineering notes. 10 were repointed to targets that had moved; 24 had targets that were never migrated and are now unlinked prose rather than dead hrefs.

deployers/version.txt bumped to 1.0.26.

Correction to the original scope: item 2 was a false alarm

The 6 "broken" site URLs in the issue body resolve correctly. jekyll-redirect-from is enabled, and both targets are declared as redirect_from on their replacement pages:

• /application_scaling/ is declared on docs/guides/scale-simplechat-on-azure.md.
• /reference/admin_configuration/ is declared on docs/admin_configuration.md, which also covers the 10 features.yml occurrences.

My original audit did not resolve redirect_from, so it reported false positives. No change was needed. The new link integrity test resolves permalink and redirect_from correctly and confirms all 609 site page links and all 58 features.yml links resolve.

Web search documentation corrected

docs/guides/use-web-search.md rewritten, with companion summaries updated in docs/guides/index.md, docs/features.md, docs/reference/chat-controls.md, and docs/admin/knowledge.md.

• The mechanism is now described accurately: an Azure AI Foundry agent using the Grounding with Bing Search tool, not the Bing Web Search API removed in v0.229.001.
• Added a dedicated What leaves SimpleChat section stating the boundary plainly, with an explicit exclusion list covering conversation history, workspace documents, attached file contents, system prompts, agent instructions, and workspace or document names.
• Documented the Deep Research nuance: several planned queries instead of one, all still derived from the current message alone.
• Added the Grounding with Bing Search compliance-boundary notice to the user-facing guide.
• Replaced the placeholder descriptions in the admin Web Search settings table, which previously read like "Narrows the admin list shown for foundry agent id".
• Reused the existing docs/images/workflow-web_search.png architecture diagram instead of leaving a "recording planned" video card, which also removed one outstanding video slot.

Unplanned find: 27 release note sections had been lost

While regenerating the release notes pages I found that docs/explanation/release_notes.md had been truncated from 46 version sections to 19 by commit 7772a3f1 ("Update release_notes.md", 2026-08-26). It dropped every v0.260 entry plus v0.250.229 through v0.250.231.

This was invisible because the pages that render release notes are generated from that file and had not been rebuilt since. The site still served the missing history, so the repository was one routine build_release_notes_pages.py run away from erasing roughly 2,400 lines of release notes with no apparent cause. I caught it because that run was about to happen as part of this work.

The 27 sections were recovered from history and the pages regenerated. Source and site now agree at 48 sections across 8 pages, with no duplicate or out-of-order entries. test_docs_release_notes_integrity.py now fails if a version is published but missing from the source, or present in the source but missing from the pages, so neither truncation nor staleness can hide again.

Validation

Test	Result
test_docs_link_integrity	5/5
test_docs_web_search_accuracy	3/3
test_docs_release_notes_integrity	1/1
test_docs_site_quality	6/6
test_docs_app_surface_coverage	7/7
test_docs_latest_release_catalog_parity	6/6

Remaining

Media coverage is unchanged at 18 of 122 screenshot slots filled, 104 outstanding, plus 43 video posters. Still to do:

• Reuse pass over the 127 existing images at the root of docs/images/ before any capture work.
• Playwright capture harness under scripts/, reusing the ui_tests environment conventions.
• Screenshot capture in batches of 20, one commit per batch.
• A deliberate decision on the 43 video slots.

[paullizer]

Progress: screenshot batches 1 and 2

Screenshot coverage is now 47 of 122 slots filled, up from 18. The Administration group is fully illustrated.

Batch 1 (19 slots)

Area	Slots
Admin settings overviews	Backup & Recovery, Data Lifecycle, Governance, Workflow
Chat control reference	conversation list, conversation header, composer, selectors, grounded search, advanced conversation search
Task guides	web search, Deep Research, workspace scope lock, group workspaces (x2), tags, agent creation, action type selection, workflow creation

Batch 2 (10 slots)

Action configuration reference for Azure Maps, plus task guide steps for action configuration, file sync source type and configuration, the public workspace directory, image generation, pasted URL review, profile preferences, workflow triggering, and send feedback.

Notes

The web search capture includes the live data notice, so the guide's claim that only the current message leaves the application is now visible in the documentation rather than only asserted.

Two captures needed redaction rather than a straight screenshot. The Send Feedback form and the profile page both render the signed-in account email address. The feedback form fields were replaced with a neutral placeholder address, and the profile capture is cropped to the settings panel so the account banner is excluded.

Placeholder alt text such as alt="Screenshot showing create an agent step 3." was replaced on every filled slot with a description of what the reader learns from the image. The generated text was useless to a screen reader and restated the step number.

No version bump for either batch; all changes are confined to docs/.

Deliberately deferred

26 of the 27 action configuration slots. Each requires selecting an action type, naming the action, and stepping through a five-stage wizard to reach the Configuration pane. That is a near-identical flow repeated 27 times, which belongs in the scripted capture harness rather than manual browser driving. Only 12 action types are enabled on the tenant used for capture, so the remaining 15 need a differently configured environment regardless.

Remaining

• 45 guide slots and 29 reference slots outstanding.
• Build the scripted capture harness under scripts/, then run the action configuration slots through it.
• 43 video slots still need a decision. The issue owner has indicated they will handle video separately.

Branch status

Upstream write access to microsoft/simplechat lapsed partway through this work; repos/microsoft/simplechat currently reports "push": false for the author. Both commits are pushed to the fork at paullizer/simplechat, branch docs/1371-link-integrity-and-web-search. The upstream branch of the same name still holds only the first commit and needs the remaining two once access is restored.

[paullizer]

Progress: action configuration screenshots

Screenshot coverage is now 58 of 122 slots filled, up from 18 at the start of this issue. The reference/actions group drops from 27 outstanding to 16.

Captured the Configuration pane for eleven action types: Blob Storage, Chart, Cosmos Query, Databricks, Document Search, Log Analytics, MCP, Microsoft Graph, OpenAPI, RocksDB and SimpleChat. These join the Azure Maps pane captured earlier, so all twelve action types enabled on the capture tenant now have a real screenshot.

Safety of these captures

No action was saved and no connection was tested. Every credential field in these images shows only its shipped placeholder hint. Connection strings, access tokens, workspace IDs, endpoints and subscription keys are placeholder text, not tenant values.

Remaining

• 16 reference slots. Thirteen are action types not enabled on the capture tenant and need a differently configured environment. Three are chat control dialogs that still need capturing: export/fork/delete, collaboration, and voice input.
• 45 guide slots.
• 43 video slots, which the issue owner is handling separately.

All work is pushed to origin on branch docs/1371-link-integrity-and-web-search.