tsykvas_rails_template 0.1.0

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

@@ -0,0 +1,315 @@
+# Architecture
+
+## Concepts Pattern (primary feature organization)
+
+All features live in `app/concepts/<namespace>/<feature>/` with two sub-directories:
+
+- **`operation/`** — business logic, authorization, data loading
+- **`component/`** — ViewComponent UI classes + Slim templates
+
+Top-level namespaces (illustrative — name them after your access tiers):
+
+- `admin/` — administrators (`user.admin?`)
+- `crm/` — business users (`user.owner?`)
+- `public/` — unauthenticated visitors / end consumers
+- `base/` — shared building blocks (`Base::Operation::Base`, `Base::Component::Base`, `Base::Component::Btn`, `Base::Component::Table::Table`, `Base::Component::TitleRow`, `Base::Operation::Sortable`)
+- `shared/` — cross-domain UI (sidebars, navbars)
+
+`config/initializers/view_component.rb` sets `view_component_path = "app/concepts"`. ViewComponent resolves templates inside the concepts tree, NOT under `app/views/`. `app/views/` only holds layouts (one per top-level namespace, e.g. `admin.slim`, `crm.slim`, `public.slim`), Devise views, and PWA stubs.
+
+Controllers are thin wrappers that call `endpoint`:
+
+```ruby
+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
+```
+
+The `endpoint` method (defined in `app/controllers/concerns/operations_methods.rb`) runs the operation, extracts `result.model`, and passes it to the component for rendering.
+
+### How `endpoint` dispatches
+
+`endpoint` decides the response based on `action_name` and the response format:
+
+- **`format.html`** — for `index/show/edit/new` it renders the component; for `create/update/destroy` it redirects to `result.redirect_path` or `<controller_name>_path`. Flash from `result.message` / `result.error_message`. On `create/update` failure it re-renders the component with HTTP 422.
+- **`format.js`** — used for Bootstrap modal new/edit dialogs. Renders the component into `#modals` via JS or redirects on success.
+- **`format.json`** — used by select2 search. Returns `result.model.map(&:select2_search_result)` with pagination.
+- **`format.any`** — fallback for auto-submit/null requests.
+
+Component constructor kwargs are derived from `result.model`:
+
+- If `result.model` is an `OpenStruct` — splatted as kwargs (`component.new(**result.model.to_h)`).
+- Otherwise — passed as `<concept>: model` (singular for show/edit/new, pluralized for index), where `<concept>` is the operation's top-level namespace underscored (e.g. `Admin::User::Operation::Index` → `admin: ...`). Keep this naming in sync between operation and component when not using `OpenStruct`.
+
+### `format.js` — Bootstrap modal flow
+
+For new/edit dialogs that should render inside an already-loaded page (no full navigation), submit the form with `data-turbo: false` and let the response come back as JS. `endpoint`'s `format.js` branch:
+
+- **Success on create/update/destroy** → emits `window.location.href = '<path>'`. The browser navigates to `result.redirect_path` (or the `<controller_name>_path` fallback).
+- **Failure / new / edit** → renders the component to a string, hides any currently-open Bootstrap modal, then injects the rendered HTML into `<div id="modals"></div>` and shows it. The injected HTML must contain a `.modal` element at the root.
+
+Required scaffolding on the page:
+
+```slim
+/ in the layout / shared partial
+#modals
+```
+
+```ruby
+/ trigger button
+render ::Base::Component::Btn.new(
+  type: 'add',
+  text: I18n.t('admin.users.new'),
+  path: new_admin_user_path,
+  data: { remote: true, turbo: false }   # request format.js
+)
+```
+
+The component template should wrap content in a Bootstrap modal:
+
+```slim
+.modal.fade tabindex="-1" id="user_modal"
+  .modal-dialog
+    .modal-content
+      .modal-header
+        h5.modal-title = I18n.t('admin.users.new.title')
+        button.btn-close type="button" data-bs-dismiss="modal"
+      .modal-body
+        / form
+```
+
+`escape_javascript` is used to safely interpolate the rendered HTML into the JS response — see `OperationsMethods#endpoint`. Don't bypass it.
+
+### `format.json` — select2 search
+
+The JSON branch is wired for select2 (jQuery select2 with remote data). Operation requirements:
+
+- `result.model` is either a paginated relation OR an `OpenStruct` with a single pluralized key (e.g. `users:`).
+- Each record must implement `#select2_search_result` returning `{ id:, text: }`.
+- Pagination is detected via `respond_to?(:next_page)` (works with kaminari/pagy when configured).
+
+```ruby
+class User
+  def select2_search_result
+    { id: id, text: "#{name} <#{email}>" }
+  end
+end
+```
+
+The response shape:
+
+```json
+{ "result": [{"id": 1, "text": "..."}], "pagination": { "more": true } }
+```
+
+### Sub-operations in detail
+
+`run_operation(OtherOp, params: ..., current_user: ...)` calls another operation, appends its `Result` to `result.sub_results`, and bubbles failures by default:
+
+```ruby
+def perform!(params:, current_user:)
+  self.model = Crm::Property.new(name: params[:property_name])
+  authorize_and_save!
+
+  run_operation(
+    Crm::Property::Operation::Notify,
+    params: params,
+    current_user: current_user
+  )
+  # If the sub-operation fails, its errors are copied onto self and ActiveRecord::RecordInvalid is raised.
+end
+```
+
+To handle sub-operation errors yourself (e.g. swallow them or branch logic), pass `manually_handle_errors: true`:
+
+```ruby
+sub_result = run_operation(
+  OtherOp,
+  params: params,
+  current_user: current_user,
+  manually_handle_errors: true
+)
+
+if sub_result.failure?
+  add_error :base, I18n.t('alerts.partial_failure')
+  invalid!
+end
+```
+
+`result.success?` / `result.failure?` consider the operation's own errors AND every sub-result, so authorization in sub-operations is enforced just like top-level ones.
+
+### When to bypass `endpoint`
+
+Use `endpoint` for every standard CRUD action. There is no `endpoint_partial` or `endpoint_json` helper in this project (yet). For ad-hoc Turbo Frame fragments or JSON endpoints, render directly from the controller and call `check_authorization_is_called(result)` after the operation, OR have the operation `skip_authorize` + `skip_policy_scope` and let the helper observe the flags.
+
+## Operations (`Base::Operation::Base`)
+
+```ruby
+# frozen_string_literal: true
+
+class Admin::User::Operation::Index < Base::Operation::Base
+  include Base::Operation::Sortable
+
+  def perform!(params:, current_user:)
+    self.model = ::OpenStruct.new(users: nil)
+
+    users = policy_scope(User)
+
+    users = apply_sorting(
+      users,
+      params: params,
+      allowed_columns: %i[id name email role created_at],
+      default_column: :id,
+      default_direction: :desc
+    )
+
+    self.model.users = users
+  end
+end
+```
+
+Always use **compact class notation**: `class Feature::Operation::Action < Base::Operation::Base` — never nested `module` blocks.
+
+Key methods available inside operations:
+
+- `authorize!(record, query)` / `policy_scope(scope)` — Pundit authorization (mandatory in every operation; see below)
+- `skip_authorize` / `skip_policy_scope` — bypass auth checks; usually used together
+- `self.model = value` — data passed to component
+- `self.redirect_path = path` — redirect after action (triggers redirect in `endpoint`)
+- `notice(text, level: :notice)` — flash message
+- `add_error(key, message)` / `add_errors(from)` / `invalid!` — failure handling
+- `authorize_and_save!(auth_method = nil)` — `authorize!` then `model.save!` (defaults to `:create?` for new records, `:update?` otherwise)
+- `run_operation(OperationClass, params)` — sub-operations; sub-results bubble failures unless `manually_handle_errors: true`
+
+Result (`Base::Operation::Result` — includes `ActiveModel::Validations`):
+
+- `result.success?` / `result.failure?` — considers `errors`, `model.errors`, and all `sub_results`
+- `result.model` / `result.errors` / `result.message` / `result.message_level` / `result.redirect_path`
+- `result.error_message` — `errors[:base].join(' ')`
+- `result[:key]` — stash extra data via `@result[key] = ...`
+- `invalid!` — force-fail even if no errors are recorded
+
+### `OpenStruct` as model
+
+Use `::OpenStruct` to pass multiple values to a component. `endpoint` spreads its keys as kwargs:
+
+```ruby
+self.model = ::OpenStruct.new(users: paginated, request_params: params)
+
+# component receives:
+def initialize(users:, request_params:)
+```
+
+When a slim template needs request params (search forms, sorting), pass them through the OpenStruct as `request_params:` rather than reaching for `params` inside the component.
+
+## Authorization (Pundit) — MANDATORY
+
+Every operation MUST call one of:
+
+- `authorize!(record, :action?)`
+- `policy_scope(scope)`
+- `skip_authorize` (alone — `OperationsMethods#check_authorization_is_called` already skips `policy_scope` on failure or `[:pundit_scope]`)
+- `authorize_and_save!`
+
+`OperationsMethods#check_authorization_is_called` enforces this after the operation runs by calling `skip_authorization` / `skip_policy_scope` only when the operation set `result[:pundit]` / `result[:pundit_scope]` (or the operation failed). Forgetting to call any of them → `Pundit::AuthorizationNotPerformedError`.
+
+### Policies
+
+Policies live in `app/policies/` and inherit from `ApplicationPolicy`. There are three per-domain base policies — they are also used by `ApplicationController#user_not_authorized` to decide where to redirect on `Pundit::NotAuthorizedError`:
+
+- `Admin::BasePolicy` — `user.admin?`. Denied → `crm_root_path` for non-admin staff, otherwise root.
+- `Crm::BasePolicy` — `user.admin? || user.owner?` (extend with the staff roles your app needs). Denied → root.
+- `Public::BasePolicy` — anonymous-friendly base for unauthenticated layouts.
+
+`Admin::BaseController` runs `Admin::BasePolicy#index?` in a `before_action` to gate the whole namespace.
+
+Policy patterns in this project:
+
+```ruby
+class Crm::PropertyPolicy < Crm::BasePolicy
+  def update?
+    return false unless crm_access?
+    return true if user.admin?
+    return true if user.owner? && record.owner_id == user.id
+
+    false
+  end
+
+  class Scope < Crm::BasePolicy::Scope
+    def resolve
+      return ::Crm::Property.none unless crm_access?
+
+      if user.admin?
+        scope.all
+      elsif user.owner?
+        scope.where(owner_id: user.id)
+      else
+        ::Crm::Property.none
+      end
+    end
+  end
+end
+```
+
+## Components (`Base::Component::Base`)
+
+```ruby
+# frozen_string_literal: true
+
+class Admin::User::Component::Index < Base::Component::Base
+  def initialize(users:)
+    @users = users
+  end
+end
+```
+
+Template at `app/concepts/admin/user/component/index.html.slim`. Components are pure presentation — they receive data via `initialize` and never fetch it themselves.
+
+`Base::Component::Base` exists in this project (`app/concepts/base/component/base.rb`) — it's a thin subclass of `ViewComponent::Base`. Feature components inherit from it. Generic base UI primitives (`Base::Component::Btn`, `Base::Component::Table::Table`) inherit directly from `ViewComponent::Base` because they are imported elsewhere.
+
+Use `::` prefix when referencing other components from namespaced contexts (e.g. `::Base::Component::Btn`).
+
+## Sorting
+
+`Base::Operation::Sortable` provides `apply_sorting(relation, params:, allowed_columns:, default_column:, default_direction:)` for index operations. Always pass an `allowed_columns` allowlist — anything outside it falls back to the default.
+
+```ruby
+include Base::Operation::Sortable
+
+users = apply_sorting(
+  policy_scope(User),
+  params: params,
+  allowed_columns: %i[id name email role created_at],
+  default_column: :id,
+  default_direction: :desc
+)
+```
+
+## Domain model (illustrative — substitute your own)
+
+The examples above assume `User` (Devise-authenticated, with a `role` enum) and a representative business resource (`Crm::Property`). Replace with your domain:
+
+```ruby
+class User < ApplicationRecord
+  enum :role, { admin: 0, owner: 1, customer: 2 }
+  has_many :owned_properties, class_name: "Crm::Property", foreign_key: "owner_id"
+end
+
+class Crm::Property < ApplicationRecord
+  belongs_to :owner, class_name: "User", foreign_key: "owner_id"
+end
+```
+
+Roles in the policy examples (`user.admin?`, `user.owner?`) come from this enum. Customise the role list to fit your access model.
+
+## I18n
+
+Locale files live in `config/locales/`. Default locale and fallbacks are configured in `config/application.rb`. Always use `I18n.t('full.key')` — never `t('.relative_key')` shorthand inside components/operations, since ViewComponent doesn't resolve relative keys the way Action View does.
+
+`ApplicationController#user_not_authorized` reads I18n keys for redirect-on-deny messages (e.g. `authorization.admin_access_denied`, `authorization.crm_access_denied`, `authorization.action_access_denied`). Add those keys to your locale files; see `.claude/docs/i18n.md`.

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

@@ -0,0 +1,96 @@
+# Authentication (Devise)
+
+Auth uses **Devise** with the modules: `:database_authenticatable, :registerable, :recoverable, :rememberable, :validatable` (see `app/models/user.rb`). Lockable / confirmable / trackable / timeoutable / omniauthable are NOT enabled — don't reach for `confirmation_sent_at` etc. unless you also turn them on.
+
+## Routes
+
+```ruby
+# config/routes.rb
+devise_for :users, controllers: { registrations: "users/registrations" }
+```
+
+Only `registrations` is overridden. Sessions and passwords use Devise defaults.
+
+## Permitted parameters
+
+`ApplicationController#configure_permitted_parameters` runs on every Devise request:
+
+```ruby
+devise_parameter_sanitizer.permit(:sign_up, keys: [:name, :role])
+devise_parameter_sanitizer.permit(:account_update, keys: [:name, :role])
+```
+
+When you add a new column the user can edit, add it to both `:sign_up` and `:account_update`.
+
+## Custom registration flow (optional)
+
+If your app needs a richer sign-up — for example, atomically creating a related resource (an organisation, a tenant, a profile) when a user picks the "owner" role — override Devise's `RegistrationsController`:
+
+```ruby
+# config/routes.rb
+devise_for :users, controllers: { registrations: "users/registrations" }
+```
+
+```ruby
+# app/controllers/users/registrations_controller.rb
+class Users::RegistrationsController < Devise::RegistrationsController
+  def create
+    ActiveRecord::Base.transaction do
+      build_resource(sign_up_params)
+      resource.save || (raise ActiveRecord::Rollback)
+      # create related records here, then promote roles if needed
+    end
+    super
+  end
+end
+```
+
+Why a transaction: cross-record validations ("owner must have a related X" + "X must have an owner") create a chicken-and-egg. A transaction lets you save the User first as a base role, build dependents inside the same transaction (with `save(validate: false)` for the inner record), then promote the User and re-validate everything at commit.
+
+## Where redirects go after sign-up
+
+```ruby
+def after_sign_up_path_for(resource)
+  resource.owner? ? crm_root_path : super
+end
+```
+
+Override `after_sign_up_path_for` only if a specific role needs a non-default landing page. Otherwise Devise's default (`stored_location_for(resource) || root_path`) is correct.
+
+## Sign-out / unauthorized redirects
+
+Pundit failures route through `ApplicationController#user_not_authorized` — see `routing-and-namespaces.md` for the redirect matrix.
+
+## I18n
+
+Devise strings live in `config/locales/devise.<locale>.yml` (separate from your app locales). The custom-flow flash messages use:
+
+- `set_flash_message! :notice, :signed_up` — Devise's standard key
+- `I18n.t("authorization.admin_access_denied" | "crm_access_denied" | "action_access_denied")` — defined in your app locales
+
+When you add a new flash, decide: Devise-flow → `devise.<locale>.yml`; app-flow → your app locales.
+
+## Stubbing auth in tests
+
+```ruby
+# Controller spec
+before do
+  allow(controller).to receive(:authenticate_user!).and_return(true)
+  allow(controller).to receive(:current_user).and_return(user)
+end
+
+# Operation spec — pass current_user explicitly
+described_class.call(params: params, current_user: build(:user, :owner)  # adjust trait to match your factories)
+```
+
+For request specs, `sign_in(user)` works (Devise test helpers are loaded via `rails_helper`).
+
+## Adding new fields
+
+Steps when adding a new attribute users can set during sign-up or edit:
+
+1. Migration → add column.
+2. Model → validation if needed.
+3. `ApplicationController#configure_permitted_parameters` → add the attribute to `:sign_up` and/or `:account_update`.
+4. Devise views (`app/views/devise/...`) → add the field to the form.
+5. Locales → add the label/placeholder to `devise.<locale>.yml` and your app locales.

data/lib/generators/tsykvas_rails_template/install/templates/.claude/docs/background-jobs.md

@@ -0,0 +1,135 @@
+# Background Jobs (SolidQueue)
+
+The app uses **SolidQueue** (database-backed Active Job adapter) with a dedicated queue database. There are no jobs yet — `app/jobs/` only contains `application_job.rb`. This doc fixes conventions before the first real job lands.
+
+## Configuration
+
+```
+config/queue.yml         # Worker / dispatcher config
+config/recurring.yml     # Cron-style recurring tasks
+db/queue_schema.rb       # Schema for the queue database
+```
+
+`config/queue.yml` (default workers):
+
+- 1 dispatcher, polling every 1s, batch size 500.
+- Workers process all queues (`*`), 3 threads each, polling every 0.1s.
+- Process count via `JOB_CONCURRENCY` env var (default 1).
+
+`config/recurring.yml` already schedules:
+
+```yaml
+production:
+  clear_solid_queue_finished_jobs:
+    command: "SolidQueue::Job.clear_finished_in_batches(sleep_between_batches: 0.3)"
+    schedule: every hour at minute 12
+```
+
+In production deploys (Kamal), SolidQueue runs **inside Puma** via `SOLID_QUEUE_IN_PUMA=true` (set in `config/deploy.yml`). When traffic grows, split it onto a dedicated job server.
+
+## Where jobs live
+
+```
+app/jobs/
+  application_job.rb              # Base class (queue_as :default by default)
+  <namespace>/<feature>_job.rb    # Feature-specific jobs, mirroring app/concepts naming
+```
+
+For feature-scoped jobs prefer `app/jobs/<namespace>/<job>.rb` (e.g. `app/jobs/crm/property/cleanup_job.rb`). Don't put them inside `app/concepts/` — jobs are infrastructure, not part of the request/operation cycle.
+
+## Naming & class layout
+
+```ruby
+# app/jobs/crm/property/cleanup_job.rb
+# frozen_string_literal: true
+
+class Crm::Property::CleanupJob < ApplicationJob
+  queue_as :default
+
+  def perform(property_id)
+    property = Crm::Property.find_by(id: property_id)
+    return if property.nil?
+
+    Crm::Property::Operation::Cleanup.call(
+      params: { property_id: property.id },
+      current_user: nil
+    )
+  end
+end
+```
+
+Rules:
+
+- Always `# frozen_string_literal: true`.
+- `queue_as :default` unless you have a specific reason (e.g. `:background` for non-time-sensitive bulk work).
+- **Pass IDs, not AR objects** — by the time the job runs, the record may be gone.
+- **Idempotent perform** — workers retry on failure, and recurring tasks may overlap.
+- Delegate real logic to an Operation (`<Feature>::Operation::<Action>`). The job is a thin wrapper that pulls IDs and calls the operation, NOT a place for business logic.
+- Set `retry_on` / `discard_on` for known failures (e.g. `discard_on ActiveJob::DeserializationError` for missing records).
+
+## Calling from an operation
+
+```ruby
+# Inside Operation#perform!
+Crm::Property::CleanupJob.perform_later(model.id)
+```
+
+For tests, prefer `perform_later` + assert enqueued (see below); use `perform_now` only if you want sync execution.
+
+## Recurring tasks
+
+Add new entries to `config/recurring.yml` under the `production:` key (or `default:` if you want them to run in dev too):
+
+```yaml
+production:
+  daily_archive:
+    class: Crm::Archive::DailyJob
+    queue: background
+    schedule: every day at 3am
+
+  cleanup:
+    command: "Crm::Stale.delete_all"
+    schedule: every hour at minute 12
+```
+
+Use `class:` for jobs that take no arguments; use `command:` for one-off Ruby snippets. Provide a unique top-level key for each task.
+
+## Testing
+
+```ruby
+# rails_helper.rb already loads ActiveJob test helpers.
+RSpec.describe Crm::Property::CleanupJob do
+  let(:property) { create(:property) }
+
+  it 'enqueues with the property id' do
+    expect {
+      described_class.perform_later(property.id)
+    }.to have_enqueued_job.with(property.id).on_queue('default')
+  end
+
+  it 'calls the cleanup operation' do
+    op_double = class_double(Crm::Property::Operation::Cleanup, call: nil)
+    stub_const('Crm::Property::Operation::Cleanup', op_double)
+
+    described_class.perform_now(property.id)
+
+    expect(op_double).to have_received(:call).with(
+      params: { property_id: property.id }, current_user: nil
+    )
+  end
+end
+```
+
+When testing operations that enqueue jobs:
+
+```ruby
+expect { result }.to have_enqueued_job(Crm::Property::CleanupJob).with(property.id)
+```
+
+## Anti-patterns
+
+- ❌ Passing AR objects: `MyJob.perform_later(user)` → fragile across deserialization. Use `user.id`.
+- ❌ Business logic in `perform` — keep it in an Operation.
+- ❌ Long-running synchronous calls inside `Operation#perform!` — push them to a job.
+- ❌ Skipping `retry_on`/`discard_on` — defaults will retry forever.
+- ❌ Using `:default` queue for everything when some work is genuinely lower-priority — split queues so a backlog of slow tasks doesn't starve fast ones.

data/lib/generators/tsykvas_rails_template/install/templates/.claude/docs/code-style.md

@@ -0,0 +1,101 @@
+# Code Style
+
+## Ruby / Rails
+
+- `# frozen_string_literal: true` on the first line of every Ruby file under `app/` and `spec/`.
+- RuboCop is `rubocop-rails-omakase` (see `.rubocop.yml`). Run with `bin/rubocop` and autocorrect via `bin/rubocop -A`.
+- Compact class notation: `class Feature::Operation::Action < Base::Operation::Base`. Never nested `module` blocks.
+- Business logic belongs in operations under `app/concepts/<...>/operation/`. Controllers are `endpoint Op, Component` one-liners; models hold validations/associations only.
+- Trailing commas in multi-line arrays and hashes (Omakase enforces it).
+- Use `Time.zone.parse(...)` rather than `DateTime.parse(...)` (Rails timezone-aware).
+
+## I18n
+
+- Default locale is set in `config/application.rb`. Every locale file under `config/locales/` must be kept in sync (mirror the same keys).
+- Always `I18n.t('full.key')` in operations and components — never `t('key')` or `t('.relative_key')` shorthand.
+- Devise strings are split into `config/locales/devise.en.yml`.
+
+## ViewComponent / Slim
+
+- View component path is `app/concepts/` (`config/initializers/view_component.rb`). Templates live next to the `.rb` file: `app/concepts/<ns>/<feature>/component/<action>.html.slim`. (ViewComponent 4.8+ requires the explicit `.html.` prefix; Rails layouts under `app/views/layouts/` keep the bare `.slim` extension.)
+- Feature components inherit from `Base::Component::Base`; generic base primitives (`Btn`, `Table`) inherit from `ViewComponent::Base`.
+- Use `::Base::Component::Btn` (with `::` prefix) when referencing components from namespaced contexts.
+- Templates: keep logic minimal — push Ruby into the component `.rb` file. Slim auto-escapes; never use `==`/`raw`/`html_safe` on user input.
+
+## Forms
+
+- Use `simple_form_for` (gem `simple_form`). Forms must call it via `helpers.simple_form_for` inside ViewComponents:
+
+  ```slim
+  = helpers.simple_form_for @model, url: some_path, method: :post do |f|
+  ```
+
+- New/Edit pattern: extract a shared `Form` component; create distinct `New`/`Edit` subclasses (for breadcrumbs/title differences).
+- On validation failure inside an operation: `add_error :base, message` + `invalid!` and re-`self.model = ...`. `endpoint` will re-render with 422.
+
+## File layout cheatsheet
+
+```
+app/concepts/<namespace>/<feature>/
+  operation/<action>.rb    # business logic, must call authorize!/policy_scope/skip_authorize
+  component/<action>.rb    # ViewComponent::Base subclass
+  component/<action>.html.slim  # template
+```
+
+Mirror the same structure under `spec/concepts/...` for tests.
+
+# Anti-patterns checklist
+
+Real examples of patterns that show up in code reviews. The ✅ side is what to write.
+
+## Operations / Controllers
+
+- ❌ AR queries in controllers → ✅ controller is `endpoint Op, Component`; queries live in the operation.
+- ❌ `if/else` flow control in controllers → ✅ branch inside the operation; let `endpoint` handle redirect vs render.
+- ❌ Forgetting Pundit (`Pundit::AuthorizationNotPerformedError` at runtime) → ✅ every operation calls `authorize!` / `policy_scope` / `skip_authorize` / `authorize_and_save!`.
+- ❌ Nested module blocks (`module Admin; class User; ...`) → ✅ compact: `class Admin::User::Operation::Index < Base::Operation::Base`.
+- ❌ Business logic in `before_save` callbacks → ✅ run it inside the operation that mutates the record.
+- ❌ `params.permit!` / `params.to_unsafe_h` → ✅ explicit `params.require(:user).permit(:name, :email, ...)`.
+
+## Components / Views
+
+- ❌ AR queries inside a ViewComponent → ✅ data only via `initialize`; operation loads it.
+- ❌ Reading `helpers.params` inside a component → ✅ pass through `OpenStruct` as `request_params:`.
+- ❌ `==`, `raw`, `html_safe` on user input → ✅ trust Slim's auto-escape; if you need HTML, sanitize via Rails' `sanitize` helper with an allowlist.
+- ❌ Inline literal strings in templates → ✅ `I18n.t('full.key')` with mirrors in every locale you ship.
+- ❌ `t('.relative_key')` shorthand → ✅ `I18n.t('full.key')`. ViewComponent's lookup path makes relative keys unreliable.
+- ❌ Raw `<form>` or `form_with` → ✅ `helpers.simple_form_for` (see `forms.md`).
+- ❌ Raw `<button>`/`<a class="btn ...">` → ✅ `render ::Base::Component::Btn.new(...)`.
+- ❌ Hand-rolled `<table>` for collections → ✅ `Base::Component::Table::Table` with `add_column`.
+- ❌ Top-level constant references (e.g. `Base::Component::Btn`) inside another component → ✅ `::Base::Component::Btn.new(...)`. Without `::` Ruby's lookup falls through `ViewComponent::Base::Component` and crashes at render time.
+
+## Visual / design-system
+
+See `design-system.md` for the full token set + component catalog. Frequent traps:
+
+- ❌ Hardcoded hex literals (`#0d6efd`) in component templates → ✅ design-system tokens (`var(--bs-primary)` or your own SCSS variable).
+- ❌ Hardcoded `box-shadow` / `border-radius` values per component → ✅ shared `--bs-border-radius`, `--bs-box-shadow` tokens.
+- ❌ Hardcoded `font-family` overrides per component → ✅ inherit from the cascade; set fonts once in your stylesheet entry.
+- ❌ `class="bg-primary text-white text-center fw-bold p-3"` repeated everywhere → ✅ extract a small SCSS utility class or component partial.
+- ❌ `active_nav_class('/crm')` for a dashboard link (matches every CRM page) → ✅ `active_nav_class('/crm', '/crm/dashboard', exact: true)`.
+- ❌ Hardcoded brand strings (year, tagline, copyright) in templates → ✅ `I18n.t('ui.brand.year' / 'ui.brand.tagline')`.
+
+## Time / dates
+
+- ❌ `Time.now`, `DateTime.parse(...)`, `Date.today` → ✅ `Time.zone.now`, `Time.zone.parse(...)`, `Date.current` (timezone-aware, honors `config.time_zone`).
+- ❌ Hardcoded format strings repeated everywhere → ✅ `Base::Component::Table::Table#format_date`, or register in `config/locales/*.yml` under `date.formats.*`.
+
+## Tests
+
+- ❌ `FactoryBot.create(...)` → ✅ shorthand `create(...)` (FactoryBot syntax included globally).
+- ❌ Hardcoded fixtures (`email: "test@test.com"`) → ✅ `Faker::Internet.unique.email`.
+- ❌ `double` when an interface exists → ✅ `instance_double(SomeClass)`.
+- ❌ `expect(x).to receive(:y)` in `before` → ✅ `allow` + `have_received` after the call.
+- ❌ Skipping the Pundit-failure test for an operation → ✅ always cover both happy and `Pundit::NotAuthorizedError` paths.
+
+# Git Workflow
+
+- Commit messages in **imperative present tense** ("Add feature", not "Added feature"), under 72 chars.
+- Default branch is `main`. Feature branches PR into `main`.
+- Before requesting review: run `bin/rubocop`, `bundle exec rspec`, and `bin/brakeman --no-pager` (all three are part of CI).
+- Never force-push to `main`.

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

@@ -0,0 +1,34 @@
+# Commands
+
+## Development
+
+```bash
+bin/setup                           # bundle install + db:prepare + start dev
+bin/dev                             # foreman: rails server + dartsass:watch (Procfile.dev)
+bin/rails db:prepare                # create + migrate (or load schema)
+bin/rails zeitwerk:check            # autoloading sanity check
+```
+
+## Tests
+
+```bash
+bundle exec rspec                                       # full suite
+bundle exec rspec spec/path/to/file_spec.rb             # single file
+bundle exec rspec spec/path/to/file_spec.rb:42          # single example by line
+bundle exec rspec --tag focus                           # by tag
+```
+
+## Linting & security
+
+```bash
+bin/rubocop                         # style check (rubocop-rails-omakase)
+bin/rubocop -A                      # autocorrect all safe offenses
+bin/brakeman --no-pager             # static security analysis
+bin/importmap audit                 # JS dependency audit
+```
+
+CI (`.github/workflows/ci.yml`) runs **brakeman + importmap audit + rubocop + rspec** against PostgreSQL 16.
+
+## Deploy
+
+This app uses **Kamal** (`config/deploy.yml`). `bin/kamal deploy` for production deploys; managed by the project owner.