# ProductBrain (LLM guide: https://productbrain.com/docs/llm-guide.md)

> A logic-driven product planning tool for technical founders. One dataset, two views: a hierarchical tree for strategy (Goal → Need → Bet → Job; a bet is stored as type `approach`) and an execution matrix for releases. Built to be driven by an agent — the whole API surface is credit-free and you bring your own model.

If you are an LLM working on a ProductBrain plan, read the guide before you write anything. It is the canonical contract: the data model, the hierarchy rules, field validation, every endpoint, and the placement workflow. Guessing the shape wastes turns; the guide is one fetch.

## Start here

Fetch tools often return a cached copy. Add a cache buster such as `?cb=<timestamp>` to any URL below, and check the guide's version date against the [changelog](https://docs.productbrain.com/changelog).

- [LLM guide](https://productbrain.com/docs/llm-guide.md): The full contract. Data model, hierarchy rules, field-by-field validation, all endpoints, error shapes, and the search-first placement workflow.
- [Concept docs index](https://docs.productbrain.com/llms.txt): The longer framework docs (Goals, Needs, Bets, Jobs, Kano, the two views). Every page is also served as markdown at its URL plus `.md`.

## API

The base URL is `https://productbrain.com/api/v1`. Authenticate with `Authorization: Bearer <your pb_ key>`. Every endpoint can return an `_meta` block carrying in-band coaching — a `_tip` on how to recover, an `advisory` for backpressure, a `focus` to drive the canvas, and a `guide` link back here on a 400/401/403 from any of the six core endpoints below. Read it; it is there so you rarely need to come back to the guide mid-run.

- [POST /api/v1/mutate](https://productbrain.com/docs/llm-guide.md#add-node): Write the plan. Create, update, delete nodes and phases; batch many changes in one call. Pass an `Idempotency-Key` so a retry never double-applies.
- [GET /api/v1/search](https://productbrain.com/docs/llm-guide.md#search-nodes): Semantic search with ancestor paths. Search first, always — never scan all nodes to find placement.
- [GET /api/v1/nodes](https://productbrain.com/docs/llm-guide.md#read-nodes): Bulk read. For "every job in phase X", not for lookup.
- [GET /api/v1/tree](https://productbrain.com/docs/llm-guide.md#navigate-the-tree): Traverse structure — ancestors, subtree, siblings, context.
- [GET /api/v1/iterations](https://productbrain.com/docs/llm-guide.md#phases): Read phases and resolve the current one.
- [POST /api/v1/workflow](https://productbrain.com/docs/llm-guide.md#hosted-workflow-api-drive-the-planner-with-your-own-llm): Run the planning methodology with your own LLM. Consumes no ProductBrain AI credits. Prefer it over hand-rolling the same change with `mutate`.
- [View control](https://productbrain.com/docs/llm-guide.md#view-control): `POST /api/v1/view-command` and `GET /api/v1/view-state` — drive and read the live canvas.

## MCP

- [MCP server](https://productbrain.com/docs/llm-guide.md#mcp-server): `npx -y @productbrain-com/mcp`. A thin shim over the same v1 API — every agent-facing endpoint is one tool, and responses carry the same `_meta` coaching.

## Optional

- [Full guide as one file](https://productbrain.com/llms-full.txt): The entire LLM guide inlined, for clients that would rather not follow links.
- [Product vision](https://productbrain.com): What ProductBrain is for and who it is for.