Merge pull request #19 from SolidLabResearch/codex/repo-followup-polish

repo: expose storage health and trim stale docs

Author: argahsuknesib

.github/copilot-instructions.md

@@ -186,7 +186,6 @@ Minimal dependency philosophy:
 - `src/storage/indexing/dictionary.rs` (172 lines) - Dictionary encoding
 - `tests/dictionary_encoding_test.rs` (624 lines) - Comprehensive integration tests
 - `BENCHMARK_RESULTS.md` - Performance metrics and analysis
-- `ARCHITECTURE.md` - High-level design (note: mentions TypeScript, but actual impl is Rust)
 - `Makefile` - Common development commands
 
 # Copilot Instructions

.github/workflows/docs-links.yml

@@ -0,0 +1,20 @@
+name: Docs Link Check
+
+on:
+  pull_request:
+    branches: [main, develop]
+    paths:
+      - "**/*.md"
+      - ".github/workflows/docs-links.yml"
+      - "scripts/check_doc_links.sh"
+
+jobs:
+  docs-links:
+    name: Validate Markdown Links
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Check local markdown links
+        run: bash scripts/check_doc_links.sh

GETTING_STARTED.md

@@ -40,10 +40,7 @@ cargo run --example http_client_example
 That example covers query registration, start, stop, replay control, and
 WebSocket result consumption.
 
-## Optional Local Demo UI
-
-This repository keeps a small static demo at
-`examples/demo_dashboard.html` for manual browser testing.
+## Optional Frontend
 
 The maintained Svelte dashboard lives in the separate
 `SolidLabResearch/janus-dashboard` repository.
@@ -75,9 +72,9 @@ make ci-check
 - `src/stream`: live stream processing
 - `src/storage`: segmented RDF storage
 - `src/bin`: executable binaries
-- `examples`: runnable examples and a minimal static demo
+- `examples`: runnable examples, including the HTTP client example
 - `tests`: integration coverage
-- `docs`: current docs plus older design notes
+- `docs`: current product docs plus a small amount of retained background material
 
 ## Where to Read Next
 

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help build test clean fmt lint check ci-check install run dev doc bench audit deps update watch all release
+.PHONY: help build test clean fmt lint check ci-check install run dev doc bench audit deps update watch all release doc-links
 
 # Default target
 .DEFAULT_GOAL := help
@@ -59,6 +59,10 @@ lint: ## Run clippy lints
 check: fmt-check lint ## Run all checks (formatting and linting)
 	@echo "$(GREEN)All checks passed!$(NC)"
 
+doc-links: ## Check local markdown links
+	@echo "$(BLUE)Checking markdown links...$(NC)"
+	@bash ./scripts/check_doc_links.sh
+
 ci-check: ## Run full CI/CD checks locally before pushing
 	@echo "$(BLUE)Running CI/CD checks...$(NC)"
 	@./scripts/ci-check.sh

README.md

@@ -70,8 +70,6 @@ The maintained dashboard lives in a separate repository:
 
 - `https://github.com/SolidLabResearch/janus-dashboard`
 
-The `janus-dashboard/` folder in this repository is a lightweight local demo client, not the primary frontend.
-
 ## Performance
 
 Janus uses dictionary encoding and segmented storage for high-throughput ingestion and historical reads.
@@ -129,9 +127,7 @@ This example demonstrates:
 The maintained web dashboard lives in the separate
 `SolidLabResearch/janus-dashboard` repository.
 
-This repository keeps a small static demo at
-[`examples/demo_dashboard.html`](./examples/demo_dashboard.html) for manual API
-testing, but frontend development should happen in the dedicated dashboard repo.
+Frontend development should happen in the dedicated dashboard repo.
 
 ## Development
 
@@ -155,7 +151,6 @@ The repository includes runnable examples under [`examples/`](./examples), inclu
 
 - [`examples/http_client_example.rs`](./examples/http_client_example.rs)
 - [`examples/comparator_demo.rs`](./examples/comparator_demo.rs)
-- [`examples/demo_dashboard.html`](./examples/demo_dashboard.html) for a minimal local demo
 
 ## Documentation
 
@@ -169,7 +164,8 @@ Start here:
 
 ## Notes
 
-- `src/main.rs` is currently a benchmark-style executable, not the main user-facing interface.
+- `src/main.rs` is now a lightweight entry binary that points to the main Janus
+  executables and benchmark helpers.
 - The primary user-facing entry point is `http_server`.
 
 ## Licence

START_HERE.md

@@ -18,7 +18,7 @@ cargo run --example http_client_example
 
 - `http_server` is the main backend entry point
 - `stream_bus_cli` is the ingestion and replay CLI
-- `examples/demo_dashboard.html` is a minimal manual demo
+- `examples/http_client_example.rs` is the fastest local API exercise
 - the maintained Svelte dashboard lives in the separate `janus-dashboard` repository
 
 ## Current Docs

docs/ARCHITECTURE.md

@@ -58,20 +58,8 @@ This is the shortest path to understanding the current Janus implementation.
 - [README_HTTP_API.md](./README_HTTP_API.md)
 - [QUICKSTART_HTTP_API.md](./QUICKSTART_HTTP_API.md)
 
-## Legacy Material
-
-The following files remain useful as background, but they are not the main entrypoint for the current code:
-
-- [ARCHITECTURE.md](./ARCHITECTURE.md)
-- [EXECUTION_ARCHITECTURE.md](./EXECUTION_ARCHITECTURE.md)
-- [MVP_ARCHITECTURE.md](./MVP_ARCHITECTURE.md)
-- [MVP_TODO.md](./MVP_TODO.md)
-- [RSP_INTEGRATION_COMPLETE.md](./RSP_INTEGRATION_COMPLETE.md)
-- [SPARQL_BINDINGS_UPGRADE.md](./SPARQL_BINDINGS_UPGRADE.md)
-
 ## Dashboard Boundary
 
-- Local demo dashboard in this repository: `examples/demo_dashboard.html`
 - Maintained dashboard repository: `https://github.com/SolidLabResearch/janus-dashboard`
 
 ## Related Code