Align SCUM operations with reference tools

openspec/changes/align-scum-operations-with-reference-tools/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-13

openspec/changes/align-scum-operations-with-reference-tools/design.md

@@ -0,0 +1,28 @@
+## Context
+
+`scum_new_web` and `scum_robot` establish the useful operator shape: players can be searched and narrowed by squad, squads expose their rosters, maps use layers and marker inspection, and gifts distinguish definitions from a player's receipt history. The existing browser repository already has typed SCUM observations and gift workflows, so the design extends those contracts instead of importing the old direct-access path.
+
+## Decisions
+
+### Projection views compose existing facts
+
+The frontend reads users, squads, squad members, vehicles, flags, map points, observed timed-gift events, and platform gift APIs. It joins those responses only for display. A user action creates existing typed operations or gift grants; it never mutates a projection in the browser.
+
+### Plugin data packs own version-sensitive game data
+
+The SCUM manifest names a v57 gift-item catalog and map geometry data asset. The platform resolves a requested gift item through the installed server plugin and game version. Updating SCUM changes the plugin package, not platform code.
+
+### Observed events have a distinct target table
+
+`finished_timed_gift_spawner` represents a completed in-game timed-gift event. It is stored as `scum_gift_events`; `game_gift_catalogs`, revisions, and grants remain platform-owned operational data. This removes the ambiguous old `scum_gift_catalogs` observation table.
+
+### Map is geometric, not a copied game asset
+
+The plugin supplies world bounds and axis direction. The web client projects points into that normalized frame and exposes player, vehicle, base, and flag layers. No copyrighted tile bundle is copied. Trajectory playback remains dependent on independently collected track points.
+
+## Verification
+
+- Go tests covering observed-gift target and plugin-resolved gift items.
+- Plugin typecheck, tests, and manifest validation.
+- Frontend typecheck, tests, and build.
+- `scripts/check-structure.sh` and `openspec validate align-scum-operations-with-reference-tools --strict`.

openspec/changes/align-scum-operations-with-reference-tools/proposal.md

@@ -0,0 +1,23 @@
+## Why
+
+The SCUM projection pipeline now reads real v57 facts, but the five SCUM pages still present those facts as disconnected tables. The established `scum_new_web` and `scum_robot` tools have useful operator workflows for player search, squad rosters, map overlays, and gifts. Their direct database, FTP, and SQL-transport design does not fit this platform.
+
+## What Changes
+
+- Turn SCUM users into a searchable, squad-filterable projection view with player details and typed-operation entry points.
+- Show each squad with its linked roster and flags rather than a disconnected aggregate table.
+- Render current player, vehicle, base, and flag points in a versioned plugin-declared coordinate frame with independent layers and a selected-marker inspector.
+- Separate game-observed completed timed-gift events from platform-owned gift definitions, revisions, and grants.
+- Move SCUM gift item catalogs and map geometry out of platform code into versioned SCUM plugin data packs.
+
+## Boundaries
+
+- Platform remains the durable owner of projections, gift definitions, revisions, and grants; the plugin owns version-specific SQL, item keys, and map geometry; Run only executes declared work.
+- Do not reintroduce FTP, direct platform/browser access to `SCUM.db`, arbitrary SQL, raw RCON, host paths, or a `run/` source tree.
+- Do not copy third-party map tiles into this repository. The map is an operator coordinate board until a plugin-declared asset reference is available.
+
+## Impact
+
+- `platform/`: separates observed timed-gift events from platform gift catalog data and resolves gift item definitions from the registered plugin.
+- `platform_web/`: adds projection-oriented user, squad, map, and gift views within the existing themed console.
+- `plugins/examples/scum-server-plugin/`: declares SCUM v57 gift items and map geometry as versioned data-pack assets.

openspec/changes/align-scum-operations-with-reference-tools/specs/scum-operations-reference-alignment/spec.md

@@ -0,0 +1,33 @@
+## ADDED Requirements
+
+### Requirement: Reference-aligned SCUM projection workspaces
+The system SHALL present SCUM users, squads, map points, and gifts as connected operator workspaces backed by platform projections and typed workflows.
+
+#### Scenario: Operator filters users by squad
+- **WHEN** an operator searches or selects a squad in the SCUM users workspace
+- **THEN** the page filters real local player projections by the selected name, Steam identifier, or squad without querying `SCUM.db` from the browser
+
+#### Scenario: Operator inspects a squad
+- **WHEN** an operator selects a squad
+- **THEN** the page shows its observed members, leader markers, and related flag observations without fabricating missing values
+
+### Requirement: Plugin-declared SCUM map geometry
+The system SHALL use SCUM plugin package geometry to project current map-point overlays.
+
+#### Scenario: Operator changes map layers
+- **WHEN** an operator enables or disables players, vehicles, bases, or flags
+- **THEN** the map renders only the selected real projection classes using the installed plugin's declared coordinate frame
+
+### Requirement: Distinct observed and operational gifts
+The system SHALL keep observed SCUM timed-gift completion events separate from platform-owned gift definitions and grant state.
+
+#### Scenario: Operator opens gifts
+- **WHEN** an operator opens SCUM gift management
+- **THEN** the workspace distinguishes platform gift definitions and grants from completed in-game timed-gift observations
+
+### Requirement: Versioned plugin game data
+The system SHALL resolve SCUM gift item definitions from versioned plugin package data.
+
+#### Scenario: SCUM version changes
+- **WHEN** the server uses a plugin package with a different declared SCUM item catalog
+- **THEN** gift validation uses that plugin package data without changing platform source code

openspec/changes/align-scum-operations-with-reference-tools/tasks.md

@@ -0,0 +1,12 @@
+## 1. Reference-Aligned SCUM Operations
+
+- [x] 1.1 Positive prompt: Deliver practical SCUM user, squad, map, and gift operations shaped by the mature reference tools while retaining the current plugin/platform/Run ownership model.
+- [x] 1.2 Directional prompt: Update `platform/`, `platform_web/`, and the SCUM plugin package using existing projection, gift, manifest, and themed-console patterns; verify backend, frontend, plugin, structure, and OpenSpec checks.
+- [x] 1.3 Boundary prompt: Do not reintroduce direct SQLite/FTP/browser SQL access, raw RCON, host paths, copied map tiles, unrelated product areas, or a `run/` tree.
+- [x] 1.4 Separate observed timed-gift completion events from platform gift catalog/revision/grant records.
+- [x] 1.5 Resolve SCUM gift item definitions and map geometry from the versioned installed plugin package.
+- [x] 1.6 Implement searchable player and squad-filtered user projections plus roster/flag-aware squad detail.
+- [x] 1.7 Implement layered projection map with plugin-declared coordinate conversion and marker inspection.
+- [x] 1.8 Implement a gift workspace that clearly separates definitions/grants from observed completed timed-gift events.
+- [x] 1.9 Add focused tests and run the required validation suite.
+- [x] 1.10 Stage only task files, commit on `main`, and push the configured remote after verification succeeds.