From 67337a6771bd3986802bede684f24919b79cd925 Mon Sep 17 00:00:00 2001
From: Cal Corum <calcorum@users.noreply.github.com>
Date: Thu, 5 Mar 2026 19:50:05 -0600
Subject: [PATCH] Modularize major-domo skill (1005 -> 173 lines in SKILL.md)

Extract API and CLI references into dedicated files:
- SKILL.md (173 lines): routing, safety rules, architecture, common queries
- API_REFERENCE.md (99 lines): endpoints, auth, Python client
- CLI_REFERENCE.md (115 lines): commands, flag ordering, compliance workflow

Total content reduced from 1005 to 387 lines.
Context loaded per session drops from 1005 to 173 lines.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 skills/major-domo/API_REFERENCE.md |   99 +++
 skills/major-domo/CLI_REFERENCE.md |  115 ++++
 skills/major-domo/SKILL.md         | 1027 +++-------------------------
 3 files changed, 312 insertions(+), 929 deletions(-)
 create mode 100644 skills/major-domo/API_REFERENCE.md
 create mode 100644 skills/major-domo/CLI_REFERENCE.md

diff --git a/skills/major-domo/API_REFERENCE.md b/skills/major-domo/API_REFERENCE.md
new file mode 100644
index 0000000..1d64282
--- /dev/null
+++ b/skills/major-domo/API_REFERENCE.md
@@ -0,0 +1,99 @@
+# Major Domo - API Reference
+
+## Authentication
+
+All write operations require Bearer token:
+```bash
+export API_TOKEN='your-token-here'
+```
+
+## Environments
+
+- **Production**: `https://api.sba.manticorum.com/v3/`
+- **Development**: `http://10.10.0.42:8000/api/v3/`
+
+```bash
+export DATABASE='prod'  # or 'dev'
+```
+
+## Endpoints
+
+### Current Status
+- `GET /current` - Current season/week status
+- `GET /current?season={N}` - Specific season status
+- `PATCH /current/{id}` - Update status (private)
+
+### Players
+- `GET /players?season={N}` - List all players in season
+- `GET /players?team_id={id}` - Players by team
+- `GET /players?name={name}` - Players by name (exact)
+- `GET /players/search?q={query}` - Fuzzy search
+- `GET /players/{id}` - Single player
+- `PATCH /players/{id}` - Update player (private)
+
+### Teams
+- `GET /teams?season={N}` - List teams
+- `GET /teams?team_abbrev={abbrev}` - By abbreviation
+- `GET /teams?active_only=true` - Active teams only
+- `GET /teams/{id}` - Single team
+- `GET /teams/{id}/roster/{which}` - Roster (current/next)
+
+### Standings
+- `GET /standings?season={N}` - All standings
+- `GET /standings?season={N}&division_abbrev={div}` - By division
+- `GET /standings/team/{team_id}` - Single team
+- `POST /standings/s{season}/recalculate` - Recalculate (private)
+
+### Transactions
+- `GET /transactions?season={N}` - List transactions
+- `GET /transactions?season={N}&team_abbrev={abbrev}` - By team
+- `GET /transactions?season={N}&week_start={W}&week_end={W}` - By week range
+- `PATCH /transactions/{move_id}` - Update (private)
+
+### Statistics (Advanced Views)
+- `GET /views/season-stats/batting?season={N}` - Season batting
+  - Params: `team_id`, `player_id`, `min_pa`, `sort_by`, `sort_order`, `limit`, `offset`
+- `GET /views/season-stats/pitching?season={N}` - Season pitching
+  - Params: `team_id`, `player_id`, `min_outs`, `sort_by`, `sort_order`, `limit`, `offset`
+- `POST /views/season-stats/batting/refresh` - Refresh batting (private)
+- `POST /views/season-stats/pitching/refresh` - Refresh pitching (private)
+
+### Other Endpoints
+- `/api/v3/schedules` - Game scheduling
+- `/api/v3/results` - Game results
+- `/api/v3/injuries` - Injury tracking
+- `/api/v3/awards` - League awards
+- `/api/v3/managers` - Manager profiles
+- `/api/v3/divisions` - Division info
+- `/api/v3/draftdata` - Draft status
+- `/api/v3/draftpicks` - Pick ownership
+- `/api/v3/draftlist` - Draft priority lists
+- `/api/v3/keepers` - Keeper selections
+- `/api/v3/stratgame` - Game data
+- `/api/v3/stratplay` - Play-by-play
+- `/api/v3/sbaplayers` - Player pool
+- `/api/v3/custom_commands` - Custom Discord commands
+- `/api/v3/help_commands` - Static help text
+
+## Python API Client
+
+```python
+from api_client import MajorDomoAPI
+
+api = MajorDomoAPI(environment='prod', verbose=True)
+# Or: api = MajorDomoAPI(environment='dev', token='your-token')
+
+# Common operations
+current = api.get_current()
+team = api.get_team(abbrev='CAR')
+player = api.get_player(name='Mike Trout', season=12)
+results = api.search_players(query='trout', season=12, limit=10)
+roster = api.get_team_roster(team_id=42, which='current')
+standings = api.get_standings(season=12, division_abbrev='ALE')
+transactions = api.get_transactions(season=12, team_abbrev='CAR')
+batting = api.get_season_batting_stats(season=12, min_pa=100, sort_by='woba', limit=50)
+pitching = api.get_season_pitching_stats(season=12, min_outs=150, sort_by='era', limit=50)
+```
+
+**OpenAPI docs**: `http://10.10.0.42/api/docs`
+**Router source**: `/mnt/NV2/Development/major-domo/database/app/routers_v3/`
diff --git a/skills/major-domo/CLI_REFERENCE.md b/skills/major-domo/CLI_REFERENCE.md
new file mode 100644
index 0000000..91b874f
--- /dev/null
+++ b/skills/major-domo/CLI_REFERENCE.md
@@ -0,0 +1,115 @@
+# Major Domo - CLI Reference
+
+## Invocation
+
+**Wrapper**: `majordomo` (alias, uses `uv run`)
+
+**Full path** (for Claude Code):
+```bash
+python3 ~/.claude/skills/major-domo/cli.py <command>
+```
+
+## Flag Ordering
+
+`--env`, `--json`, `--verbose` are **top-level flags** (BEFORE subcommand).
+`--season` is a **subcommand flag** (AFTER subcommand).
+
+```bash
+# Correct:
+python3 ~/.claude/skills/major-domo/cli.py --json team get CLS
+python3 ~/.claude/skills/major-domo/cli.py --env dev team roster CAN
+
+# Wrong (will error):
+python3 ~/.claude/skills/major-domo/cli.py team get CLS --json
+```
+
+## Commands
+
+### Status
+```bash
+cli.py status                              # Current season/week
+cli.py health                              # API health check
+```
+
+### Players
+```bash
+cli.py player get "Mike Trout"             # Get player info
+cli.py player search "trout"               # Fuzzy search
+cli.py player move "Name" TEAM             # Move single player
+cli.py player move --batch "N1:T1,N2:T2"   # Batch moves
+```
+
+### Teams
+```bash
+cli.py team list [--active]                # List teams
+cli.py team get CAR                        # Team details
+cli.py team roster CAR                     # Roster breakdown (Active/Short IL/Long IL)
+```
+
+### Standings
+```bash
+cli.py standings [--division ALE]          # League standings
+```
+
+### Transactions
+```bash
+cli.py transactions --team CLS --week 9                           # Team transactions
+cli.py transactions list --week-start 1 --week-end 4              # Week range
+cli.py transactions --player "Mike Trout"                         # Player transactions
+cli.py transactions simulate CLS "Stott:CLSMiL,Walker:CLS"       # Compliance check (dry run)
+```
+
+### Injuries
+```bash
+cli.py injuries list --team CLS --active   # Active injuries for team
+cli.py injuries list --sort return-asc     # Sort by return date
+```
+
+### Statistics
+```bash
+cli.py stats batting --sort woba --min-pa 100 --limit 25    # Batting leaders
+cli.py stats pitching --sort era --min-outs 100 --limit 25  # Pitching leaders
+cli.py stats batting --team CLS                              # Team batting
+```
+
+### Results & Schedule
+```bash
+cli.py results --team CLS --week 9                            # Team results
+cli.py results list --week-start 1 --week-end 4               # Range
+cli.py schedule --team CLS --week 10                          # Team schedule
+cli.py schedule list --week-start 10 --week-end 12            # Range
+```
+
+### Admin (write operations)
+```bash
+cli.py admin recalculate-standings          # Recalculate standings
+cli.py admin refresh-batting                # Refresh batting view
+cli.py admin refresh-pitching               # Refresh pitching view
+cli.py admin refresh-stats                  # Refresh both views
+cli.py admin refresh-batting --season 11    # Specific season
+```
+
+## Key Notes
+
+- `team get` shows salary_cap in formatted output; use `--json` for all fields
+- `team roster` shows Active/Short IL/Long IL with WARA values for Active only
+- "Long IL" = MiL (minor leagues)
+- For individual player lookups, use `player get "Name"` — bulk queries can timeout
+- `transactions simulate` validates compliance without making changes
+- `stats` commands support standard baseball stats sorting (woba, obp, slg, era, whip, fip, etc.)
+
+## Transaction Compliance Workflow
+
+```bash
+# 1. Simulate proposed moves (dry run)
+cli.py transactions simulate CLS "Stott:CLSMiL,Walker:CLS,Castellanos:FA,Martin:CLS"
+
+# Validates: roster count = 26, total sWAR <= salary_cap, all players exist
+```
+
+**Manual verification** (if needed):
+1. `cli.py team roster ABBREV` → note count and WARA
+2. `cli.py --json team get ABBREV` → read `salary_cap`
+3. `cli.py player get "Name"` for each incoming player
+4. Calculate: current sWAR ± changes <= cap, roster = 26
+5. `cli.py player move --batch "Name1:Team1,Name2:Team2"`
diff --git a/skills/major-domo/SKILL.md b/skills/major-domo/SKILL.md
index a9b22f1..bd42253 100644
--- a/skills/major-domo/SKILL.md
+++ b/skills/major-domo/SKILL.md
@@ -7,96 +7,44 @@ description: Major Domo SBA fantasy baseball management. USE WHEN user mentions
 
 **SCOPE**: Only use in major-domo-v2, major-domo-bot, major-domo-database repos. Do not activate in unrelated projects.
 
-## When to Activate This Skill
+## When to Activate
 
-**Discord Bot Operations**:
-- "Test Discord bot command"
-- "Update bot on dev server"
-- "Check bot status"
-
-> **For Docker deployment and releases**, use the `deploy` skill instead:
-> - "Deploy discord bot" / "Deploy database"
-> - "Bump version and deploy"
-
-**League Operations**:
-- "Update weekly stats for SBA"
-- "Process injuries for week X"
-- "Show trade deadline information"
-- "Get current season/week status"
-
-**Data Queries**:
-- "Show player stats for [name]"
-- "List teams in season X"
-- "Get team roster for [abbrev]"
-- "Show league standings"
-- "Find transactions for team [abbrev]"
-
-**Database Operations**:
-- "Run database migration"
-- "Sync production data to dev"
-- "Check database health"
-- "Validate data integrity"
-
-**Analytics & Reporting**:
-- "Generate season batting leaders"
-- "Show pitching stats for season X"
-- "Analyze team performance"
-- "Create weekly report"
+- Discord bot operations, deployment, status checks
+- League operations: weekly stats, injuries, trade deadlines
+- Data queries: player stats, team rosters, standings, transactions
+- Database operations: migrations, sync, health checks
+- Analytics: batting/pitching leaders, team analysis
 
 ## What is Major Domo?
 
-**Major Domo** is a comprehensive system for managing the **Strat-o-Matic Baseball Association (SBA)**, a fantasy baseball league with:
-- Discord bot for league management and gameplay
-- FastAPI backend serving league data (PostgreSQL)
-- Vue.js website displaying league information
-- 18-week seasons with 4 games per week
-- Draft system with keepers and pick trading
-- Real-time game simulation using Strat-o-Matic rules
-
-**Key Components**:
-- **Database API**: FastAPI backend (production: 10.10.0.42, dev: 10.10.0.42 Docker)
-- **Discord Bot**: Python bot using discord.py 2.5.2
-- **Discord Bot v2**: Next-generation bot with enhanced logging
-- **Website**: Vue 3 + TypeScript frontend
-- **Current Season**: 12 (from helpers.py)
+Comprehensive system for managing the **Strat-o-Matic Baseball Association (SBA)**:
+- **Database API**: FastAPI + PostgreSQL (prod: `https://api.sba.manticorum.com/v3/`, dev: `http://10.10.0.42:8000/api/v3/`)
+- **Discord Bot**: Python bot (discord.py 2.5.2) + v2 with enhanced logging
+- **Website**: Vue 3 + TypeScript
+- **Seasons**: 18 weeks, 4 games/week, draft with keepers and pick trading
+- **Current Season**: 12
 
 ---
 
-## 🚨 CRITICAL: Environment & Safety Rules
+## CRITICAL: Safety Rules
 
-### API-Based Data Access
-
-✅ **ALWAYS** use the API endpoints (production or development)
-- Default to **production** unless specified otherwise
-- Use `MajorDomoAPI` client from `api_client.py`
-- Production: `https://api.sba.manticorum.com/v3/`
-- Development: `http://10.10.0.42:8000/api/v3/` (Docker)
-
-❌ **NEVER** access databases directly
-- **NEVER** query local SQLite databases (always out of date)
-- Do NOT use `sqlite3` commands on .db files
-- Do NOT use `psql` commands without explicit request
-- Do NOT bypass the API for queries
-- API provides proper authentication and access control
-
-**Exception**: Only access database directly when user **explicitly requests** it
-
-**Why This Matters**:
-- Local SQLite databases are development artifacts and NOT current
+### API-First Data Access
+- **ALWAYS** use the API or CLI — never query databases directly
+- **NEVER** access local SQLite databases (always out of date)
 - Production API is the single source of truth
-- Direct database access bypasses security and may show stale data
+- Exception: direct DB access only when user **explicitly requests** it
 
-### Repository Safety
+### CLI-First for Operations
+```bash
+python3 ~/.claude/skills/major-domo/cli.py <command>
+```
+See `CLI_REFERENCE.md` for full command list and flag ordering rules.
 
-**BEFORE EVERY COMMIT**:
+### Before Every Commit
 - Run `git remote -v` to verify repository
-- Check you're in the correct directory
-- Major Domo is at `/mnt/NV2/Development/major-domo/`
-- Discord bot v2 at `/mnt/NV2/Development/major-domo/discord-app-v2/`
+- Major Domo: `/mnt/NV2/Development/major-domo/`
 
-### Docker & Production Safety
-
-**ALWAYS prompt user before**:
+### Always Prompt User Before
 - Modifying production infrastructure
 - Running `docker-compose down` on production
 - Deploying bot updates to main Discord server
@@ -104,901 +52,122 @@ description: Major Domo SBA fantasy baseball management. USE WHEN user mentions
 
 ---
 
-## System Architecture
-
-### Project Structure
+## Architecture
 
 ```
 major-domo/
-├── database/                 # FastAPI backend (PostgreSQL)
-│   ├── app/
-│   │   ├── main.py          # FastAPI application
-│   │   ├── db_engine.py     # Peewee ORM models
-│   │   ├── dependencies.py  # Auth & error handling
-│   │   └── routers_v3/      # API endpoints (v3)
-│   ├── docker-compose.yml   # PostgreSQL + API + Adminer
-│   └── migrations/          # SQL migration files
-├── discord-app/             # Original Discord bot (Python)
-│   ├── majordomo.py         # Bot entry point
-│   ├── cogs/                # Command modules
-│   └── db_calls.py          # API integration
-├── discord-app-v2/          # Next-gen Discord bot
-│   ├── bot.py               # Enhanced bot with logging
-│   └── commands/            # Command packages
-└── sba-website/             # Vue.js frontend
-    ├── src/
-    └── package.json
+├── database/               # FastAPI backend (PostgreSQL)
+│   ├── app/main.py         # FastAPI application
+│   ├── app/db_engine.py    # Peewee ORM models
+│   ├── app/routers_v3/     # API v3 endpoints
+│   └── migrations/         # SQL migration files
+├── discord-app/            # Original Discord bot
+├── discord-app-v2/         # Next-gen bot with enhanced logging
+└── sba-website/            # Vue.js frontend
 ```
 
-### API Endpoints (routers_v3/)
-
-**Core Data Endpoints**:
-- `/api/v3/current` - Season/week status, trade deadlines, playoff schedule
-- `/api/v3/players` - Player information, rosters, search
-- `/api/v3/teams` - Team data, rosters (current/next week)
-- `/api/v3/standings` - League standings by division/league
-- `/api/v3/transactions` - Player transactions (trades, waivers)
-
-**Statistics Endpoints**:
-- `/api/v3/battingstats` - Batting statistics (seasonal + career)
-- `/api/v3/pitchingstats` - Pitching statistics (seasonal + career)
-- `/api/v3/fieldingstats` - Fielding statistics (seasonal + career)
-- `/api/v3/views/season-stats/batting` - Advanced batting views
-- `/api/v3/views/season-stats/pitching` - Advanced pitching views
-
-**League Management**:
-- `/api/v3/schedules` - Game scheduling
-- `/api/v3/results` - Game results
-- `/api/v3/injuries` - Player injury tracking
-- `/api/v3/awards` - League awards
-- `/api/v3/managers` - Manager profiles
-- `/api/v3/divisions` - Division information
-
-**Draft System**:
-- `/api/v3/draftdata` - Current draft status
-- `/api/v3/draftpicks` - Draft pick ownership
-- `/api/v3/draftlist` - Team draft priority lists
-- `/api/v3/keepers` - Keeper selections
-
-**Game Data**:
-- `/api/v3/stratgame` - Strat-o-Matic game data
-- `/api/v3/stratplay` - Play-by-play data
-- `/api/v3/sbaplayers` - SBA player pool
-
-**Custom Features**:
-- `/api/v3/custom_commands` - User-created Discord commands
-- `/api/v3/help_commands` - Static help text
-- `/api/v3/decisions` - Game decisions/choices
-
 ### Database Models (Key Entities)
-
-**Core Entities**:
-- `Current` - Season/week status, configuration
-- `Player` - Player data with positions, WARA, injuries
-- `Team` - Teams with managers, divisions, metadata
-- `Manager` - Manager profiles and contact info
-- `Division` - League/division structure
-
-**Statistics**:
-- `BattingStat` - Game-by-game batting stats
-- `PitchingStat` - Game-by-game pitching stats
-- `FieldingStat` - Game-by-game fielding stats
-- `SeasonBattingStats` - Aggregated season batting (view)
-- `SeasonPitchingStats` - Aggregated season pitching (view)
-
-**League Management**:
-- `Standings` - Team records and standings
-- `Schedule` - Game schedules
-- `Result` - Game results
-- `Transaction` - Player transactions
-- `Injury` - Player injury tracking
-- `Award` - League awards and recognition
-
-**Draft System**:
-- `DraftData` - Current draft status
-- `DraftPick` - Draft pick ownership
-- `DraftList` - Team draft priority lists
-- `Keeper` - Keeper selections
-
-**Game Data**:
-- `StratGame` - Strat-o-Matic game records
-- `StratPlay` - Play-by-play data
-- `SBAPlayer` - Available player pool
-
----
-
-## API Reference
-
-### Authentication
-
-All write operations require Bearer token:
-```bash
-export API_TOKEN='your-token-here'
-```
-
-Headers:
-```python
-{'Authorization': f'Bearer {API_TOKEN}'}
-```
-
-### Environments
-
-- **Production**: `https://api.sba.manticorum.com/v3/` (main API server)
-- **Development**: `http://10.10.0.42:8000/api/v3/` (Docker container on dev server)
-
-Set via environment variable:
-```bash
-export DATABASE='prod'  # or 'dev'
-```
-
-### Common Endpoints
-
-**Current Season/Week**:
-- `GET /current` - Get current season/week status
-- `GET /current?season={N}` - Get specific season status
-- `PATCH /current/{id}` - Update current status (private)
-
-**Players**:
-- `GET /players?season={N}` - List all players in season
-- `GET /players?team_id={id}` - Players by team
-- `GET /players?name={name}` - Players by name (exact match)
-- `GET /players/search?q={query}` - Fuzzy search players
-- `GET /players/{id}` - Get single player
-- `PATCH /players/{id}` - Update player (private)
-
-**Teams**:
-- `GET /teams?season={N}` - List teams in season
-- `GET /teams?team_abbrev={abbrev}` - Get team by abbreviation
-- `GET /teams?active_only=true` - Only active teams (excludes IL/MiL)
-- `GET /teams/{id}` - Get single team
-- `GET /teams/{id}/roster/{which}` - Get roster (current/next week)
-
-**Standings**:
-- `GET /standings?season={N}` - All standings for season
-- `GET /standings?season={N}&division_abbrev={div}` - By division
-- `GET /standings/team/{team_id}` - Single team standings
-- `POST /standings/s{season}/recalculate` - Recalculate standings (private)
-
-**Transactions**:
-- `GET /transactions?season={N}` - List transactions
-- `GET /transactions?season={N}&team_abbrev={abbrev}` - By team
-- `GET /transactions?season={N}&week_start={W}&week_end={W}` - By week range
-- `GET /transactions?move_id={id}` - By move ID
-- `PATCH /transactions/{move_id}` - Update transaction (private)
-
-**Statistics (Advanced Views)**:
-- `GET /views/season-stats/batting?season={N}` - Season batting stats
-  - Params: `team_id`, `player_id`, `min_pa`, `sort_by`, `sort_order`, `limit`, `offset`
-- `GET /views/season-stats/pitching?season={N}` - Season pitching stats
-  - Params: `team_id`, `player_id`, `min_outs`, `sort_by`, `sort_order`, `limit`, `offset`
-- `POST /views/season-stats/batting/refresh` - Refresh batting stats (private)
-- `POST /views/season-stats/pitching/refresh` - Refresh pitching stats (private)
-
----
-
-## Using the API Client
-
-### Basic Setup
-
-```python
-from api_client import MajorDomoAPI
-
-# Initialize (reads API_TOKEN from environment)
-api = MajorDomoAPI(environment='prod', verbose=True)
-
-# Or provide token directly
-api = MajorDomoAPI(environment='dev', token='your-token')
-```
-
-### Common Operations
-
-```python
-# Get current season/week
-current = api.get_current()
-print(f"Season {current['season']}, Week {current['week']}")
-
-# Get a team
-team = api.get_team(abbrev='CAR')
-team = api.get_team(team_id=42)
-
-# List teams
-all_teams = api.list_teams(season=12)
-active_teams = api.list_teams(season=12, active_only=True)
-
-# Get player
-player = api.get_player(name='Mike Trout', season=12)
-player = api.get_player(player_id=1234)
-
-# Search players (fuzzy)
-results = api.search_players(query='trout', season=12, limit=10)
-
-# Get team roster
-roster = api.get_team_roster(team_id=42, which='current')  # or 'next'
-
-# Get standings
-standings = api.get_standings(season=12, division_abbrev='ALE')
-
-# Get transactions
-transactions = api.get_transactions(season=12, team_abbrev='CAR', week_start=1, week_end=4)
-
-# Get batting stats (advanced)
-stats = api.get_season_batting_stats(
-    season=12,
-    min_pa=100,
-    sort_by='woba',
-    sort_order='desc',
-    limit=50
-)
-
-# Get pitching stats (advanced)
-stats = api.get_season_pitching_stats(
-    season=12,
-    min_outs=150,
-    sort_by='era',
-    sort_order='asc',
-    limit=50
-)
-```
+- **Core**: Current, Player, Team, Manager, Division
+- **Stats**: BattingStat, PitchingStat, FieldingStat, SeasonBattingStats, SeasonPitchingStats
+- **League**: Standings, Schedule, Result, Transaction, Injury, Award
+- **Draft**: DraftData, DraftPick, DraftList, Keeper
+- **Game**: StratGame, StratPlay, SBAPlayer
 
 ---
 
 ## Workflows
 
-This skill includes structured workflows for common tasks:
+| Workflow | Trigger | Details |
+|----------|---------|---------|
+| Bot Deployment | "Deploy bot" | `workflows/bot-deployment.md` |
+| Weekly Stats | "Update weekly stats" | `workflows/weekly-stats-update.md` |
+| Database Migration | "Run migration" | `workflows/database-migration.md` |
+| Season Rollover | "Start new season" | `workflows/season-rollover.md` |
 
-### 1. Discord Bot Deployment
+## Common Queries
 
-**Purpose**: Deploy Discord bot updates to production or test servers
+```bash
+# Status
+cli.py status                                    # Current season/week
 
-**When**: After bot code changes, new features, or bug fixes
+# Players
+cli.py player get "Mike Trout"                   # Player info
+cli.py player search "trout"                     # Fuzzy search
 
-> **Recommended**: Use the `deploy` skill for Docker-based deployments:
-> ```bash
-> ~/.claude/skills/deploy/deploy.sh md-discord patch
-> ```
-> This handles version bumping, Docker build/push, and production deployment automatically.
+# Teams
+cli.py team roster CAR                           # Full roster breakdown
+cli.py --json team get CAR                       # All fields inc. salary_cap
 
-**Manual Workflow**: `~/.claude/skills/major-domo/workflows/bot-deployment.md`
+# Standings & Stats
+cli.py standings --division ALE                  # Division standings
+cli.py stats batting --sort woba --min-pa 100    # Batting leaders
+cli.py stats pitching --sort era --min-outs 100  # Pitching leaders
 
-**Quick Steps** (manual):
-1. Test changes locally or on dev server
-2. Update version in bot code
-3. Stop production bot
-4. Pull latest changes
-5. Restart bot
-6. Verify bot is online and responsive
+# Transactions
+cli.py transactions --team CLS --week 9          # Team transactions
+cli.py transactions simulate CLS "P1:CLSMiL,P2:CLS"  # Compliance check
 
-### 2. Weekly Stats Update
-
-**Purpose**: Process weekly game results and update statistics
-
-**When**: End of each game week (weekly)
-
-**Workflow**: `~/.claude/skills/major-domo/workflows/weekly-stats-update.md`
-
-**Quick Steps**:
-1. Import game results from Strat-o-Matic
-2. Update standings
-3. Process injuries
-4. Refresh season statistics
-5. Generate weekly report
-6. Post updates to Discord
-
-### 3. Database Migration
-
-**Purpose**: Apply database schema changes
-
-**When**: Schema updates, new features requiring DB changes
-
-**Workflow**: `~/.claude/skills/major-domo/workflows/database-migration.md`
-
-**Quick Steps**:
-1. Create migration SQL file in `migrations/`
-2. Test migration on development database
-3. Backup production database
-4. Apply migration to production
-5. Verify schema changes
-6. Update API/bot code if needed
-
-### 4. Season Rollover
-
-**Purpose**: Prepare system for new season
-
-**When**: Start of new season (annually)
-
-**Workflow**: `~/.claude/skills/major-domo/workflows/season-rollover.md`
-
-**Quick Steps**:
-1. Archive previous season data
-2. Create new season teams
-3. Initialize standings
-4. Configure draft settings
-5. Update current season/week
-6. Test all systems
-
----
-
-## Common Request Patterns
-
-### Information Queries
-
-**Current Status**:
-```
-"What season/week is it?"
-→ api.get_current()
-
-"When is the trade deadline?"
-→ api.get_current(), show trade_deadline field
-```
-
-**Player Information**:
-```
-"Show stats for Mike Trout"
-→ api.get_player(name='Mike Trout', season=12)
-
-"Search for players named Smith"
-→ api.search_players(query='smith', season=12)
-
-"List all injured players"
-→ api.list_players(season=12, is_injured=True)
-```
-
-**Team Information**:
-```
-"Show roster for CAR"
-→ api.get_team_roster(team_id=X, which='current')
-
-"List all teams in season 12"
-→ api.list_teams(season=12)
-
-"Show standings for AL East"
-→ api.get_standings(season=12, division_abbrev='ALE')
-```
-
-**Transactions**:
-```
-"Show trades this week"
-→ api.get_transactions(season=12, week_start=W, week_end=W)
-
-"List all CAR transactions"
-→ api.get_transactions(season=12, team_abbrev='CAR')
-```
-
-### Analytics Queries
-
-**Batting Leaders**:
-```
-"Show top 50 hitters by wOBA"
-→ api.get_season_batting_stats(season=12, sort_by='woba', limit=50)
-
-"Who has the most home runs?"
-→ api.get_season_batting_stats(season=12, sort_by='hr', sort_order='desc', limit=10)
-
-"Show qualified batting leaders (min 100 PA)"
-→ api.get_season_batting_stats(season=12, min_pa=100, sort_by='woba', limit=50)
-```
-
-**Pitching Leaders**:
-```
-"Show top 50 pitchers by ERA"
-→ api.get_season_pitching_stats(season=12, sort_by='era', sort_order='asc', limit=50)
-
-"Who has the most strikeouts?"
-→ api.get_season_pitching_stats(season=12, sort_by='k', sort_order='desc', limit=10)
-
-"Show qualified pitching leaders (min 150 outs)"
-→ api.get_season_pitching_stats(season=12, min_outs=150, sort_by='era', limit=50)
-```
-
-**Team Analysis**:
-```
-"Compare team rosters"
-→ cli.py team roster ABBREV (for each team)
-
-"Show team's best players by WARA"
-→ cli.py team roster ABBREV (sorted by WARA in output)
-
-"Check if transactions are compliant"
-→ See "Transaction Compliance Check Workflow" in CLI section
-
-"Analyze team transaction history"
-→ api.get_transactions(season=12, team_abbrev=X)
+# Admin
+cli.py admin recalculate-standings               # Recalculate standings
+cli.py admin refresh-stats                       # Refresh stat views
 ```
 
 ---
 
-## Development Commands
+## Reference Files
 
-### Database API (database/)
-
-**Local Development** (Docker):
-```bash
-cd /mnt/NV2/Development/major-domo/database
-docker-compose up                    # Start all services
-docker-compose up --build            # Rebuild and start
-docker-compose logs -f app           # View API logs
-docker-compose exec app bash         # Shell into API container
-```
-
-**Database Management**:
-```bash
-# Access Adminer (web UI)
-# Visit http://10.10.0.42:8080
-
-# Sync production data to dev
-docker-compose --profile sync up sync-prod
-
-# Database migrations
-python migrations.py
-
-# Or via psql directly
-psql -h 10.10.0.42 -U sba_admin -d sba_master -f migrations/migration_001.sql
-```
-
-### Discord Bot (discord-app/)
-
-**Local Development**:
-```bash
-cd /mnt/NV2/Development/major-domo/discord-app
-python majordomo.py                  # Start bot
-
-# With environment variables
-export BOT_TOKEN='...'
-export API_TOKEN='...'
-export DB_URL='http://10.10.0.42/api/v3'
-export GUILD_ID='...'
-python majordomo.py
-```
-
-**Testing**:
-```bash
-pytest                               # Run all tests
-pytest tests/api_calls/              # Test API integration
-pytest tests/api_calls/test_current.py  # Specific test
-```
-
-### Discord Bot v2 (discord-app-v2/)
-
-**Local Development**:
-```bash
-cd /mnt/NV2/Development/major-domo/discord-app-v2
-python bot.py                        # Start bot
-
-# Testing
-python -m pytest --tb=short -q       # All tests
-python -m pytest tests/test_models.py -v  # Specific test
-python -m pytest tests/test_utils_decorators.py -v  # Decorator tests
-```
-
-**Key Features**:
-- Enhanced logging with `@logged_command` decorator
-- Structured command packages (league, players, teams, voice)
-- Improved type safety with required model IDs
-
-### Website (sba-website/)
-
-**Local Development**:
-```bash
-cd /mnt/NV2/Development/major-domo/sba-website
-npm run dev                          # Development server
-npm run build                        # Build for production
-npm run type-check                   # Type checking only
-```
-
----
-
-## Safety Considerations
-
-### Data Modification
-
-**READ Operations** (Safe):
-- All GET endpoints
-- Player/team/stats queries
-- Standings calculations
-- Search operations
-
-**WRITE Operations** (Require Caution):
-- PATCH/PUT/DELETE endpoints (require API token)
-- Database migrations
-- Standings recalculation
-- Stats refresh operations
-- Transaction modifications
-
-**Always Prompt User Before**:
-- Modifying production data
-- Running database migrations on production
-- Deleting records
-- Recalculating standings
-- Refreshing season statistics
-
-### Discord Bot Safety
-
-**Test Server First**:
-- Use test Discord server for command testing
-- Verify command output before deploying to main server
-- Test with dev database when possible
-
-**Deployment Checklist**:
-- ✅ Tested on dev server
-- ✅ Reviewed code changes
-- ✅ Updated version number
-- ✅ Checked environment variables
-- ✅ Verified API connectivity
-- ✅ Announced downtime if needed
-
----
-
-## File Locations
-
-**Skill Directory**: `~/.claude/skills/major-domo/`
-
-**Structure**:
-```
-major-domo/
-├── SKILL.md (this file)
-├── api_client.py (shared API client)
-├── cli.py (main CLI - mounts sub-apps, core commands)
-├── cli_common.py (shared state, console, output helpers)
-├── cli_transactions.py (transactions list + simulate)
-├── cli_injuries.py (injury listing)
-├── cli_stats.py (batting/pitching leaderboards)
-├── cli_results.py (game results)
-├── cli_schedule.py (game schedules)
-├── cli_admin.py (admin: standings recalculate, stats refresh)
-├── workflows/
-│   ├── bot-deployment.md
-│   ├── weekly-stats-update.md
-│   ├── database-migration.md
-│   └── season-rollover.md
-└── scripts/
-    ├── README.md
-    ├── sync_data.py
-    ├── validate_database.py
-    ├── generate_report.py
-    └── deploy_bot.sh
-```
-
-**Related Codebases**:
-- Database API: `/mnt/NV2/Development/major-domo/database/`
-- Discord Bot (v1): `/mnt/NV2/Development/major-domo/discord-app/`
-- Discord Bot (v2): `/mnt/NV2/Development/major-domo/discord-app-v2/`
-- Website: `/mnt/NV2/Development/major-domo/sba-website/`
-
-**⚠️ WARNING**: Local SQLite databases (*.db files) are development artifacts and always out of date. NEVER use them for queries.
-
----
+| File | Purpose |
+|------|---------|
+| `API_REFERENCE.md` | Full API endpoints, authentication, Python client |
+| `CLI_REFERENCE.md` | Complete CLI commands, flag ordering, workflows |
+| `workflows/bot-deployment.md` | Bot deployment procedure |
+| `workflows/database-migration.md` | Migration procedure |
+| `GETTING_STARTED.md` | Onboarding guide |
 
 ## Environment Variables
 
-**Required**:
-- `API_TOKEN` - API authentication token
-- `DATABASE` - Environment ('prod' or 'dev')
+| Variable | Purpose |
+|----------|---------|
+| `API_TOKEN` | API auth token (required) |
+| `DATABASE` | Environment: `prod` or `dev` |
+| `BOT_TOKEN` | Discord bot auth |
+| `GUILD_ID` | Discord server ID |
+| `DB_URL` | Database API endpoint |
 
-**Discord Bot**:
-- `BOT_TOKEN` - Discord bot authentication
-- `GUILD_ID` - Discord server ID
-- `DB_URL` - Database API endpoint
-
-**Database API** (PostgreSQL):
-- `POSTGRES_HOST` - PostgreSQL hostname (default: 10.10.0.42)
-- `POSTGRES_DB` - Database name (default: sba_master)
-- `POSTGRES_USER` - Database user (default: sba_admin)
-- `POSTGRES_PASSWORD` - Database password
-- `POSTGRES_PORT` - Database port (default: 5432)
-
-**Optional**:
-- `LOG_LEVEL` - Logging level (INFO/WARNING)
-
----
-
-## CLI Application
-
-The `cli.py` provides a command-line interface for common operations, primarily for use with Claude Code.
-
-**Wrapper Script**: `~/.local/bin/majordomo` (uses `uv run` for dependency management)
-
-**⚠️ Claude Code Note**: The wrapper uses `uv run` which may not be available in all contexts. Use the full invocation if needed:
-```bash
-uv run --with typer --with rich --with requests python ~/.claude/skills/major-domo/cli.py <command>
-```
-
-### Commands
+## Development
 
 ```bash
-# Status & Health (use full path in Claude Code)
-python ~/.claude/skills/major-domo/cli.py status    # Current season/week
-python ~/.claude/skills/major-domo/cli.py health    # API health check
-
-# In interactive terminal, alias works:
-majordomo status                              # Current season/week
-majordomo health                              # API health check
-
-# Player Operations
-majordomo player get "Mike Trout"             # Get player info
-majordomo player search "trout"               # Fuzzy search
-majordomo player move "Name" TEAM             # Move single player
-majordomo player move --batch "N1:T1,N2:T2"   # Batch moves
-
-# Team Operations
-majordomo team list [--active]                # List teams
-majordomo team get CAR                        # Get team details
-majordomo team roster CAR                     # Team roster breakdown
-
-# Standings
-majordomo standings [--division ALE]          # League standings
-
-# Transactions
-majordomo transactions --team CLS --week 9    # Team transactions for week
-majordomo transactions list --week-start 1 --week-end 4  # Week range
-majordomo transactions --player "Mike Trout"  # Player-specific transactions
-majordomo transactions simulate CLS "Stott:CLSMiL,Walker:CLS,Castellanos:FA,Martin:CLS"  # Check compliance
-
-# Injuries
-majordomo injuries list --team CLS --active   # Active injuries for team
-majordomo injuries list --sort return-asc     # Sort by return date
-
-# Statistics (Season Leaders)
-majordomo stats batting --sort woba --min-pa 100 --limit 25    # Batting leaders
-majordomo stats pitching --sort era --min-outs 100 --limit 25  # Pitching leaders
-majordomo stats batting --team CLS            # Team batting stats
-
-# Game Results
-majordomo results --team CLS --week 9         # Team results for week
-majordomo results list --week-start 1 --week-end 4  # Results for week range
-
-# Game Schedule
-majordomo schedule --team CLS --week 10       # Team schedule for week
-majordomo schedule list --week-start 10 --week-end 12  # Schedule for week range
-
-# Admin Operations (write + confirm)
-majordomo admin recalculate-standings          # Recalculate standings, show results
-majordomo admin refresh-batting                # Refresh batting materialized view, show top 5
-majordomo admin refresh-pitching               # Refresh pitching materialized view, show top 5
-majordomo admin refresh-stats                  # Refresh both batting + pitching views
-```
-
-### Options
-
-**⚠️ IMPORTANT**: `--env`, `--json`, `--verbose` are **top-level flags** that go BEFORE the subcommand.
-`--season` is a **subcommand flag** that goes AFTER the subcommand.
-
-```bash
-# Top-level flags (BEFORE subcommand)
---env prod|dev    # Environment (default: prod)
---json            # Output as JSON (shows all fields including salary_cap)
---verbose / -v    # Show API request details
-
-# Subcommand flags (AFTER subcommand)
---season / -s N   # Specify season (defaults to current)
-```
-
-**Correct:**
-```bash
-python3 ~/.claude/skills/major-domo/cli.py --json team get CLS
-python3 ~/.claude/skills/major-domo/cli.py --env dev team roster CAN
-```
-
-**Wrong** (will error):
-```bash
-python3 ~/.claude/skills/major-domo/cli.py team get CLS --json    # ❌
-python3 ~/.claude/skills/major-domo/cli.py team roster CAN --env prod  # ❌
-```
-
-### Key Notes
-
-- `team get` shows salary_cap in formatted output; use `--json` for all fields
-- `team roster` shows Active/Short IL/Long IL with WARA values for Active only
-- "Long IL" = MiL (minor leagues)
-- For individual player lookups, use `player get "Name"` — avoid bulk API queries (`/players?team_id=X`) which can timeout on large rosters
-- **Prefer CLI over direct API client** for all standard operations
-- `transactions simulate` validates compliance without making changes — check roster count, WARA limits, salary cap
-- `stats` commands support standard baseball stats sorting (woba, obp, slg, era, whip, fip, etc.)
-- `injuries list` shows return_date, weeks_out, and injury_type for all injured players
-
-### Examples
-
-```bash
-# Roster moves
-python3 ~/.claude/skills/major-domo/cli.py player move --batch "Gerrit Cole:CAN,Robert Suarez:CANMiL"
-
-# Check standings
-python3 ~/.claude/skills/major-domo/cli.py standings --division ALE
-
-# Get team roster
-python3 ~/.claude/skills/major-domo/cli.py team roster CAN
-
-# Get team salary cap (need --json)
-python3 ~/.claude/skills/major-domo/cli.py --json team get CAN
-
-# Check transaction compliance (dry run)
-python3 ~/.claude/skills/major-domo/cli.py transactions simulate CLS "Stott:CLSMiL,Walker:CLS,Castellanos:FA,Martin:CLS"
-
-# View recent transactions
-python3 ~/.claude/skills/major-domo/cli.py transactions --team CLS --week 9
-python3 ~/.claude/skills/major-domo/cli.py transactions list --week-start 1 --week-end 4
-
-# Check injuries
-python3 ~/.claude/skills/major-domo/cli.py injuries list --active
-python3 ~/.claude/skills/major-domo/cli.py injuries list --team CLS
-
-# Season batting leaders
-python3 ~/.claude/skills/major-domo/cli.py stats batting --sort woba --min-pa 100 --limit 25
-python3 ~/.claude/skills/major-domo/cli.py stats batting --team CLS
-
-# Season pitching leaders
-python3 ~/.claude/skills/major-domo/cli.py stats pitching --sort era --min-outs 100 --limit 25
-python3 ~/.claude/skills/major-domo/cli.py stats pitching --team CAN --sort k
-
-# Game results and schedules
-python3 ~/.claude/skills/major-domo/cli.py results --team CLS --week 9
-python3 ~/.claude/skills/major-domo/cli.py schedule --team CLS --week 10
-python3 ~/.claude/skills/major-domo/cli.py schedule list --week-start 10 --week-end 12
-
-# Practical workflows
-# 1. Check if proposed trades are compliant before executing
-python3 ~/.claude/skills/major-domo/cli.py transactions simulate CLS "Player1:CLS,Player2:CLSMiL"
-
-# 2. Review team stats and identify weak positions
-python3 ~/.claude/skills/major-domo/cli.py team roster CLS
-python3 ~/.claude/skills/major-domo/cli.py stats batting --team CLS
-
-# 3. Monitor weekly transactions across the league
-python3 ~/.claude/skills/major-domo/cli.py transactions list --week-start 8 --week-end 9
-
-# 4. Check injury status before setting lineups
-python3 ~/.claude/skills/major-domo/cli.py injuries list --team CLS --active
-
-# 5. Admin: Recalculate standings and refresh stats after weekly import
-python3 ~/.claude/skills/major-domo/cli.py admin recalculate-standings
-python3 ~/.claude/skills/major-domo/cli.py admin refresh-stats
-
-# 6. Admin: Refresh only batting or pitching stats for a specific season
-python3 ~/.claude/skills/major-domo/cli.py admin refresh-batting --season 11
-python3 ~/.claude/skills/major-domo/cli.py admin refresh-pitching --season 11
-```
-
-### Transaction Compliance Check Workflow
-
-**Recommended approach** - Use the simulate command for automatic compliance validation:
-
-```bash
-# Simulate proposed transactions (dry run - no changes made)
-python3 ~/.claude/skills/major-domo/cli.py transactions simulate CLS "Stott:CLSMiL,Walker:CLS,Castellanos:FA,Martin:CLS"
-```
-
-The simulate command automatically validates:
-- Active roster count = 26
-- Total sWAR ≤ salary cap
-- All players exist and can be moved to target destinations
-- Returns detailed compliance report with before/after state
-
-**Manual verification workflow** (if needed):
-
-1. **Get current ML roster**: `cli.py team roster ABBREV` → note player count and WARA values
-2. **Get salary cap**: `cli.py --json team get ABBREV` → read `salary_cap` field
-3. **Look up incoming players**: `cli.py player get "Name"` for each player being added to ML
-4. **Calculate**: Current ML sWAR ± transaction changes ≤ salary_cap, and roster count = 26
-5. **Process moves**: `cli.py player move --batch "Name1:Team1,Name2:Team2"`
-
----
-
-## Quick Reference Commands
-
-### API Client Usage
-
-```bash
-# Test API connection
-cd ~/.claude/skills/major-domo
-python api_client.py --env prod --verbose
-
-# Get current season/week
-python -c "from api_client import MajorDomoAPI; api = MajorDomoAPI('prod'); print(api.get_current())"
-```
-
-### Docker Management
-
-```bash
-# Start all services
+# Database API (Docker)
 cd /mnt/NV2/Development/major-domo/database
-docker-compose up -d
+docker-compose up --build
 
-# View logs
-docker-compose logs -f app
+# Discord Bot
+cd /mnt/NV2/Development/major-domo/discord-app-v2
+python bot.py
 
-# Restart API
-docker-compose restart app
+# Website
+cd /mnt/NV2/Development/major-domo/sba-website
+npm run dev
 
-# Stop all services
-docker-compose down
+# Tests
+cd /mnt/NV2/Development/major-domo/discord-app-v2
+python -m pytest --tb=short -q
 ```
 
-### Database Access
+## Deployment
 
+Use the `deploy` skill for Docker-based deployments:
 ```bash
-# Via Adminer web UI
-# Visit http://10.10.0.42:8080
-
-# Via psql
-psql -h 10.10.0.42 -U sba_admin -d sba_master
-
-# Sync production to dev
-docker-compose --profile sync up sync-prod
-```
-
----
-
-## Workflow Selection
-
-**When user request matches a specific workflow**:
-→ Follow the workflow document
-
-**When user request is ad-hoc query**:
-→ Use API client directly to answer
-
-**Examples**:
-
-| Request | Approach |
-|---------|----------|
-| "Deploy bot to production" | bot-deployment workflow |
-| "Update weekly stats" | weekly-stats-update workflow |
-| "Run database migration" | database-migration workflow |
-| "Show player stats" | Ad-hoc: api.get_player() |
-| "List teams" | Ad-hoc: api.list_teams() |
-| "Start new season" | season-rollover workflow |
-
----
-
-## Deployment (deploy skill)
-
-For Docker-based deployment workflows, use the dedicated `deploy` skill.
-
-**Quick Commands**:
-```bash
-# Dry run (see what would happen)
-~/.claude/skills/deploy/deploy.sh md-discord patch --dry-run
-~/.claude/skills/deploy/deploy.sh md-database minor --dry-run
-
-# Actual deployment
 ~/.claude/skills/deploy/deploy.sh md-discord patch
 ~/.claude/skills/deploy/deploy.sh md-database minor
 ```
 
-**Services**:
-| Service | Docker Image | Production Path |
-|---------|--------------|-----------------|
+| Service | Image | Production Path |
+|---------|-------|-----------------|
 | `md-discord` | `manticorum67/major-domo-discordapp` | `/root/container-data/major-domo` |
 | `md-database` | `manticorum67/major-domo-database` | `/root/container-data/sba-database` |
 
-**Version Bump Types**: `major`, `minor`, `patch`
-
-**Workflow**:
-1. Increment VERSION file
-2. Build Docker image (version + latest tags)
-3. Push to Docker Hub
-4. SSH to akamai, pull and restart container
-5. Git commit and tag
-
 ---
 
-## Additional Resources
-
-**API Documentation**:
-- OpenAPI/Swagger: `http://10.10.0.42/api/docs`
-- Router files: `/mnt/NV2/Development/major-domo/database/app/routers_v3/`
-
-**Database Schema**:
-- `/mnt/NV2/Development/major-domo/database/app/db_engine.py`
-
-**Discord Bot Examples**:
-- Original: `/mnt/NV2/Development/major-domo/discord-app/cogs/`
-- v2: `/mnt/NV2/Development/major-domo/discord-app-v2/commands/`
-
-**Project Documentation**:
-- Database: `/mnt/NV2/Development/major-domo/database/CLAUDE.md`
-- Root: `/mnt/NV2/Development/major-domo/CLAUDE.md`
-
----
-
-**Last Updated**: 2025-11-10
-**Maintainer**: Cal Corum
-**Version**: 1.0
+**Updated**: 2026-03-05
+**Version**: 2.0.0 (modularized)