modwright 0.1.0

package/knowledge/baldursgate3/journal.quests.yaml

@@ -0,0 +1,214 @@
+game: baldursgate3
+topic: journal.quests
+title: Journal structure, quest state DBs, and Osiris quest calls
+facts:
+  - id: bg3.journal.quests.questupdate-requires-parent-quest-id
+    claim: "\"QuestUpdate always requires the parent quest ID to give out updates, even when updating a
+      subquest\" — so QuestUpdate((CHARACTER)_Player, (STRING)_QuestID, (STRING)_EntryID) takes the
+      top-level quest's ID in _QuestID and the subquest's entry in _EntryID, never the subquest's
+      own ID in _QuestID."
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Journal:_Osiris_Calls §Functions > QuestUpdate
+    tags:
+      - journal
+      - questupdate
+      - subquest
+      - silent-failure
+  - id: bg3.journal.quests.questupdate-does-not-emit-a-journal-entry-by-itself
+    claim: '"The QuestUpdate call will also respect the quest step property to add or close the quest
+      for you", but "Adding or Closing a quest does not automatically give you a journal update...
+      You will always want to provide a quest update after adding or before closing a quest."'
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Journal:_Osiris_Calls §Functions > QuestUpdate
+    tags:
+      - journal
+      - questupdate
+      - quest-state
+      - gotcha
+  - id: bg3.journal.quests.questupdate-two-arg-overload-implicit-player
+    claim: QuestUpdate has a two-argument overload, QuestUpdate((STRING)_QuestID, (STRING)_EntryID),
+      that omits the player parameter "since the quest is shared, everybody should get the update
+      anyway"; it "Overloads the engine call" (the three-argument version).
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Journal:_Osiris_Calls §Functions > QuestUpdate
+    tags:
+      - journal
+      - questupdate
+      - overload
+  - id: bg3.journal.quests.questadd-questclose-should-be-avoided
+    claim: "QuestAdd and QuestClose exist for manually unlocking/closing a quest, but the documentation
+      recommends against both: \"It's better to avoid starting quests with this call and instead
+      rely on QuestUpdate\" and \"It's better to avoid closing quests with this call and instead
+      rely on QuestUpdate.\""
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Journal:_Osiris_Calls §Functions > QuestAdd, >
+      QuestClose
+    tags:
+      - journal
+      - questadd
+      - questclose
+      - best-practice
+  - id: bg3.journal.quests.questupdateunlocked-reports-top-level-quest-id
+    claim: The QuestUpdateUnlocked event always receives the top-level parent quest as its _QuestID
+      parameter, even when the update that was unlocked belongs to a subquest;
+      SubQuestUpdateUnlocked is the separate event that fires specifically for subquest updates and
+      receives the subquest ID instead.
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Journal:_Osiris_Calls §Events > QuestUpdateUnlocked,
+      > SubQuestUpdateUnlocked
+    tags:
+      - journal
+      - events
+      - subquest
+      - questupdateunlocked
+  - id: bg3.journal.quests.questisclosed-false-until-explicitly-closed
+    claim: The QuestIsClosed query "always returns false if the quest has not yet been explicitly
+      closed, even while it has not yet been accepted/added/opened/unlocked" — it does not
+      distinguish "not yet started" from "not yet closed."
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Journal:_Osiris_Calls §Queries > QuestIsClosed
+    tags:
+      - journal
+      - questisclosed
+      - query
+      - gotcha
+    detail: "Separate caution for Script Extender work: this is the in-story Osiris query. Reading
+      Osiris queries through SE's Osi bridge is separately unreliable in the build recorded here —
+      see bg3.se.osi-queries-broken-actions-work (verified: Osi actions work, Osi queries return
+      junk)."
+  - id: bg3.journal.quests.db-questdef-state-reacts-to-flag
+    claim: "DB_QuestDef_State(_Flag, _Quest, _Update) is a declarative database: defining it unlocks
+      _Update in _Quest as soon as _Flag is set. If _Flag is global, the update unlocks for every
+      player; otherwise it unlocks only for the specific character the flag was set on."
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Journal:_DB_Helpers §Declarative Databases ("When
+      _Flag is set, unlock _Update in _Quest")
+    tags:
+      - journal
+      - db-questdef-state
+      - declarative-database
+      - flags
+  - id: bg3.journal.quests.db-questdef-chainedstate-links-entries
+    claim: DB_QuestDef_ChainedState(_Quest, _Step, _NewStep) declares that unlocking _Step in _Quest
+      automatically unlocks _NewStep in the same quest; a 4-parameter overload,
+      DB_QuestDef_ChainedState(_Quest, _Step, _NewQuest, _NewStep), links a step in one quest to a
+      step in a different quest.
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Journal:_DB_Helpers §Linking Quest Entries ("When
+      _Step in _Quest is unlocked, so is _NewStep [in _NewQuest]")
+    tags:
+      - journal
+      - db-questdef-chainedstate
+      - declarative-database
+  - id: bg3.journal.quests.db-questdef-conditionalstate-defined-multiple-times
+    claim: DB_QuestDef_ConditionalState (in its 5/6/7-parameter forms) works like
+      DB_QuestDef_ChainedState but can be defined multiple times for the same unlock, letting an
+      entry unlock conditionally on different combinations of a separate step's boolean state.
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Journal:_DB_Helpers §Entries Conditional to Other
+      Entries ("Similar to DB_QuestDef_ChainedState, but they can be defined multiple times")
+    tags:
+      - journal
+      - db-questdef-conditionalstate
+      - declarative-database
+  - id: bg3.journal.quests.qry-questdef-blockquestupdate-is-the-exception-hook
+    claim: QRY_QuestDef_BlockQuestUpdate((CHARACTER)_Player, (STRING)_Quest, (STRING)_Update) is checked
+      by every declarative database rule before it calls QuestUpdate; defining this query to return
+      false for a specific player/quest/update combination is the documented way to carve out a
+      last-minute exception to an otherwise-automatic quest-state rule.
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Journal:_DB_Helpers §Adding Exceptions to Declarative
+      Database Rules ("Every declarative database rule will also check if this QRY returns false
+      before calling the QuestUpdate")
+    tags:
+      - journal
+      - qry-questdef-blockquestupdate
+      - exception
+  - id: bg3.journal.quests.db-questdef-companionleft-reason-steps
+    claim: "DB_QuestDef_State_CompanionLeft((TAG)_CompanionTag, (STRING)_Quest, (STRING)_Reason) links a
+      companion's REALLY_ORIGIN tag to that companion's journal quest and to a _Reason, which is \"a
+      quest step defined in the journal; it explains the reason for the companion leaving\". Three
+      _Reason steps \"are generic and should be defined in any companion's journal\":
+      CompanionLowRelation, CompanionMurdered, CompanionHostile."
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Journal:_DB_Helpers §Companions ("_CompanionTag
+      refers to the REALLY_ORIGIN tag a companion has")
+    tags:
+      - journal
+      - companion
+      - db-questdef-companionleft
+      - tags
+    detail: PROC_Origins_CompanionLeavePermanently() is what writes the reason step, picking
+      CompanionLowRelation by default, CompanionMurder if GLO_Companion_Murder is set, or
+      CompanionHostile if GLO_Companion_Combat is set — so a custom companion missing those three
+      steps loses the default leave-reason updates.
+  - id: bg3.journal.quests.level-transition-dbs-close-on-point-of-no-return
+    claim: DB_QuestDef_LevelLoaded and DB_QuestDef_LevelUnloading fire (via PROC_LevelLoadedOnce /
+      PROC_LevelUnloading respectively) to give a quest update to all players on entering or leaving
+      a named level; their documented typical use is closing quest entries a player can no longer
+      complete once they progress past a region they can't return to.
+    status: community
+    source: 'docs.baldursgate3.game/index.php?title=Journal:_DB_Helpers §Leaving/Entering a Region
+      ("Typical use: For closing entries, when a quest must close when the player progresses to the
+      next region")'
+    tags:
+      - journal
+      - level-transition
+      - db-questdef-levelloaded
+  - id: bg3.journal.quests.party-shared-state-dbs-checked-not-defined
+    claim: DB_QuestIsAccepted(_QuestID), DB_QuestIsOpened(_QuestID), and DB_QuestIsClosed(_QuestID) are
+      set automatically by the engine and are meant to be checked, not defined by mod authors; all
+      three also apply to subquests, not only top-level quests.
+    status: community
+    source: docs.baldursgate3.game/index.php?title=Journal:_DB_Helpers §Party Shared Quest State ("These
+      DBs are set automatically and can be checked"; "Subquests are also added to the above DBs")
+    tags:
+      - journal
+      - party-shared-state
+      - database
+  - id: bg3.journal.quests.questupdate-helper-queries-signatures
+    claim: "Three generated helper queries exist alongside QuestUpdate: QuestUpdateExists(questID,
+      stateID), QuestUpdateGetTopLevel(questID, stateID), and QuestUpdateIsUnlocked(character,
+      quest, update) — the latter taking a character parameter the first two don't, confirming it is
+      the per-player unlock check rather than a global existence check."
+    status: verified
+    source: LaughingLeader/BG3ModdingTools@ab343b6 generated/Osi.lua:1988 (QuestUpdateExists), :1993
+      (QuestUpdateGetTopLevel), :1999 (QuestUpdateIsUnlocked)
+    detail: "Checked against the source (2026-09-08): `verified_on` removed — read from a generated stub
+      file that names no game version. Verified as declared signatures only; what the queries return
+      at runtime was not observed."
+    tags:
+      - journal
+      - questupdate
+      - signature
+      - osiris
+  - id: bg3.journal.quests.questupdaterevert-and-questcloseverted-exist
+    claim: Beyond QuestUpdate/QuestAdd/QuestClose, the generated stubs also declare
+      QuestUpdateRevert(character, questID, stateID) as a call and QuestCloseReverted(questID) as an
+      event. The existence of a revert call and a revert event is all the stub file shows; no source
+      read here documents what reverting does or when the event fires.
+    status: verified
+    source: LaughingLeader/BG3ModdingTools@ab343b6 generated/Osi.lua:3583 (QuestUpdateRevert);
+      generated/Osi.Events.lua:864 (QuestCloseReverted). Osi.Events.lua:875 also declares
+      QuestUpdateUnlockReverted(character, topLevelQuestID, stateID)
+    tags:
+      - journal
+      - questupdaterevert
+      - questclosereverted
+      - signature
+  - id: bg3.journal.quests.questupdatemessagecounter-adjusts-message-count
+    claim: Osi.QuestUpdateMessageCounter(messageId, deltaUpdateAmount) is a separate call from
+      QuestUpdate that adjusts a message/notification counter by a delta amount rather than
+      unlocking a journal entry — its existence in the generated stub file means a mod could
+      increment or decrement a quest-related counter without triggering a full QuestUpdate.
+    status: inferred
+    source: LaughingLeader/BG3ModdingTools@ab343b6 generated/Osi.lua:3576-3578
+    tags:
+      - journal
+      - questupdatemessagecounter
+      - signature
+    detail: Inferred from the function name and parameter names alone (messageId, deltaUpdateAmount) —
+      neither the community Journal:Osiris_Calls page nor any other source on disk documents this
+      call's semantics or when the engine invokes the corresponding
+      QuestUpdateUnlockReverted/QuestUpdateUnlocked events that appear alongside it in
+      Osi.Events.lua.

package/knowledge/baldursgate3/loadorder.modsettings.yaml

@@ -0,0 +1,128 @@
+game: baldursgate3
+topic: loadorder.modsettings
+title: Load order, modsettings.lsx, and dependency resolution
+facts:
+  - id: bg3.loadorder.external-guid-dependencies
+    claim: "Borrowing another mod's assets (a RootTemplate referencing a VisualTemplate /
+      EquipmentTypeID — or any resource GUID — defined in a different mod) creates a load-order
+      dependency: that mod must be enabled AND ordered before yours in modsettings.lsx. If it is
+      missing from the enabled list the game CTDs at LoadModule — no dangling-name error, and your
+      own reference-checker stays green because the name resolves fine inside your files."
+    status: verified
+    source: ModWright field verification
+    tags:
+      - load-order
+      - dependencies
+      - guids
+      - roottemplate
+    detail: "A class mod hit this while borrowing Whips Expanded / BetterWhips assets (VisualTemplate
+      1c66562c, EquipmentTypeID e9b4ae39): the mod must load AFTER BetterWhips or these refs won't
+      resolve. The crash looks like your own bug. Referencing a GUID is not the same as defining it
+      — both mods can reference a third."
+  - id: bg3.loadorder.modsettings-crash-guard
+    claim: BG3's crash-guard auto-disables a mod after repeated crashes (the in-game manager shows it
+      off even though modsettings still lists it; the save screen shows a "Mod Verification /
+      Missing or Disabled" checkbox). Every launch test after a crash streak must confirm the module
+      was actually ACTIVE, or the "it loads now" result is meaningless.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - load-order
+      - crash-guard
+      - auto-disable
+    detail: '"Half our bisect arms were confounded by this" during the 2026-08-31 launch-CTD marathon.'
+  - id: bg3.loadorder.modsettings-not-durable
+    claim: A hand-added modsettings.lsx entry is not durable — a mod-manager deploy (Vortex) rewrites
+      the file and silently drops it, so a previously-working setup starts crashing with no content
+      change on your side. The in-game mod manager also rewrites modsettings.lsx when the mod list
+      is edited and strips hand-inserted loose-mod entries.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - load-order
+      - modsettings
+      - vortex
+      - volatility
+    detail: 'Suspect this whenever a build that loaded fine starts CTDing after an unrelated repack.
+      Back the file up before editing; validate with [xml]$x = Get-Content ... -Raw afterwards. Grep
+      gotchas that cause false "not found" conclusions here: PowerShell Select-String -SimpleMatch
+      treats a|b as a literal string, and -Path treats [PAK]-style brackets as wildcards (use
+      -LiteralPath or [System.IO.File]::ReadAllText).'
+  - id: bg3.loadorder.dependency-diagnostic
+    claim: "To diagnose a load-order CTD: (1) tail bin\\network.*.log — LoadModule means module/asset
+      load, not a level transition (bin\\CrashDump*.dmp timestamps confirm the attempt). (2) Extract
+      the deployed pak and convert RootTemplates/_merged.lsf to lsx; grep VisualTemplate /
+      EquipmentTypeID values. (3) For each external GUID, extract the candidate provider pak and
+      confirm it DEFINES it (a VisualBank region _merged.lsf <attribute id=\"ID\" ...>, or
+      EquipmentTypes.lsx UUID). (4) Check the enabled list in %LOCALAPPDATA%\\Larian
+      Studios\\Baldur's Gate 3\\PlayerProfiles\\Public\\modsettings.lsx (order = top-to-bottom; the
+      dependency must come first)."
+    status: verified
+    source: ModWright field verification
+    tags:
+      - load-order
+      - dependencies
+      - diagnostic
+    detail: This is the standard dependency debugging workflow; the crash looks like a content bug until
+      you trace the GUID origins.
+  - id: bg3.loadorder.modmanager-skips-order-entries-with-no-local-mod-match
+    claim: "When BG3 Mod Manager builds its final dependency-resolved output list (BuildOutputList) from
+      a load order, an order entry whose UUID does not match any mod the manager has actually
+      indexed on disk is logged as \"[*ERROR*] Missing mod for mod in order: '<Name>'.\" and
+      excluded from the built list, rather than the build failing outright. BuildOutputList also
+      skips order entries already flagged Missing before it starts (`order.Where(x =>
+      !x.Missing)`)."
+    status: verified
+    source: LaughingLeader/BG3ModManager@fc35358 src/Core/Util/DivinityModDataLoader.cs:1431-1465
+      (BuildOutputList; the log line at :1462)
+    tags:
+      - load-order
+      - missing-mod
+      - bg3modmanager
+      - silent-omission
+    related:
+      - id: bg3.loadorder.modsettings-crash-guard
+        detail: "A different mechanism producing a similar symptom: here the mod manager itself quietly
+          drops an order entry it cannot resolve locally, distinct from the game's own crash-guard
+          auto-disabling a mod after a crash streak — both can make an \"enabled\" mod not actually
+          end up active."
+  - id: bg3.loadorder.modsettings-not-rewritten-by-a-plain-launch
+    claim: "Launching the game and loading a save does not by itself rewrite modsettings.lsx: the file
+      keeps its previous content and modification time across launches, and its ModuleShortDesc
+      Folder attribute therefore records the module folder the mod manager last bound the UUID to,
+      not the copy the running game loaded. It is rewritten when the mod list is edited (the in-game
+      manager, Vortex, BG3 Mod Manager)."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - load-order
+      - modsettings
+      - launch
+      - folder
+      - uuid
+    detail: "Consequence for diagnosis: with several installed copies of one UUID, the Folder attribute
+      cannot tell you which copy the game bound to at the last launch; read the content back through
+      the Script Extender (Ext.Stats.Get on an entry unique to one copy, or ModWright's
+      bg3.stat.exists probe) instead. ModWright's own load_order guidance used to say the game
+      \"rewrites modsettings.lsx on launch\"; that is the mod-manager case in
+      bg3.loadorder.modsettings-not-durable, not a plain launch."
+  - id: bg3.loadorder.profile-activemods-drives-current-order-not-modsettings-order-alone
+    claim: BG3 Mod Manager reconstructs "the current load order" from a profile by reading the
+      ActiveMods list recorded under modsettings.lsx's Mods node and matching each entry's UUID
+      against its own indexed mod list in that same sequence, skipping any UUID it cannot match —
+      the DivinityProfileData model documents ActiveMods explicitly as "The mod data under the Mods
+      node, from modsettings.lsx".
+    status: verified
+    source: LaughingLeader/BG3ModManager@fc35358 src/Core/Models/DivinityProfileData.cs:21-24 (the
+      ActiveMods field and its doc comment), :26-39 (GetLoadOrder walking ActiveMods in order)
+    detail: "Inference, not in the source: because the manager rebuilds \"Current\" purely from that
+      list, the Mods node's child order in modsettings.lsx is the order it reflects back — there is
+      no separate order file involved in this path. Checked against the source (2026-09-08):
+      `verified_on` removed; this is read from the mod manager's source, which names no game
+      version."
+    tags:
+      - load-order
+      - modsettings
+      - activemods
+      - bg3modmanager

package/knowledge/baldursgate3/localization.handles.yaml

@@ -0,0 +1,92 @@
+game: baldursgate3
+topic: localization.handles
+title: Localization handles, UUID mapping, and field-specific formatting
+facts:
+  - id: bg3.loca.handle-is-uuid-with-g-separators
+    claim: 'A loca handle IS a UUID with an h prefix and dashes→g: uuid abcd1234-... ↔ handle
+      habcd1234g.... The game shows "Not Found" for a human-readable handle such as
+      h_Em_Example_DisplayName.'
+    status: verified
+    source: ModWright field verification
+    tags:
+      - localization
+      - handles
+      - uuid
+      - format
+    detail: 'Generate deterministically: "h" + str(uuid.uuid5(MOD_UUID, key)).replace("-","g"). All four
+      dashes of the UUID become g characters; the underlying UUID is unchanged.'
+  - id: bg3.loca.display-name-format
+    claim: Stat fields DisplayName and Description use the h..g..;<version> handle form. But some fields
+      (TooltipUpcastDescription, ExtraDescription) take the raw dash-UUID form (abcd1234-...). Match
+      the form the field expects; the underlying UUID is the same.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - localization
+      - handles
+      - field-specific
+      - format
+    detail: The engine maps the raw dash-UUID form to the same loca entry. This inconsistency is a
+      common mistake source.
+  - id: bg3.loca.xml-location-and-format
+    claim: Loca lives in Mods/<Mod>/Localization/English/<Mod>.xml as <content contentuid="h..."
+      version="1">text</content>. The .xml must be compiled to the binary .loca, which is what ships
+      in the pak and is required at runtime.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - localization
+      - xml
+      - loca
+      - format
+    detail: Compile with Divine.exe -g bg3 -a convert-loca -s <src>.xml -d <out>.loca. See
+      bg3.toolchain.loca-compilation.
+  - id: bg3.loca.description-params-inheritance
+    claim: DescriptionParams only substitutes into [1]-style placeholders; harmless if the text has
+      none, but inherited params (via `using`) can be stale — clear them when reskinning.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - localization
+      - params
+      - reskin
+      - inheritance
+    detail: Set DescriptionParams "" to clear inherited params that no longer apply to the reskinned
+      spell/item.
+  - id: bg3.loca.entry-version-is-uint16
+    claim: A compiled .loca entry's Version field (the number after the ";" in a handle reference such
+      as "h...;<version>", and the same number as the .xml content tag's version attribute) is
+      stored as a 16-bit unsigned integer in the binary format — a version number above 65535 cannot
+      be represented and would wrap or fail to compile correctly.
+    status: inferred
+    source: Norbyte/lslib@6f5f698 LSLib/LS/Localization.cs:22 (`public UInt16 Version;` in LocaEntry)
+    tags:
+      - localization
+      - loca
+      - version
+      - binary-format
+    detail: Inferred from the struct field type (UInt16 Version) rather than observed failing — no
+      vanilla or known mod content has been checked against this ceiling, but no hand-authored mod
+      is likely to approach it either, since version numbers only increment when a line's text
+      changes.
+  - id: bg3.loca.magic-signature-and-numentries-header
+    claim: A compiled .loca file opens with a 4-byte magic signature spelling 'LOCA' (0x41434f4c)
+      followed by a uint32 entry count and a uint32 byte offset where the actual text payload
+      begins; LSLib's reader throws "Incorrect signature in localization file" on any file that
+      doesn't start with that exact magic.
+    status: verified
+    source: "Norbyte/lslib@6f5f698 LSLib/LS/Localization.cs:5-13 (LocaHeader:
+      Signature/NumEntries/TextsOffset, DefaultSignature 0x41434f4c), :75-80 (the signature check
+      and its InvalidDataException)"
+    detail: "Checked against the source (2026-09-08): `verified_on` removed — read from LSLib's source,
+      which names no game version."
+    tags:
+      - localization
+      - loca
+      - binary-format
+      - magic-signature
+    related:
+      - id: bg3.loca.xml-location-and-format
+        detail: Adds the compiled .loca file's exact binary header shape underneath the already-verified
+          statement that .loca is what ships in the pak and is required at runtime — this is the
+          format LSLib's reader validates before trusting the rest of the file.

package/knowledge/baldursgate3/misc.encoding-and-practice.yaml

@@ -0,0 +1,111 @@
+game: baldursgate3
+topic: misc.encoding-and-practice
+title: Version encoding, UTF-8 handling, reference checking, and development practices
+facts:
+  - id: bg3.encoding.version64-format
+    claim: "Mod version in meta.lsx: Version64 = (major<<55) | (minor<<47) | (revision<<31) | build.
+      Decode/encode in Python: def enc(ma,mi,rev,bld): return (ma<<55)|(mi<<47)|(rev<<31)|bld; def
+      dec(v): return (v>>55, (v>>47)&0xFF, (v>>31)&0xFFFF, v&0x7FFFFFFF). Bump revision for
+      iterative builds. Bumping the version does NOT break loading an existing save."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - version
+      - encoding
+      - meta.lsx
+    detail: The revision field (bits 31–46) is the primary field for dev iteration; major/minor rarely
+      change.
+  - id: bg3.encoding.utf8-bom-corruption
+    claim: PowerShell 5.1 Set-Content -Encoding utf8 writes a UTF-8 BOM — stats .txt and .lsx files must
+      stay BOM-less. Use Python or careful byte writes for surgical edits to game-parsed files.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - encoding
+      - utf-8
+      - bom
+      - powershell
+    detail: The BOM is invisible but breaks parsing. Found in the 2026-08-31 launch-CTD bisect.
+  - id: bg3.practice.reference-checker-invaluable
+    claim: A static reference checker — a script that verifies every
+      SpellList/DefaultValues/SelectSpells/ApplyStatus/RootSpellID/`using` reference resolves
+      against your stats plus a vanilla stats extract — catches the dangling-ref CTDs before
+      packing. Invaluable; run it before every pack.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - tools
+      - reference-checking
+      - automation
+    detail: A class mod's reference-checking script is the reference implementation; it later grew drift
+      checks for hardcoded enumerations (the per-slot SpellId enumeration behind an on-cast charge
+      passive).
+  - id: bg3.practice.diagnostic-with-every-fix
+    claim: Pair a diagnostic with every bug-fix from the first attempt. Don't ship a blind fix and wait
+      a relaunch cycle. A visible marker (a temporary distinctive boost, a visible status, an SE
+      print/dump) gives ground truth in one cycle instead of guessing over many.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - testing
+      - diagnostics
+      - debugging
+    detail: A spell-slot-display bug cost 3 blind cycles before an SE Ext.StaticData dump gave the
+      answer in one, and a character-level weapon gate was proven dead in one cycle by pairing it
+      with a visible "+1 Thunder" marker.
+  - id: bg3.practice.unproven-token-verification
+    claim: When a token/mechanism is unproven (no vanilla precedent), assume it may not work and verify
+      with a diagnostic before building a whole system on it.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - testing
+      - verification
+      - risky-patterns
+    detail: "Example: IsWeaponOfProficiencyGroup in an equip passive's Boosts had zero vanilla precedent
+      and was proven in-game on a gloves item before being relied on (see
+      bg3.weapons.weapon-category-gated-equipment-bonus)."
+  - id: bg3.practice.incremental-testing
+    claim: Test after every addition — don't stack multiple untested features. A static
+      reference-checker catches dangling-ref CTDs, but functor/status-field errors only surface
+      in-engine (usually logged, sometimes CTD). If a batch breaks, bisect.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - testing
+      - incremental
+      - bisect
+    detail: One untested phase stacked on another was the core failure mode of an earlier mod; the class
+      mod's workflow that followed has a per-phase testing checklist for this reason.
+  - id: bg3.practice.se-console-dumps
+    claim: 'An SE console dump (Ext.StaticData) settles "is my data wrong or is the UI wrong" questions:
+      it shows what the engine actually loaded. The Class Features investigation used it to prove
+      the ProgressionDescriptions and progression table were loaded and correct, which moved the bug
+      to the UI side.'
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - testing
+      - script-extender
+      - diagnostics
+    detail: The dump confirmed 9 ProgressionDescriptions loaded and matched to the exact boosts, the
+      progression table loaded with 13 nodes, and 419 ProgressionDescriptions / 1019 Progressions in
+      static data overall.
+  - id: bg3.practice.manual-path-first
+    claim: If a manual/GUI path is >99% likely to work and the headless path is unproven, OFFER THE
+      MANUAL PATH FIRST.
+    status: community
+    source: ModWright research
+    tags:
+      - practice
+      - automation
+      - manual
+    detail: 'A behavioural rule for assistants rather than a BG3 engine fact: automate what is certain,
+      offer manual routes when they are safer. The CP2077 "sector saga" violated it and cost time.'