Publish curated ForgeFlow source from 2ed1787c0b52

docs/ACCEPTANCE.md

@@ -0,0 +1,34 @@
+# End-to-end acceptance
+
+ForgeFlow 0.8 includes a read-only acceptance harness for the real Local ->
+Gitea -> Server chain. It never deploys unless an execution flag is supplied.
+
+Set `FORGEFLOW_GITEA_URL`, `FORGEFLOW_GITEA_TOKEN`, `FORGEFLOW_REPOSITORY`
+(`owner/repository`), `FORGEFLOW_LOCAL_PATH`, `FORGEFLOW_BRANCH`,
+`FORGEFLOW_STATUS_URL` and `FORGEFLOW_HEALTH_URL` locally. Optional variables
+are `FORGEFLOW_WORKFLOW`, `FORGEFLOW_ROLLBACK_WORKFLOW` and
+`FORGEFLOW_ENVIRONMENT`. Never commit the token.
+
+```powershell
+npm run acceptance
+npm run acceptance -- --execute-deployment
+npm run acceptance -- --execute-rollback
+```
+
+The first command is read-only. The mutation flags require every read-only
+check to pass, dispatch a controlled exact-SHA workflow with a unique request
+ID, and wait for matching status plus a successful health endpoint.
+
+## Isolated production acceptance
+
+`npm run acceptance:isolated` provisions disposable bare Git remotes, working
+trees, server appdata folders, Compose definitions, deployment keys,
+configuration migrations and release manifests below the operating-system temp
+directory. It covers clean and portable installs, the 0.10.0 migration path,
+both authentication modes, exact-SHA server pull and Direct Copy, adoption,
+external updates, deploy-key lifecycle, host-key changes, unhealthy activation,
+rollback, network interruption, shutdown recovery, stale plans, corrupt config,
+release integrity and inventories of more than twenty workloads.
+
+Every fixture is removed after its test. The suite never discovers or mutates
+real project folders, configured servers, credentials, containers or releases.

docs/ARCHITECTURE.md

@@ -0,0 +1,221 @@
+# Architecture
+
+## Process model
+
+```text
++---------------- Electron renderer ----------------+
+| Desktop UI                                         |
+| No Node.js, filesystem, process or token access    |
++-------------------------+---------------------------+
+                          |
+                  frozen preload API
+                          |
++-------------------------v---------------------------+
+| Electron main process                              |
+|                                                     |
+| IPC validation + trusted sender checks             |
+| ConfigStore -------- schema 8 + protected Gitea/SSH secrets    |
+| GitService ----------- Git through execFile args   |
+| GiteaService --------- repositories + Actions API  |
+| RepositoryService ---- discovery + aggregation     |
+| RepositoryMonitor ---- local state awareness       |
+| PreflightService ----- system/deployment readiness |
+| DeploymentService ---- dispatch/poll/verify        |
+| DiagnosticsService --- JSONL/redaction/support ZIP |
++----------------+--------------------+---------------+
+                 |                    |
+             local Git            Gitea API
+                 |                    |
+           working trees      repositories/actions
+                                      |
+                                trusted runner
+                                      |
+                         fixed allowlisted entry point
+                                      |
+                         app + independent status JSON
+```
+
+## Trust boundaries
+
+### Renderer
+
+The renderer is untrusted input. It can request only methods exposed by
+`preload.cjs`. Node integration is disabled, context isolation and sandboxing
+are enabled, and IPC requests are accepted only from the packaged file origin.
+Renderer crashes and unhandled rejections are reported through a sanitized
+one-way diagnostic method.
+
+### Main process
+
+Paths, URLs, file selections, branch names, commit messages, diagnostic export
+modes and deployment requests are checked here. The renderer cannot supply a
+server command. UI eligibility is advisory; main-process services re-read the
+working tree and remote ancestry immediately before privileged actions.
+
+### Gitea
+
+Gitea supplies repository metadata and the Actions control plane. ForgeFlow
+handles run-list response variants, retries servers that reject optional query
+filters and can fall back to the older tasks listing. Requests log only method,
+API path, status and duration—not authorization headers or request bodies.
+
+### Runner and server
+
+The runner consumes only committed trusted workflows. The root-owned server
+entry point reads an exact repository/environment target from a root-owned,
+non-writable data file. It validates the full SHA again and uses a
+per-environment lock. The runner receives no free-form command from ForgeFlow.
+
+## Local state
+
+`forgeflow-config.json` lives below Electron's platform-specific user-data path
+and is written atomically. Schema version 8 contains:
+
+- Gitea connection metadata and an OS-encrypted token blob where available;
+- workspace roots and explicit repository mappings;
+- favorites and application preferences;
+- diagnostic retention and level preferences;
+- multiple deployment profiles and last server state;
+- up to 250 operation records.
+
+Renderer-visible public state never contains the plaintext or encrypted token.
+
+Structured diagnostic JSONL files live in a separate `diagnostics` directory.
+They have independent rotation and retention and never block normal app use when
+logging itself fails.
+
+## Repository aggregation
+
+1. Fetch accessible Gitea repositories.
+2. Scan bounded workspace roots for Git working trees.
+3. Normalize HTTPS and SCP-style SSH remotes.
+4. Match local `origin` identity to `owner/repository`.
+5. Apply explicit mappings where present.
+6. Read Git state with bounded concurrency.
+7. Attach favorites, deployment profiles and last server state.
+8. Derive attention and ready-to-deploy status.
+9. Feed linked paths to the repository monitor.
+
+## Repository clone lifecycle
+
+The first configured project root is the default. The renderer submits only the
+current Gitea repository identity and either `default` or `custom` location
+mode. The main process resolves the repository again, selects a configured root
+or a native-dialog result, calculates the repository-named child path and asks
+GitService to inspect it.
+
+```text
+repository identity
+        |
+current Gitea metadata
+        |
+project root + safe repository folder name
+        |
+missing / empty / matching checkout / conflict
+        |
+clone or reuse -> save mapping -> refresh -> monitor
+```
+
+A matching existing checkout is reused. Different repositories and arbitrary
+non-empty folders are rejected.
+
+## Git execution
+
+ForgeFlow invokes the installed Git executable through `execFile`; it never
+builds shell command strings. File arguments must remain repository-relative
+and cannot contain traversal segments.
+
+Core status command:
+
+```bash
+git status --porcelain=v2 --branch -z --untracked-files=all
+```
+
+Synchronization is intentionally limited to:
+
+```bash
+git pull --ff-only
+```
+
+Branch switching requires a clean working tree. Stash supports untracked files.
+Deployment and rollback verify the full SHA against `origin/<allowed-branch>`
+with `merge-base --is-ancestor`.
+
+## Preflight model
+
+### System preflight
+
+Checks Git, author identity, app storage, diagnostic storage, OS credential
+protection, configured workspace roots and—when credentials are present—Gitea
+connectivity and repository visibility.
+
+### Deployment preflight
+
+Checks repository link, Git working tree, allowed branch, clean state, upstream,
+ahead/behind state, exact remote SHA, local and remote workflow presence,
+Actions API access, server status endpoint and healthcheck.
+
+Only failed required checks block readiness. The deployment backend repeats
+safety-critical Git/SHA validation after the user continues.
+
+## Repository monitor
+
+The current monitor periodically fingerprints Git state. It establishes a
+baseline, reports later changes and pauses during mutating operations to avoid
+intermediate noise. It is dependency-free rather than a native filesystem
+watcher.
+
+## Deployment lifecycle
+
+```text
+requested -> queued -> running -> health/version verification -> terminal
+```
+
+A deployment operation stores the exact SHA, fixed profile, environment,
+workflow and a UUID request ID. Polling then:
+
+1. finds the matching Actions run by SHA, branch, workflow and dispatch time;
+2. normalizes run status;
+3. retrieves jobs and locally redacted runner output;
+4. maps jobs to ForgeFlow stages;
+5. reads the independent status endpoint and healthcheck after runner success;
+6. verifies live SHA equality;
+7. stores success, rolled-back, failed or cancelled.
+
+The request ID is sent to the workflow and server status document, making one
+operation correlatable without using a credential as an identifier.
+
+## Diagnostics pipeline
+
+```text
+event -> recursive sanitization -> ordered JSONL write
+                                      |
+                            support export requested
+                                      |
+               fresh state + preflight + redacted logs
+                                      |
+                strict/standard privacy transformation
+                                      |
+                  fail-closed local secret safety audit
+                                      |
+                         ZIP + SHA-256 result
+```
+
+Raw runner output is deliberately omitted from exported support bundles.
+
+## Status endpoint
+
+The recommended endpoint is a static JSON file served independently from the
+application. It reports live, previous and requested SHAs, request ID, health
+and last exit code. See `STATUS_ENDPOINT.md`.
+
+
+## v0.4 services
+
+- `UpdateService` reports `package.json` at an exact Gitea branch SHA, refuses
+  unsigned source replacement and applies only publisher-signed packaged updates.
+- `SshService` provides pinned-host SSH execution with encrypted password or
+  private-key passphrase storage.
+- `UnraidDeploymentService` inspects existing application folders and performs
+  exact-SHA Git and Docker Compose deployments without deleting untracked
+  runtime data.

docs/COVERAGE_POLICY.md

@@ -0,0 +1,18 @@
+# Coverage policy
+
+ForgeFlow treats coverage as release evidence, not as a target to game. `npm run coverage`
+enforces 75% statements, 75% lines, 75% functions and 65% branches globally.
+
+The July 2026 hardening pass raised the measured baseline from 69.74% statements/lines,
+68.82% functions and 55.38% branches to 81.48% statements/lines, 82.07% functions and
+65.59% branches. Node/V8 discovered additional branch counters when previously unexecuted
+functions became covered; the denominator grew from 2,537 to 3,473 while the new tests
+added hundreds of asserted decisions. No command builders, platform guards or error
+adapters were excluded to improve the result cosmetically.
+
+The 65% global gate is paired with scenario-level evidence for the critical
+boundaries: deploy-key rollback, deployment verification, Gitea authentication and
+redirects, SSH host identity and output limits, inventory reconciliation, stale plans,
+configuration recovery, release integrity and updater failure modes. New code must not
+reduce the global baseline. Future increases must come from additional asserted failure
+scenarios, not ignore comments or source exclusions.

docs/CURRENT_STATE.md

@@ -0,0 +1,54 @@
+# ForgeFlow current state
+
+## Baseline
+
+- Baseline version: **0.10.0**
+- Baseline commit: `56efd1a00c2e76251a0b2e7a7a424d94200ae33c`
+- Baseline branch: `main`
+- Desktop runtime: Electron 43 with Node.js 22+ required by the source project
+- Primary supported packaged updater: Windows installer and portable executable
+
+The baseline was recorded before the 1.0 professionalization programme. It is the comparison point for functional, deployment and renderer regressions.
+
+## Known baseline evidence
+
+- `npm run check`: 155 tests, 152 passed, 3 environment-dependent Bash checks skipped, 0 failed.
+- OS-backed secure storage, encrypted Gitea token, Gitea API, repository and Actions access were available.
+- Unraid exposed Docker, Compose, Git, tar and SHA-256 tooling.
+- The server inventory contained active repository workloads plus a large number of historical or unrelated definitions that require backend classification.
+- Windows release artifacts were checksum-protected but not Authenticode-signed.
+
+No secret values, passwords, private keys or tokens are stored in this document.
+
+## Operation classes
+
+| Class | Default | Examples |
+| --- | --- | --- |
+| Read-only inspection | Allowed without confirmation | repository refresh, server inventory, deploy-key probe, preflight, audit export |
+| Reconciliation | Preview required | adopt an exact workload, refresh a profile from server truth |
+| Configuration mutation | Explicit action and audit record | save profile, rotate deploy key, change server settings |
+| Deployment | Fresh preflight and confirmation | server pull, Direct Copy, Gitea Actions dispatch |
+| Destructive maintenance | Recovery evidence and explicit confirmation | unlink, prune, key revocation, rollback |
+
+Discovery and audit never belong to a mutating class. Ambiguous evidence cannot be promoted automatically.
+
+## Recovery model
+
+ForgeFlow writes its configuration atomically. Explicit server reconciliation additionally creates a private recovery snapshot before changing profiles or deployment state. Encrypted user-created `.ffbackup` files remain the portable restore mechanism; recovery snapshots are local operational safeguards and can contain OS-encrypted credential material.
+
+## Issue priorities
+
+- **P0:** active data loss, credential disclosure, arbitrary execution or uncontrolled production mutation.
+- **P1:** release-blocking incorrect deployment, unsafe implicit mutation, broken recovery or material security gap.
+- **P2:** important functional, accessibility, performance or maintainability defect with a safe workaround.
+- **P3:** polish, documentation or low-risk improvement.
+
+## 1.0 constraints
+
+- No force-push or implicit repository history rewrite.
+- No automatic deployment deletion.
+- No desktop Gitea token on a server.
+- Read-only repository-scoped deploy keys for server pull.
+- SSH host-key changes fail closed.
+- Live commit, remote commit and runtime health remain separate evidence.
+- Packaged updates fail closed on missing or mismatched release assets, SHA-256 evidence and the pinned Ed25519 publisher signature; paid Authenticode remains optional.

docs/DEPENDENCY_AUDIT.md

@@ -0,0 +1,46 @@
+# Dependency security audit
+
+Audit date: 2026-07-29
+
+## Outcome
+
+- Runtime/production dependency audit: **0 vulnerabilities** (`npm audit --omit=dev`).
+- Full development toolchain: **19 high advisories**, reduced from 23.
+- Critical advisories: **0**.
+
+Playwright was upgraded from 1.55.0 to 1.62.0, removing the browser-download
+certificate-verification advisory. `c8` was upgraded from 10.1.3 to 12.0.0,
+removing the vulnerable `test-exclude` chain. Compatible patched
+`brace-expansion` releases were installed where dependency ranges allowed it.
+
+## Remaining development-only chain
+
+All remaining records collapse to one advisory:
+`GHSA-mh99-v99m-4gvg`, an uncontrolled brace-expansion denial of service. npm
+reports it through nested `minimatch` versions in two independent toolchains:
+
+- ESLint 10.8.0 (`@eslint/config-array`, `@eslint/eslintrc`);
+- electron-builder 26.15.3 (`@electron/asar`, `@electron/universal`, `glob`,
+  `dir-compare`, `ejs`/`jake`, Windows packaging helpers).
+
+These packages are never loaded by the packaged ForgeFlow runtime. They run in
+developer or CI processes against repository and build configuration owned by
+the operator. A malicious repository could still attempt resource exhaustion
+during linting or packaging, so the finding is not classified as harmless.
+CI jobs must retain memory/time limits and untrusted pull requests must not run
+release signing or publishing jobs.
+
+## Decisions
+
+- `npm audit fix --force` is prohibited. npm proposes ESLint 4.0.0 and an older
+  electron-builder; both are breaking downgrades and the tested older builder
+  dependency graph increased the result to 30 high and 1 critical advisory.
+- No global `minimatch` override is used. Several affected consumers declare
+  older APIs, and forcing a new major could silently break packaging or lint
+  file selection.
+- Latest stable ESLint and electron-builder versions are pinned exactly. The
+  residual chain will be retested whenever either publishes a dependency fix.
+
+The release gate treats `npm audit --omit=dev --audit-level=high` as blocking.
+The complete development audit remains documented and visible rather than
+being misrepresented as a production vulnerability count.

docs/DEPLOYMENT_MIGRATION_EXAMPLE.md

@@ -0,0 +1,63 @@
+# Deployment migration example
+
+This example shows how to bring an existing Git-backed Docker or Unraid application under ForgeFlow control without exposing or overwriting runtime data.
+
+Use synthetic names and values while testing. Replace them with your own repository, server and paths only in ForgeFlow's local configuration; do not commit credentials or environment-specific diagnostics.
+
+## 1. Establish the authoritative repository
+
+Before deploying, verify that the server checkout and Gitea repository represent the same application:
+
+- compare the complete 40-character commit SHA;
+- confirm the configured remote belongs to the intended Gitea origin and repository;
+- preserve the root `.git` directory for exact-SHA verification and rollback;
+- resolve any remote URL mismatch explicitly instead of silently rewriting it.
+
+ForgeFlow blocks deployment when the existing origin conflicts with the selected repository unless the user explicitly approves alignment.
+
+## 2. Protect runtime data
+
+Typical persistent paths include:
+
+```text
+.env
+appdata/
+config/
+data/
+logs/
+compose.override.yml
+```
+
+Keep those paths outside the tracked deployment payload and add runtime-only directories to `.dockerignore` when they are not build inputs. ForgeFlow uses a controlled Git reset without `git clean`, but the repository's own Compose and ignore rules remain authoritative.
+
+## 3. Reuse the maintained Compose definition
+
+Prefer the repository's existing `compose.yml` or `docker-compose.yml` when it already defines ports, volumes, device mappings, labels and health checks. These application-specific settings should be reviewed and versioned with the application rather than regenerated during deployment.
+
+## 4. Handle nested repositories separately
+
+A historical checkout such as `source/` may contain another `.git` directory. Treat this as a migration warning:
+
+1. verify that the root Compose file builds from the intended root;
+2. back up the application folder;
+3. stop modifying the nested checkout;
+4. rename it temporarily;
+5. rebuild and verify the application from the root checkout;
+6. remove the legacy copy only after rollback has also been tested.
+
+ForgeFlow reports nested repositories but does not delete them automatically.
+
+## 5. Recommended profile
+
+```text
+Provider:       SSH / Unraid
+Server folder:  example-app
+Branch:         main
+Compose mode:   Repository/server Compose
+Compose file:   compose.yml
+Clone URL:      a Git URL reachable from the server
+Healthcheck:    the application's existing health endpoint
+Preserve paths: .env, appdata, config, data, logs, compose.override.yml
+```
+
+Complete a preflight first, deploy one exact commit, verify both the live SHA and runtime health, and test rollback before treating the migration as production-ready.

docs/DEPLOYMENT_SETUP.md

@@ -0,0 +1,58 @@
+# Deployment setup guide
+
+This guide connects one Gitea repository to one server environment without giving the desktop arbitrary shell access.
+
+## 1. Add fixed workflows
+
+Copy these examples into the repository:
+
+```text
+examples/gitea-actions/deploy.yml   -> .gitea/workflows/deploy.yml
+examples/gitea-actions/rollback.yml -> .gitea/workflows/rollback.yml
+```
+
+Change the runner label to the label registered for the target environment.
+
+## 2. Install the allowlisted server entry point
+
+Copy `examples/server/forgeflow-deploy` to `/usr/local/bin/forgeflow-deploy`, customize its repository/environment allowlist and make it root-owned:
+
+```bash
+sudo install -o root -g root -m 0755 forgeflow-deploy /usr/local/bin/forgeflow-deploy
+```
+
+Grant the runner account permission to execute only this entry point where elevation is needed. Do not grant unrestricted shell or Docker administration merely for ForgeFlow.
+
+## 3. Expose deployment status
+
+The example script writes an atomic JSON document beneath `/var/lib/forgeflow-status`. Serve the appropriate file at a fixed HTTPS URL, for example with `examples/server/nginx-forgeflow-status.conf`.
+
+See `STATUS_ENDPOINT.md` for the contract.
+
+## 4. Configure the ForgeFlow profile
+
+Open the repository, choose **Deployments** and add an environment with:
+
+- Name: `Production` or `Staging`.
+- Environment: the fixed workflow input.
+- Branch: usually `main`.
+- Workflow file: `deploy.yml`.
+- Rollback workflow: `rollback.yml`.
+- Status URL: the JSON endpoint.
+- Healthcheck URL: the application health endpoint.
+- Confirmation: enabled for production.
+
+## 5. Validate the complete path
+
+Test these scenarios before relying on production:
+
+1. Clean commit and push.
+2. Successful deployment to the exact SHA.
+3. Gitea runner failure.
+4. Application healthcheck failure.
+5. Server reports the wrong SHA.
+6. Second deployment while the lock is held.
+7. Rollback to the recorded previous SHA.
+8. Token without sufficient permissions.
+
+Keep a manual recovery path documented even after rollback works.

docs/DIAGNOSTICS.md

@@ -0,0 +1,150 @@
+# Diagnostics, privacy and support bundles
+
+ForgeFlow v0.3.2 records development-oriented diagnostics locally so failures
+can be investigated without requesting the user's Gitea token, SSH key or
+server password.
+
+## Storage
+
+Diagnostic events are stored beneath the Electron application-data directory in:
+
+```text
+diagnostics/forgeflow-YYYY-MM-DD.jsonl
+```
+
+The Diagnostics page displays an aliased path such as `<HOME>` rather than the
+Windows account name. Files use restrictive permissions where the operating
+system supports them.
+
+Defaults:
+
+- enabled;
+- minimum level `info`;
+- 14-day retention;
+- 8 MB maximum per log segment;
+- daily filenames with numbered rotation;
+- ordered asynchronous writes;
+- no application crash when diagnostic storage itself fails.
+
+These values can be changed in **Diagnostics -> Recording policy**.
+
+## What an event can contain
+
+Useful fields include:
+
+- UTC timestamp;
+- level and stable event name;
+- per-launch session identifier;
+- operation or deployment request identifier;
+- Git/Gitea operation outcome;
+- HTTP status, duration and endpoint path without request headers;
+- repository state and branch/SHA metadata;
+- preflight result;
+- sanitized exception name, code, message and stack;
+- renderer crash or unhandled-rejection metadata.
+
+ForgeFlow does not log IPC payloads, request authorization headers or Gitea
+response bodies merely because a request was made.
+
+## Redaction
+
+Every event passes through a recursive sanitizer before it is written.
+Redaction covers:
+
+- the currently active Gitea token;
+- token, password, authorization, credential, API-key, client-secret and
+  encrypted-token object fields, including camelCase variants;
+- bearer/token/basic authorization values in strings;
+- common token query parameters;
+- credentials embedded in URLs;
+- PEM private-key blocks;
+- known Gitea/Git hosting token patterns;
+- Windows, macOS and Linux home-directory paths;
+- application source path aliases;
+- circular data structures and oversized strings.
+
+Credential values are replaced with `[REDACTED]`; user paths use aliases such as
+`<HOME>`.
+
+## Support bundle
+
+**Create diagnostic ZIP** exports a local archive containing:
+
+```text
+manifest.json
+safety-audit.json
+README.txt
+system.json
+diagnostics-status.json
+configuration-sanitized.json
+repositories-sanitized.json
+operations-sanitized.json
+preflight.json
+context.json
+logs/*.jsonl
+```
+
+The application returns the SHA-256 of the generated archive so a shared file
+can be identified exactly.
+
+### Excluded data
+
+The bundle intentionally excludes:
+
+- plaintext Gitea access tokens;
+- Electron `safeStorage` encrypted-token blobs;
+- request authorization headers;
+- passwords and private keys;
+- raw Gitea runner logs;
+- arbitrary environment-variable dumps;
+- full local file contents and Git diffs.
+
+ForgeFlow does not automatically ingest or persist raw runner output. Job names,
+statuses and safe operation summaries are stored locally; full runner output remains
+available only in the trusted Gitea Actions interface when deeper server-side
+investigation is necessary.
+
+## Privacy modes
+
+### Standard
+
+Preserves repository names and user-facing identifiers. Local home paths and
+credentials are still redacted. Use when the recipient already knows the
+project context.
+
+### Strict
+
+Additionally replaces repository and user identifiers with deterministic
+SHA-256-based aliases. Related events remain correlatable without revealing the
+original names.
+
+## Fail-closed bundle audit
+
+Immediately before writing the archive, ForgeFlow scans every prepared entry
+for:
+
+- the known active runtime secret values;
+- private-key begin markers;
+- unredacted credentials embedded in HTTP(S) URLs.
+
+The result is stored as `safety-audit.json`. When a finding remains, archive
+creation is aborted and the unsafe ZIP is not written.
+
+## Practical limitation
+
+No generic logger can mathematically identify every unknown secret if a third-
+party process prints an arbitrary value without a label or recognizable format.
+ForgeFlow reduces this risk by not including raw runner logs, not recording IPC
+payloads and applying both structured and textual redaction. Always inspect a
+support bundle before sharing it, particularly when custom integrations have
+been added.
+
+## Development workflow after a failure
+
+1. Reproduce the issue once when safe.
+2. Note the approximate time and repository/environment.
+3. Run the relevant preflight.
+4. Export a Strict diagnostic bundle.
+5. Keep the returned SHA-256 with the bug report.
+6. Describe the visible action that failed.
+7. Share no separate token, key or password.

docs/ERROR_CODES.md

@@ -0,0 +1,15 @@
+# ForgeFlow error and recovery catalog
+
+| Code | Meaning | Recovery |
+| --- | --- | --- |
+| `RECONCILIATION_PLAN_REQUIRED` | A server mutation was requested without its reviewed plan. | Open Review reconciliation and apply the current plan ID. |
+| `RECONCILIATION_PLAN_STALE` | Server truth changed after preview. | Rescan, review the new impact and apply that plan. |
+| `SERVER_GIT_VERIFICATION_FAILED` | Branch, deploy key or pinned SSH evidence could not be proven. | Run Verify server pull; repair only the failing check before retrying. |
+| `DEPLOY_KEY_NOT_READ_ONLY` | A matching key can write to Gitea. | Revoke it in Gitea and configure a dedicated read-only key. |
+| `SSH_DEPLOYMENT_PREFLIGHT_FAILED` | One or more deployment safety checks failed. | Open preflight evidence and follow the failing check's detail. |
+| `REMOTE_WRITE_ACCESS_REQUIRED` | The SSH user cannot safely write the managed source/state paths. | Use Check / fix write access after reviewing its scoped impact. |
+| `UPDATE_ORIGIN_MISMATCH` | An update asset points outside the trusted Gitea origin. | Correct release asset URLs; never bypass the origin check. |
+| `UPDATE_CHECKSUM_MISMATCH` | Downloaded bytes do not match the published checksum. | Keep the current version and republish the exact commit atomically. |
+
+Audit and discovery never repair these conditions automatically. Mutating recovery
+actions require an explicit user flow and preserve rollback or snapshot evidence.

docs/MUTATION_MODEL.md

@@ -0,0 +1,26 @@
+# Mutation and reconciliation model
+
+ForgeFlow separates observation from state changes at the API boundary.
+
+## Discovery
+
+`scanServerInventory()` and `discoverServerWorkloads()` collect Docker, Compose, DockerMan and Git evidence. They may write diagnostic logs, but they do not save, update or delete deployment profiles and do not change containers.
+
+## Reconciliation planning
+
+`planServerInventoryReconciliation()` returns a content-addressed plan containing:
+
+- exact links that may be added;
+- existing profiles whose observed metadata may be refreshed;
+- stale profiles that require review;
+- ambiguous workloads that block automatic application.
+
+The plan identifier changes whenever its proposed scope changes.
+
+## Reconciliation application
+
+`reconcileServerInventory()` requires the exact reviewed plan identifier. It rescans the server and refuses a stale plan. Before writing configuration it creates a private recovery snapshot. Stale profiles are reported but never removed automatically.
+
+## Direct mutations
+
+Manual linking, unlinking, deploy-key rotation, deployment and rollback remain separate explicit commands. Each must append an audit event with repository, profile, operation identifier and result. Destructive commands need a dedicated confirmation flow and recovery path.

docs/PRODUCTION_READINESS_1.0.md

@@ -0,0 +1,78 @@
+# ForgeFlow 1.0 production-readiness evidence
+
+## 1. Scope and history
+
+The professionalization work started from `64ca267` on `main`. It preserves the
+0.10.0 compatibility baseline and deliberately creates no 1.0 tag or public
+release. The commits and their exact SHAs remain the authoritative audit trail.
+
+## 2. Deployment safety
+
+Server pull uses repository-scoped read-only deploy keys, exact commit SHAs,
+pinned SSH/Gitea host identities, Compose validation, health evidence and bounded
+rollback. Rotation is transactional and revocation requires reviewed impact and
+recovery evidence. Direct Copy and monitor-only remain explicit alternatives.
+
+## 3. Inventory and reconciliation
+
+Canonical deployment identity combines repository, branch, server, environment,
+Compose project/root, runtime labels, container, live SHA and profile. Duplicate,
+stale, ambiguous, orphan and historical evidence has persistent content-addressed
+review decisions. Discovery never deletes, stops or rewrites a workload.
+
+## 4. Architecture
+
+Renderer, IPC and Unraid responsibilities are split by domain. The generated
+architecture audit currently reports zero source files above 750 or 1,000 lines.
+Runtime schemas, bounded IPC capabilities, operation IDs and explicit error
+contracts protect the process boundary.
+
+## 5. Repository assurance
+
+Git Validator 2.0 covers security, reproducibility, governance, collaboration,
+performance/hygiene and release readiness. Minimal, Standard, Strict, Production
+and custom policies support accountable expiring suppressions, trend history and
+reviewable JSON/Markdown/HTML reports. Repairs always require preview and never
+commit or push automatically.
+
+## 6. Automated verification
+
+The Node suite includes real temporary Git remotes and an isolated production
+acceptance harness. Playwright adds 36 renderer cases across six viewport/theme/
+motion/scaling projects. Failure artifacts contain screenshots, traces, video,
+console events, DOM, fixture details and test identity.
+
+## 7. Coverage and dependencies
+
+Coverage increased from 69.74% statements/lines, 68.82% functions and 55.38%
+branches to 81.48%, 82.07% and 65.59%, respectively. The enforced gates are now
+75/75/75/65 and are documented in `COVERAGE_POLICY.md`. Production dependencies have zero known
+audit vulnerabilities. Remaining development findings belong to current upstream
+ESLint/electron-builder toolchains and are assessed in `DEPENDENCY_AUDIT.md`.
+
+## 8. UX and accessibility
+
+Dark and light themes use the same semantic hierarchy, restrained project-signal
+motion and status text that never depends on color alone. Deployment cards expose
+container, repository, environment, commit parity and health distinctly. Dense
+inventories, long names, keyboard focus, dialogs, reduced motion and high scaling
+are part of the automated matrix.
+
+## 9. Packaging and updating
+
+Windows installer and portable packaging use deterministic names; old `dist`
+versions are pruned after every successful build. Publication stays draft until
+installer, portable, checksums, provenance and CycloneDX SBOM are complete. Binary
+updates verify the exact release asset, executable format and published SHA-256
+before download staging and again before replacement. Authenticode is optional and
+is not a release or updater dependency for this personal/internal application.
+
+## 10. Release decision
+
+No open P0 or P1 technical issue is known after the final quality, browser,
+acceptance, signing and packaging gates. The technically correct status is:
+
+`TECHNICALLY_COMPLETE`
+
+There is no paid certificate or external signing-service dependency. Windows may
+show its normal unknown-publisher warning during first installation.

docs/RELEASE_AUDIT_0.6.0.md

@@ -0,0 +1,73 @@
+# ForgeFlow 0.6.0 release audit
+
+## Scope
+
+This audit covers the source release intended for publication to `Jens/ForgeFlow` and subsequent installation through ForgeFlow's built-in source updater.
+
+Reviewed areas:
+
+- local Git discovery, status, staging, commit, push, fetch and fast-forward;
+- large Windows path selections and deleted/renamed files;
+- stale Git lock diagnosis, conservative repair and automatic retry;
+- divergence recovery with a safety branch;
+- Gitea repository and Actions integration;
+- SSH host identity, Unraid-to-Gitea preflight and exact-SHA deployment;
+- Docker Compose identity normalization while preserving visible container names;
+- DockerMan WebUI, icon and shell labels, XML fallback and cache refresh;
+- interrupted/stale deployment reconciliation;
+- renderer viewport behavior and guided troubleshooting;
+- diagnostics redaction and support bundles;
+- release publication and built-in source-update lifecycle.
+
+## Regression coverage
+
+The automated suite contains 99 passing tests, including real temporary Git repositories and bare remotes. High-risk regressions covered directly include:
+
+- staged and unstaged deletions;
+- renamed files;
+- a local commit followed by a failed push;
+- 850 long selected paths transported through NUL-delimited stdin;
+- stale `HEAD.lock` removal while excluding Git object/LFS storage;
+- backup-before-reset repair of a diverged branch;
+- exact remote-SHA checks;
+- background SSH deployment completion without a stuck operation;
+- startup/manual reconciliation of live Unraid state;
+- lowercase-safe Compose project/service/image identities with visible `Portfolio` casing;
+- DockerMan labels, built-in icon upload, XML fallback and cache invalidation;
+- source-updater STARTED handshake, result acknowledgement, direct Electron restart and rollback state.
+
+## Product behavior added for the reported incidents
+
+- Git mutations are serialized per repository.
+- A lock failure triggers a safe diagnosis and one automatic repair/retry when no active Git process is detected.
+- Git Tools provides personalized scan, lock repair, origin repair, fast-forward, push and safety-branch divergence recovery actions.
+- Successful SSH deployments become terminal before the secondary server refresh, preventing a live container from leaving ForgeFlow in deployment mode.
+- ForgeFlow refreshes configured server truth after startup and through the combined refresh action.
+- A healthy live SHA equal to local/Gitea is not offered for deployment again.
+- Running containers missing DockerMan metadata can be repaired individually or in one batch from Deployments.
+- Built-in/uploaded icons are placed in persistent DockerMan storage, referenced through a `file:///` label, written into a user template and copied into known icon caches.
+- WebUI uses the Unraid label placeholders based on the configured host port and path.
+- Update publication creates and publishes `package-lock.json`; the updater uses `npm ci` when it is present.
+- Update success is persisted before restart, and restart invokes Electron directly rather than relying on a detached npm process.
+
+## Static and packaging checks
+
+- every JavaScript/CJS/MJS source file passes `node --check`;
+- required source, branding, documentation, updater and deployment files are present;
+- direct dependency versions are pinned;
+- renderer privileged actions remain behind the preload/IPC boundary;
+- the PowerShell update helper starts with `param(`, has no UTF-8 BOM and contains lifecycle state before shutdown/restart;
+- release archives exclude `.git`, `node_modules`, `dist`, update downloads and generated ZIPs;
+- the generated source manifest records SHA-256 and size for every distributed source file.
+
+## Remaining live acceptance step
+
+The automated environment cannot execute Windows PowerShell 5.1 or connect to the user's private Gitea/Unraid services. The final live acceptance is therefore deliberately the requested workflow:
+
+1. publish the release from an extracted Downloads folder;
+2. leave the installed older source at `C:\Projects\ForgeFlow` untouched;
+3. open that older ForgeFlow;
+4. use **Settings → ForgeFlow updates → Check now → Download update → Apply & restart**;
+5. confirm the restarted application reports version 0.6.0 and displays the persisted success result.
+
+A failed handoff must keep the old app open. A failed validation must restore the previous source. A successful installation remains installed even when only automatic restart fails.

docs/RELEASE_NOTES_0.10.0.md

@@ -0,0 +1,32 @@
+# ForgeFlow 0.10.0
+
+ForgeFlow 0.10.0 makes existing Unraid workloads substantially easier and safer to adopt, verify and deploy.
+
+## Deployment discovery and verification
+
+- Automatic discovery links unique running server workloads to their matching Gitea repositories while excluding unrelated infrastructure and stale release folders.
+- Deployment cards preserve the last verified live commit and compare it with the current Gitea branch, even when a container was updated outside ForgeFlow.
+- Existing Compose project names, files, services, remote folders and DockerMan metadata are adopted from server truth instead of guessed or overwritten.
+
+## Safe Server pull
+
+- Server pull is now the recommended deployment route and fetches the exact requested commit from Gitea.
+- Each repository receives its own repository-scoped read-only deploy key; ForgeFlow never installs the desktop Gitea token on Unraid.
+- Gitea SSH host fingerprints are pinned and checked before trust is changed and before every pull.
+- Fetch, archive, checksum, Compose validation, activation and rollback remain exact-commit and transactional.
+- Direct copy remains available when server-side Git access is undesirable, and monitoring-only links cannot deploy accidentally.
+
+## Git hygiene
+
+- Git Validator now also checks `.gitattributes`, `.editorconfig`, dependency lockfiles and a Gitea Actions workflow.
+- Safe repairs create reviewable files without committing or pushing them automatically.
+- Existing identity, upstream, synchronization, branch-protection, documentation, secret-path and oversized-file checks remain available in one scored view.
+
+## Interface and reliability
+
+- The deployment workspace now emphasizes repository, container, environment and live-versus-Gitea evidence, with a focused animated project illustration and clearer server inventory.
+- Large unrelated server inventories are summarized instead of producing dozens of indistinguishable cards.
+- Connection validation consistently opens the same encrypted Electron profile as the installed app.
+- Obsolete ForgeFlow artifacts are removed from `dist` after every successful packaged build.
+
+No container was restarted or replaced during automatic discovery. Deployments still require a successful preflight and an explicit user action.

docs/RELEASE_NOTES_0.10.1.md

@@ -0,0 +1,21 @@
+# ForgeFlow 0.10.1
+
+## Reliable certificate-free updates
+
+- Windows installer and portable releases are supported without paid signing services.
+- Packaged updates remain protected by exact Gitea release assets, PE validation and SHA-256 verification before staging and immediately before replacement.
+- Old ForgeFlow versions are pruned from `dist` after each successful build.
+
+## Deployment inventory correctness
+
+- Repository matching is case-insensitive, so `Jens/Repo` and `jens/repo` refresh the same deployment profile.
+- Running repository workloads are linked conservatively; third-party DockerMan applications remain visible as external monitoring-only workloads instead of generating hundreds of false repository problems.
+- Historical and stopped duplicate definitions no longer require repetitive manual review.
+- Shadowed automatic profiles are retired only after a recovery snapshot and a stable reviewed reconciliation plan.
+- Live runtime, container health and commit evidence are refreshed before readiness is reported.
+
+## Server pull verification
+
+- Existing running repository workloads can receive repository-scoped read-only deploy keys without changing containers.
+- The audit command supports compact inventory, reconciliation and access evidence for operational verification.
+- Release acceptance no longer assumes an external Authenticode certificate while retaining checksum, provenance and SBOM checks.

docs/RELEASE_NOTES_0.10.10.md

@@ -0,0 +1,10 @@
+# ForgeFlow 0.10.10
+
+## Complete server-pull deployment repair
+
+- Missing repository-scoped read-only deploy keys can be provisioned and verified from Unraid against the exact Gitea branch.
+- A repository deployment root can now remain above its Compose working directory without breaking workload recognition or being overwritten by inventory refresh.
+- Nested Compose files are preserved as repository-relative deployment paths, including Ludarium, Launchpad and ITWorx MCP Hub layouts.
+- The **Fix write access** action now receives its permission-report parser correctly instead of reporting a false write-access failure.
+- Server-pull preflight proves every required deployment file at the exact Gitea commit before any container activation starts.
+- Runtime secrets remain in server-side `.env` files and preserved appdata paths; no secret values are written to Git or diagnostic output.

docs/RELEASE_NOTES_0.10.11.md

@@ -0,0 +1,10 @@
+# ForgeFlow 0.10.11
+
+## Resilient repository refresh and consistent server pull
+
+- Temporary Gitea list failures now use the in-session **last-known-good** repository inventory while local and server state continue to refresh. The UI clearly reports that remote data is stale.
+- A **closed output pipe** from a detached parent process is no longer treated as a fatal desktop-app exception.
+- Server pull, deploy-key verification, deployment, rollback and metadata now consistently prefer the verified **linked checkout origin** over a stale URL detected earlier on the server.
+- Repository-scoped **read-only deploy key** checks remain fail-closed; a changed SSH host still requires explicit trust and access reconfiguration.
+- The local **browser test server** now has a dedicated port and identity endpoint, preventing another localhost application from being mistaken for ForgeFlow.
+- All 42 responsive browser flows pass across dark/light, compact/wide and reduced-motion configurations.

docs/RELEASE_NOTES_0.10.12.md

@@ -0,0 +1,12 @@
+# ForgeFlow 0.10.12
+
+## Faster awareness with stricter deployment truth
+
+- Repository refreshes are **coalesced** and briefly cache Gitea inventory and workspace discovery; a manual refresh remains fully forced and file changes arriving mid-refresh receive one trailing refresh.
+- Server discovery reuses its Docker and Compose evidence for existing deployment profiles instead of opening a separate SSH session for every linked workload.
+- Deployment status only claims **exact Gitea commit parity** after comparing a concrete branch SHA with the live server SHA; matching repository provenance alone is no longer sufficient.
+- Container discovery uses **batched Docker inspect** with a safe per-container fallback when a container disappears during the scan.
+- Active Gitea and SSH deployment polling uses **bounded worker pools**, improving multi-deployment latency without flooding external services.
+- A **stopped container** can no longer be marked healthy because another process answers on its previous healthcheck port.
+- Large repository and server-inventory lists use offscreen rendering containment to reduce layout and paint work.
+- Inventory diagnostics now include scan and state-refresh durations, and Gitea bulk verification fails fast after a confirmed connectivity outage.

docs/RELEASE_NOTES_0.10.13.md

@@ -0,0 +1,18 @@
+# ForgeFlow 0.10.13
+
+## Veilige synchronisatie en aantoonbare release-integriteit
+
+- **Gitea workspace sync** toont eerst de exacte additions, wijzigingen en deletions ten opzichte van de actuele upstream-SHA. Lokale commits worden beschermd in een recovery branch; staged, unstaged en untracked werk gaat naar een stash. Genegeerde runtimebestanden blijven onaangeroerd.
+- Read-only achtergrondfetch houdt `ahead` en `behind` actueel zonder projectbestanden automatisch te wijzigen. Interval `0` schakelt netwerkfetch volledig uit.
+- Stale deployment links blokkeren niet langer de automatische, bewijsgebaseerde koppeling van de werkelijk draaiende vervangende workload.
+- SSH-hostidentiteit wordt vóór het verzenden van credentials getoond en bij bevestiging exact vastgepind. Gitea-tokens vereisen HTTPS, behalve bij expliciete loopbackontwikkeling.
+- Packaged updates vereisen een **Ed25519-signed release manifest** dat versie, tag, broncommit, artifactnaam, bytegrootte en SHA-256 bindt aan de ingebouwde publisher key. Hiervoor is geen betaald certificaat of Azure-dienst nodig.
+- Diagnostische bundels exporteren geen ruwe remote output meer. Untracked diffs kunnen geen junction of symlink buiten de repository volgen en zijn begrensd op bestandsgrootte.
+- De Git-toolsgrid behoudt nu de volledige inhoudshoogte binnen zijn eigen scrollvlak; workspace sync en troubleshooting overlappen niet meer. De demo bridge ondersteunt dezelfde recoveryflow als de desktopapp.
+- Repositorymonitoring, deploymentpolling, Docker-inspect en SSH-verbindingen gebruiken begrensde paralleliteit en hergebruik waar dat veilig is.
+
+## Verificatie
+
+- Volledige Node-testset, coveragepoort, architectuuraudit en dependency-audit.
+- 72 browserflows over dark/light, compact/desktop/wide, 100–150% schaal en reduced motion.
+- Windows installer en portable build, SHA-256-sidecars, provenance, CycloneDX-SBOM en ondertekend releasemanifest.

docs/RELEASE_NOTES_0.10.14.md

@@ -0,0 +1,15 @@
+# ForgeFlow 0.10.14
+
+## Betere uitleg en een stabiele repositorywerkruimte
+
+- Een nieuw doorzoekbaar **Help center** legt de belangrijkste workflows stap voor stap uit: eerste configuratie, changes en commits, Gitea workspace sync, deploymentdetectie, exacte serverdeployments, deploykeys, Git Validator, updates en diagnose.
+- Contextuele help vanuit **Gitea workspace sync** opent onmiddellijk de relevante uitleg. De instructies maken expliciet wat ForgeFlow wijzigt, welke recovery ForgeFlow vooraf maakt en welke genegeerde runtimebestanden onaangeroerd blijven.
+- De variabele **repository context** is samengebracht in één structurele zone. Quick actions, Local → Gitea → Server-status en gekoppelde deployments kunnen daardoor niet langer over de tabnavigatie of inhoud heen schuiven.
+- Smalle werkruimtes gebruiken gecontroleerde **horizontal tab navigation**. Elke tab behoudt zijn volledige label en blijft bereikbaar zonder dat tekst door andere bedieningselementen loopt.
+- Het Help center heeft een eigen premium, responsieve presentatie met categorieën, zoekresultaten, uitklapbare stappen, veiligheidsnotities en motion-safe projectillustratie.
+
+## Verificatie
+
+- Volledige Node-testset en statische renderercontroles.
+- **84 browser flows** over dark/light, compact/desktop/wide, 100–150% schaal en reduced motion; de drie tijdens een semantische testaanpassing geraakte flows zijn daarna opnieuw groen uitgevoerd.
+- Extra layoutasserties bewijzen dat repository context, tabs en tabinhoud elkaar niet overlappen bij 1024 × 768.

docs/RELEASE_NOTES_0.10.15.md

@@ -0,0 +1,15 @@
+# ForgeFlow 0.10.15
+
+## Veilige exacte workspace-sync en robuustere updates
+
+- **Workspace Sync** brengt een repository gecontroleerd naar de exacte Gitea-commit zonder lokale wijzigingen stilzwijgend terug naar de server te sturen. Lokale commits krijgen een recovery branch en gewijzigde of niet-getrackte bestanden worden in een expliciete ForgeFlow-quarantaine bewaard.
+- Elke quarantaine krijgt een lokaal **Codex review manifest** met bron- en doelcommit, recovery branch, stash-identiteit en betrokken bestanden. Quarantainestashes kunnen niet via de normale ForgeFlow-herstelactie in één keer worden teruggezet; eerst moet de inhoud gericht worden nagekeken.
+- ForgeFlow behandelt `forgeflow/recovery-*` branches als **local-only** en weigert ze via de normale pushactie te publiceren, zodat herstelmateriaal niet per ongeluk opnieuw in Gitea terechtkomt.
+- De source updater voert checksum- en Git-working-tree-preflight uit **voordat** ForgeFlow de update aan de externe helper overdraagt. Een Git-checkout wordt niet meer destructief met een bronarchief overschreven.
+- De Windows binary updater controleert het nieuwe uitvoerbare bestand vóór de ownership handoff, verifieert na update dat ForgeFlow werkelijk blijft draaien en kan bij een mislukte portable update de vorige executable herstellen en opnieuw starten.
+- Een geslaagde installer-update waarbij alleen de automatische herstart mislukt, wordt correct als geïnstalleerd gerapporteerd met een duidelijke instructie om ForgeFlow handmatig te starten.
+
+## Verificatie
+
+- Managed full validation op de sync/updater-hardening is geslaagd op de exacte feature-head en opnieuw als verplichte pull-requestvalidatie vóór merge.
+- De merge naar `main` is uitgevoerd via de beschermde pull-requestflow; de releaseversie wordt afzonderlijk gevalideerd voordat 0.10.15 wordt gepubliceerd.

docs/RELEASE_NOTES_0.10.2.md

@@ -0,0 +1,9 @@
+# ForgeFlow 0.10.2
+
+## Packaged updater origin repair
+
+- Gitea release assets that expose an internal HTTP `ROOT_URL` are safely rewritten to ForgeFlow's configured public HTTPS Gitea origin.
+- Authentication remains same-origin: the Gitea token is never forwarded to an internal address, CDN or unrelated redirect target.
+- Published Windows executables are still validated as PE files and against their release SHA-256 sidecars before staging.
+- The live authenticated updater acceptance downloads the exact published installer and proves its byte count and SHA-256 digest.
+

docs/RELEASE_NOTES_0.10.3.md

@@ -0,0 +1,19 @@
+# ForgeFlow 0.10.3
+
+## Responsive large workspaces
+
+- Repository monitoring checks up to four local working trees concurrently while retaining overlap protection and per-repository pause controls.
+- Global search, repository filtering and the command palette debounce full interface renders during rapid typing.
+- Commit-message input updates readiness and action controls in place, preserving focus and cursor responsiveness.
+- Interactive project illustrations and diff atmosphere effects perform at most one layout update per animation frame.
+
+## Git Validator reliability
+
+- Git Validator and every long repository tab now retain an explicit vertical scroll owner across compact, desktop and wide layouts.
+- Standard, Strict and Production policies correctly treat configured warning severities as blockers; Minimal remains error-only.
+- Documented suppressions no longer reduce the hygiene score or remain counted as active blockers.
+- Repair requests are rescanned immediately before preview or execution, preventing stale or forged fixes.
+
+## Verification
+
+- Full quality gate, coverage thresholds and all responsive browser scenarios pass for this release.

docs/RELEASE_NOTES_0.10.4.md

@@ -0,0 +1,9 @@
+# ForgeFlow 0.10.4
+
+## Permanent packaged updater handshake repair
+
+- Binary and source update helpers now use a Windows PowerShell 5.1-compatible atomic status replacement with a real temporary backup path.
+- A deterministic overwrite fallback preserves lifecycle reporting on filesystems that do not implement atomic replacement.
+- The binary helper exposes a side-effect-free handshake-only verification mode exercised by the real Windows PowerShell executable during tests.
+- existing installations with the defective helper require this one-time installer upgrade; every subsequent packaged update uses the repaired helper automatically.
+- Startup failures retain request-scoped status and helper-log evidence instead of collapsing into an unexplained exit-code message.

docs/RELEASE_NOTES_0.10.5.md

@@ -0,0 +1,10 @@
+# ForgeFlow 0.10.5
+
+## Consistent repository and deployment links
+
+- Every repository workspace now shows all configured deployment environments in a compact, directly actionable strip.
+- The repository deployment tab includes every detected server workload linked to that repository, including its container, Compose identity, server and runtime state.
+- A workload is only labelled linked when its repository and resolved profile both exist in the current ForgeFlow configuration.
+- Stale or incomplete metadata is shown as **Link unresolved** and routed through explicit reconciliation instead of being presented as a healthy deployment.
+- The global deployment inventory links directly to the correct repository deployment profile.
+- Responsive browser coverage now verifies valid links, unresolved links, repository navigation and scrolling across dark/light and scaled layouts.

docs/RELEASE_NOTES_0.10.6.md

@@ -0,0 +1,9 @@
+# ForgeFlow 0.10.6
+
+## Permanent Windows updater launch repair
+
+- ForgeFlow no longer launches hidden PowerShell update helpers with Node's defective Windows `detached` process mode.
+- Binary and source updater processes remain hidden, are explicitly unreferenced after their verified handshake, and continue independently when ForgeFlow closes.
+- A real Windows regression test now exercises the exact production Node spawn options instead of using a different process API.
+- Startup is still fail-closed: ForgeFlow remains open unless the request-scoped helper status reaches `started`.
+- Versions 0.10.4 and 0.10.5 need a one-time direct installation of 0.10.6 because their installed launcher cannot execute its own helper; updates after 0.10.6 use the repaired path.

docs/RELEASE_NOTES_0.10.7.md

@@ -0,0 +1,10 @@
+# ForgeFlow 0.10.7
+
+## Reliable server-to-repository recognition
+
+- Live, running workloads with one unique exact provenance or runtime-identity match are now linked automatically during normal server discovery.
+- Automatic adoption creates only ForgeFlow configuration and observed state; it performs no container changes and never automatically removes stale profiles.
+- Ambiguous, duplicate, external and monitoring-only workloads remain behind explicit **Review & link** confirmation.
+- Every linked repository now displays an `S` deployment badge with its profile count in the repository sidebar.
+- The repository release rail reports **Linked** with container and server identity even when a legacy workload has no verifiable live commit yet.
+- DevRunbook-style DockerMan deployments therefore show the same linked relationship in Deployments, the repository sidebar and the repository workspace.

docs/RELEASE_NOTES_0.10.8.md

@@ -0,0 +1,9 @@
+# ForgeFlow 0.10.8
+
+## Self-contained checksum verification
+
+- Binary and source update helpers no longer depend on the optional PowerShell `Get-FileHash` cmdlet.
+- Both helpers calculate checksums directly with the built-in .NET SHA-256 implementation.
+- A real Windows regression test clears `PSModulePath` and verifies the downloaded binary successfully in that minimal environment.
+- The helper still validates the exact published checksum before waiting for ForgeFlow to exit or changing installed files.
+- This release retains the reliable non-detached launcher and server-to-repository recognition improvements from 0.10.6 and 0.10.7.

docs/RELEASE_NOTES_0.10.9.md

@@ -0,0 +1,10 @@
+# ForgeFlow 0.10.9
+
+## Reliable deployment inventory and preflight
+
+- Unraid inventory now includes containers without healthchecks. Docker's complete JSON state is parsed safely instead of using a failing Go-template lookup.
+- ForgeFlow is single-instance: opening it again focuses the existing window, preventing concurrent inventory scans and configuration writes.
+- Server pull verifies required Compose files or the Dockerfile at the exact Gitea commit before any deployment operation starts.
+- Server-pull verification now separates deploy-ready access from optional live-SHA and runtime-health evidence. A recoverable workload is no longer shown as blocked merely because parity is not yet provable.
+- Deployment cards and audit output show concrete access blockers and non-blocking warnings instead of a generic incomplete result.
+- All discovery, verification and preflight checks remain non-destructive; no containers are changed during these checks.

docs/RELEASE_NOTES_0.2.0.md

@@ -0,0 +1,32 @@
+# ForgeFlow 0.2.0 release notes
+
+ForgeFlow 0.2.0 turns the original visual prototype into a substantially more operational personal release cockpit.
+
+## Highlights
+
+- Automatic repository status monitoring with safe pause/resume around Git mutations.
+- Commit-only and commit-and-push flows with recoverable push failures.
+- Branch creation, switching, publication and stash workflows.
+- Favorite repositories and action-oriented attention queues.
+- Multiple deployment environments per repository.
+- Exact remote-branch SHA verification before deploy and rollback.
+- Gitea Actions run, job and available log polling.
+- Live server version, previous version and health verification.
+- Fixed-workflow rollback to a recorded full commit SHA.
+- Stronger IPC, URL, path and secret-handling controls.
+- Reworked renderer with command palette and live deployment states.
+- 21 passing automated tests, including real temporary Git remotes.
+- Headless browser smoke coverage at three desktop viewport sizes.
+
+## Upgrade notes
+
+Configuration is migrated automatically to schema version 2. Existing Gitea tokens are preserved when the settings form is saved with an empty token field.
+
+Deployment profiles now support independent branch, workflow, rollback workflow, healthcheck and status endpoint settings. Review existing profiles before using them against production.
+
+## Known limitations
+
+- No signed installer or automatic update channel is included in this source release.
+- Partial-hunk staging, conflict resolution and protected-branch awareness are not yet implemented.
+- Gitea Actions behavior still needs acceptance testing against the intended Gitea and act_runner versions.
+- Native desktop notifications, tray mode and accessibility acceptance remain future work.

docs/RELEASE_NOTES_0.3.0.md

@@ -0,0 +1,140 @@
+# ForgeFlow 0.3.0 release notes
+
+Release date: 2026-07-24  
+Release type: self-service test release
+
+## Goal
+
+Version 0.3.0 closes the gap between a functional developer preview and a build
+that can be configured and tested by its owner without sharing credentials with
+a developer. The release concentrates on setup guidance, deterministic
+preflight checks, safe diagnostics and server-side allowlisting.
+
+## Setup and readiness
+
+- Replaced the lightweight onboarding with a five-step setup wizard.
+- Added a computer readiness preflight for Git, Git identity, writable app data,
+  writable diagnostics and OS credential encryption.
+- Added a Gitea validation stage before setup completion.
+- Added visible repository discovery results.
+- Added safe setup diagnostics before Gitea is connected.
+- Added a comprehensive start page and end-to-end setup guide.
+- Added a JSON-capable command-line doctor for local environment validation.
+
+## Deployment preflight
+
+A deployment now receives a visible preflight before confirmation and a second
+mandatory backend validation immediately before dispatch. Checks include:
+
+- linked local Git repository;
+- allowed deployment branch;
+- clean working tree;
+- configured upstream;
+- local/remote ahead and behind state;
+- exact full SHA on the remote branch;
+- local deploy and rollback workflow files;
+- remote workflow visibility through Gitea;
+- Gitea Actions API availability;
+- deployment status endpoint;
+- application health endpoint.
+
+Optional environment checks can warn without hiding required failures.
+Deployment cannot bypass the mandatory checks through the renderer.
+
+## Diagnostic logging
+
+- Added ordered structured JSONL logging in the Electron app-data directory.
+- Added daily files, size rotation and retention pruning.
+- Added configurable logging level, retention and file-size policy.
+- Added process, renderer, Git, repository, Gitea, IPC, preflight and deployment
+  diagnostics.
+- Added per-launch session IDs and per-operation deployment request IDs.
+- Added a no-throw logging design so diagnostic storage does not crash the app.
+- Added local clear and open-folder controls.
+
+## Secret and privacy protection
+
+- Added recursive sensitive-key detection, including camelCase variants.
+- Added bearer/basic/token/password/API-key/client-secret redaction.
+- Added runtime-secret replacement.
+- Added URL credential, token query parameter and private-key redaction.
+- Added common hosting-token pattern redaction.
+- Added user-home and source-root path aliases.
+- Added strict privacy mode with deterministic identifier hashing.
+- Stopped automatically ingesting or persisting raw runner logs; full output stays in Gitea.
+- Added fail-closed bundle auditing before the ZIP is written.
+- Added SHA-256 output for every generated support bundle.
+
+No Gitea token, SSH key or server password is needed by the developer to use
+these diagnostics.
+
+## Support bundle contents
+
+A support bundle can contain:
+
+- manifest and safety audit;
+- system and application version information;
+- sanitized public configuration;
+- sanitized repository state;
+- sanitized operation history;
+- latest preflight report;
+- safe diagnostic status;
+- redacted JSONL logs.
+
+It intentionally excludes protected token blobs, authorization headers,
+private keys, source files, Git diffs, environment dumps and raw runner output.
+
+## Server deployment hardening
+
+- Moved target definitions to a root-owned `/etc/forgeflow/targets.conf` file.
+- Added exact repository/environment allowlisting.
+- Made the server status URL mandatory and require matching SHA plus request ID before success.
+- Added configuration ownership and permission checks.
+- Added absolute and restricted path validation.
+- Added exact remote-SHA and branch ancestry validation.
+- Added per-target `flock` locking.
+- Added Docker Compose result and health verification.
+- Added current, previous, requested SHA, request ID and exit code to server
+  status output.
+- Added a restrictive sudoers template for the runner.
+- Added explicit deploy and rollback workflow request-ID inputs.
+- Added backend repository re-resolution so renderer-supplied paths and identities
+  cannot select an arbitrary local folder or Gitea repository.
+- Captured pre-dispatch Actions run IDs so polling cannot attach to an older run
+  with the same commit SHA.
+- Required repository, environment, live SHA, requested SHA, request ID, zero
+  server exit code and explicit health success before marking a release complete.
+- Restricted rollback to the exact previous SHA currently reported by the server
+  status endpoint.
+
+## User interface
+
+- Added a dedicated Diagnostics workspace.
+- Added system and deployment preflight presentation.
+- Added diagnostic policy controls.
+- Added Standard and Strict support-bundle export.
+- Added support-bundle checksum and reveal action.
+- Added readiness explanations to onboarding.
+- Replaced duplicate sidebar navigation with a compact safe-diagnostics state.
+
+## Validation
+
+- 39 required project files validated.
+- 35 JavaScript files passed syntax checks.
+- 36 of 36 automated tests passed.
+- Two real temporary Git remotes remain part of the integration suite.
+- New tests cover redaction, diagnostic rotation/export, support ZIP generation,
+  fail-closed safety auditing, preflight and Gitea workflow-file checks.
+
+## Known boundaries
+
+- The release is not code-signed.
+- A platform-native installer is not guaranteed by the source ZIP alone.
+- The private Gitea, runner and server environment still requires the documented
+  local acceptance test.
+- Application-specific compose commands and health endpoints remain target
+  configuration, because they cannot be inferred safely.
+- No redactor can mathematically identify an arbitrary unknown secret printed by
+  custom third-party code; raw runner logs therefore remain only in the trusted
+  Gitea Actions interface, and exported bundles should still be inspected before
+  sharing.

docs/RELEASE_NOTES_0.3.1.md

@@ -0,0 +1,25 @@
+# ForgeFlow 0.3.1 release notes
+
+## Windows environment-doctor hotfix
+
+Version 0.3.1 fixes a Windows-only false negative in the environment doctor.
+The setup script could invoke npm successfully, install all dependencies and then
+report `spawn npm ENOENT` from Node.js. Windows exposes npm through a command
+shim (`npm.cmd`), which cannot always be executed directly through
+`child_process.execFile`.
+
+The doctor now:
+
+- uses `npm_execpath` through the active Node executable when launched by npm;
+- falls back to `cmd.exe /c npm --version` on Windows;
+- continues to invoke npm directly on Linux and macOS;
+- reports which safe invocation path succeeded;
+- reads its displayed application version from `package.json` instead of a
+  duplicated hard-coded value.
+
+Three regression tests cover npm-script execution, the Windows command-shim
+fallback and the normal non-Windows path.
+
+The npm deprecation messages printed during dependency installation are warnings
+from transitive build-tool dependencies. They were not the cause of the setup
+failure and do not prevent ForgeFlow from starting.

docs/RELEASE_NOTES_0.3.2.md

@@ -0,0 +1,72 @@
+# ForgeFlow 0.3.2 release notes
+
+## Automatic clone destinations
+
+The normal **Clone from Gitea** action no longer opens a Windows folder picker
+for every repository. ForgeFlow now:
+
+1. uses the first configured project root as the default;
+2. derives a safe folder name from the repository clone URL;
+3. creates `<project-root>/<repository-name>`;
+4. clones into that folder;
+5. validates the resulting Git repository;
+6. saves the repository mapping;
+7. starts monitoring the working tree;
+8. opens the linked repository in ForgeFlow.
+
+Example:
+
+```text
+Default project root: C:\Users\your-name\Projects
+Gitea repository:     Jens/Portfolio
+Automatic target:     C:\Users\your-name\Projects\Portfolio
+```
+
+A separate **Choose another location** action remains available for exceptional
+cases. That choice selects a parent project root; ForgeFlow still creates the
+repository-named subfolder itself.
+
+## Existing-folder safety
+
+The clone backend now inspects the automatic target before running Git:
+
+- a missing target is created through `git clone`;
+- an existing empty directory is accepted;
+- an existing Git checkout with the same normalized origin is linked;
+- a different Git repository is blocked;
+- an ordinary non-empty directory is blocked;
+- a file at the target path is blocked.
+
+ForgeFlow never silently overwrites a conflicting folder and does not create a
+duplicated `Repository\Repository` directory.
+
+## Security and consistency
+
+The renderer no longer supplies a free-form remote URL or clone destination to
+the privileged Git operation. It sends the Gitea repository identity and a
+location mode. The main process then:
+
+- resolves the current repository again from Gitea;
+- selects the configured root or a native-dialog result;
+- calculates the destination itself;
+- performs conflict checks;
+- clones or reuses the checkout;
+- persists the mapping atomically.
+
+Clone diagnostics contain repository identity, target, branch and commit state,
+but no Gitea token or authorization header.
+
+## Validation
+
+Version 0.3.2 contains 45 passing automated tests. New coverage includes:
+
+- HTTPS and SSH repository folder-name derivation;
+- automatic target construction;
+- missing and empty target handling;
+- same-origin checkout reuse;
+- different-repository rejection;
+- non-empty ordinary-folder rejection;
+- file-at-target rejection.
+
+Existing Git, deployment, diagnostics, redaction, rollback and Windows doctor
+tests continue to pass.

docs/RELEASE_NOTES_0.4.0.md

@@ -0,0 +1,57 @@
+# ForgeFlow 0.4.0 release notes
+
+## Scrollable change list
+
+The changed-file panel now has an independent bounded vertical scroll area. Large commits no longer make lower files unreachable.
+
+## Commit readiness
+
+The action panel now labels the commit message as required and displays the exact reason why commit actions are disabled. Selected files are staged automatically during commit; manual staging remains available as an optional index-review step.
+
+## ITWorx.tech branding
+
+The supplied ITWorx.tech logo is integrated into the title bar, first-run setup and application icons.
+
+## Built-in source updater
+
+ForgeFlow can check the configured private Gitea repository, defaulting to `Jens/ForgeFlow` on `main`.
+
+The updater:
+
+- reads the remote `package.json` at an exact branch commit;
+- compares semantic versions;
+- downloads an authenticated exact-SHA archive;
+- verifies a SHA-256 checksum;
+- closes ForgeFlow;
+- backs up the current source;
+- installs dependencies;
+- runs the complete quality gate;
+- restores the previous source when validation fails;
+- restarts ForgeFlow.
+
+## SSH / Unraid deployment
+
+A server can be configured once with hostname, SSH port, username, encrypted credentials and `/mnt/user/appdata` as base path.
+
+Deployment profiles support:
+
+- existing Git-backed application folders;
+- automatic new folder creation;
+- exact commit verification;
+- pinned SSH host identity;
+- existing or generated Compose configuration;
+- host and container ports;
+- Unraid Web UI and icon labels;
+- server-folder mapping;
+- tracked-change blocking;
+- nested-Git warnings;
+- runtime-data preservation;
+- rollback to the previous SHA.
+
+## Deployment migration example
+
+The documented migration flow keeps the root Git checkout and maintained Compose file in place, verifies the complete commit SHA and treats a stale nested `source/` checkout as separate, controlled cleanup.
+
+## Validation
+
+ForgeFlow 0.4.0 has 59 passing automated tests, including real temporary Git remotes, update exact-SHA checks, SSH path safety, renderer workflow contracts, diagnostics redaction, exact previous-SHA rollback enforcement and deployment controls.

docs/RELEASE_NOTES_0.4.1.md

@@ -0,0 +1,26 @@
+# ForgeFlow 0.4.1 release notes
+
+## Windows Bash path fix
+
+ForgeFlow 0.4.1 fixes the source quality gate on Windows when the project is stored at a path such as `C:\Projects\ForgeFlow`.
+
+The previous verifier passed an absolute Windows path directly to `bash -n`. Bash interpreted the backslashes as escape characters, producing a collapsed path such as `C:ProjectsForgeFlow...` and a false validation failure.
+
+The verifier now starts Bash with the ForgeFlow project root as its working directory and passes the deployment example as a relative POSIX path:
+
+```text
+examples/server/forgeflow-deploy
+```
+
+This keeps the project root separate from the script argument and works across Windows Git Bash, Linux and macOS.
+
+## Regression coverage
+
+New automated coverage verifies that:
+
+- a Windows project root remains in `cwd`;
+- no drive letter or backslash is passed as the Bash script argument;
+- absolute and escaping script paths are rejected;
+- Bash validation succeeds from a project root containing spaces.
+
+No Gitea token, repository mapping, SSH credential, deployment profile or diagnostic history is changed by this update.

docs/RELEASE_NOTES_0.4.2.md

@@ -0,0 +1,29 @@
+# ForgeFlow 0.4.2
+
+## Windows Git Bash reliability hotfix
+
+This release fixes the two remaining Windows-only failures, including the temporary-directory lock seen during cleanup while validating the 0.4.1 recovery update.
+
+### Remote shell transport
+
+SSH / Unraid scripts are now sent through a single-line base64 transport and decoded by Bash on the server. This removes nested quote parsing from the transport layer and prevents Git Bash from misreading multiline commands, single quotes, or newline-stripping expressions.
+
+The generated command contains no raw multiline payload. The decoded script still enables strict shell mode, disables interactive Git prompts, and requires batch-mode SSH for server-side Git operations.
+
+### Temporary-directory lock cleanup
+
+The Bash syntax regression test now retries cleanup when Windows briefly retains a working-directory handle after `bash -n` exits. A successful syntax validation is no longer reported as failed solely because of a short-lived `EBUSY`, `EPERM`, or `ENOTEMPTY` cleanup condition.
+
+### Additional correction
+
+The remote status reader now invokes `base64` with the status filename in the correct argument position before stripping CR/LF characters.
+
+## Regression coverage
+
+Coverage verifies:
+
+- Windows Git Bash execution from a project root containing spaces;
+- a single-line base64 transport for generated Unraid inspection commands;
+- preserved runtime-path inspection without nested quoting failures;
+- strict, non-interactive server-side Git settings after decoding;
+- safe rollback to ForgeFlow 0.4.0 when an update validation fails.

docs/RELEASE_NOTES_0.4.3.md

@@ -0,0 +1,9 @@
+# ForgeFlow 0.4.3
+
+## Full clean release
+
+- Replaced the OS-dependent local Bash/Windows-temp-path Unraid inspection test with a platform-independent mocked SSH inspection contract.
+- The SSH inspection command is still verified to use Base64 transport and the returned Unraid metadata is parsed and evaluated deterministically.
+- Removed the false Windows failure where a local temporary path was interpreted as a remote Linux path.
+- Regression coverage confirms preserved runtime paths, nested Git directories, `.dockerignore` handling, and remote target resolution.
+- This release is distributed as a complete source package rather than another incremental updater.

docs/RELEASE_NOTES_0.4.4.md

@@ -0,0 +1,9 @@
+# ForgeFlow 0.4.4
+
+## Correct Git change handling
+
+- Deleted files are staged with `git add -A` and are removed from Gitea after commit and push.
+- Renames include both the new path and original path when staging or unstaging selected changes.
+- A failed staging action always reloads the real repository state so changes remain visible.
+- When commit succeeds but push failed, ForgeFlow clears obsolete file selection and shows the clean working tree as an ahead branch with a dedicated retry push action.
+- Added real bare-remote regression tests for deleted files, renames, and push-after-commit failure recovery.

docs/RELEASE_NOTES_0.4.5.md

@@ -0,0 +1,8 @@
+# ForgeFlow 0.4.5
+
+## Git staging correctness
+
+- Fixes committing and pushing a deleted file after it was already staged manually.
+- Already staged deletions and renames are no longer passed to `git add -A` a second time.
+- Only selected records that still contain unstaged worktree changes are restaged.
+- Adds a real bare-remote regression test using `silent-zebra-glow.zip`.

docs/RELEASE_NOTES_0.5.0.md

@@ -0,0 +1,14 @@
+# ForgeFlow 0.5.0
+
+## Reliability and viewport release
+
+- All dialogs are constrained to the visible desktop viewport. Long deployment configuration and preflight content scrolls independently while the action footer remains available.
+- Large partial selections use Git's NUL-delimited `--pathspec-from-file` interface instead of thousands of command-line arguments. This removes Windows `ENAMETOOLONG` failures.
+- Mutating Git operations are serialized per repository, preventing ForgeFlow background actions from competing for `.git/index.lock`.
+- Added explicit stale index-lock inspection and repair APIs.
+- Added one-click normalization of every linked repository origin to the current Gitea SSH URL, replacing legacy aliases and renamed owners without changing files or commits.
+- Source updater remains exact-commit pinned and runs the full quality gate before restart.
+
+## Upgrade test
+
+Push the extracted source to `Jens/ForgeFlow` with package version `0.5.0`. A running 0.4.5 source installation can then use Settings → Updates → Check now → Download update → Apply & restart.

docs/RELEASE_NOTES_0.5.1.md

@@ -0,0 +1,16 @@
+# ForgeFlow 0.5.1
+
+## Windows publication reliability
+
+- Validates the server deployment shell script through Bash standard input instead of passing a Windows working directory to Bash.
+- Removes the Git Bash versus WSL path ambiguity that caused a blank-error quality-gate failure from Downloads.
+- Adds regression coverage proving shell validation no longer depends on a Windows path or a path containing spaces.
+- Retains all v0.5.0 viewport, Git batching, remote normalization, repository serialization and password-form fixes.
+
+Publish the extracted source to `Jens/ForgeFlow` with package version `0.5.1`. A running older source installation can then discover and apply it through the built-in updater.
+
+## Carried forward from 0.5.0
+
+- Responsive viewport handling keeps long modals and their actions reachable.
+- Large Git selections continue to use `--pathspec-from-file` with NUL separation.
+- Mutating Git work remains serialized per repository.

docs/RELEASE_NOTES_0.5.2.md

@@ -0,0 +1,11 @@
+# ForgeFlow 0.5.2
+
+## Windows publication and update reliability
+
+- Removes the external Bash executable as a Windows publication/update prerequisite.
+- Always performs deterministic structural validation of the Linux/Unraid deployment script.
+- Runs GNU Bash `-n` syntax validation on non-Windows hosts and Linux CI.
+- Prevents Git Bash, WSL launcher, or another `bash.exe` shim from blocking a valid Windows release.
+- Keeps all ForgeFlow 0.5.0 and 0.5.1 viewport, Git batching, remote normalization, serialized per repository, lock handling, SSH form, and updater improvements.
+
+The release retains the viewport fixes, Git `--pathspec-from-file` batching, and Git mutations serialized per repository from 0.5.0/0.5.1.

docs/RELEASE_NOTES_0.5.3.md

@@ -0,0 +1,20 @@
+# ForgeFlow 0.5.3
+
+## Confirmed source-update handoff
+
+- ForgeFlow writes a launch request and waits for an external PowerShell **STARTED marker** before closing.
+- A helper launch failure or timeout leaves ForgeFlow open and surfaces the real error.
+- The updater records structured lifecycle state alongside the detailed update log.
+- Successful installation remains valid even when automatic restart is unavailable.
+- The next manual start shows a **visible update result** for success, failure, or rollback.
+- The PowerShell helper uses the absolute Windows PowerShell executable where available.
+- Success and rollback both attempt an **automatic restart**, with the result persisted for diagnosis.
+
+## Included 0.5.x reliability improvements
+
+- viewport-safe, scrollable deployment and settings dialogs;
+- sticky modal action bars;
+- large Git selections through NUL-delimited pathspec input;
+- serialized repository mutations;
+- SSH password-form persistence correction;
+- origin normalization and stale-index-lock repair.

docs/RELEASE_NOTES_0.5.4.md

@@ -0,0 +1,10 @@
+# ForgeFlow 0.5.4
+
+This release repairs the first real SSH / Unraid deployment path.
+
+- Preflight now verifies **Unraid → Gitea access** with the exact configured clone URL before deployment can start.
+- SSH deployments run as a **background deployment** operation; the interface returns immediately and polls the real operation state.
+- Failed SSH or Docker operations are written back as terminal failed operations instead of leaving the UI indefinitely active.
+- Compose service and container casing are preserved, so the requested name **Portfolio** remains Portfolio.
+- Generated Compose no longer forces service names to lowercase.
+- Deployment status refreshes automatically until success or failure.

docs/RELEASE_NOTES_0.6.0.md

@@ -0,0 +1,61 @@
+# ForgeFlow 0.6.0
+
+ForgeFlow 0.6.0 is a product-level reliability release for Git recovery, SSH / Unraid deployment truth, DockerMan integration, source updating and high-contrast ITWorx branding.
+
+## Git operations that recover themselves
+
+- Every mutating Git action is serialized per repository.
+- A Git lock error triggers a conservative stale-lock scan, a short grace period for very recent locks, safe removal and automatic retry when ForgeFlow can prove that no matching process is active.
+- The scanner resolves the actual Git directory and covers `HEAD.lock`, `index.lock`, ref locks and worktree locks while skipping Git object/LFS storage.
+- The Git tools page now provides repository-specific troubleshooting instead of generic terminal advice.
+- Available automated actions are selected from the actual branch state: fetch, fast-forward, push, origin repair and divergence recovery.
+- Divergence recovery creates a `forgeflow/backup-<branch>-<timestamp>` safety branch before resetting the current branch to upstream.
+
+## Deployment truth instead of stuck spinners
+
+- SSH / Unraid operations are reconciled with the live Git SHA, container state and health.
+- Startup deployment reconciliation converts an interrupted but successful deployment to `success` and refreshes repository cards immediately.
+- Stale operations are marked failed instead of remaining indefinitely in `running`.
+- Deployment cards provide **Reconcile**, **Open Web UI** and **Repair DockerMan integration** actions.
+- Background completion broadcasts update the renderer and trigger repository refresh.
+
+
+- A successful remote Compose run is marked terminal before the secondary Unraid inspection, so a slow refresh can no longer leave the UI stuck in deployment mode.
+- Startup and manual refresh reconcile every configured environment and suppress a new Deploy action when the exact healthy SHA is already live.
+- The Deployments page can repair all running containers that are missing DockerMan WebUI/icon metadata in one controlled batch.
+
+## DockerMan integration
+
+- ForgeFlow applies `net.unraid.docker.managed=dockerman`, `net.unraid.docker.webui`, `net.unraid.docker.icon` and `net.unraid.docker.shell` through a controlled Compose override.
+- WebUI labels use Unraid's `[IP]` and `[PORT:<host-port>]` placeholders.
+- Internal Compose project, service and image identities are lowercase-safe while the visible container name can remain `Portfolio`.
+- The built-in high-contrast ITWorx mark is the default DockerMan icon for new or migrated SSH profiles.
+- A user can instead select a local PNG, use an HTTP(S) PNG URL or disable the icon.
+- Built-in/uploaded PNGs are copied persistently to DockerMan's image storage under `/boot/config/plugins/dockerMan/images`.
+- ForgeFlow writes a persistent `templates-user/my-<container>.xml` fallback so WebUI and icon metadata remain available when label caching is unreliable.
+- Known DockerMan icon caches and the volatile metadata cache are invalidated after container recreation so changes can be re-read.
+
+## SSH and server-side safety
+
+- Unraid-to-Gitea access remains part of preflight before any deployment starts.
+- SFTP directory creation now distinguishes existing directories from permission and path errors instead of treating every generic SFTP failure as success.
+- Repository Compose files receive the same metadata and exact-SHA controls as generated Compose files.
+- Tracked server-side modifications continue to block deployment and rollback.
+
+## Source updater and publication
+
+- The PowerShell update helper starts directly with `param(`, without a UTF-8 BOM or stray leading character.
+- ForgeFlow waits for a structured `started` marker before closing the running application.
+- Update application performs backup, exact archive checksum validation, source replacement, lockfile-based `npm ci` when available and the complete quality gate.
+- Success, restart failure and rollback status are persisted and shown on the next launch.
+- Automatic restart launches the installed Electron executable directly, avoiding the unreliable detached `npm start` handoff.
+- The publishing script runs the quality gate, mirrors a clean source tree and verifies that Gitea reports the exact pushed release commit.
+
+## Branding
+
+- The title bar, setup flow, desktop icon and installer artwork use the newly supplied higher-contrast ITWorx.tech logo.
+- The cloud/check mark was recropped to remove wordmark fragments and remain legible at small icon sizes.
+
+## Verification
+
+The release includes real Git integration coverage for large selections, staged deletions, failed pushes, `HEAD.lock`, object-store exclusion and backup-before-reset divergence recovery. It also covers DockerMan labels and XML fallback, built-in icon upload, cache invalidation, operation reconciliation, viewport-safe dialogs and updater lifecycle behavior.

docs/RELEASE_NOTES_0.6.1.md

@@ -0,0 +1,10 @@
+# ForgeFlow 0.6.1
+
+## Windows source updater reliability
+
+- Fixes the Windows PowerShell 5.1 STARTED-handshake failure caused by replacing an already existing status file with `Move-Item -Force`.
+- Uses `System.IO.File.Replace` with an overwrite-copy fallback for deterministic status persistence.
+- Adds a handshake-only verification mode used by the local bootstrap overlay.
+- Keeps ForgeFlow open when startup cannot be proven and now includes the helper log tail in the visible error.
+- Requires the status `updateId` to match the current request, preventing an old status file from being accepted.
+- Records the actual restart PID after a successful update or rollback.

docs/RELEASE_NOTES_0.7.0.md

@@ -0,0 +1,47 @@
+# ForgeFlow 0.7.0
+
+## Existing deployment adoption
+
+ForgeFlow can now import an existing Unraid deployment directly from the server. The server is treated as the source of truth instead of relying on guessed defaults.
+
+The discovery pass reads:
+
+- the server-side Git checkout, origin, branch and live commit;
+- the actual Compose file and normalized `docker compose config --format json` output;
+- running and stopped containers through `docker inspect`;
+- every detected port mapping, mount, network and environment-variable name;
+- Compose project and service labels;
+- image, restart policy and healthcheck metadata;
+- the matching Unraid DockerMan XML template, including WebUI, icon and shell metadata.
+
+The primary values are imported into the deployment form. The complete multi-service and multi-port runtime description is retained as detected metadata. Imported values remain editable as explicit user overrides.
+
+ForgeFlow no longer invents a host port, container port, service name, WebUI or icon when the server does not report one.
+
+## One-click troubleshooter
+
+Diagnostics now contains a general troubleshooter that scans all linked repositories and SSH/Unraid deployment profiles.
+
+Safe one-click repairs cover:
+
+- interrupted rebase, merge, cherry-pick and revert operations;
+- stale Git lock files;
+- clean fast-forward synchronization;
+- unpublished local commits;
+- refresh and recalculation of repository truth.
+
+Diverged branches are treated as an explicit higher-impact repair. ForgeFlow creates a safety branch before resetting to the upstream version and never includes that action in the automatic safe-repair batch.
+
+The troubleshooter also reports non-automatic issues such as tracked server-side changes, missing deployment folders, SSH inspection failures and missing Docker context exclusions.
+
+## Reliability fixes
+
+- Unraid DockerMan WebUI templates such as `http://[IP]:[PORT:1223]/` are now accepted and preserved.
+- Configuration writes are serialized so an older concurrent save cannot overwrite a newer snapshot.
+- A malformed configuration file is preserved as a timestamped `.corrupt-*` file and replaced with safe defaults instead of making ForgeFlow unstartable.
+- Source verification now handles Windows CRLF manifests correctly.
+- Existing deployment metadata stores field provenance, detection time and server-source-of-truth status.
+
+## Validation
+
+The release includes real Git integration coverage for aborting an interrupted merge and server-discovery mapping coverage for Compose, Docker inspect and DockerMan metadata.

docs/RELEASE_NOTES_0.8.0.md

@@ -0,0 +1,10 @@
+# ForgeFlow 0.8.0
+
+- Select and stage individual diff hunks without staging the remainder.
+- Guide interrupted merge, rebase, cherry-pick and revert resolution.
+- Read Gitea branch protection and create pull requests.
+- Open configurable editors and terminals without a shell.
+- Enforce freezes, maintenance windows, release notes and reasoned overrides.
+- Export append-only audits and credential-free encrypted configuration backups.
+- Provide native notifications, tray, close-to-tray and start-at-login.
+- Run guarded read-only, deployment and rollback acceptance checks.

docs/RELEASE_NOTES_0.8.1.md

@@ -0,0 +1,13 @@
+# ForgeFlow 0.8.1
+
+ForgeFlow 0.8.1 is a premium UX and connection-assurance release.
+
+## Highlights
+
+- A more deliberate desktop design system with refined hierarchy, depth, typography, focus states and responsive density.
+- Repository settings now show live open Gitea pull requests and link directly to them.
+- `npm run connections:check` validates the installed DPAPI-protected token against the Gitea user, ForgeFlow repository and Actions APIs without printing credentials.
+- Reduced-motion preferences are respected throughout the interface.
+- Windows packaging and compact-window behavior are revalidated after the visual redesign.
+
+The existing token and SSH private key remain local and are never copied into logs, backups or release artifacts.

docs/RELEASE_NOTES_0.8.2.md

@@ -0,0 +1,11 @@
+# ForgeFlow 0.8.2
+
+ForgeFlow 0.8.2 activates binary auto-update for packaged Windows releases.
+
+- Installed builds download the matching NSIS installer from the authenticated Gitea release.
+- Portable builds download and safely replace the original portable executable.
+- Every executable requires a separately published SHA-256 sidecar and is verified again immediately before installation.
+- The updater runs outside ForgeFlow, waits for the old process to exit and records a durable success, failure or rollback result.
+- Release publishing verifies that local `HEAD` equals `origin/main` before uploading artifacts.
+
+Users of 0.8.1 or older must install 0.8.2 once manually. Updates after 0.8.2 can use the built-in updater.

docs/RELEASE_NOTES_0.8.3.md

@@ -0,0 +1,13 @@
+# ForgeFlow 0.8.3
+
+ForgeFlow 0.8.3 refreshes the complete light appearance with richer surfaces,
+subtle color, clearer depth and stronger active states.
+
+Deployment cards now lead with the exact container identity, repository,
+environment and a stable visual accent. Live and Gitea commits are shown side by
+side, with an explicit confirmation when both sources agree.
+
+Deployment reconciliation now revisits stale failed records. When the requested
+commit is healthy on Unraid it is corrected to success. When a newer commit is
+both live and current on Gitea, the old failure is marked as superseded instead
+of remaining an apparently current incident.

docs/RELEASE_NOTES_0.8.4.md

@@ -0,0 +1,10 @@
+# ForgeFlow 0.8.4
+
+ForgeFlow 0.8.4 adds interactive project illustrations where they reinforce the
+release story. The overview now visualizes commits travelling through a release
+topology, with animated status nodes and cursor-responsive depth.
+
+Repository headers reuse the same visual language as a subtle animated
+watermark. Illustrations adapt to light and dark themes, collapse gracefully at
+compact widths and disable non-essential movement when reduced motion is
+requested by the operating system.

docs/RELEASE_NOTES_0.8.5.md

@@ -0,0 +1,11 @@
+# ForgeFlow 0.8.5
+
+ForgeFlow 0.8.5 fixes packaged update downloads for Gitea instances whose
+release metadata reports a public asset URL with a different scheme or origin.
+
+The updater now ignores that mutable browser URL and downloads each release
+asset through its immutable asset ID on the configured, trusted Gitea origin.
+Authentication tokens remain protected and are never sent to another host.
+
+Install 0.8.5 manually when upgrading from 0.8.4 because the affected download
+path runs before the new updater code can be installed.

docs/RELEASE_NOTES_0.8.6.md

@@ -0,0 +1,14 @@
+# ForgeFlow 0.8.6
+
+ForgeFlow 0.8.6 gives the changes workspace a richer, more purposeful visual
+identity. Unused diff-canvas space now presents a contextual animated code map
+that reflects the selected file type and its additions and removals.
+
+Subtle travelling signals, floating status nodes and pointer-responsive depth
+bring the canvas to life while keeping every diff line fully readable. Dense
+diffs automatically reduce the illustration's presence, and narrow panes hide
+it entirely when there is no useful room.
+
+The changed-file list also gains clearer state chips, stronger active-file
+hierarchy and refined hover feedback. All effects support light and dark themes
+and respect the operating system's reduced-motion preference.

docs/RELEASE_NOTES_0.8.7.md

@@ -0,0 +1,22 @@
+# ForgeFlow 0.8.7
+
+ForgeFlow 0.8.7 automatically discovers applications already running on every
+configured and trusted Unraid server. It inventories server-side Git checkouts,
+Docker Compose metadata, bind mounts, container identity and image provenance,
+then links each workload to a Gitea repository only when the evidence produces
+one unambiguous match.
+
+Uniquely matched workloads are added to Deployments automatically, even when
+they were originally deployed outside ForgeFlow. Every refresh resolves the
+configured branch directly on Gitea and compares its full commit SHA with the
+live server version. A deployment is reported as in order when the SHAs match,
+the container is running and Docker health is not failing.
+
+Containers without a server-side Git checkout can also be discovered when the
+image exposes standard OCI source/revision labels or ForgeFlow provenance
+labels. New ForgeFlow deployments now write repository, branch and exact commit
+labels so future discovery remains deterministic.
+
+Ambiguous or weak matches are intentionally left unlinked for manual review.
+Server inventory is read-only; automatic adoption changes only ForgeFlow's local
+configuration.

docs/RELEASE_NOTES_0.8.8.md

@@ -0,0 +1,13 @@
+# ForgeFlow 0.8.8
+
+ForgeFlow 0.8.8 fixes the HTTP 404 returned while downloading packaged updates
+from the configured Gitea server.
+
+The server's API requires release attachments to be addressed using both the
+immutable release ID and attachment ID. ForgeFlow now uses that exact
+release-scoped endpoint for the executable and its checksum file.
+
+Strict same-origin token protection and SHA-256 verification remain unchanged.
+Install 0.8.8 manually when upgrading from 0.8.7 because the affected download
+code runs before the corrected updater can be installed. Future packaged
+updates can again be completed from inside ForgeFlow.

docs/RELEASE_NOTES_0.8.9.md

@@ -0,0 +1,20 @@
+# ForgeFlow 0.8.9
+
+ForgeFlow 0.8.9 introduces Git Validator, a dedicated repository assurance
+workspace that checks whether practical Git and Gitea best practices are being
+followed.
+
+The validator produces a weighted score with evidence for repository identity,
+upstream tracking, working-tree state, effective commit identity, safe local
+synchronization defaults, default-branch and force-push protection, README and
+gitignore hygiene, tracked secret-shaped filenames and oversized tracked files.
+
+Every repair is deliberately bounded. Origin alignment and repository-local
+fetch/pull/autostash safeguards can be applied as safe fixes. Creating default
+branch protection or a recommended `.gitignore` requires explicit confirmation.
+The generated `.gitignore` remains uncommitted for review, and secret/history
+findings are never modified automatically.
+
+The new workspace includes grouped findings, an assurance score, safe-fix
+batching, audit events, interactive project illustration and responsive premium
+layouts for light and dark themes.

docs/RELEASE_NOTES_0.9.0.md

@@ -0,0 +1,30 @@
+# ForgeFlow 0.9.0
+
+ForgeFlow 0.9.0 changes Unraid deployments from a Git-checkout-first workflow into a server-inventory-first workflow.
+
+## Existing installations are now visible
+
+Server Inventory collects a safe, selected subset of Docker, Compose and DockerMan metadata for both running and stopped containers. It recognizes Compose project names, working directories, active Compose files and services, mounts, ports, runtime state, image provenance and existing DockerMan templates. Environment values and other container secrets are not collected.
+
+Exact repository provenance may be linked automatically. Name similarity is never treated as proof: uncertain workloads remain visible as suggestions and can be linked through the new manual wizard. The saved link preserves the workload identity rather than depending on the disposable container ID.
+
+## Push bundle is the new default
+
+New SSH/Unraid profiles use **Push bundle**. ForgeFlow creates a tar archive from the exact local Git commit, calculates its SHA-256 digest and uploads it over the already trusted desktop-to-Unraid SSH connection. Unraid therefore does not need a Git client, Gitea host-key entry or Gitea private key for this mode.
+
+The server verifies the checksum and archive paths, rejects symlink payloads, preserves configured runtime paths, updates only ForgeFlow-managed files and validates the merged Compose model before starting services. The active SHA and managed-file manifest are promoted atomically only after the expected services are running. Failure restoration keeps the previous deployment truth and restores overwritten files and Compose metadata.
+
+**Server-side Git** remains available as an explicit mode. Its Gitea access check is now reported separately from desktop SSH and Docker/Compose capabilities. **Monitor only** links an existing workload without granting ForgeFlow permission to deploy it.
+
+## Safer adoption
+
+Adopted workloads retain their existing Compose project, Compose files and service set. ForgeFlow no longer overrides their image or container name in the metadata overlay. Existing DockerMan templates are left untouched; generated templates are managed only for explicitly generated Compose profiles. `--force-recreate` and `--remove-orphans` are opt-in rather than defaults.
+
+A deployment lock records the live shell process, and an old lock is removed only when it is sufficiently old and its owner no longer runs. Deployment output truncation now fails explicitly instead of allowing ForgeFlow to interpret an incomplete inventory or command result.
+## Release publication correction
+
+- The standard release publisher now publishes the validated source and matching Windows binary assets as one workflow.
+- Added `Publish-Missing-Binary-Release.ps1` to repair a source-only Gitea release without reinstalling ForgeFlow manually.
+- Binary publication now derives the repository owner, repository name and branch from ForgeFlow settings instead of hardcoding them.
+- Missing-release errors now explain that packaged installations require both Windows executables and their SHA-256 sidecars.
+

docs/RELEASE_NOTES_0.9.1.md

@@ -0,0 +1,10 @@
+# ForgeFlow 0.9.1
+
+## Gitea binary updater repair
+
+- Downloads the actual release attachment through `browser_download_url` instead of treating the Gitea attachment metadata response as an executable.
+- Keeps the Gitea token on the configured Gitea origin and follows HTTPS object-storage redirects without leaking credentials.
+- Adds regression coverage for attachment metadata lookup, direct browser download URLs and cross-origin redirect safety.
+- Improves diagnostics when an older updater receives JSON attachment metadata.
+
+Because ForgeFlow 0.8.9 and 0.9.0 contain the broken attachment endpoint, upgrading to 0.9.1 requires one manual installer run. in-app updates work normally again after 0.9.1 is installed.

docs/RELEASE_NOTES_0.9.2.md

@@ -0,0 +1,10 @@
+# ForgeFlow 0.9.2
+
+## Emergency deployment and discovery repair
+
+- Existing deployment profiles without an explicit mode migrate to **Push bundle**, never Server-side Git.
+- Push bundle deploys the clean, committed local HEAD directly over SSH/SFTP and never requires a Gitea key, upstream, remote sync, or Git on Unraid.
+- Desktop-to-Unraid authentication can use the server password; a failed key opens a password recovery flow instead of blocking deployment.
+- Server inventory scans `docker ps -a`, complete Docker inspect data, Compose projects, and every DockerMan user template, including stopped and template-only workloads.
+- Inventory connection failures are shown as failures rather than misleading zero counts.
+- Existing Compose and DockerMan workloads can be linked manually without restarting or modifying them.

docs/RELEASE_NOTES_0.9.3.md

@@ -0,0 +1,25 @@
+# ForgeFlow 0.9.3
+
+This release removes server-side repository authentication from every SSH/Unraid deployment path and makes server Compose files the primary discovery source.
+
+## Direct deployment only
+
+- Every existing SSH/Unraid deployment profile is migrated to **Direct copy**, except profiles explicitly marked **Monitor only**.
+- Deployment and rollback archive the exact committed local HEAD, upload it over the already configured desktop-to-Unraid connection and run Docker Compose on Unraid.
+- Preflight contains no Unraid-to-repository access probe, no remote `git ls-remote`, no repository-key validation and no Git requirement on Unraid.
+- Password authentication for the desktop-to-Unraid connection remains supported and is independent of repository access.
+
+## Compose-file inventory and automatic linking
+
+- Server Inventory scans Compose YAML files such as `compose.yml`, `compose.yaml`, `docker-compose.yml`, `docker-compose.yaml`, overrides and stack YAML files below the configured appdata roots.
+- YAML discovery still runs when Docker inspection fails or Docker is unavailable, so a container-query problem no longer produces a false empty inventory.
+- ForgeFlow reads the Compose project name, file set, service names and image names from the server.
+- A unique high-confidence repository match based on both Compose folder and project identity is linked automatically.
+- Remaining strong matches use a one-click link action with server folder, Compose project, Compose files, services, container identity and preservation paths already filled in.
+- Runtime containers, stopped containers and DockerMan templates are merged with the YAML definition when available. `/mnt/user/appdata`, `/mnt/cache/appdata` and disk-backed appdata paths are treated as the same logical deployment location.
+
+## Reliability
+
+- The inventory shell script is safe under `set -euo pipefail`; Docker or Compose command failures are captured as warnings instead of aborting the scan.
+- Large runtime, cache, log and database folders are pruned while searching for Compose files.
+- A failed inventory operation remains visible as an error and is never presented as zero workloads.

docs/RELEASE_NOTES_0.9.4.md

@@ -0,0 +1,7 @@
+# ForgeFlow 0.9.4
+
+ForgeFlow now treats the real Compose files discovered on Unraid as the only activation source for adopted workloads. A generated labels fragment is no longer merged into an imported project, so stale service hints such as `geointel` cannot create a phantom service without an image or build context.
+
+Direct copy redeployments always use `--force-recreate`. The runtime service list comes from `docker compose config --services`, not from manually stored service names. Before activation ForgeFlow records the existing container ID for every service; after activation it verifies that each service is running, not unhealthy, and uses a different container ID.
+
+ForgeFlow also rejects the deployment when Compose starts a duplicate workload while leaving the previous container running. The new SHA is written only after these checks pass. Existing DockerMan templates and the real Compose files remain untouched.

docs/RELEASE_NOTES_0.9.5.md

@@ -0,0 +1,11 @@
+# ForgeFlow 0.9.5
+
+ForgeFlow 0.9.5 makes Direct copy deployments fail closed and adds an in-app repair for Unraid write permissions.
+
+Before a bundle is created or uploaded, ForgeFlow probes the linked project folder, `.forgeflow` upload/state folders and every active Compose file using the configured SSH identity. A failed check names the exact path, user, owner, group and mode. Deployment stops before file transfer and before any Docker or Compose command changes the runtime. The same write-access check runs again immediately before upload to prevent a stale preflight result.
+
+Every SSH / Unraid deployment card now includes **Check / fix write access**. The same action appears beside a blocking preflight result. It normalizes the linked source tree and ForgeFlow state folders to safe shared access, uses the Unraid `users` group where available and preserves existing executable bits. Configured runtime locations such as `.env`, `appdata`, `data`, `config`, `logs`, mounted data paths and common generated dependency folders are excluded. It never runs Docker, stops a container, removes a container or uses `chmod 777`. The action also runs when the SSH account is root so manual SMB/file-copy access can be repaired, not only ForgeFlow's own write access.
+
+Direct copy now validates candidate Compose configuration and builds candidate images before replacing live source files. It never implicitly executes `docker compose down`, `--remove-orphans` or `--force-recreate`. Existing container IDs, image IDs and source files are captured first. When activation fails, ForgeFlow restores the prior source, retags the previous images, attempts to restore the previous runtime and retains the backup evidence. A release is only promoted after the exact linked Compose services are running and verified.
+
+This release does not claim live validation against a specific private Unraid server. The automated suite validates generated Bash syntax, permission-report parsing, scoped repair commands, no server-to-Gitea authentication, no destructive Compose flags and transactional deployment ordering.

docs/RELEASING.md

@@ -0,0 +1,56 @@
+# Releasing ForgeFlow
+
+ForgeFlow releases are built only from a clean, reviewed commit on Node 22 LTS.
+
+## Quality gate
+
+```powershell
+npm ci
+npm run quality
+npm audit --omit=dev --audit-level=high
+```
+
+## Windows build — no paid services required
+
+ForgeFlow is a personal/internal tool. The supported release path therefore has
+no certificate, Azure or other paid-service dependency:
+
+```powershell
+npm run dist:win
+```
+
+Run `npm run signing:setup` once on the release workstation. It stores the
+private Ed25519 key outside the repository and writes only its public key into
+the packaged app. `npm run dist:win` then produces the installer and portable
+executable, SHA-256 sidecars, CycloneDX SBOM, provenance and an Ed25519-signed
+manifest bound to the exact source commit. The updater verifies the pinned
+publisher key before trusting the artifact digest and verifies that digest again
+immediately before replacing the installed executable.
+
+Windows can display an `Unknown publisher` warning for an unsigned installer.
+That warning concerns public publisher reputation; it does not prevent ForgeFlow
+from installing or using its checksum-verified in-app updates. Authenticode can
+be added later as an optional distribution convenience, but is not required for
+correct operation.
+
+## Atomic publication
+
+`npm run release:binary` keeps the Gitea release in draft state while uploading
+the installer, portable executable, two checksums, provenance, SBOM, signed
+manifest and signature. It only publishes after all eight assets are present. A
+failed upload leaves a draft rather than exposing an incomplete updater target.
+
+The optional signing acceptance fixture can still validate the complete local
+Authenticode chain without purchasing or retaining a certificate:
+
+```powershell
+npm run test:signing
+```
+
+This disposable fixture signs installer, portable, update-helper and uninstaller
+stand-ins, requires an RFC 3161 timestamp, and proves rejection of a missing
+timestamp, wrong publisher and a modified binary. Its certificate is removed
+from the current-user certificate store after the test.
+
+The disposable test certificate is removed from the current-user certificate
+store after the test and is never used for a published build.

docs/ROADMAP.md

@@ -0,0 +1,106 @@
+# ForgeFlow roadmap
+
+## Delivered in v0.8
+
+- partial-hunk staging with staged-only commits;
+- guided conflict resolution and safe continue/abort controls;
+- Gitea branch-protection awareness and pull-request creation;
+- configurable editor/terminal integration;
+- deployment freezes, maintenance windows, release notes and overrides;
+- append-only audit export and encrypted credential-free configuration backup;
+- native notifications, tray, close-to-tray and start-at-login;
+- guarded real-environment deploy/rollback acceptance harness.
+
+## Delivered through v0.4
+
+- coherent Local -> Gitea -> Server desktop model;
+- protected Gitea credential storage and strict IPC boundary;
+- real Git status, diff, stage, commit, push, fetch and fast-forward pull;
+- branches, stashes, favorites and automatic local awareness;
+- multiple Gitea Actions and SSH / Unraid deployment profiles;
+- exact-SHA remote-branch validation, runner polling, request-ID verification, health and rollback;
+- five-step readiness/setup wizard;
+- system and deployment preflight engine;
+- structured rotating diagnostic JSONL logs;
+- aggressive credential/path redaction;
+- standard/strict support bundles with SHA-256 and fail-closed safety audit;
+- no automatic ingestion or persistence of raw runner logs;
+- root-owned declarative server target configuration;
+- cross-layer request-ID correlation;
+- canonical end-to-end setup guide;
+- 36 automated tests.
+
+The source is now intended to be locally configured and testable without
+sharing credentials. It remains a developer preview until a real environment
+acceptance pass is completed.
+
+## Milestone A — Real personal acceptance
+
+- run the canonical setup guide on the target Windows machine;
+- connect the actual Gitea instance locally;
+- use one non-critical staging repository;
+- register a narrowly scoped trusted runner;
+- install the target configuration, entry point and status endpoint;
+- pass Deployment preflight;
+- validate commit -> push -> deploy -> status -> health -> rollback;
+- deliberately test stopped runner, wrong branch, missing workflow, failed
+  health and lock contention;
+- export/inspect a strict diagnostic bundle from a failed test;
+- capture only non-secret environment-specific adjustments in documentation.
+
+Exit: one real application can be released and restored without code changes to
+ForgeFlow itself.
+
+## Milestone B — Git completeness
+
+- partial-hunk staging/discard;
+- amend and signing checks;
+- richer branch publication/upstream controls;
+- conflict helper and editor integration;
+- protected-branch awareness;
+- pull-request creation;
+- submodule/worktree policy.
+
+## Milestone C — Desktop operations
+
+- native notifications and system tray;
+- background start preference;
+- notification center;
+- native menus and expanded keyboard navigation;
+- configurable editor/terminal commands;
+- repository attention rules and snoozing;
+- safer periodic remote fetch scheduling.
+
+## Milestone D — Recovery and audit
+
+- append-only audit export distinct from diagnostics;
+- deployment notes and release annotations;
+- explicit reconciliation of externally deployed versions;
+- per-environment recovery runbook links;
+- encrypted configuration backup/restore without token export;
+- deployment freeze and maintenance-window policies.
+
+## Milestone E — Additional controlled adapters
+
+- mutually authenticated ForgeFlow server agent;
+- Portainer stack deployment;
+- systemd adapter;
+- Kubernetes adapter.
+
+Every adapter must retain exact version identity, allowlisting, lock control,
+health verification, diagnostic correlation and no arbitrary shell input.
+
+## Milestone F — Productization
+
+- Windows installer/portable acceptance;
+- macOS/Linux package validation;
+- optional code signing/notarization for future public distribution;
+- dependency/secret/package scans;
+- accessibility review;
+- hundreds-of-repositories performance tests;
+- opt-in privacy-aware crash reporting;
+- documented Gitea/Git/runner support matrix;
+- stable configuration migration rollback policy.
+
+- built-in private-Gitea source updater with backup and rollback;
+- Unraid server inventory, generated basic Compose and exact-SHA SSH deployment.

docs/SECURITY.md

@@ -0,0 +1,137 @@
+# Security model
+
+ForgeFlow bridges developer credentials, local source trees and production
+release controls. The design favors constrained operations over arbitrary
+flexibility.
+
+## Desktop boundary
+
+- `nodeIntegration: false`;
+- `contextIsolation: true`;
+- renderer sandbox enabled;
+- Content Security Policy limited to packaged resources;
+- narrow frozen preload API;
+- IPC rejected unless it originates from the packaged file renderer;
+- external navigation restricted to HTTP(S);
+- renderer errors reported through sanitized diagnostic IPC;
+- support-bundle reveal restricted to the last archive created by the main
+  process.
+
+## Credentials and persistence
+
+- Gitea token encrypted through Electron `safeStorage` where available;
+- session-only fallback when OS encryption is unavailable;
+- token omitted from renderer-visible public state;
+- encrypted token blob excluded from diagnostic bundles;
+- a blank settings token field preserves the existing token only when the normalized Gitea origin is unchanged;
+- atomic config replacement and restrictive permissions where supported;
+- service URLs reject embedded user credentials;
+- no token is required by setup/build scripts or documentation.
+
+## Git operations
+
+- Git executed through `execFile` argument arrays, never shell interpolation;
+- local repository and Git root verified;
+- file actions accept only repository-relative paths;
+- absolute paths, traversal and NUL characters rejected;
+- clone remotes restricted to supported Git protocols; embedded passwords
+  rejected;
+- renderer supplies repository identity rather than a free-form remote URL;
+- automatic clone targets are calculated in the main process below a selected
+  project root;
+- matching existing origins may be linked, while different repositories and
+  non-empty ordinary folders are blocked;
+- branch names validated by Git;
+- fast-forward-only pull;
+- branch switching/creation require a clean tree;
+- selected-commit flow refuses hidden staged files outside the selection;
+- monitor pauses around mutating actions.
+
+## Deployment
+
+- fixed workflow filenames, branch and environment;
+- full 40–64 character SHA required;
+- local state re-read immediately before dispatch;
+- clean, published and synchronized branch required;
+- deployment SHA must equal local `HEAD`;
+- deploy and rollback SHA must belong to the allowed remote branch;
+- no free-form server commands over IPC or workflow inputs;
+- mandatory deployment preflight in the normal UI flow;
+- backend validation repeated after preflight;
+- exact target displayed in confirmation;
+- independent health and live-SHA checks;
+- rollback uses a separate fixed workflow and previous full SHA;
+- UUID request ID correlates desktop, workflow and server state.
+
+## Diagnostics and redaction
+
+- structured events are sanitized before writing;
+- IPC payloads and HTTP authorization headers are not logged;
+- sensitive object keys, including camelCase, are removed;
+- known active tokens, authorization strings, query tokens, URL passwords,
+  private-key blocks and common token formats are redacted;
+- home/source paths are aliased;
+- strings and collections are bounded;
+- logs rotate by day/size and expire by retention policy;
+- support bundles offer deterministic strict-privacy aliases;
+- raw runner logs, diffs and source file contents are omitted from bundles;
+- bundle creation performs a final fail-closed scan for known secrets,
+  private-key markers and URL credentials;
+- bundle SHA-256 is displayed for exact identification.
+
+No generic detector can identify a completely unknown arbitrary secret printed
+without context by third-party code. ForgeFlow minimizes that residual risk by
+not exporting raw runner output and by requiring user inspection before sharing.
+
+## Runner boundary
+
+Use a production-capable runner only for repositories you trust. Give it a
+label unique to the intended environment and the narrowest repository or
+organization scope.
+
+Avoid exposing a host Docker socket to untrusted jobs. Treat a runner capable of
+host deployment as privileged infrastructure.
+
+## Server entry point
+
+The runner account should not receive unrestricted sudo or SSH access. The
+included model uses:
+
+- root-owned `/usr/local/bin/forgeflow-deploy`;
+- root-owned `/etc/forgeflow/targets.conf` without group/other write access;
+- a sudoers rule for that exact executable only;
+- exact repository/environment matching;
+- absolute-path and branch validation;
+- full-SHA remote ancestry proof;
+- per-target `flock` lock;
+- fixed Compose and healthcheck configuration;
+- atomic non-secret status JSON;
+- previous-SHA recording and non-zero failure exits.
+
+## Optional and future release hardening
+
+- optional code signing if ForgeFlow is ever distributed publicly;
+- validate private CA/TLS behavior in the target network;
+- dependency, secret and binary scans in CI;
+- package-level IPC/navigation regression tests;
+- OS-specific credential storage and installer acceptance;
+- rate/approval policies for team use;
+- threat-model every future deployment adapter separately.
+
+
+## SSH and updater additions
+
+- SSH passwords and private-key passphrases use Electron `safeStorage`;
+- diagnostics receive those runtime secrets only for redaction and never export
+  encrypted credential fields;
+- SSH host identity is previewed without credentials and authenticated sessions
+  require the exact user-confirmed pinned fingerprint;
+- remote folders and Compose paths are validated against traversal;
+- tracked server-side changes block exact-SHA reset;
+- updater tokens are sent only to the configured Gitea origin, and changing that origin requires a newly entered token;
+- non-loopback Gitea connections require HTTPS;
+- packaged updates require a publisher-signed Ed25519 manifest that binds the
+  source commit, artifact identity, byte length and SHA-256 digest;
+- packaged update bytes are rehashed immediately before apply;
+- integrated source replacement is disabled until source archives carry the
+  same independent publisher signature.

docs/SETUP_GUIDE.md

@@ -0,0 +1,485 @@
+# ForgeFlow setup and first-test guide
+
+This is the canonical guide for turning the source release into a locally
+configured desktop application and testing one complete path:
+
+```text
+local change -> commit -> push -> exact-SHA deployment -> healthcheck -> rollback
+```
+
+You never need to provide your Gitea token, SSH key or server credentials to a
+developer. Enter them only on the computer or server where they belong.
+
+---
+
+## Part 1 — Prepare the Windows desktop
+
+### 1. Extract the release
+
+Extract the complete ForgeFlow ZIP to a normal local directory, for example:
+
+```text
+C:\Tools\ForgeFlow
+```
+
+Avoid running it directly from inside the ZIP or from a temporary email folder.
+
+### 2. Install the prerequisites
+
+Required:
+
+- Node.js 22 or newer;
+- npm, normally installed with Node.js;
+- Git for Windows available on `PATH`;
+- a normal signed-in Windows desktop session so Electron can use OS credential
+  encryption.
+
+Optional manual check:
+
+```powershell
+node --version
+npm --version
+git --version
+git config --global user.name
+git config --global user.email
+```
+
+Configure the Git identity when either value is empty:
+
+```powershell
+git config --global user.name "YOUR NAME"
+git config --global user.email "YOUR EMAIL"
+```
+
+### 3. Run the local setup command
+
+Open PowerShell in the extracted folder and run:
+
+```powershell
+Set-ExecutionPolicy -Scope Process Bypass
+.\setup-windows.ps1
+```
+
+This command:
+
+1. checks Node.js, npm and Git;
+2. installs the declared project dependency versions;
+3. runs source validation and all automated tests;
+4. starts the Electron desktop application.
+
+No Gitea or server credential is requested by the PowerShell script.
+
+---
+
+## Part 2 — Complete the ForgeFlow desktop wizard
+
+The first launch uses five explicit steps.
+
+### Step 1. Readiness
+
+Select **Run readiness check**. ForgeFlow verifies:
+
+- Git CLI availability;
+- Git author identity;
+- writable application storage;
+- writable diagnostic storage;
+- availability of operating-system credential encryption.
+
+Warnings are informative. Red required checks block completion until resolved.
+A safe setup diagnostic ZIP can already be exported at this stage.
+
+### Step 2. Gitea
+
+Create a Gitea access token (personal access token) in your own Gitea account. The exact scope labels
+can vary by Gitea version. Give it only the minimum rights needed for:
+
+- reading the repositories you want to show in ForgeFlow;
+- reading repository contents and branches;
+- reading Actions runs and jobs;
+- dispatching the fixed deployment and rollback workflows.
+
+Do not put this token in a Markdown file, `.env`, workflow or chat message.
+
+Enter locally in ForgeFlow:
+
+```text
+Instance URL:  https://YOUR-GITEA-HOST
+Access token:  PASTE LOCALLY IN THE PASSWORD FIELD
+```
+
+Select **Validate & continue**. ForgeFlow confirms the user identity and
+repository access. When OS encryption is available, the token is stored with
+Electron `safeStorage`; otherwise it remains session-only and must be entered
+again after restarting.
+
+### Step 3. Folders
+
+Choose one or more project roots that contain local repositories, for
+example:
+
+```text
+C:\Development
+D:\Projects
+```
+
+Do not select the entire system disk. A focused project root produces faster
+and clearer discovery.
+
+The first configured root is also the default clone destination. When cloning
+`owner/repository`, ForgeFlow automatically creates:
+
+```text
+<first-project-root>\repository
+```
+
+The normal **Clone from Gitea** action does not open a folder picker. Use
+**Choose another location** only when a repository belongs under a different
+parent directory. ForgeFlow still creates the repository-named subfolder.
+
+### Step 4. Discovery
+
+ForgeFlow scans Git metadata and matches each local `origin` to a Gitea
+repository. Generated dependency directories are skipped.
+
+### Step 5. Ready
+
+Enter ForgeFlow. Repositories that could not be matched can still be linked or
+cloned from their repository screen. A clone is automatically linked and
+monitored after Git completes.
+
+---
+
+## Part 3 — Prepare one repository for deployment
+
+Start with a non-critical staging application when possible.
+
+### 1. Verify the local repository
+
+The repository should have:
+
+- a configured `origin` pointing to the same Gitea repository;
+- a normal branch such as `main`;
+- no unresolved conflicts;
+- an upstream branch after the first push.
+
+### 2. Add the fixed Gitea Actions workflows
+
+Copy:
+
+```text
+examples/gitea-actions/deploy.yml
+examples/gitea-actions/rollback.yml
+```
+
+to the target repository as:
+
+```text
+.gitea/workflows/deploy.yml
+.gitea/workflows/rollback.yml
+```
+
+Review the runner label in both files:
+
+```yaml
+runs-on: forgeflow-production
+```
+
+Replace it with the exact label of the trusted runner that can reach the target
+server environment. Commit and push these workflow files before running the
+deployment preflight.
+
+The workflows accept only controlled inputs:
+
+```text
+environment
+commit_sha or target_sha
+request_id
+```
+
+ForgeFlow creates the `request_id` automatically so desktop diagnostics,
+Actions output and server status can be correlated without exposing a secret.
+
+---
+
+## Part 4 — Prepare the server and trusted runner
+
+The example implementation targets a dedicated Git checkout deployed with
+Docker Compose. Adapt the allowlisted target values, not the security model.
+
+### 1. Confirm the server prerequisites
+
+On the target server, verify:
+
+```bash
+git --version
+docker --version
+docker compose version
+curl --version
+flock --version
+```
+
+The application checkout must already exist and have a working `origin` that the
+server can fetch without interactive prompts.
+
+Example:
+
+```text
+/srv/YOUR-APP
+/srv/YOUR-APP/compose.yml
+```
+
+### 2. Install the target configuration
+
+Copy the template:
+
+```bash
+sudo install -d -o root -g root -m 0755 /etc/forgeflow
+sudo install -o root -g root -m 0640 \
+  examples/server/forgeflow-targets.conf \
+  /etc/forgeflow/targets.conf
+```
+
+Edit it as root:
+
+```bash
+sudo nano /etc/forgeflow/targets.conf
+```
+
+Each active line has seven pipe-separated fields:
+
+```text
+repository|environment|app_dir|branch|compose_file|healthcheck_url|status_file
+```
+
+Example:
+
+```text
+jens/my-app|staging|/srv/my-app-staging|main|/srv/my-app-staging/compose.yml|http://127.0.0.1:18080/health|/var/lib/forgeflow-status/my-app-staging.json
+```
+
+Rules:
+
+- repository must exactly match `owner/repository` in Gitea;
+- environment must exactly match the ForgeFlow profile value;
+- all filesystem paths must be absolute;
+- status files must stay under `/var/lib/forgeflow-status/`;
+- the configuration must remain root-owned and not group/other writable.
+
+Validate permissions:
+
+```bash
+sudo stat -c '%U %G %a %n' /etc/forgeflow/targets.conf
+```
+
+Expected owner is `root`; a mode such as `640` is appropriate.
+
+### 3. Install the allowlisted deployment entry point
+
+```bash
+sudo install -o root -g root -m 0755 \
+  examples/server/forgeflow-deploy \
+  /usr/local/bin/forgeflow-deploy
+```
+
+The script:
+
+- accepts only a valid repository, environment, full SHA and request ID;
+- resolves the repository/environment through the root-owned target file;
+- rejects unsafe paths and branches;
+- prevents concurrent deployments with `flock`;
+- fetches the allowed branch;
+- proves that the requested SHA is an ancestor of the remote branch;
+- resets only the dedicated deployment checkout;
+- runs the fixed Docker Compose redeploy;
+- performs repeated healthchecks;
+- writes live, previous and requested SHAs atomically;
+- records the correlation request ID and last exit code.
+
+### 4. Restrict runner elevation
+
+Copy and edit the sudoers example:
+
+```bash
+sudo install -o root -g root -m 0440 \
+  examples/server/forgeflow-runner.sudoers \
+  /etc/sudoers.d/forgeflow-runner
+sudo visudo -cf /etc/sudoers.d/forgeflow-runner
+```
+
+Replace `act_runner` with the actual trusted runner account. Do not grant that
+account unrestricted passwordless `sudo`, shell access or wildcard commands.
+
+### 5. Register and start the Gitea runner
+
+Register a dedicated trusted runner according to your Gitea instance and runner
+version. Attach the exact label referenced by the workflow, for example:
+
+```text
+forgeflow-production
+```
+
+Only repositories you control should be able to schedule jobs on a runner with
+production access.
+
+---
+
+## Part 5 — Publish server version status
+
+The server script writes one non-secret JSON status document per environment.
+Serve it over HTTPS independently of the application process so it can still
+report a failed release.
+
+Copy and adapt:
+
+```text
+examples/server/nginx-forgeflow-status.conf
+```
+
+Example URL:
+
+```text
+https://YOUR-APP-HOST/.well-known/forgeflow
+```
+
+Expected response:
+
+```json
+{
+  "repository": "jens/my-app",
+  "environment": "staging",
+  "request_id": "00000000-0000-0000-0000-000000000000",
+  "commit_sha": "0123456789abcdef0123456789abcdef01234567",
+  "previous_sha": "89abcdef0123456789abcdef0123456789abcdef",
+  "requested_sha": "0123456789abcdef0123456789abcdef01234567",
+  "deployed_at": "2026-07-24T12:00:00Z",
+  "health": "healthy",
+  "last_exit_code": 0
+}
+```
+
+Test from the ForgeFlow desktop computer:
+
+```powershell
+Invoke-WebRequest "https://YOUR-APP-HOST/.well-known/forgeflow"
+Invoke-WebRequest "https://YOUR-APP-HOST/health"
+```
+
+See [`STATUS_ENDPOINT.md`](STATUS_ENDPOINT.md) for the accepted contract.
+
+---
+
+## Part 6 — Create the deployment profile in ForgeFlow
+
+Open the linked repository and add an environment.
+
+Fill in:
+
+```text
+Profile name:       Staging
+Environment input:  staging
+Allowed branch:     main
+Deploy workflow:    deploy.yml
+Rollback workflow:  rollback.yml
+Status URL:         https://YOUR-APP-HOST/.well-known/forgeflow
+Healthcheck URL:    https://YOUR-APP-HOST/health
+Confirmation:       enabled
+```
+
+Save the profile.
+
+---
+
+## Part 7 — Run Deployment preflight
+
+Select **Preflight** on the environment card. ForgeFlow must verify:
+
+1. local repository link;
+2. valid Git working tree;
+3. allowed current branch;
+4. clean working tree;
+5. published upstream;
+6. zero commits ahead and zero behind;
+7. exact local SHA exists on the allowed remote branch;
+8. local deploy workflow exists;
+9. remote deploy workflow exists on Gitea;
+10. Gitea Actions API is readable;
+11. a configured server status endpoint;
+12. current status-endpoint reachability;
+13. application healthcheck result when configured.
+
+The status URL is mandatory because ForgeFlow uses it after the workflow to prove
+that the server applied the exact SHA for the exact request ID. An unreachable
+status document can be a warning before the very first deployment because the
+server script may create it, but the operation cannot finish successfully until
+the endpoint returns the requested SHA and request ID. Required failures block
+the Continue button and the deployment backend repeats its own Git/SHA checks at
+dispatch time.
+
+---
+
+## Part 8 — First safe end-to-end test
+
+Use a staging profile first.
+
+1. Make a harmless visible change.
+2. Review the diff in ForgeFlow.
+3. Enter a commit message.
+4. Select **Commit & push**.
+5. Confirm that Local and Gitea show the same SHA.
+6. Select **Deploy SHA -> Staging**.
+7. Review and continue through Deployment preflight.
+8. Confirm the exact SHA.
+9. Follow workflow, job and healthcheck progress.
+10. Confirm that the server status endpoint reports the same full SHA.
+11. Create a second harmless commit and deploy it.
+12. Use **Rollback** to restore the recorded previous SHA.
+
+Also test deliberately:
+
+- an uncommitted local change;
+- a local commit that was not pushed;
+- the wrong branch;
+- a missing workflow file;
+- a stopped runner;
+- a failed healthcheck;
+- a second deployment while the lock is held.
+
+ForgeFlow should block unsafe local states and clearly retain failed operation
+metadata for diagnostics.
+
+---
+
+## Part 9 — Export a diagnostic bundle without sharing credentials
+
+Open **Diagnostics**.
+
+1. Run **System preflight**.
+2. Select **Strict privacy** when sharing externally.
+3. Select **Create diagnostic ZIP**.
+4. Inspect the ZIP before sending it.
+
+The bundle deliberately contains no encrypted token field and omits raw runner
+logs. Before writing the ZIP, ForgeFlow runs a safety audit for known runtime
+secrets, private-key markers and unredacted URL credentials. If that audit
+fails, no bundle is written.
+
+See [`DIAGNOSTICS.md`](DIAGNOSTICS.md) for the exact contents and limitations.
+
+
+---
+
+## Part 8 — Configure an Unraid server
+
+Open **Settings → SSH / Unraid servers**. Enter the host, SSH port, username and
+`/mnt/user/appdata` as the base path. Prefer a private key. Save, then run
+**Test & trust** to record the server host-key fingerprint.
+
+For an existing project, enter its current server folder name. ForgeFlow
+inspects the root Git repository, tracked modifications, Compose files and
+nested repositories before it permits deployment.
+
+For a new project, use the repository name as server folder. Select the
+repository Compose file or enable basic generated Compose and enter host and
+container ports.
+
+See `docs/SSH_UNRAID_DEPLOYMENT.md`.

docs/SSH_UNRAID_DEPLOYMENT.md

@@ -0,0 +1,73 @@
+# SSH / Unraid deployment
+
+ForgeFlow uses one deployment flow for Unraid: it copies the exact committed local project from the desktop to the server and activates the Compose definition found for that deployment.
+
+## Deployment modes
+
+### Direct copy — default
+
+ForgeFlow creates an archive from the exact local commit and uploads it through the configured desktop-to-Unraid connection. Unraid needs Docker, Docker Compose, `tar` and a SHA-256 checksum tool. Unraid does not clone, fetch or authenticate to a repository.
+
+### Monitor only
+
+ForgeFlow inventories and tracks the workload but refuses deploy and rollback operations until **Direct copy** is selected.
+
+All older SSH/Unraid profiles are migrated to Direct copy unless they were explicitly Monitor only.
+
+## Server Inventory and automatic linking
+
+Server Inventory reads the server itself instead of relying on ForgeFlow history. The default scan root is `/mnt/user/appdata`, together with the configured server base path and the cache-backed appdata path when present. It combines:
+
+- running and stopped containers from `docker ps -a` and Docker Inspect;
+- active and stopped Compose projects;
+- DockerMan templates;
+- Compose YAML files below the configured appdata roots, including standard override files.
+
+YAML discovery continues even when Docker inspection fails. For each Compose definition ForgeFlow reads the working directory, project name, file set, services and images. It then compares those values with the linked local repositories.
+
+A unique high-confidence match based on both the Compose folder and project identity is linked automatically. Other strong matches show a one-click **Link to repository** action. The server folder, Compose project, Compose files, service list, visible container identity, ports and preservation paths are already filled in; linking does not recreate the container.
+
+## Compose identity
+
+An adopted installation retains the identity detected on the server:
+
+```text
+Visible container:        geointel
+Server folder:            GeoIntel
+Compose project:          geointel
+Compose files:            compose.yml, compose.override.yml
+Compose services:         web, worker
+```
+
+ForgeFlow adds `.forgeflow/compose.metadata.yml` as the final Compose overlay. For adopted workloads this overlay adds safe labels only; it does not replace the existing image, volumes, ports, networks or `container_name`.
+
+`--force-recreate` and `--remove-orphans` remain disabled by default. Existing DockerMan templates are not rewritten.
+
+## Direct-copy sequence
+
+1. Verify the selected local branch, clean working tree and exact committed HEAD.
+2. Test the desktop-to-Unraid connection, Docker, Compose, `tar`, checksum tooling and deployment storage.
+3. Create the release locally with `git archive`.
+4. Upload a temporary `.part` file through SFTP.
+5. Verify SHA-256 and reject unsafe archive paths or symbolic links.
+6. Preserve `.forgeflow`, `.git` and configured runtime paths such as `.env`, `data`, `config`, `logs` and application-specific folders.
+7. Update only files covered by the managed release manifests; unrelated server files remain untouched.
+8. Validate the detected merged Compose configuration.
+9. Activate the retained Compose project and verify every selected service is running and not unhealthy.
+10. Promote the active SHA and manifests only after activation succeeds.
+11. Run the optional desktop health check and persist runtime state.
+
+If activation fails, ForgeFlow restores the previous managed files and Compose metadata and leaves the previous active SHA authoritative.
+
+## Authentication model
+
+- The only remote authentication used for Direct copy is the configured desktop-to-Unraid connection.
+- That connection may use an Unraid password or a private key.
+- Passwords and private-key passphrases use Electron safe storage.
+- The first trusted connection records the SSH host-key fingerprint; later changes fail closed.
+- Remote inventory collects selected labels, mounts, ports and runtime state; it does not collect container environment values.
+- The renderer cannot submit arbitrary shell commands; remote scripts are assembled from validated profile fields.
+
+## Rollback
+
+Rollback is allowed only to the exact `previousSha` recorded for the profile. ForgeFlow recreates that commit archive locally and uses the same upload, checksum, backup, Compose validation and atomic promotion flow.

docs/STATUS_ENDPOINT.md

@@ -0,0 +1,59 @@
+# Server status endpoint contract
+
+A workflow can report success while the wrong application version is running.
+ForgeFlow therefore supports a small server-side endpoint that independently
+reports the deployed commit.
+
+## Canonical response
+
+```json
+{
+  "repository": "jens/example-app",
+  "environment": "production",
+  "request_id": "3a6ed71c-d52d-4d8d-9678-96e0c9456a81",
+  "commit_sha": "0123456789abcdef0123456789abcdef01234567",
+  "previous_sha": "89abcdef0123456789abcdef0123456789abcdef",
+  "requested_sha": "0123456789abcdef0123456789abcdef01234567",
+  "deployed_at": "2026-07-24T13:00:00Z",
+  "health": "healthy",
+  "last_exit_code": 0
+}
+```
+
+Required for exact version verification:
+
+- `commit_sha`: full 40–64 character hexadecimal commit identity.
+
+Recommended:
+
+- `previous_sha`: previous successful commit used by rollback;
+- `requested_sha`: SHA requested by the latest deployment attempt;
+- `request_id`: ForgeFlow operation correlation identifier;
+- `deployed_at`: ISO-8601 timestamp;
+- `health`: `healthy`, `deploying` or `unhealthy`;
+- `last_exit_code`: server entry-point result, with `0` for success;
+- `repository` and `environment`: useful for human consistency checks.
+
+ForgeFlow also accepts `commitSha`, `sha`, `previousSha`, `requestId` and nested
+`version.sha`, but canonical snake-case fields are preferred.
+
+## Isolation
+
+Serve the endpoint independently from the deployed application when practical.
+A static JSON file exposed by the reverse proxy remains readable when the
+application fails to boot. The included deployment script writes it atomically.
+
+The JSON file is non-secret and can be served read-only. Do not include tokens,
+host credentials, environment variables, registry secrets or stack traces.
+
+## Profile configuration
+
+Set both URLs when available:
+
+- **Status URL**: returns this document and exact live SHA;
+- **Healthcheck URL**: returns a successful HTTP status only when the application
+  is operational.
+
+After an Actions run succeeds, ForgeFlow checks both. It marks the operation
+failed when the healthcheck is unhealthy or the server reports another SHA than
+the requested deployment.

docs/STITCH_REVIEW.md

@@ -0,0 +1,99 @@
+# Stitch review and design corrections
+
+## What worked well
+
+The Stitch export established a strong visual starting point:
+
+- A restrained graphite theme suitable for long sessions.
+- Compact desktop density.
+- Clear technical typography.
+- Useful deployment progress and failure concepts.
+- A credible developer-tool tone without excessive decoration.
+- Good use of green, amber and red for operational state.
+
+## What was changed
+
+### 1. From IDE shell to release cockpit
+
+The export contained navigation for Editor, Monitoring and Extensions. Those features would blur the product into an incomplete IDE. ForgeFlow instead complements the user's existing editor and terminal.
+
+The product boundary is now:
+
+```text
+Understand repository state -> perform safe Git action -> release exact version
+```
+
+### 2. One navigation model
+
+The mock-ups mixed a top product navigation with a broad left application navigation. The implementation uses:
+
+- A compact top bar for global search, identity, refresh and theme.
+- A left rail for Overview, Deployments, Settings and repositories.
+- Repository tabs only inside the selected project.
+
+### 3. Operational cards instead of generic statistics
+
+CPU, queue or server graphs are not useful unless ForgeFlow becomes a monitoring suite. The overview now answers:
+
+- Which projects have local changes?
+- Which commits are not pushed?
+- Which repositories are behind or conflicted?
+- Which exact commits are ready to deploy?
+
+### 4. Persistent Local -> Gitea -> Server rail
+
+The most important state was made visible at the top of every repository workspace. The user no longer needs to infer synchronization from several unrelated badges.
+
+### 5. Contextual action panel
+
+The right panel now changes with state:
+
+- Link or clone.
+- Resolve conflict.
+- Commit and push.
+- Fast-forward synchronize.
+- Push commits.
+- Configure deployment.
+- Deploy exact SHA.
+- Explain the blocking error.
+
+Only one action is visually dominant.
+
+### 6. Diff viewer, not editor
+
+ForgeFlow displays changed files and diffs, but deliberately opens the real project folder for editing. This avoids duplicating editor features and keeps the application technically realistic.
+
+### 7. Safer deployment language
+
+A generic **Deploy** button can hide too much. ForgeFlow displays the exact action:
+
+```text
+Deploy b82f91a -> Production
+```
+
+The confirmation state shows the repository, branch, full SHA and workflow file.
+
+### 8. Desktop behavior
+
+The implementation adds details that static screens could not provide:
+
+- Native directory selection.
+- External-link restrictions.
+- Keyboard shortcut for global search.
+- Ctrl/Cmd+Enter for commit and push.
+- Resizable desktop layout.
+- Offline and error handling foundations.
+- Secure process boundary between UI and system operations.
+
+## Visual direction retained
+
+The implementation intentionally keeps:
+
+- Deep neutral background and panels.
+- Blue primary actions.
+- Green synchronization and health.
+- Amber pending work.
+- Red actual failures and conflicts.
+- Compact status badges.
+- Monospace only for branches, commits, paths and logs.
+- Minimal decorative effects.

docs/TEST_MATRIX.md

@@ -0,0 +1,149 @@
+# Test matrix
+
+## Automated baseline (0.10.x)
+
+The quality chain contains more than 230 Node and browser acceptance cases. The
+latest Windows source run completed without failures and retains one explicitly
+Bash-dependent skip. `npm run coverage` enforces 75% lines/statements/functions
+and 65% branches; the measured hardening baseline is 81.48% statements/lines,
+82.07% functions and 65.59% branches. See `COVERAGE_POLICY.md` for the
+non-gamed branch policy.
+
+`npm run quality` is the local equivalent of `.gitea/workflows/quality.yml` and
+runs source verification, ESLint, the complete suite and coverage on Node 22 LTS.
+Production dependencies are separately checked with `npm audit --omit=dev
+--audit-level=high`.
+
+### Server safety and reconciliation
+
+- inventory discovery is read-only and byte-stable for configuration;
+- reconciliation requires a content-addressed preview plan and recovery snapshot;
+- automatic linking requires unique exact provenance/runtime identity;
+- server-pull verification checks Gitea branch, read-only deploy-key ID, pinned
+  host/key fingerprints, remote/live SHA, Compose evidence, runtime and health;
+- a fresh access verification is mandatory immediately before server-pull deploy;
+- writable or missing deploy keys fail closed.
+
+### Renderer regression matrix
+
+Playwright runs 36 cases across 1120×720, 1440×900 and 1920×1080, dark and
+light themes, reduced motion, and simulated 100%, 125% and 150% Windows scaling.
+It checks console/page errors, accessible names, labels, heading structure,
+horizontal overflow, viewport containment, dialogs, keyboard focus, updater and
+deployment failure evidence. CI retains screenshots, video, trace, console JSON,
+DOM HTML and fixture context on failure.
+
+### Git and repository behavior
+
+- porcelain v2 ordinary and rename parsing;
+- HTTPS and SCP-style remote matching;
+- real temporary bare remote: status, diff, selected commit and push;
+- real temporary bare remote: commit-only, branch creation/publication and
+  remote-SHA ancestry verification;
+- real stash creation, listing, pop and untracked-file restoration;
+- repository monitor baseline, change detection and pause/resume;
+- safe repository folder-name derivation from HTTPS and SSH clone URLs;
+- automatic target construction beneath the project root;
+- missing, empty and matching-checkout clone target handling;
+- different repository, ordinary non-empty folder and file conflict rejection.
+
+### Gitea and deployment behavior
+
+- Gitea URL/credential validation;
+- Actions run normalization across payload shapes;
+- optional query-filter compatibility retry;
+- runs-to-tasks fallback;
+- newest matching run selection;
+- repository workflow contents lookup and 404 behavior;
+- deployment terminal-status mapping;
+- controlled dispatch inputs that cannot be overridden by profile data;
+- exact post-workflow SHA and request-ID verification;
+- rollback input allowlisting and exact current previous-SHA enforcement;
+- complete deployment preflight with Git, workflow, Actions, status and health
+  mocks.
+
+### Security and diagnostics
+
+- repository path traversal and absolute-path rejection;
+- workflow filename, branch, environment and full-SHA validation;
+- clone protocol and embedded-password rejection;
+- runtime token, authorization, query token, URL credential and private-key
+  redaction;
+- camelCase and nested sensitive-key removal;
+- home-path aliasing;
+- deterministic strict-privacy identifier hashing;
+- required versus optional preflight blocking behavior;
+- system preflight before credentials are entered;
+- structured JSONL diagnostic writes;
+- support-bundle strict privacy and secret exclusion;
+- ZIP structure, deflate payloads and CRC validation.
+- Windows npm command-shim discovery through `npm_execpath` and `cmd.exe`;
+- normal direct npm discovery on non-Windows systems.
+
+## Static source quality gate
+
+`npm run verify` checks:
+
+- all required source, documentation and server-template files;
+- JavaScript syntax across the project;
+- package version and required scripts;
+- desktop packaging metadata and icons;
+- Bash syntax for the server entry point;
+- status JSON parsing;
+- required setup-guide sections;
+- renderer entry hooks.
+
+## Manual before a real production release
+
+- setup wizard against the installed Gitea version;
+- repository discovery on the target Windows system;
+- token persistence through Windows credential protection;
+- HTTPS and/or SSH Git authentication;
+- actual Actions dispatch, run resolution and job visibility;
+- runner label and repository trust scope;
+- server target-file ownership/mode enforcement;
+- status endpoint through the real reverse proxy;
+- deployment lock, failed healthcheck and rollback;
+- diagnostic ZIP inspection after a deliberately failed deployment;
+- locally test-signed installer, portable, helper and uninstaller fixtures with
+  RFC 3161 timestamp plus wrong-publisher, missing-timestamp and tamper rejection;
+- keyboard-only and screen-reader smoke test.
+
+## Renderer smoke target
+
+The standalone demo should be checked at minimum at:
+
+- 1120 × 720;
+- 1440 × 900;
+- 1920 × 1080.
+
+Required views now include setup readiness, dashboard, repository workspace,
+deployment preflight, active run, success/failure and Diagnostics.
+
+## v0.8 functional acceptance
+
+- real-repository partial hunk staging without staging the remaining changes;
+- guided merge-conflict resolution and safe continue/abort actions;
+- Gitea pull-request creation and protected-branch inspection;
+- shell-free editor and terminal argument-template expansion;
+- deployment freezes, maintenance windows, mandatory release notes and reasoned overrides;
+- authenticated encrypted configuration backup without credentials or operation history;
+- append-only audit JSONL and CSV export;
+- desktop notification, tray and close-to-tray preference integration;
+- read-only-by-default end-to-end Gitea Actions acceptance harness with explicit deploy/rollback flags;
+- interactive demo verification for repository quick actions, hunk staging and pull-request dialogs.
+
+
+### v0.4 additions
+
+- bounded independently scrollable changed-file layout;
+- explicit commit-message and selection readiness contract;
+- ITWorx.tech asset integration;
+- semantic update-version comparison;
+- exact-SHA Gitea update manifest lookup;
+- update repository path-injection rejection;
+- SSH host-key fingerprint helper;
+- remote shell quoting;
+- Unraid folder and Compose path escape rejection;
+- server inspection payload decoding;
+- SSH deployment preflight summary behavior.

docs/UPDATING.md

@@ -0,0 +1,69 @@
+# Updating ForgeFlow on Windows
+
+ForgeFlow stores credentials, repository mappings, preferences, deployment profiles, diagnostics and operation history outside the source directory.
+
+## Source checkouts
+
+Integrated source replacement is disabled until source archives are covered by the same independent publisher signature as packaged releases. A server-provided commit SHA and a checksum calculated from the downloaded archive do not independently authenticate its publisher, while dependency installation can execute package lifecycle scripts.
+
+Update a source checkout through Git instead:
+
+1. fetch the configured upstream;
+2. review the exact commit and release notes;
+3. switch to the intended release commit or tag;
+4. run `npm ci --ignore-scripts` and review the dependency lifecycle allowlist;
+5. run `npm run check` before starting ForgeFlow.
+
+The in-app updater remains available for signed packaged Windows releases.
+
+## Packaged Windows updates
+
+ForgeFlow uses authenticated Gitea release assets when running from the installer or portable executable. The updater selects the artifact that matches the current installation mode and requires its `.sha256` sidecar. From version 0.10.13 onward it also requires an Ed25519-signed release manifest. The embedded public key verifies that manifest before ForgeFlow trusts the artifact name, byte length, exact source commit or SHA-256 digest. The digest is checked again immediately before applying the update.
+
+`Publish-ForgeFlow-Release.ps1` treats source and binaries as one release transaction. It pushes the validated source, builds the exact published commit and uploads eight 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`
+- `ForgeFlow-<version>-provenance.json`
+- `ForgeFlow-<version>-sbom.cdx.json`
+- `ForgeFlow-<version>-release-manifest.json`
+- `ForgeFlow-<version>-release-manifest.json.sig`
+
+Run `npm run signing:setup` once on the release workstation. The private Ed25519 key stays outside the repository in ForgeFlow's user-data folder. This independent publisher signature is free; optional Authenticode can still be added later for Windows reputation.
+
+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\your-name\Downloads\ForgeFlow-<version>\ForgeFlow\package.json
+```
+
+Run:
+
+```powershell
+cd C:\Users\your-name\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 all binaries, checksums and signed release evidence to the matching Gitea release. Publication fails when either the source commit, publisher signature or any required asset cannot be verified.
+
+Keep the currently installed older ForgeFlow source folder untouched until the built-in updater test is complete.