specweave 1.0.244 → 1.0.246

package/plugins/specweave/skills/team-orchestrate/SKILL.md

@@ -149,6 +149,43 @@ Agents are NOT all spawned simultaneously. The orchestrator follows a two-phase
 | GraphQL schema | `schema.graphql` | Backend agent | Frontend, Mobile |
 | API route types | `src/api/types/` | Backend agent | Frontend |
 
+### Organization Discovery (CRITICAL — resolve BEFORE spawning agents)
+
+**The orchestrator MUST resolve the actual organization/owner name before spawning ANY agents.**
+All `{ORG}` placeholders below must be replaced with the real value.
+
+**Discovery chain (in order of priority):**
+
+1. **From config** (`repository.organization`):
+```bash
+ORG=$(jq -r '.repository.organization // empty' .specweave/config.json 2>/dev/null)
+```
+
+2. **From sync profiles** (fallback if repository.organization not set):
+```bash
+if [ -z "$ORG" ]; then
+  ORG=$(jq -r '[.sync.profiles[].config.owner // .sync.profiles[].config.organization] | map(select(. != null)) | first // empty' .specweave/config.json 2>/dev/null)
+fi
+```
+
+3. **From umbrella childRepos** (fallback):
+```bash
+if [ -z "$ORG" ]; then
+  ORG=$(jq -r '.umbrella.childRepos[0].path // empty' .specweave/config.json 2>/dev/null | sed 's|repositories/||' | cut -d/ -f1)
+fi
+```
+
+4. **From existing filesystem** (last resort):
+```bash
+if [ -z "$ORG" ]; then
+  ORG=$(ls -d repositories/*/ 2>/dev/null | head -1 | xargs basename 2>/dev/null)
+fi
+```
+
+5. **If all fail**: Ask the user. NEVER guess or use a placeholder.
+
+**NEVER read org from .env files.** Organization belongs in `.specweave/config.json`.
+
 ### Multi-Repo Increment Placement (CRITICAL)
 
 **In umbrella projects with a `repositories/` folder, each agent MUST create its increment in its OWN repo's `.specweave/`:**
@@ -158,11 +195,11 @@ Agents are NOT all spawned simultaneously. The orchestrator follows a two-phase
 umbrella-project/
 ├── .specweave/config.json              # Umbrella config ONLY
 ├── repositories/
-│   ├── {org}/sw-ecom-domain/
+│   ├── {ORG}/sw-ecom-domain/
 │   │   └── .specweave/increments/0001-domain-models/    # Domain agent's increment
-│   ├── {org}/sw-ecom-shared/
+│   ├── {ORG}/sw-ecom-shared/
 │   │   └── .specweave/increments/0001-shared-types/     # Shared agent's increment
-│   └── {org}/sw-ecom-api/
+│   └── {ORG}/sw-ecom-api/
 │       └── .specweave/increments/0001-api-endpoints/    # Backend agent's increment
 
 # WRONG: All agents dumping into umbrella root
@@ -174,6 +211,7 @@ umbrella-project/
 - Run `specweave init` in each repo if `.specweave/` doesn't exist
 - Each agent's working directory is its assigned repo inside `repositories/`
 - Never create `.specweave/increments/` in the umbrella root for multi-repo work
+- Replace `{ORG}` with the actual organization discovered above
 
 ### Phase 1: Upstream Agents (Contracts First)
 
@@ -274,7 +312,7 @@ DESIGN QUALITY:
   - Invoke `sw-frontend:frontend-design` for high-quality UI polish
 
 WORKFLOW:
-  1. Set working directory to your assigned repo: cd repositories/{org}/{repo-name}
+  1. Set working directory to your assigned repo: cd repositories/{ORG}/{repo-name}
   2. If .specweave/ doesn't exist in your repo, run: specweave init
   3. Create YOUR increment in YOUR repo: .specweave/increments/[ID]/
   4. Read the increment spec: .specweave/increments/[ID]/spec.md
@@ -296,7 +334,7 @@ RULES:
   - Follow existing code conventions (check .eslintrc, .prettierrc, tsconfig.json)
   - Run linter and type-check before signaling completion
   - All new components must have corresponding test files
-  - ALL repository operations MUST use `repositories/{org}/` directory structure. NEVER create repos at the project root.
+  - ALL repository operations MUST use `repositories/{ORG}/` directory structure. NEVER create repos at the project root.
   - Create .specweave/increments/ in YOUR assigned repo, NOT in the umbrella project root.
 ```
 
@@ -327,7 +365,7 @@ AUTH SETUP:
   - Ensure auth middleware works end-to-end before signaling completion
 
 WORKFLOW:
-  1. Set working directory to your assigned repo: cd repositories/{org}/{repo-name}
+  1. Set working directory to your assigned repo: cd repositories/{ORG}/{repo-name}
   2. If .specweave/ doesn't exist in your repo, run: specweave init
   3. Create YOUR increment in YOUR repo: .specweave/increments/[ID]/
   4. Read the increment spec: .specweave/increments/[ID]/spec.md
@@ -350,7 +388,7 @@ RULES:
   - Every new API endpoint must have request/response validation
   - Error handling must follow project conventions
   - All services must have unit tests
-  - ALL repository operations MUST use `repositories/{org}/` directory structure. NEVER create repos at the project root.
+  - ALL repository operations MUST use `repositories/{ORG}/` directory structure. NEVER create repos at the project root.
   - Create .specweave/increments/ in YOUR assigned repo, NOT in the umbrella project root.
 ```
 
@@ -373,7 +411,7 @@ FILE OWNERSHIP (WRITE access):
 READ ACCESS: Any file in the repository
 
 WORKFLOW:
-  1. Set working directory to your assigned repo: cd repositories/{org}/{repo-name}
+  1. Set working directory to your assigned repo: cd repositories/{ORG}/{repo-name}
   2. If .specweave/ doesn't exist in your repo, run: specweave init
   3. Create YOUR increment in YOUR repo: .specweave/increments/[ID]/
   4. Read the increment spec: .specweave/increments/[ID]/spec.md
@@ -395,7 +433,7 @@ RULES:
   - Always create migrations (never modify schema without migration)
   - Seed data must be idempotent
   - Schema changes must be backward-compatible when possible
-  - ALL repository operations MUST use `repositories/{org}/` directory structure. NEVER create repos at the project root.
+  - ALL repository operations MUST use `repositories/{ORG}/` directory structure. NEVER create repos at the project root.
   - Create .specweave/increments/ in YOUR assigned repo, NOT in the umbrella project root.
 ```
 
@@ -424,7 +462,7 @@ FILE OWNERSHIP (WRITE access):
 READ ACCESS: Any file in the repository
 
 WORKFLOW:
-  1. Set working directory to your assigned repo: cd repositories/{org}/{repo-name}
+  1. Set working directory to your assigned repo: cd repositories/{ORG}/{repo-name}
   2. If .specweave/ doesn't exist in your repo, run: specweave init
   3. Create YOUR increment in YOUR repo: .specweave/increments/[ID]/
   4. Read the increment spec: .specweave/increments/[ID]/spec.md
@@ -446,7 +484,7 @@ RULES:
   - Tests must cover all acceptance criteria from spec.md
   - Follow existing test patterns and utilities
   - E2E tests must include accessibility checks when applicable
-  - ALL repository operations MUST use `repositories/{org}/` directory structure. NEVER create repos at the project root.
+  - ALL repository operations MUST use `repositories/{ORG}/` directory structure. NEVER create repos at the project root.
   - Create .specweave/increments/ in YOUR assigned repo, NOT in the umbrella project root.
 ```
 
@@ -471,7 +509,7 @@ FILE OWNERSHIP (WRITE access):
 READ ACCESS: Any file in the repository
 
 WORKFLOW:
-  1. Set working directory to your assigned repo: cd repositories/{org}/{repo-name}
+  1. Set working directory to your assigned repo: cd repositories/{ORG}/{repo-name}
   2. If .specweave/ doesn't exist in your repo, run: specweave init
   3. Create YOUR increment in YOUR repo: .specweave/increments/[ID]/
   4. Read the increment spec: .specweave/increments/[ID]/spec.md
@@ -493,7 +531,7 @@ RULES:
   - NEVER commit secrets, credentials, or API keys
   - All user input must be validated and sanitized
   - Follow OWASP Top 10 guidelines
-  - ALL repository operations MUST use `repositories/{org}/` directory structure. NEVER create repos at the project root.
+  - ALL repository operations MUST use `repositories/{ORG}/` directory structure. NEVER create repos at the project root.
   - Create .specweave/increments/ in YOUR assigned repo, NOT in the umbrella project root.
 ```
 
@@ -524,7 +562,7 @@ Each agent has exclusive WRITE access to specific file patterns. This prevents m
 3. **Shared files require coordination** -- if two domains need to modify the same file (e.g., `package.json`), the orchestrator assigns a primary owner and others request changes via messages
 4. **New files** -- agents can create new files ONLY within their ownership patterns
 5. **Conflict detection** -- the orchestrator checks for ownership overlap before spawning and resolves ambiguity upfront
-6. **Repository directory structure** -- for multi-repo setups, ALL repository cloning and creation MUST use the `repositories/{org}/` directory convention. NEVER create repositories at the project root or arbitrary locations.
+6. **Repository directory structure** -- for multi-repo setups, ALL repository cloning and creation MUST use the `repositories/{ORG}/` directory convention. NEVER create repositories at the project root or arbitrary locations.
 
 ---
 

package/plugins/specweave-frontend/commands/component-generate.md

@@ -469,14 +469,16 @@ Before considering a component complete:
 - [ ] TypeScript interface with JSDoc comments
 - [ ] All variants implemented and tested
 - [ ] Unit tests with >80% coverage
-- [ ] Storybook stories for all variants
+- [ ] Storybook stories for all variants with realistic data
 - [ ] README documentation
 - [ ] Accessibility compliance (ARIA, keyboard nav)
 - [ ] Responsive design
-- [ ] Error states handled
-- [ ] Loading states (if applicable)
+- [ ] Error states handled (styled fallbacks, never raw undefined/NaN)
+- [ ] Loading states with skeleton shimmer (if applicable)
 - [ ] Dark mode support (if applicable)
 - [ ] Performance optimized (React.memo, useMemo)
+- [ ] Images use placeholder URLs or AI-generated assets (never "No image" boxes)
+- [ ] Numeric data uses Intl.NumberFormat (prices, dates, percentages)
 
 ## Workflow
 

package/plugins/specweave-frontend/commands/frontend-scaffold.md

@@ -166,7 +166,43 @@ Generate these essential config files:
 9. **API Integration**: Fetch wrapper, error handling, typing
 10. **Performance**: Code splitting, lazy loading, memoization
 
-### 6. Best Practices
+### 6. Demo-Ready Presentation (MANDATORY)
+
+Every scaffolded project MUST be demoable immediately after setup. No broken visuals, no missing data.
+
+**Data Formatting**:
+- ALWAYS use `Intl.NumberFormat` for prices/currencies — NEVER display raw numbers that could show `$NaN`, `$undefined`, or `$null`
+- Create a `formatPrice()` utility in `lib/utils` that handles edge cases:
+```typescript
+export function formatPrice(price: number | null | undefined, currency = 'USD', locale = 'en-US'): string {
+  if (price == null || isNaN(price)) return 'Price unavailable';
+  return new Intl.NumberFormat(locale, { style: 'currency', currency }).format(price / 100);
+}
+```
+- Apply the same defensive pattern to all displayed data — dates, percentages, counts
+
+**Placeholder Images**:
+- NEVER show "No image" text boxes or broken image icons. Use one of these approaches:
+  1. **Unsplash** (free, high-quality): `https://images.unsplash.com/photo-{id}?w=600&h=400&fit=crop`
+  2. **Picsum** (free, random): `https://picsum.photos/seed/{slug}/600/400`
+  3. **AI-generated**: Invoke `/sw-media:image` to generate custom product/hero images
+  4. **SVG placeholders**: Use tasteful gradient SVGs with subtle icons (not gray boxes)
+- For e-commerce: provide 4-6 realistic product image URLs in seed data
+- For dashboards: use chart/graph placeholder components with realistic mock data
+- For landing pages: use hero images that match the brand aesthetic
+
+**Seed Data Requirements**:
+- Include a `lib/mock-data.ts` with realistic, complete seed data
+- Every product must have: name, price (valid number), image URL, description
+- Every user profile must have: name, avatar URL, email
+- Use diverse, realistic names and data (not "Test User 1", "Product A")
+
+**Loading & Error States**:
+- Skeleton loaders with shimmer animation (not spinner-only)
+- Error states must show helpful messages with retry actions
+- Empty states must be visually designed, not just "No items found" text
+
+### 7. Best Practices
 
 - **Component Organization**: Atomic Design pattern
 - **Type Safety**: No `any` types, strict mode
@@ -176,15 +212,16 @@ Generate these essential config files:
 - **Security**: CSP headers, XSS prevention
 - **Code Quality**: Consistent naming, clear structure
 
-### 7. Workflow
+### 8. Workflow
 
 1. Ask about framework choice (React/Next/Vue/Angular)
 2. Confirm styling approach (Tailwind/styled-components/CSS Modules)
 3. Verify state management needs
-4. Generate complete file structure
+4. Generate complete file structure with mock data and placeholder images
 5. Create configuration files
 6. Set up package.json with scripts
-7. Provide setup instructions
+7. Verify all pages render without NaN/undefined/broken images
+8. Provide setup instructions
 
 ## Example Usage
 

package/plugins/specweave-frontend/skills/frontend/SKILL.md

@@ -529,6 +529,34 @@ const useStore = create<Store>((set) => ({
 8. **Error Handling**: Implement Error Boundaries
 9. **Documentation**: Comment complex logic, document APIs
 10. **Security**: Sanitize user input, validate data
+11. **Demo-Ready Output**: Every page must render without visual bugs — no `$NaN`, no "No image" boxes, no raw `undefined`
+
+## Data Display & Formatting (MANDATORY)
+
+Never display raw, unformatted, or potentially-null data to users:
+
+```typescript
+// Prices — ALWAYS use Intl.NumberFormat, NEVER raw template literals
+// BAD:  `$${product.price}` → shows "$NaN" if price is undefined
+// GOOD: formatPrice(product.price)
+export function formatPrice(cents: number | null | undefined, currency = 'USD'): string {
+  if (cents == null || isNaN(cents)) return 'Price unavailable';
+  return new Intl.NumberFormat('en-US', { style: 'currency', currency }).format(cents / 100);
+}
+
+// Dates — ALWAYS use Intl.DateTimeFormat
+export function formatDate(date: string | Date | null | undefined): string {
+  if (!date) return '';
+  const d = new Date(date);
+  if (isNaN(d.getTime())) return '';
+  return new Intl.DateTimeFormat('en-US', { dateStyle: 'medium' }).format(d);
+}
+```
+
+**Images**: Never show "No image" text or broken icons. Use placeholder services:
+- Products: `https://picsum.photos/seed/{slug}/600/400`
+- Avatars: `https://i.pravatar.cc/150?u={id}`
+- Custom: invoke `/sw-media:image` for AI-generated visuals
 
 ## Tools and Libraries
 

package/plugins/specweave-frontend/skills/frontend-architect/SKILL.md

@@ -303,8 +303,11 @@ When making architectural decisions, consider:
 3. Set up build tools and development environment
 4. Configure linting, formatting, and Git hooks
 5. Create base components and layouts
-6. Set up testing infrastructure
-7. Configure deployment pipeline
+6. Include `lib/formatters.ts` with `formatPrice()`, `formatDate()`, `formatNumber()` utilities using `Intl` APIs
+7. Include `lib/mock-data.ts` with realistic seed data (real names, valid prices, placeholder image URLs)
+8. Set up testing infrastructure
+9. Verify all pages render without NaN/undefined/broken images
+10. Configure deployment pipeline
 
 ### Design Component Architecture
 1. Analyze UI requirements and design system

package/plugins/specweave-frontend/skills/frontend-design/SKILL.md

@@ -288,6 +288,28 @@ Tertiary Content  → Subtle, discovered on exploration
 }
 ```
 
+## Visual Media & Placeholder Strategy
+
+When building UIs that display images, products, or media content:
+
+**NEVER leave empty image placeholders.** Every image slot must show something visually appealing.
+
+1. **Product/Hero images**: Invoke `/sw-media:image` to generate custom AI images matching the brand
+2. **Profile avatars**: Use `https://i.pravatar.cc/150?u={unique-id}` for realistic avatars
+3. **Stock photography**: Use `https://picsum.photos/seed/{slug}/{width}/{height}` for contextual photos
+4. **Branded graphics**: Generate with AI or use gradient SVGs with brand colors
+
+**Data Display Rules**:
+- Prices MUST use `Intl.NumberFormat` with currency — showing `$NaN` is a critical visual bug
+- Dates MUST use `Intl.DateTimeFormat` — never show raw ISO strings or "Invalid Date"
+- Empty/null values MUST show styled fallbacks ("Price unavailable", skeleton loaders) — never raw `undefined` or `null`
+- Counts and stats should use compact notation for large numbers
+
+**Empty & Error States**:
+- Empty states need illustrations or icons, a clear message, and a CTA
+- Error states need a visual indicator, human-readable message, and retry action
+- Loading states use skeleton shimmer animations (see Loading States section above)
+
 ## When to Use This Agent
 
 - Creating landing pages

package/plugins/specweave-mobile/skills/expo/SKILL.md

@@ -144,6 +144,128 @@ public:
 };
 ```
 
+## Expo Monorepo Setup
+
+### Monorepo with Expo (Workspaces)
+
+Expo supports monorepos but requires explicit Metro configuration. Metro does NOT resolve workspace packages or follow symlinks by default.
+
+### Step-by-Step Setup
+
+#### 1. Root package.json
+
+```jsonc
+{
+  "private": true,
+  "workspaces": ["apps/*", "packages/*"]
+}
+```
+
+#### 2. Shared Package
+
+```jsonc
+// packages/shared/package.json
+{
+  "name": "@myapp/shared",
+  "main": "src/index.ts",    // Point to SOURCE, not dist — Metro transpiles
+  "types": "src/index.ts"
+}
+```
+
+#### 3. Mobile App Dependencies
+
+```jsonc
+// apps/mobile/package.json
+{
+  "dependencies": {
+    "@myapp/shared": "*"      // workspace:* for pnpm
+  }
+}
+```
+
+#### 4. Metro Config (Critical)
+
+```javascript
+// apps/mobile/metro.config.js
+const { getDefaultConfig } = require('expo/metro-config');
+const path = require('path');
+
+const monorepoRoot = path.resolve(__dirname, '../..');
+const config = getDefaultConfig(__dirname);
+
+// Watch the entire monorepo
+config.watchFolders = [monorepoRoot];
+
+// Resolve node_modules from both app and root (for hoisted deps)
+config.resolver.nodeModulesPaths = [
+  path.resolve(__dirname, 'node_modules'),
+  path.resolve(monorepoRoot, 'node_modules'),
+];
+
+// Prevent duplicate React/RN instances (crashes at runtime)
+config.resolver.extraNodeModules = {
+  'react': path.resolve(__dirname, 'node_modules/react'),
+  'react-native': path.resolve(__dirname, 'node_modules/react-native'),
+  'react-dom': path.resolve(__dirname, 'node_modules/react-dom'),
+};
+
+// Enable symlink resolution (workspace packages are symlinked)
+config.resolver.unstable_enableSymlinks = true;
+
+module.exports = config;
+```
+
+#### 5. TypeScript Path Aliases (Editor Only)
+
+```jsonc
+// apps/mobile/tsconfig.json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@myapp/shared": ["../../packages/shared/src"],
+      "@myapp/shared/*": ["../../packages/shared/src/*"]
+    }
+  }
+}
+```
+
+**Important**: `tsconfig.json` paths only affect the editor and `tsc`. Metro uses its own resolver configured in `metro.config.js`.
+
+### EAS Build with Monorepos
+
+```jsonc
+// apps/mobile/eas.json
+{
+  "build": {
+    "production": {
+      "node": "20.0.0"
+    }
+  }
+}
+```
+
+EAS Build automatically detects monorepo structure. If using pnpm:
+
+```bash
+# Set install command for EAS
+eas secret:create --name EAS_BUILD_INSTALL_COMMAND --value "pnpm install --frozen-lockfile"
+```
+
+For yarn workspaces, EAS uses `yarn install` by default — no extra config needed.
+
+### Troubleshooting Monorepo Issues
+
+| Error | Fix |
+|-------|-----|
+| `Unable to resolve module @myapp/shared` | Add `watchFolders: [monorepoRoot]` to metro.config.js |
+| `Unable to resolve module react` (duplicate) | Set `extraNodeModules.react` to app's copy |
+| Module found by TS but crashes at runtime | Configure Metro resolver (tsconfig paths ≠ Metro) |
+| `ENOENT` errors on workspace packages | Set `resolver.unstable_enableSymlinks: true` |
+| EAS Build fails with missing packages | Verify workspace setup, add `EAS_BUILD_INSTALL_COMMAND` for pnpm |
+
+---
+
 ## EAS Build and EAS Submit
 
 ### EAS Configuration

package/plugins/specweave-mobile/skills/react-native-expert/SKILL.md

@@ -159,7 +159,176 @@ eas --version       # Expo
 
 ---
 
-## Part 3: Common Build Issues
+## Part 3: Monorepo & Metro Configuration
+
+### Monorepo Project Structure
+
+```
+my-monorepo/
+├── package.json              # workspaces: ["apps/*", "packages/*"]
+├── apps/
+│   ├── mobile/               # React Native / Expo app
+│   │   ├── app/              # Expo Router screens
+│   │   ├── metro.config.js   # ← Critical: must configure for monorepo
+│   │   ├── tsconfig.json     # Path aliases (editor only)
+│   │   └── package.json      # depends on @myapp/shared
+│   └── web/                  # Next.js / Vite web app
+├── packages/
+│   ├── shared/               # @myapp/shared — shared types, utils, API client
+│   │   ├── src/
+│   │   └── package.json      # "name": "@myapp/shared"
+│   └── ui/                   # @myapp/ui — shared components
+```
+
+### Metro Configuration for Monorepos
+
+Metro does NOT follow symlinks or resolve workspace packages by default. You must configure it explicitly.
+
+#### Expo Projects (Recommended)
+
+```javascript
+// metro.config.js
+const { getDefaultConfig } = require('expo/metro-config');
+const path = require('path');
+
+// Find the monorepo root (where root package.json with workspaces lives)
+const monorepoRoot = path.resolve(__dirname, '../..');
+
+const config = getDefaultConfig(__dirname);
+
+// 1. Watch all files in the monorepo (so Metro sees shared packages)
+config.watchFolders = [monorepoRoot];
+
+// 2. Tell Metro where to find node_modules (handles hoisted deps)
+config.resolver.nodeModulesPaths = [
+  path.resolve(__dirname, 'node_modules'),       // app-level
+  path.resolve(monorepoRoot, 'node_modules'),     // hoisted root
+];
+
+// 3. Ensure react/react-native resolve from the app (avoid duplicates)
+config.resolver.extraNodeModules = {
+  'react': path.resolve(__dirname, 'node_modules/react'),
+  'react-native': path.resolve(__dirname, 'node_modules/react-native'),
+};
+
+module.exports = config;
+```
+
+#### Bare React Native Projects
+
+```javascript
+// metro.config.js
+const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
+const path = require('path');
+
+const monorepoRoot = path.resolve(__dirname, '../..');
+
+const config = {
+  watchFolders: [monorepoRoot],
+  resolver: {
+    nodeModulesPaths: [
+      path.resolve(__dirname, 'node_modules'),
+      path.resolve(monorepoRoot, 'node_modules'),
+    ],
+    // Prevent duplicate React instances
+    extraNodeModules: {
+      'react': path.resolve(__dirname, 'node_modules/react'),
+      'react-native': path.resolve(__dirname, 'node_modules/react-native'),
+    },
+    // Handle symlinks (yarn/pnpm workspaces create symlinks)
+    unstable_enableSymlinks: true,
+  },
+};
+
+module.exports = mergeConfig(getDefaultConfig(__dirname), config);
+```
+
+### TypeScript Path Aliases vs Metro Resolver
+
+**TypeScript `paths`** only affect the editor and type checker — Metro ignores them entirely. You need BOTH:
+
+```jsonc
+// tsconfig.json — for editor intellisense and tsc
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@myapp/shared": ["../../packages/shared/src"],
+      "@myapp/shared/*": ["../../packages/shared/src/*"],
+      "@/*": ["./src/*"]
+    }
+  }
+}
+```
+
+```javascript
+// metro.config.js — for actual runtime bundling
+config.resolver.extraNodeModules = {
+  '@myapp/shared': path.resolve(monorepoRoot, 'packages/shared/src'),
+};
+// OR use a custom resolver:
+config.resolver.resolveRequest = (context, moduleName, platform) => {
+  if (moduleName.startsWith('@myapp/shared')) {
+    const subPath = moduleName.replace('@myapp/shared', '');
+    return context.resolveRequest(
+      context,
+      path.resolve(monorepoRoot, 'packages/shared/src') + subPath,
+      platform
+    );
+  }
+  return context.resolveRequest(context, moduleName, platform);
+};
+```
+
+### Package Manager Workspace Setup
+
+```jsonc
+// Root package.json (yarn/npm workspaces)
+{
+  "private": true,
+  "workspaces": ["apps/*", "packages/*"]
+}
+
+// pnpm-workspace.yaml (pnpm)
+// packages:
+//   - "apps/*"
+//   - "packages/*"
+```
+
+```jsonc
+// packages/shared/package.json
+{
+  "name": "@myapp/shared",
+  "main": "src/index.ts",      // Point to source for Metro (not dist)
+  "types": "src/index.ts"
+}
+```
+
+```jsonc
+// apps/mobile/package.json
+{
+  "dependencies": {
+    "@myapp/shared": "*"        // workspace:* for pnpm
+  }
+}
+```
+
+**Important**: For Metro bundling, point shared package `main` to **source** (`src/index.ts`), not compiled output. Metro transpiles everything itself.
+
+### Common Monorepo Pitfalls
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| `Unable to resolve module @myapp/shared` | Metro can't see workspace package | Add `watchFolders` pointing to monorepo root |
+| `Unable to resolve module react` (duplicate) | Multiple React copies in node_modules | Pin via `extraNodeModules` to app's copy |
+| Module works in web but not mobile | Webpack resolves workspaces; Metro doesn't | Configure `metro.config.js` resolver |
+| Types resolve but runtime fails | tsconfig `paths` ≠ Metro resolver | Configure both tsconfig AND metro.config.js |
+| `ENOENT` on symlinked packages | Metro doesn't follow symlinks by default | Set `unstable_enableSymlinks: true` |
+| Hoisted deps not found | Dependencies hoisted to root node_modules | Add root `node_modules` to `nodeModulesPaths` |
+
+---
+
+## Part 3b: Common Build Issues
 
 ### Metro Cache Issues
 
@@ -185,6 +354,37 @@ cd ios && rm -rf build Pods Podfile.lock && pod install && cd ..
 cd android && ./gradlew clean && cd ..
 ```
 
+### Metro Resolution Errors
+
+**"Unable to resolve module X"** — Systematic debugging:
+
+```bash
+# 1. Verify the package exists and is installed
+ls node_modules/@myapp/shared 2>/dev/null || echo "NOT in app node_modules"
+ls ../../node_modules/@myapp/shared 2>/dev/null || echo "NOT in root node_modules"
+
+# 2. Check if it's a symlink (workspaces create these)
+ls -la node_modules/@myapp/ 2>/dev/null
+
+# 3. Verify metro.config.js has watchFolders and nodeModulesPaths
+cat metro.config.js
+
+# 4. Check the shared package's main/module entry point
+cat ../../packages/shared/package.json | grep -E '"main"|"module"|"exports"'
+
+# 5. Clear cache and restart
+watchman watch-del-all && npx expo start --clear
+```
+
+**"Unable to resolve module X from Y: X could not be found within the project or in these directories: node_modules"**
+
+This error means Metro's resolver checked its configured paths and found nothing. Checklist:
+1. Is `watchFolders` set to include the directory containing the package?
+2. Is `nodeModulesPaths` set to include all relevant `node_modules` directories?
+3. Does the package's `package.json` have a valid `main` field pointing to an existing file?
+4. If using pnpm, is `unstable_enableSymlinks: true` set in the resolver?
+5. After config changes, always run `npx expo start --clear` (Metro caches aggressively)
+
 ---
 
 ## Part 4: New Architecture (Fabric, Turbo Modules, JSI)