From ee4157d07bc3aeaa12031b8a10a3f9760e75fd17 Mon Sep 17 00:00:00 2001 From: Riz Ashraf Date: Mon, 14 Sep 2026 04:27:00 +0100 Subject: [PATCH] docs: complete final doc sweep for Dashboard UI REST APIs and query_graph_path --- README.md | 14 +++++++++++--- design.md | 13 ++++++++++--- instructions.md | 8 ++++---- 3 files changed, 25 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 3f6f87f..ad42113 100644 --- a/README.md +++ b/README.md @@ -75,16 +75,24 @@ mcp-memory gate verify This queries the daemon (via HTTP) to confirm if pre-push validation (like running tests via PrePushAuditor) has been cleared by the agent. ` ## Brain Monitor Dashboard -The server hosts a live, real-time HTML dashboard called the **Brain Monitor**. It visually tracks the metrics of your Antigravity knowledge graph, such as the total count of Entities, Relations, Tasks, Snippets, and Architectural Decisions (ADRs). +The server hosts a live, real-time SPA dashboard called the **Brain Monitor**. To view the dashboard, simply navigate to the root endpoint in your browser while the server is running: `http://127.0.0.1:3000/` -You can also programmatically query these live metrics via the API endpoint: +### Dashboard Features: +* **Interactive Knowledge Graph:** A full physics-simulated network graph with node-type coloring, a drag-to-pan canvas, and an interactive Inspector Panel. Click any node to instantly view its stored observations. +* **Actionable Kanban Board:** Visually track all active agent Tasks. You can click 'Complete' directly from the UI to trigger a `POST /api/tasks/{id}/complete` REST call back to the daemon without needing the CLI. +* **Sticky Notes & Search:** Browse your ephemeral notes and utilize the integrated fuzzy-search bar to locate graph entities instantly. +* **Native Dark Mode:** Fully styled for modern development environments. + +You can also programmatically query the live backing APIs: `curl http://127.0.0.1:3000/api/stats` +`curl http://127.0.0.1:3000/api/graph` +`curl http://127.0.0.1:3000/api/tasks` ## Further Reading -For a deep dive into the architecture, Write-Ahead Logging (WAL), locking mechanisms, and the HTTP SSE event loop, consult the design.md file in this repository. +For a deep dive into the architecture, the **Redb LSM-tree** embedded database, `tantivy` indexing, and the HTTP SSE event loop, consult the design.md file in this repository. ## Neovim Integration The linux-nvim and win-nvim MCP servers provide direct Msgpack-RPC communication with Neovim. diff --git a/design.md b/design.md index 01b0dd4..54ab35e 100644 --- a/design.md +++ b/design.md @@ -16,10 +16,17 @@ The daemon uses the `axum` and `rust-mcp-axum` crates, binding to `0.0.0.0:3000` * `GET /sse`: The Server-Sent Events (SSE) endpoint. Antigravity clients connect here to keep a one-way pipe open for receiving pushed responses. * `POST /messages`: The JSON-RPC endpoint. Clients use this to send tool calls and resource reads up to the server when connected via SSE. -### Custom Integration Endpoints -* `GET /`: The Brain Monitor live HTML dashboard (returns real-time metrics UI). +### Dashboard REST API +The server hosts a rich Single Page Application (SPA) natively on the root route, backed by a suite of REST endpoints: +* `GET /`: The Brain Monitor live HTML dashboard SPA. +* `GET /api/graph`: Returns the full node/edge topology for the interactive physics-simulated canvas. +* `GET /api/tasks` & `POST /api/tasks/{id}/complete`: Drives the actionable Kanban board. +* `GET /api/sticky` & `GET /api/search`: Powers the sticky notes tab and global fuzzy search UI. * `GET /api/stats`: Returns a JSON snapshot of current entity, relation, task, and tech debt counts. -* `GET /gate/verify`: A lightweight, deterministic endpoint used by external scripts to verify if an action (like a `git push`) is authorized based on the current state. + +### Git & IDE Integration Endpoints +* `POST /nvim/telemetry`: A one-way webhook that Neovim instances hit on `FocusGained` or `BufEnter` to globally broadcast the user's active file to the UI and Agent. +* `GET /gate/verify`: A lightweight, deterministic endpoint used by external scripts (like a `git push` wrapper) to verify if an action is authorized based on the current state. ## 3. Client Connections The Antigravity configurations (`mcp_config.json`) utilize the dual-transport system: diff --git a/instructions.md b/instructions.md index faa87f7..7ed2ab5 100644 --- a/instructions.md +++ b/instructions.md @@ -18,10 +18,10 @@ You do not need to memorize JSON schemas for these tools; they are strictly defi - **When to use:** Use this whenever you make a non-trivial architectural, environmental, or tooling decision (e.g. choosing a specific framework, a specific deployment flag, bypassing a rule with a workaround). - **Behavior:** This permanently stores the context, decision, and consequence of *why* something is done the way it is, preventing future agents from second-guessing or reverting it. -## 10. Graph Refactoring & Maintenance -- **Tools:** merge_entities, ind_orphans -- **When to use:** Run ind_orphans periodically or when you notice graph clutter to safely delete unused nodes. Use merge_entities when you notice duplicated semantic concepts (e.g. API_Gateway vs APIGateway). -- **Behavior:** merge_entities will safely combine their observations and automatically remap all relations pointing to or from the deleted duplicate. +## 10. Graph Refactoring & Algorithms +- **Tools:** merge_entities, find_orphans, query_graph_path +- **When to use:** Run `find_orphans` periodically or when you notice graph clutter to safely delete unused nodes. Use `merge_entities` when you notice duplicated semantic concepts (e.g. API_Gateway vs APIGateway). Use `query_graph_path` when you need to understand how two completely different architectural components are related (e.g. "How does the Frontend connect to the Database?"). +- **Behavior:** `merge_entities` will safely combine their observations and automatically remap all relations pointing to or from the deleted duplicate. `query_graph_path` executes a breadth-first search to find the shortest relational path between nodes. ## 11. Dynamic Learned Preferences - **Tools:** learn_preference,