modwright 0.1.0

package/scaffolds/baldursgate3/new-item.yaml

@@ -0,0 +1,264 @@
+# new-item (BG3, armor/weapon). Writes the stat -> RootTemplate -> VisualBank
+# triangle: a stats entry that `using`s a
+# vanilla parent, a RootTemplate GameObjects node with a fresh MapKey, a
+# TreasureTable row, and DisplayName/Description loca rows.
+#
+# Design note: this
+# scaffold REUSES an existing (project or vanilla) VisualBank Resource id
+# directly — RootTemplate's VisualTemplate points straight at the id the
+# author names — rather than writing a *new* VisualBank/MaterialBank/
+# TextureBank Resource chain of its own. Two reasons: the vanilla index's `guid` query
+# answers only a Resource node's own top-level attributes (`ID`, `Name`),
+# never its `Objects`/`Texture2DParameters` children (those node ids are not
+# in `INDEXED_NODE_IDS` — see build.ts), so a chosen visual's own MaterialID
+# cannot be read back through the index to build a faithful copy; and LSX has
+# no "insert a child node into an existing region's children" emit op in this
+# engine (only line-oriented text, loca and CR2W-json have dedicated insert
+# ops). Recoloring — writing a mod-owned bank chain and repointing
+# VisualTemplate at it — is the manual, optional creative step ("recolor art, optional").
+#
+# Observed in game: a loose `.lsx` under `Public/<Mod>/RootTemplates` is never
+# loaded by the game — `Ext.Template.GetTemplate` and `Osi.CreateAt` both
+# returned nothing for it live, while the identical node converted to a
+# `.lsf` of its own name (beside `_merged.lsf`, not merged into it) loaded,
+# resolved and spawned (knowledge fact
+# bg3.items.roottemplates.loose-lsx-in-roottemplates-is-not-loaded-a-separate-lsf-is).
+# The one-RootTemplate-per-file choice above still stands — only the file
+# *type* this scaffold shipped was wrong. Fixed by the `patch-project` emit
+# below, which ensures a `divine-lsx-to-lsf` build step exists (idempotent —
+# reapplying this scaffold never adds a second one) covering
+# `Public/**/RootTemplates/*.lsx`, with `deleteSource: true` and positioned
+# before `divine-create-package` (`engine.ts`'s `before:` convention) so the
+# item's own written `.lsx` reaches the pak as a `.lsf` and the stale `.lsx`
+# does not reach it at all. The narrow glob matters: only `RootTemplates` is
+# affected, and the rest of `Public/<Mod>` (Lists, Progressions,
+# ClassDescriptions, GUI atlases) keeps shipping as the `.lsx` the game
+# reads.
+id: baldursgate3.new-item
+game: baldursgate3
+title: New BG3 item (armor/weapon with a visual bank)
+summary: Append an Armor/Weapon stats entry with a vanilla `using` parent, a RootTemplate reusing an existing VisualBank visual, a TreasureTable row, and loca rows.
+modTypes: [armor, weapon, accessory]
+needs: { index: true }
+inputs:
+  - type: string
+    name: itemName
+    prompt: "Full stats entry name, e.g. HWV_TestBreastplate."
+    pattern: "^[A-Za-z][A-Za-z0-9_]*$"
+  - type: enum
+    name: entryKind
+    prompt: "Stats file this entry belongs in (also its `type`)."
+    values: [Armor, Weapon]
+  - type: string
+    name: slot
+    prompt: "data \"Slot\" value, e.g. Breast, Shield, Melee Main Weapon."
+  - type: index-ref
+    name: parentStat
+    prompt: "Vanilla (or project) Armor/Weapon entry to `using`."
+    lookup: { kind: stat, params: { name: "${input.parentStat}" } }
+    requires:
+      - path: type
+        matches: "^(Armor|Weapon)$"
+        reason: "the parent must be an Armor or Weapon entry, or `using` inherits fields from the wrong stat family."
+      # Observed in game (2026-09-11): a GameObjects node carrying
+      # only MapKey/Name/VisualTemplate reached the pak as an .lsf and the
+      # engine still did not load it (`Ext.Template.GetTemplate` nil,
+      # `bg3.template.exists` fail), while every template the engine has been
+      # seen to load — the vanilla dagger, the 2026-09-10 chest repro, the
+      # summoned-weapon recipe — carries Type, Stats and a ParentTemplateId.
+      # The parent stat's own RootTemplate becomes this template's
+      # ParentTemplateId, so the item inherits physics, equipment type and
+      # icon handling from the vanilla template its stats already `using`.
+      - path: fields.RootTemplate
+        matches: "^[0-9a-fA-F-]{36}$"
+        reason: "the parent must carry its own RootTemplate (a UUID) — it becomes the new template's ParentTemplateId, which the engine needs to load the node at all."
+        expose: parentRootTemplate
+  - type: index-ref
+    name: visualBankId
+    prompt: "Existing (project or vanilla) VisualBank Resource ID this item's RootTemplate should reuse."
+    lookup: { kind: guid, params: { uuid: "${input.visualBankId}" } }
+    requires:
+      - path: kind
+        matches: "^Resource$"
+        reason: "the given UUID must resolve to a Resource node, or the RootTemplate's VisualTemplate would point at a non-visual LSX node."
+      - path: region
+        matches: "^VisualBank$"
+        reason: "the given UUID must be a VisualBank Resource (region VisualBank), not a MaterialBank/TextureBank one, or the RootTemplate's VisualTemplate would point at the wrong bank kind."
+  - type: string
+    name: displayName
+    prompt: "Player-facing item name."
+  - type: string
+    name: description
+    prompt: "Tooltip description text."
+ids:
+  - name: rootTemplateUuid
+    slot: "roottemplate:${input.itemName}"
+    form: uuid
+    collision:
+      project: true
+      index: { kind: guid, param: uuid }
+  - name: display
+    slot: "display:${input.itemName}"
+    form: bg3-handle
+  - name: description
+    slot: "description:${input.itemName}"
+    form: bg3-handle
+  # The same two handles without the `;1` suffix, for the RootTemplate's
+  # TranslatedString attributes (same slot => same digest => same loca row).
+  - name: displayHandle
+    slot: "display:${input.itemName}"
+    form: bg3-handle-bare
+  - name: descriptionHandle
+    slot: "description:${input.itemName}"
+    form: bg3-handle-bare
+emits:
+  - op: ensure-dir
+    path: "Public/${project.identity.folder}/Stats/Generated/Data"
+  - op: ensure-dir
+    path: "Public/${project.identity.folder}/RootTemplates"
+  - op: insert-block
+    path: "Public/${project.identity.folder}/Stats/Generated/Data/${input.entryKind}.txt"
+    createIfMissing: "// ModWright-scaffolded ${input.entryKind} file.\n"
+    anchor: append
+    body: |
+      // ${project.today} - ModWright scaffold: ${input.itemName}, using parent ${input.parentStat}.
+      new entry "${input.itemName}"
+      type "${input.entryKind}"
+      using "${input.parentStat}"
+      data "RootTemplate" "${ids.rootTemplateUuid}"
+      data "Slot" "${input.slot}"
+  # One RootTemplate per file (not a shared _merged.lsx) sidesteps the
+  # missing "insert into an existing LSX region" op — see this file's header.
+  - op: write-text
+    path: "Public/${project.identity.folder}/RootTemplates/${input.itemName}.lsx"
+    body: |
+      <?xml version="1.0" encoding="UTF-8"?>
+      <save>
+        <version major="4" minor="8" revision="0" build="10"/>
+        <region id="Templates">
+          <node id="Templates">
+            <children>
+              <node id="GameObjects">
+                <attribute id="MapKey" type="FixedString" value="${ids.rootTemplateUuid}"/>
+                <attribute id="Name" type="LSString" value="${input.itemName}"/>
+                <attribute id="Type" type="FixedString" value="item"/>
+                <attribute id="ParentTemplateId" type="FixedString" value="${template.parentRootTemplate}"/>
+                <attribute id="Stats" type="FixedString" value="${input.itemName}"/>
+                <attribute id="VisualTemplate" type="FixedString" value="${input.visualBankId}"/>
+                <attribute id="Icon" type="FixedString" value="${input.itemName}_Icon"/>
+                <attribute id="DisplayName" type="TranslatedString" handle="${ids.displayHandle}" version="1"/>
+                <attribute id="Description" type="TranslatedString" handle="${ids.descriptionHandle}" version="1"/>
+              </node>
+            </children>
+          </node>
+        </region>
+      </save>
+  # Ensures the pak's build actually converts RootTemplates .lsx -> .lsf
+  # (this file's header note above); idempotent (`engine.ts`'s
+  # `mergeBuildSteps`), so scaffolding a second item never adds a second
+  # copy of this step, and `before` lands it ahead of
+  # `divine-create-package` (or a bare-string shorthand that expands to it,
+  # e.g. "pack-pak") whichever form the project's build
+  # already uses.
+  #
+  # `in: "${stage}"` is the *whole* stage root, not one stage id's own
+  # subtree (core/build/paths.ts's own header comment: `in` on this step
+  # normally names a bare stage id, resolved as `${stage}/<id>`; the bare
+  # `${stage}` token alone resolves to the stage root with no id segment at
+  # all) — deliberate, because a `patch-project` addition is static YAML and
+  # cannot know which id the project's own `stage` step happens to use
+  # (a real project may use "pack"; the schemaVersion-1 shorthand
+  # uses "stage"). `walk()` (core/fsutil.ts) recurses the whole tree either
+  # way, so the glob below is written `**/Public/**/...` — tolerant of
+  # whatever stage-id segment precedes `Public/` in the staged copy — rather
+  # than anchored to `Public/` the way a per-id `in` value could afford to
+  # be.
+  #
+  # `deleteSource: true` is set here and nowhere else. The step's own default
+  # is false (it converts in place, as it always has), because its default
+  # glob is the whole-stage `**/*.lsx` and every other `Public/<Mod>` folder's
+  # `.lsx` — Lists, Progressions, ClassDescriptions, GUI atlases — is read by
+  # the game as `.lsx`. This step's glob is narrowed to `RootTemplates`, the
+  # one folder where the loose `.lsx` is dead weight, so removing the staged
+  # copy matches exactly the configuration verified in game (convert,
+  # remove the `.lsx`, rebuild) and keeps the stale copy out of the pak.
+  - op: patch-project
+    add:
+      steps:
+        - step: divine-lsx-to-lsf
+          id: roottemplates-lsx-to-lsf
+          in: "${stage}"
+          glob: "**/Public/**/RootTemplates/*.lsx"
+          deleteSource: true
+          before: divine-create-package
+  - op: insert-block
+    path: "Public/${project.identity.folder}/Stats/Generated/TreasureTable.txt"
+    createIfMissing: "// ModWright TreasureTable, ModWright-scaffolded.\n"
+    anchor: append
+    body: |
+      new treasuretable "${project.identity.folder}_Treasure"
+      CanMerge 1
+      object category "I_${input.itemName}",1,0,0,0,0,0,0,0
+  - op: insert-loca-row
+    path: "Mods/${project.identity.folder}/Localization/English/${project.identity.folder}.xml"
+    handle: "${ids.display}"
+    text: "${input.displayName}"
+  - op: insert-loca-row
+    path: "Mods/${project.identity.folder}/Localization/English/${project.identity.folder}.xml"
+    handle: "${ids.description}"
+    text: "${input.description}"
+templates: []
+satisfies:
+  - bg3.items.stats-roottemplate-link
+  - bg3.items.roottemplate-visual-link
+  - bg3.items.visual-material-texture-chain
+  - bg3.items.parenttemplateid-type-match
+  - bg3.items.armor-weapon-fields
+  - bg3.items.treasuretable-i-prefix
+  - bg3.items.icon-mapkey-resolves
+  - bg3.items.dds-extension-case
+  - bg3.items.texturebank-srgb
+  - bg3.items.roottemplate-guid-attribute-type
+  - bg3.history.handle-form-per-field
+  - bg3.history.handle-defined-in-loca
+manual:
+  - title: Icon, visual and (for a Weapon) proficiency fields
+    steps:
+      - "Draw the ${input.itemName}_Icon art and register it in the item atlas (bg3.items.icon-mapkey-resolves warns until then)."
+      - "For a Weapon entry (this one is ${input.entryKind}), also add data \"Proficiency Group\" and data \"Weapon Properties\" to the new entry (bg3.items.armor-weapon-fields warns without them; there is no new base weapon type, so fake one by combining an existing group with Weapon Properties)."
+      - "To give ${input.itemName} its own recolor instead of reusing VisualBank ${input.visualBankId}'s appearance, add a mod-owned VisualBank/MaterialBank/TextureBank Resource chain under Content/Assets/Characters and repoint this RootTemplate's VisualTemplate at your new VisualBank ID."
+    expected: "The item spawns with a real icon, its own visual (recolored or reused), and (if a Weapon) a valid proficiency/properties pair."
+claim:
+  idSuffix: spawns-with-stats
+  claim: "${input.itemName} (using parent ${input.parentStat}) spawns with stats from its RootTemplate, a visible visual reused from VisualBank ${input.visualBankId}, and a treasure-table entry."
+testRows:
+  - gate: S-1
+    title: "Stat entry loads with expected fields"
+    expected: "bg3.stat.exists finds ${input.itemName}; bg3.stat.fields confirms RootTemplate/Slot match this scaffold's output (an Armor/Weapon stats object has no DisplayName/Description attribute — observed in game 2026-09-11; those live on the RootTemplate)."
+    manual: false
+    probes:
+      - kind: bg3.stat.exists
+        params: { name: "${input.itemName}" }
+      - kind: bg3.stat.fields
+        params: { name: "${input.itemName}", fields: [RootTemplate, Slot] }
+  # A separate row, not a third probe on S-1. The kind is attested (its own
+  # bridge run, 2026-09-10), so the row is automated, but
+  # it stays its own row because bg3.stat.exists alone cannot tell a real
+  # RootTemplate from a loose, engine-ignored `.lsx` (this file's header
+  # note) and a template verdict should not drag the stats verdict down with
+  # it — exactly what was observed in game (2026-09-11): this row failed
+  # (`present: false`) while bg3.stat.exists passed on the same item.
+  - gate: S-1.1
+    title: "RootTemplate resolves in the engine"
+    expected: "bg3.template.exists confirms Ext.Template.GetTemplate(\"${ids.rootTemplateUuid}\") returns the template (present: true, name ${input.itemName}), not nil — a bg3.stat.exists pass alone does not prove the template this scaffold wrote actually reached the engine (it does not, unless the divine-lsx-to-lsf step this scaffold adds converts it)."
+    manual: false
+    probes:
+      - kind: bg3.template.exists
+        params:
+          mapKey: "${ids.rootTemplateUuid}"
+  - gate: S-2
+    title: "Visual renders, not the default fallback"
+    expected: "A human confirms TemplateAddTo/spawn shows the reused VisualBank ${input.visualBankId} visual, not the invisible/default fallback, and the icon/tooltip render."
+    manual: true
+    probeKinds: []
+evidence: ["ModWright research"]

package/scaffolds/baldursgate3/new-mod.yaml

@@ -0,0 +1,174 @@
+# new-mod (BG3). Writes the
+# standard skeleton: meta.lsx, ScriptExtender/Config.json,
+# Localization/English/<Mod>.xml, and the Public/<Mod> subtree every stats/
+# progression/item scaffold expects to already exist. Version64 is derived
+# from the project's own declared version (project.version64, computed by
+# the engine — see engine.ts's computeVersion64), not re-specified here, so
+# meta.lsx and modwright.json never disagree on major/minor/revision.
+id: baldursgate3.new-mod
+game: baldursgate3
+title: New BG3 mod (meta.lsx, Config.json, Localization)
+summary: Write meta.lsx, ScriptExtender/Config.json and an empty Localization/English/<Mod>.xml, plus the Public/<Mod> subtree, and declare the BG3 Script Extender dependency.
+modTypes: [packaging]
+needs: {}
+inputs:
+  - type: string
+    name: folder
+    prompt: Module folder name (Mods/<folder>, Public/<folder>).
+    pattern: "^[A-Za-z][A-Za-z0-9_]*$"
+  - type: string
+    name: displayName
+    prompt: Display name shown in the in-game mod manager.
+  - type: string
+    name: author
+    prompt: Author name.
+    default: "Unknown"
+  - type: string
+    name: description
+    prompt: One-line mod description.
+    default: ""
+  - type: string
+    name: tags
+    prompt: Comma-separated Larian tag(s), e.g. "Class".
+    default: "Adventure"
+ids:
+  - name: moduleUuid
+    slot: "module-uuid:${input.folder}"
+    form: uuid
+    collision:
+      project: true
+      loadOrder: true
+      index: { kind: guid, param: uuid }
+emits:
+  - op: ensure-dir
+    path: "Mods/${input.folder}/ScriptExtender"
+  - op: ensure-dir
+    path: "Mods/${input.folder}/Localization/English"
+  - op: ensure-dir
+    path: "Public/${input.folder}/ActionResourceDefinitions"
+  - op: ensure-dir
+    path: "Public/${input.folder}/ClassDescriptions"
+  - op: ensure-dir
+    path: "Public/${input.folder}/Lists"
+  - op: ensure-dir
+    path: "Public/${input.folder}/Progressions"
+  - op: ensure-dir
+    path: "Public/${input.folder}/RootTemplates"
+  - op: ensure-dir
+    path: "Public/${input.folder}/Stats/Generated/Data"
+  - op: ensure-dir
+    path: "Public/${input.folder}/Tags"
+  - op: ensure-dir
+    path: "Public/${input.folder}/GUI"
+  # meta.lsx: BOM (bg3.history.no-bom exempts it by name — Larian's own
+  # Toolkit writes one), Version64 from the project's own declared version.
+  - op: write-text
+    path: "Mods/${input.folder}/meta.lsx"
+    bom: true
+    body: |
+      <?xml version="1.0" encoding="utf-8"?>
+      <save>
+        <version major="4" minor="8" revision="0" build="500" />
+        <region id="Config">
+          <node id="root">
+            <children>
+              <node id="Conflicts" />
+              <node id="Dependencies" />
+              <node id="ModuleInfo">
+                <attribute id="Author" type="LSString" value="${input.author}" />
+                <attribute id="CharacterCreationLevelName" type="FixedString" value="" />
+                <attribute id="Description" type="LSString" value="${input.description}" />
+                <attribute id="FileSize" type="uint64" value="0" />
+                <attribute id="Folder" type="LSString" value="${input.folder}" />
+                <attribute id="LobbyLevelName" type="FixedString" value="" />
+                <attribute id="MD5" type="LSString" value="" />
+                <attribute id="MainMenuBackgroundVideo" type="FixedString" value="" />
+                <attribute id="MenuLevelName" type="FixedString" value="" />
+                <attribute id="Name" type="FixedString" value="${input.displayName}" />
+                <attribute id="NumPlayers" type="uint8" value="4" />
+                <attribute id="PhotoBooth" type="FixedString" value="" />
+                <attribute id="PublishHandle" type="uint64" value="0" />
+                <attribute id="StartupLevelName" type="FixedString" value="" />
+                <attribute id="Tags" type="LSString" value="${input.tags}" />
+                <attribute id="Type" type="FixedString" value="Add-on" />
+                <attribute id="UUID" type="FixedString" value="${ids.moduleUuid}" />
+                <attribute id="Version64" type="int64" value="${project.version64}" />
+                <children>
+                  <node id="PublishVersion">
+                    <attribute id="Version64" type="int64" value="${project.version64}" />
+                  </node>
+                  <node id="Scripts" />
+                  <node id="TargetModes">
+                    <children>
+                      <node id="Target">
+                        <attribute id="Object" type="FixedString" value="Story" />
+                      </node>
+                    </children>
+                  </node>
+                </children>
+              </node>
+            </children>
+          </node>
+        </region>
+      </save>
+  - op: write-text
+    path: "Mods/${input.folder}/ScriptExtender/Config.json"
+    body: |
+      {
+          "RequiredVersion": 21,
+          "ModTable": "${input.folder}",
+          "FeatureFlags": ["Lua"]
+      }
+  - op: write-text
+    path: "Mods/${input.folder}/Localization/English/${input.folder}.xml"
+    body: |
+      <?xml version="1.0" encoding="utf-8"?>
+      <contentList>
+      </contentList>
+  - op: insert-xl-entry
+    path: "modwright.json"
+    pointer: identity.uuid
+    value: "${ids.moduleUuid}"
+  - op: insert-xl-entry
+    path: "modwright.json"
+    pointer: identity.folder
+    value: "${input.folder}"
+  - op: patch-project
+    add:
+      dependencies:
+        - id: bg3-script-extender
+          kind: loader
+          minVersion: "21"
+          url: "https://github.com/Norbyte/bg3se"
+          notes: "RequiredVersion 21 pinned in ScriptExtender/Config.json."
+templates: []
+satisfies:
+  - bg3.progression.meta-version64
+  - bg3.history.no-bom
+  - bg3.history.se-config-shape
+  - bg3.history.stale-same-uuid-pak
+  - bg3.history.external-guid-load-order
+  - bg3.history.loca-no-xml-comments
+manual:
+  - title: Add real content
+    steps:
+      - "Run new-spell/new-passive/new-status to fill Stats/Generated/Data."
+      - "Register the module in the game's modsettings.lsx load order once tested."
+    expected: "The module loads in-game and passes validate with no blocking findings."
+claim:
+  idSuffix: mod-loads
+  claim: "${input.folder} (UUID ${ids.moduleUuid}) is a loadable BG3 module with a valid meta.lsx and Script Extender config."
+testRows:
+  - gate: S-1
+    title: "Module enumerates and loads"
+    expected: "bg3.mod.active reports the module UUID loaded, matching the declared Version64."
+    manual: false
+    probes:
+      - kind: bg3.mod.active
+        params: { uuid: "${ids.moduleUuid}" }
+  - gate: S-2
+    title: "Menu enumeration"
+    expected: "The mod appears in the in-game mod manager under its display name."
+    manual: true
+    probeKinds: [bg3.client.loaded]
+evidence: ["ModWright research"]

package/scaffolds/baldursgate3/new-passive.yaml

@@ -0,0 +1,100 @@
+# new-passive (BG3). Same
+# shape as new-spell, but PassiveData carries
+# BoostContext including OnCreate, so the
+# `bg3.history.boostcontext-initial-event` "initial-event" failure mode is
+# a passive-specific concern, unlike SpellData.
+id: baldursgate3.new-passive
+game: baldursgate3
+title: New BG3 passive (PassiveData entry)
+summary: Append a PassiveData entry to Passive.txt with a vanilla `using` parent, BoostContext including OnCreate, and DisplayName/Description loca rows.
+modTypes: [dialogue]
+needs: { index: true }
+inputs:
+  - type: string
+    name: entryName
+    prompt: "Full stats entry name, e.g. MyMod_QuickReflexes."
+    pattern: "^[A-Za-z][A-Za-z0-9_]*$"
+  - type: index-ref
+    name: parent
+    prompt: "Vanilla (or project) PassiveData entry to `using`."
+    lookup: { kind: stat, params: { name: "${input.parent}" } }
+    requires:
+      - path: type
+        matches: "^PassiveData$"
+        reason: "the parent must be a PassiveData entry, or `using` inherits fields from the wrong stat family."
+  - type: string
+    name: displayName
+    prompt: "Player-facing passive name."
+  - type: string
+    name: description
+    prompt: "Tooltip description text."
+  - type: string
+    name: boosts
+    prompt: "Boosts string (semicolon-separated boost functors), or leave blank for a display-only passive."
+    default: ""
+ids:
+  - name: display
+    slot: "display:${input.entryName}"
+    form: bg3-handle
+  - name: description
+    slot: "description:${input.entryName}"
+    form: bg3-handle
+emits:
+  - op: insert-block
+    path: "Public/${project.identity.folder}/Stats/Generated/Data/Passive.txt"
+    createIfMissing: "// ModWright-scaffolded passive file.\n"
+    anchor: append
+    body: |
+      // ${project.today} - ModWright scaffold: ${input.entryName}, using parent ${input.parent}.
+      new entry "${input.entryName}"
+      type "PassiveData"
+      using "${input.parent}"
+      data "Icon" "${input.entryName}_Icon"
+      data "DisplayName" "${ids.display}"
+      data "Description" "${ids.description}"
+      data "Boosts" "${input.boosts}"
+      data "BoostContext" "OnCreate"
+  - op: insert-loca-row
+    path: "Mods/${project.identity.folder}/Localization/English/${project.identity.folder}.xml"
+    handle: "${ids.display}"
+    text: "${input.displayName}"
+  - op: insert-loca-row
+    path: "Mods/${project.identity.folder}/Localization/English/${project.identity.folder}.xml"
+    handle: "${ids.description}"
+    text: "${input.description}"
+templates: []
+satisfies:
+  - bg3.history.spellanimation-present
+  - bg3.history.boostcontext-initial-event
+  - bg3.history.context-qualifier-validity
+  - bg3.history.reference-integrity
+  - bg3.history.handle-form-per-field
+  - bg3.history.handle-defined-in-loca
+  - bg3.history.islinkedspellcontainer-links
+  - bg3.history.spellid-enumeration-drift
+  - bg3.history.loca-no-xml-comments
+manual:
+  - title: Icon and progression
+    steps:
+      - "Draw the ${input.entryName}_Icon art and register it in the spell atlas."
+      - "Grant ${input.entryName} via a Progression's PassivesAdded if it should be automatic."
+    expected: "The passive shows a real icon and its boost is observable in-game."
+claim:
+  idSuffix: applies
+  claim: "${input.entryName} applies its boost(s) once granted, inheriting fields from ${input.parent}."
+testRows:
+  - gate: S-1
+    title: "Stat entry loads with expected fields"
+    expected: "bg3.stat.exists finds ${input.entryName}; bg3.stat.fields confirms BoostContext/Boosts/DisplayName/Description."
+    manual: false
+    probes:
+      - kind: bg3.stat.exists
+        params: { name: "${input.entryName}" }
+      - kind: bg3.stat.fields
+        params: { name: "${input.entryName}", fields: [BoostContext, Boosts, DisplayName, Description] }
+  - gate: S-2
+    title: "Icon and tooltip render"
+    expected: "The passive's card shows the drawn icon and correct tooltip text in-game."
+    manual: true
+    probeKinds: []
+evidence: ["ModWright research"]

package/scaffolds/baldursgate3/new-project.yaml

@@ -0,0 +1,118 @@
+# new-project (Baldur's Gate 3).
+# The one scaffold that runs before a modwright.json exists: writes the
+# skeleton every other BG3 scaffold assumes (the two source trees, the v2
+# project file, ledger/decisions.yaml). tests/authored.yaml and
+# ledger/claims.yaml are written by the engine's own automatic per-apply
+# steps, not by an emit here.
+id: baldursgate3.new-project
+game: baldursgate3
+title: New BG3 mod project
+summary: Scaffold a fresh ModWright project for a Baldur's Gate 3 mod — modwright.json (schemaVersion 2), the Mods/Public source trees, .gitignore, and ledger/decisions.yaml.
+modTypes: [packaging]
+needs: {}
+inputs:
+  - type: string
+    name: name
+    prompt: Mod name (also used as the Mods/<name> and Public/<name> folder name).
+    pattern: "^[A-Za-z][A-Za-z0-9_]*$"
+  - type: string
+    name: version
+    prompt: Initial version (semver-ish, major.minor.revision).
+    default: "0.1.0"
+  - type: string
+    name: author
+    prompt: Author name.
+    default: "Unknown"
+  # A project can keep its
+  # LSLib divine path as a toolchain override in modwright.json; a fresh
+  # project on the same machine needs the same line or its first build
+  # cannot find the tool. Empty means "the locator's own candidates" and
+  # writes nothing.
+  - type: string
+    name: divine
+    prompt: "Absolute path to LSLib's Divine.exe when it is not where check_toolchain looks (written as the project's toolchain override; leave empty to rely on the locator)."
+    default: ""
+ids:
+  - name: moduleUuid
+    slot: "module-uuid:${input.name}"
+    form: uuid
+    collision:
+      project: true
+      index: { kind: guid, param: uuid }
+emits:
+  - op: ensure-dir
+    path: "Mods/${input.name}"
+  - op: ensure-dir
+    path: "Public/${input.name}/Stats/Generated/Data"
+  - op: ensure-dir
+    path: "Public/${input.name}/Localization/English"
+  - op: write-text
+    path: ".gitignore"
+    ifExists: skip
+    # Two files under .modwright are worth tracking, so a reviewer
+    # reads them in a clean checkout: suppressions.json and
+    # templates/manifest.json. A bare `.modwright/` hides both (a
+    # hand-written ignore often un-hides only the first). git cannot re-include
+    # a file inside an ignored directory, so the templates folder is
+    # re-included and its other contents ignored again.
+    body: |
+      .modwright/*
+      !.modwright/suppressions.json
+      !.modwright/templates/
+      .modwright/templates/*
+      !.modwright/templates/manifest.json
+      build/
+      *.pak
+      .modwright-build-manifest.json
+  - op: write-text
+    path: "ledger/decisions.yaml"
+    body: |
+      decisions: []
+  - op: write-text
+    path: "modwright.json"
+    body: |
+      {
+        "schemaVersion": 2,
+        "name": "${input.name}",
+        "game": "baldursgate3",
+        "version": "${input.version}",
+        "authors": ["${input.author}"],
+        "identity": {
+          "uuid": "${ids.moduleUuid}",
+          "folder": "${input.name}"
+        },
+        "sources": [
+          { "id": "mods", "path": "Mods/${input.name}", "kind": "mods" },
+          { "id": "public", "path": "Public/${input.name}", "kind": "public" }
+        ]
+      }
+  # The LSLib divine override, written the way a project keeps
+  # its own; the engine merges it into the modwright.json written just above, and an
+  # empty input adds no key at all.
+  - op: patch-project
+    add:
+      toolchain:
+        divine: "${input.divine}"
+templates: []
+# Nothing is satisfied directly: the one real postcondition is that
+# validate reports no *unmet-needs* skip among project-only rules. A
+# project-target rule with needs:{project:true} always evaluates (the
+# {kind:"project"} target always exists), so this trivially "ran" with zero
+# findings against the still-empty source trees.
+satisfies: [bg3.progression.meta-version64]
+manual:
+  - title: Populate the mod
+    steps:
+      - "Add real content under Mods/<name> (meta.lsx, ScriptExtender, Localization) and Public/<name> (Stats, RootTemplates)."
+      - "Run the new-mod scaffold next to fill in meta.lsx and ScriptExtender/Config.json."
+    expected: "validate reports the project's own structural rules clean once real content exists."
+claim:
+  idSuffix: scaffolded
+  claim: "${input.name} is scaffolded as a ModWright project with a schemaVersion 2 modwright.json and a fresh module UUID."
+testRows:
+  - gate: S-0
+    title: "Project loads"
+    expected: "validate loads modwright.json with no schema errors and no unmet-needs skip among project-only rules."
+    manual: true
+    probeKinds: []
+evidence: ["ModWright research"]