ProvenMap
Getting Started

Getting Started

Your architecture is a handful of systems and the connections between them. Here you draw that whole estate first — your system landscape — then drill into one system and let the Cdx Code plugin map its repo in detail. You own the top of the map; the plugin fills in what's inside each box.

Note

The plugin's core loop — /analyze, /sync, /insights — works with no model provider connected. Cdx Code reasons inside your own AI coding session, not on our servers. A model provider is optional, needed only for chat and for building a board from a governing docs source.

Before you start

That's all you need to draw the landscape. An AI coding tool and plugin credentials come later, once you've drilled into a system and have a board to map.

Start with the landscape

Your Root Board is your landscape. Lay out your estate on it: one node per system, an edge wherever two connect. Type each node from the archetype library — a System for a whole application, with cloud, database, and integration archetypes for the parts you already know. Archetypes carry containment rules, so a System can hold Services and the map stays valid as it grows. You can also define your own.

Say you run three systems — a marketing portal, the platform behind it, and the infrastructure that provisions them both. Three System nodes and the edges between them, and you've drawn the top of your map.

The top of the map: your estate, authored from the archetype library.

This is your system landscape: the top of the map. Everything below it is a drill-down.

Drill into a system

Pick a system to map in detail — say one backed by a code repo. Right-click its node and choose Create Subsystem Layer: the node gets a drill-down indicator, and clicking it takes you into a fresh child board for that system. (Boards → Layers covers the nesting model.)

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

You're one level down now: the landscape above, an empty board for this system in front of you. Next, fill it from the repo.

Connect the board to your repo

Connect a board to the Code Plugin

You drew the system; Cdx Code maps its internals. This is the first step that needs a coding agent — Claude Code, Codex, or Cursor. Install the plugin for your platform, point it at the repo behind this board, and sync.

BASH
/plugin marketplace add contextdx/cdx-claude
/plugin install cdx-code@contextdx   # then restart Claude Code

Once it's installed, the commands are identical on every platform:

BASH
/configure   # connect to this board (reads .contextdx/config.json)
/analyze     # map the repo into a structured graph, locally
/sync        # push it onto the board

/configure validates your config, tests the connection, and confirms the board it's bound to. /analyze scans the repo — services, APIs, databases, queues — into an L0 overview (usually 10–30 nodes) on disk, pushing nothing yet. /sync pushes that graph onto the board you drilled into.

Note

cdx-code is the install id for the code plugin; its sibling Cdx Work maps a knowledge base the same way (/analyze-docs → /sync). The full command and config reference lives in the ContextDX Plugins.

Where your credentials come from

The bindingToken and apiSecret (it starts with ck_cp_live_) in your config come from a Code Plugin source bound to this board:

  1. In the workspace: Sources → Add Source → Code Plugin (saving generates the API Secret).
  2. Open the system's board → Sources → Bind Source, pick that source, set the branch (e.g. main).
  3. Click Copy Credentials, then set boardSlug to this board.

A binding is tied to one branch — match branch in your config to it, or /sync fails with 400 Branch mismatch. Deep dive: Connecting Sources and Boards API.

Climb back to the landscape and the system you drilled is no longer a single node — it opens into everything Cdx Code just mapped.

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

Go deeper: layers inside the repo

The board you filled is the repo's L0 overview. Drill further into any node and Cdx Code maps that slice in detail — /analyze --drill <board>/<node> for one node, or /analyze --all then /sync --all to build the whole L0 → L1 → L2 hierarchy at once. Each layer links to its parent automatically, so a click descends into the internals. Commands and flags in the ContextDX Plugins; the layer model in Boards.

Map your other systems

Repeat for each system on the landscape: drill its node into a board, then map its repo. One binding maps one repo — so when a repo changes, only its board moves, and Cdx Code never blurs two codebases into one. Run /configure from inside each repo against that system's board; each keeps its own .contextdx/config.json and Binding Token. Branch and slug rules are in the ContextDX Plugins.

Add the why: boards from docs

Code gives you structure, not the why. Bind a documentation source — Confluence, Notion, a URL, or a pasted Note — as reference (context for chat) or governing (it extracts structure onto the board). The strongest boards pair a code-built board with reference docs, so chat can explain why the architecture is the way it is — answered from the ADR that decided it. Full catalog and roles in Connecting Sources.

Or map a whole knowledge base the way you just mapped code: point Cdx Work — the docs sibling of Cdx Code — at your docs repo and it pushes a knowledge board of concepts, decisions, and how they relate, with /analyze-docs → /sync. Same nodes-and-edges model, in Claude Code or Codex (Cursor coming for Cdx Work).

Note

Building a board from a governing docs source uses server-side extraction, so that path needs a connected model provider (e.g. OpenRouter) — unlike the plugin's code path. See Turn on Chat.

Generate insights

/insights runs your workspace's insight skills — security checks, dependency audits, quality reviews — entirely in your AI coding session, no model provider required. Each finding pins to a component and highlights it on the board. Target them (/insights find auth risks), list them (--list), or run every skill (--all). Author your own in Insight Skills.

Publish & share

Publish a board to create a read-only snapshot your team can self-serve at a stable URL — Public, Unlisted, or Protected (share token or password). Re-publish after changes. Visibility controls and the stakeholder viewer in Publishing Boards.

Keep it current

Analysis is incremental by default: re-run /analyze then /sync after code changes and only the diff moves. Use /analyze --clean to force a full re-analysis when a result looks stale. The first deep pass on a large monorepo takes a few minutes; everything after is fast.

Turn on Chat

Chat answers natural-language questions about your landscape — "where does auth live?", "what depends on the payments service?" — and can return a board, not just text. It needs a one-time, org-level model-provider connection (e.g. OpenRouter) in Settings → Integrations; the plugin loop above runs without it. See the Integrations Reference to connect one, and Org-Level Intelligence for what it unlocks across the landscape.

Tip

Starting from a completely empty workspace with chat on? Open it and pick Set up your project — chat interviews you about your systems and repos, then scaffolds the landscape, the app boards, and their bindings for you (every step approved in the conversation). It replaces the manual landscape steps above; you jump straight to /configure in each repo. Offered only while the workspace is brand new.

You're done — checklist

  • Drew the system landscape on your Root Board from the archetype library
  • Drilled a system node into its own board layer (Create Subsystem Layer)
  • Mapped and synced the system's board (/configure → /analyze → /sync)
  • Repeated for your other systems — one binding per repo
  • (Optional) Added a docs source, ran /insights, published, or turned on chat

What's next

Your landscape is live and filling in. The next move is to let your whole org query it — connect a model and ask your architecture anything in Org-Level Intelligence.

Related docs: