Skip to content
ProvenMap
Getting Started
On this page

Getting Started — Plugin or Chat

On the assisted path, you answer questions about your systems and an interview draws the landscape. Run the interview with the workspace plugin in Claude Code or Codex, or from Chat in the portal. Then bind each repo, sync it, and ask the board a question. To draw the landscape yourself, use Getting Started — Hands-On.

An interview creates the landscape; the code plugin fills the app boards, and its /monitor and /ground commands turn live signals and documents into insights and work items.

What you will have at the end

You will have a system landscape on your root board and an app board for every repo you own. One of those app boards is mapped and synced from its code, and has answered a first question in chat.

Use it solo or as a team:

StepSoloArchitect + developers
Set up the workspace (/setup or chat)YouThe architect
Fill each app board (/login → /analyze → /sync)You, once per repoEach repo's developer
Author and deliver work itemsYouThe architect authors; developers deliver

What you need

  • A workspace and local clones of the repos you are mapping.
  • For the plugin path: Claude Code or Codex. The workspace plugin runs on both but not on Cursor. The code plugin runs on all three.
  • For the chat path: nothing extra. Chat starts on your organization's trial credits, which your first message offers to turn on. Connect a model provider (e.g. OpenRouter) under Settings → Connectors when they run out. The plugins need none.

The guide in the app

The Setup guide playbook in the sidebar walks you through this page one step at a time. When it asks how you want to fill the empty workspace, choose From my terminal or In chat; Getting Started — Hands-On covers the rest of how it works.

The plugins you use

PluginInstall idWhat it does here
The workspace pluginpmap-workspaceRuns the interview and creates the landscape. It binds no repo. It reaches your workspace over an MCP token.
The code pluginpmap-codeBinds one repo to one board, maps that codebase locally, and pushes the graph. The same plugin grounds a board in a repo's documents (/ground) and correlates monitoring signals with the board (/monitor).
Tip

Unsure what to run next in any of the plugins? /start shows the command groups, ranks the next steps for your state, and offers to run the first.

Set up your workspace

The interview asks what your systems are, what each one does, and which systems talk to which. Answer at the level you know: an area you're unsure of does not block the rest. Choose where to run it.

Open Chat from the board bar. While the workspace is still empty, the new-thread panel offers Set up this workspace. Choose it, and ProvenMap interviews you about the systems you run. It then draws the landscape on the root board and creates an empty board for each app that has its own repository. Every board it creates or draws appears as a card in the conversation, and each change applies only after you approve it.

Once the workspace has content, Set up this workspace no longer appears. From then on, you add systems by asking in chat, or with /new-app in the workspace plugin.

After approval, your root board holds the system landscape, and every repo-backed system has an app board of its own.

Every system is a node. Repo-backed systems open into their own app boards, which stay empty until their code is synced.
  1. 1

    Drill-down indicator

    Opens the system into its own board layer. To add one, right-click any node and choose Create Subsystem Layer.

  2. 2

    Typed connections

    Each edge carries a description of the relationship between the systems it connects.

Create your first app

The interview already created an app board for every repo-backed system, and the root hub lists them. To make another system an app, right-click its node and choose Make this an app, keeping to one app, one repo; Getting Started — Hands-On covers the details.

Connect the repo and sync it

The app boards are empty on purpose: content comes from code, not the interview. In each repo, install the code plugin from the same marketplace (pmap-code@provenmap; Cursor works too) and run:

BASH
cd <the-repo>
/login       # browser: pick the app board created for this repo
/analyze     # map the repo into a structured graph, locally
/sync        # push it onto the board

/analyze runs inside your own coding session, writes to .provenmap/ and never edits your source. /sync pushes the result, and the system's node on the landscape then opens into the internals mapped from its code.

The app board's hub shows the same path under App agent access (changed 12 October 2026), with no secret to copy. If you can't sign in through a browser, /configure sets up credentials by hand. Connecting Sources has the full setup sequence.

The first sync fills the empty app board from the repo's code.
  1. 1

    Breadcrumb

    Shows the app and the layer you are in. Select it to go back up to the landscape.

  2. 2

    Components as nodes

    A first /sync turns each part of the stack into a node and connects the nodes by dependency edges.

Repeat for each repo.

Ask the board a question

Open Chat on the synced app board and ask about what arrived. Two questions to try:

  • What depends on the database?
  • What does this app's API expose?

ProvenMap answers from the board and its sources, and it can reply with a drawn board instead of text.

That completes the setup guide. Chat covers what else you can do in chat, and Org-Level Intelligence covers what you can do once several systems are mapped.

Keep it current

The board shows the code as of its last /sync. In each repo:

  • Run /changes once. It reads about three months of git history into the Changes screen. The diary there tells each week's work: what it did, who did it with which agent, and which change rules it hit.
  • Schedule /analyze --scheduled as a scheduled run. Each run refreshes the boards whose code changed, syncs them, and records the new weeks in the diary, without anyone running a command.

After setup

  • /discover ranks the insights and context boards worth showing first and pushes the ones you pick.
  • /monitor attaches errors, incidents and cloud costs to the elements they affect, and /ground cites ADRs and design docs against their nodes, by hand or on a schedule.
  • Developers pull handed-off work items with /work-items, and the next /sync verifies structural changes against code.
Tip

If the architect sketched a target architecture before the repo connected, the first push does not erase it. Analysis compares the code to the sketch, and every disagreement appears as a work item.

Founding a product line instead

In the workspace plugin, answer founding something new and the command stays at the product level: the product line, its intended systems, and their relationships. It generates no boards, because there is nothing to map or bind yet.

When one of those planned systems becomes real, /new-app adds it to the existing landscape and continues from there.

You are done — checklist

  • Set up the workspace with /setup or Set up this workspace in chat: landscape drawn, app boards created
  • Every repo-backed system is an app board
  • In one repo: code plugin /login → /analyze → /sync, and the push arrived
  • Asked the board a question in chat
  • (Optional) Ran /changes and scheduled /analyze --scheduled in each repo
  • (Optional) Repeated the sync per repo, connected live source signals, authored a first work item

Where to go next

The Workspace Plugin

The full lifecycle behind the interview: daily work, authoring, and reviewing.

Chat

Questions, drawn boards, reviews, and drafted work items from one conversation.

The Code Plugin

Every command, flag, and config field for filling a board.

Changes

Each repo's weeks as a diary: what changed, who did it, and the rules it hit.