feat(B6): served-usage ledger + reconciliation (#58)

Operators are now metered for the tokens they serve on behalf of mesh
accounts, and the upstream rolls that up for compensation.

cortex-gateway:
- served_usage.rs: an in-process per-(account,key,UTC-day) served-token
  counter, incremented in metering::usage_sink alongside spend/settle for
  every authenticated request. A flush task (spawned in run() when
  [upstream].enabled, mirroring poller/evictor) POSTs ABSOLUTE cumulative
  counters to upstream on [upstream].served_usage_report_interval_secs.
- The no-limit infra key is the operator's local key with hard_cap=None
  (already supported) — it's metered for served-usage but never budget-
  refused and never hits upstream.

helexa-upstream:
- POST /authz/v1/served-usage: upserts rows keyed by (operator_id from the
  client bearer, account, key, period) with
  GREATEST(existing, incoming) — monotonic + idempotent, so re-sends,
  races, and a restarted cortex's lower counter never regress the total.
- reconcile.rs + `helexa-upstream reconcile` CLI: rolls up unreconciled
  served_usage per operator/period (SUM::bigint), stamps reconciled_at,
  prints the totals. Payout mechanism out of scope.

Validated against a throwaway Postgres: monotonic upsert (100→250, a 50
re-send stays 250, same-value idempotent) and reconcile rollup +
stamp-once; cortex counter unit test for per-principal accumulation.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01F6o3ddqmYNh9kzdwq6eowh

Cargo.toml

@@ -9,6 +9,7 @@ members = [
     "crates/helexa-bench",
     "crates/helexa-router",
     "crates/helexa-stream",
+    "crates/helexa-upstream",
 ]
 
 [workspace.package]

cortex.example.toml

@@ -90,3 +90,20 @@ account_id = "operator"
 key_id = "infra"
 # No hard_cap → uncapped operator infra key (own fleet, own use). Still
 # metered for visibility.
+
+# -- Upstream (helexa mesh) entitlements client (#57) --------------------
+# When enabled, a bearer key NOT found in [[entitlements.keys]] above is
+# validated against the helexa-upstream authority (mesh accounts), and its
+# budget is reserved/settled there. Operator-local keys (incl. the infra
+# key) never leave this process. Fail-closed: if upstream is unreachable a
+# request is refused (503 + Retry-After), never served un-authorized.
+# Disabled by default — a standalone operator runs purely local.
+[upstream]
+enabled = false
+# url = "https://upstream.helexa.ai"
+# Shared client bearer this cortex presents (maps to an operator_id
+# upstream). Override via CORTEX_UPSTREAM__BEARER in prod.
+# bearer = "replace-with-operator-client-secret"
+# timeout_secs = 5
+# How often to flush served-usage counters to upstream for reconciliation (#58).
+# served_usage_report_interval_secs = 60

crates/cortex-core/src/config.rs

@@ -22,6 +22,43 @@ pub struct GatewayConfig {
     /// setups keep working until keys are configured.
     #[serde(default)]
     pub entitlements: EntitlementsConfig,
+    /// helexa-upstream client (#57). When enabled, keys not found in the
+    /// local `[entitlements]` config are validated against the mesh
+    /// authority, and budget is reserved/settled there. Disabled by default
+    /// — a single operator runs purely local.
+    #[serde(default)]
+    pub upstream: UpstreamClientConfig,
+}
+
+/// `[upstream]` — the helexa-upstream authority client (#57). Locally
+/// unrecognised bearer keys are resolved against `url`'s `/authz/v1` surface
+/// (mesh accounts); local keys (operator + infra) never leave the process.
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub struct UpstreamClientConfig {
+    /// Enable the upstream fallthrough. Off → purely local entitlements.
+    #[serde(default)]
+    pub enabled: bool,
+    /// Base URL of helexa-upstream (e.g. "https://upstream.helexa.ai").
+    #[serde(default)]
+    pub url: String,
+    /// Shared client bearer this cortex presents to `/authz/v1` (maps to an
+    /// operator_id upstream). Sent as `Authorization: Bearer <bearer>`.
+    #[serde(default)]
+    pub bearer: String,
+    /// Per-call timeout (seconds) to upstream.
+    #[serde(default = "default_upstream_timeout")]
+    pub timeout_secs: u64,
+    /// How often (seconds) to flush served-usage counters to upstream for
+    /// reconciliation (#58).
+    #[serde(default = "default_served_usage_interval")]
+    pub served_usage_report_interval_secs: u64,
+}
+
+fn default_upstream_timeout() -> u64 {
+    5
+}
+fn default_served_usage_interval() -> u64 {
+    60
 }
 
 /// `[entitlements]` — the local/static [`crate::entitlements::EntitlementProvider`]
@@ -129,6 +166,7 @@ impl Default for GatewayConfig {
             neurons: vec![],
             models_config: default_models_path(),
             entitlements: EntitlementsConfig::default(),
+            upstream: UpstreamClientConfig::default(),
         }
     }
 }

crates/cortex-core/src/entitlements.rs

@@ -81,12 +81,19 @@ pub struct BudgetSnapshot {
     pub reserved: u64,
 }
 
-/// Authentication failure — the bearer key could not be resolved. Maps to
-/// `401 invalid_api_key` (#49/#63).
+/// Authentication failure — the bearer key could not be resolved.
 #[derive(Debug, thiserror::Error)]
 pub enum AuthError {
+    /// The key is genuinely unknown → `401 invalid_api_key` (#49/#63).
     #[error("invalid or unknown API key")]
     InvalidKey,
+    /// The authority that could resolve the key is unreachable (e.g. the
+    /// helexa-upstream client failed, #57). Fail **closed** but distinctly:
+    /// a transient outage must surface as `503 service_unavailable` +
+    /// `Retry-After`, never `401` — a real key must not be rejected as
+    /// invalid during an upstream blip.
+    #[error("entitlement authority unavailable; retry in {retry_after_secs}s")]
+    Unavailable { retry_after_secs: u64 },
 }
 
 /// Why a reservation was refused. Carries enough for the caller to build the

crates/cortex-gateway/src/auth.rs

@@ -22,7 +22,7 @@ use axum::http::header::AUTHORIZATION;
 use axum::http::{HeaderMap, HeaderValue};
 use axum::middleware::Next;
 use axum::response::Response;
-use cortex_core::entitlements::{HEADER_ACCOUNT_ID, HEADER_KEY_ID};
+use cortex_core::entitlements::{AuthError, HEADER_ACCOUNT_ID, HEADER_KEY_ID};
 use cortex_core::error_envelope::OpenAiError;
 use std::sync::Arc;
 
@@ -83,14 +83,25 @@ pub async fn require_principal(
                 req.extensions_mut().insert(principal);
                 next.run(req).await
             }
-            // An unrecognized key only hard-fails when auth is *required*.
-            // In allow-anonymous mode (the default) we must IGNORE it and
-            // serve the request unauthenticated — otherwise the placeholder
-            // keys that OpenAI-compatible clients send by default (opencode,
-            // Open WebUI, Agent Zero, litellm) would all break, even though
-            // the operator never opted into auth. Pre-#49 the bearer was
-            // never inspected at all; this preserves that for require_auth=false.
-            Err(_) => {
+            // The entitlement authority is unreachable (upstream client
+            // blip, #57). Fail **closed but distinct**: a transient outage
+            // must not reject a real key as `401 invalid_api_key` — it's a
+            // retryable `503`. This holds regardless of require_auth: we
+            // can't safely serve a key we couldn't authorize.
+            Err(AuthError::Unavailable { retry_after_secs }) => {
+                envelope_response(OpenAiError::service_unavailable(
+                    "entitlement authority temporarily unavailable",
+                    Some(retry_after_secs),
+                ))
+            }
+            // A genuinely unrecognized key only hard-fails when auth is
+            // *required*. In allow-anonymous mode (the default) we IGNORE it
+            // and serve unauthenticated — otherwise the placeholder keys that
+            // OpenAI-compatible clients send by default (opencode, Open WebUI,
+            // Agent Zero, litellm) would all break though the operator never
+            // opted into auth. Pre-#49 the bearer was never inspected; this
+            // preserves that for require_auth=false.
+            Err(AuthError::InvalidKey) => {
                 if fleet.require_auth {
                     unauthorized("invalid API key")
                 } else {

crates/cortex-gateway/src/entitlements_chain.rs

@@ -0,0 +1,112 @@
+//! Chained entitlement provider (#57): operator-local keys first, mesh
+//! upstream for everything else.
+//!
+//! `resolve` tries the [`LocalEntitlementProvider`] (operator + infra keys —
+//! never a network hop); only a locally-unknown key falls through to
+//! [`UpstreamEntitlementProvider`]. Because the local provider treats an
+//! unconfigured principal as uncapped, reserve/settle/release/snapshot must
+//! **not** blindly hit local — they dispatch to whichever backend resolved
+//! that account, remembered in a map keyed by `account_id` (populated at
+//! resolve time).
+
+use crate::entitlements_local::LocalEntitlementProvider;
+use crate::entitlements_upstream::UpstreamEntitlementProvider;
+use async_trait::async_trait;
+use cortex_core::entitlements::{
+    AuthError, BudgetError, BudgetSnapshot, EntitlementProvider, Principal, Reservation,
+};
+use std::collections::HashMap;
+use tokio::sync::RwLock;
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum Backend {
+    Local,
+    Upstream,
+}
+
+pub struct ChainedEntitlementProvider {
+    local: LocalEntitlementProvider,
+    upstream: UpstreamEntitlementProvider,
+    /// account_id → which backend owns it, learned at resolve time.
+    backends: RwLock<HashMap<String, Backend>>,
+}
+
+impl ChainedEntitlementProvider {
+    pub fn new(local: LocalEntitlementProvider, upstream: UpstreamEntitlementProvider) -> Self {
+        Self {
+            local,
+            upstream,
+            backends: RwLock::new(HashMap::new()),
+        }
+    }
+
+    async fn record(&self, account_id: &str, backend: Backend) {
+        self.backends
+            .write()
+            .await
+            .insert(account_id.to_string(), backend);
+    }
+
+    /// The backend that owns `account_id`. Defaults to `Upstream` for an
+    /// account never resolved this process-lifetime (a resolve always
+    /// precedes reserve in a request, so this is just a safe fallback —
+    /// upstream fails closed if the account is bogus).
+    async fn backend_for(&self, account_id: &str) -> Backend {
+        self.backends
+            .read()
+            .await
+            .get(account_id)
+            .copied()
+            .unwrap_or(Backend::Upstream)
+    }
+}
+
+#[async_trait]
+impl EntitlementProvider for ChainedEntitlementProvider {
+    async fn resolve(&self, api_key: &str) -> Result<Principal, AuthError> {
+        match self.local.resolve(api_key).await {
+            Ok(p) => {
+                self.record(&p.account_id, Backend::Local).await;
+                Ok(p)
+            }
+            Err(AuthError::InvalidKey) => {
+                let p = self.upstream.resolve(api_key).await?;
+                self.record(&p.account_id, Backend::Upstream).await;
+                Ok(p)
+            }
+            Err(e) => Err(e),
+        }
+    }
+
+    async fn reserve(
+        &self,
+        principal: &Principal,
+        max_tokens: u64,
+    ) -> Result<Reservation, BudgetError> {
+        match self.backend_for(&principal.account_id).await {
+            Backend::Local => self.local.reserve(principal, max_tokens).await,
+            Backend::Upstream => self.upstream.reserve(principal, max_tokens).await,
+        }
+    }
+
+    async fn settle(&self, reservation: Reservation, actual_tokens: u64) {
+        match self.backend_for(&reservation.principal.account_id).await {
+            Backend::Local => self.local.settle(reservation, actual_tokens).await,
+            Backend::Upstream => self.upstream.settle(reservation, actual_tokens).await,
+        }
+    }
+
+    async fn release(&self, reservation: Reservation) {
+        match self.backend_for(&reservation.principal.account_id).await {
+            Backend::Local => self.local.release(reservation).await,
+            Backend::Upstream => self.upstream.release(reservation).await,
+        }
+    }
+
+    async fn snapshot(&self, principal: &Principal) -> Option<BudgetSnapshot> {
+        match self.backend_for(&principal.account_id).await {
+            Backend::Local => self.local.snapshot(principal).await,
+            Backend::Upstream => self.upstream.snapshot(principal).await,
+        }
+    }
+}

crates/cortex-gateway/src/entitlements_upstream.rs

@@ -0,0 +1,246 @@
+//! helexa-upstream client (#57): an [`EntitlementProvider`] that resolves
+//! keys and reserves/settles budget against the mesh authority's
+//! `/authz/v1` surface (B2). It is "just another impl of the trait" — cortex
+//! enforcement (`auth.rs`, `metering.rs`) is unchanged.
+//!
+//! **Fail closed.** When upstream is unreachable, `resolve` returns
+//! [`AuthError::Unavailable`] (→ `503`, never `401`) and `reserve` refuses
+//! with a retryable [`BudgetError::RateLimited`] — a request is never served
+//! on an un-authorized key, and a real key is never rejected as invalid
+//! during a blip.
+
+use async_trait::async_trait;
+use cortex_core::config::UpstreamClientConfig;
+use cortex_core::entitlements::{
+    AuthError, BudgetError, BudgetSnapshot, EntitlementProvider, Principal, Reservation,
+};
+use serde::Deserialize;
+use std::time::Duration;
+
+/// Retry-After (seconds) advertised when we fail closed on an upstream
+/// outage.
+const FAIL_CLOSED_RETRY_SECS: u64 = 5;
+
+pub struct UpstreamEntitlementProvider {
+    client: reqwest::Client,
+    base_url: String,
+    bearer: String,
+}
+
+#[derive(Deserialize)]
+struct PrincipalDto {
+    account_id: String,
+    key_id: String,
+}
+#[derive(Deserialize)]
+struct SnapshotDto {
+    hard_cap: Option<u64>,
+    spent: u64,
+    reserved: u64,
+}
+#[derive(Deserialize)]
+struct ResolveResp {
+    principal: PrincipalDto,
+    #[allow(dead_code)]
+    snapshot: Option<SnapshotDto>,
+}
+#[derive(Deserialize)]
+struct ReserveResp {
+    reservation_id: Option<i64>,
+    rejected: Option<Rejection>,
+}
+#[derive(Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+enum Rejection {
+    InsufficientQuota {
+        requested: u64,
+        available: u64,
+    },
+    RateLimited {
+        requested: u64,
+        available: u64,
+        retry_after_secs: u64,
+    },
+}
+
+impl UpstreamEntitlementProvider {
+    pub fn new(cfg: &UpstreamClientConfig) -> Self {
+        let client = reqwest::Client::builder()
+            .timeout(Duration::from_secs(cfg.timeout_secs))
+            .build()
+            .expect("failed to build upstream HTTP client");
+        Self {
+            client,
+            base_url: cfg.url.trim_end_matches('/').to_string(),
+            bearer: cfg.bearer.clone(),
+        }
+    }
+
+    fn url(&self, path: &str) -> String {
+        format!("{}{}", self.base_url, path)
+    }
+}
+
+#[async_trait]
+impl EntitlementProvider for UpstreamEntitlementProvider {
+    async fn resolve(&self, api_key: &str) -> Result<Principal, AuthError> {
+        let resp = self
+            .client
+            .post(self.url("/authz/v1/resolve"))
+            .bearer_auth(&self.bearer)
+            .json(&serde_json::json!({ "api_key": api_key }))
+            .send()
+            .await;
+        let resp = match resp {
+            Ok(r) => r,
+            Err(e) => {
+                tracing::warn!(error = %e, "upstream resolve unreachable; failing closed");
+                return Err(AuthError::Unavailable {
+                    retry_after_secs: FAIL_CLOSED_RETRY_SECS,
+                });
+            }
+        };
+        if resp.status().as_u16() == 401 {
+            return Err(AuthError::InvalidKey);
+        }
+        if !resp.status().is_success() {
+            return Err(AuthError::Unavailable {
+                retry_after_secs: FAIL_CLOSED_RETRY_SECS,
+            });
+        }
+        match resp.json::<ResolveResp>().await {
+            Ok(r) => Ok(Principal {
+                account_id: r.principal.account_id,
+                key_id: r.principal.key_id,
+            }),
+            Err(e) => {
+                tracing::warn!(error = %e, "upstream resolve: bad body; failing closed");
+                Err(AuthError::Unavailable {
+                    retry_after_secs: FAIL_CLOSED_RETRY_SECS,
+                })
+            }
+        }
+    }
+
+    async fn reserve(
+        &self,
+        principal: &Principal,
+        max_tokens: u64,
+    ) -> Result<Reservation, BudgetError> {
+        let fail_closed = || BudgetError::RateLimited {
+            requested: max_tokens,
+            available: 0,
+            retry_after_secs: FAIL_CLOSED_RETRY_SECS,
+        };
+        let resp = self
+            .client
+            .post(self.url("/authz/v1/reserve"))
+            .bearer_auth(&self.bearer)
+            .json(&serde_json::json!({
+                "account_id": principal.account_id,
+                "key_id": principal.key_id,
+                "max_tokens": max_tokens,
+            }))
+            .send()
+            .await;
+        let resp = match resp {
+            Ok(r) if r.status().is_success() => r,
+            Ok(r) => {
+                tracing::warn!(status = %r.status(), "upstream reserve non-2xx; failing closed");
+                return Err(fail_closed());
+            }
+            Err(e) => {
+                tracing::warn!(error = %e, "upstream reserve unreachable; failing closed");
+                return Err(fail_closed());
+            }
+        };
+        match resp.json::<ReserveResp>().await {
+            Ok(ReserveResp {
+                reservation_id: Some(id),
+                ..
+            }) => Ok(Reservation {
+                id: id as u64,
+                principal: principal.clone(),
+                reserved: max_tokens,
+            }),
+            Ok(ReserveResp {
+                rejected:
+                    Some(Rejection::InsufficientQuota {
+                        requested,
+                        available,
+                    }),
+                ..
+            }) => Err(BudgetError::InsufficientQuota {
+                requested,
+                available,
+            }),
+            Ok(ReserveResp {
+                rejected:
+                    Some(Rejection::RateLimited {
+                        requested,
+                        available,
+                        retry_after_secs,
+                    }),
+                ..
+            }) => Err(BudgetError::RateLimited {
+                requested,
+                available,
+                retry_after_secs,
+            }),
+            _ => Err(fail_closed()),
+        }
+    }
+
+    async fn settle(&self, reservation: Reservation, actual_tokens: u64) {
+        // Best-effort; a lost settle is reaped by the upstream sweeper (B2).
+        let _ = self
+            .client
+            .post(self.url("/authz/v1/settle"))
+            .bearer_auth(&self.bearer)
+            .json(&serde_json::json!({
+                "reservation_id": reservation.id as i64,
+                "actual_tokens": actual_tokens,
+            }))
+            .send()
+            .await
+            .inspect_err(
+                |e| tracing::warn!(error = %e, "upstream settle failed (sweeper will reap)"),
+            );
+    }
+
+    async fn release(&self, reservation: Reservation) {
+        let _ = self
+            .client
+            .post(self.url("/authz/v1/release"))
+            .bearer_auth(&self.bearer)
+            .json(&serde_json::json!({ "reservation_id": reservation.id as i64 }))
+            .send()
+            .await
+            .inspect_err(
+                |e| tracing::warn!(error = %e, "upstream release failed (sweeper will reap)"),
+            );
+    }
+
+    async fn snapshot(&self, principal: &Principal) -> Option<BudgetSnapshot> {
+        let resp = self
+            .client
+            .post(self.url("/authz/v1/snapshot"))
+            .bearer_auth(&self.bearer)
+            .json(&serde_json::json!({
+                "account_id": principal.account_id,
+                "key_id": principal.key_id,
+            }))
+            .send()
+            .await
+            .ok()?;
+        if !resp.status().is_success() {
+            return None;
+        }
+        let dto = resp.json::<SnapshotDto>().await.ok()?;
+        Some(BudgetSnapshot {
+            hard_cap: dto.hard_cap,
+            spent: dto.spent,
+            reserved: dto.reserved,
+        })
+    }
+}

crates/cortex-gateway/src/handlers.rs

@@ -322,7 +322,11 @@ async fn anthropic_messages(
             )
             .await
             {
-                Ok(guard) => Some(crate::metering::usage_sink(principal, guard)),
+                Ok(guard) => Some(crate::metering::usage_sink(
+                    principal,
+                    guard,
+                    std::sync::Arc::clone(&fleet.served_usage),
+                )),
                 Err(env) => return crate::error::envelope_response(env),
             }
         }
@@ -802,7 +806,11 @@ async fn proxy_with_metrics(
             )
             .await
             {
-                Ok(guard) => Some(crate::metering::usage_sink(principal, guard)),
+                Ok(guard) => Some(crate::metering::usage_sink(
+                    principal,
+                    guard,
+                    std::sync::Arc::clone(&fleet.served_usage),
+                )),
                 Err(env) => return crate::error::envelope_response(env),
             }
         }

crates/cortex-gateway/src/lib.rs

@@ -1,6 +1,8 @@
 pub mod anthropic_sse;
 pub mod auth;
+pub mod entitlements_chain;
 pub mod entitlements_local;
+pub mod entitlements_upstream;
 pub mod error;
 pub mod evictor;
 pub mod handlers;
@@ -9,6 +11,7 @@ pub mod metrics;
 pub mod poller;
 pub mod proxy;
 pub mod router;
+pub mod served_usage;
 pub mod state;
 
 use anyhow::Result;
@@ -55,6 +58,28 @@ pub async fn run(config: GatewayConfig) -> Result<()> {
         evictor::eviction_loop(evictor_fleet).await;
     });
 
+    // Served-usage reporter (#58): when this operator is part of the mesh,
+    // periodically flush absolute per-principal served-token counters to
+    // upstream for reconciliation.
+    if config.upstream.enabled {
+        let su_fleet = Arc::clone(&fleet);
+        let url = config.upstream.url.clone();
+        let bearer = config.upstream.bearer.clone();
+        let interval =
+            std::time::Duration::from_secs(config.upstream.served_usage_report_interval_secs);
+        tokio::spawn(async move {
+            loop {
+                tokio::time::sleep(interval).await;
+                let rows = su_fleet.served_usage.snapshot();
+                if let Err(e) =
+                    served_usage::report(&su_fleet.http_client, &url, &bearer, &rows).await
+                {
+                    tracing::warn!(error = %e, "served-usage report failed (will retry)");
+                }
+            }
+        });
+    }
+
     let app = build_app(Arc::clone(&fleet));
 
     let listen_addr = config.gateway.listen.parse::<std::net::SocketAddr>()?;

crates/cortex-gateway/src/metering.rs

@@ -117,9 +117,21 @@ impl Drop for ReservationGuard {
 /// Build the completion sink for an authenticated request: record spend and
 /// settle the reservation with the observed total. Dropping it unused (no
 /// usage observed) releases the reservation via the guard.
-pub fn usage_sink(principal: Principal, guard: ReservationGuard) -> UsageSink {
+pub fn usage_sink(
+    principal: Principal,
+    guard: ReservationGuard,
+    served_usage: std::sync::Arc<crate::served_usage::ServedUsage>,
+) -> UsageSink {
     Box::new(move |prompt, completion| {
         record_spend(&principal, prompt, completion);
+        // Per-principal served-usage tally for #58 reconciliation. Recorded
+        // for every metered (authenticated) request; the flush task reports
+        // it to upstream when the operator is part of the mesh.
+        served_usage.add(
+            &principal.account_id,
+            &principal.key_id,
+            prompt + completion,
+        );
         guard.settle(prompt + completion);
     })
 }

crates/cortex-gateway/src/served_usage.rs

@@ -0,0 +1,105 @@
+//! Served-usage ledger (#58): cortex meters, per principal and per UTC day,
+//! the tokens it has served on behalf of mesh accounts, and periodically
+//! reports **absolute** cumulative counters to helexa-upstream for
+//! reconciliation (operators are compensated for served tokens).
+//!
+//! Counters are cumulative-since-process-start for the current period;
+//! upstream upserts them monotonically (GREATEST), so re-sending the same
+//! value is idempotent and a flush that races another is harmless. (A
+//! process restart resets the in-memory counter; the monotonic upsert keeps
+//! upstream from regressing — at most it under-counts the restarted window,
+//! acceptable for beta. One cortex per operator token is assumed.)
+
+use serde::Serialize;
+use std::collections::HashMap;
+use std::sync::Mutex;
+
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+pub struct ServedRow {
+    pub account_id: String,
+    pub key_id: String,
+    pub period: String, // YYYY-MM-DD (UTC)
+    pub served_tokens: u64,
+}
+
+#[derive(Default)]
+pub struct ServedUsage {
+    inner: Mutex<HashMap<(String, String, String), u64>>,
+}
+
+impl ServedUsage {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Add served tokens for a principal in today's (UTC) period.
+    pub fn add(&self, account_id: &str, key_id: &str, tokens: u64) {
+        if tokens == 0 {
+            return;
+        }
+        let period = chrono::Utc::now().format("%Y-%m-%d").to_string();
+        let mut m = self.inner.lock().expect("served-usage lock");
+        *m.entry((account_id.to_string(), key_id.to_string(), period))
+            .or_insert(0) += tokens;
+    }
+
+    /// Absolute cumulative counters, for a flush to upstream.
+    pub fn snapshot(&self) -> Vec<ServedRow> {
+        let m = self.inner.lock().expect("served-usage lock");
+        m.iter()
+            .map(|((account_id, key_id, period), &served_tokens)| ServedRow {
+                account_id: account_id.clone(),
+                key_id: key_id.clone(),
+                period: period.clone(),
+                served_tokens,
+            })
+            .collect()
+    }
+}
+
+/// POST the absolute counters to upstream's `/authz/v1/served-usage`.
+pub async fn report(
+    client: &reqwest::Client,
+    base_url: &str,
+    bearer: &str,
+    rows: &[ServedRow],
+) -> Result<(), reqwest::Error> {
+    if rows.is_empty() {
+        return Ok(());
+    }
+    let url = format!("{}/authz/v1/served-usage", base_url.trim_end_matches('/'));
+    client
+        .post(url)
+        .bearer_auth(bearer)
+        .json(&serde_json::json!({ "rows": rows }))
+        .send()
+        .await?
+        .error_for_status()?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn accumulates_per_principal_and_period() {
+        let su = ServedUsage::new();
+        su.add("acct", "key", 10);
+        su.add("acct", "key", 5);
+        su.add("acct", "other", 7);
+        su.add("acct", "key", 0); // no-op
+        let mut rows = su.snapshot();
+        rows.sort_by(|a, b| a.key_id.cmp(&b.key_id));
+        assert_eq!(rows.len(), 2);
+        let key_row = rows.iter().find(|r| r.key_id == "key").unwrap();
+        assert_eq!(key_row.served_tokens, 15);
+        assert_eq!(
+            rows.iter()
+                .find(|r| r.key_id == "other")
+                .unwrap()
+                .served_tokens,
+            7
+        );
+    }
+}

crates/cortex-gateway/src/state.rs

@@ -1,4 +1,6 @@
+use crate::entitlements_chain::ChainedEntitlementProvider;
 use crate::entitlements_local::LocalEntitlementProvider;
+use crate::entitlements_upstream::UpstreamEntitlementProvider;
 use cortex_core::catalogue::ModelCatalogue;
 use cortex_core::config::{EvictionSettings, GatewayConfig, NeuronEndpoint};
 use cortex_core::entitlements::EntitlementProvider;
@@ -20,6 +22,9 @@ pub struct CortexState {
     /// Whether to reject unauthenticated requests (#49). Read by the auth
     /// middleware once it lands.
     pub require_auth: bool,
+    /// Per-principal served-token tally (#58), reported to upstream for
+    /// operator reconciliation by the flush task when upstream is enabled.
+    pub served_usage: Arc<crate::served_usage::ServedUsage>,
 }
 
 impl CortexState {
@@ -45,8 +50,20 @@ impl CortexState {
 
         let catalogue = ModelCatalogue::load(&config.models_config);
 
-        let entitlements: Arc<dyn EntitlementProvider> =
-            Arc::new(LocalEntitlementProvider::from_config(&config.entitlements));
+        // Local provider always handles operator + infra keys. When the
+        // upstream client is enabled (#57), wrap it in the chain so locally
+        // unknown keys fall through to the mesh authority; otherwise stay
+        // purely local.
+        let local = LocalEntitlementProvider::from_config(&config.entitlements);
+        let entitlements: Arc<dyn EntitlementProvider> = if config.upstream.enabled {
+            tracing::info!(url = %config.upstream.url, "upstream entitlement client enabled");
+            Arc::new(ChainedEntitlementProvider::new(
+                local,
+                UpstreamEntitlementProvider::new(&config.upstream),
+            ))
+        } else {
+            Arc::new(local)
+        };
 
         Self {
             nodes: RwLock::new(nodes),
@@ -59,6 +76,7 @@ impl CortexState {
                 .expect("failed to build HTTP client"),
             entitlements,
             require_auth: config.entitlements.require_auth,
+            served_usage: Arc::new(crate::served_usage::ServedUsage::new()),
         }
     }
 }

crates/cortex-gateway/tests/aliases.rs

@@ -57,6 +57,7 @@ async fn test_alias_resolves_in_chat_completions() {
         }],
         models_config: models_path.to_string_lossy().to_string(),
         entitlements: Default::default(),
+        upstream: Default::default(),
     };
 
     let fleet = Arc::new(CortexState::from_config(&config));
@@ -143,6 +144,7 @@ async fn test_aliases_surface_in_v1_models() {
         }],
         models_config: models_path.to_string_lossy().to_string(),
         entitlements: Default::default(),
+        upstream: Default::default(),
     };
 
     let fleet = Arc::new(CortexState::from_config(&config));
@@ -232,6 +234,7 @@ async fn test_alias_falls_through_for_unmapped_model() {
         }],
         models_config: models_path.to_string_lossy().to_string(),
         entitlements: Default::default(),
+        upstream: Default::default(),
     };
 
     let fleet = Arc::new(CortexState::from_config(&config));

crates/cortex-gateway/tests/auth.rs

@@ -105,6 +105,7 @@ async fn spawn_gateway(neuron_url: &str, entitlements: EntitlementsConfig) -> St
         }],
         models_config: "/dev/null".into(),
         entitlements,
+        upstream: Default::default(),
     };
 
     let fleet = Arc::new(CortexState::from_config(&config));

crates/cortex-gateway/tests/budget_enforcement.rs

@@ -81,6 +81,7 @@ async fn spawn_gateway(neuron_url: &str, key: ApiKeyConfig) -> (Arc<CortexState>
             require_auth: true,
             keys: vec![key],
         },
+        upstream: Default::default(),
     };
     let fleet = Arc::new(CortexState::from_config(&config));
     {

crates/cortex-gateway/tests/common/mod.rs

@@ -430,6 +430,7 @@ pub async fn spawn_gateway_with_state(mock_url: &str) -> (Arc<CortexState>, Stri
         }],
         models_config: "/dev/null".into(),
         entitlements: Default::default(),
+        upstream: Default::default(),
     };
 
     let fleet = Arc::new(CortexState::from_config(&config));

crates/cortex-gateway/tests/error_envelope.rs

@@ -89,6 +89,7 @@ async fn error_response_no_healthy_nodes() {
         }],
         models_config: "/dev/null".into(),
         entitlements: Default::default(),
+        upstream: Default::default(),
     };
 
     let fleet = Arc::new(cortex_gateway::state::CortexState::from_config(&config));

crates/cortex-gateway/tests/eviction.rs

@@ -72,6 +72,7 @@ fn make_fleet(endpoint: &str, defrag_after: u32) -> Arc<CortexState> {
         }],
         models_config: "/dev/null".into(),
         entitlements: Default::default(),
+        upstream: Default::default(),
     };
     Arc::new(CortexState::from_config(&config))
 }

crates/cortex-gateway/tests/feasibility_routing.rs

@@ -74,6 +74,7 @@ async fn fleet_with(big_healthy: bool, big_devices: usize) -> Arc<CortexState> {
         ],
         models_config: cat.to_string_lossy().into_owned(),
         entitlements: Default::default(),
+        upstream: Default::default(),
     };
     let fleet = Arc::new(CortexState::from_config(&config));
     {

crates/cortex-gateway/tests/load_routing.rs

@@ -72,6 +72,7 @@ async fn two_neuron_fleet(endpoint_a: &str, endpoint_b: &str) -> Arc<CortexState
         ],
         models_config: "/dev/null".into(),
         entitlements: Default::default(),
+        upstream: Default::default(),
     };
     Arc::new(CortexState::from_config(&config))
 }

crates/cortex-gateway/tests/metering.rs

@@ -53,6 +53,7 @@ async fn spawn_metered_gateway(neuron_url: &str) -> (Arc<CortexState>, String) {
                 window: CapWindow::Balance,
             }],
         },
+        upstream: Default::default(),
     };
 
     let fleet = Arc::new(CortexState::from_config(&config));
@@ -158,6 +159,7 @@ async fn anonymous_request_records_no_spend() {
         }],
         models_config: "/dev/null".into(),
         entitlements: EntitlementsConfig::default(),
+        upstream: Default::default(),
     };
     let fleet = Arc::new(CortexState::from_config(&config));
     {

crates/cortex-gateway/tests/model_cost.rs

@@ -66,6 +66,7 @@ harness = "candle"
         }],
         models_config: cat_path.to_string_lossy().into_owned(),
         entitlements: Default::default(),
+        upstream: Default::default(),
     };
 
     let fleet = Arc::new(CortexState::from_config(&config));

crates/cortex-gateway/tests/model_limits.rs

@@ -55,6 +55,7 @@ capabilities = ["text"]
         }],
         models_config: cat_path.to_string_lossy().into_owned(),
         entitlements: Default::default(),
+        upstream: Default::default(),
     };
 
     let fleet = Arc::new(CortexState::from_config(&config));

crates/cortex-gateway/tests/poller.rs

@@ -32,6 +32,7 @@ async fn test_poller_discovers_models() {
         }],
         models_config: "/dev/null".into(),
         entitlements: Default::default(),
+        upstream: Default::default(),
     };
 
     let fleet = Arc::new(CortexState::from_config(&config));
@@ -84,6 +85,7 @@ async fn test_poller_updates_gateway_models_endpoint() {
         }],
         models_config: "/dev/null".into(),
         entitlements: Default::default(),
+        upstream: Default::default(),
     };
 
     let fleet = Arc::new(CortexState::from_config(&config));
@@ -156,6 +158,7 @@ async fn test_models_endpoint_unions_capabilities_across_nodes() {
         ],
         models_config: "/dev/null".into(),
         entitlements: Default::default(),
+        upstream: Default::default(),
     };
 
     let fleet = Arc::new(CortexState::from_config(&config));
@@ -219,6 +222,7 @@ async fn test_poller_marks_unreachable_node_unhealthy() {
         }],
         models_config: "/dev/null".into(),
         entitlements: Default::default(),
+        upstream: Default::default(),
     };
 
     let fleet = Arc::new(CortexState::from_config(&config));
@@ -273,6 +277,7 @@ async fn test_poller_removes_stale_models() {
         }],
         models_config: "/dev/null".into(),
         entitlements: Default::default(),
+        upstream: Default::default(),
     };
 
     let fleet = Arc::new(CortexState::from_config(&config));
@@ -304,6 +309,7 @@ async fn test_poller_removes_stale_models() {
         }],
         models_config: "/dev/null".into(),
         entitlements: Default::default(),
+        upstream: Default::default(),
     };
 
     let fleet2 = Arc::new(CortexState::from_config(&config2));
@@ -386,6 +392,7 @@ async fn test_poller_captures_activation_from_health() {
         }],
         models_config: "/dev/null".into(),
         entitlements: Default::default(),
+        upstream: Default::default(),
     };
 
     let fleet = Arc::new(CortexState::from_config(&config));
@@ -431,6 +438,7 @@ async fn test_poller_parses_recovering_status() {
         }],
         models_config: "/dev/null".into(),
         entitlements: Default::default(),
+        upstream: Default::default(),
     };
 
     let fleet = Arc::new(CortexState::from_config(&config));

crates/cortex-gateway/tests/prompt_prevalidation.rs

@@ -75,6 +75,7 @@ async fn spawn_gateway(neuron: &str, context: usize) -> String {
         }],
         models_config: "/dev/null".into(),
         entitlements: Default::default(),
+        upstream: Default::default(),
     };
     let fleet = Arc::new(CortexState::from_config(&config));
     {

crates/cortex-gateway/tests/proxy_basic.rs

@@ -118,6 +118,7 @@ async fn test_no_healthy_nodes() {
         }],
         models_config: "/dev/null".into(),
         entitlements: Default::default(),
+        upstream: Default::default(),
     };
     let fleet = std::sync::Arc::new(cortex_gateway::state::CortexState::from_config(&config));
 

crates/cortex-gateway/tests/upstream_chain.rs

@@ -0,0 +1,106 @@
+//! B3: the chained entitlement provider (local → upstream) and fail-closed
+//! semantics, exercised against a mock helexa-upstream `/authz/v1`.
+
+use axum::{Json, Router, routing::post};
+use cortex_core::config::{ApiKeyConfig, EntitlementsConfig, UpstreamClientConfig};
+use cortex_core::entitlements::{AuthError, EntitlementProvider};
+use cortex_gateway::entitlements_chain::ChainedEntitlementProvider;
+use cortex_gateway::entitlements_local::LocalEntitlementProvider;
+use cortex_gateway::entitlements_upstream::UpstreamEntitlementProvider;
+use serde_json::{Value, json};
+use tokio::net::TcpListener;
+
+/// Mock upstream: `mesh-key` resolves to a mesh account; anything else 401.
+/// reserve always grants reservation 1.
+async fn spawn_mock_upstream() -> String {
+    async fn resolve(Json(body): Json<Value>) -> axum::response::Response {
+        use axum::response::IntoResponse;
+        if body["api_key"] == "mesh-key" {
+            Json(json!({"principal": {"account_id": "mesh-acct", "key_id": "mesh-key-1"}}))
+                .into_response()
+        } else {
+            (
+                axum::http::StatusCode::UNAUTHORIZED,
+                Json(json!({"error": {"code": "invalid_api_key"}})),
+            )
+                .into_response()
+        }
+    }
+    async fn reserve() -> Json<Value> {
+        Json(json!({ "reservation_id": 1 }))
+    }
+    let app = Router::new()
+        .route("/authz/v1/resolve", post(resolve))
+        .route("/authz/v1/reserve", post(reserve));
+    let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let addr = listener.local_addr().unwrap();
+    tokio::spawn(async move {
+        axum::serve(listener, app).await.unwrap();
+    });
+    format!("http://{addr}")
+}
+
+fn local_with_key() -> LocalEntitlementProvider {
+    let cfg = EntitlementsConfig {
+        require_auth: false,
+        keys: vec![ApiKeyConfig {
+            key: "local-key".into(),
+            account_id: "op".into(),
+            key_id: None,
+            hard_cap: None,
+            window: Default::default(),
+        }],
+    };
+    LocalEntitlementProvider::from_config(&cfg)
+}
+
+fn chain(local: LocalEntitlementProvider, url: &str) -> ChainedEntitlementProvider {
+    let upstream = UpstreamEntitlementProvider::new(&UpstreamClientConfig {
+        enabled: true,
+        url: url.to_string(),
+        bearer: "client-secret".into(),
+        timeout_secs: 5,
+        served_usage_report_interval_secs: 60,
+    });
+    ChainedEntitlementProvider::new(local, upstream)
+}
+
+#[tokio::test]
+async fn local_key_resolves_locally() {
+    let url = spawn_mock_upstream().await;
+    let c = chain(local_with_key(), &url);
+    let p = c.resolve("local-key").await.expect("local resolves");
+    assert_eq!(p.account_id, "op");
+}
+
+#[tokio::test]
+async fn unknown_key_falls_through_to_upstream() {
+    let url = spawn_mock_upstream().await;
+    let c = chain(local_with_key(), &url);
+    let p = c.resolve("mesh-key").await.expect("upstream resolves");
+    assert_eq!(p.account_id, "mesh-acct");
+    assert_eq!(p.key_id, "mesh-key-1");
+}
+
+#[tokio::test]
+async fn unknown_everywhere_is_invalid_key() {
+    let url = spawn_mock_upstream().await;
+    let c = chain(local_with_key(), &url);
+    match c.resolve("nope").await {
+        Err(AuthError::InvalidKey) => {}
+        other => panic!("expected InvalidKey, got {other:?}"),
+    }
+}
+
+#[tokio::test]
+async fn upstream_unreachable_fails_closed_as_unavailable() {
+    // No mock — point at a dead port. A locally-unknown key must surface
+    // Unavailable (→ 503), never InvalidKey (→ 401).
+    let c = chain(local_with_key(), "http://127.0.0.1:1");
+    match c.resolve("some-mesh-key").await {
+        Err(AuthError::Unavailable { retry_after_secs }) => assert!(retry_after_secs > 0),
+        other => panic!("expected Unavailable, got {other:?}"),
+    }
+    // A local key still resolves without touching upstream.
+    assert_eq!(c.resolve("local-key").await.unwrap().account_id, "op");
+}

crates/helexa-upstream/Cargo.toml

@@ -0,0 +1,63 @@
+[package]
+name = "helexa-upstream"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[[bin]]
+name = "helexa-upstream"
+path = "src/main.rs"
+
+[lib]
+name = "helexa_upstream"
+path = "src/lib.rs"
+
+[dependencies]
+tokio = { workspace = true }
+axum = { workspace = true }
+tower-http = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+figment = { workspace = true }
+anyhow = { workspace = true }
+thiserror = { workspace = true }
+clap = { workspace = true }
+tracing = { workspace = true }
+tracing-subscriber = { workspace = true }
+chrono = { workspace = true }
+
+# PostgreSQL — the mesh authority's system of record. Runtime query API
+# (not the compile-time `query!` macros) so the crate builds in CI without a
+# live database or a committed `.sqlx` offline cache; correctness is covered
+# by the gated integration tests. (Macro adoption is a later refinement once
+# a dev DB + offline cache exist.)
+sqlx = { version = "0.8", default-features = false, features = [
+    "runtime-tokio",
+    "tls-rustls",
+    "postgres",
+    "macros",
+    "migrate",
+    "chrono",
+    "uuid",
+] }
+uuid = { version = "1", features = ["v4", "serde"] }
+sha2 = "0.10"
+subtle = "2.6"
+# Web auth (B4): argon2id password hashing, JWT sessions, CSPRNG secrets,
+# transactional email.
+argon2 = "0.5"
+jsonwebtoken = "9"
+rand = "0.8"
+lettre = { version = "0.11", default-features = false, features = [
+    "tokio1-rustls-tls",
+    "smtp-transport",
+    "builder",
+] }
+
+# cortex-core for the shared #63 OpenAiError envelope on the authz surface.
+cortex-core = { workspace = true }
+
+[dev-dependencies]
+figment = { workspace = true, features = ["test"] }
+reqwest = { workspace = true }

crates/helexa-upstream/migrations/0001_init.sql

@@ -0,0 +1,137 @@
+-- helexa-upstream initial schema (#59): accounts, keys, ledger, top-up
+-- codes, served-usage. The mesh-level authority's system of record.
+--
+-- Token amounts are BIGINT (i64) throughout; the cortex EntitlementProvider
+-- carries u64 but mesh allocations sit comfortably inside i64 and Postgres
+-- has no unsigned type.
+
+CREATE EXTENSION IF NOT EXISTS citext;
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+
+-- ── Users (web auth: email + password) ──────────────────────────────
+CREATE TABLE users (
+    id                       UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email                    CITEXT NOT NULL UNIQUE,
+    password_hash            TEXT NOT NULL,                 -- argon2id PHC string
+    email_verified           BOOLEAN NOT NULL DEFAULT FALSE,
+    -- Browser fingerprint captured at registration (#abuse). Best-effort,
+    -- client-supplied; the primary signal for silent multi-account
+    -- detection. NULL when the client could not produce one.
+    registration_fingerprint TEXT,
+    created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX users_registration_fingerprint_idx
+    ON users (registration_fingerprint)
+    WHERE registration_fingerprint IS NOT NULL;
+
+-- Single-use email tokens for verification and password reset. Only the
+-- sha256 of the emailed secret is stored.
+CREATE TABLE email_tokens (
+    token_hash BYTEA PRIMARY KEY,
+    user_id    UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    kind       TEXT NOT NULL CHECK (kind IN ('verify', 'reset')),
+    expires_at TIMESTAMPTZ NOT NULL,
+    consumed_at TIMESTAMPTZ
+);
+CREATE INDEX email_tokens_user_idx ON email_tokens (user_id);
+
+-- ── Accounts (the billable allocation ledger) ───────────────────────
+CREATE TABLE accounts (
+    id                 UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    owner_user_id      UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    allocation_total   BIGINT NOT NULL DEFAULT 0,
+    allocation_spent   BIGINT NOT NULL DEFAULT 0,
+    allocation_reserved BIGINT NOT NULL DEFAULT 0,
+    -- 'deactivated' is the SILENT abuse flag: keys stop authorizing but no
+    -- surface ever tells the user why (see resolve → 401).
+    status             TEXT NOT NULL DEFAULT 'active'
+                       CHECK (status IN ('active', 'deactivated')),
+    -- This account shares a registration fingerprint with >= 1 other.
+    fingerprint_flagged BOOLEAN NOT NULL DEFAULT FALSE,
+    created_at         TIMESTAMPTZ NOT NULL DEFAULT now(),
+    -- The no-overshoot backstop to the atomic reserve UPDATE.
+    CONSTRAINT accounts_no_overshoot
+        CHECK (allocation_spent + allocation_reserved <= allocation_total),
+    CONSTRAINT accounts_nonneg
+        CHECK (allocation_spent >= 0 AND allocation_reserved >= 0)
+);
+CREATE INDEX accounts_owner_idx ON accounts (owner_user_id);
+
+-- ── API keys (Principal.key_id = api_keys.id) ───────────────────────
+CREATE TABLE api_keys (
+    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    account_id  UUID NOT NULL REFERENCES accounts(id) ON DELETE CASCADE,
+    key_hash    BYTEA NOT NULL,                 -- sha256(raw key)
+    key_prefix  TEXT NOT NULL,                  -- non-secret display prefix
+    label       TEXT NOT NULL DEFAULT '',
+    status      TEXT NOT NULL DEFAULT 'active'
+                CHECK (status IN ('active', 'archived')),
+    -- Per-key sub-cap: 'hardcap' = absolute tokens; 'percent' = % of the
+    -- account's allocation_total (resolved to an absolute at reserve time).
+    limit_kind  TEXT NOT NULL DEFAULT 'percent'
+                CHECK (limit_kind IN ('percent', 'hardcap')),
+    limit_value BIGINT NOT NULL DEFAULT 100,
+    -- serde of cortex_core::entitlements::CapWindow (Balance | Rolling).
+    cap_window  JSONB NOT NULL DEFAULT '{"kind":"balance"}'::jsonb,
+    -- Per-key running ledger (mirrors the account ledger; Balance semantics
+    -- in this migration — rolling-window reset lands with the authz API).
+    key_spent    BIGINT NOT NULL DEFAULT 0,
+    key_reserved BIGINT NOT NULL DEFAULT 0,
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+    CONSTRAINT api_keys_key_nonneg
+        CHECK (key_spent >= 0 AND key_reserved >= 0)
+);
+-- A raw key resolves only while active; the hash is unique among active keys.
+CREATE UNIQUE INDEX api_keys_active_hash_idx
+    ON api_keys (key_hash) WHERE status = 'active';
+CREATE INDEX api_keys_account_idx ON api_keys (account_id);
+
+-- ── Reservations (reserve → settle/release) ─────────────────────────
+-- id is BIGSERIAL so it maps to the cortex Reservation.id (u64) verbatim,
+-- with the Postgres sequence as the sole global authority.
+CREATE TABLE reservations (
+    id          BIGSERIAL PRIMARY KEY,
+    account_id  UUID NOT NULL REFERENCES accounts(id) ON DELETE CASCADE,
+    key_id      UUID NOT NULL REFERENCES api_keys(id) ON DELETE CASCADE,
+    reserved    BIGINT NOT NULL,
+    actual      BIGINT,
+    state       TEXT NOT NULL DEFAULT 'open'
+                CHECK (state IN ('open', 'settled', 'released')),
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+    settled_at  TIMESTAMPTZ
+);
+-- The sweeper scans open reservations by age.
+CREATE INDEX reservations_open_idx
+    ON reservations (created_at) WHERE state = 'open';
+
+-- ── Top-up codes (hybrid allocation) ────────────────────────────────
+CREATE TABLE top_up_codes (
+    code_hash   BYTEA PRIMARY KEY,             -- sha256(raw code)
+    value       BIGINT NOT NULL,              -- tokens this code grants
+    denomination TEXT,                         -- human label (e.g. "small")
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+    redeemed_by UUID REFERENCES accounts(id) ON DELETE SET NULL,
+    redeemed_at TIMESTAMPTZ
+);
+
+-- ── Served-usage ledger (#58 reconciliation) ────────────────────────
+-- Absolute per-(operator, account, key, period) served tokens, upserted by
+-- each cortex; reconciliation rolls these up for operator compensation.
+CREATE TABLE served_usage (
+    operator_id   TEXT NOT NULL,
+    account_id    UUID NOT NULL,
+    key_id        UUID NOT NULL,
+    period        DATE NOT NULL,
+    served_tokens BIGINT NOT NULL DEFAULT 0,
+    reconciled_at TIMESTAMPTZ,
+    PRIMARY KEY (operator_id, account_id, key_id, period)
+);
+
+-- ── Web sessions (DB-backed; alt/complement to stateless JWT) ───────
+CREATE TABLE sessions (
+    token_hash BYTEA PRIMARY KEY,             -- sha256(session token)
+    user_id    UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    expires_at TIMESTAMPTZ NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX sessions_user_idx ON sessions (user_id);

crates/helexa-upstream/src/authz.rs

@@ -0,0 +1,340 @@
+//! `/authz/v1` — the machine surface cortex's `UpstreamEntitlementProvider`
+//! (#57) consumes. It mirrors the `cortex_core::entitlements::EntitlementProvider`
+//! trait 1:1 (resolve / reserve / settle / release / snapshot) over the B1
+//! ledger.
+//!
+//! Contract notes for the cortex client:
+//! - A **non-2xx** response means the authority could not give an
+//!   authoritative answer (bad caller auth, malformed request, server
+//!   error) → the client should **fail closed**.
+//! - `reserve` returns **200** whether granted or budget-refused: the body
+//!   carries either `reservation_id` or a `rejected` discriminant. A budget
+//!   refusal is an authoritative answer, not a transport failure.
+//! - Rejections that are genuinely auth failures use the #63 `OpenAiError`
+//!   envelope so they can be surfaced verbatim.
+
+use crate::crypto::sha256;
+use crate::error::envelope_response;
+use crate::ledger::{self, LedgerError};
+use crate::state::AppState;
+use axum::extract::{Request, State};
+use axum::http::{StatusCode, header};
+use axum::middleware::Next;
+use axum::response::{IntoResponse, Response};
+use axum::routing::post;
+use axum::{Extension, Json, Router};
+use cortex_core::error_envelope::OpenAiError;
+use serde::{Deserialize, Serialize};
+use subtle::ConstantTimeEq;
+use uuid::Uuid;
+
+/// The operator a validated client bearer identifies (served-usage
+/// attribution, #58). Inserted into request extensions by [`client_auth`].
+#[derive(Debug, Clone)]
+pub struct OperatorId(pub String);
+
+/// Build the `/authz/v1` router with the client-auth layer applied.
+pub fn router(state: &AppState) -> Router<AppState> {
+    Router::new()
+        .route("/authz/v1/resolve", post(resolve))
+        .route("/authz/v1/reserve", post(reserve))
+        .route("/authz/v1/settle", post(settle))
+        .route("/authz/v1/release", post(release))
+        .route("/authz/v1/snapshot", post(snapshot))
+        .route("/authz/v1/served-usage", post(served_usage))
+        .layer(axum::middleware::from_fn_with_state(
+            state.clone(),
+            client_auth,
+        ))
+}
+
+// ── client auth (shared bearer → operator_id) ───────────────────────
+
+/// Validate the caller's `Authorization: Bearer` against the configured
+/// client tokens (constant-time) and stamp the `operator_id`. When no tokens
+/// are configured the surface is open (dev) and a synthetic operator is
+/// used.
+async fn client_auth(State(state): State<AppState>, mut req: Request, next: Next) -> Response {
+    let tokens = &state.config.client_auth.tokens;
+    if tokens.is_empty() {
+        req.extensions_mut().insert(OperatorId("dev".into()));
+        return next.run(req).await;
+    }
+    let presented = req
+        .headers()
+        .get(header::AUTHORIZATION)
+        .and_then(|v| v.to_str().ok())
+        .and_then(|v| v.strip_prefix("Bearer "))
+        .map(str::trim)
+        .unwrap_or("");
+    let matched = tokens
+        .iter()
+        .find(|t| t.token.as_bytes().ct_eq(presented.as_bytes()).into());
+    match matched {
+        Some(t) => {
+            req.extensions_mut()
+                .insert(OperatorId(t.operator_id.clone()));
+            next.run(req).await
+        }
+        None => envelope_response(OpenAiError::invalid_api_key(
+            "missing or invalid client credentials",
+        )),
+    }
+}
+
+// ── DTOs ────────────────────────────────────────────────────────────
+
+#[derive(Deserialize)]
+struct ResolveReq {
+    api_key: String,
+}
+
+#[derive(Serialize)]
+struct PrincipalDto {
+    account_id: String,
+    key_id: String,
+}
+
+#[derive(Serialize)]
+struct SnapshotDto {
+    hard_cap: Option<i64>,
+    spent: i64,
+    reserved: i64,
+}
+
+#[derive(Serialize)]
+struct ResolveResp {
+    principal: PrincipalDto,
+    snapshot: SnapshotDto,
+}
+
+#[derive(Deserialize)]
+struct ReserveReq {
+    account_id: String,
+    key_id: String,
+    max_tokens: i64,
+}
+
+#[derive(Serialize, Default)]
+struct ReserveResp {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    reservation_id: Option<i64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    rejected: Option<Rejection>,
+}
+
+#[derive(Serialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+enum Rejection {
+    InsufficientQuota {
+        requested: i64,
+        available: i64,
+    },
+    // Part of the frozen wire contract so the cortex client (#57) can map it
+    // without a later breaking change. Not yet constructed: the B1 ledger
+    // implements Balance caps only; rolling-window key sub-caps (which yield
+    // this) land in a follow-up.
+    #[allow(dead_code)]
+    RateLimited {
+        requested: i64,
+        available: i64,
+        retry_after_secs: u64,
+    },
+}
+
+#[derive(Deserialize)]
+struct SettleReq {
+    reservation_id: i64,
+    actual_tokens: i64,
+}
+
+#[derive(Deserialize)]
+struct ReservationRef {
+    reservation_id: i64,
+}
+
+#[derive(Deserialize)]
+struct SnapshotReq {
+    account_id: String,
+    key_id: String,
+}
+
+// ── handlers ────────────────────────────────────────────────────────
+
+/// `POST /authz/v1/resolve` — bearer key → principal + snapshot, or
+/// `401 invalid_api_key` (also for a deactivated account: no clue).
+async fn resolve(State(state): State<AppState>, Json(req): Json<ResolveReq>) -> Response {
+    match ledger::resolve_key(&state.pool, &sha256(&req.api_key)).await {
+        Ok(Some(p)) => Json(ResolveResp {
+            principal: PrincipalDto {
+                account_id: p.account_id.to_string(),
+                key_id: p.key_id.to_string(),
+            },
+            snapshot: SnapshotDto {
+                hard_cap: Some(p.hard_cap),
+                spent: p.key_spent,
+                reserved: p.key_reserved,
+            },
+        })
+        .into_response(),
+        Ok(None) => envelope_response(OpenAiError::invalid_api_key("invalid or unknown API key")),
+        Err(e) => {
+            tracing::error!(error = %e, "resolve query failed");
+            envelope_response(OpenAiError::service_unavailable("authority error", Some(5)))
+        }
+    }
+}
+
+/// `POST /authz/v1/reserve` — 200 with `reservation_id` (granted) or
+/// `rejected` (budget). Non-2xx only for bad input / server error.
+async fn reserve(State(state): State<AppState>, Json(req): Json<ReserveReq>) -> Response {
+    let (Ok(account_id), Ok(key_id)) = (
+        Uuid::parse_str(&req.account_id),
+        Uuid::parse_str(&req.key_id),
+    ) else {
+        return bad_request("account_id and key_id must be UUIDs");
+    };
+    match ledger::reserve(&state.pool, account_id, key_id, req.max_tokens).await {
+        Ok(reservation_id) => Json(ReserveResp {
+            reservation_id: Some(reservation_id),
+            rejected: None,
+        })
+        .into_response(),
+        Err(LedgerError::InsufficientQuota {
+            requested,
+            available,
+        }) => Json(ReserveResp {
+            reservation_id: None,
+            rejected: Some(Rejection::InsufficientQuota {
+                requested,
+                available,
+            }),
+        })
+        .into_response(),
+        Err(LedgerError::AccountNotFound | LedgerError::KeyNotFound) => {
+            // Resolve succeeded earlier; the principal vanished (archived /
+            // deactivated). Treat as no budget — fail closed at the client.
+            Json(ReserveResp {
+                reservation_id: None,
+                rejected: Some(Rejection::InsufficientQuota {
+                    requested: req.max_tokens,
+                    available: 0,
+                }),
+            })
+            .into_response()
+        }
+        Err(LedgerError::Db(e)) => {
+            tracing::error!(error = %e, "reserve failed");
+            envelope_response(OpenAiError::service_unavailable("authority error", Some(5)))
+        }
+    }
+}
+
+/// `POST /authz/v1/settle` — idempotent; `204`.
+async fn settle(State(state): State<AppState>, Json(req): Json<SettleReq>) -> Response {
+    match ledger::settle(&state.pool, req.reservation_id, req.actual_tokens).await {
+        Ok(()) => StatusCode::NO_CONTENT.into_response(),
+        Err(e) => {
+            tracing::error!(error = %e, "settle failed");
+            envelope_response(OpenAiError::service_unavailable("authority error", Some(5)))
+        }
+    }
+}
+
+/// `POST /authz/v1/release` — idempotent; `204`.
+async fn release(State(state): State<AppState>, Json(req): Json<ReservationRef>) -> Response {
+    match ledger::release(&state.pool, req.reservation_id).await {
+        Ok(()) => StatusCode::NO_CONTENT.into_response(),
+        Err(e) => {
+            tracing::error!(error = %e, "release failed");
+            envelope_response(OpenAiError::service_unavailable("authority error", Some(5)))
+        }
+    }
+}
+
+/// `POST /authz/v1/snapshot` — `{hard_cap, spent, reserved}` or `404`.
+async fn snapshot(State(state): State<AppState>, Json(req): Json<SnapshotReq>) -> Response {
+    let (Ok(account_id), Ok(key_id)) = (
+        Uuid::parse_str(&req.account_id),
+        Uuid::parse_str(&req.key_id),
+    ) else {
+        return bad_request("account_id and key_id must be UUIDs");
+    };
+    match ledger::snapshot(&state.pool, account_id, key_id).await {
+        Ok(Some((hard_cap, spent, reserved))) => Json(SnapshotDto {
+            hard_cap: Some(hard_cap),
+            spent,
+            reserved,
+        })
+        .into_response(),
+        Ok(None) => StatusCode::NOT_FOUND.into_response(),
+        Err(e) => {
+            tracing::error!(error = %e, "snapshot failed");
+            envelope_response(OpenAiError::service_unavailable("authority error", Some(5)))
+        }
+    }
+}
+
+// ── served-usage report (#58) ───────────────────────────────────────
+
+#[derive(Deserialize)]
+struct ServedUsageReport {
+    rows: Vec<ServedUsageRow>,
+}
+
+#[derive(Deserialize)]
+struct ServedUsageRow {
+    account_id: String,
+    key_id: String,
+    period: String, // YYYY-MM-DD
+    served_tokens: i64,
+}
+
+/// `POST /authz/v1/served-usage` — a cortex reports the absolute served-token
+/// counters it has accrued for the current period. Upsert is monotonic
+/// (`GREATEST`) so re-sends and races are idempotent and never regress.
+/// `operator_id` comes from the validated client bearer (request extension).
+async fn served_usage(
+    State(state): State<AppState>,
+    Extension(operator): Extension<OperatorId>,
+    Json(req): Json<ServedUsageReport>,
+) -> Response {
+    for row in &req.rows {
+        let (Ok(account_id), Ok(key_id)) = (
+            Uuid::parse_str(&row.account_id),
+            Uuid::parse_str(&row.key_id),
+        ) else {
+            continue; // skip malformed ids rather than fail the whole batch
+        };
+        let Ok(period) = chrono::NaiveDate::parse_from_str(&row.period, "%Y-%m-%d") else {
+            continue;
+        };
+        let res = sqlx::query(
+            "INSERT INTO served_usage (operator_id, account_id, key_id, period, served_tokens) \
+             VALUES ($1, $2, $3, $4, $5) \
+             ON CONFLICT (operator_id, account_id, key_id, period) \
+             DO UPDATE SET served_tokens = GREATEST(served_usage.served_tokens, EXCLUDED.served_tokens)",
+        )
+        .bind(&operator.0)
+        .bind(account_id)
+        .bind(key_id)
+        .bind(period)
+        .bind(row.served_tokens.max(0))
+        .execute(&state.pool)
+        .await;
+        if let Err(e) = res {
+            tracing::error!(error = %e, "served-usage upsert failed");
+            return envelope_response(OpenAiError::service_unavailable("authority error", Some(5)));
+        }
+    }
+    StatusCode::NO_CONTENT.into_response()
+}
+
+fn bad_request(msg: &str) -> Response {
+    envelope_response(OpenAiError::new(
+        400,
+        "invalid_request_error",
+        "invalid_request",
+        msg,
+    ))
+}

crates/helexa-upstream/src/config.rs

@@ -0,0 +1,261 @@
+//! helexa-upstream configuration: loaded from `helexa-upstream.toml` with
+//! figment, `UPSTREAM_`-prefixed env overrides (mirrors the cortex/router
+//! convention, e.g. `UPSTREAM_SERVER__LISTEN`, `UPSTREAM_DB__URL`).
+
+use figment::{
+    Figment,
+    providers::{Env, Format, Toml},
+};
+use serde::{Deserialize, Serialize};
+use std::path::Path;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct UpstreamConfig {
+    #[serde(default)]
+    pub server: ServerSettings,
+    pub db: DbSettings,
+    #[serde(default)]
+    pub grant: GrantSettings,
+    #[serde(default)]
+    pub abuse: AbuseSettings,
+    #[serde(default)]
+    pub client_auth: ClientAuthSettings,
+    #[serde(default)]
+    pub authz: AuthzSettings,
+    #[serde(default)]
+    pub auth: AuthSettings,
+    #[serde(default)]
+    pub email: EmailSettings,
+}
+
+/// `[auth]` — web-session signing + token lifetimes (B4). Web sessions are
+/// JWTs, distinct from inference API keys.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AuthSettings {
+    /// HMAC secret for signing session JWTs. MUST be overridden in prod
+    /// (env `UPSTREAM_AUTH__JWT_SECRET`); the default is dev-only.
+    #[serde(default = "default_jwt_secret")]
+    pub jwt_secret: String,
+    /// Session token lifetime (seconds).
+    #[serde(default = "default_session_ttl")]
+    pub session_ttl_secs: u64,
+    /// Email verification / password-reset token lifetime (seconds).
+    #[serde(default = "default_email_token_ttl")]
+    pub email_token_ttl_secs: u64,
+    /// Public base URL of the frontend, used to build verify/reset links.
+    #[serde(default = "default_app_base_url")]
+    pub app_base_url: String,
+}
+
+impl Default for AuthSettings {
+    fn default() -> Self {
+        Self {
+            jwt_secret: default_jwt_secret(),
+            session_ttl_secs: default_session_ttl(),
+            email_token_ttl_secs: default_email_token_ttl(),
+            app_base_url: default_app_base_url(),
+        }
+    }
+}
+
+/// `[email]` — transactional email transport for verify/reset.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct EmailSettings {
+    /// `"log"` (dev — logs the link) or `"smtp"`.
+    #[serde(default = "default_email_provider")]
+    pub provider: String,
+    /// SMTP relay URL (e.g. "smtp://user:pass@host:587") when provider=smtp.
+    #[serde(default)]
+    pub smtp_url: Option<String>,
+    /// `From:` address.
+    #[serde(default = "default_from_addr")]
+    pub from_addr: String,
+}
+
+impl Default for EmailSettings {
+    fn default() -> Self {
+        Self {
+            provider: default_email_provider(),
+            smtp_url: None,
+            from_addr: default_from_addr(),
+        }
+    }
+}
+
+/// `[client_auth]` — credentials operators' cortexes present to `/authz/v1`.
+/// Each token maps to an `operator_id` (served-usage attribution, #58). This
+/// transport credential is distinct from end-user API keys (which ride in
+/// the `resolve` body). v2 adds mTLS.
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub struct ClientAuthSettings {
+    /// When empty the authz surface is **open** (dev only; logged at warn).
+    #[serde(default)]
+    pub tokens: Vec<ClientToken>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ClientToken {
+    /// Shared bearer a cortex presents.
+    pub token: String,
+    /// Operator this token identifies.
+    pub operator_id: String,
+}
+
+/// `[authz]` — reservation lifecycle knobs.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AuthzSettings {
+    /// Open reservations older than this are swept (released), self-healing
+    /// a reservation whose settle/release from cortex was lost.
+    #[serde(default = "default_reservation_ttl")]
+    pub reservation_ttl_secs: u64,
+    /// How often the sweeper runs.
+    #[serde(default = "default_sweep_interval")]
+    pub sweep_interval_secs: u64,
+}
+
+impl Default for AuthzSettings {
+    fn default() -> Self {
+        Self {
+            reservation_ttl_secs: default_reservation_ttl(),
+            sweep_interval_secs: default_sweep_interval(),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ServerSettings {
+    /// Address to listen on (e.g. "0.0.0.0:8090"). Plaintext — edge nginx
+    /// terminates TLS, consistent with the rest of the stack.
+    #[serde(default = "default_listen")]
+    pub listen: String,
+}
+
+impl Default for ServerSettings {
+    fn default() -> Self {
+        Self {
+            listen: default_listen(),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DbSettings {
+    /// PostgreSQL connection URL (e.g. "postgres://user:pass@host/helexa").
+    pub url: String,
+    /// Max pool connections.
+    #[serde(default = "default_max_connections")]
+    pub max_connections: u32,
+}
+
+/// `[grant]` — the flat free token grant every email-verified account
+/// receives (the floor of the hybrid allocation model; top-up codes extend
+/// it).
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GrantSettings {
+    #[serde(default = "default_free_grant")]
+    pub free_token_grant: i64,
+}
+
+impl Default for GrantSettings {
+    fn default() -> Self {
+        Self {
+            free_token_grant: default_free_grant(),
+        }
+    }
+}
+
+/// `[abuse]` — silent multi-account abuse detection. When at least
+/// `fingerprint_account_threshold` accounts share one registration
+/// fingerprint, all of them are silently deactivated (no notice to the
+/// user; deactivation only surfaces as ordinary inference rejections).
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AbuseSettings {
+    #[serde(default = "default_fingerprint_threshold")]
+    pub fingerprint_account_threshold: i64,
+}
+
+impl Default for AbuseSettings {
+    fn default() -> Self {
+        Self {
+            fingerprint_account_threshold: default_fingerprint_threshold(),
+        }
+    }
+}
+
+fn default_listen() -> String {
+    "0.0.0.0:8090".into()
+}
+fn default_max_connections() -> u32 {
+    16
+}
+fn default_free_grant() -> i64 {
+    1_000_000
+}
+fn default_fingerprint_threshold() -> i64 {
+    5
+}
+fn default_reservation_ttl() -> u64 {
+    120
+}
+fn default_sweep_interval() -> u64 {
+    60
+}
+fn default_jwt_secret() -> String {
+    "dev-insecure-change-me".into()
+}
+fn default_session_ttl() -> u64 {
+    7 * 24 * 3600
+}
+fn default_email_token_ttl() -> u64 {
+    24 * 3600
+}
+fn default_app_base_url() -> String {
+    "http://localhost:5173".into()
+}
+fn default_email_provider() -> String {
+    "log".into()
+}
+fn default_from_addr() -> String {
+    "helexa <no-reply@helexa.ai>".into()
+}
+
+impl UpstreamConfig {
+    /// Load from a TOML file with `UPSTREAM_`-prefixed env overrides
+    /// (`__` nesting separator).
+    pub fn load(path: impl AsRef<Path>) -> Result<Self, Box<figment::Error>> {
+        Figment::new()
+            .merge(Toml::file(path))
+            .merge(Env::prefixed("UPSTREAM_").split("__"))
+            .extract()
+            .map_err(Box::new)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    #[allow(clippy::result_large_err)]
+    fn loads_toml_with_env_override_and_defaults() {
+        figment::Jail::expect_with(|jail| {
+            jail.create_file(
+                "helexa-upstream.toml",
+                r#"
+[db]
+url = "postgres://localhost/helexa"
+"#,
+            )?;
+            jail.set_env("UPSTREAM_SERVER__LISTEN", "127.0.0.1:9099");
+
+            let cfg = UpstreamConfig::load("helexa-upstream.toml").expect("load");
+            assert_eq!(cfg.server.listen, "127.0.0.1:9099");
+            assert_eq!(cfg.db.url, "postgres://localhost/helexa");
+            // Defaults applied when sections omitted.
+            assert_eq!(cfg.grant.free_token_grant, 1_000_000);
+            assert_eq!(cfg.abuse.fingerprint_account_threshold, 5);
+            assert_eq!(cfg.db.max_connections, 16);
+            Ok(())
+        });
+    }
+}

crates/helexa-upstream/src/crypto.rs

@@ -0,0 +1,113 @@
+//! Hashing + secret-generation helpers.
+//!
+//! - **Passwords** (low-entropy) → argon2id PHC strings.
+//! - **API keys / top-up codes / email + session tokens** (high-entropy
+//!   secrets minted here) → stored only as their sha256; sha256 is the fast,
+//!   sufficient choice for high-entropy material.
+
+use argon2::Argon2;
+use argon2::password_hash::rand_core::OsRng as ArgonOsRng;
+use argon2::password_hash::{PasswordHash, PasswordHasher, PasswordVerifier, SaltString};
+use rand::RngCore;
+use sha2::{Digest, Sha256};
+
+/// sha256 of `input`, as raw bytes (matches the `BYTEA` columns).
+pub fn sha256(input: &str) -> Vec<u8> {
+    let mut h = Sha256::new();
+    h.update(input.as_bytes());
+    h.finalize().to_vec()
+}
+
+/// Hash a password with argon2id, returning a PHC string for storage.
+pub fn hash_password(password: &str) -> Result<String, argon2::password_hash::Error> {
+    let salt = SaltString::generate(&mut ArgonOsRng);
+    Ok(Argon2::default()
+        .hash_password(password.as_bytes(), &salt)?
+        .to_string())
+}
+
+/// Verify a password against a stored PHC hash. `false` on any mismatch or
+/// malformed hash (never panics).
+pub fn verify_password(password: &str, phc: &str) -> bool {
+    match PasswordHash::new(phc) {
+        Ok(parsed) => Argon2::default()
+            .verify_password(password.as_bytes(), &parsed)
+            .is_ok(),
+        Err(_) => false,
+    }
+}
+
+/// A fresh URL-safe high-entropy secret (256 bits) for email/session/reset
+/// tokens. The caller stores only `sha256` of this and emails/returns the
+/// raw value.
+pub fn random_token() -> String {
+    let mut bytes = [0u8; 32];
+    rand::rngs::OsRng.fill_bytes(&mut bytes);
+    base62(&bytes)
+}
+
+/// Mint a new API key: `(raw, prefix)`. `raw` is shown to the user once;
+/// only `sha256(raw)` is stored. The prefix is a non-secret display tag.
+pub fn generate_api_key() -> (String, String) {
+    let mut bytes = [0u8; 32];
+    rand::rngs::OsRng.fill_bytes(&mut bytes);
+    let raw = format!("sk-helexa-{}", base62(&bytes));
+    // Non-secret prefix for the dashboard list (scheme + first few chars).
+    let prefix: String = raw.chars().take(14).collect();
+    (raw, prefix)
+}
+
+/// base62 encode (0-9A-Za-z) — URL/clipboard friendly, no padding.
+fn base62(bytes: &[u8]) -> String {
+    const ALPHABET: &[u8] = b"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+    // Treat the bytes as a big-endian integer and base62 it. 32 bytes → ~43
+    // chars. Simple repeated-division over a big-uint built from the bytes.
+    let mut digits: Vec<u8> = vec![0];
+    for &byte in bytes {
+        let mut carry = byte as u32;
+        for d in digits.iter_mut() {
+            let v = (*d as u32) * 256 + carry;
+            *d = (v % 62) as u8;
+            carry = v / 62;
+        }
+        while carry > 0 {
+            digits.push((carry % 62) as u8);
+            carry /= 62;
+        }
+    }
+    digits
+        .iter()
+        .rev()
+        .map(|&d| ALPHABET[d as usize] as char)
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn password_round_trips_and_rejects_wrong() {
+        let phc = hash_password("correct horse").unwrap();
+        assert!(verify_password("correct horse", &phc));
+        assert!(!verify_password("wrong", &phc));
+        assert!(!verify_password("correct horse", "not-a-phc-string"));
+    }
+
+    #[test]
+    fn api_key_has_scheme_prefix_and_unique_body() {
+        let (raw, prefix) = generate_api_key();
+        assert!(raw.starts_with("sk-helexa-"));
+        assert!(prefix.starts_with("sk-helexa-"));
+        let (raw2, _) = generate_api_key();
+        assert_ne!(raw, raw2, "keys are unique");
+    }
+
+    #[test]
+    fn random_tokens_are_unique_and_nonempty() {
+        let a = random_token();
+        let b = random_token();
+        assert!(!a.is_empty());
+        assert_ne!(a, b);
+    }
+}

crates/helexa-upstream/src/db.rs

@@ -0,0 +1,20 @@
+//! PostgreSQL pool + embedded migrations.
+
+use anyhow::{Context, Result};
+use sqlx::postgres::{PgPool, PgPoolOptions};
+
+/// Connect to Postgres and run embedded migrations (`./migrations`).
+pub async fn connect_and_migrate(url: &str, max_connections: u32) -> Result<PgPool> {
+    let pool = PgPoolOptions::new()
+        .max_connections(max_connections)
+        .connect(url)
+        .await
+        .with_context(|| "connecting to PostgreSQL")?;
+
+    sqlx::migrate!("./migrations")
+        .run(&pool)
+        .await
+        .with_context(|| "running migrations")?;
+
+    Ok(pool)
+}

crates/helexa-upstream/src/email.rs

@@ -0,0 +1,64 @@
+//! Transactional email for verification + password-reset links.
+//!
+//! Two transports: `Log` (dev — writes the link to the log so flows are
+//! testable without a relay) and `Smtp` (lettre over rustls). Built from
+//! `[email]` config.
+
+use crate::config::EmailSettings;
+use anyhow::{Context, Result};
+use lettre::message::Mailbox;
+use lettre::{AsyncSmtpTransport, AsyncTransport, Message, Tokio1Executor};
+
+#[derive(Clone)]
+pub enum EmailSender {
+    /// Dev: log the message instead of sending.
+    Log { from: String },
+    Smtp {
+        from: String,
+        transport: AsyncSmtpTransport<Tokio1Executor>,
+    },
+}
+
+impl EmailSender {
+    pub fn from_config(cfg: &EmailSettings) -> Result<Self> {
+        match cfg.provider.as_str() {
+            "smtp" => {
+                let url = cfg
+                    .smtp_url
+                    .as_deref()
+                    .context("[email].smtp_url required when provider = \"smtp\"")?;
+                let transport = AsyncSmtpTransport::<Tokio1Executor>::from_url(url)
+                    .context("parsing [email].smtp_url")?
+                    .build();
+                Ok(EmailSender::Smtp {
+                    from: cfg.from_addr.clone(),
+                    transport,
+                })
+            }
+            _ => Ok(EmailSender::Log {
+                from: cfg.from_addr.clone(),
+            }),
+        }
+    }
+
+    /// Send a plaintext email. Errors are returned but the caller treats
+    /// send failures as non-fatal to the request (the user can re-request).
+    pub async fn send(&self, to: &str, subject: &str, body: &str) -> Result<()> {
+        match self {
+            EmailSender::Log { from } => {
+                tracing::info!(%from, %to, %subject, body, "EMAIL (log transport)");
+                Ok(())
+            }
+            EmailSender::Smtp { from, transport } => {
+                let msg = Message::builder()
+                    .from(from.parse::<Mailbox>().context("parsing from_addr")?)
+                    .to(to.parse::<Mailbox>().context("parsing recipient")?)
+                    .subject(subject)
+                    .body(body.to_string())
+                    .context("building message")?;
+                transport.send(msg).await.context("sending email")?;
+                Ok(())
+            }
+        }
+    }
+}

crates/helexa-upstream/src/error.rs

@@ -0,0 +1,21 @@
+//! Adapter from the shared, axum-agnostic
+//! [`cortex_core::error_envelope::OpenAiError`] (#60/#63) to an axum
+//! response, with `Retry-After`. The `/authz/v1` surface speaks the #63
+//! envelope so cortex (an OpenAI-compatible proxy) can forward rejections
+//! verbatim. (The future `/web/v1` surface uses a plain JSON error shape.)
+
+use axum::http::{HeaderValue, StatusCode, header};
+use axum::response::{IntoResponse, Json, Response};
+use cortex_core::error_envelope::OpenAiError;
+
+pub fn envelope_response(err: OpenAiError) -> Response {
+    let status = StatusCode::from_u16(err.status).unwrap_or(StatusCode::INTERNAL_SERVER_ERROR);
+    let retry_after = err.retry_after_secs;
+    let mut response = (status, Json(err.body())).into_response();
+    if let Some(secs) = retry_after
+        && let Ok(value) = HeaderValue::from_str(&secs.to_string())
+    {
+        response.headers_mut().insert(header::RETRY_AFTER, value);
+    }
+    response
+}

crates/helexa-upstream/src/handlers.rs

@@ -0,0 +1,21 @@
+//! HTTP handlers. B1 ships `/health`; the authz (`/authz/v1`) and web
+//! (`/web/v1`) surfaces land in later phases.
+
+use crate::state::AppState;
+use axum::{Json, Router, extract::State, routing::get};
+use serde_json::{Value, json};
+
+pub fn routes() -> Router<AppState> {
+    Router::new()
+        .route("/health", get(health))
+        .route("/", get(health))
+}
+
+/// `GET /health` — liveness + a database round-trip (`SELECT 1`).
+async fn health(State(state): State<AppState>) -> Json<Value> {
+    let db_ok = sqlx::query("SELECT 1").execute(&state.pool).await.is_ok();
+    Json(json!({
+        "status": if db_ok { "ok" } else { "degraded" },
+        "db": if db_ok { "ok" } else { "unreachable" },
+    }))
+}

crates/helexa-upstream/src/ledger.rs

@@ -0,0 +1,338 @@
+//! The allocation ledger: reserve → settle/release with the no-overshoot
+//! guarantee enforced by a row-locked transaction.
+//!
+//! Each reserve takes `SELECT … FOR UPDATE` on the account (and key) row, so
+//! concurrent reserves from many cortexes serialize and `spent + reserved`
+//! can never exceed the effective cap. The `accounts_no_overshoot` CHECK is
+//! the DB-level backstop. Settle/release are idempotent (they only act on a
+//! reservation still in `open`).
+//!
+//! Per-key effective cap = `min(resolved key cap, remaining account
+//! allocation)`. The key cap is resolved from its `limit_kind`:
+//! `hardcap` → the value verbatim; `percent` → that % of the account's
+//! `allocation_total`.
+//!
+//! Cap-window semantics: this module implements **Balance** (non-resetting)
+//! caps. Rolling-window key sub-caps (and the `RateLimited` rejection that
+//! rides them) land with the authz API (B2); today an over-cap is always
+//! `InsufficientQuota`.
+
+use sqlx::postgres::PgPool;
+use uuid::Uuid;
+
+/// A bearer key resolved to its principal + a budget snapshot.
+#[derive(Debug, Clone)]
+pub struct ResolvedPrincipal {
+    pub account_id: Uuid,
+    pub key_id: Uuid,
+    /// Effective per-key absolute cap (the key sub-cap; the account cap
+    /// still binds at reserve time).
+    pub hard_cap: i64,
+    pub key_spent: i64,
+    pub key_reserved: i64,
+}
+
+/// Resolve a key by its `sha256` hash to its principal, or `None` when the
+/// key is unknown/archived **or its account is deactivated** (the silent
+/// abuse flag — indistinguishable from an unknown key, by design: no clue).
+pub async fn resolve_key(
+    pool: &PgPool,
+    key_hash: &[u8],
+) -> Result<Option<ResolvedPrincipal>, sqlx::Error> {
+    let row = sqlx::query(
+        "SELECT k.id AS key_id, k.account_id, k.limit_kind, k.limit_value, \
+                k.key_spent, k.key_reserved, a.allocation_total \
+         FROM api_keys k JOIN accounts a ON a.id = k.account_id \
+         WHERE k.key_hash = $1 AND k.status = 'active' AND a.status = 'active'",
+    )
+    .bind(key_hash)
+    .fetch_optional(pool)
+    .await?;
+    Ok(row.map(|r| {
+        let total: i64 = sqlx::Row::get(&r, "allocation_total");
+        let limit_kind: String = sqlx::Row::get(&r, "limit_kind");
+        let limit_value: i64 = sqlx::Row::get(&r, "limit_value");
+        ResolvedPrincipal {
+            account_id: sqlx::Row::get(&r, "account_id"),
+            key_id: sqlx::Row::get(&r, "key_id"),
+            hard_cap: resolve_abs_cap(&limit_kind, limit_value, total),
+            key_spent: sqlx::Row::get(&r, "key_spent"),
+            key_reserved: sqlx::Row::get(&r, "key_reserved"),
+        }
+    }))
+}
+
+/// Per-key budget snapshot `(hard_cap, spent, reserved)`, or `None` if the
+/// key/account isn't an active pair.
+pub async fn snapshot(
+    pool: &PgPool,
+    account_id: Uuid,
+    key_id: Uuid,
+) -> Result<Option<(i64, i64, i64)>, sqlx::Error> {
+    let row = sqlx::query(
+        "SELECT k.limit_kind, k.limit_value, k.key_spent, k.key_reserved, a.allocation_total \
+         FROM api_keys k JOIN accounts a ON a.id = k.account_id \
+         WHERE k.id = $1 AND k.account_id = $2 AND k.status = 'active' AND a.status = 'active'",
+    )
+    .bind(key_id)
+    .bind(account_id)
+    .fetch_optional(pool)
+    .await?;
+    Ok(row.map(|r| {
+        let total: i64 = sqlx::Row::get(&r, "allocation_total");
+        let limit_kind: String = sqlx::Row::get(&r, "limit_kind");
+        let limit_value: i64 = sqlx::Row::get(&r, "limit_value");
+        let cap = resolve_abs_cap(&limit_kind, limit_value, total);
+        (
+            cap,
+            sqlx::Row::get::<i64, _>(&r, "key_spent"),
+            sqlx::Row::get::<i64, _>(&r, "key_reserved"),
+        )
+    }))
+}
+
+/// Release every `open` reservation older than `max_age_secs`, returning
+/// each one's reserved tokens to its account and key in a single statement.
+/// The lost-settle self-heal. Returns the number swept.
+pub async fn sweep_stale(pool: &PgPool, max_age_secs: i64) -> Result<u64, sqlx::Error> {
+    // Data-modifying CTEs: release stale rows, then fold their reserved sums
+    // back into accounts and api_keys. All in one atomic statement.
+    let result = sqlx::query(
+        "WITH stale AS ( \
+             UPDATE reservations SET state = 'released', settled_at = now() \
+             WHERE state = 'open' AND created_at < now() - make_interval(secs => $1) \
+             RETURNING account_id, key_id, reserved \
+         ), acct AS ( \
+             UPDATE accounts a SET allocation_reserved = allocation_reserved - s.total \
+             FROM (SELECT account_id, SUM(reserved) AS total FROM stale GROUP BY account_id) s \
+             WHERE a.id = s.account_id \
+         ) \
+         UPDATE api_keys k SET key_reserved = key_reserved - s.total \
+         FROM (SELECT key_id, SUM(reserved) AS total FROM stale GROUP BY key_id) s \
+         WHERE k.id = s.key_id",
+    )
+    .bind(max_age_secs as f64)
+    .execute(pool)
+    .await?;
+    Ok(result.rows_affected())
+}
+
+/// Resolve a key's per-key cap to an absolute token count.
+///
+/// `percent` is `floor(allocation_total * limit_value / 100)`; `hardcap` is
+/// `limit_value` verbatim. Computed in i128 to avoid overflow, floored at 0.
+pub fn resolve_abs_cap(limit_kind: &str, limit_value: i64, allocation_total: i64) -> i64 {
+    let cap = match limit_kind {
+        "percent" => (allocation_total as i128 * limit_value as i128) / 100,
+        _ => limit_value as i128, // "hardcap" (and any unknown → treat as absolute)
+    };
+    cap.clamp(0, i64::MAX as i128) as i64
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum LedgerError {
+    #[error("account not found")]
+    AccountNotFound,
+    #[error("api key not found or not active")]
+    KeyNotFound,
+    /// Account balance or a Balance-window key sub-cap is exhausted.
+    #[error("insufficient quota: requested {requested}, available {available}")]
+    InsufficientQuota { requested: i64, available: i64 },
+    #[error(transparent)]
+    Db(#[from] sqlx::Error),
+}
+
+/// Reserve `max_tokens` against `account_id`/`key_id`. Returns the
+/// reservation id (the `BIGSERIAL`, mapped to the cortex `Reservation.id`).
+pub async fn reserve(
+    pool: &PgPool,
+    account_id: Uuid,
+    key_id: Uuid,
+    max_tokens: i64,
+) -> Result<i64, LedgerError> {
+    let mut tx = pool.begin().await?;
+
+    // Lock the account row — serializes concurrent reserves on this account.
+    let acct = sqlx::query(
+        "SELECT allocation_total, allocation_spent, allocation_reserved \
+         FROM accounts WHERE id = $1 AND status = 'active' FOR UPDATE",
+    )
+    .bind(account_id)
+    .fetch_optional(&mut *tx)
+    .await?;
+    let Some(acct) = acct else {
+        return Err(LedgerError::AccountNotFound);
+    };
+    let total: i64 = sqlx::Row::get(&acct, "allocation_total");
+    let spent: i64 = sqlx::Row::get(&acct, "allocation_spent");
+    let reserved: i64 = sqlx::Row::get(&acct, "allocation_reserved");
+    let account_avail = total - spent - reserved;
+
+    // Lock the key row and resolve its absolute sub-cap.
+    let key = sqlx::query(
+        "SELECT limit_kind, limit_value, key_spent, key_reserved \
+         FROM api_keys WHERE id = $1 AND account_id = $2 AND status = 'active' FOR UPDATE",
+    )
+    .bind(key_id)
+    .bind(account_id)
+    .fetch_optional(&mut *tx)
+    .await?;
+    let Some(key) = key else {
+        return Err(LedgerError::KeyNotFound);
+    };
+    let limit_kind: String = sqlx::Row::get(&key, "limit_kind");
+    let limit_value: i64 = sqlx::Row::get(&key, "limit_value");
+    let key_spent: i64 = sqlx::Row::get(&key, "key_spent");
+    let key_reserved: i64 = sqlx::Row::get(&key, "key_reserved");
+    let key_cap = resolve_abs_cap(&limit_kind, limit_value, total);
+    let key_avail = key_cap - key_spent - key_reserved;
+
+    let available = account_avail.min(key_avail).max(0);
+    if max_tokens > available {
+        // tx rolls back on drop
+        return Err(LedgerError::InsufficientQuota {
+            requested: max_tokens,
+            available,
+        });
+    }
+
+    let id: i64 = sqlx::Row::get(
+        &sqlx::query(
+            "INSERT INTO reservations (account_id, key_id, reserved, state) \
+             VALUES ($1, $2, $3, 'open') RETURNING id",
+        )
+        .bind(account_id)
+        .bind(key_id)
+        .bind(max_tokens)
+        .fetch_one(&mut *tx)
+        .await?,
+        "id",
+    );
+    sqlx::query("UPDATE accounts SET allocation_reserved = allocation_reserved + $1 WHERE id = $2")
+        .bind(max_tokens)
+        .bind(account_id)
+        .execute(&mut *tx)
+        .await?;
+    sqlx::query("UPDATE api_keys SET key_reserved = key_reserved + $1 WHERE id = $2")
+        .bind(max_tokens)
+        .bind(key_id)
+        .execute(&mut *tx)
+        .await?;
+
+    tx.commit().await?;
+    Ok(id)
+}
+
+/// Settle a reservation with the actual tokens used (clamped to
+/// `[0, reserved]`). Idempotent: a second settle (or settle after release)
+/// is a no-op.
+pub async fn settle(
+    pool: &PgPool,
+    reservation_id: i64,
+    actual_tokens: i64,
+) -> Result<(), LedgerError> {
+    let mut tx = pool.begin().await?;
+    let row = sqlx::query(
+        "UPDATE reservations SET state = 'settled', settled_at = now(), \
+         actual = LEAST(GREATEST($2, 0), reserved) \
+         WHERE id = $1 AND state = 'open' \
+         RETURNING reserved, account_id, key_id, actual",
+    )
+    .bind(reservation_id)
+    .bind(actual_tokens)
+    .fetch_optional(&mut *tx)
+    .await?;
+    let Some(row) = row else {
+        return Ok(()); // already settled/released, or unknown → idempotent no-op
+    };
+    let reserved: i64 = sqlx::Row::get(&row, "reserved");
+    let actual: i64 = sqlx::Row::get(&row, "actual");
+    let account_id: Uuid = sqlx::Row::get(&row, "account_id");
+    let key_id: Uuid = sqlx::Row::get(&row, "key_id");
+
+    sqlx::query(
+        "UPDATE accounts SET allocation_reserved = allocation_reserved - $1, \
+         allocation_spent = allocation_spent + $2 WHERE id = $3",
+    )
+    .bind(reserved)
+    .bind(actual)
+    .bind(account_id)
+    .execute(&mut *tx)
+    .await?;
+    sqlx::query(
+        "UPDATE api_keys SET key_reserved = key_reserved - $1, key_spent = key_spent + $2 WHERE id = $3",
+    )
+    .bind(reserved)
+    .bind(actual)
+    .bind(key_id)
+    .execute(&mut *tx)
+    .await?;
+
+    tx.commit().await?;
+    Ok(())
+}
+
+/// Release a reservation, returning its full reserved amount to the
+/// allocation. Idempotent.
+pub async fn release(pool: &PgPool, reservation_id: i64) -> Result<(), LedgerError> {
+    let mut tx = pool.begin().await?;
+    let row = sqlx::query(
+        "UPDATE reservations SET state = 'released', settled_at = now() \
+         WHERE id = $1 AND state = 'open' \
+         RETURNING reserved, account_id, key_id",
+    )
+    .bind(reservation_id)
+    .fetch_optional(&mut *tx)
+    .await?;
+    let Some(row) = row else {
+        return Ok(());
+    };
+    let reserved: i64 = sqlx::Row::get(&row, "reserved");
+    let account_id: Uuid = sqlx::Row::get(&row, "account_id");
+    let key_id: Uuid = sqlx::Row::get(&row, "key_id");
+
+    sqlx::query("UPDATE accounts SET allocation_reserved = allocation_reserved - $1 WHERE id = $2")
+        .bind(reserved)
+        .bind(account_id)
+        .execute(&mut *tx)
+        .await?;
+    sqlx::query("UPDATE api_keys SET key_reserved = key_reserved - $1 WHERE id = $2")
+        .bind(reserved)
+        .bind(key_id)
+        .execute(&mut *tx)
+        .await?;
+
+    tx.commit().await?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::resolve_abs_cap;
+
+    #[test]
+    fn hardcap_is_verbatim() {
+        assert_eq!(resolve_abs_cap("hardcap", 50_000, 1_000_000), 50_000);
+    }
+
+    #[test]
+    fn percent_is_fraction_of_allocation() {
+        assert_eq!(resolve_abs_cap("percent", 25, 1_000_000), 250_000);
+        assert_eq!(resolve_abs_cap("percent", 100, 1_000_000), 1_000_000);
+        // floor
+        assert_eq!(resolve_abs_cap("percent", 33, 10), 3);
+    }
+
+    #[test]
+    fn percent_does_not_overflow_on_large_allocation() {
+        // total * value would overflow i64 if not widened to i128.
+        let cap = resolve_abs_cap("percent", 100, i64::MAX);
+        assert_eq!(cap, i64::MAX);
+    }
+
+    #[test]
+    fn negative_or_zero_clamps_to_zero() {
+        assert_eq!(resolve_abs_cap("hardcap", -5, 100), 0);
+        assert_eq!(resolve_abs_cap("percent", 0, 1_000_000), 0);
+    }
+}

crates/helexa-upstream/src/lib.rs

@@ -0,0 +1,90 @@
+//! helexa-upstream — the mesh-level account/authorization authority (#59).
+//!
+//! The clearing house above cortex: it issues accounts and API keys, holds
+//! the real token-allocation ledger, authorizes inference in real time
+//! (reserve → settle, fail-closed), and tracks served usage for operator
+//! reconciliation. cortex's `UpstreamEntitlementProvider` (#57) is a client
+//! of the `/authz/v1` surface; the helexa.ai frontend is a client of the
+//! `/web/v1` surface.
+//!
+//! Landed so far: B1 — schema + reserve→settle [`ledger`] (no-overshoot) +
+//! `/health`. B2 — the `/authz/v1` [`authz`] surface (resolve/reserve/
+//! settle/release/snapshot) with shared-bearer client auth and a
+//! stale-reservation sweeper.
+
+pub mod authz;
+pub mod config;
+pub mod crypto;
+pub mod db;
+pub mod email;
+pub mod error;
+pub mod handlers;
+pub mod ledger;
+pub mod reconcile;
+pub mod state;
+pub mod topup;
+pub mod web;
+
+use anyhow::Result;
+use config::UpstreamConfig;
+use email::EmailSender;
+use state::AppState;
+use std::time::Duration;
+use tower_http::cors::CorsLayer;
+use tower_http::trace::TraceLayer;
+
+/// Build the axum application.
+pub fn build_app(state: AppState) -> axum::Router {
+    axum::Router::new()
+        .merge(handlers::routes())
+        .merge(authz::router(&state))
+        .merge(web::router(&state))
+        // The /web/v1 surface is called cross-origin by the browser SPA in
+        // dev; same-origin behind nginx in prod. Permissive is fine — these
+        // endpoints authenticate via bearer/JWT, not cookies.
+        .layer(CorsLayer::permissive())
+        .layer(TraceLayer::new_for_http())
+        .with_state(state)
+}
+
+/// Start the service: connect Postgres, run migrations, spawn the
+/// reservation sweeper, bind the listener.
+pub async fn run(config: UpstreamConfig) -> Result<()> {
+    let pool = db::connect_and_migrate(&config.db.url, config.db.max_connections).await?;
+    let email = EmailSender::from_config(&config.email)?;
+    let listen = config.server.listen.clone();
+    let state = AppState::new(pool, config, email);
+
+    if state.config.client_auth.tokens.is_empty() {
+        tracing::warn!(
+            "no [client_auth] tokens configured — the /authz/v1 surface is OPEN (dev only)"
+        );
+    }
+
+    // Stale-reservation sweeper: releases open reservations whose
+    // settle/release from cortex was lost, self-healing allocation_reserved.
+    spawn_sweeper(&state);
+
+    let addr = listen.parse::<std::net::SocketAddr>()?;
+    tracing::info!("helexa-upstream listening on {addr}");
+
+    let listener = tokio::net::TcpListener::bind(addr).await?;
+    axum::serve(listener, build_app(state)).await?;
+    Ok(())
+}
+
+fn spawn_sweeper(state: &AppState) {
+    let pool = state.pool.clone();
+    let ttl = state.config.authz.reservation_ttl_secs as i64;
+    let interval = Duration::from_secs(state.config.authz.sweep_interval_secs);
+    tokio::spawn(async move {
+        loop {
+            tokio::time::sleep(interval).await;
+            match ledger::sweep_stale(&pool, ttl).await {
+                Ok(n) if n > 0 => tracing::info!(swept = n, "released stale reservations"),
+                Ok(_) => {}
+                Err(e) => tracing::warn!(error = %e, "reservation sweep failed"),
+            }
+        }
+    });
+}

crates/helexa-upstream/src/main.rs

@@ -0,0 +1,99 @@
+use anyhow::Result;
+use clap::{Parser, Subcommand};
+use helexa_upstream::config::UpstreamConfig;
+use tracing_subscriber::EnvFilter;
+
+#[derive(Parser)]
+#[command(name = "helexa-upstream")]
+#[command(about = "Mesh-level account & authorization authority for helexa")]
+#[command(version)]
+struct Cli {
+    #[command(subcommand)]
+    command: Commands,
+}
+
+#[derive(Subcommand)]
+enum Commands {
+    /// Start the upstream server.
+    Serve {
+        /// Path to the config file.
+        #[arg(short, long, default_value = "helexa-upstream.toml")]
+        config: String,
+    },
+    /// Mint single-use top-up codes and print them (one per line). The raw
+    /// codes are shown only here — only their hash is stored. (The future
+    /// faucet bot calls the same path.)
+    Mint {
+        #[arg(short, long, default_value = "helexa-upstream.toml")]
+        config: String,
+        /// Tokens each code grants.
+        #[arg(long)]
+        value: i64,
+        /// How many codes to mint.
+        #[arg(long, default_value_t = 1)]
+        count: u32,
+        /// Optional human label (e.g. "small", "beta-launch").
+        #[arg(long)]
+        denomination: Option<String>,
+    },
+    /// Roll up not-yet-reconciled served usage per operator/period (#58),
+    /// stamp it reconciled, and print the totals. Payout is out of scope.
+    Reconcile {
+        #[arg(short, long, default_value = "helexa-upstream.toml")]
+        config: String,
+    },
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    tracing_subscriber::fmt()
+        .with_env_filter(
+            EnvFilter::try_from_default_env()
+                .unwrap_or_else(|_| EnvFilter::new("info,helexa_upstream=debug")),
+        )
+        .init();
+
+    let cli = Cli::parse();
+
+    match cli.command {
+        Commands::Serve { config } => {
+            let cfg = UpstreamConfig::load(&config)
+                .map_err(|e| anyhow::anyhow!("failed to load config from '{config}': {e}"))?;
+            tracing::info!(listen = %cfg.server.listen, "starting helexa-upstream");
+            helexa_upstream::run(cfg).await?;
+        }
+        Commands::Mint {
+            config,
+            value,
+            count,
+            denomination,
+        } => {
+            let cfg = UpstreamConfig::load(&config)
+                .map_err(|e| anyhow::anyhow!("failed to load config from '{config}': {e}"))?;
+            let pool =
+                helexa_upstream::db::connect_and_migrate(&cfg.db.url, cfg.db.max_connections)
+                    .await?;
+            let codes =
+                helexa_upstream::topup::mint(&pool, value, count, denomination.as_deref()).await?;
+            // Raw codes to stdout (one per line) for the operator to distribute;
+            // logs/diagnostics go to stderr via tracing.
+            for code in codes {
+                println!("{code}");
+            }
+        }
+        Commands::Reconcile { config } => {
+            let cfg = UpstreamConfig::load(&config)
+                .map_err(|e| anyhow::anyhow!("failed to load config from '{config}': {e}"))?;
+            let pool =
+                helexa_upstream::db::connect_and_migrate(&cfg.db.url, cfg.db.max_connections)
+                    .await?;
+            let rollup = helexa_upstream::reconcile::reconcile(&pool).await?;
+            for r in &rollup {
+                println!("{}\t{}\t{}", r.operator_id, r.period, r.total_served_tokens);
+            }
+            tracing::info!(operators_periods = rollup.len(), "reconciliation complete");
+        }
+    }
+
+    Ok(())
+}

crates/helexa-upstream/src/reconcile.rs

@@ -0,0 +1,43 @@
+//! Reconciliation rollup (#58): aggregate the served-usage ledger per
+//! operator and period for operator compensation, stamping rows
+//! `reconciled_at` so each window is settled once. The payout mechanism
+//! itself is out of scope — this produces the authoritative per-operator
+//! totals a settlement process consumes.
+
+use sqlx::Row;
+use sqlx::postgres::PgPool;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RollupRow {
+    pub operator_id: String,
+    pub period: chrono::NaiveDate,
+    pub total_served_tokens: i64,
+}
+
+/// Roll up all not-yet-reconciled served-usage into per-(operator, period)
+/// totals, then stamp those rows `reconciled_at`. Returns the rollup.
+/// Idempotent: a second run finds nothing unreconciled and returns empty.
+pub async fn reconcile(pool: &PgPool) -> Result<Vec<RollupRow>, sqlx::Error> {
+    let mut tx = pool.begin().await?;
+    let rows = sqlx::query(
+        // SUM(bigint) is numeric in Postgres — cast back to bigint for i64.
+        "SELECT operator_id, period, SUM(served_tokens)::bigint AS total \
+         FROM served_usage WHERE reconciled_at IS NULL \
+         GROUP BY operator_id, period ORDER BY operator_id, period",
+    )
+    .fetch_all(&mut *tx)
+    .await?;
+    let rollup: Vec<RollupRow> = rows
+        .iter()
+        .map(|r| RollupRow {
+            operator_id: r.get("operator_id"),
+            period: r.get("period"),
+            total_served_tokens: r.get::<i64, _>("total"),
+        })
+        .collect();
+    sqlx::query("UPDATE served_usage SET reconciled_at = now() WHERE reconciled_at IS NULL")
+        .execute(&mut *tx)
+        .await?;
+    tx.commit().await?;
+    Ok(rollup)
+}

crates/helexa-upstream/src/state.rs

@@ -0,0 +1,23 @@
+//! Shared application state.
+
+use crate::config::UpstreamConfig;
+use crate::email::EmailSender;
+use sqlx::postgres::PgPool;
+use std::sync::Arc;
+
+#[derive(Clone)]
+pub struct AppState {
+    pub pool: PgPool,
+    pub config: Arc<UpstreamConfig>,
+    pub email: EmailSender,
+}
+
+impl AppState {
+    pub fn new(pool: PgPool, config: UpstreamConfig, email: EmailSender) -> Self {
+        Self {
+            pool,
+            config: Arc::new(config),
+            email,
+        }
+    }
+}

crates/helexa-upstream/src/topup.rs

@@ -0,0 +1,82 @@
+//! Single-use top-up codes (#B5) — the second half of the hybrid allocation
+//! model. Each code grants `value` tokens to the account that redeems it,
+//! raising `accounts.allocation_total`. Minting codes is operator/CLI side
+//! (the future faucet bot calls the same `mint` path); redemption is a
+//! `/web/v1` action.
+//!
+//! Security: only `sha256(code)` is stored. Redemption is **timing-safe and
+//! single-use** — a conditional `UPDATE … WHERE redeemed_by IS NULL` does
+//! the claim atomically (concurrent double-redeem → exactly one winner), and
+//! a not-found code and an already-redeemed code return the **same** generic
+//! failure with the same code path (no oracle for "valid but spent").
+
+use crate::crypto::{random_token, sha256};
+use sqlx::Row;
+use sqlx::postgres::PgPool;
+use uuid::Uuid;
+
+#[derive(Debug, thiserror::Error)]
+pub enum TopUpError {
+    /// Code unknown OR already redeemed — deliberately indistinguishable.
+    #[error("invalid or already-redeemed code")]
+    Invalid,
+    #[error(transparent)]
+    Db(#[from] sqlx::Error),
+}
+
+/// Redeem `raw_code` for `account_id`, raising the account's
+/// `allocation_total` by the code's value. Returns the new total.
+pub async fn redeem(pool: &PgPool, account_id: Uuid, raw_code: &str) -> Result<i64, TopUpError> {
+    let mut tx = pool.begin().await?;
+    // Atomic single-use claim. `redeemed_by IS NULL` is the guarantee: under
+    // concurrent redemption exactly one UPDATE touches the row.
+    let claimed = sqlx::query(
+        "UPDATE top_up_codes SET redeemed_by = $1, redeemed_at = now() \
+         WHERE code_hash = $2 AND redeemed_by IS NULL RETURNING value",
+    )
+    .bind(account_id)
+    .bind(sha256(raw_code))
+    .fetch_optional(&mut *tx)
+    .await?;
+    let Some(row) = claimed else {
+        // Not found or already redeemed — same path, same error.
+        return Err(TopUpError::Invalid);
+    };
+    let value: i64 = row.get("value");
+    let new_total: i64 = sqlx::query(
+        "UPDATE accounts SET allocation_total = allocation_total + $1 WHERE id = $2 \
+         RETURNING allocation_total",
+    )
+    .bind(value)
+    .bind(account_id)
+    .fetch_one(&mut *tx)
+    .await?
+    .get("allocation_total");
+    tx.commit().await?;
+    Ok(new_total)
+}
+
+/// Mint `count` codes each worth `value` tokens, optionally tagged with a
+/// `denomination` label. Returns the raw codes (shown once — only their
+/// hash is stored). The CLI prints these; the future faucet bot calls this.
+pub async fn mint(
+    pool: &PgPool,
+    value: i64,
+    count: u32,
+    denomination: Option<&str>,
+) -> Result<Vec<String>, sqlx::Error> {
+    let mut codes = Vec::with_capacity(count as usize);
+    for _ in 0..count {
+        let raw = format!("helexa-topup-{}", random_token());
+        sqlx::query(
+            "INSERT INTO top_up_codes (code_hash, value, denomination) VALUES ($1, $2, $3)",
+        )
+        .bind(sha256(&raw))
+        .bind(value)
+        .bind(denomination)
+        .execute(pool)
+        .await?;
+        codes.push(raw);
+    }
+    Ok(codes)
+}

crates/helexa-upstream/src/web.rs

@@ -0,0 +1,594 @@
+//! `/web/v1` — the human-facing account API the helexa.ai frontend (#F4)
+//! consumes: email+password auth (register / verify / login / reset),
+//! API-key CRUD with per-key limits, and the account balance. Web sessions
+//! are JWTs, **distinct** from inference API keys.
+//!
+//! Errors use a plain JSON shape `{ "error": { "message", "code" } }` (web
+//! clients, not OpenAI clients — the #63 envelope is the authz surface).
+//!
+//! Silent fingerprint abuse (no clue to the abuser): registration captures
+//! the browser fingerprint and always succeeds; when ≥ threshold accounts
+//! share one fingerprint, all are silently `deactivated` (keys then resolve
+//! as ordinary `401`s at the authz surface — never a "banned" signal).
+
+use crate::crypto::{generate_api_key, hash_password, random_token, sha256, verify_password};
+use crate::state::AppState;
+use axum::extract::{Path, Request, State};
+use axum::http::{StatusCode, header};
+use axum::middleware::Next;
+use axum::response::{IntoResponse, Json, Response};
+use axum::routing::{get, post};
+use axum::{Extension, Router};
+use chrono::{DateTime, Duration, Utc};
+use jsonwebtoken::{DecodingKey, EncodingKey, Header, Validation, decode, encode};
+use serde::{Deserialize, Serialize};
+use serde_json::json;
+use sqlx::Row;
+use uuid::Uuid;
+
+pub fn router(state: &AppState) -> Router<AppState> {
+    let protected = Router::new()
+        .route("/web/v1/account", get(account))
+        .route("/web/v1/keys", get(list_keys).post(create_key))
+        .route("/web/v1/keys/{id}/archive", post(archive_key))
+        .route(
+            "/web/v1/keys/{id}/limit",
+            axum::routing::patch(update_key_limit),
+        )
+        .route("/web/v1/redeem", post(redeem))
+        .layer(axum::middleware::from_fn_with_state(
+            state.clone(),
+            require_session,
+        ));
+
+    Router::new()
+        .route("/web/v1/register", post(register))
+        .route("/web/v1/verify", post(verify))
+        .route("/web/v1/login", post(login))
+        .route("/web/v1/password-reset/request", post(reset_request))
+        .route("/web/v1/password-reset/confirm", post(reset_confirm))
+        .merge(protected)
+}
+
+// ── errors ──────────────────────────────────────────────────────────
+
+enum WebError {
+    BadRequest(&'static str),
+    Unauthorized,
+    Internal,
+}
+
+impl IntoResponse for WebError {
+    fn into_response(self) -> Response {
+        let (status, code, message) = match self {
+            WebError::BadRequest(m) => (StatusCode::BAD_REQUEST, "bad_request", m),
+            WebError::Unauthorized => (StatusCode::UNAUTHORIZED, "unauthorized", "unauthorized"),
+            WebError::Internal => (
+                StatusCode::INTERNAL_SERVER_ERROR,
+                "internal_error",
+                "internal error",
+            ),
+        };
+        (
+            status,
+            Json(json!({"error": {"message": message, "code": code}})),
+        )
+            .into_response()
+    }
+}
+
+impl From<sqlx::Error> for WebError {
+    fn from(e: sqlx::Error) -> Self {
+        tracing::error!(error = %e, "web db error");
+        WebError::Internal
+    }
+}
+
+type WebResult<T> = Result<T, WebError>;
+
+// ── sessions (JWT) ──────────────────────────────────────────────────
+
+#[derive(Serialize, Deserialize)]
+struct Claims {
+    sub: String, // user id
+    exp: usize,
+}
+
+fn mint_session(state: &AppState, user_id: Uuid) -> WebResult<String> {
+    let exp = (Utc::now() + Duration::seconds(state.config.auth.session_ttl_secs as i64))
+        .timestamp() as usize;
+    let claims = Claims {
+        sub: user_id.to_string(),
+        exp,
+    };
+    encode(
+        &Header::default(),
+        &claims,
+        &EncodingKey::from_secret(state.config.auth.jwt_secret.as_bytes()),
+    )
+    .map_err(|_| WebError::Internal)
+}
+
+/// Authenticated user id, injected by [`require_session`].
+#[derive(Clone)]
+struct AuthUser(Uuid);
+
+async fn require_session(State(state): State<AppState>, mut req: Request, next: Next) -> Response {
+    let token = req
+        .headers()
+        .get(header::AUTHORIZATION)
+        .and_then(|v| v.to_str().ok())
+        .and_then(|v| v.strip_prefix("Bearer "))
+        .map(str::trim);
+    let Some(token) = token else {
+        return WebError::Unauthorized.into_response();
+    };
+    let decoded = decode::<Claims>(
+        token,
+        &DecodingKey::from_secret(state.config.auth.jwt_secret.as_bytes()),
+        &Validation::default(),
+    );
+    match decoded
+        .ok()
+        .and_then(|d| Uuid::parse_str(&d.claims.sub).ok())
+    {
+        Some(uid) => {
+            req.extensions_mut().insert(AuthUser(uid));
+            next.run(req).await
+        }
+        None => WebError::Unauthorized.into_response(),
+    }
+}
+
+/// The caller's single account id.
+async fn account_id_for(state: &AppState, user_id: Uuid) -> WebResult<Uuid> {
+    let row = sqlx::query("SELECT id FROM accounts WHERE owner_user_id = $1")
+        .bind(user_id)
+        .fetch_optional(&state.pool)
+        .await?;
+    row.map(|r| r.get::<Uuid, _>("id"))
+        .ok_or(WebError::Internal)
+}
+
+// ── auth lifecycle ──────────────────────────────────────────────────
+
+#[derive(Deserialize)]
+struct RegisterReq {
+    email: String,
+    password: String,
+    #[serde(default)]
+    fingerprint: Option<String>,
+}
+
+/// `POST /web/v1/register` — always returns `202`, regardless of whether the
+/// email was new, already taken, or fingerprint-flagged (no enumeration, no
+/// abuse clue).
+async fn register(State(state): State<AppState>, Json(req): Json<RegisterReq>) -> Response {
+    match register_inner(&state, req).await {
+        Ok(()) | Err(WebError::BadRequest(_)) => {}
+        Err(e) => return e.into_response(),
+    }
+    // Generic 202 whatever happened above (except hard server errors).
+    StatusCode::ACCEPTED.into_response()
+}
+
+async fn register_inner(state: &AppState, req: RegisterReq) -> WebResult<()> {
+    if !req.email.contains('@') {
+        return Err(WebError::BadRequest("invalid email"));
+    }
+    if req.password.len() < 8 {
+        return Err(WebError::BadRequest("password too short (min 8)"));
+    }
+    let phc = hash_password(&req.password).map_err(|_| WebError::Internal)?;
+
+    // Insert the user; a duplicate email silently no-ops (no enumeration).
+    let user_id: Option<Uuid> = sqlx::query(
+        "INSERT INTO users (email, password_hash, registration_fingerprint) \
+         VALUES ($1, $2, $3) ON CONFLICT (email) DO NOTHING RETURNING id",
+    )
+    .bind(&req.email)
+    .bind(&phc)
+    .bind(&req.fingerprint)
+    .fetch_optional(&state.pool)
+    .await?
+    .map(|r| r.get("id"));
+
+    let Some(user_id) = user_id else {
+        return Ok(()); // email already registered — say nothing
+    };
+
+    // Account with the flat free grant.
+    sqlx::query("INSERT INTO accounts (owner_user_id, allocation_total) VALUES ($1, $2)")
+        .bind(user_id)
+        .bind(state.config.grant.free_token_grant)
+        .execute(&state.pool)
+        .await?;
+
+    // Silent fingerprint abuse handling.
+    if let Some(fp) = req.fingerprint.as_deref().filter(|f| !f.is_empty()) {
+        apply_fingerprint_policy(state, fp).await?;
+    }
+
+    // Email verification link.
+    let token = random_token();
+    let expires: DateTime<Utc> =
+        Utc::now() + Duration::seconds(state.config.auth.email_token_ttl_secs as i64);
+    sqlx::query(
+        "INSERT INTO email_tokens (token_hash, user_id, kind, expires_at) \
+         VALUES ($1, $2, 'verify', $3)",
+    )
+    .bind(sha256(&token))
+    .bind(user_id)
+    .bind(expires)
+    .execute(&state.pool)
+    .await?;
+
+    let link = format!("{}/verify?token={token}", state.config.auth.app_base_url);
+    let _ = state
+        .email
+        .send(
+            &req.email,
+            "Verify your helexa account",
+            &format!("Welcome to helexa. Verify your email:\n\n{link}\n"),
+        )
+        .await;
+    Ok(())
+}
+
+/// Count accounts sharing `fp`; flag them, and silently deactivate all once
+/// the count reaches the configured threshold. No response difference — the
+/// abuser gets no signal.
+async fn apply_fingerprint_policy(state: &AppState, fp: &str) -> WebResult<()> {
+    let count: i64 =
+        sqlx::query_scalar("SELECT count(*) FROM users WHERE registration_fingerprint = $1")
+            .bind(fp)
+            .fetch_one(&state.pool)
+            .await?;
+    if count > 1 {
+        sqlx::query(
+            "UPDATE accounts SET fingerprint_flagged = true \
+             WHERE owner_user_id IN (SELECT id FROM users WHERE registration_fingerprint = $1)",
+        )
+        .bind(fp)
+        .execute(&state.pool)
+        .await?;
+    }
+    if count >= state.config.abuse.fingerprint_account_threshold {
+        let res = sqlx::query(
+            "UPDATE accounts SET status = 'deactivated' \
+             WHERE owner_user_id IN (SELECT id FROM users WHERE registration_fingerprint = $1)",
+        )
+        .bind(fp)
+        .execute(&state.pool)
+        .await?;
+        tracing::warn!(
+            fingerprint = fp,
+            accounts = res.rows_affected(),
+            "silently deactivated fingerprint-abusing accounts"
+        );
+    }
+    Ok(())
+}
+
+#[derive(Deserialize)]
+struct TokenReq {
+    token: String,
+}
+
+/// `POST /web/v1/verify` — consume a verification token, mark verified.
+async fn verify(State(state): State<AppState>, Json(req): Json<TokenReq>) -> WebResult<Response> {
+    let row = sqlx::query(
+        "UPDATE email_tokens SET consumed_at = now() \
+         WHERE token_hash = $1 AND kind = 'verify' AND consumed_at IS NULL AND expires_at > now() \
+         RETURNING user_id",
+    )
+    .bind(sha256(&req.token))
+    .fetch_optional(&state.pool)
+    .await?;
+    let Some(row) = row else {
+        return Err(WebError::BadRequest("invalid or expired token"));
+    };
+    let user_id: Uuid = row.get("user_id");
+    sqlx::query("UPDATE users SET email_verified = true WHERE id = $1")
+        .bind(user_id)
+        .execute(&state.pool)
+        .await?;
+    Ok(StatusCode::OK.into_response())
+}
+
+#[derive(Deserialize)]
+struct LoginReq {
+    email: String,
+    password: String,
+}
+
+/// `POST /web/v1/login` — verify password + email-verified → session JWT.
+async fn login(State(state): State<AppState>, Json(req): Json<LoginReq>) -> WebResult<Response> {
+    let row = sqlx::query("SELECT id, password_hash, email_verified FROM users WHERE email = $1")
+        .bind(&req.email)
+        .fetch_optional(&state.pool)
+        .await?;
+    // Generic 401 for every failure mode (no enumeration).
+    let Some(row) = row else {
+        return Err(WebError::Unauthorized);
+    };
+    let phc: String = row.get("password_hash");
+    let verified: bool = row.get("email_verified");
+    if !verify_password(&req.password, &phc) || !verified {
+        return Err(WebError::Unauthorized);
+    }
+    let user_id: Uuid = row.get("id");
+    let token = mint_session(&state, user_id)?;
+    Ok(Json(json!({
+        "token": token,
+        "expires_in": state.config.auth.session_ttl_secs,
+    }))
+    .into_response())
+}
+
+#[derive(Deserialize)]
+struct EmailReq {
+    email: String,
+}
+
+/// `POST /web/v1/password-reset/request` — always `202` (no enumeration);
+/// mints + emails a reset token only if the account exists.
+async fn reset_request(State(state): State<AppState>, Json(req): Json<EmailReq>) -> Response {
+    // The inner only ever yields `Internal` (DB failure); a missing email is
+    // Ok(()) so there's no enumeration. Surface 500 on a real error, else 202.
+    match reset_request_inner(&state, &req.email).await {
+        Ok(()) => StatusCode::ACCEPTED.into_response(),
+        Err(e) => e.into_response(),
+    }
+}
+
+async fn reset_request_inner(state: &AppState, email: &str) -> WebResult<()> {
+    let row = sqlx::query("SELECT id FROM users WHERE email = $1")
+        .bind(email)
+        .fetch_optional(&state.pool)
+        .await?;
+    let Some(row) = row else { return Ok(()) };
+    let user_id: Uuid = row.get("id");
+    let token = random_token();
+    let expires: DateTime<Utc> =
+        Utc::now() + Duration::seconds(state.config.auth.email_token_ttl_secs as i64);
+    sqlx::query(
+        "INSERT INTO email_tokens (token_hash, user_id, kind, expires_at) \
+         VALUES ($1, $2, 'reset', $3)",
+    )
+    .bind(sha256(&token))
+    .bind(user_id)
+    .bind(expires)
+    .execute(&state.pool)
+    .await?;
+    let link = format!("{}/reset?token={token}", state.config.auth.app_base_url);
+    let _ = state
+        .email
+        .send(
+            email,
+            "Reset your helexa password",
+            &format!("Reset your password:\n\n{link}\n"),
+        )
+        .await;
+    Ok(())
+}
+
+#[derive(Deserialize)]
+struct ResetConfirmReq {
+    token: String,
+    new_password: String,
+}
+
+/// `POST /web/v1/password-reset/confirm` — consume reset token, rotate hash.
+async fn reset_confirm(
+    State(state): State<AppState>,
+    Json(req): Json<ResetConfirmReq>,
+) -> WebResult<Response> {
+    if req.new_password.len() < 8 {
+        return Err(WebError::BadRequest("password too short (min 8)"));
+    }
+    let row = sqlx::query(
+        "UPDATE email_tokens SET consumed_at = now() \
+         WHERE token_hash = $1 AND kind = 'reset' AND consumed_at IS NULL AND expires_at > now() \
+         RETURNING user_id",
+    )
+    .bind(sha256(&req.token))
+    .fetch_optional(&state.pool)
+    .await?;
+    let Some(row) = row else {
+        return Err(WebError::BadRequest("invalid or expired token"));
+    };
+    let user_id: Uuid = row.get("user_id");
+    let phc = hash_password(&req.new_password).map_err(|_| WebError::Internal)?;
+    sqlx::query("UPDATE users SET password_hash = $1 WHERE id = $2")
+        .bind(phc)
+        .bind(user_id)
+        .execute(&state.pool)
+        .await?;
+    Ok(StatusCode::OK.into_response())
+}
+
+// ── account + keys (protected) ──────────────────────────────────────
+
+async fn account(
+    State(state): State<AppState>,
+    Extension(user): Extension<AuthUser>,
+) -> WebResult<Response> {
+    let acct = account_id_for(&state, user.0).await?;
+    let row = sqlx::query(
+        "SELECT allocation_total, allocation_spent, allocation_reserved FROM accounts WHERE id = $1",
+    )
+    .bind(acct)
+    .fetch_one(&state.pool)
+    .await?;
+    Ok(Json(json!({
+        "account_id": acct.to_string(),
+        "allocation_total": row.get::<i64, _>("allocation_total"),
+        "allocation_spent": row.get::<i64, _>("allocation_spent"),
+        "allocation_reserved": row.get::<i64, _>("allocation_reserved"),
+    }))
+    .into_response())
+}
+
+async fn list_keys(
+    State(state): State<AppState>,
+    Extension(user): Extension<AuthUser>,
+) -> WebResult<Response> {
+    let acct = account_id_for(&state, user.0).await?;
+    let rows = sqlx::query(
+        "SELECT id, key_prefix, label, status, limit_kind, limit_value, key_spent, key_reserved, \
+                created_at \
+         FROM api_keys WHERE account_id = $1 ORDER BY created_at DESC",
+    )
+    .bind(acct)
+    .fetch_all(&state.pool)
+    .await?;
+    let keys: Vec<_> = rows
+        .iter()
+        .map(|r| {
+            json!({
+                "id": r.get::<Uuid, _>("id").to_string(),
+                "prefix": r.get::<String, _>("key_prefix"),
+                "label": r.get::<String, _>("label"),
+                "status": r.get::<String, _>("status"),
+                "limit_kind": r.get::<String, _>("limit_kind"),
+                "limit_value": r.get::<i64, _>("limit_value"),
+                "spent": r.get::<i64, _>("key_spent"),
+                "reserved": r.get::<i64, _>("key_reserved"),
+                "created_at": r.get::<DateTime<Utc>, _>("created_at").to_rfc3339(),
+            })
+        })
+        .collect();
+    Ok(Json(json!({ "keys": keys })).into_response())
+}
+
+#[derive(Deserialize)]
+struct CreateKeyReq {
+    #[serde(default)]
+    label: String,
+    /// "percent" | "hardcap" (default percent=100 → full allocation).
+    #[serde(default)]
+    limit_kind: Option<String>,
+    #[serde(default)]
+    limit_value: Option<i64>,
+}
+
+async fn create_key(
+    State(state): State<AppState>,
+    Extension(user): Extension<AuthUser>,
+    Json(req): Json<CreateKeyReq>,
+) -> WebResult<Response> {
+    let acct = account_id_for(&state, user.0).await?;
+    let limit_kind = match req.limit_kind.as_deref() {
+        Some("hardcap") => "hardcap",
+        _ => "percent",
+    };
+    let limit_value = req.limit_value.unwrap_or(100).max(0);
+    let (raw, prefix) = generate_api_key();
+    let id: Uuid = sqlx::query(
+        "INSERT INTO api_keys (account_id, key_hash, key_prefix, label, limit_kind, limit_value) \
+         VALUES ($1, $2, $3, $4, $5, $6) RETURNING id",
+    )
+    .bind(acct)
+    .bind(sha256(&raw))
+    .bind(&prefix)
+    .bind(&req.label)
+    .bind(limit_kind)
+    .bind(limit_value)
+    .fetch_one(&state.pool)
+    .await?
+    .get("id");
+    // The raw key is shown exactly once.
+    Ok((
+        StatusCode::CREATED,
+        Json(json!({
+            "id": id.to_string(),
+            "key": raw,
+            "prefix": prefix,
+            "limit_kind": limit_kind,
+            "limit_value": limit_value,
+        })),
+    )
+        .into_response())
+}
+
+async fn archive_key(
+    State(state): State<AppState>,
+    Extension(user): Extension<AuthUser>,
+    Path(id): Path<Uuid>,
+) -> WebResult<Response> {
+    let acct = account_id_for(&state, user.0).await?;
+    let res = sqlx::query(
+        "UPDATE api_keys SET status = 'archived' WHERE id = $1 AND account_id = $2 AND status = 'active'",
+    )
+    .bind(id)
+    .bind(acct)
+    .execute(&state.pool)
+    .await?;
+    if res.rows_affected() == 0 {
+        return Err(WebError::BadRequest("no such active key"));
+    }
+    Ok(StatusCode::NO_CONTENT.into_response())
+}
+
+#[derive(Deserialize)]
+struct UpdateLimitReq {
+    limit_kind: String,
+    limit_value: i64,
+}
+
+async fn update_key_limit(
+    State(state): State<AppState>,
+    Extension(user): Extension<AuthUser>,
+    Path(id): Path<Uuid>,
+    Json(req): Json<UpdateLimitReq>,
+) -> WebResult<Response> {
+    if req.limit_kind != "percent" && req.limit_kind != "hardcap" {
+        return Err(WebError::BadRequest(
+            "limit_kind must be percent or hardcap",
+        ));
+    }
+    if req.limit_value < 0 {
+        return Err(WebError::BadRequest("limit_value must be >= 0"));
+    }
+    let acct = account_id_for(&state, user.0).await?;
+    let res = sqlx::query(
+        "UPDATE api_keys SET limit_kind = $1, limit_value = $2 WHERE id = $3 AND account_id = $4",
+    )
+    .bind(&req.limit_kind)
+    .bind(req.limit_value)
+    .bind(id)
+    .bind(acct)
+    .execute(&state.pool)
+    .await?;
+    if res.rows_affected() == 0 {
+        return Err(WebError::BadRequest("no such key"));
+    }
+    Ok(StatusCode::NO_CONTENT.into_response())
+}
+
+#[derive(Deserialize)]
+struct RedeemReq {
+    code: String,
+}
+
+/// `POST /web/v1/redeem` — redeem a single-use top-up code, raising the
+/// account's allocation. Returns the new total. Generic 400 for an invalid
+/// or already-redeemed code (no oracle).
+async fn redeem(
+    State(state): State<AppState>,
+    Extension(user): Extension<AuthUser>,
+    Json(req): Json<RedeemReq>,
+) -> WebResult<Response> {
+    let acct = account_id_for(&state, user.0).await?;
+    match crate::topup::redeem(&state.pool, acct, &req.code).await {
+        Ok(new_total) => Ok(Json(json!({ "allocation_total": new_total })).into_response()),
+        Err(crate::topup::TopUpError::Invalid) => {
+            Err(WebError::BadRequest("invalid or already-redeemed code"))
+        }
+        Err(crate::topup::TopUpError::Db(e)) => {
+            tracing::error!(error = %e, "redeem db error");
+            Err(WebError::Internal)
+        }
+    }
+}

crates/helexa-upstream/tests/authz_pg.rs

@@ -0,0 +1,243 @@
+//! Integration tests for the `/authz/v1` surface against a real Postgres,
+//! driving the built axum app over HTTP. Gated on `UPSTREAM_TEST_DATABASE_URL`
+//! (skips cleanly when unset, so CI stays green without a DB):
+//!
+//!   UPSTREAM_TEST_DATABASE_URL=postgres://helexa:helexa@localhost/helexa_test \
+//!     cargo test -p helexa-upstream --test authz_pg
+
+use helexa_upstream::config::{ClientToken, UpstreamConfig};
+use helexa_upstream::crypto::sha256;
+use helexa_upstream::db::connect_and_migrate;
+use helexa_upstream::state::AppState;
+use serde_json::{Value, json};
+use sqlx::Executor;
+use sqlx::Row;
+use sqlx::postgres::PgPool;
+use uuid::Uuid;
+
+const CLIENT_TOKEN: &str = "test-operator-token";
+
+async fn spawn_or_skip(test: &str) -> Option<(String, PgPool)> {
+    let Ok(url) = std::env::var("UPSTREAM_TEST_DATABASE_URL") else {
+        eprintln!("skipping {test}: UPSTREAM_TEST_DATABASE_URL not set");
+        return None;
+    };
+    let pool = connect_and_migrate(&url, 16).await.expect("migrate");
+
+    let mut config = UpstreamConfig {
+        server: Default::default(),
+        db: helexa_upstream::config::DbSettings {
+            url,
+            max_connections: 16,
+        },
+        grant: Default::default(),
+        abuse: Default::default(),
+        client_auth: Default::default(),
+        authz: Default::default(),
+        auth: Default::default(),
+        email: Default::default(),
+    };
+    config.client_auth.tokens.push(ClientToken {
+        token: CLIENT_TOKEN.into(),
+        operator_id: "op-test".into(),
+    });
+
+    let email = helexa_upstream::email::EmailSender::from_config(&config.email).unwrap();
+    let state = AppState::new(pool.clone(), config, email);
+    let app = helexa_upstream::build_app(state);
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let addr = listener.local_addr().unwrap();
+    tokio::spawn(async move {
+        axum::serve(listener, app).await.unwrap();
+    });
+    Some((format!("http://{addr}"), pool))
+}
+
+/// Seed an account with `total` allocation and an active key with raw value
+/// `raw` (percent=100). Optionally deactivate the account. Returns
+/// (account_id, key_id).
+async fn seed_key(pool: &PgPool, total: i64, raw: &str, deactivated: bool) -> (Uuid, Uuid) {
+    let user_id: Uuid = pool
+        .fetch_one(
+            sqlx::query(
+                "INSERT INTO users (email, password_hash, email_verified) VALUES ($1,'x',true) RETURNING id",
+            )
+            .bind(format!("u-{}@t.local", Uuid::new_v4())),
+        )
+        .await
+        .unwrap()
+        .get("id");
+    let status = if deactivated { "deactivated" } else { "active" };
+    let account_id: Uuid = pool
+        .fetch_one(
+            sqlx::query(
+                "INSERT INTO accounts (owner_user_id, allocation_total, status) VALUES ($1,$2,$3) RETURNING id",
+            )
+            .bind(user_id)
+            .bind(total)
+            .bind(status),
+        )
+        .await
+        .unwrap()
+        .get("id");
+    let key_id: Uuid = pool
+        .fetch_one(
+            sqlx::query(
+                "INSERT INTO api_keys (account_id, key_hash, key_prefix, limit_kind, limit_value) \
+                 VALUES ($1,$2,'sk-test','percent',100) RETURNING id",
+            )
+            .bind(account_id)
+            .bind(sha256(raw)),
+        )
+        .await
+        .unwrap()
+        .get("id");
+    (account_id, key_id)
+}
+
+fn client() -> reqwest::Client {
+    reqwest::Client::new()
+}
+
+async fn post(
+    c: &reqwest::Client,
+    url: String,
+    body: Value,
+    bearer: Option<&str>,
+) -> reqwest::Response {
+    let mut req = c.post(url).json(&body);
+    if let Some(b) = bearer {
+        req = req.bearer_auth(b);
+    }
+    req.send().await.unwrap()
+}
+
+#[tokio::test]
+async fn resolve_reserve_settle_round_trip() {
+    let Some((base, pool)) = spawn_or_skip("resolve_reserve_settle_round_trip").await else {
+        return;
+    };
+    let raw = format!("sk-{}", Uuid::new_v4());
+    let (account_id, key_id) = seed_key(&pool, 1000, &raw, false).await;
+    let c = client();
+
+    // resolve
+    let r = post(
+        &c,
+        format!("{base}/authz/v1/resolve"),
+        json!({"api_key": raw}),
+        Some(CLIENT_TOKEN),
+    )
+    .await;
+    assert_eq!(r.status(), 200);
+    let body: Value = r.json().await.unwrap();
+    assert_eq!(body["principal"]["account_id"], account_id.to_string());
+    assert_eq!(body["principal"]["key_id"], key_id.to_string());
+    assert_eq!(body["snapshot"]["hard_cap"], 1000);
+
+    // reserve 400
+    let r = post(
+        &c,
+        format!("{base}/authz/v1/reserve"),
+        json!({"account_id": account_id, "key_id": key_id, "max_tokens": 400}),
+        Some(CLIENT_TOKEN),
+    )
+    .await;
+    assert_eq!(r.status(), 200);
+    let body: Value = r.json().await.unwrap();
+    let rid = body["reservation_id"].as_i64().expect("granted");
+
+    // settle 150
+    let r = post(
+        &c,
+        format!("{base}/authz/v1/settle"),
+        json!({"reservation_id": rid, "actual_tokens": 150}),
+        Some(CLIENT_TOKEN),
+    )
+    .await;
+    assert_eq!(r.status(), 204);
+
+    // snapshot reflects spend
+    let r = post(
+        &c,
+        format!("{base}/authz/v1/snapshot"),
+        json!({"account_id": account_id, "key_id": key_id}),
+        Some(CLIENT_TOKEN),
+    )
+    .await;
+    let body: Value = r.json().await.unwrap();
+    assert_eq!(body["spent"], 150);
+    assert_eq!(body["reserved"], 0);
+}
+
+#[tokio::test]
+async fn over_cap_reserve_is_rejected_not_errored() {
+    let Some((base, pool)) = spawn_or_skip("over_cap_reserve_is_rejected_not_errored").await else {
+        return;
+    };
+    let raw = format!("sk-{}", Uuid::new_v4());
+    let (account_id, key_id) = seed_key(&pool, 100, &raw, false).await;
+    let c = client();
+    let r = post(
+        &c,
+        format!("{base}/authz/v1/reserve"),
+        json!({"account_id": account_id, "key_id": key_id, "max_tokens": 999}),
+        Some(CLIENT_TOKEN),
+    )
+    .await;
+    assert_eq!(r.status(), 200, "budget refusal is an authoritative 200");
+    let body: Value = r.json().await.unwrap();
+    assert!(body["reservation_id"].is_null());
+    assert_eq!(body["rejected"]["kind"], "insufficient_quota");
+    assert_eq!(body["rejected"]["available"], 100);
+}
+
+#[tokio::test]
+async fn deactivated_account_resolves_as_invalid_no_clue() {
+    let Some((base, pool)) = spawn_or_skip("deactivated_account_resolves_as_invalid_no_clue").await
+    else {
+        return;
+    };
+    let raw = format!("sk-{}", Uuid::new_v4());
+    seed_key(&pool, 1000, &raw, true).await; // deactivated
+    let c = client();
+    let r = post(
+        &c,
+        format!("{base}/authz/v1/resolve"),
+        json!({"api_key": raw}),
+        Some(CLIENT_TOKEN),
+    )
+    .await;
+    // Indistinguishable from an unknown key.
+    assert_eq!(r.status(), 401);
+    let body: Value = r.json().await.unwrap();
+    assert_eq!(body["error"]["code"], "invalid_api_key");
+}
+
+#[tokio::test]
+async fn missing_client_auth_is_401_before_db() {
+    let Some((base, pool)) = spawn_or_skip("missing_client_auth_is_401_before_db").await else {
+        return;
+    };
+    let raw = format!("sk-{}", Uuid::new_v4());
+    seed_key(&pool, 1000, &raw, false).await;
+    let c = client();
+    // No bearer → rejected by client_auth.
+    let r = post(
+        &c,
+        format!("{base}/authz/v1/resolve"),
+        json!({"api_key": raw}),
+        None,
+    )
+    .await;
+    assert_eq!(r.status(), 401);
+    // Wrong bearer → also rejected.
+    let r = post(
+        &c,
+        format!("{base}/authz/v1/resolve"),
+        json!({"api_key": raw}),
+        Some("wrong"),
+    )
+    .await;
+    assert_eq!(r.status(), 401);
+}

crates/helexa-upstream/tests/ledger_pg.rs

@@ -0,0 +1,204 @@
+//! Integration tests for the allocation ledger against a real PostgreSQL.
+//!
+//! Gated on `UPSTREAM_TEST_DATABASE_URL` — when unset (CI's generic runner,
+//! local builds without a DB), every test logs a skip and returns, so
+//! `cargo test --workspace` stays green without Postgres. Point the env var
+//! at a throwaway database to exercise the no-overshoot guarantee and
+//! settle/release idempotency:
+//!
+//!   UPSTREAM_TEST_DATABASE_URL=postgres://helexa:helexa@localhost/helexa_test \
+//!     cargo test -p helexa-upstream --test ledger_pg
+
+use helexa_upstream::db::connect_and_migrate;
+use helexa_upstream::ledger::{self, LedgerError};
+use sqlx::Executor;
+use sqlx::Row;
+use sqlx::postgres::PgPool;
+use uuid::Uuid;
+
+/// Returns a migrated pool, or `None` (with a skip log) when the env var is
+/// unset.
+async fn pool_or_skip(test: &str) -> Option<PgPool> {
+    let Ok(url) = std::env::var("UPSTREAM_TEST_DATABASE_URL") else {
+        eprintln!("skipping {test}: UPSTREAM_TEST_DATABASE_URL not set");
+        return None;
+    };
+    Some(
+        connect_and_migrate(&url, 16)
+            .await
+            .expect("connect + migrate"),
+    )
+}
+
+/// Seed a verified user + account (with `total` allocation) + an active key
+/// (percent=100 so the account cap binds). Returns (account_id, key_id).
+async fn seed(pool: &PgPool, total: i64) -> (Uuid, Uuid) {
+    let user_id: Uuid = pool
+        .fetch_one(
+            sqlx::query(
+                "INSERT INTO users (email, password_hash, email_verified) \
+                 VALUES ($1, 'x', true) RETURNING id",
+            )
+            .bind(format!("u-{}@test.local", Uuid::new_v4())),
+        )
+        .await
+        .unwrap()
+        .get("id");
+    let account_id: Uuid = pool
+        .fetch_one(
+            sqlx::query(
+                "INSERT INTO accounts (owner_user_id, allocation_total) \
+                 VALUES ($1, $2) RETURNING id",
+            )
+            .bind(user_id)
+            .bind(total),
+        )
+        .await
+        .unwrap()
+        .get("id");
+    let key_id: Uuid = pool
+        .fetch_one(
+            sqlx::query(
+                "INSERT INTO api_keys (account_id, key_hash, key_prefix, limit_kind, limit_value) \
+                 VALUES ($1, $2, 'sk-test', 'percent', 100) RETURNING id",
+            )
+            .bind(account_id)
+            .bind(Uuid::new_v4().as_bytes().to_vec()),
+        )
+        .await
+        .unwrap()
+        .get("id");
+    (account_id, key_id)
+}
+
+async fn account_cols(pool: &PgPool, account_id: Uuid) -> (i64, i64) {
+    let row = pool
+        .fetch_one(
+            sqlx::query("SELECT allocation_spent, allocation_reserved FROM accounts WHERE id = $1")
+                .bind(account_id),
+        )
+        .await
+        .unwrap();
+    (row.get("allocation_spent"), row.get("allocation_reserved"))
+}
+
+#[tokio::test]
+async fn concurrent_reserves_never_overshoot() {
+    let Some(pool) = pool_or_skip("concurrent_reserves_never_overshoot").await else {
+        return;
+    };
+    // Allocation admits exactly 5 reservations of 100 (cap 500).
+    let (account_id, key_id) = seed(&pool, 500).await;
+
+    let mut handles = Vec::new();
+    for _ in 0..20 {
+        let pool = pool.clone();
+        handles.push(tokio::spawn(async move {
+            ledger::reserve(&pool, account_id, key_id, 100).await
+        }));
+    }
+    let mut ok = 0;
+    let mut quota = 0;
+    for h in handles {
+        match h.await.unwrap() {
+            Ok(_) => ok += 1,
+            Err(LedgerError::InsufficientQuota { .. }) => quota += 1,
+            Err(e) => panic!("unexpected error: {e}"),
+        }
+    }
+    assert_eq!(ok, 5, "exactly 5 reserves of 100 fit in a 500 allocation");
+    assert_eq!(quota, 15);
+
+    let (spent, reserved) = account_cols(&pool, account_id).await;
+    assert_eq!(spent, 0);
+    assert_eq!(reserved, 500, "reserved exactly the cap, never over");
+}
+
+#[tokio::test]
+async fn settle_is_idempotent_and_reconciles_spend() {
+    let Some(pool) = pool_or_skip("settle_is_idempotent_and_reconciles_spend").await else {
+        return;
+    };
+    let (account_id, key_id) = seed(&pool, 1000).await;
+    let rid = ledger::reserve(&pool, account_id, key_id, 400)
+        .await
+        .unwrap();
+
+    // Settle actual=150 (< reserved 400): spent=150, reserved back to 0.
+    ledger::settle(&pool, rid, 150).await.unwrap();
+    let (spent, reserved) = account_cols(&pool, account_id).await;
+    assert_eq!((spent, reserved), (150, 0));
+
+    // Second settle is a no-op.
+    ledger::settle(&pool, rid, 999).await.unwrap();
+    let (spent2, reserved2) = account_cols(&pool, account_id).await;
+    assert_eq!((spent2, reserved2), (150, 0), "settle is idempotent");
+}
+
+#[tokio::test]
+async fn release_returns_reservation_and_is_idempotent() {
+    let Some(pool) = pool_or_skip("release_returns_reservation_and_is_idempotent").await else {
+        return;
+    };
+    let (account_id, key_id) = seed(&pool, 1000).await;
+    let rid = ledger::reserve(&pool, account_id, key_id, 300)
+        .await
+        .unwrap();
+    assert_eq!(account_cols(&pool, account_id).await, (0, 300));
+
+    ledger::release(&pool, rid).await.unwrap();
+    assert_eq!(account_cols(&pool, account_id).await, (0, 0));
+    // Idempotent; settle-after-release also a no-op.
+    ledger::release(&pool, rid).await.unwrap();
+    ledger::settle(&pool, rid, 100).await.unwrap();
+    assert_eq!(account_cols(&pool, account_id).await, (0, 0));
+}
+
+#[tokio::test]
+async fn hardcap_key_subcap_binds_below_account() {
+    let Some(pool) = pool_or_skip("hardcap_key_subcap_binds_below_account").await else {
+        return;
+    };
+    // Account has 1000 but the key is hard-capped at 200.
+    let user_id: Uuid = pool
+        .fetch_one(
+            sqlx::query(
+                "INSERT INTO users (email, password_hash, email_verified) \
+                 VALUES ($1, 'x', true) RETURNING id",
+            )
+            .bind(format!("u-{}@test.local", Uuid::new_v4())),
+        )
+        .await
+        .unwrap()
+        .get("id");
+    let account_id: Uuid = pool
+        .fetch_one(
+            sqlx::query(
+                "INSERT INTO accounts (owner_user_id, allocation_total) VALUES ($1, 1000) RETURNING id",
+            )
+            .bind(user_id),
+        )
+        .await
+        .unwrap()
+        .get("id");
+    let key_id: Uuid = pool
+        .fetch_one(
+            sqlx::query(
+                "INSERT INTO api_keys (account_id, key_hash, key_prefix, limit_kind, limit_value) \
+                 VALUES ($1, $2, 'sk-test', 'hardcap', 200) RETURNING id",
+            )
+            .bind(account_id)
+            .bind(Uuid::new_v4().as_bytes().to_vec()),
+        )
+        .await
+        .unwrap()
+        .get("id");
+
+    ledger::reserve(&pool, account_id, key_id, 200)
+        .await
+        .unwrap();
+    match ledger::reserve(&pool, account_id, key_id, 1).await {
+        Err(LedgerError::InsufficientQuota { available, .. }) => assert_eq!(available, 0),
+        other => panic!("expected InsufficientQuota, got {other:?}"),
+    }
+}

crates/helexa-upstream/tests/served_usage_pg.rs

@@ -0,0 +1,116 @@
+//! Integration test for the served-usage report (#58): the idempotent,
+//! monotonic upsert and the reconcile rollup. Gated on
+//! UPSTREAM_TEST_DATABASE_URL (skips cleanly when unset).
+
+use helexa_upstream::config::{ClientToken, UpstreamConfig};
+use helexa_upstream::db::connect_and_migrate;
+use helexa_upstream::email::EmailSender;
+use helexa_upstream::reconcile::reconcile;
+use helexa_upstream::state::AppState;
+use serde_json::{Value, json};
+use sqlx::Row;
+use sqlx::postgres::PgPool;
+use uuid::Uuid;
+
+const CLIENT_TOKEN: &str = "su-test-token";
+const OPERATOR: &str = "op-su-test";
+
+async fn spawn_or_skip(test: &str) -> Option<(String, PgPool)> {
+    let Ok(url) = std::env::var("UPSTREAM_TEST_DATABASE_URL") else {
+        eprintln!("skipping {test}: UPSTREAM_TEST_DATABASE_URL not set");
+        return None;
+    };
+    let pool = connect_and_migrate(&url, 16).await.expect("migrate");
+    let mut config = UpstreamConfig {
+        server: Default::default(),
+        db: helexa_upstream::config::DbSettings {
+            url,
+            max_connections: 16,
+        },
+        grant: Default::default(),
+        abuse: Default::default(),
+        client_auth: Default::default(),
+        authz: Default::default(),
+        auth: Default::default(),
+        email: Default::default(),
+    };
+    config.client_auth.tokens.push(ClientToken {
+        token: CLIENT_TOKEN.into(),
+        operator_id: OPERATOR.into(),
+    });
+    let email = EmailSender::from_config(&config.email).unwrap();
+    let state = AppState::new(pool.clone(), config, email);
+    let app = helexa_upstream::build_app(state);
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let addr = listener.local_addr().unwrap();
+    tokio::spawn(async move {
+        axum::serve(listener, app).await.unwrap();
+    });
+    Some((format!("http://{addr}"), pool))
+}
+
+async fn report(base: &str, rows: Value) -> u16 {
+    reqwest::Client::new()
+        .post(format!("{base}/authz/v1/served-usage"))
+        .bearer_auth(CLIENT_TOKEN)
+        .json(&json!({ "rows": rows }))
+        .send()
+        .await
+        .unwrap()
+        .status()
+        .as_u16()
+}
+
+async fn stored(pool: &PgPool, account: Uuid, key: Uuid) -> i64 {
+    sqlx::query(
+        "SELECT served_tokens FROM served_usage WHERE operator_id = $1 AND account_id = $2 AND key_id = $3",
+    )
+    .bind(OPERATOR)
+    .bind(account)
+    .bind(key)
+    .fetch_one(pool)
+    .await
+    .unwrap()
+    .get("served_tokens")
+}
+
+#[tokio::test]
+async fn served_usage_upsert_is_monotonic_and_reconciles() {
+    let Some((base, pool)) = spawn_or_skip("served_usage_upsert_is_monotonic_and_reconciles").await
+    else {
+        return;
+    };
+    let account = Uuid::new_v4();
+    let key = Uuid::new_v4();
+    let period = "2026-06-23";
+    let row = |n: i64| json!([{"account_id": account, "key_id": key, "period": period, "served_tokens": n}]);
+
+    // First report.
+    assert_eq!(report(&base, row(100)).await, 204);
+    assert_eq!(stored(&pool, account, key).await, 100);
+
+    // Re-send a higher absolute value → advances.
+    assert_eq!(report(&base, row(250)).await, 204);
+    assert_eq!(stored(&pool, account, key).await, 250);
+
+    // A lower value (e.g. a restarted cortex) must NOT regress (GREATEST).
+    assert_eq!(report(&base, row(50)).await, 204);
+    assert_eq!(stored(&pool, account, key).await, 250);
+
+    // Re-sending the same value is idempotent.
+    assert_eq!(report(&base, row(250)).await, 204);
+    assert_eq!(stored(&pool, account, key).await, 250);
+
+    // Reconcile rolls it up and stamps reconciled_at; a second run is empty.
+    let rollup = reconcile(&pool).await.unwrap();
+    let mine = rollup
+        .iter()
+        .find(|r| r.operator_id == OPERATOR)
+        .expect("operator in rollup");
+    assert!(mine.total_served_tokens >= 250);
+    let again = reconcile(&pool).await.unwrap();
+    assert!(
+        again.iter().all(|r| r.operator_id != OPERATOR),
+        "already reconciled"
+    );
+}

crates/helexa-upstream/tests/web_pg.rs

@@ -0,0 +1,425 @@
+//! Integration tests for the `/web/v1` account API + the silent fingerprint
+//! abuse policy, driving the built app over HTTP against a real Postgres.
+//! Gated on `UPSTREAM_TEST_DATABASE_URL` (skips cleanly when unset).
+
+use helexa_upstream::config::{ClientToken, UpstreamConfig};
+use helexa_upstream::crypto::sha256;
+use helexa_upstream::db::connect_and_migrate;
+use helexa_upstream::email::EmailSender;
+use helexa_upstream::state::AppState;
+use serde_json::{Value, json};
+use sqlx::Executor;
+use sqlx::Row;
+use sqlx::postgres::PgPool;
+
+const CLIENT_TOKEN: &str = "web-test-operator-token";
+
+async fn spawn_or_skip(test: &str) -> Option<(String, PgPool)> {
+    let Ok(url) = std::env::var("UPSTREAM_TEST_DATABASE_URL") else {
+        eprintln!("skipping {test}: UPSTREAM_TEST_DATABASE_URL not set");
+        return None;
+    };
+    let pool = connect_and_migrate(&url, 16).await.expect("migrate");
+    let mut config = UpstreamConfig {
+        server: Default::default(),
+        db: helexa_upstream::config::DbSettings {
+            url,
+            max_connections: 16,
+        },
+        grant: Default::default(),
+        abuse: Default::default(),
+        client_auth: Default::default(),
+        authz: Default::default(),
+        auth: Default::default(),
+        email: Default::default(), // Log transport
+    };
+    config.client_auth.tokens.push(ClientToken {
+        token: CLIENT_TOKEN.into(),
+        operator_id: "op-web".into(),
+    });
+    let email = EmailSender::from_config(&config.email).unwrap();
+    let state = AppState::new(pool.clone(), config, email);
+    let app = helexa_upstream::build_app(state);
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let addr = listener.local_addr().unwrap();
+    tokio::spawn(async move {
+        axum::serve(listener, app).await.unwrap();
+    });
+    Some((format!("http://{addr}"), pool))
+}
+
+fn unique_email() -> String {
+    format!("u-{}@test.local", uuid::Uuid::new_v4())
+}
+
+async fn post(url: String, body: Value, bearer: Option<&str>) -> reqwest::Response {
+    let c = reqwest::Client::new();
+    let mut req = c.post(url).json(&body);
+    if let Some(b) = bearer {
+        req = req.bearer_auth(b);
+    }
+    req.send().await.unwrap()
+}
+
+#[tokio::test]
+async fn verify_endpoint_consumes_token_once() {
+    let Some((base, pool)) = spawn_or_skip("verify_endpoint_consumes_token_once").await else {
+        return;
+    };
+    let email = unique_email();
+    // Register, then mint a verify token directly (the raw token is only in
+    // the email; here we insert a known one to drive the endpoint).
+    assert_eq!(
+        post(
+            format!("{base}/web/v1/register"),
+            json!({"email": email, "password": "password123"}),
+            None
+        )
+        .await
+        .status(),
+        202
+    );
+    let user_id: uuid::Uuid = pool
+        .fetch_one(sqlx::query("SELECT id FROM users WHERE email = $1").bind(&email))
+        .await
+        .unwrap()
+        .get("id");
+    let raw = "verify-raw-token-xyz";
+    pool.execute(
+        sqlx::query(
+            "INSERT INTO email_tokens (token_hash, user_id, kind, expires_at) \
+             VALUES ($1, $2, 'verify', now() + interval '1 hour')",
+        )
+        .bind(sha256(raw))
+        .bind(user_id),
+    )
+    .await
+    .unwrap();
+
+    assert_eq!(
+        post(format!("{base}/web/v1/verify"), json!({"token": raw}), None)
+            .await
+            .status(),
+        200
+    );
+    // Consumed → second attempt fails.
+    assert_eq!(
+        post(format!("{base}/web/v1/verify"), json!({"token": raw}), None)
+            .await
+            .status(),
+        400
+    );
+
+    let verified: bool = pool
+        .fetch_one(sqlx::query("SELECT email_verified FROM users WHERE id = $1").bind(user_id))
+        .await
+        .unwrap()
+        .get("email_verified");
+    assert!(verified);
+}
+
+#[tokio::test]
+async fn account_lifecycle_and_key_resolves_then_archives() {
+    let Some((base, pool)) =
+        spawn_or_skip("account_lifecycle_and_key_resolves_then_archives").await
+    else {
+        return;
+    };
+    let email = unique_email();
+    post(
+        format!("{base}/web/v1/register"),
+        json!({"email": email, "password": "password123"}),
+        None,
+    )
+    .await;
+    // Bypass the email step for the login/key portion.
+    pool.execute(
+        sqlx::query("UPDATE users SET email_verified = true WHERE email = $1").bind(&email),
+    )
+    .await
+    .unwrap();
+
+    // login → session JWT
+    let r = post(
+        format!("{base}/web/v1/login"),
+        json!({"email": email, "password": "password123"}),
+        None,
+    )
+    .await;
+    assert_eq!(r.status(), 200);
+    let token = r.json::<Value>().await.unwrap()["token"]
+        .as_str()
+        .unwrap()
+        .to_string();
+
+    // create key (raw shown once)
+    let r = post(
+        format!("{base}/web/v1/keys"),
+        json!({"label": "laptop"}),
+        Some(&token),
+    )
+    .await;
+    assert_eq!(r.status(), 201);
+    let body: Value = r.json().await.unwrap();
+    let raw_key = body["key"].as_str().unwrap().to_string();
+    let key_id = body["id"].as_str().unwrap().to_string();
+    assert!(raw_key.starts_with("sk-helexa-"));
+
+    // account balance reflects the free grant
+    let r = reqwest::Client::new()
+        .get(format!("{base}/web/v1/account"))
+        .bearer_auth(&token)
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(
+        r.json::<Value>().await.unwrap()["allocation_total"],
+        1_000_000
+    );
+
+    // list keys shows the prefix, never the raw secret
+    let r = reqwest::Client::new()
+        .get(format!("{base}/web/v1/keys"))
+        .bearer_auth(&token)
+        .send()
+        .await
+        .unwrap();
+    let listed = r.json::<Value>().await.unwrap();
+    let k = &listed["keys"][0];
+    assert_eq!(k["id"], key_id);
+    assert!(k.get("key").is_none(), "raw secret never listed");
+    assert!(k["prefix"].as_str().unwrap().starts_with("sk-helexa-"));
+
+    // the key authorizes at the authz surface
+    let r = post(
+        format!("{base}/authz/v1/resolve"),
+        json!({"api_key": raw_key}),
+        Some(CLIENT_TOKEN),
+    )
+    .await;
+    assert_eq!(r.status(), 200);
+
+    // archive → the key no longer resolves
+    let r = post(
+        format!("{base}/web/v1/keys/{key_id}/archive"),
+        json!({}),
+        Some(&token),
+    )
+    .await;
+    assert_eq!(r.status(), 204);
+    let r = post(
+        format!("{base}/authz/v1/resolve"),
+        json!({"api_key": raw_key}),
+        Some(CLIENT_TOKEN),
+    )
+    .await;
+    assert_eq!(r.status(), 401);
+}
+
+#[tokio::test]
+async fn fingerprint_abuse_silently_deactivates_all_no_clue() {
+    let Some((base, pool)) =
+        spawn_or_skip("fingerprint_abuse_silently_deactivates_all_no_clue").await
+    else {
+        return;
+    };
+    let fp = format!("fp-{}", uuid::Uuid::new_v4());
+
+    // 5 registrations sharing one fingerprint — every one returns a normal 202.
+    let mut emails = Vec::new();
+    for _ in 0..5 {
+        let email = unique_email();
+        let r = post(
+            format!("{base}/web/v1/register"),
+            json!({"email": email, "password": "password123", "fingerprint": fp}),
+            None,
+        )
+        .await;
+        assert_eq!(r.status(), 202, "registration always looks successful");
+        emails.push(email);
+    }
+
+    // Silent effect: all 5 accounts are deactivated + flagged.
+    let (deactivated, flagged): (i64, i64) = {
+        let row = pool
+            .fetch_one(
+                sqlx::query(
+                    "SELECT \
+                   count(*) FILTER (WHERE a.status = 'deactivated') AS d, \
+                   count(*) FILTER (WHERE a.fingerprint_flagged) AS f \
+                 FROM accounts a JOIN users u ON u.id = a.owner_user_id \
+                 WHERE u.registration_fingerprint = $1",
+                )
+                .bind(&fp),
+            )
+            .await
+            .unwrap();
+        (row.get("d"), row.get("f"))
+    };
+    assert_eq!(deactivated, 5, "all sharing accounts silently deactivated");
+    assert_eq!(flagged, 5);
+
+    // No clue at the authz surface: a key on a deactivated account resolves
+    // as an ordinary 401, indistinguishable from an unknown key.
+    let acct: uuid::Uuid = pool
+        .fetch_one(
+            sqlx::query(
+                "SELECT a.id FROM accounts a JOIN users u ON u.id = a.owner_user_id \
+                 WHERE u.registration_fingerprint = $1 LIMIT 1",
+            )
+            .bind(&fp),
+        )
+        .await
+        .unwrap()
+        .get("id");
+    let raw = "sk-helexa-deactivated-probe";
+    pool.execute(
+        sqlx::query(
+            "INSERT INTO api_keys (account_id, key_hash, key_prefix) VALUES ($1, $2, 'sk-helexa-')",
+        )
+        .bind(acct)
+        .bind(sha256(raw)),
+    )
+    .await
+    .unwrap();
+    let r = post(
+        format!("{base}/authz/v1/resolve"),
+        json!({"api_key": raw}),
+        Some(CLIENT_TOKEN),
+    )
+    .await;
+    assert_eq!(
+        r.status(),
+        401,
+        "deactivated account's key looks like any invalid key"
+    );
+}
+
+#[tokio::test]
+async fn topup_redeem_raises_allocation_single_use() {
+    let Some((base, pool)) = spawn_or_skip("topup_redeem_raises_allocation_single_use").await
+    else {
+        return;
+    };
+    let email = unique_email();
+    post(
+        format!("{base}/web/v1/register"),
+        json!({"email": email, "password": "password123"}),
+        None,
+    )
+    .await;
+    pool.execute(
+        sqlx::query("UPDATE users SET email_verified = true WHERE email = $1").bind(&email),
+    )
+    .await
+    .unwrap();
+    let token = post(
+        format!("{base}/web/v1/login"),
+        json!({"email": email, "password": "password123"}),
+        None,
+    )
+    .await
+    .json::<Value>()
+    .await
+    .unwrap()["token"]
+        .as_str()
+        .unwrap()
+        .to_string();
+
+    // Mint a code worth 500_000 (mint path used by the CLI/faucet).
+    let codes = helexa_upstream::topup::mint(&pool, 500_000, 1, Some("test"))
+        .await
+        .unwrap();
+    let code = &codes[0];
+
+    // Redeem → allocation_total rises from the 1_000_000 free grant.
+    let r = post(
+        format!("{base}/web/v1/redeem"),
+        json!({"code": code}),
+        Some(&token),
+    )
+    .await;
+    assert_eq!(r.status(), 200);
+    assert_eq!(
+        r.json::<Value>().await.unwrap()["allocation_total"],
+        1_500_000
+    );
+
+    // Single-use: a second redemption fails generically (no oracle).
+    let r = post(
+        format!("{base}/web/v1/redeem"),
+        json!({"code": code}),
+        Some(&token),
+    )
+    .await;
+    assert_eq!(r.status(), 400);
+
+    // Unknown code: same generic 400.
+    let r = post(
+        format!("{base}/web/v1/redeem"),
+        json!({"code": "helexa-topup-does-not-exist"}),
+        Some(&token),
+    )
+    .await;
+    assert_eq!(r.status(), 400);
+}
+
+#[tokio::test]
+async fn topup_concurrent_double_redeem_one_winner() {
+    let Some((base, pool)) = spawn_or_skip("topup_concurrent_double_redeem_one_winner").await
+    else {
+        return;
+    };
+    // Two verified accounts.
+    let mut tokens = Vec::new();
+    for _ in 0..2 {
+        let email = unique_email();
+        post(
+            format!("{base}/web/v1/register"),
+            json!({"email": email, "password": "password123"}),
+            None,
+        )
+        .await;
+        pool.execute(
+            sqlx::query("UPDATE users SET email_verified = true WHERE email = $1").bind(&email),
+        )
+        .await
+        .unwrap();
+        let t = post(
+            format!("{base}/web/v1/login"),
+            json!({"email": email, "password": "password123"}),
+            None,
+        )
+        .await
+        .json::<Value>()
+        .await
+        .unwrap()["token"]
+            .as_str()
+            .unwrap()
+            .to_string();
+        tokens.push(t);
+    }
+    let code = helexa_upstream::topup::mint(&pool, 100, 1, None)
+        .await
+        .unwrap()
+        .remove(0);
+
+    // Both accounts race to redeem the same code; exactly one wins.
+    let (a, b) = tokio::join!(
+        post(
+            format!("{base}/web/v1/redeem"),
+            json!({"code": code}),
+            Some(&tokens[0])
+        ),
+        post(
+            format!("{base}/web/v1/redeem"),
+            json!({"code": code}),
+            Some(&tokens[1])
+        ),
+    );
+    let wins = [a.status(), b.status()]
+        .iter()
+        .filter(|s| s.as_u16() == 200)
+        .count();
+    assert_eq!(wins, 1, "exactly one redemption wins the single-use code");
+}

helexa-upstream.example.toml

@@ -0,0 +1,52 @@
+# helexa-upstream.example.toml — mesh-level account/authorization authority
+#
+# Copy to helexa-upstream.toml and adjust. Env overrides use the UPSTREAM_
+# prefix with __ separators, e.g. UPSTREAM_DB__URL=postgres://...
+
+[server]
+# Plaintext listener; edge nginx terminates TLS (consistent with the stack).
+listen = "0.0.0.0:8090"
+
+[db]
+# PostgreSQL connection URL. Required.
+url = "postgres://helexa:helexa@localhost/helexa_upstream"
+# max_connections = 16
+
+[grant]
+# Flat free token grant every email-verified account receives (the floor of
+# the hybrid allocation; single-use top-up codes extend it).
+# free_token_grant = 1000000
+
+[abuse]
+# When this many accounts share one registration fingerprint, all are
+# silently deactivated (no notice to the user).
+# fingerprint_account_threshold = 5
+
+# -- Client auth: credentials operators' cortexes present to /authz/v1.
+# Each token maps to an operator_id (served-usage attribution). When no
+# tokens are configured the authz surface is OPEN (dev only). Distinct from
+# end-user API keys, which ride inside the resolve request body.
+# [[client_auth.tokens]]
+# token = "replace-with-a-strong-shared-secret"
+# operator_id = "lair-cafe"
+
+[authz]
+# Open reservations older than this are swept (released), self-healing a
+# reservation whose settle/release from a cortex was lost.
+# reservation_ttl_secs = 120
+# sweep_interval_secs = 60
+
+[auth]
+# HMAC secret for signing web-session JWTs. MUST be overridden in prod via
+# UPSTREAM_AUTH__JWT_SECRET; the built-in default is dev-only.
+# jwt_secret = "change-me"
+# session_ttl_secs = 604800        # 7 days
+# email_token_ttl_secs = 86400     # 24 hours
+# Frontend base URL used to build verify/reset links in emails.
+app_base_url = "https://helexa.ai"
+
+[email]
+# "log" (dev: logs the link) or "smtp".
+provider = "log"
+# smtp_url = "smtp://user:pass@smtp.example.com:587"
+from_addr = "helexa <no-reply@helexa.ai>"

helexa.ai/package.json

@@ -8,7 +8,10 @@
     "build": "tsc -b && vite build",
     "preview": "vite preview",
     "lint": "eslint .",
-    "typecheck": "tsc -b"
+    "typecheck": "tsc -b",
+    "i18n:check": "node ./scripts/check-i18n-keys.mjs",
+    "i18n:meta": "node ./scripts/check-i18n-metadata.mjs",
+    "i18n:lang-labels": "node ./scripts/check-i18n-lang-labels.mjs"
   },
   "dependencies": {
     "@fingerprintjs/fingerprintjs": "^4.6.2",

helexa.ai/scripts/check-i18n-keys.mjs

@@ -0,0 +1,332 @@
+#!/usr/bin/env node
+
+/**
+ * Simple i18n key consistency checker.
+ *
+ * Compares translation JSONs for all configured languages against the English
+ * baseline, for each namespace (common, home, chat).
+ *
+ * Exit codes:
+ *  - 0: all good
+ *  - 1: inconsistencies found or unexpected error
+ */
+
+import fs from "fs";
+import path from "path";
+import url from "url";
+
+// Adjust these if your i18n structure changes.
+const ROOT = path.resolve(
+  path.dirname(url.fileURLToPath(import.meta.url)),
+  "..",
+);
+const RESOURCES_DIR = path.join(ROOT, "src", "i18n", "resources");
+
+// Namespaces to validate.
+const NAMESPACES = ["common", "mission", "chat"];
+
+// Languages to validate should track SUPPORTED_LANGUAGES in src/i18n/languages.ts.
+// NOTE: This list is intentionally narrower than SUPPORTED_LANGUAGES and does not
+// enforce that every supported language has wired resources. That enforcement is
+// implemented further below by checking the i18n index.
+const LANGUAGES = [
+  "bg",
+  "de",
+  "el",
+  "en",
+  "es",
+  "et",
+  "fr",
+  "it",
+  "pt",
+  "ro",
+  "ru",
+];
+
+function readJson(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Failed to read/parse JSON at ${filePath}: ${err.message}`);
+  }
+}
+
+/**
+ * Recursively walk an object and collect all key paths using dot-notation.
+ * Arrays are traversed structurally but their indexes are not part of the key path
+ * (we only care that the shape exists, not array lengths).
+ */
+function collectKeyPaths(obj, prefix = "") {
+  const keys = new Set();
+
+  if (obj === null || obj === undefined) {
+    return keys;
+  }
+
+  if (typeof obj !== "object") {
+    if (prefix) keys.add(prefix);
+    return keys;
+  }
+
+  // If this is an array, walk its elements but don't add indices to the path.
+  if (Array.isArray(obj)) {
+    obj.forEach((item) => {
+      for (const childKey of collectKeyPaths(item, prefix)) {
+        keys.add(childKey);
+      }
+    });
+    return keys;
+  }
+
+  // Plain object
+  for (const [k, v] of Object.entries(obj)) {
+    const nextPrefix = prefix ? `${prefix}.${k}` : k;
+    if (v !== null && typeof v === "object") {
+      for (const childKey of collectKeyPaths(v, nextPrefix)) {
+        keys.add(childKey);
+      }
+    } else {
+      keys.add(nextPrefix);
+    }
+  }
+
+  return keys;
+}
+
+function diffKeys(baseSet, targetSet) {
+  const missing = [];
+  const extra = [];
+
+  for (const k of baseSet) {
+    if (!targetSet.has(k)) missing.push(k);
+  }
+
+  for (const k of targetSet) {
+    if (!baseSet.has(k)) extra.push(k);
+  }
+
+  missing.sort();
+  extra.sort();
+
+  return { missing, extra };
+}
+
+function logHeader(title) {
+  // Simple console formatting without external deps.
+  console.log("\n" + "=".repeat(title.length));
+  console.log(title);
+  console.log("=".repeat(title.length));
+}
+
+function main() {
+  let hadIssues = false;
+
+  console.log("helexa.ai i18n key consistency check");
+  console.log(`Root: ${ROOT}`);
+  console.log(`Resources dir: ${RESOURCES_DIR}`);
+  console.log(`Languages: ${LANGUAGES.join(", ")}`);
+  console.log(`Namespaces: ${NAMESPACES.join(", ")}`);
+
+  // --- Wiring check: ensure each SUPPORTED_LANGUAGES entry has resources registered ---
+  //
+  // This prevents cases where a language is:
+  //   - present in LanguageCode and SUPPORTED_LANGUAGES
+  //   - has translation JSONs under src/i18n/resources/<code>/
+  // but is *not* wired into the i18n `resources` object (and thus silently
+  // falls back to English at runtime).
+  try {
+    const languagesTs = fs.readFileSync(
+      path.join(ROOT, "src", "i18n", "languages.ts"),
+      "utf8",
+    );
+    const i18nIndexTs = fs.readFileSync(
+      path.join(ROOT, "src", "i18n", "index.ts"),
+      "utf8",
+    );
+
+    // Parse SUPPORTED_LANGUAGES from languages.ts
+    const marker = "export const SUPPORTED_LANGUAGES";
+    const start = languagesTs.indexOf(marker);
+    if (start === -1) {
+      throw new Error("Could not find `SUPPORTED_LANGUAGES` in languages.ts");
+    }
+    const after = languagesTs.slice(start);
+    const bracketIndex = after.indexOf("[");
+    const closingIndex = after.indexOf("];");
+    if (bracketIndex === -1 || closingIndex === -1) {
+      throw new Error("Malformed SUPPORTED_LANGUAGES array");
+    }
+    const arraySlice = after.slice(bracketIndex + 1, closingIndex);
+    const supportedFromTs = new Set();
+    const codeRegex = /"([^"]+)"/g;
+    let m;
+    while ((m = codeRegex.exec(arraySlice)) !== null) {
+      supportedFromTs.add(m[1]);
+    }
+
+    console.log(
+      `SUPPORTED_LANGUAGES from TS for wiring check: ${Array.from(
+        supportedFromTs,
+      )
+        .sort()
+        .join(", ")}`,
+    );
+
+    // Languages that are intentionally "future" and may not yet have
+    // resources wired in. Keep them out of the hard failure path so
+    // CI does not break while their translations are still pending.
+    const FUTURE_LANGUAGES = new Set(["ig", "om", "so", "ti", "wo"]);
+
+    // Parse i18n resources object keys from index.ts.
+    // We look for a block like:
+    //   const resources: Resource = {
+    //     en: { ... },
+    //     fr: { ... },
+    //   };
+    const resourcesMarker = "const resources: Resource = {";
+    const resStart = i18nIndexTs.indexOf(resourcesMarker);
+    if (resStart === -1) {
+      throw new Error("Could not find `const resources: Resource` in index.ts");
+    }
+    const resAfter = i18nIndexTs.slice(resStart + resourcesMarker.length);
+    const resEndIndex = resAfter.indexOf("};");
+    if (resEndIndex === -1) {
+      throw new Error("Malformed resources object in index.ts");
+    }
+    const resourcesBlock = resAfter.slice(0, resEndIndex);
+
+    // Extract top-level language keys: lines starting with two spaces then <code>:
+    // Example: "  en: {" or "  fr: {"
+    const wiredLangs = new Set();
+    const lineRegex = /^\s*([a-z]{2}):\s*{\s*$/gm;
+    let lm;
+    while ((lm = lineRegex.exec(resourcesBlock)) !== null) {
+      wiredLangs.add(lm[1]);
+    }
+
+    console.log(
+      `Languages wired in i18n resources: ${Array.from(wiredLangs)
+        .sort()
+        .join(", ")}`,
+    );
+
+    // Now compare SUPPORTED_LANGUAGES vs wired resources.
+    const missingWiring = [];
+    for (const code of supportedFromTs) {
+      if (FUTURE_LANGUAGES.has(code)) {
+        // These are explicitly allowed to be missing until their
+        // translations and wiring land.
+        continue;
+      }
+      if (!wiredLangs.has(code)) {
+        missingWiring.push(code);
+      }
+    }
+
+    if (missingWiring.length > 0) {
+      hadIssues = true;
+      console.error(
+        "\nERROR: Some SUPPORTED_LANGUAGES codes are not wired into the i18n `resources` object in src/i18n/index.ts:",
+      );
+      for (const code of missingWiring.sort()) {
+        console.error(`  - ${code}`);
+      }
+      console.error(
+        "These languages will silently fall back to English at runtime. Ensure that:",
+      );
+      console.error(
+        "  1) ./resources/<code>/{common,home,chat}.json exist, and",
+      );
+      console.error(
+        "  2) They are imported and registered in the `resources` object.",
+      );
+      console.error("");
+    } else {
+      console.log(
+        "OK: Every SUPPORTED_LANGUAGES entry (excluding future languages) is wired into the i18n resources object.",
+      );
+    }
+  } catch (err) {
+    hadIssues = true;
+    console.error(
+      "ERROR: Failed while checking SUPPORTED_LANGUAGES wiring in i18n index:",
+      err.message,
+    );
+  }
+
+  for (const ns of NAMESPACES) {
+    logHeader(`Namespace: ${ns}`);
+
+    const basePath = path.join(RESOURCES_DIR, "en", `${ns}.json`);
+    let baseJson;
+    try {
+      baseJson = readJson(basePath);
+    } catch (err) {
+      console.error(err.message);
+      hadIssues = true;
+      continue;
+    }
+
+    const baseKeys = collectKeyPaths(baseJson);
+    console.log(`Baseline (en) keys: ${baseKeys.size}`);
+
+    for (const lang of LANGUAGES) {
+      if (lang === "en") continue;
+
+      const langPath = path.join(RESOURCES_DIR, lang, `${ns}.json`);
+      if (!fs.existsSync(langPath)) {
+        console.error(`  [${lang}] MISSING file: ${langPath}`);
+        hadIssues = true;
+        continue;
+      }
+
+      let langJson;
+      try {
+        langJson = readJson(langPath);
+      } catch (err) {
+        console.error(`  [${lang}] ${err.message}`);
+        hadIssues = true;
+        continue;
+      }
+
+      const langKeys = collectKeyPaths(langJson);
+      const { missing, extra } = diffKeys(baseKeys, langKeys);
+
+      if (missing.length === 0 && extra.length === 0) {
+        console.log(`  [${lang}] OK (keys: ${langKeys.size})`);
+      } else {
+        hadIssues = true;
+        console.log(`  [${lang}] Issues found:`);
+        if (missing.length > 0) {
+          console.log("    Missing keys (present in en, absent here):");
+          for (const k of missing) {
+            console.log(`      - ${k}`);
+          }
+        }
+        if (extra.length > 0) {
+          console.log("    Extra keys (present here, absent in en):");
+          for (const k of extra) {
+            console.log(`      + ${k}`);
+          }
+        }
+      }
+    }
+  }
+
+  console.log("");
+  if (hadIssues) {
+    console.error("i18n check completed with inconsistencies.");
+    process.exitCode = 1;
+  } else {
+    console.log("i18n check completed successfully. All keys are consistent.");
+    process.exitCode = 0;
+  }
+}
+
+try {
+  main();
+} catch (err) {
+  console.error("Unexpected error while running i18n check:", err);
+  process.exitCode = 1;
+}

helexa.ai/scripts/check-i18n-lang-labels.mjs

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+
+/**
+ * helexa.ai i18n language label consistency check
+ *
+ * This script validates that for every supported language code in
+ * `SUPPORTED_LANGUAGES`:
+ *
+ *   1. The English `common.lang` map (`src/i18n/resources/en/common.json`)
+ *      contains a human-readable label at `lang.<code>`.
+ *   2. Optionally (and more leniently), other languages that define a
+ *      `lang` block do not omit supported language codes.
+ *
+ * At minimum, it enforces that the English UI always has labels for all
+ * supported languages, since the header language selector renders
+ * `t("lang.<code>")` using the active language.
+ *
+ * Exit codes:
+ *   - 0: all checks pass
+ *   - 1: one or more inconsistencies found
+ */
+
+import fs from "fs";
+import path from "path";
+import url from "url";
+
+const ROOT = path.resolve(path.dirname(url.fileURLToPath(import.meta.url)), "..");
+const I18N_DIR = path.join(ROOT, "src", "i18n");
+const LANGUAGES_TS = path.join(I18N_DIR, "languages.ts");
+const EN_COMMON_JSON = path.join(I18N_DIR, "resources", "en", "common.json");
+
+/**
+ * Utility: read a file as UTF-8 or throw with a helpful message.
+ */
+function readFileOrDie(filePath) {
+  try {
+    return fs.readFileSync(filePath, "utf8");
+  } catch (err) {
+    throw new Error(`Failed to read ${filePath}: ${err.message}`);
+  }
+}
+
+/**
+ * Parse SUPPORTED_LANGUAGES from languages.ts.
+ *
+ * Expects a definition like:
+ *   export const SUPPORTED_LANGUAGES: LanguageCode[] = [
+ *     "en",
+ *     "bg",
+ *   ];
+ */
+function parseSupportedLanguages(source) {
+  const marker = "export const SUPPORTED_LANGUAGES";
+  const start = source.indexOf(marker);
+  if (start === -1) {
+    throw new Error("Could not find `SUPPORTED_LANGUAGES` in languages.ts");
+  }
+
+  const after = source.slice(start);
+  const bracketIndex = after.indexOf("[");
+  const closingIndex = after.indexOf("];");
+  if (bracketIndex === -1 || closingIndex === -1) {
+    throw new Error("Malformed SUPPORTED_LANGUAGES array");
+  }
+
+  const arraySlice = after.slice(bracketIndex + 1, closingIndex);
+  const codes = new Set();
+  const regex = /"([^"]+)"/g;
+  let m;
+  while ((m = regex.exec(arraySlice)) !== null) {
+    codes.add(m[1]);
+  }
+
+  if (codes.size === 0) {
+    throw new Error("No entries found in SUPPORTED_LANGUAGES");
+  }
+
+  return codes;
+}
+
+/**
+ * Safely read and parse a JSON file.
+ */
+function readJsonOrDie(filePath) {
+  const raw = readFileOrDie(filePath);
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Failed to parse JSON at ${filePath}: ${err.message}`);
+  }
+}
+
+/**
+ * Compute set difference: a \ b
+ */
+function difference(a, b) {
+  const result = new Set();
+  for (const x of a) {
+    if (!b.has(x)) result.add(x);
+  }
+  return result;
+}
+
+/**
+ * Convenience: sorted array from a Set.
+ */
+function toSortedArray(set) {
+  return [...set].sort();
+}
+
+function main() {
+  console.log("helexa.ai i18n language label check");
+  console.log(`Root: ${ROOT}`);
+  console.log(`Languages file: ${LANGUAGES_TS}`);
+  console.log(`English common.json: ${EN_COMMON_JSON}`);
+  console.log("");
+
+  let hadIssues = false;
+
+  // 1) Load SUPPORTED_LANGUAGES
+  let languagesSource;
+  try {
+    languagesSource = readFileOrDie(LANGUAGES_TS);
+  } catch (err) {
+    console.error(err.message);
+    process.exitCode = 1;
+    return;
+  }
+
+  let supportedLanguages;
+  try {
+    supportedLanguages = parseSupportedLanguages(languagesSource);
+    console.log(
+      `SUPPORTED_LANGUAGES (${supportedLanguages.size}): ${toSortedArray(
+        supportedLanguages,
+      ).join(", ")}`,
+    );
+  } catch (err) {
+    console.error(`ERROR: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log("");
+
+  // 2) Load English common.json and extract lang map
+  let enCommon;
+  try {
+    enCommon = readJsonOrDie(EN_COMMON_JSON);
+  } catch (err) {
+    console.error(`ERROR: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const enLangMap = enCommon?.lang ?? {};
+  if (!enLangMap || typeof enLangMap !== "object") {
+    console.error("ERROR: `en/common.json` does not contain a `lang` object.");
+    process.exitCode = 1;
+    return;
+  }
+
+  const enLangKeys = new Set(Object.keys(enLangMap));
+  console.log(
+    `English lang map keys (${enLangKeys.size}): ${toSortedArray(
+      enLangKeys,
+    ).join(", ")}`,
+  );
+  console.log("");
+
+  // 3) Ensure every supported language has a corresponding key in en.lang
+  const missingInEnglish = difference(supportedLanguages, enLangKeys);
+  if (missingInEnglish.size > 0) {
+    hadIssues = true;
+    console.error(
+      "ERROR: The following supported languages are missing labels in `en/common.json` under `lang`:",
+    );
+    for (const code of toSortedArray(missingInEnglish)) {
+      console.error(`  - lang.${code}`);
+    }
+  } else {
+    console.log(
+      "OK: Every supported language has a `lang.<code>` entry in `en/common.json`.",
+    );
+  }
+
+  console.log("");
+
+  // 4) Optional: scan other locales for informational consistency
+  //    (non-fatal, just warnings).
+  const resourcesDir = path.join(I18N_DIR, "resources");
+  let otherLocales = [];
+  try {
+    otherLocales = fs
+      .readdirSync(resourcesDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && d.name !== "en")
+      .map((d) => d.name);
+  } catch (err) {
+    console.warn(
+      `WARN: Could not list locales in ${resourcesDir}: ${err.message}`,
+    );
+  }
+
+  for (const locale of otherLocales) {
+    const filePath = path.join(resourcesDir, locale, "common.json");
+    if (!fs.existsSync(filePath)) continue;
+
+    let localeJson;
+    try {
+      localeJson = readJsonOrDie(filePath);
+    } catch (err) {
+      console.warn(`WARN: Failed to read ${filePath}: ${err.message}`);
+      continue;
+    }
+
+    const langObj = localeJson?.lang;
+    if (!langObj || typeof langObj !== "object") {
+      // Not all locales need to maintain a full lang map; skip silently.
+      continue;
+    }
+
+    const localeKeys = new Set(Object.keys(langObj));
+    const missingHere = difference(supportedLanguages, localeKeys);
+    if (missingHere.size > 0) {
+      console.warn(
+        `WARN: Locale '${locale}' is missing some supported language labels under "lang":`,
+      );
+      for (const code of toSortedArray(missingHere)) {
+        console.warn(`  - lang.${code}`);
+      }
+      console.warn("");
+    }
+  }
+
+  if (hadIssues) {
+    console.error("Language label check completed with inconsistencies.");
+    process.exitCode = 1;
+  } else {
+    console.log("Language label check completed successfully.");
+    process.exitCode = 0;
+  }
+}
+
+try {
+  main();
+} catch (err) {
+  console.error("Unexpected error while running language label check:", err);
+  process.exitCode = 1;
+}

helexa.ai/scripts/check-i18n-metadata.mjs

@@ -0,0 +1,327 @@
+#!/usr/bin/env node
+
+/**
+ * helexa.ai i18n metadata consistency check
+ *
+ * This script validates that:
+ *  - Every `LanguageCode` used in the project appears in `TRANSLATION_PRIORITY`
+ *  - Every `TRANSLATION_PRIORITY` entry refers to a valid `LanguageCode`
+ *  - `REMAINING_LANGUAGES` is a subset of `LanguageCode`
+ *  - `REMAINING_LANGUAGES` is disjoint from `SUPPORTED_LANGUAGES`
+ *
+ * It is intentionally implemented as a standalone Node script (no TypeScript
+ * build step required) and does a very lightweight parse of the TypeScript
+ * source files to avoid pulling in a full TS compiler.
+ *
+ * Exit codes:
+ *  - 0: all checks pass
+ *  - 1: one or more metadata inconsistencies found
+ */
+
+import fs from "fs";
+import path from "path";
+import url from "url";
+
+/**
+ * Resolve project root as the directory containing this script.
+ */
+const ROOT = path.resolve(path.dirname(url.fileURLToPath(import.meta.url)), "..");
+const I18N_DIR = path.join(ROOT, "src", "i18n");
+const LANGUAGES_TS = path.join(I18N_DIR, "languages.ts");
+const PRIORITY_TS = path.join(I18N_DIR, "translation-priority.ts");
+
+function readFileOrDie(filePath) {
+  try {
+    return fs.readFileSync(filePath, "utf8");
+  } catch (err) {
+    console.error(`Failed to read ${filePath}: ${err.message}`);
+    process.exitCode = 1;
+    return "";
+  }
+}
+
+/**
+ * Extract union members from a definition like:
+ *
+ * export type LanguageCode =
+ *   | "en"
+ *   | "bg"
+ *   | "cs";
+ */
+function parseLanguageCodeUnion(source) {
+  const start = source.indexOf("export type LanguageCode");
+  if (start === -1) {
+    throw new Error("Could not find `export type LanguageCode` in languages.ts");
+  }
+
+  const after = source.slice(start);
+  const eqIndex = after.indexOf("=");
+  if (eqIndex === -1) {
+    throw new Error("Malformed LanguageCode definition (no '=')");
+  }
+
+  const unionBlock = after.slice(eqIndex + 1);
+  const semicolonIndex = unionBlock.indexOf(";");
+  const unionSlice = semicolonIndex === -1 ? unionBlock : unionBlock.slice(0, semicolonIndex);
+
+  const codes = new Set();
+  const regex = /\|\s*"([^"]+)"/g;
+  let m;
+  while ((m = regex.exec(unionSlice)) !== null) {
+    codes.add(m[1]);
+  }
+
+  if (codes.size === 0) {
+    throw new Error("No language codes found in LanguageCode union");
+  }
+
+  return codes;
+}
+
+/**
+ * Parse SUPPORTED_LANGUAGES from languages.ts
+ *
+ * export const SUPPORTED_LANGUAGES: LanguageCode[] = [
+ *   "en",
+ *   "bg",
+ * ];
+ */
+function parseSupportedLanguages(source) {
+  const marker = "export const SUPPORTED_LANGUAGES";
+  const start = source.indexOf(marker);
+  if (start === -1) {
+    throw new Error("Could not find `SUPPORTED_LANGUAGES` in languages.ts");
+  }
+
+  const after = source.slice(start);
+  const bracketIndex = after.indexOf("[");
+  const closingIndex = after.indexOf("];");
+  if (bracketIndex === -1 || closingIndex === -1) {
+    throw new Error("Malformed SUPPORTED_LANGUAGES array");
+  }
+
+  const arraySlice = after.slice(bracketIndex + 1, closingIndex);
+  const codes = new Set();
+  const regex = /"([^"]+)"/g;
+  let m;
+  while ((m = regex.exec(arraySlice)) !== null) {
+    codes.add(m[1]);
+  }
+
+  if (codes.size === 0) {
+    throw new Error("No entries found in SUPPORTED_LANGUAGES");
+  }
+
+  return codes;
+}
+
+/**
+ * Parse REMAINING_LANGUAGES from translation-priority.ts
+ *
+ * export const REMAINING_LANGUAGES: LanguageCode[] = [
+ *   "tr",
+ *   "pl",
+ * ];
+ */
+function parseRemainingLanguages(source) {
+  const marker = "export const REMAINING_LANGUAGES";
+  const start = source.indexOf(marker);
+  if (start === -1) {
+    // It's valid for this list to not exist; treat as empty if missing
+    return new Set();
+  }
+
+  const after = source.slice(start);
+  const bracketIndex = after.indexOf("[");
+  const closingIndex = after.indexOf("];");
+  if (bracketIndex === -1 || closingIndex === -1) {
+    throw new Error("Malformed REMAINING_LANGUAGES array");
+  }
+
+  const arraySlice = after.slice(bracketIndex + 1, closingIndex);
+  const codes = new Set();
+  const regex = /"([^"]+)"/g;
+  let m;
+  while ((m = regex.exec(arraySlice)) !== null) {
+    codes.add(m[1]);
+  }
+
+  return codes;
+}
+
+/**
+ * Parse TRANSLATION_PRIORITY entries from translation-priority.ts
+ *
+ * export const TRANSLATION_PRIORITY: TranslationPriorityEntry[] = [
+ *   {
+ *     code: "tr",
+ *     bucket: "high",
+ *     nativeSpeakers: "70–90M",
+ *   },
+ *   ...
+ * ];
+ */
+function parseTranslationPriority(source) {
+  const marker = "export const TRANSLATION_PRIORITY";
+  const start = source.indexOf(marker);
+  if (start === -1) {
+    throw new Error("Could not find `TRANSLATION_PRIORITY` in translation-priority.ts");
+  }
+
+  const after = source.slice(start);
+  const bracketIndex = after.indexOf("[");
+  const closingIndex = after.indexOf("];");
+  if (bracketIndex === -1 || closingIndex === -1) {
+    throw new Error("Malformed TRANSLATION_PRIORITY array");
+  }
+
+  const arraySlice = after.slice(bracketIndex + 1, closingIndex);
+
+  // Simple heuristic: find code: "<value>" inside objects
+  const codes = new Set();
+  const regex = /code:\s*"([^"]+)"/g;
+  let m;
+  while ((m = regex.exec(arraySlice)) !== null) {
+    codes.add(m[1]);
+  }
+
+  if (codes.size === 0) {
+    throw new Error("No `code` entries found in TRANSLATION_PRIORITY");
+  }
+
+  return codes;
+}
+
+function difference(a, b) {
+  const result = new Set();
+  for (const x of a) {
+    if (!b.has(x)) result.add(x);
+  }
+  return result;
+}
+
+function toSortedArray(set) {
+  return [...set].sort();
+}
+
+function main() {
+  console.log("helexa.ai i18n metadata consistency check");
+  console.log(`Root: ${ROOT}`);
+  console.log(`Languages file: ${LANGUAGES_TS}`);
+  console.log(`Priority file: ${PRIORITY_TS}`);
+  console.log("");
+
+  const languagesSource = readFileOrDie(LANGUAGES_TS);
+  const prioritySource = readFileOrDie(PRIORITY_TS);
+
+  let hadIssues = false;
+
+  let languageCodes;
+  let supportedLanguages;
+  let remainingLanguages;
+  let priorityCodes;
+
+  try {
+    languageCodes = parseLanguageCodeUnion(languagesSource);
+    console.log(`LanguageCode entries: ${languageCodes.size}`);
+  } catch (err) {
+    console.error(`ERROR: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    supportedLanguages = parseSupportedLanguages(languagesSource);
+    console.log(`SUPPORTED_LANGUAGES entries: ${supportedLanguages.size}`);
+  } catch (err) {
+    console.error(`ERROR: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    remainingLanguages = parseRemainingLanguages(prioritySource);
+    console.log(`REMAINING_LANGUAGES entries: ${remainingLanguages.size}`);
+  } catch (err) {
+    console.error(`ERROR: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    priorityCodes = parseTranslationPriority(prioritySource);
+    console.log(`TRANSLATION_PRIORITY entries: ${priorityCodes.size}`);
+  } catch (err) {
+    console.error(`ERROR: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log("");
+
+  // 1) Every LanguageCode should have a TRANSLATION_PRIORITY entry
+  const missingInPriority = difference(languageCodes, priorityCodes);
+  if (missingInPriority.size > 0) {
+    hadIssues = true;
+    console.error("ERROR: The following LanguageCode values are missing from TRANSLATION_PRIORITY:");
+    for (const code of toSortedArray(missingInPriority)) {
+      console.error(`  - ${code}`);
+    }
+  } else {
+    console.log("OK: All LanguageCode values are present in TRANSLATION_PRIORITY.");
+  }
+
+  // 2) Every TRANSLATION_PRIORITY code must be a valid LanguageCode
+  const unknownPriorityCodes = difference(priorityCodes, languageCodes);
+  if (unknownPriorityCodes.size > 0) {
+    hadIssues = true;
+    console.error("ERROR: The following TRANSLATION_PRIORITY codes are not present in LanguageCode:");
+    for (const code of toSortedArray(unknownPriorityCodes)) {
+      console.error(`  - ${code}`);
+    }
+  } else {
+    console.log("OK: All TRANSLATION_PRIORITY codes are valid LanguageCode values.");
+  }
+
+  // 3) REMAINING_LANGUAGES must be subset of LanguageCode
+  const remainingNotInLanguageCode = difference(remainingLanguages, languageCodes);
+  if (remainingNotInLanguageCode.size > 0) {
+    hadIssues = true;
+    console.error("ERROR: The following REMAINING_LANGUAGES entries are not in LanguageCode:");
+    for (const code of toSortedArray(remainingNotInLanguageCode)) {
+      console.error(`  - ${code}`);
+    }
+  } else {
+    console.log("OK: All REMAINING_LANGUAGES are valid LanguageCode values.");
+  }
+
+  // 4) REMAINING_LANGUAGES must be disjoint from SUPPORTED_LANGUAGES
+  const remainingThatAreSupported = difference(remainingLanguages, difference(remainingLanguages, supportedLanguages));
+  // Equivalent to intersection(remainingLanguages, supportedLanguages)
+  if (remainingThatAreSupported.size > 0) {
+    hadIssues = true;
+    console.error("ERROR: The following REMAINING_LANGUAGES are already in SUPPORTED_LANGUAGES:");
+    for (const code of toSortedArray(remainingThatAreSupported)) {
+      console.error(`  - ${code}`);
+    }
+  } else {
+    console.log("OK: REMAINING_LANGUAGES does not include any SUPPORTED_LANGUAGES.");
+  }
+
+  console.log("");
+
+  if (hadIssues) {
+    console.error("i18n metadata check completed with inconsistencies.");
+    process.exitCode = 1;
+  } else {
+    console.log("i18n metadata check completed successfully. All metadata is consistent.");
+    process.exitCode = 0;
+  }
+}
+
+try {
+  main();
+} catch (err) {
+  console.error("Unexpected error while running i18n metadata check:", err);
+  process.exitCode = 1;
+}

helexa.ai/src/App.css

@@ -0,0 +1,411 @@
+:root {
+    --color-bg: #f5f7fb;
+    --color-bg-elevated: #ffffff;
+    --color-bg-subtle: #eef1f7;
+    --color-border-subtle: rgba(15, 23, 42, 0.12);
+    --color-text: #020617;
+    --color-text-muted: #64748b;
+    --color-accent: #22d3ee;
+    --color-accent-hot: #ec4899;
+    --color-accent-soft: rgba(34, 211, 238, 0.12);
+    --color-navbar-bg: rgba(255, 255, 255, 0.85);
+    --color-footer-bg: rgba(255, 255, 255, 0.9);
+    --shadow-soft: 0 18px 45px rgba(15, 23, 42, 0.08);
+    --transition-fast: 150ms ease-out;
+}
+
+/* Dark theme overrides, driven by ThemeProvider via [data-theme] */
+:root[data-theme="dark"] {
+    --color-bg: #000618;
+    --color-bg-elevated: #020617;
+    --color-bg-subtle: #020617;
+    --color-border-subtle: rgba(148, 163, 184, 0.24);
+    --color-text: #e2e8f0;
+    --color-text-muted: #cbd5f5;
+    --color-accent: #22d3ee;
+    --color-accent-soft: rgba(34, 211, 238, 0.18);
+    --color-navbar-bg: rgba(2, 6, 23, 0.92);
+    --color-footer-bg: rgba(2, 6, 23, 0.96);
+    --shadow-soft: 0 22px 55px rgba(15, 23, 42, 0.8);
+}
+
+/* Global base styles */
+
+html,
+body,
+#root {
+    height: 100%;
+}
+
+body {
+    margin: 0;
+    font-family:
+        system-ui,
+        -apple-system,
+        BlinkMacSystemFont,
+        "SF Pro Text",
+        "Segoe UI",
+        sans-serif;
+    background-color: var(--color-bg);
+    color: var(--color-text);
+    -webkit-font-smoothing: antialiased;
+    text-rendering: optimizeLegibility;
+}
+
+/* Basic RTL reset: when the root document is RTL, ensure logical direction */
+html[dir="rtl"] body {
+    direction: rtl;
+}
+
+.app-root {
+    min-height: 100vh;
+    background-color: var(--color-bg);
+    color: var(--color-text);
+    transition:
+        background-color var(--transition-fast),
+        color var(--transition-fast);
+}
+
+/* Typography helpers */
+
+.app-main h1,
+.app-main h2,
+.app-main h3,
+.app-main h4,
+.app-main h5 {
+    letter-spacing: 0.02em;
+}
+
+.app-main p.lead {
+    color: var(--color-text-muted);
+}
+
+/* Hot pink accent utility for occasional emphasis */
+.text-hot-pink {
+    color: var(--color-accent-hot) !important;
+}
+
+/* Header / Navbar */
+
+.app-header {
+    background-color: var(--color-navbar-bg);
+    backdrop-filter: blur(12px);
+    -webkit-backdrop-filter: blur(12px);
+    box-shadow: 0 1px 0 var(--color-border-subtle);
+    transition:
+        background-color var(--transition-fast),
+        box-shadow var(--transition-fast),
+        border-color var(--transition-fast);
+}
+
+.app-header .navbar-brand {
+    font-weight: 700;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    font-size: 0.85rem;
+    color: var(--color-text);
+}
+
+.app-header .navbar-brand:hover {
+    color: var(--color-accent);
+}
+
+.app-header .nav-link {
+    color: var(--color-text-muted);
+    font-weight: 500;
+    font-size: 0.9rem;
+    transition:
+        color var(--transition-fast),
+        background-color var(--transition-fast);
+}
+
+.app-header .nav-link:hover,
+.app-header .nav-link:focus {
+    color: var(--color-accent);
+    background-color: transparent;
+}
+
+.app-header .nav-link.active {
+    color: var(--color-accent);
+}
+
+.app-header .btn.btn-outline-secondary {
+    --bs-btn-color: var(--color-text-muted);
+    --bs-btn-border-color: var(--color-border-subtle);
+    --bs-btn-hover-bg: var(--color-accent-soft);
+    --bs-btn-hover-border-color: var(--color-accent);
+    --bs-btn-hover-color: var(--color-accent);
+    --bs-btn-focus-shadow-rgb: 34, 211, 238;
+    padding-inline: 0.55rem;
+    padding-block: 0.3rem;
+    border-radius: 999px;
+}
+
+/* Language dropdown: theme-aware styling */
+.app-header .dropdown-menu-dark {
+    --bs-dropdown-bg: var(--color-bg-elevated);
+    --bs-dropdown-link-color: var(--color-text);
+    --bs-dropdown-link-hover-bg: var(--color-accent-soft);
+    --bs-dropdown-link-hover-color: var(--color-accent);
+    --bs-dropdown-link-active-bg: var(--color-accent-soft);
+    --bs-dropdown-link-active-color: var(--color-accent);
+    --bs-dropdown-border-color: var(--color-border-subtle);
+    background-color: var(--color-bg-elevated);
+    border-color: var(--color-border-subtle);
+    color: var(--color-text);
+}
+
+/* Prevent language dropdown from overflowing off-screen in RTL */
+html[dir="rtl"] .app-header .dropdown-menu-end {
+    left: auto;
+    right: 0;
+    transform: none;
+}
+
+.app-header .dropdown-menu-dark .dropdown-item.active,
+.app-header .dropdown-menu-dark .dropdown-item:active {
+    background-color: var(--color-accent-soft);
+    color: var(--color-accent);
+}
+
+.app-header .dropdown-menu-dark-context .dropdown-toggle.btn-secondary {
+    --bs-btn-bg: transparent;
+    --bs-btn-border-color: var(--color-border-subtle);
+    --bs-btn-color: var(--color-text-muted);
+    --bs-btn-hover-bg: var(--color-accent-soft);
+    --bs-btn-hover-border-color: var(--color-accent);
+    --bs-btn-hover-color: var(--color-accent);
+    --bs-btn-focus-shadow-rgb: 34, 211, 238;
+}
+
+.app-header .btn.btn-outline-secondary svg {
+    display: block;
+}
+
+/* Generic helper class for mirroring directional icons in RTL.
+   Used by DirectionalIcon when `mirrorInRtl` is enabled. */
+html[dir="rtl"] .diricon-mirror-rtl {
+    transform: scaleX(-1);
+}
+
+/* Provide a visible toggler icon when using default Bootstrap styles */
+.navbar-toggler {
+    border-color: var(--color-border-subtle);
+}
+
+.navbar-toggler-icon {
+    background-image: none;
+    position: relative;
+    width: 1.25rem;
+    height: 1.25rem;
+}
+
+.navbar-toggler-icon::before,
+.navbar-toggler-icon::after,
+.navbar-toggler-icon span {
+    content: "";
+    position: absolute;
+    left: 0;
+    right: 0;
+    height: 2px;
+    border-radius: 999px;
+    background-color: var(--color-text);
+    transition:
+        transform 150ms ease-out,
+        opacity 150ms ease-out;
+}
+
+.navbar-toggler-icon::before {
+    top: 0.25rem;
+}
+
+.navbar-toggler-icon::after {
+    bottom: 0.25rem;
+}
+
+/* Footer */
+
+.app-footer {
+    background-color: var(--color-footer-bg);
+    backdrop-filter: blur(10px);
+    -webkit-backdrop-filter: blur(10px);
+    box-shadow: 0 -1px 0 var(--color-border-subtle);
+    transition:
+        background-color var(--transition-fast),
+        box-shadow var(--transition-fast),
+        border-color var(--transition-fast);
+}
+
+/* Main content layout */
+
+.app-main {
+    max-width: 1120px;
+}
+
+/* When in RTL mode, flip common flex directions and alignment where needed */
+html[dir="rtl"] .app-root {
+    direction: rtl;
+    text-align: right;
+}
+
+html[dir="rtl"] .app-header .navbar-brand {
+    flex-direction: row-reverse;
+}
+
+html[dir="rtl"] .app-header .nav-link {
+    text-align: right;
+}
+
+html[dir="rtl"] .app-header .d-flex.align-items-center.gap-2 {
+    flex-direction: row-reverse;
+}
+
+html[dir="rtl"] .app-main .card-body {
+    text-align: right;
+}
+
+/* Ensure footer content also respects RTL direction */
+html[dir="rtl"] .app-footer {
+    direction: rtl;
+    text-align: right;
+}
+
+.app-main .card,
+.app-main .card-body {
+    background-color: var(--color-bg-elevated);
+    border-color: var(--color-border-subtle);
+}
+
+/* Generic utility styles */
+
+.surface-elevated {
+    background-color: var(--color-bg-elevated);
+    border-radius: 1rem;
+    border: 1px solid var(--color-border-subtle);
+    box-shadow: var(--shadow-soft);
+}
+
+/* Mesh / principle icon containers */
+.mesh-icon,
+.principle-icon {
+    width: 2.25rem;
+    height: 2.25rem;
+    border-radius: 999px;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    border: 1px solid var(--color-border-subtle);
+    background: radial-gradient(
+        circle,
+        var(--color-accent-soft),
+        transparent 60%
+    );
+    color: var(--color-accent);
+    margin-bottom: 0.35rem;
+    flex-shrink: 0;
+}
+
+.principle-icon {
+    width: 2rem;
+    height: 2rem;
+}
+
+/* CTA background texture */
+.join-mesh-cta {
+    background:
+        radial-gradient(
+            circle at top,
+            rgba(34, 211, 238, 0.18),
+            transparent 60%
+        ),
+        url("/bg-logo-right.png") center/cover no-repeat,
+        var(--color-bg-elevated);
+    background-blend-mode: screen, normal;
+}
+
+.badge-accent {
+    background-color: var(--color-accent-soft);
+    color: var(--color-accent);
+    border-radius: 999px;
+    padding: 0.1rem 0.55rem;
+    font-size: 0.7rem;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+}
+
+/* Ensure muted text uses our theme variable instead of Bootstrap defaults */
+.text-muted,
+small {
+    color: var(--color-text-muted) !important;
+}
+
+/* Small cyan dot used inside hero and CTA badges */
+.bg-cyan-500-dot {
+    display: inline-block;
+    width: 0.45rem;
+    height: 0.45rem;
+    border-radius: 999px;
+    background: radial-gradient(
+        circle,
+        var(--color-accent) 0%,
+        transparent 65%
+    );
+}
+
+/* Links */
+
+a {
+    color: var(--color-accent);
+    text-decoration: none;
+}
+
+a:hover {
+    color: var(--color-accent);
+    text-decoration: underline;
+}
+
+/* Scrollbar theming (WebKit) */
+
+*::-webkit-scrollbar {
+    width: 8px;
+    height: 8px;
+}
+
+*::-webkit-scrollbar-thumb {
+    background-color: rgba(148, 163, 184, 0.6);
+    border-radius: 999px;
+}
+
+:root[data-theme="dark"] *::-webkit-scrollbar-thumb {
+    background-color: rgba(148, 163, 184, 0.8);
+}
+
+/* Code blocks / preformatted text placeholders */
+
+pre,
+code {
+    font-family:
+        ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas,
+        "Liberation Mono", "Courier New", monospace;
+}
+
+pre {
+    background-color: var(--color-bg-subtle);
+    border-radius: 0.75rem;
+    padding: 0.75rem 1rem;
+    border: 1px solid var(--color-border-subtle);
+    overflow-x: auto;
+}
+
+/* Small-screen adjustments */
+
+@media (max-width: 576px) {
+    .app-main {
+        padding-left: 1rem !important;
+        padding-right: 1rem !important;
+    }
+
+    .app-header .navbar-brand {
+        font-size: 0.8rem;
+    }
+}

helexa.ai/src/App.tsx

@@ -1,12 +1,27 @@
-import { Container } from "react-bootstrap";
+import { BrowserRouter, Routes, Route } from "react-router-dom";
+import ThemeProvider from "./layout/ThemeProvider";
+import Header from "./components/Header";
+import Footer from "./components/Footer";
+import Mission from "./pages/Mission";
+import Chat from "./pages/Chat";
+import "./App.css";
 
-// F0 scaffold shell. Theming, i18n, routing, the chat workspace, mission
-// page and account dashboard land in the F1+ phases.
+// Composition root: theme + router + layout shell. `/` is the chat
+// workspace (F3, anonymous for now); `/mission` (F2) is the EU-sovereignty
+// narrative; the auth/account routes (F4) land next.
 export default function App() {
   return (
-    <Container className="py-5">
-      <h1 className="mb-2">helexa.ai</h1>
-      <p className="text-muted">Public beta — coming online.</p>
-    </Container>
+    <ThemeProvider>
+      <BrowserRouter>
+        <div className="d-flex flex-column min-vh-100">
+          <Header />
+          <Routes>
+            <Route path="/" element={<Chat />} />
+            <Route path="/mission" element={<Mission />} />
+          </Routes>
+          <Footer />
+        </div>
+      </BrowserRouter>
+    </ThemeProvider>
   );
 }

helexa.ai/src/components/DirectionalIcon.tsx

@@ -0,0 +1,127 @@
+import React from "react";
+import { useTranslation } from "react-i18next";
+import { isRtlLanguage, type LanguageCode } from "../i18n/languages";
+
+export type Direction = "forward" | "back";
+
+/**
+ * DirectionalIcon
+ *
+ * Small helper component to render direction-aware icons that respect
+ * the current UI writing direction (LTR vs RTL).
+ *
+ * Usage example:
+ *
+ *   <DirectionalIcon
+ *     direction="forward"
+ *     ltrIcon={FaArrowRight}
+ *     rtlIcon={FaArrowLeft}
+ *   />
+ *
+ * - `direction="forward"` means “toward the natural reading direction”
+ *   (right in LTR, left in RTL).
+ * - `direction="back"` means the opposite (left in LTR, right in RTL).
+ *
+ * You can either:
+ *   - pass explicit `ltrIcon` and `rtlIcon` React components, or
+ *   - pass a single `icon` component and set `mirrorInRtl` to flip it
+ *     horizontally when in RTL (via CSS transform).
+ *
+ * In most cases, using explicit LTR / RTL icons is clearer and avoids
+ * surprises with asymmetric icon shapes.
+ */
+export interface DirectionalIconProps {
+  /**
+   * Logical direction relative to reading order.
+   * - "forward": in the direction of the text flow
+   * - "back": opposite the direction of the text flow
+   */
+  direction: Direction;
+
+  /**
+   * Icon component to use for LTR contexts (e.g. FaArrowRight).
+   */
+  ltrIcon?: React.ComponentType<{ size?: number | string; className?: string }>;
+
+  /**
+   * Icon component to use for RTL contexts (e.g. FaArrowLeft).
+   */
+  rtlIcon?: React.ComponentType<{ size?: number | string; className?: string }>;
+
+  /**
+   * Single base icon component. When provided together with
+   * `mirrorInRtl={true}`, it will be mirrored horizontally in RTL.
+   */
+  icon?: React.ComponentType<{ size?: number | string; className?: string }>;
+
+  /**
+   * Whether to flip the `icon` horizontally in RTL.
+   * Ignored if both `ltrIcon` and `rtlIcon` are supplied.
+   */
+  mirrorInRtl?: boolean;
+
+  /**
+   * Optional size forwarded to the rendered icon.
+   */
+  size?: number | string;
+
+  /**
+   * Additional className to apply to the rendered icon.
+   */
+  className?: string;
+}
+
+/**
+ * Determine if current language is RTL based on i18next language code.
+ *
+ * Delegates to the shared `isRtlLanguage` helper from i18n/languages.ts
+ * so that all RTL logic lives in one place.
+ */
+const isRtlLanguageCode = (code: string | undefined | null): boolean => {
+  if (!code) return false;
+  const lang = code.split("-")[0].toLowerCase() as LanguageCode;
+  return isRtlLanguage(lang);
+};
+
+const DirectionalIcon: React.FC<DirectionalIconProps> = ({
+  direction,
+  ltrIcon: LtrIcon,
+  rtlIcon: RtlIcon,
+  icon: BaseIcon,
+  mirrorInRtl = false,
+  size,
+  className,
+}) => {
+  const { i18n } = useTranslation();
+  const isRtl = isRtlLanguageCode(i18n.language);
+
+  // If explicit LTR/RTL icons are provided, prefer those.
+  if (LtrIcon && RtlIcon) {
+    const IconComponent =
+      (direction === "forward" && !isRtl) || (direction === "back" && isRtl)
+        ? LtrIcon
+        : RtlIcon;
+
+    return <IconComponent size={size} className={className} />;
+  }
+
+  // Fallback: single base icon, optionally mirrored in RTL.
+  if (!BaseIcon) {
+    return null;
+  }
+
+  const shouldMirror =
+    mirrorInRtl &&
+    ((direction === "forward" && isRtl) || (direction === "back" && !isRtl));
+
+  const combinedClassName = [
+    className,
+    shouldMirror ? "diricon-mirror-rtl" : null,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return <BaseIcon size={size} className={combinedClassName} />;
+};
+
+export default DirectionalIcon;

helexa.ai/src/components/Footer.tsx

@@ -0,0 +1,23 @@
+import React from "react";
+import { useTranslation } from "react-i18next";
+
+/**
+ * Footer
+ *
+ * Simple application footer used in the main layout.
+ * Renders a subtle, theme-aware bar with copyright text.
+ */
+const Footer: React.FC = () => {
+  const year = new Date().getFullYear();
+  const { t } = useTranslation("common");
+
+  return (
+    <footer className="app-footer border-top py-3 mt-auto">
+      <div className="container-fluid text-center text-muted small">
+        <span>{t("footer.copyright", { year })}</span>
+      </div>
+    </footer>
+  );
+};
+
+export default Footer;

helexa.ai/src/components/Header.tsx

@@ -0,0 +1,140 @@
+import React from "react";
+import { Link, NavLink } from "react-router-dom";
+import { Navbar, Container, Nav, Button, Dropdown } from "react-bootstrap";
+import { FaRegMoon, FaRegSun } from "react-icons/fa6";
+import { useTheme } from "../layout/theme";
+import { useTranslation } from "react-i18next";
+import { AUTONYM_MAP, type LanguageCode, isRtlLanguage } from "../i18n/languages";
+import { getLanguageOptionsByUsage } from "../i18n/translation-priority";
+
+/**
+ * Top navigation: brand, primary routes (chat at `/`, `/mission`), an
+ * auth-aware cluster (stubbed until F4 wires sessions), the theme toggle,
+ * and the language selector.
+ *
+ * The language picker is ordered by **estimated usage**
+ * (getLanguageOptionsByUsage), not alphabetically — a deliberate choice that
+ * foregrounds helexa's international grounding. Each item shows the autonym
+ * (language in its own script) plus a secondary label in the current
+ * language; RTL-aware alignment.
+ */
+const Header: React.FC = () => {
+  const { theme, toggleTheme } = useTheme();
+  const { t, i18n } = useTranslation("common");
+
+  const currentLanguage: LanguageCode = (i18n.language.split("-")[0] ||
+    "en") as LanguageCode;
+  const isRtl = isRtlLanguage(currentLanguage);
+  const languageOptions = getLanguageOptionsByUsage();
+
+  return (
+    <Navbar
+      expand="lg"
+      className="app-header border-bottom"
+      variant={theme === "dark" ? "dark" : "light"}
+    >
+      <Container fluid>
+        <Navbar.Brand
+          as={Link}
+          to="/"
+          className="d-flex align-items-center gap-2"
+        >
+          <img
+            src="/logo.png"
+            alt="helexa logo"
+            width={28}
+            height={28}
+            style={{ borderRadius: "999px" }}
+          />
+          <span className="fw-semibold text-uppercase small tracking-wide">
+            {t("app.name")}
+          </span>
+        </Navbar.Brand>
+
+        <Navbar.Toggle aria-controls="main-navbar" />
+
+        <Navbar.Collapse id="main-navbar">
+          <Nav className="me-auto">
+            <NavLink
+              to="/"
+              end
+              className={({ isActive }): string =>
+                isActive ? "nav-link active" : "nav-link"
+              }
+            >
+              {t("nav.chat")}
+            </NavLink>
+            <NavLink
+              to="/mission"
+              className={({ isActive }): string =>
+                isActive ? "nav-link active" : "nav-link"
+              }
+            >
+              {t("nav.mission")}
+            </NavLink>
+          </Nav>
+
+          <div className="d-flex align-items-center gap-2">
+            {/* Auth cluster — plain links until F4 wires session state. */}
+            <NavLink to="/login" className="nav-link">
+              {t("nav.login")}
+            </NavLink>
+            <NavLink to="/register" className="nav-link">
+              {t("nav.register")}
+            </NavLink>
+
+            <Button
+              size="sm"
+              variant="outline-secondary"
+              type="button"
+              onClick={toggleTheme}
+              aria-label={
+                theme === "dark"
+                  ? t("theme.toggle.toLight")
+                  : t("theme.toggle.toDark")
+              }
+              className="d-inline-flex align-items-center justify-content-center"
+            >
+              {theme === "dark" ? <FaRegSun size={16} /> : <FaRegMoon size={16} />}
+            </Button>
+
+            <Dropdown
+              align={isRtl ? "start" : "end"}
+              className={theme === "dark" ? "dropdown-menu-dark-context" : ""}
+            >
+              <Dropdown.Toggle
+                size="sm"
+                variant={theme === "dark" ? "secondary" : "outline-secondary"}
+                id="language-switcher"
+              >
+                <span className="me-1" aria-hidden="true">
+                  文A
+                </span>
+                <span>{AUTONYM_MAP[currentLanguage]}</span>
+              </Dropdown.Toggle>
+              <Dropdown.Menu
+                className={theme === "dark" ? "dropdown-menu-dark" : ""}
+              >
+                {languageOptions.map(({ code, autonym }) => (
+                  <Dropdown.Item
+                    key={code}
+                    active={code === currentLanguage}
+                    onClick={() => void i18n.changeLanguage(code)}
+                    className="d-flex align-items-center gap-2"
+                  >
+                    <span>{autonym}</span>
+                    <span className="text-muted small fw-light">
+                      · {t(`lang.${code}`)}
+                    </span>
+                  </Dropdown.Item>
+                ))}
+              </Dropdown.Menu>
+            </Dropdown>
+          </div>
+        </Navbar.Collapse>
+      </Container>
+    </Navbar>
+  );
+};
+
+export default Header;

helexa.ai/src/data/db.ts

@@ -0,0 +1,72 @@
+// IndexedDB (Dexie) — the ONLY home for chat history and project
+// organisation. Nothing here is ever sent to a server (#69/#F3): the mesh
+// serves inference, but conversations live exclusively in the browser.
+//
+// `owner` namespaces data: `"anon"` for the fingerprinted anonymous visitor,
+// or an account id once signed in. On login, anonymous data can be claimed
+// into the account (F4) — still purely client-side.
+
+import Dexie, { type Table } from "dexie";
+
+export interface Project {
+  id: string;
+  owner: string;
+  name: string;
+  createdAt: number;
+  updatedAt: number;
+  archived: boolean;
+  sortOrder: number;
+}
+
+export interface Conversation {
+  id: string;
+  owner: string;
+  projectId: string | null; // null → "Unsorted"
+  title: string;
+  model: string;
+  createdAt: number;
+  updatedAt: number;
+  pinned: boolean;
+}
+
+export type MessageRole = "system" | "user" | "assistant";
+export type MessageStatus = "complete" | "streaming" | "error";
+
+export interface Message {
+  id: string;
+  conversationId: string;
+  role: MessageRole;
+  content: string;
+  createdAt: number;
+  status: MessageStatus;
+  errorCode?: string;
+  promptTokens?: number;
+  completionTokens?: number;
+}
+
+/** Small key/value store: fingerprint, active conversation, anon usage. */
+export interface Meta {
+  key: string;
+  value: unknown;
+}
+
+class HelexaDB extends Dexie {
+  projects!: Table<Project, string>;
+  conversations!: Table<Conversation, string>;
+  messages!: Table<Message, string>;
+  meta!: Table<Meta, string>;
+
+  constructor() {
+    super("helexa");
+    this.version(1).stores({
+      // Indexes only — Dexie stores the whole object. Compound indexes
+      // drive the common queries (by owner, by conversation in time order).
+      projects: "id, owner, [owner+archived], updatedAt",
+      conversations: "id, owner, projectId, [owner+projectId], updatedAt",
+      messages: "id, conversationId, [conversationId+createdAt]",
+      meta: "key",
+    });
+  }
+}
+
+export const db = new HelexaDB();

helexa.ai/src/data/repositories.ts

@@ -0,0 +1,154 @@
+// Typed CRUD + queries over the Dexie store. UI components use the
+// `useLiveQuery` hook (dexie-react-hooks) with the list helpers here so the
+// sidebar/thread react to writes automatically.
+
+import Dexie from "dexie";
+import {
+  db,
+  type Conversation,
+  type Message,
+  type MessageRole,
+  type Project,
+} from "./db";
+
+function uuid(): string {
+  return crypto.randomUUID();
+}
+function now(): number {
+  return Date.now();
+}
+
+// ── projects ────────────────────────────────────────────────────────
+
+export async function listProjects(owner: string): Promise<Project[]> {
+  const rows = await db.projects.where({ owner }).toArray();
+  return rows
+    .filter((p) => !p.archived)
+    .sort((a, b) => a.sortOrder - b.sortOrder || a.createdAt - b.createdAt);
+}
+
+export async function createProject(owner: string, name: string): Promise<string> {
+  const id = uuid();
+  const ts = now();
+  await db.projects.add({
+    id,
+    owner,
+    name,
+    createdAt: ts,
+    updatedAt: ts,
+    archived: false,
+    sortOrder: ts,
+  });
+  return id;
+}
+
+export async function renameProject(id: string, name: string): Promise<void> {
+  await db.projects.update(id, { name, updatedAt: now() });
+}
+
+export async function archiveProject(id: string): Promise<void> {
+  // Detach its conversations to "Unsorted" so nothing is orphaned.
+  await db.transaction("rw", db.projects, db.conversations, async () => {
+    await db.projects.update(id, { archived: true, updatedAt: now() });
+    const convs = await db.conversations.where({ projectId: id }).toArray();
+    await Promise.all(
+      convs.map((c) => db.conversations.update(c.id, { projectId: null })),
+    );
+  });
+}
+
+// ── conversations ───────────────────────────────────────────────────
+
+export async function listConversations(owner: string): Promise<Conversation[]> {
+  const rows = await db.conversations.where({ owner }).toArray();
+  return rows.sort(
+    (a, b) => Number(b.pinned) - Number(a.pinned) || b.updatedAt - a.updatedAt,
+  );
+}
+
+export async function createConversation(
+  owner: string,
+  model: string,
+  projectId: string | null = null,
+  title = "New chat",
+): Promise<string> {
+  const id = uuid();
+  const ts = now();
+  await db.conversations.add({
+    id,
+    owner,
+    projectId,
+    title,
+    model,
+    createdAt: ts,
+    updatedAt: ts,
+    pinned: false,
+  });
+  return id;
+}
+
+export async function renameConversation(id: string, title: string): Promise<void> {
+  await db.conversations.update(id, { title, updatedAt: now() });
+}
+
+export async function moveConversation(
+  id: string,
+  projectId: string | null,
+): Promise<void> {
+  await db.conversations.update(id, { projectId, updatedAt: now() });
+}
+
+export async function deleteConversation(id: string): Promise<void> {
+  await db.transaction("rw", db.conversations, db.messages, async () => {
+    await db.messages.where({ conversationId: id }).delete();
+    await db.conversations.delete(id);
+  });
+}
+
+// ── messages ────────────────────────────────────────────────────────
+
+export async function listMessages(conversationId: string): Promise<Message[]> {
+  return db.messages
+    .where("[conversationId+createdAt]")
+    .between([conversationId, Dexie.minKey], [conversationId, Dexie.maxKey])
+    .toArray();
+}
+
+export async function addMessage(
+  conversationId: string,
+  role: MessageRole,
+  content: string,
+  status: Message["status"] = "complete",
+): Promise<string> {
+  const id = uuid();
+  await db.messages.add({ id, conversationId, role, content, createdAt: now(), status });
+  await db.conversations.update(conversationId, { updatedAt: now() });
+  return id;
+}
+
+export async function appendToMessage(id: string, delta: string): Promise<void> {
+  const msg = await db.messages.get(id);
+  if (!msg) return;
+  await db.messages.update(id, { content: msg.content + delta });
+}
+
+export async function finalizeMessage(
+  id: string,
+  patch: Partial<Pick<Message, "status" | "errorCode" | "promptTokens" | "completionTokens">>,
+): Promise<void> {
+  await db.messages.update(id, patch);
+}
+
+/** Rewrite all `anon` data to `accountId` on first login (stays local). */
+export async function claimAnonymousData(accountId: string): Promise<void> {
+  await db.transaction("rw", db.projects, db.conversations, async () => {
+    const projects = await db.projects.where({ owner: "anon" }).toArray();
+    await Promise.all(
+      projects.map((p) => db.projects.update(p.id, { owner: accountId })),
+    );
+    const convs = await db.conversations.where({ owner: "anon" }).toArray();
+    await Promise.all(
+      convs.map((c) => db.conversations.update(c.id, { owner: accountId })),
+    );
+  });
+}

helexa.ai/src/i18n/index.ts

@@ -0,0 +1,360 @@
+import i18n, { type Resource } from "i18next";
+import { initReactI18next } from "react-i18next";
+import {
+  SUPPORTED_LANGUAGES,
+  normalizeLocaleToLanguage,
+  isRtlLanguage,
+} from "./languages";
+import type { LanguageCode } from "./languages";
+
+// Core languages
+import enCommon from "./resources/en/common.json";
+import ruCommon from "./resources/ru/common.json";
+import enMission from "./resources/en/mission.json";
+import ruMission from "./resources/ru/mission.json";
+import enChat from "./resources/en/chat.json";
+import ruChat from "./resources/ru/chat.json";
+
+// Scandinavian & Nordic languages
+import daCommon from "./resources/da/common.json";
+import daMission from "./resources/da/mission.json";
+import daChat from "./resources/da/chat.json";
+
+import fiCommon from "./resources/fi/common.json";
+import fiMission from "./resources/fi/mission.json";
+import fiChat from "./resources/fi/chat.json";
+
+import noCommon from "./resources/no/common.json";
+import noMission from "./resources/no/mission.json";
+import noChat from "./resources/no/chat.json";
+
+import svCommon from "./resources/sv/common.json";
+import svMission from "./resources/sv/mission.json";
+import svChat from "./resources/sv/chat.json";
+
+import bgCommon from "./resources/bg/common.json";
+import bgMission from "./resources/bg/mission.json";
+import bgChat from "./resources/bg/chat.json";
+
+import etCommon from "./resources/et/common.json";
+import etMission from "./resources/et/mission.json";
+import etChat from "./resources/et/chat.json";
+
+// African & MENA languages
+import swCommon from "./resources/sw/common.json";
+import swMission from "./resources/sw/mission.json";
+import swChat from "./resources/sw/chat.json";
+
+import arCommon from "./resources/ar/common.json";
+import arMission from "./resources/ar/mission.json";
+import arChat from "./resources/ar/chat.json";
+
+import faCommon from "./resources/fa/common.json";
+import faMission from "./resources/fa/mission.json";
+import faChat from "./resources/fa/chat.json";
+
+import haCommon from "./resources/ha/common.json";
+import haMission from "./resources/ha/mission.json";
+import haChat from "./resources/ha/chat.json";
+
+import amCommon from "./resources/am/common.json";
+import amMission from "./resources/am/mission.json";
+import amChat from "./resources/am/chat.json";
+
+import yoCommon from "./resources/yo/common.json";
+import yoMission from "./resources/yo/mission.json";
+import yoChat from "./resources/yo/chat.json";
+
+import zuCommon from "./resources/zu/common.json";
+import zuMission from "./resources/zu/mission.json";
+import zuChat from "./resources/zu/chat.json";
+
+// Darija (Moroccan Arabic)
+import maCommon from "./resources/ma/common.json";
+import maMission from "./resources/ma/mission.json";
+import maChat from "./resources/ma/chat.json";
+
+// European / other languages
+import esCommon from "./resources/es/common.json";
+import esMission from "./resources/es/mission.json";
+import esChat from "./resources/es/chat.json";
+
+import frCommon from "./resources/fr/common.json";
+import frMission from "./resources/fr/mission.json";
+import frChat from "./resources/fr/chat.json";
+
+import deCommon from "./resources/de/common.json";
+import deMission from "./resources/de/mission.json";
+import deChat from "./resources/de/chat.json";
+
+import elCommon from "./resources/el/common.json";
+import elMission from "./resources/el/mission.json";
+import elChat from "./resources/el/chat.json";
+
+import itCommon from "./resources/it/common.json";
+import itMission from "./resources/it/mission.json";
+import itChat from "./resources/it/chat.json";
+
+import heCommon from "./resources/he/common.json";
+import heMission from "./resources/he/mission.json";
+import heChat from "./resources/he/chat.json";
+
+import ptCommon from "./resources/pt/common.json";
+import ptMission from "./resources/pt/mission.json";
+import ptChat from "./resources/pt/chat.json";
+
+import roCommon from "./resources/ro/common.json";
+import roMission from "./resources/ro/mission.json";
+import roChat from "./resources/ro/chat.json";
+
+import kaCommon from "./resources/ka/common.json";
+import kaMission from "./resources/ka/mission.json";
+import kaChat from "./resources/ka/chat.json";
+
+import trCommon from "./resources/tr/common.json";
+import trMission from "./resources/tr/mission.json";
+import trChat from "./resources/tr/chat.json";
+
+import plCommon from "./resources/pl/common.json";
+import plMission from "./resources/pl/mission.json";
+import plChat from "./resources/pl/chat.json";
+
+import ukCommon from "./resources/uk/common.json";
+import ukMission from "./resources/uk/mission.json";
+import ukChat from "./resources/uk/chat.json";
+
+import nlCommon from "./resources/nl/common.json";
+import nlMission from "./resources/nl/mission.json";
+import nlChat from "./resources/nl/chat.json";
+
+import srCommon from "./resources/sr/common.json";
+import srMission from "./resources/sr/mission.json";
+import srChat from "./resources/sr/chat.json";
+
+import kkCommon from "./resources/kk/common.json";
+import kkMission from "./resources/kk/mission.json";
+import kkChat from "./resources/kk/chat.json";
+
+import uzCommon from "./resources/uz/common.json";
+import uzMission from "./resources/uz/mission.json";
+import uzChat from "./resources/uz/chat.json";
+
+/**
+ * Application translation resources, split by language and namespace.
+ *
+ * - `common`: shared UI elements (navigation, theme toggle, etc.)
+ * - `home`:   marketing / narrative copy on the landing page
+ * - `chat`:   copy for the chat workspace
+ */
+const resources: Resource = {
+  en: {
+    common: enCommon,
+    mission: enMission,
+    chat: enChat,
+  },
+  ru: {
+    common: ruCommon,
+    mission: ruMission,
+    chat: ruChat,
+  },
+  bg: {
+    common: bgCommon,
+    mission: bgMission,
+    chat: bgChat,
+  },
+  da: {
+    common: daCommon,
+    mission: daMission,
+    chat: daChat,
+  },
+  et: {
+    common: etCommon,
+    mission: etMission,
+    chat: etChat,
+  },
+  fi: {
+    common: fiCommon,
+    mission: fiMission,
+    chat: fiChat,
+  },
+  kk: {
+    common: kkCommon,
+    mission: kkMission,
+    chat: kkChat,
+  },
+  uz: {
+    common: uzCommon,
+    mission: uzMission,
+    chat: uzChat,
+  },
+
+  // African & MENA languages (LTR unless marked RTL via isRtlLanguage)
+  sw: {
+    common: swCommon,
+    mission: swMission,
+    chat: swChat,
+  },
+  ar: {
+    common: arCommon,
+    mission: arMission,
+    chat: arChat,
+  },
+  fa: {
+    common: faCommon,
+    mission: faMission,
+    chat: faChat,
+  },
+  ha: {
+    common: haCommon,
+    mission: haMission,
+    chat: haChat,
+  },
+  am: {
+    common: amCommon,
+    mission: amMission,
+    chat: amChat,
+  },
+  yo: {
+    common: yoCommon,
+    mission: yoMission,
+    chat: yoChat,
+  },
+  zu: {
+    common: zuCommon,
+    mission: zuMission,
+    chat: zuChat,
+  },
+  ma: {
+    common: maCommon,
+    mission: maMission,
+    chat: maChat,
+  },
+
+  // European & other languages
+  es: {
+    common: esCommon,
+    mission: esMission,
+    chat: esChat,
+  },
+  fr: {
+    common: frCommon,
+    mission: frMission,
+    chat: frChat,
+  },
+  de: {
+    common: deCommon,
+    mission: deMission,
+    chat: deChat,
+  },
+  el: {
+    common: elCommon,
+    mission: elMission,
+    chat: elChat,
+  },
+  it: {
+    common: itCommon,
+    mission: itMission,
+    chat: itChat,
+  },
+  he: {
+    common: heCommon,
+    mission: heMission,
+    chat: heChat,
+  },
+  pt: {
+    common: ptCommon,
+    mission: ptMission,
+    chat: ptChat,
+  },
+  ro: {
+    common: roCommon,
+    mission: roMission,
+    chat: roChat,
+  },
+  ka: {
+    common: kaCommon,
+    mission: kaMission,
+    chat: kaChat,
+  },
+  tr: {
+    common: trCommon,
+    mission: trMission,
+    chat: trChat,
+  },
+  pl: {
+    common: plCommon,
+    mission: plMission,
+    chat: plChat,
+  },
+  uk: {
+    common: ukCommon,
+    mission: ukMission,
+    chat: ukChat,
+  },
+  nl: {
+    common: nlCommon,
+    mission: nlMission,
+    chat: nlChat,
+  },
+  sr: {
+    common: srCommon,
+    mission: srMission,
+    chat: srChat,
+  },
+  no: {
+    common: noCommon,
+    mission: noMission,
+    chat: noChat,
+  },
+  sv: {
+    common: svCommon,
+    mission: svMission,
+    chat: svChat,
+  },
+};
+
+// Determine initial language from browser, normalised to language-only.
+const browserLang: LanguageCode =
+  typeof navigator !== "undefined"
+    ? normalizeLocaleToLanguage(navigator.language)
+    : "en";
+
+// Keep document direction (ltr/rtl) in sync with the active language.
+if (typeof document !== "undefined") {
+  document.documentElement.dir = isRtlLanguage(browserLang) ? "rtl" : "ltr";
+}
+
+/**
+ * Initialize i18next with React bindings.
+ *
+ * This module is imported once in src/main.tsx before any React
+ * rendering so that `useTranslation` is ready everywhere.
+ */
+i18n.use(initReactI18next).init({
+  resources,
+  lng: browserLang,
+  fallbackLng: "en",
+  supportedLngs: SUPPORTED_LANGUAGES,
+  ns: ["common", "mission", "chat"],
+  defaultNS: "common",
+  // Because we control the keys and interpolate only simple values.
+  interpolation: {
+    escapeValue: false,
+  },
+  // For now we stay language-only; we already normalise the browser locale.
+  load: "languageOnly",
+  // Be explicit about react options for clarity.
+  react: {
+    useSuspense: false,
+  },
+});
+
+// Ensure that when the language changes at runtime, document direction
+// tracks the new language's natural writing direction.
+i18n.on("languageChanged", (lng) => {
+  if (typeof document === "undefined") return;
+  const lang = normalizeLocaleToLanguage(lng);
+  document.documentElement.dir = isRtlLanguage(lang) ? "rtl" : "ltr";
+});
+
+export default i18n;

helexa.ai/src/i18n/languages.ts

@@ -0,0 +1,232 @@
+import type { Resource } from "i18next";
+
+/**
+ * Supported language codes for the application.
+ *
+ * For the foreseeable future we deliberately stay at the language level
+ * (e.g. "en", "ru") rather than full locales (e.g. "en-GB") to keep
+ * translation overhead manageable.
+ *
+ * When you add a new language:
+ * - Add its code to `SUPPORTED_LANGUAGES`
+ * - Add its autonym to `AUTONYM_MAP`
+ * - Add its resources to the i18n configuration
+ */
+export type LanguageCode =
+  | "en"
+  | "bg"
+  | "cs"
+  | "da"
+  | "de"
+  | "el"
+  | "es"
+  | "he"
+  | "et"
+  | "ar"
+  | "fa"
+  | "fi"
+  | "sw"
+  | "ha"
+  | "am"
+  | "yo"
+  | "zu"
+  | "fr"
+  | "ma"
+  | "ga"
+  | "hr"
+  | "hu"
+  | "is"
+  | "it"
+  | "ka"
+  | "lt"
+  | "lv"
+  | "mt"
+  | "nl"
+  | "no"
+  | "pl"
+  | "pt"
+  | "ro"
+  | "ru"
+  | "sk"
+  | "sl"
+  | "sr"
+  | "sv"
+  | "tr"
+  | "uk"
+  | "bs"
+  | "mk"
+  | "kk"
+  | "uz"
+  | "ig"
+  | "om"
+  | "so"
+  | "ti"
+  | "wo";
+
+/**
+ * Ordered list of languages enabled in the UI.
+ *
+ * For now you can keep `SUPPORTED_LANGUAGES` in sync with the
+ * actually configured i18n resources (e.g. ["en", "ru"]) and grow
+ * it as translations land.
+ */
+export const SUPPORTED_LANGUAGES: LanguageCode[] = [
+  "bg",
+  "da",
+  "de",
+  "el",
+  "en",
+  "es",
+  "et",
+  "fi",
+  "fr",
+  "he",
+  "it",
+  "ka",
+  "kk",
+  "nl",
+  "no",
+  "sv",
+  "uz",
+  "ar",
+  "fa",
+  "sw",
+  "ha",
+  "am",
+  "yo",
+  "zu",
+  "ma",
+  "pl",
+  "pt",
+  "ro",
+  "ru",
+  "sr",
+  "tr",
+  "uk",
+  // Future Afro‑European / Eurasian candidates; keep out of SUPPORTED_LANGUAGES until translated:
+  // "ig", // Igbo
+  // "om", // Oromo
+  // "so", // Somali
+  // "ti", // Tigrinya
+  // "wo", // Wolof
+];
+
+/**
+ * Autonym map.
+ *
+ * Each language is named in its own language so that a user only
+ * needs to know their own language to find it in the selector.
+ */
+export const AUTONYM_MAP: Record<LanguageCode, string> = {
+  en: "English",
+  bg: "български",
+  cs: "čeština",
+  da: "dansk",
+  de: "Deutsch",
+  el: "Ελληνικά",
+  es: "español",
+  et: "eesti",
+  he: "עברית",
+  ar: "العربية",
+  fa: "فارسی",
+  sw: "Kiswahili",
+  ha: "Hausa",
+  am: "አማርኛ",
+  yo: "Yorùbá",
+  zu: "isiZulu",
+  ma: "Darija",
+  fi: "suomi",
+  fr: "français",
+  ga: "Gaeilge",
+  hr: "hrvatski",
+  hu: "magyar",
+  is: "íslenska",
+  it: "italiano",
+  lt: "lietuvių",
+  lv: "latviešu",
+  mt: "Malti",
+  nl: "Nederlands",
+  no: "norsk",
+  pl: "polski",
+  pt: "português",
+  ro: "română",
+  ru: "русский",
+  sk: "slovenčina",
+  sl: "slovenščina",
+  sr: "српски",
+  sv: "svenska",
+  tr: "Türkçe",
+  uk: "українська",
+  bs: "bosanski",
+  mk: "македонски",
+  ka: "ქართული", // Georgian
+  kk: "қазақ тілі", // Kazakh
+  uz: "oʻzbekcha", // Uzbek
+  ig: "Igbo", // Igbo
+  om: "Afaan Oromoo", // Oromo
+  so: "Af-Soomaali", // Somali
+  ti: "ትግርኛ", // Tigrinya
+  wo: "Wolof", // Wolof
+};
+
+/**
+ * Normalize a full locale (e.g. "en-GB") down to a `LanguageCode`.
+ *
+ * - Uses the first segment of the locale (before "-")
+ * - Falls back to "en" if the language is unsupported or invalid
+ */
+export const normalizeLocaleToLanguage = (
+  locale: string | null | undefined,
+): LanguageCode => {
+  if (!locale) return "en";
+  const lang = locale.split("-")[0]?.toLowerCase() ?? "en";
+
+  if (SUPPORTED_LANGUAGES.includes(lang as LanguageCode)) {
+    return lang as LanguageCode;
+  }
+
+  return "en";
+};
+
+/**
+ * Build a stable list of language options for UI components
+ * such as dropdowns.
+ */
+export type LanguageOption = {
+  code: LanguageCode;
+  autonym: string;
+};
+
+export const getLanguageOptions = (): LanguageOption[] =>
+  [...SUPPORTED_LANGUAGES]
+    .map((code) => ({
+      code,
+      autonym: AUTONYM_MAP[code],
+    }))
+    .sort((a, b) => a.autonym.localeCompare(b.autonym));
+
+/**
+ * Utility to derive i18next `supportedLngs` from our language codes,
+ * so configuration can import from this module instead of hardcoding
+ * the list in multiple places.
+ */
+export const getSupportedLngsForI18Next = (): Resource["en"] extends never
+  ? string[]
+  : string[] => {
+  // i18next accepts string[], while we keep a stricter LanguageCode[]
+  return [...SUPPORTED_LANGUAGES];
+};
+
+/**
+ * Languages whose natural writing direction is right-to-left.
+ *
+ * This is used by layout code (outside this module) to switch
+ * document direction and RTL-aware styling when needed.
+ */
+export const RTL_LANGUAGES: LanguageCode[] = ["he", "ar", "fa", "ma"];
+
+/**
+ * Utility to check whether a given language code is RTL.
+ */
+export const isRtlLanguage = (code: LanguageCode): boolean =>
+  RTL_LANGUAGES.includes(code);

helexa.ai/src/i18n/resources/am/chat.json

@@ -0,0 +1,17 @@
+{
+  "title": "የውይይት ቦታ",
+  "badge": "ውይይት",
+  "lead": "ይህ የውይይት እይታ ነው። የውይይት ሎጂክዎን እና የተጠቃሚ በስተጀርባ ክፍሎችን ወደዚህ ገፅ ያገናኙ።",
+  "transcriptPlaceholder": "የውይይቱ ሪኮርድ እዚህ ይታያል። የሞዴሉን እና የተጠቃሚውን መልዕክቶች በሚንቀሳቀስ ኮንቴይነር ውስጥ ያቀርቡ፣  приወይም በዙር ዙር በመከፈል ማቅረብ ይችላሉ።",
+  "inputPlaceholder": "ውይይትን ለመጀምር መልዕክት ይፃፉ…",
+  "send": "መላክ",
+  "clear": "ማጽዳት",
+  "newChat": "New chat",
+  "newProject": "New project",
+  "newProjectName": "New project",
+  "unsorted": "Unsorted",
+  "emptyState": "Start a conversation. Your history stays in this browser.",
+  "anonBanner": "You have reached the anonymous limit. Sign up for a free allocation.",
+  "signUp": "Sign up",
+  "stop": "Stop"
+}

helexa.ai/src/i18n/resources/am/common.json

@@ -0,0 +1,63 @@
+{
+  "app": {
+    "name": "helexa.ai"
+  },
+  "nav": {
+    "home": "መነሻ ገፅ",
+    "docs": "ሰነዶች",
+    "chat": "ውይይት",
+    "mission": "Mission",
+    "login": "Sign in",
+    "register": "Sign up",
+    "account": "Account",
+    "logout": "Sign out"
+  },
+  "theme": {
+    "toggle": {
+      "toLight": "ወደ ብርሃን ሁኔታ መቀየር",
+      "toDark": "ወደ ጨለማ ሁኔታ መቀየር"
+    }
+  },
+  "lang": {
+    "bg": "ቡልጋሪኛ",
+    "de": "ጀርመንኛ",
+    "el": "ግሪከኛ",
+    "en": "እንግሊዝኛ",
+    "es": "ስፓኒሽኛ",
+    "et": "ኤስቶኒያን",
+    "fr": "ፈረንሳይኛ",
+    "he": "እብራስጥ",
+    "it": "ጣሊያንኛ",
+    "nl": "ደችኛ",
+    "da": "ዴኒሽኛ",
+    "fi": "ፊኒሽኛ",
+    "no": "ኖርዌጂያንኛ",
+    "sv": "ስዊድንኛ",
+    "ar": "ዐርቢኛ",
+    "fa": "ፐርሺያኛ",
+    "sw": "ስዋሂሊኛ",
+    "ha": "ሃውሳኛ",
+    "am": "አማርኛ",
+    "yo": "ዮሩባ",
+    "zu": "ዙሉ",
+    "ma": "ዳሪጃ",
+    "ig": "ኢግቦኛ",
+    "ka": "ጊዮርጂያንኛ",
+    "kk": "ካዛክኛ",
+    "om": "ኦሮሞኛ",
+    "so": "ሶማሊኛ",
+    "ti": "ትግርኛ",
+    "uz": "ኡዝቤክኛ",
+    "wo": "ዎሎፍኛ",
+    "pl": "ፖሊሽኛ",
+    "pt": "ፖርቱጋልኛ",
+    "ro": "ሮማኒያን",
+    "ru": "ራሽኛ",
+    "sr": "ሰርቢኛ",
+    "tr": "ቱርክኛ",
+    "uk": "ዩክሬንኛ"
+  },
+  "footer": {
+    "copyright": "© {{year}} helexa.ai"
+  }
+}

helexa.ai/src/i18n/resources/am/mission.json

@@ -0,0 +1,103 @@
+{
+  "hero": {
+    "badge": "አዲስ የአእምሮ ቅርጽ",
+    "title": "አዲስ የአእምሮ ቅርጽ",
+    "lead": "Helexa በተገናኙ ነጻ ኦፕሬተሮች የሚነሳ ራሷን የሚያደርግ የኤ.አይ. መረብ ነው። ክፍት ነው። ተበታተነ። በመደጋገም ይቀየራል።",
+    "ctaJoinMesh": "ወደ መረቡ ይቀላቀሉ",
+    "ctaFollowProject": "ፕሮጀክቱን ይከተሉ",
+    "subcopy": "AI ክፍት፣ ጠንካራ እና የሚጋራ መሆን አለበት በሚሉ ለኦፕሬተሮች፣ ለአበልጣጫዎች እና ለማህበረሰቦች ተሠርቷል።",
+    "imageAlt": "የHelexa ሄሊክስ ምስል"
+  },
+
+  "intent": {
+    "title": "Helexa ለምን አለች",
+    "p1": "AI በምድር ላይ በጣም ኃይለኛው መሠረታዊ መዋቅር እየሆነ ነው። ነገር ግን ዛሬ፣ ያ ኃይል በግል ቅድሚያዎች፣ በጂኦግራፊያዊ ገደቦች እና በደካማ ኢኮኖሚዎች የተሳሰበ በጥቂት ኩባንያዎች ውስጥ ተሰብስቧል።",
+    "p2Intro": "Helexa የተለየ ነገር ታስባለች፦",
+    "bullet1": "ከአንድ ቦታ ሳይሆን ከሁሉም ቦታ የሚያድግ አእምሮ።",
+    "bullet2": "ማንኛውም ሰው ሊያስተዋውቅበትና ሊጠቀምበት የሚችለው መረብ።",
+    "bullet3": "በትእዛዝ ሳይሆን በፍላጎት ላይ የሚማር ስርዓት።",
+    "bullet4": "ማህበረሰቦችን ለመተካት ሳይሆን የሚጠናከል ቴክኖሎጂ።",
+    "closing": "Helexa መድረክ አይደለችም። ደመና አይደለችም።\nመረብ ነች — የተወለደ እና የሚሻሻል የነጻ ኦፕሬተሮች መረብ ሆና አዲስ ዓይነት አእምሮ የምታቀና."
+  },
+
+  "whyNow": {
+    "title": "ለAI የሚለው የመቀየር ጊዜ",
+    "problemTitle": "ችግኙ",
+    "problemBullet1": "AI ከቀድሞው ማንኛውም ቴክኖሎጂ የማይተካ ፍጥነት በመሰብሰብ ላይ ነው።",
+    "problemBullet2": "የኮምፒውተር ኃይል መዳረሻ ችሎታን ያወራል፣ ይህም መዳረሻ ግን በቀስታ እየተጠበቀ ነው።",
+    "problemBullet3": "የወጪ መከልከያዎች ምርምር እና የኢንተርፕራይዝ ጀማሪዎችን እና ማህበረሰቦችን እያወጡ ነው።",
+    "problemBullet4": "የጄኦፖለቲካ እና የህግ ግፊት የዓለም አቀፍ መዳረሻን እያቀረበ ነው።",
+    "problemBullet5": "የሞዴሎች ፈጣሪዎችና የሀርድዌር ኦፕሬተሮች ብዙ ጊዜ በራሳቸው የሚፈጥሩትን ዋጋ አያጋሩም።",
+    "opportunityTitle": "እድሉ",
+    "opportunityIntro": "ግን የተሰራጨ ዓለም የሚቻል ነው።",
+    "opportunityBullet1": "ሺዎች የሚቆጠሩ የGPU ካርዶች በዓለም ዙሪያ አሁንም በትንሽ እየተጠቀሙባቸው ነው።",
+    "opportunityBullet2": "ኦፕሬተሮች ለየሚሰጡት ኮምፒውተር ኃይል እውነተኛ እና ፍትሃዊ ክፍያ ይፈልጋሉ።",
+    "opportunityBullet3": "ዲቨሎፐሮች ክፍት እና ከመቆጣጠር የተጠበቀ መሠረታዊ መዋቅር ይፈልጋሉ።",
+    "opportunityBullet4": "ማህበረሰቦች በዲጂታል ስርዓቶቻቸው ውስጥ ስብስብ መንግስታዊነትን እና ጽኑ መሆን ይፈልጋሉ።",
+    "opportunityBullet5": "የAI እድገት ባለመለኪያ ሁኔታ ከባለሙያ ደመናዎች በላይ ቀድሞ ሄዷል — አዳዲስ ቅርጾች ያስፈልጋሉ።",
+    "opportunityClosing": "Helexa እነዚህ ኃይሎች በአንድ ጊዜ የሚገናኙበት ጊዜ ነው።"
+  },
+
+  "howItWorks": {
+    "title": "መረቡ እንዴት እንደሚሰራ",
+    "operators": {
+      "eyebrow": "ኦፕሬተሮች ኖዶችን ይያዙ",
+      "title": "ማንኛውም ሰው የኮምፒውተር ኃይል ሊያቀርብ ይችላል።",
+      "body": "ኦፕሬተሮች የHelexa ኖዶችን ያስኬዳሉ። የማንኛውንም ሞዴል እንዲሰሩ ያስችላሉ። በሀርድዌሩና በኢኮኖሚያዊ ውሳኔዎቻቸው ላይ ቁጥጥር ይጠብቃሉ። ምንም የፈቃድ ሂደት የለም፣ ጠባቂ መከላከያ የለም።"
+    },
+    "routing": {
+      "eyebrow": "መረቡ አእምሮን ይመራል",
+      "title": "ፍላጎት በመረቡ ውስጥ ይፈሳሳል።",
+      "body": "Helexa እየማረከች የቆየበት አቅም ወዴት እንደሚገኝ፣ ፍላጎት የሚጨምርበት ቦታ የት እንደሆነ እና ምን ኖድ ለማቅረብ ተስማሚ እንደሆነ ትማራለች። መረቡ በተፈጥሯዊ መንገድ ይለመዳል — እያደገ ያለ ሄሊክስ እንደሆነ።"
+    },
+    "value": {
+      "eyebrow": "ዋጋው ወደ ኋላ ይመለሳል",
+      "title": "ሥራ ታረጋገጠ። ክፍያ ፍትሃዊ ነው።",
+      "body": "እያንዳንዱ ስራ ክሪፕቶግራፊ የተፈረመ ደረሰኝ ይይዛል። ኦፕሬተሮች በሚሰጡት አእምሮ ላይ ገንዘብ ያገኛሉ። የመድረክ ታክስ የለም። ግልጽ ካልሆነ የክፍያ ሂደት የለም።"
+    }
+  },
+
+  "principles": {
+    "title": "በመድረኮች ላይ ሳይሆን በመርሆዎች ላይ የተገነባ",
+    "distributed": {
+      "title": "በንድፍ የተበታተነ",
+      "body": "አንድ የብቻ የእርምጃ መደበቂያ የለም። ማዕከላዊ ሥልጣን የለም። በእያንዳንዱ አዲስ ኦፕሬተር ጋር የሚጠናከር መረብ ነው።"
+    },
+    "participation": {
+      "title": "ተሳትፎ ለሁሉም ክፍት",
+      "body": "ኮምፒውተር ኃይል ካለህ ልዩ ልዩ ድርሻ ሊያስተዋውቅ ትችላለህ። መረቡ ሁሉንም ይቀበላል — ከኤጀጅ መሣሪያዎች፣ እስከ የቤት አገልጋዮች እና የዳታ ማእከላት ድረስ።"
+    },
+    "fairness": {
+      "title": "ፍትህና ተመልካችነት",
+      "body": "ገቢዎች በእውነተኛ ስራ ላይ ተመስርተዋል፣ በክሪፕቶግራፊ መሠረት ተረጋግጠዋል። ጥቁር ሳጥን የለም። የተደበቀ ክፍያ የለም።"
+    },
+    "evolving": {
+      "title": "የሚያድግ አእምሮ",
+      "body": "መረቡ ከፍላጎት ይማራል። ሞዴሎች የሚፈለጉበት ቦታ ላይ ይጫናሉ። አእምሮ በተባባሪነት ይበተናል።"
+    }
+  },
+
+  "roadAhead": {
+    "title": "Helexa ምን ለመሆን እየተሻሻለች ነው",
+    "p1": "ለሁሉም የሚያገለግል የዓለም አቀፍ የአእምሮ ንብርብር፣ በሄሊክስ ያለ የኖዶችና የማህበረሰቦች መረብ የሚደገፍ።",
+    "p2": "ማቋረጥ፣ ፖለቲካ፣ ነጠላ ባለቤቶች እና ወደፊት ሊከሰት በሚችል እንኳን የሚቋቋም መረብ።",
+    "p3": "ኦፕሬተሮች፣ አበልጣጫዎች እና ተጠቃሚዎች ሁሉም ተዋጊ የሚሆኑበት አዲስ የኢኮኖሚ ሞዴል።",
+    "p4": "ፈጠራ ከጠርዝ የሚያድግ፣ ከማዕከል ሳይሆን፣ የሥራ አካባቢ ኢኮሲስተም።",
+    "card": {
+      "eyebrow": "የራዕይ አጭር እትም",
+      "title": "ወደ የተጋራ የአእምሮ መረብ",
+      "body": "Helexa ገና በቀዳሚ ደረጃ ላይ ይ beታል። ሀሳቦቹ ከአሁን እና ከተፈጠረው ተቀባይነት የበለጠ ትልቅ ናቸው — ይህም በተወሰነ ዓላማ ነው። መረቡ በእያንዳንዱ ደረጃ ይበቃል፣ ኦፕሬተሮችና አበልጣጫዎችም እድገቷን በጋራ ይፀናሉ።"
+    }
+  },
+
+  "joinMesh": {
+    "badge": "የመጀመሪያ ደረጃ",
+    "title": "መረቡ እየተፈጠረ ነው።",
+    "titleHighlight": "እርስዎም ክፍል ሆነው ሊሳተፉበት ይችላሉ።",
+    "lead": "ሀርድዌር ብትከናወኑ፣ ሞዴሎችን ብታበርኩ፣ ወይም በአጠቃላይ AI እንዴት እንደሚመራ ብታስቡ ሆነው፣ በዚህ መረብ ውስጥ ለእርስዎ የተዘጋበ ቦታ አለ።",
+    "ctaRunNode": "ኖድ ያስኬዱ (በቅርቡ)",
+    "ctaJoinAnnouncements": "የቀድሞ ማስታወቂያዎችን ይቀበሉ",
+    "ctaExploreCode": "ኮድን ያስሱ",
+    "footer": "የተጣሉ ፍራንቻዎች የሉም። አንድ ብቻ ባለቤት የለም። የሚመጣውን የአእምሮ ወደፊት በሚያቀና መልኩ በሰዎች፣ በሀርድዌር እና በሀሳቦች የተሠራ መረብ ብቻ ነው።"
+  }
+}

helexa.ai/src/i18n/resources/ar/chat.json

@@ -0,0 +1,17 @@
+{
+  "title": "مساحة محادثة",
+  "badge": "محادثة",
+  "lead": "هذه هي واجهة المحادثة. قم بتوصيل منطق الحوار الخاص بك ومكوّنات واجهة المستخدم بهذه الصفحة.",
+  "transcriptPlaceholder": "سجل المحادثة سيظهر هنا. اعرض رسائل النموذج والمستخدم في حاوية قابلة للتمرير، ويمكنك تجميعها حسب أدوار الحوار إذا رغبت.",
+  "inputPlaceholder": "اكتب رسالة لبدء المحادثة…",
+  "send": "إرسال",
+  "clear": "مسح",
+  "newChat": "New chat",
+  "newProject": "New project",
+  "newProjectName": "New project",
+  "unsorted": "Unsorted",
+  "emptyState": "Start a conversation. Your history stays in this browser.",
+  "anonBanner": "You have reached the anonymous limit. Sign up for a free allocation.",
+  "signUp": "Sign up",
+  "stop": "Stop"
+}

helexa.ai/src/i18n/resources/ar/common.json

@@ -0,0 +1,63 @@
+{
+  "app": {
+    "name": "helexa.ai"
+  },
+  "nav": {
+    "home": "الصفحة الرئيسية",
+    "docs": "التوثيق",
+    "chat": "المحادثة",
+    "mission": "Mission",
+    "login": "Sign in",
+    "register": "Sign up",
+    "account": "Account",
+    "logout": "Sign out"
+  },
+  "theme": {
+    "toggle": {
+      "toLight": "التبديل إلى الوضع الفاتح",
+      "toDark": "التبديل إلى الوضع الداكن"
+    }
+  },
+  "lang": {
+    "bg": "البلغارية",
+    "de": "الألمانية",
+    "el": "اليونانية",
+    "en": "الإنجليزية",
+    "es": "الإسبانية",
+    "et": "الإستونية",
+    "fr": "الفرنسية",
+    "he": "العبرية",
+    "it": "الإيطالية",
+    "nl": "الهولندية",
+    "da": "الدنماركية",
+    "fi": "الفنلندية",
+    "ar": "العربية",
+    "fa": "الفارسية",
+    "sw": "السواحيلية",
+    "ha": "الهوسا",
+    "am": "الأمهرية",
+    "yo": "اليوربا",
+    "zu": "الزولو",
+    "ma": "الدارجة المغربية",
+    "ig": "الإيجبو",
+    "ka": "الجورجية",
+    "kk": "الكازاخية",
+    "no": "النرويجية",
+    "om": "الأورومو",
+    "so": "الصومالية",
+    "sv": "السويدية",
+    "ti": "التيغرينية",
+    "uz": "الأوزبكية",
+    "wo": "الولوف",
+    "pl": "البولندية",
+    "pt": "البرتغالية",
+    "ro": "الرومانية",
+    "ru": "الروسية",
+    "sr": "الصربية",
+    "tr": "التركية",
+    "uk": "الأوكرانية"
+  },
+  "footer": {
+    "copyright": "© {{year}} helexa.ai"
+  }
+}

helexa.ai/src/i18n/resources/ar/mission.json

@@ -0,0 +1,103 @@
+{
+  "hero": {
+    "badge": "شكل جديد من الذكاء",
+    "title": "شكل جديد من الذكاء",
+    "lead": "هيليكسـا هي شبكة ذكاء اصطناعي ذاتية التنظيم، يشغّلها مشغّلون مستقلون. مفتوحة. موزعة. تتطور باستمرار.",
+    "ctaJoinMesh": "انضم إلى الشبكة",
+    "ctaFollowProject": "تابع المشروع",
+    "subcopy": "صُممت للمشغّلين والبنّائين والمجتمعات التي تؤمن بأن الذكاء الاصطناعي يجب أن يكون مفتوحًا، مرنًا، ومشتركًا.",
+    "imageAlt": "تصور حلزوني لشكل Helexa"
+  },
+
+  "intent": {
+    "title": "لماذا وُجدت Helexa",
+    "p1": "الذكاء الاصطناعي يتحول إلى أقوى بنية تحتية على كوكب الأرض. لكن اليوم، هذه القوة مركّزة في أيدي عدد قليل من الشركات، تشكلها أولويات خاصة، وحدود جغرافية، واقتصادات هشة.",
+    "p2Intro": "هيليكسـا تتخيل شيئًا مختلفًا:",
+    "bullet1": "ذكاء ينمو من كل مكان، لا من نقطة واحدة.",
+    "bullet2": "شبكة يمكن للجميع فيها أن يساهموا ويستفيدوا.",
+    "bullet3": "نظام يتكيّف مع الطلب، لا مع الأوامر الفوقية.",
+    "bullet4": "تكنولوجيا تقوّي المجتمعات بدلًا من أن تستبدلها.",
+    "closing": "هيليكسـا ليست منصة. وليست سحابة.\nإنها شبكة — نسيج حيّ ومتطوّر من مشغّلين مستقلين يشكّلون نوعًا جديدًا من الذكاء."
+  },
+
+  "whyNow": {
+    "title": "نقطة تحوّل للذكاء الاصطناعي",
+    "problemTitle": "المشكلة",
+    "problemBullet1": "الذكاء الاصطناعي يتمركز أسرع من أي تكنولوجيا سبقته.",
+    "problemBullet2": "الوصول إلى القدرة الحاسوبية يحدد الإمكانات، وهذا الوصول يضيق باستمرار.",
+    "problemBullet3": "حواجز التكلفة تستبعد الباحثين والشركات الناشئة والمجتمعات.",
+    "problemBullet4": "الضغوط الجيوسياسية والتنظيمية تهدّد التوافر العالمي.",
+    "problemBullet5": "مُنشئو النماذج ومشغّلو العتاد نادرًا ما يشاركون في القيمة التي ينتجونها.",
+    "opportunityTitle": "الفرصة",
+    "opportunityIntro": "لكن عالمًا موزعًا ممكن.",
+    "opportunityBullet1": "آلاف وحدات الـGPU حول العالم تعمل بأقل من طاقتها.",
+    "opportunityBullet2": "المشغّلون يريدون تعويضًا عادلًا عن الحوسبة التي يقدّمونها.",
+    "opportunityBullet3": "المطورون يريدون بنية تحتية مفتوحة ومقاوِمة للرقابة.",
+    "opportunityBullet4": "المجتمعات تريد سيادة ومرونة في أنظمتها الرقمية.",
+    "opportunityBullet5": "نمو الذكاء الاصطناعي تجاوز البنى السحابية التقليدية — نحن بحاجة إلى أشكال جديدة.",
+    "opportunityClosing": "هيليكسـا هي لحظة تلاقي هذه القوى."
+  },
+
+  "howItWorks": {
+    "title": "كيف تتشكّل الشبكة",
+    "operators": {
+      "eyebrow": "المشغّلون يديرون العقد",
+      "title": "أي شخص يمكنه المساهمة بقوة حاسوبية.",
+      "body": "المشغّلون يشغّلون عُقد Helexa. يقررون أي النماذج يستضيفون. يبقون متحكمين في عتادهم واقتصادهم. لا موافقات، ولا حراس بوابة."
+    },
+    "routing": {
+      "eyebrow": "الشبكة توجّه الذكاء",
+      "title": "الطلب يتدفق عبر الشبكة.",
+      "body": "هيليكسـا تتعلم أين توجد السعة، وأين يرتفع الطلب، وأي العقد أنسب لخدمة الطلبات. الشبكة تتكيّف بشكل عضوي — مثل حلزون ينمو."
+    },
+    "value": {
+      "eyebrow": "القيمة تعود إلى المصدر",
+      "title": "العمل مُثبت. والدفع عادل.",
+      "body": "كل مهمة تحمل إيصالًا تشفيريًا. يكسب المشغّلون مقابل الذكاء الذي يساعدون في توفيره. لا ضرائب منصة. لا فواتير غامضة."
+    }
+  },
+
+  "principles": {
+    "title": "مبنية على مبادئ، لا على منصات",
+    "distributed": {
+      "title": "موزعة بالتصميم",
+      "body": "لا توجد نقطة فشل واحدة. لا توجد سلطة مركزية. شبكة تقوى مع كل مشغّل جديد."
+    },
+    "participation": {
+      "title": "مشاركة مفتوحة",
+      "body": "إذا كان لديك قدرة حاسوبية، يمكنك المساهمة. الشبكة ترحّب بالجميع — من الحافة، إلى الخوادم المنزلية، إلى مراكز البيانات."
+    },
+    "fairness": {
+      "title": "العدالة والشفافية",
+      "body": "الأرباح مبنية على عمل حقيقي، مُثبت تشفيريًا. لا صناديق سوداء. لا رسوم خفية."
+    },
+    "evolving": {
+      "title": "ذكاء يتطور باستمرار",
+      "body": "الشبكة تتعلم من الطلب. تُحمَّل النماذج حيث تكون مطلوبة. الذكاء ينتشر من خلال التعاون."
+    }
+  },
+
+  "roadAhead": {
+    "title": "إلى ماذا تطمح Helexa أن تصبح",
+    "p1": "طبقة ذكاء عالمية تنتمي للجميع، مدفوعة بحلزونة من العقد والمجتمعات.",
+    "p2": "شبكة مقاومة للانقطاعات، والسياسة، والاحتكارات، والإخفاق.",
+    "p3": "نموذج اقتصادي جديد يستفيد منه المشغّلون والبنّاؤون والمستخدمون جميعًا.",
+    "p4": "نظام بيئي تنمو فيه الابتكارات من الأطراف — لا من المركز.",
+    "card": {
+      "eyebrow": "لمحة عن الرؤية",
+      "title": "نحو شبكة ذكاء مشتركة",
+      "body": "هيليكسـا في مرحلة مبكرة. الأفكار أكبر من التنفيذ الحالي — وهذا مقصود. الشبكة ستنمو تدريجيًا، بينما يشكّل المشغّلون والبنّاؤون مسار تطورها."
+    }
+  },
+
+  "joinMesh": {
+    "badge": "مرحلة مبكرة",
+    "title": "الشبكة قيد التشكل.",
+    "titleHighlight": "ويمكنك أن تكون جزءًا منها.",
+    "lead": "سواءً كنت تدير عتادًا، تبني نماذج، أو يهمّك ببساطة كيف يُدار الذكاء الاصطناعي — هناك مكان لك داخل الشبكة.",
+    "ctaRunNode": "تشغيل عقدة (قريبًا)",
+    "ctaJoinAnnouncements": "انضم إلى الإعلانات المبكرة",
+    "ctaExploreCode": "استكشف الشفرة",
+    "footer": "لا حدائق مسوّرة. لا مالك واحد. مجرد شبكة من أشخاص وعتاد وأفكار — تصوغ مستقبلًا مختلفًا للذكاء."
+  }
+}

helexa.ai/src/i18n/resources/bg/chat.json

@@ -0,0 +1,17 @@
+{
+  "title": "Работно пространство за разговори",
+  "badge": "Чат",
+  "lead": "Това е изгледът за чат. Тук можеш да свържеш своята логика за разговори и потребителски интерфейс.",
+  "transcriptPlaceholder": "Тук ще се показва историята на чата. Визуализирай съобщенията от модела и потребителя в превъртащ се контейнер, по желание групирани по ход.",
+  "inputPlaceholder": "Напиши съобщение, за да започнеш разговора…",
+  "send": "Изпрати",
+  "clear": "Изчисти",
+  "newChat": "New chat",
+  "newProject": "New project",
+  "newProjectName": "New project",
+  "unsorted": "Unsorted",
+  "emptyState": "Start a conversation. Your history stays in this browser.",
+  "anonBanner": "You have reached the anonymous limit. Sign up for a free allocation.",
+  "signUp": "Sign up",
+  "stop": "Stop"
+}

helexa.ai/src/i18n/resources/bg/common.json

@@ -0,0 +1,63 @@
+{
+  "app": {
+    "name": "helexa.ai"
+  },
+  "nav": {
+    "home": "Начало",
+    "docs": "Документация",
+    "chat": "Чат",
+    "mission": "Mission",
+    "login": "Sign in",
+    "register": "Sign up",
+    "account": "Account",
+    "logout": "Sign out"
+  },
+  "theme": {
+    "toggle": {
+      "toLight": "Превключване към светла тема",
+      "toDark": "Превключване към тъмна тема"
+    }
+  },
+  "lang": {
+    "bg": "български",
+    "de": "немски",
+    "el": "гръцки",
+    "en": "английски",
+    "es": "испански",
+    "et": "естонски",
+    "fr": "френски",
+    "he": "иврит",
+    "it": "италиански",
+    "nl": "Нидерландски",
+    "da": "Датски",
+    "fi": "Фински",
+    "no": "Норвежки",
+    "sv": "Шведски",
+    "ar": "Арабски",
+    "fa": "персийски",
+    "sw": "суахили",
+    "ha": "хауза",
+    "am": "амхарски",
+    "yo": "йоруба",
+    "zu": "зулу",
+    "ma": "дариджа",
+    "ig": "игбо",
+    "ka": "грузински",
+    "kk": "казахски",
+    "om": "оромо",
+    "so": "сомалийски",
+    "ti": "тигриња",
+    "uz": "узбекски",
+    "wo": "волоф",
+    "pl": "полски",
+    "pt": "португалски",
+    "ro": "румънски",
+    "ru": "руски",
+    "sr": "сръбски",
+    "tr": "турски",
+    "uk": "украински"
+  },
+  "footer": {
+    "copyright": "© {{year}} helexa.ai"
+  }
+}

helexa.ai/src/i18n/resources/bg/mission.json

@@ -0,0 +1,103 @@
+{
+  "hero": {
+    "badge": "Нова форма на интелигентност",
+    "title": "Нова форма на интелигентност",
+    "lead": "Helexa е самоорганизираща се AI мрежа, задвижвана от независими оператори. Отворена. Разпределена. Еволюираща.",
+    "ctaJoinMesh": "Присъедини се към мрежата",
+    "ctaFollowProject": "Следвай проекта",
+    "subcopy": "Създадена за оператори, разработчици и общности, които вярват, че AI трябва да бъде отворен, устойчив и споделен.",
+    "imageAlt": "Визуализация на хеликса на Helexa"
+  },
+
+  "intent": {
+    "title": "Защо съществува Helexa",
+    "p1": "AI се превръща в най-мощната инфраструктура на Земята. Но днес тази сила е концентрирана в шепа корпорации, оформяна от частни приоритети, географски ограничения и крехка икономика.",
+    "p2Intro": "Helexa си представя нещо различно:",
+    "bullet1": "Интелигентност, която расте от всякъде, не от едно място.",
+    "bullet2": "Мрежа, в която всеки може да допринася и да се възползва.",
+    "bullet3": "Система, която се адаптира към търсенето, не към заповеди.",
+    "bullet4": "Технология, която подсилва общностите вместо да ги заменя.",
+    "closing": "Helexa не е платформа. Не е и облак.\nТя е мрежа — жива, еволюираща решетка от независими оператори, която оформя нов вид интелигентност."
+  },
+
+  "whyNow": {
+    "title": "Преломен момент за AI",
+    "problemTitle": "Проблемът",
+    "problemBullet1": "AI се централизира по-бързо от всяка предишна технология.",
+    "problemBullet2": "Достъпът до изчислителни ресурси определя възможностите, а достъпът се стеснява.",
+    "problemBullet3": "Ценовите бариери изключват изследователи, стартъпи и общности.",
+    "problemBullet4": "Геополитически и регулаторни натиск застрашават глобалната достъпност.",
+    "problemBullet5": "Създателите на модели и операторите на хардуер рядко споделят стойността, която създават.",
+    "opportunityTitle": "Възможността",
+    "opportunityIntro": "Но един разпределен свят е възможен.",
+    "opportunityBullet1": "Хиляди GPU машини вече са недоизползвани по целия свят.",
+    "opportunityBullet2": "Операторите искат честно заплащане за изчислителната си мощ.",
+    "opportunityBullet3": "Разработчиците искат отворена, устойчива на цензура инфраструктура.",
+    "opportunityBullet4": "Общностите искат суверенитет и устойчивост в дигиталните системи.",
+    "opportunityBullet5": "Ръстът на AI изпревари традиционните облаци — нужни са нови форми.",
+    "opportunityClosing": "Helexa е моментът, в който тези сили се подравняват."
+  },
+
+  "howItWorks": {
+    "title": "Как се формира мрежата",
+    "operators": {
+      "eyebrow": "Операторите стартират възли",
+      "title": "Всеки може да допринесе с изчислителна мощ.",
+      "body": "Операторите стартират възли на Helexa. Те решават кои модели да хостват. Остават в контрол над своя хардуер и своята икономика. Без одобрения, без посредници."
+    },
+    "routing": {
+      "eyebrow": "Мрежата маршрутизира интелигентността",
+      "title": "Търсенето тече през мрежата.",
+      "body": "Helexa научава къде има капацитет, къде търсенето нараства и кои възли са най-подходящи да обслужват заявките. Мрежата се адаптира органично — като растяща спирала."
+    },
+    "value": {
+      "eyebrow": "Стойността се връща обратно",
+      "title": "Работата е доказуема. Заплащането е честно.",
+      "body": "Всяка задача носи криптографско потвърждение. Операторите печелят за интелигентността, която помагат да се предостави. Без платформи данъкоплатци. Без непрозрачни сметки."
+    }
+  },
+
+  "principles": {
+    "title": "Изградена върху принципи, не върху платформи",
+    "distributed": {
+      "title": "Разпределена по замисъл",
+      "body": "Без една-единствена точка на отказ. Без централен орган. Мрежа, която става по-силна с всеки нов оператор."
+    },
+    "participation": {
+      "title": "Отворено участие",
+      "body": "Ако имаш изчислителни ресурси, можеш да допринесеш. Мрежата посреща всички — edge устройства, домашни сървъри, центрове за данни."
+    },
+    "fairness": {
+      "title": "Справедливост и прозрачност",
+      "body": "Приходите се базират на реална свършена работа, криптографски потвърдена. Без черни кутии. Без скрити такси."
+    },
+    "evolving": {
+      "title": "Еволюираща интелигентност",
+      "body": "Мрежата учи от търсенето. Моделите се зареждат там, където са нужни. Интелигентността се разпространява чрез сътрудничество."
+    }
+  },
+
+  "roadAhead": {
+    "title": "Какво цели да стане Helexa",
+    "p1": "Глобален слой от интелигентност, който принадлежи на всички, задвижван от спирала от възли и общности.",
+    "p2": "Мрежа, устойчива на сривове, политика, монополи и провали.",
+    "p3": "Нов икономически модел, в който оператори, създатели и потребители печелят заедно.",
+    "p4": "Екосистема, в която иновациите растат от периферията — не от центъра.",
+    "card": {
+      "eyebrow": "Миг от визията",
+      "title": "Към споделена мрежа от интелигентност",
+      "body": "Helexa е в ранен етап. Идеите са по-големи от реализацията — и това е умишлено. Мрежата ще расте итеративно, оформяна от операторите и разработчиците."
+    }
+  },
+
+  "joinMesh": {
+    "badge": "Ранен етап",
+    "title": "Мрежата се формира.",
+    "titleHighlight": "Ти можеш да бъдеш част от нея.",
+    "lead": "Независимо дали управляваш хардуер, изграждаш модели или просто ти пука как се управлява AI, има място за теб в мрежата.",
+    "ctaRunNode": "Пусни възел (скоро)",
+    "ctaJoinAnnouncements": "Включи се в ранните известия",
+    "ctaExploreCode": "Разгледай кода",
+    "footer": "Без оградени градини. Без един собственик. Само мрежа от хора, хардуер и идеи — които заедно създават различно бъдеще за интелигентността."
+  }
+}

helexa.ai/src/i18n/resources/da/chat.json

@@ -0,0 +1,17 @@
+{
+  "title": "Samtalearbejdsområde",
+  "badge": "Chat",
+  "lead": "Dette er chatvisningen. Tilføj din samtalelogik og dine UI‑komponenter til denne side.",
+  "transcriptPlaceholder": "Chattransskriptionen vises her. Gengiv beskeder fra modellen og brugeren i en rullende container, eventuelt grupperet efter tur.",
+  "inputPlaceholder": "Skriv en besked for at starte en chat…",
+  "send": "Send",
+  "clear": "Ryd",
+  "newChat": "New chat",
+  "newProject": "New project",
+  "newProjectName": "New project",
+  "unsorted": "Unsorted",
+  "emptyState": "Start a conversation. Your history stays in this browser.",
+  "anonBanner": "You have reached the anonymous limit. Sign up for a free allocation.",
+  "signUp": "Sign up",
+  "stop": "Stop"
+}

helexa.ai/src/i18n/resources/da/common.json

@@ -0,0 +1,63 @@
+{
+  "app": {
+    "name": "helexa.ai"
+  },
+  "nav": {
+    "home": "Hjem",
+    "docs": "Dokumentation",
+    "chat": "Chat",
+    "mission": "Mission",
+    "login": "Sign in",
+    "register": "Sign up",
+    "account": "Account",
+    "logout": "Sign out"
+  },
+  "theme": {
+    "toggle": {
+      "toLight": "Skift til lyst tema",
+      "toDark": "Skift til mørkt tema"
+    }
+  },
+  "lang": {
+    "am": "Amharisk",
+    "ar": "Arabisk",
+    "bg": "Bulgarsk",
+    "da": "Dansk",
+    "de": "Tysk",
+    "el": "Græsk",
+    "en": "Engelsk",
+    "es": "Spansk",
+    "et": "Estisk",
+    "fa": "Persisk",
+    "fi": "Finsk",
+    "fr": "Fransk",
+    "ha": "Hausa",
+    "he": "Hebraisk",
+    "ig": "Igbo",
+    "it": "Italiensk",
+    "ka": "Georgisk",
+    "kk": "Kasakhisk",
+    "ma": "Darija",
+    "nl": "Hollandsk",
+    "no": "Norsk",
+    "om": "Oromo",
+    "pl": "Polsk",
+    "pt": "Portugisisk",
+    "ro": "Rumænsk",
+    "ru": "Russisk",
+    "so": "Somalisk",
+    "sr": "Serbisk",
+    "sv": "Svensk",
+    "sw": "Swahili",
+    "ti": "Tigrinya",
+    "tr": "Tyrkisk",
+    "uk": "Ukrainsk",
+    "uz": "Usbekisk",
+    "wo": "Wolof",
+    "yo": "Yoruba",
+    "zu": "Zulu"
+  },
+  "footer": {
+    "copyright": "© {{year}} helexa.ai"
+  }
+}

helexa.ai/src/i18n/resources/da/mission.json

@@ -0,0 +1,103 @@
+{
+  "hero": {
+    "badge": "En ny form for intelligens",
+    "title": "En ny form for intelligens",
+    "lead": "Helexa er et selvorganiserende AI‑mesh drevet af uafhængige operatører. Åbent. Distribueret. Under udvikling.",
+    "ctaJoinMesh": "Deltag i mesh'en",
+    "ctaFollowProject": "Følg projektet",
+    "subcopy": "Bygget til operatører, udviklere og fællesskaber, der mener, at AI skal være åbent, robust og delt.",
+    "imageAlt": "Helexa helix‑visualisering"
+  },
+
+  "intent": {
+    "title": "Hvorfor Helexa findes",
+    "p1": "AI er ved at blive den mest magtfulde infrastruktur på Jorden. Men i dag er den magt koncentreret hos en håndfuld virksomheder, formet af private prioriteter, geografiske begrænsninger og skrøbelig økonomi.",
+    "p2Intro": "Helexa forestiller sig noget andet:",
+    "bullet1": "Intelligens, der vokser frem overalt – ikke ét sted.",
+    "bullet2": "Et netværk, hvor alle kan bidrage og få gavn.",
+    "bullet3": "Et system, der tilpasser sig efter efterspørgsel, ikke direktiver.",
+    "bullet4": "Teknologi, der styrker fællesskaber i stedet for at erstatte dem.",
+    "closing": "Helexa er ikke en platform. Det er ikke en cloud.\nDet er et mesh – et levende, udviklende gitter af uafhængige operatører, der danner en ny form for intelligens."
+  },
+
+  "whyNow": {
+    "title": "Et vendepunkt for AI",
+    "problemTitle": "Problemet",
+    "problemBullet1": "AI centraliseres hurtigere end nogen tidligere teknologi.",
+    "problemBullet2": "Adgang til compute definerer kapacitet, og adgangen bliver snævrere.",
+    "problemBullet3": "Omkostninger udelukker forskere, startups og fællesskaber.",
+    "problemBullet4": "Geopolitiske og regulatoriske pres truer global tilgængelighed.",
+    "problemBullet5": "Skaberne af modeller og operatørerne af hardware deler sjældent i den værdi, de producerer.",
+    "opportunityTitle": "Muligheden",
+    "opportunityIntro": "Men en distribueret verden er mulig.",
+    "opportunityBullet1": "Tusindvis af GPU'er står allerede uudnyttede rundt om i verden.",
+    "opportunityBullet2": "Operatører ønsker retfærdig kompensation for compute.",
+    "opportunityBullet3": "Udviklere ønsker åben, censurresistent infrastruktur.",
+    "opportunityBullet4": "Fællesskaber ønsker suverænitet og robusthed i digitale systemer.",
+    "opportunityBullet5": "AI's vækst har overhalet traditionelle clouds – der er brug for nye former.",
+    "opportunityClosing": "Helexa er øjeblikket, hvor disse kræfter mødes."
+  },
+
+  "howItWorks": {
+    "title": "Sådan dannes mesh'en",
+    "operators": {
+      "eyebrow": "Operatører kører noder",
+      "title": "Alle kan bidrage med compute.",
+      "body": "Operatører kører Helexa‑noder. De beslutter, hvilke modeller der skal hostes. De bevarer kontrollen over deres hardware og økonomi. Ingen godkendelser, ingen gatekeepere."
+    },
+    "routing": {
+      "eyebrow": "Mesh'en dirigerer intelligens",
+      "title": "Efterspørgslen flyder gennem netværket.",
+      "body": "Helexa lærer, hvor kapacitet findes, hvor efterspørgslen stiger, og hvilke noder der er bedst egnet til at håndtere forespørgsler. Mesh'en tilpasser sig organisk – som en voksende helix."
+    },
+    "value": {
+      "eyebrow": "Værdien flyder tilbage",
+      "title": "Arbejdet bevises. Betalingen er retfærdig.",
+      "body": "Hver opgave bærer en kryptografisk kvittering. Operatører tjener på den intelligens, de hjælper med at levere. Ingen platformsskat. Ingen uigennemsigtig fakturering."
+    }
+  },
+
+  "principles": {
+    "title": "Bygget på principper, ikke platforme",
+    "distributed": {
+      "title": "Distribueret fra starten",
+      "body": "Ingen enkelt fejlkilde. Ingen central autoritet. Et netværk, der bliver stærkere for hver ny operatør."
+    },
+    "participation": {
+      "title": "Åben deltagelse",
+      "body": "Hvis du har compute, kan du bidrage. Mesh'en byder alle velkommen – edge, hjemmeserver, datacenter."
+    },
+    "fairness": {
+      "title": "Retfærdighed og gennemsigtighed",
+      "body": "Indtjening er baseret på reelt arbejde, kryptografisk verificeret. Ingen sorte bokse. Ingen skjulte gebyrer."
+    },
+    "evolving": {
+      "title": "Udviklende intelligens",
+      "body": "Mesh'en lærer af efterspørgslen. Modeller loades dér, hvor de behøves. Intelligens spredes gennem samarbejde."
+    }
+  },
+
+  "roadAhead": {
+    "title": "Hvad Helexa sigter mod at blive",
+    "p1": "Et globalt intelligenslag, der tilhører alle, drevet af en helix af noder og fællesskaber.",
+    "p2": "Et netværk, der er robust over for nedbrud, politik, monopoler og fejl.",
+    "p3": "En ny økonomisk model, hvor operatører, udviklere og brugere alle får udbytte.",
+    "p4": "Et økosystem, hvor innovation vokser ud fra kanterne – ikke centrum.",
+    "card": {
+      "eyebrow": "Visionsoversigt",
+      "title": "Mod et delt intelligens‑mesh",
+      "body": "Helexa er i en tidlig fase. Idéerne er større end implementationen – og det er med vilje. Netværket vil vokse gradvist, hvor operatører og udviklere sammen former dets udvikling."
+    }
+  },
+
+  "joinMesh": {
+    "badge": "Tidlig fase",
+    "title": "Mesh'en tager form.",
+    "titleHighlight": "Du kan være en del af den.",
+    "lead": "Uanset om du kører hardware, bygger modeller eller blot går op i, hvordan AI styres, er der en plads til dig i mesh'en.",
+    "ctaRunNode": "Kør en node (snart)",
+    "ctaJoinAnnouncements": "Deltag i tidlige annonceringer",
+    "ctaExploreCode": "Udforsk koden",
+    "footer": "Ingen lukkede haver. Ingen enkelt ejer. Bare et mesh af mennesker, hardware og idéer – der sammen former en anderledes fremtid for intelligens."
+  }
+}

helexa.ai/src/i18n/resources/de/chat.json

@@ -0,0 +1,17 @@
+{
+  "title": "Konversationsbereich",
+  "badge": "Chat",
+  "lead": "Dies ist die Chat-Ansicht. Binde hier deine Konversationslogik und UI-Komponenten ein.",
+  "transcriptPlaceholder": "Das Chat-Protokoll erscheint hier. Rendern die Nachrichten des Modells und der Nutzerin bzw. des Nutzers in einem scrollbaren Container, optional nach Gesprächsrunden gruppiert.",
+  "inputPlaceholder": "Schreibe eine Nachricht, um mit dem Chat zu beginnen…",
+  "send": "Senden",
+  "clear": "Leeren",
+  "newChat": "New chat",
+  "newProject": "New project",
+  "newProjectName": "New project",
+  "unsorted": "Unsorted",
+  "emptyState": "Start a conversation. Your history stays in this browser.",
+  "anonBanner": "You have reached the anonymous limit. Sign up for a free allocation.",
+  "signUp": "Sign up",
+  "stop": "Stop"
+}

helexa.ai/src/i18n/resources/de/common.json

@@ -0,0 +1,63 @@
+{
+  "app": {
+    "name": "helexa.ai"
+  },
+  "nav": {
+    "home": "Startseite",
+    "docs": "Dokumentation",
+    "chat": "Chat",
+    "mission": "Mission",
+    "login": "Sign in",
+    "register": "Sign up",
+    "account": "Account",
+    "logout": "Sign out"
+  },
+  "theme": {
+    "toggle": {
+      "toLight": "In den hellen Modus wechseln",
+      "toDark": "In den dunklen Modus wechseln"
+    }
+  },
+  "lang": {
+    "bg": "Bulgarisch",
+    "de": "Deutsch",
+    "el": "Griechisch",
+    "en": "Englisch",
+    "es": "Spanisch",
+    "et": "Estnisch",
+    "fr": "Französisch",
+    "he": "Hebräisch",
+    "it": "Italienisch",
+    "nl": "Niederländisch",
+    "da": "Dänisch",
+    "fi": "Finnisch",
+    "no": "Norwegisch",
+    "sv": "Schwedisch",
+    "ar": "Arabisch",
+    "fa": "Persisch",
+    "sw": "Suaheli",
+    "ha": "Hausa",
+    "am": "Amharisch",
+    "yo": "Yoruba",
+    "zu": "Zulu",
+    "ma": "Darija",
+    "ig": "Igbo",
+    "ka": "Georgisch",
+    "kk": "Kasachisch",
+    "om": "Oromo",
+    "so": "Somali",
+    "ti": "Tigrinya",
+    "uz": "Usbekisch",
+    "wo": "Wolof",
+    "pl": "Polnisch",
+    "pt": "Portugiesisch",
+    "ro": "Rumänisch",
+    "ru": "Russisch",
+    "sr": "Serbisch",
+    "tr": "Türkisch",
+    "uk": "Ukrainisch"
+  },
+  "footer": {
+    "copyright": "© {{year}} helexa.ai"
+  }
+}

helexa.ai/src/i18n/resources/de/mission.json

@@ -0,0 +1,103 @@
+{
+  "hero": {
+    "badge": "Eine neue Form von Intelligenz",
+    "title": "Eine neue Form von Intelligenz",
+    "lead": "Helexa ist ein selbstorganisiertes KI‑Mesh, betrieben von unabhängigen Operatoren. Offen. Dezentral. Im Wandel.",
+    "ctaJoinMesh": "Dem Mesh beitreten",
+    "ctaFollowProject": "Dem Projekt folgen",
+    "subcopy": "Geschaffen für Operatoren, Builder und Communities, die glauben, dass KI offen, widerstandsfähig und geteilt sein sollte.",
+    "imageAlt": "Helexa‑Helix‑Visualisierung"
+  },
+
+  "intent": {
+    "title": "Warum es Helexa gibt",
+    "p1": "KI wird zur mächtigsten Infrastruktur auf der Erde. Doch heute ist diese Macht in den Händen weniger Konzerne konzentriert – geprägt von privaten Prioritäten, geografischen Grenzen und fragilen Geschäftsmodellen.",
+    "p2Intro": "Helexa stellt sich etwas anderes vor:",
+    "bullet1": "Intelligenz, die überall wächst – nicht nur an einem Ort.",
+    "bullet2": "Ein Netzwerk, in dem jeder beitragen und profitieren kann.",
+    "bullet3": "Ein System, das sich an Nachfrage anpasst, nicht an Vorgaben.",
+    "bullet4": "Technologie, die Gemeinschaften stärkt, statt sie zu ersetzen.",
+    "closing": "Helexa ist keine Plattform. Es ist keine Cloud.\nEs ist ein Mesh – ein lebendiges, sich entwickelndes Geflecht unabhängiger Operatoren, das eine neue Form von Intelligenz bildet."
+  },
+
+  "whyNow": {
+    "title": "Ein Wendepunkt für KI",
+    "problemTitle": "Das Problem",
+    "problemBullet1": "KI zentralisiert sich schneller als jede Technologie zuvor.",
+    "problemBullet2": "Zugang zu Rechenressourcen bestimmt die Fähigkeiten – und dieser Zugang verengt sich.",
+    "problemBullet3": "Kostenbarrieren schließen Forschende, Startups und Communities aus.",
+    "problemBullet4": "Geopolitische und regulatorische Spannungen bedrohen die globale Verfügbarkeit.",
+    "problemBullet5": "Die Schöpfer von Modellen und die Betreiber von Hardware teilen selten den Wert, den sie erzeugen.",
+    "opportunityTitle": "Die Chance",
+    "opportunityIntro": "Aber eine verteilte Welt ist möglich.",
+    "opportunityBullet1": "Tausende GPUs weltweit sind heute bereits unterausgelastet.",
+    "opportunityBullet2": "Operatoren wollen eine faire Vergütung für ihre Rechenleistung.",
+    "opportunityBullet3": "Entwicklerinnen und Entwickler wünschen sich offene, zensurresistente Infrastruktur.",
+    "opportunityBullet4": "Communities wollen Souveränität und Resilienz in digitalen Systemen.",
+    "opportunityBullet5": "Das Wachstum der KI hat klassische Clouds überholt – es braucht neue Formen.",
+    "opportunityClosing": "Helexa ist der Moment, in dem sich diese Kräfte ausrichten."
+  },
+
+  "howItWorks": {
+    "title": "Wie sich das Mesh bildet",
+    "operators": {
+      "eyebrow": "Operatoren betreiben Nodes",
+      "title": "Jede und jeder kann Rechenleistung beisteuern.",
+      "body": "Operatoren betreiben Helexa‑Nodes. Sie entscheiden, welche Modelle sie hosten. Sie behalten die Kontrolle über ihre Hardware und ihre Wirtschaftlichkeit. Keine Genehmigungen, keine Gatekeeper."
+    },
+    "routing": {
+      "eyebrow": "Das Mesh leitet Intelligenz",
+      "title": "Nachfrage fließt durch das Netzwerk.",
+      "body": "Helexa lernt, wo Kapazität vorhanden ist, wo die Nachfrage steigt und welche Nodes sich am besten für Anfragen eignen. Das Mesh passt sich organisch an – wie eine wachsende Helix."
+    },
+    "value": {
+      "eyebrow": "Wert fließt zurück",
+      "title": "Arbeit wird bewiesen. Bezahlung ist fair.",
+      "body": "Jeder Job trägt einen kryptografischen Beleg. Operatoren verdienen an der Intelligenz mit, die sie bereitstellen. Keine Plattformsteuer. Keine intransparente Abrechnung."
+    }
+  },
+
+  "principles": {
+    "title": "Auf Prinzipien gebaut, nicht auf Plattformen",
+    "distributed": {
+      "title": "Von Grund auf verteilt",
+      "body": "Kein Single Point of Failure. Keine zentrale Instanz. Ein Netzwerk, das mit jedem neuen Operator stärker wird."
+    },
+    "participation": {
+      "title": "Offene Teilhabe",
+      "body": "Wenn du Rechenleistung hast, kannst du beitragen. Das Mesh heißt alle willkommen – Edge, Heimserver oder Rechenzentrum."
+    },
+    "fairness": {
+      "title": "Fairness & Transparenz",
+      "body": "Einnahmen basieren auf echter, kryptografisch verifizierter Arbeit. Keine Blackboxen. Keine versteckten Gebühren."
+    },
+    "evolving": {
+      "title": "Sich entwickelnde Intelligenz",
+      "body": "Das Mesh lernt aus der Nachfrage. Modelle landen dort, wo sie gebraucht werden. Intelligenz breitet sich durch Kooperation aus."
+    }
+  },
+
+  "roadAhead": {
+    "title": "Was Helexa werden will",
+    "p1": "Eine globale Intelligenzschicht, die allen gehört – angetrieben von einer Helix aus Nodes und Communities.",
+    "p2": "Ein Netzwerk, das Ausfällen, Politik, Monopolen und Störungen standhält.",
+    "p3": "Ein neues Wirtschaftsmodell, in dem Operatoren, Builder und Nutzerinnen gleichermaßen profitieren.",
+    "p4": "Ein Ökosystem, in dem Innovation von den Rändern ausgeht – nicht aus der Mitte.",
+    "card": {
+      "eyebrow": "Visions‑Snapshot",
+      "title": "Auf dem Weg zu einem geteilten Intelligenz‑Mesh",
+      "body": "Helexa steht am Anfang. Die Ideen sind größer als die aktuelle Implementierung – und das ist beabsichtigt. Das Netzwerk wird schrittweise wachsen, während Operatoren und Builder seine Entwicklung mitgestalten."
+    }
+  },
+
+  "joinMesh": {
+    "badge": "Frühe Phase",
+    "title": "Das Mesh formt sich.",
+    "titleHighlight": "Du kannst Teil davon sein.",
+    "lead": "Ob du Hardware betreibst, Modelle baust oder dir einfach wichtig ist, wie KI gesteuert wird – im Mesh gibt es einen Platz für dich.",
+    "ctaRunNode": "Node betreiben (bald)",
+    "ctaJoinAnnouncements": "Frühe Ankündigungen abonnieren",
+    "ctaExploreCode": "Code erkunden",
+    "footer": "Keine geschlossenen Gärten. Kein einzelner Besitzer. Nur ein Mesh aus Menschen, Hardware und Ideen – das eine andere Zukunft für Intelligenz komponiert."
+  }
+}

helexa.ai/src/i18n/resources/el/chat.json

@@ -0,0 +1,17 @@
+{
+  "title": "Χώρος συνομιλίας",
+  "badge": "Συνομιλία",
+  "lead": "Αυτή είναι η προβολή συνομιλίας. Σύνδεσε εδώ τη λογική της συζήτησης και τα components του περιβάλλοντος χρήστη σου.",
+  "transcriptPlaceholder": "Το ιστορικό της συνομιλίας θα εμφανίζεται εδώ. Απόδωσε τα μηνύματα του μοντέλου και του χρήστη σε ένα κυλιόμενο container, προαιρετικά ομαδοποιημένα ανά γύρο.",
+  "inputPlaceholder": "Πληκτρολόγησε ένα μήνυμα για να ξεκινήσεις τη συνομιλία…",
+  "send": "Αποστολή",
+  "clear": "Καθαρισμός",
+  "newChat": "New chat",
+  "newProject": "New project",
+  "newProjectName": "New project",
+  "unsorted": "Unsorted",
+  "emptyState": "Start a conversation. Your history stays in this browser.",
+  "anonBanner": "You have reached the anonymous limit. Sign up for a free allocation.",
+  "signUp": "Sign up",
+  "stop": "Stop"
+}

helexa.ai/src/i18n/resources/el/common.json

@@ -0,0 +1,63 @@
+{
+  "app": {
+    "name": "helexa.ai"
+  },
+  "nav": {
+    "home": "Αρχική",
+    "docs": "Τεκμηρίωση",
+    "chat": "Συνομιλία",
+    "mission": "Mission",
+    "login": "Sign in",
+    "register": "Sign up",
+    "account": "Account",
+    "logout": "Sign out"
+  },
+  "theme": {
+    "toggle": {
+      "toLight": "Μετάβαση σε φωτεινή λειτουργία",
+      "toDark": "Μετάβαση σε σκοτεινή λειτουργία"
+    }
+  },
+  "lang": {
+    "bg": "Βουλγαρικά",
+    "de": "Γερμανικά",
+    "el": "Ελληνικά",
+    "en": "Αγγλικά",
+    "es": "Ισπανικά",
+    "et": "Εσθονικά",
+    "fr": "Γαλλικά",
+    "he": "Εβραϊκά",
+    "it": "Ιταλικά",
+    "nl": "Ολλανδικά",
+    "da": "Δανικά",
+    "fi": "Φινλανδικά",
+    "no": "Νορβηγικά",
+    "sv": "Σουηδικά",
+    "ar": "Αραβικά",
+    "fa": "Περσικά",
+    "sw": "Σουαχίλι",
+    "ha": "Χάουσα",
+    "am": "Αμχαρικά",
+    "yo": "Γιορούμπα",
+    "zu": "Ζουλού",
+    "ma": "Νταρίτζα",
+    "ig": "Ίγκμπο",
+    "ka": "Γεωργιανά",
+    "kk": "Καζακικά",
+    "om": "Ορόμο",
+    "so": "Σομαλικά",
+    "ti": "Τιγκρινια",
+    "uz": "Ουζμπεκικά",
+    "wo": "Γουόλοφ",
+    "pl": "Πολωνικά",
+    "pt": "Πορτογαλικά",
+    "ro": "Ρουμανικά",
+    "ru": "Ρωσικά",
+    "sr": "Σερβικά",
+    "tr": "Τουρκικά",
+    "uk": "Ουκρανικά"
+  },
+  "footer": {
+    "copyright": "© {{year}} helexa.ai"
+  }
+}

helexa.ai/src/i18n/resources/el/mission.json

@@ -0,0 +1,103 @@
+{
+  "hero": {
+    "badge": "Μια νέα μορφή νοημοσύνης",
+    "title": "Μια νέα μορφή νοημοσύνης",
+    "lead": "Η Helexa είναι ένα αυτο-οργανωμένο πλέγμα ΤΝ που τροφοδοτείται από ανεξάρτητους operators. Ανοιχτό. Κατανεμημένο. Εξελισσόμενο.",
+    "ctaJoinMesh": "Γίνε μέρος του πλέγματος",
+    "ctaFollowProject": "Παρακολούθησε το έργο",
+    "subcopy": "Φτιαγμένο για operators, builders και κοινότητες που πιστεύουν ότι η ΤΝ πρέπει να είναι ανοιχτή, ανθεκτική και κοινόχρηστη.",
+    "imageAlt": "Οπτικοποίηση της έλικας Helexa"
+  },
+
+  "intent": {
+    "title": "Γιατί υπάρχει η Helexa",
+    "p1": "Η ΤΝ γίνεται η πιο ισχυρή υποδομή στον κόσμο. Σήμερα όμως, αυτή η ισχύς είναι συγκεντρωμένη σε λίγες εταιρείες, διαμορφωμένη από ιδιωτικές προτεραιότητες, γεωγραφικούς περιορισμούς και εύθραυστες οικονομίες.",
+    "p2Intro": "Η Helexa φαντάζεται κάτι διαφορετικό:",
+    "bullet1": "Μια νοημοσύνη που αναπτύσσεται από παντού, όχι από ένα μόνο σημείο.",
+    "bullet2": "Ένα δίκτυο στο οποίο ο καθένας μπορεί να συνεισφέρει και να ωφεληθεί.",
+    "bullet3": "Ένα σύστημα που προσαρμόζεται στη ζήτηση, όχι στις εντολές.",
+    "bullet4": "Τεχνολογία που ενδυναμώνει τις κοινότητες αντί να τις αντικαθιστά.",
+    "closing": "Η Helexa δεν είναι πλατφόρμα. Δεν είναι cloud.\nΕίναι ένα πλέγμα — ένα ζωντανό, εξελισσόμενο δίκτυο ανεξάρτητων operators που σχηματίζουν ένα νέο είδος νοημοσύνης."
+  },
+
+  "whyNow": {
+    "title": "Ένα σημείο καμπής για την ΤΝ",
+    "problemTitle": "Το πρόβλημα",
+    "problemBullet1": "Η ΤΝ συγκεντρώνεται πιο γρήγορα από κάθε προηγούμενη τεχνολογία.",
+    "problemBullet2": "Η πρόσβαση σε υπολογιστική ισχύ καθορίζει τις δυνατότητες και αυτή η πρόσβαση περιορίζεται.",
+    "problemBullet3": "Τα κόστη αποκλείουν ερευνητές, startups και κοινότητες.",
+    "problemBullet4": "Γεωπολιτικές και ρυθμιστικές πιέσεις απειλούν τη συνολική διαθεσιμότητα.",
+    "problemBullet5": "Οι δημιουργοί μοντέλων και οι operators υλικού σπάνια μοιράζονται την αξία που παράγουν.",
+    "opportunityTitle": "Η ευκαιρία",
+    "opportunityIntro": "Όμως ένας κατανεμημένος κόσμος είναι εφικτός.",
+    "opportunityBullet1": "Χιλιάδες GPUs σε όλο τον κόσμο παραμένουν υποαπασχολημένες.",
+    "opportunityBullet2": "Οι operators θέλουν δίκαιη αποζημίωση για την υπολογιστική ισχύ.",
+    "opportunityBullet3": "Οι developers θέλουν ανοιχτή, ανθεκτική στη λογοκρισία υποδομή.",
+    "opportunityBullet4": "Οι κοινότητες θέλουν κυριαρχία και ανθεκτικότητα στα ψηφιακά τους συστήματα.",
+    "opportunityBullet5": "Η ανάπτυξη της ΤΝ έχει ξεπεράσει τα παραδοσιακά clouds — χρειάζονται νέες μορφές.",
+    "opportunityClosing": "Η Helexa είναι η στιγμή όπου αυτές οι δυνάμεις ευθυγραμμίζονται."
+  },
+
+  "howItWorks": {
+    "title": "Πώς σχηματίζεται το πλέγμα",
+    "operators": {
+      "eyebrow": "Οι operators τρέχουν nodes",
+      "title": "Ο καθένας μπορεί να συνεισφέρει υπολογιστική ισχύ.",
+      "body": "Οι operators τρέχουν nodes της Helexa. Αποφασίζουν ποια μοντέλα θα φιλοξενήσουν. Παραμένουν σε έλεγχο του υλικού και της οικονομίας τους. Χωρίς εγκρίσεις, χωρίς μεσάζοντες gatekeepers."
+    },
+    "routing": {
+      "eyebrow": "Το πλέγμα δρομολογεί νοημοσύνη",
+      "title": "Η ζήτηση ρέει μέσα από το δίκτυο.",
+      "body": "Η Helexa μαθαίνει πού υπάρχει διαθέσιμη ισχύς, πού αυξάνεται η ζήτηση και ποια nodes είναι πιο κατάλληλα για να εξυπηρετήσουν τα αιτήματα. Το πλέγμα προσαρμόζεται οργανικά — σαν μια αναπτυσσόμενη έλικα."
+    },
+    "value": {
+      "eyebrow": "Η αξία επιστρέφει πίσω",
+      "title": "Η εργασία αποδεικνύεται. Η πληρωμή είναι δίκαιη.",
+      "body": "Κάθε εργασία φέρει μια κρυπτογραφική απόδειξη. Οι operators αμείβονται για τη νοημοσύνη που βοηθούν να παραχθεί. Χωρίς φόρο πλατφόρμας. Χωρίς αδιαφανή τιμολόγηση."
+    }
+  },
+
+  "principles": {
+    "title": "Χτισμένη σε αρχές, όχι σε πλατφόρμες",
+    "distributed": {
+      "title": "Κατανεμημένη από σχεδιασμό",
+      "body": "Χωρίς μοναδικό σημείο αποτυχίας. Χωρίς κεντρική αρχή. Ένα δίκτυο που γίνεται ισχυρότερο με κάθε νέο operator."
+    },
+    "participation": {
+      "title": "Ανοιχτή συμμετοχή",
+      "body": "Αν έχεις υπολογιστική ισχύ, μπορείς να συνεισφέρεις. Το πλέγμα καλωσορίζει τους πάντες — edge, οικιακό server, datacenter."
+    },
+    "fairness": {
+      "title": "Δικαιοσύνη & διαφάνεια",
+      "body": "Τα έσοδα βασίζονται σε πραγματική, κρυπτογραφικά επαληθευμένη εργασία. Χωρίς «μαύρα κουτιά». Χωρίς κρυφές χρεώσεις."
+    },
+    "evolving": {
+      "title": "Εξελισσόμενη νοημοσύνη",
+      "body": "Το πλέγμα μαθαίνει από τη ζήτηση. Τα μοντέλα φορτώνονται εκεί όπου χρειάζονται. Η νοημοσύνη εξαπλώνεται μέσω συνεργασίας."
+    }
+  },
+
+  "roadAhead": {
+    "title": "Τι στοχεύει να γίνει η Helexa",
+    "p1": "Ένα παγκόσμιο επίπεδο νοημοσύνης που ανήκει σε όλους, τροφοδοτούμενο από μια έλικα από nodes και κοινότητες.",
+    "p2": "Ένα δίκτυο ανθεκτικό σε διακοπές, πολιτική, μονοπώλια και αστοχίες.",
+    "p3": "Ένα νέο οικονομικό μοντέλο όπου operators, builders και χρήστες ωφελούνται όλοι.",
+    "p4": "Ένα οικοσύστημα όπου η καινοτομία αναπτύσσεται από τις άκρες — όχι από το κέντρο.",
+    "card": {
+      "eyebrow": "Στιγμιότυπο του οράματος",
+      "title": "Προς ένα κοινό πλέγμα νοημοσύνης",
+      "body": "Η Helexa βρίσκεται σε πρώιμο στάδιο. Οι ιδέες είναι μεγαλύτερες από την υλοποίηση — και αυτό είναι σκόπιμο. Το δίκτυο θα μεγαλώνει βήμα‑βήμα, με τους operators και τους builders να διαμορφώνουν την εξέλιξή του."
+    }
+  },
+
+  "joinMesh": {
+    "badge": "Πρώιμη φάση",
+    "title": "Το πλέγμα σχηματίζεται.",
+    "titleHighlight": "Μπορείς να είσαι μέρος του.",
+    "lead": "Είτε τρέχεις hardware, είτε χτίζεις μοντέλα, είτε απλώς σε νοιάζει πώς κυβερνάται η ΤΝ, υπάρχει μια θέση για σένα μέσα στο πλέγμα.",
+    "ctaRunNode": "Τρέξε ένα node (σύντομα)",
+    "ctaJoinAnnouncements": "Μπες στις πρώιμες ανακοινώσεις",
+    "ctaExploreCode": "Εξερεύνησε τον κώδικα",
+    "footer": "Χωρίς περιφραγμένους κήπους. Χωρίς έναν μόνο ιδιοκτήτη. Μόνο ένα πλέγμα από ανθρώπους, hardware και ιδέες — που συνθέτουν ένα διαφορετικό μέλλον για τη νοημοσύνη."
+  }
+}

helexa.ai/src/i18n/resources/en/chat.json

@@ -0,0 +1,17 @@
+{
+  "title": "Conversation workspace",
+  "badge": "Chat",
+  "lead": "This is the chat view. Plug your conversational logic and UI components into this page.",
+  "transcriptPlaceholder": "Chat transcript will appear here. Render messages from the model and user in a scrolling container, optionally grouped by turn.",
+  "inputPlaceholder": "Type a message to start chatting…",
+  "send": "Send",
+  "clear": "Clear",
+  "newChat": "New chat",
+  "newProject": "New project",
+  "newProjectName": "New project",
+  "unsorted": "Unsorted",
+  "emptyState": "Start a conversation. Your history stays in this browser.",
+  "anonBanner": "You have reached the anonymous limit. Sign up for a free allocation.",
+  "signUp": "Sign up",
+  "stop": "Stop"
+}

helexa.ai/src/i18n/resources/en/common.json

@@ -0,0 +1,63 @@
+{
+  "app": {
+    "name": "helexa.ai"
+  },
+  "nav": {
+    "home": "Home",
+    "docs": "Docs",
+    "chat": "Chat",
+    "mission": "Mission",
+    "login": "Sign in",
+    "register": "Sign up",
+    "account": "Account",
+    "logout": "Sign out"
+  },
+  "theme": {
+    "toggle": {
+      "toLight": "Switch to light mode",
+      "toDark": "Switch to dark mode"
+    }
+  },
+  "lang": {
+    "bg": "Bulgarian",
+    "de": "German",
+    "el": "Greek",
+    "en": "English",
+    "es": "Spanish",
+    "et": "Estonian",
+    "fr": "French",
+    "he": "Hebrew",
+    "it": "Italian",
+    "nl": "Dutch",
+    "da": "Danish",
+    "fi": "Finnish",
+    "no": "Norwegian",
+    "sv": "Swedish",
+    "ar": "Arabic",
+    "fa": "Persian",
+    "sw": "Swahili",
+    "ha": "Hausa",
+    "am": "Amharic",
+    "yo": "Yoruba",
+    "zu": "Zulu",
+    "ma": "Darija",
+    "ig": "Igbo",
+    "ka": "Georgian",
+    "kk": "Kazakh",
+    "om": "Oromo",
+    "so": "Somali",
+    "ti": "Tigrinya",
+    "uz": "Uzbek",
+    "wo": "Wolof",
+    "pl": "Polish",
+    "pt": "Portuguese",
+    "ro": "Romanian",
+    "ru": "Russian",
+    "sr": "Serbian",
+    "tr": "Turkish",
+    "uk": "Ukrainian"
+  },
+  "footer": {
+    "copyright": "© {{year}} helexa.ai"
+  }
+}

helexa.ai/src/i18n/resources/en/mission.json

@@ -0,0 +1,103 @@
+{
+  "hero": {
+    "badge": "European digital sovereignty",
+    "title": "Sovereign AI, Run by Europe",
+    "lead": "helexa is a sovereign AI mesh: near-frontier models served by independent European operators, on European hardware, under European law. Open. Distributed. Yours.",
+    "ctaJoinMesh": "Start chatting",
+    "ctaFollowProject": "Follow the project",
+    "subcopy": "For people and organisations who refuse to make their thinking a dependency of a foreign hyperscaler.",
+    "imageAlt": "helexa helix visual"
+  },
+
+  "intent": {
+    "title": "Why helexa Exists",
+    "p1": "AI is becoming the most consequential infrastructure on Earth — and Europe runs almost none of it. The models, the GPUs, the clouds, and the terms of service belong to a handful of US corporations, leaving European users, researchers, and businesses renting their own intelligence back from someone else's jurisdiction.",
+    "p2Intro": "helexa is built for a different settlement:",
+    "bullet1": "Data residency by default — your prompts stay on operators you can locate on a map.",
+    "bullet2": "GDPR-native, not GDPR-retrofitted: no server-side chat history, ever.",
+    "bullet3": "Capacity owned by independent operators, not a single hyperscaler.",
+    "bullet4": "Infrastructure that strengthens European autonomy instead of deepening dependency.",
+    "closing": "helexa is not a platform. It is not a US cloud with an EU region.\nIt is a mesh — a lattice of independent European operators serving frontier-class intelligence under European law."
+  },
+
+  "whyNow": {
+    "title": "A Turning Point for European AI",
+    "problemTitle": "The Dependency",
+    "problemBullet1": "Frontier AI is centralising faster than any technology before it — almost entirely outside Europe.",
+    "problemBullet2": "Compute access defines capability, and that access is gated by a few foreign providers.",
+    "problemBullet3": "Cross-border data flows and shifting US policy put European data and availability at risk.",
+    "problemBullet4": "Terms, prices, and model availability can change overnight, decided elsewhere.",
+    "problemBullet5": "European operators who own capable hardware rarely share in the value it could produce.",
+    "opportunityTitle": "The Sovereign Opportunity",
+    "opportunityIntro": "A European alternative is already within reach.",
+    "opportunityBullet1": "Capable consumer GPUs sit underutilised across European homes, labs, and datacentres.",
+    "opportunityBullet2": "Operators want fair compensation for serving compute close to users.",
+    "opportunityBullet3": "Developers want open, censorship-resistant infrastructure under known law.",
+    "opportunityBullet4": "Communities and institutions want sovereignty and resilience in their digital systems.",
+    "opportunityBullet5": "Near-frontier open-weight models now run well on consumer hardware — no hyperscaler required.",
+    "opportunityClosing": "helexa is the moment these forces align — in Europe's favour."
+  },
+
+  "howItWorks": {
+    "title": "How the Mesh Forms",
+    "operators": {
+      "eyebrow": "Operators Run Nodes",
+      "title": "European compute, locally owned.",
+      "body": "Independent operators run helexa nodes on their own hardware, in their own jurisdiction. They choose what to host and keep control of their economics. No approvals, no gatekeepers, no offshore dependency."
+    },
+    "routing": {
+      "eyebrow": "The Mesh Routes Intelligence",
+      "title": "Requests stay close to home.",
+      "body": "helexa routes each request to an operator with capacity, preferring region affinity — so traffic and data stay where you expect. The mesh adapts organically, like a growing helix."
+    },
+    "value": {
+      "eyebrow": "Value Flows Back",
+      "title": "Work is proven. Payment is fair.",
+      "body": "Usage is metered transparently and operators are compensated for the intelligence they serve. No platform taxation, no opaque billing, no lock-in."
+    }
+  },
+
+  "principles": {
+    "title": "Built on Sovereignty, Not Platforms",
+    "distributed": {
+      "title": "Sovereign by Design",
+      "body": "European hardware, European operators, European law. No single point of failure and no foreign control plane your access depends on."
+    },
+    "participation": {
+      "title": "Open Participation",
+      "body": "If you have capable compute, you can contribute — edge, home server, or datacentre. The mesh welcomes every European operator."
+    },
+    "fairness": {
+      "title": "Privacy & Transparency",
+      "body": "GDPR-native: chat history lives only in your browser, never on a server. Usage metering is transparent; there are no black boxes and no hidden fees."
+    },
+    "evolving": {
+      "title": "Resilient Intelligence",
+      "body": "The mesh learns from demand and loads models where they're needed. Capacity spread across many operators is harder to censor, throttle, or switch off."
+    }
+  },
+
+  "roadAhead": {
+    "title": "What helexa Aims to Become",
+    "p1": "A European intelligence layer that belongs to its users and operators, powered by a helix of independent nodes.",
+    "p2": "A network resilient to outages, foreign policy shifts, monopolies, and single-vendor failure.",
+    "p3": "A fair economic model where European operators, builders, and users all benefit.",
+    "p4": "An ecosystem where innovation grows from the edges of Europe — not the centre of someone else's market.",
+    "card": {
+      "eyebrow": "Vision snapshot",
+      "title": "Toward a sovereign intelligence mesh",
+      "body": "helexa is early, and deliberately so. The network grows iteratively, with European operators and builders shaping its evolution — not a roadmap dictated from abroad."
+    }
+  },
+
+  "joinMesh": {
+    "badge": "Early phase",
+    "title": "The Mesh Is Forming.",
+    "titleHighlight": "You Can Be Part of It.",
+    "lead": "Whether you run hardware, build models, or simply care about who governs your AI, there is a place for you in the mesh.",
+    "ctaRunNode": "Run a node (soon)",
+    "ctaJoinAnnouncements": "Join early announcements",
+    "ctaExploreCode": "Explore the code",
+    "footer": "No walled gardens. No foreign owner. A mesh of European people, hardware, and ideas — composing a sovereign future for intelligence."
+  }
+}

helexa.ai/src/i18n/resources/es/chat.json

@@ -0,0 +1,17 @@
+{
+  "title": "Espacio de conversación",
+  "badge": "Chat",
+  "lead": "Esta es la vista de chat. Conecta aquí tu lógica conversacional y los componentes de interfaz que desees.",
+  "transcriptPlaceholder": "La transcripción del chat aparecerá aquí. Renderiza los mensajes del modelo y de la persona usuaria en un contenedor desplazable, opcionalmente agrupados por turno.",
+  "inputPlaceholder": "Escribe un mensaje para comenzar a chatear…",
+  "send": "Enviar",
+  "clear": "Limpiar",
+  "newChat": "New chat",
+  "newProject": "New project",
+  "newProjectName": "New project",
+  "unsorted": "Unsorted",
+  "emptyState": "Start a conversation. Your history stays in this browser.",
+  "anonBanner": "You have reached the anonymous limit. Sign up for a free allocation.",
+  "signUp": "Sign up",
+  "stop": "Stop"
+}

helexa.ai/src/i18n/resources/es/common.json

@@ -0,0 +1,63 @@
+{
+  "app": {
+    "name": "helexa.ai"
+  },
+  "nav": {
+    "home": "Inicio",
+    "docs": "Documentación",
+    "chat": "Chat",
+    "mission": "Mission",
+    "login": "Sign in",
+    "register": "Sign up",
+    "account": "Account",
+    "logout": "Sign out"
+  },
+  "theme": {
+    "toggle": {
+      "toLight": "Cambiar a modo claro",
+      "toDark": "Cambiar a modo oscuro"
+    }
+  },
+  "lang": {
+    "bg": "Búlgaro",
+    "de": "Alemán",
+    "el": "Griego",
+    "en": "Inglés",
+    "es": "Español",
+    "et": "Estonio",
+    "fr": "Francés",
+    "he": "Hebreo",
+    "it": "Italiano",
+    "nl": "Neerlandés",
+    "da": "Danés",
+    "fi": "Finés",
+    "no": "Noruego",
+    "sv": "Sueco",
+    "ar": "Árabe",
+    "fa": "Persa",
+    "sw": "Suajili",
+    "ha": "Hausa",
+    "am": "Amhárico",
+    "yo": "Yoruba",
+    "zu": "Zulu",
+    "ma": "Darija",
+    "ig": "Igbo",
+    "ka": "Georgiano",
+    "kk": "Kazajo",
+    "om": "Oromo",
+    "so": "Somalí",
+    "ti": "Tigriña",
+    "uz": "Uzbeko",
+    "wo": "Wólof",
+    "pl": "Polaco",
+    "pt": "Portugués",
+    "ro": "Rumano",
+    "ru": "Ruso",
+    "sr": "Serbio",
+    "tr": "Turco",
+    "uk": "Ucraniano"
+  },
+  "footer": {
+    "copyright": "© {{year}} helexa.ai"
+  }
+}

helexa.ai/src/i18n/resources/es/mission.json

@@ -0,0 +1,103 @@
+{
+  "hero": {
+    "badge": "Una nueva forma de inteligencia",
+    "title": "Una nueva forma de inteligencia",
+    "lead": "Helexa es una malla de IA autoorganizada impulsada por operadores independientes. Abierta. Distribuida. En evolución.",
+    "ctaJoinMesh": "Únete a la malla",
+    "ctaFollowProject": "Sigue el proyecto",
+    "subcopy": "Construida para operadores, desarrolladores y comunidades que creen que la IA debe ser abierta, resiliente y compartida.",
+    "imageAlt": "Visual de la hélice de Helexa"
+  },
+
+  "intent": {
+    "title": "Por qué existe Helexa",
+    "p1": "La IA se está convirtiendo en la infraestructura más poderosa de la Tierra. Pero hoy, ese poder está concentrado en un puñado de corporaciones, moldeado por prioridades privadas, limitaciones geográficas y economías frágiles.",
+    "p2Intro": "Helexa imagina algo diferente:",
+    "bullet1": "Una inteligencia que crece desde todas partes, no desde un solo lugar.",
+    "bullet2": "Una red donde cualquiera puede contribuir y beneficiarse.",
+    "bullet3": "Un sistema que se adapta a la demanda, no a directivas.",
+    "bullet4": "Tecnología que fortalece a las comunidades en lugar de reemplazarlas.",
+    "closing": "Helexa no es una plataforma. No es una nube.\nEs una malla: una red viva y evolutiva de operadores independientes que forman un nuevo tipo de inteligencia."
+  },
+
+  "whyNow": {
+    "title": "Un punto de inflexión para la IA",
+    "problemTitle": "El problema",
+    "problemBullet1": "La IA se está centralizando más rápido que cualquier tecnología anterior.",
+    "problemBullet2": "El acceso al cómputo define la capacidad, y ese acceso se está reduciendo.",
+    "problemBullet3": "Las barreras de coste excluyen a investigadores, startups y comunidades.",
+    "problemBullet4": "Las presiones geopolíticas y regulatorias amenazan la disponibilidad global.",
+    "problemBullet5": "Los creadores de modelos y los operadores de hardware rara vez comparten el valor que producen.",
+    "opportunityTitle": "La oportunidad",
+    "opportunityIntro": "Pero un mundo distribuido es posible.",
+    "opportunityBullet1": "Miles de GPU ya están subutilizadas en todo el mundo.",
+    "opportunityBullet2": "Los operadores quieren una compensación justa por el cómputo.",
+    "opportunityBullet3": "Los desarrolladores quieren infraestructura abierta y resistente a la censura.",
+    "opportunityBullet4": "Las comunidades quieren soberanía y resiliencia en los sistemas digitales.",
+    "opportunityBullet5": "El crecimiento de la IA ha superado a las nubes tradicionales: se necesitan nuevas formas.",
+    "opportunityClosing": "Helexa es el momento en que estas fuerzas se alinean."
+  },
+
+  "howItWorks": {
+    "title": "Cómo se forma la malla",
+    "operators": {
+      "eyebrow": "Los operadores ejecutan nodos",
+      "title": "Cualquiera puede aportar cómputo.",
+      "body": "Los operadores ejecutan nodos de Helexa. Deciden qué modelos alojar. Mantienen el control de su hardware y su economía. Sin aprobaciones, sin guardianes."
+    },
+    "routing": {
+      "eyebrow": "La malla enruta la inteligencia",
+      "title": "La demanda fluye a través de la red.",
+      "body": "Helexa aprende dónde existe capacidad, dónde está creciendo la demanda y qué nodos están mejor preparados para atender las solicitudes. La malla se adapta de forma orgánica, como una hélice en crecimiento."
+    },
+    "value": {
+      "eyebrow": "El valor fluye de vuelta",
+      "title": "El trabajo se prueba. El pago es justo.",
+      "body": "Cada tarea lleva un recibo criptográfico. Los operadores ganan por la inteligencia que ayudan a proporcionar. Sin impuestos de plataforma. Sin facturación opaca."
+    }
+  },
+
+  "principles": {
+    "title": "Basada en principios, no en plataformas",
+    "distributed": {
+      "title": "Distribuida por diseño",
+      "body": "Sin un único punto de fallo. Sin autoridad central. Una red que se fortalece con cada nuevo operador."
+    },
+    "participation": {
+      "title": "Participación abierta",
+      "body": "Si tienes cómputo, puedes contribuir. La malla da la bienvenida a todos: edge, servidor doméstico o centro de datos."
+    },
+    "fairness": {
+      "title": "Equidad y transparencia",
+      "body": "Las ganancias se basan en trabajo real, verificado criptográficamente. Sin cajas negras. Sin comisiones ocultas."
+    },
+    "evolving": {
+      "title": "Inteligencia en evolución",
+      "body": "La malla aprende de la demanda. Los modelos se cargan donde se necesitan. La inteligencia se extiende mediante la cooperación."
+    }
+  },
+
+  "roadAhead": {
+    "title": "Lo que Helexa aspira a ser",
+    "p1": "Una capa de inteligencia global que pertenece a todos, impulsada por una hélice de nodos y comunidades.",
+    "p2": "Una red resiliente frente a cortes, política, monopolios y fallos.",
+    "p3": "Un nuevo modelo económico donde operadores, constructores y usuarios se benefician por igual.",
+    "p4": "Un ecosistema donde la innovación crece desde los bordes, no desde el centro.",
+    "card": {
+      "eyebrow": "Instantánea de la visión",
+      "title": "Hacia una malla de inteligencia compartida",
+      "body": "Helexa está en una fase temprana. Las ideas son más grandes que la implementación, y eso es intencional. La red crecerá de forma iterativa, con operadores y desarrolladores dando forma a su evolución."
+    }
+  },
+
+  "joinMesh": {
+    "badge": "Fase inicial",
+    "title": "La malla se está formando.",
+    "titleHighlight": "Tú puedes ser parte de ella.",
+    "lead": "Tanto si gestionas hardware, construyes modelos o simplemente te importa cómo se gobierna la IA, hay un lugar para ti en la malla.",
+    "ctaRunNode": "Ejecutar un nodo (pronto)",
+    "ctaJoinAnnouncements": "Únete a los anuncios iniciales",
+    "ctaExploreCode": "Explora el código",
+    "footer": "Sin jardines amurallados. Sin un único propietario. Solo una malla de personas, hardware e ideas que componen un futuro distinto para la inteligencia."
+  }
+}

helexa.ai/src/i18n/resources/et/chat.json

@@ -0,0 +1,17 @@
+{
+  "title": "Vestluse tööruum",
+  "badge": "Vestlus",
+  "lead": "See on vestlusvaade. Siia saad ühendada oma vestlusloogika ja kasutajaliidese komponendid.",
+  "transcriptPlaceholder": "Vestluse logi kuvatakse siin. Esita mudeli ja kasutaja sõnumeid keritavas konteineris, soovi korral sammude kaupa rühmitatuna.",
+  "inputPlaceholder": "Alusta vestlust, kirjutades siia sõnumi…",
+  "send": "Saada",
+  "clear": "Tühjenda",
+  "newChat": "New chat",
+  "newProject": "New project",
+  "newProjectName": "New project",
+  "unsorted": "Unsorted",
+  "emptyState": "Start a conversation. Your history stays in this browser.",
+  "anonBanner": "You have reached the anonymous limit. Sign up for a free allocation.",
+  "signUp": "Sign up",
+  "stop": "Stop"
+}

helexa.ai/src/i18n/resources/et/common.json

@@ -0,0 +1,63 @@
+{
+  "app": {
+    "name": "helexa.ai"
+  },
+  "nav": {
+    "home": "Avaleht",
+    "docs": "Dokumentatsioon",
+    "chat": "Vestlus",
+    "mission": "Mission",
+    "login": "Sign in",
+    "register": "Sign up",
+    "account": "Account",
+    "logout": "Sign out"
+  },
+  "theme": {
+    "toggle": {
+      "toLight": "Lülita heledale teemale",
+      "toDark": "Lülita tumedale teemale"
+    }
+  },
+  "lang": {
+    "bg": "bulgaaria",
+    "de": "saksa",
+    "el": "kreeka",
+    "en": "inglise",
+    "es": "hispaania",
+    "et": "eesti",
+    "fr": "prantsuse",
+    "he": "heebrea",
+    "it": "itaalia",
+    "nl": "hollandi",
+    "da": "taani",
+    "fi": "soome",
+    "no": "norra",
+    "sv": "rootsi",
+    "ar": "araabia",
+    "fa": "pärsia",
+    "sw": "suahiili",
+    "ha": "hausa",
+    "am": "amhara",
+    "yo": "joruba",
+    "zu": "isuulu",
+    "ma": "darija",
+    "ig": "igbo",
+    "ka": "gruusia",
+    "kk": "kasahhi",
+    "om": "oromo",
+    "so": "soomeeli",
+    "ti": "tigrinja",
+    "uz": "usbeki",
+    "wo": "wolofi",
+    "pl": "poola",
+    "pt": "portugali",
+    "ro": "rumeenia",
+    "ru": "vene",
+    "sr": "serbia",
+    "tr": "türgi",
+    "uk": "ukraina"
+  },
+  "footer": {
+    "copyright": "© {{year}} helexa.ai"
+  }
+}

helexa.ai/src/i18n/resources/et/mission.json

@@ -0,0 +1,103 @@
+{
+  "hero": {
+    "badge": "Uus intelligentsuse vorm",
+    "title": "Uus intelligentsuse vorm",
+    "lead": "Helexa on iseorganiseeruv tehisintellekti võrk, mida juhivad sõltumatud operaatorid. Avatud. Hajutatud. Arenev.",
+    "ctaJoinMesh": "Liitu võrgustikuga",
+    "ctaFollowProject": "Jälgi projekti",
+    "subcopy": "Loodud operaatoritele, ehitajatele ja kogukondadele, kes usuvad, et tehisintellekt peab olema avatud, vastupidav ja jagatud.",
+    "imageAlt": "Helexa heeliksi visuaal"
+  },
+
+  "intent": {
+    "title": "Miks Helexa olemas on",
+    "p1": "Tehisintellektist saab Maa võimsaim taristu. Kuid täna on see jõud koondunud väheste korporatsioonide kätte, mida kujundavad eraeesmärgid, geograafilised piirangud ja habras majandus.",
+    "p2Intro": "Helexa kujutab ette midagi teistsugust:",
+    "bullet1": "Intelligents, mis kasvab igalt poolt, mitte ühest kohast.",
+    "bullet2": "Võrk, kus igaüks saab panustada ja kasu saada.",
+    "bullet3": "Süsteem, mis kohaneb nõudluse, mitte korralduste järgi.",
+    "bullet4": "Tehnoloogia, mis tugevdab kogukondi, mitte ei asenda neid.",
+    "closing": "Helexa ei ole platvorm. See ei ole pilv.\nSee on võrk — elav, arenev iseseisvate operaatorite võrgustik, mis loob uutmoodi intelligentsi."
+  },
+
+  "whyNow": {
+    "title": "Pöördepunkt tehisintellekti jaoks",
+    "problemTitle": "Probleem",
+    "problemBullet1": "Tehisintellekt tsentraliseerub kiiremini kui ükski varasem tehnoloogia.",
+    "problemBullet2": "Arvutusvõimsuse kättesaadavus määrab võimekuse ja ligipääs kitseneb.",
+    "problemBullet3": "Kulubarjäärid jätavad kõrvale uurijad, idufirmad ja kogukonnad.",
+    "problemBullet4": "Geopoliitiline ja regulatiivne surve ohustab globaalset kättesaadavust.",
+    "problemBullet5": "Mudeliloojatel ja riistvara operaatoritel on harva osa väärtusest, mille nad loovad.",
+    "opportunityTitle": "Võimalus",
+    "opportunityIntro": "Kuid hajutatud maailm on võimalik.",
+    "opportunityBullet1": "Tuhanded GPU-d on juba täna üle maailma alakasutatud.",
+    "opportunityBullet2": "Operaatorid soovivad arvutusvõimsuse eest õiglast tasu.",
+    "opportunityBullet3": "Arendajad tahavad avatud, tsensuurikindlat infrastruktuuri.",
+    "opportunityBullet4": "Kogukonnad soovivad suveräänsust ja vastupidavust digitaalsüsteemides.",
+    "opportunityBullet5": "Tehisintellekti kasv on traditsioonilisi pilvi edestanud — vaja on uusi vorme.",
+    "opportunityClosing": "Helexa on hetk, mil need jõud joondavad end."
+  },
+
+  "howItWorks": {
+    "title": "Kuidas võrk kujuneb",
+    "operators": {
+      "eyebrow": "Operaatorid käitavad sõlmi",
+      "title": "Igaüks saab panustada arvutusvõimsusega.",
+      "body": "Operaatorid käitavad Helexa sõlmi. Nad otsustavad, milliseid mudeleid hostida. Nad jäävad kontrollima oma riistvara ja oma majandust. Ilma kinnitusteta, ilma väravavahtideta."
+    },
+    "routing": {
+      "eyebrow": "Võrk suunab intelligentsi",
+      "title": "Nõudlus liigub läbi võrgustiku.",
+      "body": "Helexa õpib, kus on vaba võimsust, kus nõudlus kasvab ja millised sõlmed sobivad päringutele kõige paremini. Võrk kohaneb orgaaniliselt — nagu kasvav spiraal."
+    },
+    "value": {
+      "eyebrow": "Väärtus voolab tagasi",
+      "title": "Töö on tõendatav. Tasustamine on õiglane.",
+      "body": "Iga tööülesanne kannab endas krüptograafilist kviitungit. Operaatorid teenivad intelligentsi eest, mille loomises nad osalevad. Ilma platvormimaksuta. Ilma läbipaistmatu arvelduseta."
+    }
+  },
+
+  "principles": {
+    "title": "Ehitame põhimõtete, mitte platvormide peale",
+    "distributed": {
+      "title": "Hajutatud juba disainist",
+      "body": "Ei mingeid üksikuid tõrkepunkte. Ei mingit keskust. Võrk, mis muutub iga uue operaatoriga tugevamaks."
+    },
+    "participation": {
+      "title": "Avatud osalus",
+      "body": "Kui sul on arvutusressursse, saad panustada. Võrk tervitab kõiki — servaseadmeid, koduservereid ja andmekeskusi."
+    },
+    "fairness": {
+      "title": "Õiglus ja läbipaistvus",
+      "body": "Tulu põhineb tegelikul, krüptograafiliselt tõendatud tööl. Ei mingeid musti kaste. Ei mingeid varjatud tasusid."
+    },
+    "evolving": {
+      "title": "Arenev intelligentsus",
+      "body": "Võrk õpib nõudlusest. Mudeleid laetakse sinna, kus neid on vaja. Intelligentsus levib koostöö kaudu."
+    }
+  },
+
+  "roadAhead": {
+    "title": "Milleks Helexa pürgib",
+    "p1": "Globaalne intelligentsuskiht, mis kuulub kõigile, mida kannab sõlmede ja kogukondade heeliks.",
+    "p2": "Võrk, mis on vastupidav katkestustele, poliitikale, monopooliale ja riketele.",
+    "p3": "Uus majandusmudel, kus operaatorid, loojad ja kasutajad võidavad koos.",
+    "p4": "Ökosüsteem, kus uuendused kasvavad servast — mitte keskmest.",
+    "card": {
+      "eyebrow": "Visiooni hetkeseis",
+      "title": "Teel jagatud intelligentsusvõrguni",
+      "body": "Helexa on algusjärgus. Ideed on suuremad kui praegune teostus — ja see on taotluslik. Võrk kasvab järk-järgult, kujundatuna operaatorite ja ehitajate poolt."
+    }
+  },
+
+  "joinMesh": {
+    "badge": "Varajane etapp",
+    "title": "Võrk on kujunemas.",
+    "titleHighlight": "Sina võid olla selle osa.",
+    "lead": "Olenemata sellest, kas haldad riistvara, ehitad mudeleid või hoolid lihtsalt sellest, kuidas tehisintellekti juhitakse, sinu jaoks on võrgus koht.",
+    "ctaRunNode": "Käivita sõlm (varsti)",
+    "ctaJoinAnnouncements": "Liitu varajaste teadetega",
+    "ctaExploreCode": "Uuri koodi",
+    "footer": "Ilma suletud aedadeta. Ilma ühe omanikuta. Vaid võrk inimestest, riistvarast ja ideedest — mis koos loovad teistsuguse tuleviku intelligentsusele."
+  }
+}

helexa.ai/src/i18n/resources/fa/chat.json

@@ -0,0 +1,17 @@
+{
+  "title": "محیط گفتگو",
+  "badge": "گفتگو",
+  "lead": "این نمای گفتگوی شماست. منطق مکالمه و مؤلفه‌های رابط کاربری خود را در این صفحه متصل کنید.",
+  "transcriptPlaceholder": "رونوشت گفتگو در اینجا نمایش داده می‌شود. پیام‌های مدل و کاربر را در یک محفظه قابل اسکرول رندر کنید؛ در صورت تمایل آن‌ها را بر اساس نوبت گروه‌بندی کنید.",
+  "inputPlaceholder": "برای شروع گفتگو یک پیام بنویسید…",
+  "send": "ارسال",
+  "clear": "پاک کردن",
+  "newChat": "New chat",
+  "newProject": "New project",
+  "newProjectName": "New project",
+  "unsorted": "Unsorted",
+  "emptyState": "Start a conversation. Your history stays in this browser.",
+  "anonBanner": "You have reached the anonymous limit. Sign up for a free allocation.",
+  "signUp": "Sign up",
+  "stop": "Stop"
+}

helexa.ai/src/i18n/resources/fa/common.json

@@ -0,0 +1,63 @@
+{
+  "app": {
+    "name": "helexa.ai"
+  },
+  "nav": {
+    "home": "صفحه اصلی",
+    "docs": "مستندات",
+    "chat": "گفتگو",
+    "mission": "Mission",
+    "login": "Sign in",
+    "register": "Sign up",
+    "account": "Account",
+    "logout": "Sign out"
+  },
+  "theme": {
+    "toggle": {
+      "toLight": "تغییر به حالت روشن",
+      "toDark": "تغییر به حالت تیره"
+    }
+  },
+  "lang": {
+    "bg": "بلغاری",
+    "de": "آلمانی",
+    "el": "یونانی",
+    "en": "انگلیسی",
+    "es": "اسپانیایی",
+    "et": "استونیایی",
+    "fr": "فرانسوی",
+    "he": "عبری",
+    "it": "ایتالیایی",
+    "nl": "هلندی",
+    "am": "امهری",
+    "ar": "عربی",
+    "da": "دانمارکی",
+    "fa": "فارسی",
+    "fi": "فنلاندی",
+    "ha": "هوسا",
+    "ig": "ایگبو",
+    "ka": "گرجی",
+    "kk": "قزاقی",
+    "ma": "داریجه",
+    "no": "نروژی",
+    "om": "اورومو",
+    "pl": "لهستانی",
+    "pt": "پرتغالی",
+    "ro": "رومانیایی",
+    "ru": "روسی",
+    "so": "سومالیایی",
+    "sr": "صربی",
+    "sv": "سوئدی",
+    "sw": "سواحیلی",
+    "ti": "تیگرینیایی",
+    "tr": "ترکی",
+    "uk": "اوکراینی",
+    "uz": "ازبکی",
+    "wo": "ولوف",
+    "yo": "یوروبا",
+    "zu": "زولو"
+  },
+  "footer": {
+    "copyright": "© {{year}} helexa.ai"
+  }
+}

helexa.ai/src/i18n/resources/fa/mission.json

@@ -0,0 +1,103 @@
+{
+  "hero": {
+    "badge": "شکل جدیدی از هوش",
+    "title": "شکل جدیدی از هوش",
+    "lead": "هلیکسا یک شبکه هوش مصنوعی خودسازمان‌ده است که توسط اپراتورهای مستقل راه‌اندازی می‌شود. باز. توزیع‌شده. در حال تکامل.",
+    "ctaJoinMesh": "به شبکه بپیوندید",
+    "ctaFollowProject": "پروژه را دنبال کنید",
+    "subcopy": "ساخته شده برای اپراتورها، سازندگان و جوامعی که معتقدند هوش مصنوعی باید باز، مقاوم و مشترک باشد.",
+    "imageAlt": "نمای بصری هلیکسی هلیکسا"
+  },
+
+  "intent": {
+    "title": "چرا هلیکسا وجود دارد",
+    "p1": "هوش مصنوعی در حال تبدیل شدن به قدرتمندترین زیرساخت روی زمین است. اما امروزه این قدرت در دست تعداد اندکی از شرکت‌ها متمرکز شده که توسط اولویت‌های خصوصی، محدودیت‌های جغرافیایی و اقتصادهای شکننده شکل گرفته است.",
+    "p2Intro": "هلیکسا چیز دیگری را تصور می‌کند:",
+    "bullet1": "هوشی که از همه‌جا رشد می‌کند، نه فقط از یک نقطه.",
+    "bullet2": "یک شبکه که در آن هر کس می‌تواند مشارکت کند و بهره‌مند شود.",
+    "bullet3": "سیستمی که خود را با تقاضا تطبیق می‌دهد، نه با دستورهای از بالا.",
+    "bullet4": "فناوری‌ای که جوامع را تقویت می‌کند، نه این‌که جایگزین آن‌ها شود.",
+    "closing": "هلیکسا یک پلتفرم نیست. یک «ابر» هم نیست.\nاین یک شبکه است ـ یک شبکه زنده و در حال تکامل از اپراتورهای مستقل که نوع جدیدی از هوش را شکل می‌دهد."
+  },
+
+  "whyNow": {
+    "title": "نقطه عطفی برای هوش مصنوعی",
+    "problemTitle": "مسئله",
+    "problemBullet1": "هوش مصنوعی سریع‌تر از هر فناوری پیشین در حال تمرکزگرایی است.",
+    "problemBullet2": "دسترسی به توان محاسباتی، قابلیت‌ها را تعریف می‌کند و این دسترسی رو به محدودتر شدن است.",
+    "problemBullet3": "مانع‌های هزینه، پژوهشگران، استارتاپ‌ها و جوامع را کنار می‌گذارد.",
+    "problemBullet4": "فشارهای ژئوپلیتیک و رگولاتوری، دسترسی جهانی را تهدید می‌کنند.",
+    "problemBullet5": "سازندگان مدل‌ها و اپراتورهای سخت‌افزار به ندرت در ارزشی که ایجاد می‌کنند سهیم می‌شوند.",
+    "opportunityTitle": "فرصت",
+    "opportunityIntro": "اما دنیایی توزیع‌شده ممکن است.",
+    "opportunityBullet1": "هزاران GPU در سراسر جهان هم‌اکنون کمتر از ظرفیت واقعی خود استفاده می‌شوند.",
+    "opportunityBullet2": "اپراتورها خواهان جبران منصفانه برای توان محاسباتی هستند.",
+    "opportunityBullet3": "توسعه‌دهندگان به دنبال زیرساختی باز و مقاوم در برابر سانسور هستند.",
+    "opportunityBullet4": "جوامع خواهان حاکمیت و تاب‌آوری در سیستم‌های دیجیتال خود هستند.",
+    "opportunityBullet5": "رشد هوش مصنوعی از ابرهای سنتی جلو زده است ـ شکل‌های جدیدی لازم است.",
+    "opportunityClosing": "هلیکسا لحظه‌ای است که این نیروها در آن همسو می‌شوند."
+  },
+
+  "howItWorks": {
+    "title": "شبکه چگونه شکل می‌گیرد",
+    "operators": {
+      "eyebrow": "اپراتورها نودها را اجرا می‌کنند",
+      "title": "هر کسی می‌تواند توان محاسباتی فراهم کند.",
+      "body": "اپراتورها نودهای هلیکسا را اجرا می‌کنند. آن‌ها تصمیم می‌گیرند چه مدل‌هایی را میزبانی کنند. کنترل سخت‌افزار و اقتصاد خود را در دست دارند. بدون تأییدیه، بدون دربان."
+    },
+    "routing": {
+      "eyebrow": "شبکه هوش را مسیردهی می‌کند",
+      "title": "تقاضا در شبکه جریان دارد.",
+      "body": "هلیکسا می‌آموزد کجا ظرفیت وجود دارد، کجا تقاضا در حال افزایش است و کدام نودها برای پاسخ‌گویی به درخواست‌ها مناسب‌ترند. شبکه به شکل ارگانیک ـ مانند یک هلیکسی که رشد می‌کند ـ خود را تطبیق می‌دهد."
+    },
+    "value": {
+      "eyebrow": "ارزش بازمی‌گردد",
+      "title": "کار اثبات‌شده است. پرداخت منصفانه است.",
+      "body": "هر کار، یک رسید رمزنگاری‌شده همراه دارد. اپراتورها بابت هوشی که در فراهم کردن آن مشارکت دارند، درآمد کسب می‌کنند. بدون مالیات پلتفرمی. بدون صورت‌حساب مبهم."
+    }
+  },
+
+  "principles": {
+    "title": "بر پایه اصول، نه پلتفرم‌ها",
+    "distributed": {
+      "title": "توزیع‌شده در طراحی",
+      "body": "هیچ نقطه تک‌نقطه‌ای شکست وجود ندارد. هیچ مرجع مرکزی‌ای در کار نیست. شبکه‌ای که با هر اپراتور جدید، قوی‌تر می‌شود."
+    },
+    "participation": {
+      "title": "مشارکت باز",
+      "body": "اگر توان محاسباتی دارید، می‌توانید مشارکت کنید. شبکه از همه استقبال می‌کند ـ چه لبه، چه سرور خانگی، چه دیتاسنتر."
+    },
+    "fairness": {
+      "title": "عدالت و شفافیت",
+      "body": "درآمدها بر اساس کار واقعی و به‌طور رمزنگاری‌شده تأیید می‌شوند. بدون جعبه سیاه. بدون کارمزد پنهان."
+    },
+    "evolving": {
+      "title": "هوشی در حال تکامل",
+      "body": "شبکه از دل تقاضا می‌آموزد. مدل‌ها در جایی بارگذاری می‌شوند که به آن‌ها نیاز است. هوش از طریق همکاری گسترش می‌یابد."
+    }
+  },
+
+  "roadAhead": {
+    "title": "هلیکسا می‌خواهد به چه چیزی تبدیل شود",
+    "p1": "لایه‌ای از هوش جهانی که متعلق به همه است، با یک هلیکسی از نودها و جوامع نیرو می‌گیرد.",
+    "p2": "شبکه‌ای مقاوم در برابر قطعی‌ها، سیاست، انحصارها و خطا.",
+    "p3": "مدل اقتصادی جدیدی که در آن اپراتورها، سازندگان و کاربران همگی منتفع می‌شوند.",
+    "p4": "اکوسیستمی که در آن نوآوری از لبه‌ها رشد می‌کند ـ نه از مرکز.",
+    "card": {
+      "eyebrow": "برشی از چشم‌انداز",
+      "title": "به سوی یک شبکه هوش مشترک",
+      "body": "هلیکسا در مرحله‌ای اولیه قرار دارد. ایده‌ها بزرگ‌تر از پیاده‌سازی فعلی‌اند ـ و این عمدی است. شبکه به‌صورت تدریجی رشد خواهد کرد و اپراتورها و سازندگان در شکل‌دهی به تکامل آن نقش خواهند داشت."
+    }
+  },
+
+  "joinMesh": {
+    "badge": "مرحله اولیه",
+    "title": "شبکه در حال شکل‌گیری است.",
+    "titleHighlight": "شما می‌توانید بخشی از آن باشید.",
+    "lead": "فرقی نمی‌کند سخت‌افزار اجرا می‌کنید، مدل می‌سازید، یا فقط برایتان مهم است که چگونه بر هوش مصنوعی حکمرانی می‌شود ـ در این شبکه جایی برای شما وجود دارد.",
+    "ctaRunNode": "اجرای یک نود (به‌زودی)",
+    "ctaJoinAnnouncements": "پیوستن به اعلان‌های اولیه",
+    "ctaExploreCode": "کد را کاوش کنید",
+    "footer": "بدون باغ‌های محصور. بدون یک مالک یکتا. تنها شبکه‌ای از انسان‌ها، سخت‌افزار و ایده‌ها ـ که آینده‌ای متفاوت برای هوش می‌آفرینند."
+  }
+}

helexa.ai/src/i18n/resources/fi/chat.json

@@ -0,0 +1,17 @@
+{
+  "title": "Keskustelutila",
+  "badge": "Keskustelu",
+  "lead": "Tämä on keskustelunäkymä. Liitä oma keskustelulogiikkasi ja käyttöliittymäkomponenttisi tälle sivulle.",
+  "transcriptPlaceholder": "Keskusteluloki näkyy tässä. Näytä mallin ja käyttäjän viestit vieritettävässä säiliössä, halutessasi vuoroittain ryhmiteltynä.",
+  "inputPlaceholder": "Kirjoita viesti aloittaaksesi keskustelun…",
+  "send": "Lähetä",
+  "clear": "Tyhjennä",
+  "newChat": "New chat",
+  "newProject": "New project",
+  "newProjectName": "New project",
+  "unsorted": "Unsorted",
+  "emptyState": "Start a conversation. Your history stays in this browser.",
+  "anonBanner": "You have reached the anonymous limit. Sign up for a free allocation.",
+  "signUp": "Sign up",
+  "stop": "Stop"
+}