diff --git a/docker-compose.ecosystem.yml b/docker-compose.ecosystem.yml
index 6ea4ea4d..14554d15 100644
--- a/docker-compose.ecosystem.yml
+++ b/docker-compose.ecosystem.yml
@@ -8,7 +8,10 @@
 #   2. All product repos must be sibling directories of this repo
 #
 # Usage:
-#   docker compose -f docker-compose.ecosystem.yml --env-file .env.ecosystem up --build
+#   GITEA_NPM_TOKEN=<token> docker compose -f docker-compose.ecosystem.yml --env-file .env.ecosystem up --build
+#
+# The GITEA_NPM_TOKEN env var is required for product Docker builds that install
+# @bytelyst/* packages from the local Gitea npm registry via BuildKit secrets.
 #
 # Port Map:
 #   Infrastructure: cosmos-emulator 8081, azurite 10000, mailpit 1025/8025,
@@ -23,6 +26,18 @@
 #                   notelett 3045, mindlyst 3050, nomgap 3055,
 #                   actiontrail 3060, localmemgpt 3070, lysnrai 3002
 
+# Product Dockerfiles require BuildKit secrets for Gitea npm registry access.
+# GITEA_NPM_HOST defaults to host.docker.internal (Mac local dev).
+x-product-build: &product-build
+  args:
+    GITEA_NPM_HOST: ${GITEA_NPM_HOST:-host.docker.internal}
+  secrets:
+    - gitea_npm_token
+
+secrets:
+  gitea_npm_token:
+    environment: GITEA_NPM_TOKEN
+
 services:
 
   # ═════════════════════════════════════════════════════════════════
@@ -271,6 +286,7 @@ services:
 
   peakpulse-backend:
     build:
+      <<: *product-build
       context: ../learning_ai_peakpulse
       dockerfile: backend/Dockerfile
     ports:
@@ -293,6 +309,7 @@ services:
 
   chronomind-backend:
     build:
+      <<: *product-build
       context: ../learning_ai_clock
       dockerfile: backend/Dockerfile
     ports:
@@ -315,6 +332,7 @@ services:
 
   jarvisjr-backend:
     build:
+      <<: *product-build
       context: ../learning_ai_jarvis_jr
       dockerfile: backend/Dockerfile
     ports:
@@ -337,6 +355,7 @@ services:
 
   nomgap-backend:
     build:
+      <<: *product-build
       context: ../learning_ai_fastgap
       dockerfile: backend/Dockerfile
     ports:
@@ -359,6 +378,7 @@ services:
 
   mindlyst-backend:
     build:
+      <<: *product-build
       context: ../learning_multimodal_memory_agents
       dockerfile: backend/Dockerfile
     ports:
@@ -381,6 +401,7 @@ services:
 
   lysnrai-backend:
     build:
+      <<: *product-build
       context: ../learning_voice_ai_agent
       dockerfile: backend/Dockerfile
     ports:
@@ -403,6 +424,7 @@ services:
 
   notelett-backend:
     build:
+      <<: *product-build
       context: ../learning_ai_notes
       dockerfile: backend/Dockerfile
     ports:
@@ -426,6 +448,7 @@ services:
 
   flowmonk-backend:
     build:
+      <<: *product-build
       context: ../learning_ai_flowmonk
       dockerfile: backend/Dockerfile
     ports:
@@ -448,6 +471,7 @@ services:
 
   actiontrail-backend:
     build:
+      <<: *product-build
       context: ../learning_ai_trails
       dockerfile: backend/Dockerfile
     ports:
@@ -470,6 +494,7 @@ services:
 
   localmemgpt-backend:
     build:
+      <<: *product-build
       context: ../learning_ai_local_memory_gpt
       dockerfile: backend/Dockerfile
     ports:
@@ -499,6 +524,7 @@ services:
 
   lysnrai-dashboard:
     build:
+      <<: *product-build
       context: ../learning_voice_ai_agent
       dockerfile: user-dashboard-web/Dockerfile
     ports:
@@ -515,6 +541,7 @@ services:
 
   chronomind-web:
     build:
+      <<: *product-build
       context: ../learning_ai_clock
       dockerfile: web/Dockerfile
     ports:
@@ -531,6 +558,7 @@ services:
 
   jarvisjr-web:
     build:
+      <<: *product-build
       context: ../learning_ai_jarvis_jr
       dockerfile: web/Dockerfile
     ports:
@@ -547,6 +575,7 @@ services:
 
   flowmonk-web:
     build:
+      <<: *product-build
       context: ../learning_ai_flowmonk
       dockerfile: web/Dockerfile
     ports:
@@ -563,6 +592,7 @@ services:
 
   notelett-web:
     build:
+      <<: *product-build
       context: ../learning_ai_notes
       dockerfile: web/Dockerfile
     ports:
@@ -579,6 +609,7 @@ services:
 
   mindlyst-web:
     build:
+      <<: *product-build
       context: ../learning_multimodal_memory_agents
       dockerfile: mindlyst-native/web/Dockerfile
     ports:
@@ -595,6 +626,7 @@ services:
 
   nomgap-web:
     build:
+      <<: *product-build
       context: ../learning_ai_fastgap
       dockerfile: web/Dockerfile
     ports:
@@ -611,6 +643,7 @@ services:
 
   actiontrail-web:
     build:
+      <<: *product-build
       context: ../learning_ai_trails
       dockerfile: web/Dockerfile
     ports:
@@ -627,6 +660,7 @@ services:
 
   localmemgpt-web:
     build:
+      <<: *product-build
       context: ../learning_ai_local_memory_gpt
       dockerfile: web/Dockerfile
     ports:
diff --git a/docs/devops/ECOSYSTEM_DEPLOYMENT.md b/docs/devops/ECOSYSTEM_DEPLOYMENT.md
index 8ae8c151..49ba2a81 100644
--- a/docs/devops/ECOSYSTEM_DEPLOYMENT.md
+++ b/docs/devops/ECOSYSTEM_DEPLOYMENT.md
@@ -41,15 +41,18 @@ cd learning_ai_common_plat
 
 # 1. Create env file from example
 cp .env.ecosystem.example .env.ecosystem
-# Edit .env.ecosystem — fill in Stripe keys, Gemini key, etc.
+# Edit .env.ecosystem — fill in Cosmos emulator key, Azurite key, Stripe keys, Gemini key, etc.
 
-# 2. Validate compose config
+# 2. Export Gitea npm token (required for product Docker builds)
+export GITEA_NPM_TOKEN=<your-gitea-package-token>
+
+# 3. Validate compose config
 docker compose -f docker-compose.ecosystem.yml --env-file .env.ecosystem config --quiet
 
-# 3. Build and start everything
+# 4. Build and start everything
 docker compose -f docker-compose.ecosystem.yml --env-file .env.ecosystem up --build -d
 
-# 4. Check health
+# 5. Check health
 docker compose -f docker-compose.ecosystem.yml ps
 ```