docs: add local package resolution section to UX guide

Added critical section on using local common platform packages instead of Gitea registry:

- .pnpmfile.cjs configuration for local package resolution
- .npmrc configuration (remove repo-level GITEA_NPM_TOKEN)
- Environment variables (BYTELYST_PACKAGE_SOURCE)
- Verification commands to confirm local resolution
- Benefits of local package resolution (faster dev, offline, no registry dependency)
- Updated Phase 1 roadmap to include local package setup

This ensures other products follow the same approach of using local common-plat packages by default instead of pulling from Gitea registry.

docs/UX_TESTING_SETUP_GUIDE.md

@@ -22,6 +22,80 @@ This guide documents the complete UX implementation approach for the trading das
 
 ## Part 1: Common Platform UI Integration
 
+### Local Package Resolution
+
+**Critical:** Use local common platform packages by default, not Gitea registry.
+
+**File:** `.pnpmfile.cjs`
+
+```javascript
+// .pnpmfile.cjs
+// Default to local common platform packages
+function readPackage(pkg, context) {
+  if (!context.workspace) return pkg;
+
+  // Default to common-plat (local packages)
+  const packageSource = process.env.BYTELYST_PACKAGE_SOURCE || 'common-plat';
+
+  if (packageSource === 'common-plat') {
+    // Resolve @bytelyst/* packages from local common platform
+    if (pkg.name.startsWith('@bytelyst/')) {
+      pkg.dependencies = pkg.dependencies || {};
+      pkg.dependencies[pkg.name] = 'workspace:*';
+    }
+  }
+
+  return pkg;
+}
+
+module.exports = {
+  name: 'bytelyst-package-source',
+  hooks: {
+    readPackage,
+  },
+};
+```
+
+**File:** `.npmrc`
+
+```ini
+# Remove repo-level GITEA_NPM_TOKEN interpolation
+# Gitea registry auth should live in user-level ~/.npmrc or CI secrets
+# Only when BYTELYST_PACKAGE_SOURCE=gitea is explicitly used
+```
+
+**Commit Reference:** `f2216ad` - chore(pnpm): prefer local bytelyst packages
+
+### Environment Variables
+
+```bash
+# Default: Use local common platform packages
+BYTELYST_PACKAGE_SOURCE=common-plat
+
+# Optional: Use Gitea registry (requires auth)
+BYTELYST_PACKAGE_SOURCE=gitea
+# GITEA_NPM_TOKEN should be in ~/.npmrc or CI secrets
+```
+
+### Verification Commands
+
+```bash
+# Verify local package resolution
+pnpm install @bytelyst/ui @bytelyst/design-tokens
+
+# Verify packages resolve from local common platform
+pnpm list @bytelyst/ui
+# Should show: @bytelyst/ui -> link:../learning_ai_common_plat/packages/ui
+```
+
+### Benefits of Local Package Resolution
+
+1. **Faster Development** - No network calls to registry during development
+2. **Immediate Updates** - Changes to common platform are immediately available
+3. **No Registry Dependency** - Works offline and without Gitea access
+4. **Consistent Builds** - Same packages across all environments
+5. **Simpler CI** - No need for registry auth in CI by default
+
 ### Product Adapter Pattern
 
 Create a product adapter to normalize imports and extend shared primitives with product-specific variants:
@@ -1014,7 +1088,9 @@ const statusColors = {
 ### Phase 1: Foundation Setup
 
 **Week 1-2**
-- [ ] Install common platform packages
+- [ ] Set up local package resolution (.pnpmfile.cjs)
+- [ ] Remove repo-level GITEA_NPM_TOKEN from .npmrc
+- [ ] Install common platform packages from local source
 - [ ] Create product adapter (`Primitives.tsx`)
 - [ ] Set up design token integration
 - [ ] Configure Playwright
@@ -1022,7 +1098,12 @@ const statusColors = {
 
 **Verification:**
 ```bash
+# Verify local package resolution
 pnpm install @bytelyst/ui @bytelyst/design-tokens
+pnpm list @bytelyst/ui
+# Should show: @bytelyst/ui -> link:../learning_ai_common_plat/packages/ui
+
+# Verify build works with local packages
 pnpm run typecheck
 pnpm run build
 ```