docs: align destroy references with #2493 type-scoped contract

[bpamiri]

Summary

Doc follow-up to PR #2513, which narrowed wheels destroy <Name> controller to delete only the controller .cfc + spec (no longer cascading views). Three doc surfaces still described the old behaviour or carried stale filenames — this PR aligns them.

Changes

start-here/tutorial/03-crud-scaffold.mdx

Chapter 3 says "Drop the hand-written controller and views. The model, migration, seed file, and the resources("posts") route stay." Under the old contract that was a single wheels destroy Posts controller --force. Under the new contract that command leaves the views directory alone.

The tutorial's stated intent (drop controller AND views, keep everything else) needs two commands now:

wheels destroy Posts controller --force
wheels destroy Posts view --force

The resource form (wheels destroy Posts) would also work but it'd drop the model, migration, and route — which the chapter explicitly wants to keep. Added an explanatory sentence so readers understand why the split exists.

command-line-tools/wheels-commands/scaffold-cleanup.mdx

Two fixes:

1. The "destroy is destructive" caution said destroy removes whole view directories by default — true for the resource form and destroy view, NOT for destroy controller. Rewrote that bullet to call out the boundary explicitly.
2. The "Example" output mentioned tests/specs/controllers/PostsSpec.cfc — stale name from before fix(cli): wheels destroy looks for ControllerSpec, not Spec #2502 fixed the destroy filename. Corrected to PostsControllerSpec.cfc.

The Types table on line 48 was already accurate (described controller as removing only the CFC + spec). The behaviour now matches.

command-line-tools/mcp-integration.mdx

The wheels_destroy tool description was a generic one-liner. Made it crisper so AI agents understand the cascade-vs-scoped split before they call the tool.

Out of scope

• command-line-tools/index.mdx line 91 ("undo a generator cleanly") — generic enough to leave alone.
• command-line-tools/wheels-commands/code-quality.mdx line 176 — generic related-link description.
• digging-deeper/caching.mdx line 229 — refers to the HTTP destroy REST verb, not the CLI command. Untouched.
• v3 docs (v3-0-0/...) — frozen historical version, do not touch.

Test plan

• Render tutorial/03-crud-scaffold.mdx — the two-command block appears with the explanatory paragraph.
• Render scaffold-cleanup.mdx — caution bullet calls out the controller-vs-resource boundary; example output references PostsControllerSpec.cfc.
• Render mcp-integration.mdx — wheels_destroy row reads correctly in the table.
• Walk through the tutorial chapter 3 as written — wheels generate scaffold Post succeeds after the two destroy commands run.

---

Generated by Claude Code

[claude]

🟡 The new wheels_destroy description groups model with controller and view as 'scoped to that artefact only', but destroyModel in cli/lucli/services/Destroy.cfc also writes a drop-table migration (line 97). This contradicts the same PR's scaffold-cleanup.mdx, which states 'destroy model and destroy resource generate a drop-table migration'. Consider rewording so AI agents see that type=model has the same migration side effect as the resource form.

Extended reasoning...

Bug: MCP wheels_destroy description omits drop-table migration for type=model

The new tool description added in this PR reads:

The default resource type cascades (model + controller + views + tests + route + drop-table migration); model, controller, and view are scoped to that artefact only.

This groups model with controller and view as if all three are pure-deletion operations. That's accurate for controller and view, but not for model.

Why the wording is wrong

cli/lucli/services/Destroy.cfc lines 82–100 (destroyModel) deletes the model CFC and its spec and calls generateRemoveTableMigration(lCase(variables.helpers.pluralize(clean))) on line 97. destroyController and destroyView do not generate any migration. So model shares the migration side effect with the resource form, not the artefact-only behaviour of controller/view.

The PR is internally inconsistent on this point. The companion scaffold-cleanup.mdx (also touched here) says explicitly:

destroy model and destroy resource generate a drop-table migration but do not execute it.

…and its Types table lists the model row as removing 'Model CFC, model spec, plus a new drop-table migration file'. The MCP description directly contradicts both of those.

Why this matters for the stated audience

The PR description says the rewording is 'so AI agents understand the cascade-vs-scoped split before they call the tool'. An agent reading only the MCP tools/list output (the typical case — agents do not browse scaffold-cleanup.mdx) would conclude that wheels_destroy(name="Foo", type="model") is a pure-deletion operation. In reality, that call leaves a <timestamp>_remove_foos_table.cfc file in app/migrator/migrations/ that drops the table on the next wheels migrate latest — a notable filesystem and future-schema side effect.

Step-by-step proof

1. Agent calls wheels_destroy(name="Posts", type="model").
2. Module.cfc dispatches to Destroy.cfc::destroyModel.
3. destroyModel deletes app/models/Posts.cfc and tests/specs/models/PostsSpec.cfc (lines 87–94).
4. Then it calls generateRemoveTableMigration("posts") at line 97, writing a new <ts>_remove_posts_table.cfc into app/migrator/migrations/.
5. The MCP description told the agent this type was 'scoped to that artefact only' — so the agent does not know the migration file exists, and a later wheels migrate latest will drop the table.

Suggested fix

Move 'drop-table migration' out of the resource clause, e.g.:

The default resource type cascades (model + controller + views + tests + route); model removes the model CFC and spec; controller and view are scoped to that artefact only. Both resource and model also write a drop-table migration that you must run manually.

Severity is nit — the table is otherwise accurate, the synopsis and Types table elsewhere are correct, and an agent that follows the link to scaffold-cleanup.mdx would learn the truth. But since the PR's stated intent is to make this exact description AI-agent-friendly, the omission is on-topic for review.