numerology/README.md

# Numerology Calculator

A comprehensive TypeScript-based numerology calculator with **10 specialized tools** for deep numerological analysis. Calculate core numbers, find optimal days, analyze relationships, optimize names for master numbers, and integrate with the Telos personal development framework.

**Built with Bun + TypeScript. Zero dependencies. Professional-grade calculations and interpretations.**

## Features

### Core Calculations
- **Life Path Number** - Your life's purpose and journey
- **Expression Number** - Your natural talents and abilities
- **Soul Urge Number** - Your inner desires and motivations
- **Birthday Number** - Special gifts from your birth day
- **Advanced Numbers** - Maturity, Personality, Hidden Passion, Karmic Lessons, Balance
- **Master Number Detection** - Automatically identifies 11, 22, and 33

### Timing & Cycles
- **Personal Cycles** - Year/Month/Day calculations for strategic planning
- **Universal Cycles** - Current world energy influences
- **Optimal Days Finder** - Find best days for launches, creative work, business deals
- **Year-Ahead Calendar** - 12-month Personal Month preview
- **Life Pinnacles** - 4 major life stages with challenge numbers

### Analysis Tools
- **Compatibility Analysis** - Compare charts for romantic, business, family, or friendship relationships
- **Name Change Analyzer** - Test how nicknames, stage names, or married names shift your energy
- **Name Optimizer** 🔮 - "Rainbow tables" for finding master number variations (90+ name tests)
- **Telos Integration** - Weekly planner aligning personal goals with daily numerology energy

### Output & Formats
- **Multiple Output Formats** - Terminal (with colors), Markdown, JSON
- **Detailed Interpretations** - Comprehensive meanings for every number
- **Professional Reports** - Ready for clients or personal deep-dive analysis

## Core Numbers Explained

### Life Path Number
Calculated from your complete birthdate (month + day + year), this is your primary number representing your life's purpose, the path you're meant to walk, and the lessons you're here to learn.

### Expression Number
Calculated from your full name, this represents your natural talents, abilities, and the tools you have to fulfill your Life Path. It's what you're naturally good at.

### Soul Urge Number
Calculated from the vowels in your name, this represents your inner desires, motivations, and what truly drives you at a soul level.

### Birthday Number
Calculated from your day of birth, this represents special gifts and talents you were born with. It's a modifier that adds nuance to your other numbers.

## Installation

```bash
git clone [your-repo-url]
cd numerology
# No dependencies to install - uses Bun's native TypeScript support!
```

## Profile Management ⭐ NEW

Save your numerology profile once and reuse it across all tools. No more typing your name and birthdate every time!

### Create a Profile

```bash
# Auto-generate profile ID from first name
bun profile.ts create --name "John Smith" --birthdate "3/15/1990"
# → Creates profile 'john'

# Custom profile ID
bun profile.ts create johns --name "John Smith" --birthdate "3/15/1990"
```

### Manage Profiles

```bash
# List all profiles
bun profile.ts list

# Show profile details
bun profile.ts show rob

# Delete a profile
bun profile.ts delete rob
```

### Use Profiles Everywhere

Once created, use `--profile` flag with any tool:

```bash
# Main calculator
bun numerology.ts --profile john --detailed --advanced --cycles

# PDF Report generator
bun generate-report.ts --profile john

# Compatibility analysis
bun compatibility.ts --profile john --person2 "Jane:1/1/1990"

# Optimal days finder
bun optimal-days.ts --profile john --day 1

# Year-ahead calendar
bun year-ahead.ts --profile john

# And all other tools...
```

**Benefits:**
- Save multiple profiles (you, partner, family, clients)
- No more retyping name/birthdate
- Consistent data across all tools
- Profiles stored in `~/.numerology/profiles/`

## Usage

### Basic Calculation

```bash
# Terminal output with colors
bun numerology.ts --name "John Doe" --birthdate "5/13/1982"

# Detailed terminal output
bun numerology.ts --name "John Doe" --birthdate "5/13/1982" --detailed
```

### Output Formats

```bash
# Markdown format
bun numerology.ts --name "Jane Smith" --birthdate "11/22/1990" --format markdown

# JSON format
bun numerology.ts --name "Bob Jones" --birthdate "3/14/1975" --format json

# Save to file
bun numerology.ts --name "Alice Wonder" --birthdate "7/7/1977" --format markdown > profile.md
```

### Timing Cycles

Calculate your Personal and Universal timing cycles:

```bash
# Show today's cycles
bun numerology.ts --name "Your Name" --birthdate "mm/dd/yyyy" --cycles

# Check cycles for specific date
bun numerology.ts --name "Your Name" --birthdate "mm/dd/yyyy" --cycles --date "12/25/2025"

# Detailed chart + cycles
bun numerology.ts --name "Your Name" --birthdate "mm/dd/yyyy" --detailed --cycles
```

### Telos Integration

#### Export Numerology Profile

Generate telos-formatted numerology profile:

```bash
# Export numerology profile
bun telos-export.ts --name "Your Name" --birthdate "mm/dd/yyyy" > ~/.claude/context/personal/telos/numerology.md
```

#### Weekly Planner

Align your telos goals with Personal Day cycles for optimal timing:

```bash
# Generate this week's planner
bun telos-week.ts --name "Your Name" --birthdate "mm/dd/yyyy"

# Plan specific week
bun telos-week.ts --name "Your Name" --birthdate "mm/dd/yyyy" --week-start "10/14/2025"

# Use custom telos file
bun telos-week.ts --name "Your Name" --birthdate "mm/dd/yyyy" --telos-file ~/my-telos.md
```

**Example Output:**
```
╔════════════════════════════════════════════════════════════════╗
║  📅 YOUR WEEK AHEAD (10/14-20, 2025)                          ║
╚════════════════════════════════════════════════════════════════╝

Monday, October 14 - Personal Day 3
═══════════════════════════════════════════════════════════════
🎨 ENERGY: Expression, Creativity, Communication

🎯 TELOS GOAL ALIGNMENT (High Priority):
   ✅ G2: Provide education materials
   ✅ PJ3: Content creation and social media

⚠️  AVOID TODAY:
   ❌ Deep analytical work (save for Day 7)
   ❌ Heavy organizational tasks (save for Day 4)
```

This integrates with the [Telos personal development framework](https://danielmiessler.com/p/telos/).

## Command Line Options

### numerology.ts

```
--name NAME          Full name (required)
--birthdate DATE     Birthdate in mm/dd/yyyy format (required)
--format FORMAT      Output format: terminal, markdown, json (default: terminal)
--detailed, -d       Show detailed meanings (terminal format only)
--cycles, -c         Include timing cycles (Personal Year/Month/Day)
--date DATE          Specific date for cycles (mm/dd/yyyy) [default: today]
--help, -h           Show help message
```

### telos-export.ts

```
--name NAME          Full name (required)
--birthdate DATE     Birthdate in mm/dd/yyyy format (required)
--help, -h           Show help message
```

### telos-week.ts

```
--name NAME          Full name (required)
--birthdate DATE     Birthdate in mm/dd/yyyy format (required)
--week-start DATE    Week start date (mm/dd/yyyy) [default: next Monday]
--telos-file PATH    Path to telos.md file [default: ~/.claude/context/personal/telos/telos.md]
--help, -h           Show help message
```

### optimal-days.ts ✨ NEW

```
--birthdate DATE     Your birthdate (mm/dd/yyyy) [required]
--month NUMBER       Month to search (1-12) [optional - searches whole year if omitted]
--year NUMBER        Year to search [default: current year]
--day NUMBER         Target Personal Day number (1-9, 11, 22, 33)
--activity NAME      Activity type (new, creative, business, study, etc.) [optional]
--help, -h           Show help message
```

### pinnacles.ts ✨ NEW

```
--birthdate DATE     Your birthdate (mm/dd/yyyy) [required]
--name NAME          Your name [optional - for context]
--help, -h           Show help message
```

### compatibility.ts ✨ NEW

```
--person1, --p1      First person (format: "Name:mm/dd/yyyy") [required]
--person2, --p2      Second person (format: "Name:mm/dd/yyyy") [required]
--type, -t           Relationship type: general, romantic, business, family, friendship [default: general]
--help, -h           Show help message
```

### year-ahead.ts ✨ NEW

```
--birthdate DATE     Your birthdate (mm/dd/yyyy) [required]
--year NUMBER        Year to preview [default: current year]
--name NAME          Your name [optional - for personalized output]
--help, -h           Show help message
```

### advanced-numbers.ts ✨ NEW

```
--name NAME          Your full name [required]
--birthdate DATE     Your birthdate (mm/dd/yyyy) [required]
--detailed, -d       Show detailed interpretations
--help, -h           Show help message
```

### name-change.ts ✨ NEW

```
--birthdate DATE         Your birthdate (mm/dd/yyyy) [required]
--current NAME           Your current/legal name [required]
--alternative NAME       Alternative name to compare [can use multiple times]
--help, -h               Show help message
```

### name-optimizer.ts 🔮 NEW

```
--birthdate DATE         Your birthdate (mm/dd/yyyy) [required]
--current NAME           Your base name [required]
--find-masters           Find ANY master numbers (11, 22, 33)
--purpose TYPE           Optimize for: spiritual, business, creative, teaching, analytical
--target-expression NUM  Find specific Expression number
--target-soul-urge NUM   Find specific Soul Urge number
--max NUMBER             Max results to show [default: 20]
--help, -h               Show help message
```

## Examples

### Example 1: Quick Check

```bash
$ bun numerology.ts --name "John Doe" --birthdate "5/13/1982"

╔═══════════════════════════════════════╗
║     NUMEROLOGY CHART                  ║
╚═══════════════════════════════════════╝

Name: John Doe
Birthdate: 5/13/1982

Core Numbers:
  1. Life Path:    11
  2. Expression:   8
  3. Soul Urge:    8
  4. Birthday:     4
```

### Example 2: Detailed Analysis

```bash
$ bun numerology.ts --name "John Doe" --birthdate "5/13/1982" --detailed

[Full detailed output with meanings for all numbers...]
```

### Example 3: JSON for Integration

```bash
$ bun numerology.ts --name "John Doe" --birthdate "5/13/1982" --format json
{
  "name": "John Doe",
  "birthdate": "5/13/1982",
  "lifePath": 11,
  "expression": 8,
  "soulUrge": 8,
  "birthday": 4,
  "calculations": {
    "month": 5,
    "day": 4,
    "year": 2,
    "nameBreakdown": {
      "John": 2,
      "Doe": 11
    },
    "vowelBreakdown": {
      "John": 6,
      "Doe": 11
    }
  },
  "meanings": {
    "lifePath": { ... },
    "expression": { ... },
    "soulUrge": { ... },
    "birthday": { ... }
  }
}
```

### Example 4: Find Optimal Days

```bash
# Find all Personal Day 1 days in November 2025 (best for launches)
$ bun optimal-days.ts --birthdate "5/13/1982" --month 11 --year 2025 --day 1

# Find creative work days by activity type
$ bun optimal-days.ts --birthdate "5/13/1982" --month 12 --activity creative

# Find business deal days for entire year
$ bun optimal-days.ts --birthdate "5/13/1982" --year 2025 --day 8
```

### Example 5: Life Stages & Pinnacles

```bash
# See your life pinnacles and current stage
$ bun pinnacles.ts --birthdate "5/13/1982" --name "John Doe"

# Output shows:
# - 4 major life pinnacles (9-year cycles)
# - Challenge numbers for each stage
# - Current pinnacle with strategic guidance
# - Next pinnacle preview
```

### Example 6: Relationship Compatibility

```bash
# General compatibility analysis
$ bun compatibility.ts --person1 "John Doe:5/13/1982" --person2 "Jane Smith:11/22/1990"

# Romantic relationship analysis
$ bun compatibility.ts --p1 "Alice:7/7/1988" --p2 "Bob:3/14/1985" --type romantic

# Business partnership analysis
$ bun compatibility.ts --p1 "Sarah:1/1/1980" --p2 "Mike:8/8/1983" --type business
```

### Example 7: Year-Ahead Calendar

```bash
# Preview current year's Personal Month cycles
$ bun year-ahead.ts --birthdate "5/13/1982"

# Plan for 2026 with name
$ bun year-ahead.ts --birthdate "5/13/1982" --year 2026 --name "John Doe"

# Output shows:
# - Personal Year theme and overview
# - All 12 months with Personal Month numbers
# - Strategic planning guide (launch months, creative months, etc.)
# - Key opportunities grouped by cycle type
```

### Example 8: Advanced Numbers

```bash
# Calculate additional numbers beyond core 4
$ bun advanced-numbers.ts --name "John Doe" --birthdate "5/13/1982"

# With detailed interpretations
$ bun advanced-numbers.ts --name "Jane Smith" --birthdate "11/22/1990" --detailed

# Or use --advanced flag with main calculator for everything
$ bun numerology.ts --name "John Doe" --birthdate "5/13/1982" --advanced

# Output shows:
# - Maturity Number (who you become after age 40)
# - Personality Number (how others see you)
# - Hidden Passion Number (your secret talent)
# - Karmic Lessons (areas to develop)
# - Balance Number (how you handle crisis)
```

### Example 9: Name Change Analysis

```bash
# Compare name variations
$ bun name-change.ts --birthdate "1/1/1980" --current "John Smith" --alternative "John Smith"

# Test multiple alternatives
$ bun name-change.ts -b "5/13/1982" -c "Jane Smith" -a "Jane Doe" -a "J Smith" -a "JJ"

# Output shows:
# - Expression/Soul Urge/Personality shifts
# - Master number activations
# - Karmic lesson changes
# - Energy shift analysis
# - Recommendations for which contexts to use each name
```

### Example 10: Name Optimizer (Rainbow Tables) 🔮

```bash
# Find ANY master numbers
$ bun name-optimizer.ts -b "1/1/1980" -c "John Smith" --find-masters

# Optimize for spiritual writing pseudonym
$ bun name-optimizer.ts -b "5/13/1982" -c "Jane Smith" --purpose spiritual

# Find business power names (Expression 8)
$ bun name-optimizer.ts -b "3/14/1985" -c "John Doe" --target-expression 8

# Creative work optimization
$ bun name-optimizer.ts -b "7/7/1990" -c "Sarah Jones" --purpose creative

# Output shows:
# - Tests 90+ intelligent name variations
# - Finds master number combinations (11, 22, 33)
# - Scores and ranks results by purpose
# - Shows top matches with star ratings ⭐
# - Like "hash cracking" but for numerology!
```

## Master Numbers

The calculator automatically detects and preserves master numbers (11, 22, 33) during calculation. Master numbers are spiritually significant and are not reduced to single digits.

Example:
```
✨ Master number found in Life Path: 11
```

## Numerology Meanings Database

The calculator includes comprehensive meanings for each number covering:

- Keywords
- Full description
- Strengths
- Challenges
- Life purpose
- Career paths
- Relationship dynamics
- Spiritual lessons

Each number (1-9, 11, 22, 33) has contextual meanings that vary based on position:
- Life Path meanings (your core purpose)
- Expression meanings (your natural talents)
- Soul Urge meanings (your inner desires)
- Birthday meanings (your special gifts)

## How Numerology Works

Numerology is based on the Pythagorean system where:
- Each letter has a numeric value (A=1, B=2, ... Z=26)
- Numbers are reduced to single digits (or master numbers)
- Different calculations reveal different aspects of personality

**Calculation Methods:**

1. **Life Path** = Reduce(Month) + Reduce(Day) + Reduce(Year), then reduce sum
2. **Expression** = Sum of all letters in full name, reduced
3. **Soul Urge** = Sum of vowels in full name, reduced
4. **Birthday** = Day of birth, reduced

**Master Number Rule:** 11, 22, and 33 are never reduced further.

## File Structure

```
numerology/
├── core-calculator.ts             # Core calculation functions
├── meanings.ts                    # Comprehensive numerology interpretations
├── cycle-meanings.ts              # Timing cycle interpretations
├── cycles.ts                      # Timing cycle calculations
├── numerology.ts                  # Main calculator with CLI
├── generate-report.ts             # LaTeX PDF report generator 📄 NEW
├── profile.ts                     # Profile management CLI ⭐ NEW
├── profile-manager.ts             # Profile CRUD operations ⭐ NEW
├── telos-export.ts                # Telos framework integration
├── telos-week.ts                  # Weekly planner (goals + cycles)
├── telos-cycles-analyze.ts        # Goal alignment analyzer
├── optimal-days.ts                # Find best days for activities ✨
├── pinnacles.ts                   # Life stages & pinnacles calculator ✨
├── compatibility.ts               # Relationship compatibility analyzer ✨
├── year-ahead.ts                  # Year-ahead Personal Month calendar ✨
├── advanced-numbers.ts            # Additional numbers (Maturity, Personality, etc.) ✨
├── name-change.ts                 # Name variation comparison tool ✨
├── name-optimizer.ts              # Master number hunter (rainbow tables) 🔮
├── templates/
│   └── report-template.tex        # LaTeX report template
├── archive/
│   ├── numerology.py              # Original Python version
│   ├── r_num.py                   # Refactored Python version
│   └── requirements.txt           # Python dependencies
├── CYCLES-DOCUMENTATION.md        # Complete cycle system guide
├── TELOS-INTEGRATION.md           # Integration vision document
├── PROFILE-SYSTEM.md              # Profile management documentation
└── README.md                      # This file
```

## Technology Stack

- **Runtime:** Bun (fast TypeScript runtime)
- **Language:** TypeScript (type-safe, modern)
- **No Dependencies:** Pure TypeScript, no external packages required

## Development

The calculator is written in pure TypeScript with no external dependencies. It uses:

- Bun's native TypeScript support
- Standard library only
- ANSI escape codes for terminal colors
- Functional programming patterns

## Documentation

- **[CYCLES-DOCUMENTATION.md](./CYCLES-DOCUMENTATION.md)** - Complete guide to timing cycles
- **[TELOS-INTEGRATION.md](./TELOS-INTEGRATION.md)** - Telos integration vision and roadmap

## Roadmap

### Phase 1: Core Integration ✅
- [x] Build telos-week.ts weekly planner
- [x] Test with real telos data
- [x] Document timing cycles system
- [x] Update README

### Phase 2: Deep Analysis ✅
- [x] Build telos-cycles-analyze.ts - Goal alignment analyzer with scoring
- [x] Quarterly action plan generator
- [x] 2026 preview feature

### Phase 3: Fabric Integration ✅
- [x] Create t_numerology_guidance Fabric pattern
- [x] AI-powered combined analysis
- [ ] Integrate with telos-runner.ts

### Phase 4: Advanced Features ✅
- [x] Optimal days finder (find best days for specific activities) ✨
- [x] Life stages/pinnacles calculator ✨
- [x] Compatibility analysis (compare two charts) ✨
- [x] Year-ahead calendar (Personal Month overview for 12 months) ✨

### Phase 5: Polish ✅
- [x] Additional numbers (Maturity, Hidden Passion, Karmic Lessons, etc.) ✨
- [x] Name change analysis (compare name variations) ✨
- [x] Name optimizer (brute-force master numbers) 🔮

### Phase 6: Profile System & Ultimate Deliverable ✅ COMPLETE
- [x] Profile management system (save name/birthdate, reuse across all tools)
  - `bun profile.ts create --name "..." --birthdate "..."`
  - `bun numerology.ts --profile name [command]`
  - Store in `~/.numerology/profiles/`
  - Multiple profiles support (you, partner, clients)
  - **ALL major tools now support --profile flag**
- [x] 📄 **LaTeX PDF Report Generator** - The ultimate deliverable!
  - Beautiful full-spectrum numerology report
  - Core numbers + advanced numbers + cycles + pinnacles
  - Professional typography and layout
  - Includes all calculations and detailed interpretations
  - Shareable/printable for clients or personal use
  - `bun generate-report.ts --profile name`

**🎯 CURRENT STATUS: Production-ready for client delivery via PDF reports**

### Phase 7: Future Enhancements (Post-Customer Validation)

**Strategy:** Start with PDF reports as primary deliverable. Gather customer feedback and traction. Then expand to web UI for self-service.

#### Calculation Enhancements
- [ ] **Transits Calculator** - Calculate when you'll experience specific Personal Days/Months/Years
- [ ] **Karmic Debt Numbers** - Detect and interpret 13, 14, 16, 19 karmic debt numbers
- [ ] **Master Number 44** - Add support for master number 44
- [ ] **Compound Numbers** - Track compound numbers before reduction (e.g., 29/11 vs 38/11)
- [ ] **Business Name Analysis** - Dedicated tool for business/brand name numerology
- [ ] **Pythagorean vs Chaldean** - Toggle between different numerology systems

#### Intelligence & Optimization
- [ ] **Business Name Generator** - Intelligent variations beyond middle initials for optimal numbers
- [ ] **Multi-person Compatibility** - Compare 3+ people (teams, families, partnerships)

#### User Experience & Delivery
- [ ] 🎨 **Web UI** (Bun.serve + React) - *Deploy after customer traction*
  - Interactive forms with real-time calculations
  - Visual comparisons and compatibility charts
  - Side-by-side name variations explorer
  - Shareable links and web-based PDF generation
  - Profile/account management
  - Date pickers and input validation
- [ ] **Interactive Birth Chart Visualization** - Visual representation of numerology charts
- [ ] **Email Delivery** - Automated email delivery of PDF reports to clients
- [ ] **Client Portal** - Dashboard for managing multiple client reports

## Credits

**Original Python Implementation:** Initial algorithm and calculation logic
**TypeScript Rewrite:** Modern implementation with comprehensive meanings database
**Numerology System:** Based on Pythagorean numerology

## License

GNU General Public License v3.0

## Resources

- [Numerology Basics](https://www.numerology.com/)
- [Life Path Calculator](https://www.tokenrock.com/numerology/life-path-number/)
- [Telos Framework](https://danielmiessler.com/p/telos/)

---

**Made with ❤️ and TypeScript**