tsykvas_rails_template 0.1.0

data/lib/generators/tsykvas_rails_template/install/templates/.claude/docs/companions.md

@@ -0,0 +1,128 @@
+# Recommended companions
+
+`bin/rails g tsykvas_rails_template:companions` adds the gems used across
+every project the gem author maintains, plus runs their `:install`
+sub-generators and injects standard configuration. Run **after**
+`tsykvas_rails_template:install`.
+
+This doc is gem-shipped reference; `/tsykvas-claude` keeps the body
+verbatim and only swaps host-specific examples.
+
+## What you get
+
+| Gem | Group | Why | Post-install action |
+|---|---|---|---|
+| `devise` | top-level | Authentication (`current_user`, `before_action :authenticate_user!`). The gem's `OperationsMethods` and `Base::Operation::Base#authorize!` need a `current_user` source — Devise is the universal choice across reference projects. | `rails g devise:install` (initializer + locale). **No User model is generated** — run `rails g devise User` (or your resource name) when ready. |
+| `omniauth-rails_csrf_protection` | top-level | CSRF guard for OAuth callbacks. Required if Devise + OmniAuth are used together. | none |
+| `simple_form` | top-level | Form builder with cleaner DSL than `form_with`. Components and operation scaffolds work fine without it, but you'll likely use it once you have non-trivial forms. | `rails g simple_form:install` (with `--bootstrap` if Probe sees Bootstrap). |
+| `mini_magick` | top-level | Image processing for ActiveStorage variants and `image_processing` gem. | none — but **ImageMagick must be installed system-wide** (`brew install imagemagick` / `apt install imagemagick`). The generator doesn't manage OS packages. |
+| `mission_control-jobs` | top-level (gated on `:solid_queue`) | Web UI for SolidQueue at `/jobs`. | Injects an admin-only mount into `config/routes.rb`. See "MissionControl::Jobs constraint" below. |
+| `rspec-rails` | `:development, :test` | The gem assumes RSpec for testing; operation-spec patterns documented in `testing.md`. | `rails g rspec:install` (creates `.rspec`, `spec/spec_helper.rb`, `spec/rails_helper.rb`). |
+| `factory_bot_rails` | `:development, :test` | Test data factories. | none |
+| `faker` | `:development, :test` | Realistic fake data inside factories. | none |
+| `shoulda-matchers` | `:test` | RSpec matchers for AR / Rails (`have_many`, `validate_presence_of`, etc.). The project explicitly avoids association/validation specs as a default — but matchers are still useful where appropriate. | Appends a `Shoulda::Matchers.configure` block to `spec/rails_helper.rb`. |
+| `webmock` | `:test` | Stub external HTTP calls in tests. | Appends `WebMock.disable_net_connect!(allow_localhost: true)` to `spec/rails_helper.rb`. |
+| `dotenv-rails` | `:development, :test` | Load env vars from `.env` files in dev/test. | Appends `.env` / `.env.*` / `!.env.example` rules to `.gitignore`. |
+
+## Opt-out matrix
+
+| Flag | Skips |
+|---|---|
+| `--skip-auth` | `devise` + `omniauth-rails_csrf_protection` + `devise:install` |
+| `--skip-forms` | `simple_form` + `simple_form:install` |
+| `--skip-images` | `mini_magick` |
+| `--skip-jobs-ui` | `mission_control-jobs` + the routes mount |
+| `--skip-test` | `rspec-rails` + `factory_bot_rails` + `faker` + `shoulda-matchers` + `webmock` + `rspec:install` + config injections |
+| `--skip-dev` | `dotenv-rails` + `.gitignore` append |
+| `--skip-bundle` | `bundle install` after Gemfile edits |
+| `--skip-post-install` | All `:install` sub-generators and config injections (Gemfile additions still happen) |
+
+Combine flags freely: `bin/rails g tsykvas_rails_template:companions --skip-auth --skip-forms` adds only the test/dev/images/jobs-ui groups.
+
+## Idempotency
+
+Re-running `:companions` is safe:
+
+- **Gemfile additions** check existing contents via regex; skip if present.
+- **`:install` sub-generators** skip if their canonical config file exists
+  (`config/initializers/devise.rb`, `config/initializers/simple_form.rb`,
+  `spec/rails_helper.rb`).
+- **Config injections** check for marker strings (`Shoulda::Matchers`,
+  `WebMock.disable_net_connect`, `MissionControl::Jobs::Engine`, `.env`)
+  and bail if found.
+
+You can re-run after edits without losing your work, and CI runs the
+generator twice in the smoke job to verify this.
+
+## MissionControl::Jobs constraint
+
+The mount injected into `config/routes.rb`:
+
+```ruby
+mount MissionControl::Jobs::Engine,
+      at: "/jobs",
+      constraints: ->(req) {
+        user = req.env["warden"]&.user
+        user.respond_to?(:admin?) && user.admin?
+      }
+```
+
+Why a lambda constraint and not `authenticated :user`:
+
+- The lambda runs **per request**, so a missing `User` model at boot
+  doesn't crash. You can install `:companions` before generating Devise's
+  User; `/jobs` will return 404 on every request until `User` exists with
+  an `admin?` method, which is exactly what you want (lock-by-default).
+- Works with **any Warden-based auth** (Devise, custom Warden mounts).
+  Doesn't require Devise's `devise_for :users` to have run yet.
+- `respond_to?(:admin?)` keeps the lambda from raising `NoMethodError`
+  if your User model doesn't define `admin?` yet — the route just 404s.
+
+If your auth stack isn't Warden-based, swap the constraint:
+```ruby
+constraints: ->(req) {
+  current_user = YourAuthHelper.current_user_from(req)
+  current_user&.admin?
+}
+```
+
+## Common follow-ups
+
+After `bin/rails g tsykvas_rails_template:companions`:
+
+1. **Devise User model.** When your domain is ready: `rails g devise User`.
+   Add `admin:boolean` if you want the `/jobs` mount to actually show its
+   UI: `rails g devise User admin:boolean`. Then `rails db:migrate`.
+   Don't forget to update the Devise routes line: `devise_for :users`.
+2. **simple_form configuration.** If you skipped `--bootstrap` and want it
+   later, re-run `rails g simple_form:install --bootstrap` (it'll prompt
+   to overwrite the initializer; say yes).
+3. **shoulda-matchers + RSpec.** The appended config block targets RSpec.
+   If you migrated to a different test framework after running
+   `:companions`, remove the block manually.
+4. **WebMock allow-list.** If your tests need to hit a real internal
+   service (e.g. a containerized backend), wrap the call:
+   ```ruby
+   WebMock.disable! { real_call }   # or WebMock.allow_net_connect!
+   ```
+
+## Why these gems specifically
+
+These are the gems that appear across the gem author's reference projects AND aren't part of the default `rails new` Gemfile. The gem deliberately doesn't ship gems that:
+
+- Already come with Rails (Puma, Importmap, Turbo, Stimulus, Bootsnap,
+  SolidQueue / SolidCache / SolidCable, Brakeman, Rubocop-Rails-Omakase, …).
+- Vary across projects (Tailwind vs custom CSS as alternatives to Bootstrap, MySQL vs
+  Postgres, Sidekiq vs SolidQueue when both are valid).
+- Are essential to one project but not universal (Swagger generators, alternate
+  pagination libraries, search DSLs).
+
+The `:companions` set is the **least common denominator across the gem
+author's projects**, not "every gem you might want".
+
+## Skipping `:companions` entirely
+
+If your stack is incompatible (CanCanCan instead of Pundit, Tailwind
+instead of Bootstrap with simple_form, Minitest instead of RSpec), don't
+run `:companions`. The gem's core (`:install` + `:concept`) is stack-
+agnostic and works fine without any of these.

data/lib/generators/tsykvas_rails_template/install/templates/.claude/docs/concepts-refactoring.md

@@ -0,0 +1,194 @@
+# Concepts Pattern — Guide
+
+## What a controller looks like
+
+```ruby
+# frozen_string_literal: true
+
+class Admin::UsersController < Admin::BaseController
+  def index
+    endpoint Admin::User::Operation::Index, Admin::User::Component::Index
+  end
+
+  def show
+    endpoint Admin::User::Operation::Show, Admin::User::Component::Show
+  end
+end
+```
+
+Every action is a one-liner: `endpoint OperationClass, ComponentClass`. For redirect-only actions the component can be omitted (the operation must set `self.redirect_path`). No AR queries, no `if`/`else`, no flash juggling in controllers.
+
+---
+
+## File structure
+
+```
+app/concepts/<namespace>/<feature>/
+  operation/
+    index.rb       # business logic for index
+    show.rb
+    create.rb
+    update.rb
+    destroy.rb
+  component/
+    index.rb            # ViewComponent class
+    index.html.slim     # template (note .html.slim — required by ViewComponent 4.8+)
+    show.rb
+    show.html.slim
+    form.rb             # shared form for new/edit
+    form.html.slim
+    new.rb              # subclass of Form (breadcrumbs/title)
+    edit.rb
+```
+
+Mirror the same paths under `spec/concepts/...`.
+
+---
+
+## How `endpoint` works
+
+`endpoint` is defined in `app/controllers/concerns/operations_methods.rb`. It:
+
+1. Calls `operation.call(params:, current_user:)`
+2. Verifies authorization was invoked (or skipped) via `check_authorization_is_called(result)`
+3. Yields to the optional block (used by `Users::RegistrationsController` for Devise sign-in glue)
+4. Dispatches by `action_name` and response format
+
+| `action_name` | Success behavior | Failure behavior |
+|---|---|---|
+| `index`, `show`, `edit`, `new` | Render `component.new(**kwargs)` | Same, with flash alert |
+| `create`, `update`, anything containing `destroy` | Redirect to `result.redirect_path` (or `<controller_name>_path`) with flash notice | Re-render component with 422 |
+| `format.js` (for any action) | Redirect via `window.location.href = '<path>'` | Render component into `#modals` and toggle Bootstrap modal |
+| `format.json` | `result.model.map(&:select2_search_result)` with pagination JSON | (same) |
+
+Component kwargs come from `result.model`:
+
+- `OpenStruct` → `component.new(**result.model.to_h)` (recommended for multi-value results)
+- Single AR object → `component.new(<concept>: model)` where `<concept>` is the operation's top-level namespace, singularized for show/edit/new and pluralized for index/create/update/destroy
+
+---
+
+## Writing an operation
+
+```ruby
+# frozen_string_literal: true
+
+class Feature::Operation::Action < Base::Operation::Base
+  def perform!(params:, current_user:)
+    # 1. Authorization (REQUIRED — pick one)
+    authorize! record, :action?
+    # or
+    self.model = ::OpenStruct.new(items: policy_scope(Item))
+    # or
+    skip_authorize       # only when there's no AR record to authorize
+
+    # 2. Business logic / data loading
+
+    # 3. Set the result model
+    self.model = ::OpenStruct.new(key: value, ...)
+
+    # 4. (For create/update/destroy) trigger redirect
+    self.redirect_path = some_path
+    notice(I18n.t('notices.created'))
+  end
+end
+```
+
+### Authorization rules
+
+- Internal AR models → `authorize! record, :action?` (or `policy_scope(...)` for collections, or `authorize_and_save!`)
+- Anything truly auth-free → `skip_authorize` and (if iterating a collection) `skip_policy_scope`
+- Per-domain base policies (`Admin::BasePolicy`, `Crm::BasePolicy`, `Screener::BasePolicy`) drive the redirect destination on `Pundit::NotAuthorizedError` — keep your `<Domain>Policy < <Domain>::BasePolicy` hierarchy intact.
+
+### Triggering a redirect from an operation
+
+Set `self.redirect_path` and `endpoint` will redirect:
+
+```ruby
+self.redirect_path = Rails.application.routes.url_helpers.crm_root_path
+notice(I18n.t('notices.updated'))
+```
+
+For "resource not found" in a `show`-style action:
+
+```ruby
+def resource_not_found?(record)
+  return false unless record.nil?
+
+  add_error :base, I18n.t('alerts.resource_not_found')
+  invalid!
+  self.redirect_path = Rails.application.routes.url_helpers.admin_users_path
+  true
+end
+```
+
+### Flash messages
+
+```ruby
+notice(I18n.t('notices.created'))                       # success → result.message
+notice(I18n.t('alerts.warning'), level: :alert)         # warning → result.message_level == :alert
+add_error :base, I18n.t('alerts.failed'); invalid!      # failure → result.error_message
+```
+
+### `OpenStruct` model
+
+Pass multiple values via `::OpenStruct`. `endpoint` spreads it as kwargs:
+
+```ruby
+self.model = ::OpenStruct.new(
+  users: paginated_users,
+  request_params: params           # only if the slim template needs request params
+)
+```
+
+```ruby
+component.new(**result.model.to_h)  # Component.new(users: ..., request_params: ...)
+```
+
+### Sub-operations
+
+```ruby
+run_operation(OtherOp, params: params, current_user: current_user)
+# Failures bubble up automatically. Pass manually_handle_errors: true to handle them yourself.
+```
+
+---
+
+## Writing a component
+
+```ruby
+# frozen_string_literal: true
+
+class Feature::Component::Index < Base::Component::Base
+  def initialize(users:, request_params: nil)
+    @users = users
+    @request_params = request_params
+  end
+end
+```
+
+Rules:
+
+- Always `# frozen_string_literal: true`.
+- Pure presentation: data only via `initialize`. No AR queries.
+- Use `I18n.t('full.key')` — never `t('.relative_key')`.
+- Template at `app/concepts/<ns>/<feature>/component/<action>.html.slim` next to the `.rb`.
+- For request params, prefer `@request_params` (passed through OpenStruct) over `helpers.params`.
+
+---
+
+## Non-standard action names
+
+`endpoint` triggers a redirect when `result.redirect_path` is set, regardless of action name. So custom actions like `archive_property` work without special handling — just make sure the operation sets `self.redirect_path`.
+
+---
+
+## Refactor checklist
+
+1. Read the controller — understand each action's intent.
+2. Move logic into operations under `app/concepts/<ns>/<feature>/operation/`.
+3. Create or verify components under `app/concepts/<ns>/<feature>/component/`.
+4. Replace controller actions with `endpoint Op, Component`.
+5. Update every locale file under `config/locales/` to mirror the new keys.
+6. Add specs: operation spec (happy path + Pundit failure path), component spec for non-trivial render logic.
+7. Validate: `bin/rails zeitwerk:check`, `bin/rubocop`, `bundle exec rspec`.

data/lib/generators/tsykvas_rails_template/install/templates/.claude/docs/database.md

@@ -0,0 +1,135 @@
+# Database & Migrations
+
+PostgreSQL 16, Rails 8.1, multi-database setup.
+
+## Multi-database layout
+
+Rails 8.1 ships with three solid_* gems, each with its own database:
+
+| Database | Purpose | Schema file |
+|---|---|---|
+| `<app_name>_<env>` (primary) | Application data — `users`, `properties`, ... | `db/schema.rb` |
+| `cache` | `Rails.cache` backing (SolidCache) | `db/cache_schema.rb` |
+| `queue` | Active Job backing (SolidQueue) | `db/queue_schema.rb` |
+| `cable` | Action Cable backing (SolidCable) | `db/cable_schema.rb` |
+
+`config/database.yml` only defines the primary; `cache`, `queue`, `cable` are configured per-env via the corresponding YAML files (`config/cache.yml`, `config/queue.yml`, `config/cable.yml`). In **development** and **test**, cache/queue/cable run in the primary database for simplicity. In **production** they're separate Postgres databases on the same instance.
+
+Practical impact: `bin/rails db:prepare` handles them all. You generally don't write migrations against the cache/queue/cable schemas — those are managed by their respective gems.
+
+## Migration conventions
+
+- File name: `db/migrate/YYYYMMDDHHMMSS_describe_change.rb`
+- Class name in PascalCase matching the file.
+- Schema version is in `db/schema.rb` — keep it in version control.
+- Always include `null: false` for required columns.
+- Always add an index for foreign keys: `t.references :property, foreign_key: true, null: false` (creates the index automatically).
+- Use `add_foreign_key` if you create the column without `t.references`.
+- Default values: only at the DB layer for safety-critical defaults (NOT NULL with sensible default). Application-level defaults live in the model.
+- For long-running migrations on large tables, use `disable_ddl_transaction!` and `add_index ..., algorithm: :concurrently`.
+
+```ruby
+class CreateReports < ActiveRecord::Migration[8.1]
+  def change
+    create_table :reports do |t|
+      t.references :property, null: false, foreign_key: true
+      t.string :title, null: false
+      t.text :body
+      t.integer :status, null: false, default: 0
+      t.timestamps
+    end
+
+    add_index :reports, [:property_id, :status]
+  end
+end
+```
+
+## Enums
+
+Use **integer enums** at the DB layer, declared in the model:
+
+```ruby
+# db migration
+t.integer :role, null: false, default: 1
+
+# model
+enum :role, { admin: 0, owner: 1, customer: 2 }
+```
+
+Rules:
+- Always pin integer values explicitly (don't rely on positional ordering).
+- Adding a new value: append to the end with the next integer. Never reorder or reuse values — existing rows reference them.
+- The default integer in the migration should map to the most common value (here `1` = `:customer`).
+
+## Current schema (snapshot)
+
+```
+users
+  id (bigint, PK)
+  email (string, NOT NULL, default '', unique index)
+  encrypted_password (string, NOT NULL, default '')
+  name (string, NOT NULL)
+  role (integer, NOT NULL, default 1)         # User#role enum
+  reset_password_token (string, unique index)
+  reset_password_sent_at (datetime)
+  remember_created_at (datetime)
+  created_at, updated_at
+
+properties
+  id (bigint, PK)
+  name (string, NOT NULL)
+  owner_id (bigint, FK → users.id, NOT NULL, indexed)
+  created_at, updated_at
+```
+
+`properties.owner_id` → `users.id` is the property/owner relationship. `User#owned_properties` returns properties where this user is the owner. Substitute your own associations to fit your domain.
+
+## Models
+
+`app/models/` — keep them small:
+
+- Validations + associations + enums + scopes only.
+- No business logic — that lives in operations.
+- No callbacks for cross-model side effects (use operations or jobs).
+- Custom validators (e.g. `User#owner_can_have_only_one_property`) are fine when they enforce a true invariant.
+
+`select2_search_result` is a model-level convention: any model used as a select2 source must implement it (called by `endpoint`'s `format.json` branch). Returns a hash like `{ id:, text: }`.
+
+## Seeds & dev data
+
+`db/seeds.rb` is currently empty. When you add seeds:
+
+- Make them **idempotent** (`find_or_create_by!`).
+- Use `Rails.env.development?` guards if a seed shouldn't run in production.
+- Document the dev login (admin email + password) in `README.md` so a fresh checkout works.
+
+```ruby
+# db/seeds.rb
+if Rails.env.development?
+  User.find_or_create_by!(email: 'admin@example.com') do |u|
+    u.name = 'Admin'
+    u.password = 'password'
+    u.role = :admin
+  end
+end
+```
+
+## Common commands
+
+```bash
+bin/rails db:prepare          # create + migrate (or load schema) — run on bootstrap
+bin/rails db:migrate          # apply pending migrations
+bin/rails db:rollback         # roll back last migration
+bin/rails db:seed             # run db/seeds.rb
+bin/rails db:reset            # drop + create + load schema + seed (development only)
+bin/rails db:schema:load      # load schema.rb (faster than running all migrations)
+```
+
+## Anti-patterns
+
+- ❌ `belongs_to :foo` without `foreign_key: true` constraint at the DB level.
+- ❌ String-typed enums — use integer enums with explicit values.
+- ❌ Renaming an enum value without a data migration.
+- ❌ Reusing an integer for a different enum value (silently corrupts old rows).
+- ❌ Long-running `add_column` on large tables without `algorithm: :concurrently` for the matching index.
+- ❌ Business logic in `before_save` — the operation layer is the right place.

data/lib/generators/tsykvas_rails_template/install/templates/.claude/docs/deployment.md

@@ -0,0 +1,138 @@
+# Deployment (Kamal)
+
+The app deploys via **Kamal** (`config/deploy.yml`). Single web server runs Puma + SolidQueue + the Thruster proxy in one container.
+
+## Where things live
+
+```
+config/deploy.yml         # Service config — servers, registry, env, volumes, builder
+.kamal/secrets            # Pulls secrets from local env / 1Password (NEVER raw creds)
+.kamal/hooks/             # Lifecycle hooks (pre-build, post-deploy, ...) — all .sample by default
+Dockerfile                # Production image
+config/master.key         # NEVER committed — used to decrypt config/credentials.yml.enc
+```
+
+## Service overview
+
+From `config/deploy.yml`:
+
+- **Service name**: `<your-app>` (set in `config/deploy.yml` — match the host app's name)
+- **Image**: `your-user/<your-app>` (replace `your-user` with your container registry user before first deploy)
+- **Servers**: web servers under `servers.web`
+- **SSL**: Let's Encrypt via Kamal proxy (`proxy.ssl: true`)
+- **Volumes**: `app_storage:/rails/storage` for Active Storage (rename to match your service)
+- **Builder arch**: `amd64`
+- **SolidQueue runs in Puma**: `SOLID_QUEUE_IN_PUMA=true` (single-server setup). Split it onto `servers.job` once you scale.
+
+## Secrets
+
+```bash
+.kamal/secrets    # Resolves at deploy time, never holds raw secrets
+```
+
+Current setup pulls:
+- `KAMAL_REGISTRY_PASSWORD` from local env
+- `RAILS_MASTER_KEY` from `config/master.key`
+
+To add a new secret:
+
+1. Add the variable name to `.kamal/secrets` and resolve it (env, 1Password, file).
+2. Reference it under `env.secret:` in `config/deploy.yml`.
+3. The container will receive it as an env var at runtime.
+
+**Never** put raw credentials in `config/deploy.yml` or `.kamal/secrets` — both are committed.
+
+## Common commands
+
+```bash
+bin/kamal setup              # First-time setup (one-shot per server)
+bin/kamal deploy             # Build + push image + reload containers
+bin/kamal redeploy           # Redeploy without rebuilding
+bin/kamal rollback           # Rollback to the previous version
+bin/kamal logs -f            # Tail logs (alias defined in deploy.yml)
+bin/kamal console            # Open a Rails console on the server
+bin/kamal shell              # Bash shell on the server
+bin/kamal dbc                # Open a dbconsole
+
+bin/kamal app exec ...       # Run an ad-hoc command in the app container
+bin/kamal proxy ...          # Manage the Kamal proxy container
+```
+
+`config/deploy.yml.aliases` defines `console`, `shell`, `logs`, `dbc` as shortcuts.
+
+## Build & release flow
+
+1. `bin/kamal deploy` builds the image locally (or via remote builder if configured).
+2. Pushes to the registry.
+3. Triggers `pre-deploy` hooks (none by default — `.sample` files).
+4. Runs `db:prepare` inside the app container (handled by Rails on boot).
+5. Replaces running containers.
+6. Triggers `post-deploy` hooks.
+
+Bridging in-flight requests across asset versions: `asset_path: /rails/public/assets` (Kamal copies the new and old asset directories so neither generation 404s during the swap).
+
+## Lifecycle hooks
+
+`.kamal/hooks/` ships with samples:
+
+- `pre-build` — before the image is built (e.g. compile assets externally)
+- `pre-connect` — before Kamal connects to servers
+- `pre-deploy`, `post-deploy` — around the deploy
+- `pre-app-boot`, `post-app-boot` — around the app container start
+- `pre-proxy-reboot`, `post-proxy-reboot` — around the Kamal proxy
+
+Drop the `.sample` extension to enable a hook. They are shell scripts run from the deploy machine.
+
+## Rollback strategy
+
+```bash
+bin/kamal rollback           # Reverts to previous image version
+```
+
+Rollbacks are fast (just swap container images), but **migrations are not auto-reverted** — if you rolled forward a destructive migration, you need to manually fix the schema before rolling back.
+
+For destructive migrations, prefer the two-step pattern:
+1. Deploy a release that *adds* the new column / table without removing the old one.
+2. Backfill data + switch reads/writes.
+3. Deploy a follow-up release that drops the old column.
+
+## CI
+
+GitHub Actions (`.github/workflows/ci.yml`) runs on every PR:
+
+- `bin/brakeman --no-pager`
+- `bin/importmap audit`
+- `bin/rubocop`
+- `bundle exec rspec` (against PostgreSQL 16)
+
+All four must pass before merge. CI does NOT auto-deploy — production deploys are manual via `bin/kamal deploy`.
+
+## Environment variables
+
+Set in `config/deploy.yml` under `env.clear` (visible) or `env.secret` (resolved from `.kamal/secrets`):
+
+- `RAILS_MASTER_KEY` (secret) — decrypts credentials
+- `SOLID_QUEUE_IN_PUMA=true` — runs queue inline with web
+- `JOB_CONCURRENCY` — number of SolidQueue processes (default 1)
+- `WEB_CONCURRENCY` — number of Puma workers (default 1)
+- `DB_HOST` — when using an external Postgres
+- `RAILS_LOG_LEVEL` — defaults to `info`
+
+In development, use `.env` (loaded by `dotenv-rails`).
+
+## Adding a new server
+
+1. Add the IP under `servers.web` in `config/deploy.yml`.
+2. Run `bin/kamal setup` against that server (one-time).
+3. Run `bin/kamal deploy`.
+
+Once you have multiple web servers, **move SolidQueue to a dedicated `servers.job` host** (set `SOLID_QUEUE_IN_PUMA=false` and use `cmd: bin/jobs`). Otherwise jobs run on every web box and double-execute.
+
+## Anti-patterns
+
+- ❌ Committing `config/master.key`.
+- ❌ Hardcoding secrets in `config/deploy.yml` or `.kamal/secrets`.
+- ❌ `kamal redeploy` after a schema change without re-running migrations (use `deploy`).
+- ❌ Running `bin/kamal deploy` from a branch with uncommitted changes.
+- ❌ Force-pushing to `main` (CI gates production-bound code).
+- ❌ Multi-host deploys with `SOLID_QUEUE_IN_PUMA=true` (jobs double-execute).