modwright 0.1.0

package/scaffolds/cyberpunk2077/new-workspot-entity.yaml

@@ -0,0 +1,177 @@
+# new-workspot-entity (Cyberpunk 2077) — observed in game (2026-09-19).
+#
+# A spawnable entity whose only job is to carry a workspot, so a script can
+# pose any puppet with it: spawn the entity at the puppet's transform, then
+#   WorkspotSystem.PlayInDeviceSimple(entity, puppet, false, n"<componentName>",
+#                                    n"", n"", 0.0, WorkspotSlidingBehaviour.DontPlayAtResourcePosition, null)
+# and, when the workspot's animation set has several entries,
+#   WorkspotSystem.SendJumpToAnimEnt(puppet, n"<animation>", true).
+# That is exactly how Appearance Menu Mod poses NPCs and spawned V clones
+# (its `base\amm_workspots\entity\workspot_anim.ent`, one
+# `workWorkspotResourceComponent` named `amm_workspot_base`), and what an
+# in-game test confirmed on a spawned `Character.TPP_Player_Cutscene_Female`:
+# `NPCPuppet.ChangeStanceState(Crouch)` sets the blackboard and poses
+# nothing, the workspot kneels it. The game itself ships no entity that is
+# only a workspot (the 2,607 `.workspot` resources under `base\workspots\`
+# are referenced from sector nodes and device entities), which is why a mod
+# that wants a pose must ship its own — and why this scaffold exists rather
+# than a dependency on AMM.
+#
+# The component block is the `workWorkspotResourceComponent` read off the
+# vanilla `base\gameplay\devices\utilities\netrunner\netrunner_chair.ent`
+# (extracted 2026-09-19): `workspotResource` is the one field that matters,
+# the two `*ResourceSync` paths stay unset (uint64 0, as the chair's own
+# personal-link workspot has them), `syncSlotName` None, `shouldCrouch` 0,
+# `parentTransform` null, identity transform. The root is a `gameObject`,
+# not a bare `entEntity`: `PlayInDeviceSimple` takes the device as a
+# `GameObject`, and a script resolving the spawned entity casts it to one
+# (observed in game, 2026-09-19: an `entEntity` root spawned
+# but never cast, so the clone was never posed). The component `id` is
+# fixed above the vanilla range like `new-entity-patch`'s.
+#
+# `workspotResource` is a plain string, not an `index-ref`: the resource
+# index answers existence (`lookup` kind `resource`, `path`), and the
+# manual step says to ask it, but a scaffold that needs the index cannot
+# run in a project without one, and the pose is chosen by eye in any case.
+id: cyberpunk2077.new-workspot-entity
+game: cyberpunk2077
+title: New Cyberpunk 2077 workspot entity (a spawnable pose holder)
+summary: Write a spawnable entity carrying one workWorkspotResourceComponent that points at a vanilla .workspot, plus its deserialize build step, so a script can pose a puppet with PlayInDeviceSimple.
+modTypes: [quickhack, npc, entity-patch]
+needs: {}
+inputs:
+  - type: string
+    name: modSlug
+    prompt: "Lowercase depot folder name for this mod, e.g. mymod (the entity compiles to mod\\\\<slug>\\\\<entityName>.ent)."
+    pattern: "^[a-z][a-z0-9_]*$"
+  - type: string
+    name: entityName
+    prompt: "File stem of the entity, e.g. kneel_workspot (source <entityName>.ent.json, compiled <entityName>.ent)."
+    pattern: "^[a-z][a-z0-9_]*$"
+  - type: string
+    name: componentName
+    prompt: "Name of the workspot component (what a script passes as actorDataCompName to PlayInDeviceSimple)."
+    pattern: "^[A-Za-z][A-Za-z0-9_]*$"
+    default: "workspot"
+  - type: string
+    name: workspotResource
+    prompt: "Depot path of the vanilla .workspot the entity plays, backslashes, lowercase, e.g. base\\\\workspots\\\\common\\\\ground\\\\generic__kneel_ground__cover__01.workspot. Confirm it exists with lookup kind resource (path) first."
+    pattern: "^[a-z0-9_]+(\\\\[a-z0-9_.]+)+\\.workspot$"
+  - type: path
+    name: sourceDir
+    prompt: "Directory the entity's JSON source is written to, typically sources/<modSlug>."
+    mustExist: false
+  - type: path
+    name: compiledDir
+    prompt: "Directory the compiled <entityName>.ent lands in, typically <archive-staging>/<Project>/mod/<modSlug> — the folder the script's ResRef names (mod\\\\<modSlug>\\\\<entityName>.ent)."
+    mustExist: false
+ids: []
+emits:
+  # One write-text with ifExists: skip, idempotent, for the same reason
+  # new-entity-patch gives: an append at `components.-` would grow a second
+  # component with the same name and id on a re-run. The depot path does
+  # NOT land inside this JSON text: a backslash substituted raw into JSON
+  # is an invalid escape (`\w`), and the engine's string context does not
+  # JSON-escape. So the body carries an empty `$value` and the structured
+  # `insert-xl-entry` below sets the leaf by pointer (a numeric segment
+  # indexes the components array), which is also a plain set on a re-run.
+  - op: write-text
+    path: "${input.sourceDir}/${input.entityName}.ent.json"
+    ifExists: skip
+    body: |
+      {
+        "Header": {
+          "WolvenKitVersion": "8.20.0",
+          "WKitJsonVersion": "0.0.9",
+          "GameVersion": 2310,
+          "DataType": "CR2W",
+          "ArchiveFileName": "${input.entityName}.ent"
+        },
+        "Data": {
+          "Version": 195,
+          "BuildVersion": 0,
+          "RootChunk": {
+            "$type": "entEntityTemplate",
+            "appearances": [],
+            "components": [
+              {
+                "$type": "workWorkspotResourceComponent",
+                "deviceWorkspotResourceSync": {
+                  "DepotPath": { "$type": "ResourcePath", "$storage": "uint64", "$value": "0" },
+                  "Flags": "Default"
+                },
+                "id": "9020000000000000001",
+                "isReplicable": 0,
+                "localTransform": {
+                  "$type": "WorldTransform",
+                  "Orientation": { "$type": "Quaternion", "i": 0, "j": 0, "k": 0, "r": 1 },
+                  "Position": {
+                    "$type": "WorldPosition",
+                    "x": { "$type": "FixedPoint", "Bits": 0 },
+                    "y": { "$type": "FixedPoint", "Bits": 0 },
+                    "z": { "$type": "FixedPoint", "Bits": 0 }
+                  }
+                },
+                "name": { "$type": "CName", "$storage": "string", "$value": "${input.componentName}" },
+                "npcWorkspotResourceSync": {
+                  "DepotPath": { "$type": "ResourcePath", "$storage": "uint64", "$value": "0" },
+                  "Flags": "Default"
+                },
+                "parentTransform": null,
+                "shouldCrouch": 0,
+                "syncSlotName": { "$type": "CName", "$storage": "string", "$value": "None" },
+                "workspotResource": {
+                  "DepotPath": { "$type": "ResourcePath", "$storage": "string", "$value": "" },
+                  "Flags": "Default"
+                }
+              }
+            ],
+            "cookingPlatform": "PLATFORM_None",
+            "defaultAppearance": { "$type": "CName", "$storage": "string", "$value": "default" },
+            "entity": {
+              "HandleId": "0",
+              "Data": { "$type": "gameObject" }
+            },
+            "includes": [],
+            "resolvedDependencies": []
+          },
+          "EmbeddedFiles": []
+        }
+      }
+  - op: insert-xl-entry
+    path: "${input.sourceDir}/${input.entityName}.ent.json"
+    pointer: "Data.RootChunk.components.0.workspotResource.DepotPath.$value"
+    value: "${input.workspotResource}"
+  - op: patch-project
+    add:
+      outDir: "archive-staging"
+      steps:
+        - step: exec
+          id: "deserialize-${input.modSlug}-${input.entityName}"
+          command: wolvenkit-cli
+          args: ["convert", "deserialize", "${input.sourceDir}/${input.entityName}.ent.json", "-o", "${input.compiledDir}"]
+          expectOutputs: ["${input.compiledDir}/${input.entityName}.ent"]
+          before: stage
+templates: []
+satisfies:
+  - cp2077.vehicles.cr2w-unique-ids
+  - cp2077.vehicles.cr2w-resource-path-shape
+  - cp2077.vehicles.cr2w-gameversion-header
+manual:
+  - title: Spawn it and pose a puppet
+    steps:
+      - "Confirm the workspot exists in the install: lookup kind resource, path ${input.workspotResource}; a count of 0 means the pose will silently not play."
+      - "Build, then from a script (Codeware's DynamicEntitySystem, or exEntitySpawner.Spawn from the CET console) spawn mod\\\\${input.modSlug}\\\\${input.entityName}.ent at the puppet's transform, wait for the entity to resolve (one frame; two armed bridge requests), then WorkspotSystem.PlayInDeviceSimple(entity, puppet, false, n\"${input.componentName}\", n\"\", n\"\", 0.0, WorkspotSlidingBehaviour.DontPlayAtResourcePosition, null)."
+      - "IsActorInWorkspot(puppet) reads true only a frame after PlayInDeviceSimple, not in the same call; if the puppet stays standing with it true, the workspot's animation does not fit the puppet's rig (observed in game: a player-rig animation did nothing on the cutscene V, the woman-average one posed it) — pick a workspot authored for that rig, or SendJumpToAnimEnt a named animation from the set."
+      - "Release with WorkspotSystem.StopInDevice(puppet) before despawning the entity; a puppet left in a workspot whose device vanished keeps the pose."
+    expected: "The puppet holds the workspot's pose from the entity's position and facing, and StopInDevice returns it to its own animation."
+claim:
+  idSuffix: "${input.entityName}.poses"
+  claim: "mod\\${input.modSlug}\\${input.entityName}.ent spawns, and PlayInDeviceSimple on it with actorDataCompName ${input.componentName} puts a puppet into ${input.workspotResource}."
+testRows:
+  - gate: P-1
+    title: "Spawned workspot entity poses a puppet"
+    expected: "Through the bridge, spawn the entity at a spawned puppet, PlayInDeviceSimple, and read IsActorInWorkspot(puppet) true a request later; the pose is visible in game."
+    manual: true
+    probeKinds: []
+evidence: ["ModWright research"]

package/scaffolds/cyberpunk2077/sequences/iconic-weapon.yaml

@@ -0,0 +1,72 @@
+# iconic-weapon (Cyberpunk 2077) — the authoring sequence for a weapon mod:
+# a project, the kitbashed mesh, the item chain, and the world placement of
+# the prop that holds the acquisition. Each step names the asset it needs from the
+# modder at the point it needs it; `scaffold action=plan` asks for exactly
+# those and nothing is guessed. Applying a step is still `scaffold run`.
+id: cyberpunk2077.iconic-weapon
+game: cyberpunk2077
+title: Iconic weapon from nothing
+summary: Project, kitbashed mesh export, TweakXL item chain with its own blueprint and localization, and a world-placed prop for the acquisition.
+modType: weapon
+inputs:
+  - name: modName
+    prompt: "Mod name, used for the project and its r6/tweaks/<name> and scripts/<name> folders, e.g. MyWeapon."
+  - name: modSlug
+    prompt: "Lowercase depot folder name, used in every mod\\<slug>\\... path, e.g. myweapon."
+  - name: itemName
+    prompt: "Item name, used for the TweakDB record and LocKey namespace, e.g. MyWeapon."
+steps:
+  - id: project
+    scaffold: cyberpunk2077.new-project
+    title: The project file and source trees
+    skipIf: project-exists
+    inputs:
+      name: "${sequence.modName}"
+  - id: mesh
+    scaffold: cyberpunk2077.mesh-export-preset
+    title: The mesh export preset (Blender join-by-material export, WolvenKit import over a donor mesh)
+    inputs:
+      presetId: "${sequence.modSlug}"
+      exportScriptFile: "blender/export_${sequence.modSlug}.py"
+      glbOutputPath: "${stage}/${sequence.modSlug}.glb"
+      outputMeshDir: "archive-staging/${sequence.modName}/mod/${sequence.modSlug}/meshes"
+    assets:
+      - name: blend
+        prompt: "The editable .blend of the kitbash, parts kept as separate objects (e.g. blender/myweapon_kitbash_edit.blend). Path relative to the project."
+        inputs: [blendFile]
+      - name: donorMesh
+        prompt: "The staged vanilla .mesh WolvenKit imports the exported glb over, for its chunkMaterials and skinning (extract it from the base weapon's own archive; keep it under 65,535 vertices per submesh). Path relative to the project."
+        inputs: [baseMeshPath]
+  - id: chain
+    scaffold: cyberpunk2077.new-item-chain
+    title: The item chain (TweakXL record, its own blueprint with the iconic slot, factory row, localization, cloned .app)
+    inputs:
+      itemName: "${sequence.itemName}"
+      modSlug: "${sequence.modSlug}"
+      tweaksFile: "r6/tweaks/${sequence.modName}/${sequence.modSlug}.yaml"
+      xlFile: "archive-staging/${sequence.modName}.archive.xl"
+      factoryCsvFile: "archive-staging/${sequence.modName}/mod/${sequence.modSlug}/factory_parts.csv"
+      enUsSourceDir: "sources/${sequence.modSlug}"
+      entSourceDir: "sources/entities/${sequence.modSlug}"
+      entCompiledDir: "archive-staging/${sequence.modName}/mod/${sequence.modSlug}"
+    assets:
+      - name: appTemplate
+        prompt: "The cached template-record directory of the base weapon's own .app (template extract of the .app that weapons_appearances.csv maps the base's appearanceResourceName to, kind weapon-app; it must be the base's kind, or the game hangs on equip). The record.json + content.json directory path."
+        inputs: [entTemplate]
+      - name: icon
+        prompt: "The inventory icon: a PNG authored dark (the png→xbm import lifts gamma in game; power-curve the pixels, ~3.0) and the .inkatlas rectangle it occupies. Not a scaffold input; say where both went."
+  - id: place
+    scaffold: cyberpunk2077.new-sector-node
+    title: The world-placed prop that holds the acquisition (a case, a spec)
+    inputs:
+      outputDir: "archive-staging/${sequence.modName}/mod/${sequence.modSlug}/sectors"
+      outputPath: "archive-staging/${sequence.modName}/mod/${sequence.modSlug}/sectors/${sequence.modSlug}.streamingsector"
+    assets:
+      - name: sectorSource
+        prompt: "The mod's own .streamingsector JSON source (an entSpawner export run through WolvenKit's import script; category Exterior, level 1). Path relative to the project; it must already exist."
+        inputs: [file]
+      - name: propEntity
+        prompt: "Depot path of the .ent the node spawns (backslashes, lowercase), e.g. mod\\myweapon\\cache_case.ent, with an appearanceName the .ent actually declares (a wrong name spawns an invisible entity)."
+        inputs: [entityTemplatePath]
+evidence:
+  - cp2077.tweakdb.iconic-blueprint-required-for-mod-slot

package/scaffolds/cyberpunk2077/sequences/quickhack-takeover.yaml

@@ -0,0 +1,213 @@
+# quickhack-takeover (Cyberpunk 2077) — the authoring sequence for a mod that
+# takes an NPC over through a quickhack: a camera patched into NPC archetypes,
+# the control system's quickhack records, and its Mod Settings page.
+#
+# The `hack` step is FIVE `new-tweak` runs, because a quickhack is five records
+# and the plan runs `scaffold run` once per step (a step cannot be several
+# records). Four clone a vanilla `$base` — the objectActionUI interaction, the
+# status effect (the only bridge to script), the cyberdeck program, and the
+# hack itself — and the eligibility wrapper is a `$type: ObjectActionPrereq`
+# record with no base, written through new-tweak's `type` mode.
+#
+# The flats are FIXED here: this sequence records the shape of a working
+# takeover mod, so it encodes the takeover wiring rather than leaving the modder to
+# rediscover it. The four dependent records cross-link by
+# `${steps.<id>.ids.recordName}`, so each names exactly the record the earlier
+# step allocated. Values are that mod's own (memory cost 6, 30 s status duration,
+# Rare program) — a sensible takeover default; the modder edits the produced
+# yaml or tunes at runtime through the Mod Settings page. The flats are written
+# as natural block scalars and normalized to nest under the record by
+# new-tweak's `flats` `reindent`.
+#
+# Target-side registration: the hack only
+# appears on an NPC whose `objectActions` list names it (matched by actionName),
+# so the two `register-*` steps edit `Character.Interactable_NPC_Base` (humans)
+# and `Character.Mechanical_NPC_Base` (mechanicals) — the bases most NPCs
+# inherit their hack list from — with `objectActions: [!append <hack>]` through
+# `edit-tweak`. A handful of NPC families (arasaka, Cerberus,
+# drones, exos in the working mod's own tree) RE-DECLARE their own hack list
+# rather than inheriting; which ones is install-version-specific (found by
+# indexing the install), so registering the hack on those is left to the modder
+# as extra `edit-tweak` runs rather than hardcoded here.
+#
+# Localization: the three `loca-*` steps define the
+# `LocKey#${modName}-Name/-Description/-Ineligible` handles the records
+# reference, each through `new-localization` (one en-us on-screen entry, sharing
+# one source and one deserialize step across the three runs).
+#
+# ONE thing this sequence still does NOT do: the
+# scripted eligibility class `${modName}.${modName}TargetPrereq` is redscript
+# the modder writes; this sequence assumes that name in the wrapper's
+# prereqClassName (ModWright has no redscript scaffold yet).
+id: cyberpunk2077.quickhack-takeover
+game: cyberpunk2077
+title: Quickhack that takes an NPC over
+summary: A camera patched into NPC archetypes, the five-record quickhack chain (interaction, status effect, eligibility wrapper, the hack, the cyberdeck program), and a Mod Settings page.
+modType: quickhack
+inputs:
+  - name: modName
+    prompt: "Mod name, used for the project and its r6/tweaks/<name> and scripts/<name> folders, e.g. MyTakeover."
+  - name: modSlug
+    prompt: "Lowercase depot folder name, e.g. mytakeover."
+  - name: patchName
+    prompt: "File stem of the patch entity, e.g. npc_camera_patch."
+steps:
+  - id: project
+    scaffold: cyberpunk2077.new-project
+    title: The project file and source trees
+    skipIf: project-exists
+    inputs:
+      name: "${sequence.modName}"
+  - id: patch
+    scaffold: cyberpunk2077.new-entity-patch
+    title: The camera patched into the target archetypes
+    inputs:
+      modSlug: "${sequence.modSlug}"
+      patchName: "${sequence.patchName}"
+      component: camera
+      xlFile: "archive-staging/${sequence.modName}.archive.xl"
+      patchSourceDir: "sources/${sequence.modSlug}"
+      patchCompiledDir: "archive-staging/${sequence.modName}/mod/${sequence.modSlug}"
+    assets:
+      - name: targets
+        prompt: "The vanilla entity templates to patch, one depot path per line (backslashes, no leading slash, lowercase, .ent) — list them from the install's own archives, not from memory; a working takeover mod patched 426 human NPC archetypes."
+        inputs: [targets]
+  - id: interaction
+    scaffold: cyberpunk2077.new-tweak
+    title: The objectActionUI interaction (the hack's on-screen entry)
+    inputs:
+      file: "r6/tweaks/${sequence.modName}/${sequence.modSlug}.yaml"
+      recordName: "Interactions.${sequence.modName}Hack"
+      base: Interactions.BlindHack
+      flats: |
+        name: ${sequence.modName}Hack
+        caption: LocKey#${sequence.modName}-Name
+        description: LocKey#${sequence.modName}-Description
+        captionIcon: ChoiceCaptionParts.CyberwareMalfunctionIcon
+  - id: status-effect
+    scaffold: cyberpunk2077.new-tweak
+    title: The status effect the hack applies (the only bridge to script)
+    inputs:
+      file: "r6/tweaks/${sequence.modName}/${sequence.modSlug}.yaml"
+      recordName: "BaseStatusEffect.${sequence.modName}Takeover"
+      base: BaseStatusEffect.WasQuickHacked
+      flats: |
+        gameplayTags: [Debuff, Quickhack, ${sequence.modName}]
+        duration:
+          statModifiers:
+            - $type: ConstantStatModifier
+              statType: BaseStats.MaxDuration
+              modifierType: Additive
+              value: 30
+  - id: wrapper
+    scaffold: cyberpunk2077.new-tweak
+    title: The eligibility prereq wrapper ($type-only, no vanilla base)
+    inputs:
+      file: "r6/tweaks/${sequence.modName}/${sequence.modSlug}.yaml"
+      recordName: "Prereqs.${sequence.modName}TargetPrereq"
+      type: ObjectActionPrereq
+      flats: |
+        failureConditionPrereq:
+          - $type: IPrereq
+            prereqClassName: ${sequence.modName}.${sequence.modName}TargetPrereq
+        failureExplanation: LocKey#${sequence.modName}-Ineligible
+  - id: hack
+    scaffold: cyberpunk2077.new-tweak
+    title: The quickhack record (QuickHack.BaseBlindHack family), wiring the interaction, status effect and prereq
+    inputs:
+      file: "r6/tweaks/${sequence.modName}/${sequence.modSlug}.yaml"
+      recordName: "QuickHack.${sequence.modName}Hack"
+      base: QuickHack.BaseBlindHack
+      flats: |
+        actionName: ${sequence.modName}
+        priority: 1
+        objectActionUI: ${steps.interaction.ids.recordName}
+        costs:
+          - $base: QuickHack.MemoryCostControl
+            costMods:
+              - $base: QuickHack.MemoryMod
+                value: 6
+        completionEffects:
+          - !append
+            statusEffect: ${steps.status-effect.ids.recordName}
+            recipient: ObjectActionReference.Target
+        targetActivePrereqs:
+          - !append ${steps.wrapper.ids.recordName}
+  - id: program
+    scaffold: cyberpunk2077.new-tweak
+    title: The cyberdeck program item that carries the hack
+    inputs:
+      file: "r6/tweaks/${sequence.modName}/${sequence.modSlug}.yaml"
+      recordName: "Items.${sequence.modName}Program"
+      base: Items.BlindLvl1Program
+      flats: |
+        displayName: LocKey#${sequence.modName}-Name
+        localizedDescription: LocKey#${sequence.modName}-Description
+        quality: Quality.Rare
+        objectActions:
+          - ItemAction.ProgramDisassemble
+          - ${steps.hack.ids.recordName}
+        OnAttach:
+          - $type: GameplayLogicPackage
+            UIData:
+              iconPath: ability_utility
+              localizedName: LocKey#${sequence.modName}-Name
+              localizedDescription: LocKey#${sequence.modName}-Description
+  - id: register-humans
+    scaffold: cyberpunk2077.edit-tweak
+    title: Register the hack on human NPC hack lists (edits Character.Interactable_NPC_Base)
+    inputs:
+      file: "r6/tweaks/${sequence.modName}/${sequence.modSlug}.yaml"
+      recordName: Character.Interactable_NPC_Base
+      flats: |
+        objectActions:
+          - !append ${steps.hack.ids.recordName}
+  - id: register-mechanical
+    scaffold: cyberpunk2077.edit-tweak
+    title: Register the hack on mechanical NPC hack lists (edits Character.Mechanical_NPC_Base)
+    inputs:
+      file: "r6/tweaks/${sequence.modName}/${sequence.modSlug}.yaml"
+      recordName: Character.Mechanical_NPC_Base
+      flats: |
+        objectActions:
+          - !append ${steps.hack.ids.recordName}
+  - id: loca-name
+    scaffold: cyberpunk2077.new-localization
+    title: The player-facing name text (LocKey#<mod>-Name)
+    inputs:
+      modSlug: "${sequence.modSlug}"
+      xlFile: "archive-staging/${sequence.modName}.archive.xl"
+      enUsSourceDir: "sources/${sequence.modSlug}"
+      entCompiledDir: "archive-staging/${sequence.modName}/mod/${sequence.modSlug}"
+      secondaryKey: "${sequence.modName}-Name"
+  - id: loca-description
+    scaffold: cyberpunk2077.new-localization
+    title: The description text (LocKey#<mod>-Description)
+    inputs:
+      modSlug: "${sequence.modSlug}"
+      xlFile: "archive-staging/${sequence.modName}.archive.xl"
+      enUsSourceDir: "sources/${sequence.modSlug}"
+      entCompiledDir: "archive-staging/${sequence.modName}/mod/${sequence.modSlug}"
+      secondaryKey: "${sequence.modName}-Description"
+  - id: loca-ineligible
+    scaffold: cyberpunk2077.new-localization
+    title: The "ineligible target" text (LocKey#<mod>-Ineligible)
+    inputs:
+      modSlug: "${sequence.modSlug}"
+      xlFile: "archive-staging/${sequence.modName}.archive.xl"
+      enUsSourceDir: "sources/${sequence.modSlug}"
+      entCompiledDir: "archive-staging/${sequence.modName}/mod/${sequence.modSlug}"
+      secondaryKey: "${sequence.modName}-Ineligible"
+  - id: settings-trigger
+    scaffold: cyberpunk2077.new-mod-settings
+    title: The Mod Settings page — first setting (a trigger)
+    inputs:
+      file: "scripts/${sequence.modName}/${sequence.modSlug}_settings.reds"
+      className: "${sequence.modName}Settings"
+  - id: settings-multiplier
+    scaffold: cyberpunk2077.new-mod-settings
+    title: The Mod Settings page — second setting (a multiplier), added to the same class
+    inputs:
+      file: "scripts/${sequence.modName}/${sequence.modSlug}_settings.reds"
+      className: "${sequence.modName}Settings"
+evidence: ["ModWright research"]

package/scaffolds/stardewvalley/new-cp-patch.yaml

@@ -0,0 +1,106 @@
+# new-cp-patch (Stardew Valley). Appends one
+# patch to an existing pack's content.json, with LogName set, because
+# Content Patcher's troubleshooting guide says to "make sure you set a
+# LogName field ... and then search the SMAPI log file for that name".
+# Limited to the two file-backed actions (Load, EditImage): their required
+# fields are the same three (Target, FromFile, plus the action), every
+# other action needs a body this scaffold cannot author honestly without
+# the data index, and an Include is
+# one line by hand.
+#
+# The asset FromFile names is the author's to supply: this scaffold writes
+# no image. Until it exists, `stardewvalley.content.fromfile-exists` blocks
+# with the file's exact path, which is the scaffold's own next step
+# reported by the postcondition validate rather than a failure of it.
+id: stardewvalley.new-cp-patch
+game: stardewvalley
+title: New Content Patcher patch (Load or EditImage)
+summary: Append one Load or EditImage patch, with a LogName, to an existing pack's content.json; the FromFile asset is the author's to add under the pack.
+modTypes: [content-pack]
+needs: {}
+inputs:
+  # A `path`, not a `string`, for the same two reasons every other
+  # append-into-an-existing-file scaffold makes its destination one
+  # (cyberpunk2077 new-tweak's `file`, new-mod-settings' `file`): the folder
+  # has to be there already — `mustExist` refuses a typo before the
+  # insert-xl-entry op creates a stray content.json under it, outside every
+  # project source where no rule would ever see it — and the engine builds
+  # the ledger claim id from the first `string`/`index-ref` input, so leaving
+  # the pack folder first would give every patch in one pack the same claim
+  # id (a second run is then an idempotent authored→authored no-op that keeps
+  # the *first* patch's claim text; `core/ledger/status.ts`). `logName` is the
+  # input that actually distinguishes one run from the next.
+  - type: path
+    name: folder
+    mustExist: true
+    prompt: The pack folder holding content.json, relative to the project (e.g. "[CP] YourModName"); it must already exist.
+  - type: string
+    name: logName
+    prompt: LogName for the patch — the name to search the SMAPI log for.
+    pattern: "^[^\\r\\n]+$"
+  - type: enum
+    name: action
+    prompt: Load replaces the whole asset with FromFile; EditImage edits or overlays part of it.
+    values: [Load, EditImage]
+  - type: string
+    name: target
+    prompt: The asset name (no Content/ prefix, no extension, no language code), e.g. "Portraits/Abigail".
+    pattern: "^(?!Content/)[^\\\\]+(?<!\\.xnb|\\.png|\\.json|\\.tbin|\\.tmx)$"
+  - type: string
+    name: fromFile
+    prompt: The file to load, relative to the pack folder (the assets/ subfolder by convention), e.g. "assets/abigail.png".
+    default: "assets/example.png"
+ids: []
+emits:
+  # content.json must already exist (new-project writes it); a missing file
+  # would come back as a Changes-only document with no Format, which the
+  # format rule then blocks — the report says so rather than guessing one.
+  # The append re-serializes the whole document (`emit.ts`), so it parses the
+  # file as strict JSON: a content.json carrying the `//` comments or
+  # trailing commas Content Patcher's own reader tolerates (and the author
+  # guide's examples use) fails the run with a named parse error rather than
+  # being silently rewritten without them. Add that patch by hand.
+  - op: insert-xl-entry
+    path: "${input.folder}/content.json"
+    pointer: "Changes.-"
+    value:
+      LogName: "${input.logName}"
+      Action: "${input.action}"
+      Target: "${input.target}"
+      FromFile: "${input.fromFile}"
+templates: []
+# The rules the appended patch itself must pass. fromfile-exists is
+# deliberately not listed: it is expected to block until the asset is in
+# place (header comment), and a satisfies rule must come back clean.
+satisfies:
+  - stardewvalley.content.parses
+  - stardewvalley.content.format
+  - stardewvalley.content.changes-present
+  - stardewvalley.content.patch-action
+  - stardewvalley.content.patch-target
+  - stardewvalley.content.patch-fields
+  - stardewvalley.content.when-tokens
+manual:
+  - title: Add the asset
+    steps:
+      - "Put the image at <folder>/<fromFile>; for a Load it replaces the whole asset, so unpack the original with StardewXnbHack first to match its size."
+      - "Re-run validate: stardewvalley.content.fromfile-exists must no longer report the file."
+    expected: "validate is clean for the pack."
+  - title: Check in game
+    steps:
+      - "Launch through SMAPI, run `patch summary` in the console, and find the LogName in the table with applied = X."
+      - "If it is loaded but not applied, run `patch export \"<target>\"` to see what the game currently has for that asset."
+    expected: "The patch shows as loaded and applied under its LogName; the asset in game is the one from FromFile."
+claim:
+  idSuffix: patch
+  claim: "content.json in ${input.folder} carries a ${input.action} patch \"${input.logName}\" on ${input.target} from ${input.fromFile}."
+testRows:
+  - gate: S-1
+    title: "Patch applies"
+    expected: "`patch summary` lists the LogName with applied = X and the asset in game is the FromFile image."
+    manual: true
+    probeKinds: []
+evidence:
+  - "stardewvalley.contentpatcher.format.five-actions"
+  - "stardewvalley.contentpatcher.format.patch-fields"
+  - "stardewvalley.contentpatcher.format.patch-console-commands"