modwright 0.1.0

package/knowledge/stardewvalley/smapi.manifest.yaml

@@ -0,0 +1,293 @@
+game: stardewvalley
+topic: smapi.manifest
+title: manifest.json — the fields, the exact validation rules, and the published JSON Schema
+facts:
+  - id: stardewvalley.smapi.manifest.every-mod-has-one
+    claim: Every SMAPI mod and every content pack must have a `manifest.json` in its folder; SMAPI uses
+      it to identify and load the mod and to perform update checks, and the parsed manifest is
+      available to mods at runtime through `this.ModManifest` and the mod registry.
+    status: community
+    source: 'https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Manifest (read 2026-09-11): "Every
+      SMAPI mod or content pack must have a manifest.json file in its folder. SMAPI uses this to
+      identify and load the mod, perform update checks, etc."'
+    tags:
+      - manifest
+      - required
+      - mods
+      - scanning
+  - id: stardewvalley.smapi.manifest.fields
+    claim: The manifest fields are `Name`, `Author`, `Version`, `Description`, `UniqueID`,
+      `MinimumApiVersion`, `MinimumGameVersion`, `EntryDll`, `ContentPackFor`, `Dependencies` and
+      `UpdateKeys`. Any other field is kept in `IManifest.ExtraFields` and ignored by SMAPI.
+    status: community
+    source: https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Manifest ("Any other fields will be
+      stored in the IManifest.ExtraFields dictionary, which is available through the mod registry.
+      Extra fields are ignored by SMAPI, but may be useful for extended metadata intended for other
+      mods."); the same set is the constructor signature of
+      src/SMAPI.Toolkit/Serialization/Models/Manifest.cs, which carries `[JsonExtensionData] public
+      IDictionary<string, object> ExtraFields`
+    tags:
+      - manifest
+      - fields
+      - extrafields
+      - validator
+    detail: "The published JSON Schema sets `additionalProperties: false`, which contradicts the
+      runtime. The runtime is authoritative: a validator should report an unknown field at `info`,
+      never block on it."
+  - id: stardewvalley.smapi.manifest.entrydll-xor-contentpackfor
+    claim: A mod must declare exactly one of `EntryDll` (a C# mod) or `ContentPackFor` (a content pack).
+      SMAPI's first validation check is `if (hasDll == isContentPack)`, failing with "manifest sets
+      both EntryDll and ContentPackFor, which are mutually exclusive." or "manifest has no EntryDll
+      or ContentPackFor field; must specify one."
+    status: inferred
+    source: SMAPI develop,
+      https://github.com/Pathoschild/SMAPI/blob/develop/src/SMAPI.Toolkit/Framework/ManifestValidator.cs,
+      `TryValidateFields(...)`; stated for authors at
+      https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Manifest ("These are mutually
+      exclusive — you can't specify both.")
+    tags:
+      - manifest
+      - validator
+      - block
+      - entrydll
+      - contentpackfor
+    detail: This is checked before anything else and it is the most common concrete manifest error. A
+      `block`-severity validator with SMAPI's own wording is the right shape. The same condition
+      also decides the mod's *type* during scanning, so getting it wrong makes the folder
+      `ModType.Invalid` rather than producing a partially working mod.
+  - id: stardewvalley.smapi.manifest.validation-order
+    claim: "SMAPI validates the manifest in a fixed order and returns on the first failure:
+      EntryDll/ContentPackFor exclusivity, then EntryDll filename characters, then ContentPackFor's
+      required UniqueID, then missing required fields (Name, Version, UniqueID), then the UniqueID
+      slug format, then each dependency entry."
+    status: inferred
+    source: SMAPI develop, src/SMAPI.Toolkit/Framework/ManifestValidator.cs,
+      `TryValidateFields(IManifest manifest, out string error)`
+    tags:
+      - manifest
+      - validator
+      - order
+      - errors
+    detail: "The method's own header comment explains why every message is a sentence fragment: \"SMAPI
+      assumes that it can grammatically append the returned sentence in the form `failed loading
+      <mod> because its <error>`. Any errors returned should be valid in that format\". That is what
+      makes them matchable in a log."
+  - id: stardewvalley.smapi.manifest.version-zero-counts-as-missing
+    claim: "A `Version` of `\"0.0.0\"` is treated as *missing*, not as a version: SMAPI's required-field
+      check is `if (manifest.Version == null || manifest.Version.ToString() == \"0.0.0\")`."
+    status: inferred
+    source: SMAPI develop, src/SMAPI.Toolkit/Framework/ManifestValidator.cs, `TryValidateFields(...)`
+      required-fields block
+    tags:
+      - manifest
+      - version
+      - validator
+      - block
+      - gotcha
+    detail: No JSON Schema expresses this — `0.0.0` matches the published SemanticVersion pattern
+      perfectly — so a validator that only runs the schema will pass a manifest SMAPI will refuse
+      with "manifest is missing required fields (Version)." It is a realistic default value for a
+      generated project file, which is why it is worth a dedicated rule.
+  - id: stardewvalley.smapi.manifest.uniqueid-format
+    claim: "`UniqueID` must match `^[a-zA-Z0-9_.-]+$` (letters, numbers, underscores, periods, hyphens)
+      to pass the published schema; SMAPI's runtime check (`PathUtilities.IsSlug`, rejection class
+      `[^\\p{L}\\d_\\.\\-]`) accepts any Unicode letter, so a non-ASCII id loads and only the schema
+      objects. The recommended format is `<your name>.<mod name>`, and once published it must never
+      change, because other mods reference it."
+    status: community
+    source: 'Pattern and its provenance from https://smapi.io/schemas/manifest.json (`"ModID": { "type":
+      "string", "pattern": "^[a-zA-Z0-9_.-]+$", "$comment": "derived from
+      SMAPI.Toolkit.Utilities.PathUtilities.IsSlug" }`); the runtime check from SMAPI develop,
+      src/SMAPI.Toolkit/Utilities/PathUtilities.cs: `return string.IsNullOrEmpty(str) ||
+      !Regex.IsMatch(str, @"[^\p{L}\d_\.\-]", RegexOptions.IgnoreCase);`; the rule and the "do not
+      change this unique ID in future versions of the same mod" instruction from
+      https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Manifest'
+    tags:
+      - manifest
+      - uniqueid
+      - slug
+      - validator
+      - block
+    detail: SMAPI's own failure text is "manifest specifies an invalid ID (IDs must only contain
+      letters, numbers, underscores, periods, or hyphens)." The same slug rule applies to every
+      `Dependencies[].UniqueID`.
+  - id: stardewvalley.smapi.manifest.semantic-version-pattern
+    claim: "`Version` must match
+      `^(?>(?:0|[1-9]\\d*))\\.(?>(?:0|[1-9]\\d*))(?>(?:\\.(?:0|[1-9]\\d*))?)(?:-(?:(?>[a-zA-Z0-9]+[\
+      \\-\\.]?)+))?$` or be the literal string `%ProjectVersion%` to pass the published schema. The
+      patch segment is optional. Build metadata (`+...`) is rejected by the schema but parsed by
+      SMAPI's runtime `SemanticVersionReader`, so a `1.2.0+build5` loads; the runtime is
+      authoritative and a validator should warn, not block."
+    status: community
+    source: "https://smapi.io/schemas/manifest.json, `definitions.SemanticVersion` (with `\"$comment\":
+      \"derived from SMAPI.Toolkit.SemanticVersion\"`) and the `anyOf` on the `Version` property;
+      the runtime's build-metadata branch from SMAPI develop,
+      src/SMAPI.Toolkit/Framework/SemanticVersionReader.cs: `// read optional build tag / if
+      (TryParseLiteral(raw, ref i, '+') && !TryParseTag(raw, ref i, out buildMetadata)) return
+      false;` — reached whether or not `allowNonStandard` is set"
+    tags:
+      - manifest
+      - version
+      - semver
+      - validator
+      - pattern
+    detail: "Two consequences a hand-written rule gets wrong: `1.2` is valid (the patch part is
+      optional), and `1.2.0+build5` fails the schema while loading in SMAPI
+      (src/SMAPI.Toolkit/Framework/SemanticVersionReader.cs parses the build-metadata segment). The
+      schema's own error message is \"Invalid Value. This must be formatted like 1.2.0 or
+      1.2.0-prerelease.tags ..., or the exact string '%ProjectVersion%'.\""
+  - id: stardewvalley.smapi.manifest.project-version-token
+    claim: "`\"Version\": \"%ProjectVersion%\"` in a manifest is replaced with the `.csproj`'s
+      `<Version>` at build time by the ModBuildConfig NuGet package, in both the deployed copy and
+      the release zip."
+    status: community
+    source: 'https://github.com/Pathoschild/SMAPI/blob/develop/docs/technical/mod-package.md, "Manifest
+      tokens": "you can use `%ProjectVersion%` in your manifest.json. This will be replaced with
+      your project version automatically in your game folder and the release zip."'
+    tags:
+      - manifest
+      - version
+      - build
+      - modbuildconfig
+      - scaffold
+    detail: Added in ModBuildConfig 4.4.0 (13 April 2025). A scaffold for a C# mod should use it, since
+      it removes an entire class of "the manifest says 1.0.0 and the DLL says 1.2.0" drift. It also
+      works for bundled content packs.
+  - id: stardewvalley.smapi.manifest.entrydll-must-exist
+    claim: "`EntryDll` must match `^[a-zA-Z0-9_.-]+\\.dll$`, must contain no invalid filename
+      characters, and must name a file that actually exists in the mod folder — SMAPI refuses the
+      mod with \"its DLL '{EntryDll}' doesn't exist.\""
+    status: inferred
+    source: Pattern from https://smapi.io/schemas/manifest.json; the character check and the existence
+      check from SMAPI develop, src/SMAPI.Toolkit/Framework/ManifestValidator.cs and
+      src/SMAPI/Framework/ModLoading/ModResolver.cs `ValidateManifests(...)`
+    tags:
+      - manifest
+      - entrydll
+      - validator
+      - block
+      - filesystem
+    detail: "The existence check is a pure filesystem check with no game, no index and no toolchain, and
+      it catches a mod that will not load at all. Highest value per line of code of any rule in this
+      file. It applies to the manifest SMAPI reads, the deployed one: a C# project's source manifest
+      sits beside its .csproj and the DLL is a build output (the build package assembles that
+      folder, the manifest beside the DLL with %ProjectVersion% substituted, when it deploys or
+      zips), so a validator reading the source tree must not block on it there."
+  - id: stardewvalley.smapi.manifest.dependencies-shape
+    claim: "`Dependencies` is a list of `{ UniqueID, MinimumVersion?, IsRequired? }`. `MinimumVersion`
+      is optional (\"If specified, older versions won't meet the requirement\"); `IsRequired: false`
+      makes the dependency optional — \"It will be loaded first if it's installed, otherwise it'll
+      be ignored.\""
+    status: community
+    source: https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Manifest, the Dependencies section
+      and its two worked examples
+    tags:
+      - manifest
+      - dependencies
+      - load-order
+      - validator
+    detail: Note that an optional dependency still *orders* the load when present — the flag only
+      decides whether a missing one is fatal, exactly as BepInEx's SoftDependency does on Valheim.
+      Validation rejects a null entry, a blank `UniqueID`, or a non-slug `UniqueID`, each with its
+      own message.
+  - id: stardewvalley.smapi.manifest.contentpackfor-shape
+    claim: '`ContentPackFor` is `{ UniqueID, MinimumVersion? }` naming the framework mod that reads this
+      pack — for Content Patcher, `{"UniqueID": "Pathoschild.ContentPatcher"}`. A blank `UniqueID`
+      fails with "manifest declares ContentPackFor without its required UniqueID field."'
+    status: community
+    source: https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Manifest ("For a content pack,
+      ContentPackFor specifies which mod can read it. The MinimumVersion is optional."); the failure
+      text from src/SMAPI.Toolkit/Framework/ManifestValidator.cs
+    tags:
+      - manifest
+      - contentpackfor
+      - content-pack
+      - scaffold
+    detail: The `UniqueID` here names the *framework* that reads the pack, not the pack itself, so it
+      stays `Pathoschild.ContentPatcher` while every other id in the file is the author's own — an
+      easy thing to overwrite when a scaffold's placeholders are filled in by hand. No source says
+      this explicitly; it follows from the wiki's own definition ("ContentPackFor specifies which
+      mod can read it") and from `ModResolver` resolving the id against an installed mod.
+  - id: stardewvalley.smapi.manifest.minimum-versions
+    claim: '`MinimumApiVersion` and `MinimumGameVersion` set the minimum SMAPI and Stardew Valley
+      versions needed. A player below either sees the mod skipped with "it needs SMAPI {v} or
+      later..." or "it needs Stardew Valley {v} or later...".'
+    status: community
+    source: https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Manifest ("If a player tries to use
+      the mod with an older version, they'll see a friendly message saying they need to update
+      it."); the two messages from src/SMAPI/Framework/ModLoading/ModResolver.cs
+      `ValidateManifests(...)`
+    tags:
+      - manifest
+      - version
+      - compat
+      - validator
+    detail: "Worth a validator of its own: a mod declaring `MinimumApiVersion` higher than the SMAPI
+      installed on the machine under test will silently not load during testing, and the reason will
+      be in a list most people do not scroll to."
+  - id: stardewvalley.smapi.manifest.update-keys
+    claim: "`UpdateKeys` entries must match
+      `^(?i)(Chucklefish:\\d+|Nexus:\\d+|GitHub:[A-Za-z0-9_\\-\\.]+/[A-Za-z0-9_\\-]+|ModDrop:\\d+|C\
+      urseForge:\\d+)(?: *@ *[a-zA-Z0-9_]+ *)?$` — five sites plus an optional `@subkey`."
+    status: community
+    source: https://smapi.io/schemas/manifest.json, the `UpdateKeys` item pattern, whose error message
+      is "Invalid update key; see
+      https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Manifest#Update_checks for more info."
+    tags:
+      - manifest
+      - updatekeys
+      - distribution
+      - validator
+      - pattern
+    detail: This regex is also the machine-readable statement of which distribution channels SMAPI knows
+      about. Chucklefish is marked deprecated on the wiki. A bad key breaks update alerts rather
+      than the mod, so `warn`, not `block`.
+  - id: stardewvalley.smapi.manifest.update-subkeys
+    claim: An update subkey (`"Nexus:2400@GeodeCrusher"`) narrows an update check to files whose title
+      or description contains `@GeodeCrusher`, for the case of several mods sharing one mod page. If
+      no file matches the subkey SMAPI ignores it and does a normal check.
+    status: community
+    source: https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Update_checks (read 2026-09-11),
+      "Update subkeys"
+    tags:
+      - manifest
+      - updatekeys
+      - subkey
+      - distribution
+    detail: "Two documented caveats: CurseForge subkeys in a file description are not visible through
+      its API, and GitHub subkeys do nothing because only the latest release is fetched."
+  - id: stardewvalley.smapi.manifest.name-brackets-are-rewritten
+    claim: SMAPI strips newlines from every manifest string field, and in `Name` only it replaces `[`
+      with `(` and `]` with `)`, with the in-source reason that this "is used in the mod name to
+      avoid breaking the log format".
+    status: inferred
+    source: SMAPI develop, src/SMAPI.Toolkit/Serialization/Models/Manifest.cs, `NormalizeField(string?
+      input, bool replaceSquareBrackets = false)`
+    tags:
+      - manifest
+      - name
+      - log
+      - signature
+      - gotcha
+    detail: "Relevant to log signatures: a mod's display name in a log line can never contain a square
+      bracket, which is what lets SMAPI's own `MessageHeaderPattern` end the source capture at the
+      first `]`. It also means a pack folder named `[CP] Something` will appear in the log as `(CP)
+      Something` if that string is also its `Name`."
+  - id: stardewvalley.smapi.manifest.published-json-schema
+    claim: 'SMAPI publishes a JSON Schema for the manifest at `https://smapi.io/schemas/manifest.json`,
+      referenceable from a file with `"$schema": "https://smapi.io/schemas/manifest.json"`. Its
+      required set is `["Name", "Author", "Version", "Description", "UniqueID"]`.'
+    status: community
+    source: https://github.com/Pathoschild/SMAPI/blob/develop/docs/technical/web.md, "Using a schema
+      file directly", which tabulates the three published schemas; the required set read from
+      https://smapi.io/schemas/manifest.json on 2026-09-11
+    tags:
+      - manifest
+      - schema
+      - validator
+      - smapi-io
+      - tooling
+    detail: No other ModWright surface has a first-party machine-readable schema for its authored
+      format. Validating against it and adding only the rules it cannot state — the `0.0.0` case,
+      the EntryDll existence check, and the additionalProperties disagreement — is strictly better
+      than maintaining an independent opinion. The web validator that uses it is at smapi.io/json.

package/knowledge/stardewvalley/toolchain.build.yaml

@@ -0,0 +1,261 @@
+game: stardewvalley
+topic: toolchain.build
+title: Building a Stardew mod — the ModBuildConfig NuGet package, the release zip, and XNB unpacking
+facts:
+  - id: stardewvalley.toolchain.build.modbuildconfig-package
+    claim: The build toolchain is one NuGet package, `Pathoschild.Stardew.ModBuildConfig`, currently
+      4.4.0 (13 April 2025) "for SMAPI 4.1.0 or later". It finds the game folder, adds the game and
+      SMAPI assembly references, deploys the mod and builds a release zip.
+    status: community
+    source: https://github.com/Pathoschild/SMAPI/blob/develop/docs/technical/mod-package.md ("an
+      open-source NuGet package which automates the MSBuild configuration for SMAPI mods and related
+      tools"); version list from
+      https://api.nuget.org/v3-flatcontainer/pathoschild.stardew.modbuildconfig/index.json and the
+      release notes at docs/technical/mod-package-release-notes.md, both read 2026-09-11
+    tags:
+      - build
+      - nuget
+      - msbuild
+      - csharp
+      - toolchain
+    detail: A content pack needs none of this — there is nothing to compile — which is why a Stardew
+      surface can do most of its work with no toolchain at all.
+  - id: stardewvalley.toolchain.build.assembly-references
+    claim: "The package adds exactly seven references, all resolved out of the installed game folder:
+      `Stardew Valley.dll`, `StardewValley.GameData.dll`, `MonoGame.Framework.dll`, `xTile.dll`,
+      `StardewModdingAPI.dll`, `smapi-internal\\SMAPI.Toolkit.CoreInterfaces.dll`, and — only when
+      `EnableHarmony` is true — `smapi-internal\\0Harmony.dll`."
+    status: inferred
+    source: SMAPI develop,
+      https://github.com/Pathoschild/SMAPI/blob/develop/src/SMAPI.ModBuildConfig/build/smapi.targets,
+      the `<Reference>` ItemGroup
+    tags:
+      - build
+      - references
+      - csharp
+      - dist
+      - validator
+    detail: "These seven names are exactly the never-ships list for a dist validator: they are game and
+      loader assemblies, copy-local only when `BundleExtraAssemblies` includes `Game`, which the
+      docs mark as \"a specialized option. Most mods should not change this option.\" A mod folder
+      or release zip containing any of them is a packaging error of the same shape as ModWright's
+      existing `vanilla-extract-never-ships` rule."
+  - id: stardewvalley.toolchain.build.requires-the-game-installed
+    claim: 'The build package hard-fails when the game or SMAPI is missing, with three MSBuild errors:
+      the game folder not existing, the folder not containing `Stardew Valley.dll`, and the folder
+      not containing `StardewModdingAPI.dll` ("You need to install SMAPI before building the
+      mod.").'
+    status: inferred
+    source: SMAPI develop, src/SMAPI.ModBuildConfig/build/smapi.targets, the `BeforeBuild` target's
+      three `<Error Condition="!Exists(...)">` elements
+    tags:
+      - build
+      - requires-game
+      - csharp
+      - blocking
+      - testing
+    detail: So a C# Stardew mod **cannot be compiled on a machine without the game and SMAPI installed**
+      — a sharper constraint than any other supported game, where the payload is data. A content
+      pack has no such constraint. This is the main argument for making a first Stardew project a
+      content pack.
+  - id: stardewvalley.toolchain.build.anycpu-warning
+    claim: "The package warns when the target platform is not `AnyCPU`: \"The target platform should be
+      set to 'Any CPU' for compatibility with both 32-bit and 64-bit versions of Stardew Valley
+      (currently set to '{x}').\""
+    status: inferred
+    source: SMAPI develop, src/SMAPI.ModBuildConfig/build/smapi.targets, the `BeforeBuild` target's
+      `<Warning Condition="'$(Platform)' != 'AnyCPU'" ...>`
+    tags:
+      - build
+      - csproj
+      - validator
+      - warn
+    detail: Checkable statically from the `.csproj`, so it is a validator ModWright can run before
+      MSBuild does. The internal value is `AnyCPU`; Visual Studio shows it as "Any CPU".
+  - id: stardewvalley.toolchain.build.deploy-and-zip-properties
+    claim: "The build package deploys and zips by default: `EnableModDeploy` (default true) copies the
+      mod into `$(GameModsPath)`, which defaults to `$(GamePath)/Mods`; `EnableModZip` (default
+      true) writes a release zip into `$(ModZipPath)`, which defaults to the project's `bin` folder;
+      `ModFolderName` defaults to the project name."
+    status: inferred
+    source: SMAPI develop, src/SMAPI.ModBuildConfig/build/smapi.targets, the default PropertyGroup;
+      documented at https://github.com/Pathoschild/SMAPI/blob/develop/docs/technical/mod-package.md
+      under "Available properties"
+    tags:
+      - build
+      - deploy
+      - zip
+      - msbuild
+      - conflict
+    detail: "This collides with ModWright owning deploy: MSBuild would copy the same files with no
+      backup and no write plan. A ModWright-managed project should set
+      `<EnableModDeploy>false</EnableModDeploy>` and `<EnableModZip>false</EnableModZip>` so deploy
+      stays a `WritePlan` over `core/safety` with a rollback. That should be a documented
+      requirement of the scaffold, not a surprise discovered when two systems write the same files."
+  - id: stardewvalley.toolchain.build.release-zip-shape
+    claim: The release zip is named `{ModFolderName} {Version}.zip` and its entries are
+      `{ModFolderName}/{relative path}`, with forward slashes regardless of OS — so unzipping it
+      into `Mods/` produces a correctly nested mod folder.
+    status: inferred
+    source: 'SMAPI develop,
+      https://github.com/Pathoschild/SMAPI/blob/develop/src/SMAPI.ModBuildConfig/DeployModTask.cs:
+      `string zipName = this.EscapeInvalidFilenameCharacters($"{this.ModFolderName}
+      {manifest.Version}.zip");` and `archivePath = $"{this.ModFolderName}/{relativePath}"` with the
+      comment "zip files use forward slashes regardless of OS"'
+    tags:
+      - build
+      - zip
+      - packaging
+      - verify
+      - validator
+    detail: "A ModWright build's verify step can assert exactly this: one top-level folder named after
+      the mod, containing `manifest.json`. Bundled content packs nest one level deeper as
+      `{ModFolderName}/{contentPackFolder}/...`."
+  - id: stardewvalley.toolchain.build.ignore-properties
+    claim: "`IgnoreModFilePaths` (a comma-delimited list of literal paths relative to `bin`) and
+      `IgnoreModFilePatterns` (a comma-delimited list of regexes) exclude files from both the deploy
+      and the zip. Path delimiters in a pattern should be written `[/\\\\]` for crossplatform use."
+    status: community
+    source: https://github.com/Pathoschild/SMAPI/blob/develop/docs/technical/mod-package.md,
+      "Specialized properties", with the worked example `<IgnoreModFilePatterns>\.txt$, \.pdf$,
+      assets[/\\]paths.png</IgnoreModFilePatterns>`
+    tags:
+      - build
+      - packaging
+      - exclude
+      - msbuild
+    detail: "The literal-path list is case-sensitive but normalises path delimiters. Relevant to a dist
+      validator: if a project excludes a file here, the file is still in `bin` and a naive staging
+      step that copies `bin` wholesale would ship it."
+  - id: stardewvalley.toolchain.build.bundled-content-packs
+    claim: A C# mod can bundle content packs with a `<ContentPacks Include="..." Version="$(Version)"
+      />` item group; they are grouped under a parent folder in both the deploy and the zip, and the
+      package validates that each bundled pack's manifest version matches the declared `Version`.
+    status: community
+    source: https://github.com/Pathoschild/SMAPI/blob/develop/docs/technical/mod-package.md, "Bundled
+      content packs", and the per-item property table (`Include`, `Version`, `FolderName`,
+      `ValidateManifest`, `IgnoreModFilePaths`, `IgnoreModFilePatterns`)
+    tags:
+      - build
+      - content-pack
+      - bundling
+      - validator
+    detail: "The version cross-check is a validator ModWright can perform statically and should: a mod
+      whose bundled pack's version drifts from the parent's produces out-of-sync update alerts,
+      which is exactly what the `Version` property exists to prevent."
+  - id: stardewvalley.toolchain.build.code-analyzers
+    claim: "The package ships Roslyn analyzers that raise two Stardew-specific warnings at build time:
+      \"'{{expression}}' is a {{net type}} field; consider using the {{property name}} property
+      instead.\" and \"The '{{old field}}' field is obsolete and should be replaced with '{{new
+      field}}'.\""
+    status: community
+    source: https://github.com/Pathoschild/SMAPI/blob/develop/docs/technical/mod-package.md, "Code
+      warnings"; the analyzers themselves are src/SMAPI.ModBuildConfig.Analyzer/NetFieldAnalyzer.cs
+      and ObsoleteFieldAnalyzer.cs
+    tags:
+      - build
+      - analyzer
+      - csharp
+      - validator
+      - netfield
+    detail: These are compile-time checks ModWright should not duplicate — they run inside MSBuild and
+      are strictly better placed there. A ModWright build step should surface them from the build
+      output rather than reimplement them. ModBuildConfig 4.3.1 removed the implicit net-field
+      conversion warnings, "which were removed in Stardew Valley 1.6.9".
+  - id: stardewvalley.toolchain.build.unit-test-settings
+    claim: The documented settings for a unit-test or framework project using this package are
+      `<EnableGameDebugging>false</EnableGameDebugging>`,
+      `<EnableModDeploy>false</EnableModDeploy>`, `<EnableModZip>false</EnableModZip>` and
+      `<BundleExtraAssemblies>All</BundleExtraAssemblies>` — and the docs note "you still need a
+      game install on the machine running the tests."
+    status: community
+    source: https://github.com/Pathoschild/SMAPI/blob/develop/docs/technical/mod-package.md, "Unit tests"
+    tags:
+      - build
+      - tests
+      - csharp
+      - requires-game
+    detail: "Confirms the constraint from the other direction: even a test project for a Stardew C# mod
+      needs the game present, because the references resolve out of the game folder."
+  - id: stardewvalley.toolchain.build.dotnet-is-the-only-compiler-tool
+    claim: Building a C# Stardew mod needs nothing but the .NET SDK — `dotnet build` — plus the NuGet
+      package and an installed game. There is no game-specific packer, archiver or asset compiler in
+      the pipeline.
+    status: inferred
+    source: Derived from src/SMAPI.ModBuildConfig/build/smapi.targets (an ordinary MSBuild targets file
+      with one custom task, `DeployModTask`) and from the absence of any other tool in
+      https://github.com/Pathoschild/SMAPI/blob/develop/docs/technical/mod-package.md
+    tags:
+      - build
+      - dotnet
+      - toolchain
+      - toolspec
+    detail: So the only new `ToolSpec` a Stardew surface needs for building is `dotnet` (`--version`,
+      which prints a bare version) — the same spec a Valheim surface needs, which argues for adding
+      it once centrally rather than twice.
+  - id: stardewvalley.toolchain.build.stardewxnbhack
+    claim: The recommended XNB unpacker is StardewXnbHack, currently 1.1.2 (6 November 2024). It is
+      one-way — "It can't pack files back into .xnb, but you rarely need to" — and its output is
+      already Content Patcher-compatible.
+    status: community
+    source: https://stardewvalleywiki.com/Modding:Editing_XNB_files (read 2026-09-11); version from the
+      GitHub releases API for Pathoschild/StardewXnbHack, read 2026-09-11
+    tags:
+      - xnb
+      - unpack
+      - index
+      - toolspec
+      - requires-game
+    detail: Because it is one-way there is no round trip to verify, so it belongs in `index` as an
+      extraction step and not in `core/text` as a converter — the converter contract there is built
+      on round-trip verification.
+  - id: stardewvalley.toolchain.build.stardewxnbhack-installs-into-the-game-folder
+    claim: StardewXnbHack is installed *into the game folder* — "Unzip the download into your game
+      folder, so StardewXnbHack.exe is in the same folder as StardewValley.exe" — and is run by
+      double-clicking it, producing a `Content (unpacked)` folder beside `Content`.
+    status: community
+    source: "https://stardewvalleywiki.com/Modding:Editing_XNB_files (read 2026-09-11), the
+      StardewXnbHack section: \"Install SMAPI. Download StardewXnbHack ... Unzip the download into
+      your game folder ... it'll unpack the files into a Content (unpacked) folder. The unpacked
+      files will already be compatible with Content Patcher.\""
+    tags:
+      - xnb
+      - unpack
+      - toolspec
+      - candidates
+      - install
+    detail: "Two consequences for a `ToolSpec`: its primary candidate path is derived from a
+      `GameInstall` rather than from a convention, which no existing spec does; and it requires
+      SMAPI to be installed first, so it is not usable on a machine without the game at all. No CLI
+      version flag was confirmed from the project's own docs, so `versionArgs` should be left unset
+      rather than guessed."
+  - id: stardewvalley.toolchain.build.xnbcli-is-not-recommended
+    claim: "The alternative unpacker xnbcli can pack as well as unpack, but the wiki steers away from
+      it: it \"can't unpack XNB files containing data models (like Data\\FishPondData or
+      Data\\Movies); use StardewXnbHack if you need those\", and its data output needs a manual
+      post-processing step."
+    status: community
+    source: https://stardewvalleywiki.com/Modding:Editing_XNB_files (read 2026-09-11), the xnbcli
+      section and its "removing the XNB metadata" instructions
+    tags:
+      - xnb
+      - unpack
+      - toolspec
+      - rejected
+    detail: The manual step is to delete everything except the `content` field from the emitted JSON,
+      leaving the bare lookup — a documented footgun. Adding xnbcli as a second `ToolSpec` would be
+      adding that footgun to ModWright, so the recommendation is not to.
+  - id: stardewvalley.toolchain.build.repacking-is-unnecessary
+    claim: "There is no need to repack anything for a modern mod: \"There's no need to repack game files
+      if you're using Content Patcher! Just use the .json, .png, .tmx, or .tbin file directly in
+      your content.json.\""
+    status: community
+    source: https://stardewvalleywiki.com/Modding:Editing_XNB_files (read 2026-09-11), "Pack game files"
+    tags:
+      - xnb
+      - contentpatcher
+      - build
+      - assets
+    detail: "This is why a Stardew surface needs no text converters and no archive packer: every
+      authored asset ships in its source format. Maps are `.tmx`/`.tbin`, images are PNG, data is
+      JSON."