docs(handbook/support): expand how-to-answer guide as decision tree

[CodeCLS]

Grew the support playbook from a handful of templates to a 44-branch decision tree covering account/access, billing, self-hosting, ingestion, SDKs/integrations, prompt management, evaluations, security/compliance, data deletion, API errors, UI bugs, and non-support inbox triage.

Branches use native

/

(mapped to the Details MDX components) so support engineers and AI support agents can walk down to the matching playbook. Each leaf has triage steps, a canonical reply template drawn from real team replies, escalation rules, and links to existing FAQ pages.

Patterns are derived from analyzing ~1,500 closed Pylon tickets.

Greptile Summary

This PR replaces the original ~170-line support guide with a comprehensive 1,255-line decision tree covering 13 question categories and 44 branches, each containing triage steps, canonical reply templates drawn from ~1,500 resolved tickets, escalation rules, and links to existing FAQ pages.

• The decision tree is structured with collapsible <details>/<summary> blocks so both human engineers and AI support agents can navigate to the matching playbook branch quickly.
• Two concrete errors need attention before merge: a misplaced FAQ link in the CVE section points to /faq/all/data-retention-timeouts-and-errors (a data retention topic) instead of a security/disclosure page; and the startup discount code STARTUP-LF-50 is now published on a publicly accessible handbook URL, allowing it to be used at checkout without the required form submission.

Confidence Score: 3/5

The documentation changes are high-quality and well-structured, but two concrete correctness issues should be resolved before the page goes live: a wrong FAQ link that would send support engineers and AI agents to the wrong resource, and a promotional discount code that any visitor can now apply without completing the required vetting form.

The playbook content itself is thorough and drawn from real ticket resolutions. Two issues stand out: the STARTUP-LF-50 code published on a public URL defeats the form-gating intended by the startup program, and the CVE section points to an entirely unrelated FAQ about data retention. Both issues are on the changed file and have immediate operational impact — one financial, one on playbook accuracy.

content/handbook/support/how-to-answer-support-questions.mdx — specifically the startup discount code block (line 339) and the CVE section FAQ link (line 610).

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Incoming support ticket] --> B[Preflight: check tier, region, status page, Pylon duplicates]
    B --> C{Category?}
    C --> D[1. Account / login / access]
    C --> E[2. Billing / pricing / contracts]
    C --> F[3. Self-hosting]
    C --> G[4. Ingestion]
    C --> H[5. SDKs & integrations]
    C --> I[6. Prompt management]
    C --> J[7. Evaluations]
    C --> K[8. Security & compliance]
    C --> L[9. Data deletion & retention]
    C --> M[10. API errors]
    C --> N[11. UI bugs]
    C --> O[12. Customer leaving]
    C --> P[13. Non-support inbox]
    D --> D1{Sub-branch}
    D1 --> D2[Can't log in → region mismatch]
    D1 --> D3[Password reset → suppression list]
    D1 --> D4[SSO setup → collect IdP credentials]
    D1 --> D5[2FA recovery → verify ownership]
    D1 --> D6[Can't see org/project → RBAC/region]
    E --> E1{Sub-branch}
    E1 --> E2[Unexpected charge → Stripe + OTEL check]
    E1 --> E3[Cancel / downgrade → Stripe vs EE contract]
    E1 --> E4[Refund → USD 2k threshold]
    E1 --> E5[Startup discount → form + STARTUP-LF-50]
    E1 --> E6[Enterprise quote → route to Akio/Clemens]
    K --> K1[SOC2/ISO27001 → route to Akio]
    K --> K2[DPA → langfuse.com/security/dpa]
    K --> K3[BAA/HIPAA → hipaa.cloud.langfuse.com]
    K --> K4[Bug bounty → no formal program]

Loading

Prompt To Fix All With AI

Fix the following 4 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 4
content/handbook/support/how-to-answer-support-questions.mdx:610-616
Wrong FAQ linked under the CVE section. `/faq/all/data-retention-timeouts-and-errors` is about data retention jobs and errors, not vulnerability reports. A customer or AI agent following this playbook for a CVE report will land on an unrelated FAQ page, eroding trust in the playbook. The correct link would be to the security or responsible-disclosure page, or the link can simply be removed since no directly relevant FAQ exists yet.

```suggestion
Related FAQ: [/security/responsible-disclosure](https://langfuse.com/security/responsible-disclosure).

</details>

---

### 4. Ingestion (Cloud and self-hosted)
```

### Issue 2 of 4
content/handbook/support/how-to-answer-support-questions.mdx:339-346
**Discount code published on a public-facing page**

The handbook at `langfuse.com/handbook` is publicly accessible. Publishing `STARTUP-LF-50` here means anyone who reads this page — not just approved applicants — can apply it directly at checkout, bypassing the Google Form vetting step entirely. The stated requirement "All applicants go through the form, no exceptions" is now only advisory for anyone who finds this page. Consider either (a) removing the literal code and noting it is emailed post-approval, or (b) rotating the code to a form-generated per-applicant token so the public one no longer works.

### Issue 3 of 4
content/handbook/support/how-to-answer-support-questions.mdx:42-44
**Internal Slack handles and individual employee emails in a public document**

The AI-agents callout instructs AI agents to ping `@steffen.schmitz`, `@jannik.maierhoefer`, and `@caleb.seeling` by Slack handle. Individual email addresses for Akio and Clemens also appear throughout the billing and security sections. Since `langfuse.com/handbook` is publicly indexed, these identifiers are now crawlable by scrapers. Consider replacing specific handles with role-based escalation paths (e.g. "engineering on-call", "enterprise team") and keeping personal contacts in an internal-only note or Pylon macro.

### Issue 4 of 4
content/handbook/support/how-to-answer-support-questions.mdx:862-866
**GitHub discussion references lack full URLs**

Several entries reference discussions only by number — e.g. "#13268", "#13359", "#1819", "#12897", "#12876" — without specifying the repository. A support engineer (or an AI agent) cannot navigate to them without already knowing the repo context. Consider using full `github.com/langfuse/langfuse/discussions/NNNNN` links. The same applies to "#13438", "#13261", "#13514", "#13583", "#36107" (the last is a Dify issue, not a Langfuse one).

_{Reviews (1): Last reviewed commit: "docs(handbook/support): expand how-to-an..." | Re-trigger Greptile}

Greptile also left 2 inline comments on this PR.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
langfuse-docs	Ready	Preview, Comment	May 28, 2026 12:57pm

[github-actions]

@claude review

[claude]

Additional findings (outside current diff — PR may have been updated during review):

• 🔴 lib/source.ts:147-152 — Build-breaking: the recent revert in lib/source.ts removes the workshopSource export, but three files still import it from @/lib/source — lib/section-registry.ts (lines 15, 122), app/workshop/layout.tsx (lines 1, 11), and app/workshop/[[...slug]]/page.tsx (lines 4, 22, 54, 70, 76). This will fail tsc / next build with TS2305 'Module "@/lib/source" has no exported member workshopSource' and block the Vercel deploy. Fix by either (a) also reverting the workshop callers (delete app/workshop/, remove the workshop entry from lib/section-registry.ts, and remove the workshop defineDocs(...) from source.config.ts:179-182) or (b) restoring the workshopSource loader in lib/source.ts.

  Extended reasoning...

  What the bug is. This PR contains two changes: an MDX docs expansion in content/handbook/support/how-to-answer-support-questions.mdx, and a revert in lib/source.ts that removes both the workshop collection import (line 17 of the prior file) and the entire workshopSource loader export (the deleted hunk at the old lines 148-153). The MDX change is the headline; the second change is the build breaker.

  The specific code path that triggers the failure. Three files in the working tree still import the now-deleted symbol from @/lib/source:

  1. lib/section-registry.ts:15 — import { ..., workshopSource, ... } from "@/lib/source"; — used at line 122 as source: workshopSource inside docSections.workshop.
  2. app/workshop/layout.tsx:1 — import { workshopSource } from "@/lib/source"; — used at line 11 as workshopSource.getPageTree() in the layout shell.
  3. app/workshop/[[...slug]]/page.tsx:4 — import { workshopSource } from "@/lib/source"; — used at lines 22, 54, 70, and 76 (workshopSource.getPages(), workshopSource.getPage(slug), workshopSource.generateParams()). The generateStaticParams call at line 76 in particular runs during next build, so this is not just a type error — it is a build-time runtime reference to a missing module export.

  These imports are unconditional named imports, not commented out and not behind a feature flag. TypeScript will reject them with TS2305: Module "@/lib/source" has no exported member workshopSource, and Next.js will fail to resolve the symbol at bundle time.

  Why existing guardrails do not catch this. The PR title and description scope it as a docs change (docs(handbook/support): expand how-to-answer guide as decision tree), and the prose review tooling (Greptile, Vercel preview comments) focuses on the MDX content. There is no markdown-only linter that would flag this — only tsc / next build would. The Vercel preview is listed as "Building" in the PR timeline; once it gets past the docs change, the Next build step on this branch will fail.

  Note on the underlying data. The workshop collection itself is still declared in source.config.ts:179-182 (export const workshop = defineDocs({ dir: "content/workshop", ... })), so the underlying MDX collection is intact. Only the loader wrapper that exposes it as workshopSource was removed. This means the revert is partial: data layer remains, loader is gone, callers still reference the loader.

  Step-by-step proof.

  1. Check out this PR branch and run pnpm install.
  2. Run pnpm typecheck (or npx tsc --noEmit). It will fail with three TS2305 errors at lib/section-registry.ts:15, app/workshop/layout.tsx:1, and app/workshop/[[...slug]]/page.tsx:4, all of the form Module '"@/lib/source"' has no exported member 'workshopSource'.
  3. Equivalently, run pnpm build (or next build). It will fail at the type-check phase with the same errors, or at the bundle phase when Next.js tries to resolve the named import.
  4. Vercel deploy will fail on the same step. The "Building" status in the PR timeline will flip to "Failed" once the typecheck stage runs.

  Impact. Hard build-breaking on a docs PR. Blocks Vercel deploy and any downstream merge train. The PR title and description give no signal that a non-docs file is being touched, which makes this easy to miss in review.

  How to fix. Pick one of two paths:

  • (a) Complete the revert. The previous commit 51f584f [codex] Add workshop section (#3003) introduced all of these caller sites together with the loader. Mirror its inverse: delete app/workshop/ (both layout.tsx and [[...slug]]/page.tsx), remove the workshopSource import and the workshop entry from lib/section-registry.ts, and remove the workshop = defineDocs({...}) block from source.config.ts:179-182. This is the minimal change consistent with the commit message "remove workshop collection loader".
  • (b) Restore the loader. Re-add the workshop import to lib/source.ts and re-add the workshopSource = loader({...}) block. This keeps the workshop section live in production until the team is ready to remove it end-to-end.

  Either fix unblocks the build. (a) matches the intent of the commit message; (b) is the smaller diff and lower-risk if the revert was not actually intended to remove the workshop UI as well.