familia 2.0.0.pre19 → 2.0.0.pre22

data/docs/guides/feature-relationships-methods.md

@@ -1,684 +1,226 @@
 # Relationship Methods Reference
 
-This guide provides detailed documentation for all methods automatically generated by Familia's relationships feature. Each relationship declaration creates a comprehensive set of methods for managing object associations, indexing, and tracking.
+Complete reference for methods generated by Familia's relationships feature. Each relationship declaration creates predictable, consistently-named methods on both participating classes.
 
-## Method Generation Overview
+## Quick Reference
 
-The relationships feature uses consistent naming patterns to generate methods based on your declarations. Understanding these patterns helps you predict and use the available methods effectively.
+### Basic Participation
 
-## Participation Methods (`participates_in`)
-
-### Basic Participation Declaration
+When `Domain` declares `participates_in Customer, :domains`:
 
 ```ruby
-class Domain < Familia::Horreum
-  feature :relationships
-  participates_in Customer, :domains
-end
-
-class Customer < Familia::Horreum
-  feature :relationships
-  set :domains  # Must define the collection
-end
-```
+# Target class (Customer) gets:
+customer.domains                          # Collection accessor
+customer.add_domains_instance(domain)     # Add single
+customer.add_domains([d1, d2])           # Add multiple
+customer.remove_domains_instance(domain)  # Remove
 
-### Generated Instance Methods
+# Participant class (Domain) gets:
+domain.add_to_customer_domains(customer)     # Add self
+domain.remove_from_customer_domains(customer) # Remove self
+domain.in_customer_domains?(customer)        # Check membership
+domain.score_in_customer_domains(customer)   # Get score (sorted_set)
 
-**On Domain instances:**
-- **`add_to_customer_domains(customer_obj_or_id)`** - Add this domain to customer's domains collection
-- **`remove_from_customer_domains(customer_obj_or_id)`** - Remove this domain from customer's domains collection
-- **`in_customer_domains?(customer_obj_or_id)`** - Check if this domain is in customer's domains collection
-
-```ruby
-domain = Domain.new(name: "example.com")
-customer = Customer.new(name: "Acme Corp")
-
-# Explicit method calls
-domain.add_to_customer_domains(customer)
-domain.in_customer_domains?(customer)        # => true
-domain.remove_from_customer_domains(customer)
-domain.in_customer_domains?(customer)        # => false
+# Reverse collection methods (Domain):
+domain.customer_instances    # Load Customer objects
+domain.customer_ids          # Just IDs
+domain.customer?            # Has any?
+domain.customer_count       # Count
 ```
 
-### Collection Operator Support
+## Participation Methods
 
-**Ruby-like syntax with automatic bidirectional updates:**
-```ruby
-customer.domains << domain                    # Equivalent to domain.add_to_customer_domains(customer)
-customer.domains.delete(domain.identifier)   # Removes relationship bidirectionally
-```
+### Target Class Methods
 
-### Method Naming Pattern
-`{action}_{to|from}_{lowercase_class_name}_{collection_name}` or `in_{lowercase_class_name}_{collection_name}?`
+The target class (specified in `participates_in`) receives collection management methods.
 
-## Class-Level Tracking Methods (`class_participates_in`)
-
-### Declaration
 ```ruby
-class Customer < Familia::Horreum
-  feature :relationships
-  class_participates_in :all_customers, score: :created_at
-  class_participates_in :active_customers, score: ->(customer) {
-    customer.status == 'active' ? customer.last_activity : 0
-  }
+class Domain < Familia::Horreum
+  participates_in Customer, :domains, score: :priority
 end
 ```
 
-### Generated Class Methods
+| Method | Description | Example |
+|--------|-------------|---------|
+| `domains` | Collection accessor | `customer.domains.size` |
+| `add_domains_instance(item, score)` | Add single item | `customer.add_domains_instance(domain, 100)` |
+| `add_domains([items])` | Bulk add | `customer.add_domains([d1, d2, d3])` |
+| `remove_domains_instance(item)` | Remove item | `customer.remove_domains_instance(domain)` |
 
-**Collection access:**
-- **`Customer.all_customers`** - Returns the sorted set collection directly
-- **`Customer.active_customers`** - Returns the active customers sorted set
+### Participant Class Methods
 
-**Manual management (rarely needed):**
-- **`Customer.add_to_all_customers(customer)`** - Manually add customer to tracking
-- **`Customer.remove_from_all_customers(customer)`** - Manually remove customer from tracking
+The participant class (calling `participates_in`) receives membership management methods.
 
-### Collection Operations
+| Method | Description | Example |
+|--------|-------------|---------|
+| `add_to_customer_domains(target, score)` | Add to target's collection | `domain.add_to_customer_domains(customer)` |
+| `remove_from_customer_domains(target)` | Remove from target's collection | `domain.remove_from_customer_domains(customer)` |
+| `in_customer_domains?(target)` | Check membership | `domain.in_customer_domains?(customer)` |
+| `score_in_customer_domains(target)` | Get score (sorted_set only) | `domain.score_in_customer_domains(customer)` |
+| `position_in_customer_domains(target)` | Get position (list only) | `domain.position_in_customer_domains(customer)` |
 
-```ruby
-# Query operations (delegated to underlying sorted set)
-Customer.all_customers.size                              # Count of tracked customers
-Customer.all_customers.range(0, 9)                      # First 10 customers (by score)
-Customer.all_customers.range_by_score(min_score, max_score)  # Customers in score range
-
-# Score-based queries
-recent_customers = Customer.all_customers.range_by_score(
-  (Time.now - 1.week).to_i, '+inf'
-)
-
-# Get customer with scores
-customers_with_scores = Customer.all_customers.range(0, -1, with_scores: true)
-# => [["customer_id_1", 1634567890], ["customer_id_2", 1634567920], ...]
-```
-
-### Automatic Behavior
-- Objects are **automatically added** to class-level tracking collections when saved
-- Objects are **automatically removed** when destroyed
-- Scores are **automatically calculated** using the provided field or lambda
-- No manual method calls required for basic lifecycle tracking
-
-### Scored Participation in Parent Collections
+### Reverse Collection Methods
 
-```ruby
-class User < Familia::Horreum
-  feature :relationships
-  participates_in Team, :active_users, score: :last_seen
-  participates_in Team, :top_performers, score: ->(user) { user.performance_score }
-end
+Participants also get methods to query all relationships of a given type.
 
-class Team < Familia::Horreum
-  feature :relationships
-  sorted_set :active_users, :top_performers
-end
-```
-
-**Generated methods on Team instances:**
-- **`team.active_users`** - Access the scored collection
-- **`team.top_performers`** - Access the performance-scored collection
-
-**Usage:**
-```ruby
-team = Team.new(name: "Development")
-user = User.new(name: "Alice", last_seen: Time.now.to_i)
-
-# User automatically added with score when relationship established
-team.active_users << user
-
-# Query by score ranges
-recently_active = team.active_users.range_by_score(
-  (Time.now - 1.hour).to_i, '+inf'
-)
-```
+| Method | Description | Returns |
+|--------|-------------|---------|
+| `customer_instances` | Load all related objects | `Array<Customer>` |
+| `customer_ids` | Get all related IDs | `Array<String>` |
+| `customer?` | Check if has any relationships | `Boolean` |
+| `customer_count` | Count relationships | `Integer` |
 
-## Indexing Methods (`indexed_by`)
+## Class-Level Participation
 
-The `indexed_by` declaration creates Valkey/Redis hash-based indexes for O(1) field lookups with automatic management.
-
-### Class-Level Indexing (`class_indexed_by`)
+### Declaration
 
 ```ruby
-class Customer < Familia::Horreum
-  feature :relationships
-  field :email, :username, :api_key
-
-  class_indexed_by :email, :email_lookup
-  class_indexed_by :username, :username_lookup
-  class_indexed_by :api_key, :api_key_lookup
+class User < Familia::Horreum
+  class_participates_in :all_users, score: :created_at
+  class_participates_in :active_users,
+    score: ->(u) { u.active? ? u.last_activity : 0 }
 end
 ```
 
-### Generated Class Methods
+### Generated Methods
 
-**Index access:**
-- **`Customer.email_lookup`** - Returns the hash index directly
-- **`Customer.username_lookup`** - Returns the username hash index
-- **`Customer.api_key_lookup`** - Returns the API key hash index
+| Level | Method | Description |
+|-------|--------|-------------|
+| **Class** | `User.all_users` | Collection accessor |
+| | `User.add_to_all_users(user, score)` | Manual add |
+| | `User.remove_from_all_users(user)` | Manual remove |
+| **Instance** | `user.add_to_class_all_users(score)` | Add self |
+| | `user.remove_from_class_all_users` | Remove self |
+| | `user.in_class_all_users?` | Check membership |
+| | `user.score_in_class_all_users` | Get score |
 
-**Convenience lookup methods:**
-- **`Customer.find_by_email(email)`** - Find customer ID by email (O(1) lookup)
-- **`Customer.find_by_username(username)`** - Find customer ID by username
-- **`Customer.find_by_api_key(api_key)`** - Find customer ID by API key
+## Indexing Methods
 
-### Generated Instance Methods (rarely used manually)
-
-**Index management:**
-- **`customer.add_to_class_email_lookup`** - Manually add to email index
-- **`customer.remove_from_class_email_lookup`** - Manually remove from email index
-- **`customer.update_class_email_lookup(old_email)`** - Update index when email changes
-
-### Usage Examples
+### Class-Level Unique Index
 
 ```ruby
-# Automatic indexing on save
-customer = Customer.new(
-  email: "alice@example.com",
-  username: "alice123",
-  api_key: "ak_abcd1234"
-)
-customer.save  # Automatically added to all indexes
-
-# O(1) lookups
-customer_id = Customer.find_by_email("alice@example.com")
-customer = Customer.load(customer_id) if customer_id
-
-# Direct index access
-all_emails = Customer.email_lookup.to_h
-# => {"alice@example.com" => "customer_1", "bob@example.com" => "customer_2"}
-
-# Index operations
-Customer.email_lookup.get("alice@example.com")  # => "customer_1"
-Customer.email_lookup.set("new@example.com", "customer_3")
-```
-
-### Automatic Behavior
-- Objects are **automatically indexed** when saved
-- Indexes are **automatically updated** when indexed fields change
-- Objects are **automatically removed** from indexes when destroyed
-- No manual index management required for standard lifecycle operations
-
-**Redis key pattern:** `{class_name.downcase}:{index_name}`
-
-### Relationship-Scoped Indexing (`indexed_by` with `target:`)
-
-```ruby
-class Customer < Familia::Horreum
-  feature :relationships
-  field :name
-  set :domains
-end
-
-class Domain < Familia::Horreum
-  feature :relationships
-  field :name, :subdomain, :port
-  participates_in Customer, :domains
-
-  # Index domains by name within each customer (domains can have same name across customers)
-  indexed_by :name, :domain_index, target: Customer
-  indexed_by :subdomain, :subdomain_index, target: Customer
-  indexed_by :port, :port_index, target: Customer
+class User < Familia::Horreum
+  unique_index :email, :email_lookup
+  unique_index :api_key, :api_key_lookup, query: false
 end
 ```
 
-### Generated Methods on Target Class (Customer)
-
-**Single lookups:**
-- **`customer.find_by_name(domain_name)`** - Find domain ID by name within this customer
-- **`customer.find_by_subdomain(subdomain)`** - Find domain ID by subdomain within this customer
-- **`customer.find_by_port(port)`** - Find domain ID by port within this customer
-
-**Multiple lookups:**
-- **`customer.find_all_by_name(domain_names)`** - Find multiple domain IDs by names
-- **`customer.find_all_by_subdomain(subdomains)`** - Find multiple domain IDs by subdomains
-- **`customer.find_all_by_port(ports)`** - Find multiple domain IDs by ports
-
-**Direct index access:**
-- **`customer.domain_index`** - Access the name index hash directly
-- **`customer.subdomain_index`** - Access the subdomain index hash directly
-- **`customer.port_index`** - Access the port index hash directly
-
-### Usage Examples
-
-```ruby
-customer = Customer.new(name: "Acme Corp")
-domain1 = Domain.new(name: "example.com", subdomain: "www", port: 443)
-domain2 = Domain.new(name: "api.example.com", subdomain: "api", port: 443)
-
-# Establish relationships (automatic indexing)
-customer.domains << domain1
-customer.domains << domain2
-
-# O(1) lookups within customer scope
-domain_id = customer.find_by_name("example.com")
-api_domain_id = customer.find_by_subdomain("api")
-
-# Multiple lookups
-ssl_domains = customer.find_all_by_port([443, 8443])
-
-# Direct index access
-all_domain_names = customer.domain_index.to_h
-# => {"example.com" => "domain_1", "api.example.com" => "domain_2"}
-
-# Check if customer has domain with specific name
-has_domain = customer.domain_index.get("example.com").present?
-```
-
-### Generated Methods on Indexed Class (Domain)
+| Method | Generated When | Description |
+|--------|---------------|-------------|
+| `User.find_by_email(email)` | `query: true` (default) | O(1) lookup |
+| `User.index_email_for(user)` | Always | Manual index |
+| `User.unindex_email_for(user)` | Always | Remove from index |
+| `User.reindex_email_for(user)` | Always | Update index |
 
-**Index management (automatic):**
-- **`domain.add_to_customer_domain_index(customer)`** - Add to customer's domain name index
-- **`domain.remove_from_customer_domain_index(customer)`** - Remove from customer's domain name index
-- **`domain.update_customer_domain_index(customer, old_name)`** - Update index when name changes
+### Instance-Scoped Unique Index
 
-### Automatic Behavior
-- Domain is **automatically indexed** when added to customer's domains collection
-- Index is **automatically updated** when domain's indexed fields change
-- Domain is **automatically removed** from index when relationship is removed
-- All index management happens transparently during relationship operations
-
-**Redis key pattern:** `{target_class.downcase}:{target_id}:{index_name}`
-
-### When to Use Each Indexing Context
-
-**Class-level indexing (`class_indexed_by`):**
-- Use for **system-wide unique** field lookups
-- Examples: email addresses, usernames, API keys, social security numbers
-- Best when field values should be unique across all instances
-
-**Relationship-scoped indexing (`indexed_by` with `target:`):**
-- Use for **context-specific** field lookups
-- Examples: domain names per customer, project names per team, usernames per organization
-- Best when field values are unique within a specific parent context but may duplicate across different parents
-
-## Complete API Reference
-
-### Method Naming Conventions
-
-**Participation methods:**
-- `{add_to|remove_from}_{target_class_downcase}_{collection_name}(target)`
-- `in_{target_class_downcase}_{collection_name}?(target)`
-
-**Class-level tracking:**
-- `{add_to|remove_from}_{collection_name}(object)` (class methods)
-- `{ClassName}.{collection_name}` (collection accessor)
-
-**Class-level indexing:**
-- `{add_to|remove_from}_class_{index_name}` (instance methods)
-- `{ClassName}.{index_name}` (index accessor)
-- `{ClassName}.find_by_{field_name}(value)` (convenience lookup)
-
-**Relationship-scoped indexing:**
-- `{target_instance}.find_by_{field_name}(value)` (single lookup)
-- `{target_instance}.find_all_by_{field_name}(values)` (multiple lookup)
-- `{target_instance}.{index_name}` (direct index access)
-
-## Key Benefits of the Relationships API
-
-- **Automatic Management**: Save operations update indexes and tracking automatically
-- **Ruby-Idiomatic**: Use `<<` operator for natural collection syntax
-- **Consistent Storage**: All indexes stored at class level for architectural simplicity
-- **Predictable Naming**: Method names follow consistent patterns for easy discovery
-- **O(1) Performance**: Hash-based indexes provide constant-time lookups
-- **Bidirectional Sync**: Relationship changes automatically update both sides
-
-## Advanced Implementation Patterns
-
-### Error Handling and Edge Cases
-
-**Handling Missing Objects:**
 ```ruby
-# Safe relationship operations
-begin
-  customer.domains << domain
-rescue Familia::Problem => e
-  Rails.logger.error "Failed to establish relationship: #{e.message}"
-end
-
-# Check if objects exist before relating
-if domain.persisted? && customer.persisted?
-  customer.domains << domain
-end
-
-# Batch operations with error handling
-domain_ids.each do |id|
-  next unless Domain.exists?(id)  # Custom existence check
-  customer.domains.add(id)
+class Employee < Familia::Horreum
+  unique_index :badge_number, :badge_index, within: Company
 end
 ```
 
-**Index Consistency Validation:**
-```ruby
-class Customer < Familia::Horreum
-  feature :relationships
-
-  def validate_email_index_consistency
-    stored_id = self.class.email_lookup.get(email)
-    return true if stored_id == identifier
+**Methods on scope class (Company):**
+| Method | Description |
+|--------|-------------|
+| `company.find_by_badge_number(badge)` | Find employee |
+| `company.index_badge_number_for(employee)` | Add to index |
+| `company.unindex_badge_number_for(employee)` | Remove from index |
 
-    Rails.logger.warn "Email index inconsistency: #{email} -> #{stored_id} vs #{identifier}"
-    # Repair the index
-    self.class.email_lookup.set(email, identifier)
-    false
-  end
+**Methods on indexed class (Employee):**
+| Method | Description |
+|--------|-------------|
+| `employee.add_to_company_badge_index(company)` | Add to company's index |
+| `employee.remove_from_company_badge_index(company)` | Remove from index |
+| `employee.in_company_badge_index?(company)` | Check if indexed |
 
-  after_save :validate_email_index_consistency
-end
-```
+### Multi-Value Index
 
-### Performance Optimization Techniques
-
-**Lazy Loading Patterns:**
 ```ruby
-class Customer < Familia::Horreum
-  feature :relationships
-  set :domains
-
-  # Memoized relationship loading
-  def domain_objects
-    @domain_objects ||= begin
-      domain_ids = domains.to_a
-      Domain.multiget(*domain_ids).compact
-    end
-  end
-
-  # Paginated relationship loading
-  def recent_domains(limit = 10)
-    recent_ids = domains.range(0, limit - 1)
-    Domain.multiget(*recent_ids).compact
-  end
-
-  # Selective field loading
-  def domain_names
-    domains.to_a.map do |id|
-      Domain.new(domain_id: id).name  # Load only name field
-    end
-  end
+class Employee < Familia::Horreum
+  multi_index :department, :dept_index, within: Company
 end
 ```
 
-**Bulk Operations with Transaction Safety:**
-```ruby
-class Team < Familia::Horreum
-  feature :relationships
-  set :members
-
-  def bulk_add_members(user_ids)
-    # Validate all IDs exist first
-    valid_ids = user_ids.select { |id| User.exists?(id) }
-
-    # Use Valkey/Redis pipeline for bulk operations
-    Familia.redis.pipelined do |pipeline|
-      valid_ids.each do |user_id|
-        members.add(user_id)
-        # Update reverse indexes in same pipeline
-        user = User.new(user_id: user_id)
-        user.add_to_team_members(self)
-      end
-    end
-
-    valid_ids.size
-  end
-
-  def bulk_remove_members(user_ids)
-    # Atomic bulk removal
-    removed_count = 0
-    user_ids.each do |user_id|
-      if members.delete(user_id)
-        removed_count += 1
-        # Clean up reverse relationship
-        user = User.new(user_id: user_id)
-        user.remove_from_team_members(self)
-      end
-    end
-    removed_count
-  end
-end
-```
+**Methods on scope class (Company):**
+| Method | Description |
+|--------|-------------|
+| `company.find_all_by_department(dept)` | Find all in department |
+| `company.sample_from_department(dept, count)` | Random sample |
 
-### Custom Scoring and Complex Relationships
+**Methods on indexed class (Employee):**
+| Method | Description |
+|--------|-------------|
+| `employee.add_to_company_dept_index(company)` | Add to index |
+| `employee.remove_from_company_dept_index(company)` | Remove from index |
 
-**Dynamic Scoring with Context:**
-```ruby
-class Project < Familia::Horreum
-  feature :relationships
-  field :priority, :created_at, :deadline
+## Method Naming Patterns
 
-  participates_in Team, :projects, score: :calculated_priority
+### Participation
 
-  private
+- **Target methods**: `{collection}`, `add_{collection}_instance`, `remove_{collection}_instance`
+- **Participant methods**: `{action}_to_{target_config_name}_{collection}`
+- **Reverse methods**: `{target_config_name}_instances`, `{target_config_name}_ids`
 
-  def calculated_priority
-    base_priority = priority.to_i
-    urgency_multiplier = deadline_urgency_factor
-    age_factor = project_age_factor
+### Indexing
 
-    (base_priority * urgency_multiplier * age_factor).to_i
-  end
+- **Class unique**: `find_by_{field}`, `index_{field}_for`, `unindex_{field}_for`
+- **Scoped unique**: `{scope}.find_by_{field}`, `{item}.add_to_{scope}_{index}`
+- **Multi-value**: `{scope}.find_all_by_{field}`, `{scope}.sample_from_{field}`
 
-  def deadline_urgency_factor
-    return 1.0 unless deadline
+## Common Usage Examples
 
-    days_until_deadline = (deadline.to_time - Time.now) / 1.day
-    return 3.0 if days_until_deadline <= 1  # Critical
-    return 2.0 if days_until_deadline <= 7  # High
-    1.0  # Normal
-  end
+### Establishing Relationships
 
-  def project_age_factor
-    days_old = (Time.now - created_at.to_time) / 1.day
-    [1.0 + (days_old / 30.0), 2.0].min  # Cap at 2x multiplier
-  end
-end
-```
-
-**Multi-Level Relationships:**
-```ruby
-class Organization < Familia::Horreum
-  feature :relationships
-  set :departments
-
-  # Find all users across all departments
-  def all_users
-    department_ids = departments.to_a
-    user_ids = []
-
-    department_ids.each do |dept_id|
-      dept = Department.load(dept_id)
-      user_ids.concat(dept.users.to_a) if dept
-    end
-
-    User.multiget(*user_ids.uniq).compact
-  end
-
-  # Hierarchical relationship queries
-  def users_in_department(department_name)
-    dept_id = find_by_name(department_name)
-    return [] unless dept_id
-
-    dept = Department.load(dept_id)
-    return [] unless dept
-
-    user_ids = dept.users.to_a
-    User.multiget(*user_ids).compact
-  end
-end
-```
-
-### Advanced Indexing Patterns
-
-**Composite Index Keys:**
 ```ruby
-class ApiKey < Familia::Horreum
-  feature :relationships
-  field :customer_id, :environment, :key_type, :key_hash
+# Single addition with auto-calculated score
+customer.add_domains_instance(domain)
 
-  # Composite index for environment + type lookups
-  indexed_by :environment_and_type, :env_type_lookup, target: Customer
+# Single addition with explicit score
+customer.add_domains_instance(domain, 100.0)
 
-  private
-
-  def environment_and_type
-    "#{environment}:#{key_type}"  # e.g., "production:read_write"
-  end
-end
+# Bulk addition
+customer.add_domains([domain1, domain2, domain3])
 
-# Usage
-customer.find_by_environment_and_type("production:read_only")
-customer.find_all_by_environment_and_type(["staging:read_write", "production:read_write"])
+# From participant side
+domain.add_to_customer_domains(customer)
 ```
 
-**Time-Based Index Partitioning:**
-```ruby
-class Event < Familia::Horreum
-  feature :relationships
-  field :event_type, :timestamp, :user_id
-
-  participates_in User, :events, score: :timestamp
-  indexed_by :daily_partition, :daily_events, target: User
-
-  private
+### Querying Relationships
 
-  def daily_partition
-    Time.at(timestamp).strftime('%Y%m%d')  # e.g., "20241215"
-  end
-end
-
-# Usage - find today's events for user
-today = Time.now.strftime('%Y%m%d')
-todays_event_ids = user.find_all_by_daily_partition([today])
-```
+```ruby
+# Check membership
+domain.in_customer_domains?(customer)  # => true/false
 
-### Testing Relationship Methods
+# Get all relationships
+domain.customer_instances  # => [customer1, customer2]
+domain.customer_ids        # => ["cust_123", "cust_456"]
+domain.customer_count      # => 2
 
-**Unit Testing Patterns:**
-```ruby
-# test/models/relationship_test.rb
-class RelationshipTest < Minitest::Test
-  def setup
-    @customer = Customer.create(email: "test@example.com", name: "Test Corp")
-    @domain = Domain.create(name: "test.com", status: "active")
-  end
-
-  def test_bidirectional_relationship_establishment
-    @customer.domains << @domain
-
-    # Test both sides of relationship
-    assert @customer.domains.member?(@domain.identifier)
-    assert @domain.in_customer_domains?(@customer.identifier)
-  end
-
-  def test_relationship_removal
-    @customer.domains << @domain
-    @customer.domains.delete(@domain.identifier)
-
-    # Verify complete cleanup
-    refute @customer.domains.member?(@domain.identifier)
-    refute @domain.in_customer_domains?(@customer.identifier)
-  end
-
-  def test_index_automatic_maintenance
-    @customer.save  # Should trigger indexing
-
-    found_id = Customer.find_by_email("test@example.com")
-    assert_equal @customer.identifier, found_id
-  end
-
-  def test_scoped_index_lookup
-    @customer.domains << @domain
-
-    found_id = @customer.find_by_name("test.com")
-    assert_equal @domain.identifier, found_id
-  end
-
-  def test_scored_relationship_ordering
-    project = Project.create(name: "Test Project")
-    task1 = Task.create(title: "Low priority", priority: 1)
-    task2 = Task.create(title: "High priority", priority: 10)
-
-    project.tasks << task1
-    project.tasks << task2
-
-    # Should be ordered by priority (high to low)
-    task_ids = project.tasks.range(0, -1, order: 'DESC')
-    assert_equal task2.identifier, task_ids.first
-    assert_equal task1.identifier, task_ids.last
-  end
-end
+# Direct collection access
+customer.domains.size      # Count
+customer.domains.to_a      # All IDs
+customer.domains.range(0, 9)  # First 10
 ```
 
-### Complete Production Example
+### Working with Indexes
 
 ```ruby
-# Real-world e-commerce system
-class Customer < Familia::Horreum
-  feature :relationships
-  field :email, :username, :tier, :created_at, :last_activity
-
-  # Global unique lookups
-  class_indexed_by :email, :email_lookup
-  class_indexed_by :username, :username_lookup
-
-  # Tiered customer tracking
-  class_participates_in :all_customers, score: :created_at
-  class_participates_in :active_customers, score: :last_activity
-  class_participates_in :premium_customers,
-    score: ->(c) { c.tier == 'premium' ? c.last_activity : 0 }
-
-  # Relationships
-  set :orders, :addresses, :payment_methods
-
-  def recent_orders(limit = 10)
-    order_ids = orders.range(0, limit - 1)
-    Order.multiget(*order_ids).compact
-  end
-
-  def total_spent
-    recent_orders(100).sum(&:total_amount)
-  end
-end
-
-class Order < Familia::Horreum
-  feature :relationships
-  field :total_amount, :status, :created_at, :order_number
-
-  participates_in Customer, :orders, score: :created_at
-  indexed_by :order_number, :order_lookup, target: Customer
-  indexed_by :status, :status_lookup, target: Customer
-
-  set :line_items
-end
-
-class Address < Familia::Horreum
-  feature :relationships
-  field :street, :city, :state, :zip_code, :address_type
-
-  participates_in Customer, :addresses
-  indexed_by :address_type, :address_type_lookup, target: Customer
-end
+# Automatic class-level indexing
+user = User.create(email: 'alice@example.com')
+User.find_by_email('alice@example.com')  # => user
 
-# Usage in production
-customer = Customer.create(
-  email: "alice@example.com",
-  username: "alice_smith",
-  tier: "premium"
-)
+# Manual scoped indexing
+employee.add_to_company_badge_index(company)
+company.find_by_badge_number('12345')    # => employee
 
-# Automatic indexing and tracking
-Customer.find_by_email("alice@example.com")  # => customer.identifier
-Customer.premium_customers.range(0, 9)       # Recent premium customers
-
-# Complex relationship queries
-order = Order.create(order_number: "ORD-12345", status: "shipped")
-customer.orders << order
-
-customer.find_by_order_number("ORD-12345")   # => order.identifier
-shipped_orders = customer.find_all_by_status(["shipped", "delivered"])
+# Multi-value indexing
+employee.add_to_company_dept_index(company)
+engineers = company.find_all_by_department('engineering')
 ```
 
----
-
 ## See Also
 
-- **[Relationships Feature Guide](feature-relationships.md)** - Conceptual introduction to relationships
-- **[Technical Reference](../reference/api-technical.md#relationships-feature-v200-pre7)** - Advanced implementation patterns
-- **[Feature System Guide](feature-system.md)** - Understanding Familia's feature architecture
+- [**Relationships Overview**](feature-relationships.md) - Core concepts and patterns
+- [**Participation Guide**](feature-relationships-participation.md) - Detailed participation docs
+- [**Indexing Guide**](feature-relationships-indexing.md) - Detailed indexing docs