vybekiit 0.7.3 → 0.7.7

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

@@ -1,3 +1,9 @@
+> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
+
+# Next.js - Docs
+
+Copy page
+
 # Next.js - Docs
 
 PostHog makes it easy to get data about traffic and usage of your [Next.js](https://nextjs.org/) app. Integrating PostHog into your site enables analytics about user behavior, custom events capture, session recordings, feature flags, and more.
@@ -57,6 +63,18 @@ pnpm add posthog-js
 bun add posthog-js
 ```
 
+> **If your site sets a Content-Security-Policy**, it needs to allow PostHog. This applies to the snippet and to package installs alike: the SDK lazy-loads extra bundles (session replay, surveys) from PostHog's CDN, and sends events to the ingestion host. PostHog serves from subdomains of `posthog.com` that change over time, so allow the wildcard:
+>
+> PostHog AI
+>
+> ```
+> script-src 'self' https://*.posthog.com;
+> connect-src 'self' https://*.posthog.com;
+> worker-src 'self' blob: data:;
+> ```
+>
+> `script-src` covers the snippet and the lazy-loaded bundles, `connect-src` covers event ingestion and feature flags, and `worker-src` covers session replay. The [toolbar needs a few more](/docs/advanced/content-security-policy.md), or use a [reverse proxy](/docs/advanced/proxy.md) so everything is first-party. Failing to do so causes silent failures where `capture` and `identify` calls never send, so the integration looks complete while zero events arrive. Remember `connect-src` falls back to `default-src`, so `default-src 'self'` blocks event delivery even when the script itself is bundled.
+
 Add your environment variables to your `.env.local` file and to your hosting provider (e.g. Vercel, Netlify, AWS). You can find your project token in your [project settings](https://app.posthog.com/project/settings).
 
 .env.local
@@ -113,8 +131,34 @@ See the [bootstrapping guide](/docs/feature-flags/bootstrapping.md) for more inf
 
 > **Identifying users is required.** Call `posthog.identify('your-user-id')` after login to link events to a known user. This is what connects frontend event captures, [session replays](/docs/session-replay.md), [LLM traces](/docs/ai-engineering.md), and [error tracking](/docs/error-tracking.md) to the same person — and lets backend events link back too.
 >
+> Use a stable ID from your auth system when possible, not an email or display name. Send those as person properties instead. If your app has no other stable key, email works as a fallback if they are unique. Never a shared literal like `"anonymous"` or `"user"`, which pools many people onto one person and corrupts their data. When no ID is available at all, skip the identify and retain the anonymous distinct ID that's automatically assigned.
+>
+> Call `posthog.reset()` on logout, so the next person to use the browser doesn't inherit the last one's identity.
+>
 > See our guide on [identifying users](/docs/getting-started/identify-users.md) for how to set this up.
 
+### Linking client and server events
+
+Next.js apps usually capture on both sides. To keep them on the same person, use the same distinct ID in both, and let the browser tell your server which one that is.
+
+If your app calls your own backend, `tracing_headers` adds `X-POSTHOG-DISTINCT-ID` and `X-POSTHOG-SESSION-ID` to matching `fetch` and `XMLHttpRequest` requests. This lets server-side SDKs link backend events, errors, and LLM traces back to frontend sessions and replays. Use hostnames only, without protocols or paths.
+
+JavaScript
+
+PostHog AI
+
+```javascript
+posthog.init('<ph_project_token>', {
+  api_host: 'https://us.i.posthog.com',
+  // Optional: send PostHog session/user context to your backend
+  tracing_headers: ['api.example.com'],
+})
+```
+
+This works in local development too, but match on the hostname alone: use `'localhost'`, not `'localhost:3000'`. Ports are never part of a hostname, so a value with one in it never matches anything. `localhost` and `127.0.0.1` are also different hostnames — use whichever your app actually calls.
+
+Tracing headers help you attribute events across front and backend consistently. When this isn't available, use your server-side stable IDs to deduce the matching `distinctId`, and pass it in when capturing the event.
+
 Set up a reverse proxy (recommended)
 
 We recommend [setting up a reverse proxy](/docs/advanced/proxy.md), so that events are less likely to be intercepted by tracking blockers.
@@ -183,7 +227,7 @@ See the [React SDK docs](/docs/libraries/react.md) for examples of how to use:
 -   [`posthog-js` functions like custom event capture, user identification, and more.](/docs/libraries/react.md#using-posthog-js-functions)
 -   [Feature flags including variants and payloads.](/docs/libraries/react.md#feature-flags)
 
-You can also read [the full `posthog-js` documentation](/docs/libraries/js/features.md) for all the usable functions.
+You can also read [the full `posthog-js` documentation](/docs/libraries/js/usage.md) for all the usable functions.
 
 ## Server-side analytics
 
@@ -288,6 +332,7 @@ PostHog AI
 // pages/posts/[id].js
 import { useContext, useEffect, useState } from 'react'
 import { getServerSession } from "next-auth/next"
+import { authOptions } from '@/lib/auth'
 import { PostHog } from 'posthog-node'
 export default function Post({ post, flags }) {
   const [ctaState, setCtaState] = useState()
@@ -309,7 +354,8 @@ export default function Post({ post, flags }) {
   )
 }
 export async function getServerSideProps(ctx) {
-  const session = await getServerSession(ctx.req, ctx.res)
+  // Pass authOptions, or your session callbacks don't run.
+  const session = await getServerSession(ctx.req, ctx.res, authOptions)
   let flags = null
   if (session) {
     const client = new PostHog(
@@ -318,9 +364,11 @@ export async function getServerSideProps(ctx) {
         host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
       }
     )
-    flags = await client.getAllFlags(session.user.email);
+    // A stable ID from your auth system, not an email. See the note below.
+    const distinctId = session.user.id
+    flags = await client.getAllFlags(distinctId);
     client.capture({
-      distinctId: session.user.email,
+      distinctId,
       event: 'loaded blog article',
       properties: {
         $current_url: ctx.req.url,
@@ -339,6 +387,28 @@ export async function getServerSideProps(ctx) {
 }
 ```
 
+> **Note**: next-auth doesn't put a user ID on the session by default. Its session is `{ name, email, image }`, so `session.user.id` is `undefined` until you add it yourself with a session callback in your `authOptions`:
+>
+> JavaScript
+>
+> PostHog AI
+>
+> ```javascript
+> // lib/auth.js
+> export const authOptions = {
+>   callbacks: {
+>     session({ session, token, user }) {
+>       // JWT sessions (the default) carry the user ID in token.sub.
+>       // Database sessions get it from user.id instead.
+>       session.user.id = token?.sub ?? user.id
+>       return session
+>     },
+>   },
+> }
+> ```
+>
+> Capturing with an `undefined` distinct ID creates events that belong to nobody, so check that the ID arrives before relying on it.
+
 > **Note**: Make sure to *always* call `await client.shutdown()` after sending events from the server-side. PostHog queues events into larger batches, and this call forces all batched events to be flushed immediately.
 
 ### Server-side configuration
@@ -374,10 +444,6 @@ To improve the reliability of client-side tracking and make requests less likely
 -   [How to set up Next.js pages router analytics, feature flags, and more](/tutorials/nextjs-pages-analytics.md)
 -   [How to set up Next.js A/B tests](/tutorials/nextjs-ab-tests.md)
 
-### Community questions
-
-Ask a question
-
 ### Was this page useful?
 
 HelpfulCould be better

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

@@ -1,3 +1,9 @@
+> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
+
+# Node.js Feature Flags installation - Docs
+
+Copy page
+
 # Node.js Feature Flags installation - Docs
 
 1.  1
@@ -207,10 +213,6 @@
     | [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 |
 
-### Community questions
-
-Ask a question
-
 ### Was this page useful?
 
 HelpfulCould be better

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

@@ -1,3 +1,9 @@
+> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
+
+# PHP Feature Flags installation - Docs
+
+Copy page
+
 # PHP Feature Flags installation - Docs
 
 1.  1
@@ -178,10 +184,6 @@
     | [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 |
 
-### Community questions
-
-Ask a question
-
 ### Was this page useful?
 
 HelpfulCould be better

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

@@ -1,3 +1,9 @@
+> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
+
+# Python Feature Flags installation - Docs
+
+Copy page
+
 # Python Feature Flags installation - Docs
 
 1.  1
@@ -182,10 +188,6 @@
     | [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 |
 
-### Community questions
-
-Ask a question
-
 ### Was this page useful?
 
 HelpfulCould be better

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

@@ -1,3 +1,9 @@
+> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
+
+# React Native Feature Flags installation - Docs
+
+Copy page
+
 # React Native Feature Flags installation - Docs
 
 1.  1
@@ -157,10 +163,6 @@
     | [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 |
 
-### Community questions
-
-Ask a question
-
 ### Was this page useful?
 
 HelpfulCould be better

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

@@ -1,3 +1,9 @@
+> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
+
+# React Feature Flags installation - Docs
+
+Copy page
+
 # React Feature Flags installation - Docs
 
 1.  1
@@ -293,10 +299,6 @@
     | [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 |
 
-### Community questions
-
-Ask a question
-
 ### Was this page useful?
 
 HelpfulCould be better

package/dist/global-skills/instrument-feature-flags/references/ruby-on-rails.md

@@ -1,3 +1,9 @@
+> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
+
+# Ruby on Rails - Docs
+
+Copy page
+
 # Ruby on Rails - Docs
 
 PostHog makes it easy to get data about traffic and usage of your Ruby on Rails app. Integrating PostHog enables analytics, custom event capture, feature flags, and automatic exception tracking.
@@ -595,10 +601,6 @@ Ensure you've set `personal_api_key` in your configuration.
 
 For any technical questions for how to integrate specific PostHog features into Rails (such as analytics, feature flags, A/B testing, etc.), have a look at our [Ruby SDK docs](/docs/libraries/ruby.md).
 
-### Community questions
-
-Ask a question
-
 ### Was this page useful?
 
 HelpfulCould be better

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

@@ -1,3 +1,9 @@
+> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
+
+# Ruby Feature Flags installation - Docs
+
+Copy page
+
 # Ruby Feature Flags installation - Docs
 
 1.  1
@@ -191,10 +197,6 @@
     | [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 |
 
-### Community questions
-
-Ask a question
-
 ### Was this page useful?
 
 HelpfulCould be better

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

@@ -1,3 +1,9 @@
+> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
+
+# Rust Feature Flags installation - Docs
+
+Copy page
+
 # Rust Feature Flags installation - Docs
 
 Install the `posthog-rs` crate by adding it to your `Cargo.toml`.
@@ -213,10 +219,6 @@ Now that you're evaluating flags, continue with the resources below to learn wha
 | [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 |
 
-### Community questions
-
-Ask a question
-
 ### Was this page useful?
 
 HelpfulCould be better

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

@@ -1,3 +1,9 @@
+> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
+
+# iOS SDK usage - Docs
+
+Copy page
+
 # iOS SDK usage - Docs
 
 ## Capturing events
@@ -534,6 +540,41 @@ PostHogSDK.shared.captureFeatureView(flag: "flag-key", flagVariant: "variant-key
 PostHogSDK.shared.captureFeatureInteraction(flag: "flag-key", flagVariant: "variant-key")
 ```
 
+### Bootstrapping flags
+
+Since there is a delay between initializing PostHog and fetching feature flags, feature flags are not always available immediately. This makes them unusable if you want to do something like redirecting a user to a different page based on a feature flag.
+
+To have your feature flags available immediately, you can initialize PostHog with precomputed values until it has had a chance to fetch them. This is called bootstrapping. After the SDK fetches feature flags from PostHog, it will use those flag values instead of bootstrapped ones.
+
+Set `config.bootstrap` before calling `setup()` to seed identity and flag values before the first `/flags` response (requires iOS SDK `3.66.0`+):
+
+Swift
+
+PostHog AI
+
+```swift
+let config = PostHogConfig(projectToken: "<ph_project_token>", host: "https://us.i.posthog.com")
+config.bootstrap = PostHogBootstrapConfig(
+    distinctId: "distinct_id_of_your_user",
+    isIdentifiedId: true,
+    featureFlags: [
+        "flag-1": true,
+        "variant-flag": "control"
+    ],
+    featureFlagPayloads: nil
+)
+PostHogSDK.shared.setup(config)
+```
+
+-   **Bootstrapped identity applies during setup.** On a fresh install, setting it before `setup()` means events captured synchronously during initialization (like `Application Installed`) carry your distinct ID instead of the SDK-generated UUID.
+    -   An **anonymous** bootstrap (`isIdentifiedId: false`, the default) seeds the anonymous ID only when none is persisted yet. Once an anonymous ID exists on disk, or the person has been identified, the SDK ignores it.
+    -   An **identified** bootstrap (`isIdentifiedId: true`) is for a signed-in identity available to your app (for example, from a backend session token). On a fresh install, it seeds the distinct ID, marks the person identified, and generates a separate device ID. On a returning install, a matching anonymous ID is marked identified without emitting `$identify`; a different anonymous ID is merged via `identify()` when person profiles are enabled. This emits `$identify` unless capturing is opted out. A different, already-identified person is left untouched.
+-   **Bootstrapped flags are served until the first `/flags` response, then replaced.** A complete `/flags` response takes over entirely, so bootstrapped-only keys don't persist past it. Only *enabled* flags are seeded: a `true` boolean or a non-empty variant string. A `false` or empty value is dropped, matching posthog-js. Seed payloads with the separate `featureFlagPayloads` option. Flag values and payloads must be JSON-serializable, or they're dropped. Bootstrapped flags are cleared on `reset()`.
+
+The feature-flags-loaded signal fires as soon as bootstrapped flags are applied, so startup logic can read them immediately. These SDKs don't support the `sessionID` bootstrap option. When person profiles are set to `never`, the SDK preserves a different anonymous identity instead of merging it into an identified bootstrap.
+
+See the [SDK bootstrapping guide](/docs/libraries/bootstrapping.md) for the cross-SDK overview.
+
 ## Experiments (A/B tests)
 
 Since [experiments](/docs/experiments/start-here.md) use feature flags, the code for running an experiment is very similar to the feature flags code. See [adding experiment code](/docs/experiments/adding-experiment-code.md) for iOS examples.
@@ -591,10 +632,6 @@ PostHogSDK.shared.debug(true)
 PostHogSDK.shared.debug(false)
 ```
 
-### Community questions
-
-Ask a question
-
 ### Was this page useful?
 
 HelpfulCould be better

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

@@ -1,3 +1,9 @@
+> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
+
+# Web Feature Flags installation - Docs
+
+Copy page
+
 # Web Feature Flags installation - Docs
 
 1.  1
@@ -18,7 +24,7 @@
 
     ```html
     <script>
-        !function(t,e){var o,n,p,r;e.__SV||(window.posthog && window.posthog.__loaded)||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host.replace(".i.posthog.com","-assets.i.posthog.com")+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="init capture register register_once register_for_session unregister unregister_for_session getFeatureFlag getFeatureFlagResult isFeatureEnabled reloadFeatureFlags updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures on onFeatureFlags onSessionId getSurveys getActiveMatchingSurveys renderSurvey canRenderSurvey getNextSurveyStep identify setPersonProperties group resetGroups setPersonPropertiesForFlags resetPersonPropertiesForFlags setGroupPropertiesForFlags resetGroupPropertiesForFlags reset get_distinct_id getGroups get_session_id get_session_replay_url alias set_config startSessionRecording stopSessionRecording sessionRecordingStarted captureException loadToolbar get_property getSessionProperty createPersonProfile opt_in_capturing opt_out_capturing has_opted_in_capturing has_opted_out_capturing clear_opt_in_out_capturing debug".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
+        !function(t,e){var o,n,p,r;e.__SV||(window.posthog && window.posthog.__loaded)||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}p||((p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host.replace(".i.posthog.com","-assets.i.posthog.com")+"/static/array.js",p.onerror=function(){p=null},(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r));var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="init capture register register_once register_for_session unregister unregister_for_session getFeatureFlag getFeatureFlagResult isFeatureEnabled reloadFeatureFlags updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures on onFeatureFlags onSessionId getSurveys getActiveMatchingSurveys renderSurvey canRenderSurvey getNextSurveyStep identify setPersonProperties group resetGroups setPersonPropertiesForFlags resetPersonPropertiesForFlags setGroupPropertiesForFlags resetGroupPropertiesForFlags reset get_distinct_id getGroups get_session_id get_session_replay_url alias set_config startSessionRecording stopSessionRecording sessionRecordingStarted captureException loadToolbar get_property getSessionProperty createPersonProfile opt_in_capturing opt_out_capturing has_opted_in_capturing has_opted_out_capturing clear_opt_in_out_capturing debug".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
         posthog.init('<ph_project_token>', {
             api_host: 'https://us.i.posthog.com',
             defaults: '2026-05-30',
@@ -184,10 +190,6 @@
     | [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 |
 
-### Community questions
-
-Ask a question
-
 ### Was this page useful?
 
 HelpfulCould be better

package/dist/global-skills/instrument-product-analytics/SKILL.md

@@ -65,7 +65,7 @@ STEP 9: Set up environment variables.
 STEP 10: Verify and clean up.
   - Check the project for errors. Look for type checking or build scripts in package.json.
   - Ensure any components created were actually used.
-  - Run any linter or prettier-like scripts found in the package.json.
+  - Run any linter or prettier-like scripts found in the package.json, but ONLY on the files you have edited or created during this session. Never run formatting or linting across the entire project's codebase.
 
 ## Reference files
 
@@ -129,6 +129,7 @@ STEP 10: Verify and clean up.
 - `references/flutter.md` - Flutter - docs
 - `references/react-native.md` - React native - docs
 - `references/identify-users.md` - Identify users - docs
+- `references/COMMANDMENTS.md` - Framework-specific rules the integration must follow
 
 Each framework reference contains SDK-specific installation, initialization, and usage patterns. Find the one matching the user's stack.
 

package/dist/global-skills/instrument-product-analytics/references/COMMANDMENTS.md

@@ -0,0 +1,5 @@
+# Framework rules
+
+Follow these when integrating PostHog into this framework.
+
+- A missing PostHog configuration must never break the app — read keys optionally (never a required setting), guard init and capture behind their presence, and keep build and boot working with no PostHog environment set — but never silently: in development or debug builds fail loudly, using the language's idiomatic error, with the message "<VAR> variable required by PostHog is missing or un-configured, this causes events to be silently missed. This error stops appearing once <VAR> is configured" (substituting the actual variable name); production stays a no-op

package/dist/global-skills/instrument-product-analytics/references/EXAMPLE-astro-hybrid.md

@@ -24,14 +24,14 @@ This shows how to:
 - Opt specific pages into SSR with `export const prerender = false`
 - Keep most pages static for performance
 - Track events from API routes using `posthog-node`
-- Pass session IDs from client to server for unified sessions
+- Link client and server sessions automatically with the `tracing_headers` option
 
 ## Features
 
 - **Hybrid rendering**: Static pages by default, SSR when needed
 - **API routes**: Server-side endpoints for auth and event tracking
 - **Dual tracking**: Events captured on both client and server
-- **Session continuity**: Session ID passed to server via headers
+- **Session continuity**: Session and distinct ID forwarded automatically via `tracing_headers`
 - **Product analytics**: Track login and burrito consideration events
 - **Error tracking**: Manual error capture sent to PostHog
 
@@ -358,7 +358,10 @@ export default defineConfig({
   !function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="capture identify alias people.set people.set_once set_config register register_once unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled onFeatureFlags getFeatureFlag getFeatureFlagPayload reloadFeatureFlags group updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures getActiveMatchingSurveys getSurveys getNextSurveyStep onSessionId".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
   posthog.init(apiKey || '', {
     api_host: apiHost || 'https://us.i.posthog.com',
-    defaults: '2026-01-30'
+    defaults: '2026-01-30',
+    // Automatically add X-POSTHOG-SESSION-ID and X-POSTHOG-DISTINCT-ID headers
+    // to same-origin requests so server-side events join the same session.
+    tracing_headers: [window.location.hostname]
   })
 </script>
 
@@ -724,15 +727,13 @@ export const prerender = false;
       source: 'client'
     });
 
-    // Also send to server-side API for server tracking
+    // Also send to server-side API for server tracking. The session and distinct
+    // ID are added automatically by the tracing_headers option in posthog.init.
     try {
-      const sessionId = window.posthog?.get_session_id?.() || null;
-
       await fetch('/api/events/burrito', {
         method: 'POST',
         headers: {
-          'Content-Type': 'application/json',
-          'X-PostHog-Session-Id': sessionId || ''
+          'Content-Type': 'application/json'
         },
         body: JSON.stringify({
           username: currentUser,
@@ -844,15 +845,12 @@ import PostHogLayout from '../layouts/PostHogLayout.astro';
     }
 
     try {
-      // Get the session ID from PostHog to pass to the server
-      const sessionId = window.posthog?.get_session_id?.() || null;
-
-      // Call the server-side login API
+      // Call the server-side login API. The session and distinct ID are added
+      // automatically by the tracing_headers option configured in posthog.init.
       const response = await fetch('/api/auth/login', {
         method: 'POST',
         headers: {
-          'Content-Type': 'application/json',
-          'X-PostHog-Session-Id': sessionId || ''
+          'Content-Type': 'application/json'
         },
         body: JSON.stringify({ username, password })
       });

package/dist/global-skills/instrument-product-analytics/references/EXAMPLE-astro-ssr.md

@@ -20,7 +20,7 @@ This shows how to:
 
 - Initialize PostHog on both client and server
 - Track events from API routes using `posthog-node`
-- Pass session IDs from client to server for unified sessions
+- Link client and server sessions automatically with the `tracing_headers` option
 - Identify users on both client and server
 - Capture errors via `posthog.captureException()`
 - Reset PostHog state on logout
@@ -30,7 +30,7 @@ This shows how to:
 - **Server-side rendering**: Full SSR with `output: 'server'`
 - **API routes**: Server-side endpoints for auth and event tracking
 - **Dual tracking**: Events captured on both client and server
-- **Session continuity**: Session ID passed to server via headers
+- **Session continuity**: Session and distinct ID forwarded automatically via `tracing_headers`
 - **Product analytics**: Track login and burrito consideration events
 - **Session replay**: Enabled via PostHog snippet configuration
 - **Error tracking**: Manual error capture sent to PostHog
@@ -148,18 +148,24 @@ export const POST: APIRoute = async ({ request }) => {
 };
 ```
 
-### Passing session ID to server (`src/pages/index.astro`)
+### Passing session context to the server (`src/components/posthog.astro`)
+
+The `tracing_headers` option in `posthog.init` automatically adds the
+`X-POSTHOG-SESSION-ID` and `X-POSTHOG-DISTINCT-ID` headers to same-origin
+`fetch`/`XHR` requests, so the server route above receives them with no manual
+wiring:
 
 ```javascript
-// Get the session ID from PostHog to pass to the server
-const sessionId = window.posthog?.get_session_id?.() || null;
+posthog.init(apiKey, {
+  api_host: apiHost,
+  defaults: "2026-01-30",
+  tracing_headers: [window.location.hostname],
+});
 
+// Client fetches then need no PostHog headers of their own:
 const response = await fetch("/api/auth/login", {
   method: "POST",
-  headers: {
-    "Content-Type": "application/json",
-    "X-PostHog-Session-Id": sessionId || "",
-  },
+  headers: { "Content-Type": "application/json" },
   body: JSON.stringify({ username, password }),
 });
 ```
@@ -374,7 +380,10 @@ export default defineConfig({
   !function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="capture identify alias people.set people.set_once set_config register register_once unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled onFeatureFlags getFeatureFlag getFeatureFlagPayload reloadFeatureFlags group updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures getActiveMatchingSurveys getSurveys getNextSurveyStep onSessionId".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
   posthog.init(apiKey || '', {
     api_host: apiHost || 'https://us.i.posthog.com',
-    defaults: '2026-01-30'
+    defaults: '2026-01-30',
+    // Automatically add X-POSTHOG-SESSION-ID and X-POSTHOG-DISTINCT-ID headers
+    // to same-origin requests so server-side events join the same session.
+    tracing_headers: [window.location.hostname]
   })
 </script>
 
@@ -732,15 +741,13 @@ import PostHogLayout from '../layouts/PostHogLayout.astro';
       source: 'client'
     });
 
-    // Also send to server-side API for server tracking
+    // Also send to server-side API for server tracking. The session and distinct
+    // ID are added automatically by the tracing_headers option in posthog.init.
     try {
-      const sessionId = window.posthog?.get_session_id?.() || null;
-
       await fetch('/api/events/burrito', {
         method: 'POST',
         headers: {
-          'Content-Type': 'application/json',
-          'X-PostHog-Session-Id': sessionId || ''
+          'Content-Type': 'application/json'
         },
         body: JSON.stringify({
           username: currentUser,
@@ -849,15 +856,12 @@ import PostHogLayout from '../layouts/PostHogLayout.astro';
     }
 
     try {
-      // Get the session ID from PostHog to pass to the server
-      const sessionId = window.posthog?.get_session_id?.() || null;
-
-      // Call the server-side login API
+      // Call the server-side login API. The session and distinct ID are added
+      // automatically by the tracing_headers option configured in posthog.init.
       const response = await fetch('/api/auth/login', {
         method: 'POST',
         headers: {
-          'Content-Type': 'application/json',
-          'X-PostHog-Session-Id': sessionId || ''
+          'Content-Type': 'application/json'
         },
         body: JSON.stringify({ username, password })
       });