Workflows

Four flows cover almost everything Mercatorgraph does day to day.

1. Onboard a new project

A maintainer registers a repository once. The worker builds its graph and promotes it.

# register (see Getting Started for full steps)
curl -X POST localhost:19883/projects/demo/rebuild
curl localhost:19883/projects/demo/status     # wait for "succeeded"

2. Agent query (the everyday path)

An agent asks scoped questions instead of grepping the repo. Every answer is size-capped.

Typical tool sequence an agent runs while exploring:

1. list_projects — what can I see?
2. search — find the entry points.
3. get_node — inspect a function + its edges + any annotations.
4. trace_path — how does A reach B?
5. blast_radius — what breaks if I change this?

3. Rebuild on push (keep the graph fresh)

The primary trigger is a git webhook. Bursts are coalesced; cron is an alternative.

• Webhook: set webhook_secret_ref on the project; point the repo's webhook at /webhook/<slug>.
• Cron: set rebuild_interval (seconds) to rebuild on a schedule.
• Manual: POST /projects/<slug>/rebuild any time.

4. Contribute knowledge (survives rebuilds)

Humans and agents attach knowledge that Graphify can't infer — the "why". It lives in Postgres and is overlaid at query time, never written into the graph.

# an agent tags a node with durable context
add_annotation(project="demo", node_id="svc_db_conn", content="singleton: connection pooled")

# later, any agent sees it in get_node(...).annotations  (tag: CONTRIBUTED)

Because contributed knowledge is separate from the derived graph, a rebuild refreshes the code structure without losing the human/agent context layered on top.