docs: rewrite README with structured overview and quick start guide

Replaces the minimal project description with a comprehensive README
including a component overview table, quick start instructions, common
Ansible operations, and links to detailed documentation. Aligns with
Red Panda Approval™ standards.

ansible/arke/.env.j2

@@ -0,0 +1,147 @@
+# Arke Environment Configuration
+# Edit these values as needed before deployment
+
+# ============================================================================
+# Server Configuration
+# ============================================================================
+HOST=0.0.0.0
+PORT={{ arke_port }}
+DEBUG=false
+LOG_LEVEL=info
+RELOAD={{ arke_reload | default('false') }}
+
+# ============================================================================
+# PostgreSQL Database Configuration
+# ============================================================================
+DB_HOST={{ arke_db_host }}
+DB_PORT={{ arke_db_port }}
+DB_NAME={{ arke_db_name }}
+DB_USER={{ arke_db_user }}
+DB_PASSWORD={{ arke_db_password }}
+
+# ============================================================================
+# Memcached Configuration
+# ============================================================================
+MEMCACHED_HOST={{ arke_memcached_host | default('localhost') }}
+MEMCACHED_PORT={{ arke_memcached_port | default('11211') }}
+
+# ============================================================================
+# NTTh API Configuration
+# ============================================================================
+# --- NTTh Backend (Token Pool) ---
+# NTTh is treated specially as it manages a pool of tokens with session limits
+NTTH_BACKEND_ENABLED=true
+NTTH_SESSION_LIMIT=90
+NTTH_SESSION_TTL=3600
+NTTH_TOKEN_CACHE_TTL=82800
+
+# NTTh Tokens (numbered, add as many as needed)
+NTTH_TOKEN_1_NAME={{ntth_token_1_app_name}}
+NTTH_TOKEN_1_APP_ID={{ntth_token_1_app_id}}
+NTTH_TOKEN_1_APP_SECRET={{ntth_token_1_app_secret}}
+
+NTTH_TOKEN_2_NAME={{ntth_token_2_app_name}}
+NTTH_TOKEN_2_APP_ID={{ntth_token_2_app_id}}
+NTTH_TOKEN_2_APP_SECRET={{ntth_token_2_app_secret}}
+
+NTTH_TOKEN_3_NAME={{ntth_token_3_app_name}}
+NTTH_TOKEN_3_APP_ID={{ntth_token_3_app_id}}
+NTTH_TOKEN_3_APP_SECRET={{ntth_token_3_app_secret}}
+
+NTTH_TOKEN_4_NAME={{ntth_token_4_app_name}}
+NTTH_TOKEN_4_APP_ID={{ntth_token_4_app_id}}
+NTTH_TOKEN_4_APP_SECRET={{ntth_token_4_app_secret}}
+
+# Session Management
+SESSION_LIMIT={{ arke_session_limit | default('90') }}
+SESSION_TTL={{ arke_session_ttl | default('3600') }}
+TOKEN_CACHE_TTL={{ arke_token_cache_ttl | default('82800') }}
+
+# ============================================================================
+# Embedding Provider Configuration
+# ============================================================================
+# Choose your embedding provider: 'ollama' or 'openai'
+EMBEDDING_PROVIDER={{arke_embedding_provider}}
+
+# --- OpenAI-Compatible Configuration (when EMBEDDING_PROVIDER=openai) ---
+# Works with OpenAI API, llama-cpp, LocalAI, and other compatible services
+OPENAI_EMBEDDING_BASE_URL={{arke_openai_embedding_base_url}}
+OPENAI_EMBEDDING_API_KEY={{arke_openai_embedding_api_key}}
+OPENAI_EMBEDDING_MODEL={{arke_openai_embedding_model}}
+
+# --- Embedding Configuration ---
+EMBEDDING_TIMEOUT={{ arke_embedding_timeout | default('30.0') }}
+EMBEDDING_BATCH_SIZE={{arke_embedding_batch_size}}
+EMBEDDING_UBATCH_SIZE={{arke_embedding_ubatch_size}}
+EMBEDDING_MAX_CONTEXT={{arke_embedding_max_context}}
+
+# ============================================================================
+# Memory System Configuration
+# ============================================================================
+MEMORY_ENABLED={{ arke_memory_enabled | default('true') }}
+MAX_CONTEXT_TOKENS={{ arke_max_context_tokens | default('8000') }}
+SIMILARITY_THRESHOLD={{ arke_similarity_threshold | default('0.7') }}
+MIN_IMPORTANCE_SCORE={{ arke_min_importance_score | default('0.7') }}
+
+# ============================================================================
+# Message Size Limits
+# ============================================================================
+# Maximum tokens allowed for incoming messages (default: 32768)
+# This limit prevents excessively large requests that could overwhelm the system
+MESSAGE_MAX_TOKENS=700000
+
+# ============================================================================
+# Background Task Configuration (Async Embedding Generation)
+# ============================================================================
+# Enable background task processing for async operations
+BACKGROUND_TASKS_ENABLED=true
+
+# Number of worker threads for background tasks
+BACKGROUND_TASK_WORKERS=5
+
+# Maximum retry attempts for failed tasks
+BACKGROUND_TASK_MAX_RETRIES=3
+
+# Initial retry delay in seconds (uses exponential backoff)
+BACKGROUND_TASK_RETRY_DELAY=1.0
+
+# Cleanup interval for old completed/failed tasks (hours)
+BACKGROUND_TASK_CLEANUP_HOURS=24
+
+# --- Async Embedding Configuration ---
+# Enable async embedding generation (non-blocking)
+ASYNC_EMBEDDINGS_ENABLED=true
+
+# Number of messages to batch together for embedding generation
+ASYNC_EMBEDDING_BATCH_SIZE=50
+
+# Priority level for embedding tasks: LOW, NORMAL, HIGH, CRITICAL
+ASYNC_EMBEDDING_PRIORITY=NORMAL
+
+# --- Async Deduplication Configuration ---
+# Enable async document enhancement (non-blocking embedding generation for deduplicated documents)
+ASYNC_DEDUPLICATION_ENABLED=true
+
+# Number of documents to batch together for enhancement
+DEDUPLICATION_BATCH_SIZE=20
+
+# Priority level for document enhancement tasks: LOW, NORMAL, HIGH, CRITICAL
+DEDUPLICATION_ENHANCEMENT_PRIORITY=NORMAL
+
+# Enable HTML content extraction and processing
+HTML_CONTENT_EXTRACTION=true
+
+# Minimum token count for document deduplication
+MIN_TOKENS_FOR_DEDUP=500
+
+# Semantic similarity threshold for duplicate detection (0.0-1.0)
+DEDUPLICATION_THRESHOLD=0.95
+
+# Reference expansion strategy: smart, full, summary, minimal
+REFERENCE_EXPANSION_STRATEGY=smart
+
+# ============================================================================
+# Monitoring Configuration
+# ============================================================================
+PROMETHEUS_ENABLED=true
+METRICS_PORT={{arke_metrics_port}}