Merge remote-tracking branch 'origin/main'

# Conflicts:
#	site/README.md

README.md

@@ -89,6 +89,7 @@ Settings → Shortcuts** to change them or assign gestures to other actions.
 
 ## Documentation
 
+- [Why Ferese](docs/why-ferese.md)
 - [Installation and recovery](docs/installation.md)
 - [Configuration reference](docs/configuration.md)
 - [Desktop widgets](docs/desktop-widgets.md)

docs/why-ferese.md

@@ -0,0 +1,74 @@
+# Why Ferese
+
+Omarchy and Ferese come from two different ideas about how a desktop should be
+built. Omarchy brings existing Linux tools together and configures them as one
+environment, which gives it access to mature components that already do their
+jobs well.
+
+A setup like that might combine:
+
+```text
+Hyprland + bar + launcher + notifications + lock screen + theme scripts
+```
+
+There is nothing wrong with this approach, and being able to replace each part
+is useful, but those parts still have their own configuration, state, rendering,
+and lifecycle. Matching their themes can make them look related, while keeping
+their behavior in sync remains an ongoing part of maintaining the desktop.
+
+With Ferese, we are building the compositor and shell together, so workspaces,
+layout, focus, outputs, input, and materials all come from the same desktop
+state. The shell and Settings use first-party interfaces to work with that state
+instead of reading separate versions of it from several external tools.
+
+This does not mean every Ferese component has to run in one process. It means
+that the components share the same concepts, configuration, and protocols, so a
+workspace or surface means the same thing everywhere it appears.
+
+## What this means in practice
+
+You can see the difference in something as simple as corner radius. Ferese has a
+shared setting for shell surfaces:
+
+```kdl
+theme {
+    geometry {
+        shell-radius 16
+    }
+}
+```
+
+Changing that value updates the bar, Control Center, popovers, notifications,
+widgets, and native lock screen together. Managed windows have their own radius
+because they are a different kind of surface, but each value still has one clear
+meaning wherever it is used.
+
+In an assembled desktop, making the same visual change may mean editing the
+window manager, bar CSS, launcher theme, notification daemon, and lock screen
+config separately, then keeping those values aligned as the setup changes.
+
+The same difference shows up in how the desktop behaves. Ferese implements
+scrolling as part of its workspace model, renders blur behind shell surfaces in
+the compositor, and builds the overview from the real window scene. Focus,
+fullscreen, workspace geometry, and input all work from the same state rather
+than waiting for separate tools to catch up with one another.
+
+When a window opens, Ferese can handle the result as one transition:
+
+```text
+window opens → layout updates → viewport moves → input follows
+```
+
+An assembled environment may need to publish a window-manager event, pass it
+through IPC, run a script, update the bar, and start another animation before
+the rest of the desktop reflects the change. Each step can be fast, but it is
+still another boundary that has to be maintained.
+
+## The tradeoff we are making
+
+Building more of the desktop ourselves gives Ferese tighter control over how its
+parts work together, but it also leaves us responsible for more code. Omarchy
+can rely on mature components from across the Linux desktop ecosystem, while
+Ferese has to build that same level of maturity over time, and that is a tradeoff
+we are willing to make to keep the desktop consistent in both behavior and
+configuration.

scripts/build-site.py

@@ -13,6 +13,7 @@ OUTPUT = ROOT / 'build' / 'site'
 REPO = 'https://github.com/ferese-wm/ferese'
 PAGES = [
     ('index', 'Introduction', ROOT / 'site/content/index.md'),
+    ('why-ferese', 'Why Ferese', ROOT / 'docs/why-ferese.md'),
     ('installation', 'Installation', ROOT / 'docs/installation.md'),
     ('configuration', 'Configuration', ROOT / 'docs/configuration.md'),
     ('desktop-widgets', 'Desktop widgets', ROOT / 'docs/desktop-widgets.md'),

site/README.md

@@ -18,7 +18,7 @@ site sources or Markdown guides, then refresh the browser.
 
 - `site/index.html` and `site/styles.css`: homepage and shared visual design.
 - `site/content/index.md`: handbook introduction.
-- `docs/{installation,configuration,desktop-widgets,notifications,locking,screen-sharing}.md`:
+- `docs/{why-ferese,installation,configuration,desktop-widgets,notifications,locking,screen-sharing}.md`:
   source guides.
 - `scripts/build-site.py`: renders Markdown, resolves links, generates section
   navigation, previous/next links, and the search index.

site/content/index.md

@@ -4,6 +4,8 @@ Ferese is a complete Wayland desktop built around personalization. Its custom sh
 
 This handbook covers installing Ferese, finding your way around, and making the desktop your own.
 
+[Why Ferese](why-ferese.md) explains why the desktop is designed as one integrated system rather than assembled from separately configured tools.
+
 ## Start with your first session
 
 1. Read [Installation](installation.md) for dependencies, building, login-manager or TTY startup, and recovery.

site/index.html

@@ -93,7 +93,7 @@
             A menu bar, Control Center, Settings, notifications, and desktop
             widgets, designed to work together.
           </p>
-          <a href="docs/">Explore the handbook →</a>
+          <a href="docs/why-ferese.html">Why integration matters →</a>
         </article>
         <article>
           <h2>Make it yours</h2>