dimknaf · dimknaf · May 25, 2026 · May 25, 2026 · May 25, 2026 · May 25, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,46 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] — 2026-05-25
+
+Headline: a small read-only frontend lands so humans can browse the same
+knowledge graph the agents read and write to. Plus a YouTube walkthrough
+linked from the README, and the merged contribution from @WarGloom that
+tightens up the relations endpoints.
+
+### Added
+
+- **Frontend** (`frontend/`): vanilla-JS, no build step, no npm.
+  - **Reader** — left rail wiki index + elastic-debounced semantic search
+    with type-pill breakdown, central wiki body with citation chips,
+    right-rail Relations panel that resolves every endpoint to a readable
+    chip (type pill + canonical name) rather than a raw UUID.
+  - **Graph** — force-layout view with custom shapes per entity type.
+    Physics is one-shot (off after first settle) and new nodes added on
+    expansion are placed in a deterministic ring around the click target,
+    so the graph never drifts under the user's mouse. Zoom buttons,
+    scroll-wheel zoom, drag-pan, retired-wiki badge in the search dropdown.
+  - **Ops** — pipeline-queue and activity-log tables with actor pills
+    (Maintainer / Writer / Scheduler / Watcher), readable target-wiki +
+    entity chips, zebra stripes, and a NOTE column that distinguishes
+    benign rationale from real errors.
+  - **Ask drawer** — a textarea that posts to the agent endpoint
+    (`POST /api/v1/agent/query`) with the same async semantics as the
+    Claude Code skill (long calls supported).
+  - **Universal entity-chip resolver**: a small async helper is wired into
+    every render site that previously showed a UUID — relations, jobs,
+    log rows, drawer titles. Cached after first fetch.
+- **YouTube walkthrough**: linked from `README.md`
+  ([youtu.be/AJ7iMOj4vvA](https://youtu.be/AJ7iMOj4vvA)).
+- **README**: new "Frontend (optional, read-only)" section with one-line
+  serve instructions.
+
+### Changed
+
+- **Relations endpoint hardening** — merges @WarGloom's
+  [PR #5](https://github.com/dimknaf/braindb/pull/5): missing relation
+  endpoints now reject cleanly instead of returning a confusing 200.
+
 ## [0.2.0] — 2026-05-24
 
 The first substantial release beyond the v0.1.0 memory-store baseline. The

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -87,6 +87,7 @@ braindb/
 ├── skills/                            # Shipped Claude Code skills
 │   ├── braindb/SKILL.md               # Direct curl-based skill
 │   └── braindb-agent/SKILL.md         # Thin wrapper around the agent endpoint
+├── frontend/                          # Read-only browser UI — vanilla JS, no build
 ├── docker-compose.yml                 # api + watcher services (external PostgreSQL)
 ├── .env                               # Real credentials — DO NOT COMMIT
 └── BRAINDB_GUIDE.md                   # Full API reference with curl examples

diff --git a/README.md b/README.md
@@ -1,5 +1,9 @@
 # BrainDB
 
+[![BrainDB walkthrough](https://img.youtube.com/vi/AJ7iMOj4vvA/maxresdefault.jpg)](https://youtu.be/AJ7iMOj4vvA "Watch the BrainDB walkthrough on YouTube")
+
+> **▶ Watch the walkthrough:** [youtu.be/AJ7iMOj4vvA](https://youtu.be/AJ7iMOj4vvA) — Karpathy's LLM wiki idea, on a SQL database, driven by REST APIs.
+
 A memory database and REST API for LLM agents. Store and retrieve thoughts, facts, sources, documents, and behavioral rules — with fuzzy + semantic keyword search, graph traversal up to 3 hops, temporal decay, and always-on rule injection. Built to be driven externally by an LLM via HTTP calls.
 
 It also ships with **its own internal agent** (OpenAI Agents SDK + LiteLLM with pluggable providers — **DeepInfra is the recommended default**, with NIM / local vLLM / others available via config) so external callers can talk to BrainDB in plain English via a single endpoint instead of orchestrating individual API calls.
@@ -307,6 +311,16 @@ automatically. To run without it, bring the stack up excluding the service or
 scale it to 0 (`docker compose up -d --scale wiki_scheduler=0`), exactly as
 you would for the watcher; or point `LLM_PROFILE` at a local model.
 
+## Frontend (optional, read-only)
+
+A small vanilla-JS frontend ships under `frontend/` — no build step. Three views (Reader for browsing wikis, Graph for visual exploration, Ops for watching the maintainer/writer pipeline) plus an Ask drawer that talks to the agent endpoint. Talks to the BrainDB API at `http://localhost:8000`. Serve it from the repo root:
+
+```bash
+cd frontend && python -m http.server 8090
+```
+
+Then open `http://localhost:8090`. See [frontend/README.md](frontend/README.md) for the design notes.
+
 ## Stack
 
 - Python 3.12 + FastAPI + psycopg2 (sync, no ORM)

diff --git a/frontend/README.md b/frontend/README.md
@@ -0,0 +1,69 @@
+# BrainDB frontend
+
+A thin, read-mostly browser UI for BrainDB. Vanilla HTML / CSS / JS — no build, no npm, no framework.
+
+## Run
+
+The BrainDB backend must be running first (default: `http://localhost:8000`). From the repo root:
+
+```bash
+python -m http.server 8090 -d frontend
+```
+
+Then open <http://localhost:8090>.
+
+That's it. The frontend is a static page that talks to the API directly via `fetch`. CORS is already open on the backend.
+
+> If `8090` is in use on your machine, pick any free port: `python -m http.server <PORT> -d frontend`. (Avoid `8080` on Windows with Docker Desktop installed — it's commonly held by the WSL backend.)
+
+## Pointing at a non-local backend
+
+If your API lives somewhere other than `localhost:8000`, set `window.BRAINDB_API_URL` before `app.js` loads — e.g. inject a small `<script>window.BRAINDB_API_URL="https://my-host:8000"</script>` before the module tag in `index.html`.
+
+## What's in here
+
+| File | Purpose |
+|---|---|
+| `index.html` | Layout shell: top bar with Reader / Graph / Ops tabs, the Reader grid (rail / wiki body / relations), the Graph view (Cytoscape canvas + toolbar + legend), the Ops grid (stats / queue / log / rules), and two slide-over drawers (entity / Ask). Loads Cytoscape + fCoSE from a CDN. |
+| `style.css` | Design language: near-monochrome palette, refined serif for body, clean grotesque for UI, hairline rules, one restrained accent. Light + dark via `data-theme` on `<html>`. Graph view tokens included. |
+| `wiki-render.js` | Small Markdown-ish renderer specialised for the BrainDB wiki body grammar — `<!-- wiki:meta -->`, headings, `> **Summary:** / **Disambiguation:**` callouts, `<!-- section:slug -->` dividers, GFM tables, lists, `**bold**`, `` `code` ``, and `[[ref:UUID]]` / `[[ref:UUID|display]]` citation chips (tolerant of the grouped form). |
+| `graph.js` | Cytoscape.js integration: per-entity-type shapes/colours, edge-label-on-hover, click → entity drawer, double-click → expand 1-hop neighbourhood, 300-node soft cap. |
+| `app.js` | Data layer + routing + Ops auto-refresh + Ask drawer wiring + Graph tab wiring. ES module; imports `wiki-render.js` and `graph.js`. |
+
+## Keyboard
+
+- `/` — focus the search box (Reader)
+- `Cmd/Ctrl+K` — open the Ask drawer
+- `Esc` — close any open drawer
+- `F` — fit graph to viewport (Graph tab)
+
+## Graph tab — quick tour
+
+- Open a wiki in **Reader**, then click the **Graph** tab → the graph seeds with that wiki and its direct neighbours (keywords, facts, sources).
+- Cold-start the Graph tab → empty canvas with a search box; pick a result to seed.
+- **Click** any node → opens the entity drawer (same one Reader uses).
+- **Double-click** a node → expands its 1-hop neighbourhood.
+- Scroll to zoom, drag empty space to pan. Soft-capped at 300 nodes.
+
+## Endpoints used
+
+Read-only except where intentional:
+
+- `GET /api/v1/entities?entity_type=wiki` — wiki index
+- `GET /api/v1/entities/{id}` — full entity (wiki body, fact, thought, …)
+- `GET /api/v1/entities/{id}/relations` — relations of one entity
+- `GET /api/v1/wiki/jobs` — Ops queue
+- `GET /api/v1/memory/log` — Ops activity log
+- `GET /api/v1/memory/stats` — Ops stats strip
+- `GET /api/v1/memory/rules` — Ops rules list
+- `POST /api/v1/memory/context` — search (the modern keyword-mediated path)
+- `POST /api/v1/agent/query` — the Ask drawer
+
+No `/memory/sql`. No direct database access. No write outside the user-driven Ask drawer.
+
+## External dependencies (CDN, optional)
+
+- [Cytoscape.js](https://js.cytoscape.org/) 3.30.4 — graph rendering for the Graph tab.
+- [cytoscape-fcose](https://github.com/iVis-at-Bilkent/cytoscape.js-fcose) 2.2.0 — force-directed layout for the Graph tab.
+
+Both are loaded from `unpkg.com` in `index.html` with pinned versions. If the CDN is unreachable, the Graph tab shows an error message and the rest of the app (Reader / Ops / Ask) continues to work.