After you connect
What the first sync is doing, and what to make of the map when it arrives. Most first surprises have a plain answer, and they are all here.
1. What happens now
Four stages, and you can watch which one it is on.
Reading opens every file once and is the part that takes the time. Placing works out where everything goes from the structure, and on a repeat sync it is where things stay where they were. Saving writes the map down so it opens instantly from then on.
The naming pass is not a fourth step you wait for. It starts after the map is already marked ready and runs without holding anything up, so things can be sitting there under their raw filenames for a while and that is the system working, not stalling.
How long it takes depends on how much code there is, and we would rather not print a number we would often be wrong about. A small service is quick. A large monorepo is not, the first time. You can close the tab; it does not stop.
2. The first thing to do
Zoom all the way out and read what is left, before clicking anything.
At the furthest zoom only the things that matter at that distance survive, so what remains is a short description of what your product actually is. It is worth thirty seconds because it is the one view you cannot get any other way, and it is frequently not the list people expect.
Then pick the part you know best and go into it. Judging a map on the area you understand is the fastest way to work out how far to trust the rest of it. How to read the map explains what the sizes, shapes and colours are telling you.
3. The count looks wrong
Almost always because installed dependencies were not counted.
A map of your product should show what your team wrote, not the tens of thousands of files someone else wrote that happen to live in your repository. Installed packages, build output, caches and virtual environments are all skipped, wherever they sit in the tree.
That usually accounts for the entire difference between the number you expected and the number you see. The full list of what is skipped is on will it work on my repo, along with the languages that are read at all, which is the other half of the answer.
4. Something is missing
Three likely reasons, in the order they are usually true.
It is written in a language cleap does not read. A repository can be mostly TypeScript with a Rust service in one folder, and that folder will be absent rather than empty. It is not hidden deliberately.
It is too far in to be shown yet. Not everything appears at every zoom level. Search for it by name rather than hunting for it visually, which is faster and settles the question immediately.
The sync has not finished. Names in particular arrive after the map does, so a thing can be present and still be wearing its raw filename for a while.
5. A connection you do not recognise
Check whether it is marked as inferred, because that means it is a guess.
Most connections are read straight out of the code: this file imports that one, this function calls that one. Those are facts and are drawn as facts.
A smaller number are suggested by a model rather than found in the source, and they are drawn differently and labelled as inferred. If one of those looks wrong, it may well be wrong. Treating a guess as identical to a fact is how a map starts lying to you, which is why they never look the same here.
A connection that is drawn as a fact and is genuinely wrong is a bug in the parser, and worth telling us about, because that one should not happen.
6. Nothing was mapped
The map will tell you which languages it found instead.
An empty result is not a failure that hides itself. When a sync finds no files it can read, it finishes and names the languages that are actually in the repository, with counts, so you can see immediately whether this is a support gap or a wrong repository.
If the language is one we do read and the map is still empty, that is worth reporting. Send the repository name to hello@cleap.dev and we will look at it directly.
7. Keeping it current
Nothing to do. A push updates it, and the map says when it last looked.
There is no maintenance step and no document to update. Later syncs only read what changed, so they are much faster than the first.
Where things sit stays put between syncs, which is what makes it worth learning your way around. An ordinary day of commits moves nothing at all. The rules behind that, including where they stop holding, are in the Stable Map Spec.
Areas that have not been re-read recently say so on the map rather than looking as confident as everything else, because a map that quietly goes stale is more dangerous than one that admits it.
8. Undoing it
Disconnect, and everything derived from that repository is deleted.
No export to request and nothing to reclaim: the map was derived from your code, so there is nothing here you need handed back. You can also revoke access on GitHub directly, which stops all reading immediately without asking us first.
What cleap keeps sets out exactly what existed while it was connected and what goes when it is not.