From e2dc1e3448a27102eab93c41eec085ef6aa4a7a7 Mon Sep 17 00:00:00 2001
From: Sean Perkins <sean@mobility-labs.com>
Date: Tue, 28 Jul 2026 16:58:16 -0400
Subject: [PATCH] docs: record the install commands that actually work on the
 NAS (SYD-291)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both commands I documented with the wrapper fail on el-duro, found by
running them:

  scp — "subsystem request failed on channel 0". The SFTP subsystem is
  disabled, which is why deploy-nas.sh pipes through tar|ssh rather than
  using scp. `ssh host 'cat > /tmp/x' < file` works.

  visudo -c — "command not found". Not on Synology's PATH. Chained onto
  the end of the install with &&, it made a fully successful install
  look like a failure.

Also records what the run settled: /etc/sudoers.d is unreadable to the
ssh user, so a drop-in file beats editing an existing line, and
#includedir is confirmed active because the rule took effect at once.

Verified end to end afterwards: list-github-repos returns the three real
repos, add-actor refuses with exit 3, and backfill-pr-links --dry-run
reports "would create 0 link(s); 179 already linked" — the SYD-280
migration reproduced through the operator path that did not exist.
---
 scripts/switchyard-admin | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/scripts/switchyard-admin b/scripts/switchyard-admin
index fa371c6..111a9f1 100755
--- a/scripts/switchyard-admin
+++ b/scripts/switchyard-admin
@@ -30,6 +30,26 @@
 # mint-login / mint-supervised-session hand out sessions. Any of those behind a
 # NOPASSWD rule would turn "can ssh to the NAS" into "can obtain full API
 # credentials", which is a bigger grant than this wrapper is meant to make.
+# INSTALL (verified on el-duro 2026-07-28 — both obvious commands fail there):
+#
+#   # scp does NOT work: the SFTP subsystem is disabled, so it dies with
+#   # "subsystem request failed on channel 0". Pipe over ssh instead, the same
+#   # way deploy-nas.sh already does.
+#   ssh "$NAS" 'cat > /tmp/switchyard-admin' < scripts/switchyard-admin
+#
+#   # -t so sudo can prompt: install and the sudoers write are precisely the
+#   # operations no NOPASSWD rule covers. `visudo` is NOT on Synology's PATH,
+#   # so do not chain a `visudo -c` validation onto the end — it exits 127.
+#   ssh -t "$NAS" 'sudo install -o root -g root -m 755 /tmp/switchyard-admin /usr/local/bin/switchyard-admin && \
+#     echo "hardcock ALL=(root) NOPASSWD: /usr/local/bin/switchyard-admin" | sudo tee /etc/sudoers.d/switchyard-admin >/dev/null && \
+#     sudo chmod 0440 /etc/sudoers.d/switchyard-admin'
+#
+#   # Verify WITHOUT -t: this only passes if the NOPASSWD rule really took.
+#   ssh "$NAS" 'sudo -n /usr/local/bin/switchyard-admin list-github-repos'
+#
+# /etc/sudoers.d is unreadable to the ssh user, so a drop-in file is used
+# rather than editing an existing line — and `#includedir /etc/sudoers.d` is
+# confirmed active, since the rule took effect immediately.
 set -e
 
 CONTAINER="${SWITCHYARD_CONTAINER:-switchyard}"