Add PostHog storytelling v2 tracking for notebook usage flows.

.env.local.example

@@ -43,6 +43,13 @@ NOTEBOOK_PUBLIC_URL=http://notebook.local.knowhereto.ai:3001
 # to Better Auth's standard cookie names.
 # SESSION_COOKIE_NAMES=better-auth.session_token,__Secure-better-auth.session_token
 
+# --- Product analytics (client-side) ---
+# PostHog Project API key. When unset, Notebook skips analytics initialization.
+# NEXT_PUBLIC_POSTHOG_KEY=phc_your_project_api_key
+#
+# PostHog ingestion host. Keep default for US PostHog Cloud.
+# NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
+
 # --- Database (server-side only) ---
 # Neon Postgres connection string (Vercel Marketplace free tier).
 # Provisioned by the owner; do not commit a real value.

README.md

@@ -12,6 +12,8 @@ Upload documents, explore parsed content, and ask questions about your knowledge
 2. Fill in your API keys in `.env.local`:
    - `AI_GATEWAY_API_KEY` — your Vercel AI Gateway key for chat (optional `CHAT_MODEL` override)
    - `KNOWHERE_API_KEY` — optional development override that skips Dashboard auth and calls Knowhere directly
+   - `NEXT_PUBLIC_POSTHOG_KEY` — PostHog Project API key for front-end event tracking
+   - `NEXT_PUBLIC_POSTHOG_HOST` — PostHog ingestion host (default `https://us.i.posthog.com`)
 
 3. Install dependencies and run:
    ```bash
@@ -21,6 +23,43 @@ Upload documents, explore parsed content, and ask questions about your knowledge
 
 4. Open [http://localhost:3000](http://localhost:3000)
 
+## PostHog Tracking
+
+Notebook sends these product analytics events when PostHog is configured:
+
+- `notebook_upload_button_clicked`
+- `notebook_document_upload_completed` (`uploaded_count`, `file_types`, `total_size_bytes`)
+- `notebook_assistant_question_submitted` (`selected_sources_count`, `message_length`)
+- `notebook_dashboard_link_clicked`
+
+Notebook also calls PostHog `identify` for authenticated users and `reset` for
+guest sessions so insights can be grouped by user.
+
+### Connect Notebook to PostHog
+
+1. In PostHog, create/select a project.
+2. Copy the project API key and ingestion host.
+3. Set these values in `.env.local`:
+   ```bash
+   NEXT_PUBLIC_POSTHOG_KEY=phc_your_project_api_key
+   NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
+   ```
+4. Restart `pnpm dev` (or `npm run dev`), then trigger a few actions in Notebook.
+5. Open PostHog `Events` and filter by the event names above to verify ingestion.
+
+### Where to view the metrics
+
+Create four Trends insights in PostHog:
+
+1. Upload button clicks: count of `notebook_upload_button_clicked`
+2. Uploaded documents: `sum(uploaded_count)` on `notebook_document_upload_completed`
+3. Avg sources per question: `avg(selected_sources_count)` on `notebook_assistant_question_submitted`
+4. Users opening dashboard: `Unique users` on `notebook_dashboard_link_clicked`
+
+Pin those four insights to a `Notebook Tracking` dashboard for team reporting.
+
+GA4 field and event alignment guidance lives in `docs/ga4-alignment.md`.
+
 ## Tech Stack
 
 - **Framework**: [Next.js 16](https://nextjs.org) with App Router and Server Components

docs/ga4-alignment.md

@@ -0,0 +1,41 @@
+# GA4 Alignment for Notebook Storytelling v2
+
+This document maps the Notebook storytelling events to GA4 naming and parameters.
+
+## Naming policy
+
+- Keep the same event names in PostHog and GA4.
+- Keep the same parameter names and meanings in both systems.
+
+## Shared user properties
+
+- `workspace_id`
+- `workspace_namespace`
+- `is_guest`
+
+## Event mapping
+
+- `notebook_upload_button_clicked`
+  - params: `source_count_snapshot`, `surface`
+- `notebook_document_upload_completed`
+  - params: `uploaded_count`, `file_types`, `total_size_bytes`, `source_count_before`, `source_count_after`
+- `notebook_document_upload_failed`
+  - params: `file_type`, `file_size_bytes`, `error_type`, `error_message`
+- `notebook_assistant_question_submitted`
+  - params: `thread_id`, `selected_sources_count`, `source_count_snapshot`, `message_length`
+- `notebook_assistant_answer_completed`
+  - params: `thread_id`, `latency_ms`
+- `notebook_assistant_answer_failed`
+  - params: `thread_id`, `latency_ms`, `error_type`, `error_message`
+- `notebook_dashboard_link_clicked`
+  - params: `from_page`, `target_url`, `has_sources`, `has_chats`
+- `notebook_workspace_first_document_uploaded`
+  - params: `surface`
+- `notebook_workspace_first_question_asked`
+  - params: `selected_sources_count`, `surface`
+
+## GA4 implementation notes
+
+- Send GA4 events from the same trigger points as PostHog.
+- Attach `workspace_id`, `workspace_namespace`, and `is_guest` as GA4 user properties after auth state resolves.
+- Keep `error_message` truncated to avoid oversized payloads.

docs/posthog-notebook-tracking.md

@@ -0,0 +1,34 @@
+# PostHog Notebook Tracking Setup
+
+This runbook configures the four baseline insights for Knowhere Notebook usage.
+
+## Events
+
+- `notebook_upload_button_clicked`
+- `notebook_document_upload_completed`
+- `notebook_assistant_question_submitted`
+- `notebook_dashboard_link_clicked`
+
+## Create the Insights
+
+1. Open PostHog `Product Analytics -> Insights`.
+2. Create a `Trends` insight named `Notebook - Upload Button Clicks`.
+   - Series: event `notebook_upload_button_clicked`
+   - Math: `Total count`
+3. Create `Notebook - Uploaded Documents`.
+   - Series: event `notebook_document_upload_completed`
+   - Math: `Sum`
+   - Property: `uploaded_count`
+4. Create `Notebook - Avg Sources Per Question`.
+   - Series: event `notebook_assistant_question_submitted`
+   - Math: `Average`
+   - Property: `selected_sources_count`
+5. Create `Notebook - Dashboard Click Users`.
+   - Series: event `notebook_dashboard_link_clicked`
+   - Math: `Unique users`
+
+## Dashboard
+
+1. Open PostHog `Dashboards` and create `Notebook Tracking`.
+2. Add all four insights above to this dashboard.
+3. Use a rolling `Last 30 days` filter for product reviews.