# Plan Review: Step 3 — Update generated docs and stale-catalog guidance

Verdict: **REVISE**

STATUS does not yet contain a concrete Step 3 plan; it only has the original checklist. For this docs step, that leaves important user-facing semantics underspecified.

## Blocking issues

1. **Diagnostic comparison wording is not planned.**  
   The docs must use the implemented field semantics precisely: compare the visible tool-description fields (`description_server_version`, `description_catalog_fingerprint`, `description_toolset`, `description_delete_mode`) with the diagnostic response fields (`server_version`, `description_catalog_fingerprint`, `toolset`, `delete_mode`). Do not tell users to compare `description_catalog_fingerprint` to the live `catalog_hash`; those are different values.

2. **Reconnect vs new conversation guidance is underspecified.**  
   The task requires guidance on when to reconnect/reload MCP tools versus when to start a new chat. The plan should state the intended rule, e.g. reconnect/reload the MCP client when the visible description baseline differs from the diagnostic response, and start a new conversation when `_meta.schema_changed` is visible or the current chat continues using stale schemas/context after reconnecting.

3. **Generated-doc scope needs to be explicit.**  
   `make docs-tools` currently regenerates `web/data/tools.json`; `web/content/reference/tools.md` is a shortcode wrapper, not directly regenerated by that target. The plan should call out running `make docs-tools`, verifying the new `icuvisor_check_server_version` entry appears in the generated catalog data under the meta group, and only touching `web/content/reference/tools.md` if surrounding prose actually needs a change.

4. **Privacy/no-telemetry wording needs concrete guardrails.**  
   The documentation plan should explicitly avoid suggesting telemetry, cloud checks, credential upload, filesystem inspection, or intervals.icu API calls. It should say the diagnostic is local/read-only/no-argument and returns catalog/version/delete-mode/toolset metadata only.

## Expected revised Step 3 plan

Please update STATUS with a short docs plan covering:

- run `make docs-tools` and verify `web/data/tools.json` contains the meta-tool entry;
- update `after-upgrade.md` with the `_meta.schema_changed` path and the visible-description diagnostic fallback for clients that hide `_meta`;
- update `troubleshooting.md` stale-catalog steps with the diagnostic call and clear reconnect vs new-conversation actions;
- add a `[Unreleased]` changelog entry under `Added` for the new read-only diagnostic tool;
- verify docs use exact field names and do not imply telemetry, cloud service, credential upload, athlete-data exposure, or automatic server-side stale-client detection.
