fix: include Tailwind CSS utilities in distribution build

.devcontainer/README.md

@@ -136,13 +136,49 @@ pwshow      # playwright show-report
 
 ## 🌐 Port Forwarding
 
-The following ports are automatically forwarded from the container to your host machine:
+This devcontainer is optimized to minimize port forwarding and only open ports on-demand when services are actually running:
 
-- **3000**: Storybook development server
-- **5173**: Vite development server (Showcase app)
-- **4173**: Vite preview server
-- **8080**: API server
-- **9323**: Playwright UI mode
+### 🚀 **On-Demand Port Forwarding**
+
+- **No ports are forwarded by default** - this prevents blocking ports on your local machine
+- Ports are automatically detected and forwarded only when services start
+- Ports are automatically closed when services stop
+
+### 🔧 **Automatic Detection**
+
+When you start development services, VS Code will automatically:
+
+| Service                  | Port | Behavior                    |
+| ------------------------ | ---- | --------------------------- |
+| **Vite Dev Server**      | 5173 | Auto-forward & open browser |
+| **Storybook (UI Kit)**   | 6006 | Auto-forward & open browser |
+| **Storybook (Showcase)** | 3000 | Auto-forward & open browser |
+| **Vite Preview**         | 4173 | Auto-forward & open browser |
+| **Playwright UI**        | 9323 | Auto-forward & open browser |
+| **API Server**           | 8080 | Auto-forward & notify only  |
+
+### 💡 **Usage Examples**
+
+```bash
+# Start Storybook - port 6006 will be auto-forwarded
+pnpm --filter @etherisc/ui-kit run storybook
+
+# Start showcase app - port 5173 will be auto-forwarded
+pnpm --filter @org/showcase run dev
+
+# Start Playwright UI - port 9323 will be auto-forwarded
+pnpm --filter @org/showcase run test:e2e --ui
+```
+
+### 🔍 **Manual Port Management**
+
+If you need to manually forward additional ports:
+
+1. Open VS Code Command Palette (`Ctrl+Shift+P`)
+2. Run "Ports: Focus on Ports View"
+3. Click "Forward a Port" to add any custom port
+
+This optimized setup prevents the common issue of having 20+ ports forwarded unnecessarily while still providing seamless development experience.
 
 ## 💾 Persistent Storage
 

.devcontainer/devcontainer.json

@@ -73,19 +73,50 @@
         "typescript.suggest.autoImports": true,
         "npm.packageManager": "pnpm",
         "playwright.reuseBrowser": true,
-        "playwright.showTrace": true
+        "playwright.showTrace": true,
+        // Disable automatic port forwarding to prevent excessive port exposure
+        "remote.autoForwardPorts": false
       }
     }
   },
 
-  // Use 'forwardPorts' to make a list of ports inside the container available locally
-  "forwardPorts": [
-    3000, // Storybook
-    5173, // Vite dev server
-    4173, // Vite preview
-    8080, // API server
-    9323 // Playwright UI mode
-  ],
+  // Forward commonly used development ports
+  "forwardPorts": [3000, 5173, 6006],
+
+  // Configure port attributes for on-demand forwarding with random port assignment
+  "portsAttributes": {
+    "*": {
+      "onAutoForward": "ignore"
+    },
+    "3000": {
+      "label": "Additional Dev Server",
+      "onAutoForward": "openBrowser"
+    },
+    "4173": {
+      "label": "Vite Preview",
+      "onAutoForward": "openBrowser"
+    },
+    "5173": {
+      "label": "Showcase App (Vite)",
+      "onAutoForward": "openBrowser"
+    },
+    "5174": {
+      "label": "Vite Dev Server (Alt)",
+      "onAutoForward": "openBrowser"
+    },
+    "6006": {
+      "label": "Storybook (UI Kit)",
+      "onAutoForward": "openBrowser"
+    },
+    "8080": {
+      "label": "API Server",
+      "onAutoForward": "notify"
+    },
+    "9323": {
+      "label": "Playwright UI",
+      "onAutoForward": "openBrowser"
+    }
+  },
 
   // Use 'postCreateCommand' to run commands after the container is created
   "postCreateCommand": ".devcontainer/scripts/post-create.sh",

.devcontainer/scripts/gh-auth.sh

@@ -0,0 +1,89 @@
+#!/bin/bash
+
+# GitHub CLI authentication script
+# This script directly reads .devcontainer/.env to avoid dependency on shell exports
+
+echo "🔐 GitHub CLI Authentication"
+echo "=============================="
+
+# Function to load environment variables from .env file
+load_env_file() {
+    local env_file=".devcontainer/.env"
+    if [ -f "$env_file" ]; then
+        echo "📄 Loading environment variables from $env_file"
+        # Use a subshell to avoid polluting the current environment permanently
+        while IFS='=' read -r key value; do
+            # Skip empty lines and comments
+            [[ -z "$key" || "$key" =~ ^#.*$ ]] && continue
+            # Remove quotes if present
+            value="${value%\"}"
+            value="${value#\"}"
+            value="${value%\'}"
+            value="${value#\'}"
+            # Export the variable
+            export "$key=$value"
+        done < "$env_file"
+        return 0
+    else
+        echo "ℹ️  No .env file found at $env_file"
+        return 1
+    fi
+}
+
+# Load environment variables from .env file
+load_env_file
+
+# Debug: Check if GH_TOKEN is available (without showing the full token)
+if [ -n "$GH_TOKEN" ]; then
+    echo "🔍 GH_TOKEN found (${#GH_TOKEN} characters)"
+else
+    echo "🔍 GH_TOKEN not found in environment or .env file"
+fi
+
+# Check if already authenticated with persistent credentials (not just env var)
+if [ -f "$HOME/.config/gh/hosts.yml" ] && [ -s "$HOME/.config/gh/hosts.yml" ]; then
+    echo "✅ GitHub CLI is already authenticated with persistent credentials"
+    echo "👤 Authenticated as: $(gh api user --jq .login 2>/dev/null || echo 'Unknown')"
+
+    # Setup git credential helper
+    echo "⚙️  Configuring git credential helper..."
+    gh auth setup-git
+    echo "✅ Git credential helper configured"
+    echo ""
+    echo "✅ GitHub CLI is ready to use!"
+    exit 0
+fi
+
+# If not authenticated, check if GH_TOKEN is available
+if [ -z "$GH_TOKEN" ]; then
+    echo "ℹ️  No GH_TOKEN found - GitHub CLI authentication will be skipped"
+    echo "   To enable automatic authentication, create .devcontainer/.env with:"
+    echo "   GH_TOKEN=your_github_token_here"
+    exit 0
+fi
+
+# Authenticate with GitHub CLI and store credentials persistently
+echo "🔑 Authenticating with GitHub CLI using token..."
+# Temporarily store token and clear environment to force persistent storage
+TEMP_TOKEN="$GH_TOKEN"
+unset GH_TOKEN
+echo "$TEMP_TOKEN" | gh auth login --with-token
+
+# Verify authentication
+if gh auth status >/dev/null 2>&1; then
+    echo "✅ GitHub CLI authentication successful"
+
+    # Setup git credential helper
+    echo "⚙️  Configuring git credential helper..."
+    gh auth setup-git
+    echo "✅ Git credential helper configured"
+
+    # Show current user
+    echo "👤 Authenticated as: $(gh api user --jq .login)"
+    echo ""
+    echo "✅ GitHub CLI is ready to use!"
+else
+    echo "❌ GitHub CLI authentication failed"
+    echo "   Please check your token and try again"
+    exit 1
+fi 

.devcontainer/scripts/post-create.sh

@@ -8,6 +8,10 @@ echo "🚀 Setting up UI Kit development environment..."
 # Ensure we're in the workspace directory
 cd /workspace
 
+# Authenticate with GitHub CLI (gh-auth.sh handles .env loading internally)
+echo "🔐 Setting up GitHub CLI authentication..."
+bash .devcontainer/scripts/gh-auth.sh
+
 # Set up git configuration if not already set
 if [ -z "$(git config --global user.name)" ]; then
     echo "⚙️  Setting up git configuration..."

docs/project_plan.md

@@ -120,6 +120,16 @@ A pragmatic breakdown into **four one‑week sprints** plus a preparatory **Spri
 
 ---
 
+## Critical Bug Fixes & Unplanned Tasks
+
+| #    | Task                                                              | DoD                                                                                    | Status |
+| ---- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------ |
+| BF.1 | **Issue #46**: Fix TypeScript module resolution for pnpm projects | pnpm users can compile TypeScript without module resolution errors; peer deps resolved | ✓      |
+
+**BF.1 Details**: Moved all Radix UI packages from dependencies to peerDependencies to fix TypeScript compilation failures in pnpm projects due to symlink structure conflicts. Released as v0.4.4.
+
+---
+
 ## Post‑MVP backlog (icebox)
 
 - Add Prometheus metrics endpoint to API stub.

packages/showcase/index.html

@@ -1,16 +1,14 @@
 <!doctype html>
 <html lang="en">
-
-<head>
+  <head>
     <meta charset="UTF-8" />
     <link rel="icon" type="image/svg+xml" href="/vite.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>UI-Kit Showcase</title>
-</head>
+  </head>
 
-<body>
+  <body>
     <div id="root"></div>
     <script type="module" src="/src/main.tsx"></script>
-</body>
-
-</html>
+  </body>
+</html>