Options:
| Option | Default | Description |
|--------|---------|-------------|
| -c, --collection | /collection.csv | Path to BGG collection CSV |
| -o, --output | /valuation.csv | Path to output valuation CSV |
| -f, --force | false | Force re-scrape all games, ignoring cache |
| -r, --region | europe | Region for currency weighting (see below) |
| -C, --currency | SEK | Target currency for valuation (ISO 4217 code) |
| --condition | (inferred) | Default condition for valuation (see Condition System) |

File Locations

| File | Location | Description |
| ---------------- | ----------------------------- | ------------------------------------ |
| Collection CSV | ./collection.csv | Your BGG collection export (input) |
| Exchange rates | ./.data/exchange-rates.json | Cached currency rates (auto-fetched) |
| Price data | ./.data/prices.json | Scraped prices + statistics |
| Valuation report | ./valuation.csv | Final output |

The .data/ directory is created automatically and contains cached data that can be safely deleted.

Data Flow

`
collection.csv (BGG export)
│
▼
┌─────────────┐ ┌──────────────────────┐
│ scrape │────▶│ exchange-rates.json │ (auto-fetched from ECB)
│ command │ └──────────────────────┘
│ │
│ │────▶ prices.json (scraped data + statistics)
└─────────────┘
│
▼
┌─────────────┐
│ valuation │────▶ valuation.csv (final report)
│ command │
└─────────────┘
`

How Valuation Works

$3

The tool uses a sophisticated weighting system that combines three factors multiplicatively. This approach provides more accurate valuations than simple averages or hard outlier removal.

#### 1. Time Weighting

Market prices change over time. Recent sales are more relevant.

- Exponential decay with 1-year half-life
- Today's sale: weight 1.0
- 6 months ago: weight ~0.71
- 1 year ago: weight 0.5
- 2 years ago: weight 0.25
- 3 years ago: weight 0.125

#### 2. Price Weighting (Soft Outliers)

Instead of completely removing outliers (which loses information), extreme prices get reduced weight:

- Gaussian decay from median
- At median: weight 1.0
- 1 IQR from median: weight ~0.61
- 2 IQR from median: weight ~0.14
- 3 IQR from median: weight ~0.01
- Minimum weight: 0.01 (outliers still contribute slightly)

#### 3. Currency Weighting (Region-Based)

Currencies from your preferred region are weighted higher. This accounts for local market conditions and shipping costs.

Supported regions:
| Region | Currencies |
|--------|------------|
| europe (default) | SEK, EUR, DKK, NOK, GBP, CHF, PLN, CZK, HUF, RON, BGN, HRK, ISK, RUB, UAH, TRY |
| americas | USD, CAD, MXN, BRL, ARS, CLP, COP, PEN |
| asia | JPY, CNY, KRW, SGD, HKD, TWD, THB, MYR, PHP, IDR, VND |
| india | INR |
| oceania | AUD, NZD |

Weighting rules:

- When ≥2 sales from your region exist:
- Regional currencies: weight 1.0
- Non-regional currencies: weight 0.3
- When insufficient regional data: all currencies weighted equally

#### Combined Weight Formula

`
combinedWeight = timeWeight × priceWeight × currencyWeight
weightedMean = Σ(value × combinedWeight) / Σ(combinedWeight)
`

This ensures valuations reflect your regional market conditions while still incorporating global data where relevant.

$3

The tool supports per-game condition for more accurate valuations. Each game's condition is determined in priority order:

#### 1. conditiontext from CSV (Highest Priority)

If your BGG collection CSV has a conditiontext column with a value matching a standard BGG condition (case-insensitive), that condition is used for valuation.

Valid values: New, Like New, Very Good, Good, Acceptable

You can add this column to your exported CSV using a spreadsheet editor (Numbers, Excel, etc.).

#### 2. --condition CLI Flag

If no conditiontext is set for a game, the --condition flag provides a global default.

Valid values (kebab-case): new, like-new, very-good, good, acceptable

`bash
geek-valuation valuation --condition like-new
geek-valuation all --condition very-good
`

#### 3. Inferred from Play Count

If neither conditiontext nor --condition is set, condition is inferred from numplays:

| Plays | Inferred Condition |
| ----- | ------------------ |
| 0-1 | New |
| 2-10 | Like New |
| 11-15 | Very Good |
| 16-25 | Good |
| 26+ | Acceptable |

These thresholds can be customized in src/constants.ts (see Customizing Condition Thresholds).

#### 4. Ultimate Fallback

If none of the above apply, defaults to Like New.

#### Market Data Condition Fallback

Once the game's condition is determined, the tool looks for market data matching that condition. If no exact match exists, it falls back through the condition priority order:

1. New (highest value)
2. Like New
3. Very Good
4. Good
5. Acceptable (lowest value)

The source column in the output CSV indicates whether an exact match was found or a fallback was used (e.g., market:like-new(fallback)).

#### Customizing Condition Thresholds

Edit src/constants.ts to customize the condition inference thresholds:

`typescript
export const CONDITION_PLAY_THRESHOLDS = {
NEW_MAX_PLAYS: 1, // 0-1 plays = New
LIKE_NEW_MAX_PLAYS: 10, // 2-10 plays = Like New
VERY_GOOD_MAX_PLAYS: 15, // 11-15 plays = Very Good
GOOD_MAX_PLAYS: 25, // 16-25 plays = Good
// 26+ plays = Acceptable
};

// Default condition when nothing else applies
export const DEFAULT_CONDITION = Condition.LIKE_NEW;
`

$3

For rare games, new releases, or expansions without sales history:

- Estimates value as 60% of purchase price
- This is conservative but better than showing zero
- The 60% figure is a rough industry average for board game depreciation

$3

Raw marketplace data contains anomalies:

- Bulk sales at deep discounts
- Mislabeled conditions
- Rare variants or signed copies

The tool uses soft weighting instead of removing outliers:

- Prices near the median get full weight
- Prices further away get progressively lower weight
- Even extreme outliers contribute slightly (weight ≥0.01)

This preserves all information while reducing the influence of anomalies.

Exchange Rates

- Rates are fetched automatically from the Frankfurter API (ECB data)
- Cached locally and refreshed daily (stale if date is not today)
- Prices are stored internally in USD for consistency
- At valuation time, prices are converted to your target currency (default: SEK)
- The cache supports multiple base currencies for efficient conversion
- If the API is unavailable, stale cached rates are used as fallback
- Unknown currencies in purchase prices are converted using 1:1 ratio with a warning

Scraping Behavior

$3

To be respectful to BGG's servers:

- Random 250-1000ms delay between requests
- Progress saved every 10 games
- Caching prevents re-scraping known games

$3

Failed requests are automatically retried:

- Up to 2 retry attempts per game
- 2-second delay between retries
- Helps handle transient network issues

$3

During scraping, the tool shows:

- Current progress (e.g., [42/392])
- Estimated time remaining
- Number of games left to scrape

A full scrape of ~400 games takes approximately 15-20 minutes.

Troubleshooting

$3

This is normal. Many games (especially expansions, promos, and obscure titles) have never been sold on BGG's marketplace.

$3

Just run the command again. Games already in prices.json with data are skipped automatically. Use --force to re-scrape everything.

$3

The tool will use cached rates if available. If no cache exists and the API is down, wait and try again later.

$3

If your collection has purchase prices in currencies not supported by the ECB (exotic currencies), the tool will:

1. Warn loudly during scraping
2. Assume the currency is USD for conversion
3. Report all such conversions at the end of the scrape

Review these warnings and verify the valuations are correct.

$3

Some price formats on BGG aren't recognized. The tool logs these for debugging. Common formats are supported; exotic ones may be skipped.

$3

Make sure you have Chrome installed. If running in a containerized environment, you may need additional dependencies:

`bash


Debian/Ubuntu