From 79a175358f539fa1c40eed298998ebd8d6c1a595 Mon Sep 17 00:00:00 2001
From: atagen <boss@atagen.co>
Date: Mon, 23 Jun 2025 20:28:59 +1000
Subject: [PATCH] chore: update README.md

---
 README.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 74 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 4689293..bdab4cf 100644
--- a/README.md
+++ b/README.md
@@ -10,12 +10,13 @@ tag based management is relatively intuitive - sets of windows are assigned nume
 these tags are then de/activated to raise and lower the windows. \
 only a single workspace is ever in active use per output.
 
-## usage
+# usage
 
-### typical unix
+## typical unix
 
 first,\
 clone the repo.\
+clone a niri source tree into a subdirectory called niri - make sure it is the same release you are running.
 build and install with cargo as per usual for rust projects on your platform.
 
 next,\
@@ -43,7 +44,7 @@ niri's `exec-once` *should* also be okay, but the use of a service manager is hi
 finally,\
 set up niri binds using `tagctl` to control windows and tags as you see fit.
 
-### nixos (flakes)
+## nixos (flakes)
 
 first,\
 add the following to your flake inputs:
@@ -73,7 +74,7 @@ in
 ...
 ````
 
-### bindings
+## bindings
 
 first,\
 it is recommended that you unset all workspace related binds, as
@@ -94,5 +95,73 @@ all commands (except `remove`) take a tag number from 1-255 after their command.
 finally,\
 you may now use the aforementioned binds to assign tags to windows and toggle the tags on and off to hide/reveal them.
 
-enjoy !
+## config
 
+configs are expected to be located at `$XDG_CONFIG_DIR/niri-tag/config.toml`.\
+they are simple, headerless toml files.
+
+the current config options (and their defaults) are:
+````toml
+# prepopulates a certain number of tags, from 1-255.
+# this is useful for getting the full number of tags you intend to use
+# premade and sent in any initial event stream connection.
+prepopulate = 3
+
+# strict workspaces
+# this prevents you from switching away from the workspaces that were on each monitor
+# when niri-tag was started, ensuring you don't accidentally break the window management
+# paradigm, or get your desktop stuck in a weird state.
+strict = true
+
+ ````
+
+## ipc
+
+### command socket
+`tagctl` is a simple wrapper over a one-shot socket connection to the niri-tag ipc, a socket which should be available at `$XDG_RUNTIME_DIR/niri-tag.sock`.\
+this socket accepts all the `tagctl` commands, as formatted in PascalCase rather than kebab-case, and sent as a single JSON object per connection (for now) followed by a line ending.
+
+as an example,
+````json
+{"EnableTag":4}
+
+  
+````
+
+### event stream socket
+there is a stream of events available via `$XDG_RUNTIME_DIR/niri-tag-events.sock`.
+
+on initial connection, you will be sent your first and only `TagFullState` event, a JSON object summarising the entire state of the tag system, sent in similar fashion to the command socket.
+
+following that, a stream of tag events with one JSON object per line will be sent for every niri-tag operation, until you close the connection.
+
+#### events
+
+here is a summary of possible events:
+
+````json
+{"TagEmpty": int} // tag no longer contains any windows
+{"TagOccupied": int} // tag now contains window/s
+{"TagUrgent": int} // tag has window signaling urgency
+{"TagEnabled": int} // tag now enabled
+{"TagDisabled": int} // tag  now disabled
+{"TagExclusive": int} // tag has been enabled to exclusion of all others
+{"TagFullState": {
+ "1": {
+    "enabled": bool,
+    "occupied": bool,
+    "urgent": bool
+  },
+  ... // more tags detailed in similar fashion
+ }
+} // a full account of the tag state, sent only once on connection
+````
+
+## acknowledgements
+- YaLTeR - for creating niri and blessing it with excellent IPC
+- sodiboo - for niri-flake
+- outfoxxed - for advice on XDG, IPC, and other TLA
+- notashelf - a man so bald he can blind you at a glancing angle
+- me - for writing this excellent program
+
+enjoy !