feat(ai): generate the SDK agent skills from bugsee-for-ai

.claude/CLAUDE.md

@@ -58,6 +58,7 @@ All markdown content, organized by section:
 ### Build Pipeline (`scripts/`)
 - **build.sh** — Runs spell check → `npm run build` → `node scripts/copy-raw-markdown.mjs`
 - **deploy.sh** — Manual fallback deploy: S3 sync + CloudFront invalidation (requires `S3CMD_CONFIG`, `DEPLOY_ENDPOINT`, `CLOUDFRONT_ID` env vars). CI normally deploys automatically on every push to `main` — see **Deployment & Git remote**.
+- **mirror-skills.mjs** — Generates `docs/ai/agent-skills/sdk/**/SKILL.md` from `bugsee/bugsee-for-ai` (the single source of truth for agent skills). **Never edit those files here** — change the skill in `bugsee-for-ai`; `.github/workflows/sync-agent-skills.yml` opens a PR with the regenerated copies. Inputs: `skills-map.json` (which plugin skill feeds which docs path; `docsOwned` lists files that are not generated, currently `sdk/ios/v7`) and `skills-source.json` (the pinned `bugsee-for-ai` commit). `npm run mirror-skills` regenerates at the pin, `node scripts/mirror-skills.mjs --update` moves the pin to `main`, `npm run check-skills` fails on hand edits, `npm run test:mirror` runs the unit tests.
 - **copy-raw-markdown.mjs** — Post-build: copies docs to `build/` as raw `.md` files for AI agents. Strips JSX from `.mdx` files (`<Tabs>` → bold labels), simplifies front matter to title/description/url only
 - **migrate-content.mjs** — One-time MkDocs → Docusaurus migration script (already run, kept for reference)
 

.github/workflows/deploy.yml

@@ -49,6 +49,13 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      # The agent skills under docs/ai/agent-skills/sdk are generated from bugsee/bugsee-for-ai
+      # (see scripts/mirror-skills.mjs). Fail on hand edits to them.
+      - name: Agent skills mirror (tests + no hand edits)
+        run: |
+          npm run test:mirror
+          npm run check-skills
+
       - name: Spell check
         run: npx cspell "docs/**/*.md" "docs/**/*.mdx" --no-cache -c cspell.json
 

.github/workflows/sync-agent-skills.yml

@@ -0,0 +1,135 @@
+name: Sync agent skills
+
+# Keeps docs/ai/agent-skills/sdk/** in step with bugsee/bugsee-for-ai, the single source of
+# truth for agent skills. Whenever bugsee-for-ai main has new skill content this opens (or
+# updates) ONE rolling pull request with the regenerated copies.
+#
+# Triggers
+#   * repository_dispatch "bugsee-for-ai-updated" — sent by bugsee-for-ai on every push to main
+#     that touches skills/ (needs the DOCS_SYNC_TOKEN secret there; without it that repo just
+#     skips the notification).
+#   * schedule — polling fallback, so a sync happens even if the notification is not set up.
+#   * workflow_dispatch — run it by hand from the Actions tab.
+#
+# One-time setup (see the PR that introduced this file):
+#   * Settings > Actions > General > "Allow GitHub Actions to create and approve pull requests".
+#   * Recommended: a GitHub App (owned by the org, not a person) installed on this repo with
+#     Contents + Pull requests: write. Set its client ID as the repository VARIABLE
+#     SYNC_APP_CLIENT_ID and its private key as the repository SECRET SYNC_APP_PRIVATE_KEY. The job
+#     then mints a short-lived token per run, and the sync PR gets the normal "Build and Deploy"
+#     checks. Without the app it falls back to GITHUB_TOKEN: PRs opened that way do not trigger
+#     other workflows, so this job runs the spell check and the site build itself and opens the PR
+#     as a DRAFT if either fails.
+
+on:
+  repository_dispatch:
+    types: [bugsee-for-ai-updated]
+  schedule:
+    - cron: '23 */6 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: sync-agent-skills
+  cancel-in-progress: false
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    env:
+      SYNC_APP_CLIENT_ID: ${{ vars.SYNC_APP_CLIENT_ID }}
+      SYNC_APP_PRIVATE_KEY: ${{ secrets.SYNC_APP_PRIVATE_KEY }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Regenerate from bugsee-for-ai main
+        id: mirror
+        run: |
+          old="$(node -p "require('./scripts/skills-source.json').ref")"
+          node scripts/mirror-skills.mjs --update
+          new="$(node -p "require('./scripts/skills-source.json').ref")"
+          echo "old=$old" >> "$GITHUB_OUTPUT"
+          echo "new=$new" >> "$GITHUB_OUTPUT"
+          if [ -z "$(git status --porcelain -- docs scripts/skills-source.json)" ]; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            echo "Nothing to sync."
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Spell check
+        id: spell
+        if: steps.mirror.outputs.changed == 'true'
+        continue-on-error: true
+        run: |
+          set -o pipefail
+          npx cspell "docs/**/*.md" "docs/**/*.mdx" --no-cache -c cspell.json 2>&1 | tee spell.log
+
+      - name: Build site
+        id: build
+        if: steps.mirror.outputs.changed == 'true'
+        continue-on-error: true
+        run: |
+          set -o pipefail
+          npm run build 2>&1 | tee build.log
+
+      - name: Compose PR body
+        if: steps.mirror.outputs.changed == 'true'
+        run: |
+          {
+            echo "Regenerates the SDK agent skills from [bugsee-for-ai](https://github.com/bugsee/bugsee-for-ai)."
+            echo
+            echo "Changes upstream: https://github.com/bugsee/bugsee-for-ai/compare/${{ steps.mirror.outputs.old }}...${{ steps.mirror.outputs.new }}"
+            echo
+            echo "- Spell check: **${{ steps.spell.outcome }}**"
+            echo "- Site build: **${{ steps.build.outcome }}**"
+            if [ "${{ steps.spell.outcome }}" = "failure" ]; then
+              echo
+              echo "Spell check failed. Valid terms belong in \`cspell.json\`; push that to this branch."
+              echo '```'
+              grep -E 'Unknown word' spell.log | sort -u | head -30
+              echo '```'
+            fi
+            echo
+            echo "Generated files must not be edited here — fix the skill in bugsee-for-ai instead."
+            echo
+            echo "🤖 Generated with [Claude Code](https://claude.com/claude-code)"
+          } > pr-body.md
+
+      - name: Mint a short-lived GitHub App token
+        id: app
+        if: steps.mirror.outputs.changed == 'true' && env.SYNC_APP_CLIENT_ID != '' && env.SYNC_APP_PRIVATE_KEY != ''
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          client-id: ${{ vars.SYNC_APP_CLIENT_ID }}
+          private-key: ${{ secrets.SYNC_APP_PRIVATE_KEY }}
+          permission-contents: write
+          permission-pull-requests: write
+
+      - name: Open or update the sync PR
+        if: steps.mirror.outputs.changed == 'true'
+        uses: peter-evans/create-pull-request@v8.1.1
+        with:
+          token: ${{ steps.app.outputs.token || secrets.GITHUB_TOKEN }}
+          branch: automation/sync-agent-skills
+          delete-branch: true
+          add-paths: |
+            docs/ai/agent-skills
+            scripts/skills-source.json
+          commit-message: "chore(skills): sync agent skills from bugsee-for-ai@${{ steps.mirror.outputs.new }}"
+          title: "chore(skills): sync agent skills from bugsee-for-ai"
+          body-path: pr-body.md
+          draft: ${{ steps.spell.outcome == 'failure' || steps.build.outcome == 'failure' }}

cspell.json

@@ -228,6 +228,8 @@
         "jsbundle",
         "rustflags",
         "sandboxing",
-        "libil"
+        "libil",
+        "unbreak",
+        "Podspec"
     ]
 }

docs/ai/agent-skills/index.md

@@ -21,8 +21,8 @@ The skill files are structured markdown documents that guide AI agents through p
 
 | Platform | Prompt |
 |----------|--------|
-| **Android** | `Use curl to download, read and follow: https://docs.bugsee.com/ai/agent-skills/sdk/android/SKILL.md` |
-| **Android 7.x (beta)** | `Use curl to download, read and follow: https://docs.bugsee.com/ai/agent-skills/sdk/android/v7/SKILL.md` |
+| **Android 6.x** | `Use curl to download, read and follow: https://docs.bugsee.com/ai/agent-skills/sdk/android/SKILL.md` |
+| **Android 7.x** | `Use curl to download, read and follow: https://docs.bugsee.com/ai/agent-skills/sdk/android/v7/SKILL.md` |
 | **iOS** | `Use curl to download, read and follow: https://docs.bugsee.com/ai/agent-skills/sdk/ios/SKILL.md` |
 | **iOS 7.x (beta)** | `Use curl to download, read and follow: https://docs.bugsee.com/ai/agent-skills/sdk/ios/v7/SKILL.md` |
 | **Flutter** | `Use curl to download, read and follow: https://docs.bugsee.com/ai/agent-skills/sdk/flutter/SKILL.md` |

docs/ai/agent-skills/sdk/android/SKILL.md

@@ -1,25 +1,30 @@
 ---
-title: "Bugsee Android SDK"
-name: bugsee-android-sdk
-description: Full Bugsee SDK setup for Android. Use when asked to add Bugsee to Android, install bugsee-android, or set up bug reporting, crash reporting, and video recording for Android applications.
-sidebar_label: "Android"
+title: Bugsee Android SDK 6.x
+name: bugsee-android-sdk-6x
+description: Bugsee SDK setup for legacy Android 6.x apps. Use only when maintaining an app already on bugsee-android 6.x, or when the user explicitly asks for the 6.x line. For new apps and the current SDK, use bugsee-android-sdk (7.x).
+sidebar_label: Android (6.x)
 sidebar_position: 1
 slug: "/ai/agent-skills/sdk/android/SKILL"
-license: proprietary
+license: MIT
 category: sdk-setup
+generated_from: bugsee-for-ai/skills/bugsee-android-sdk-6x/SKILL.md
 ---
 
-# Bugsee Android SDK
+# Bugsee Android SDK (6.x, Legacy)
 
-Opinionated wizard that scans your Android project and guides you through complete Bugsee setup — bug reporting with video, crash reporting, network monitoring, and console logs.
+Opinionated wizard for the **6.x** line of the Bugsee Android SDK — bug reporting with video, crash reporting, network monitoring, and console logs, using the classic `Bugsee.launch(...)` API (the Gradle plugin is optional on 6.x — the 3.x line only uploads symbols; it does no instrumentation).
+
+> **Legacy.** 7.x is the current Android SDK and the default for new apps — use [`bugsee-android-sdk`](https://docs.bugsee.com/ai/agent-skills/sdk/android/v7/SKILL.md) instead. Use this 6.x skill **only** to maintain an app already pinned to `com.bugsee:bugsee-android` 6.x, or when the user explicitly asks for the 6.x line. 7.x is a different, plugin-based SDK with a new API; see the [migration guide](https://docs.bugsee.com/sdk/android/migration/) when upgrading.
 
 ## Invoke This Skill When
 
-- User asks to "add Bugsee to Android" or "set up Bugsee" in an Android app
-- User wants bug reporting, crash reporting, video recording, or network monitoring in Android
-- User mentions `bugsee-android`, `com.bugsee:bugsee-android`, or Bugsee for Kotlin/Java Android
+- The user is maintaining an existing app already on `com.bugsee:bugsee-android` 6.x
+- The user explicitly asks for Bugsee Android "6.x" / the "legacy" / "old" SDK
+- The user's project pins a 6.x version (`com.bugsee:bugsee-android:6.x.y`) and they want to keep it
+
+For a fresh "add Bugsee to Android" with no 6.x signal, use the current [`bugsee-android-sdk`](https://docs.bugsee.com/ai/agent-skills/sdk/android/v7/SKILL.md) (7.x) skill instead.
 
-> **Note:** Always verify against [docs.bugsee.com/sdk/android/installation/](https://docs.bugsee.com/sdk/android/installation/) before implementing.
+> **Note:** Always verify against [docs.bugsee.com/sdk/android/v6/installation/](https://docs.bugsee.com/sdk/android/v6/installation/) before implementing. 6.x docs live under `/sdk/android/v6/`.
 
 ---
 
@@ -73,19 +78,19 @@ Add the Bugsee dependency to the app module's build file.
 
 ```gradle
 dependencies {
-    implementation 'com.bugsee:bugsee-android:+'
+    implementation 'com.bugsee:bugsee-android:6.0.4'
 }
 ```
 
 **Kotlin DSL (`app/build.gradle.kts`):**
 
 ```kotlin
 dependencies {
-    implementation("com.bugsee:bugsee-android:+")
+    implementation("com.bugsee:bugsee-android:6.0.4")
 }
 ```
 
-> The `+` fetches the latest version. Pin to a specific version from [release notes](https://docs.bugsee.com/sdk/android/release-notes/) for production stability.
+> `6.0.4` is the latest 6.x release — pin to it (or another 6.x version from the [6.x release notes](https://docs.bugsee.com/sdk/android/v6/release-notes/)). **Do not** use `+`: that resolves to 7.x, which is the plugin-based SDK with a different API — switch to the [`bugsee-android-sdk`](https://docs.bugsee.com/ai/agent-skills/sdk/android/v7/SKILL.md) (7.x) skill for that.
 
 If your `compileSdkVersion` is below 29 and you get `android:foregroundServiceType not found`, set `compileSdkVersion` to 29 or higher.
 
@@ -179,7 +184,7 @@ Common options:
 | `ScreenshotEnabled` | `true` | Attach screenshot to report |
 | `WifiOnlyUpload` | `false` | Upload only on WiFi |
 
-Full options: [docs.bugsee.com/sdk/android/configuration/](https://docs.bugsee.com/sdk/android/configuration/)
+Full options: [docs.bugsee.com/sdk/android/v6/configuration/](https://docs.bugsee.com/sdk/android/v6/configuration/)
 
 ---
 
@@ -201,13 +206,48 @@ Check the Bugsee dashboard for the incoming report.
 
 ---
 
+## Debug Symbols
+
+The 6.x line pairs with the **3.x** Gradle plugin (latest **3.6**) — never 4.x, which targets the 7.x module layout ([compatibility](https://docs.bugsee.com/sdk/android/gradle-plugin/requirements/)). Plugin 3.x does no bytecode instrumentation; it uploads the R8/ProGuard `mapping.txt` (and, with `ndk(true)`, NDK symbols) on each release build and injects a `BUILD_UUID` into the merged manifest ([6.x Gradle plugin](https://docs.bugsee.com/sdk/android/v6/gradle-plugin/)):
+
+```kotlin
+// app/build.gradle.kts
+plugins {
+    id("com.android.application")
+    id("com.bugsee.android.gradle") version "3.6"
+}
+
+bugsee {
+    appToken("<your_app_token>")
+    ndk(true)   // only if the app ships native libraries
+}
+```
+
+3.x takes the boolean `ndk(true)`; the nested `ndk { enabled.set(true) }` block is 4.x-only.
+
+Without the plugin — or from CI with no Gradle — upload the mapping through the [Bugsee CLI](https://github.com/bugsee/bugsee-for-ai/blob/main/skills/bugsee-cli/SKILL.md) (or the dashboard's manual upload):
+
+```bash
+bugsee-cli debug-files upload ./app/build/outputs/mapping/release \
+    --version 1.4.0 --build 1400
+```
+
+`--version` / `--build` must match the shipped build — a mismatch uploads a mapping that is accepted and then never resolves a crash. Native NDK symbols go up with `--type elf` and a `--uuid` matching what the SDK reports.
+
+Upgrading to 7.x moves to plugin 4.x, which adds instrumentation on top of the uploads.
+
+Full workflow: [`bugsee-upload-symbols`](https://github.com/bugsee/bugsee-for-ai/blob/main/skills/bugsee-upload-symbols/SKILL.md).
+
+---
+
 ## Documentation Links
 
-- [Installation](https://docs.bugsee.com/sdk/android/installation/)
-- [Configuration](https://docs.bugsee.com/sdk/android/configuration/)
-- [Custom data](https://docs.bugsee.com/sdk/android/v6/custom/)
-- [Network events](https://docs.bugsee.com/sdk/android/network/)
-- [Console logs](https://docs.bugsee.com/sdk/android/logs/)
-- [Privacy](https://docs.bugsee.com/sdk/android/privacy/overview/)
-- [Manual invocation](https://docs.bugsee.com/sdk/android/v6/manual/)
-- [Release notes](https://docs.bugsee.com/sdk/android/release-notes/)
+- [Installation (6.x)](https://docs.bugsee.com/sdk/android/v6/installation/)
+- [Configuration (6.x)](https://docs.bugsee.com/sdk/android/v6/configuration/)
+- [Custom data (6.x)](https://docs.bugsee.com/sdk/android/v6/custom/)
+- [Network events (6.x)](https://docs.bugsee.com/sdk/android/v6/network/)
+- [Console logs (6.x)](https://docs.bugsee.com/sdk/android/v6/logs/)
+- [Privacy (6.x)](https://docs.bugsee.com/sdk/android/v6/privacy/overview/)
+- [Manual invocation (6.x)](https://docs.bugsee.com/sdk/android/v6/manual/)
+- [Release notes (6.x)](https://docs.bugsee.com/sdk/android/v6/release-notes/)
+- [Migrate to 7.x](https://docs.bugsee.com/sdk/android/migration/)