[Foundry] "Push update" for already-linked NPCs #156

New issue

Open

opened 2026-07-15 22:04:10 +00:00 by claude-bot · 0 comments

claude-bot commented

2026-07-15 22:04:10 +00:00

Contributor

Motivation/Context

Once an NPC has been pushed once (directory or live scene), GMs will regenerate stats or backstory (#130) and want to push the update to the already-linked Foundry actor rather than create a duplicate. The live-push investigation (2026-07-15) flags this as an explicit open question (§6.8): "when a GM regenerates a stat block after pushing, does 'Send' update the live actor mid-combat?" — with a proposed v1 answer of yes, with explicit confirmation, touching only Quest Board-owned fields.

Approach

When foundry_links (#146) already has a link for the entry being pushed, "Send to Foundry" becomes "Push update": re-push overwrites only Quest Board-owned fields on the linked actor — biography/backstory text, stat rows mapped by #148, and token image (#150) — and explicitly never touches fields Quest Board doesn't own, such as current HP-in-combat or other GM edits made directly in Foundry. This is a deliberate v1 simplification (create-once + explicit overwrite-with-confirmation) rather than a three-way merge, per the investigation's §4.3 update-semantics guidance.

Require an explicit confirmation dialog before overwriting an already-linked actor (per the open question in §6.8 — ship the "yes, with confirm" answer as v1, subject to playtesting feedback).

Add a stale-push indicator: using foundry_links.last_pushed_at / last_push_hash (#146), surface in the UI (WikiArticle/CampaignPlanning, extending #154) when the source LoreEntry has changed since the last push, so the GM knows a push is out of date without needing to remember.

Dependencies

Hard dependency: #146 (foundry_links) — this issue is the update-semantics consumer of that table's link data and hash tracking.
Hard dependency: #148 (structured stat mapping) — "Quest Board-owned fields" for update purposes are exactly the fields #148 maps.
Hard dependency: #152 ("Send to live scene") and its directory-push counterpart (#9) — this issue modifies both push targets' behavior when a link already exists.
Extends #154's UI (button label/state and stale-push indicator).

Out of scope

True three-way merge or field-level diffing against manual Foundry edits — explicitly rejected for v1 per the investigation.
Automatic/silent updates without confirmation.
Any change to the create path when no link exists yet (unchanged, covered by #9/#152).

Acceptance criteria

Re-pushing an already-linked NPC updates the existing Foundry actor (bio, stats, token image) rather than creating a duplicate.
HP-in-combat and other non-Quest-Board-owned actor fields are never overwritten by a push update.
GM sees an explicit confirmation before an update overwrites the linked actor.
UI shows a stale-push indicator when the LoreEntry has changed since last_pushed_at.
Verified against the real Foundry test instance: pushing twice updates in place; a manual HP change in Foundry survives a subsequent Quest Board push.

## Motivation/Context Once an NPC has been pushed once (directory or live scene), GMs will regenerate stats or backstory (#130) and want to push the update to the already-linked Foundry actor rather than create a duplicate. The live-push investigation (2026-07-15) flags this as an explicit open question (§6.8): "when a GM regenerates a stat block after pushing, does 'Send' update the live actor mid-combat?" — with a proposed v1 answer of yes, with explicit confirmation, touching only Quest Board-owned fields. ## Approach When `foundry_links` (#146) already has a link for the entry being pushed, "Send to Foundry" becomes "Push update": re-push overwrites only Quest Board-owned fields on the linked actor — biography/backstory text, stat rows mapped by #148, and token image (#150) — and explicitly never touches fields Quest Board doesn't own, such as current HP-in-combat or other GM edits made directly in Foundry. This is a deliberate v1 simplification (create-once + explicit overwrite-with-confirmation) rather than a three-way merge, per the investigation's §4.3 update-semantics guidance. Require an explicit confirmation dialog before overwriting an already-linked actor (per the open question in §6.8 — ship the "yes, with confirm" answer as v1, subject to playtesting feedback). Add a **stale-push indicator**: using `foundry_links.last_pushed_at` / `last_push_hash` (#146), surface in the UI (WikiArticle/CampaignPlanning, extending #154) when the source `LoreEntry` has changed since the last push, so the GM knows a push is out of date without needing to remember. ## Dependencies - Hard dependency: #146 (`foundry_links`) — this issue is the update-semantics consumer of that table's link data and hash tracking. - Hard dependency: #148 (structured stat mapping) — "Quest Board-owned fields" for update purposes are exactly the fields #148 maps. - Hard dependency: #152 ("Send to live scene") and its directory-push counterpart (#9) — this issue modifies both push targets' behavior when a link already exists. - Extends #154's UI (button label/state and stale-push indicator). ## Out of scope - True three-way merge or field-level diffing against manual Foundry edits — explicitly rejected for v1 per the investigation. - Automatic/silent updates without confirmation. - Any change to the create path when no link exists yet (unchanged, covered by #9/#152). ## Acceptance criteria - Re-pushing an already-linked NPC updates the existing Foundry actor (bio, stats, token image) rather than creating a duplicate. - HP-in-combat and other non-Quest-Board-owned actor fields are never overwritten by a push update. - GM sees an explicit confirmation before an update overwrites the linked actor. - UI shows a stale-push indicator when the `LoreEntry` has changed since `last_pushed_at`. - Verified against the real Foundry test instance: pushing twice updates in place; a manual HP change in Foundry survives a subsequent Quest Board push.

claude-bot added this to the v5.2.0 - FoundryVTT Phase 2.5: Live Scene Push milestone

2026-07-15 22:04:14 +00:00

claude-bot added the

backend

enhancement

frontend

labels

2026-07-15 22:04:14 +00:00

claude-bot referenced this issue

2026-07-15 22:04:26 +00:00

[Foundry] Link pushed actors to journal backstory #157