class-ai-agent 1.5.1 → 1.6.1

package/.agent/rules/antigravity-overview.md

@@ -24,10 +24,11 @@ Supporting workflows: `debug`, `simplify`, `fix-issue`, `handoff`, `resume` in `
 
 ## Mandatory standards
 
-- Follow **`.agent/rules/`** (`*.md` with YAML frontmatter). **`security.md`**, **`codegraph.md`**, and **`agent-continuity.md`** use `trigger: always_on`; others often use `trigger: glob`.
+- Follow **`.agent/rules/`** (`*.md` with YAML frontmatter). **`security.md`**, **`codegraph.md`**, **`ontosight.md`**, and **`agent-continuity.md`** use `trigger: always_on`; others often use `trigger: glob`.
 - Prefer **tests first** and **small vertical slices** (see `.agents/skills/incremental-implementation/`).
 - Use **`.agents/references/`** for checklists (security, testing, performance, accessibility).
 - For **structural** code questions, prefer **CodeGraph** MCP tools per **`.agent/rules/codegraph.md`**.
+- When the user wants a **visual call graph**, use **OntoSight CLI** per **`.agent/rules/ontosight.md`** (`npx @royalsolution/ontosight`).
 
 ## Agents (personas)
 

package/.agent/rules/codegraph.md

@@ -23,6 +23,14 @@ Use codegraph for **structural** questions — what calls what, what would break
 | "See several related symbols' source at once" | `codegraph_explore` |
 | "What files exist under path/" | `codegraph_files` |
 | "Is the index healthy?" | `codegraph_status` |
+| Visual exploration of a subgraph in browser | `npx @royalsolution/ontosight` (see **`.agent/rules/ontosight.md`**) |
+| "Show/demonstrate impact of changing Z" | `codegraph_impact` → then OntoSight `--symbol Z` (see **`.agent/rules/ontosight.md`**) |
+
+### Visualization
+
+For interactive call-graph UI (user asks to "show the graph" or explore architecture visually), use **OntoSight CLI** after gathering context with `codegraph_*` tools. See **`.agent/rules/ontosight.md`**.
+
+For **impact demonstration** requests ("show impact", "blast radius", "what breaks if I change X"), run `codegraph_impact` first, present a text summary, then open OntoSight — never stop at MCP text alone when the user wants to see or show impact.
 
 ### Tool parameters (do not mix)
 

package/.agent/rules/ontosight.md

@@ -0,0 +1,89 @@
+---
+trigger: always_on
+description: "OntoSight CLI — visualize CodeGraph call subgraphs in the browser"
+---
+
+## OntoSight
+
+[OntoSight](https://www.npmjs.com/package/@royalsolution/ontosight) visualizes CodeGraph call subgraphs in an interactive browser UI. It is **not** an MCP server — there are no `ontosight_*` tools. Use **CodeGraph MCP** (`codegraph_*`) to answer structural questions in chat; use **OntoSight CLI** when the user wants a visual, interactive call graph.
+
+See **`.agent/rules/codegraph.md`** for MCP usage and **`.agents/references/ontosight.md`** for full flags and troubleshooting.
+
+### CodeGraph MCP vs OntoSight
+
+| Goal | Use |
+|------|-----|
+| Find symbols, callers, traces, impact (text in chat) | `codegraph_*` MCP tools |
+| Visual exploration of a subgraph | `npx @royalsolution/ontosight` |
+| User says "show me the graph" | OntoSight CLI |
+| Impact / blast radius demonstration | `codegraph_impact` → summary → OntoSight CLI |
+
+Rule of thumb: gather facts with CodeGraph MCP; open OntoSight when visualization helps the human explore complexity you already identified.
+
+### When to run OntoSight
+
+Run (or suggest) OntoSight when the user:
+
+- Asks to visualize, show, or explore a call graph or architecture
+- Wants an interactive view after you surfaced symbols via `codegraph_search` / `codegraph_context`
+- Is doing onboarding or architecture review and benefits from a graph UI
+- Asks about **impact**, **blast radius**, or **what breaks** and wants to see or demonstrate scope (refactor, rename, delete)
+
+Do **not** run OntoSight to collect agent context — that duplicates CodeGraph MCP and blocks the terminal while the browser is open.
+
+### Impact analysis demonstration
+
+**Triggers** — open the graph, not only text:
+
+- "impact", "blast radius", "what breaks", "what would break", "downstream", "affected by"
+- "show impact", "demonstrate impact", "visualize impact"
+- User is about to refactor, rename, or delete a symbol and wants to see scope
+
+**Workflow** (mandatory order):
+
+1. `codegraph_search({ query: "<symbol>" })` — confirm name, file, kind
+2. `codegraph_impact({ query: "<symbol>" })` — ranked blast radius (chat facts)
+3. Read **`.agents/skills/ui-ux-pro-max/IMPACT-DEMO.md`** — presentation checklist (use your tool's skills path: `.agents/skills/`, `.agents/skills/`, `.agents/skills/`)
+4. Optional: run ui-ux-pro-max searches from the playbook for chart/UX framing
+5. Summarize in chat: seed symbol, top impacted callers, risk tier, what the graph will highlight
+6. `npx @royalsolution/ontosight . --symbol <name> --path <dir> --hops 3 --max-nodes 200`
+
+**Hop guidance:** use `--hops 3` (or `4` for deep trees) for impact demos; prefer `--path` over raising `--max-nodes` when truncated.
+
+**UX rule:** always give a **text summary before** opening the browser (progressive disclosure); include a **ranked table** of top impacted symbols as an accessible alternative to the graph alone.
+
+### Suggested workflows
+
+**Symbol the user named:**
+
+1. `codegraph_search({ query: "<name>" })` → confirm file + kind
+2. Summarize in chat
+3. `npx @royalsolution/ontosight . --symbol <name> --path <dir-from-search>`
+
+**Feature area ("how does auth work?"):**
+
+1. `codegraph_context({ task: "authentication flow", maxNodes: 20 })`
+2. Summarize key symbols in chat
+3. `npx @royalsolution/ontosight . --task "authentication flow" --hops 2 --max-nodes 200`
+
+**Large repo:** prefer `--path` or `--symbol` before raising `--max-nodes`.
+
+### Commands
+
+```bash
+npx @royalsolution/ontosight .
+npx @royalsolution/ontosight . --symbol <name> --path <dir>
+npx @royalsolution/ontosight . --task "auth flow" --hops 2 --max-nodes 200
+npx @royalsolution/ontosight . --symbol <name> --path <dir> --hops 3 --max-nodes 200
+```
+
+Auto-creates the CodeGraph index when `.codegraph/codegraph.db` is missing (unless `ONTOSIGHT_SKIP_AUTO_INIT=1`). Ask the user before auto-init on very large repos.
+
+### Prerequisites
+
+| Requirement | Notes |
+|-------------|-------|
+| Node 20+ | For `npx @royalsolution/ontosight` |
+| Python 3.11+ | Used by `ontosight-codegraph` |
+| uv (recommended) or pipx | Wrapper tries `uvx` first, then `pipx run` |
+| CodeGraph index | `.codegraph/codegraph.db` in project root |

package/.agents/references/codegraph.md

@@ -87,4 +87,8 @@ Example — correct:
 | Stale symbols after edit | Wait ~2s for watcher sync, or check staleness banner in tool output |
 | Init failed during install | Run `npx @colbymchenry/codegraph init -i` manually |
 
+## Visualization (OntoSight)
+
+For interactive call-graph exploration in the browser, use **[OntoSight](https://www.npmjs.com/package/@royalsolution/ontosight)** (`npx @royalsolution/ontosight`). Gather facts with `codegraph_*` first; open OntoSight when the user wants a visual UI. See [`.cursor/references/ontosight.md`](ontosight.md).
+
 Upstream: [colbymchenry/codegraph](https://github.com/colbymchenry/codegraph)

package/.agents/references/ontosight.md

@@ -0,0 +1,128 @@
+# OntoSight reference
+
+[OntoSight](https://www.npmjs.com/package/@royalsolution/ontosight) visualizes [CodeGraph](https://github.com/colbymchenry/codegraph) call subgraphs in an interactive browser UI. **class-ai-agent** installs usage rules across all four agent trees; invocation is via `npx` (no npm dependency).
+
+OntoSight complements CodeGraph MCP — use `codegraph_*` for structural facts in chat; use OntoSight when the user wants visual exploration. See also [`.cursor/references/codegraph.md`](codegraph.md).
+
+## Per-tool wiring
+
+| Tool | Rules | Reference |
+|------|-------|-----------|
+| Cursor | `.cursor/rules/ontosight.mdc` | `.cursor/references/ontosight.md` |
+| Claude Code | `.claude/rules/ontosight.md` | `.claude/references/ontosight.md` |
+| Kiro | `.kiro/steering/ontosight.md` | `.kiro/references/ontosight.md` |
+| Antigravity | `.agent/rules/ontosight.md` | `.agents/references/ontosight.md` |
+
+## Quick start
+
+```bash
+# Full project — seeds from highest fan-in symbols
+npx @royalsolution/ontosight .
+
+# Seed around a symbol (optionally scoped to a path)
+npx @royalsolution/ontosight . --symbol view_graph --path src/auth/
+
+# Task-scoped subgraph (keyword FTS seeding)
+npx @royalsolution/ontosight . --task "auth flow" --hops 2 --max-nodes 200
+```
+
+Auto-creates the CodeGraph index when `.codegraph/codegraph.db` is missing (unless `ONTOSIGHT_SKIP_AUTO_INIT=1`).
+
+## Flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `[project-path]` | Project root containing `.codegraph/` | `.` (cwd) |
+| `--path <dir>` | Limit symbols to files under this path | — |
+| `--symbol <name>` | Seed symbol for BFS subgraph expansion | auto (fan-in) |
+| `--task <text>` | Natural-language seed (keyword match) | — |
+| `--hops <n>` | BFS hop depth | `2` |
+| `--max-nodes <n>` | Cap subgraph size | `200` |
+
+`--symbol` and `--task` are mutually exclusive seeds; `--path` narrows either.
+
+## Suggested agent workflows
+
+### Symbol the user named
+
+```text
+1. codegraph_search({ query: "view_graph" })     → confirm file + kind
+2. Tell user what you found
+3. npx @royalsolution/ontosight . --symbol view_graph --path <dir-from-search>
+```
+
+### Feature area ("how does auth work?")
+
+```text
+1. codegraph_context({ task: "authentication flow", maxNodes: 20 })
+2. Summarize key symbols in chat
+3. npx @royalsolution/ontosight . --task "authentication flow" --hops 2 --max-nodes 200
+```
+
+### Impact analysis demonstration
+
+When the user wants to **know** or **see** impact (blast radius, what breaks, downstream callers):
+
+**Triggers:** "impact", "blast radius", "what breaks", "what would break", "downstream", "affected by", "show impact", "demonstrate impact", "visualize impact"; or user is about to refactor/rename/delete a symbol.
+
+**Workflow:**
+
+```text
+1. codegraph_search({ query: "<symbol>" })     → confirm file + kind
+2. codegraph_impact({ query: "<symbol>" })     → ranked blast radius
+3. Read skills/ui-ux-pro-max/IMPACT-DEMO.md  → UX presentation checklist
+4. Optional: ui-ux-pro-max chart/ux searches (see playbook)
+5. Summarize in chat (seed, ranked table, what graph shows)
+6. npx @royalsolution/ontosight . --symbol <name> --path <dir> --hops 3 --max-nodes 200
+```
+
+**Example:**
+
+```bash
+npx @royalsolution/ontosight . --symbol deleteUser --path src/services/ --hops 3 --max-nodes 200
+```
+
+**UX:** Always text summary before opening the browser; include a ranked table of top impacted symbols (accessible alternative to graph-only). See [IMPACT-DEMO.md](../skills/ui-ux-pro-max/IMPACT-DEMO.md).
+
+**Truncated subgraph:** narrow `--path` or lower `--hops` before raising `--max-nodes`.
+
+### Index missing
+
+```bash
+npx @colbymchenry/codegraph init -i
+# or let the OntoSight wrapper auto-init (default)
+```
+
+## Environment variables
+
+| Variable | Effect |
+|----------|--------|
+| `ONTOSIGHT_SKIP_AUTO_INIT=1` | Fail if `.codegraph/codegraph.db` missing instead of running init |
+| `ONTOSIGHT_CODEGRAPH_VERSION` | Pin PyPI `ontosight-codegraph` version |
+
+## Requirements
+
+| Requirement | Notes |
+|-------------|-------|
+| Node 20+ | For `npx @royalsolution/ontosight` |
+| Python 3.11+ | Used by `ontosight-codegraph` |
+| uv (recommended) or pipx | Wrapper tries `uvx` first, then `pipx run` |
+| CodeGraph index | `.codegraph/codegraph.db` in project root |
+
+## What the user sees
+
+1. Terminal prints project path, seed, hops/max-nodes, and a topology table (critical / hub nodes).
+2. OntoSight opens in the browser with the call subgraph, critical-node highlights, and a CodeGraph query panel for live reloads.
+3. Process stays running until the user closes the server (Ctrl+C in terminal).
+
+## Troubleshooting
+
+| Issue | Action |
+|-------|--------|
+| `CodeGraph index not found` | Run `npx @colbymchenry/codegraph init -i` or remove `ONTOSIGHT_SKIP_AUTO_INIT` |
+| `Neither uv nor pipx found` | Install uv: `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
+| Subgraph truncated warning | Add `--symbol`, `--task`, or `--path`; lower scope before raising `--max-nodes` |
+| Stale symbols after edits | Wait ~2s for CodeGraph watcher sync, or re-run init |
+| Agent needs facts, not UI | Use `codegraph_*` MCP tools instead |
+
+Upstream: [@royalsolution/ontosight](https://www.npmjs.com/package/@royalsolution/ontosight)

package/.agents/skills/ui-ux-pro-max/IMPACT-DEMO.md

@@ -0,0 +1,101 @@
+# Impact analysis demonstration — UX playbook
+
+Use this playbook when presenting **CodeGraph impact analysis** with an **OntoSight** graph demo. It extends the [ui-ux-pro-max SKILL](SKILL.md) for a specific agent workflow — not a full design-system pass.
+
+**Skill path by tool:** `.agents/skills/ui-ux-pro-max/`, `.agents/skills/ui-ux-pro-max/`, `.agents/skills/ui-ux-pro-max/`, `.agents/skills/ui-ux-pro-max/`
+
+---
+
+## When to use
+
+User asks about blast radius, what breaks, downstream impact, or wants to **see** / **show** / **demonstrate** impact before a refactor, rename, or delete.
+
+Pair with **`.agent/rules/ontosight.md`** (or synced `ontosight` rule in your tool tree).
+
+---
+
+## ui-ux-pro-max searches (optional, recommended)
+
+Run from project root. Adjust the skills path to match your tool.
+
+### Network graph UX
+
+```bash
+python3 .agents/skills/ui-ux-pro-max/scripts/search.py "relationship connection network graph" --domain chart
+```
+
+Use for: drilldown + hover expectations; provide an adjacency-list or ranked table alternative (network graphs are poor for screen-reader-only users).
+
+### Impact tier framing
+
+```bash
+python3 .agents/skills/ui-ux-pro-max/scripts/search.py "root cause decomposition hierarchy drill-down" --domain chart
+```
+
+Use for: grouping impact into tiers (direct callers vs transitive) in chat before opening the graph.
+
+### Progressive disclosure
+
+```bash
+python3 .agents/skills/ui-ux-pro-max/scripts/search.py "progressive disclosure loading feedback" --domain ux
+```
+
+Use for: summary-before-graph; tell the user what OntoSight is loading and what they will see.
+
+---
+
+## Chat summary template
+
+Present this **before** running `npx @royalsolution/ontosight`:
+
+### 1. Seed
+
+- Symbol name, kind (function, class, …), file path
+
+### 2. Blast radius
+
+Top 5–10 from `codegraph_impact`, in a **ranked table**:
+
+| Rank | Symbol | File | Relationship |
+|------|--------|------|--------------|
+| 1 | … | … | direct caller |
+| 2 | … | … | transitive |
+
+Group by risk: **direct callers** (highest) vs **transitive** (lower).
+
+### 3. What the graph shows
+
+- Seed node and `--hops` depth (typically 3 for impact demos)
+- Note that OntoSight highlights critical / hub nodes in the topology table
+- Mention interactive pan, zoom, and live CodeGraph re-query in the browser
+
+### 4. Action
+
+Short line: *"Opening interactive impact graph…"* then run:
+
+```bash
+npx @royalsolution/ontosight . --symbol <name> --path <dir-from-search> --hops 3 --max-nodes 200
+```
+
+---
+
+## Accessibility notes
+
+- **Always** include the ranked table — graph-only answers fail accessibility guidance for network visualizations.
+- Keep table columns sortable by impact rank when possible in prose.
+- If subgraph truncates, say so and offer a narrower `--path` before raising `--max-nodes`.
+
+---
+
+## Full agent workflow
+
+```text
+1. codegraph_search({ query: "<symbol>" })
+2. codegraph_impact({ query: "<symbol>" })
+3. Read this file (IMPACT-DEMO.md)
+4. Optional: ui-ux-pro-max chart/ux searches above
+5. Chat summary (template sections 1–3)
+6. npx @royalsolution/ontosight . --symbol <name> --path <dir> --hops 3 --max-nodes 200
+```
+
+See **`.agents/references/ontosight.md`** for flags and troubleshooting.

package/.claude/CLAUDE.md

@@ -97,6 +97,7 @@ All rules in `.claude/rules/` are **mandatory** and must be followed:
 | `git-workflow.md` | Branching strategy, conventional commits |
 | `agent-continuity.md` | Session handoff via `.agent/SESSION.md` |
 | `codegraph.md` | CodeGraph MCP usage; when to use `codegraph_*` tools |
+| `ontosight.md` | OntoSight CLI for visual call graphs |
 
 ---
 
@@ -121,6 +122,20 @@ Then in each project: `codegraph init -i` (class-ai-agent may run this on instal
 
 ---
 
+## Code visualization (OntoSight)
+
+This project includes **[OntoSight](https://www.npmjs.com/package/@royalsolution/ontosight)** for interactive CodeGraph call subgraphs in the browser.
+
+| Item | Location |
+|------|----------|
+| Usage rules | `.claude/rules/ontosight.md` |
+| Setup reference | `.claude/references/ontosight.md` |
+| Shared index | `.codegraph/` (same as CodeGraph) |
+
+Use `codegraph_*` MCP tools to gather structural facts in chat; run `npx @royalsolution/ontosight .` when the user wants a visual call graph. For **impact analysis demos**, follow `skills/ui-ux-pro-max/IMPACT-DEMO.md` (search → `codegraph_impact` → summary → graph). Requires Node 20+, Python 3.11+, and uv or pipx.
+
+---
+
 ## Available Agents
 
 Invoke the right agent for each task type:
@@ -178,6 +193,7 @@ Quick references in `.claude/references/`:
 | `performance-checklist.md` | Core Web Vitals, optimization |
 | `accessibility-checklist.md` | WCAG 2.1 AA compliance |
 | `codegraph.md` | CodeGraph install (Claude Code) and Cursor MCP notes |
+| `ontosight.md` | OntoSight CLI for visual call graphs |
 | `agent-continuity.md` | Session handoff and `/resume` / `/handoff` |
 | `supabase.md` | Supabase skills, MCP OAuth, secrets |
 

package/.claude/references/ontosight.md

@@ -0,0 +1,128 @@
+# OntoSight reference
+
+[OntoSight](https://www.npmjs.com/package/@royalsolution/ontosight) visualizes [CodeGraph](https://github.com/colbymchenry/codegraph) call subgraphs in an interactive browser UI. **class-ai-agent** installs usage rules across all four agent trees; invocation is via `npx` (no npm dependency).
+
+OntoSight complements CodeGraph MCP — use `codegraph_*` for structural facts in chat; use OntoSight when the user wants visual exploration. See also [`.cursor/references/codegraph.md`](codegraph.md).
+
+## Per-tool wiring
+
+| Tool | Rules | Reference |
+|------|-------|-----------|
+| Cursor | `.cursor/rules/ontosight.mdc` | `.cursor/references/ontosight.md` |
+| Claude Code | `.claude/rules/ontosight.md` | `.claude/references/ontosight.md` |
+| Kiro | `.kiro/steering/ontosight.md` | `.kiro/references/ontosight.md` |
+| Antigravity | `.agent/rules/ontosight.md` | `.agents/references/ontosight.md` |
+
+## Quick start
+
+```bash
+# Full project — seeds from highest fan-in symbols
+npx @royalsolution/ontosight .
+
+# Seed around a symbol (optionally scoped to a path)
+npx @royalsolution/ontosight . --symbol view_graph --path src/auth/
+
+# Task-scoped subgraph (keyword FTS seeding)
+npx @royalsolution/ontosight . --task "auth flow" --hops 2 --max-nodes 200
+```
+
+Auto-creates the CodeGraph index when `.codegraph/codegraph.db` is missing (unless `ONTOSIGHT_SKIP_AUTO_INIT=1`).
+
+## Flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `[project-path]` | Project root containing `.codegraph/` | `.` (cwd) |
+| `--path <dir>` | Limit symbols to files under this path | — |
+| `--symbol <name>` | Seed symbol for BFS subgraph expansion | auto (fan-in) |
+| `--task <text>` | Natural-language seed (keyword match) | — |
+| `--hops <n>` | BFS hop depth | `2` |
+| `--max-nodes <n>` | Cap subgraph size | `200` |
+
+`--symbol` and `--task` are mutually exclusive seeds; `--path` narrows either.
+
+## Suggested agent workflows
+
+### Symbol the user named
+
+```text
+1. codegraph_search({ query: "view_graph" })     → confirm file + kind
+2. Tell user what you found
+3. npx @royalsolution/ontosight . --symbol view_graph --path <dir-from-search>
+```
+
+### Feature area ("how does auth work?")
+
+```text
+1. codegraph_context({ task: "authentication flow", maxNodes: 20 })
+2. Summarize key symbols in chat
+3. npx @royalsolution/ontosight . --task "authentication flow" --hops 2 --max-nodes 200
+```
+
+### Impact analysis demonstration
+
+When the user wants to **know** or **see** impact (blast radius, what breaks, downstream callers):
+
+**Triggers:** "impact", "blast radius", "what breaks", "what would break", "downstream", "affected by", "show impact", "demonstrate impact", "visualize impact"; or user is about to refactor/rename/delete a symbol.
+
+**Workflow:**
+
+```text
+1. codegraph_search({ query: "<symbol>" })     → confirm file + kind
+2. codegraph_impact({ query: "<symbol>" })     → ranked blast radius
+3. Read skills/ui-ux-pro-max/IMPACT-DEMO.md  → UX presentation checklist
+4. Optional: ui-ux-pro-max chart/ux searches (see playbook)
+5. Summarize in chat (seed, ranked table, what graph shows)
+6. npx @royalsolution/ontosight . --symbol <name> --path <dir> --hops 3 --max-nodes 200
+```
+
+**Example:**
+
+```bash
+npx @royalsolution/ontosight . --symbol deleteUser --path src/services/ --hops 3 --max-nodes 200
+```
+
+**UX:** Always text summary before opening the browser; include a ranked table of top impacted symbols (accessible alternative to graph-only). See [IMPACT-DEMO.md](../skills/ui-ux-pro-max/IMPACT-DEMO.md).
+
+**Truncated subgraph:** narrow `--path` or lower `--hops` before raising `--max-nodes`.
+
+### Index missing
+
+```bash
+npx @colbymchenry/codegraph init -i
+# or let the OntoSight wrapper auto-init (default)
+```
+
+## Environment variables
+
+| Variable | Effect |
+|----------|--------|
+| `ONTOSIGHT_SKIP_AUTO_INIT=1` | Fail if `.codegraph/codegraph.db` missing instead of running init |
+| `ONTOSIGHT_CODEGRAPH_VERSION` | Pin PyPI `ontosight-codegraph` version |
+
+## Requirements
+
+| Requirement | Notes |
+|-------------|-------|
+| Node 20+ | For `npx @royalsolution/ontosight` |
+| Python 3.11+ | Used by `ontosight-codegraph` |
+| uv (recommended) or pipx | Wrapper tries `uvx` first, then `pipx run` |
+| CodeGraph index | `.codegraph/codegraph.db` in project root |
+
+## What the user sees
+
+1. Terminal prints project path, seed, hops/max-nodes, and a topology table (critical / hub nodes).
+2. OntoSight opens in the browser with the call subgraph, critical-node highlights, and a CodeGraph query panel for live reloads.
+3. Process stays running until the user closes the server (Ctrl+C in terminal).
+
+## Troubleshooting
+
+| Issue | Action |
+|-------|--------|
+| `CodeGraph index not found` | Run `npx @colbymchenry/codegraph init -i` or remove `ONTOSIGHT_SKIP_AUTO_INIT` |
+| `Neither uv nor pipx found` | Install uv: `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
+| Subgraph truncated warning | Add `--symbol`, `--task`, or `--path`; lower scope before raising `--max-nodes` |
+| Stale symbols after edits | Wait ~2s for CodeGraph watcher sync, or re-run init |
+| Agent needs facts, not UI | Use `codegraph_*` MCP tools instead |
+
+Upstream: [@royalsolution/ontosight](https://www.npmjs.com/package/@royalsolution/ontosight)

package/.claude/rules/codegraph.md

@@ -19,6 +19,14 @@ Use codegraph for **structural** questions — what calls what, what would break
 | "See several related symbols' source at once" | `codegraph_explore` |
 | "What files exist under path/" | `codegraph_files` |
 | "Is the index healthy?" | `codegraph_status` |
+| Visual exploration of a subgraph in browser | `npx @royalsolution/ontosight` (see **`.claude/rules/ontosight.md`**) |
+| "Show/demonstrate impact of changing Z" | `codegraph_impact` → then OntoSight `--symbol Z` (see **`.claude/rules/ontosight.md`**) |
+
+### Visualization
+
+For interactive call-graph UI (user asks to "show the graph" or explore architecture visually), use **OntoSight CLI** after gathering context with `codegraph_*` tools. See **`.claude/rules/ontosight.md`**.
+
+For **impact demonstration** requests ("show impact", "blast radius", "what breaks if I change X"), run `codegraph_impact` first, present a text summary, then open OntoSight — never stop at MCP text alone when the user wants to see or show impact.
 
 ### Tool parameters (do not mix)
 

package/.claude/rules/ontosight.md

@@ -0,0 +1,85 @@
+
+## OntoSight
+
+[OntoSight](https://www.npmjs.com/package/@royalsolution/ontosight) visualizes CodeGraph call subgraphs in an interactive browser UI. It is **not** an MCP server — there are no `ontosight_*` tools. Use **CodeGraph MCP** (`codegraph_*`) to answer structural questions in chat; use **OntoSight CLI** when the user wants a visual, interactive call graph.
+
+See **`.claude/rules/codegraph.md`** for MCP usage and **`.claude/references/ontosight.md`** for full flags and troubleshooting.
+
+### CodeGraph MCP vs OntoSight
+
+| Goal | Use |
+|------|-----|
+| Find symbols, callers, traces, impact (text in chat) | `codegraph_*` MCP tools |
+| Visual exploration of a subgraph | `npx @royalsolution/ontosight` |
+| User says "show me the graph" | OntoSight CLI |
+| Impact / blast radius demonstration | `codegraph_impact` → summary → OntoSight CLI |
+
+Rule of thumb: gather facts with CodeGraph MCP; open OntoSight when visualization helps the human explore complexity you already identified.
+
+### When to run OntoSight
+
+Run (or suggest) OntoSight when the user:
+
+- Asks to visualize, show, or explore a call graph or architecture
+- Wants an interactive view after you surfaced symbols via `codegraph_search` / `codegraph_context`
+- Is doing onboarding or architecture review and benefits from a graph UI
+- Asks about **impact**, **blast radius**, or **what breaks** and wants to see or demonstrate scope (refactor, rename, delete)
+
+Do **not** run OntoSight to collect agent context — that duplicates CodeGraph MCP and blocks the terminal while the browser is open.
+
+### Impact analysis demonstration
+
+**Triggers** — open the graph, not only text:
+
+- "impact", "blast radius", "what breaks", "what would break", "downstream", "affected by"
+- "show impact", "demonstrate impact", "visualize impact"
+- User is about to refactor, rename, or delete a symbol and wants to see scope
+
+**Workflow** (mandatory order):
+
+1. `codegraph_search({ query: "<symbol>" })` — confirm name, file, kind
+2. `codegraph_impact({ query: "<symbol>" })` — ranked blast radius (chat facts)
+3. Read **`.claude/skills/ui-ux-pro-max/IMPACT-DEMO.md`** — presentation checklist (use your tool's skills path: `.claude/skills/`, `.kiro/skills/`, `.agents/skills/`)
+4. Optional: run ui-ux-pro-max searches from the playbook for chart/UX framing
+5. Summarize in chat: seed symbol, top impacted callers, risk tier, what the graph will highlight
+6. `npx @royalsolution/ontosight . --symbol <name> --path <dir> --hops 3 --max-nodes 200`
+
+**Hop guidance:** use `--hops 3` (or `4` for deep trees) for impact demos; prefer `--path` over raising `--max-nodes` when truncated.
+
+**UX rule:** always give a **text summary before** opening the browser (progressive disclosure); include a **ranked table** of top impacted symbols as an accessible alternative to the graph alone.
+
+### Suggested workflows
+
+**Symbol the user named:**
+
+1. `codegraph_search({ query: "<name>" })` → confirm file + kind
+2. Summarize in chat
+3. `npx @royalsolution/ontosight . --symbol <name> --path <dir-from-search>`
+
+**Feature area ("how does auth work?"):**
+
+1. `codegraph_context({ task: "authentication flow", maxNodes: 20 })`
+2. Summarize key symbols in chat
+3. `npx @royalsolution/ontosight . --task "authentication flow" --hops 2 --max-nodes 200`
+
+**Large repo:** prefer `--path` or `--symbol` before raising `--max-nodes`.
+
+### Commands
+
+```bash
+npx @royalsolution/ontosight .
+npx @royalsolution/ontosight . --symbol <name> --path <dir>
+npx @royalsolution/ontosight . --task "auth flow" --hops 2 --max-nodes 200
+npx @royalsolution/ontosight . --symbol <name> --path <dir> --hops 3 --max-nodes 200
+```
+
+Auto-creates the CodeGraph index when `.codegraph/codegraph.db` is missing (unless `ONTOSIGHT_SKIP_AUTO_INIT=1`). Ask the user before auto-init on very large repos.
+
+### Prerequisites
+
+| Requirement | Notes |
+|-------------|-------|
+| Node 20+ | For `npx @royalsolution/ontosight` |
+| Python 3.11+ | Used by `ontosight-codegraph` |
+| uv (recommended) or pipx | Wrapper tries `uvx` first, then `pipx run` |
+| CodeGraph index | `.codegraph/codegraph.db` in project root |