Merge remote-tracking branch 'origin/main' into apple-pay-flow

Author: broody

.agents/skills/package-filter/SKILL.md

@@ -25,7 +25,7 @@ Execute commands in specific packages within the monorepo.
 pnpm --filter @cartridge/keychain test
 
 # Build specific package
-pnpm --filter @cartridge/controller build
+pnpm --filter @cartridge/controller build:deps
 
 # Run dev server for keychain only
 pnpm --filter @cartridge/keychain dev

.agents/skills/run-tests/SKILL.md

@@ -130,7 +130,7 @@ If Storybook tests fail with visual differences:
 
 ```bash
 # Check specific package
-pnpm controller build
+pnpm controller build:deps
 pnpm keychain build
 ```
 

.claude/settings.json

@@ -17,6 +17,7 @@
       "Bash(pnpm:storybook:*)",
       "Bash(pnpm:e2e:*)",
       "Bash(pnpm:--filter:*)",
+      "Bash(gh:pr:*)",
       "Bash(git:status)",
       "Bash(git:diff)",
       "Bash(git:log)",

.github/workflows/claude-code-review.yml

@@ -8,8 +8,8 @@ permissions:
   contents: read
   pull-requests: write
   issues: read
-
   id-token: write
+
 jobs:
   claude-code-review:
     runs-on: ubuntu-latest
@@ -25,6 +25,7 @@ jobs:
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           prompt: "/review"
+          allowed_tools: "Read,Glob,Grep"
           # CLAUDE.md is a symlink to AGENTS.md in this repo; keep repo rules there.
           claude_args: |
             --max-turns 4

.github/workflows/docs-sync.yml

@@ -33,34 +33,33 @@ jobs:
         run: |
           set -e
           if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-            # Get changed files for the specified commit
             git fetch origin
-            CHANGED_FILES=$(git diff --name-only ${{ github.event.inputs.commit_sha }}~1 ${{ github.event.inputs.commit_sha }})
+            DIFF_BASE="${{ github.event.inputs.commit_sha }}~1"
+            DIFF_HEAD="${{ github.event.inputs.commit_sha }}"
           else
-            # Get list of changed files in the merged PR
             git fetch origin main
-            CHANGED_FILES=$(git diff --name-only ${{ github.event.pull_request.base.sha }} ${{ github.event.pull_request.merge_commit_sha }})
+            DIFF_BASE="${{ github.event.pull_request.base.sha }}"
+            DIFF_HEAD="${{ github.event.pull_request.merge_commit_sha }}"
           fi
+          CHANGED_FILES=$(git diff --name-only "$DIFF_BASE" "$DIFF_HEAD")
+          # Truncate diff to avoid blowing up the prompt
+          DIFF_CONTENT=$(git diff "$DIFF_BASE" "$DIFF_HEAD" -- '*.ts' '*.tsx' '*.md' | head -c 60000)
           echo "changed_files<<EOF" >> $GITHUB_OUTPUT
           echo "$CHANGED_FILES" >> $GITHUB_OUTPUT
           echo "EOF" >> $GITHUB_OUTPUT
+          echo "diff_content<<EOF" >> $GITHUB_OUTPUT
+          echo "$DIFF_CONTENT" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
 
       - name: Check if docs update needed
         id: check-docs
         run: |
-          # Check if changes require documentation updates
           NEEDS_DOCS_UPDATE=false
 
-          # Define patterns that typically require docs updates
           DOCS_PATTERNS=(
-            "^src/.*\.ts$"
-            "^src/.*\.tsx$"
             "^packages/.*/src/.*\.ts$"
             "^packages/.*/src/.*\.tsx$"
-            "^README\.md$"
-            "^CHANGELOG\.md$"
             "^docs/"
-            "package\.json$"
             "^api/"
             "^schema/"
           )
@@ -90,71 +89,76 @@ jobs:
         uses: anthropics/claude-code-action@beta
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          model: "claude-sonnet-4-5-20250929"
           direct_prompt: |
-            I need you to analyze the changes in this controller repository PR and update the documentation in the cartridge-gg/docs repository accordingly.
+            Analyze changes in this controller repository and update documentation
+            in the cartridge-gg/docs repository ONLY if user-facing behavior changed.
 
             **Change Information:**
             - Title: ${{ github.event.pull_request.title || format('Manual trigger for commit {0}', github.event.inputs.commit_sha) }}
             - Description: ${{ github.event.pull_request.body || 'Manually triggered documentation sync' }}
             - Files changed: ${{ steps.changed-files.outputs.changed_files }}
             - Commit SHA: ${{ github.event.pull_request.merge_commit_sha || github.event.inputs.commit_sha }}
 
-            **Your tasks:**
-            1. Review the changed files and PR description to understand what functionality was added, modified, or removed
-            2. Check the docs-repo directory to see what documentation currently exists
-            3. Determine if any existing documentation needs updates or if new documentation should be created
-            4. If updates are needed:
-               - Create or update the appropriate documentation files in the docs-repo directory
-               - Ensure the documentation accurately reflects the current state of the controller
-               - Follow the existing documentation style and structure
-               - Focus on user-facing changes, API changes, new features, or breaking changes
-
-            **Important guidelines:**
-            - Only create documentation updates if they are actually needed
-            - Don't document internal implementation details unless they affect usage
-            - If no documentation updates are needed, simply state that and exit
-            - DO NOT create git branches, commits, or PRs - just update the files
-
-            The docs repository is checked out in the `docs-repo` directory. Please analyze the controller changes and update the documentation files accordingly.
+            **Diff of user-facing files:**
+            ${{ steps.changed-files.outputs.diff_content }}
+
+            **Docs repo structure** (checked out in `docs-repo/`):
+            The site uses Vocs. Content lives in `docs-repo/src/pages/` with three sections:
+            - `controller/` — wallet, sessions, policies, presets, achievements, inventory, native integrations, examples
+            - `slot/` — Katana/Torii deployment, billing, scale, paymaster, vRNG, RPC
+            - `arcade/` — game hub setup, marketplace
+            Sidebar config is in `docs-repo/vocs.config.ts`.
+
+            **Rules — read these carefully:**
+            1. DEFAULT TO NO CHANGES. Most code PRs do not need docs updates.
+               Internal refactors, test changes, CI changes, and dependency bumps need nothing.
+               Only proceed if there is a concrete user-facing change (new API, changed behavior,
+               new feature, removed feature, changed configuration).
+            2. SINGLE CANONICAL LOCATION. Each piece of information belongs on exactly one page.
+               Find the one page that owns the topic and make your substantive edits there.
+               Other pages MAY add a brief cross-reference linking to the canonical page,
+               but do NOT duplicate explanations, code samples, or configuration details
+               across multiple pages.
+            3. MINIMAL EDITS. Update only the specific section affected. Do not rewrite
+               surrounding paragraphs, add new sections for context, or reorganize existing content.
+            4. ONE CODE EXAMPLE per concept. If a code sample is needed, add it once in the
+               canonical location. Do not add the same or similar examples to multiple pages.
+            5. Do NOT create git branches, commits, or PRs — just update files.
+            6. If no documentation updates are needed, state that clearly and exit.
 
           allowed_tools: "Read,Write,Edit,MultiEdit,Glob,Grep"
 
       - name: Create branch and commit changes
         if: steps.check-docs.outputs.needs_update == 'true'
         working-directory: docs-repo
         run: |
-          # Configure git
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
 
-          # Check if there are any changes
           if [ -n "$(git status --porcelain)" ]; then
-            # Create new branch
             BRANCH_NAME="docs-update-$(date +%s)"
             git checkout -b "$BRANCH_NAME"
-            
-            # Add and commit changes
+
             git add .
             if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
               git commit -m "docs: Update documentation for controller commit ${{ github.event.inputs.commit_sha }}
 
               Updates documentation to reflect changes made in commit:
               ${{ github.event.inputs.commit_sha }}
-              
+
               Manually triggered documentation sync"
             else
               git commit -m "docs: Update documentation for controller PR #${{ github.event.pull_request.number }}
 
               Updates documentation to reflect changes made in:
               ${{ github.event.pull_request.title }}
-              
+
               Related controller PR: cartridge-gg/controller#${{ github.event.pull_request.number }}"
             fi
-            
-            # Push branch
+
             git push origin "$BRANCH_NAME"
-            
-            # Create PR
+
             if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
               gh pr create \
                 --title "docs: Update documentation for controller commit ${{ github.event.inputs.commit_sha }}" \
@@ -166,6 +170,7 @@ jobs:
               - Trigger: Manual documentation sync
 
               Please review the documentation changes to ensure they accurately reflect the controller updates."
+              gh pr merge --auto --squash
             else
               gh pr create \
                 --title "docs: Update documentation for controller PR #${{ github.event.pull_request.number }}" \
@@ -176,6 +181,7 @@ jobs:
               - Files changed: ${{ steps.changed-files.outputs.changed_files }}
 
               Please review the documentation changes to ensure they accurately reflect the controller updates."
+              gh pr merge --auto --squash
             fi
           else
             echo "No documentation changes were made by Claude"
@@ -186,5 +192,4 @@ jobs:
       - name: Cleanup
         if: always()
         run: |
-          # Clean up any temporary files or directories
           rm -rf docs-repo || true

.github/workflows/e2e.yml

@@ -1,28 +1,68 @@
- name: End-to-End tests
- on:
-   push:
-     branches: [main]
-   pull_request:
-     branches: [main]
- jobs:
-   test:
-     if: always() == 'skip' # temporarily skip cc @jun
-     timeout-minutes: 60
-     runs-on: ubuntu-latest
-     steps:
-       - uses: actions/checkout@v4
-       - uses: actions/setup-node@v4
-         with:
-           node-version: lts/*
-       - name: Install dependencies
-         run: npm install -g pnpm && pnpm install
-       - name: Install Playwright Browsers
-         run: pnpm exec playwright install --with-deps
-       - name: Run Playwright tests
-         run: pnpm exec playwright test
-       - uses: actions/upload-artifact@v4
-         if: always()
-         with:
-           name: playwright-report
-           path: playwright-report/
-           retention-days: 30
+name: End-to-End tests
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  next:
+    if: always() == 'skip' # temporarily skip cc @jun
+    permissions:
+      contents: read
+    timeout-minutes: 60
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+      - name: Install dependencies
+        run: npm install -g pnpm && pnpm install
+      - name: Install Playwright Browsers
+        run: pnpm exec playwright install --with-deps
+      - name: Run Playwright tests
+        run: pnpm exec playwright test
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 30
+
+  capacitor:
+    permissions:
+      contents: read
+    timeout-minutes: 60
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+      - uses: actions/cache@v4
+        with:
+          path: ~/.pnpm-store
+          key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-
+      - uses: pnpm/action-setup@v4
+        with:
+          run_install: |
+            - args: [--frozen-lockfile]
+      - name: Build
+        run: pnpm build
+      - name: Install Playwright Browsers
+        run: pnpm --filter cartridge-capacitor-example exec playwright install --with-deps chromium
+      - name: Run Capacitor E2E tests
+        run: pnpm --filter cartridge-capacitor-example e2e
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: capacitor-playwright-report
+          path: examples/capacitor/playwright-report/
+          retention-days: 30

.github/workflows/release.yml

@@ -37,15 +37,18 @@ jobs:
         run: |
           echo "VERSION=$(jq -r '.version' packages/controller/package.json)" >> $GITHUB_OUTPUT
 
-      - name: Publish release to npm
-        if: ${{ github.event.pull_request.head.ref == 'prepare-release' }}
+      - name: Publish to npm
+        if: |
+          github.event.pull_request.head.ref == 'prepare-release' ||
+          github.event.pull_request.head.ref == 'prepare-prerelease' ||
+          github.event_name == 'workflow_dispatch'
         run: |
-          pnpm release
-
-      - name: Publish prerelease to npm
-        if: ${{ github.event.pull_request.head.ref == 'prepare-prerelease' }}
-        run: |
-          pnpm release:prerelease
+          VERSION="${{ steps.get_version.outputs.VERSION }}"
+          if [[ "$VERSION" == *-* ]]; then
+            pnpm release:prerelease
+          else
+            pnpm release
+          fi
 
       - name: Extract changelog for version
         id: get_changelog

.gitignore

@@ -55,6 +55,7 @@ htmlcov/
 .cache
 nosetests.xml
 coverage.xml
+**/coverage/
 *.cover
 *.py,cover
 .hypothesis/

AGENTS.md

@@ -1,3 +1,6 @@
+<!-- SKILLS_INDEX_START -->
+[Agent Skills Index]|root: ./agents|IMPORTANT: Prefer retrieval-led reasoning over pre-training for any tasks covered by skills.|skills|agent-browser:{agent-browser.md},clean-build:{clean-build.md},code-review:{code-review.md},codegen:{codegen.md},create-a-plan:{create-a-plan.md},create-pr:{create-pr.md},dispatch-release:{dispatch-release.md},find-skills:{find-skills.md},package-filter:{package-filter.md},pre-commit-check:{pre-commit-check.md},release-prep:{release-prep.md},run-tests:{run-tests.md},test:{test.md},update-pr:{update-pr.md},update-storybook-snapshots:{update-storybook-snapshots.md},validate-before-merge:{validate-before-merge.md}
+<!-- SKILLS_INDEX_END -->
 # Repository Guidelines
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.