Insights

---
name: insights
user-invokable: false
description: Bundled Node.js CLI scripts for fetching server-defined insight skills and pushing analysis results to the ProvenMap Claude Code Plugin API. Provides pmap-insights.js for skill caching, insight persistence, and server push. Self-contained — no npm install required.
metadata:
  author: ProvenMap
  version: 0.2.0
---

# ProvenMap Insights Scripts (Code)

This skill provides bundled Node.js scripts for running server-defined insight analyses on codebase architecture boards. These scripts are self-contained — no npm install required.

## Available Scripts

### pmap-insights.js — Insight Skill & Results Manager

Fetches insight skills from the server, saves analysis results locally, and optionally pushes to the Claude Code Plugin API.

**Invocation:**
```bash
node ${CLAUDE_PLUGIN_ROOT}/scripts/pmap-insights.js [mode] [options]
```

**Modes:**

| Mode | Arguments | Description |
|---|---|---|
| `--list-insight-skills` | `[--no-cache]` | Fetch available insight skills as JSON |
| `--get-insight-skill <slug>` | _(none)_ | Fetch full skill by slug (instructions + references) |
| `--save-insight <path>` | `[--push]` | Save insight payload from JSON file; optionally push to server |
| `--list-insights` | _(none)_ | List locally stored insight skill slugs |
| `--build-context` | `--board-slug <slug> [--out <path>] [--summary] [--demo]` | Build the deterministic context pack (board universe + keyed element/edge index) for a board |

**Common Options:**
| Flag | Default | Description |
|---|---|---|
| `--config <path>` | `.provenmap/config.json` | Config file path |
| `--cache-file <name>` | `insight-skills-cache.json` | Cache file name |
| `--no-cache` | - | Bypass cache, always fetch from server |
| `--push` | - | Attempt to push insight to server after saving |

**Output:** JSON to stdout with fields: `success`, `skills` or `storedInsights`, `featureAvailable`, `cacheStatus`

**Exit codes:** 0=success, 1=config error, 2=board data error (missing/empty/corrupt), 3=API/build error

### pmap-context-tags.js — ContextTag Vocabulary

Fetches the org's curated ContextTag vocabulary (1-hour TTL cache). Pull it during analysis so you can classify insights with tags the org actually uses — the `name` values are what you put in the insight payload's `tags` array, and the server **rejects any name not in this list**.

**Invocation:**
```bash
node ${CLAUDE_PLUGIN_ROOT}/scripts/pmap-context-tags.js [--no-cache]
```

**Output:** JSON with `tags` (`{name, category, description}[]`) and `tagNames` (`string[]`). Copy the relevant `name` values verbatim into the payload's `tags` field.

## Configuration Source

Scripts read configuration from `.provenmap/config.json`.

## Local Storage

Insight results are stored per-skill at `.provenmap/boards/insights/<skill-slug>.json`. Skill metadata is cached at `.provenmap/boards/insight-skills-cache.json` with a 1-hour TTL. The deterministic context pack (`--build-context --out`) is written per board to `.provenmap/discover/packs/<board>.context.json` and recomputed each run; `--save-insight` loads it as the oracle for its quality gates.

## References

- [execution-protocol.md](references/execution-protocol.md) — How to execute an InsightSkill
- [graph-context.md](references/graph-context.md) — How to extract board context for analysis
- [report-output-format.md](references/report-output-format.md) — InsightDraft, Stop, trail, advice, proposal, and measurement schemas