Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring
TypeScript diagramhomelabhomelab-infrastructure-observabilitynetworkproxmox-veself-hostedzigbeezwavezwave-js
docs: say the documentation space exists
Pouzor4bcba084db2a
diff --git a/FEATURES.md b/FEATURES.mdindex 7a8aebc..f0e3239 100644--- a/FEATURES.md+++ b/FEATURES.md@@ -24,13 +24,14 @@ Here's what Homelable can do. One line on what each feature is, then how to swit10. [Z-Wave Import](#10-z-wave-import-)11. [Proxmox VE Import](#11-proxmox-ve-import-)12. [Device Inventory](#12-device-inventory-)-13. [Live Status Monitoring](#13-live-status-monitoring-)-14. [Export (PNG / SVG / YAML / Markdown)](#14-export)-15. [Live View (read-only public canvas)](#15-live-view-)-16. [Gethomepage Widget](#16-gethomepage-widget-)-17. [MCP Server (AI integration)](#17-mcp-server-)-18. [Settings & Shortcuts](#18-settings--shortcuts)-19. [Authentication (Local / OpenID Connect)](#19-authentication-local--openid-connect-)+13. [Documentation](#13-documentation-)+14. [Live Status Monitoring](#14-live-status-monitoring-)+15. [Export (PNG / SVG / YAML / Markdown)](#15-export)+16. [Live View (read-only public canvas)](#16-live-view-)+17. [Gethomepage Widget](#17-gethomepage-widget-)+18. [MCP Server (AI integration)](#18-mcp-server-)+19. [Settings & Shortcuts](#19-settings--shortcuts)+20. [Authentication (Local / OpenID Connect)](#20-authentication-local--openid-connect-)---@@ -187,7 +188,25 @@ Nodes: `proxmox` (host) / `vm` / `lxc`, linked host→guest by a `virtual` edge.----## 13. Live Status Monitoring 🔒+## 13. Documentation 🔒++**What:** A markdown documentation space for the whole lab. Every device gets a document written once from what the scan actually found — identity, hardware, services, network, operations, troubleshooting — and it is yours from there; nothing rewrites it behind you. Next to it, a Library of pages you write yourself: runbooks, incidents, decisions, a network overview.++**Use:**+- Sidebar → **Documentation**. The **Devices** root re-pivots instantly by zone, group, type, physical/virtual, subnet, rack, vendor, discovery source, status, tag or A–Z; picking a device with no document writes one from its facts.+- The **Library** is folders you make. **New page** / **New folder** in the header, drag an item to file it. Templates: blank, runbook, service, network overview, incident, procedure, decision (ADR), zone.+- Editing is plain markdown and **saving is explicit**, like the canvas. An unsaved body is kept in your browser and offered back if you close the tab. `/` in the editor inserts a freshly generated block — services, hardware, network, rack — from the device's current data.+- **Link documents** with `[[VLAN plan]]`, `[[device:nas-01]]` or `[[doc:slug|label]]`. A link to a document that does not exist yet renders red and offers to create it, and every document lists **Linked from** at the bottom — who points here.+- **History**: the clock-arrow button in the header lists earlier versions, up to 50 per document. Read one, hit **Changes** for a line-by-line diff against the current body, **Restore** to bring it back — the body it replaces is saved to the history first.+- **Keeping it honest**: `review_every: 6m` in a document's frontmatter badges it "due for review" when it lapses; a **device data changed** banner appears when the device has moved on since the document was written; **Regenerate** rebuilds a device document from scratch (old body kept in the history). Tags are chips under the title.+- **Search** the whole space from the box above the tree — title, tags and body.+- Coming from the old per-device **Notes** field? A banner offers to migrate every device that has one into a document. It copies, it does not move: the `notes` field is left exactly as it was.++> **Full documentation:** [docs/documentation.md](./docs/documentation.md)++---++## 14. Live Status Monitoring 🔒**What:** Keeps checking each node and shows its status (🟢 online / 🔴 offline / ⚫ unknown) right on the canvas.@@ -208,7 +227,7 @@ Nodes: `proxmox` (host) / `vm` / `lxc`, linked host→guest by a `virtual` edge.----## 14. Export+## 15. Export**What:** Get your canvas out as a picture or as structured data.@@ -220,7 +239,7 @@ Nodes: `proxmox` (host) / `vm` / `lxc`, linked host→guest by a `virtual` edge.----## 15. Live View 🔒+## 16. Live View 🔒**What:** A read-only, no-login snapshot of a canvas you can share on your LAN. Off by default.@@ -232,7 +251,7 @@ Pan and zoom only, no editing. Click a node with an IP and it opens in a new tab----## 16. Gethomepage Widget 🔒+## 17. Gethomepage Widget 🔒**What:** A tiny JSON stats endpoint for [gethomepage](https://gethomepage.dev)'s `customapi` widget. Off by default.@@ -244,7 +263,7 @@ Widget snippet lives in the [README](./README.md#gethomepage-widget-read-only-st----## 17. MCP Server 🔒+## 18. MCP Server 🔒**What:** A [Model Context Protocol](https://modelcontextprotocol.io) server so an MCP client (Claude Code, Claude Desktop, Open WebUI…) can read and change your topology. Optional, runs as its own service.@@ -262,7 +281,7 @@ The AI can list nodes/edges/canvas/zones/designs/inventory/scans, add/update/del----## 18. Settings & Shortcuts+## 19. Settings & Shortcuts**What:** App config and keyboard shortcuts.@@ -273,7 +292,7 @@ The AI can list nodes/edges/canvas/zones/designs/inventory/scans, add/update/del----## 19. Authentication (Local / OpenID Connect) 🔒+## 20. Authentication (Local / OpenID Connect) 🔒**What:** Homelable protects the app behind a login. Two exclusive modes, set once in `.env` with `AUTH_MODE`:- **`local`** (default) — a single username + bcrypt-hashed password. Nothing changes for existing installs.diff --git a/README.md b/README.mdindex b3d6d1d..8abe442 100644--- a/README.md+++ b/README.md@@ -35,6 +35,8 @@ Homelable is a self-hosted infrastructure visualization solution. It provides aHomelable also offers a healthcheck system through multiple methods (ping/TCP, /health API, etc.) to get a global overview of online/offline services.+Every device also gets a **document** — written for you from what the scan found, and yours to maintain from there — next to a Library of pages you write yourself: runbooks, incidents, a network overview. Your homelab stops being documented in a wiki somewhere else.+You can also select some pre-built design styles, or personalize each device in your diagram.If you just like the design, you can only run the frontend and export your design as PNG.@@ -57,7 +59,7 @@ If you are running <img width="22" height="22" align="top" alt="New_Home_Assist## Features-From one-click **network scans** and **Proxmox / Zigbee / Z-Wave** imports to **live status monitoring**, floor plans, **rack canvases** with port-to-port patching, multi-canvas layouts and an **MCP server** for AI assistants — Homelable maps and watches your whole homelab.+From one-click **network scans** and **Proxmox / Zigbee / Z-Wave** imports to **live status monitoring**, floor plans, **rack canvases** with port-to-port patching, a **markdown documentation space** for the whole lab, multi-canvas layouts and an **MCP server** for AI assistants — Homelable maps, documents and watches your whole homelab.Every feature, with how to turn it on and use it, is described in **[FEATURES.md](./FEATURES.md)**.@@ -87,6 +89,28 @@ Gear sits in a U range and part of a 12-column width grid, so half- and third-wi---+## Documentation++Homelable keeps its own markdown documentation space, so the lab is described where it is drawn. Sidebar → **Documentation**.++Every device has a document, generated once from what the scan actually found — identity, hardware, one section per service, network, operations, troubleshooting — and never rewritten behind you. Beside it, a **Library** of pages you write: runbooks, incidents, decisions, a network overview, from a template or blank.++### Usage++1. **Pick a device** in the tree — one with no document yet gets one written from its facts. Re-pivot the tree by zone, subnet, type, rack, vendor, tag… at no cost; it is grouped from data the app already holds+2. **Write markdown**, save explicitly — nothing is ever saved behind your back. `/` inserts a freshly generated block (services, hardware, network, rack) from the device's current data+3. **Link things**: `[[VLAN plan]]`, `[[device:nas-01]]`. Each document lists **Linked from** at the bottom, so you can see what points at it+4. **History**: up to 50 versions per document. Read one, diff it against the current body, restore it — what it replaces is kept too+5. **Search** the whole space, tag documents, and set `review_every: 6m` on the ones that rot; a document past its interval is badged as due++A device that changes after its document was written raises a **device data changed** banner, and **Regenerate** rebuilds the document from scratch when you want that. Old per-device **Notes** migrate into documents from a banner, non-destructively.++Full mode only — documents need the backend to store, index and search them.++> **Full documentation:** [docs/documentation.md](./docs/documentation.md)++---+## Network ScannerThe scanner runs `nmap -sV --open` on your configured CIDR ranges and populates a **Pending Devices** queue. From the sidebar you can then approve (adds a node to the canvas), hide, or ignore each discovered device.diff --git a/docs/documentation.md b/docs/documentation.mdindex 3293646..d994124 100644--- a/docs/documentation.md+++ b/docs/documentation.md@@ -124,6 +124,47 @@ ordinary markdown for anything else that reads it.**Raw HTML is deliberately not rendered** — `rehype-raw` is absent — so adocument cannot inject markup and no sanitiser is needed.+### Backlinks++Every document lists what points at it, under **Linked from**, with the line the+link was written on and the label it was written as.++The inversion is done **server-side** (`services/doc_backlinks.py`,+`GET /documents/{id}/backlinks`), because the browser holds no bodies but the+open one: `GET /documents` is metadata-only so the tree can badge without+downloading the space. That service mirrors the resolution rules in+`wikilinks.ts` — same prefixes, same id → slug → title fallback, same+case-insensitivity — the way the generator's `service_url` mirrors+`utils/serviceUrl.ts`. Change one and change the other;+`test_doc_backlinks.py` pins the rules.++Repeated links from the same document collapse into one entry with a count, and+a document never backlinks itself. The inventory is only loaded when some body+actually carries a `[[device:…]]`.++---++## History++Every explicit save that changes the body snapshots the previous one, capped at+`REVISION_LIMIT` (50) per document; so do restore, regenerate, scaffold and the+notes migration, each recording why.++The clock-arrow button in the header opens the history rail: what each version+was (Saved, Regenerated, Restored, Migrated from notes…), when, and how big.+Selecting one replaces the body with that version — same title, same chips, same+rail — and **Changes** turns it into a line diff against the current body, with+long unchanged runs collapsed. **Restore** brings it back, snapshotting the body+it replaces first, so a restore is itself undoable.++A revision's body is fetched only when it is opened: the list carries a size, not+the text, so fifty versions cost one small request.++The diff is a plain LCS over lines (`documentation/diff.ts`), after the common+head and tail are trimmed — no diff library, and a pathological pair of long,+wholly different bodies degrades to "replaced wholesale" instead of building a+250k-cell matrix.+---## Search@@ -166,6 +207,7 @@ Non-destructive and repeatable.| `PATCH` | `/api/v1/documents/{id}` || `DELETE` | `/api/v1/documents/{id}` — a folder takes its subtree || `GET` | `/api/v1/documents/{id}/revisions`, `/revisions/{rev_id}` |+| `GET` | `/api/v1/documents/{id}/backlinks` — the documents linking here || `POST` | `/api/v1/documents/{id}/revisions/{rev_id}/restore` || `POST` | `/api/v1/documents/{id}/regenerate` — erase the body and scaffold it again || `GET` | `/api/v1/documents/search?q=&limit=` |@@ -188,5 +230,6 @@ into `localStorage` with no search and no history.Export/import of the tree as `.md` files, a print/handbook view, an aggregatedopen-tasks view, image upload inside a document (would reuse-`api/routes/media.py`, full-mode only), and the MCP tools — those are the+`api/routes/media.py`, full-mode only), documents in the canvas-wide search+modal, `[[` autocompletion in the editor, and the MCP tools — those are theplanned second lot.