# roadflow

> Free, fast, browser-based roadmap editor at https://roadflow.io. Create product roadmaps with a visual canvas or plain-text markup. Also: Artifacts graphs and Model parameter register. No signup. Local save by default for Plans; Model facts live in MySQL. Remote MCP for AI agents at https://roadflow.io/mcp.

## Start here

- [App](https://roadflow.io/): Open the editor in your browser.
- [MCP for agents](https://roadflow.io/mcp.html): **Connect Cursor / MCP clients** — tools, config, workspace modes. Protocol URL: `https://roadflow.io/mcp`.
- [Markup notation](https://roadflow.io/notation.md): **Primary reference** for generating or parsing roadmaps as text. Includes line types, field rules, connections, date grid, artifacts (`@ label|url`), and a machine-readable schema.
- [Privacy](https://roadflow.io/privacy.html): Data handling (localStorage, shared maps, Slack Connect, MCP).
- [Terms](https://roadflow.io/terms.html): Acceptable use.

## What roadflow is

- **Roads** — initiatives with a name, goal, optional color, and artifact links (`@` lines after the road header).
- **Lanes** — parallel tracks within a road.
- **Steps** — work items with title, notes, status (`pending` | `in_progress` | `done`), optional date, optional milestone type, optional artifact links (`@` lines after the step).
- **Connections** — cross-road links from a step to another road's goal or step (`-> Road / Step : note` in markup).
- **Date grid** — optional calendar mode in Preferences; steps use `DD/MM/YYYY` in markup when enabled.

Canvas and markup stay in sync; edit either side.

## For agents generating markup

1. Prefer [MCP](https://roadflow.io/mcp.html) (`roadflow_apply_json` / `roadflow_apply_markup`) when available; otherwise paste markup into the app.
2. Read [notation.md](https://roadflow.io/notation.md) — especially the **Machine-readable schema** section.
3. Use `|` as field separator on step lines; avoid `|` inside titles and notes.
4. Artifact links: `@ label|url` after a road (goal) or after a step.
5. Placeholders like `{road name}` and `{step title}` in docs are **not** literal — omit braces in real markup.

## Share links (optional)

- **Share → To edit**: URL with edit id; changes save when you use a share link.
- **Share → To view**: Separate view-only URL; read-only UI (no markup panel, no editing).
- Shared map URLs (`?id=…`) are user content; the marketing homepage is https://roadflow.io/

## Slack Connect (optional)

- **Connect → Slack List** in the app: OAuth to Slack, pick a List, map columns (title, notes, status, date, road/lane grouping, optional link→artifacts).
- Creates a **view-only** roadmap that re-syncs from the List when viewed.
- Slack tokens are stored encrypted on the server; they do not appear in map JSON or the browser.

## Export formats

Text (markup), JSON (app state), CSV (steps table), PNG (canvas screenshot) — from the Export menu in the app. MCP exports JSON, markup, and CSV. For a visual map via MCP, call `roadflow_create_shared` and open the view URL.

## MCP (remote agents)

Human docs: [mcp.html](https://roadflow.io/mcp.html).

Streamable HTTP MCP at **https://roadflow.io/mcp** (no auth for now — treat as a public capability).

One session can hold separate **Plans**, **Artifacts**, and **Model** workspaces. Plans tools are `roadflow_*` (URLs `/?id=…`). Artifacts tools are `artifacts_*` (URLs `/artifacts/?id=…`). Model tools are `model_*` (URLs `/model/?id=…`). Plans/Artifacts apply on a shared edit workspace auto-saves. Model writes one record or a capped bulk (`model_upsert_parameters` / `model_upsert_observations`, max 400) — never a whole-document upsert. `model_new` allocates `viewId` (`mv-…`) and returns `viewUrl`. Closed formula set (IF, AND/OR/NOT, CEILING/FLOOR, MAX/MIN, ^/POW, PCT, CalendarHours(year|range), YearsFromBase, YEARFRACTION, BAND/LOOKUP, SUM/NPV/IRR/PAYBACK/DSCR, unicode ×÷−, unique [canonicalId]). CALC needs `=` or SBC; formula wins if both are set. Narrative stays IN + comment. `model_evaluate` is read-only compute (default period = calendar start; cap 2000). Not computed here: optimizer, reverse EQ, XNPV/XIRR, ECML. Do not persist CALC outputs or FORMULA edges.

Plans tools: `roadflow_new`, `roadflow_status`, `roadflow_get`, `roadflow_apply_json`, `roadflow_apply_markup`, `roadflow_open_shared`, `roadflow_create_shared`, `roadflow_export_json`, `roadflow_export_markup`, `roadflow_export_csv`, `roadflow_list_versions`, `roadflow_get_version`, `roadflow_discard`.

Artifacts tools: `artifacts_new`, `artifacts_status`, `artifacts_get`, `artifacts_apply_json`, `artifacts_open_shared`, `artifacts_create_shared`, `artifacts_export_json`, `artifacts_list_versions`, `artifacts_get_version`, `artifacts_discard`.
- Artifact kinds: `document`, `registry`, `note`, `package`, plus canvas `labels`.
- `registry` nodes hold table structure: `hasHeader` (boolean), `columns` (`[{ id, name }]`), `rows` (`[{ id, cells: string[] }]`), and optional canvas `width` and `height`.
- Connections can anchor to a specific table row using `targetRowId`.

Model tools: `model_new`, `model_open`, `model_status`, `model_get`, `model_discard`, `model_patch_project`, `model_list_parameters`, `model_get_parameter`, `model_upsert_parameter`, `model_upsert_parameters`, `model_delete_parameter`, `model_list_observations`, `model_upsert_observation`, `model_upsert_observations`, `model_delete_observation`, `model_list_edges`, `model_upsert_edge`, `model_delete_edge`, `model_evaluate`, `model_list_dictionaries`. Full schema, dictionaries, formula rules, and demo entities: [model/AGENTS.md](https://roadflow.io/model/AGENTS.md). Human Instructions (EN/RU) in the Model **?** menu cover the same contract.

Cursor remote MCP:

```json
{
  "mcpServers": {
    "roadflow": {
      "url": "https://roadflow.io/mcp"
    }
  }
}
```

See [mcp.html](https://roadflow.io/mcp.html) for tools, workspace modes, and usage.

## Contact

admin@roadflow.io