ForgeFlow/START_HERE.md

Start here — ForgeFlow v0.4.2

You do not need to send anyone your Gitea token, SSH key or server password. All credentials are entered locally in ForgeFlow during setup. Diagnostic logging is designed to exclude them.

Already running v0.3.2?

Use the v0.4.2 update overlay and follow docs/UPDATING.md. Your Gitea token and ForgeFlow configuration are stored outside the source folder and are preserved.

Fast path on Windows

1. Extract the complete ForgeFlow ZIP to a normal local folder.
2. Open PowerShell in that folder.
3. Run:

Set-ExecutionPolicy -Scope Process Bypass
.\setup-windows.ps1

The script checks Node.js and Git, installs the desktop dependencies, runs the full source/test quality gate and opens ForgeFlow.

4. Follow the five-step setup wizard in the application.
5. Continue with docs/SETUP_GUIDE.md to connect one repository to a staging or production environment.

When something fails

Open Diagnostics in ForgeFlow and:

1. Run System preflight or the environment Deployment preflight.
2. Resolve any blocking checks shown in red.
3. Choose Create diagnostic ZIP.
4. Prefer Strict privacy when the bundle will be shared.
5. Inspect the ZIP before sharing it.

The bundle contains redacted application events, configuration structure, repository/deployment states, preflight output and a local safety-audit result. It intentionally excludes access tokens, encrypted token blobs and raw runner logs.

Detailed diagnostic behavior: docs/DIAGNOSTICS.md.

Unraid deployments

After the desktop app opens:

1. Open Settings → SSH / Unraid servers.
2. Add the Unraid host and /mnt/user/appdata.
3. Save it and run Test & trust.
4. Open a repository, go to Deployments, and choose SSH / Unraid.
5. Run Preflight before the first deployment.

See docs/SSH_UNRAID_DEPLOYMENT.md.