Merge branch 'main' into docs-mcp-tool-count-15

docs/choose-your-module.md

@@ -226,7 +226,7 @@ Pick your goal to see the minimum imports and a working skeleton.
   </Tab>
 
   <Tab title="MCP — Claude / Cursor">
-    Use Semantica from Claude Desktop, Cursor, VS Code, or any MCP-aware tool — no Python code required after setup. 12 tools available instantly.
+    Use Semantica from Claude Desktop, Cursor, VS Code, or any MCP-aware tool — no Python code required after setup. 15 tools available instantly.
 
     **Step 1 — Install:**
     ```bash

docs/cli-setup.md

@@ -53,7 +53,7 @@ python -c "import semantica; print(semantica.__version__)"
 - **semantica-server** — 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.
 - **semantica-worker** — Background task processor. Run alongside `semantica-server` when you need async pipeline execution outside the request cycle. Start the server first, then start one or more workers pointing at the same backend.
 - **semantica-explorer** — Launches the browser dashboard. Requires `pip install semantica[explorer]`. Use this to explore a saved knowledge graph interactively. See [Explorer Setup](explorer-setup).
-- **semantica-mcp** — 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).
+- **semantica-mcp** — Runs the MCP server over stdio. Configure it in your MCP client's settings file to expose all 15 tools and 3 resources to Claude Desktop, Cursor, Windsurf, or any MCP-aware client. See [MCP Server](reference/mcp_server).
 
 
 ## Usage Examples
@@ -229,6 +229,6 @@ Install the [Microsoft Visual C++ Redistributable](https://aka.ms/vs/17/release/
 ## Next Steps
 
 - [Explorer Setup](explorer-setup) — Build a graph, save it, and launch the browser dashboard.
-- [MCP Server](reference/mcp_server) — All 12 tools and 3 resources exposed over the MCP protocol.
+- [MCP Server](reference/mcp_server) — All 15 tools and 3 resources exposed over the MCP protocol.
 - [Installation](installation) — Virtual environments, optional extras, and platform-specific notes.
 - [Quickstart](quickstart) — End-to-end pipeline walkthrough with working code.

docs/getting-started.md

@@ -183,7 +183,7 @@ icon: "rocket"
     }
     ```
 
-    12 tools available instantly: extract entities, query graph, record decisions, run reasoning, export results.
+    15 tools available instantly: extract entities, query graph, record decisions, run reasoning, export results.
 
     **Next:** [MCP Server reference →](reference/mcp_server)
   </Tab>

docs/guides/mcp-server.md

@@ -11,7 +11,7 @@ MCP stands for the Model Context Protocol. It is an open standard that allows ex
 The Semantica MCP server exposes your knowledge graph as 12 callable tools. By connecting it, any compatible AI client can traverse the graph live, record decisions, run analytics, and export results during a conversation — without you having to write custom tool wrappers.
 
 <Info>
-  The Semantica MCP server exposes 12 tools and 3 read-only resources. All tools accept and return JSON. No configuration beyond an optional environment variable for graph persistence is required.
+  The Semantica MCP server exposes 15 tools and 3 read-only resources. All tools accept and return JSON. No configuration beyond an optional environment variable for graph persistence is required.
 </Info>
 
 ## Architecture & Communication
@@ -132,7 +132,7 @@ docker run --rm -i \
   ghcr.io/semantica-agi/semantica-mcp:latest
 ```
 
-## What the Agent Can Do: The 12 Tools
+## What the Agent Can Do: The 15 Tools
 
 Once connected, the LLM can call any of these tools during a conversation. The agent chains them automatically — you do not orchestrate the sequence, you just describe what you want.
 
@@ -140,6 +140,8 @@ Once connected, the LLM can call any of these tools during a conversation. The a
 
 **Knowledge graph manipulation** — `add_entity` adds a node, `add_relationship` adds a directed edge. After extraction, the agent calls these to persist what it found into the live graph.
 
+**Live graph queries and edits** — `query_graph` reads the graph without exporting it: fetch one node, walk its neighbours up to five hops, or keyword-search nodes. `update_node` merges properties onto an existing node (for example marking a task node `done`), and `delete_node` archives a node it no longer tracks. When `SEMANTICA_KG_PATH` is set, `update_node` and `delete_node` write their changes back to that file so they survive a restart.
+
 **Decision intelligence** — `record_decision` writes a decision as a provenance node with confidence score, reasoning, and decision maker identity. `query_decisions` retrieves past decisions by query or category. `find_precedents` finds the most similar past decisions by semantic similarity. `get_causal_chain` traces decision causality upstream or downstream.
 
 **Reasoning** — `run_reasoning` applies forward-chaining IF/THEN rules over a set of facts and returns derived conclusions.

docs/index.md

@@ -369,7 +369,7 @@ Semantica was designed for domains where every decision must be explainable and
 | `semantica.reasoning` | Forward chaining, Rete, deductive, abductive, SPARQL, Datalog |
 | `semantica.ontology` | SHACL, SKOS, alignments, diff/migration, auto-generation, OWL/RDF |
 | `semantica.explorer` | FastAPI Knowledge Explorer, Ontology Hub, Distance Intelligence, SHACL Studio |
-| `semantica.mcp_server` | MCP stdio server: 12 tools for Claude Desktop, VS Code, Cursor, Windsurf, Cline |
+| `semantica.mcp_server` | MCP stdio server: 15 tools for Claude Desktop, VS Code, Cursor, Windsurf, Cline |
 | `semantica.vector_store` | FAISS, Pinecone, Weaviate, Qdrant, Milvus, PgVector |
 | `semantica.graph_store` | Neo4j, FalkorDB, Apache AGE, Amazon Neptune |
 | `semantica.triplet_store` | In-memory and persistent RDF triple store with SPARQL |

docs/modules.md

@@ -438,7 +438,7 @@ Exposes Semantica as an MCP stdio server for IDE and agent integrations.
 python -m semantica.mcp_server
 ```
 
-**Integrations:** Claude Desktop, VS Code, Cursor, Windsurf, Cline: 12 MCP tools exposed
+**Integrations:** Claude Desktop, VS Code, Cursor, Windsurf, Cline: 15 MCP tools exposed
 
 ### Seed
 

docs/reference/mcp_server.md

@@ -6,7 +6,7 @@ icon: "plug"
 
 **`semantica.mcp_server`** exposes Semantica's knowledge graph, decision intelligence, semantic extraction, and reasoning capabilities as an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) **server over stdio**:
 
-- 12 MCP tools exposed: extract entities, query graph, record decisions, run reasoning, export results
+- 15 MCP tools exposed: extract entities, query graph, record decisions, run reasoning, export results
 - No Python code required after launch: configure once, use from any MCP-aware client
 - Compatible with Claude Desktop, Windsurf, Cline, Continue, VS Code, Roo Code, Cursor
 
@@ -40,7 +40,7 @@ python -m semantica.mcp_server
 
 ## What You Get
 
-- **12 MCP Tools** — Extract entities, extract relations, record decisions, query decisions, find precedents, trace causal chains, add entities, add relationships, run analytics, summarise graph, run reasoning, export graph.
+- **15 MCP Tools** — Extract entities, extract relations, record decisions, query decisions, find precedents, trace causal chains, add entities, add relationships, run analytics, summarise graph, run reasoning, export graph, query the live graph, update nodes, archive nodes.
 - **3 Readable Resources** — Live graph JSON (`semantica://graph/summary`), decision list, and schema/version info: readable by any MCP client.
 - **Zero Infrastructure** — Runs over stdio: no server, no port, no Docker required. One config block to activate in any MCP client.
 - **Persistent Graphs** — Point `SEMANTICA_KG_PATH` at a saved graph file to reload it automatically on every server startup.
@@ -159,7 +159,7 @@ The MCP server is included in the base install: no extras required.
 
 ## Tools
 
-The MCP server exposes 12 tools that any connected AI assistant can call:
+The MCP server exposes 15 tools that any connected AI assistant can call:
 
 | Tool | Category | Description |
 | :---- | :-------- | :----------- |
@@ -173,6 +173,9 @@ The MCP server exposes 12 tools that any connected AI assistant can call:
 | `add_relationship` | Graph Operations | Add a directed edge between two nodes |
 | `get_graph_summary` | Graph Operations | Node count, decision count, graph status |
 | `get_graph_analytics` | Graph Operations | PageRank centrality and community detection |
+| `query_graph` | Graph Operations | Fetch a node, traverse its neighbours, or keyword-search nodes |
+| `update_node` | Graph Operations | Merge properties onto a node and persist to `SEMANTICA_KG_PATH` |
+| `delete_node` | Graph Operations | Soft-delete (archive) a node and persist to `SEMANTICA_KG_PATH` |
 | `run_reasoning` | Reasoning | Forward-chain IF/THEN rules over facts |
 | `export_graph` | Reasoning & Export | Serialise the graph (`turtle`/`ttl`: RDF Turtle aliases, `nt`, `xml`, `json-ld`, `json`) |
 
@@ -386,6 +389,51 @@ Takes no input parameters.
 
 </Accordion>
 
+<Accordion title="query_graph" icon="magnifying-glass">
+
+Read the live graph in one of three modes, set by `mode`:
+
+- `node` — return a single node by `node_id`.
+- `neighbors` (default) — traverse outward and inward from `node_id` up to `depth` hops (clamped to 1-5, default 1). Optional `relationship_types` filters edge types; optional `limit` caps results.
+- `search` — keyword match `query` against each node's id and content. Optional `node_type` restricts the scan; `limit` defaults to 50.
+
+**Input:**
+
+```json
+{ "mode": "neighbors", "node_id": "apple_inc", "depth": 2 }
+```
+
+</Accordion>
+
+<Accordion title="update_node" icon="pen">
+
+Merge a set of properties onto an existing node. The change is applied in memory and, when `SEMANTICA_KG_PATH` is set, written back to that file so it survives a restart. Returns `persisted: false` when no path is configured.
+
+**Input:**
+
+```json
+{
+  "node_id": "task_42",
+  "properties": { "status": "done", "note": "shipped in v0.6.7" }
+}
+```
+
+`node_id` and a non-empty `properties` object are required. Updating a missing node returns an error.
+
+</Accordion>
+
+<Accordion title="delete_node" icon="box-archive">
+
+Soft-delete a node: it stays in the graph for history but is marked `status: "archived"`. Persists to `SEMANTICA_KG_PATH` when configured.
+
+**Input:**
+
+```json
+{ "node_id": "task_42" }
+```
+
+</Accordion>
+
 </AccordionGroup>
 
 ### Reasoning