Add desktop Gecko vertical probe

README.md

@@ -55,6 +55,7 @@ python3 -m unittest discover -s tests
 - [Browser builds](docs/browser-builds.md)
 - [Candidate transports](docs/candidate-transports.md)
 - [Configuration](docs/configuration.md)
+- [Desktop vertical](docs/desktop-vertical.md)
 - [Fixture manifests](docs/fixture-manifests.md)
 - [Mobile browser](docs/mobile-browser.md)
 - [Open flow](docs/open-flow.md)

docs/architecture.md

@@ -47,6 +47,8 @@ is boring, and generated fixtures from AMPG open without manual proxy setup.
 Generated backend metadata lives in
 [generated browser strategy](generated/browser-strategy.md).
 
+The first implementation path is documented in [desktop vertical](desktop-vertical.md).
+
 ## Relationship To AMPG
 
 AMPG publishes protocol-specific site variants. AMPB opens those variants with the right

docs/browser-builds.md

@@ -35,6 +35,33 @@ The script creates:
 - `/tmp/ampb-browser-build/artifacts`
 - `/tmp/ampb-browser-build/logs`
 
+## Desktop Build Probe
+
+Desktop is the first browser proof. The probe uses the current Gecko checkout and writes
+its mozconfig, object directory, caches, and logs under `/tmp`.
+
+Print the desktop build entrypoint help:
+
+```sh
+sh tools/browser-desktop-build-probe.sh
+```
+
+Run the first desktop configure probe:
+
+```sh
+AMPB_DESKTOP_BUILD_PROBE_MODE=configure sh tools/browser-desktop-build-probe.sh
+```
+
+The probe writes:
+
+- `/tmp/ampb-browser-build/mozconfigs/desktop-debug.mozconfig`
+- `/tmp/ampb-browser-build/obj/gecko-desktop-debug`
+- `/tmp/ampb-browser-build/logs/gecko-desktop-mach-help.log`
+- `/tmp/ampb-browser-build/logs/gecko-desktop-mach-configure.log`
+
+Configure mode may install Mozilla build Python helpers such as `zstandard` into mach
+virtualenvs under `/tmp/ampb-browser-build/cache/mozbuild`.
+
 ## Source Plan
 
 Print the canonical source targets and paths:
@@ -77,7 +104,8 @@ AMPB_INCLUDE_LEGACY_FIREFOX_ANDROID=1 sh tools/browser-source-sync.sh
 
 ## Android Build Probe
 
-Run the first Android build-discovery command from the `/tmp` checkout while keeping
+Android remains a first-class target, but it follows the desktop proof. Run the first
+Android build-discovery command from the `/tmp` checkout while keeping
 Gradle, pip, Python bytecode, and Mozilla build state in `/tmp`:
 
 ```sh

docs/desktop-vertical.md

@@ -0,0 +1,28 @@
+# Desktop Vertical
+
+> Status: draft | Updated 2026-07-07 | Applies to: AMPB desktop builders
+
+The first AMPB browser proof is desktop-first with mobile constraints kept in view. The
+vertical is a bundled Gecko desktop runtime, AMPB-owned profile state, and a managed Tor
+runtime for `.onion` browsing. Android and iOS follow the same routing and transport
+contracts after the desktop path is proven.
+
+## Build Path
+
+Use the external build workspace:
+
+```sh
+sh tools/browser-build-workspace.sh
+sh tools/browser-source-sync.sh
+AMPB_DESKTOP_BUILD_PROBE_MODE=configure sh tools/browser-desktop-build-probe.sh
+```
+
+The desktop probe keeps Gecko source, object files, downloaded toolchains, Python
+virtualenvs, pip cache, and logs under `/tmp/ampb-browser-build`.
+
+## Transport Path
+
+The first transport target is Tor through an AMPB-owned Arti/Tor runtime. The desktop
+vertical is not complete until AMPB can start the runtime, verify the SOCKS endpoint, and
+launch the bundled browser profile without clearnet fallback. I2P and Reticulum use the
+same route, consent, state, and health-check model after Tor works.

tools/browser-desktop-build-probe.sh

@@ -0,0 +1,68 @@
+#!/bin/sh
+set -eu
+
+root="${AMPB_BROWSER_BUILD_ROOT:-/tmp/ampb-browser-build}"
+gecko_dir="$root/src/gecko-dev"
+mode="${AMPB_DESKTOP_BUILD_PROBE_MODE:-help}"
+log="$root/logs/gecko-desktop-mach-${mode}.log"
+mozconfig="$root/mozconfigs/desktop-debug.mozconfig"
+objdir="$root/obj/gecko-desktop-debug"
+
+if [ ! -d "$gecko_dir" ]; then
+  printf 'missing gecko checkout: %s\n' "$gecko_dir" >&2
+  exit 1
+fi
+
+mkdir -p "$root/cache/gradle"
+mkdir -p "$root/cache/mozbuild"
+mkdir -p "$root/cache/pip"
+mkdir -p "$root/cache/pycache"
+mkdir -p "$root/logs"
+mkdir -p "$root/mozconfigs"
+mkdir -p "$objdir"
+
+cat >"$mozconfig" <<EOF
+mk_add_options MOZ_OBJDIR=$objdir
+ac_add_options --enable-application=browser
+ac_add_options --disable-crashreporter
+ac_add_options --disable-debug
+ac_add_options --enable-optimize
+EOF
+
+cd "$gecko_dir"
+
+mach_env() {
+  MOZCONFIG="$mozconfig" \
+  MOZBUILD_STATE_PATH="$root/cache/mozbuild" \
+  GRADLE_USER_HOME="$root/cache/gradle" \
+  PIP_CACHE_DIR="$root/cache/pip" \
+  PYTHONPYCACHEPREFIX="$root/cache/pycache" \
+    "$@"
+}
+
+ensure_zstandard() {
+  for python_bin in "$root"/cache/mozbuild/srcdirs/*/_virtualenvs/build/bin/python "$root"/cache/mozbuild/srcdirs/*/_virtualenvs/common/bin/python; do
+    [ -x "$python_bin" ] || continue
+    if "$python_bin" -c 'import zstandard' >/dev/null 2>&1; then
+      continue
+    fi
+    PIP_CACHE_DIR="$root/cache/pip" "$python_bin" -m pip install 'zstandard<=0.23.0,>=0.11.1'
+  done
+}
+
+case "$mode" in
+  help)
+    mach_env ./mach build --help >"$log" 2>&1
+    ;;
+  configure)
+    mach_env ./mach build --help >/dev/null 2>&1
+    ensure_zstandard
+    mach_env ./mach configure >"$log" 2>&1
+    ;;
+  *)
+    printf 'unsupported AMPB_DESKTOP_BUILD_PROBE_MODE: %s\n' "$mode" >&2
+    exit 2
+    ;;
+esac
+
+printf 'AMPB_DESKTOP_BUILD_PROBE status=ok mode=%s mozconfig=%s objdir=%s log=%s\n' "$mode" "$mozconfig" "$objdir" "$log"

tools/browser-source-plan.sh

@@ -16,4 +16,5 @@ printf 'AMPB_TOR_BROWSER_BUILD_REPO=%s\n' "$tor_build_repo"
 printf 'AMPB_TOR_BROWSER_BUILD_DIR=%s\n' "$root/src/tor-browser-build"
 printf 'AMPB_GRADLE_USER_HOME=%s\n' "$root/cache/gradle"
 printf 'AMPB_MOZBUILD_STATE_PATH=%s\n' "$root/cache/mozbuild"
-printf 'AMPB_BUILD_LOG=%s\n' "$root/logs/gecko-android-mach-probe.log"
+printf 'AMPB_DESKTOP_BUILD_LOG=%s\n' "$root/logs/gecko-desktop-mach-help.log"
+printf 'AMPB_ANDROID_BUILD_LOG=%s\n' "$root/logs/gecko-android-mach-probe.log"