PILOTAGE
GitHub Get started →

2. Learn the language

The manifest says that pilotage_get_guide carries the learn operation.

First retrieve the guide index:

↑Request
{"tool":"pilotage_get_guide","arguments":{"language":"buildingflow/1"}}
↓Response
{
  "guides": [
    {
      "id": "quickstart",
      "title": "Your first flow",
      "level": "core",
      "topics": [
        "shape",
        "steps",
        "expressions",
        "scope-rules",
        "the-loop"
      ],
      "version": "1",
      "language": "buildingflow/1",
      "format": "text/markdown",
      "size_bytes": 2653
    },
    {
      "id": "reference",
      "title": "The closed sets: codes, statuses, kinds, bounds",
      "level": "reference",
      "topics": [
        "closed-sets",
        "diagnostic-codes",
        "outcomes",
        "risk",
        "scope-rules",
        "input-binding",
        "trace-levels",
        "bounds"
      ],
      "version": "1",
      "language": "buildingflow/1",
      "format": "text/markdown",
      "size_bytes": 4417
    },
    {
      "id": "examples",
      "title": "Worked examples",
      "level": "examples",
      "topics": [
        "read-then-act",
        "input",
        "automation"
      ],
      "version": "1",
      "language": "buildingflow/1",
      "format": "text/markdown",
      "size_bytes": 1836
    }
  ]
}

Fetch the core guide:

curl -s -X POST https://harborview.pilotagespec.org/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: $HARBORVIEW_SESSION" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "pilotage_get_guide",
      "arguments": {
        "language": "buildingflow/1",
        "id": "quickstart"
      }
    }
  }'

The real core guide teaches that a flow is a JSON object with steps. It defines exactly four step kinds:

call · branch · for_each · set

It also gives the smallest useful flow:

{
  "name": "lobby on",
  "steps": [
    {
      "id": "on",
      "do": "call",
      "device": "light.lobby",
      "action": "turn_on"
    }
  ]
}

The important scope rule is equally short:

$.steps.<stepId>.output

A result is addressed in the parent scope, even when the step sits inside a branch arm or loop body.

What this taught

Guides provide stable grammar in-band. The index is cheap; bodies are fetched only when needed. The core guide gets a client new to the language to a meaningful first draft, while the reference guide owns the complete closed vocabularies.

See Guides and Part II §5.2.