@mokoconsulting/mokoabs-mcp 0.0.0-stage → 4.0.2

package/.mokogit/workflows/pre-release.yml

@@ -0,0 +1,1134 @@
+# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# FILE INFORMATION
+# DEFGROUP: MokoGIT.Workflow
+# INGROUP: MokoCLI.Release
+# REPO: https://git.mokoconsulting.tech/MokoConsulting/Template-Generic
+# PATH: /.mokogit/workflows/pre-release.yml
+# VERSION: 07.15.00
+# CHANGE (07.15.00): "Vendor PHP dependencies (build-time)" is no longer a silent no-op on the release runners. The step existed since 07.xx but EVERY vendored build was failing invisibly: the runners' php-cli ships WITHOUT ext-gd, so composer could not RESOLVE mpdf/mpdf at all ("mpdf/mpdf require ext-gd * -> it is missing from your system"), and the step's continue-on-error + `|| warning` fail-soft swallowed that into a green build — the zip then shipped WITHOUT admin/vendor while the component manifest lists <folder>vendor</folder>, so JInstaller aborts the ENTIRE package install on-site ("File does not exist [ROOT][TMP]/.../admin/vendor" → "Failed to copy administrator files"; reproduced on MokonyxCRMDCM + MokonyxCRM dev installs). Fix: (1) provision ext-gd when missing before resolving; (2) verify the package's CONFIGURED vendor-dir (composer config vendor-dir, e.g. admin/vendor) actually materialized autoload.php; (3) when vendoring fails for a package whose Joomla manifest ships <folder>vendor</folder>, FAIL the build loud (::error:: + exit 1, continue-on-error removed) — a broken artifact that bricks installs is strictly worse than a red build. Packages whose manifests do NOT reference vendor/ keep the old fail-soft warning, and repos with no sub-package composer.json are a clean no-op, so non-vendoring repos are 100% unaffected. PREVIOUS (07.14.00): #469 — gate the dev-channel version BUMP on whether the push touched the Makefile SRC_DIR. The former non-code/test paths-ignore denylist on the dev push trigger is REMOVED: a docs/workflow/sample/test-only push no longer skips the build, it now RUNS in no-bump "update the current rolling dev release in place" mode. A new step "Resolve SRC_DIR bump gate (#469)" (id: srcgate) mirrors auto-release.yml: (1) electron (file-detected) or opt-out vars.RELEASE_SRCDIR_GATE=off -> bypass/always-bump; (2) else SRC_DIR REQUIRED, missing -> fail loud; (3) else diff before..sha (HEAD^1 fallback) ∩ ${SRC_DIR}/ -> should_bump. The per-merge dev-base patch bump ("Advance dev base") is now gated on should_bump!='false', so a non-source push keeps the dev base PUT and the rest of the job re-issues the existing rolling dev release. Loop-safety unchanged (job if: still re-checks [skip ci]/[skip bump]). Fleet-wide release-semantics change. PREVIOUS (07.13.00): the dev-base-bump and checkout-fallback steps now name the per-run token env var GITHUB_TOKEN (was the misleadingly-named MOKOGIT_TOKEN; the VALUE was always ${{ github.token }}). Same-repo writes (the dev base bump) use the built-in per-run github.token with contents:write — NEVER the org MOKOGIT_TOKEN secret, which this workflow does not reference at all. Naming-only; no behavior change. (The earlier "it's an org secret" framing was wrong — MokoGIT#1721.) PREVIOUS (07.12.00): "Advance dev base (per-merge patch bump)" now FAILS the step (::error:: + exit 1) when release_bump_dev reports failure (0 version files stamped), instead of the old ::warning:: + exit 0. A stalled bump (e.g. a repo-side Contents-API HTTP 500 on release_bump_dev's temp-branch write) was silently re-cutting the SAME dev version on every merge — for ~10 merges on MokonyxTickets — so the Joomla update feed stayed at the installed version and NO update was ever offered, invisibly, because the step stayed green. Failing loud turns the pre-release RED so the stall is caught immediately. The GITHUB_TOKEN-unset and #1412 "already advanced" branches keep their graceful exit 0 (not failures). See MokoGIT#1721.
+# BRIEF: NEW (07.15.00): build-time PHP vendoring is now LOUD and actually works on the runners — ext-gd provisioned (mpdf resolution failed without it), configured vendor-dir verified (autoload.php), and a vendoring failure for a package whose manifest ships <folder>vendor</folder> FAILS the build (continue-on-error removed) instead of green-shipping a zip that bricks the whole package install on JInstaller "File does not exist .../admin/vendor" (MokonyxCRMDCM/MokonyxCRM). PREVIOUS: NEW (07.13.00): dev-base-bump + checkout-fallback token env var renamed MOKOGIT_TOKEN → GITHUB_TOKEN (value unchanged = ${{ github.token }}; same-repo writes use the per-run github.token, never the org secret — naming clarity, MokoGIT#1721). PREVIOUS: NEW (07.12.00): the per-merge dev base bump now fails the pre-release (::error:: + exit 1) on a 0-file stamp instead of silently re-cutting the current version (MokoGIT#1721 — a stalled bump hid for ~10 merges on MokonyxTickets). PREVIOUS: NEW (07.11.00): Setup MokoCLI tools no longer installs a STALE mokocli during the registry publish-lag window (#1671). After the fresh registry install, the step compares the installed /tmp/mokocli PROJECT_VERSION against the /opt/mokocli failsafe and PREFERS whichever is NEWER (sort -V); the opportunistic /opt refresh is gated to only move FORWARD (never downgrade /opt when it is the newer, just-deployed copy). Backward-compatible: runners with no /opt/mokocli use the registry copy exactly as before. PREVIOUS (07.09.00): the "Cascade alpha + beta on base-version bump" step is REMOVED entirely (was opt-in via vars.PRERELEASE_CASCADE in 07.08.01). A dev push now cuts ONLY the development channel; alpha, beta and rc are ON-DEMAND ONLY — cut solely via manual workflow_dispatch (stability=alpha|beta|release-candidate). This is the durable fix: no repo/org var can re-enable an automatic alpha/beta cut. PREVIOUS (07.08.01): the "Cascade alpha + beta on base-version bump" step was OPT-IN via vars.PRERELEASE_CASCADE=true (default OFF). A dev push cuts ONLY the development channel; alpha/beta/rc come solely from manual workflow_dispatch. Previously alpha+beta auto-re-cut on every committed base bump, making Joomla offer the -beta build even to Dev-channel sites. NEW (07.08.00): electron repos now create NO release and build NO installer in CI on ANY channel (publish forced off for electron; opt back in with vars.ELECTRON_CI_BUILD=true) — always built locally + uploaded manually; the version BUMP still runs. Template-Generic #390. NEW (07.07.00): the electron installer build/attach steps (electron-builder via Wine/Xvfb) are gated to MANUAL workflow_dispatch only (`&& github.event_name == 'workflow_dispatch'`). A dev push no longer auto-builds electron installers (heavy ~90m, runner-fragile — OOM/Wine-zombie; migrating to mokocli ElectronPackager, MokoCLI #756/#758). The per-merge dev base bump ("Advance dev base") and "Resolve metadata and bump version" STILL run on push — only the electron installer is skipped and pushed MANUALLY via dispatch. Non-electron repos unaffected. Template-Generic #390. Pre-release on dev push + manual dispatch (rolling dev/rc asset, build-metadata version — #404/#1313: the build counter is folded into the PATCH with a single -<stability> suffix and NO dotted ".N" — the retired ".N" counter broke Joomla's updater fleet-wide, see the "Resolve metadata and bump version" step); non-Joomla MokoGIT release + cosmetic release-notes are best-effort. npm publishing is ABSORBED here (07.05.00) and CORRECTED (07.06.00): dev/alpha/beta/rc builds publish via plain `npm publish` (dist-tagged by channel) to the MokoGIT npm registry ONLY (per-run token; public npmjs is stable-only), is_npm-gated so non-npm repos are unaffected. The prior `moko publish` variant only made a git release (mokocli has no npm-publish verb), so dev builds never reached a registry. The dev push trigger skips [skip ci]/[skip bump] commits. NEW (06.04.00): on a dev push that BUMPS the committed base version, alpha + beta are re-cut at the same base so the whole pre-release ladder (dev/alpha/beta, plus rc/stable via auto-release) stays in lockstep — previously alpha/beta were cut only by manual dispatch and froze. Joomla-family + push only; additive, isolated, continue-on-error; single job (no matrix) to keep the fleet wave small. (Ported from Template-Joomla 06.06.00 — same step, `moko package` variant.) NEW (07.00.00): ladder-bootstrap step removed (channel ladder no longer auto-created here); `moko assets:optimize` artifact-time step added before packaging (graceful-skip on non-asset repos); Setup MokoCLI tools makes the fresh `moko` executable + first on PATH to fix exit-126 (mokocli #650). NEW (07.02.00): versioning comments corrected to the current scheme (MokoGIT #1313 — dev/rc patch-bump the base, single suffix, no dotted .N counter). CONSEQUENCE of re-cutting alpha/beta/dev at the SAME base: Joomla keeps the highest-precedence variant of a given base (beta > alpha > dev), so a site — even at minimum-stability Dev — is offered the -beta build of the newest base, not -dev. To pin a site to the -dev line, don't publish alpha/beta at that base (or point the site's update channel at dev), NOT by lowering minimum-stability (Dev is already the most permissive floor).
+
+name: "Universal: Pre-Release"
+
+# #404 — moved OFF every-push to a nightly schedule + manual dispatch. Building a
+# dev/rc pre-release on every push (and committing a version bump back) caused
+# manifest <version> merge conflicts and wasted CI builds + void versioned dev
+# assets. Batching to nightly removes most of that load; the version now advances
+# as BUILD METADATA (version_build_metadata.php) instead of a committed bump, and
+# the asset is published under a FIXED rolling name replaced in place.
+on:
+  # Dev-channel release on every merge to dev. Uses build-metadata versioning
+  # (version_build_metadata.php) so nothing is committed back to dev — the #404
+  # manifest <version> merge-conflict problem does NOT return. The concurrency guard
+  # below collapses a burst of merges into one.
+  #
+  # #469: the former non-code paths-ignore denylist (which SKIPPED docs / CI config /
+  # test-only / repo-metadata pushes entirely) is REMOVED. Such a push must now RUN
+  # the pipeline in no-bump "update the current rolling dev release in place" mode
+  # rather than be dropped: the in-job SRC_DIR-diff gate (steps.srcgate below) decides
+  # bump (push touched ${SRC_DIR}/) vs no-bump (it did not). Loop-safety is unchanged
+  # and fully covered by the job if: [skip ci]/[skip bump] re-checks, so the
+  # per-merge dev-base bump's own [skip ci] commit never re-triggers this workflow.
+  push:
+    branches:
+      - dev
+  workflow_dispatch:
+    inputs:
+      stability:
+        description: 'Pre-release channel'
+        required: true
+        default: development
+        type: choice
+        options:
+          - development
+          - alpha
+          - beta
+          - release-candidate
+      ref:
+        description: 'Branch to build (default: dev)'
+        required: false
+        default: dev
+        type: string
+
+concurrency:
+  # Per channel + ref. A manual alpha/beta/rc dispatch has its own group, so it is
+  # never cancelled by a dev push (and vice versa); the nightly runs on the
+  # default-branch ref, a different group again.
+  #
+  # cancel-in-progress is TRUE: the release-runner fleet is capacity-constrained and
+  # cannot be scaled, and a full electron build is ~90 min, so a BURST of dev merges
+  # must not each run a serial build (that backs the runner up for hours). A
+  # superseding build cancels the older one and builds only the latest state.
+  # Safe for the pre-release channels: they publish to a ROLLING, last-write-wins
+  # tag, so a cancelled build's publish is simply re-done by the winning (latest)
+  # build; real STABLE releases go through auto-release.yml, which keeps its own
+  # serialized safety (cancel-in-progress:false there). Trade-off: a
+  # concurrency-CANCELLED run marks the commit combined status red on Gitea, but
+  # that status is cosmetic (CI is non-gating for merges) and is always superseded
+  # by the winning build green. The ~150x sync storm stays prevented by the
+  # paths-ignore denylist + the job-level ref gate.
+  group: pre-release-${{ github.ref }}-${{ inputs.stability || 'development' }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+  packages: write
+  pull-requests: write
+
+env:
+  GIT_URL: ${{ vars.MOKOGIT_URL || 'https://git.mokoconsulting.tech' }}
+  GIT_ORG: ${{ vars.MOKOGIT_ORG || github.repository_owner }}
+  GIT_REPO: ${{ vars.MOKOGIT_REPO || github.event.repository.name }}
+
+jobs:
+  build:
+    name: "Build Pre-Release (${{ inputs.stability || 'development' }})"
+    # LITERAL runner label — do NOT use ${{ vars.RELEASE_RUNNER_LABEL || 'release' }}.
+    # This MokoGIT/Gitea instance does not resolve the `|| 'release'` fallback for an
+    # unset var in the `runs-on` position, so the job gets no runner and aborts at the
+    # container level (every step, incl. step-0, marked failure). Runners are correct;
+    # the only registered release runner label is `release`. See #366 (regression) and
+    # #134 (same class: runs-on ubuntu-latest -> no runner).
+    runs-on: release
+    # Bound a hung/starved build so it can't squat the scarce release runner for
+    # hours (the act_runner default let stuck builds run ~3h before failing). A
+    # healthy package/electron build is well under this; anything past it is
+    # stuck and should fail fast to free the runner. Repos with a legitimately
+    # longer build override via the PRERELEASE_BUILD_TIMEOUT repo variable.
+    timeout-minutes: ${{ fromJSON(vars.PRERELEASE_BUILD_TIMEOUT || '90') }}
+    # Skip on template repos (Template-*) — they scaffold other repos and do not release.
+    # Triggers: push to dev (per-merge dev-channel build), the nightly schedule
+    # (safety-net batch), and manual workflow_dispatch. The push trigger is scoped
+    # to `dev` + a non-code paths-ignore, so a template-sync/doc-only push can't
+    # reach it (the ~150x storm on chore/template-sync-* stays prevented).
+    # As defence-in-depth we also refuse a manual dispatch aimed at a bot/sync ref.
+    if: >-
+      github.event.repository.name != '.vault' &&
+      (
+        (
+          github.event_name == 'push' &&
+          !contains(github.event.head_commit.message, '[skip ci]') &&
+          !contains(github.event.head_commit.message, '[skip bump]')
+        ) ||
+        github.event_name == 'schedule' ||
+        (
+          github.event_name == 'workflow_dispatch' &&
+          !startsWith(inputs.ref, 'chore/') &&
+          !startsWith(inputs.ref, 'sync/') &&
+          !startsWith(inputs.ref, 'bot/') &&
+          !startsWith(inputs.ref, 'template-sync')
+        )
+      )
+
+    steps:
+      # Build ref: the dispatch input if given, else `dev` — which is correct for
+      # both a push (only `dev` triggers it) and the nightly schedule (where
+      # github.ref_name would otherwise be the default branch, main).
+      - name: Resolve build ref
+        id: ref
+        run: echo "ref=${{ inputs.ref || 'dev' }}" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ github.token }}
+          ref: ${{ steps.ref.outputs.ref }}
+          submodules: false
+
+      # #1672: transient step-0 checkout aborts on the shared `release` runners under
+      # release-time load. This fallback fires ONLY when the checkout above failed
+      # (step-level `if: failure()` — a LITERAL, not a discarded continue-on-error
+      # expression) and re-materialises the workspace via a bounded 3-attempt git
+      # clone + backoff, checking out the SAME resolved build ref
+      # (steps.ref.outputs.ref) the checkout targeted. fetch-depth: 0 is preserved
+      # with a FULL clone (no --depth) + tags (the bump/version steps below need
+      # history + tags). Fails loudly (exit 1) after 3 attempts so a real breakage is
+      # never masked. Independent step — no needs:+always() fan-in.
+      - name: "Checkout fallback (retry transient flake) (#1672)"
+        if: failure()
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          BUILD_REF: ${{ steps.ref.outputs.ref }}
+        run: |
+          set -u
+          TOK="$(printf '%s' "$GITHUB_TOKEN" | tr -d '[:space:]')"; echo "::add-mask::$TOK"
+          SERVER="${GITHUB_SERVER_URL:-https://git.mokoconsulting.tech}"
+          CLONE_URL="https://x-access-token:${TOK}@${SERVER#https://}/${GITHUB_REPOSITORY}.git"
+          REF="${BUILD_REF:-${GITHUB_SHA:-}}"
+          echo "Retrying full-history checkout of ${GITHUB_REPOSITORY}@${REF:-<HEAD>} into ${GITHUB_WORKSPACE}"
+          ok=0
+          for attempt in 1 2 3; do
+            rm -rf "${GITHUB_WORKSPACE:?}/.git" 2>/dev/null || true
+            find "${GITHUB_WORKSPACE}" -mindepth 1 -maxdepth 1 -exec rm -rf {} + 2>/dev/null || true
+            if git clone "$CLONE_URL" "${GITHUB_WORKSPACE}" \
+               && git -C "${GITHUB_WORKSPACE}" fetch --tags origin \
+               && { [ -z "$REF" ] || git -C "${GITHUB_WORKSPACE}" checkout -f "$REF"; }; then
+              ok=1; echo "Fallback checkout succeeded on attempt ${attempt}."; break
+            fi
+            echo "::warning::Fallback checkout attempt ${attempt} failed; backing off $((attempt * 5))s"
+            sleep $((attempt * 5))
+          done
+          if [ "$ok" != "1" ]; then
+            echo "::error::Checkout failed after 3 retry attempts (#1672) — this is not a transient flake, failing loudly."
+            exit 1
+          fi
+
+      - name: Update submodules to latest
+        # Skip cleanly on submodule-less repos. The old step was a silent no-op:
+        # `2>/dev/null || true` swallowed every error and the in-step `git pull`
+        # used an UN-credentialed remote, so private submodules never actually
+        # updated. Credential the private remote, then update each submodule to its
+        # tracked branch (default: the submodule's default branch) so the built
+        # package contains the latest submodule content. Per #404 this is
+        # working-tree only (no commit) — the package is built from the working tree.
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          if [ -f .gitmodules ]; then
+            # Mask the token (trim + ::add-mask::) before embedding it in the git
+            # config URL rewrite — matches the checkout-fallback step's hygiene and
+            # keeps the derived value out of logs (#1840). --global is required so the
+            # rewrite reaches the submodule fetch subprocesses.
+            TOK="$(printf '%s' "$GITHUB_TOKEN" | tr -d '[:space:]')"; echo "::add-mask::$TOK"
+            git config --global url."https://x-access-token:${TOK}@git.mokoconsulting.tech/".insteadOf "https://git.mokoconsulting.tech/"
+            git submodule sync --recursive || true
+            # FAIL-OPEN (#430): the per-run Actions token is scoped to THIS repo, so a
+            # cross-repo submodule can return "Repository not found" and abort the whole
+            # release (seen: MokonyxCRM addons/* -> pre-release red). Warn loudly but do
+            # NOT red the build — the package is built from the working tree, and any
+            # accessible submodules still update.
+            git submodule update --init --remote --recursive \
+              || echo "::warning::submodule update failed (inaccessible/optional cross-repo submodule; run token may lack read). Building from the working tree without it — see Template-Generic #430."
+          else
+            echo "No .gitmodules — skipping submodule update."
+          fi
+
+      - name: Isolate workspace (remove foreign/stale checkouts)
+        run: |
+          find . -name .git -not -path './.git' -prune -print | while read nested; do
+            dir=$(dirname "$nested")
+            [ "$dir" = "." ] && continue
+            git ls-files --error-unmatch "$dir" >/dev/null 2>&1 && continue
+            echo "::warning::Removing untracked nested checkout: $dir"
+            rm -rf "$dir"
+          done
+
+      - name: Setup MokoCLI tools
+        run: |
+          # Install mokocli FRESH from the MokoGIT Composer registry on every run
+          # (PRIMARY) so CI always uses the latest published version. /opt/mokocli is
+          # a FAILSAFE only — its refresh unit (mokocli-sync.service) is disabled, so
+          # the on-disk snapshot rots and must NOT be preferred. Registry path
+          # /api/packages/** is anon-allowlisted (no MOKOGIT_TOKEN); it serves a dist
+          # zip (no git clone). --no-install: mokocli self-bootstraps via bundled lib/
+          # + a fallback PSR-4 autoloader (native ext-curl), so no vendor/ is needed.
+          if ! command -v composer > /dev/null 2>&1; then
+            sudo apt-get update -qq && sudo apt-get install -y -qq php-cli php-mbstring php-xml php-zip php-curl composer > /dev/null 2>&1
+          fi
+          rm -rf /tmp/mokocli
+          REG='{"type":"composer","url":"https://git.mokoconsulting.tech/api/packages/MokoConsulting/composer"}'
+          if composer create-project --no-install --no-interaction --no-progress --quiet \
+               --repository="${REG}" mokoconsulting/mokocli /tmp/mokocli >/dev/null 2>&1 \
+             && [ -f /tmp/mokocli/cli/version_bump.php ]; then
+            echo "Installed mokocli fresh from the Composer registry (primary)"
+            # #1671: registry-publish LAG race. The registry install "succeeds" but can
+            # serve the PREVIOUS package for ~tens of seconds after a MokoCLI release
+            # (publish finishes AFTER the release run reports success). Meanwhile the
+            # /opt/mokocli deploy (pull-timer) may already carry the just-released,
+            # NEWER engine. So instead of blindly using the registry copy, compare the
+            # two on-disk versions and PREFER whichever is newer. The Makefile
+            # PROJECT_VERSION is the version source of truth and ships in both the
+            # composer dist and /opt/mokocli. Backward-compatible: with no /opt/mokocli
+            # (most consumer runners), the registry copy is used exactly as before.
+            mk_ver() { sed -n 's/^[[:space:]]*PROJECT_VERSION[[:space:]]*:*=[[:space:]]*//p' "$1" 2>/dev/null | head -n1 | tr -d '[:space:]'; }
+            ver_newer() { [ "$1" != "$2" ] && [ "$(printf '%s\n%s\n' "$1" "$2" | sort -V | tail -n1)" = "$1" ]; }
+            REG_VER="$(mk_ver /tmp/mokocli/Makefile)"
+            OPT_VER="$(mk_ver /opt/mokocli/Makefile)"
+            MOKO_ROOT=/tmp/mokocli
+            if [ -f /opt/mokocli/cli/version_bump.php ] && [ -n "$OPT_VER" ] && [ -n "$REG_VER" ] \
+               && ver_newer "$OPT_VER" "$REG_VER"; then
+              echo "::notice::/opt/mokocli (${OPT_VER}) is newer than the registry copy (${REG_VER}) — using /opt (#1671 publish-lag race)."
+              MOKO_ROOT=/opt/mokocli
+            else
+              echo "Using registry copy (${REG_VER:-unknown}); /opt/mokocli=${OPT_VER:-none}"
+            fi
+            echo "MOKO_CLI=${MOKO_ROOT}/cli" >> $GITHUB_ENV
+            # #650: make the chosen moko executable + FIRST on PATH so bare `moko`
+            # never resolves to a stale/non-executable copy (exit 126).
+            for d in bin cli; do
+              if [ -f "${MOKO_ROOT}/$d/moko" ]; then
+                # #1263 defense-in-depth: strip CR bytes so a CRLF-tainted registry
+                # dist or rotted /opt snapshot can't yield `/usr/bin/env: 'php\r'`
+                # (exit 127). tr interprets \r as a real CR (unlike portable sed).
+                # /opt may be root-owned — write via a temp file + sudo when needed.
+                if tr -d '\r' < "${MOKO_ROOT}/$d/moko" > "/tmp/moko.lf" 2>/dev/null; then
+                  if cp "/tmp/moko.lf" "${MOKO_ROOT}/$d/moko" 2>/dev/null; then :; \
+                  else sudo cp "/tmp/moko.lf" "${MOKO_ROOT}/$d/moko" 2>/dev/null || true; fi
+                  rm -f "/tmp/moko.lf"
+                fi
+                chmod +x "${MOKO_ROOT}/$d/moko" 2>/dev/null || sudo chmod +x "${MOKO_ROOT}/$d/moko" 2>/dev/null || true
+                echo "${MOKO_ROOT}/$d" >> "$GITHUB_PATH"
+              fi
+            done
+            sudo chmod +x /opt/mokocli/*/moko 2>/dev/null || true
+            # Opportunistically refresh the /opt failsafe from this fresh copy when it
+            # differs — keeps the disabled-sync snapshot current so the fallback is
+            # never far behind. Best-effort: needs sudo, gated on a diff to avoid
+            # fleet-wide churn, never fails the job. #1671: only refresh FORWARD — skip
+            # when /opt is the newer copy we just chose, so we never downgrade it.
+            if [ "$MOKO_ROOT" = /tmp/mokocli ] && command -v sudo >/dev/null 2>&1 && [ -d /opt/mokocli ] \
+               && ! cmp -s /tmp/mokocli/cli/version_reset_dev.php /opt/mokocli/cli/version_reset_dev.php 2>/dev/null; then
+              sudo cp -a /tmp/mokocli/. /opt/mokocli/ 2>/dev/null \
+                && echo "Refreshed /opt/mokocli failsafe from the fresh registry copy" \
+                || echo "  (/opt failsafe refresh skipped — no sudo/perms)"
+            fi
+          elif [ -f /opt/mokocli/cli/version_bump.php ]; then
+            echo "::warning::Registry install failed — using /opt/mokocli FAILSAFE (may be stale)"
+            echo "MOKO_CLI=/opt/mokocli/cli" >> $GITHUB_ENV
+          else
+            echo "::error::mokocli unavailable: registry install failed and no /opt/mokocli failsafe present"
+            exit 1
+          fi
+
+      - name: Detect platform
+        id: platform
+        run: |
+          # PILOT: native-manifest platform detection via the MokoCLI build agent —
+          # NO metadata-API read. `moko platform:detect` (maps to platform_detect.php,
+          # detection-only) resolves the platform from the in-tree manifest and emits
+          # the single `platform` output the eligibility step below consumes. The
+          # former metadata-API-first lookup (GET /repos/.../metadata) is REMOVED; the
+          # build agent is the source of truth and no longer depends on the registry.
+          moko platform:detect --path . --github-output 2>/dev/null || true
+          # Fallback: if the agent emitted nothing (e.g. detached manifest), keep the
+          # file-based manifest read so repos still resolve a platform.
+          if ! grep -q '^platform=' "$GITHUB_OUTPUT" 2>/dev/null; then
+            echo "::notice::moko emitted no platform — falling back to manifest read"
+            moko manifest:read --path . --github-output 2>/dev/null || true
+          fi
+
+      - name: Check platform eligibility
+        id: eligibility
+        run: |
+          # Shared release engine (#122): the pre-release path runs for every
+          # artifact platform that produces releases — joomla, npm, mcp, and client. Deploy-only platforms (go) are
+          # EXCLUDED: they consume a tag but never bump/release here.
+          #
+          # is_joomla_family selects the Joomla/PHP-specific steps (manifest
+          # element/zip resolution, release_package.php zip, updates.xml). Those
+          # steps stay TRUE for the Joomla family so Joomla behavior is unchanged,
+          # and are skipped for npm/mcp/client, which ride only the platform-
+          # agnostic steps (version, tag, changelog, release-notes, release,
+          # cascade). Build/publish stay in the platform shim (ADR #124).
+          PLATFORM="${{ steps.platform.outputs.platform }}"
+          IS_JOOMLA_FAMILY=false
+          # STEP 1 — Authoritative baseline (unchanged): the hardcoded case gate
+          # remains the source of truth for `proceed` and the default value of
+          # is_joomla_family. Everything below (the registry lookup) is PURELY
+          # ADDITIVE and can only *refine* is_joomla_family for a cleanly-matched
+          # platform — it never flips `proceed`, never downgrades, and any
+          # failure/absence leaves this decision exactly as it is today.
+          # ADDITIVE + GATED (Template-Generic#326): electron / mokohub-manifest /
+          # mokohub-recipes are first-class eligible artifact platforms. They ride
+          # the platform-agnostic pre-release path (version + release + attach) and
+          # each has its OWN gated packaging step below, so joomla/npm/mcp/client
+          # behaviour is 100% unchanged. is_manifest / is_recipes drive those steps.
+          IS_MANIFEST=false
+          IS_RECIPES=false
+          IS_NPM=false
+          case "$PLATFORM" in
+            joomla*)
+              PROCEED=true
+              IS_JOOMLA_FAMILY=true
+              ;;
+            npm*)
+              PROCEED=true
+              IS_NPM=true
+              ;;
+            mcp*|client*)
+              PROCEED=true
+              ;;
+            electron*)
+              # electron is first-class eligible; the electron-builder installer
+              # legs below still self-gate on is_electron (file-detected) so a repo
+              # with an electron-builder config builds installers even before the
+              # registry classifies it (mokocli electron detection: MokoGIT #1201).
+              PROCEED=true
+              ;;
+            mokohub-manifest*)
+              PROCEED=true
+              IS_MANIFEST=true
+              ;;
+            mokohub-recipes*)
+              PROCEED=true
+              IS_RECIPES=true
+              ;;
+            *)
+              PROCEED=false
+              echo "::notice::Platform '$PLATFORM' — not an artifact release platform, skipping pre-release auto-bump"
+              ;;
+          esac
+
+          # STEP 2 — Registry enhancement (#125): classify the Joomla family from
+          # the live platform registry (GET /api/v1/platforms) so newly-registered
+          # manifest/packaging platforms get correct family classification without
+          # editing this workflow. We key on the registry `family` field: family
+          # `joomla` is exactly the Joomla-style manifest/packaging
+          # path (the manifest_element + release_package steps). We deliberately do
+          # NOT key on `manifest_based`, because npm and mcp are also
+          # manifest_based:true yet must ride the platform-agnostic path (family
+          # `node`) — so `manifest_based` is ambiguous here and `family` is the
+          # clean discriminator.
+          #
+          # Fail-safe contract: the curl is captured into a var (never allowed to
+          # crash the step under set -e -o pipefail), the JSON is parsed with a
+          # guarded python3 one-liner, and the result is only applied when it is
+          # exactly "true"/"false". On ANY of {non-200, curl error, empty/malformed
+          # JSON, parse failure, platform key absent} REGISTRY_FAMILY stays empty
+          # and we keep the STEP 1 hardcoded value untouched.
+          REGISTRY_JSON="$(curl -sf \
+            -H "Authorization: token ${{ github.token }}" \
+            "${GIT_URL}/api/v1/platforms" 2>/dev/null || true)"
+          REGISTRY_FAMILY=""
+          if [ -n "$REGISTRY_JSON" ]; then
+            # Single physical line of python3 so we stay safely inside this YAML
+            # block scalar (a column-0 continuation would terminate the scalar).
+            # Emits exactly: "true"  -> matched key, family joomla;
+            #                "false" -> matched key, some other family;
+            #                ""      -> key absent (fall back to hardcoded).
+            # On malformed/empty JSON the parse raises, 2>/dev/null hides the
+            # traceback and the trailing "|| true" keeps set -e -o pipefail from
+            # crashing the step, so REGISTRY_FAMILY stays "" and we fall back.
+            REGISTRY_FAMILY="$(printf '%s' "$REGISTRY_JSON" | PLATFORM="$PLATFORM" python3 -c 'import json,os,sys; p=os.environ.get("PLATFORM",""); f=next((x.get("family","") for x in json.load(sys.stdin) if x.get("key")==p), None); sys.stdout.write("true" if f == "joomla" else ("false" if f is not None else ""))' 2>/dev/null || true)"
+          fi
+          if [ "$REGISTRY_FAMILY" = "true" ]; then
+            IS_JOOMLA_FAMILY=true
+            echo "::notice::Registry classified '$PLATFORM' as Joomla family (via /api/v1/platforms)"
+          elif [ "$REGISTRY_FAMILY" = "false" ]; then
+            IS_JOOMLA_FAMILY=false
+            echo "::notice::Registry classified '$PLATFORM' as non-Joomla family (via /api/v1/platforms)"
+          else
+            echo "::notice::Registry lookup unavailable/absent for '$PLATFORM' — using hardcoded family classification"
+          fi
+
+          # electron (ADDITIVE + GATED): mokocli does not detect electron yet
+          # (MokoGIT #1201), so gate on an electron-builder config at the repo root
+          # and ride the platform-agnostic pre-release path (release + attach).
+          IS_ELECTRON=false
+          if [ -f electron-builder.yml ] || [ -f electron-builder.yaml ]; then
+            IS_ELECTRON=true
+            PROCEED=true
+          fi
+          echo "is_electron=${IS_ELECTRON}" >> "$GITHUB_OUTPUT"
+
+          echo "is_manifest=${IS_MANIFEST}" >> "$GITHUB_OUTPUT"
+          echo "is_recipes=${IS_RECIPES}" >> "$GITHUB_OUTPUT"
+          echo "proceed=${PROCEED}" >> "$GITHUB_OUTPUT"
+          echo "is_joomla_family=${IS_JOOMLA_FAMILY}" >> "$GITHUB_OUTPUT"
+          echo "is_npm=${IS_NPM}" >> "$GITHUB_OUTPUT"
+          # Releases on/off publish gate (.mokogit-private#73): the version BUMP
+          # runs on every eligible repo (proceed), but PUBLISH is gated on the
+          # repo's Releases unit so releases-off repos (Template-*, etc.) still
+          # bump WITHOUT publishing. Replaces the old !startsWith(name,Template-)
+          # name gate. Defaults ON unless the API explicitly returns
+          # has_releases=false (a transient error never disables a real publish).
+          HR=$(curl -sf -H "Authorization: token ${{ github.token }}" "${GIT_URL}/api/v1/repos/${{ github.repository }}" | jq -r '.has_releases' 2>/dev/null || true)
+          if [ "$PROCEED" = "true" ] && [ "$HR" != "false" ]; then PUBLISH=true; else PUBLISH=false; fi
+          # Electron: CI creates NO release and builds NO installer on ANY channel
+          # (dev/rc/stable) — always built locally + uploaded manually. The version
+          # BUMP (proceed) still runs; only the publish/build path is disabled. Opt a
+          # repo back into CI electron builds with vars.ELECTRON_CI_BUILD=true.
+          # (Template-Generic #390; electron -> mokocli ElectronPackager MokoCLI #756/#758.)
+          if [ "$IS_ELECTRON" = "true" ] && [ "${{ vars.ELECTRON_CI_BUILD }}" != "true" ]; then
+            PUBLISH=false
+            echo "::notice::electron repo — CI release/build disabled (local build + manual upload); version bump still runs"
+          fi
+          echo "publish=${PUBLISH}" >> "$GITHUB_OUTPUT"
+          echo "Publish gate: publish=${PUBLISH} (proceed=${PROCEED}, has_releases=${HR:-unknown})"
+          if [ "$PROCEED" = "true" ]; then
+            echo "::notice::Platform '$PLATFORM' eligible for pre-release (joomla_family=${IS_JOOMLA_FAMILY})"
+          fi
+
+      - name: "Resolve SRC_DIR bump gate (#469)"
+        id: srcgate
+        if: steps.eligibility.outputs.proceed == 'true'
+        # #469 (mirrors auto-release.yml): decide version-BUMP vs NO-BUMP from whether
+        # this dev push touched the Makefile source directory (SRC_DIR). Replaces the
+        # old non-code paths-ignore denylist — a docs/workflow/sample/test-only push no
+        # longer skips the build, it runs in no-bump "update the current rolling dev
+        # release in place" mode. On the dev channel the version advance is the
+        # per-merge patch bump ("Advance dev base"); should_bump=false skips it so the
+        # dev base stays put and the existing rolling dev release is simply re-issued.
+        #
+        # Gate logic (per #469):
+        #   1. ELECTRON (file-detected via steps.eligibility.is_electron) or opt-out
+        #      vars.RELEASE_SRCDIR_GATE=off -> BYPASS, keep always-bump (electron has
+        #      NO source dir, so a naive SRC_DIR test would never bump — a trap).
+        #   2. Else SRC_DIR is REQUIRED; no resolvable SRC_DIR on a non-excluded repo
+        #      -> FAIL LOUD (::error:: + exit 1), never silently never-bump.
+        #   3. Else diff the push range (before..sha, HEAD^1 fallback) intersected with
+        #      ${SRC_DIR}/ : source -> should_bump=true; none -> should_bump=false.
+        #      workflow_dispatch / schedule always bump (explicit/scheduled re-cut).
+        run: |
+          set -uo pipefail
+          if [ "${{ steps.eligibility.outputs.is_electron }}" = "true" ] || [ "${{ vars.RELEASE_SRCDIR_GATE }}" = "off" ]; then
+            echo "should_bump=true" >> "$GITHUB_OUTPUT"
+            echo "::notice::SRC_DIR gate BYPASSED (electron repo or vars.RELEASE_SRCDIR_GATE=off) — keeping always-bump behaviour (#469)."
+            exit 0
+          fi
+          if [ "${{ github.event_name }}" != "push" ]; then
+            echo "should_bump=true" >> "$GITHUB_OUTPUT"
+            echo "event=${{ github.event_name }} (dispatch/schedule) — always bump (#469)."
+            exit 0
+          fi
+          # Accept all three GNU make assignment forms: SRC_DIR=, SRC_DIR :=, and
+          # the conditional SRC_DIR ?= (the [:?]? matches an optional : or ?).
+          SRC_DIR="$(grep -m1 -E '^SRC_DIR[[:space:]]*[:?]?=' Makefile 2>/dev/null | sed -E 's/.*[:?]?=[[:space:]]*//' | tr -d '[:space:]')"
+          if [ -z "$SRC_DIR" ]; then
+            echo "::error::#469 SRC_DIR gate: no SRC_DIR resolvable from the Makefile on a non-electron repo. This is a misconfiguration — refusing to silently never-bump. Set SRC_DIR in the Makefile, or opt this repo out with vars.RELEASE_SRCDIR_GATE=off (electron-style always-bump)."
+            {
+              echo "### ❌ Pre-release gate failed — no SRC_DIR (#469)"
+              echo ""
+              echo "A non-electron repo must declare a Makefile \`SRC_DIR\`. Treating an empty SRC_DIR as \"never bump\" would silently break dev releases, so this fails loud. Fix: set \`SRC_DIR\`, or set \`vars.RELEASE_SRCDIR_GATE=off\`."
+            } >> "$GITHUB_STEP_SUMMARY"
+            exit 1
+          fi
+          SRC_DIR="${SRC_DIR%/}"
+          BEFORE="${{ github.event.before }}"
+          SHA="${GITHUB_SHA:-}"
+          RANGE=""
+          ZERO="0000000000000000000000000000000000000000"
+          if [ -n "$BEFORE" ] && [ "$BEFORE" != "$ZERO" ] && git cat-file -e "${BEFORE}^{commit}" 2>/dev/null; then
+            RANGE="${BEFORE}..${SHA}"
+          elif git rev-parse "${SHA}^1" >/dev/null 2>&1; then
+            RANGE="${SHA}^1..${SHA}"
+          fi
+          if [ -z "$RANGE" ]; then
+            echo "should_bump=true" >> "$GITHUB_OUTPUT"
+            echo "::notice::#469 SRC_DIR gate: no resolvable diff range (before=${BEFORE:-none}); defaulting to bump."
+            exit 0
+          fi
+          CHANGED="$(git diff --name-only "$RANGE" 2>/dev/null || true)"
+          SRC_HITS="$(printf '%s\n' "$CHANGED" | grep -E "^${SRC_DIR}/" || true)"
+          if [ -n "$SRC_HITS" ]; then
+            echo "should_bump=true" >> "$GITHUB_OUTPUT"
+            echo "#469 SRC_DIR gate: push touched ${SRC_DIR}/ (range ${RANGE}) — BUMP dev base + build release."
+          else
+            echo "should_bump=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::#469 SRC_DIR gate: push touched NO ${SRC_DIR}/ paths (range ${RANGE}) — NO dev-base bump; re-issuing the current rolling dev release in place."
+          fi
+
+      - name: "Require Makefile (pre-release gate)"
+        if: steps.eligibility.outputs.proceed == 'true'
+        # Enforce the same Makefile requirement as auto-release, but only when the
+        # platform is eligible to build/release (pre-release legitimately no-ops for
+        # ineligible platforms). Post-checkout step: a job-level if: cannot see the workspace.
+        run: |
+          if [ ! -f Makefile ] && [ ! -f makefile ] && [ ! -f GNUmakefile ]; then
+            echo "::error::pre-release requires a Makefile at the repository root — none found. A release-bearing repo must ship a Makefile (build/package targets). Aborting."
+            echo "## Pre-release blocked: no Makefile at repo root" >> "$GITHUB_STEP_SUMMARY"
+            exit 1
+          fi
+          echo "Makefile present — pre-release may proceed."
+
+      - name: "Advance dev base (per-merge patch bump)"
+        # RESTORES per-merge version advancement (fleet-wide dev-version freeze fix).
+        #
+        # WHY THIS EXISTS: the fleet's documented per-branch bumper — auto-bump.yml,
+        # referenced by auto-release.yml's "fix/patch/hotfix already carried their
+        # patch bump from auto-bump.yml" comment — DOES NOT EXIST in any template repo
+        # (404). Dev advancement therefore relied entirely on version_build_metadata.php
+        # folding a commit counter into the PATCH, which was removed (mokocli #459/#712)
+        # because it ballooned the dev patch past stable (e.g. 03.03.56 > stable 03.03.00)
+        # and stranded Joomla's updater. With neither mechanism, the committed dev base
+        # FREEZES between promotions: every dev build re-cuts the SAME <version>, so the
+        # updater never offers a newer dev build and merged fixes never reach dev sites.
+        #
+        # THE FIX: on a real dev merge, advance the committed base by exactly ONE clean
+        # patch via release_bump_dev.php --bump patch --no-changelog. This uses the
+        # Contents API (protected-branch bypass), is idempotent + monotonic (never moves
+        # dev down; a re-synchronize re-run is a safe no-op), and commits with a
+        # [skip ci] message so the bump does NOT re-trigger this workflow (the push
+        # trigger already filters [skip ci]/[skip bump]). +1-per-merge stays far below
+        # the next minor, so dev never outruns stable — the counter's failure mode is
+        # avoided. Changelog promotion is deliberately skipped here; it remains a
+        # promotion-time action (auto-release's release_bump_dev --bump minor).
+        #
+        # Only on a genuine dev push (never the nightly schedule or manual dispatch,
+        # and never a non-dev ref). Degrades safely: if the bump can't run (no bypass
+        # token) the build simply re-cuts the current version, exactly as today.
+        # #469: this per-merge patch bump IS the dev-channel version advance, so it is
+        # skipped in no-bump mode (steps.srcgate.should_bump=false — a non-source
+        # push). The dev base then stays put and the rest of the job re-issues the
+        # current rolling dev release in place. On the bump path it runs as before.
+        if: >-
+          steps.eligibility.outputs.proceed == 'true' &&
+          github.event_name == 'push' &&
+          steps.ref.outputs.ref == 'dev' &&
+          steps.srcgate.outputs.should_bump != 'false'
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          if [ -z "${GITHUB_TOKEN}" ]; then
+            echo "::warning::GITHUB_TOKEN unset — cannot advance the dev base; this build re-cuts the current version."
+            exit 0
+          fi
+          # #1412 idempotency: if the merge/push that triggered this build already
+          # advanced the base (e.g. a PR that pre-bumped PROJECT_VERSION), do NOT
+          # bump again - a second +1 here doubles the version. Compare HEAD's base
+          # to its first parent (fetch-depth: 0 guarantees the parent is present).
+          if git rev-parse HEAD^1 >/dev/null 2>&1; then
+            cur_v="$(grep -E '^[[:space:]]*PROJECT_VERSION[[:space:]]*:?=' Makefile 2>/dev/null | head -1 | grep -oE '[0-9][0-9.]+' | head -1 || true)"
+            par_v="$(git show HEAD^1:Makefile 2>/dev/null | grep -E '^[[:space:]]*PROJECT_VERSION[[:space:]]*:?=' | head -1 | grep -oE '[0-9][0-9.]+' | head -1 || true)"
+            if [ -n "$cur_v" ] && [ -n "$par_v" ] && [ "$cur_v" != "$par_v" ]; then
+              echo "::notice::base already advanced this merge ($par_v -> $cur_v); skipping per-merge auto-bump to avoid doubling (#1412)."
+              exit 0
+            fi
+          fi
+          API_BASE="${GIT_URL}/api/v1/repos/${GIT_ORG}/${GIT_REPO}"
+          if ! php ${MOKO_CLI}/release_bump_dev.php                  --path . --branch dev --bump patch --no-changelog                  --token "${GITHUB_TOKEN}" --api-base "${API_BASE}"; then
+            echo "::error::dev base patch-bump FAILED — release_bump_dev stamped 0 version files, so the dev base did NOT advance. Refusing to silently re-cut the current version: a stalled bump keeps the Joomla update feed at the installed version and hides across many merges (it stayed green for ~10 merges on MokonyxTickets — MokoGIT#1721). This is usually a repo-side Contents-API write failure (HTTP 500 on the bot/version-advance temp branch). Fix the bump and re-run."
+            exit 1
+          fi
+          # release_bump_dev.php writes the BRANCH (Contents API), not the local
+          # checkout. Mirror the freshly-committed base into the working tree so the
+          # "Resolve metadata and bump version" step below (which reads the LOCAL
+          # Makefile) stamps THIS build with the newly-bumped version.
+          git fetch origin dev --quiet 2>/dev/null || true
+          git checkout origin/dev -- Makefile 2>/dev/null || true
+          echo "Dev base advanced; local Makefile mirrored for this build:"
+          grep -E '^\s*PROJECT_VERSION' Makefile || true
+
+      - name: Resolve metadata and bump version
+        id: meta
+        if: steps.eligibility.outputs.proceed == 'true'
+        run: |
+          # #404 — stability comes from the dispatch input; the nightly schedule
+          # always builds the development channel. There is no push event.
+          if [ "${{ github.event_name }}" = "schedule" ]; then
+            STABILITY="development"
+          else
+            STABILITY="${{ inputs.stability || 'development' }}"
+          fi
+
+          case "$STABILITY" in
+            development)        SUFFIX="-dev";   TAG="development" ;;
+            alpha)              SUFFIX="-alpha"; TAG="alpha" ;;
+            beta)               SUFFIX="-beta";  TAG="beta" ;;
+            release-candidate)  SUFFIX="-rc";    TAG="release-candidate" ;;
+          esac
+
+          # #404 — VERSION AS BUILD METADATA, NOT A COMMITTED BUMP.
+          # version_build_metadata.php derives a monotonically-advancing version by
+          # FOLDING the build counter (commits-since-base, #468) INTO THE PATCH and
+          # appending a SINGLE channel suffix — a clean XX.YY.ZZ-<stability> with NO
+          # dotted ".N" counter (MokoGIT #1313). It stamps this into the in-tree
+          # manifest ONLY (no git add/commit/push). This keeps <version> advancing so
+          # Joomla's updater detects each new dev/rc build, while removing the pushed
+          # bump commit that caused manifest <version> merge conflicts on every
+          # branch->dev merge.
+          php ${MOKO_CLI}/version_build_metadata.php \
+            --path . --stability "$STABILITY" --github-output 2>/dev/null || true
+
+          # #404 + #1313: cascade the FULL derived version (e.g. 02.91.03-dev), NOT
+          # the bare Makefile base. version_build_metadata folds the monotonic build
+          # counter INTO THE PATCH and emits build_version as a clean XX.YY.ZZ plus a
+          # SINGLE channel suffix (-dev/-alpha/-beta/-rc) — no dotted ".N".
+          #
+          # WHY the ".N" counter was removed (the fleet "version-freeze"): the old
+          # XX.YY.ZZ-<stability>.<N> form (e.g. 02.91.00-dev.3) broke the Joomla update
+          # chain end-to-end. The MokoGIT updates.xml generator dropped/mis-carried
+          # ".N" into <version> (MokoGIT #1307), and Joomla itself cannot parse a
+          # dotted pre-release counter: it fused ".N" into <element>, minted duplicate
+          # <version>s across builds, and broke version_compare — so dev/rc sites were
+          # NEVER offered a newer build (MokoGIT #1313). Folding the counter into the
+          # patch keeps <version> strictly increasing AND a plain, comparable
+          # XX.YY.ZZ-<stability>. NOTE: the feed is rendered on-demand by the MokoGIT
+          # server binary, so a generator fix only takes effect once that binary is
+          # deployed (this bit the fleet when a broken prod deploy stranded the fix).
+          # Re-reading the base here instead would discard the advance and re-freeze
+          # every build at the same <version>.
+          VERSION="$(grep '^build_version=' "$GITHUB_OUTPUT" | tail -1 | cut -d= -f2 || true)"
+          if [ -z "$VERSION" ]; then
+            # Fallback when build metadata is unavailable: bare base + suffix (legacy,
+            # frozen-within-base behaviour — better than an empty version).
+            VERSION=$(php ${MOKO_CLI}/version_read.php --path . 2>/dev/null || echo "00.00.01")
+            VERSION="$(echo "$VERSION" | sed 's/-\(dev\|alpha\|beta\|rc\)$//')${SUFFIX}"
+          fi
+
+          # Pass the version VERBATIM — deliberately NO --stability. version_set_platform
+          # only strips a *trailing* -<stability> and only appends the suffix when it is
+          # absent, so a full "02.91.03-dev" is written unchanged via its semver branch;
+          # passing --stability would re-append and double the suffix (…-dev-dev).
+          # #289: also stamp <creationDate> (build date, UTC) + <author> (Makefile
+          # PROJECT_AUTHOR) into Joomla manifests at build. No-op on non-Joomla, and
+          # harmless on an older MokoCLI lacking --date/--author (2>/dev/null || true).
+          MG_BUILD_DATE="$(date -u +%Y-%m-%d)"
+          MG_AUTHOR="$(grep -m1 -E '^PROJECT_AUTHOR[[:space:]]*:?=' Makefile 2>/dev/null | sed -E 's/.*:?=[[:space:]]*//' | sed 's/[[:space:]]*$//' || true)"
+          php ${MOKO_CLI}/version_set_platform.php \
+            --path . --version "$VERSION" --branch "${{ steps.ref.outputs.ref }}" \
+            --date "$MG_BUILD_DATE" ${MG_AUTHOR:+--author "$MG_AUTHOR"} 2>/dev/null || true
+          php ${MOKO_CLI}/version_check.php --path . --fix 2>/dev/null || true
+
+          # Emit a Joomla schema-update stub for each shipped extension's own
+          # version so #__schemas tracks the manifest (fixes "database out of date").
+          # --prune-above also removes leftover old-scheme (02.x/03.x) update files
+          # stranded above the manifest version by the rebrand down-reset, which
+          # otherwise keep ChangeSet::getSchema() pinned high (MokoCLI schema drift,
+          # Mokonyx #469). No-op on non-Joomla repos, which have no sql/updates dirs.
+          php ${MOKO_CLI}/schema_stub.php --path . --prune-above
+
+          # Ensure licensing tags (updateservers, dlid) if enabled in manifest.xml
+          php ${MOKO_CLI}/manifest_licensing.php --path . --fix 2>/dev/null || true
+
+          # VERSION already carries its single -<stability> suffix (from build_version
+          # above), so it is NOT re-suffixed here — re-appending $SUFFIX produced the
+          # -dev-dev double-suffix (Template-Generic#319).
+
+          # NOTE: no commit/push here (#404). The derived version lives only in the
+          # built artifact + the dynamic updates feed; the branch tip is untouched.
+
+          # Auto-detect element via manifest_element.php (Joomla-family only:
+          # element/manifest resolution is Joomla-specific). For npm/mcp/client
+          # the generic fallback below derives ext_element/zip_name from the repo
+          # name — no Joomla manifest is present or required.
+          if [ "${{ steps.eligibility.outputs.is_joomla_family }}" = "true" ]; then
+            # NO --stability: $VERSION already carries its single -<stability> suffix,
+            # and manifest_element appends the stability suffix unconditionally — passing
+            # it would double the suffix in the zip name (…-dev-dev.zip). (#319)
+            php ${MOKO_CLI}/manifest_element.php \
+              --path . --version "$VERSION" \
+              --repo "${GIT_REPO}" --github-output
+          fi
+
+          # Read back element outputs
+          EXT_ELEMENT=$(grep '^ext_element=' "$GITHUB_OUTPUT" | tail -1 | cut -d= -f2 || true)
+          ZIP_NAME=$(grep '^zip_name=' "$GITHUB_OUTPUT" | tail -1 | cut -d= -f2 || true)
+          [ -z "$EXT_ELEMENT" ] && EXT_ELEMENT=$(echo "${GIT_REPO}" | tr '[:upper:]' '[:lower:]' | tr -d ' -')
+          [ -z "$ZIP_NAME" ] && ZIP_NAME="${EXT_ELEMENT}-${VERSION}.zip"
+
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "stability=${STABILITY}" >> "$GITHUB_OUTPUT"
+          echo "suffix=${SUFFIX}" >> "$GITHUB_OUTPUT"
+          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
+          echo "zip_name=${ZIP_NAME}" >> "$GITHUB_OUTPUT"
+          echo "ext_element=${EXT_ELEMENT}" >> "$GITHUB_OUTPUT"
+
+          echo "=== Pre-Release: ${EXT_ELEMENT} ${VERSION} ==="
+
+      # npm publishing is NOT part of this universal workflow — it lives only in
+      # Template-NPM (.mokogit/workflows/npm-publish.yml) so it cannot leak into
+      # Joomla / non-npm repos via template sync. Joomla-family repos attach a zip
+      # below; npm repos publish from their own dedicated workflow.
+      # Release API operations (create / notes / upload / cascade delete) run
+      # against THIS repo, so they authenticate with the built-in per-run
+      # github.token (contents: write) — NOT the org MOKOGIT_TOKEN. That keeps
+      # MOKOGIT_TOKEN least-privilege (read-only, used only for the cross-repo
+      # mokocli / submodule clones above) while same-repo release writes stay
+      # scoped to the run — matching auto-release.yml (Template-Generic #188).
+      # github.token carries no trailing newline, but trim + mask anyway for
+      # Authorization-header hygiene.
+      - name: Sanitize release API token
+        if: steps.eligibility.outputs.proceed == 'true'
+        run: |
+          T="$(printf '%s' "${{ github.token }}" | tr -d '[:space:]')"
+          echo "::add-mask::${T}"
+          echo "MOKO_TOKEN=${T}" >> "$GITHUB_ENV"
+
+      - name: Create release
+        id: release
+        if: steps.eligibility.outputs.publish == 'true'
+        # The MokoGIT release is the deliverable ONLY for the Joomla family. npm/mcp/
+        # client publish their real artifact upstream (npm) and merely mirror a
+        # release here, so a MokoGIT release failure must not fail those runs.
+        # release_create.php can fail its delete-then-recreate of the rolling dev/rc
+        # release (DELETE returns HTTP 200 but the release lingers), which turns an
+        # already-successful npm publish red. We branch on family INSIDE the run
+        # script (this act runner rejects `continue-on-error: ${{ ... }}` — it only
+        # accepts a literal bool): Joomla stays fatal; non-Joomla swallows a release
+        # failure so a green npm publish stays green.
+        run: |
+          TAG="${{ steps.meta.outputs.tag }}"
+          VERSION="${{ steps.meta.outputs.version }}"
+          API_BASE="${GIT_URL}/api/v1/repos/${GIT_ORG}/${GIT_REPO}"
+          if [ "${{ steps.eligibility.outputs.is_joomla_family }}" = "true" ]; then
+            php ${MOKO_CLI}/release_create.php \
+              --path . --version "$VERSION" --tag "$TAG" \
+              --token "${MOKO_TOKEN}" --api-base "$API_BASE" \
+              --repo "${GIT_REPO}" --branch "${{ steps.ref.outputs.ref }}" --prerelease
+          else
+            php ${MOKO_CLI}/release_create.php \
+              --path . --version "$VERSION" --tag "$TAG" \
+              --token "${MOKO_TOKEN}" --api-base "$API_BASE" \
+              --repo "${GIT_REPO}" --branch "${{ steps.ref.outputs.ref }}" --prerelease \
+              || echo "::warning::MokoGIT release failed — non-fatal for npm/mcp/client (npm is the real artifact)"
+          fi
+
+      - name: "Deploy to dev (inline — replaces standalone deploy.yml, #1427)"
+        if: github.event_name == 'push' && github.ref == 'refs/heads/dev' && vars.DEV_SSH_USERNAME != ''
+        env:
+          DEPLOY_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
+        run: |
+          # #1427: dev-channel deploy inlined here (pre-release runs on dev push);
+          # the standalone deploy.yml is deleted. Only a genuine dev PUSH deploys
+          # (never the nightly schedule or a manual alpha/beta/rc dispatch). Gate =
+          # DEV_SSH_USERNAME set → non-deploy repos skip green. Targets from repo
+          # VARIABLES. mokocli deploy.php → restricted moko-deploy pattern.
+          set -euo pipefail
+          if [ -z "${DEPLOY_KEY:-}" ]; then
+            echo "::warning::DEV_SSH_USERNAME set but DEPLOY_SSH_KEY secret missing — skipping dev deploy"; exit 0
+          fi
+          mkdir -p ~/.ssh
+          # DEPLOY_SSH_KEY is base64-encoded (single line) so act_runner masks it in logs
+          # and the multi-line key is never echoed. Decode when it base64-decodes to a
+          # private key; else treat as a legacy raw PEM (back-compat during rollout).
+          install -m600 /dev/null ~/.ssh/deploy_key   # 0600 before any bytes (no umask window)
+          trap 'rm -f ~/.ssh/deploy_key' EXIT         # never leave the key on a shared runner
+          if printf '%s' "$DEPLOY_KEY" | base64 -d 2>/dev/null | grep -q 'PRIVATE KEY'; then
+            printf '%s' "$DEPLOY_KEY" | base64 -d > ~/.ssh/deploy_key
+          else
+            echo "$DEPLOY_KEY" > ~/.ssh/deploy_key
+          fi
+          TAG="$(git describe --tags --always 2>/dev/null || git rev-parse --short HEAD)-dev"
+          echo "Deploying dev tag ${TAG} to ${{ vars.DEV_SSH_USERNAME }}@${{ vars.DEV_SSH_HOST }}"
+          php "${MOKO_CLI}/deploy.php" --tier dev --tag "$TAG" \
+            --ssh-host "${{ vars.DEV_SSH_HOST }}" --ssh-port "${{ vars.DEV_SSH_PORT }}" \
+            --ssh-user "${{ vars.DEV_SSH_USERNAME }}" --ssh-key ~/.ssh/deploy_key
+
+      # -- Electron pre-release: build installers (Windows via Wine + Linux) ------
+      # No Windows/macOS runner: cross-build Windows with Wine on the Ubuntu
+      # `release` runner, build Linux natively, skip macOS. Gated on is_electron
+      # so non-electron pre-releases are 100% unaffected.
+      - name: "Setup Node (electron)"
+        if: steps.eligibility.outputs.proceed == 'true' && steps.eligibility.outputs.is_electron == 'true' && vars.ELECTRON_CI_BUILD == 'true'
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24.18.1
+      - name: "Setup pnpm (electron)"
+        if: steps.eligibility.outputs.proceed == 'true' && steps.eligibility.outputs.is_electron == 'true' && vars.ELECTRON_CI_BUILD == 'true'
+        uses: pnpm/action-setup@v4
+        with:
+          version: 11.20.0
+      - name: "Build electron installers (Windows via Wine + Linux) [pre-release]"
+        if: steps.eligibility.outputs.publish == 'true' && steps.eligibility.outputs.is_electron == 'true' && vars.ELECTRON_CI_BUILD == 'true'
+        env:
+          HUSKY: "0"
+        run: |
+          # electron-builder's NSIS target RUNS the built installer under Wine to
+          # generate + sign the uninstaller, which needs 32-bit Wine libs (the NSIS
+          # stub is a WoW64 exe) AND an X display. A bare `wine64` on an
+          # under-provisioned `release` runner aborts with "wine process failed 1
+          # ... ntdll.dll c0000135 / no driver could be loaded" (intermittent: only
+          # when a job lands on a runner without wine32/xvfb pre-seeded). Provision
+          # i386 Wine + Xvfb here so the Windows leg builds on ANY runner, and init
+          # the prefix once, headless, so electron-builder's first Wine call does
+          # not race prefix creation.
+          sudo dpkg --add-architecture i386 || true
+          sudo apt-get update -qq
+          sudo apt-get install -y -qq xvfb >/dev/null 2>&1 || echo "::warning::xvfb install failed"
+          sudo apt-get install -y -qq wine64 wine32 >/dev/null 2>&1             || sudo apt-get install -y -qq wine >/dev/null 2>&1             || sudo apt-get install -y -qq wine64 >/dev/null 2>&1             || echo "::warning::wine install failed -- Windows target may be skipped"
+          export WINEDEBUG=-all
+          export WINEPREFIX="${WINEPREFIX:-$HOME/.wine}"
+          xvfb-run -a wineboot --init >/dev/null 2>&1 || true
+          pnpm install --frozen-lockfile
+          # Compile the app into electron-builder's app dir (directories.app, e.g. ./build)
+          # BEFORE packaging. electron-builder validates the app dir up-front, so running
+          # it without a prior compile aborts with "Application directory ./build doesn't
+          # exist". Prefer an explicit repo script (compile:app); fall back to the esbuild
+          # entrypoint that Ferdium-derived electron apps ship.
+          if pnpm run 2>/dev/null | grep -qiE '(^|[[:space:]])compile:app([[:space:]]|$)'; then
+            pnpm run compile:app
+          elif [ -f esbuild.mjs ]; then
+            npx --no-install preval-build-info-cli >/dev/null 2>&1 || true
+            node esbuild.mjs
+          else
+            echo "::warning::no compile step found (add a 'compile:app' package.json script or esbuild.mjs) -- electron-builder may fail if the app dir is not pre-built"
+          fi
+          # xvfb-run gives Wine a virtual X display for the installer-run pass that
+          # generates the NSIS uninstaller; without it Wine cannot create a window
+          # and the build fails ("no driver could be loaded / $DISPLAY").
+          xvfb-run -a npx --no-install electron-builder --win --linux --publish never             || xvfb-run -a npx electron-builder --win --linux --publish never
+      - name: "Attach electron installers (pre-release)"
+        if: steps.eligibility.outputs.publish == 'true' && steps.eligibility.outputs.is_electron == 'true' && vars.ELECTRON_CI_BUILD == 'true'
+        continue-on-error: true
+        run: |
+          API_BASE="${GIT_URL}/api/v1/repos/${GIT_ORG}/${GIT_REPO}"
+          TOKEN="${MOKO_TOKEN}"
+          TAG="${{ steps.meta.outputs.tag }}"
+          RID=$(curl -sf -H "Authorization: token ${TOKEN}" "${API_BASE}/releases/tags/${TAG}" | python3 -c "import json,sys; print(json.load(sys.stdin).get('id',''))" 2>/dev/null || true)
+          if [ -z "$RID" ]; then echo "::warning::pre-release ${TAG} not found -- skipping electron asset upload"; else
+            for f in $(find out dist_electron dist -maxdepth 2 -type f \( -name '*.exe' -o -name '*.AppImage' -o -name '*.deb' -o -name 'latest*.yml' \) 2>/dev/null); do
+              name=$(basename "$f")
+              curl -sf -X POST -H "Authorization: token ${TOKEN}" "${API_BASE}/releases/${RID}/assets?name=${name}" -F "attachment=@${f}" >/dev/null && echo "attached ${name}" || echo "::warning::upload failed ${name}"
+            done
+          fi
+
+      # -- npm pre-release: publish the dev/alpha/beta/rc build to the MokoGIT npm
+      # registry (INTERNAL ONLY). ABSORBED from Template-NPM's retired
+      # npm-prerelease.yml, but CORRECTED: the old step called `moko publish`, which
+      # maps to release_publish.php and does a GIT RELEASE ONLY — mokocli has no npm
+      # publish verb, so dev builds never actually reached an npm registry (only
+      # npm-publish.yml's plain `npm publish` ever did). This uses plain `npm publish`
+      # with the channel as the npm dist-tag, to the MokoGIT npm registry via the
+      # per-run Actions token (least-privilege). Public npmjs.org is deliberately NOT
+      # used for prereleases. Gated on is_npm; idempotent (existing version = no-op).
+      - name: "Setup Node (npm)"
+        if: steps.eligibility.outputs.publish == 'true' && steps.eligibility.outputs.is_npm == 'true'
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - name: "Publish npm package (pre-release -> MokoGIT registry, dist-tag by channel)"
+        if: steps.eligibility.outputs.publish == 'true' && steps.eligibility.outputs.is_npm == 'true'
+        env:
+          NODE_AUTH_TOKEN: ${{ github.token }}
+        run: |
+          set -uo pipefail
+          VERSION="${{ steps.meta.outputs.version }}"
+          case "${{ steps.meta.outputs.stability }}" in
+            alpha)                TAG=alpha ;;
+            beta)                 TAG=beta ;;
+            release-candidate|rc) TAG=rc ;;
+            *)                    TAG=dev ;;
+          esac
+          # Stamp package.json to the derived build version (in-tree only, never
+          # committed) so `npm publish` ships exactly the pre-release version.
+          npm version "$VERSION" --no-git-tag-version --allow-same-version >/dev/null 2>&1             || echo "::warning::could not stamp package.json to ${VERSION} (continuing)"
+          npm ci --no-audit --no-fund || npm install --no-audit --no-fund
+          npm run build --if-present
+          HOST="${GIT_URL#https://}"; OWNER="${GIT_ORG}"
+          REG="https://${HOST}/api/packages/${OWNER}/npm/"
+          echo "//${HOST}/api/packages/${OWNER}/npm/:_authToken=${NODE_AUTH_TOKEN}" > .npmrc
+          set +e; out="$(npm publish --ignore-scripts --registry "${REG}" --tag "${TAG}" 2>&1)"; rc=$?; set -e
+          rm -f .npmrc; echo "$out"
+          if [ "$rc" -eq 0 ]; then echo "Published ${VERSION} (dist-tag ${TAG}) to the MokoGIT npm registry."
+          elif printf '%s' "$out" | grep -qiE 'already exists|cannot publish over|EPUBLISHCONFLICT|409 Conflict'; then echo "::notice::MokoGIT registry already has ${VERSION} - no-op (idempotent)."
+          else echo "::error::MokoGIT-registry pre-release publish FAILED (npm exit ${rc})."; exit "$rc"; fi
+
+      # -- mokohub-manifest pre-release: zip manifest.json -> attach ---------------
+      # ADDITIVE + GATED (Template-Generic#326). Package the repo's manifest.json
+      # into a rolling zip and attach it to the pre-release. Gated on is_manifest,
+      # so every other platform is unaffected. Best-effort (continue-on-error): a
+      # cosmetic packaging hiccup must not red an otherwise-good pre-release.
+      - name: "Package mokohub-manifest (zip manifest.json) [pre-release]"
+        if: >-
+          steps.eligibility.outputs.publish == 'true' &&
+          steps.eligibility.outputs.is_manifest == 'true'
+        continue-on-error: true
+        run: |
+          TAG="${{ steps.meta.outputs.tag }}"
+          VERSION="${{ steps.meta.outputs.version }}"
+          API_BASE="${GIT_URL}/api/v1/repos/${GIT_ORG}/${GIT_REPO}"
+          if [ ! -f manifest.json ]; then
+            echo "::warning::mokohub-manifest: no manifest.json at repo root — nothing to package"
+            exit 0
+          fi
+          ZIP="${RUNNER_TEMP}/manifest-${VERSION}.zip"
+          ( cd "$(dirname manifest.json)" && zip -j "$ZIP" manifest.json ) \
+            || { echo "::warning::mokohub-manifest: zip failed"; exit 0; }
+          RID=$(curl -sf -H "Authorization: token ${MOKO_TOKEN}" "${API_BASE}/releases/tags/${TAG}" | python3 -c "import json,sys; print(json.load(sys.stdin).get('id',''))" 2>/dev/null || true)
+          if [ -z "$RID" ]; then echo "::warning::pre-release ${TAG} not found — skipping manifest asset upload"; exit 0; fi
+          name="$(basename "$ZIP")"
+          # Replace-in-place: delete a same-named asset so the rolling zip updates.
+          AID=$(curl -sf -H "Authorization: token ${MOKO_TOKEN}" "${API_BASE}/releases/${RID}/assets" | N="$name" python3 -c "import json,sys,os; n=os.environ['N']; print(next((a['id'] for a in json.load(sys.stdin) if a.get('name')==n),''))" 2>/dev/null || true)
+          [ -n "$AID" ] && curl -sf -X DELETE -H "Authorization: token ${MOKO_TOKEN}" "${API_BASE}/releases/${RID}/assets/${AID}" >/dev/null 2>&1 || true
+          curl -sf -X POST -H "Authorization: token ${MOKO_TOKEN}" "${API_BASE}/releases/${RID}/assets?name=${name}" -F "attachment=@${ZIP}" >/dev/null \
+            && echo "attached ${name}" || echo "::warning::manifest asset upload failed (${name})"
+
+      # -- mokohub-recipes pre-release: build catalog.zip (via MokoCLI) -> attach --
+      # ADDITIVE + GATED (Template-Generic#326). Delegate catalog.zip packaging to
+      # the MokoCLI build agent (`moko package`), which builds ONE signed catalog.zip
+      # per stream for the mokohub-recipes platform (MokoCLI #684 / epic
+      # mokohub-recipes#1). Gated on is_recipes; best-effort so joomla/npm/etc are
+      # untouched and a not-yet-shipped MokoCLI verb can't red the run.
+      - name: "Package mokohub-recipes (catalog.zip via MokoCLI) [pre-release]"
+        if: >-
+          steps.eligibility.outputs.publish == 'true' &&
+          steps.eligibility.outputs.is_recipes == 'true'
+        continue-on-error: true
+        run: |
+          VERSION="${{ steps.meta.outputs.version }}"
+          TAG="${{ steps.meta.outputs.tag }}"
+          STABILITY="${{ steps.meta.outputs.stability }}"
+          API_BASE="${GIT_URL}/api/v1/repos/${GIT_ORG}/${GIT_REPO}"
+          # `moko package` for the mokohub-recipes platform builds the per-stream
+          # catalog.zip (all recipes + all.json) and attaches it as the rolling
+          # stream asset. Same --stability/--rolling/--tag/attach contract as the
+          # Joomla zip step; the platform shim selects the catalog builder.
+          moko package \
+            --path . --version "$VERSION" --tag "$TAG" \
+            --token "${MOKO_TOKEN}" --api-base "$API_BASE" \
+            --repo "${GIT_REPO}" --out "$RUNNER_TEMP" \
+            --stability "$STABILITY" --rolling \
+            || echo "::warning::mokohub-recipes: moko package (catalog.zip) failed or unavailable — non-fatal (MokoCLI #684)"
+
+      - name: Update release notes from CHANGELOG.md
+        if: steps.eligibility.outputs.publish == 'true'
+        # Release notes are cosmetic. The release-body PATCH can 403 on this MokoGIT
+        # instance (the per-run github.token lacks release-write), and for npm/mcp/
+        # client the published package is the real artifact — never let this fail
+        # the run. (Matches the cascade step's best-effort contract.)
+        continue-on-error: true
+        run: |
+          TAG="${{ steps.meta.outputs.tag }}"
+          VERSION="${{ steps.meta.outputs.version }}"
+          API_BASE="${GIT_URL}/api/v1/repos/${GIT_ORG}/${GIT_REPO}"
+
+          # Extract [Unreleased] section via the shared mokocli command (#364 centralization).
+          if [ -f "CHANGELOG.md" ]; then
+            NOTES=$(php ${MOKO_CLI}/release_notes.php --path . --version Unreleased 2>/dev/null || true)
+            # release_notes.php echoes "Release Unreleased" when the section is empty; normalize.
+            [ "$NOTES" = "Release Unreleased" ] && NOTES=""
+            [ -z "$NOTES" ] && NOTES="Release ${VERSION}"
+          else
+            NOTES="Release ${VERSION}"
+          fi
+
+          # Update release body via API
+          RELEASE_ID=$(curl -sf -H "Authorization: token ${MOKO_TOKEN}" \
+            "${API_BASE}/releases/tags/${TAG}" | python3 -c "import json,sys; print(json.load(sys.stdin).get('id',''))" 2>/dev/null || true)
+
+          if [ -n "$RELEASE_ID" ]; then
+            python3 -c "
+          import json, urllib.request
+          body = open('/dev/stdin').read()
+          payload = json.dumps({'body': body}).encode()
+          req = urllib.request.Request(
+              '${API_BASE}/releases/${RELEASE_ID}',
+              data=payload, method='PATCH',
+              headers={
+                  'Authorization': 'token ${MOKO_TOKEN}',
+                  'Content-Type': 'application/json'
+              })
+          urllib.request.urlopen(req)
+          " <<< "$NOTES"
+            echo "Release notes updated from CHANGELOG.md"
+          fi
+
+      # Build-time PHP dependency vendoring (universal, guarded). If a sub-package
+      # ships a composer.json, fetch its runtime deps into that package's CONFIGURED
+      # vendor dir (composer config vendor-dir — e.g. admin/vendor) BEFORE
+      # release_package.php zips the working tree — so a component can declare a PHP
+      # library (e.g. mPDF) via composer.json instead of committing vendor/. No-op
+      # for any repo without a sub-package composer.json.
+      #
+      # (07.15.00) This step used to be a SILENT NO-OP on the release runners:
+      # php-cli ships without ext-gd, so composer could not even RESOLVE mpdf/mpdf
+      # ("require ext-gd * -> it is missing from your system"), and the old
+      # continue-on-error + `|| warning` swallowed that into a green build. The zip
+      # then shipped WITHOUT admin/vendor while the component manifest lists
+      # <folder>vendor</folder>, so JInstaller aborts the ENTIRE package install
+      # on-site ("File does not exist [ROOT][TMP]/.../admin/vendor" → "Failed to
+      # copy administrator files"; reproduced on MokonyxCRMDCM + MokonyxCRM). Now:
+      # ext-gd is provisioned when missing, the configured vendor-dir is verified
+      # to have materialized autoload.php, and a vendoring failure for a package
+      # whose manifest ships <folder>vendor</folder> FAILS the build loud — a
+      # broken artifact that bricks installs is strictly worse than a red build.
+      # Packages whose manifests do NOT reference vendor/ keep the fail-soft
+      # warning, so non-vendoring repos are unaffected.
+      - name: Vendor PHP dependencies (build-time)
+        if: steps.eligibility.outputs.proceed == 'true'
+        run: |
+          set -uo pipefail
+          CJS="$(find source/packages src/packages -maxdepth 2 -name composer.json 2>/dev/null || true)"
+          if [ -z "$CJS" ]; then echo "No sub-package composer.json — nothing to vendor."; exit 0; fi
+          command -v composer >/dev/null 2>&1 || { sudo apt-get update -qq && sudo apt-get install -y -qq composer >/dev/null 2>&1 || true; }
+          # mPDF (and most PHP PDF/image libs) hard-require ext-gd; without it
+          # composer fails dependency RESOLUTION outright, not just a sub-dep.
+          if ! php -m 2>/dev/null | grep -qi '^gd$'; then
+            PHPV="$(php -r 'echo PHP_MAJOR_VERSION.".".PHP_MINOR_VERSION;' 2>/dev/null || true)"
+            sudo apt-get update -qq || true
+            sudo apt-get install -y -qq "php${PHPV}-gd" || sudo apt-get install -y -qq php-gd || echo "::warning::php-gd install failed (php ${PHPV})"
+            php -m 2>/dev/null | grep -qi '^gd$' || echo "::warning::ext-gd STILL missing after install attempt — vendoring will fail for gd-requiring packages"
+          fi
+          rc=0
+          for cj in $CJS; do
+            dir="$(dirname "$cj")"
+            echo "::notice::composer install (no-dev) in ${dir}"
+            ok=true
+            composer install --no-dev --no-interaction --no-progress --optimize-autoloader --working-dir="$dir" || ok=false
+            # Verify the CONFIGURED vendor dir actually materialized — composer can
+            # exit 0 while writing nothing the manifest needs.
+            vd="$(composer config vendor-dir --working-dir="$dir" 2>/dev/null || true)"; vd="${vd:-vendor}"
+            [ -f "${dir}/${vd}/autoload.php" ] || ok=false
+            if [ "$ok" = "true" ]; then
+              echo "vendored: ${dir}/${vd}"
+            elif grep -qs '<folder>vendor</folder>' "${dir}"/*.xml; then
+              echo "::error::vendoring FAILED in ${dir} but its Joomla manifest ships <folder>vendor</folder> — the built zip would abort the whole package install on JInstaller ('File does not exist .../vendor'). Failing the build instead of shipping a broken package."
+              rc=1
+            else
+              echo "::warning::composer install failed in ${dir} — manifest does not ship vendor/; packaging the existing tree"
+            fi
+          done
+          exit $rc
+
+      # Joomla-family only: mokocli release_package.php builds the extension zip
+      # (+ sha256, attach). npm/mcp/client package/publish in their platform shim
+      # (trust boundary, ADR #124), so this PHP zip step is skipped for them.
+      - name: Optimize assets (artifact-time)
+        if: steps.eligibility.outputs.proceed == 'true'
+        continue-on-error: true
+        run: |
+          moko assets:optimize --path . 2>/dev/null || echo "::notice::moko assets:optimize unavailable or no assets — skipping"
+
+      - name: Build package and upload
+        id: package
+        if: >-
+          steps.eligibility.outputs.publish == 'true' &&
+          steps.eligibility.outputs.is_joomla_family == 'true'
+        run: |
+          VERSION="${{ steps.meta.outputs.version }}"
+          TAG="${{ steps.meta.outputs.tag }}"
+          STABILITY="${{ steps.meta.outputs.stability }}"
+          API_BASE="${GIT_URL}/api/v1/repos/${GIT_ORG}/${GIT_REPO}"
+          # Publish the pre-release asset under a VERSIONED rolling name
+          # (pkg_<ext>-<version>-dev.zip / -rc.zip) replaced in place each build. The
+          # release version is stable within a base version, so the asset URL stays
+          # stable while the version is visible in the filename. The in-package
+          # manifest <version> still advances (build metadata) so the updater keeps
+          # detecting new builds.
+          # PILOT: build the package via the MokoCLI build agent. `moko package`
+          # wraps release_package.php UNCHANGED (standards preserved) and writes the
+          # artifact to $RUNNER_TEMP (CI-provided temp dir) instead of a hardcoded
+          # /tmp. The --stability/--rolling/--tag/attach contract is identical.
+          moko package \
+            --path . --version "$VERSION" --tag "$TAG" \
+            --token "${MOKO_TOKEN}" --api-base "$API_BASE" \
+            --repo "${GIT_REPO}" --out "$RUNNER_TEMP" \
+            --stability "$STABILITY" --rolling
+
+      # updates.xml <downloadurl> is generated server-side by MokoGIT (the license
+      # server; being moved to MokoSuiteLicensing). It must reference the VERSIONED
+      # rolling asset (pkg_<ext>-<version>-dev.zip) that release_package.php now
+      # publishes — keep the server-side generator in sync with that filename.
+
+      - name: "Delete lesser pre-release channels (cascade)"
+        if: steps.eligibility.outputs.publish == 'true'
+        continue-on-error: true
+        run: |
+          API_BASE="${GIT_URL}/api/v1/repos/${GIT_ORG}/${GIT_REPO}"
+          TOKEN="${MOKO_TOKEN}"
+
+          php ${MOKO_CLI}/release_cascade.php \
+            --stability "${{ steps.meta.outputs.stability }}" \
+            --token "${TOKEN}" \
+            --api-base "${API_BASE}"
+
+      - name: Summary
+        if: always()
+        run: |
+          VERSION="${{ steps.meta.outputs.version }}"
+          STABILITY="${{ steps.meta.outputs.stability }}"
+          ZIP_NAME="${{ steps.meta.outputs.zip_name }}"
+          SHA256="${{ steps.package.outputs.sha256_zip }}"
+          echo "## Pre-Release Complete" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "| Field | Value |" >> $GITHUB_STEP_SUMMARY
+          echo "|-------|-------|" >> $GITHUB_STEP_SUMMARY
+          echo "| Version | \`${VERSION}\` |" >> $GITHUB_STEP_SUMMARY
+          echo "| Channel | ${STABILITY} |" >> $GITHUB_STEP_SUMMARY
+          echo "| Package | \`${ZIP_NAME}\` |" >> $GITHUB_STEP_SUMMARY
+          echo "| SHA-256 | \`${SHA256:-n/a}\` |" >> $GITHUB_STEP_SUMMARY