---
name: paper-dynasty
description: Paper Dynasty baseball card game management. USE WHEN user mentions Paper Dynasty, gauntlet teams, player cards, scouting reports, pack distribution, rewards, or card game database operations.
---

# Paper Dynasty - Baseball Card Game Management

**SCOPE**: Only use in paper-dynasty, paper-dynasty-database repos. Do not activate in unrelated projects.


---

## When to Activate This Skill

**Database Operations**:
- "Sync prod to dev" / "Copy production database"
- "Pull production data to dev"

**Structured Operations**:
- "Clean up gauntlet team [name]"
- "Generate weekly cards" / "run card workflow"
- "Update scouting" / "regenerate scouting reports"
- "Distribute [N] packs to all teams"
- "Wipe team [abbrev] cards"

**Discord Bot Troubleshooting**:
- "Check pd-discord logs" / "restart bot"
- "Is the bot running?" / "bot status"

**Ad-Hoc Queries**:
- "How many cards does team SKB have?"
- "Show me all MVP rarity players"
- "List all teams in season 5"
- "Find active gauntlet runs"

**Ecosystem & Cross-Project**:
- "PD status" / "ecosystem status" / "what needs work"
- "Show PD ecosystem status" / "What's the status across all projects?"

**Growth & Engagement**:
- "growth roadmap" / "engagement" / "user retention"

> **For deployment**, use the `deploy` skill instead.

---

## What is Paper Dynasty?

A baseball card TCG with digital player cards, team collection, game simulation, and gauntlet tournaments.

**Key Components**:
- **API**: `pd.manticorum.com` (prod) / `pddev.manticorum.com` (dev)
- **Discord Bot**: On `sba-bots` server
- **Card Generation**: `/mnt/NV2/Development/paper-dynasty/card-creation/`

---

## Critical Rules

### CLI-First for ALL Operations

✅ **ALWAYS** use CLI tools first — they handle auth, formatting, and error handling
❌ **NEVER** write raw Python API calls when a CLI command exists
❌ **NEVER** access local SQLite directly

**paperdomo CLI** (queries, packs, gauntlet, teams):
```bash
python ~/.claude/skills/paper-dynasty/cli.py [command]
```

**pd-cards CLI** (card generation, scouting, uploads):
```bash
cd /mnt/NV2/Development/paper-dynasty/card-creation
pd-cards [command]
```

Only fall back to the Python API (`api_client.py`) for complex multi-step operations that the CLI doesn't cover (e.g., batch cleanup loops, custom card creation).

**For CLI reference**: `reference/cli-overview.md` (links to per-command files)

---

## Workflows

| Workflow | Trigger | Quick Command |
|----------|---------|---------------|
| **Database Sync** | "Sync prod to dev" | `~/.claude/skills/paper-dynasty/scripts/sync_prod_to_dev.sh` |
| **Gauntlet Cleanup** | "Clean up gauntlet team X" | `$PD gauntlet cleanup Gauntlet-X -e N -y` |
| **Pack Distribution** | "Give N packs to everyone" | `$PD pack distribute --num N` |
| **Scouting Update** | "Update scouting" | `pd-cards scouting all -c 27` |
| **Card Generation (Retrosheet)** | "Generate cards for 2005" | **Use `retrosheet-card-update` agent** |
| **Card Generation (Live Series)** | "Update live series cards" | **Use `live-series-card-update` agent** |
| **Custom Cards** | "Create custom player" | `pd-cards custom preview name` |
| **S3 Upload** | "Upload cards to S3" | `pd-cards upload s3 -c "2005 Live"` |
| **Bot Troubleshooting** | "Check bot logs" | `ssh sba-bots "docker logs paper-dynasty_discord-app_1 --tail 100"` |

**Detailed workflow docs**: `workflows/` directory

### Gauntlet Cleanup Safety

**Safe to clean**: Gauntlet teams (temporary), completed runs, eliminated teams
**Never clean**: Regular season teams, teams with active gameplay, before tournament ends

| Data | Action | Reversible? |
|------|--------|-------------|
| Cards | Unassigned (team = NULL) | Yes (reassign) |
| Packs | Deleted | No |
| Run Record | Ended (timestamp set) | Kept in DB |
| Team/Results/Stats | Preserved | Kept in DB |

**Batch cleanup** (all active runs in an event):
```python
runs = api.list_gauntlet_runs(event_id=8, active_only=True)
for run in runs:
    team_id = run['team']['id']
    api.wipe_team_cards(team_id)
    for pack in api.list_packs(team_id=team_id):
        api.delete_pack(pack['id'])
    api.end_gauntlet_run(run['id'])
```

### Database Sync Notes

**Restore a dev backup**:
```bash
BACKUP_FILE=~/.paper-dynasty/db-backups/paperdynasty_dev_YYYYMMDD_HHMMSS.sql
ssh pd-database "docker exec -i sba_postgres psql -U sba_admin -d paperdynasty_dev" < "$BACKUP_FILE"
```

**Manual fallback** (if script fails):
```bash
ssh akamai "docker exec sba_postgres pg_dump -U pd_admin -d pd_master --clean --if-exists" > /tmp/pd_prod_dump.sql
ssh pd-database "docker exec -i sba_postgres psql -U sba_admin -d paperdynasty_dev" < /tmp/pd_prod_dump.sql
```

**Large databases**: Pipe through `gzip`/`gunzip` for compressed transfer.

---

## Discord Bot

**Server**: `sba-bots` (10.10.0.88) | **Container**: `paper-dynasty_discord-app_1` | **Compose Dir**: `/home/cal/container-data/paper-dynasty/`

Related services: PostgreSQL (`paper-dynasty_db_1`), Adminer (`paper-dynasty_adminer_1`, port 8080 — user: `postgres`, pass: `example`, server: `db`)

```bash
# Check status
ssh sba-bots "docker ps --filter name=paper-dynasty"

# View logs
ssh sba-bots "docker logs paper-dynasty_discord-app_1 --tail 100"

# Follow logs
ssh sba-bots "docker logs paper-dynasty_discord-app_1 -f --tail 50"

# Restart bot
ssh sba-bots "cd /home/cal/container-data/paper-dynasty && docker compose restart discord-app"

# Database CLI
ssh sba-bots "docker exec -it paper-dynasty_db_1 psql -U postgres"
```

**Key env vars** (in docker-compose.yml): `BOT_TOKEN`, `GUILD_ID`, `API_TOKEN`, `DATABASE` (Prod/Dev), `LOG_LEVEL`, `DB_URL` (usually `db`), `SCOREBOARD_CHANNEL`

---

## Common Patterns

```bash
PD="python ~/.claude/skills/paper-dynasty/cli.py"

# Teams
$PD team get SKB                          # Single team details
$PD team list --season 10                 # All teams in a season
$PD team cards SKB                        # Team's card collection

# Players
$PD player get 12785                      # Single player details
$PD player list --rarity MVP --cardset 27 # Filtered player list

# Packs
$PD status                                # Packs opened today
$PD pack list --team SKB --unopened       # Team's unopened packs
$PD pack distribute --num 10              # Give 10 packs to all teams
$PD pack distribute --num 5 --exclude CAR # Exclude a team

# Gauntlet
$PD gauntlet list --active                # Active gauntlet runs
$PD gauntlet teams --active               # Active gauntlet teams
$PD gauntlet cleanup Gauntlet-SKB -e 9 -y # Wipe a gauntlet team
```

Add `--json` to any command for machine-readable output. Add `--env dev` for dev database.

---

## Quick Reference

### Environment Setup
```bash
export API_TOKEN='your-token'
export DATABASE='prod'  # or 'dev'
```

### Key IDs
- **Current Live Cardset**: 27 (2005 Live)
- **Default Pack Type**: 1 (Standard)
- **Rarities**: Replacement < Reserve < Starter < All-Star < MVP < Hall of Fame

**For full schema**: `reference/database-schema.md`

### pd-cards Commands
```bash
cd /mnt/NV2/Development/paper-dynasty/card-creation

pd-cards custom list/preview/submit              # Custom cards
pd-cards scouting all -c 27                      # Scouting reports
pd-cards retrosheet process 2005 -c 27 -d Live   # Card generation
pd-cards upload s3 -c "2005 Live"                # S3 upload
```

### paperdomo Commands
```bash
PD="python ~/.claude/skills/paper-dynasty/cli.py"
$PD health                        # API health check
$PD status                        # Packs opened today
$PD team list/get/cards            # Team operations
$PD player get/list                # Player operations
$PD pack list/today/distribute     # Pack operations
$PD gauntlet list/teams/cleanup    # Gauntlet operations
```

---

## File Structure

```
~/.claude/skills/paper-dynasty/
├── SKILL.md              # This file (routing & quick reference)
├── api_client.py         # Python API client
├── cli.py                # paperdomo CLI
├── reference/
│   ├── database-schema.md    # Models, cardsets, pack types, rarities
│   ├── api-reference.md      # Endpoints, authentication, client examples
│   ├── cli-overview.md       # CLI routing table — load this first
│   └── cli/
│       ├── team.md           # team list/get/cards
│       ├── pack.md           # pack list/today/distribute + pack type IDs
│       ├── player.md         # player get/list
│       ├── gauntlet.md       # gauntlet list/teams/cleanup
│       └── pd-cards.md       # custom/scouting/retrosheet/upload/live-series
├── workflows/
│   ├── card-generation.md       # Retrosheet reference (pipeline now in retrosheet-card-update agent)
│   ├── live-series-update.md    # Live series reference (pipeline now in live-series-card-update agent)
│   ├── card_utilities.py        # Card refresh pipeline (fetch → S3 → update)
│   ├── custom-card-creation.md  # Archetypes, manual creation, rating rules
│   └── TROUBLESHOOTING.md       # Card rendering issues
└── scripts/
    ├── distribute_packs.py
    ├── gauntlet_cleanup.py
    └── validate_database.py
```

**Related Codebases**:
- Database/API: `/mnt/NV2/Development/paper-dynasty/database/`
- Discord Bot: `/mnt/NV2/Development/paper-dynasty/discord-app/`
- Card Creation: `/mnt/NV2/Development/paper-dynasty/card-creation/`

---

## When to Load Additional Context

| Need | Load |
|------|------|
| Database model details | `reference/database-schema.md` |
| API endpoints & client usage | `reference/api-reference.md` |
| CLI command reference | `reference/cli-overview.md` → load `cli/team.md`, `cli/pack.md`, `cli/player.md`, `cli/gauntlet.md`, or `cli/pd-cards.md` |
| Retrosheet card workflow / PotM | **Use `retrosheet-card-update` agent** (ref: `workflows/card-generation.md`) |
| Live series workflow / PotM | **Use `live-series-card-update` agent** (ref: `workflows/live-series-update.md`) |
| Card rendering issues | `workflows/TROUBLESHOOTING.md` |

---

---

## Ecosystem Dashboard

Provides a cross-project view of all Paper Dynasty Gitea repos in a single terminal dashboard.

**Script**: `~/.claude/skills/paper-dynasty/scripts/ecosystem_status.sh`

**Trigger phrases**:
- "Show PD ecosystem status"
- "What's the status across all projects?"
- "PD status" / "ecosystem status" / "what needs work"

**Usage**:
```bash
# Requires GITEA_TOKEN in env (or auto-reads from gitea-mcp config)
~/.claude/skills/paper-dynasty/scripts/ecosystem_status.sh
```

**What it shows**:
- Open issue count per repo
- Open PR count per repo
- Latest commit SHA + date per repo
- Recent commits (last 3) per repo with author and message
- Open issue titles grouped by repo (with labels)
- Open PR titles grouped by repo (with branch info)
- Cross-repo totals

**Repos covered**: paper-dynasty-database, paper-dynasty-discord, paper-dynasty-card-creation, paper-dynasty-website

**Auth**: Uses `GITEA_TOKEN` env var. If unset, attempts to read from `~/.config/claude-code/mcp-servers/gitea-mcp.json`.

---

## Initiative Tracker (`pd-plan`)

Local SQLite database tracking cross-project initiatives, priorities, and status.

**CLI**: `python ~/.claude/skills/paper-dynasty/plan/cli.py [command]`
**Database**: `~/.claude/skills/paper-dynasty/plan/initiatives.db`

**Trigger phrases**:
- "what should I work on" / "what's the priority"
- "initiative status" / "pd-plan" / "show priorities"
- "update initiative" / "mark done"

**Quick reference**:
```bash
PDP="python ~/.claude/skills/paper-dynasty/plan/cli.py"

$PDP summary                         # Dashboard — run at session start
$PDP list                            # All active initiatives
$PDP list --phase 1                  # Phase 1 only
$PDP list --repo discord             # Filter by repo
$PDP next                            # Highest priority non-blocked item
$PDP next --repo discord             # Next for a specific repo
$PDP show 1                          # Full details + activity log
$PDP add "Title" --phase 1 --priority 20 --impact retention --size M --repos discord
$PDP update 3 --status in_progress --actor pd-discord
$PDP update 3 --note "Merged 8 PRs" --actor pd-ops
$PDP update 3 --link "discord#104"   # Append linked issue
$PDP done 3 --actor pd-ops           # Mark complete
$PDP list --json                     # Machine-readable output
```

**Session startup**: Always run `pd-plan summary` at the start of a Paper Dynasty session to understand current priorities.

---

## Growth Roadmap

High-level roadmap for Paper Dynasty player growth, engagement, and retention strategies.

**File**: `/mnt/NV2/Development/paper-dynasty/ROADMAP.md`

**Trigger phrases**:
- "growth roadmap" / "engagement" / "user retention"
- "what's planned" / "next features"

Load the roadmap file for context before discussing growth priorities, feature planning, or retention strategies. Use `pd-plan` for current status of specific initiatives.

---

## Specialized Agents

Dispatch work to these agents for their respective domains. Do not do their work inline — launch them explicitly.

| Agent | Model | Domain | Dispatch When |
|-------|-------|--------|---------------|
| `pd-database` | Opus | Database/API | Schema changes, endpoints, migrations, data model |
| `pd-discord` | Opus | Discord bot | Commands, gameplay engine, bot UX |
| `pd-cards` | Opus | Card pipeline | Card generation, ratings, scouting, rendering |
| `pd-growth` | Opus | Product growth | Engagement, retention, roadmap prioritization |
| `pd-ops` | Sonnet | Release ops | Merging PRs, deploys, branch cleanup, process |

PO agents (Opus) decide **what** to build. `pd-ops` ensures it **ships correctly**. Implementation is delegated to `engineer`, `issue-worker`, or `swarm-coder`.

**How to dispatch**: Mention the agent name explicitly, e.g. "use the pd-cards agent to regenerate scouting" or "dispatch to pd-database for this migration".

---

**Last Updated**: 2026-03-22
**Version**: 2.8 (Added pd-plan initiative tracker, pd-ops agent, updated agent table with models)