seams 0.1.0

data/lib/generators/seams/remove/remove_generator.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "rails/generators"
+require "seams"
+require "seams/generators/sibling_rubocop_writer"
+require "seams/generators/host_injector"
+
+module Seams
+  module Generators
+    # Removes an engine generated by `seams:engine`. Prompts for
+    # confirmation unless --force is passed. Cleans up the surviving
+    # engines' .rubocop.yml so OtherEngines no longer references the
+    # engine that was just removed. Reverses host file edits made by
+    # the canonical generators (mount line, includes) — leaves the
+    # Gemfile alone since other engines may share gem deps.
+    #
+    # Run with: bin/rails generate seams:remove billing [--force]
+    class RemoveGenerator < Rails::Generators::NamedBase
+      include Seams::Generators::HostInjector
+
+      # Same constraints as EngineGenerator — keeps `seams:remove ../../etc`
+      # from being interpreted as a relative path the destructive
+      # FileUtils.rm_rf at line 80 would happily follow with --force.
+      NAME_PATTERN = /\A[a-z][a-z0-9_]*\z/
+
+      class_option :force, type: :boolean, default: false,
+                           desc: "Skip the confirmation prompt"
+
+      def validate_name
+        return if NAME_PATTERN.match?(name)
+
+        raise Seams::GeneratorError,
+              "Engine name #{name.inspect} must be lowercase letters, digits, " \
+              "and underscores, starting with a letter."
+      end
+
+      # Maps engine name -> { mount: <Class>, includes: { user: [...], application_controller: [...] } }
+      # Lets remove know what to undo for the canonical engines. Generic
+      # engines aren't in this table and just get the directory deleted.
+      CANONICAL_HOST_EDITS = {
+        "auth" => {
+          mount: "Auth::Engine",
+          user_includes: %w[Auth::Authenticatable],
+          application_controller_includes: %w[Auth::Authentication]
+        },
+        "notifications" => {
+          mount: "Notifications::Engine",
+          user_includes: %w[Notifications::Notifiable]
+        },
+        # Post-Wave-9: billing no longer injects Billing::Billable
+        # into the host User — the engine includes it into the
+        # configured tenant class (default Accounts::Account) at
+        # boot via Billing.configuration.billable_class. The only
+        # host-side edit billing makes is the mount line, so unmount
+        # is the only reverse-edit we need.
+        "billing" => {
+          mount: "Billing::Engine",
+          user_includes: %w[]
+        },
+        "teams" => {
+          # Wave 9 removed Teams::Teamable — there's no canonical host
+          # User concern to remove. The `mount Teams::Engine` line is
+          # the only host edit the teams generator makes, so unmount
+          # is the only reverse-edit we need here.
+          mount: "Teams::Engine",
+          user_includes: %w[]
+        },
+        # Wave 9 — accounts engine. Like billing/teams post-Wave-9, the
+        # accounts generator does NOT inject anything into the host User
+        # (the canonical demo doesn't have one). Mount is the only
+        # host-side edit, so unmount is the only reverse-edit we need.
+        "accounts" => {
+          mount: "Accounts::Engine",
+          user_includes: %w[]
+        },
+        # Wave 11A — admin engine. Mounts under Seams::Admin::Engine.
+        # The generator injects `gem "administrate"` and `gem "pundit"`
+        # into the host Gemfile but the remover does NOT prune them
+        # (the host may have other dashboards depending on either).
+        # Unmounting + dropping the engine dir is enough.
+        "admin" => {
+          mount: "Seams::Admin::Engine",
+          user_includes: %w[]
+        }
+      }.freeze
+
+      # Read the engine's create_table calls before its directory is
+      # deleted. Used by write_drop_table_migration to generate the
+      # reversal. Pattern-matches the literal ActiveRecord::Migration
+      # call so we drop exactly what the engine created — never
+      # host-side tables that happen to share the prefix.
+      def capture_engine_tables
+        engine_path = File.join(destination_root, "engines", name)
+        return @engine_tables = [] unless File.directory?(engine_path)
+
+        migrate_dir = File.join(engine_path, "db/migrate")
+        return @engine_tables = [] unless File.directory?(migrate_dir)
+
+        @engine_tables = Dir.glob(File.join(migrate_dir, "*.rb")).flat_map do |file|
+          # Strip line comments before scanning so a stray
+          # `# create_table :backup_table do |t|` in a migration
+          # doesn't end up in the drop-table list.
+          source = File.read(file).gsub(/^\s*#.*$/, "")
+          source.scan(/^\s*create_table\s+:(\w+)/).flatten
+        end.uniq
+      end
+
+      def remove_engine_directory
+        engine_path = File.join(destination_root, "engines", name)
+
+        unless File.directory?(engine_path)
+          @engine_was_present = false
+          say "  skip    engines/#{name}/ (not found)", :yellow
+          return
+        end
+
+        return unless options[:force] || confirm_removal?
+
+        FileUtils.rm_rf(engine_path)
+        @engine_was_present = true
+        say "  remove  engines/#{name}/", :red
+      end
+
+      # Phase 1.7 — generate a drop-table migration in the host's
+      # db/migrate so the host can run `bin/rails db:migrate` to
+      # reclaim the engine's tables. Idempotent if-table-exists
+      # check so re-running doesn't blow up on already-dropped tables.
+      def write_drop_table_migration
+        return unless @engine_was_present
+        return if @engine_tables.nil? || @engine_tables.empty?
+
+        migrate_dir = File.join(destination_root, "db/migrate")
+        FileUtils.mkdir_p(migrate_dir)
+
+        filename       = "#{drop_migration_timestamp}_drop_#{name}_tables.rb"
+        migration_path = File.join(migrate_dir, filename)
+        File.write(migration_path, drop_table_migration_body)
+
+        say "  create  db/migrate/#{filename}", :green
+        say "          → run `bin/rails db:migrate` to drop #{@engine_tables.size} table(s).", :yellow
+      end
+
+      # Phase 1.7 — re-run `bundle install` so the host's lockfile no
+      # longer references the removed engine's gem deps (the canonical
+      # generators each inject their own — bcrypt, faraday, etc; the
+      # remover doesn't touch the Gemfile because deps are usually
+      # shared, but a fresh `bundle install` keeps lockfile + Gemfile
+      # in sync if the host did prune anything by hand). Skipped when
+      # the engine was never present (no-op remove) or when there's
+      # no Gemfile to bundle against.
+      def run_bundle_install
+        return unless @engine_was_present
+        return unless File.exist?(File.join(destination_root, "Gemfile"))
+
+        say "  run     bundle install (post-remove sync)", :green
+        Dir.chdir(destination_root) do
+          system("bundle", "install", "--quiet") || say("          → bundle install failed; resolve manually.", :red)
+        end
+      end
+
+      def update_sibling_engines
+        return unless @engine_was_present
+
+        engines_root = File.join(destination_root, "engines")
+        return unless Dir.exist?(engines_root)
+
+        survivors = Dir.children(engines_root)
+                       .select { |c| File.directory?(File.join(engines_root, c)) }
+                       .reject { |c| c.start_with?(".") }
+                       .sort
+
+        return if survivors.empty?
+
+        Seams::Generators::SiblingRubocopWriter.rewrite!(engines_root: engines_root, dirs: survivors)
+        say "  update  .rubocop.yml of #{survivors.size} sibling engine(s)", :green
+      end
+
+      def unwire_from_host
+        return unless @engine_was_present
+
+        unwire_generic_host_edits
+        unwire_canonical_host_edits(CANONICAL_HOST_EDITS[name])
+      end
+
+      private
+
+      def unwire_generic_host_edits
+        # Generic uninject — applies to every engine. The mount line +
+        # initializer were created by the generic engine generator.
+        host_uninject_mount(engine_class: "#{generic_module_name}::Engine")
+        host_remove_initializer
+      end
+
+      def unwire_canonical_host_edits(edits)
+        return unless edits
+
+        host_uninject_mount(engine_class: edits[:mount]) if edits[:mount]
+        Array(edits[:user_includes]).each do |concern|
+          host_uninject_include("app/models/user.rb", concern)
+        end
+        Array(edits[:application_controller_includes]).each do |concern|
+          host_uninject_include("app/controllers/application_controller.rb", concern)
+        end
+      end
+
+      def confirm_removal?
+        yes?("Remove engine `#{name}` and everything under engines/#{name}? [y/N]")
+      end
+
+      def generic_module_name
+        name.split("_").map(&:capitalize).join
+      end
+
+      def host_remove_initializer
+        path = File.join(destination_root, "config/initializers/#{name}.rb")
+        return unless File.exist?(path)
+
+        FileUtils.rm(path)
+        say "  remove  config/initializers/#{name}.rb", :red
+      end
+
+      def drop_migration_timestamp
+        Time.now.utc.strftime("%Y%m%d%H%M%S")
+      end
+
+      def drop_table_migration_body
+        drops = @engine_tables.map do |table|
+          %(    drop_table :#{table}, force: :cascade if table_exists?(:#{table}))
+        end.join("\n")
+
+        rails_version = Rails::VERSION::STRING.split(".")[0, 2].join(".") if defined?(Rails::VERSION::STRING)
+        rails_version ||= "7.1"
+
+        <<~RB
+          # frozen_string_literal: true
+          #
+          # Drops every table created by the #{name} engine. Generated by
+          # `bin/rails generate seams:remove #{name}`. Run with:
+          #
+          #   bin/rails db:migrate
+          #
+          # The if-table-exists guards make re-running safe.
+          class Drop#{name.classify}Tables < ActiveRecord::Migration[#{rails_version}]
+            def up
+          #{drops}
+            end
+
+            def down
+              raise ActiveRecord::IrreversibleMigration,
+                    "Cannot recreate #{name} engine tables — re-run " \\
+                    "`bin/rails generate seams:#{name}` to recreate the engine."
+            end
+          end
+        RB
+      end
+    end
+  end
+end

data/lib/generators/seams/teams/teams_generator.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "rails/generators"
+require "seams"
+require "generators/seams/engine/engine_generator"
+require "seams/generators/host_injector"
+require "seams/generators/eject_aware"
+require "seams/generators/dummy_app_writer"
+
+module Seams
+  module Generators
+    # Generates a canonical Teams engine on top of the generic engine
+    # scaffold. Models cover Team, Membership, Invitation; controllers
+    # cover team CRUD + membership management + invitation send/accept.
+    #
+    # Wave 9 model: Teams is a peer to Accounts (not nested). A
+    # Teams::Membership joins Auth::Identity directly to a Teams::Team.
+    # The host-User Teamable concern is gone — Wave 9 dropped the
+    # canonical demo's host User, so there's nowhere to mix it into.
+    #
+    # Run with: bin/rails generate seams:teams
+    class TeamsGenerator < Rails::Generators::Base
+      include Seams::Generators::HostInjector
+      include Seams::Generators::EjectAware
+
+      source_root File.expand_path("templates", __dir__)
+
+      ENGINE_NAME = "teams"
+      DEFAULT_FEATURES = %w[invitations roles].freeze
+
+      class_option :with, type: :string, default: "all",
+                          desc: "Comma-separated features to enable: invitations,roles (or 'all')"
+
+      def create_base_engine
+        EngineGenerator.start([ENGINE_NAME], destination_root: destination_root)
+      end
+
+      def overwrite_engine_entry_point
+        # engine.rb / lib/teams.rb stay framework-managed.
+        template "lib/engine.rb.tt",                 engine_path("lib/teams/engine.rb"),        force: true
+        template "lib/teams.rb.tt",                  engine_path("lib/teams.rb"),               force: true
+        template_unless_ejected "lib/configuration.rb.tt",
+                                engine_path("lib/teams/configuration.rb")
+      end
+
+      def overwrite_routes
+        template_unless_ejected "config/routes.rb.tt", engine_path("config/routes.rb"), force: true
+      end
+
+      def create_models
+        template_unless_ejected "app/models/application_record.rb.tt",
+                                engine_path("app/models/teams/application_record.rb")
+        template_unless_ejected "app/models/team.rb.tt",
+                                engine_path("app/models/teams/team.rb")
+        template_unless_ejected "app/models/membership.rb.tt",
+                                engine_path("app/models/teams/membership.rb")
+        template_unless_ejected "app/models/current.rb.tt",
+                                engine_path("app/models/teams/current.rb")
+        return unless features.include?("invitations")
+
+        template_unless_ejected "app/models/invitation.rb.tt",
+                                engine_path("app/models/teams/invitation.rb")
+      end
+
+      def create_controllers
+        template_unless_ejected "app/controllers/teams_controller.rb.tt",
+                                engine_path("app/controllers/teams/teams_controller.rb")
+        template_unless_ejected "app/controllers/memberships_controller.rb.tt",
+                                engine_path("app/controllers/teams/memberships_controller.rb")
+        return unless features.include?("invitations")
+
+        template_unless_ejected "app/controllers/invitations_controller.rb.tt",
+                                engine_path("app/controllers/teams/invitations_controller.rb")
+      end
+
+      # Phase 4A (2/2) — bare-bones views so the engine renders out
+      # of the box. Hosts override by dropping files at
+      # app/views/teams/teams/* in their own tree.
+      def create_views
+        %w[index show new edit].each do |action|
+          template_unless_ejected "app/views/teams/#{action}.html.erb.tt",
+                                  engine_path("app/views/teams/teams/#{action}.html.erb")
+        end
+        template_unless_ejected "app/views/memberships/index.html.erb.tt",
+                                engine_path("app/views/teams/memberships/index.html.erb")
+        return unless features.include?("invitations")
+
+        template_unless_ejected "app/views/invitations/index.html.erb.tt",
+                                engine_path("app/views/teams/invitations/index.html.erb")
+      end
+
+      def create_concerns
+        # Phase 4A — account scoping helper that pairs with Core's
+        # TenantScoped. Mix into models that belong to a single team.
+        template_unless_ejected "lib/concerns/account_scoped.rb.tt",
+                                engine_path("lib/teams/concerns/account_scoped.rb")
+        # `--with=roles` ships role-based controller filters.
+        return unless features.include?("roles")
+
+        template_unless_ejected "lib/concerns/authorization.rb.tt",
+                                engine_path("lib/teams/concerns/authorization.rb")
+      end
+
+      def create_jobs
+        template_unless_ejected "app/jobs/application_job.rb.tt",
+                                engine_path("app/jobs/teams/application_job.rb")
+      end
+
+      def create_mailer_and_subscriber
+        return unless features.include?("invitations")
+
+        template_unless_ejected "app/mailers/invitation_mailer.rb.tt",
+                                engine_path("app/mailers/teams/invitation_mailer.rb")
+        template_unless_ejected "app/views/invitation_mailer/invite.text.erb.tt",
+                                engine_path("app/views/teams/invitation_mailer/invite.text.erb")
+        template_unless_ejected "app/subscribers/invitation_subscriber.rb.tt",
+                                engine_path("app/subscribers/teams/invitation_subscriber.rb")
+      end
+
+      def create_migrations
+        template "db/migrate/create_teams.rb.tt",
+                 engine_path("db/migrate/#{timestamp(0)}_create_teams.rb")
+        template "db/migrate/create_team_memberships.rb.tt",
+                 engine_path("db/migrate/#{timestamp(1)}_create_team_memberships.rb")
+        return unless features.include?("invitations")
+
+        template "db/migrate/create_team_invitations.rb.tt",
+                 engine_path("db/migrate/#{timestamp(2)}_create_team_invitations.rb")
+      end
+
+      def create_specs
+        template_unless_ejected "spec/models/team_spec.rb.tt",
+                                engine_path("spec/models/teams/team_spec.rb")
+        template_unless_ejected "spec/models/membership_spec.rb.tt",
+                                engine_path("spec/models/teams/membership_spec.rb")
+        # Phase 4A — factories live alongside the model specs so any
+        # spec can `create(:team)` without rolling its own fixture.
+        template_unless_ejected "spec/factories/teams.rb.tt",
+                                engine_path("spec/factories/teams.rb")
+        return unless features.include?("invitations")
+
+        template_unless_ejected "spec/models/invitation_spec.rb.tt",
+                                engine_path("spec/models/teams/invitation_spec.rb")
+      end
+
+      def overwrite_readme
+        template "README.md.tt", engine_path("README.md"), force: true
+      end
+
+      def update_exposed_concerns
+        rubocop_path = engine_path(".rubocop.yml")
+        return unless File.exist?(rubocop_path)
+
+        contents       = File.read(rubocop_path)
+        exposed_lines  = ["    - Teams::AccountScoped"]
+        exposed_lines << "    - Teams::Authorization" if features.include?("roles")
+        replacement    = "  ExposedConcerns:\n#{exposed_lines.join("\n")}"
+        contents.sub!(/^  ExposedConcerns: \[\]$/, replacement)
+        File.write(rubocop_path, contents)
+      end
+
+      def create_dummy_app
+        # Wave 9: no host User model in the dummy. The dummy ships a
+        # slim Auth::Identity stub at app/models/auth/identity.rb so
+        # the teams engine's boot-time dependency assertion (defined?
+        # ::Auth::Identity) passes without pulling in the full auth
+        # engine. The same stub also lets `create(:auth_identity)`
+        # build real AR rows against the auth_identities table baked
+        # into dummy_schema.
+        Seams::Generators::DummyAppWriter.write!(
+          engine_path: File.join(destination_root, "engines", ENGINE_NAME),
+          engine_module: "Teams",
+          mount_at: "/teams",
+          schema: dummy_schema,
+          host_user: dummy_host_identity,
+          host_user_path: "app/models/auth/identity.rb"
+        )
+        template "spec/runtime/boot_spec.rb.tt",
+                 engine_path("spec/runtime/teams_boot_spec.rb")
+      end
+
+      def wire_into_host
+        # factory_bot_rails powers spec/factories/teams.rb. Lives in
+        # the host's test group only.
+        host_inject_gem("factory_bot_rails", "~> 6.4", group: :test)
+        host_inject_mount(engine_class: "Teams::Engine", at: "/teams")
+        # NB: no host_inject_include_in_user — the host User is gone
+        # post-Wave-9. Hosts that DO keep a User model and want
+        # team-membership query helpers wire those up themselves.
+      end
+
+      def report_summary
+        say ""
+        say "  Teams engine generated at engines/teams/", :green
+        say ""
+        say "  Next steps:", :yellow
+        say "    1. bin/rails db:migrate"
+        say "    2. Run the engine specs: bin/rails seams:test[teams]"
+        say ""
+      end
+
+      private
+
+      # Resolved feature list from --with. "all" (or empty / unrecognised)
+      # → invitations + roles. Garbage / unknown values fall back to all
+      # so the engine ships fully wired by default. Memoised so ERB
+      # branches stay consistent across the generator run.
+      def features
+        @features ||= begin
+          raw = options[:with].to_s.downcase.strip
+          if raw.empty? || raw == "all"
+            DEFAULT_FEATURES.dup
+          else
+            requested = raw.split(",").map(&:strip).reject(&:empty?)
+            allowed   = requested & DEFAULT_FEATURES
+            allowed.empty? ? DEFAULT_FEATURES.dup : allowed
+          end
+        end
+      end
+
+      def engine_path(relative)
+        File.join(destination_root, "engines", ENGINE_NAME, relative)
+      end
+
+      # Offset by 300 to avoid collisions with the other canonical
+      # engines (auth +0/+1, notifications +100, billing +200/+201/+202).
+      def timestamp(offset)
+        base = Time.now.utc.strftime("%Y%m%d%H%M%S").to_i
+        (base + 300 + offset).to_s
+      end
+
+      # Slim Auth::Identity stub for the teams dummy app. Stands in
+      # for the real Auth::Identity (which lives in the auth engine,
+      # not loaded by the dummy) so the teams engine's boot-time
+      # cross-engine dependency assertion passes and specs that
+      # `create(:auth_identity)` get a real Active Record row backing
+      # the auth_identities table.
+      def dummy_host_identity
+        <<~RB
+          # frozen_string_literal: true
+          module Auth
+            class Identity < ApplicationRecord
+              self.table_name = "auth_identities"
+              has_secure_password
+            end
+          end
+        RB
+      end
+
+      # Includes auth_identities so factories that link memberships to
+      # an Identity can `create(:auth_identity)` against a real row.
+      # Match the auth engine's schema for that table so cross-engine
+      # specs don't drift.
+      def dummy_schema
+        <<~SCHEMA
+          create_table :auth_identities do |t|
+            t.text    :email,            null: false
+            t.string  :password_digest,  null: false
+            t.boolean :staff,            null: false, default: false
+            t.timestamps
+          end
+          add_index :auth_identities, :email, unique: true
+          add_index :auth_identities, :staff, where: "staff = true"
+
+          create_table :teams do |t|
+            t.string :name, null: false
+            t.string :slug, null: false
+            t.timestamps
+          end
+          add_index :teams, :slug, unique: true
+
+          create_table :team_memberships do |t|
+            t.references :team,        null: false
+            t.bigint     :identity_id, null: false
+            t.string     :role,        null: false, default: "member"
+            t.timestamps
+          end
+          add_index :team_memberships, %i[team_id identity_id], unique: true
+          add_index :team_memberships, :identity_id
+
+          create_table :team_invitations do |t|
+            t.references :team,        null: false
+            t.string     :email,       null: false
+            t.string     :token,       null: false
+            t.string     :role,        null: false, default: "member"
+            t.datetime   :expires_at,  null: false
+            t.datetime   :accepted_at
+            t.timestamps
+          end
+          add_index :team_invitations, :token, unique: true
+          add_index :team_invitations, %i[team_id email], unique: true,
+                                                          where: "accepted_at IS NULL"
+        SCHEMA
+      end
+    end
+  end
+end

data/lib/generators/seams/teams/templates/README.md.tt

@@ -0,0 +1,88 @@
+# Teams
+
+> Multi-tenant teams + memberships + invitations for a Seams-powered host.
+
+**Requires:** the `auth` engine. `Teams::Membership.identity_id`
+joins to `auth_identities`. The `Teams::Authorization` concern
+reads `Auth::Current.identity` for membership checks; without auth
+installed, `current_identity_id` returns nil and team-admin gates
+return 403 unconditionally. Install auth before teams.
+
+## Model
+
+A `Teams::Team` is a peer to `Accounts::Account` — **not** nested
+inside one. A `Teams::Membership` is a `(team_id, identity_id, role)`
+join row that links an `Auth::Identity` directly to a `Teams::Team`.
+
+If your application wants "Team belongs to Account" semantics, wire
+that yourself with a host-side migration that adds an `account_id`
+column to `teams`. The Teams engine deliberately stays out of the
+Account/Tenant question: hosts that don't have Accounts (e.g. a B2C
+SaaS that uses Teams as standalone groups) work without any further
+plumbing.
+
+`Auth::Identity` is referenced by id only (`identity_id` is a bare
+bigint column on `team_memberships`, no `belongs_to :identity`). The
+Teams engine never joins to `auth_identities` at the ActiveRecord
+level — cross-engine integrity is enforced at the application layer
+so Teams can move to a separate database in the future.
+
+## Events emitted
+
+| Event name                       | Payload                                                  | Emitted when |
+| ---                              | ---                                                      | --- |
+| `team.created.teams`             | `{ team_id:, creator_identity_id: }`                     | TeamsController#create succeeds |
+| `team.member_joined.teams`       | `{ team_id:, identity_id:, role: }`                      | MembershipsController#create succeeds |
+| `team.member_left.teams`         | `{ team_id:, identity_id: }`                             | MembershipsController#destroy runs |
+| `invitation.sent.teams`          | `{ invitation_id:, team_id:, email:, role:, token: }`    | InvitationsController#create succeeds |
+| `invitation.accepted.teams`      | `{ team_id:, identity_id:, invitation_id: }`             | InvitationsController#accept succeeds |
+
+## Events consumed
+
+| Event name              | Subscriber                       | What it does |
+| ---                     | ---                              | --- |
+| `invitation.sent.teams` | `Teams::InvitationSubscriber`    | Looks up the invitation by id and enqueues `Teams::InvitationMailer.invite(invitation_id).deliver_later`. The host overrides the email body at `app/views/teams/invitation_mailer/invite.text.erb`. |
+
+## Exposed concerns
+
+| Concern                  | Purpose                                                             |
+| ---                      | ---                                                                 |
+| `Teams::Authorization`   | Mixed into engine controllers; provides `require_team_member!` and `require_team_admin!`. Resolves the current human via `current_identity_id`, which by default reads `Auth::Current.identity` (the Auth engine's per-request namespace). Override `current_identity_id` to plug in a different resolver. |
+| `Teams::AccountScoped`   | Mix into host models that belong to a single team. Sets up `belongs_to :team` + a `default_scope` on `Teams::Current.team`. |
+
+> **Wave 9 note.** The `Teams::Teamable` host-User concern was removed.
+> Wave 9 dropped the canonical demo's host User model: hosts that
+> still maintain one are responsible for adding any
+> `team_memberships`-keyed helper methods themselves (querying by
+> `Teams::Membership.where(identity_id: …)`).
+
+## Roles
+
+| Role     | Capabilities |
+| ---      | --- |
+| `owner`  | Everything an admin can, plus deleting the team. |
+| `admin`  | Manage memberships and invitations. |
+| `member` | Read-only by default. |
+
+Teams roles are intentionally independent of Accounts roles — a Team
+is its own RBAC unit. Hosts that want a single role across both
+should denormalise that themselves.
+
+The engine ships role enforcement at the model level (`Membership#admin?`).
+Authorization in controllers is the host's responsibility — Seams gives
+you the data and the events; opinion-free on which authz library you use.
+
+## Mounting
+
+```ruby
+# config/routes.rb (host application)
+Rails.application.routes.draw do
+  mount Teams::Engine, at: "/teams"
+end
+```
+
+## Running the specs
+
+```bash
+bin/rails seams:test[teams]
+```