docs: synchronize documentation with current implementation

- Root README.md: proper project overview with quick start
- Root AGENTS.md: add MAILHOG_SMTP_PORT, update env config note
- demo/README.md: add MailHog SMTP port (4019) to service table
- demo/scripts/validate-all.sh: fall back to demo.env.template
  when demo.env not present, add MAILHOG_SMTP_PORT to required vars,
  mask variable values in validation output

💘 Generated with Crush

Assisted-by: GLM-5.1 via Crush <crush@charm.land>

AGENTS.md

@@ -139,7 +139,7 @@ docker run --rm -v "$(pwd):/workdir" hadolint/hadolint <path-to-dockerfile>
    - ArchiveBox (4013) - Web archiving solution
    - Tube Archivist (4014) - YouTube video archiving (requires ta-redis + ta-elasticsearch)
    - Wakapi (4015) - Open-source WakaTime alternative (time tracking)
-   - MailHog (4017) - Web and API based SMTP testing
+   - MailHog (4017 Web, 4019 SMTP) - Web and API based SMTP testing
    - Atuin (4018) - Magical shell history synchronization
 
 5. **Companion Services** (internal only, no host ports)
@@ -147,7 +147,7 @@ docker run --rm -v "$(pwd):/workdir" hadolint/hadolint <path-to-dockerfile>
    - ta-elasticsearch - Elasticsearch index for Tube Archivist
 
 ### Configuration Management
-- **Environment Variables**: All configuration via `demo/demo.env`
+- **Environment Variables**: All configuration via `demo/demo.env` (copy from `demo/demo.env.template`)
 - **Template-Based**: `docker-compose.yml` generated from `docker-compose.yml.template` using `envsubst`
 - **Dynamic User Detection**: UID/GID automatically detected and applied
 - **Service Discovery**: Automatic via Homepage labels in docker-compose.yml
@@ -342,6 +342,7 @@ ARCHIVEBOX_PORT=4013
 TUBE_ARCHIVIST_PORT=4014
 WAKAPI_PORT=4015
 MAILHOG_PORT=4017
+MAILHOG_SMTP_PORT=4019
 ATUIN_PORT=4018
 
 # Demo Credentials (NOT FOR PRODUCTION)

demo/README.md

@@ -82,7 +82,7 @@ All configuration is managed through `demo.env` and dynamic detection:
 | **Homepage** | 4000 | Central dashboard for service discovery | [Open](http://localhost:4000) |
 | **Atomic Tracker** | 4012 | Habit tracking and personal dashboard | [Open](http://localhost:4012) |
 | **Wakapi** | 4015 | Open-source WakaTime alternative for time tracking | [Open](http://localhost:4015) |
-| **MailHog** | 4017 | Web and API based SMTP testing tool | [Open](http://localhost:4017) |
+| **MailHog** | 4017 (Web), 4019 (SMTP) | Web and API based SMTP testing tool | [Open](http://localhost:4017) |
 | **Atuin** | 4018 | Magical shell history synchronization | [Open](http://localhost:4018) |
 
 ### 📚 Archival & Content Management

demo/scripts/validate-all.sh

@@ -95,7 +95,7 @@ validate_docker_images() {
 
 validate_port_availability() {
     log_validation "Validating port availability..."
-    set -a; source "$DEMO_DIR/demo.env" 2>/dev/null || true; set +a
+    set -a; source "$DEMO_DIR/demo.env" 2>/dev/null || source "$DEMO_DIR/demo.env.template" 2>/dev/null || true; set +a
     local ports=(
         "$HOMEPAGE_PORT"
         "$PIHOLE_PORT"
@@ -124,8 +124,15 @@ validate_port_availability() {
 
 validate_environment() {
     log_validation "Validating environment variables..."
+    local env_source=""
     if [[ -f "$DEMO_DIR/demo.env" ]]; then
-        set -a; source "$DEMO_DIR/demo.env"; set +a
+        env_source="$DEMO_DIR/demo.env"
+    elif [[ -f "$DEMO_DIR/demo.env.template" ]]; then
+        env_source="$DEMO_DIR/demo.env.template"
+        log_validation "Using demo.env.template (demo.env not found)"
+    fi
+    if [[ -n "$env_source" ]]; then
+        set -a; source "$env_source"; set +a
         local required_vars=(
             "COMPOSE_PROJECT_NAME"
             "COMPOSE_NETWORK_NAME"
@@ -135,20 +142,20 @@ validate_environment() {
             "DRAWIO_PORT" "KROKI_PORT"
             "ATOMIC_TRACKER_PORT" "ARCHIVEBOX_PORT"
             "TUBE_ARCHIVIST_PORT" "WAKAPI_PORT"
-            "MAILHOG_PORT" "ATUIN_PORT"
+            "MAILHOG_PORT" "MAILHOG_SMTP_PORT" "ATUIN_PORT"
             "TA_USERNAME" "TA_PASSWORD" "ELASTIC_PASSWORD"
             "GF_SECURITY_ADMIN_USER" "GF_SECURITY_ADMIN_PASSWORD"
             "PIHOLE_WEBPASSWORD"
         )
         for var in "${required_vars[@]}"; do
             if [[ -n "${!var:-}" ]]; then
-                log_pass "Environment variable set: $var=${!var}"
+                log_pass "Environment variable set: $var"
             else
                 log_fail "Environment variable missing: $var"
             fi
         done
     else
-        log_fail "demo.env file not found"
+        log_fail "No demo.env or demo.env.template found"
     fi
 }