[codex] add pwa setup

AGENTS.md

@@ -15,6 +15,7 @@ This is a TypeScript monorepo using pnpm workspaces. The application follows a d
 | Testing procedure | [docs/testing.md](./docs/testing.md) |
 | React conventions | [docs/react.md](./docs/react.md) |
 | OpenAPI and typed client generation | [docs/openapi.md](./docs/openapi.md) |
+| Progressive web app setup | [docs/pwa.md](./docs/pwa.md) |
 | Production Docker Compose | [docs/production.md](./docs/production.md) |
 | Core beliefs & principles | [docs/beliefs.md](./docs/beliefs.md) |
 | Quality tracking | [docs/quality.md](./docs/quality.md) |

README.md

@@ -35,7 +35,7 @@ See [docs/production.md](./docs/production.md) for the production image, Compose
 
 See [docs/architecture.md](./docs/architecture.md) for the full picture.
 
-Each business domain follows a strict layered model. The React UI uses TanStack Query for server-state fetching, mutation, caching, and invalidation. HTTP route contracts generate the OpenAPI spec, typed frontend client, and TanStack Query helper factories; see [docs/openapi.md](./docs/openapi.md).
+Each business domain follows a strict layered model. The React UI uses TanStack Query for server-state fetching, mutation, caching, and invalidation. HTTP route contracts generate the OpenAPI spec, typed frontend client, and TanStack Query helper factories; see [docs/openapi.md](./docs/openapi.md). Progressive web app build behavior is documented in [docs/pwa.md](./docs/pwa.md).
 
 ```
 Types → Config → Repo → Service → Runtime → UI
@@ -58,7 +58,7 @@ When an agent needs the running app URL, use `pnpm health` or read `.stack/<work
 3. Update this README with the product name and local setup notes.
 4. Replace or rename the example domain under `src/domains/example/`.
 5. Add your first real domain by starting at the `types/` layer, then move forward through config, repo, service, runtime, and UI as needed.
-6. Keep [AGENTS.md](./AGENTS.md), [docs/implementation.md](./docs/implementation.md), [docs/testing.md](./docs/testing.md), [docs/openapi.md](./docs/openapi.md), [docs/production.md](./docs/production.md), and [docs/react.md](./docs/react.md) current as the project develops.
+6. Keep [AGENTS.md](./AGENTS.md), [docs/implementation.md](./docs/implementation.md), [docs/testing.md](./docs/testing.md), [docs/openapi.md](./docs/openapi.md), [docs/pwa.md](./docs/pwa.md), [docs/production.md](./docs/production.md), and [docs/react.md](./docs/react.md) current as the project develops.
 7. Run `pnpm lint`, `pnpm test`, `pnpm build`, and `pnpm check:docs` before treating the template migration as complete.
 
 ## For Agents

docs/pwa.md

@@ -0,0 +1,32 @@
+# Progressive Web App Setup
+
+Last verified: 2026-05-11
+
+This repo uses `vite-plugin-pwa` from the existing Vite build instead of maintaining a hand-written service worker.
+
+## What Is Wired
+
+- `src/app/vite.config.ts` registers `VitePWA` with `registerType: "autoUpdate"`.
+- Production web builds emit `manifest.webmanifest`, `sw.js`, and Workbox assets into `dist/app`.
+- `src/app/public/` contains the source logo, favicon, Apple touch icon, required manifest PNG icons, and `robots.txt`.
+- `src/app/index.html` includes description, theme color, favicon, SVG icon, and Apple touch icon metadata.
+- `src/static-assets.ts` serves `.webmanifest` as `application/manifest+json`.
+
+## Scope
+
+The service worker precaches the app shell and static assets only. API data stays network-driven through TanStack Query and the generated API client. Keep `/api/*` out of navigation fallback behavior so API routes never look like browser routes.
+
+Installability also requires HTTPS outside localhost. Keep TLS and HTTP-to-HTTPS redirects at the deployment or reverse-proxy layer; the app-level PWA setup assumes the production origin is already secure.
+
+## When Changing It
+
+1. Keep PWA configuration in `src/app/vite.config.ts`.
+2. Put installability assets under `src/app/public/`, which is the Vite public directory because `src/app` is the Vite root.
+3. Keep `theme_color` in the manifest aligned with the `<meta name="theme-color">` value in `src/app/index.html`.
+4. Regenerate icon files from `src/app/public/logo.svg` only when the source mark changes. The current assets were generated with:
+
+```bash
+pnpm dlx @vite-pwa/assets-generator --preset minimal-2023 --root src/app public/logo.svg
+```
+
+5. Run `pnpm build` to verify the manifest and service worker are emitted. Use `pnpm preview` for a pseudo-production browser smoke check.

docs/quality.md

@@ -24,6 +24,7 @@ Track the health of each domain and architectural layer. Update this when you im
 | database | B | Postgres provider wired through Docker Compose stack |
 | telemetry | B | Pino logger, request IDs, route timings, and stack log files are wired; metrics/traces are future work |
 | openapi | B | Route contracts generate `openapi.generated.json` and a typed frontend client; broader coverage should grow as domains are added |
+| pwa | B | Vite production builds emit a web manifest, service worker, installability icons, and static asset MIME handling; offline API data is intentionally out of scope |
 | production | B | Node 24 multi-stage Docker image and production Compose stack are documented; deployment hardening remains environment-specific |
 | feature-flags | D | Placeholder |
 
@@ -34,4 +35,4 @@ Track the health of each domain and architectural layer. Update this when you im
 
 ---
 
-*Last updated: 2026-05-05*
+*Last updated: 2026-05-11*

package.json

@@ -42,6 +42,7 @@
 		"tsx": "^4.21.0",
 		"typescript": "^6.0.3",
 		"vite": "^8.0.10",
+		"vite-plugin-pwa": "^1.3.0",
 		"vitest": "^4.1.5"
 	},
 	"engines": {