Skyrim Forge 5.2.1

This is the last standalone Skyrim Forge release. Development continues inside the
Ultimate AI Starter Bundle,
at BUNDLED-TOOLS/skyrim-forge. Forge 6.0.0 and later ship from there.

The bundle installs Forge, and the two lived in separate repositories — which
is how bundle 7.8.0 shipped an installer that read a field Forge has never
emitted and aborted every install, with all gates green on both sides. Two
files that must agree do not belong in two repositories.

5.2.1 keeps working and stays downloadable. Upgrading is a normal install:
the bundle migrates a Skyrim-Forge-5.2.1 folder onto the versionless
Skyrim-Forge name and preserves Workspaces, .venv, REPORTS and a local
config.toml. 6.0.0 removes forge bundle-contract, which existed only to
negotiate across the split this notice is about.

Two releases in one: 5.2.0 was built but never published, so this tag carries both.

5.2.0 — bundle handshake

forge bundle-contract --bundle-version X.Y.Z proves whether this build and an Ultimate AI Starter Bundle can safely cooperate. It returns capabilities as JSON and exits non-zero on an incompatible range (>=7.8.0,<8.0.0). Bundle 7.9.0 installs, self-tests, registers and contract-checks Forge unattended.

5.2.1 — the version gate only checked the files it remembered

forge --help, the GUI window title and the Go native self-test fixture all announced the 4.2 series from inside a 5.2.0 install.

Forge already had a version gate. It compared eight enumerated sources — version.py, pyproject.toml, CURRENT.txt, VERSION.txt, START-HERE.bat, README.md, the Go constant, the skill series — and they all agreed. None of the three offenders was on the list, and enumeration cannot find what it does not enumerate.

The gate now also sweeps every shipped .py, .ps1, .bat and .go file for a product-name literal carrying a major.minor, and fails on any that is not the current series. Proved by reintroducing the literal:

stale product-version literal in shipped source: skyrim_forge/cli.py:15 says 4.2, series is 5.2

Also:

• tests/test_bundle_contract_v520.py hardcoded "5.2.0", so every patch release was a test edit. It pins the 5.2 series — the thing the contract range actually promises.
• The README now documents the install directory as Skyrim-Forge, without a version suffix. Every AI provider stores the MCP command as a hard absolute path, so a Skyrim-Forge-5.2.1 folder disconnects all of them the next time you upgrade — silently, because a provider that cannot spawn its server just shows no tools. The installed version is in VERSION.txt.

Verification

scripts/validate_repository.py   PASS, idempotent across three runs
tests                            162 tests, 0 failures
native helpers                   rebuilt reproducibly under pinned Go 1.23.2
release archive                  identical SHA-256 across two builds
GitHub CI                        12/12 checks green on 23d8689

Live MCP proof against the installed build, including a tools/call with no _meta: resultType: complete on every response.

Install

Extract as Skyrim-Forge — no version in the folder name — next to your other Skyrim tools, then run START-HERE.bat.

If you use the Ultimate AI Starter Bundle, do nothing: 7.9.0 ships this build and installs it for you.

Skyrim Forge 5.1.7

MCP desktop-app support; manifest now CI-stable (git-normalized hashing); removed stray dist2 build artifacts

v5.1.6

Full Changelog: v5.1.5...v5.1.6

v5.1.5

Full Changelog: v5.1.4...v5.1.5

Skyrim Forge 5.1.4 — UTF-8 config reads, space-tolerant Hermes test, reproducible natives

Encoding correctness, a test that only passed on space-free paths, and a
release profile that no longer reproduced.

• Provider configs are read as UTF-8, not the ANSI codepage. On Windows
  PowerShell 5.1, Get-Content -Raw without an explicit -Encoding decodes
  using the ANSI codepage (Windows-1252), not UTF-8. Register-MCP.ps1 read the
  user's Kimi mcp.json that way and wrote the parsed object straight back, so
  every non-ASCII character in that file would have been replaced by mojibake.
  Measured on an mcp.json carrying one em dash: Get-Content -Raw turned 1 em
  dash into 0 and produced 1 mojibake sequence; ReadAllText preserved it.
  Four call sites moved to [IO.File]::ReadAllText across Register-MCP.ps1,
  Install-Forge-Skill.ps1 and workers/SkyrimForge.UIWorker.ps1. The UI
  worker's path is caller-supplied and may be relative, so it is resolved with
  Convert-Path first: .NET resolves relative paths against the process working
  directory, not PowerShell's current location.

• The Hermes registration test asserted an unquoted command line. PowerShell
  quotes any argument containing a space, so an install under a path such as
  S:\Apps\Skyrim Tools\... logs --command "S:\Apps\...". That quoting is
  required -- without it hermes would receive --command S:\Apps\Skyrim and
  Tools\... as two separate arguments -- but the test compared against the bare
  form and therefore only passed when the install path contained no spaces. The
  registration code was correct; the assertion now strips quotes before
  comparing.

• The shipped native helpers no longer reproduced from source. Running
  scripts/validate_repository.py against a clean checkout of 5.1.3 reported
  both binaries as "not reproducible under the -buildvcs=false release profile":
  they had been built with a different Go toolchain than the one the profile
  now produces. Rebuilt deterministically, so a from-source rebuild matches the
  published bytes again. CHECKSUMS-SHA256.txt, MANIFEST.json, SBOM.spdx.json
  and BUILD-RECEIPT.json are regenerated to match.

Validation: scripts/validate_repository.py -> PASS, no errors (5.1.3
reported FAIL on the reproducibility check). python -m unittest discover -s tests -> 151 tests, OK. PowerShell parser gate -> PASS (9 scripts).

Skyrim Forge 5.1.3 - Release and Runtime Repair

Skyrim Forge 5.1.3 closes the final release and installation reliability gaps.

Fixed

• Release publication is idempotent. Tag workflows now create a missing release or refresh an existing release's assets instead of failing with "a release with the same tag name already exists".
• The installer no longer treats a present .venv\Scripts\python.exe as proof that the environment works. It executes the interpreter and safely rebuilds only the exact local .venv when its base Python is gone.
• Version and startup branding now resolve to 5.1.3, and deployment uses the exact Skyrim-Forge-5.1.3 folder.

Verified

• 151 Python regression tests
• Windows installer, deliberately broken-venv repair, reinstall, legacy migration, exact START-HERE path, and provider bridge tests
• Python 3.11, 3.13, and 3.14 on Windows and Linux
• Go 1.23.2 format, vet, tests, race detector, reproducible Windows/Linux native builds
• 52 MCP tools and dual-era protocol validation
• CI, CodeQL, and the Release workflow all green

Validated portable archive SHA-256:
a473561c69171d377fef9a609c247331ee9c05c62a3c58fd777aff0a23bc4c69

Full changelog: v5.1.2...v5.1.3

Skyrim Forge 5.1.2 — Hermes MCP registration hotfix

Hermes MCP registration hotfix

Supersedes v5.1.1 for Hermes users.

• Supplies Hermes' required confirmation to enable all discovered Forge tools.
• Rejects Hermes false-success responses by requiring actual connection/tool-discovery output.
• Keeps the 5.1.1 cross-provider MCP bridge, rollback, and provider-home fixes.

Validation

• 149 automated tests passed.
• Full repository, MCP, packaging, PowerShell, native Windows/Linux reproducibility, and ZIP manifest gates passed.
• GitHub CI and CodeQL passed before publication.
• The real Hermes client persisted the Forge entry and discovered all 52 tools.

Asset SHA-256: 2cb1b8b6c94f9a511d116cab777a63fd7511308f1f4705705e7b572980ed66f2

Skyrim Forge 5.1.1 — Cross-provider MCP bridge

AI bridge reliability release

• Fixed the advertised forge_papyrus_compile MCP tool so it reaches Forge.
• Added real Kimi and Hermes MCP registration, verification, and byte-exact rollback on failed replacement.
• Corrected Hermes skill discovery to %LOCALAPPDATA%\hermes.
• Preserved existing Grok configuration and existing Kimi/Hermes settings during failed registration attempts.

Validation

• 149 automated tests passed.
• Full repository, MCP, packaging, PowerShell, native Windows/Linux reproducibility, and ZIP manifest gates passed.
• GitHub CI and CodeQL passed before publication.

Asset SHA-256: 0f9f019cefb8de19ee98ee5bb7d0098cf4c313f1452d975f0de2981ad5020adb

Skyrim Forge 5.1.0 — linting, checked against 3,000 real mods

Skyrim Forge 5.1.0

Framework linting, checked against a real reference corpus for the first time.

Forge's SPID/KID/BOS/FLM/SkyPatcher profiles were written from documentation,
with no installed mods to check them against. Pointed at 1,195 framework
configs from a live 3,000-mod load order, the linter produced:

	before	after
errors	13,554	11
warnings	11,762	71
files with findings	194 (16%)	64 (5%)

The 11 remaining errors are genuine defects in third-party mods.

Every finding was triaged against the frameworks' own SKSE runtime logs, because
a distribution log outranks a static profile.

What was wrong

SkyPatcher clause values were split on commas. A value is routinely a
comma-separated form list:

filterByLLNPCs=Skyrim.esm|0x01E78D:removeFromLLs=A.esp|001DBD, A.esp|001DC8

Every form after the first was reported as unmodeled syntax — 11,730 warnings
from a single parsing error. Rules are validated per key=value clause now.

A single-value SPID skill filter was an error. The corpus installs 13,427 of
them across skill indices 12–16, and po3_SpellPerkItemDistributor.log records
zero parse failures for any of them. One was traced end to end: Abyss's
14(20) distributed as SPEL:FE059810.

Five rows were rejected at runtime, all using skill index 0, so the observation
is kept — as an advisory. Failing 13,427 working rows to catch 5 is the worse
error, and Forge cannot currently tell them apart. It says so rather than
pretending to know.

Advisories buried everything else. A repeated note is now collapsed to one
entry per file naming the count and first line.

Five SkyPatcher categories were missing — outfit, ingestible, misc,
ingredient, projectile. All installed, all working, none in the profile.

KID keys were matched case-sensitively. Shipping mods write keyword =, and
BoobiesArmorPouch [KYWD:FF001DA3] distributes from one.

A two-field KID line was rejected as an unsupported type label. Field 2 is a
name filter there; BoobiesArmorScarf [KYWD:FF001DA5] applied at runtime.

Byte-order marks invented findings. utf-8-sig strips one. Corpus files
carry three stacked at the top, and one mid-file where two sources were
concatenated. A surviving U+FEFF stopped a comment from being a comment and
turned a valid key into an unknown one.

Kept strict

Nothing above weakens a check that catches real breakage. The 11 surviving errors
are real, including a KID line wrapped across two lines that never distributes.

Two existing tests asserted the single-value-skill rejection. Runtime disproved
them, so they now assert the evidence instead. InstalledCorpusRegressionTests
is built from the real installed lines.

Note

The version gate added in 5.0.2 caught the AI skill still advertising the 5.0
series during this bump — which is exactly what it was written for.

Validation: full repository gate PASS at 5.1.0, 142 tests, all 10 CI jobs and
CodeQL green, native helpers rebuilt reproducibly with pinned Go 1.23.2.

Still tool-validated: Skyrim gameplay and third-party GUI results remain untested
runtime gates. The corpus evidence here is stronger than that — it is drawn from
installed mods and their own runtime logs — but it is one load order, not proof
of every framework version.

Skyrim Forge 5.0.2 — the skill said 4.2

Skyrim Forge 5.0.2

The installed AI skill advertised "Skyrim Forge 4.2" from inside a 5.0
installation.

That line is the skill's description — the only thing an agent reads when
deciding whether to load Forge at all — and the AI bridge had installed it that
way into every provider home it targets.

The version gate added in 5.0.0 did not catch it, because the skill states the
series (5.0) rather than the patch (5.0.2), so it was never compared. The
gate now checks major.minor against version.py, bringing the number of gated
restatements from seven to eight.

Found while deploying 5.0.1 to a real machine, which is the only place a
provider-home file can be observed.

Validation: full repository gate PASS at 5.0.2, 135 tests, all 10 CI jobs and
CodeQL green, native helpers rebuilt reproducibly with pinned Go 1.23.2.
Everything in 5.0.0 and 5.0.1 is unchanged and still gated.