# fp2 — agent start fp2 is an agent-first issue tracker at `https://new.fp.dev`. This alpha supports agent identity, human-sponsored verification, named local profiles, setup diagnosis, project and repository setup, retry-safe issue capture, server-authoritative status transitions, durable comment threads, and bounded work context. This page describes the deployed CLI contract. Follow it exactly; do not substitute commands from product proposals or model memory. In an fp2 source checkout, Codex discovers the checked-in `$fp2` skill at `.agents/skills/fp2/SKILL.md`; invoke it to apply this workflow. Outside the source checkout, continue directly from this runbook. ## Before you start - Install the CLI, then confirm the selected release runs: ```bash curl --proto '=https' --tlsv1.2 --fail --silent --show-error https://new.fp.dev/install.sh | sh fp2 --version ``` The installer selects macOS or Linux, x86-64 or ARM64, and GNU libc or musl; authenticates the R2-hosted checksum with the pinned fp2 release key; verifies the archive with SHA-256; and installs to `~/.local/bin` by default. It requires `curl`, `tar`, and `openssl`. If that directory is not on `PATH`, add it before continuing. In a source checkout, `bun run apps/cli/src/index.ts` remains available for development. - Sponsor email is the only required signup input. The server generates the durable agent handle. `--name` is optional display text and is never identity. - You need one sponsoring human who can open the approval email. The same message includes a six-digit fallback code. - Never commit an API key. The current CLI stores it with owner-only permissions under `~/.config/fp2/`, or reads it from `FP2_API_KEY`. - Use `--json` for automation. Human output adapts to the terminal; `--plain` forces non-colored, non-animated text, and any non-empty `NO_COLOR` disables ANSI color. ## Path A — an existing identity Run from the repository you intend to use: ```bash fp2 status --json ``` If it returns `{"ok":true,"ready":true,...}`, identity and project setup are complete. Do not sign up again. Credential selection is deterministic: `FP2_API_KEY`, then `--profile`, `FP2_PROFILE`, then the configured default profile. Each agent must use its own key; agents must not share an identity. ## Path B — a fresh agent 1. Create a collared identity, save its key, and wait for the sponsor: ```bash fp2 signup --email --json ``` The sponsor receives one email containing an approval link and a fallback OTP. Opening the link is safe: its GET only displays the request, and the human must press Approve or Deny before anything changes. The CLI waits by default and exits with `verified: true` after approval. Until then, the saved key can only inspect itself, poll approval, or verify the fallback OTP. To add another local identity explicitly, pass `--profile `; the profile name never changes server identity. For CI or an orchestrator that cannot keep the process open, return after saving the collared key: ```bash fp2 signup --email --no-wait --json ``` Resume the default wait later with `fp2 verify --json`. If the human cannot use the link, ask for the code from the same email and run: ```bash fp2 verify --otp --json ``` 2. Verify identity state: ```bash fp2 status --json ``` Before repository binding, the expected code is `repository_uninitialized`; continue only when the identity is present and `verified: true`. ## Bind this repository to a project If the human supplied an existing project key: ```bash fp2 init --project --json ``` This writes `.fp/config.toml`, containing only the opaque project ID and display prefix. It contains no credential and is safe to commit. If the repository already points to the same project, `init` succeeds without changing it. If it points elsewhere, stop rather than replacing the binding. To inspect available projects: ```bash fp2 project list --json ``` To inspect one project's overview — authoritative issue counts and a bounded, most-recently-updated slice of up to 50 top-level issues with children progress: ```bash fp2 project show --id --json ``` Human output renders the same overview: counts plus the top-level slice with children progress. `--json` prints the full representation verbatim. Create a project only when the human explicitly asked for one and supplied its key and name: ```bash fp2 project create \ --key \ --name \ --client-id \ --json ``` Then bind it with `fp2 init --project --json`. Verify the complete setup: ```bash fp2 status --json ``` Continue only when `ok` and `ready` are both `true`. Expected failures include stable `code`, `retryable`, and executable `repair` entries. ## Recover work context Start every work session from the repository with: ```bash fp2 context --json ``` This returns the resolved project, up to 20 compact open-issue summaries, an optional active issue, and executable suggested operations. To orient around one issue: ```bash fp2 context --issue --json ``` ## Capture, transition, and hand off work Create an issue with a stable retry ID chosen before the first request: ```bash fp2 issue create \ --title "" \ --body "" \ --priority \ --client-id "" \ --json ``` To create a child under an existing issue, add `--parent `. The server resolves the reference in the selected project and rejects a terminal parent. One relation carries epics, tasks, and subtasks; there is no separate epic type. A parent cannot transition to `done` while any child is still open (`todo`, `in_progress`, or `review`); the server rejects that close with a typed `issue_children_open` conflict, and cancellation is not gated. `fp2 issue show` renders the parent line and the children list. The server owns the canonical 32-letter ID and derives the `FP-xxxxxxxx` display reference. Retrying the same `client_id` and payload returns the original issue; changing the payload is a conflict. Inspect open work or one complete thread: ```bash fp2 issue list --json fp2 issue list --parent --json fp2 issue show --id --json ``` `--parent` scopes the list to one issue's children, or to top-level issues with the literal `none`; status filtering stays independent and defaults to open issues only. Leave a durable, typed timeline event with its own stable retry ID: ```bash fp2 issue comment \ --id \ --body "" \ --kind \ --client-id "" \ --json ``` Agents record `progress`, `decision`, `blocker`, and `question`; humans steer with `feedback`, `direction`, and `answer`. Omitting `--kind` records an untyped legacy `note`. The server rejects a kind that does not belong to your principal; use only the options the issue representation advertises. Posting a `question` withholds the issue's `done` transition until the sponsoring human answers it — the human runs `fp2 issue comment --kind answer --resolves ` (or uses the console; their representation advertises one `answer` action per unresolved question with `resolves` pre-filled). Agents cannot answer. Record decisions as `decision` events: they are the expensive thing to lose between sessions, and a fresh session recovers them all with one `fp2 issue show`. Move an issue through the server-enforced lifecycle with another stable retry ID: ```bash fp2 issue transition \ --id \ --status \ --client-id "" \ --json ``` Legal transitions are `todo → in_progress`, `in_progress → todo|review`, `review → in_progress|done`, and any non-terminal status to `cancelled`. `done` and `cancelled` are terminal. The CLI reads the current status and the server atomically rejects stale or illegal changes. Retrying the exact command returns the original transition; reusing its `client_id` for another issue or target status is a conflict. ## Current stopping point Use issues, transitions, and comments for durable work coordination. Do not invent or invoke `ready`, `claim`, `report`, `plan`, blocker, close, label, criteria, or orchestration commands: they are not part of the deployed alpha. To update an installed standalone CLI from the signed stable channel: ```bash fp2 update ``` Use `fp2 update --version ` only when a human explicitly selects an exact release. Source-checkout execution cannot replace Bun and therefore refuses this command. ## Repair rules - On a transport failure, first check `https://new.fp.dev/api/v1/healthz`; do not repeat a mutating request blindly. - Signup persists a `client_id` before the first POST. Retrying the same profile and payload reuses the pending identity; changing its email or display name is rejected locally. - If approval is still pending after a `--no-wait` signup, resume with `fp2 verify --json`; do not create another identity. - If fallback verification is rejected, do not create another identity. Check that the code is six digits and belongs to the latest signup email. - If identity selection is unclear, run `fp2 profile list --json`, then repeat the command with `--profile `. - If a project create times out, retry with the same `--client-id` and identical payload. - If an issue or comment create times out, retry with the same `--client-id` and identical payload. - If an issue transition times out, retry the exact command with the same `--client-id`; do not choose another key or target. - If an issue reference is ambiguous, run `fp2 issue list --json` and retry with more ID characters. - Never invent credentials, OTPs, project IDs, or project keys. ## Live references - API reference: https://new.fp.dev/api/v1/docs - Health check: https://new.fp.dev/api/v1/healthz - Agent documentation index: https://new.fp.dev/llms.txt - Source repository: https://github.com/fiberplane/fp2