docs(webui): ship release-time user docs and surface --webui in --help

[inureyes]

Part of #1910.

Problem / Background

Epic #1834 shipped the bundled macOS-style WebUI, and #1848 (PR #1898) is its integration gate. The WebUI is still experimental, so on 2026-09-16 the maintainer decided that release-facing documentation lands at actual release time rather than with the feature work. #1849 ("docs(webui): document secure workflows and bundled distribution") is closed and its entire scope moves here unchanged, together with one CLI discoverability defect found while validating the bundled server. This issue is the single place where the deferred documentation, that CLI fix, and the final epic checklist are tracked.

Current Behavior

docs/webui/ already holds the developer and contract documents produced by the earlier children: api.yaml, architecture.md, ux-contract.md, state-machines.md, catalog.md (plus catalog.ko.md), chat.md, settings.md, runtime.md, activity.md, bundling.md (plus bundling.ko.md), design-system.md, ui-common.md, and generated/. docs/webui/README.md does not exist. The root README.md contains zero mentions of the WebUI (grep -ic webui README.md returns 0), so nothing on the project front page tells a user the feature exists.

--webui itself works. Running mlxcel-server --webui without --api-key on a non-interactive loopback listener correctly refuses with "--webui without --api-key is only allowed on an interactive loopback terminal so the generated session key can be shown once" (src/server/webui/security/startup.rs:96). The flag does not appear in --help at all: --ui with alias = "webui" (src/cli/ui_compat_args.rs:70-77) and --no-ui with alias = "no-webui" (src/cli/ui_compat_args.rs:80-87) are declared hide = true, because the whole UiCompatArgs group is the llama-server b10621 compatibility surface and every argument in it is hidden by that group's stated policy (src/cli/ui_compat_args.rs:62-67). Epic #1834 treats --webui as the primary product flag rather than only a compatibility alias, so a user has no path from --help to the feature.

Proposed Solution

Two tracks, both landing at release time.

A. Release-facing documentation, scope transferred from #1849

• Copy/paste quickstarts for mlxcel-server --webui and the equivalent mlxcel serve --webui, covering explicit --models-dir, the managed model-store root, single-model mode, offline use, enabled live settings, and safe authenticated remote or reverse-proxy access.
• The generated local session key, the no-terminal behavior, and memory-only browser login. No example ever prints a real secret or a token-bearing URL.
• The distinction between supported, downloaded, and loaded, plus source precedence and containment, the explicit preload exception to the empty-start guarantee, model and task capability gates, the load / drain / memory-release distinction, cancellation limits, and cache removal versus unload.
• The separation between browser preferences and history, per-request sampling, live settings, next-load profiles, and restart-only controls, with privacy defaults, local history opt-in / export / clear, and the explicit statements that there is no remote telemetry and no tool execution.
• Contributor workflow: contract-first changes, shared module ownership, frontend source versus generated assets, pinned pnpm install and build, asset regeneration and the drift check, offline Rust builds, the UI Cargo feature graph, and the distinction between webui/ and the marketing webpage/.
• docs/webui/README.md as the entry point, links from the root README.md and docs/README.md, and English and Korean user documents. Korean coverage today is partial (bundling.ko.md, catalog.ko.md) and the user-facing set needs both languages.
• The b10621 UI alias / disable / environment / static-path / config / tool / proxy classifications in compat/llama-server/b10621/ui-tools-mcp-gcp.json must accurately describe implemented versus rejected behavior, including the root-health divergence notes.
• Bundle source hash and size, the offline moved-binary check, and release feature inclusion must link to final integration evidence rather than restate intent.
• NOTICE retains all frontend and adapted-code licenses and per-file derivation notices, and no Apple design-kit or system font asset is redistributed.

B. CLI discoverability for --webui

Make --webui discoverable from --help on both mlxcel-server and mlxcel serve, without breaking the b10621 compatibility classification and without unhiding genuinely unsupported compatibility arguments: --ui-config, --ui-config-file, --path, --tools, --tools-runtime, --mcp-servers-config, --mcp-servers-json, --ui-mcp-proxy, --agent and their negative forms stay hidden and still fail startup with their existing diagnostics. This issue does not prescribe an implementation: a visible product argument beside the hidden compatibility alias, an after_help section on the two help surfaces (src/bin/mlx_server.rs:105, src/main.rs:1024), or unhiding only this one pair are all acceptable as long as the manifest and its gate stay truthful. This is a code change rather than documentation, so per #1849's ownership rule it is coordinated with the startup owner (#1838), who owns central CLI, config, and route registration.

Scope

In scope: a new docs/webui/README.md and the English and Korean user documents under docs/webui/; the root README.md WebUI section and the docs/README.md index entry; CLI help visibility for --webui in src/cli/ui_compat_args.rs and the after_help surfaces in src/bin/mlx_server.rs and src/main.rs; the --ui entry in compat/llama-server/b10621/ui-tools-mcp-gcp.json (its mlxcel.hidden field on line 252 and the accompanying notes); a NOTICE review; and the final epic checklist posted on #1834.

Out of scope: any behavior change to the WebUI itself; the model inspector affordance, which is tracked in its own issue; lifting the two deferrals recorded in docs/webui-integration-matrix.md; and the epic's deferred features (private Hub authentication, native packaging, tools/MCP, other task UIs), which are documented as limits and never as enabled placeholders.

Implementation Notes

• Reuse: the contract and developer docs already under docs/webui/ are the source of truth for endpoint shapes and lifecycle states, so the user docs summarize and link them instead of restating the contract. docs/webui-integration-matrix.md is the canonical evidence table; link its rows rather than copying numbers into prose that then goes stale.
• Constraints: the b10621 manifest is gated by make verify-llama-compat (scripts/ci/check_llama_compat_manifest.py), so changing mlxcel.hidden for the --ui entry requires the manifest and the real clap declaration to agree, and src/cli/ui_compat_args_tests.rs::webui_enable_disable_resolves_with_last_flag_winning must keep passing.
• Edge cases: a --no-default-features build has no UI and must reject an enabling flag with the documented diagnostic; a UNIX-socket-only listener rejects WebUI with a TCP or reverse-proxy instruction; an absent default store is an empty library rather than a startup failure; an invalid explicit root is an actionable error.
• Error handling: every failure path shown in the docs (bad root, unauthenticated access, UI not compiled) is reproduced against the installed artifact and the documented text is corrected to the actual message, never the reverse.

Acceptance Criteria

• English and Korean user docs and help examples are exercised against the installed artifact, not only reviewed as prose, and the bad-root, unauthenticated-access, and UI-not-compiled diagnostics match the documented text verbatim.
• docs/webui/README.md exists as the WebUI entry point, the root README.md links to it, and grep -ic webui README.md no longer returns 0.
• The b10621 UI alias / disable / environment / static-path / config / tool / proxy classifications accurately describe implemented versus rejected behavior and preserve the root-health divergence notes, with make verify-llama-compat passing.
• Bundle source hash and size, the offline moved-binary check, and release feature inclusion are each linked to final integration evidence from test(webui): gate bundled UX, security, and real-model integration #1848 and PR update: add bundled WebUI integration verification #1898, and normal MLX runtime dependencies remain explicit.
• mlxcel-server --help and mlxcel serve --help both show --webui, while every unsupported b10621 UI, tools, MCP, and proxy argument stays hidden and still fails startup with its existing diagnostic.
• NOTICE retains all frontend and adapted-code licenses and per-file derivation notices, and no Apple design-kit or system font asset is redistributed.
• A final epic checklist is posted on epic: ship a bundled macOS-style model control interface #1834 listing every deferred item with its concrete scope, including the two already recorded in docs/webui-integration-matrix.md: manual VoiceOver against the installed artifact (user-deferred 2026-09-16, not run) and the native hidden Activity acceptance, that is the minimize-to-document.hidden measurement (user-deferred 2026-09-16). Nothing deferred appears as a functioning button.
• The documentation is integrated into the real product surface (root README, docs/README.md index, and CLI help), not left as unlinked files.

Verification

cargo build --release --features metal,accelerate
./target/release/mlxcel-server --help | grep -- --webui
./target/release/mlxcel serve --help | grep -- --webui
./target/release/mlxcel-server --help | grep -E -- '--ui-config|--tools|--mcp-servers|--ui-mcp-proxy|--agent'   # must print nothing
make verify-llama-compat
cargo test --workspace --profile test-fast --features metal,accelerate
cargo clippy --workspace --all-targets --features metal,accelerate -- -D warnings
cargo fmt --check

A pass means the first three greps print the flag or nothing as annotated, make verify-llama-compat exits 0, and the workspace gate is green. Manual pass: run every quickstart in the docs against the installed release binary in both languages, including the failure paths, and record the artifact SHA-256 and the UI bundle digest alongside the results.

Technical Considerations

Transferred from #1849, which is closed in favor of this issue. Part of epic #1834; the evidence this issue links comes from #1848 and PR #1898.