The `fp` CLI is the primary interface for agent-native issue tracking. All commands work locally and are designed to be used by both humans and AI agents.

## Commands

### Project Setup

| Command | Description |
|---------|-------------|
| `fp init` | Initialize `.fp/` in your project |
| `fp setup claude` | Configure Claude Code integration |

### Issue Management

| Command | Description |
|---------|-------------|
| `fp issue create --title "..."` | Create a new issue |
| `fp issue create --title "..." --parent ID` | Create a sub-issue |
| `fp issue create --title "..." --property labels=frontend,backend` | Create with extension fields |
| `fp issue list` | List all issues |
| `fp issue list --status todo` | Filter by status |
| `fp issue show ID` | Show issue details and comments |
| `fp issue update --status STATUS ID` | Update issue status |
| `fp issue update --property labels=frontend ID` | Update extension fields |
| `fp issue assign ID --rev COMMIT` | Attach commit(s) to an issue |
| `fp issue diff ID` | Show diff for issue's commit range |
| `fp issue files ID` | Show files changed in commit range |

### Navigation & Context

| Command | Description |
|---------|-------------|
| `fp tree` | View the full issue hierarchy |
| `fp context ID` | Load full issue context (for agents) |
| `fp comment ID "message"` | Add a comment to an issue |

### Brainstorms

| Command | Description |
|---------|-------------|
| `fp bs create <file>` | Create a brainstorm from an HTML file |
| `fp bs list` | List all brainstorms |
| `fp bs show ID` | Show brainstorm HTML (or open in desktop with `--desktop`) |
| `fp bs open ID` | Open brainstorm in desktop app |
| `fp bs update ID --file <path>` | Publish a new version |
| `fp bs delete ID` | Delete a brainstorm |
| `fp bs comments ID` | List comments on a brainstorm |
| `fp bs comments add ID "text"` | Add a comment (use `--selector` to pin to an element) |
| `fp bs comments delete ID COMMENT_ID` | Delete a comment |
| `fp bs versions ID` | List version history |

### Agent Identity

| Command | Description |
|---------|-------------|
| `fp agent whoami` | Show current agent identity |

## Issue Statuses

Issues have three statuses:

| Status | Meaning |
|--------|---------|
| `todo` | Planned, not yet started |
| `in-progress` | Actively being worked on |
| `done` | Completed |

VCS refs are captured on status transitions:

- **Base commit** — captured when moving to `in-progress`
- **Tip commit** — captured when moving to `done`

This enables `fp issue diff` and `fp issue files` to show exactly what changed.

## Priority Levels

Issues support priority levels: `low`, `medium`, `high`.

```bash
fp issue create --title "Fix critical bug" --priority high
```

## Getting Help

Every command supports `--help`:

```bash
fp --help
fp issue --help
fp issue create --help
```