Distribution mirror — built artifacts only (claude plugins v0.18.0). Generated from a private source repository. Do not open pull requests here.
Turn a codebase into a living architecture board on ProvenMap Portal — straight from your AI coding host. No manual diagramming: the plugin scans your code, classifies every component against your org's archetype catalogue, maps the relationships, and syncs a structured graph you can review, share, and run analyses on.
The pipeline runs both ways: the platform also carries your app's spec — compiled skills
(specs + guidelines), architect intents, board designs, and aspect contracts — and /build
implements it in the repo, from an empty directory up, then maps the result back onto the board.
Boards themselves are authored by an architect, not produced by scanning documents. ProvenMap Connect binds a document/knowledge repo to an architect-authored board and keeps it honest: maintaining node↔document evidence links, reporting drift when a linked document changes underneath the board, and implementing architect-authored intents by editing the documents directly. It has no analysis brain of its own — the architect authors the board upstream.
And the people authoring that spec get their own plugin: ProvenMap Architect is the architect workbench — explore the board graph, review insights, and draft intents from the same AI host, over the ProvenMap MCP server, with every write landing as a reviewable draft.
Three plugins, one engine:
| Plugin | Install id | Serves | Works with | Lead commands |
|---|---|---|---|---|
| ProvenMap Code | pmap-code |
Developers | A codebase — JS/TS, Python, Java, Go, C#, Ruby, Rust → an architecture board | /analyze · /build |
| ProvenMap Connect | pmap-connect |
Developers / writers | A document/knowledge repo — grounds an architect-authored board, no board of its own | /sync · /intents |
| ProvenMap Architect | pmap-architect |
Architects | The existing board graph + documents + insights, over MCP — writes land as drafts | /board · /intents |
ProvenMap Code produces boards from a codebase and emits the node/edge wire model; ProvenMap Connect grounds a board an architect already authored, in this repo's documents; ProvenMap Architect works over any board — code- or architect-authored — via MCP. Per‑plugin docs: ProvenMap Code · ProvenMap Connect · ProvenMap Architect.
The same plugin content is repackaged per host. Pick the row for your tool:
| Host | ProvenMap Code | ProvenMap Connect | ProvenMap Architect | How you install |
|---|---|---|---|---|
| Claude Code / Claude Cowork | ✅ | ✅ | ✅ | Marketplace provenmap/pmap-claude |
| Codex / Codex for Work | ✅ | ✅ | ✅ | Marketplace provenmap/pmap-codex |
| Cursor | ✅ | planned | planned | Local install + “Add to Cursor” deeplink |
Note
Cursor ships ProvenMap Code only for now — ProvenMap Connect and ProvenMap Architect on Cursor are planned,
not yet built. Also: the published artifacts are useless without ProvenMap credentials —
installing a plugin is safe, but it does nothing until you connect it (/configure or
/login) against a workspace you belong to.
The commands below are live. provenmap/pmap-claude and provenmap/pmap-codex stay in lockstep
(yarn release publishes both together) and the provenmap marketplace on each serves the current
published pmap-code, pmap-connect, and pmap-architect.
Add the marketplace once, then install whichever plugins you want (Cowork uses the same marketplace):
/plugin marketplace add provenmap/pmap-claude
/plugin install pmap-code@provenmap # codebase → architecture board
/plugin install pmap-connect@provenmap # ground an authored board in your documents
/plugin install pmap-architect@provenmap # architect workbench over MCPRestart Claude Code so the commands load. Scope the install with --scope user (default, all your
projects), --scope project (shared via .claude/settings.json), or --scope local (only you, only
this repo).
codex plugin marketplace add provenmap/pmap-codexThen install pmap-code, pmap-connect, and/or pmap-architect from /plugins and restart
Codex. The code plugins auth via the same .provenmap/config.json described below; ProvenMap Architect
uses an MCP token (see Configure — ProvenMap Architect).
Cursor installs locally (no marketplace yet). After building (or downloading) the plugin:
# Copy the built plugin into Cursor's local plugins directory:
cp -r pmap-code ~/.cursor/plugins/local/pmap-codeThen add the MCP server with the “Add to Cursor” deeplink on provenmap.com and restart Cursor. (Cursor currently ships ProvenMap Code only.)
The two plugin families authenticate differently — a repo‑pinned binding for the code plugins, a workspace‑roaming MCP token for the architect plugin.
Every host reads the same project‑local config. Get a Binding Token and API Secret from the
ProvenMap Portal (Sources → Add Source → Board Builder — saving generates the secret), then create
.provenmap/config.json at the root of your repo or document set:
{
"bindingToken": "your-base64url-binding-token",
"apiSecret": "ck_cp_live_your_api_secret",
"boardSlug": "my-project-overview",
"branch": "main",
"baseUrl": "https://platform.provenmap.com/api"
}| Field | Required | Notes |
|---|---|---|
bindingToken |
yes | Base64url workspaceId::bindingId from the portal. Sent as X-CodePlugin-Token. |
apiSecret |
yes | Must start with ck_cp_live_. Sent as X-CodePlugin-Secret. |
boardSlug |
yes | Target board. /configure can discover and write it for you. |
branch |
yes | Must match the binding, or /sync returns 400 Branch Mismatch. (Optional for non‑git doc sets.) |
baseUrl |
no | Override for self‑hosted (default https://platform.provenmap.com/api). |
excludePaths |
no | Paths skipped during analysis (default node_modules, dist, .git, coverage). |
includeTests |
no | ProvenMap Code only — include test files in analysis (default false). |
includeSourceReferences |
no | Attach file/doc path + short excerpt to synced nodes/edges (default true). |
Run /configure to validate the config, test the connection, and add .provenmap/ to your
.gitignore. Credentials live only in this file — never logged or echoed to chat, and sent only to
platform.provenmap.com.
A
SessionStarthook scaffolds an empty.provenmap/config.jsonand the.gitignoreline for you on first run. It makes no network calls. (Cowork/Cursor‑cloud may not fire hooks — use/configureand/statusas the fallback.)
ProvenMap Architect keeps no project files: it talks to the ProvenMap MCP server
(https://platform.provenmap.com/api/mcp) with a workspace‑scoped bearer token
(ck_mcp_live_…) that carries the whole identity — workspace, scope (read / read_write),
and an optional board‑subtree restriction.
/login(recommended): sign in in the browser, pick workspace + scope + restriction, and the generated token is stored for you (user‑scope,~/.provenmap/architect-mcp.json, owner‑only) and written into the host's MCP config where scriptable. Approval needs workspace admin./configure(manual / restricted accounts): an admin generates the token in workspace settings → MCP access tokens; set it asPMAP_MCP_TOKENin your environment and restart the session. The plugin ships an.mcp.jsonthat expands it./statusprobes the connection (tools/list) and reports scope;/logoutremoves the stored token locally (revoke server‑side in the same settings screen).
The token never transits the chat — displays show it masked or as presence only.
/configure— connect to the portal (one‑time per repo)./analyze— the full codebase analysis. Incremental by default — only changed files are re‑analyzed./sync— push the analysis to your board (smart diff: only new/changed elements)./insights— run server‑defined analyses (security, performance, etc.) against the board./status— see config state, the analysis summary, and sync state.
/configure
/analyze # analyze the codebase (incremental)
/analyze src/backend # or target a path
/analyze --clean # force a full re-analysis
/sync # push to the portalCustomizing the vocabulary (optional). /analyze types every component with the closest
archetype your server's catalogue offers, and names any gaps it hit once the board is built. If you
want those categories in the catalogue, run /analyze-archetypes to propose them for admin
review, then /analyze --clean once they land. To require settlement before every /analyze
instead, set "analysis": { "archetypeGate": "strict" } in .provenmap/config.json.
Commands are grouped by lifecycle stage — the same five groups /help renders. The stages form a
loop: Operate findings become intents an architect approves, Build implements them,
Map re-syncs so the server verifies the change, Understand evaluates the new state.
1 · Account — bind this project to a ProvenMap board
| Command | Plugin | What it does |
|---|---|---|
/login |
both | Sign in in the browser and pick a board — no copy‑paste |
/configure |
both | Manual credential setup, connection test, .gitignore |
/status |
both | Lifecycle dial (where you are + the one next command) + config, analysis, and sync state |
/help |
both | Grouped command list and the plugin version |
/update |
both | Update this plugin to the latest published version for your host |
2 · Map — turn the codebase into a living board, or ground an authored one
| Command | Plugin | What it does |
|---|---|---|
/analyze [path] (--clean / --drill <board>/<node> / --all) |
ProvenMap Code | Analyze codebase architecture (incremental) |
/adopt --aspect <kind> (--db / --api aliases) |
ProvenMap Code | Extract a code aspect (DB schema / API surface / frontend pages / event catalog / authz registry) onto the board |
/sync [--board <slug>] · /sync --all |
both | ProvenMap Code pushes the analysis (diff‑based); ProvenMap Connect pulls the authored board and pushes evidence links |
/demo-insights [count] |
both | Seed a freshly mapped/grounded board with demonstrative, path‑rich insights |
3 · Understand — run intelligence on the mapped board
| Command | Plugin | What it does |
|---|---|---|
/insights · /insights <slug> · /insights --all |
both | List and run server‑defined insight skills against the board |
4 · Build — let the platform's spec drive the code
| Command | Plugin | What it does |
|---|---|---|
/skills [--status] |
both | Compile the platform's skill bundle (specs + guidelines) into the repo — never overwrites your local edits |
/build [--plan] |
ProvenMap Code | Build the app from the platform's spec — compiled skills, intents, board design, aspect contracts. Works from an empty repo (bootstrap) or an existing one (gap‑fill), incrementally |
/intents |
both | Pull architect‑authored intents, implement them, record resolutions |
5 · Operate — keep production and the board in a scheduled loop
| Command | Plugin | What it does |
|---|---|---|
/monitor · /monitor setup |
ProvenMap Code | Correlate monitoring signals (Sentry errors, CloudWatch, cloud costs) with board elements and push the findings as a draft insight; architects promote findings to intents. setup configures sources + a recurring run |
Advanced — opt‑in customization no workflow requires
| Command | Plugin | What it does |
|---|---|---|
/analyze-archetypes (--dry-run / --skip-submit / --replace) |
ProvenMap Code | Customize the archetype vocabulary — scan for gaps in your server's catalogue and submit proposals for admin review |
For non‑trivial codebases, /analyze produces a hierarchy so you can navigate from a 10–30 node overview
down to detail without overwhelming any single view:
| Layer | Scope |
|---|---|
| L0 Overview | Entire project |
| L1 Domain | Domain / workspace |
| L2 Component | Service / module |
| L3 Detail | Deep internals (opt‑in) |
Board hierarchy and per‑board sync state live in .provenmap/boards/ (manifest.json,
<board-slug>.json, stores/<board-slug>.store.json).
Components are classified against archetypes defined on your ProvenMap server — not a fixed list
shipped with the plugin. The catalogue is per board kind (code for architecture boards,
knowledge for the boards ProvenMap Connect grounds). Knowledge-kind archetypes are settled by the
architect's own /archetypes command in ProvenMap Architect, since ProvenMap Connect never produces
a board. If your codebase has patterns that don't fit, /analyze types them with the closest
available archetype and reports the gap; /analyze-archetypes then proposes new archetypes (or
improvements) for human review. Settling is optional — the board is complete either way.
Connect has no analysis brain of its own — the architect authors the board upstream in ProvenMap
Portal. Connect's job, all run from /sync, is three duties:
- Evidence — maintains node↔document links between the authored board and this repo's documents: which document(s) substantiate each node's claim, down to an anchor and a quoted excerpt.
- Drift — notices when a linked document changes (or disappears) underneath the board and reports it, so a citation never goes silently stale.
- Fulfillment — beyond
/sync,/insightsruns server‑defined analysis against the grounded board, and/intentsimplements architect‑authored intents by editing this repo's documents directly.
/configure
/sync # pull the authored board, propose + push evidence links, report drift
/insights # run server-defined insight skills against the grounded board
/intents # pull and implement architect-authored intentsRun /sync again any time the documents change — it re‑mirrors, re‑diffs, and only asks you to look
at what actually drifted. See ProvenMap Connect for the full command
reference and supported document formats.
Where the code plugins push boards up, ProvenMap Architect works the boards: it consumes the
platform's ~25–47 fenced board tools over MCP (reads always; writes with a read_write token),
and every write lands as a draft — a revertible intent reviewed in ProvenMap. Delete the
intent to revert the change; nothing mutates a board directly.
The command lifecycle (/help renders the same four groups):
| Stage | Command | What it does |
|---|---|---|
| Account | /login · /configure · /status · /logout · /help · /update |
MCP‑token lifecycle (browser device flow or manual) |
| Explore | /board [slug] |
Orient on a board — layers, structure, work in flight — then free conversation: questions, analysis, governed edits |
/hub |
Workspace dashboard: board tree, intent counts, latest insights, binding health | |
| Review | /insights |
Review insight runs; promote reviewed findings into draft intents |
| Author | /intents |
List, author, and manage intents (drafts → an architect opens them for developer pulls) |
Drop a PRD or RFC into the session and ask for it to become board work — the plugin reads it with
the host's own file access, drafts intents anchored to the right elements by slug, and it
all lands for review. The loop closes with the code plugins: developers pull what architects
author here via /intents and deliver it.
- Credentials are user‑supplied and stored only in project‑local
.provenmap/config.json(plaintext, gitignored). They are never logged, never echoed to chat, and sent only asX-CodePlugin-Token/X-CodePlugin-Secretheaders. The plugin reads no secrets from environment variables and no files outside your project (~/.ssh,~/.aws,~/.netrc, etc. are never touched). - The only network endpoint is
https://platform.provenmap.com/api, contacted solely when you run/analyze,/sync, or/insights— never in the background. - ProvenMap Architect's credential is an MCP bearer token, kept in your environment
(
PMAP_MCP_TOKEN) or the owner‑only~/.provenmap/architect-mcp.jsonwritten by/login— never in the project, never in chat (always masked). Its only endpoints are…/api/mcp(tools) and…/api/mcp/device/*(login); revoke any token in workspace settings and the next call 401s. - What leaves your machine: node/edge names and descriptions (≤500 chars), file/document paths,
short source excerpts (≤500 chars per reference), line ranges, the git origin remote URL
(
git remote get-url origin), branch, commit, and project name. SetincludeSourceReferences: falseto omit paths/excerpts (analysis still runs).
| Problem | Solution |
|---|---|
| “ProvenMap not configured” | Run /configure with credentials set in .provenmap/config.json |
| “Configuration file not found” | Run /configure first — it scaffolds .provenmap/config.json |
| “Invalid apiSecret format” | The API secret must start with ck_cp_live_ |
401 Unauthorized |
Regenerate the binding token / API secret in the ProvenMap Portal |
400 Branch Mismatch |
Set branch in the config to match the board binding |
| “No analysis found” | Run /analyze before /sync (ProvenMap Code only — ProvenMap Connect's /sync grounds directly, no prior analysis step) |
| Commands not showing | Restart the host after installing; on Cowork/Cursor‑cloud use /configure + /status |
/analyze keeps asking about archetypes |
Your config has analysis.archetypeGate: "strict" — remove the key to make settlement optional again |
Business Source License 1.1 — source‑available, converts to Apache 2.0 on 2030‑05‑29. See LICENSE for the Additional Use Grant (production use permitted except for offering a competing hosted/managed service).