modwright 0.1.0

package/knowledge/cyberpunk2077/tweakxl.hotreload.yaml

@@ -0,0 +1,151 @@
+game: cyberpunk2077
+topic: tweakxl.hotreload
+title: TweakXL's Reload() hot-reload entry point and what it does under the hood
+facts:
+  - id: cp2077.tweakxl.hotreload.reload-scripted-entry-point
+    claim: TweakXL exposes a scripted static class whose RTTI name is `App::Project::Name` = "TweakXL"
+      and whose native implementation is `App::Facade`; `App::Facade::Reload()` is the
+      RTTI-registered method backing a scripted `TweakXL.Reload()` call, and that call resolves from
+      the CET console and runs a full load, usage-report and issue-check cycle.
+    status: verified
+    verified_on: "2.31"
+    source: psiberx/cp2077-tweak-xl@f8da6be src/App/Facade.hpp:7-23 (class declaration, `Reload()` at
+      :18) and :26-39 (`RTTI_DEFINE_CLASS(App::Facade, App::Project::Name, ...)` with
+      `RTTI_METHOD(Reload)` at :36); config/Project.hpp.in:12 (`constexpr auto Name = "${NAME}"`);
+      xmake.lua:50 (`set_configvar("NAME", "TweakXL")`)
+    tags:
+      - tweakxl
+      - hot-reload
+      - reload
+      - redscript
+      - rtti
+    detail: "Checked against the source (2026-09-08): an earlier wording also said \"there is no
+      separate console command — it is invoked as a scripted static function call, e.g. from the CET
+      console\". Neither the header, the xmake file nor the Facade implementation says anything
+      about a console, CET or otherwise; that was the drafter's own illustration and is removed
+      here. What the source does show is only that `Reload` is registered as an RTTI method on a
+      scripted class, i.e. callable from any scripting surface that can reach RTTI statics. The CET
+      console is one such surface, confirmed live 2026-09-09 with TweakXL 1.11.4: `TweakXL.Reload()`
+      typed in the console resolved without error."
+  - id: cp2077.tweakxl.hotreload.reload-does-three-things
+    claim: "`App::Facade::Reload()` calls, in order, `TweakService::LoadTweaks()`,
+      `TweakService::ReportUsage()` and `TweakService::CheckForIssues()` — hot reload re-runs the
+      full tweak load pipeline and a changelog-based issue check every time it is called, not just
+      the file(s) that changed."
+    status: inferred
+    source: psiberx/cp2077-tweak-xl@f8da6be src/App/Facade.cpp:47-55 (`App::Facade::Reload` body)
+    tags:
+      - tweakxl
+      - hot-reload
+      - reload
+      - pipeline
+    detail: "`CheckForIssues()` in turn calls `m_changelog->CheckForIssues(m_manager)`
+      (src/App/Tweaks/TweakService.cpp:103-109), i.e. the same changelog mechanism that flags
+      renamed/removed vanilla records runs again on every Reload(), not only at initial game load."
+  - id: cp2077.tweakxl.hotreload.importdir-importtweak-removed
+    claim: The older `TweakXL.ImportDir()` and `TweakXL.Import()` (internally `ImportTweak`) scripted
+      methods are still RTTI-registered but their bodies do nothing except log a debug message
+      telling the caller to use `TweakXL.Reload()` instead; they no longer import anything.
+    status: verified
+    source: psiberx/cp2077-tweak-xl@f8da6be src/App/Facade.cpp:22-30 (both bodies log "[TweakXL] The
+      method TweakXL.ImportDir() is no longer supported. Use TweakXL.Reload() instead." and return
+      without doing anything else); src/App/Facade.hpp:30-32 (`RTTI_METHOD(ImportDir)`,
+      `RTTI_METHOD(ImportTweak, "Import")` still registered)
+    tags:
+      - tweakxl
+      - hot-reload
+      - deprecated
+      - importdir
+    detail: A mod script or bridge that still calls `TweakXL.ImportDir()` or `TweakXL.Import()`
+      expecting a load to happen will no-op; the debug log line is the only effect the source shows.
+      Note both bodies log the *ImportDir* wording, so an `Import()` call logs a message naming
+      `ImportDir()` — do not use the message text to tell the two apart.
+  - id: cp2077.tweakxl.hotreload.require-version-gate
+    claim: "TweakXL exposes `TweakXL.Require(version: String) -> Bool`, which parses `version` as a
+      semver string and returns whether the installed TweakXL's own `Project::Version` is greater
+      than or equal to it; an unparsable version string returns false rather than throwing."
+    status: verified
+    verified_on: "2.31"
+    source: psiberx/cp2077-tweak-xl@f8da6be src/App/Facade.cpp:57-61 (`App::Facade::Require`, using
+      `semver::from_string_noexcept(aVersion.c_str())` and `requirement.has_value() &&
+      Project::Version >= requirement.value()`)
+    tags:
+      - tweakxl
+      - version-check
+      - require
+      - compatibility
+    detail: This is the mechanism a mod's own redscript can use to gate functionality on a minimum
+      installed TweakXL version at runtime, distinct from the RED4ext-level version floor recorded
+      in cp2077.tweakxl.yaml-syntax.version-floors.
+  - id: cp2077.tweakxl.hotreload.getversion-method
+    claim: TweakXL exposes `TweakXL.Version() -> String` (native method `GetVersion`, registered under
+      the RTTI alias `Version`), returning the installed TweakXL build's own semver as a string.
+    status: verified
+    verified_on: "2.31"
+    source: psiberx/cp2077-tweak-xl@f8da6be src/App/Facade.cpp:63-66 (`App::Facade::GetVersion` returns
+      `Project::Version.to_string().c_str()`); src/App/Facade.hpp:38 (`RTTI_METHOD(GetVersion,
+      "Version")`)
+    tags:
+      - tweakxl
+      - version-check
+      - redscript-api
+  - id: cp2077.tweakxl.hotreload.reload-does-not-unload-removed-records
+    claim: "`TweakXL.Reload()` adds and updates records from the tweak files present on disk but does
+      not remove a record whose source file has been deleted since the last load; the record stays
+      in TweakDB for the rest of the game session and only a process restart clears it."
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - tweakxl
+      - hot-reload
+      - reload
+      - remove
+      - asymmetric
+    related:
+      - cp2077.tweakxl.hotreload.reload-does-three-things
+    detail: "Consistent with `reload-does-three-things`: LoadTweaks() re-imports what is on disk into
+      the live TweakDB, and nothing in the pipeline diffs against the previous load to retract
+      records. Hot reload is therefore asymmetric for the deploy/reload recommendation: adding or
+      editing a tweak file is hot, removing one needs a restart. A later probe in the same session
+      can misread a removed record as still shipped."
+  - id: cp2077.tweakxl.hotreload.reload-applies-changed-flat-on-existing-record
+    claim: "TweakXL.Reload() re-applies a CHANGED flat on an already-existing record, not just newly
+      added records: editing a flat in a deployed tweak file and calling TweakXL.Reload() updates
+      the live TweakDB flat. This is the positive half of the asymmetry in
+      reload-does-not-unload-removed-records (edits/additions are hot; only removals need a
+      restart)."
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - tweakxl
+      - hot-reload
+      - reload
+      - flat
+      - verified
+    related:
+      - cp2077.tweakxl.hotreload.reload-does-not-unload-removed-records
+      - cp2077.redhottools.hotreload.hot-tweaks-consumed-without-reload-1.3.0
+    detail: Because TweakXL.Reload() works but RHT 1.3.0.33690's `.hot-tweaks` sentinel does not drive
+      it (hot-tweaks-consumed-without-reload-1.3.0), the reliable tweak hot-reload is
+      TweakXL.Reload() via cp2077.lua.eval — which is what the reload table's tweaks `via` should
+      lead with, and what deploy --reload apply should call for a tweaks target.
+  - id: cp2077.tweakxl.hotreload.parse-error-still-ends-in-import-completed
+    claim: 'TweakXL 1.11.4 writes each session to red4ext/plugins/TweakXL/TweakXL-<date>-<time>.log and
+      leaves TweakXL.log empty. A reload that cannot parse a tweak file logs `Reading "<path under
+      r6/tweaks>"...` followed by an `[error] yaml-cpp: ...` line and still ends with "Import
+      completed.", so that line alone does not show that a given file loaded.'
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - tweakxl
+      - log
+      - hot-reload
+      - read-back
+      - silent-failure
+    related:
+      - cp2077.tweakxl.yaml-syntax.log-file-location
+    detail: deploy --reload apply now reads the newest TweakXL*.log and turns a read-back into `error`
+      when an [error] line follows the Reading line of a deployed file (commit 1f95118).

package/knowledge/cyberpunk2077/tweakxl.yaml-syntax.yaml

@@ -0,0 +1,208 @@
+game: cyberpunk2077
+topic: tweakxl.yaml-syntax
+title: TweakXL YAML tweak file placement, structure and record/inline semantics
+facts:
+  - id: cp2077.tweakxl.yaml-syntax.version-floors
+    claim: TweakXL's README lists its compatibility as Cyberpunk 2077 2.3 and redscript 0.5.27+, and its
+      installation step 1 requires RED4ext 1.28.0+ before extracting `TweakXL-x.x.x.zip` into the
+      Cyberpunk 2077 directory.
+    status: community
+    source: psiberx/cp2077-tweak-xl/README.md, sections "Getting Started > Compatibility" (game,
+      redscript) and "Getting Started > Installation" (RED4ext)
+    tags:
+      - tweakxl
+      - version-floor
+      - redscript
+      - red4ext
+  - id: cp2077.tweakxl.yaml-syntax.file-placement
+    claim: TweakXL loads tweak definitions from `.yaml` or `.tweak` files placed in `Cyberpunk
+      2077/r6/tweaks`, or from `.xl` files placed in `Cyberpunk 2077/archive/pc/mod`; regardless of
+      which of the three extensions is used, the file's contents must be written in YAML or JSON
+      syntax.
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/core-mods-explained/tweakxl/README.md, section "How do I use it?"
+    tags:
+      - tweakxl
+      - file-placement
+      - r6-tweaks
+      - archive-xl-manifest
+    detail: "The page's exact wording for the second half: \"No matter the file extension, the file
+      `contents` must be in `.yaml` or `.json` syntax.\""
+  - id: cp2077.tweakxl.yaml-syntax.log-file-location
+    claim: TweakXL writes its own log to `<game_directory>/red4ext/plugins/TweakXL/TweakXL.log`; a YAML
+      syntax or load error for a tweak file is reported there.
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/core-mods-explained/tweakxl/tweakxl-changing-game-records/how-to-yaml-tweak-modding-basics.md,
+      section "The log file"
+    tags:
+      - tweakxl
+      - log-file
+      - troubleshooting
+  - id: cp2077.tweakxl.yaml-syntax.indentation-spaces-only
+    claim: TweakXL yaml tweak files must be indented with spaces, never tabs; a tab character in the
+      indentation breaks the file's structure and, in the page's words, "your mod won't work".
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/core-mods-explained/tweakxl/tweakxl-changing-game-records/how-to-yaml-tweak-modding-basics.md,
+      section "Indentation"
+    tags:
+      - tweakxl
+      - yaml
+      - indentation
+      - validator
+    detail: 'A validator or linter should flag literal tab characters found in the leading whitespace of
+      a `.yaml`/`.tweak` file before it is packed. Checked against the source (2026-09-08): the page
+      does not say the failure is silent — it says the opposite elsewhere ("If there are any issues
+      with your yaml file, the TweakXL log will tell you about it", see
+      cp2077.tweakxl.yaml-syntax.log-file-location), so do not assume a tab failure is invisible.'
+  - id: cp2077.tweakxl.yaml-syntax.duplicate-keys-break-file
+    claim: A duplicate key at the same nesting level in a TweakXL yaml file breaks the whole file's
+      parse; the community-recommended check is to run the file through yamllint.com before packing.
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/core-mods-explained/tweakxl/tweakxl-changing-game-records/how-to-yaml-tweak-modding-basics.md,
+      section "Key Uniqueness"
+    tags:
+      - tweakxl
+      - yaml
+      - duplicate-key
+      - validator
+  - id: cp2077.tweakxl.yaml-syntax.record-names-must-be-unique
+    claim: Every TweakXL record (a named container grouping properties, which may themselves be other
+      records or flats) must have a globally unique name; two records sharing a name overwrite each
+      other.
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/core-mods-explained/tweakxl/tweakxl-changing-game-records/how-to-yaml-tweak-modding-basics.md,
+      section "Records"
+    tags:
+      - tweakxl
+      - record
+      - naming
+      - silent-failure
+    detail: 'Checked against the source (2026-09-08): the page states only that colliding records
+      "overwrite each other" — whether the overwrite is reported anywhere (e.g. in TweakXL.log) is
+      not stated by this source and should not be assumed either way.'
+  - id: cp2077.tweakxl.yaml-syntax.inline-record-autonaming
+    claim: An inline record (one written nested directly inside another record's property instead of
+      being given its own top-level name) is assigned an automatic name of the form
+      `<ParentRecordName>_inlineN`, where N depends on the inline's position inside the parent; that
+      position, and therefore the generated name, can change on any game update with no warning.
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/core-mods-explained/tweakxl/tweakxl-changing-game-records/how-to-yaml-tweak-modding-basics.md,
+      section "Inlines"
+    tags:
+      - tweakxl
+      - inline
+      - record
+      - naming
+      - versioning
+  - id: cp2077.tweakxl.yaml-syntax.vanilla-inline-records-numbered-per-root
+    claim: The game numbers the inline records of a vanilla (.tweak) top-level record with one counter
+      per top-level record, in source order, a parent before its children, and names every one of
+      them flat `<TopLevelRecord>_inline<N>`, never `<parent inline>_inline<N>`. The Basilisk's
+      drive model is the sixth inline record under Vehicle.v_militech_basilisk counting the nested
+      ones, and the game calls it Vehicle.v_militech_basilisk_inline5. A weapon blueprint's root
+      inline and its three inline children are Items.Base_Tech_Handgun_NoMuzzle_Blueprint_inline0
+      and _inline1/2/3.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - tweakdb
+      - inline
+      - record
+      - naming
+      - index
+    related:
+      - cp2077.tweakxl.yaml-syntax.inline-record-autonaming
+      - cp2077.tweakxl.yaml-syntax.inline-record-as-base-is-bad-practice
+    detail: "ModWright's vanilla index numbers them the same way since 2026-09-25 (TWEAKDB_PARSE_VERSION
+      2). Before that it named nested inlines `<parent>_inline<N>` with a counter per parent, so its
+      Vehicle.v_militech_basilisk_inline5 was the procedural camera parameters, and
+      cp2077.tweaks.base-exists accepted a $base against the wrong record. How TweakXL names nested
+      inlines in a mod's own YAML is not read. The rule is not universal: the Archer Quartz player
+      variant's package is _inline0 in game where source order gives _inline1 (see
+      cp2077.tweakdb.index-inline-names-can-differ-from-the-game)."
+  - id: cp2077.tweakdb.index-inline-names-can-differ-from-the-game
+    claim: The redmod tweak sources do not always give the game's inline record names. The Archer
+      Quartz's player-variant data package is Vehicle.v_standard2_archer_quartz_inline0 in game,
+      where the source writes the statModifiers inline first (source order gives _inline1), and in
+      game _inline1 is a ConstantStatModifier. The Quartz Nomad, written the same way (a
+      statModifiers += inline, then the vehDataPackage inline), has its package at _nomad_inline1 in
+      game, as source order gives. So an inline name taken from the index (built from those sources)
+      is unverified until read live.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - tweakdb
+      - inline
+      - record
+      - naming
+      - index
+      - gotcha
+    related:
+      - cp2077.tweakxl.yaml-syntax.vanilla-inline-records-numbered-per-root
+      - cp2077.tweakxl.yaml-syntax.inline-record-as-base-is-bad-practice
+    detail: Why the Quartz differs is not known (a compiled TweakDB newer than the sources is one
+      possibility). validate's cp2077.tweaks.inline-reference warns on any $base or value naming a
+      vanilla _inline<N> record.
+  - id: cp2077.tweakxl.yaml-syntax.files-read-in-name-order
+    claim: "TweakXL reads a tweaks folder's files in name order and clones a record's $base when its
+      file is read, so a $base defined in a file that sorts later does not exist yet: TweakXL logs
+      \"Cannot clone <base>, the record doesn't exist\" and drops the record (and anything based on
+      it)."
+    status: verified
+    verified_on: 2.31 (TweakXL 1.x)
+    source: ModWright field verification
+    tags:
+      - tweakxl
+      - load-order
+      - base
+      - gotcha
+    detail: validate's cp2077.tweaks.base-defined-before-use blocks it. One mod fixed it by renaming the
+      dependent file to <mod>_tiers.yaml ('.' sorts before '_').
+  - id: cp2077.tweakxl.yaml-syntax.inline-record-as-base-is-bad-practice
+    claim: Using an auto-generated `_inlineN` record name as the `$base` of a mod's own record is
+      documented as bad practice, because a future game update can silently change which vanilla
+      record that inline name now points to (see
+      cp2077.tweakxl.yaml-syntax.inline-record-autonaming), breaking the mod without any load error.
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/core-mods-explained/tweakxl/tweakxl-changing-game-records/how-to-yaml-tweak-modding-basics.md,
+      section "Inlines"
+    tags:
+      - tweakxl
+      - inline
+      - base
+      - gotcha
+      - versioning
+    detail: "Direct quote of the warning: \"NEVER use `inlineX` records as base in your items\".
+      RELATED: sharpens cp2077.tweakxl.yaml-syntax.inline-record-autonaming with the concrete
+      failure mode a scaffold/validator should check for: a mod's own record whose `$base` matches
+      `.*_inline\\d+$`."
+    related:
+      - id: cp2077.tweakxl.yaml-syntax.inline-record-autonaming
+        detail: "Sharpens that fact: the auto-generated name it describes must never be used as a `$base`,
+          because the update-to-update instability is exactly what breaks the dependent record."
+  - id: cp2077.tweakxl.record-description-property-is-localizeddescription
+    claim: An item record's description flat is `localizedDescription`, not `description`; TweakXL logs
+      `Unknown property description.` for the latter and still creates the record, so the item
+      exists but shows no description text.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - tweakxl
+      - yaml
+      - record
+      - property
+      - description
+      - localizeddescription
+    detail: "`displayName` is the display-name flat; `gameplayDescription` is the separate gameplay line
+      (a weapon mod can override an inherited LocKey there). TweakXL drops an unknown property
+      rather than rejecting the record, so the mistake is invisible unless TweakXL.log is read."

package/knowledge/cyberpunk2077/ui.icons.yaml

@@ -0,0 +1,259 @@
+game: cyberpunk2077
+topic: ui.icons
+title: Icon rendering, gamma correction, and atlas declaration
+facts:
+  - id: cp2077.ui.icon-import-gamma-lift
+    claim: png-to-xbm import applies automatic gamma lift; icon renders appear brighter in-game than
+      authored. Author dark with power-curve pixels (e.g., ^3.0) and keep speculars via curve
+      multiplication rather than multiply blend.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - icon
+      - gamma
+      - import
+      - xbm
+      - brightness
+    detail: "The lift is observed in game, not in the png: the same render looks correct on disk and
+      washed out in the inventory. The workaround is to power-curve the pixels before import (^3.0
+      is the example given) rather than multiplying the image down, which would kill the speculars."
+  - id: cp2077.ui.hud-icon-stroke-width
+    claim: HUD icons are freestyle line art at native resolution with thin strokes (~1.15px);
+      supersampling+downscale causes thin strokes to merge into blobs. Author at target resolution
+      with native pixel dimensions.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - hud-icon
+      - line-art
+      - stroke
+      - resolution
+      - supersampling
+    detail: Vanilla style is white lines on transparency with the muzzle pointing right; the widget
+      applies the tint (per a comment in the mod's tweak yaml). Rendering large and downscaling
+      merged the lines, so the art is rendered at the final size.
+  - id: cp2077.ui.icon-atlas-texture-resolution
+    claim: Icon atlases have a declared textureResolution enum (HD_1280_720, FullHD_1920_1080,
+      UltraHD_3840_2160); displayed icon size is calculated as uv fraction × textureResolution in
+      pixels.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - atlas
+      - texture-resolution
+      - enum
+      - icon-size
+      - uv
+    detail: Enum spellings corrected — they are HD_1280_720, FullHD_1920_1080 and UltraHD_3840_2160, not
+      lowercase-hyphenated. One weapon mod's icons.inkatlas declares HD_1280_720 and its part spans
+      0.2656..0.7344 x 0.3555..0.6445, i.e. 600x208 effective pixels.
+  - id: cp2077.ui.icon-atlas-part-declaration
+    claim: An icon atlas declaration (atlasResourcePath + atlasPartName) references an .inkatlas file
+      and a named part within it; the part definition includes uv bounds and controls the displayed
+      icon crop and size.
+    status: inferred
+    source: ModWright research
+    tags:
+      - atlas
+      - atlas-part-name
+      - atlas-resource-path
+      - uv
+      - part
+    detail: UIIcon.<ModWeapon>Icon sets $type UIIcon, atlasResourcePath mod\<modname>\icons.inkatlas and
+      atlasPartName <mod>_icon. Field and record names corrected from the lowercase forms
+      ("uiicon.", "atlasresourcepath") used earlier in this file. That the part's uv bounds control
+      the crop follows from the size formula in cp2077.ui.icon-atlas-texture-resolution rather than
+      from a direct statement.
+  - id: cp2077.ui.hud-icon-record
+    claim: HUD icons for weapons are registered via a separate UIIcon record with the same structure as
+      inventory icons; weapons can have both inventory and HUD icons declared separately.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - hud-icon
+      - weapon
+      - uiicon
+      - record
+    detail: "UIIcon.<ModWeapon>HudIcon (atlasResourcePath mod\\<modname>\\hud_icons.inkatlas,
+      atlasPartName <mod>_hud) is a second record; Items.Preset_<ModWeapon> references it as
+      `hudIcon: UIIcon.<ModWeapon>HudIcon` while the inventory icon goes in `iconPath:
+      <ModWeapon>Icon`."
+  - id: cp2077.ui.icon-path-record-name
+    claim: A weapon's iconPath field takes a tweakdb UIIcon record name (e.g., <ModWeapon>Icon), not a
+      path string; the tweakdb record contains the atlas reference.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - icon-path
+      - record-name
+      - tweakdb
+      - uiicon
+    detail: iconPath carries the bare record name with no "UIIcon." prefix, while hudIcon carries the
+      fully qualified UIIcon.<ModWeapon>HudIcon — the two fields are written differently in the same
+      working record.
+  - id: cp2077.ui.inkatlas-file-format
+    claim: Icon atlases are .inkatlas files (binary cr2w format) containing texture atlas definitions
+      with part uv mappings; they are generated from asset build tools or created via wolvenkit.
+    status: inferred
+    source: ModWright research
+    tags:
+      - inkatlas
+      - atlas
+      - file-format
+      - binary
+    detail: A build script authors the atlas json, which is then deserialized to the binary .inkatlas
+      like every other CR2W asset in the mod. The schema itself is not documented in the sources.
+  - id: cp2077.ui.xbm-file-format
+    claim: Icon images are stored as .xbm files (binary texture format); png images must be imported via
+      wolvenkit cli to convert to .xbm, applying gamma lift in the process.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - xbm
+      - texture
+      - import
+      - png
+      - gamma
+    detail: Shipped files are mod\<modname>\icons\<mod>_icon.xbm and <mod>_hud.xbm. The gamma lift is a
+      property of the png->xbm import step, which is why the render is authored dark.
+  - id: cp2077.ui.inventory-icon-size-recommendation
+    claim: Inventory icons should be sized to display clearly at ~600×208 effective pixels (the typical
+      in-game icon display size); larger assets are downscaled and smaller ones appear pixelated.
+    status: inferred
+    source: ModWright research
+    tags:
+      - inventory-icon
+      - size
+      - display
+      - pixels
+    detail: "600x208 is what one weapon mod's atlas part works out to under the displayed-size formula
+      (uv fraction x textureResolution), not a game-wide standard: change the declared
+      textureResolution or the part's uv bounds and the effective size changes. The
+      downscaling/pixelation consequences are not recorded in any source."
+  - id: cp2077.ui.icon-atlas-rendering-pipeline
+    claim: "Icon creation pipeline: render source image → apply gamma correction (power curve) → export
+      png → wolvenkit cli import to xbm → build the atlas with a script → register part in UIIcon
+      tweakdb record → reference in weapon."
+    status: inferred
+    source: ModWright research
+    tags:
+      - icon
+      - pipeline
+      - rendering
+      - atlas
+      - tweakdb
+    detail: A render script (moody top-lit pass + gamma curve) makes the inventory icon and a Freestyle
+      line-art pass makes the HUD icon. The end of the chain is UIIcon.<ModWeapon>Icon /
+      UIIcon.<ModWeapon>HudIcon referenced from Items.Preset_<ModWeapon>. No single source states
+      this pipeline end to end, hence inferred.
+  - id: cp2077.ui.icons.quickhack-program-icon-part-size
+    claim: "Every vanilla quickhack program icon is an atlas part displayed at 188 x 136 px: in
+      base\\gameplay\\gui\\common\\icons\\items\\item_icons21.inkatlas (textureResolution
+      UltraHD_3840_2160) each quickhack_* part spans UV 0.0489 x 0.0627. A custom program icon
+      should span the same box (its texels portrait, as vanilla's: see the detail); a part covering
+      a whole texture at a large declared resolution displays enormous."
+    status: verified
+    verified_on: "2.31"
+    source: base\gameplay\gui\common\icons\items\item_icons21.inkatlas
+      (archive\pc\content\basegame_4_gamedata.archive); UIIcon.quickhack_optics_malfunction and
+      UIIcon.quickhack_cw_malfunction name item_icons21 / item_icons19
+    tags:
+      - icon
+      - quickhack
+      - program
+      - inkatlas
+      - size
+    related:
+      - cp2077.ui.icon-atlas-texture-resolution
+      - cp2077.ui.icons.a-part-keeps-its-texel-proportions
+    detail: "The 188 x 136 is UV x the declared resolution, the box the part is fitted into. In texels
+      the parts are portrait: item_icons21.xbm is 2024 x 2040, so each quickhack_* part is 99 x 128
+      texels (w/h 0.773); see cp2077.ui.icons.a-part-keeps-its-texel-proportions. A quickhack mod's
+      icon since 2026-09-28: a 1024x1024 texture declared HD_1280_720 with a 150x194-texel part
+      (texel shape 0.773, UV x resolution 187.5 x 136.4), the art laid out unsquashed on the part's
+      own proportions."
+  - id: cp2077.ui.icons.wolvenkit-import-keep-onto-a-base-xbm
+    claim: "A PNG becomes an .xbm with the settings of an existing one by WolvenKit CLI `import <raw
+      dir> -o <out dir> -k`: the raw dir holds the png at the depot path, the out dir a copy of the
+      base xbm renamed to match. The result takes the png's pixels and size (a 1024x1024 base gave
+      256x256 and later 1024x1024 xbms) and keeps the base's setup. The CLI exits 3 and prints \"No
+      buffers found to rebuild\" while also printing \"Imported 1/1 file(s)\": the import did
+      happen."
+    status: verified
+    verified_on: 2.31 (WolvenKit CLI 8.20.0)
+    source: ModWright field verification
+    tags:
+      - wolvenkit
+      - import
+      - xbm
+      - texture
+      - icon
+  - id: cp2077.ui.icons.xbm-format-comes-from-the-setup
+    claim: "An .xbm's pixel format is not stored in its blob header (rendRenderTextureBlobHeader holds
+      only size, mip and slice layout); it follows from the setup's rawFormat, compression and
+      isGamma. So isGamma can be flipped in the serialized JSON and deserialized without touching
+      the pixels: the same 8-bit data is read as sRGB (1) or linear (0)."
+    status: verified
+    verified_on: 2.31 (WolvenKit CLI 8.20.0)
+    source: ModWright field verification
+    tags:
+      - xbm
+      - texture
+      - gamma
+      - format
+  - id: cp2077.ui.icons.lift-may-be-isgamma-0
+    claim: "The gamma lift of cp2077.ui.icon-import-gamma-lift is likely the xbm's isGamma 0: a weapon
+      mod's icon xbm, whose render looked lifted in game, has isGamma 0 (the png's sRGB pixels read
+      as linear). A quickhack mod's program icon, imported undarkened with isGamma 1, matches the
+      vanilla program chips' brightness in the cyberdeck. That isGamma 0 caused the weapon icon's
+      lift is inferred (not re-imported to compare)."
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - icon
+      - gamma
+      - xbm
+      - isgamma
+    related:
+      - cp2077.ui.icon-import-gamma-lift
+      - cp2077.ui.icons.xbm-format-comes-from-the-setup
+  - id: cp2077.ui.icons.a-part-keeps-its-texel-proportions
+    claim: "The cyberdeck's program tile draws an atlas part in its texel proportions, scaled to fit,
+      and the vanilla program parts are portrait in texels: item_icons21.xbm is 2024 x 2040 (not its
+      declared UltraHD_3840_2160), so a quickhack_* part (UV 0.048913 x 0.062745) is 99 x 128
+      texels, w/h 0.773. A custom program icon should match that texel shape. A 188x136-texel part
+      (texture size equal to its declared HD_1280_720) showed squat, \"square\" beside the vanilla
+      chips; a 150x193-texel part showed stretched tall only because its art had been squeezed from
+      a 188:136 canvas into it."
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - icon
+      - inkatlas
+      - aspect
+      - texel
+      - program
+    related:
+      - cp2077.ui.icon-atlas-texture-resolution
+      - cp2077.ui.icons.quickhack-program-icon-part-size
+  - id: cp2077.ui.icons.program-tooltip-bullets
+    claim: "A quickhack program's tooltip bullets are its localizedDescription (the first) and one per
+      OnAttach GameplayLogicPackage's UIData.localizedDescription: Items.BlindLvl1Program's second
+      bullet (\"Extends the base effect's duration\") is EquipmentGLP.BlindLvl1Program's UIData.
+      Vanilla lines are short and do not list the targets that are immune."
+    status: inferred
+    verified_on: "2.31"
+    source: ModWright research
+    tags:
+      - quickhack
+      - tooltip
+      - localization
+      - uidata