@codyswann/lisa 2.176.11 → 2.177.0

package/plugins/lisa-harper-fabric-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "Harper/Fabric-specific rules for TypeScript component apps",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-harper-fabric-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "Harper/Fabric-specific rules for TypeScript component apps",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "NestJS-specific skills and migration write-protection hooks.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-openclaw/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-openclaw/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, across Claude and Codex.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-openclaw-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-openclaw-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-openclaw-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-phaser/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-phaser/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-phaser-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-phaser-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-phaser-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "Ruby on Rails-specific skills and hooks for RuboCop and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "TypeScript-specific hooks for formatting, linting, and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "Distributable LLM Wiki kernel — ingest, query, lint, and maintain a git-native markdown knowledge base across Claude and Codex.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/src/base/hooks/setup-jira-cli.sh

@@ -5,9 +5,9 @@
 #
 # Required env vars (must be created in your Claude Code Web environment):
 #   JIRA_INSTALLATION - cloud or local
-#   JIRA_SERVER       - Atlassian instance URL
+#   JIRA_SERVER       - Atlassian instance URL (falls back to .lisa.config*.json atlassian.site)
 #   JIRA_LOGIN        - login email
-#   JIRA_PROJECT      - default project key
+#   JIRA_PROJECT      - default project key (falls back to .lisa.config*.json jira.project)
 #   JIRA_API_TOKEN    - already expected by jira-cli natively
 #
 # Optional env vars:
@@ -31,6 +31,40 @@ fi
 CONFIG_DIR="${HOME}/.config/.jira"
 CONFIG_FILE="${CONFIG_DIR}/.config.yml"
 
+read_lisa_config() {
+  local query="$1"
+  local value=""
+
+  if ! command -v jq &>/dev/null; then
+    return 0
+  fi
+
+  if [[ -f ".lisa.config.local.json" ]]; then
+    value=$(jq -r "${query} // empty" .lisa.config.local.json 2>/dev/null || true)
+  fi
+
+  if [[ -z "${value}" && -f ".lisa.config.json" ]]; then
+    value=$(jq -r "${query} // empty" .lisa.config.json 2>/dev/null || true)
+  fi
+
+  printf '%s' "${value}"
+}
+
+if [[ -z "${JIRA_SERVER:-}" ]]; then
+  ATLASSIAN_SITE="$(read_lisa_config '.atlassian.site')"
+  if [[ -n "${ATLASSIAN_SITE}" ]]; then
+    if [[ "${ATLASSIAN_SITE}" == http://* || "${ATLASSIAN_SITE}" == https://* ]]; then
+      JIRA_SERVER="${ATLASSIAN_SITE}"
+    else
+      JIRA_SERVER="https://${ATLASSIAN_SITE}"
+    fi
+  fi
+fi
+
+if [[ -z "${JIRA_PROJECT:-}" ]]; then
+  JIRA_PROJECT="$(read_lisa_config '.jira.project')"
+fi
+
 # Skip config write if required vars are missing
 if [[ -z "${JIRA_SERVER:-}" || -z "${JIRA_LOGIN:-}" ]]; then
   exit 0

package/plugins/src/base/rules/eager/integration-access-layer.md

@@ -0,0 +1,10 @@
+# Integration Access Layer
+
+Skills and rules that use external integrations route through the matching
+`*-access` skill. Do not call vendor MCP tools or REST APIs directly from a
+consumer skill.
+
+Resolution order is MCP when available and authenticated, then documented
+token/REST substrate when the env var is set, then a loud error naming the env
+var. Full matrix and migration rules:
+[reference/integration-access-layer.md](../reference/integration-access-layer.md).

package/plugins/src/base/rules/reference/integration-access-layer.md

@@ -0,0 +1,56 @@
+# Integration Access Layer
+
+Every Lisa skill or rule that consumes an external integration MUST route through
+the integration's `*-access` skill instead of calling that vendor's MCP tools or
+REST API directly.
+
+The access skill owns substrate resolution:
+
+1. MCP, when the tool is available and already authenticated to the configured
+   workspace/account.
+2. Token/REST substrate, only when the documented env var is present.
+3. Loud failure naming the exact env var to set.
+
+Do not blind-retry a failed or absent MCP. Fall back only after checking the
+documented env var for that vendor, and never silently no-op when neither tier is
+available.
+
+## Access Skills
+
+| Vendor | Access skill | Headless env var | REST/token substrate |
+|---|---|---|---|
+| Atlassian | `lisa:atlassian-access` | `ATLASSIAN_API_TOKEN` | Atlassian Cloud REST |
+| Notion | `lisa:notion-access` | `NOTION_API_TOKEN` | Notion REST |
+| Linear | `lisa:linear-access` | `LINEAR_API_KEY` | Linear GraphQL |
+| Jam | `lisa:jam-access` | `JAM_PAT` | Jam MCP HTTP endpoint with bearer PAT |
+| SonarCloud | `lisa:sonarcloud-access` | `SONAR_TOKEN` | SonarCloud Web API |
+| Sentry | `lisa:sentry-access` | `SENTRY_AUTH_TOKEN` | Sentry REST API |
+| PostHog | `lisa:posthog-access` | `POSTHOG_PERSONAL_API_KEY` | PostHog REST API |
+
+## Current Coupling Matrix
+
+Source audit date: 2026-06-23. Scope: `plugins/src/**/skills/**` and
+`plugins/src/**/rules/**`.
+
+| Vendor | Direct source MCP references | Current route | Retrofit status |
+|---|---:|---|---|
+| Atlassian | setup-only references plus legacy stack-generated sources | `atlassian-access` for base runtime paths | Done for base hot paths; stack overlays still need sync from base patterns when touched. |
+| Notion | setup-only references | `notion-access` | Done. |
+| Linear | Multiple base queue/read/write/verify skills | Raw Linear MCP | Access layer added; consumers still need migration to `linear-access`. |
+| Jam | None in `plugins/src` at audit time | No access layer | Access layer added for host rules that include Jam triage. |
+| SonarCloud | None in `plugins/src` at audit time | No access layer | Access layer added for host rules that include SonarCloud gate triage. |
+| Sentry | No Sentry MCP references in `plugins/src`; CLI/REST mentions only | CLI/REST scattered in observability docs | Access layer added for future MCP-backed consumers. |
+| PostHog | No PostHog MCP references in `plugins/src`; observability docs mention PostHog detection | No access layer | Access layer added for future MCP-backed consumers. |
+
+## Migration Rule For Consumers
+
+When editing any skill listed in the matrix:
+
+- Replace direct `mcp__<vendor>__*` calls in `allowed-tools` with `Skill` and
+  delegate to the matching access skill.
+- Keep operation names coarse and vendor-native. Add new operation rows to the
+  access skill instead of embedding REST details in the consumer.
+- Preserve existing MCP behavior as the first tier where Claude/Codex can expose
+  the MCP, but make headless token fallback explicit and gated by the env var.
+- If a vendor has no documented token substrate, keep the MCP-only behavior and
+  fail with a clear "no documented headless substrate" message.

package/plugins/src/base/skills/jam-access/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: jam-access
+description: "Vendor-neutral access layer for Jam. Jam triage rules and skills MUST delegate through this skill rather than calling Jam MCP tools directly. Resolves Jam MCP first when available, then falls back to JAM_PAT bearer auth for headless routines."
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# Jam Access: $ARGUMENTS
+
+Single chokepoint for Jam operations. Caller skills and rules MUST NOT call
+`mcp__Jam__*` tools directly.
+
+## Invocation Contract
+
+```text
+operation: get-trace url:<jam-url-or-id>
+operation: get-recording url:<jam-url-or-id>
+operation: get-bug-report url:<jam-url-or-id>
+```
+
+Return parsed JSON or a concise structured summary in a `<result>` block.
+
+## Substrate Selection
+
+Probe in order:
+
+1. Jam MCP, if the tool is available and authenticated.
+2. `JAM_PAT` bearer token against Jam's MCP/trace HTTP substrate.
+
+Jam documents personal access tokens for MCP clients so a browser OAuth flow is
+not required. The headless tier uses:
+
+```bash
+curl -sS "https://mcp.jam.dev/mcp" \
+  -H "Authorization: Bearer $JAM_PAT" \
+  -H "Content-Type: application/json" \
+  --data-binary "$PAYLOAD"
+```
+
+If neither tier works, fail with:
+
+```text
+Error: no Jam access substrate available. Authenticate the Jam MCP or set JAM_PAT.
+```
+
+## Invariants
+
+- Fallback is gated on `JAM_PAT`; do not retry Jam MCP failures blindly.
+- Never commit a Jam PAT into `.mcp.json`. Use env interpolation in host MCP
+  config, for example `Authorization: Bearer ${JAM_PAT}`.
+- If a requested operation is not yet mapped to the Jam HTTP substrate, surface
+  that exact missing adapter instead of pretending the trace is unavailable.

package/plugins/src/base/skills/linear-access/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: linear-access
+description: "Vendor-neutral access layer for Linear. Linear skills MUST delegate through this skill rather than calling Linear MCP tools or Linear GraphQL directly. Resolves Linear MCP first when authenticated, then falls back to LINEAR_API_KEY + Linear GraphQL in headless environments."
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# Linear Access: $ARGUMENTS
+
+Single chokepoint for Linear operations. Caller skills (`linear-*`) MUST go
+through this skill. They MUST NOT call `mcp__linear-server__*` tools directly or
+curl `https://api.linear.app/graphql` themselves.
+
+## Invocation Contract
+
+```text
+operation: list-teams [query:<KEY>]
+operation: get-team id:<ID>
+operation: list-projects [team:<KEY>] [label:<NAME>] [state:<arr>]
+operation: get-project id:<ID>
+operation: save-project payload:{...}
+operation: list-issues [team:<ID>] [project:<ID>] [label:<NAME>] [state_type:<arr>]
+operation: get-issue id:<ID>
+operation: save-issue payload:{...}
+operation: list-comments issue_id:<ID>
+operation: save-comment issue_id:<ID> body:"..."
+operation: list-issue-labels [team:<ID>]
+operation: create-issue-label payload:{...}
+operation: list-project-labels
+operation: create-project-label payload:{...}
+operation: list-documents project_id:<ID>
+operation: get-document id:<ID>
+```
+
+Return parsed JSON in a `<result>` block. On failure, prefix the message with
+`Error:` and include the failing operation name.
+
+## Substrate Selection
+
+Read config:
+
+```bash
+WORKSPACE=$(jq -r '.linear.workspace // empty' .lisa.config.json 2>/dev/null)
+TEAM_KEY=$(jq -r '.linear.teamKey // empty' .lisa.config.json 2>/dev/null)
+```
+
+Probe in order:
+
+1. Linear MCP, if `mcp__linear-server__list_teams` is available and can list the
+   configured workspace/team.
+2. `LINEAR_API_KEY` with Linear GraphQL (`https://api.linear.app/graphql`).
+
+The Linear GraphQL docs support personal API keys for scripts and authenticate
+with an `Authorization: <API_KEY>` header. Treat `LINEAR_API_KEY` as the
+headless substrate. If neither tier works, fail with:
+
+```text
+Error: no Linear access substrate available. Authenticate the Linear MCP or set LINEAR_API_KEY.
+```
+
+## GraphQL Adapter
+
+All GraphQL calls use:
+
+```bash
+linear_graphql() {
+  local query="$1"
+  local variables="${2:-{}}"
+  [ -n "$LINEAR_API_KEY" ] || {
+    echo "Error: LINEAR_API_KEY is not set." >&2
+    return 1
+  }
+  jq -n --arg query "$query" --argjson variables "$variables" \
+    '{query:$query, variables:$variables}' |
+    curl -sS -X POST "https://api.linear.app/graphql" \
+      -H "Content-Type: application/json" \
+      -H "Authorization: '"$LINEAR_API_KEY"'" \
+      --data-binary @-
+}
+```
+
+Map operation names to Linear GraphQL queries/mutations in this access skill.
+Consumers pass business-shaped arguments only; they do not embed GraphQL.
+
+## Invariants
+
+- MCP is preferred when it is present and already authenticated.
+- GraphQL fallback runs only when `LINEAR_API_KEY` is present.
+- Missing MCP plus missing token is a hard failure naming `LINEAR_API_KEY`.
+- Mutations send only the fields being changed, matching existing Linear skill
+  guidance that `save_*` style updates should not clobber unrelated fields.

package/plugins/src/base/skills/posthog-access/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: posthog-access
+description: "Vendor-neutral access layer for PostHog. PostHog skills and observability rules MUST delegate through this skill rather than calling PostHog MCP tools or REST directly. Resolves PostHog MCP first when available, then falls back to POSTHOG_PERSONAL_API_KEY bearer auth."
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# PostHog Access: $ARGUMENTS
+
+Single chokepoint for PostHog operations. Caller skills and rules MUST NOT call
+`mcp__posthog__*` tools or PostHog REST directly.
+
+## Invocation Contract
+
+```text
+operation: query project_id:<ID> payload:{...}
+operation: insights project_id:<ID>
+operation: persons project_id:<ID> [query:<QUERY>]
+operation: events project_id:<ID> [after:<ISO>] [before:<ISO>]
+```
+
+Return parsed JSON in a `<result>` block.
+
+## Substrate Selection
+
+Probe in order:
+
+1. PostHog MCP, if available and authenticated.
+2. `POSTHOG_PERSONAL_API_KEY` bearer token against the configured PostHog host.
+
+PostHog documents personal API keys and bearer authentication. The headless REST
+tier uses:
+
+```bash
+POSTHOG_HOST=${POSTHOG_HOST:-https://app.posthog.com}
+posthog_api() {
+  local path="$1"
+  local method="${2:-GET}"
+  local body="${3:-}"
+  [ -n "$POSTHOG_PERSONAL_API_KEY" ] || {
+    echo "Error: POSTHOG_PERSONAL_API_KEY is not set." >&2
+    return 1
+  }
+  local args=(-sS -X "$method" -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY")
+  [ -n "$body" ] && args+=(-H "Content-Type: application/json" --data-binary "$body")
+  curl "${args[@]}" "${POSTHOG_HOST%/}/api${path}"
+}
+```
+
+If neither tier works, fail with:
+
+```text
+Error: no PostHog access substrate available. Authenticate the PostHog MCP or set POSTHOG_PERSONAL_API_KEY.
+```
+
+## Invariants
+
+- Fallback is gated on `POSTHOG_PERSONAL_API_KEY`.
+- `POSTHOG_HOST` defaults to PostHog Cloud but can point at a self-hosted
+  deployment.
+- Consumer skills do not embed PostHog REST paths.