modwright 0.1.0

package/knowledge/baldursgate3/origins.companions.yaml

@@ -0,0 +1,144 @@
+game: baldursgate3
+topic: origins.companions
+title: Custom origin creation (manual/non-Toolkit method)
+facts:
+  - id: bg3.origins.companions.moderate-difficulty-manual-method
+    claim: "\"This tutorial is considered moderate difficulty–you are expected to already be familiar
+      with code editing and searching BG3's files for the info you need.\" It documents the manual
+      (non-Toolkit) method; a separate page, \"Creating Custom Origins In Toolkit\", covers the
+      Toolkit route."
+    status: community
+    source: wiki.bg3.community/en/Tutorials/General/Custom-Origin-Creation
+    tags:
+      - origin
+      - difficulty
+      - toolkit
+      - manual-method
+  - id: bg3.origins.companions.regenerate-uuid-find-replace-warning
+    claim: The custom-origin template repeatedly marks placeholder UUIDs with "Regenerate this!"
+      comments; the recommended fix is VS Code's "Replace in Files" to replace every occurrence of a
+      given UUID across the whole template at once, specifically to avoid UUIDs that don't link up
+      between files, which the guide calls out as a cause of crashes.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/General/Custom-Origin-Creation
+    tags:
+      - origin
+      - uuid
+      - crash
+      - find-replace
+  - id: bg3.origins.companions.origins-lsx-tag-must-be-a-real-origin-tag
+    claim: The default origin tags in the template are fine for a Tav-like origin; "If you want a Durge
+      origin, you'll have to swap in the REALLY_DARK_URGE tag". Origins.lsx's ReallyTags must name a
+      tag that exists — an existing origin's tag works ("Heck, you could even put in another
+      origin's tag if you wanted, but it probably wouldn't make a lot of narrative sense").
+    status: community
+    source: wiki.bg3.community/en/Tutorials/General/Custom-Origin-Creation
+    tags:
+      - origin
+      - origins-lsx
+      - tags
+  - id: bg3.origins.companions.cc-body-race-swap-causes-floating-heads
+    claim: Making a custom origin's body type or race editable in character creation doesn't work
+      reliably with the template's setup and produces symptoms like floating heads; the tutorial
+      author states they hadn't found a fix for this as of writing.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/General/Custom-Origin-Creation
+    tags:
+      - origin
+      - character-creation
+      - floating-heads
+      - known-bug
+  - id: bg3.origins.companions.cc-editable-scar-resets-to-default
+    claim: If a custom origin is made editable in character creation, any scar preset baked into its
+      Character Visuals resets to "no scar" and the player has to reselect it manually; scars are
+      fine only when the origin's appearance is kept locked (not editable).
+    status: community
+    source: wiki.bg3.community/en/Tutorials/General/Custom-Origin-Creation
+    tags:
+      - origin
+      - character-creation
+      - scars
+      - character-visuals
+      - known-bug
+  - id: bg3.origins.companions.custom-colors-need-mergedinto-on-race
+    claim: Custom eye/hair/skin colors on an origin reset in character creation when the game can't find
+      them as part of the race's defaults — "If the game can't find their custom colors as part of
+      the race defaults, it'll reset to the first color in the race's list" — and the fix is to add
+      those colors to the origin's race using MergedInto.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/General/Custom-Origin-Creation
+    tags:
+      - origin
+      - character-creation
+      - mergedinto
+      - colors
+      - silent-failure
+  - id: bg3.origins.companions.crash-without-worldcharacter-equivalent-file
+    claim: The custom-origin template includes a file that defines the character in the world itself
+      (separate from the origin-list entry and the CC-preset template); the tutorial author reports
+      the game crashed when that file was omitted, even though its exact necessity for an origin
+      wasn't fully understood.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/General/Custom-Origin-Creation
+    tags:
+      - origin
+      - crash
+      - world-character
+  - id: bg3.origins.companions.vanilla-tav-voice-uuids
+    claim: A custom origin can be pinned to a single fixed voice by building a custom voice table
+      containing only one of the vanilla Tav voice UUIDs — voice 1
+      24247531-c432-4f0f-8f35-6c90c4844aa8, voice 2 869248f0-468a-4747-82d7-e8efc3bbcacf, voice 3
+      4df6dba0-8574-4704-a9fb-a500da38e1e1, voice 4 3347e417-d7ad-4088-bdd6-d5565efcd815, voice 5
+      f5b335b2-9cd9-4b38-a4c1-458b846ab499, voice 6 b9b26a44-943b-4427-9890-d81c7e81a75b, voice 7
+      2d206fda-0d4f-457f-b4ea-0fc18866f5dd, voice 8 fb6b5353-8d14-4507-9222-ceaec990fce9 — set into
+      a table's SpeakerUUID field and assigned back in Origins.lsx.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/General/Custom-Origin-Creation
+    tags:
+      - origin
+      - voice
+      - uuid
+  - id: bg3.origins.companions.pickable-voice-table-uuid
+    claim: To let the player pick a voice for a custom origin in character creation (instead of a fixed
+      one), Origins.lsx's voice table field should be set back to the vanilla pickable-voice table
+      UUID 5ee56242-d07c-482e-9260-24529d1473a3.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/General/Custom-Origin-Creation
+    tags:
+      - origin
+      - voice
+      - uuid
+  - id: bg3.origins.companions.custom-portrait-requires-generator-trigger
+    claim: A custom generated portrait for a custom origin requires setting up a trigger/camera-trigger
+      pair that fires on game start and level up, positioned using in-game coordinates (obtained
+      e.g. via the Script Extender console command "_P(Osi.GetPosition(GetHostCharacter()))"); it
+      only affects the origin-selection icon, and the pose used is whatever the origin's
+      race/bodytype default pose is.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/General/Custom-Origin-Creation
+    tags:
+      - origin
+      - portrait
+      - trigger
+      - camera
+  - id: bg3.origins.companions.starting-equipment-file-defines-gear
+    claim: A custom origin's starting equipment (armor, camp clothes, other items) is defined in its own
+      equipment file; the recommended way to find an item's real stats name from its in-game display
+      is to look it up on a wiki, then paste the UUID into the Multitool or NorbSearch to resolve
+      the actual stats entry name.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/General/Custom-Origin-Creation
+    tags:
+      - origin
+      - starting-equipment
+      - multitool
+  - id: bg3.origins.companions.dependencies-recommended-for-releases
+    claim: A custom origin that relies on other mods should declare them as dependencies — described as
+      "especially important if you'd be releasing your custom origin" — via the general
+      mod-dependencies process, not a custom-origin-specific one.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/General/Custom-Origin-Creation
+    tags:
+      - origin
+      - dependencies
+      - meta-lsx

package/knowledge/baldursgate3/osiris.signatures.yaml

@@ -0,0 +1,211 @@
+game: baldursgate3
+topic: osiris.signatures
+title: Osiris call/query/event signatures, confirmed against the generated LaughingLeader stubs
+facts:
+  - id: bg3.osiris.signatures.setflag-has-three-overloads
+    claim: "Osi.SetFlag has three overloads shorter than its full four-parameter form: fun(flag),
+      fun(flag, object), and fun(flag, object, dialogInstance); the full form is SetFlag(flag:FLAG,
+      object:GUIDSTRING, dialogInstance:integer, sendFlagSetEventIfChanged:integer)."
+    status: verified
+    source: LaughingLeader/BG3ModdingTools/generated/Osi.lua:4074-4080
+    tags:
+      - osiris
+      - setflag
+      - overload
+      - signature
+    related:
+      - id: bg3.dialogue.flags-guid-definitions
+        detail: Confirms the existing fact's two-argument Osi.SetFlag("Name_GUID", char) usage is the
+          documented fun(flag, object) overload, not an ad hoc shorthand.
+  - id: bg3.osiris.signatures.getflag-is-two-param-query
+    claim: Osi.GetFlag is a two-parameter query, GetFlag(flag:FLAG, object:GUIDSTRING) returning an
+      integer flagState — the object parameter is required, there is no zero- or one-argument
+      overload the way SetFlag has.
+    status: verified
+    source: LaughingLeader/BG3ModdingTools/generated/Osi.lua:914-918
+    tags:
+      - osiris
+      - getflag
+      - query
+      - signature
+    related:
+      - id: bg3.se.osi-queries-broken-actions-work
+        detail: Records GetFlag's real signature only — does not contradict the existing verified finding
+          that Osi.GetFlag itself is unreliable on this SE build; this fact is purely about arity,
+          not correctness.
+  - id: bg3.osiris.signatures.requestdelete-single-item-param
+    claim: Osi.RequestDelete takes exactly one parameter, an ITEM, with no overloads in the generated
+      stub file — RequestDeleteTemporary(character:CHARACTER) is a distinct, separate call for
+      temporary summons, not an overload of RequestDelete.
+    status: verified
+    source: LaughingLeader/BG3ModdingTools/generated/Osi.lua:3747-3752
+    tags:
+      - osiris
+      - requestdelete
+      - signature
+    related:
+      - id: bg3.se.corpse-removal
+        detail: Confirms the existing fact's Osi.RequestDelete(obj) call shape exactly, arity 1.
+  - id: bg3.osiris.signatures.usespell-guidstring-caster-and-target-types
+    claim: "Osi.UseSpell's canonical five-parameter form types caster and target/target2 as GUIDSTRING
+      (not CHARACTER), spellID as a plain string, and withoutMove as an integer:
+      UseSpell(caster:GUIDSTRING, spellID:string, target:GUIDSTRING, target2:GUIDSTRING,
+      withoutMove:integer); the two shorter forms are declared as @overload annotations (fun(caster,
+      spellID, target) and fun(caster, spellID, target, target2)), confirming there is no overload
+      that takes a spell level."
+    status: verified
+    source: LaughingLeader/BG3ModdingTools/generated/Osi.lua:4770-4779
+    tags:
+      - osiris
+      - usespell
+      - overload
+      - signature
+    related:
+      - id: bg3.se.use-spell-forced-cast
+        detail: Sharpens the existing verified fact's "3/4/5 args, NO level parameter" claim with the exact
+          generated-stub parameter types and confirms the two shorter forms are annotated @overload
+          rather than independently declared functions.
+  - id: bg3.osiris.signatures.query-functions-flagged-broken-have-real-signatures
+    claim: "The specific query functions recorded as unreliable on one SE build all have ordinary,
+      single-form signatures in the generated stub file: GetEquippedItem(character:CHARACTER,
+      slotName:EQUIPMENTSLOTNAME):ITEM; HasActiveStatus(target, status):integer; HasPassive(entity,
+      passiveID:string):integer (return named boolHasPassive); IsDead(character):integer;
+      IsEnemy(character, otherCharacter):integer; IsPlayer(character):integer;
+      GetDistanceTo(object1, object2):number. None of the seven carries an @overload annotation."
+    status: verified
+    source: LaughingLeader/BG3ModdingTools/generated/Osi.lua:878-884 (GetDistanceTo), :893-897
+      (GetEquippedItem), :1340-1345 (HasActiveStatus), :1391-1392 (HasPassive), :1532 (IsDead),
+      :1556 (IsEnemy), :1764 (IsPlayer)
+    tags:
+      - osiris
+      - query
+      - signature
+      - arity
+    related:
+      - id: bg3.se.osi-queries-broken-actions-work
+        detail: Records the exact signature of every query function named as broken on that SE build. This
+          fact states arity/typing only and does not claim these queries return correct values — it
+          neither contradicts nor rehabilitates the "do not trust them" finding.
+  - id: bg3.osiris.signatures.gethostcharacter-getmaxhitpoints-arity
+    claim: Osi.GetHostCharacter() takes no parameters and Osi.GetMaxHitpoints(entity) takes exactly one
+      — confirming the two calls used by an Osiris-health probe resolve to real, single-form
+      generated stubs rather than overloaded or ambiguous names.
+    status: verified
+    source: LaughingLeader/BG3ModdingTools/generated/Osi.lua:974,1048
+    tags:
+      - osiris
+      - gethostcharacter
+      - getmaxhitpoints
+      - signature
+  - id: bg3.osiris.signatures.questupdate-family-signatures
+    claim: The generated stub declares QuestUpdate(character, questID, stateID) as a three-parameter
+      call with one `@overload fun(questID:string, stateID:string)` annotation (not a separately
+      declared function); QuestAdd(character, questID) and QuestClose(questID) are separate,
+      unrelated calls with different arities (2 and 1); the events QuestUpdateUnlocked(character,
+      topLevelQuestID, stateID) and QuestClosed(questID) are 3- and 1-parameter respectively.
+    status: verified
+    source: LaughingLeader/BG3ModdingTools@ab343b6 generated/Osi.lua:3547,3550,3570-3574 (QuestAdd,
+      QuestClose, QuestUpdate with its @overload line at :3570); generated/Osi.Events.lua:867,877
+      (QuestClosed, QuestUpdateUnlocked)
+    tags:
+      - osiris
+      - questupdate
+      - questadd
+      - questclose
+      - signature
+    detail: "Checked against the source (2026-09-08): an earlier wording said the two-argument form \"is
+      not itself a separately generated function — it is documented as 'overloading the engine
+      call'\". The first half is right, but the quoted phrase is unattributed and the generated file
+      does carry the annotation, so the claim now states what the file shows. Note the annotation
+      drops the LEADING parameter (character), a second counterexample to the trailing-drop rule —
+      see bg3.osiris.signatures.use-overload-is-a-counterexample-to-the-trailing-drop-rule."
+    related:
+      - id: bg3.journal.quests.questupdate-requires-parent-quest-id
+        detail: Adds the exact generated-stub parameter list underneath the community wiki's semantic claim
+          about which quest ID QuestUpdate expects.
+      - id: bg3.journal.quests.questadd-questclose-should-be-avoided
+        detail: Confirms QuestAdd and QuestClose are real, separately declared calls (2- and 1-parameter)
+          rather than aliases of QuestUpdate, consistent with the community advice to prefer
+          QuestUpdate over either.
+  - id: bg3.osiris.signatures.equip-overloads-confirm-trailing-drop-rule
+    claim: Osi.Equip's three shorter @overload forms — fun(character, item), fun(character, item,
+      addToMainInventoryOnFail), and fun(character, item, addToMainInventoryOnFail,
+      showNotification) — each drop parameters only from the end of the full 5-parameter form,
+      confirming the community guide's general Osiris rule that "overloaded calls cannot change the
+      order of the parameters" and that supplying a non-default value for a late parameter requires
+      supplying every parameter before it too.
+    status: community
+    source: bg3-community/Tutorials/Osiris/Understanding-Osiris-Actions.md:111, §Overloaded Calls
+      ("overloaded calls cannot change the order of the parameters."); cross-checked against
+      LaughingLeader/BG3ModdingTools@ab343b6 generated/Osi.lua:2960-2966 (Equip)
+    tags:
+      - osiris
+      - overload
+      - calling-convention
+      - equip
+    detail: "Checked against the source (2026-09-08): quotation trimmed to one sentence (the page states
+      no licence). The page's next sentence makes the same point for the caller's side: supplying a
+      non-default value for a late parameter means supplying every parameter before it."
+    related:
+      - id: bg3.osiris.signatures.use-overload-is-a-counterexample-to-the-trailing-drop-rule
+        detail: Disagrees in the general case. Equip's own three overloads do only drop trailing parameters,
+          but Osi.Use's generated overload does not, so the community guide's rule must not be
+          applied to an arbitrary call without checking that call's own @overload lines.
+  - id: bg3.osiris.signatures.use-overload-is-a-counterexample-to-the-trailing-drop-rule
+    claim: "Osi.Use's generated 3-parameter @overload, fun(character, item, event), is NOT a
+      trailing-drop overload of its full form Use(character, item, useItem, isInteraction, event):
+      it omits the two MIDDLE parameters (useItem, isInteraction) while keeping the LAST one (event)
+      — the opposite shape from Equip's overloads. This contradicts the community guide's stated
+      general rule that overloaded calls only ever drop trailing parameters; at least one real
+      generated overload breaks that rule, and the three-argument form dispatches and acts at
+      runtime."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: LaughingLeader/BG3ModdingTools@ab343b6 generated/Osi.lua:4764-4770 (the `@overload
+      fun(character:CHARACTER, item:ITEM, event:string)` line at :4764 above `function
+      Osi.Use(character, item, useItem, isInteraction, event)` at :4770); contrasted with the
+      general rule stated in bg3-community/Tutorials/Osiris/Understanding-Osiris-Actions.md:111,
+      §Overloaded Calls
+    tags:
+      - osiris
+      - overload
+      - calling-convention
+      - use
+      - disagreement
+    detail: "Observed in game 2026-09-09 (SE console, save loaded): the two-argument
+      Osi.QuestUpdate(\"NoSuchQuest\", \"NoSuchState\") returned to the prompt with no arity error
+      and no output, so a shorter overload of QuestUpdate dispatches (with fake ids nothing
+      observable happens, which is the expected no-op). The Use three-argument form was then tried
+      with a real item guid the same night: it dispatches and has the item's Use effect, and the
+      five-argument form dispatches too. Side observation: Use on an equipped armor piece toggles it
+      (first call unequips, the next equips), and a malformed item id produces no error at all, so a
+      silent return is not proof the call did anything."
+    related:
+      - id: bg3.osiris.signatures.equip-overloads-confirm-trailing-drop-rule
+        detail: "Direct counterexample to the trailing-drop generalization that fact draws from the
+          community guide — do not assume every Osiris overload only omits trailing parameters;
+          check the specific @overload line in the generated file before calling a shorter form. A
+          second counterexample in the same file drops a LEADING parameter: QuestUpdate's `@overload
+          fun(questID, stateID)` (Osi.lua:3570), recorded in
+          bg3.osiris.signatures.questupdate-family-signatures. Neither this fact nor the Equip one
+          is verified beyond what the annotations literally say; what the engine does with a short
+          form at runtime was not observed."
+  - id: bg3.osiris.signatures.applystatus-lands-after-the-calling-chunk
+    claim: "Osi.ApplyStatus(target, status, duration, force) does not apply the status synchronously:
+      Osi.HasActiveStatus(target, status) in the same Lua chunk, right after the call, returns 0,
+      and a read one request later (fourteen seconds) returns 1. A read-back belongs in a separate
+      probe or a later tick, not in the chunk that applies."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - osiris
+      - applystatus
+      - hasactivestatus
+      - timing
+      - eval
+    detail: GetStatusTurns read -1 in the same chunk as the indefinite (-1.0) application; it was not
+      read again in the later request, so only HasActiveStatus is attested across the gap. The
+      earlier 12.0-second application had expired on its own out of combat before its first read 27
+      seconds later (HasActiveStatus 0, GetStatusTurns 0), so a short duration masks this timing
+      rather than exposing it.

package/knowledge/baldursgate3/packaging.meta.yaml

@@ -0,0 +1,155 @@
+game: baldursgate3
+topic: packaging.meta
+title: meta.lsx ModuleInfo schema, dependency/conflict declaration, and header versioning
+facts:
+  - id: bg3.packaging.meta.moduleinfo-fields-read-by-mod-manager
+    claim: "LaughingLeader's BG3 Mod Manager parses a mod's meta.lsx ModuleInfo node for these
+      attributes: UUID, Name, Author, Version (via Version64 falling back to Version — see
+      bg3.packaging.meta.version64-preferred-with-version-fallback), Folder, Description, MD5, Type,
+      PublishHandle, and FileSize, plus the root <version major minor revision build> element read
+      separately as the file's own header version."
+    status: verified
+    source: LaughingLeader/BG3ModManager@fc35358 src/Core/Util/DivinityModDataLoader.cs:222-235
+    tags:
+      - meta-lsx
+      - moduleinfo
+      - required-fields
+      - bg3modmanager
+  - id: bg3.packaging.meta.version64-preferred-with-version-fallback
+    claim: BG3 Mod Manager reads a mod's version from meta.lsx by checking two attribute names in order
+      — "Version64" first, then the legacy "Version" — via a two-element fallback array, not by
+      assuming Version64 is always present.
+    status: verified
+    source: LaughingLeader/BG3ModManager@fc35358 src/Core/Util/DivinityModDataLoader.cs:32
+    tags:
+      - meta-lsx
+      - version64
+      - version
+      - fallback
+    related:
+      - id: bg3.ui.mcm.dependency-version64-should-pin-dev-version
+        detail: Independently confirms "Version64" as the real meta.lsx attribute name MCM's own
+          dependency-version advice refers to, and adds that a mod manager reading a dependency's
+          version falls back to the older "Version" attribute if Version64 is absent.
+  - id: bg3.packaging.meta.moduletype-attribute-marked-deprecated-in-source
+    claim: BG3 Mod Manager's own source comments the ModuleInfo "Type" attribute as "// Deprecated?" at
+      the point it is read into ModType — the mod manager still reads and stores the field, but its
+      own maintainer considers its meaning uncertain or obsolete going forward. GustavDev and
+      GustavX are hardcoded to ModType "Adventure" regardless of what their meta.lsx actually
+      contains, overriding whatever Type value those two specific UUIDs carry.
+    status: inferred
+    source: LaughingLeader/BG3ModManager@fc35358 src/Core/Util/DivinityModDataLoader.cs:229,237-241
+    tags:
+      - meta-lsx
+      - moduletype
+      - deprecated
+      - gustavdev
+      - hardcoded
+    detail: Inferred from the source comment and the special-cased UUID check, not from documentation
+      stating the field is deprecated outright — treat a meta.lsx Type value as advisory rather than
+      load-bearing.
+  - id: bg3.packaging.meta.tags-attribute-is-semicolon-delimited
+    claim: A meta.lsx ModuleInfo node's Tags attribute is a single string of semicolon-separated tag
+      names, which the mod manager reads with `tagsText.Split(';')` into a tag list.
+    status: verified
+    source: LaughingLeader/BG3ModManager@fc35358 src/Core/Util/DivinityModDataLoader.cs:242-246
+    tags:
+      - meta-lsx
+      - tags
+      - moduleinfo
+    detail: "Checked against the source (2026-09-08): an earlier wording also asserted \"there is no
+      separate child Tags node the way a ClassDescription's race/class Tags reference works\". A
+      parser that does not read such a node is not evidence that none exists, so that half has been
+      dropped rather than promoted."
+  - id: bg3.packaging.meta.dependencies-node-holds-moduleshortdesc-children
+    claim: A meta.lsx's Dependencies node (a sibling of ModuleInfo, found by searching for a node whose
+      id equals "Dependencies") contains one child node per dependency with id "ModuleShortDesc",
+      each carrying its own Folder, MD5, Name, UUID, and Version(64) attributes.
+    status: verified
+    source: LaughingLeader/BG3ModManager@fc35358 src/Core/Util/DivinityModDataLoader.cs:251-273
+    tags:
+      - meta-lsx
+      - dependencies
+      - moduleshortdesc
+    detail: "Checked against the source (2026-09-08): an earlier wording added that this is \"the same
+      ModuleShortDesc shape the Compatibility Framework's config schema also uses for its per-mod
+      entries\". No fact in knowledge/baldursgate3/compatibilityframework.api.yaml mentions
+      ModuleShortDesc and the cited parser says nothing about the Compatibility Framework, so that
+      comparison has been dropped."
+    related:
+      - id: bg3.ui.mcm.dependency-recommended-in-meta-lsx
+        detail: Confirms the exact node/attribute shape ("ModuleShortDesc" under a "Dependencies" node) that
+          declaring MCM as a meta.lsx dependency actually produces, read independently from the mod
+          manager's own parser rather than from the MCM tutorial.
+  - id: bg3.packaging.meta.conflicts-node-mirrors-dependencies-shape
+    claim: meta.lsx also supports a "Conflicts" node using the identical child shape as Dependencies
+      (child nodes with id "ModuleShortDesc" carrying Folder/MD5/Name/UUID/Version), parsed into a
+      separate ModData.Conflicts list by the mod manager — a distinct declaration from Dependencies,
+      kept in a separate list. What the game or the manager then does with a declared conflict is
+      not shown by the cited parser code.
+    status: verified
+    source: LaughingLeader/BG3ModManager@fc35358 src/Core/Util/DivinityModDataLoader.cs:278-300
+    tags:
+      - meta-lsx
+      - conflicts
+      - moduleshortdesc
+  - id: bg3.packaging.meta.bg3-header-version-is-4-0-9
+    claim: BG3 Mod Manager's own source comment records the meta.lsx root <version> element's expected
+      form for a BG3 mod as major="4" minor="0" revision="9" (with a mod-specific build number, e.g.
+      331 in the comment's example) — distinct from the D:OS Classic (3.1.3.5) and D:OS 2 DE
+      (3.6.2.0) forms the same parser also recognizes for older-game meta.lsx files.
+    status: verified
+    source: LaughingLeader/BG3ModManager@fc35358 src/Core/Util/DivinityModDataLoader.cs:183-189
+    tags:
+      - meta-lsx
+      - header-version
+      - bg3modmanager
+    detail: The mod manager falls back to hardcoded HEADER_MAJOR/MINOR/REVISION/BUILD constants if the
+      file has no <version> element at all, rather than rejecting the meta.lsx outright — and those
+      constants (DivinityModDataLoader.cs:27-30) are 4/8/0/0, i.e. 4.8.0.0, not the 4.0.9.x form the
+      comment gives for a BG3 mod. Do not read the fallback as a second attestation of 4.0.9.
+  - id: bg3.packaging.meta.mod-manager-auto-resolves-dependency-order
+    claim: BG3 Mod Manager's own load-order builder (BuildOutputList) walks each enabled mod's declared
+      Dependencies recursively via GetDependencyMods and inserts every not-yet-added dependency into
+      the output order immediately before the mod that needs it (recursively, skipping any
+      dependency UUID that does not resolve to an indexed local mod).
+    status: verified
+    source: LaughingLeader/BG3ModManager@fc35358 src/Core/Util/DivinityModDataLoader.cs:1400-1428
+      (GetDependencyMods), :1431-1465 (BuildOutputList)
+    tags:
+      - meta-lsx
+      - dependencies
+      - load-order
+      - bg3modmanager
+      - automatic
+    detail: "Inference, not in the source: a mod author who declares Dependencies correctly therefore
+      does not need end users to drag the dependency above it by hand — but only for orders built or
+      exported through BG3 Mod Manager with addDependencies left at its default true, and only when
+      the dependency is installed and indexed."
+    related:
+      - id: bg3.loadorder.external-guid-dependencies
+        detail: Sharpens the existing verified fact (a missing/misordered dependency CTDs at LoadModule) by
+          showing the mechanism a well-formed meta.lsx Dependencies declaration uses to avoid that
+          failure automatically, at least when the mod list is built or exported through BG3 Mod
+          Manager rather than hand-edited.
+  - id: bg3.packaging.meta.modsettings-export-is-plain-xml-write
+    claim: BG3 Mod Manager writes modsettings.lsx by generating its XML content in memory, re-indenting
+      it with a standard XmlDocument/XmlTextWriter pass (2-space indentation), and writing the UTF-8
+      bytes to Path.Combine(folder, "modsettings.lsx") with FileMode.Create and FileShare.None.
+    status: verified
+    source: LaughingLeader/BG3ModManager@fc35358 src/Core/Util/DivinityModDataLoader.cs:1331-1352
+    tags:
+      - meta-lsx
+      - modsettings
+      - bg3modmanager
+      - file-locking
+    detail: "Inference, not in the source: FileShare.None means no other process may hold the file open
+      during the write, so a write attempted while the game (or a second manager instance) has
+      modsettings.lsx open should fail — the code catches and logs exceptions there rather than
+      describing that case."
+    related:
+      - id: bg3.loadorder.modsettings-not-durable
+        detail: "Adds a mechanism note to the existing fact about hand-edited modsettings.lsx entries being
+          overwritten: the mod manager's own writer does a full regenerate-and-overwrite, not an
+          in-place patch, which is why any hand-added entry outside its own model does not survive a
+          re-export."

package/knowledge/baldursgate3/packaging.paks.yaml

@@ -0,0 +1,79 @@
+game: baldursgate3
+topic: packaging.paks
+title: PAK file packaging, load precedence, and locking behavior
+facts:
+  - id: bg3.paks.same-uuid-precedence
+    claim: A packed mod of the same UUID in the profile Mods\ folder WINS over a junctioned/loose copy.
+      A stale same-UUID pak silently overrides your loose edits — the classic "why aren't my changes
+      showing" trap.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - pak
+      - precedence
+      - loose-mods
+      - uuid
+      - load-order
+    detail: Loose+junctioned mods are also NOT reliably visible in the in-game mod manager list in this
+      environment; a present .pak is what the list shows. For real testing beyond SE Lua / stats
+      hot-reload, rebuild and deploy the pak. If edits "don't take", check the pak's timestamp
+      before debugging further.
+  - id: bg3.paks.every-same-uuid-pak-is-opened
+    claim: When several .pak files in the profile Mods folder carry the same module UUID, the running
+      game holds every one of them open (a rename of any of them fails with "being used by another
+      process" until the game exits), even though Ext.Mod.GetMod(uuid).Info.Directory names only one
+      module folder as bound.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - pak
+      - uuid
+      - duplicate
+      - file-lock
+      - deploy
+    detail: "Consequence for deploy: retiring a duplicate pak needs the game closed, the same as
+      replacing the bound one. Which copy the engine binds among duplicates was the sideloaded .pak
+      in every launch that day regardless of launch path or the mod-management screen; the rule
+      behind that choice is still not characterised."
+  - id: bg3.paks.paks-lock-while-running
+    claim: PAKs lock while the game is running. You cannot overwrite the profile pak while BG3 is open
+      ("Device or resource busy").
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - pak
+      - locking
+      - game-process
+    detail: "Reliable pattern: build to a scratch path, then a background watcher polls tasklist | grep
+      bg3_dx11.exe and copies the pak once the process exits (the player has to restart to load a
+      new pak anyway)."
+  - id: bg3.paks.profile-pak-directory
+    claim: Deploy by copying the built pak to %LOCALAPPDATA%\Larian Studios\Baldur's Gate
+      3\Mods\<Mod>.pak (the user profile, not the game directory).
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - pak
+      - deployment
+      - profile
+    detail: The profile Mods folder is where packed mods load from and what the in-game manager lists.
+      The game's own Data\Mods / Data\Public tree is used for the loose junctioned dev loop and for
+      loose dialog overrides, not for shipping a pak.
+  - id: bg3.paks.stats-spell-load-fresh
+    claim: Stat/spell/loca changes load fresh from the pak on game load — they apply to existing SAVES
+      (no new game needed). But anything baked at a moment in time (a summoned item's stats, a
+      granted progression feature) needs a re-trigger (re-summon; respec).
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - pak
+      - reloading
+      - save-compatibility
+      - progression
+    detail: A common source of "my change isn't showing on this save". Progressions partially bake into
+      saves once loaded, so always test progression changes on a fresh save or respec with Withers.

package/knowledge/baldursgate3/process.launch.yaml

@@ -0,0 +1,34 @@
+game: baldursgate3
+topic: process.launch
+title: Launching Baldur's Gate 3 from a script
+facts:
+  - id: bg3.process.steam-intercepts-direct-exe-launch
+    claim: Launching `bin\\bg3_dx11.exe --skip-launcher` directly, bypassing `steam://rungameid`, makes
+      Steam show its own confirmation dialog that a person must click before the game starts.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - process
+      - launch
+      - steam
+      - unattended
+    detail: Whether a Steam setting suppresses the dialog, or whether the `steam://rungameid` route with
+      `--skip-launcher` set as a Steam launch option avoids it, is not yet established. Until it is,
+      a scripted BG3 launch cannot run unattended.
+  - id: bg3.process.launched-pid-is-not-the-game-pid
+    claim: After Steam's confirmation, the game runs under a different process id than the one
+      `Start-Process` returned for `bg3_dx11.exe`; the approved launch is re-spawned through Steam's
+      own wrapper.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - process
+      - launch
+      - steam
+      - pid
+      - lock
+    related:
+      - bg3.process.steam-intercepts-direct-exe-launch
+    detail: Anything that waits on, or kills, "the game process" by the launched pid will miss the real
+      one. Find the game by executable name or by the handle holding the pak, as ModWright's deploy
+      lock check already does.