1 files changed, 46 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..24adbac
--- /dev/null
+++ b/README.md
@@ -0,0 +1,46 @@
+# quickshell
+
+Quickshell components for a Hyprland desktop, each one self-contained in its
+own directory. They are separate shells, not modules of a single bar: any of
+them can run alone, and running one does not require the others.
+
+Visually they follow [unified-desktop-theme][udt]: Catppuccin Macchiato as the
+fixed base, Noto Sans for UI text, and an accent that tracks the wallpaper.
+That accent is read from the file `udt-accent` already writes, so the two
+repos stay independent, this one has no build-time dependency on that one.
+
+[udt]: ../unified-desktop-theme
+
+## Implementations
+
+    volume-osd/     on-screen display for output and input volume
+
+Each directory has its own README covering what it does and how to run it.
+
+## Running one
+
+    qs -p ./volume-osd
+
+To start it with the session, from Hyprland:
+
+    exec-once = qs -p ~/Programming/GIT/quickshell/volume-osd
+
+Quickshell uses private Qt APIs, so it must be rebuilt after every Qt update.
+`qs --version` should report the same Qt as the installed one.
+
+Some components ask the compositor for an effect they cannot draw themselves,
+such as the blur behind `volume-osd`. Those rules live in the Hyprland config
+rather than here, and each component's README gives the block to add. They are
+optional: without the rule the component renders without that effect.
+
+## License
+
+GPLv2 only. See `LICENSE`.
+
+## Development Approach
+
+This project is developed using AI-assisted tools. Code is generated with the help of AI based on human-provided specifications, design decisions, and iterative feedback.
+
+All contributions are reviewed, tested, and curated by the maintainer before being included in the codebase. AI is used as a productivity and exploration tool, while human oversight remains central to all decisions.
+
+The goal is to combine the flexibility of AI-assisted development with standard open-source practices such as transparency, review, and accountability.