# 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.

## 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` and fails if Gitea does not report the exact release commit.

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