docs: document player-point-change bootstrap slice

Author: MikelCalvo

README.md

@@ -17,6 +17,7 @@ Current scope of the project:
 - A deterministic selected-character `SYNC_POSITION` reconciliation path wired through the current bootstrap runtime.
 - A first visible-world bootstrap that inserts the selected character into the game world after `ENTERGAME`.
 - A first self-only `CHARACTER_UPDATE` refresh emitted immediately after the visible-world insert.
+- A first self-only `PLAYER_POINT_CHANGE` refresh emitted immediately after the selected-character update.
 - Multi-stage Docker build with a lightweight runtime image that keeps Go debug information intact by avoiding stripped builds.
 
 ## Near-term goal
@@ -114,6 +115,7 @@ Legend:
 - `spec/protocol/select-world-entry.md`
 - `spec/protocol/visible-world-bootstrap.md`
 - `spec/protocol/character-update-bootstrap.md`
+- `spec/protocol/player-point-change-bootstrap.md`
 - `spec/protocol/sync-position-bootstrap.md`
 - `spec/protocol/boot-path.md`
 - `spec/protocol/packet-matrix.md`
@@ -188,7 +190,7 @@ Current stub bootstrap credentials:
 
 Current minimal runtime path exposed by the shipped binaries:
 - `authd`: `HANDSHAKE -> AUTH -> LOGIN3 -> AUTH_SUCCESS`
-- `gamed`: `HANDSHAKE -> LOGIN -> SELECT -> EMPIRE_SELECT? -> CHARACTER_CREATE? -> CHARACTER_SELECT -> LOADING -> GAME -> CHARACTER_ADD -> CHAR_ADDITIONAL_INFO -> CHARACTER_UPDATE -> MOVE/SYNC_POSITION`
+- `gamed`: `HANDSHAKE -> LOGIN -> SELECT -> EMPIRE_SELECT? -> CHARACTER_CREATE? -> CHARACTER_SELECT -> LOADING -> GAME -> CHARACTER_ADD -> CHAR_ADDITIONAL_INFO -> CHARACTER_UPDATE -> PLAYER_POINT_CHANGE -> MOVE/SYNC_POSITION`
 
 This is still a bootstrap runtime, not full gameplay.
 What exists today:
@@ -199,7 +201,7 @@ What exists today:
 - deterministic selected-character `SYNC_POSITION` reconciliation in `GAME`
 - bootstrap movement updates character coordinates and persists them across fresh auth/game sessions
 - empty-account bootstrap flow can select empire before first character creation, and that choice persists across fresh auth/game sessions
-- the selected character is inserted into the visible world after `ENTERGAME` via minimal `CHARACTER_ADD` + `CHAR_ADDITIONAL_INFO` + `CHARACTER_UPDATE`
+- the selected character is inserted into the visible world after `ENTERGAME` via minimal `CHARACTER_ADD` + `CHAR_ADDITIONAL_INFO` + `CHARACTER_UPDATE` + `PLAYER_POINT_CHANGE`
 
 What still does not exist yet:
 - compatibility-grade persistence matching the legacy target

docs/plans/2026-04-18-player-point-change-bootstrap.md

@@ -0,0 +1,85 @@
+# Player-Point-Change Bootstrap Implementation Plan
+
+> For Hermes: use test-driven-development. Keep slices tiny and push one commit at a time.
+
+Goal: add the first minimal `PLAYER_POINT_CHANGE` emission after `ENTERGAME` so the selected character gets a deterministic self-only point refresh during the bootstrap transition into `GAME`.
+
+Architecture: freeze a project-owned codec for `PLAYER_POINT_CHANGE`, extend visible-world bootstrap tests to expect the extra frame, then wire the minimal runtime to emit one deterministic self-only point refresh for the selected character.
+
+Tech stack: Go 1.26, existing frame/session/world packages, current authd/gamed bootstrap runtime.
+
+---
+
+## Task 1: Freeze player-point-change packet codec
+Objective: define the server-side `PLAYER_POINT_CHANGE` packet shape.
+
+Files:
+- Modify: `internal/proto/world/world.go`
+- Modify: `internal/proto/world/world_test.go`
+
+Steps:
+1. Write failing tests for:
+   - `PLAYER_POINT_CHANGE` encode/decode
+   - invalid header rejection
+2. Run: `go test ./internal/proto/world`
+3. Implement the smallest codec set to pass.
+4. Re-run: `go test ./internal/proto/world`
+5. Commit: `feat: add player-point-change packet codec`
+
+## Task 2: Extend visible-world bootstrap in the runtime
+Objective: emit `PLAYER_POINT_CHANGE` after the selected-character visible bootstrap.
+
+Files:
+- Modify: `internal/minimal/factory.go`
+- Modify: `internal/minimal/factory_test.go`
+
+Steps:
+1. Write failing tests for:
+   - existing selected character gets the extra point-change frame
+   - newly created selected character gets the same sequence
+2. Run: `go test ./internal/minimal`
+3. Implement the smallest selected-character packet builder.
+4. Re-run: `go test ./internal/minimal`
+5. Commit: `feat: add player-point-change bootstrap`
+
+## Task 3: Cover boot composition
+Objective: verify the composed boot flow and TCP harness can emit the extra point-change frame.
+
+Files:
+- Modify: `internal/boot/flow_test.go`
+- Modify: `internal/boot/flow_socket_test.go`
+
+Steps:
+1. Extend visible-world bootstrap tests to expect `PLAYER_POINT_CHANGE`.
+2. Run: `go test ./internal/boot`
+3. Re-run after wiring the test config.
+4. Commit: `test: cover player-point-change bootstrap`
+
+## Task 4: Update docs
+Objective: document the first `PLAYER_POINT_CHANGE` slice.
+
+Files:
+- Modify: `README.md`
+- Modify: `spec/protocol/README.md`
+- Modify: `spec/protocol/visible-world-bootstrap.md`
+- Modify: `spec/protocol/boot-path.md`
+- Modify: `spec/protocol/packet-matrix.md`
+- Create: `spec/protocol/player-point-change-bootstrap.md`
+
+Steps:
+1. Document packet layout and bootstrap order.
+2. Run: `go test ./... && go vet ./...`
+3. Commit: `docs: document player-point-change bootstrap slice`
+
+## Verification
+- `go test ./internal/proto/world`
+- `go test ./internal/minimal`
+- `go test ./internal/boot`
+- `go test ./...`
+- `go vet ./...`
+
+## Scope guardrails
+- Do not add repeated point-change streams yet
+- Do not add other entities yet
+- Do not add combat/inventory-driven point changes yet
+- Keep the slice deterministic and selected-character only

spec/protocol/README.md

@@ -11,6 +11,7 @@ The repository targets TMP4-era client compatibility, but the protocol contract
 - `login-selection.md` — minimal login-by-key and selection-surface packet layouts
 - `select-world-entry.md` — minimal selection, loading, and enter-game packet choreography
 - `character-update-bootstrap.md` — first self-only state refresh after entering `GAME`
+- `player-point-change-bootstrap.md` — first self-only point refresh after entering `GAME`
 - `sync-position-bootstrap.md` — first self-only sync-position reconciliation after entering `GAME`
 - `boot-path.md` — first milestone from connect to basic movement
 - `packet-matrix.md` — working inventory for the first protocol slice

spec/protocol/boot-path.md

@@ -103,6 +103,7 @@ Expected outcomes:
 - the server keeps the session stable after the transition
 - the selected character is inserted into the visible world with deterministic bootstrap packets
 - the selected character receives a first deterministic `CHARACTER_UPDATE` refresh after the visible insert
+- the selected character receives a first deterministic `PLAYER_POINT_CHANGE` refresh during the same bootstrap burst
 
 ## 9. Basic movement works
 The client sends a movement packet and the server processes it in the live game phase.
@@ -137,5 +138,6 @@ This document depends on:
 - `spec/protocol/frame-layout.md`
 - `spec/protocol/packet-matrix.md`
 - `spec/protocol/character-update-bootstrap.md`
+- `spec/protocol/player-point-change-bootstrap.md`
 - `spec/protocol/sync-position-bootstrap.md`
 - `docs/testing-strategy.md`

spec/protocol/packet-matrix.md

@@ -51,7 +51,7 @@ Status values:
 | `PLAYER_DELETE_SUCCESS` | server -> client | `0x020E` | select | planned | later milestone |
 | `MAIN_CHARACTER` | server -> client | `0x0210` | loading | documented | main actor bootstrap |
 | `PLAYER_POINTS` | server -> client | `0x0214` | loading/game bootstrap | documented | initial stat payload |
-| `PLAYER_POINT_CHANGE` | server -> client | `0x0215` | game | planned | likely needed shortly after bootstrap |
+| `PLAYER_POINT_CHANGE` | server -> client | `0x0215` | game bootstrap | documented | first self-only point refresh after the selected-character bootstrap |
 
 ## Movement
 

spec/protocol/player-point-change-bootstrap.md

@@ -0,0 +1,71 @@
+# Player-point-change bootstrap
+
+This document freezes the first minimal `PLAYER_POINT_CHANGE` behavior used by the bootstrap runtime after `ENTERGAME`.
+
+The goal of this slice is narrow:
+- emit a deterministic self-only point refresh after the selected character enters `GAME`
+- keep the bootstrap limited to one selected character
+- avoid adding a broader stat system too early
+
+It does not yet define general-purpose point updates during gameplay.
+
+## Covered packet
+
+- `PLAYER_POINT_CHANGE` server -> client (`0x0215`)
+
+## Working flow
+
+The current project-owned bootstrap behavior after `ENTERGAME` is:
+
+1. the session transitions to `GAME`
+2. the server emits:
+   - `PHASE(GAME)`
+   - `CHARACTER_ADD`
+   - `CHAR_ADDITIONAL_INFO`
+   - `CHARACTER_UPDATE`
+   - `PLAYER_POINT_CHANGE`
+3. the `PLAYER_POINT_CHANGE` frame refreshes one deterministic point for the selected character only
+
+This slice is intentionally narrow:
+- only the selected character receives the point refresh
+- only one deterministic point-change frame is emitted during bootstrap
+- no fanout to other sessions is required yet
+- no general-purpose stat recalculation engine is required yet
+
+## Packet layout
+
+Direction:
+- server -> client
+
+Header:
+- `0x0215`
+
+Payload layout:
+- `vid` — `uint32`
+- `type` — `uint8`
+- `amount` — `int32`
+- `value` — `int32`
+
+Frame length:
+- `17` bytes total (`4 + 13`)
+
+## Current bootstrap behavior
+
+The bootstrap runtime currently emits one deterministic self-only point refresh:
+- `type = 1`
+- `amount` mirrors the selected character bootstrap point value at index `1`
+- `value` mirrors the same selected character bootstrap point value
+
+For the current stub/bootstrap characters this means:
+- existing selected character refresh uses its persisted point value
+- newly created selected character refresh uses its initial point value
+
+This is good enough for the first `PLAYER_POINT_CHANGE` slice, but not yet the final compatibility target.
+
+## Out of scope
+
+This slice does not yet freeze:
+- repeated point-change streams during gameplay
+- point-change updates for other entities
+- derived stat recalculation rules
+- inventory, buffs, or combat-driven point updates

spec/protocol/visible-world-bootstrap.md

@@ -15,6 +15,7 @@ It does not yet freeze the broader entity stream for NPCs, mobs, items, or other
 - `CHARACTER_ADD`
 - `CHAR_ADDITIONAL_INFO`
 - `CHARACTER_UPDATE`
+- `PLAYER_POINT_CHANGE`
 
 ## Working flow
 
@@ -28,10 +29,12 @@ The current project-owned world bootstrap after `ENTERGAME` is:
    - `CHARACTER_ADD`
    - `CHAR_ADDITIONAL_INFO`
    - `CHARACTER_UPDATE`
+   - `PLAYER_POINT_CHANGE`
 
 This slice is intentionally narrow:
 - only the selected character is announced
 - only the selected character gets a deterministic self-update refresh
+- only the selected character gets a deterministic self-only point refresh
 - no item/NPC/mob bursts are required yet
 - no fanout to other sessions is required yet
 
@@ -91,7 +94,7 @@ The bootstrap runtime currently uses deterministic values for the visible insert
 - a fixed self-insert type for player characters
 - deterministic movement/attack speed values
 - deterministic state bootstrap
-- selected character coordinates, race, empire, level, visible parts, and self-update state
+- selected character coordinates, race, empire, level, visible parts, self-update state, and one self-only point refresh
 
 This is good enough for the first visible-world slice, but not yet the final compatibility target.