ariadna 1.1.3 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1ed375271ac768caefa266c693b81aabf5721cbe01cba600ba219a25594de3c
-  data.tar.gz: 0253d51a13f639d93785d01bb72459020d42afceac232282c798975faf629bf4
+  metadata.gz: a59ce08ab4d7f1165dd59dac034ac04e5725263a3022bebbd2c3c39fdb0a3c23
+  data.tar.gz: 2eb175ba24a25c5114e3b76f83bbfef0275a21dc114f00d7376390508cb54a87
 SHA512:
-  metadata.gz: ae19b2a21a2713c0e15f9dacc0d06a4306d47b3620b0e7c0ea78c87a109e11f35c6f396efb5e2b3b4e7ddf404f1db94cecf01df10144213911eadcb59cc6e360
-  data.tar.gz: 580e4a7376e86aa30f705d1502264729c9be324711b0daa2f54caa1818acd42d67101859811b5d2a46a9ce321fbaacc74ddb08e6746ffd51165588723842843b
+  metadata.gz: 11f2127685615ea902f97bfc9fc813e20e74f354b055672568d39552d3d551d31896ba73b5ad3434d1ac84dc6d593f8d385818e78fc7cae24844f45720558f80
+  data.tar.gz: cec523e574d6182711229ddf5fa7519929f3c9fb9a144a0eb4928cf46a24d4761e9f718cf3678cf2dde812f9cd655647ca2c12776fcf29aa526831ad9df017a9

data/data/agents/ariadna-backend-executor.md

@@ -23,7 +23,7 @@ Load and follow the project's backend guide for domain-specific patterns:
 - **Models & Concerns:** Concern-driven architecture, intention-revealing APIs, smart association defaults
 - **Controllers:** Thin controllers delegating to rich models, RESTful resource nesting
 - **Jobs:** Ultra-thin jobs with _now/_later pattern, multi-tenancy context
-- **Migrations:** UUID primary keys, proper foreign key references
+- **Migrations:** Proper foreign key references
 - **Configuration:** Rails conventions, initializers, routing
 
 **When executing backend tasks:**

data/data/agents/ariadna-planner.md

@@ -17,6 +17,7 @@ Your job: Produce PLAN.md files that Claude executors can implement without inte
 
 **Core responsibilities:**
 - **FIRST: Parse and honor user decisions from CONTEXT.md** (locked decisions are NON-NEGOTIABLE)
+- Use Rails conventions (from `rails-conventions.md`) for standard task decomposition
 - Decompose phases into parallel-optimized plans with 2-3 tasks each
 - Build dependency graphs and assign execution waves
 - Derive must-haves using goal-backward methodology
@@ -25,6 +26,33 @@ Your job: Produce PLAN.md files that Claude executors can implement without inte
 - Return structured results to orchestrator
 </role>
 
+<rails_awareness>
+## Rails-Aware Planning
+
+Load Rails conventions from your required reading for standard task decomposition patterns.
+
+@~/.claude/ariadna/references/rails-conventions.md
+
+**Use domain templates** for common Rails work:
+- "Add model" → migration + model + tests + fixtures
+- "Add controller" → routes + controller + views + tests
+- "Add authentication" → auth scaffold + user model + session controller + tests
+- "Add background job" → job class + model method + tests
+- "Add mailer" → mailer + views + tests
+- "Add Turbo/Hotwire feature" → Turbo Frame + controller response + Stimulus (if needed) + system test
+
+**Known domains (skip discovery):** Models, Controllers, Views, Auth, Jobs, Email, File Uploads, Real-time, Testing, API Mode, Caching. See `rails-conventions.md` `<known_domains>` for the full list.
+
+**Discovery only for:** External API integrations, novel gems, payment systems, or anything not in the known domains list.
+
+**Pitfall prevention:** Apply common Rails pitfalls from `rails-conventions.md` proactively:
+- Include `includes()` for associations in controller queries (N+1)
+- Add database indexes in migration tasks
+- Use strong_parameters in controller tasks
+- Keep controllers thin, models rich
+- Use background jobs for external calls
+</rails_awareness>
+
 <context_fidelity>
 ## CRITICAL: User Decision Fidelity
 
@@ -180,7 +208,7 @@ Each task: **15-60 minutes** Claude execution time.
 | "Create the API" | "Create POST /projects endpoint in ProjectsController#create accepting {name, description}, validates name length 3-50 chars, returns 201 with project JSON" |
 | "Style the dashboard" | "Add CSS classes to dashboard view: grid layout (3 cols on lg via media query, 1 on mobile), card shadows via --shadow variable, hover states on action buttons per style guide" |
 | "Handle errors" | "Add rescue_from in ApplicationController, render JSON errors on 4xx/5xx, show flash messages on server-rendered pages" |
-| "Set up the database" | "Add User and Project models with UUID primary keys, email unique constraint, timestamps, run rails db:migrate" |
+| "Set up the database" | "Add User and Project models, email unique constraint, timestamps, run rails db:migrate" |
 
 **Test:** Could a different Claude instance execute without asking clarifying questions? If not, add specificity.
 

data/data/agents/ariadna-test-executor.md

@@ -21,7 +21,7 @@ Load and follow the project's testing guide for domain-specific patterns:
 
 **Focus areas:**
 - **Minitest conventions:** `ActiveSupport::TestCase` for models, `ActionDispatch::IntegrationTest` for controllers
-- **Fixtures:** YAML fixtures for deterministic test data, UUID-based fixture IDs
+- **Fixtures:** YAML fixtures for deterministic test data
 - **Current context:** Always set `Current.session = sessions(:name)` in setup blocks
 - **assert_difference:** Use for state changes, nest for multiple record types
 - **Testing patterns:** Model tests for business logic, controller tests for delegation, job tests for enqueuing

data/data/ariadna/references/rails-conventions.md

@@ -0,0 +1,384 @@
+<rails_conventions>
+
+Pre-baked Rails knowledge for Ariadna planning and execution agents. This document replaces generic research for standard Rails projects, encoding well-known conventions, patterns, and pitfalls so agents don't need to web-search for common Rails patterns.
+
+<standard_stack>
+
+## Standard Rails Stack (2025)
+
+| Layer | Technology | Notes |
+|-------|-----------|-------|
+| Framework | Rails 8+ | Defaults to SQLite in dev, includes Solid Queue/Cache/Cable |
+| Database | PostgreSQL (production) | SQLite for dev/test is fine for most projects |
+| Background Jobs | Solid Queue | Rails 8 default, replaces Sidekiq for most cases |
+| Caching | Solid Cache | Rails 8 default, database-backed cache |
+| WebSockets | Action Cable + Solid Cable | Rails 8 default |
+| Real-time UI | Turbo (Hotwire) | Turbo Drive, Frames, Streams |
+| JS Sprinkles | Stimulus (Hotwire) | Controllers for interactive behavior |
+| CSS | Tailwind CSS or Propshaft | Rails 8 defaults to Propshaft asset pipeline |
+| Auth | Rails built-in `has_secure_password` or Devise | Rails 8 includes auth generator |
+| Email | Action Mailer | Built-in |
+| File Upload | Active Storage | Built-in |
+| API | Rails API mode or Jbuilder | Built-in |
+| Testing | Minitest | Rails default, use fixtures not factories |
+| Linting | RuboCop + rubocop-rails | Standard community linting |
+
+**What NOT to use (and why):**
+- Factories (FactoryBot) when fixtures suffice — fixtures are faster, declarative, and Rails-native
+- RSpec unless the project already uses it — Minitest is simpler and Rails-native
+- Webpacker/Shakapacker — replaced by importmap-rails or jsbundling-rails
+- Sprockets — replaced by Propshaft in Rails 8
+- Redis for jobs/cache — Solid Queue/Cache use the database, simpler ops
+
+</standard_stack>
+
+<architecture_patterns>
+
+## Rails Architecture Patterns
+
+### MVC Foundation
+- **Models:** Business logic lives here. Validations, scopes, callbacks, associations.
+- **Controllers:** Thin. Receive request, call model, render response. 7 RESTful actions max.
+- **Views:** ERB templates. Logic delegated to presenters or helpers.
+
+### Concern-Driven Architecture
+```
+app/models/concerns/
+  shared/           # Cross-model concerns (Trackable, Searchable)
+  model_name/       # Model-specific concerns (User::Authenticatable)
+```
+
+**When to extract a concern:**
+- Behavior reused across 2+ models → shared concern
+- Model file exceeds ~100 lines → model-specific concern
+- Logical grouping of related methods → named concern
+
+### Service Objects (When Needed)
+Use plain Ruby objects in `app/services/` for:
+- Multi-model operations (CreateOrderWithPayment)
+- External API integrations (StripeChargeService)
+- Complex business processes spanning multiple steps
+
+**Don't use for:** Simple CRUD, single-model operations, or anything a model method handles.
+
+### Presenter Pattern
+Plain Ruby classes for complex view logic:
+```ruby
+# app/models/dashboard_presenter.rb (NOT app/presenters/)
+class DashboardPresenter
+  include ActionView::Helpers::TagHelper
+
+  def initialize(user)
+    @user = user
+  end
+
+  def greeting
+    "Welcome, #{@user.name}"
+  end
+end
+```
+
+### RESTful Resource Design
+- Prefer creating new controllers over adding custom actions
+- `POST /messages/:id/archive` → `ArchivesController#create`
+- Nest resources max 1 level: `/posts/:post_id/comments`
+- Use `concerns` in routes for shared resource patterns
+
+### Current Attributes
+```ruby
+# app/models/current.rb
+class Current < ActiveSupport::CurrentAttributes
+  attribute :user, :session, :account
+end
+```
+Set in `ApplicationController`, access everywhere. No parameter passing for auth context.
+
+</architecture_patterns>
+
+<common_pitfalls>
+
+## Common Rails Pitfalls (with Prevention)
+
+### 1. N+1 Queries
+**Problem:** Loading associated records in a loop.
+**Prevention:** Use `includes`, `preload`, or `eager_load` in controllers. Add `strict_loading` to models in development.
+```ruby
+# Bad
+@posts = Post.all  # then post.comments in view
+
+# Good
+@posts = Post.includes(:comments, :author).all
+```
+
+### 2. Missing Database Indexes
+**Prevention:** Always add indexes for:
+- Foreign keys (`add_index :posts, :user_id`)
+- Columns used in `where` clauses
+- Columns used in `order` clauses
+- Unique constraints (`add_index :users, :email, unique: true`)
+
+### 3. Mass Assignment Vulnerabilities
+**Prevention:** Always use `strong_parameters` in controllers.
+```ruby
+def post_params
+  params.require(:post).permit(:title, :body, :published)
+end
+```
+
+### 4. Callback Hell
+**Prevention:** Limit callbacks to:
+- `before_validation` for normalization (strip whitespace, downcase email)
+- `after_create_commit` for async side effects (send email, broadcast)
+- Avoid `after_save` chains that trigger cascading updates
+
+### 5. Fat Controllers
+**Prevention:** Controllers should only:
+1. Authenticate/authorize
+2. Load/build the resource
+3. Call save/update/destroy
+4. Respond with redirect or render
+
+### 6. Missing Validations
+**Prevention:** Validate at model level, not just in forms:
+- Presence on required fields
+- Uniqueness with database-level constraint
+- Format for emails, URLs, phone numbers
+- Numericality for quantities, prices
+
+### 7. Unscoped Queries (Multi-tenancy)
+**Prevention:** Always scope queries to current user/account:
+```ruby
+# Bad
+Post.find(params[:id])
+
+# Good
+Current.user.posts.find(params[:id])
+```
+
+### 8. Missing Error Handling
+**Prevention:** Add `rescue_from` in `ApplicationController`:
+```ruby
+rescue_from ActiveRecord::RecordNotFound, with: :not_found
+rescue_from ActionController::ParameterMissing, with: :bad_request
+```
+
+### 9. Synchronous External Calls
+**Prevention:** Always use background jobs for:
+- Sending emails
+- Calling external APIs
+- Processing uploads
+- Generating reports
+
+### 10. Missing CSRF Protection
+**Prevention:** Rails enables CSRF by default. Don't disable `protect_from_forgery`. For API endpoints, use token auth instead.
+
+</common_pitfalls>
+
+<testing_patterns>
+
+## Rails Testing Patterns (Minitest)
+
+### Test Organization
+```
+test/
+  models/           # Unit tests for models
+  controllers/      # Integration tests for request/response
+  system/           # Browser-based end-to-end tests
+  helpers/          # Helper method tests
+  jobs/             # Background job tests
+  mailers/          # Mailer tests
+  fixtures/         # YAML test data
+  test_helper.rb    # Shared setup
+```
+
+### Fixtures Over Factories
+```yaml
+# test/fixtures/users.yml
+alice:
+  name: Alice
+  email: alice@example.com
+  password_digest: <%= BCrypt::Password.create('password') %>
+
+bob:
+  name: Bob
+  email: bob@example.com
+  password_digest: <%= BCrypt::Password.create('password') %>
+```
+
+**Why fixtures:** Faster (loaded once per test suite), declarative, Rails-native, no external gem needed.
+
+### Model Test Pattern
+```ruby
+class UserTest < ActiveSupport::TestCase
+  setup do
+    Current.session = sessions(:alice_session) # Always set Current context
+  end
+
+  test "validates email presence" do
+    user = User.new(name: "Test")
+    assert_not user.valid?
+    assert_includes user.errors[:email], "can't be blank"
+  end
+
+  test "creates user with valid attributes" do
+    assert_difference "User.count", 1 do
+      User.create!(name: "New", email: "new@example.com", password: "password")
+    end
+  end
+end
+```
+
+### Controller Test Pattern (Integration)
+```ruby
+class PostsControllerTest < ActionDispatch::IntegrationTest
+  setup do
+    @user = users(:alice)
+    sign_in @user  # Helper method
+  end
+
+  test "index returns posts" do
+    get posts_url
+    assert_response :success
+    assert_select "h2", posts(:first).title
+  end
+
+  test "create redirects on success" do
+    assert_difference "Post.count", 1 do
+      post posts_url, params: { post: { title: "New", body: "Content" } }
+    end
+    assert_redirected_to post_url(Post.last)
+  end
+end
+```
+
+### System Test Pattern
+```ruby
+class UserFlowsTest < ApplicationSystemTestCase
+  test "user can sign up and create a post" do
+    visit new_registration_url
+    fill_in "Name", with: "Test User"
+    fill_in "Email", with: "test@example.com"
+    fill_in "Password", with: "password123"
+    click_on "Sign up"
+
+    assert_text "Welcome, Test User"
+
+    click_on "New Post"
+    fill_in "Title", with: "My First Post"
+    fill_in "Body", with: "Hello world"
+    click_on "Create Post"
+
+    assert_text "My First Post"
+  end
+end
+```
+
+### Key Testing Conventions
+- Use `assert_difference` for state changes, not just boolean checks
+- Set `Current.session` in setup blocks for multi-tenancy
+- Test happy path and one key failure path per method
+- Use `assert_select` for HTML assertions in controller tests
+- Run `bin/rails test` (not `rspec`) for the full suite
+
+</testing_patterns>
+
+<domain_templates>
+
+## Rails Task Templates for Planning
+
+These templates help the planner agent decompose common Rails work into well-structured tasks.
+
+### Add Model
+```
+Tasks:
+1. Create migration + model with validations, associations, and concerns
+   Files: db/migrate/xxx_create_[model].rb, app/models/[model].rb
+2. Add model tests + fixtures
+   Files: test/models/[model]_test.rb, test/fixtures/[model].yml
+```
+
+### Add Controller (with views)
+```
+Tasks:
+1. Add routes + controller with RESTful actions
+   Files: config/routes.rb, app/controllers/[model]_controller.rb
+2. Add views (index, show, new, edit, _form partial)
+   Files: app/views/[model]/*.html.erb
+3. Add controller tests
+   Files: test/controllers/[model]_controller_test.rb
+```
+
+### Add Authentication
+```
+Tasks:
+1. Generate auth scaffold (Rails 8: bin/rails generate authentication)
+   or: Add User model with has_secure_password, Session model, SessionsController
+   Files: app/models/user.rb, app/models/session.rb, app/controllers/sessions_controller.rb
+2. Add auth views (login, registration)
+   Files: app/views/sessions/*.html.erb, app/views/registrations/*.html.erb
+3. Add auth tests
+   Files: test/controllers/sessions_controller_test.rb, test/models/user_test.rb
+```
+
+### Add Background Job
+```
+Tasks:
+1. Create job class + model method it delegates to
+   Files: app/jobs/[name]_job.rb, app/models/[model].rb
+2. Add job tests
+   Files: test/jobs/[name]_job_test.rb
+```
+
+### Add Mailer
+```
+Tasks:
+1. Create mailer + views
+   Files: app/mailers/[name]_mailer.rb, app/views/[name]_mailer/*.html.erb
+2. Add mailer tests
+   Files: test/mailers/[name]_mailer_test.rb
+```
+
+### Add Turbo/Hotwire Feature
+```
+Tasks:
+1. Add Turbo Frame wrapping + controller turbo_stream response
+   Files: app/views/[model]/*.html.erb, app/controllers/[model]_controller.rb
+2. Add Stimulus controller (if interactive behavior needed)
+   Files: app/javascript/controllers/[name]_controller.js
+3. Add system test for real-time behavior
+   Files: test/system/[feature]_test.rb
+```
+
+</domain_templates>
+
+<known_domains>
+
+## Known Rails Domains (Skip Research)
+
+These domains are well-understood in Rails and don't need web research:
+
+| Domain | Key Patterns | Research Needed? |
+|--------|-------------|-----------------|
+| Models & Migrations | ActiveRecord, validations, associations, concerns | No |
+| Controllers & Routes | RESTful resources, before_action, strong params | No |
+| Views & Templates | ERB, partials, layouts, content_for | No |
+| Authentication | has_secure_password, Devise, Rails 8 auth generator | No |
+| Authorization | Pundit, CanCanCan, or hand-rolled | No |
+| Background Jobs | Solid Queue, ActiveJob | No |
+| Email | Action Mailer, letter_opener | No |
+| File Uploads | Active Storage | No |
+| Real-time | Action Cable, Turbo Streams | No |
+| Testing | Minitest, fixtures, system tests | No |
+| API Mode | Jbuilder, API-only controllers, token auth | No |
+| Caching | Fragment caching, Russian doll, Solid Cache | No |
+| Search | pg_search, Ransack | Maybe (depends on complexity) |
+| Payments | Stripe, Pay gem | Yes (API details change) |
+| External APIs | Third-party integrations | Yes (API-specific) |
+| Novel Gems | Unfamiliar libraries | Yes |
+| Infrastructure | Docker, Kamal, deployment | Maybe |
+
+**Heuristic:** If all phase requirements map to "No" domains, skip research automatically. If any requirement maps to "Yes", consider `--research` flag.
+
+</known_domains>
+
+</rails_conventions>

data/data/ariadna/templates/codebase/architecture.md

@@ -17,7 +17,7 @@ Template for `.planning/codebase/ARCHITECTURE.md` - captures conceptual code org
 
 **Overall:** [Pattern name: e.g., "Rails Monolith", "Rails API-only", "Rails + Hotwire", "Rails Engine-based"]
 
-**Multi-Tenancy:** [e.g., "Path-based with CurrentAttributes", "Subdomain-based", "acts_as_tenant gem", "Single-tenant", "None"]
+**Multi-Tenancy:** [e.g., "Path-based with CurrentAttributes", "Subdomain-based", "session based", "Single-tenant", "None"]
 
 **Key Characteristics:**
 - [Characteristic 1: e.g., "Server-rendered with Turbo"]
@@ -277,7 +277,7 @@ Template for `.planning/codebase/ARCHITECTURE.md` - captures conceptual code org
 **Key Domain Models:**
 - `Account` — Tenant root. All data scoped to an account
 - `Board` — Project workspace containing cards, columns, and access rules
-- `Card` — Primary work item. Most concern-composed model (20+ concerns). Uses `number` (integer) for user-facing IDs, UUID internally
+- `Card` — Primary work item. Most concern-composed model (20+ concerns).
 - `Event` — Audit trail record. Polymorphic `eventable`, JSON `particulars` for action-specific data
 - `User` — Account member with role-based permissions. Resolved from `Current.session` → `identity` → `user`
 
@@ -357,11 +357,6 @@ Template for `.planning/codebase/ARCHITECTURE.md` - captures conceptual code org
 - Location: `app/models/` subdirectories — `User::Filtering`, `Event::Description`, `User::DayTimeline`
 - Pattern: Constructor injection, memoized collections (`@boards ||= ...`), boolean methods for conditional display (`show_tags?`), cache keys for fragment caching. Some include `ActionView::Helpers::TagHelper` for HTML generation. Instantiated via controller concerns or factory methods on models (`event.description_for(user)`)
 
-**Pundit Policies:**
-- Purpose: Authorize user actions on resources
-- Examples: `ProjectPolicy`, `TaskPolicy`, `MembershipPolicy`
-- Pattern: Policy class per model with `?` predicate methods
-
 ## Multi-Tenancy & Current Context
 
 **Approach:** Path-based — account slug extracted from URL path by `AccountSlug::Extractor` middleware. Slug moves from `PATH_INFO` to `SCRIPT_NAME`. No subdomain configuration needed.
@@ -400,7 +395,7 @@ Template for `.planning/codebase/ARCHITECTURE.md` - captures conceptual code org
 
 **Patterns:**
 - `rescue_from ActiveRecord::RecordNotFound` → 404 page
-- `rescue_from Pundit::NotAuthorizedError` → 403 or redirect with flash
+- `rescue_from NotAuthorizedError` → 403 or redirect with flash
 - Model validation errors re-render form with `@model.errors`
 - Service objects return `Result` structs (success/failure) instead of raising
 - Jobs use `retry_on` for transient failures, `discard_on` for permanent ones
@@ -421,7 +416,6 @@ Template for `.planning/codebase/ARCHITECTURE.md` - captures conceptual code org
 - `require_authentication` filter on all non-public controllers
 
 **Authorization:**
-- Pundit policies per resource
 - `authorize` calls in controller actions
 - Scoped queries via `policy_scope`
 

data/data/ariadna/templates/codebase/concerns.md

@@ -190,8 +190,8 @@ Template for `.planning/codebase/CONCERNS.md` - captures known issues and areas
 **Missing authorization checks on nested resources:**
 - Risk: Card comments endpoint does not verify user has access to the parent board
 - Files: `app/controllers/comments_controller.rb`, missing `authorize @comment` call
-- Current mitigation: Obscured by UUID-based URLs (hard to guess)
-- Recommendations: Add Pundit `authorize` call or `before_action` scope check, add `CommentPolicy` with board-access verification
+- Current mitigation: Denormalise tables so all include account_id and rely on `Current.account` scope, but no explicit check on board access.
+- Recommendations: Add `before_action` scope check.
 
 **Unscoped queries leaking tenant data:**
 - Risk: `Admin::ReportsController` uses `Card.where(created_at: range)` without `Current.account` scope

data/data/ariadna/templates/codebase/conventions.md

@@ -251,7 +251,7 @@ end
 - Model validation errors re-render form with `@model.errors`
 
 **Error Types:**
-- Raise on authorization failures: `rescue_from Pundit::NotAuthorizedError`
+- Raise on authorization failures: `rescue_from NotAuthorizedError`
 - Raise on missing records: `rescue_from ActiveRecord::RecordNotFound`
 - Return `false`/`nil` for expected domain failures
 - Jobs: `retry_on` for transient failures (network, timeouts), `discard_on ActiveRecord::RecordNotFound`

data/data/ariadna/templates/codebase/stack.md

@@ -123,9 +123,8 @@ Template for `.planning/codebase/STACK.md` - captures the technology foundation.
 
 **Critical:**
 - authentication (built-in) — Session-based auth
-- pundit — Authorization
+- authorization - custom implementation (no gem) — Role-based access control, pundit
 - solid_queue — Background jobs (Rails 8 default)
-- stripe — Payment processing
 
 **Infrastructure:**
 - sqlite3 — SQLite adapter (Rails default)

data/data/ariadna/templates/research-project/ARCHITECTURE.md

@@ -164,7 +164,57 @@ test/                      # [test framework: Minitest (default) or spec/ if RSp
 ### Authentication and Authorization
 
 **Authentication:** [Rails authentication generator / has_secure_password / custom / other]
-**Authorization:** [Pundit / CanCanCan / custom / Action Policy / other]
+**Authorization:** [Custom / Pundit / CanCanCan / Action Policy / other]
+
+### Internationalization (I18n)
+
+**Configuration:**
+- Default locale: [discovered from `config.i18n.default_locale`]
+- Available locales: [discovered from `config.i18n.available_locales`]
+- Fallback chain: [discovered from `config.i18n.fallbacks`]
+
+**Locale file organization:**
+```
+config/locales/
+├── [default locale].yml            # [application-wide defaults]
+├── activerecord.[lang].yml         # [model and attribute translations]
+├── [feature].[lang].yml            # [per-feature locale files if present]
+└── [additional locale files discovered]
+```
+
+**ActiveRecord translations:**
+```yaml
+# config/locales/activerecord.[lang].yml
+[lang]:
+  activerecord:
+    models:
+      [model]: [translated model name]
+    attributes:
+      [model]:
+        [attribute]: [translated attribute name]
+```
+
+**Translation approach:**
+
+| Context | Recommended Approach | What This Project Does |
+|---------|---------------------|------------------------|
+| Model names | `activerecord.models.*` — automatic lookup by Rails | [discovered approach] |
+| Attribute names | `activerecord.attributes.*` — automatic lookup by `form.label`, validations, etc. | [discovered approach] |
+| Form labels | `form.label :name` — resolves from `activerecord.attributes` automatically | [discovered approach] |
+| Validation messages | `activerecord.errors.models.*` / `errors.messages.*` — automatic lookup | [discovered approach] |
+| View text | Lazy lookup `t(".title")` or explicit `t("views.controller.action.title")` | [discovered approach] |
+| Enum values | `activerecord.attributes.[model].[enum_attribute]/[value]` | [discovered approach] |
+| Flash messages | Controller lazy lookup `t(".success")` or explicit keys | [discovered approach] |
+| Mailer subjects | `I18n.t("mailer_name.action_name.subject")` — automatic from mailer class | [discovered approach] |
+
+**CLDR / base locale data:**
+- `rails-i18n` gem: [present/absent — provides date, time, currency, number formats for non-English locales]
+- Custom date/time formats: [discovered in locale files or initializers]
+
+**Example from codebase:**
+```ruby
+# [Brief code example showing the project's actual I18n usage pattern]
+```
 
 ## Data Flow
 
@@ -377,4 +427,13 @@ Client receives → DOM update
 - Note external API integration patterns and HTTP client choices
 - Look for engine boundaries and module interfaces
 
+**Internationalization (I18n):**
+- Check `config/application.rb` for `i18n.default_locale`, `i18n.available_locales`, and `i18n.fallbacks`
+- Inspect `config/locales/` file organization — per-model, per-feature, or flat structure
+- Look for `activerecord.models.*` and `activerecord.attributes.*` keys in locale files — these power automatic lookup for model names, form labels, and validation messages
+- Check whether form labels use automatic lookup (`form.label :name`) vs explicit `t()` calls — explicit calls duplicate what Rails provides for free
+- Check Gemfile for `rails-i18n` gem — provides CLDR base data (dates, times, currency, numbers) for non-English locales
+- Look for validation error message customization under `activerecord.errors.models.*`
+- Check for lazy lookup usage in views (`t(".key")`) and controllers
+
 </guidelines>