Skip to content

docs: refresh the readme and cli help for invitations - #12

Merged
cablehead merged 1 commit into
mainfrom
docs/readme-and-help
Aug 18, 2026
Merged

docs: refresh the readme and cli help for invitations#12
cablehead merged 1 commit into
mainfrom
docs/readme-and-help

Conversation

@cablehead

Copy link
Copy Markdown
Owner

Catches the README and --help up with what shipped in #10 and #11.

CLI

--help still opened with "What happens when you want dumbpipe to stay running,
handle a few ports at once, and reconnect when your laptop wakes up", a tagline
the README replaced a while ago. Now -h gives a one-line summary and --help
gives the README's opening, including the sentence that matters most: access is
default deny and per peer.

Command descriptions were written when the commands were named differently.
expose said "Expose a port to specific peers (a directed grant)", which
explains the mechanism to someone who already knows it. It now says nothing is
reachable without a grant. project now leads with the fact that peers are
projected automatically, so you only need it to pin an address or rename one.
Two help strings still said "enrollment label".

README

Three things were stale:

  • The intro said an unknown machine "enrolls with a one-time token".
  • Surfaces said a peer is named after "its enrollment label". Labels are gone;
    it is the name you gave it, or a short form of its key.
  • The example ended with pai-sho expose 3002 --to <laptop-key>, asking the
    reader for a key the example never gave them. It is --all now, with a line
    saying what --all does and does not mean.

One thing was missing. The README described a single shape: an operator with
workloads that phone home. That was accurate before, but the invite/accept work
was driven by the other shape, two long-lived machines where the provider
invites and the consumer names. The intro now says a link is mutual and works
either way, and a new More section points at docs/scenarios.md, which was
not linked from anywhere.

On the ordering

I looked at whether Example should move below Install, since it opens with "the
daemon is already running on its own network interface". It already links both
Install and Setting up the network in that sentence, so a reader who needs setup
can get there. Leading with the example is the right call for this project.
Left as is.

@cablehead
cablehead merged commit 22f833f into main Aug 18, 2026
1 check passed
@cablehead
cablehead deleted the docs/readme-and-help branch August 18, 2026 17:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant