release: 4.0.0 as the base line + docs/vocabulary migration

.docker/autobdd-base.dockerfile

@@ -72,6 +72,10 @@ RUN apt-get update -y && \
 # ---------------------------------------------------------------------------
 # Exact + checksum-verified (NFR-P3/P5): the official tarball, not a floating apt repo.
 # Node 20 reached EOL 2026-04-30; 24 is the active LTS (EOL 2028-04-30).
+# The product version this image is built as. It is recorded in /etc/autobdd-versions and
+# reported by `autobdd --version`; the framework image selects its base with the same arg
+# (FROM xyteam/autobdd-base:${AUTOBDD_VERSION}).
+ARG AUTOBDD_VERSION=4.0.0
 ARG NODE_VERSION=24.21.0
 ARG NODE_SHA256=fd8e59d5a511510f6a298afb548f18c7d2b1be404d8b4a27d94fbe49f56cb2d6
 RUN curl -fsSL -o /tmp/node.tar.xz "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz" && \
@@ -128,12 +132,13 @@ EXPOSE 22
 # Record the resolved versions this base was built with (NFR-P4). The framework appends
 # its own (Chrome/chromedriver) lines to the same file.
 RUN { echo "# autobdd-base"; \
+      echo "version=${AUTOBDD_VERSION}"; \
       echo "os=$(. /etc/os-release; echo $PRETTY_NAME)"; \
       echo "ubuntu_digest=sha256:224a1869083a311ef3f13648a154ba79832fbef6364d31493642ca03082da254"; \
       echo "java=$(java -version 2>&1 | head -1)"; \
       echo "node=$(node -v)"; \
       echo "python=$(python3 --version 2>&1)"; \
-      echo "oculix=$(ls /opt/autobdd/third_party/xysikulixapi/lib 2>/dev/null | grep -E '\.jar$' | head -1)"; \
+      echo "oculix=$(ls /opt/autobdd/seam/lib 2>/dev/null | grep -E '\.jar$' | head -1)"; \
       for p in openjdk-17-jdk xvfb openbox x11vnc arc-theme lxde imagemagick ffmpeg \
                xdotool wmctrl xdg-utils python3 python3-pip supervisor tini \
                fonts-wqy-microhei fonts-wqy-zenhei; do \

.github/workflows/conformance.yml

@@ -18,7 +18,9 @@ on:
   workflow_dispatch:
 
 env:
-  AUTOBDD_VER: "dev"
+  # AUTOBDD_VER is resolved from package.json by the first step: it is the product version,
+  # the image tag, and (via --build-arg) the tag the framework image pins as its base. Using
+  # one value for all three is what lets the base suite gate the declared release.
   # NFR-S2 budgets, in GB of compressed pull size (see the sizes step for the metric).
   BASE_BUDGET_GB: "2.5"
   FRAMEWORK_BUDGET_GB: "3.5"
@@ -34,6 +36,16 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      # package.json is the single source of truth for the product version. Everything below
+      # derives from it: the build arg, the image tags, and the expectation the base suite
+      # gates on -- so a version drift anywhere fails the build instead of shipping.
+      - name: Resolve version
+        run: |
+          set -euo pipefail
+          ver="$(node -p "require('./package.json').version")"
+          echo "AUTOBDD_VER=${ver}" >> "${GITHUB_ENV}"
+          echo "### building ${ver}" >> "${GITHUB_STEP_SUMMARY}"
+
       - name: Build autobdd-base + autobdd-framework
         run: |
           docker build --build-arg AUTOBDD_VERSION="${AUTOBDD_VER}" \
@@ -96,6 +108,8 @@ jobs:
       - name: autobdd-base-test (no browser)
         working-directory: test-projects/autobdd-base-test
         env:
+          AutoBDD_Ver: ${{ env.AUTOBDD_VER }}      # the tag this workflow built
+          EXPECTED_VERSION: ${{ env.AUTOBDD_VER }} # the release the image must report
           USER: runner
           HOSTOS: Linux
           USERID: "1001"
@@ -106,6 +120,7 @@ jobs:
       - name: autobdd-framework-test (e2e, baked image)
         working-directory: test-projects/autobdd-framework-test
         env:
+          AutoBDD_Ver: ${{ env.AUTOBDD_VER }}
           USER: runner
           HOSTOS: Linux
           USERID: "1001"

CHANGELOG.md

@@ -159,6 +159,44 @@ in `findTargetImage`, all fixed here:
 
 The v1 release cuts when Phase B is green and publishes the two tags.
 
+## v4.0.0
+
+**A re-scope, not a re-baseline: the base becomes the product.** `v3.0.0` is untouched —
+tag, release and image stay exactly as shipped, as the last release of the framework line.
+`v4.0.0` is cut from it and narrows the product to the **substrate**: a docker-runnable GUI
+(Xvfb + openbox + x11vnc) with the Oculix screen engine behind one CLI, so that higher-level
+tools — a framework, a script, an agent — drive it. No browser, no test runner, no BDD layer.
+
+What that meant in practice, all in this release:
+
+* **One interface.** `autobdd <verb>` replaced the bare `findTargetImage` binary:
+  `autobdd find-target` locates a target (a picture, or text) and optionally acts on it;
+  `autobdd read-text` reads the screen. The v1 name remains a deprecated alias.
+* **A vocabulary that reads as an instruction.** `--match-image` / `--match-text` name the
+  target; `--min-score`, `--max-score`, `--wait=5s`, `--limit`, `--box`, `--psm`, `--oem`
+  state everything once for both modalities; actions are composable flags (`--hover --click`).
+  Every v1 flag is translated, with a stderr-only warning.
+* **Discoverability.** `--help`/`--list`/`--version` answer in ~40 ms **without starting the
+  engine** (measuring the old behaviour: 3079 ms and a whole-screen scan, with zero usage
+  strings in the binary); unusable values exit 2 instead of silently defaulting.
+* **A self-contained image.** The Oculix natives bundled in the engine JAR are extracted at
+  build time into `/opt/oculix-natives` and registered with `ldconfig`: no runtime
+  extraction, no writable `/tmp` or `/root` needed.
+* **A conformance suite that is also the spec.** 44 features / 131 checks, each independently
+  reproducible (`base-test/one.sh <feature>`), each printing the exact command it ran and the
+  value it observed. Writing it found and fixed six real defects in the engine, and five in
+  the suite's own narration.
+* **The image reports what it is.** `version=` is recorded in `/etc/autobdd-versions` and
+  printed by `autobdd --version`, and CI resolves that value from `package.json` so the
+  build arg, the image tags and the suite's expectation cannot drift: the base suite checks
+  that `--version` agrees with the image's own stamp, and — when `EXPECTED_VERSION` is set —
+  that both equal the declared release. Unset (a local run) it checks consistency only, so
+  the same suite works for a `dev` build and for a release build.
+
+The framework image (`xyteam/autobdd-framework`, and the `xyteam/autobdd` alias) remains on
+the 3.0.0 line; it pins its base via `AUTOBDD_VERSION`, so re-baselining it onto 4.0.0 is a
+later, separate change that must pass the framework e2e suite.
+
 ## v3.0.0
 
 The runtime re-baseline — the continuation of v2.4.0.