lcp 0.1.0

data/docs/reference/i18n_check.md

@@ -0,0 +1,351 @@
+# i18n_check Reference
+
+`lcp_ruby:i18n_check` is a boot-time empirical lint that asserts every
+labeled element in your LCP metadata resolves to a translation in every
+configured locale. It complements the existing `lcp_ruby:i18n_lint`
+(which scans `app/views/**/*.erb` and JS) and the
+`LcpRuby/NoHardcodedI18nString` RuboCop cop (which covers controllers /
+services).
+
+For the i18n key conventions themselves (where to put translations, how
+keys are derived from model / field / enum names) see
+[i18n.md](i18n.md). This reference focuses on the lint that audits
+those conventions are followed.
+
+## Quick Start
+
+```bash
+bundle exec rake lcp_ruby:i18n_check
+```
+
+The task boots Rails (it depends on `:environment`) and walks every
+`presenter`, `model`, `workflow`, `view group`, `page`, and `menu`
+definition the loader sees. For each labeled element it computes the
+canonical i18n key and asks `I18n.exists?(key, locale)` for every
+configured locale.
+
+Default severity is `:warning` — exit code is `0` so CI doesn't fail
+until you opt in (see [Severity & CI integration](#severity--ci-integration)).
+
+## Configuration
+
+In `config/initializers/lcp_ruby.rb`:
+
+```ruby
+LcpRuby.configure do |config|
+  config.i18n_check = {
+    locales: [ :en, :cs ],          # which locales the lint audits
+    severity: :warning,             # top-level default
+    severity_per_kind: {
+      literal_in_dsl:       :warning,
+      direct_render_label: :warning,
+      missing_translation:  :warning
+    },
+    flag_pure_duplicates: false,
+    paths:    [ "config/lcp_ruby" ],
+    exclude:  [ "**/fixtures/**", "**/tmp/**" ]
+  }
+end
+```
+
+### Options
+
+| | |
+|---|---|
+| **`locales`** | Array of locale symbols the lint audits. **Strongly recommended to set explicitly** — defaults to `I18n.available_locales`, which on a host that loads `rails-i18n` is ~30 entries and produces unreadable `missing in: en,ar,de,...` reports. The lint emits a one-time stderr warning when this falls back. **Auto-populated by `lcp new --locale=<list>`** — the install generator writes `locales: [<parsed CLI list>]` into the initializer so the lint validates exactly the locales the app declares. Standalone `rails generate lcp_ruby:install` (no `--locale`) keeps the safe `[:en]` default; pass `--locale=cs,de` to override. See [adding-locale.md](../guides/adding-locale.md#migration-from-pre-v1-generators) for the migration recipe if your app was generated before this auto-propagation landed. |
+| **`severity`** | `:error` / `:warning` / `:info` / `:off`. Top-level default for offenses without a per-kind override. `:off` disables the lint entirely. |
+| **`severity_per_kind`** | Per-kind severity overrides. Three kinds: `:literal_in_dsl`, `:direct_render_label`, `:missing_translation` — see [Offense kinds](#offense-kinds) below for what each fires on. Setting any to `:off` skips emission entirely (the offense isn't reported at all). |
+| **`flag_pure_duplicates`** | When `false` (default), a literal that pairs with an all-locales-present key is silent — it acts as the runtime fallback. Set `true` to flag pure duplicates ("you have both the literal AND the locale entry, they will drift"). |
+| **`literal_as_default_locale`** | When `false` (default — strict principle), every configured locale must have an entry. When `true`, the lint excludes `I18n.default_locale` from "missing" before firing — DSL literals are treated as the implicit default-locale value. See [Single-locale ergonomics](#single-locale-ergonomics) below. |
+| **`paths`** | Where to look for metadata source files (used to map exclude globs). Default `config/lcp_ruby`. |
+| **`exclude`** | Glob patterns to skip on top of the default `**/fixtures/**` and `**/tmp/**`. Path-based — useful for whole-file opt-out (the line-level exempt marker covers per-line). |
+
+## How it works
+
+The lint is a single boot-time pass. It iterates
+`LcpRuby.loader.*_definitions` through the iteration façade
+(`each_section`, `each_field`, `each_view_label`, …) and for each
+labeled element:
+
+  1. Computes the canonical i18n key (e.g.
+     `lcp_ruby.models.activity.fields.subject`).
+  2. Checks `I18n.exists?(key, locale, fallback: false)` for every
+     locale in `config.locales`.
+  3. Emits an offense if the key doesn't resolve in some locale.
+
+This is the empirical check: whatever the runtime would query, the
+lint queries too. Custom backends (DB-stored translations, gem-provided
+backends) are seen automatically because `I18n.exists?` goes through
+the same backend the runtime uses.
+
+DSL-loaded definitions surface with precise `file:line` (captured by
+`caller_locations` at DSL set-time). YAML-loaded definitions surface
+with the YAML file path and `line: nil` (no per-row precision —
+sufficient to locate the issue, and simpler than walking Psych::Nodes).
+
+### Offense kinds
+
+The lint emits three kinds, distinguished by what the runtime would
+render and whether a translation file is consulted:
+
+| Kind | When it fires |
+|---|---|
+| `missing_translation` | The runtime would render a humanize-default fallback in some locale (e.g. `field :recorded_on` shows "Recorded on" — fine in `:en`, broken UX in `:cs` without a locale entry). The DSL value matches what `humanize(name)` would produce. |
+| `literal_in_dsl` | The author wrote a hardcoded `label "Custom Name"` that differs from the humanize default, AND that key is missing in some locale. The literal acts as the runtime fallback — broken UX in any locale without an entry, AND a "two sources of truth" drift risk even after the translation lands. |
+| `direct_render_label` | The author wrote a hardcoded label on a UI surface the runtime renders directly without consulting a translation file: column labels, filter labels, view-group view labels, saved-filter presets, state descriptions. The literal renders as-is in every locale. Fix is either remove the literal so the underlying field's translation applies, or extend the runtime to consume a per-element key for that surface. |
+
+When the canonical key resolves in every configured locale (and the
+surface DOES go through `I18n.t`), the lint stays silent — the literal
+is harmless, it's the never-reached `default:` argument. Set
+`flag_pure_duplicates: true` to also flag the override case
+(`literal_in_dsl` with `missing_in: []`) as a drift-risk warning.
+
+### Severity downgrades
+
+`:missing_translation` downgrades to `:info` when **every** missing
+locale is covered by a configured `I18n.fallbacks` chain. So if
+`cs → en` is your fallback and the key resolves in `:en`, the runtime
+experience is "English shown in CS UI" — a real but lower-priority
+gap, not the same as "broken everywhere."
+
+`:literal_in_dsl` is fallback-agnostic — the principle violation
+stands even when fallbacks mask the runtime symptom.
+
+## Exemption Marker
+
+For deliberate one-locale demos or fixtures where translation isn't
+warranted, mark the offending DSL line:
+
+```ruby
+label "Demo only"  # i18n-exempt: showcase fixture, English-only by design
+```
+
+The reason after the colon is **mandatory** (lint rejects
+`# i18n-exempt:` with empty reason). Same convention as
+`lcp_ruby:i18n_lint` and the `LcpRuby/NoHardcodedI18nString` cop.
+
+The marker only works on lines the lint can identify by row — that is,
+DSL files where `caller_locations` captured a precise line. For YAML
+files (no row precision in this design), use `config.exclude` glob
+patterns to opt out at the file level.
+
+## Output Formats
+
+Picked by `LCP_I18N_FORMAT` env var or rake arg
+(`rake "lcp_ruby:i18n_check[json]"`):
+
+* **`text`** (default) — human-readable, grouped by file with summary footer.
+* **`github`** — GitHub Actions workflow command annotations
+  (`::warning file=...,line=...::msg`). Properly escapes `:` / `,` / `%`.
+* **`json`** — versioned schema (`{ "version": 1, "offenses": [...], "summary": {...} }`)
+  for IDE / CI integrations. The `version` field is a stable contract.
+
+## Severity & CI Integration
+
+Default `severity: :warning` means exit code is always `0` — the lint
+reports without failing CI. To gate CI:
+
+```ruby
+config.i18n_check = {
+  locales: [ :en, :cs ],
+  severity_per_kind: {
+    literal_in_dsl:       :error,    # Tier 1 — strict
+    missing_translation:  :warning,  # informational
+    direct_render_label: :warning   # Tier 2 — warn until runtime support exists
+  }
+}
+```
+
+GitHub Actions snippet:
+
+```yaml
+- name: i18n check
+  run: bundle exec rake "lcp_ruby:i18n_check[github]"
+```
+
+The `github` format emits annotations on the PR diff inline. CI fails
+on any `:error` severity offense (exit code `1`).
+
+### Greenfield install (new app via `rails generate lcp_ruby:install`)
+
+The install generator scaffolds a strict `config.i18n_check` block
+with `literal_in_dsl: :error` from day one — there's no legacy
+`literal_in_dsl` debt to ramp down. New PRs that introduce a
+hardcoded override with a missing translation fail CI immediately.
+`:missing_translation` and `:direct_render_label` default to
+`:warning` so the inevitable cleanup of implicit field labels and
+Tier 2 surfaces happens at the host's pace, not as a CI block.
+
+### Retrofit ramp (existing app adding the lint)
+
+Existing apps usually have a non-zero baseline of `literal_in_dsl`
+offenses inherited from before the lint existed. Default the whole
+config to `:warning` initially and ramp up:
+
+1. **Install with default `:warning` severity.** Lint runs in CI but
+   never fails — produces a baseline offense count.
+2. **Cleanup pass** — populate `config/locales/{en,cs}.yml` so
+   `:missing_translation` offenses go to zero. Tier 2 offenses
+   (`direct_render_label`) stay until runtime support exists for
+   per-element keys.
+3. **Flip `:literal_in_dsl` to `:error`** once cleanup merges. New
+   PRs that introduce hardcoded labels with a missing translation
+   fail CI immediately.
+4. **Cleanup of hardcoded labels on direct-render surfaces**
+   (`:direct_render_label`, see below) is a longer-term project —
+   convert column / filter / view-group literals one at a time as the
+   runtime gains matching i18n keys.
+
+## What gets checked
+
+The lint checks two flavors of label, distinguished by how the runtime
+resolves them.
+
+### Labels the runtime resolves through `I18n.t`
+
+These are the most common — runtime calls `I18n.t(<key>, default: …)`
+and the lint asserts the key resolves in every configured locale.
+Both `literal_in_dsl` and `missing_translation` offense kinds apply
+here. The lint vocabulary calls these "Tier 1".
+
+| Element | Canonical key |
+|---|---|
+| Model singular | `lcp_ruby.models.<name>.one` |
+| Model plural | `lcp_ruby.models.<name>.other` |
+| Model field | `lcp_ruby.models.<model>.fields.<field>` (primary) + `lcp_ruby.fields.<field>` (global fallback) |
+| Enum value | `lcp_ruby.models.<model>.enums.<field>.<value>` |
+| Presenter label | `lcp_ruby.models.<model>.other` (shared with model plural) |
+| Presenter section | `lcp_ruby.presenters.<name>.sections.<section_key>` — explicit DSL `key:` wins verbatim; otherwise `title.parameterize(separator: "_")` |
+| Custom action label | `lcp_ruby.actions.form.<action_name>` (per-action-name, shared across presenters) |
+| Workflow state | `lcp_ruby.workflows.<workflow>.states.<state>` |
+| Workflow transition | `lcp_ruby.workflows.<workflow>.transitions.<transition>` |
+| Menu entry | `lcp_ruby.menu.<label.parameterize>` |
+| Page title | the value of `page.title_key` verbatim (fully-qualified i18n key — e.g. `lcp_ruby.crm.dashboard.title`); only checked when `title_key:` is set |
+
+### Labels the runtime renders directly
+
+Some UI surfaces don't currently consult a translation file — the
+literal you wrote is what the user sees, in every locale. Only
+`direct_render_label` (a severity dial — see [options](#options))
+applies. The lint vocabulary calls these "Tier 2":
+
+| DSL surface | Today's runtime |
+|---|---|
+| `column :v, label: "Mark"` | renders literal directly |
+| `field :v, label: "X"` (override inside show/form section) | renders literal directly |
+| `filter :v, label: "X"` | renders literal directly |
+| `preset :v, label: "X"` (saved filter) | renders literal directly |
+| `view :page, label: "Tab"` (view group) | renders literal directly |
+| `state :s, description: "X"` (workflow) | renders literal directly |
+
+Two ways to clean these up:
+
+* **Remove the literal** so the underlying field/parameter translation
+  applies (most column / field-override / filter cases — they fall
+  through to the model field's translation).
+* **File a runtime extension request** for the engine to consume a
+  per-element i18n key on this surface (everything else). Until that
+  lands, the lint warns about the literal.
+
+If your app accepts the literal as English on these surfaces (e.g. a
+single-language demo, or a multi-locale app where you accept English
+fallback for these specific UI bits), set
+`severity_per_kind: { direct_render_label: :off }` to silence the
+warnings entirely.
+
+Tier 2 severity defaults to `:warning` regardless of the top-level
+`severity:` setting, so the lint doesn't demand a runtime change
+before strict-mode flip.
+
+## Single-locale ergonomics
+
+By default the lint enforces the strict project i18n principle (see
+[`CLAUDE.md`](../../CLAUDE.md) § "i18n Principle"): every configured
+locale must have an entry, hardcoded labels in DSL/YAML get flagged.
+This works well when translators edit only locale files and never see
+the DSL.
+
+For apps that ship in only one language, the strict rule is friction
+without benefit — a `label "Stage"` works correctly at runtime in `:en`
+(via `I18n.t(key, default: "Stage")`), but the lint asks the author to
+also create an `en.yml` entry. The locale file just duplicates the
+literal.
+
+Opt in with `literal_as_default_locale: true`:
+
+```ruby
+LcpRuby.configure do |config|
+  config.i18n_check = {
+    locales: [ :en ],
+    literal_as_default_locale: true
+  }
+end
+```
+
+With the flag on, the lint accepts a hardcoded literal as the implicit
+`I18n.default_locale` value:
+
+* **Single-locale app, `locales: [:en]`, `default_locale: :en`** —
+  silent on `label "Stage"` without any locale entry. The literal is
+  the en value at runtime.
+* **Multi-locale app, `locales: [:en, :cs]`, `default_locale: :en`** —
+  silent on the en side, but `label "Stage"` without a `cs.yml` entry
+  still fires `:missing_translation` (cs needs a translation). Adding
+  Czech is forward-compatible: the literal stays put, locale files grow.
+* **Hardcoded labels on UI surfaces the runtime renders directly**
+  (column labels, filter labels, view-group view labels, saved-filter
+  presets, state descriptions — collectively "Tier 2" in lint
+  vocabulary): the lint silences them only when the configured set is
+  exactly `[default_locale]`. Multi-locale apps still see warnings here
+  because non-default locales would render the literal too (Czech users
+  see English on these surfaces, broken UX in those locales).
+
+To also silence Tier 2 warnings in a multi-locale app — accepting that
+non-default locales will render the literal until the runtime grows a
+per-element key for those surfaces — combine with
+`severity_per_kind: { direct_render_label: :off }`:
+
+```ruby
+config.i18n_check = {
+  locales: [ :en, :cs ],
+  literal_as_default_locale: true,
+  severity_per_kind: { direct_render_label: :off }
+}
+```
+
+(`:off` severity skips emission entirely — the warning isn't reported
+at all. See [Severity & CI Integration](#severity--ci-integration).)
+
+Trade-off: relaxes the "locale files are the single source of truth"
+principle. For projects with translator workflows where translators
+edit only locale files (and need every label to surface there), keep
+the flag `false`. For solo / small-team apps with optional later
+internationalization, set `true` for ergonomics.
+
+## Limitations
+
+* **No per-line precision in YAML** — YAML-loaded definitions surface
+  with the file path but `line: nil`. Sufficient to locate the issue
+  in the file; not pinpoint to the exact row. Use `config.exclude`
+  for whole-file opt-out.
+
+* **Engine-internal definitions are skipped** — definitions
+  registered programmatically (no source file) are not flagged. The
+  lint is host-only by design.
+
+* **Boot cost** — Pass requires Rails (`:environment` dependency).
+  Typical run is 5–15 s on a 100-presenter app. Not suitable for
+  editor inner-loop; intended for CI and pre-commit.
+
+* **Custom `I18n.fallbacks`** — the lint reads `I18n.fallbacks` at
+  task-run time. If your host configures fallbacks programmatically
+  inside an initializer that doesn't run during the rake task, the
+  chain may differ from production.
+
+## Cross-references
+
+* Design rationale and decisions: [`docs/design/i18n_consistency_check.md`](../design/i18n_consistency_check.md)
+* General i18n conventions (where to put keys): [i18n.md](i18n.md)
+* RuboCop cop covering controllers / services:
+  `LcpRuby/NoHardcodedI18nString` (registered in `.rubocop.yml`)
+* ERB / JS scanner: `bundle exec rake lcp_ruby:i18n_lint`

data/docs/reference/import.md

@@ -0,0 +1,260 @@
+# Import Reference
+
+Import enables uploading CSV or XLSX files to create, update, or upsert records. It supports column auto-mapping, association lookup, four import strategies, saved profiles, background execution with progress tracking, and nested `has_one` import.
+
+## Presenter Configuration
+
+The `import:` block is a top-level presenter key that enables import for that presenter.
+
+### YAML
+
+```yaml
+presenter:
+  name: employees
+  model: employee
+
+  import:
+    formats: [csv, xlsx]
+    max_rows: 5000
+    csv_delimiter: ","
+    csv_encoding: auto
+    nested_associations: [employee_profile, employee_emergency_contact]
+    nested_blank_strategy: skip
+    parsing:
+      date_format: ["%d.%m.%Y", "%Y-%m-%d"]
+      boolean_true: [true, yes, 1, ano]
+      boolean_false: [false, no, 0, ne]
+```
+
+### DSL
+
+```ruby
+define_presenter :employees do
+  model :employee
+
+  import formats: [:csv, :xlsx], max_rows: 5000,
+    nested_associations: [:employee_profile],
+    nested_blank_strategy: "skip",
+    parsing: { date_format: ["%d.%m.%Y", "%Y-%m-%d"] }
+end
+```
+
+### Import Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `formats` | array | `["csv"]` | Accepted file formats. Supported: `csv`, `xlsx`. XLSX requires the `roo` gem. |
+| `max_rows` | integer | `10000` | Safety limit. Row count is checked in phase 1 before the job is enqueued. |
+| `max_file_size` | integer | `10485760` | Maximum file size in bytes (default 10 MiB). |
+| `csv_delimiter` | string | `","` | CSV column separator. Use `";"` for European locales. |
+| `csv_encoding` | string | `"auto"` | CSV encoding. `"auto"` detects via BOM and UTF-8 validity check. |
+| `parsing` | hash | `{}` | Type coercion options: `date_format`, `datetime_format`, `decimal_separator`, `boolean_true`, `boolean_false`. |
+| `nested_associations` | array | `nil` (all) | Whitelist of `has_one` association names to expose in import. When omitted, all `has_one` with `nested_attributes` are exposed. |
+| `nested_blank_strategy` | string | `"null"` | How to handle blank values in nested columns. `"null"` sets to nil (overwrites). `"skip"` omits blank fields (preserves existing values). |
+
+## Import Actions
+
+Import requires an action declaration in the presenter:
+
+```yaml
+actions:
+  collection:
+    - { name: import, type: built_in, icon: upload }
+```
+
+DSL equivalent:
+
+```ruby
+action :import, type: :built_in, on: :collection, icon: "upload"
+```
+
+## Import Strategies
+
+The strategy is chosen by the user in the import dialog, not hardcoded in config.
+
+| Strategy | Match attr | Behavior |
+|----------|-----------|----------|
+| `create_only` | No | Always create new records |
+| `update_only` | Yes | Find + update existing, error if not found |
+| `upsert` | Yes | Find + update, or create if not found |
+| `skip_existing` | Yes | Skip if found, create if not found |
+
+## Column Mapping
+
+Source CSV/XLSX columns are mapped to target model fields via a two-phase dialog:
+
+- **Phase 1 (Upload):** File upload, strategy selection, match attribute
+- **Phase 2 (Mapping):** Column mapping table with auto-mapping suggestions
+
+### Auto-Mapping
+
+Source headers are matched to target fields using three strategies (in order):
+
+1. **Exact field name** (case-insensitive): `"name"` matches `name`
+2. **Humanized label**: `"Product Name"` matches `name` via i18n reverse lookup
+3. **Underscore normalization**: `"Category Id"` matches `category_id`
+
+For nested fields, auto-mapping also matches by suffix: `"Starting Salary"` matches `employee_profile.starting_salary`. Direct fields always win over nested suffixes. If two nested fields share the same suffix (e.g., `hire_detail.notes` and `departure_detail.notes`), neither is auto-mapped.
+
+### Association Lookup
+
+For `belongs_to` FK fields, the user can select a lookup attribute (e.g., `name`) to resolve text values to IDs. When lookup fails, the row is recorded as error.
+
+For associations declared with [`primary_key:`](models.md#primary_key) — i.e., joins on a business key instead of a surrogate id — the importer resolves the target record by the selected lookup attribute, then writes the **join column value** back to the FK field. For example, with `belongs_to :division, foreign_key: :division_code, primary_key: :vema_code` and lookup attribute `id`, a CSV row carrying `42` is resolved via `Division.find(42)` and the employee's `division_code` is set to `division.vema_code` (not `42`). The "ID" option in the lookup dropdown therefore still works for `primary_key:` associations, and string business keys (including leading-zero codes like `"0042"`) round-trip through the importer without integer coercion.
+
+## Permissions
+
+- **Action permission:** `import` must be in the role's `actions` list
+- **Field-level:** Only `writable_fields` appear as mapping targets (enforced at mapping time AND execution time)
+- **Nested fields:** Writable fields on the target model are checked via the target model's `PermissionEvaluator`
+
+## Nested has_one Import
+
+Import flat CSV rows into a parent record and its `has_one` associations in a single transaction.
+
+### Model Setup
+
+The `has_one` association must declare `nested_attributes`:
+
+```yaml
+associations:
+  - type: has_one
+    name: employee_profile
+    target_model: employee_profile
+    dependent: destroy
+    inverse_of: employee
+    nested_attributes: true    # safe defaults: reject_if: all_blank, update_only: true
+```
+
+See [Models Reference — Nested Attributes](models.md#nested-attributes) for the boolean shorthand and explicit hash form.
+
+### Column Mapping Format
+
+Dot-notation in column mapping targets nested fields:
+
+```json
+{
+  "Name": "name",
+  "Hire Date": "employee_profile.hire_date",
+  "Salary": "employee_profile.salary",
+  "Contact Name": "employee_emergency_contact.contact_name"
+}
+```
+
+The `RowProcessor` converts dot-notation to Rails nested attributes:
+
+```ruby
+{
+  "name" => "Alice",
+  "employee_profile_attributes" => { "hire_date" => Date.new(2024, 1, 15), "salary" => 72000.0 },
+  "employee_emergency_contact_attributes" => { "contact_name" => "Karel" }
+}
+```
+
+### Field Picker UI
+
+Nested fields appear in `<optgroup>` elements in the mapping dropdown:
+
+```
+Target field dropdown:
+  -- skip --
+  Name
+  Email
+  Department
+  ...
+  ▸ Employee Profile
+      Hire date
+      Salary
+      National ID
+      ...
+  ▸ Employee Emergency Contact
+      Contact name
+      Relationship
+      ...
+```
+
+Nested fields do NOT show the "Lookup by" column — they are direct value fields.
+
+### Blank Handling
+
+When **all** nested columns for an association are blank, `reject_if: :all_blank` applies — no nested record is created or modified.
+
+When only **some** nested columns are blank, the `nested_blank_strategy` controls behavior:
+
+| Strategy | Blank column behavior | Use case |
+|----------|----------------------|----------|
+| `"null"` (default) | Set field to `nil`. Overwrites existing data. | When blank means "clear this field" |
+| `"skip"` | Omit field from nested attributes. Existing value preserved. | When blank means "no change" (safer for bulk import) |
+
+**Example:** CSV has `salary=""`, `referral="Martin"`. Existing record has `salary=50000`.
+
+- `"null"`: `{ "salary" => nil, "referral" => "Martin" }` → salary overwritten to nil
+- `"skip"`: `{ "referral" => "Martin" }` → salary preserved as 50000
+
+### Upsert Behavior
+
+When strategy is `upsert` or `update_only`:
+
+1. Parent record is found by `match_attribute`
+2. Existing nested record → **updated in-place** (same ID preserved, `update_only: true`)
+3. No existing nested record → **new one created**
+4. All nested columns blank → **existing nested record untouched**
+
+### Nested Associations Whitelist
+
+The `nested_associations` presenter config controls which `has_one` associations appear in the import field picker:
+
+```yaml
+import:
+  nested_associations: [employee_profile]     # only employee_profile, not emergency_contact
+```
+
+When omitted, all `has_one` associations with `nested_attributes` are exposed.
+
+### Permission Filtering
+
+Nested fields are checked against the **target model's** permissions, not the parent's. A user must have write permission on the target model to see and map its fields. Permission is enforced at three points:
+
+1. **Field picker** — `FieldTreeBuilder` checks `target_evaluator.field_writable?`
+2. **Dialog submit** — `ImportDialogHandler` validates before enqueuing
+3. **Job execution** — `ImportJobHandler` re-validates in case permissions changed
+
+## Type Coercion
+
+| Type | Parsing rules |
+|------|---------------|
+| string | Stripped whitespace, taken as-is |
+| integer | `Integer(value)`, error if non-numeric |
+| float/decimal | Configurable decimal separator (`.` or `,`) |
+| boolean | Accept: true/false, yes/no, 1/0, t/f (i18n-extensible) |
+| date | Ordered format list via `strptime`, first match wins |
+| datetime | Ordered format list, ISO 8601 default |
+| enum | Accept: raw key, human label (i18n reverse lookup), case-insensitive |
+
+## Background Execution
+
+Import runs as a `data_import` background job:
+
+- Progress tracking (percentage updated every 100 rows)
+- Cancellation support (user can cancel mid-import)
+- No auto-retry (`retry: 0`) to prevent duplicate records
+- Per-row processing (partial imports supported)
+- Memory-efficient streaming
+
+## Import Profiles
+
+Saved column mappings + strategy as named profiles with visibility levels: personal, role, global.
+
+## Per-Row Tracking
+
+Each imported row creates an `import_row` record with status, error message, source data, target record ID, and previous values (for undo).
+
+## Generator
+
+```bash
+rails generate lcp_ruby:import
+```
+
+Creates: `import_row` model/presenter/permissions, `import_profile` model/presenter/permissions, `data_import` job definition.
+
+Prerequisite: `rails generate lcp_ruby:background_jobs` must be run first.