docs overhaul, orientation API, fluid-sizing fixes, examples made honest

Documentation pass: every claim in docs/ and the meta files was audited against the source and the drift fixed — around ninety corrections. CONTRIBUTING and the CI workflow now run cargo test with --features test-support (the gated test_support module made both the documented commands and the CI build fail to compile), make example becomes make examples, make doctest-md and the debhelper requirement of make clean are documented, and patch shape asks for a CHANGELOG entry. theming.md loses the nonexistent surface.backdrop, gains the real gradient defaults (linear-rgb, oklab), the six slot variants including typography, the ten-field palette, a truthful effects-consumer table, the ThemePreference/from_hour API and a responsive-sizing note; the stale docstrings in src/theme that fed the drift are fixed too. architecture.md's "Known gaps" section is rewritten against reality (multi-touch slots, xdg-activation, a11y live regions and SetValue/Increment/Decrement are implemented), gains a module map, subsurfaces and window-lifecycle coverage, and correct crustace/loginmanager paths. widgets.md fixes the ten factual errors (stateless spinner, toast/combo via overlays(), tooltip hover contract, row has no max_width, scroll axes, multiline text_edit, dialog panic wording) and now states the column() 16 px default padding — the recurring ambush — plus row's differing 0 default and dialog's max_width. onboarding, README and cookbook get the remaining sweep: build/test instructions, complete example lists, img_widget, clipping-parity honesty, ~30 Hz software cap, read_rgba_pixels signature, tab indentation in snippets, and rustdoc-style links that rendered literally are gone everywhere. CHANGELOG is restructured per Keep a Changelog with the missing entries (window_resizable, claims_raw_touch, Row::align_top/fill_height, caret fixes, dependency pins) and the pad_v Added/Changed contradiction resolved.
New adaptive-layout API: ltk::orientation() with the Orientation enum, backed by viewport_size()/set_viewport_size — the runtime records the main surface's physical dimensions on every configure, before App::on_resize, so view() can branch a layout on portrait vs landscape without hand-tracking resizes. The portrait rule matches Length::orient (square counts as portrait); embedders driving core::UiSurface call set_viewport_size themselves. Documented in the crate root's responsive-design section and architecture.md.
Fluid-vs-fixed sizing fixes in widgets, all the same disease — fluid content inside a fixed-pixel box. TextEdit::fixed_width takes impl Into<Length> (f32 call sites keep compiling as px) and the time picker's digit fields move to Length::fluid( 72.0 ), matching their fluid font so digits can no longer outgrow the box. Dialog::max_width takes impl Into<Length> with a Length::fluid( 480.0 ) default so the card scales with the stock buttons inside it, and the card's interior no longer stacks the column() default 16 px padding on top of CARD_PADDING — that double inset squeezed the action row until its buttons clipped on narrow windows. App::on_pointer_axis now triggers a view rebuild and repaint; previously state mutated in the hook did not paint until the next unrelated event.
Examples reworked to be honest demos: responsive's mode/density controls become stock buttons in a grid/column so they follow the modes they demonstrate instead of overflowing; dialog's openers stack vertically, and the example gains the app-level ESC handler so the ESC chain closes an open dialog first and quits second; widgets' tab strip now switches real per-tab pages; carousel gains pointer/touch drag through the horizontal-swipe hooks (crustace's pager pattern), one-tile-per-detent mouse wheel, and snap math driven by the real surface width from on_resize instead of a hardcoded 800; clip_path arranges its cells by ltk::orientation() and sizes them from the counter-axis of the flow.

docs/onboarding.md

@@ -15,8 +15,8 @@ runtime-free UI surfaces.
 
 At a high level:
 
-- Implement the [`App`] trait.
-- Return an [`Element<Msg>`] tree from `view()`.
+- Implement the `App` trait.
+- Return an `Element<Msg>` tree from `view()`.
 - React to user input by handling messages in `update()`.
 - Start the event loop with `ltk::run(app)`.
 
@@ -40,8 +40,8 @@ it assumes:
 
 - a running **Wayland** session
 - Wayland client libraries available through Rust dependencies
-- a usable system font such as `google-sora-fonts`, `liberation-fonts` or
-  `dejavu-fonts`
+- a usable system font — on Debian (the crate's own packaging target):
+  `fonts-sora`, `fonts-liberation` or `fonts-dejavu`
 - an installed `default` theme, or a development theme directory exposed
   through `LTK_THEMES_DIR`
 
@@ -55,18 +55,50 @@ The rendering backend is selected automatically:
 From the repo root:
 
 ```bash
-cargo run --example showcase
+LTK_THEMES_DIR=themes cargo run --example showcase
 ```
 
-Other useful examples:
+The `LTK_THEMES_DIR=themes` prefix points theme lookup at the in-repo
+`themes/` directory (see *Theme and font setup* below); without it, on a
+machine without the `default` theme installed, the example runs on the
+embedded B/W fallback with a red banner.
+
+The other examples, same prefix:
 
 - `cargo run --example widgets` — broad widget survey
-- `cargo run --example inputs` — text entry
-- `cargo run --example scroll` — scroll viewport patterns
+- `cargo run --example inputs` — plain and secure text fields with a
+  show/hide-password toggle
+- `cargo run --example scroll` — the two main scroll use cases: a long list
+  and an app-drawer-style grid
+- `cargo run --example sliders` — the Glass effect on horizontal and
+  vertical sliders
+- `cargo run --example combo` — select/dropdown with editable query and
+  multi-select chips
+- `cargo run --example pickers` — notebook tabs, date, time and color
+  pickers
+- `cargo run --example dialog` — modal confirm, non-modal pick and the
+  other dialog shapes
+- `cargo run --example carousel` — focused-tile carousel
+- `cargo run --example responsive` — fluid vs physical scaling side by side
+- `cargo run --example clip_path` — per-path canvas clipping
 - `cargo run --example mini_shell` — overlays, animation and theme switching
 
 All examples require a running Wayland compositor.
 
+## Build and test
+
+The `Makefile` wraps the cargo invocations the repo expects:
+
+- `make all` — release build
+- `make test` — `cargo test --features test-support`; a bare `cargo test`
+  fails because the integration tests import the feature-gated
+  `ltk::test_support`
+- `make doctest-md` — typechecks the code snippets in `docs/*.md`, so API
+  drift surfaces in CI like a normal doctest failure
+- `make examples` — runs every example in sequence with
+  `LTK_THEMES_DIR=themes`
+- `make doc` — `cargo doc --no-deps`
+
 ## Theme and font setup
 
 `ltk` currently expects a theme named `default`. Lookup order is:
@@ -84,13 +116,15 @@ export LTK_THEMES_DIR="$PWD/themes"
 That makes `ThemeDocument::find("default")` resolve to
 `$PWD/themes/default/theme.json`.
 
-Font loading is separate from theme lookup. `Canvas` walks a chain of
-common system font paths (`fonts-sora`, `fonts-liberation`, `fonts-dejavu`,
-`fonts-freefont`, …) and uses the first one it finds. If nothing matches,
-it falls back to an embedded Sora Regular (~50 KB, SIL OFL 1.1) shipped
-inside the crate, so canvas construction never panics on a system without
-the expected fonts. Installing one of the listed packages is still
-recommended for richer glyph coverage.
+Font loading is separate from theme lookup. `src/system_fonts.rs` walks a
+chain of common system font *file paths* — the files installed by the
+Debian packages `fonts-sora`, `fonts-liberation`, `fonts-freefont` and
+`fonts-dejavu`, plus the equivalent locations other distros use — and
+loads the first one it finds. If nothing matches, it falls back to an
+embedded Sora Regular (~50 KB, SIL OFL 1.1) shipped inside the crate, so
+font resolution never panics on a system without the expected fonts.
+Installing one of the listed packages is still recommended for richer
+glyph coverage.
 
 ## Your first app
 
@@ -186,7 +220,7 @@ The APIs you will usually touch first live here conceptually:
 
 - `App`
 - `Element<Msg>`
-- `button`, `text`, `text_edit`, `image`
+- `button`, `text`, `text_edit`, `img_widget`
 - `column`, `row`, `stack`, `grid`, `spacer`
 - `container`, `scroll`, `slider`, `toggle`, `checkbox`, `radio`
 - `Color`
@@ -260,8 +294,11 @@ The knobs you will usually override are:
 - `keyboard_exclusive()`
 - `background_color()`
 
-For a non-trivial layer-shell example, use `examples/mini_shell.rs` as the
-reference entry point.
+For a non-trivial multi-surface example, use `examples/mini_shell.rs` as the
+reference entry point — note it runs as a regular window (it never overrides
+`shell_mode()`) and demonstrates screen routing, coordinated overlays, an
+animated OSD and live theme switching. The layer-shell knobs themselves are
+exercised by the downstream shell components, not by the in-repo examples.
 
 ## The APIs you will touch first
 
@@ -271,7 +308,7 @@ Start here:
 
 - `App`
 - `Element<Msg>`
-- `button`, `text`, `text_edit`, `image`
+- `button`, `text`, `text_edit`, `img_widget`
 - `column`, `row`, `stack`, `grid`, `spacer`
 - `container`, `scroll`, `slider`, `toggle`, `checkbox`, `radio`
 - `Color`
@@ -398,8 +435,17 @@ None of that blocks learning the toolkit, but it matters when you evaluate
 
 ## What to read next
 
+In the README's recommended order — onboarding, then the widget catalogue,
+then the cookbook, then architecture:
+
+- [`docs/widgets.md`](./widgets.md) — per-widget catalogue: what each one
+  is, when to use it, minimal example
+- [`docs/cookbook.md`](./cookbook.md) — concrete recipes: slide-in panels,
+  password fields, runtime theme toggle, channel-driven state
 - [`docs/architecture.md`](./architecture.md) — multi-surface patterns,
   theming, animation and performance
+- [`docs/theming.md`](./theming.md) — JSON theme schema, slot conventions,
+  runtime APIs
 - [`examples/showcase.rs`](../examples/showcase.rs) — smallest visual tour
 - [`examples/widgets.rs`](../examples/widgets.rs) — broader widget coverage
 - [`examples/mini_shell.rs`](../examples/mini_shell.rs) — overlays and shell