From 65b20f9ef9b141a07abb9b5d659fb24233bb4d8c Mon Sep 17 00:00:00 2001
From: nxtkofi <psliwa.b@gmail.com>
Date: Fri, 15 May 2026 19:42:06 +0200
Subject: [PATCH] docs(pwa): document lightweight PWA customization

---
 DEVELOPMENT.md | 38 ++++++++++++++++++++++++++++++++++++++
 README.md      |  1 +
 2 files changed, 39 insertions(+)

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index ad5929b..f0b58f2 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -230,3 +230,41 @@ When starting a new project:
 - [ ] Remove/replace placeholder content in `src/app/[locale]/page.tsx`
 - [ ] Add project-specific routes to `src/lib/routes.ts`
 - [ ] Run `pnpm lint` and `pnpm build` to verify
+
+## PWA Lite
+
+The template includes lightweight PWA installability out of the box. It is intentionally minimal and does **not** include offline caching, push notifications, or app-store wrappers.
+
+### What is included
+- `src/app/manifest.ts` — Web App Manifest with installability metadata
+- `public/pwa/icon.svg` — template placeholder icon
+- `public/pwa/maskable-icon.svg` — template placeholder maskable icon
+- `public/pwa/apple-touch-icon.svg` — template placeholder Apple touch icon
+- `src/app/layout.tsx` — PWA-relevant metadata (`applicationName`, `appleWebApp`, `icons`)
+
+### What is NOT included
+- Service worker or offline caching
+- Push notifications
+- Google Play TWA / Bubblewrap wrapper
+- Apple App Store native wrapper
+
+### Before shipping, customize these
+| Field | File |
+|-------|------|
+| `name`, `short_name`, `description` | `src/app/manifest.ts` |
+| `theme_color`, `background_color` | `src/app/manifest.ts` |
+| `start_url`, `scope` | `src/app/manifest.ts` |
+| Icon files | `public/pwa/` |
+| `applicationName`, `appleWebApp.title` | `src/app/layout.tsx` |
+
+> Replace the placeholder SVG icons with real branded assets before production. The template uses neutral `S` initials as a placeholder only.
+
+### Locale behavior
+The default manifest uses `start_url: '/'`. With `localePrefix: 'as-needed'` in `src/i18n/routing.ts`, Next.js/next-intl resolves the locale automatically when the app opens.
+
+### Auth / cache note
+Do not add aggressive caching for authenticated SaaS pages (dashboard, settings) unless you are deliberately designing offline behavior. The template intentionally skips the service worker to avoid accidental auth data leaks.
+
+### Store distribution
+- **Google Play**: requires a native/TWA wrapper such as Bubblewrap. The manifest alone is not enough.
+- **Apple App Store**: usually rejects simple repackaged websites without native value. A PWA wrapper alone is not sufficient.
diff --git a/README.md b/README.md
index b02edf3..e33af96 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,7 @@ A personal, opinionated SaaS template built for speed. Next.js 16 + Convex self-
 - [x] Runtime env validation (Zod)
 - [x] GitHub Actions CI (lint + build)
 - [x] Project init script (`bin/init-template.mjs`)
+- [x] PWA Lite installability (manifest + icons)
 
 ## Quick Start