diff --git a/docs/dev/core-model.md b/docs/dev/core-model.md
index fd9c35d3..fa82b88f 100644
--- a/docs/dev/core-model.md
+++ b/docs/dev/core-model.md
@@ -335,3 +335,87 @@ better one. What stays, and what kfw does (the list to hand over):
10. **Monitor fields** (d): `Monitor
` with `#[serde(flatten)] platform: P` (decided: the schemars
`required` order of the runtime notification and socket schemas changes, nothing checked in
does).
+
+## 8. Design: the platform hooks of a shared `Workspace` (not implemented)
+
+Status: design from kfw (Windows side), written against `wip-u-core` plus the revisions of
+`wip-u-kfw2` (items 1 to 7 of section 7 are done on Windows: `window_id`, `hide_window`/`restore_window`,
+`Window::focus`/`maximize`/`unmaximize` over `backend()`, `Option` lookups, `WindowDetails: From`,
+`remove_floating_window`, the shared error strings). Nothing below is code; no trait exists yet.
+
+### 8.1 Shape
+
+`Workspace` lives in `komorebi-core`, like `Container`; `P::Window` is the
+`ContainerWindow` (`Copy`, with the `Id`). Windows and KDE implement `WorkspacePlatform` on a unit
+struct; the daemon uses the alias `type Workspace = komorebi_core::Workspace`. Every
+hook has a default that does nothing (or the generic behaviour), so a platform lists only its
+differences. The trait is a generic parameter, not `dyn`: the calls are in the layout hot path and the
+platform is fixed at compile time. All hooks take `&mut Workspace` or the relevant parts, never
+the `WindowManager`, so the layer below `window_manager` stays independent of it.
+
+The window-facing operations are NOT hooks: `focus`, `maximize`, `unmaximize`, `hide_window`,
+`restore_window`, `title`/`exe`/`class`/`path` (all `Option`) are methods the `ContainerWindow` bound
+(extended with `focus`, `maximize`, `unmaximize`, `title`, `exe`, `class`, `path`) requires, which both
+`Window` types now have under these names. Hooks are only for behaviour the shared code cannot express
+with window operations.
+
+### 8.2 The (c) hooks
+
+| Where | Hook | Windows does | KDE does | Default |
+|---|---|---|---|---|
+| `update` start | `fn begin_update(&mut self_ws) -> Flow` | returns `Skip` until `INITIAL_CONFIGURATION_LOADED`; opens the `AnimationBatch` (a guard returned in `Flow::Run(guard)`, dropped at the end of `update`, so every move of the pass animates together) | nothing | `Run(())` |
+| `update` per layout | `fn adjust_layout(&self_ws, layouts: &mut [Rect], work_area: &Rect)` | nothing (the borders/padding are already applied by `calculate`) | clamps every layout to the work area, applies the percentage override | no-op |
+| `update`, a window gets its rect | `fn place_window(&self_ws, window: &P::Window, rect: &Rect, first: bool) -> eyre::Result<()>` | title-bar removal or restore (`REMOVE_TITLEBARS` and the per-window rules), `set_position(rect, top)` with the top flag set for the maximized and monocle windows, stackbar update for stacks | `set_rect`, `scrolling_placed` bookkeeping | `backend().set_rect` |
+| `update` end | `fn end_update(&mut self_ws)` | the scrolling `adopt_actual_widths` pass when animations are on and the user is not stepping a live resize (`live_resize::is_stepping`); stackbar redraw | `has_settled` | no-op |
+| `apply_wallpaper` | `fn apply_wallpaper(&self_ws, monitor: &MonitorId, wallpaper: &Wallpaper) -> eyre::Result<()>` | `WindowsApi::set_wallpaper` plus the palette theme built inline | asks the backend and calls `theme_manager::wallpaper_palette` | `Ok(())` (wallpaper is KDE/Windows only: the trait has no wallpaper operation, D36) |
+| `remove_window` | `fn on_window_removed(&mut self_ws, id: P::Window::Id)` | `border_manager::delete_border(id)` | nothing | no-op |
+| `remove_window` result | none: the shared version returns `eyre::Result