Skip to content

Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring

docs: say the documentation space exists

Pouzor4bcba084db2a
diff --git a/FEATURES.md b/FEATURES.md
index 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 swit
10. [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.md
index b3d6d1d..8abe442 100644
--- a/README.md
+++ b/README.md
@@ -35,6 +35,8 @@ Homelable is a self-hosted infrastructure visualization solution. It provides a
Homelable 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 Scanner
The 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.md
index 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 a
document 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 aggregated
open-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 the
planned second lot.