class-ai-agent 1.6.1 → 1.6.3

package/.agent/SESSION.md

@@ -46,6 +46,7 @@ Maintain and ship **class-ai-agent** — production-grade AI agent scaffolding f
 
 - Calling `codegraph_context` with `{ "query": "...", "limit": 15 }` → `task must be a non-empty string`.
 - CodeGraph MCP may need `projectPath` if workspace root is not detected.
+- OntoSight with bare `.` may load the wrong project's graph — pass absolute workspace root as `[project-path]`; run `codegraph_status` first.
 - CLI smoke test: `npm run test:cli`
 - `npx class-ai-agent` runs CodeGraph init by default; set `CODEGRAPH_SKIP_INIT=1` to skip.
 

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

@@ -28,7 +28,7 @@ Supporting workflows: `debug`, `simplify`, `fix-issue`, `handoff`, `resume` in `
 - 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`).
+- When the user wants a **visual call graph**, use **OntoSight CLI** per **`.agent/rules/ontosight.md`** (`npx @royalsolution/ontosight@0.2.0`).
 
 ## Agents (personas)
 

package/.agent/rules/codegraph.md

@@ -23,7 +23,7 @@ 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`**) |
+| Visual exploration of a subgraph in browser | `npx @royalsolution/ontosight@0.2.0` (see **`.agent/rules/ontosight.md`**) |
 | "Show/demonstrate impact of changing Z" | `codegraph_impact` → then OntoSight `--symbol Z` (see **`.agent/rules/ontosight.md`**) |
 
 ### Visualization
@@ -32,6 +32,8 @@ For interactive call-graph UI (user asks to "show the graph" or explore architec
 
 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.
 
+**Project graph fidelity:** OntoSight is a separate CLI — MCP `${workspaceFolder}` binding does not apply automatically. Pass the **same workspace root** to OntoSight's `[project-path]` as you use for `projectPath` on `codegraph_*` calls when MCP cwd detection is wrong. Run `codegraph_status` before opening OntoSight; seeds (`--symbol`, `--task`) must come from queries against that same index. See **Project graph fidelity** in **`.agent/rules/ontosight.md`**.
+
 ### Tool parameters (do not mix)
 
 | Tool | Required arg | Optional cap | Wrong args → error |

package/.agent/rules/ontosight.md

@@ -14,12 +14,50 @@ See **`.agent/rules/codegraph.md`** for MCP usage and **`.agents/references/onto
 | Goal | Use |
 |------|-----|
 | Find symbols, callers, traces, impact (text in chat) | `codegraph_*` MCP tools |
-| Visual exploration of a subgraph | `npx @royalsolution/ontosight` |
+| Visual exploration of a subgraph | `npx @royalsolution/ontosight@0.2.0` |
 | 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.
 
+### Project graph fidelity
+
+OntoSight reads nodes from `.codegraph/codegraph.db` under the **`[project-path]`** argument (default: shell `cwd`). The browser must show **this workspace's** project graph — never a foreign repo or auto-init index from the wrong directory.
+
+**Mandatory preflight** (before any OntoSight run):
+
+1. Resolve **workspace root** (Cursor `${workspaceFolder}` / absolute path from user context).
+2. `codegraph_status({ projectPath: "<workspace-root>" })` when MCP may be on wrong cwd; otherwise default.
+3. If index missing → `npx @colbymchenry/codegraph init -i` **in workspace root** (ask user on large repos).
+4. If MCP returns "wrong project" / path mismatch → pass `projectPath` on all subsequent `codegraph_*` calls.
+
+**Hard rule:** Do not open OntoSight until `.codegraph/codegraph.db` exists under the **target workspace root**.
+
+**Absolute project path** — never rely on bare `.` when workspace root is known:
+
+```bash
+# Required when workspace root is known
+npx @royalsolution/ontosight@0.2.0 "/absolute/path/to/workspace" \
+  --symbol <name> --path <dir>
+```
+
+Pass workspace root as the **first positional `[project-path]`** argument. Optionally set shell `cwd` to workspace root as well — but always pass the absolute path.
+
+**Seed binding** — seeds must come from the same project's CodeGraph index:
+
+| Seed mode | Requirement |
+|-----------|-------------|
+| `--symbol` | Name **must** come from `codegraph_search` / `codegraph_context` with the **same** `projectPath`; `--path` must match the directory prefix of the returned file path |
+| `--task` | Only after `codegraph_context({ task, maxNodes })`; prefer `--symbol` when user named a symbol |
+| Default (no seed) | Full-project exploration only; still require absolute workspace path |
+
+**Anti-patterns (explicit ban):**
+
+- Do not use README/doc example symbols (`view_graph`, `deleteUser`) unless `codegraph_search` confirms they exist in **this** project.
+- Do not run OntoSight from a subdirectory with bare `.` — auto-init may index the wrong tree.
+
+**After launch:** confirm OntoSight terminal output shows the correct **project path** and topology symbols under that project. If mismatch → stop and re-run with corrected absolute path.
+
 ### When to run OntoSight
 
 Run (or suggest) OntoSight when the user:
@@ -41,12 +79,13 @@ Do **not** run OntoSight to collect agent context — that duplicates CodeGraph
 
 **Workflow** (mandatory order):
 
-1. `codegraph_search({ query: "<symbol>" })` — confirm name, file, kind
-2. `codegraph_impact({ query: "<symbol>" })` — ranked blast radius (chat facts)
+0. `codegraph_status({ projectPath: "<workspace-root>" })` — verify index at workspace root
+1. `codegraph_search({ query: "<symbol>", projectPath: "<workspace-root>" })` — confirm name, file, kind
+2. `codegraph_impact({ query: "<symbol>", projectPath: "<workspace-root>" })` — 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`
+6. `npx @royalsolution/ontosight@0.2.0 "<workspace-root>" --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.
 
@@ -56,25 +95,29 @@ Do **not** run OntoSight to collect agent context — that duplicates CodeGraph
 
 **Symbol the user named:**
 
-1. `codegraph_search({ query: "<name>" })` → confirm file + kind
+0. `codegraph_status({ projectPath: "<workspace-root>" })`
+1. `codegraph_search({ query: "<name>", projectPath: "<workspace-root>" })` → confirm file + kind
 2. Summarize in chat
-3. `npx @royalsolution/ontosight . --symbol <name> --path <dir-from-search>`
+3. `npx @royalsolution/ontosight@0.2.0 "<workspace-root>" --symbol <name> --path <dir-from-search>`
 
 **Feature area ("how does auth work?"):**
 
-1. `codegraph_context({ task: "authentication flow", maxNodes: 20 })`
+0. `codegraph_status({ projectPath: "<workspace-root>" })`
+1. `codegraph_context({ task: "authentication flow", maxNodes: 20, projectPath: "<workspace-root>" })`
 2. Summarize key symbols in chat
-3. `npx @royalsolution/ontosight . --task "authentication flow" --hops 2 --max-nodes 200`
+3. `npx @royalsolution/ontosight@0.2.0 "<workspace-root>" --task "authentication flow" --hops 2 --max-nodes 200`
 
 **Large repo:** prefer `--path` or `--symbol` before raising `--max-nodes`.
 
 ### Commands
 
+Replace `<workspace-root>` with the absolute path to the open workspace (never bare `.` when root is known):
+
 ```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
+npx @royalsolution/ontosight@0.2.0 "<workspace-root>"
+npx @royalsolution/ontosight@0.2.0 "<workspace-root>" --symbol <name> --path <dir>
+npx @royalsolution/ontosight@0.2.0 "<workspace-root>" --task "auth flow" --hops 2 --max-nodes 200
+npx @royalsolution/ontosight@0.2.0 "<workspace-root>" --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.
@@ -83,7 +126,7 @@ Auto-creates the CodeGraph index when `.codegraph/codegraph.db` is missing (unle
 
 | Requirement | Notes |
 |-------------|-------|
-| Node 20+ | For `npx @royalsolution/ontosight` |
+| Node 20+ | For `npx @royalsolution/ontosight@0.2.0` |
 | 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 |
+| CodeGraph index | `.codegraph/codegraph.db` in workspace root |

package/.agents/references/codegraph.md

@@ -83,12 +83,14 @@ Example — correct:
 |-------|--------|
 | `task must be a non-empty string` | Use `task` (not `query`) on `codegraph_context`; use `maxNodes` (not `limit`). For `/resume`, read `.agent/SESSION.md` instead. |
 | MCP “not initialized” | Run `npx @colbymchenry/codegraph init -i` in project root |
+| MCP wrong project / path mismatch | Pass `projectPath: "<workspace-root>"` on all `codegraph_*` calls; use the same root for OntoSight `[project-path]` |
 | MCP not connecting | Reload Cursor; verify `.cursor/mcp.json`; test `npx @colbymchenry/codegraph serve --mcp` |
 | 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 |
+| OntoSight shows wrong project's graph | Pass absolute workspace root to OntoSight (not bare `.`); run `codegraph_status` first — see [`.cursor/references/ontosight.md`](ontosight.md) |
 
 ## 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).
+For interactive call-graph exploration in the browser, use **[OntoSight](https://www.npmjs.com/package/@royalsolution/ontosight)** (`npx @royalsolution/ontosight@0.2.0`). Gather facts with `codegraph_*` first; open OntoSight when the user wants a visual UI. Pass the **absolute workspace root** as `[project-path]` (not bare `.`) so the browser loads this project's graph. See [`.cursor/references/ontosight.md`](ontosight.md).
 
 Upstream: [colbymchenry/codegraph](https://github.com/colbymchenry/codegraph)

package/.agents/references/ontosight.md

@@ -2,6 +2,8 @@
 
 [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).
 
+**Recommended version:** `@royalsolution/ontosight@0.2.0` (pins PyPI `ontosight-codegraph` 0.2.0). Use unpinned `npx @royalsolution/ontosight@0.2.0` only when the user explicitly wants latest.
+
 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
@@ -13,17 +15,32 @@ OntoSight complements CodeGraph MCP — use `codegraph_*` for structural facts i
 | Kiro | `.kiro/steering/ontosight.md` | `.kiro/references/ontosight.md` |
 | Antigravity | `.agent/rules/ontosight.md` | `.agents/references/ontosight.md` |
 
+## Project graph fidelity
+
+OntoSight loads nodes from `.codegraph/codegraph.db` under **`[project-path]`** (default: shell `cwd`). To ensure the browser shows **this workspace's** graph:
+
+1. Resolve workspace root (absolute path).
+2. Run `codegraph_status({ projectPath: "<workspace-root>" })` before OntoSight.
+3. Pass **absolute workspace root** as `[project-path]` — never bare `.` when root is known.
+4. Seed `--symbol` / `--task` from `codegraph_*` queries using the **same** `projectPath`.
+5. After launch, verify terminal output: printed project path and topology symbols belong to this repo.
+
+See **Project graph fidelity** in [`.cursor/rules/ontosight.mdc`](../rules/ontosight.mdc).
+
 ## Quick start
 
+Replace `<workspace-root>` with the absolute path to the open workspace:
+
 ```bash
 # Full project — seeds from highest fan-in symbols
-npx @royalsolution/ontosight .
+npx @royalsolution/ontosight@0.2.0 "<workspace-root>"
 
 # Seed around a symbol (optionally scoped to a path)
-npx @royalsolution/ontosight . --symbol view_graph --path src/auth/
+# --symbol must exist in this project (confirm via codegraph_search first)
+npx @royalsolution/ontosight@0.2.0 "<workspace-root>" --symbol <name> --path src/auth/
 
 # Task-scoped subgraph (keyword FTS seeding)
-npx @royalsolution/ontosight . --task "auth flow" --hops 2 --max-nodes 200
+npx @royalsolution/ontosight@0.2.0 "<workspace-root>" --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`).
@@ -32,7 +49,7 @@ Auto-creates the CodeGraph index when `.codegraph/codegraph.db` is missing (unle
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `[project-path]` | Project root containing `.codegraph/` | `.` (cwd) |
+| `[project-path]` | Project root containing `.codegraph/` | `.` (cwd) — **prefer absolute workspace root** |
 | `--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) | — |
@@ -46,17 +63,19 @@ Auto-creates the CodeGraph index when `.codegraph/codegraph.db` is missing (unle
 ### Symbol the user named
 
 ```text
-1. codegraph_search({ query: "view_graph" })     → confirm file + kind
+0. codegraph_status({ projectPath: "<workspace-root>" })
+1. codegraph_search({ query: "<name>", projectPath: "<workspace-root>" })  → confirm file + kind
 2. Tell user what you found
-3. npx @royalsolution/ontosight . --symbol view_graph --path <dir-from-search>
+3. npx @royalsolution/ontosight@0.2.0 "<workspace-root>" --symbol <name> --path <dir-from-search>
 ```
 
 ### Feature area ("how does auth work?")
 
 ```text
-1. codegraph_context({ task: "authentication flow", maxNodes: 20 })
+0. codegraph_status({ projectPath: "<workspace-root>" })
+1. codegraph_context({ task: "authentication flow", maxNodes: 20, projectPath: "<workspace-root>" })
 2. Summarize key symbols in chat
-3. npx @royalsolution/ontosight . --task "authentication flow" --hops 2 --max-nodes 200
+3. npx @royalsolution/ontosight@0.2.0 "<workspace-root>" --task "authentication flow" --hops 2 --max-nodes 200
 ```
 
 ### Impact analysis demonstration
@@ -68,18 +87,19 @@ When the user wants to **know** or **see** impact (blast radius, what breaks, do
 **Workflow:**
 
 ```text
-1. codegraph_search({ query: "<symbol>" })     → confirm file + kind
-2. codegraph_impact({ query: "<symbol>" })     → ranked blast radius
+0. codegraph_status({ projectPath: "<workspace-root>" })
+1. codegraph_search({ query: "<symbol>", projectPath: "<workspace-root>" })  → confirm file + kind
+2. codegraph_impact({ query: "<symbol>", projectPath: "<workspace-root>" })  → 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
+6. npx @royalsolution/ontosight@0.2.0 "<workspace-root>" --symbol <name> --path <dir> --hops 3 --max-nodes 200
 ```
 
-**Example:**
+**Example** (replace paths and symbol with values from `codegraph_search` in **this** project):
 
 ```bash
-npx @royalsolution/ontosight . --symbol deleteUser --path src/services/ --hops 3 --max-nodes 200
+npx @royalsolution/ontosight@0.2.0 "/path/to/workspace" --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).
@@ -89,8 +109,9 @@ npx @royalsolution/ontosight . --symbol deleteUser --path src/services/ --hops 3
 ### Index missing
 
 ```bash
+cd "<workspace-root>"
 npx @colbymchenry/codegraph init -i
-# or let the OntoSight wrapper auto-init (default)
+# or let the OntoSight wrapper auto-init (default) — only when [project-path] is correct
 ```
 
 ## Environment variables
@@ -104,10 +125,10 @@ npx @colbymchenry/codegraph init -i
 
 | Requirement | Notes |
 |-------------|-------|
-| Node 20+ | For `npx @royalsolution/ontosight` |
+| Node 20+ | For `npx @royalsolution/ontosight@0.2.0` |
 | 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 |
+| CodeGraph index | `.codegraph/codegraph.db` in workspace root |
 
 ## What the user sees
 
@@ -115,11 +136,16 @@ npx @colbymchenry/codegraph init -i
 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).
 
+**Verify fidelity:** confirm the printed **project path** matches workspace root and topology symbols are files under that project — not another repo. If mismatch, stop and re-run with the corrected absolute path.
+
 ## Troubleshooting
 
 | Issue | Action |
 |-------|--------|
-| `CodeGraph index not found` | Run `npx @colbymchenry/codegraph init -i` or remove `ONTOSIGHT_SKIP_AUTO_INIT` |
+| Browser shows symbols from another repo | Re-run with absolute workspace root as `[project-path]`; delete stray `.codegraph/` in wrong cwd if auto-init ran there |
+| Empty or generic graph | Run `codegraph init -i` in workspace root; seed with `--symbol` from `codegraph_search` in this project |
+| MCP and OntoSight disagree | Align paths: same root for MCP `projectPath` and OntoSight `[project-path]` |
+| `CodeGraph index not found` | Run `npx @colbymchenry/codegraph init -i` in workspace root 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 |

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

@@ -46,7 +46,7 @@ Use for: summary-before-graph; tell the user what OntoSight is loading and what
 
 ## Chat summary template
 
-Present this **before** running `npx @royalsolution/ontosight`:
+Present this **before** running `npx @royalsolution/ontosight@0.2.0` (with absolute workspace root as `[project-path]`):
 
 ### 1. Seed
 
@@ -71,10 +71,10 @@ Group by risk: **direct callers** (highest) vs **transitive** (lower).
 
 ### 4. Action
 
-Short line: *"Opening interactive impact graph…"* then run:
+Short line: *"Opening interactive impact graph…"* then run (replace `<workspace-root>` with absolute workspace path):
 
 ```bash
-npx @royalsolution/ontosight . --symbol <name> --path <dir-from-search> --hops 3 --max-nodes 200
+npx @royalsolution/ontosight@0.2.0 "<workspace-root>" --symbol <name> --path <dir-from-search> --hops 3 --max-nodes 200
 ```
 
 ---
@@ -90,12 +90,13 @@ npx @royalsolution/ontosight . --symbol <name> --path <dir-from-search> --hops 3
 ## Full agent workflow
 
 ```text
-1. codegraph_search({ query: "<symbol>" })
-2. codegraph_impact({ query: "<symbol>" })
+0. codegraph_status({ projectPath: "<workspace-root>" })  → verify index at workspace root
+1. codegraph_search({ query: "<symbol>", projectPath: "<workspace-root>" })
+2. codegraph_impact({ query: "<symbol>", projectPath: "<workspace-root>" })
 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
+6. npx @royalsolution/ontosight@0.2.0 "<workspace-root>" --symbol <name> --path <dir> --hops 3 --max-nodes 200
 ```
 
 See **`.agents/references/ontosight.md`** for flags and troubleshooting.

package/.claude/CLAUDE.md

@@ -132,7 +132,7 @@ This project includes **[OntoSight](https://www.npmjs.com/package/@royalsolution
 | 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.
+Use `codegraph_*` MCP tools to gather structural facts in chat; run `npx @royalsolution/ontosight@0.2.0 .` 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.
 
 ---
 

package/.claude/references/ontosight.md

@@ -2,6 +2,8 @@
 
 [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).
 
+**Recommended version:** `@royalsolution/ontosight@0.2.0` (pins PyPI `ontosight-codegraph` 0.2.0). Use unpinned `npx @royalsolution/ontosight@0.2.0` only when the user explicitly wants latest.
+
 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
@@ -13,17 +15,32 @@ OntoSight complements CodeGraph MCP — use `codegraph_*` for structural facts i
 | Kiro | `.kiro/steering/ontosight.md` | `.kiro/references/ontosight.md` |
 | Antigravity | `.agent/rules/ontosight.md` | `.agents/references/ontosight.md` |
 
+## Project graph fidelity
+
+OntoSight loads nodes from `.codegraph/codegraph.db` under **`[project-path]`** (default: shell `cwd`). To ensure the browser shows **this workspace's** graph:
+
+1. Resolve workspace root (absolute path).
+2. Run `codegraph_status({ projectPath: "<workspace-root>" })` before OntoSight.
+3. Pass **absolute workspace root** as `[project-path]` — never bare `.` when root is known.
+4. Seed `--symbol` / `--task` from `codegraph_*` queries using the **same** `projectPath`.
+5. After launch, verify terminal output: printed project path and topology symbols belong to this repo.
+
+See **Project graph fidelity** in [`.cursor/rules/ontosight.mdc`](../rules/ontosight.mdc).
+
 ## Quick start
 
+Replace `<workspace-root>` with the absolute path to the open workspace:
+
 ```bash
 # Full project — seeds from highest fan-in symbols
-npx @royalsolution/ontosight .
+npx @royalsolution/ontosight@0.2.0 "<workspace-root>"
 
 # Seed around a symbol (optionally scoped to a path)
-npx @royalsolution/ontosight . --symbol view_graph --path src/auth/
+# --symbol must exist in this project (confirm via codegraph_search first)
+npx @royalsolution/ontosight@0.2.0 "<workspace-root>" --symbol <name> --path src/auth/
 
 # Task-scoped subgraph (keyword FTS seeding)
-npx @royalsolution/ontosight . --task "auth flow" --hops 2 --max-nodes 200
+npx @royalsolution/ontosight@0.2.0 "<workspace-root>" --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`).
@@ -32,7 +49,7 @@ Auto-creates the CodeGraph index when `.codegraph/codegraph.db` is missing (unle
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `[project-path]` | Project root containing `.codegraph/` | `.` (cwd) |
+| `[project-path]` | Project root containing `.codegraph/` | `.` (cwd) — **prefer absolute workspace root** |
 | `--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) | — |
@@ -46,17 +63,19 @@ Auto-creates the CodeGraph index when `.codegraph/codegraph.db` is missing (unle
 ### Symbol the user named
 
 ```text
-1. codegraph_search({ query: "view_graph" })     → confirm file + kind
+0. codegraph_status({ projectPath: "<workspace-root>" })
+1. codegraph_search({ query: "<name>", projectPath: "<workspace-root>" })  → confirm file + kind
 2. Tell user what you found
-3. npx @royalsolution/ontosight . --symbol view_graph --path <dir-from-search>
+3. npx @royalsolution/ontosight@0.2.0 "<workspace-root>" --symbol <name> --path <dir-from-search>
 ```
 
 ### Feature area ("how does auth work?")
 
 ```text
-1. codegraph_context({ task: "authentication flow", maxNodes: 20 })
+0. codegraph_status({ projectPath: "<workspace-root>" })
+1. codegraph_context({ task: "authentication flow", maxNodes: 20, projectPath: "<workspace-root>" })
 2. Summarize key symbols in chat
-3. npx @royalsolution/ontosight . --task "authentication flow" --hops 2 --max-nodes 200
+3. npx @royalsolution/ontosight@0.2.0 "<workspace-root>" --task "authentication flow" --hops 2 --max-nodes 200
 ```
 
 ### Impact analysis demonstration
@@ -68,18 +87,19 @@ When the user wants to **know** or **see** impact (blast radius, what breaks, do
 **Workflow:**
 
 ```text
-1. codegraph_search({ query: "<symbol>" })     → confirm file + kind
-2. codegraph_impact({ query: "<symbol>" })     → ranked blast radius
+0. codegraph_status({ projectPath: "<workspace-root>" })
+1. codegraph_search({ query: "<symbol>", projectPath: "<workspace-root>" })  → confirm file + kind
+2. codegraph_impact({ query: "<symbol>", projectPath: "<workspace-root>" })  → 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
+6. npx @royalsolution/ontosight@0.2.0 "<workspace-root>" --symbol <name> --path <dir> --hops 3 --max-nodes 200
 ```
 
-**Example:**
+**Example** (replace paths and symbol with values from `codegraph_search` in **this** project):
 
 ```bash
-npx @royalsolution/ontosight . --symbol deleteUser --path src/services/ --hops 3 --max-nodes 200
+npx @royalsolution/ontosight@0.2.0 "/path/to/workspace" --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).
@@ -89,8 +109,9 @@ npx @royalsolution/ontosight . --symbol deleteUser --path src/services/ --hops 3
 ### Index missing
 
 ```bash
+cd "<workspace-root>"
 npx @colbymchenry/codegraph init -i
-# or let the OntoSight wrapper auto-init (default)
+# or let the OntoSight wrapper auto-init (default) — only when [project-path] is correct
 ```
 
 ## Environment variables
@@ -104,10 +125,10 @@ npx @colbymchenry/codegraph init -i
 
 | Requirement | Notes |
 |-------------|-------|
-| Node 20+ | For `npx @royalsolution/ontosight` |
+| Node 20+ | For `npx @royalsolution/ontosight@0.2.0` |
 | 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 |
+| CodeGraph index | `.codegraph/codegraph.db` in workspace root |
 
 ## What the user sees
 
@@ -115,11 +136,16 @@ npx @colbymchenry/codegraph init -i
 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).
 
+**Verify fidelity:** confirm the printed **project path** matches workspace root and topology symbols are files under that project — not another repo. If mismatch, stop and re-run with the corrected absolute path.
+
 ## Troubleshooting
 
 | Issue | Action |
 |-------|--------|
-| `CodeGraph index not found` | Run `npx @colbymchenry/codegraph init -i` or remove `ONTOSIGHT_SKIP_AUTO_INIT` |
+| Browser shows symbols from another repo | Re-run with absolute workspace root as `[project-path]`; delete stray `.codegraph/` in wrong cwd if auto-init ran there |
+| Empty or generic graph | Run `codegraph init -i` in workspace root; seed with `--symbol` from `codegraph_search` in this project |
+| MCP and OntoSight disagree | Align paths: same root for MCP `projectPath` and OntoSight `[project-path]` |
+| `CodeGraph index not found` | Run `npx @colbymchenry/codegraph init -i` in workspace root 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 |

package/.claude/rules/codegraph.md

@@ -19,7 +19,7 @@ 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`**) |
+| Visual exploration of a subgraph in browser | `npx @royalsolution/ontosight@0.2.0` (see **`.claude/rules/ontosight.md`**) |
 | "Show/demonstrate impact of changing Z" | `codegraph_impact` → then OntoSight `--symbol Z` (see **`.claude/rules/ontosight.md`**) |
 
 ### Visualization
@@ -28,6 +28,8 @@ For interactive call-graph UI (user asks to "show the graph" or explore architec
 
 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.
 
+**Project graph fidelity:** OntoSight is a separate CLI — MCP `${workspaceFolder}` binding does not apply automatically. Pass the **same workspace root** to OntoSight's `[project-path]` as you use for `projectPath` on `codegraph_*` calls when MCP cwd detection is wrong. Run `codegraph_status` before opening OntoSight; seeds (`--symbol`, `--task`) must come from queries against that same index. See **Project graph fidelity** in **`.claude/rules/ontosight.md`**.
+
 ### Tool parameters (do not mix)
 
 | Tool | Required arg | Optional cap | Wrong args → error |