Fallout-build · ChrisonSimtian · May 27, 2026 · May 27, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,26 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ### Breaking changes
 
+- **AES-GCM v2 secret format for `EncryptionUtility` — `parameters.json` encrypted values** (#214, closes #212). The secret-encryption scheme used by `fallout :secrets` is now AES-GCM with per-secret random salt + nonce and 600,000 PBKDF2-SHA256 iterations (OWASP 2023). Previous `v1:` (AES-CBC, static salt, 10,000 iterations, unauthenticated) values **continue to decrypt** — the `Decrypt` path dispatches on `v1:`/`v2:`/unprefixed-legacy. New `Encrypt` calls always emit `v2:`.
+  - **On-disk format**: `v2:base64(salt[16] || nonce[12] || tag[16] || ciphertext)`. `v1:` was `v1:base64(salt-as-iv || ciphertext)` with a static `"Ivan Medvedev"` salt.
+  - **Migration path**: existing `.fallout/parameters.json` files with `v1:` values stay readable. Re-running `fallout :secrets` to add or update **any** secret naturally re-encrypts that entry under `v2:` (existing `SaveSecrets` flow already calls `Encrypt` per value). A whole-file rekey command can be added if there's demand.
+  - **Mixed-version repos**: developers on Fallout < 11.0 pulling a `parameters.json` that contains `v2:` values from a teammate on 11.0+ get `Could not decrypt 'X' with provided password`. Upgrade direction is fine (`v1:` reads keep working); downgrade is not.
+  - **`Rfc2898DeriveBytes` constructor obsoletion (`SYSLIB0060`)** cleared — both legacy and current paths now use the static `Rfc2898DeriveBytes.Pbkdf2(...)`. No public-API impact; just stops the warning.
+
+- **`Fallout.GlobalTool` package renamed to `Fallout.Cli`** (#206). The dotnet-tool install command is now `dotnet tool install -g Fallout.Cli`. The CLI **command name stays `fallout`** — no script or invocation changes needed.
+  - **NuGet package ID changes**: `Fallout.GlobalTool` (frozen at 10.3.40, then unlisted) → `Fallout.Cli` (10.3.41 onward, then 11.0.x).
+  - **Project / assembly / namespace rename**: `src/Fallout.GlobalTool/` → `src/Fallout.Cli/`, `tests/Fallout.GlobalTool.Tests/` → `tests/Fallout.Cli.Tests/`, `namespace Fallout.GlobalTool[.*]` → `namespace Fallout.Cli[.*]` across 48 files. Internal types only — no public-API consumer breakage from the namespace rename itself.
+  - **Migration for consumers**: see [`docs/migration/from-globaltool-to-cli.md`](docs/migration/from-globaltool-to-cli.md). Short form: `dotnet tool uninstall -g Fallout.GlobalTool && dotnet tool install -g Fallout.Cli`, and in repos with a local manifest, edit `.config/dotnet-tools.json` to replace `fallout.globaltool` with `fallout.cli`.
+  - **Update-notification text** in `UpdateNotificationAttribute` already points at the new name, so existing `Fallout.GlobalTool` installs will prompt users toward `Fallout.Cli` on next run.
+
+- **Thin bootstrappers + `.config/dotnet-tools.json` manifest; `build.cmd` dropped** (#204, PR-B of #203). The per-repo `build.cmd`/`build.sh`/`build.ps1` shape changes substantially — and the `[GitHubActions]` generator now emits a different workflow shape downstream consumers will see on the next regen.
+  - **`build.cmd` is gone** from the canonical scaffold. `fallout :setup` no longer emits it. New repos get only `build.sh` + `build.ps1`.
+  - **`build.sh` / `build.ps1` are ~60-line thin shims**: provision dotnet (kept verbatim from the pre-existing block), `dotnet tool restore`, `exec dotnet fallout "$@"`. The `BUILD_PROJECT_FILE` / `BUILD_DIRECTORY` config + explicit `dotnet build` + `dotnet run --project` lines are gone — `Fallout.Cli`'s in-tool runner (added in #201) does that work now.
+  - **`.config/dotnet-tools.json`** is the new home of the pin. `fallout :setup` writes one with the tool pinned at the running CLI's own version. Skipped if one already exists (consumer may have other local tools pinned).
+  - **`[GitHubActions]` generator** (`Fallout.Common/CI/GitHubActions/Configuration/GitHubActionsRunStep.cs`): the single `run: ./{BuildCmdPath} {targets}` step is replaced with three steps — `actions/setup-dotnet@v4` (reads `global.json`), `dotnet tool restore`, `dotnet fallout {targets}`. Downstream consumers using `[GitHubActions(InvokedTargets = ...)]` see the new shape on next workflow regen.
+  - **`BuildCmdPath` property** on `GitHubActionsAttribute` is no longer consumed (the run-step no longer references it). The Azure Pipelines / AppVeyor / TeamCity / SpaceAutomation generators still fall back to a literal `"build.cmd"` if `BuildCmdPath` is unset — keeps those legacy providers functional for the demand-driven revival (#8) without forcing this repo to keep a `build.cmd`.
+  - **Migration**: existing repos can keep their fat bootstrappers and they'll work indefinitely (the bootstrapper does its own `dotnet build` + `dotnet run --project`, doesn't depend on the global tool). To adopt the new shape, re-run `fallout :setup --force` (or hand-edit the shims to match the new template).
+
 - **Last-mile Newtonsoft removal — closes the #83 migration tree** (#119 STJ-6, #115 STJ-2 tail). Every Fallout source file is STJ-native; `Newtonsoft.Json.dll` survives in the closure only as a transitive of `NuGet.Packaging` and `Serilog.Formatting.Compact.Reader`. The `Newtonsoft.Json` `PackageVersion` is gone from `Directory.Packages.props` entirely.
   - **`GitHubActions.GitHubEvent` is now `JsonObject`** (was Newtonsoft `JObject`). Consumers that introspect the event payload need to swap `using Newtonsoft.Json.Linq` → `using System.Text.Json.Nodes` and update accessors (`["key"].Value<T>()` → `["key"].GetValue<T>()`, `Property(name)` → indexer, etc.).
   - **`Fallout.Utilities.Net` `HttpRequestExtensions.WithJsonContent` / `HttpResponseExtensions.GetBodyAsJson` defaults are STJ.** The `[Obsolete]`-marked Newtonsoft overloads (`JsonSerializerSettings` parameter, `JObject` return) are gone. `JsonSerializerOptions` overloads remain for explicit configuration; the parameterless default uses STJ with default options. `GetBodyAsJsonObject` returns `System.Text.Json.Nodes.JsonObject`.

diff --git a/docs/migration/from-globaltool-to-cli.md b/docs/migration/from-globaltool-to-cli.md
@@ -0,0 +1,96 @@
+---
+title: Fallout.GlobalTool → Fallout.Cli
+description: Migrating from the renamed Fallout CLI NuGet package. Short guide — the command name didn't change, just the package ID.
+---
+
+In v11, the dotnet-tool NuGet package id was renamed: **`Fallout.GlobalTool` → `Fallout.Cli`**. The **command name stays `fallout`**, so build scripts and shell invocations don't change. The only thing that moves is the install/restore reference.
+
+> If you've never installed `Fallout.GlobalTool`, you don't need this page — install `Fallout.Cli` directly per the [Install section in the README](https://github.com/ChrisonSimtian/Fallout#install).
+
+## TL;DR
+
+**Global install:**
+
+```sh
+dotnet tool uninstall -g Fallout.GlobalTool
+dotnet tool install -g Fallout.Cli
+```
+
+**Local manifest (`.config/dotnet-tools.json`):** open the file, replace the `fallout.globaltool` entry with `fallout.cli`, restore.
+
+```diff
+ {
+   "version": 1,
+   "isRoot": true,
+   "tools": {
+-    "fallout.globaltool": {
++    "fallout.cli": {
+       "version": "11.0.0",
+       "commands": [ "fallout" ]
+     }
+   }
+ }
+```
+
+```sh
+dotnet tool restore
+```
+
+That's it. `fallout :setup`, `fallout Compile`, etc. all work unchanged because the command name (`fallout`) is the same.
+
+## Why the rename
+
+`dotnet tool install Fallout.Cli` is easier to type and remember than `dotnet tool install Fallout.GlobalTool`. The "GlobalTool" suffix was a NUKE-era artefact distinguishing the dotnet-tool wrapper from the framework libraries — but every consumer's first encounter with the tool is at install-time, and `Fallout.Cli` is what they reach for naturally.
+
+The change is purely cosmetic at the NuGet metadata layer. No source-level API changed; the C# namespace inside the tool moved from `Fallout.GlobalTool.*` to `Fallout.Cli.*` but those types are `internal` so external consumers never referenced them.
+
+## Affected versions
+
+| Package | Last published | Status |
+|---|---|---|
+| `Fallout.GlobalTool` | `10.3.40` | Frozen on nuget.org. **Unlisted** as part of the v11 semver cleanup (see [#220](https://github.com/ChrisonSimtian/Fallout/pull/220)). Existing installs keep working; `dotnet tool update` won't find newer versions. |
+| `Fallout.Cli` | `11.0.x` (current) | Active. Receives all future tool releases. |
+
+The `10.3.41` through `10.3.47` patch releases of `Fallout.Cli` are **also unlisted** — they shipped under a patch number that hid breaking changes, fixed by the v11 major bump. Pin to **`11.0.0`** or later.
+
+## Migration scenarios
+
+### You installed `Fallout.GlobalTool` globally on your machine
+
+```sh
+dotnet tool uninstall -g Fallout.GlobalTool
+dotnet tool install -g Fallout.Cli
+```
+
+`dotnet tool list -g` confirms only `Fallout.Cli` remains. The `fallout` command on your PATH now resolves to the renamed package.
+
+### Your repo has a local `.config/dotnet-tools.json` manifest
+
+Edit the manifest, replace `fallout.globaltool` with `fallout.cli` (both the key and any references). Bump the version pin to the current `Fallout.Cli` release (`11.0.x` and above).
+
+```sh
+dotnet tool restore
+```
+
+Confirm with `dotnet tool list` — the `fallout.cli` row should appear, the `fallout.globaltool` row should not.
+
+### Your repo uses the thin `build.sh` / `build.ps1` shims
+
+Nothing to do. The shims call `dotnet fallout "$@"` — they look up the command by name, not by package ID, and `dotnet tool restore` resolves whatever your manifest pins.
+
+If your repo is still on the **old fat bootstrappers** (with the `BUILD_PROJECT_FILE` config block + explicit `dotnet build` + `dotnet run --project`), those don't depend on the global tool at all and keep working unchanged. To adopt the new shape, re-run `fallout :setup --force` after upgrading. See [the v11 CHANGELOG entry for #204](https://github.com/ChrisonSimtian/Fallout/blob/main/CHANGELOG.md) for what the new shape looks like.
+
+### Your repo's CI calls `dotnet fallout` directly (no shim)
+
+Update the workflow's `dotnet tool restore` step's manifest to reference `fallout.cli`. The actual `dotnet fallout <target>` lines stay identical.
+
+## Stuck on 10.3.40 of `Fallout.GlobalTool`?
+
+The package is unlisted but still downloadable if you have an explicit pin in your manifest. You can keep running on `10.3.40` indefinitely. When you're ready to upgrade, follow the steps above — there is no required intermediate step. `Fallout.GlobalTool 10.3.40` and `Fallout.Cli 11.0.0` are the same code-base; the only consequential difference is the package ID and the semver-correct breaking changes that have accumulated.
+
+## Refs
+
+- [#206](https://github.com/ChrisonSimtian/Fallout/pull/206) — the rename PR.
+- [#210](https://github.com/ChrisonSimtian/Fallout/pull/210) — README install section + the prompt to uninstall old CLI.
+- [#220](https://github.com/ChrisonSimtian/Fallout/pull/220) — the v11 semver-policy bump that catalysed unlisting the 10.3.41-47 range.
+- [`from-nuke.md`](from-nuke.md) — if you're also migrating from NUKE, do that first; this guide is downstream of it.