# nib agent quickstart

This is the short operating contract for agents joining a `nib` doc. The
server serves this file from `GET /agents.md`.

For the full human-and-agent CLI/API manual, read [`reference.md`](reference.md)
or fetch `GET /reference.md` from a running server.

---

## Invite prompt

You will usually receive a prompt like this:

```text
Join this nib doc as an agent.
Approve once: `nib agent *`
First run: `nib agent connect https://nib.so/d/<slug> --invite-token <token>`
```

The token is a one-time claim credential. Keep it in the connect command; do
not repeat it in chat, status text, summaries, or final replies.

## First run

If your shell permission model supports persistent approvals, ask for one
narrow approval rule for `nib agent *` before the first command. In
Codex-style sandboxes this is the `["nib", "agent"]` prefix. Do not request
broader `nib *` or shell-wide access.

Run the exact `nib agent connect ...` command from the prompt first. Do not
spend extra approvals on discovery commands such as `which nib`,
`nib --version`, `nib agent ... --help`, shell pipes, or bare `nib ...`
commands. If `nib agent connect` fails because `nib` is missing, ask once for:

```bash
curl -fsSL https://nib.so/install | sh
```

Then return to the `nib agent *` approval rule and run the connect command.

`nib agent connect` claims the invite, detects your platform (`codex`,
`claude`, `cursor`, or similar), stores the returned doc-scoped bearer locally,
announces presence for the browser facepile, fetches the snapshot and open
comments, and prints a short ready summary.

After connecting, tell the human you are in the doc and ready for instructions.
Do not edit, comment, resolve, or otherwise mutate the doc until the human asks.

## Identity

Agent handles should stay tied to the human who invited you. When `nib` knows
the human email, the invite prefix is the email local part before `@`, with any
`+tag` removed: `kmiller@dropbox.com` becomes `kmiller`. When `nib` only knows
a display name, multi-word names use first initial plus last word (`Kyle Miller`
becomes `kmiller`) and one-word names use the normalized word (`Dropbox`
becomes `dropbox`).

The server appends your platform after a dash, so Codex joining for Kyle Miller
becomes `kmiller-codex`. If platform detection is wrong, rerun connect with
`--force --platform codex`, `--force --platform claude`, or
`--force --platform cursor`.

## Work from the URL

Opening or reading a share URL must not create a local `.md` mirror. Work from
the doc URL by default, and only pull to a local path if the human explicitly
asks for a local mirror.

Use only `nib agent ...` commands after connecting:

```bash
nib agent guide
nib agent urls
nib agent read <url>
nib agent comments <url> --json
nib agent comment <url> --text "..." --quote "..."
nib agent reply <url> --mark <markId> --text "..."
nib agent edit-block <url> --ops ops.json
nib agent activity <url> --json
nib agent revert <url> <event-id>
nib agent status <url>
nib agent sync <url>
nib agent sync diff <url>
nib agent do <url> "make the requested change"
```

Most product commands also accept `nib agent <command> ...`, including
catalog, sync, conflict, comment, edit, activity, revert, invite/token,
delete/restore, and watcher/auth/status actions. The shell approval only grants
permission to run the CLI command; server-side doc roles, tokens, owner secrets,
and capabilities still decide whether the action is allowed.

For edits, prefer surgical block operations (`edit-block`) or the guided
`nib agent do` flow. Blocks you do not reference stay untouched, so anchored
comments survive normal non-overlapping edits, including table-cell edits.

For mirrored docs, remember that agents and browser users cannot see unsaved
editor buffers. If local and cloud disagree, ask whether the human wants smart
sync instead of a directional replacement.

## Safety

Do not print invite tokens, bearer tokens, owner secrets, or share access
tokens. Treat a hosted invite token as single-use; after connect, let the CLI
load the stored doc credential.

Obey capability errors. Viewer tokens cannot mutate. If a mutation fails with
`LIVE_DOC_BUSY`, `CONFLICT`, or another structured code, stop broad changes and
report the latest code and message rather than retrying blindly.

If you need CLI flags, HTTP endpoints, JSON request bodies, table-cell editing
details, activity history, or the `/edit/v2` retry loop, use
[`reference.md`](reference.md).