feat: rough pharmacy skill added

1 files changed, 950 insertions, 0 deletions

diff --git a/skill_plans/scavenging.md b/skill_plans/scavenging.md
new file mode 100644
index 0000000..5dc7d39
--- /dev/null
+++ b/skill_plans/scavenging.md
@@ -0,0 +1,950 @@
+# Scavenging Skill Implementation Plan
+
+## 1. Overview
+
+Scavenging is the Runecrafting analog for The House of Icarus. The skill has two phases:
+
+1. **Mining scrap** — Gather `scrap_metal` from scrap pile objects using a pickaxe (Mining skill). This already works via `data/behaviors/mine_scrap.yaml` and `data/objects/scrap_pile.yaml`. The item `data/items/scrap_metal.yaml` exists and is non-stackable.
+2. **Identifying junk** — Take scrap to an altar station. With the correct identifier tool in inventory, type `id` (or `use <altar>`). On the next tick, ALL scrap in the player's inventory is converted into the corresponding junk type. Output quantity is `scrap_count × multiplier`, where multiplier increases with Scavenging level (like OSRS double runes).
+
+There are 4 junk types, each requiring a specific identifier tool and altar:
+
+| Junk Type | Identifier Tool | Altar Station | Level Req | XP/scrap |
+|-----------|----------------|---------------|-----------|----------|
+| Solarjunk | Solar Identifier | Solar Altar | 1 | 5 |
+| Hydrojunk | Hydro Identifier | Hydro Altar | 14 | 8 |
+| Ecojunk | Eco Identifier | Eco Altar | 28 | 12 |
+| Biojunk | Bio Identifier | Bio Altar | 44 | 16 |
+
+The Scavenging skill constant already exists in `internal/player/player.go:28` as `Scavenging SkillName = "scavenging"` with abbreviation `"scv"`.
+
+---
+
+## 2. Commands
+
+### New Command: `id`
+
+| Property | Value |
+|----------|-------|
+| Command | `id` |
+| Aliases | `identify` |
+| Class | `ClassActive` |
+| Handler | `g.doIdentify(sess, args)` |
+| Action Type | `"identify"` |
+| ActionState | `ActionIdentifying` |
+| Ticks | 1 (instant conversion on next tick) |
+
+**Behavior:** When the player types `id`:
+1. Cancel any active action.
+2. Scan the room for an altar object (`solar_altar`, `hydro_altar`, `eco_altar`, `bio_altar`).
+3. If no altar found: `"There is no altar here."`
+4. Determine the junk type from the altar type.
+5. Check the player has the matching identifier tool in inventory or equipment.
+6. If no identifier: `"You need a <type> identifier to use this altar."`
+7. Check the player has at least one `scrap_metal` in inventory.
+8. If no scrap: `"You don't have any scrap metal."`
+9. Check player's Scavenging level meets the junk's level requirement.
+10. If too low: `"You need level <N> scavenging to identify <junk type>."`
+11. Create a 1-tick `"identify"` action.
+12. On advance: count all `scrap_metal` slots, remove them, calculate multiplier, add junk, award XP.
+
+**`use <altar>` path:** The `id` command is the primary interface. Additionally, `use` on an altar without specifying an item should route to the same `doIdentify` logic. This can be handled by giving each altar object a `behavior` that points to a behavior YAML with `type: use`, OR by special-casing altar IDs in the `use` command handler. The recommended approach is to add `use_interactions` on each altar object YAML that triggers the identify logic (see Section 6).
+
+### Classification and Dispatch Changes
+
+**File: `internal/game/game.go`**
+
+In `classifyCommand()` at line 136, add `"id"` and `"identify"` to the `ClassActive` list:
+
+```go
+case "get", "take", "grab", "pick", "drop",
+    "attack", "kill",
+    "north", "n", "south", "s", "east", "e",
+    "west", "w", "up", "u", "down", "d",
+    "quit", "use", "burn", "stoke", "search", "walk", "cook", "smelt", "smith", "craft",
+    "id", "identify":
+    return ClassActive
+```
+
+In `executeCommand()` (around line 249), add a case:
+
+```go
+case "id", "identify":
+    g.doIdentify(sess, strings.Join(args, " "))
+    return
+```
+
+---
+
+## 3. New Files to Create
+
+### Go Files
+
+| File | Purpose |
+|------|---------|
+| `internal/game/cmd_id.go` | `doIdentify()` handler — validate altar, identifier, scrap; create action |
+| `internal/game/action_identify.go` | `startIdentify()` and `advanceIdentify()` — the conversion logic |
+
+### YAML Files — Items
+
+| File | Description |
+|------|-------------|
+| `data/items/solar_identifier.yaml` | Solar Identifier tool |
+| `data/items/hydro_identifier.yaml` | Hydro Identifier tool |
+| `data/items/eco_identifier.yaml` | Eco Identifier tool |
+| `data/items/bio_identifier.yaml` | Bio Identifier tool |
+| `data/items/solarjunk.yaml` | Solarjunk (stackable output) |
+| `data/items/hydrojunk.yaml` | Hydrojunk (stackable output) |
+| `data/items/ecojunk.yaml` | Ecojunk (stackable output) |
+| `data/items/biojunk.yaml` | Biojunk (stackable output) |
+
+### YAML Files — Objects
+
+| File | Description |
+|------|-------------|
+| `data/objects/solar_altar.yaml` | Solar Altar station |
+| `data/objects/hydro_altar.yaml` | Hydro Altar station |
+| `data/objects/eco_altar.yaml` | Eco Altar station |
+| `data/objects/bio_altar.yaml` | Bio Altar station |
+
+### YAML Files — Help
+
+| File | Description |
+|------|-------------|
+| `data/help/id.yaml` | Help for the `id` command |
+| `data/help/scavenging.yaml` | Help for the Scavenging skill |
+
+---
+
+## 4. Code Changes to Existing Files
+
+### `internal/game/game.go`
+
+1. **`classifyCommand()`** (line 136): Add `"id"`, `"identify"` to `ClassActive` case.
+2. **`executeCommand()`** (line 249): Add `case "id", "identify":` dispatching to `g.doIdentify(sess, strings.Join(args, " "))`.
+
+### `internal/game/action_state.go`
+
+Add the new ActionType constant:
+
+```go
+ActionIdentifying ActionType = "identifying"
+```
+
+Add a case in `Description()`:
+
+```go
+case ActionIdentifying:
+    return "identifying scrap at " + a.TargetName
+```
+
+### `internal/game/action.go`
+
+In `AdvanceActions()` (line 225), add a case in the switch:
+
+```go
+case "identify":
+    g.advanceIdentify(sess, p)
+```
+
+### `internal/game/game.go` — `ProcessQueuedCommands()`
+
+In the `ActionState` clearing logic (line 472), the `ActionIdentifying` type is a 1-tick action like `ActionPickingUp`. It does NOT need to persist in the list of long-running actions. After the advance tick fires and completes, the action is nil'd and the state clears naturally. No changes needed here — the `default` branch at line 474 already clears non-persistent action states.
+
+---
+
+## 5. Items — Full YAML Definitions
+
+### `data/items/scrap_metal.yaml` (ALREADY EXISTS — verify)
+
+```yaml
+id: scrap_metal
+name: scrap metal
+color: "243"
+description: "A chunk of salvaged scrap metal."
+value: 2
+stackable: false
+```
+
+This already exists at `data/items/scrap_metal.yaml`. No changes needed. Scrap metal is intentionally non-stackable (like rune essence in OSRS — each piece takes an inventory slot, limiting how many you can carry per trip to 28).
+
+### `data/items/solar_identifier.yaml`
+
+```yaml
+id: solar_identifier
+name: solar identifier
+color: "220"
+description: "A handheld scanner calibrated to isolate solar-frequency signatures in scrap metal. Required to produce solarjunk at a solar altar."
+value: 500
+```
+
+### `data/items/hydro_identifier.yaml`
+
+```yaml
+id: hydro_identifier
+name: hydro identifier
+color: "39"
+description: "A handheld scanner calibrated to isolate hydro-frequency signatures in scrap metal. Required to produce hydrojunk at a hydro altar."
+value: 1000
+```
+
+### `data/items/eco_identifier.yaml`
+
+```yaml
+id: eco_identifier
+name: eco identifier
+color: "34"
+description: "A handheld scanner calibrated to isolate eco-frequency signatures in scrap metal. Required to produce ecojunk at an eco altar."
+value: 2500
+```
+
+### `data/items/bio_identifier.yaml`
+
+```yaml
+id: bio_identifier
+name: bio identifier
+color: "196"
+description: "A handheld scanner calibrated to isolate bio-frequency signatures in scrap metal. Required to produce biojunk at a bio altar."
+value: 5000
+```
+
+### `data/items/solarjunk.yaml`
+
+```yaml
+id: solarjunk
+name: solarjunk
+color: "220"
+description: "A fragment of reclaimed solar circuitry. Used as a universal energy medium."
+value: 10
+stackable: true
+```
+
+### `data/items/hydrojunk.yaml`
+
+```yaml
+id: hydrojunk
+name: hydrojunk
+color: "39"
+description: "A fragment of reclaimed hydro circuitry. Used as a universal energy medium."
+value: 18
+stackable: true
+```
+
+### `data/items/ecojunk.yaml`
+
+```yaml
+id: ecojunk
+name: ecojunk
+color: "34"
+description: "A fragment of reclaimed eco circuitry. Used as a universal energy medium."
+value: 30
+stackable: true
+```
+
+### `data/items/biojunk.yaml`
+
+```yaml
+id: biojunk
+name: biojunk
+color: "196"
+description: "A fragment of reclaimed bio circuitry. Used as a universal energy medium."
+value: 50
+stackable: true
+```
+
+---
+
+## 6. Objects — Full YAML Definitions
+
+### `data/objects/solar_altar.yaml`
+
+```yaml
+id: solar_altar
+name: solar altar
+color: "220"
+description: "A humming altar of golden circuitry. Place scrap metal here with a solar identifier to produce solarjunk. Type 'id' to begin."
+```
+
+### `data/objects/hydro_altar.yaml`
+
+```yaml
+id: hydro_altar
+name: hydro altar
+color: "39"
+description: "A pulsing altar of blue crystalline conduits. Place scrap metal here with a hydro identifier to produce hydrojunk. Type 'id' to begin."
+```
+
+### `data/objects/eco_altar.yaml`
+
+```yaml
+id: eco_altar
+name: eco altar
+color: "34"
+description: "A thrumming altar of green organic circuits. Place scrap metal here with an eco identifier to produce ecojunk. Type 'id' to begin."
+```
+
+### `data/objects/bio_altar.yaml`
+
+```yaml
+id: bio_altar
+name: bio altar
+color: "196"
+description: "A sinister altar of red biological interfaces. Place scrap metal here with a bio identifier to produce biojunk. Type 'id' to begin."
+```
+
+---
+
+## 7. Rooms
+
+### Existing Room: Room 9 — Scavenging Post
+
+Currently at `data/rooms/9.yaml`:
+
+```yaml
+id: 9
+name: "Scavenging Post"
+description: "A cluttered yard full of scrap metal and discarded technology. This area is not yet accessible."
+exits:
+  east: 10
+  west: 8
+```
+
+**Update room 9** to add scrap pile objects and a useful description:
+
+```yaml
+id: 9
+name: "Scavenging Post"
+description: "A cluttered yard full of {243}scrap metal{/} and discarded technology. Piles of salvageable debris are scattered across the ground. The air smells of ozone and rust."
+exits:
+  east: 10
+  west: 8
+objects:
+  - id: scrap_pile
+  - id: scrap_pile
+  - id: scrap_pile
+```
+
+### New Altar Rooms
+
+Create 4 new rooms for the altars. These should branch off from or near the Scavenging Post area. The exact room IDs depend on the next available IDs in the codebase. Check `data/rooms/` for the highest existing ID and use the next sequential numbers.
+
+**Suggested room layout:**
+- Room 9 (Scavenging Post) — hub with scrap piles
+- New rooms branching from room 9 or nearby rooms for each altar
+
+Example new room files (IDs are placeholders — use next available):
+
+#### `data/rooms/<next_id>.yaml` — Solar Altar Chamber
+
+```yaml
+id: <next_id>
+name: "Solar Altar Chamber"
+description: "A circular chamber bathed in warm {220}golden light{/}. At its center stands a humming {220 bold}solar altar{/}, its surface etched with fractal circuit patterns that glow softly."
+exits:
+  south: 9
+objects:
+  - id: solar_altar
+```
+
+#### `data/rooms/<next_id+1>.yaml` — Hydro Altar Chamber
+
+```yaml
+id: <next_id+1>
+name: "Hydro Altar Chamber"
+description: "Condensation drips from the ceiling of this cool, blue-lit chamber. A {39 bold}hydro altar{/} dominates the room, its crystalline surface rippling with patterns like flowing water."
+exits:
+  south: 9
+objects:
+  - id: hydro_altar
+```
+
+#### `data/rooms/<next_id+2>.yaml` — Eco Altar Chamber
+
+```yaml
+id: <next_id+2>
+name: "Eco Altar Chamber"
+description: "Bioluminescent moss covers the walls of this overgrown chamber. An {34 bold}eco altar{/} rises from the floor, entwined with living circuitry that pulses with green light."
+exits:
+  south: 9
+objects:
+  - id: eco_altar
+```
+
+#### `data/rooms/<next_id+3>.yaml` — Bio Altar Chamber
+
+```yaml
+id: <next_id+3>
+name: "Bio Altar Chamber"
+description: "The air here is thick and warm. A {196 bold}bio altar{/} throbs at the center of the room, its surface covered in red organic membranes threaded with copper wire."
+exits:
+  south: 9
+objects:
+  - id: bio_altar
+```
+
+**Update room 9 exits** to add north exits (or other directions) to the altar rooms. The exact exit directions depend on the room layout. Add exits from room 9 to each altar room, e.g.:
+
+```yaml
+exits:
+  east: 10
+  west: 8
+  north: <solar_altar_room_id>
+```
+
+Or create an intermediate hub room that branches to all 4 altars.
+
+**To determine actual room IDs:** Run `ls data/rooms/ | sort -n | tail -5` to find the highest existing room ID, then use sequential IDs after that.
+
+---
+
+## 8. Mechanics — The `id` Command
+
+### Flow Diagram
+
+```
+Player types "id" (or "identify")
+    │
+    ├── CancelAction(p)
+    │
+    ├── Scan room for altar objects
+    │   └── Check: solar_altar, hydro_altar, eco_altar, bio_altar
+    │   └── If none found: "There is no altar here." → return
+    │
+    ├── Determine altar type → junk mapping
+    │   ├── solar_altar → solarjunk (req: solar_identifier, level 1, 5 XP)
+    │   ├── hydro_altar → hydrojunk (req: hydro_identifier, level 14, 8 XP)
+    │   ├── eco_altar  → ecojunk   (req: eco_identifier, level 28, 12 XP)
+    │   └── bio_altar  → biojunk   (req: bio_identifier, level 44, 16 XP)
+    │
+    ├── Check identifier tool in inventory or equipment
+    │   └── If missing: "You need a <name> to use this altar." → return
+    │
+    ├── Check player has scrap_metal in inventory
+    │   └── If none: "You don't have any scrap metal." → return
+    │
+    ├── Check Scavenging level ≥ required level
+    │   └── If too low: "You need level <N> scavenging to do that." → return
+    │
+    └── Create action:
+        p.Action = &action.Action{
+            Type:       "identify",
+            TargetName: <altar_name>,
+            Data: {
+                "altar_type": <altar_def_id>,
+                "junk_id":    <junk_item_id>,
+                "xp_per":     <xp_per_scrap>,
+                "level_req":  <level_req>,
+            },
+            WaitLeft: 1,
+        }
+        p.ActionState = &ActionState{Type: ActionIdentifying, TargetName: <altar_name>}
+```
+
+### Advance Logic (next tick)
+
+```
+advanceIdentify(sess, p):
+    │
+    ├── Read action data (junk_id, xp_per, level_req)
+    │
+    ├── Count all scrap_metal in inventory
+    │   └── Iterate slots 0-27, sum quantities where ItemID == "scrap_metal"
+    │
+    ├── Calculate multiplier from Scavenging level (see Section 11)
+    │   └── totalJunk = scrapCount * multiplier
+    │
+    ├── Check inventory space for junk (junk is stackable, so only need 1 free slot
+    │   if player doesn't already have that junk type)
+    │   └── If no existing stack AND no free slot:
+    │       "Your inventory is too full!" → CancelAction → return
+    │
+    ├── Remove all scrap_metal from inventory
+    │   └── Iterate slots 0-27, nil any slot with ItemID == "scrap_metal"
+    │
+    ├── Add junk to inventory
+    │   └── Find existing stack of junk_id → add totalJunk to quantity
+    │   └── OR find free slot → set to {ItemID: junk_id, Quantity: totalJunk}
+    │
+    ├── Award XP: totalXP = scrapCount * xp_per
+    │   └── p.AddSkillXP(player.Scavenging, totalXP)
+    │   └── Check for level-up, output message if so
+    │
+    ├── Output message:
+    │   "The altar hums. You identify <scrapCount> scrap metal into <totalJunk> <junk_name>."
+    │   └── If xp_drops enabled: " (+<totalXP>xp scv)"
+    │
+    ├── SaveCharacter(p)
+    │
+    └── CancelAction(p)
+```
+
+---
+
+## 9. Action Lifecycle — Implementation Details
+
+### `internal/game/cmd_id.go`
+
+```go
+package game
+
+import (
+	"fmt"
+
+	"thehouseoficarus/internal/action"
+	"thehouseoficarus/internal/net"
+	"thehouseoficarus/internal/player"
+)
+
+type altarConfig struct {
+	AltarID      string
+	IdentifierID string
+	JunkID       string
+	LevelReq     int
+	XPPer        int
+}
+
+var altarConfigs = []altarConfig{
+	{"solar_altar", "solar_identifier", "solarjunk", 1, 5},
+	{"hydro_altar", "hydro_identifier", "hydrojunk", 14, 8},
+	{"eco_altar", "eco_identifier", "ecojunk", 28, 12},
+	{"bio_altar", "bio_identifier", "biojunk", 44, 16},
+}
+
+func (g *Game) doIdentify(sess *net.Session, input string) {
+	p := sess.Player.(*player.Player)
+	g.CancelAction(p)
+
+	var found *altarConfig
+	for _, ac := range altarConfigs {
+		if defID, _ := g.findStation(p.RoomID, []string{ac.AltarID}); defID != "" {
+			found = &ac
+			break
+		}
+	}
+	if found == nil {
+		sess.WriteLine("There is no altar here.")
+		return
+	}
+
+	identifierName := found.IdentifierID
+	if def, err := g.ItemStore.Load(found.IdentifierID); err == nil {
+		identifierName = def.Name
+	}
+	if !p.HasItem(found.IdentifierID) {
+		sess.WriteLine(fmt.Sprintf("You need a %s to use this altar.", identifierName))
+		return
+	}
+
+	scrapCount := g.countItem(p, "scrap_metal")
+	if scrapCount == 0 {
+		sess.WriteLine("You don't have any scrap metal.")
+		return
+	}
+
+	scavLevel := p.Level(player.Scavenging)
+	if scavLevel < found.LevelReq {
+		junkName := found.JunkID
+		if def, err := g.ItemStore.Load(found.JunkID); err == nil {
+			junkName = def.Name
+		}
+		sess.WriteLine(fmt.Sprintf("You need level %d scavenging to identify %s.", found.LevelReq, junkName))
+		return
+	}
+
+	altarName := found.AltarID
+	if def, err := g.ObjectStore.Load(found.AltarID); err == nil {
+		altarName = def.Name
+	}
+
+	p.Action = &action.Action{
+		Type:       "identify",
+		TargetID:   found.AltarID,
+		TargetName: altarName,
+		WaitLeft:   1,
+		Data: map[string]any{
+			"junk_id":   found.JunkID,
+			"xp_per":    found.XPPer,
+			"level_req": found.LevelReq,
+		},
+	}
+	p.ActionState = &ActionState{Type: ActionIdentifying, TargetName: altarName}
+}
+
+// countItem counts total quantity of an item across all inventory slots.
+// For non-stackable items, each slot with that item contributes 1.
+func (g *Game) countItem(p *player.Player, itemID string) int {
+	total := 0
+	for i := 0; i < 28; i++ {
+		slot := p.InvSlot(i)
+		if slot != nil && slot.ItemID == itemID {
+			total += slot.Quantity
+		}
+	}
+	return total
+}
+```
+
+**Note on `countItem`:** Check if `player.Player` already has a `CountItem` method. Looking at the codebase, `p.CountItem` is used in production code (`recipe.HasAllItemsQty(p.CountItem)`). Use that if it already returns a count for a given item ID. If `CountItem(id string) int` exists, use `p.CountItem("scrap_metal")` instead of a custom helper.
+
+### `internal/game/action_identify.go`
+
+```go
+package game
+
+import (
+	"fmt"
+
+	"thehouseoficarus/internal/net"
+	"thehouseoficarus/internal/player"
+)
+
+func (g *Game) advanceIdentify(sess *net.Session, p *player.Player) {
+	junkID := p.Action.Data["junk_id"].(string)
+	xpPer := p.Action.Data["xp_per"].(int)
+
+	scrapCount := 0
+	for i := 0; i < 28; i++ {
+		slot := p.InvSlot(i)
+		if slot != nil && slot.ItemID == "scrap_metal" {
+			scrapCount += slot.Quantity
+		}
+	}
+
+	if scrapCount == 0 {
+		sess.WriteLine("You don't have any scrap metal.")
+		g.CancelAction(p)
+		return
+	}
+
+	scavLevel := p.Level(player.Scavenging)
+	multiplier := junkMultiplier(junkID, scavLevel)
+	totalJunk := scrapCount * multiplier
+
+	hasExistingStack := false
+	for i := 0; i < 28; i++ {
+		slot := p.InvSlot(i)
+		if slot != nil && slot.ItemID == junkID {
+			hasExistingStack = true
+			break
+		}
+	}
+	if !hasExistingStack && p.FirstFreeSlot() == -1 {
+		sess.WriteLine("Your inventory is too full!")
+		g.CancelAction(p)
+		return
+	}
+
+	for i := 0; i < 28; i++ {
+		slot := p.InvSlot(i)
+		if slot != nil && slot.ItemID == "scrap_metal" {
+			p.SetInvSlot(i, nil)
+		}
+	}
+
+	placed := false
+	for i := 0; i < 28; i++ {
+		slot := p.InvSlot(i)
+		if slot != nil && slot.ItemID == junkID {
+			slot.Quantity += totalJunk
+			placed = true
+			break
+		}
+	}
+	if !placed {
+		freeSlot := p.FirstFreeSlot()
+		p.SetInvSlot(freeSlot, &player.InventorySlot{ItemID: junkID, Quantity: totalJunk})
+	}
+
+	totalXP := scrapCount * xpPer
+	junkName := junkID
+	if def, err := g.ItemStore.Load(junkID); err == nil {
+		junkName = def.Name
+	}
+
+	msg := fmt.Sprintf("The altar hums. You identify %d scrap metal into %d %s.", scrapCount, totalJunk, junkName)
+
+	if newLevel := p.AddSkillXP(player.Scavenging, totalXP); newLevel > 0 {
+		sess.WriteLine(g.colorize(sess, "level_up",
+			fmt.Sprintf("*** You are now level %d scavenging! ***", newLevel)))
+	}
+
+	if p.OptionBool("xp_drops") && totalXP > 0 {
+		msg += g.colorize(sess, "xp", fmt.Sprintf(" (+%dxp scv)", totalXP))
+	}
+	sess.WriteLine(msg)
+
+	g.AccountStore.SaveCharacter(p)
+	g.CancelAction(p)
+}
+```
+
+**Note on `xpPer` type:** When data is stored via `map[string]any` and read back after JSON/YAML round-tripping through the action system, integer values may come back as `float64` (if the action data is ever serialized). Check how other action handlers read integers from `Data`. Looking at `action_search.go:42`, it uses `data["slot_idx"].(int)` — so direct int assertion is fine since action data is never serialized to disk. However, `action_production.go:310` reads `wait` as `float64` — this is because `map[string]any` stores numbers from YAML as float64. Since we're setting these values directly in Go code (not loading from YAML), `int` assertion is correct. But to be safe, consider storing as `float64` and reading as `float64`, then converting:
+
+```go
+xpPer := int(p.Action.Data["xp_per"].(float64))
+```
+
+This is safer. Check the `advanceSearch` pattern — it reads `int` directly because it was set as `int` in `startSearch`. Since `doIdentify` also sets `int` values directly, the `.(int)` assertion should work. But be aware: if the game ever serializes/deserializes actions, this could break. Follow whichever pattern the codebase uses consistently.
+
+---
+
+## 10. XP Table
+
+XP is awarded per scrap converted, not per junk produced. This means multipliers give more output but not more XP per scrap.
+
+| Junk Type | XP per scrap | Level Req |
+|-----------|-------------|-----------|
+| Solarjunk | 5 | 1 |
+| Hydrojunk | 8 | 14 |
+| Ecojunk | 12 | 28 |
+| Biojunk | 16 | 44 |
+
+**XP examples (28 inventory slots = 28 scrap per trip):**
+
+| Junk Type | XP per trip (28 scrap) |
+|-----------|----------------------|
+| Solarjunk | 140 |
+| Hydrojunk | 224 |
+| Ecojunk | 336 |
+| Biojunk | 448 |
+
+For reference, level 99 requires 13,034,431 XP (RSC table). At 448 XP per trip (biojunk), that's ~29,094 trips — comparable to OSRS Runecrafting grind.
+
+---
+
+## 11. Level Multipliers
+
+At higher Scavenging levels, each scrap metal produces multiple junk (like OSRS double/triple runes).
+
+### Multiplier Table
+
+| Scavenging Level | Solarjunk | Hydrojunk | Ecojunk | Biojunk |
+|-----------------|-----------|-----------|---------|---------|
+| 1 | 1x | — | — | — |
+| 14 | 1x | 1x | — | — |
+| 22 | 2x | 1x | — | — |
+| 28 | 2x | 1x | 1x | — |
+| 36 | 2x | 2x | 1x | — |
+| 44 | 3x | 2x | 1x | 1x |
+| 56 | 3x | 2x | 2x | 1x |
+| 66 | 4x | 3x | 2x | 1x |
+| 78 | 4x | 3x | 3x | 2x |
+| 88 | 5x | 4x | 3x | 2x |
+| 99 | 6x | 4x | 3x | 3x |
+
+### Implementation
+
+```go
+type junkMultiplierEntry struct {
+	Level      int
+	Multiplier int
+}
+
+var junkMultipliers = map[string][]junkMultiplierEntry{
+	"solarjunk": {
+		{1, 1}, {22, 2}, {44, 3}, {66, 4}, {88, 5}, {99, 6},
+	},
+	"hydrojunk": {
+		{14, 1}, {36, 2}, {66, 3}, {88, 4},
+	},
+	"ecojunk": {
+		{28, 1}, {56, 2}, {78, 3},
+	},
+	"biojunk": {
+		{44, 1}, {78, 2}, {99, 3},
+	},
+}
+
+func junkMultiplier(junkID string, level int) int {
+	entries, ok := junkMultipliers[junkID]
+	if !ok {
+		return 1
+	}
+	mult := 1
+	for _, e := range entries {
+		if level >= e.Level {
+			mult = e.Multiplier
+		}
+	}
+	return mult
+}
+```
+
+Place this in `cmd_id.go` or `action_identify.go` — whichever file contains the `advanceIdentify` function.
+
+---
+
+## 12. Mining Scrap — Verification
+
+The existing setup:
+
+- **Behavior:** `data/behaviors/mine_scrap.yaml` — skill: mining, level 1, XP 5, base_wait 10, requires pickaxe, 55% base success + 1% per level (cap 95%), drops `scrap_metal` with depletion, 50-tick respawn.
+- **Object:** `data/objects/scrap_pile.yaml` — name "scrap pile", behavior `mine_scrap`.
+- **Item:** `data/items/scrap_metal.yaml` — non-stackable, value 2.
+
+**Verify these work by:**
+1. Ensure room 9 has `scrap_pile` objects listed.
+2. Test: `mine scrap` or `mine pile` should start gathering.
+3. Test: Successful gather produces `scrap_metal` in inventory.
+4. Test: Depletion and respawn work correctly.
+
+**Potential adjustment:** The `base_wait: 10` (10 ticks = 6 seconds at 600ms tick) is reasonable for scrap mining. The success rate starting at 55% and capping at 95% is fine. Consider whether the behavior should use `skill: scavenging` instead of `skill: mining`. The TODO says "Mine 'scrap' in scrap pile objects" which implies Mining skill is correct (Scavenging is for the identification phase). However, this is a design decision — if scrap mining should train Scavenging, change the behavior to `skill: scavenging`.
+
+**Recommendation:** Keep `skill: mining` for scrap mining (consistent with the mining skill being used for all pick-based gathering). The Scavenging skill is trained exclusively through identification at altars. This parallels OSRS where Mining trains Mining and Runecrafting trains Runecrafting.
+
+---
+
+## 13. Help Files
+
+### `data/help/id.yaml`
+
+```yaml
+name: "id"
+category: "Commands"
+description: |
+  Identify scrap metal at an altar to produce junk.
+
+  Usage: id
+         identify
+
+  Stand at an altar (solar, hydro, eco, or bio) with the matching
+  identifier tool in your inventory and scrap metal. Type 'id' to
+  convert all your scrap metal into junk on the next game tick.
+
+  Each altar type requires a specific identifier:
+    Solar Altar  → solar identifier → solarjunk  (level 1)
+    Hydro Altar  → hydro identifier → hydrojunk  (level 14)
+    Eco Altar    → eco identifier   → ecojunk    (level 28)
+    Bio Altar    → bio identifier   → biojunk    (level 44)
+
+  At higher scavenging levels, each scrap produces multiple junk.
+  See 'help scavenging' for the full multiplier table.
+```
+
+### `data/help/scavenging.yaml`
+
+```yaml
+name: "scavenging"
+category: "Skills"
+description: |
+  Scavenging is the art of reclaiming useful circuitry from salvaged scrap.
+
+  Step 1: Mine scrap metal from scrap piles (requires a pickaxe, uses
+          the Mining skill).
+  Step 2: Take scrap metal to an altar with the matching identifier tool.
+  Step 3: Type 'id' to convert all scrap metal into junk.
+
+  Junk types and requirements:
+    Solarjunk — level 1,  solar identifier, solar altar (5 XP/scrap)
+    Hydrojunk — level 14, hydro identifier, hydro altar (8 XP/scrap)
+    Ecojunk   — level 28, eco identifier, eco altar     (12 XP/scrap)
+    Biojunk   — level 44, bio identifier, bio altar     (16 XP/scrap)
+
+  Higher scavenging levels produce more junk per scrap:
+    Solarjunk: 2x at 22, 3x at 44, 4x at 66, 5x at 88, 6x at 99
+    Hydrojunk: 2x at 36, 3x at 66, 4x at 88
+    Ecojunk:   2x at 56, 3x at 78
+    Biojunk:   2x at 78, 3x at 99
+
+  Scrap metal is not stackable — you can carry 28 per trip (one per
+  inventory slot). Each trip converts all scrap in one tick.
+```
+
+---
+
+## 14. Implementation Checklist
+
+### Phase 1: Core Files (minimal working feature)
+
+- [ ] Create `internal/game/cmd_id.go` with `doIdentify()`, `altarConfigs`, `junkMultiplier()`
+- [ ] Create `internal/game/action_identify.go` with `advanceIdentify()`
+- [ ] Edit `internal/game/action_state.go`: add `ActionIdentifying` constant and `Description()` case
+- [ ] Edit `internal/game/game.go` → `classifyCommand()`: add `"id"`, `"identify"` to `ClassActive`
+- [ ] Edit `internal/game/game.go` → `executeCommand()`: add `case "id", "identify":`
+- [ ] Edit `internal/game/action.go` → `AdvanceActions()`: add `case "identify":`
+
+### Phase 2: YAML Data
+
+- [ ] Create `data/items/solar_identifier.yaml`
+- [ ] Create `data/items/hydro_identifier.yaml`
+- [ ] Create `data/items/eco_identifier.yaml`
+- [ ] Create `data/items/bio_identifier.yaml`
+- [ ] Create `data/items/solarjunk.yaml`
+- [ ] Create `data/items/hydrojunk.yaml`
+- [ ] Create `data/items/ecojunk.yaml`
+- [ ] Create `data/items/biojunk.yaml`
+- [ ] Create `data/objects/solar_altar.yaml`
+- [ ] Create `data/objects/hydro_altar.yaml`
+- [ ] Create `data/objects/eco_altar.yaml`
+- [ ] Create `data/objects/bio_altar.yaml`
+
+### Phase 3: Rooms
+
+- [ ] Update `data/rooms/9.yaml` — add scrap pile objects, update description, add exits to altar rooms
+- [ ] Create altar room YAML files (4 rooms) — determine next available room IDs
+- [ ] Ensure exits are bidirectional (altar rooms exit back to room 9 or a hub)
+
+### Phase 4: Help
+
+- [ ] Create `data/help/id.yaml`
+- [ ] Create `data/help/scavenging.yaml`
+
+### Phase 5: Verify
+
+- [ ] `make build` — compiles without errors
+- [ ] `make vet` — no vet warnings
+- [ ] `make test` — all tests pass
+- [ ] Manual test: mine scrap at room 9, walk to altar, `id`, verify conversion
+- [ ] Test: identifier not in inventory → correct error message
+- [ ] Test: no scrap in inventory → correct error message
+- [ ] Test: no altar in room → correct error message
+- [ ] Test: level too low → correct error message
+- [ ] Test: inventory full (no room for junk) → correct error message
+- [ ] Test: multiplier works at higher levels
+- [ ] Test: XP is awarded correctly
+- [ ] Test: level-up message displays
+- [ ] Test: `help id` and `help scavenging` display correctly
+
+---
+
+## 15. Design Decisions & Edge Cases
+
+### Why not use the recipe/production system?
+
+The production system (`action_production.go`) processes items one at a time in a loop with "How many?" prompts and per-cycle timing. Scavenging converts ALL scrap in a single tick with level-based multipliers. The mechanics are fundamentally different:
+- Production: consume 1 input → wait N ticks → produce 1 output → repeat
+- Identify: consume ALL scrap → wait 1 tick → produce (scrap × multiplier) junk
+
+A custom action type (`identify`) is cleaner than bending the production system.
+
+### Scrap is non-stackable (intentional)
+
+Like rune essence in OSRS, scrap metal fills one inventory slot per piece. This limits trips to 28 scrap maximum, creating a meaningful gameplay loop of mine → walk → identify → repeat.
+
+### Identifier tools are NOT consumed
+
+Identifiers are reusable tools (like a talisman in OSRS). Players buy/find them once and keep them. They take 1 inventory slot, reducing max scrap per trip to 27.
+
+### What if the player has multiple types of identifiers?
+
+The `id` command scans for altars in the room, not identifiers. It finds which altar is present, then checks for the matching identifier. Only one altar type per room. No ambiguity.
+
+### What if multiple altars are in the same room?
+
+The first matching altar in `altarConfigs` order wins (solar → hydro → eco → bio). In practice, each room should have exactly one altar.
+
+### Junk items are stackable
+
+Unlike scrap, junk stacks in a single inventory slot. A player can accumulate unlimited junk in one slot. This is intentional — junk is the "rune" equivalent and will be consumed by future skills/spells.
+
+### XP is per scrap, not per junk
+
+If a player converts 28 scrap at 3x multiplier, they get 84 junk but only 28 × (xp_per) XP. The multiplier rewards efficiency (more output per trip) without inflating XP rates.
+
+### The `countItem` helper
+
+Before implementing, check if `player.Player` already has a `CountItem(id string) int` method. The production system uses `p.CountItem` — see `action_production.go:221` where `recipe.HasAllItemsQty(p.CountItem)` passes it as a function. If `CountItem` exists, use it directly instead of writing a new helper. If it returns a count, `p.CountItem("scrap_metal")` gives the total.
+
+### Action cancellation
+
+The `identify` action is a 1-tick action. If the player moves or starts another action before it fires, the action is cancelled naturally (CancelAction is called). The scrap is NOT consumed until `advanceIdentify` runs, so cancellation is safe — no items lost.