diff --git a/CLAUDE.md b/CLAUDE.md
index 3701409..7b80416 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -83,8 +83,9 @@ wc-tier-and-package-prices/
 │   ├── *.pot                       # Translation template
 │   ├── *.po                        # Translation sources
 │   └── *.mo                        # Compiled translations
-├── vendor/                          # Composer dependencies
-│   └── magdev/wc-licensed-product-client/ # License client (git submodule)
+├── lib/                             # Bundled libraries (git submodules)
+│   └── wc-licensed-product-client/  # License client library (v0.2.x)
+├── vendor/                          # Composer dependencies (generated)
 ├── releases/                        # Release packages (not in git)
 └── *.md                            # Documentation files
 
@@ -407,19 +408,22 @@ git checkout dev
 
 ### Git Submodule: wc-licensed-product-client
 
-The `magdev/wc-licensed-product-client` library is bundled as a git submodule to avoid private repository authentication during CI/CD.
+The `magdev/wc-licensed-product-client` library is bundled as a git submodule in `lib/` to avoid private repository authentication during CI/CD and to prevent conflicts with Composer's `vendor/` directory.
 
-**Location:** `vendor/magdev/wc-licensed-product-client/`
+**Location:** `lib/wc-licensed-product-client/`
+
+**Submodule URL:** Relative path `../wc-licensed-product-client.git` (works with Gitea CI/CD)
 
 **Updating the submodule:**
 
 ```bash
-# Update to latest commit
-cd vendor/magdev/wc-licensed-product-client
-git pull origin main
-cd ../../..
-git add vendor/magdev/wc-licensed-product-client
-git commit -m "Update wc-licensed-product-client submodule"
+# Update to a specific tag
+cd lib/wc-licensed-product-client
+git fetch --tags
+git checkout v0.2.3  # or desired version
+cd ../..
+git add lib/wc-licensed-product-client
+git commit -m "Update wc-licensed-product-client to v0.2.3"
 ```
 
 **Composer Configuration:**
@@ -429,16 +433,17 @@ git commit -m "Update wc-licensed-product-client submodule"
   "repositories": [
     {
       "type": "path",
-      "url": "vendor/magdev/wc-licensed-product-client",
-      "options": { "symlink": false }
+      "url": "lib/wc-licensed-product-client"
     }
   ],
   "require": {
-    "magdev/wc-licensed-product-client": "@dev"
+    "magdev/wc-licensed-product-client": "^0.2"
   }
 }
 ```
 
+Composer creates a symlink in `vendor/magdev/wc-licensed-product-client` pointing to `lib/wc-licensed-product-client`.
+
 ### Manual Release (Legacy)
 
 For manual releases without CI/CD, run from the **parent directory**:
@@ -1238,10 +1243,11 @@ The plugin architecture is solid and well-tested. Most bugs arise from:
    - Publishes release to Gitea with changelog notes
 
 2. Added git submodule for license client:
-   - `vendor/magdev/wc-licensed-product-client/` as git submodule
+   - Initially placed in `vendor/magdev/` - **FAILED** (Composer conflicts)
+   - Fixed: Moved to `lib/wc-licensed-product-client/` like wp-fedistream
+   - Uses relative URL `../wc-licensed-product-client.git`
+   - Pinned to v0.2.2 tag
    - Avoids private repository authentication during CI/CD
-   - Updated `.gitignore` to allow submodule path
-   - Updated `composer.json` to use path repository
 
 3. Updated documentation:
    - README.md - Added CI/CD section, updated file structure
@@ -1249,10 +1255,12 @@ The plugin architecture is solid and well-tested. Most bugs arise from:
 
 **Key Learnings:**
 
+- **CRITICAL:** Git submodules should be in `lib/` NOT `vendor/` to avoid Composer conflicts
+- Composer manages `vendor/` directory - don't put submodules there
+- Use relative submodule URL (`../repo.git`) for Gitea CI/CD compatibility
+- Use version constraint `^0.2` instead of `@dev` for stability
 - Git submodules require `submodules: recursive` in checkout action
-- Composer path repository with `symlink: false` works with submodules
-- `.gitignore` patterns: Use `/vendor/*` then `!/vendor/magdev/` to allow specific paths
-- When adding submodules to ignored paths, use `git submodule add -f` to force
+- Composer creates symlink from `vendor/` to `lib/` automatically
 
 **CI/CD Pipeline Notes:**
 
@@ -1260,6 +1268,7 @@ The plugin architecture is solid and well-tested. Most bugs arise from:
 - Required secret: `SRC_GITEA_TOKEN` for Gitea API access
 - Uses `shivammathur/setup-php@v2` for PHP setup
 - Uses `actions/checkout@v4` with `submodules: recursive`
+- Modeled after working wp-fedistream implementation
 
 ---
 
diff --git a/README.md b/README.md
index f511b25..3ded1fa 100644
--- a/README.md
+++ b/README.md
@@ -154,8 +154,9 @@ wc-tier-and-package-prices/
 │   ├── wc-tier-package-prices.pot    # Translation template
 │   ├── wc-tier-package-prices-*.po   # Translation sources
 │   └── wc-tier-package-prices-*.mo   # Compiled translations
-├── vendor/                            # Composer dependencies
-│   └── magdev/wc-licensed-product-client/ # License client (git submodule)
+├── lib/                               # Bundled libraries (git submodules)
+│   └── wc-licensed-product-client/    # License client library
+├── vendor/                            # Composer dependencies (generated)
 ├── CHANGELOG.md                       # Complete version history
 ├── INSTALLATION.md                    # Installation guide
 ├── QUICKSTART.md                      # Quick start guide