docs(easy-docker): document jq processing and fallback

docs/01-getting-started/05-easy-docker.md

@@ -21,9 +21,23 @@ Current status:
 The script entrypoint is:
 
 ```bash
-bash easy-docker.sh
+bash ./easy-docker.sh
 ```
 
+Before the wizard opens, `easy-docker` validates its startup dependencies.
+Today that means:
+
+- `gum`
+- `docker`
+- `docker compose`
+- Docker daemon availability
+- `jq`
+
+If `gum` or `jq` is missing, `easy-docker` first tries package-manager
+installation and can then fall back to a pinned GitHub binary when the setup is
+interactive and fallback is not disabled. On Windows, use a real Bash
+environment such as WSL or Git Bash and keep the script path in Bash syntax.
+
 Minimal first use:
 
 1. Start `easy-docker.sh`

docs/07-troubleshooting/01-troubleshoot.md

@@ -4,6 +4,7 @@ title: Troubleshoot
 
 - [Fixing MariaDB issues after rebuilding the container](#fixing-mariadb-issues-after-rebuilding-the-container)
 - [docker-compose does not recognize variables from `.env` file](#docker-compose-does-not-recognize-variables-from-env-file)
+- [easy-docker dependency checks](#easy-docker-dependency-checks)
 - [Windows Based Installation](#windows-based-installation)
 - [Redo installation](#redo-installation)
 
@@ -69,6 +70,33 @@ Note: For MariaDB 10.3 and older use `mysql.user` instead of `mysql.global_priv`
 
 If you are using old version of `docker-compose` the .env file needs to be located in directory from where the docker-compose command is executed. There may also be difference in official `docker-compose` and the one packaged by distro. Use `--env-file=.env` if available to explicitly specify the path to file.
 
+### easy-docker dependency checks
+
+`easy-docker` now validates its startup dependencies before the TUI opens.
+
+The check order is:
+
+1. CLI options
+2. `gum`
+3. `docker`
+4. `jq`
+
+If `gum` or `jq` is missing, the wizard first tries package-manager
+installation. If that does not work and the session is interactive, it can then
+offer a pinned GitHub binary fallback unless `--no-installation-fallback` is
+set.
+
+If `jq` is still missing after those steps, startup stops with install guidance
+instead of continuing into the menus.
+
+On Windows, pay attention to which Bash runtime you are actually using:
+
+- `bash` from PowerShell usually means WSL
+- Git Bash is a separate runtime
+- use Bash path syntax such as `bash ./easy-docker.sh`
+
+Windows-native Bash setups can use either `jq` or `jq.exe` on `PATH`.
+
 ### Windows Based Installation
 
 - Set environment variable `COMPOSE_CONVERT_WINDOWS_PATHS` e.g. `set COMPOSE_CONVERT_WINDOWS_PATHS=1`

docs/10-easy-docker/01-overview.md

@@ -17,6 +17,11 @@ All stack data created by the wizard is written into the repository-local
 `.easy-docker` directory. That includes the generated stack environment files
 and the stack-specific metadata used by the workflow.
 
+Internally, the stack JSON contract is now handled through `jq` instead of
+line-based `awk` parsing. This is meant to improve robustness against harmless
+JSON formatting differences without changing the generated layout of
+`metadata.json` or `apps.json`.
+
 This means `easy-docker` is not a closed system. After the setup has been
 created, you can still inspect the generated files, keep working with them
 manually, and continue outside the wizard if that fits your workflow better.
@@ -63,6 +68,18 @@ To run `easy-docker`, the environment should have:
 - Docker Compose v2 through `docker compose`
 - a running Docker daemon
 - `gum` for the interactive terminal UI
+- `jq` for stack JSON processing
+
+The startup checks happen in this order:
+
+1. CLI option parsing
+2. `gum`
+3. `docker`
+4. `jq`
+5. TUI startup
+
+That means `--help` exits before dependency checks, while missing dependencies
+stop the workflow before the menus open.
 
 When `gum` is already installed, the wizard uses it directly.
 
@@ -81,6 +98,12 @@ This means the usual setup flow is:
 The Docker requirements are also checked on startup so the workflow stops early
 with guidance instead of failing later in the middle of stack setup.
 
+`jq` now follows the same install strategy as `gum`: `easy-docker` first checks
+whether it is already available, then tries the system package manager, and can
+finally offer a pinned GitHub binary fallback in interactive sessions.
+Runtime resolution accepts either `jq` or `jq.exe`, which keeps Windows-native
+Bash setups compatible as long as one of them is on `PATH`.
+
 ## Main Areas
 
 ### Stack Creation
@@ -210,5 +233,5 @@ the workflow stays consistent when you return to manage it later.
 Run the wizard from the repository root:
 
 ```bash
-bash easy-docker.sh
+bash ./easy-docker.sh
 ```

docs/10-easy-docker/02-workflows.md

@@ -25,6 +25,12 @@ Site app management is intentionally scoped to apps that are already part of the
 stack image. The wizard does not try to install arbitrary apps that are not part
 of the selected stack configuration.
 
+Internally, the stack app contract is now handled through `jq` instead of
+line-based `awk` parsing. This is intended to keep app selection and branch
+update behavior the same while making the JSON processing more robust in the
+background. The generated `metadata.json` and `apps.json` files are still meant
+to look the same to users.
+
 For the split-services path, see
 [Split Services](./05-split-services.md). That page explains the intended flow
 in simple terms and shows where the proxy, application, database, and Redis

docs/10-easy-docker/03-updates.md

@@ -22,5 +22,11 @@ you can see the base version the stack is built against.
 value on the next start or restart, so the tag change becomes effective once the
 image has been rebuilt and the stack is restarted.
 
+The update flow still rebuilds the image from a regenerated `apps.json`, and
+`metadata.json` remains the source of truth for the stack state. The difference
+is internal: stack metadata and generated app state are now processed through
+`jq` instead of line-based `awk` parsing. No user-visible change in the file
+layout is intended.
+
 For now, this update flow focuses on app branch changes. A separate Frappe base
 version update flow can be added later without changing the overall model.

docs/10-easy-docker/index.md

@@ -16,6 +16,11 @@ This section documents the current behavior of the wizard:
 - stack, site, app, and update actions are handled through the wizard
 - the generated Compose output is available as a rendered snapshot
 
+Before the wizard opens, `easy-docker` validates its startup dependencies. That
+includes `gum`, `docker`, `docker compose`, a running Docker daemon, and `jq`.
+`gum` and `jq` can both use package-manager installation and a pinned GitHub
+binary fallback. `docker` still must already be present.
+
 Start here:
 
 - [Overview](./01-overview.md)

scripts/easy-docker/README.md

@@ -5,26 +5,45 @@ Easy installation script for Frappe Docker for development and production
 ## Run
 
 ```bash
-bash easy-docker.sh
+bash ./easy-docker.sh
 ```
 
+Run the entrypoint from a real Bash environment.
+
+- On Linux, use your normal shell session.
+- On Windows, use WSL or Git Bash.
+- If you start `bash` from PowerShell, that usually means WSL, so keep the path
+  in Bash form such as `bash ./easy-docker.sh`, not `bash .\easy-docker.sh`.
+
 ## Dependencies
 
 - `gum` is used for the TUI and is installed automatically when possible
 - `docker` CLI is required and checked on startup
 - `docker compose` (Compose v2 command) is required and checked on startup
+- `jq` is required for stack JSON handling and is checked on startup
 - Docker Desktop includes Compose v2 by default; on Linux Engine-only setups you may need the `docker-compose-plugin` package
 - Docker daemon must be running before the TUI starts
 - Required docker commands are validated (`docker ps/exec/inspect/cp` and `docker compose config/up/down/logs/exec/pull/ps`)
-- If package manager installation for `gum` fails, the script can use a pinned GitHub binary fallback
-- The GitHub fallback is pinned to `gum` `v0.17.0` and verifies SHA256 checksums from `scripts/easy-docker/config/gum-checksums.tsv`
+- Startup validation order is: CLI options, `gum`, `docker`, then `jq`
+- If package manager installation for `gum` or `jq` fails, the script can use a pinned GitHub binary fallback
+- The `gum` fallback is pinned to `gum` `v0.17.0` and verifies SHA256 checksums from `scripts/easy-docker/config/gum-checksums.tsv`
+- The `jq` fallback is pinned to `jq` `1.8.1` and verifies SHA256 checksums from `scripts/easy-docker/config/jq-checksums.tsv`
+- `docker` still has no installation fallback path and must already be present
+- Runtime `jq` resolution accepts either `jq` or `jq.exe`, so Windows-native setups with only `jq.exe` on `PATH` are supported
+
+## JSON Handling
+
+- `metadata.json` remains the source of truth for stack state
+- `apps.json` is still generated from stack metadata and still used for the image build
+- `easy-docker` now reads and writes stack JSON through `jq` instead of line-based `awk` parsing
+- This is an internal robustness change only; the generated layout of `metadata.json` and `apps.json` is intended to stay the same for users
 
 ## Options
 
 - `-h`, `--help`
   - Shows usage and exits without starting the TUI
 - `--no-installation-fallback`
-  - Disables GitHub binary fallback for `gum`
+  - Disables GitHub binary fallback prompts for `gum` and `jq`
   - If package manager installation fails, the script exits with manual installation guidance
 
 ## Apps Catalog