modwright 0.1.0

package/scaffolds/cyberpunk2077/new-project.yaml

@@ -0,0 +1,157 @@
+# new-project (Cyberpunk 2077). Mirrors the BG3 new-project scaffold: writes
+# the skeleton every other CP2077 scaffold assumes. tests/authored.yaml and
+# ledger/claims.yaml come from the engine's own automatic per-apply steps,
+# not an emit here.
+#
+# It also writes the build and deploy configuration a working project
+# needs (2026-09-11: scratch projects had to be configured by hand while
+# this scaffold wrote sources only): stage the archive-staging source under
+# the mod's name, pack it with WolvenKit, verify no CR2W JSON leaked into
+# the archive, and deploy the archive, the tweaks folder and the scripts
+# folder. The content scaffolds (new-item-chain, new-garment-refit,
+# new-sector-node) put their deserialize steps ahead of the stage step and
+# register the manifests they write as a project source and a deploy
+# target. A build on a project with nothing staged yet fails at the stage
+# step ("staged zero files"), which is the honest result until a content
+# scaffold has run.
+id: cyberpunk2077.new-project
+game: cyberpunk2077
+title: New Cyberpunk 2077 mod project
+summary: Scaffold a fresh ModWright project for a Cyberpunk 2077 mod — modwright.json (schemaVersion 2), the tweaks/scripts source trees, .gitignore, and ledger/decisions.yaml.
+modTypes: [packaging]
+needs: {}
+inputs:
+  - type: string
+    name: name
+    prompt: Mod name (also used as the r6/tweaks/<name> and scripts/<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"
+  # Observed in practice (2026-09-12): the WolvenKit CLI override had to be
+  # added to a fresh project by hand because the locator does not find a CLI
+  # installed outside the usual places. The path is machine-specific and
+  # lives in modwright.json's `toolchain` block; empty means "the locator's
+  # own candidates" and writes nothing.
+  - type: string
+    name: wolvenkitCli
+    prompt: "Absolute path to WolvenKit.CLI.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: []
+emits:
+  - op: ensure-dir
+    path: "r6/tweaks/${input.name}"
+  - op: ensure-dir
+    path: "scripts/${input.name}"
+  - op: ensure-dir
+    path: "archive-staging/${input.name}"
+  # Every other Cyberpunk scaffold that writes an editable JSON source
+  # (new-item-chain's .ent.json/localization, new-sector-node's
+  # .streamingsector.json, new-vehicle-livery's .mlsetup.json) writes it
+  # under "sources/...", and a working project declares exactly this as a
+  # project source of kind "sources". Without it here, those files sit
+  # outside every declared project source, so `core/validate/context.ts`'s
+  # `listFiles()` (which walks `project.sources`, not the whole tree) never
+  # lists them: the reason `cp2077.vehicles.cr2w-unique-ids`/
+  # `cr2w-enums-are-strings`/`cr2w-resource-path-shape` skipped "no file
+  # matched" against a scaffold that plainly does write a JSON
+  # `.mlsetup`/`.ent`/`.streamingsector` source, confirmed against a fresh
+  # project. Declaring it here is the root-cause fix: it makes those rules
+  # genuinely run (and check real content) instead of quietly moving them to
+  # `manual` for every scaffold that writes under sources/.
+  - op: ensure-dir
+    path: "sources"
+  - op: write-text
+    path: ".gitignore"
+    ifExists: skip
+    # Two files under .modwright should be tracked, so a reviewer reads them
+    # in a clean checkout: suppressions.json and templates/manifest.json. A
+    # bare `.modwright/` hides both (observed 2026-09-12). 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/
+      *.archive
+      .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": "cyberpunk2077",
+        "version": "${input.version}",
+        "authors": ["${input.author}"],
+        "identity": {
+          "name": "${input.name}"
+        },
+        "sources": [
+          { "id": "tweaks", "path": "r6/tweaks/${input.name}", "kind": "tweaks" },
+          { "id": "scripts", "path": "scripts/${input.name}", "kind": "scripts" },
+          { "id": "archive-staging", "path": "archive-staging/${input.name}", "kind": "archive-staging" },
+          { "id": "sources", "path": "sources", "kind": "sources" }
+        ],
+        "build": {
+          "outDir": "archive-staging",
+          "steps": [
+            { "step": "stage", "id": "pack", "sources": ["archive-staging"], "into": "${input.name}" },
+            { "step": "wolvenkit-pack", "from": "${stage}/pack/${input.name}", "out": "${input.name}.archive" },
+            { "step": "verify-listing", "of": "${input.name}.archive", "forbid": ["**/*.json", "!**/en-us.json"] }
+          ]
+        },
+        "deploy": {
+          "waitMinutes": 0,
+          "targets": [
+            { "rootId": "archive", "from": "${input.name}.archive", "locked": true, "backup": true },
+            { "rootId": "tweaks", "from": "tweaks", "into": "${input.name}", "locked": false, "backup": true },
+            { "rootId": "redscript", "from": "scripts", "into": "${input.name}", "locked": false, "backup": true }
+          ]
+        },
+        "dependencies": [
+          { "id": "red4ext", "kind": "loader", "url": "https://www.nexusmods.com/cyberpunk2077/mods/2380" },
+          { "id": "archivexl", "kind": "framework", "url": "https://www.nexusmods.com/cyberpunk2077/mods/4198" },
+          { "id": "tweakxl", "kind": "framework", "url": "https://www.nexusmods.com/cyberpunk2077/mods/4197" },
+          { "id": "wolvenkit-cli", "kind": "tool", "minVersion": "8.20", "notes": "Packs archive-staging/${input.name} into ${input.name}.archive and deserializes the CR2W JSON sources the content scaffolds write." }
+        ]
+      }
+  # The override merges into the modwright.json written just above (the
+  # engine patches the pending copy); an empty input adds no key at all.
+  - op: patch-project
+    add:
+      toolchain:
+        wolvenkit-cli: "${input.wolvenkitCli}"
+templates: []
+# No rule applies directly, same reasoning as the BG3 twin: pick a
+# project-target, project-only-needs rule so the postcondition is "ran,
+# clean" against the still-empty tree rather than "skipped".
+satisfies: [cp2077.tweaks.dotted-path-same-file]
+manual:
+  - title: Populate the mod
+    steps:
+      - "Add tweak YAML under r6/tweaks/<name>, redscript under scripts/<name>."
+      - "Run the new-tweak scaffold next to add the first TweakDB record."
+    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."
+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"]

package/scaffolds/cyberpunk2077/new-sector-node.yaml

@@ -0,0 +1,156 @@
+# new-sector-node (Cyberpunk 2077) — the scaffold writes the JSON source and
+# appends a `convert deserialize` build step (via patch-project) rather than
+# invoking WolvenKit itself. HandleId/BufferId are renumbered into document-
+# encounter order automatically by the engine's `insert-xl-entry` handling —
+# the literal placeholder below is arbitrary on purpose.
+#
+# Deviations observed in game (2026-09):
+#   - this scaffold's own patch-project op now supplies
+#     `add.outDir: "archive-staging"` — the convention a working project
+#     ships (`build.outDir: "archive-staging"` holding
+#     `archive-staging/<ModName>`) — so a project with no `build` block yet
+#     (fresh off `new-project`) does not end up with one missing `outDir`.
+#     It only fills the gap: a project that already has `build.outDir` set
+#     keeps its own value (engine.ts's own merge). Fixed at the engine level
+#     too: a patch-project op that would leave modwright.json invalid now
+#     refuses instead of writing (engine.ts).
+#   - the emitted build step used `wolvenkit-cli convert deserialize
+#     -i <src> -o <dst>`, but WolvenKit.CLI's `convert` subcommands take the
+#     input path positionally and `-o` names an output *directory*, not a
+#     file (`-i` is silently swallowed as noise and the run exits 161 —
+#     confirmed by hand in game). Fixed to `convert deserialize
+#     <input file> -o <output directory>` via a new `outputDir` input
+#     (smaller than teaching the engine a "directory of this path" derived
+#     value for the one caller that needs it — see new-item-chain.yaml's
+#     matching note). `expectOutputs` still names `outputPath`, the file
+#     WolvenKit is expected to actually write there — inferred from the
+#     serialize direction (it strips the trailing `.json` off the source
+#     file's own name) and NOT yet confirmed against a real `deserialize`
+#     run; `outputPath` and `outputDir` are both given by the caller and
+#     must agree (outputPath's directory should equal outputDir) — nothing
+#     here derives one from the other.
+#   - `satisfies` is trimmed to the rules that genuinely run against
+#     the `.streamingsector` JSON this scaffold writes (checked with a
+#     `ran`-membership assertion in the scaffold's tests) — `cp2077.history.
+#     xl-manifest-lint` only applies to `.xl` files and never matches a bare
+#     sector JSON, so it is dropped.
+#
+# Re-audited against a truly fresh new-project output, not a hand-built
+# fixture (observed 2026-09): `${input.file}` typically lands under
+# `sources/sector/...`, which only resolves to a file the validation context
+# can see because `cyberpunk2077.new-project`
+# now declares a `sources`-kind project source (fixed there, at the root,
+# once for every scaffold that writes under `sources/...`). No change to
+# this file's own satisfies[] was needed once that fix landed.
+id: cyberpunk2077.new-sector-node
+game: cyberpunk2077
+title: New Cyberpunk 2077 sector node
+summary: Append a worldEntityNode to an existing .streamingsector JSON source at a given position, and add the convert-deserialize build step for it.
+modTypes: [world-sector]
+needs: {}
+inputs:
+  - type: path
+    name: file
+    prompt: "The mod's own .streamingsector JSON source to append the node to (must already exist)."
+    mustExist: true
+  - type: path
+    name: outputPath
+    prompt: "Where the compiled .streamingsector binary should land (project-relative), for the build step this scaffold appends. Its directory must equal outputDir."
+    mustExist: false
+  - type: path
+    name: outputDir
+    prompt: "Directory the compiled .streamingsector binary should land in (project-relative) — passed to WolvenKit.CLI's convert deserialize -o, which takes a directory, not a file. Must be outputPath's own directory."
+    mustExist: false
+  - type: string
+    name: entityTemplatePath
+    prompt: "Depot path (backslash, lowercase) to the .ent this node spawns, e.g. mod\\\\mymod\\\\newprop.ent."
+    pattern: "^[a-z0-9_]+(\\\\[a-z0-9_]+)*\\.ent$"
+  - type: string
+    name: appearanceName
+    prompt: "Appearance name to use (must be one the .ent actually declares, once staged)."
+    default: "default"
+  - type: number
+    name: positionX
+    prompt: "World position X."
+  - type: number
+    name: positionY
+    prompt: "World position Y."
+  - type: number
+    name: positionZ
+    prompt: "World position Z."
+ids: []
+emits:
+  - op: insert-xl-entry
+    path: "${input.file}"
+    pointer: Data.RootChunk.nodes.-
+    value:
+      HandleId: "new-node"
+      Data:
+        $type: worldEntityNode
+        appearanceName: { $type: CName, $storage: string, $value: "${input.appearanceName}" }
+        debugName: { $type: CName, $storage: string, $value: "[ModWright] ${input.entityTemplatePath}" }
+        entityLod: 0
+        entityTemplate:
+          DepotPath: { $type: ResourcePath, $storage: string, $value: "${input.entityTemplatePath}" }
+          Flags: Soft
+        ioPriority: Immediate
+        isHostOnly: 0
+        isVisibleInGame: 1
+        sourcePrefabHash: "0"
+        tag: None
+        tagExt: None
+  - op: insert-xl-entry
+    path: "${input.file}"
+    pointer: Data.RootChunk.nodeData.Data.-
+    value:
+      Id: "1"
+      NodeIndex: 1
+      Position: { $type: Vector4, W: 0, X: "${input.positionX}", Y: "${input.positionY}", Z: "${input.positionZ}" }
+      Orientation: { $type: Quaternion, i: 0.0, j: 0.0, k: 0.0, r: 1.0 }
+      Scale: { $type: Vector3, X: 1, Y: 1, Z: 1 }
+  - op: patch-project
+    add:
+      outDir: "archive-staging"
+      steps:
+        - step: exec
+          id: "deserialize-sector"
+          command: wolvenkit-cli
+          args: ["convert", "deserialize", "${input.file}", "-o", "${input.outputDir}"]
+          expectOutputs: ["${input.outputPath}"]
+          # Ordering (2026-09-11): ahead of the project's stage step, or
+          # the compiled sector lands after the archive was packed.
+          before: stage
+templates: []
+satisfies:
+  - cp2077.vehicles.cr2w-unique-ids
+  - cp2077.vehicles.cr2w-enums-are-strings
+  - cp2077.vehicles.cr2w-resource-path-shape
+  - cp2077.vehicles.cr2w-gameversion-header
+  - cp2077.vehicles.appearance-name-resolution
+manual:
+  - title: Confirm placement in-game
+    steps:
+      - "Stage the referenced .ent (${input.entityTemplatePath}) so appearance-name-resolution can actually check ${input.appearanceName}."
+      - "Load a save near the placed coordinates and confirm the entity spawns and renders."
+    expected: "The entity is visible at the given position with the expected appearance."
+claim:
+  idSuffix: placed
+  claim: "A worldEntityNode referencing ${input.entityTemplatePath} (appearance ${input.appearanceName}) is placed at (${input.positionX}, ${input.positionY}, ${input.positionZ})."
+testRows:
+  - gate: N-1
+    title: "Entity located in-game"
+    # cp2077.entity.tagged only finds legacy dev-spawn duplicates, not a
+    # sector-placed static prop (observed in game, 2026-09,
+    # taggedCount: 0 against a real placed prop) — this scaffold's own node is
+    # exactly that case, so the tag mechanism does not apply to it at all. cp2077.entity.transform
+    # is itself only `unverified` for a sector-placed prop (same citation).
+    # Neither kind is usable here; a human confirms placement by eye instead.
+    expected: "A human loads near (${input.positionX}, ${input.positionY}, ${input.positionZ}) and confirms the entity is present at that position — cp2077.entity.tagged/cp2077.entity.transform do not apply to a sector-placed static prop (see this row's own note)."
+    manual: true
+    probeKinds: [cp2077.entity.tagged, cp2077.entity.transform]
+  - gate: N-2
+    title: "Visual inspection"
+    expected: "A human confirms the entity renders with the correct mesh/appearance from two camera angles."
+    manual: true
+    probeKinds: []
+evidence: ["ModWright research"]

package/scaffolds/cyberpunk2077/new-tweak.yaml

@@ -0,0 +1,121 @@
+# new-tweak (Cyberpunk 2077) — writes one TweakXL record from a vanilla (or
+# project) $base into a .yaml file under a project source of kind "tweaks".
+# `file` is a `path` input rather than a fixed convention, because projects
+# lay their tweaks trees out differently (r6/tweaks/<Mod>/*.yaml in one,
+# tweaks/*.yaml deployed to r6/tweaks/ in another) — the caller (a `lookup`
+# call, or the person running the scaffold) names the destination, this
+# scaffold does not guess it.
+#
+# Observed while authoring a quickhack (2026-09-19): a record either
+# clones a vanilla/project `$base` OR declares a fresh engine `$type` with no
+# base — the quickhack chain's `ObjectActionPrereq` prereq wrapper is the
+# latter, and this scaffold could not write it while `base` was required.
+# `base` and `type` are now a `oneOf` group (exactly one, engine.ts): each is
+# optional, and the two record blocks below gate on which was given
+# (`when.inputDefined`), so `${ids.recordName}` gets exactly one occurrence in
+# the file — the same mutual-exclusion discipline new-item-chain's two record
+# blocks follow. The `$type` path leans on the tweaks validators already
+# handling a base-less record (`base-exists` skips `!rec.base`; `type-known`
+# checks `rec.type`; `flat-name-exists` is out of scope "unless the record
+# declares its own $type").
+id: cyberpunk2077.new-tweak
+game: cyberpunk2077
+title: New Cyberpunk 2077 TweakDB record
+summary: Append one TweakXL record (with a $base and hand-authored flats) into an existing .yaml under a project's "tweaks" source.
+modTypes: [gameplay-tweak, 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: string
+    name: recordName
+    prompt: "Full TweakDB record name, e.g. Items.Preset_MyGun."
+    pattern: "^[A-Za-z][A-Za-z0-9_]*(\\.[A-Za-z0-9_]+)+$"
+  - type: index-ref
+    name: base
+    prompt: "$base record this inherits from (provide this OR type, not both)."
+    lookup: { kind: record, params: { name: "${input.base}" } }
+    requires: []
+  - type: string
+    name: type
+    prompt: "$type engine record type for a fresh record with no vanilla $base, e.g. ObjectActionPrereq (provide this OR base, not both)."
+    pattern: "^[A-Za-z][A-Za-z0-9_]*$"
+  - type: string
+    name: flats
+    prompt: "Hand-authored flat lines as YAML (e.g. \"displayName: LocKey#Foo-Name\\nprice: 500\"). Indentation is normalized to nest under the record, so write it at any consistent base indent — a sequence step can fix this as a natural block scalar."
+    default: ""
+    reindent: 2
+ids:
+  - name: recordName
+    slot: "${input.recordName}"
+    form: tweak-record
+    collision:
+      project: true
+      index: { kind: record, param: name }
+oneOf:
+  - [base, type]
+emits:
+  # Exactly one of these two fires (oneOf: [base, type], enforced by the
+  # engine): a $base clone, or a fresh $type declaration. Both append the
+  # record name once, then the hand-authored flats.
+  - op: insert-block
+    path: "${input.file}"
+    when: { inputDefined: base }
+    createIfMissing: ""
+    anchor: append
+    body: |
+      ${ids.recordName}:
+        $base: ${input.base}
+      ${input.flats}
+  - op: insert-block
+    path: "${input.file}"
+    when: { inputDefined: type }
+    createIfMissing: ""
+    anchor: append
+    body: |
+      ${ids.recordName}:
+        $type: ${input.type}
+      ${input.flats}
+templates: []
+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
+manual:
+  - title: Confirm in-game
+    steps:
+      - "Load a save with the mod active and confirm the TweakXL log shows no error for ${input.file}."
+      - "Spawn/inspect ${ids.recordName} and confirm the copied flats read as expected."
+    expected: "TweakXL-<timestamp>.log carries no error for this file, and the record's flats match the $base plus overrides."
+claim:
+  idSuffix: spawns-with-stats
+  # Not "$base ${input.base}": a $type-only record has no base, and an
+  # unguarded ${input.base} would fail to interpolate in that mode.
+  claim: "${ids.recordName} exists in TweakDB with its declared $base or $type and the hand-authored flat overrides applied."
+testRows:
+  - gate: T-1
+    title: "Record exists with the right base and flats"
+    # cp2077.tweakdb.flat needs one concrete <record>.<flat> id, but
+    # ${input.flats} is hand-authored free text (no free-form
+    # name is trusted to happen to match) — no flat name is fixed
+    # here to probe, so only the record's own existence is automated; the
+    # flat values themselves stay on the manual checklist above
+    # ("confirm the copied flats read as expected").
+    expected: "cp2077.tweakdb.record confirms ${ids.recordName} exists."
+    manual: false
+    probes:
+      - kind: cp2077.tweakdb.record
+        params: { id: "${ids.recordName}" }
+  - gate: T-2
+    title: "TweakXL log clean"
+    expected: "TweakXL-<timestamp>.log shows no error for this file after a fresh load."
+    manual: true
+    probeKinds: []
+evidence: ["ModWright research"]

package/scaffolds/cyberpunk2077/new-vehicle-livery.yaml

@@ -0,0 +1,148 @@
+# new-vehicle-livery (Cyberpunk 2077) — clones a vehicle's `.mlsetup`
+# material with a renamed base material/texture pair, and a TweakXL vehicle
+# record inheriting the base vehicle's own entityTemplate through its `$base`
+# chain (so no new `.ent` is needed for a pure recolor).
+#
+# Observed in game (2026-09): the `baseVehicle` index-ref's `requires`
+# checked `type` against `^gamedataVehicle`, but `chain`'s own `type` field is
+# the record's bare RTTI-derived type name (queries.ts's `latestPointer`), and
+# for every real vehicle record that name is the literal string `Vehicle` —
+# WolvenKit's own naming rule drops both the `gamedata` prefix and `_Record`
+# suffix (`gamedataVehicle_Record` -> `Vehicle`), confirmed in
+# cp2077.wolvenkit.cli.tweak-type-name-drops-gamedata-and-record-suffix.
+# The requirement matches that literal value.
+#
+# `cp2077.vehicles.tweak-name-from-ent` and `cp2077.vehicles.inkatlas-uv-range`
+# are not in `satisfies`: both are file-extension-gated (`v_*.ent.json`,
+# `*.inkatlas.json` respectively) and this scaffold clones only a `.mlsetup`
+# and a tweak record, never an `.ent` or an `.inkatlas`.
+# `cp2077.vehicles.ent-app-resolution`/`appearance-name-resolution`/
+# `inkatlas-part-resolves` stay: all three are project-scoped
+# (`appliesTo: project`), so they genuinely run every time.
+#
+# Observed in game (2026-09): a fresh project reported `clean: false` with
+# `findings: []` — only benign `(listed in satisfies) skipped` reasons. The
+# real offenders were `cp2077.vehicles.cr2w-unique-ids`/`cr2w-enums-are-strings`/
+# `cr2w-resource-path-shape` skipping "no file matched", because this
+# scaffold's `.mlsetup.json` source landed under `sources/...`, which
+# `cyberpunk2077.new-project` declared no project source for, so the
+# validation context never saw it. `new-project` now declares a
+# `sources`-kind project source; every satisfies rule here concerns a file
+# this scaffold writes, once that file is visible at all.
+#
+# The catalog also lists an "`.xl` substitution entry". There is no
+# confirmed shape for how ArchiveXL wires a recolored `.mlsetup` into a
+# vehicle's paint job (`resource.patch`'s own sub-shape, per
+# `cp2077.history.xl-manifest-lint`, is `.ent`-keyed-to-`.ent` only, which a
+# material swap does not fit). Inventing an unconfirmed manifest shape would
+# be guessing; the manual checklist calls out confirming the real mechanism
+# against current ArchiveXL docs instead of shipping a shape nobody has
+# verified.
+id: cyberpunk2077.new-vehicle-livery
+game: cyberpunk2077
+title: New Cyberpunk 2077 vehicle livery
+summary: Clone a vehicle's .mlsetup material with a renamed base material and texture, plus a TweakXL vehicle record inheriting the base vehicle's own entityTemplate.
+modTypes: [vehicle]
+needs: { index: true }
+inputs:
+  - type: string
+    name: vehicleName
+    prompt: "Suffix for the new TweakDB Vehicle.* record, e.g. TestQuartzRecolor."
+    pattern: "^[A-Za-z][A-Za-z0-9_]*$"
+  - type: index-ref
+    name: baseVehicle
+    prompt: "$base Vehicle.* TweakDB record this livery inherits from (its entityTemplate is inherited, not restated)."
+    lookup: { kind: chain, params: { name: "${input.baseVehicle}" } }
+    requires:
+      - path: type
+        matches: "^Vehicle$"
+        reason: "the base's resolved type must be the literal record type \"Vehicle\" — how RTTI type gamedataVehicle_Record is written in .tweak yaml (cp2077.wolvenkit.cli.tweak-type-name-drops-gamedata-and-record-suffix) and what the chain lookup's own type field actually holds for every real vehicle record — or this livery would inherit fields from the wrong record family."
+  - type: string
+    name: baseMaterialPath
+    prompt: "Depot path (backslash, lowercase) to the vanilla/project base .mt this livery's material inherits, e.g. base\\\\materials\\\\metal_painted.mt."
+    pattern: "^[a-z0-9_]+(\\\\[a-z0-9_]+)*\\.mt$"
+  - type: string
+    name: textureBaseColorPath
+    prompt: "Depot path (backslash, lowercase) to this livery's own basecolor texture."
+    pattern: "^[a-z0-9_]+(\\\\[a-z0-9_]+)*\\.xbm$"
+  - type: path
+    name: tweaksFile
+    prompt: "Destination .yaml under a project source of kind \"tweaks\" (created if missing)."
+    mustExist: false
+  - type: path
+    name: mlsetupOutputFile
+    prompt: "Destination for the cloned .mlsetup JSON source."
+    mustExist: false
+  - type: template-record
+    name: mlsetupTemplate
+    prompt: "Cached template-record directory (record.json + content.mlsetup) for the .mlsetup this livery clones."
+ids:
+  - name: recordName
+    slot: "Vehicle.${project.name}_${input.vehicleName}"
+    form: tweak-record
+    collision:
+      project: true
+      index: { kind: record, param: name }
+emits:
+  - op: insert-block
+    path: "${input.tweaksFile}"
+    createIfMissing: ""
+    anchor: append
+    body: |
+      ${ids.recordName}:
+        $base: ${input.baseVehicle}
+  - op: write-json-from-template
+    path: "${input.mlsetupOutputFile}"
+    template: mlsetupTemplate
+    rewrite:
+      - path: Data.BaseMaterial.DepotPath.$value
+        value: "${input.baseMaterialPath}"
+      - path: Data.Values.0.v.DepotPath.$value
+        value: "${input.textureBaseColorPath}"
+    strip: []
+    # .mlsetup carries no HandleId/BufferId at all (unlike .ent/.app) — the
+    # renumber pass would be a harmless no-op either way, but disabling it
+    # names that explicitly rather than relying on it silently doing nothing.
+    renumberHandles: false
+templates:
+  - ref: mlsetupTemplate
+    from: "${template.mlsetupTemplate.contentPath}"
+    provenanceFrom: mlsetupTemplate
+satisfies:
+  - cp2077.tweaks.yaml-lint
+  - cp2077.tweaks.base-exists
+  - cp2077.tweaks.type-known
+  - cp2077.tweaks.dotted-path-same-file
+  - cp2077.tweaks.instances-resolve
+  - cp2077.vehicles.ent-app-resolution
+  - cp2077.vehicles.appearance-name-resolution
+  - cp2077.vehicles.inkatlas-part-resolves
+  - cp2077.vehicles.cr2w-unique-ids
+  - cp2077.vehicles.cr2w-enums-are-strings
+  - cp2077.vehicles.cr2w-resource-path-shape
+  - cp2077.vehicles.cr2w-gameversion-header
+  - cp2077.history.xl-manifest-lint
+manual:
+  - title: Wire the recolor in and paint the texture
+    steps:
+      - "Confirm, against ArchiveXL's current docs, the real mechanism for pointing ${input.baseVehicle}'s paint job at ${input.mlsetupOutputFile}'s compiled .mlsetup — this scaffold deliberately does not guess at an .xl manifest shape nobody has confirmed (see this file's own header note)."
+      - "Paint the basecolor (and normal/roughness, if this material needs them) texture(s) referenced by ${input.textureBaseColorPath}."
+      - "Build and deploy, then confirm the vehicle is drivable and the livery is visible from two camera angles."
+    expected: "The vehicle spawns drivable with the new livery visible from at least two camera angles, and the base vehicle's own paint jobs are unaffected."
+claim:
+  idSuffix: livery-applied
+  claim: "${ids.recordName} (based on ${input.baseVehicle}) renders with the ${input.mlsetupOutputFile}-derived livery."
+testRows:
+  - gate: L-1
+    title: "Vehicle record exists with the right base"
+    expected: "cp2077.tweakdb.record confirms ${ids.recordName} exists with $base ${input.baseVehicle}."
+    manual: false
+    probes:
+      - kind: cp2077.tweakdb.record
+        params: { id: "${ids.recordName}" }
+  - gate: L-2
+    title: "Drivable with the livery visible"
+    expected: "CET spawn probe confirms the vehicle is drivable and the livery is visible from two camera angles."
+    manual: true
+    probeKinds: []
+evidence: ["ModWright research"]