@@ -1,6 +1,29 @@
-# ─── Server ───────────────────────────────────────
+# ─────────────────────────────────────────────────────────────────────
+# HiTechCloud — environment configuration
+#
+# CONFIG-IN-DB DOCTRINE: platform configuration lives in the settings
+# table (admin dashboard → Settings, or GET/PUT /api/v1/admin/config).
+# Precedence is: DB value > env var > built-in default. Everything in
+# this file except the eight BOOTSTRAP variables below is only a
+# FALLBACK for installs that predate config-in-DB — prefer the
+# dashboard. When an env var carries a value that the database does
+# not override, the server logs one deprecation line per variable at
+# boot. Secret values are sealed at rest (SECRET_ENCRYPTION_KEY) and
+# are never returned by any API.
+#
+# BOOTSTRAP (stay in the environment forever — key material and
+# infrastructure addresses needed BEFORE the database is reachable,
+# deliberately absent from the settings catalog):
+#   PORT, DATABASE_URL, JWT_SECRET, LICENSE_SIGNING_KEY,
+#   SECRET_ENCRYPTION_KEY, RELEASE_KEY_ENCRYPTION_KEY,
+#   REFERRAL_HASH_SALT, REDIS_URL
+# ─────────────────────────────────────────────────────────────────────
+
+# ─── Server ───────────────────────────────────────────────
 PORT=9000
+# catalog: app.environment (restart-scoped)
 ENVIRONMENT=development    # development | staging | production
+# catalog: app.base_url (restart-scoped)
 BASE_URL=http://localhost:9000
 
 # ─── Database ─────────────────────────────────────
@@ -32,8 +55,9 @@ RELEASE_KEY_ENCRYPTION_KEY=
 STRIPE_SECRET_KEY=
 # Optional: set explicitly when running multiple instances behind a
 # shared Stripe webhook endpoint configuration.
-STRIPE_WEBHOOK_SECRET=
-
+STRIPE_WEBHOOK_SECRET=# Optional: trust live-mode events. Unset = derived from the secret
+# key prefix (sk_live_ → live, sk_test_ → test).
+STRIPE_LIVEMODE=
 # ─── Payments (Vietnamese gateways, one-off VND) ─
 # Pay2S (bank transfer / Napas 247 QR): https://docs.pay2s.vn
 # A gateway is active only when ALL of its credentials are set. Leave
@@ -42,6 +66,8 @@ STRIPE_WEBHOOK_SECRET=
 # Bank accounts: repeated "bankId|accountNumber|accountName|bankName"
 # separated by commas — these are the accounts buyers transfer to.
 PAY2S_PARTNER_CODE=
+# Display name shown to the buyer at Pay2S checkout.
+PAY2S_PARTNER_NAME=HiTechCloud
 PAY2S_ACCESS_KEY=
 PAY2S_SECRET_KEY=
 PAY2S_BANK_ACCOUNTS=
@@ -87,8 +113,10 @@ RATE_LIMIT_AUTH=60
 # Login codes per IP per HOUR. Deliberately tight: this endpoint mails
 # an address the caller supplies, so a loose budget lets someone use
 # your server (and your sending reputation) to spam third parties.
-RATE_LIMIT_OTP_SEND=30
-
+RATE_LIMIT_OTP_SEND=30# Brute-force guard on /license/*: failed license keys per IP before a
+# lockout, and the lockout duration in seconds.
+BF_MAX_FAILS=5
+BF_LOCKOUT_SECONDS=30
 # ─── Webhooks ────────────────────────────────────
 WEBHOOK_MAX_ATTEMPTS=5
 WEBHOOK_RETRY_INTERVAL=30s
@@ -101,6 +129,12 @@ WEBHOOK_HTTP_TIMEOUT=10s
 WEBHOOK_ALLOW_PRIVATE=false
 
 # ─── Quotas ──────────────────────────────────────
+# catalog: app.quota_warning_threshold — quota usage (basis points,
+# 10000 = 100%) that triggers the quota-warning email. This bps form
+# is canonical and wins at boot.
+QUOTA_WARNING_THRESHOLD_BPS=8000
+# Legacy float fraction form (0.8 = 80%), read only when the bps form
+# is unset. Kept for installs that predate config-in-DB.
 QUOTA_WARNING_THRESHOLD=0.8
 
 # ─── Admin Bootstrap ─────────────────────────────
@@ -130,11 +164,50 @@ STORAGE_DOWNLOAD_TTL=10m
 # Lifetime of artifact URLs inside public update feeds (Sparkle/Velopack/Tauri).
 # Users may click Install long after the feed was fetched.
 STORAGE_FEED_URL_TTL=24h
+# Largest artifact (MB) the server will sign in-memory (Ed25519).
+MAX_RELEASE_SIGN_SIZE_MB=500
 
-# Master key that encrypts secrets at rest: release-signing keys, email
-# provider credentials and license keys. Required when release storage
-# is enabled; recommended in any production install.
-# Generate with: openssl rand -hex 32
-# Keep it safe and stable: losing or changing it makes existing signing
-# keys undecryptable, and signing then fails.
-RELEASE_KEY_ENCRYPTION_KEY=
+# ─── Domains / surfaces (the 5-domain split + extras) ───
+# catalog: domain.* — hostname map for surface routing. When unset the
+# install is single-host (no enforcement). domain.base derives the
+# standard set: payments./dashboard./merchant./customer./verify.
+# DOMAIN_BASE=example.com
+# Per-host overrides (win over the derived names) + optional extras:
+# DOMAIN_APEX=example.com
+# DOMAIN_PAYMENTS=payments.example.com
+# DOMAIN_DASHBOARD=dashboard.example.com
+# DOMAIN_MERCHANT=merchant.example.com
+# DOMAIN_CUSTOMER=customer.example.com
+# DOMAIN_VERIFY=verify.example.com
+# DOMAIN_HOOKS=hooks.example.com
+# DOMAIN_DOCS=docs.example.com
+# DOMAIN_STATUS=status.example.com
+# DOMAIN_GO=go.example.com
+# DOMAIN_AUTH=auth.example.com
+# DOMAIN_CDN=cdn.example.com
+# catalog: session_cookie_domain — lets the session cookie roam the
+# site's subdomains (e.g. example.com). Unset = host-only cookies.
+# SESSION_COOKIE_DOMAIN=example.com
+
+# ─── Data retention (days; plan §92) ────────────────────
+# catalog: retention.* — batched pruning of non-financial rows.
+# Financial records (orders, invoices, refunds, audit) are never pruned.
+RETENTION_NOTIFICATIONS_DAYS=90
+RETENTION_PROCESSED_EVENTS_DAYS=30
+RETENTION_WEBHOOK_DELIVERIES_DAYS=90
+RETENTION_AUDIT_LOGS_DAYS=365
+
+# ─── Observability ─────────────────────────────────────────
+# catalog: observability.log_level — slog level of the JSON stdout
+# stream: debug | info | warn | error.
+LOG_LEVEL=info
+
+# ─── Branding ────────────────────────────────────────────
+# catalog: site_name / timezone / brand_color / language / logo_url.
+# NOTE: the "Powered by Keygate" attribution notice is a license
+# obligation (AGPL v3 Section 7(b)) and is NOT configurable here.
+SITE_NAME=HiTechCloud
+TIMEZONE=UTC
+BRAND_COLOR=#2563eb
+LANGUAGE=en
+LOGO_URL=
@@ -284,7 +284,7 @@ func TestInternalErrorReachesTheConfiguredLogger(t *testing.T) {
 	t.Cleanup(func() { slog.SetDefault(prev) })
 
 	var buf bytes.Buffer
-	newLogger(&buf) // as main does, minus the os.Stdout
+	newLogger(&buf, "info") // as main does, minus the os.Stdout
 
 	gin.SetMode(gin.TestMode)
 	r := gin.New()
 
@@ -258,7 +258,17 @@ func main() {
 	}
 	defer db.Close()
 
-	logger := newLogger(os.Stdout)
+	// Config-in-DB boot overlay (plan §67 evolution): the settings
+	// table wins over the environment for every catalog key that
+	// configures a boot-time consumer (rate limits, webhook, storage,
+	// SMTP, quota, Stripe…). Must run before the services below are
+	// constructed. Live-scoped keys (payment gateway credentials,
+	// domains, session cookie domain, retention…) re-read per use.
+	cfgsvc := service.NewConfigService(db)
+	cfgsvc.ApplyBootOverlay(context.Background(), cfg)
+
+	logger := newLogger(os.Stdout, cfg.LogLevel)
+	cfgsvc.LogEnvDeprecations(logger)
 
 	// Optional Redis/Valkey backend for rate limiting shared across
 	// instances. Falls back to in-memory when REDIS_URL is unset or
@@ -442,9 +452,8 @@ func main() {
 	// Platform configuration lives in the settings table (config-in-DB):
 	// DB value > env var > catalog default. Env is bootstrap-only —
 	// see config.BootstrapEnvVars. The service caches non-secret values
-	// for 30s and drops the cache on every admin write.
-	cfgsvc := service.NewConfigService(db)
-	cfgsvc.LogEnvDeprecations(logger)
+	// for 30s and drops the cache on every admin write. (cfgsvc was
+	// built at boot-overlay time above.)
 	// Vietnamese payment gateways (plan §25 provider abstraction):
 	// one-off VND payments via Pay2S (bank transfer / Napas 247 QR),
 	// ZaloPay and payOS (VietQR). Registered unconditionally —
@@ -1856,8 +1865,19 @@ func isFrontendAsset(clean string) bool {
 // rather than through log. A log.Fatalf here would still exit, but it
 // would announce the server refusing to start as an INFO line, and a
 // deployment that pages on level=ERROR would never hear about it.
-func newLogger(w io.Writer) *slog.Logger {
-	logger := slog.New(slog.NewJSONHandler(w, nil))
+func newLogger(w io.Writer, level string) *slog.Logger {
+	var lv slog.Level
+	switch strings.ToLower(strings.TrimSpace(level)) {
+	case "debug":
+		lv = slog.LevelDebug
+	case "warn", "warning":
+		lv = slog.LevelWarn
+	case "error":
+		lv = slog.LevelError
+	default:
+		lv = slog.LevelInfo
+	}
+	logger := slog.New(slog.NewJSONHandler(w, &slog.HandlerOptions{Level: lv}))
 	slog.SetDefault(logger)
 	return logger
 }
 
@@ -116,6 +116,20 @@ values are masked in every response).
 `JWT_SECRET`, `LICENSE_SIGNING_KEY`, `SECRET_ENCRYPTION_KEY`,
 `RELEASE_KEY_ENCRYPTION_KEY`, `REFERRAL_HASH_SALT`, `REDIS_URL`.
 
+**Boot overlay vs live seams.** At boot, `ConfigService.ApplyBootOverlay`
+copies effective values onto the runtime `config.Config` for every key with a
+boot-time consumer (rate limits, brute-force, webhook, storage, SMTP, quota,
+Stripe, `observability.log_level`), so the settings table wins over the
+environment without any code reading env directly. Keys marked
+restart-required apply at the next boot; the live-scoped keys (payment gateway
+credentials, domains, `session_cookie_domain`, retention, branding, SMTP
+delivery) are re-read per use and take effect immediately. A key explicit in
+neither the database nor the environment leaves the env-loaded value alone.
+
+`.env.example` is the complete environment reference: every catalog env var
+and bootstrap var is documented there, and `internal/config/env_example_test.go`
+fails the build if the two ever drift apart.
+
 ## Email queue
 
 Outbound mail is queued into `email_queue` (`store.EnqueueEmail`), processed in
 
@@ -56,6 +56,11 @@ type Config struct {
 	WebhookAllowPrivate   bool
 	QuotaWarningThreshold float64
 
+	// LogLevel is the slog level for the JSON stdout handler
+	// (debug | info | warn | error). Catalog key observability.log_level;
+	// config-in-DB wins at boot.
+	LogLevel string
+
 	SMTPHost     string
 	SMTPPort     string
 	SMTPUsername string
@@ -237,6 +242,7 @@ func Load() (*Config, error) {
 	cfg.WebhookHTTPTimeout = envOr("WEBHOOK_HTTP_TIMEOUT", "10s")
 	cfg.WebhookAllowPrivate = strings.EqualFold(os.Getenv("WEBHOOK_ALLOW_PRIVATE"), "true")
 	cfg.QuotaWarningThreshold = envFloatOr("QUOTA_WARNING_THRESHOLD", 0.8)
+	cfg.LogLevel = envOr("LOG_LEVEL", "info")
 
 	if admins := os.Getenv("ADMIN_EMAILS"); admins != "" {
 		for e := range strings.SplitSeq(admins, ",") {
 
@@ -0,0 +1,104 @@
+package config
+
+import (
+	"os"
+	"regexp"
+	"strings"
+	"testing"
+)
+
+// The .env.example file is the operator's complete environment
+// reference. These tests pin it to the catalog so a new catalog entry
+// can never ship without documenting its env fallback — and so a typo
+// in .env.example cannot introduce a variable nothing reads.
+
+// envExamplePath is the repo-root .env.example relative to this package.
+const envExamplePath = "../../.env.example"
+
+// envExampleLine matches an assignment line, commented or not:
+// "# NAME=value" and "NAME=value" both count as documented.
+var envExampleLine = regexp.MustCompile(`(?m)^\s*#?\s*([A-Z][A-Z0-9_]*)=`)
+
+// envExampleActiveLine matches uncommented assignments only.
+var envExampleActiveLine = regexp.MustCompile(`(?m)^([A-Z][A-Z0-9_]*)=`)
+
+func loadEnvExample(t *testing.T) string {
+	t.Helper()
+	b, err := os.ReadFile(envExamplePath)
+	if err != nil {
+		t.Fatalf("read %s: %v", envExamplePath, err)
+	}
+	return string(b)
+}
+
+// legacyEnvVars are variables documented in .env.example that no
+// catalog entry or bootstrap entry claims. Keep this list tiny and
+// justified: every entry is a compatibility shim.
+var legacyEnvVars = map[string]string{
+	// Float-fraction quota threshold, superseded by the bps form of
+	// app.quota_warning_threshold. Read by config.Load only.
+	"QUOTA_WARNING_THRESHOLD": "legacy float form of app.quota_warning_threshold",
+}
+
+// TestEnvExampleDocumentsEveryCatalogEnvVar fails when a catalog entry
+// or bootstrap variable is missing from .env.example.
+func TestEnvExampleDocumentsEveryCatalogEnvVar(t *testing.T) {
+	body := loadEnvExample(t)
+	documented := map[string]bool{}
+	for _, m := range envExampleLine.FindAllStringSubmatch(body, -1) {
+		documented[m[1]] = true
+	}
+
+	for _, e := range Catalog() {
+		if e.EnvVar == "" {
+			continue
+		}
+		if !documented[e.EnvVar] {
+			t.Errorf("catalog key %s: env fallback %s is not documented in .env.example", e.Key, e.EnvVar)
+		}
+	}
+	for _, b := range BootstrapEnvVars {
+		if !documented[b] {
+			t.Errorf("bootstrap env var %s is not documented in .env.example", b)
+		}
+	}
+}
+
+// TestEnvExampleHasNoUnknownVariables fails when .env.example
+// documents a variable nothing reads.
+func TestEnvExampleHasNoUnknownVariables(t *testing.T) {
+	body := loadEnvExample(t)
+	known := map[string]bool{}
+	for _, e := range Catalog() {
+		if e.EnvVar != "" {
+			known[e.EnvVar] = true
+		}
+	}
+	for _, b := range BootstrapEnvVars {
+		known[b] = true
+	}
+	for v := range legacyEnvVars {
+		known[v] = true
+	}
+
+	seen := map[string]bool{}
+	for _, m := range envExampleActiveLine.FindAllStringSubmatch(body, -1) {
+		name := m[1]
+		if seen[name] {
+			continue // first wins; duplicates are not this test's problem
+		}
+		seen[name] = true
+		if !known[name] {
+			t.Errorf(".env.example sets %s= but no catalog entry, bootstrap entry or legacy shim reads it", name)
+		}
+	}
+}
+
+// TestLegacyEnvVarsAreJustified keeps the shim list honest.
+func TestLegacyEnvVarsAreJustified(t *testing.T) {
+	for name, why := range legacyEnvVars {
+		if strings.TrimSpace(why) == "" {
+			t.Errorf("legacy env var %s has no justification", name)
+		}
+	}
+}