## Install

Two ways to bring fp into a project. Pick one — the end state is the same.

### Run it yourself

```bash
curl -fsSL https://setup.fp.dev/install.sh | sh -s
```

Downloads the latest `fp` binary for your platform and adds it to your path.
Then `cd` into your project and run `fp init`.

### Or hand it to your agent

Paste this into Claude Code, Codex, Cursor, Gemini, or any agent that reads
`AGENTS.md`:

```text
Install fp and start the onboarding loop in this project:

1. curl -fsSL https://setup.fp.dev/install.sh | sh -s
2. fp init --yes --agent standard   # use `--agent claude` for FP_CLAUDE.md / CLAUDE.md
3. fp tree, then work the seeded onboarding children one at a time
```

`--agent standard` writes `FP_AGENTS.md` and ensures `AGENTS.md` `@`-includes it,
so the fp workflow loads into agents that read `AGENTS.md`. Use `--agent claude`
instead when you want Claude-specific `FP_CLAUDE.md` / `CLAUDE.md` files.

## Requirements

- **macOS** (Apple Silicon or Intel) or **Linux** (x86_64)
- A coding agent like Claude Code, Codex, Cursor, Gemini (optional but recommended)

## Verify Installation

```bash
fp --version
```

## Initialize a Project

Navigate to your project directory and run:

```bash
cd your-project
fp init
```

`fp init` does the following:

- Registers the project in `~/.fiberplane/projects.toml` so `fp` commands work
  from any subdirectory.
- Scaffolds `.fp/extensions/` with the extension types and authoring guide.
- Updates `.gitignore` to ignore `.fp/`.
- On the first fp project on a machine, seeds an onboarding issue tree so
  there is something to explore immediately.

In interactive mode, `fp init` then asks which agent instructions to add. You
can answer ahead of time with `--agent`:

| Flag | What it writes |
|---|---|
| `--agent claude` | `FP_CLAUDE.md` and ensures `CLAUDE.md` `@`-includes it |
| `--agent standard` | `FP_AGENTS.md` and ensures `AGENTS.md` `@`-includes it |
| `--agent codex` | alias for `standard` |
| `--agent skip` | no agent instruction files |

You can also run the agent step on its own later with
[`fp agent setup`](#agent-instruction-setup).

For non-interactive setup (CI, scripts):

```bash
fp init --prefix FP --yes --agent skip             # Skip prompts, no extra agent files
fp init --prefix FP --yes --agent claude  # Skip prompts, also write FP_CLAUDE.md / CLAUDE.md
```

## Workflow Primers for Agents

`fp guide` prints workflow primers to stdout as markdown. Pipe them into your
agent or print them for review:

```bash
fp guide plan         # Planning skill
fp guide implement    # Implementation skill
fp guide brainstorm   # Brainstorm authoring (alias: bs)
fp guide extension    # Extension authoring (aliases: extensions, ext)
```

Pass `--references` to surface companion material, for example
`fp guide brainstorm --references mermaid`.

## What Gets Created


```
your-project/
└── .fp/
    └── extensions/           # Scaffolding for authoring fp extensions
```

With `--agent standard` or `--agent codex`:

```
your-project/
├── FP_AGENTS.md              # Agent workflow instructions (managed by fp)
└── AGENTS.md                 # `@`-includes FP_AGENTS.md
```

With `--agent claude` (or by selecting Claude Code in the prompt):

```
your-project/
├── FP_CLAUDE.md              # Claude-specific workflow rules (managed by fp)
└── CLAUDE.md                 # `@`-includes FP_CLAUDE.md
```

`FP_AGENTS.md` and `FP_CLAUDE.md` are managed files. fp owns those files and may
overwrite them. `AGENTS.md` and `CLAUDE.md` are yours; fp only ensures they
`@`-include the corresponding `FP_*` file and never touches user-authored content.

Issue data, comments, and sync state are stored locally outside the repo at
`~/.fiberplane/projects/<storage-dir>/`. The project is registered globally in
`~/.fiberplane/projects.toml` so `fp` commands work from any subdirectory of the
repo.

## Agent Instruction Setup

Already-initialized project? Add or refresh agent files without re-running
`fp init`:

```bash
fp agent setup claude     # Write FP_CLAUDE.md + ensure CLAUDE.md @-includes it
fp agent setup standard   # Write FP_AGENTS.md + ensure AGENTS.md @-includes it
fp agent setup codex      # Alias for `standard`
```

These commands are idempotent — files are only rewritten when their content
drifts from the bundled template, and the `@`-include is only added when it's
missing.

## Update the CLI

```bash
fp update
```

`fp update` installs the latest stable release. Use `fp update --latest` to opt
into prereleases.

## Next Steps

Head to the [Quick Start](/docs/getting-started/quick-start) to create your first issues and learn the fp workflow.