Skip to content

Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.

docs: unify README into single cohesive document with screenshots

FABIOTESS613a6ce3b6a5
diff --git a/README.md b/README.md
index f2d139aa..06916209 100644
--- a/README.md
+++ b/README.md
@@ -7,29 +7,30 @@
[![PitchHut](https://img.shields.io/badge/PitchHut-open--ontologies-orange)](https://www.pitchhut.com/project/open-ontologies-mcp)
[![ClawHub Skill](https://img.shields.io/badge/ClawHub-open--ontologies-7c3aed)](https://clawhub.ai/fabio-rovai/open-ontologies)
-A Terraforming MCP for Knowledge Graphs: validate, classify, and govern AI-generated ontologies.
+A Terraforming MCP for Knowledge Graphs — validate, classify, and govern AI-generated ontologies.
-Open Ontologies is a standalone MCP server and CLI for AI-native ontology engineering. It exposes 42 tools and 5 workflow prompts that let Claude validate, query, diff, lint, version, and persist RDF/OWL ontologies using an in-memory Oxigraph triple store — plus plan changes, detect drift, enforce design patterns, monitor health, align ontologies, track lineage, and learn from user feedback.
+Open Ontologies is a **Rust MCP server** and **desktop Studio** for AI-native ontology engineering. It exposes 42 tools that let Claude (or any MCP client) build, validate, query, diff, lint, version, reason over, align, and persist RDF/OWL ontologies using an in-memory Oxigraph triple store — with Terraform-style lifecycle management, clinical crosswalks, semantic embeddings, and a full audit trail.
-Written in Rust, ships as a single binary. No JVM, no Protégé, no GUI.
+The **Studio** is a Tauri desktop app that wraps the engine in a visual environment: 3D force-directed graph, AI chat panel, Protégé-style property inspector, lineage viewer, and named save.
---
-## Contents
+## Screenshots
-- [MCP Server / CLI](#quick-start) — use Open Ontologies from Claude Code, Claude Desktop, or any MCP client
-- [Studio](#studio) — desktop GUI for visual ontology engineering (Tauri + React + 3D graph)
+| Full UI | 3D Graph |
+|---|---|
+| ![Studio overview showing 3D graph, property inspector, and AI chat](studio/docs/screenshots/studio-overview.png) | ![3D force-directed graph of the Forest ontology](studio/docs/screenshots/studio-graph.png) |
+
+*Forest ontology built entirely through natural language: "Build me an ontology about a forest ecosystem." Claude called `onto_clear` → `onto_load` → `onto_reason` → `onto_save` automatically.*
---
-## Quick Start
+## Quick Start (MCP / CLI)
-### 1. Install
+### Install
#### Pre-built binaries
-Download from [GitHub Releases](https://github.com/fabio-rovai/open-ontologies/releases/latest):
-
```bash
# macOS (Apple Silicon)
curl -LO https://github.com/fabio-rovai/open-ontologies/releases/latest/download/open-ontologies-aarch64-apple-darwin
@@ -60,7 +61,7 @@ cargo build --release
./target/release/open-ontologies init
```
-### 2. Connect to your MCP client
+### Connect to your MCP client
<details>
<summary><strong>Claude Code</strong></summary>
@@ -130,7 +131,7 @@ Add to your MCP settings (usually `.cursor/mcp.json` or equivalent):
```
</details>
-### 3. Build your first ontology
+### Build your first ontology
```text
Build me a Pizza ontology following the Manchester University tutorial.
@@ -141,9 +142,111 @@ Validate it, load it, and show me the stats.
Claude generates Turtle, then automatically calls `onto_validate` → `onto_load` → `onto_stats` → `onto_lint` → `onto_query`, fixing errors along the way.
+---
+
+## Studio (Desktop App)
+
+The Studio lives in [`studio/`](studio/) and provides a visual interface on top of the same engine.
+
+### Prerequisites
+
+- **Rust + Cargo** — `curl https://sh.rustup.rs -sSf | sh`
+- **Node.js 18+** — `brew install node`
+
+### First-time setup
+
+```bash
+# 1. Build the engine binary (from repo root)
+cargo build --release
+
+# 2. Install JS dependencies
+cd studio && npm install
+```
+
+### Run
+
+```bash
+cd studio
+PATH=/opt/homebrew/bin:/Users/fabio/.cargo/bin:$PATH npm run tauri dev
+```
+
+The `PATH` prefix is required because macOS doesn't expose Homebrew or Cargo to subprocess shells.
+
+On startup Tauri will:
+
+1. Compile the Rust shell (~1 min first run, fast after)
+2. Start Vite dev server on `localhost:1420`
+3. Open the app window
+4. Spawn the engine sidecar (`open-ontologies serve-http --port 8080`)
+5. Spawn the AI agent sidecar (Node.js, 3s after engine)
+
+### Rebuild after changes
+
+```bash
+# Engine changes (src/):
+cargo build --release
+
+# Agent sidecar changes (studio/src-tauri/sidecars/agent/index.ts):
+cd studio/src-tauri/sidecars/agent && npm run build
+```
+
+### Studio Features
+
+#### 3D Graph Canvas
+
+Live force-directed graph (Three.js / WebGL) of your OWL class hierarchy.
+
+- **Drag** to orbit · **Scroll** to zoom · **Click node** to inspect · **Right-click** to add class · **Delete** to remove
+- On load, fires two SPARQL queries: all `owl:Class` nodes + all `rdfs:subClassOf` edges
+- Nodes are spheres with floating label sprites; selected node highlighted in amber
+- Auto-refreshes after every agent mutation or UI edit via `window.__refreshGraph()`
+
+#### AI Agent Chat
+
+Natural language ontology engineering powered by Claude Sonnet 4.6 via the Agent SDK.
+
+- Type any instruction: *"Add a Mammal hierarchy"*, *"Run OWL reasoning"*, *"Validate and fix issues"*
+- Claude calls the engine's 42 MCP tools automatically, iterating until the result is correct
+- After any mutation, the graph refreshes and the ontology is auto-saved
+- Slash commands: `/build`, `/expand`, `/validate`, `/reason`, `/query`, `/stats`, `/save`
+
+#### Property Inspector
+
+Click any node to open a Protégé-style triple editor.
+
+- Click any value to edit inline (Enter saves, Escape cancels)
+- Hover a row to reveal the `×` delete button
+- `+ Add` opens a form with predicate quick-pick (`rdfs:label`, `rdfs:subClassOf`, `owl:equivalentClass`, etc.) and Literal/URI toggle
+
+#### Lineage Panel
+
+Full audit trail of every agent action, stored in SQLite.
+
+- Events grouped by session with a count badge
+- Color-coded badges: `P` plan · `A` apply · `E` enforce · `D` drift · `M` monitor · `AL` align
+
+#### Named Save
+
+- Click `💾` or press **⌘S** to save with a custom filename
+- All saves go to `~/.open-ontologies/<name>.ttl`
+- Auto-save after every mutation writes to `~/.open-ontologies/studio-live.ttl`
+
+### Keyboard Shortcuts
+
+| Shortcut | Action |
+| --- | --- |
+| ⌘J | Toggle Chat panel |
+| ⌘I | Toggle Inspector panel |
+| ⌘S | Save As… |
+| Delete / Backspace | Delete selected node |
+
+---
+
## Why This Exists
-Single-shot LLM ontology generation has real problems: no validation, no verification, no iteration, no persistence, no scale, no integration. Open Ontologies solves all of these with a proper RDF/SPARQL engine (Oxigraph) exposed as MCP tools that Claude calls automatically.
+Single-shot LLM ontology generation has real problems: no validation, no verification, no iteration, no persistence, no scale, no integration. Open Ontologies solves all of these with a proper RDF/SPARQL engine (Oxigraph) exposed as MCP tools that Claude calls automatically — and a desktop Studio that makes the results visible in real time.
+
+---
## Tools
@@ -160,13 +263,17 @@ Single-shot LLM ontology generation has real problems: no validation, no verific
| **Alignment** | `align`, `align-feedback` | Cross-ontology class matching with self-calibrating confidence |
| **Clinical** | `crosswalk`, `enrich`, `validate-clinical` | ICD-10 / SNOMED / MeSH crosswalks |
| **Feedback** | `lint-feedback`, `enforce-feedback` | Self-calibrating suppression |
-| **Embeddings** | `embed`, `search`, `similarity` | Dual-space semantic search (text + Poincare structural) |
+| **Embeddings** | `embed`, `search`, `similarity` | Dual-space semantic search (text + Poincaré structural) |
| **Reasoning** | `reason`, `dl_explain`, `dl_check` | Native OWL2-DL SHOIQ tableaux reasoner |
All tools are available both as MCP tools (prefixed `onto_`) and as CLI subcommands.
+---
+
## Architecture
+### Engine
+
```mermaid
flowchart TD
Claude["Claude / LLM"]
@@ -190,106 +297,7 @@ flowchart TD
Tools --> Core
```
-## Documentation
-
-| Topic | Link |
-| ----- | ---- |
-| Quickstart | [docs/quickstart.md](docs/quickstart.md) |
-| Data Pipeline | [docs/data-pipeline.md](docs/data-pipeline.md) |
-| Ontology Lifecycle | [docs/lifecycle.md](docs/lifecycle.md) |
-| Schema Alignment | [docs/alignment.md](docs/alignment.md) |
-| OWL2-DL Reasoning | [docs/reasoning.md](docs/reasoning.md) |
-| Semantic Embeddings | [docs/embeddings.md](docs/embeddings.md) |
-| Clinical Crosswalks | [docs/clinical.md](docs/clinical.md) |
-| Benchmarks | [docs/benchmarks.md](docs/benchmarks.md) |
-| Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) |
-| Changelog | [CHANGELOG.md](CHANGELOG.md) |
-
-## Stack
-
-- **Rust** (edition 2024) — single binary, no JVM
-- **Oxigraph 0.4** — pure Rust RDF/SPARQL engine
-- **rmcp** — MCP protocol implementation
-- **SQLite** (rusqlite) — state, versions, lineage, feedback, embeddings
-- **Apache Arrow/Parquet** — clinical crosswalk file format
-- **tract-onnx** — pure Rust ONNX runtime for text embeddings (optional)
-- **tokenizers** — HuggingFace tokenizer (optional)
-
-## License
-
-MIT
-
-<a href="https://glama.ai/mcp/servers/fabio-rovai/open-ontologies"><img width="380" height="200" src="https://glama.ai/mcp/servers/fabio-rovai/open-ontologies/badge" /></a>
-
----
-
-## Studio
-
-A desktop ontology engineering environment powered by AI. Built with Tauri 2, React 19, and the Open Ontologies engine.
-
-### Features
-
-#### 3D Graph Canvas
-
-The graph view renders your OWL ontology as a live 3D force-directed graph powered by `3d-force-graph` (Three.js / WebGL).
-
-**How it works:**
-
-- On connection, the canvas fires two SPARQL queries against the engine's in-memory Oxigraph store:
- - `SELECT ?c ?label WHERE { ?c a owl:Class . OPTIONAL { ?c rdfs:label ?label } }` — fetches all named classes
- - `SELECT ?sub ?parent WHERE { ?sub rdfs:subClassOf ?parent . ?sub a owl:Class }` — fetches the subclass hierarchy
-- Nodes are spheres with floating canvas-text label sprites. The selected node is highlighted in amber; others are blue.
-- Edges are directed arrows (subClassOf → parent direction) with 60% opacity.
-- The graph uses Three.js warm lighting (ambient + directional) on a `#1e1e2e` background.
-- A `ResizeObserver` keeps the canvas sized to its container on every layout change.
-
-**Interaction:**
-
-- **Drag** to orbit the scene
-- **Scroll** to zoom in/out
-- **Click a node** — selects it, flies the camera toward it (800ms ease), and opens the Property Inspector
-- **Click background** — deselects
-- **Right-click** — opens the Add Class dialog at the cursor position
-- **Delete / Backspace** — deletes the selected class (fires two SPARQL DELETE statements, then saves and refreshes)
-
-**Refresh:** After any mutation (agent, inspector, delete, add), `window.__refreshGraph()` is called to re-query the store and redraw.
-
-#### AI Agent Chat
-
-Natural language ontology engineering via the Claude Agent SDK.
-
-**How it works:**
-- The agent runs as a Node.js sidecar process (`studio/src-tauri/sidecars/agent/`), spawned by Tauri 3 seconds after the engine starts.
-- The sidecar connects Claude to the Open Ontologies engine via its MCP endpoint (`http://localhost:8080/mcp`), giving Claude access to all 42 ontology tools.
-- The Tauri Rust backend communicates with the sidecar over stdin/stdout using a simple JSON protocol (`{ type: 'chat', message }` in, `{ type: 'text' | 'tool_call' | 'done' | 'error' }` out).
-- Multi-turn sessions are maintained in-memory within the sidecar process.
-- After any mutation tool call, the frontend detects `mutated: true` in the `done` message and triggers a graph refresh.
-
-**Slash commands:** `/build`, `/expand`, `/validate`, `/reason`, `/query`, `/stats`, `/save`
-
-#### Property Inspector
-
-Protégé-style property editing for any selected node.
-
-- Click any literal or URI value to edit it inline (Enter saves, Escape cancels)
-- Hover over a triple row to reveal the `×` delete button
-- The `+ Add` button opens a form with predicate quick-pick and Literal/URI toggle
-- All edits call SPARQL UPDATE via REST, then save to file
-
-#### Lineage Panel
-
-Full audit trail of every agent action, stored in SQLite and exposed via `GET /api/lineage`.
-
-- Events grouped by session with a count badge
-- Color-coded operation badges: `P` plan, `A` apply, `E` enforce, `D` drift, `M` monitor, `AL` align
-
-#### Named Save
-
-- Click `💾` or press **⌘S** to save with a custom filename
-- Saves to `~/.open-ontologies/<name>.ttl`
-- All auto-saves after mutations persist to `~/.open-ontologies/studio-live.ttl`
-
-### Studio Architecture
+### Studio
```mermaid
flowchart TD
@@ -336,80 +344,55 @@ flowchart TD
Store --> DB
```
+### Design decisions
+
| Decision | Reason |
| --- | --- |
-| Reads go through sessionless REST API | No MCP session management needed for SPARQL queries or stats |
+| UI reads use sessionless REST API | No MCP session management needed for SPARQL queries or stats |
| UI writes use REST `/api/update` + `/api/save` | Avoids session lifecycle issues in the Tauri WebKit webview |
| Agent writes go through MCP `tools/call` | The Agent SDK manages its own MCP session; Claude needs the full tool set |
| Shared `Arc<GraphStore>` | All MCP sessions and all REST handlers operate on the same in-memory triple store |
| Agent sidecar over stdin/stdout | Keeps Node.js process isolated; Tauri manages lifecycle |
-### Studio Stack
+---
+
+## Stack
| Layer | Tech |
| --- | --- |
+| Engine | Rust (edition 2024), single binary |
+| Triple store | Oxigraph 0.4 (pure Rust RDF/SPARQL) |
+| MCP protocol | rmcp (Streamable HTTP transport) |
+| State / lineage | SQLite (rusqlite) |
+| Clinical crosswalks | Apache Arrow / Parquet |
+| Embeddings | tract-onnx (pure Rust ONNX runtime, optional) |
| Desktop shell | Tauri 2 |
| Frontend | React 19, Vite 7, TypeScript 5.8, Tailwind CSS 4 |
| 3D graph | 3d-force-graph 1.79 (Three.js / WebGL) |
-| State | Zustand 5 |
-| Engine | Rust, Axum 0.8, Oxigraph 0.4 (SPARQL), SQLite |
-| MCP | rmcp 1 (Streamable HTTP transport) |
+| UI state | Zustand 5 |
| AI agent | Claude Sonnet 4.6 via Agent SDK (Node.js sidecar) |
-### Running the Studio
-
-#### Prerequisites
-
-- **Rust + Cargo** — install via `curl https://sh.rustup.rs -sSf | sh`
-- **Node.js 18+** — install via Homebrew: `brew install node`
-- **Tauri CLI** — installed as a dev dependency (`npm install` handles this)
-
-#### First-time setup
-
-```bash
-# 1. Build the engine binary
-cargo build --release
-# Produces: target/release/open-ontologies
-# The studio symlink at studio/src-tauri/binaries/open-ontologies-aarch64-apple-darwin
-# already points to it — no extra step needed.
-
-# 2. Install JS dependencies
-cd studio
-npm install
-```
-
-#### Start the app
-
-```bash
-cd studio
-PATH=/opt/homebrew/bin:/Users/fabio/.cargo/bin:$PATH npm run tauri dev
-```
-
-The `PATH` prefix is required because the macOS default shell PATH doesn't include Homebrew or Cargo when Tauri spawns subprocesses.
-
-Tauri will:
+---
-1. Compile the Rust shell (first run ~1 min, subsequent runs fast)
-2. Start the Vite dev server on `localhost:1420`
-3. Open the app window
-4. Spawn the engine sidecar (`open-ontologies serve-http --port 8080`)
-5. Spawn the agent sidecar (Node.js, after 3s delay)
+## Documentation
-#### Rebuild after changes
+| Topic | Link |
+| ----- | ---- |
+| Quickstart | [docs/quickstart.md](docs/quickstart.md) |
+| Data Pipeline | [docs/data-pipeline.md](docs/data-pipeline.md) |
+| Ontology Lifecycle | [docs/lifecycle.md](docs/lifecycle.md) |
+| Schema Alignment | [docs/alignment.md](docs/alignment.md) |
+| OWL2-DL Reasoning | [docs/reasoning.md](docs/reasoning.md) |
+| Semantic Embeddings | [docs/embeddings.md](docs/embeddings.md) |
+| Clinical Crosswalks | [docs/clinical.md](docs/clinical.md) |
+| Benchmarks | [docs/benchmarks.md](docs/benchmarks.md) |
+| Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) |
+| Changelog | [CHANGELOG.md](CHANGELOG.md) |
-```bash
-# After changes to the engine (src/):
-cargo build --release
+---
-# After changes to the agent sidecar (studio/src-tauri/sidecars/agent/index.ts):
-cd studio/src-tauri/sidecars/agent && npm run build
-```
+## License
-#### Keyboard Shortcuts
+MIT
-| Shortcut | Action |
-| --- | --- |
-| ⌘J | Toggle Chat panel |
-| ⌘I | Toggle Inspector panel |
-| ⌘S | Save As… |
-| Delete / Backspace | Delete selected node |
+<a href="https://glama.ai/mcp/servers/fabio-rovai/open-ontologies"><img width="380" height="200" src="https://glama.ai/mcp/servers/fabio-rovai/open-ontologies/badge" alt="Open Ontologies MCP server on Glama" /></a>
diff --git a/studio/docs/screenshots/studio-graph.png b/studio/docs/screenshots/studio-graph.png
new file mode 100644
index 00000000..9ccdee17
Binary files /dev/null and b/studio/docs/screenshots/studio-graph.png differ
diff --git a/studio/docs/screenshots/studio-overview.png b/studio/docs/screenshots/studio-overview.png
new file mode 100644
index 00000000..9d0f1beb
Binary files /dev/null and b/studio/docs/screenshots/studio-overview.png differ