refactor(specs): nest client and commerce specifications under specs/openiap

.claude/commands/audit-code.md

@@ -73,7 +73,7 @@ Check each package against internal rules AND latest API capabilities:
 
 - `packages/apple/Sources/` - iOS/macOS Swift code
 - `packages/google/openiap/src/{main,play,horizon,amazon}/` - Android Kotlin code
-- `packages/gql/src/` - GraphQL schema (API definitions)
+- `specs/client/src/` - GraphQL schema (API definitions)
 
 **Rules to check (from knowledge/internal/):**
 
@@ -86,7 +86,7 @@ Check each package against internal rules AND latest API capabilities:
 
 Compare current implementation against latest platform APIs:
 
-**Google Play Billing (check packages/gql/src/api-android.graphql):**
+**Google Play Billing (check specs/client/src/api-android.graphql):**
 
 | Feature                                | Version | Check                                  |
 | -------------------------------------- | ------- | -------------------------------------- |
@@ -101,7 +101,7 @@ Compare current implementation against latest platform APIs:
 | Opt-in price increase in-app messages  | 9.0     | showInAppMessagesAndroid implemented?  |
 | Billing Choice                         | 9.1     | Info, dialog, and choice type wired?   |
 
-**StoreKit 2 (check packages/gql/src/api-ios.graphql):**
+**StoreKit 2 (check specs/client/src/api-ios.graphql):**
 
 | Feature                        | Version                            | Check                                    |
 | ------------------------------ | ---------------------------------- | ---------------------------------------- |
@@ -165,7 +165,7 @@ packages/google (Kotlin):
 - [ ] Play, Horizon, and Amazon flavors compile
 - [ ] Shared code is store-agnostic; Play-only APIs stay in `src/play`
 
-packages/gql (GraphQL):
+specs/client (GraphQL):
 
 - [ ] Async operations have `# Future` comment
 - [ ] Generated types are not manually edited

.claude/commands/audit-iapkit.md

@@ -44,7 +44,7 @@ does not decide the question (product positioning, support claims). Never
 
 ```bash
 # Spec and SDK movement since the kit surface was last reviewed.
-git log --oneline -20 -- packages/gql/src/type.graphql openiap-versions.json
+git log --oneline -20 -- specs/client/src/type.graphql openiap-versions.json
 # Least recently reviewed kit files first — that is where drift concentrates.
 for f in $(git ls-files packages/kit/src/pages/docs/sections packages/kit/src/content); do
   echo "$(git log -1 --format='%ad' --date=short -- "$f")  $f"

.claude/commands/commit.md

@@ -18,13 +18,13 @@ Complete workflow: branch → commit → push → PR
 - `--push` or `-p`: Push to remote after commit
 - `--pr`: Create PR after push
 - `--all` or `-a`: Commit all changes at once
-- `<path>`: Commit only specific path (e.g., `packages/gql`)
+- `<path>`: Commit only specific path (e.g., `specs/client`)
 
 ## Examples
 
 ```bash
 # Full workflow: commit gql spec, push, create PR
-/commit packages/gql/src/*.graphql --pr
+/commit specs/client/src/*.graphql --pr
 
 # Commit all and create PR
 /commit --all --pr
@@ -93,7 +93,7 @@ git checkout -b feat/<feature-name>
 - `flutter` → flutter_inapp_purchase
 - `godot` → godot-iap
 - `kmp` → kmp-iap
-- `gql` → packages/gql
+- `gql` → specs/client
 - `apple` → packages/apple
 - `google` → packages/google
 - `docs` → packages/docs
@@ -110,13 +110,13 @@ git diff --name-only
 **GQL schema only (FIRST COMMIT):**
 
 ```bash
-git add packages/gql/src/*.graphql
+git add specs/client/src/*.graphql
 ```
 
 **Generated types (SECOND COMMIT):**
 
 ```bash
-git add packages/gql/src/generated/
+git add specs/client/src/generated/
 ```
 
 **Specific path:**
@@ -252,7 +252,7 @@ gh pr edit <PR_NUMBER> --add-label "<label1>,<label2>"
 - Changes to `packages/apple/` → `📱 iOS`
 - Changes to `packages/google/` → `🤖 android`
 - Changes to `packages/docs/` → `📖 documentation`
-- Changes to `packages/gql/` → `⬡ gql`
+- Changes to `specs/client/` → `⬡ gql`
 - Changes to `libraries/react-native-iap/` → `react-native-iap`
 - Changes to `libraries/expo-iap/` → `expo-iap`
 - Changes to `libraries/flutter_inapp_purchase/` → `flutter-iap`
@@ -274,8 +274,8 @@ When making cross-package changes, commit in this order:
 
 | Order | Path                          | Description                              |
 | ----- | ----------------------------- | ---------------------------------------- |
-| 1     | `packages/gql/src/*.graphql`  | GraphQL schema ONLY (no generated types) |
-| 2     | `packages/gql/src/generated/` | Generated types (after schema review)    |
+| 1     | `specs/client/src/*.graphql`  | GraphQL schema ONLY (no generated types) |
+| 2     | `specs/client/src/generated/` | Generated types (after schema review)    |
 | 3     | `packages/apple/`             | iOS implementation                       |
 | 4     | `packages/google/`            | Android implementation                   |
 | 5     | `packages/docs/`              | Documentation updates                    |
@@ -286,13 +286,13 @@ When making cross-package changes, commit in this order:
 
 ```bash
 # Stage ONLY .graphql files (not generated/)
-git add packages/gql/src/*.graphql
+git add specs/client/src/*.graphql
 
 # Verify - should only show .graphql files
 git diff --cached --name-only
-# packages/gql/src/type-android.graphql
-# packages/gql/src/type-ios.graphql
-# packages/gql/src/type.graphql
+# specs/client/src/type-android.graphql
+# specs/client/src/type-ios.graphql
+# specs/client/src/type.graphql
 
 # Commit schema changes
 git commit -m "feat(gql): add new types..."
@@ -376,7 +376,7 @@ Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 
 ## Changes
 
-### GraphQL Schema (packages/gql)
+### GraphQL Schema (specs/client)
 
 - `WinBackOfferInputIOS` - Win-back offer input type
 - `ProductStatusAndroid` - Product fetch status enum
@@ -417,9 +417,9 @@ Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 ```bash
 # Full workflow from main
 git checkout -b feat/my-feature
-git add packages/gql/src/*.graphql
+git add specs/client/src/*.graphql
 git commit -m "feat(gql): add new types"
-git add packages/gql/src/generated/
+git add specs/client/src/generated/
 git commit -m "chore(gql): regenerate types"
 git add packages/apple/
 git commit -m "feat(apple): implement new types"

.claude/commands/resolve-issue.md

@@ -63,7 +63,7 @@ gh issue edit $ISSUE_NUMBER --repo hyodotdev/openiap --add-label "<label1>,<labe
 | Mentions `packages/apple` or iOS | `📱 iOS` |
 | Mentions `packages/google` or Android | `🤖 android` |
 | Mentions `packages/docs` | `📖 documentation` |
-| Mentions `packages/gql` | `⬡ gql` |
+| Mentions `specs/client` | `⬡ gql` |
 | Mentions `react-native-iap` | `react-native-iap` |
 | Mentions `expo-iap` | `expo-iap` |
 | Mentions `flutter_inapp_purchase` | `flutter-iap` |
@@ -102,7 +102,7 @@ git checkout -b fix/<library>-<short-description>
 
 | Package | Commands |
 |---------|----------|
-| `packages/gql/` | `cd packages/gql && bun run test` |
+| `specs/client/` | `cd specs/client && bun run test` |
 | `packages/docs/` | `cd packages/docs && bun run lint && bun run typecheck` |
 | `packages/apple/` | `cd packages/apple && swift build` |
 | `packages/google/` | `cd packages/google && ./gradlew :openiap:compilePlayDebugKotlin && ./gradlew :openiap:compileHorizonDebugKotlin && ./gradlew :openiap:compileAmazonDebugKotlin` |

.claude/commands/review-pr.md

@@ -17,13 +17,13 @@ Review and address PR review comments for this repository.
 
 Based on changed files, run these checks BEFORE committing:
 
-| Package            | Commands                                                                                                                                                         |
-| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `scripts/agent/`   | `cd scripts/agent && bun test`                                                                                                                                   |
-| `packages/gql/`    | `cd packages/gql && bun run test`                                                                                                                                |
-| `packages/docs/`   | `cd packages/docs && bun run lint && bun run typecheck`                                                                                                          |
-| `packages/apple/`  | `cd packages/apple && swift build`                                                                                                                               |
-| `packages/google/` | `cd packages/google && ./gradlew :openiap:compilePlayDebugKotlin && ./gradlew :openiap:compileHorizonDebugKotlin && ./gradlew :openiap:compileAmazonDebugKotlin` |
+| Package                 | Commands                                                                                                                                                         |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `scripts/agent/`        | `cd scripts/agent && bun test`                                                                                                                                   |
+| `specs/client/` | `cd specs/client && bun run test`                                                                                                                        |
+| `packages/docs/`        | `cd packages/docs && bun run lint && bun run typecheck`                                                                                                          |
+| `packages/apple/`       | `cd packages/apple && swift build`                                                                                                                               |
+| `packages/google/`      | `cd packages/google && ./gradlew :openiap:compilePlayDebugKotlin && ./gradlew :openiap:compileHorizonDebugKotlin && ./gradlew :openiap:compileAmazonDebugKotlin` |
 
 **Important:** For Android, test Play, Horizon, and Amazon flavors.
 

.claude/commands/verify-all.md

@@ -35,7 +35,7 @@ type sync target, or GQL root operation is not covered by the parity audit.
 set -euo pipefail
 
 # Regenerate the schema SSOT, run codegen tests, and sync every wrapper first.
-(cd packages/gql && bun run generate && bun run test)
+(cd specs/client && bun run generate && bun run test)
 
 # Docs formatting, typecheck, and production bundle
 (cd packages/docs && bun run format:check && bun run build)
@@ -193,12 +193,12 @@ Verify the manifest-owned generated graph and cross-SDK contracts:
 ```bash
 set -euo pipefail
 
-(cd packages/gql && bun run test)
+(cd specs/client && bun run test)
 bun run audit:parity
 ```
 
 The GQL suite derives source/target paths from
-`packages/gql/generated-sync-manifest.mjs`; do not add a hard-coded file loop.
+`specs/client/generated-sync-manifest.mjs`; do not add a hard-coded file loop.
 
 Also verify `COMMON_ERROR_CODE_MAP` in react-native-iap and expo-iap includes all ErrorCode entries:
 
@@ -312,7 +312,7 @@ the complete platform matrix in step 1.
 ```bash
 set -euo pipefail
 
-(cd packages/gql && bun run generate && bun run test)
+(cd specs/client && bun run generate && bun run test)
 (cd packages/docs && bun run format:check && bun run build)
 (cd packages/apple && swift test)
 (cd packages/google && ./gradlew \

.claude/guides/01-overview.md

@@ -9,24 +9,27 @@ openiap/
 ├── packages/
 │   ├── apple/         # iOS/macOS library (Swift, StoreKit 2)
 │   ├── google/        # Android library (Kotlin, Play Billing)
-│   ├── gql/           # GraphQL schema & type generation
 │   ├── docs/          # Documentation site (React/Vite)
 │   └── kit/           # Hosted receipt-validation SaaS (kit.openiap.dev)
+├── specs/
+│   ├── client/             # Client GraphQL contract & type generation
+│   └── commerce-protocol/  # Server-side Commerce Protocol
 ├── scripts/           # Monorepo-wide automation
 ├── .github/workflows/ # CI/CD workflows
 ├── AGENTS.md          # Canonical shared agent guidelines
 └── openiap-versions.json  # Version management
 ```
 
-## Package Responsibilities
+## Directory Responsibilities
 
-| Package  | Purpose                                                   | Language         | Output                        |
-| -------- | --------------------------------------------------------- | ---------------- | ----------------------------- |
-| `apple`  | iOS/macOS IAP implementation                              | Swift            | CocoaPods, SPM                |
-| `google` | Android IAP implementation                                | Kotlin           | Maven Central                 |
-| `gql`    | Type definitions & generation                             | TypeScript       | Swift, Kotlin, Dart, TS types |
-| `docs`   | Documentation website                                     | React/TypeScript | Vercel deployment             |
-| `kit`    | Hosted receipt-validation SaaS (free, MIT, self-hostable) | TypeScript       | Fly.io app (`openiap-kit`)    |
+| Directory                         | Purpose                                                           | Language         | Output                                                           |
+| --------------------------------- | ----------------------------------------------------------------- | ---------------- | ---------------------------------------------------------------- |
+| `packages/apple`                  | iOS/macOS IAP implementation                                      | Swift            | CocoaPods, SPM                                                   |
+| `packages/google`                 | Android IAP implementation                                        | Kotlin           | Maven Central                                                    |
+| `specs/client`            | Client contract and generated types                               | GraphQL          | Swift, Kotlin, Dart, TS types; package name `@hyodotdev/openiap` |
+| `specs/commerce-protocol` | Server-side Commerce Protocol contract, bindings, and conformance | GraphQL          | Package name `openiap-commerce-protocol`                         |
+| `packages/docs`                   | Documentation website                                             | React/TypeScript | Vercel deployment                                                |
+| `packages/kit`                    | Hosted receipt-validation SaaS (free, MIT, self-hostable)         | TypeScript       | Fly.io app (`openiap-kit`)                                       |
 
 ## Version Management
 
@@ -36,7 +39,7 @@ All versions are tracked in `openiap-versions.json`:
 {
   "apple": "1.2.x",
   "google": "1.2.x",
-  "gql": "1.2.x"
+  "spec": "1.2.x"
 }
 ```
 

.claude/guides/04-apple-package.md

@@ -59,7 +59,7 @@ Types.swift is auto-generated from GraphQL schema.
 
 ```bash
 # From the monorepo root: generate all languages and sync manifest targets
-cd packages/gql && bun run generate
+cd specs/client && bun run generate
 ```
 
 ## Version Management

.claude/guides/06-gql-package.md

@@ -1,12 +1,12 @@
-# GQL Package Guide
+# OpenIAP Client Specification Guide
 
-The GraphQL package's canonical instructions live in:
+The client specification's canonical instructions live in:
 
-- `packages/gql/CONVENTION.md` — schema organization, marker/deprecation
+- `specs/client/CONVENTION.md` — schema organization, marker/deprecation
   contracts, supported generation commands, and generated-file rules.
 - `knowledge/internal/04-platform-packages.md` — platform sync and SDK parity.
 - `knowledge/internal/07-docs-consistency.md` — documentation and generated
   API SSOT requirements.
 
 Do not duplicate those rules here. Read all three before changing
-`packages/gql/`, then use the repository-owned `bun run generate` workflow.
+`specs/client/`, then use the repository-owned `bun run generate` workflow.

.claude/guides/08-deployment.md

@@ -22,4 +22,4 @@ This file is a route map, not a second deployment specification.
 
 For the rare IAPKit manual fallback, follow the Convex-first sequence in
 `packages/kit/README.md#deployment-convex--flyio`. IAPKit has its own Convex
-schema and is not part of the `packages/gql` generated-type sync chain.
+schema and is not part of the `specs/client` generated-type sync chain.