docs(docs): correct tutorial 02 + 03 gaps surfaced by fresh-vm onboarding#2321
Merged
docs(docs): correct tutorial 02 + 03 gaps surfaced by fresh-vm onboarding#2321
Conversation
…ding Three small fixes against the v4-0-0-snapshot start-here tutorial that the 2026-04-25 fresh-VM onboarding run flagged: * Tutorial 02 — replace the "0.3.5-SNAPSHOT generator can't run" caveat with the real generator flow. `wheels generate model` works on current 0.3.7+ (the snippet-template gap was closed in #1944). The generator output is slim, so we walk the user through augmenting it with the `enum` and the extra columns instead of "hand-write three files." * Tutorial 02 — `wheels new` does not scaffold `app/db/`, so the seed-file step now starts with `mkdir -p app/db`. (A separate CLI follow-up will make `wheels new` produce the directory.) * Tutorial 03 — fix `wheels destroy controller Posts` to the actual CLI argument order (`<name> [type]`). Replace the "scaffold needs templates that don't ship" preamble with the real failure mode the user now hits: scaffold-on-existing-model bails with "Model already exists". Hand-write fallback stays as the recovery. Refs the open CLI issues for the underlying ergonomics gaps: - destroy arg-order accept-both: future CLI follow-up - scaffold --skip-existing: future CLI follow-up Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Three corrections against the v4-0-0-snapshot start-here tutorial, all surfaced by the 2026-04-25 fresh-VM onboarding run:
1. Replace stale generator caveat in chapter 2 (Finding #13)
The chapter said `wheels generate model` doesn't work on 0.3.5-SNAPSHOT and walked the user through hand-writing three files. `wheels generate model` works on current 0.3.7+ — the snippet-template gap closed in #1944. Now the chapter shows the real flow: run the generator, then augment the slim output with the `status` enum and the extra columns.
2. `mkdir -p app/db` before creating seeds.cfm (Finding #14)
`wheels new` does not scaffold an `app/db/` directory; only the root-level `db/` for the SQLite files. Trying to write `app/db/seeds.cfm` without first creating the directory fails. Added the explicit `mkdir -p`. (A CLI follow-up should make `wheels new` create the directory and a `seeds.cfm` skeleton with the `` wrapper baked in.)
3. Fix `wheels destroy` argument order in chapter 3 (Finding #9)
The chapter said `wheels destroy controller Posts`. The CLI's actual argument order is ` [type]`, so `wheels destroy Posts controller`. Also replaced the dated "scaffold needs templates" preamble with the real failure new users now hit: `Scaffold failed: Model already exists`, since chapter 2 wrote the model. Hand-write fallback stays as the recovery path.
Source
Findings #9, #13, #14 from the fresh-VM onboarding journal. The harness at `tools/test-onboarding.sh` validates the chapter-2 `wheels new` -> migrate cliff but doesn't re-execute these specific tutorial steps; copy fidelity is verified by the next fresh-VM run.
Test plan
🤖 Generated with Claude Code