modwright 0.1.0

package/knowledge/cyberpunk2077/wolvenkit.cli.yaml

@@ -0,0 +1,167 @@
+game: cyberpunk2077
+topic: wolvenkit.cli
+title: WolvenKit.CLI commands ModWright runs — pack, import, convert serialize/deserialize
+facts:
+  - id: cp2077.wolvenkit.cli.pack-ignores-non-archive-files
+    claim: "`pack` only generates the `.archive` file(s) from a folder of REDengine files — it does not
+      behave exactly like WolvenKit's own \"Build Project\" button, and specifically ignores extra
+      files such as `.xl` manifests; those still need to land at their final path by some other step
+      (e.g. a plain file copy) alongside the packed archive."
+    status: community
+    source: CDPR-Modding-Documentation/WolvenKit-8-Wiki/wolvenkit-cli/usage/command-list.md, hint under
+      "Pack" ("It will only generate **.archive** file(s) and ignore any extra files (such as
+      **.xl**)"; the same hint also says the command does not behave exactly like the WolvenKit
+      application's `Build Project` button)
+    tags:
+      - wolvenkit
+      - cli
+      - pack
+      - .xl
+      - build-project
+      - gotcha
+  - id: cp2077.wolvenkit.cli.pack-multiple-paths-one-output-dir
+    claim: "`pack` accepts two invocation forms: `pack -p <path> [-o output]` (backward-compatible
+      single-path form) and `pack [-o output] <path1> <pathN>` (multiple project paths, each
+      producing its own `.archive`); when packing multiple projects at once only a single output
+      directory can be given for all of them — the wiki attributes this limitation to .NET."
+    status: community
+    source: CDPR-Modding-Documentation/WolvenKit-8-Wiki/wolvenkit-cli/usage/command-list.md, section
+      "Pack" ("Usage" and the warning under "Example")
+    tags:
+      - wolvenkit
+      - cli
+      - pack
+      - multiple-paths
+      - output-directory
+  - id: cp2077.wolvenkit.cli.pack-must-not-replace-vanilla-archives
+    claim: The `pack` command's documentation carries an explicit warning not to replace existing
+      vanilla archives with its output.
+    status: community
+    source: CDPR-Modding-Documentation/WolvenKit-8-Wiki/wolvenkit-cli/usage/command-list.md, danger hint
+      under "Pack" ("Do not replace existing vanilla archives")
+    tags:
+      - wolvenkit
+      - cli
+      - pack
+      - vanilla-archive
+      - safety
+  - id: cp2077.wolvenkit.cli.import-keep-flag-needs-matching-pair
+    claim: "`import`'s `-k`/`--keep` flag (used to preserve existing REDengine files' data when
+      importing raw files over them) requires that both halves of a matching pair already exist in
+      the output — e.g. both `judy_body_wet.xbm` and `judy_body_wet.dds` — and when `-o` is used,
+      the existing REDengine files must be located in that output folder while the raw source files
+      are read from the path given by `-p`."
+    status: community
+    source: CDPR-Modding-Documentation/WolvenKit-8-Wiki/wolvenkit-cli/usage/command-list.md, section
+      "Import" (hint under the command)
+    tags:
+      - wolvenkit
+      - cli
+      - import
+      - keep-flag
+      - gotcha
+    detail: "RELATED: this documents the same `-k`/`--keep` flag as cp2077.toolchain.cli-import-flag,
+      but the wiki does not state what `-k` actually preserves beyond requiring the matching-pair
+      precondition — that fact's \"preserves the donor's material bindings\" reading remains an
+      inference from a mod's build pipeline, not confirmed by this page either."
+  - id: cp2077.wolvenkit.cli.convert-serialize-deserialize-flags
+    claim: '`convert -s "<path>"` converts a REDengine (CR2W) file into its human-readable (json) form;
+      `convert -d "<path>"` converts a json file back into a REDengine file. The older `cr2w
+      -s`/`cr2w -d` command spelling does the same thing but is documented as deprecated in favor of
+      `convert`.'
+    status: community
+    source: CDPR-Modding-Documentation/WolvenKit-8-Wiki/wolvenkit-cli/usage/command-list.md, sections
+      "~~CR2W/W2RC~~ (Deprecated)" and "Convert"
+    tags:
+      - wolvenkit
+      - cli
+      - convert
+      - serialize
+      - deserialize
+      - cr2w
+      - deprecated
+    detail: "RELATED: grounds the direction of cp2077.toolchain.cli-convert-serialize (binary->json) and
+      cp2077.toolchain.cli-convert-deserialize (json->binary) in the actual CLI flags (`-s` and
+      `-d`) — those two facts describe a mod's pipeline usage without naming the flags."
+  - id: cp2077.wolvenkit.cli.tweak-command-flats-and-groups
+    claim: The `tweak` command compiles a `.tweak` yaml file (with top-level `flats` and/or `groups`
+      keys) into a TweakDB `.bin` loadable by TweakDBext; for a `groups` entry, member flats are
+      auto-generated by appending each member's name to the record's own name (e.g. a
+      `MyRecord.mine` group with an `affiliation` member yields flat `MyRecord.mine.affiliation`),
+      and the compiler does not validate that a group's `type` is a real TweakDB type — an unknown
+      type only surfaces later, as a message in `red4ext\logs\tweakdb.log` when TweakDBext loads the
+      resulting `.bin`.
+    status: community
+    source: CDPR-Modding-Documentation/WolvenKit-8-Wiki/wolvenkit-cli/usage/command-list.md, section
+      "Tweak"
+    tags:
+      - wolvenkit
+      - cli
+      - tweak
+      - flats
+      - groups
+      - tweakdbext
+      - silent-failure
+    detail: This `tweak`/TweakDBext path is a different pipeline from TweakXL's yaml tweaks
+      (cp2077.tweakxl.yaml-syntax.*) — TweakDBext compiles to a binary TweakDB patch loaded
+      independently of TweakXL, so a fact about one does not transfer to the other without checking
+      which pipeline a given project actually uses.
+  - id: cp2077.wolvenkit.cli.tweak-type-name-drops-gamedata-and-record-suffix
+    claim: A TweakDB group's `type` value is the RTTI record type name with the `gamedata` prefix and
+      `_Record` suffix both dropped — e.g. RTTI type `gamedataVehicle_Record` is written as
+      `Vehicle` in `.tweak` yaml.
+    status: community
+    source: CDPR-Modding-Documentation/WolvenKit-8-Wiki/wolvenkit-cli/usage/command-list.md, section
+      "Tweak > Groups" (naming rule and Vehicle example)
+    tags:
+      - wolvenkit
+      - cli
+      - tweak
+      - naming-convention
+      - rtti
+  - id: cp2077.wolvenkit.cli.tweak-supported-flat-types
+    claim: "`.tweak` yaml flats and group members must declare a base `type` from a fixed list: `CName`,
+      `String`, `TweakDBID`, `raRef:CResource`, `Float`, `Bool`, `Uint8/16/32/64`, `Int8/16/32/64`,
+      `Color`, `EulerAngles`, `Quaternion`, `Vector2`, `Vector3`, `LocKey`; any of these can be
+      wrapped as `array:<Type>` to declare an array field."
+    status: community
+    source: CDPR-Modding-Documentation/WolvenKit-8-Wiki/wolvenkit-cli/usage/command-list.md, section
+      "Tweak > Types"
+    tags:
+      - wolvenkit
+      - cli
+      - tweak
+      - type
+      - schema
+    detail: "`TweakDBID` values can be written as the full flat/group path (e.g. `myOtherFlat.cow`) or
+      as the shorthand hash/length form `TDBID:12345678:12`; `raRef:CResource` also accepts a raw
+      integer hash (e.g. pulled from a TweakDB dump) in place of a string path."
+  - id: cp2077.wolvenkit.cli.pack-is-not-byte-deterministic
+    claim: "WolvenKit CLI 8.20.0 `pack` of an unchanged tree does not reproduce the same bytes: two
+      packs are the same size and differ in a few dozen bytes near the end of the file, so a sha256
+      compare cannot tell an unchanged repack from a real change."
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - wolvenkit
+      - cli
+      - pack
+      - determinism
+      - deploy
+    detail: "Where the differing bytes sit (after the file data) suggests per-entry timestamps in the
+      archive's file table; that is inferred, not read. Consequence: deploy's skip-identical check
+      redeploys a repacked archive whose content did not change."
+  - id: cp2077.wolvenkit.cli.archive-list-prints-backslash-paths
+    claim: "`archive <file> -l` prints one depot path per line with backslash separators
+      (`mod\\<modname>\\en-us.json`), so a glob written with `/` must match either separator."
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - wolvenkit
+      - cli
+      - archive
+      - listing
+      - verify-listing
+      - glob

package/knowledge/cyberpunk2077/workspot.system.yaml

@@ -0,0 +1,55 @@
+game: cyberpunk2077
+topic: workspot.system
+title: WorkspotGameSystem - the play-in-device signatures
+facts:
+  - id: cp2077.workspot.system.playindevicesimple-signature
+    claim: "WorkspotGameSystem.PlayInDeviceSimple is declared as PlayInDeviceSimple(device:
+      ref<GameObject>, actor: ref<GameObject>, allowCameraMov: Bool, opt actorDataCompName: CName,
+      opt deviceDataCompName: CName, opt syncSlotName: CName, opt slideTime: Float, opt
+      slideBehaviour: WorkspotSlidingBehaviour, opt callbackEventRecipient: ref<Entity>). The third
+      argument is allowCameraMov: it is not a freeze-on-end flag."
+    status: verified
+    verified_on: "2.31"
+    source: codeberg adamsmasher/cyberpunk@a2e6bb3 orphans.swift:18383
+    tags:
+      - workspot
+      - playindevicesimple
+      - allowcameramov
+      - signature
+    detail: A quickhack mod plays V's jack-in kneel with true; a freezeOnEnd reading of the argument,
+      adopted and reverted on 2026-09-21, was wrong. The fourth argument is what a script passes as
+      the component name (that mod's own workspot component).
+  - id: cp2077.workspot.system.playindevice-signature
+    claim: "WorkspotGameSystem.PlayInDevice is declared as PlayInDevice(device: ref<GameObject>, actor:
+      ref<GameObject>, opt workspotStateFlavourName: CName, opt actorDataCompName: CName, opt
+      deviceDataCompName: CName, opt syncSlotName: CName, opt slideTime: Float, opt slideBehaviour:
+      WorkspotSlidingBehaviour, opt callbackEventRecipient: ref<Entity>); unlike PlayInDeviceSimple
+      it has no camera-movement flag and takes a workspot state flavour name instead."
+    status: verified
+    verified_on: "2.31"
+    source: codeberg adamsmasher/cyberpunk@a2e6bb3 orphans.swift:18385
+    tags:
+      - workspot
+      - playindevice
+      - signature
+  - id: cp2077.workspot.system.resource-without-anim-graph-crashes-on-play
+    claim: "A workWorkspotResource that carries only its workspotTree (no rootNode, empty nodesToInit
+      and animFeatures, no variables container, no staticCommandsRig) deserializes with WolvenKit
+      8.20, and its entity spawns. Playing V into it with PlayInDeviceSimple crashes the game in the
+      same frame: an access violation reading 0x44 at exe+0x4B2A1D, the entry of a routine called
+      with a null object. The same workspot with a vanilla workspot's layout (rootNode →
+      animAnimNode_Root → animAnimNode_Output → animAnimNode_WorkspotHub, nodesToInit holding the
+      three, the animAnimFeatureUpdateWorkspot feature named UpdateWorkspot, an empty
+      animAnimVariableContainer, staticCommandsRig) plays."
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - workspot
+      - resource
+      - animgraph
+      - crash
+      - authoring
+    detail: A quickhack mod's build script writes the layout by hand; its key set matches the vanilla
+      q104 workspot's key for key. The animSetup hash stays 0 in the mod's resources and they play,
+      so the hash is not required.

package/knowledge/cyberpunk2077/world.interactions.yaml

@@ -0,0 +1,41 @@
+game: cyberpunk2077
+topic: world.interactions
+title: Native Interactions Framework
+facts:
+  - id: cp2077.world.interactions.dependency-and-install-path
+    claim: Native Interactions Framework requires Red4Ext, CET, Codeware, Redscript and ArchiveXL
+      installed first, plus World Builder "if you want to place interactions which use props".
+      Installed correctly it produces the folder `Cyberpunk
+      2077\bin\x64\plugins\cyber_engine_tweaks\mods\nativeInteractions`.
+    status: community
+    source: wiki.redmodding.org "Installation" (Native Interactions Framework), sections "Requirements",
+      "Download" and "Installing" (info hint)
+    tags:
+      - nif
+      - native-interactions-framework
+      - dependency
+      - install-path
+    detail: The page names no version floors for any of the five dependencies. It is installed like any
+      other mod, by extracting into the base game directory (the one "called `Cyberpunk 2077` and
+      contains the folders `bin` and `archive`"). Page title corrected 2026-09-07 — the page is
+      simply "Installation" under the Native Interactions Framework section.
+  - id: cp2077.world.interactions.basic-interaction-fields
+    claim: A Simple Interaction (one that needs no props) is edited from the "Cog" icon beside its name,
+      in the "Edit Interaction" tab. `Icon Position` controls where the icon is; `Icon Visibility
+      Range` how close the player must be for the icon to show; `Interaction Range` how close for
+      the interaction prompt to show; `Interaction Angle` how close the screen centre / crosshair
+      must be to the icon for the prompt to show ("Smaller means closer"). `Workspot Position` and
+      `Workspot Orientation` control where and in what rotation an animation plays, and are
+      available only for interactions that play an animation at a specific position.
+    status: community
+    source: wiki.redmodding.org "Interaction Settings" (Native Interactions Framework), sections
+      "Editing Interactions", "Icon" and "Workspot Position"
+    tags:
+      - nif
+      - native-interactions-framework
+      - interaction-settings
+      - workspot
+    detail: "\"When using any positional controls, you can hold down 'Shift' to switch to precision
+      mode.\" For Workspot Orientation, \"Usually the green arrow points inwards\". Page title and
+      section names corrected 2026-09-07 (there is no \"Basic Interaction Configuration Fields\"
+      page and no \"Key Gotchas\" heading)."

package/knowledge/cyberpunk2077/world.loot-container.yaml

@@ -0,0 +1,167 @@
+game: cyberpunk2077
+topic: world.loot-container
+title: A lootable Arasaka weapon case — placement, drop table, and deploy safety
+facts:
+  - id: cp2077.world.loot-container.cache-drops-weapon-directly
+    claim: A weapon mod's Arasaka cache loot table drops the weapon itself (Items.<ModWeapon>, quality
+      Quality.Random) directly, because the mod ships no crafting spec for a recipe to resolve
+      against.
+    status: contradicted
+    source: ModWright research
+    tags:
+      - world
+      - cache
+      - loot
+      - recipe
+      - retracted
+    detail: "This was true when written (2026-09-02) and is now stale: a full tiered crafting-spec layer
+      was added the next day. Superseded by cp2077.world.loot-container.cache-drops-tiered-recipe.
+      The mod's own cache notes were not edited to reflect this — a later entry in its plan says so
+      explicitly."
+  - id: cp2077.world.loot-container.cache-drops-tiered-recipe
+    claim: A weapon mod's Arasaka cache loot table (LootTables.<ModCacheLoot>) drops one of five tiered
+      crafting recipes (Items.Recipe_<Tier>_<ModWeapon>, Common through Legendary), each gated by a
+      LootPrereqs.CraftedIconicWeaponRecipePrereq_<Tier> level-band prerequisite so exactly one
+      resolves per player level — mirroring vanilla's own iconic-spec drop pattern — not a direct
+      weapon drop.
+    status: inferred
+    source: ModWright research
+    tags:
+      - world
+      - cache
+      - loot
+      - recipe
+      - tiered
+    supersedes: cp2077.world.loot-container.cache-drops-weapon-directly
+    detail: "The mod's own notes on the change: the comment in the loot table had said the mod ships no
+      crafting spec, which was now false. The rewrite added Items.$(tier)_<ModWeapon> crafting
+      results, an Items.Recipe_Preset_<ModWeapon> base and Items.Recipe_$(tier)_<ModWeapon>
+      instances (with hideOnItemsAdded so a crafted recipe disappears once used) — the same
+      crafting-spec pattern used by a ranged weapon mod and Silent Ashura, added one day after the
+      cache's initial build and drop-table design."
+  - id: cp2077.world.loot-container.vanilla-case-mesh-already-has-arasaka-livery
+    claim: The vanilla lootable_weapon_case_medium_neomilitary_a[_lid].mesh assets already carry four
+      material appearances — default, arasaka, militech, toolbox — including a complete Arasaka
+      livery (its own multilayered mlsetup plus xx_decals_arasaka_d01[_arasaka] decal materials),
+      but no vanilla .app exposes the arasaka appearance; a two-component .app selecting
+      meshAppearance = arasaka is the only custom asset needed to ship an Arasaka-branded lootable
+      case.
+    status: inferred
+    source: ModWright research
+    tags:
+      - world
+      - cache
+      - mesh
+      - appearance
+      - arasaka
+      - livery
+    detail: No mesh work and no textures were needed for this asset — a significant cost reduction
+      versus a from-scratch container.
+  - id: cp2077.world.loot-container.chip-container-too-small-for-blade
+    claim: arasaka_chip_container_a, the other genuinely Arasaka-branded container in the game, measures
+      0.14 x 0.04 x 0.11 m — a shard case, effectively invisible in the world and far too small to
+      plausibly hold a 1.28 m blade — and was rejected as the cache container in favor of the medium
+      weapon case.
+    status: inferred
+    source: ModWright research
+    tags:
+      - world
+      - cache
+      - mesh
+      - measurement
+      - rejected
+    detail: The chosen lootable_weapon_case_medium_neomilitary_a is 1.28 m long, matching the weapon.
+  - id: cp2077.world.loot-container.case-mesh-long-axis-is-local-x-not-forward
+    claim: For the medium lootable weapon case mesh, the body origin sits on the BASE (local Z spans
+      0.000..0.171) and the case's long axis is its local X (1.259 m) rather than local Y — even
+      though an entity's forward direction is local +Y. A case built straight from a captured player
+      transform therefore lies with its long side running ACROSS the captured facing, like a case
+      set down in front of the player, not end-on; a yawOffsetDeg of 90 rotates it to lie end-on
+      instead.
+    status: inferred
+    source: ModWright research
+    tags:
+      - world
+      - cache
+      - mesh
+      - orientation
+      - placement
+    detail: Measured directly off the mesh bounds, not guessed. The lid mesh's own bounds (Y out to
+      0.506, Z down to -0.046) are explicitly called out as NOT meaningful for placement — they are
+      in the lid's own hinge frame, positioned and animated by the .app component transform and the
+      TransformAnimator, and should be ignored when reasoning about the case's world footprint.
+  - id: cp2077.world.loot-container.transformanimator-kept-because-vanilla-meshes-unmodified
+    claim: "Also observed on a second mod, as the contrasting case to
+      cp2077.entities.transform-animator-open-anim (documented on a ranged weapon mod, which had to
+      strip its gameTransformAnimatorComponent because a custom, longer lid floated incorrectly in
+      the donor's open pose): a lootable Arasaka case KEEPS the TransformAnimator intact and its lid
+      opens correctly, because both of its case meshes are used completely unmodified from vanilla.
+      The animator only has to be removed when the geometry it swings has been altered."
+    status: inferred
+    source: ModWright research
+    tags:
+      - world
+      - cache
+      - transform-animator
+      - lid
+      - mesh
+    detail: Contrast case for the existing fact cp2077.entities.transform-animator-open-anim / the
+      process lesson about removing vs. keeping the animator — here the animator survives because
+      the geometry it swings was never altered.
+  - id: cp2077.world.loot-container.placement-captured-via-cet-console-oneliner
+    claim: A world-placement position + orientation can be captured directly in the exact JSON shape a
+      placement file expects, by standing at the target spot in game and pasting a short CET console
+      Lua one-liner that reads Game.GetPlayer():GetWorldPosition()/GetWorldOrientation() and
+      string.formats them as x/y/z/rotation{i,j,k,r} fields.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - world
+      - cache
+      - placement
+      - cet
+      - console
+      - workflow
+    detail: The player's own transform is used AS the object's transform ("think of it as standing in
+      for the case"), which is why
+      cp2077.world.loot-container.case-mesh-long-axis-is-local-x-not-forward's yawOffsetDeg
+      correction is necessary — the player's forward is not the case's long axis. Re-siting is then
+      one edit to placement.json plus a script rerun, no second in-game trip needed unless the spot
+      itself was wrong.
+  - id: cp2077.world.loot-container.three-artifacts-must-deploy-together
+    claim: Deploying a world-placed lootable container requires three artifacts to move together — the
+      archive (holding the .app/.ent/sector/block), the archive's .xl manifest (holding the
+      `streaming:` block REGISTRATION), and the tweaks yaml (loot table + crafting specs); if the
+      archive is redeployed but the .xl is left at an older version, the container silently fails to
+      appear even though the archive itself contains everything needed.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - world
+      - cache
+      - deploy
+      - archivexl
+      - manifest
+      - silent-failure
+    detail: "Named as an actual incident: \"This is exactly what went wrong on 2026-09-03: archive
+      packed, .xl left at its 08-19 version.\" The mod's deploy script now gates on this by grepping
+      the deployed .xl for a `streaming:` line and throwing if it is missing."
+  - id: cp2077.world.loot-container.deploy-verifies-with-md5-not-mtime
+    claim: A mod's archive deploy scripts verify a successful copy by comparing MD5 hashes of source and
+      destination (not file size or modification time), and only create a rollback backup of the
+      previously-live archive when its hash actually differs from the incoming one.
+    status: inferred
+    source: ModWright research
+    tags:
+      - world
+      - cache
+      - deploy
+      - md5
+      - rollback
+      - verification
+    detail: Rollback copies are hash-verified immediately after being written (throws "rollback copy
+      mismatch" if the backup itself doesn't match), and the final live-archive copy is
+      hash-compared against the staged source before the script reports success. Consistent with the
+      same hash-over-mtime discipline used in mesh deploy (see
+      cp2077.anims.method.identify-builds-by-anims-md5-never-mtime and
+      cp2077.anims.method.copy-live-archive-to-rollback-before-every-deploy).

package/knowledge/cyberpunk2077/world.sectors.yaml

@@ -0,0 +1,233 @@
+game: cyberpunk2077
+topic: world.sectors
+title: Sector structure, streaming blocks, and world placement
+facts:
+  - id: cp2077.sectors.entspawner-export-format
+    claim: entspawner export json is a recipe format, not a final sector; it reveals sector and
+      descriptor configuration (category, level, streaming fields, appearance names) that can be
+      used to build a correct hand-authored sector.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - entspawner
+      - export
+      - recipe
+      - sector
+      - reference
+    detail: "A vanilla suitcase was placed in game with entSpawner (worldBuilder v1.0.81, installed from
+      GitHub after the old install turned out to be a hollow Vortex skeleton) and project
+      \"malorian\" was exported to bin\\...\\mods\\entSpawner\\export\\malorian_exported.json. The
+      export gave category \"Exterior\" level 1, the full appearance name
+      suitcase_small_neomilitary_a, the placement (-835.758, 328.628, 7.884) and the streaming
+      values. It did not by itself fix the placement: what finally shipped was the sector GENERATED
+      by WolvenKit GUI's official entSpawner import script, with the loot instanceData injected into
+      it by a script; the hand-authored sector was abandoned."
+  - id: cp2077.sectors.sector-category-alwaysloaded
+    claim: A modded streaming sector and its streamingblock descriptor for a world placement use
+      category AlwaysLoaded at level 0.
+    status: contradicted
+    source: ModWright research
+    tags:
+      - sector
+      - descriptor
+      - category
+      - level
+      - always-loaded
+      - retracted
+    detail: "This was the hand-authored guess: the mod's sector build script started from a donor
+      descriptor selected by `category == \"AlwaysLoaded\"` and the early cache architecture is
+      described in its notes as \"one AlwaysLoaded descriptor\". The entSpawner export showed the
+      vanilla-tool value is Exterior/1. Superseded by cp2077.sectors.sector-category-level."
+  - id: cp2077.sectors.sector-category-level
+    claim: Sector descriptors have category and level fields; "Exterior" category with level 1 is
+      correct for outdoor world placements; always-loaded category with level 0 causes invisible
+      entities.
+    status: inferred
+    source: ModWright research
+    tags:
+      - sector
+      - descriptor
+      - category
+      - level
+      - exterior
+      - always-loaded
+    supersedes: cp2077.sectors.sector-category-alwaysloaded
+    detail: Early builds used AlwaysLoaded/0 and entities were invisible; the switch to Exterior/1 came
+      from the entSpawner export and ships in the working mod. Two candidate causes of the
+      invisibility (category/level and a wrong appearanceName) were changed at the same time, so
+      neither is proven to be the cause. The mod's notes call them "the likely invisibility causes".
+  - id: cp2077.sectors.streaming-block-json-structure
+    claim: A .streamingblock json file contains descriptor entries; each descriptor references a
+      .streamingsector file path and specifies load behavior (category, level, streaming fields).
+    status: inferred
+    source: ModWright research
+    tags:
+      - streaming-block
+      - json
+      - descriptor
+      - sector
+    detail: "The shipped block is malorian\\all.streamingblock, referencing
+      malorian\\sectors\\malorian.streamingsector, and it is registered in the mod's .archive.xl
+      under `streaming: blocks:`. The mod's older notes still name the abandoned hand-authored paths
+      mod\\<modname>\\<mod>.streamingblock and mod\\<modname>\\<mod>.streamingsector; the .xl
+      manifest is the ground truth."
+  - id: cp2077.sectors.streaming-sector-node-data
+    claim: A .streamingsector json file contains worldEntityNode entries with nodedata objects; each
+      nodedata specifies position, rotation, appearance, streaming distance, and interaction chunks.
+    status: inferred
+    source: ModWright research
+    tags:
+      - streaming-sector
+      - world-entity-node
+      - nodedata
+    detail: "The two halves are separate: `nodes[]` holds the worldEntityNode (entityTemplate,
+      appearanceName, instanceData with the loot chunk), while `nodeData[]` holds one transform
+      entry per node, matched by NodeIndex. A shipped cache sits at the old Malorian factory site on
+      the City Center NE waterfront, given as approximately (-836, 329)."
+  - id: cp2077.sectors.node-appearance-name-full
+    claim: Sector node appearanceName must be the full internal appearance name; using "default",
+      partial names, or typos produces invisible entities with no log error.
+    status: inferred
+    source: ModWright research
+    tags:
+      - node
+      - appearance-name
+      - appearance
+      - invisible
+      - silent-failure
+    detail: "The name must RESOLVE to an appearance that exists in the referenced entity: the vanilla
+      control node needs suitcase_small_neomilitary_a, while the custom node ships with
+      appearanceName \"default\" and works, because the custom case's .app defines an appearance
+      literally named \"default\". So the rule is \"the appearance's real name\", not \"never
+      default\"."
+  - id: cp2077.sectors.control-node-testing
+    claim: When diagnosing sector issues, place a vanilla entity node alongside the custom one as a
+      control; comparing render and loot outcomes isolates whether the bug is in the custom entity
+      or the sector structure.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - testing
+      - control
+      - diagnosis
+      - node
+      - sector
+    detail: "The technique was actually run in game: node 0 = the custom Malorian case, node 1 = an
+      untouched vanilla suitcase +1.5m in x, both carrying the same loot instanceData. What it
+      settled was that hand-authored sectors were a dead end — the experiment's \"Still
+      invisible/unlootable\" branch fired (conclusion: stop hand-authoring), and the placement was
+      redone through the official entSpawner import. It did not, as an earlier version of this fact
+      claimed, narrow the bug to the appearance chain."
+  - id: cp2077.sectors.custom-ent-vs-vanilla-control
+    claim: If custom entity is invisible while vanilla control renders, the bug is in the custom .ent
+      appearance chain or resource paths; if vanilla loots but custom doesn't, the bug is in
+      interaction chunks or physics.
+    status: unverified
+    source: ModWright research
+    tags:
+      - diagnosis
+      - entity
+      - loot
+      - appearance
+      - physics
+    detail: This is the decision tree written before the run, not a result. The branch that actually
+      fired was the third one — still invisible/unlootable — so neither inference in the claim was
+      exercised.
+  - id: cp2077.sectors.no-node-transforms-in-import
+    claim: When importing a sector or entity json, wolvenkit does not apply or read node transform
+      (position/rotation) data; transforms must be embedded in vertex positions during mesh export
+      (blender transform_apply).
+    status: unverified
+    source: ModWright research
+    tags:
+      - transform
+      - sector
+      - import
+      - node
+      - vertex
+    detail: "Treat with suspicion: the sector's own Position/Orientation/Pivot fields ARE the world
+      placement and are honoured (per the mod's sector build script, and moving the case is
+      described as editing X/Y/Z and rebuilding). The lesson is about GLB mesh import only."
+  - id: cp2077.sectors.streaming-field-values-from-export
+    claim: Streaming field values (MaxStreamingDistance, UkFloat1, Uk10, Uk11) should be taken directly
+      from entspawner export rather than guessed; exact values ensure proper load/unload behavior at
+      distance.
+    status: inferred
+    source: ModWright research
+    tags:
+      - streaming
+      - fields
+      - distance
+      - values
+      - export
+      - nodedata
+    detail: MaxStreamingDistance 120, UkFloat1 100, Uk10 1056, Uk11 512. These are nodeData fields, one
+      entry per node. The mod's notes are explicit that they "already matched" the hand-authored
+      values, so they were never a cause of the invisibility; the meaning of the Uk fields is
+      undocumented. The advice to copy rather than estimate is the author's, not a measured result.
+  - id: cp2077.sectors.sector-json-file-uniqueness
+    claim: All handleid and bufferid values in a sector json file must be unique across the entire file
+      (not just per node); a duplicate anywhere causes silent deserialization failure.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - sector
+      - json
+      - uniqueness
+      - handleid
+      - bufferid
+    detail: The fields are spelled HandleId and BufferId in the CR2W json. The observed failure was a
+      duplicate BufferId "1" on the second node, which broke deserialization with "a useless generic
+      JsonException at the buffer's closing brace". The scripts step around it by assigning explicit
+      unique values (HandleId "980"/"500", BufferId "2"/"9"). The duplicate-HandleId half of the
+      rule is stated in the mod's notes but no failure from it is recorded. This is a WolvenKit
+      deserializer behaviour, not an engine observation.
+  - id: cp2077.sectors.instance-data-loot-field
+    claim: Sector node instanceData field carries loot configuration (loot-tables, loot-quality,
+      display-name); presence of instanceData is necessary but not sufficient for looting (also
+      requires LootContainerObjectAnimatedByTransform chunk in the entity itself).
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - sector
+      - instance-data
+      - loot
+      - configuration
+    detail: Exact field names are lootTables, lootQuality, containerType and displayName inside the
+      instanceData buffer's LootContainerObjectAnimatedByTransform chunk. The shipped injection sets
+      lootTables [LootTables.<ModCacheLoot>], lootQuality Legendary and containerType
+      ClothingContainer on the sector node, while cache_case.ent carries its own lootTables,
+      contentAssignment, lootQuality and displayName LocKey#<Mod>-Cache-Name. Both layers ship in
+      the working case.
+  - id: cp2077.sectors.raycasting-vs-vertex-sampling
+    claim: When placing objects relative to mesh geometry (e.g., a plaque on a case lid), use
+      raycast-based placement rather than vertex sampling; vertex sampling fails on large flat
+      faces.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - placement
+      - raycast
+      - vertex-sampling
+      - mesh
+    detail: A build script places an embossed plaque by raycast. The mod's notes call the
+      vertex-sampling failure a "recurring trap". This is a Blender-side authoring lesson, not an
+      in-game observation.
+  - id: cp2077.sectors.pivot-point-precision
+    claim: When rotating mesh geometry (e.g., closing a case lid via 180° Z-axis spin), the pivot point
+      must be at the exact rotation axis; a misplaced pivot produces visible gaps or misalignment.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - pivot
+      - rotation
+      - geometry
+      - alignment
+      - lid
+    detail: The vanilla gun-case meshes are authored OPEN and exterior-up, so closing the lid is a 180°
+      spin about Z plus a translate onto the bottom (an earlier X-axis fold put it exterior-down).
+      The lid animation shipped in v1.0.0, so the pivot is confirmed in game.