docs(web): describe the free tier and the archive we actually ship

docs/advanced-docs/compile-guarantee.md

@@ -147,17 +147,17 @@ BUILD FAILURE — Attempt 1
 ========================
 
 Error 1:
-  File: api/YourProject.Api/Controllers/ProjectController.cs
+  File: dotnet/Controllers/ProjectEndpoints.cs
   Line: 47
-  Error: CS0161 — 'ProjectController.GetByWorkspace': not all code paths return a value
+  Error: CS0161 — 'ProjectEndpoints.GetByWorkspace': not all code paths return a value
 
 Error 2:
-  File: api/YourProject.Data/Repositories/ProjectRepository.cs
+  File: dotnet/Repositories/ProjectRepository.cs
   Line: 89
-  Error: CS1061 — 'DapperConnection' does not contain a definition for 'QuerySingleAsync'
+  Error: CS1061 — 'IDbConnection' does not contain a definition for 'QuerySingleAsync'
 
 AFFECTED FILES (full content):
-[ProjectController.cs — full file content]
+[ProjectEndpoints.cs — full file content]
 [ProjectRepository.cs — full file content]
 
 TASK: Fix only the specific errors listed above. Do not modify other files.

docs/user/faq.md

@@ -15,16 +15,20 @@ No. StackAlchemist generates real source code that you own and modify. It's a **
 ### What stack does StackAlchemist generate?
 
 V1 generates:
-- **Backend:** .NET 10 Web API with Dapper ORM and PostgreSQL
-- **Frontend:** Next.js 15 (App Router, TypeScript, Tailwind CSS)
-- **Database:** PostgreSQL with Supabase auth
-- **Dev Environment:** Docker Compose
+- **Backend:** .NET 10 minimal API with Dapper and PostgreSQL (one project, not a solution)
+- **Frontend:** Next.js 15 (App Router, TypeScript, Tailwind CSS) with a typed API client
+- **Database:** PostgreSQL migration with UUID keys and row-level security enabled
+- **Dev Environment:** Docker Compose + a multi-stage Dockerfile
 
-Additional stacks are planned for V2.
+No authentication flow is generated — the Supabase client and env slots ship preinstalled, the
+wiring is yours. Additional stacks are planned for V2.
 
 ### Do I need an account to try it?
 
-You can explore the interface and define your schema without an account. An account is required at the point of purchase and download.
+Yes, for anything past reading. The marketing pages, this FAQ, and the docs are public, but both
+build modes are gated: `/simple` and `/advanced` redirect a signed-out visitor to sign-in, so the
+account comes before the schema wizard, not after it. Starting a build needs one too — including
+a free Spark build, which is limited to 5 per calendar month.
 
 ---
 
@@ -42,11 +46,13 @@ You'll see real-time progress updates throughout.
 
 Every Boilerplate and Infrastructure package is run through the actual .NET and Next.js compilers before delivery:
 
-1. `dotnet build` is executed against the .NET API
-2. `npm run build` is executed against the Next.js frontend
+1. `dotnet restore` and `dotnet build --no-restore` are executed against the .NET API
+2. `npm ci`, `npm run typecheck` and `next build` are executed against the Next.js frontend
 3. If either fails, the error output is fed back to the LLM and the failing files are regenerated
 4. This retry loop runs up to **3 times**
 5. If the build is still failing after 3 attempts: **a full refund is initiated automatically, no questions asked**
+6. On success the archive gets a `build-report.json` naming every command, its exit code, and
+   the verdict per half — the same verdict your delivery page shows
 
 This is a hard technical constraint in the delivery pipeline — not a marketing claim.
 
@@ -74,9 +80,10 @@ Yes. The generated code has no licensing restrictions. Use it, sell it, scale it
 
 | Tier | What you get |
 |------|-------------|
-| Blueprint ($299) | Architecture documents: schema, OpenAPI spec, SQL, data flow diagram |
-| Boilerplate ($599) | Full compiled source code + Docker Compose |
-| Infrastructure ($999) | Everything + AWS CDK, Helm charts, CI/CD pipeline, deployment runbook |
+| Spark (free) | A fixed demo app running in your browser. Not built from your description, not downloadable. |
+| Blueprint ($299) | Architecture documents: `schema.json` and `api-docs.md` (the CRUD contract) |
+| Boilerplate ($599) | The generated source built from your schema, both halves compiled, + Docker Compose |
+| Infrastructure ($999) | Everything + AWS CDK, Terraform, Helm chart, deployment runbook |
 
 See [Tiers and Pricing](./tiers-and-pricing) for full details.
 
@@ -114,7 +121,7 @@ Yes. The Boilerplate tier generates a Docker Compose setup that runs on any mach
 
 ### What database does it use?
 
-PostgreSQL for the primary data store. Supabase provides auth, real-time subscriptions, and storage on top of PostgreSQL. The generated code uses raw SQL via Dapper — not Entity Framework — so the database layer is lightweight and explicit.
+PostgreSQL for the primary data store, reached with raw SQL via Dapper — not Entity Framework — so the database layer is lightweight and explicit. Supabase is the intended home for auth, real-time, and storage on top of that PostgreSQL: the client library and the env slots ship in the archive, but no auth code is generated for you.
 
 ---
 

docs/user/getting-started.md

@@ -59,40 +59,67 @@ Use the entity wizard to define your schema step by step:
 
 | Tier | Name | Price | What You Receive |
 |------|------|-------|-----------------|
-| **Tier 0** | Spark | Free | Live preview only, with schema canvas and no download |
-| **Tier 1** | Blueprint | $299 | Architecture documents: ER schema, OpenAPI spec, SQL migration scripts, data flow diagram |
-| **Tier 2** | Boilerplate | $599 | Everything in Blueprint + compiled .NET 10 API, Next.js 15 frontend, PostgreSQL schema, Docker Compose |
-| **Tier 3** | Infrastructure | $999 | Everything in Boilerplate + AWS CDK stack, Helm charts, CI/CD pipeline, deployment runbook |
+| **Tier 0** | Spark | Free | A fixed demo app that boots in your browser. Not built from your description, and not downloadable. |
+| **Tier 1** | Blueprint | $299 | Architecture documents: `schema.json` and `api-docs.md` (the CRUD contract per entity) |
+| **Tier 2** | Boilerplate | $599 | The generated source: .NET 10 minimal API, Next.js 15 frontend, PostgreSQL migration, Docker Compose — both halves compiled before delivery |
+| **Tier 3** | Infrastructure | $999 | Everything in Boilerplate + AWS CDK stack, Terraform baseline, Helm chart, deployment runbook |
 
 > **All prices are one-time.** No subscriptions, no recurring fees. The generated code is entirely yours.
 
+### About the free tier
+
+Spark exists so you can watch the machine run before paying for it. It renders one fixed
+template — a small task tracker — with your project name substituted in, and makes **no AI
+call at all**. That is why it is instant, free, and always boots. It is not a preview of the
+code a paid tier would produce for you, it contains no .NET half, and it cannot be
+downloaded.
+
+What Spark is genuinely good for:
+
+- Proving the end-to-end flow works in your browser before you pay (the in-browser runtime
+  needs a Chromium-based browser — Chrome, Edge, Arc)
+- Seeing the delivery page and the embedded editor exactly as a paid run presents them
+- Reading a real Next.js 15 App Router project file by file, and editing it live
+- Modelling your entities on the Advanced Mode ER canvas — that schema is saved with the
+  build, so you can come back and buy a paid run against it
+
+You get **5 free builds per calendar month** per account.
+
 ---
 
 ## Step 4: Generate
 
 Click **Synthesize** (or press `Ctrl + Enter` in Simple Mode). Watch real-time progress as StackAlchemist:
 
-1. Parses and validates your schema
-2. Applies Handlebars templates to the structure
-3. Injects LLM-generated business logic into the holes
-4. Runs the output through the compiler
-5. Auto-corrects any build errors (up to 3 retries)
-6. Packages everything into a ZIP archive
+1. Renders the template tree for your stack and substitutes your project name
+2. Sends your description or schema to the model and reconstructs the returned files into that tree
+3. Runs `dotnet restore` and `dotnet build` against the API half
+4. Runs `npm ci`, `npm run typecheck`, and `next build` against the frontend half
+5. Auto-corrects any build errors and retries (up to 3 retries)
+6. Writes `build-report.json` and packages everything into a ZIP archive
 
 Generation typically takes **30–90 seconds** depending on schema complexity.
 
+A free Spark build skips all of that: it renders the fixed demo template and hands it to the
+in-browser runtime, which is why it returns almost immediately.
+
 ---
 
 ## Step 5: Download and Run
 
-Extract the ZIP archive. Every Boilerplate and Infrastructure package includes a `README.md` with specific setup instructions, but the general pattern is:
+Extract the ZIP archive. The root of a Boilerplate or Infrastructure package holds
+`docker-compose.yml`, a multi-stage `Dockerfile`, `.env.example`, and `build-report.json`
+(the record of the builds that were run against your code). The two halves live in
+`dotnet/` and `nextjs/`.
 
 > **Prerequisite — configure `.env` before starting the stack.** The API will not
 > boot with an empty `.env`: after copying `.env.example`, open `.env` and fill in
-> the required values (database credentials and, if your package uses Supabase
-> auth, the keys from your Supabase dashboard). Every required key is documented
-> in the generated `README.md`. Skipping this is the #1 cause of "the frontend
-> loads but every API call fails" on a fresh download.
+> the required values — at minimum `DATABASE_URL` /
+> `ConnectionStrings__DefaultConnection`. The Supabase entries are placeholders for
+> the client library that ships preinstalled in the frontend; no auth flow is
+> generated, so leave them alone until you wire one up. Skipping the database
+> values is the #1 cause of "the frontend loads but every API call fails" on a
+> fresh download.
 
 ```bash
 # 1. Unzip and navigate
@@ -114,10 +141,13 @@ Your dev environment will be running at:
 
 ## Common First Steps After Download
 
-- Review `README.md` in the root — it has all env variable documentation
+- Read `build-report.json` in the root — it names every command that was run against your
+  code, its exit code, and the per-half verdict
 - The `.env.example` file lists all required configuration keys
-- Database migrations are in `/migrations` — they run automatically on first `docker compose up`
-- Supabase auth keys need to be populated from your Supabase project dashboard
+- Database migrations are in `dotnet/Migrations/` — `docker compose up` mounts that directory
+  into the Postgres init hook, so they run automatically on first boot
+- API endpoints are mapped under `/api/v1/{entity}` and the OpenAPI document is served in
+  Development at `/openapi/v1.json`
 
 ---
 

docs/user/simple-mode.md

@@ -20,10 +20,18 @@ Use [Advanced Mode](./advanced-mode) instead when you have a precise data model
 
 1. Enter your application description in the prompt field on the home page
 2. Click **Synthesize** or press `Ctrl + Enter`
-3. StackAlchemist's LLM layer parses your description and produces a structured entity schema
-4. You review the generated schema before committing to purchase
-5. Select your tier and complete checkout
-6. The generation pipeline runs and packages your output
+3. A free Spark build starts immediately and lands you on the delivery page with a demo app
+   running in your browser. Spark is a fixed template, so nothing is interpreted at this step.
+4. Choose a paid tier from that page and complete checkout
+5. The generation pipeline reruns against your description — for Boilerplate and
+   Infrastructure the model reads your prose directly and emits the entities, repositories,
+   endpoints, migration, and typed frontend client in one pass
+6. Both halves are compiled, then your archive is packed and made available
+
+> **There is no schema-review step in Simple Mode.** Your description goes to the model as
+> written. If you want to see and edit the entity model before you buy, use
+> [Advanced Mode](./advanced-mode) — its wizard is where the ER canvas lives, and the schema
+> you build there is what the paid run generates from.
 
 ---