From b7ba35477c6b225597f679a48c633a40b0aaa752 Mon Sep 17 00:00:00 2001
From: archipelago <archipelago@localhost>
Date: Wed, 12 Aug 2026 12:15:55 -0400
Subject: [PATCH] docs(dev-guide): package.install needs dockerImage too;
 helper gotchas
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Learned installing alby-hub/phoenixd for real: the id-only payload fails
with 'Missing dockerImage' (the store normally injects the image from the
catalog), the session helper silently reuses a stale cached session
without ARCHY_FORCE_LOGIN=1, needs jq, and its set -euo pipefail kills an
interactive shell chain without output — so the guide now wraps the flow
in a heredoc subshell.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/app-developer-guide.md | 21 ++++++++++++++++-----
 1 file changed, 16 insertions(+), 5 deletions(-)

diff --git a/docs/app-developer-guide.md b/docs/app-developer-guide.md
index 0e3ad0bc..8b3cfe5a 100644
--- a/docs/app-developer-guide.md
+++ b/docs/app-developer-guide.md
@@ -435,21 +435,32 @@ validates every manifest on load and tells you about problems immediately
 
 **2. Install over JSON-RPC.**
 
-The repo ships the same session helper the release lifecycle gate uses:
+The repo ships the same session helper the release lifecycle gate uses.
+Three things to know before using it: it needs `jq`; it reuses a cached
+session from `/tmp/archy-rpc-session-<uid>` unless `ARCHY_FORCE_LOGIN=1` is
+set (a stale cache fails every call quietly); and it sets `set -euo pipefail`,
+so run it inside a script or subshell — sourcing it into your interactive
+shell makes the first failed step kill the whole chain without printing
+anything.
 
 ```bash
-export ARCHY_PASSWORD='<your dashboard password>'
+bash <<'EOF'
+export ARCHY_PASSWORD='<your dashboard password>' ARCHY_FORCE_LOGIN=1
 # Stock nodes serve HTTPS on 443; dev boxes behind plain nginx use:
 #   export ARCHY_HOST=127.0.0.1 ARCHY_SCHEME=http
 source tests/lifecycle/lib/rpc.bash
-rpc_login
-rpc_call package.install '{"id":"my-app"}'
+rpc_login && echo "login ok"
+# Both fields are required: `dockerImage` is normally supplied by the App
+# Store from the signed catalog — pre-catalog, you pass your manifest's
+# image yourself (it must match, and must come from a trusted registry).
+rpc_call package.install '{"id":"my-app","dockerImage":"docker.io/myorg/my-app:1.0.0"}'
+EOF
 ```
 
 **3. Verify the lifecycle, not just the install:**
 
 ```bash
-rpc_call package.status '{"id":"my-app"}'        # state + health
+rpc_call package.status '{"id":"my-app"}'        # state + health (run inside the same subshell pattern)
 podman ps --filter name=my-app                   # container is up
 rpc_call package.stop '{"id":"my-app"}'          # …and start, restart
 sudo systemctl restart archipelago               # app must survive this