feat: update docs

CONTRIBUTING.md

@@ -13,7 +13,7 @@ Thanks for helping us improve next-cwv-monitor! This guide covers development se
 
 ## Requirements
 
-- Node.js ≥ 20
+- Node.js ≥ 24
 - pnpm > 10.1
 - Docker + Docker Compose
 
@@ -25,9 +25,15 @@ pnpm install
 pnpm docker:dev
 ```
 
-- Brings up ClickHouse and the monitor app, runs migrations, and seeds demo data automatically.
-- Monitor: http://localhost:3000
-- Login with credentials from your `.env` file (defaults: `user@example.com` / `password`)
+`pnpm docker:dev` starts the full stack via Docker Compose:
+- **ClickHouse** — analytics database
+- **migrations** — runs ClickHouse schema migrations (short-lived, then exits)
+- **monitor-app** — dashboard + ingest API (http://localhost:3000)
+- **seed-demo** — seeds demo data on first start
+
+Login with credentials from your `.env` file (defaults: `user@example.com` / `password`).
+
+> To also run the demo **client-app** alongside the SDK in watch mode, use `pnpm dev:client` from the repo root (requires the monitor to already be running).
 
 ## Coding conventions
 
@@ -56,7 +62,14 @@ Key highlights (see [`CODE_STYLE.md`](./CODE_STYLE.md) for the full guide):
 
 ## Commit messages
 
-Use Conventional Commits
+Use [Conventional Commits](https://www.conventionalcommits.org/). Examples:
+
+```text
+feat: add hourly aggregates for route breakdowns
+fix: correct INP threshold for needs-improvement rating
+chore: upgrade ClickHouse client to 1.14
+docs: clarify sampleRate behaviour in SDK README
+```
 
 ## Pull requests
 

DEPLOYMENT.md

@@ -34,3 +34,4 @@ docker compose up -d
 - HTTPS in production (enable SSL mode in setup wizard, or use `AUTH_BASE_URL` with `https://`)
 - Firewall: only expose ports 80/443 (SSL mode) or `APP_PORT`
 - `TRUST_PROXY=true` only when behind a trusted proxy (auto-set in SSL mode)
+- Change `INITIAL_USER_PASSWORD` from the default before exposing the monitor publicly

README.md

@@ -43,11 +43,29 @@ Google's Core Web Vitals directly impact your **SEO rankings** and **user experi
 
 ## 🚀 Quick Start
 
-**Self-hosting?** Follow the [Deployment Guide](./DEPLOYMENT.md) to run on your infrastructure.
+There are two parts: the **monitor** (server that stores and displays metrics) and the **SDK** (snippet you add to your Next.js app).
 
-**Contributing?** See [Contributing Guide](./CONTRIBUTING.md) for local development setup.
+> **Prerequisites:** [Node.js](https://nodejs.org/) ≥ 24, [pnpm](https://pnpm.io/) ≥ 10.1, and [Docker](https://www.docker.com/). See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for full setup details.
 
-Add the SDK to the Next.js app you want to monitor:
+**Step 1 — Run the monitor** locally:
+
+```bash
+git clone https://github.com/Blazity/next-cwv-monitor.git
+cd next-cwv-monitor
+cp apps/monitor-app/.env.example apps/monitor-app/.env  # defaults work for local dev
+pnpm install
+pnpm docker:dev
+```
+
+The dashboard is now running at [http://localhost:3000](http://localhost:3000). See the [Deployment Guide](./DEPLOYMENT.md) for production self-hosting.
+
+**Step 2 — Create a project** in the monitor dashboard and copy the project UUID.
+
+**Step 3 — Add the SDK** to the Next.js app you want to monitor:
+
+```bash
+npm install next-cwv-monitor
+```
 
 ```tsx
 // app/providers.tsx — wrap your root layout with this provider
@@ -57,8 +75,8 @@ import { CWVMonitor } from "next-cwv-monitor/app-router";
 export function Providers({ children }: { children: React.ReactNode }) {
   return (
     <CWVMonitor
-      projectId="YOUR_PROJECT_UUID" // From the dashboard
-      endpoint="http://localhost:3000"
+      projectId="YOUR_PROJECT_UUID" // Paste the UUID from the dashboard
+      endpoint="http://localhost:3000" // In production, use your deployed monitor URL
     >
       {children}
     </CWVMonitor>

apps/client-app/README.md

@@ -1,30 +1,20 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# client-app
+
+A demo Next.js application that uses the `next-cwv-monitor` SDK. It exists to:
+
+- Demonstrate SDK integration in a realistic Next.js app.
+- Generate real CWV events and custom events against the local monitor for development and testing.
 
 ## Getting Started
 
-First, run the development server (defaults to port 3001):
+From the **repo root** (requires the monitor to already be running via `pnpm docker:dev`):
 
 ```bash
-pnpm dev
+pnpm dev:client
 ```
 
-Open [http://localhost:3001](http://localhost:3001) with your browser to see the result.
-
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
-
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
-
-## Learn More
-
-To learn more about Next.js, take a look at the following resources:
-
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
-
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
-
-## Deploy on Vercel
+This starts the client-app on [http://localhost:3001](http://localhost:3001) alongside the SDK in watch mode. See [`CONTRIBUTING.md`](../../CONTRIBUTING.md) for the full development setup.
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+## SDK integration example
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+See `src/app/providers.tsx` for how `CWVMonitor` is wired up. For full SDK documentation, see [`packages/client-sdk/README.md`](../../packages/client-sdk/README.md).

apps/monitor-app/README.md

@@ -1,30 +1,32 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# monitor-app
+
+The Next.js dashboard application for next-cwv-monitor. It serves two purposes:
+
+1. **Ingest API** (`POST /api/ingest`) — receives batched CWV events from the client SDK, validates them, and persists to ClickHouse.
+2. **Dashboard UI** — displays Core Web Vitals, route breakdowns, and custom events for all projects. Includes multi-user auth (Better Auth).
 
 ## Getting Started
 
-First, run the development server:
+The recommended way to run locally is from the **repo root**:
 
 ```bash
-pnpm dev
+pnpm docker:dev
 ```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
-
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
-
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
-
-## Learn More
-
-To learn more about Next.js, take a look at the following resources:
+This starts ClickHouse, runs migrations, seeds demo data, and launches the monitor at [http://localhost:3000](http://localhost:3000). See [`CONTRIBUTING.md`](../../CONTRIBUTING.md) for details.
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+> If you already have ClickHouse running separately, you can use `pnpm dev` inside this directory instead.
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+## Stack
 
-## Deploy on Vercel
+- **Next.js 16** App Router
+- **ClickHouse** — analytics storage
+- **Better Auth** — authentication
+- **Tailwind CSS + shadcn/ui** — UI
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+## Further reading
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+- [`ARCHITECTURE.md`](../../ARCHITECTURE.md) — system diagram and component breakdown
+- [`DEPLOYMENT.md`](../../DEPLOYMENT.md) — self-hosting guide and environment variables
+- [`clickhouse/SCHEMA.md`](./clickhouse/SCHEMA.md) — database schema
+- [`CONTRIBUTING.md`](../../CONTRIBUTING.md) — local development setup

apps/monitor-app/clickhouse/SCHEMA.md

@@ -26,7 +26,7 @@ Order key: `(id)`
 | `route`        | String                 | Normalized route                           |
 | `path`         | String                 | Raw concrete path (e.g. `/blog/xyz`)       |
 | `device_type`  | LowCardinality(String) | Device classification (`desktop`/`mobile`) |
-| `metric_name`  | LowCardinality(String) | Metric name (LCP, FID, etc.)               |
+| `metric_name`  | LowCardinality(String) | Metric name (LCP, INP, CLS, etc.)          |
 | `metric_value` | Float64                | Metric value                               |
 | `rating`       | LowCardinality(String) | Rating (good / needs_improvement / poor)   |
 | `recorded_at`  | DateTime64(3, 'UTC')   | Client-side timestamp                      |

packages/client-sdk/README.md

@@ -13,7 +13,9 @@ A lightweight React SDK for monitoring Core Web Vitals and custom events in Next
 ## Installation
 
     npm install next-cwv-monitor
-
+
+> The SDK requires a running instance of the monitor app as your `endpoint`. See the [self-hosting guide](https://github.com/Blazity/next-cwv-monitor/blob/main/DEPLOYMENT.md) to deploy one.
+
 
 ## Usage