docs: update llms.txt, README, and CLAUDE.md for construction reference API

Document new construction reference queries, resolved component types on
mechData, equipment builder filters, and equipment-seed scraper command.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: graylikeme

CLAUDE.md

@@ -31,6 +31,12 @@ DATABASE_URL=postgres://postgres:pass@localhost:5432/battletech \
 # Add --force to re-import availability even if rows exist
 # Add --overrides overrides.json for manual MUL ID→slug mappings
 
+# Run the scraper — equipment stats seeding
+DATABASE_URL=postgres://postgres:pass@localhost:5432/battletech \
+  cargo run -p scraper@0.1.0 --release -- equipment-seed \
+  --file data/equipment_stats.json
+# Add --force to overwrite previously-seeded stats
+
 # Seed database from dump (alternative to running the scraper)
 ./seed/load.sh            # uses DATABASE_URL from .env
 
@@ -88,7 +94,7 @@ HTTP POST /graphql
 - `db/models.rs` — `Db*` structs derived from `FromRow`, used only inside the db layer
 - `graphql/types/*.rs` — `*Gql` newtypes wrapping `Db*`, with `#[Object]` impls that expose the GraphQL API
 
-**DataLoader** (`graphql/loaders.rs`): `MechDataLoader` uses async-graphql's `dataloader` feature to batch-load `unit_mech_data` rows, preventing N+1 queries when `mechData` is requested in list queries.
+**DataLoader** (`graphql/loaders.rs`): `MechDataLoader` batch-loads `unit_mech_data` rows. Seven component-type loaders (`EngineTypeLoader`, `ArmorTypeLoader`, `StructureTypeLoader`, `HeatsinkTypeLoader`, `GyroTypeLoader`, `CockpitTypeLoader`, `MyomerTypeLoader`) resolve FK references from `unit_mech_data` to construction reference tables. `AmmoForLoader` and `AmmoTypesLoader` handle ammo↔weapon relationships on equipment. All use async-graphql's `dataloader` feature to prevent N+1 queries.
 
 **Pagination** (`graphql/pagination.rs`): keyset cursors encoded as `base64("sort_val|id:N")`. The `search` functions in `db/units.rs` and `db/equipment.rs` use `QueryBuilder` for dynamic WHERE clauses and `COUNT(*) OVER()` for total count in a single query.
 
@@ -102,7 +108,7 @@ HTTP POST /graphql
 
 ### `crates/scraper` — Data importer (MegaMek + MUL)
 
-Three subcommands: `megamek`, `mul-fetch`, `mul-import`.
+Four subcommands: `megamek`, `mul-fetch`, `mul-import`, `equipment-seed`.
 
 **`megamek`** — Reads a MegaMek `unit_files.zip` and upserts all units into Postgres.
 
@@ -121,6 +127,8 @@ The scraper maintains an in-process `HashMap<slug, equipment_id>` cache to avoid
 
 **`mul-import`** — Imports previously-fetched MUL data from local files into Postgres. Matches MUL units to DB units by slug (exact → normalized → case-insensitive full_name). Updates BV, cost, intro year, role, and MUL ID. Optionally imports faction/era availability from detail pages. Auto-creates new factions discovered in MUL. Outputs `unmatched_mul_units.csv` for manual review.
 
+**`equipment-seed`** — Reads `data/equipment_stats.json` and updates equipment rows by slug match. Uses a static alias map to bridge clean JSON slugs (e.g. `clan-er-large-laser`) to MegaMek-generated DB slugs (e.g. `clerlargelaser`). Without `--force`, only updates NULL columns; with `--force`, overwrites all. Sets `stats_source = 'seed'` and `stats_updated_at = now()`.
+
 **MUL module structure** (`mul/`):
 - `client.rs` — HTTP client with retry (429/5xx), jitter, configurable base URL
 - `quicklist.rs` — JSON deserialization for MUL QuickList endpoint
@@ -134,6 +142,10 @@ The scraper maintains an in-process `HashMap<slug, equipment_id>` cache to avoid
 
 Schema is in `migrations/`. PostgreSQL enums defined: `tech_base_enum`, `rules_level_enum`, `equipment_category_enum`, `location_name_enum`.
 
+**Construction reference tables** (migrations 6 + 8–10): `engine_types`, `armor_types`, `structure_types`, `heatsink_types`, `gyro_types`, `cockpit_types`, `myomer_types` store prescriptive component data for unit builders (weight multipliers, crit slots, rules levels). `engine_weight_table` maps engine ratings to standard weights. `mech_internal_structure` maps mech tonnage to per-location structure points. Seven `*_type_aliases` tables map MegaMek text strings to FK IDs. `unit_mech_data` has FK columns (`engine_type_id`, `armor_type_id`, etc.) linking to reference tables, populated on import via alias resolution. Standard gyro/cockpit/myomer are defaulted when MegaMek omits the field.
+
+**Equipment builder columns** (migration 7): `equipment.observed_locations` (TEXT[], GIN-indexed) tracks which locations equipment appears in across existing units. `equipment.ammo_for_id` links ammo to its parent weapon. `equipment.stats_source` / `stats_updated_at` track provenance.
+
 `tonnage` columns are `NUMERIC(10,1)` (widened in migration 2 from `NUMERIC(6,1)` to accommodate dropships/jumpships up to ~500,000 tons).
 
 Unit slugs are lowercased, non-alphanumeric characters replaced with hyphens and deduplicated (e.g. `"Atlas AS7-D"` → `"atlas-as7-d"`). Chassis slugs include the unit type suffix to avoid collisions between different unit types sharing a name (e.g. `"atlas-mech"`, `"demolisher-vehicle"`). Unit slugs are derived from `"chassis model"`.

README.md

@@ -5,7 +5,7 @@ A GraphQL API serving BattleTech unit, equipment, faction, and era data sourced
 ## Stack
 
 - **API:** Rust · axum 0.8 · async-graphql 7 · sqlx 0.8 · PostgreSQL 16
-- **Scraper:** imports from MegaMek unit files (MTF + BLK formats) and the Master Unit List (BV, roles, availability, clan names)
+- **Scraper:** imports from MegaMek unit files (MTF + BLK formats), the Master Unit List (BV, roles, availability, clan names), and equipment stats seed data
 - **Ops:** Prometheus metrics at `/metrics`, Dockerfile (musl/Alpine), IP rate limiting
 
 ## Quick start
@@ -112,7 +112,7 @@ The server starts on `http://localhost:8080`. In debug builds, GraphiQL is avail
   }
 }
 
-# Single unit with full detail
+# Single unit with full detail and resolved component types
 {
   unit(slug: "atlas-as7-d") {
     fullName
@@ -126,17 +126,21 @@ The server starts on `http://localhost:8080`. In debug builds, GraphiQL is avail
       config
       isOmnimech
       engineRating
-      engineType
       walkMp
       runMp
       jumpMp
       heatSinkCount
-      heatSinkType
-      armorType
-      structureType
-      gyroType
-      cockpitType
-      myomerType
+      # Resolved component types with construction properties
+      engine { name weightMultiplier ctCrits stCrits }
+      armor { name pointsPerTon crits }
+      structure { name weightFraction crits }
+      heatsink { name dissipation crits weight }
+      gyro { name weightMultiplier crits }
+      cockpit { name weight crits }
+      myomer { name }
+      # Raw MegaMek strings (always available as fallback)
+      engineTypeRaw
+      armorTypeRaw
     }
     loadout {
       equipmentName
@@ -214,6 +218,47 @@ The server starts on `http://localhost:8080`. In debug builds, GraphiQL is avail
     }
   }
 }
+
+# Equipment with stats and ammo relationships
+{
+  equipment(slug: "autocannon-10") {
+    name
+    tonnage
+    crits
+    damage
+    heat
+    rangeShort
+    rangeMedium
+    rangeLong
+    bv
+    observedLocations
+    ammoTypes { slug name }
+  }
+}
+
+# Equipment search with builder filters
+{
+  allEquipment(maxTonnage: 2.0, maxCrits: 3, observedLocation: "right_arm") {
+    edges {
+      node { slug name tonnage crits }
+    }
+  }
+}
+
+# Construction reference — all component types in one request
+{
+  constructionReference {
+    engineTypes { slug name techBase weightMultiplier ctCrits stCrits }
+    armorTypes { slug name pointsPerTon crits }
+    structureTypes { slug name weightFraction crits }
+    heatsinkTypes { slug name dissipation crits weight }
+    gyroTypes { slug name weightMultiplier crits }
+    cockpitTypes { slug name weight crits }
+    myomerTypes { slug name }
+    engineWeights { rating standardWeight }
+    internalStructure { tonnage head centerTorso sideTorso arm leg }
+  }
+}
 ```
 
 ### Filters
@@ -234,6 +279,19 @@ The `units` query supports the following filters:
 | `hasJump` | Bool | Jump-capable mechs only |
 | `role` | String | Tactical role (e.g. `"Juggernaut"`, `"Sniper"`, `"Striker"`) |
 
+The `allEquipment` query supports additional builder-oriented filters:
+
+| Filter | Type | Description |
+|--------|------|-------------|
+| `nameSearch` | String | Case-insensitive substring match on equipment name |
+| `category` | String | Equipment category in snake_case (e.g. `"energy_weapon"`) |
+| `techBase` | String | `inner_sphere`, `clan`, `mixed`, `primitive` |
+| `rulesLevel` | String | `introductory`, `standard`, `advanced`, `experimental`, `unofficial` |
+| `maxTonnage` | Float | Equipment weighing at most this many tons |
+| `maxCrits` | Int | Equipment consuming at most this many critical slots |
+| `observedLocation` | String | Equipment observed at this location (e.g. `"right_arm"`) |
+| `ammoForSlug` | ID | Ammo types compatible with this weapon slug |
+
 ### Limits
 
 - Query depth: 20
@@ -343,3 +401,12 @@ All imports are idempotent — inserts use `ON CONFLICT ... DO UPDATE`.
 | `unit_availability` | ~100,000+ | MUL |
 | `eras` | 10 | seed + MUL |
 | `factions` | ~70 | seed + MUL |
+| `engine_types` | 9 | construction ref |
+| `armor_types` | 9 | construction ref |
+| `structure_types` | 6 | construction ref |
+| `heatsink_types` | 4 | construction ref |
+| `gyro_types` | 5 | construction ref |
+| `cockpit_types` | 6 | construction ref |
+| `myomer_types` | 4 | construction ref |
+| `engine_weight_table` | 79 | construction ref |
+| `mech_internal_structure` | 17 | construction ref |

crates/api/src/handlers/llms_txt.rs

@@ -2,7 +2,7 @@ pub fn generate_llms_txt(base_url: &str) -> String {
     format!(
         r#"# BattleTech Data API
 
-> GraphQL API for BattleTech tabletop game data: units (mechs, vehicles, fighters, dropships), equipment (weapons, armor, engines), factions, and eras. Data sourced from MegaMek 0.50.11 (~6,500 units, ~2,875 equipment items) enriched with Master Unit List (MUL) data (BV, roles, availability).
+> GraphQL API for BattleTech tabletop game data: units (mechs, vehicles, fighters, dropships), equipment (weapons, armor, engines), construction reference tables, factions, and eras. Data sourced from MegaMek 0.50.11 (~6,500 units, ~2,875 equipment items) enriched with Master Unit List (MUL) data (BV, roles, availability). Includes construction reference data for unit builders (engine/armor/structure/heatsink/gyro/cockpit/myomer types with weights and crit slots).
 
 ## Endpoint
 
@@ -29,6 +29,8 @@ GET {base_url}/schema.graphql
 - **Tonnage**: weight in metric tons (20–100 for mechs, up to 500,000+ for jumpships)
 - **Range values**: measured in tabletop hexes
 - **Crits**: number of critical hit slots an equipment item occupies
+- **Resolved component types**: `mechData` provides both raw MegaMek strings (e.g. `engineTypeRaw`) and resolved references (e.g. `engine`) with full construction properties (weight multipliers, crit slots, etc.)
+- **Construction reference**: prescriptive data for unit builders — component types with weights, crit slots, and rules; engine weight table; internal structure table
 
 ## Pagination
 
@@ -85,7 +87,7 @@ To paginate: pass `endCursor` from the previous response as `after` in the next
 }}
 ```
 
-### Get a single unit with full loadout, armor, and mech data
+### Get a single unit with full loadout, armor, and resolved component types
 ```graphql
 {{
   unit(slug: "atlas-as7-d") {{
@@ -101,17 +103,24 @@ To paginate: pass `endCursor` from the previous response as `after` in the next
       config
       isOmnimech
       engineRating
-      engineType
       walkMp
       runMp
       jumpMp
       heatSinkCount
-      heatSinkType
-      structureType
-      armorType
-      gyroType
-      cockpitType
-      myomerType
+      engine {{ name weightMultiplier ctCrits stCrits }}
+      armor {{ name pointsPerTon crits }}
+      structure {{ name weightFraction crits }}
+      heatsink {{ name dissipation crits weight }}
+      gyro {{ name weightMultiplier crits }}
+      cockpit {{ name weight crits }}
+      myomer {{ name properties }}
+      engineTypeRaw
+      armorTypeRaw
+      structureTypeRaw
+      heatSinkTypeRaw
+      gyroTypeRaw
+      cockpitTypeRaw
+      myomerTypeRaw
     }}
     loadout {{
       equipmentName
@@ -166,7 +175,7 @@ To paginate: pass `endCursor` from the previous response as `after` in the next
         tonnage
         mechData {{
           config
-          engineType
+          engine {{ name }}
           walkMp
           runMp
           jumpMp
@@ -231,7 +240,7 @@ To paginate: pass `endCursor` from the previous response as `after` in the next
 }}
 ```
 
-### Search equipment
+### Search equipment with builder filters
 ```graphql
 {{
   allEquipment(first: 10, nameSearch: "laser", category: "energy_weapon", techBase: "clan") {{
@@ -240,12 +249,14 @@ To paginate: pass `endCursor` from the previous response as `after` in the next
         slug
         name
         tonnage
+        crits
         damage
         heat
         rangeShort
         rangeMedium
         rangeLong
         bv
+        observedLocations
       }}
     }}
     pageInfo {{
@@ -255,6 +266,78 @@ To paginate: pass `endCursor` from the previous response as `after` in the next
 }}
 ```
 
+### Filter equipment by weight, crits, and location
+```graphql
+{{
+  allEquipment(first: 20, maxTonnage: 2.0, maxCrits: 3, observedLocation: "right_arm") {{
+    edges {{
+      node {{
+        slug
+        name
+        tonnage
+        crits
+        observedLocations
+      }}
+    }}
+  }}
+}}
+```
+
+### Find ammo types for a weapon
+```graphql
+{{
+  equipment(slug: "autocannon-10") {{
+    name
+    ammoTypes {{
+      slug
+      name
+      tonnage
+      bv
+    }}
+  }}
+}}
+```
+
+### Construction reference — fetch all data for builder initialization
+```graphql
+{{
+  constructionReference {{
+    engineTypes {{ slug name techBase weightMultiplier ctCrits stCrits }}
+    armorTypes {{ slug name techBase pointsPerTon crits }}
+    structureTypes {{ slug name techBase weightFraction crits }}
+    heatsinkTypes {{ slug name techBase dissipation crits weight }}
+    gyroTypes {{ slug name weightMultiplier crits }}
+    cockpitTypes {{ slug name weight crits }}
+    myomerTypes {{ slug name properties }}
+    engineWeights {{ rating standardWeight }}
+    internalStructure {{ tonnage head centerTorso sideTorso arm leg }}
+  }}
+}}
+```
+
+### Look up engine weight for a specific rating
+```graphql
+{{
+  engineWeights(rating: 300) {{
+    rating
+    standardWeight
+  }}
+}}
+```
+
+### Look up internal structure for a tonnage
+```graphql
+{{
+  internalStructure(tonnage: 75) {{
+    head
+    centerTorso
+    sideTorso
+    arm
+    leg
+  }}
+}}
+```
+
 ### List all Clan factions
 ```graphql
 {{