P2E Codex

Pathfinder Experience App System Wireframe

4 min read

Pathfinder Experience App (PXA) — System Wireframe

1) Product Intent

Build a player-facing Pathfinder experience that stays current and relevant every time someone opens it.

Success criteria:

  • Latest timeline/session/NPC changes are reflected automatically.
  • Home page reflects current arc and current priorities (not stale history dumps).
  • Portraits (PC + NPC) render reliably in published Quartz.
  • Pathfinder Buddy gives table-useful answers from canonical docs.
  • User reactions (👍/👎) become structured behavioral feedback.

2) High-Level System Map

Discord (timeline / denizens / media)
  -> Export + transform pipeline
  -> Canonical Pathfinder vault updates
       - Sessions
       - NPC cards + portraits
       - Character sheets + portraits
       - Rules/quickref refresh
  -> Publish staging (pathfinder-publish remaps)
  -> Quartz build + push
  -> p2e.zgod.io
 
Discord mentions
  -> pathfinder-buddy agent
  -> Reads canonical vault content
  -> Responds spoiler-safe + campaign-aware
 
Discord reactions (👍/👎 on bot replies)
  -> reaction-feedback hook
  -> JSONL + summary
  -> future prompt/rule tuning cycle

3) Content Architecture (Current)

Source of truth

  • Canonical write source: /srv/docs/homelab-vault/pathfinder
  • Publish staging: /srv/docs/homelab-vault/pathfinder-publish
  • Quartz repo/runtime: /home/zack/pathfinder-quartz

Publish IA mapping (active)

  • 01_Campaigns/Age of Ashes/01_Sessions → 01_Sessions
  • 01_Campaigns/Age of Ashes/02_NPCs → 03_NPCs
  • 01_Campaigns removed from publish output.

Portrait conventions

  • NPC portraits: 01_Campaigns/Age of Ashes/02_NPCs/_assets/portraits/
  • PC portraits: 02_Characters/_assets/portraits/
  • NPC embed path convention: ![](../_assets/portraits/<Name>.webp)
  • Character sheet embed path convention: ![](../_assets/portraits/<Name>.webp)

4) Automation Pipelines

A) Game-night refresh pipeline

Entry points:

  • scripts/discord-export/run_pipeline.sh
  • scripts/discord-export/game_night_refresh.sh

Includes:

  • Discord export/transform
  • Session docs refresh (RECAP/CATCHUP)
  • NPC intake sync
  • Rules index rebuild
  • Party quickref refresh
  • Readiness report generation

B) NPC portrait sync pipeline

Scripts:

  • scripts/discord-export/sync_npc_portraits.py
  • scripts/discord-export/pass2_npc_portrait_inbox_sync.py

Current behavior:

  • Pull avatar attachments from both _raw/aoa-denizens and _raw/aoa-timeline
  • Map to canonical NPC cards when possible
  • Create inbox stubs for unmatched names
  • Copy portraits + insert/update portrait embeds

C) Quartz publish pipeline

Primary command:

  • scripts/quartz/publish_and_push.sh

Flow:

  1. export_publish_set.sh (allowlist export + remaps + 01_Campaigns removal)
  2. validate_publish_set.sh
  3. deploy_publish_set.sh (sync to content + generate home)
  4. Quartz build
  5. Git commit + push

D) Home freshness automation

  • Dynamic home generator: scripts/quartz/generate_home_index.py
  • On every publish, index.md is generated from current content.
  • Static template remains fallback only.

5) Pathfinder Buddy Runtime Design

Agent:

  • pathfinder-buddy
  • Discord-routed, mention-triggered

Key hardening applied:

  • Workspace-mounted vault path available in buddy workspace.
  • Instructions updated to read canonical character sheets directly for character questions.
  • Removed “ask for command approval” behavior for known in-vault reads.

Desired answer quality:

  • Spoiler-safe
  • In-game chronology weighted
  • Character-sheet grounded for build/spell decisions
  • No unnecessary friction in table-time Q&A

6) Reinforcement Loop (👍 / 👎)

Hook installed:

  • reaction-feedback (workspace hook)
  • Event: message:received

Current output:

  • memory/reaction-feedback.jsonl
  • memory/reaction-feedback-summary.md

Semantics:

  • 👍 ⇒ positive signal
  • 👎 ⇒ negative signal

Next step (planned):

  • periodic rule/prompt patch candidates generated from negative clusters.

7) Operations Runbook (Lite)

Daily / per update cycle:

  1. Run refresh pipeline.
  2. Run portrait sync if new media arrived.
  3. Publish and verify site.
  4. Spot-check key pages (Home, latest session, current-arc NPC, one character sheet).
  5. Review feedback summary for behavior drift.

Failure modes to watch:

  • Broken relative image links
  • Missing image export due to filtering rules
  • Stale Home index
  • Buddy falling back to generic rules answers instead of sheet-grounded answers

Recovery posture:

  • Keep changes script-first and idempotent.
  • Prefer remap at publish staging; keep source vault canonical.

8) Near-Term Roadmap

v1.1

  • Auto-propose prompt/rule updates from 👎 logs.
  • Promote safe inbox NPCs to canonical buckets.
  • Add automated broken-link/image check in publish pipeline.

v1.2

  • Add “current threats” widget to generated Home.
  • Add per-page “last refreshed from timeline” stamp.

v2

  • Unified “Pathfinder Experience App” control panel for:
    • refresh,
    • publish,
    • quality checks,
    • feedback review,
    • one-click safe remediation.

9) Definition of Done (Always Relevant)

The system is “always relevant” when:

  • Home reflects current arc and latest actionable context.
  • New timeline/denizen changes flow through on next publish.
  • Portraits for active PCs/NPCs render consistently.
  • Buddy answers directly from current campaign corpus.
  • Feedback signals are captured and fed into behavior improvement.

Recent Notes