vybekiit 0.7.33 → 0.7.35

package/dist/global-skills/instrument-feature-flags/references/android.md

@@ -2,6 +2,20 @@
 
 # Android Feature Flags installation
 
+Canonical URL: https://posthog.com/docs/feature-flags/installation/android
+
+> **Cloud region:** This page uses US Cloud hosts. For an EU Cloud project, use `https://eu.i.posthog.com` instead of `https://us.i.posthog.com` (ingestion host).
+
+## On this page
+
+- [Install the dependency](#install-the-dependency)
+- [Configure PostHog](#configure-posthog)
+- [Send events](#send-events)
+- [Evaluate boolean feature flags](#evaluate-boolean-feature-flags)
+- [Evaluate multivariate feature flags](#evaluate-multivariate-feature-flags)
+- [Running experiments](#running-experiments)
+- [Next steps](#next-steps)
+
 1.  1
 
     ## Install the dependency
@@ -128,16 +142,8 @@
 
     | Resource | Description |
     | --- | --- |
-    | [Creating a feature flag](/docs/feature-flags/creating-feature-flags.md) | How to create a feature flag in PostHog |
-    | [Adding feature flag code](/docs/feature-flags/adding-feature-flag-code.md) | How to check flags in your code for all platforms |
-    | [Framework-specific guides](/docs/feature-flags/tutorials.md#framework-guides) | Setup guides for React Native, Next.js, Flutter, and other frameworks |
-    | [How to do a phased rollout](/tutorials/phased-rollout.md) | Gradually roll out features to minimize risk |
-    | [More tutorials](/docs/feature-flags/tutorials.md) | Other real-world examples and use cases |
-
-### Still have questions?
-
-Ask PostHog AI
-
-### Was this page useful?
-
-HelpfulCould be better
+    | [Creating a feature flag](https://posthog.com/docs/feature-flags/creating-feature-flags.md) | How to create a feature flag in PostHog |
+    | [Adding feature flag code](https://posthog.com/docs/feature-flags/adding-feature-flag-code.md) | How to check flags in your code for all platforms |
+    | [Framework-specific guides](https://posthog.com/docs/feature-flags/tutorials.md#framework-guides) | Setup guides for React Native, Next.js, Flutter, and other frameworks |
+    | [How to do a phased rollout](https://posthog.com/tutorials/phased-rollout.md) | Gradually roll out features to minimize risk |
+    | [More tutorials](https://posthog.com/docs/feature-flags/tutorials.md) | Other real-world examples and use cases |

package/dist/global-skills/instrument-feature-flags/references/api.md

@@ -2,6 +2,18 @@
 
 # API Feature Flags installation
 
+Canonical URL: https://posthog.com/docs/feature-flags/installation/api
+
+> **Cloud region:** This page uses US Cloud hosts. For an EU Cloud project, use `https://eu.i.posthog.com` instead of `https://us.i.posthog.com` (ingestion host).
+
+## On this page
+
+- [Evaluate the feature flag value using flags](#evaluate-the-feature-flag-value-using-flags)
+- [Include feature flag information when capturing events](#include-feature-flag-information-when-capturing-events)
+- [Send a $feature_flag_called event](#send-a-feature_flag_called-event)
+- [Running experiments](#running-experiments)
+- [Next steps](#next-steps)
+
 1.  1
 
     ## Evaluate the feature flag value using flags
@@ -178,16 +190,8 @@
 
     | Resource | Description |
     | --- | --- |
-    | [Creating a feature flag](/docs/feature-flags/creating-feature-flags.md) | How to create a feature flag in PostHog |
-    | [Adding feature flag code](/docs/feature-flags/adding-feature-flag-code.md) | How to check flags in your code for all platforms |
-    | [Framework-specific guides](/docs/feature-flags/tutorials.md#framework-guides) | Setup guides for React Native, Next.js, Flutter, and other frameworks |
-    | [How to do a phased rollout](/tutorials/phased-rollout.md) | Gradually roll out features to minimize risk |
-    | [More tutorials](/docs/feature-flags/tutorials.md) | Other real-world examples and use cases |
-
-### Still have questions?
-
-Ask PostHog AI
-
-### Was this page useful?
-
-HelpfulCould be better
+    | [Creating a feature flag](https://posthog.com/docs/feature-flags/creating-feature-flags.md) | How to create a feature flag in PostHog |
+    | [Adding feature flag code](https://posthog.com/docs/feature-flags/adding-feature-flag-code.md) | How to check flags in your code for all platforms |
+    | [Framework-specific guides](https://posthog.com/docs/feature-flags/tutorials.md#framework-guides) | Setup guides for React Native, Next.js, Flutter, and other frameworks |
+    | [How to do a phased rollout](https://posthog.com/tutorials/phased-rollout.md) | Gradually roll out features to minimize risk |
+    | [More tutorials](https://posthog.com/docs/feature-flags/tutorials.md) | Other real-world examples and use cases |

package/dist/global-skills/instrument-feature-flags/references/best-practices.md

@@ -2,11 +2,23 @@
 
 # Best practices for production-ready flags
 
+Canonical URL: https://posthog.com/docs/feature-flags/best-practices
+
+## On this page
+
+- [Checklist](#checklist)
+- [Flags are pure functions](#flags-are-pure-functions)
+- [Unexpected results are almost always input problems](#unexpected-results-are-almost-always-input-problems)
+- [Resolve identity before evaluating flags](#resolve-identity-before-evaluating-flags)
+- [Evaluation architecture](#evaluation-architecture)
+- [Flag hygiene](#flag-hygiene)
+- [Further reading](#further-reading)
+
 ## Checklist
 
 -    [Call `identify()` before evaluating flags](#resolve-identity-before-evaluating-flags) – the hash uses the wrong ID otherwise. This is the most common input problem.
 -    [Evaluate flags server-side with local evaluation](#server-side-local-evaluation-is-the-recommended-default) – explicit inputs, your data right there, no workarounds.
--    [Bootstrap client-side flags](#have-the-value-before-you-need-it) – client-side evaluation is async. [Bootstrap](/docs/feature-flags/bootstrapping.md) to eliminate the gap.
+-    [Bootstrap client-side flags](#have-the-value-before-you-need-it) – client-side evaluation is async. [Bootstrap](https://posthog.com/docs/feature-flags/bootstrapping.md) to eliminate the gap.
 -    [Handle `undefined` explicitly](#undefined-is-not-false) – it means "not evaluated yet," not `false`.
 -    [Evaluate once, record the result](#evaluate-once-not-continuously) – a flag is a one-time signal. Re-evaluate only on meaningful state changes.
 -    [Evaluate where the data lives](#evaluate-where-the-data-lives) – if the data is on your server, evaluate there.
@@ -58,13 +70,13 @@ So when a flag returns something you didn't expect, **the flag is fine, the prob
 
 If you keep running into flag issues and they're not [incidents](https://status.posthog.com), the conversation isn't about PostHog's flag behavior – it's about how your application coordinates the data that flags depend on. That's an engineering conversation about identity flows, property syncing, and evaluation architecture. No single config tweak fixes it.
 
-We're here to help with that – this guide, [PostHog AI](/docs/feature-flags/manage-flags-ai.md), and [professional services](https://posthog.com/professional-services) all exist for exactly this. But the starting point is always the same: **look at the inputs.**
+We're here to help with that – this guide, [PostHog AI](https://posthog.com/docs/feature-flags/manage-flags-ai.md), and [professional services](https://posthog.com/professional-services) all exist for exactly this. But the starting point is always the same: **look at the inputs.**
 
 When something goes wrong, in order of likelihood:
 
-1.  **Input problems** (most common). Wrong distinct ID, missing properties, changed flag definition. PostHog gives you tools to get the coordination right – [bootstrapping](/docs/feature-flags/bootstrapping.md), [property overrides](/docs/feature-flags/property-overrides.md), [server-side evaluation](/docs/feature-flags/local-evaluation.md).
+1.  **Input problems** (most common). Wrong distinct ID, missing properties, changed flag definition. PostHog gives you tools to get the coordination right – [bootstrapping](https://posthog.com/docs/feature-flags/bootstrapping.md), [property overrides](https://posthog.com/docs/feature-flags/property-overrides.md), [server-side evaluation](https://posthog.com/docs/feature-flags/local-evaluation.md).
 2.  **Output problems.** The flag returned the right value but your code misread it – `undefined` treated as `false`, no handling for the loading gap, evaluating repeatedly instead of recording the result.
-3.  **Actual incidents.** Check [status.posthog.com](https://status.posthog.com). If nothing there, it's #1 or #2. And even here: with [server-side local evaluation](/docs/feature-flags/local-evaluation.md), the SDK evaluates against cached flag definitions locally. PostHog being unreachable doesn't affect flags that are already cached. Add per-flag safe defaults and even a cold start during an outage returns usable values. An incident only breaks your flags if your implementation depends on PostHog being available at request time – which is itself an implementation gap you can close.
+3.  **Actual incidents.** Check [status.posthog.com](https://status.posthog.com). If nothing there, it's #1 or #2. And even here: with [server-side local evaluation](https://posthog.com/docs/feature-flags/local-evaluation.md), the SDK evaluates against cached flag definitions locally. PostHog being unreachable doesn't affect flags that are already cached. Add per-flag safe defaults and even a cold start during an outage returns usable values. An incident only breaks your flags if your implementation depends on PostHog being available at request time – which is itself an implementation gap you can close.
 
 ## Resolve identity before evaluating flags
 
@@ -72,17 +84,17 @@ Identity is the most common input problem. The hash takes two inputs: the flag k
 
 If you call `identify()` after a flag has already been evaluated, the flag likely used the anonymous ID. The hash produced one result. After `identify()`, the distinct ID changes, the hash changes, and the next evaluation returns a different variant. You see a "flip" – but it's because the input changed.
 
-Call [`identify()`](/docs/product-analytics/identify.md) before any flag evaluation in auth flows. If you can't guarantee that timing, [bootstrap](/docs/feature-flags/bootstrapping.md) with the stable ID at init so the distinct ID is correct from the first millisecond. See [keeping flag evaluations stable](/docs/feature-flags/stable-identity-for-flags.md) for the full picture.
+Call [`identify()`](https://posthog.com/docs/product-analytics/identify.md) before any flag evaluation in auth flows. If you can't guarantee that timing, [bootstrap](https://posthog.com/docs/feature-flags/bootstrapping.md) with the stable ID at init so the distinct ID is correct from the first millisecond. See [keeping flag evaluations stable](https://posthog.com/docs/feature-flags/stable-identity-for-flags.md) for the full picture.
 
 **SPA-specific timing.** In single-page applications, `identify()` and event captures often fire from different components during the same navigation in unpredictable order. The SDK updates the `distinct_id` synchronously when `identify()` runs, but if `capture()` was called first in the same execution frame, that event uses the anonymous ID. The fix: call `identify()` before the navigation that mounts post-auth components – in Vue, in `beforeEach` before `next()`; in React, before `navigate()`, not in a `useEffect` inside the target route.
 
 ### Don't rely on flag persistence to fix identity gaps
 
-If you've enabled [experience continuity](/docs/feature-flags/creating-feature-flags.md#persisting-feature-flags-across-authentication-steps-optional) (flag persistence across authentication), consider what that's telling you: the distinct ID is changing during your session, and you need PostHog to paper over it.
+If you've enabled [experience continuity](https://posthog.com/docs/feature-flags/creating-feature-flags.md#persisting-feature-flags-across-authentication-steps-optional) (flag persistence across authentication), consider what that's telling you: the distinct ID is changing during your session, and you need PostHog to paper over it.
 
-That comes at a cost. Experience continuity couples flag evaluation with database writes – every evaluation reads and writes to the DB to persist the result. This mixes two concerns (evaluation and storage) that should be separate, and it's the source of [known bugs](https://github.com/PostHog/posthog-js/issues/2623) where values can still change after `identify()`. It also means no support for [local evaluation](/docs/feature-flags/local-evaluation.md) and slower flag responses.
+That comes at a cost. Experience continuity couples flag evaluation with database writes – every evaluation reads and writes to the DB to persist the result. This mixes two concerns (evaluation and storage) that should be separate, and it's the source of [known bugs](https://github.com/PostHog/posthog-js/issues/2623) where values can still change after `identify()`. It also means no support for [local evaluation](https://posthog.com/docs/feature-flags/local-evaluation.md) and slower flag responses.
 
-The better fix is to make persistence unnecessary. Use [device bucketing](/docs/feature-flags/device-bucketing.md) for single-device consistency, or design your identity flow so the distinct ID [never changes](/docs/feature-flags/stable-identity-for-flags.md). If you need experience continuity today, treat it as a migration path toward proper [identity resolution](/docs/product-analytics/identity-resolution.md), not a permanent solution. The identity gap it papers over is the root cause of the most common flag issues – closing that gap eliminates the need for persistence entirely.
+The better fix is to make persistence unnecessary. Use [device bucketing](https://posthog.com/docs/feature-flags/device-bucketing.md) for single-device consistency, or design your identity flow so the distinct ID [never changes](https://posthog.com/docs/feature-flags/stable-identity-for-flags.md). If you need experience continuity today, treat it as a migration path toward proper [identity resolution](https://posthog.com/docs/product-analytics/identity-resolution.md), not a permanent solution. The identity gap it papers over is the root cause of the most common flag issues – closing that gap eliminates the need for persistence entirely.
 
 ## Evaluation architecture
 
@@ -103,13 +115,13 @@ If you target a flag on `plan_type: "pro"`, your app originally told PostHog thi
 
 If you evaluate client-side instead, the SDK needs to fetch that property from PostHog's servers – a round-trip to look up what you originally sent it. Any flag check before that completes evaluates against incomplete data.
 
-If you must evaluate client-side, use [`setPersonPropertiesForFlags()`](/docs/feature-flags/property-overrides.md#manual-overrides-with-setpersonpropertiesforflags) to set properties locally before evaluation. This avoids the round-trip when you already have the data in the browser.
+If you must evaluate client-side, use [`setPersonPropertiesForFlags()`](https://posthog.com/docs/feature-flags/property-overrides.md#manual-overrides-with-setpersonpropertiesforflags) to set properties locally before evaluation. This avoids the round-trip when you already have the data in the browser.
 
 Property targeting is fine – just understand that the further the evaluation is from the data, the more async complexity you take on.
 
 ### Server-side local evaluation is the recommended default
 
-[Server-side local evaluation](/docs/feature-flags/local-evaluation.md) is where the pure function model is fully legible:
+[Server-side local evaluation](https://posthog.com/docs/feature-flags/local-evaluation.md) is where the pure function model is fully legible:
 
 -   **All inputs are explicit.** You pass the distinct ID and properties directly. When something's wrong, you log what you passed.
 -   **Your data is right there.** User plan, account type, permissions – it's in your database at request time. No syncing, no fetching.
@@ -121,7 +133,7 @@ Client-side evaluation is right when you need properties only available in the b
 
 Client-side flag evaluation is async – the SDK needs to fetch values from PostHog. Any flag check before that completes returns `undefined`, not `false`.
 
-**[Bootstrap](/docs/feature-flags/bootstrapping.md) is the fix.** Evaluate flags server-side and pass values to the client at init. The value exists before the page renders – no gap, no flicker.
+**[Bootstrap](https://posthog.com/docs/feature-flags/bootstrapping.md) is the fix.** Evaluate flags server-side and pass values to the client at init. The value exists before the page renders – no gap, no flicker.
 
 If you can't bootstrap, use `onFeatureFlags()` to wait. This means you will need a loading state (spinner, skeleton) until flags arrive – it prevents showing the wrong variant but doesn't prevent a delay.
 
@@ -129,8 +141,6 @@ If you can't bootstrap, use `onFeatureFlags()` to wait. This means you will need
 
 `posthog.getFeatureFlag()` returns `undefined` before flags load. That means "not evaluated yet," not "flag is off."
 
-JavaScript
-
 ```javascript
 // Returns undefined before flags load – not false
 if (posthog.getFeatureFlag('my-experiment') === 'test') {
@@ -138,9 +148,9 @@ if (posthog.getFeatureFlag('my-experiment') === 'test') {
 }
 ```
 
-Handle it with [bootstrap](/docs/feature-flags/bootstrapping.md) (preferred) or `onFeatureFlags()` (adds a loading state). You can check the current identity with `posthog.get_distinct_id()`.
+Handle it with [bootstrap](https://posthog.com/docs/feature-flags/bootstrapping.md) (preferred) or `onFeatureFlags()` (adds a loading state). You can check the current identity with `posthog.get_distinct_id()`.
 
-The "not loaded yet" return value varies across SDKs – some return `undefined`/`nil`/`None`, others return `false` or a `defaultValue` you provide. Don't assume that a falsy return means the flag is off. Check your SDK's documentation for the exact return type of `getFeatureFlag()` and `isFeatureEnabled()` when flags haven't loaded, and handle that state explicitly. If your goal is to programmatically check whether a flag exists at all, use the [Feature Flags API](/docs/api/feature-flags.md) to query flag definitions directly.
+The "not loaded yet" return value varies across SDKs – some return `undefined`/`nil`/`None`, others return `false` or a `defaultValue` you provide. Don't assume that a falsy return means the flag is off. Check your SDK's documentation for the exact return type of `getFeatureFlag()` and `isFeatureEnabled()` when flags haven't loaded, and handle that state explicitly. If your goal is to programmatically check whether a flag exists at all, use the [Feature Flags API](https://posthog.com/docs/api/feature-flags.md) to query flag definitions directly.
 
 ## Flag hygiene
 
@@ -148,7 +158,7 @@ Flags are infrastructure. Like any infrastructure, they accumulate cost when lef
 
 ### Choose a flag type intentionally
 
-Every flag in PostHog is configured as client-side, server-side, or both via [evaluation contexts](/docs/feature-flags/evaluation-contexts.md). New flags default to "server and client" – this exists for backwards compatibility (it's how all flags worked before we added evaluation contexts) and to avoid blocking users who haven't thought about their implementation yet. It's a safe starting point, not a recommendation.
+Every flag in PostHog is configured as client-side, server-side, or both via [evaluation contexts](https://posthog.com/docs/feature-flags/evaluation-contexts.md). New flags default to "server and client" – this exists for backwards compatibility (it's how all flags worked before we added evaluation contexts) and to avoid blocking users who haven't thought about their implementation yet. It's a safe starting point, not a recommendation.
 
 If all your flags are set to both, that usually means the decision was never revisited after creation – and you're paying for client-side evaluation on flags that only need to exist on your server.
 
@@ -158,7 +168,7 @@ Pick the context based on where the flag is actually consumed. Server-side flags
 
 A flag set to 100% of all users with no property targeting is a flag that has finished its job. It's always returning the same value – the rollout is complete, the experiment concluded, the feature is live. If your SDK still evaluates that flag, it can keep making billable `/flags` requests, keep appearing in SDK payloads, and add clutter to your codebase.
 
-Remove the flag and hardcode the winning path. If you're not ready to remove it from code, at least archive it in PostHog so it stops being evaluated. Stale flags are the most common source of unnecessary flag evaluation. See [cleaning up stale flags](/docs/feature-flags/cleaning-up-stale-flags.md) for the full workflow and [cutting costs](/docs/feature-flags/cutting-costs.md) for more on reducing your bill.
+Remove the flag and hardcode the winning path. If you're not ready to remove it from code, at least archive it in PostHog so it stops being evaluated. Stale flags are the most common source of unnecessary flag evaluation. See [cleaning up stale flags](https://posthog.com/docs/feature-flags/cleaning-up-stale-flags.md) for the full workflow and [cutting costs](https://posthog.com/docs/feature-flags/cutting-costs.md) for more on reducing your bill.
 
 **An idea worth considering:** design your flag code paths with an escape hatch you control outside of PostHog. For example, a "gate flag" that your server reads once every 30 seconds (not per user) – when it's `true`, the feature is fully rolled out and your code skips the per-user flag evaluation entirely. This means you stop making per-user `/flags` requests for that rollout as soon as it's complete, even before you remove the flag from code. And you can dial it back by setting the gate flag to `false`. This is also another application of "evaluate once, not continuously" – if you cache flag results, your per-user evaluation cost drops while you wait for the code cleanup.
 
@@ -170,14 +180,12 @@ This is the practical extension of "evaluate once, not continuously." Your serve
 
 ### Use a reverse proxy
 
-Ad blockers can disable your Feature Flags, leading to users seeing the wrong version of your app or missing a rollout. Deploy a [reverse proxy](/docs/advanced/proxy.md) so requests go through your own domain. PostHog offers a free [managed reverse proxy](/docs/advanced/proxy/managed-reverse-proxy.md), or you can run your own.
+Ad blockers can disable your Feature Flags, leading to users seeing the wrong version of your app or missing a rollout. Deploy a [reverse proxy](https://posthog.com/docs/advanced/proxy.md) so requests go through your own domain. PostHog offers a free [managed reverse proxy](https://posthog.com/docs/advanced/proxy/managed-reverse-proxy.md), or you can run your own.
 
 ### Call your flag in as few places as possible
 
 The more locations a flag appears in your code, the more likely it is to cause problems – a developer removes it in one place but forgets another. If you use a flag in multiple places, wrap it in a single function:
 
-JavaScript
-
 ```javascript
 function useBetaFeature() {
     return posthog.isFeatureEnabled('beta-feature')
@@ -195,11 +203,11 @@ Good naming makes flags easier to understand and maintain:
 
 ### Roll out progressively
 
-Start at 5-10% of users, monitor metrics, then gradually increase. This is a [phased rollout](/tutorials/phased-rollout.md). At PostHog, we typically roll out to the developer first, then the internal team, then beta users, then everyone.
+Start at 5-10% of users, monitor metrics, then gradually increase. This is a [phased rollout](https://posthog.com/tutorials/phased-rollout.md). At PostHog, we typically roll out to the developer first, then the internal team, then beta users, then everyone.
 
 ### Use dependencies for complex rollouts
 
-[Feature flag dependencies](/docs/feature-flags/dependencies.md) let one flag's activation depend on another flag's state – useful for enabling complex features only after foundational components are active, or running Experiments only on users with specific features enabled. Keep dependency chains simple and avoid circular dependencies.
+[Feature flag dependencies](https://posthog.com/docs/feature-flags/dependencies.md) let one flag's activation depend on another flag's state – useful for enabling complex features only after foundational components are active, or running Experiments only on users with specific features enabled. Keep dependency chains simple and avoid circular dependencies.
 
 ### Be careful with "Latest" person properties
 
@@ -207,19 +215,11 @@ PostHog automatically creates person properties like "Latest Current URL" and "L
 
 ### Reducing your bill
 
-Stale flags are the most common source of unnecessary cost. Beyond cleaning up flags, see our [dedicated guide to cutting costs](/docs/feature-flags/cutting-costs.md) for estimating and reducing your feature flag bill.
+Stale flags are the most common source of unnecessary cost. Beyond cleaning up flags, see our [dedicated guide to cutting costs](https://posthog.com/docs/feature-flags/cutting-costs.md) for estimating and reducing your feature flag bill.
 
 ## Further reading
 
--   [Identity resolution](/docs/product-analytics/identity-resolution.md) – how PostHog resolves who a user is
--   [Keeping flag evaluations stable](/docs/feature-flags/stable-identity-for-flags.md) – preventing the hash input from changing across auth transitions
--   [Local evaluation](/docs/feature-flags/local-evaluation.md) – server-side evaluation for explicit input control
--   [Bootstrapping](/docs/feature-flags/bootstrapping.md) – having flag values before the page renders
-
-### Still have questions?
-
-Ask PostHog AI
-
-### Was this page useful?
-
-HelpfulCould be better
+-   [Identity resolution](https://posthog.com/docs/product-analytics/identity-resolution.md) – how PostHog resolves who a user is
+-   [Keeping flag evaluations stable](https://posthog.com/docs/feature-flags/stable-identity-for-flags.md) – preventing the hash input from changing across auth transitions
+-   [Local evaluation](https://posthog.com/docs/feature-flags/local-evaluation.md) – server-side evaluation for explicit input control
+-   [Bootstrapping](https://posthog.com/docs/feature-flags/bootstrapping.md) – having flag values before the page renders

package/dist/global-skills/instrument-feature-flags/references/django.md

@@ -2,18 +2,29 @@
 
 # Django
 
+Canonical URL: https://posthog.com/docs/libraries/django
+
+> **Cloud region:** This page uses US Cloud hosts. For an EU Cloud project, use `https://eu.i.posthog.com` instead of `https://us.i.posthog.com` (ingestion host), and use `https://eu.posthog.com` instead of `https://app.posthog.com` (app host for links).
+
+## On this page
+
+- [Beta: integration via LLM](#beta-integration-via-llm)
+- [Installation](#installation)
+- [Identifying users](#identifying-users)
+- [Django contexts middleware](#django-contexts-middleware)
+- [Next steps](#next-steps)
+- [Supported versions](#supported-versions)
+
 PostHog makes it easy to get data about traffic and usage of your Django app. Integrating PostHog enables analytics, custom events capture, feature flags, error tracking, and more.
 
-This guide walks you through integrating PostHog into your Django app using the [Python SDK](/docs/libraries/python.md).
+This guide walks you through integrating PostHog into your Django app using the [Python SDK](https://posthog.com/docs/libraries/python.md).
 
 ## Beta: integration via LLM
 
-Install PostHog for Django in seconds with our wizard by running this prompt with [LLM coding agents](/blog/envoy-wizard-llm-agent.md) like Cursor and Bolt, or by running it in your terminal.
+Install PostHog for Django in seconds with our wizard by running this prompt with [LLM coding agents](https://posthog.com/blog/envoy-wizard-llm-agent.md) like Cursor and Bolt, or by running it in your terminal.
 
 `npx @posthog/wizard`
 
-[Learn more](/wizard.md)
-
 Or, to integrate manually, continue with the rest of this guide.
 
 > These docs cover version `7.x` of the Python SDK, which requires Python 3.10 or higher. On Python 3.9? See [supported versions](#supported-versions).
@@ -53,8 +64,6 @@ You can find your project token and instance address in [your project settings](
 
 To capture events from any file, import `posthog` and call the method you need. For example:
 
-Python
-
 ```python
 import posthog
 from posthog import identify_context
@@ -69,7 +78,7 @@ def some_request(request):
         posthog.capture('event_name')
 ```
 
-Events captured without a context or explicit `distinct_id` are sent as [anonymous events](/docs/data/anonymous-vs-identified-events.md) with an auto-generated `distinct_id`. See the [Python SDK docs](/docs/libraries/python.md#person-profiles-and-properties) for more details.
+Events captured without a context or explicit `distinct_id` are sent as [anonymous events](https://posthog.com/docs/data/anonymous-vs-identified-events.md) with an auto-generated `distinct_id`. See the [Python SDK docs](https://posthog.com/docs/libraries/python.md#person-profiles-and-properties) for more details.
 
 ## Identifying users
 
@@ -77,8 +86,6 @@ Events captured without a context or explicit `distinct_id` are sent as [anonymo
 >
 > In Python, you can do this through a context. All event captures in the same context will be tagged automatically with the correct `distinct_id`. Typically, you would set a fresh context and identify at the top of each route.
 >
-> Python
->
 > ```python
 > from posthog import new_context, identify_context, capture
 >
@@ -94,18 +101,16 @@ Events captured without a context or explicit `distinct_id` are sent as [anonymo
 
 ## Django contexts middleware
 
-The Python SDK provides a Django middleware that automatically wraps all requests with a [context](/docs/libraries/python.md#contexts). This middleware extracts session and user information from each request and tags all events captured during that request with relevant metadata.
+The Python SDK provides a Django middleware that automatically wraps all requests with a [context](https://posthog.com/docs/libraries/python.md#contexts). This middleware extracts session and user information from each request and adds relevant properties to events captured during that request.
 
 ### Basic setup
 
 Add the middleware to your Django settings. If your app uses Django authentication, place it after `django.contrib.auth.middleware.AuthenticationMiddleware` so the middleware can use the authenticated Django user as a distinct ID fallback and capture the user's email.
 
-Python
-
 ```python
 MIDDLEWARE = [
     # ... other middleware
-    'posthog.integrations.django.PosthogContextMiddleware',
+    "posthog.integrations.django.PosthogContextMiddleware",
     # ... other middleware
 ]
 ```
@@ -114,8 +119,8 @@ The middleware uses the globally configured `posthog` client by default, so you
 
 The middleware automatically extracts and uses:
 
--   **Session ID** from the `X-POSTHOG-SESSION-ID` header, if present
--   **Distinct ID** from the `X-POSTHOG-DISTINCT-ID` header, if present, falling back to the authenticated Django user's `pk` (Django's primary-key alias, which works with custom user models)
+-   **Session ID** from the `X-POSTHOG-SESSION-ID` header when you enable `POSTHOG_MW_TRUST_TRACING_HEADERS`
+-   **Distinct ID** from the authenticated Django user's `pk` (Django's primary-key alias, which works with custom user models), or from the `X-POSTHOG-DISTINCT-ID` header when you enable `POSTHOG_MW_TRUST_TRACING_HEADERS`
 -   **User email** from the authenticated Django user's `email` as `email`
 -   **Current URL** as `$current_url`
 -   **Request method** as `$request_method`
@@ -123,7 +128,14 @@ The middleware automatically extracts and uses:
 -   **Forwarded IP address** from `X-Forwarded-For` as `$ip`
 -   **User agent** from `User-Agent` as `$user_agent`
 
-The session and distinct ID headers are sanitized before use. Empty values are ignored, control characters are removed, values are trimmed, and values are capped at 1000 characters.
+The middleware ignores the session and distinct ID headers by default because clients can control them. To use them as analytics context, enable them in your Django settings:
+
+```python
+# settings.py
+POSTHOG_MW_TRUST_TRACING_HEADERS = True
+```
+
+Don't use these headers for authentication or authorization. The middleware sanitizes trusted header values before use. It ignores empty values, removes control characters, trims values, and caps them at 1000 characters.
 
 All events captured during the request (including exceptions) include these properties and are associated with the extracted session and distinct ID.
 
@@ -133,8 +145,6 @@ The middleware reads `request.user` once, before your view runs. On a login or s
 
 Identify the context from inside the request once you know who the user is. Django's auth signals are the natural place:
 
-Python
-
 ```python
 from django.contrib.auth.signals import user_logged_in
 from django.dispatch import receiver
@@ -147,7 +157,7 @@ def identify_posthog_user(sender, request, user, **kwargs):
 
 Every capture later in that request is then attributed to the user who just logged in. Requests made after login don't need this. The middleware sees the authenticated user from the start.
 
-If you're using [PostHog JavaScript Web](/docs/libraries/js.md) on the frontend, configure [`tracing_headers`](/docs/libraries/js/config.md#tracing-headers) for your Django backend hostname so browser requests include the session and distinct ID headers.
+If you're using [PostHog JavaScript Web](https://posthog.com/docs/libraries/js.md) on the frontend, configure [`tracing_headers`](https://posthog.com/docs/libraries/js/config.md#tracing-headers) for your Django backend hostname so browser requests include the session and distinct ID headers. You must also set `POSTHOG_MW_TRUST_TRACING_HEADERS = True` in Django to accept them.
 
 ### Exception capture
 
@@ -155,120 +165,166 @@ By default, the middleware captures exceptions and sends them to PostHog's error
 
 Disable this by setting:
 
-Python
-
 ```python
 # settings.py
 POSTHOG_MW_CAPTURE_EXCEPTIONS = False
 ```
 
-### Adding custom tags
+Set `POSTHOG_MW_CAPTURE_EXCEPTIONS = None` to inherit the global client's `enable_exception_autocapture` setting. When you omit `POSTHOG_MW_CAPTURE_EXCEPTIONS`, the middleware preserves the existing Django default and captures exceptions.
+
+### Capture Django REST Framework exceptions
 
-Use `POSTHOG_MW_EXTRA_TAGS` to add custom properties to all requests:
+This integration requires version `7.69.0` or later of the Python SDK.
 
-Python
+Django REST Framework (DRF) converts many exceptions into responses before Django middleware can observe them. Add PostHog's DRF exception handler to capture these handled errors:
 
 ```python
 # settings.py
-def add_user_tags(request):
+REST_FRAMEWORK = {
+    # ... other DRF settings
+    "EXCEPTION_HANDLER": "posthog.integrations.drf.exception_handler",
+}
+```
+
+Keep `PosthogContextMiddleware` enabled. The middleware adds request properties and identity to the active context, while the DRF handler captures handled API exceptions. The handler captures responses with a `5xx` status by default and ignores expected `4xx` responses. If DRF doesn't handle an exception, Django re-raises it and the middleware captures it instead.
+
+If you already use a custom DRF exception handler, wrap it in an application module:
+
+```python
+# your_app/exception_handlers.py
+from posthog.integrations.drf import create_exception_handler
+from your_app.api import existing_exception_handler
+
+exception_handler = create_exception_handler(existing_exception_handler)
+```
+
+Then point DRF to the wrapper:
+
+```python
+# settings.py
+REST_FRAMEWORK = {
+    "EXCEPTION_HANDLER": "your_app.exception_handlers.exception_handler",
+}
+```
+
+To capture selected `4xx` responses, create a handler with `capture_4xx=True` and an exception filter:
+
+```python
+# your_app/exception_handlers.py
+from posthog.integrations.drf import create_exception_handler
+
+
+def capture_auth_errors(exception, response, context):
+    return response.status_code >= 500 or response.status_code in {401, 403}
+
+
+exception_handler = create_exception_handler(
+    capture_4xx=True,
+    exception_filter=capture_auth_errors,
+)
+```
+
+The DRF handler follows `POSTHOG_MW_CAPTURE_EXCEPTIONS` and `POSTHOG_MW_REQUEST_FILTER`. You can also pass `capture_exceptions=True` or `capture_exceptions=False` to `create_exception_handler()` to override the middleware setting.
+
+### Add custom properties
+
+Use `POSTHOG_MW_EXTRA_PROPERTIES` to add custom properties to all requests:
+
+```python
+# settings.py
+def add_user_properties(request):
     # type: (HttpRequest) -> Dict[str, Any]
-    tags = {}
-    if hasattr(request, 'user') and request.user.is_authenticated:
+    properties = {}
+    if hasattr(request, "user") and request.user.is_authenticated:
         # Use pk instead of id so this works with custom User primary keys.
-        tags['user_id'] = str(request.user.pk)
-        tags['email'] = request.user.email
-    return tags
+        properties["user_id"] = str(request.user.pk)
+        properties["email"] = request.user.email
+    return properties
 
-POSTHOG_MW_EXTRA_TAGS = add_user_tags
+POSTHOG_MW_EXTRA_PROPERTIES = add_user_properties
 ```
 
-#### Filtering requests
+### Filter requests
 
 Skip tracking for certain requests using `POSTHOG_MW_REQUEST_FILTER`:
 
-Python
-
 ```python
 # settings.py
 def should_track_request(request):
     # type: (HttpRequest) -> bool
     # Don't track health checks or admin requests
-    if request.path.startswith('/health') or request.path.startswith('/admin'):
+    if request.path.startswith("/health") or request.path.startswith("/admin"):
         return False
     return True
 
 POSTHOG_MW_REQUEST_FILTER = should_track_request
 ```
 
-### Modifying default tags
+### Modify default properties
 
-Use `POSTHOG_MW_TAG_MAP` to modify or remove default tags:
-
-Python
+Use `POSTHOG_MW_PROPERTIES_MAP` to modify or remove default properties:
 
 ```python
 # settings.py
-def customize_tags(tags):
+def customize_properties(properties):
     # type: (Dict[str, Any]) -> Dict[str, Any]
     # Remove URL for privacy
-    tags.pop('$current_url', None)
+    properties.pop("$current_url", None)
     # Add custom prefix to method
-    if '$request_method' in tags:
-        tags['http_method'] = tags.pop('$request_method')
-    return tags
+    if "$request_method" in properties:
+        properties["http_method"] = properties.pop("$request_method")
+    return properties
 
-POSTHOG_MW_TAG_MAP = customize_tags
+POSTHOG_MW_PROPERTIES_MAP = customize_properties
 ```
 
 ### Complete configuration example
 
-Python
-
 ```python
 # settings.py
 def add_request_context(request):
     # type: (HttpRequest) -> Dict[str, Any]
-    tags = {}
-    if hasattr(request, 'user') and request.user.is_authenticated:
-        tags['user_type'] = 'authenticated'
+    properties = {}
+    if hasattr(request, "user") and request.user.is_authenticated:
+        properties["user_type"] = "authenticated"
         # Use pk instead of id so this works with custom User primary keys.
-        tags['user_id'] = str(request.user.pk)
+        properties["user_id"] = str(request.user.pk)
     else:
-        tags['user_type'] = 'anonymous'
+        properties["user_type"] = "anonymous"
 
     # Add request info
-    tags['user_agent'] = request.META.get('HTTP_USER_AGENT', '')
-    return tags
+    properties["user_agent"] = request.META.get("HTTP_USER_AGENT", "")
+    return properties
 
 def filter_tracking(request):
     # type: (HttpRequest) -> bool
     # Skip internal endpoints
-    return not request.path.startswith(('/health', '/metrics', '/admin'))
+    return not request.path.startswith(("/health", "/metrics", "/admin"))
 
-def clean_tags(tags):
+def clean_properties(properties):
     # type: (Dict[str, Any]) -> Dict[str, Any]
     # Remove sensitive data
-    tags.pop('user_agent', None)
-    return tags
+    properties.pop("user_agent", None)
+    return properties
 
-POSTHOG_MW_EXTRA_TAGS = add_request_context
+POSTHOG_MW_EXTRA_PROPERTIES = add_request_context
 POSTHOG_MW_REQUEST_FILTER = filter_tracking
-POSTHOG_MW_TAG_MAP = clean_tags
+POSTHOG_MW_PROPERTIES_MAP = clean_properties
 POSTHOG_MW_CAPTURE_EXCEPTIONS = True
 ```
 
-All events captured within the request context automatically include the configured tags and are associated with the session and user identified from the request headers or Django authentication.
+All events captured within the request context automatically include the configured properties. They use the authenticated Django user as the distinct ID, or the session and distinct ID from request headers when you enable `POSTHOG_MW_TRUST_TRACING_HEADERS`.
 
 The middleware supports both sync (WSGI) and async (ASGI) Django applications. In async mode, it uses Django's `request.auser()` API when available to avoid synchronous user access.
 
 ## Next steps
 
-For any technical questions for how to integrate specific PostHog features into Django (such as analytics, feature flags, A/B testing, etc.), have a look at our [Python SDK docs](/docs/libraries/python.md).
+For any technical questions for how to integrate specific PostHog features into Django (such as analytics, feature flags, A/B testing, etc.), have a look at our [Python SDK docs](https://posthog.com/docs/libraries/python.md).
 
 Alternatively, the following tutorials can help you get started:
 
--   [Setting up Django analytics, feature flags, and more](/tutorials/django-analytics.md)
--   [How to set up A/B tests in Django](/tutorials/django-ab-tests.md)
+-   [Setting up Django analytics, feature flags, and more](https://posthog.com/tutorials/django-analytics.md)
+-   [How to set up A/B tests in Django](https://posthog.com/tutorials/django-ab-tests.md)
 
 ## Supported versions
 
@@ -277,11 +333,3 @@ These docs cover version `7.x` of the PostHog Python SDK, which requires Python
 Everything on this page works the same way on `6.9.3`. Event capture, the context API (`new_context`, `identify_context`, `set_context_session`), and `PosthogContextMiddleware` are identical on `6.9.3` and `7.0.0` — `7.0.0` only dropped Python 3.9 and bumped the optional LLM provider SDKs. That includes the middleware identifying the request context from the `X-POSTHOG-DISTINCT-ID` header and falling back to the authenticated user, which behaves the same across both lines.
 
 Later `7.x` releases add what the 6.x line does not receive, such as the Celery integration, tracing header sanitization, and `set_context_device_id`. They also changed the middleware's own captured properties: `7.x` sends the request IP as `$ip`, where `6.9.3` sends it as `$ip_address`, and `7.x` additionally captures `$request_path`, `$raw_user_agent`, and the authenticated user's `email`.
-
-### Still have questions?
-
-Ask PostHog AI
-
-### Was this page useful?
-
-HelpfulCould be better