docs: add pioneer charter dungeon design

CHANGELOG.md

@@ -87,6 +87,9 @@ versioned release tag yet, so entries are organized as pre-alpha snapshots.
   by loading the server-owned Nakama NPC Frame list on Play Mode start.
 - Prototype debug panels now default to hidden hotkey toggles so they no longer
   overlap the main HUD in Play Mode.
+- Gate, dungeon, and Pioneer Charter design doc for ranked Gates,
+  server-issued first-clear rights, common Tower/Gate genre mechanics, and
+  in-game-only Clearance Royalty loops.
 
 ### Changed
 

ROADMAP.md

@@ -1,7 +1,7 @@
 # SECOND SPAWN Roadmap
 
 Status: Pre-alpha, vertical slice foundation in development.
-Last updated: 2026-05-18.
+Last updated: 2026-05-19.
 
 This roadmap tracks implementation status. Detailed design remains in `docs/`,
 especially `docs/design/02-vertical-slice-spec.md` and
@@ -209,6 +209,11 @@ MVP, and a visible offline-agent prototype.
 - [ ] Implement the first server-authoritative contested loot rule for taking
   BodyTime or SECOND from another user after a validated PvP or zone event.
 - [ ] Add one dungeon instance with one boss and grounded dialogue.
+- [ ] Add a server-owned dungeon clear ledger before any Pioneer Charter
+  rewards.
+- [ ] Add a non-economic first-clear record for the first Gate or dungeon.
+- [ ] Design capped in-game Pioneer Charter / Clearance Royalty rules after
+  combat, dungeon validation, and reward ledgers exist.
 - [ ] Add one Hunter NFT skin equip placeholder with DOS Chain escrow design
   still server-authoritative.
 - [ ] Run Multiplayer Play Mode smoke for 2-4 local clients.
@@ -232,6 +237,7 @@ MVP, and a visible offline-agent prototype.
 - [ ] Pet breeding system.
 - [ ] Movement-only mount system.
 - [ ] Economy balancing.
+- [ ] Gate tiering, Pioneer Charter, and in-game Clearance Royalty balancing.
 - [ ] Live ops infrastructure.
 - [ ] Public beta launch.
 

docs/README.md

@@ -28,6 +28,7 @@ Relevant docs:
 - [Overview Design](design/06-overview-design.md)
 - [Networked Player Controller Prototype](design/07-player-controller-prototype.md)
 - [Pirate Adventure Reference Review](design/09-pirate-adventure-reference-review.md)
+- [Gate, Dungeon, and Pioneer Charter System](design/15-gate-dungeon-pioneer-charter-system.md)
 
 ## Signature Features
 

docs/SUMMARY.md

@@ -20,6 +20,7 @@
 - [Pirate Adventure Reference Review](design/09-pirate-adventure-reference-review.md)
 - [Character Profile, Soul, and Agent Memory](design/10-character-profile-agent-memory.md)
 - [NPC Agent Brain Architecture](design/11-npc-agent-brain-architecture.md)
+- [Gate, Dungeon, and Pioneer Charter System](design/15-gate-dungeon-pioneer-charter-system.md)
 
 ## Architecture Decision Records
 

docs/design/02-vertical-slice-spec.md

@@ -2,7 +2,7 @@
 
 *Status: Spec with prototype progress*
 *Created: 2026-05-14*
-*Last updated: 2026-05-17*
+*Last updated: 2026-05-19*
 *Target completion: 3-6 months from setup (T+3 to T+6 from 2026-05-14)*
 
 > Note: This is the SPEC version (planning the slice). After slice is built, rename to `02-vertical-slice-report.md` and fill the report template (build velocity, playtest results, recommendation PROCEED/PIVOT/KILL).
@@ -24,6 +24,7 @@ This is two questions in one: **does the design loop fun?** AND **is the archite
 | **Zone** | 1 small open area + 1 hub town |
 | **Character class** | 1 combat Frame archetype (may use one MetaDOS Hunter Frame skin as the visual direction) |
 | **Dungeon instance** | 1 (single instance with 1 boss encounter) |
+| **Gate first-clear record** | Concept-only slice surface: one server-owned clear log or badge if dungeon validation exists; no in-game royalty payout yet |
 | **Boss with LLM dialogue** | 1 (Convai-driven, grounded in zone state) |
 | **Quest line** | 1 (3-5 quests sequential) |
 | **Reincarnation MVP** | Die -> test SECOND -> new Frame with current-body reset |
@@ -63,6 +64,8 @@ Still missing from the playable slice:
 - Normal-play TIME earn and spend sources outside debug controls.
 - Player-vs-player or contested-zone time-loot rules.
 - Questline, dungeon, boss, and grounded dialogue content.
+- Pioneer Charter runtime reward payouts. The slice may add a first-clear debug
+  record after dungeon clear validation exists, but not Clearance Royalty.
 - Production HUD and reincarnation presentation flow.
 - NFT skin equip and escrow.
 - Dedicated server deployment and 4-20 player load validation.
@@ -147,6 +150,7 @@ When slice is complete, decision tree:
 | ---- | ---- | ---- |
 | SECOND economy (cost per reincarnation, source, sink) | Phase 5 | JOY (input later) |
 | TIME economy tuning (drain, earn, spend, transfer, top-up rules) | Phase 6 | JOY (input later) |
+| Pioneer Charter first-clear reward resource and duration | Post-slice / Alpha | JOY (input later) |
 | Hunter Frame NFT integration approach (Option 1 vs Hybrid 1+3) | Phase 6 | JOY (input later) |
 | Voice NPC vendor | NOT in slice | Defer |
 | Hetzner VPS specs | Phase 8 (load test) | JOY |

docs/design/03-systems-index.md

@@ -2,7 +2,7 @@
 
 *Status: Living index*
 *Created: 2026-05-14*
-*Last updated: 2026-05-18*
+*Last updated: 2026-05-19*
 
 ---
 
@@ -19,6 +19,7 @@ SECOND SPAWN is a hybrid MMO + top-down ARPG. The mechanical scope spans:
 - Level/stat progression
 - Reincarnation loop (death -> SECOND -> new Frame)
 - TIME / SECOND body lifespan economy
+- Gate first-clear economy through server-issued Pioneer Charter records
 - NFT integration (DOS Chain via thirdweb)
 - Server-authoritative invariants (anti-cheat assumes open source)
 
@@ -46,6 +47,7 @@ This index enumerates every system the game needs, categorizes by Core/Gameplay/
 | 13 | Reincarnation flow (death -> SECOND -> new Frame) | Progression | VS | Prototype | [12-game-design-document.md](12-game-design-document.md) | Level/stats, NFT escrow, Persistence |
 | 14 | SECOND economy | Economy | VS | Not designed | (GDD pending - JOY input) | DOS Chain integration |
 | 36 | TIME / SECOND economy | Economy | VS | Prototype | [08-time-as-currency.md](08-time-as-currency.md) | Reincarnation, Combat, Persistence |
+| 38 | Gate first-clear and Pioneer Charter economy | Economy / Gameplay | Alpha | Concept | [15-gate-dungeon-pioneer-charter-system.md](15-gate-dungeon-pioneer-charter-system.md) | Dungeon, Combat, Persistence, Rewards, Anti-cheat |
 | 15 | NFT inventory (Hunter Frame skin slice scope) | Economy | VS | Not started | (TDD pending) | thirdweb-api MCP, Persistence |
 | 16 | NFT escrow (lock on equip, release on unequip) | Economy | VS | Not started | (TDD pending) | NFT inventory, DOS Chain |
 | 17 | Loot / drop tables | Economy | VS | Not started | (TDD pending) | Combat, persistence |
@@ -68,7 +70,7 @@ This index enumerates every system the game needs, categorizes by Core/Gameplay/
 | 34 | Telemetry / monitoring (Sentry + Grafana) | Meta | Alpha | Deferred | - | All systems |
 | 35 | Onboarding / tutorial | Meta | VS | Deferred (assume slice = no tutorial) | - | All gameplay systems |
 
-**Total: 37 systems identified for slice scope and post-slice roadmap.**
+**Total: 38 systems identified for slice scope and post-slice roadmap.**
 
 ---
 
@@ -79,7 +81,7 @@ This index enumerates every system the game needs, categorizes by Core/Gameplay/
 | **Core** | Foundation systems everything depends on | 5 (NetworkRunner, Controller, Camera, Input, Zone management) |
 | **Gameplay** | The systems that make the game fun | 7 (Combat, NPC dialogue, Quest, Dungeon, Boss LLM, AI agent, OpenClaw-connected NPC bridge) |
 | **Progression** | How the player grows over time | 2 (Level/stats, Reincarnation) |
-| **Economy** | Resource creation and consumption | 5 (SECOND, TIME / SECOND economy, NFT inventory, NFT escrow, Loot) |
+| **Economy** | Resource creation and consumption | 6 (SECOND, TIME / SECOND economy, Pioneer Charter, NFT inventory, NFT escrow, Loot) |
 | **Persistence** | Save state and continuity | 5 (Profile, Inventory, Quest, Level/stats, Auth) |
 | **UI** | Player-facing information displays | 6 (HUD, Inventory UI, NPC dialogue UI, Quest tracker, Reincarnation UI, Agent log) |
 | **Audio** | Sound and music systems | 1 (placeholder for slice) |
@@ -127,23 +129,24 @@ This index enumerates every system the game needs, categorizes by Core/Gameplay/
 24. TIME / SECOND economy (#36) - depends on: Reincarnation, Combat, Persistence
 25. SECOND economy (#14) - depends on: DOS Chain integration, Reincarnation
 26. AI agent for offline players (#11) - depends on: NetworkRunner, api.dos.ai model service, intent schema, Combat, TIME / SECOND economy
+27. Gate first-clear and Pioneer Charter economy (#38) - depends on: Dungeon, Combat, Persistence, Rewards, Anti-cheat
 
 ### Presentation Layer (depends on features)
 
-27. HUD (#23)
-28. Inventory UI (#24)
-29. NPC dialogue UI (#25)
-30. Quest tracker UI (#26)
-31. Reincarnation UI (#27)
-32. AI agent activity log UI (#28)
-33. Audio (#29)
+28. HUD (#23)
+29. Inventory UI (#24)
+30. NPC dialogue UI (#25)
+31. Quest tracker UI (#26)
+32. Reincarnation UI (#27)
+33. AI agent activity log UI (#28)
+34. Audio (#29)
 
 ### Meta Layer
 
-34. Anti-cheat verification (#33) - cuts across everything
-35. Quest progress persistence (#20) - depends on: Quest system
-36. Telemetry (#34) - depends on: everything
-37. Onboarding (#35) - depends on: all gameplay (deferred for slice)
+35. Anti-cheat verification (#33) - cuts across everything
+36. Quest progress persistence (#20) - depends on: Quest system
+37. Telemetry (#34) - depends on: everything
+38. Onboarding (#35) - depends on: all gameplay (deferred for slice)
 
 ---
 
@@ -157,6 +160,7 @@ This index enumerates every system the game needs, categorizes by Core/Gameplay/
 | NFT escrow (#16) | Technical | Latency between Unity equip action and DOS Chain confirmation | Optimistic UI + reconcile-on-failure; cache lock state in Supabase |
 | Reincarnation flow (#13) | Design | Carryover too generous = no death weight; too punitive = grind | Tune cost during slice playtests |
 | TIME / SECOND economy (#36) | Design + Economy | Constant drain can feel oppressive; weak drain can feel invisible | Start with danger-zone drain, one earn source, one spend sink |
+| Gate first-clear and Pioneer Charter economy (#38) | Economy + Anti-cheat | First-clear rewards can become exploit magnets or feel unfair if autonomous agents claim them while players sleep | Start with non-economic first-clear records; require server clear logs, caps, expiry, and human-led eligibility for economic Charters |
 | Photon Fusion 2 dedicated server (#1) | Technical | Solo dev capacity to run dedicated infra | Slice uses Photon Cloud free 20 CCU; production migration is post-slice |
 | Convai SDK in Unity (#7) | Technical | 3rd-party SDK may not test against Unity 6.5 beta | Have phase 2 fallback (`api.dos.ai` / api.dos.ai model service + custom LLM) ready in design |
 
@@ -190,6 +194,7 @@ Aligned with [02-vertical-slice-spec.md](02-vertical-slice-spec.md) build phases
 | 20 | Audio placeholder (#29) | Phase 9 | S | Slice-quality only |
 | 21 | Chat (#30) | Phase 9 | M | Nakama channel first, Supabase sidecar only if useful |
 | 22 | Polish + playtest | Phase 9 | XL | |
+| 23 | Gate first-clear and Pioneer Charter economy (#38) | Post-slice / Alpha | L | Start with ledger and badge before in-game royalty |
 
 Effort estimate: S = 1-3 days, M = 4-7 days, L = 1-2 weeks, XL = 2-4 weeks (solo dev + AI agent).
 
@@ -199,9 +204,9 @@ Effort estimate: S = 1-3 days, M = 4-7 days, L = 1-2 weeks, XL = 2-4 weeks (solo
 
 | Metric | Count |
 | ---- | ---- |
-| Total systems identified | 37 |
+| Total systems identified | 38 |
 | Systems with prototype implementation | 14 |
-| Design docs started | 12 |
+| Design docs started | 13 |
 | Design docs reviewed | 0 |
 | Design docs approved | 0 |
 | MVP systems with TDD started | 0 |
@@ -216,3 +221,4 @@ Effort estimate: S = 1-3 days, M = 4-7 days, L = 1-2 weeks, XL = 2-4 weeks (solo
 - [ ] Per-system TDD as each system is started (use `templates/technical-design-document.md`)
 - [ ] Re-run systems-index review at slice midpoint to add missed systems
 - [ ] Decompose AI agent autoplay (#11) into sub-systems before Phase 7 (highest risk)
+- [ ] Write TDD for Gate clear logs before implementing Pioneer Charter rewards

docs/design/12-game-design-document.md

@@ -2,7 +2,7 @@
 
 *Status: Pre-alpha GDD*
 *Created: 2026-05-16*
-*Last updated: 2026-05-18*
+*Last updated: 2026-05-19*
 *Source of truth level: Consolidates current design decisions from `docs/design/`, `AGENTS.md`, and accepted architecture direction. Per-system docs remain authoritative for implementation details.*
 
 ---
@@ -63,6 +63,7 @@ promise that the same UI or tuning will ship.
 | Permanent NPCs | `ZoneTest_Hub` can seed and display 10 permanent prototype NPC Frames from Nakama, each with fixed body identity and visual variant. |
 | Prototype NPC brain | Permanent NPC brains sense nearby actors, call the model-backed Nakama decision path, speak through model-selected `say` intent, and persist model speech through Nakama memory and relationship records. |
 | Backend foundation | Nakama owns durable game profile state, model-decision RPCs, and server-side intent validation before gameplay systems consume LLM output. |
+| Gate / dungeon economy | Design now includes temporary `Pioneer Charter` terminology for server-issued first-clear rights and in-game-only Clearance Royalty loops. No runtime implementation yet. |
 | Not implemented yet | Real combat damage, enemy loot, quest rewards, production HUD, player-vs-player time loot, wallet escrow, dungeon boss, and dedicated server deployment. |
 
 ---
@@ -171,6 +172,40 @@ Tone requirements:
   but TIME is the player-facing life medium. Do not add Nibiru-derived XP,
   cultivation tiers, rituals, or vertical-slice progression.
 
+### Gate and Dungeon Fantasy
+
+SECOND SPAWN can use the Korean manhwa-style fantasy of ranked Gates appearing
+in the real world, but the explanation remains sci-fi. Gates are unstable
+Nibiru-influenced breaches where ruined infrastructure, memory residue, spatial
+collapse, and TIME density form bounded combat instances.
+
+Useful reference pool:
+
+- Solo Leveling.
+- Omniscient Reader's Viewpoint.
+- Leveling with the Gods.
+- The Player Who Can't Level Up.
+- My S-Class Hunters.
+- SSS-Class Revival Hunter.
+- Second Life Ranker.
+- Return to Player.
+
+Secondary references include Murim Login, Solo Max-Level Newbie, The Advanced
+Player of the Tutorial Tower, Kill the Hero, Return of the Disaster-Class Hero,
+and Seoul Station's Necromancer. Do not use Tomb Raider King as a primary
+reference.
+
+Working vocabulary:
+
+- `Gate`, `Breach`, or `Shard Dungeon`: dungeon portal or instance source.
+- `Pioneer Charter`: temporary name for the server-issued first-clear right.
+- `Clearance Royalty`: temporary name for the in-game reward pool paid from
+  later clears of the same Gate version.
+
+All revenue language in this system means in-game resources only. It does not
+mean real-world revenue share, external yield, securities-like ownership, or
+passive income. See [15-gate-dungeon-pioneer-charter-system.md](15-gate-dungeon-pioneer-charter-system.md).
+
 ### MetaDOS Continuity / Timeline
 
 This timeline is inherited from the MetaDOS GDD and adapted for SECOND SPAWN:
@@ -620,6 +655,9 @@ Session model:
 
 - Players join instanced zones of roughly 4-20 players in the vertical slice.
 - Dungeons are separate instances.
+- Ranked Gates can become the fiction and discovery layer around dungeon
+  instances. The current rank vocabulary is F, E, D, C, B, A, and S, with S+,
+  SS, and SSS deferred until live-ops scale justifies them.
 - Guild PvP up to 50v50 is a future target, not vertical slice scope.
 - Server interest management must keep replication bounded.
 - Offline agents act inside server-approved contexts, not client-local simulations.
@@ -799,6 +837,7 @@ The economy is not fully designed. This GDD only defines resource roles and boun
 | TIME | Life medium loaded into humans and Frames, measured in SECOND | Body-bound once loaded, lost on body death unless future rules say otherwise |
 | SECOND | Unit, currency, and tokenized measure of TIME, used for rewards and reincarnation | Account or wallet-level, exact source and sink design undecided |
 | Loot and supplies | Tactical power and run support | Server-owned, no client-granted drops |
+| Pioneer Charter | Server-issued first-clear right for a Gate version | Concept only; can grant in-game prestige or capped in-game Clearance Royalty later |
 | NFT assets | Ownership-linked skins, weapons, pets | Bound through DOS Chain and escrow rules |
 
 Design constraints:
@@ -808,6 +847,8 @@ Design constraints:
 - Do not let LLMs mutate economy state.
 - Do not place chain or wallet mutation authority in the Unity client.
 - Keep vertical slice economy small: one SECOND earn source, one TIME spend sink, and test-token reincarnation.
+- Keep Gate first-clear rewards in-game only. Pioneer Charter and Clearance
+  Royalty must never be framed as real-world revenue share or external yield.
 
 ### TIME and SECOND Relationship
 
@@ -825,8 +866,54 @@ Open economy decisions:
 - Whether SECOND directly seeds body TIME or only gates body creation: [TODO: JOY input]
 - SECOND earning and sink design beyond reincarnation: [TODO: JOY input]
 - TIME earn, spend, drain, and transfer values: [TODO: JOY input]
+- First Pioneer Charter reward resource and duration: [TODO: JOY input]
 - Marketplace design: [TODO: JOY input]
 
+### Gate First-Clear Economy
+
+The temporary design direction is `Pioneer Charter`: when a party is the first
+to clear a newly discovered Gate version under server-validated conditions, the
+server may issue a first-clear right. In the short term this should be a badge,
+title, guild record, or debug ledger entry. Later it may grant a capped,
+time-limited in-game `Clearance Royalty` from later clears of that Gate.
+
+Pioneer Charter requirements:
+
+- The server records `gate_id`, `gate_version`, seed, party members, controller
+  types, clear time, objective hash, combat log hash, deaths, reincarnations,
+  reward ledger, and exploit-review state.
+- Clients, LLMs, offline agents, and OpenClaw-connected actors cannot grant or
+  self-report first-clear rights.
+- Human-led clears should be the first eligible category. Agent-assisted clears
+  can earn normal loot and activity, but should not claim the primary economic
+  Charter in the MVP.
+- Any in-game royalty must have caps, expiry, and exploit invalidation.
+
+Candidate royalty tuning remains placeholder only: F-E Gates could pay a small
+1-2 percent in-game pool for roughly a week, while high-rank Gates could pay
+larger capped shares for a season or until stabilization. Do not implement these
+numbers until combat, dungeon clear validation, append-only reward ledgers, and
+abuse review exist.
+
+Genre mechanics that should inform this system:
+
+- Gates, Towers, Scenarios, and dungeon rules are a visible rule layer added to
+  a modern world.
+- Rank exists at multiple levels: Frame, Gate, monster, item, guild, and clear
+  record.
+- Leveling is body-bound in SECOND SPAWN. Current-body level and stat growth can
+  reset on reincarnation while durable memories, titles, and clear records can
+  remain on the soul or account layer.
+- Skills should be layered as Frame skills, Soul/title records, and Agent
+  behavior policy instead of one generic fantasy skill sheet.
+- Hidden knowledge should come from NPC memory, Gate intel, previous clear
+  records, and agent logs rather than random untelegraphed secrets.
+- Rank is a public estimate and social permission layer, not absolute truth.
+  Body traits, equipment, TIME pressure, AI policy, memory, and Gate intel can
+  all make the real outcome diverge from rank.
+- Guilds, associations, registries, insurance, and clear records should become
+  useful social infrastructure, not just villains or quest flavor.
+
 ### Loot, Items, and Cosmetics
 
 Loot and itemization should support the ARPG loop without diluting the reincarnation pillar.