Skip to content
ProvenMap
Getting Started
On this page

Getting Started — Hands-On

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

What you will have at the end

You will have 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 need a model provider only after those credits run out, or to build a board from a governing document source.

The guide in the app

The Setup guide is a playbook in the sidebar's Playbooks group that tracks your real setup state. When it asks how you want to fill the empty workspace, choose On the canvas for this path; a workspace that already has systems skips the question. The guide then shows one step at a time, and a step completes only when its result exists, such as a board appearing or a push arriving. It retires when a work item you authored from it comes back confirmed by code, and ⌘K reopens it read-only.

Draw the landscape

Start with one node per system and an edge wherever systems connect. Give each node a type from the archetype library. The library 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. 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.

Warning

When you first open a board, you choose its layout, and you cannot change it afterward. Pick it deliberately.

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

Make one system an app

Pick the system backed by a code repo. Right-click its node and choose Make this an app, or choose it from the board menu once you are inside the system's layer. Choose the app type and sync branch. A node without a layer gets one in the same step. You can also drag an app from the canvas Apps palette to create the child app board, source, and binding together.

One rule applies: one app, one repo. A board gets exactly one governing Code Plugin binding, and app boards cannot nest. Sources Overview lists the cardinality rules. After you confirm, the board becomes an app board.

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

Making an app gives you no secret to paste: /login writes the credentials into the repo. Each /login issues that machine its own credential, and machines already connected keep working. The app board's hub shows the install link, the /login command and the board's slug under App agent access (changed 12 October 2026). Connecting Sources lists the full setup steps.

/analyze 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.

The code plugin draws a node for each component and an edge wherever two components connect.
  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 your other systems, one binding per repo.

Ground a document repo (optional)

If your PRDs, RFCs, and ADRs live in a repo, run /ground in the code plugin. It links the documents to the board's nodes as evidence links and reports drift; it does not build the board.

You can also bind a URL or a pasted note as reference context, as Connecting Sources describes.

Turn on chat

In Chat, you ask questions about your landscape, and the answer can be a board instead of text. The first message needs no setup; connect a model provider (e.g. OpenRouter) under Settings → Connectors when the trial credits run out.

See the first insights

An analysis starts from chat or from /insights in the repo, which runs your workspace's insight skills. Each insight anchors to a board element and appears in the Insights Bar. Insight Skills covers authoring those skills.

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

Keep it current

The board shows the code as of its last /sync. In each bound 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.

Publish it

When the board is ready to share, publish it. You choose the address, the access, and which insights, aspects, and skills to include. Stakeholders get a stable URL and need no account to open it. 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) Ran /changes and scheduled /analyze --scheduled in each repo
  • (Optional) Grounded a document repo, ran /insights, published, or turned on chat

What's next

Org-Level Intelligence shows how the whole org can query the landscape.

Related docs: