seams 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48050ae5ddd2075cf436343c837ad75370660410f96c3a3d1c12e4d58612ec65
-  data.tar.gz: debc50e9f6570fa7361e8a03d23bab7c1c84e30214cb4b49ff2e66b957e493d9
+  metadata.gz: '080facbda9aa03ebeec4885f3745dd0c100d698465dcfcd7bbf35c62dd634eff'
+  data.tar.gz: d9a6b438e0ff12c37ba4006e680a7d01f30358c1bb351cdf2e47fee9110f13be
 SHA512:
-  metadata.gz: bd7f31ec043899f985949285a8f3b47cfd9fda83885d06c9f89fc5052c7374113427c054c7868501c34d484ae62c4f58377d915300777df0ff150ea7d34068b4
-  data.tar.gz: ae8884205c3f95c991722517358897b1bb5ee559be3bca06d513f477e76e58fbb8bfeb4a20602be40517d51a8178e7e1d0cd2e744e069eefd1cae5b6950afa6e
+  metadata.gz: 1e607f46a0b749397ad5b7f7a8a1927dcd267ca14dbf77107c938269bd17c17d426ac38b98f88ba734c7d7a27adceb150973fa331e2d1b302515102b96afdccd
+  data.tar.gz: b708e636f64a8502215b811102640df371ed57846ecd54a44dbd8ea0391f84848f4f42350b3111ddab113eb96a19a75d529f19c45b8a0726b7e6e0cd4c62b9cd

data/CHANGELOG.md

@@ -7,6 +7,206 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] — 2026-09-27
+
+> [!WARNING]
+> Breaking changes for hosts (pre-1.0, so this is a minor bump):
+>
+> - Generated billing code targets `stripe ~> 19.0` (was `~> 13.0`) and
+>   raises `Billing::GatewayError` where Stripe errors used to escape.
+>   Hosts that rescued `Stripe::*` from the generated services must rescue
+>   `Billing::GatewayError`. Match your Stripe webhook endpoint's API
+>   version to `2026-08-26.dahlia`.
+> - Generated code is not rewritten by a gem upgrade. See "Fixed" for the
+>   manual steps (engine `spec/dummy/config/cable.yml`, admin engine).
+
+### Added
+
+- Integration suite: a default `seams:install` host must resolve its
+  bundle on a multi-platform lockfile (x86_64-linux, aarch64-linux,
+  arm64-darwin, x86_64-darwin). Guards the #42 class, where a gem shipping
+  only some native platforms broke `bundle` on Rails 8 lockfiles. Completes
+  #48.
+- Community and AI-era repository standards: `SUPPORT.md`, `GOVERNANCE.md`,
+  `MAINTAINERS.md`, `CITATION.cff`, `.editorconfig`, `.github/FUNDING.yml`,
+  an `llms.txt` machine-readable index, and `AGENTS.md` instructions for AI
+  coding agents. `doc/explanation/ARCHITECTURE.md` gains a "Where this design would
+  strain" section. Blank issues are now routed through the issue chooser.
+
+- Install generator: ships an opinionated quality toolchain — a host is hardened
+  from the first CLI run. `seams:install` installs **strong_migrations**
+  (+ initializer, audits all migrations via `start_after = 0`) and **lefthook**
+  (`lefthook.yml`: pre-commit rubocop, pre-push specs) by default, and wires a
+  from-scratch `db:migrate` safety check into the generated CI. The rubocop/
+  brakeman/bundle-audit gems the generated CI shells out to are now injected
+  into the host Gemfile too. **herb** (HTML+ERB lint + `.herb.yml`) is available
+  but **off by default** — opt in with `--herb` — because its platform-specific
+  native gem breaks cold installs on multi-platform lockfiles (see commit
+  6c16c52). strong_migrations and lefthook are opt-out via
+  `--no-strong-migrations` / `--no-lefthook`. Also closes two gaps where Seams
+  generated migrations that nothing validated — the host CI now vets them.
+- Permissions engine (`bin/seams permissions`): generates a host-editable
+  role → ability grant map at `config/initializers/seams_permissions.rb`, backed
+  by `Seams::PermissionRegistry` / `Seams::Permissions` and the
+  `authorize_permission!` controller helper. See [doc/reference/PERMISSIONS.md].
+- Admin engine (`bin/seams admin`): opt-in Administrate dashboards with a Pundit
+  `Platform`/`Tenant` policy split and an admin audit trail writing
+  `Core::AuditLog` rows. See [doc/explanation/ARCHITECTURE_WAVE_11.md].
+- Design engine (`bin/seams design`, `--shell`): a themeable design system —
+  33 `ui_*` components, Tailwind v4 `@theme` tokens + component CSS,
+  `Design::FormBuilder`, a `/design/guide` gallery, and a `design:component`
+  generator; `--shell` also generates an application layout and a starter
+  signed-in dashboard. See [doc/design-system/DESIGN_SYSTEM.md].
+
+### Changed
+
+- Generated host pins: rspec-rails is injected as `">= 7.1", "< 9"` (was
+  `"~> 7.1"`) in the host Gemfile and each engine Gemfile, so Rails 7.2+
+  hosts get rspec-rails 8.x. The generated CI uses `actions/checkout@v7`
+  and a `postgres:18` service; the Kamal Postgres accessory comment moves
+  to `postgres:18` and its volume to `/var/lib/postgresql` (18's layout).
+- Billing generator: the generated engine now targets stripe-ruby 19
+  (`gem "stripe", "~> 19.0"`, was `~> 13.0`), which pins Stripe API version
+  `2026-08-26.dahlia`. Existing hosts run `bundle update stripe` and should
+  move their webhook endpoint to the same API version (the handlers accept
+  both shapes meanwhile). Changes in the generated code:
+  - New `Billing::Stripe::Payload` reads Stripe objects and webhook hashes
+    alike. Handlers and `Invoices::SyncService` read the invoice's
+    subscription from `invoice.parent.subscription_details.subscription` and
+    the period end from `items.data[0].current_period_end` (both moved in
+    2025-03-31.basil). The old top-level `invoice.subscription` and
+    `subscription.current_period_end` are still read as fallbacks.
+  - `invoice.paid` now stores Stripe's `status_transitions.paid_at` as
+    `paid_at` instead of the time the webhook arrived.
+  - Fixed `#dig` calls on SDK responses (`Gateways::Stripe#normalise_subscription`,
+    `Invoices::SyncService#paid_at_for`). `Stripe::StripeObject` has no `#dig`,
+    so these raised `NoMethodError` on real API responses.
+  - `Billing::Stripe::Client` re-raises every `Stripe::StripeError` as
+    `Billing::GatewayError` (original on `#cause`). Every generated caller
+    already rescued `Billing::GatewayError`, but the gem-backed client never
+    raised it, so Stripe errors escaped `StripeService`, the checkout and
+    portal services, and `CreateLifetimeSessionService`. Hosts that rescued
+    `Stripe::*` errors from these services should rescue
+    `Billing::GatewayError` instead.
+  - The webhook endpoint answers `400` (not `500`) to a signed v2 thin event;
+    stripe-ruby 19's `Stripe::Webhook.construct_event` raises `ArgumentError`
+    for those.
+  - Stripe event fixtures under `spec/fixtures/stripe/` use the dahlia shapes
+    and carry `api_version`.
+- Dependencies: Ruby 4.0.7 (repo, CI, and the generated host's
+  `.ruby-version` / Dockerfile default), Rails 8.1.4, RuboCop 1.91 (+
+  rubocop-rails 2.38, rubocop-performance 1.27), SimpleCov 1.3, brakeman
+  8.0.6, sqlite3 2.9.6, yard 0.9.45, and the docs-site on Astro 7.3 / Starlight 0.42. Patches the
+  websocket-driver 0.8.0 advisories (CVE-2026-54463/54464/54465/61666)
+  and the docs-site devalue, nanoid, and postcss advisories. CI moves to
+  `actions/setup-node@v7`.
+- Documentation: `doc/` is now organised into Diátaxis folders —
+  `tutorials/`, `how-to/`, `reference/`, `design-system/`,
+  `explanation/`, plus `internal/` for maintainer-facing working
+  documents. Published URLs on the docs site are unchanged (the site
+  flattens the folders), and the site's in-page cross-links — which
+  previously shipped as raw `.md` hrefs and 404'd — now resolve to the
+  real page URLs.
+- Engine generator: ApplicationController now requires authentication by default. Opt out via `skip_before_action :authenticate_identity!` in controllers serving public flows. [BREAKING for hosts that explicitly relied on engines being unauthenticated by default.]
+- Notifications generator: preferences controller now uses an explicit
+  permit list from the channel/type registry rather than `permit!`.
+  Eliminates the brakeman mass-assignment warning shipped with generated
+  engines. Hosts that have already ejected
+  `app/controllers/notifications/preferences_controller.rb` will not
+  re-generate it (per the `template_unless_ejected` contract); to pick
+  up the new behaviour, replace
+  `params.require(:preferences).permit!` in the ejected copy with
+  `params.require(:preferences).permit(*Notifications::Preferences.allowed_keys)`
+  and require `notifications/preferences` from
+  `lib/notifications.rb`.
+- Teams generator: `TeamsController` now includes `Teams::Authorization` and applies `require_team_member!` as a `before_action` on `show`, and `require_team_admin!` on `edit`, `update`, and `destroy`. Previously those actions had no resource-level membership guard, letting any authenticated identity act on any team by ID. The `require_team_member!` and `require_team_admin!` predicates in the concern now redirect to `teams_path` with an alert rather than returning a bare 403, matching the convention used by the other team controllers.
+
+### Fixed
+
+- Admin engine UI: the sidebar and every New / show / edit / destroy link
+  were missing, because Administrate reads the host's routes and a mounted
+  engine's routes are not in them. `existing_action?` and a navigation
+  partial now read the engine's routes; `authorized_action?` uses the
+  policy of the resource being linked. An `_index_header` override builds
+  the New link from the controller. Creates now write an admin audit row
+  (Administrate's `create` never set `requested_resource`). The admin
+  README documents the authenticator and membership resolver that tenant
+  mode needs.
+- `bin/audit` (the pre-push gate) failed from a linked git worktree:
+  the hook's exported `GIT_DIR` made `bundle-audit --update` pull its
+  advisory database against this repo. It now clears git's hook
+  variables for that command.
+- gemspec: `required_ruby_version` is now `>= 3.3.0` (was `>= 4.0.0`), so
+  `bundle add seams` resolves on Ruby 3.3 and 3.4 hosts. CI runs the spec
+  suite on 3.3, 3.4, and 4.0. RuboCop targets 3.3 so 4.0-only syntax is
+  caught. Ruby 3.2 is end-of-life and SimpleCov 1.x requires 3.3.
+  Fixes #79.
+- `host_inject_gem` dropped every version requirement after the first, so
+  a range like `(">= 7.1", "< 9")` was written as `">= 7.1"` only.
+- Admin generator: the host no longer gets `mount Admin::Engine` and an
+  `Admin.configure` initializer stub from the base engine step. The engine
+  lives at `Seams::Admin::Engine`, so every host that ran `seams:admin`
+  raised `NameError` on boot. `seams:engine` gains `--skip-host-wiring`
+  for canonical generators that wire the host themselves. The admin engine
+  now runs in the rails-new integration suite.
+- Admin engine: every dashboard request failed. Fixed the chain found by
+  driving a generated host over HTTP:
+  - routes point at `/admin/...` controllers (isolate_namespace resolved
+    `admin/identities` to `Seams::Admin::Admin::IdentitiesController`) and
+    sit in `scope as: :admin` so Administrate's `admin_*` helpers exist;
+  - the base controller includes `Auth::Authentication`, so
+    `current_identity` resolves; signed-out visitors are redirected to
+    sign-in, non-staff get 403;
+  - policies resolve as `Admin::<Platform|Tenant>::<Resource>Policy` via
+    Pundit's `policy_class:` (the array lookup produced
+    `Module::Auth::IdentityPolicy`);
+  - dashboards declare `self.model`; association fields take a
+    `dashboard:` option (`Admin::Fields::BelongsTo` / `HasMany`);
+  - the `Admin::*` controllers get the engine's route helpers, the
+    `accounts`/`teams` membership route-key clash is dispatched by record
+    class, flash messages use the real model name, and `verify_authorized`
+    no longer names a non-action (ActionNotFound on Rails 7.1+);
+  - the admin dummy app registers the abilities its tenant policies
+    check, and the tenant role specs use a concrete policy.
+  The integration suite signs in as anonymous, non-staff, and staff and
+  asserts every dashboard's index and new page plus a create.
+- Generated `bin/docker-entrypoint` now runs `db:prepare` for the
+  Dockerfile's own `bundle exec rails server -b 0.0.0.0` command. It only
+  checked the first three arguments, where `server` never appears, so a
+  seams-built container started against an empty database. Verified by
+  building and running a generated host (all engines) against Postgres 18.
+- Engine dummy apps now ship `spec/dummy/config/cable.yml` (test adapter).
+  solid_cable 4.1 reads `config_for("cable")` at boot, so every generated
+  engine spec suite failed to load in a host that bundles solid_cable.
+  Engines generated before this release need the file added by hand:
+  `engines/*/spec/dummy/config/cable.yml` containing `test:` /
+  `  adapter: test`.
+- Nightly link check: lychee retries each link 5 times (10s apart) before
+  reporting it, and a failing run updates the open `broken-link` issue
+  instead of filing a new one. Closes #93 and #109, both transient
+  connection resets on contributor-covenant.org.
+- Teams generator: `InvitationsController#accept` now redirects unauthenticated requests to the sign-in path (stashing the token in the session under `pending_invitation_token`) instead of raising `ActiveRecord::RecordInvalid`. The host's sign-in flow is responsible for reading `return_to` and redirecting back after authentication.
+- Teams generator: `InvitationsController#accept` now verifies that the signed-in identity's email matches the invitation email (case-insensitively) before creating the membership. Previously any authenticated identity holding a valid token could accept the invitation under a different account.
+- Billing generator: `scoped_invoices` / `scoped_subscriptions` now return
+  `.none` when the current customer ref is nil. The previous behaviour was
+  an **information disclosure**: Rails translates
+  `.where(customer_ref: nil)` to `WHERE customer_ref IS NULL`, which
+  matches every invoice and subscription row whose `customer_ref` has not
+  yet been linked to a Stripe customer — typically including manual,
+  draft, or test records seeded by other staff. The fix returns an empty
+  relation when there is no customer to scope by.
+
+  Hosts that have already ejected
+  `app/controllers/billing/invoices_controller.rb` or
+  `subscriptions_controller.rb` will not re-generate them (per the
+  `template_unless_ejected` contract). To pick up the fix, prepend each
+  scope helper with:
+
+      return Billing::Invoice.none if current_billing_customer_ref.nil?
+
+  (likewise `Billing::Subscription.none` in the subscriptions helper)
+  before the existing `.where(customer_ref: …)` line.
+
 ## [0.1.0] — 2026-05-10
 
 First public release on rubygems.org. The cumulative changelog from
@@ -21,9 +221,9 @@ notifications, billing, teams) can mount an Administrate-backed admin
 surface at `/admin` covering all twelve canonical seams models with a
 single command. Dashboards, two-mode authorization, audit-log
 auto-write, and the four config knobs all ship out of the box. See
-[`doc/ARCHITECTURE_WAVE_11.md`](doc/ARCHITECTURE_WAVE_11.md) for the
+[`doc/explanation/ARCHITECTURE_WAVE_11.md`](doc/explanation/ARCHITECTURE_WAVE_11.md) for the
 new architecture material; the framework selection rationale lives in
-[`proposals/admin_engine_administrate.md`](proposals/admin_engine_administrate.md).
+`proposals/admin_engine_administrate.md`.
 
 #### Added
 
@@ -97,8 +297,8 @@ follow-up generators target those points to add features without
 re-templating the whole engine; and `bin/seams resolve --eject`
 marks any single host file as host-owned so subsequent
 `bin/seams <engine>` runs leave it alone. See
-[`doc/ARCHITECTURE_WAVE_10.md`](doc/ARCHITECTURE_WAVE_10.md) for the
-addendum and [`doc/WRITING_FOLLOW_UP_GENERATORS.md`](doc/WRITING_FOLLOW_UP_GENERATORS.md)
+[`doc/explanation/ARCHITECTURE_WAVE_10.md`](doc/explanation/ARCHITECTURE_WAVE_10.md) for the
+addendum and [`doc/how-to/WRITING_FOLLOW_UP_GENERATORS.md`](doc/how-to/WRITING_FOLLOW_UP_GENERATORS.md)
 for the author's guide.
 
 #### Added
@@ -116,8 +316,8 @@ for the author's guide.
   core Configuration class). Marker shape:
   `# seams:insertion-point <engine>.<area>.<scope>` — ASCII only,
   greppable, parses through every Ruby linter. Format spec in
-  [`doc/INSERTION_POINTS.md`](doc/INSERTION_POINTS.md); canonical list
-  in [`doc/INSERTION_POINTS_CATALOGUE.md`](doc/INSERTION_POINTS_CATALOGUE.md).
+  [`doc/reference/INSERTION_POINTS.md`](doc/reference/INSERTION_POINTS.md); canonical list
+  in [`doc/reference/INSERTION_POINTS_CATALOGUE.md`](doc/reference/INSERTION_POINTS_CATALOGUE.md).
 - **`bin/seams resolve` CLI.** Three modes:
   - `--eject <engine>/<file>` — prepends a
     `# seams:ejected from <engine>.<path>` header to the host file;
@@ -144,12 +344,12 @@ for the author's guide.
   `auth.configuration.oauth_providers` marker, and writes a matching
   spec. Idempotent on rerun.
 - **Documentation.**
-  [`doc/INSERTION_POINTS.md`](doc/INSERTION_POINTS.md) (format spec),
-  [`doc/INSERTION_POINTS_CATALOGUE.md`](doc/INSERTION_POINTS_CATALOGUE.md)
+  [`doc/reference/INSERTION_POINTS.md`](doc/reference/INSERTION_POINTS.md) (format spec),
+  [`doc/reference/INSERTION_POINTS_CATALOGUE.md`](doc/reference/INSERTION_POINTS_CATALOGUE.md)
   (canonical 33-marker list),
-  [`doc/WRITING_FOLLOW_UP_GENERATORS.md`](doc/WRITING_FOLLOW_UP_GENERATORS.md)
+  [`doc/how-to/WRITING_FOLLOW_UP_GENERATORS.md`](doc/how-to/WRITING_FOLLOW_UP_GENERATORS.md)
   (author's guide), and
-  [`doc/ARCHITECTURE_WAVE_10.md`](doc/ARCHITECTURE_WAVE_10.md)
+  [`doc/explanation/ARCHITECTURE_WAVE_10.md`](doc/explanation/ARCHITECTURE_WAVE_10.md)
   (architecture addendum with splice + eject sequence diagrams).
 - **Host-facing surfaces updated.**
   `bin/seams help` and `bin/seams resolve --help` document the new
@@ -161,7 +361,7 @@ for the author's guide.
 
 Replaces the conflated `Auth::User` (which owned credentials AND
 tenant-membership concepts) with three peer engines, each with one
-clear responsibility. See `doc/UPGRADING_FROM_WAVE_8.md` for the
+clear responsibility. See `doc/how-to/UPGRADING_FROM_WAVE_8.md` for the
 migration story.
 
 #### Added
@@ -245,7 +445,7 @@ migration story.
   state holders are intentionally readable from any engine. The
   cop now treats `Current` as a framework-level constant and
   exempts it from the boundary rule. Documented in
-  `doc/CURRENT_ATTRIBUTES.md` and inline in the cop's docstring.
+  `doc/reference/CURRENT_ATTRIBUTES.md` and inline in the cop's docstring.
 - `Teams::AccountScoped` now references `Teams::Current.team`
   (previously a bare `Current.team` that resolved to nothing
   inside `module Teams` — silently making the default_scope a

data/README.md

@@ -1,104 +1,257 @@
 # Seams
 
-> A CLI framework that generates modular Rails engines.
+[![Gem Version](https://img.shields.io/gem/v/seams.svg)](https://rubygems.org/gems/seams)
+[![CI](https://github.com/Davidslv/seams/actions/workflows/ci.yml/badge.svg)](https://github.com/Davidslv/seams/actions/workflows/ci.yml)
+[![Docs site](https://img.shields.io/badge/docs-davidslv.github.io%2Fseams-blue.svg)](https://davidslv.github.io/seams/)
+[![API docs](https://img.shields.io/badge/api-rubydoc.info-blue.svg)](https://rubydoc.info/gems/seams)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
-Seams gives you the architectural benefits of microservices — clear
-boundaries, independent testing, team autonomy — without the
-operational cost. You ship a single Rails app. You think in
-independent engines.
+Seams generates modular Rails engines inside your Rails app.
 
-> Seams materialises the patterns David Silva teaches in **[Modular
-> Rails: Architecture for the Long Game](https://davidslv.uk/modular-rails/)**.
-> The book is the artefact; this gem is the executable shorthand. See
-> [seams-example](https://github.com/Davidslv/seams-example) for a
-> reference host that wires every canonical engine end-to-end.
+You ship one Rails app. Inside it, each feature (auth, accounts, billing, teams, and so on) lives in its own engine under `engines/`. Each engine has its own models, tests, and boundaries. Engines talk to each other through events, not by reaching into each other's code. Custom RuboCop cops enforce that.
 
-## Quick start
+Every generated file is plain Rails code in your repo. You can read it, change it, or delete it. Nothing is hidden behind the gem.
 
-```ruby
-# Gemfile
-gem "seams"
-```
+> [!NOTE]
+> Seams is the executable companion to the book **[Modular Rails: Architecture for the Long Game](https://davidslv.uk/modular-rails/)**. The full guides live on the **[documentation site](https://davidslv.github.io/seams/)**. [seams-example](https://github.com/Davidslv/seams-example) is a reference host with every engine wired up.
+
+## Requirements
+
+| | Supported | Tested in CI |
+| --- | --- | --- |
+| Ruby | 3.3 or newer | 3.3, 3.4, 4.0.7 |
+| Rails | 7.1 or newer (below 9) | 8.1.4 |
+| Database | PostgreSQL | PostgreSQL 18 |
+
+> [!IMPORTANT]
+> **PostgreSQL is required.** The generated engines use `jsonb` columns, and each engine's test suite runs against Postgres. SQLite and MySQL are not supported.
+
+## Installation
+
+> [!WARNING]
+> **Install from GitHub for now.** The only release on RubyGems is `0.1.0` (May 2026). It requires Ruby 4.0 or newer and predates many fixes, including the admin engine working at all and Ruby 3.3 support. Until a new version is released, point your Gemfile at the repository:
+>
+> ```ruby
+> # Gemfile
+> gem "seams", github: "Davidslv/seams"
+> ```
+>
+> Once a newer version is on RubyGems, use `gem "seams"` instead.
+
+Then install the framework:
 
 ```bash
 bundle install
 bin/rails generate seams:install
-bin/seams auth
-bin/seams accounts
-bin/seams notifications
-bin/seams billing
-bin/seams teams
-bin/seams list
 ```
 
-That's auth, tenant boundary, transactional email/SMS, Stripe
-subscriptions, and multi-tenant teams generated as five real Rails
-engines under `engines/`. Every file is yours to edit. Nothing is
-hidden behind the gem.
+`seams:install` adds the framework files, a CI workflow, and a `bin/seams` command. Every step after this uses `bin/seams`.
+
+## Quick start
+
+Generate the engines you need. The order matters, because later engines build on earlier ones:
+
+```bash
+bin/seams core            # shared building blocks (always first)
+bin/seams auth            # sign-in, sessions, OAuth, API tokens
+bin/seams accounts        # the tenant (Account) and its members
+bin/seams notifications   # in-app, email, and SMS notifications
+bin/seams billing         # Stripe subscriptions
+bin/seams teams           # optional teams inside an account
+bin/seams design --shell  # UI components and an app layout
+
+bundle install
+bin/rails db:migrate
+bin/seams list            # show engines, their events, and subscribers
+```
+
+> [!TIP]
+> New to Seams? Follow **[Getting Started](doc/tutorials/GETTING_STARTED.md)**. It goes step by step from `bundle install` to a running app.
 
 ## What you get
 
-- `bin/seams install`        — adds the framework + CI workflow + bin/seams wrapper
-- `bin/seams engine <name>`  — generic engine scaffold
-- `bin/seams core`           — canonical Core engine (Current attributes, AuditLog, TenantScoped, EmailFormatValidator)
-- `bin/seams auth`           — canonical Auth engine (Identity, Session, OAuth, API tokens, GDPR-encrypted PII)
-- `bin/seams accounts`       — canonical Accounts engine (Account tenant, Membership, AccountScoped, system actor)
-- `bin/seams notifications`  — canonical Notifications engine (STI strategies, ActionCable bell, TypeRegistry, --channels flag)
-- `bin/seams billing`        — canonical Billing engine (official Stripe gem, 13-handler webhook router, Lifetime Deals)
-- `bin/seams teams`          — canonical Teams engine (Team, Membership, Invitation, AccountScoped, --with flag)
-- `bin/seams remove <name>`  — clean removal + sibling cleanup + drop-table migration
-- `bin/seams list`           — engines, the events they emit, and what they subscribe to
-- `bin/seams resolve`        — eject host files / list insertion-point markers / list ejected files
-- `bin/rails generate seams:auth:add_oauth_provider <name>` — first follow-up generator (adds an OAuth provider adapter to an installed Auth engine)
-- Four custom RuboCop cops that enforce cross-engine boundaries
-- A GitHub Actions CI workflow that runs every engine's specs in parallel
+### The engines
+
+| Command | What it generates |
+| --- | --- |
+| `bin/seams core` | Shared basics: per-request `Current` attributes, an audit log, tenant scoping, an email validator. |
+| `bin/seams auth` | `Identity` (the person signing in), sessions, OAuth providers, API tokens. Personal data is encrypted at rest. |
+| `bin/seams accounts` | `Account` (the tenant), memberships with roles, account scoping. |
+| `bin/seams notifications` | Notifications over in-app, email, and SMS. Choose channels with `--channels in_app,email,sms` (default: all). |
+| `bin/seams billing` | Stripe subscriptions using the official `stripe` gem (19.x), a webhook router with 13 handlers, and lifetime deals. |
+| `bin/seams teams` | Teams, team memberships, and invitations. Choose features with `--with invitations,roles` (default: all). |
+| `bin/seams admin` | An admin area built on Administrate and Pundit. Optional. See [Admin engine](#admin-engine) below. |
+| `bin/seams design` | A design system: 33 `ui_*` components, Tailwind v4 theme tokens, a form builder, and a `/design/guide` gallery. `--shell` also adds an app layout and a starter dashboard. |
+| `bin/seams permissions` | An editable map of which roles can do what, in `config/initializers/seams_permissions.rb`. See [Permissions](doc/reference/PERMISSIONS.md). |
+
+### Framework and tools
+
+| Command | What it does |
+| --- | --- |
+| `bin/rails generate seams:install` | Installs the framework, the CI workflow, and `bin/seams`. |
+| `bin/seams engine <name>` | Generates an empty engine for your own feature. |
+| `bin/seams remove <name>` | Removes an engine, cleans up references to it, and adds a migration that drops its tables. |
+| `bin/seams list` | Lists engines, the events they publish, and who subscribes to them. |
+| `bin/seams test <engine>` | Runs one engine's tests. |
+| `bin/seams quality <engine>` | Runs RuboCop on one engine. |
+| `bin/seams resolve --eject <engine>/<file>` | Marks a generated file as yours, so future runs of the generator leave it alone. Also `--list-markers <engine>` and `--list-ejected`. |
+| `bin/rails generate seams:auth:add_oauth_provider <name>` | Adds an OAuth provider to the auth engine. |
+
+You also get:
+
+- **Four custom RuboCop cops.** Two fail the build when one engine reaches into another's code or models. The other two check background job queue names and migration comments.
+- **A GitHub Actions workflow** that runs each engine's tests in parallel.
+- **A quality toolchain** set up by `seams:install`:
+  - strong_migrations and lefthook git hooks are on by default. Turn them off with `--no-strong-migrations` or `--no-lefthook`.
+  - herb (ERB lint) is off by default. Turn it on with `--herb`.
+- **A Dockerfile and a Kamal `deploy.yml`**, written only if your app doesn't already have them. Rails 8 apps ship their own Dockerfile, which Seams leaves in place.
+
+## Admin engine
+
+`bin/seams admin` adds an admin area at `/admin`. It needs the `auth` engine. It adds the `administrate` and `pundit` gems to your Gemfile.
+
+> [!IMPORTANT]
+> **Only staff can open the admin area by default.** Set `staff: true` on an `Auth::Identity` to let that person in:
+>
+> ```ruby
+> Auth::Identity.find_by(email: "you@example.com").update!(staff: true)
+> ```
+>
+> Signed-out visitors are sent to the sign-in page. Signed-in identities that aren't staff get a 403.
+
+<details>
+<summary><strong>Tenant mode: let each customer's admins manage their own account</strong></summary>
+
+By default the admin area runs in **platform** mode: staff see every account. In **tenant** mode, an account's admins see only their own account's data.
+
+Tenant mode needs three settings. Without the last two, tenant admins get a 403.
+
+```ruby
+# config/initializers/seams_admin.rb
+Seams::Admin.configure do |c|
+  c.tenancy_scope = :tenant
+
+  # Let any signed-in identity past the gate. The tenant policies then
+  # decide what each role may do.
+  c.authenticator = ->(ctrl) { ctrl.current_identity.present? }
+
+  # Tell the admin area which membership the request belongs to.
+  # This example takes the identity's first active membership. Use
+  # however your app picks the current account (subdomain, session, a switcher).
+  c.current_membership_resolver = lambda do |ctrl|
+    identity = ctrl.current_identity
+    identity && Accounts::Membership.find_by(identity_id: identity.id, active: true)
+  end
+end
+```
+
+With these set:
+- An `admin` or `owner` of an account sees only that account's rows.
+- Requests for another account's records return 404.
+- A `member` gets a 403.
+
+The generated `engines/admin/README.md` has the full reference.
+
+</details>
+
+## Upgrading an existing Seams app
+
+Seams writes code into your app. So updating the gem does not change engines you already generated. Read the [CHANGELOG](CHANGELOG.md) before you update, and apply the changes that affect you.
+
+> [!NOTE]
+> If you generated engines before the September 2026 changes, check these:
+> - **solid_cable 4.1 or newer:** each engine's test app needs `engines/*/spec/dummy/config/cable.yml`, containing `test:` with `adapter: test`. Without it, the engine's tests fail to load.
+> - **Billing:** the generated code now targets `stripe ~> 19.0`. The generated services now raise `Billing::GatewayError` instead of `Stripe::*` errors. Set your Stripe webhook endpoint to the same API version as the gem.
+> - **Admin:** regenerate the admin engine, or copy the fixes listed in the CHANGELOG. Earlier versions could not boot or serve any admin page.
+>
+> If you adopted Seams before Wave 9, start with the [Wave 8 upgrade guide](doc/how-to/UPGRADING_FROM_WAVE_8.md).
 
 ## Documentation
 
-- [doc/GETTING_STARTED.md](doc/GETTING_STARTED.md)
-- [doc/ARCHITECTURE.md](doc/ARCHITECTURE.md) — short overview
-- [doc/ARCHITECTURE_WAVE_9.md](doc/ARCHITECTURE_WAVE_9.md) — full system walk-through (post-Wave-9)
-- [doc/ARCHITECTURE_WAVE_10.md](doc/ARCHITECTURE_WAVE_10.md) — Wave 10 addendum: insertion points, follow-up generators, eject CLI
-- [doc/ENGINE_CATALOGUE.md](doc/ENGINE_CATALOGUE.md)
-- [doc/CURRENT_ATTRIBUTES.md](doc/CURRENT_ATTRIBUTES.md) — per-request namespaces (Auth::Current, Accounts::Current, Teams::Current, Core::Current)
-- [doc/INSERTION_POINTS.md](doc/INSERTION_POINTS.md) — marker format spec
-- [doc/INSERTION_POINTS_CATALOGUE.md](doc/INSERTION_POINTS_CATALOGUE.md) — the canonical 33 markers
-- [doc/WRITING_FOLLOW_UP_GENERATORS.md](doc/WRITING_FOLLOW_UP_GENERATORS.md) — write your own follow-up generator
-- [doc/ADDING_AN_ENGINE.md](doc/ADDING_AN_ENGINE.md)
-- [doc/REMOVING_AN_ENGINE.md](doc/REMOVING_AN_ENGINE.md)
-- [doc/WRITING_AN_ADAPTER.md](doc/WRITING_AN_ADAPTER.md)
-- [doc/TESTING.md](doc/TESTING.md)
-- [doc/UPGRADING_FROM_WAVE_8.md](doc/UPGRADING_FROM_WAVE_8.md) — if you adopted seams pre-Wave-9
-
-## Why Seams instead of...
-
-| ... | Seams gives you |
+The **[documentation site](https://davidslv.github.io/seams/)** has every guide below, with search. The API reference is on **[rubydoc.info](https://rubydoc.info/gems/seams)**.
+
+<details>
+<summary><strong>Start here</strong></summary>
+
+- [Getting Started](doc/tutorials/GETTING_STARTED.md): install, first engine, running app
+- [Engine catalogue](doc/reference/ENGINE_CATALOGUE.md): every engine in detail
+- [Architecture overview](doc/explanation/ARCHITECTURE.md): why Seams is built this way
+
+</details>
+
+<details>
+<summary><strong>Building and extending</strong></summary>
+
+- [Adding an engine](doc/how-to/ADDING_AN_ENGINE.md)
+- [Removing an engine](doc/how-to/REMOVING_AN_ENGINE.md)
+- [Writing an adapter](doc/how-to/WRITING_AN_ADAPTER.md): swap in Mailgun, Twilio, Paddle, and others
+- [Writing follow-up generators](doc/how-to/WRITING_FOLLOW_UP_GENERATORS.md)
+- [Insertion points](doc/reference/INSERTION_POINTS.md) and the [catalogue of markers](doc/reference/INSERTION_POINTS_CATALOGUE.md)
+- [Deploying](doc/how-to/DEPLOYING.md)
+
+</details>
+
+<details>
+<summary><strong>Reference</strong></summary>
+
+- [Current attributes](doc/reference/CURRENT_ATTRIBUTES.md): `Auth::Current`, `Accounts::Current`, `Teams::Current`, `Core::Current`
+- [Permissions](doc/reference/PERMISSIONS.md): ability codes, roles, the grant map
+- [Observability](doc/reference/OBSERVABILITY.md): logging, tracing, metrics
+- [Testing](doc/reference/TESTING.md)
+
+</details>
+
+<details>
+<summary><strong>Design system</strong></summary>
+
+- [Design system overview](doc/design-system/DESIGN_SYSTEM.md) (start here)
+- [Foundations](doc/design-system/DESIGN_SYSTEM_FOUNDATIONS.md): tokens and scales
+- [Components](doc/design-system/DESIGN_SYSTEM_COMPONENTS.md): the 33 `ui_*` components
+- [Forms](doc/design-system/DESIGN_SYSTEM_FORMS.md): `Design::FormBuilder`
+- [Theming](doc/design-system/DESIGN_SYSTEM_THEMING.md)
+- [Accessibility](doc/design-system/DESIGN_SYSTEM_ACCESSIBILITY.md)
+
+</details>
+
+<details>
+<summary><strong>Architecture history</strong></summary>
+
+- [Wave 9](doc/explanation/ARCHITECTURE_WAVE_9.md): the full system walk-through, including the identity / account / team split
+- [Wave 10](doc/explanation/ARCHITECTURE_WAVE_10.md): insertion points, follow-up generators, the eject command
+- [Wave 11](doc/explanation/ARCHITECTURE_WAVE_11.md): the admin engine
+- [Personal data and GDPR](doc/explanation/WAVE_11_PII_GDPR.md)
+- [Architecture Decision Records](doc/adr/)
+
+</details>
+
+## How Seams compares
+
+| Instead of | Seams gives you |
 | --- | --- |
-| Bullet Train | The substrate, not a starter kit. Code is in your repo, not behind a gem. |
-| Jumpstart Pro | Same. Plus the boundary cops. |
-| `rails plugin new --mountable` | Engines come pre-wired with events, registry, observability, boundary enforcement, CI. |
-| Hand-rolled microservices | One process. No HTTP between services. Synchronous events with explicit subscribers. |
-
-## Status
-
-Waves 1–9 complete: foundation, auth (with OAuth, API tokens,
-GDPR-encrypted PII), notifications (with TypeRegistry,
-ActionCable bell, multipart mailers), billing (official Stripe
-gem, 13-handler webhook router, Lifetime Deals), teams (with
-team scoping, role-based authz). Wave 9 added the `accounts`
-engine and reworked the identity/account/team boundary —
-`Auth::Identity` (the human), `Accounts::Account` (the tenant),
-`Teams::Team` (the optional grouping) are now three peer engines
-with one clear responsibility each. See
-[CHANGELOG.md](CHANGELOG.md#wave-9--identity--account--team-rework-breaking)
-and [doc/UPGRADING_FROM_WAVE_8.md](doc/UPGRADING_FROM_WAVE_8.md).
-
-See [issue #5](https://github.com/Davidslv/seams/issues/5) for the live
-work tracker.
-
-Suite: RuboCop clean, brakeman + bundle-audit clean. Run
-`bin/audit` before any push.
+| Bullet Train or Jumpstart Pro | The code lives in your repo, not behind a gem. Seams also enforces engine boundaries with RuboCop cops. |
+| `rails plugin new --mountable` | Engines come wired with events, registries, observability, boundary checks, and CI. |
+| Microservices | One process and one deploy. No HTTP between services. Engines talk through synchronous events with explicit subscribers. |
+
+## Project status
+
+> [!NOTE]
+> Seams is in active development and has not reached 1.0. Breaking changes are listed in the [CHANGELOG](CHANGELOG.md). Open work is tracked in [issue #5](https://github.com/Davidslv/seams/issues/5).
+
+Each change is checked in CI:
+- RuboCop, Brakeman, and bundle-audit
+- the gem's own tests, on Ruby 3.3, 3.4, and 4.0.7
+- an end-to-end run that creates a new Rails app with `rails new`, generates every engine, runs each engine's tests, and boots the app against Postgres
+
+## Contributing
+
+- **How to contribute:** [CONTRIBUTING.md](CONTRIBUTING.md) covers setup, the checks, and the pull request workflow. Run `bin/audit` before you push.
+- **Security issues:** [SECURITY.md](SECURITY.md)
+- **Getting help:** [SUPPORT.md](SUPPORT.md)
+- **How the project is run:** [GOVERNANCE.md](GOVERNANCE.md) and [MAINTAINERS.md](MAINTAINERS.md)
+- **Community expectations:** [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
+- **AI coding agents:** [AGENTS.md](AGENTS.md) and [llms.txt](llms.txt)
+- **Citing Seams:** [CITATION.cff](CITATION.cff)
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT. See [LICENSE](LICENSE).