ProvenMap
Sources

The Code Plugin

The code plugin maps one code repo to one board. It runs inside Claude Code, Codex, or Cursor, analyzes the repo locally, and pushes a graph of services, APIs, databases, and their connections. The same binding also brings board context back to the repo: compiled skills, intents, unbuilt design, and aspect contracts.

This page is the complete reference. For a guided first run, start with Getting Started — Hands-On.

Note

Everything the plugin does runs inside your own AI coding session and needs no model provider connected. Connecting a model is only for the portal's in-app Chat.

The plugin binds the repo as the board's governing Code Plugin source, which turns the board into an app board. For a document repo, use the connect plugin; to edit boards across a workspace, use the architect plugin.

Install and connect

The install id is pmap-code. Add the marketplace and install the plugin.

BASH
/plugin marketplace add provenmap/pmap-claude
/plugin install pmap-code@provenmap
# Restart Claude Code so the commands load.

Then connect the repo and push its first board update:

BASH
/login      # browser sign-in — pick a workspace, then this repo's board
/analyze    # map the codebase, locally
/sync       # push it to the board

/login opens your browser so you can pick a workspace and board, then writes the credentials. To change boards later, run /login switch; the next /sync asks whether to migrate the boards analysed under the old binding or start clean.

Other account commands:

  • /status — what is configured, and what changed since the last analysis
  • /start — shows the command groups, ranks the next steps for this repo's state, and offers to run the first
  • /configure — hand-managed credentials and CI; see Signing In & Credentials
  • /logout and /update — disconnect, or upgrade to the latest build

The lifecycle

The commands fall into five stages:

#StagePurposeCommands
1AccountBind this repo to a board/login · /configure · /status · /logout · /update · /help
2MapTurn the codebase into a living board/analyze-archetypes · /analyze · /adopt · /inspect · /sync · /restyle
3UnderstandRun intelligence on the mapped board/discover · /insights
4BuildUse the platform's build context in the code/skills · /build · /intents
5OperateCompare production signals with the board/monitor

/start reads the repo state, ranks the next steps, and offers to run the first. Every other command ends with an Outcome: what it did, what it left, and the next command with the reason, or a Hand off line when the next step belongs to someone else.

Map

/analyze-archetypes settles node types before analysis. It proposes missing workspace archetypes and is optional by default. Set analysis.archetypeGate to "strict" to require it before /analyze. In strict mode, /analyze stops until the check passes and prompts again when the catalogue or commit changes. Admins review proposals in Archetypes. Flags: --dry-run, --skip-submit, --replace, --force.

/analyze maps the system locally. It pushes nothing and never touches your source files.

BASH
/analyze                                           # incremental pass over what changed
/analyze --clean                                   # full re-analysis from scratch
/analyze --drill <parent-board-slug>/<node-slug>   # map one node into its own child board
/analyze --all                                     # progressive pass across all layers
/analyze --all --auto                              # the same, unattended — no mid-run prompts

/analyze is incremental by default: it reads the git diff since the last analyzed commit. Run /analyze --clean when a result looks stale.

Each run reports analysis coverage against the planned board tree: how many boards are built, stale, incomplete, or still unbuilt. The hub's analysis coverage card shows the same report (App Boards).

Layers build in parallel. Each selected drill-down gets its own subagent, running the model in analysis.subagentModel. --auto loops through the recommended areas unattended; it reports oversized nodes and file waivers instead of resolving them, and branch, credential, and strict-archetype checks still stop the run.

Imports that leave a drill-down board's scope appear as boundary ports, ghost nodes the script rebuilds on every run; see Nodes & Edges.

/sync pushes the diff, not the whole board. It also adds the ✓ Confirmed mark to Completed intents whose structural changes match the code.

BASH
/sync                  # one board (prompts if you have several)
/sync --board <slug>   # a specific board
/sync --all            # the whole layered tree
Warning

By default, synced nodes and edges include a source reference: the relative file path, plus a git-host link when a remote is configured. If paths are sensitive, set "includeSourceReferences": false in .provenmap/config.json. Local analysis under .provenmap/boards/ keeps paths, so you can re-enable them without re-analyzing.

Boards are styled on sync. /analyze saves a styling plan for size, color, and layout. Styling never blocks a push; if a plan fails, the structure still appears and the report points you to /restyle.

BASH
/restyle              # pick from your least-styled boards
/restyle <board-slug> # restyle a specific board

/restyle creates a new plan for your approval, with no /sync needed after. The latest styling decision wins, whether it came from the plugin or an architect's /style-board.

/adopt, in full

Beyond nodes and edges, a board stores aspects: typed details attached to the graph. /adopt extracts one from code and reconciles it onto the board. Portal-authored rows are never overwritten.

BASH
/adopt --aspect <kind> [--mode replace|merge] [--dry-run]

Five kinds ship today:

--aspect <kind>What it extracts
database.schemaTables, columns, keys, indexes
api.surfaceEndpoints, parameters, auth
ui.pagesThe app's front-end route surface — see Pages
event.catalogPublished and consumed events, and their brokers
authz.registryThe policy definitions that decide who can do what

--db and --api are back-compat shorthand for the first two. Extraction reads definitions only: it never runs your app, connects to a live database, or evaluates a policy against real inputs.

Run /analyze and /sync before /adopt; the board structure must exist first.

/inspect

/inspect captures your running app into the board. It opens a browser on a throwaway profile: browse normally, arm Pick to select a component, or Annotate to box a region and attach a note.

BASH
/inspect                          # open the running app and record a session
/inspect --url http://localhost:3000
/inspect --env local              # open a URL saved under inspect.urls
/inspect --capture <url>          # headless: screenshot + element map, no human
/inspect --list | --show <id>     # review recorded sessions

Capturing needs no credentials; only pushing does. A pushed session becomes an intent's visual context and stores each page's page capture on its ui.page aspect for Pages.

Understand

/discover is the graph-first pass to run after the repo is mapped and synced. A script reads the board tree, scores what the architecture can answer on its own, and offers two ranked menus:

  • Insights describe one element and trace the relevant path, such as a chokepoint, an outage cascade, or the route from an entry point to a leaf.
  • Context boards draw a small C4 board of relationships to explain a blast radius, a neighborhood, or where data lives.

Pick from the menus, pass a [count], or take the recommended set with --auto. Use --lens reliability,onboarding,ownership to weight the ranking and --board <slug> to scope one board. Authoring agents write the picks in parallel, and the plugin pushes them in order. Insights appear under the Architecture Highlights skill; context boards appear in the hub's Context boards card. A new run replaces the previous results.

/insights runs workspace insight skills. The server provides the skill definition; the plugin reasons locally over the board and source, then pushes a batch of insights. Each insight is tied to an element and can become an intent.

Build

These commands bring board context back into the repo. They write application or compiled-skill files. Other commands write local plugin state.

/skills compiles this app's skills into IDE-native files. On Claude Code, it writes to .claude/skills/. Related skills are grouped into a recipe.

It preserves local edits and records what it wrote in pmap-skills.lock.json; commit both so the team shares them.

BASH
/skills            # compile the bundle into the repo
/skills --status   # read-only: up to date? changed upstream? edited locally?

/build implements the platform's build context, including in an empty repo. It assembles compiled skills, open intents, unbuilt board design, and aspect contracts, classifies the repo, and changes nothing until you approve the plan. Re-running builds only the delta.

BASH
/build           # assemble the build context, plan, then implement after approval
/build --plan    # present the plan only — no files touched

/intents works handed-off intents in four steps: claim, implement from Instructions and anchors, verify with project checks, then resolve with a note. It never edits before a claim and gap review, never resolves without verification evidence, and blocks stale intents.

You author, hand off, and assign intents in the portal; see Intents.

Operate

/monitor correlates production signals with board elements. It maps stack frames, resource names, routes, and tags; uncertain matches become prompts you answer once. Matches appear as insights.

BASH
/monitor                          # pull signals from connected monitoring tools
/monitor --input <signals-file>   # or feed an exported, normalized signals file
/monitor setup                    # configure sources and a recurring run

/monitor setup scaffolds config and, where supported, creates the recurring run. Unattended runs read PMAP_* credentials, so secrets never pass through chat.

Configuration reference

Settings live in .provenmap/config.json and credentials in .provenmap/credentials.json. Add a setting to override its default; delete it to restore the default. config.schema.json, beside the config, lists every setting and its default for editor completion.

What /login writes

A fresh sign-in on Claude Code writes this file:

JSON
{
  "$schema": "./config.schema.json",
  "baseUrl": "https://platform.provenmap.com/api",
  "branch": "main",
  "boardSlug": "payments",
  "excludePaths": ["node_modules", "dist", ".git", "coverage"],
  "includeTests": false,
  "includeSourceReferences": true,
  "analysis": { "subagentModel": "sonnet" }
}

On Codex, subagentModel is gpt-5-codex; Cursor omits it.

SettingDefaultEffect
baseUrlhttps://platform.provenmap.com/apiThe API endpoint /login used. Change it only for a self-hosted instance.
branchset by /loginThe git branch pinned to the binding. Commands refuse to push from any other branch.
boardSlugset by /loginThe board this repo is bound to, the root of its board tree.
excludePathsnode_modules, dist, .git, coverageRepo-relative directories the analysis skips, with everything beneath them.
includeTestsfalseSet true to analyze test files. When false, test files and test directories are excluded.
includeSourceReferencestrueSet false to omit file paths from synced nodes and edges.
analysis.subagentModelset by /loginThe model for every parallel layer subagent. "" uses per-layer defaults: domain layers inherit the session model, deeper layers a faster one.

Tuning settings

Analysis coverage: which files count as source and which the planned board tree leaves out.

SettingDefaultEffect
coverage.ignore[]Glob patterns left out of the planned board tree; files matching them belong to no board and no count.
coverage.extensions[]Extra file extensions to count as source, for stacks beyond the built-in language list.
coverage.infratrueIncludes infrastructure and schema files (Docker, Terraform, CI workflows, Kubernetes, SQL migrations, serverless templates). They count against coverage only once a board covers them. Set false to exclude them.

Board content: how the analysis resolves imports, folds small files, draws relations, and checks node types.

SettingDefaultEffect
analysis.edgeBudgetPerNode2Board-wide edge budget: this value times the node count, drawn highest import count first. 1 gives a leaner board; 0 draws every resolved relation, subject to analysis.hubDrawnPerHub.
analysis.hubDrawnPerHub3On boards of ten or more nodes, caps the consumer edges drawn from a module that over 40% of the board imports; the node lists the rest. 0 lists every consumer.
analysis.archetypeGateoffSet "strict" to require a settled archetype vocabulary before /analyze. Run /analyze-archetypes to pass the check.
analysis.minorFilesallHow small helper files appear on drill-down boards: all folds eligible files into the node that uses them, one-host folds only single-importer files, off gives each file its own node. Eligible means at most analysis.minorMaxLines lines, imported by another file, and no exported class.
analysis.minorMaxLines100Line cap for the minor-file fold. Files above it are always their own candidates.
analysis.roots[]Extra source directories, relative to the repo root, for a layout your build files don't declare. Python, Go, Ruby, Rust, and Swift imports resolve against each one, so imports that point into them reach real files instead of staying unresolved.

Sync and /inspect: the board-structure check on /sync, and the app URLs /inspect opens.

SettingDefaultEffect
validation.skipBoardStructureCheckfalseSet true to opt out of the board-structure guardrail described in When a run fails.
inspect.urls{}Named app URLs for /inspect, such as {"local": "http://localhost:3000"}. Run /inspect --env local to open one. When /inspect asks for the app URL, you can save the answer here under a name.
inspect.defaultEnvnullThe environment /inspect opens when you pass neither --url nor --env. The first environment you save becomes the default.

Board-tree plan: how deep /analyze plans the board tree, and how many boards /analyze --auto builds.

SettingDefaultEffect
analysis.plan.maxDepth4The deepest layer the plan creates boards for; the bound board is layer 0. Deeper clusters become proposals. null removes the cap. See When plan settings take effect.
analysis.plan.unitFloor12The minimum significant files a cluster needs to become a board. A child must also leave that many in its parent.
analysis.plan.maxParallel4Boards /analyze --auto builds at once.
analysis.plan.maxBoardsPerRun25Boards one /analyze --auto run builds before it stops and asks.
Tip

To plan without limits, set maxDepth to null for depth and lower unitFloor for breadth, so smaller clusters become boards too. Raise maxBoardsPerRun to build the whole tree in one /analyze --all --auto run. Every extra board adds model tokens, analysis time, and rows against your graph allowance.

When plan settings take effect

The first /analyze computes the board-tree plan and stores it; maxDepth and unitFloor apply to that computation. maxParallel and maxBoardsPerRun apply on every run.

Warning

Changing maxDepth or unitFloor after the plan exists doesn't resize it: planned boards stay, and new depth arrives only as proposals. To re-plan, run /analyze --clean, which deletes the local analysis and plan, then rebuild and /sync. /sync doesn't delete boards the new plan drops.

Files and allowance

Edges take the largest share of your organization's graph allowance. A repo of about 3,000 files across 29 boards uses about 2,300 rows at the default analysis.edgeBudgetPerNode, 1,500 at 1, and 4,200 at 0.

Credential fields and PMAP_* variables are covered in Signing In & Credentials. Everything else the plugin writes lives under gitignored .provenmap/. Commit what /skills writes and the application changes from /build and /intents.

There is no background auto-sync. Analysis, sync, and monitoring run only when you, or a schedule you created, run the commands.

When a run fails

Five failures are most common.

What you seeWhat's happening, and the fix
/sync rejected by the board-structure checkA board with more than 8 nodes has no domain_group containers. Re-run /analyze, which populates them. If the board really is that simple, set validation.skipBoardStructureCheck; every /sync then says so on stderr.
/sync refuses on a branch mismatchThe branch in your config is not the branch the binding is tied to. Set the config to match the binding.
Credentials rejectedThe credential was revoked, or a fresh /login on this machine replaced it. Run /login to reconnect, or use Generate new secret in the binding's credentials dialog and update credentials.json or your CI environment variables.
Push rejected with a repo mismatchThe board is bound to a different repo. The binding records the first repo that pushes and refuses pushes from another repo, so two codebases can't overwrite each other. Bind this repo to its own board instead.
/adopt stops before extractingThe board structure is not synced yet. Run /analyze → /sync first, then adopt. If strict archetype checking is enabled, run /analyze-archetypes before /analyze.

What's next

link-2

The Connect Plugin

The sibling plugin that grounds an authored board in a document repo, with its own /sync and command set.

Boards API

Headers, payload shape, and auth for every push.

Connecting Sources

Register a source, bind it from the hub, and copy the credentials this plugin needs.

Insight Skills

How the skills /insights runs are authored at the workspace level.

The Architect Workbench

Explore, review, and author on the boards this plugin builds.