diff --git a/docs/guides/deployment.md b/docs/guides/deployment.md
index 0660222830..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 (`kubectl apply -k k8s/overlays/local/`) |
+| `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:
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