docs: address 2026-04-30 documentation review suggestions

docs/game-design/README.md

@@ -8,4 +8,4 @@
 
 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), **[crafting](crafting.md)** (recipes, pipeline), **[economy](economy.md)** (faucets, sinks, trade), **[death-loss-recovery](death-loss-recovery.md)** (stakes, recovery), **[risk-security-bands](risk-security-bands.md)** (tiers, PvP eligibility), **[zones](zones.md)** (place identity), travel/mechanics stubs, 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/).
+Implementation-facing breakdowns stay under [`docs/decomposition/`](../decomposition/README.md) and plans under [`docs/plans/`](../plans/) (see [`docs/plans/README.md`](../plans/README.md) for **NEO-*** vs legacy **`NEON-*`** plan filenames).

docs/game-design/abilities.md

@@ -2,7 +2,7 @@
 
 Vision for **what the player triggers** in play: combat **kits**, non-combat **skill interactions**, and **item**-carried actions—and how those map to **gigs**, **`SkillDef`**, and **Seams**. This is **not** a full ability list or data schema; it steers combat design, UX, and implementation boundaries.
 
-**Framing:** [progression.md](progression.md) (**gig** vs **skill**). **Combat roles:** [gigs.md](gigs.md). **Gear, craft, consumables:** [skills.md](skills.md) **Seams** ([anchor](skills.md#seams-gigs-skills)). **Item buckets & acquisition:** [items.md](items.md). **Gather → craft economy spine:** [gathering.md](gathering.md), [crafting.md](crafting.md). **Combat pillar pointers:** [overview.md — Combat pillars](overview.md#combat-pillars-vision-stub).
+**Framing:** [progression.md](progression.md) (**gig** vs **skill**). **Combat roles:** [gigs.md](gigs.md). **Gear, craft, consumables:** [skills.md](skills.md) — [Seams (gigs ↔ skills)](skills.md#seams-gigs-skills). **Item buckets & acquisition:** [items.md](items.md). **Gather → craft economy spine:** [gathering.md](gathering.md), [crafting.md](crafting.md). **Combat pillar pointers:** [overview.md — Combat pillars](overview.md#combat-pillars-vision-stub).
 
 ## Vocabulary
 

docs/game-design/overview.md

@@ -39,21 +39,14 @@ Neon Sprawl’s design work here starts from **concrete visions** of progression
 
 ### Planned topics (stubs)
 
-Link new files here when they exist; remove or rewrite this subsection once the table is populated.
+**Shipped vision docs** are listed in the [Artifact index](#artifact-index) above—update that table when a new first-class file lands.
 
-- **Progression** — [progression.md](progression.md): hybrid **gig + skill** overview and vocabulary. **Gigs:** [gigs.md](gigs.md). **Skills** + seams: [skills.md](skills.md). Recruitment channel **deferred**; *professions* stay folded into **skills** + rep unless a future doc defines something separate.
+The bullets below are **roadmap / not-yet-first-class-file** topics (or pointers into existing docs for cross-cutting angles):
-- **Zones** — [zones.md](zones.md): tone, danger, faction/economic **hooks**; **graph** in [E4.M1](../decomposition/modules/E4_M1_ZoneGraphAndTravelRules.md).
+
-- **Travel & connections** — how places link (gates, costs, downtime, danger en route); complements zone identity.
+- **Travel & connections** — how places link (gates, costs, downtime, danger en route); complements [zones.md](zones.md) and [E4.M1](../decomposition/modules/E4_M1_ZoneGraphAndTravelRules.md).
-- **Mechanics** — loops, constraints, what the server vs. client must honor.
+- **Mechanics** — loops, constraints, what the server vs. client must honor (no dedicated vision file yet).
-- **Items** — [items.md](items.md): categories, rarity philosophy, crafting vs. drops; **Seams** for gig/skill gates.
+- **Factions & reputation** — who remembers you, grudges, access gates; ties [gigs.md](gigs.md), [skills.md](skills.md), future faction doc.
-- **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).
+- **Combat pillars** — [Vision stub below](#combat-pillars-vision-stub); **items in combat** in [items.md](items.md).
-- **Gathering & resources** — [gathering.md](gathering.md): nodes, competition, exhaustion, open-world contesting; **skill XP** not **gig** XP.
-- **Crafting & recipes** — [crafting.md](crafting.md): depth vs breadth, failure, quality, stations; **skill XP**; [items.md](items.md) for output buckets.
-- **Economy** — [economy.md](economy.md): currency, sinks, trade, **E3.M5** / **E8.M3**; **mission** payouts vs **combat** loot ([progression.md](progression.md)).
-- **Factions & reputation** — who remembers you, grudges, access gates; **gig** story arcs: [gigs.md](gigs.md), rep + seams: [skills.md](skills.md).
-- **Combat pillars** — [Vision stub below](#combat-pillars-vision-stub): PvE vs. PvP stance, readability, time-to-kill, fairness; **items in combat** in [items.md](items.md).
-- **Death, loss & recovery** — [death-loss-recovery.md](death-loss-recovery.md): stakes, **E3.M4**/**E6.M3**, recovery UX.
-- **Risk & security bands** — [risk-security-bands.md](risk-security-bands.md): **tiers**, **PvP** opt-in, **theft**/gather **contest** hooks; **place** **fiction**: [zones.md](zones.md).
 - **Social play** — squad scale, corps, trust, betrayal affordances, async cooperation.
 - **Encounters & enemy roles** — archetypes, what a fight teaches, variety without noise. **Skill + gig split runs:** [brainstorm/hack-bodyguard-missions.md](brainstorm/hack-bodyguard-missions.md).
 - **Onboarding** — first session hook, clarity vs. mystery, how much systems the new player sees.
@@ -79,5 +72,5 @@ Combat is still missing a **single** pillar doc. Until then, use this table for
 | Area | Location |
 |------|----------|
 | Module / epic breakdown | [`docs/decomposition/`](../decomposition/README.md) |
-| Implementation plans | [`docs/plans/`](../plans/) |
+| Implementation plans | [`docs/plans/`](../plans/) — [README (NEO vs NEON filenames)](../plans/README.md) |
 | Architecture | [`docs/architecture/`](../architecture/tech_stack.md) |

docs/plans/NEON-29-implementation-plan.md

@@ -1,5 +1,7 @@
 # NEON-29 Implementation Plan — Expand prototype client district for camera/nav stress QA
 
+> **Historical — Jira archive.** This file preserved the **Atlassian / NEON-*** story record. **Active tracker:** Linear **NEO-***, team Neon Sprawl. The same work is described for implementation kickoff in [**NEO-19** — implementation plan](NEO-19-implementation-plan.md) (same title and scope). Do not open new work against **NEON-*** keys.
+
 ## Story reference
 
 - **Key:** [NEON-29](https://neon-sprawl.atlassian.net/browse/NEON-29)

docs/plans/README.md

@@ -0,0 +1,15 @@
+# Implementation plans (`docs/plans/`)
+
+Story-level implementation plans live here, keyed by **Linear issue id** (`NEO-*`) when the work is tracked in Linear (team **NEO**, Neon Sprawl).
+
+## Legacy `NEON-*` filenames
+
+A small number of files keep the historical **Jira / Atlassian `NEON-*`** key in the **filename** only. They are **not** the active issue tracker for new work.
+
+- Each such file includes a short **Historical** banner at the top pointing at the matching **`NEO-*`** plan (same scope) where kickoff and commits should align.
+- Prefer opening and linking **`NEO-*`** issues and plans for new contributors.
+
+## Conventions
+
+- New or moved plans: `docs/plans/{LINEAR_KEY}-implementation-plan.md` (see [story kickoff](../../.cursor/rules/story-kickoff.md)).
+- Cross-links from decomposition and game-design docs should use **`NEO-*`** URLs (Linear) for current engineering work.

docs/reviews/2026-04-30-documentation-review.md

@@ -0,0 +1,53 @@
+# Documentation review — game design + decomposition alignment
+
+**Date:** 2026-04-30  
+**Scope:** Representative pass over `docs/game-design/` (index, progression vocabulary, skills roster + seams hooks, abilities, gathering, risk/security), `docs/decomposition/README.md`, `docs/decomposition/modules/documentation_and_implementation_alignment.md`, and spot-checked epic/module paths referenced from those docs.  
+**Base:** Workspace as of 2026-04-30 (no branch named).
+
+## Verdict
+
+**Approve with suggestions** — vision docs and decomposition cross-links are coherent with the hybrid gig/skill model; no blocking factual errors found in the sampled paths. A few polish items improve discoverability and reader trust.
+
+## Summary
+
+Game-design entry points (`README.md`, `overview.md`, `progression.md`, `skills.md`, `abilities.md`, `gathering.md`, `risk-security-bands.md`) agree on **gig** = combat role, **skill** = non-combat, **combat encounter → gig XP** vs **gather/craft → skill XP**, and **Seams** as the gear/craft/deploy boundary. Decomposition README and the implementation alignment table mirror **E1.M3** / **E1.M4** story landings without contradicting the register’s **In Progress** rows. Sampled relative links to epics, **E4.M1** / **E4.M4**, **E6.M1**–**M3**, **E3.M3**, and `docs/architecture/tech_stack.md` resolve. Residual risk is mostly **legacy plan naming** (**NEON-*** vs **NEO-***) and small markdown UX nits.
+
+## Documentation checked
+
+| Path | Assessment |
+|------|------------|
+| `docs/game-design/README.md` | **Matches** — index, correct links to overview, progression, decomposition, plans. |
+| `docs/game-design/overview.md` | **Matches** — artifact table, hybrid links, Epic 4 slice anchor for risk, architecture link valid. |
+| `docs/game-design/progression.md` | **Matches** — vocabulary table aligned with skills/gigs; Epic 2 Slice 3 note matches gathering/crafting docs. |
+| `docs/game-design/skills.md` (incl. roster + `<a id="seams-gigs-skills">`) | **Matches** — explicit seam anchor; roster and Process/Make boundaries consistent with progression. |
+| `docs/game-design/abilities.md` | **Partially matches** — content aligns with gigs/skills/items; link text `[anchor](skills.md#…)` is confusing (see Suggestions). |
+| `docs/game-design/gathering.md` | **Matches** — skill XP vs gig XP; module links (E3.M1, E1.M3, E3.M3, E4.M2) present on disk. |
+| `docs/game-design/risk-security-bands.md` | **Matches** — E4.M4 / E6.M1–M2 / server authority framing matches docs-review ground truth. |
+| `docs/decomposition/README.md` | **Matches** — epic table, tooling CT.* note, links to contracts and register. |
+| `docs/decomposition/modules/documentation_and_implementation_alignment.md` | **Matches** — E1.M3/E1.M4 narrative consistent with `module_dependency_register.md` grep for E1.M4. |
+| `docs/decomposition/epics/epic_04_world_topology.md` (slice anchors) | **Matches** — `#epic-4-slice-2` anchor exists for risk doc deep links. |
+| `neon_sprawl_vision.plan.md` (existence check from doc links) | **Matches** — file at repo root as linked from game-design. |
+| `docs/plans/NEON-29-implementation-plan.md` | **N/A** (sampled for drift) — legacy Jira **NEON-*** plan alongside Linear **NEO-*** plans; see Suggestions. |
+
+## Blocking issues
+
+None identified in this pass.
+
+## Suggestions
+
+1. ~~**`abilities.md` framing link** — Replace the link text `anchor` with something meaningful (e.g. `Seams (gigs ↔ skills)`) in the sentence that currently uses `[anchor](skills.md#seams-gigs-skills)` so readers scanning links see the destination intent.~~ **Done.** (`docs/game-design/abilities.md`)
+2. ~~**Legacy `NEON-*` vs `NEO-*` plans** — `docs/plans/NEON-29-implementation-plan.md` still points at Atlassian; consider a short note in `docs/plans/` (only if you add a `README.md` there) or a header in each legacy file: “superseded by Linear NEO-* / historical” so new contributors do not treat **NEON-*** as the active tracker.~~ **Done.** — Banner on [`NEON-29-implementation-plan.md`](../plans/NEON-29-implementation-plan.md) → [NEO-19](../plans/NEO-19-implementation-plan.md); [`docs/plans/README.md`](../plans/README.md).
+3. ~~**`overview.md` “Planned topics (stubs)”** — Large overlap with the artifact index above it; optional consolidation would reduce maintenance when adding a new vision file (update one table instead of two).~~ **Done.** — Stub list trimmed to roadmap-only bullets; index owns shipped files.
+
+## Nits
+
+- **`documentation_and_implementation_alignment.md`** — The E1.M3 table cell is very long; fine for a living log, but harder to diff. Optional: split per-ticket bullets under the module page only, keep one line + “see module doc” in the table.
+- **TODO block in `overview.md` (rating / compliance)** — Appropriate as vision debt; no change required unless stakeholders want it moved to a single “compliance” stub file.
+
+## Verification
+
+After any edits:
+
+1. ~~Re-open `docs/game-design/abilities.md` and confirm the Seams link reads naturally.~~ **Checked** (2026-05-05 follow-up).
+2. ~~`rg 'NEON-' docs/plans` — decide whether each hit is archival or should gain a one-line deprecation pointer.~~ **Checked** — only [`NEON-29-implementation-plan.md`](../plans/NEON-29-implementation-plan.md); archival banner + [`docs/plans/README.md`](../plans/README.md).
+3. Spot-check any new `docs/game-design/*.md` against `progression.md` vocabulary and `skills.md` Seams once before filing implementation plans.