P2E Codex

Pathfinder Experience App Technical Runbook

3 min read

Pathfinder Experience App (PXA) — Technical Runbook

1. Scope

This runbook documents operational procedures for the Pathfinder Experience App pipeline:

  • Discord ingest
  • Canonical vault updates
  • Portrait sync
  • Quartz publish
  • Pathfinder Buddy behavior baseline
  • Reaction feedback capture

Primary source vault:

  • /srv/docs/homelab-vault/pathfinder

Publish staging:

  • /srv/docs/homelab-vault/pathfinder-publish

Quartz runtime repo:

  • /home/zack/pathfinder-quartz

2. Daily Operating Flow

Step A — Refresh campaign corpus

Command:

  • /home/zack/.openclaw/workspace/scripts/discord-export/run_pipeline.sh

Core script:

  • game_night_refresh.sh

Expected outputs:

  • Updated timeline/denizens exports
  • Updated session recap docs
  • NPC intake sync updates
  • Rules index refresh
  • 99_P2E_Workshop/Game_Night_Readiness.md

Step B — Sync portraits (if new media landed)

Primary script:

  • /home/zack/.openclaw/workspace/scripts/discord-export/sync_npc_portraits.py

Pass-2 helper (inbox stubs + broad mapping):

  • /home/zack/.openclaw/workspace/scripts/discord-export/pass2_npc_portrait_inbox_sync.py

Expected behavior:

  • Pulls avatar files from _raw/aoa-denizens and _raw/aoa-timeline
  • Updates/copies portraits into NPC assets path
  • Inserts portrait embeds into mapped NPC docs

Step C — Publish

Command:

  • /home/zack/pathfinder-quartz/scripts/quartz/publish_and_push.sh

Expected behavior:

  • Export → validate → deploy → build → git push
  • content/index.md regenerated dynamically each run

3. Publish Mapping & IA Rules

Configured remaps (staging-level):

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

Why:

  • Preserve canonical source structure in vault.
  • Expose clean player-facing structure in public site.

Critical file:

  • /home/zack/pathfinder-quartz/scripts/quartz/export_publish_set.sh

NPC pages

Assets:

  • 01_Campaigns/Age of Ashes/02_NPCs/_assets/portraits/

Embed (inside NPC markdown):

  • ![](../_assets/portraits/<Name>.webp)

Character sheets

Assets:

  • 02_Characters/_assets/portraits/

Embed (inside 00_Character_Sheet.md):

  • ![](../_assets/portraits/<Name>.webp)

Common failure:

  • ./_assets/... used instead of ../_assets/... for nested pages.

5. Home Page Freshness

Generator:

  • /home/zack/pathfinder-quartz/scripts/quartz/generate_home_index.py

Invoked by:

  • /home/zack/pathfinder-quartz/scripts/quartz/deploy_publish_set.sh

Behavior:

  • Builds content/index.md from current publish content.
  • Uses template fallback only if generator fails.

Operator check after publish:

  • Confirm Home includes latest sessions + current-arc NPC snapshot.

6. Pathfinder Buddy Baseline

Agent:

  • pathfinder-buddy (Discord-routed)

Workspace:

  • /home/zack/.openclaw/workspace-p2ebuddy

Vault mount/symlink:

  • /home/zack/.openclaw/workspace-p2ebuddy/pathfinder → /srv/docs/homelab-vault/pathfinder

Behavior expectations:

  • Reads canonical character sheets directly for build/spell queries.
  • Avoids asking for manual path/command approval for known in-vault reads.
  • Uses spoiler-safe campaign grounded responses.

7. Reaction Feedback Loop (👍/👎)

Hook:

  • reaction-feedback
  • Path: /home/zack/.openclaw/workspace/hooks/reaction-feedback/
  • Event: message:received

Outputs:

  • /home/zack/.openclaw/workspace/memory/reaction-feedback.jsonl
  • /home/zack/.openclaw/workspace/memory/reaction-feedback-summary.md

Current semantics:

  • 👍 → positive
  • 👎 → negative

Purpose:

  • Behavioral reinforcement telemetry for prompt/rule tuning (not model weight training).

8. Verification Checklist (Post-Publish)

  1. Site loads (https://p2e.zgod.io).
  2. Home reflects current arc/session context.
  3. One PC sheet portrait renders.
  4. One ally/contact portrait renders.
  5. One current-arc baddie portrait renders.
  6. No obvious broken internal links in Home quick links.
  7. Publish commit exists and pushed.

9. Recovery Playbook

A) Missing portraits on live pages

  • Check markdown embed path (../_assets/portraits/...).
  • Check assets exported to content/.../_assets/portraits.
  • Re-run publish.

B) New NPC avatars not appearing

  • Ensure sync script includes both denizens + timeline raw sources.
  • Re-run sync_npc_portraits.py.
  • Re-run publish.

C) Home stale after refresh

  • Confirm generator script ran in deploy step.
  • Validate generated content/index.md contents.
  • Re-run publish.

D) Buddy giving generic/non-grounded answers

  • Confirm buddy workspace path mount exists.
  • Confirm agent instruction file still enforces direct sheet reads.
  • Restart gateway if config/agent instructions changed.

10. Planned Hardening

  1. Add automated broken-link/image gate in publish pipeline.
  2. Add periodic “feedback → prompt patch suggestions” job.
  3. Add “safe-to-promote NPC inbox” auto-review + promote workflow.
  4. Add operator-facing dashboard/summary for one-click health review.

Recent Notes