Remove design documents and their handbook references

2026-10-01 17:51:54 +01:00
1 parent 3d0c85c70a
commit c0010ccbb6
@@ -12,8 +12,6 @@
 - [Shortcuts and gestures](shortcuts.md): keyboard navigation, Super-drag, resize, and window grouping.
 - [Desktop widgets](desktop-widgets.md): clocks and sticky notes.
 - [Notifications](notifications.md): popups, history, and Do Not Disturb.
 - [Lock screen](locking.md): appearance, automatic locking, and display sleep.
 - [Screen sharing and recording](screen-sharing.md): choosing sources and stopping a session.
 - [Desktop portals](portals.md): application integration and supported services.
@@ -21,10 +19,6 @@
 ## Develop Ferese
 - [Development](development.md): builds, tests, and portal checks.
 - [Compositor architecture](ferese-window-manager-spec.md).
 - [Shell behavior](ferese-shell-design.md).
 - [Theme components](ferese-theme-ui-spec.md).
 - [Animation checks](animation-validation.md).
 - [Nested resize checks](nested-resize-testing.md).
 - [Client soak testing](native-soak-testing.md).
 - [Performance measurements](performance-baseline.md).
@@ -1,26 +0,0 @@
 # Animation regression checks
 Run `cargo test -p ferese-animation -p ferese --offline` for transition,
 resize requests, reduced motion, stacking, and refresh-rate regression tests.
 For visual validation, use a disposable Ferese session with three tiled windows
 containing text and at least one floating window. Test both the nested and DRM
 backends. Record the session at its native refresh rate when comparing builds;
 single screenshots cannot establish smoothness.
 | Scenario | Expected result |
 | --- | --- |
 | Super+F on the middle column, then exit | Neighbours remain behind the expanding window. The shrinking window stays above them until the transition finishes. |
 | Toggle Super+F repeatedly at 40–80 ms intervals | Every reversal starts at the presented frame. Corners, border and shadow follow the same zoom progress. The final state matches the last input. |
 | Cycle width, then immediately Super+F | The old column-width spring cannot override maximized width. |
 | Exit maximize or fullscreen and immediately resize or scroll | The current frame is retained when the target changes; scrolling resumes without a position jump. |
 | Drag a floating window; resize from its top-left corner | The window follows the pointer directly. The opposite edge stays anchored. Delayed client commits do not move or raise it. |
 | Zoom responsive and slow-redrawing clients | Each zoom requests the destination size once. Client redraws do not generate intermediate resize requests or restart the motion. |
 | Zoom the leftmost and rightmost columns in and out | Each outer edge moves monotonically toward its destination; neither side trembles or reverses near the screen edge. |
 | Disable borders and shadows, then zoom | Rounded corner pixels repaint through the final frame; no corner remnants remain. |
 | Repeat on 60 Hz and 144 Hz outputs; move focus between them | Similar elapsed-time motion with no double advancement. Check frame timing on actual DRM hardware. |
 | Enable reduced motion | Geometry and decorations reach their final values together. |
 Zoom requests the destination client size once and scales the available buffer
 along the transition. This avoids repeated content reflow during motion. It is
 not a buffer snapshot or a guarantee of perfectly sharp intermediate text.
@@ -6,8 +6,7 @@ which includes app and media shortcuts, appearance, widgets, and optional startu
 and display settings. Its browser/editor shortcuts need Firefox/Zed; brightness
 keys need `brightnessctl` and audio keys need `wpctl`.
 This reference covers layouts, appearance, input, and desktop behavior.
-See [Desktop widgets](desktop-widgets.md), [Notifications](notifications.md),
+See [Desktop portals](portals.md) for application integration options.
 and [Desktop portals](portals.md) for their additional options.
 ## KDL syntax
@@ -135,8 +134,7 @@ Choose Light, Dark, or Auto in Settings or Control Center. Auto follows local
 07:00 and 19:00 boundaries unless you change its schedule.
 Selections store preset names. Partial KDL files can override shared colors or
-one appearance. See [Themes](theme-engine.md) for files, accessibility options,
+one appearance.
 and live previews.
 | Section / key | Type | Default | Meaning |
 | --- | --- | --- | --- |
@@ -145,7 +143,7 @@ and live previews.
 | `theme.split` | boolean | `false` | Use separate light/dark families; retains both selections when disabled |
 | `theme.light.family`, `theme.dark.family` | family id | `"ferese-blue"` | Stored selections used when split is enabled |
 | `theme.custom-themes.<id>.file` | path | unset | Imported KDL family with explicit light and/or dark sections |
-| `theme.light.preset` | preset name | `"ferese-blue-light"` | Light palette; see the [preset pairs](theme-engine.md#preset-pairs) |
+| `theme.light.preset` | preset name | `"ferese-blue-light"` | Light palette |
 | `theme.dark.preset` | preset name | `"ferese-blue"` | Dark palette |
 | `theme.file` | path | unset | Shared partial KDL theme |
 | `theme.light.file`, `theme.dark.file` | path | unset | Partial KDL theme for one appearance |
@@ -567,7 +565,3 @@ override shell rounding.
 Power actions use a centered confirmation. **Super+Shift+E** and
 `feresectl request-logout` ask to log out. `feresectl exit` ends the session
 immediately.
 ## Notifications
 See [Notifications](notifications.md) for popups, Do Not Disturb, and timeout options.
@@ -1,118 +0,0 @@
 # Desktop widgets
 Clock and sticky-note widgets sit above the wallpaper and behind windows.
 Drag the clock or a note's title to move it. Release to save, or press Escape to
 cancel. Widgets stop at each other's edges on the same display.
 Enable it in Settings → Desktop widgets or in your Ferese config:
 ```kdl
 desktop-widgets {
    clock enabled=#true anchor="top_left" margin-x=64 margin-y=80 {
        style "pixel"                   // or "minimal"
        outputs                         // every output; or outputs "DP-2"
        width 440
        height 320
        font-family ""                  // style default; or "Comfortaa"
        bold #false
        time-size 128.0
        date-size 18.0
        time-format "%-I:%M %p"          // use "%H:%M" for 24-hour time
        date-format "%a, %b %-d"
        time-zone ""                    // system zone; or "Africa/Lagos"
        show-date #true
        lowercase #true
        color ""                        // theme primary text
        date-color ""                   // theme muted text
        opacity 0.9
        alignment "center"              // left, center, right
        gap 4.0
        padding 12.0
        background ""                   // transparent; or "#10101080"
        radius 16.0
    }
 }
 ```
 Positions: `top_left`, `top_center`, `top_right`, `center_left`, `center`,
 `center_right`, `bottom_left`, `bottom_center`, `bottom_right`.
 Margins affect anchored axes only: a centered horizontal position ignores
 `margin-x`; a centered vertical position ignores `margin-y`.
 All geometry and text sizes use logical pixels and follow the output's scale.
 Increase the widget width/height for longer formats or larger text.
 Choose **Pixel** for stacked hours and minutes with alternating theme colors,
 or **Minimal** for a plain time/date layout. Pixel zero-pads hours and hides am/pm.
 Formats containing seconds or extra text use a single line. Both styles shrink
 time text to fit. Select a different font in Settings, or set `font-family`.
 Changes apply live. Colors and fonts follow the theme unless overridden.
 Formatting uses [strftime-compatible formats](https://docs.rs/jiff/latest/jiff/fmt/strtime/index.html).
 Use `%H:%M` for 24-hour time or `%-I:%M %p` for 12-hour time.
 ## Clock limits
 Clock and note corners follow the shared shell radius. Their `radius` fields
 are accepted for compatibility but do not override it.
 All clock keys are optional. The example enables the clock (disabled by default);
 the other values illustrate defaults or their empty-string equivalents.
 `outputs` is an array of strings; `enabled`, `bold`, `show-date`, `lowercase` are
 booleans; `width`, `height`, and margins are integers. Other sizes/opacity are numbers.
 | Fields | Accepted range |
 | --- | --- |
 | `width`, `height` | 64–1600, 32–800 |
 | `margin-x`, `margin-y` | 0–8192 |
 | `time-size`, `date-size` | 8–240, 8–96 |
 | `opacity` | 0–1 |
 | `gap`, `padding`, `radius` | 0–64, 0–64, 0–128 |
 | `font-family`, `time-format`, `date-format` | At most 128 bytes each |
 | `outputs` | At most 32 exact output names, each 1–128 bytes |
 Formats must be valid; `time-zone` must be empty or a recognized IANA name.
 Colors are empty (inherit), `#RRGGBB` or `#RRGGBBAA`; all numeric values must be finite.
 ## Sticky notes
 Settings → Desktop widgets → Add note creates a card. Drag its title to move it;
 click Edit for its multiline editor, then Done to finish. Text autosaves after
 500 ms without typing. Escape cancels a drag or finishes editing. Position saves
 on release; dragging changes the anchor to `top_left` and saves pixel margins.
 Title, size and style are also editable in Settings. Notes persist in the config.
 Choose a note’s font in Settings or set `font-family "Comfortaa"` in its `note`
 node. Without an override, notes use the interface font.
 These are plain-text notes, not Markdown or HTML.
 ```kdl
 desktop-widgets {
    note id="today" title="Today" text="Review the pull request\nTake a break\n" anchor="top_right" margin-x=48 margin-y=80
 }
 ```
 Repeat the `note` node for additional notes; IDs must be unique. Cards stay behind windows
 and take keyboard focus only when clicked. Set `interactive #false` for a fully
 click-through card. Long text wraps; increase height if needed.
 | Key | Type | Default / accepted values |
 | --- | --- | --- |
 | `id` | string | `"note"`; unique, 1–64 ASCII letters/digits/`-`/`_` |
 | `enabled` | boolean | `true` |
 | `interactive` | boolean | `true`; drag/edit controls; `false` is click-through |
 | `title` | string | `"Note"`; empty hides it; maximum 256 bytes |
 | `text` | string | `""`; multiline plain text, maximum 16 KiB |
 | `outputs` | string array | `[]` means all; at most 32 exact names, each 1–128 bytes |
 | `anchor` | string | `"top_right"`; same nine positions as clock |
 | `margin-x`, `margin-y` | integer | `48`, `80`; 0–8192; anchored edges only |
 | `width`, `height` | integer | `320`, `240`; 120–1200, 80–1200 |
 | `font-family` | string | omitted/empty follows desktop font; maximum 128 bytes |
 | `text-size`, `title-size` | number | `16`, `18`; 8–96 |
 | `color` | string | omitted/empty/`"theme"` follows primary text; or hex color |
 | `background` | string | omitted/`"theme"` follows surface base; empty is transparent; or hex color |
 | `opacity` | number | `0.9`; 0–1, multiplies text/background alpha |
 | `padding`, `gap` | number | `20`, `8`; 0–64 |
 | `radius` | number | `16`; 0–128 |
 | `alignment` | string | `"left"`; `left`, `center`, `right` |
 At most 32 notes; the entire live config is limited to 60 KiB.
@@ -14,14 +14,10 @@ Keep another desktop available for direct-session recovery.
 ## Test guides
 - [Animation checks](animation-validation.md): transitions, interruption, and hit testing.
 - [Nested resize checks](nested-resize-testing.md): wallpaper and bar responsiveness.
 - [Client soak testing](native-soak-testing.md): repeated client lifecycle and resource growth.
 - [Performance measurements](performance-baseline.md): sampling and historical results.
 The [compositor](ferese-window-manager-spec.md), [shell](ferese-shell-design.md),
 and [theme](ferese-theme-ui-spec.md) references describe the main code boundaries.
 ## Portal checks
 Run backend unit tests and compare D-Bus contracts against installed portal XML:
@@ -1,65 +0,0 @@
 # Shell behavior
 This is a maintainer reference. User options are documented in
 [Configuration](configuration.md). Common UI belongs in
 [ferese-theme](../crates/ferese-theme/README.md).
 ## Bar and popovers
 The shell creates a bar for each output. Workspace buttons use compositor state
 and appear in numeric order. The active window title occupies the center when
 space allows. Date and time form one calendar button. Right-side controls open
 sound, battery, notifications, recording, and Control Center popovers.
 A popover is anchored to its control and constrained to the same output.
 Opening another primary popover replaces the current one. Popovers reserve no
 workspace space; the bar reserves its configured height and margins.
 True fullscreen hides the bar without changing the preserved tiled layout.
 Use real service availability for controls. Handle missing services and failed
 actions without blocking the UI. Settings opens as a separate application.
 ## Overview
 The compositor presents window previews; the shell supplies labels and workspace
 controls. Do not continuously copy windows into the shell process.
 Clicking a workspace background selects that workspace and keeps overview open
 so its windows can be selected. Clicking a window activates that exact window.
 Directional keys change selection, Enter activates it, and Escape dismisses.
 Activation must use the selected window ID, not the window focused before overview.
 ## Focus and dialogs
 The bar and notification popups do not normally take keyboard focus. Interactive
 shell surfaces restore the previous valid app focus when dismissed.
 Power actions and logout use a centered system confirmation, including blockers
 when present. Input outside the confirmation must not reach applications.
 Authentication, screen-sharing, and recording dialogs are separate themed windows.
 Use one visible frame, content-sized height, and an output-sized height limit.
 Scrollable lists must leave headings and action buttons accessible.
 Attach dialog material to the content card using the shared theme helper.
 Match blur regions to the displayed card throughout opening and resize; do not
 paint an opaque window behind a translucent card.
 ## Notifications and widgets
 The shell provides the standard notification service. Normal popups respect
 Do Not Disturb; critical messages bypass it. History is held in memory and clears
 when the shell exits. See [Notifications](notifications.md).
 Clock and note widgets sit behind application windows, reserve no workspace space,
 and save positions after dragging. Only interactive notes take keyboard focus.
 See [Desktop widgets](desktop-widgets.md).
 ## Lifecycle
 Shell failure must not destroy managed windows or workspace state. Reconstruct
 bars and controls from compositor state after reconnecting, and clear dead shell
 focus. Notification history is not reconstructed from disk.
 Keep slow service queries, image loading, and filesystem work away from UI event
 handling. Stop animation work once the UI settles. Validate popover placement,
 fullscreen transitions, dialog dismissal, and shell restart in a nested session.
@@ -1,83 +0,0 @@
 # Theme components
 Ferese's native apps use [ferese-theme](../crates/ferese-theme/README.md) for
 colors, fonts, controls, menus, icons, calendar elements, and dialog materials.
 Use [Configuration → Appearance](configuration.md#appearance) for supported keys
 and defaults.
 ## Shared appearance
 The six theme families are Ferese Blue, Catppuccin, Gruvbox, Rosé Pine, Tokyo
 Night, and Everforest. Each has a paired light and dark palette. Ferese Blue uses the
 logo accent, `#3D7BE6`. Presets supply colors and materials; explicit wallpaper,
 typography, geometry, and material overrides remain in place.
 The interface font applies to shell text and native dialogs. Clock and note
 widgets can override it. Managed-window corners and shell corners are separate
 settings; small controls cap their corners to fit their size.
 ## Materials
 Two material styles are supported:
 | Style | Background |
 | --- | --- |
 | `solid` | Opaque theme surface |
 | `translucent` | Theme tint over blurred background content |
 Bars, popovers, notifications, and themed dialogs share `theme.material.opacity`
 and `blur-radius`. Text and icons stay opaque. An opacity of zero hides the
 material; blur radius zero disables blur. Solid mode stays opaque.
 ```kdl
 theme {
    colors {
        accent "#3D7BE6"
    }
    material {
        style "translucent"
        opacity 0.78
        blur-radius 12
    }
    geometry {
        shell-radius 14
        window-radius 14
    }
 }
 ```
 The compositor owns blur and tint. `material::ModalMaterial` attaches native
 dialogs to that rendering path. Keep the attachment alive with the window and
 make the attached client background transparent. Outside Ferese, retain a client
 background so the dialog remains usable.
 ## Components
 | Module | Use |
 | --- | --- |
 | `palette` | Resolve configuration colors and build the native toolkit theme |
 | `controls` | Surfaces, navigation, text buttons, and input styles |
 | `menus` | Rows, headings, sections, separators, switches, and sliders |
 | `gallery` | Split theme previews, selected badges and accessible radio navigation |
 | `calendar` | Date/time labels, clock digits, and calendar grids |
 | `icons` | Shared SVG assets, sizing, and tint |
 | `typography` | Shared font selection and text |
 | `contrast` | Readable labels on filled controls |
 | `material` | Attach modal cards to compositor materials |
 Applications provide data, layout, actions, and animation progress. Extend shared
 components when a style is needed in multiple apps. Avoid hardcoded app-specific
 fonts, foreground colors, or opacity values.
 ## UI checks
 - Check text and icons in all twelve light and dark variants.
 - Check rest, hover, pressed, focused, selected, and disabled controls.
 - Keep accent-button labels readable after typing or changing focus.
 - Keep controls usable with solid materials and blur disabled.
 - Align material regions with the visible card at every output scale.
 - Give dialogs one frame; cap their height and scroll their content, preserving actions.
 - Respect reduced motion and stop requesting animation frames after settling.
 Theme changes affect appearance; they do not change focus, workspace ownership,
 input permissions, or authentication policy.
@@ -1,109 +0,0 @@
 # Compositor architecture
 This is a maintainer reference. For supported configuration and shortcuts, use
 [Configuration](configuration.md); for builds and checks, use [Development](development.md).
 ## Processes and crates
 | Component | Responsibility |
 | --- | --- |
 | `ferese` | Wayland clients, windows, workspaces, input, outputs, and rendering |
 | `ferese-shell` | Bar, popovers, notifications, widgets, and system confirmations |
 | `ferese-settings` | Configuration editor |
 | `feresectl` | Command-line control |
 | `ferese-lock` | Lock-screen UI and PAM authentication |
 | `ferese-polkit-agent` | System authentication prompts |
 | `xdg-desktop-portal-ferese` | Desktop portal requests and PipeWire streams |
 | `ferese-record` | Video encoding and saving |
 The compositor uses Smithay and calloop. The direct backend renders through
 DRM/KMS; the nested backend renders into a window on another Wayland desktop.
 Native UIs use libcosmic. Layout, animation, configuration, IPC, protocols, and
 [theme components](../crates/ferese-theme/README.md) live in separate crates.
 ## State and ownership
 The event loop owns compositor state and Wayland objects. Background workers
 return results through bounded channels; results must be checked against current
 window, output, and request identities before application.
 Keep these relationships valid after a state change:
 - Each window belongs to one workspace and appears once in its layout or floating list.
 - Each attached workspace belongs to one output; each output has one active workspace.
 - A window's output follows workspace ownership.
 - Fullscreen preserves the underlying layout or floating placement.
 - Focus points to a live window or authorized shell surface.
 - Workspace focus history is distinct from current keyboard focus.
 Monitor removal migrates workspaces to a remaining output. Returning monitors
 restore eligible workspaces; explicit user moves take priority. Selecting a
 workspace visible on another monitor focuses that monitor.
 ## Layout and presentation
 Scrolling layouts arrange columns horizontally. Windows within a column divide
 its height. A workspace owns its viewport; presentation subtracts that viewport
 from window positions. Tree layouts use nested splits and stacks. Layout changes
 preserve window membership and floating placement.
 Keep layout targets, animated rectangles, and committed client sizes separate.
 A layout transition requests the destination client size rather than sending
 one configure per animation frame. Available content is scaled and clipped until
 the matching client buffer arrives. Hit testing uses the same presented geometry.
 Interrupted animations continue from their current position.
 Input and layout use logical pixels. Rendering converts them using the output's
 scale and transform. Application popups use their parent's output and presented
 position when calculating bounds.
 ## Rendering and frame delivery
 Render damage from client commits, animations, effects, cursor motion, and output
 changes. Movement damages both old and new bounds, including shadows and blur.
 Output-specific callbacks follow window ownership. Presentation feedback is
 collected only for surfaces the renderer actually displayed on that output.
 An unchanged frame still permits paced client callbacks without submitting a
 new display buffer.
 Animations use elapsed time across outputs, with a timer while transitions remain
 active. An idle focused monitor must not stall another monitor's animation.
 The compositor renders blur from content behind the requesting surface. Material
 regions and client content must share coordinates during placement, scaling,
 and animation. See [Theme components](ferese-theme-ui-spec.md).
 ## Input
 Use milliseconds for keyboard, pointer, touch, and gesture protocol events;
 relative-motion timestamps retain microseconds. Keep keyboard focus, pointer
 focus, and window stacking separate. Hover focus does not scroll or raise windows.
 Pointer grabs and constraints must end cleanly when their surface disappears.
 A locked pointer's position hint is stored while locked, then resolved against
 current surface geometry and clamped to an output when the lock is released.
 ## IPC and private protocols
 User control uses `$XDG_RUNTIME_DIR/ferese/control.sock`, restricted to the
 session user. The parent directory is private and peers are checked by UID.
 IPC frames are length-prefixed JSON with bounded message sizes, workers, and queues.
 See `feresectl --help` for commands.
 Private Wayland capabilities grant shell control or material effects to trusted
 components. Public layer-shell access alone grants neither. Trusted connections
 and descriptors must not leak to launched applications. Capture paths check
 session policy and reject capture while locked.
 Session locking must protect every output, including hotplug, and remain secure
 if the lock UI crashes. [Portal integration](portals.md) documents application
 consent and the currently supported services.
 ## Review and testing
 Check output ownership, presented geometry, focus restoration, request lifetimes,
 and bounded work whenever changing a protocol or rendering path. Test both
 backends; a nested result does not establish hardware behavior.
 Use the [animation](animation-validation.md), [resize](nested-resize-testing.md),
 and [soak](native-soak-testing.md) checks alongside the workspace tests.
@@ -1,47 +0,0 @@
 # Notifications
 Ferese shows compact notification popups and a history panel opened from the bar.
 Their colors, font, corners, and background follow the shell theme.
 ## Popups and history
 Up to three popups are visible at once. Hovering pauses a popup's timer.
 History keeps the latest 100 notifications and clears when the shell exits.
 App action buttons work when provided by the sender. Transient messages leave
 history when closed.
 Critical notifications bypass Do Not Disturb and remain visible unless the app
 provides a timeout. Other apps can also request a timeout or no timeout.
 ## Settings
 **Settings → Notifications** controls popup visibility, the default timeout, and
 the Do Not Disturb preference. The bar toggle changes Do Not Disturb for the
 current session; Settings saves it for future sessions. Hidden popups still enter
 history.
 ```kdl
 notifications {
    show-popups #true
    do-not-disturb #false
    timeout-ms 6000
 }
 ```
 The default timeout accepts 1000–30000 milliseconds.
 ## Send a test notification
 ```sh
 notify-send --app-name=Ferese --icon=dialog-information "Hello" "Your desktop notification"
 ```
 ## Troubleshooting
 Only one notification server can run on the session bus. The session launcher
 stops `swaync.service` before starting the shell. When launching the shell manually,
 stop any existing notification server first. If another server owns the interface,
 Ferese logs that native notifications are unavailable.
 Ferese supports plain text, app icons, actions, replacement, and urgency. Rich
 markup, embedded images, sounds, and saved notification history are not supported.
@@ -1,150 +0,0 @@
 # Themes
 The compositor resolves theme files and publishes a versioned snapshot. Native
 apps consume that snapshot; Settings edits references and requests isolated previews.
 ## Preset pairs
 | Family | Dark preset | Light preset |
 | --- | --- | --- |
 | Ferese Blue (default) | `ferese-blue` | `ferese-blue-light` |
 | Catppuccin | `catppuccin-mocha` | `catppuccin-latte` |
 | Gruvbox | `gruvbox` | `gruvbox-light` |
 | Rosé Pine | `rose-pine-moon` | `rose-pine-dawn` |
 | Tokyo Night | `tokyo-night` | `tokyo-night-day` |
 | Everforest | `everforest-dark` | `everforest-light` |
 Each variant supplies its own surfaces, tint strength, opacity, blur, borders,
 and shadows. Shared material overrides apply to both appearances; appearance
 specific overrides take precedence. [Palette sources and adjustments](theme-palette-sources.md)
 record the upstream colors and contrast tuning.
 ## Configuration
 ```kdl
 theme {
    mode "auto"
    family "catppuccin"
    split #false
    file "themes/custom_theme.kdl"
    light {
        preset "ferese-blue-light"
        file "themes/custom_theme_light.kdl"
        material { opacity 0.94; tint-strength 1; }
    }
    dark { preset "ferese-blue"; file "themes/custom_theme_dark.kdl"; }
    schedule { source "schedule"; timezone "system"; light-at "07:00"; dark-at "19:00"; }
    accessibility { increase-contrast #false; reduce-transparency #false; }
    accent "#3D7BE6"
 }
 ```
 Paths are relative to the configuration directory. Partial theme files contain
 `theme { colors { accent "#3D7BE6"; } }`, or the token sections directly.
 Merge order is preset, shared file, appearance file, shared inline tokens,
 appearance inline tokens, then accent and accessibility adjustments. Unknown tokens warn; invalid known values reject
 an entire update and retain the last working snapshot.
 ## Snapshot
 `ResolvedTheme` contains effective appearance and typed colors, surfaces, material,
 geometry, typography, wallpaper, border paints, and shadow tokens. Base, raised,
 and application backgrounds are separate colors. Selected mode,
 accessibility inputs, requested accent, adjusted accent, warnings, schema version,
 and revision accompany it. Consumers do not infer appearance from brightness.
 Material tokens differ by appearance. Light translucent surfaces use full tint strength and
 0.94 default opacity to stay pale over dark wallpapers; dark surfaces use a softer
 0.5 tint. Shared material overrides apply to both unless the appearance overrides
 them. Reduce Transparency resolves to solid
 material with zero blur. Increase Contrast adjusts text, borders, and translucent
 surface tint for 7:1 text contrast, and enables native high-contrast controls.
 Accents are adjusted against surfaces independently for each appearance, then
 on-accent text is selected for readability.
 ## Scheduling
 Auto selects the most recent light or dark boundary in the configured timezone.
 The interval is circular, so light may start after dark. Equal boundaries are
 invalid. Repeated hours use their first occurrence; skipped hours shift forward
 by the timezone gap. The next transition arms a realtime timer. Resume, timezone
 replacement, and realtime clock jumps trigger recalculation without polling.
 ## Transitions
 Prepare the incoming wallpaper before starting a 250 ms eased transition. Decode
 or upload failures and a bounded readiness timeout retain the old wallpaper and
 allow the theme change. Reduced motion and accessibility changes apply immediately.
 Transitions preserve their exact resolved endpoints. Changes within one appearance
 keep the resolved material settings instead of adding temporary tint corrections.
 Surface, tint, border, shadow, and accent colors can transition. Fonts and geometry
 switch atomically. Foregrounds remain readable across dark and light backdrops. Near the neutral
 midpoint, the transition temporarily strengthens material tint instead of fading
 text through the background color. Tests sample primary, muted,
 and on-accent text throughout the transition. Wallpaper changes use prepared
 images rather than a placeholder.
 Publish effective appearance at transition start. The portal emits changed
 `color-scheme`, `accent-color`, `contrast`, and `reduced-motion` values then.
 ## Commands
 | Command | Action |
 | --- | --- |
 | `feresectl theme get` | Read the current mode, effective appearance, and colors |
 | `feresectl theme status` | Read warnings and the last reload error |
 | `feresectl theme subscribe` | Stream changes as JSON; no polling |
 | `feresectl theme mode light` | Save Light mode; also accepts `dark` and `auto` |
 | `feresectl theme preview PATH` | Resolve a candidate config without applying it |
 Settings shows six paired previews, with Light on the left and Dark on the right.
 Auto uses a switch in the page header. The adjacent button shows its source and,
 when enabled, the effective appearance. It opens source and schedule controls
 below the gallery, which can be edited before enabling Auto. Enabling Auto
 immediately follows the chosen source; disabling it keeps the current appearance.
 Manual appearance controls are in Control Center. Selecting a family
 applies the matching variant live and offers Undo for five
 seconds. Hovering does not change the desktop. Arrow keys navigate the gallery.
 Enable **Use different themes for light and dark** for two independent galleries.
 Disabling it uses the active family and retains the stored pair. A missing
 variant uses Ferese Blue for that appearance and displays a fallback note.
 **Follow system** reads `org.gnome.desktop.interface color-scheme` and monitors
 changes. `default` and `prefer-light` mean Light; `prefer-dark` means Dark. If the
 setting is unavailable, Ferese uses Dark and displays a note. This source does
 not read Ferese's own appearance portal, avoiding a feedback loop. Sunrise/sunset
 is deferred.
 The gallery’s Import button adds a family to the gallery without selecting it. Give each
 variant an explicit section; omitted tokens inherit Ferese Blue for that
 appearance. For example:
 ```kdl
 theme {
    name "My theme"
    light { colors { accent "#8F5300"; }; }
    dark { colors { accent "#CBA6F7"; }; }
 }
 ```
 Settings stores the file reference under `theme.custom-themes.<id>.file`.
 The compositor validates it and publishes its palettes alongside built-ins.
 Omit a variant to make a single-variant family. Token-only partial files remain
 supported as shared/per-appearance overrides; imports require explicit variants
 so appearance is never guessed from brightness. Imported and override files
 reload after a short debounce, including saves that replace the file. Invalid
 updates retain the last working theme and produce one desktop notification.
 High contrast, Reduce Transparency and Reduce Motion are in Accessibility.
 Material, accent, font and geometry controls stay visible below the gallery. Theme
 overrides are under Advanced customization, in one file-picker row with a
 Shared/Light/Dark selector; each stored
 reference is retained when selecting another scope. Settings and shell switches
 share the same palette. Switch and slider thumbs stay circular regardless of
 shell corner radius.
 When an older config first adopts mode or preset selection, Ferese moves its
 inline palette into the dark selection and preserves comments. Shared wallpaper,
 font, and geometry settings continue to apply to both appearances. For a wallpaper
 pair, set `background { path "..."; }` inside each appearance or its theme file.
@@ -1,33 +0,0 @@
 # Theme palette sources
 Ferese maps upstream palettes to desktop roles. Materials are authored for Ferese;
 text and accents have the adjustments below to meet desktop contrast requirements.
 | Family | Source revision | License |
 | --- | --- | --- |
 | catppuccin | [07d02aa110ef](https://github.com/catppuccin/palette/blob/07d02aa110ef9eb7e7427afca5c73ba9cf7f8ebd/palette.json) | MIT |
 | gruvbox | [ef8864bb42bf](https://github.com/morhetz/gruvbox/blob/ef8864bb42bf244f0295d1c5a403b27e3d139695/colors/gruvbox.vim) | MIT/X11 |
 | rose-pine | [ff483051a47e](https://github.com/rose-pine/neovim/blob/ff483051a47e27d84bdef47703538df1ed9f4a47/lua/rose-pine/palette.lua) | MIT |
 | tokyo-night | [cdc07ac78467](https://github.com/folke/tokyonight.nvim/blob/cdc07ac78467a233fd62c493de29a17e0cf2b2b6/extras/kitty/tokyonight_day.conf) | Apache-2.0; palette exports marked MIT |
 | everforest | [85a86eb62409](https://github.com/sainnhe/everforest/blob/85a86eb62409e3ec88713bff3d1b9d7374e112e4/autoload/everforest.vim) | MIT |
 Tokyo Night Night also uses its [official export](https://github.com/folke/tokyonight.nvim/blob/cdc07ac78467a233fd62c493de29a17e0cf2b2b6/extras/kitty/tokyonight_night.conf).
 ## Color adjustments
 | Variant | Token | Upstream | Ferese |
 | --- | --- | --- | --- |
 | rose-pine-moon | muted | `#908CAA` | `#918DAA` |
 | rose-pine-dawn | muted | `#797593` | `#716D89` |
 | tokyo-night-day | text | `#3760BF` | `#3358B0` |
 | tokyo-night-day | muted | `#6172B0` | `#4D5A8C` |
 | tokyo-night-day | accent | `#2E7DE9` | `#2C76DD` |
 | everforest-light | muted | `#829181` | `#677367` |
 | everforest-light | accent | `#8DA101` | `#849601` |
 Catppuccin Latte uses upstream subtext1 for muted labels. Gruvbox uses readable
 foreground shades rather than its comment gray. Rosé Pine uses its subtle role
 for secondary labels and its love accent in Dawn. Everforest uses the Hard pair.
 Tokyo Night uses the upstream Night and Day exports.
 License texts are bundled in [assets/themes/licenses](../assets/themes/licenses)
 and copied into each installed release. Older saved Monochrome, Dracula, Ayu Light,
 and Monokai selections remain readable, but are absent from the gallery.
@@ -17,11 +17,7 @@ PAGES = [
    ('why-ferese', 'Why Ferese', ROOT / 'docs/why-ferese.md'),
    ('installation', 'Installation', ROOT / 'docs/installation.md'),
    ('configuration', 'Configuration', ROOT / 'docs/configuration.md'),
    ('theme-engine', 'Themes', ROOT / 'docs/theme-engine.md'),
    ('theme-palette-sources', 'Theme palette sources', ROOT / 'docs/theme-palette-sources.md'),
    ('shortcuts', 'Shortcuts and gestures', ROOT / 'docs/shortcuts.md'),
    ('desktop-widgets', 'Desktop widgets', ROOT / 'docs/desktop-widgets.md'),
    ('notifications', 'Notifications', ROOT / 'docs/notifications.md'),
    ('locking', 'Lock screen', ROOT / 'docs/locking.md'),
    ('screen-sharing', 'Screen sharing', ROOT / 'docs/screen-sharing.md'),
    ('portals', 'Desktop portals', ROOT / 'docs/portals.md'),
@@ -10,7 +10,7 @@ use
 ## Get started
 1. [Install Ferese](installation.md), or try a [nested preview](installation.md#preview-and-logs).
-2. Choose Light, Dark, or Auto in **Control Center**. Open **Settings** for [theme files and presets](theme-engine.md).
+2. Choose Light, Dark, or Auto in **Control Center**. Open **Settings** for theme files and presets.
 3. Use the [configuration reference](configuration.md) for shortcuts, gestures, window rules, and displays.
 ## Default shortcuts
@@ -40,8 +40,6 @@ group windows, resize them and move between workspaces.
 ## Desktop guides
 - [Desktop widgets](desktop-widgets.md): clocks and sticky notes.
 - [Notifications](notifications.md): history and Do Not Disturb.
 - [Lock screen](locking.md): appearance, automatic locking, and display sleep.
 - [Screen sharing and recording](screen-sharing.md): share an app or display, or save a video.
 - [Desktop portals](portals.md): integration with applications.