diff --git a/doc/design/p2p_socket_transport.mdwn b/doc/design/p2p_socket_transport.mdwn
new file mode 100644
index 0000000000..725acb8b5e
--- /dev/null
+++ b/doc/design/p2p_socket_transport.mdwn
@@ -0,0 +1,40 @@
+This is a generic interface that allows git-annex to use a P2P network.
+
+Examples of such networks are tor, yggstack or fowl. (git-annex has a
+built-in integration with tor which does not use this interface.)
+
+Such a P2P network has some form of address, which can be
+used to connect to a given peer by address across the network.
+
+A git remote using the P2P network has an url of the form
+`p2p-annex::<netname>+<address>`
+
+To connect to that remote, git-annex runs the command
+`git-annex-p2p-<netname>`, giving it the P2P network address as its only
+parameter. The command is responsible for connecting to that peer, and
+relaying data to it. Data fed into the command on stdin should be sent to
+the peer, and data received from the peer should be output to stdout. If it
+is unable to connect, the command can exit nonzero. When the peer closes
+connection, the command can exit zero.
+
+To handle incoming connections from peers, `git-annex remotedaemon`
+runs `git-annex-p2p-<netname>` with the parameter "socket", followed 
+by the P2P address of the local repository. The command
+should output the path of a unix socket file. When it does, `git-annex
+remotedaemon` will use that socket file to listen for connections from
+peers, and service them. (The [[P2P_protocol]] is spoken over these
+connections.)
+
+Note that, if the P2P network does not natively use a unix socket file,
+a command like `socat` can be run by `git-annex-p2p-<netname> socket` 
+to convert the P2P network's own equivilant into a unix socket file.
+
+To configure `git-annex remotedaemon` to listen on a given P2P network,
+the user runs `git-annex p2p --enable <netname>`. That also
+runs `git-annex-p2p-<netname>`, this time with the parameter "address".
+That should output the P2P network address that can be used by peers
+to connect to the repository.
+
+The program [[git-remote-p2p-annex]] is included in git-annex as a git
+remote helper program. git will use that program to handle `pull` and
+`push` with git remotes that use the `p2p-annex::` url scheme.
diff --git a/doc/todo/generic_p2p_socket_transport/comment_12_c106b0a8011cc5f66e35894e9899c2ab._comment b/doc/todo/generic_p2p_socket_transport/comment_12_c106b0a8011cc5f66e35894e9899c2ab._comment
new file mode 100644
index 0000000000..b6b2203482
--- /dev/null
+++ b/doc/todo/generic_p2p_socket_transport/comment_12_c106b0a8011cc5f66e35894e9899c2ab._comment
@@ -0,0 +1,22 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""comment 12"""
+ date="2025-07-29T16:41:07Z"
+ content="""
+I have started a design document at [[design/p2p_socket_transport]],
+to collect all the scattered decisions here into a coherent document that
+can be used by someone implementing support for one of these networks.
+
+In the process, I realized that rather than defining a path where git-annex
+expects the socket file to be, it could run the same `git-annex-p2p-foo`
+command in a mode where the command outputs the path to the socket file.
+That also lets the command run socat to connect up the socket, for example.
+
+I also put in there that `git-annex p2p --enable <netname>` will run
+`git-annex-p2p-<netname> address`, which will output the P2P address that
+peers will use to connect the the repository. That seemed nicer than
+requiring the user to somehow come up with the P2P address on their own.
+
+I have started writing the user-level documentation too, on the
+`genericp2p` branch.
+"""]]