diff --git a/BRANCH_ANALYSIS_IMPLEMENTATION.md b/BRANCH_ANALYSIS_IMPLEMENTATION.md
new file mode 100644
index 00000000..377b9d96
--- /dev/null
+++ b/BRANCH_ANALYSIS_IMPLEMENTATION.md
@@ -0,0 +1,162 @@
+# Branch Analysis Tool - Implementation Summary
+
+## Problem Statement
+The repository maintainer needed a way to identify which branches should be closed out as out of date or not needed.
+
+## Solution Delivered
+
+### 1. Automated Branch Analysis Tool
+**Location**: `scripts/analyze-branches.js`
+
+A comprehensive Node.js script that:
+- Fetches all remote branches from GitHub
+- Analyzes each branch's status relative to `main`
+- Categorizes branches into 5 priority groups:
+  1. **Merged** (safe to delete immediately)
+  2. **Stale** (90+ days old, review needed)
+  3. **Outdated** (60+ days, behind main)
+  4. **Work in Progress** (30-90 days old)
+  5. **Recent** (< 30 days, active)
+
+### 2. Branch Analysis Report
+**Location**: `BRANCH_ANALYSIS_REPORT.md`
+
+Auto-generated markdown report containing:
+- Summary statistics of all branches
+- Detailed tables for each category
+- Days since last commit
+- Number of commits behind main
+- Branch subjects/descriptions
+- Instructions for deleting branches
+
+**Current Statistics**:
+- Total branches: 260
+- Stale (90+ days): 21 branches
+- Work in Progress (30-90 days): 155 branches
+- Recent (< 30 days): 83 branches
+
+### 3. Branch Management Documentation
+**Location**: `BRANCH_MANAGEMENT.md`
+
+Comprehensive guide covering:
+- How to run the analysis tool
+- Branch categorization criteria
+- Deletion guidelines and best practices
+- Common scenarios and solutions
+- Monthly maintenance checklist
+- Branch naming conventions
+
+### 4. Integration with Workflow
+
+#### Added npm script:
+```bash
+npm run branches:analyze
+```
+
+#### Updated README.md:
+- Added "Useful Scripts" section with common commands
+- Added branch management reference in maintenance section
+- Clear documentation path for maintainers
+
+## How to Use
+
+### Running the Analysis
+```bash
+npm run branches:analyze
+```
+
+This will:
+1. Fetch all branches from GitHub
+2. Analyze their status
+3. Generate `BRANCH_ANALYSIS_REPORT.md`
+4. Display a summary in the terminal
+
+### Reading the Report
+Open `BRANCH_ANALYSIS_REPORT.md` to see:
+- Which branches are safe to delete
+- Which branches need review
+- Detailed information for each branch
+
+### Taking Action
+Follow the guidelines in `BRANCH_MANAGEMENT.md` to:
+1. Delete merged branches immediately
+2. Review stale branches with team
+3. Contact owners of abandoned work
+4. Keep recent active branches
+
+## Key Features
+
+### Intelligent Analysis
+- Detects merged branches automatically
+- Calculates age and divergence from main
+- Identifies temporary AI-generated branches
+- Provides context with commit subjects
+
+### Safety First
+- Never auto-deletes branches
+- Provides detailed information for review
+- Includes instructions for safe deletion
+- Recommends communication before deletion
+
+### Maintainable
+- Clear naming conventions
+- Well-documented code
+- Easy to extend or modify
+- Follows repository standards
+
+## Files Added/Modified
+
+### New Files
+- `scripts/analyze-branches.js` - Main analysis tool
+- `BRANCH_MANAGEMENT.md` - Comprehensive guide
+- `BRANCH_ANALYSIS_REPORT.md` - Generated report (initial)
+- `BRANCH_ANALYSIS_IMPLEMENTATION.md` - This file
+
+### Modified Files
+- `package.json` - Added `branches:analyze` script
+- `README.md` - Added references and useful scripts section
+
+## Recommendations for Maintenance
+
+### Monthly Tasks
+1. Run `npm run branches:analyze`
+2. Review the generated report
+3. Delete all merged branches
+4. Contact owners of stale branches
+5. Close associated PRs for abandoned work
+
+### Immediate Actions Available
+Based on the current analysis:
+
+#### Stale Branches (21 total)
+Review these 90+ day old branches:
+- Many `codex/*` branches from July-August 2025
+- Likely completed or abandoned AI-assisted fixes
+- Most are 1 commit behind main (easy to evaluate)
+
+#### Work in Progress (155 total)
+- Many `copilot/fix-*` branches from August-September
+- Review if associated PRs are merged
+- Consider closing abandoned feature branches
+
+## Future Enhancements (Optional)
+
+1. **Automated Cleanup**: Script to delete merged branches
+2. **PR Integration**: Link branches to their PRs
+3. **GitHub Actions**: Automated monthly reports
+4. **Web Dashboard**: Visual branch health overview
+5. **Notifications**: Alert branch owners of stale work
+
+## Support
+
+If you have questions about:
+- **Running the tool**: See `BRANCH_MANAGEMENT.md`
+- **Understanding the report**: Check the "How to Use" section above
+- **Deletion guidelines**: Review `BRANCH_MANAGEMENT.md` scenarios
+- **Tool issues**: Check `scripts/analyze-branches.js` comments
+
+---
+
+**Created**: 2025-11-05
+**Tool Version**: 1.0
+**Status**: Production Ready
diff --git a/BRANCH_ANALYSIS_REPORT.md b/BRANCH_ANALYSIS_REPORT.md
new file mode 100644
index 00000000..c39b17ce
--- /dev/null
+++ b/BRANCH_ANALYSIS_REPORT.md
@@ -0,0 +1,316 @@
+# Branch Analysis Report
+Generated: 2025-11-05T21:54:49.217Z
+
+## Summary
+
+- **Merged branches (safe to delete):** 0
+- **Stale branches (90+ days old):** 21
+- **Outdated branches (behind main, 60+ days):** 0
+- **Work in progress (30-90 days):** 155
+- **Recent branches (< 30 days):** 83
+
+## Recommendations
+
+### High Priority: Branches to Delete
+
+These branches have been merged into main and can be safely deleted:
+
+*No merged branches found.*
+
+### Medium Priority: Stale Branches (90+ days old)
+
+These branches haven't been updated in 90+ days. Review if they're still needed:
+
+| Branch | Last Commit | Days Old | Behind Main | Subject |
+|--------|-------------|----------|-------------|---------|
+| codex/refactor-application-for-transit-overlays | 2025-07-25 | 103 | 1 | Add relocation overlay option and enhanced coordin |
+| codex/create-config.example.js-with-api-key-placeholder | 2025-07-26 | 102 | 1 | Add config example file and update README |
+| codex/delete-openapi-1.json-and-temporary-files | 2025-07-26 | 102 | 1 | chore: remove stray macOS files |
+| codex/remove-default-person-b-information | 2025-07-26 | 102 | 1 | Remove default Person B UI and references |
+| codex/reorganize-project-structure-with-wovenmap | 2025-07-26 | 102 | 1 | Move app into wovenmap directory and add landing p |
+| codex/update-readme-with-new-instructions | 2025-07-26 | 102 | 1 | docs: update setup instructions |
+| codex/ensure-apidata.detail-is-a-string | 2025-07-29 | 99 | 1 | Ensure apiData.detail is stringified |
+| codex/add-glossary-terms-to-readme.md | 2025-07-30 | 98 | 1 | Add Raven Calder Synastry glossary |
+| codex/add-integration-note-to-readme-file | 2025-07-30 | 98 | 1 | Add integration note clarifying backend and downst |
+| codex/fix-missing-fields-error-in-request | 2025-07-30 | 98 | 1 | Use latitude/longitude fields |
+| codex/fix-undefined-object-error-in-chart | 2025-07-30 | 98 | 1 | fix transit relocation coordinates |
+| codex/update-country-code-validation-message | 2025-07-30 | 98 | 1 | Add synastry option and improve docs |
+| codex/add-api-key-presence-check | 2025-07-31 | 97 | 1 | Add RAPIDAPI_KEY presence check and dynamic header |
+| codex/add-error-handling-to-astrology-functions | 2025-07-31 | 97 | 1 | Improve response handling and JSON parsing |
+| codex/decide-project-licensing-and-update-documentation | 2025-07-31 | 97 | 1 | Add MIT license and update README |
+| codex/fix-api-error-when-generating-report | 2025-07-31 | 97 | 1 | docs: clarify restarting after setting env variabl |
+| codex/fix-external-api-error-in-dropdown | 2025-07-31 | 97 | 1 | docs: add troubleshooting section |
+| codex/fix-json-syntax-and-validate | 2025-07-31 | 97 | 1 | Fix incomplete openapi spec |
+| codex/update-error-handling-in-getchartdatafromapi | 2025-07-31 | 97 | 1 | Improve error handling for chart API |
+| codex/wrap-console.error-in-astrology.js | 2025-07-31 | 97 | 1 | log errors only on bad astrology responses |
+| copilot/fix-f6e82f54-71ed-4430-98c6-de1caa4e1d90 | 2025-08-02 | 95 | 1 | Merge branch 'main' into copilot/fix-f6e82f54-71ed |
+
+### Low Priority: Outdated Branches
+
+These branches are behind main and older than 60 days. Consider rebasing or closing:
+
+*No outdated branches found.*
+
+### Work in Progress (Review Needed)
+
+These branches are 30-90 days old. Review their status:
+
+| Branch | Last Commit | Days Old | Behind Main | Subject |
+|--------|-------------|----------|-------------|---------|
+| copilot/fix-0b19b383-3435-4766-be78-14a77006a258 | 2025-08-21 | 76 | 1 | Initial plan |
+| copilot/fix-26213c81-e071-48aa-81e0-66645d9876e7 | 2025-08-21 | 76 | 1 | Initial plan |
+| copilot/fix-925cfa18-71f9-43e0-9e3e-c99287df5a3f | 2025-08-21 | 76 | 1 | Initial plan |
+| copilot/fix-e79e6a74-0ca9-4b65-adb5-f47fe3267ebe | 2025-08-21 | 76 | 1 | Initial plan |
+| copilot/fix-07cd75fd-1ac0-44a5-adcf-4ac8d48635e7 | 2025-08-21 | 75 | 1 | Fix Netlify deployment by relocating seismograph m |
+| copilot/fix-0c9d168b-35ae-44cd-a257-ce862ced51c0 | 2025-08-21 | 75 | 1 | Merge branch 'main' into copilot/fix-0c9d168b-35ae |
+| copilot/fix-31 | 2025-08-21 | 75 | 1 | Merge branch 'main' into copilot/fix-31 |
+| copilot/fix-34 | 2025-08-21 | 75 | 1 | Merge branch 'main' into copilot/fix-34 |
+| copilot/fix-45563531-0a68-4387-a36e-45e97da9b1b8 | 2025-08-22 | 75 | 1 | [2025-01-21] FIX: Replace hardcoded "Person A/B" w |
+| copilot/fix-581002cf-689b-4afe-94ea-7a15595ed847 | 2025-08-22 | 75 | 1 | [2025-01-21] FIX: Include outer planets (Saturn, U |
+| copilot/fix-6ce62961-f0e6-49c7-9058-b03ac9415665 | 2025-08-21 | 75 | 1 | Fix seismograph.js conflicts and interface mismatc |
+| copilot/fix-6dc8162a-0655-4a28-92c2-b3f353bef901 | 2025-08-22 | 75 | 1 | [2025-01-21] UPDATE: Replace generic house descrip |
+| copilot/fix-86cd59e6-0299-49a4-99cc-23a4d4433430 | 2025-08-22 | 75 | 1 | [2025-01-22] FIX: Dual-person mode detection and P |
+| copilot/fix-9c52c6df-5a1e-4cd0-930c-f78bea2a0156 | 2025-08-21 | 75 | 1 | Create missing seismograph module with aggregate f |
+| copilot/fix-a4cc9020-91fe-4038-a2cc-0cb55a1891f6 | 2025-08-21 | 75 | 1 | [2025-01-21] FIX: Complete transit data handling f |
+| copilot/fix-a69409b9-6a62-4784-a69d-01cb1fcddf50 | 2025-08-22 | 75 | 1 | [2025-01-21] REFACTOR: Extract reusable natal char |
+| fix-missing-transits | 2025-08-22 | 75 | 1 | Update index.html |
+| fix-single-day-transits | 2025-08-22 | 75 | 1 | Fix: Use UTC dates for transit calculations |
+| fix/end-to-end-transit-logic | 2025-08-21 | 75 | 1 | Merge branch 'main' into fix/end-to-end-transit-lo |
+| copilot/fix-360586f8-7e73-4d64-9cd5-70568c1905da | 2025-08-22 | 74 | 1 | [2025-01-21] COMPLETE: Transit calculations fixed  |
+| copilot/fix-4c9bb9ac-aeb6-4401-97e6-4f860c0862ca | 2025-08-23 | 74 | 1 | [2025-01-23] CLEANUP: Remove temporary test files |
+| copilot/fix-51be708d-65a2-43c6-85f7-aa6619e48234 | 2025-08-23 | 74 | 1 | [2025-01-21] FEATURE: Add comprehensive debug logg |
+| copilot/fix-5c646122-e59b-406c-8925-c26f96121a87 | 2025-08-23 | 74 | 1 | [2025-01-23] FIX: Add missing zodiac_type to trans |
+| copilot/fix-4dd7469c-9237-40d4-ab8e-6925220c389c | 2025-08-24 | 73 | 1 | [2025-01-21] FEATURE: Implement Orb-Band + Phase + |
+| copilot/fix-50 | 2025-08-24 | 73 | 1 | [2025-01-21] COMPLETE: Mobile compatibility fixes  |
+| copilot/fix-1d91bbb6-6bd1-409d-9749-16848b93bf1f | 2025-08-25 | 72 | 1 | [2025-01-21] FIX: Remove dist/ from .gitignore to  |
+| copilot/fix-94025603-cfc2-4ca0-bf00-4271a38c38b6 | 2025-08-25 | 72 | 1 | [2025-01-21] FEATURE: Complete copilot fix recover |
+| copilot/fix-6cb5d9e5-4a51-4355-89f0-90371b49be4f | 2025-08-28 | 69 | 1 | [2025-01-21] FEATURE: Implement Mirror-first UX wi |
+| copilot/fix-b53974a4-ab90-4666-a7b9-2c339be0fba9 | 2025-08-28 | 69 | 1 | [2025-01-21] FEATURE: Implement enhanced thin-slic |
+| copilot/fix-daccaf49-c2bf-4047-bedc-ce202fd403aa | 2025-08-29 | 68 | 1 | Complete audit compliance implementation with Echo |
+| copilot/fix-f6067b52-cc09-4411-b5f6-1add9ec053fa | 2025-08-29 | 68 | 1 | Changes before error encountered |
+| copilot/fix-3b23575d-8d72-4f4e-a18f-793ba95b7cdf | 2025-09-02 | 64 | 1 | [2025-01-21] FIX: Enhanced barometer visualization |
+| codex/add-raw-natal-math-to-reports | 2025-09-04 | 62 | 1 | feat: expose raw math in reports and tests |
+| copilot/fix-32ee73bb-005d-41a2-a202-f1f457ff2626 | 2025-09-04 | 62 | 1 | [2025-01-21] FIX: Add synastry transit support to  |
+| copilot/fix-49b98822-0339-46d1-af26-9f1892861875 | 2025-09-04 | 62 | 1 | Merge branch 'main' into copilot/fix-49b98822-0339 |
+| copilot/fix-5383224f-879f-4976-afce-8c6e4c4d38a5 | 2025-09-03 | 62 | 1 | [2025-01-21] SOLUTION: Complete Queue Analysis and |
+| copilot/fix-768eb520-c96d-4d12-b578-a8157816a94d | 2025-09-03 | 62 | 1 | [2025-01-21] FIX: Remove automatic uncanny flags f |
+| copilot/fix-a218acb0-6322-400c-8f2f-3ea3b276f523 | 2025-09-04 | 62 | 1 | Merge branch 'main' into copilot/fix-a218acb0-6322 |
+| copilot/fix-bd3e3386-9a1f-4566-b7ab-8e10f1b1a805 | 2025-09-04 | 62 | 1 | Merge branch 'main' into copilot/fix-bd3e3386-9a1f |
+| copilot/fix-e42c3162-2547-42c2-beb5-2a9b7c625525 | 2025-09-04 | 62 | 1 | Merge branch 'main' into copilot/fix-e42c3162-2547 |
+| copilot/fix-68 | 2025-09-08 | 58 | 1 | [2025-01-21] FEATURE: Complete smoke test and debu |
+| codex/add-missing-natal-chart-data | 2025-09-09 | 57 | 1 | Add natal numbers and aspect geometry |
+| codex/ensure-glossary-card-consistency | 2025-09-09 | 57 | 1 | Define neutral magnitude ladder |
+| codex/implement-compensation-for-penalty-in-computesfd | 2025-09-09 | 57 | 1 | Adjust heavy-benefic conjunction penalty |
+| codex/modify-buildravenjsonreport-to-exclude-reports.templates | 2025-09-09 | 57 | 1 | Merge branch 'main' into codex/modify-buildravenjs |
+| codex/update-balance/triple-channel-sections | 2025-09-09 | 57 | 1 | Add calibration note and boundary logic to Balance |
+| codex/update-buildravenjsonreport-to-merge-reports | 2025-09-09 | 57 | 1 | Include top-level reports in Raven export |
+| codex/update-computebalancevalence-with-new-weights | 2025-09-09 | 57 | 1 | Refine balance meter valence weights |
+| copilot/fix-6f453f4d-65f1-4eb7-afdc-8a73773a3ea5 | 2025-09-09 | 57 | 1 | [2025-01-27] FEATURE: Complete emoji rebalancing - |
+| copilot/fix-auth0-redirect-urls | 2025-09-09 | 57 | 1 | Complete Auth0 fix with resolution summary and cle |
+| copilot/fix-chunk-upload-http-400-errors | 2025-09-09 | 57 | 1 | Add documentation test for chunked relationship va |
+| copilot/fix-natal-inputs-in-report | 2025-09-09 | 57 | 1 | [2025-01-21] FEATURE: Complete relational mirror p |
+| copilot/fix-pdf-generation-initialization-error | 2025-09-09 | 57 | 1 | [2025-01-27] FIX: Resolve PDF filename initializat |
+| copilot/remove-unnecessary-report-titles | 2025-09-09 | 57 | 1 | [2025-01-21] FIX: Replace narrative seismograph ti |
+| copilot/update-solo-mirror-report | 2025-09-09 | 57 | 1 | [2025-01-21] FIX: Correct data paths in Solo Mirro |
+| chore-restore-env-example | 2025-09-09 | 56 | 1 | chore: Restore .env.example to original state |
+| codex/create-netlify_integration.md-for-auth0-troubleshooting | 2025-09-10 | 56 | 1 | docs: add Auth0 404 troubleshooting |
+| codex/ensure-glossary-card-consistency-yeaqw3 | 2025-09-09 | 56 | 1 | Merge branch 'main' into codex/ensure-glossary-car |
+| copilot/fix-480b0116-bc05-4091-8f0d-6c01ef1257bf | 2025-09-10 | 56 | 1 | [2025-01-21] FEATURE: Implement Auth0 Application  |
+| copilot/fix-5cc562f4-eabf-4291-bf1d-4780c50038f9 | 2025-09-10 | 56 | 1 | [2025-01-21] FIX: Auth0 configuration issue resolv |
+| copilot/fix-5ea8110a-eb8d-4f71-9cc7-27edf68af253 | 2025-09-10 | 56 | 1 | [2025-01-21] FEATURE: Complete Auth0 setup with ve |
+| copilot/fix-6b7c5e8d-24f3-4c6d-9db3-ee8c022df31f | 2025-09-10 | 56 | 1 | [2025-01-21] UPDATE: Add authorizationParams fix d |
+| copilot/fix-6cb4ea92-0a95-4870-ae46-b34b0b81d818 | 2025-09-10 | 56 | 1 | [2025-01-21] FEATURE: Streamlined Auth0 setup work |
+| copilot/fix-d2649197-c508-48c6-83d0-6b7caa8e47ac | 2025-09-10 | 56 | 1 | [2025-01-21] FIX: Google Auth0 login configuration |
+| copilot/fix-ff65a0d7-ec2c-4f2c-8f65-dde6d49d3d9f | 2025-09-10 | 56 | 1 | Initial plan |
+| copilot/fix-1da9b008-d12b-4e32-85e0-1dffa74f1edc | 2025-09-19 | 47 | 1 | [2025-01-22] SOLUTION: Complete branch protection  |
+| copilot/fix-95 | 2025-09-19 | 47 | 1 | [2025-09-19] INITIAL: Start comprehensive copilot  |
+| copilot/fix-97 | 2025-09-19 | 47 | 1 | [2025-01-19] FINAL: Complete analysis document - T |
+| feature/full-next-migration | 2025-09-19 | 47 | 1 | update |
+| codex/resolve-netlify-deployment-issues | 2025-09-20 | 46 | 1 | Ensure Netlify build ignores CI warning mode |
+| codex/add-button-to-switch-to-math-brain | 2025-09-21 | 45 | 1 | Add return button from Poetic Brain to Math Brain |
+| codex/add-guard-for-conversation-intent-in-raven-route | 2025-09-21 | 45 | 1 | Merge branch 'main' into codex/add-guard-for-conve |
+| codex/add-guard-logic-to-raven-route | 2025-09-21 | 45 | 1 | Add Raven API guard for missing chart context |
+| codex/add-no-chart/report-guard-to-raven-route | 2025-09-21 | 45 | 1 | Merge branch 'main' into codex/add-no-chart/report |
+| codex/add-relocate-both-option-and-contact-toggle | 2025-09-21 | 45 | 1 | Merge branch 'main' into codex/add-relocate-both-o |
+| codex/adjust-jsx-for-authentication-handling | 2025-09-21 | 45 | 1 | Ensure login CTA shows when Poetic Brain disabled |
+| codex/find-gemini-api-usage-for-raven-calder | 2025-09-21 | 45 | 1 | Update Raven Calder system prompt with integrated  |
+| codex/fix-google-login-suppression-for-poetic-brain | 2025-09-21 | 45 | 1 | Switch PDF export to text-based generation and res |
+| codex/fix-google-login-suppression-for-poetic-brain-num1aq | 2025-09-21 | 45 | 1 | Merge branch 'main' into codex/fix-google-login-su |
+| codex/fix-issues-in-reports-structure | 2025-09-21 | 45 | 1 | Merge branch 'main' into codex/fix-issues-in-repor |
+| codex/fix-issues-in-reports-structure-d1qcoy | 2025-09-21 | 45 | 1 | Merge branch 'main' into codex/fix-issues-in-repor |
+| codex/fix-issues-in-reports-structure-dh2ypx | 2025-09-21 | 45 | 1 | Calibrate valence output to Balance Meter spec |
+| codex/fix-json-report-issues-and-improve-pdf-output | 2025-09-21 | 45 | 1 | Refine valence metrics and reporting scaffolding |
+| codex/fix-json-upload-handling-in-poetic-brain | 2025-09-21 | 45 | 1 | Clean up raven conversation comment |
+| codex/fix-netlify-publish-directory-configuration | 2025-09-21 | 45 | 1 | Configure Netlify publish directory |
+| codex/fix-netlify-publish-directory-configuration-3ow25v | 2025-09-21 | 45 | 1 | Fix Netlify function imports for astrology health |
+| codex/fix-netlify-publish-directory-configuration-4eb94r | 2025-09-21 | 45 | 1 | Merge branch 'main' into codex/fix-netlify-publish |
+| codex/fix-relocation-dropdown-menu-functionality | 2025-09-21 | 45 | 1 | Merge branch 'main' into codex/fix-relocation-drop |
+| codex/fix-syntax-error-in-woven-map-composer.js | 2025-09-21 | 45 | 1 | Fix woven map composer syntax regression |
+| codex/simplify-timezone-normalization-function | 2025-09-21 | 45 | 1 | Simplify timezone normalization |
+| codex/update-authenabled-case-insensitive-checks | 2025-09-21 | 45 | 1 | Normalize auth flag parsing |
+| codex/extend-detectintent-for-astroseek-responses | 2025-09-22 | 44 | 1 | Merge branch 'main' into codex/extend-detectintent |
+| codex/fix-500-internal-server-error-on-synastry | 2025-09-22 | 44 | 1 | Fix Both_local relocation handling and tests |
+| codex/fix-multiple-definitions-and-syntax-errors | 2025-09-21 | 44 | 1 | Merge branch 'main' into codex/fix-multiple-defini |
+| codex/fix-report-upload-error-in-raven-calder | 2025-09-22 | 44 | 1 | Fix Raven report context handling and guard copy |
+| codex/fix-syntax-error-in-chatclient.tsx | 2025-09-21 | 44 | 1 | Fix header JSX structure and close disabled export |
+| codex/investigate-navigation-and-report-errors | 2025-09-22 | 44 | 1 | Fix auth persistence and stabilize transit payload |
+| codex/investigate-server-side-500-error | 2025-09-22 | 44 | 1 | Handle uploaded report JSON in Raven API |
+| codex/refactor-guard-block-and-add-tests | 2025-09-22 | 44 | 1 | Add varied guard copy and tests |
+| codex/update-json-export-and-guidance-in-routes | 2025-09-22 | 44 | 1 | Merge branch 'main' into codex/update-json-export- |
+| codex/update-relational-menu-and-fix-date-input | 2025-09-22 | 44 | 1 | Improve relational type options and day input hand |
+| codex/update-relocation-options-in-transits-ui | 2025-09-22 | 44 | 1 | Add shared-city relocation summary and payload wir |
+| codex/clarify-symbolic-weather-constraints | 2025-09-23 | 43 | 1 | Align MirrorVoice output with activation-aware wea |
+| codex/enhance-poetic-brain-mobile-chat-experience | 2025-09-23 | 43 | 1 | Improve Poetic Brain mobile layout and clipboard s |
+| codex/fix-math-brain-error-on-balance-report | 2025-09-23 | 43 | 1 | Fix balance meter location requirement when only P |
+| codex/fix-poetic-brain-conversation-handling | 2025-09-22 | 43 | 1 | Allow conversational Raven responses without conte |
+| codex/simplify-raven-s-greeting-response | 2025-09-23 | 43 | 1 | Refine Raven greeting handling and header |
+| codex/update-buildmirrorvoice-for-data-checks | 2025-09-22 | 43 | 1 | Adjust MirrorVoice baseline handling |
+| codex/update-guidance-strings-for-json-export | 2025-09-23 | 43 | 1 | Update guard messaging for JSON export guidance |
+| codex/widen-no-context-guard-for-astroseek | 2025-09-23 | 43 | 1 | Expand AstroSeek guard coverage |
+| codex/add-include-transits-toggle-to-menu | 2025-09-23 | 42 | 1 | Simplify transit selection UI with include toggle |
+| codex/fix-report-generation-error | 2025-09-24 | 42 | 1 | Fix Math Brain readiness for compact transit days |
+| codex/fix-report-generation-error-p06sqz | 2025-09-24 | 42 | 1 | Fix Math Brain PDF export for balance reports |
+| codex/fix-report-issue-with-mirror_ready-flag | 2025-09-24 | 42 | 1 | Remove consent gating from mirror readiness |
+| codex/fix-response-to-engage-astrology-data | 2025-09-24 | 42 | 1 | Implement AstroSeek geometry parsing and richer mi |
+| codex/investigate-frozen-date-range-selection | 2025-09-24 | 42 | 1 | Fix Math Brain date range persistence and PDF down |
+| codex/investigate-solo-mirror-options-issue | 2025-09-24 | 42 | 1 | Hide relational report modes when Person B is disa |
+| codex/reinstate-report-fetching-for-raven-calder | 2025-09-24 | 42 | 1 | Restore Math Brain handoff data for Raven |
+| codex/fix-syntax-error-in-wrapupcard.tsx | 2025-09-26 | 40 | 1 | Fix WrapUpCard PDF export template |
+| codex/add-version-number-to-front-page | 2025-09-27 | 39 | 1 | Display deployment metadata on home page |
+| codex/fix-ios-mobile-chat-display-issue | 2025-09-27 | 39 | 1 | Fix chat stream height on mobile |
+| codex/fix-type-error-for-logevent | 2025-09-27 | 39 | 1 | Fix analytics helpers and rubric actions in wrap u |
+| codex/fix-unknown-deployment-status-message | 2025-09-27 | 39 | 1 | Improve deployment metadata fallback |
+| codex/add-reloclabel-parameter-to-extractreportheader | 2025-09-28 | 38 | 1 | Merge branch 'main' into codex/add-reloclabel-para |
+| codex/fix-import-issue-with-math-brain-session | 2025-09-28 | 38 | 1 | Auto-send Math Brain resume prompts |
+| codex/fix-netlify-deploy-failure-due-to-missing-dependencies | 2025-09-28 | 38 | 1 | Fix relocation label usage and add snapshot types |
+| codex/fix-netlify-deploy-module-not-found-error | 2025-09-28 | 38 | 1 | Add shared data normalizer helper |
+| codex/fix-report-self-invalidations-and-readiness-flags | 2025-09-28 | 38 | 1 | Add contract header snippet to report template |
+| codex/fix-syntax-error-in-page.tsx | 2025-09-28 | 38 | 1 | Fix relocation label handling in math brain report |
+| codex/fix-type-error-in-page.tsx | 2025-09-28 | 38 | 1 | Fix Math Brain transit flag ordering and Poetic Br |
+| codex/propose-pdf-report-format-for-users | 2025-09-28 | 38 | 1 | Refactor Math Brain to support dynamic report flow |
+| codex/refactor-poeticsnapshotcard-for-bold-markup | 2025-09-28 | 38 | 1 | Render bold emphasis without innerHTML in snapshot |
+| codex/set-default-date-range-to-today | 2025-09-28 | 38 | 1 | Set transit defaults to single-day window |
+| codex/fix-contract-validation-errors-for-mirrors | 2025-09-28 | 37 | 1 | Ensure contract payload carries window and locatio |
+| codex/fix-visibility-issue-in-poetic-brain-chat | 2025-09-28 | 37 | 1 | Fix chat layout collapsing when report context is  |
+| codex/check-sidereal-chart-support-in-api | 2025-09-30 | 36 | 1 | Add sidereal variant support for astrology proxy |
+| codex/fix-disappearing-date-picker-in-ios | 2025-09-30 | 36 | 1 | Fix iOS date picker dismissal on Math Brain |
+| codex/fix-missing-visual-graphs-in-pdf-download | 2025-09-30 | 36 | 1 | Add visual Balance Meter capture to graphs PDF exp |
+| codex/add-direct-json-export-alongside-pdf | 2025-10-02 | 34 | 1 | Add direct JSON downloads and append data appendix |
+| codex/fix-chat-visibility-issue-during-report-pull | 2025-10-02 | 34 | 1 | Fix auto handoff from Math Brain to chat |
+| codex/fix-generate-reports-button-functionality | 2025-10-02 | 34 | 1 | Fix relational report submit gating |
+| codex/fix-header-label-and-add-resume-button | 2025-10-01 | 34 | 1 | Adjust lens banner and restore resume session prom |
+| codex/fix-callback-url-mismatch-for-google-login | 2025-10-03 | 33 | 1 | Fix Auth0 redirect URI for math brain callback |
+| codex/fix-chat-visibility-on-ios-mobile | 2025-10-02 | 33 | 1 | Fix mobile chat visibility after loading context |
+| codex/update-scrolling-behavior-for-mobile | 2025-10-02 | 33 | 1 | Fix chat scrolling behavior on mobile |
+| codex/verify-api-key-exposure-in-repository | 2025-10-03 | 33 | 1 | Remove committed environment secrets |
+| copilot/fix-8edd74c6-9619-49c7-9e49-d0c4412b69b2 | 2025-10-04 | 32 | 1 | [2025-01-21] DOCS: Add implementation summary for  |
+| codex/fix-chat-message-clipping-issue | 2025-10-06 | 30 | 1 | Fix chat scroll padding and add sidebar exit |
+| codex/improve-chat-interface-on-ios | 2025-10-06 | 30 | 1 | Fix mobile chat layout scrolling and adjust offset |
+| codex/improve-chat-ui-for-mobile | 2025-10-06 | 30 | 1 | Fix chat composer layout |
+| codex/improve-chat-ui-for-mobile-mjw2qx | 2025-10-06 | 30 | 1 | Merge branch 'main' into codex/improve-chat-ui-for |
+| docs-project-overview | 2025-10-06 | 30 | 1 | docs: Create PROJECT_OVERVIEW.md summary |
+| fix-jsx-attribute-duplication-erro-ntl-68e38fd0a82e512055650732 | 2025-10-06 | 30 | 1 | Fix JSX attribute duplication error in ChatClient. |
+| fix-type-error-in-appmath-brainpag-ntl-68e42c975259e79a4a43fb39 | 2025-10-06 | 30 | 1 | Fix Type Error in app/math-brain/page.tsx for Netl |
+| fix-type-error-in-netlify-deploy-e-ntl-68e36cd73b140cd07ff47602 | 2025-10-06 | 30 | 1 | Fix Type Error in Netlify Deploy: Export 'SCALE_FA |
+
+### Recent Branches (Active Development)
+
+These branches are actively being worked on (< 30 days old):
+
+| Branch | Last Commit | Days Old | Behind Main | Subject |
+|--------|-------------|----------|-------------|---------|
+| codex/fix-callback-url-mismatch-in-auth0 | 2025-11-05 | 0 | 1 | Adjust Auth0 callback default to Math Brain |
+| codex/fix-overflow-detection-logic-in-balance-meter | 2025-11-05 | 0 | 1 | Fix balance meter overflow handling |
+| codex/fix-type-error-for-mandatediagnostic | 2025-11-05 | 0 | 1 | fix: import mandate diagnostic type |
+| codex/improve-poetic-brain-experience | 2025-11-05 | 0 | 1 | Fix Playwright CI port conflict when external serv |
+| copilot/create-mandate-translation-layer | 2025-11-05 | 0 | 1 | [2025-11-05] FIX: Remove duplicate directional_bia |
+| copilot/docsfield-relocation-ui-copy | 2025-11-05 | 0 | 1 | Initial plan |
+| copilot/fix-playwright-port-conflict | 2025-11-05 | 0 | 1 | Final verification complete |
+| copilot/review-outdated-branches | 2025-11-05 | 0 | 0 | Add implementation summary and regenerate report |
+| copilot/sub-pr-239 | 2025-11-04 | 0 | 1 | Fix: Remove missing test fixture and update test t |
+| copilot/sub-pr-252 | 2025-11-05 | 0 | 1 | Branch analysis: PR #252 Fix Placidus House Calcul |
+| copilot/sub-pr-265 | 2025-11-05 | 0 | 1 | Fix Playwright port conflict in CI by skipping web |
+| copilot/update-docs-field-relocation-ui | 2025-11-05 | 0 | 1 | docs: add FIELD vs Overlay UI copy and provenance  |
+| copilot/update-transit-overlay-documentation | 2025-11-05 | 0 | 1 | [2025-11-05] docs: Add FIELD vs Overlay UI copy an |
+| feat/srp-translocation | 2025-11-05 | 0 | 1 | feat: Implement Symbolic Resonance Protocol and Tr |
+| fix-initial-reading-trigger | 2025-11-05 | 0 | 0 | Fix: Correctly trigger initial report reading |
+| fix/balance-meter-overflow-boundary | 2025-11-05 | 0 | 1 | The overflow detection logic in the Balance Meter  |
+| fix/graceful-error-handling | 2025-11-05 | 0 | 1 | Initial plan (#257) |
+| fix/robust-house-cusp-extraction | 2025-11-05 | 0 | 1 | refactor: Make house cusp extraction more robust |
+| pr-review-1 | 2025-11-05 | 0 | 1 | Reviewed the PR and identified several issues. |
+| codex/fix-typescript-error-in-lib/devauth.ts | 2025-11-04 | 1 | 1 | Fix SRP example relative imports |
+| copilot/fix-osr-detection-error | 2025-11-04 | 1 | 1 | fix: restore corrupted useChartExport.ts file to v |
+| copilot/sub-pr-251 | 2025-11-04 | 1 | 1 | Initial plan |
+| fix/placidus-calculation-bug | 2025-11-04 | 1 | 1 | Fix: Correct Placidus house calculation algorithm |
+| code-review-balance-meter-v5 | 2025-11-03 | 2 | 1 | Reviewed and improved the Balance Meter v5.0 upgra |
+| fix/graceful-error-handling-v2-1 | 2025-11-03 | 2 | 1 | refactor: Improve error handling for composite cha |
+| jules-review-20251102-2 | 2025-11-03 | 2 | 1 | Reviewed the pull request and provided a summary o |
+| code-review-balance-meter-v5-1 | 2025-11-02 | 3 | 1 | feat: Add Golden Standard test for Balance Meter |
+| code-review/volatility-metric-removal | 2025-11-02 | 3 | 1 | Reviewed the refactoring of the deprecated `volati |
+| codex/fix-typescript-type-error-in-pingfeedback | 2025-11-02 | 3 | 1 | fix: allow ping feedback to handle unclear respons |
+| copilot/fix-typescript-syntax-error | 2025-11-02 | 3 | 1 | [2025-11-02] FIX: Add parentheses to nullish coale |
+| fix/raven-tests-and-cleanup | 2025-11-02 | 3 | 1 | Fix raven geometry test and remove dead code |
+| jules/remove-volatility-metric | 2025-11-02 | 3 | 1 | refactor: Remove deprecated volatility metric |
+| codex/fix-scoring-options-context-placement | 2025-10-31 | 4 | 1 | Adjust Raven upload summary to delay resonance pro |
+| codex/improve-raven-s-response-modes | 2025-11-01 | 4 | 1 | Merge pull request #237 from DHCross/feat/raw-expo |
+| codex/improve-session-flow-in-poetic-brain | 2025-11-01 | 4 | 1 | Refresh onboarding copy for automatic session star |
+| copilot/sub-pr-230 | 2025-11-01 | 4 | 1 | Initial plan |
+| feat/raw-export | 2025-11-01 | 4 | 1 | feat: Add createRawExport function |
+| feature/code-review | 2025-11-01 | 4 | 1 | Reviewed pull request, summarizing key changes, id |
+| fix/remove-dead-code | 2025-11-01 | 4 | 1 | Remove unused `createRawExport` function |
+| jules-math-brain-refactor | 2025-11-01 | 4 | 1 | Refactor Math Brain orchestrator and fix failing t |
+| jules-timeless-report-fix | 2025-11-01 | 4 | 1 | Fix: Add default date range for timeless reports |
+| jules-timeless-report-fix-1 | 2025-11-01 | 4 | 1 | refactor: Remove deprecated volatility metric from |
+| refactor-relational-summary | 2025-11-01 | 4 | 1 | Refactor: Improve clarity and structure of compute |
+| remove-bundle-download | 2025-11-01 | 4 | 1 | Merge pull request #234 from DHCross/remove-deprec |
+| remove-deprecated-volatility-metric | 2025-11-01 | 4 | 1 | Merge pull request #235 from DHCross/jules-timeles |
+| feature/display-relational-summary | 2025-10-30 | 6 | 1 | feat: Display relational summary in Markdown repor |
+| fix-legacy-balance-meter-exports | 2025-10-30 | 6 | 1 | fix(reports): Correct Balance Meter values in lega |
+| fix-netlify-build-error | 2025-10-30 | 6 | 1 | Fixes a TypeScript build error that occurred durin |
+| fix/docs-ascendant-formula | 2025-10-30 | 6 | 1 | docs: Correct Ascendant formula in primary referen |
+| codex/summarize-lighthouse-performance-report | 2025-10-27 | 9 | 1 | Add Lighthouse performance summary report |
+| fix-raven-chat-auth | 2025-10-27 | 9 | 1 | Refactor: Move glossary to a separate page |
+| fix/relocation-calculations | 2025-10-27 | 9 | 1 | Merge branch 'main' into fix/relocation-calculatio |
+| codex/add-option-to-download-zipfile-bundle | 2025-10-26 | 10 | 1 | Add AI bundle ZIP export for Poetic Brain |
+| codex/fix-usability-issues-on-chat-page | 2025-10-26 | 10 | 1 | Fix chat navigation and sticky layout behavior |
+| fix-balance-meter-schema | 2025-10-26 | 10 | 1 | feat: Upgrade Balance Meter to v5.0 |
+| fix/placidus-calculation | 2025-10-26 | 10 | 1 | Fix: Correct Placidus house calculation |
+| jules/audit-fixes | 2025-10-26 | 10 | 1 | Fix: Correct critical bugs in core logic and add t |
+| refactor-seismograph-v5 | 2025-10-26 | 10 | 1 | refactor: Align Seismograph and Prompts with v5.0  |
+| test-coverage-improvements | 2025-10-25 | 11 | 1 | feat: Improve test coverage for mathbrain adapter |
+| fix-garbled-download-filename | 2025-10-23 | 13 | 1 | fix(math-brain): Correctly process relational repo |
+| fix/relocation-docs | 2025-10-23 | 13 | 1 | Fix: Correct relocation pseudo-code in design docs |
+| fix/relocation-houses-bugs | 2025-10-23 | 13 | 1 | Fix: Correct Placidus house calculation and normal |
+| spec-v5-unification | 2025-10-23 | 13 | 1 | Update BALANCE_METER_README.md |
+| agent-deployment-8f47 | 2025-10-22 | 14 | 1 | Fix Type Error in useChartExport.ts for Netlify De |
+| feature/consolidate-poetic-brain-output | 2025-10-19 | 17 | 1 | Refactor: Consolidate Poetic Brain output into a s |
+| copilot/add-astrology-mathbrain-api | 2025-10-18 | 18 | 1 | Fix longitude display bug in verification test |
+| feat/perplexity-persona-hook | 2025-10-18 | 18 | 1 | feat(llm): Align Perplexity API with persona requi |
+| fix-mobile-download | 2025-10-18 | 18 | 1 | Merge main into fix-mobile-download, resolve confl |
+| feat/performance-optimizations | 2025-10-17 | 19 | 1 | Feat: Optimize WovenWebApp performance |
+| fix/balance-meter-export-zeros | 2025-10-17 | 19 | 1 | fix(export): Correct rounding in Balance Meter JSO |
+| fix/gemini-api-compliance | 2025-10-17 | 19 | 1 | fix: Implement Gemini API compliance and robustnes |
+| perf-improvements | 2025-10-17 | 19 | 1 | feat: Implement performance optimizations |
+| chore/remove-legacy-balance-meter-code | 2025-10-15 | 21 | 1 | Refactor: Remove dead code from Balance Meter |
+| codex/fix-report-generation-error-in-math-brain-v2 | 2025-10-15 | 21 | 1 | Fix Math Brain v2 filename sanitization |
+| codex/fix-report-generation-in-v2 | 2025-10-15 | 21 | 1 | Restore legacy seismograph fields for v2 exports |
+| docs/update-v5-balance-meter-docs | 2025-10-15 | 21 | 1 | Fixes a build failure caused by a dangling import  |
+| refactor/remove-legacy-metrics | 2025-10-15 | 21 | 1 | Refactor: Remove legacy Coherence, Volatility, and |
+| copilot/fix-magnitudeavg-definition | 2025-10-11 | 25 | 1 | [2025-10-11] DOCS: Add documentation for magnitude |
+| copilot/fix-missing-export-assertnotdoubleinverted | 2025-10-09 | 27 | 1 | Fix SPEC_VERSION and finalize assertNotDoubleInver |
+| fix-typescript-type-error-in-weath-ntl-68e6a7e2c587bf7a1fa0df2a | 2025-10-08 | 28 | 1 | Fix TypeScript type error in WeatherPlots.tsx at l |
+| codex/fix-504-gateway-timeout-error | 2025-10-07 | 29 | 1 | Handle empty synastry responses gracefully |
+| codex/fix-codex-review-issues-for-pr-#187 | 2025-10-07 | 29 | 1 | Fix display-scale detection for volatility and coh |
+| codex/fix-scaling-issues-in-weather-data-pipeline | 2025-10-07 | 29 | 1 | Merge pull request #189 from DHCross/codex/fix-cod |
+
+## How to Delete Branches
+
+### Delete a single branch:
+```bash
+git push origin --delete <branch-name>
+```
+
+### Delete multiple branches (example):
+```bash
+# Delete merged branches
+```
diff --git a/BRANCH_MANAGEMENT.md b/BRANCH_MANAGEMENT.md
new file mode 100644
index 00000000..119fb523
--- /dev/null
+++ b/BRANCH_MANAGEMENT.md
@@ -0,0 +1,212 @@
+# Branch Management Guidelines
+
+This document provides guidelines for managing branches in the WovenWebApp repository.
+
+## Overview
+
+The WovenWebApp repository uses a branch-based workflow for feature development, bug fixes, and code reviews. Over time, branches can accumulate and become outdated. This guide helps identify which branches should be closed or deleted.
+
+## Branch Analysis Tool
+
+We provide an automated tool to analyze all branches and categorize them based on their status.
+
+### Running the Analysis
+
+```bash
+npm run branches:analyze
+```
+
+This will:
+1. Fetch all remote branches from GitHub
+2. Analyze each branch's status relative to `main`
+3. Generate a report: `BRANCH_ANALYSIS_REPORT.md`
+
+### What the Tool Checks
+
+The tool examines:
+- **Merge status**: Whether the branch has been merged into `main`
+- **Age**: Days since the last commit
+- **Divergence**: How many commits behind `main` the branch is
+- **Branch naming patterns**: Identifies temporary fix branches, feature branches, etc.
+
+## Branch Categories
+
+### 1. Merged Branches (Safe to Delete)
+**Priority**: High
+
+These branches have been merged into `main` and can be safely deleted without losing any code.
+
+**Action**: Delete immediately
+```bash
+git push origin --delete <branch-name>
+```
+
+### 2. Stale Branches (90+ Days Old)
+**Priority**: Medium
+
+Branches that haven't been updated in 90+ days are likely abandoned or no longer relevant.
+
+**Action**: 
+1. Review the branch purpose (check PR or commit messages)
+2. If no longer needed, delete the branch
+3. If still relevant, consider rebasing on `main` and creating a new PR
+
+### 3. Outdated Branches (60+ Days, Behind Main)
+**Priority**: Low
+
+Branches that are significantly behind `main` and haven't been updated recently.
+
+**Action**:
+1. Review if the work is still relevant
+2. Consider closing the associated PR/issue
+3. If work should continue, rebase on `main` or create a fresh branch
+
+### 4. Work in Progress (30-90 Days)
+**Priority**: Review Required
+
+Active development that may have stalled.
+
+**Action**:
+1. Check with the branch author or PR assignee
+2. Determine if work will continue
+3. Update or close accordingly
+
+### 5. Recent Branches (< 30 Days)
+**Priority**: Keep
+
+Active development branches.
+
+**Action**: Monitor but keep
+
+## Branch Naming Conventions
+
+Our repository uses several naming patterns:
+
+- `codex/*` - Codex-generated branches (AI assistant work)
+- `copilot/*` - GitHub Copilot-generated branches
+- `feature/*` - New features
+- `fix/*` - Bug fixes
+- `chore/*` - Maintenance tasks
+- `docs/*` - Documentation updates
+- `refactor/*` - Code refactoring
+- `test/*` - Test improvements
+
+## Deletion Guidelines
+
+### Before Deleting a Branch
+
+1. **Verify merge status**: Ensure the branch is merged or no longer needed
+2. **Check for open PRs**: Close or update any associated pull requests
+3. **Review with team**: For major features, confirm with the team
+4. **Document decision**: Update relevant issues or PRs with the reason
+
+### How to Delete Branches
+
+#### Delete a Single Remote Branch
+```bash
+git push origin --delete <branch-name>
+```
+
+#### Delete Multiple Branches (Script)
+Create a temporary script for bulk deletion:
+
+```bash
+#!/bin/bash
+# delete-branches.sh
+branches=(
+  "branch-name-1"
+  "branch-name-2"
+  "branch-name-3"
+)
+
+for branch in "${branches[@]}"; do
+  echo "Deleting $branch..."
+  git push origin --delete "$branch"
+done
+```
+
+#### Delete Local Tracking Branches
+After deleting remote branches, clean up local references:
+
+```bash
+git fetch --prune
+git branch -vv | grep ': gone]' | awk '{print $1}' | xargs git branch -d
+```
+
+## Automated Cleanup
+
+### GitHub Branch Protection Rules
+
+Consider enabling automatic branch deletion for merged PRs:
+1. Go to repository Settings → Branches
+2. Enable "Automatically delete head branches"
+
+This will delete branches automatically after PR merge.
+
+## Best Practices
+
+### For Contributors
+
+1. **Keep branches short-lived**: Aim to merge within 2-4 weeks
+2. **Regular updates**: Rebase on `main` regularly to avoid drift
+3. **Clean up after merge**: Delete your branch after successful merge
+4. **Meaningful names**: Use descriptive branch names that indicate purpose
+5. **Close unused branches**: Don't leave experimental branches hanging
+
+### For Maintainers
+
+1. **Regular reviews**: Run the analysis tool monthly
+2. **Proactive cleanup**: Delete merged branches promptly
+3. **Communication**: Notify contributors before deleting their branches
+4. **Documentation**: Keep this guide updated with new patterns
+
+## Monthly Maintenance Checklist
+
+- [ ] Run `npm run branches:analyze`
+- [ ] Review the generated report
+- [ ] Delete all merged branches (high priority)
+- [ ] Contact owners of stale branches (90+ days)
+- [ ] Close PRs associated with abandoned branches
+- [ ] Update this document if new patterns emerge
+
+## Common Scenarios
+
+### Scenario 1: Codex/Copilot Branches
+Many `codex/*` and `copilot/*` branches are temporary AI-assisted fixes.
+
+**Action**: If merged or older than 60 days without activity, delete them.
+
+### Scenario 2: Feature Branch Conflicts
+A feature branch is heavily outdated but work should continue.
+
+**Action**: 
+1. Create a new branch from `main`
+2. Cherry-pick or reapply changes
+3. Delete the old branch
+4. Update PR to point to new branch
+
+### Scenario 3: Experimental Work
+A branch contains experimental code that didn't pan out.
+
+**Action**:
+1. If valuable for future reference, tag it before deletion
+2. Document findings in an issue
+3. Delete the branch
+
+## Questions?
+
+If you're unsure about deleting a branch:
+1. Check the associated PR or issue
+2. Contact the repository maintainer (Jules/DHCross)
+3. When in doubt, keep it for one more review cycle
+
+## Related Documents
+
+- `README.md` - General setup and contribution guidelines
+- `CHANGELOG.md` - Project history
+- `MAINTENANCE_GUIDE.md` - General maintenance procedures
+
+---
+
+Last updated: 2025-11-05
+Tool version: 1.0
diff --git a/README.md b/README.md
index 799e8ec6..24a3230c 100644
--- a/README.md
+++ b/README.md
@@ -45,6 +45,29 @@ npm run dev
 
 Visit [http://localhost:3000](http://localhost:3000)
 
+### Useful Scripts
+
+```bash
+# Development
+npm run dev                  # Start development server
+npm run build                # Build for production
+npm run start                # Start production server
+
+# Testing
+npm run test                 # Run tests
+npm run test:e2e            # Run end-to-end tests
+npm run smoke:golden        # Run golden standard tests
+
+# Maintenance
+npm run branches:analyze    # Analyze and categorize all branches
+npm run lexicon:lint        # Check voice compliance
+npm run validate:fieldmap   # Validate field mappings
+
+# Environment
+npm run check-env           # Verify .env configuration
+npm run auth:check          # Validate Auth0 configuration
+```
+
 ---
 
 ## 📚 Documentation Navigation
@@ -68,6 +91,7 @@ Visit [http://localhost:3000](http://localhost:3000)
 
 ### 🔧 Maintenance & Troubleshooting
 - **Maintenance Guide:** [Developers Notes/Lessons Learned/MAINTENANCE_GUIDE.md](Developers%20Notes/Lessons%20Learned/MAINTENANCE_GUIDE.md)
+- **Branch Management:** [BRANCH_MANAGEMENT.md](BRANCH_MANAGEMENT.md) - Tool for identifying outdated branches
 - **Emergency Recovery:** [Developers Notes/Lessons Learned/copilot_fix_recovery.md](Developers%20Notes/Lessons%20Learned/copilot_fix_recovery.md)
 - **Deployment Troubleshooting:** [DEPLOYMENT_TROUBLESHOOTING.md](DEPLOYMENT_TROUBLESHOOTING.md)
 
diff --git a/package.json b/package.json
index bb7e207e..4b174bbe 100644
--- a/package.json
+++ b/package.json
@@ -49,7 +49,8 @@
     "postinstall": "if [ -f package.json ] && node -e \"try{require('concurrently')}catch(e){process.exit(1)}\"; then echo 'concurrently already installed'; else echo 'Installing concurrently...'; npm i -D concurrently; fi",
     "auth:check": "node scripts/auth-config-check.js",
     "lexicon:lint": "node scripts/lexicon-lint.mjs",
-    "validate:fieldmap": "node scripts/validate-fieldmap-v5.js"
+    "validate:fieldmap": "node scripts/validate-fieldmap-v5.js",
+    "branches:analyze": "node scripts/analyze-branches.js"
   },
   "dependencies": {
     "@google/generative-ai": "^0.24.1",
diff --git a/scripts/analyze-branches.js b/scripts/analyze-branches.js
new file mode 100755
index 00000000..9722aea3
--- /dev/null
+++ b/scripts/analyze-branches.js
@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+
+/**
+ * Branch Analysis Tool for WovenWebApp
+ * 
+ * This script analyzes all branches in the repository and identifies:
+ * 1. Branches that have been merged into main
+ * 2. Branches that are outdated (behind main by many commits)
+ * 3. Branches with old last commit dates
+ * 4. Branches that appear to be stale feature/fix branches
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+
+function exec(cmd) {
+  try {
+    return execSync(cmd, { encoding: 'utf-8', cwd: process.cwd() }).trim();
+  } catch (error) {
+    return '';
+  }
+}
+
+function getBranchInfo() {
+  console.log('Fetching branch information from GitHub...\n');
+  
+  // Get all remote branches with details
+  const branchesRaw = exec(
+    'git for-each-ref --format="%(refname:short)|%(committerdate:iso8601)|%(authorname)|%(subject)" refs/remotes/origin/'
+  );
+  
+  if (!branchesRaw) {
+    console.error('Error: Could not fetch branch information');
+    return [];
+  }
+  
+  const branches = branchesRaw
+    .split('\n')
+    .filter(line => line && !line.includes('HEAD'))
+    .map(line => {
+      const [name, date, author, subject] = line.split('|');
+      return {
+        name: name.replace('origin/', ''),
+        date: new Date(date),
+        author,
+        subject,
+        fullName: name
+      };
+    });
+  
+  return branches;
+}
+
+function getMainCommitDate() {
+  const dateStr = exec('git log main -1 --format="%ci"');
+  return new Date(dateStr);
+}
+
+function isMergedIntoMain(branchName) {
+  const result = exec(`git branch -r --merged main | grep "origin/${branchName}$"`);
+  return result.length > 0;
+}
+
+function getCommitsBehindMain(branchName) {
+  try {
+    const result = exec(`git rev-list --count main..origin/${branchName}`);
+    const ahead = parseInt(result) || 0;
+    const behindResult = exec(`git rev-list --count origin/${branchName}..main`);
+    const behind = parseInt(behindResult) || 0;
+    return { ahead, behind };
+  } catch (error) {
+    return { ahead: 0, behind: 0 };
+  }
+}
+
+function categorizeBranches(branches, mainDate) {
+  const now = new Date();
+  const thirtyDaysAgo = new Date(now - 30 * 24 * 60 * 60 * 1000);
+  const sixtyDaysAgo = new Date(now - 60 * 24 * 60 * 60 * 1000);
+  const ninetyDaysAgo = new Date(now - 90 * 24 * 60 * 60 * 1000);
+  
+  const categories = {
+    merged: [],
+    stale: [],
+    outdated: [],
+    recent: [],
+    workInProgress: []
+  };
+  
+  branches.forEach(branch => {
+    // Skip main branch
+    if (branch.name === 'main') {
+      return;
+    }
+    
+    const merged = isMergedIntoMain(branch.name);
+    const { ahead, behind } = getCommitsBehindMain(branch.name);
+    const daysSinceCommit = Math.floor((now - branch.date) / (1000 * 60 * 60 * 24));
+    
+    const branchInfo = {
+      ...branch,
+      daysSinceCommit,
+      ahead,
+      behind,
+      merged
+    };
+    
+    if (merged) {
+      categories.merged.push(branchInfo);
+    } else if (branch.date < ninetyDaysAgo) {
+      categories.stale.push(branchInfo);
+    } else if (behind > 50 && branch.date < sixtyDaysAgo) {
+      categories.outdated.push(branchInfo);
+    } else if (branch.date > thirtyDaysAgo) {
+      categories.recent.push(branchInfo);
+    } else {
+      categories.workInProgress.push(branchInfo);
+    }
+  });
+  
+  return categories;
+}
+
+function formatDate(date) {
+  return date.toISOString().split('T')[0];
+}
+
+function generateReport(categories) {
+  const report = [];
+  
+  report.push('# Branch Analysis Report');
+  report.push(`Generated: ${new Date().toISOString()}`);
+  report.push('');
+  
+  // Summary
+  report.push('## Summary');
+  report.push('');
+  report.push(`- **Merged branches (safe to delete):** ${categories.merged.length}`);
+  report.push(`- **Stale branches (90+ days old):** ${categories.stale.length}`);
+  report.push(`- **Outdated branches (behind main, 60+ days):** ${categories.outdated.length}`);
+  report.push(`- **Work in progress (30-90 days):** ${categories.workInProgress.length}`);
+  report.push(`- **Recent branches (< 30 days):** ${categories.recent.length}`);
+  report.push('');
+  
+  // Recommendations
+  report.push('## Recommendations');
+  report.push('');
+  report.push('### High Priority: Branches to Delete');
+  report.push('');
+  report.push('These branches have been merged into main and can be safely deleted:');
+  report.push('');
+  
+  if (categories.merged.length === 0) {
+    report.push('*No merged branches found.*');
+  } else {
+    report.push('| Branch | Last Commit | Days Old | Behind Main |');
+    report.push('|--------|-------------|----------|-------------|');
+    categories.merged
+      .sort((a, b) => b.daysSinceCommit - a.daysSinceCommit)
+      .forEach(branch => {
+        report.push(`| ${branch.name} | ${formatDate(branch.date)} | ${branch.daysSinceCommit} | ${branch.behind} |`);
+      });
+  }
+  report.push('');
+  
+  // Stale branches
+  report.push('### Medium Priority: Stale Branches (90+ days old)');
+  report.push('');
+  report.push('These branches haven\'t been updated in 90+ days. Review if they\'re still needed:');
+  report.push('');
+  
+  if (categories.stale.length === 0) {
+    report.push('*No stale branches found.*');
+  } else {
+    report.push('| Branch | Last Commit | Days Old | Behind Main | Subject |');
+    report.push('|--------|-------------|----------|-------------|---------|');
+    categories.stale
+      .sort((a, b) => b.daysSinceCommit - a.daysSinceCommit)
+      .forEach(branch => {
+        const subject = branch.subject.substring(0, 50);
+        report.push(`| ${branch.name} | ${formatDate(branch.date)} | ${branch.daysSinceCommit} | ${branch.behind} | ${subject} |`);
+      });
+  }
+  report.push('');
+  
+  // Outdated branches
+  report.push('### Low Priority: Outdated Branches');
+  report.push('');
+  report.push('These branches are behind main and older than 60 days. Consider rebasing or closing:');
+  report.push('');
+  
+  if (categories.outdated.length === 0) {
+    report.push('*No outdated branches found.*');
+  } else {
+    report.push('| Branch | Last Commit | Days Old | Behind Main | Subject |');
+    report.push('|--------|-------------|----------|-------------|---------|');
+    categories.outdated
+      .sort((a, b) => b.behind - a.behind)
+      .forEach(branch => {
+        const subject = branch.subject.substring(0, 50);
+        report.push(`| ${branch.name} | ${formatDate(branch.date)} | ${branch.daysSinceCommit} | ${branch.behind} | ${subject} |`);
+      });
+  }
+  report.push('');
+  
+  // Work in progress
+  report.push('### Work in Progress (Review Needed)');
+  report.push('');
+  report.push('These branches are 30-90 days old. Review their status:');
+  report.push('');
+  
+  if (categories.workInProgress.length === 0) {
+    report.push('*No work-in-progress branches found.*');
+  } else {
+    report.push('| Branch | Last Commit | Days Old | Behind Main | Subject |');
+    report.push('|--------|-------------|----------|-------------|---------|');
+    categories.workInProgress
+      .sort((a, b) => b.daysSinceCommit - a.daysSinceCommit)
+      .forEach(branch => {
+        const subject = branch.subject.substring(0, 50);
+        report.push(`| ${branch.name} | ${formatDate(branch.date)} | ${branch.daysSinceCommit} | ${branch.behind} | ${subject} |`);
+      });
+  }
+  report.push('');
+  
+  // Recent branches
+  report.push('### Recent Branches (Active Development)');
+  report.push('');
+  report.push('These branches are actively being worked on (< 30 days old):');
+  report.push('');
+  
+  if (categories.recent.length === 0) {
+    report.push('*No recent branches found.*');
+  } else {
+    report.push('| Branch | Last Commit | Days Old | Behind Main | Subject |');
+    report.push('|--------|-------------|----------|-------------|---------|');
+    categories.recent
+      .sort((a, b) => a.daysSinceCommit - b.daysSinceCommit)
+      .forEach(branch => {
+        const subject = branch.subject.substring(0, 50);
+        report.push(`| ${branch.name} | ${formatDate(branch.date)} | ${branch.daysSinceCommit} | ${branch.behind} | ${subject} |`);
+      });
+  }
+  report.push('');
+  
+  // Instructions
+  report.push('## How to Delete Branches');
+  report.push('');
+  report.push('### Delete a single branch:');
+  report.push('```bash');
+  report.push('git push origin --delete <branch-name>');
+  report.push('```');
+  report.push('');
+  report.push('### Delete multiple branches (example):');
+  report.push('```bash');
+  report.push('# Delete merged branches');
+  if (categories.merged.length > 0) {
+    const exampleBranches = categories.merged.slice(0, 3).map(b => b.name);
+    exampleBranches.forEach(name => {
+      report.push(`git push origin --delete ${name}`);
+    });
+  }
+  report.push('```');
+  report.push('');
+  
+  return report.join('\n');
+}
+
+// Main execution
+console.log('WovenWebApp Branch Analysis Tool');
+console.log('=================================\n');
+
+try {
+  // Ensure we have the latest from origin
+  console.log('Fetching latest changes from origin...');
+  exec('git fetch --all --prune');
+  
+  const branches = getBranchInfo();
+  console.log(`Found ${branches.length} remote branches\n`);
+  
+  const mainDate = getMainCommitDate();
+  console.log(`Main branch last updated: ${formatDate(mainDate)}\n`);
+  
+  console.log('Analyzing branches (this may take a moment)...\n');
+  const categories = categorizeBranches(branches, mainDate);
+  
+  const report = generateReport(categories);
+  
+  // Write report to file
+  const reportPath = 'BRANCH_ANALYSIS_REPORT.md';
+  fs.writeFileSync(reportPath, report);
+  
+  console.log(`Report generated: ${reportPath}\n`);
+  console.log('Quick Summary:');
+  console.log(`  - Merged (can delete): ${categories.merged.length}`);
+  console.log(`  - Stale (90+ days): ${categories.stale.length}`);
+  console.log(`  - Outdated (60+ days): ${categories.outdated.length}`);
+  console.log(`  - Work in progress: ${categories.workInProgress.length}`);
+  console.log(`  - Recent: ${categories.recent.length}`);
+  console.log(`\nSee ${reportPath} for detailed information.`);
+  
+} catch (error) {
+  console.error('Error analyzing branches:', error.message);
+  process.exit(1);
+}