1 files changed, 46 insertions, 0 deletions
diff --git a/hosts/README.md b/hosts/README.md
new file mode 100644
index 0000000..1be1dd7
--- /dev/null
+++ b/hosts/README.md
@@ -0,0 +1,46 @@
+# hosts
+
+The LAN map from the Obsidian vault as a searchable list, over a dimmed
+screen. ALT+SHIFT+Return opens it, Escape or a click outside closes it. It
+replaces the rofi SSH menu, `blackpearl-sshmenu.sh`.
+
+Each card shows a host's `ip:port`, its hostname, the Proxmox node and CT id
+it runs on, and the actions its data allows:
+
+- `ssh <alias>`, one per `~/.ssh/config` alias pointing at it, in a kitty tab
+  (`ssh-tab`, lifted from the rofi script);
+- `open`, when the note has a `url`;
+- `copy <ip:port>`, through `wl-copy`.
+
+Type to filter (every word must match name, ip, port, hostname, node, CT id
+or alias), Up/Down to move, Enter runs the first action, chips run their own.
+
+`hosts.py` builds the list on every opening, so there is no cache. It reads
+the frontmatter of each note in the vault's `Local Network/services/`
+(`HOSTS_DIR` overrides the path) and the ssh config. An alias joins the note
+whose `ip` or `hostname` is its `HostName`, or whose short hostname is the
+alias; an alias that matches no note gets a card of its own, so everything
+the rofi menu listed is still here. Aliases with the same `HostName` share a
+card. Like the rofi script, it reads plain `Keyword value` lines only:
+`Include` and `Match` are not followed, wildcard `Host` patterns are skipped.
+
+## Running
+
+    qs -p ./hosts
+    qs -p ./hosts ipc call hosts toggle
+
+## Blur
+
+Optional, in the Hyprland config:
+
+    hl.layer_rule({
+        name         = "blur-hosts",
+        match        = { namespace = "^(keystone-hosts)$" },
+        blur         = true,
+        xray         = false,
+        ignore_alpha = 0.1,
+    })
+
+## Check
+
+    /usr/bin/python3 hosts/hosts.py --check