docs: rewrite README + add comprehensive docs/

README is now tight and link-heavy: 60-second tour, then deep links
into docs/. The wall of detail moved out.

docs/ covers the framework end-to-end:
- getting-started.md — prerequisites by distro (Tumbleweed, Fedora,
  Debian/Ubuntu, Arch), full first-run walkthrough, troubleshooting.
- architecture.md — process pair, transport, dev/bundled mode.
- update-semantics.md — state machine + optimistic mutations + key
  round-tripping.
- reactive-models.md — ReactiveListModel, ReactiveObject, Mercure
  dual-publish.
- makers.md — make:bridge:resource/command/window.
- dev-workflow.md — hot reload (PHP + QML), dev console, editor
  configs, bridge:doctor, snapshot/integration test loops, perfsmoke.
- bundled-mode.md — supervisor, per-session secret rotation,
  first-launch migrations, auto-update wiring.
- packaging-linux.md — make appimage, build-appimage.sh CLI,
  AppImageUpdate sidecar, perfsmoke budgets, release CI, bundle-size
  breakdown.
- qml-api.md / php-api.md — exhaustive symbol reference with all
  Q_PROPERTY/Q_INVOKABLE/signals + every public PHP service / attribute
  / command.
- configuration.md — every env var (host, Symfony, dev script,
  packaging script, perfsmoke), every CLI flag (php-qml-init,
  build-appimage.sh), make targets, default ports/paths.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/README.md

@@ -0,0 +1,34 @@
+# Documentation
+
+Developer documentation for [php-qml](../README.md). Design rationale and roadmap live in [PLAN.md](../PLAN.md); per-release changes in [CHANGELOG.md](../CHANGELOG.md).
+
+## Start here
+
+- **[Getting started](getting-started.md)** — install prerequisites, scaffold a project, run it, troubleshoot.
+- **[Architecture](architecture.md)** — process-pair design, transport, dev vs bundled mode.
+
+## Concepts
+
+- **[Update semantics](update-semantics.md)** — `Connecting → Online → Reconnecting → Offline`, optimistic mutations, idempotency-key round-tripping.
+- **[Reactive models](reactive-models.md)** — `ReactiveListModel`, `ReactiveObject`, Mercure dual-publish on `app://model/<name>` and `app://model/<name>/<id>`.
+- **[Bundled mode](bundled-mode.md)** — what changes when there is no `BRIDGE_URL`: supervisor, per-session secret rotation, first-launch migrations.
+
+## Guides
+
+- **[Makers](makers.md)** — `make:bridge:resource`, `make:bridge:command`, `make:bridge:window`.
+- **[Dev workflow](dev-workflow.md)** — hot reload (PHP + QML), dev console (`Ctrl+\``), editor configs, `bridge:doctor`.
+- **[Linux packaging](packaging-linux.md)** — `make appimage`, AppImageUpdate, performance budgets.
+
+## Reference
+
+- **[QML API](qml-api.md)** — `BackendConnection`, `RestClient`, `MercureClient`, `ReactiveListModel`, `ReactiveObject`, `AppShell`, `DevConsole`, `SingleInstance`.
+- **[PHP API](php-api.md)** — `BridgeBundle`, `#[BridgeResource]`, `ModelPublisher`, `bridge:doctor`, `CorrelationKeyListener`, `SessionAuthenticator`.
+- **[Configuration](configuration.md)** — env vars (`BRIDGE_URL`, `BRIDGE_TOKEN`, `FRANKENPHP`, …) and CLI flags for `php-qml-init` / `build-appimage.sh`.
+
+## How the docs are organised
+
+- **Concept** docs answer *what is this and why?*. They reference code only when it clarifies the model.
+- **Guide** docs walk through a workflow end-to-end with copy-pasteable commands.
+- **Reference** docs are exhaustive lookups for symbols, env vars, and flags. They prioritise findability over narrative.
+
+When something is in flux or aspirational, the doc says so and links into [PLAN.md](../PLAN.md). When a feature is shipped, the doc covers it without forward-looking caveats.