modwright 0.1.2 → 0.1.3

package/dist/surfaces/cyberpunk2077/index/parsers/tweakxl-yaml.js

@@ -140,9 +140,9 @@ function extractBindings(node, file, line) {
     }
     return bindings;
 }
-export function parseTweakXLYaml(text, file) {
+export function parseTweakXLYaml(text, file, options = {}) {
     const lineCounter = new YAML.LineCounter();
-    const doc = YAML.parseDocument(text, { lineCounter });
+    const doc = YAML.parseDocument(text, { lineCounter, uniqueKeys: !options.allowDuplicateKeys });
     if (doc.errors.length > 0) {
         const first = doc.errors[0];
         const line = first.pos ? lineCounter.linePos(first.pos[0]).line : 1;

package/dist/surfaces/cyberpunk2077/logs.js

@@ -355,6 +355,12 @@ const TWEAKXL = [
             ".yml or .tweak extension — TweakXL never saw it.",
         seenIn: [`${REAL}/tweakxl.log`],
         extract: ["file"],
+        attribution: {
+            kind: "read-order",
+            subjectLabel: "TweakXL tweak files (read order; a later file wins the same flat)",
+            actor: "file",
+            alsoFinding: true,
+        },
     },
     {
         id: "cyberpunk2077.tweakxl.yaml-parse-error",
@@ -538,11 +544,12 @@ const ARCHIVEXL = [
         sources: ["archivexl"],
         severity: "warn",
         category: "resource",
-        pattern: re(PRE, String.raw `\[Localization\] Item #(?<item>\d+) overwrites entry (?<entry>\d+)\.`),
+        pattern: re(PRE, String.raw `\[Localization\] Item #(?<item>\d+) overwrites (?<key>entry (?<entry>\d+))(?: \("(?<secondary>[^"\n]*)"\))?\.`),
         explain: "Two localization sources define the same string key; the later one wins. Harmless " +
             "when intended, but a mod's own name showing up wrong usually traces back to this.",
-        seenIn: [`${REAL}/archivexl.log`],
-        extract: ["item", "entry"],
+        seenIn: [`${REAL}/archivexl.log`, "psiberx/cp2077-archive-xl src/App/Extensions/Localization/Extension.cpp (secondary-key form)"],
+        extract: ["item", "entry", "secondary"],
+        attribution: { kind: "overwrite", subject: "key", detail: "secondary", alsoFinding: true },
         systemImpact: false,
     },
     {
@@ -601,6 +608,49 @@ const ARCHIVEXL = [
         ],
         extract: ["kind", "path"],
     },
+    {
+        id: "cyberpunk2077.archivexl.localization-merge-source",
+        game: GAME,
+        sources: ["archivexl"],
+        severity: "info",
+        category: "attribution",
+        pattern: re(PRE, String.raw `\[Localization\] Merging entries from "(?<file>[^"\n]+)"\.\.\.`),
+        explain: "ArchiveXL is merging one localization file; any 'overwrites entry' line after it was " +
+            "caused by this file.",
+        seenIn: [
+            "psiberx/cp2077-archive-xl src/App/Extensions/Localization/Extension.cpp (source-read 2026-09-29; no real sample yet)",
+        ],
+        attribution: { kind: "overwrite", actor: "file", setsContext: true },
+    },
+    {
+        id: "cyberpunk2077.archivexl.animations-target",
+        game: GAME,
+        sources: ["archivexl"],
+        severity: "info",
+        category: "attribution",
+        pattern: re(PRE, String.raw `\[EntityAnimation\] Initializing animations for "(?<target>[^"\n]+)"\.\.\.`),
+        explain: "ArchiveXL is about to merge extra animation sets into one entity component " +
+            "(<template>:<component>); the 'Merging animations from' lines after it name them.",
+        seenIn: [
+            "psiberx/cp2077-archive-xl src/App/Extensions/Animation/Extension.cpp (source-read 2026-09-29; no real sample yet)",
+        ],
+        attribution: { kind: "merge", subject: "target", setsContext: true },
+    },
+    {
+        id: "cyberpunk2077.archivexl.animations-merge",
+        game: GAME,
+        sources: ["archivexl"],
+        severity: "info",
+        category: "attribution",
+        pattern: re(PRE, String.raw `\[EntityAnimation\] Merging animations from "(?<anims>[^"\n]+)" with priority (?<priority>-?\d+)\.\.\.`),
+        explain: "One mod's animation set merged into the component named by the preceding " +
+            "'Initializing animations for' line, at this priority. Two sets animating the same " +
+            "action on one component is the usual 'wrong animation plays' conflict.",
+        seenIn: [
+            "psiberx/cp2077-archive-xl src/App/Extensions/Animation/Extension.cpp (source-read 2026-09-29; no real sample yet)",
+        ],
+        attribution: { kind: "merge", actor: "anims", detail: "priority" },
+    },
 ];
 const CET_PRE = String.raw `\[\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2} UTC[+-]\d{2}:\d{2}\] \[info\] \[[^\]\n]*\] \[\d+\] `;
 const LUA_LOCATION = String.raw `(?<file>[^\n]*?(?:mods[\\/](?<mod>[^\\/\n]+)[\\/])?[^\\/\n]*\.lua):(?<line>\d+):\s*`;
@@ -733,6 +783,34 @@ const CODEWARE = [
         seenIn: [`${REAL}/codeware.log`],
     },
 ];
+const REDHOTTOOLS = [
+    {
+        id: "cyberpunk2077.redhottools.resource-not-found",
+        game: GAME,
+        sources: ["redhottools"],
+        severity: "warn",
+        category: "resource",
+        pattern: re(PRE, String.raw `Resource not found: hash=(?<hash>\d+) path="(?:\?|(?<path>[^"\n]+))" archive="(?:\?|(?<archive>[^"\n]+))"`),
+        explain: "The engine asked for a resource that no loaded archive provides. RHT only logs this for " +
+            "requests tied to a mod archive (it skips the base game's and DLC's), and names that " +
+            "archive — the usual trail from an invisible, purple or 'black and shiny' item back to the " +
+            "mod whose file points at something that is not there. Which role the named archive played " +
+            "in the request (the referencing mod or only the one searched) is not yet confirmed on a real log.",
+        hint: "Check the named archive's depot paths for a typo or a file it forgot to ship, and whether it " +
+            "needs another mod (a body framework, an ArchiveXL resource) that is not installed.",
+        seenIn: ["psiberx/cp2077-red-hot-tools src/App/Archives/ResourceLogger.cpp"],
+        extract: ["hash", "path", "archive"],
+        systemImpact: false,
+        attribution: {
+            kind: "missing-resource",
+            subject: "path",
+            subjectFallback: "hash",
+            actor: "archive",
+            detail: "hash",
+            alsoFinding: true,
+        },
+    },
+];
 export const SIGNATURES = [
     ...RED4EXT,
     ...REDSCRIPT,
@@ -740,4 +818,5 @@ export const SIGNATURES = [
     ...ARCHIVEXL,
     ...CET,
     ...CODEWARE,
+    ...REDHOTTOOLS,
 ];

package/dist/surfaces/cyberpunk2077/surface.js

@@ -5,6 +5,7 @@ import { findInSteam } from "../../core/steam.js";
 import { dedupeByRoot, logs, roots } from "../../core/surfaceutil.js";
 import { cp2077Index } from "./index/index.js";
 import { SIGNATURES } from "./logs.js";
+import { extractCyberpunkWrites } from "./writes.js";
 import { BRIDGE_VALIDATORS } from "./validators/bridge.js";
 import { GARMENT_VALIDATORS } from "./validators/garments.js";
 import { MESH_VALIDATORS } from "./validators/mesh.js";
@@ -188,9 +189,19 @@ export const cyberpunk2077 = {
                     "initialized.' A missing 'is initialized' line means every redscript mod that " +
                     "depends on Codeware is running without it.",
             },
+            {
+                id: "redhottools",
+                label: "Red Hot Tools",
+                candidates: pluginLogCandidates(install, "RedHotTools"),
+                rootId: "red4ext",
+                notes: "Red Hot Tools' own log. Besides its hot-reload lines it records 'Resource not found: " +
+                    "hash=… path=\"…\" archive=\"…\"' for every failed request tied to a mod archive, which " +
+                    "names the archive behind a missing resource. Only present when Red Hot Tools is installed.",
+            },
         ]);
     },
     logSignatures: SIGNATURES,
+    extractWrites: (mod, root) => extractCyberpunkWrites(mod, root),
     index: cp2077Index,
     validators: [
         ...TWEAK_VALIDATORS,

package/dist/surfaces/cyberpunk2077/writes.js

@@ -0,0 +1,67 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { TweakParseError } from "./index/model.js";
+import { parseTweakFile } from "./index/parsers/tweak.js";
+import { parseTweakXLYaml } from "./index/parsers/tweakxl-yaml.js";
+const TWEAK_EXTENSIONS = new Set([".yaml", ".yml", ".tweak"]);
+const MAX_TWEAK_BYTES = 8 * 1024 * 1024;
+export const TWEAKS_UNIT_NOTE = "r6/tweaks is one shared folder and TweakXL has no notion of mods, so each top-level folder there " +
+    "(or a file directly in r6/tweaks) is taken as one mod — how mods are packaged, not something the game records.";
+function recordWrites(records, file, unit) {
+    const writes = [];
+    const withUnit = (w) => (unit ? { ...w, unit } : w);
+    for (const record of records) {
+        if (record.type !== undefined || record.base !== undefined) {
+            const value = {};
+            if (record.type !== undefined)
+                value.$type = record.type;
+            if (record.base !== undefined)
+                value.$base = record.base;
+            writes.push(withUnit({ key: record.name, keyKind: "tweakdb-record", op: "create", value, file, line: record.line, certainty: "definite" }));
+        }
+        for (const flat of record.flats) {
+            writes.push(withUnit({
+                key: `${record.name}.${flat.name}`,
+                keyKind: "tweakdb-flat",
+                op: flat.op,
+                value: flat.value,
+                file,
+                line: record.line,
+                certainty: "definite",
+            }));
+        }
+    }
+    return writes;
+}
+async function parseFile(abs) {
+    const stat = await fs.stat(abs);
+    if (stat.size > MAX_TWEAK_BYTES)
+        throw new Error(`larger than ${MAX_TWEAK_BYTES} bytes; skipped`);
+    const text = await fs.readFile(abs, "utf8");
+    return path.extname(abs).toLowerCase() === ".tweak" ? parseTweakFile(text, abs) : parseTweakXLYaml(text, abs, { allowDuplicateKeys: true });
+}
+export async function extractCyberpunkWrites(mod, root) {
+    let files;
+    if (root.id === "tweaks")
+        files = mod.files;
+    else if (root.id === "redmod")
+        files = mod.files.filter((f) => f.toLowerCase().startsWith("tweaks/"));
+    else
+        return undefined;
+    files = files.filter((f) => TWEAK_EXTENSIONS.has(path.extname(f).toLowerCase()));
+    const extraction = { writes: [], errors: [] };
+    if (root.id === "tweaks")
+        extraction.unitNote = TWEAKS_UNIT_NOTE;
+    for (const rel of files) {
+        const abs = path.join(mod.path, rel);
+        const unit = root.id === "tweaks" ? rel.split("/")[0] : undefined;
+        try {
+            extraction.writes.push(...recordWrites(await parseFile(abs), abs, unit));
+        }
+        catch (error) {
+            const message = error instanceof TweakParseError ? error.message : `${abs}: ${error.message}`;
+            extraction.errors.push({ file: abs, error: message });
+        }
+    }
+    return extraction;
+}

package/dist/surfaces/skyrimse/loadorder.js

@@ -1,6 +1,7 @@
 import { existsSync, promises as fs } from "node:fs";
 import * as path from "node:path";
 import { documents, localAppData, pathExists } from "../../core/fsutil.js";
+import { parseIni } from "../../core/ini.js";
 export const STOREFRONT_FOLDER = {
     steam: "Skyrim Special Edition",
     gog: "Skyrim Special Edition GOG",
@@ -68,32 +69,7 @@ export async function readCcc(root) {
         .map((l) => l.trim())
         .filter((l) => l.length > 0);
 }
-export function parseIni(text) {
-    const out = new Map();
-    let section = "";
-    for (const raw of text.split(/\r?\n/)) {
-        const line = raw.trim();
-        if (!line || line.startsWith(";") || line.startsWith("#"))
-            continue;
-        const sec = /^\[(.+)\]$/.exec(line);
-        if (sec) {
-            section = sec[1].trim().toLowerCase();
-            continue;
-        }
-        const eq = line.indexOf("=");
-        if (eq < 0)
-            continue;
-        const key = line.slice(0, eq).trim().toLowerCase();
-        let value = line.slice(eq + 1).trim();
-        const wrapped = /^@ByteArray\((.*)\)$/.exec(value);
-        if (wrapped)
-            value = wrapped[1];
-        if (!out.has(section))
-            out.set(section, new Map());
-        out.get(section).set(key, value);
-    }
-    return out;
-}
+export { parseIni } from "../../core/ini.js";
 function samePath(a, b) {
     const norm = (p) => path.resolve(p.replace(/\\\\/g, "\\")).replace(/[\\/]+$/, "").toLowerCase();
     return norm(a) === norm(b);

package/dist/surfaces/skyrimse/surface.js

@@ -19,6 +19,7 @@ export const skyrimse = {
     aliases: ["skyrim", "skyrimspecialedition", "sse", "skse"],
     summary: "Creation Engine. Plugins (.esp/.esm/.esl) and archives (.bsa) in Data/, " +
         "with load order in Plugins.txt and native extensions via SKSE64.",
+    managedDataDir: "Data",
     async detect() {
         const installs = [];
         const override = process.env.MODWRIGHT_SKYRIMSE_ROOT;

package/dist/surfaces/stardewvalley/logs.js

@@ -4,6 +4,9 @@ const SCORE = "SMAPI src/SMAPI/Framework/SCore.cs";
 const LOGMANAGER = "SMAPI src/SMAPI/Framework/Logging/LogManager.cs";
 const CP = "Content Patcher ContentPatcher/ModEntry.cs and Framework/PatchLoader.cs";
 const PENDING = "pending a real sample";
+const CONTENT_MANAGER = "SMAPI src/SMAPI/Framework/ContentManagers/GameContentManager.cs (source-read 2026-09-29)";
+const SMAPI_PREFIX = String.raw `^\[(?<time>\d\d[:.]\d\d[:.]\d\d) (?<level>[A-Za-z]+)(?: +screen_(?<screen>\d+))? +SMAPI\] `;
+const ON_BEHALF = String.raw `(?: \(for the '(?<via>.+)' content pack\))?\.$`;
 export const PREFIX = String.raw `^\[(?<time>\d\d[:.]\d\d[:.]\d\d) (?<level>[A-Za-z]+)(?: +screen_(?<screen>\d+))? +(?<source>[^\]]+)\] `;
 function re(body) {
     return new RegExp(PREFIX + body);
@@ -304,4 +307,42 @@ export const SIGNATURES = [
         seenIn: [`${CP}`, PENDING],
         extract: ["pack"],
     }),
+    {
+        id: "stardewvalley.smapi.asset-edited",
+        game: "stardewvalley",
+        sources: ["smapi"],
+        severity: "info",
+        category: "attribution",
+        pattern: new RegExp(SMAPI_PREFIX + String.raw `(?<mod>.+?) edited (?<asset>.+?)` + ON_BEHALF),
+        explain: "SMAPI applied one mod's edit to a game asset (for a content pack when one is named). Every " +
+            "mod that edits an asset gets its own line, in the order the edits were applied, so the list " +
+            "for one asset answers 'which mod is changing this'; for the same field, the later editor wins.",
+        seenIn: [CONTENT_MANAGER, PENDING],
+        attribution: { kind: "edit", subject: "asset", actor: "mod", via: "via" },
+    },
+    {
+        id: "stardewvalley.smapi.asset-loaded",
+        game: "stardewvalley",
+        sources: ["smapi"],
+        severity: "info",
+        category: "attribution",
+        pattern: new RegExp(SMAPI_PREFIX + String.raw `(?<mod>.+?) loaded asset '(?<asset>[^']+)'` + ON_BEHALF),
+        explain: "One mod supplied a whole asset in place of the game's own (a Content Patcher Load, or a C# " +
+            "mod's loader). Only one mod can load a given asset; edits by others then apply on top.",
+        seenIn: [CONTENT_MANAGER, PENDING],
+        attribution: { kind: "replace", subject: "asset", actor: "mod", via: "via" },
+    },
+    smapi("asset-edit-crashed", {
+        severity: "error",
+        category: "resource",
+        pattern: re(String.raw `Mod crashed when (?<op>editing|loading) asset '(?<asset>[^']+)'(?: \(for the '(?<via>.+?)' content pack\))?[,.]`),
+        explain: "A mod threw while loading or editing a game asset. For a load SMAPI falls back to the game's " +
+            "own asset; for an edit the asset keeps whatever the earlier editors did, so the mod's change " +
+            "(and anything depending on it) is missing. The mod is the line's source.",
+        hint: "The continuation lines carry the exception; update or remove the named mod or content pack.",
+        seenIn: [CONTENT_MANAGER, PENDING],
+        extract: ["source", "op", "asset", "via"],
+        systemImpact: false,
+        attribution: { kind: "failed", subject: "asset", actor: "source", via: "via", detail: "op", alsoFinding: true },
+    }),
 ];

package/dist/surfaces/stardewvalley/surface.js

@@ -7,6 +7,7 @@ import { findInSteam } from "../../core/steam.js";
 import { dedupeByRoot, logs, roots } from "../../core/surfaceutil.js";
 import { SIGNATURES } from "./logs.js";
 import { WIKI_FETCH } from "./index/wiki.js";
+import { extractStardewWrites } from "./writes.js";
 import { parseManifest, scanMods } from "./mods.js";
 import { stardewvalleyCompat } from "./compat.js";
 import { readSmapiConfig, stringList } from "./config.js";
@@ -221,6 +222,7 @@ export const stardewvalley = {
         return reasons;
     },
     logSignatures: SIGNATURES,
+    extractWrites: (mod, root) => extractStardewWrites(mod, root),
     validators: [...MANIFEST_VALIDATORS, ...CONTENT_VALIDATORS, ...FIELDS_VALIDATORS, ...LOADORDER_VALIDATORS],
     index: stardewvalleyIndex,
     compat: stardewvalleyCompat,

package/dist/surfaces/stardewvalley/writes.js

@@ -0,0 +1,136 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { hasTokens, parseContentJson, patchesOf, pick, splitLexically } from "./contentpatcher.js";
+const MAX_INCLUDE_DEPTH = 5;
+const obj = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : undefined;
+function push(ctx, write) {
+    const full = { ...write, file: ctx.file };
+    if (ctx.unit)
+        full.unit = ctx.unit;
+    ctx.writes.push(full);
+}
+function patchWrites(cfg, ctx) {
+    const includes = [];
+    for (const patch of patchesOf(cfg).patches) {
+        const when = obj(pick(patch.raw, "When")?.value);
+        const condition = when && Object.keys(when).length > 0 ? JSON.stringify(when) : undefined;
+        const action = patch.action?.trim().toLowerCase();
+        if (action === "include") {
+            for (const from of splitLexically(patch.fromFile ?? "")) {
+                includes.push(condition ? { fromFile: from, condition } : { fromFile: from });
+            }
+            continue;
+        }
+        const targets = splitLexically(patch.target ?? "");
+        for (const target of targets) {
+            const certainty = (...parts) => condition || hasTokens(target) || parts.some((p) => hasTokens(p)) ? "conditional" : "definite";
+            const base = (extra = {}) => (condition ? { condition, ...extra } : extra);
+            if (action === "load") {
+                const w = { key: target, keyKind: "asset", op: "load", certainty: certainty(), ...base() };
+                if (patch.fromFile)
+                    w.value = patch.fromFile;
+                push(ctx, w);
+            }
+            else if (action === "editdata") {
+                const tf = pick(patch.raw, "TargetField")?.value;
+                const prefix = Array.isArray(tf) && tf.length > 0 ? `${target}#${tf.map(String).join(".")}` : undefined;
+                const entryKey = (k) => (prefix ? `${prefix}.${k}` : `${target}#${k}`);
+                let parts = 0;
+                const entries = obj(pick(patch.raw, "Entries")?.value);
+                for (const [k, v] of Object.entries(entries ?? {})) {
+                    push(ctx, { key: entryKey(k), keyKind: "asset-entry", op: v === null ? "remove" : "set", value: v, certainty: certainty(k), ...base() });
+                    parts++;
+                }
+                const fields = obj(pick(patch.raw, "Fields")?.value);
+                for (const [k, fieldMap] of Object.entries(fields ?? {})) {
+                    for (const [f, v] of Object.entries(obj(fieldMap) ?? {})) {
+                        push(ctx, { key: `${entryKey(k)}.${f}`, keyKind: "asset-field", op: v === null ? "remove" : "set", value: v, certainty: certainty(k, f), ...base() });
+                        parts++;
+                    }
+                }
+                const textOps = pick(patch.raw, "TextOperations")?.value;
+                for (const op of Array.isArray(textOps) ? textOps : []) {
+                    const o = obj(op);
+                    const opTarget = o ? pick(o, "Target")?.value : undefined;
+                    if (!Array.isArray(opTarget) || opTarget.length < 2)
+                        continue;
+                    const [kind, ...rest] = opTarget.map(String);
+                    const operation = String((o && pick(o, "Operation")?.value) ?? "").toLowerCase();
+                    const writeOp = operation === "removedelimited" ? "remove" : operation === "replacedelimited" ? "set" : "append";
+                    const key = kind.toLowerCase() === "fields" ? `${entryKey(rest[0])}.${rest.slice(1).join(".")}` : entryKey(rest.join("."));
+                    push(ctx, { key, keyKind: kind.toLowerCase() === "fields" ? "asset-field" : "asset-entry", op: writeOp, value: o && pick(o, "Value")?.value, certainty: certainty(...rest), ...base() });
+                    parts++;
+                }
+                const moves = pick(patch.raw, "MoveEntries")?.value;
+                for (const move of Array.isArray(moves) ? moves : []) {
+                    const id = obj(move) && pick(obj(move), "ID")?.value;
+                    if (typeof id !== "string")
+                        continue;
+                    push(ctx, { key: entryKey(id), keyKind: "asset-entry", op: "edit", value: move, certainty: certainty(id), ...base() });
+                    parts++;
+                }
+                if (parts === 0)
+                    push(ctx, { key: target, keyKind: "asset", op: "edit", certainty: certainty(), ...base() });
+            }
+            else if (action === "editimage" || action === "editmap") {
+                const w = { key: target, keyKind: "asset", op: "edit", certainty: certainty(), ...base() };
+                const toArea = pick(patch.raw, "ToArea")?.value;
+                if (toArea !== undefined)
+                    w.value = { ToArea: toArea };
+                push(ctx, w);
+            }
+        }
+    }
+    return includes;
+}
+async function readPack(packDir, file, unit, extraction, depth) {
+    let cfg;
+    try {
+        cfg = parseContentJson(await fs.readFile(file, "utf8"));
+    }
+    catch (error) {
+        extraction.errors.push({ file, error: error.message });
+        return;
+    }
+    const ctx = { file, unit, writes: [] };
+    const includes = patchWrites(cfg, ctx);
+    extraction.writes.push(...ctx.writes);
+    for (const include of includes) {
+        if (hasTokens(include.fromFile)) {
+            extraction.errors.push({ file, error: `Include of "${include.fromFile}" uses tokens; not followed.` });
+            continue;
+        }
+        if (depth >= MAX_INCLUDE_DEPTH) {
+            extraction.errors.push({ file, error: `Include of "${include.fromFile}" is nested more than ${MAX_INCLUDE_DEPTH} deep; not followed.` });
+            continue;
+        }
+        const target = path.resolve(packDir, include.fromFile);
+        if (!target.startsWith(path.resolve(packDir) + path.sep)) {
+            extraction.errors.push({ file, error: `Include of "${include.fromFile}" points outside the pack; not followed.` });
+            continue;
+        }
+        const before = extraction.writes.length;
+        await readPack(packDir, target, unit, extraction, depth + 1);
+        if (include.condition) {
+            for (const w of extraction.writes.slice(before)) {
+                w.certainty = "conditional";
+                w.condition = w.condition ? `${include.condition} and ${w.condition}` : include.condition;
+            }
+        }
+    }
+}
+export async function extractStardewWrites(mod, root) {
+    if (root.id !== "mods")
+        return undefined;
+    const packs = mod.files.filter((f) => f.toLowerCase() === "content.json" || f.toLowerCase().endsWith("/content.json"));
+    if (packs.length === 0)
+        return undefined;
+    const extraction = { writes: [], errors: [] };
+    for (const rel of packs) {
+        const packRel = path.posix.dirname(rel);
+        const packDir = path.join(mod.path, packRel);
+        const unit = packRel === "." ? undefined : packRel;
+        await readPack(packDir, path.join(mod.path, rel), unit, extraction, 0);
+    }
+    return extraction;
+}

package/knowledge/baldursgate3/dialogue.osiris-goals.yaml

@@ -384,3 +384,32 @@ facts:
       Whether the journal .lsx under Mods/<Mod>/Story/Journals loads as loose .lsx was not separated
       from the missing compile; the RootTemplates rule (loose .lsx not loaded, .lsf needed) suggests
       it does not.
+  - id: bg3.dialogue.osiris-goals.prefix-convention-is-a-compiler-warning-in-lslib
+    claim: In LSLib's Osiris story compiler a database whose name does not start with "DB", a PROC whose
+      name does not start with "PROC" or a query whose name does not start with "QRY" produces a
+      warning (W26 DbNamingStyle, W23 RuleNamingStyle), never an error, and W23 is switched off by
+      default; the story still compiles.
+    status: inferred
+    source: Norbyte/lslib@6f5f698 LSLib/LS/Story/Compiler/Compiler.cs VerifyIRRule ("Name of PROC ...
+      should start with the prefix PROC", "Name of Query ... should start with the prefix QRY"),
+      VerifyDatabases ("Name of database ... should start with the prefix DB");
+      CompilationContext.cs DiagnosticCode RuleNamingStyle = "W23", DbNamingStyle = "W26",
+      CompilationLog() WarningSwitches[RuleNamingStyle] = false
+    tags:
+      - osiris
+      - naming
+      - db-prefix
+      - proc-prefix
+      - qry-prefix
+      - compiler
+      - warning
+    detail: "This is the community compiler's behaviour, not Larian's in-engine one: there the prefix is
+      a style check. Nothing read in that source supports the claim, attributed to a Nexus article,
+      that a missing prefix silently disables the whole story component; until the game's own
+      compiler is shown to behave differently, the bg3.story.osiris-naming-convention validator rule
+      stays informational. The checks compare the first 2-4 characters case-insensitively
+      (\"PROC\"/\"QRY\"/\"DB\"), and the PROC and QRY checks skip names no longer than the prefix,
+      so \"Proc_X\" and \"dbFoo\" pass them."
+    related:
+      - id: bg3.dialogue.osiris-goals.qry-proc-color-coding
+        detail: Agrees on the convention itself; adds what the compiler does when it is broken.

package/knowledge/baldursgate3/osiris.tags.yaml

@@ -0,0 +1,78 @@
+game: baldursgate3
+topic: osiris.tags
+title: "Osiris entity tags: SetTag/IsTagged/ClearTag and the tag events, from Larian's modding wiki
+  and the generated stubs"
+facts:
+  - id: bg3.osiris.tags.settag-istagged-cleartag-signatures
+    claim: Osiris tags an entity with the call SetTag((GUIDSTRING)_Target, (TAG)_Tag), tests it with the
+      query IsTagged([in](GUIDSTRING)_Target, [in](TAG)_Tag, [out](INTEGER)_Bool), and removes it
+      with the call ClearTag((GUIDSTRING)_Source, (TAG)_Tag). In the Script Extender's Osi table
+      these are Osi.SetTag(target, tag), Osi.IsTagged(target, tag) -> integer, and
+      Osi.ClearTag(target, tag).
+    status: verified
+    source: wiki pages SetTag ("call SetTag((GUIDSTRING)_Target, (TAG)_Tag)"), IsTagged ("query
+      IsTagged([in](GUIDSTRING)_Target, [in](TAG)_Tag, [out](INTEGER)_Bool)"), ClearTag
+      ("ClearTag((GUIDSTRING)_Source, (TAG)_Tag)"); LaughingLeader/BG3ModdingTools@ab343b6
+      generated/ Osi.lua:4273-4275 (SetTag), :1840-1843 (IsTagged, @return integer bool), :2570-2572
+      (ClearTag).
+    tags:
+      - osiris
+      - tag
+      - settag
+      - istagged
+      - cleartag
+      - signature
+    detail: "Verified as declared signatures only; what the calls do at runtime was not observed. The
+      wiki's own examples: SetTag(_ParentA, (TAG)_SHADOW_CURSE_IMMUNE) inside a PROC;
+      IsTagged(_Player, (TAG)_DARK_URGE, 1) as an AND condition in a QRY (the trailing 1 binds the
+      out-param to \"true\"). A TAG is a UUID-keyed resource, referenced in story scripts by a named
+      constant; the wiki examples use (TAG)_NAME constants, which the story compiler resolves."
+  - id: bg3.osiris.tags.cleartag-only-clears-osiris-set-tags
+    claim: ClearTag removes only tags that Osiris itself set. Tags placed via the editor sidebar on a
+      root template or on an object instance cannot be cleared this way (a polymorph status replaces
+      them with the target template's, but plain Transform calls leave them), and tags set from
+      Anubis or from dialogs can only be cleared from those same systems (dialog tags via
+      ClearDialogTag).
+    status: community
+    source: wiki page ClearTag, "Further Information" section (last edited 2024-12-16); ClearDialogTag
+      is Osi.ClearDialogTag(target, tag) at LaughingLeader/BG3ModdingTools@ab343b6
+      generated/Osi.lua:2522-2524.
+    tags:
+      - osiris
+      - tag
+      - cleartag
+      - gotcha
+      - roottemplate
+      - dialog
+    related:
+      - bg3.osiris.tags.settag-istagged-cleartag-signatures
+    detail: "Practical consequence for a probe or test row: IsTagged answers for every tag source, so a
+      tag that \"will not clear\" is usually one that was never Osiris-owned — check the root
+      template's sidebar tags before treating a failed ClearTag as a scripting bug."
+  - id: bg3.osiris.tags.tag-events-and-inventory-tag-queries
+    claim: "Osiris declares tag-related events — CharacterTagEvent(character, tag, event),
+      TagCleared(target, tag), TagEvent(tag, event), TagSet(target, tag) — and inventory queries
+      that take their tags as a string rather than a TAG: GetByTagInInventory(tags, inventoryHolder)
+      -> GUIDSTRING, GetItemByTagInInventory(tags, inventoryHolder) -> ITEM, and
+      TaggedItemsGetCountInMagicPockets(tags, source) -> integer. HasAppearanceVisualTag(character,
+      tag) -> integer tests visual tags separately."
+    status: verified
+    source: LaughingLeader/BG3ModdingTools@ab343b6 generated/Osi.Events.lua:237
+      CharacterTagEvent(character, tag, event); Osi.Events.lua:1197 TagCleared(target, tag);
+      Osi.Events.lua:1201 TagEvent(tag, event); Osi.Events.lua:1205 TagSet(target, tag);
+      generated/Osi.lua:796-799 (GetByTagInInventory), :1006-1009 (GetItemByTagInInventory),
+      :2136-2139 (TaggedItemsGetCountInMagicPockets), :1347-1350 (HasAppearanceVisualTag).
+    tags:
+      - osiris
+      - tag
+      - event
+      - inventory
+      - tag-expression
+    related:
+      - bg3.osiris.tags.settag-istagged-cleartag-signatures
+    detail: Verified as declared signatures only; when the events fire and what the queries return at
+      runtime was not observed. The wiki's search-result snippets describe the string argument as a
+      tag expression, but its grammar (how several tags combine) is not established by anything read
+      here; test it before relying on more than a single tag name. Recorded so a future BG3 probe
+      kind for "is the scaffolded entity tagged" has its call shapes on file; none is registered yet
+      (bg3.entity.* probes go through the Script Extender's Ext.Entity, not Osiris tags).