From 200847f77e434d7e9aa3394d696fea88ccc7bad5 Mon Sep 17 00:00:00 2001
From: jwbron <8340608+jwbron@users.noreply.github.com>
Date: Fri, 24 Apr 2026 18:00:54 +0000
Subject: [PATCH 1/2] docs: update deploy docs for EGG_HOST_REPO_MAP
 auto-discovery

Document changes introduced by a8b132430 (#1991):
- `make deploy` now requires `envsubst` (GNU gettext) and auto-derives
  `EGG_HOST_HOME` and `EGG_HOST_REPO_MAP` from repositories.yaml via
  scripts/build-host-repo-map.py. Update the Deployment Commands table
  in deployment.md to reflect the actual behavior.
- Add a note in local-quickstart.md that `local_repos.paths` entries
  are used to auto-derive EGG_HOST_REPO_MAP at deploy time, so no
  manual editing of k8s overlays is needed.

Authored-by: egg
---
 docs/guides/deployment.md       | 2 +-
 docs/guides/local-quickstart.md | 2 ++
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/guides/deployment.md b/docs/guides/deployment.md
index 0660222830..ca93e247d1 100644
--- a/docs/guides/deployment.md
+++ b/docs/guides/deployment.md
@@ -118,7 +118,7 @@ make build
 | Command | Description |
 |---------|-------------|
 | `make k3s-setup` | Install k3s + Calico CNI (idempotent) |
-| `make deploy` | Deploy all k8s resources (`kubectl apply -k k8s/overlays/local/`) |
+| `make deploy` | Deploy all k8s resources; runs `envsubst` to expand `EGG_HOST_HOME` (default: `$HOME`) and `EGG_HOST_REPO_MAP` (auto-derived from `~/.config/egg/repositories.yaml` via `scripts/build-host-repo-map.py`) into the Kustomize output before applying. Requires `envsubst` from GNU gettext (`dnf install gettext` / `brew install gettext`). Override at deploy time: `make deploy EGG_HOST_HOME=/data/egg` or `EGG_HOST_REPO_MAP='{"owner/repo":"/path"}' make deploy`. |
 | `make build` | Build images and import into k3s |
 | `make k3s-teardown` | Remove k3s installation |
 
diff --git a/docs/guides/local-quickstart.md b/docs/guides/local-quickstart.md
index 76a7d1caef..ef4b0098e2 100644
--- a/docs/guides/local-quickstart.md
+++ b/docs/guides/local-quickstart.md
@@ -63,6 +63,8 @@ local_repos:
     - /path/to/your-repo   # absolute path on host
 ```
 
+`make deploy` reads `local_repos.paths` and queries each repo's `origin` remote URL to auto-derive `EGG_HOST_REPO_MAP` (the JSON map the orchestrator uses for hostPath mounts). No manual editing of Kubernetes overlays is required. `envsubst` (from GNU gettext: `dnf install gettext` / `brew install gettext`) must be installed for `make deploy` to work.
+
 Setting `auth_mode: user` tells the gateway to use `GITHUB_USER_TOKEN` for git/gh operations, attributing commits and PRs to your personal GitHub account.
 
 ## 3. Build and deploy

From daecfbd8faa59f352678e7e6514772908627d212 Mon Sep 17 00:00:00 2001
From: "egg-reviewer[bot]"
 <261018737+egg-reviewer[bot]@users.noreply.github.com>
Date: Fri, 24 Apr 2026 18:17:48 +0000
Subject: [PATCH 2/2] docs: move make deploy details from table cell to
 subsection

Address review feedback: the dense ~350-char table cell is now a concise
one-liner linking to a dedicated subsection with the defaults, overrides,
and prerequisite info.
---
 docs/guides/deployment.md | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/docs/guides/deployment.md b/docs/guides/deployment.md
index ca93e247d1..2adbd53efb 100644
--- a/docs/guides/deployment.md
+++ b/docs/guides/deployment.md
@@ -118,10 +118,26 @@ make build
 | Command | Description |
 |---------|-------------|
 | `make k3s-setup` | Install k3s + Calico CNI (idempotent) |
-| `make deploy` | Deploy all k8s resources; runs `envsubst` to expand `EGG_HOST_HOME` (default: `$HOME`) and `EGG_HOST_REPO_MAP` (auto-derived from `~/.config/egg/repositories.yaml` via `scripts/build-host-repo-map.py`) into the Kustomize output before applying. Requires `envsubst` from GNU gettext (`dnf install gettext` / `brew install gettext`). Override at deploy time: `make deploy EGG_HOST_HOME=/data/egg` or `EGG_HOST_REPO_MAP='{"owner/repo":"/path"}' make deploy`. |
+| `make deploy` | Deploy all k8s resources via Kustomize + `envsubst` (see [details below](#make-deploy-details)) |
 | `make build` | Build images and import into k3s |
 | `make k3s-teardown` | Remove k3s installation |
 
+#### `make deploy` details
+
+`make deploy` runs `envsubst` to expand two variables into the Kustomize output before applying:
+
+- **`EGG_HOST_HOME`** — defaults to `$HOME`.
+- **`EGG_HOST_REPO_MAP`** — auto-derived from `~/.config/egg/repositories.yaml` via `scripts/build-host-repo-map.py`.
+
+**Prerequisite:** `envsubst` from GNU gettext (`dnf install gettext` / `brew install gettext`).
+
+**Override at deploy time:**
+
+```bash
+make deploy EGG_HOST_HOME=/data/egg
+EGG_HOST_REPO_MAP='{"owner/repo":"/path"}' make deploy
+```
+
 ### Network Topology
 
 Kubernetes uses namespace separation and Calico NetworkPolicies for network isolation: