numerology/PROFILE-SYSTEM.md

# Profile Management System

## Overview

The profile management system allows you to save your numerology data (name and birthdate) once and reuse it across all numerology tools. No more typing `--name "..." --birthdate "..."` every time!

## Features

- **Create profiles** with auto-generated or custom identifiers
- **List all profiles** to see what's saved
- **Show profile details** including creation/update dates
- **Delete profiles** when no longer needed
- **Use profiles everywhere** across all 10+ numerology tools

## Storage

Profiles are stored in JSON format at:
```
~/.numerology/profiles/<identifier>.json
```

Each profile contains:
```json
{
  "name": "John Smith",
  "birthdate": "3/15/1990",
  "created": "2025-10-15T12:27:34.567Z",
  "updated": "2025-10-15T12:27:34.567Z"
}
```

## Commands

### Create a Profile

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

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

# Update existing profile (same command)
bun profile.ts create rob --name "John Smith" --birthdate "3/15/1990"
```

**Options:**
- `--name, -n NAME` - Full name (required)
- `--birthdate, -b DATE` - Birthdate in mm/dd/yyyy format (required)

### List Profiles

```bash
bun profile.ts list
```

Shows all saved profiles with:
- Identifier
- Name
- Birthdate
- Creation date

### Show Profile Details

```bash
bun profile.ts show rob
```

Shows detailed information:
- Name
- Birthdate
- Created timestamp
- Updated timestamp

### Delete Profile

```bash
bun profile.ts delete rob
```

Permanently removes the profile from storage.

## Using Profiles

Once created, use `--profile` (or `-p`) flag with any numerology tool:

### Main Calculator

```bash
# Basic calculation
bun numerology.ts --profile john

# With detailed meanings
bun numerology.ts --profile john --detailed

# With advanced numbers
bun numerology.ts --profile john --advanced

# With timing cycles
bun numerology.ts --profile john --cycles

# All together
bun numerology.ts --profile john --detailed --advanced --cycles
```

### PDF Report Generator

```bash
# Generate comprehensive PDF report
bun generate-report.ts --profile john

# Custom output location
bun generate-report.ts --profile john --output ~/reports/rob-numerology.pdf
```

### Other Tools

```bash
# 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

# Pinnacles & life stages
bun pinnacles.ts --profile john

# Advanced numbers
bun advanced-numbers.ts --profile john --detailed

# Name change analysis (current name loaded from profile)
bun name-change.ts --profile john --alternative "John Smith"

# Name optimizer (base name loaded from profile)
bun name-optimizer.ts --profile john --find-masters
```

## Use Cases

### Personal Use
Save your own profile and quickly run any calculation:
```bash
bun profile.ts create --name "Your Name" --birthdate "mm/dd/yyyy"
bun numerology.ts --profile yourname --detailed --advanced --cycles
```

### Family Profiles
Store profiles for family members:
```bash
bun profile.ts create --name "Partner Name" --birthdate "mm/dd/yyyy"
bun profile.ts create --name "Child Name" --birthdate "mm/dd/yyyy"

# Compare compatibility
bun compatibility.ts --profile partner1 --profile partner2
```

### Professional/Client Use
Numerology practitioners can store client profiles:
```bash
# Create client profiles
bun profile.ts create client1 --name "Client Name" --birthdate "mm/dd/yyyy"

# Generate professional reports
bun generate-report.ts --profile client1 --output ~/clients/client1-report.pdf
```

### Multiple Profiles
Test different scenarios with saved profiles:
```bash
# Create variations
bun profile.ts create john-legal --name "John Smith" --birthdate "3/15/1990"
bun profile.ts create john-nick --name "John Smith" --birthdate "3/15/1990"

# Compare
bun numerology.ts --profile john-legal --detailed
bun numerology.ts --profile john-nick --detailed
```

## Architecture

### File Structure

```
profile-manager.ts  # Core CRUD operations
profile.ts          # CLI interface
~/.numerology/
  └── profiles/
      ├── rob.json
      ├── jane.json
      └── ...
```

### API Functions

From `profile-manager.ts`:

```typescript
// Save or update a profile
saveProfile(identifier: string, name: string, birthdate: string): void

// Load a profile
loadProfile(identifier: string): Profile | null

// List all profiles
listProfiles(): Array<{ identifier: string; profile: Profile }>

// Delete a profile
deleteProfile(identifier: string): boolean

// Check if profile exists
profileExists(identifier: string): boolean

// Generate identifier from name
generateIdentifier(name: string): string
```

### Profile Interface

```typescript
interface Profile {
  name: string;
  birthdate: string;
  created: string;     // ISO 8601 timestamp
  updated: string;     // ISO 8601 timestamp
}
```

## Implementation Details

### Identifier Generation

Auto-generated identifiers:
- Extract first name from full name
- Convert to lowercase
- Remove non-alphanumeric characters

Example: "John Smith" → "rob"

### File Naming

Profile files use sanitized identifiers:
- Lowercase
- Replace invalid characters with hyphens
- Only `a-z`, `0-9`, `-`, `_` allowed

Example: "Rob's Profile" → `robs-profile.json`

### Timestamp Tracking

- `created` - Never changes, set on first save
- `updated` - Updates every time profile is modified

### Error Handling

- Profile not found → Helpful error message with suggestion to list profiles
- Invalid data → Validation errors with clear instructions
- File system errors → Caught and reported gracefully

## Future Enhancements

Potential additions to the profile system:

1. **Profile metadata** - Add notes, tags, or categories
2. **Import/export** - Share profiles or backup to file
3. **Profile groups** - Organize profiles by family, clients, etc.
4. **Search** - Find profiles by name or birthdate pattern
5. **Aliases** - Multiple identifiers for same profile
6. **Defaults** - Set default profile for quick access
7. **Cloud sync** - Sync profiles across devices
8. **History** - Track calculation history per profile

## Benefits

✅ **Convenience** - Type once, use everywhere
✅ **Consistency** - Same data across all tools
✅ **Speed** - Faster workflow for repeated calculations
✅ **Organization** - Manage multiple people systematically
✅ **Professional** - Clean interface for client work
✅ **Portable** - Simple JSON format, easy to backup

## Compatibility

Works with all numerology tools:
- ✅ numerology.ts (main calculator)
- ✅ generate-report.ts (PDF reports)
- ✅ optimal-days.ts
- ✅ pinnacles.ts
- ✅ compatibility.ts
- ✅ year-ahead.ts
- ✅ advanced-numbers.ts
- ✅ name-change.ts
- ✅ name-optimizer.ts
- ✅ telos-week.ts
- ✅ And more...

---

**Status:** ✅ Fully Implemented (Phase 6)
**Version:** 1.0
**Date:** October 15, 2025