docs/JOIN_PROMPT.md

Rama main · réplica de lectura del repositorio original.

# Joining a project: the prompt a newcomer pastes into their agent

Nobody joining a Ferryman project should see a terminal. The inviter makes a code on
the dashboard (Teammates -> *Make the code*); what comes out is not a command but a
**prompt** - the newcomer pastes it into whatever AI agent they use (Claude Code,
Claude desktop with computer access, Cursor, Codex, Copilot: anything that can run a
command on the machine they will work from), and the agent does the setup. Someone
with no agent runs the same numbered steps in a terminal; they are ordinary commands.
The one thing the agent never does is create the person's identity: that happens in a
browser tab it hands over, where the person picks their own password and sees their
recovery phrase once.

What the prompt makes the agent do:

1. Install `ferry` with the platform's install script and confirm the version.
2. `ferry team invite accept <code> --email <theirs>` - starts the managed Syncthing
   (installing it with winget or brew if absent), names this device after the invite,
   trusts the inviter, creates the project folder under `~/Ferryman/<project>`,
   registers the channel folder shared with the inviter, and writes a signed
   acceptance. With no terminal attached, identity creation is deferred to the browser.
3. `ferry dashboard` from that folder - prints a one-time setup token and opens the tab.
   The agent relays the token and steps back.
4. The person creates their identity in the tab: the reserved name, a password, the
   24 words. Their keys land in their copy of the channel.

How long the access lasts is the inviter's choice, made on every invitation, and is separate
from how long the code works. On the dashboard the form has "Access lasts" (1, 7, 14, 30 or 90
days, or no expiry; no default) and "Code valid for" (1, 3 or 7 days). From a terminal:

```text
ferry team invite create --name david --agent david-agent --access 30            # 30 days of access
ferry team invite create --name david --agent david-agent --access forever       # no expiry
ferry team invite create --name david --access 30 --expires-days 3               # code valid 3 days
```

`--access` is required (a machine added under your own identity, `--as-identity`, takes none and
lapses with its owner). Timed access runs from the moment the grant is signed; a few days before
it ends the inviter is asked to Renew or Let it end, and no answer lets it end. See ADR 0029.

Meanwhile the inviter's Ferryman (the worker loop, or the dashboard while it is open)
sees a device knocking under the invite's name, trusts it and shares the folder. When the
newcomer's keys and acceptance sync back, the dashboard signs the grant the invite
promised. The inviter's Vault can then seal secrets to the newcomer's agent.

The prompt text itself is generated by the dashboard with the code and names filled in;
`crates/ferryman-server/src/dashboard.html` is its source of truth. It requires a
released `ferry` of 0.5.8 or newer on the newcomer's side, because `team invite accept`
first shipped there.