chore: add game-design gigs.md artifact; link from overview and skills

docs/game-design/gigs.md

@@ -0,0 +1,106 @@
+# Gigs (combat roles)
+
+Vision-level design for **combat identity**: what you bring to a fight, how you progress, and how you swap roles. Vocabulary (**gig**, **sub-gig**) and the **gigs ↔ skills** seams (gear, crafting, consumables, rep) stay in [skills.md](skills.md); this doc is the **gig** artifact proper.
+
+**Implementation anchors:** [Epic 5 — PvE combat](../decomposition/epics/epic_05_pve_combat.md); gig XP/progression will need alignment with [Epic 2 — Classless progression](../decomposition/epics/epic_02_classless_progression.md) when data models split.
+
+## What a gig is
+
+A **gig** is the combat **role** on an outing: which **abilities** you run, how the party reads you (tank, support, control, damage, etc.), and tuning expectations. It is **not** a non-combat profession—**skills** cover gather/craft ([skills.md](skills.md)).
+
+Fiction may say *contract*, *loadout*, or *job*; specs use **gig**.
+
+## Gig roster
+
+**Open:** final count and names. Start from a **small roster** with **clear party niches** so LFG and encounter design stay legible; grow over content seasons.
+
+**Starter archetypes to cover (working labels, not final):**
+
+| Niche | Job in a fight |
+|--------|------------------|
+| Mitigation / control | Hold space, reduce harm to the group |
+| Healing / cleansing | Recover HP, strip bad states |
+| Damage (single / cleave) | Primary threat removal |
+| Utility / debuff | Weaken targets, enable others |
+
+Cyberpunk paint (netrunner overlay, street sam, corp tech, etc.) layers on these **mechanical** niches—**open** which niches map to launch gigs.
+
+## Main gig + sub-gig
+
+**Agreed:** every loadout has a **main gig** and a **sub-gig** (FFXI-style). The sub adds **limited** cross-gig abilities without second-main power—a **large creative space** as the roster grows ([skills.md](skills.md) hybrid rationale).
+
+- **Effective sub level:** at **main** per-gig level **X**, sub contributes abilities up to **⌊X / 2⌋**, capped by the **sub-gig’s own trained level**—exact `min` / rounding **TBD**.
+- **Hub-only** changes to main or sub ([Hub swap](#hub-swap)).
+
+**Still open:**
+
+- **Combat gear:** almost certainly **main-gig–restricted** for equip; sub feeds **abilities** only—confirm in content pass.
+- **Consumables:** baseline for all; some items **amplify** on matching gig (e.g. medic)—does **sub-gig** count for amp? **Open.**
+- **PvP:** gig + sub balance, brackets, templates—**open.**
+- **UI:** two gig strips, sub ability styling, loadout summary for party—**open.**
+
+## Progression
+
+**Agreed:** **per-gig** level/XP (and later **mastery/perks** on that gig). No shared **combat rank** that levels every gig at once. **Maining every gig** on one character is allowed; **slow leveling** makes that a long-term goal ([skills.md](skills.md) seams).
+
+**Open:**
+
+- **When gig XP applies:** only while **main**, or also while **sub**, or split rates—must be decided for server rules and telemetry.
+- **Curves:** same philosophy as **skills** (soft feel, more XP per level)—per-gig tables vs global template **TBD**.
+- **Mastery/perks** on gigs vs flat level gates—**open** (E2.M3-style expression).
+
+## Hub swap
+
+**Agreed:** **no on-the-fly swap.** Changing **main gig**, **sub-gig**, or both only at a **safe hub**—**city**, **home base**, or other **data-tagged swap site**. Not in the field, not mid-combat.
+
+**Open:**
+
+- Which locations qualify (faction terminals, apartments, guild halls, etc.).
+- Fees, rep gates, cooldowns, tutorial exceptions.
+- **Loadout UX** after swap: auto-unequip invalid combat gear vs player-managed **presets** per gig pair.
+- **Party:** what happens if someone swaps while grouped—**open** (session lock vs free swap at hub).
+
+## Party, LFG, encounters
+
+**Intent:** gigs give a **plain language** for recruitment (“need mitigation,” “need cleanse”) and for **encounter** assumptions (required niches vs flexible).
+
+**Open:**
+
+- LFG **tags** and filters (map 1:1 to gigs vs to niches).
+- **Mandatory roles** in instanced content vs open-world flex.
+- **Group scaling** ([E5.M4](../decomposition/modules/E5_M4_GroupCombatScaling.md)) vs gig composition—design pass with encounters.
+
+## PvE vs PvP
+
+**Open:** whether all gigs are PvP-viable on launch, **templates** (PvP loadout subset), or **security-band** restrictions ([overview](overview.md) risk stubs). Sub-gig rules may differ by mode.
+
+## Story
+
+**Gig-scoped** storylines and **main-quest-style** arcs live per gig on one character; **faction rep** stays character-wide ([skills.md](skills.md) seams). **Open:** how much **mandatory** gig story vs optional.
+
+## Gear & consumables (summary)
+
+- **Combat gear:** **gig-restricted** equip; after hub swap, player **fixes loadout** for new main gig.
+- **Crafting** combat gear: **no gig requirement**—**skills** only; can craft for trade.
+- **Consumables:** anyone can use; some scale with **gig** match.
+
+Detail: seams table in [skills.md](skills.md).
+
+## Decisions log (gig-focused)
+
+| Topic | Direction | Status |
+|-------|-----------|--------|
+| Sub-gig slot | FFXI-style; ~½ main effective cap; hub change | Agreed ([skills.md](skills.md)) |
+| Hub swap | Safe hubs only; not in field / combat | Agreed |
+| Combat progression | Per-gig tracks | Agreed |
+| Gig roster size & names | Small launch set; clear niches | Open |
+| Gig XP award timing (main vs sub) | — | Open |
+| Sub-gig + consumable amp | — | Open |
+| LFG / party tags | — | Open |
+| PvP gig rules | — | Open |
+
+## Next artifacts
+
+- [Abilities](overview.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)).
+- [Items](overview.md) — equip tags per gig; crafted vs dropped.

docs/game-design/overview.md

@@ -6,20 +6,21 @@ 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.
 
-**Vocabulary ([skills.md](skills.md)):** **gig** = combat role; **skill** = non-combat trained capability only.
+**Vocabulary ([skills.md](skills.md)):** **gig** = combat role; **skill** = non-combat trained capability only. **Gig** design detail: [gigs.md](gigs.md).
 
 ## Artifact index
 
 | Document | Focus | Notes |
 |----------|--------|--------|
-| [skills.md](skills.md) | Gigs (combat) + skills (non-combat); hybrid progression | First vision artifact |
+| [skills.md](skills.md) | Hybrid progression; vocabulary; gigs ↔ skills seams | With [gigs.md](gigs.md) |
+| [gigs.md](gigs.md) | Combat gigs: roster, hub swap, sub-gig, party, PvP (open) | Gig artifact |
 | *(add rows as files land)* | | |
 
 ### Planned topics (stubs)
 
 Link new files here when they exist; remove or rewrite this subsection once the table is populated.
 
-- **Gigs & skills** — [skills.md](skills.md): **gigs** for combat; **skills** (classless) for gather/craft/etc. *Professions* stay folded into **skills** + rep unless a future doc defines something separate.
+- **Gigs** — [gigs.md](gigs.md): combat roles, hub swap, sub-gig, progression, party/LFG. **Skills** (non-combat): [skills.md](skills.md). *Professions* stay folded into **skills** + rep unless a future doc defines something separate.
 - **Zones** — tone, danger, faction or economic role of a place.
 - **Travel & connections** — how places link (gates, costs, downtime, danger en route); complements zone identity.
 - **Mechanics** — loops, constraints, what the server vs. client must honor.
@@ -28,7 +29,7 @@ Link new files here when they exist; remove or rewrite this subsection once the
 - **Gathering & resources** — nodes, competition, exhaustion, what “open world” contesting feels like.
 - **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 are scoped in [skills.md](skills.md) seams.
+- **Factions & reputation** — who remembers you, grudges, access gates; **gig** story arcs: [gigs.md](gigs.md), rep + seams: [skills.md](skills.md).
 - **Combat pillars** — PvE vs. PvP stance, readability, time-to-kill, what “fair” means here.
 - **Death, loss & recovery** — stakes on failure, recovery paths, anti-grief boundaries.
 - **Risk & security bands** — safe pockets vs. wild space; where optional PvP and theft sit (aligns with security-tier thinking).

docs/game-design/skills.md

@@ -10,7 +10,7 @@ From here on in game-design docs:
 |------|--------|
 | **Gig** | The **combat role** (combat “class”): what you bring to a fight—kit, tuning band, party expectations. Not used for crafting or gathering. |
 | **Skill** | A **non-combat** trained capability only (gather, craft, etc.). Never used to mean the combat gig. |
-| **Sub-gig** | A **secondary gig** paired with your **main gig** on one loadout. Used for **limited** cross-gig ability access—see [Sub-gigs](#sub-gigs-ffxi-style) below—not for crafting or replacing the main gig’s identity in combat. |
+| **Sub-gig** | A **secondary gig** paired with your **main gig** on one loadout. Used for **limited** cross-gig ability access—see [gigs.md](gigs.md) (**Main gig + sub-gig**)—not for crafting or replacing the main gig’s identity in combat. |
 
 Fiction and UI may still say *job*, *contract*, or *loadout* in dialogue; design vocabulary stays **gig** / **skill** to avoid ambiguity.
 
@@ -21,19 +21,7 @@ Fiction and UI may still say *job*, *contract*, or *loadout* in dialogue; design
 
 ## Gigs (combat)
 
-A **gig** is the **combat identity** you bring to a fight: ability access, baseline tuning band, and party expectations (tank, support, control, damage, etc.).
-
-- **Swap rules (agreed):** **No on-the-fly swap.** Changing **main gig**, **sub-gig**, or both happens only at a **safe hub**—a **city**, **home base**, or other **designated swap location** (world/data-defined). Not in the field, not mid-combat. **Open:** exact site list, fees, faction gates, or cooldowns at the hub.
-- **Combat progression (agreed):** **Per gig.** Each gig has its **own level/XP track** (and later mastery/perks on that gig). There is **no** shared single “combat rank” that advances all gigs at once. **Open:** when gig XP is awarded (e.g. only while main, sub, or both).
-- **Mastery/perks** can attach to **gigs** (combat expression) while **skills** use the same *idea* for craft depth (E2.M3-style), or stay separate—**open**.
-
-### Sub-gigs (FFXI-style)
-
-**Agreed:** each loadout has a **sub-gig** slot so one character mixes two gigs without full dual-main power. That opens a **large space of creative builds** as the gig roster grows—no need to enumerate counts; the point is **breadth of choice**.
-
-- **Reference pattern (FFXI-style):** at **main gig** per-gig level **X**, the **sub-gig** contributes abilities (and any sub-gated systems) only up to an **effective sub level** of **⌊X / 2⌋** (and not above the **sub-gig’s own trained level**—**open** how `min`/`floor` interacts). Exact floor/rounding **TBD**.
-- **Intent:** hybrid builds and party coverage (e.g. main damage + sub support tools) without letting a sub match a fully leveled second gig.
-- **Still open:** **gear** (likely still **main-gig–restricted** for combat gear; sub only feeds **abilities**), **consumable** amplification (main vs. sub), **PvP** ceilings, and UI (two gig strips on HUD). **Sub-gig** choice changes use the same **hub-only** rules as main gig swap.
+The **gig** artifact—**roles**, **hub swap**, **per-gig progression**, **main + sub-gig**, **party/LFG**, **PvP notes**, and **gig-only open questions**—is **[gigs.md](gigs.md)**. This file keeps **vocabulary**, **why hybrid**, and **seams** with **skills**.
 
 ## Skills (non-combat, classless)
 
@@ -99,6 +87,6 @@ Categories group skills for **UI and balance** (e.g. *Gathering*, *Craft*, *Tech
 
 ## Next artifacts
 
-- **Gigs** — roster size, main vs. **sub-gig** UX, **hub** definitions & swap UX, party finder tags, PvP ([overview](overview.md)).
+- **[gigs.md](gigs.md)** — gig roster, hub UX, LFG, PvP (started; extend there).
 - **Abilities** — **gig-locked** vs. **item-locked** vs. **skill-gated**.
 - **Items** — **equip:** gig rules; **craft:** **skills** (and recipe/rep), never gig level.