From f98f2b2b9245f5b02b44be50da5888892e28a365 Mon Sep 17 00:00:00 2001
From: maxjneto <maxjneto@gmail.com>
Date: Sun, 31 May 2026 12:17:14 -0300
Subject: [PATCH 1/6] feat(observability): add PostHog AI observability, cookie
 consent, and analytics foundation

Backend: wire PostHog posthog-python client; instrument every phase function
(discovery, alignment, generation, refinement, audit, completion) with
$ai_trace / $ai_span events via a new services/observability.py helper.
Guardrails also capture span events on violations.

Frontend: initialise posthog-js (opt-out by default), add CookieConsentBanner
that drives opt-in/opt-out, wire Clerk user identity to PostHog, add initial
product events (phase_entered, document_created) and session-recording mask
selectors for editor content.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 packages/backend/.env.example                 |  7 ++
 packages/backend/app/ai/core/__init__.py      |  3 +-
 packages/backend/app/ai/core/client.py        | 10 ++-
 packages/backend/app/config.py                |  6 ++
 packages/backend/app/guardrails/input.py      | 25 ++++++--
 packages/backend/app/guardrails/output.py     |  6 ++
 packages/backend/app/phases/alignment/ai.py   |  7 ++
 .../backend/app/phases/alignment/contract.py  |  7 ++
 .../backend/app/phases/alignment/function.py  | 19 +++++-
 packages/backend/app/phases/audit/ai.py       |  7 +-
 packages/backend/app/phases/audit/function.py | 19 +++++-
 .../backend/app/phases/completion/function.py |  7 ++
 packages/backend/app/phases/discovery/ai.py   |  7 ++
 .../backend/app/phases/discovery/function.py  | 29 ++++++++-
 packages/backend/app/phases/generation/ai.py  | 14 +++-
 .../backend/app/phases/generation/function.py | 27 +++++++-
 .../backend/app/phases/generation/helpers.py  | 13 +++-
 packages/backend/app/phases/refinement/ai.py  |  7 ++
 .../backend/app/phases/refinement/function.py | 29 ++++++++-
 .../backend/app/phases/refinement/helpers.py  | 32 ++++++++--
 packages/backend/app/routers/documents.py     |  5 +-
 .../backend/app/services/observability.py     | 48 ++++++++++++++
 packages/backend/pyproject.toml               |  1 +
 packages/frontend/.env.example                |  4 ++
 packages/frontend/package.json                |  1 +
 packages/frontend/src/App.tsx                 | 64 ++++++++++++++-----
 .../phases/discovery/InitialInput.tsx         |  2 +
 .../phases/editor/EditorCenterPanel.tsx       |  2 +-
 .../components/shared/CookieConsentBanner.tsx | 53 +++++++++++++++
 .../components/shared/MarkdownRenderer.tsx    |  2 +-
 .../components/shared/NewDocumentDialog.tsx   |  3 +
 .../src/hooks/useClerkPosthogIdentity.ts      | 17 +++++
 packages/frontend/src/pages/DocumentPage.tsx  |  8 ++-
 33 files changed, 441 insertions(+), 50 deletions(-)
 create mode 100644 packages/backend/app/services/observability.py
 create mode 100644 packages/frontend/src/components/shared/CookieConsentBanner.tsx
 create mode 100644 packages/frontend/src/hooks/useClerkPosthogIdentity.ts

diff --git a/packages/backend/.env.example b/packages/backend/.env.example
index d76c12f..e81251a 100644
--- a/packages/backend/.env.example
+++ b/packages/backend/.env.example
@@ -9,3 +9,10 @@ INNGEST_SIGNING_KEY=
 CLERK_JWKS_URL=https://<your-clerk-frontend-api>.clerk.accounts.dev/.well-known/jwks.json
 # Comma-separated list of allowed frontend origins (matches the `azp` JWT claim)
 CLERK_AUTHORIZED_PARTIES=["http://localhost:5173"]
+
+# PostHog analytics (optional — leave POSTHOG_ENABLED=false to disable entirely)
+POSTHOG_API_KEY=
+POSTHOG_HOST=https://us.i.posthog.com
+POSTHOG_ENABLED=false
+
+POSTHOG_REDACT_PROMPTS=true
diff --git a/packages/backend/app/ai/core/__init__.py b/packages/backend/app/ai/core/__init__.py
index 5efebf8..1c3abd7 100644
--- a/packages/backend/app/ai/core/__init__.py
+++ b/packages/backend/app/ai/core/__init__.py
@@ -1,4 +1,4 @@
-from app.ai.core.client import DEFAULT_MODEL, GUARDRAIL_MODEL, client
+from app.ai.core.client import DEFAULT_MODEL, GUARDRAIL_MODEL, client, posthog_client
 from app.ai.core.output_cleaner import (
     clean_section_output,
     promote_h1_headings,
@@ -18,6 +18,7 @@
 
 __all__ = [
     "client",
+    "posthog_client",
     "DEFAULT_MODEL",
     "GUARDRAIL_MODEL",
     "truncate_section",
diff --git a/packages/backend/app/ai/core/client.py b/packages/backend/app/ai/core/client.py
index 839c406..9b77eb4 100644
--- a/packages/backend/app/ai/core/client.py
+++ b/packages/backend/app/ai/core/client.py
@@ -1,10 +1,16 @@
-from openai import AsyncOpenAI
+from posthog import Posthog
+from posthog.ai.openai import AsyncOpenAI
 
 from app.config import settings
 
+posthog_client: Posthog | None = None
+if settings.POSTHOG_ENABLED and settings.POSTHOG_API_KEY:
+    posthog_client = Posthog(settings.POSTHOG_API_KEY, host=settings.POSTHOG_HOST)
+
 client = AsyncOpenAI(
     base_url=settings.AZURE_OPENAI_ENDPOINT,
-    api_key=settings.AZURE_OPENAI_API_KEY
+    api_key=settings.AZURE_OPENAI_API_KEY,
+    posthog_client=posthog_client,
 )
 DEFAULT_MODEL = settings.AZURE_OPENAI_DEPLOYMENT
 GUARDRAIL_MODEL = settings.AZURE_OPENAI_GUARDRAIL_DEPLOYMENT
diff --git a/packages/backend/app/config.py b/packages/backend/app/config.py
index ccfb216..d184318 100644
--- a/packages/backend/app/config.py
+++ b/packages/backend/app/config.py
@@ -30,6 +30,12 @@ class Settings(BaseSettings):
     GUIDED_DOCUMENT_COST: int = 3
     EDITOR_DOCUMENT_COST: int = 1
 
+    # PostHog analytics — all disabled by default; set POSTHOG_ENABLED=true to activate
+    POSTHOG_API_KEY: str = ""
+    POSTHOG_HOST: str = "https://us.i.posthog.com"
+    POSTHOG_ENABLED: bool = False
+    POSTHOG_REDACT_PROMPTS: bool = True
+
     model_config = {"env_file": ENV_FILE, "extra": "ignore"}
 
 
diff --git a/packages/backend/app/guardrails/input.py b/packages/backend/app/guardrails/input.py
index 94540a9..9d0c961 100644
--- a/packages/backend/app/guardrails/input.py
+++ b/packages/backend/app/guardrails/input.py
@@ -103,7 +103,13 @@ def validate_refinement_message(message: str) -> ValidationError | None:
 }
 
 
-async def validate_message_intent(message: str, section_type: str, section_summary: str | None = None) -> ValidationError | None:
+async def validate_message_intent(
+    message: str,
+    section_type: str,
+    section_summary: str | None = None,
+    posthog_distinct_id: str | None = None,
+    posthog_properties: dict | None = None,
+) -> ValidationError | None:
     """LLM-based intent classifier: rejects messages unrelated to document editing.
 
     Failures are swallowed — a guardrail error must never block the user.
@@ -115,18 +121,23 @@ async def validate_message_intent(message: str, section_type: str, section_summa
     system_prompt = load_yaml_prompt("guardrails", "intent_classification", "system")
 
     try:
-        response = await client.chat.completions.create(
-            model=GUARDRAIL_MODEL,
-            messages=[
+        create_kwargs: dict = {
+            "model": GUARDRAIL_MODEL,
+            "messages": [
                 {"role": "system", "content": system_prompt},
                 {
                     "role": "user",
                     "content": f"Section: {section_type}\nSummary: {section_summary}\nMessage: {message}",
                 },
             ],
-            response_format=_INTENT_SCHEMA,
-            temperature=0.0,
-        )
+            "response_format": _INTENT_SCHEMA,
+            "temperature": 1.0,
+        }
+        if posthog_distinct_id is not None:
+            create_kwargs["posthog_distinct_id"] = posthog_distinct_id
+        if posthog_properties is not None:
+            create_kwargs["posthog_properties"] = posthog_properties
+        response = await client.chat.completions.create(**create_kwargs)
         result = json.loads(response.choices[0].message.content)
         if not result.get("is_valid", True):
             logger.warning(
diff --git a/packages/backend/app/guardrails/output.py b/packages/backend/app/guardrails/output.py
index f2919da..0612cf3 100644
--- a/packages/backend/app/guardrails/output.py
+++ b/packages/backend/app/guardrails/output.py
@@ -17,6 +17,8 @@ async def call_with_retry(
     temperature: float = 0.3,
     required_fields: list[str] | None = None,
     section_type: str | None = None,
+    posthog_distinct_id: str | None = None,
+    posthog_properties: dict | None = None,
 ) -> Any:
     """
     Call the AI model and validate the structured response.
@@ -37,6 +39,10 @@ async def call_with_retry(
         kwargs["tools"] = tools
     if tool_choice is not None:
         kwargs["tool_choice"] = tool_choice
+    if posthog_distinct_id is not None:
+        kwargs["posthog_distinct_id"] = posthog_distinct_id
+    if posthog_properties is not None:
+        kwargs["posthog_properties"] = posthog_properties
 
     response = await client.chat.completions.create(**kwargs)
     error = _validate_response(response, required_fields)
diff --git a/packages/backend/app/phases/alignment/ai.py b/packages/backend/app/phases/alignment/ai.py
index 1df76d1..dba2a07 100644
--- a/packages/backend/app/phases/alignment/ai.py
+++ b/packages/backend/app/phases/alignment/ai.py
@@ -60,6 +60,8 @@ async def generate_alignment(
     rejected_sections: list[dict] | None = None,
     db: AsyncSession | None = None,
     document_type_id: uuid.UUID | None = None,
+    posthog_distinct_id: str | None = None,
+    doc_id: str | None = None,
 ) -> dict:
     """Generate 1-2 sentence summaries for each section using per-section discovery contexts."""
     logger.info(
@@ -85,6 +87,11 @@ async def generate_alignment(
         response_format=ALIGNMENT_SCHEMA,
         temperature=0.3,
         required_fields=["summaries"],
+        posthog_distinct_id=posthog_distinct_id,
+        posthog_properties=(
+            {"$ai_trace_id": doc_id, "$ai_parent_id": f"alignment-{doc_id}"}
+            if doc_id else None
+        ),
     )
 
     log_usage("alignment", response.usage)
diff --git a/packages/backend/app/phases/alignment/contract.py b/packages/backend/app/phases/alignment/contract.py
index 8f2a953..e4a01ae 100644
--- a/packages/backend/app/phases/alignment/contract.py
+++ b/packages/backend/app/phases/alignment/contract.py
@@ -54,6 +54,8 @@ async def extract_document_contract(
     user_preferences: str | None = None,
     db: AsyncSession | None = None,
     document_type_id: uuid.UUID | None = None,
+    posthog_distinct_id: str | None = None,
+    doc_id: str | None = None,
 ) -> dict:
     """Extract a structured document contract from the approved alignment summaries."""
     logger.info("[AI:contract] extracting document contract")
@@ -83,6 +85,11 @@ async def extract_document_contract(
         response_format=CONTRACT_SCHEMA,
         temperature=0.1,
         required_fields=["entities", "decisions", "terminology", "constraints"],
+        posthog_distinct_id=posthog_distinct_id,
+        posthog_properties=(
+            {"$ai_trace_id": doc_id, "$ai_parent_id": f"alignment-{doc_id}"}
+            if doc_id else None
+        ),
     )
 
     log_usage("contract", response.usage)
diff --git a/packages/backend/app/phases/alignment/function.py b/packages/backend/app/phases/alignment/function.py
index 16ded85..55772cf 100644
--- a/packages/backend/app/phases/alignment/function.py
+++ b/packages/backend/app/phases/alignment/function.py
@@ -9,6 +9,7 @@
 from app.phases._shared.concurrency import DOC_CONCURRENCY
 from app.phases._shared.failure import workflow_on_failure
 from app.services import db as db_service
+from app.services.observability import capture_span
 
 
 @inngest_client.create_function(
@@ -21,6 +22,7 @@ async def function(ctx: inngest.Context):
     step = ctx.step
     doc_id = ctx.event.data["document_id"]
     document_type_id = ctx.event.data.get("document_type_id")
+    user_id = ctx.event.data.get("user_id", "")
 
     logger.info("[orchestrator] ALIGNMENT start | doc_id={}", doc_id)
 
@@ -66,6 +68,8 @@ async def _generate_summaries(sc=section_contexts):
                     None,
                     db=db,
                     document_type_id=uuid.UUID(document_type_id) if document_type_id else None,
+                    posthog_distinct_id=user_id,
+                    doc_id=doc_id,
                 )
 
         summaries = await step.run(f"generate-summaries-{iteration}", _generate_summaries)
@@ -105,6 +109,8 @@ async def _extract_contract(s=summaries, sc=section_contexts):
                         user_preferences=doc.user_preferences,
                         db=db,
                         document_type_id=uuid.UUID(document_type_id) if document_type_id else None,
+                        posthog_distinct_id=user_id,
+                        doc_id=doc_id,
                     )
                 import json as _json
                 raw = _json.dumps(contract)
@@ -119,11 +125,22 @@ async def _extract_contract(s=summaries, sc=section_contexts):
                 doc_id,
             )
 
+    async def _capture_phase_span():
+        capture_span(
+            user_id, doc_id,
+            span_id=f"alignment-{doc_id}",
+            span_name="alignment",
+            input_state="Section contexts reviewed",
+            output_state="Alignment approved",
+        )
+
+    await step.run("capture-span-alignment", _capture_phase_span)
+
     logger.info("[orchestrator] emitting alignment.completed | doc_id={}", doc_id)
     await step.send_event(
         "emit-alignment-completed",
         inngest.Event(
             name="docforge/alignment.completed",
-            data={"document_id": doc_id, "document_type_id": document_type_id},
+            data={"document_id": doc_id, "document_type_id": document_type_id, "user_id": user_id},
         ),
     )
diff --git a/packages/backend/app/phases/audit/ai.py b/packages/backend/app/phases/audit/ai.py
index c71e727..bdac65b 100644
--- a/packages/backend/app/phases/audit/ai.py
+++ b/packages/backend/app/phases/audit/ai.py
@@ -88,7 +88,7 @@ def build_audit_context(
     return "\n\n".join(parts)
 
 
-async def run_audit(doc_id: str, document_type_id: str | None = None) -> dict:
+async def run_audit(doc_id: str, document_type_id: str | None = None, posthog_distinct_id: str | None = None) -> dict:
     """Run audit on all 4 finalized sections."""
     logger.info("[AI:audit] run_audit | doc_id={}", doc_id)
     from app.services import db as db_service
@@ -129,6 +129,11 @@ async def run_audit(doc_id: str, document_type_id: str | None = None) -> dict:
         response_format=AUDIT_SCHEMA,
         temperature=0.2,
         required_fields=["has_problems", "problems"],
+        posthog_distinct_id=posthog_distinct_id,
+        posthog_properties=(
+            {"$ai_trace_id": doc_id, "$ai_parent_id": f"audit-{doc_id}"}
+            if posthog_distinct_id else None
+        ),
     )
 
     log_usage("audit", response.usage)
diff --git a/packages/backend/app/phases/audit/function.py b/packages/backend/app/phases/audit/function.py
index 4e1022d..798a017 100644
--- a/packages/backend/app/phases/audit/function.py
+++ b/packages/backend/app/phases/audit/function.py
@@ -8,6 +8,7 @@
 from app.phases._shared.concurrency import DOC_CONCURRENCY
 from app.phases._shared.failure import workflow_on_failure
 from app.services import db as db_service
+from app.services.observability import capture_span
 
 
 @inngest_client.create_function(
@@ -20,6 +21,7 @@ async def function(ctx: inngest.Context):
     step = ctx.step
     doc_id = ctx.event.data["document_id"]
     document_type_id = ctx.event.data.get("document_type_id")
+    user_id = ctx.event.data.get("user_id", "")
 
     logger.info("[orchestrator] AUDIT start | doc_id={}", doc_id)
 
@@ -31,7 +33,7 @@ async def _set_audit():
 
     async def _run_audit():
         from app.phases.audit.ai import run_audit
-        return await run_audit(doc_id, document_type_id=document_type_id)
+        return await run_audit(doc_id, document_type_id=document_type_id, posthog_distinct_id=user_id)
 
     result = await step.run("run-audit", _run_audit)
 
@@ -55,10 +57,23 @@ async def _save_findings(r=result):
 
     await step.run("save-findings", _save_findings)
 
+    async def _capture_phase_span(r=result):
+        problems = r.get("problems", [])
+        output = f"Audit complete. {len(problems)} issue(s) found." if problems else "Audit complete. No issues found."
+        capture_span(
+            user_id, doc_id,
+            span_id=f"audit-{doc_id}",
+            span_name="audit",
+            input_state="Document sections reviewed",
+            output_state=output,
+        )
+
+    await step.run("capture-span-audit", _capture_phase_span)
+
     await step.send_event(
         "emit-audit-completed",
         inngest.Event(
             name="docforge/document.audit_completed",
-            data={"document_id": doc_id, "document_type_id": document_type_id},
+            data={"document_id": doc_id, "document_type_id": document_type_id, "user_id": user_id},
         ),
     )
diff --git a/packages/backend/app/phases/completion/function.py b/packages/backend/app/phases/completion/function.py
index 7445401..48ae8df 100644
--- a/packages/backend/app/phases/completion/function.py
+++ b/packages/backend/app/phases/completion/function.py
@@ -6,6 +6,7 @@
 from app.phases._shared.concurrency import DOC_CONCURRENCY
 from app.phases._shared.failure import workflow_on_failure
 from app.services import db as db_service
+from app.services.observability import capture_trace
 
 
 @inngest_client.create_function(
@@ -17,6 +18,7 @@
 async def function(ctx: inngest.Context):
     step = ctx.step
     doc_id = ctx.event.data["document_id"]
+    user_id = ctx.event.data.get("user_id", "")
 
     logger.info("[orchestrator] COMPLETED | doc_id={}", doc_id)
 
@@ -25,3 +27,8 @@ async def _set_completed():
             await db_service.set_phase(db, doc_id, "completed")
 
     await step.run("set-phase-completed", _set_completed)
+
+    async def _close_trace():
+        capture_trace(user_id, doc_id, output_state="Document complete")
+
+    await step.run("capture-trace-complete", _close_trace)
diff --git a/packages/backend/app/phases/discovery/ai.py b/packages/backend/app/phases/discovery/ai.py
index 2977b13..c8f5f9f 100644
--- a/packages/backend/app/phases/discovery/ai.py
+++ b/packages/backend/app/phases/discovery/ai.py
@@ -59,6 +59,8 @@ async def analyze_discovery(
     section_role: str,
     db: AsyncSession,
     document_type_id: uuid.UUID | None,
+    posthog_distinct_id: str | None = None,
+    doc_id: str | None = None,
 ) -> dict:
     """Analyze if context is sufficient for a specific section, or generate follow-up questions."""
     logger.info(
@@ -80,6 +82,11 @@ async def analyze_discovery(
         response_format=DISCOVERY_SCHEMA,
         temperature=0.3,
         required_fields=["is_sufficient", "follow_up_questions"],
+        posthog_distinct_id=posthog_distinct_id,
+        posthog_properties=(
+            {"$ai_trace_id": doc_id, "$ai_parent_id": f"discovery-{section_key}-{doc_id}"}
+            if doc_id else None
+        ),
     )
 
     log_usage("discovery", response.usage)
diff --git a/packages/backend/app/phases/discovery/function.py b/packages/backend/app/phases/discovery/function.py
index 08aa8ab..77fbf7e 100644
--- a/packages/backend/app/phases/discovery/function.py
+++ b/packages/backend/app/phases/discovery/function.py
@@ -12,6 +12,7 @@
 from app.phases._shared.concurrency import DOC_CONCURRENCY
 from app.phases._shared.failure import workflow_on_failure
 from app.services import db as db_service
+from app.services.observability import capture_span
 
 
 @inngest_client.create_function(
@@ -26,6 +27,7 @@ async def function(ctx: inngest.Context):
     document_context = ctx.event.data["document_context"]
     user_preferences = ctx.event.data["user_preferences"]
     document_type_id = ctx.event.data.get("document_type_id")
+    user_id = ctx.event.data.get("user_id", "")
 
     logger.info("[orchestrator] DISCOVERY start | doc_id={}", doc_id)
 
@@ -104,6 +106,8 @@ async def _analyze():
                         section_role=sr,
                         db=db,
                         document_type_id=uuid.UUID(document_type_id) if document_type_id else None,
+                        posthog_distinct_id=user_id,
+                        doc_id=doc_id,
                     )
             return _analyze
 
@@ -182,11 +186,34 @@ async def _save_context(sid=section_id_str, ctx_text=context_to_save):
 
         await step.run(f"save-context-{section_key}", _save_context)
 
+        async def _capture_section_span(sk=section_key, ctx_text=context_to_save):
+            capture_span(
+                user_id, doc_id,
+                span_id=f"discovery-{sk}-{doc_id}",
+                span_name=sk,
+                parent_id=f"discovery-{doc_id}",
+                input_state=document_context,
+                output_state=ctx_text[:1000] if ctx_text else "",
+            )
+
+        await step.run(f"capture-span-discovery-{section_key}", _capture_section_span)
+
+    async def _capture_phase_span():
+        capture_span(
+            user_id, doc_id,
+            span_id=f"discovery-{doc_id}",
+            span_name="discovery",
+            input_state=document_context,
+            output_state="Discovery complete",
+        )
+
+    await step.run("capture-span-discovery", _capture_phase_span)
+
     logger.info("[orchestrator] emitting discovery.completed | doc_id={}", doc_id)
     await step.send_event(
         "emit-discovery-completed",
         inngest.Event(
             name="docforge/discovery.completed",
-            data={"document_id": doc_id, "document_type_id": document_type_id},
+            data={"document_id": doc_id, "document_type_id": document_type_id, "user_id": user_id},
         ),
     )
diff --git a/packages/backend/app/phases/generation/ai.py b/packages/backend/app/phases/generation/ai.py
index 5df243d..71c4a4a 100644
--- a/packages/backend/app/phases/generation/ai.py
+++ b/packages/backend/app/phases/generation/ai.py
@@ -93,6 +93,8 @@ async def generate_section(
     document_contract: dict | None = None,
     db: AsyncSession | None = None,
     document_type_id: uuid.UUID | None = None,
+    posthog_distinct_id: str | None = None,
+    doc_id: str | None = None,
 ) -> str:
     """Generate full markdown content for a section."""
     logger.info("[AI:generation] generating section | type={}", section_type)
@@ -109,6 +111,11 @@ async def generate_section(
             {"role": "user", "content": user_content},
         ],
         temperature=0.5,
+        posthog_distinct_id=posthog_distinct_id,
+        posthog_properties=(
+            {"$ai_trace_id": doc_id, "$ai_parent_id": f"generation-{section_type}-{doc_id}"}
+            if doc_id else None
+        ),
     )
 
     log_usage("generation", response.usage, section_type=section_type)
@@ -121,7 +128,7 @@ async def generate_section(
     return content
 
 
-async def refine_cross_references(doc_id: str, document_type_id: str | None = None) -> None:
+async def refine_cross_references(doc_id: str, document_type_id: str | None = None, posthog_distinct_id: str | None = None) -> None:
     """Run a coherence pass on all sections to ensure cross-references are accurate."""
     from app.database import async_session
     from app.services import db as db_service
@@ -175,6 +182,11 @@ async def refine_cross_references(doc_id: str, document_type_id: str | None = No
                 section_type=section_type,
                 messages=messages,
                 temperature=0.2,
+                posthog_distinct_id=posthog_distinct_id,
+                posthog_properties=(
+                    {"$ai_trace_id": doc_id, "$ai_parent_id": f"generation-{section_type}-{doc_id}"}
+                    if posthog_distinct_id else None
+                ),
             )
 
             log_usage("generation:coherence", response.usage, section_type=section_type)
diff --git a/packages/backend/app/phases/generation/function.py b/packages/backend/app/phases/generation/function.py
index 7405f82..69c81d4 100644
--- a/packages/backend/app/phases/generation/function.py
+++ b/packages/backend/app/phases/generation/function.py
@@ -9,6 +9,7 @@
 from app.phases._shared.failure import workflow_on_failure
 from app.phases.generation.helpers import generate_section_root
 from app.services import db as db_service
+from app.services.observability import capture_span
 
 
 @inngest_client.create_function(
@@ -21,6 +22,7 @@ async def function(ctx: inngest.Context):
     step = ctx.step
     doc_id = ctx.event.data["document_id"]
     document_type_id = ctx.event.data.get("document_type_id")
+    user_id = ctx.event.data.get("user_id", "")
 
     logger.info("[orchestrator] GENERATION start | doc_id={}", doc_id)
 
@@ -50,20 +52,39 @@ async def _get_section_order():
     for section_key in section_order:
         async def _generate(sk=section_key):
             logger.info("[orchestrator] generating section {} | doc_id={}", sk, doc_id)
-            await generate_section_root(doc_id, sk)
+            content = await generate_section_root(doc_id, sk, posthog_distinct_id=user_id)
+            capture_span(
+                user_id, doc_id,
+                span_id=f"generation-{sk}-{doc_id}",
+                span_name=sk,
+                parent_id=f"generation-{doc_id}",
+                input_state=f"Generate section: {sk}",
+                output_state=content[:1000] if content else "",
+            )
         await step.run(f"generate-{section_key}", _generate)
 
     async def _coherence_pass():
         from app.phases.generation.ai import refine_cross_references
-        await refine_cross_references(doc_id, document_type_id=document_type_id)
+        await refine_cross_references(doc_id, document_type_id=document_type_id, posthog_distinct_id=user_id)
 
     await step.run("coherence-pass", _coherence_pass)
 
+    async def _capture_phase_span():
+        capture_span(
+            user_id, doc_id,
+            span_id=f"generation-{doc_id}",
+            span_name="generation",
+            input_state="Sections generated",
+            output_state="Generation complete",
+        )
+
+    await step.run("capture-span-generation", _capture_phase_span)
+
     logger.info("[orchestrator] emitting generation.completed | doc_id={}", doc_id)
     await step.send_event(
         "emit-generation-completed",
         inngest.Event(
             name="docforge/generation.completed",
-            data={"document_id": doc_id, "document_type_id": document_type_id},
+            data={"document_id": doc_id, "document_type_id": document_type_id, "user_id": user_id},
         ),
     )
diff --git a/packages/backend/app/phases/generation/helpers.py b/packages/backend/app/phases/generation/helpers.py
index 0584225..6a1afc2 100644
--- a/packages/backend/app/phases/generation/helpers.py
+++ b/packages/backend/app/phases/generation/helpers.py
@@ -45,8 +45,12 @@ async def _build_cross_section_context_from_db(db, doc_id: uuid.UUID, target_typ
     return _build_cross_section_context(sections, target_type)
 
 
-async def generate_section_root(doc_id: str, section_type: str) -> None:
-    """Generate the initial version of a section using AI."""
+async def generate_section_root(
+    doc_id: str,
+    section_type: str,
+    posthog_distinct_id: str | None = None,
+) -> str:
+    """Generate the initial version of a section using AI. Returns the generated content."""
     from app.phases.generation.ai import generate_section
 
     logger.info("[helpers] generate_section_root | doc_id={} type={}", doc_id, section_type)
@@ -54,7 +58,7 @@ async def generate_section_root(doc_id: str, section_type: str) -> None:
         doc = await db_service.get_document_detail(db, uuid.UUID(doc_id))
         section = next((s for s in doc.sections if s.section_type == section_type), None)
         if not section:
-            return
+            return ""
 
         cross_section_context = _build_cross_section_context(doc.sections, section_type)
 
@@ -77,6 +81,8 @@ async def generate_section_root(doc_id: str, section_type: str) -> None:
             document_contract=contract_dict,
             db=db,
             document_type_id=doc.document_type_id,
+            posthog_distinct_id=posthog_distinct_id,
+            doc_id=doc_id,
         )
         content = clean_section_output(content, section_type)
 
@@ -92,3 +98,4 @@ async def generate_section_root(doc_id: str, section_type: str) -> None:
             section_type,
             len(content or ""),
         )
+        return content or ""
diff --git a/packages/backend/app/phases/refinement/ai.py b/packages/backend/app/phases/refinement/ai.py
index eec6288..063eacc 100644
--- a/packages/backend/app/phases/refinement/ai.py
+++ b/packages/backend/app/phases/refinement/ai.py
@@ -154,6 +154,8 @@ async def refine_section(
     document_contract: dict | None = None,
     db: AsyncSession | None = None,
     document_type_id: uuid.UUID | None = None,
+    posthog_distinct_id: str | None = None,
+    doc_id: str | None = None,
 ) -> dict:
     """Process a refinement interaction using function calling."""
     logger.info(
@@ -184,6 +186,11 @@ async def refine_section(
         tools=REFINEMENT_TOOLS,
         tool_choice=tool_choice,
         temperature=0.4,
+        posthog_distinct_id=posthog_distinct_id,
+        posthog_properties=(
+            {"$ai_trace_id": doc_id, "$ai_parent_id": f"refinement-{section_type}-{doc_id}"}
+            if doc_id else None
+        ),
     )
 
     log_usage("refinement", response.usage, section_type=section_type)
diff --git a/packages/backend/app/phases/refinement/function.py b/packages/backend/app/phases/refinement/function.py
index fdfd6b4..392bfd8 100644
--- a/packages/backend/app/phases/refinement/function.py
+++ b/packages/backend/app/phases/refinement/function.py
@@ -9,6 +9,7 @@
 from app.phases._shared.failure import workflow_on_failure
 from app.phases.refinement.helpers import process_edit, process_question
 from app.services import db as db_service
+from app.services.observability import capture_span
 
 
 @inngest_client.create_function(
@@ -21,6 +22,7 @@ async def start_function(ctx: inngest.Context):
     """Set up refinement phase. Actions are handled by action_function."""
     step = ctx.step
     doc_id = ctx.event.data["document_id"]
+    user_id = ctx.event.data.get("user_id", "")
 
     logger.info("[orchestrator] REFINEMENT start | doc_id={}", doc_id)
 
@@ -31,6 +33,26 @@ async def _set_refinement():
 
     await step.run("set-phase-refinement", _set_refinement)
 
+    async def _capture_refinement_spans():
+        async with async_session() as db:
+            doc = await db_service.get_document_detail(db, doc_id)
+            capture_span(
+                user_id, doc_id,
+                span_id=f"refinement-{doc_id}",
+                span_name="refinement",
+                input_state="User refinement phase started",
+            )
+            for section in doc.sections:
+                capture_span(
+                    user_id, doc_id,
+                    span_id=f"refinement-{section.section_type}-{doc_id}",
+                    span_name=section.section_type,
+                    parent_id=f"refinement-{doc_id}",
+                    input_state="Awaiting user edits",
+                )
+
+    await step.run("capture-span-refinement", _capture_refinement_spans)
+
 
 @inngest_client.create_function(
     fn_id="handle-section-action",
@@ -50,6 +72,7 @@ async def action_function(ctx: inngest.Context):
     doc_id = ctx.event.data["document_id"]
     section_id = ctx.event.data["section_id"]
     action = ctx.event.data["action_type"]
+    user_id = ctx.event.data.get("user_id", "")
 
     logger.info(
         "[orchestrator] section action | doc_id={} section_id={} action={}",
@@ -60,12 +83,12 @@ async def action_function(ctx: inngest.Context):
 
     if action == "request_edit":
         async def _apply_edit():
-            await process_edit(section_id, ctx.event.data["prompt"])
+            await process_edit(section_id, ctx.event.data["prompt"], posthog_distinct_id=user_id)
         await step.run("apply-edit", _apply_edit)
 
     elif action == "ask_question":
         async def _answer_question():
-            await process_question(section_id, ctx.event.data["message"])
+            await process_question(section_id, ctx.event.data["message"], posthog_distinct_id=user_id)
         await step.run("answer-question", _answer_question)
 
     elif action == "finalize":
@@ -91,6 +114,6 @@ async def _check_finalized():
                 "emit-refinement-completed",
                 inngest.Event(
                     name="docforge/document.refinement_completed",
-                    data={"document_id": doc_id, "document_type_id": doc_type_id},
+                    data={"document_id": doc_id, "document_type_id": doc_type_id, "user_id": user_id},
                 ),
             )
diff --git a/packages/backend/app/phases/refinement/helpers.py b/packages/backend/app/phases/refinement/helpers.py
index e39d10b..347924b 100644
--- a/packages/backend/app/phases/refinement/helpers.py
+++ b/packages/backend/app/phases/refinement/helpers.py
@@ -78,7 +78,7 @@ async def _build_cross_section_context_from_db(db, doc_id: uuid.UUID, target_typ
     return _build_cross_section_context(sections, target_type)
 
 
-async def process_edit(section_id: str, prompt: str) -> None:
+async def process_edit(section_id: str, prompt: str, posthog_distinct_id: str | None = None) -> None:
     """Process an edit request via AI refinement."""
     from app.phases.refinement.ai import refine_section
 
@@ -95,6 +95,8 @@ async def process_edit(section_id: str, prompt: str) -> None:
             return
 
         doc = section.document
+        _phog_id = posthog_distinct_id or str(doc.user_id)
+        _doc_id = str(doc.id)
         cross_context = _build_cross_section_context_from_db(db, doc.id, section.section_type)
         chat_history = await _get_chat_history(db, section.id)
         contract_dict = await _get_contract_dict(db, doc.id)
@@ -102,7 +104,15 @@ async def process_edit(section_id: str, prompt: str) -> None:
         await db_service.add_chat_message(db, doc.id, section.id, "user", prompt)
 
         from app.guardrails import validate_message_intent
-        intent_err = await validate_message_intent(prompt, section.section_type, section.summary)
+        intent_err = await validate_message_intent(
+            prompt, section.section_type, section.summary,
+            posthog_distinct_id=_phog_id,
+            posthog_properties={
+                "$ai_trace_id": _doc_id,
+                "$ai_parent_id": f"refinement-{section.section_type}-{_doc_id}",
+                "$ai_span_name": "edit-guardrail",
+            },
+        )
         if intent_err:
             await db_service.add_chat_message(db, doc.id, section.id, "agent", intent_err.message)
             return
@@ -120,6 +130,8 @@ async def process_edit(section_id: str, prompt: str) -> None:
                 document_contract=contract_dict,
                 db=db,
                 document_type_id=doc.document_type_id,
+                posthog_distinct_id=_phog_id,
+                doc_id=_doc_id,
             )
         except BadRequestError as exc:
             body = exc.body if isinstance(exc.body, dict) else {}
@@ -155,7 +167,7 @@ async def process_edit(section_id: str, prompt: str) -> None:
             await db_service.add_chat_message(db, doc.id, section.id, "agent", ai_result["reply"])
 
 
-async def process_question(section_id: str, message: str) -> None:
+async def process_question(section_id: str, message: str, posthog_distinct_id: str | None = None) -> None:
     """Process a question about a section via AI."""
     from app.phases.refinement.ai import refine_section
 
@@ -172,6 +184,8 @@ async def process_question(section_id: str, message: str) -> None:
             return
 
         doc = section.document
+        _phog_id = posthog_distinct_id or str(doc.user_id)
+        _doc_id = str(doc.id)
         cross_context = _build_cross_section_context_from_db(db, doc.id, section.section_type)
         chat_history = await _get_chat_history(db, section.id)
         contract_dict = await _get_contract_dict(db, doc.id)
@@ -179,7 +193,15 @@ async def process_question(section_id: str, message: str) -> None:
         await db_service.add_chat_message(db, doc.id, section.id, "user", message)
 
         from app.guardrails import validate_message_intent
-        intent_err = await validate_message_intent(message, section.section_type, section.summary)
+        intent_err = await validate_message_intent(
+            message, section.section_type, section.summary,
+            posthog_distinct_id=_phog_id,
+            posthog_properties={
+                "$ai_trace_id": _doc_id,
+                "$ai_parent_id": f"refinement-{section.section_type}-{_doc_id}",
+                "$ai_span_name": "question-guardrail",
+            },
+        )
         if intent_err:
             await db_service.add_chat_message(db, doc.id, section.id, "agent", intent_err.message)
             return
@@ -197,6 +219,8 @@ async def process_question(section_id: str, message: str) -> None:
                 document_contract=contract_dict,
                 db=db,
                 document_type_id=doc.document_type_id,
+                posthog_distinct_id=_phog_id,
+                doc_id=_doc_id,
             )
         except BadRequestError as exc:
             body = exc.body if isinstance(exc.body, dict) else {}
diff --git a/packages/backend/app/routers/documents.py b/packages/backend/app/routers/documents.py
index 7b37892..490b9b7 100644
--- a/packages/backend/app/routers/documents.py
+++ b/packages/backend/app/routers/documents.py
@@ -19,6 +19,7 @@
     validate_document_context,
     validate_refinement_message,
 )
+from app.services.observability import capture_trace
 from app.inngest_client import inngest_client
 from app.models import (
     AuditFinding,
@@ -256,6 +257,7 @@ async def create_document(
     await db.commit()
 
     # Dispatch Inngest event
+    capture_trace(str(current_user.id), str(doc.id), span_name=doc.title, input_state=payload.document_context)
     try:
         await inngest_client.send(
             inngest.Event(
@@ -265,6 +267,7 @@ async def create_document(
                     "document_context": payload.document_context,
                     "user_preferences": payload.user_preferences or "",
                     "document_type_id": str(doc_type.id),
+                    "user_id": str(current_user.id),
                 },
             )
         )
@@ -474,7 +477,7 @@ async def dispatch_event(
                     detail="Message limit reached for this section (10/10).",
                 )
 
-    event_data = {**payload.data, "document_id": str(document_id)}
+    event_data = {**payload.data, "document_id": str(document_id), "user_id": str(current_user.id)}
 
     try:
         await inngest_client.send(
diff --git a/packages/backend/app/services/observability.py b/packages/backend/app/services/observability.py
new file mode 100644
index 0000000..8235122
--- /dev/null
+++ b/packages/backend/app/services/observability.py
@@ -0,0 +1,48 @@
+"""PostHog AI observability helpers — trace and span capture for document workflows."""
+from app.ai.core.client import posthog_client
+
+
+def capture_trace(
+    distinct_id: str,
+    doc_id: str,
+    *,
+    span_name: str | None = None,
+    input_state: str | None = None,
+    output_state: str | None = None,
+) -> None:
+    if posthog_client is None:
+        return
+    properties: dict = {"$ai_trace_id": doc_id}
+    if span_name is not None:
+        properties["$ai_span_name"] = span_name
+    if input_state is not None:
+        properties["$ai_input_state"] = input_state
+    if output_state is not None:
+        properties["$ai_output_state"] = output_state
+    posthog_client.capture(distinct_id=distinct_id, event="$ai_trace", properties=properties)
+
+
+def capture_span(
+    distinct_id: str,
+    doc_id: str,
+    span_id: str,
+    span_name: str,
+    *,
+    parent_id: str | None = None,
+    input_state: str | None = None,
+    output_state: str | None = None,
+) -> None:
+    if posthog_client is None:
+        return
+    properties: dict = {
+        "$ai_trace_id": doc_id,
+        "$ai_span_id": span_id,
+        "$ai_span_name": span_name,
+    }
+    if parent_id is not None:
+        properties["$ai_parent_id"] = parent_id
+    if input_state is not None:
+        properties["$ai_input_state"] = input_state
+    if output_state is not None:
+        properties["$ai_output_state"] = output_state
+    posthog_client.capture(distinct_id=distinct_id, event="$ai_span", properties=properties)
diff --git a/packages/backend/pyproject.toml b/packages/backend/pyproject.toml
index 3a574d8..74c0e09 100644
--- a/packages/backend/pyproject.toml
+++ b/packages/backend/pyproject.toml
@@ -20,6 +20,7 @@ dependencies = [
     "python-jose[cryptography]>=3.3.0",
     "httpx>=0.27.0",
     "pyyaml>=6.0.0",
+    "posthog>=7.16.2",
 ]
 
 [project.optional-dependencies]
diff --git a/packages/frontend/.env.example b/packages/frontend/.env.example
index cb94f12..8e5fdaa 100644
--- a/packages/frontend/.env.example
+++ b/packages/frontend/.env.example
@@ -1,2 +1,6 @@
 VITE_API_BASE=http://localhost:8000/api
 VITE_CLERK_PUBLISHABLE_KEY=pk_test_...
+
+# PostHog analytics (optional — leave blank to disable)
+VITE_POSTHOG_KEY=
+VITE_POSTHOG_HOST=https://us.i.posthog.com
diff --git a/packages/frontend/package.json b/packages/frontend/package.json
index ddb393f..79dd15a 100644
--- a/packages/frontend/package.json
+++ b/packages/frontend/package.json
@@ -24,6 +24,7 @@
     "react-router-dom": "^7.14.2",
     "remark-gfm": "^4.0.1",
     "tailwind-merge": "^3.0.2",
+    "posthog-js": "^1.240.0",
     "zustand": "^5.0.12"
   },
   "devDependencies": {
diff --git a/packages/frontend/src/App.tsx b/packages/frontend/src/App.tsx
index ee2fb38..1283cdf 100644
--- a/packages/frontend/src/App.tsx
+++ b/packages/frontend/src/App.tsx
@@ -1,7 +1,12 @@
+import { useState } from "react";
+import posthog from "posthog-js";
+import { PostHogProvider } from "posthog-js/react";
 import { BrowserRouter, Routes, Route } from "react-router-dom";
 import { ClerkProvider } from "@clerk/clerk-react";
 import { HomePage, DocumentPage, LoadingPage, LandingPage, LegalPage, HowItWorksPage, PricingPage, McpPage, BillingPage } from "./pages";
 import { ProtectedRoute } from "./components/shared";
+import CookieConsentBanner from "./components/shared/CookieConsentBanner";
+import { useClerkPosthogIdentity } from "./hooks/useClerkPosthogIdentity";
 
 const CLERK_PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY as string;
 
@@ -9,24 +14,49 @@ if (!CLERK_PUBLISHABLE_KEY) {
   throw new Error("VITE_CLERK_PUBLISHABLE_KEY is not set");
 }
 
+if (import.meta.env.VITE_POSTHOG_KEY) {
+  posthog.init(import.meta.env.VITE_POSTHOG_KEY as string, {
+    api_host: (import.meta.env.VITE_POSTHOG_HOST as string) ?? "https://us.i.posthog.com",
+    opt_out_capturing_by_default: true,
+    capture_pageview: true,
+    capture_pageleave: true,
+    session_recording: {
+      maskTextSelector: "[data-ph-mask], .editor-content, .markdown-preview",
+    },
+  });
+}
+
+function AppInner() {
+  const [consentGiven, setConsentGiven] = useState(false);
+  useClerkPosthogIdentity(consentGiven);
+  return (
+    <>
+      <CookieConsentBanner onOptIn={() => setConsentGiven(true)} />
+      <Routes>
+        <Route path="/" element={<LandingPage />} />
+        <Route path="/how-it-works" element={<HowItWorksPage />} />
+        <Route path="/pricing" element={<PricingPage />} />
+        <Route path="/legal/:doc" element={<LegalPage />} />
+        <Route element={<ProtectedRoute />}>
+          <Route path="/home" element={<HomePage />} />
+          <Route path="/mcp" element={<McpPage />} />
+          <Route path="/billing" element={<BillingPage />} />
+          <Route path="/document/:id" element={<DocumentPage />} />
+          <Route path="/loading/forge" element={<LoadingPage />} />
+        </Route>
+      </Routes>
+    </>
+  );
+}
+
 export default function App() {
   return (
-    <ClerkProvider publishableKey={CLERK_PUBLISHABLE_KEY}>
-      <BrowserRouter>
-        <Routes>
-          <Route path="/" element={<LandingPage />} />
-          <Route path="/how-it-works" element={<HowItWorksPage />} />
-          <Route path="/pricing" element={<PricingPage />} />
-          <Route path="/legal/:doc" element={<LegalPage />} />
-          <Route element={<ProtectedRoute />}>
-            <Route path="/home" element={<HomePage />} />
-            <Route path="/mcp" element={<McpPage />} />
-            <Route path="/billing" element={<BillingPage />} />
-            <Route path="/document/:id" element={<DocumentPage />} />
-            <Route path="/loading/forge" element={<LoadingPage />} />
-          </Route>
-        </Routes>
-      </BrowserRouter>
-    </ClerkProvider>
+    <PostHogProvider client={posthog}>
+      <ClerkProvider publishableKey={CLERK_PUBLISHABLE_KEY}>
+        <BrowserRouter>
+          <AppInner />
+        </BrowserRouter>
+      </ClerkProvider>
+    </PostHogProvider>
   );
 }
diff --git a/packages/frontend/src/components/phases/discovery/InitialInput.tsx b/packages/frontend/src/components/phases/discovery/InitialInput.tsx
index 6d51f04..8c5e833 100644
--- a/packages/frontend/src/components/phases/discovery/InitialInput.tsx
+++ b/packages/frontend/src/components/phases/discovery/InitialInput.tsx
@@ -77,6 +77,7 @@ export function InitialInput({ onSubmit }: InitialInputProps) {
             Describe the problem your document solves. The more detail, the better.
           </p>
           <textarea
+            data-ph-mask
             value={context}
             onChange={(e) => setContext(e.target.value)}
             onFocus={() => setActiveField("context")}
@@ -142,6 +143,7 @@ export function InitialInput({ onSubmit }: InitialInputProps) {
             Tone, format, target audience, and any specific instructions.
           </p>
           <textarea
+            data-ph-mask
             value={preferences}
             onChange={(e) => setPreferences(e.target.value)}
             onFocus={() => setActiveField("preferences")}
diff --git a/packages/frontend/src/components/phases/editor/EditorCenterPanel.tsx b/packages/frontend/src/components/phases/editor/EditorCenterPanel.tsx
index e8eb70c..43620c8 100644
--- a/packages/frontend/src/components/phases/editor/EditorCenterPanel.tsx
+++ b/packages/frontend/src/components/phases/editor/EditorCenterPanel.tsx
@@ -112,7 +112,7 @@ export function EditorCenterPanel({
       <div
         ref={scrollRef}
         style={{ flex: 1, overflowY: "auto" }}
-        className="hide-scrollbar"
+        className="hide-scrollbar editor-content"
       >
         <div style={{ maxWidth: 720, margin: "0 auto", padding: "40px 56px 80px" }}>
           {mode === "preview" ? (
diff --git a/packages/frontend/src/components/shared/CookieConsentBanner.tsx b/packages/frontend/src/components/shared/CookieConsentBanner.tsx
new file mode 100644
index 0000000..9ad81ee
--- /dev/null
+++ b/packages/frontend/src/components/shared/CookieConsentBanner.tsx
@@ -0,0 +1,53 @@
+import { useState } from "react";
+import posthog from "posthog-js";
+
+const CONSENT_KEY = "docforge_cookie_consent";
+
+interface CookieConsentBannerProps {
+  onOptIn?: () => void;
+}
+
+export default function CookieConsentBanner({ onOptIn }: CookieConsentBannerProps) {
+  const [visible, setVisible] = useState(
+    () => localStorage.getItem(CONSENT_KEY) === null
+  );
+
+  if (!visible) return null;
+
+  function handleAccept() {
+    localStorage.setItem(CONSENT_KEY, "accepted");
+    posthog.opt_in_capturing();
+    posthog.startSessionRecording();
+    onOptIn?.();
+    setVisible(false);
+  }
+
+  function handleDecline() {
+    localStorage.setItem(CONSENT_KEY, "declined");
+    posthog.opt_out_capturing();
+    setVisible(false);
+  }
+
+  return (
+    <div className="fixed bottom-0 left-0 right-0 z-50 flex items-center justify-between gap-4 bg-surface border-t border-outline/20 px-6 py-4 shadow-lg">
+      <p className="text-sm text-on-surface/80">
+        We use analytics to understand how DocForge is used and improve the product.
+        No document content is shared.
+      </p>
+      <div className="flex shrink-0 gap-2">
+        <button
+          onClick={handleDecline}
+          className="rounded-md px-4 py-2 text-sm text-on-surface/60 hover:text-on-surface transition-colors"
+        >
+          Decline
+        </button>
+        <button
+          onClick={handleAccept}
+          className="rounded-md bg-primary px-4 py-2 text-sm font-medium text-on-primary hover:bg-primary/90 transition-colors"
+        >
+          Accept
+        </button>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/frontend/src/components/shared/MarkdownRenderer.tsx b/packages/frontend/src/components/shared/MarkdownRenderer.tsx
index 1fa0f51..b62531b 100644
--- a/packages/frontend/src/components/shared/MarkdownRenderer.tsx
+++ b/packages/frontend/src/components/shared/MarkdownRenderer.tsx
@@ -127,7 +127,7 @@ export function MarkdownRenderer({
   const isEditor = variant === "editor";
 
   return (
-    <article className={cn("w-full", className)}>
+    <article className={cn("w-full markdown-preview", className)}>
       <ReactMarkdown
         remarkPlugins={[remarkGfm]}
         components={{
diff --git a/packages/frontend/src/components/shared/NewDocumentDialog.tsx b/packages/frontend/src/components/shared/NewDocumentDialog.tsx
index 0174f4a..211ed73 100644
--- a/packages/frontend/src/components/shared/NewDocumentDialog.tsx
+++ b/packages/frontend/src/components/shared/NewDocumentDialog.tsx
@@ -1,6 +1,7 @@
 import { useEffect, useState } from "react";
 import { useNavigate } from "react-router-dom";
 import { useAuth } from "@clerk/clerk-react";
+import posthog from "posthog-js";
 import { apiListDocumentTypes, apiCreateDocument } from "@/utils/api";
 import type { DocumentType } from "@/types";
 
@@ -49,6 +50,7 @@ export function NewDocumentDialog({ onClose, credits }: NewDocumentDialogProps)
 
   function handleSelectGuided(doc: DocumentType) {
     if (!canAffordGuided) return;
+    posthog.capture("document_created", { mode: "guided", document_type_slug: doc.slug });
     onClose();
     navigate("/document/new", { state: { documentTypeSlug: doc.slug, documentTitle: documentTitle.trim() || null } });
   }
@@ -66,6 +68,7 @@ export function NewDocumentDialog({ onClose, credits }: NewDocumentDialogProps)
         undefined,
         "editor",
       );
+      posthog.capture("document_created", { mode: "editor" });
       onClose();
       navigate(`/document/${doc.id}`);
     } catch (err) {
diff --git a/packages/frontend/src/hooks/useClerkPosthogIdentity.ts b/packages/frontend/src/hooks/useClerkPosthogIdentity.ts
new file mode 100644
index 0000000..18cf427
--- /dev/null
+++ b/packages/frontend/src/hooks/useClerkPosthogIdentity.ts
@@ -0,0 +1,17 @@
+import { useEffect } from "react";
+import { useUser } from "@clerk/clerk-react";
+import posthog from "posthog-js";
+
+export function useClerkPosthogIdentity(consentGiven?: boolean) {
+  const { user, isSignedIn } = useUser();
+
+  useEffect(() => {
+    if (isSignedIn && user) {
+      posthog.identify(user.id, {
+        email: user.primaryEmailAddress?.emailAddress,
+      });
+    } else if (isSignedIn === false) {
+      posthog.reset();
+    }
+  }, [isSignedIn, user, consentGiven]);
+}
diff --git a/packages/frontend/src/pages/DocumentPage.tsx b/packages/frontend/src/pages/DocumentPage.tsx
index 1998d5f..44c816a 100644
--- a/packages/frontend/src/pages/DocumentPage.tsx
+++ b/packages/frontend/src/pages/DocumentPage.tsx
@@ -1,6 +1,7 @@
 import { useParams, useNavigate, useLocation } from "react-router-dom";
-import { useState, useCallback } from "react";
+import { useState, useCallback, useEffect } from "react";
 import { useAuth } from "@clerk/clerk-react";
+import posthog from "posthog-js";
 import type { Phase } from "@/types";
 import { useDocument } from "@/hooks/useDocument";
 import { usePhase } from "@/hooks/usePhase";
@@ -34,6 +35,11 @@ export function DocumentPage() {
   const currentPhase: Phase = document?.currentPhase ?? "discovery";
   const { config } = usePhase(currentPhase);
 
+  useEffect(() => {
+    if (!activeDocId) return;
+    posthog.capture("phase_entered", { to_phase: currentPhase, document_id: activeDocId });
+  }, [currentPhase, activeDocId]);
+
   const handleRenameTitle = useCallback(async (title: string) => {
     if (!activeDocId) return;
     await apiUpdateDocumentTitle(activeDocId, title, getToken);

From 2936deab85c60a68902f7f1896ca4723c471f75b Mon Sep 17 00:00:00 2001
From: maxjneto <maxjneto@gmail.com>
Date: Sun, 31 May 2026 18:35:40 -0300
Subject: [PATCH 2/6] feat(analytics): add product analytics, session replay
 masking, and MCP events

- Add capture_event helper to observability service for custom PostHog events
- Fire alignment_section_reopened per rejected section in alignment phase
- Fire mcp_document_created, mcp_section_written, mcp_snapshot_saved, mcp_version_activated at HTTP layer via api_key_id detection
- Add document_opened, phase_completed, phase_entered events in DocumentPage
- Add discovery_question_answered/skipped in FollowUpQuestions
- Add alignment_section_reopened in AlignmentLayout
- Add refinement_edit_requested, refinement_question_asked, refinement_section_finalized in workspace store
- Add refinement_version_branched in TimelinePanel
- Add refinement_local_changes_saved, document_exported in EditorLayout
- Add editor_version_created, editor_version_restored in EditorVersionPanel
- Add document_exported in CompletedLayout
- Add data-ph-mask to SummaryCard, AuditProblems, CompletedLayout textareas/findings
- Guard posthog.identify behind consent in useClerkPosthogIdentity

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../backend/app/phases/alignment/function.py  | 11 +++++++--
 packages/backend/app/routers/documents.py     |  4 +++-
 packages/backend/app/routers/sections.py      | 18 +++++++++++++++
 .../backend/app/services/observability.py     | 12 ++++++++++
 .../phases/alignment/AlignmentLayout.tsx      |  2 ++
 .../phases/alignment/SummaryCard.tsx          |  1 +
 .../components/phases/audit/AuditProblems.tsx |  2 +-
 .../phases/completed/CompletedLayout.tsx      |  5 +++-
 .../phases/discovery/FollowUpQuestions.tsx    |  7 ++++++
 .../components/phases/editor/EditorLayout.tsx |  3 +++
 .../phases/editor/EditorVersionPanel.tsx      |  3 +++
 .../components/workspace/TimelinePanel.tsx    |  3 +++
 .../src/hooks/useClerkPosthogIdentity.ts      |  1 +
 packages/frontend/src/pages/DocumentPage.tsx  | 23 ++++++++++++++++++-
 packages/frontend/src/store/workspace.ts      |  5 ++++
 15 files changed, 94 insertions(+), 6 deletions(-)

diff --git a/packages/backend/app/phases/alignment/function.py b/packages/backend/app/phases/alignment/function.py
index 55772cf..70beff1 100644
--- a/packages/backend/app/phases/alignment/function.py
+++ b/packages/backend/app/phases/alignment/function.py
@@ -9,7 +9,7 @@
 from app.phases._shared.concurrency import DOC_CONCURRENCY
 from app.phases._shared.failure import workflow_on_failure
 from app.services import db as db_service
-from app.services.observability import capture_span
+from app.services.observability import capture_event, capture_span
 
 
 @inngest_client.create_function(
@@ -119,12 +119,19 @@ async def _extract_contract(s=summaries, sc=section_contexts):
 
             await step.run("extract-contract", _extract_contract)
         else:
+            rejected = approval_event.data.get("rejected", [])
             logger.info(
                 "[orchestrator] alignment rejected sections={} | doc_id={}",
-                approval_event.data.get("rejected", []),
+                rejected,
                 doc_id,
             )
 
+            async def _capture_rejected(r=rejected, it=iteration):
+                for section_type in r:
+                    capture_event(user_id, doc_id, "alignment_section_reopened", {"section_type": section_type, "iteration": it})
+
+            await step.run(f"capture-alignment-rejected-{iteration}", _capture_rejected)
+
     async def _capture_phase_span():
         capture_span(
             user_id, doc_id,
diff --git a/packages/backend/app/routers/documents.py b/packages/backend/app/routers/documents.py
index 490b9b7..6af91a6 100644
--- a/packages/backend/app/routers/documents.py
+++ b/packages/backend/app/routers/documents.py
@@ -19,7 +19,7 @@
     validate_document_context,
     validate_refinement_message,
 )
-from app.services.observability import capture_trace
+from app.services.observability import capture_event, capture_trace
 from app.inngest_client import inngest_client
 from app.models import (
     AuditFinding,
@@ -333,6 +333,8 @@ async def _create_editor_document(
     ))
 
     api_key_id = getattr(request.state, "api_key_id", None)
+    if api_key_id:
+        capture_event(str(current_user.id), str(doc.id), "mcp_document_created", {"has_context": bool(payload.user_preferences)})
     await db_service.log_activity(
         db, doc.id, "document_created",
         description="Document created via Editor",
diff --git a/packages/backend/app/routers/sections.py b/packages/backend/app/routers/sections.py
index ac5fef4..979d70e 100644
--- a/packages/backend/app/routers/sections.py
+++ b/packages/backend/app/routers/sections.py
@@ -18,6 +18,7 @@
     VersionRestoreResponse,
 )
 from app.services.db import create_version_snapshot, restore_version, update_section_content
+from app.services.observability import capture_event
 
 router = APIRouter(tags=["sections"])
 
@@ -95,6 +96,12 @@ async def create_section_snapshot(
     except ValueError as e:
         raise HTTPException(status_code=409, detail=str(e))
 
+    if api_key_id:
+        capture_event(str(current_user.id), str(section.document_id), "mcp_snapshot_saved", {
+            "has_name": bool(payload.version_name if payload else None),
+            "has_summary": bool(payload.change_summary if payload else None),
+        })
+
     return SectionVersionResponse.model_validate(version)
 
 
@@ -152,6 +159,13 @@ async def update_section_content_endpoint(
         )
     except ValueError as e:
         raise HTTPException(status_code=409, detail=str(e))
+
+    if api_key_id:
+        capture_event(str(current_user.id), str(section.document_id), "mcp_section_written", {
+            "content_length": len(payload.content),
+            "has_note": bool(note),
+        })
+
     return SectionVersionResponse.model_validate(version)
 
 
@@ -182,4 +196,8 @@ async def restore_section_version(
         raise HTTPException(status_code=404, detail="Version not found for this section")
 
     restored = await restore_version(db, section_id, version_id, doc_id=section.document_id, api_key_id=api_key_id)
+
+    if api_key_id:
+        capture_event(str(current_user.id), str(section.document_id), "mcp_version_activated", {})
+
     return VersionRestoreResponse(success=True, active_version_id=restored.id)
diff --git a/packages/backend/app/services/observability.py b/packages/backend/app/services/observability.py
index 8235122..d863572 100644
--- a/packages/backend/app/services/observability.py
+++ b/packages/backend/app/services/observability.py
@@ -22,6 +22,18 @@ def capture_trace(
     posthog_client.capture(distinct_id=distinct_id, event="$ai_trace", properties=properties)
 
 
+def capture_event(
+    distinct_id: str,
+    doc_id: str,
+    event_name: str,
+    properties: dict | None = None,
+) -> None:
+    if posthog_client is None:
+        return
+    full_props: dict = {"$ai_trace_id": doc_id, **(properties or {})}
+    posthog_client.capture(distinct_id=distinct_id, event=event_name, properties=full_props)
+
+
 def capture_span(
     distinct_id: str,
     doc_id: str,
diff --git a/packages/frontend/src/components/phases/alignment/AlignmentLayout.tsx b/packages/frontend/src/components/phases/alignment/AlignmentLayout.tsx
index c942f51..6794f65 100644
--- a/packages/frontend/src/components/phases/alignment/AlignmentLayout.tsx
+++ b/packages/frontend/src/components/phases/alignment/AlignmentLayout.tsx
@@ -1,5 +1,6 @@
 import { useState, useEffect } from "react";
 import { useAuth } from "@clerk/clerk-react";
+import posthog from "posthog-js";
 import type { Section, GuidedSectionType as SectionType } from "@/types";
 import { apiSendEvent } from "@/utils/api";
 import { ForgeLoader } from "@/components/shared";
@@ -102,6 +103,7 @@ export function AlignmentLayout({ documentId, sections }: AlignmentLayoutProps)
 
   const handleReopen = (type: SectionType) => {
     setCards((prev) => ({ ...prev, [type]: { ...prev[type], status: "pending" } }));
+    posthog.capture("alignment_section_reopened", { document_id: documentId, section_type: type });
   };
 
   return (
diff --git a/packages/frontend/src/components/phases/alignment/SummaryCard.tsx b/packages/frontend/src/components/phases/alignment/SummaryCard.tsx
index f265d01..08f673d 100644
--- a/packages/frontend/src/components/phases/alignment/SummaryCard.tsx
+++ b/packages/frontend/src/components/phases/alignment/SummaryCard.tsx
@@ -139,6 +139,7 @@ export function SummaryCard({
         </div>
       ) : (
         <p
+          data-ph-mask
           style={{
             fontSize: 13,
             color: isApproved
diff --git a/packages/frontend/src/components/phases/audit/AuditProblems.tsx b/packages/frontend/src/components/phases/audit/AuditProblems.tsx
index 224ba77..9981fe1 100644
--- a/packages/frontend/src/components/phases/audit/AuditProblems.tsx
+++ b/packages/frontend/src/components/phases/audit/AuditProblems.tsx
@@ -28,7 +28,7 @@ export function AuditProblems({ problems, onFix }: AuditProblemsProps) {
                   <span className="text-xs text-error/80 font-medium uppercase tracking-wider">
                     {problem.section}
                   </span>
-                  <p className="text-sm text-on-surface/80 mt-1">
+                  <p data-ph-mask className="text-sm text-on-surface/80 mt-1">
                     {problem.issue}
                   </p>
                   {problem.severity && (
diff --git a/packages/frontend/src/components/phases/completed/CompletedLayout.tsx b/packages/frontend/src/components/phases/completed/CompletedLayout.tsx
index 5eeb4d4..81092bd 100644
--- a/packages/frontend/src/components/phases/completed/CompletedLayout.tsx
+++ b/packages/frontend/src/components/phases/completed/CompletedLayout.tsx
@@ -1,5 +1,6 @@
 import { useEffect, useRef, useState } from "react";
 import { useAuth } from "@clerk/clerk-react";
+import posthog from "posthog-js";
 import type { Section, GuidedSectionType as SectionType, AuditFinding } from "@/types";
 import { apiFetchAuditFindings, apiDismissAuditFinding } from "@/utils/api";
 import { MarkdownRenderer } from "@/components/shared";
@@ -281,6 +282,7 @@ function SectionBlock({ sectionType, content, onEdit }: SectionBlockProps) {
 
       {isEditing ? (
         <textarea
+          data-ph-mask
           value={content}
           onChange={(e) => onEdit(e.target.value)}
           style={{
@@ -395,6 +397,7 @@ export function CompletedLayout({ documentId, sections }: CompletedLayoutProps)
     a.download = `document-${documentId}.md`;
     a.click();
     URL.revokeObjectURL(url);
+    posthog.capture("document_exported", { document_id: documentId, export_format: "markdown" });
   };
 
   return (
@@ -575,7 +578,7 @@ export function CompletedLayout({ documentId, sections }: CompletedLayoutProps)
                       >
                         {finding.severity === "high" ? "BLOCKER" : "WARN"}
                       </span>
-                      <span style={{ fontSize: 12.5, color: "var(--df-on-surface-soft, #c6c5c4)", lineHeight: 1.55, flex: 1 }}>
+                      <span data-ph-mask style={{ fontSize: 12.5, color: "var(--df-on-surface-soft, #c6c5c4)", lineHeight: 1.55, flex: 1 }}>
                         {finding.description}
                       </span>
                       <button
diff --git a/packages/frontend/src/components/phases/discovery/FollowUpQuestions.tsx b/packages/frontend/src/components/phases/discovery/FollowUpQuestions.tsx
index ed62a65..899ac58 100644
--- a/packages/frontend/src/components/phases/discovery/FollowUpQuestions.tsx
+++ b/packages/frontend/src/components/phases/discovery/FollowUpQuestions.tsx
@@ -1,5 +1,6 @@
 import { useState } from "react";
 import { useAuth } from "@clerk/clerk-react";
+import posthog from "posthog-js";
 import type { DiscoveryQuestion } from "@/types";
 import { apiAnswerQuestion } from "@/utils/api";
 
@@ -31,6 +32,12 @@ export function FollowUpQuestions({
     const question = questions.find((q) => q.id === questionId);
     if (!question || exitingId) return;
 
+    if (answer === null) {
+      posthog.capture("discovery_question_skipped", { document_id: documentId, section_key: question.sectionKey });
+    } else {
+      posthog.capture("discovery_question_answered", { document_id: documentId, section_key: question.sectionKey, answer_length: answer.length });
+    }
+
     setExitingId(questionId);
     const apiPromise = apiAnswerQuestion(documentId, question.question, answer, getToken);
 
diff --git a/packages/frontend/src/components/phases/editor/EditorLayout.tsx b/packages/frontend/src/components/phases/editor/EditorLayout.tsx
index 2a36fc5..c3b7ed8 100644
--- a/packages/frontend/src/components/phases/editor/EditorLayout.tsx
+++ b/packages/frontend/src/components/phases/editor/EditorLayout.tsx
@@ -1,5 +1,6 @@
 import { useState, useEffect, useRef, useCallback } from "react";
 import { useAuth } from "@clerk/clerk-react";
+import posthog from "posthog-js";
 import type { Section } from "@/types";
 import { apiUpdateSectionContent } from "@/utils/api";
 import { EditorNavPanel, parseHeadings, type Heading } from "./EditorNavPanel";
@@ -59,6 +60,7 @@ export function EditorLayout({ documentId, sections, sseTick }: EditorLayoutProp
       try {
         await apiUpdateSectionContent(bodySection.id, value, getToken);
         savedContentRef.current = value;
+        posthog.capture("refinement_local_changes_saved", { document_id: documentId, section_id: bodySection.id, content_length: value.length });
       } catch {
         // silent — next keystroke will retry
       }
@@ -104,6 +106,7 @@ export function EditorLayout({ documentId, sections, sseTick }: EditorLayoutProp
     a.download = "document.md";
     a.click();
     URL.revokeObjectURL(url);
+    posthog.capture("document_exported", { document_id: documentId, export_format: "markdown" });
   }
 
   function handleVersionSwitch(switchedContent: string) {
diff --git a/packages/frontend/src/components/phases/editor/EditorVersionPanel.tsx b/packages/frontend/src/components/phases/editor/EditorVersionPanel.tsx
index f7cc629..ea7d230 100644
--- a/packages/frontend/src/components/phases/editor/EditorVersionPanel.tsx
+++ b/packages/frontend/src/components/phases/editor/EditorVersionPanel.tsx
@@ -1,5 +1,6 @@
 import { useEffect, useState } from "react";
 import { useAuth } from "@clerk/clerk-react";
+import posthog from "posthog-js";
 import DiffMatchPatch from "diff-match-patch";
 import type { SectionVersion } from "@/types";
 import {
@@ -404,6 +405,7 @@ export function EditorVersionPanel({ sectionId, currentContent, refreshTick, onV
     setSnapshotting(true);
     try {
       await apiCreateVersionSnapshot(sectionId, getToken);
+      posthog.capture("editor_version_created", { section_id: sectionId });
       // Re-fetch so old versions have their latest auto-saved content in state
       await refetchVersions();
       setSelectedId(null);
@@ -419,6 +421,7 @@ export function EditorVersionPanel({ sectionId, currentContent, refreshTick, onV
       // Flush pending auto-save so the current edit is committed before we switch
       await onFlushSave();
       await apiRestoreVersion(sectionId, version.id, getToken);
+      posthog.capture("editor_version_restored", { section_id: sectionId, version_id: version.id });
       // Re-fetch all versions to get fresh content — auto-save may have written
       // to the old active version since the component first mounted, making the
       // local version.content stale.
diff --git a/packages/frontend/src/components/workspace/TimelinePanel.tsx b/packages/frontend/src/components/workspace/TimelinePanel.tsx
index 836145b..2559863 100644
--- a/packages/frontend/src/components/workspace/TimelinePanel.tsx
+++ b/packages/frontend/src/components/workspace/TimelinePanel.tsx
@@ -1,4 +1,5 @@
 import { useState } from "react";
+import posthog from "posthog-js";
 import { useWorkspaceStore, SECTION_LABELS } from "@/store";
 import type { SectionType, SectionVersion } from "@/types";
 import { apiUpdateSectionVersion } from "@/utils/api";
@@ -294,6 +295,7 @@ export function TimelinePanel() {
   const createVersionSnapshot = useWorkspaceStore((s) => s.createVersionSnapshot);
   const getActiveSection = useWorkspaceStore((s) => s.getActiveSection);
   const viewMode = useWorkspaceStore((s) => s.getActiveViewMode());
+  const documentId = useWorkspaceStore((s) => s.documentId);
 
   const isAwaitingAgent = useWorkspaceStore((s) => s.getActiveSectionIsAwaitingAgent());
   const isSendingMessage = useWorkspaceStore((s) => s.getActiveSectionIsSendingMessage());
@@ -313,6 +315,7 @@ export function TimelinePanel() {
 
   const handleNewVersion = () => {
     if (!currentSection || viewMode !== "editing" || isAIPending) return;
+    posthog.capture("refinement_version_branched", { document_id: documentId, section_id: currentSection.id });
     void createVersionSnapshot(currentSection.id);
   };
 
diff --git a/packages/frontend/src/hooks/useClerkPosthogIdentity.ts b/packages/frontend/src/hooks/useClerkPosthogIdentity.ts
index 18cf427..c5a619f 100644
--- a/packages/frontend/src/hooks/useClerkPosthogIdentity.ts
+++ b/packages/frontend/src/hooks/useClerkPosthogIdentity.ts
@@ -6,6 +6,7 @@ export function useClerkPosthogIdentity(consentGiven?: boolean) {
   const { user, isSignedIn } = useUser();
 
   useEffect(() => {
+    if (!consentGiven) return;
     if (isSignedIn && user) {
       posthog.identify(user.id, {
         email: user.primaryEmailAddress?.emailAddress,
diff --git a/packages/frontend/src/pages/DocumentPage.tsx b/packages/frontend/src/pages/DocumentPage.tsx
index 44c816a..72d1b3a 100644
--- a/packages/frontend/src/pages/DocumentPage.tsx
+++ b/packages/frontend/src/pages/DocumentPage.tsx
@@ -1,5 +1,5 @@
 import { useParams, useNavigate, useLocation } from "react-router-dom";
-import { useState, useCallback, useEffect } from "react";
+import { useState, useCallback, useEffect, useRef } from "react";
 import { useAuth } from "@clerk/clerk-react";
 import posthog from "posthog-js";
 import type { Phase } from "@/types";
@@ -35,9 +35,30 @@ export function DocumentPage() {
   const currentPhase: Phase = document?.currentPhase ?? "discovery";
   const { config } = usePhase(currentPhase);
 
+  // Fire document_opened once when a document is loaded
+  useEffect(() => {
+    if (!activeDocId || !document) return;
+    posthog.capture("document_opened", {
+      document_id: activeDocId,
+      phase: document.currentPhase,
+      document_type: document.documentMode,
+    });
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [activeDocId]);
+
+  // Track phase transitions for phase_completed and phase_entered
+  const prevPhaseRef = useRef<Phase | null>(null);
   useEffect(() => {
     if (!activeDocId) return;
+    if (prevPhaseRef.current && prevPhaseRef.current !== currentPhase) {
+      posthog.capture("phase_completed", {
+        document_id: activeDocId,
+        from_phase: prevPhaseRef.current,
+        to_phase: currentPhase,
+      });
+    }
     posthog.capture("phase_entered", { to_phase: currentPhase, document_id: activeDocId });
+    prevPhaseRef.current = currentPhase;
   }, [currentPhase, activeDocId]);
 
   const handleRenameTitle = useCallback(async (title: string) => {
diff --git a/packages/frontend/src/store/workspace.ts b/packages/frontend/src/store/workspace.ts
index 2c03409..c677f18 100644
--- a/packages/frontend/src/store/workspace.ts
+++ b/packages/frontend/src/store/workspace.ts
@@ -1,4 +1,5 @@
 import { create } from "zustand";
+import posthog from "posthog-js";
 import type {
   GuidedSectionType,
   SectionType,
@@ -306,8 +307,10 @@ export const useWorkspaceStore = create<WorkspaceState>((set, get) => ({
 
     if (actionType === "ask_question") {
       eventData.message = content;
+      posthog.capture("refinement_question_asked", { document_id: state.documentId, section_id: section.id, section_type: section.sectionType });
     } else if (actionType === "request_edit") {
       eventData.prompt = content;
+      posthog.capture("refinement_edit_requested", { document_id: state.documentId, section_id: section.id, section_type: section.sectionType });
     }
 
     try {
@@ -335,6 +338,8 @@ export const useWorkspaceStore = create<WorkspaceState>((set, get) => ({
     const state = get();
     if (!state.documentId || !state.getToken) return;
 
+    posthog.capture("refinement_section_finalized", { document_id: state.documentId, section_id: sectionId });
+
     await apiSendEvent(state.documentId, "section_action", {
       action_type: "finalize",
       section_id: sectionId,

From 4119a209d0d9b14f864bb3047cf2b77c07f9566b Mon Sep 17 00:00:00 2001
From: maxjneto <maxjneto@gmail.com>
Date: Mon, 1 Jun 2026 16:35:57 -0300
Subject: [PATCH 3/6] feat(analytics): fix event naming, add save/restore
 events, and first_document_completed
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Remove auto-save debounce from EditorLayout (was misfiring refinement_local_changes_saved)
- Add editor_changes_saved to EditorVersionPanel.handleSaveChanges (explicit save only)
- Add refinement_version_restored to TimelinePanel.handleRestore
- Add refinement_changes_saved + Save changes button to TimelinePanel
- Add saveActiveContent action to workspace store
- Add first_document_completed event on audit → completed phase transition

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../components/phases/editor/EditorLayout.tsx | 59 +------------------
 .../phases/editor/EditorVersionPanel.tsx      | 14 ++---
 .../components/workspace/TimelinePanel.tsx    | 52 ++++++++++++++++
 packages/frontend/src/pages/DocumentPage.tsx  |  3 +
 packages/frontend/src/store/workspace.ts      | 10 ++++
 5 files changed, 74 insertions(+), 64 deletions(-)

diff --git a/packages/frontend/src/components/phases/editor/EditorLayout.tsx b/packages/frontend/src/components/phases/editor/EditorLayout.tsx
index c3b7ed8..c708d69 100644
--- a/packages/frontend/src/components/phases/editor/EditorLayout.tsx
+++ b/packages/frontend/src/components/phases/editor/EditorLayout.tsx
@@ -1,8 +1,6 @@
 import { useState, useEffect, useRef, useCallback } from "react";
-import { useAuth } from "@clerk/clerk-react";
 import posthog from "posthog-js";
 import type { Section } from "@/types";
-import { apiUpdateSectionContent } from "@/utils/api";
 import { EditorNavPanel, parseHeadings, type Heading } from "./EditorNavPanel";
 import { EditorCenterPanel, type EditorMode } from "./EditorCenterPanel";
 import { EditorVersionPanel } from "./EditorVersionPanel";
@@ -15,8 +13,6 @@ interface EditorLayoutProps {
 }
 
 export function EditorLayout({ documentId, sections, sseTick }: EditorLayoutProps) {
-  const { getToken } = useAuth();
-
   const bodySection = sections.find((s) => s.sectionType === "body");
   const initialContent = (bodySection?.activeVersionContent ?? "").trim();
 
@@ -41,52 +37,9 @@ export function EditorLayout({ documentId, sections, sseTick }: EditorLayoutProp
     setHeadings(parseHeadings(content));
   }, [content]);
 
-  // Bump activityTick after auto-save so the panel refreshes
   const bumpActivity = useCallback(() => setActivityTick((n) => n + 1), []);
 
-  // Auto-save debounce — 1.5s after last keystroke
-  const saveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const savedContentRef = useRef(initialContent);
-  // Use a ref so flushSave always captures the latest content without stale closure
-  const contentRef = useRef(initialContent);
-
-  const handleChange = useCallback((value: string) => {
-    setContent(value);
-    contentRef.current = value;
-
-    if (saveTimerRef.current) clearTimeout(saveTimerRef.current);
-    saveTimerRef.current = setTimeout(async () => {
-      if (!bodySection || value === savedContentRef.current) return;
-      try {
-        await apiUpdateSectionContent(bodySection.id, value, getToken);
-        savedContentRef.current = value;
-        posthog.capture("refinement_local_changes_saved", { document_id: documentId, section_id: bodySection.id, content_length: value.length });
-      } catch {
-        // silent — next keystroke will retry
-      }
-    }, 1500);
-  }, [bodySection, getToken]);
-
-  // Immediately cancel the debounce and flush any unsaved content to the backend.
-  // Call this before switching versions so the current edit is never lost.
-  const flushSave = useCallback(async () => {
-    if (saveTimerRef.current) {
-      clearTimeout(saveTimerRef.current);
-      saveTimerRef.current = null;
-    }
-    const current = contentRef.current;
-    if (!bodySection || current === savedContentRef.current) return;
-    try {
-      await apiUpdateSectionContent(bodySection.id, current, getToken);
-      savedContentRef.current = current;
-    } catch {
-      // best-effort
-    }
-  }, [bodySection, getToken]);
-
-  useEffect(() => () => {
-    if (saveTimerRef.current) clearTimeout(saveTimerRef.current);
-  }, []);
+  const handleChange = (value: string) => setContent(value);
 
   function handleNavigate(slug: string) {
     setMode("preview");
@@ -110,14 +63,6 @@ export function EditorLayout({ documentId, sections, sseTick }: EditorLayoutProp
   }
 
   function handleVersionSwitch(switchedContent: string) {
-    // Cancel any pending auto-save so the old version's content doesn't
-    // get written to the newly-active version after we switch.
-    if (saveTimerRef.current) {
-      clearTimeout(saveTimerRef.current);
-      saveTimerRef.current = null;
-    }
-    contentRef.current = switchedContent;
-    savedContentRef.current = switchedContent;
     lastSectionContent.current = switchedContent;
     setContent(switchedContent);
   }
@@ -155,10 +100,10 @@ export function EditorLayout({ documentId, sections, sseTick }: EditorLayoutProp
       {bodySection && (
         <EditorVersionPanel
           sectionId={bodySection.id}
+          documentId={documentId}
           currentContent={content}
           refreshTick={sseTick}
           onVersionSwitch={(c) => { handleVersionSwitch(c); bumpActivity(); }}
-          onFlushSave={flushSave}
         />
       )}
 
diff --git a/packages/frontend/src/components/phases/editor/EditorVersionPanel.tsx b/packages/frontend/src/components/phases/editor/EditorVersionPanel.tsx
index ea7d230..123abfa 100644
--- a/packages/frontend/src/components/phases/editor/EditorVersionPanel.tsx
+++ b/packages/frontend/src/components/phases/editor/EditorVersionPanel.tsx
@@ -356,13 +356,13 @@ function DiffView({ oldText, newText }: { oldText: string; newText: string }) {
 
 interface EditorVersionPanelProps {
   sectionId: string;
+  documentId: string;
   currentContent: string;
   refreshTick: number;
   onVersionSwitch: (switchedContent: string) => void;
-  onFlushSave: () => Promise<void>;
 }
 
-export function EditorVersionPanel({ sectionId, currentContent, refreshTick, onVersionSwitch, onFlushSave }: EditorVersionPanelProps) {
+export function EditorVersionPanel({ sectionId, documentId, currentContent, refreshTick, onVersionSwitch }: EditorVersionPanelProps) {
   const { getToken } = useAuth();
   const [versions, setVersions] = useState<SectionVersion[]>([]);
   const [selectedId, setSelectedId] = useState<string | null>(null);
@@ -389,6 +389,11 @@ export function EditorVersionPanel({ sectionId, currentContent, refreshTick, onV
       setVersions((prev) =>
         prev.map((v) => (v.isActive ? { ...v, content: updated.content } : v))
       );
+      posthog.capture("editor_changes_saved", {
+        document_id: documentId,
+        section_id: sectionId,
+        content_length: currentContent.length,
+      });
     } finally {
       setSaving(false);
     }
@@ -418,13 +423,8 @@ export function EditorVersionPanel({ sectionId, currentContent, refreshTick, onV
     if (switching) return;
     setSwitching(true);
     try {
-      // Flush pending auto-save so the current edit is committed before we switch
-      await onFlushSave();
       await apiRestoreVersion(sectionId, version.id, getToken);
       posthog.capture("editor_version_restored", { section_id: sectionId, version_id: version.id });
-      // Re-fetch all versions to get fresh content — auto-save may have written
-      // to the old active version since the component first mounted, making the
-      // local version.content stale.
       const fresh = await apiFetchVersions(sectionId, getToken);
       setVersions(fresh.slice().reverse());
       const target = fresh.find((v) => v.id === version.id);
diff --git a/packages/frontend/src/components/workspace/TimelinePanel.tsx b/packages/frontend/src/components/workspace/TimelinePanel.tsx
index 2559863..8e26230 100644
--- a/packages/frontend/src/components/workspace/TimelinePanel.tsx
+++ b/packages/frontend/src/components/workspace/TimelinePanel.tsx
@@ -293,19 +293,27 @@ export function TimelinePanel() {
   const restoreVersion = useWorkspaceStore((s) => s.restoreVersion);
   const finalizeSection = useWorkspaceStore((s) => s.finalizeSection);
   const createVersionSnapshot = useWorkspaceStore((s) => s.createVersionSnapshot);
+  const saveActiveContent = useWorkspaceStore((s) => s.saveActiveContent);
   const getActiveSection = useWorkspaceStore((s) => s.getActiveSection);
+  const getActiveVersionContent = useWorkspaceStore((s) => s.getActiveVersionContent);
   const viewMode = useWorkspaceStore((s) => s.getActiveViewMode());
   const documentId = useWorkspaceStore((s) => s.documentId);
 
   const isAwaitingAgent = useWorkspaceStore((s) => s.getActiveSectionIsAwaitingAgent());
   const isSendingMessage = useWorkspaceStore((s) => s.getActiveSectionIsSendingMessage());
   const isAIPending = isAwaitingAgent || isSendingMessage;
+  const [saving, setSaving] = useState(false);
 
   const currentSection = getActiveSection();
 
   const handleRestore = (versionId: string) => {
     if (!currentSection || viewMode !== "editing") return;
     restoreVersion(currentSection.id, versionId);
+    posthog.capture("refinement_version_restored", {
+      document_id: documentId,
+      section_id: currentSection.id,
+      version_id: versionId,
+    });
   };
 
   const handleFinalize = () => {
@@ -319,6 +327,21 @@ export function TimelinePanel() {
     void createVersionSnapshot(currentSection.id);
   };
 
+  const handleSaveChanges = async () => {
+    if (!currentSection || viewMode !== "editing" || saving) return;
+    setSaving(true);
+    try {
+      await saveActiveContent();
+      posthog.capture("refinement_changes_saved", {
+        document_id: documentId,
+        section_id: currentSection.id,
+        content_length: getActiveVersionContent().length,
+      });
+    } finally {
+      setSaving(false);
+    }
+  };
+
   return (
     <aside
       style={{
@@ -412,6 +435,35 @@ export function TimelinePanel() {
             flexShrink: 0,
           }}
         >
+          <button
+            onClick={handleSaveChanges}
+            disabled={saving}
+            style={{
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "center",
+              gap: 6,
+              padding: "8px 12px",
+              borderRadius: 6,
+              fontSize: 11,
+              fontWeight: 500,
+              background: "transparent",
+              border: "1px solid var(--df-outline-md, rgba(255,255,255,0.10))",
+              color: saving ? "var(--df-mute, rgba(227,226,226,0.18))" : "var(--df-faint, rgba(227,226,226,0.38))",
+              cursor: saving ? "not-allowed" : "pointer",
+              opacity: saving ? 0.5 : 1,
+              transition: "all 0.15s",
+              fontFamily: "var(--df-font-mono, 'JetBrains Mono', monospace)",
+              letterSpacing: "0.06em",
+              textTransform: "uppercase",
+            }}
+            onMouseEnter={(e) => { if (!saving) { (e.currentTarget as HTMLElement).style.color = "var(--df-dim, rgba(227,226,226,0.62))"; } }}
+            onMouseLeave={(e) => { if (!saving) { (e.currentTarget as HTMLElement).style.color = "var(--df-faint, rgba(227,226,226,0.38))"; } }}
+          >
+            <span className="material-symbols-outlined" style={{ fontSize: 14 }}>save</span>
+            {saving ? "Saving…" : "Save changes"}
+          </button>
+
           <button
             onClick={handleNewVersion}
             disabled={isAIPending}
diff --git a/packages/frontend/src/pages/DocumentPage.tsx b/packages/frontend/src/pages/DocumentPage.tsx
index 72d1b3a..374425a 100644
--- a/packages/frontend/src/pages/DocumentPage.tsx
+++ b/packages/frontend/src/pages/DocumentPage.tsx
@@ -56,6 +56,9 @@ export function DocumentPage() {
         from_phase: prevPhaseRef.current,
         to_phase: currentPhase,
       });
+      if (prevPhaseRef.current === "audit" && currentPhase === "completed") {
+        posthog.capture("first_document_completed", { document_id: activeDocId });
+      }
     }
     posthog.capture("phase_entered", { to_phase: currentPhase, document_id: activeDocId });
     prevPhaseRef.current = currentPhase;
diff --git a/packages/frontend/src/store/workspace.ts b/packages/frontend/src/store/workspace.ts
index c677f18..37fa7fb 100644
--- a/packages/frontend/src/store/workspace.ts
+++ b/packages/frontend/src/store/workspace.ts
@@ -14,6 +14,7 @@ import {
   apiSendEvent,
   apiRestoreVersion,
   apiCreateVersionSnapshot,
+  apiUpdateSectionContent,
 } from "@/utils/api";
 
 type GetToken = () => Promise<string | null>;
@@ -75,6 +76,7 @@ interface WorkspaceState {
 
   // Section actions
   finalizeSection: (sectionId: string) => Promise<void>;
+  saveActiveContent: () => Promise<void>;
 
   // Derived
   getActiveSection: () => Section | undefined;
@@ -347,6 +349,14 @@ export const useWorkspaceStore = create<WorkspaceState>((set, get) => ({
     // Polling from DocumentPage will update section status
   },
 
+  saveActiveContent: async () => {
+    const state = get();
+    const section = state.sections.find((s) => s.sectionType === state.activeSection);
+    if (!section || !state.getToken) return;
+    const content = state.getActiveVersionContent();
+    await apiUpdateSectionContent(section.id, content, state.getToken);
+  },
+
   // ─── Derived ─────────────────────────────────────────────
 
   getActiveSection: () => {

From 6927169bb422cc69922064dc2844ee035ab0fbed Mon Sep 17 00:00:00 2001
From: maxjneto <maxjneto@gmail.com>
Date: Mon, 1 Jun 2026 16:36:04 -0300
Subject: [PATCH 4/6] fix(mcp): fix UnboundLocalError when request has no
 Bearer token

key was only assigned inside the if block, crashing on unauthenticated
requests like the initial GET /mcp handshake from MCP clients.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 packages/mcp/src/docforge_mcp/server.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/packages/mcp/src/docforge_mcp/server.py b/packages/mcp/src/docforge_mcp/server.py
index 5c5c2bb..da93513 100644
--- a/packages/mcp/src/docforge_mcp/server.py
+++ b/packages/mcp/src/docforge_mcp/server.py
@@ -349,8 +349,7 @@ async def docforge_orientation() -> str:
 class _ApiKeyMiddleware(BaseHTTPMiddleware):
     async def dispatch(self, request: Request, call_next):
         auth = request.headers.get("authorization", "")
-        if auth.lower().startswith("bearer "):
-            key = auth[7:]
+        key = auth[7:] if auth.lower().startswith("bearer ") else ""
         token = _api_key_var.set(key)
         try:
             return await call_next(request)

From 8e59ed6bd6e7169068a0692175f07040ea64af3a Mon Sep 17 00:00:00 2001
From: maxjneto <maxjneto@gmail.com>
Date: Mon, 1 Jun 2026 16:53:17 -0300
Subject: [PATCH 5/6] feat(ci): add PostHog environment variables to frontend
 .env setup

---
 .../workflows/azure-static-web-apps-jolly-ocean-0fcd5df0f.yml   | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.github/workflows/azure-static-web-apps-jolly-ocean-0fcd5df0f.yml b/.github/workflows/azure-static-web-apps-jolly-ocean-0fcd5df0f.yml
index 1061902..484b4fa 100644
--- a/.github/workflows/azure-static-web-apps-jolly-ocean-0fcd5df0f.yml
+++ b/.github/workflows/azure-static-web-apps-jolly-ocean-0fcd5df0f.yml
@@ -33,6 +33,8 @@ jobs:
         run: |
           echo "VITE_API_BASE=${{ secrets.VITE_API_BASE }}" >> .env
           echo "VITE_CLERK_PUBLISHABLE_KEY=${{ secrets.VITE_CLERK_PUBLISHABLE_KEY }}" >> .env
+          echo "VITE_POSTHOG_KEY=${{ secrets.VITE_POSTHOG_KEY }}" >> .env
+          echo "VITE_POSTHOG_HOST=${{ secrets.VITE_POSTHOG_HOST }}" >> .env
 
       - name: Install
         working-directory: packages/frontend

From 236d0374918a6ffa59e6ed46ed1541f2d5f50f91 Mon Sep 17 00:00:00 2001
From: maxjneto <maxjneto@gmail.com>
Date: Mon, 1 Jun 2026 17:09:45 -0300
Subject: [PATCH 6/6] refactor (lint): reorder observability imports for
 consistency

---
 packages/backend/app/routers/documents.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/backend/app/routers/documents.py b/packages/backend/app/routers/documents.py
index 6af91a6..093f940 100644
--- a/packages/backend/app/routers/documents.py
+++ b/packages/backend/app/routers/documents.py
@@ -19,7 +19,6 @@
     validate_document_context,
     validate_refinement_message,
 )
-from app.services.observability import capture_event, capture_trace
 from app.inngest_client import inngest_client
 from app.models import (
     AuditFinding,
@@ -45,6 +44,7 @@
 from app.schemas.events import AnswerQuestionRequest, EventRequest
 from app.services import db as db_service
 from app.services import sse as sse_service
+from app.services.observability import capture_event, capture_trace
 
 router = APIRouter(tags=["documents"])