Skip to content

docs: make the onboarding path work when followed literally - #148

Merged
Davidslv merged 1 commit into
mainfrom
docs/fix-onboarding
Sep 28, 2026
Merged

Davidslv merged 1 commit into
mainfrom
docs/fix-onboarding

Conversation

@Davidslv

Copy link
Copy Markdown
Owner

I followed the onboarding docs literally in fresh apps built from the published 0.2.0 gem. They didn't work as written.

What broke

Doc Problem
Tutorial "SQLite is fine". The migrations use jsonb and fail on SQLite (verified).
Tutorial Sends readers to /auth/sign_up, which returns 404. The real path is /auth/registration/new.
Tutorial, Getting Started Tell readers to add mount lines and include Auth::Authentication, which the generators already write.
All three No bundle install between generators. Billing adds stripe, so the next generator fails to boot the app (verified: teams failed).
All three No encryption keys step. Sign-up returns 500 with Missing Active Record encryption credential (verified).
All three No tailwindcss:build after design --shell. Pages return 500 with The asset 'tailwind.css' was not found (verified).
Getting Started Generated auth before core.
Engine Catalogue The wiring example mounted Core at / (the generator uses /core), left out admin, and didn't say which includes are manual.

Verified after the fix

  • Tutorial path: rails new --database=postgresql, bundle add seams, install, core, auth, design --shell, Tailwind build, encryption keys, migrate. Sign-up returns 302 and lands on the dashboard with 200.
  • README quick start, all 7 engines with bundle install after each: migrate passes, bin/seams list shows 7 engines, sign-up works.
  • The auth controllers skip_before_action :authenticate_identity! on sign-in, sign-up and password reset, so the catalogue's app-wide before_action advice is safe.
  • The docs-site build passes. The README links now point at the live URL (davidslv.uk/seams; github.io redirects there).

Re-ran the tutorials and README quick start in fresh apps from the
published 0.2.0 gem. Fixes found:

- TUTORIAL said SQLite is fine; migrations use jsonb and fail
- TUTORIAL pointed at /auth/sign_up (real: /auth/registration/new)
- both tutorials had readers add mounts/includes the generators write
- missing steps everywhere: bundle install after each generator (teams
  fails to boot after billing adds stripe), db:encryption:init +
  credentials (sign-up 500s without), tailwindcss:build after design
- GETTING_STARTED generated auth before core
- Engine Catalogue wiring example mounted Core at / and omitted admin;
  now shows the generated routes and which includes are manual
- README docs links use davidslv.uk/seams (github.io redirects there)
@Davidslv
Davidslv merged commit e9889c4 into main Sep 28, 2026
11 of 12 checks passed
@Davidslv
Davidslv deleted the docs/fix-onboarding branch September 28, 2026 09:50
@Davidslv Davidslv mentioned this pull request Sep 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant