htm 0.0.17 → 0.0.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 964868a160989db5a7f8baa524e89d82552166f5d065f30685a17597ddec627b
-  data.tar.gz: 963b4d21d30ee51d08c34af26a1d2d1284b17d03ac39734ad81be0d0b3cd1a45
+  metadata.gz: 7379c23800bf3f00cc328be9725b14bcea06a9d2158eaf3b3bca80b11a6efb74
+  data.tar.gz: ec96095a72ab89fed1dd7df0ceaeb3888938f5ddbdea6fd3f3c06aa15b80bf67
 SHA512:
-  metadata.gz: 2c061077debb17b3bcee1c70e1136cdf8d1248ca100815adb75eb522aa39c40ac1a8863c07684d89da36a7c8df37f6b22b3c98669939cfaf177ea37d51716435
-  data.tar.gz: 49b6ec15849051d17c85261d7529374d7d5f95be381b96415c10e0e883b08c3f52c5b3303c04ae850376dd23682dd4f387218eed1c6a5b1fab28c2f8eac2c183
+  metadata.gz: 428b9c8f1db0f3a7a4be6e0b8bc4cc27f0bf058e7847c409cfca423c1bf9722a8efad92dbdd276d69844ab771670ea7cdc62e292018bec4705ed3f9f66255c16
+  data.tar.gz: af62a40339de40eac22f90b919a626b0f2d61a14440cdd5ca9e0aaf87ca088cc086cd35bc1eb4394d87a0646512c0a30d2fb47fdee7ec9ea2c4f11e469f2a44b

data/.architecture/decisions/adrs/001-use-postgresql-timescaledb-storage.md

@@ -115,7 +115,7 @@ We will use **PostgreSQL with TimescaleDB** as the primary storage backend for H
 ### Connection Configuration
 ```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/.architecture/decisions/adrs/011-database-side-embedding-generation-with-pgai.md

@@ -284,7 +284,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')"
@@ -294,16 +294,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/.architecture/decisions/adrs/012-llm-driven-ontology-topic-extraction.md

@@ -333,7 +333,7 @@ htm.add_node('memory_001', 'PostgreSQL with TimescaleDB handles time-series data
 HTM::Database.migrate
 
 # 2. (Optional) Re-extract topics for existing nodes
-psql $HTM_DBURL -c "UPDATE nodes SET value = value;"
+psql $HTM_DATABASE__URL -c "UPDATE nodes SET value = value;"
 # Triggers topic extraction for all existing nodes
 ```
 

data/.envrc

@@ -2,35 +2,22 @@
 
 export RR=`pwd`
 
-export RAILS_ENV=development
+export HTM_ENV=development
 export HTM_EXTRACT_PROPOSITIONS=true
 
 # Database connection - Localhost PostgreSQL
-export HTM_DBHOST=localhost
-export HTM_DBPORT=5432
-export HTM_DBNAME=htm_development
-export HTM_DBUSER=${USER}
-export HTM_DBPASS=
-export HTM_DBURL="postgresql://${HTM_DBUSER}@${HTM_DBHOST}:${HTM_DBPORT}/${HTM_DBNAME}?sslmode=disable"
-# export HTM_DBURL="postgresql://dewayne@localhost:5432/htm_development"
-
-# Uncomment if using TimescaleDB Cloud instead:
-# export HTM_SERVICE_NAME=$TIGER_SERVICE_NAME
-# export HTM_DBURL=$TIGER_DBURL
-# export HTM_DBNAME=$TIGER_DBNAME
-# export HTM_DBUSER=$TIGER_DBUSER
-# export HTM_DBPASS=$TIGER_DBPASS
-# export HTM_DBHOST=$TIGER_DBHOST
-# export HTM_DBPORT=$TIGER_DBPORT
+export HTM_DATABASE__HOST=localhost
+export HTM_DATABASE__PORT=5432
+export HTM_DATABASE__NAME=htm_development
+export HTM_DATABASE__USER=${USER}
+export HTM_DATABASE__PASSWORD=
+export HTM_DATABASE__URL="postgresql://${HTM_DATABASE__USER}@${HTM_DATABASE__HOST}:${HTM_DATABASE__PORT}/${HTM_DATABASE__NAME}?sslmode=disable"
 
 # Client-side embedding generation
-# HTM generates embeddings before inserting into database
-export HTM_EMBEDDINGS_PROVIDER=ollama
-export HTM_EMBEDDINGS_MODEL=embeddinggemma
-export HTM_EMBEDDINGS_BASE_URL=http://localhost:11434
-export HTM_EMBEDDINGS_DIMENSION=768
+export HTM_EMBEDDING__PROVIDER=ollama
+export HTM_EMBEDDING__MODEL=embeddinggemma
+export HTM_EMBEDDING__DIMENSIONS=768
 
 # Topic extraction (client-side)
-export HTM_TOPIC_PROVIDER=ollama
-export HTM_TOPIC_MODEL=phi4
-export HTM_TOPIC_BASE_URL=http://localhost:11434
+export HTM_TAG__PROVIDER=ollama
+export HTM_TAG__MODEL=phi4

data/.irbrc

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # HTM Interactive Development Console
-# Usage: HTM_DBURL="postgresql://user@localhost:5432/htm_development" irb
+# Usage: HTM_DATABASE__URL="postgresql://user@localhost:5432/htm_development" irb
 
 require_relative 'lib/htm'
 require 'debug_me'
@@ -21,12 +21,12 @@ end
 
 # Configure HTM with sensible defaults for interactive use
 HTM.configure do |config|
-  config.job_backend = :inline
-  config.embedding_provider = :ollama
-  config.embedding_model = 'nomic-embed-text:latest'
-  config.embedding_dimensions = 768
-  config.tag_provider = :ollama
-  config.tag_model = 'gemma3:latest'
+  config.job.backend = :inline
+  config.embedding.provider = :ollama
+  config.embedding.model = 'nomic-embed-text:latest'
+  config.embedding.dimensions = 768
+  config.tag.provider = :ollama
+  config.tag.model = 'gemma3:latest'
   config.reset_to_defaults
 end
 puts "✓ HTM configured (inline jobs, Ollama provider)"

data/.tbls.yml

@@ -1,9 +1,9 @@
 # tbls configuration for HTM database documentation
 # https://github.com/k1LoW/tbls
 
-# Database connection - uses HTM_DBURL environment variable
+# Database connection - uses HTM_DATABASE__URL environment variable
 # tbls expands environment variables with $VAR or ${VAR} syntax
-dsn: $HTM_DBURL
+dsn: $HTM_DATABASE__URL
 
 # Output documentation to docs/database directory
 docPath: docs/database

data/CHANGELOG.md

@@ -6,6 +6,77 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+## [0.0.18] - 2025-12-20
+### Added
+- **Anyway::Config-based configuration system** - Replaced custom Configuration class with robust multi-source config management
+  - **Multi-layer configuration loading** with priority (lowest to highest):
+    1. Bundled defaults (`lib/htm/config/defaults.yml`)
+    2. XDG user config (`~/.config/htm/htm.yml`)
+    3. Project config (`./config/htm.yml`)
+    4. Local overrides (`./config/htm.local.yml`) - gitignored for secrets
+    5. Environment variables (`HTM_*`)
+    6. Programmatic (`HTM.configure` block)
+  - **Nested configuration access**: `HTM.config.database.host`, `HTM.config.embedding.model`, etc.
+  - **Environment-specific overrides**: Different defaults for development, test, and production environments
+  - **Configuration source tracing**: Debug where each configuration value originated
+- **YAML-based prompt templates** - Tag and proposition extraction prompts now configurable via YAML
+  - Prompts use `%{placeholder}` syntax for runtime interpolation
+  - System and user prompts for tag extraction: `tag.system_prompt`, `tag.user_prompt_template`
+  - System and user prompts for proposition extraction: `proposition.system_prompt`, `proposition.user_prompt_template`
+  - Taxonomy context templates: `tag.taxonomy_context_existing`, `tag.taxonomy_context_empty`
+- **New loaders for configuration sources**:
+  - `HTM::Loaders::DefaultsLoader` - Loads bundled gem defaults from YAML
+  - `HTM::Loaders::XDGConfigLoader` - Loads XDG-compliant user configuration
+- **Configuration management example** - New `examples/config_file_example/` directory
+  - `show_config.rb` - Demonstrates configuration source tracing
+  - Sample configuration files showing override mechanisms
+  - Comprehensive README with configuration patterns
+
+### Changed
+- **BREAKING: Database environment variables renamed** - Migrate from `HTM_DBURL`/`HTM_DB*` to namespaced format
+  - `HTM_DBURL` → `HTM_DATABASE__URL`
+  - `HTM_DATABASE` → `HTM_DATABASE__NAME`
+  - `HTM_DB_USER` → `HTM_DATABASE__USER`
+  - `HTM_DB_PASSWORD` → `HTM_DATABASE__PASSWORD`
+  - `HTM_DB_HOST` → `HTM_DATABASE__HOST`
+  - `HTM_DB_PORT` → `HTM_DATABASE__PORT`
+  - Uses double underscore (`__`) for nested config (Anyway::Config convention)
+- **Configuration access patterns updated** - Direct attributes → nested configuration
+  - `config.embedding_provider` → `config.embedding.provider`
+  - `config.embedding_model` → `config.embedding.model`
+  - `config.tag_provider` → `config.tag.provider`
+  - `config.tag_model` → `config.tag.model`
+  - `config.chunk_size` → `config.chunking.size`
+  - `config.chunk_overlap` → `config.chunking.overlap`
+- **Removed `config/database.yml`** - Replaced by flexible YAML configuration files
+- **Prompt generation refactored** - Hardcoded prompt strings moved to `defaults.yml` templates
+- **MCP CLI enhanced** - Improved command handling and configuration output display
+
+### Removed
+- **`HTM::Configuration` class** - Replaced by `HTM::Config` using Anyway::Config
+- **Legacy database environment variable support** - Must use new `HTM_DATABASE__*` format
+
+### Dependencies
+- Added `anyway_config` gem for configuration management
+
+### Migration Guide
+Update your environment variables:
+```bash
+# Old format
+export HTM_DBURL="postgresql://user@localhost:5432/htm_development"
+
+# New format
+export HTM_DATABASE__URL="postgresql://user@localhost:5432/htm_development"
+```
+
+Update configuration access:
+```ruby
+# Old pattern
+HTM.configuration.embedding_model
+
+# New pattern
+HTM.config.embedding.model
+```
 
 ## [0.0.17] - 2025-12-18
 

data/README.md

@@ -39,7 +39,7 @@ HTM includes a Model Context Protocol server with 23 tools for memory management
   "mcpServers": {
     "htm": {
       "command": "htm_mcp",
-      "env": { "HTM_DBURL": "postgresql://localhost/htm" }
+      "env": { "HTM_DATABASE__URL": "postgresql://localhost/htm" }
     }
   }
 }

data/Rakefile

@@ -10,16 +10,21 @@ Rake::TestTask.new(:test) do |t|
   t.verbose = true
 end
 
-# Ensure test task runs with RAILS_ENV=test
+# Ensure test task runs with HTM_ENV=test (takes priority over RAILS_ENV/RACK_ENV)
 task :test do
-  ENV['RAILS_ENV'] = 'test'
+  ENV['HTM_ENV'] = 'test'
 end
 
 # Prepend environment setup before test runs
 Rake::Task[:test].enhance [:set_test_env]
 
 task :set_test_env do
-  ENV['RAILS_ENV'] = 'test'
+  ENV['HTM_ENV'] = 'test'
+  # Set database URL if not already configured
+  # Uses current system user for local PostgreSQL connection
+  unless ENV['HTM_DATABASE__URL']
+    ENV['HTM_DATABASE__URL'] = "postgresql://#{ENV['USER']}@localhost:5432/htm_test"
+  end
 end
 
 task default: :test

data/SETUP.md

@@ -60,10 +60,10 @@ psql htm_development -c "SELECT extname, extversion FROM pg_extension;"
 
 ```bash
 # Add to your ~/.bashrc or ~/.zshrc
-export HTM_DBURL="postgresql://postgres@localhost:5432/htm_development"
+export HTM_DATABASE__URL="postgresql://postgres@localhost:5432/htm_development"
 
 # Or for a specific user with password
-export HTM_DBURL="postgresql://username:password@localhost:5432/htm_development"
+export HTM_DATABASE__URL="postgresql://username:password@localhost:5432/htm_development"
 ```
 
 ### 5. Verify Connection
@@ -136,12 +136,12 @@ export OLLAMA_URL="http://custom-host:11434"
 
 | Variable | Description | Example Value |
 |----------|-------------|---------------|
-| `HTM_DBURL` | Full PostgreSQL connection URL (preferred) | `postgresql://postgres@localhost:5432/htm_development` |
-| `HTM_DBNAME` | Database name (fallback) | `htm_development` |
-| `HTM_DBUSER` | Database user (fallback) | `postgres` |
-| `HTM_DBPASS` | Database password (fallback) | `` |
-| `HTM_DBHOST` | Database host (fallback) | `localhost` |
-| `HTM_DBPORT` | Database port (fallback) | `5432` |
+| `HTM_DATABASE__URL` | Full PostgreSQL connection URL (preferred) | `postgresql://postgres@localhost:5432/htm_development` |
+| `HTM_DATABASE__NAME` | Database name (fallback) | `htm_development` |
+| `HTM_DATABASE__USER` | Database user (fallback) | `postgres` |
+| `HTM_DATABASE__PASSWORD` | Database password (fallback) | `` |
+| `HTM_DATABASE__HOST` | Database host (fallback) | `localhost` |
+| `HTM_DATABASE__PORT` | Database port (fallback) | `5432` |
 | `OLLAMA_URL` | Ollama server URL | `http://localhost:11434` |
 
 ## Development Workflow
@@ -150,7 +150,7 @@ export OLLAMA_URL="http://custom-host:11434"
 
 ```bash
 # 1. Set database URL (if not in shell config)
-export HTM_DBURL="postgresql://postgres@localhost:5432/htm_development"
+export HTM_DATABASE__URL="postgresql://postgres@localhost:5432/htm_development"
 
 # 2. Install dependencies
 bundle install
@@ -196,7 +196,7 @@ HTM/
 │   │   ├── configuration.rb      # Multi-provider LLM config
 │   │   └── version.rb            # Version constant
 ├── config/
-│   └── database.yml              # Database configuration
+│   └── defaults.yml              # Default configuration values
 ├── db/
 │   └── schema.sql                # Database schema
 ├── test/
@@ -248,10 +248,10 @@ If you get connection errors:
 
 ```bash
 # Verify environment variable is set
-echo $HTM_DBURL
+echo $HTM_DATABASE__URL
 
 # Test connection manually
-psql $HTM_DBURL -c "SELECT 1"
+psql $HTM_DATABASE__URL -c "SELECT 1"
 
 # Check PostgreSQL is running
 brew services list | grep postgresql  # macOS

data/bin/htm_mcp

@@ -13,10 +13,6 @@
 #   htm_mcp version      # Show HTM version
 #   htm_mcp help         # Show help and environment variables
 
-# Setup bundler to load gems from Gemfile
-# This allows running the script directly without `bundle exec`
-require 'bundler/setup'
-
 require_relative '../lib/htm'
 require_relative '../lib/htm/mcp/cli'
 

data/db/seed_data/README.md

@@ -23,8 +23,8 @@ The seeding process uses environment variables for configuration. All settings h
 
 ### Database Settings
 
-- `HTM_DBURL` - Full PostgreSQL connection URL (required)
-- Or individual settings: `HTM_DBHOST`, `HTM_DBPORT`, `HTM_DBNAME`, `HTM_DBUSER`, `HTM_DBPASS`
+- `HTM_DATABASE__URL` - Full PostgreSQL connection URL (required)
+- Or individual settings: `HTM_DATABASE__HOST`, `HTM_DATABASE__PORT`, `HTM_DATABASE__NAME`, `HTM_DATABASE__USER`, `HTM_DATABASE__PASSWORD`
 
 ### Other Settings
 

data/db/seeds.rb

@@ -15,7 +15,7 @@
 #   HTM_EMBEDDING_TIMEOUT - Embedding generation timeout in seconds (default: 120)
 #   HTM_TAG_TIMEOUT - Tag generation timeout in seconds (default: 180)
 #   HTM_CONNECTION_TIMEOUT - LLM connection timeout in seconds (default: 30)
-#   HTM_DBURL - Database connection URL
+#   HTM_DATABASE__URL - Database connection URL
 #
 # Usage:
 #   rake htm:db:seed
@@ -64,7 +64,7 @@ end
 puts "✓ HTM configured"
 puts
 
-# Create HTM instance (uses default database config from ENV['HTM_DBURL'])
+# Create HTM instance (uses default database config from ENV['HTM_DATABASE__URL'])
 htm = HTM.new(robot_name: ENV['HTM_ROBOT_NAME'] || "Seed Robot")
 
 # Add sample conversation messages

data/docs/api/database.md

@@ -38,7 +38,7 @@ HTM::Database.setup(db_url = nil)
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `db_url` | String, nil | `ENV['HTM_DBURL']` | Database connection URL |
+| `db_url` | String, nil | `ENV['HTM_DATABASE__URL']` | Database connection URL |
 
 #### Returns
 
@@ -170,25 +170,25 @@ HTM::Database.parse_connection_params()
 #### Returns
 
 - `Hash` - Connection configuration
-- `nil` - If `ENV['HTM_DBNAME']` not set
+- `nil` - If `ENV['HTM_DATABASE__NAME']` not set
 
 #### Environment Variables
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `HTM_DBHOST` | Database hostname | `'cw7rxj91bm.srbbwwxn56.tsdb.cloud.timescale.com'` |
-| `HTM_DBPORT` | Database port | `37807` |
-| `HTM_DBNAME` | Database name | *required* |
-| `HTM_DBUSER` | Database user | *required* |
-| `HTM_DBPASS` | Database password | *required* |
+| `HTM_DATABASE__HOST` | Database hostname | `'cw7rxj91bm.srbbwwxn56.tsdb.cloud.timescale.com'` |
+| `HTM_DATABASE__PORT` | Database port | `37807` |
+| `HTM_DATABASE__NAME` | Database name | *required* |
+| `HTM_DATABASE__USER` | Database user | *required* |
+| `HTM_DATABASE__PASSWORD` | Database password | *required* |
 
 #### Examples
 
 ```ruby
 # Set environment variables
-ENV['HTM_DBNAME'] = 'tsdb'
-ENV['HTM_DBUSER'] = 'tsdbadmin'
-ENV['HTM_DBPASS'] = 'secret'
+ENV['HTM_DATABASE__NAME'] = 'tsdb'
+ENV['HTM_DATABASE__USER'] = 'tsdbadmin'
+ENV['HTM_DATABASE__PASSWORD'] = 'secret'
 
 config = HTM::Database.parse_connection_params()
 # => {
@@ -201,14 +201,14 @@ config = HTM::Database.parse_connection_params()
 # }
 
 # Custom host and port
-ENV['HTM_DBHOST'] = 'localhost'
-ENV['HTM_DBPORT'] = '5432'
+ENV['HTM_DATABASE__HOST'] = 'localhost'
+ENV['HTM_DATABASE__PORT'] = '5432'
 
 config = HTM::Database.parse_connection_params()
 # => { host: "localhost", port: 5432, ... }
 
-# Without HTM_DBNAME
-ENV.delete('HTM_DBNAME')
+# Without HTM_DATABASE__NAME
+ENV.delete('HTM_DATABASE__NAME')
 config = HTM::Database.parse_connection_params()
 # => nil
 ```
@@ -230,29 +230,29 @@ HTM::Database.default_config()
 
 #### Priority Order
 
-1. `ENV['HTM_DBURL']` - Parse connection URL
-2. `ENV['HTM_DBNAME']` - Parse individual params
+1. `ENV['HTM_DATABASE__URL']` - Parse connection URL
+2. `ENV['HTM_DATABASE__NAME']` - Parse individual params
 3. `nil` - No configuration available
 
 #### Examples
 
 ```ruby
-# Using HTM_DBURL
-ENV['HTM_DBURL'] = 'postgresql://user:pass@host/db'
+# Using HTM_DATABASE__URL
+ENV['HTM_DATABASE__URL'] = 'postgresql://user:pass@host/db'
 config = HTM::Database.default_config
 # => Parsed from URL
 
-# Using HTM_DBNAME
-ENV.delete('HTM_DBURL')
-ENV['HTM_DBNAME'] = 'mydb'
-ENV['HTM_DBUSER'] = 'user'
-ENV['HTM_DBPASS'] = 'pass'
+# Using HTM_DATABASE__NAME
+ENV.delete('HTM_DATABASE__URL')
+ENV['HTM_DATABASE__NAME'] = 'mydb'
+ENV['HTM_DATABASE__USER'] = 'user'
+ENV['HTM_DATABASE__PASSWORD'] = 'pass'
 config = HTM::Database.default_config
 # => Parsed from params
 
 # No configuration
-ENV.delete('HTM_DBURL')
-ENV.delete('HTM_DBNAME')
+ENV.delete('HTM_DATABASE__URL')
+ENV.delete('HTM_DATABASE__NAME')
 config = HTM::Database.default_config
 # => nil
 
@@ -341,33 +341,33 @@ Using URL (recommended):
 
 ```bash
 # In ~/.bashrc__tiger
-export HTM_DBURL='postgresql://tsdbadmin:PASSWORD@SERVICE.tsdb.cloud.timescale.com:37807/tsdb?sslmode=require'
+export HTM_DATABASE__URL='postgresql://tsdbadmin:PASSWORD@SERVICE.tsdb.cloud.timescale.com:37807/tsdb?sslmode=require'
 ```
 
 Using individual variables:
 
 ```bash
 # In ~/.bashrc__tiger
-export HTM_DBHOST='xxx.tsdb.cloud.timescale.com'
-export HTM_DBPORT=37807
-export HTM_DBNAME='tsdb'
-export HTM_DBUSER='tsdbadmin'
-export HTM_DBPASS='your_password'
+export HTM_DATABASE__HOST='xxx.tsdb.cloud.timescale.com'
+export HTM_DATABASE__PORT=37807
+export HTM_DATABASE__NAME='tsdb'
+export HTM_DATABASE__USER='tsdbadmin'
+export HTM_DATABASE__PASSWORD='your_password'
 ```
 
 ### Local PostgreSQL
 
 ```bash
-export HTM_DBURL='postgresql://localhost/htm_dev'
+export HTM_DATABASE__URL='postgresql://localhost/htm_dev'
 
 # Or with auth
-export HTM_DBURL='postgresql://user:pass@localhost:5432/htm_dev'
+export HTM_DATABASE__URL='postgresql://user:pass@localhost:5432/htm_dev'
 ```
 
 ### Docker PostgreSQL
 
 ```bash
-export HTM_DBURL='postgresql://postgres:postgres@localhost:5432/htm'
+export HTM_DATABASE__URL='postgresql://postgres:postgres@localhost:5432/htm'
 ```
 
 ---
@@ -402,7 +402,7 @@ if config
   puts "Port: #{config[:port]}"
 else
   puts "No database configuration found"
-  puts "Please set HTM_DBURL or HTM_DBNAME environment variables"
+  puts "Please set HTM_DATABASE__URL or HTM_DATABASE__NAME environment variables"
 end
 
 # Test connection
@@ -493,7 +493,7 @@ pg_isready -h localhost -p 5432
 psql -h localhost -U user -d dbname
 
 # Verify environment
-echo $HTM_DBURL
+echo $HTM_DATABASE__URL
 ```
 
 ### Permission Denied
@@ -576,7 +576,7 @@ end
 config = HTM::Database.default_config
 
 unless config
-  raise "Database not configured. Please set HTM_DBURL environment variable. " \
+  raise "Database not configured. Please set HTM_DATABASE__URL environment variable. " \
         "See README.md for configuration instructions."
 end
 ```

data/docs/api/htm.md

@@ -49,7 +49,7 @@ HTM.new(
 |-----------|------|---------|-------------|
 | `working_memory_size` | Integer | `128_000` | Maximum tokens for working memory |
 | `robot_name` | String, nil | `"robot_#{uuid[0..7]}"` | Human-readable name |
-| `db_config` | Hash, nil | From `ENV['HTM_DBURL']` | Database configuration |
+| `db_config` | Hash, nil | From `ENV['HTM_DATABASE__URL']` | Database configuration |
 | `db_pool_size` | Integer | `5` | Database connection pool size |
 | `db_query_timeout` | Integer | `30_000` | Query timeout in milliseconds |
 | `db_cache_size` | Integer | `1000` | Query cache size (0 to disable) |

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

@@ -15,9 +15,9 @@ Get connection pool statistics
 ## disconnect!() {: #method-c-disconnect! }
 Close all database connections
 ## establish_connection!() {: #method-c-establish_connection! }
-Establish database connection from config/database.yml
+Establish database connection from HTM::Config
 ## load_database_config() {: #method-c-load_database_config }
-Load and parse database configuration from YAML with ERB
+Load database configuration from HTM::Config
 ## verify_extensions!() {: #method-c-verify_extensions! }
 Verify required extensions are available
 

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

@@ -16,37 +16,48 @@ HTM uses RubyLLM for multi-provider LLM support. Supported providers:
 *   :deepseek (DeepSeek)
 
 
-**`@example`**
+**`@example`** Using nested configuration sections
 ```ruby
 HTM.configure do |config|
-  config.embedding_provider = :openai
-  config.embedding_model = 'text-embedding-3-small'
-  config.tag_provider = :openai
-  config.tag_model = 'gpt-4o-mini'
+  config.embedding.provider = :openai
+  config.embedding.model = 'text-embedding-3-small'
+  config.tag.provider = :openai
+  config.tag.model = 'gpt-4o-mini'
   config.openai_api_key = ENV['OPENAI_API_KEY']
 end
 ```
-**`@example`**
+**`@example`** Using Ollama (local default)
 ```ruby
 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'
   config.ollama_url = 'http://localhost:11434'
 end
 ```
-**`@example`**
+**`@example`** Mixed providers
 ```ruby
 HTM.configure do |config|
-  config.embedding_provider = :openai
-  config.embedding_model = 'text-embedding-3-small'
+  config.embedding.provider = :openai
+  config.embedding.model = 'text-embedding-3-small'
   config.openai_api_key = ENV['OPENAI_API_KEY']
-  config.tag_provider = :anthropic
-  config.tag_model = 'claude-3-haiku-20240307'
+  config.tag.provider = :anthropic
+  config.tag.model = 'claude-3-haiku-20240307'
   config.anthropic_api_key = ENV['ANTHROPIC_API_KEY']
 end
 ```
+**`@example`** Job and chunking configuration
+```ruby
+HTM.configure do |config|
+  config.job.backend = :inline  # or :sidekiq, :active_job, :thread
+  config.chunking.size = 1024
+  config.chunking.overlap = 64
+  config.proposition.enabled = true
+  config.proposition.provider = :ollama
+  config.proposition.model = 'gemma3:latest'
+end
+```
 **`@example`**
 ```ruby
 HTM.configure do |config|