From 244759114ae6e097e31215fc08fe3cf310b5a78a Mon Sep 17 00:00:00 2001
From: Teknium <127238744+teknium1@users.noreply.github.com>
Date: Tue, 28 Jul 2026 22:36:13 -0700
Subject: [PATCH] docs(photon): document immutable-install sidecar resolution
 (setup step + sidecar README)

---
 plugins/platforms/photon/sidecar/README.md  | 6 +++++-
 website/docs/user-guide/messaging/photon.md | 7 ++++++-
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/plugins/platforms/photon/sidecar/README.md b/plugins/platforms/photon/sidecar/README.md
index 67d332a8427..b511c1f6072 100644
--- a/plugins/platforms/photon/sidecar/README.md
+++ b/plugins/platforms/photon/sidecar/README.md
@@ -21,7 +21,11 @@ npm install
 ```
 
 The Hermes plugin's `hermes photon setup` command runs `npm install`
-here automatically.
+automatically. When the plugin directory is read-only (Docker/Podman
+images, immutable install trees), deps resolve through
+`sidecar_paths.resolve_sidecar_dir()`: an explicit `PHOTON_SIDECAR_DIR`
+override → writable-in-place → a baked image copy → a mirror under
+`~/.hermes/photon/sidecar` (created and installed on demand).
 
 ## Run standalone
 
diff --git a/website/docs/user-guide/messaging/photon.md b/website/docs/user-guide/messaging/photon.md
index c37361ef93f..d789894348d 100644
--- a/website/docs/user-guide/messaging/photon.md
+++ b/website/docs/user-guide/messaging/photon.md
@@ -73,7 +73,12 @@ The setup, in order:
    user with that number already exists, so re-running is safe.
 5. **Prints your assigned iMessage line** — the number you text to reach
    your agent.
-6. **Runs `npm install`** inside the plugin's sidecar directory.
+6. **Runs `npm install`** for the sidecar. On writable source checkouts this
+   installs into the plugin's own `sidecar/` directory; on read-only or
+   immutable installs (Docker/Podman images, hosted deployments) the deps
+   resolve to a baked image copy or are mirrored under
+   `~/.hermes/photon/sidecar` automatically. Set `PHOTON_SIDECAR_DIR` to
+   override the location explicitly.
 
 Runtime credentials are written to `~/.hermes/.env`
 (`PHOTON_PROJECT_ID` = the Spectrum project id, `PHOTON_PROJECT_SECRET`),