Fix QueryFilter IN/NOT_IN serialization

.claude/docs/mistdemo/configuration.md

@@ -230,7 +230,7 @@ All configuration keys can be set via environment variables.
 | `api_token` | `CLOUDKIT_API_TOKEN` |
 | `environment` | `CLOUDKIT_ENVIRONMENT` |
 | `database` | `CLOUDKIT_DATABASE` |
-| `web_auth_token` | `CLOUDKIT_WEBAUTH_TOKEN` |
+| `web_auth_token` | `CLOUDKIT_WEB_AUTH_TOKEN` |
 | `key_id` | `CLOUDKIT_KEY_ID` |
 | `private_key_file` | `CLOUDKIT_PRIVATE_KEY_FILE` |
 | `output` | `MISTDEMO_OUTPUT` |

.claude/docs/mistdemo/error-handling.md

@@ -444,7 +444,7 @@ query_with_auth_retry() {
 
   if [ "$code" = "AUTHENTICATION_FAILED" ]; then
     echo "Token expired, re-authenticating..." >&2
-    export CLOUDKIT_WEBAUTH_TOKEN=$(mistdemo auth-token -a "$CLOUDKIT_API_TOKEN")
+    export CLOUDKIT_WEB_AUTH_TOKEN=$(mistdemo auth-token -a "$CLOUDKIT_API_TOKEN")
 
     # Retry
     mistdemo query --database private
@@ -469,7 +469,7 @@ Error: Invalid or expired web authentication token
 **Solution:**
 ```bash
 # Get new token
-export CLOUDKIT_WEBAUTH_TOKEN=$(mistdemo auth-token -a "$CLOUDKIT_API_TOKEN")
+export CLOUDKIT_WEB_AUTH_TOKEN=$(mistdemo auth-token -a "$CLOUDKIT_API_TOKEN")
 
 # Retry operation
 mistdemo query --database private

.claude/docs/mistdemo/operations-auth.md

@@ -6,29 +6,25 @@ Authentication operations handle obtaining and validating CloudKit authenticatio
 
 ### Authentication Methods
 
-CloudKit Web Services supports two authentication methods:
-
-#### 1. Web Authentication Token (User Authentication)
-- **Use Case**: User-specific operations in private/shared databases
-- **Flow**: OAuth-style browser-based authentication
-- **Token Type**: Web auth token (user-scoped)
+#### 1. Web Authentication Token — Private/Shared Database
+- **Use Case**: Private and shared database operations
+- **Credentials**: `CLOUDKIT_API_TOKEN` + `CLOUDKIT_WEB_AUTH_TOKEN`
+- **Flow**: OAuth-style browser-based sign-in (`mistdemo auth-token`)
 - **Duration**: Temporary (expires periodically)
-- **Required For**: Private and shared database access
 
-#### 2. Server-to-Server Key (Server Authentication)
-- **Use Case**: Server-side applications, automation
-- **Flow**: ECDSA key-based signing
-- **Token Type**: None (signs requests directly)
+#### 2. Server-to-Server Key — Public Database
+- **Use Case**: Public database operations
+- **Credentials**: `CLOUDKIT_KEY_ID` + `CLOUDKIT_PRIVATE_KEY` or `CLOUDKIT_PRIVATE_KEY_PATH`
+- **Flow**: ECDSA request signing (no browser required)
 - **Duration**: Permanent (until key is revoked)
-- **Required For**: Server automation, background jobs
 
 ### Database Access Requirements
 
-| Database | Public Operations | Authenticated Operations |
-|----------|------------------|--------------------------|
-| **Public** | API token only | API token only |
-| **Private** | Not allowed | Web auth token or server key |
-| **Shared** | Not allowed | Web auth token or server key |
+| Database | Required Credentials | Auth Method |
+|----------|---------------------|-------------|
+| **Public** | `CLOUDKIT_KEY_ID` + `CLOUDKIT_PRIVATE_KEY[_FILE]` | Server-to-server signing |
+| **Private** | `CLOUDKIT_API_TOKEN` + `CLOUDKIT_WEB_AUTH_TOKEN` | Web authentication |
+| **Shared** | `CLOUDKIT_API_TOKEN` + `CLOUDKIT_WEB_AUTH_TOKEN` | Web authentication |
 
 ## auth-token
 
@@ -71,7 +67,7 @@ mistdemo auth-token --api-token YOUR_API_TOKEN
 
 **Save to environment variable:**
 ```bash
-export CLOUDKIT_WEBAUTH_TOKEN=$(mistdemo auth-token --api-token YOUR_API_TOKEN)
+export CLOUDKIT_WEB_AUTH_TOKEN=$(mistdemo auth-token --api-token YOUR_API_TOKEN)
 ```
 
 **Save to file:**
@@ -145,7 +141,7 @@ Waiting for authentication callback...
 
 # Check if token exists and is valid
 if [ -f ~/.mistdemo/token.txt ]; then
-  export CLOUDKIT_WEBAUTH_TOKEN=$(cat ~/.mistdemo/token.txt)
+  export CLOUDKIT_WEB_AUTH_TOKEN=$(cat ~/.mistdemo/token.txt)
   if mistdemo validate > /dev/null 2>&1; then
     echo "Using existing token"
     exit 0
@@ -156,15 +152,15 @@ fi
 echo "Obtaining new authentication token..."
 mistdemo auth-token --api-token "$CLOUDKIT_API_TOKEN" > ~/.mistdemo/token.txt
 chmod 600 ~/.mistdemo/token.txt
-export CLOUDKIT_WEBAUTH_TOKEN=$(cat ~/.mistdemo/token.txt)
+export CLOUDKIT_WEB_AUTH_TOKEN=$(cat ~/.mistdemo/token.txt)
 echo "Authentication complete"
 ```
 
 **CI/CD automation:**
 ```bash
 # For server-to-server authentication
 export CLOUDKIT_KEY_ID="your-key-id"
-export CLOUDKIT_PRIVATE_KEY_FILE="/path/to/private-key.pem"
+export CLOUDKIT_PRIVATE_KEY_PATH="/path/to/private-key.pem"
 
 # No web auth token needed
 mistdemo query --database private
@@ -173,7 +169,7 @@ mistdemo query --database private
 **Interactive session:**
 ```bash
 # One-time setup per session
-export CLOUDKIT_WEBAUTH_TOKEN=$(mistdemo auth-token -a YOUR_API_TOKEN)
+export CLOUDKIT_WEB_AUTH_TOKEN=$(mistdemo auth-token -a YOUR_API_TOKEN)
 
 # Use for all subsequent commands
 mistdemo query --database private
@@ -270,7 +266,7 @@ fi
 
 mistdemo validate --test-query || {
   echo "Error: Invalid authentication. Please re-authenticate."
-  export CLOUDKIT_WEBAUTH_TOKEN=$(mistdemo auth-token -a "$CLOUDKIT_API_TOKEN")
+  export CLOUDKIT_WEB_AUTH_TOKEN=$(mistdemo auth-token -a "$CLOUDKIT_API_TOKEN")
 }
 
 # Proceed with operations
@@ -295,56 +291,48 @@ done
 
 ## Authentication Workflows
 
-### First-Time Setup
+### First-Time Setup — Public Database
 
 ```bash
-# 1. Set API token (from CloudKit Dashboard)
-export CLOUDKIT_API_TOKEN="your-api-token-here"
+# 1. Set container ID
+export CLOUDKIT_CONTAINER_IDENTIFIER="iCloud.com.example.MyApp"
 
-# 2. Set container ID
-export CLOUDKIT_CONTAINER_ID="iCloud.com.example.MyApp"
+# 2. Set server-to-server credentials (from CloudKit Dashboard)
+export CLOUDKIT_KEY_ID="your-key-id"
+export CLOUDKIT_PRIVATE_KEY_PATH="/path/to/eckey.pem"
 
 # 3. Test public database access
-mistdemo query --database public
-
-# 4. Get web auth token for private access
-export CLOUDKIT_WEBAUTH_TOKEN=$(mistdemo auth-token -a "$CLOUDKIT_API_TOKEN")
-
-# 5. Verify private access
-mistdemo current-user --database private
+mistdemo query
 ```
 
-### Development Environment
+### First-Time Setup — Private Database
 
 ```bash
-# .env file (never commit this)
-CLOUDKIT_CONTAINER_ID=iCloud.com.example.MyApp
-CLOUDKIT_API_TOKEN=your-api-token
-CLOUDKIT_ENVIRONMENT=development
-CLOUDKIT_DATABASE=private
+# 1. Set container ID
+export CLOUDKIT_CONTAINER_IDENTIFIER="iCloud.com.example.MyApp"
 
-# Load environment
-source .env
+# 2. Set API token (from CloudKit Dashboard)
+export CLOUDKIT_API_TOKEN="your-api-token"
+
+# 3. Get web auth token (browser sign-in)
+export CLOUDKIT_WEB_AUTH_TOKEN=$(mistdemo auth-token)
 
-# Get token for session
-export CLOUDKIT_WEBAUTH_TOKEN=$(mistdemo auth-token -a "$CLOUDKIT_API_TOKEN")
+# 4. Verify private access
+mistdemo current-user
 ```
 
-### Production Environment (Server-to-Server)
+### Automated / CI Environment (Public Database)
 
 ```bash
-# Generate key pair (one time)
-# See CloudKit documentation for key generation
-
 # Set environment variables
-export CLOUDKIT_CONTAINER_ID=iCloud.com.example.MyApp
-export CLOUDKIT_API_TOKEN=your-api-token
+export CLOUDKIT_CONTAINER_IDENTIFIER=iCloud.com.example.MyApp
 export CLOUDKIT_ENVIRONMENT=production
 export CLOUDKIT_KEY_ID=your-key-id
-export CLOUDKIT_PRIVATE_KEY_FILE=/secure/path/to/key.pem
+export CLOUDKIT_PRIVATE_KEY_PATH=/secure/path/to/key.pem
 
-# No web auth needed
-mistdemo query --database private
+# Run public database operations — no browser required
+mistdemo query
+mistdemo demo-in-filter
 ```
 
 ## Troubleshooting
@@ -353,7 +341,7 @@ mistdemo query --database private
 ```bash
 # Error: AUTHENTICATION_FAILED
 # Solution: Get new token
-export CLOUDKIT_WEBAUTH_TOKEN=$(mistdemo auth-token -a "$CLOUDKIT_API_TOKEN")
+export CLOUDKIT_WEB_AUTH_TOKEN=$(mistdemo auth-token -a "$CLOUDKIT_API_TOKEN")
 ```
 
 ### Port Already in Use

.claude/docs/mistdemo/operations-user.md

@@ -46,7 +46,7 @@ mistdemo current-user --fields "userRecordName,firstName,lastName"
 **With authentication:**
 ```bash
 # Get web auth token first
-export CLOUDKIT_WEBAUTH_TOKEN=$(mistdemo auth-token -a YOUR_API_TOKEN)
+export CLOUDKIT_WEB_AUTH_TOKEN=$(mistdemo auth-token -a YOUR_API_TOKEN)
 
 # Query current user
 mistdemo current-user --database private
@@ -294,7 +294,7 @@ mistdemo lookup-contacts \
 ### Verify Authentication and Get User Info
 ```bash
 # Set up authentication
-export CLOUDKIT_WEBAUTH_TOKEN=$(mistdemo auth-token -a YOUR_API_TOKEN)
+export CLOUDKIT_WEB_AUTH_TOKEN=$(mistdemo auth-token -a YOUR_API_TOKEN)
 
 # Get current user
 mistdemo current-user --database private -o table

.claude/docs/mistdemo/overview.md

@@ -34,8 +34,7 @@ All subcommands accept these global options:
 
 | Option | Short | Environment Variable | Description |
 |--------|-------|---------------------|-------------|
-| `--container-id` | `-c` | `CLOUDKIT_CONTAINER_ID` | CloudKit container identifier |
-| `--api-token` | `-a` | `CLOUDKIT_API_TOKEN` | CloudKit API token |
+| `--container-id` | `-c` | `CLOUDKIT_CONTAINER_IDENTIFIER` | CloudKit container identifier |
 
 ### Database & Environment
 
@@ -50,11 +49,20 @@ Valid values:
 
 ### Authentication Options
 
+**Public database** — server-to-server signing:
+
+| Option | Environment Variable | Description |
+|--------|---------------------|-------------|
+| `--key-id` | `CLOUDKIT_KEY_ID` | Server-to-server key ID (required for public database) |
+| `--private-key-file` | `CLOUDKIT_PRIVATE_KEY_PATH` | Path to ECDSA private key PEM file |
+| `--private-key` | `CLOUDKIT_PRIVATE_KEY` | ECDSA private key as inline string |
+
+**Private/shared database** — web authentication:
+
 | Option | Environment Variable | Description |
 |--------|---------------------|-------------|
-| `--web-auth-token` | `CLOUDKIT_WEBAUTH_TOKEN` | Web authentication token (required for private/shared databases) |
-| `--key-id` | `CLOUDKIT_KEY_ID` | Server-to-server key ID |
-| `--private-key-file` | `CLOUDKIT_PRIVATE_KEY_FILE` | Path to server-to-server private key |
+| `--api-token` | `CLOUDKIT_API_TOKEN` | CloudKit API token (required for private/shared database) |
+| `--web-auth-token` | `CLOUDKIT_WEB_AUTH_TOKEN` | Web authentication token (from `mistdemo auth-token`) |
 
 ### Output Options
 
@@ -81,22 +89,26 @@ Valid output formats: `json`, `table`, `csv`, `yaml`
 
 ## Authentication Overview
 
-MistDemo supports two authentication methods:
-
-### 1. Web Auth Token (User Authentication)
-Required for accessing private or shared databases.
+MistDemo uses different credentials depending on the target database:
 
+### Public Database — Server-to-Server Key
 ```bash
-# Obtain token
-export CLOUDKIT_WEBAUTH_TOKEN=$(mistdemo auth-token --api-token YOUR_API_TOKEN)
+export CLOUDKIT_KEY_ID="your-key-id"
+export CLOUDKIT_PRIVATE_KEY_PATH="/path/to/eckey.pem"
+mistdemo query
+mistdemo demo-in-filter
+```
 
-# Use token in commands
-mistdemo query --database private
+### Private/Shared Database — Web Authentication
+```bash
+export CLOUDKIT_API_TOKEN="your-api-token"
+export CLOUDKIT_WEB_AUTH_TOKEN=$(mistdemo auth-token)
+mistdemo current-user
 ```
 
 See [Authentication Operations](operations-auth.md) for details.
 
-### 2. Server-to-Server Key (Server Authentication)
+### Legacy: Server-to-Server Key (Private Database)
 For server-side applications using key-based authentication.
 
 ```bash
@@ -215,7 +227,7 @@ mistdemo create \
 ### Authenticated Operations
 ```bash
 # Get auth token first
-export CLOUDKIT_WEBAUTH_TOKEN=$(mistdemo auth-token -a YOUR_API_TOKEN)
+export CLOUDKIT_WEB_AUTH_TOKEN=$(mistdemo auth-token -a YOUR_API_TOKEN)
 
 # Use private database
 mistdemo query --database private

.github/actions/setup-mistkit/action.yml

@@ -0,0 +1,26 @@
+name: Setup MistKit
+description: Replaces the local MistKit path dependency with a remote branch reference
+
+inputs:
+  branch:
+    description: MistKit branch to use (leave empty to keep the local path dependency)
+
+runs:
+  using: composite
+  steps:
+    - name: Update Package.swift (Unix)
+      if: inputs.branch != '' && runner.os != 'Windows'
+      shell: bash
+      run: |
+        if [ "$RUNNER_OS" = "macOS" ]; then
+          sed -i '' 's|\.package(name: "MistKit", path: "\.\./\.\.")|.package(url: "https://github.com/brightdigit/MistKit.git", branch: "'"${{ inputs.branch }}"'")|g' Package.swift
+        else
+          sed -i 's|\.package(name: "MistKit", path: "\.\./\.\.")|.package(url: "https://github.com/brightdigit/MistKit.git", branch: "'"${{ inputs.branch }}"'")|g' Package.swift
+        fi
+        rm -f Package.resolved
+    - name: Update Package.swift (Windows)
+      if: inputs.branch != '' && runner.os == 'Windows'
+      shell: pwsh
+      run: |
+        (Get-Content Package.swift) -replace '\.package\(name: "MistKit", path: "\.\./\.\."\)', ".package(url: `"https://github.com/brightdigit/MistKit.git`", branch: `"${{ inputs.branch }}`")" | Set-Content Package.swift
+        Remove-Item -Path Package.resolved -Force -ErrorAction SilentlyContinue

CLAUDE.md

@@ -223,7 +223,9 @@ A `ClientTransport` extension could provide a generic upload method, but would n
 
 ### CloudKit Web Services Integration
 - Base URL: `https://api.apple-cloudkit.com`
-- Authentication: API Token + Web Auth Token or Server-to-Server Key Authentication
+- Authentication:
+  - **Public database**: `CLOUDKIT_KEY_ID` + `CLOUDKIT_PRIVATE_KEY` or `CLOUDKIT_PRIVATE_KEY_PATH` → server-to-server signing
+  - **Private database**: `CLOUDKIT_API_TOKEN` + `CLOUDKIT_WEB_AUTH_TOKEN` → web authentication
 - All operations should reference the OpenAPI spec in `cloudkit-api-openapi.yaml`
 - URL Pattern: `/database/{version}/{container}/{environment}/{database}/{operation}`
 - Supported databases: `public`, `private`, `shared`
@@ -262,6 +264,8 @@ A `ClientTransport` extension could provide a generic upload method, but would n
 
 The Swift package uses Apple's swift-openapi-generator to create type-safe client code from the OpenAPI specification. Generated code is placed in `Sources/MistKit/Generated/` and should not be committed to version control.
 
+> **IMPORTANT: Never manually edit files in `Sources/MistKit/Generated/`.** These files are auto-generated from `openapi.yaml`. Any manual edits will be lost when code is regenerated. Instead, modify `openapi.yaml` and regenerate using `./Scripts/generate-openapi.sh`.
+
 The `openapi.yaml` file serves as the source of truth for:
 - All available endpoints and their HTTP methods
 - Request/response schemas and models

Examples/BushelCloud/.github/actions/cloudkit-sync/action.yml

@@ -145,6 +145,10 @@ runs:
         path: ./binary
         branch: ${{ github.ref_name }}
 
+    - name: Setup MistKit
+      if: steps.download-binary.outcome != 'success'
+      uses: ./.github/actions/setup-mistkit
+
     - name: Build binary (fallback if artifact unavailable)
       if: steps.download-binary.outcome != 'success'
       shell: bash