From 5e35a6a396c0cedaad8c4d8b3a2c6471a16a9f96 Mon Sep 17 00:00:00 2001
From: atagen <boss@atagen.co>
Date: Fri, 20 Jun 2025 11:48:40 +1000
Subject: [PATCH] chore: write readme

---
 README.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..235b167
--- /dev/null
+++ b/README.md
@@ -0,0 +1,98 @@
+# niri-tag
+
+## tag-based window management for the [niri](https://github.com/YaLTeR/niri) compositor
+
+niri-tag allows you to use a simple tagging-based system to manage your windows.
+
+## how tags work
+
+tag based management is relatively intuitive - sets of windows are assigned numeric tags. \
+these tags are then de/activated to raise and lower the windows. \
+only a single workspace is ever in active use per output.
+
+## usage
+
+### typical unix
+
+first,\
+clone the repo.\
+build and install with cargo as per usual for rust projects on your platform.
+
+next,\
+set up niri-tag as a user-level service.\
+for systemd users, something like the following should suffice:
+
+````ini
+# /etc/systemd/user/niri-tag.service
+[Unit]
+Description=Niri Tag Manager
+PartOf=graphical-session.target
+
+[Service]
+ExecStart=/usr/bin/niri-tag
+PrivateTmp=true
+Restart=always
+Type=notify
+
+[Install]
+WantedBy=graphical-session.target
+````
+
+niri's `exec-once` *should* also be okay, but the use of a service manager is highly recommended.
+
+finally,\
+set up niri binds using `tagctl` to control windows and tags as you see fit.
+
+### nixos (flakes)
+
+first,\
+add the following to your flake inputs:
+````nix
+niri-tag = {
+  url = "git+https://git.atagen.co/atagen/niri-tag";
+  inputs.niri-flake.follows = "niri-flake"; 
+  inputs.nixpkgs.follows = "nixpkgs";
+}
+````
+it is assumed you use niri-flake, or else will use the `stable` package output; this is important for the niri IPC definitions.
+
+next,\
+- add `inputs.niri-tag.nixosModules.niri-tag` to your module imports
+- add `services.niri-tag.enable = true;` somewhere in your config
+- if you wish to use a stable niri instead of unstable from niri-flake (default), set `services.niri-tag.package = inputs.niri-tag.packages.${pkgs.system}.stable;`
+
+finally,\
+add binds to your niri configuration.
+
+you will need the path of `tagctl`, which you can get with something like the following:
+````nix
+let
+  niri-tag = inputs.niri-tag.packages.${pkgs.system}.unstable; # or stable
+  tagctl = lib.getExe' niri-tag "tagctl";
+in
+...
+````
+
+### bindings
+
+first,\
+it is recommended that you unset all workspace related binds, as
+switching workspaces or moving windows between them
+while using tag management can cause unexpected behaviours.
+
+next,\
+set up:
+- `Mod+Shift+$number` as a spawn bind for `tagctl toggle $number`
+- `Mod+$number` as `tagctl toggle-tag $number`.
+
+alternatively,\
+you may bind as you see fit the tagctl commands `add` `remove` `toggle` for window tagging,
+and `enable-tag` `disable-tag` `toggle-tag` for managing tags.
+
+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 !
+