htm 0.0.17 → 0.0.18

data/docs/api/yard/HTM/Database.md

@@ -8,10 +8,9 @@ initialization
 
 # Class Methods
 ## default_config() {: #method-c-default_config }
-Get default database configuration (respects RAILS_ENV)
+Get default database configuration (respects HTM_ENV)
 
-Uses ActiveRecordConfig which reads from config/database.yml and respects
-RAILS_ENV for environment-specific database selection.
+Uses HTM::Config for database settings.
 **`@return`** [Hash, nil] Connection configuration hash with PG-style keys
 
 ## drop(db_url nil) {: #method-c-drop }
@@ -37,7 +36,7 @@ comprehensive database documentation including:
 *   Table schemas with comments
 *   Index information
 *   Relationship diagrams
-**`@param`** [String] Database connection URL (uses ENV['HTM_DBURL'] if not provided)
+**`@param`** [String] Database connection URL (uses ENV['HTM_DATABASE__URL'] if not provided)
 
 **`@return`** [void] 
 
@@ -57,13 +56,13 @@ Uses psql to load the schema file
 
 ## migrate(db_url nil) {: #method-c-migrate }
 Run pending database migrations
-**`@param`** [String] Database connection URL (uses ENV['HTM_DBURL'] if not provided)
+**`@param`** [String] Database connection URL (uses ENV['HTM_DATABASE__URL'] if not provided)
 
 **`@return`** [void] 
 
 ## migration_status(db_url nil) {: #method-c-migration_status }
 Show migration status
-**`@param`** [String] Database connection URL (uses ENV['HTM_DBURL'] if not provided)
+**`@param`** [String] Database connection URL (uses ENV['HTM_DATABASE__URL'] if not provided)
 
 **`@return`** [void] 
 
@@ -85,13 +84,13 @@ Seed database with sample data
 Loads and executes db/seeds.rb file following Rails conventions. All seeding
 logic is contained in db/seeds.rb and reads data from markdown files in
 db/seed_data/ directory.
-**`@param`** [String] Database connection URL (uses ENV['HTM_DBURL'] if not provided)
+**`@param`** [String] Database connection URL (uses ENV['HTM_DATABASE__URL'] if not provided)
 
 **`@return`** [void] 
 
 ## setup(db_url nil, run_migrations: true, dump_schema: false) {: #method-c-setup }
 Set up the HTM database schema
-**`@param`** [String] Database connection URL (uses ENV['HTM_DBURL'] if not provided)
+**`@param`** [String] Database connection URL (uses ENV['HTM_DATABASE__URL'] if not provided)
 
 **`@param`** [Boolean] Whether to run migrations (default: true)
 

data/docs/api/yard/HTM/JobAdapter.md

@@ -18,7 +18,7 @@ Supported backends:
 **`@example`**
 ```ruby
 HTM.configure do |config|
-  config.job_backend = :active_job
+  config.job.backend = :active_job
 end
 ```
 **`@example`**

data/docs/api/yard/HTM/Railtie.md

@@ -20,8 +20,8 @@ This railtie automatically configures HTM when Rails boots:
 ```ruby
 # config/initializers/htm.rb
 HTM.configure do |config|
-  config.embedding_model = 'custom-model'
-  config.tag_model = 'custom-tag-model'
+  config.embedding.model = 'custom-model'
+  config.tag.model = 'custom-tag-model'
 end
 ```
 

data/docs/architecture/adrs/001-postgresql-timescaledb.md

@@ -145,7 +145,7 @@ CREATE INDEX nodes_type_idx ON nodes (type);
 
 ```ruby
 # Via environment variable (preferred)
-ENV['HTM_DBURL'] = "postgresql://user:pass@host:port/dbname?sslmode=require"
+ENV['HTM_DATABASE__URL'] = "postgresql://user:pass@host:port/dbname?sslmode=require"
 
 # Parsed into connection hash
 {

data/docs/architecture/adrs/011-pgai-integration.md

@@ -273,7 +273,7 @@ LIMIT $3;
 ruby enable_extensions.rb
 
 # 2. Run database schema with triggers
-psql $HTM_DBURL < sql/schema.sql
+psql $HTM_DATABASE__URL < sql/schema.sql
 
 # 3. Use HTM normally - embeddings automatic!
 ruby -r ./lib/htm -e "HTM.new(robot_name: 'Bot').add_node('test', 'value')"
@@ -283,16 +283,16 @@ ruby -r ./lib/htm -e "HTM.new(robot_name: 'Bot').add_node('test', 'value')"
 
 ```bash
 # 1. Backup database
-pg_dump $HTM_DBURL > htm_backup.sql
+pg_dump $HTM_DATABASE__URL > htm_backup.sql
 
 # 2. Enable pgai extension
 ruby enable_extensions.rb
 
 # 3. Apply new schema (adds triggers)
-psql $HTM_DBURL < sql/schema.sql
+psql $HTM_DATABASE__URL < sql/schema.sql
 
 # 4. (Optional) Regenerate embeddings with new model
-psql $HTM_DBURL -c "UPDATE nodes SET value = value;"
+psql $HTM_DATABASE__URL -c "UPDATE nodes SET value = value;"
 # This triggers embedding regeneration for all nodes
 ```
 

data/docs/database_rake_tasks.md

@@ -143,7 +143,7 @@ Opens an interactive PostgreSQL console (psql).
 
 **What it does:**
 - Launches `psql` connected to your HTM database
-- Uses connection parameters from `HTM_DBURL` or `.envrc`
+- Uses connection parameters from `HTM_DATABASE__URL` or `.envrc`
 - Allows you to run SQL queries directly
 
 **Example:**
@@ -237,7 +237,7 @@ rake htm:db:info
 
 ### Method 2: Manual Export
 ```bash
-export HTM_DBURL="postgresql://user:password@host:port/dbname?sslmode=require"
+export HTM_DATABASE__URL="postgresql://user:password@host:port/dbname?sslmode=require"
 rake htm:db:info
 ```
 
@@ -293,12 +293,12 @@ rake htm:db:migrate       # Run new migrations only
 
 ### "Database configuration not found"
 - Run `direnv allow` in the project directory
-- Or manually export `HTM_DBURL`
-- Verify: `echo $HTM_DBURL`
+- Or manually export `HTM_DATABASE__URL`
+- Verify: `echo $HTM_DATABASE__URL`
 
 ### "Connection refused"
 - Check database is running
-- Verify host/port in `HTM_DBURL`
+- Verify host/port in `HTM_DATABASE__URL`
 - Test: `rake htm:db:test`
 
 ### "Extension not found"

data/docs/development/rake-tasks.md

@@ -56,7 +56,7 @@ Running migrations...
 
 **What it does:**
 
-- Connects to PostgreSQL using `HTM_DBURL`
+- Connects to PostgreSQL using `HTM_DATABASE__URL`
 - Verifies required extensions (pgvector, pg_trgm)
 - Creates all HTM tables (robots, nodes, tags, file_sources, etc.)
 - Runs all pending ActiveRecord migrations
@@ -906,7 +906,7 @@ Rebuilding tags for 1,542 nodes...
 bundle install
 
 # Set database URL
-export HTM_DBURL="postgresql://user@localhost:5432/htm_development"
+export HTM_DATABASE__URL="postgresql://user@localhost:5432/htm_development"
 
 # Create and setup database
 rake htm:db:create
@@ -1012,17 +1012,17 @@ All tasks require database configuration. Set one of these:
 
 | Variable | Description |
 |----------|-------------|
-| `HTM_DBURL` | Full PostgreSQL connection URL (preferred) |
-| `HTM_DBHOST` | Database host |
-| `HTM_DBPORT` | Database port |
-| `HTM_DBNAME` | Database name |
-| `HTM_DBUSER` | Database username |
-| `HTM_DBPASS` | Database password |
+| `HTM_DATABASE__URL` | Full PostgreSQL connection URL (preferred) |
+| `HTM_DATABASE__HOST` | Database host |
+| `HTM_DATABASE__PORT` | Database port |
+| `HTM_DATABASE__NAME` | Database name |
+| `HTM_DATABASE__USER` | Database username |
+| `HTM_DATABASE__PASSWORD` | Database password |
 
 **Example:**
 
 ```bash
-export HTM_DBURL="postgresql://user:password@localhost:5432/htm_development"
+export HTM_DATABASE__URL="postgresql://user:password@localhost:5432/htm_development"
 ```
 
 ---
@@ -1031,10 +1031,10 @@ export HTM_DBURL="postgresql://user:password@localhost:5432/htm_development"
 
 ### "Database configuration not found"
 
-Set the `HTM_DBURL` environment variable:
+Set the `HTM_DATABASE__URL` environment variable:
 
 ```bash
-export HTM_DBURL="postgresql://user@localhost:5432/htm_development"
+export HTM_DATABASE__URL="postgresql://user@localhost:5432/htm_development"
 ```
 
 ### "Extension not found"

data/docs/development/setup.md

@@ -187,11 +187,11 @@ Create or edit `~/.bashrc__tiger`:
 ```bash
 # TimescaleDB Connection Configuration
 export HTM_SERVICE_NAME="db-67977"  # Your service name
-export HTM_DBNAME="tsdb"
-export HTM_DBUSER="tsdbadmin"
-export HTM_DBPASS="your_password_here"
-export HTM_DBPORT="37807"  # Your port number
-export HTM_DBURL="postgres://tsdbadmin:your_password@host:port/tsdb?sslmode=require"
+export HTM_DATABASE__NAME="tsdb"
+export HTM_DATABASE__USER="tsdbadmin"
+export HTM_DATABASE__PASSWORD="your_password_here"
+export HTM_DATABASE__PORT="37807"  # Your port number
+export HTM_DATABASE__URL="postgres://tsdbadmin:your_password@host:port/tsdb?sslmode=require"
 ```
 
 Replace the placeholders with your actual connection details.
@@ -236,11 +236,11 @@ docker-compose up -d
 # Configure environment variables
 cat > ~/.bashrc__tiger <<'EOF'
 export HTM_SERVICE_NAME="local-dev"
-export HTM_DBNAME="tsdb"
-export HTM_DBUSER="tsdbadmin"
-export HTM_DBPASS="devpassword"
-export HTM_DBPORT="5432"
-export HTM_DBURL="postgres://tsdbadmin:devpassword@localhost:5432/tsdb?sslmode=disable"
+export HTM_DATABASE__NAME="tsdb"
+export HTM_DATABASE__USER="tsdbadmin"
+export HTM_DATABASE__PASSWORD="devpassword"
+export HTM_DATABASE__PORT="5432"
+export HTM_DATABASE__URL="postgres://tsdbadmin:devpassword@localhost:5432/tsdb?sslmode=disable"
 EOF
 
 source ~/.bashrc__tiger
@@ -364,7 +364,7 @@ You can also run the schema SQL directly:
 
 ```bash
 # Using psql
-psql $HTM_DBURL -f sql/schema.sql
+psql $HTM_DATABASE__URL -f sql/schema.sql
 
 # Or using Ruby
 ruby -r ./lib/htm -e "HTM::Database.setup"
@@ -478,11 +478,11 @@ HTM uses environment variables for configuration. Here's a complete reference:
 
 | Variable | Description | Example |
 |----------|-------------|---------|
-| `HTM_DBURL` | Full PostgreSQL connection URL (preferred) | `postgres://user:pass@host:port/db?sslmode=require` |
-| `HTM_DBNAME` | Database name | `tsdb` |
-| `HTM_DBUSER` | Database username | `tsdbadmin` |
-| `HTM_DBPASS` | Database password | `your_password` |
-| `HTM_DBPORT` | Database port | `37807` |
+| `HTM_DATABASE__URL` | Full PostgreSQL connection URL (preferred) | `postgres://user:pass@host:port/db?sslmode=require` |
+| `HTM_DATABASE__NAME` | Database name | `tsdb` |
+| `HTM_DATABASE__USER` | Database username | `tsdbadmin` |
+| `HTM_DATABASE__PASSWORD` | Database password | `your_password` |
+| `HTM_DATABASE__PORT` | Database port | `37807` |
 | `HTM_SERVICE_NAME` | Service identifier (informational) | `db-67977` |
 
 ### Ollama Variables
@@ -515,10 +515,10 @@ source ~/.bashrc__tiger
 
 ```bash
 # Verify environment variables are set
-echo $HTM_DBURL
+echo $HTM_DATABASE__URL
 
 # Test connection directly with psql
-psql $HTM_DBURL
+psql $HTM_DATABASE__URL
 
 # Check if service is running (TimescaleDB Cloud)
 # Visit your Timescale Cloud dashboard
@@ -559,7 +559,7 @@ ollama pull gpt-oss
 ruby enable_extensions.rb
 
 # Check extension status
-psql $HTM_DBURL -c "SELECT extname, extversion FROM pg_extension ORDER BY extname"
+psql $HTM_DATABASE__URL -c "SELECT extname, extversion FROM pg_extension ORDER BY extname"
 
 # For TimescaleDB Cloud, extensions should be pre-installed
 # For local PostgreSQL, ensure you're using timescale/timescaledb-ha image
@@ -615,11 +615,11 @@ If you see SSL certificate errors:
 
 ```bash
 # Ensure sslmode is set in connection URL
-echo $HTM_DBURL | grep sslmode
+echo $HTM_DATABASE__URL | grep sslmode
 # Should show: sslmode=require
 
 # For local development without SSL
-export HTM_DBURL="postgres://user:pass@localhost:5432/tsdb?sslmode=disable"
+export HTM_DATABASE__URL="postgres://user:pass@localhost:5432/tsdb?sslmode=disable"
 ```
 
 ### Ruby Version Issues

data/docs/development/testing.md

@@ -244,7 +244,7 @@ Testing with real database:
 ```ruby
 class DatabaseIntegrationTest < Minitest::Test
   def setup
-    skip "Database not configured" unless ENV['HTM_DBURL']
+    skip "Database not configured" unless ENV['HTM_DATABASE__URL']
 
     @htm = HTM.new(
       robot_name: "Test Robot",

data/docs/getting-started/installation.md

@@ -103,24 +103,24 @@ CREATE EXTENSION IF NOT EXISTS pg_trgm;
 
 ```bash
 # Add to ~/.bashrc or your preferred config file
-export HTM_DBURL="postgres://username:password@localhost:5432/htm_db"
-export HTM_DBNAME="htm_db"
-export HTM_DBUSER="your_username"
-export HTM_DBPASS="your_password"
-export HTM_DBPORT="5432"
-export HTM_DBHOST="localhost"
+export HTM_DATABASE__URL="postgres://username:password@localhost:5432/htm_db"
+export HTM_DATABASE__NAME="htm_db"
+export HTM_DATABASE__USER="your_username"
+export HTM_DATABASE__PASSWORD="your_password"
+export HTM_DATABASE__PORT="5432"
+export HTM_DATABASE__HOST="localhost"
 
 # Load the configuration
 source ~/.bashrc
 ```
 
 !!! tip "Environment Configuration"
-    HTM automatically uses the `HTM_DBURL` environment variable if available. You can also pass database configuration directly to `HTM.new()`.
+    HTM automatically uses the `HTM_DATABASE__URL` environment variable if available. You can also pass database configuration directly to `HTM.new()`.
 
 Set environment variable:
 
 ```bash
-export HTM_DBURL="postgres://localhost/htm_db"
+export HTM_DATABASE__URL="postgres://localhost/htm_db"
 ```
 
 ## Step 3: Enable PostgreSQL Extensions
@@ -139,7 +139,7 @@ Test your database connection and verify extensions:
 cd /path/to/your/project
 ruby -e "
 require 'pg'
-conn = PG.connect(ENV['HTM_DBURL'])
+conn = PG.connect(ENV['HTM_DATABASE__URL'])
 result = conn.exec('SELECT extname, extversion FROM pg_extension ORDER BY extname')
 result.each { |row| puts \"✓ #{row['extname']}: Version #{row['extversion']}\" }
 conn.close
@@ -352,11 +352,11 @@ HTM uses the following environment variables:
 
 | Variable | Description | Default | Required |
 |----------|-------------|---------|----------|
-| `HTM_DBURL` | PostgreSQL connection URL | - | Yes |
-| `HTM_DBNAME` | Database name | `htm_db` | No |
-| `HTM_DBUSER` | Database user | `postgres` | No |
-| `HTM_DBPASS` | Database password | - | No |
-| `HTM_DBPORT` | Database port | `5432` | No |
+| `HTM_DATABASE__URL` | PostgreSQL connection URL | - | Yes |
+| `HTM_DATABASE__NAME` | Database name | `htm_db` | No |
+| `HTM_DATABASE__USER` | Database user | `postgres` | No |
+| `HTM_DATABASE__PASSWORD` | Database password | - | No |
+| `HTM_DATABASE__PORT` | Database port | `5432` | No |
 | `OLLAMA_URL` | Ollama API URL | `http://localhost:11434` | No |
 
 ### Example Configuration File
@@ -365,7 +365,7 @@ Create a configuration file for easy loading:
 
 ```bash
 # ~/.bashrc__htm
-export HTM_DBURL="postgres://user:pass@host:port/db?sslmode=require"
+export HTM_DATABASE__URL="postgres://user:pass@host:port/db?sslmode=require"
 export OLLAMA_URL="http://localhost:11434"
 ```
 
@@ -385,11 +385,11 @@ source ~/.bashrc__htm
 **Solutions**:
 
 ```bash
-# 1. Verify HTM_DBURL is set
-echo $HTM_DBURL
+# 1. Verify HTM_DATABASE__URL is set
+echo $HTM_DATABASE__URL
 
 # 2. Test connection manually
-psql $HTM_DBURL
+psql $HTM_DATABASE__URL
 
 # 3. Check if PostgreSQL is running (local installs)
 pg_ctl status
@@ -433,7 +433,7 @@ make
 sudo make install
 
 # Enable in database
-psql $HTM_DBURL -c "CREATE EXTENSION IF NOT EXISTS pgvector;"
+psql $HTM_DATABASE__URL -c "CREATE EXTENSION IF NOT EXISTS pgvector;"
 ```
 
 ### Ruby Version Issues
@@ -462,7 +462,7 @@ ruby --version
 
 ```bash
 # Ensure your database user has necessary permissions
-psql $HTM_DBURL -c "
+psql $HTM_DATABASE__URL -c "
   GRANT ALL PRIVILEGES ON DATABASE your_db TO your_user;
   GRANT ALL ON ALL TABLES IN SCHEMA public TO your_user;
 "

data/docs/getting-started/quick-start.md

@@ -125,10 +125,10 @@ Create an HTM instance for your robot:
 ```ruby
 # Configure HTM globally (optional - uses Ollama by default)
 HTM.configure do |config|
-  config.embedding_provider = :ollama
-  config.embedding_model = 'nomic-embed-text:latest'
-  config.tag_provider = :ollama
-  config.tag_model = 'gemma3:latest'
+  config.embedding.provider = :ollama
+  config.embedding.model = 'nomic-embed-text:latest'
+  config.tag.provider = :ollama
+  config.tag.model = 'gemma3:latest'
 end
 
 # Initialize HTM with a robot name
@@ -338,10 +338,10 @@ puts "=" * 60
 
 # Step 1: Configure and initialize HTM
 HTM.configure do |config|
-  config.embedding_provider = :ollama
-  config.embedding_model = 'nomic-embed-text:latest'
-  config.tag_provider = :ollama
-  config.tag_model = 'gemma3:latest'
+  config.embedding.provider = :ollama
+  config.embedding.model = 'nomic-embed-text:latest'
+  config.tag.provider = :ollama
+  config.tag.model = 'gemma3:latest'
 end
 
 htm = HTM.new(
@@ -522,8 +522,8 @@ htm = HTM.new(
 
 # Try different embedding models via configure
 HTM.configure do |config|
-  config.embedding_provider = :ollama
-  config.embedding_model = 'llama3:latest'  # Use Llama3
+  config.embedding.provider = :ollama
+  config.embedding.model = 'llama3:latest'  # Use Llama3
 end
 
 # Try different recall strategies
@@ -606,10 +606,10 @@ curl http://localhost:11434/api/version
 
 ### Issue: "Database connection failed"
 
-**Solution**: Verify your `HTM_DBURL` is set:
+**Solution**: Verify your `HTM_DATABASE__URL` is set:
 
 ```bash
-echo $HTM_DBURL
+echo $HTM_DATABASE__URL
 # Should show your connection string
 ```
 

data/docs/guides/getting-started.md

@@ -55,10 +55,10 @@ HTM requires a TimescaleDB database. Set your database connection:
 
 ```bash
 # Add to your .bashrc or .zshrc
-export HTM_DBURL="postgresql://user:password@host:port/database"
+export HTM_DATABASE__URL="postgresql://user:password@host:port/database"
 
 # Or create a config file
-echo "export HTM_DBURL='your-connection-string'" > ~/.bashrc__tiger
+echo "export HTM_DATABASE__URL='your-connection-string'" > ~/.bashrc__tiger
 source ~/.bashrc__tiger
 ```
 

data/docs/guides/long-term-memory.md

@@ -803,7 +803,7 @@ begin
   conn.close
 rescue PG::Error => e
   puts "Connection failed: #{e.message}"
-  puts "Check HTM_DBURL environment variable"
+  puts "Check HTM_DATABASE__URL environment variable"
 end
 ```
 

data/docs/guides/mcp-server.md

@@ -26,7 +26,7 @@ Before using the MCP server, ensure you have:
 
 2. **PostgreSQL database set up**
    ```bash
-   export HTM_DBURL="postgresql://user@localhost:5432/htm_development"
+   export HTM_DATABASE__URL="postgresql://user@localhost:5432/htm_development"
    htm_mcp setup
    ```
 
@@ -66,7 +66,7 @@ The `htm_mcp` executable includes management commands for database setup and dia
 
 ```bash
 # Set your database URL
-export HTM_DBURL="postgresql://user@localhost:5432/htm_development"
+export HTM_DATABASE__URL="postgresql://user@localhost:5432/htm_development"
 
 # Initialize the database
 htm_mcp setup
@@ -745,7 +745,7 @@ Add to `~/.config/claude/claude_desktop_config.json` (Linux/macOS) or `%APPDATA%
     "htm-memory": {
       "command": "htm_mcp",
       "env": {
-        "HTM_DBURL": "postgresql://user@localhost:5432/htm_development"
+        "HTM_DATABASE__URL": "postgresql://user@localhost:5432/htm_development"
       }
     }
   }
@@ -760,7 +760,7 @@ If `htm_mcp` is not in your PATH, use the absolute path:
     "htm-memory": {
       "command": "/path/to/htm_mcp",
       "env": {
-        "HTM_DBURL": "postgresql://user@localhost:5432/htm_development"
+        "HTM_DATABASE__URL": "postgresql://user@localhost:5432/htm_development"
       }
     }
   }
@@ -782,7 +782,7 @@ Add to `~/.claude/claude_code_config.json`:
     "htm-memory": {
       "command": "htm_mcp",
       "env": {
-        "HTM_DBURL": "postgresql://user@localhost:5432/htm_development"
+        "HTM_DATABASE__URL": "postgresql://user@localhost:5432/htm_development"
       }
     }
   }
@@ -812,7 +812,7 @@ mcp_servers:
   htm-memory:
     command: htm_mcp
     env:
-      HTM_DBURL: postgresql://user@localhost:5432/htm_development
+      HTM_DATABASE__URL: postgresql://user@localhost:5432/htm_development
 ```
 
 For project-specific configuration, add to `.aia/config.yml` in your project root:
@@ -822,7 +822,7 @@ mcp_servers:
   htm-memory:
     command: htm_mcp
     env:
-      HTM_DBURL: postgresql://user@localhost:5432/my_project_htm
+      HTM_DATABASE__URL: postgresql://user@localhost:5432/my_project_htm
 ```
 
 ## Usage Examples
@@ -952,9 +952,9 @@ This will find `database:postgresql` even with the typo.
 gem install fast-mcp
 ```
 
-**Error: `HTM_DBURL not set`**
+**Error: `HTM_DATABASE__URL not set`**
 ```bash
-export HTM_DBURL="postgresql://user@localhost:5432/htm_development"
+export HTM_DATABASE__URL="postgresql://user@localhost:5432/htm_development"
 ```
 
 ### Database Connection Issues
@@ -982,7 +982,7 @@ psql htm_development -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;"
 **Claude Code doesn't recognize tools:**
 1. Run `/mcp` to refresh MCP connections
 2. Verify config is valid JSON
-3. Check that HTM_DBURL is set in the env section
+3. Check that HTM_DATABASE__URL is set in the env section
 
 ### Embedding/Tag Errors
 
@@ -1011,17 +1011,17 @@ Run `htm_mcp help` for a complete list. Key variables:
 
 | Variable | Description |
 |----------|-------------|
-| `HTM_DBURL` | PostgreSQL connection URL (e.g., `postgresql://user:pass@localhost:5432/htm_development`) |
+| `HTM_DATABASE__URL` | PostgreSQL connection URL (e.g., `postgresql://user:pass@localhost:5432/htm_development`) |
 
-### Database (alternative to HTM_DBURL)
+### Database (alternative to HTM_DATABASE__URL)
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `HTM_DBNAME` | Database name | - |
-| `HTM_DBHOST` | Database host | `localhost` |
-| `HTM_DBPORT` | Database port | `5432` |
-| `HTM_DBUSER` | Database username | - |
-| `HTM_DBPASS` | Database password | - |
+| `HTM_DATABASE__NAME` | Database name | - |
+| `HTM_DATABASE__HOST` | Database host | `localhost` |
+| `HTM_DATABASE__PORT` | Database port | `5432` |
+| `HTM_DATABASE__USER` | Database username | - |
+| `HTM_DATABASE__PASSWORD` | Database password | - |
 | `HTM_DBSSLMODE` | SSL mode | `prefer` |
 
 ### LLM Providers

data/docs/guides/robot-groups.md

@@ -89,10 +89,10 @@ require 'htm'
 
 # Configure HTM
 HTM.configure do |config|
-  config.embedding_provider = :ollama
-  config.embedding_model = 'nomic-embed-text'
-  config.tag_provider = :ollama
-  config.tag_model = 'llama3'
+  config.embedding.provider = :ollama
+  config.embedding.model = 'nomic-embed-text'
+  config.tag.provider = :ollama
+  config.tag.model = 'llama3'
 end
 
 # Create a robot group with active and passive members
@@ -386,8 +386,8 @@ group_name = 'distributed-service'
 
 # Configure HTM
 HTM.configure do |config|
-  config.embedding_provider = :ollama
-  config.embedding_model = 'nomic-embed-text'
+  config.embedding.provider = :ollama
+  config.embedding.model = 'nomic-embed-text'
 end
 
 # Create HTM instance for this worker
@@ -573,7 +573,7 @@ Single-process demo showing:
 - Real-time sync via LISTEN/NOTIFY
 
 ```bash
-HTM_DBURL="postgresql://user@localhost:5432/htm_dev" ruby examples/robot_groups/same_process.rb
+HTM_DATABASE__URL="postgresql://user@localhost:5432/htm_dev" ruby examples/robot_groups/same_process.rb
 ```
 
 ### multi_process.rb
@@ -585,7 +585,7 @@ Multi-process demo showing:
 - Dynamic scaling by spawning new processes
 
 ```bash
-HTM_DBURL="postgresql://user@localhost:5432/htm_dev" ruby examples/robot_groups/multi_process.rb
+HTM_DATABASE__URL="postgresql://user@localhost:5432/htm_dev" ruby examples/robot_groups/multi_process.rb
 ```
 
 ### robot_worker.rb

data/docs/index.md

@@ -81,10 +81,10 @@ require 'htm'
 
 # Configure HTM globally (optional - uses Ollama by default)
 HTM.configure do |config|
-  config.embedding_provider = :ollama
-  config.embedding_model = 'nomic-embed-text:latest'
-  config.tag_provider = :ollama
-  config.tag_model = 'gemma3:latest'
+  config.embedding.provider = :ollama
+  config.embedding.model = 'nomic-embed-text:latest'
+  config.tag.provider = :ollama
+  config.tag.model = 'gemma3:latest'
 end
 
 # Initialize HTM for your robot