htm 0.0.15 → 0.0.18

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

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# HTM MCP Server with CLI management commands
+#
+# Usage:
+#   htm_mcp              # Start MCP server (default)
+#   htm_mcp server       # Start MCP server (explicit)
+#   htm_mcp setup        # Initialize database
+#   htm_mcp init         # Initialize database (alias for setup)
+#   htm_mcp verify       # Verify database connection
+#   htm_mcp stats        # Show memory statistics
+#   htm_mcp version      # Show HTM version
+#   htm_mcp help         # Show help and environment variables
+
+require_relative '../lib/htm'
+require_relative '../lib/htm/mcp/cli'
+
+# Handle CLI commands (exits if command handled)
+# Returns false if server should start
+unless HTM::MCP::CLI.run(ARGV) == false
+  exit 0
+end
+
+# Start MCP server
+require_relative '../lib/htm/mcp/server'
+HTM::MCP::Server.start

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|

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"