tsykvas_rails_template 0.1.0

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

@@ -0,0 +1,165 @@
+# I18n
+
+Default locale and fallbacks are configured in `config/application.rb`. Time zone is configured there too. All UI strings must come from locale files — no inline literals in components or operations.
+
+## Locale files
+
+```
+config/locales/
+  en.yml                # Application strings (one file per locale you ship)
+  devise.en.yml         # Devise built-in strings (sign-up, errors, mailer, ...) — one per locale
+  simple_form.en.yml    # simple_form built-in strings (required mark, error notification, ...) — one per locale
+```
+
+**Rule:** every key must exist in every locale file. They are mirrors. CI does not enforce this — be diligent.
+
+When you add a Devise- or simple_form-specific override, put it in the matching `<gem>.<locale>.yml`. Don't mix them with app strings in your main locale files.
+
+## The full-key rule
+
+Always reference the full I18n key — never the relative `t('.foo')` shorthand:
+
+```ruby
+# ✅ good
+I18n.t('admin.users.index.title')
+I18n.t('crm.property.edit.submit')
+
+# ❌ bad
+t('.title')             # only resolves with conventional view paths; ViewComponents don't follow them
+t('admin.users.title')  # under-qualified — collisions across domains
+```
+
+This applies in operations, components, slim templates, controllers — everywhere. The reason: ViewComponent's lookup path differs from regular Rails views, so `t('.relative_key')` is unreliable.
+
+## Key structure
+
+Top-level: domain (`admin`, `crm`, `public`, `forms`, `notices`, `alerts`, `authorization`, `simple_form`).
+Below that: feature → action → label.
+
+```yaml
+en:
+  admin:
+    users:
+      index:
+        title: "Users"
+        table:
+          id: "ID"
+          email: "Email"
+          role: "Role"
+      delete:
+        confirm: "Are you sure?"
+
+  crm:
+    property:
+      edit:
+        title: "Edit property"
+        name: "Name"
+        name_placeholder: "Enter a name..."
+        submit: "Save"
+
+  notices:
+    created: "Created"
+    updated: "Updated"
+    deleted: "Deleted"
+
+  alerts:
+    failed: "Failed"
+    resource_not_found: "Record not found"
+
+  authorization:
+    admin_access_denied: "Access denied"
+    crm_access_denied: "CRM access denied"
+    action_access_denied: "Action not allowed"
+```
+
+## simple_form conventions
+
+`simple_form` reads labels, placeholders, and hints by convention:
+
+```yaml
+en:
+  simple_form:
+    labels:
+      property:
+        name: "Name"
+    placeholders:
+      property:
+        name: "Enter a name..."
+    hints:
+      property:
+        name: "Public name."
+```
+
+With these in place, `f.input :name` auto-populates label + placeholder + hint. **Prefer this over inline `f.input :name, label: ..., placeholder: ...`** — see `forms.md`.
+
+## Pluralization
+
+```yaml
+en:
+  reports:
+    count:
+      one: "%{count} report"
+      other: "%{count} reports"
+```
+
+Use `I18n.t('reports.count', count: n)`. For locales with multiple plural forms (e.g. `one`/`few`/`many`/`other` in Slavic languages), include each form your target locales require — see the [Rails I18n plural rules](https://guides.rubyonrails.org/i18n.html#pluralization).
+
+## Time zone & date formatting
+
+- App-wide time zone: set in `config/application.rb`.
+- Always use `Time.zone.parse(...)`, `Time.zone.now`, `Date.current` — never `DateTime.parse` or `Time.now`.
+- For display, prefer `Base::Component::Table::Table#format_date`.
+
+For custom date formats, register them in the locale file:
+
+```yaml
+en:
+  date:
+    formats:
+      default: "%Y-%m-%d"
+      long: "%B %-d, %Y"
+```
+
+Then `I18n.l(date, format: :long)`.
+
+## Authorization-denied messages
+
+`ApplicationController#user_not_authorized` reads three keys:
+
+- `authorization.admin_access_denied`
+- `authorization.crm_access_denied`
+- `authorization.action_access_denied`
+
+Every locale you ship must define all three.
+
+## UI / design-system strings
+
+Brand- or design-system strings (sidebar section titles, taglines, navigational labels) belong in their own top-level namespace so the design layer stays decoupled from feature copy:
+
+```yaml
+ui:
+  sections:
+    workspace: "..."
+    account: "..."
+    administration: "..."
+```
+
+Reference via `I18n.t('ui.sections.workspace')`. Typographic constants that should never be translated (e.g. brand year markers) belong here too — keep them identical across all locales.
+
+See [`design-system.md`](design-system.md) for the visual context behind these strings.
+
+## Adding a new translation
+
+1. Add the key to your default-locale YAML under the right namespace.
+2. Mirror it in every other locale you ship.
+3. Reference it via `I18n.t('full.key')`.
+4. If it's a `simple_form` label/placeholder/hint, follow the simple_form convention so it's picked up automatically.
+
+## Anti-patterns
+
+- ❌ `t('.title')` — relative keys break in ViewComponent.
+- ❌ Inline strings in components or slim templates.
+- ❌ Adding a key only to one locale — fallback must work.
+- ❌ Using `DateTime.parse` / `Time.now` instead of `Time.zone.*`.
+- ❌ Mixing Devise/simple_form strings into your app locale files.
+- ❌ Deep nesting beyond 4 levels — split into a sibling top-level key instead.

data/lib/generators/tsykvas_rails_template/install/templates/.claude/docs/routing-and-namespaces.md

@@ -0,0 +1,114 @@
+# Routing & Namespaces
+
+This app is split into three top-level domains. Each has its own URL namespace, layout, base controller, and base policy. Read this before adding a new controller — placement is not optional.
+
+## Domain → namespace map
+
+| Domain | URL prefix | Layout | Base controller | Base policy | Concepts root |
+|---|---|---|---|---|---|
+| **Admin** (administrators) | `/admin/...` | `app/views/layouts/admin.slim` | `Admin::BaseController` | `Admin::BasePolicy` (`user.admin?`) | `app/concepts/admin/` |
+| **CRM** (business users) | `/crm/...` | `app/views/layouts/crm.slim` | `Crm::BaseController` | `Crm::BasePolicy` (admin / owner / employee / manager) | `app/concepts/crm/` |
+| **Screener** (end consumers) | `/` (root) and `/screener/...` | `app/views/layouts/screener.slim` | `Screener::BaseController` | `Screener::BasePolicy` | `app/concepts/screener/` (not yet created — first feature in this domain creates it) |
+
+Each `BaseController` runs a `before_action` that instantiates its `BasePolicy` with `current_user, nil` and raises `Pundit::NotAuthorizedError` if `policy.index?` is false. `ApplicationController#user_not_authorized` then dispatches the redirect:
+
+| Policy class on the exception | Where the user is sent |
+|---|---|
+| `Admin::BasePolicy` | `crm_root_path` if owner/employee/manager, else `root_path` |
+| `Crm::BasePolicy` | `crm_root_path` for crm-eligible users, else `root_path` |
+| `Screener::BasePolicy` | `crm_root_path` |
+| anything else | `redirect_back(fallback_location: root_path)` |
+
+The redirect hinges on the **policy class name**, so keep `<Domain>Policy < <Domain>::BasePolicy` intact when you add new policies.
+
+## Adding a controller
+
+1. Inherit from the matching base controller — never from `ApplicationController` directly.
+2. Mount under the matching `namespace` block in `config/routes.rb`.
+3. Place operations + components under `app/concepts/<namespace>/<feature>/`.
+4. Each action is a one-liner: `endpoint Op, Component` (see `concepts-refactoring.md`).
+
+```ruby
+# config/routes.rb
+namespace :crm do
+  resources :reports, only: [:index, :show]
+end
+
+# app/controllers/crm/reports_controller.rb
+class Crm::ReportsController < Crm::BaseController
+  def index
+    endpoint Crm::Report::Operation::Index, Crm::Report::Component::Index
+  end
+end
+```
+
+## Custom (non-`resources`) routes
+
+Some flows don't map cleanly to REST — for example `Crm::PropertyController#edit` uses a singular path with no `id` (an owner edits *their* property):
+
+```ruby
+namespace :crm do
+  get "property/edit", to: "property#edit", as: :edit_property
+end
+```
+
+Use a custom path when:
+- the resource is implicitly the current user's (no id needed), OR
+- the action name doesn't fit `index/show/new/create/edit/update/destroy` (e.g. `archive_property`, `confirm`, `archive`).
+
+`endpoint` handles non-standard action names automatically: if the operation sets `self.redirect_path`, it redirects; otherwise it renders the component.
+
+## How `endpoint` derives the redirect target
+
+After a successful `create` / `update` / `destroy` (or any action name containing `destroy`), `endpoint` redirects to:
+
+```ruby
+result.redirect_path || public_send("#{controller_name}_path")
+```
+
+Two consequences:
+
+1. **Set `self.redirect_path` explicitly** for non-trivial cases. The fallback only works if a route helper exists with the exact name `<controller_name>_path`.
+2. **Controller name matters.** `Crm::propertiesController` falls back to `properties_path`, NOT `crm_properties_path`. If your controller's pluralized name doesn't match a route helper, you must set `self.redirect_path`.
+
+## Named route helpers (cheat-sheet)
+
+- `root_path` → `Screener::HomeController#index` (public landing)
+- `screener_root_path` → same controller, namespaced URL
+- `admin_root_path` → `Admin::DashboardController#index`
+- `crm_root_path` → `Crm::DashboardController#index`
+- `crm_edit_property_path` → `Crm::PropertyController#edit`
+- `new_user_session_path` / `destroy_user_session_path` — Devise sign-in/out
+- `new_user_registration_path` / `user_registration_path` — Devise sign-up (uses `Users::RegistrationsController`)
+- `rails_health_check_path` → `/up` (uptime probes)
+
+When linking from an operation, prefer route helpers via `Rails.application.routes.url_helpers`:
+
+```ruby
+self.redirect_path = Rails.application.routes.url_helpers.crm_root_path
+```
+
+## Devise routes
+
+```ruby
+devise_for :users, controllers: { registrations: "users/registrations" }
+```
+
+Only `registrations` is overridden — see `authentication.md` for the custom sign-up flow. Other Devise controllers (sessions, passwords) use defaults.
+
+## What lives where
+
+```
+config/routes.rb                # All routes — keep namespaced
+app/controllers/
+  application_controller.rb     # Pundit + OperationsMethods + redirect dispatch
+  admin/base_controller.rb      # layout + Admin::BasePolicy gate
+  crm/base_controller.rb        # layout + Crm::BasePolicy gate
+  screener/base_controller.rb   # layout + Screener::BasePolicy gate
+  users/registrations_controller.rb  # custom Devise sign-up
+app/policies/
+  application_policy.rb         # Pundit baseline
+  admin/base_policy.rb
+  crm/base_policy.rb
+  screener/base_policy.rb
+```

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

@@ -0,0 +1,122 @@
+# Security
+
+Defaults Rails 8.1 ships with, plus a few project-specific settings. Run `bin/brakeman --no-pager` before opening a PR — it's part of CI.
+
+## Authorization
+
+**Pundit** is mandatory in every operation. `OperationsMethods#check_authorization_is_called` enforces this — any operation that doesn't call one of `authorize!` / `policy_scope` / `skip_authorize` / `authorize_and_save!` raises `Pundit::AuthorizationNotPerformedError` after the operation runs.
+
+See `architecture.md` for the full Pundit setup. Per-domain base policies (`Admin::BasePolicy`, `Crm::BasePolicy`, `Screener::BasePolicy`) gate entire namespaces via the `BaseController#before_action`.
+
+## Parameter filtering
+
+`config/initializers/filter_parameter_logging.rb`:
+
+```ruby
+Rails.application.config.filter_parameters += [
+  :passw, :email, :secret, :token, :_key, :crypt, :salt,
+  :certificate, :otp, :ssn, :cvv, :cvc
+]
+```
+
+`:passw` is a partial match (covers `password`, `password_confirmation`, ...). `:email` is filtered out of logs to satisfy data-protection norms — be aware that even server logs won't show emails.
+
+When you add a new sensitive attribute, add the matching token here.
+
+## Content Security Policy
+
+`config/initializers/content_security_policy.rb` is currently **commented out** (Rails default). When you enable it for production:
+
+```ruby
+Rails.application.configure do
+  config.content_security_policy do |policy|
+    policy.default_src :self, :https
+    policy.script_src  :self, :https, :unsafe_inline  # only if needed for importmap nonces
+    policy.style_src   :self, :https
+    policy.img_src     :self, :https, :data
+    policy.font_src    :self, :https, :data
+    policy.object_src  :none
+  end
+
+  config.content_security_policy_nonce_generator = ->(req) { req.session.id.to_s }
+  config.content_security_policy_nonce_directives = %w[script-src style-src]
+end
+```
+
+Then audit Stimulus controllers and Bootstrap usage for inline scripts/styles that need nonces.
+
+## CSRF
+
+Rails default — `protect_from_forgery with: :exception` is implicit in `ActionController::Base`. Devise + Turbo handle the token automatically. **Don't** disable CSRF on a controller unless it's a webhook endpoint, in which case use a different authentication mechanism (signature verification).
+
+## XSS
+
+- Slim auto-escapes by default. `==` and `raw` and `html_safe` bypass it — never use them on user input.
+- ViewComponents render via Slim, so the same rule applies.
+- `escape_javascript` is used in `OperationsMethods#endpoint`'s `format.js` branch when injecting modal HTML — keep that helper in any new JS-response code that interpolates a string.
+
+## SQL injection
+
+- ActiveRecord query methods (`where`, `joins`) auto-escape when given hashes / arrays. Never interpolate user input into raw SQL: prefer `where("name LIKE ?", "%#{q}%")` (parameterized) over `where("name LIKE '%#{q}%'")`.
+- For `order(...)`, user-controlled column names are dangerous — use the `Base::Operation::Sortable#apply_sorting` helper, which validates against an `allowed_columns` allowlist.
+
+## Browser support
+
+`ApplicationController` calls `allow_browser versions: :modern`. Old browsers receive a 426 page. This is intentional: it lets us assume modern JS / CSS and simplifies CSP and Hotwire support.
+
+## Devise modules currently enabled
+
+`:database_authenticatable, :registerable, :recoverable, :rememberable, :validatable`.
+
+NOT enabled (and probably should be, eventually):
+
+- `:lockable` — lock account after N failed attempts (sensible to add).
+- `:trackable` — record sign-in count / IP / timestamps.
+- `:confirmable` — email confirmation.
+- `:timeoutable` — auto-logout after inactivity.
+
+Adding any of these requires a migration (see Devise docs) plus enabling them in `User`.
+
+## Brakeman
+
+`bin/brakeman --no-pager` runs in CI. If it flags something:
+
+1. Fix the underlying issue if possible.
+2. If it's a false positive, document why with a comment and add an inline ignore (`# brakeman:ignore`) — but prefer fixes over ignores.
+
+## importmap audit
+
+`bin/importmap audit` runs in CI and flags JS dependencies with known CVEs. Pinned via `config/importmap.rb`.
+
+## Mass assignment
+
+Use **strong parameters** in operations:
+
+```ruby
+def perform!(params:, current_user:)
+  attrs = params.require(:property).permit(:name, :description)
+  self.model = Crm::Property.new(attrs)
+  authorize_and_save!
+end
+```
+
+Never `params.permit!` or `params.to_unsafe_h` unless you have a *very* specific reason and a comment explaining it.
+
+## Webhook / unauthenticated endpoints
+
+There are none in the project right now. When the first one lands:
+
+- Skip Devise: `skip_before_action :authenticate_user!`
+- Skip CSRF: `protect_from_forgery with: :null_session, only: [:webhook]`
+- Verify the request signature (HMAC, JWT, etc.) inside the operation.
+- `skip_authorize` only after signature verification passes — and document why.
+
+## Anti-patterns
+
+- ❌ Skipping authorization in operations (`skip_authorize` without a comment explaining why).
+- ❌ Building SQL with string interpolation.
+- ❌ `params.permit!` / `params.to_unsafe_h`.
+- ❌ `==` / `raw` / `html_safe` in Slim or ViewComponent templates on anything user-controlled.
+- ❌ `before_action :skip_authorization` on an entire controller.
+- ❌ Logging request bodies that contain unfiltered sensitive data.
+- ❌ Using `find_by_sql` with interpolated input.

data/lib/generators/tsykvas_rails_template/install/templates/.claude/docs/stimulus-controllers.md

@@ -0,0 +1,166 @@
+# Stimulus Controllers
+
+All JavaScript interactivity uses **Hotwire Stimulus**. Controllers live in `app/javascript/controllers/`.
+
+## File naming & registration
+
+Controllers are auto-loaded via `eagerLoadControllersFrom` (`app/javascript/controllers/index.js`) — **no manual registration needed**.
+
+- `controllers/dropdown_controller.js` → identifier `dropdown`
+- `controllers/navbar_controller.js` → identifier `navbar`
+- `controllers/some_feature/loader_controller.js` → identifier `some-feature--loader`
+
+Rules:
+
+- Filename: `snake_case_controller.js`
+- Underscores → hyphens in the identifier
+- Subdirectory separator → `--` in the identifier
+- Group related controllers in a subdirectory
+
+## Controller structure
+
+```js
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["input", "result"]
+  static values  = { delay: { type: Number, default: 300 } }
+
+  connect() {
+    // called when element is added to DOM
+  }
+
+  disconnect() {
+    // clean up any external event listeners here
+  }
+}
+```
+
+Always `export default class extends Controller` — never name the class.
+
+## Targets, values, outlets
+
+- **targets** — DOM references; auto-generates `this.inputTarget`, `this.inputTargets`, `this.hasInputTarget`
+- **values** — reactive typed properties; use typed defaults: `{ type: String, default: 'all' }`
+- **outlets** — cross-controller communication (rare; prefer Turbo events)
+
+Use `this.has*Target` guard before accessing optional targets:
+
+```js
+if (this.hasLoaderTarget) {
+  this.loaderTarget.style.display = 'none'
+}
+```
+
+## Event listeners on `document` / outside the element
+
+Use **arrow-function class fields** so `this` is preserved, and **always remove them in `disconnect()`**:
+
+```js
+connect() {
+  document.addEventListener("turbo:submit-start", this.handleSubmitStart)
+}
+
+disconnect() {
+  document.removeEventListener("turbo:submit-start", this.handleSubmitStart)
+}
+
+handleSubmitStart = (event) => {
+  if (this.element.contains(event.target)) { ... }
+}
+```
+
+Never add document-level listeners with `.bind(this)` in `connect()` — the bound function is a new reference each call, so you can't `removeEventListener` it. (Existing controllers like `dropdown_controller.js` use `this.boundXxx = handler.bind(this)` and store the reference; that works too — but arrow-function class fields are simpler.)
+
+Always scope handlers to `this.element.contains(event.target)` to avoid reacting to other frames/forms.
+
+## Turbo integration
+
+Useful Turbo lifecycle events:
+
+- `turbo:load` / `turbo:render` — page navigated
+- `turbo:submit-start` / `turbo:submit-end` — form submission
+- `turbo:before-fetch-request` — any Turbo fetch starts
+- `turbo:frame-load` — Turbo Frame finished loading
+
+## Bootstrap integration
+
+Bootstrap is loaded globally and exposed as `window.bootstrap`:
+
+```js
+new window.bootstrap.Modal(this.element).show()
+new window.bootstrap.Tooltip(this.element)
+window.bootstrap.Dropdown.getInstance(this.element)
+```
+
+No import needed.
+
+## Passing data from Rails to Stimulus
+
+Use `data-*-value` attributes for scalar values and `data-*-param` on action elements:
+
+```slim
+div data-controller="users-search"
+    input data-action="input->users-search#search" data-users-search-target="input"
+    button data-action="click->users-search#clear" data-users-search-default-param="all"
+```
+
+```js
+search() { this.fetchResults(this.inputTarget.value) }
+
+clear({ params: { default: defaultValue } }) {
+  this.inputTarget.value = defaultValue || ''
+}
+```
+
+## Debouncing
+
+```js
+connect() { this.timeout = null }
+
+search() {
+  clearTimeout(this.timeout)
+  this.timeout = setTimeout(() => this.performSearch(), this.delayValue)
+}
+
+disconnect() { clearTimeout(this.timeout) }
+```
+
+## What belongs in a Stimulus controller vs. elsewhere
+
+- UI interactivity (show/hide, toggle, debounce, modals) — Stimulus
+- Fetching data / form submissions — Turbo (frames, streams); controllers only trigger or react
+- Application-wide state / complex logic — keep minimal; split into focused controllers
+- Third-party widget init (Bootstrap, etc.) — `connect()` / `disconnect()` lifecycle
+
+Keep controllers small and single-purpose.
+
+## Existing controllers (reference)
+
+| File | Identifier | Purpose |
+|---|---|---|
+| `application.js` | — | Stimulus app bootstrap |
+| `index.js` | — | `eagerLoadControllersFrom` registration |
+| `dropdown_controller.js` | `dropdown` | Bootstrap dropdown lifecycle + click-outside-to-close. Uses `boundXxx = handler.bind(this)` pattern (legacy) — new controllers should prefer arrow-function class fields. |
+| `navbar_controller.js` | `navbar` | Top navbar interactions (mobile collapse, active link highlighting). |
+| `theme_controller.js` | `theme` | Light/dark theme toggle. Persists choice in `localStorage`, sets `data-theme` and `data-bs-theme` on `<html>` and `<body>` (Bootstrap reads `data-bs-theme`). |
+| `hello_controller.js` | `hello` | Stimulus boilerplate — safe to delete once replaced by real controllers. |
+
+### Theme controller pattern
+
+`theme_controller.js` is the reference for "persisted UI state" controllers:
+
+```js
+connect() {
+  const savedTheme = localStorage.getItem('theme') || 'light'
+  this.setTheme(savedTheme)
+}
+```
+
+Notes:
+- Reads `localStorage` in `connect()` so theme survives Turbo navigation.
+- Mirrors state to BOTH `data-theme` (for app CSS) and `data-bs-theme` (for Bootstrap 5).
+- Optional `toggle` target — guarded with `this.hasToggleTarget`.
+- The toggle button can be either an `<i>` icon or a wrapper containing `<i>` — the controller handles both.
+
+When you add similar persisted UI controllers (sidebar collapse, font-size, density), follow the same shape: read in `connect`, write in `setX`, no listeners on `document`.