# Drive blueprint → greenfield local dashboard bootstrap

Use when the user provides a Google Drive/Docs “Bauplan” or similar product blueprint and asks to realize a new local dashboard/PWA/app in an empty GitHub repo.

## Workflow

1. **Fetch and archive the source of truth first**
   - Locate the Drive folder/file via the configured workspace tool.
   - Export the document to plain text or markdown into a local `_source/` directory.
   - Copy the same exported blueprint into `docs/` so the repo carries the architecture/spec, but do not expose secrets or private raw datasets.

2. **Extract the roadmap before coding**
   - Search the blueprint for sections such as `Phase`, `Auftrag`, `Akzeptanzkriterien`, `Tests`, `Nicht machen`, and `Risiken`.
   - Treat those as the delivery contract.
   - Build strictly in order; do not jump to later phases because the final product is exciting. Very tempting. Also how dashboards become hydras.

3. **Bootstrap the first runnable slice**
   - Create a monorepo skeleton matching the blueprint (`backend/`, `frontend/`, `docs/`, `scripts/`, compose/proxy files).
   - Add a conservative `.gitignore`, `.env.example` with placeholders only, and README with start/stop/log/test commands.
   - Implement only the current phase/auftrag acceptance criteria plus the smallest safe seed data needed for smoke tests.
   - If the blueprint names a target device (for example an iPad model), document the physical-vs-CSS viewport assumptions in `docs/` before deep UI work, then size touch targets/layout breakpoints against CSS pixels, not hardware pixels.
   - For Docker/Compose-based local dashboards, add a short setup note with the exact install/check/start commands, but report missing Docker as an install prerequisite rather than treating non-Docker verification as Compose success.

4. **Verify locally without over-claiming**
   - Run backend tests and frontend build.
   - If Docker or a remote push is blocked by local setup/approval, report that as a blocker and preserve the local working tree; do not fabricate compose/push success.
   - Prefer a non-Docker smoke path (e.g. local FastAPI + frontend build) when Docker is unavailable, but label it as non-Docker verification.
   - For Python backends managed by `uv`, prefer `uv sync --extra dev` before TestClient/API smoke checks. `uv pip install -e '.[dev]'` can target an active global/session venv when `VIRTUAL_ENV` is set, leaving the project `.venv` without dev-only packages.
   - If a backend repo has runtime/generated folders beside the app package (for example `data/`), add explicit package discovery before editable installs: `[tool.setuptools.packages.find] include = ["app*"]`. Otherwise setuptools may refuse with “Multiple top-level packages discovered in a flat-layout”.

5. **GitHub handling**
   - Verify repo/remote/auth without printing tokens.
   - If auth/push approval is blocked, stop before trying alternate credential bypasses and report local path plus test evidence.

6. **Docker Compose verification on local dashboard servers**
   - After the user installs Docker, verify both `docker --version` and `docker compose version` before claiming Compose readiness.
   - If the user was just added to the `docker` group but the current shell has not picked it up, run Compose through `sg docker -c '<command>'` for verification and tell the user a logout/login should make plain `docker compose ...` work. This captures the fix, not a durable claim that Docker is broken.
   - Treat host port conflicts as expected on multi-dashboard machines. Prefer making Compose ports configurable, for example `"${FRONTEND_PORT:-5173}:5173"`, then smoke with `FRONTEND_PORT=5174 docker compose up --build -d` rather than killing unrelated dashboards.
   - Real Compose acceptance should include: build/start, backend health endpoint, frontend HTTP 200, a safe seed/read endpoint, and `docker compose ps` showing healthy/running services.

7. **FastAPI/TestClient dependency pitfall**
   - With newer FastAPI/Starlette stacks, `starlette.testclient` may require `httpx2` in addition to `httpx`. If TestClient raises `RuntimeError: ... requires the httpx2 package`, add `httpx2` to dev/test dependencies and run the project-environment sync (`uv sync --extra dev`) rather than repeatedly installing into the wrong active venv.
   - When editable Python packaging sees generated folders such as `data/` as top-level packages, add explicit setuptools package discovery such as `[tool.setuptools.packages.find] include = ["app*"]`.

## Acceptance reporting

Report:
- local project path;
- source blueprint archive path;
- phase/auftrag completed;
- exact tests/builds run and their real outputs;
- blocked items separately from completed items;
- next phase to execute.