# Drilldown Sequence

Mermaid sequence diagrams where any arrow can carry click-to-reveal details (request and
response bodies, SQL, headers, notes). Charts live at https://sequence.worksonmymachine.sh/c/<id>; anyone with the link
can view it, only the owner can change it.

## Source format

An ordinary Mermaid `sequenceDiagram`. Under any message, indent one or more `@kind` blocks:

    sequenceDiagram
      title Order checkout
      autonumber
      participant Client
      participant API
      Client->>API: POST /orders
        @request
        { "sku": "ABC-1", "qty": 2 }
        @headers
        Authorization: Bearer <token>
        @response 201
        { "id": 8812, "status": "pending" }
      API->>DB: insert order
        @query
        INSERT INTO orders (sku, qty) VALUES ($1, $2)
        @note
        Runs inside the checkout transaction.

Rules:
- A `@kind` line must be indented MORE than the message it belongs to, and must come right
  after that message (or after another block of the same message).
- The body is every following line indented at least as far as the `@` line. It ends at the
  next `@` at that indent or the first line indented less. Blank lines are fine inside.
  Never put Mermaid keywords like `end` inside a body at a lower indent.
- Text after the kind is a free label shown on the tab, e.g. `@response 201`.
  `lang=<highlight.js language>` overrides highlighting, e.g. `@query lang=plaintext`.
- Default highlighting: request/response/body/json = JSON, query/sql = SQL, headers/http = HTTP,
  yaml, xml, graphql, curl/shell = bash, note and anything else = plain text. Kinds are open.
- Several blocks on one message become tabs. Everything else is passed to Mermaid unchanged.
- Mermaid basics: `A->>B: text` (solid), `A-->>B: text` (dashed reply), `A-)B: text` (async),
  `A-xB: text` (failure). Blocks: loop/alt(else)/opt/par(and)/critical(option)/break/rect/box,
  each closed by `end`. `Note over A,B: text`. `participant X as Long Name`. A literal `;`
  ends a statement in Mermaid; write `#59;` for a semicolon in message text.

## Working with charts

- Prefer `edit_chart` with small exact-text replacements (like a code editor's find/replace)
  over rewriting the whole source. Each `old` must match exactly once, including indentation;
  add surrounding lines to make it unique, or set `replace_all`.
- For a large chart, call `get_chart` with `view: "outline"` first to see the messages and their
  line numbers, then `view: "full"` when you need the exact text to edit.
- Every write returns diagnostics. Fix anything reported as `error` before telling the user the
  chart is done; `hint` entries (e.g. JSON that does not parse) can be intentional.
- Editing overwrites the chart in place; the link stays the same and there is no history.
- Placeholder values (`<token>`, `…`) are fine in bodies; never paste real secrets.

## HTTP API

Authenticate with `Authorization: Bearer sq_…` (minted under My charts in the web app).

    GET    /api/v1/charts                 list your charts
    POST   /api/v1/charts                 {source, title?} → create
    GET    /api/v1/charts/:id?view=outline|full
    PUT    /api/v1/charts/:id             {source, title?} → replace
    PATCH  /api/v1/charts/:id             {edits:[{old, new, replace_all?}]}
    DELETE /api/v1/charts/:id
    POST   /api/v1/validate               {source} → diagnostics and outline, nothing saved
    POST   /mcp                           MCP (Streamable HTTP, stateless)