Add initial plan and README

Architectural design (PLAN.md) and project intro committed before any
implementation begins.

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

README.md

@@ -0,0 +1,70 @@
+# php-qml
+
+A framework for building native desktop applications with a Symfony / FrankenPHP backend and a Qt/QML frontend, packaged as a single distributable per OS.
+
+## Status
+
+**Planning stage.** The architectural design lives in [PLAN.md](PLAN.md). No implementation exists yet — first code lands in Phase 0 (a throwaway transport spike). See the [roadmap](PLAN.md#13-roadmap-to-poc).
+
+## What it is
+
+php-qml lets a PHP developer write a desktop application using ordinary Symfony on the backend and ordinary QML on the frontend. The two halves run as a process pair inside one bundled binary:
+
+- A Qt/QML host process owns the window, input, and rendering.
+- A bundled FrankenPHP child runs a Symfony application in worker mode.
+- They communicate over a local socket — HTTP for commands and queries, Mercure SSE for state push.
+
+The framework provides the lifecycle, transport, reactive models, and scaffolding so application code stays idiomatic on both sides.
+
+## What it is not
+
+Not a PHP↔Qt language binding. It does not embed PHP into a Qt event loop and it does not generate Qt classes from PHP. The two languages run in separate processes; the bridge is a wire protocol, not an FFI layer.
+
+If you've watched php-gtk and php-qt go quiet, that is the failure mode this project deliberately avoids — the framework owns the boring parts (lifecycle, transport, conventions) so it doesn't depend on a single maintainer keeping a language binding alive.
+
+## Tech stack
+
+- **Backend:** PHP 8.x, Symfony, Doctrine ORM, FrankenPHP (worker mode), Mercure
+- **Frontend:** Qt 6 LTS, QML, C++ plugin where required
+- **Build:** CMake, Composer
+- **CI:** Gitea Actions, Gitea Releases
+- **Targets:** Linux (AppImage), macOS (`.app` + `.dmg`), Windows (NSIS / MSIX)
+
+## Getting started
+
+Nothing to run yet. Once Phase 0 lands:
+
+1. Clone the repository and check out the `dev` branch.
+2. Install Qt 6 and PHP 8.x; the FrankenPHP runtime is fetched at build time.
+3. `task dev` — starts FrankenPHP in watch mode and launches the Qt host pointed at it.
+
+Detailed setup will be documented alongside the framework skeleton in Phase 1.
+
+## Project structure
+
+See [PLAN.md §9](PLAN.md#9-project-layout) for the intended layout. The repo currently contains only `PLAN.md` and this README.
+
+## Roadmap
+
+Six phases, each ending with something runnable. Detail in [PLAN.md §13](PLAN.md#13-roadmap-to-poc).
+
+- **Phase 0** — throwaway spike, prove transport on Linux.
+- **Phase 1** — framework skeleton, dev mode, single-instance lock, CI quality gate.
+- **Phase 2** — reactive models, update semantics, headline maker (`make:bridge:resource`).
+- **Phase 3** — POC todo application generated via the makers; testing infrastructure.
+- **Phase 4** — bundled mode, per-OS packaging, release CI, auto-update.
+- **Phase 5** — DX polish.
+
+## Contributing
+
+Active development happens on the `dev` branch; `main` only carries release commits. Pull requests target `dev`.
+
+A `CONTRIBUTING.md` will be added with the framework skeleton in Phase 1.
+
+## Versioning
+
+Semantic Versioning — `MAJOR.MINOR.BUGFIX`. MAJOR for breaking changes, MINOR for backwards-compatible features, BUGFIX for backwards-compatible fixes.
+
+## License
+
+To be decided before the first release. The framework's own code will be permissively licensed; note that Qt is shipped under LGPL and that carries obligations for distributors — see [PLAN.md §12](PLAN.md#12-open-questions-and-risks) (Qt LGPL relinkability).