hyodotdev · hyochan · Aug 19, 2026 · Aug 18, 2026 · Aug 18, 2026 · Aug 18, 2026
diff --git a/.claude/commands/compile-knowledge.md b/.claude/commands/compile-knowledge.md
@@ -1,23 +1,23 @@
 ---
 name: compile-knowledge
-description: Compile the OpenIAP knowledge base into the context files AI assistants load. Use after editing anything under knowledge/, or when the user asks to compile, recompile, or refresh the knowledge base or agent context.
+description: Compile the OpenIAP knowledge base into the shared reference and public AI files. Use after editing anything under knowledge/, or when the user asks to compile, recompile, or refresh the knowledge base or agent context.
 ---
 
 # Compile Knowledge Base
 
-Compile the OpenIAP knowledge base to generate context files for AI assistants.
+Compile the OpenIAP knowledge base into a shared reference and public AI files.
 
 > **Full documentation:** See `scripts/agent/README.md` for detailed setup and troubleshooting.
 
 ## Quick Reference
 
 ### Output Files
 
-| Output          | Location                     | Purpose                      |
-| --------------- | ---------------------------- | ---------------------------- |
-| `context.md`    | `knowledge/_claude-context/` | Claude Code context          |
-| `llms.txt`      | `packages/docs/public/`      | AI assistant quick reference |
-| `llms-full.txt` | `packages/docs/public/`      | AI assistant full reference  |
+| Output          | Location                    | Purpose                      |
+| --------------- | --------------------------- | ---------------------------- |
+| `context.md`    | `knowledge/_agent-context/` | Generated shared reference   |
+| `llms.txt`      | `packages/docs/public/`     | AI assistant quick reference |
+| `llms-full.txt` | `packages/docs/public/`     | AI assistant full reference  |
 
 ### Commands
 
@@ -73,16 +73,16 @@ bun run compile:ai
 ### 2. Verify Output
 
 ```bash
-ls -la ../../knowledge/_claude-context/
+ls -la ../../knowledge/_agent-context/
 ls -la ../../packages/docs/public/llms*.txt
 ```
 
 ### 3. Review Generated Changes
 
 ```bash
-git add knowledge/_claude-context/context.md
-git add packages/docs/public/llms.txt
-git add packages/docs/public/llms-full.txt
+git -C ../.. add knowledge/_agent-context/context.md knowledge/_claude-context
+git -C ../.. add packages/docs/public/llms.txt
+git -C ../.. add packages/docs/public/llms-full.txt
 ```
 
 Commit or push generated context only when the user requested publication or it
@@ -94,7 +94,7 @@ context changes local and report them.
 ```text
 knowledge/
 ├── internal/     ─┐
-└── external/     ─┴─► compile:ai ─┬► context.md (Claude Code)
+└── external/     ─┴─► compile:ai ─┬► context.md (shared reference)
                                    ├► llms.txt (Quick Ref)
                                    └► llms-full.txt (Full Ref)
 ```
diff --git a/.claude/commands/release.md b/.claude/commands/release.md
@@ -51,7 +51,7 @@ Every release lane's version-bump commit also runs
 `scripts/sync-release-generated.sh`, which regenerates and stages the files
 derived from version metadata (`packages/docs/src/generated/version-metadata.json`,
 `packages/docs/public/llms.txt`, `packages/docs/public/llms-full.txt`,
-`knowledge/_claude-context/context.md`). Expect these paths in bump commits;
+`knowledge/_agent-context/context.md`). Expect these paths in bump commits;
 they are not worktree drift. Skipping this regeneration leaves `main` stale and
 fails the `Audit SDK Parity` / `Test Agent Scripts` clean-worktree checks on
 every subsequent PR.
@@ -131,9 +131,9 @@ For a multi-package release train, use this order when affected:
    version, so it does not participate in the `spec = min(google, apple)`
    invariant.
 10. `npm run deploy`; run `release.yml` with `version=current` only when the
-   native-derived `spec` advanced. If a Docs GitHub Release is requested while
-   `spec` is unchanged, stop and explain that the immutable `docs-{spec}` tag
-   cannot represent a new release.
+    native-derived `spec` advanced. If a Docs GitHub Release is requested while
+    `spec` is unchanged, stop and explain that the immutable `docs-{spec}` tag
+    cannot represent a new release.
 
 Train rules (mistake guards):
 

diff --git a/.claude/commands/review-pr.md b/.claude/commands/review-pr.md
@@ -37,7 +37,7 @@ When reviewing, check these project-specific rules:
 - **Android functions in packages/google**: NO `Android` suffix (it's Android-only)
 - **Generated files**: Do NOT edit `packages/apple/Sources/Models/Types.swift` or `packages/google/openiap/src/main/java/dev/hyo/openiap/Types.kt`
 
-See [CLAUDE.md](../../CLAUDE.md) and [knowledge/internal/](../../knowledge/internal/) for full conventions.
+See [AGENTS.md](../../AGENTS.md) and [knowledge/internal/](../../knowledge/internal/) for full conventions.
 
 ## Public GitHub Language Guard
 

diff --git a/.claude/commands/verify-all.md b/.claude/commands/verify-all.md
@@ -295,8 +295,8 @@ ruby -e 'require "yaml"; Dir[".github/workflows/*.yml"].each { |f| YAML.safe_loa
 
 ### 8. Agent instructions
 
-- Root AGENTS.md lists all framework library CLAUDE.md files
-- Root CLAUDE.md and GEMINI.md are symlinks to AGENTS.md
+- Root AGENTS.md lists all framework library AGENTS.md files
+- Root and framework-library CLAUDE.md/GEMINI.md files are symlinks to AGENTS.md
 - `knowledge/internal/02-architecture.md` includes `libraries/` in structure
 - Auto-generated files list includes library types
 

diff --git a/.claude/guides/01-overview.md b/.claude/guides/01-overview.md
@@ -14,7 +14,7 @@ openiap/
 │   └── kit/           # Hosted receipt-validation SaaS (kit.openiap.dev)
 ├── scripts/           # Monorepo-wide automation
 ├── .github/workflows/ # CI/CD workflows
-├── CLAUDE.md          # Main agent guidelines
+├── AGENTS.md          # Canonical shared agent guidelines
 └── openiap-versions.json  # Version management
 ```
 

diff --git a/.claude/guides/03-deprecations.md b/.claude/guides/03-deprecations.md
@@ -68,4 +68,4 @@ When deprecating APIs:
    ```
 
 4. **Update documentation** - Add migration guide in `docs/updates/releases.tsx`
-5. **Update CLAUDE.md** - Add to deprecated functions list
+5. **Update AGENTS.md** - Add to deprecated functions list
diff --git a/.claude/skills/openiap-workflows/SKILL.md b/.claude/skills/openiap-workflows/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: openiap-workflows
-description: Use for OpenIAP monorepo work that should follow the repository's slash-command workflows when the user asks in natural language instead of typing a slash command, including review-pr, audit-code, compile-knowledge, verify-all, e2e-tests, stable or prerelease package releases, resolve-issue, commit/push/PR, generated type sync, package-specific checks, GitHub review threads, and project conventions from AGENTS.md/CLAUDE.md/GEMINI.md.
+description: Use for OpenIAP monorepo work that should follow the repository's slash-command workflows when the user asks in natural language instead of typing a slash command, including review-pr, audit-code, compile-knowledge, verify-all, e2e-tests, stable or prerelease package releases, resolve-issue, commit/push/PR, generated type sync, package-specific checks, GitHub review threads, and project conventions from AGENTS.md.
 ---
 
 # OpenIAP Workflows (Claude Code)

diff --git a/.codex/skills/iapkit-e2e-martie/SKILL.md b/.codex/skills/iapkit-e2e-martie/SKILL.md
@@ -85,7 +85,7 @@ satisfied.
 ## Preflight
 
 1. Read `$OPENIAP_REPO/AGENTS.md`, `packages/kit/CONVENTION.md`, the selected
-   framework's `CLAUDE.md`, and the `Local (IAPKit) Receipt Vertical` section of
+   framework's `AGENTS.md`, and the `Local (IAPKit) Receipt Vertical` section of
    `.claude/commands/e2e-tests.md`.
 2. Run `git status --short --branch` and preserve all existing changes.
 3. Confirm port `3100` is free and identify the device:

diff --git a/.codex/skills/openiap-workflows/SKILL.md b/.codex/skills/openiap-workflows/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: openiap-workflows
-description: Use for OpenIAP monorepo work that should follow the repository's Claude slash-command workflows, including review-pr, audit-code, compile-knowledge, verify-all, e2e-tests, stable or prerelease package releases, resolve-issue, commit/push/PR, generated type sync, package-specific checks, GitHub review threads, and project conventions from AGENTS.md/CLAUDE.md/GEMINI.md.
+description: Use for OpenIAP monorepo work that should follow the repository's shared agent workflows, including review-pr, audit-code, compile-knowledge, verify-all, e2e-tests, stable or prerelease package releases, resolve-issue, commit/push/PR, generated type sync, package-specific checks, GitHub review threads, and project conventions from AGENTS.md.
 ---
 
 # OpenIAP Workflows
@@ -13,11 +13,12 @@ verifying the monorepo, or committing and opening a PR.
 ## Source Of Truth
 
 Before changing code, read the root `AGENTS.md`; `CLAUDE.md` and `GEMINI.md`
-are symlinks to it in this repo. Then read the relevant detailed files:
+are symlinks to it in this repo, while Grok and Codex consume `AGENTS.md`
+directly. Then read the relevant detailed files:
 
 - Package and library rules: `knowledge/internal/*.md`
 - Package conventions: `packages/*/CONVENTION.md`
-- Library conventions: `libraries/*/CLAUDE.md`
+- Library conventions: `libraries/*/AGENTS.md`
 - Workflow details: `.claude/commands/*.md`
 
 Do not duplicate or reinterpret those rules when a file already covers the

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -31,6 +31,9 @@ jobs:
         with:
           node-version: 20
 
+      - name: Audit repository layout
+        run: npm run audit:layout
+
       - name: Reject prerelease metadata on main
         run: node scripts/release-branch-policy.mjs audit
 

diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
@@ -424,6 +424,8 @@ jobs:
       - name: Build Flutter Swift wrappers
         if: matrix.component == 'flutter'
         working-directory: libraries/flutter_inapp_purchase
+        env:
+          EXPECTED_XCODE_MAJOR: ${{ github.event_name == 'pull_request' && '26' || '27' }}
         run: bash scripts/verify-apple-swiftpm-consumer-build.sh
 
       - name: Build Godot Swift wrapper

diff --git a/.github/workflows/deploy-kit.yml b/.github/workflows/deploy-kit.yml
@@ -175,6 +175,7 @@ jobs:
           "$RUNNER_TEMP/trivy" image openiap-kit:security-scan
           --scanners vuln
           --severity HIGH,CRITICAL
+          --ignorefile packages/kit/.trivyignore.yaml
           --exit-code 1
           --exit-on-eol 1
 

diff --git a/.github/workflows/security-rescan.yml b/.github/workflows/security-rescan.yml
@@ -149,6 +149,7 @@ jobs:
           "$RUNNER_TEMP/trivy" image openiap-kit:security-scan
           --scanners vuln
           --severity HIGH,CRITICAL
+          --ignorefile packages/kit/.trivyignore.yaml
           --exit-code 1
           --exit-on-eol 1
           --format json

diff --git a/.husky/pre-commit b/.husky/pre-commit
@@ -52,6 +52,10 @@ fi
 echo "🔎 SDK parity audit — running CI mirror…"
 node scripts/audit-non-godot-parity.mjs
 
+# Canonical project directories must not be duplicated at repository root.
+echo "🧭 repository layout audit…"
+bun run audit:layout
+
 # Unconditional: either side of the kit/spec contract can move.
 echo "🔎 IAPKit spec contract audit — running CI mirror…"
 node --test scripts/audit-kit-spec-contract.test.mjs

diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -1,11 +1,16 @@
 {
   "cSpell.words": [
+    "apollographql",
+    "codegen",
+    "gradlew",
     "hyodotdev",
     "Iapkit",
+    "JsonSlurper",
     "openiap",
+    "preorder",
+    "pubspec",
     "Skus",
-    "Slurper",
-    "JsonSlurper"
+    "Slurper"
   ],
   "files.associations": {
     "*.podspec": "ruby"
@@ -47,4 +52,4 @@
   "java.configuration.updateBuildConfiguration": "automatic",
   "gradle.nestedProjects": false,
   "eslint.workingDirectories": [{ "mode": "auto" }]
-}
+}
diff --git a/AGENTS.md b/AGENTS.md
@@ -21,11 +21,12 @@ This document provides an overview for AI agents working across the OpenIAP mono
 ```text
 openiap/
 ├── packages/
+│   ├── conformance/   # Behavioral conformance spec, runner, and reports
 │   ├── docs/          # Documentation site (React/Vite/Vercel)
 │   ├── gql/           # GraphQL schema & type generation
 │   ├── google/        # Android library
 │   ├── apple/         # iOS/macOS library
-│   ├── kit/           # Hosted receipt-validation SaaS (Fly.io app)
+│   ├── kit/           # Purchase validation + entitlement infrastructure (Fly.io app)
 │   └── mcp-server/    # IAPKit MCP server (hosted at kit.openiap.dev/mcp)
 ├── plugins/
 │   └── openiap/       # Codex + Claude Code plugin (skills + MCP config)
@@ -39,7 +40,8 @@ openiap/
 ├── knowledge/         # Shared knowledge base (SSOT)
 │   ├── internal/      # Project philosophy (HIGHEST PRIORITY)
 │   ├── external/      # External API reference
-│   └── _claude-context/  # Compiled context for Claude Code
+│   ├── _agent-context/   # Compiled context shared by AI assistants
+│   └── _claude-context/  # Compatibility link to _agent-context
 ├── scripts/           # Monorepo-wide automation
 └── .github/workflows/ # CI/CD workflows
 ```
@@ -56,13 +58,13 @@ openiap/
    - [`packages/apple/CONVENTION.md`](packages/apple/CONVENTION.md)
    - [`packages/docs/CONVENTION.md`](packages/docs/CONVENTION.md)
    - [`packages/kit/CONVENTION.md`](packages/kit/CONVENTION.md) — kit is a deployable SaaS (not a library); has its own Convex schema and isn't part of the GQL type-sync chain. Its `/v1` responses are still a published contract that shipped SDKs decode: read the `/v1` response contract section and run `bun audit:kit-contract` before changing a response enum, `isValidState`, or a purchase-state mapping
-3. **For framework libraries, read the library-specific CLAUDE.md**:
-   - [`libraries/react-native-iap/CLAUDE.md`](libraries/react-native-iap/CLAUDE.md) — Yarn 3, Nitro Modules, useIAP hook semantics, error handling
-   - [`libraries/expo-iap/CLAUDE.md`](libraries/expo-iap/CLAUDE.md) — Bun, Expo Modules, iOS podspec 13.4 workaround, tvOS 16.0 requirement
-   - [`libraries/flutter_inapp_purchase/CLAUDE.md`](libraries/flutter_inapp_purchase/CLAUDE.md) — Flutter/Dart, generated types.dart, fetchProducts generic API
-   - [`libraries/godot-iap/CLAUDE.md`](libraries/godot-iap/CLAUDE.md) — GDScript conventions, GDExtension (iOS), AAR plugin (Android)
-   - [`libraries/kmp-iap/CLAUDE.md`](libraries/kmp-iap/CLAUDE.md) — Kotlin Multiplatform, Flow-based API, CocoaPods iOS integration
-   - [`libraries/maui-iap/CLAUDE.md`](libraries/maui-iap/CLAUDE.md) — .NET MAUI / C# 12, generated Types.cs, Android/iOS bindings
+3. **For framework libraries, read the library-specific AGENTS.md**:
+   - [`libraries/react-native-iap/AGENTS.md`](libraries/react-native-iap/AGENTS.md) — Yarn 3, Nitro Modules, useIAP hook semantics, error handling
+   - [`libraries/expo-iap/AGENTS.md`](libraries/expo-iap/AGENTS.md) — Bun, Expo Modules, iOS podspec 13.4 workaround, tvOS 16.0 requirement
+   - [`libraries/flutter_inapp_purchase/AGENTS.md`](libraries/flutter_inapp_purchase/AGENTS.md) — Flutter/Dart, generated types.dart, fetchProducts generic API
+   - [`libraries/godot-iap/AGENTS.md`](libraries/godot-iap/AGENTS.md) — GDScript conventions, GDExtension (iOS), AAR plugin (Android)
+   - [`libraries/kmp-iap/AGENTS.md`](libraries/kmp-iap/AGENTS.md) — Kotlin Multiplatform, Flow-based API, CocoaPods iOS integration
+   - [`libraries/maui-iap/AGENTS.md`](libraries/maui-iap/AGENTS.md) — .NET MAUI / C# 12, generated Types.cs, Android/iOS bindings
 
 ## Key Rules Summary
 
@@ -79,6 +81,13 @@ KISS and SSOT are mandatory release criteria. The canonical rules live in
 [`knowledge/internal/03-coding-style.md`](knowledge/internal/03-coding-style.md#0-kiss-and-ssot-are-release-requirements).
 Apply that section before implementation and during every review.
 
+### Repository Layout
+
+Treat the directory ownership rules in
+[`knowledge/internal/02-architecture.md`](knowledge/internal/02-architecture.md#directory-ownership-guardrail)
+as mandatory. Extend the existing owner instead of creating a parallel root
+directory, and run `bun run audit:layout` after adding or moving directories.
+
 ### Comment Style
 
 Keep comments short — default to one line. AI-authored comments over-explain by
@@ -188,27 +197,36 @@ GraphQL Schema ─┬─► graphql-codegen + AST guards ─► TypeScript
   `main` using the bump type relative to its stable metadata.
 - Read `.claude/commands/release.md` before any package deployment.
 
-## Using Claude Code with Context
+## Shared Agent Context
 
 ```bash
 cd scripts/agent
 
-# Compile for AI assistants (no Ollama required)
+# Compile shared context for AI assistants (no Ollama required)
 bun run compile:ai
 
-# Or compile for both Claude Code + Local RAG
+# Or compile for both AI assistants + Local RAG
 bun run compile
-
-# Use with Claude Code
-claude --context knowledge/_claude-context/context.md
 ```
 
-## Codex Compatibility
+## Shared Agent Configuration
+
+`AGENTS.md` is the root project instruction SSOT. Codex and Grok read it
+directly; `CLAUDE.md` and `GEMINI.md` are compatibility symlinks to the same
+file. Every framework library follows the same pattern with a local canonical
+`AGENTS.md`. The `.claude/commands/`, `.claude/skills/`, `.codex/skills/`, and
+`.cursor/rules/` files remain thin tool-discovery adapters where their host
+formats genuinely differ; they must route back to the shared instructions and
+workflow sources instead of copying project policy.
 
-`AGENTS.md` is the root project instruction SSOT. `CLAUDE.md` and `GEMINI.md`
-are symlinks to `AGENTS.md`, so Claude Code, Gemini, and Codex read the same
-root instructions. The `.claude/commands/` files remain the workflow SSOT for
-slash-command-style tasks.
+The canonical compiled reference is
+`knowledge/_agent-context/context.md`. It supports audits, local RAG, and
+on-demand reading; assistant project rules are discovered through the root
+instruction files above. The legacy `knowledge/_claude-context` path is a
+compatibility symlink, so existing paths continue to work without creating a
+second generated copy.
+
+## Codex Compatibility
 
 Codex supports Skills through `SKILL.md` folders. This repo provides
 Codex-compatible local skills in `.codex/skills/`, including
@@ -231,6 +249,13 @@ Keep `$review-self` and `$loop-review` repo-local. Their review, merge, and
 release-safety policies are project-specific; globally linking them could apply
 the wrong repository workflow elsewhere.
 
+## Grok Compatibility
+
+Grok Build reads the repository's `AGENTS.md` hierarchy directly and supports
+the Claude Code command, skill, plugin, and marketplace layout. Do not add a
+parallel `GROK.md`; keep shared rules in `AGENTS.md` and tool-specific adapters
+thin. See the [xAI skills and plugins documentation](https://docs.x.ai/build/features/skills-plugins-marketplaces).
+
 ## Claude Code Compatibility
 
 Claude Code gets the same workflow surface without any install step:
@@ -278,7 +303,7 @@ Cursor-specific files.
 | `/review-pr`         | Review PR comments, fix issues, resolve threads    | `/review-pr 65` or `/review-pr <url>` |
 | `/audit-code`        | Audit code against knowledge rules and latest APIs | `/audit-code`                         |
 | `/audit-security`    | Audit SBOM, provenance, and supply-chain posture   | `/audit-security`                     |
-| `/compile-knowledge` | Compile knowledge base for Claude context          | `/compile-knowledge`                  |
+| `/compile-knowledge` | Compile the shared AI agent context                | `/compile-knowledge`                  |
 | `/resolve-issue`     | Analyze an issue, label it, and fix/comment        | `/resolve-issue 88`                   |
 | `/verify-all`        | Run the full monorepo health check                 | `/verify-all`                         |
 | `/e2e-tests`         | Run device-backed OpenIAP regression tests         | `/e2e-tests PR 162`                   |