synthra 0.1.0

data/docs/USAGE_GUIDE.md

@@ -0,0 +1,980 @@
+# FakeDataDSL Usage Guide
+
+Complete guide on how to use FakeDataDSL: DSL syntax, types, formulas, unique constraints, and options.
+
+## Table of Contents
+
+- [Basic DSL Syntax](#basic-dsl-syntax)
+- [Types](#types)
+- [Formula](#formula)
+- [Unique Constraints](#unique-constraints)
+- [Options and Modifiers](#options-and-modifiers)
+- [Deterministic Generation (Same Data Every Time)](#deterministic-generation-same-data-every-time)
+- [Complete Examples](#complete-examples)
+
+---
+
+## Basic DSL Syntax
+
+### Schema Definition
+
+A schema starts with a name followed by a colon:
+
+```ruby
+SchemaName:
+  field1: type1
+  field2: type2
+```
+
+### Field Definition
+
+Basic field syntax:
+
+```
+field_name: type
+```
+
+**Example:**
+
+```ruby
+User:
+  id: uuid
+  name: name
+  email: email
+  age: number(18..65)
+```
+
+### Comments
+
+Use `#` for comments:
+
+```ruby
+User:
+  # Primary identifier
+  id: uuid
+  name: name  # User's full name
+  email: email
+```
+
+---
+
+## Types
+
+### Basic Types
+
+FakeDataDSL provides many built-in types:
+
+```ruby
+User:
+  # Identifiers
+  id: uuid
+  user_id: id_sequence
+  
+  # Text
+  name: name
+  first_name: first_name
+  last_name: last_name
+  email: email
+  bio: text(50..500)
+  username: username
+  
+  # Numbers
+  age: number(18..100)
+  score: number(min: 0, max: 100)
+  price: number(10.0..99.99)
+  
+  # Boolean
+  active: boolean
+  verified: boolean(true: 80%)  # 80% chance of true
+  
+  # Dates
+  created_at: timestamp
+  birth_date: date
+  last_login: past_date(days: 30)
+  
+  # Location
+  country: country
+  city: city
+  address: address
+  postal_code: postal_code
+  
+  # Internet
+  website: url
+  ip_address: ip
+  mac_address: mac_address
+  user_agent: user_agent
+```
+
+### Type Arguments
+
+Many types accept arguments to customize generation:
+
+#### Number with Range
+
+```ruby
+age: number(18..65)              # Range
+price: number(min: 10, max: 100) # Min/max
+score: number(0..100)            # Integer range
+```
+
+#### Text with Length
+
+```ruby
+title: text(10..50)    # 10-50 characters
+description: text(100) # Exactly 100 characters
+bio: text(min: 50, max: 500)
+```
+
+#### Enum with Weights
+
+```ruby
+status: enum(active, inactive, pending)
+priority: enum(low: 50%, medium: 30%, high: 20%)
+role: enum(user: 80%, admin: 10%, moderator: 10%)
+```
+
+#### Array Types
+
+```ruby
+tags: array(text, 3..10)           # Array of text, 3-10 items
+scores: array(number(0..100), 5)   # Array of numbers, exactly 5 items
+items: array(Item, 1..5)            # Array of nested schemas
+```
+
+#### Date Types
+
+```ruby
+created_at: timestamp
+birth_date: date
+last_week: past_date(days: 7)
+next_month: future_date(days: 30)
+between: date_between(start: "2024-01-01", end: "2024-12-31")
+```
+
+### All Available Types
+
+See [Type Reference](type_reference.md) for a complete list of all 80+ types including:
+
+- **Personal**: `first_name`, `last_name`, `full_name`, `gender`, `age`, `username`, `email`, `phone`, `national_id`
+- **Location**: `country`, `city`, `state`, `address`, `latitude`, `longitude`, `timezone`, `postal_code`
+- **Commerce**: `product_name`, `product_category`, `sku`, `price`, `discount`, `tax_rate`
+- **Finance**: `credit_card`, `bank_name`, `account_number`, `iban`, `money`, `currency`, `transaction_amount`
+- **Date & Time**: `date`, `time`, `datetime`, `timestamp`, `past_date`, `future_date`, `date_between`
+- **Internet/IT**: `uuid`, `ip`, `ipv6`, `mac_address`, `domain`, `url`, `user_agent`
+- **Crypto**: `hash`, `bitcoin_address`, `ethereum_address`, `private_key`
+- **Health**: `blood_type`, `bmi`, `heart_rate`, `medical_code`
+- **Travel**: `airport_code`, `airline`, `flight_number`, `seat_number`
+- **Advanced**: `sequence`, `default_value`, `formula`, `template`, `regex`, `json_array`
+
+---
+
+## Formula
+
+The `formula` type computes values from other fields using mathematical expressions.
+
+### Basic Formula
+
+```ruby
+Order:
+  quantity: number(1..10)
+  unit_price: number(10..100)
+  total: formula(quantity * unit_price)
+```
+
+**Generated Example:**
+```ruby
+{
+  "quantity" => 5,
+  "unit_price" => 50,
+  "total" => 250
+}
+```
+
+### Complex Formulas
+
+```ruby
+Order:
+  quantity: number(1..10)
+  unit_price: number(10..100)
+  subtotal: formula(quantity * unit_price)
+  tax_rate: number(0.05..0.15)
+  tax: formula(subtotal * tax_rate)
+  discount: number(0..20)
+  discount_amount: formula(subtotal * discount / 100)
+  total: formula(subtotal + tax - discount_amount)
+```
+
+**Generated Example:**
+```ruby
+{
+  "quantity" => 3,
+  "unit_price" => 75,
+  "subtotal" => 225,
+  "tax_rate" => 0.08,
+  "tax" => 18,
+  "discount" => 10,
+  "discount_amount" => 22.5,
+  "total" => 220.5
+}
+```
+
+### Formula Operations
+
+Formulas support:
+
+- **Arithmetic**: `+`, `-`, `*`, `/`, `%`
+- **Parentheses**: `(quantity * price) + tax`
+- **Field References**: Use field names directly in expressions
+- **Numbers**: `total * 0.08`, `price + 10`
+
+**Example:**
+
+```ruby
+Product:
+  base_price: number(10..100)
+  markup: number(1.1..1.5)
+  final_price: formula(base_price * markup)
+  shipping: number(5..15)
+  total: formula(final_price + shipping)
+```
+
+### Formula Limitations
+
+- Only works with **numeric** field values
+- Field must be generated **before** the formula field
+- Returns `0` if expression fails to evaluate
+- No string concatenation (use `template` type instead)
+
+---
+
+## Unique Constraints
+
+The `unique` modifier ensures generated values are unique within a batch.
+
+### Basic Unique
+
+```ruby
+User:
+  id: uuid unique
+  email: email unique
+  username: username unique
+```
+
+### Unique with Types
+
+```ruby
+Product:
+  sku: sku unique
+  code: text(10) unique
+  serial_number: sequence(start: 1000) unique
+```
+
+### Unique with Enums
+
+```ruby
+Order:
+  status: enum(pending, processing, completed) unique
+  # Each generated order will have a different status
+```
+
+### How Unique Works
+
+1. **Per-Batch**: Uniqueness is enforced within a single `generate_many` call
+2. **Retries**: Generator retries up to `max_unique_retries` times (default: 100)
+3. **Error**: Raises `UniquenessError` if unique value cannot be generated
+
+**Example:**
+
+```ruby
+registry = FakeDataDSL::Registry.new
+registry.load_string(<<~DSL)
+  User:
+    id: uuid unique
+    email: email unique
+DSL
+
+schema = registry.schema("User")
+
+# Generate 10 unique users
+users = schema.generate_many(10, seed: 42)
+# All users will have different IDs and emails
+```
+
+### Unique Configuration
+
+Configure max retries:
+
+```ruby
+FakeDataDSL.configure do |config|
+  config.max_unique_retries = 200  # Default: 100
+end
+```
+
+---
+
+## Options and Modifiers
+
+### Nullable Fields
+
+Add `?` to make a field nullable (can be `nil`):
+
+```ruby
+User:
+  middle_name: name?      # Type is nullable
+  nickname: text?          # May be nil
+  manager: User?          # Reference can be nil
+```
+
+### Optional Fields
+
+Use `optional` modifier to omit fields sometimes:
+
+```ruby
+User:
+  phone: phone optional      # May be omitted from output
+  address: address optional # Sometimes not included
+```
+
+**Difference:**
+- **Nullable (`?`)**: Field is always included, but value may be `nil`
+- **Optional**: Field may be completely omitted from output
+
+### Conditional Fields
+
+Use `if` to conditionally include fields:
+
+```ruby
+User:
+  is_admin: boolean
+  admin_note: text if is_admin        # Only if is_admin is true
+  employee_id: text if is_employee    # Only if is_employee is true
+```
+
+**Note**: The condition field must be defined **before** the conditional field.
+
+### Type Options
+
+Many types support options:
+
+#### Number Options
+
+```ruby
+age: number(18..65)              # Range
+price: number(min: 10, max: 100) # Named arguments
+score: number(0..100, precision: 2)  # With precision
+```
+
+#### Text Options
+
+```ruby
+title: text(10..50)                    # Length range
+description: text(min: 100, max: 500)  # Named arguments
+code: text(10, prefix: "CODE-")        # With prefix
+
+# Language support (English/Arabic)
+english_text: text(50, language: :en)   # English (default)
+arabic_text: text(50, language: :ar)    # Arabic
+arabic_text: text(50, lang: :arabic)    # Also accepts :arabic
+```
+
+#### Enum Options
+
+```ruby
+status: enum(active, inactive)
+priority: enum(low: 50%, medium: 30%, high: 20%)  # With weights
+role: enum(user: 80%, admin: 10%, moderator: 10%)  # Percentages
+```
+
+#### Array Options
+
+```ruby
+tags: array(text, 3..10)              # Element type and size
+items: array(Item, min: 1, max: 5)     # Named arguments
+scores: array(number(0..100), 5)       # Fixed size
+```
+
+#### Date Options
+
+```ruby
+created_at: timestamp
+last_week: past_date(days: 7)
+next_month: future_date(days: 30)
+between: date_between(start: "2024-01-01", end: "2024-12-31")
+```
+
+#### Sequence Options
+
+```ruby
+id: sequence(start: 1, step: 1)
+code: sequence(start: "A001", step: 1, format: "ID-%03d")
+```
+
+#### Template Options
+
+```ruby
+full_name: template("{{first_name}} {{last_name}}")
+email: template("{{username}}@example.com")
+```
+
+### Combining Modifiers
+
+You can combine multiple modifiers:
+
+```ruby
+User:
+  id: uuid unique                    # Unique constraint
+  email: email unique optional       # Unique and optional
+  nickname: text? optional           # Nullable and optional
+  admin_note: text? if is_admin      # Nullable and conditional
+```
+
+---
+
+## Deterministic Generation (Same Data Every Time)
+
+Use the `seed` parameter to generate the **same data every time**. This is essential for:
+- **Testing** - Reproducible test data
+- **Debugging** - Same data to debug issues
+- **Documentation** - Consistent examples
+- **CI/CD** - Predictable test results
+
+### Basic Usage
+
+```ruby
+require 'fake_data_dsl'
+
+registry = FakeDataDSL::Registry.new
+registry.load_string(<<~DSL)
+  User:
+    id: uuid
+    name: name
+    email: email
+    age: number(18..65)
+DSL
+
+schema = registry.schema("User")
+
+# Generate with seed - same data every time
+user1 = schema.generate(seed: 42)
+user2 = schema.generate(seed: 42)
+
+# user1 and user2 will be IDENTICAL
+puts user1 == user2  # => true
+```
+
+### Generate Multiple Records
+
+```ruby
+# Generate 10 records with same seed
+users1 = schema.generate_many(10, seed: 12345)
+users2 = schema.generate_many(10, seed: 12345)
+
+# All records will be identical
+users1.each_with_index do |user, i|
+  puts user == users2[i]  # => true for all
+end
+```
+
+### Different Seeds = Different Data
+
+```ruby
+# Different seeds produce different data
+user1 = schema.generate(seed: 42)
+user2 = schema.generate(seed: 43)
+
+puts user1 == user2  # => false (different data)
+```
+
+### Streaming with Seed
+
+```ruby
+# Streaming also supports seeds for determinism
+streamer = schema.generate_many_stream(count: 100, seed: 999)
+
+# All records will be deterministic
+streamer.each do |record|
+  # Process record
+end
+```
+
+### Complete Example
+
+```ruby
+require 'fake_data_dsl'
+
+# Define schema
+registry = FakeDataDSL::Registry.new
+registry.load_string(<<~DSL)
+  Product:
+    id: uuid
+    name: product_name
+    price: number(10..100)
+    category: product_category
+    in_stock: boolean
+DSL
+
+schema = registry.schema("Product")
+
+# Generate same product every time
+product = schema.generate(seed: 42)
+puts product
+# => {
+#   "id" => "550e8400-e29b-41d4-a716-446655440000",
+#   "name" => "Ergonomic Granite Chair",
+#   "price" => 45.67,
+#   "category" => "Electronics",
+#   "in_stock" => true
+# }
+
+# Generate again with same seed - IDENTICAL
+product2 = schema.generate(seed: 42)
+puts product == product2  # => true
+
+# Different seed - different data
+product3 = schema.generate(seed: 99)
+puts product == product3  # => false
+```
+
+### Seed Best Practices
+
+1. **Use Fixed Seeds for Tests**
+   ```ruby
+   # In your test
+   user = schema.generate(seed: 12345)
+   expect(user["age"]).to be_between(18, 65)
+   ```
+
+2. **Use Different Seeds for Variety**
+   ```ruby
+   # Generate varied test data
+   (1..100).each do |seed|
+     user = schema.generate(seed: seed)
+     # Each user will be different
+   end
+   ```
+
+3. **Store Seeds for Reproducibility**
+   ```ruby
+   # Save seed with generated data
+   seed = 42
+   user = schema.generate(seed: seed)
+   user["_seed"] = seed  # Store for later reproduction
+   ```
+
+4. **Seed Per Schema**
+   ```ruby
+   # Each schema can have different seeds
+   user = user_schema.generate(seed: 100)
+   order = order_schema.generate(seed: 200)
+   ```
+
+### Determinism Guarantees
+
+✅ **Guaranteed Deterministic:**
+- Same seed + same schema = **identical output**
+- Works across multiple runs
+- Works across different machines
+- Works with `generate`, `generate_many`, and `generate_many_stream`
+
+⚠️ **Not Deterministic:**
+- Without seed (uses random seed each time)
+- Different Ruby versions (may vary)
+- Different Faker versions (may vary)
+- Schema changes (different schema = different output)
+
+### Example: Testing with Seeds
+
+```ruby
+# spec/user_spec.rb
+RSpec.describe "User generation" do
+  let(:schema) do
+    registry = FakeDataDSL::Registry.new
+    registry.load_string(<<~DSL)
+      User:
+        id: uuid
+        name: name
+        email: email
+        age: number(18..65)
+    DSL
+    registry.schema("User")
+  end
+
+  it "generates consistent data with seed" do
+    user1 = schema.generate(seed: 42)
+    user2 = schema.generate(seed: 42)
+    
+    expect(user1).to eq(user2)
+    expect(user1["age"]).to be_between(18, 65)
+  end
+
+  it "generates different data with different seeds" do
+    user1 = schema.generate(seed: 1)
+    user2 = schema.generate(seed: 2)
+    
+    expect(user1).not_to eq(user2)
+  end
+end
+```
+
+### Configuration
+
+You can also set a default seed globally:
+
+```ruby
+FakeDataDSL.configure do |config|
+  # Note: There's no global seed setting, always pass seed explicitly
+  # This ensures explicit control over determinism
+end
+
+# Always pass seed explicitly for clarity
+schema.generate(seed: 42)
+```
+
+---
+
+## Fixed Values (Same Value Every Time)
+
+Sometimes you need specific fields to always have the **same value** every time you generate data, regardless of seed. This is useful for:
+- **Timestamps** - Fixed `created_at` for all records
+- **Constants** - Fixed status, category, or identifier
+- **Test Data** - Known values for testing
+
+### Method 1: Using `default_value` Type (Recommended)
+
+Use the `default_value` type to set a fixed value:
+
+```ruby
+User:
+  id: uuid unique
+  username: username unique
+  email: email unique
+  first_name: first_name
+  last_name: last_name
+  full_name: template("{{first_name}} {{last_name}}")
+  age: number(18..100)
+  gender: gender
+  phone: phone? optional
+  address: address? optional
+  is_admin: boolean(true: 10%)
+  admin_level: enum(none: 90%, moderator: 8%, admin: 2%) if is_admin
+  created_at: default_value(value: "2024-01-15 10:30:00 UTC")
+  last_login: past_date(days: 30)? optional
+```
+
+**For Timestamps:**
+
+```ruby
+User:
+  # Fixed timestamp (same for all records)
+  created_at: default_value(value: "2024-01-15T10:30:00Z")
+  
+  # Or use Time object format
+  updated_at: default_value(value: "2024-01-15 10:30:00 UTC")
+  
+  # Or Unix timestamp
+  timestamp: default_value(value: 1705315800)
+```
+
+**For Other Types:**
+
+```ruby
+Product:
+  # Fixed string
+  status: default_value(value: "active")
+  
+  # Fixed number
+  version: default_value(value: 1)
+  
+  # Fixed boolean
+  enabled: default_value(value: true)
+  
+  # Fixed array
+  tags: default_value(value: ["featured", "new"])
+```
+
+### Method 2: Using Overrides
+
+Override specific fields when generating:
+
+```ruby
+require 'fake_data_dsl'
+
+registry = FakeDataDSL::Registry.new
+registry.load_string(<<~DSL)
+  User:
+    id: uuid unique
+    username: username unique
+    email: email unique
+    created_at: timestamp
+DSL
+
+schema = registry.schema("User")
+
+# Generate with fixed created_at
+fixed_time = Time.parse("2024-01-15 10:30:00 UTC")
+
+user1 = schema.generate(
+  seed: 42,
+  overrides: { "created_at" => fixed_time }
+)
+
+user2 = schema.generate(
+  seed: 43,
+  overrides: { "created_at" => fixed_time }
+)
+
+# Both have same created_at
+puts user1["created_at"] == user2["created_at"]  # => true
+```
+
+**For Multiple Records:**
+
+```ruby
+fixed_time = Time.parse("2024-01-15 10:30:00 UTC")
+
+users = schema.generate_many(
+  10,
+  seed: 42,
+  overrides: { "created_at" => fixed_time }
+)
+
+# All users have the same created_at
+users.each do |user|
+  puts user["created_at"] == fixed_time  # => true
+end
+```
+
+### Method 3: Combining Seed + Overrides
+
+Use seed for most fields, but override specific ones:
+
+```ruby
+User:
+  id: uuid unique
+  username: username unique
+  email: email unique
+  first_name: first_name
+  last_name: last_name
+  full_name: template("{{first_name}} {{last_name}}")
+  age: number(18..100)
+  gender: gender
+  phone: phone? optional
+  address: address? optional
+  is_admin: boolean(true: 10%)
+  admin_level: enum(none: 90%, moderator: 8%, admin: 2%) if is_admin
+  created_at: timestamp  # Will be overridden
+  last_login: past_date(days: 30)? optional
+```
+
+```ruby
+# Generate with seed for randomness, but fixed created_at
+fixed_created_at = Time.parse("2024-01-15 10:30:00 UTC")
+
+user = schema.generate(
+  seed: 42,
+  overrides: { "created_at" => fixed_created_at }
+)
+
+# Other fields vary with seed, but created_at is always the same
+```
+
+### Complete Example
+
+```ruby
+require 'fake_data_dsl'
+
+registry = FakeDataDSL::Registry.new
+registry.load_string(<<~DSL)
+  User:
+    id: uuid unique
+    username: username unique
+    email: email unique
+    first_name: first_name
+    last_name: last_name
+    full_name: template("{{first_name}} {{last_name}}")
+    age: number(18..100)
+    gender: gender
+    phone: phone? optional
+    address: address? optional
+    is_admin: boolean(true: 10%)
+    admin_level: enum(none: 90%, moderator: 8%, admin: 2%) if is_admin
+    created_at: default_value(value: "2024-01-15 10:30:00 UTC")
+    last_login: past_date(days: 30)? optional
+DSL
+
+schema = registry.schema("User")
+
+# Generate multiple users - all have same created_at
+users = schema.generate_many(10, seed: 42)
+
+users.each do |user|
+  puts user["created_at"]  # => "2024-01-15 10:30:00 UTC" (same for all)
+  puts user["first_name"]  # => Different names (varies with seed)
+end
+```
+
+### When to Use Each Method
+
+**Use `default_value` when:**
+- ✅ Value should be the same in the DSL definition
+- ✅ Value is a constant that never changes
+- ✅ You want it defined in the schema itself
+
+**Use `overrides` when:**
+- ✅ Value needs to be set at generation time
+- ✅ Value might vary per batch but same within batch
+- ✅ You want flexibility to change it programmatically
+
+### Tips
+
+1. **Timestamp Format**: Use ISO 8601 format for timestamps:
+   ```ruby
+   created_at: default_value(value: "2024-01-15T10:30:00Z")
+   ```
+
+2. **Time Objects**: You can also use Time objects in overrides:
+   ```ruby
+   overrides: { "created_at" => Time.parse("2024-01-15 10:30:00 UTC") }
+   ```
+
+3. **Multiple Fixed Fields**: Set multiple fixed values:
+   ```ruby
+   overrides: {
+     "created_at" => fixed_time,
+     "status" => "active",
+     "version" => 1
+   }
+   ```
+
+---
+
+## Complete Examples
+
+### E-commerce Order
+
+```ruby
+Order:
+  id: uuid unique
+  order_number: sequence(start: 1000) unique
+  customer_id: uuid
+  items: array(OrderItem, 1..5)
+  subtotal: formula(items.map(&:total).sum)
+  tax_rate: number(0.05..0.15)
+  tax: formula(subtotal * tax_rate)
+  shipping: number(5..25)
+  total: formula(subtotal + tax + shipping)
+  status: enum(pending: 20%, processing: 30%, shipped: 40%, delivered: 10%)
+  created_at: timestamp
+  shipped_at: timestamp? optional
+
+OrderItem:
+  product_id: uuid
+  product_name: product_name
+  quantity: number(1..10)
+  unit_price: number(10..100)
+  total: formula(quantity * unit_price)
+```
+
+### User Profile
+
+```ruby
+User:
+  id: uuid unique
+  username: username unique
+  email: email unique
+  first_name: first_name
+  last_name: last_name
+  full_name: template("{{first_name}} {{last_name}}")
+  age: number(18..100)
+  gender: gender
+  phone: phone? optional
+  address: address? optional
+  is_admin: boolean(true: 10%)
+  admin_level: enum(none: 90%, moderator: 8%, admin: 2%) if is_admin
+  created_at: timestamp
+  last_login: past_date(days: 30)? optional
+```
+
+### Financial Transaction
+
+```ruby
+Transaction:
+  id: uuid unique
+  transaction_id: sequence(start: "TXN-0001", format: "TXN-%04d") unique
+  from_account: account_number
+  to_account: account_number
+  amount: transaction_amount(min: 1.0, max: 10000.0)
+  currency: currency
+  fee: formula(amount * 0.02)
+  total: formula(amount + fee)
+  status: enum(pending: 10%, processing: 20%, completed: 65%, failed: 5%)
+  created_at: timestamp
+  completed_at: timestamp? if status == "completed"
+```
+
+### Product Catalog
+
+```ruby
+Product:
+  id: uuid unique
+  sku: sku unique
+  name: product_name
+  category: product_category
+  description: text(50..500)
+  price: number(10.0..999.99, precision: 2)
+  discount: discount(min: 0, max: 50)
+  final_price: formula(price * (1 - discount / 100))
+  in_stock: boolean(true: 80%)
+  stock_quantity: number(0..1000) if in_stock
+  tags: array(text, 3..10)
+  created_at: timestamp
+```
+
+---
+
+## Quick Reference
+
+### Field Syntax
+
+```
+field_name: type(arguments) modifiers
+```
+
+### Common Modifiers
+
+- `unique` - Ensure unique values
+- `optional` - May be omitted
+- `?` - Nullable (can be nil)
+- `if condition` - Conditional field
+
+### Common Types
+
+- `uuid` - UUID v4
+- `name` - Full name
+- `email` - Email address
+- `number(range)` - Number in range
+- `text(length)` - Text with length
+- `boolean` - True/false
+- `enum(values)` - Enum with values
+- `array(type, size)` - Array of type
+- `formula(expression)` - Computed value
+- `sequence(start, step)` - Sequential values
+
+### Type Arguments
+
+- `number(18..65)` - Range
+- `number(min: 10, max: 100)` - Named arguments
+- `text(10..50)` - Length range
+- `enum(low: 50%, high: 50%)` - With weights
+- `array(text, 3..10)` - Element type and size
+
+---
+
+## Next Steps
+
+- [Getting Started](getting_started.md) - Quick start guide
+- [DSL Reference](dsl_reference.md) - Complete syntax reference
+- [Type Reference](type_reference.md) - All available types
+- [Examples](examples.md) - Real-world examples
+- [Advanced Features](advanced_features.md) - References, custom functions, streaming
+