chore: add game-design gathering & resources doc

- Add gathering.md (nodes, Gather skills, gig vs skill XP, E3.M1/E4.M2)
- Cross-link from overview, progression, skills, gigs, items, abilities, README
- Extend docs-review-agent hybrid progression ground truth

.cursor/rules/docs-review-agent.md

@@ -26,7 +26,7 @@ Use this rule when the user is working in **`docs/`** (design, decomposition, pl
 ## Ground truth (required to check)
 
 1. **Same folder and upstream links** — Read every `docs/...` link from the target doc(s); verify paths exist and headings match intent.
-2. **Hybrid progression** — `docs/game-design/progression.md`, `skills.md`, `gigs.md`, `abilities.md`, `items.md`: **Gig** = combat role; **Skill** = non-combat; **combat abilities** = gig kit (+ item channels per data); **Seams** live in `skills.md` unless a dedicated doc supersedes. **Combat encounters** → **gig XP** only (no default skill XP from the fight loop). **Mission/quest rewards** may still grant **skill XP** when explicitly defined—separate from the encounter **gig XP** path.
+2. **Hybrid progression** — `docs/game-design/progression.md`, `skills.md`, `gigs.md`, `abilities.md`, `items.md`, `gathering.md`: **Gig** = combat role; **Skill** = non-combat; **combat abilities** = gig kit (+ item channels per data); **Seams** live in `skills.md` unless a dedicated doc supersedes. **Combat encounters** → **gig XP** only (no default skill XP from the fight loop). **Gather / craft** → **skill XP** (see `gathering.md`, Epic 3)—not **gig** XP. **Mission/quest rewards** may still grant **skill XP** when explicitly defined—separate from the encounter **gig XP** path.
 3. **Decomposition** — Map claims to `docs/decomposition/epics/` and `docs/decomposition/modules/` where relevant; flag **conflicts** (e.g. “combat skill” vs skills-as-non-combat). **CI** enforces a minimal guard via [`scripts/check_decomposition_language.py`](../../scripts/check_decomposition_language.py) in the **PR gate** (extend the script if a vetted exception is needed).
 4. **Plans** — If work maps to `docs/plans/`, check for **acceptance criteria** vs design doc (same spirit as [code-review-agent](code-review-agent.md) plan alignment).
 

docs/game-design/README.md

@@ -6,6 +6,6 @@
 
 **Brainstorm-only** (not specs): [`brainstorm/`](brainstorm/README.md).
 
-Non-implementation notes: **gigs** (combat roles), **skills** (non-combat), **[abilities](abilities.md)** (what players trigger), **[items](items.md)** (loot, craft, equip), zones, mechanics, and other design artifacts before they are tied to concrete systems or tickets.
+Non-implementation notes: **gigs** (combat roles), **skills** (non-combat), **[abilities](abilities.md)** (what players trigger), **[items](items.md)** (loot, craft, equip), **[gathering](gathering.md)** (resource nodes, yields), zones, mechanics, and other design artifacts before they are tied to concrete systems or tickets.
 
 Implementation-facing breakdowns stay under [`docs/decomposition/`](../decomposition/README.md) and plans under [`docs/plans/`](../plans/).

docs/game-design/abilities.md

@@ -58,6 +58,7 @@ Vision for **what the player triggers** in play: combat **kits**, non-combat **s
 |--------|----------|
 | Gig roster, hub swap, XP | [gigs.md](gigs.md) |
 | Item categories, craft vs loot | [items.md](items.md) |
+| Gathering (skill XP, nodes—not gig) | [gathering.md](gathering.md) |
 | Seams (gear, craft, consumables) | [skills.md](skills.md) |
 | Hybrid vocabulary | [progression.md](progression.md) |
 | Encounter rewards + combat hooks | [Epic 5](../decomposition/epics/epic_05_pve_combat.md), [Epic 7](../decomposition/epics/epic_07_quest_faction.md) |

docs/game-design/gathering.md

@@ -0,0 +1,79 @@
+# Gathering & resources
+
+Vision for **pulling raw value from the world**: **resource nodes**, **yields**, **who can compete**, and how gathering feeds **inventory** and **skill** progression—without collapsing into **gig** combat progression.
+
+**Runtime ownership:** [E3.M1 — ResourceNodeAndGatherLoop](../decomposition/modules/E3_M1_ResourceNodeAndGatherLoop.md) defines **`ResourceNodeDef`**, **`GatherResult`**, **`ResourceYieldTable`**, and ties gather interactions to [E1.M3 — InteractionAndTargetingLayer](../decomposition/modules/E1_M3_InteractionAndTargetingLayer.md). Outputs land as items via [E3.M3](../decomposition/modules/E3_M3_ItemizationAndInventorySchema.md). **Ecology / respawn pacing** per zone: [E4.M2 — SpawnEcologyController](../decomposition/modules/E4_M2_SpawnEcologyController.md).
+
+**Skill roster (Gather category):** [skills.md — Gather](skills.md#skill-roster-draft-ideas-by-category) (**Salvage**, **Extraction**, **Harvest (bio)**, **Quarry / bulk**). **Hybrid vocabulary:** [progression.md](progression.md). **Where gathered stuff goes:** [items.md](items.md) **Materials & intermediates** and **Acquisition**.
+
+## Gig vs skill
+
+- **Gathering is skill progression**, not **gig** identity. **Combat encounters** do not grant **skill XP** by default; **gather / craft** pipes do ([progression.md](progression.md), [Epic 2 — Skills](../decomposition/epics/epic_02_skills_and_progression.md) **Slice 3**).
+- **No gig XP** from nodes or harvest loops—**gig XP** stays on the **combat** path ([gigs.md](gigs.md)).
+- **World gates** (rep, licenses, zone access) can **gate which nodes exist or who may interact**; they must not replace “wrong class” locks—**any character** can train **Gather** skills over time ([skills.md](skills.md) **Pillars**).
+
+## Node lenses (design-facing)
+
+Nodes are **data** (`ResourceNodeDef`); these **lenses** help content and balance talk align with **Gather** skills:
+
+| Lens | Fiction / examples | Typical skill hook |
+|------|--------------------|--------------------|
+| **Consumer salvage** | Wrecks, e-waste, stripped chrome, discarded gear | **Salvage** |
+| **Subsurface / geological** | Seams, drilled feedstock, rare earths | **Extraction** |
+| **Bio / organic** | Fungal mats, cultured tissue, black-market organics (grim **concepts**—[overview.md](overview.md) presentation band) | **Harvest (bio)** |
+| **Urban bulk / structures** | Demo recoverables, aggregate, structural mass—not consumer wrecks | **Quarry / bulk** |
+
+Same **physical prop** might map to **different** node types or yield tables by **zone tier** and **fiction**—**content** decides; skills table in [skills.md](skills.md) stays the **boundary** reference (e.g. **Salvage** vs **Quarry**).
+
+## Competition and “open world” feel
+
+Directional goals (implementation **open**):
+
+- **Depletion** and **regen** (capacity, timers) make **presence** and **timing** matter—aligned with E3.M1/E4.M2 responsibilities.
+- **Contesting** the same node may be **non-combat** (arrival order, channel time, tool tier) or **high-risk** (PvP-adjacent) depending on **security tier**—see [overview.md](overview.md) **Risk & security bands** (stub) and [gigs.md](gigs.md) **PvP** notes (**open** until PvP vision lands).
+- **Instanced vs shared** world: some resources may live only in **contracts** or **dungeons**; others in **shared** overworld—**split by content**, not a single global rule (**open**).
+
+## Exhaustion, tools, and gates
+
+- **Stamina / daily caps / exhaustion** on gather—**open**; if used, should support **specialist fantasy** without hard **gig** coupling ([skills.md](skills.md) **Low-gig specialist**).
+- **Tools** (pickaxes, rigs, scanners) are **items**—craft or buy via [items.md](items.md); **use** may be **skill**-gated per item data ([Seams](skills.md#seams-gigs-skills) **Non-combat Rigging / utility** pattern).
+- **Skill XP** from gather: award on **successful** interaction / yield resolution—structured for telemetry ([E2.M2 — XpAwardAndLevelEngine](../decomposition/modules/E2_M2_XpAwardAndLevelEngine.md)); exact curves **open**.
+
+## Pipeline position
+
+**Gather → Process → Make** is the agreed chain shape ([skills.md](skills.md) **Production chains**). This doc stops at **raw outputs**; **refine / fab / recipes** are [E3.M2](../decomposition/modules/E3_M2_RefinementAndRecipeExecution.md) and a future **crafting & recipes** vision doc.
+
+## Module map (gathering-focused)
+
+| Module | Role | Ties to this doc |
+|--------|------|-------------------|
+| [E3.M1](../decomposition/modules/E3_M1_ResourceNodeAndGatherLoop.md) | Nodes, gather, yields | **Core** |
+| [E2.M2](../decomposition/modules/E2_M2_XpAwardAndLevelEngine.md) | Skill XP awards | Gather **skill** progression |
+| [E3.M3](../decomposition/modules/E3_M3_ItemizationAndInventorySchema.md) | Items in inventory | **GatherResult** outputs |
+| [E4.M2](../decomposition/modules/E4_M2_SpawnEcologyController.md) | Spawn profiles, respawn, depletion bounds | Zone **density** and recovery |
+| [E1.M3](../decomposition/modules/E1_M3_InteractionAndTargetingLayer.md) | Interaction range / targeting | Player **interacts** with node |
+
+## Decisions log
+
+| Topic | Direction | Status |
+|-------|-----------|--------|
+| Gather → skill XP, not gig XP | **Skill** XP from gather/craft pipes; **gig** XP from combat encounters | Agreed ([progression.md](progression.md)) |
+| Gather skills vs node fiction | **Salvage** / **Extraction** / **Harvest** / **Quarry** boundaries as in [skills.md](skills.md) | Agreed |
+| Pipeline | Raw from nodes feeds **Process** then **Make**—not a flat single-step economy | Agreed ([skills.md](skills.md)) |
+
+## Open questions
+
+- **Node ownership** (personal tap, party split, corp claims) vs **FFA** taps—social and exploit surface.
+- **Stealing** gathered output or **harvesting under fire**—ties to **risk bands** and **death** doc (**TBD**).
+- **Bots / automation** fantasy vs anti-bot—how much **AFK** is acceptable (**open**).
+- **Cross-skill nodes** (e.g. **Intrusion** to **unlock** a **Salvage** pile)—mission design vs systemic rule.
+
+## Where to read next
+
+| Topic | Document / module |
+|--------|-------------------|
+| Gather skill names & merge notes | [skills.md](skills.md) **Gather** table |
+| Items & materials buckets | [items.md](items.md) |
+| Epic 3 gather slice | [Epic 3](../decomposition/epics/epic_03_crafting_economy.md) — *Slice 2 — Gather nodes and outputs* |
+| Interaction contracts | [E1.M3](../decomposition/modules/E1_M3_InteractionAndTargetingLayer.md) |
+| Zone ecology | [E4.M2](../decomposition/modules/E4_M2_SpawnEcologyController.md), [Epic 4](../decomposition/epics/epic_04_world_topology.md) |

docs/game-design/gigs.md

@@ -132,4 +132,5 @@ Detail: seams table in [skills.md](skills.md).
 - [abilities.md](abilities.md) — **gig-locked** kits, sub-gig ability rules, telegraphs ([Epic 5](../decomposition/epics/epic_05_pve_combat.md)).
 - [Combat pillars](overview.md) — PvE readability, TTK, risk ([overview](overview.md); stub until a dedicated doc ships).
 - [items.md](items.md) — **combat gear** vs chrome vs consumables; craft vs loot; loadout + swap ([Seams](skills.md#seams-gigs-skills)).
+- [gathering.md](gathering.md) — **not** gig progression; **skill** nodes and yields feed economy ([progression.md](progression.md)).
 - [brainstorm/hack-bodyguard-missions.md](brainstorm/hack-bodyguard-missions.md) — group content where **gigs** hold security while **skills** run the hack (brainstorm).

docs/game-design/items.md

@@ -21,7 +21,7 @@ These overlap in data; they are **lenses** for writers and systems.
 ## Acquisition
 
 - **Crafted:** Primary fantasy for **durables** that matter in combat and economy—**player-made goods stay relevant** across stages ([Epic 3](../decomposition/epics/epic_03_crafting_economy.md) success criteria).
-- **Dropped / looted / salvaged:** Feed **gather–refine–craft** loops and **world fiction**; tuning is **content + economy policy** (**open** drop tables).
+- **Dropped / looted / salvaged:** Feed **gather–refine–craft** loops and **world fiction**; tuning is **content + economy policy** (**open** drop tables). **World-sourced raw** (nodes, yields): [gathering.md](gathering.md).
 - **Mission & vendor rewards:** Can grant **items** or **skill XP** separately from combat XP pipes ([progression.md](progression.md)); avoid double-dipping the same milestone without intent (**open** reward UX).
 - **Trade:** Craft-for-others is **valid** even when the buyer cannot **equip** or **combat-deploy** the product ([Seams](skills.md#seams-gigs-skills) **Crafting combat gear**).
 
@@ -73,7 +73,8 @@ Design **buckets** above are not 1:1 types in data—they inform tags and metada
 | Abilities from items | [abilities.md](abilities.md) |
 | Combat pillars (vision stub) | [overview.md — Combat pillars](overview.md#combat-pillars-vision-stub) |
 | Epic 3 loop & slices | [Epic 3](../decomposition/epics/epic_03_crafting_economy.md) |
-| Gather nodes | [E3.M1](../decomposition/modules/E3_M1_ResourceNodeAndGatherLoop.md) |
+| Gathering vision (nodes, contesting) | [gathering.md](gathering.md) |
+| Gather module | [E3.M1](../decomposition/modules/E3_M1_ResourceNodeAndGatherLoop.md) |
 | Recipes & craft pipeline | [E3.M2](../decomposition/modules/E3_M2_RefinementAndRecipeExecution.md) |
 | Item schema & inventory | [E3.M3](../decomposition/modules/E3_M3_ItemizationAndInventorySchema.md) |
 | Sinks & durability | [E3.M4](../decomposition/modules/E3_M4_SinkAndDurabilityLifecycle.md) |

docs/game-design/overview.md

@@ -6,7 +6,7 @@ This folder holds **vision-level** design: what we want players to feel, do, and
 
 Neon Sprawl’s design work here starts from **concrete visions** of progression, places, risk, economy, social play, combat, and the items/abilities that express them. Documents below are added as we write them; each should stay opinionated and specific enough to argue with, without pretending to be a full GDD.
 
-**Hybrid progression:** [progression.md](progression.md) (vocabulary + why gigs + skills). **Gig** detail: [gigs.md](gigs.md). **Skills** + **seams**: [skills.md](skills.md). **Abilities** (combat vs non-combat actions): [abilities.md](abilities.md). **Items** (loot, craft, equip): [items.md](items.md). **Loose ideas:** [`brainstorm/`](brainstorm/README.md).
+**Hybrid progression:** [progression.md](progression.md) (vocabulary + why gigs + skills). **Gig** detail: [gigs.md](gigs.md). **Skills** + **seams**: [skills.md](skills.md). **Abilities** (combat vs non-combat actions): [abilities.md](abilities.md). **Items** (loot, craft, equip): [items.md](items.md). **Gathering** (nodes, skill XP, ecology): [gathering.md](gathering.md). **Loose ideas:** [`brainstorm/`](brainstorm/README.md).
 
 ## Presentation and target rating (vision)
 
@@ -27,6 +27,7 @@ Neon Sprawl’s design work here starts from **concrete visions** of progression
 | [gigs.md](gigs.md) | **9-gig roster** (v1 cyberpunk names); hub, sub-gig, party | Recruitment **deferred**; PvP **open indefinite**; niche LFG **if** tool ships |
 | [abilities.md](abilities.md) | **Combat** gig kits vs **skill** interactions vs **item** channels; Seams hooks | With [gigs.md](gigs.md), [skills.md](skills.md); [Combat pillars (vision stub)](#combat-pillars-vision-stub) |
 | [items.md](items.md) | Buckets (gear, chrome, consumables, mats); craft vs drops; rarity/readability | **Seams** in [skills.md](skills.md); **Epic 3 module map** in [items.md](items.md#epic-3-module-map) |
+| [gathering.md](gathering.md) | Resource **nodes**, **Gather** skills, contesting, pipeline to refine/craft | **E3.M1** + **E4.M2**; with [skills.md](skills.md), [items.md](items.md) |
 | [brainstorm/hack-bodyguard-missions.md](brainstorm/hack-bodyguard-missions.md) | Split **skill** (hack) + **gig** (bodyguard) instances—idea capture | Brainstorm |
 | *(add rows as files land)* | | |
 
@@ -40,7 +41,7 @@ Link new files here when they exist; remove or rewrite this subsection once the
 - **Mechanics** — loops, constraints, what the server vs. client must honor.
 - **Items** — [items.md](items.md): categories, rarity philosophy, crafting vs. drops; **Seams** for gig/skill gates.
 - **Abilities** — [abilities.md](abilities.md): inputs, timing; combo with items; **gig** vs **skill** gates (see [progression.md](progression.md) vocabulary). **Combat context:** [Combat pillars (vision stub)](#combat-pillars-vision-stub).
-- **Gathering & resources** — nodes, competition, exhaustion, what “open world” contesting feels like.
+- **Gathering & resources** — [gathering.md](gathering.md): nodes, competition, exhaustion, open-world contesting; **skill XP** not **gig** XP.
 - **Crafting & recipes** — depth vs. breadth, failure, specialization; pairs with items but is its own loop.
 - **Economy** — currency velocity, sinks, trade vs. self-sufficiency, how wealth shows up in play.
 - **Factions & reputation** — who remembers you, grudges, access gates; **gig** story arcs: [gigs.md](gigs.md), rep + seams: [skills.md](skills.md).

docs/game-design/progression.md

@@ -28,6 +28,7 @@ Use these terms in **design specs and tools** (fiction may say *job*, *contract*
 | Gig roster, hub swap, sub-gig, XP, party/PvP notes | [gigs.md](gigs.md) |
 | Combat vs non-combat **actions** (kits, skill interactions, items) | [abilities.md](abilities.md) |
 | **Items** (craft, loot, equip, gig/skill gates) | [items.md](items.md) |
+| **Gathering** (nodes, yields, skill XP—not gig) | [gathering.md](gathering.md) |
 | Skill domains, categories, XP curves, gates, mastery | [skills.md](skills.md) |
 | **Seams** (combat gear vs craft, consumables, rep, alts) | [skills.md](skills.md) (section *Seams (gigs ↔ skills)*) |
 | Loose ideas | [brainstorm/](brainstorm/README.md) |

docs/game-design/skills.md

@@ -1,6 +1,6 @@
 # Skills (non-combat progression)
 
-Design for **non-combat skills** only. **Shared vocabulary**, **why we use gigs + skills**, and the **hybrid overview** are in **[progression.md](progression.md)**. **Combat gigs** (roster, hub swap, sub-gig, etc.) are **[gigs.md](gigs.md)**. **What counts as a combat vs non-combat action** (kits, interactions, items): **[abilities.md](abilities.md)**. **Item buckets and acquisition** (loot, craft, equip): **[items.md](items.md)**.
+Design for **non-combat skills** only. **Shared vocabulary**, **why we use gigs + skills**, and the **hybrid overview** are in **[progression.md](progression.md)**. **Combat gigs** (roster, hub swap, sub-gig, etc.) are **[gigs.md](gigs.md)**. **What counts as a combat vs non-combat action** (kits, interactions, items): **[abilities.md](abilities.md)**. **Item buckets and acquisition** (loot, craft, equip): **[items.md](items.md)**. **Gathering & resource nodes** (competition, ecology, gig vs skill): **[gathering.md](gathering.md)**.
 
 **This file also owns the [Seams (gigs ↔ skills)](#seams-gigs-skills)** section—rules where **gigs** and **skills** meet (gear, crafting, consumables, rep, alts). **Brainstorm-only** ideas: [`brainstorm/`](brainstorm/README.md).
 
@@ -250,4 +250,5 @@ Explicit **bonuses** when skill A + B cross a threshold vs **pure fiction** (“
 - **[gigs.md](gigs.md)** — gig roster, hub UX, recruitment **deferred**; **PvP** gig rules **open indefinite** (overall PvP scope TBD).
 - **[abilities.md](abilities.md)** — **gig** combat kits vs **skill** interactions vs **item** channels (written).
 - **[items.md](items.md)** — buckets, craft vs drops, rarity/readability; detail still in [Seams](#seams-gigs-skills).
+- **[gathering.md](gathering.md)** — nodes, yields, **skill** XP from gather; **E3.M1** / **E4.M2** hooks (written).
 - [brainstorm/hack-bodyguard-missions.md](brainstorm/hack-bodyguard-missions.md) — group **skill** (hack) + **gig** (bodyguard) instances (brainstorm).