feat(wiki): improve registry visualization scoring and docs (#276)

* feat(wiki): add /visualize-registry skill for cross-campaign knowledge graph

Adds the registry visualization — an interactive D3.js HTML page showing
campaigns, entities, concepts, and parameters as a force-directed graph
with entity clusters and heuristic opportunity scoring.

The Opportunities tab computes scores from frontier/interaction/dead-end
counts per cluster (no LLM calls needed) and provides copyable /suggest-next
commands for users who want detailed recommendations for specific clusters.

Delivers:
- scripts/visualize_registry.py — generates ~/.nous/wiki/viz/registry.html
- .claude/commands/visualize-registry.md — 4-step deterministic skill
- docs/nous-wiki.md — updated with /visualize-registry documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat(wiki): improve registry visualization scoring and docs

- Fix opportunity scoring: use principle-based relevance matching instead of
  counting all frontiers/interactions from any touching campaign
- Use adaptive normalization (max raw score = 1.0) instead of fixed divisor
- Remove numerical score display from UI — show only raw counts
- Cap entity clusters at 20 per project
- Add quickstart section and concurrency warning to docs/nous-wiki.md
- Document scripts/visualize_registry.py in the Scripts section

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: address PR #276 review — robustness and UX fixes

1. Show all nodes by default on Knowledge tab (was blank until filter)
2. Add try-except to all JSON load paths (graceful degradation)
3. Use D3 CDN directly (remove dead local path fallback)
4. Escape </ in JSON data to prevent </script> injection breakage
5. Remove unused params from build_entity_clusters signature

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: susiejojo

.claude/commands/index-wiki.md

@@ -71,6 +71,7 @@ Merge a single campaign's extracted knowledge into the cross-campaign registry.
 
    b. Semantically group entities by functional role/purpose into clusters. Rules:
       - Min 2 entities per cluster, max 10
+      - Max 20 clusters total per project — if grouping would exceed 20, merge the smallest/most-similar clusters
       - Each entity belongs to at most one cluster (singletons are valid — omit them)
       - Labels: 2-4 words, Title Case, describe the functional group
 

.claude/commands/visualize-registry.md

@@ -0,0 +1,42 @@
+Render the cross-campaign knowledge graph from the Nous wiki registry.
+
+This skill verifies prerequisites and runs `visualize_registry.py` to produce an interactive HTML page showing campaigns, entities, concepts, entity clusters, and heuristic opportunity scores — all computed directly from registry data without any LLM calls.
+
+## Steps
+
+1. **Verify registry exists**: Check that `~/.nous/wiki/registry.json` exists and is non-empty.
+
+   If missing, **STOP** and tell the user:
+
+   > "No registry found. Run `/post-campaign <path>` on at least one campaign first, then re-run `/visualize-registry`."
+
+   Do NOT proceed. Do NOT attempt to generate or fix any data yourself.
+
+2. **Run the visualization script**:
+   ```bash
+   python scripts/visualize_registry.py
+   ```
+
+   The script:
+   - Reads `registry.json` and per-campaign wiki files
+   - Builds a force-directed graph with campaigns, entities, concepts, and parameters as nodes
+   - Computes cross-node edges from explicit relationship fields (operates_on, parent_concept, shared principles)
+   - Computes heuristic opportunity scores per entity cluster from frontier/interaction/dead-end counts
+   - Renders the Opportunities tab showing per-cluster research potential with copyable `/suggest-next` commands
+   - Writes `~/.nous/wiki/viz/registry.html`
+
+3. **Open the HTML**:
+   ```bash
+   open ~/.nous/wiki/viz/registry.html
+   ```
+
+4. **Report** the output path and a brief summary of what's in the graph (number of campaigns, entities, concepts, clusters).
+
+## Important
+
+- This skill does NOT modify registry.json, campaign data, or any existing wiki files.
+- The ONLY file this skill writes is `~/.nous/wiki/viz/registry.html` (via the Python script).
+- Entity clusters are pre-computed at index time by `/index-wiki` and stored in `registry.json`. The script reads them directly.
+- No LLM calls are made. All scoring is heuristic (frontier count, interaction count, recency, dead-end density).
+- The Opportunities tab helps users identify where to focus research, then run `/suggest-next` themselves for detailed recommendations.
+- If the script fails, report the error output verbatim.

docs/nous-wiki.md

@@ -4,6 +4,28 @@ After a Nous campaign finishes, its knowledge lives in raw `ledger.json` and
 `principles.json` files. The wiki skills extract that knowledge into structured,
 self-contained files and render them as interactive visualizations.
 
+## Quickstart
+
+After a campaign completes, run these in order:
+
+```bash
+# 1. Extract knowledge, index into registry, generate per-campaign visualization
+/post-campaign path/to/.nous/my-campaign
+
+# 2. Re-render the campaign visualization (e.g., after script updates)
+/visualize-campaign path/to/.nous/my-campaign
+
+# 3. (Optional) Render the cross-campaign knowledge graph
+/visualize-registry
+
+# 4. Get recommendations for the next campaign
+/suggest-next /path/to/repo "your research question"
+```
+
+`/post-campaign` already generates the campaign visualization and calls
+`/index-wiki` internally, so step 2 is only needed to re-render after script
+changes.
+
 ## Skills
 
 ### `/post-campaign`
@@ -162,6 +184,49 @@ wiki data, or any other existing files.
 
 ---
 
+### `/visualize-registry`
+
+Renders the full cross-campaign knowledge graph with heuristic opportunity
+scores. No LLM calls — runs in seconds.
+
+**Usage:**
+
+```
+/visualize-registry
+```
+
+**Prerequisites:** At least one campaign must be indexed via `/index-wiki`
+(i.e., `registry.json` must exist with at least one project).
+
+**What it reads:**
+
+| Source | What it uses |
+|--------|--------------|
+| `~/.nous/wiki/registry.json` | Projects, entities, entity clusters, campaigns |
+| Per-campaign wiki files | concepts.json, dead-ends.json, frontiers.json, interactions.json, summary.md |
+
+**What it writes:**
+
+| File | Contents |
+|------|----------|
+| `~/.nous/wiki/viz/registry.html` | Interactive cross-campaign knowledge graph |
+
+**Algorithm:**
+1. Verify registry exists
+2. Run `visualize_registry.py` (reads registry + campaign files, computes
+   heuristic scores, writes HTML)
+3. Open HTML in browser
+
+The Opportunities tab shows per-cluster research potential scored by frontier
+count, interaction count, and dead-end density. Each cluster card includes a
+copyable `/suggest-next` command for users who want detailed LLM-powered
+recommendations for that area.
+
+**What doesn't happen:** This skill never modifies registry.json, campaign
+data, or any other existing wiki files. No LLM calls are made.
+
+---
+
 ## Output Data Model
 
 All output lives under `~/.nous/wiki/` — a user-level directory outside any
@@ -185,7 +250,8 @@ repo. Each campaign gets its own subdirectory.
 │   └── campaigns/                   # Generated campaign configs
 │       └── <date>-<slug>-<N>.yaml
 └── viz/
-    └── <campaign-name>.html
+    ├── <campaign-name>.html         # Per-campaign graphs
+    └── registry.html                # Cross-campaign graph
 ```
 
 ### dead-ends.json
@@ -310,3 +376,36 @@ The HTML includes:
 - **Knowledge tab** — force-directed graph of entities, concepts, and parameters
 - **Insights tab** — dead-ends, frontiers, and interactions as browsable cards
 - **Summary tab** — the campaign's narrative summary with key principles
+
+### `scripts/visualize_registry.py`
+
+Generates an interactive cross-campaign HTML page from the registry and
+per-campaign wiki files.
+
+```bash
+python scripts/visualize_registry.py
+```
+
+Reads `~/.nous/wiki/registry.json` plus per-campaign files (concepts.json,
+dead-ends.json, frontiers.json, interactions.json, summary.md). Produces
+`~/.nous/wiki/viz/registry.html` and opens it in the default browser.
+
+The HTML includes:
+- **Graph tab** — force-directed graph of entities, concepts, and parameters across all campaigns, colored by campaign
+- **Opportunities tab** — per-cluster research potential scored by frontier count, interaction count, and dead-end density; each card includes a copyable `/suggest-next` command
+
+---
+
+## Concurrency
+
+**Do not run `/post-campaign` in parallel for multiple campaigns targeting the
+same project.** The skill writes to `~/.nous/wiki/campaigns/<name>/` and then
+invokes `/index-wiki`, which performs a read-modify-write cycle on
+`registry.json`. Running two `/post-campaign` invocations concurrently can
+cause one to overwrite the other's registry changes (last-writer-wins race
+condition).
+
+Safe patterns:
+- Run `/post-campaign` sequentially — finish one campaign before starting the next
+- Running `/post-campaign` for campaigns in *different* projects is safe (they write to different registry keys), but still shares the same `registry.json` file — so even cross-project parallelism should be avoided
+- `/visualize-campaign` and `/visualize-registry` are read-only and safe to run anytime