chore(template): sync README.md

README.md

@@ -1,3 +1,67 @@
-# templates.SaaSStarter
+# SaaS Starter — W4C project template
 
-A multi-tenant SaaS web app with authentication, billing, a customer dashboard and an admin area.
+A W4C **project template**. Creating a project from it generates a private copy of this
+repository in your namespace and starts the **Startup Creator** agent, which drives the build
+from this brief.
+
+This repository is deliberately a **brief, not a finished app**: it ships the product
+specification, the project metadata and the seed assets; the tech stack chosen in the creation
+dialog decides the scaffold. Read [`SPEC.md`](SPEC.md) for the full product contract — roles,
+routes, data model, flows, functional and non-functional requirements, and the acceptance
+criteria the work is checked against. It is a multi-tenant SaaS: authentication, workspaces,
+billing, a tenant-scoped customer dashboard and a platform-operator back office.
+
+## What ships in this repository
+
+| Path | Purpose |
+|------|---------|
+| `README.md` | This file: how the template is wired and how to work in the project. |
+| `SPEC.md` | The product specification and acceptance criteria — the contract to build. |
+| `.w4c/template.json` | Template manifest: dialog fields, starter prompt, element list (templates only). |
+| `.w4c/project.json` | Project metadata committed with the repository. |
+| `.w4c/diagrams/` | Excalidraw architecture diagram. |
+| `.w4c/boards/roadmap.json` | Board columns and the seed tasks for the build. |
+| `.w4c/workflows/` | The CI workflow to import into the workflows module. |
+
+See [`.w4c/README.md`](.w4c/README.md) for the full `.w4c/` contract.
+
+## Stack
+
+The creation dialog records the chosen stack (and its skill pair `stack-*` +
+`stack-*-quality`), the billing provider, the tenancy model and the auth provider. Scaffold with
+those skills and hold the work to their conventions and quality gates. The stack is not fixed
+here on purpose: the same brief is built on Next.js, Vue 3 + Quasar, Laravel, Phoenix, … without
+changing `SPEC.md`.
+
+## Build order
+
+Work **top-down**, one layer at a time, and verify each layer before starting the next:
+
+1. **Scaffold** the stack and get the empty shell running (install → dev server → commit).
+2. **Scope** — routes and the data model from `SPEC.md` §3–§4, including `organisationId` and the
+   shared tenant-scoping layer.
+3. **Auth + tenant scoping** — signup, login, organisations, membership and roles, plus the
+   cross-tenant isolation test before any dashboard work.
+4. **Dashboard shell** scoped to the active organisation.
+5. **Billing + plan limits** (mock provider first, then real), including signature-verified,
+   idempotent webhooks and the server-side limit guard.
+6. **First product feature** from the must-have list.
+7. **Admin** back office, then **quality** — tests, CI, README quickstart, `.env.example`,
+   accessibility.
+
+The full rationale and the acceptance criteria live in `SPEC.md` §8–§9.
+
+## Working rules
+
+- One concern per commit, conventional messages (`feat:`, `fix:`, `chore:`, `docs:`, `test:`).
+- **Tenant isolation is the top requirement:** scope every query and mutation by
+  `organisationId` server-side; never trust a client-supplied tenant id, and never rely on
+  filtering in the UI.
+- Authorize every mutation on the server; never only in the UI.
+- Money is integer minor units (`priceMinor`), never floating point; format with the plan
+  currency and `en-US` number formatting.
+- Keep billing keys and provider secrets server-side only; verify webhook signatures and make
+  webhook/checkout handling idempotent.
+- Enforce plan limits server-side, not just in the UI.
+- Never commit secrets — document them in `.env.example` instead.
+- Keep `docs/PLAN.md`, the board and `.w4c/project.json` in sync as the project evolves.