Skip to content

Doc type

Documentation

A system on one page, with a drawing you can open.

A docs page explains a system that exists. The system is a blueprint canvas you zoom into, flows play across it step by step, and procedures are checklists whose ticks the local server keeps.

InstallView on GitHub
"type": "docs"

Zoom three levels into the order path and back. A node with children is a system. Double-click it, or zoom in, to see its parts on their own sheet; Esc and the crumbs go back up.

What it’s for

One page per system, in five shapes.

The agent picks the kind when it starts the page; each has its own order of sections.

  • Architecture

    The system on a canvas, its terms, its parts and the decisions behind them.

  • Walkthrough

    One flow per scenario on the canvas, then each step explained.

  • Runbook

    Procedures as checklists, with verification and a troubleshooting table.

  • Setup

    Prerequisites, the stack you are building and the steps to get it running.

  • Change

    Proposed and removed parts on the canvas, what changes and the rollout.

Features

What you can do on the page.

Pan and zoom the blueprint canvas

The system is a drawing you drag and zoom. Edges run at right angles, routed around the nodes, and their labels don’t overlap.

Watch a data flow run across the systems

A flow plays one step per edge: a token rides the edge with its payload, and the caption reads the step and counts Step n of m.

Pick a flow and step through it

Each level has its own flows. Pick one in the canvas header, pause it, and step with ‹ › one hop at a time.

Open a node’s notes and source anchors

Click a node to read its notes and where it lives in the repo, as path:line references.

Read edge kinds and node states

Edges show what moves: data, control calls, async events. A node marked unverified, local or proposed looks different from the live parts.

Open the drawing full screen

Full screen gives the canvas the whole window, Fit frames the drawing, and Esc returns to the page.

Tick a runbook step

Each procedure is a checklist. A step opens to its command and its check; tick it and the progress bar moves. The local server keeps the ticks.

Jump from a checklist step to its node

A step or a table cell can name a node. Its ref key flies the canvas there.

Copy checklist progress as Markdown

Copy progress exports the ticks as a Markdown checklist, for a PR or an issue.

Terms, cards, callouts and tables

Around the drawing, the page is built from blocks: terms, cards, callouts and tables, each one a thing you can comment on.

Works on every doc

Comments, revisions and approval, the same on every type.

See every shared feature

  • Pin a comment on any element

    Point at a node, a row or a button and write a note. The pin stays on the element.

  • Comment on a passage

    Select a sentence and say what should change.

  • Compare two revisions word by word

    New, changed and removed parts are marked in place, with words struck and added.

How the agent uses it

The agent writes JSON. The server draws the page.

The agent starts from a skeleton and fills it in. A node with children is a system you can open; each level has its own flows.

python3 <skill>/scripts/build.py new docs docs/orders/order-path.bluedoc.json --title "Order path" --kind Architecture
python3 <skill>/scripts/build.py docs/orders/order-path.bluedoc.json
python3 <skill>/scripts/serve.py open docs/orders/order-path.bluedoc.json
acme-orders.bluedoc.json · a canvas node
{  "id": "api",  "label": "orders-api",  "sub": "Node · Fastify",  "md": "Validates, prices and charges the order.",  "refs": ["`services/orders-api/src/routes/createOrder.ts:18-96`"],  "children": {    "nodes": [      { "id": "auth", "label": "auth hook", "sub": "JWT check", "col": 0, "row": 0 },      { "id": "validate", "label": "validate", "sub": "zod schema", "col": 1, "row": 0 }    ],    "edges": [      { "from": "@left", "to": "auth", "label": "POST /orders" },      { "from": "auth", "to": "validate" }    ],    "flows": [{      "id": "create",      "label": "Create one order",      "steps": [        { "edge": "@left->auth", "label": "The auth hook checks the JWT.", "payload": "JWT" }      ]    }]  }}

build.py validates the doc, lints it and records the revision; serve.py prints the page’s URL.

Install

Pick your agent.

Each one installs the same skill from the GitHub repository.

claude plugin marketplace add andreiverdes/bluedoc
claude plugin install bluedoc@bluedoc

Inside a session the same commands are /plugin marketplace add andreiverdes/bluedoc and /plugin install bluedoc@bluedoc. Start a new session to load the skill.

Needs: Python 3.9 or later on PATH · git, for code reviews · gh, only to import GitHub review threads.

View on GitHub

Other doc types

Six more kinds of page.