feat: add APIMart AI generation and guided Studio onboarding

README.md

@@ -106,3 +106,46 @@ A refreshed package-lock.json is retained for npm tooling, but Bun runs the app.
 After deployment, check `/`, a component playground and `/design-studio/`.
 Create a draft, generate alternatives, open a preview, export JSON, then reload
 and confirm draft recovery. Existing Studio drafts on other origins remain there.
+
+## APIMart AI generation
+
+Create a `.env` file in the application root on the VM (copy `.env.example`):
+
+```dotenv
+APIMART_API_KEY=your_apimart_key
+```
+
+Restart the app after setting the key. No key goes in the browser or application
+configuration. The server calls https://api.apimart.ai/v1/chat/completions with
+model `gpt-6-luna`, bearer authentication, and `stream: false`, as described in
+https://docs.apimart.ai/en/api-reference/texts/general/chat-completions.
+Model access must be available on your APIMart account. No live provider call is
+part of the normal build or test suite.
+
+Open `/design-studio/` and follow the in-page guide:
+
+1. In Guided design, enter what you are building and who will use it. Use Next
+   to choose tone, geometry, spacing, surfaces and optional brand references.
+2. Generate three directions. Review a direction, inspect its changes, then
+   select Use reviewed proposal to save it as a recoverable draft revision.
+3. Under Edit with words, request a change, for example “Make the buttons square,
+   use blue as the primary color, and reduce shadows.” Lock colors, geometry or
+   other decisions to keep them unchanged.
+4. Preview the design at different sizes and in light/dark mode. Use Components
+   for individual recipes and Foundations for exact token values.
+5. Open Review & apply and export Theme config or Compiled CSS. Integrate one
+   of those outputs into your application's theme/style configuration. This
+   hosted Studio does not write to deployed application files.
+
+AI generation sends the current design, brief and allowed component capabilities
+to APIMart when you request generation. The engine validates proposals and locks
+before offering them for review. Failed requests leave the draft unchanged.
+Requests allow two concurrent generations and ten starts per minute per server
+process, with two attempts, 4096 output tokens per attempt and a 20-second deadline.
+Without APIMART_API_KEY, generation uses local rules and reports that in the UI;
+local rules do not interpret arbitrary product descriptions. Drafts remain in
+browser storage; export before clearing browser data or moving to another origin.
+
+The complete check includes mocked provider contract/error/lock tests and a
+compiled-server deployment check. A real APIMart completion requires your key
+and model access; it is not claimed by the mocked tests.