Distribution mirror — built artifacts only (claude plugins v0.7.1). Generated from a private source repository. Do not open pull requests here.

ProvenMap Plugins — Prov Code, Prov Work & Prov Architect

Turn a codebase or a document set into a living architecture/knowledge board on ProvenMap Portal — straight from your AI coding host. No manual diagramming: the plugin scans your code or docs, 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.

And the people authoring that spec get their own plugin: Prov Architect is the architect workbench — explore the board graph, review insights, and draft intents and specs 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
Prov Code	prov-code	Developers	A codebase — JS/TS, Python, Java, Go, C#, Ruby, Rust → an architecture board	/analyze · /build
Prov Work	prov-work	Developers / writers	A document set — specs, RFCs, ADRs, policies, wikis → a knowledge board	/analyze-docs
Prov Architect	prov-architect	Architects	The existing board graph + documents + insights, over MCP — writes land as drafts	/board · /intents

Prov Code and Prov Work produce boards from raw material and emit the same node/edge wire model; Prov Architect works over the boards they produce (any board — code boards included). Per‑plugin docs: Prov Code · Prov Work · Prov Architect.

---

Hosts & availability

The same plugin content is repackaged per host. Pick the row for your tool:

Host	Prov Code	Prov Work	Prov Architect	How you install
Claude Code / Claude Cowork	✅	✅	✅	Marketplace provenmap/prov-claude
Codex / Codex for Work	✅	✅	✅	Marketplace provenmap/prov-codex
Cursor	✅	planned	planned	Local install + “Add to Cursor” deeplink

Note

Cursor ships Prov Code only for now — Prov Work and Prov 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.

---

Installation

Important

Pre-release. The dist repos (provenmap/prov-claude, provenmap/prov-codex) exist, but the first ProvenMap-branded release (yarn release, v0.7.0) hasn't been published yet — until it ships, the marketplace add / install commands resolve to stale pre-rebrand artifacts or nothing. To try it now, build from source (yarn build) and install the generated plugin under plugins/<suite>/<host>/<plugin>/ via your host's local-install path, or watch provenmap.com for availability.

Claude Code & Claude Cowork

Add the marketplace once, then install whichever plugins you want (Cowork uses the same marketplace):

/plugin marketplace add provenmap/prov-claude
/plugin install prov-code@provenmap        # codebase → architecture board
/plugin install prov-work@provenmap        # documents → knowledge board
/plugin install prov-architect@provenmap   # architect workbench over MCP

Restart 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

codex plugin marketplace add provenmap/prov-codex

Then install prov-code, prov-work, and/or prov-architect from /plugins and restart Codex. The code plugins auth via the same .provenmap/config.json described below; Prov Architect uses an MCP token (see Configure — Prov Architect).

Cursor

Cursor installs locally (no marketplace yet). After building (or downloading) the plugin:

# Copy the built plugin into Cursor's local plugins directory:
cp -r prov-code ~/.cursor/plugins/local/prov-code

Then add the MCP server with the “Add to Cursor” deeplink on provenmap.com and restart Cursor. (Cursor currently ships Prov Code only.)

---

Configure

The two plugin families authenticate differently — a repo‑pinned binding for the code plugins, a workspace‑roaming MCP token for the architect plugin.

Prov Code & Prov Work — project binding

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 orgId: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	Prov 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 SessionStart hook scaffolds an empty .provenmap/config.json and the .gitignore line for you on first run. It makes no network calls. (Cowork/Cursor‑cloud may not fire hooks — use /configure and /status as the fallback.)

Prov Architect — MCP token

Prov 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 minted 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 mints the token in workspace settings → MCP access tokens; set it as PROV_MCP_TOKEN in your environment and restart the session. The plugin ships an .mcp.json that expands it.
• /status probes the connection (tools/list) and reports scope; /logout removes 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.

---

Usage — the two‑phase workflow (Prov Code & Prov Work)

Analysis is split into two phases so every component gets a fit archetype instead of a misfit that needs re‑typing later:

1. /configure — connect to the portal (one‑time per repo / doc set).
2. /analyze-archetypes — Phase 1: scan for the categories present, compare them against your server's archetype catalogue, and either confirm it's complete or submit proposals for admin review. This is a precondition — Phase 2 prompts you to run it if the catalogue is stale or missing.
3. /analyze (Prov Code) or /analyze-docs (Prov Work) — Phase 2: the full analysis. Incremental by default — only changed files/docs are re‑analyzed.
4. /sync — push the analysis to your board (smart diff: only new/changed elements).
5. /insights — run server‑defined analyses (security, performance, etc.) against the board.
6. /status — see config state, the archetype precondition, the analysis summary, and sync state.

# Prov Code
/configure
/analyze-archetypes      # settle the vocabulary (Phase 1)
/analyze                 # analyze the codebase (Phase 2, incremental)
/analyze src/backend     # or target a path
/analyze --clean         # force a full re-analysis
/sync                    # push to the portal

# Prov Work
/configure
/analyze-archetypes      # settle the vocabulary (Phase 1)
/analyze-docs            # analyze the document set (Phase 2, incremental)
/sync                    # push to the portal

Command reference — five lifecycle stages

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 · Connect — 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, archetype, 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 / document set into a living board

Command	Plugin	What it does
/analyze-archetypes (--dry-run / --skip-submit / --replace)	both	Phase 1 — scan for archetype gaps, submit proposals if needed
/analyze [path] (--clean / --drill <board>/<node> / --all)	Prov Code	Phase 2 — analyze codebase architecture (incremental)
/analyze-docs (same flags)	Prov Work	Phase 2 — analyze the document set (incremental)
/adopt --aspect <kind> (--db / --api aliases)	Prov Code	Extract a code aspect (DB schema / API surface / frontend pages / event catalog / authz registry) onto the board
/sync [--board <slug>] · /sync --all	both	Push analysis to the portal (diff‑based); one board or every board
/demo-insights [count]	both	Seed a freshly mapped 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]	Prov 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	Prov 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

Layered boards

For non‑trivial inputs, Phase 2 produces a hierarchy so you can navigate from a 10–30 node overview down to detail without overwhelming any single view:

Layer	Scope (Code)	Scope (Work)
L0 Overview	Entire project	Entire knowledge base
L1 Domain	Domain / workspace	Subject area / doc collection
L2 Component	Service / module	Single document / spec
L3 Detail	Deep internals (opt‑in)	Section / decision internals (opt‑in)

Board hierarchy and per‑board sync state live in .provenmap/boards/ (manifest.json, <board-slug>.json, stores/<board-slug>.store.json).

Archetypes are server‑defined

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 knowledge boards); Phase 1 settles the right one before Phase 2 runs. If your input has patterns that don't fit, /analyze-archetypes proposes new archetypes (or improvements) for human review before any board is produced.

---

Usage — the architect workbench (Prov Architect)

Where the code plugins push boards up, Prov 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
Connect	/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)
	/specs	Draft specs from conversation or documents; promote approved requirements into intents

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

---

Credential security & data flow

• 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 as X-CodePlugin-Token / X-CodePlugin-Secret headers. 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-archetypes, /sync, or /insights — never in the background.
• Prov Architect's credential is an MCP bearer token, kept in your environment (PROV_MCP_TOKEN) or the owner‑only ~/.provenmap/architect-mcp.json written 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. Set includeSourceReferences: false to omit paths/excerpts (analysis still runs).

---

Troubleshooting

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 (or /analyze-docs) before /sync
Commands not showing	Restart the host after installing; on Cowork/Cursor‑cloud use /configure + /status
/analyze keeps asking for Phase 1	Run /analyze-archetypes — the catalogue is stale or hasn't been settled for this state

---

License

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).