PILOTAGE
GitHub Get started →

3. Look up the live vocabulary

The guide teaches what a device call means. The catalog tells us which devices exist.

Retrieve the lobby light:

↑Request
{"tool":"pilotage_catalog","arguments":{"language":"buildingflow/1","verb":"get","id":"light.lobby"}}
↓Response
{
  "entry": {
    "id": "light.lobby",
    "kind": "light",
    "name": "Lobby lights",
    "description": "Lighting circuit: Lobby lights. Actions: turn_on(); turn_off(); set_brightness(percent: number).",
    "input_schema": {
      "type": "object",
      "properties": {
        "action": {
          "type": "string",
          "enum": [
            "turn_on",
            "turn_off",
            "set_brightness"
          ]
        },
        "with": {
          "type": "object"
        }
      },
      "required": [
        "action"
      ]
    },
    "output_schema": null,
    "risk": "write",
    "risk_hints": {
      "readOnly": false,
      "destructive": false,
      "openWorld": false
    },
    "tags": [
      "lighting",
      "lobby"
    ],
    "languages": [
      "buildingflow/1"
    ]
  },
  "catalog_version": "cv_590fefad56a7a504"
}

Now retrieve the dock lock:

↑Request
{"tool":"pilotage_catalog","arguments":{"language":"buildingflow/1","verb":"get","id":"lock.dock_door"}}
↓Response
{
  "entry": {
    "id": "lock.dock_door",
    "kind": "lock",
    "name": "Loading-dock door",
    "description": "Badge-controlled lock: Loading-dock door. Actions: lock(); unlock().",
    "input_schema": {
      "type": "object",
      "properties": {
        "action": {
          "type": "string",
          "enum": [
            "lock",
            "unlock"
          ]
        },
        "with": {
          "type": "object"
        }
      },
      "required": [
        "action"
      ]
    },
    "output_schema": null,
    "risk": "destructive",
    "risk_hints": {
      "readOnly": false,
      "destructive": true,
      "openWorld": false
    },
    "tags": [
      "access",
      "dock"
    ],
    "languages": [
      "buildingflow/1"
    ]
  },
  "catalog_version": "cv_590fefad56a7a504"
}

The names and actions now come from the live server. The token identifies the snapshot used for authoring.

What this taught

Guides are grammar. The catalog is vocabulary. catalog_version connects that vocabulary to later validation and execution.

See The catalog and catalog_version and Part II ยง5.4.