diff --git a/architecture-docs/2025-03-31-ssh-strategy.md b/architecture-docs/2025-03-31-ssh-strategy.md
new file mode 100644
index 0000000..3effedb
--- /dev/null
+++ b/architecture-docs/2025-03-31-ssh-strategy.md
@@ -0,0 +1,87 @@
+# ssh access strategy
+
+some notes on our current status, challenges and ways to address these
+
+## questions
+
+- [x] which keys do we accept on which users on which machines (infra/test)?
+- [x] when deploying (by nixops/tf, machines infra/test, separate/local/deployed), which user and key do we pass?
+
+## background
+
+<!-- - manual setup kevin -->
+  <!-- - `nixos-24.05-minimal-x86_64.iso` -->
+  <!-- - `users.users.procolix.openssh.authorizedKeys.keys` (procolix SSH jump nodes) -->
+- manual setup @niols
+  - sync machines' `/etc/ssh/ssh_host_ed25519_key.pub` to:
+    - `infra/test-machines/testxx/ssh_host_ed25519_key` (test machines)
+    - `keys/systems/fedixxx.pub` (infra)
+
+## challenges
+
+- TF messing up non-root SSH access (`/etc/ssh/authorized_keys.d` absent)
+- TF not having a clear SSH strategy for production
+  - machine key? how to select the right user/key? how does nixops handle this?
+- testing the panel locally not having a clear SSH strategy with password-protected SSH keys
+
+## strategy
+
+### which keys to accept on which users on which machines
+
+- fedixxx/test0x
+  <!-- - procolix -->
+    <!-- - procolix jump nodes -->
+  - root
+    - fediversity team's individual keys
+  - personal
+    - personal (protected)
+- test0x: a passwordless wheel account (personal accounts? root too?) should allow also an unprotected ssh key (personal?)
+
+### how to use SSH on deployment
+
+[^temp]: for now, as per the scope of #274
+[^sensitive]: must be password-protected
+[^agent]: thru ssh agent
+[^inaccessible]: fails to handle password protection
+[^propagate]: with password propagated, somehow
+[^hardcoded]: hard-coded
+[^explicit]: password can be passed explicitly
+[^either]: unprotected, or if protected by passing it explicitly
+
+#### user
+
+|-|-|-|
+| context | current | desired[^temp] |
+| nixops infra | root | root |
+| nixops local | root | root |
+| protected? nixops panel local | root | root |
+| nixops panel deployed | root | root |
+<!-- | tf infra | root | root | -->
+| tf local | personal[^hardcoded] | root |
+| protected? tf panel local | personal[^hardcoded] | root |
+| tf panel deployed | personal[^hardcoded] | root |
+
+#### key
+
+|-|-|-|
+| context | current | desired |
+| nixops infra | personal[^agent] | (protected) personal key |
+| nixops local | personal[^agent] | personal |
+| nixops panel local | personal[^agent] [^inaccessible] | (unprotected) personal key |
+| nixops panel deployed | machine key[^agent] | machine key |
+<!-- | tf infra | n/a | (protected) personal key [^propagate] | -->
+| tf local | personal[^agent] [^explicit] | personal[^either] |
+| tf panel local | personal[^agent] [^explicit] | personal[^either] |
+| tf panel deployed | machine key[^agent] | machine key |
+
+## solutions
+
+- [x] fix ssh user in #274
+- [ ] fix ssh access on test03
+- [?] mimic strategy used with nixops for TF for ssh access from panel (deployed)
+  - [ ] allow access by machine key? or.. how did nixops have access?
+- [ ] use/allow separate unprotected SSH key for test0x VMs (#272)
+- [ ] ensure whitelisted keys for infra are protected
+- [ ] work out way to use password-protected ssh keys in TF for infra? e.g.:
+  - delegate to ssh agent
+  - pass explicitly