PolyhydraGames.Rpg.Contracts 1.0.0.4

Questy Player for PF1e

Questy Player for PF1e is the player-facing Pathfinder 1e assistant in the Questy RPG application family. It supports character management, spell lookup, loot rolling, encounter helpers, and table-side play utilities.

The repository and technical identifiers remain rpg-pf-assistant and PFAssistant until a future technical rename slice explicitly changes projects, namespaces, deployments, public hosts, or routes.

The active public beta target is the Blazor web app at:

• https://pfa.polyhydragames.com
• Health check: https://pfa.polyhydragames.com/health
• Readiness check: https://pfa.polyhydragames.com/ready

Tags

• rpg
• rpg-pf-assistant
• tabletop
• auth
• docs
• dotnet

Related Repos

• rpg-gm-tools
• rpg-book-extractor
• pathfinder1e-flatfiles
• Pathfinder-2E-SRD-Markdown-Companion
• rpg-PathfinderLoot
• rpg-PathfinderGrimoire
• rpg-StarFinder
• rpg-PFCraft
• rpg-combat-manager
• rpg-combat-manager.apis
• rpg-d20

Public Beta Scope

The beta is focused on the player-facing PF1e workflow:

• Create, select, and open saved characters.
• Edit a character through the Blazor /editor/{id} surface backed by the core Character model.
• Review stats, equipment, selections, notes, and play-loop summaries.
• Search PF1e spells in the Grimoire and inspect mechanics fields.
• Roll loot and random encounters from the browser.
• Adjust local app options for the current play session.

Known rough edges:

• The app is web-first for this beta; mobile app-store packaging is not part of this pass.
• Cloud sync and offline-first support remain future roadmap work.
• GM companion integration remains outside this repository's current beta scope.
• Some deeper PF1e data recovery and condition/status normalization work is still tracked in the backlog.
• Once the MAUI version is ready for beta, the next release goal is to deploy it through Firebase.

Active Solution Surface

Primary contributor solution: PFAssistant.Active.slnx

Active projects:

• PFAssistant.Blazor - Blazor Server public beta surface for Questy Player for PF1e.
• PFAssistant.Core - shared application view models and services.
• PolyhydraGames.Pathfinder - PF1e domain model and rules.
• PFAssistant.Console - archived legacy CLI surface, kept for reference only.
• PFAssistant.MauiApp - companion/mobile target, validated separately with scripts/run-maui-validation.sh because it requires MAUI Android platform workloads.
• PolyhydraGames.Rpg.Contracts - the technical project behind Questy Rules Contracts.
• PolyhydraGames.Rpg.Postgres - the technical project behind Questy Rules Storage.

These Questy names are product-facing aliases only. Code, packages, database objects, configuration, and deployment automation continue to use the existing technical identifiers.

Legacy and archived shells remain in the repository for reference but are not the public beta target.

Prerequisites

• .NET SDK 10.0.103 or compatible .NET 10 SDK from global.json.
• Access to NuGet.org, the single package source defined in NuGet.Config. Repository restores do not require GitHub Packages credentials.
• Docker for container publish checks.
• Access to the r620 Swarm deployment environment for live deploys.

Current Pathfinder package baseline:

• PolyhydraGames.Pathfinder 3.2.0.12
• PolyhydraGames.Pathfinder.Dtos 3.0.1.35
• PolyhydraGames.Pathfinder.Rules 3.2.0.13
• PolyhydraGames.Pathfinder.RestAsync 3.0.1.34
• PolyhydraGames.Pathfinder.SQLite 3.0.2.34
• PolyhydraGames.Documents.Interfaces 1.0.0.39

Check the SDK:

dotnet --info

Build And Run

Restore once, then build the Blazor target:

dotnet restore PFAssistant.Blazor/PFAssistant.Blazor.csproj
dotnet build PFAssistant.Blazor/PFAssistant.Blazor.csproj --no-restore

Run locally:

dotnet run --project PFAssistant.Blazor/PFAssistant.Blazor.csproj

Run the responsive smoke harness:

scripts/run-blazor-responsive-smoke.sh

Run the repo-local active-surface coverage command:

./scripts/coverage.sh

Run the optional live HTTP smoke:

PATHFINDER_LIVE_BASE_URL=https://pfa.polyhydragames.com scripts/run-pathfinder-http-smoke.sh
PATHFINDER_LIVE_BASE_URL=https://pfa.polyhydragames.com PATHFINDER_LIVE_BEARER_TOKEN=... scripts/run-pathfinder-http-smoke.sh
PFA_ASSISTANT_SMOKE_BASE_URL=http://localhost:5165 \
PFA_ASSISTANT_LOGIN_ENV=~/.config/secrets/keycloak-login.env \
  scripts/run-pathfinder-authenticated-smoke.sh

Run the local full-stack authenticated smoke, including a managed local Api.Pathfinder rule API backed by the RPG Postgres app env:

scripts/run-pathfinder-local-authenticated-smoke.sh

The local wrapper defaults to deterministic smoke auth so it does not depend on the external OIDC provider. Set PFA_ASSISTANT_SMOKE_LOCAL_AUTH=false and pass PFA_ASSISTANT_LOGIN_ENV when the real login flow is the target.

The authenticated smoke signs in through OIDC, verifies the shell and protected routes, checks the document/navigation pages, creates a disposable character through the UI, verifies editor routes target the created character ID, exercises catalogue row and detail-card select/menu/report alert/Continue Play/Open Editor actions, exercises editor buttons, tabs, Selections menu actions, Skill Points choice visibility, the Open Skills add-skill flow, and Play class-action surface handling plus deterministic classed fixtures: Barbarian Class Skills, Add Archetype, Begin Rage, and End Rage, and Paladin Class Skills, Lay On Hands, Channel Energy, and Smite Evil, and Wizard Set Arcane School, Set Arcane Bond, and Set Familiar, Notes add/reload/API-payload/remove behavior, browses conditions and Main Book skill details, searches Grimoire spell details, clicks table-side tool buttons, verifies Combat launch-context controls and Crafting tabs, adds a Party member through the picker, opens that member's DPR menu path, and verifies the character API create/delete lifecycle. The classed paths also guard the REST class feature, class skill, archetype-name, and class feat calls needed to load and operate a playable character.

Docker And Swarm

Use the guarded production deploy path when changing the live service:

DRY_RUN=1 scripts/deploy-production-guarded.sh
LOAD_REMOTE=1 RPG_PF_DOCKER_SSH=1 scripts/deploy-production-guarded.sh

The guarded script builds the Blazor app, runs responsive smoke, builds the Docker image, optionally pushes or loads the image to r620, deploys the Swarm stack, waits for convergence, checks health/readiness, runs live HTTP smoke, and checks recent Docker/Seq diagnostics. It prints the rollback command when a gate fails.

The Portainer/Infisical restore contract for this stack is documented in docs/vault/portainer-infisical-restore.md.

Build the public beta image locally without pushing:

PUSH_IMAGE=0 ./pub.sh latest

Push and deploy are opt-in:

PUSH_IMAGE=1 ./pub.sh latest
DEPLOY_STACK=1 ./pub.sh latest

The publish helper also loads optional local secrets from ~/.config/secrets/ghcr.env and ~/.config/secrets/polyhydra.env before pushing to GHCR.

The canonical public host is pfa.polyhydragames.com. Older pf1 / pf2 hostnames should be treated only as aliases when Traefik and DNS already support them.

Public Routes

Stable beta routes:

• /
• /how-to-use
• /characters
• /editor/{id}
• /grimoire
• /loot
• /encounters
• /options
• /questy-table
• /health
• /ready

Questy Table Authority Boundary

GameMasterToolsWeb is the sole durable authority for Questy table sessions, rosters, encounters, targets, pending actions, confirmations, and hit-point state. This application does not register a process-local table authority and does not expose /api/v1/table-sessions or /api/v1/table-actions in production. The /questy-table player surface uses the authenticated GameMasterToolsWeb client and the shared PolyhydraGames.Rpg.Contracts.TableLoop wire contract. PFA verifies the selected character belongs to the signed-in player and resolves only attacks derived from that character's equipped saved state. A confidential service credential submits the signed resolution to GMT, where it remains pending until the GM confirms or rejects it.

Documentation

• Docs Home
• Engineering Principles
• Test Strategy
• Feature Index
• Blazor Feature Notes
• Production Readiness
• PF1e Production Readiness Runbook
• Backlog
• Phase 0 Execution Board
• Product Vision
• Questy Technical Rename Roadmap

License

Private - Polyhydra Games.