From 6ecb10284eb5b53ea8eb60ea388999a0df24df19 Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <29069505+gewenyu99@users.noreply.github.com>
Date: Tue, 30 Jun 2026 12:35:03 -0400
Subject: [PATCH 1/3] Use "project API token" terminology over "API key"
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Aligns the wording the wizard emits with PostHog's "project API token" terminology. The project token (the public phc_… ingestion key) was being called an "API key" in several skill descriptions and one example app, which is inconsistent with the project-token convention used everywhere else.

- Omnibus instrument-* skills: the credential step now asks for the "project API token" rather than the "API key".
- mcp-analytics: env var renamed POSTHOG_PROJECT_API_KEY → POSTHOG_PROJECT_TOKEN, prose updated to "project API token".
- PHP example app: POSTHOG_API_KEY → POSTHOG_PROJECT_TOKEN, matching every other example app.
- Renamed incidental local variables that hold a project token to projectToken (js-web, expo, react-native) for consistency with the node example.

Left untouched: genuine personal-API-key references (source-map upload / error tracking, local-evaluation keys, query-API personal keys) and the SDKs' own apiKey / api_key parameter names, which are fixed by the SDK signatures.

Why: feedback that the wizard's generated setup labels the project token as an "API key" instead of a token.

Generated-By: PostHog Code
Task-Id: 870391f2-b0c5-4a20-8534-7dd9607b7a48
---
 context/commandments.yaml                      |  2 +-
 context/skills/mcp-analytics/description.md    | 18 +++++++++---------
 .../instrument-error-tracking/description.md   |  2 +-
 .../instrument-feature-flags/description.md    |  2 +-
 .../instrument-integration/description.md      |  2 +-
 .../instrument-llm-analytics/description.md    |  2 +-
 .../omnibus/instrument-logs/description.md     |  2 +-
 .../description.md                             |  2 +-
 example-apps/expo/README.md                    |  2 +-
 example-apps/expo/src/config/posthog.ts        |  8 ++++----
 example-apps/javascript-web/src/posthog.js     |  6 +++---
 example-apps/php/.env.example                  |  2 +-
 example-apps/php/README.md                     |  6 +++---
 example-apps/php/todo.php                      |  8 ++++----
 example-apps/react-native/README.md            |  6 +++---
 .../react-native/src/config/posthog.ts         |  6 +++---
 16 files changed, 38 insertions(+), 38 deletions(-)

diff --git a/context/commandments.yaml b/context/commandments.yaml
index ff4afda1..18ffbd2c 100644
--- a/context/commandments.yaml
+++ b/context/commandments.yaml
@@ -170,7 +170,7 @@ commandments:
     - "capture_exception takes POSITIONAL args: PostHog.capture_exception(exception, distinct_id, additional_properties) — do NOT use keyword args"
     - "Define posthog_distinct_id on the User model for automatic user association in error reports — posthog-rails auto-detects by trying: posthog_distinct_id, distinct_id, id, pk, uuid (in order)"
     - "For ActiveJob user association, use the class-level DSL `posthog_distinct_id ->(user) { user.email }` or pass user_id: in a hash argument"
-    - Store API key in Rails credentials or environment variables, never hardcode
+    - Store the project API token in Rails credentials or environment variables, never hardcode
     - "For frontend tracking alongside posthog-rails, add the posthog-js snippet to the layout template — posthog-js handles pageviews, session replay, and client-side errors while posthog-ruby handles backend events, server errors, feature flags, and background jobs"
 
   hogql:
diff --git a/context/skills/mcp-analytics/description.md b/context/skills/mcp-analytics/description.md
index 0a502c19..9edf1f5e 100644
--- a/context/skills/mcp-analytics/description.md
+++ b/context/skills/mcp-analytics/description.md
@@ -73,7 +73,7 @@ Create the PostHog client **once at module scope** (never per request), reading
 ```ts
 import { PostHog } from "posthog-node"
 
-const posthog = new PostHog(process.env.POSTHOG_PROJECT_API_KEY, {
+const posthog = new PostHog(process.env.POSTHOG_PROJECT_TOKEN, {
   host: process.env.POSTHOG_HOST, // https://us.i.posthog.com or https://eu.i.posthog.com
 })
 ```
@@ -106,7 +106,7 @@ const handler = createMcpHandler((server) => {
 ```ts
 import { PostHogMCP } from "@posthog/mcp"
 
-const posthog = new PostHogMCP(process.env.POSTHOG_PROJECT_API_KEY, {
+const posthog = new PostHogMCP(process.env.POSTHOG_PROJECT_TOKEN, {
   host: process.env.POSTHOG_HOST,
 })
 
@@ -136,7 +136,7 @@ import { Module } from "@nestjs/common"
 import { McpModule } from "@rekog/mcp-nest"
 import { PostHog, instrumentMutator } from "@posthog/mcp"
 
-const posthog = new PostHog(process.env.POSTHOG_PROJECT_API_KEY, {
+const posthog = new PostHog(process.env.POSTHOG_PROJECT_TOKEN, {
   host: process.env.POSTHOG_HOST,
 })
 
@@ -161,7 +161,7 @@ import os
 from posthog import Posthog
 
 posthog = Posthog(
-    os.environ["POSTHOG_PROJECT_API_KEY"],
+    os.environ["POSTHOG_PROJECT_TOKEN"],
     host=os.environ["POSTHOG_HOST"],  # https://us.i.posthog.com or https://eu.i.posthog.com
 )
 ```
@@ -184,7 +184,7 @@ analytics = instrument(server, posthog)  # wrap right after constructing the ser
 import time
 from posthog.mcp import PostHogMCP
 
-posthog = PostHogMCP(os.environ["POSTHOG_PROJECT_API_KEY"], host=os.environ["POSTHOG_HOST"])
+posthog = PostHogMCP(os.environ["POSTHOG_PROJECT_TOKEN"], host=os.environ["POSTHOG_HOST"])
 
 # on the initialize handshake:
 posthog.capture_initialize(client_name=client_name, client_version=client_version, distinct_id=distinct_id)
@@ -207,10 +207,10 @@ Resolve `distinct_id` / `session_id` from whatever auth/session the dispatcher a
 
 ### STEP 5: Wire up credentials
 
-- Check existing env files (`.env`, `.env.local`, etc.) for a PostHog project API key. If a valid `phc_…` key and host are already set, reference those and skip the rest of this step.
-- If the key is missing, use the PostHog MCP server's `projects-get` tool to fetch the project's `api_token`. If multiple projects come back, ask the user which to use. If the MCP server isn't connected, ask the user for their project API key directly.
+- Check existing env files (`.env`, `.env.local`, etc.) for a PostHog project API token. If a valid `phc_…` token and host are already set, reference those and skip the rest of this step.
+- If the token is missing, use the PostHog MCP server's `projects-get` tool to fetch the project's `api_token`. If multiple projects come back, ask the user which to use. If the MCP server isn't connected, ask the user for their project API token directly.
 - Host: `https://us.i.posthog.com` for US Cloud, `https://eu.i.posthog.com` for EU Cloud.
-- Write `POSTHOG_PROJECT_API_KEY` and `POSTHOG_HOST` to the appropriate env file and reference them in code (`process.env.*` in JS, `os.environ[...]` in Python) — never hardcode the key.
+- Write `POSTHOG_PROJECT_TOKEN` and `POSTHOG_HOST` to the appropriate env file and reference them in code (`process.env.*` in JS, `os.environ[...]` in Python) — never hardcode the token.
 
 ### STEP 6: Ensure events get flushed
 
@@ -251,7 +251,7 @@ The PostHog client batches events; the user owns the client's lifecycle.
 
 - **One server, one wrapper.** `instrument()` is idempotent; don't call it twice on the same server.
 - **Module-scope client.** Construct the `PostHog` / `Posthog` / `PostHogMCP` client once, not per request.
-- **Env, never hardcode.** The project API key and host come from environment variables.
+- **Env, never hardcode.** The project API token and host come from environment variables.
 - **Additive only.** Don't change tool behavior or restructure the server — just wrap/capture.
 - **Don't break STDIO.** No `console.*` (JS) or `print()` (Python) on STDIO transports; use a `logger` instead.
 - **Pin the beta SDK** and tell the user it's pre-1.0. (Python: `posthog.mcp` ships inside `posthog`; pin `posthog>=7.21`.)
diff --git a/context/skills/omnibus/instrument-error-tracking/description.md b/context/skills/omnibus/instrument-error-tracking/description.md
index eb5e2e52..435deff0 100644
--- a/context/skills/omnibus/instrument-error-tracking/description.md
+++ b/context/skills/omnibus/instrument-error-tracking/description.md
@@ -38,7 +38,7 @@ STEP 6: Upload source maps (frontend/mobile only).
 
 STEP 7: Set up environment variables.
   - Check if the project already has PostHog environment variables configured (e.g. in `.env`, `.env.local`, or framework-specific env files). If valid values already exist, skip this step.
-  - If the PostHog API key is missing, use the PostHog MCP server's `projects-get` tool to retrieve the project's `api_token`. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project API key instead.
+  - If the PostHog project API token is missing, use the PostHog MCP server's `projects-get` tool to retrieve the project's `api_token`. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project API token instead.
   - For the PostHog host URL, use `https://us.i.posthog.com` for US Cloud or `https://eu.i.posthog.com` for EU Cloud.
   - Write these values to the appropriate env file using the framework's naming convention.
   - Reference these environment variables in code instead of hardcoding them.
diff --git a/context/skills/omnibus/instrument-feature-flags/description.md b/context/skills/omnibus/instrument-feature-flags/description.md
index 8b211031..33265dfc 100644
--- a/context/skills/omnibus/instrument-feature-flags/description.md
+++ b/context/skills/omnibus/instrument-feature-flags/description.md
@@ -35,7 +35,7 @@ STEP 5: Instrument the feature.
 
 STEP 6: Set up environment variables.
   - Check if the project already has PostHog environment variables configured (e.g. in `.env`, `.env.local`, or framework-specific env files). If valid values already exist, skip this step.
-  - If the PostHog API key is missing, use the PostHog MCP server's `projects-get` tool to retrieve the project's `api_token`. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project API key instead.
+  - If the PostHog project API token is missing, use the PostHog MCP server's `projects-get` tool to retrieve the project's `api_token`. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project API token instead.
   - For the PostHog host URL, use `https://us.i.posthog.com` for US Cloud or `https://eu.i.posthog.com` for EU Cloud.
   - Write these values to the appropriate env file using the framework's naming convention.
   - Reference these environment variables in code instead of hardcoding them.
diff --git a/context/skills/omnibus/instrument-integration/description.md b/context/skills/omnibus/instrument-integration/description.md
index fac9ae24..28c9ef12 100644
--- a/context/skills/omnibus/instrument-integration/description.md
+++ b/context/skills/omnibus/instrument-integration/description.md
@@ -32,7 +32,7 @@ STEP 5: Identify users.
 
 STEP 6: Set up environment variables.
   - Check if the project already has PostHog environment variables configured (e.g. in `.env`, `.env.local`, or framework-specific env files). If valid values already exist, skip this step.
-  - If the PostHog API key is missing, use the PostHog MCP server's `projects-get` tool to retrieve the project's `api_token`. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project API key instead.
+  - If the PostHog project API token is missing, use the PostHog MCP server's `projects-get` tool to retrieve the project's `api_token`. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project API token instead.
   - For the PostHog host URL, use `https://us.i.posthog.com` for US Cloud or `https://eu.i.posthog.com` for EU Cloud.
   - Write these values to the appropriate env file (e.g. `.env.local` for Next.js, `.env` for others) using the framework's naming convention.
   - Reference these environment variables in code instead of hardcoding them.
diff --git a/context/skills/omnibus/instrument-llm-analytics/description.md b/context/skills/omnibus/instrument-llm-analytics/description.md
index 6728e89a..d1fda861 100644
--- a/context/skills/omnibus/instrument-llm-analytics/description.md
+++ b/context/skills/omnibus/instrument-llm-analytics/description.md
@@ -36,7 +36,7 @@ STEP 5: Link to users.
 
 STEP 6: Set up environment variables.
   - Check if the project already has PostHog environment variables configured (e.g. in `.env`, `.env.local`, or framework-specific env files). If valid values already exist, skip this step.
-  - If the PostHog API key is missing, use the PostHog MCP server's `projects-get` tool to retrieve the project's `api_token`. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project API key instead.
+  - If the PostHog project API token is missing, use the PostHog MCP server's `projects-get` tool to retrieve the project's `api_token`. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project API token instead.
   - For the PostHog host URL, use `https://us.i.posthog.com` for US Cloud or `https://eu.i.posthog.com` for EU Cloud.
   - Write these values to the appropriate env file using the framework's naming convention.
   - Reference these environment variables in code instead of hardcoding them.
diff --git a/context/skills/omnibus/instrument-logs/description.md b/context/skills/omnibus/instrument-logs/description.md
index 37f47b3a..f514c870 100644
--- a/context/skills/omnibus/instrument-logs/description.md
+++ b/context/skills/omnibus/instrument-logs/description.md
@@ -39,7 +39,7 @@ STEP 6: Add structured properties.
 
 STEP 7: Set up environment variables.
   - Check if the project already has PostHog environment variables configured (e.g. in `.env`, `.env.local`, or framework-specific env files). If valid values already exist, skip this step.
-  - If the PostHog API key is missing, use the PostHog MCP server's `projects-get` tool to retrieve the project's `api_token`. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project API key instead.
+  - If the PostHog project API token is missing, use the PostHog MCP server's `projects-get` tool to retrieve the project's `api_token`. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project API token instead.
   - For the PostHog host URL, use `https://us.i.posthog.com` for US Cloud or `https://eu.i.posthog.com` for EU Cloud.
   - For the OpenTelemetry endpoint, use `https://us.i.posthog.com/v1` (US) or `https://eu.i.posthog.com/v1` (EU).
   - Write these values to the appropriate env file using the framework's naming convention.
diff --git a/context/skills/omnibus/instrument-product-analytics/description.md b/context/skills/omnibus/instrument-product-analytics/description.md
index 07d06a86..ab0c2841 100644
--- a/context/skills/omnibus/instrument-product-analytics/description.md
+++ b/context/skills/omnibus/instrument-product-analytics/description.md
@@ -47,7 +47,7 @@ STEP 8: Add error tracking.
 
 STEP 9: Set up environment variables.
   - Check if the project already has PostHog environment variables configured (e.g. in `.env`, `.env.local`, or framework-specific env files). If valid values already exist, skip this step.
-  - If the PostHog API key is missing, use the PostHog MCP server's `projects-get` tool to retrieve the project's `api_token`. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project API key instead.
+  - If the PostHog project API token is missing, use the PostHog MCP server's `projects-get` tool to retrieve the project's `api_token`. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project API token instead.
   - For the PostHog host URL, use `https://us.i.posthog.com` for US Cloud or `https://eu.i.posthog.com` for EU Cloud.
   - Write these values to the appropriate env file using the framework's naming convention.
   - Reference these environment variables in code instead of hardcoding them.
diff --git a/example-apps/expo/README.md b/example-apps/expo/README.md
index c016be65..fbb47274 100644
--- a/example-apps/expo/README.md
+++ b/example-apps/expo/README.md
@@ -105,7 +105,7 @@ PostHog is configured in `src/config/posthog.ts` using environment variables fro
 ```typescript
 import Constants from 'expo-constants'
 
-const apiKey = Constants.expoConfig?.extra?.posthogProjectToken
+const projectToken = Constants.expoConfig?.extra?.posthogProjectToken
 ```
 
 ### Event Tracking
diff --git a/example-apps/expo/src/config/posthog.ts b/example-apps/expo/src/config/posthog.ts
index 23079d02..fc071ac4 100644
--- a/example-apps/expo/src/config/posthog.ts
+++ b/example-apps/expo/src/config/posthog.ts
@@ -3,13 +3,13 @@ import Constants from 'expo-constants'
 
 // Configuration loaded from app.config.js extras via expo-constants
 // Environment variables are read at build time in app.config.js
-const apiKey = Constants.expoConfig?.extra?.posthogProjectToken as string | undefined
+const projectToken = Constants.expoConfig?.extra?.posthogProjectToken as string | undefined
 const host = (Constants.expoConfig?.extra?.posthogHost as string) || 'https://us.i.posthog.com'
-const isPostHogConfigured = apiKey && apiKey !== 'phc_your_project_token_here'
+const isPostHogConfigured = projectToken && projectToken !== 'phc_your_project_token_here'
 
 if (__DEV__) {
   console.log('PostHog config:', {
-    apiKey: apiKey ? `SET` : 'NOT SET',
+    projectToken: projectToken ? `SET` : 'NOT SET',
     host,
     isConfigured: isPostHogConfigured,
   })
@@ -34,7 +34,7 @@ if (!isPostHogConfigured) {
  *
  * @see https://posthog.com/docs/libraries/react-native
  */
-export const posthog = new PostHog(apiKey || 'placeholder_key', {
+export const posthog = new PostHog(projectToken || 'placeholder_key', {
   // PostHog API host
   host,
 
diff --git a/example-apps/javascript-web/src/posthog.js b/example-apps/javascript-web/src/posthog.js
index edc59b2f..e6bca4c2 100644
--- a/example-apps/javascript-web/src/posthog.js
+++ b/example-apps/javascript-web/src/posthog.js
@@ -6,16 +6,16 @@
  */
 import posthog from 'posthog-js';
 
-const apiKey = import.meta.env.VITE_POSTHOG_PROJECT_TOKEN;
+const projectToken = import.meta.env.VITE_POSTHOG_PROJECT_TOKEN;
 const apiHost = import.meta.env.VITE_POSTHOG_HOST || 'https://us.i.posthog.com';
 
-if (!apiKey) {
+if (!projectToken) {
   console.warn(
     'PostHog not configured (VITE_POSTHOG_PROJECT_TOKEN not set).',
     'App will work but analytics will not be tracked.',
   );
 } else {
-  posthog.init(apiKey, {
+  posthog.init(projectToken, {
     api_host: apiHost,
     // Autocapture is ON by default — tracks clicks, form submissions, pageviews
     // capture_pageview: true (default) — captures $pageview on init
diff --git a/example-apps/php/.env.example b/example-apps/php/.env.example
index 6bbc2938..0f290efe 100644
--- a/example-apps/php/.env.example
+++ b/example-apps/php/.env.example
@@ -1,3 +1,3 @@
 # PostHog configuration
-POSTHOG_API_KEY=phc_your_api_key_here
+POSTHOG_PROJECT_TOKEN=phc_your_project_token_here
 POSTHOG_HOST=https://us.i.posthog.com
diff --git a/example-apps/php/README.md b/example-apps/php/README.md
index 32e00f70..c7710933 100644
--- a/example-apps/php/README.md
+++ b/example-apps/php/README.md
@@ -31,8 +31,8 @@ composer install
 # Copy environment template
 cp .env.example .env
 
-# Edit .env and add your PostHog API key
-# POSTHOG_API_KEY=phc_your_api_key_here
+# Edit .env and add your PostHog project token
+# POSTHOG_PROJECT_TOKEN=phc_your_project_token_here
 # POSTHOG_HOST=https://us.i.posthog.com
 ```
 
@@ -84,7 +84,7 @@ basics/php/
 ### 1. Initialize Once
 
 ```php
-PostHog::init($apiKey, [
+PostHog::init($projectToken, [
     'host' => $host,
     'error_tracking' => [
         'enabled' => true,
diff --git a/example-apps/php/todo.php b/example-apps/php/todo.php
index a6e66978..949ad47b 100644
--- a/example-apps/php/todo.php
+++ b/example-apps/php/todo.php
@@ -46,14 +46,14 @@ function initializePostHog(): bool
 {
     loadEnvFile(__DIR__ . '/.env');
 
-    $apiKey = getenv('POSTHOG_API_KEY');
-    if (!$apiKey || str_starts_with($apiKey, 'phc_your_')) {
-        echo "WARNING: PostHog not configured (POSTHOG_API_KEY not set)\n";
+    $projectToken = getenv('POSTHOG_PROJECT_TOKEN');
+    if (!$projectToken || str_starts_with($projectToken, 'phc_your_')) {
+        echo "WARNING: PostHog not configured (POSTHOG_PROJECT_TOKEN not set)\n";
         echo "         App will work but analytics won't be tracked\n";
         return false;
     }
 
-    PostHog::init($apiKey, [
+    PostHog::init($projectToken, [
         'host' => getenv('POSTHOG_HOST') ?: 'https://us.i.posthog.com',
         'error_tracking' => [
             'enabled' => true,
diff --git a/example-apps/react-native/README.md b/example-apps/react-native/README.md
index f8f664a5..f10d9926 100644
--- a/example-apps/react-native/README.md
+++ b/example-apps/react-native/README.md
@@ -200,10 +200,10 @@ The PostHog client is configured with V4 SDK options. If no project token is pro
 import PostHog from 'posthog-react-native'
 import Config from 'react-native-config'
 
-const apiKey = Config.POSTHOG_PROJECT_TOKEN
-const isPostHogConfigured = apiKey && apiKey !== 'phc_your_project_token_here'
+const projectToken = Config.POSTHOG_PROJECT_TOKEN
+const isPostHogConfigured = projectToken && projectToken !== 'phc_your_project_token_here'
 
-export const posthog = new PostHog(apiKey || 'placeholder_key', {
+export const posthog = new PostHog(projectToken || 'placeholder_key', {
   host: Config.POSTHOG_HOST || 'https://us.i.posthog.com',
   disabled: !isPostHogConfigured,  // Disable if no project token
   captureAppLifecycleEvents: true,
diff --git a/example-apps/react-native/src/config/posthog.ts b/example-apps/react-native/src/config/posthog.ts
index ef605723..1c5aa18d 100644
--- a/example-apps/react-native/src/config/posthog.ts
+++ b/example-apps/react-native/src/config/posthog.ts
@@ -3,9 +3,9 @@ import Config from 'react-native-config'
 
 // Environment variables are embedded at build time via react-native-config
 // Ensure .env file exists with POSTHOG_PROJECT_TOKEN and POSTHOG_HOST
-const apiKey = Config.POSTHOG_PROJECT_TOKEN
+const projectToken = Config.POSTHOG_PROJECT_TOKEN
 const host = Config.POSTHOG_HOST || 'https://us.i.posthog.com'
-const isPostHogConfigured = apiKey && apiKey !== 'phc_your_project_token_here'
+const isPostHogConfigured = projectToken && projectToken !== 'phc_your_project_token_here'
 
 if (!isPostHogConfigured) {
   console.warn(
@@ -23,7 +23,7 @@ if (!isPostHogConfigured) {
  *
  * @see https://posthog.com/docs/libraries/react-native
  */
-export const posthog = new PostHog(apiKey || 'placeholder_key', {
+export const posthog = new PostHog(projectToken || 'placeholder_key', {
   // PostHog API host (usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com')
   host,
 

From 26ea6363b73aebfb04f5f4f8051fc1feede9528b Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <29069505+gewenyu99@users.noreply.github.com>
Date: Tue, 30 Jun 2026 14:29:25 -0400
Subject: [PATCH 2/3] =?UTF-8?q?Drop=20"API"=20=E2=80=94=20use=20"project?=
 =?UTF-8?q?=20token"=20not=20"project=20API=20token"?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Per review feedback: PostHog's term is "project token", not "project API token". Drops the "API" word across the omnibus instrument-* skills, mcp-analytics, and the Rails commandment. The MCP `api_token` field name in code is unchanged, and "personal API key" references are untouched.

Generated-By: PostHog Code
Task-Id: 870391f2-b0c5-4a20-8534-7dd9607b7a48
---
 context/commandments.yaml                                   | 2 +-
 context/skills/mcp-analytics/description.md                 | 6 +++---
 .../skills/omnibus/instrument-error-tracking/description.md | 2 +-
 .../skills/omnibus/instrument-feature-flags/description.md  | 2 +-
 .../skills/omnibus/instrument-integration/description.md    | 2 +-
 .../skills/omnibus/instrument-llm-analytics/description.md  | 2 +-
 context/skills/omnibus/instrument-logs/description.md       | 2 +-
 .../omnibus/instrument-product-analytics/description.md     | 2 +-
 8 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/context/commandments.yaml b/context/commandments.yaml
index 18ffbd2c..f58957bf 100644
--- a/context/commandments.yaml
+++ b/context/commandments.yaml
@@ -170,7 +170,7 @@ commandments:
     - "capture_exception takes POSITIONAL args: PostHog.capture_exception(exception, distinct_id, additional_properties) — do NOT use keyword args"
     - "Define posthog_distinct_id on the User model for automatic user association in error reports — posthog-rails auto-detects by trying: posthog_distinct_id, distinct_id, id, pk, uuid (in order)"
     - "For ActiveJob user association, use the class-level DSL `posthog_distinct_id ->(user) { user.email }` or pass user_id: in a hash argument"
-    - Store the project API token in Rails credentials or environment variables, never hardcode
+    - Store the project token in Rails credentials or environment variables, never hardcode
     - "For frontend tracking alongside posthog-rails, add the posthog-js snippet to the layout template — posthog-js handles pageviews, session replay, and client-side errors while posthog-ruby handles backend events, server errors, feature flags, and background jobs"
 
   hogql:
diff --git a/context/skills/mcp-analytics/description.md b/context/skills/mcp-analytics/description.md
index 9edf1f5e..61d239fe 100644
--- a/context/skills/mcp-analytics/description.md
+++ b/context/skills/mcp-analytics/description.md
@@ -207,8 +207,8 @@ Resolve `distinct_id` / `session_id` from whatever auth/session the dispatcher a
 
 ### STEP 5: Wire up credentials
 
-- Check existing env files (`.env`, `.env.local`, etc.) for a PostHog project API token. If a valid `phc_…` token and host are already set, reference those and skip the rest of this step.
-- If the token is missing, use the PostHog MCP server's `projects-get` tool to fetch the project's `api_token`. If multiple projects come back, ask the user which to use. If the MCP server isn't connected, ask the user for their project API token directly.
+- Check existing env files (`.env`, `.env.local`, etc.) for a PostHog project token. If a valid `phc_…` token and host are already set, reference those and skip the rest of this step.
+- If the token is missing, use the PostHog MCP server's `projects-get` tool to fetch the project's `api_token`. If multiple projects come back, ask the user which to use. If the MCP server isn't connected, ask the user for their project token directly.
 - Host: `https://us.i.posthog.com` for US Cloud, `https://eu.i.posthog.com` for EU Cloud.
 - Write `POSTHOG_PROJECT_TOKEN` and `POSTHOG_HOST` to the appropriate env file and reference them in code (`process.env.*` in JS, `os.environ[...]` in Python) — never hardcode the token.
 
@@ -251,7 +251,7 @@ The PostHog client batches events; the user owns the client's lifecycle.
 
 - **One server, one wrapper.** `instrument()` is idempotent; don't call it twice on the same server.
 - **Module-scope client.** Construct the `PostHog` / `Posthog` / `PostHogMCP` client once, not per request.
-- **Env, never hardcode.** The project API token and host come from environment variables.
+- **Env, never hardcode.** The project token and host come from environment variables.
 - **Additive only.** Don't change tool behavior or restructure the server — just wrap/capture.
 - **Don't break STDIO.** No `console.*` (JS) or `print()` (Python) on STDIO transports; use a `logger` instead.
 - **Pin the beta SDK** and tell the user it's pre-1.0. (Python: `posthog.mcp` ships inside `posthog`; pin `posthog>=7.21`.)
diff --git a/context/skills/omnibus/instrument-error-tracking/description.md b/context/skills/omnibus/instrument-error-tracking/description.md
index 435deff0..1b5017e5 100644
--- a/context/skills/omnibus/instrument-error-tracking/description.md
+++ b/context/skills/omnibus/instrument-error-tracking/description.md
@@ -38,7 +38,7 @@ STEP 6: Upload source maps (frontend/mobile only).
 
 STEP 7: Set up environment variables.
   - Check if the project already has PostHog environment variables configured (e.g. in `.env`, `.env.local`, or framework-specific env files). If valid values already exist, skip this step.
-  - If the PostHog project API token is missing, use the PostHog MCP server's `projects-get` tool to retrieve the project's `api_token`. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project API token instead.
+  - If the PostHog project token is missing, use the PostHog MCP server's `projects-get` tool to retrieve the project's `api_token`. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project token instead.
   - For the PostHog host URL, use `https://us.i.posthog.com` for US Cloud or `https://eu.i.posthog.com` for EU Cloud.
   - Write these values to the appropriate env file using the framework's naming convention.
   - Reference these environment variables in code instead of hardcoding them.
diff --git a/context/skills/omnibus/instrument-feature-flags/description.md b/context/skills/omnibus/instrument-feature-flags/description.md
index 33265dfc..2aad904a 100644
--- a/context/skills/omnibus/instrument-feature-flags/description.md
+++ b/context/skills/omnibus/instrument-feature-flags/description.md
@@ -35,7 +35,7 @@ STEP 5: Instrument the feature.
 
 STEP 6: Set up environment variables.
   - Check if the project already has PostHog environment variables configured (e.g. in `.env`, `.env.local`, or framework-specific env files). If valid values already exist, skip this step.
-  - If the PostHog project API token is missing, use the PostHog MCP server's `projects-get` tool to retrieve the project's `api_token`. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project API token instead.
+  - If the PostHog project token is missing, use the PostHog MCP server's `projects-get` tool to retrieve the project's `api_token`. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project token instead.
   - For the PostHog host URL, use `https://us.i.posthog.com` for US Cloud or `https://eu.i.posthog.com` for EU Cloud.
   - Write these values to the appropriate env file using the framework's naming convention.
   - Reference these environment variables in code instead of hardcoding them.
diff --git a/context/skills/omnibus/instrument-integration/description.md b/context/skills/omnibus/instrument-integration/description.md
index 28c9ef12..53f5c8c1 100644
--- a/context/skills/omnibus/instrument-integration/description.md
+++ b/context/skills/omnibus/instrument-integration/description.md
@@ -32,7 +32,7 @@ STEP 5: Identify users.
 
 STEP 6: Set up environment variables.
   - Check if the project already has PostHog environment variables configured (e.g. in `.env`, `.env.local`, or framework-specific env files). If valid values already exist, skip this step.
-  - If the PostHog project API token is missing, use the PostHog MCP server's `projects-get` tool to retrieve the project's `api_token`. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project API token instead.
+  - If the PostHog project token is missing, use the PostHog MCP server's `projects-get` tool to retrieve the project's `api_token`. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project token instead.
   - For the PostHog host URL, use `https://us.i.posthog.com` for US Cloud or `https://eu.i.posthog.com` for EU Cloud.
   - Write these values to the appropriate env file (e.g. `.env.local` for Next.js, `.env` for others) using the framework's naming convention.
   - Reference these environment variables in code instead of hardcoding them.
diff --git a/context/skills/omnibus/instrument-llm-analytics/description.md b/context/skills/omnibus/instrument-llm-analytics/description.md
index d1fda861..0f4beddf 100644
--- a/context/skills/omnibus/instrument-llm-analytics/description.md
+++ b/context/skills/omnibus/instrument-llm-analytics/description.md
@@ -36,7 +36,7 @@ STEP 5: Link to users.
 
 STEP 6: Set up environment variables.
   - Check if the project already has PostHog environment variables configured (e.g. in `.env`, `.env.local`, or framework-specific env files). If valid values already exist, skip this step.
-  - If the PostHog project API token is missing, use the PostHog MCP server's `projects-get` tool to retrieve the project's `api_token`. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project API token instead.
+  - If the PostHog project token is missing, use the PostHog MCP server's `projects-get` tool to retrieve the project's `api_token`. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project token instead.
   - For the PostHog host URL, use `https://us.i.posthog.com` for US Cloud or `https://eu.i.posthog.com` for EU Cloud.
   - Write these values to the appropriate env file using the framework's naming convention.
   - Reference these environment variables in code instead of hardcoding them.
diff --git a/context/skills/omnibus/instrument-logs/description.md b/context/skills/omnibus/instrument-logs/description.md
index f514c870..5614985e 100644
--- a/context/skills/omnibus/instrument-logs/description.md
+++ b/context/skills/omnibus/instrument-logs/description.md
@@ -39,7 +39,7 @@ STEP 6: Add structured properties.
 
 STEP 7: Set up environment variables.
   - Check if the project already has PostHog environment variables configured (e.g. in `.env`, `.env.local`, or framework-specific env files). If valid values already exist, skip this step.
-  - If the PostHog project API token is missing, use the PostHog MCP server's `projects-get` tool to retrieve the project's `api_token`. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project API token instead.
+  - If the PostHog project token is missing, use the PostHog MCP server's `projects-get` tool to retrieve the project's `api_token`. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project token instead.
   - For the PostHog host URL, use `https://us.i.posthog.com` for US Cloud or `https://eu.i.posthog.com` for EU Cloud.
   - For the OpenTelemetry endpoint, use `https://us.i.posthog.com/v1` (US) or `https://eu.i.posthog.com/v1` (EU).
   - Write these values to the appropriate env file using the framework's naming convention.
diff --git a/context/skills/omnibus/instrument-product-analytics/description.md b/context/skills/omnibus/instrument-product-analytics/description.md
index ab0c2841..97ed9ef8 100644
--- a/context/skills/omnibus/instrument-product-analytics/description.md
+++ b/context/skills/omnibus/instrument-product-analytics/description.md
@@ -47,7 +47,7 @@ STEP 8: Add error tracking.
 
 STEP 9: Set up environment variables.
   - Check if the project already has PostHog environment variables configured (e.g. in `.env`, `.env.local`, or framework-specific env files). If valid values already exist, skip this step.
-  - If the PostHog project API token is missing, use the PostHog MCP server's `projects-get` tool to retrieve the project's `api_token`. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project API token instead.
+  - If the PostHog project token is missing, use the PostHog MCP server's `projects-get` tool to retrieve the project's `api_token`. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project token instead.
   - For the PostHog host URL, use `https://us.i.posthog.com` for US Cloud or `https://eu.i.posthog.com` for EU Cloud.
   - Write these values to the appropriate env file using the framework's naming convention.
   - Reference these environment variables in code instead of hardcoding them.

From c8e475a63b92e39b4c0ccbc062e2456bbde93d36 Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <gewenyu99@gmail.com>
Date: Wed, 8 Jul 2026 15:02:32 -0400
Subject: [PATCH 3/3] docs(product-tours): call the phc_ key a project token,
 not an API key

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 context/skills/creating-product-tours/description.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/context/skills/creating-product-tours/description.md b/context/skills/creating-product-tours/description.md
index 73452ed0..bc1d826b 100644
--- a/context/skills/creating-product-tours/description.md
+++ b/context/skills/creating-product-tours/description.md
@@ -2,7 +2,7 @@
 
 Product tours use PostHog feature flags for targeting (who sees the tour and when) and PostHog events for tracking (completion, drop-off, step funnel). UI components should be custom-built but reusable across multiple tours.
 
-**Local-dev behavior**: the tour renders locally even when PostHog isn't initialized (no API key, provider not mounted, ad blocker active). The feature flag infrastructure is still scaffolded for production rollout — it just isn't a hard gate in dev. This lets engineers iterate on the tour without needing a PostHog project wired up. See "Local development" below for how the fail-open works and how to opt out.
+**Local-dev behavior**: the tour renders locally even when PostHog isn't initialized (no project token, provider not mounted, ad blocker active). The feature flag infrastructure is still scaffolded for production rollout — it just isn't a hard gate in dev. This lets engineers iterate on the tour without needing a PostHog project wired up. See "Local development" below for how the fail-open works and how to opt out.
 
 ## Step 1: gather requirements
 
@@ -73,7 +73,7 @@ interface UseTourOptions {
   storageKey?: string; // localStorage key to remember completion; defaults to `tour-${flagKey}`
   // When true, the flag check is enforced even if PostHog isn't initialized
   // (the tour won't render locally without PostHog wired up). Default false:
-  // fail-open in dev so engineers can iterate without an API key.
+  // fail-open in dev so engineers can iterate without a project token.
   requireFlag?: boolean;
 }