diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index a0e3329..1fe859f 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -71,6 +71,57 @@ borders {
 
 Colors are specified in `0xRRGGBB` or `0xRRGGBBAA` hex format.
 
+## Window Rules
+
+Window rules let you set certain properties on windows when they first appear,
+based on their `app_id` and/or `title`. Crucially, you can override them any time after
+that, it's only when the window is first created. Rules are placed inside a `window_rules` block:
+
+```kdl
+window_rules {
+    // Float Firefox picture-in-picture windows
+    float app_id="firefox" title="Picture-in-Picture"
+    // Float any window with "Preferences" in the title
+    float title="*Preferences*"
+    // Keep mpv windows tiled
+    no_float app_id="mpv"
+    // Send Slack to tag 3 (1<<2 = 0x0004)
+    tags 0x0004 app_id="Slack"
+}
+```
+
+### Rule Types
+
+| Rule       | Argument         | Description                              |
+|------------|------------------|------------------------------------------|
+| `float`    |                  | Make matching windows float              |
+| `no_float` |                  | Keep matching windows tiled              |
+| `tags`     | u32 (bitmask)    | Assign matching windows to specific tags |
+
+### Matching
+
+Each rule can have an `app_id=` and/or `title=` property. Both support glob patterns:
+
+| Pattern       | Matches                        |
+|---------------|--------------------------------|
+| `"foo"`       | Exact match only               |
+| `"foo*"`      | Starts with "foo"              |
+| `"*foo"`      | Ends with "foo"                |
+| `"*foo*"`     | Contains "foo"                 |
+| `"*"`         | Everything                     |
+
+A rule with no `app_id=` or `title=` property matches all windows. If both are
+specified, both must match.
+
+### Evaluation
+
+Rules are evaluated top-to-bottom. Each matching rule applies only the properties it
+specifies, so multiple rules can contribute different properties to the same window.
+For the same property, later rules override earlier ones.
+
+Rules are applied once during window initialization. Title changes after initialization
+do not re-trigger rules.
+
 ## Bar
 
 The bar is an optional widget that shows the time on your screen. Right now, that's it.
diff --git a/docs/TODO.md b/docs/TODO.md
index ed3c048..531002e 100644
--- a/docs/TODO.md
+++ b/docs/TODO.md
@@ -2,6 +2,8 @@
 
 These are in rough order of my priority, though no promises I do them in this order.
 
+- [ ] Move orphan handling out of .output and .seat events; into manage()
+- [ ] Add focused window title to bar
 - [ ] Support overriding config location
 - [ ] Support configuring primary vs secondary stack side
 - [ ] Support switch handling (e.g. lid close)
diff --git a/examples/config.kdl b/examples/config.kdl
index 9be9915..63e09e6 100644
--- a/examples/config.kdl
+++ b/examples/config.kdl
@@ -18,11 +18,11 @@ borders {
     color_focused "0x89b4fa"
     color_unfocused "0x1e1e2e"
 }
-// Bar widget - shows the time
+// Bar widget; shows the time
 bar {
     position top
 }
-// Tag overlay widget - shown briefly when switching tags
+// Tag overlay widget; shown briefly when switching tags
 // Remove this block to disable the overlay entirely
 tag_overlay {
     tag_amount 10
@@ -35,6 +35,18 @@ tag_overlay {
     square_inactive_border_color "0x6c7086"
     square_inactive_occupied_color "0xcdd6f4"
 }
+// Window rules; applied once when a window first appears
+// Rules are evaluated top-to-bottom; later rules override earlier ones
+window_rules {
+    // Float Firefox picture-in-picture windows
+    float app_id="firefox" title="Picture-in-Picture"
+    // Float any window with "Preferences" in the title
+    float title="*Preferences*"
+    // Keep mpv windows tiled
+    no_float app_id="mpv"
+    // Send Slack to tag 3 (1<<2 = 0x0004)
+    tags 0x0004 app_id="Slack"
+}
 keybinds {
     // Swap a window
     spawn Mod4 T foot