class-ai-agent 1.6.1 → 1.6.3

package/.kiro/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/.kiro/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 **`.cursor/references/ontosight.md`** for flags and troubleshooting.

package/.kiro/steering/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 **`.kiro/rules/ontosight.md`**) |
+| Visual exploration of a subgraph in browser | `npx @royalsolution/ontosight@0.2.0` (see **`.kiro/rules/ontosight.md`**) |
 | "Show/demonstrate impact of changing Z" | `codegraph_impact` → then OntoSight `--symbol Z` (see **`.kiro/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 **`.kiro/rules/ontosight.md`**.
+
 ### Tool parameters (do not mix)
 
 | Tool | Required arg | Optional cap | Wrong args → error |

package/.kiro/steering/kiro-overview.md

@@ -28,7 +28,7 @@ Supporting prompts: `debug`, `simplify`, `fix-issue`, `handoff`, `resume` in `.k
 - Prefer **tests first** and **small vertical slices** (see `.kiro/skills/incremental-implementation/`).
 - Use **`.kiro/references/`** for checklists (security, testing, performance, accessibility).
 - For **structural** code questions, prefer **CodeGraph** MCP tools per **`.kiro/steering/codegraph.md`**.
-- When the user wants a **visual call graph**, use **OntoSight CLI** per **`.kiro/steering/ontosight.md`** (`npx @royalsolution/ontosight`).
+- When the user wants a **visual call graph**, use **OntoSight CLI** per **`.kiro/steering/ontosight.md`** (`npx @royalsolution/ontosight@0.2.0`).
 
 ## Agents (personas)
 

package/.kiro/steering/ontosight.md

@@ -14,12 +14,50 @@ See **`.kiro/rules/codegraph.md`** for MCP usage and **`.kiro/references/ontosig
 | 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 **`.kiro/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`
+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.md

@@ -37,7 +37,7 @@ Project guidance for AI coding agents:
 ## Code intelligence
 
 - **CodeGraph MCP** (`codegraph_*`) — structural code search in chat; rules in each tool's `codegraph` rule file
-- **OntoSight** (`npx @royalsolution/ontosight`) — interactive call-graph visualization in the browser; rules in each tool's `ontosight` rule file
+- **OntoSight** (`npx @royalsolution/ontosight@0.2.0`) — interactive call-graph visualization in the browser; rules in each tool's `ontosight` rule file
 
 ## Maintainers
 

package/GEMINI.md

@@ -101,7 +101,7 @@ This project includes **[OntoSight](https://www.npmjs.com/package/@royalsolution
 | Setup reference | `.agents/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. 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/README.md

@@ -18,7 +18,7 @@ Open-source AI agent scaffolding by **Royal Solution** — use it in your own pr
   <a href="https://www.npmjs.com/package/class-ai-agent"><img src="https://img.shields.io/npm/v/class-ai-agent?label=npm&logo=npm&style=flat-square" alt="npm version" /></a>
   <img src="https://img.shields.io/badge/node-%3E%3D16.7-339933?logo=node.js&logoColor=white&style=flat-square" alt="Node.js 16.7+" />
   <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License MIT" />
-  <img src="https://img.shields.io/badge/version-1.6.1-blue?style=flat-square" alt="Version" />
+  <img src="https://img.shields.io/badge/version-1.6.3-blue?style=flat-square" alt="Version" />
 </p>
 
 </div>
@@ -58,7 +58,7 @@ Open-source AI agent scaffolding by **Royal Solution** — use it in your own pr
 | **13 topic rules** | Code style, security, API, DB, testing, git, and more (same ideas in both trees) |
 | **`npx` installer** | Copies the folders into your project in one command |
 | **CodeGraph** | MCP + usage rules for Cursor and Kiro; Antigravity via user `mcp_config.json`; local index via [CodeGraph](https://github.com/colbymchenry/codegraph) |
-| **OntoSight** | Visual call-graph UI via `npx @royalsolution/ontosight`; usage rules synced to all four agent trees |
+| **OntoSight** | Visual call-graph UI via `npx @royalsolution/ontosight@0.2.0`; usage rules synced to all four agent trees |
 | **Agent continuity** | Committed **`.agent/SESSION.md`** — `/resume` and `/handoff` across Cursor, Claude Code, Kiro, and Antigravity |
 
 Root **`AGENTS.md`** links hubs: **`.cursor/CURSOR.md`**, **`.kiro/KIRO.md`**, **`.claude/CLAUDE.md`**, **`GEMINI.md`**.
@@ -151,7 +151,9 @@ npm exec -- class-ai-agent --dir /path/to/your/project
 | **Kiro** | `.kiro/steering/ontosight.md`, `.kiro/references/ontosight.md` |
 | **Claude Code** | `.claude/rules/ontosight.md`, `.claude/references/ontosight.md` |
 | **Antigravity** | `.agent/rules/ontosight.md`, `.agents/references/ontosight.md` |
-| **Quick start** | `npx @royalsolution/ontosight .` (auto-inits CodeGraph index if missing) |
+| **Quick start** | `npx @royalsolution/ontosight@0.2.0 "<workspace-root>"` — pass absolute workspace root (not bare `.`); auto-inits CodeGraph index if missing |
+| **Project graph** | Preflight with `codegraph_status`; seeds from `codegraph_search` in same project — see `.cursor/rules/ontosight.mdc` |
+| **Pinned version** | `@royalsolution/ontosight@0.2.0` (`ontosight-codegraph` 0.2.0 on PyPI) |
 | **Requirements** | Node 20+, Python 3.11+, uv or pipx; shares `.codegraph/` with CodeGraph |
 | **Troubleshooting** | `.cursor/references/ontosight.md` |
 | **Impact demos** | `skills/ui-ux-pro-max/IMPACT-DEMO.md` — `codegraph_impact` → UX summary → graph |
@@ -159,19 +161,23 @@ npm exec -- class-ai-agent --dir /path/to/your/project
 Example agent workflow (feature area):
 
 ```text
-1. codegraph_context({ task: "auth flow", maxNodes: 20 })  → answer in chat
-2. npx @royalsolution/ontosight . --task "auth flow" --hops 2   → open graph for user
+0. codegraph_status({ projectPath: "<workspace-root>" })
+1. codegraph_context({ task: "auth flow", maxNodes: 20, projectPath: "<workspace-root>" })  → answer in chat
+2. npx @royalsolution/ontosight@0.2.0 "<workspace-root>" --task "auth flow" --hops 2   → open graph for user
 ```
 
 Example **impact analysis** demo:
 
 ```text
-1. codegraph_search({ query: "deleteUser" })
-2. codegraph_impact({ query: "deleteUser" })  → ranked blast radius in chat
+0. codegraph_status({ projectPath: "<workspace-root>" })
+1. codegraph_search({ query: "<symbol>", projectPath: "<workspace-root>" })
+2. codegraph_impact({ query: "<symbol>", projectPath: "<workspace-root>" })  → ranked blast radius in chat
 3. Follow IMPACT-DEMO.md (ui-ux-pro-max presentation)
-4. npx @royalsolution/ontosight . --symbol deleteUser --path src/services/ --hops 3
+4. npx @royalsolution/ontosight@0.2.0 "<workspace-root>" --symbol <name> --path <dir> --hops 3
 ```
 
+**Wrong graph in browser?** OntoSight defaults to shell `cwd` — always pass the absolute workspace root as `[project-path]`. See `.cursor/references/ontosight.md` troubleshooting.
+
 ---
 
 ## Overview
@@ -436,6 +442,18 @@ Ship thin end-to-end slices (DB + API + UI), not “all models first, then all r
 
 
 
+
+
+### 1.6.3 — 2026-06-19
+
+- Add **Project graph fidelity** rules for OntoSight — mandatory `codegraph_status` preflight, absolute workspace root as `[project-path]`, seed binding from CodeGraph MCP
+- Replace fragile bare `.` OntoSight examples with `<workspace-root>` across rules, references, IMPACT-DEMO, README, and CLI help
+- Add wrong-graph troubleshooting (foreign repo symbols, MCP/OntoSight path mismatch)
+
+### 1.6.2 — 2026-06-19
+
+- Pin agent OntoSight CLI invocations to **`@royalsolution/ontosight@0.2.0`** (latest; `ontosight-codegraph` 0.2.0)
+
 ### 1.6.1 — 2026-06-19
 
 - Add **impact analysis demonstration** workflow: `codegraph_impact` → UX summary → OntoSight graph
@@ -444,7 +462,7 @@ Ship thin end-to-end slices (DB + API + UI), not “all models first, then all r
 
 ### 1.6.0 — 2026-06-19
 
-- Integrate **[OntoSight](https://www.npmjs.com/package/@royalsolution/ontosight)** — visual CodeGraph call subgraphs via `npx @royalsolution/ontosight`
+- Integrate **[OntoSight](https://www.npmjs.com/package/@royalsolution/ontosight)** — visual CodeGraph call subgraphs via `npx @royalsolution/ontosight@0.2.0`
 - Add always-on `ontosight` rules and references synced to Cursor, Claude Code, Kiro, and Antigravity
 - Cross-link CodeGraph rules with OntoSight visualization workflows
 

package/bin/class-ai-agent.cjs

@@ -40,7 +40,9 @@ CodeGraph:
   (Node 20+ recommended). Set CODEGRAPH_SKIP_INIT=1 to skip indexing.
 
 OntoSight:
-  Visual call graphs: npx @royalsolution/ontosight .
+  Visual call graphs: npx @royalsolution/ontosight@0.2.0 "<workspace-root>"
+  Pass absolute workspace root as [project-path] (not bare .) so the browser loads this project's graph.
+  Preflight with codegraph_status; seed --symbol from codegraph_search in the same project.
   Agent rules installed at .cursor/rules/ontosight.mdc (and synced trees).
   Requires Node 20+, Python 3.11+, uv or pipx.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "class-ai-agent",
-  "version": "1.6.1",
+  "version": "1.6.3",
   "description": "Production-grade AI agent configuration for Claude Code, Cursor, Kiro & Antigravity",
   "license": "MIT",
   "repository": {