docs: §4.3 API & docs example audit

[rorygraves]

Summary

Pre-1.0 hardening item §4.3 — walk the public surface, every tutorial / guide / cookbook snippet, and remove copy-into-your-app surprises.

Doc fixes

File	Issue	Fix
docs/guide/app-layer.md	Cmd.asyncResult signature wrong (toCmd: A => Cmd[Msg]); Sub.TerminalResize signature wrong ((msg, sink)); enum block missing RequestAttention / Notify	Corrected to (task, onSuccess, onError, onEnqueue); corrected to (millis, mkMsg, ctx); added new cases to enum + table
docs/guide/widgets.md	MultiLineInput.handleKey[Msg](state, key)(_ => None) — that variant doesn't take a curried second arg list	Dropped the bogus (_ => None)
docs/guide/terminal-layer.md	Capabilities definition missing notifications: NotificationKind field	Added the 6th field with one-line cookbook pointer
docs/intro/architecture.md	Cmd.FCmd[Future[A], Msg] — wrong type params	Changed to Cmd.FCmd[A, Msg]; pointed at Cmd.asyncResult
docs/tut/01-hello-world.md	Full-source RootNode(...) missing required input arg — wouldn't compile	Added input = None
docs/tut/03-async.md	Cmd.FCmd table mislabeled 2nd param as onComplete; vague "Cookbook has a recipe" footnote	Renamed to toCmd; replaced footnote with concrete Cmd.asyncResult pointer
docs/cookbook/file-picker.md	Cmd.FCmd(Future{…}, Msg.LoadDone.apply) — A => Msg ≠ A => Cmd[M], wouldn't typecheck	Switched to Cmd.asyncResult(future, Msg.LoadDone.apply, Msg.LoadFailed.apply)
docs/cookbook/full-screen-layout.md	Orphaned Layout.column(gap = 0)(header, …) builder block before the real layout	Removed the dead block

Migration notes

docs/reference/migration.md is no longer an empty placeholder. Now states explicitly that 1.0 is source-compatible with 0.2.x / 0.3.x and catalogues the additive changes since 0.2.0 (error overlay, asyncResult, notifications, Grid / Border / toBudgetedRootNode, mouse-wheel scrollback) so apps can opt in. MiMa enforcement remains scheduled for the 1.0.x / 1.1 cycle as decided 2026-04-30.

Roadmap

Marked §4.3 as ☑ landed and added a 2026-04-30 decision entry under §8.

SPI surface

TuiRenderer, CmdConsumer, CmdBus, EventSink, EventSource already carry @note SPI in source Scaladoc. TerminalBackend is consumed by the runtime, rarely implemented by apps; an SPI annotation there is a Scaladoc tweak that fits §4.8 polish rather than this audit. ANSI raw escape constants in AnsiRenderer aren't surfaced in user docs.

Test plan

• mdbook build (with linkcheck backend) — clean, no warnings, no broken links
• Reviewer eyeballs the corrected snippets for the eight call sites listed above
• Reviewer confirms the migration-notes catalogue covers everything they consider user-visible since 0.2.0