Upload 23 files

.env

@@ -0,0 +1,2 @@
+OLLAMA_BASE_URL=http://127.0.0.1:11434
+OLLAMA_MODEL=codellama:7b

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+app/services/__pycache__/ai_service.cpython-314.pyc filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,15 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+ENV PORT=7860
+
+COPY requirements.txt .
+
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 7860
+
+CMD ["sh", "-c", "uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-7860}"]

README.md

@@ -1,12 +1,139 @@
----
-title: Auto Coding Agent
-emoji: 👀
-colorFrom: yellow
-colorTo: green
-sdk: docker
-pinned: false
-license: mit
-short_description: AI Project Agent that generates full-stack projects instantl
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: Project Agent
+emoji: 🚀
+colorFrom: blue
+colorTo: purple
+sdk: docker
+app_port: 7860
+---
+
+# Project Agent
+
+Project Agent is a FastAPI web app that turns a rough project idea into a **100% runnable starter project** preview, then creates a ZIP only after the user confirms it. The deployed app is designed to stay usable for free on Hugging Face Spaces even when no Ollama service is available.
+
+## Features
+
+- Suggest -> Preview -> Regenerate -> Confirm ZIP workflow
+- Fast/Deep generation modes with Fast Mode as the default
+- Template-first project generation with required docs, scripts, and dependency files
+- Safe fallback previews when AI is unavailable, slow, or invalid
+- ZIP output that contains generated source, config, scripts, and docs only
+- Safe path validation and generated output constrained to `generated/`
+- Docker-ready deployment for Hugging Face Spaces
+
+## Requirements
+
+The app depends on:
+
+- `fastapi`
+- `uvicorn[standard]`
+- `jinja2`
+- `python-dotenv`
+- `httpx`
+
+## Run Locally
+
+Install dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+Start the app with the default Hugging Face-friendly port:
+
+```bash
+python -m app.main
+```
+
+Or run Uvicorn directly:
+
+```bash
+uvicorn app.main:app --host 0.0.0.0 --port 7860
+```
+
+To use a different port:
+
+```bash
+PORT=8000 python -m app.main
+```
+
+Then open `http://127.0.0.1:7860` or the port you set.
+
+## Environment Variables
+
+Optional app/runtime variables:
+
+```env
+PORT=7860
+OLLAMA_BASE_URL=http://localhost:11434
+OLLAMA_MODEL=qwen2.5-coder
+```
+
+Notes:
+
+- `PORT` defaults to `7860`, which matches Hugging Face Spaces.
+- If `OLLAMA_BASE_URL` is missing or unreachable, Fast Mode still works by returning a complete template-based preview.
+- Deep Mode remains optional. If AI is unavailable, the app still returns a valid preview and notes that Deep AI enrichment was skipped.
+
+## Hugging Face Spaces Deployment
+
+Deploy this project as a **Docker Space**.
+
+### 1. Create the Space
+
+- Create a new Space on Hugging Face
+- Choose **Docker** as the Space SDK
+- Push this repository to the Space
+
+### 2. Container Runtime
+
+The included `Dockerfile` starts the app with:
+
+```bash
+uvicorn app.main:app --host 0.0.0.0 --port 7860
+```
+
+The container also supports `PORT` overrides through the environment and defaults to `7860`.
+
+### 3. Free Deployment Behavior
+
+For the free public version, you do **not** need cloud Ollama.
+
+- Fast Mode works without Ollama by using template fallback
+- Deep Mode attempts AI enrichment only if Ollama is reachable
+- If Ollama is unavailable, the app still returns a complete preview instead of failing
+
+### 4. Optional AI Configuration
+
+If you later want AI-backed planning on a deployment that can reach Ollama, set:
+
+```env
+OLLAMA_BASE_URL=https://your-ollama-endpoint
+OLLAMA_MODEL=qwen2.5-coder
+```
+
+If those values are not set, the app remains usable in fallback mode.
+
+## ZIP Output Behavior
+
+Generated ZIPs:
+
+- do not include installed libraries
+- do not include `.venv`
+- do not include `node_modules`
+- do include dependency manifests, setup scripts, run scripts, starter code, and generated docs
+
+This keeps ZIP creation compatible with Hugging Face temporary storage.
+
+## API Endpoints
+
+- `GET /` renders the frontend
+- `POST /api/suggest` returns a normalized project preview
+- `POST /api/zip` writes the confirmed project into `generated/` and returns a download URL
+- `GET /downloads/{filename}` downloads the generated ZIP
+
+## Deployment Notes
+
+- Generated project artifacts are written only inside `generated/`
+- The app assumes ephemeral writable storage is acceptable for preview ZIP downloads
+- No dependency installation happens during preview or ZIP creation

app/__init__.py

@@ -0,0 +1 @@
+

app/main.py

@@ -0,0 +1,228 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from dotenv import load_dotenv
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from fastapi.templating import Jinja2Templates
+from pydantic import BaseModel, Field
+
+from .services.agent_controller import agent_controller
+from .services.file_service import ensure_within_directory
+from .services.zip_service import create_project_zip
+
+
+load_dotenv()
+
+ROOT_DIR = Path(__file__).resolve().parent.parent
+APP_DIR = ROOT_DIR / "app"
+GENERATED_DIR = ROOT_DIR / "generated"
+DEFAULT_PORT = 7860
+
+app = FastAPI(title="Project Agent")
+app.mount("/static", StaticFiles(directory=APP_DIR / "static"), name="static")
+templates = Jinja2Templates(directory=str(APP_DIR / "templates"))
+
+
+class StackSelectionPayload(BaseModel):
+    language: str = "Auto"
+    frontend: str = "Auto"
+    backend: str = "Auto"
+    database: str = "Auto"
+    aiTools: str = "Auto"
+    deployment: str = "Auto"
+
+
+class EnvVariablePayload(BaseModel):
+    name: str
+    value: str = ""
+    description: str = ""
+
+
+class RequiredInputPayload(BaseModel):
+    name: str
+    required: bool = True
+    example: str = ""
+    whereToAdd: str = ".env"
+    purpose: str = ""
+
+
+class SuggestRequest(BaseModel):
+    idea: str = Field(..., min_length=1)
+    selectedStack: StackSelectionPayload | None = None
+    generationMode: str = "fast"
+    finalRequirements: str = ""
+
+
+class AgentAnalyzeRequest(BaseModel):
+    idea: str = Field(..., min_length=1)
+
+
+class AgentQuestionPayload(BaseModel):
+    id: str
+    question: str
+    type: str
+    options: list[str] = Field(default_factory=list)
+    default: str = ""
+    reason: str = ""
+
+
+class AgentAnalyzeResponse(BaseModel):
+    understanding: str
+    assumptions: list[str] = Field(default_factory=list)
+    suggestedStack: StackSelectionPayload = Field(default_factory=StackSelectionPayload)
+    stackReasons: list[str] = Field(default_factory=list)
+    questions: list[AgentQuestionPayload] = Field(default_factory=list)
+    detectedProjectType: str = "full-stack"
+    confidence: int = 0
+
+
+class AgentFinalizeRequest(BaseModel):
+    idea: str = Field(..., min_length=1)
+    answers: dict[str, Any] = Field(default_factory=dict)
+    suggestedStack: StackSelectionPayload = Field(default_factory=StackSelectionPayload)
+
+
+class AgentFinalizeResponse(BaseModel):
+    finalRequirements: str = ""
+    selectedStack: StackSelectionPayload = Field(default_factory=StackSelectionPayload)
+    assumptions: list[str] = Field(default_factory=list)
+
+
+class ModulePayload(BaseModel):
+    name: str
+    purpose: str = ""
+    keyFiles: list[str] = Field(default_factory=list)
+
+
+class FilePayload(BaseModel):
+    path: str
+    content: str = ""
+
+
+class PreviewPayload(BaseModel):
+    projectName: str
+    detectedUserChoices: list[str] = Field(default_factory=list)
+    selectedStack: StackSelectionPayload = Field(default_factory=StackSelectionPayload)
+    chosenStack: list[str] = Field(default_factory=list)
+    assumptions: list[str] = Field(default_factory=list)
+    summary: str = ""
+    problemStatement: str = ""
+    architecture: list[str] = Field(default_factory=list)
+    modules: list[ModulePayload] = Field(default_factory=list)
+    packageRequirements: list[str] = Field(default_factory=list)
+    installCommands: list[str] = Field(default_factory=list)
+    runCommands: list[str] = Field(default_factory=list)
+    requiredInputs: list[RequiredInputPayload] = Field(default_factory=list)
+    envVariables: list[EnvVariablePayload] = Field(default_factory=list)
+    fileTree: str = ""
+    files: list[FilePayload] = Field(default_factory=list)
+
+
+class ZipRequest(BaseModel):
+    preview: PreviewPayload
+
+
+@app.get("/", response_class=HTMLResponse)
+async def index(request: Request) -> HTMLResponse:
+    return templates.TemplateResponse("index.html", {"request": request})
+
+
+@app.post("/api/suggest")
+async def suggest_project(payload: SuggestRequest) -> JSONResponse:
+    idea = payload.idea.strip()
+    if not idea:
+        raise HTTPException(status_code=400, detail="Please enter a project idea.")
+
+    try:
+        preview = await agent_controller.generate_files(
+            idea,
+            payload.selectedStack.model_dump() if payload.selectedStack else None,
+            payload.generationMode,
+            payload.finalRequirements,
+        )
+    except RuntimeError as exc:
+        raise HTTPException(status_code=502, detail=str(exc)) from exc
+
+    return JSONResponse(preview)
+
+
+@app.post("/api/agent/analyze")
+async def analyze_agent(payload: AgentAnalyzeRequest) -> JSONResponse:
+    idea = payload.idea.strip()
+    if not idea:
+        raise HTTPException(status_code=400, detail="Please enter a project idea.")
+
+    return JSONResponse(agent_controller.analyze_idea(idea))
+
+
+@app.post("/api/agent/finalize")
+async def finalize_agent(payload: AgentFinalizeRequest) -> JSONResponse:
+    idea = payload.idea.strip()
+    if not idea:
+        raise HTTPException(status_code=400, detail="Please enter a project idea.")
+
+    finalized = agent_controller.finalize_requirements(
+        idea,
+        payload.answers,
+        payload.suggestedStack.model_dump(),
+    )
+    return JSONResponse(finalized)
+
+
+@app.post("/api/zip")
+async def build_zip(payload: ZipRequest) -> JSONResponse:
+    try:
+        normalized_preview = agent_controller.validate_project(payload.preview.model_dump())
+        result = create_project_zip(normalized_preview, GENERATED_DIR)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except OSError as exc:
+        raise HTTPException(status_code=500, detail=f"Could not create ZIP: {exc}") from exc
+
+    return JSONResponse(result)
+
+
+@app.get("/downloads/{filename}")
+async def download_zip(filename: str) -> FileResponse:
+    download_path = GENERATED_DIR / filename
+    if download_path.name != filename:
+        raise HTTPException(status_code=404, detail="File not found.")
+    if download_path.suffix != ".zip":
+        raise HTTPException(status_code=404, detail="File not found.")
+    if not download_path.exists():
+        raise HTTPException(status_code=404, detail="File not found.")
+    if not ensure_within_directory(GENERATED_DIR, download_path):
+        raise HTTPException(status_code=404, detail="File not found.")
+
+    return FileResponse(
+        download_path,
+        media_type="application/zip",
+        filename=download_path.name,
+    )
+
+
+@app.exception_handler(HTTPException)
+async def http_exception_handler(_: Request, exc: HTTPException) -> JSONResponse:
+    if exc.status_code == 404:
+        return JSONResponse(status_code=404, content={"detail": exc.detail})
+    return JSONResponse(status_code=exc.status_code, content={"detail": exc.detail})
+
+
+@app.exception_handler(Exception)
+async def unhandled_exception_handler(_: Request, exc: Exception) -> JSONResponse:
+    return JSONResponse(status_code=500, content={"detail": f"Unexpected server error: {exc}"})
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(
+        "app.main:app",
+        host="0.0.0.0",
+        port=int(os.getenv("PORT", str(DEFAULT_PORT))),
+    )

app/services/__init__.py

@@ -0,0 +1 @@
+

app/services/__pycache__/ai_service.cpython-314.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:74a9427a7c4a74ab2a8f072f62122bc4c3a1a6833f369ca6ef173b2c61a9c835
+size 140855

app/services/agent_controller.py

@@ -0,0 +1,449 @@
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+from . import ai_service as ai
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(slots=True)
+class IdeaContext:
+    idea: str
+    requested_stack: dict[str, str]
+    generation_mode: str
+    final_requirements: str = ""
+    generation_context: str = ""
+    detected_user_choices: list[str] = field(default_factory=list)
+    declared_project_type: str = ""
+    selected_stack: dict[str, str] = field(default_factory=dict)
+    project_kind: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class AgentAnalysisResult:
+    understanding: str
+    assumptions: list[str]
+    suggested_stack: dict[str, str]
+    stack_reasons: list[str]
+    questions: list[dict[str, Any]]
+    detected_project_type: str
+    confidence: int
+
+    def to_api_dict(self) -> dict[str, Any]:
+        return {
+            "understanding": self.understanding,
+            "assumptions": self.assumptions,
+            "suggestedStack": self.suggested_stack,
+            "stackReasons": self.stack_reasons,
+            "questions": self.questions,
+            "detectedProjectType": self.detected_project_type,
+            "confidence": self.confidence,
+        }
+
+
+@dataclass(slots=True)
+class FinalizedRequirementsResult:
+    final_requirements: str
+    selected_stack: dict[str, str]
+    assumptions: list[str]
+    normalized_answers: dict[str, str] = field(default_factory=dict)
+    project_kind: dict[str, Any] = field(default_factory=dict)
+
+    def to_api_dict(self) -> dict[str, Any]:
+        return {
+            "finalRequirements": self.final_requirements,
+            "selectedStack": self.selected_stack,
+            "assumptions": self.assumptions,
+        }
+
+
+@dataclass(slots=True)
+class ProjectStructurePlan:
+    project_name: str
+    detected_user_choices: list[str]
+    selected_stack: dict[str, str]
+    chosen_stack: list[str]
+    assumptions: list[str]
+    summary: str
+    problem_statement: str
+    architecture: list[str]
+    modules: list[dict[str, Any]]
+    package_requirements: list[str]
+    install_commands: list[str]
+    run_commands: list[str]
+    required_inputs: list[dict[str, Any]]
+    env_variables: list[dict[str, Any]]
+    custom_manifest: list[dict[str, str]]
+    files: list[dict[str, str]]
+    file_tree: str
+    project_kind: dict[str, Any] = field(default_factory=dict)
+
+    def to_preview_dict(self) -> dict[str, Any]:
+        return {
+            "projectName": self.project_name,
+            "detectedUserChoices": self.detected_user_choices,
+            "selectedStack": self.selected_stack,
+            "chosenStack": self.chosen_stack,
+            "assumptions": self.assumptions,
+            "summary": self.summary,
+            "problemStatement": self.problem_statement,
+            "architecture": self.architecture,
+            "modules": self.modules,
+            "packageRequirements": self.package_requirements,
+            "installCommands": self.install_commands,
+            "runCommands": self.run_commands,
+            "requiredInputs": self.required_inputs,
+            "envVariables": self.env_variables,
+            "fileTree": self.file_tree,
+            "files": self.files,
+        }
+
+
+@dataclass(slots=True)
+class GeneratedProjectResult:
+    preview: dict[str, Any]
+    fallback_used: bool = False
+    fallback_reason: str = ""
+
+
+class AgentController:
+    def analyze_idea(self, idea: str) -> dict[str, Any]:
+        context = self._build_idea_context(idea)
+        questions = self.ask_questions(context)
+        result = AgentAnalysisResult(
+            understanding=ai.build_agent_understanding(
+                context.idea,
+                context.selected_stack,
+                context.project_kind,
+            ),
+            assumptions=ai.build_agent_analysis_assumptions(
+                context.selected_stack,
+                context.project_kind,
+                questions,
+            ),
+            suggested_stack=context.selected_stack,
+            stack_reasons=ai.build_stack_reasons(
+                context.selected_stack,
+                context.project_kind,
+            ),
+            questions=questions,
+            detected_project_type=context.project_kind["label"],
+            confidence=ai.compute_agent_confidence(
+                context.idea,
+                context.detected_user_choices,
+                questions,
+                context.project_kind,
+            ),
+        )
+        return result.to_api_dict()
+
+    def decide_stack(self, context: IdeaContext, model_stack: Any = None) -> dict[str, str]:
+        return ai.resolve_selected_stack(
+            context.idea,
+            context.requested_stack,
+            model_stack,
+            context.detected_user_choices,
+        )
+
+    def determine_missing_info(self, context: IdeaContext) -> list[dict[str, Any]]:
+        return ai.build_agent_questions(
+            context.idea,
+            context.selected_stack,
+            context.project_kind,
+        )
+
+    def ask_questions(self, context: IdeaContext) -> list[dict[str, Any]]:
+        return self.determine_missing_info(context)
+
+    def finalize_requirements(
+        self,
+        idea: str,
+        answers: Mapping[str, Any] | None,
+        selected_stack: Mapping[str, Any] | None,
+    ) -> dict[str, Any]:
+        normalized_answers = ai.normalize_agent_answers(answers)
+        resolved_stack = ai.apply_agent_answers_to_stack(
+            idea,
+            ai.normalize_stack_selection(selected_stack),
+            normalized_answers,
+        )
+        project_kind = ai.determine_project_kind(
+            resolved_stack,
+            normalized_answers.get("project_scope"),
+        )
+        result = FinalizedRequirementsResult(
+            final_requirements=ai.build_final_requirements_summary(
+                idea,
+                normalized_answers,
+                resolved_stack,
+                project_kind,
+            ),
+            selected_stack=resolved_stack,
+            assumptions=ai.build_agent_finalize_assumptions(
+                normalized_answers,
+                resolved_stack,
+                project_kind,
+            ),
+            normalized_answers=normalized_answers,
+            project_kind=project_kind,
+        )
+        return result.to_api_dict()
+
+    def plan_project_structure(
+        self,
+        context: IdeaContext,
+        raw_plan: Mapping[str, Any] | None = None,
+    ) -> ProjectStructurePlan:
+        raw = dict(raw_plan or {})
+        detected_choices = ai.dedupe_list(
+            ai.normalize_string_list(raw.get("detectedUserChoices"))
+            or context.detected_user_choices
+            or ai.detect_user_choices(context.idea)
+        )
+        selected_stack = ai.resolve_selected_stack(
+            context.idea,
+            context.requested_stack,
+            raw.get("selectedStack") or context.selected_stack,
+            detected_choices,
+        )
+        project_kind = ai.determine_project_kind(
+            selected_stack,
+            raw.get("projectType") or context.declared_project_type,
+        )
+        project_name = ai.clean_project_name(raw.get("projectName"), context.idea)
+
+        modules = ai.merge_modules(
+            ai.normalize_modules(raw.get("modules")),
+            ai.build_default_modules(selected_stack, project_kind),
+        )
+        required_inputs = ai.merge_required_inputs(
+            ai.normalize_required_inputs(raw.get("requiredInputs")),
+            ai.build_required_inputs(
+                context.generation_context or context.idea,
+                selected_stack,
+                project_kind,
+                modules,
+            ),
+        )
+        env_variables = ai.merge_env_variables(
+            ai.normalize_env_variables(raw.get("envVariables")),
+            ai.required_inputs_to_env_variables(required_inputs),
+        )
+        package_requirements = ai.dedupe_list(
+            ai.normalize_string_list(raw.get("packageRequirements"))
+            + ai.build_package_requirements(selected_stack, project_kind)
+        )
+        install_commands = ai.dedupe_list(
+            ai.normalize_string_list(raw.get("installCommands"))
+            + ai.build_install_commands(selected_stack, project_kind)
+        )
+        run_commands = ai.dedupe_list(
+            ai.normalize_string_list(raw.get("runCommands"))
+            + ai.build_run_commands(selected_stack, project_kind)
+        )
+        custom_manifest = ai.normalize_custom_manifest(
+            raw.get("customFiles"),
+            selected_stack,
+            project_kind,
+        )
+        files = ai.finalize_preview_files(
+            project_name=project_name,
+            selected_stack=selected_stack,
+            project_kind=project_kind,
+            custom_manifest=custom_manifest,
+            raw_files=raw.get("files"),
+        )
+        assumptions = ai.dedupe_list(
+            ai.normalize_string_list(raw.get("assumptions"))
+            + ai.build_assumptions(
+                selected_stack,
+                project_kind,
+                context.requested_stack,
+                context.generation_mode,
+                bool(custom_manifest),
+            )
+        )
+        architecture = ai.dedupe_list(
+            ai.normalize_string_list(raw.get("architecture"))
+            + ai.build_architecture(selected_stack, project_kind)
+        )
+        file_tree = ai.build_preview_file_tree(
+            files,
+            include_env_example=bool(env_variables),
+        )
+
+        return ProjectStructurePlan(
+            project_name=project_name,
+            detected_user_choices=detected_choices,
+            selected_stack=selected_stack,
+            chosen_stack=ai.build_chosen_stack(selected_stack),
+            assumptions=assumptions,
+            summary=str(raw.get("summary") or "").strip()
+            or ai.build_summary(
+                project_name,
+                project_kind,
+                selected_stack,
+                context.generation_mode,
+            ),
+            problem_statement=str(raw.get("problemStatement") or "").strip()
+            or context.idea.strip()
+            or f"Build a starter project for {project_name}.",
+            architecture=architecture,
+            modules=modules,
+            package_requirements=package_requirements,
+            install_commands=install_commands,
+            run_commands=run_commands,
+            required_inputs=required_inputs,
+            env_variables=env_variables,
+            custom_manifest=custom_manifest,
+            files=files,
+            file_tree=file_tree,
+            project_kind=project_kind,
+        )
+
+    async def generate_files(
+        self,
+        idea: str,
+        selected_stack: dict[str, str] | None = None,
+        generation_mode: str = "fast",
+        final_requirements: str = "",
+    ) -> dict[str, Any]:
+        context = self._build_idea_context(
+            idea,
+            selected_stack=selected_stack,
+            generation_mode=generation_mode,
+            final_requirements=final_requirements,
+        )
+        preview_started_at = time.perf_counter()
+        deadline = time.monotonic() + ai.preview_budget_seconds(context.generation_mode)
+        planner_started_at: float | None = None
+        planner_duration = 0.0
+
+        try:
+            planner_started_at = time.perf_counter()
+            raw_plan = await ai.generate_project_plan(
+                context.generation_context,
+                context.requested_stack,
+                context.generation_mode,
+                deadline,
+            )
+            planner_duration = time.perf_counter() - planner_started_at
+            structure_plan = self.plan_project_structure(context, raw_plan)
+            preview = structure_plan.to_preview_dict()
+
+            if context.generation_mode == "deep" and structure_plan.custom_manifest:
+                remaining = ai.remaining_time(deadline)
+                if remaining >= ai.MIN_CUSTOM_PASS_SECONDS:
+                    try:
+                        generated_custom_files = await ai.generate_deep_custom_files(
+                            context.generation_context,
+                            structure_plan.project_name,
+                            structure_plan.selected_stack,
+                            structure_plan.custom_manifest,
+                            remaining,
+                        )
+                        preview = ai.apply_custom_file_overrides(preview, generated_custom_files)
+                        preview["assumptions"] = ai.dedupe_list(
+                            preview["assumptions"]
+                            + ["Deep Mode enriched custom business logic with a second scoped AI pass."]
+                        )
+                    except Exception as exc:
+                        preview["assumptions"] = ai.dedupe_list(
+                            preview["assumptions"]
+                            + [f"Deep Mode custom enrichment was skipped, so template custom files were kept: {exc}"]
+                        )
+                else:
+                    preview["assumptions"] = ai.dedupe_list(
+                        preview["assumptions"]
+                        + ["Deep Mode used the fast template custom files because the 70-second preview budget was nearly exhausted."]
+                    )
+
+            preview = self.validate_project(preview)
+            total_duration = time.perf_counter() - preview_started_at
+            logger.info(
+                "project_preview_complete mode=%s planner_duration=%.2fs total_duration=%.2fs fallback_used=%s",
+                context.generation_mode,
+                planner_duration,
+                total_duration,
+                False,
+            )
+            return GeneratedProjectResult(preview=preview).preview
+        except Exception as exc:
+            if planner_started_at is not None and planner_duration == 0.0:
+                planner_duration = time.perf_counter() - planner_started_at
+            preview = self._build_fallback_preview(context, str(exc))
+            preview = self.validate_project(preview)
+            total_duration = time.perf_counter() - preview_started_at
+            logger.warning(
+                "project_preview_fallback mode=%s planner_duration=%.2fs total_duration=%.2fs fallback_used=%s reason=%s",
+                context.generation_mode,
+                planner_duration,
+                total_duration,
+                True,
+                str(exc),
+            )
+            return GeneratedProjectResult(
+                preview=preview,
+                fallback_used=True,
+                fallback_reason=str(exc),
+            ).preview
+
+    def validate_project(self, preview: dict[str, Any]) -> dict[str, Any]:
+        return ai.prepare_preview_for_output(dict(preview))
+
+    def _build_idea_context(
+        self,
+        idea: str,
+        *,
+        selected_stack: Mapping[str, Any] | None = None,
+        generation_mode: str = "fast",
+        final_requirements: str = "",
+    ) -> IdeaContext:
+        requested_stack = ai.normalize_stack_selection(selected_stack)
+        normalized_mode = ai.normalize_generation_mode(generation_mode)
+        generation_context = ai.build_generation_context(
+            idea,
+            final_requirements,
+            normalized_mode,
+        )
+        detected_user_choices = ai.detect_user_choices(idea)
+        declared_project_type = ai.infer_declared_project_type(idea)
+        context = IdeaContext(
+            idea=idea,
+            requested_stack=requested_stack,
+            generation_mode=normalized_mode,
+            final_requirements=final_requirements,
+            generation_context=generation_context,
+            detected_user_choices=detected_user_choices,
+            declared_project_type=declared_project_type,
+        )
+        context.selected_stack = self.decide_stack(context)
+        context.project_kind = ai.determine_project_kind(
+            context.selected_stack,
+            declared_project_type,
+        )
+        return context
+
+    def _build_fallback_preview(self, context: IdeaContext, reason: str) -> dict[str, Any]:
+        structure_plan = self.plan_project_structure(context, {})
+        preview = structure_plan.to_preview_dict()
+        fallback_note = (
+            "Deep Mode AI enrichment was unavailable, so the 100% runnable starter project uses the safe template-generated fallback."
+            if context.generation_mode == "deep"
+            else "Fast Mode AI planning was unavailable, so the 100% runnable starter project uses the safe template-generated fallback."
+        )
+        preview["assumptions"] = ai.dedupe_list(
+            [
+                fallback_note,
+                f"Template fallback preview was generated because the AI planner could not complete in time or returned invalid output: {reason}",
+                *preview.get("assumptions", []),
+            ]
+        )
+        return preview
+
+
+agent_controller = AgentController()

app/services/file_service.py

@@ -0,0 +1,1932 @@
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path, PurePosixPath
+from typing import Any, Mapping, Sequence
+
+
+MAX_GENERATED_FILES = 60
+MAX_FILE_SIZE_BYTES = 250 * 1024
+
+SYSTEM_FILENAMES = {
+    "README.md",
+    "PROJECT_EXPLANATION.md",
+    "SETUP_INSTRUCTIONS.md",
+    "FILE_STRUCTURE.md",
+    "PACKAGE_REQUIREMENTS.md",
+    "REQUIRED_INPUTS.md",
+    ".env.example",
+}
+
+
+def slugify(value: str, fallback: str = "project-agent-output") -> str:
+    slug = re.sub(r"[^a-zA-Z0-9]+", "-", value.lower()).strip("-")
+    return slug or fallback
+
+
+def sanitize_relative_path(raw_path: str) -> Path:
+    if not isinstance(raw_path, str):
+        raise ValueError("Generated file paths must be strings.")
+
+    normalized = raw_path.replace("\\", "/").strip()
+    if not normalized:
+        raise ValueError("Generated file paths cannot be empty.")
+    if normalized.startswith(("/", "~")):
+        raise ValueError(f"Absolute paths are not allowed: {raw_path}")
+    if re.match(r"^[a-zA-Z]:", normalized):
+        raise ValueError(f"Drive-qualified paths are not allowed: {raw_path}")
+
+    posix_path = PurePosixPath(normalized)
+    safe_parts: list[str] = []
+    for part in posix_path.parts:
+        if part in {"", "."}:
+            continue
+        if part == "..":
+            raise ValueError(f"Path traversal is not allowed: {raw_path}")
+        safe_parts.append(part)
+
+    if not safe_parts:
+        raise ValueError(f"Generated file path is invalid: {raw_path}")
+
+    return Path(*safe_parts)
+
+
+def ensure_within_directory(base_dir: Path, candidate: Path) -> bool:
+    resolved_base = base_dir.resolve()
+    resolved_candidate = candidate.resolve()
+    return resolved_candidate.is_relative_to(resolved_base)
+
+
+def validate_generated_files(files: list[dict[str, str]]) -> list[dict[str, str]]:
+    if len(files) > MAX_GENERATED_FILES:
+        raise ValueError(
+            f"Generated output exceeds the limit of {MAX_GENERATED_FILES} files."
+        )
+
+    validated: list[dict[str, str]] = []
+    seen_paths: set[str] = set()
+    for file_entry in files:
+        raw_path = str(file_entry.get("path", ""))
+        relative_path = sanitize_relative_path(raw_path)
+        normalized_path = relative_path.as_posix()
+        if normalized_path in seen_paths:
+            continue
+
+        content = str(file_entry.get("content", ""))
+        content_size = len(content.encode("utf-8"))
+        if content_size > MAX_FILE_SIZE_BYTES:
+            raise ValueError(
+                f"Generated file '{normalized_path}' exceeds the size limit of 250 KB."
+            )
+
+        seen_paths.add(normalized_path)
+        validated.append({"path": normalized_path, "content": content})
+
+    return validated
+
+
+def build_required_docs(
+    preview: dict[str, Any], bundle_info: dict[str, Any] | None = None
+) -> dict[str, str]:
+    bundle_info = bundle_info or {}
+    project_name = str(preview.get("projectName") or "Generated Project").strip()
+    detected_choices = _listify(preview.get("detectedUserChoices"))
+    chosen_stack = _listify(preview.get("chosenStack"))
+    assumptions = _listify(preview.get("assumptions"))
+    architecture = _listify(preview.get("architecture"))
+    package_requirements = _listify(preview.get("packageRequirements"))
+    install_commands = _listify(preview.get("installCommands"))
+    run_commands = _listify(preview.get("runCommands"))
+    modules = preview.get("modules") or []
+    required_inputs = _required_input_list(preview.get("requiredInputs"))
+    env_variables = _env_list(preview.get("envVariables")) or _required_inputs_to_env_list(
+        required_inputs
+    )
+    file_tree = str(
+        bundle_info.get("actualFileTree") or preview.get("fileTree") or ""
+    ).strip()
+    summary = str(preview.get("summary") or "No summary was provided by the model.").strip()
+    problem_statement = str(
+        preview.get("problemStatement") or "No problem statement was provided by the model."
+    ).strip()
+    selected_stack = preview.get("selectedStack") or {}
+
+    readme = "\n".join(
+        [
+            f"# {project_name}",
+            "",
+            summary,
+            "",
+            "## What Was Generated",
+            "This ZIP contains a 100% runnable starter project from the latest preview, including dependency files, setup scripts, run scripts, starter source code, and required input guidance.",
+            "",
+            "## Problem Statement",
+            problem_statement,
+            "",
+            "## Selected Stack",
+            _selected_stack_text(selected_stack),
+            "",
+            "## Chosen Stack",
+            _bullet_text(chosen_stack, "The generated plan did not include stack details."),
+            "",
+            "## Detected User Choices",
+            _bullet_text(
+                detected_choices,
+                "The user did not explicitly specify language, tooling, or framework choices.",
+            ),
+            "",
+            "## Architecture Highlights",
+            _bullet_text(architecture, "Architecture details were not provided."),
+            "",
+            "## Core Modules",
+            _modules_text(modules),
+            "",
+            "## Setup",
+            "Fill `.env` from `.env.example`, then run the setup script before starting the project.",
+            "- Windows: `setup.bat`",
+            "- Mac/Linux: `setup.sh`",
+            "",
+            "## How To Run",
+            _bullet_text(run_commands, "No run commands were provided."),
+            "",
+            "## Required Inputs",
+            "Fill these values in `.env` before running the project.",
+            "",
+            _required_inputs_summary(required_inputs),
+            "",
+            "## Notes",
+            _bullet_text(assumptions, "No assumptions were recorded."),
+        ]
+    ).strip() + "\n"
+
+    explanation = "\n".join(
+        [
+            f"# {project_name} Explanation",
+            "",
+            "## Summary",
+            summary,
+            "",
+            "## Problem Statement",
+            problem_statement,
+            "",
+            "## Selected Stack",
+            _selected_stack_text(selected_stack),
+            "",
+            "## Architecture",
+            _bullet_text(architecture, "Architecture details were not provided."),
+            "",
+            "## Modules",
+            _modules_text(modules),
+            "",
+            "## Assumptions",
+            _bullet_text(assumptions, "No assumptions were recorded."),
+        ]
+    ).strip() + "\n"
+
+    setup_instructions = "\n".join(
+        [
+            "# Setup Instructions",
+            "",
+            "## Normal Setup",
+            "1. Review `README.md`, `PROJECT_EXPLANATION.md`, and `FILE_STRUCTURE.md` first.",
+            "2. Review `PACKAGE_REQUIREMENTS.md` and `REQUIRED_INPUTS.md` before installing dependencies.",
+            "3. Copy `.env.example` to `.env` and fill the required values.",
+            "",
+            "## Windows",
+            "1. Fill `.env` from `.env.example`.",
+            "2. Run `setup.bat`.",
+            "3. Run `run.bat`.",
+            "",
+            "## Mac/Linux",
+            "1. Fill `.env` from `.env.example`.",
+            "2. Run `chmod +x setup.sh run.sh`.",
+            "3. Run `./setup.sh`.",
+            "4. Run `./run.sh`.",
+            "",
+            "## Setup Scripts",
+            "- Windows: `setup.bat`",
+            "- Mac/Linux: `setup.sh`",
+            "",
+            "## Selected Stack",
+            _selected_stack_text(selected_stack),
+            "",
+            "## Install Commands",
+            _bullet_text(install_commands, "No install commands were provided."),
+            "",
+            "## Run Commands",
+            _bullet_text(run_commands, "No run commands were provided."),
+            "",
+            "## Environment Variables",
+            _env_variables_text(env_variables),
+            "",
+            "## Troubleshooting",
+            "- If dependencies fail to install, confirm Python, Node.js, or Maven is installed for the selected stack.",
+            "- If the app cannot connect to a service, double-check the values in `.env` against `REQUIRED_INPUTS.md`.",
+            "- If frontend and backend both start locally, verify `VITE_API_BASE_URL` or related API host settings match the backend URL.",
+            "",
+            "## Notes",
+            _bullet_text(assumptions, "No additional assumptions were provided."),
+        ]
+    ).strip() + "\n"
+
+    structure = "\n".join(
+        [
+            "# File Structure",
+            "",
+            "## Final Generated Tree",
+            "```text",
+            file_tree or "No file tree was available.",
+            "```",
+            "",
+            "## Included Modules",
+            _modules_text(modules),
+        ]
+    ).strip() + "\n"
+
+    package_docs = "\n".join(
+        [
+            "# Package Requirements",
+            "",
+            "## Libraries And Packages",
+            _bullet_text(package_requirements, "No package requirements were provided."),
+            "",
+            "## Install Commands",
+            _bullet_text(install_commands, "No install commands were provided."),
+            "",
+            "## Run Commands",
+            _bullet_text(run_commands, "No run commands were provided."),
+        ]
+    ).strip() + "\n"
+
+    required_inputs_doc = "\n".join(
+        [
+            "# Required Inputs",
+            "",
+            "Fill these values in `.env` before running the project.",
+            "",
+            "| Name | Required | Example | Where To Add | Purpose |",
+            "|---|---|---|---|---|",
+            _required_inputs_table(required_inputs),
+        ]
+    ).strip() + "\n"
+
+    docs = {
+        "README.md": readme,
+        "PROJECT_EXPLANATION.md": explanation,
+        "SETUP_INSTRUCTIONS.md": setup_instructions,
+        "FILE_STRUCTURE.md": structure,
+        "PACKAGE_REQUIREMENTS.md": package_docs,
+        "REQUIRED_INPUTS.md": required_inputs_doc,
+        ".env.example": build_env_example(required_inputs),
+    }
+
+    return docs
+
+
+def build_env_example(required_inputs: list[dict[str, Any]]) -> str:
+    if not required_inputs:
+        return (
+            "# No required inputs were detected for this starter.\n"
+            "# Copy this file to .env if you want to override defaults later.\n"
+        )
+
+    lines = [
+        "# Fill these values in .env before running the project.",
+        "# Copy this file to .env and replace the example values as needed.",
+        "",
+    ]
+    for variable in required_inputs:
+        name = str(variable.get("name") or "").strip()
+        example = str(variable.get("example") or "").strip()
+        if name:
+            lines.append(f"{name}={example}")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def build_file_tree_from_paths(paths: list[str]) -> str:
+    if not paths:
+        return ""
+
+    tree: dict[str, Any] = {}
+    for raw_path in paths:
+        parts = [part for part in raw_path.replace("\\", "/").split("/") if part]
+        current = tree
+        for part in parts:
+            current = current.setdefault(part, {})
+
+    lines: list[str] = []
+
+    def walk(node: dict[str, Any], depth: int = 0) -> None:
+        for name, child in sorted(node.items()):
+            lines.append(f"{'  ' * depth}{name}")
+            walk(child, depth + 1)
+
+    walk(tree)
+    return "\n".join(lines)
+
+
+def _listify(value: Any) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, str):
+        items = [line.strip(" -*\t") for line in value.splitlines()]
+        return [item for item in items if item]
+    if isinstance(value, dict):
+        return [
+            f"{key}: {str(item).strip()}"
+            for key, item in value.items()
+            if str(item).strip()
+        ]
+    if isinstance(value, (list, tuple, set)):
+        items = []
+        for item in value:
+            text = str(item).strip()
+            if text:
+                items.append(text)
+        return items
+    text = str(value).strip()
+    return [text] if text else []
+
+
+def _env_list(value: Any) -> list[dict[str, str]]:
+    env_vars: list[dict[str, str]] = []
+    if isinstance(value, dict):
+        value = [
+            {
+                "name": key,
+                "value": str(item).strip(),
+                "description": "",
+            }
+            for key, item in value.items()
+        ]
+    if not isinstance(value, (list, tuple)):
+        return env_vars
+
+    for item in value:
+        if not isinstance(item, dict):
+            continue
+        name = str(item.get("name") or "").strip()
+        if not name:
+            continue
+        env_vars.append(
+            {
+                "name": name,
+                "value": str(item.get("value") or "").strip(),
+                "description": str(item.get("description") or "").strip(),
+            }
+        )
+    return env_vars
+
+
+def _required_input_list(value: Any) -> list[dict[str, Any]]:
+    if isinstance(value, Mapping):
+        value = [value]
+    if not isinstance(value, (list, tuple)):
+        return []
+
+    required_inputs: list[dict[str, Any]] = []
+    for item in value:
+        if not isinstance(item, Mapping):
+            continue
+        name = str(item.get("name") or "").strip()
+        if not name:
+            continue
+        required_inputs.append(
+            {
+                "name": name,
+                "required": bool(item.get("required", True)),
+                "example": str(item.get("example") or item.get("value") or "").strip(),
+                "whereToAdd": str(item.get("whereToAdd") or ".env").strip() or ".env",
+                "purpose": str(item.get("purpose") or item.get("description") or "").strip(),
+            }
+        )
+    return required_inputs
+
+
+def _bullet_text(items: list[str], fallback: str) -> str:
+    if not items:
+        return f"- {fallback}"
+    return "\n".join(f"- {item}" for item in items)
+
+
+def _selected_stack_text(selected_stack: dict[str, Any]) -> str:
+    if not isinstance(selected_stack, dict) or not selected_stack:
+        return "- No explicit stack selection was recorded."
+
+    ordered_labels = [
+        ("language", "Language"),
+        ("frontend", "Frontend"),
+        ("backend", "Backend"),
+        ("database", "Database"),
+        ("aiTools", "AI / Tools"),
+        ("deployment", "Deployment"),
+    ]
+    lines = []
+    for key, label in ordered_labels:
+        value = str(selected_stack.get(key) or "Auto").strip()
+        lines.append(f"- {label}: {value}")
+    return "\n".join(lines)
+
+
+def _env_variables_text(env_variables: list[dict[str, str]]) -> str:
+    if not env_variables:
+        return "- No environment variables are required."
+
+    lines = []
+    for variable in env_variables:
+        description = variable.get("description", "").strip()
+        value = variable.get("value", "").strip()
+        suffix = f" ({description})" if description else ""
+        default_text = f" default `{value}`" if value else ""
+        lines.append(f"- `{variable['name']}`{suffix}{default_text}")
+    return "\n".join(lines)
+
+
+def _required_inputs_to_env_list(required_inputs: list[dict[str, Any]]) -> list[dict[str, str]]:
+    env_vars: list[dict[str, str]] = []
+    for item in required_inputs:
+        env_vars.append(
+            {
+                "name": str(item.get("name") or "").strip(),
+                "value": str(item.get("example") or "").strip(),
+                "description": str(item.get("purpose") or "").strip(),
+            }
+        )
+    return [item for item in env_vars if item["name"]]
+
+
+def _required_inputs_summary(required_inputs: list[dict[str, Any]]) -> str:
+    if not required_inputs:
+        return "- No required inputs were detected. `.env.example` is still included for future overrides."
+    return "\n".join(
+        f"- `{item['name']}` ({'required' if item.get('required', True) else 'optional'}): {item.get('purpose') or 'No description provided.'}"
+        for item in required_inputs
+    )
+
+
+def _required_inputs_table(required_inputs: list[dict[str, Any]]) -> str:
+    if not required_inputs:
+        return "| None | No | n/a | `.env` | No required external values were detected for this starter. |"
+
+    rows = []
+    for item in required_inputs:
+        rows.append(
+            "| {name} | {required} | {example} | {where_to_add} | {purpose} |".format(
+                name=item.get("name") or "",
+                required="Yes" if item.get("required", True) else "No",
+                example=(item.get("example") or "").replace("|", "\\|"),
+                where_to_add=(item.get("whereToAdd") or ".env").replace("|", "\\|"),
+                purpose=(item.get("purpose") or "").replace("|", "\\|"),
+            )
+        )
+    return "\n".join(rows)
+
+
+def _modules_text(modules: list[dict[str, Any]]) -> str:
+    if not modules:
+        return "- No modules were provided."
+
+    lines: list[str] = []
+    for module in modules:
+        name = str(module.get("name") or "Unnamed module").strip()
+        purpose = str(module.get("purpose") or "No purpose provided.").strip()
+        key_files = _listify(module.get("keyFiles"))
+        lines.append(f"- {name}: {purpose}")
+        if key_files:
+            lines.append(f"  Key files: {', '.join(key_files)}")
+    return "\n".join(lines)
+
+
+MAX_CUSTOM_TEMPLATE_FILES = 8
+MAX_CUSTOM_FILE_LINES = 300
+
+
+def finalize_preview_files(
+    *,
+    project_name: str,
+    selected_stack: Mapping[str, Any],
+    project_kind: Mapping[str, Any],
+    custom_manifest: Sequence[Mapping[str, Any]] | None = None,
+    raw_files: Any = None,
+) -> list[dict[str, str]]:
+    standard_files = _build_standard_files(project_name, selected_stack, project_kind)
+    custom_template_files = _build_custom_template_files(
+        custom_manifest or [],
+        project_name,
+        selected_stack,
+        project_kind,
+    )
+    existing_files = _normalize_preview_files(raw_files)
+
+    merged_files = _merge_file_entries(standard_files, custom_template_files)
+    merged_files = _merge_file_entries(merged_files, existing_files)
+    completed_files = _ensure_minimum_project_files(
+        merged_files,
+        project_name,
+        selected_stack,
+        project_kind,
+    )
+    repaired_files = _repair_runtime_contract(
+        completed_files,
+        project_name,
+        selected_stack,
+        project_kind,
+    )
+    return validate_generated_files(repaired_files)
+
+
+def build_preview_file_tree(
+    files: Sequence[Mapping[str, Any]],
+    *,
+    include_env_example: bool,
+) -> str:
+    doc_paths = [
+        "README.md",
+        "PROJECT_EXPLANATION.md",
+        "SETUP_INSTRUCTIONS.md",
+        "FILE_STRUCTURE.md",
+        "PACKAGE_REQUIREMENTS.md",
+        "REQUIRED_INPUTS.md",
+        ".env.example",
+    ]
+    file_paths = [str(file_entry.get("path") or "").strip() for file_entry in files]
+    return build_file_tree_from_paths([path for path in file_paths if path] + doc_paths)
+
+
+def _build_standard_files(
+    project_name: str,
+    selected_stack: Mapping[str, Any],
+    project_kind: Mapping[str, Any],
+) -> list[dict[str, str]]:
+    files: dict[str, str] = {}
+    if project_kind["isFullStack"]:
+        if project_kind["hasFrontend"]:
+            files.update(
+                _build_frontend_files(
+                    str(selected_stack.get("frontend") or "React"),
+                    project_name,
+                    "frontend",
+                )
+            )
+        if project_kind["hasBackend"]:
+            files.update(_build_backend_files(selected_stack, project_name, "backend"))
+        files.update(_build_root_scripts(selected_stack, project_kind))
+    elif project_kind["hasBackend"]:
+        files.update(_build_backend_files(selected_stack, project_name, ""))
+        files.update(_build_root_scripts(selected_stack, project_kind))
+    else:
+        files.update(
+            _build_frontend_files(
+                str(selected_stack.get("frontend") or "React"),
+                project_name,
+                "",
+            )
+        )
+        files.update(_build_root_scripts(selected_stack, project_kind))
+    return [{"path": path, "content": content} for path, content in files.items()]
+
+
+def _build_custom_template_files(
+    manifest: Sequence[Mapping[str, Any]],
+    project_name: str,
+    selected_stack: Mapping[str, Any],
+    project_kind: Mapping[str, Any],
+) -> list[dict[str, str]]:
+    files: list[dict[str, str]] = []
+    for item in list(manifest)[:MAX_CUSTOM_TEMPLATE_FILES]:
+        path = _clean_relative_path(item.get("path"))
+        purpose = str(item.get("purpose") or "").strip()
+        if not path or not purpose:
+            continue
+        content = _build_custom_template_content(
+            path,
+            purpose,
+            project_name,
+            selected_stack,
+            project_kind,
+        )
+        files.append({"path": path, "content": _trim_content_lines(content)})
+    return files
+
+
+def _build_custom_template_content(
+    path: str,
+    purpose: str,
+    project_name: str,
+    selected_stack: Mapping[str, Any],
+    project_kind: Mapping[str, Any],
+) -> str:
+    del selected_stack, project_kind
+    stem = Path(path).stem
+    pretty_name = stem.replace("_", " ").replace("-", " ").title()
+    extension = Path(path).suffix.lower()
+
+    if extension in {".jsx", ".tsx"}:
+        if "page" in stem.lower() or "/pages/" in path:
+            return f"""const cards = [
+  {{
+    title: "{pretty_name} Overview",
+    detail: "{purpose}"
+  }},
+  {{
+    title: "Starter Workflow",
+    detail: "Use this page to connect forms, API requests, and user-facing business actions."
+  }}
+];
+
+export default function {_safe_component_name(stem)}() {{
+  return (
+    <section className="card">
+      <h2>{pretty_name}</h2>
+      <p>{purpose}</p>
+      <ul>
+        {{cards.map((card) => (
+          <li key={{card.title}}>
+            <strong>{{card.title}}</strong>: {{card.detail}}
+          </li>
+        ))}}
+      </ul>
+    </section>
+  );
+}}
+"""
+        return f"""export default function {_safe_component_name(stem)}() {{
+  return (
+    <section className="card">
+      <h3>{pretty_name}</h3>
+      <p>{purpose}</p>
+    </section>
+  );
+}}
+"""
+
+    if extension == ".py":
+        if "router" in path or "/routers/" in path:
+            return f"""from fastapi import APIRouter
+
+router = APIRouter()
+
+
+@router.get("/")
+def read_{_safe_python_name(stem)}() -> dict[str, str]:
+    return {{
+        "message": "{purpose}",
+        "project": "{project_name}",
+    }}
+"""
+        if "schema" in path or "/schemas/" in path:
+            return f"""from pydantic import BaseModel
+
+
+class {_safe_component_name(stem)}(BaseModel):
+    name: str
+    description: str = "{purpose}"
+"""
+        if "model" in path or "/models/" in path:
+            return f"""from dataclasses import dataclass
+
+
+@dataclass
+class {_safe_component_name(stem)}:
+    name: str
+    status: str = "ready"
+"""
+        return f"""def {_safe_python_name(stem)}_summary() -> dict[str, str]:
+    return {{
+        "name": "{pretty_name}",
+        "purpose": "{purpose}",
+        "project": "{project_name}",
+    }}
+"""
+
+    if extension in {".js", ".mjs"}:
+        if "service" in path.lower():
+            return f"""export function get{_safe_component_name(stem)}Summary() {{
+  return {{
+    project: "{project_name}",
+    purpose: "{purpose}"
+  }};
+}}
+"""
+        if "controller" in path.lower():
+            return f"""export function {_safe_js_name(stem)}(_req, res) {{
+  res.json({{
+    project: "{project_name}",
+    purpose: "{purpose}"
+  }});
+}}
+"""
+        return f"""export const {_safe_js_name(stem)} = {{
+  project: "{project_name}",
+  purpose: "{purpose}"
+}};
+"""
+
+    if extension == ".java":
+        class_name = _safe_component_name(stem)
+        return f"""package com.example.demo.service;
+
+import org.springframework.stereotype.Service;
+
+@Service
+public class {class_name} {{
+    public String summary() {{
+        return "{purpose}";
+    }}
+}}
+"""
+
+    return f"# {pretty_name}\n\n{purpose}\n"
+
+
+def _ensure_minimum_project_files(
+    files: Sequence[Mapping[str, str]],
+    project_name: str,
+    selected_stack: Mapping[str, Any],
+    project_kind: Mapping[str, Any],
+) -> list[dict[str, str]]:
+    merged = {str(entry["path"]): str(entry["content"]) for entry in files}
+    for path, content in _build_root_scripts(selected_stack, project_kind).items():
+        merged.setdefault(path, content)
+
+    if project_kind["isFullStack"]:
+        for path, content in _build_frontend_files(
+            str(selected_stack.get("frontend") or "React"),
+            project_name,
+            "frontend",
+        ).items():
+            merged.setdefault(path, content)
+        for path, content in _build_backend_files(selected_stack, project_name, "backend").items():
+            merged.setdefault(path, content)
+    elif project_kind["hasBackend"]:
+        for path, content in _build_backend_files(selected_stack, project_name, "").items():
+            merged.setdefault(path, content)
+    else:
+        for path, content in _build_frontend_files(
+            str(selected_stack.get("frontend") or "React"),
+            project_name,
+            "",
+        ).items():
+            merged.setdefault(path, content)
+
+    filler_index = 1
+    minimum_files = int(project_kind.get("minimumFiles") or 0)
+    while len(merged) < minimum_files:
+        filler_path = f"notes/starter-note-{filler_index}.md"
+        merged.setdefault(
+            filler_path,
+            f"# Starter Note {filler_index}\n\nThis file preserves the complete minimum project structure while you continue iterating.\n",
+        )
+        filler_index += 1
+
+    return [{"path": path, "content": content} for path, content in merged.items()]
+
+
+def _repair_runtime_contract(
+    files: Sequence[Mapping[str, str]],
+    project_name: str,
+    selected_stack: Mapping[str, Any],
+    project_kind: Mapping[str, Any],
+) -> list[dict[str, str]]:
+    standard_map = {
+        item["path"]: item["content"]
+        for item in _build_standard_files(project_name, selected_stack, project_kind)
+    }
+    merged = {str(entry["path"]): str(entry["content"]) for entry in files}
+
+    for protected_path in _protected_runtime_paths(selected_stack, project_kind):
+        template_content = standard_map.get(protected_path)
+        if template_content is not None:
+            merged[protected_path] = template_content
+
+    for required_path in _required_runtime_paths(selected_stack, project_kind):
+        template_content = standard_map.get(required_path)
+        if template_content is None:
+            continue
+        if not str(merged.get(required_path, "")).strip():
+            merged[required_path] = template_content
+
+    for path, content in list(merged.items()):
+        if not str(content).strip():
+            replacement = standard_map.get(path) or _build_safe_fallback_content(
+                path,
+                project_name,
+            )
+            merged[path] = replacement
+
+    for path, content in list(merged.items()):
+        if not path.endswith(".py"):
+            continue
+        if _python_compiles(content):
+            continue
+        merged[path] = standard_map.get(path) or _build_safe_fallback_content(path, project_name)
+
+    for package_json_path in _package_json_paths(selected_stack, project_kind):
+        if package_json_path not in merged or not _valid_package_json(
+            merged[package_json_path],
+            _expected_package_scripts(package_json_path, selected_stack, project_kind),
+        ):
+            template = standard_map.get(package_json_path)
+            if template is not None:
+                merged[package_json_path] = template
+
+    for entry_path in _entry_validation_paths(selected_stack, project_kind):
+        template = standard_map.get(entry_path)
+        content = str(merged.get(entry_path, ""))
+        if template is None:
+            continue
+        if not content.strip() or not _valid_entry_file(entry_path, content):
+            merged[entry_path] = template
+
+    if project_kind["hasBackend"]:
+        for endpoint_path in _backend_endpoint_paths(selected_stack, project_kind):
+            template = standard_map.get(endpoint_path)
+            if template is None:
+                continue
+            content = str(merged.get(endpoint_path, ""))
+            if not content.strip() or not _valid_backend_endpoint_file(endpoint_path, content):
+                merged[endpoint_path] = template
+
+    if project_kind["hasFrontend"]:
+        for page_path in _frontend_page_paths(selected_stack, project_kind):
+            template = standard_map.get(page_path)
+            if template is None:
+                continue
+            if not str(merged.get(page_path, "")).strip():
+                merged[page_path] = template
+
+    return [{"path": path, "content": content} for path, content in merged.items()]
+
+
+def _build_backend_files(
+    selected_stack: Mapping[str, Any],
+    project_name: str,
+    prefix: str,
+) -> dict[str, str]:
+    backend = str(selected_stack.get("backend") or "FastAPI")
+    if backend in {"FastAPI", "Flask"}:
+        return _build_fastapi_backend_files(project_name, prefix)
+    if backend in {"Express", "NestJS"}:
+        return _build_express_backend_files(project_name, prefix)
+    if backend == "Spring Boot":
+        return _build_spring_backend_files(project_name, prefix)
+    return _build_fastapi_backend_files(project_name, prefix)
+
+
+def _build_frontend_files(frontend: str, project_name: str, prefix: str) -> dict[str, str]:
+    if frontend in {"React", "Next.js", "Vue"}:
+        return _build_react_frontend_files(project_name, prefix)
+    return _build_vanilla_frontend_files(project_name, prefix)
+
+
+def _build_fastapi_backend_files(project_name: str, prefix: str) -> dict[str, str]:
+    app_prefix = _prefixed(prefix, "app")
+    return {
+        _prefixed(prefix, "requirements.txt"): "\n".join(
+            [
+                "fastapi",
+                "uvicorn[standard]",
+                "pydantic",
+                "pydantic-settings",
+                "sqlalchemy",
+                "python-dotenv",
+                "aiosqlite",
+                "",
+            ]
+        ),
+        _prefixed(app_prefix, "__init__.py"): "",
+        _prefixed(app_prefix, "main.py"): f"""from fastapi import FastAPI
+
+from app.routers import health, items
+
+
+app = FastAPI(title="{project_name} API")
+app.include_router(health.router)
+app.include_router(items.router, prefix="/api/items", tags=["items"])
+
+
+@app.get("/")
+def read_root() -> dict[str, str]:
+    return {{"status": "ok", "message": "Project is running"}}
+""",
+        _prefixed(app_prefix, "routers/__init__.py"): "",
+        _prefixed(app_prefix, "routers/health.py"): """from fastapi import APIRouter
+
+from app.schemas.health import HealthResponse
+
+router = APIRouter(tags=["health"])
+
+
+@router.get("/health", response_model=HealthResponse)
+def healthcheck() -> HealthResponse:
+    return HealthResponse(status="ok", message="Project is running")
+""",
+        _prefixed(app_prefix, "routers/items.py"): """from fastapi import APIRouter
+
+from app.schemas.item import Item
+from app.services.item_service import list_items
+
+router = APIRouter()
+
+
+@router.get("/", response_model=list[Item])
+def get_items() -> list[Item]:
+    return list_items()
+""",
+        _prefixed(app_prefix, "services/__init__.py"): "",
+        _prefixed(app_prefix, "services/app_service.py"): f"""def get_app_summary() -> str:
+    return "{project_name} includes routes, services, schemas, and configuration for quick iteration."
+""",
+        _prefixed(app_prefix, "services/item_service.py"): """from app.schemas.item import Item
+
+
+def list_items() -> list[Item]:
+    return [
+        Item(id=1, name="Starter task", status="ready"),
+        Item(id=2, name="Next iteration", status="planned"),
+    ]
+""",
+        _prefixed(app_prefix, "models/__init__.py"): "",
+        _prefixed(app_prefix, "models/base.py"): """from sqlalchemy.orm import DeclarativeBase
+
+
+class Base(DeclarativeBase):
+    pass
+""",
+        _prefixed(app_prefix, "models/item.py"): """from sqlalchemy import String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.models.base import Base
+
+
+class ItemModel(Base):
+    __tablename__ = "items"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    name: Mapped[str] = mapped_column(String(120))
+    status: Mapped[str] = mapped_column(String(40), default="ready")
+""",
+        _prefixed(app_prefix, "schemas/__init__.py"): "",
+        _prefixed(app_prefix, "schemas/health.py"): """from pydantic import BaseModel
+
+
+class HealthResponse(BaseModel):
+    status: str
+    message: str
+""",
+        _prefixed(app_prefix, "schemas/item.py"): """from pydantic import BaseModel
+
+
+class Item(BaseModel):
+    id: int
+    name: str
+    status: str
+""",
+        _prefixed(app_prefix, "database.py"): """from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+
+from app.config import settings
+
+engine = create_engine(settings.database_url, future=True)
+SessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False)
+""",
+        _prefixed(app_prefix, "config.py"): """from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env")
+    app_env: str = "development"
+    database_url: str = "sqlite:///./app.db"
+
+
+settings = Settings()
+""",
+    }
+
+
+def _build_express_backend_files(project_name: str, prefix: str) -> dict[str, str]:
+    return {
+        _prefixed(prefix, "package.json"): json.dumps(
+            {
+                "name": project_name.lower().replace(" ", "-"),
+                "version": "0.1.0",
+                "private": True,
+                "type": "module",
+                "scripts": {"dev": "node --watch server.js", "start": "node server.js"},
+                "dependencies": {"cors": "^2.8.5", "dotenv": "^16.4.5", "express": "^4.19.2"},
+            },
+            indent=2,
+        )
+        + "\n",
+        _prefixed(prefix, "server.js"): f"""import cors from "cors";
+import dotenv from "dotenv";
+import express from "express";
+import indexRouter from "./src/routes/index.js";
+import itemsRouter from "./src/routes/items.js";
+
+dotenv.config();
+
+const app = express();
+app.use(cors());
+app.use(express.json());
+app.use("/", indexRouter);
+app.use("/api/items", itemsRouter);
+
+const port = process.env.PORT || 8000;
+app.listen(port, () => {{
+  console.log("{project_name} API listening on port", port);
+}});
+""",
+        _prefixed(prefix, "src/routes/index.js"): """import { Router } from "express";
+import { getStatus } from "../controllers/appController.js";
+
+const router = Router();
+router.get("/", getStatus);
+
+export default router;
+""",
+        _prefixed(prefix, "src/routes/items.js"): """import { Router } from "express";
+import { listItems } from "../controllers/itemController.js";
+
+const router = Router();
+router.get("/", listItems);
+
+export default router;
+""",
+        _prefixed(prefix, "src/controllers/appController.js"): """export function getStatus(_req, res) {
+  res.json({ status: "ok", message: "Project is running" });
+}
+""",
+        _prefixed(prefix, "src/controllers/itemController.js"): """import { getItems } from "../services/itemService.js";
+
+export function listItems(_req, res) {
+  res.json(getItems());
+}
+""",
+        _prefixed(prefix, "src/services/appService.js"): f"""export function getAppSummary() {{
+  return "{project_name} includes routes, controllers, services, and starter configuration.";
+}}
+""",
+        _prefixed(prefix, "src/services/itemService.js"): """export function getItems() {
+  return [
+    { id: 1, name: "Starter task", status: "ready" },
+    { id: 2, name: "Next iteration", status: "planned" }
+  ];
+}
+""",
+        _prefixed(prefix, "src/models/itemModel.js"): """export const itemShape = {
+  id: "number",
+  name: "string",
+  status: "string"
+};
+""",
+    }
+
+
+def _build_react_frontend_files(project_name: str, prefix: str) -> dict[str, str]:
+    return {
+        _prefixed(prefix, "package.json"): json.dumps(
+            {
+                "name": project_name.lower().replace(" ", "-") + "-frontend",
+                "private": True,
+                "version": "0.1.0",
+                "type": "module",
+                "scripts": {"dev": "vite", "build": "vite build", "preview": "vite preview"},
+                "dependencies": {"react": "^18.3.1", "react-dom": "^18.3.1"},
+                "devDependencies": {"vite": "^5.4.0", "@vitejs/plugin-react": "^4.3.1"},
+            },
+            indent=2,
+        )
+        + "\n",
+        _prefixed(prefix, "index.html"): """<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Project Starter</title>
+    <script type="module" src="/src/main.jsx"></script>
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>
+""",
+        _prefixed(prefix, "vite.config.js"): """import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: 5173
+  }
+});
+""",
+        _prefixed(prefix, "src/main.jsx"): """import React from "react";
+import ReactDOM from "react-dom/client";
+import App from "./App";
+import "./styles.css";
+
+ReactDOM.createRoot(document.getElementById("root")).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);
+""",
+        _prefixed(prefix, "src/App.jsx"): f"""import AppShell from "./components/AppShell";
+import HomePage from "./pages/HomePage";
+
+export default function App() {{
+  return (
+    <AppShell title="{project_name}">
+      <HomePage />
+    </AppShell>
+  );
+}}
+""",
+        _prefixed(prefix, "src/components/AppShell.jsx"): """export default function AppShell({ title, children }) {
+  return (
+    <div className="app-shell">
+      <header className="hero">
+        <p className="eyebrow">Generated by Project Agent</p>
+        <h1>{title}</h1>
+      </header>
+      <main>{children}</main>
+    </div>
+  );
+}
+""",
+        _prefixed(prefix, "src/pages/HomePage.jsx"): """import { getProjectHealth } from "../services/api";
+
+export default function HomePage() {
+  const projectHealth = getProjectHealth();
+
+  return (
+    <section className="card">
+      <h2>Starter Overview</h2>
+      <p>This 100% runnable starter project is ready for your first feature slice.</p>
+      <p>API health source: {projectHealth}</p>
+    </section>
+  );
+}
+""",
+        _prefixed(prefix, "src/services/api.js"): """export function getProjectHealth() {
+  return import.meta.env.VITE_API_BASE_URL || "http://localhost:8000";
+}
+""",
+        _prefixed(prefix, "src/styles.css"): """:root {
+  color-scheme: light;
+  font-family: "Segoe UI", Arial, sans-serif;
+  background: #f5f7fb;
+  color: #132238;
+}
+
+body {
+  margin: 0;
+}
+
+.app-shell {
+  max-width: 960px;
+  margin: 0 auto;
+  padding: 32px 20px 56px;
+}
+
+.hero {
+  margin-bottom: 24px;
+}
+
+.eyebrow {
+  font-size: 0.75rem;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  color: #57657d;
+}
+
+.card {
+  background: white;
+  border-radius: 16px;
+  padding: 24px;
+  box-shadow: 0 18px 40px rgba(19, 34, 56, 0.08);
+}
+""",
+    }
+
+
+def _build_vanilla_frontend_files(project_name: str, prefix: str) -> dict[str, str]:
+    return {
+        _prefixed(prefix, "package.json"): json.dumps(
+            {
+                "name": project_name.lower().replace(" ", "-") + "-frontend",
+                "private": True,
+                "version": "0.1.0",
+                "type": "module",
+                "scripts": {"dev": "vite", "build": "vite build", "preview": "vite preview"},
+                "devDependencies": {"vite": "^5.4.0"},
+            },
+            indent=2,
+        )
+        + "\n",
+        _prefixed(prefix, "index.html"): """<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Project Starter</title>
+    <script type="module" src="/src/main.js"></script>
+  </head>
+  <body>
+    <div id="app"></div>
+  </body>
+</html>
+""",
+        _prefixed(prefix, "vite.config.js"): """import { defineConfig } from "vite";
+
+export default defineConfig({
+  server: {
+    port: 5173
+  }
+});
+""",
+        _prefixed(prefix, "src/main.js"): f"""import {{ renderHomePage }} from "./views/home.js";
+import "./styles.css";
+
+document.querySelector("#app").innerHTML = renderHomePage("{project_name}");
+""",
+        _prefixed(prefix, "src/views/home.js"): """export function renderHomePage(title) {
+  return `
+    <main class="app-shell">
+      <section class="card">
+        <p class="eyebrow">Generated by Project Agent</p>
+        <h1>${title}</h1>
+        <p>This starter is ready for your first feature slice.</p>
+      </section>
+    </main>
+  `;
+}
+""",
+        _prefixed(prefix, "src/services/api.js"): """export function getApiBaseUrl() {
+  return import.meta.env.VITE_API_BASE_URL || "http://localhost:8000";
+}
+""",
+        _prefixed(prefix, "src/styles.css"): """body {
+  margin: 0;
+  font-family: "Segoe UI", Arial, sans-serif;
+  background: #f5f7fb;
+  color: #132238;
+}
+
+.app-shell {
+  max-width: 960px;
+  margin: 0 auto;
+  padding: 32px 20px 56px;
+}
+
+.card {
+  background: white;
+  border-radius: 16px;
+  padding: 24px;
+  box-shadow: 0 18px 40px rgba(19, 34, 56, 0.08);
+}
+
+.eyebrow {
+  font-size: 0.75rem;
+  text-transform: uppercase;
+  color: #57657d;
+}
+""",
+    }
+
+
+def _build_spring_backend_files(project_name: str, prefix: str) -> dict[str, str]:
+    java_base = _prefixed(prefix, "src/main/java/com/example/demo")
+    resources_base = _prefixed(prefix, "src/main/resources")
+    return {
+        _prefixed(prefix, "pom.xml"): """<project xmlns="http://maven.apache.org/POM/4.0.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>com.example</groupId>
+  <artifactId>demo</artifactId>
+  <version>0.0.1-SNAPSHOT</version>
+  <parent>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-parent</artifactId>
+    <version>3.3.2</version>
+  </parent>
+  <properties>
+    <java.version>17</java.version>
+  </properties>
+  <dependencies>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter-web</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter-data-jpa</artifactId>
+    </dependency>
+  </dependencies>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-maven-plugin</artifactId>
+      </plugin>
+    </plugins>
+  </build>
+</project>
+""",
+        _prefixed(java_base, "Application.java"): """package com.example.demo;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+@SpringBootApplication
+public class Application {
+    public static void main(String[] args) {
+        SpringApplication.run(Application.class, args);
+    }
+}
+""",
+        _prefixed(java_base, "controller/AppController.java"): """package com.example.demo.controller;
+
+import com.example.demo.service.AppService;
+import java.util.Map;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+public class AppController {
+    private final AppService appService;
+
+    public AppController(AppService appService) {
+        this.appService = appService;
+    }
+
+    @GetMapping("/")
+    public Map<String, String> status() {
+        return Map.of("status", "ok", "message", "Project is running");
+    }
+}
+""",
+        _prefixed(java_base, "service/AppService.java"): f"""package com.example.demo.service;
+
+import org.springframework.stereotype.Service;
+
+@Service
+public class AppService {{
+    public String status() {{
+        return "Project is running";
+    }}
+}}
+""",
+        _prefixed(java_base, "model/AppModel.java"): """package com.example.demo.model;
+
+public class AppModel {
+    private Long id;
+    private String name;
+
+    public Long getId() { return id; }
+    public void setId(Long id) { this.id = id; }
+    public String getName() { return name; }
+    public void setName(String name) { this.name = name; }
+}
+""",
+        _prefixed(java_base, "repository/AppRepository.java"): """package com.example.demo.repository;
+
+import com.example.demo.model.AppModel;
+import java.util.List;
+import org.springframework.stereotype.Repository;
+
+@Repository
+public class AppRepository {
+    public List<AppModel> findAll() {
+        return List.of();
+    }
+}
+""",
+        _prefixed(resources_base, "application.properties"): """spring.application.name=demo
+server.port=8080
+""",
+    }
+
+
+def _build_root_scripts(
+    selected_stack: Mapping[str, Any],
+    project_kind: Mapping[str, Any],
+) -> dict[str, str]:
+    if project_kind["isFullStack"]:
+        return _build_fullstack_scripts(selected_stack)
+    if project_kind["hasBackend"]:
+        backend = str(selected_stack.get("backend") or "FastAPI")
+        if backend in {"FastAPI", "Flask"}:
+            return _build_python_scripts(".")
+        if backend in {"Express", "NestJS"}:
+            return _build_node_scripts(".", "start")
+        if backend == "Spring Boot":
+            return _build_java_scripts(".")
+    return _build_node_scripts(".", "dev")
+
+
+def _build_fullstack_scripts(selected_stack: Mapping[str, Any]) -> dict[str, str]:
+    backend_setup = ""
+    backend_run_windows = "echo No backend runtime configured.\n"
+    backend_run_unix = 'echo "No backend runtime configured."\n'
+    backend = str(selected_stack.get("backend") or "")
+
+    if backend in {"FastAPI", "Flask"}:
+        backend_setup = (
+            "if exist backend\\requirements.txt (\n"
+            "  pushd backend\n"
+            "  python -m venv .venv\n"
+            "  call .venv\\Scripts\\python -m pip install --upgrade pip\n"
+            "  call .venv\\Scripts\\pip install -r requirements.txt\n"
+            "  popd\n"
+            ")\n"
+        )
+        backend_run_windows = (
+            'start "Backend" cmd /k "cd backend && .venv\\Scripts\\python -m uvicorn app.main:app --reload"\n'
+        )
+        backend_run_unix = '(cd backend && . .venv/bin/activate && uvicorn app.main:app --reload) &\n'
+    elif backend in {"Express", "NestJS"}:
+        backend_setup = (
+            "if exist backend\\package.json (\n"
+            "  pushd backend\n"
+            "  call npm install\n"
+            "  popd\n"
+            ")\n"
+        )
+        backend_run_windows = 'start "Backend" cmd /k "cd backend && npm start"\n'
+        backend_run_unix = '(cd backend && npm start) &\n'
+    elif backend == "Spring Boot":
+        backend_setup = (
+            "where mvn >nul 2>nul && (\n"
+            "  pushd backend\n"
+            "  call mvn install\n"
+            "  popd\n"
+            ") || echo Maven not found. Skipping backend install.\n"
+        )
+        backend_run_windows = 'start "Backend" cmd /k "cd backend && mvn spring-boot:run"\n'
+        backend_run_unix = '(cd backend && mvn spring-boot:run) &\n'
+
+    return {
+        "setup.bat": f"""@echo off
+setlocal
+{backend_setup}if exist frontend\\package.json (
+  pushd frontend
+  call npm install
+  popd
+)
+echo Setup complete.
+""",
+        "setup.sh": """#!/usr/bin/env bash
+set -e
+if [ -f backend/requirements.txt ]; then
+  (
+    cd backend
+    python3 -m venv .venv
+    . .venv/bin/activate
+    python -m pip install --upgrade pip
+    pip install -r requirements.txt
+  )
+fi
+if [ -f backend/package.json ]; then
+  (cd backend && npm install)
+fi
+if [ -f backend/pom.xml ]; then
+  if command -v mvn >/dev/null 2>&1; then
+    (cd backend && mvn install)
+  else
+    echo "Maven not found. Skipping backend install."
+  fi
+fi
+if [ -f frontend/package.json ]; then
+  (cd frontend && npm install)
+fi
+echo "Setup complete."
+""",
+        "run.bat": f"""@echo off
+setlocal
+{backend_run_windows}start "Frontend" cmd /k "cd frontend && npm run dev"
+""",
+        "run.sh": f"""#!/usr/bin/env bash
+set -e
+{backend_run_unix}(cd frontend && npm run dev) &
+wait
+""",
+    }
+
+
+def _build_python_scripts(target_dir: str) -> dict[str, str]:
+    del target_dir
+    return {
+        "setup.bat": """@echo off
+setlocal
+python -m venv .venv
+call .venv\\Scripts\\python -m pip install --upgrade pip
+call .venv\\Scripts\\pip install -r requirements.txt
+echo Setup complete.
+""",
+        "setup.sh": """#!/usr/bin/env bash
+set -e
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install --upgrade pip
+pip install -r requirements.txt
+echo "Setup complete."
+""",
+        "run.bat": """@echo off
+setlocal
+call .venv\\Scripts\\python -m uvicorn app.main:app --reload
+""",
+        "run.sh": """#!/usr/bin/env bash
+set -e
+. .venv/bin/activate
+uvicorn app.main:app --reload
+""",
+    }
+
+
+def _build_node_scripts(target_dir: str, script_name: str) -> dict[str, str]:
+    directory_prefix = "" if target_dir in {"", "."} else f"{target_dir}/"
+    windows_prefix = "" if target_dir in {"", "."} else f"{target_dir}\\"
+    run_script = "npm start" if script_name == "start" else "npm run dev"
+    return {
+        "setup.bat": f"""@echo off
+setlocal
+pushd {windows_prefix or "."}
+call npm install
+popd
+echo Setup complete.
+""",
+        "setup.sh": f"""#!/usr/bin/env bash
+set -e
+(cd {directory_prefix or "."} && npm install)
+echo "Setup complete."
+""",
+        "run.bat": f"""@echo off
+setlocal
+pushd {windows_prefix or "."}
+call {run_script}
+popd
+""",
+        "run.sh": f"""#!/usr/bin/env bash
+set -e
+(cd {directory_prefix or "."} && {run_script})
+""",
+    }
+
+
+def _protected_runtime_paths(
+    selected_stack: Mapping[str, Any],
+    project_kind: Mapping[str, Any],
+) -> set[str]:
+    paths: set[str] = {"setup.bat", "setup.sh", "run.bat", "run.sh"}
+    backend_prefix = "backend/" if project_kind["isFullStack"] else ""
+    frontend_prefix = "frontend/" if project_kind["isFullStack"] else ""
+
+    if project_kind["hasBackend"]:
+        backend = str(selected_stack.get("backend") or "FastAPI")
+        if backend in {"FastAPI", "Flask"}:
+            paths.update(
+                {
+                    f"{backend_prefix}requirements.txt",
+                    f"{backend_prefix}app/main.py",
+                    f"{backend_prefix}app/routers/health.py",
+                    f"{backend_prefix}app/schemas/health.py",
+                    f"{backend_prefix}app/config.py",
+                    f"{backend_prefix}app/database.py",
+                }
+            )
+        elif backend in {"Express", "NestJS"}:
+            paths.update(
+                {
+                    f"{backend_prefix}package.json",
+                    f"{backend_prefix}server.js",
+                    f"{backend_prefix}src/routes/index.js",
+                    f"{backend_prefix}src/controllers/appController.js",
+                }
+            )
+        elif backend == "Spring Boot":
+            paths.update(
+                {
+                    f"{backend_prefix}pom.xml",
+                    f"{backend_prefix}src/main/java/com/example/demo/Application.java",
+                    f"{backend_prefix}src/main/java/com/example/demo/controller/AppController.java",
+                    f"{backend_prefix}src/main/resources/application.properties",
+                }
+            )
+
+    if project_kind["hasFrontend"]:
+        frontend = str(selected_stack.get("frontend") or "React")
+        if frontend in {"React", "Next.js", "Vue"}:
+            paths.update(
+                {
+                    f"{frontend_prefix}package.json",
+                    f"{frontend_prefix}index.html",
+                    f"{frontend_prefix}vite.config.js",
+                    f"{frontend_prefix}src/main.jsx",
+                    f"{frontend_prefix}src/App.jsx",
+                    f"{frontend_prefix}src/pages/HomePage.jsx",
+                }
+            )
+        else:
+            paths.update(
+                {
+                    f"{frontend_prefix}package.json",
+                    f"{frontend_prefix}index.html",
+                    f"{frontend_prefix}vite.config.js",
+                    f"{frontend_prefix}src/main.js",
+                    f"{frontend_prefix}src/views/home.js",
+                }
+            )
+
+    return paths
+
+
+def _required_runtime_paths(
+    selected_stack: Mapping[str, Any],
+    project_kind: Mapping[str, Any],
+) -> set[str]:
+    return set(_protected_runtime_paths(selected_stack, project_kind))
+
+
+def _package_json_paths(
+    selected_stack: Mapping[str, Any],
+    project_kind: Mapping[str, Any],
+) -> list[str]:
+    paths: list[str] = []
+    backend_prefix = "backend/" if project_kind["isFullStack"] else ""
+    frontend_prefix = "frontend/" if project_kind["isFullStack"] else ""
+    if project_kind["hasBackend"] and str(selected_stack.get("backend") or "") in {"Express", "NestJS"}:
+        paths.append(f"{backend_prefix}package.json")
+    if project_kind["hasFrontend"]:
+        paths.append(f"{frontend_prefix}package.json")
+    return paths
+
+
+def _expected_package_scripts(
+    package_json_path: str,
+    selected_stack: Mapping[str, Any],
+    project_kind: Mapping[str, Any],
+) -> set[str]:
+    if package_json_path.endswith("backend/package.json") or (
+        not project_kind["isFullStack"] and project_kind["hasBackend"]
+    ):
+        backend = str(selected_stack.get("backend") or "")
+        if backend in {"Express", "NestJS"}:
+            return {"start"}
+    return {"dev"}
+
+
+def _entry_validation_paths(
+    selected_stack: Mapping[str, Any],
+    project_kind: Mapping[str, Any],
+) -> list[str]:
+    paths: list[str] = []
+    backend_prefix = "backend/" if project_kind["isFullStack"] else ""
+    frontend_prefix = "frontend/" if project_kind["isFullStack"] else ""
+    if project_kind["hasBackend"]:
+        backend = str(selected_stack.get("backend") or "FastAPI")
+        if backend in {"FastAPI", "Flask"}:
+            paths.append(f"{backend_prefix}app/main.py")
+        elif backend in {"Express", "NestJS"}:
+            paths.append(f"{backend_prefix}server.js")
+        elif backend == "Spring Boot":
+            paths.append(f"{backend_prefix}src/main/java/com/example/demo/Application.java")
+    if project_kind["hasFrontend"]:
+        frontend = str(selected_stack.get("frontend") or "React")
+        if frontend in {"React", "Next.js", "Vue"}:
+            paths.extend([f"{frontend_prefix}src/main.jsx", f"{frontend_prefix}src/App.jsx"])
+        else:
+            paths.extend([f"{frontend_prefix}src/main.js", f"{frontend_prefix}index.html"])
+    return paths
+
+
+def _backend_endpoint_paths(
+    selected_stack: Mapping[str, Any],
+    project_kind: Mapping[str, Any],
+) -> list[str]:
+    if not project_kind["hasBackend"]:
+        return []
+    backend_prefix = "backend/" if project_kind["isFullStack"] else ""
+    backend = str(selected_stack.get("backend") or "FastAPI")
+    if backend in {"FastAPI", "Flask"}:
+        return [f"{backend_prefix}app/main.py", f"{backend_prefix}app/routers/health.py"]
+    if backend in {"Express", "NestJS"}:
+        return [f"{backend_prefix}server.js", f"{backend_prefix}src/controllers/appController.js"]
+    if backend == "Spring Boot":
+        return [f"{backend_prefix}src/main/java/com/example/demo/controller/AppController.java"]
+    return []
+
+
+def _frontend_page_paths(
+    selected_stack: Mapping[str, Any],
+    project_kind: Mapping[str, Any],
+) -> list[str]:
+    if not project_kind["hasFrontend"]:
+        return []
+    frontend_prefix = "frontend/" if project_kind["isFullStack"] else ""
+    frontend = str(selected_stack.get("frontend") or "React")
+    if frontend in {"React", "Next.js", "Vue"}:
+        return [f"{frontend_prefix}src/App.jsx", f"{frontend_prefix}src/pages/HomePage.jsx"]
+    return [f"{frontend_prefix}index.html", f"{frontend_prefix}src/views/home.js"]
+
+
+def _valid_package_json(content: str, required_scripts: set[str]) -> bool:
+    try:
+        payload = json.loads(content)
+    except json.JSONDecodeError:
+        return False
+    if not isinstance(payload, Mapping):
+        return False
+    scripts = payload.get("scripts")
+    if not isinstance(scripts, Mapping):
+        return False
+    return required_scripts.issubset({str(key) for key in scripts.keys()})
+
+
+def _valid_entry_file(path: str, content: str) -> bool:
+    text = content.strip()
+    if not text:
+        return False
+    lower = path.lower()
+    if lower.endswith("app/main.py"):
+        return "FastAPI" in text and "app = FastAPI" in text and '@app.get("/")' in text
+    if lower.endswith("server.js"):
+        return "express" in text and 'app.use("/", indexRouter)' in text and "app.listen" in text
+    if lower.endswith("src/main.jsx"):
+        return "ReactDOM.createRoot" in text and 'from "./App"' in text
+    if lower.endswith("src/app.jsx"):
+        return "export default function App" in text
+    if lower.endswith("src/main.js"):
+        return "renderHomePage" in text and 'querySelector("#app")' in text
+    if lower.endswith("index.html"):
+        return '<div id="root"></div>' in text or '<div id="app"></div>' in text
+    if lower.endswith("application.java"):
+        return "@SpringBootApplication" in text and "SpringApplication.run" in text
+    return True
+
+
+def _valid_backend_endpoint_file(path: str, content: str) -> bool:
+    lower = path.lower()
+    if lower.endswith("app/main.py"):
+        return '"status": "ok"' in content and '"message": "Project is running"' in content
+    if lower.endswith("routers/health.py"):
+        return 'status="ok"' in content and 'message="Project is running"' in content
+    if lower.endswith("server.js"):
+        return 'app.use("/", indexRouter)' in content and "app.listen" in content
+    if lower.endswith("appcontroller.js"):
+        return 'status: "ok"' in content and 'message: "Project is running"' in content
+    if lower.endswith("appcontroller.java"):
+        return '"status", "ok"' in content and '"message", "Project is running"' in content
+    return True
+
+
+def _python_compiles(content: str) -> bool:
+    try:
+        compile(content, "<generated>", "exec")
+    except SyntaxError:
+        return False
+    return True
+
+
+def _build_safe_fallback_content(path: str, project_name: str) -> str:
+    lower = path.lower()
+    if lower.endswith(".py"):
+        return f"""def generated_safe_summary() -> dict[str, str]:
+    return {{"status": "ok", "message": "{project_name} safe fallback is loaded."}}
+"""
+    if lower.endswith(".jsx"):
+        return f"""export default function SafeFallback() {{
+  return <section className="card"><h2>{project_name}</h2><p>Safe fallback UI loaded.</p></section>;
+}}
+"""
+    if lower.endswith(".js"):
+        return f"""export const safeFallback = {{
+  status: "ok",
+  message: "{project_name} safe fallback loaded"
+}};
+"""
+    if lower.endswith(".java"):
+        return """package com.example.demo.service;
+
+public class SafeFallback {
+    public String summary() {
+        return "Safe fallback loaded";
+    }
+}
+"""
+    return f"# Safe fallback\n\n{project_name} restored this file to preserve a runnable starter.\n"
+
+
+def _build_java_scripts(target_dir: str) -> dict[str, str]:
+    directory_prefix = "" if target_dir in {"", "."} else f"{target_dir}/"
+    windows_prefix = "" if target_dir in {"", "."} else f"{target_dir}\\"
+    return {
+        "setup.bat": f"""@echo off
+setlocal
+where mvn >nul 2>nul && (
+  pushd {windows_prefix or "."}
+  call mvn install
+  popd
+) || (
+  echo Maven not found. Skipping install.
+)
+""",
+        "setup.sh": f"""#!/usr/bin/env bash
+set -e
+if command -v mvn >/dev/null 2>&1; then
+  (cd {directory_prefix or "."} && mvn install)
+else
+  echo "Maven not found. Skipping install."
+fi
+""",
+        "run.bat": f"""@echo off
+setlocal
+pushd {windows_prefix or "."}
+call mvn spring-boot:run
+popd
+""",
+        "run.sh": f"""#!/usr/bin/env bash
+set -e
+(cd {directory_prefix or "."} && mvn spring-boot:run)
+""",
+    }
+
+
+def _normalize_preview_files(value: Any) -> list[dict[str, str]]:
+    if not isinstance(value, Sequence) or isinstance(value, (str, bytes, bytearray)):
+        return []
+    files: list[dict[str, str]] = []
+    for item in value:
+        if not isinstance(item, Mapping):
+            continue
+        path = _clean_relative_path(item.get("path"))
+        if not path:
+            continue
+        files.append(
+            {
+                "path": path,
+                "content": _trim_content_lines(str(item.get("content") or ""), allow_long=True),
+            }
+        )
+    return files
+
+
+def _merge_file_entries(
+    primary: Sequence[Mapping[str, str]],
+    secondary: Sequence[Mapping[str, str]],
+) -> list[dict[str, str]]:
+    merged: dict[str, dict[str, str]] = {}
+    for file_entry in primary:
+        merged[str(file_entry["path"])] = {
+            "path": str(file_entry["path"]),
+            "content": str(file_entry["content"]),
+        }
+    for file_entry in secondary:
+        merged[str(file_entry["path"])] = {
+            "path": str(file_entry["path"]),
+            "content": str(file_entry["content"]),
+        }
+    return list(merged.values())
+
+
+def _clean_relative_path(value: Any) -> str:
+    path = str(value or "").replace("\\", "/").strip().strip("/")
+    if not path or path.startswith(".") or ".." in path.split("/"):
+        return ""
+    return path
+
+
+def _trim_content_lines(content: str, allow_long: bool = False) -> str:
+    if allow_long:
+        return content
+    lines = content.splitlines()
+    if len(lines) <= MAX_CUSTOM_FILE_LINES:
+        return content
+    return "\n".join(lines[:MAX_CUSTOM_FILE_LINES]).rstrip() + "\n"
+
+
+def _safe_component_name(value: str) -> str:
+    parts = re.findall(r"[A-Za-z0-9]+", value)
+    return "".join(part.capitalize() for part in parts) or "GeneratedComponent"
+
+
+def _safe_python_name(value: str) -> str:
+    cleaned = re.sub(r"[^a-zA-Z0-9_]+", "_", value).strip("_").lower()
+    return cleaned or "generated_item"
+
+
+def _safe_js_name(value: str) -> str:
+    parts = re.findall(r"[A-Za-z0-9]+", value)
+    if not parts:
+        return "generatedItem"
+    head = parts[0].lower()
+    tail = "".join(part.capitalize() for part in parts[1:])
+    return head + tail
+
+
+def _prefixed(prefix: str, path: str) -> str:
+    base = Path(prefix) if prefix else Path()
+    return (base / path).as_posix()

app/services/zip_service.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+from zipfile import ZIP_DEFLATED, ZipFile
+
+from .file_service import (
+    SYSTEM_FILENAMES,
+    build_file_tree_from_paths,
+    build_required_docs,
+    ensure_within_directory,
+    sanitize_relative_path,
+    slugify,
+)
+
+
+def create_project_zip(preview: dict[str, Any], generated_dir: Path) -> dict[str, str]:
+    generated_dir.mkdir(parents=True, exist_ok=True)
+
+    project_name = str(preview.get("projectName") or "Generated Project")
+    slug = slugify(project_name)
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+    unique_suffix = uuid4().hex[:8]
+    bundle_name = f"{slug}-{timestamp}-{unique_suffix}"
+
+    project_dir = generated_dir / bundle_name
+    project_dir.mkdir(parents=True, exist_ok=False)
+
+    _write_project_source_files(project_dir, preview)
+    bundle_info: dict[str, Any] = {}
+
+    actual_paths = [
+        path.relative_to(project_dir).as_posix()
+        for path in sorted(project_dir.rglob("*"))
+        if path.is_file()
+    ]
+    bundle_info["actualFileTree"] = build_file_tree_from_paths(actual_paths)
+
+    required_docs = build_required_docs(preview, bundle_info)
+    full_paths = sorted(set(actual_paths + list(required_docs.keys())))
+    bundle_info["actualFileTree"] = build_file_tree_from_paths(full_paths)
+    required_docs = build_required_docs(preview, bundle_info)
+    for doc_name, content in required_docs.items():
+        target_path = project_dir / doc_name
+        _write_text_file(project_dir, target_path, content)
+
+    zip_path = generated_dir / f"{bundle_name}.zip"
+    with ZipFile(zip_path, "w", compression=ZIP_DEFLATED) as zip_file:
+        for file_path in sorted(project_dir.rglob("*")):
+            if file_path.is_file():
+                arcname = Path(bundle_name) / file_path.relative_to(project_dir)
+                zip_file.write(file_path, arcname=arcname)
+
+    return {
+        "filename": zip_path.name,
+        "downloadUrl": f"/downloads/{zip_path.name}",
+    }
+
+
+def _write_project_source_files(project_dir: Path, preview: dict[str, Any]) -> None:
+    written_paths: set[Path] = set()
+    for file_entry in preview.get("files", []):
+        relative_path = sanitize_relative_path(str(file_entry.get("path", "")))
+        if relative_path in written_paths or (
+            relative_path.name in SYSTEM_FILENAMES and relative_path.parent == Path(".")
+        ):
+            continue
+
+        content = str(file_entry.get("content", ""))
+        target_path = project_dir / relative_path
+        _write_text_file(project_dir, target_path, content)
+        written_paths.add(relative_path)
+
+
+def _write_text_file(project_dir: Path, target_path: Path, content: str) -> None:
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+    if not ensure_within_directory(project_dir, target_path):
+        raise ValueError(f"Refusing to write outside the generated project folder: {target_path}")
+    target_path.write_text(content, encoding="utf-8")

app/static/app.js

@@ -0,0 +1,895 @@
+const STACK_OPTIONS = {
+  language: ["Auto", "Python", "JavaScript", "TypeScript", "Java"],
+  frontend: ["Auto", "None", "HTML/CSS/JavaScript", "React", "Next.js", "Vue"],
+  backend: ["Auto", "None", "FastAPI", "Flask", "Express", "NestJS", "Spring Boot"],
+  database: ["Auto", "None", "SQLite", "PostgreSQL", "MySQL", "MongoDB"],
+  aiTools: ["Auto", "None", "Ollama", "OpenAI API", "LangChain"],
+  deployment: ["Auto", "None", "Render", "Railway", "Vercel", "Docker"],
+};
+
+const ideaInput = document.getElementById("ideaInput");
+const suggestButton = document.getElementById("suggestButton");
+const continueButton = document.getElementById("continueButton");
+const skipQuestionsButton = document.getElementById("skipQuestionsButton");
+const generateProjectButton = document.getElementById("generateProjectButton");
+const regenerateButton = document.getElementById("regenerateButton");
+const confirmButton = document.getElementById("confirmButton");
+const clearButton = document.getElementById("clearButton");
+const statusMessage = document.getElementById("statusMessage");
+const generationModeSelect = document.getElementById("generationModeSelect");
+
+const agentSection = document.getElementById("agentSection");
+const advancedStackSection = document.getElementById("advancedStackSection");
+const previewSection = document.getElementById("previewSection");
+const downloadSection = document.getElementById("downloadSection");
+
+const agentUnderstandingText = document.getElementById("agentUnderstandingText");
+const agentAssumptionsList = document.getElementById("agentAssumptionsList");
+const agentSuggestedStackList = document.getElementById("agentSuggestedStackList");
+const questionCards = document.getElementById("questionCards");
+const finalizeCard = document.getElementById("finalizeCard");
+const finalizeSummaryText = document.getElementById("finalizeSummaryText");
+const finalSelectedStackList = document.getElementById("finalSelectedStackList");
+const finalRequirementsText = document.getElementById("finalRequirementsText");
+
+const projectNameHeading = document.getElementById("projectNameHeading");
+const detectedChoicesList = document.getElementById("detectedChoicesList");
+const stackChips = document.getElementById("stackChips");
+const selectedStackList = document.getElementById("selectedStackList");
+const chosenStackList = document.getElementById("chosenStackList");
+const assumptionsList = document.getElementById("assumptionsList");
+const summaryText = document.getElementById("summaryText");
+const problemStatementText = document.getElementById("problemStatementText");
+const architectureList = document.getElementById("architectureList");
+const packageRequirementsList = document.getElementById("packageRequirementsList");
+const installCommandsList = document.getElementById("installCommandsList");
+const runCommandsList = document.getElementById("runCommandsList");
+const envVariablesList = document.getElementById("envVariablesList");
+const requiredInputsBody = document.getElementById("requiredInputsBody");
+const modulesList = document.getElementById("modulesList");
+const fileTreeBlock = document.getElementById("fileTreeBlock");
+const filesList = document.getElementById("filesList");
+const downloadText = document.getElementById("downloadText");
+const downloadLink = document.getElementById("downloadLink");
+
+const stackSelects = {
+  language: document.getElementById("languageSelect"),
+  frontend: document.getElementById("frontendSelect"),
+  backend: document.getElementById("backendSelect"),
+  database: document.getElementById("databaseSelect"),
+  aiTools: document.getElementById("aiToolsSelect"),
+  deployment: document.getElementById("deploymentSelect"),
+};
+
+let baseIdea = "";
+let agentAnalysis = null;
+let agentAnswers = {};
+let finalRequirements = "";
+let currentPreview = null;
+let selectedStack = getDefaultStackState();
+let currentQuestionIndex = 0;
+let currentQuestionDraft = "";
+let showingSuggestion = false;
+
+initializeStackSelectors();
+refreshUiState();
+
+suggestButton.addEventListener("click", handleStartAgent);
+continueButton.addEventListener("click", handleContinueAgent);
+skipQuestionsButton.addEventListener("click", handleSkipQuestions);
+generateProjectButton.addEventListener("click", handleGenerateProject);
+regenerateButton.addEventListener("click", handleRegenerate);
+confirmButton.addEventListener("click", handleConfirmZip);
+clearButton.addEventListener("click", resetAll);
+
+Object.values(stackSelects).forEach((select) => {
+  select.addEventListener("change", handleStackChange);
+});
+
+function initializeStackSelectors() {
+  Object.entries(stackSelects).forEach(([key, select]) => {
+    STACK_OPTIONS[key].forEach((option) => {
+      const optionElement = document.createElement("option");
+      optionElement.value = option;
+      optionElement.textContent = option;
+      select.appendChild(optionElement);
+    });
+  });
+  applySelectedStackToControls(getDefaultStackState());
+}
+
+function getDefaultStackState() {
+  return {
+    language: "Auto",
+    frontend: "Auto",
+    backend: "Auto",
+    database: "Auto",
+    aiTools: "Auto",
+    deployment: "Auto",
+  };
+}
+
+function getQuestionList() {
+  return Array.isArray(agentAnalysis?.questions) ? agentAnalysis.questions : [];
+}
+
+function getCurrentQuestion() {
+  const questions = getQuestionList();
+  return questions[currentQuestionIndex] || null;
+}
+
+function getStoredAnswer(questionId) {
+  return typeof agentAnswers[questionId] === "string" ? agentAnswers[questionId] : "";
+}
+
+function setQuestionDraft(value) {
+  currentQuestionDraft = String(value || "");
+}
+
+function resetQuestionFlow() {
+  currentQuestionIndex = 0;
+  currentQuestionDraft = "";
+  showingSuggestion = false;
+}
+
+function collectSelectedStack() {
+  return {
+    language: stackSelects.language.value,
+    frontend: stackSelects.frontend.value,
+    backend: stackSelects.backend.value,
+    database: stackSelects.database.value,
+    aiTools: stackSelects.aiTools.value,
+    deployment: stackSelects.deployment.value,
+  };
+}
+
+function applySelectedStackToControls(stack) {
+  const safeStack = stack || getDefaultStackState();
+  Object.entries(stackSelects).forEach(([key, select]) => {
+    select.value = safeStack[key] || "Auto";
+  });
+  selectedStack = collectSelectedStack();
+}
+
+function handleStackChange() {
+  selectedStack = collectSelectedStack();
+  refreshUiState();
+}
+
+function setStatus(message, type) {
+  statusMessage.hidden = false;
+  statusMessage.className = `status-message ${type}`;
+  statusMessage.textContent = message;
+}
+
+function clearStatus() {
+  statusMessage.hidden = true;
+  statusMessage.className = "status-message";
+  statusMessage.textContent = "";
+}
+
+function setBusy(isBusy, message = "Working...") {
+  suggestButton.disabled = isBusy;
+  continueButton.disabled = isBusy || !agentAnalysis;
+  skipQuestionsButton.disabled = isBusy || !agentAnalysis;
+  generateProjectButton.disabled = isBusy || !finalRequirements;
+  regenerateButton.disabled = isBusy || !currentPreview;
+  confirmButton.disabled = isBusy || !currentPreview;
+  clearButton.disabled = isBusy && !baseIdea && !currentPreview && !agentAnalysis;
+  generationModeSelect.disabled = isBusy;
+  Object.values(stackSelects).forEach((select) => {
+    select.disabled = isBusy || !agentAnalysis;
+  });
+  if (isBusy) {
+    setStatus(message, "loading");
+  }
+}
+
+function refreshUiState() {
+  continueButton.disabled = !agentAnalysis;
+  skipQuestionsButton.disabled = !agentAnalysis;
+  generateProjectButton.disabled = !finalRequirements;
+  regenerateButton.disabled = !currentPreview;
+  confirmButton.disabled = !currentPreview;
+  clearButton.disabled = !baseIdea && !currentPreview && !agentAnalysis;
+  Object.values(stackSelects).forEach((select) => {
+    select.disabled = !agentAnalysis;
+  });
+
+  const questions = getQuestionList();
+  const hasQuestionFlow = !!agentAnalysis && questions.length > 0 && !finalRequirements;
+  if (hasQuestionFlow) {
+    continueButton.disabled = showingSuggestion;
+    continueButton.textContent = currentQuestionIndex >= questions.length - 1 ? "Finish Questions" : "Next";
+  } else if (!!agentAnalysis && !finalRequirements) {
+    continueButton.textContent = "Continue";
+  } else {
+    continueButton.textContent = "Next";
+  }
+}
+
+async function handleStartAgent() {
+  const idea = ideaInput.value.trim();
+  if (!idea) {
+    setStatus("Please enter a project idea before starting the agent.", "error");
+    return;
+  }
+
+  baseIdea = idea;
+  currentPreview = null;
+  finalRequirements = "";
+  agentAnswers = {};
+  resetQuestionFlow();
+  previewSection.hidden = true;
+  downloadSection.hidden = true;
+  finalizeCard.hidden = true;
+  setBusy(true, "Analyzing your idea...");
+
+  try {
+    const payload = await requestAgentAnalysis(idea);
+    agentAnalysis = payload;
+    selectedStack = payload.suggestedStack || getDefaultStackState();
+    applySelectedStackToControls(selectedStack);
+    renderAgentAnalysis(payload);
+    agentSection.hidden = false;
+    advancedStackSection.hidden = false;
+    setStatus("The agent reviewed your idea. Answer the questions one by one or skip and use the suggested defaults.", "success");
+  } catch (error) {
+    agentAnalysis = null;
+    agentSection.hidden = true;
+    advancedStackSection.hidden = true;
+    setStatus(error.message || "Could not start the agent.", "error");
+  } finally {
+    clearBusyState();
+  }
+}
+
+async function handleContinueAgent() {
+  if (!baseIdea || !agentAnalysis) {
+    setStatus("Start the agent before continuing.", "error");
+    return;
+  }
+
+  const question = getCurrentQuestion();
+  if (!question) {
+    await finalizeConversationOnly();
+    return;
+  }
+
+  const typedAnswer = currentQuestionDraft.trim();
+  if (!typedAnswer) {
+    showingSuggestion = true;
+    renderQuestionFlow();
+    setStatus("No answer was entered. Review the suggested default or edit your answer.", "info");
+    return;
+  }
+
+  storeQuestionAnswer(question.id, typedAnswer);
+  moveToNextQuestion();
+}
+
+async function handleSkipQuestions() {
+  if (!baseIdea || !agentAnalysis) {
+    setStatus("Start the agent before skipping questions.", "error");
+    return;
+  }
+
+  downloadSection.hidden = true;
+  setBusy(true, "Generating project with suggested defaults...");
+
+  try {
+    await finalizeAgentConversation({ fillDefaults: true });
+    await generatePreviewFromCurrentState(
+      "Preview ready. Review the generated project, regenerate if needed, then confirm to create the ZIP.",
+    );
+  } catch (error) {
+    currentPreview = null;
+    previewSection.hidden = true;
+    setStatus(error.message || "Could not generate the project from the suggested defaults.", "error");
+  } finally {
+    clearBusyState();
+  }
+}
+
+async function handleGenerateProject() {
+  if (!baseIdea || !finalRequirements) {
+    setStatus("Finalize the agent conversation before generating the project.", "error");
+    return;
+  }
+
+  downloadSection.hidden = true;
+  setBusy(true, "Generating project preview...");
+
+  try {
+    await generatePreviewFromCurrentState(
+      "Preview ready. Review the generated project, regenerate if needed, then confirm to create the ZIP.",
+    );
+  } catch (error) {
+    currentPreview = null;
+    previewSection.hidden = true;
+    setStatus(error.message || "Could not generate the project preview.", "error");
+  } finally {
+    clearBusyState();
+  }
+}
+
+async function handleRegenerate() {
+  if (!baseIdea || !currentPreview) {
+    setStatus("Generate a preview before regenerating with the selected stack.", "error");
+    return;
+  }
+
+  downloadSection.hidden = true;
+  setBusy(true, "Generating project preview...");
+
+  try {
+    await generatePreviewFromCurrentState(
+      "Preview regenerated with the latest requirements and selected stack.",
+    );
+  } catch (error) {
+    setStatus(error.message || "Could not regenerate the preview.", "error");
+  } finally {
+    clearBusyState();
+  }
+}
+
+async function handleConfirmZip() {
+  if (!currentPreview) {
+    setStatus("Generate a preview before creating a ZIP.", "error");
+    return;
+  }
+
+  setBusy(true, "Creating ZIP from the latest accepted preview...");
+
+  try {
+    const response = await fetch("/api/zip", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        preview: currentPreview,
+      }),
+    });
+
+    const payload = await response.json();
+    if (!response.ok) {
+      throw new Error(payload.detail || "Could not create the ZIP.");
+    }
+
+    downloadLink.href = payload.downloadUrl;
+    downloadLink.download = payload.filename;
+    downloadText.textContent = `Your generated project ZIP is ready: ${payload.filename}`;
+    downloadSection.hidden = false;
+    setStatus("ZIP created successfully. You can download it now.", "success");
+  } catch (error) {
+    setStatus(error.message || "Could not create the ZIP.", "error");
+  } finally {
+    clearBusyState();
+  }
+}
+
+async function requestAgentAnalysis(idea) {
+  const response = await fetch("/api/agent/analyze", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ idea }),
+  });
+
+  const payload = await response.json();
+  if (!response.ok) {
+    throw new Error(payload.detail || "Could not analyze the idea.");
+  }
+  return payload;
+}
+
+async function requestAgentFinalize(body) {
+  const response = await fetch("/api/agent/finalize", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+
+  const payload = await response.json();
+  if (!response.ok) {
+    throw new Error(payload.detail || "Could not finalize the requirements.");
+  }
+  return payload;
+}
+
+async function requestPreview(body) {
+  const response = await fetch("/api/suggest", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      generationMode: generationModeSelect.value || "fast",
+      ...body,
+    }),
+  });
+
+  const payload = await response.json();
+  if (!response.ok) {
+    throw new Error(payload.detail || "Could not generate a preview.");
+  }
+  return payload;
+}
+
+function renderAgentAnalysis(analysis) {
+  agentUnderstandingText.textContent = analysis.understanding || "No understanding available.";
+  renderList(agentAssumptionsList, analysis.assumptions, "No assumptions recorded.");
+  renderStackSummary(agentSuggestedStackList, analysis.suggestedStack || getDefaultStackState());
+  resetQuestionFlow();
+  renderQuestionFlow();
+}
+
+function renderQuestionFlow() {
+  questionCards.replaceChildren();
+
+  const questions = getQuestionList();
+  if (questions.length === 0) {
+    const empty = document.createElement("p");
+    empty.className = "text-block";
+    empty.textContent = "No follow-up questions are needed. Continue to finalize the recommended stack or skip straight to generation.";
+    questionCards.appendChild(empty);
+    refreshUiState();
+    return;
+  }
+
+  const question = getCurrentQuestion();
+  if (!question) {
+    const completed = document.createElement("p");
+    completed.className = "text-block";
+    completed.textContent = "All important questions are complete. Continue to finalize your requirements.";
+    questionCards.appendChild(completed);
+    refreshUiState();
+    return;
+  }
+
+  if (!currentQuestionDraft && getStoredAnswer(question.id) && !showingSuggestion) {
+    setQuestionDraft(getStoredAnswer(question.id));
+  }
+
+  const card = document.createElement("article");
+  card.className = "question-card active-question-card";
+
+  const position = document.createElement("p");
+  position.className = "question-position";
+  position.textContent = `Question ${currentQuestionIndex + 1} of ${questions.length}`;
+
+  const title = document.createElement("h4");
+  title.textContent = question.question || "Question";
+
+  const reason = document.createElement("p");
+  reason.className = "question-reason";
+  reason.textContent = "Type your preference first. If you leave it blank, the agent will suggest a default and explain why.";
+
+  const inputLabel = document.createElement("label");
+  inputLabel.className = "field-label";
+  inputLabel.setAttribute("for", "activeQuestionInput");
+  inputLabel.textContent = "Your answer";
+
+  const input = document.createElement("input");
+  input.type = "text";
+  input.id = "activeQuestionInput";
+  input.className = "question-input";
+  input.placeholder = buildQuestionPlaceholder(question);
+  input.value = currentQuestionDraft;
+  input.addEventListener("input", (event) => {
+    setQuestionDraft(event.target.value);
+  });
+
+  card.append(position, title, reason, inputLabel, input);
+
+  if (Array.isArray(question.options) && question.options.length) {
+    const optionsHint = document.createElement("p");
+    optionsHint.className = "question-hint";
+    optionsHint.textContent = `Common choices: ${question.options.join(", ")}`;
+    card.appendChild(optionsHint);
+  }
+
+  if (showingSuggestion) {
+    const suggestionBlock = document.createElement("div");
+    suggestionBlock.className = "suggestion-block";
+
+    const suggestionTitle = document.createElement("p");
+    suggestionTitle.className = "suggestion-title";
+    suggestionTitle.textContent = `Suggested: ${question.default || "No default available"}`;
+
+    const suggestionReason = document.createElement("p");
+    suggestionReason.className = "suggestion-reason";
+    suggestionReason.textContent = question.reason || "This default keeps the starter simple and runnable.";
+
+    const suggestionActions = document.createElement("div");
+    suggestionActions.className = "question-actions";
+
+    const acceptButton = document.createElement("button");
+    acceptButton.type = "button";
+    acceptButton.className = "secondary-button";
+    acceptButton.textContent = "Accept Suggestion";
+    acceptButton.addEventListener("click", () => {
+      storeQuestionAnswer(question.id, question.default || "");
+      moveToNextQuestion();
+    });
+
+    const editButton = document.createElement("button");
+    editButton.type = "button";
+    editButton.className = "ghost-button";
+    editButton.textContent = "Edit Answer";
+    editButton.addEventListener("click", () => {
+      showingSuggestion = false;
+      renderQuestionFlow();
+      const inputElement = document.getElementById("activeQuestionInput");
+      inputElement?.focus();
+    });
+
+    suggestionActions.append(acceptButton, editButton);
+    suggestionBlock.append(suggestionTitle, suggestionReason, suggestionActions);
+    card.appendChild(suggestionBlock);
+  }
+
+  questionCards.appendChild(card);
+  refreshUiState();
+}
+
+function buildQuestionPlaceholder(question) {
+  if (Array.isArray(question.options) && question.options.length) {
+    return `Example: ${question.options[0]}`;
+  }
+  return "Type your answer or leave blank for a suggestion";
+}
+
+function storeQuestionAnswer(questionId, value) {
+  agentAnswers[questionId] = String(value || "").trim();
+}
+
+function moveToNextQuestion() {
+  showingSuggestion = false;
+  currentQuestionIndex += 1;
+  currentQuestionDraft = "";
+
+  if (currentQuestionIndex >= getQuestionList().length) {
+    renderQuestionFlow();
+    void finalizeConversationOnly();
+    return;
+  }
+
+  renderQuestionFlow();
+  clearStatus();
+}
+
+async function finalizeConversationOnly() {
+  setBusy(true, "Finalizing requirements...");
+
+  try {
+    await finalizeAgentConversation({ fillDefaults: false });
+    setStatus("Requirements finalized. Generate the project when you are ready.", "success");
+  } catch (error) {
+    setStatus(error.message || "Could not finalize the requirements.", "error");
+  } finally {
+    clearBusyState();
+  }
+}
+
+function buildAnswersPayload(fillDefaults) {
+  const answers = { ...agentAnswers };
+  if (!fillDefaults) {
+    return answers;
+  }
+
+  getQuestionList().forEach((question) => {
+    if (!answers[question.id]) {
+      answers[question.id] = question.default || "";
+    }
+  });
+  return answers;
+}
+
+function buildFinalizationSummary(finalizedStack, assumptions) {
+  const scope = [
+    finalizedStack.frontend && finalizedStack.frontend !== "None" ? finalizedStack.frontend : null,
+    finalizedStack.backend && finalizedStack.backend !== "None" ? finalizedStack.backend : null,
+  ].filter(Boolean).join(" + ");
+  const firstAssumption = Array.isArray(assumptions) && assumptions.length ? assumptions[0] : "";
+  return scope
+    ? `The starter is now aligned around ${scope}. ${firstAssumption}`.trim()
+    : `The starter requirements are finalized. ${firstAssumption}`.trim();
+}
+
+function renderFinalization(finalized) {
+  finalizeCard.hidden = false;
+  finalRequirementsText.textContent = finalized.finalRequirements || "No finalized requirements available.";
+  finalizeSummaryText.textContent = buildFinalizationSummary(
+    finalized.selectedStack || selectedStack,
+    finalized.assumptions || [],
+  );
+  renderStackSummary(finalSelectedStackList, finalized.selectedStack || selectedStack);
+  renderStackSummary(agentSuggestedStackList, finalized.selectedStack || selectedStack);
+  const mergedAssumptions = dedupeList([
+    ...(Array.isArray(agentAnalysis?.assumptions) ? agentAnalysis.assumptions : []),
+    ...(Array.isArray(finalized.assumptions) ? finalized.assumptions : []),
+  ]);
+  renderList(agentAssumptionsList, mergedAssumptions, "No assumptions recorded.");
+  refreshUiState();
+}
+
+function clearBusyState() {
+  suggestButton.disabled = false;
+  generationModeSelect.disabled = false;
+  refreshUiState();
+}
+
+async function finalizeAgentConversation({ fillDefaults }) {
+  const payload = await requestAgentFinalize({
+    idea: baseIdea,
+    answers: buildAnswersPayload(fillDefaults),
+    suggestedStack: collectSelectedStack(),
+  });
+  finalRequirements = payload.finalRequirements || "";
+  selectedStack = payload.selectedStack || selectedStack;
+  applySelectedStackToControls(selectedStack);
+  renderFinalization(payload);
+  return payload;
+}
+
+async function generatePreviewFromCurrentState(successMessage) {
+  selectedStack = collectSelectedStack();
+  const payload = await requestPreview({
+    idea: baseIdea,
+    selectedStack,
+    finalRequirements,
+  });
+  currentPreview = payload;
+  selectedStack = payload.selectedStack || selectedStack;
+  renderPreview(payload);
+  applySelectedStackToControls(selectedStack);
+  setStatus(successMessage, "success");
+  return payload;
+}
+
+function resetAll() {
+  baseIdea = "";
+  agentAnalysis = null;
+  agentAnswers = {};
+  finalRequirements = "";
+  currentPreview = null;
+  selectedStack = getDefaultStackState();
+  resetQuestionFlow();
+
+  ideaInput.value = "";
+  clearStatus();
+  applySelectedStackToControls(getDefaultStackState());
+  agentSection.hidden = true;
+  advancedStackSection.hidden = true;
+  advancedStackSection.open = false;
+  previewSection.hidden = true;
+  downloadSection.hidden = true;
+  finalizeCard.hidden = true;
+  generateProjectButton.disabled = true;
+  generationModeSelect.value = "fast";
+  generationModeSelect.disabled = false;
+  downloadLink.removeAttribute("href");
+  downloadLink.removeAttribute("download");
+  downloadText.textContent = "Your generated project ZIP is ready.";
+
+  agentUnderstandingText.textContent = "";
+  clearCollection(agentAssumptionsList);
+  clearCollection(agentSuggestedStackList);
+  questionCards.replaceChildren();
+  finalizeSummaryText.textContent = "";
+  clearCollection(finalSelectedStackList);
+  finalRequirementsText.textContent = "";
+
+  clearCollection(detectedChoicesList);
+  stackChips.replaceChildren();
+  clearCollection(selectedStackList);
+  clearCollection(chosenStackList);
+  clearCollection(assumptionsList);
+  clearCollection(architectureList);
+  clearCollection(packageRequirementsList);
+  clearCollection(installCommandsList);
+  clearCollection(runCommandsList);
+  clearCollection(envVariablesList);
+  requiredInputsBody.replaceChildren();
+  modulesList.replaceChildren();
+  filesList.replaceChildren();
+  fileTreeBlock.textContent = "";
+  summaryText.textContent = "";
+  problemStatementText.textContent = "";
+  projectNameHeading.textContent = "Generated Project";
+  refreshUiState();
+}
+
+function renderPreview(preview) {
+  previewSection.hidden = false;
+  projectNameHeading.textContent = preview.projectName || "Generated Project";
+  summaryText.textContent = preview.summary || "No summary available.";
+  problemStatementText.textContent = preview.problemStatement || "No problem statement available.";
+  fileTreeBlock.textContent = preview.fileTree || "No file tree available.";
+
+  renderList(detectedChoicesList, preview.detectedUserChoices, "No explicit user choices detected.");
+  renderStackChips(preview.selectedStack || getDefaultStackState());
+  renderStackSummary(selectedStackList, preview.selectedStack || getDefaultStackState());
+  renderList(chosenStackList, preview.chosenStack, "No chosen stack details available.");
+  renderList(assumptionsList, preview.assumptions, "No assumptions recorded.");
+  renderList(architectureList, preview.architecture, "No architecture details available.");
+  renderList(packageRequirementsList, preview.packageRequirements, "No package requirements available.");
+  renderList(installCommandsList, preview.installCommands, "No install commands available.");
+  renderList(runCommandsList, preview.runCommands, "No run commands available.");
+  renderRequiredInputs(preview.requiredInputs || []);
+  renderEnvVariables(preview.envVariables || []);
+  renderModules(preview.modules || []);
+  renderFiles(preview.files || []);
+}
+
+function renderStackChips(stack) {
+  stackChips.replaceChildren();
+  const featuredChips = [
+    ["language", "Language"],
+    ["frontend", "Frontend"],
+    ["backend", "Backend"],
+    ["database", "Database"],
+  ];
+
+  featuredChips.forEach(([key, label]) => {
+    const chip = document.createElement("span");
+    chip.className = "stack-chip";
+    chip.innerHTML = `<strong>${escapeHtml(label)}</strong> ${escapeHtml(stack[key] || "Auto")}`;
+    stackChips.appendChild(chip);
+  });
+}
+
+function renderList(element, items, fallback) {
+  clearCollection(element);
+  const safeItems = Array.isArray(items) && items.length ? items : [fallback];
+
+  safeItems.forEach((item) => {
+    const listItem = document.createElement("li");
+    listItem.textContent = item;
+    element.appendChild(listItem);
+  });
+}
+
+function renderStackSummary(element, stack) {
+  clearCollection(element);
+  const labels = {
+    language: "Language",
+    frontend: "Frontend",
+    backend: "Backend",
+    database: "Database",
+    aiTools: "AI / Tools",
+    deployment: "Deployment",
+  };
+
+  Object.entries(labels).forEach(([key, label]) => {
+    const listItem = document.createElement("li");
+    listItem.textContent = `${label}: ${stack[key] || "Auto"}`;
+    element.appendChild(listItem);
+  });
+}
+
+function renderEnvVariables(envVariables) {
+  clearCollection(envVariablesList);
+  if (!Array.isArray(envVariables) || envVariables.length === 0) {
+    renderList(envVariablesList, [], "No environment variables required.");
+    return;
+  }
+
+  envVariables.forEach((variable) => {
+    const listItem = document.createElement("li");
+    const description = variable.description ? ` - ${variable.description}` : "";
+    const value = variable.value ? ` = ${variable.value}` : "";
+    listItem.textContent = `${variable.name}${value}${description}`;
+    envVariablesList.appendChild(listItem);
+  });
+}
+
+function renderRequiredInputs(requiredInputs) {
+  requiredInputsBody.replaceChildren();
+  if (!Array.isArray(requiredInputs) || requiredInputs.length === 0) {
+    const row = document.createElement("tr");
+    row.innerHTML = `
+      <td colspan="5">No required inputs detected. Copy <code>.env.example</code> to <code>.env</code> if you want to override defaults later.</td>
+    `;
+    requiredInputsBody.appendChild(row);
+    return;
+  }
+
+  requiredInputs.forEach((item) => {
+    const row = document.createElement("tr");
+    row.innerHTML = `
+      <td><code>${escapeHtml(item.name || "")}</code></td>
+      <td>${item.required === false ? "Optional" : "Required"}</td>
+      <td><code>${escapeHtml(item.example || "") || "-"}</code></td>
+      <td>${escapeHtml(item.whereToAdd || ".env")}</td>
+      <td>${escapeHtml(item.purpose || "No purpose provided.")}</td>
+    `;
+    requiredInputsBody.appendChild(row);
+  });
+}
+
+function renderModules(modules) {
+  modulesList.replaceChildren();
+  if (!Array.isArray(modules) || modules.length === 0) {
+    const empty = document.createElement("p");
+    empty.className = "text-block";
+    empty.textContent = "No modules available.";
+    modulesList.appendChild(empty);
+    return;
+  }
+
+  modules.forEach((module) => {
+    const card = document.createElement("article");
+    card.className = "module-card";
+
+    const title = document.createElement("h4");
+    title.textContent = module.name || "Unnamed module";
+
+    const purpose = document.createElement("p");
+    purpose.textContent = module.purpose || "No purpose provided.";
+
+    const keyFiles = document.createElement("p");
+    keyFiles.className = "key-files";
+    const files = Array.isArray(module.keyFiles) && module.keyFiles.length
+      ? module.keyFiles.join(", ")
+      : "No key files provided.";
+    keyFiles.textContent = `Key files: ${files}`;
+
+    card.append(title, purpose, keyFiles);
+    modulesList.appendChild(card);
+  });
+}
+
+function renderFiles(files) {
+  filesList.replaceChildren();
+  if (!Array.isArray(files) || files.length === 0) {
+    const empty = document.createElement("p");
+    empty.className = "text-block";
+    empty.textContent = "No starter files were generated.";
+    filesList.appendChild(empty);
+    return;
+  }
+
+  files.forEach((file) => {
+    const entry = document.createElement("details");
+    entry.className = "file-entry";
+
+    const summary = document.createElement("summary");
+    summary.innerHTML = `
+      <span class="file-entry-header">
+        <span class="file-entry-dots"><span></span><span></span><span></span></span>
+        <span class="file-entry-path">${escapeHtml(file.path || "Unnamed file")}</span>
+      </span>
+      <span class="file-entry-tag">Source</span>
+    `;
+
+    const code = document.createElement("pre");
+    code.className = "code-block";
+    code.textContent = file.content || "";
+
+    entry.append(summary, code);
+    filesList.appendChild(entry);
+  });
+}
+
+function clearCollection(element) {
+  element.replaceChildren();
+}
+
+function dedupeList(items) {
+  return [...new Set((items || []).filter(Boolean))];
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#039;");
+}

app/static/style.css

@@ -0,0 +1,648 @@
+:root {
+  --bg: #f2f4f7;
+  --surface: #ffffff;
+  --surface-soft: #f8fafc;
+  --surface-strong: #eef4ff;
+  --text: #1f2937;
+  --muted: #667085;
+  --border: #d0d5dd;
+  --accent: #2563eb;
+  --accent-strong: #1d4ed8;
+  --success: #027a48;
+  --success-soft: #ecfdf3;
+  --danger: #b42318;
+  --danger-soft: #fef3f2;
+  --info: #175cd3;
+  --info-soft: #eff8ff;
+  --shadow: 0 1px 2px rgba(16, 24, 40, 0.06), 0 10px 20px rgba(16, 24, 40, 0.06);
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-height: 100vh;
+  background: var(--bg);
+  color: var(--text);
+  font-family: "Segoe UI", Tahoma, Arial, sans-serif;
+}
+
+.page-shell {
+  width: min(1180px, calc(100% - 28px));
+  margin: 0 auto;
+  padding: 24px 0 40px;
+}
+
+.hero,
+.panel {
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  background: var(--surface);
+  box-shadow: var(--shadow);
+}
+
+.hero {
+  margin-bottom: 18px;
+  padding: 20px 22px;
+  background: var(--surface);
+}
+
+.eyebrow,
+.section-label {
+  margin: 0 0 8px;
+  color: var(--accent);
+  font-size: 0.78rem;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.hero h1 {
+  margin: 0;
+  font-size: 1.9rem;
+  font-weight: 700;
+}
+
+.hero-copy {
+  margin: 10px 0 0;
+  color: var(--muted);
+  line-height: 1.6;
+  max-width: 780px;
+}
+
+.panel {
+  margin-top: 18px;
+  padding: 20px;
+}
+
+.section-heading {
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-start;
+  gap: 16px;
+  margin-bottom: 16px;
+}
+
+.section-heading h2,
+.download-panel h2 {
+  margin: 0;
+  font-size: 1.35rem;
+  font-weight: 600;
+}
+
+.section-note {
+  margin: 0;
+  color: var(--muted);
+  font-size: 0.92rem;
+  line-height: 1.5;
+}
+
+.field-label {
+  display: block;
+  margin-bottom: 8px;
+  font-size: 0.95rem;
+  font-weight: 600;
+}
+
+textarea,
+select,
+.question-input {
+  width: 100%;
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  background: #fff;
+  color: var(--text);
+  font: 0.96rem/1.5 "Segoe UI", Tahoma, Arial, sans-serif;
+}
+
+textarea {
+  min-height: 190px;
+  resize: vertical;
+  padding: 14px 16px;
+}
+
+select,
+.question-input {
+  padding: 11px 12px;
+}
+
+textarea:focus,
+select:focus,
+.question-input:focus,
+details summary:focus {
+  outline: none;
+  border-color: var(--accent);
+  box-shadow: 0 0 0 3px rgba(37, 99, 235, 0.12);
+}
+
+.compose-grid,
+.stack-grid,
+.preview-grid,
+.agent-grid {
+  display: grid;
+  gap: 14px;
+}
+
+.compose-grid {
+  grid-template-columns: minmax(0, 280px);
+}
+
+.stack-grid {
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+}
+
+.preview-grid,
+.agent-grid {
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 16px;
+}
+
+.select-field {
+  display: grid;
+  gap: 6px;
+}
+
+.select-field span {
+  font-size: 0.9rem;
+  font-weight: 600;
+}
+
+.action-row,
+.question-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+}
+
+.action-row {
+  margin-top: 16px;
+}
+
+button {
+  border: 1px solid transparent;
+  border-radius: 10px;
+  padding: 10px 16px;
+  font: 600 0.94rem/1 "Segoe UI", Tahoma, Arial, sans-serif;
+  cursor: pointer;
+}
+
+button:disabled {
+  cursor: not-allowed;
+  opacity: 0.6;
+}
+
+.primary-button {
+  background: var(--accent);
+  color: #fff;
+}
+
+.primary-button:hover:not(:disabled) {
+  background: var(--accent-strong);
+}
+
+.secondary-button {
+  background: #344054;
+  color: #fff;
+}
+
+.success-button {
+  background: #039855;
+  color: #fff;
+}
+
+.ghost-button {
+  background: #fff;
+  color: var(--text);
+  border-color: var(--border);
+}
+
+.status-message {
+  margin-top: 14px;
+  padding: 12px 14px;
+  border: 1px solid transparent;
+  border-radius: 10px;
+  font-size: 0.93rem;
+  line-height: 1.5;
+}
+
+.status-message.loading,
+.status-message.info {
+  background: var(--info-soft);
+  border-color: #b2ddff;
+  color: var(--info);
+}
+
+.status-message.success {
+  background: var(--success-soft);
+  border-color: #abefc6;
+  color: var(--success);
+}
+
+.status-message.error {
+  background: var(--danger-soft);
+  border-color: #fecdca;
+  color: var(--danger);
+}
+
+.agent-panel {
+  background: var(--surface);
+}
+
+.agent-bubble {
+  display: flex;
+  gap: 14px;
+  align-items: flex-start;
+  padding: 16px;
+  border: 1px solid #dbe7ff;
+  border-radius: 14px;
+  background: #f8fbff;
+  margin-bottom: 16px;
+}
+
+.agent-avatar {
+  width: 42px;
+  height: 42px;
+  border-radius: 999px;
+  background: var(--accent);
+  color: #fff;
+  display: grid;
+  place-items: center;
+  font-weight: 700;
+  flex: 0 0 auto;
+}
+
+.agent-copy {
+  min-width: 0;
+}
+
+.agent-name {
+  margin: 0 0 6px;
+  font-weight: 700;
+}
+
+.agent-inline-heading {
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-start;
+  gap: 16px;
+  margin-bottom: 14px;
+}
+
+.question-cards {
+  display: grid;
+  gap: 12px;
+}
+
+.question-card {
+  padding: 14px 16px;
+  border: 1px solid #dbe7ff;
+  border-radius: 12px;
+  background: #fff;
+}
+
+.question-card h4 {
+  margin: 0 0 8px;
+  font-size: 1rem;
+}
+
+.question-position {
+  margin: 0 0 10px;
+  color: var(--accent);
+  font-size: 0.84rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.question-reason {
+  margin: 0 0 12px;
+  color: var(--muted);
+  line-height: 1.55;
+}
+
+.question-hint {
+  margin: 10px 0 0;
+  color: var(--muted);
+  font-size: 0.88rem;
+  line-height: 1.5;
+}
+
+.question-control {
+  display: grid;
+  gap: 8px;
+}
+
+.suggestion-block {
+  margin-top: 14px;
+  padding: 14px;
+  border: 1px solid #bfd4fe;
+  border-radius: 12px;
+  background: #eff8ff;
+}
+
+.suggestion-title {
+  margin: 0 0 8px;
+  color: var(--accent);
+  font-weight: 700;
+}
+
+.suggestion-reason {
+  margin: 0 0 12px;
+  color: var(--text);
+  line-height: 1.55;
+}
+
+.final-requirements-block {
+  margin: 0 0 14px;
+  white-space: pre-wrap;
+  padding: 14px;
+  border: 1px solid #d0d5dd;
+  border-radius: 10px;
+  background: #101828;
+  color: #f8fafc;
+  font: 0.92rem/1.6 Consolas, "Courier New", monospace;
+}
+
+.advanced-stack {
+  margin-top: 18px;
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  background: #fff;
+}
+
+.advanced-stack summary {
+  padding: 14px 16px;
+  cursor: pointer;
+  font-weight: 600;
+}
+
+.advanced-stack .section-note,
+.advanced-stack .stack-grid {
+  margin: 0 16px 16px;
+}
+
+.stack-chip-row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  margin-bottom: 16px;
+}
+
+.stack-chip {
+  display: inline-flex;
+  gap: 6px;
+  align-items: center;
+  padding: 6px 10px;
+  border: 1px solid #bfd4fe;
+  border-radius: 999px;
+  background: #eff8ff;
+  color: var(--info);
+  font-size: 0.85rem;
+}
+
+.card {
+  padding: 16px;
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  background: var(--surface-soft);
+}
+
+.card.wide {
+  grid-column: 1 / -1;
+}
+
+.card h3 {
+  margin: 0 0 10px;
+  font-size: 1rem;
+  font-weight: 600;
+}
+
+.list-block,
+.modules-list,
+.files-list {
+  margin: 0;
+  padding: 0;
+}
+
+.list-block {
+  list-style: none;
+  display: grid;
+  gap: 8px;
+}
+
+.list-block li {
+  padding: 10px 12px;
+  border: 1px solid #eaecf0;
+  border-radius: 8px;
+  background: #fff;
+  line-height: 1.5;
+}
+
+.command-list li {
+  font-family: Consolas, "Courier New", monospace;
+}
+
+.text-block {
+  margin: 0;
+  line-height: 1.65;
+}
+
+.required-inputs-copy {
+  margin: 0 0 12px;
+  color: var(--muted);
+  line-height: 1.6;
+}
+
+.required-inputs-table-wrap {
+  overflow-x: auto;
+  border: 1px solid #eaecf0;
+  border-radius: 10px;
+  background: #fff;
+}
+
+.required-inputs-table {
+  width: 100%;
+  border-collapse: collapse;
+  min-width: 720px;
+}
+
+.required-inputs-table th,
+.required-inputs-table td {
+  padding: 10px 12px;
+  border-bottom: 1px solid #eaecf0;
+  text-align: left;
+  vertical-align: top;
+  line-height: 1.5;
+}
+
+.required-inputs-table th {
+  background: #f9fafb;
+  font-size: 0.84rem;
+  font-weight: 700;
+  color: var(--muted);
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+}
+
+.required-inputs-table tr:last-child td {
+  border-bottom: 0;
+}
+
+.required-inputs-table code {
+  font-family: Consolas, "Courier New", monospace;
+}
+
+.module-card {
+  padding: 12px 14px;
+  border: 1px solid #eaecf0;
+  border-radius: 10px;
+  background: #fff;
+}
+
+.module-card + .module-card,
+.file-entry + .file-entry {
+  margin-top: 10px;
+}
+
+.module-card h4 {
+  margin: 0;
+  font-size: 0.98rem;
+}
+
+.module-card p {
+  margin: 8px 0 10px;
+  color: var(--muted);
+  line-height: 1.6;
+}
+
+.key-files {
+  margin: 0;
+  color: var(--muted);
+  font-size: 0.88rem;
+}
+
+.code-block {
+  margin: 0;
+  overflow-x: auto;
+  padding: 14px;
+  border: 1px solid #d0d5dd;
+  border-radius: 10px;
+  background: #101828;
+  color: #f8fafc;
+  font: 0.92rem/1.6 Consolas, "Courier New", monospace;
+}
+
+.file-entry {
+  border: 1px solid #d0d5dd;
+  border-radius: 10px;
+  overflow: hidden;
+  background: #fff;
+}
+
+.file-entry summary {
+  padding: 12px 14px;
+  cursor: pointer;
+  list-style: none;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 10px;
+  background: #f9fafb;
+}
+
+.file-entry summary::-webkit-details-marker {
+  display: none;
+}
+
+.file-entry-header {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  min-width: 0;
+}
+
+.file-entry-dots {
+  display: inline-flex;
+  gap: 4px;
+}
+
+.file-entry-dots span {
+  width: 7px;
+  height: 7px;
+  border-radius: 999px;
+  background: #98a2b3;
+}
+
+.file-entry-path {
+  font: 0.9rem/1.4 Consolas, "Courier New", monospace;
+  word-break: break-all;
+}
+
+.file-entry-tag {
+  color: var(--muted);
+  font-size: 0.76rem;
+  font-weight: 700;
+  text-transform: uppercase;
+}
+
+.download-copy {
+  margin: 0;
+  line-height: 1.6;
+}
+
+.download-link {
+  display: inline-block;
+  margin-top: 12px;
+  padding: 10px 16px;
+  border-radius: 10px;
+  background: var(--accent);
+  color: #fff;
+  text-decoration: none;
+  font-weight: 600;
+}
+
+@media (max-width: 960px) {
+  .section-heading,
+  .agent-inline-heading {
+    flex-direction: column;
+  }
+
+  .stack-grid,
+  .preview-grid,
+  .agent-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .card,
+  .card.wide {
+    grid-column: 1 / -1;
+  }
+}
+
+@media (max-width: 640px) {
+  .page-shell {
+    width: min(100% - 16px, 1180px);
+    padding: 16px 0 28px;
+  }
+
+  .panel,
+  .hero {
+    padding: 16px;
+  }
+
+  .action-row,
+  .question-actions {
+    flex-direction: column;
+  }
+
+  button,
+  .download-link {
+    width: 100%;
+  }
+
+  .compose-grid {
+    grid-template-columns: 1fr;
+  }
+}

app/templates/index.html

@@ -0,0 +1,261 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Project Agent</title>
+  <link rel="stylesheet" href="{{ request.url_for('static', path='/style.css') }}">
+</head>
+<body>
+  <main class="page-shell">
+    <section class="hero">
+      <p class="eyebrow">Project Agent</p>
+      <h1>Agent-guided project architecture for runnable starter apps.</h1>
+      <p class="hero-copy">
+        Describe your idea, let the agent identify missing architecture decisions,
+        review the recommended stack, then generate, validate, preview, and export.
+      </p>
+    </section>
+
+    <section class="panel compose-panel">
+      <div class="section-heading">
+        <div>
+          <p class="section-label">Idea Input</p>
+          <h2>Start with the product idea</h2>
+        </div>
+        <p class="section-note">The agent will ask only the questions that change architecture, dependencies, or required files.</p>
+      </div>
+
+      <label class="field-label" for="ideaInput">Describe what you want to build</label>
+      <textarea
+        id="ideaInput"
+        name="idea"
+        rows="8"
+        placeholder="Example:
+- Build a beginner-friendly expense tracker web app for small teams
+- Create an AI support dashboard and choose the best stack automatically
+- Generate a React + FastAPI starter for a customer portal with admin access"
+      ></textarea>
+
+      <div class="compose-grid">
+        <label class="select-field">
+          <span>Generation Mode</span>
+          <select id="generationModeSelect">
+            <option value="fast">Fast Mode</option>
+            <option value="deep">Deep Mode</option>
+          </select>
+        </label>
+      </div>
+
+      <div class="action-row">
+        <button id="suggestButton" class="primary-button" type="button">Start Agent</button>
+        <button id="regenerateButton" class="secondary-button" type="button" disabled>Regenerate With Selected Stack</button>
+        <button id="confirmButton" class="success-button" type="button" disabled>Confirm And Create ZIP</button>
+        <button id="clearButton" class="ghost-button" type="button" disabled>Clear Preview</button>
+      </div>
+
+      <div id="statusMessage" class="status-message" hidden></div>
+    </section>
+
+    <section id="agentSection" class="panel agent-panel" hidden>
+      <div class="section-heading">
+        <div>
+          <p class="section-label">Agent Conversation</p>
+          <h2>Project Agent</h2>
+        </div>
+        <p class="section-note">The agent is guiding the architecture before generation.</p>
+      </div>
+
+      <div class="agent-bubble agent-intro">
+        <div class="agent-avatar">PA</div>
+        <div class="agent-copy">
+          <p class="agent-name">Project Agent</p>
+          <p id="agentUnderstandingText" class="text-block"></p>
+        </div>
+      </div>
+
+      <div class="agent-grid">
+        <article class="card">
+          <h3>Assumptions</h3>
+          <ul id="agentAssumptionsList" class="list-block"></ul>
+        </article>
+
+        <article class="card wide">
+          <h3>Suggested Stack</h3>
+          <ul id="agentSuggestedStackList" class="list-block"></ul>
+        </article>
+      </div>
+
+      <article class="card wide question-section">
+        <div class="agent-inline-heading">
+          <div>
+            <h3>Questions</h3>
+            <p class="section-note">Answer in your own words. If you leave it blank, the agent will suggest a default and explain why.</p>
+          </div>
+          <div class="question-actions">
+            <button id="continueButton" class="secondary-button" type="button" disabled>Next</button>
+            <button id="skipQuestionsButton" class="ghost-button" type="button" disabled>Skip All &amp; Use Suggested Defaults</button>
+          </div>
+        </div>
+        <div id="questionCards" class="question-cards"></div>
+      </article>
+
+      <article id="finalizeCard" class="card wide" hidden>
+        <h3>Finalized Requirements</h3>
+        <p id="finalizeSummaryText" class="text-block"></p>
+        <ul id="finalSelectedStackList" class="list-block"></ul>
+        <pre id="finalRequirementsText" class="final-requirements-block"></pre>
+        <button id="generateProjectButton" class="primary-button" type="button" disabled>Generate Project</button>
+      </article>
+
+      <details id="advancedStackSection" class="advanced-stack" hidden>
+        <summary>Advanced Stack Settings</summary>
+        <p class="section-note">You can still override the stack manually before generation or regeneration.</p>
+        <div class="stack-grid">
+          <label class="select-field">
+            <span>Language</span>
+            <select id="languageSelect"></select>
+          </label>
+          <label class="select-field">
+            <span>Frontend</span>
+            <select id="frontendSelect"></select>
+          </label>
+          <label class="select-field">
+            <span>Backend</span>
+            <select id="backendSelect"></select>
+          </label>
+          <label class="select-field">
+            <span>Database</span>
+            <select id="databaseSelect"></select>
+          </label>
+          <label class="select-field">
+            <span>AI / Tools</span>
+            <select id="aiToolsSelect"></select>
+          </label>
+          <label class="select-field">
+            <span>Deployment</span>
+            <select id="deploymentSelect"></select>
+          </label>
+        </div>
+      </details>
+    </section>
+
+    <section id="previewSection" class="panel preview-panel" hidden>
+      <div class="section-heading">
+        <div>
+          <p class="section-label">Preview</p>
+          <h2 id="projectNameHeading">Generated Project</h2>
+        </div>
+        <p class="section-note">The latest preview is used for ZIP creation.</p>
+      </div>
+
+      <div id="stackChips" class="stack-chip-row"></div>
+
+      <div class="preview-grid">
+        <article class="card wide">
+          <h3>Summary</h3>
+          <p id="summaryText" class="text-block"></p>
+        </article>
+
+        <article class="card">
+          <h3>Selected Stack</h3>
+          <ul id="selectedStackList" class="list-block"></ul>
+        </article>
+
+        <article class="card">
+          <h3>Chosen Stack Summary</h3>
+          <ul id="chosenStackList" class="list-block"></ul>
+        </article>
+
+        <article class="card">
+          <h3>Detected User Choices</h3>
+          <ul id="detectedChoicesList" class="list-block"></ul>
+        </article>
+
+        <article class="card">
+          <h3>Problem Statement</h3>
+          <p id="problemStatementText" class="text-block"></p>
+        </article>
+
+        <article class="card wide">
+          <h3>Architecture</h3>
+          <ul id="architectureList" class="list-block"></ul>
+        </article>
+
+        <article class="card wide">
+          <h3>Modules</h3>
+          <div id="modulesList" class="modules-list"></div>
+        </article>
+
+        <article class="card">
+          <h3>Package Requirements</h3>
+          <ul id="packageRequirementsList" class="list-block"></ul>
+        </article>
+
+        <article class="card">
+          <h3>Environment Variables</h3>
+          <ul id="envVariablesList" class="list-block"></ul>
+        </article>
+
+        <article class="card wide">
+          <h3>Required Inputs</h3>
+          <p class="required-inputs-copy">Fill these values in <code>.env</code> before running the project.</p>
+          <div class="required-inputs-table-wrap">
+            <table class="required-inputs-table">
+              <thead>
+                <tr>
+                  <th>Name</th>
+                  <th>Required</th>
+                  <th>Example</th>
+                  <th>Where To Add</th>
+                  <th>Purpose</th>
+                </tr>
+              </thead>
+              <tbody id="requiredInputsBody"></tbody>
+            </table>
+          </div>
+        </article>
+
+        <article class="card">
+          <h3>Install Commands</h3>
+          <ul id="installCommandsList" class="list-block command-list"></ul>
+        </article>
+
+        <article class="card">
+          <h3>Run Commands</h3>
+          <ul id="runCommandsList" class="list-block command-list"></ul>
+        </article>
+
+        <article class="card wide">
+          <h3>Assumptions</h3>
+          <ul id="assumptionsList" class="list-block"></ul>
+        </article>
+
+        <article class="card wide">
+          <h3>File Tree</h3>
+          <pre id="fileTreeBlock" class="code-block"></pre>
+        </article>
+
+        <article class="card wide">
+          <h3>Generated Files</h3>
+          <div id="filesList" class="files-list"></div>
+        </article>
+      </div>
+    </section>
+
+    <section id="downloadSection" class="panel download-panel" hidden>
+      <div class="section-heading">
+        <div>
+          <p class="section-label">Download</p>
+          <h2>ZIP Ready</h2>
+        </div>
+        <p class="section-note">Download the latest confirmed preview.</p>
+      </div>
+      <p id="downloadText" class="download-copy">Your generated project ZIP is ready.</p>
+      <a id="downloadLink" class="download-link" href="#" download>Download ZIP</a>
+    </section>
+  </main>
+
+  <script src="{{ request.url_for('static', path='/app.js') }}" defer></script>
+</body>
+</html>

requirements.txt

@@ -0,0 +1,5 @@
+fastapi
+uvicorn[standard]
+jinja2
+httpx
+python-dotenv

tests/test_agent_controller.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import unittest
+from unittest.mock import patch
+
+from app.services.agent_controller import agent_controller
+
+
+class AgentControllerTests(unittest.TestCase):
+    def test_analyze_idea_returns_stack_and_questions(self) -> None:
+        result = agent_controller.analyze_idea("Build a dashboard for a small team")
+
+        self.assertIn("understanding", result)
+        self.assertIn("suggestedStack", result)
+        self.assertIn("questions", result)
+        self.assertIsInstance(result["questions"], list)
+        self.assertTrue(result["suggestedStack"]["backend"])
+
+    def test_finalize_requirements_normalizes_partial_answers(self) -> None:
+        result = agent_controller.finalize_requirements(
+            "Build a starter app",
+            {"database": "postgres", "backend_framework": "node", "authentication": "yes"},
+            {
+                "language": "Auto",
+                "frontend": "React",
+                "backend": "FastAPI",
+                "database": "SQLite",
+                "aiTools": "Auto",
+                "deployment": "Render",
+            },
+        )
+
+        self.assertEqual(result["selectedStack"]["database"], "PostgreSQL")
+        self.assertEqual(result["selectedStack"]["backend"], "Express")
+        self.assertIn("authentication-ready", result["finalRequirements"])
+
+    def test_plan_project_structure_covers_full_stack(self) -> None:
+        context = agent_controller._build_idea_context(
+            "Build a customer portal",
+            selected_stack={
+                "language": "Python",
+                "frontend": "React",
+                "backend": "FastAPI",
+                "database": "SQLite",
+                "aiTools": "None",
+                "deployment": "Render",
+            },
+            final_requirements="Include a simple dashboard.",
+        )
+        plan = agent_controller.plan_project_structure(context, {})
+
+        self.assertEqual(plan.selected_stack["frontend"], "React")
+        self.assertEqual(plan.selected_stack["backend"], "FastAPI")
+        self.assertTrue(any(file["path"].startswith("frontend/") for file in plan.files))
+        self.assertTrue(any(file["path"].startswith("backend/") for file in plan.files))
+
+    def test_generate_files_falls_back_without_ollama(self) -> None:
+        with patch.dict(os.environ, {"OLLAMA_BASE_URL": ""}, clear=False):
+            preview = asyncio.run(
+                agent_controller.generate_files(
+                    "Build a task tracker",
+                    generation_mode="fast",
+                )
+            )
+
+        self.assertIn("projectName", preview)
+        self.assertTrue(any("fallback" in item.lower() for item in preview["assumptions"]))
+        self.assertTrue(preview["files"])
+
+
+if __name__ == "__main__":
+    unittest.main()