modwright 0.1.0

package/knowledge/stardewvalley/contentpatcher.format.yaml

@@ -0,0 +1,338 @@
+game: stardewvalley
+topic: contentpatcher.format
+title: Content Patcher — content.json, the Format version, and every way a patch is silently ignored
+facts:
+  - id: stardewvalley.contentpatcher.format.what-a-pack-is
+    claim: 'A Content Patcher pack is a folder with `manifest.json` and `content.json`, usually plus an
+      `assets/` subfolder, installed under `Mods/` like any other mod. Its manifest declares
+      `"ContentPackFor": {"UniqueID": "Pathoschild.ContentPatcher"}` and no `EntryDll`.'
+    status: community
+    source: 'https://github.com/Pathoschild/StardewMods/blob/develop/ContentPatcher/docs/author-guide.md
+      (read 2026-09-11): "A content pack is just a folder with two text files in it: manifest.json
+      (which has info like your mod name) and content.json (which tells Content Patcher what you
+      want to change). Your folder might also have images or other files, which are usually in an
+      assets subfolder by convention"'
+    tags:
+      - contentpatcher
+      - content-pack
+      - layout
+      - scaffold
+    detail: The documented folder-name convention is `[CP] YourModName`. Because there is no compiled
+      artifact, a content pack needs no toolchain at all — which is why the validator family for
+      this format is the highest-value thing a Stardew surface can build without the game.
+  - id: stardewvalley.contentpatcher.format.version-and-smapi-floor
+    claim: Content Patcher 2.9.1 is the current release, "Released 14 March 2026 for SMAPI 4.4.0 or
+      later", and the README states compatibility as "Content Patcher is compatible with Stardew
+      Valley 1.6+ on Linux/macOS/Windows, both single-player and multiplayer."
+    status: community
+    source: https://github.com/Pathoschild/StardewMods/blob/develop/ContentPatcher/docs/release-notes.md
+      and .../docs/README.md, both read 2026-09-11
+    tags:
+      - contentpatcher
+      - version
+      - compat
+      - rule
+    detail: The repository publishes no GitHub releases, so the release-notes headings are the only
+      version oracle. The previous feature release is 2.9.0, "Released 11 January 2026 for SMAPI
+      4.4.0 or later".
+  - id: stardewvalley.contentpatcher.format.format-field-is-a-cp-version
+    claim: "`content.json`'s `Format` field is not a schema number; it is the version of Content Patcher
+      the pack was designed for, and is used to keep older packs working. The current value is
+      `2.9.0`."
+    status: community
+    source: 'https://github.com/Pathoschild/StardewMods/blob/develop/ContentPatcher/docs/author-guide.md:
+      "That Format field is the version of Content Patcher for which you designed the content pack.
+      This is used to keep your content pack compatible with future versions. You should always use
+      the latest format version (currently 2.9.0) to enable the latest features, avoid obsolete
+      behavior, and reduce startup time."'
+    tags:
+      - contentpatcher
+      - format
+      - version
+      - migration
+      - validator
+    detail: Content Patcher ships a migration per format version — roughly forty
+      `Framework/Migrations/Migration_*.cs` files from `Migration_1_3` to `Migration_2_9` — so an
+      older `Format` still loads. A validator must report a low `Format` as `warn`, never `block`.
+  - id: stardewvalley.contentpatcher.format.schema-pins-the-current-version
+    claim: 'The published JSON Schema pins `Format` to the current release with `"pattern":
+      "^2\\.9\\.[0-9]+$"`, so a pack written against an older format fails the schema while still
+      loading fine in game.'
+    status: community
+    source: https://smapi.io/schemas/content-patcher.json (read 2026-09-11), the `Format` property,
+      whose `@errorMessages.pattern` is "Incorrect value '@value'. You should always use the latest
+      format version (currently 2.9.0) to enable the latest features, avoid obsolete behavior, and
+      reduce load times."
+    tags:
+      - contentpatcher
+      - schema
+      - format
+      - validator
+      - conflict
+    detail: 'This is a schema-versus-runtime disagreement that a validator must handle deliberately: the
+      schema expires on every Content Patcher release, the runtime does not. Run the schema, then
+      downgrade this one finding to `warn`. The schema also sets `required: ["Format", "Changes"]`
+      and `additionalProperties: false`.'
+  - id: stardewvalley.contentpatcher.format.top-level-fields
+    claim: "`content.json`'s top-level fields are `Format`, `Changes`, `ConfigSchema`,
+      `CustomLocations`, `DynamicTokens` and `AliasTokenNames`."
+    status: inferred
+    source: Content Patcher develop,
+      https://github.com/Pathoschild/StardewMods/blob/develop/ContentPatcher/Framework/ConfigModels/ContentConfig.cs,
+      the constructor parameters; corroborated by the property list in
+      https://smapi.io/schemas/content-patcher.json
+    tags:
+      - contentpatcher
+      - content-json
+      - fields
+      - schema
+  - id: stardewvalley.contentpatcher.format.five-actions
+    claim: Every patch has an `Action` of `Load`, `EditData`, `EditImage`, `EditMap` or `Include`.
+      `Load` "replaces an entire asset with a version you provide"; the three `Edit*` actions can be
+      applied by any number of packs to the same asset; `Include` "adds patches from another file".
+    status: community
+    source: "https://github.com/Pathoschild/StardewMods/blob/develop/ContentPatcher/docs/author-guide.m\
+      d, the Actions table; the enum members are confirmed by PatchLoader's own error text
+      \"expected one of: {string.Join(\", \", Enum.GetNames(typeof(PatchType)))}\""
+    tags:
+      - contentpatcher
+      - actions
+      - patches
+      - validator
+    detail: The guide advises against `Load` where an `Edit*` will do ("This isn't recommended if you
+      can use one of the Edit* actions instead"), because only one pack can `Load` a given asset
+      while any number can edit it. That is a real conflict-avoidance rule and worth an `info`
+      validator.
+  - id: stardewvalley.contentpatcher.format.patch-fields
+    claim: A patch's fields are `LogName`, `Action`, `Target`, `TargetLocale`, `Update`, `FromFile`,
+      `Enabled`, `When`, `Priority`, `LocalTokens`, `TextOperations`, `FromArea`, `ToArea`,
+      `PatchMode`, `Entries`, `Fields`, `MoveEntries`, `TargetField`, `MapProperties`,
+      `AddNpcWarps`, `AddWarps` and `MapTiles`.
+    status: inferred
+    source: Content Patcher develop,
+      https://github.com/Pathoschild/StardewMods/blob/develop/ContentPatcher/Framework/ConfigModels/PatchConfig.cs
+    tags:
+      - contentpatcher
+      - patches
+      - fields
+      - schema
+    detail: "`TargetLocale` is documented in source as \"the locale code in the target asset's name to
+      match (like fr-FR ...), or an empty string to match only the base unlocalized asset, or null
+      to match all localized or unlocalized variants\" — a three-way distinction that is easy to get
+      wrong and invisible in testing if the author only plays in English."
+  - id: stardewvalley.contentpatcher.format.asset-names-have-no-extension
+    claim: 'A `Target` is an asset name, not a file path: it never includes "Content", the language
+      code, or the file extension. `Content/Maps/spring_beach.xnb` and
+      `Content/Maps/spring_beach.fr-FR.xnb` are both the asset `Maps/spring_beach`.'
+    status: community
+    source: https://github.com/Pathoschild/StardewMods/blob/develop/ContentPatcher/docs/author-guide.md,
+      "What is an asset?"
+    tags:
+      - contentpatcher
+      - target
+      - asset
+      - index
+      - validator
+    detail: "A validator that checks a `Target` against a vanilla index must key on this form, and must
+      not accept a `.xnb` suffix. SMAPI's 4.0 migration guide makes the same point for C# mods:
+      \"When loading assets from helper.GameContent, don't add a .xnb file extension\"."
+  - id: stardewvalley.contentpatcher.format.tokens-and-conditions
+    claim: "Most fields accept `{{token}}` interpolation, and a patch's `When` block maps token names to
+      accepted values; tokens include `{{season}}`, `{{Spouse}}`, `{{Time}}`, `{{Language}}`,
+      `{{ModId}}` and `{{i18n: key}}`, plus author-defined `DynamicTokens`, `LocalTokens` and
+      `ConfigSchema` values."
+    status: community
+    source: 'https://github.com/Pathoschild/StardewMods/blob/develop/ContentPatcher/docs/author-guide.md,
+      the Tokens & conditions section and its worked examples (`"FromFile":
+      "assets/abigail-{{season}}.png"`, `"When": {"Spouse": "Abigail"}`)'
+    tags:
+      - contentpatcher
+      - tokens
+      - conditions
+      - validator
+      - static-analysis
+    detail: "Tokens are what makes static validation partial rather than complete: a `FromFile`
+      containing a token cannot be resolved to one path. The honest validator resolves tokenless
+      paths exactly and, for tokenised ones, checks that at least one file could match, reporting
+      `warn` with the reason when it cannot tell."
+  - id: stardewvalley.contentpatcher.format.whole-pack-rejection-messages
+    claim: "A pack is rejected whole with `Could not load content pack '{name}': {error}.` at Error,
+      where the error is one of \"content pack has no content.json file\", \"content pack doesn't
+      specify the required Format field.\", \"content pack must specify the Changes or
+      CustomLocations fields.\", or a migration failure."
+    status: inferred
+    source: Content Patcher develop,
+      https://github.com/Pathoschild/StardewMods/blob/develop/ContentPatcher/Framework/RawContentPack.cs
+      `TryReloadContent(out string? error)`, logged by ContentPatcher/ModEntry.cs
+      `GetContentPacks()`
+    tags:
+      - contentpatcher
+      - errors
+      - log
+      - signature
+      - validator
+    detail: Two sibling Error lines from the same method are `Error preloading content pack '{name}'.
+      Technical details:\n{ex}` and `Error loading configuration for content pack '{name}'.
+      Technical details:\n{ex}`, both multi-line.
+  - id: stardewvalley.contentpatcher.format.patch-skip-line-shape
+    claim: "An individual patch that fails to load is reported as `Ignored {path}: {reason}.` at
+      **Warn** — never Error — where `path` is the pack name plus the patch's `LogName`, and the
+      reason has its trailing period normalised on."
+    status: inferred
+    source: Content Patcher develop,
+      https://github.com/Pathoschild/StardewMods/blob/develop/ContentPatcher/Framework/PatchLoader.cs,
+      the `logSkip` callback and `TrackSkip(string reason, bool warn = true)` (`reason =
+      reason.TrimEnd('.', ' '); ... logSkip(reason + '.');`)
+    tags:
+      - contentpatcher
+      - errors
+      - log
+      - signature
+      - warn
+      - triage
+    detail: "Because it is Warn and not Error, it is easy to lose in a long log. That is exactly the
+      case a triage verdict should surface, and it must carry `systemImpact: false` so one broken
+      patch does not mark the whole mods system failed."
+  - id: stardewvalley.contentpatcher.format.patch-skip-reasons
+    claim: "The patch skip reasons include \"must set the Action field\", \"invalid Action value '{x}',
+      expected one of: ...\", \"must set the Target field\", \"the Target is invalid: {error}\",
+      \"the When field is invalid: {error}\", \"must set the FromFile field for a Load patch.\",
+      \"can't use the Target field with an Include patch.\", \"one of Entries, Fields, MoveEntries,
+      TextOperations, or FromFile must be specified for an '{action}' change\", \"FromFile is
+      mutually exclusive with Entries, Fields, and MoveEntries\", and \"the PatchMode is invalid.
+      Expected one of these values: [...]\"."
+    status: inferred
+    source: Content Patcher develop,
+      https://github.com/Pathoschild/StardewMods/blob/develop/ContentPatcher/Framework/PatchLoader.cs,
+      the `TrackSkip(...)` call sites in `LoadPatch(...)`
+    tags:
+      - contentpatcher
+      - errors
+      - validator
+      - block
+      - log
+    detail: "Each maps 1:1 onto a pre-build validator, so the validator's message can be the exact
+      sentence the player would otherwise have to find at Warn in the log. Also present: \"circular
+      field reference: Target field can't use the '...' tokens.\", \"the Enabled field is obsolete
+      and should be removed\", and \"the Priority value '{x}' is invalid: expected one of [...] or a
+      simple offset like '... + 10'\"."
+  - id: stardewvalley.contentpatcher.format.disabled-patch-logs-nothing
+    claim: 'In a pack whose `Format` is below 1.25.0, a patch with `"Enabled": false` is skipped with
+      **no log line at all** — `TrackSkip("Enabled is false", warn: false)` suppresses the warning.
+      From Format 1.25.0 on the field is obsolete: any value but the literal `true` skips the patch
+      with the Warn line `the Enabled field is obsolete and should be removed`, and `true` is
+      ignored.'
+    status: inferred
+    source: 'Content Patcher develop, ContentPatcher/Framework/PatchLoader.cs: `bool isEnabledAllowed =
+      rawContentPack.Content.Format!.IsOlderThan("1.25.0"); if (!isEnabledAllowed) { if
+      (!bool.TryParse(entry.Enabled, out bool raw) || !raw) return TrackSkip($"the
+      {nameof(PatchConfig.Enabled)} field is obsolete and should be removed"); }` and, below that
+      Format, `return TrackSkip($"{nameof(PatchConfig.Enabled)} is false", warn: false);`'
+    tags:
+      - contentpatcher
+      - silent-failure
+      - validator
+      - gotcha
+      - triage
+    detail: For a legacy-Format pack this is the classic "my patch does nothing and the log is clean"
+      cause, and it is invisible to log triage by construction; a current-Format pack gets one Warn
+      line instead, which the `stardewvalley.contentpatcher.patch-ignored` signature matches. It can
+      only be caught by a static validator reading `content.json`, which is a strong argument for
+      the validator family existing at all. A patch whose `When` conditions never match is similarly
+      silent and is visible only through `patch summary`.
+  - id: stardewvalley.contentpatcher.format.config-json-and-schema
+    claim: "A pack can declare a `ConfigSchema` in `content.json`; Content Patcher then creates and
+      reads a `config.json` in the pack folder and exposes each field as a token. Problems with it
+      are logged as `Ignored {pack} > {label}: {reason}` at Warn."
+    status: community
+    source: 'https://github.com/Pathoschild/StardewMods/blob/develop/ContentPatcher/docs/author-guide.md
+      (the `ConfigSchema` example with `AllowValues` and `Default`) and
+      .../docs/author-guide/config.md; the log line from ContentPatcher/ModEntry.cs (`new
+      ConfigFileHandler("config.json", this.ParseCommaDelimitedField, (pack, label, reason) =>
+      this.Monitor.Log($"Ignored {pack.Manifest.Name} > {label}: {reason}", LogLevel.Warn))`)'
+    tags:
+      - contentpatcher
+      - config
+      - tokens
+      - validator
+    detail: "`config.json` is generated, not authored, so it must not be shipped in a release zip and
+      must not be overwritten by a deploy — the player guide's \"merge update\" instructions exist
+      precisely to preserve it."
+  - id: stardewvalley.contentpatcher.format.patch-console-commands
+    claim: 'Content Patcher adds a `patch` console command family: `patch summary`, `patch update`,
+      `patch reload "<pack id>"`, `patch export "<asset>"`, `patch parse "<string>"`, `patch dump
+      order`, `patch dump applied` and `patch invalidate "<asset>"`.'
+    status: community
+    source: https://github.com/Pathoschild/StardewMods/blob/develop/ContentPatcher/docs/author-guide/troubleshooting.md
+      (read 2026-09-11)
+    tags:
+      - contentpatcher
+      - console
+      - verification
+      - bridge
+      - probe
+    detail: "`patch summary` prints a per-patch `loaded | conditions | applied` table \"along with their
+      current values, what they changed, and (if applicable) the reasons they weren't applied\" —
+      which answers most of what an in-game bridge probe would, if its output can be captured. That
+      is the cheapest verification question to settle on this game."
+  - id: stardewvalley.contentpatcher.format.patch-reload-is-real-hot-reload
+    claim: "`patch reload \"<content pack ID>\"` reloads one pack's patches while the game is running —
+      \"That lets you change your content pack's JSON files while the game is running, and see the
+      changes in-game without restarting the game\" — but \"Non-patch content (like config schema
+      and dynamic tokens) aren't reloaded\"."
+    status: community
+    source: https://github.com/Pathoschild/StardewMods/blob/develop/ContentPatcher/docs/author-guide/troubleshooting.md,
+      the `reload` section, whose example output is "Content pack reloaded."
+    tags:
+      - contentpatcher
+      - reload
+      - deploy
+      - hot-reload
+      - classifyreload
+    detail: "This is the only documented hot reload anywhere in this ecosystem and it makes
+      `classifyReload` genuinely useful here: in `ReloadAction`'s vocabulary (`hot | hot-degraded |
+      save-reload | restart | unknown`, from src/core/deploy/reload.ts) a `content.json` or asset
+      change is `hot` with `via: patch reload \"<pack id>\"`, while a `ConfigSchema` or
+      `DynamicTokens` change is `restart`. It also takes an optional second argument naming one
+      `Include` file to reload."
+  - id: stardewvalley.contentpatcher.format.verbose-log-and-logname
+    claim: "Content Patcher logs very little by default. Setting a `LogName` on each patch and enabling
+      SMAPI's `VerboseLogging` for `Pathoschild.ContentPatcher` makes it log at three points: when
+      loading patches, when SMAPI asks whether it can load or edit an asset, and whenever the
+      condition context changes."
+    status: community
+    source: "https://github.com/Pathoschild/StardewMods/blob/develop/ContentPatcher/docs/author-guide/t\
+      roubleshooting.md, \"Verbose log\": \"Content Patcher doesn't log much info. ... This may
+      significantly slow down loading, and should normally be left disabled unless you need it.\""
+    tags:
+      - contentpatcher
+      - verbose
+      - logging
+      - logname
+      - troubleshooting
+    detail: "The guide's own diagnostic sequence is worth reproducing in `guidance`: did Content Patcher
+      load the patch (if it says 'skipped', check `Enabled` or `config.json`); when the context
+      updates, is the box ticked next to the patch name (if not, check `When`); when SMAPI checks
+      the asset, is the box ticked (if not, check `When` and `Target`). A validator that sets
+      `LogName` in every scaffolded patch makes this sequence usable."
+  - id: stardewvalley.contentpatcher.format.published-json-schema
+    claim: Content Patcher's `content.json` has a published JSON Schema at
+      `https://smapi.io/schemas/content-patcher.json`, referenceable from the file with a `$schema`
+      field, and validatable in a browser at smapi.io/json.
+    status: community
+    source: "https://github.com/Pathoschild/SMAPI/blob/develop/docs/technical/web.md (\"Available
+      schemas ... Content Patcher: content.json | https://smapi.io/schemas/content-patcher.json\")
+      and .../ContentPatcher/docs/author-guide/troubleshooting.md (\"You can validate your
+      content.json and manifest.json automatically to detect some common issues. (You should still
+      test your content pack in-game before releasing it, since the validator won't detect all
+      issues.)\")"
+    tags:
+      - contentpatcher
+      - schema
+      - validator
+      - tooling
+      - smapi-io
+    detail: "The parenthetical is the whole argument for a ModWright validator family on top of the
+      schema: the schema checks JSON shape and cannot tell you that `assets/abigail-winter.png` is
+      missing, that a new item id is not namespaced, or that a `Fields` key names a field the model
+      does not have."

package/knowledge/stardewvalley/distribution.channels.yaml

@@ -0,0 +1,236 @@
+game: stardewvalley
+topic: distribution.channels
+title: Where Stardew mods are published, and the compatibility data that tracks them
+facts:
+  - id: stardewvalley.distribution.channels.nexus-is-primary-and-not-fetched
+    claim: Nexus Mods is the primary distribution channel for Stardew Valley mods. Per this repository's
+      standing rule, no nexusmods.com page was fetched for this research, so every distribution
+      claim here is sourced from the wiki or from SMAPI's own update-key vocabulary.
+    status: community
+    source: "https://stardewvalleywiki.com/Modding:Player_Guide/Getting_Started (read 2026-09-11), the
+      mod-sites table: \"Nexus Mods — Most mods are released here. An account is required, but it's
+      free\""
+    tags:
+      - distribution
+      - nexus
+      - standing-rule
+      - provenance
+    detail: The practical consequence is that a Stardew surface cannot resolve a Nexus update key to a
+      page or a version by itself, and should not try. SMAPI's own web API does that; ModWright's
+      job stops at validating the key's shape.
+  - id: stardewvalley.distribution.channels.the-five-sites
+    claim: "SMAPI recognises five mod sites in update keys: Nexus Mods, CurseForge, ModDrop, GitHub and
+      Chucklefish (deprecated). The machine-readable statement of that set is the `UpdateKeys`
+      pattern in the published manifest schema."
+    status: community
+    source: 'https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Update_checks (read 2026-09-11),
+      "Valid sites"; the pattern
+      `^(?i)(Chucklefish:\d+|Nexus:\d+|GitHub:[A-Za-z0-9_\-\.]+/[A-Za-z0-9_\-]+|ModDrop:\d+|CurseForge:\d+)(?:
+      *@ *[a-zA-Z0-9_]+ *)?$` from https://smapi.io/schemas/manifest.json'
+    tags:
+      - distribution
+      - updatekeys
+      - sites
+      - validator
+    detail: "Each site has its own version-detection rule: CurseForge reads the latest file's display
+      name (\"a semantic version at the end, with a space before the version\"), GitHub reads the
+      release tag, ModDrop reads files under \"Main Versions\", Nexus takes the highest of the mod,
+      main files and optional files. GitHub explicitly does not support monorepos."
+  - id: stardewvalley.distribution.channels.moddrop-is-discouraged
+    claim: 'The wiki actively discourages ModDrop for players: "ModDrop used to be a source for Stardew
+      mods but is currently not recommended due to lack of supervision on the part of the site
+      owners. Mod developers are encouraged to monitor it for stolen mods, but players should avoid
+      it."'
+    status: community
+    source: https://stardewvalleywiki.com/Modding:Player_Guide/Getting_Started (read 2026-09-11), the
+      mod-sites table
+    tags:
+      - distribution
+      - moddrop
+      - warning
+      - guidance
+    detail: "Worth carrying into `guidance` because it is a statement about mod *provenance*, not just
+      convenience: a mod obtained from ModDrop may be someone else's work reuploaded. SMAPI still
+      supports `ModDrop:` update keys, so the two facts coexist."
+  - id: stardewvalley.distribution.channels.no-workshop-no-in-game-browser
+    claim: 'There is no Steam Workshop and no in-game mod browser. Mods are installed by unzipping into
+      `Mods/`: "To install a mod, just unzip it into the Mods folder in your game folder. Make sure
+      each mod has its own subfolder, without trailing numbers."'
+    status: community
+    source: https://stardewvalleywiki.com/Modding:Player_Guide/Getting_Started (read 2026-09-11)
+    tags:
+      - distribution
+      - install
+      - workshop
+      - manual
+    detail: The guide's own advice to "Download mods into a folder other than Mods, unzip them there,
+      and then move their folder(s) into Mods" exists because of the wrapper-folder failure
+      (`PineapplesEverywhere-1234567890`), which is one of the most common installation errors.
+  - id: stardewvalley.distribution.channels.compatibility-list-repo
+    claim: The public mod compatibility list at smapi.io/mods is generated from the
+      `Pathoschild/SmapiCompatibilityList` repository's `data/mods.jsonc` and
+      `data/broken-content-packs.jsonc`, validated against `data/schema.json`, and republished
+      within ten minutes of a merge.
+    status: community
+    source: 'https://github.com/Pathoschild/SmapiCompatibilityList/blob/develop/docs/README.md (read
+      2026-09-11): "This repository has the compatibility metadata for every Stardew Valley C# mod
+      for SMAPI. The mod compatibility list is automatically generated from this data." and "The
+      public mod compatibility list will be updated automatically within 10 minutes once the
+      proposed change is merged."'
+    tags:
+      - compat
+      - compatibility-list
+      - data
+      - machine-readable
+    detail: "`data/mods.jsonc` is about 940 KB. The repository's default branch is `develop` and it was
+      last pushed 2026-06-04. This is a machine-readable compat corpus ModWright can read directly
+      rather than scraping a web page."
+  - id: stardewvalley.distribution.channels.compatibility-statuses
+    claim: A mod's compatibility status is one of `ok`, `optional`, `unofficial`, `workaround`,
+      `broken`, `abandoned`, `obsolete`, `unknown`. If not specified it defaults to `unofficial`
+      when an `unofficialUpdate` is given, else `broken` when `brokeIn` is specified, else `ok`.
+    status: community
+    source: 'https://github.com/Pathoschild/SmapiCompatibilityList/blob/develop/data/schema.json (read
+      2026-09-11), `definitions.Mod.properties.status`, whose description enumerates each value —
+      e.g. "optional: mod is compatible if you use a secondary download on the mod page", "obsolete:
+      mod is no longer needed and should be removed"'
+    tags:
+      - compat
+      - statuses
+      - vocabulary
+      - enum
+    detail: "The `abandoned` status requires an `abandonedReason` of `author`, `hidden` or `deleted`.
+      The repository's contribution guidelines are strict about it: \"A mod is not considered
+      abandoned just because it hasn't been updated for a while\", and \"Only mark a mod 'broken' if
+      it's incompatible. This isn't the place to track general mod bugs.\""
+  - id: stardewvalley.distribution.channels.compatibility-record-fields
+    claim: Each compatibility record has required fields `name`, `author`, `id`, `nexus`, plus optional
+      `github`, `chucklefish`, `curse`, `moddrop`, `url`, `source`, `status`, `summary`, `warnings`,
+      `brokeIn`, `unofficialUpdate`, `contentPackFor`, `overrideModData`, `retestWhenCompatible` and
+      `developerNotes`.
+    status: community
+    source: https://github.com/Pathoschild/SmapiCompatibilityList/blob/develop/data/schema.json (read
+      2026-09-11), `definitions.Mod`
+    tags:
+      - compat
+      - schema
+      - fields
+      - data
+    detail: "`brokeIn` is described as \"The SMAPI, Stardew Valley, or other release which broke this
+      mod if applicable. This should include both the name and version, like 'Stardew Valley
+      1.6.9'.\" — a parseable field that makes \"which game version broke this\" answerable across
+      the whole corpus. `id` may carry alternate or former IDs comma-separated, newest first."
+  - id: stardewvalley.distribution.channels.unofficial-update-version-convention
+    claim: An unofficial update's version must be the official version incremented by 0.0.1 with
+      `-unofficial.N-yourName` appended — so an official `1.2.3` becomes
+      `1.2.4-unofficial.1-yourName`. This keeps official update alerts working.
+    status: community
+    source: "https://github.com/Pathoschild/SmapiCompatibilityList/blob/develop/docs/README.md (read
+      2026-09-11): \"An unofficial version _must_ match the official mod's version, incremented by
+      0.0.1, with -unofficial.1-yourName appended ... This avoids breaking update alerts for the
+      official mod versions.\""
+    tags:
+      - compat
+      - versioning
+      - unofficial
+      - validator
+      - pattern
+    detail: "Directly checkable: a mod whose version contains `-unofficial.` should match that shape.
+      Also relevant to update checks, since a player on a prerelease version is put on the beta
+      channel and will see any newer version."
+  - id: stardewvalley.distribution.channels.internal-metadata-json
+    claim: SMAPI ships its own mod database as `smapi-internal/metadata.json`, maintained in the
+      repository as `src/SMAPI.Web/wwwroot/SMAPI.metadata.json`. It overrides compatibility per mod
+      with a `Status` of `Obsolete`, `AssumeBroken` or `AssumeCompatible`, plus a
+      `StatusReasonPhrase` shown to the player and a `StatusReasonDetails` logged at TRACE.
+    status: inferred
+    source: https://github.com/Pathoschild/SMAPI/blob/develop/src/SMAPI.Web/wwwroot/SMAPI.metadata.json,
+      its own header documentation; read by src/SMAPI/Framework/ModLoading/ModResolver.cs
+      `ValidateManifests(...)` via `mod.DataRecord.Status`
+    tags:
+      - compat
+      - metadata
+      - on-disk
+      - curated
+      - no-network
+    detail: 'Roughly 45 KB with about 172 `AssumeBroken` entries as of 2026-09-11. It is on disk in
+      every SMAPI install, which makes it the cheapest high-value compat input available: it turns
+      "this mod was skipped" into "this mod is curated as broken up to version X because <phrase>"
+      with no network call. Its keys are version-ranged field overrides of the form `~1.1 | Default
+      | Name`, where the version format is `min~max` with either side optionally blank.'
+  - id: stardewvalley.distribution.channels.compatibility-list-is-being-deprecated
+    claim: SMAPI's unreleased release notes deprecate the mod compatibility list and introduce a
+      replacement, the "open mod dataset" at `Pathoschild/StardewModDataset` — "Open data about
+      every Stardew Valley mod uploaded to CurseForge, ModDrop, and Nexus Mods".
+    status: community
+    source: 'https://github.com/Pathoschild/SMAPI/blob/develop/docs/release-notes.md (read 2026-09-11),
+      "Upcoming release / For the web UI: Deprecated the mod compatibility list" and "For tool
+      maintainers: Added the open mod dataset"; repository description and tree from the GitHub API
+      for Pathoschild/StardewModDataset, last pushed 2026-08-30'
+    tags:
+      - compat
+      - deprecation
+      - unresolved
+      - dataset
+      - migration
+    detail: This is in an *unreleased* section, so as of SMAPI 4.5.2 the compatibility list is still
+      live. The release note's own two links also disagree with each other — the "mod compatibility
+      list" text links to smapi.io/stats (the new stats page) rather than smapi.io/mods. A surface
+      should not hard-code either source until this settles. The new dataset is laid out as
+      `dataset/data/<site>/<bucket>/<id>.json`.
+  - id: stardewvalley.distribution.channels.smapi-web-services
+    claim: "SMAPI runs three relevant web services: the log parser at smapi.io/log, the JSON validator
+      at smapi.io/json, and the update-check API at `https://smapi.io/api/` (the `WebApiBaseUrl`
+      setting). The published schemas are at smapi.io/schemas/{manifest,i18n,content-patcher}.json."
+    status: community
+    source: https://github.com/Pathoschild/SMAPI/blob/develop/docs/technical/web.md (read 2026-09-11),
+      which documents the log parser, the JSON validator and the schema URLs; `WebApiBaseUrl` and
+      `BlacklistUrl` from src/SMAPI/SMAPI.config.json
+    tags:
+      - smapi-io
+      - tooling
+      - api
+      - schema
+      - overlap
+    detail: ModWright should read the schemas (they are static files) and should not call the update API
+      without first reading its endpoints, rate limits and terms — none of which were established
+      here. The log parser and JSON validator are human-facing products over the same rules
+      ModWright would implement offline; duplicating their regexes is right, duplicating their UI is
+      not.
+  - id: stardewvalley.distribution.channels.malicious-mod-blacklist
+    claim: 'SMAPI ships and updates a malicious-mod blacklist: `smapi-internal/blacklist.json` shipped,
+      `blacklist-updated.json` fetched from `https://smapi.io/SMAPI.blacklist.json`, controlled by
+      the `CheckForBlacklistUpdates` setting. A blacklisted mod is refused with a Critical
+      "Malicious mod detected." line and SMAPI exits.'
+    status: inferred
+    source: SMAPI develop, src/SMAPI/Constants.cs (`ApiBlacklistPath`, `ApiBlacklistFetchedPath`),
+      src/SMAPI/SMAPI.config.json (`BlacklistUrl`), and src/SMAPI/Framework/Logging/LogManager.cs
+      `LogModInfo(...)` (`this.Monitor.LogFatal("Malicious mod detected.")` followed by
+      `this.PressAnyKeyToExit()`)
+    tags:
+      - security
+      - blacklist
+      - log
+      - signature
+      - distribution
+    detail: 'Added in SMAPI 4.5.0 along with detection of "known malicious loose files in the Mods
+      folder". Disabling the updates is itself logged as a Warn: "You disabled mod blacklist
+      updates, so you may not be protected from known malicious mods." Both the Critical line and
+      that Warn deserve log signatures.'
+  - id: stardewvalley.distribution.channels.mod-managers
+    claim: Vortex manages Stardew mods — SMAPI's own scanner knows its marker file
+      `__folder_managed_by_vortex` and reports an empty one as "it's an empty Vortex folder (is the
+      mod disabled in Vortex?)." — but unlike r2modman on Valheim it does not relocate the loader or
+      maintain a separate profile tree.
+    status: inferred
+    source: SMAPI develop, src/SMAPI.Toolkit/Framework/ModScanning/ModScanner.cs, the
+      `VortexMarkerFileName` field and `IsEmptyVortexFolder(...)`
+    tags:
+      - distribution
+      - vortex
+      - mod-manager
+      - scanning
+      - deploy
+    detail: So a ModWright deploy into `Mods/` coexists with Vortex rather than competing with it, and
+      the only Stardew "profile" mechanism is SMAPI's own `--mods-path` argument. ModWright should
+      read a Vortex-managed folder and never write Vortex's metadata.