Brainstorms are markdown documents with rich directives — callouts, cards, labels, mermaid diagrams, filetrees — stored locally, versioned on every update, and commentable. Read them from the terminal or open them in the Mac desktop app for a rendered view.

Reach for a brainstorm when you're capturing a design or proposal. Reach for an [issue](/docs/cli/issue-tracking) when the work is trackable and needs a status.

<!-- SCREENSHOT: rendered brainstorm in the desktop app showing a mix of callouts, a mermaid diagram, and a label — gives readers a sense of the end result before they start authoring. -->

## Creating a Brainstorm

Write a markdown file, then create the brainstorm:

```bash
fp bs create path/to/plan.md
```

```
Created brainstorm: Auth refactor plan (dardepfromppbeyeeoryqtizcamqezio)
fp://brainstorm?id=dardepfromppbeyeeoryqtizcamqezio&project=%2FUsers%2Fme%2Fproj
```

The title is taken from the first `# heading` in the file. Override it with `--title`:

```bash
fp bs create path/to/plan.md --title "Q2 auth refactor"
```

The second line of the output is an `fp://` deep link. When run interactively, fp also hands the link to the OS opener (`open` on macOS, `xdg-open` on Linux, `start` on Windows) so the desktop app launches it automatically.

For machine-readable output, pass `--format json`:

```bash
fp bs create path/to/plan.md --format json
```

```json
{
  "id": "dardepfromppbeyeeoryqtizcamqezio",
  "deepLink": "fp://brainstorm?id=dardepfromppbeyeeoryqtizcamqezio&project=%2FUsers%2Fme%2Fproj"
}
```

`fp brainstorm` and `fp bs` are interchangeable. Short ID prefixes work wherever an ID is accepted.

## Authoring with Directives

On top of standard GitHub-flavored markdown, brainstorms understand a small set of directives. They render to rich blocks in the desktop app and to plain markdown in the terminal.

### Callouts

```markdown
:::callout{type="info"}
Key context or background information.
:::

:::callout{type="warning"}
Risk or caveat to highlight.
:::

:::callout{type="decision"}
A decision that was made and its rationale.
:::

:::callout{type="question"}
An open question that needs resolution.
:::
```

<!-- SCREENSHOT: the four callout variants rendered side-by-side in the desktop app. Placed right after the source, pairs the markdown with the rendered result. -->

### Cards

```markdown
:::card{title="Component Overview"}
Grouped content — paragraphs, lists, tables, code blocks.
:::
```

### Inline labels

```markdown
:label[Active]{color="green"}
:label[Blocked]{color="red"}
:label[In Review]{color="orange"}
:label[Planned]{color="blue"}
:label[Deprecated]{color="purple"}
```

Supported colors: `green`, `red`, `orange`, `blue`, `purple`.

### Mermaid diagrams

Standard fenced `mermaid` blocks render with automatic light/dark theming.

````markdown
```mermaid
graph TD
  A[CLI] --> B[fp-core]
  B --> C[(Local Y.Doc)]
  C --> D[Desktop app]
```
````

See the [mermaid docs](https://mermaid.js.org/intro/) for syntax.

<!-- SCREENSHOT: the mermaid example above rendered in both light and dark mode. The theming is a headline feature worth showing. -->

### Filetrees

Use a fenced `filetree` block for directory layouts. Draw hierarchy with ASCII tree characters (`├──`, `└──`, `│`); space-based indentation renders flat.

````markdown
```filetree
src/
├── components/
│   ├── Button.tsx     # new
│   └── Dialog.tsx     # modified
└── utils/
    └── legacy.ts      # deprecated
```
````

Annotations: `# new` (green), `# modified` (orange), `# deprecated` (muted + strikethrough).

### Comment references

`::comment-ref{id="..."}` anchors a comment to a specific block. The desktop sidebar inserts this directive automatically when you comment on a block. From the CLI, `fp bs comments add` prints the snippet for you to paste into the markdown yourself. See [Comments](#comments) below.

```markdown
## API changes

::comment-ref{id="ifefqrpidlidywdimqgdszqbxwrcdgcr"}

We need to decide between REST and gRPC before the end of the week.
```

### Standard GFM

Tables, task lists, inline code, and fenced code blocks all work.

## Viewing Brainstorms

List brainstorms in the current project:

```bash
fp bs list
```

```
ID        STATUS      UPDATED       TITLE
────────────────────────────────────────────────────────
1f2c3a8b  draft       Apr 17        Auth refactor plan
```

Include soft-deleted brainstorms:

```bash
fp bs list --deleted
```

Dump the raw markdown:

```bash
fp bs show <id>
```

Include comments inline. Each `::comment-ref{...}` marker is replaced by the thread it anchors, and unanchored comments are listed under an `## Unanchored Comments` heading at the bottom:

```bash
fp bs show <id> --with-comments
```

Resolved threads are hidden by default. Add `--resolved` to include them:

```bash
fp bs show <id> --with-comments --resolved
```

View an older version. The argument is either a raw version ID or a 1-based display number (v1 is the oldest):

```bash
fp bs show <id> --version 2
```

Open the brainstorm in the Mac desktop app:

```bash
fp bs show <id> --desktop
# or the equivalent shortcut
fp bs open <id>
```

<!-- SCREENSHOT: desktop app brainstorm list view. Useful to pair with `fp bs list` so readers see both surfaces. -->

## Versions and Updates

Every `update` creates a new immutable version. Older versions stay accessible via `fp bs show --version`.

```bash
fp bs update <id> path/to/revised.md
```

```
Updated brainstorm: Auth refactor plan (v2)
```

List version history:

```bash
fp bs versions <id>
```

```
Versions of "Auth refactor plan" (2):

  LABEL  AUTHOR                 CREATED
  ──────────────────────────────────────────────────
  v1     alice                  Apr 15 at 10:12 AM
  v2     alice                  Apr 17 at 02:33 PM
```

Agents editing a brainstorm typically:

1. Read it with `fp bs show <id> --with-comments`.
2. Edit the markdown locally.
3. Apply with `fp bs update <id> revised.md`.
4. Resolve any threads addressed in the edit.

## Comments

A comment is either **anchored** to a specific block via a `::comment-ref{id="..."}` directive in the markdown, or **unanchored**. Unanchored comments appear in the desktop sidebar's general thread and under `## Unanchored Comments` in `fp bs show --with-comments`.

The desktop sidebar inserts the `::comment-ref` directive automatically when you comment on a block. The CLI prints the snippet so you can paste it into the markdown yourself.

List comments on a brainstorm (this is the default `comments` subcommand):

```bash
fp bs comments <id>
```

```

## Thread 1f2c3a8b
   (1f2c3a8b) alice [Apr 17]:
     This approach doesn't handle the token refresh race.
```

Add a comment:

```bash
fp bs comments add <id> "This approach doesn't handle the token refresh race."
```

```
Added comment: ifefqrpidlidywdimqgdszqbxwrcdgcr
Place this comment in a brainstorm with:
  ::comment-ref{id="ifefqrpidlidywdimqgdszqbxwrcdgcr"}
```

Paste the `::comment-ref{...}` line beside the block you want to anchor the comment to, then `fp bs update` to apply.

Resolve a thread:

```bash
fp bs comments resolve <id> <commentId>
```

Soft-delete a comment:

```bash
fp bs comments delete <id> <commentId>
```

Both `<id>` and `<commentId>` accept short prefixes. `fp bs comments` also accepts the alias `fp bs comment`.

<!-- SCREENSHOT: desktop sidebar with an open thread anchored to a block. Anchored-vs-unanchored is the main conceptual lift in this section and a picture is worth a paragraph. -->

When editing a brainstorm, read the comments first. Threads carry review feedback and requested changes that the next update is expected to address.

## Working with the Desktop App

The CLI and the Mac desktop app share a local Y.Doc store, so changes sync in real time. A brainstorm created from the CLI shows up in the app's brainstorm list immediately. Comments added in the sidebar show up in `fp bs show --with-comments` without a refresh.

To install the desktop app, see the [Mac App overview](/docs/mac/overview).

## Output Formats

Read-style commands support `--format json`:

| Command | `--format json` |
|---------|:---:|
| `fp bs create` | ✓ |
| `fp bs list` | ✓ |
| `fp bs versions` | ✓ |
| `fp bs comments` (default list) | ✓ |
| `fp bs show` | — |
| `fp bs update` | — |
| `fp bs open` | — |
| `fp bs delete` | — |
| `fp bs comments add` / `resolve` / `delete` | — |

```bash
fp bs list --format json
```

```json
[
  {
    "id": "dardepfromppbeyeeoryqtizcamqezio",
    "title": "Auth refactor plan",
    "descriptionExcerpt": "Plan for migrating auth to OAuth 2.1...",
    "status": "draft",
    "deletedAt": null,
    "createdAt": "2026-04-15T10:12:00.000Z",
    "updatedAt": "2026-04-17T14:33:21.000Z"
  }
]
```