# Flock install & bootstrap runbook

> **STATUS: 0.4.1-alpha.** Real and moving fast: accounts, profiles, sessions with
> live status, persistent workers, delegation with quota-aware routing, the lead
> protocol, and native Claude Code surfaces. Unsigned binaries, sharp edges.
> This runbook describes exactly what exists — nothing more.

Written for **agents and humans alike**. An agent following it must honor every
consent gate — they are part of the contract, not decoration.

## What gets installed

- `flk` — a single static binary, installed to `~/.local/bin`
- tmux, if missing and consented (sessions live in tmux)
- Per profile, at wire time: event hooks, the flock MCP server entry, `/flock:*`
  slash commands, a delegation skill, and a statusline — all namespaced, all
  removed by `flk profile rm`
- No secrets stored, no network listeners, ever

## 1. Install the binary

Detect platform (`uname -sm`) and map to an artifact:

| uname -sm        | artifact           |
|------------------|--------------------|
| `Darwin arm64`   | `flk-darwin-arm64` |
| `Darwin x86_64`  | `flk-darwin-amd64` |
| `Linux aarch64`  | `flk-linux-arm64`  |
| `Linux x86_64`   | `flk-linux-amd64`  |

```sh
curl -fsSL -o /tmp/flk "https://tryflock.xyz/dl/<artifact>"
curl -fsSL "https://tryflock.xyz/dl/checksums.txt" | grep "<artifact>"
shasum -a 256 /tmp/flk
```

**The two SHA-256 values must match exactly. On mismatch: STOP, delete, report.**

⛔ **CONSENT GATE** — show the user these commands, get a yes:

```sh
mkdir -p ~/.local/bin && install -m 0755 /tmp/flk ~/.local/bin/flk
```

## 2. Accounts and profiles — identity first

```sh
flk account add <name> --provider anthropic --owner <legal-party> --email <account-email>
flk profile add work --agent claude --account <name>
flk use work
```

`--email` enables **identity attestation**: `flk whoami` cross-checks who each
profile is *actually* logged in as against who it *claims* to be, and flags
drift loudly. Accounts sharing one beneficial owner delegate freely; crossing
owners is deliberate, never silent.

## 3. Log in — 🧑 HUMAN ONLY

```sh
flk profile login work
```

Needs a real terminal (TTY). The flow names the expected account before the
browser opens and attests the result after — pick the account it tells you to.
**Agents: hand this to the user. Never touch credentials.**

## 4. Wire the native surfaces

```sh
flk profile wire
```

Installs, per profile home: lifecycle hooks (live statuses), the flock MCP
server, `/flock:status` `/flock:delegate` `/flock:recall` `/flock:handoff`
`/flock:whoami` commands, the flock-delegation skill, and a statusline.
**Surfaces load at session start — restart sessions when convenient; never
mid-work.**

## 5. Live

```sh
flk new                      # session under the right profile (repo-pinnable via .flock.toml)
flk ls                       # every session, status, age — including workers
flk ui                       # dashboard; flk switch for the tmux popup
flk attach <name|lead>       # jump anywhere
```

**Delegation & workers:** `flk delegate --to <profile|claude:auto> "brief"`
dispatches into the target profile's *persistent worker session*
(`<profile>-worker`) — a real, attachable tmux session, never an invisible
process. `claude:auto` routes to the least-consumed logged-in identity and
always names its choice. `flk task ls|status|result` is the ledger.

**Lead protocol:** `flk lead grant <session>` (owner's hand) designates the
lead — the session you talk to by default. The lease is an artifact (pid-
verified), never testimony. Leads recuse with `flk lead recuse --successor
<session|claude:auto>`; a dead lead means `LEAD DOWN` in every statusline
until the owner re-grants. No self-election.

**Usage:** `flk usage` shows per-profile consumption (5h/7d, from transcripts).
`flk usage --live` fetches **authoritative quota** (weekly utilization, resets,
5-hour window) using each profile's own token — macOS, GUI context only (the
Keychain refuses SSH sessions, by design). Sessions can self-serve via the
`flock_usage` MCP tool — leads plan from workers' real numbers.

## 6. Verify — done means verified

```sh
flk --version && flk doctor && flk whoami
```

Doctor ok + attested identities = installed. `flk ls` after your first
`flk new` = alive.

---

*Flock · tryflock.xyz · the binary is `flk` · 0.4.1-alpha*