Brainstorms

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 when the work is trackable and needs a status.

Creating a Brainstorm

Write a markdown file, then create the brainstorm:

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:

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:

fp bs create path/to/plan.md --format 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

:::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.
:::

Cards

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

Inline labels

: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.

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

See the mermaid docs for syntax.

Filetrees

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

```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 below.

## 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:

fp bs list

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

Include soft-deleted brainstorms:

fp bs list --deleted

Dump the raw markdown:

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:

fp bs show <id> --with-comments

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

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):

fp bs show <id> --version 2

Open the brainstorm in the Mac desktop app:

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

Versions and Updates

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

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

Updated brainstorm: Auth refactor plan (v2)

List version history:

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):

fp bs comments <id>

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

Add a comment:

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:

fp bs comments resolve <id> <commentId>

Soft-delete a comment:

fp bs comments delete <id> <commentId>

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

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.

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	—

fp bs list --format 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"
  }
]