--- name: cleap description: Query a cleap map of a codebase over its read-only HTTP API. Use before changing code in a repository the user has connected to cleap, to learn where execution starts, what a file or symbol connects to, and what the code behind a node looks like. --- # cleap cleap keeps a map of a repository: every file and symbol as a node, every import, call and route as an edge, laid out once and kept in sync with the code. This skill reads that map. It never changes anything. ## Before you start You need a key. The user creates one in the cleap app under Settings, in the section named "API keys", and gives it to you as `CLEAP_API_KEY`. It looks like `cleap_sk_...`. If you do not have one, ask; do not guess one. Base URL: `https://api.cleap.dev`. Every request: ``` Authorization: Bearer $CLEAP_API_KEY ``` You also need the repository id. The user can read it from the app. A repository you cannot see answers 404, the same as one that does not exist. ## The walk Take these in order. Stop as soon as you have what you need. 1. `GET /repo/:id` - is the map ready (`status: "ready"`), how big is it (`node_count`, `edge_count`), and its bounds (`world_bbox`). 2. `GET /repo/:id/entry-points` - where execution starts: routes, pages, commands, handlers, each with the `node_id` it lives in. 3. `GET /repo/:id/labels` - every node's `technical_label` (the path or symbol name), `plain_label` (plain English, may be null), `category` and `id`. Search this list yourself for the file or symbol you are about to touch. It is a flat array; there is no server-side search. 4. `GET /node/:id` - one node with `connections` (what it imports and what imports it, one hop), `breadcrumb` and `timeline`. URL-encode the id: it contains `::` and `/`. 5. `GET /node/:id/source` - the file behind a file or symbol node, with `start_line` and `end_line` for a symbol. Fetched from GitHub at call time. Directory and package nodes have no source and answer 400. Two more, rarely needed: - `GET /repo/:id/status` - sync status alone, to poll while a sync runs. - `GET /graph?repo_id=&bbox=minX,minY,maxX,maxY&zoom=` - nodes and edges inside a window of the map. All three parameters are required. For "what does this depend on", the node route is the shorter path. ## Reading the answers - `provenance` is `confirmed` for structure the parser derived from the code and `inferred` for anything a model wrote. Treat inferred text as a hint, never as a fact about the code. - `plain_label` is model-written and may be null. `technical_label` is the truth. - `is_orphaned: true` means nothing in the map reaches this node. Say so if you touch one. - Counts are per sync. `last_synced_at` tells you how old the map is. ## What you cannot do with a key Anything that changes state: trigger a sync, connect a repository, manage keys, edit labels, or ask cleap questions. Those answer 403. Do not retry them; tell the user. ## Limits 120 requests a minute per key on the repository and graph routes. Fetch the labels index once and search it locally rather than calling the node route for every candidate. ## Reporting back When you have used the map, say which nodes you read and what they connect to, in the user's terms (file paths and symbol names), and note anything `inferred` you relied on. The point of the map is that the user can check it.