modwright 0.1.0

package/scaffolds/cyberpunk2077/new-item-chain.yaml

@@ -0,0 +1,548 @@
+# new-item-chain (Cyberpunk 2077). A TweakXL record cloned from a
+# vanilla/project `$base`, the `.xl` localization + factory entries, a
+# factory CSV row, an `en-us.json.json` row pair, and one CR2W source under
+# `sources/entities/<slug>/` cloned from a `template-record` input
+# (`root.ent.json` for an item base, `appearance.app.json` for a weapon
+# base; see the two branches below). `base`'s blueprint check is a
+# `requires.through` worked example.
+#
+# The factory row is written as plain CSV text via `insert-csv-row`, not a
+# JSON source plus a `convert deserialize` step. The shipped
+# `factory_parts.csv` is compiled CR2W, but no fixture or validator in this
+# repo carries a confirmed JSON-source shape for a compiled CSV (unlike
+# `.ent`/`.app`/`en-us.json`, all attested by real examples):
+# `cp2077.garments.factory-csv-rows` itself reads the staged file as plain
+# CSV text, and the proven-clean `jacket.ok.synthetic` fixture ships its
+# `factory_parts.csv` as plain text too. Inventing an unconfirmed JSON shape
+# for the one file with no attested example would be guessing, so a real
+# release build's compiled-CR2W factory CSV is left to a WolvenKit pass by
+# hand. The `.inkatlas` entry the catalog also lists is left to the manual
+# checklist for the same reason `new-item`'s recolor is: registering an icon
+# needs UV coordinates only a human (or a GUI atlas tool, which does not
+# exist yet) can supply.
+#
+# Deserialize steps:
+#   - The two `convert deserialize` build steps use the positional-input,
+#     directory-output form (`convert deserialize <src> -o <dir>`; see
+#     new-sector-node.yaml's matching note), via two `*CompiledDir` inputs:
+#     smaller than a general "directory of this path" derived value in the
+#     engine for the one pair of callers that need it.
+#   - WolvenKit.CLI names a `convert deserialize` output by stripping
+#     exactly one trailing `.json` off the source file's own name, confirmed
+#     on three real files (`x.streamingsector.json` -> `x.streamingsector`,
+#     `x.ent.json` -> `x.ent`, and `en-us.source.json` -> `en-us.source`,
+#     not `en-us.json`). The compiled localization resource the
+#     `.archive.xl` manifest points at (`mod\<slug>\en-us.json`) is itself a
+#     CR2W resource named `en-us.json`, so its JSON source has to be named
+#     `en-us.json.json` for the tool's real rule to produce it. A name like
+#     `en-us.source.json` only works for people who compile in the WolvenKit
+#     GUI and rename the output themselves afterward; it is not a convention
+#     ModWright's unattended `build` can honour. So the free-form file
+#     inputs are collapsed into a directory-only pair (`enUsSourceDir`,
+#     `entCompiledDir`) with both filenames fixed by the scaffold itself,
+#     `en-us.json.json` on the source side and `en-us.json` on the compiled
+#     side, so the two agree by construction instead of trusting a
+#     caller-supplied name to happen to match. The same fix applies to
+#     new-garment-refit's `resource.patch` and new-sector-node. No engine
+#     change is needed: both are plain `${input.*}` interpolation directly in
+#     each op's `path`/`args`/`expectOutputs`. The manifest names one
+#     mod/<slug> folder for both compiled files, so one compiled directory
+#     serves both.
+#
+# The blueprint:
+#   - No real vanilla base is already an iconic blueprint. A
+#     `requires.through` check ("the blueprint must already be an iconic
+#     blueprint") was run against 15 real vanilla iconic and non-iconic
+#     weapons and satisfied by NONE of them: every real weapon's blueprint
+#     carries only plain `<Family>_WeaponMod1/2Element` children, never an
+#     `Iconic*ModElement`. A shipped iconic weapon mod never inherits an
+#     iconic slot from its vanilla `$base` either: it authors its OWN
+#     blueprint, `$base`'d off the vanilla base's own blueprint, adding the
+#     iconic element itself (fact
+#     cp2077.tweakdb.iconic-blueprint-required-for-mod-slot). So `requires`
+#     only asks that the base's `blueprint` flat, when present, resolves to
+#     a real record (a weapon precondition, not an iconic one; a non-weapon
+#     base with no `blueprint` flat at all stays not-applicable); a
+#     project-owned `<ItemName>Blueprint` record is authored, `$base`'d off
+#     the base's own real blueprint (exposed into `${template.baseBlueprint}`
+#     by the `requires` entry's `expose`, engine.ts), and the new item's own
+#     `blueprint:` flat is set to it. Both emits are gated on
+#     `when: { templateDefined: baseBlueprint }` (a general emit guard,
+#     engine.ts/types.ts) so a non-weapon base's chain is untouched.
+#   - `iconicModElementName` (default `Items.IconicRangedWeaponModElement`,
+#     confirmed in game) is a plain input, not hardcoded. The melee
+#     equivalent is Items.IconicMeleeWeaponModElement (slot
+#     AttachmentSlots.IconicMeleeWeaponMod1), read from the installed game's
+#     blueprint_elements.tweak on 2026-09-11 (fact
+#     cp2077.tweakdb.melee.iconic-melee-mod-element-is-items-iconicmeleeweaponmodelement);
+#     a melee item chain passes that name. Separately worth knowing: a
+#     shipped melee iconic (a katana) never clones a blueprint at all. It
+#     sets `blueprint: Items.Iconic_Melee_Blueprint`, an existing vanilla
+#     record that already carries the iconic slot (fact
+#     cp2077.tweakdb.melee.iconic-quality-pattern-confirmed-across-mods), so
+#     a melee caller may prefer overriding this scaffold's own `blueprint:`
+#     flat to that vanilla record afterward instead of trusting an unproven
+#     `iconicModElementName`.
+#   - The new blueprint record's shape follows the shipped one: `$base`
+#     plus a restated `rootElement` whose `childElements` is a plain list,
+#     with no `!append` tag (a shipped file uses `!append` only on the item
+#     record's own top-level list flats, never inside `rootElement`). The
+#     shipped file also restates the base blueprint's `slot:` and its
+#     inherited childElements. Those are values only the index knows, so a
+#     `blueprint-root` lookup renders the base root (slot, named elements by
+#     name, inline elements as nested mappings) and
+#     `requires[].through.expose` carries it into the emit. An
+#     iconic-only restatement gave the item no slots at all (observed
+#     2026-09-11).
+#   - `cp2077.vehicles.inkatlas-uv-range` is not in `satisfies`: it only
+#     applies to `*.inkatlas.json` files, which this scaffold never writes
+#     (the inkatlas registration is the manual checklist's own job, per the
+#     "no GUI atlas tool exists yet" note above).
+#     `cp2077.vehicles.inkatlas-part-resolves` stays: it is project-scoped
+#     (`appliesTo: project`), so it genuinely runs every time.
+#
+# The chain has two branches (2026-09-12), keyed on the same `baseBlueprint`
+# guard the blueprint emits use.
+#   - A base WITHOUT a blueprint flat (a garment, a loot item): the item
+#     branch. The root entity is the appearance dictionary
+#     (cp2077.items.wiring.root-entity-is-appearance-lookup-dictionary), so
+#     a root.ent is cloned from the template with its first appearance
+#     pointed at mod\<slug>\appearance.app. This branch has a known gap:
+#     nothing this scaffold writes points AT that root.ent (the record names
+#     the factory row and the row names the .app), so wiring (or dropping)
+#     the root entity is the modder's own job.
+#   - A base WITH a blueprint flat (all 15 real vanilla weapons checked
+#     carry one): the weapon branch.
+#     A vanilla weapon record names no entity of its own: Items.Base_Weapon
+#     sets entityName=weapon_root, which weapons.csv maps to
+#     base\weapons\weapon_root.ent, a shared root with an EMPTY appearances
+#     list, and its look is the .app that weapons_appearances.csv maps its
+#     appearanceResourceName to (Preset_Kenshin_Default ->
+#     base\weapons\firearms\handgun\arasaka_kenshin\w_handgun__arasaka_kenshin.app).
+#     Cloning weapon_root.ent therefore cannot work (the appearance rewrite
+#     indexes appearances[0] of an empty list) and would be pointless if it
+#     did. A shipped weapon mod ships NO root entity at all: its
+#     factory_parts.csv maps the weapon's row to mod\<slug>\<weapon>.app
+#     and the record's appearanceResourceName names that row (fact
+#     cp2077.items.wiring.weapon-look-is-an-app-row-not-a-root-entity). So
+#     for a weapon base the template must be the base's own .app (kind
+#     weapon-app), cloned verbatim to sources/.../appearance.app.json with
+#     only its ArchiveFileName rewritten, compiled beside en-us.json, and
+#     named by the factory row this scaffold already writes. The two
+#     write-json-from-template emits and the two deserialize steps are
+#     mutually exclusive on `baseBlueprint`, the same way the two record
+#     blocks are; `entTemplate`'s expectKind map keys the .app kind for a
+#     WeaponItem base so a weapon-ent (or an unrelated entity such as a
+#     loot-container .ent) is refused with the reason.
+#     One gap the guard language cannot close: the branch keys on
+#     `baseBlueprint`, `expectKind` keys on `baseType`, so a WeaponItem
+#     base carrying no blueprint flat would demand an .app template and
+#     then run the ITEM branch on it: `setAtPath` would write
+#     appearances.0.name onto the .app's first appearance *handle* instead
+#     of refusing (jsonpath.ts only throws on a missing array element, not
+#     a wrong-shaped one). No such base has been seen (the 15 checked all
+#     carry a blueprint), and `when` has no form for "the base type is X";
+#     closing it properly needs an engine-side guard.
+id: cyberpunk2077.new-item-chain
+game: cyberpunk2077
+title: New Cyberpunk 2077 item chain (TweakXL + ArchiveXL + entity)
+summary: Clone a vanilla/project item's TweakXL record, register it in an .xl manifest with a factory row and localization entries, and clone its root .ent (an item base) or its appearance .app (a weapon base) from a template.
+modTypes: [weapon, item, loot, garment]
+needs: { index: true }
+inputs:
+  - type: string
+    name: itemName
+    prompt: "Item name, used for the TweakDB record and LocKey namespace, e.g. TestBlade."
+    pattern: "^[A-Za-z][A-Za-z0-9_]*$"
+  - type: string
+    name: modSlug
+    prompt: "Lowercase depot folder name for this item, e.g. testblade (used in every mod\\\\<slug>\\\\... path)."
+    pattern: "^[a-z][a-z0-9_]*$"
+  - type: index-ref
+    name: base
+    prompt: "$base record this item's TweakXL record inherits from."
+    lookup: { kind: chain, params: { name: "${input.base}" } }
+    requires:
+      # No real vanilla base is already an iconic blueprint (see the header
+      # note), so the check is a weapon
+      # precondition, not an iconic one — the base's blueprint, when
+      # present, must name a real record, or the project-owned blueprint
+      # this scaffold builds below would inherit from nothing. `through`
+      # fires only when `$base`'s effective `blueprint` flat is present at
+      # all — a garment/loot item with no blueprint flat is not a weapon and
+      # this check does not apply to it (`expose` then leaves
+      # `${template.baseBlueprint}` unset, and the emits gated on it do not
+      # run either).
+      # The base's record type (WeaponItem, Clothing, ...) is exposed for the entTemplate's kind check below; any value
+      # passes here, an absent type leaves ${template.baseType} unset.
+      - path: type
+        expose: baseType
+        matches: ".*"
+        reason: "the base's record type is read to check the .ent template's kind against it (any value passes this entry)."
+      - path: "flats.blueprint.value"
+        expose: baseBlueprint
+        through: { kind: chain, param: name, path: name }
+        reason: "the base's blueprint flat, once resolved, must name a real TweakDB record — the project-owned blueprint this scaffold builds inherits from it directly (the iconic-mod slot is always a project-authored blueprint, never something a real vanilla base already carries)."
+      # A project-owned blueprint that restated only the iconic element gave
+      # the item no slots at all (observed 2026-09-11). The
+      # base blueprint's root is restated in full from the index (lookup
+      # blueprint-root: its slot, its named elements by name, its inline
+      # elements as nested mappings), with the iconic element put first,
+      # and lands under the emitted `rootElement:` as ${template.baseRootYaml}.
+      - path: "flats.blueprint.value"
+        through:
+          kind: blueprint-root
+          param: name
+          path: rootYaml
+          params: { indent: "4", prepend: "${input.iconicModElementName}" }
+          expose: baseRootYaml
+        reason: "the base's blueprint must carry a root element this scaffold can restate (a rootElement, or slot/childElements flats along its $base chain): a derived blueprint that restates only the iconic element gives the item no attachment slots at all."
+  - type: string
+    name: displayName
+    prompt: "Player-facing item name."
+  - type: string
+    name: description
+    prompt: "Item description text."
+  - type: string
+    name: appearanceName
+    prompt: "Appearance name this item's root .ent should declare (item branch: a base with no blueprint flat). A weapon base's cloned .app keeps the base's own appearance names and this value is not used."
+    default: "default"
+  - type: string
+    name: iconicModElementName
+    prompt: "childElements entry the new project-owned blueprint appends to grant the iconic-mod attachment slot (only used when the base has its own blueprint flat at all). Ranged bases use the default; a melee base passes Items.IconicMeleeWeaponModElement (slot AttachmentSlots.IconicMeleeWeaponMod1, the vanilla melee iconics' own element)."
+    default: "Items.IconicRangedWeaponModElement"
+  - type: path
+    name: tweaksFile
+    prompt: "Destination .yaml under a project source of kind \"tweaks\" (created if missing)."
+    mustExist: false
+  - type: path
+    name: xlFile
+    prompt: "Destination .archive.xl manifest (created with an empty skeleton if missing). Put it beside the staged folder, e.g. archive-staging/<Project>.archive.xl, not inside it: the pack step stages the archive-staging source, and a manifest inside it would ship in the archive where ArchiveXL never reads it. It is registered as a project source and deployed to archive/pc/mod by its file name."
+    mustExist: false
+  - type: path
+    name: factoryCsvFile
+    prompt: "Destination factory CSV under archive-staging (created with a header row if missing)."
+    mustExist: false
+  - type: path
+    name: enUsSourceDir
+    prompt: "Directory the localization JSON source should be written to (created with an empty entries[] skeleton if missing). Its filename is fixed by this scaffold — en-us.json.json, not a free-form name — because WolvenKit.CLI's convert deserialize names its output by stripping exactly one trailing \".json\" off the source's own filename: only a source literally named en-us.json.json strips to the en-us.json the .archive.xl manifest points at (a name like en-us.source.json strips to en-us.source instead)."
+    mustExist: false
+  - type: path
+    name: entSourceDir
+    prompt: "Directory the cloned CR2W JSON source is written to, typically sources/entities/<slug>. The file name is fixed by this scaffold: root.ent.json for an item base (compiled to mod\\<slug>\\root.ent) or appearance.app.json for a weapon base (the factory row this scaffold writes points at mod\\<slug>\\appearance.app), because WolvenKit.CLI's convert deserialize names its output by stripping exactly one trailing .json off the source's own name."
+    mustExist: false
+  - type: path
+    name: entCompiledDir
+    prompt: "Directory the compiled root.ent (or appearance.app, for a weapon base) and en-us.json both land in, typically <archive-staging>/mod/<slug> — passed to WolvenKit.CLI's convert deserialize -o, which takes a directory, not a file. Both file names are fixed by this scaffold to match the manifest and the factory row, which name the same mod/<slug> folder, so one directory serves both (a separate enUsCompiledDir input could only ever agree with this one or be wrong)."
+    mustExist: false
+  - type: template-record
+    name: entTemplate
+    prompt: "Cached template-record directory (record.json + content.json) this item's look is cloned from. Its record kind has to fit the base: for a WeaponItem base the base's own appearance resource (kind weapon-app — the .app that weapons_appearances.csv maps the base's appearanceResourceName to; a vanilla weapon has no entity of its own to clone, its weapon_root.ent carries no appearances, and a shipped weapon mod ships an .app and no root entity); for a Clothing base the root entity (kind garment-ent, clothing-ent or item-ent). Observed in game: a loot-container .ent cloned for a weapon hung the game on equip."
+    expectKind:
+      by: baseType
+      # The index keeps a record's type as written: the vanilla dump says
+      # WeaponItem, a TweakXL yaml says gamedataWeaponItem_Record; both
+      # spellings are keyed.
+      map:
+        WeaponItem: "^weapon-app$"
+        gamedataWeaponItem_Record: "^weapon-app$"
+        Clothing: "^(garment|clothing|item)-ent$"
+        gamedataClothing_Record: "^(garment|clothing|item)-ent$"
+      reason: "A weapon base's look is the .app its appearanceResourceName maps to through weapons_appearances.csv, never a root entity (Items.Base_Weapon's weapon_root.ent has an empty appearances list, and a shipped weapon mod ships an .app and no .ent), and a loot-container .ent cloned for a weapon hung the game on equip (observed in game). Extract the base's .app with `template extract` (kind weapon-app; the path is the base's row in base\\gameplay\\factories\\items\\weapons\\weapons_appearances.csv) for a weapon, or its root entity (kind garment-ent) for clothing, and pass that directory."
+ids:
+  - name: recordName
+    slot: "Items.${project.name}_${input.itemName}"
+    form: tweak-record
+    collision:
+      project: true
+      index: { kind: record, param: name }
+  # Always allocated (cheap, collision-checked like any other id), but only ever written when `${template.baseBlueprint}` is set
+  # — the two emits below that reference it are both gated on that.
+  - name: blueprintName
+    slot: "Items.${project.name}_${input.itemName}Blueprint"
+    form: tweak-record
+    collision:
+      project: true
+      index: { kind: record, param: name }
+emits:
+  # `${ids.recordName}` gets exactly ONE occurrence in this file — these two variants are mutually exclusive (`templateDefined`
+  # / `templateUndefined` on the same key), never both. A record redeclared
+  # a second time in the same file is a real, confirmed TweakXL "Ambiguous
+  # definition" compile failure for at least the dotted-path edit form
+  # (cp2077.tweakdb.melee.dotted-path-mod-of-same-file-record-fails); this
+  # scaffold does not risk finding out whether a second full-block
+  # occurrence is any safer.
+  # `appearanceResourceName` names the factory row this scaffold writes
+  # (observed 2026-09-11): without it the record inherited the
+  # base's appearance, the spawned item wore the base's model, and
+  # cp2077.garments.factory-csv-rows, which checks only rows a record names,
+  # never looked at the row's unstaged appearance.app. With it, that rule
+  # blocks until the .app is staged, which is the truth of the chain.
+  - op: insert-block
+    path: "${input.tweaksFile}"
+    when: { templateDefined: baseBlueprint }
+    createIfMissing: ""
+    anchor: append
+    body: |
+      ${ids.recordName}:
+        $base: ${input.base}
+        displayName: LocKey#${project.name}-${input.itemName}-Name
+        localizedDescription: LocKey#${project.name}-${input.itemName}-Description
+        appearanceResourceName: ${input.itemName}
+        blueprint: ${ids.blueprintName}
+  - op: insert-block
+    path: "${input.tweaksFile}"
+    when: { templateUndefined: baseBlueprint }
+    createIfMissing: ""
+    anchor: append
+    body: |
+      ${ids.recordName}:
+        $base: ${input.base}
+        displayName: LocKey#${project.name}-${input.itemName}-Name
+        localizedDescription: LocKey#${project.name}-${input.itemName}-Description
+        appearanceResourceName: ${input.itemName}
+  # The shipped-mod pattern: a project-owned blueprint, `$base`'d off the base's own real blueprint,
+  # carrying the iconic-mod element — instead of demanding (unsatisfiably,
+  # per every real vanilla base checked) that the base already be iconic.
+  # Skipped entirely for a non-weapon base with no blueprint flat at all.
+  #
+  # The emitted shape is a shipped, in-game-verified one (fact
+  # cp2077.tweakdb.iconic-blueprint-required-for-mod-slot): `$base` plus a
+  # restated `rootElement` whose `childElements` is a plain list naming the
+  # iconic element, with NO `!append` tag. A shipped file uses `!append`
+  # only on the item record's own top-level list flats (`tags:`,
+  # `statModifiers:`), never inside `rootElement`, and nothing confirms
+  # TweakXL applies a list-mutation tag at that nesting depth, so this
+  # scaffold does not invent one.
+  #
+  # The shipped file restates the base blueprint's `slot:` and its whole
+  # inherited childElements list alongside the iconic element, because a
+  # restated rootElement is what the in-game-verified file does. The base's
+  # root arrives rendered from the index through the `blueprint-root` lookup
+  # (the `requires` entry above), iconic element first, so the emitted
+  # record is complete.
+  - op: insert-block
+    path: "${input.tweaksFile}"
+    when: { templateDefined: baseBlueprint }
+    anchor: append
+    body: |
+      ${ids.blueprintName}:
+        $base: ${template.baseBlueprint}
+        rootElement:
+      ${template.baseRootYaml}
+  - op: write-text
+    path: "${input.xlFile}"
+    ifExists: skip
+    body: |
+      {
+        "localization": { "onscreens": {} },
+        "factories": []
+      }
+  - op: insert-xl-entry
+    path: "${input.xlFile}"
+    pointer: localization.onscreens.en-us
+    value: "mod\\${input.modSlug}\\en-us.json"
+  - op: insert-xl-entry
+    path: "${input.xlFile}"
+    pointer: factories.-
+    value: "mod\\${input.modSlug}\\factory_parts.csv"
+  - op: insert-csv-row
+    path: "${input.factoryCsvFile}"
+    row: { name: "${input.itemName}", path: "mod\\${input.modSlug}\\appearance.app", shared: "false" }
+  - op: write-text
+    path: "${input.enUsSourceDir}/en-us.json.json"
+    ifExists: skip
+    body: |
+      {
+        "Header": {
+          "WolvenKitVersion": "8.20.0",
+          "WKitJsonVersion": "0.0.9",
+          "GameVersion": 2310,
+          "DataType": "CR2W",
+          "ArchiveFileName": "mod\\${input.modSlug}\\en-us.json"
+        },
+        "Data": {
+          "Version": 195,
+          "BuildVersion": 0,
+          "RootChunk": {
+            "$type": "JsonResource",
+            "cookingPlatform": "PLATFORM_PC",
+            "root": {
+              "HandleId": "0",
+              "Data": { "$type": "localizationPersistenceOnScreenEntries", "entries": [] }
+            }
+          },
+          "EmbeddedFiles": []
+        }
+      }
+  - op: insert-xl-entry
+    path: "${input.enUsSourceDir}/en-us.json.json"
+    pointer: Data.RootChunk.root.Data.entries.-
+    value:
+      $type: localizationPersistenceOnScreenEntry
+      femaleVariant: "${input.displayName}"
+      maleVariant: ""
+      primaryKey: "0"
+      secondaryKey: "${project.name}-${input.itemName}-Name"
+  - op: insert-xl-entry
+    path: "${input.enUsSourceDir}/en-us.json.json"
+    pointer: Data.RootChunk.root.Data.entries.-
+    value:
+      $type: localizationPersistenceOnScreenEntry
+      femaleVariant: "${input.description}"
+      maleVariant: ""
+      primaryKey: "0"
+      secondaryKey: "${project.name}-${input.itemName}-Description"
+  # Item branch (see the header): a base with no
+  # blueprint flat clones a root entity and points its first appearance at
+  # the mod's own .app.
+  - op: write-json-from-template
+    path: "${input.entSourceDir}/root.ent.json"
+    when: { templateUndefined: baseBlueprint }
+    template: entTemplate
+    rewrite:
+      - path: Header.ArchiveFileName
+        value: "mod\\${input.modSlug}\\root.ent"
+      - path: Data.RootChunk.appearances.0.name.$value
+        value: "${input.appearanceName}"
+      - path: Data.RootChunk.appearances.0.appearanceName.$value
+        value: "${input.appearanceName}"
+      - path: Data.RootChunk.appearances.0.appearanceResource.DepotPath.$value
+        value: "mod\\${input.modSlug}\\appearance.app"
+      - path: Data.RootChunk.defaultAppearance.$value
+        value: "${input.appearanceName}"
+    strip: []
+    renumberHandles: true
+  # Weapon branch: a base with a blueprint flat clones the base's own .app
+  # verbatim (its appearance names are the base's; the record inherits
+  # whichever the base selects) under the name the factory row above
+  # already points at. Only the archive-internal name is rewritten — the
+  # extracted header carries the extraction's temp path, never a depot path.
+  - op: write-json-from-template
+    path: "${input.entSourceDir}/appearance.app.json"
+    when: { templateDefined: baseBlueprint }
+    template: entTemplate
+    rewrite:
+      - path: Header.ArchiveFileName
+        value: "mod\\${input.modSlug}\\appearance.app"
+    strip: []
+    renumberHandles: true
+  # 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 and
+  # mesh-export-preset close. `add.outDir` only fills a genuinely missing
+  # `build.outDir`; a project that already set one keeps its own value
+  # (engine.ts's merge).
+  # The two deserialize steps go ahead of the
+  # project's stage step (`before: stage`; a project with no stage step gets
+  # them appended, with a line in the report's skipped list), or the compiled
+  # .ent and en-us.json land after the archive was already packed. The
+  # manifest this scaffold writes becomes a project source of kind xl (so
+  # the manifest rules see it wherever it lives) and an archive deploy
+  # target; both are idempotent across applies (engine.ts's merge).
+  # The deserialize step for the cloned CR2W source follows
+  # the branch (root.ent for an item base, appearance.app for a weapon base),
+  # so it lives in its own guarded patch-project op; the engine accumulates
+  # every patch-project op that ran into one merge, in op order (each step
+  # goes in ahead of the stage step, so the entity or appearance compiles
+  # first, then the localization), and a guarded op that did not run adds
+  # nothing.
+  - op: patch-project
+    when: { templateUndefined: baseBlueprint }
+    add:
+      steps:
+        - step: exec
+          id: "deserialize-${input.modSlug}-ent"
+          command: wolvenkit-cli
+          args: ["convert", "deserialize", "${input.entSourceDir}/root.ent.json", "-o", "${input.entCompiledDir}"]
+          expectOutputs: ["${input.entCompiledDir}/root.ent"]
+          before: stage
+  - op: patch-project
+    when: { templateDefined: baseBlueprint }
+    add:
+      steps:
+        - step: exec
+          id: "deserialize-${input.modSlug}-app"
+          command: wolvenkit-cli
+          args: ["convert", "deserialize", "${input.entSourceDir}/appearance.app.json", "-o", "${input.entCompiledDir}"]
+          expectOutputs: ["${input.entCompiledDir}/appearance.app"]
+          before: stage
+  - op: patch-project
+    add:
+      outDir: "archive-staging"
+      sources:
+        - id: "xl-${input.modSlug}"
+          path: "${input.xlFile}"
+          kind: xl
+      steps:
+        - step: exec
+          id: "deserialize-${input.modSlug}-enus"
+          command: wolvenkit-cli
+          args: ["convert", "deserialize", "${input.enUsSourceDir}/en-us.json.json", "-o", "${input.entCompiledDir}"]
+          expectOutputs: ["${input.entCompiledDir}/en-us.json"]
+          before: stage
+      deployTargets:
+        - rootId: archive
+          from: "${input.xlFile}"
+          locked: false
+          backup: true
+templates:
+  - ref: entTemplate
+    from: "${template.entTemplate.contentPath}"
+    provenanceFrom: entTemplate
+# Audited against a fresh new-project output
+# (test/unit/scaffold/catalog-apply.test.ts). `entSourceDir`/`enUsSourceDir`
+# both typically land under `sources/...`, invisible to
+# `cp2077.vehicles.cr2w-unique-ids`/`cr2w-resource-path-shape` unless
+# `cyberpunk2077.new-project` declares a `sources`-kind project source for
+# it (it does, once for every scaffold in this position), so no further
+# change to this file's satisfies[] is needed. The `patch-project` op's
+# `add.outDir` covers a project with no `build` block yet.
+satisfies:
+  - cp2077.tweaks.yaml-lint
+  - cp2077.tweaks.base-exists
+  - cp2077.tweaks.type-known
+  - cp2077.tweaks.flat-name-exists
+  - cp2077.tweaks.record-name-exists
+  - cp2077.tweaks.append-on-list-flat
+  - cp2077.tweaks.dotted-path-same-file
+  - cp2077.tweaks.instances-resolve
+  - cp2077.garments.factory-csv-rows
+  - cp2077.garments.xl-entries-resolve
+  - cp2077.history.xl-manifest-lint
+  - cp2077.history.clean-pack-json-sweep
+  - cp2077.vehicles.cr2w-unique-ids
+  - cp2077.vehicles.cr2w-resource-path-shape
+  - cp2077.vehicles.inkatlas-part-resolves
+manual:
+  - title: Icon, inkatlas and (for a weapon base) the modifier slot
+    steps:
+      - "Draw the item's icon art and register a part + UV rect for it in the mod's .inkatlas (no GUI atlas tool exists yet — see this scaffold's own header note)."
+      - "If ${input.base} has a blueprint, ${ids.blueprintName} restates the base blueprint's whole root (slot and every child, from the index) with ${input.iconicModElementName} first, as a hand-written blueprint does; read the block and drop any element the item should not carry (for example a scope element on a weapon that has none). Then confirm it loads without a TweakXL-<timestamp>.log error, spawn the item, open the modding screen and confirm the base's own attachment slots are present beside the IconicWeaponModLegendary slot, and that it is populated with an iconic modifier's stats once one is authored on ${input.iconicModElementName}."
+      - "For a weapon base, ${input.entSourceDir}/appearance.app.json is the base's own .app verbatim (the base's meshes, so the item renders as the base until they are swapped): edit its appearances' mesh paths to the mod's own meshes when the look should change, and stage those meshes before packing. A vanilla weapon .app carries every preset appearance the base ships (the Kenshin's has ten); a shipped weapon mod's .app keeps just the single `default` one and its record names no appearanceName flat at all, so trimming the clone down to `default` is what the one working precedent did. For an item base, stage ${input.entSourceDir}/root.ent.json's appearance.app and referenced meshes before packing — the scaffold clones only the root .ent, not the mesh/appearance chain."
+    expected: "The item shows a real icon, and (for a weapon base) ${ids.blueprintName} loads cleanly with the iconic slot present and the base's own attachment slots intact on the modding screen."
+claim:
+  idSuffix: spawns-with-stats
+  claim: "Game.AddToInventory(\"${ids.recordName}\", 1) yields an item whose displayName reads \"${input.displayName}\"."
+testRows:
+  - gate: I-1
+    title: "Record exists with the right base"
+    # cp2077.tweakdb.flat reads a flat's raw TweakDB value — for displayName
+    # that is a LocKey handle, not the literal ${input.displayName} text
+    # (observed in game: TweakDB:GetFlat(...) returned a
+    # LocKey userdata) — so the probe confirms the flat *resolves*, not that
+    # it reads back as the display text verbatim; a human still confirms the
+    # actual rendered text in the manual checklist above.
+    expected: "cp2077.tweakdb.record confirms ${ids.recordName} exists; cp2077.tweakdb.flat confirms its displayName flat resolves (to a LocKey, not literal text — a human confirms the rendered text reads \"${input.displayName}\")."
+    manual: false
+    probes:
+      - kind: cp2077.tweakdb.record
+        params: { id: "${ids.recordName}" }
+      - kind: cp2077.tweakdb.flat
+        params: { id: "${ids.recordName}.displayName" }
+  - gate: I-2
+    title: "Icon and description review"
+    expected: "The spawned item's icon and description render correctly, and (if iconic) the modifier slot is populated."
+    manual: true
+    probeKinds: []
+evidence: ["ModWright research"]