From c7c36e74b6ed9568020fe86e76d9529495929a04 Mon Sep 17 00:00:00 2001
From: saravanakumardb1 <saravanakumardb1@users.noreply.github.com>
Date: Sat, 28 Feb 2026 13:17:03 -0800
Subject: [PATCH] docs: add portable Docker/CI build instructions
 (prep-consumer.sh)

---
 AGENTS.md |  5 +++++
 README.md | 30 ++++++++++++++++++++++++++++++
 2 files changed, 35 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 3e2a8d12..01891dc8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -189,6 +189,11 @@ pnpm --filter @bytelyst/design-tokens generate
 docker compose up -d
 docker compose down
 
+# ── Portable builds for consumer repos ────────────
+# Pack @bytelyst/* tarballs so Docker/CI builds don't need this sibling repo
+./scripts/prep-consumer.sh /path/to/consumer-dir           # pack + rewrite
+./scripts/prep-consumer.sh /path/to/consumer-dir --restore # undo
+
 # ── Health check all services ──────────────────────
 pnpm --filter @lysnrai/monitoring check
 ```
diff --git a/README.md b/README.md
index 1e691859..72f681c4 100644
--- a/README.md
+++ b/README.md
@@ -119,6 +119,36 @@ During development, use `file:` references in consumer `package.json`:
 
 All repos must be cloned side-by-side under the same parent directory.
 
+### Portable Builds (Docker / CI)
+
+`file:` refs break in Docker and CI because the sibling repo isn't available at the expected relative path. Use the **tarball prep** workflow to make builds self-contained:
+
+```bash
+# 1. Build all @bytelyst/* packages
+pnpm build
+
+# 2. Pack tarballs + rewrite a consumer's package.json
+#    (run from the consumer repo)
+../learning_ai_common_plat/scripts/prep-consumer.sh <target-dir>
+
+# 3. Build (Docker, EAS, CI — no sibling repo access needed)
+docker build <target-dir>
+
+# 4. Restore original package.json
+../learning_ai_common_plat/scripts/prep-consumer.sh <target-dir> --restore
+```
+
+Each consumer repo has a convenience wrapper: `scripts/docker-prep.sh` (or `scripts/docker-prep-dashboards.sh` in LysnrAI).
+
+| Consumer Repo | Wrapper Script | Targets |
+|---------------|---------------|---------|
+| `learning_voice_ai_agent` | `scripts/docker-prep-dashboards.sh` | `user-dashboard-web` |
+| `learning_ai_clock` | `scripts/docker-prep.sh` | `web` |
+| `learning_ai_fastgap` | `scripts/docker-prep.sh` | root `package.json` |
+| `learning_multimodal_memory_agents` | `scripts/docker-prep.sh` | `mindlyst-native/web` |
+
+> **Dashboards inside this repo** (`dashboards/admin-web`, `dashboards/tracker-web`) use `workspace:*` refs and do NOT need this workflow — pnpm resolves them automatically.
+
 ## Design Tokens
 
 Generate platform-specific token files from the canonical JSON: