ProvenMap
Getting Started

Getting Started — Hands-On

Draw your system landscape, pick one system, bind its repo, and let the code plugin map what is inside. Prefer an interview-driven setup? Use the Plugin or Chat path.

What you will have at the end

A board that reflects a real system, stays in sync with its repo, supports insights, and can be published for stakeholders. Repeat the process until each system opens into its mapped app board or is clearly marked as not mapped.

Note

The plugin's core commands (/analyze, /sync, and /insights) work with no model provider connected. They reason inside your own AI coding session, not on our servers. Chat starts on the organization's trial credits. You only need a model provider once they run out, and for building a board from a governing document source.

The guide in the app

The Setup guide in the top bar tracks real setup state. It updates when you create an app, when a push arrives, or when you ask chat a question, not when you click "next".

It opens with three ways to start: the architect plugin, chat, or drawing it yourself. This page is the drawing path, so choose Draw it yourself. The guide then shows one step at a time: create your first app, connect the repo and sync it, ask the board a question.

Each step names the control to use, with a chip that looks like it; click the chip or Show me and the real control pulses. The panel stays open while you work, and you can drag it by its header out of the way. After setup, the guide lists optional tasks you can finish in any order. It retires when an intent in the workspace comes back confirmed by code, and you can reopen it read-only from ⌘K.

Draw the landscape

Start with one node per system and an edge wherever systems connect. Type each node from the archetype library, which includes containment rules and can be extended.

For example: add typed nodes for a marketing portal, the platform behind it, and the infrastructure that provisions both.

The top of the map: your landscape, built from the archetype library.
  1. 1

    Drill-down indicator

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

  2. 2

    Typed connections

    Edges describe the relationship instead of showing only a line between systems.

Warning

You choose a board's layout when you first open it and cannot change it afterward. Pick it deliberately.

Any system can open into its own board layer. Right-click its node, choose Create Subsystem Layer, and use the drill-down indicator to navigate in.

Right-click a system node, create its layer, and navigate in.

Make one system an app

Pick the system backed by a code repo. Open its board and use Make this an app. Choose the app type and sync branch. You can also drag an app from the canvas Apps palette to create the child app board, source, and binding together.

Both paths preview the hub, tabs, and cards before creation. One rule applies: one app, one repo. A board gets exactly one governing Code Plugin binding, and app boards cannot nest. The cardinality rules are in Sources Overview. After confirmation, the board becomes an app board and opens on its hub.

Connect the plugin

Making an app does not give you a secret to paste. Prefer the code plugin's /login, which runs browser sign-in and writes credentials into the repo.

For manual setup, use Agent access on the hub. It shows the binding token, board slug, branch, and PMAP_* snippets for cloud sessions or CI. The live API secret appears only when issued. Need another? Generate new secret issues a fresh credential, and existing credentials keep working until you revoke them. Connecting Sources has the full setup steps.

Map the repo

Connect a board to the Code Plugin

This step needs a coding agent: Claude Code, Codex, or Cursor. Install the code plugin, then run:

BASH
/login       # browser sign-in; pick this board, and the config is written for you
/analyze     # map the repo into a structured graph, locally
/sync        # push that graph onto the board

/analyze scans the repo for services, APIs, databases, and queues, then builds the graph on disk. It pushes nothing and never edits your source files. /sync sends the diff to the board.

After the first pass, /analyze --drill <board>/<node> maps one node into its own child board. /analyze --all followed by /sync --all builds the whole layered hierarchy at once. Add --auto to run unattended, a few boards per round, until the planned tree is built.

Go back to the landscape. The bound system now opens into the graph the plugin mapped.

Your codebase, mapped — a node per component, edges where they connect.
  1. 1

    Tab strip

    Root Board and the newly synced app board — jump between layers from here.

  2. 2

    Components as nodes

    Each part of the stack becomes a node, connected by dependency edges — this is what a first /sync produces.

Repeat for your other systems. Each repo keeps its own .provenmap/credentials.json and its own binding, so when one repo changes only its board updates.

Ground a document repo (optional)

Code gives you structure, not the why. If PRDs, RFCs, and ADRs live in a repo, use the connect plugin. Its /sync checks your board against documents, proposes evidence links, and reports drift. It does not build the board. You can also bind a URL or a pasted note as reference context; see Connecting Sources.

Turn on chat

Chat answers questions about your landscape and can answer with a board instead of text. It starts on the organization's trial credits, so the first message needs no setup. Connect a model provider (e.g. OpenRouter) under Settings → Connectors when they run out. The plugin loop above never needs one.

Org-Level Intelligence covers what that enables after you map several systems.

See the first insights

An analysis starts from chat or from /insights in the repo. /insights runs your workspace's insight skills inside your coding session, so it needs no model provider. Each insight anchors to a board element and appears in the Insights Bar. Author skills in Insight Skills.

From an insight, you can create an intent. Developers implement it and record verification evidence. A later /sync confirms structural changes against code; prose-only intents complete on the developer's evidence.

Publish it

When the board is worth showing, publish it. Choose the address, access, and included insights, aspects, and skills. Stakeholders get a stable URL with no account. Publishing Boards explains the wizard.

You are done — checklist

  • Drew the system landscape from the archetype library
  • Made one system an app and bound its repo
  • Connected with /login or configured a manually issued credential
  • Mapped and synced the app board (/login → /analyze → /sync)
  • Repeated for your other systems — one binding per repo
  • (Optional) Grounded a document repo, ran /insights, published, or turned on chat

What's next

Next, let the whole org query the landscape in Org-Level Intelligence.

Related docs: