Update documentation structure and enhance .gitignore

- Added generated index files and report directories to .gitignore to prevent unnecessary tracking of transient files.
- Updated README links to reflect new documentation paths for better navigation.
- Improved documentation organization by ensuring all links point to the correct locations, enhancing user experience and accessibility.

docs/guides/PNPM_MIGRATION_GUIDE.md

@@ -0,0 +1,136 @@
+# pnpm Migration Guide
+
+This guide explains the package management setup for the Sankofa Phoenix project.
+
+## Current Status
+
+The project supports both **pnpm** (recommended) and **npm** (fallback) for package management.
+
+- **Root**: Uses `pnpm` with `pnpm-lock.yaml`
+- **API**: Supports both `pnpm` and `npm` (via `.npmrc` configuration)
+- **Portal**: Supports both `pnpm` and `npm` (via `.npmrc` configuration)
+
+## Why pnpm?
+
+pnpm offers several advantages:
+
+1. **Disk Space Efficiency**: Shared dependency store across projects
+2. **Speed**: Faster installation due to content-addressable storage
+3. **Strict Dependency Resolution**: Prevents phantom dependencies
+4. **Better Monorepo Support**: Excellent for managing multiple packages
+
+## Installation
+
+### Using pnpm (Recommended)
+
+```bash
+# Install pnpm globally
+npm install -g pnpm
+
+# Or using corepack (Node.js 16.13+)
+corepack enable
+corepack prepare pnpm@latest --activate
+
+# Install dependencies
+pnpm install
+
+# In API directory
+cd api
+pnpm install
+
+# In Portal directory
+cd portal
+pnpm install
+```
+
+### Using npm (Fallback)
+
+```bash
+# Install dependencies with npm
+npm install
+
+# In API directory
+cd api
+npm install
+
+# In Portal directory
+cd portal
+npm install
+```
+
+## CI/CD
+
+The CI/CD pipeline (`.github/workflows/ci.yml`) supports both package managers:
+
+```yaml
+- name: Install dependencies
+  run: npm install --frozen-lockfile || pnpm install --frozen-lockfile
+```
+
+This ensures CI works regardless of which package manager is used locally.
+
+## Migration Steps (Optional)
+
+If you want to fully migrate to pnpm:
+
+1. **Remove package-lock.json files** (if any exist):
+   ```bash
+   find . -name "package-lock.json" -not -path "*/node_modules/*" -delete
+   ```
+
+2. **Install with pnpm**:
+   ```bash
+   pnpm install
+   ```
+
+3. **Verify installation**:
+   ```bash
+   pnpm list
+   ```
+
+4. **Update CI/CD** (optional):
+   - The current CI already supports both, so no changes needed
+   - You can make it pnpm-only if desired
+
+## Benefits of Current Setup
+
+The current flexible setup provides:
+
+- ✅ **Backward Compatibility**: Works with both package managers
+- ✅ **Team Flexibility**: Team members can use their preferred tool
+- ✅ **CI Resilience**: CI works with either package manager
+- ✅ **Gradual Migration**: Can migrate at own pace
+
+## Recommended Practice
+
+While both are supported, we recommend:
+
+- **Local Development**: Use `pnpm` for better performance
+- **CI/CD**: Current setup (both supported) is fine
+- **Documentation**: Update to reflect pnpm as primary, npm as fallback
+
+## Troubleshooting
+
+### Module not found errors
+
+If you encounter module resolution issues:
+
+1. Delete `node_modules` and lock file
+2. Reinstall with your chosen package manager:
+   ```bash
+   rm -rf node_modules package-lock.json
+   pnpm install  # or npm install
+   ```
+
+### Lock file conflicts
+
+If you see conflicts between `package-lock.json` and `pnpm-lock.yaml`:
+
+- Use `.gitignore` to exclude `package-lock.json` (already configured)
+- Team should agree on primary package manager
+- Document choice in README
+
+---
+
+**Last Updated**: 2025-01-09
+