modwright 0.1.0

package/scaffolds/baldursgate3/new-quest-stub.yaml

@@ -0,0 +1,159 @@
+# new-quest-stub (BG3). A
+# flat (non-nested) goal: INIT sets a DB fact, KB reacts to it with a
+# QuestUpdate into a fresh top-level journal quest, EXIT clears the fact.
+#
+# Scope note: a full quest stub would also include
+# "one dialogue greeting node". A real dialogue node is a Story
+# Editor-authored .lsj that ships as the binary-derived intermediate of a
+# vanilla DialogsBinary .lsf (bg3.story.dialogue-source-version's own
+# appliesTo comment) — there is no plain-text authoring convention for it at
+# all, and producing one needs the `divine` toolchain this scaffold's
+# `needs` deliberately does not require. This scaffold stops at the goal,
+# the journal and a Flags/<uuid>.lsx stub; wiring an actual dialogue node is
+# left to the manual checklist below, as with other creative work.
+id: baldursgate3.new-quest-stub
+game: baldursgate3
+title: New BG3 quest stub (goal + journal)
+summary: Write a flat Osiris goal (INIT/KB/EXIT) that QuestUpdates a fresh top-level journal quest, plus a Flags/<uuid>.lsx stub and loca rows.
+modTypes: [quest, dialogue]
+needs: { index: true }
+inputs:
+  - type: string
+    name: goalName
+    prompt: "Goal file name, Act_Region_Situation convention (e.g. Act1_Riverside_MyQuestIntro)."
+    pattern: "^[A-Za-z0-9]+(_[A-Za-z0-9]+){2,}$"
+  - type: string
+    name: journalTitle
+    prompt: "Journal quest category display text."
+  - type: string
+    name: firstEntryText
+    prompt: "First journal entry display text."
+ids:
+  - name: questId
+    slot: "${project.identity.folder}_${input.goalName}_Quest"
+    form: map-key
+  - name: entryId
+    slot: "${project.identity.folder}_${input.goalName}_Start"
+    form: map-key
+  - name: startedDb
+    slot: "DB_${project.identity.folder}_${input.goalName}_Started"
+    form: map-key
+  - name: flagUuid
+    slot: "flag:${input.goalName}"
+    form: uuid
+  - name: journalTitleHandle
+    slot: "journal-title:${input.goalName}"
+    form: bg3-handle
+  - name: journalEntryHandle
+    slot: "journal-entry:${input.goalName}"
+    form: bg3-handle
+emits:
+  # Under Mods/<folder>/Story/... — a mod's Story tree ships inside its own
+  # module folder (like meta.lsx and ScriptExtender), not at the project
+  # root, and has to sit under a declared project source for `validate` to
+  # ever look at it at all (`listFiles()` only walks declared sources).
+  - op: ensure-dir
+    path: "Mods/${project.identity.folder}/Story/RawFiles/Goals"
+  - op: ensure-dir
+    path: "Mods/${project.identity.folder}/Story/Journals"
+  - op: ensure-dir
+    path: "Public/${project.identity.folder}/Flags"
+  - op: write-text
+    path: "Mods/${project.identity.folder}/Story/RawFiles/Goals/${input.goalName}.txt"
+    body: |
+      INIT
+      ${ids.startedDb}(1)
+
+      KB
+      IF
+      ${ids.startedDb}(_)
+      THEN
+      QuestUpdate("${ids.questId}","${ids.entryId}")
+
+      EXIT
+      SysClear(${ids.startedDb})
+  - op: write-text
+    path: "Mods/${project.identity.folder}/Story/Journals/${input.goalName}.lsx"
+    body: |
+      <?xml version="1.0" encoding="utf-8"?>
+      <save>
+        <version major="4" minor="0" revision="9" build="200" />
+        <region id="Journal">
+          <node id="JournalRoot">
+            <children>
+              <node id="Category">
+                <attribute id="Name" type="FixedString" value="${ids.questId}" />
+                <attribute id="DisplayName" type="TranslatedString" handle="${ids.journalTitleHandle}" version="1" />
+                <children>
+                  <node id="Entry">
+                    <attribute id="ID" type="FixedString" value="${ids.entryId}" />
+                    <attribute id="Text" type="TranslatedString" handle="${ids.journalEntryHandle}" version="1" />
+                  </node>
+                </children>
+              </node>
+            </children>
+          </node>
+        </region>
+      </save>
+  - op: write-text
+    path: "Public/${project.identity.folder}/Flags/${ids.flagUuid}.lsx"
+    body: |
+      <?xml version="1.0" encoding="utf-8"?>
+      <save>
+        <version major="4" minor="0" revision="9" build="200" />
+        <region id="Flag">
+          <node id="Flag">
+            <attribute id="UUID" type="FixedString" value="${ids.flagUuid}" />
+          </node>
+        </region>
+      </save>
+  - op: insert-loca-row
+    path: "Mods/${project.identity.folder}/Localization/English/${project.identity.folder}.xml"
+    handle: "${ids.journalTitleHandle}"
+    text: "${input.journalTitle}"
+  - op: insert-loca-row
+    path: "Mods/${project.identity.folder}/Localization/English/${project.identity.folder}.xml"
+    handle: "${ids.journalEntryHandle}"
+    text: "${input.firstEntryText}"
+templates: []
+satisfies:
+  - bg3.story.osiris-section-structure
+  - bg3.story.osiris-naming-convention
+  - bg3.story.osiris-symbol-defined
+  - bg3.story.goal-parent-completes
+  - bg3.story.questupdate-parent-id
+  - bg3.story.quest-entry-exists
+  - bg3.story.questadd-questclose-discouraged
+  # Not listed: bg3.story.dialogue-flag-guid-resolves. It needs a dialogue
+  # .lsj that references the flag, which this scaffold leaves to the manual
+  # step, so on a real project it only ever skipped and the apply reported
+  # unclean (observed in game 2026-09-11).
+  - bg3.history.handle-defined-in-loca
+manual:
+  - title: Wire the dialogue and trigger
+    steps:
+      - "Author the actual dialogue greeting node in the Story Editor and repoint its DialogBank SourceFile per the namespaced pattern."
+      - "Fire ${ids.startedDb}(1) from whichever trigger (an interaction, a region trigger) should start this quest."
+      - "Confirm the Flags/${ids.flagUuid}.lsx UUID is referenced from the dialogue node that should set it."
+    expected: "The trigger sets the DB fact, the goal's KB rule fires QuestUpdate, and the journal shows the new entry."
+claim:
+  idSuffix: fires
+  claim: "Triggering ${ids.startedDb} completes the ${input.goalName} goal's KB rule and unlocks the ${ids.entryId} journal entry."
+testRows:
+  - gate: G-1
+    title: "Goal DB fact and journal entry"
+    # bg3.event.watch/bg3.osiris.health are attested kinds, but both need an
+    # armed observe window straddling the manual trigger step above (fire
+    # ${ids.startedDb} from whichever interaction/region trigger a human
+    # wires up) — there is no scaffold-time input to arm ahead of a human
+    # action that has not happened yet, so this stays a manual row: a person
+    # arms both probes, fires the trigger, then reads the results by hand.
+    expected: "A human arms bg3.event.watch/bg3.osiris.health, fires the trigger, and confirms ${ids.startedDb} fired with no Osiris degradation."
+    manual: true
+    probeKinds: [bg3.event.watch, bg3.osiris.health]
+  - gate: G-2
+    title: "Dialogue and journal review"
+    expected: "The authored dialogue node fires and the journal query shows the entry unlocked."
+    manual: true
+    probeKinds: []
+evidence: ["ModWright research"]

package/scaffolds/baldursgate3/new-spell.yaml

@@ -0,0 +1,102 @@
+# new-spell (BG3). Appends one "new entry" block to Spell_<Type>.txt after a
+# dated rationale comment and two loca rows for DisplayName/Description. No SpellAnimation is
+# written — the parent (via `using`) is expected to supply one, as is
+# usual for a Target-type spell inheriting from a vanilla parent.
+id: baldursgate3.new-spell
+game: baldursgate3
+title: New BG3 spell (SpellData entry)
+summary: Append a SpellData entry to Spell_<Type>.txt with a vanilla `using` parent, plus DisplayName/Description loca rows.
+modTypes: [dialogue]
+needs: { index: true }
+inputs:
+  - type: string
+    name: entryName
+    prompt: "Full stats entry name, e.g. MyMod_ShortCircuit."
+    pattern: "^[A-Za-z][A-Za-z0-9_]*$"
+  - type: enum
+    name: spellType
+    prompt: "SpellType (also names the Spell_<Type>.txt file)."
+    values: [Target, Projectile, Shout]
+  - type: index-ref
+    name: parent
+    prompt: "Vanilla (or project) SpellData entry to `using`."
+    lookup: { kind: stat, params: { name: "${input.parent}" } }
+    requires:
+      - path: type
+        matches: "^SpellData$"
+        reason: "the parent must be a SpellData entry, or `using` inherits fields from the wrong stat family."
+  - type: string
+    name: level
+    prompt: "Spell level (0 for cantrip)."
+    default: "1"
+  - type: string
+    name: displayName
+    prompt: "Player-facing spell name."
+  - type: string
+    name: description
+    prompt: "Tooltip description text."
+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/Spell_${input.spellType}.txt"
+    createIfMissing: "// ModWright-scaffolded spell file.\n"
+    anchor: append
+    body: |
+      // ${project.today} - ModWright scaffold: ${input.entryName}, using parent ${input.parent}.
+      new entry "${input.entryName}"
+      type "SpellData"
+      data "SpellType" "${input.spellType}"
+      using "${input.parent}"
+      data "Icon" "${input.entryName}_Icon"
+      data "Level" "${input.level}"
+      data "UseCosts" "ActionPoint:1;SpellSlotsGroup:1:1:${input.level}"
+      data "DisplayName" "${ids.display}"
+      data "Description" "${ids.description}"
+  - 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.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."
+      - "Add ${input.entryName} to a SpellList or Progression's AddSpells/SelectSpells if the parent does not already grant it."
+    expected: "The spell shows a real icon and is grantable in character creation / level-up."
+claim:
+  idSuffix: applies
+  claim: "Casting ${input.entryName} applies the effect inherited from ${input.parent} for a target."
+testRows:
+  - gate: S-1
+    title: "Stat entry loads with expected fields"
+    expected: "bg3.stat.exists finds ${input.entryName}; bg3.stat.fields confirms SpellType/UseCosts/DisplayName/Description."
+    manual: false
+    probes:
+      - kind: bg3.stat.exists
+        params: { name: "${input.entryName}" }
+      - kind: bg3.stat.fields
+        params: { name: "${input.entryName}", fields: [SpellType, UseCosts, DisplayName, Description] }
+  - gate: S-2
+    title: "Icon and tooltip render"
+    expected: "The spell's card shows the drawn icon and correct tooltip text in-game."
+    manual: true
+    probeKinds: []
+evidence: ["ModWright research"]

package/scaffolds/baldursgate3/new-status.yaml

@@ -0,0 +1,119 @@
+# new-status (BG3). Same
+# shape as new-spell/new-passive, targeting Status_<GROUP>.txt.
+#
+# Observed in game (2026-09-11): a child
+# status inherits its parent's StackId through `using`, so the scaffolded
+# status (parent BLESS) was replaced the moment BLESS was applied; the entry
+# now restates StackId as its own name. The same launch showed the old
+# "DisableCombatLog" spelling ignored by the engine (the status still hit the
+# combat log; working entries spell it DisableCombatlog), so the
+# flags are an input with the engine's spelling, empty (visible) by default.
+id: baldursgate3.new-status
+game: baldursgate3
+title: New BG3 status (StatusData entry)
+summary: Append a StatusData entry to Status_<GROUP>.txt with a vanilla `using` parent, plus DisplayName/Description loca rows.
+modTypes: [dialogue]
+needs: { index: true }
+inputs:
+  - type: string
+    name: entryName
+    prompt: "Full stats entry name, e.g. MYMOD_SHOCKED."
+    pattern: "^[A-Za-z][A-Za-z0-9_]*$"
+  - type: enum
+    name: group
+    prompt: "Status group (also names the Status_<GROUP>.txt file)."
+    values: [BOOST, INCAPACITATED]
+  - type: index-ref
+    name: parent
+    prompt: "Vanilla (or project) StatusData entry to `using`."
+    lookup: { kind: stat, params: { name: "${input.parent}" } }
+    requires:
+      - path: type
+        matches: "^StatusData$"
+        reason: "the parent must be a StatusData entry, or `using` inherits fields from the wrong stat family."
+  - type: string
+    name: displayName
+    prompt: "Player-facing status name."
+  - type: string
+    name: description
+    prompt: "Tooltip description text."
+  - type: string
+    name: turns
+    prompt: "Default duration in turns (informational; wired via the caller's own functors)."
+    default: "1"
+  - type: string
+    name: statusPropertyFlags
+    prompt: "StatusPropertyFlags, ';'-separated (engine spelling: DisableOverhead, DisableCombatlog, DisablePortraitIndicator, IgnoreResting). Empty keeps the status visible."
+    pattern: "^[A-Za-z;]*$"
+    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/Status_${input.group}.txt"
+    createIfMissing: "// ModWright-scaffolded status file.\n"
+    anchor: append
+    body: |
+      // ${project.today} - ModWright scaffold: ${input.entryName}, using parent ${input.parent}.
+      new entry "${input.entryName}"
+      type "StatusData"
+      using "${input.parent}"
+      data "Icon" "${input.entryName}_Icon"
+      data "DisplayName" "${ids.display}"
+      data "Description" "${ids.description}"
+      data "StackId" "${input.entryName}"
+      data "StatusPropertyFlags" "${input.statusPropertyFlags}"
+  - 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 application
+    steps:
+      - "Draw the ${input.entryName}_Icon art and register it in the spell atlas."
+      - "Wire ApplyStatus(${input.entryName}, ...) into whichever spell/passive applies it, with a real duration for ${input.turns} turns."
+    expected: "The status applies and its icon/tooltip render correctly in-game."
+claim:
+  idSuffix: applies
+  claim: "ApplyStatus(${input.entryName}, ...) applies the effect inherited 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 DisplayName/Description."
+    manual: false
+    probes:
+      - kind: bg3.stat.exists
+        params: { name: "${input.entryName}" }
+      - kind: bg3.stat.fields
+        params: { name: "${input.entryName}", fields: [DisplayName, Description] }
+  - gate: S-2
+    title: "Status apply confirmed in-game"
+    # bg3.entity.status is attested by the registry, but it needs a live
+    # entity's own guid to check against — a fact only a human picking a
+    # target in a real session has, never something this scaffold's own
+    # inputs supply — so this stays a manual row (a person runs
+    # bg3.entity.status by hand via bridge arm/poll after ApplyStatus).
+    expected: "A human confirms bg3.entity.status (run by hand, no scaffold-known guid) reports the status active on a target after ApplyStatus."
+    manual: true
+    probeKinds: [bg3.entity.status]
+evidence: ["ModWright research"]

package/scaffolds/baldursgate3/sequences/subclass-kit.yaml

@@ -0,0 +1,50 @@
+# subclass-kit (Baldur's Gate 3) — the authoring sequence for a subclass kit
+# (a monk subclass with its armor and a polearm): the project, a passive and a spell, two items, and the
+# injection that puts the passive and spell on the target list. The
+# injection step carries the entry names the two earlier steps were given.
+id: baldursgate3.subclass-kit
+game: baldursgate3
+title: Subclass kit (passive, spell, armor, weapon, injection)
+summary: Project, a passive and a spell with loca rows, an armor and a weapon with RootTemplates, and the class injection that grants the passive and spell.
+modType: subclass
+inputs:
+  - name: modName
+    prompt: "Mod name, used for the project and its Mods/<name> and Public/<name> folders, e.g. MyMonkMod."
+steps:
+  - id: project
+    scaffold: baldursgate3.new-project
+    title: The project file and source trees
+    skipIf: project-exists
+    inputs:
+      name: "${sequence.modName}"
+  - id: passive
+    scaffold: baldursgate3.new-passive
+    title: The subclass's signature passive
+  - id: spell
+    scaffold: baldursgate3.new-spell
+    title: The subclass's signature spell
+  - id: armor
+    scaffold: baldursgate3.new-item
+    title: The armor item
+    inputs:
+      entryKind: Armor
+    assets:
+      - name: look
+        prompt: "The armor's look: an existing VisualBank Resource ID to reuse (lookup kind guid on the vanilla index for a vanilla one, or the project's own), and the icon atlas entry. Give the VisualBank id here."
+        inputs: [visualBankId]
+  - id: weapon
+    scaffold: baldursgate3.new-item
+    title: The weapon item (a naginata is a reskinned polearm)
+    inputs:
+      entryKind: Weapon
+    assets:
+      - name: look
+        prompt: "The weapon's look: an existing VisualBank Resource ID to reuse (a vanilla polearm's, from lookup kind guid), and the icon atlas entry. Give the VisualBank id here."
+        inputs: [visualBankId]
+  - id: injection
+    scaffold: baldursgate3.new-class-injection
+    title: The injection that grants the passive and spell to the target list
+    inputs:
+      injectedSpells: "${steps.spell.inputs.entryName}"
+      injectedPassives: "${steps.passive.inputs.entryName}"
+evidence: []

package/scaffolds/cyberpunk2077/edit-tweak.yaml

@@ -0,0 +1,70 @@
+# edit-tweak (Cyberpunk 2077) — the target-side registration a quickhack
+# needs on an existing record. Appends or sets
+# flats on an EXISTING TweakDB record, in place: `RecordName: { flats }` with
+# no `$base`/`$type` is TweakXL's third record form — it MODIFIES the named
+# record rather than creating one. `new-tweak` cannot write it (its recordName
+# collision check refuses a record that already exists — the exact opposite of
+# what an edit needs), so this is a separate scaffold rather than a third
+# new-tweak mode: overloading one recordName input with both "must not exist"
+# (create) and "must exist" (edit) is what the two scaffolds keep apart.
+#
+# recordName is an `index-ref`, so the engine verifies the target actually
+# resolves in the vanilla index before an edit is written to it (a typo would
+# otherwise make TweakXL create a stray record). That also scopes this scaffold
+# to VANILLA records — a project record just authored is not in the vanilla
+# index; edit those by hand in the same file.
+#
+# The quickhack chain uses it to register the hack on NPC hack lists: the game
+# offers a hack on an NPC only when that NPC's `objectActions` names it (matched
+# by actionName), and human/mechanical NPCs inherit their list from
+# Character.Interactable_NPC_Base / Character.Mechanical_NPC_Base.
+id: cyberpunk2077.edit-tweak
+game: cyberpunk2077
+title: Edit an existing Cyberpunk 2077 TweakDB record
+summary: Append or set flats on an existing vanilla TweakDB record, in place — the base-less/type-less TweakXL modify form new-tweak cannot write.
+modTypes: [gameplay-tweak, quickhack, weapon, item, loot]
+needs: { index: true }
+inputs:
+  - type: path
+    name: file
+    prompt: "Destination .yaml under a project source of kind \"tweaks\" (created if it does not yet exist)."
+    mustExist: false
+  - type: index-ref
+    name: recordName
+    prompt: "The EXISTING vanilla record to edit, e.g. Character.Interactable_NPC_Base — verified to resolve in the vanilla index before the edit is written."
+    lookup: { kind: record, params: { name: "${input.recordName}" } }
+    requires: []
+  - type: string
+    name: flats
+    prompt: "The flats to append or set on the record, as YAML (e.g. \"objectActions:\\n  - !append QuickHack.MyHack\"). Indentation is normalized to nest under the record."
+    default: ""
+    reindent: 2
+ids: []
+emits:
+  # No $base/$type line: a record block with only flats modifies the existing
+  # record. `${input.flats}` is normalized to 2-space indent (reindent) so it
+  # nests under the record name.
+  - op: insert-block
+    path: "${input.file}"
+    createIfMissing: ""
+    anchor: append
+    body: |
+      ${input.recordName}:
+      ${input.flats}
+templates: []
+satisfies:
+  - cp2077.tweaks.yaml-lint
+  - cp2077.tweaks.append-on-list-flat
+  - cp2077.tweaks.record-name-exists
+  - cp2077.tweaks.dotted-path-same-file
+  - cp2077.tweaks.instances-resolve
+manual:
+  - title: Confirm the edit landed
+    steps:
+      - "Load a save with the mod active and confirm the TweakXL log shows no error for ${input.file}."
+      - "Inspect ${input.recordName} and confirm the appended flats are present alongside its vanilla values (an edit adds to, it does not replace, unless a flat is set outright)."
+    expected: "TweakXL-<timestamp>.log carries no error for this file, and ${input.recordName} reads with both its vanilla flats and the appended ones."
+claim:
+  idSuffix: edits
+  claim: "${input.recordName} carries the flats this run appended, on top of its vanilla definition."
+evidence: ["ModWright research"]

package/scaffolds/cyberpunk2077/mesh-export-preset.yaml

@@ -0,0 +1,170 @@
+# mesh-export-preset (Cyberpunk 2077). Writes a parameterised Blender export
+# script encoding the confirmed pipeline facts
+# (`knowledge/cyberpunk2077/mesh.blender.yaml`: the 65,535-vertex-per-submesh
+# cap, exactly one "UVMap" UV layer, triangulation, baked tangents) and
+# appends the `blender-export` + `wolvenkit-import` step pair to
+# `build.steps` as `optional: true`, the shape a working project's own
+# export-then-import build takes.
+#
+# The generated script is a parameterised **rewrite** of the confirmed facts,
+# not a copy of any particular project's export script: the knowledge base
+# attests that behaviour (vertex cap, UV normalisation, triangulation,
+# tangent export, the 00/01/02/03 submesh join order) rather than quoting
+# literal text. This scaffold never invokes Blender or WolvenKit itself; it
+# only writes the script and the two `optional: true` build steps a real run
+# would exercise.
+id: cyberpunk2077.mesh-export-preset
+game: cyberpunk2077
+title: New Cyberpunk 2077 mesh export preset
+summary: Write a parameterised Blender export script (vertex cap, UV, triangulation, tangents) and append the blender-export + wolvenkit-import build steps as optional.
+modTypes: [mesh, garment, weapon, vehicle]
+needs: {}
+inputs:
+  - type: path
+    name: blendFile
+    prompt: "The .blend this preset exports from."
+    mustExist: false
+  - type: path
+    name: exportScriptFile
+    prompt: "Destination for the generated export script."
+    mustExist: false
+  - type: path
+    name: baseMeshPath
+    prompt: "Existing staged .mesh WolvenKit imports the exported glb over (donor chunkMaterials/skinning)."
+    mustExist: false
+  - type: path
+    name: outputMeshDir
+    prompt: "Directory the imported .mesh should land in."
+    mustExist: false
+  - type: string
+    name: glbOutputPath
+    prompt: "Where the exported .glb should land — may use the build system's own ${stage} placeholder, e.g. \"${stage}/mymod.glb\"."
+  - type: string
+    name: uvLayerName
+    prompt: "Required single UV layer name (cp2077.mesh.glb-uv-layers-required)."
+    default: "UVMap"
+  - type: string
+    name: presetId
+    prompt: "Short id for this preset, used to name the two build steps, e.g. mymod."
+    pattern: "^[a-z][a-z0-9_-]*$"
+ids: []
+emits:
+  - op: write-text
+    path: "${input.exportScriptFile}"
+    body: |
+      #!/usr/bin/env python3
+      # ${project.today} — ModWright scaffold: parameterised Blender export
+      # preset "${input.presetId}", generated by cyberpunk2077.mesh-export-preset.
+      # Encodes the confirmed Cyberpunk 2077 mesh-export pipeline facts
+      # (knowledge/cyberpunk2077/mesh.blender.yaml), written as a parameterised
+      # rewrite of those facts. Run via:
+      #   blender --background "${input.blendFile}" --python "${input.exportScriptFile}"
+      import os
+      import bpy
+
+      VERTEX_CAP_PER_SUBMESH = 65535  # cp2077.mesh.vertex-cap-65535
+      REQUIRED_UV_LAYER = "${input.uvLayerName}"  # cp2077.mesh.glb-uv-layers-required
+      # The build step's own "out"/"glb" fields (modwright.json) are the
+      # authoritative destination — they may use ModWright's own ${stage}
+      # placeholder, which only that build system resolves, never this
+      # script. This script writes next to the source .blend and lets the
+      # wolvenkit-import step (or you) move/copy from there, the way a
+      # plain export invocation takes no output argument
+      # (knowledge/cyberpunk2077/mesh.blender.yaml).
+      GLB_OUTPUT_PATH = os.path.splitext(bpy.data.filepath)[0] + ".glb"
+
+      def normalize_uv_layers(mesh_obj):
+          # Exactly one UV layer named REQUIRED_UV_LAYER; extra layers removed,
+          # missing ones smart-projected (cp2077.mesh.glb-uv-layers-required).
+          uv_layers = mesh_obj.data.uv_layers
+          if REQUIRED_UV_LAYER not in uv_layers:
+              bpy.ops.object.mode_set(mode="EDIT")
+              bpy.ops.uv.smart_project(angle_limit=1.15, island_margin=0.02)
+              bpy.ops.object.mode_set(mode="OBJECT")
+              uv_layers.active.name = REQUIRED_UV_LAYER
+          for layer in list(uv_layers):
+              if layer.name != REQUIRED_UV_LAYER:
+                  uv_layers.remove(layer)
+
+      def triangulate_and_check_cap(mesh_obj):
+          # cp2077.mesh.glb-triangulation-required
+          bpy.ops.object.mode_set(mode="EDIT")
+          bpy.ops.mesh.quads_convert_to_tris(quad_method="BEAUTY", ngon_method="BEAUTY")
+          bpy.ops.object.mode_set(mode="OBJECT")
+          if len(mesh_obj.data.vertices) > VERTEX_CAP_PER_SUBMESH:
+              raise RuntimeError(
+                  f"{mesh_obj.name}: {len(mesh_obj.data.vertices)} vertices exceeds the "
+                  f"{VERTEX_CAP_PER_SUBMESH}-per-submesh engine cap (cp2077.mesh.vertex-cap-65535)."
+              )
+
+      def export():
+          for obj in bpy.context.scene.objects:
+              if obj.type != "MESH":
+                  continue
+              normalize_uv_layers(obj)
+              triangulate_and_check_cap(obj)
+          bpy.ops.export_scene.gltf(
+              filepath=GLB_OUTPUT_PATH,
+              export_tangents=True,  # cp2077.mesh.glb-tangent-vectors-required
+          )
+
+      if __name__ == "__main__":
+          export()
+  # Against a fresh new-project output (no `build` block yet at all), a
+  # patch-project without `build.outDir` would leave modwright.json failing
+  # to reload ("build.outDir: Required"), the same gap new-sector-node's
+  # patch-project closes. `add.outDir` only fills a genuinely missing
+  # `build.outDir`, so a project that already set one (e.g. from an earlier
+  # scaffold's own patch-project) keeps its own value (the engine's merge).
+  # Both steps below share one id on purpose: a build step id names a
+  # *chain* for `build --only <id>` (src/core/project/types.ts, BuildStepBase),
+  # so a blender-export and wolvenkit-import pair given a single id run
+  # together under `--only <id>`. That shared id is the convention, not a
+  # bug.
+  - op: patch-project
+    add:
+      outDir: "archive-staging"
+      steps:
+        - step: blender-export
+          id: "mesh-export-${input.presetId}"
+          optional: true
+          blend: "${input.blendFile}"
+          script: "${input.exportScriptFile}"
+          out: "${input.glbOutputPath}"
+        - step: wolvenkit-import
+          id: "mesh-export-${input.presetId}"
+          optional: true
+          glb: "${input.glbOutputPath}"
+          base: "${input.baseMeshPath}"
+          outDir: "${input.outputMeshDir}"
+templates: []
+# Applied against a fresh cyberpunk2077.new-project output,
+# cp2077.history.mesh-preexport always skipped "no file matched": this
+# scaffold never invokes Blender or WolvenKit itself and only writes the
+# script and the two optional: true build steps, so it never writes a
+# .gltf/.glb for that rule to check. The rule is therefore in the manual
+# checklist below, which names the real file (the exported .glb at
+# ${input.glbOutputPath}) and the checks the rule performs in prose.
+# cp2077.history.archive-name-sort-order/deploy-set-completeness stay: both
+# are project-scoped (appliesTo: project) and genuinely run every time.
+satisfies:
+  - cp2077.history.archive-name-sort-order
+  - cp2077.history.deploy-set-completeness
+manual:
+  - title: The kitbash and export itself
+    steps:
+      - "Author/kitbash the mesh in ${input.blendFile}, joined by material in the fixed submesh order this project's own donor mesh established (cp2077.mesh.join-by-material-submesh-order)."
+      - "Run the generated script (blender --background \"${input.blendFile}\" --python \"${input.exportScriptFile}\") and confirm no vertex-cap or UV error."
+      - "Build with this step pair enabled, then confirm the imported .mesh's chunkMaterials line up with the donor (${input.baseMeshPath})."
+      - "Once ${input.glbOutputPath} exists on disk, run validate against it directly — cp2077.history.mesh-preexport (moved out of this scaffold's own satisfies[]: it checks a .gltf/.glb this scaffold itself never produces) confirms the vertex cap, UV layer, triangulation and tangent-vector facts encoded in the generated script actually held for the real export."
+    expected: "The mesh imports cleanly with correct chunkMaterials, every submesh is under the 65,535-vertex cap, and cp2077.history.mesh-preexport reports no finding against the real ${input.glbOutputPath}."
+claim:
+  idSuffix: mesh-exports-clean
+  claim: "${input.blendFile} exports through ${input.exportScriptFile} and imports over ${input.baseMeshPath} with no vertex-cap or UV-layer error."
+testRows:
+  - gate: M-1
+    title: "Export and import run without error"
+    expected: "blender-export and wolvenkit-import both report success for the ${input.presetId} preset, with no vertex-cap/UV/triangulation error."
+    manual: true
+    probeKinds: []
+evidence: ["ModWright research"]