settled-reach/docs/sprints/sprint-3/server.md

Sprint 3: Content Foundation — Server Tasks

Goal: Build the content infrastructure for v0.1 — directory structure, schema validation, and interaction mechanics.

Branch: server Agents: Dudley (simulation), Tyre (architecture), Hoshe (QA)

Tickets

#	Title	Priority	Blocked by
#385	Create content/ directory skeleton	high	#384
#386	Content schema definitions (YAML Schema files)	high	#384
#392	Implement make validate-content CLI	high	#386
#404	Proximity detection + multi-verb InteractionOptions (verbs[])	high	—
#406	Pause system — server tick rate scaling	medium	—

Use db/connectors/ticket show <id> for full details.

Key Decisions

• decisions/architecture.md — D-020 (IPC protocol), D-026 (simulation tiers), D-030 (testability)
• decisions/content.md — D-024 (10-axis NPC model), D-035 (dialogue tag taxonomy)
• Content scoping: v0.1 Content Scoping Workshop outputs (parent epic #369)

Notes

Content infrastructure (#385, #386, #392):

These three tickets form a pipeline: directory structure → schema definitions → validation tooling.

• #385 (Directory skeleton): Create the converged content/ directory structure from workshop outputs. Canonical layout: _meta/, _schema/ (infrastructure, underscore prefix), global/ (factions, technology, contraband, knowledge, enums, regions), districts/sova-transit/ (district.yaml, npcs/, locations/, templates/, triangles/, lines/). Empty YAML stubs for all major files. This establishes the physical structure that all content authoring depends on. Blocked by #384 (design doc, copy team).
• #386 (Schema files): Write YAML Schema validation files in _schema/: npc.schema.yaml (with tier-conditional rules — Tier 1 vs Tier 2 NPC requirements differ), location.schema.yaml, faction.schema.yaml, template.schema.yaml, fact.schema.yaml, dialogue.schema.yaml, monologue.schema.yaml, district.schema.yaml, pool.schema.yaml. These define the contract for all content files. Blocked by #384 (design doc).
• #392 (Validation CLI): Implement make validate-content CLI tool. Reads _schema/ definitions, validates all YAML in content/. v0.1 scope: structural validation (required fields, type checks, enum matching) + tier-conditional rules (Tier 1 NPCs need 50-70 lines, Tier 2 need 10-axis profiles). v0.2 scope (future): cross-reference validation (FactId existence checks, NPC slug resolution). This is the same crate as C3 schemas. Blocked by #386 (schemas must exist first).

These tickets lay the foundation for all content work. Without them, content authors write into the void with no validation feedback.

Interaction mechanics (#404):

• #404 (Proximity + InteractionOptions): Two deliverables: (1) proximity detection system (determines when player is close enough to interact with an entity), (2) server-side InteractionOptions component modeling N available actions per entity via verbs[] array. Without proximity, InteractionOptions has no trigger. v0.1 client behavior: pick first/best verb automatically. v0.2 client behavior: show context menu with all available verbs. Architecture requirement: This must not be throwaway work — the system must support the v0.2 multi-verb menu natively from day one. Includes ObserverSnapshot v2 → v3 protocol extension to send interaction data to client. See ticket #402 (copy team) for verb taxonomy (Move, Look, Monologue, Examine Object, Examine NPC, Talk, Overhear). Blocks #405 (client interaction prompt, client team).
• Files: server/src/simulation/interaction.rs (new module), server/src/bridge/types.rs (ObserverSnapshot v3 extension)
• Integration: Works with existing proximity/spatial queries. The observation system already tracks entity visibility — this extends it to track interaction range (closer threshold than LOS).

Pause system (#406):

• #406 (Tick rate scaling): Three tick rate states: (1) full speed (normal gameplay), (2) 50% speed (UI overlay open — knowledge panel, dialogue tree — player is reading), (3) 0% (spacebar pause). Server receives pause/speed commands from client via IPC. Medium priority — nice-to-have for v0.1 but not critical path. Improves player experience when reading dialogue or checking knowledge graph.
• Files: server/src/simulation/time.rs (extend existing SimulationTime with speed scaling)

Dependency Chain

#384 (design doc, copy) → #385 (directory skeleton) → content authoring
                       → #386 (schemas) → #392 (validation CLI) → content authoring

#404 (proximity + verbs[]) → #405 (interaction prompt, client)

#406 (pause) → standalone

Critical path: #384 → #385 → #386 → #392. All content work is blocked until these complete.

Parallel work: #404 and #406 are independent and can start immediately.

PR Workflow

When ready to submit, create a PR with tea CLI. All flags are required to avoid TTY prompts (see CLAUDE.md "Gitea access" section):

tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "feat(simulation): description" --description "body" --base main --head server