Document safe Channel Bank deployment workflow

Author: Will Darney

AGENTS.md

@@ -48,6 +48,11 @@ file, and confirm the requested runtime target. Commit and push the focused
 branch after validation; merge it into `integration/main` only after it is
 working.
 
+Modules may contain a more specific `AGENTS.md`. Read and follow the nearest
+module-level instructions before changing or deploying that module. A scoped
+instruction file may also direct you to a private deployment guide outside the
+repository; never copy private machine details from that guide into a commit.
+
 ## Validation
 
 Configure the combined macOS build from the repository root:

docs/LOCAL_DEPLOYMENT.example.md

@@ -0,0 +1,41 @@
+# Local SDR++ Deployment Guide Template
+
+Copy this template to `../LOCAL_DEPLOYMENT.md` relative to the repository root
+and fill it in locally. The resulting file is outside the Git repository and
+must not be committed.
+
+## Target
+
+- SSH target: `<user>@<host>`
+- launchd domain: `gui/<uid>`
+- Installed application: `/Applications/<test-app>.app`
+- Single rollback application: `/Applications/<test-app>.previous.app`
+- Remote staging path: `/private/tmp/<test-app>.new.app`
+
+## Managed services
+
+List only services that this deployment is authorized to stop and restart.
+
+| Purpose | Label | Plist | Port | stdout | stderr |
+| --- | --- | --- | --- | --- | --- |
+| Server 1 | `<label>` | `~/Library/LaunchAgents/<label>.plist` | `<port>` | `<path>` | `<path>` |
+
+Also list any SDR++ processes or services that must explicitly remain
+untouched.
+
+## Required procedure
+
+1. Build and validate the full app locally.
+2. Copy the new bundle to the remote staging path.
+3. Record which authorized services are loaded.
+4. Boot out only loaded authorized services.
+5. Replace the single rollback copy with the current known-good app.
+6. Move the staged app into the installed location.
+7. Clear extended attributes and sign nested Mach-O files before the bundle.
+8. Verify the installed bundle with strict codesign verification.
+9. Bootstrap only the services that were previously loaded.
+10. Verify service state, listening ports, processes, and logs.
+11. On failure, restore the rollback app and prior service state.
+
+Document any host-specific permission requirements, but do not add passwords,
+private keys, access tokens, or other secrets to this file.

misc_modules/channel_bank/AGENTS.md

@@ -0,0 +1,74 @@
+# Channel Bank Module Instructions
+
+These instructions apply to all work under `misc_modules/channel_bank/` and
+supplement the repository-root `AGENTS.md`.
+
+## Scope and platform preservation
+
+- Keep Channel Bank work scoped to this module unless the user explicitly
+  requests a core or cross-module change.
+- Desktop/macOS uses `src/main.cpp`; iOS uses `src/main_ios.cpp`. Preserve both
+  implementations and their platform-specific CMake wiring.
+- Do not overwrite the iOS implementation with the desktop implementation, or
+  vice versa. Share behavior deliberately when a change belongs on both.
+- Use a task-specific build directory or a build directory known to match the
+  current branch. Do not trust a CMake cache copied from another worktree.
+- Never commit models, recordings, runtime configuration, app bundles,
+  dependency output, or build output.
+
+## Required validation
+
+At minimum, configure the repository with Channel Bank enabled and build the
+`channel_bank` target. Build the full `sdrpp` target when shared interfaces,
+module registration, packaging, or runtime integration changed. For iOS-facing
+changes, also build the iOS simulator application.
+
+Before deployment, record the commit being tested and whether the worktree is
+dirty. A successful library link is not sufficient deployment validation.
+
+## Private deployment configuration
+
+The public repository intentionally contains no SSH host, user name, launchd
+labels, or private paths. Before any Channel Bank deployment, locate the
+repository root and read `../LOCAL_DEPLOYMENT.md` relative to that root.
+
+- If the private guide is absent, stop and ask the user for it. Do not guess
+  the host, service labels, application path, or signing procedure.
+- Never stage or commit the private guide or reproduce its private values in a
+  tracked file, commit message, pull request, or public log.
+- The private guide is operational configuration, not source code. Git pulls
+  and fresh clones do not replace it.
+
+## Remote macOS completion workflow
+
+For Channel Bank work intended for runtime testing, the default completion
+workflow includes deploying the complete macOS test application after build
+validation, unless the user explicitly requests build-only work.
+
+Follow the private guide in this order:
+
+1. Build and validate the complete macOS application locally.
+2. Stage the new app bundle on the remote Mac without touching the installed
+   app or stopping services yet.
+3. Inspect and record which configured plist-managed SDR++ services are
+   loaded. Only those services may be stopped or restarted.
+4. Stop the loaded services with `launchctl bootout`. Do not merely kill their
+   processes because launchd may immediately restart them.
+5. Preserve exactly one complete rollback app using the path in the private
+   guide, then replace the installed test app with the staged bundle.
+6. Clear extended attributes. Sign every nested Mach-O file and dynamic
+   library first, then sign the outer app bundle. Do not rely on deprecated
+   `codesign --deep` signing behavior.
+7. Run full strict codesign verification. If it fails, do not start services
+   from the new bundle; restore the rollback app and verify it instead.
+8. Restart only the services that were loaded before deployment, using their
+   plist files and `launchctl bootstrap`.
+9. Verify each expected service, process, listening port, and recent log. A
+   successful copy or `launchctl` exit status alone is not enough.
+
+Never stop or restart unrelated GUI instances, unmanaged SDR++ servers, or
+services not listed in the private guide unless the user explicitly broadens
+the deployment scope.
+
+If any step after service shutdown fails, prioritize restoring the known-good
+app and the prior service state before investigating the new build.