diff --git a/docs/cli-setup.md b/docs/cli-setup.md
new file mode 100644
index 00000000..70dce7ae
--- /dev/null
+++ b/docs/cli-setup.md
@@ -0,0 +1,235 @@
+---
+title: "CLI Setup"
+description: "The five Semantica executables — what each one does, when to use it, and how to confirm it is working."
+icon: "terminal"
+---
+
+Installing the base package registers five executables on your `PATH`. Each serves a distinct purpose. This page explains what they are, how to verify they are available, and which one to reach for in each situation.
+
+## Installed Commands
+
+```bash
+pip install semantica
+```
+
+After installation the following commands are available:
+
+| Command | Entry point | What it does |
+| ------- | ----------- | ------------ |
+| `semantica` | `semantica.cli:main` | General-purpose CLI for pipeline runs, extraction, and graph operations |
+| `semantica-server` | `semantica.server:main` | FastAPI/uvicorn REST API server bound to `0.0.0.0:8000` |
+| `semantica-worker` | `semantica.worker:main` | Background worker process entry point for Semantica deployments |
+| `semantica-explorer` | `semantica.explorer:main` | Interactive browser dashboard for knowledge graph exploration |
+| `semantica-mcp` | `semantica.mcp_server:main` | MCP server (stdio) for Claude Desktop, Cursor, Windsurf, and other MCP clients |
+
+
+ `semantica-explorer` requires `pip install semantica[explorer]`. Running it without that extra will immediately print an error and exit. See [Explorer Setup](explorer-setup) for the full walkthrough.
+
+
+## Verify the Installation
+
+Confirm each command is reachable and prints its usage:
+
+```bash
+semantica --help
+semantica-server --help
+semantica-worker --help
+semantica-explorer --help
+semantica-mcp --help
+```
+
+Confirm the package version:
+
+```bash
+python -c "import semantica; print(semantica.__version__)"
+```
+
+## When to Use Each Command
+
+
+
+ The general-purpose CLI. Use it for one-off pipeline runs, entity extraction, and graph operations from a shell script or CI job.
+
+
+ Starts the REST API server. Binds to `0.0.0.0:8000`. Use this when another service or application needs programmatic access to Semantica over HTTP.
+
+
+ Background worker process entry point for Semantica deployments. Use alongside `semantica-server` for async task processing.
+
+
+ Launches the browser dashboard. Requires `pip install semantica[explorer]`. Use this to explore a saved knowledge graph interactively. See [Explorer Setup](explorer-setup).
+
+
+ Runs the MCP server over stdio. Configure it in your MCP client's settings file to expose all 12 tools and 3 resources to Claude Desktop, Cursor, Windsurf, or any MCP-aware client. See [MCP Server](reference/mcp_server).
+
+
+
+## Usage Examples
+
+
+
+ ```bash
+ # Starts FastAPI + uvicorn on 0.0.0.0:8000
+ semantica-server
+ ```
+
+ Once running, check it with:
+
+ ```bash
+ curl http://localhost:8000/health
+ # {"status": "healthy"}
+
+ curl http://localhost:8000/api/info
+ # {"name": "Semantica API", "version": "...", "status": "active"}
+ ```
+
+ The interactive API docs are at `http://localhost:8000/docs`.
+
+
+ ```bash
+ semantica-worker
+ ```
+
+ The worker exits cleanly on `SIGINT` (Ctrl-C) or `SIGTERM`.
+
+
+ Add to your MCP client's settings file:
+
+ ```json
+ {
+ "mcpServers": {
+ "semantica": {
+ "command": "semantica-mcp"
+ }
+ }
+ }
+ ```
+
+ Or use the Python module form if the command is not on `PATH`:
+
+ ```json
+ {
+ "mcpServers": {
+ "semantica": {
+ "command": "python",
+ "args": ["-m", "semantica.mcp_server"]
+ }
+ }
+ }
+ ```
+
+ Test it directly before configuring your client:
+
+ ```bash
+ echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | semantica-mcp
+ ```
+
+ You should receive a JSON-RPC response. See [MCP Server](reference/mcp_server) for the full list of tools and resources.
+
+
+ ```bash
+ pip install semantica[explorer]
+ semantica-explorer --graph my_graph.json
+ ```
+
+ See [Explorer Setup](explorer-setup) for the full walkthrough including how to build and save a graph file.
+
+
+ Every command also runs as a Python module — useful when the script directory is not on `PATH`:
+
+ ```bash
+ python -m semantica.mcp_server
+ python -m semantica.explorer --graph my_graph.json
+ ```
+
+
+
+## Environment Variables
+
+`semantica-mcp` reads two environment variables:
+
+| Variable | Default | Description |
+| -------- | ------- | ----------- |
+| `SEMANTICA_KG_PATH` | *(none)* | Path to a saved graph file to load on startup |
+| `SEMANTICA_LOG_LEVEL` | `WARNING` | Log verbosity: `DEBUG`, `INFO`, `WARNING` |
+
+`semantica-server` reads one:
+
+| Variable | Default | Description |
+| -------- | ------- | ----------- |
+| `SEMANTICA_CORS_ORIGINS` | `http://localhost:5173,http://127.0.0.1:5173` | Comma-separated list of allowed CORS origins |
+
+No other environment variables are read by these commands.
+
+## Troubleshooting
+
+### `command not found`
+
+The executables are placed in the `bin/` (Linux/Mac) or `Scripts/` (Windows) directory of the active Python environment. If the command is not found, that directory is likely not on `PATH`.
+
+Activate your virtual environment first:
+
+```bash
+source venv/bin/activate # Linux / Mac
+venv\Scripts\activate # Windows
+semantica --help
+```
+
+Find where pip placed the scripts:
+
+```bash
+python -m site --user-scripts # user-level install
+pip show -f semantica # shows installed files
+```
+
+### Command found but crashes on import
+
+```bash
+pip install --upgrade semantica
+python -c "import semantica; print(semantica.__version__)"
+```
+
+If you have multiple Python environments, make sure you are installing into the same one the shell resolves:
+
+```bash
+python -m pip install semantica
+```
+
+### `semantica-explorer` — "uvicorn is required"
+
+The Explorer extras are not included in the base install:
+
+```bash
+pip install semantica[explorer]
+```
+
+### `semantica-mcp` silent failure in a MCP client
+
+The MCP server communicates over stdio. Test it directly from the shell first:
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"ping","params":{}}' | semantica-mcp
+```
+
+A response of `{"jsonrpc":"2.0","id":1,"result":{}}` confirms the server is working. If you see nothing, check that the command is on `PATH` and the base package is installed.
+
+### Windows: DLL errors on startup
+
+Install the [Microsoft Visual C++ Redistributable](https://aka.ms/vs/17/release/vc_redist.x64.exe). This is a Windows system dependency required by PyTorch and related packages, not a Semantica bug.
+
+## Next Steps
+
+
+
+ Build a graph, save it, and launch the browser dashboard.
+
+
+ All 12 tools and 3 resources exposed over the MCP protocol.
+
+
+ Virtual environments, optional extras, and platform-specific notes.
+
+
+ End-to-end pipeline walkthrough with working code.
+
+
diff --git a/docs/docs.json b/docs/docs.json
index c2ffe747..2ba492b4 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -103,6 +103,8 @@
"group": "Get Started",
"pages": [
"installation",
+ "cli-setup",
+ "explorer-setup",
"quickstart",
"getting-started"
]
diff --git a/docs/explorer-setup.md b/docs/explorer-setup.md
new file mode 100644
index 00000000..bdf9e43e
--- /dev/null
+++ b/docs/explorer-setup.md
@@ -0,0 +1,257 @@
+---
+title: "Explorer Setup"
+description: "Install the Explorer extras, save a ContextGraph to JSON, and launch the interactive browser dashboard."
+icon: "map"
+---
+
+`semantica-explorer` is an interactive browser dashboard for knowledge graph exploration. You give it a graph file, it starts a local server, and opens a browser tab where you can search nodes, find paths, inspect provenance, and run analytics — no code required after launch.
+
+This page covers everything needed to go from zero to a running Explorer. For the full REST API reference and endpoint catalogue, see [Explorer Reference](reference/explorer).
+
+## Prerequisites
+
+The Explorer depends on FastAPI and uvicorn, which are not included in the base install:
+
+```bash
+pip install semantica[explorer]
+```
+
+
+ `pip install semantica` alone is not sufficient. Running `semantica-explorer` without the `[explorer]` extra immediately prints an error and exits with code 1.
+
+
+Verify:
+
+```bash
+semantica-explorer --help
+```
+
+You should see the usage message with the four available flags. If you see `command not found`, activate your virtual environment first. See [CLI Setup](cli-setup#troubleshooting) for PATH help.
+
+## Minimal End-to-End Example
+
+The following four steps are everything needed to get Explorer running:
+
+```python
+from semantica.context import ContextGraph
+
+# 1. Create a graph
+graph = ContextGraph()
+
+# 2. Add a node
+graph.add_node("python", "language", content="Python programming language")
+
+# 3. Save to disk
+graph.save_to_file("my_graph.json")
+```
+
+```bash
+# 4. Launch Explorer
+semantica-explorer --graph my_graph.json
+```
+
+The browser opens at `http://127.0.0.1:8000`. The health endpoint confirms the server is up:
+
+```bash
+curl http://127.0.0.1:8000/api/health
+# {"status": "healthy"}
+```
+
+## Step 1 — Build and Save a ContextGraph
+
+Explorer loads a graph from a JSON file on disk. You need to create that file first.
+
+
+
+ ```python
+ from semantica.context import ContextGraph
+
+ graph = ContextGraph()
+
+ # add_node(node_id, node_type, content=None, **properties)
+ graph.add_node("python", "language", content="Python programming language")
+ graph.add_node("fastapi", "framework", content="FastAPI web framework")
+ graph.add_node("guido", "person", content="Guido van Rossum")
+
+ # add_edge(source_id, target_id, edge_type="related_to", weight=1.0, **properties)
+ graph.add_edge("python", "fastapi", "enables")
+ graph.add_edge("guido", "python", "created")
+ ```
+
+
+ ```python
+ graph.save_to_file("my_graph.json")
+ ```
+
+ `save_to_file` writes a JSON object with `graph_id`, `nodes`, `edges`, and `links` to the specified path.
+
+
+ ```python
+ from semantica.context import ContextGraph
+
+ check = ContextGraph()
+ check.load_from_file("my_graph.json")
+ print(check.stats())
+ # {
+ # "node_count": 3,
+ # "edge_count": 2,
+ # "node_types": {"language": 1, "framework": 1, "person": 1},
+ # "edge_types": {"enables": 1, "created": 1},
+ # "density": ...
+ # }
+ ```
+
+ If this runs without error, Explorer will load the file successfully.
+
+
+
+
+ Already have a graph from a pipeline run? Skip straight to Step 2. The only requirement is that the file was saved with `ContextGraph.save_to_file()`.
+
+
+## Step 2 — Launch Explorer
+
+```bash
+semantica-explorer --graph my_graph.json
+```
+
+The startup sequence prints:
+
+```
+✓ Graph loaded — 3 nodes, 2 edges
+╭─ Semantica Explorer · http://127.0.0.1:8000 ─╮
+│ API docs http://127.0.0.1:8000/docs │
+│ Health http://127.0.0.1:8000/api/health │
+╰───────────────────────────────────────────────╯
+```
+
+The browser opens automatically at `http://127.0.0.1:8000` approximately 1.5 seconds after the server starts.
+
+## CLI Flags
+
+`semantica-explorer` accepts exactly four flags:
+
+| Flag | Short | Default | Description |
+| ---- | ----- | ------- | ----------- |
+| `--graph` | `-g` | *(required)* | Path to a ContextGraph JSON file |
+| `--port` | `-p` | `8000` | Port to bind the server |
+| `--host` | — | `127.0.0.1` | Host to bind the server |
+| `--no-browser` | — | off | Do not open a browser tab automatically |
+
+There are no flags for authentication, log level, or TLS. Those are not implemented in the CLI.
+
+### Examples
+
+```bash
+# Minimal — local only, port 8000, browser opens automatically
+semantica-explorer --graph my_graph.json
+
+# Short flags
+semantica-explorer -g my_graph.json -p 8080
+
+# Expose on the network so other machines can connect
+semantica-explorer --graph my_graph.json --host 0.0.0.0 --port 8080
+
+# Headless — skip the auto-open and navigate manually
+semantica-explorer --graph my_graph.json --no-browser
+```
+
+
+ `--host 0.0.0.0` makes Explorer reachable on every network interface. The server has no built-in authentication. Only use this on a trusted private network.
+
+
+## Browser Access
+
+Once the server is running:
+
+| URL | What you get |
+| --- | ------------ |
+| `http://127.0.0.1:8000` | Interactive dashboard |
+| `http://127.0.0.1:8000/docs` | Swagger UI — every REST endpoint, interactive |
+| `http://127.0.0.1:8000/api/health` | Health check — `{"status": "healthy"}` |
+
+The browser tab opens 1.5 seconds after startup. If it does not open, navigate to the URL manually or pass `--no-browser` and open it yourself.
+
+## Running as a Python Module
+
+If `semantica-explorer` is not on `PATH`, use the module form:
+
+```bash
+python -m semantica.explorer --graph my_graph.json --port 8080
+```
+
+## Common Startup Errors
+
+**`Error: graph file not found: my_graph.json`**
+
+The path passed to `--graph` must point to an existing file. The CLI checks with `os.path.isfile()` before attempting to load anything.
+
+```bash
+# Confirm the file exists
+ls my_graph.json # Linux / Mac
+dir my_graph.json # Windows
+
+# Use the full path if needed
+semantica-explorer --graph /absolute/path/to/my_graph.json
+```
+
+**`Error: uvicorn is required`**
+
+The `[explorer]` extra was not installed:
+
+```bash
+pip install semantica[explorer]
+```
+
+**Explorer launches but shows zero nodes**
+
+The file loaded but contains no nodes. Verify with Python:
+
+```python
+from semantica.context import ContextGraph
+g = ContextGraph()
+g.load_from_file("my_graph.json")
+print(g.stats()) # check node_count
+```
+
+A `node_count` of `0` means the file was saved empty or the nodes key is absent. Make sure you called `add_node` before `save_to_file`.
+
+**`Connection refused` from another machine**
+
+The default `--host 127.0.0.1` only accepts connections from the same machine. To allow remote access:
+
+```bash
+semantica-explorer --graph my_graph.json --host 0.0.0.0
+```
+
+**Browser tab does not open**
+
+This is expected in headless, SSH, and container environments. Add `--no-browser` to suppress the warning and open `http://127.0.0.1:8000` in a browser that has network access to the server.
+
+## What Explorer Gives You
+
+Once running, Explorer exposes a REST API and dashboard for:
+
+- **Node and edge search** — indexed search across all nodes by ID, type, and content
+- **Neighborhood expansion** — inspect neighbors up to configurable hop depth
+- **Path finding** — BFS shortest path between any two nodes
+- **Graph analytics** — centrality, community detection, connectivity
+- **Decisions and provenance** — query recorded decisions and their causal chains
+- **Import / export** — upload JSON or CSV to extend the graph; download the current state
+
+The full endpoint catalogue is documented in the Swagger UI at `/docs` and in the reference page below.
+
+
+
+ Every REST endpoint, WebSocket events, analytics, and all supported flags.
+
+
+ All five Semantica executables and when to use each one.
+
+
+ Full documentation for ContextGraph — build, query, save, and load.
+
+
+ End-to-end pipeline: ingest → extract → build graph → export.
+
+