diff --git a/src/content/docs/guides/upgrades.mdx b/src/content/docs/guides/upgrades.mdx
index c130134e..1df7da96 100644
--- a/src/content/docs/guides/upgrades.mdx
+++ b/src/content/docs/guides/upgrades.mdx
@@ -28,6 +28,13 @@ package manager.
+ ```bash title="Upgrade komorebi"
+ brew update
+ brew upgrade lgug2z/tap/komorebi-for-mac
+ ```
+
+
+
```bash title="Upgrade komorebi"
brew update
brew upgrade lgug2z/tap/komorebi-for-mac-nightly
diff --git a/src/content/docs/usage/rules.mdx b/src/content/docs/usage/rules.mdx
index c8c83475..16e83233 100644
--- a/src/content/docs/usage/rules.mdx
+++ b/src/content/docs/usage/rules.mdx
@@ -3,4 +3,163 @@ title: Rules
description: Understanding komorebi's rules system
---
-TODO
+import KomorebicPlatformLink from '../../../components/KomorebicPlatformLink.astro';
+import KomorebiConfigPlatformLink from '../../../components/KomorebiConfigPlatformLink.astro';
+import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
+
+
+
+
+
+
+
+
+
+komorebi has a flexible rules system which aims to allow users to handle any
+problematic applications they encounter via configuration rather than requiring
+upstream code changes.
+
+## Matching Rules
+
+Applications or windows are identified using either simple or composite .
+
+Simple matching rules use a against a user-provided identifier targeting an .
+
+
+
+ ```json
+ {
+ "kind": "Exe",
+ "id": "Discord",
+ "matching_strategy": "Equals"
+ }
+ ```
+
+
+ ```json
+ {
+ "kind": "Title",
+ "id": "Cloudflare Dashboard",
+ "matching_strategy": "Contains"
+ }
+ ```
+
+
+ ```json
+ {
+ "kind": "Class",
+ "id": "Ableton Live Window Class",
+ "matching_strategy": "Equals"
+ }
+ ```
+
+
+
+Composite matching rules consist of multiple simple matching rules which must all evaluate to true to identify an application or window.
+
+```json
+[
+ {
+ "kind": "Exe",
+ "id": "zen.exe",
+ "matching_strategy": "Equals"
+ },
+ {
+ "kind": "Title",
+ "id": "Cloudflare Dashboard",
+ "matching_strategy": "Contains"
+ }
+]
+```
+
+## Workspace Rules
+
+ and a are used to identify applications or windows which should be put on a specific workspace.
+
+```json
+{
+ "monitors": [
+ {
+ "workspaces": [
+ {
+ "name": "Chat",
+ "layout": "Columns",
+ "workspace_rules": [
+ {
+ "kind": "Exe",
+ "id": "Discord",
+ "matching_strategy": "Equals"
+ }
+ ],
+ "initial_workspace_rules": [
+ {
+ "kind": "Exe",
+ "id": "Slack",
+ "matching_strategy": "Equals"
+ }
+ ]
+ },
+ ]
+ }
+ ]
+}
+```
+
+Workspace rules will apply all the time, effectively making it impossible to move the identified application or window to another workspace.
+
+Initial workspace rules will only apply once when the identified application or window is first created, allowing it to be moved to another workspace later.
+
+Workspace rules (including initial workspace rules) can be enforced in realtime using the command.
+
+
+## Application Handling Rules
+
+### Ignore Rules
+
+ are used to identify applications or windows which should be completely ignored by komorebi. Ignored applications cannot be targeted by any `komorebic` commands.
+
+### Floating Applications
+
+ are used to identify applications or windows which should be put on the [floating layer](./usage/layers).
+
+### Manage Rules
+
+ are used to identify applications or windows which should be forcibly managed. This is typically a nuclear option for extremely uncooperative applications.
+
+
+
+
+ ### Tray and Multi-Window Applications
+
+ are used to identify multi-window applications and applications which minmize to the system tray.
+
+ ### Slow Application Identifier Rules
+
+ are used to identify applications which are slow to send initial event notifications.
+
+ ### Layered Applications
+
+ are used to identify applications have the `WS_EX_LAYERED` extended window style, but should still be managed.
+
+ ### Object Name Change Applications
+
+ are used to identify applications which send `EVENT_OBJECT_NAMECHANGE` on launch. This is very rare, but includes popular applications such as Firefox (and derivatives), as well as JetBrains IDEs.
+
+ ### Slow Applications
+
+ are used to identify applications which are slow to send initial event notifications.
+
+
+
+
+
+ ### Tabbed Applications
+
+ are used to identify applications which use native macOS tabs (Finder, Ghostty etc.) - these are identified using their application name.
+
+ ### Titleless Applications
+
+ are used to identify applications which launch without a title - these are identified using their application name.
+
+
+