@bostonuniversity/buwp-local 0.6.2 → 0.6.3

package/.buwp-local.json

@@ -0,0 +1,22 @@
+{
+  "projectName": "buwp-local",
+  "image": "bu-wordpress:latest",
+  "hostname": "jaydub.local",
+  "multisite": true,
+  "services": {
+    "redis": true,
+    "s3proxy": true,
+    "shibboleth": true
+  },
+  "ports": {
+    "http": 80,
+    "https": 443,
+    "db": 3306,
+    "redis": 6379
+  },
+  "mappings": [],
+  "env": {
+    "WP_DEBUG": true,
+    "XDEBUG": false
+  }
+}

package/docs/CHANGELOG.md

@@ -5,7 +5,10 @@ All notable changes to buwp-local will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.6.3]
+
+### Added
+- Documentation for volume mapping and xdebug
 
 ## [0.6.2]
 

package/docs/GETTING_STARTED.md

@@ -183,8 +183,11 @@ npx buwp-local destroy
 ## Next Steps
 
 - **[Commands Reference](COMMANDS.md)** - Full list of available commands
+- **[Volume Mapping Patterns](VOLUME_MAPPINGS.md)** - Advanced multi-repo workflows
+- **[Xdebug Setup](XDEBUG.md)** - Configure step debugging for your pattern
 - **[Credential Management](CREDENTIALS.md)** - Detailed guide to managing secrets
 - **[Multi-Project Setup](MULTI_PROJECT.md)** - Run multiple projects simultaneously
+- **[Migration from VM Sandboxes](MIGRATION_FROM_VM.md)** - Transitioning from traditional VMs
 - **[Architecture](ARCHITECTURE.md)** - Understand how buwp-local works
 
 ## Troubleshooting

package/docs/MULTI_PROJECT.md

@@ -137,6 +137,9 @@ npx buwp-local logs -f
 
 ## Shared Environments
 
+> **💡 Looking for volume mapping patterns?**  
+> This section covers the legacy "shared environment" approach. For modern multi-repo development, see [Volume Mapping Patterns](VOLUME_MAPPINGS.md), especially [Pattern B: Sandbox Coordination](VOLUME_MAPPINGS.md#pattern-b-sandbox-coordination) which provides a cleaner architecture.
+
 ### When to Use Shared Environments
 
 Use a shared environment when you need to:

package/docs/ROADMAP.md

@@ -10,7 +10,7 @@ Strategic direction and development priorities for buwp-local.
 
 **Key Features:**
 - macOS Keychain integration for secure credential storage
-- Automatic hex decoding for legacy multiline credentials
+- Automatic hex decoding for large multiline credentials like Shibboleth keys and certs
 - Credential validation on startup with interactive setup
 - Multi-project support with isolated Docker volumes
 - Smart initialization for plugins, themes, and mu-plugins
@@ -110,11 +110,12 @@ hostile.remove('127.0.0.1', config.hostname);
   - Guide users on setting up access to private registries (ghcr.io)
   - Automatic check for registry login or existing image on `start`
 
-### Planned for v0.6.2
+### Shipped in v0.6.2
 
-- ***Get spaces in volume mappings working correctly***
+- **Fix issues with spaces in paths**
   - Fix issues with spaces in host paths causing Docker errors
-  - Ensure cross-platform compatibility (Windows, macOS, Linux)
+
+### Planned for v0.6.3
 
 - **Basic docs on existing Xdebug features**
   - Quickstart guide for enabling and using Xdebug in containers
@@ -122,6 +123,35 @@ hostile.remove('127.0.0.1', config.hostname);
 - **Volume Mapping pattern guide**
   - Documentation on different volume mapping strategies for various development workflows
 
+### Shipped in v0.6.3
+
+**Focus:** Documentation refinement based on real user patterns
+
+**Key Deliverables:**
+
+1. **Volume Mapping Patterns Guide** ✅
+   - Comprehensive [VOLUME_MAPPINGS.md](VOLUME_MAPPINGS.md) documenting 3 patterns:
+     - **Pattern A:** In-Repo Development (self-contained, wp-env style)
+     - **Pattern B:** Sandbox Coordination (base camp maps multiple repos)
+     - **Pattern C:** Monolithic Sandbox (full WordPress for IDE context)
+   - Based on real user workflows discovered during initial rollout
+   - Decision trees, comparison tables, and migration guides
+   - Advanced topics: switching patterns, hybrid setups, performance considerations
+
+2. **Xdebug Configuration Guide** ✅
+   - Comprehensive [XDEBUG.md](XDEBUG.md) with pattern-specific pathMappings
+   - VSCode, PHPStorm, and Zed examples for each pattern
+   - Multi-root workspace setup for Pattern B
+   - Troubleshooting breakpoints, performance, and common issues
+
+3. **Cross-Reference Documentation** ✅
+   - Updated readme.md with links to new guides
+   - Added callouts in MULTI_PROJECT.md pointing to Pattern B
+   - Enhanced GETTING_STARTED.md next steps section
+   - Improved discoverability across documentation
+
+**Result:** Documentation now accurately reflects real-world development workflows, making it easier for new users to adopt appropriate patterns.
+
 ## Next Phase: v0.7.0 - Developer Experience
 
 **Status:** Planned  
@@ -130,7 +160,7 @@ hostile.remove('127.0.0.1', config.hostname);
 
 ### Potential Features
 
-- **Security Checks**
+- **Database Security**
   - Check database access on db port (e.g. `localhost:3306`)
   - Consider more stringent default database passwords
   - The database can have restricted content in it, so we need to ensure that users are aware of this and take appropriate measures.
@@ -140,7 +170,7 @@ hostile.remove('127.0.0.1', config.hostname);
   - Documentation on usage patterns
 
 - **Improved Windows and Linux support**
-  - Multiplatform /etc/hosts hostname management
+  - Multiplatform /etc/hosts hostname guide
   - Evaluate credential storage solutions for non-macOS platforms (https://www.npmjs.com/package/keytar)
 
 - **Project Status & Listing**
@@ -148,10 +178,11 @@ hostile.remove('127.0.0.1', config.hostname);
   - View all running projects: `buwp-local list`
   - Quick status checks: `buwp-local status`
 
-- **Health Checks**
+- **Health Checks and Network Ports**
   - Verify services are running properly
   - Database connectivity validation
   - Clear diagnostics on failures
+  - Advice and assistance on port conflicts
 
 - **Improved Error Messages**
   - Docker startup failures → actionable solutions
@@ -165,7 +196,7 @@ hostile.remove('127.0.0.1', config.hostname);
   - listing and cleanup of unused volumes
 
 ### Prioritization
-Will be informed by feedback from initial 2-3 users and actual pain points observed during rollout.
+Will be informed by feedback from initial small group of users and actual pain points observed during rollout.
 
 ---
 
@@ -174,13 +205,11 @@ Will be informed by feedback from initial 2-3 users and actual pain points obser
 **Status:** Conceptual  
 **Timeline:** TBD based on team feedback
 
-### Potential Features (Lower Priority)
+### Potential Features
 
-- **SSL Certificate Generation** - Local HTTPS with mkcert
-- **Database Backup/Restore** - Simplified snapshots and recovery
-- **Performance Monitoring** - Real-time resource usage tracking
-- **Team Configuration Sync** - Share project configurations across team
 - **Cross-Platform Support** - Windows WSL2 and Linux credential storage
+- **SSL Certificate Generation** - Local HTTPS with mkcert
+- **Performance Monitoring** -
 
 **Note:** Automatic `/etc/hosts` management deferred pending user feedback. See "Lessons Learned" section above for details on the `hostile` library approach.
 
@@ -195,7 +224,7 @@ Will be informed by feedback from initial 2-3 users and actual pain points obser
 **Focus:** Robustness, clear setup, good documentation
 
 ### Stage 2: Team Rollout
-**Users:** 10-15 developers  
+**Users:** 5-10 developers  
 **Goal:** Find and fix real-world issues  
 **Release:** v0.7.0+  
 **Focus:** Developer experience, error handling

package/docs/VOLUME_MAPPINGS.md

@@ -0,0 +1,466 @@
+# Volume Mapping Patterns
+
+Guide to configuring volume mappings for different development workflows in buwp-local.
+
+## Overview
+
+Volume mappings connect your local filesystem to the WordPress container, enabling live code sync and IDE integration. There are two main approaches based on **where buwp-local lives**:
+
+- **Inside your plugin/theme repo** (Pattern A) - Self-contained, like wp-env
+- **In a separate "base camp" directory** (Patterns B & C) - Coordinates multiple repos
+
+This guide documents three patterns based on real user workflows.
+
+**Quick Navigation:**
+- [Pattern A: In-Repo Development](#pattern-a-in-repo-development) - Single plugin/theme, wp-env style
+- [Pattern B: Sandbox Coordination](#pattern-b-sandbox-coordination) - Multiple repos from base camp
+- [Pattern C: Monolithic Sandbox](#pattern-c-monolithic-sandbox) - Full WordPress build in base camp
+- [Choosing a Pattern](#choosing-a-pattern) - Decision guide
+
+---
+
+## Pattern A: In-Repo Development
+
+**Use Case:** Single plugin or theme development, wp-env style
+
+### Description
+
+buwp-local is installed directly in your plugin or theme repository. It can be  configured by `npx buwp-local init`, which will try to detect if is being run within a plugin or theme directory and automatically set up the volume mapping. The repository is self-contained and maps itself into WordPress.
+
+**Good for:**
+- Transitioning from wp-env
+- Open source plugins (distributable setup)
+- Single-focus development
+- Projects where repo includes dev environment setup
+
+### Pros & Cons
+
+**Pros:**
+- ✅ Simplest setup (`init` can auto-configure)
+- ✅ Self-contained to one repo (each repo can have its own setup)
+- ✅ Fast volume performance (minimal mapping)
+- ✅ Clean isolation (your code vs WordPress core)
+- ✅ Familiar to wp-env users
+
+**Cons:**
+- ❌ Can't easily develop multiple plugins together
+- ❌ Local sites don't share content or database
+- ❌ No IDE context for WordPress core
+
+### Example Configuration
+
+**Directory Structure:**
+```
+~/projects/bu-custom-analytics/    ← Your plugin repo
+├── .buwp-local.json              ← buwp-local config
+├── package.json                  ← Has buwp-local as devDependency
+├── node_modules/
+│   └── @bostonuniversity/buwp-local/
+├── bu-custom-analytics.php
+├── includes/
+└── assets/
+
+Container:
+/var/www/html/                    (Docker volume)
+└── wp-content/
+    └── plugins/
+        └── bu-custom-analytics/  (→ mapped to your repo root)
+```
+
+**Configuration File (`.buwp-local.json`):**
+```json
+{
+  "projectName": "bu-custom-analytics",
+  "hostname": "bu-custom-analytics.local",
+  "mappings": [
+    {
+      "local": "./",
+      "container": "/var/www/html/wp-content/plugins/bu-custom-analytics"
+    }
+  ]
+}
+```
+
+### Setup Workflow
+
+```bash
+# 1. Navigate to your plugin/theme repo
+cd ~/projects/bu-custom-analytics
+
+# 2. Install buwp-local
+npm install --save-dev @bostonuniversity/buwp-local
+
+# 3. Initialize (auto-generates config with mapping)
+npx buwp-local init --plugin
+
+# 4. Start environment
+npx buwp-local start
+```
+
+### When to Use
+
+- ✅ Single plugin or theme development
+- ✅ Coming from wp-env background
+- ✅ Want repo to be fully self-contained
+- ✅ Don't need to test multiple plugins together
+
+### Xdebug Configuration
+
+See [Pattern A in XDEBUG.md](XDEBUG.md#pattern-a-in-repo-development) for IDE-specific pathMappings.
+
+---
+
+## Pattern B: Sandbox Coordination
+
+**Use Case:** Multiple repos coordinated from a "base camp" directory
+
+### Description
+
+buwp-local is installed in a **separate "base camp" directory** that doesn't contain any WordPress code. This directory coordinates multiple plugin/theme repos by mapping them into a shared WordPress instance. The repos themselves remain pure and unaware of buwp-local.
+
+**Key concept:** Like the traditional VM sandbox development environment, but using Docker and volume mappings instead of SFTP.
+
+**Good for:**
+- Working on multiple repos that interact
+- Keeping repos free of development tool dependencies
+
+### Pros & Cons
+
+**Pros:**
+- ✅ Repos stay pure (no buwp-local installation needed)
+- ✅ Work on multiple plugins/themes simultaneously
+- ✅ Test plugin interactions in realistic environment
+- ✅ Team can share base camp configuration
+- ✅ Site content and database available across repos in single project
+
+**Cons:**
+- ❌ Requires hand-editing config file for mappings
+- ❌ No WordPress core context in IDE (unless using Pattern C)
+- ❌ Slightly more complex initial setup
+
+### Example Configuration
+
+**Directory Structure:**
+```
+~/projects/
+├── bu-sandbox/                   ← "Base camp" (owns buwp-local)
+│   ├── .buwp-local.json         ← Hand-edited mappings
+│   ├── .env.local               ← Credentials (optional)
+│   ├── package.json             ← npm install buwp-local here
+│   └── node_modules/
+│       └── @bostonuniversity/buwp-local/
+│
+├── bu-navigation/                ← Pure repo (no buwp-local)
+│   ├── bu-navigation.php
+│   └── includes/
+│
+├── bu-slideshow/                 ← Pure repo (no buwp-local)
+│   ├── bu-slideshow.php
+│   └── assets/
+│
+└── responsive-framework/         ← Pure repo (no buwp-local)
+    ├── style.css
+    └── functions.php
+
+Container (all repos mapped into one WordPress):
+/var/www/html/                    (Docker volume)
+└── wp-content/
+    ├── plugins/
+    │   ├── bu-navigation/        (→ ~/projects/bu-navigation)
+    │   └── bu-slideshow/         (→ ~/projects/bu-slideshow)
+    └── themes/
+        └── responsive-framework/ (→ ~/projects/responsive-framework)
+```
+
+**Configuration File (`~/projects/bu-sandbox/.buwp-local.json`):**
+
+Using **absolute paths** (most common, explicit):
+```json
+{
+  "projectName": "bu-sandbox",
+  "hostname": "bu-sandbox.local",
+  "multisite": true,
+  "services": {
+    "redis": true,
+    "s3proxy": true,
+    "shibboleth": true
+  },
+  "ports": {
+    "http": 80,
+    "https": 443,
+    "db": 3306,
+    "redis": 6379
+  },
+  "mappings": [
+    {
+      "local": "/Users/username/projects/bu-navigation",
+      "container": "/var/www/html/wp-content/plugins/bu-navigation"
+    },
+    {
+      "local": "/Users/username/projects/bu-slideshow",
+      "container": "/var/www/html/wp-content/plugins/bu-slideshow"
+    },
+    {
+      "local": "/Users/username/projects/responsive-framework",
+      "container": "/var/www/html/wp-content/themes/responsive-framework"
+    }
+  ],
+  "env": {
+    "WP_DEBUG": true,
+    "XDEBUG": false
+  }
+}
+```
+
+Using **relative paths** (if repos are siblings to base camp):
+```json
+{
+  "projectName": "bu-sandbox",
+  "hostname": "bu-sandbox.local",
+  "mappings": [
+    {
+      "local": "../bu-navigation",
+      "container": "/var/www/html/wp-content/plugins/bu-navigation"
+    },
+    {
+      "local": "../bu-slideshow",
+      "container": "/var/www/html/wp-content/plugins/bu-slideshow"
+    },
+    {
+      "local": "../responsive-framework",
+      "container": "/var/www/html/wp-content/themes/responsive-framework"
+    }
+  ]
+}
+```
+
+### Setup Workflow
+
+```bash
+# 1. Create base camp directory
+mkdir ~/projects/bu-sandbox
+cd ~/projects/bu-sandbox
+
+# 2. Initialize npm project and install buwp-local
+npm init -y
+npm install --save-dev @bostonuniversity/buwp-local
+
+# 3. Initialize in sandbox mode
+npx buwp-local init --sandbox
+
+# 4. Hand-edit .buwp-local.json to add repo mappings
+# (See example configurations above)
+
+# 5. Start environment
+npx buwp-local start
+
+# 6. Develop in your repos (bu-navigation, bu-slideshow, etc.)
+# Changes sync automatically via volume mappings
+```
+
+### When to Use
+
+- ✅ Developing multiple BU plugins/themes together
+- ✅ Testing plugin interactions (navigation + slideshow + theme)
+- ✅ Want repos to stay clean (no dev tool dependencies)
+- ✅ Transitioning from VM sandbox workflow
+
+### Xdebug Configuration
+
+See [Pattern B in XDEBUG.md](XDEBUG.md#pattern-b-sandbox-coordination) for multi-workspace pathMappings.
+
+---
+
+## Pattern C: Monolithic Sandbox
+
+**Use Case:** Full WordPress codebase for complete IDE intelligence
+
+### Description
+
+A variant of Pattern B where the base camp maps the **entire WordPress installation** instead of selective plugins/themes. This provides complete IDE context (autocomplete for WordPress core, go-to-definition across all code) at the cost of more complex setup and slower filesystem performance.
+
+**Good for:**
+- Advanced IDE users (PHPStorm, Zed)
+- Complex debugging across multiple codebases
+- Need to edit WordPress core or dependencies
+- Want full codebase navigation
+
+### Pros & Cons
+
+**Pros:**
+- ✅ Full WordPress core autocomplete in IDE
+- ✅ Go-to-definition works across all code
+- ✅ Can edit any file (core, plugins, themes)
+- ✅ Step debug the entire codebase
+- ✅ Complete codebase context
+
+**Cons:**
+- ❌ Complex initial setup
+- ❌ Must manage all code updates locally
+- ❌ Risk of accidentally editing core files
+- ❌ Potentially Slower volume performance (large mapping)
+
+### Example Configuration
+
+**Directory Structure:**
+```
+~/projects/
+├── bu-sandbox-full/              ← Base camp
+│   ├── .buwp-local.json         ← Points to wordpress-build
+│   ├── package.json             ← Has buwp-local
+│   ├── node_modules/
+│   └── wordpress-build/          ← Full WordPress ← Mapped to container
+│       ├── wp-admin/
+│       ├── wp-content/
+│       │   ├── plugins/
+│       │   │   ├── bu-navigation/
+│       │   │   ├── bu-slideshow/
+│       │   │   └── ... (all plugins)
+│       │   ├── themes/
+│       │   │   └── ... (all themes)
+│       │   └── mu-plugins/
+│       ├── wp-includes/
+│       └── wp-config.php
+
+Container:
+/var/www/html/  (→ entire wordpress-build directory)
+```
+
+**Configuration File (`~/projects/bu-sandbox-full/.buwp-local.json`):**
+
+Using **relative path** to wordpress-build:
+```json
+{
+  "projectName": "bu-sandbox-full",
+  "hostname": "bu-sandbox-full.local",
+  "multisite": true,
+  "services": {
+    "redis": true,
+    "s3proxy": true,
+    "shibboleth": true
+  },
+  "ports": {
+    "http": 80,
+    "https": 443,
+    "db": 3306,
+    "redis": 6379
+  },
+  "mappings": [
+    {
+      "local": "./wordpress-build",
+      "container": "/var/www/html"
+    }
+  ],
+  "env": {
+    "WP_DEBUG": true,
+    "XDEBUG": true
+  }
+}
+```
+
+Using **absolute path**:
+```json
+{
+  "projectName": "bu-sandbox-full",
+  "hostname": "bu-sandbox-full.local",
+  "mappings": [
+    {
+      "local": "/Users/username/projects/bu-sandbox-full/wordpress-build",
+      "container": "/var/www/html"
+    }
+  ]
+}
+```
+
+### Setup Workflow
+
+```bash
+# 1. Create base camp directory
+mkdir ~/projects/bu-sandbox-full
+cd ~/projects/bu-sandbox-full
+
+# 2. Build or clone full WordPress
+# Method depends on your organization:
+#   - Clone WordPress core
+#   - Clone all BU plugins/themes into wp-content/
+#   - Run any build scripts (composer, npm)
+#   - Or: Copy from existing dev environment
+
+# Example structure:
+mkdir wordpress-build
+cd wordpress-build
+# ... set up WordPress core + all plugins/themes ...
+
+# 3. Back to base camp, initialize npm and install buwp-local
+cd ~/projects/bu-sandbox-full
+npm init -y
+npm install --save-dev @bostonuniversity/buwp-local
+
+# 4. Initialize in sandbox mode
+npx buwp-local init --sandbox
+
+# 5. Edit .buwp-local.json to map wordpress-build
+# (See example configuration above)
+
+# 6. Start environment
+npx buwp-local start
+
+# 7. Open IDE with wordpress-build as project root
+# Full WordPress codebase is now available for autocomplete
+```
+
+### When to Use
+
+- ✅ Using advanced IDE (Zed, PHPStorm with deep inspection)
+- ✅ Need autocomplete for WordPress core functions
+- ✅ Debugging complex issues across plugins + core
+- ✅ Want complete codebase navigation
+- ✅ Willing to manage full WordPress build locally
+- ✅ Have fast disk I/O (SSD recommended)
+
+### Important Considerations
+
+**WordPress Management:**
+- You're responsible for build updates and maintenance
+
+**Performance:**
+- Largest mapping = slowest volume I/O on macOS
+- Initial sync may take time (large file count)
+- File watchers may struggle with large codebases
+- Linux performs better than macOS for large mappings
+
+### Xdebug Configuration
+
+See [Pattern C in XDEBUG.md](XDEBUG.md#pattern-c-monolithic-sandbox) for complete IDE context pathMappings.
+
+---
+
+## Choosing a Pattern
+
+### Quick Comparison Table
+
+| Pattern | buwp-local Location | IDE Context | Setup | Volume Perf | Best For |
+|---------|---------------------|-------------|-------|-------------|----------|
+| **A: In-Repo** | Inside plugin/theme repo | Your code only | ⭐ Easy | ⭐⭐⭐ Fast | wp-env users, single repo |
+| **B: Sandbox** | Separate base camp | Your repos only | ⭐⭐ Medium | ⭐⭐ Good | Multiple repos, teams |
+| **C: Monolithic** | Separate base camp | Everything | ⭐⭐⭐⭐ Advanced | ⭐ Slower | Full IDE context |
+
+### Recommendation by Scenario
+
+**Coming from wp-env?** → Pattern A (familiar workflow)  
+**Coming from VM sandbox?** → Pattern B (similar concept, better maintainability)  
+**Multiple BU plugins to test?** → Pattern B (coordination from base camp)  
+**Team development?** → Pattern B (shared base camp config)  
+**Need WordPress core autocomplete?** → Pattern C (monolithic sandbox)  
+**Single open-source plugin?** → Pattern A (self-contained repo)
+
+You can mix patterns - some repos use Pattern A while others coordinate through Pattern B base camp.  
+
+---
+
+## Related Documentation
+
+- **[XDEBUG.md](XDEBUG.md)** - Pattern-specific Xdebug configuration
+- **[MULTI_PROJECT.md](MULTI_PROJECT.md)** - Isolated vs shared environment strategies
+- **[GETTING_STARTED.md](GETTING_STARTED.md)** - Initial setup guide
+- **[COMMANDS.md](COMMANDS.md)** - CLI reference

package/docs/XDEBUG.md

@@ -0,0 +1,429 @@
+# Xdebug Setup Guide
+
+Xdebug configuration depends on your [volume mapping pattern](VOLUME_MAPPINGS.md). The key principle: **pathMappings must match your volume mappings exactly**.
+
+## Quick Start
+
+1. **Enable Xdebug** in `.buwp-local.json`:
+```json
+"env": {
+  "XDEBUG": true
+}
+```
+
+2. **Restart environment** to apply changes:
+```bash
+npx buwp-local stop
+npx buwp-local start
+```
+
+3. **Configure pathMappings** using the pattern-specific examples below.
+
+---
+
+## Pattern A: In-Repo Development
+
+**Scenario:** buwp-local lives inside your plugin/theme repo (like wp-env).
+
+**Volume mapping:**
+```json
+"mappings": [
+  {
+    "local": ".",
+    "container": "/var/www/html/wp-content/plugins/bu-navigation"
+  }
+]
+```
+
+### VSCode Configuration
+
+Create `.vscode/launch.json` in your plugin/theme repo:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Listen for Xdebug (Pattern A)",
+      "type": "php",
+      "request": "launch",
+      "port": 9003,
+      "pathMappings": {
+        "/var/www/html/wp-content/plugins/bu-navigation": "${workspaceRoot}"
+      }
+    }
+  ]
+}
+```
+
+### PHPStorm Configuration
+
+1. Go to **Run → Edit Configurations**
+2. Add **PHP Remote Debug** configuration
+3. Set **Server** configuration:
+   - Host: `localhost`
+   - Port: `9003`
+   - Debugger: `Xdebug`
+4. Add **Path mapping**:
+   - Local: `/path/to/bu-navigation` (your repo root)
+   - Remote: `/var/www/html/wp-content/plugins/bu-navigation`
+
+### Zed Configuration
+
+Create `.zed/tasks.json`:
+
+```json
+{
+  "xdebug": {
+    "type": "php",
+    "pathMappings": {
+      "/var/www/html/wp-content/plugins/bu-navigation": "."
+    }
+  }
+}
+```
+
+---
+
+## Pattern B: Sandbox Coordination
+
+**Scenario:** Base camp directory maps multiple plugin/theme repos.
+
+**Volume mapping:**
+```json
+"mappings": [
+  {
+    "local": "/Users/jaydub/projects/bu-navigation",
+    "container": "/var/www/html/wp-content/plugins/bu-navigation"
+  },
+  {
+    "local": "/Users/jaydub/projects/bu-slideshow",
+    "container": "/var/www/html/wp-content/plugins/bu-slideshow"
+  }
+]
+```
+
+### VSCode Multi-Root Workspace
+
+Create a **workspace file** (e.g., `bu-plugins.code-workspace`) to include all repos:
+
+```json
+{
+  "folders": [
+    { "path": "../bu-navigation" },
+    { "path": "../bu-slideshow" }
+  ],
+  "settings": {},
+  "launch": {
+    "version": "0.2.0",
+    "configurations": [
+      {
+        "name": "Listen for Xdebug (Pattern B)",
+        "type": "php",
+        "request": "launch",
+        "port": 9003,
+        "pathMappings": {
+          "/var/www/html/wp-content/plugins/bu-navigation": "${workspaceFolder:bu-navigation}",
+          "/var/www/html/wp-content/plugins/bu-slideshow": "${workspaceFolder:bu-slideshow}"
+        }
+      }
+    ]
+  }
+}
+```
+
+**Usage:**
+1. Open the `.code-workspace` file in VSCode
+2. All mapped repos will be available in the sidebar
+3. Set breakpoints in any repo
+4. Start debugging with F5
+
+### PHPStorm Multi-Module Setup
+
+1. Open PHPStorm, go to **File → Project Structure**
+2. Add each repo as a **Module**
+3. Configure **Run → Edit Configurations → PHP Remote Debug**
+4. Add path mappings for each repo:
+   - `/Users/jaydub/projects/bu-navigation` → `/var/www/html/wp-content/plugins/bu-navigation`
+   - `/Users/jaydub/projects/bu-slideshow` → `/var/www/html/wp-content/plugins/bu-slideshow`
+
+### Zed Workspace
+
+Zed doesn't have multi-root workspace concept. Open each repo separately and configure individually (Pattern A style for each).
+
+---
+
+## Pattern C: Monolithic Sandbox
+
+**Scenario:** Base camp maps entire WordPress installation for complete IDE context.
+
+**Volume mapping:**
+```json
+"mappings": [
+  {
+    "local": "/Users/jaydub/wordpress-builds/bu-prod",
+    "container": "/var/www/html"
+  }
+]
+```
+
+### VSCode Configuration
+
+Create `.vscode/launch.json` in your WordPress build directory:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Listen for Xdebug (Pattern C)",
+      "type": "php",
+      "request": "launch",
+      "port": 9003,
+      "pathMappings": {
+        "/var/www/html": "${workspaceRoot}"
+      }
+    }
+  ]
+}
+```
+
+**Advantages:**
+- Single path mapping (simpler)
+- Full WordPress context in IDE
+- Go-to-definition works across all code
+- Autocomplete for WordPress core
+
+**Trade-offs:**
+- Slower volume performance on macOS
+- Larger IDE project (may be slower)
+- Must manage entire WordPress build
+
+### PHPStorm Configuration
+
+1. Open the WordPress build directory as your project root
+2. Configure **PHP Remote Debug**
+3. Add single path mapping:
+   - Local: `/Users/jaydub/wordpress-builds/bu-prod`
+   - Remote: `/var/www/html`
+
+### Zed Configuration
+
+Create `.zed/tasks.json` in WordPress root:
+
+```json
+{
+  "xdebug": {
+    "type": "php",
+    "pathMappings": {
+      "/var/www/html": "."
+    }
+  }
+}
+```
+
+---
+
+## Common Setup Steps (All Patterns)
+
+### Install PHP Debug Extension (VSCode)
+
+1. Open VSCode Extensions (Cmd+Shift+X)
+2. Search for "PHP Debug"
+3. Install: https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug
+
+### Start Debugging
+
+1. **Set breakpoint** in your PHP file (click left gutter)
+2. **Start debug listener** (F5 or Run → Start Debugging)
+3. **Trigger code** in browser (reload page, submit form, etc.)
+4. **Debugger pauses** at breakpoint
+
+### Verify Xdebug is Running
+
+```bash
+# Check Xdebug is loaded
+npx buwp-local wp eval 'phpinfo();' | grep -i xdebug
+
+# Or via shell
+npx buwp-local shell
+php -v  # Should show "with Xdebug"
+```
+
+---
+
+## Alternative: VSCode Remote Container Debugging
+
+An alternative to volume mapping is to use VSCode's **Dev Containers** extension to open the entire WordPress container directly in VSCode.  PhpStorm also has a similar feature (Zed does not currently support this).
+
+### How It Works
+
+Instead of syncing code via volume mappings, you open VSCode **inside the container** and edit/debug directly there:
+
+1. Start buwp-local (any pattern, even without volume mappings)
+2. Right-click the running container in VSCode Docker explorer
+3. Select "Attach Visual Studio Code"
+4. VSCode opens inside the container with full filesystem access
+5. Set breakpoints and debug the entire build
+
+### When to Use This
+
+- ✅ Experimental edits (don't need to persist locally)
+- ✅ Full WordPress core context needed (like Pattern C)
+- ✅ Stepping through entire codebase quickly
+- ✅ Learning/exploring the build
+
+### Setup
+
+1. **Install Remote Containers Extension** (if not already installed)
+   - Open VSCode Extensions (Cmd+Shift+X)
+   - Search for "Remote - Containers"
+   - Install: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers
+
+2. **Start your environment**
+   ```bash
+   npx buwp-local start
+   ```
+
+3. **Open container in VSCode**
+   - Click **Containers** (sidebar)
+   - Open the buwp-local project in the Containers list
+   - Right-click on the WordPress container → **Attach Visual Studio Code**
+
+4. **Install Extensions and Configure Debugging in container**
+    - Install PHP Debug extension inside the container VSCode
+    - Create `.vscode/launch.json` with pathMappings as needed (usually just `/var/www/html` to `.`)
+
+### Advantages vs Volume Mapping
+
+| Aspect | Volume Mapping | Remote Container |
+|--------|---|---|
+| **IDE Context** | Pattern-dependent | Full codebase always |
+| **Persistence** | Changes stay local | Temporary only |
+| **Performance** | Fast (local) | Slower (Docker I/O) |
+| **Best For** | Production code changes | Experimental debugging |
+
+### When NOT to Use This
+
+- ❌ Changes you need to keep locally (use volume mapping instead)
+
+---
+
+## Troubleshooting
+
+### Breakpoints Not Hit
+
+**Check pathMappings match your volume mappings:**
+
+```bash
+# View your volume mappings
+npx buwp-local config --show
+
+# Ensure pathMappings in launch.json match exactly
+```
+
+**Common mistakes:**
+- Pattern A: Using `/var/www/html` instead of full plugin path
+- Pattern B: Missing mappings for some repos
+- Pattern C: Wrong workspace root
+
+### "Cannot Find File" Errors
+
+**VSCode shows:** "Could not find file /var/www/html/..."
+
+**Solution:** Your local file path doesn't match the pathMapping. Check:
+1. Is VSCode workspace root correct?
+2. Does `${workspaceRoot}` resolve to the right path?
+3. For Pattern B, are you using multi-root workspace?
+
+### Performance Issues
+
+**Xdebug can slow page loads significantly.**
+
+**Solutions:**
+- Disable Xdebug when not actively debugging
+- Use conditional breakpoints sparingly
+- Pattern C is slower than A/B due to larger volume mapping
+
+### Port Already in Use
+
+**Error:** "Port 9003 already in use"
+
+**Solution:**
+```bash
+# Find process using port 9003
+lsof -i :9003
+
+# Kill if needed
+kill -9 <PID>
+
+# Or change Xdebug port in launch.json and container config
+```
+
+---
+
+## Advanced Configuration
+
+### Conditional Breakpoints
+
+Right-click breakpoint in VSCode → Edit Breakpoint → Add expression:
+
+```php
+$post_id === 123
+```
+
+### Step Debugging WP-CLI Commands
+
+```bash
+# Enable Xdebug for CLI
+npx buwp-local wp --allow-root eval 'xdebug_break();'
+
+# Or set environment variable
+npx buwp-local shell
+export XDEBUG_SESSION=1
+wp plugin list
+```
+
+### Remote Debugging from Browser
+
+Install Xdebug browser extension:
+- Chrome: [Xdebug Helper](https://chrome.google.com/webstore/detail/xdebug-helper)
+- Firefox: [Xdebug Helper](https://addons.mozilla.org/en-US/firefox/addon/xdebug-helper-for-firefox/)
+
+Click extension icon → Enable debugging → Reload page.
+
+---
+
+## Pattern-Specific Tips
+
+### Pattern A (In-Repo)
+- ✅ Simplest pathMapping setup
+- ❌ No WordPress core debugging
+- 💡 Use [php-stubs/wordpress-stubs](https://github.com/php-stubs/wordpress-stubs) for autocomplete
+
+### Pattern B (Sandbox)
+- ✅ Debug multiple repos simultaneously
+- ⚠️ Requires multi-root workspace in VSCode
+- 💡 Create `.code-workspace` file for team to share
+
+### Pattern C (Monolithic)
+- ✅ Debug WordPress core, plugins, themes all together
+- ✅ Full IDE context (go-to-definition everywhere)
+- ⚠️ Larger project, slower performance on macOS
+- 💡 Use sparse checkout to reduce repo size
+
+---
+
+## Related Documentation
+
+- **[VOLUME_MAPPINGS.md](VOLUME_MAPPINGS.md)** - Complete guide to volume mapping patterns
+- **[GETTING_STARTED.md](GETTING_STARTED.md)** - Initial setup guide
+- **[COMMANDS.md](COMMANDS.md)** - CLI reference
+
+---
+
+## References
+
+- [Xdebug Documentation](https://xdebug.org/docs/)
+- [VSCode PHP Debugging](https://code.visualstudio.com/docs/languages/php)
+- [PHPStorm Xdebug Guide](https://www.jetbrains.com/help/phpstorm/configuring-xdebug.html)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bostonuniversity/buwp-local",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "Local WordPress development environment for Boston University projects",
   "type": "module",
   "main": "lib/index.js",

package/readme.md

@@ -99,7 +99,10 @@ Your local WordPress site should now be accessible at the hostname you configure
 
 - 📘 [Getting Started Guide](docs/GETTING_STARTED.md)
 - 📖 [Command Reference](docs/COMMANDS.md)
+- 🗺️ [Volume Mapping Patterns](docs/VOLUME_MAPPINGS.md) - Flexible development workflows
+- 🐛 [Xdebug Setup](docs/XDEBUG.md) - Step debugging configuration
 - 🔐 [Credential Management](docs/CREDENTIALS.md)
+- 🔄 [Migration from VM Sandboxes](docs/MIGRATION_FROM_VM.md)
 - 🏗️ [Architecture](docs/ARCHITECTURE.md) (for contributors)
 
 ## Features