# Plan Review R008 — Step 4

Verdict: REVISE

The Step 4 checklist is directionally right, but it is still too generic for the workflow changes already made in earlier steps.

## Blocking revisions

1. **Name the documentation targets that must change.**
   `cmd/gendocs` now writes a second generated file, `web/data/tool_schemas.json`, and the Hugo partial fails if it is missing. The plan should explicitly cover updating generation guidance, at least:
   - `web/README.md` layout bullet(s): mention both `data/tools.json` and `data/tool_schemas.json` as generated by `make docs-tools` / `cmd/gendocs` and not hand-edited.
   - `README.md` development command description if needed: make `make docs-tools` describe regenerating website tool catalog/schema data, not just the catalog.
   - `Makefile` target help/comment if Step 4 includes user-facing command guidance (`make help` currently says only `web/data/tools.json`).
   - `CONTRIBUTING.md`: either update it if contributor workflow changes, or explicitly record that no change is needed because schema snapshots remain a separate `scripts/snapshot_tool_schemas.go` workflow.

2. **Handle stale-generation coverage for the new generated file.**
   The existing CI guard only diffs `web/data/tools.json` after `make docs-tools`. With the new generated `web/data/tool_schemas.json`, a schema-docs change can become stale without CI catching it. The Step 4 plan should either add/update the generated-docs guard to include both files, or explicitly log a caveat/follow-up in `STATUS.md` if changing `.github/workflows/ci.yml` is intentionally out of scope. For this task's “docs stay aligned with the actual registry” goal, updating the guard is preferable.

3. **Make the internal-only exposure check concrete.**
   “Internal-only exposure reviewed” should specify the verification method, e.g. compare `web/data/tool_schemas.json` keys against `web/data/tools.json` names / `tools.Catalog()` after `make docs-tools`, and confirm no extra keys are emitted. Record the result in `STATUS.md`.

4. **Spell out the TP-153 dependency note.**
   TP-153 is not started. The plan should record that this generator currently projects from the live registered catalog, not snapshot files, and that future TP-153 snapshot policy changes should not silently make docs generation depend on stale snapshots unless that is reviewed.

## Suggested acceptance criteria for the revised Step 4 plan

- Changelog entry under `[Unreleased]` for the public reference/docs improvement.
- Workflow docs/help updated for both generated files, or documented rationale for no change.
- Generated-file stale guard includes `web/data/tool_schemas.json`, or an explicit caveat is logged.
- Concrete catalog/schema key comparison completed and recorded.
- Full `make test` / `make lint` / `make build` remains deferred to Step 5.
