# Updating ForgeFlow on Windows

ForgeFlow stores credentials, repository mappings, preferences, deployment profiles, diagnostics and operation history outside the source directory.

## Built-in source update

Open **Settings → ForgeFlow updates** and choose:

1. **Check now**
2. **Download update**
3. **Apply & restart**

The default update source is the configured Gitea instance, repository `Jens/ForgeFlow`, branch `main`.

The updater pins the download to the exact remote commit, checks the archive SHA-256, starts an external PowerShell helper and waits for a structured `started` marker. ForgeFlow closes only after that marker exists. The helper then:

1. waits for the old process to exit;
2. backs up the current source;
3. extracts and validates the requested semantic version;
4. mirrors the incoming source;
5. runs `npm ci --no-audit --no-fund` when the published release contains `package-lock.json`, otherwise a pinned direct-dependency `npm install`;
6. runs `npm run check`;
7. writes the successful installation result before restart;
8. launches the installed Electron executable directly;
9. persists `success`, `failed` or `rolled-back` state for the next launch.

A failed validation restores the previous source. A successful installation is not rolled back merely because automatic restart fails; start ForgeFlow manually and the persisted result is shown.

Update logs and status files are stored beneath ForgeFlow's local user-data `updates` folder and exclude the Gitea token.

## Packaged Windows updates

ForgeFlow 0.9.1 and newer use authenticated Gitea release assets when running from the installer or portable executable. The updater selects the installer or portable artifact that matches the current installation mode, requires its `.sha256` sidecar, validates the Windows executable header and SHA-256 digest, then verifies the digest again immediately before applying it. An external PowerShell helper waits for ForgeFlow to exit, installs or replaces the executable and restarts it.

`Publish-ForgeFlow-Release.ps1` now treats source and binaries as one release transaction. By default it pushes the validated source, builds the exact published commit and uploads all four required assets:

- `ForgeFlow-Setup-<version>-win-x64.exe`
- `ForgeFlow-Setup-<version>-win-x64.exe.sha256`
- `ForgeFlow-Portable-<version>-win-x64.exe`
- `ForgeFlow-Portable-<version>-win-x64.exe.sha256`

Use `-SkipBinaryRelease` only when intentionally publishing source without enabling packaged auto-update.

When the source was already pushed without a binary release, run the recovery publisher from Windows:

```powershell
Set-ExecutionPolicy -Scope Process Bypass
.\Publish-Missing-Binary-Release.ps1 -ExpectedVersion 0.9.1
```

The recovery script clones the current Gitea branch into a temporary directory, verifies the exact branch commit, runs the complete quality gate, builds both Windows artifacts and creates or repairs the matching Gitea release. It uses the encrypted Gitea token already stored by ForgeFlow.

Every platform build finishes by removing ForgeFlow artifacts for older versions from `dist`. The unpacked application directory and builder diagnostics are kept.

The binary publisher refuses to upload when local `HEAD` differs from the configured Gitea branch. ForgeFlow 0.8.9 and 0.9.0 queried Gitea attachment metadata as though it were the executable. Those versions require one manual 0.9.1 installer run. From 0.9.1 onward, the updater follows the release asset browser download URL and in-app updates work normally.

## Publishing a release from Downloads

Extract the complete source ZIP so this file exists:

```text
C:\Users\Jens\Downloads\ForgeFlow-<version>\ForgeFlow\package.json
```

Run:

```powershell
cd C:\Users\Jens\Downloads\ForgeFlow-<version>\ForgeFlow
Set-ExecutionPolicy -Scope Process Bypass
.\Publish-ForgeFlow-Release.ps1
```

The script installs dependencies, runs the complete quality gate, clones `git@gitea.itworx.tech:Jens/ForgeFlow.git` into a temporary folder, mirrors the validated source without `.git`, `node_modules`, `dist` or release archives, commits it and pushes `main`. It then compares local `HEAD` with `git ls-remote`, builds the exact published checkout and uploads the installer, portable executable and both checksums to the matching Gitea release. Publication fails when either the source commit or any required binary asset cannot be verified.

Keep the currently installed older ForgeFlow source folder untouched until the built-in updater test is complete.