Team Workflow

Mercatorgraph replaces N private, out-of-sync local graphs with one shared graph per project. Here is how a team actually uses it.

Roles

Onboarding a repository (once)

After this, every push keeps the graph current automatically — nobody rebuilds locally.

Access model

• One token per developer or per agent, scoped to the projects they may read.
• Scope is an array of project slugs, or ['*'] for everything.
• Tokens can expire and be revoked; every query is in the audit_log.

# scope a contractor to one project, for a limited time
docker compose exec -T postgres psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c \
  "INSERT INTO tokens (token_hash, principal, scopes, expires_at)
   VALUES ('<sha256>', 'contractor-bob', ARRAY['web'], now() + interval '30 days');"

The knowledge feedback loop

The graph captures structure; people capture intent. Over time the team's collective understanding accumulates as contributed knowledge that new joiners (and new agents) inherit.

Thread status moves open → addressed-by-agent → resolved, so comments are trackable rather than lost in chat.

What a new team member gets on day one

• Point their agent at the MCP server with a scoped token — instant, shared understanding of every registered repo.
• Open the viewer to browse a repo's structure, clusters, and per-node context.
• Read accumulated annotations instead of interrupting teammates.

Anti-goals

• Agents never write to the codebase or the graph directly — contributions are review-gated (comments/annotations now; a comment → agent → PR loop is on the roadmap).
• No agent ever receives the whole graph — only scoped, capped slices.