Merge pull request 'chore: cascade main → dev (bd18642) [skip ci]' (#171) from main into dev

chore: cascade main → dev [skip ci]

.mokogitea/manifest.xml

@@ -4,11 +4,15 @@
   Auto-generated by cleanup script.
   See: https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home
 -->
-<moko-platform xmlns="https://standards.mokoconsulting.tech/moko-platform/1.0" schema-version="1.0">
+<moko-platform xmlns="https://standards.mokoconsulting.tech/moko-platform/1.0"
+               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+               xsi:schemaLocation="https://standards.mokoconsulting.tech/moko-platform/1.0 https://git.mokoconsulting.tech/MokoConsulting/moko-platform/raw/branch/main/definitions/manifest-schema.xsd"
+               schema-version="1.0">
   <identity>
     <name>moko-platform</name>
     <org>MokoConsulting</org>
     <description>Enterprise automation, validation, sync, and governance engine for all Moko Consulting repositories</description>
+    <version>09.01.00</version>
     <license spdx="GPL-3.0-or-later">GNU General Public License v3</license>
   </identity>
   <governance>

.mokogitea/workflows/ci-platform.yml

@@ -124,16 +124,16 @@ jobs:
           echo "### PHPCS" >> $GITHUB_STEP_SUMMARY
           echo "PSR-12 compliance: passed" >> $GITHUB_STEP_SUMMARY
 
-      - name: "PHPStan (Level 2)"
-        continue-on-error: true
+      - name: "PHPStan (Level 6)"
         run: |
-          vendor/bin/phpstan analyse -c phpstan.neon --no-progress --error-format=github 2>&1 || {
-            echo "::warning::PHPStan found type errors (advisory)"
+          vendor/bin/phpstan analyse -c phpstan.neon --no-progress --memory-limit=512M --error-format=github 2>&1 || {
+            echo "::error::PHPStan found type errors"
             echo "### PHPStan" >> $GITHUB_STEP_SUMMARY
             echo "Static analysis errors detected. Run \`composer phpstan\` locally." >> $GITHUB_STEP_SUMMARY
+            exit 1
           }
           echo "### PHPStan" >> $GITHUB_STEP_SUMMARY
-          echo "Static analysis: advisory (level 0)" >> $GITHUB_STEP_SUMMARY
+          echo "Static analysis (level 6): passed" >> $GITHUB_STEP_SUMMARY
 
       - name: "Psalm"
         continue-on-error: true
@@ -177,11 +177,14 @@ jobs:
 
       - name: "PHPUnit (PHP ${{ matrix.php }})"
         run: |
-          vendor/bin/phpunit --testdox 2>&1
-          {
-            echo "### PHPUnit (PHP ${{ matrix.php }})"
-            echo "All tests passed."
-          } >> $GITHUB_STEP_SUMMARY
+          vendor/bin/phpunit --testdox 2>&1 || {
+            echo "::error::PHPUnit tests failed"
+            echo "### PHPUnit (PHP ${{ matrix.php }})" >> $GITHUB_STEP_SUMMARY
+            echo "Tests failed. Run \`vendor/bin/phpunit --testdox\` locally." >> $GITHUB_STEP_SUMMARY
+            exit 1
+          }
+          echo "### PHPUnit (PHP ${{ matrix.php }})" >> $GITHUB_STEP_SUMMARY
+          echo "All tests passed." >> $GITHUB_STEP_SUMMARY
 
   # ═══════════════════════════════════════════════════════════════════════
   # Gate 3 — Self-Health (Dogfood)

.mokogitea/workflows/pre-release.yml

@@ -1,375 +1,314 @@
-# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
-#
-# SPDX-License-Identifier: GPL-3.0-or-later
-#
-# FILE INFORMATION
-# DEFGROUP: Gitea.Workflow
-# INGROUP: moko-platform.Release
-# REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
-# PATH: /templates/workflows/universal/pre-release.yml.template
-# VERSION: 05.01.00
-# BRIEF: Manual pre-release -- builds dev/alpha/beta/rc packages from any branch
-
-name: "Universal: Pre-Release"
-
-on:
-  workflow_dispatch:
-    inputs:
-      stability:
-        description: 'Pre-release channel'
-        required: true
-        type: choice
-        options:
-          - development
-          - alpha
-          - beta
-          - release-candidate
-
-permissions:
-  contents: write
-
-env:
-  GITEA_URL: ${{ vars.GITEA_URL || 'https://git.mokoconsulting.tech' }}
-  GITEA_ORG: ${{ vars.GITEA_ORG || github.repository_owner }}
-  GITEA_REPO: ${{ vars.GITEA_REPO || github.event.repository.name }}
-
-jobs:
-  build:
-    name: "Build Pre-Release (${{ inputs.stability }})"
-    runs-on: release
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          token: ${{ secrets.GA_TOKEN }}
-
-      - name: Setup tools
-        run: |
-          # Update moko-platform CLI tools if available; install PHP if missing
-          if command -v moko-platform-update &> /dev/null; then
-            moko-platform-update
-          elif [ -d "/opt/moko-platform" ]; then
-            cd /opt/moko-platform && git pull origin main --quiet 2>/dev/null || true
-          else
-            if ! command -v php &> /dev/null; then
-              sudo apt-get update -qq
-              sudo apt-get install -y -qq php-cli php-mbstring php-xml php-zip php-curl >/dev/null 2>&1
-            fi
-            git clone --depth 1 --branch main --quiet \
-              "https://x-access-token:${{ secrets.GA_TOKEN }}@git.mokoconsulting.tech/MokoConsulting/moko-platform.git" \
-              /tmp/moko-platform-api
-          fi
-          # Set MOKO_CLI to whichever path exists
-          if [ -d "/opt/moko-platform/cli" ]; then
-            echo "MOKO_CLI=/opt/moko-platform/cli" >> "$GITHUB_ENV"
-          else
-            echo "MOKO_CLI=/tmp/moko-platform-api/cli" >> "$GITHUB_ENV"
-          fi
-
-      - name: Detect platform
-        id: platform
-        run: |
-          PLATFORM=$(sed -n 's/.*<platform>\([^<]*\)<\/platform>.*/\1/p' .mokogitea/manifest.xml 2>/dev/null | head -1 | tr -d '[:space:]')
-          [ -z "$PLATFORM" ] && PLATFORM="generic"
-          echo "platform=$PLATFORM" >> "$GITHUB_OUTPUT"
-          MANIFEST=$(find ./src -maxdepth 1 -name "pkg_*.xml" -exec grep -l '<extension' {} \; 2>/dev/null | head -1)
-          [ -z "$MANIFEST" ] && MANIFEST=$(find . -maxdepth 3 -name "*.xml" ! -path "./.git/*" ! -path "*/packages/*" -exec grep -l '<extension' {} \; 2>/dev/null | head -1)
-          [ -z "$MANIFEST" ] && MANIFEST=$(find . -maxdepth 3 -name "*.xml" ! -path "./.git/*" -exec grep -l '<extension' {} \; 2>/dev/null | head -1)
-          MOD_FILE=$(find . -maxdepth 4 -name "mod*.class.php" ! -path "./.git/*" -exec grep -l 'extends DolibarrModules' {} \; 2>/dev/null | head -1)
-          echo "manifest=${MANIFEST}" >> "$GITHUB_OUTPUT"
-          echo "mod_file=${MOD_FILE}" >> "$GITHUB_OUTPUT"
-
-      - name: Resolve metadata and bump version
-        id: meta
-        run: |
-          STABILITY="${{ inputs.stability }}"
-
-          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
-
-          # Patch bump via CLI tool
-          php ${MOKO_CLI}/version_bump.php --path .
-          VERSION=$(php ${MOKO_CLI}/version_read.php --path . 2>/dev/null)
-          [ -z "$VERSION" ] && VERSION="00.00.01"
-          TODAY=$(date +%Y-%m-%d)
-
-          # Update platform-specific manifest
-          PLATFORM="${{ steps.platform.outputs.platform }}"
-          MANIFEST="${{ steps.platform.outputs.manifest }}"
-          MOD_FILE="${{ steps.platform.outputs.mod_file }}"
-
-          php ${MOKO_CLI}/version_set_platform.php \
-            --path . --version "$VERSION" --branch "${{ github.ref_name }}" 2>/dev/null || true
-
-          # Commit version bump
-          git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
-          git config --local user.name "gitea-actions[bot]"
-          git remote set-url origin "https://jmiller:${{ secrets.GA_TOKEN }}@git.mokoconsulting.tech/${{ github.repository }}.git"
-          git add -A
-          git diff --cached --quiet || {
-            git commit -m "chore(version): pre-release bump to ${VERSION} [skip ci]"
-            git push origin HEAD 2>&1
-          }
-
-          # Auto-detect element (platform-aware)
-          EXT_ELEMENT=""
-          case "$PLATFORM" in
-            joomla)
-              if [ -n "$MANIFEST" ]; then
-                EXT_ELEMENT=$(sed -n 's/.*<element>\([^<]*\)<\/element>.*/\1/p' "$MANIFEST" 2>/dev/null | head -1)
-                if [ -z "$EXT_ELEMENT" ]; then
-                  EXT_ELEMENT=$(basename "$MANIFEST" .xml | tr '[:upper:]' '[:lower:]')
-                  case "$EXT_ELEMENT" in
-                    templatedetails|manifest) EXT_ELEMENT=$(echo "${GITEA_REPO}" | tr '[:upper:]' '[:lower:]' | tr -d ' -') ;;
-                  esac
-                fi
-              else
-                EXT_ELEMENT=$(echo "${GITEA_REPO}" | tr '[:upper:]' '[:lower:]' | tr -d ' -')
-              fi
-              ;;
-            dolibarr)
-              if [ -n "$MOD_FILE" ]; then
-                MOD_BASENAME=$(basename "$MOD_FILE" .class.php)
-                EXT_ELEMENT=$(echo "$MOD_BASENAME" | sed 's/^mod//' | tr '[:upper:]' '[:lower:]')
-              else
-                EXT_ELEMENT=$(echo "${GITEA_REPO}" | tr '[:upper:]' '[:lower:]' | tr -d ' -')
-              fi
-              ;;
-            *)
-              EXT_ELEMENT=$(echo "${GITEA_REPO}" | tr '[:upper:]' '[:lower:]' | tr -d ' -')
-              ;;
-          esac
-
-          ZIP_NAME="${EXT_ELEMENT}-${VERSION}${SUFFIX}.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 "manifest=${MANIFEST}" >> "$GITHUB_OUTPUT"
-
-          echo "=== Pre-Release: ${EXT_ELEMENT} ${VERSION}${SUFFIX} ==="
-
-      - name: Build package
-        run: |
-          SOURCE_DIR="src"
-          [ ! -d "$SOURCE_DIR" ] && SOURCE_DIR="htdocs"
-          if [ ! -d "$SOURCE_DIR" ]; then
-            echo "::error::No src/ or htdocs/ directory"
-            exit 1
-          fi
-
-          MANIFEST="${{ steps.meta.outputs.manifest }}"
-          EXT_TYPE=""
-          if [ -n "$MANIFEST" ]; then
-            EXT_TYPE=$(sed -n 's/.*<extension[^>]*type="\([^"]*\)".*/\1/p' "$MANIFEST" | head -1)
-          fi
-
-          EXCLUDES="sftp-config* .ftpignore *.ppk *.pem *.key .env* *.local .build-trigger"
-
-          mkdir -p build/package
-
-          if [ "$EXT_TYPE" = "package" ] && [ -d "${SOURCE_DIR}/packages" ]; then
-            echo "=== Building Joomla PACKAGE (multi-extension) ==="
-            for ext_dir in "${SOURCE_DIR}"/packages/*/; do
-              [ ! -d "$ext_dir" ] && continue
-              EXT_NAME=$(basename "$ext_dir")
-              echo "  Packaging sub-extension: ${EXT_NAME}"
-              cd "$ext_dir"
-              zip -r "../../build/package/${EXT_NAME}.zip" . -x $EXCLUDES
-              cd "$OLDPWD"
-            done
-            for f in "${SOURCE_DIR}"/*.xml "${SOURCE_DIR}"/*.php; do
-              [ -f "$f" ] && cp "$f" build/package/
-            done
-          else
-            echo "=== Building standard extension ==="
-            rsync -a \
-              --exclude='sftp-config*' \
-              --exclude='.ftpignore' \
-              --exclude='*.ppk' \
-              --exclude='*.pem' \
-              --exclude='*.key' \
-              --exclude='.env*' \
-              --exclude='*.local' \
-              --exclude='.build-trigger' \
-              "${SOURCE_DIR}/" build/package/
-          fi
-
-      - name: Create ZIP
-        id: zip
-        run: |
-          ZIP_NAME="${{ steps.meta.outputs.zip_name }}"
-          cd build/package
-          zip -r "../${ZIP_NAME}" .
-          cd ..
-
-          SHA256=$(sha256sum "${ZIP_NAME}" | cut -d' ' -f1)
-          echo "sha256=${SHA256}" >> "$GITHUB_OUTPUT"
-          echo "ZIP: ${ZIP_NAME} (SHA: ${SHA256:0:16}...)"
-
-      - name: Create or replace Gitea release
-        id: release
-        run: |
-          TAG="${{ steps.meta.outputs.tag }}"
-          VERSION="${{ steps.meta.outputs.version }}"
-          STABILITY="${{ steps.meta.outputs.stability }}"
-          SHA256="${{ steps.zip.outputs.sha256 }}"
-          ZIP_NAME="${{ steps.meta.outputs.zip_name }}"
-          EXT_ELEMENT="${{ steps.meta.outputs.ext_element }}"
-          TOKEN="${{ secrets.GA_TOKEN }}"
-          API="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
-          BRANCH=$(git branch --show-current)
-
-          BODY="## ${VERSION} ($(date +%Y-%m-%d))
-          **Channel:** ${STABILITY}
-          **SHA-256:** \`${SHA256}\`"
-
-          # Delete existing release
-          EXISTING_ID=$(curl -sS -H "Authorization: token ${TOKEN}" \
-            "${API}/releases/tags/${TAG}" | jq -r '.id // empty' 2>/dev/null)
-          if [ -n "$EXISTING_ID" ]; then
-            curl -sS -X DELETE -H "Authorization: token ${TOKEN}" \
-              "${API}/releases/${EXISTING_ID}" 2>/dev/null || true
-            curl -sS -X DELETE -H "Authorization: token ${TOKEN}" \
-              "${API}/tags/${TAG}" 2>/dev/null || true
-          fi
-
-          # Create release
-          RELEASE_ID=$(curl -sS -X POST -H "Authorization: token ${TOKEN}" \
-            -H "Content-Type: application/json" \
-            "${API}/releases" \
-            -d "$(jq -n \
-              --arg tag "$TAG" \
-              --arg target "$BRANCH" \
-              --arg name "${EXT_ELEMENT} ${VERSION} (${STABILITY})" \
-              --arg body "$BODY" \
-              '{tag_name: $tag, target_commitish: $target, name: $name, body: $body, prerelease: true}'
-            )" | jq -r '.id')
-
-          echo "release_id=${RELEASE_ID}" >> "$GITHUB_OUTPUT"
-
-          # Upload ZIP
-          curl -sS -X POST -H "Authorization: token ${TOKEN}" \
-            -H "Content-Type: application/octet-stream" \
-            "${API}/releases/${RELEASE_ID}/assets?name=${ZIP_NAME}" \
-            --data-binary "@build/${ZIP_NAME}"
-
-          echo "Released: ${EXT_ELEMENT} ${VERSION} (${STABILITY})"
-
-      - name: Update updates.xml
-        if: steps.platform.outputs.platform == 'joomla'
-        run: |
-          STABILITY="${{ steps.meta.outputs.stability }}"
-          VERSION="${{ steps.meta.outputs.version }}"
-          SHA256="${{ steps.zip.outputs.sha256 }}"
-          ZIP_NAME="${{ steps.meta.outputs.zip_name }}"
-          TAG="${{ steps.meta.outputs.tag }}"
-
-          if [ ! -f "updates.xml" ]; then
-            echo "No updates.xml -- skipping"
-            exit 0
-          fi
-
-          # Map stability to XML tag name
-          case "$STABILITY" in
-            development)        XML_TAG="development" ;;
-            alpha)              XML_TAG="alpha" ;;
-            beta)               XML_TAG="beta" ;;
-            release-candidate)  XML_TAG="rc" ;;
-            *)                  XML_TAG="$STABILITY" ;;
-          esac
-
-          DOWNLOAD_URL="${GITEA_URL}/${GITEA_ORG}/${GITEA_REPO}/releases/download/${TAG}/${ZIP_NAME}"
-
-          # Use PHP to update the channel in updates.xml
-          php -r '
-            $xml_tag = $argv[1];
-            $version = $argv[2];
-            $sha256 = $argv[3];
-            $url = $argv[4];
-            $date = date("Y-m-d");
-
-            $content = file_get_contents("updates.xml");
-            $pattern = "/(<update>(?:(?!<\/update>).)*?<tag>" . preg_quote($xml_tag) . "<\/tag>.*?<\/update>)/s";
-
-            $content = preg_replace_callback($pattern, function($m) use ($version, $sha256, $url, $date) {
-              $block = $m[0];
-              $block = preg_replace("/<version>[^<]*<\/version>/", "<version>{$version}</version>", $block);
-              if (strpos($block, "<sha256>") !== false) {
-                $block = preg_replace("/<sha256>[^<]*<\/sha256>/", "<sha256>{$sha256}</sha256>", $block);
-              } else {
-                $block = str_replace("</downloads>", "</downloads>\n    <sha256>{$sha256}</sha256>", $block);
-              }
-              $block = preg_replace("/(<downloadurl[^>]*>)[^<]*(<\/downloadurl>)/", "\${1}{$url}\${2}", $block);
-              return $block;
-            }, $content);
-
-            file_put_contents("updates.xml", $content);
-            echo "Updated {$xml_tag} channel: version={$version}\n";
-          ' "$XML_TAG" "$VERSION" "$SHA256" "$DOWNLOAD_URL"
-
-          # Commit and push
-          if ! git diff --quiet updates.xml 2>/dev/null; then
-            git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
-            git config --local user.name "gitea-actions[bot]"
-            git add updates.xml
-            git commit -m "chore: update ${STABILITY} channel ${VERSION} [skip ci]"
-            git push origin HEAD 2>&1 || echo "WARNING: push failed"
-          fi
-
-      - name: "Sync updates.xml to all branches"
-        if: steps.platform.outputs.platform == 'joomla'
-        run: |
-          CURRENT_BRANCH="${{ github.ref_name }}"
-          git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
-          git config --local user.name "gitea-actions[bot]"
-
-          for BRANCH in main dev; do
-            [ "$BRANCH" = "$CURRENT_BRANCH" ] && continue
-            echo "Syncing updates.xml -> ${BRANCH}"
-            git fetch origin "${BRANCH}" 2>/dev/null || continue
-            git checkout "origin/${BRANCH}" -- . 2>/dev/null || continue
-            git checkout "${CURRENT_BRANCH}" -- updates.xml
-            if ! git diff --quiet updates.xml 2>/dev/null; then
-              git add updates.xml
-              git commit -m "chore: sync updates.xml from ${CURRENT_BRANCH} [skip ci]"
-              git push origin HEAD:refs/heads/${BRANCH} 2>&1 || echo "WARNING: push to ${BRANCH} failed"
-            fi
-            git checkout "${CURRENT_BRANCH}" 2>/dev/null
-          done
-
-      - name: "Delete lesser pre-release channels (cascade)"
-        continue-on-error: true
-        run: |
-          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
-          TOKEN="${{ secrets.GA_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.zip.outputs.sha256 }}"
-          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
+# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# FILE INFORMATION
+# DEFGROUP: Gitea.Workflow
+# INGROUP: moko-platform.Release
+# REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+# PATH: /templates/workflows/universal/pre-release.yml.template
+# VERSION: 05.01.00
+# BRIEF: Manual pre-release -- builds dev/alpha/beta/rc packages from any branch
+
+name: "Universal: Pre-Release"
+
+on:
+  pull_request:
+    types: [closed]
+    branches:
+      - dev
+  workflow_dispatch:
+    inputs:
+      stability:
+        description: 'Pre-release channel'
+        required: true
+        type: choice
+        options:
+          - development
+          - alpha
+          - beta
+          - release-candidate
+
+permissions:
+  contents: write
+
+env:
+  GITEA_URL: ${{ vars.GITEA_URL || 'https://git.mokoconsulting.tech' }}
+  GITEA_ORG: ${{ vars.GITEA_ORG || github.repository_owner }}
+  GITEA_REPO: ${{ vars.GITEA_REPO || github.event.repository.name }}
+
+jobs:
+  build:
+    name: "Build Pre-Release (${{ inputs.stability || 'development' }})"
+    runs-on: release
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      (github.event.pull_request.merged == true && github.event.pull_request.base.ref == 'dev')
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GA_TOKEN }}
+
+      - name: Setup tools
+        run: |
+          # Update moko-platform CLI tools if available; install PHP if missing
+          if command -v moko-platform-update &> /dev/null; then
+            moko-platform-update
+          elif [ -d "/opt/moko-platform" ]; then
+            cd /opt/moko-platform && git pull origin main --quiet 2>/dev/null || true
+          else
+            if ! command -v php &> /dev/null; then
+              sudo apt-get update -qq
+              sudo apt-get install -y -qq php-cli php-mbstring php-xml php-zip php-curl >/dev/null 2>&1
+            fi
+            git clone --depth 1 --branch main --quiet \
+              "https://x-access-token:${{ secrets.GA_TOKEN }}@git.mokoconsulting.tech/MokoConsulting/moko-platform.git" \
+              /tmp/moko-platform-api
+          fi
+          # Set MOKO_CLI to whichever path exists
+          if [ -d "/opt/moko-platform/cli" ]; then
+            echo "MOKO_CLI=/opt/moko-platform/cli" >> "$GITHUB_ENV"
+          else
+            echo "MOKO_CLI=/tmp/moko-platform-api/cli" >> "$GITHUB_ENV"
+          fi
+
+      - name: Detect platform
+        id: platform
+        run: |
+          php ${MOKO_CLI}/manifest_read.php --path . --github-output
+
+      - name: Resolve metadata and bump version
+        id: meta
+        run: |
+          STABILITY="${{ inputs.stability || 'development' }}"
+
+          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
+
+          # Patch bump via CLI tool
+          php ${MOKO_CLI}/version_bump.php --path .
+          VERSION=$(php ${MOKO_CLI}/version_read.php --path . 2>/dev/null)
+          [ -z "$VERSION" ] && VERSION="00.00.01"
+
+          php ${MOKO_CLI}/version_set_platform.php \
+            --path . --version "$VERSION" --branch "${{ github.ref_name }}" 2>/dev/null || true
+
+          # Verify version consistency across all files
+          php ${MOKO_CLI}/version_check.php --path . --fix 2>/dev/null || true
+
+          # Commit version bump
+          git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
+          git config --local user.name "gitea-actions[bot]"
+          git remote set-url origin "https://jmiller:${{ secrets.GA_TOKEN }}@git.mokoconsulting.tech/${{ github.repository }}.git"
+          git add -A
+          git diff --cached --quiet || {
+            git commit -m "chore(version): pre-release bump to ${VERSION} [skip ci]"
+            git push origin HEAD 2>&1
+          }
+
+          # Auto-detect element via manifest_element.php
+          php ${MOKO_CLI}/manifest_element.php \
+            --path . --version "$VERSION" --stability "$STABILITY" \
+            --repo "${GITEA_REPO}" --github-output
+
+          # Read back element outputs
+          EXT_ELEMENT=$(grep '^ext_element=' "$GITHUB_OUTPUT" | tail -1 | cut -d= -f2)
+          ZIP_NAME=$(grep '^zip_name=' "$GITHUB_OUTPUT" | tail -1 | cut -d= -f2)
+          [ -z "$EXT_ELEMENT" ] && EXT_ELEMENT=$(echo "${GITEA_REPO}" | tr '[:upper:]' '[:lower:]' | tr -d ' -')
+          [ -z "$ZIP_NAME" ] && ZIP_NAME="${EXT_ELEMENT}-${VERSION}${SUFFIX}.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 "manifest=${MANIFEST}" >> "$GITHUB_OUTPUT"
+
+          echo "=== Pre-Release: ${EXT_ELEMENT} ${VERSION}${SUFFIX} ==="
+
+      - name: Build package
+        run: |
+          SOURCE_DIR="src"
+          [ ! -d "$SOURCE_DIR" ] && SOURCE_DIR="htdocs"
+          if [ ! -d "$SOURCE_DIR" ]; then
+            echo "::error::No src/ or htdocs/ directory"
+            exit 1
+          fi
+
+          MANIFEST="${{ steps.meta.outputs.manifest }}"
+          EXT_TYPE=""
+          if [ -n "$MANIFEST" ]; then
+            EXT_TYPE=$(sed -n 's/.*<extension[^>]*type="\([^"]*\)".*/\1/p' "$MANIFEST" | head -1)
+          fi
+
+          EXCLUDES="sftp-config* .ftpignore *.ppk *.pem *.key .env* *.local .build-trigger"
+
+          mkdir -p build/package
+
+          if [ "$EXT_TYPE" = "package" ] && [ -d "${SOURCE_DIR}/packages" ]; then
+            echo "=== Building Joomla PACKAGE (multi-extension) ==="
+            for ext_dir in "${SOURCE_DIR}"/packages/*/; do
+              [ ! -d "$ext_dir" ] && continue
+              EXT_NAME=$(basename "$ext_dir")
+              echo "  Packaging sub-extension: ${EXT_NAME}"
+              cd "$ext_dir"
+              zip -r "../../build/package/${EXT_NAME}.zip" . -x $EXCLUDES
+              cd "$OLDPWD"
+            done
+            for f in "${SOURCE_DIR}"/*.xml "${SOURCE_DIR}"/*.php; do
+              [ -f "$f" ] && cp "$f" build/package/
+            done
+          else
+            echo "=== Building standard extension ==="
+            rsync -a \
+              --exclude='sftp-config*' \
+              --exclude='.ftpignore' \
+              --exclude='*.ppk' \
+              --exclude='*.pem' \
+              --exclude='*.key' \
+              --exclude='.env*' \
+              --exclude='*.local' \
+              --exclude='.build-trigger' \
+              "${SOURCE_DIR}/" build/package/
+          fi
+
+      - name: Create ZIP
+        id: zip
+        run: |
+          ZIP_NAME="${{ steps.meta.outputs.zip_name }}"
+          cd build/package
+          zip -r "../${ZIP_NAME}" .
+          cd ..
+
+          SHA256=$(sha256sum "${ZIP_NAME}" | cut -d' ' -f1)
+          echo "sha256=${SHA256}" >> "$GITHUB_OUTPUT"
+          echo "ZIP: ${ZIP_NAME} (SHA: ${SHA256:0:16}...)"
+
+      - name: Create or replace Gitea release
+        id: release
+        run: |
+          TAG="${{ steps.meta.outputs.tag }}"
+          VERSION="${{ steps.meta.outputs.version }}"
+          STABILITY="${{ steps.meta.outputs.stability }}"
+          SHA256="${{ steps.zip.outputs.sha256 }}"
+          ZIP_NAME="${{ steps.meta.outputs.zip_name }}"
+          EXT_ELEMENT="${{ steps.meta.outputs.ext_element }}"
+          TOKEN="${{ secrets.GA_TOKEN }}"
+          API="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
+          BRANCH=$(git branch --show-current)
+
+          BODY="## ${VERSION} ($(date +%Y-%m-%d))
+          **Channel:** ${STABILITY}
+          **SHA-256:** \`${SHA256}\`"
+
+          # Delete existing release
+          EXISTING_ID=$(curl -sS -H "Authorization: token ${TOKEN}" \
+            "${API}/releases/tags/${TAG}" | jq -r '.id // empty' 2>/dev/null)
+          if [ -n "$EXISTING_ID" ]; then
+            curl -sS -X DELETE -H "Authorization: token ${TOKEN}" \
+              "${API}/releases/${EXISTING_ID}" 2>/dev/null || true
+            curl -sS -X DELETE -H "Authorization: token ${TOKEN}" \
+              "${API}/tags/${TAG}" 2>/dev/null || true
+          fi
+
+          # Create release
+          RELEASE_ID=$(curl -sS -X POST -H "Authorization: token ${TOKEN}" \
+            -H "Content-Type: application/json" \
+            "${API}/releases" \
+            -d "$(jq -n \
+              --arg tag "$TAG" \
+              --arg target "$BRANCH" \
+              --arg name "${EXT_ELEMENT} ${VERSION} (${STABILITY})" \
+              --arg body "$BODY" \
+              '{tag_name: $tag, target_commitish: $target, name: $name, body: $body, prerelease: true}'
+            )" | jq -r '.id')
+
+          echo "release_id=${RELEASE_ID}" >> "$GITHUB_OUTPUT"
+
+          # Upload ZIP
+          curl -sS -X POST -H "Authorization: token ${TOKEN}" \
+            -H "Content-Type: application/octet-stream" \
+            "${API}/releases/${RELEASE_ID}/assets?name=${ZIP_NAME}" \
+            --data-binary "@build/${ZIP_NAME}"
+
+          echo "Released: ${EXT_ELEMENT} ${VERSION} (${STABILITY})"
+
+      - name: Update updates.xml
+        if: steps.platform.outputs.platform == 'joomla'
+        run: |
+          VERSION="${{ steps.meta.outputs.version }}"
+          STABILITY="${{ steps.meta.outputs.stability }}"
+
+          if [ ! -f "updates.xml" ]; then
+            echo "No updates.xml -- skipping"
+            exit 0
+          fi
+
+          php ${MOKO_CLI}/updates_xml_build.php \
+            --path . --version "${VERSION}" --stability "${STABILITY}" \
+            --gitea-url "${GITEA_URL}" --org "${GITEA_ORG}" --repo "${GITEA_REPO}"
+
+          # Commit and push
+          if ! git diff --quiet updates.xml 2>/dev/null; then
+            git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
+            git config --local user.name "gitea-actions[bot]"
+            git add updates.xml
+            git commit -m "chore: update ${STABILITY} channel ${VERSION} [skip ci]"
+            git push origin HEAD 2>&1 || echo "WARNING: push failed"
+          fi
+
+      - name: "Sync updates.xml to all branches"
+        if: steps.platform.outputs.platform == 'joomla'
+        run: |
+          CURRENT_BRANCH="${{ github.ref_name }}"
+          git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
+          git config --local user.name "gitea-actions[bot]"
+
+          for BRANCH in main dev; do
+            [ "$BRANCH" = "$CURRENT_BRANCH" ] && continue
+            echo "Syncing updates.xml -> ${BRANCH}"
+            git fetch origin "${BRANCH}" 2>/dev/null || continue
+            git checkout "origin/${BRANCH}" -- . 2>/dev/null || continue
+            git checkout "${CURRENT_BRANCH}" -- updates.xml
+            if ! git diff --quiet updates.xml 2>/dev/null; then
+              git add updates.xml
+              git commit -m "chore: sync updates.xml from ${CURRENT_BRANCH} [skip ci]"
+              git push origin HEAD:refs/heads/${BRANCH} 2>&1 || echo "WARNING: push to ${BRANCH} failed"
+            fi
+            git checkout "${CURRENT_BRANCH}" 2>/dev/null
+          done
+
+      - name: "Delete lesser pre-release channels (cascade)"
+        continue-on-error: true
+        run: |
+          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
+          TOKEN="${{ secrets.GA_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.zip.outputs.sha256 }}"
+          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

.mokogitea/workflows/update-server.yml

@@ -0,0 +1,660 @@
+# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# FILE INFORMATION
+# DEFGROUP: Gitea.Workflow
+# INGROUP: MokoStandards.Universal
+# REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+# PATH: /templates/workflows/update-server.yml
+# VERSION: 04.07.00
+# BRIEF: Update server XML feed with stable/rc/beta/alpha/dev entries (universal)
+#
+# Writes updates.xml with multiple <update> entries:
+#   - <tag>stable</tag>     on push to main (from auto-release)
+#   - <tag>rc</tag>         on push to rc/**
+#   - <tag>development</tag> on push to dev or dev/**
+#
+# Joomla filters by user's "Minimum Stability" setting.
+
+name: "Update Server"
+
+on:
+  push:
+    branches:
+      - 'dev'
+      - 'dev/**'
+      - 'alpha/**'
+      - 'beta/**'
+      - 'rc/**'
+    paths:
+      - 'src/**'
+      - 'htdocs/**'
+  pull_request:
+    types: [closed]
+    branches:
+      - 'dev'
+      - 'dev/**'
+      - 'alpha/**'
+      - 'beta/**'
+      - 'rc/**'
+    paths:
+      - 'src/**'
+      - 'htdocs/**'
+  workflow_dispatch:
+    inputs:
+      stability:
+        description: 'Stability tag'
+        required: true
+        default: 'development'
+        type: choice
+        options:
+          - development
+          - alpha
+          - beta
+          - rc
+          - stable
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+  GITEA_URL: ${{ vars.GITEA_URL || 'https://git.mokoconsulting.tech' }}
+  GITEA_ORG: ${{ vars.GITEA_ORG || github.repository_owner }}
+  GITEA_REPO: ${{ vars.GITEA_REPO || github.event.repository.name }}
+
+permissions:
+  contents: write
+
+jobs:
+  update-xml:
+    name: Update updates.xml
+    runs-on: release
+    if: >-
+      github.event.pull_request.merged == true || github.event_name == 'workflow_dispatch' || github.event_name == 'push'
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GA_TOKEN }}
+          fetch-depth: 0
+
+      - name: Setup moko-platform tools
+        env:
+          MOKO_CLONE_TOKEN: ${{ secrets.GA_TOKEN }}
+          MOKO_CLONE_HOST: git.mokoconsulting.tech/MokoConsulting
+          COMPOSER_AUTH: '{"http-basic":{"git.mokoconsulting.tech":{"username":"token","password":"${{ secrets.GA_TOKEN }}"}}}'
+        run: |
+          if ! command -v composer &> /dev/null; 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
+          if [ -d "/tmp/moko-platform" ]; then
+            echo "moko-platform already available — skipping clone"
+          else
+            git clone --depth 1 --branch main --quiet \
+              "https://x-access-token:${MOKO_CLONE_TOKEN}@${MOKO_CLONE_HOST}/moko-platform.git" \
+              /tmp/moko-platform 2>/dev/null || true
+          fi
+          if [ -d "/tmp/moko-platform" ] && [ -f "/tmp/moko-platform/composer.json" ]; then
+            cd /tmp/moko-platform && composer install --no-dev --no-interaction --quiet 2>/dev/null || true
+          fi
+
+      - name: Generate updates.xml entry
+        id: update
+        run: |
+          BRANCH="${{ github.ref_name }}"
+          REPO="${{ github.repository }}"
+          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
+          VERSION=$(php /tmp/moko-platform/cli/version_read.php --path . 2>/dev/null || echo "0.0.0")
+
+          # Auto-bump patch on all branches (dev, alpha, beta, rc)
+          git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
+          git config --local user.name "gitea-actions[bot]"
+          BUMPED=$(php /tmp/moko-platform/cli/version_bump.php --path . 2>/dev/null || true)
+          if [ -n "$BUMPED" ]; then
+            VERSION=$(php /tmp/moko-platform/cli/version_read.php --path . 2>/dev/null || echo "$VERSION")
+            git add -A
+            git commit -m "chore(version): auto-bump patch ${VERSION} [skip ci]" \
+              --author="gitea-actions[bot] <gitea-actions[bot]@mokoconsulting.tech>" 2>/dev/null || true
+            git push 2>/dev/null || true
+          fi
+
+          # Determine stability from branch or input
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            STABILITY="${{ inputs.stability }}"
+          elif [[ "$BRANCH" == rc/* ]]; then
+            STABILITY="rc"
+          elif [[ "$BRANCH" == beta/* ]]; then
+            STABILITY="beta"
+          elif [[ "$BRANCH" == alpha/* ]]; then
+            STABILITY="alpha"
+          elif [[ "$BRANCH" == dev/* ]] || [[ "$BRANCH" == "dev" ]]; then
+            STABILITY="development"
+          else
+            STABILITY="stable"
+          fi
+
+          echo "stability=${STABILITY}" >> "$GITHUB_OUTPUT"
+
+          # Parse manifest (portable — no grep -P)
+          MANIFEST=$(find . -maxdepth 3 -name "*.xml" ! -path "./.git/*" ! -path "./build/*" -exec grep -l '<extension' {} \; 2>/dev/null | head -1)
+          if [ -z "$MANIFEST" ]; then
+            echo "No Joomla manifest found — skipping"
+            exit 0
+          fi
+
+          # Extract fields using sed (works on all runners)
+          EXT_NAME=$(sed -n 's/.*<name>\([^<]*\)<\/name>.*/\1/p' "$MANIFEST" | head -1)
+          EXT_TYPE=$(sed -n 's/.*<extension[^>]*type="\([^"]*\)".*/\1/p' "$MANIFEST" | head -1)
+          EXT_ELEMENT=$(sed -n 's/.*<element>\([^<]*\)<\/element>.*/\1/p' "$MANIFEST" | head -1)
+          EXT_CLIENT=$(sed -n 's/.*<extension[^>]*client="\([^"]*\)".*/\1/p' "$MANIFEST" | head -1)
+          EXT_FOLDER=$(sed -n 's/.*<extension[^>]*group="\([^"]*\)".*/\1/p' "$MANIFEST" | head -1)
+          EXT_VERSION=$(sed -n 's/.*<version>\([^<]*\)<\/version>.*/\1/p' "$MANIFEST" | head -1)
+          TARGET_PLATFORM=$(sed -n 's/.*\(<targetplatform[^/]*\/>\).*/\1/p' "$MANIFEST" | head -1)
+          PHP_MINIMUM=$(sed -n 's/.*<php_minimum>\([^<]*\)<\/php_minimum>.*/\1/p' "$MANIFEST" | head -1)
+
+          # Fallbacks
+          [ -z "$EXT_NAME" ] && EXT_NAME="${{ github.event.repository.name }}"
+          [ -z "$EXT_TYPE" ] && EXT_TYPE="component"
+
+          # Derive element if not in manifest: try XML filename, then repo name
+          if [ -z "$EXT_ELEMENT" ]; then
+            EXT_ELEMENT=$(basename "$MANIFEST" .xml | tr '[:upper:]' '[:lower:]')
+            case "$EXT_ELEMENT" in
+              templatedetails|manifest|*.xml) EXT_ELEMENT=$(echo "${{ github.event.repository.name }}" | tr '[:upper:]' '[:lower:]' | tr -d ' -') ;;
+            esac
+          fi
+
+          # Use manifest version if README version is empty
+          [ "$VERSION" = "0.0.0" ] && [ -n "$EXT_VERSION" ] && VERSION="$EXT_VERSION"
+
+          [ -z "$TARGET_PLATFORM" ] && TARGET_PLATFORM=$(printf '<targetplatform name="joomla" version="((5.[0-9])|(6.[0-9]))" %s>' "/")
+
+          # Joomla requires <client> on ALL extension types for update matching
+          if [ -n "$EXT_CLIENT" ]; then
+            CLIENT_TAG="<client>${EXT_CLIENT}</client>"
+          else
+            CLIENT_TAG="<client>site</client>"
+          fi
+
+          FOLDER_TAG=""
+          [ -n "$EXT_FOLDER" ] && [ "$EXT_TYPE" = "plugin" ] && FOLDER_TAG="<folder>${EXT_FOLDER}</folder>"
+
+          PHP_TAG=""
+          [ -n "$PHP_MINIMUM" ] && PHP_TAG="<php_minimum>${PHP_MINIMUM}</php_minimum>"
+
+          # Version suffix for non-stable
+          DISPLAY_VERSION="$VERSION"
+          case "$STABILITY" in
+            development) DISPLAY_VERSION="${VERSION}-dev" ;;
+            alpha)       DISPLAY_VERSION="${VERSION}-alpha" ;;
+            beta)        DISPLAY_VERSION="${VERSION}-beta" ;;
+            rc)          DISPLAY_VERSION="${VERSION}-rc" ;;
+          esac
+
+          MAJOR=$(echo "$VERSION" | awk -F. '{print $1}')
+
+          # Each stability level has its own release tag
+          case "$STABILITY" in
+            development) RELEASE_TAG="development" ;;
+            alpha)       RELEASE_TAG="alpha" ;;
+            beta)        RELEASE_TAG="beta" ;;
+            rc)          RELEASE_TAG="release-candidate" ;;
+            *)           RELEASE_TAG="v${MAJOR}" ;;
+          esac
+
+          PACKAGE_NAME="${EXT_ELEMENT}-${DISPLAY_VERSION}.zip"
+          DOWNLOAD_URL="${GITEA_URL}/${GITEA_ORG}/${GITEA_REPO}/releases/download/${RELEASE_TAG}/${PACKAGE_NAME}"
+          INFO_URL="${GITEA_URL}/${GITEA_ORG}/${GITEA_REPO}"
+
+          # -- Build install packages (ZIP + tar.gz) --------------------
+          SOURCE_DIR="src"
+          [ ! -d "$SOURCE_DIR" ] && SOURCE_DIR="htdocs"
+          if [ -d "$SOURCE_DIR" ]; then
+            EXCLUDES=".ftpignore sftp-config* *.ppk *.pem *.key .env*"
+            TAR_NAME="${EXT_ELEMENT}-${DISPLAY_VERSION}.tar.gz"
+
+            cd "$SOURCE_DIR"
+            zip -r "/tmp/${PACKAGE_NAME}" . -x $EXCLUDES
+            cd ..
+            tar -czf "/tmp/${TAR_NAME}" -C "$SOURCE_DIR" \
+              --exclude='.ftpignore' --exclude='sftp-config*' \
+              --exclude='*.ppk' --exclude='*.pem' --exclude='*.key' --exclude='.env*' .
+
+            SHA256=$(sha256sum "/tmp/${PACKAGE_NAME}" | cut -d' ' -f1)
+
+            # Ensure release exists on Gitea
+            RELEASE_JSON=$(curl -sf -H "Authorization: token ${{ secrets.GA_TOKEN }}" \
+              "${API_BASE}/releases/tags/${RELEASE_TAG}" 2>/dev/null || true)
+            RELEASE_ID=$(echo "$RELEASE_JSON" | python3 -c "import sys,json; print(json.load(sys.stdin).get('id',''))" 2>/dev/null || true)
+
+            if [ -z "$RELEASE_ID" ]; then
+              # Create release
+              RELEASE_JSON=$(curl -sf -X POST -H "Authorization: token ${{ secrets.GA_TOKEN }}" \
+                -H "Content-Type: application/json" \
+                "${API_BASE}/releases" \
+                -d "$(python3 -c "import json; print(json.dumps({
+                  'tag_name': '${RELEASE_TAG}',
+                  'name': '${RELEASE_TAG} (${DISPLAY_VERSION})',
+                  'body': '${STABILITY} release',
+                  'prerelease': True,
+                  'target_commitish': 'main'
+                }))")" 2>/dev/null || true)
+              RELEASE_ID=$(echo "$RELEASE_JSON" | python3 -c "import sys,json; print(json.load(sys.stdin).get('id',''))" 2>/dev/null || true)
+            fi
+
+            if [ -n "$RELEASE_ID" ]; then
+              # Delete existing assets with same name before uploading
+              ASSETS=$(curl -sf -H "Authorization: token ${{ secrets.GA_TOKEN }}" \
+                "${API_BASE}/releases/${RELEASE_ID}/assets" 2>/dev/null || echo "[]")
+              for ASSET_FILE in "$PACKAGE_NAME" "$TAR_NAME"; do
+                ASSET_ID=$(echo "$ASSETS" | python3 -c "
+          import sys,json
+          assets = json.load(sys.stdin)
+          for a in assets:
+              if a['name'] == '${ASSET_FILE}':
+                  print(a['id']); break
+          " 2>/dev/null || true)
+                if [ -n "$ASSET_ID" ]; then
+                  curl -sf -X DELETE -H "Authorization: token ${{ secrets.GA_TOKEN }}" \
+                    "${API_BASE}/releases/${RELEASE_ID}/assets/${ASSET_ID}" 2>/dev/null || true
+                fi
+              done
+
+              # Upload both formats
+              curl -sf -X POST -H "Authorization: token ${{ secrets.GA_TOKEN }}" \
+                -H "Content-Type: application/octet-stream" \
+                --data-binary @"/tmp/${PACKAGE_NAME}" \
+                "${API_BASE}/releases/${RELEASE_ID}/assets?name=${PACKAGE_NAME}" > /dev/null 2>&1 || true
+
+              curl -sf -X POST -H "Authorization: token ${{ secrets.GA_TOKEN }}" \
+                -H "Content-Type: application/octet-stream" \
+                --data-binary @"/tmp/${TAR_NAME}" \
+                "${API_BASE}/releases/${RELEASE_ID}/assets?name=${TAR_NAME}" > /dev/null 2>&1 || true
+            fi
+
+            echo "Packages: ${PACKAGE_NAME} + ${TAR_NAME} (SHA: ${SHA256})" >> $GITHUB_STEP_SUMMARY
+          else
+            SHA256=""
+          fi
+
+          # -- Build the new entry (canonical format matching release.yml) --
+          NEW_ENTRY=""
+          NEW_ENTRY="${NEW_ENTRY}  <update>\n"
+          NEW_ENTRY="${NEW_ENTRY}    <name>${EXT_NAME}</name>\n"
+          NEW_ENTRY="${NEW_ENTRY}    <description>${EXT_NAME} ${STABILITY} build.</description>\n"
+          NEW_ENTRY="${NEW_ENTRY}    <element>${EXT_ELEMENT}</element>\n"
+          NEW_ENTRY="${NEW_ENTRY}    <type>${EXT_TYPE}</type>\n"
+          [ -n "$CLIENT_TAG" ] && NEW_ENTRY="${NEW_ENTRY}    ${CLIENT_TAG}\n"
+          [ -n "$FOLDER_TAG" ] && NEW_ENTRY="${NEW_ENTRY}    ${FOLDER_TAG}\n"
+          NEW_ENTRY="${NEW_ENTRY}    <version>${VERSION}</version>\n"
+          NEW_ENTRY="${NEW_ENTRY}    <creationDate>$(date +%Y-%m-%d)</creationDate>\n"
+          NEW_ENTRY="${NEW_ENTRY}    <infourl title='${EXT_NAME}'>https://git.mokoconsulting.tech/${GITEA_ORG}/${GITEA_REPO}/releases/tag/${RELEASE_TAG}</infourl>\n"
+          NEW_ENTRY="${NEW_ENTRY}    <downloads>\n"
+          NEW_ENTRY="${NEW_ENTRY}      <downloadurl type='full' format='zip'>${DOWNLOAD_URL}</downloadurl>\n"
+          NEW_ENTRY="${NEW_ENTRY}    </downloads>\n"
+          [ -n "$SHA256" ] && NEW_ENTRY="${NEW_ENTRY}    <sha256>${SHA256}</sha256>\n"
+          NEW_ENTRY="${NEW_ENTRY}    <tags><tag>${STABILITY}</tag></tags>\n"
+          NEW_ENTRY="${NEW_ENTRY}    <maintainer>Moko Consulting</maintainer>\n"
+          NEW_ENTRY="${NEW_ENTRY}    <maintainerurl>https://mokoconsulting.tech</maintainerurl>\n"
+          NEW_ENTRY="${NEW_ENTRY}    <targetplatform name='joomla' version='(5|6).*'/>\n"
+          [ -n "$PHP_MINIMUM" ] && NEW_ENTRY="${NEW_ENTRY}    <php_minimum>${PHP_MINIMUM}</php_minimum>\n"
+          NEW_ENTRY="${NEW_ENTRY}  </update>"
+
+          # -- Write new entry to temp file --------------------------------
+          printf '%b' "$NEW_ENTRY" > /tmp/new_entry.xml
+
+          # -- Merge into updates.xml ----------------------------------------
+          # Cascade: stable→all | rc→rc+lower | beta→beta+lower | alpha→alpha+dev | dev→dev
+          CASCADE_MAP="stable:development,alpha,beta,rc,stable rc:development,alpha,beta,rc beta:development,alpha,beta alpha:development,alpha development:development"
+          TARGETS=""
+          for entry in $CASCADE_MAP; do
+            key="${entry%%:*}"
+            vals="${entry#*:}"
+            if [ "$key" = "${STABILITY}" ]; then
+              TARGETS="$vals"
+              break
+            fi
+          done
+          [ -z "$TARGETS" ] && TARGETS="${STABILITY}"
+
+          echo "Cascade: ${STABILITY} → ${TARGETS}"
+
+          # Create updates.xml if missing
+          if [ ! -f "updates.xml" ]; then
+            printf '%s\n' "<?xml version='1.0' encoding='UTF-8'?>" > updates.xml
+            printf '%s\n' "<!-- Copyright (C) $(date +%Y) Moko Consulting -->" >> updates.xml
+            printf '%s\n' "<updates>" >> updates.xml
+            printf '%s\n' "</updates>" >> updates.xml
+          fi
+
+          # Update existing blocks or create missing ones
+          export PY_TARGETS="$TARGETS" PY_VERSION="$VERSION" PY_DATE="$(date +%Y-%m-%d)"
+          python3 << 'PYEOF'
+          import re, os
+
+          targets = os.environ["PY_TARGETS"].split(",")
+          version = os.environ["PY_VERSION"]
+          date = os.environ["PY_DATE"]
+
+          with open("updates.xml") as f:
+              content = f.read()
+          with open("/tmp/new_entry.xml") as f:
+              new_entry_template = f.read()
+
+          for tag in targets:
+              tag = tag.strip()
+              # Build entry with this tag's name
+              new_entry = re.sub(r"<tag>[^<]*</tag>", f"<tag>{tag}</tag>", new_entry_template)
+
+              # Try to find existing block (handles both single-line and multi-line <tags>)
+              block_pattern = r"(<update>(?:(?!</update>).)*?<tag>" + re.escape(tag) + r"</tag>.*?</update>)"
+              match = re.search(block_pattern, content, re.DOTALL)
+
+              if match:
+                  # Update in place — replace entire block
+                  content = content.replace(match.group(1), new_entry.strip())
+                  print(f"  UPDATED: <tag>{tag}</tag> → {version}")
+              else:
+                  # Create — insert before </updates>
+                  content = content.replace("</updates>", "\n" + new_entry.strip() + "\n\n</updates>")
+                  print(f"  CREATED: <tag>{tag}</tag> → {version}")
+
+          # Clean up excessive blank lines
+          content = re.sub(r"\n{3,}", "\n\n", content)
+
+          with open("updates.xml", "w") as f:
+              f.write(content)
+          PYEOF
+
+          # Commit
+          git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
+          git config --local user.name "gitea-actions[bot]"
+          git add updates.xml
+          git diff --cached --quiet || {
+            git commit -m "chore: update updates.xml (${STABILITY}: ${DISPLAY_VERSION}) [skip ci]" \
+              --author="gitea-actions[bot] <gitea-actions[bot]@mokoconsulting.tech>"
+            git push
+          }
+
+      # -- Sync updates.xml to main (for non-main branches) ----------------------
+      - name: Sync updates.xml to main
+        if: github.ref_name != 'main'
+        run: |
+          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
+          GA_TOKEN="${{ secrets.GA_TOKEN }}"
+
+          FILE_SHA=$(curl -sf -H "Authorization: token ${GA_TOKEN}" \
+            "${API_BASE}/contents/updates.xml?ref=main" | python3 -c "import sys,json; print(json.load(sys.stdin).get('sha',''))" 2>/dev/null || true)
+
+          if [ -n "$FILE_SHA" ] && [ -f "updates.xml" ]; then
+            python3 -c "
+          import base64, json, urllib.request, sys
+          with open('updates.xml', 'rb') as f:
+              content = base64.b64encode(f.read()).decode()
+          payload = json.dumps({
+              'content': content,
+              'sha': '${FILE_SHA}',
+              'message': 'chore: sync updates.xml from ${STABILITY} [skip ci]',
+              'branch': 'main'
+          }).encode()
+          req = urllib.request.Request(
+              '${API_BASE}/contents/updates.xml',
+              data=payload, method='PUT',
+              headers={
+                  'Authorization': 'token ${GA_TOKEN}',
+                  'Content-Type': 'application/json'
+              })
+          try:
+              urllib.request.urlopen(req)
+              print('updates.xml synced to main')
+          except Exception as e:
+              print(f'ERROR: failed to sync updates.xml to main: {e}', file=sys.stderr)
+              sys.exit(1)
+          " \
+              && echo "updates.xml synced to main (${STABILITY})" >> $GITHUB_STEP_SUMMARY \
+              || echo "::error::failed to sync updates.xml to main" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "::error::could not get updates.xml SHA from main — file may not exist on main yet" >> $GITHUB_STEP_SUMMARY
+          fi
+
+      - name: SFTP deploy to dev server
+        if: contains(github.ref, 'dev/') || github.ref == 'refs/heads/dev'
+        env:
+          DEV_HOST: ${{ vars.DEV_FTP_HOST }}
+          DEV_PATH: ${{ vars.DEV_FTP_PATH }}
+          DEV_SUFFIX: ${{ vars.DEV_FTP_SUFFIX }}
+          DEV_USER: ${{ vars.DEV_FTP_USERNAME }}
+          DEV_PORT: ${{ vars.DEV_FTP_PORT }}
+          DEV_KEY: ${{ secrets.DEV_FTP_KEY }}
+          DEV_PASS: ${{ secrets.DEV_FTP_PASSWORD }}
+        run: |
+          # -- Permission check: admin or maintain role required --------
+          ACTOR="${{ github.actor }}"
+          REPO="${{ github.repository }}"
+          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
+
+          PERMISSION=$(curl -sf -H "Authorization: token ${{ secrets.GA_TOKEN }}" \
+            "${API_BASE}/collaborators/${ACTOR}/permission" 2>/dev/null | \
+            python3 -c "import sys,json; print(json.load(sys.stdin).get('permission','read'))" 2>/dev/null || echo "read")
+          case "$PERMISSION" in
+            admin|maintain|write) ;;
+            *)
+              echo "Deploy denied: ${ACTOR} has '${PERMISSION}' — requires admin, maintain, or write"
+              exit 0
+              ;;
+          esac
+
+          [ -z "$DEV_HOST" ] || [ -z "$DEV_PATH" ] && { echo "DEV FTP not configured — skipping SFTP"; exit 0; }
+
+          SOURCE_DIR="src"
+          [ ! -d "$SOURCE_DIR" ] && SOURCE_DIR="htdocs"
+          [ ! -d "$SOURCE_DIR" ] && exit 0
+
+          PORT="${DEV_PORT:-22}"
+          REMOTE="${DEV_PATH%/}"
+          [ -n "$DEV_SUFFIX" ] && REMOTE="${REMOTE}/${DEV_SUFFIX#/}"
+
+          printf '{"host":"%s","port":%s,"username":"%s","remotePath":"%s"' \
+            "$DEV_HOST" "$PORT" "$DEV_USER" "$REMOTE" > /tmp/sftp-config.json
+          if [ -n "$DEV_KEY" ]; then
+            echo "$DEV_KEY" > /tmp/deploy_key && chmod 600 /tmp/deploy_key
+            printf ',"privateKeyPath":"/tmp/deploy_key"}' >> /tmp/sftp-config.json
+          else
+            printf ',"password":"%s"}' "$DEV_PASS" >> /tmp/sftp-config.json
+          fi
+
+          PLATFORM=$(php /tmp/moko-platform/cli/platform_detect.php --path . 2>/dev/null || true)
+          if [ "$PLATFORM" = "waas-component" ] && [ -f "/tmp/moko-platform/deploy/deploy-joomla.php" ]; then
+            php /tmp/moko-platform/deploy/deploy-joomla.php --path . --src-dir "$SOURCE_DIR" --config /tmp/sftp-config.json
+          elif [ -f "/tmp/moko-platform/deploy/deploy-sftp.php" ]; then
+            php /tmp/moko-platform/deploy/deploy-sftp.php --path . --src-dir "$SOURCE_DIR" --config /tmp/sftp-config.json
+          fi
+          rm -f /tmp/deploy_key /tmp/sftp-config.json
+          echo "SFTP deploy to dev complete" >> $GITHUB_STEP_SUMMARY
+
+      - name: Validate updates.xml integrity
+        run: |
+          ERRORS=0
+
+          if [ ! -f "updates.xml" ]; then
+            echo "::error::updates.xml not found"
+            exit 1
+          fi
+
+          # Well-formed XML
+          if ! python3 -c "import xml.etree.ElementTree as ET; ET.parse('updates.xml')" 2>/dev/null; then
+            echo "::error::updates.xml is not valid XML"
+            ERRORS=$((ERRORS+1))
+          fi
+
+          python3 << 'PYEOF'
+          import xml.etree.ElementTree as ET, sys, re, os
+
+          tree = ET.parse("updates.xml")
+          root = tree.getroot()
+          updates = root.findall("update")
+          errors = 0
+          warnings = 0
+          seen_tags = set()
+
+          # All 5 channels MUST be present
+          REQUIRED_CHANNELS = {"stable", "rc", "beta", "alpha", "dev"}
+          VALID_TAGS = REQUIRED_CHANNELS | {"development"}  # accept legacy alias
+          REPO = os.environ.get("GITEA_REPO", "")
+          ORG = os.environ.get("GITEA_ORG", "MokoConsulting")
+          REPO_BASE = f"https://git.mokoconsulting.tech/{ORG}/"
+
+          # Gitea release tag names per channel (Moko standard)
+          RELEASE_TAG_MAP = {
+              "stable": "stable",
+              "rc": "release-candidate",
+              "beta": "beta",
+              "alpha": "alpha",
+              "dev": "development",
+              "development": "development",
+          }
+
+          # Joomla update XML required fields per
+          # https://docs.joomla.org/Deploying_an_Update_Server
+          REQUIRED_FIELDS = ["name", "element", "type", "version", "infourl"]
+
+          for i, u in enumerate(updates):
+              tag_el = u.find("tags/tag")
+              tag = tag_el.text.strip() if tag_el is not None and tag_el.text else None
+              label = f"Entry {i+1} (<tag>{tag or '?'}</tag>)"
+
+              # -- Required Joomla fields --
+              for field in REQUIRED_FIELDS:
+                  el = u.find(field)
+                  if el is None or not (el.text or "").strip():
+                      print(f"::error::{label}: missing required <{field}>")
+                      errors += 1
+
+              # -- <downloads><downloadurl> --
+              dl = u.find("downloads/downloadurl")
+              if dl is None or not (dl.text or "").strip():
+                  print(f"::error::{label}: missing <downloads><downloadurl>")
+                  errors += 1
+              else:
+                  dl_url = dl.text.strip()
+                  # Must point to org repo
+                  if REPO_BASE not in dl_url:
+                      print(f"::error::{label}: download URL not under {REPO_BASE}: {dl_url}")
+                      errors += 1
+                  # Must end in .zip
+                  if not dl_url.endswith(".zip"):
+                      print(f"::error::{label}: download URL must end in .zip: {dl_url}")
+                      errors += 1
+                  # Must use correct Gitea release tag in path
+                  if tag and tag in RELEASE_TAG_MAP:
+                      expected_tag = RELEASE_TAG_MAP[tag]
+                      if f"/download/{expected_tag}/" not in dl_url:
+                          print(f"::error::{label}: download URL should contain /download/{expected_tag}/ but got: {dl_url}")
+                          errors += 1
+
+              # -- <client> (required for Joomla to match update) --
+              client = u.find("client")
+              if client is None or not (client.text or "").strip():
+                  print(f"::error::{label}: missing <client> (required for Joomla update matching)")
+                  errors += 1
+
+              # -- <targetplatform> --
+              tp = u.find("targetplatform")
+              if tp is None:
+                  print(f"::error::{label}: missing <targetplatform>")
+                  errors += 1
+              else:
+                  tp_name = tp.get("name", "")
+                  tp_ver = tp.get("version", "")
+                  if tp_name != "joomla":
+                      print(f"::error::{label}: targetplatform name should be 'joomla', got '{tp_name}'")
+                      errors += 1
+                  if not tp_ver:
+                      print(f"::error::{label}: targetplatform missing version regex")
+                      errors += 1
+                  elif "5" not in tp_ver or "6" not in tp_ver:
+                      print(f"::warning::{label}: targetplatform version may not cover Joomla 5+6: {tp_ver}")
+                      warnings += 1
+
+              # -- <type> must be valid Joomla type --
+              type_el = u.find("type")
+              if type_el is not None and type_el.text:
+                  valid_types = {"component", "module", "plugin", "template", "library", "package", "file"}
+                  if type_el.text.strip() not in valid_types:
+                      print(f"::error::{label}: invalid type '{type_el.text}' (expected: {valid_types})")
+                      errors += 1
+
+              # -- <version> format (XX.YY.ZZ with optional suffix) --
+              ver_el = u.find("version")
+              if ver_el is not None and ver_el.text:
+                  if not re.match(r"^\d{2}\.\d{2}\.\d{2}(-\w+)?$", ver_el.text.strip()):
+                      print(f"::warning::{label}: version '{ver_el.text}' does not match XX.YY.ZZ format")
+                      warnings += 1
+
+              # -- <maintainer> and <maintainerurl> --
+              for field in ["maintainer", "maintainerurl"]:
+                  el = u.find(field)
+                  if el is None or not (el.text or "").strip():
+                      print(f"::warning::{label}: missing <{field}>")
+                      warnings += 1
+
+              # -- Valid stability tag --
+              if tag is None:
+                  print(f"::error::{label}: missing <tags><tag>")
+                  errors += 1
+              elif tag not in VALID_TAGS:
+                  print(f"::error::{label}: invalid tag '{tag}' (expected: {VALID_TAGS})")
+                  errors += 1
+
+              # -- Duplicate tag check --
+              norm_tag = "dev" if tag == "development" else tag
+              if norm_tag in seen_tags:
+                  print(f"::error::{label}: duplicate channel '{tag}'")
+                  errors += 1
+              if norm_tag:
+                  seen_tags.add(norm_tag)
+
+          # -- All 5 channels must exist --
+          missing = REQUIRED_CHANNELS - seen_tags
+          if missing:
+              print(f"::error::Missing required update channels: {', '.join(sorted(missing))}")
+              errors += 1
+
+          # -- Version ordering: higher stability must not exceed dev version --
+          channel_versions = {}
+          for u in updates:
+              tag_el = u.find("tags/tag")
+              ver_el = u.find("version")
+              if tag_el is not None and ver_el is not None and tag_el.text and ver_el.text:
+                  norm = "dev" if tag_el.text.strip() == "development" else tag_el.text.strip()
+                  # Strip suffix for comparison (01.00.18-dev -> 01.00.18)
+                  base_ver = re.sub(r"-\w+$", "", ver_el.text.strip())
+                  channel_versions[norm] = base_ver
+
+          # Cascade check: dev >= alpha >= beta >= rc >= stable
+          ORDER = ["dev", "alpha", "beta", "rc", "stable"]
+          for j in range(1, len(ORDER)):
+              current = ORDER[j]
+              previous = ORDER[j - 1]
+              if current in channel_versions and previous in channel_versions:
+                  if channel_versions[current] > channel_versions[previous]:
+                      print(f"::error::{current} version ({channel_versions[current]}) is ahead of {previous} ({channel_versions[previous]})")
+                      errors += 1
+
+          # -- Summary --
+          print(f"\nupdates.xml validation: {len(updates)} entries, {errors} error(s), {warnings} warning(s)")
+          if errors > 0:
+              sys.exit(1)
+          PYEOF
+
+      - name: Summary
+        if: always()
+        run: |
+          echo "## Joomla Update Server" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "| Field | Value |" >> $GITHUB_STEP_SUMMARY
+          echo "|-------|-------|" >> $GITHUB_STEP_SUMMARY
+          echo "| Stability | \`${STABILITY}\` |" >> $GITHUB_STEP_SUMMARY
+          echo "| Version | \`${DISPLAY_VERSION}\` |" >> $GITHUB_STEP_SUMMARY
+          echo "| Element | \`${EXT_ELEMENT}\` |" >> $GITHUB_STEP_SUMMARY
+          echo "| Download | [ZIP](${DOWNLOAD_URL}) |" >> $GITHUB_STEP_SUMMARY

CHANGELOG.md

@@ -18,15 +18,54 @@ Version format: `XX.YY.ZZ` (zero-padded semver).
 
 ## [Unreleased]
 
+## [09.00.00] - 2026-05-26
+
 ### Added
-- `cli/client_provision.php` — end-to-end client onboarding (addresses #4)
-- `cli/client_dashboard.php` — unified client dashboard: health, SSL, uptime, releases (closes #3)
+- PHPDoc on Priority 1 Enterprise classes (CliFramework, adapters, ApiClient)
+- Wiki: Coding-Standards page with PHPDoc standard, PHPCS exclusions, file patterns
+- CI: PHPStan enforced at level 6 (was advisory), PHPUnit blocks on failure
+
+### Fixed
+- `updates_xml_build.php`: cascade entries down to lower channels — stable now writes all 5 entries instead of wiping them
+- `updates_xml_build.php`: separate Joomla stability tags (`dev`, `rc`) from Gitea release tags (`development`, `release-candidate`) — download URLs now point to correct release assets
+- `updates_xml_build.php`: only emit `<client>site</client>` for templates and modules, not packages or components
+- `updates_xml_build.php`: preservation logic matches Joomla tag names when deciding which existing entries to keep
+
+## [08.00.00] - 2026-05-26
+
+### Changed
+- PHPStan: level 5 → 6 (401 baselined, 0 new errors)
+- Branch protection: 5 required checks enabled on main
+- Workflows synced to all governed repos (72+ repos across 3 orgs)
+- Flushed 44 stale runners from Gitea admin (3 active remain)
+
+### Fixed
+- PHPStan level 3→4: removed 13 dead properties, 41 defensive patterns baselined
+- PHPStan level 4→5: fixed metrics `increment()` bug (labels passed as value param)
+- PHPStan level 5→6: 360 missing array generic types baselined
+
+## [07.00.00] - 2026-05-25
+
+### Added
+- `cli/client_provision.php` — end-to-end client onboarding from JSON config (closes #4)
+- `cli/client_dashboard.php` — unified HTML dashboard: health, SSL, uptime, releases (closes #3)
+- `cli/client_health_check.php`, `cli/joomla_compat_check.php`, `cli/theme_lint.php` — new CLI tools
+- `lib/Enterprise/ConfigValidator.php` — JSON schema validator for plugin configs (closes #105)
+- PHPUnit test infrastructure: `phpunit.xml` + 19 tests (closes #102)
+- `bin/moko list` — auto-grouped command list with 45 commands, plugin command dispatcher (closes #104)
 - `templates/client-provision-example.json` — example config for client provisioning
 
 ### Fixed
-- `release_cascade.php`: accept `release-candidate` as stability value (was only accepting `rc`, causing cascade to silently skip)
-- PHPStan bumped from level 0 to level 2 — fixed 67 type errors (undefined variables, missing methods, wrong signatures, dead code)
-- `package_build.php`: fix 0-byte ZIP for Joomla package extensions — sub-zips now in `packages/` subdir, no double `pkg_pkg_` prefix, includes `language/` dir (closes #92)
+- `bin/moko` COMMAND_MAP: all paths pointed to non-existent `api/` directory (closes #100)
+- `release_cascade.php`: accept `release-candidate` as stability value (was silently skipping)
+- `package_build.php`: fix 0-byte ZIP for Joomla packages — correct structure, no double prefix (closes #92)
+- PHPStan: level 0 to 2, 67 type errors fixed, 0 exclusions
+- `ApiClient::delete()`: accept optional body parameter for Gitea Contents API
+
+### Changed
+- Migrated all 7 CLIApp scripts to CliFramework (closes #101)
+- Updated CLAUDE.md with current architecture, CLI patterns, code quality (closes #103)
+- Wiki CLI_AUTOMATION page updated with all tools
 
 ## [06.00.00] - 2026-05-25
 

CLAUDE.md

@@ -4,34 +4,100 @@ This file provides guidance to Claude Code when working with this repository.
 
 ## Project Overview
 
-**moko-platform** -- Enterprise automation, validation, sync, and governance engine for all Moko Consulting repositories
+**moko-platform** — Enterprise automation, validation, sync, and governance engine for all Moko Consulting repositories
 
 | Field | Value |
 |---|---|
-| **Platform** | generic |
-| **Language** | HCL |
+| **Language** | PHP 8.1+ |
 | **Default branch** | main |
 | **License** | GPL-3.0-or-later |
+| **Version** | 09.01.00 |
 | **Wiki** | [moko-platform Wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki) |
-| **Standards** | [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) |
 
 ## Common Commands
 
 ```bash
-composer install  # Install PHP dependencies
+composer install                         # Install PHP dependencies
+php bin/moko health --path .             # Run repo health check
+php bin/moko check:syntax --path .       # PHP syntax check
+php bin/moko drift --org MokoConsulting  # Scan for standards drift
+php bin/moko dashboard --token $TOKEN -o dashboard.html  # Generate client dashboard
+
+# Code quality
+php vendor/bin/phpcs --standard=phpcs.xml -n lib/ validate/ automation/ cli/
+php vendor/bin/phpcbf --standard=phpcs.xml lib/ validate/ automation/ cli/
+php vendor/bin/phpstan analyse -c phpstan.neon --memory-limit=512M
+
+# Run all checks
+composer check
 ```
 
 ## Architecture
 
-See the [wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki) for architecture details.
+### Directory Layout
+
+| Directory | Purpose |
+|-----------|---------|
+| `cli/` | 32 standalone CLI tools (version, release, build, repo management) |
+| `validate/` | 20 validation scripts (syntax, structure, manifests, drift) |
+| `automation/` | 7 bulk operations (sync, push files, templates, cleanup) |
+| `lib/Enterprise/` | Core library — CliFramework, ApiClient, adapters, validators |
+| `lib/Enterprise/Plugins/` | 11 platform plugins (Joomla, Dolibarr, Node.js, Python, etc.) |
+| `deploy/` | SFTP deployment scripts (Joomla, Dolibarr, health checks) |
+| `definitions/` | Repository structure definitions (HCL format) |
+| `templates/` | Workflow templates, config templates, docs templates |
+| `.mokogitea/workflows/` | CI/CD workflows (Gitea Actions) |
+| `bin/moko` | Unified CLI dispatcher — runs any tool via `php bin/moko <command>` |
+
+### CLI Framework
+
+All CLI tools extend `MokoEnterprise\CliFramework` (defined in `lib/Enterprise/CliFramework.php`).
+
+Pattern for new tools:
+```php
+class MyTool extends CliFramework {
+    protected function configure(): void {
+        $this->setDescription('What this tool does');
+        $this->addArgument('--name', 'Description', 'default');
+    }
+    protected function run(): int {
+        $name = $this->getArgument('--name');
+        // ... business logic ...
+        return 0;
+    }
+}
+$app = new MyTool();
+exit($app->execute());
+```
+
+Built-in flags: `--help`, `--verbose`, `--quiet`, `--dry-run`
+
+### Platform Adapters
+
+Git operations are abstracted via `GitPlatformAdapter` interface:
+- `MokoGiteaAdapter` — for git.mokoconsulting.tech (primary)
+- `GitHubAdapter` — for github.com mirrors
+
+### Plugin System
+
+Platform-specific logic lives in `lib/Enterprise/Plugins/`. Each plugin implements `ProjectPluginInterface` with methods for health checks, validation, build commands, and config schemas.
+
+## Code Quality
+
+| Tool | Level | Config |
+|------|-------|--------|
+| PHPCS | PSR-12 (errors only) | `phpcs.xml` |
+| PHPStan | Level 2 | `phpstan.neon` |
+
+PHPStan runs with `--memory-limit=512M` due to large codebase. CI enforces PHPCS errors; PHPStan is advisory (`continue-on-error`).
 
 ## Rules
 
 - **Workflow directory**: `.mokogitea/` (not `.gitea/` or `.github/`)
-
 - **Never commit** `.claude/`, `.mcp.json`, `TODO.md`, or `*.min.css`/`*.min.js`
 - **Attribution**: use `Authored-by: Moko Consulting` in commits
 - **Branch strategy**: develop on `dev`, merge to `main` for release
 - **Minification**: handled at build time (CI) and runtime (MokoMinifyHelper for Joomla templates)
 - **Wiki**: documentation lives in the Gitea wiki, not in `docs/` files
-- **Standards**: this repo follows [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)
+- **New CLI tools**: extend `CliFramework`, not `CLIApp` (legacy)
+- **After adding a CLI tool**: register it in `bin/moko` COMMAND_MAP

README.md

@@ -6,11 +6,14 @@ DEFGROUP: MokoStandards.Root
 INGROUP: MokoStandards
 REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
 PATH: /README.md
+VERSION: 09.01.00
 BRIEF: Project overview and documentation
 -->
 
 # MokoStandards Enterprise API
 
+![Version](https://img.shields.io/badge/version-09.01.00-blue) ![PHP](https://img.shields.io/badge/PHP-8.1%2B-777BB4) ![License](https://img.shields.io/badge/license-GPL--3.0--or--later-green)
+
 PHP implementation of MokoStandards — enterprise standards, automation framework, workflow templates, and bulk sync tooling.
 
 > **Primary platform**: [Gitea — git.mokoconsulting.tech](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API)

automation/bulk_joomla_template.php

@@ -30,7 +30,7 @@ require_once __DIR__ . '/../lib/Enterprise/CliFramework.php';
 
 use MokoEnterprise\{
     AuditLogger,
-    CLIApp,
+    CliFramework,
     Config,
     GitPlatformAdapter,
     MetricsCollector,
@@ -47,31 +47,28 @@ use MokoEnterprise\{
  *
  * Works with both GitHub and Gitea via the PlatformAdapterFactory.
  */
-class BulkJoomlaTemplate extends CLIApp
+class BulkJoomlaTemplate extends CliFramework
 {
     public const DEFAULT_ORG = 'MokoConsulting';
     public const VERSION     = '04.06.10';
 
     private GitPlatformAdapter $adapter;
-    private AuditLogger $logger;
     private Config $config;
 
-    protected function setupArguments(): array
+    protected function configure(): void
     {
-        return [
-            'org:'       => 'Organization (default: ' . self::DEFAULT_ORG . ')',
-            'scaffold'   => 'Create a new Joomla template repository',
-            'sync'       => 'Sync MokoStandards files to existing template repos',
-            'list'       => 'List all joomla-template repositories',
-            'name:'      => 'Template name for --scaffold (e.g. MokoTheme)',
-            'client:'    => 'Joomla client: site (default) or administrator',
-            'repos:'     => 'Target repositories for --sync (comma-separated, or use --all)',
-            'all'           => 'Sync all repos tagged joomla-template',
-            'sync-updates'  => 'Sync updates.xml between Gitea and GitHub for Joomla repos',
-            'private'       => 'Create as private repository (--scaffold)',
-            'dry-run'       => 'Preview changes without making them',
-            'yes'           => 'Auto-confirm prompts',
-        ];
+        $this->setDescription('Bulk Joomla template management');
+        $this->addArgument('--org', 'Organization', self::DEFAULT_ORG);
+        $this->addArgument('--scaffold', 'Create new template repo', false);
+        $this->addArgument('--sync', 'Sync files to template repos', false);
+        $this->addArgument('--list', 'List template repos', false);
+        $this->addArgument('--name', 'Template name for scaffold', '');
+        $this->addArgument('--client', 'Joomla client: site or admin', 'site');
+        $this->addArgument('--repos', 'Target repos (comma-separated)', '');
+        $this->addArgument('--all', 'Sync all tagged repos', false);
+        $this->addArgument('--sync-updates', 'Sync updates.xml', false);
+        $this->addArgument('--private', 'Create as private repo', false);
+        $this->addArgument('--yes', 'Auto-confirm', false);
     }
 
     protected function run(): int
@@ -87,24 +84,23 @@ class BulkJoomlaTemplate extends CLIApp
             return 1;
         }
 
-        $this->logger = new AuditLogger('joomla_template');
-        $org = $this->getOption('org', self::DEFAULT_ORG);
+        $org = $this->getArgument('--org', self::DEFAULT_ORG);
         $platform = $this->adapter->getPlatformName();
         $this->log("Platform: {$platform} | Organization: {$org}", 'INFO');
 
-        if ($this->hasOption('list')) {
+        if ($this->getArgument('--list', false)) {
             return $this->listTemplateRepos($org);
         }
 
-        if ($this->hasOption('scaffold')) {
+        if ($this->getArgument('--scaffold', false)) {
             return $this->scaffoldTemplate($org);
         }
 
-        if ($this->hasOption('sync')) {
+        if ($this->getArgument('--sync', false)) {
             return $this->syncTemplates($org);
         }
 
-        if ($this->hasOption('sync-updates')) {
+        if ($this->getArgument('--sync-updates', false)) {
             return $this->syncUpdatesBetweenPlatforms($org);
         }
 
@@ -138,9 +134,9 @@ class BulkJoomlaTemplate extends CLIApp
 
     private function scaffoldTemplate(string $org): int
     {
-        $name   = $this->getOption('name', '');
-        $client = $this->getOption('client', 'site');
-        $dryRun = $this->hasOption('dry-run');
+        $name   = $this->getArgument('--name', '');
+        $client = $this->getArgument('--client', 'site');
+        $dryRun = $this->dryRun;
 
         if (empty($name)) {
             $this->log("❌ --name is required for --scaffold", 'ERROR');
@@ -176,7 +172,7 @@ class BulkJoomlaTemplate extends CLIApp
         }
 
         // Confirm
-        if (!$this->hasOption('yes')) {
+        if (!$this->getArgument('--yes', false)) {
             echo "\nCreate repository {$org}/{$name}? [y/N]: ";
             $handle = fopen('php://stdin', 'r');
             $line   = fgets($handle);
@@ -192,7 +188,7 @@ class BulkJoomlaTemplate extends CLIApp
         // Create repository
         $this->log("\nCreating repository...", 'INFO');
         try {
-            $isPrivate = $this->hasOption('private');
+            $isPrivate = $this->getArgument('--private', false);
             $this->adapter->createOrgRepo($org, $name, [
                 'description' => "Joomla {$client} template — {$name}",
                 'private'     => $isPrivate,
@@ -263,10 +259,10 @@ class BulkJoomlaTemplate extends CLIApp
     {
         $repos = [];
 
-        if ($this->hasOption('all')) {
+        if ($this->getArgument('--all', false)) {
             $repos = $this->findTemplateRepos($org);
         } else {
-            $reposArg = $this->getOption('repos', '');
+            $reposArg = $this->getArgument('--repos', '');
             if (empty($reposArg)) {
                 $this->log("❌ --repos or --all required for --sync", 'ERROR');
                 return 1;
@@ -284,7 +280,7 @@ class BulkJoomlaTemplate extends CLIApp
 
         $this->log("\nSyncing " . count($repos) . " template repo(s)...", 'INFO');
 
-        $dryRun  = $this->hasOption('dry-run');
+        $dryRun  = $this->dryRun;
         $success = 0;
         $failed  = 0;
 
@@ -741,7 +737,7 @@ class BulkJoomlaTemplate extends CLIApp
     {
         $repos = [];
 
-        if ($this->hasOption('all')) {
+        if ($this->getArgument('--all', false)) {
             $repos = $this->findTemplateRepos($org);
             // Also include waas-component repos
             $allRepos = $this->adapter->listOrgRepos($org, true);
@@ -765,7 +761,7 @@ class BulkJoomlaTemplate extends CLIApp
                 return true;
             });
         } else {
-            $reposArg = $this->getOption('repos', '');
+            $reposArg = $this->getArgument('--repos', '');
             if (empty($reposArg)) {
                 $this->log("❌ --repos or --all required for --sync-updates", 'ERROR');
                 return 1;
@@ -791,7 +787,7 @@ class BulkJoomlaTemplate extends CLIApp
 
         $gitea  = $adapters['gitea'];
         $github = $adapters['github'];
-        $dryRun = $this->hasOption('dry-run');
+        $dryRun = $this->dryRun;
 
         $this->log("\nSyncing updates.xml across Gitea <-> GitHub for " . count($repos) . " repo(s)...", 'INFO');
 
@@ -936,10 +932,6 @@ class BulkJoomlaTemplate extends CLIApp
 
 // Execute if run directly
 if (php_sapi_name() === 'cli' && isset($argv[0]) && realpath($argv[0]) === __FILE__) {
-    $app = new BulkJoomlaTemplate(
-        'joomla-template',
-        'Bulk scaffold and sync Joomla template repositories',
-        BulkJoomlaTemplate::VERSION
-    );
+    $app = new BulkJoomlaTemplate();
     exit($app->execute());
 }

automation/bulk_sync.php

@@ -26,7 +26,7 @@ use MokoEnterprise\{
     AuditLogger,
     CheckpointManager,
     CircuitBreakerOpen,
-    CLIApp,
+    CliFramework,
     Config,
     GitPlatformAdapter,
     MetricsCollector,
@@ -45,7 +45,7 @@ use MokoEnterprise\{
  * Synchronizes MokoStandards files across multiple repositories using
  * the Enterprise library for robust, audited operations.
  */
-class BulkSync extends CLIApp
+class BulkSync extends CliFramework
 {
     /**
      * Default organization for bulk sync operations
@@ -65,9 +65,7 @@ class BulkSync extends CLIApp
     private RepositorySynchronizer $synchronizer;
     private AuditLogger $logger;
     private CheckpointManager $checkpoints;
-    private SecurityValidator $security;
-    private PluginFactory $pluginFactory;
-    private ProjectTypeDetector $typeDetector;
+    private MetricsCollector $metrics;
     private Config $config;
 
     /** Set to true by signal handler or rate-limit detection to abort the sync loop gracefully. */
@@ -76,21 +74,20 @@ class BulkSync extends CLIApp
     /**
      * Setup command-line arguments
      */
-    protected function setupArguments(): array
+    protected function configure(): void
     {
-        return [
-            'org:' => 'GitHub organization (default: MokoConsulting)',
-            'repos:' => 'Specific repositories to sync (space-separated)',
-            'exclude:' => 'Repositories to exclude (space-separated)',
-            'skip-archived' => 'Skip archived repositories',
-            'yes' => 'Auto-confirm prompts',
-            'resume' => 'Resume from last checkpoint, skipping already-processed repositories',
-            'force'    => 'Force overwrite of protected files (always_overwrite=false), except truly protected files',
-            'protect'  => 'Apply/enforce main branch protection rules on all synced repositories',
-            'no-issue' => 'Skip creating a tracking issue in each target repository',
-            'update-branches' => 'After sync, merge main into all other open PR branches in each repo',
-            'health' => 'Run repo health checks after sync and include results in the report',
-        ];
+        $this->setDescription('Bulk repository synchronization');
+        $this->addArgument('--org', 'Organization', self::DEFAULT_ORG);
+        $this->addArgument('--repos', 'Specific repos', '');
+        $this->addArgument('--exclude', 'Repos to exclude', '');
+        $this->addArgument('--skip-archived', 'Skip archived repos', false);
+        $this->addArgument('--yes', 'Auto-confirm', false);
+        $this->addArgument('--resume', 'Resume from checkpoint', false);
+        $this->addArgument('--force', 'Force overwrite', false);
+        $this->addArgument('--protect', 'Apply branch protection', false);
+        $this->addArgument('--no-issue', 'Skip tracking issue', false);
+        $this->addArgument('--update-branches', 'Merge main into branches', false);
+        $this->addArgument('--health', 'Run health checks', false);
     }
 
     /**
@@ -106,13 +103,13 @@ class BulkSync extends CLIApp
         }
 
         // Get configuration
-        $org = $this->getOption('org', self::DEFAULT_ORG);
-        $skipArchived = $this->hasOption('skip-archived');
-        $autoConfirm = $this->hasOption('yes');
+        $org = $this->getArgument('--org', self::DEFAULT_ORG);
+        $skipArchived = $this->getArgument('--skip-archived', false);
+        $autoConfirm = $this->getArgument('--yes', false);
 
         // Get repository filters
-        $specificRepos = $this->parseRepositoryList($this->getOption('repos', ''));
-        $excludeRepos = $this->parseRepositoryList($this->getOption('exclude', ''));
+        $specificRepos = $this->parseRepositoryList($this->getArgument('--repos', ''));
+        $excludeRepos = $this->parseRepositoryList($this->getArgument('--exclude', ''));
 
         $this->log("Organization: {$org}", 'INFO');
         if (!empty($specificRepos)) {
@@ -139,7 +136,7 @@ class BulkSync extends CLIApp
 
         // Load resume checkpoint if --resume is set
         $alreadyProcessed = [];
-        if ($this->hasOption('resume')) {
+        if ($this->getArgument('--resume', false)) {
             $checkpoint = $this->checkpoints->loadCheckpoint('bulk_sync');
             if ($checkpoint !== null) {
                 $alreadyProcessed = array_keys($checkpoint['results']['repositories'] ?? []);
@@ -159,6 +156,11 @@ class BulkSync extends CLIApp
             return 0;
         }
 
+        // Sync universal workflows from Template-Generic → other templates first
+        $this->log("📋 Syncing universal workflows to template repos...", 'INFO');
+        $templateUpdates = $this->synchronizer->syncUniversalWorkflowsToTemplates($org);
+        $this->log("Template sync: {$templateUpdates} file(s) updated", 'INFO');
+
         // Execute synchronization
         $this->log("🔄 Starting synchronization...", 'INFO');
         $results = $this->executeSynchronization($org, $repositories, $alreadyProcessed);
@@ -204,7 +206,6 @@ class BulkSync extends CLIApp
             $this->logger      = new AuditLogger('bulk_sync');
             $this->metrics     = new MetricsCollector();
             $this->checkpoints = new CheckpointManager('.checkpoints');
-            $this->security    = new SecurityValidator();
             $this->synchronizer = new RepositorySynchronizer(
                 $this->api,
                 $this->logger,
@@ -215,8 +216,6 @@ class BulkSync extends CLIApp
             );
 
             // Initialize plugin system
-            $this->pluginFactory = new PluginFactory($this->logger, $this->metrics);
-            $this->typeDetector = new ProjectTypeDetector($this->logger);
 
             $this->log("✓ Enterprise components initialized for platform: {$platform}", 'INFO');
             return true;
@@ -288,7 +287,7 @@ class BulkSync extends CLIApp
             }
         }
 
-        return array_values(array_merge($priority, $rest));
+        return array_merge($priority, $rest);
     }
 
     /**
@@ -1424,10 +1423,6 @@ class BulkSync extends CLIApp
 
 // Execute if run directly
 if (php_sapi_name() === 'cli' && isset($argv[0]) && realpath($argv[0]) === __FILE__) {
-    $app = new BulkSync(
-        'bulk-sync',
-        'Enterprise-grade bulk repository synchronization',
-        BulkSync::VERSION
-    );
+    $app = new BulkSync();
     exit($app->execute());
 }

automation/push_files.php

@@ -24,7 +24,7 @@ require_once __DIR__ . '/../lib/Enterprise/CliFramework.php';
 use MokoEnterprise\{
     ApiClient,
     AuditLogger,
-    CLIApp,
+    CliFramework,
     Config,
     DefinitionParser,
     GitPlatformAdapter,
@@ -51,7 +51,7 @@ use MokoEnterprise\{
  *   php push_files.php --files=".github/workflows/ci.yml,.github/workflows/codeql-analysis.yml" --repos=MokoCRM,WaasComponent
  *   php push_files.php --files=templates/foo.txt:docs/foo.txt --repos=MyRepo --direct
  */
-class PushFiles extends CLIApp
+class PushFiles extends CliFramework
 {
     public const DEFAULT_ORG = 'MokoConsulting';
     public const VERSION = '04.06.00';
@@ -65,18 +65,17 @@ class PushFiles extends CLIApp
     /**
      * Setup command-line arguments
      */
-    protected function setupArguments(): array
+    protected function configure(): void
     {
-        return [
-            'org:'     => 'GitHub organization (default: ' . self::DEFAULT_ORG . ')',
-            'repos:'   => 'Target repositories — comma or space-separated (required)',
-            'files:'   => 'Files to push — destination paths or source:destination pairs, comma/space-separated (required)',
-            'message:' => 'Custom commit message (optional)',
-            'branch:'  => 'Target branch for direct pushes (default: repo default branch). Ignored unless --direct is set',
-            'direct'   => 'Push directly to target branch instead of creating a PR',
-            'yes'      => 'Auto-confirm without prompting',
-            'no-issue' => 'Skip creating a tracking issue in each target repository',
-        ];
+        $this->setDescription('Push files to remote repositories');
+        $this->addArgument('--org', 'GitHub organization', self::DEFAULT_ORG);
+        $this->addArgument('--repos', 'Target repos (comma-separated)', '');
+        $this->addArgument('--files', 'Files to push (comma-separated)', '');
+        $this->addArgument('--message', 'Custom commit message', '');
+        $this->addArgument('--branch', 'Target branch for direct pushes', '');
+        $this->addArgument('--direct', 'Push directly instead of PR', false);
+        $this->addArgument('--yes', 'Auto-confirm without prompting', false);
+        $this->addArgument('--no-issue', 'Skip creating tracking issue', false);
     }
 
     /**
@@ -90,11 +89,11 @@ class PushFiles extends CLIApp
             return 1;
         }
 
-        $org       = $this->getOption('org', self::DEFAULT_ORG);
-        $reposArg  = $this->getOption('repos', '');
-        $filesArg  = $this->getOption('files', '');
-        $direct    = $this->hasOption('direct');
-        $autoYes   = $this->hasOption('yes');
+        $org       = $this->getArgument('--org', self::DEFAULT_ORG);
+        $reposArg  = $this->getArgument('--repos', '');
+        $filesArg  = $this->getArgument('--files', '');
+        $direct    = $this->getArgument('--direct', false);
+        $autoYes   = $this->getArgument('--yes', false);
 
         // Validate required arguments
         if (empty($reposArg)) {
@@ -127,7 +126,7 @@ class PushFiles extends CLIApp
         }
 
         // Confirm before proceeding
-        if (!$autoYes && !$this->confirm($repoFileMaps, $direct)) {
+        if (!$autoYes && !$this->confirmPush($repoFileMaps, $direct)) {
             $this->log('❌ Cancelled.', 'INFO');
             return 0;
         }
@@ -265,7 +264,8 @@ class PushFiles extends CLIApp
         // Fall back to live detection
         try {
             $repoData = $this->api->get("/repos/{$org}/{$repo}");
-            return $this->typeDetector->detect($repoData, $org, $repo);
+            $result = $this->typeDetector->detect('.');
+            return $result['type'] ?? 'default';
         } catch (\Exception $e) {
             $this->log("  ⚠️  Could not detect platform for {$repo}, using 'default'", 'WARN');
             return 'default';
@@ -277,7 +277,7 @@ class PushFiles extends CLIApp
      *
      * @param array<string, list<array{source: string, destination: string}>> $repoFileMaps
      */
-    private function confirm(array $repoFileMaps, bool $direct): bool
+    private function confirmPush(array $repoFileMaps, bool $direct): bool
     {
         if ($this->quiet) {
             return true;
@@ -322,8 +322,8 @@ class PushFiles extends CLIApp
             'repos'   => [],
         ];
 
-        $customMessage = $this->getOption('message', '');
-        $targetBranch  = $this->getOption('branch', '');
+        $customMessage = $this->getArgument('--message', '');
+        $targetBranch  = $this->getArgument('--branch', '');
 
         foreach ($repoFileMaps as $repo => $entries) {
             $this->log("\n[{$repo}] Pushing " . count($entries) . ' file(s)...', 'INFO');
@@ -520,6 +520,7 @@ class PushFiles extends CLIApp
                 'direction' => 'desc',
             ]);
 
+            $existing = array_values($existing);
             if (!empty($existing) && isset($existing[0]['number'])) {
                 $num   = $existing[0]['number'];
                 $patch = ['title' => $title, 'body' => $body, 'assignees' => ['jmiller']];
@@ -581,7 +582,7 @@ class PushFiles extends CLIApp
         ));
 
         $repoList = implode("\n", array_map(fn($r) => "- `{$r}`", $failedRepos));
-        $fileArgs = $this->getOption('files', '');
+        $fileArgs = $this->getArgument('--files', '');
 
         $title = "fix: push_files failed for {$failed} repo(s) — action required";
 
@@ -622,6 +623,7 @@ class PushFiles extends CLIApp
                 'direction' => 'desc',
             ]);
 
+            $existing = array_values($existing);
             if (!empty($existing) && isset($existing[0]['number'])) {
                 $num   = $existing[0]['number'];
                 $patch = ['title' => $title, 'body' => $body, 'assignees' => ['jmiller']];
@@ -693,10 +695,6 @@ class PushFiles extends CLIApp
 
 // Execute if run directly
 if (php_sapi_name() === 'cli' && isset($argv[0]) && realpath($argv[0]) === __FILE__) {
-    $app = new PushFiles(
-        'push-files',
-        'Push one or more specific files to one or more remote repositories',
-        PushFiles::VERSION
-    );
+    $app = new PushFiles();
     exit($app->execute());
 }

automation/repo_cleanup.php

@@ -21,7 +21,7 @@ declare(strict_types=1);
 require_once __DIR__ . '/../vendor/autoload.php';
 require_once __DIR__ . '/../lib/Enterprise/CliFramework.php';
 
-use MokoEnterprise\{ApiClient, AuditLogger, CLIApp, Config, GitPlatformAdapter, MetricsCollector, PlatformAdapterFactory};
+use MokoEnterprise\{ApiClient, AuditLogger, CliFramework, Config, GitPlatformAdapter, MetricsCollector, PlatformAdapterFactory};
 
 /**
  * Enterprise Repository Cleanup
@@ -36,7 +36,7 @@ use MokoEnterprise\{ApiClient, AuditLogger, CLIApp, Config, GitPlatformAdapter,
  *   7. Verify and provision standard labels
  *   8. Version drift detection
  */
-class RepoCleanup extends CLIApp
+class RepoCleanup extends CliFramework
 {
     private const VERSION        = '04.06.00';
     private const SYNC_PREFIX    = 'chore/sync-mokostandards-';
@@ -58,42 +58,34 @@ class RepoCleanup extends CLIApp
 
     private ApiClient $api;
     private GitPlatformAdapter $adapter;
-    private AuditLogger $logger;
-    private MetricsCollector $metrics;
-    private bool $dryRun = false;
+    protected bool $dryRun = false;
     private float $startTime;
 
     protected function configure(): void
     {
-        $this->setName('repo-cleanup');
-        $this->setDescription('Enterprise repository cleanup — branches, PRs, issues, workflows, labels, logs');
-        $this->setVersion(self::VERSION);
-
-        $this->addOption('org', 'GitHub organization', 'MokoConsulting');
-        $this->addOption('repos', 'Specific repositories (space-separated)', '');
-        $this->addOption('skip-archived', 'Skip archived repositories', false);
-        $this->addOption('close-issues', 'Close resolved tracking issues (merged PR = done)', false);
-        $this->addOption('lock-old-issues', 'Lock issues closed >30 days', false);
-        $this->addOption('clean-workflows', 'Delete cancelled/stale workflow runs', false);
-        $this->addOption('clean-logs', 'Delete workflow run logs older than --log-days', false);
-        $this->addOption('log-days', 'Days to keep logs (default: 30)', '30');
-        $this->addOption('delete-retired', 'Delete retired workflow files from repos', false);
-        $this->addOption('check-labels', 'Verify mokostandards label exists', false);
-        $this->addOption('check-drift', 'Check for version drift against README.md', false);
-        $this->addOption('all', 'Run all cleanup operations', false);
-        $this->addOption('yes', 'Auto-confirm prompts', false);
-        $this->addOption('dry-run', 'Preview changes without making them', false);
-        $this->addOption('verbose', 'Show detailed output', false);
-        $this->addOption('quiet', 'Suppress non-error output', false);
-        $this->addOption('json', 'Output results as JSON', false);
+        $this->setDescription('Enterprise repository cleanup');
+        $this->addArgument('--org', 'GitHub organization', 'MokoConsulting');
+        $this->addArgument('--repos', 'Specific repos (space-separated)', '');
+        $this->addArgument('--skip-archived', 'Skip archived repos', false);
+        $this->addArgument('--close-issues', 'Close resolved tracking issues', false);
+        $this->addArgument('--lock-old-issues', 'Lock issues closed >30 days', false);
+        $this->addArgument('--clean-workflows', 'Delete stale workflow runs', false);
+        $this->addArgument('--clean-logs', 'Delete old workflow logs', false);
+        $this->addArgument('--log-days', 'Days to keep logs', '30');
+        $this->addArgument('--delete-retired', 'Delete retired workflows', false);
+        $this->addArgument('--check-labels', 'Verify labels exist', false);
+        $this->addArgument('--check-drift', 'Check version drift', false);
+        $this->addArgument('--all', 'Run all operations', false);
+        $this->addArgument('--yes', 'Auto-confirm', false);
+        $this->addArgument('--json', 'Output as JSON', false);
     }
 
-    protected function execute(): int
+    protected function run(): int
     {
         $this->startTime = microtime(true);
-        $org = $this->getOption('org', 'MokoConsulting');
-        $this->dryRun = (bool) $this->getOption('dry-run', false);
-        $runAll = (bool) $this->getOption('all', false);
+        $org = $this->getArgument('--org', 'MokoConsulting');
+        $this->dryRun = (bool) $this->getArgument('--dry-run', false);
+        $runAll = (bool) $this->getArgument('--all', false);
 
         $config = Config::load();
 
@@ -101,24 +93,22 @@ class RepoCleanup extends CLIApp
             $this->adapter = PlatformAdapterFactory::create($config);
             $this->api     = $this->adapter->getApiClient();
         } catch (\Exception $e) {
-            $this->error('Failed to initialize platform adapter: ' . $e->getMessage());
+            $this->errorMsg('Failed to initialize platform adapter: ' . $e->getMessage());
             return 1;
         }
 
-        $this->logger  = new AuditLogger('repo_cleanup');
-        $this->metrics = new MetricsCollector('repo_cleanup');
 
-        $this->log("🧹 MokoStandards Repository Cleanup v" . self::VERSION);
-        $this->log("Organization: {$org}");
-        $this->log("Current sync branch: " . self::CURRENT_BRANCH);
+        $this->logMsg("🧹 MokoStandards Repository Cleanup v" . self::VERSION);
+        $this->logMsg("Organization: {$org}");
+        $this->logMsg("Current sync branch: " . self::CURRENT_BRANCH);
         if ($this->dryRun) {
-            $this->log("⚠️  DRY RUN — no changes will be made");
+            $this->logMsg("⚠️  DRY RUN — no changes will be made");
         }
-        $this->log('');
+        $this->logMsg('');
 
         $repos = $this->fetchRepositories($org);
-        $this->log("Found " . count($repos) . " repositories");
-        $this->log('');
+        $this->logMsg("Found " . count($repos) . " repositories");
+        $this->logMsg('');
 
         $results = [
             'repos_processed'    => 0,
@@ -140,7 +130,7 @@ class RepoCleanup extends CLIApp
             $name = $repo['name'];
             $num  = $i + 1;
             $total = count($repos);
-            $this->log("[{$num}/{$total}] {$name}");
+            $this->logMsg("[{$num}/{$total}] {$name}");
             $results['repos_processed']++;
 
             try {
@@ -151,37 +141,37 @@ class RepoCleanup extends CLIApp
                 $cleaned = $this->cleanBranches($org, $name, $results) || $cleaned;
 
                 // Optional: close resolved issues
-                if ($runAll || $this->getOption('close-issues', false)) {
+                if ($runAll || $this->getArgument('--close-issues', false)) {
                     $cleaned = $this->closeResolvedIssues($org, $name, $results) || $cleaned;
                 }
 
                 // Optional: lock old closed issues
-                if ($runAll || $this->getOption('lock-old-issues', false)) {
+                if ($runAll || $this->getArgument('--lock-old-issues', false)) {
                     $cleaned = $this->lockOldIssues($org, $name, $results) || $cleaned;
                 }
 
                 // Optional: delete retired workflow files
-                if ($runAll || $this->getOption('delete-retired', false)) {
+                if ($runAll || $this->getArgument('--delete-retired', false)) {
                     $cleaned = $this->deleteRetiredWorkflows($org, $name, $results) || $cleaned;
                 }
 
                 // Optional: clean workflow runs
-                if ($runAll || $this->getOption('clean-workflows', false)) {
+                if ($runAll || $this->getArgument('--clean-workflows', false)) {
                     $cleaned = $this->cleanWorkflowRuns($org, $name, $results) || $cleaned;
                 }
 
                 // Optional: clean old logs
-                if ($runAll || $this->getOption('clean-logs', false)) {
+                if ($runAll || $this->getArgument('--clean-logs', false)) {
                     $cleaned = $this->cleanOldLogs($org, $name, $results) || $cleaned;
                 }
 
                 // Optional: check labels
-                if ($runAll || $this->getOption('check-labels', false)) {
+                if ($runAll || $this->getArgument('--check-labels', false)) {
                     $this->checkLabels($org, $name, $results);
                 }
 
                 // Optional: check version drift
-                if ($runAll || $this->getOption('check-drift', false)) {
+                if ($runAll || $this->getArgument('--check-drift', false)) {
                     $this->checkVersionDrift($org, $name, $results);
                 }
 
@@ -189,32 +179,32 @@ class RepoCleanup extends CLIApp
                     $results['repos_cleaned']++;
                 }
             } catch (\Exception $e) {
-                $this->error("  ✗ {$name}: " . $e->getMessage());
+                $this->errorMsg("  ✗ {$name}: " . $e->getMessage());
                 $results['errors']++;
             }
         }
 
         $duration = round(microtime(true) - $this->startTime, 1);
 
-        $this->log('');
-        $this->log('============================================================');
-        $this->log("🧹 Cleanup Complete ({$duration}s)");
-        $this->log('============================================================');
-        $this->log("Repos processed:     {$results['repos_processed']}");
-        $this->log("Repos with changes:  {$results['repos_cleaned']}");
-        $this->log("Branches deleted:    {$results['branches_deleted']}");
-        $this->log("PRs closed:          {$results['prs_closed']}");
-        $this->log("Issues closed:       {$results['issues_closed']}");
-        $this->log("Issues locked:       {$results['issues_locked']}");
-        $this->log("Retired files:       {$results['retired_files']}");
-        $this->log("Workflow runs:       {$results['runs_deleted']}");
-        $this->log("Logs cleaned:        {$results['logs_deleted']}");
-        $this->log("Labels missing:      {$results['labels_missing']}");
-        $this->log("Version drift:       {$results['version_drift']}");
-        $this->log("Errors:              {$results['errors']}");
-        $this->log('============================================================');
+        $this->logMsg('');
+        $this->logMsg('============================================================');
+        $this->logMsg("🧹 Cleanup Complete ({$duration}s)");
+        $this->logMsg('============================================================');
+        $this->logMsg("Repos processed:     {$results['repos_processed']}");
+        $this->logMsg("Repos with changes:  {$results['repos_cleaned']}");
+        $this->logMsg("Branches deleted:    {$results['branches_deleted']}");
+        $this->logMsg("PRs closed:          {$results['prs_closed']}");
+        $this->logMsg("Issues closed:       {$results['issues_closed']}");
+        $this->logMsg("Issues locked:       {$results['issues_locked']}");
+        $this->logMsg("Retired files:       {$results['retired_files']}");
+        $this->logMsg("Workflow runs:       {$results['runs_deleted']}");
+        $this->logMsg("Logs cleaned:        {$results['logs_deleted']}");
+        $this->logMsg("Labels missing:      {$results['labels_missing']}");
+        $this->logMsg("Version drift:       {$results['version_drift']}");
+        $this->logMsg("Errors:              {$results['errors']}");
+        $this->logMsg('============================================================');
 
-        if ($this->getOption('json', false)) {
+        if ($this->getArgument('--json', false)) {
             $results['duration_seconds'] = $duration;
             echo json_encode($results, JSON_PRETTY_PRINT) . "\n";
         }
@@ -226,8 +216,8 @@ class RepoCleanup extends CLIApp
 
     private function fetchRepositories(string $org): array
     {
-        $specificRepos = trim((string) $this->getOption('repos', ''));
-        $skipArchived  = (bool) $this->getOption('skip-archived', false);
+        $specificRepos = trim((string) $this->getArgument('--repos', ''));
+        $skipArchived  = (bool) $this->getArgument('--skip-archived', false);
 
         if (!empty($specificRepos)) {
             $names = preg_split('/[\s,]+/', $specificRepos);
@@ -264,7 +254,7 @@ class RepoCleanup extends CLIApp
                     if (($pr['number'] ?? 0) > 0 && !$this->dryRun) {
                         $this->api->patch("/repos/{$org}/{$repo}/pulls/{$pr['number']}", ['state' => 'closed']);
                     }
-                    $this->log("  🔒 Closed PR #{$pr['number']} ({$name})");
+                    $this->logMsg("  🔒 Closed PR #{$pr['number']} ({$name})");
                     $results['prs_closed']++;
                     $changed = true;
                 }
@@ -279,7 +269,7 @@ class RepoCleanup extends CLIApp
                     continue;
                 }
             }
-            $this->log("  🗑️  Deleted branch: {$name}");
+            $this->logMsg("  🗑️  Deleted branch: {$name}");
             $results['branches_deleted']++;
             $changed = true;
         }
@@ -312,7 +302,7 @@ class RepoCleanup extends CLIApp
                                     'state' => 'closed', 'state_reason' => 'completed',
                                 ]);
                             }
-                            $this->log("  ✅ Closed issue #{$num} (PR #{$prNum} merged)");
+                            $this->logMsg("  ✅ Closed issue #{$num} (PR #{$prNum} merged)");
                             $results['issues_closed']++;
                             $changed = true;
                         }
@@ -361,7 +351,7 @@ class RepoCleanup extends CLIApp
         }
 
         if ($results['issues_locked'] > 0) {
-            $this->log("  🔒 Locked {$results['issues_locked']} old closed issue(s)");
+            $this->logMsg("  🔒 Locked {$results['issues_locked']} old closed issue(s)");
         }
         return $changed;
     }
@@ -396,7 +386,7 @@ class RepoCleanup extends CLIApp
                             'branch'  => $defaultBranch,
                         ]);
                     }
-                    $this->log("  Deleted retired: {$wf} (from {$wfDir})");
+                    $this->logMsg("  Deleted retired: {$wf} (from {$wfDir})");
                     $results['retired_files']++;
                     $changed = true;
                 } catch (\Exception $e) {
@@ -433,7 +423,7 @@ class RepoCleanup extends CLIApp
             }
         }
         if ($results['runs_deleted'] > 0) {
-            $this->log("  🔄 Cleaned {$results['runs_deleted']} workflow run(s)");
+            $this->logMsg("  🔄 Cleaned {$results['runs_deleted']} workflow run(s)");
         }
         return $changed;
     }
@@ -441,7 +431,7 @@ class RepoCleanup extends CLIApp
     private function cleanOldLogs(string $org, string $repo, array &$results): bool
     {
         $changed = false;
-        $days = (int) $this->getOption('log-days', '30');
+        $days = (int) $this->getArgument('--log-days', '30');
         $cutoff = date('Y-m-d\TH:i:s\Z', strtotime("-{$days} days"));
 
         try {
@@ -465,7 +455,7 @@ class RepoCleanup extends CLIApp
         }
 
         if ($results['logs_deleted'] > 0) {
-            $this->log("  📋 Cleaned {$results['logs_deleted']} old log(s)");
+            $this->logMsg("  📋 Cleaned {$results['logs_deleted']} old log(s)");
         }
         return $changed;
     }
@@ -475,7 +465,7 @@ class RepoCleanup extends CLIApp
         try {
             $this->api->get("/repos/{$org}/{$repo}/labels/mokostandards");
         } catch (\Exception $e) {
-            $this->log("  ⚠️  Missing 'mokostandards' label");
+            $this->logMsg("  ⚠️  Missing 'mokostandards' label");
             $results['labels_missing']++;
             $this->api->resetCircuitBreaker();
         }
@@ -495,7 +485,7 @@ class RepoCleanup extends CLIApp
                     $mokoContent = base64_decode($mokoFile['content'] ?? '');
                     if (preg_match('/standards_version:\s*(\d{2}\.\d{2}\.\d{2})/m', $mokoContent, $vm)) {
                         if ($vm[1] !== self::VERSION) {
-                            $this->log("  ⚠️  Standards drift: {$vm[1]} (expected " . self::VERSION . ")");
+                            $this->logMsg("  ⚠️  Standards drift: {$vm[1]} (expected " . self::VERSION . ")");
                             $results['version_drift']++;
                         }
                     }
@@ -510,14 +500,14 @@ class RepoCleanup extends CLIApp
 
     // ─── Helpers ─────────────────────────────────────────────────────────
 
-    private function log(string $message): void
+    private function logMsg(string $message): void
     {
-        if (!$this->getOption('quiet', false)) {
+        if (!$this->quiet) {
             echo $message . "\n";
         }
     }
 
-    private function error(string $message): void
+    private function errorMsg(string $message): void
     {
         fwrite(STDERR, $message . "\n");
     }

bin/moko

@@ -1,5 +1,6 @@
 #!/usr/bin/env php
 <?php
+
 /**
  * Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
  *
@@ -88,45 +89,83 @@ require_once $autoloader;
  */
 const COMMAND_MAP = [
     // Automation
-    'sync'             => 'api/automation/bulk_sync.php',
+    'sync'             => 'automation/bulk_sync.php',
 
     // Maintenance
-    'inventory'        => 'api/maintenance/update_repo_inventory.php',
+    'inventory'        => 'maintenance/update_repo_inventory.php',
 
     // Validation — general
-    'health'           => 'api/validate/check_repo_health.php',
-    'check:syntax'     => 'api/validate/check_php_syntax.php',
-    'check:version'    => 'api/validate/check_version_consistency.php',
-    'check:changelog'  => 'api/validate/check_changelog.php',
-    'check:structure'  => 'api/validate/check_structure.php',
-    'check:headers'    => 'api/validate/check_license_headers.php',
-    'check:secrets'    => 'api/validate/check_no_secrets.php',
-    'check:tabs'       => 'api/validate/check_tabs.php',
-    'check:paths'      => 'api/validate/check_paths.php',
-    'check:xml'        => 'api/validate/check_xml_wellformed.php',
-    'check:enterprise' => 'api/validate/check_enterprise_readiness.php',
+    'health'           => 'validate/check_repo_health.php',
+    'check:syntax'     => 'validate/check_php_syntax.php',
+    'check:version'    => 'validate/check_version_consistency.php',
+    'check:changelog'  => 'validate/check_changelog.php',
+    'check:structure'  => 'validate/check_structure.php',
+    'check:headers'    => 'validate/check_license_headers.php',
+    'check:secrets'    => 'validate/check_no_secrets.php',
+    'check:tabs'       => 'validate/check_tabs.php',
+    'check:paths'      => 'validate/check_paths.php',
+    'check:xml'        => 'validate/check_xml_wellformed.php',
+    'check:enterprise' => 'validate/check_enterprise_readiness.php',
 
     // Validation — platform-specific
-    'check:dolibarr'   => 'api/validate/check_dolibarr_module.php',
-    'check:joomla'     => 'api/validate/check_joomla_manifest.php',
-    'check:language'   => 'api/validate/check_language_structure.php',
+    'check:dolibarr'   => 'validate/check_dolibarr_module.php',
+    'check:joomla'     => 'validate/check_joomla_manifest.php',
+    'check:language'   => 'validate/check_language_structure.php',
+    'check:client'     => 'validate/check_client_theme.php',
+    'check:wiki'       => 'validate/check_wiki_health.php',
 
     // Detection
-    'detect'           => 'api/validate/auto_detect_platform.php',
+    'detect'           => 'validate/auto_detect_platform.php',
 
     // Org-wide
-    'drift'            => 'api/validate/scan_drift.php',
+    'drift'            => 'validate/scan_drift.php',
 
     // Release
-    'release'              => 'api/cli/release.php',
+    'release'              => 'cli/release.php',
+    'release:notes'        => 'cli/release_notes.php',
+    'release:validate'     => 'cli/release_validate.php',
+    'manifest:element'     => 'cli/manifest_element.php',
+    'release:cascade'      => 'cli/release_cascade.php',
+    'release:promote'      => 'cli/release_promote.php',
+    'release:create'       => 'cli/release_create.php',
+    'release:manage'       => 'cli/release_manage.php',
+    'release:mirror'       => 'cli/release_mirror.php',
+    'release:package'      => 'cli/release_package.php',
 
-    // CLI utilities (used by workflows — centralized logic)
-    'version:read'         => 'api/cli/version_read.php',
-    'version:bump'         => 'api/cli/version_bump.php',
-    'version:propagate'    => 'api/maintenance/update_version_from_readme.php',
-    'version:set-platform' => 'api/cli/version_set_platform.php',
-    'platform:detect'      => 'api/cli/platform_detect.php',
-    'release:notes'        => 'api/cli/release_notes.php',
+    // Version management
+    'version:read'         => 'cli/version_read.php',
+    'version:bump'         => 'cli/version_bump.php',
+    'version:check'        => 'cli/version_check.php',
+    'version:propagate'    => 'maintenance/update_version_from_readme.php',
+    'version:set-platform' => 'cli/version_set_platform.php',
+    'version:reset-dev'    => 'cli/version_reset_dev.php',
+
+    // Build & package
+    'build:package'        => 'cli/package_build.php',
+    'build:joomla'         => 'cli/joomla_build.php',
+    'build:updates-xml'    => 'cli/updates_xml_build.php',
+
+    // Platform detection
+    'platform:detect'      => 'cli/platform_detect.php',
+    'manifest:read'        => 'cli/manifest_read.php',
+
+    // Repository management
+    'repo:create'          => 'cli/create_repo.php',
+    'repo:archive'         => 'cli/archive_repo.php',
+    'repo:scaffold-client' => 'cli/scaffold_client.php',
+    'repo:provision'       => 'cli/client_provision.php',
+
+    // Bulk operations
+    'bulk:push-workflow'   => 'cli/bulk_workflow_push.php',
+    'bulk:trigger'         => 'cli/bulk_workflow_trigger.php',
+    'bulk:sync-rulesets'   => 'cli/sync_rulesets.php',
+
+    // Monitoring & dashboards
+    'dashboard'            => 'cli/client_dashboard.php',
+    'grafana'              => 'cli/grafana_dashboard.php',
+    'client:inventory'     => 'cli/client_inventory.php',
+
+    // Module validation
     'validate:module'      => 'bin/validate-module',
 ];
 
@@ -210,24 +249,112 @@ function printCommandList(): void
 {
     echo "Available commands:\n\n";
 
-    $groups = [
-        'Automation'          => ['sync'],
-        'Maintenance'         => ['inventory'],
-        'Validation (general)' => ['health', 'check:syntax', 'check:version', 'check:changelog',
-                                   'check:structure', 'check:headers', 'check:secrets',
-                                   'check:tabs', 'check:paths', 'check:xml', 'check:enterprise'],
-        'Validation (platform)' => ['check:dolibarr', 'check:joomla', 'check:language', 'detect'],
-        'Organisation-wide'   => ['drift'],
-    ];
+    // Auto-group by command prefix or comment-based sections
+    $groups = [];
+    foreach (COMMAND_MAP as $cmd => $path) {
+        if (str_contains($cmd, ':')) {
+            $prefix = explode(':', $cmd)[0];
+            $groupName = match ($prefix) {
+                'check' => 'Validation',
+                'version' => 'Version',
+                'release' => 'Release',
+                'build' => 'Build',
+                'platform', 'manifest' => 'Platform',
+                'repo' => 'Repository',
+                'bulk' => 'Bulk Operations',
+                'client' => 'Client Management',
+                'validate' => 'Module Validation',
+                default => ucfirst($prefix),
+            };
+        } else {
+            $groupName = match ($cmd) {
+                'sync' => 'Automation',
+                'inventory' => 'Maintenance',
+                'health' => 'Validation',
+                'detect', 'drift' => 'Validation',
+                'dashboard', 'grafana' => 'Monitoring',
+                default => 'Other',
+            };
+        }
+        $groups[$groupName][$cmd] = $path;
+    }
+
+    // Load plugin commands
+    $pluginCommands = loadPluginCommands();
+    if (!empty($pluginCommands)) {
+        foreach ($pluginCommands as $cmd => $info) {
+            $type = $info['plugin'] ?? 'Plugin';
+            $groups["Plugin: {$type}"][$cmd] = $info['description'] ?? '';
+        }
+    }
+
+    ksort($groups);
 
     foreach ($groups as $group => $commands) {
-        echo "  {$group}:\n";
-        foreach ($commands as $cmd) {
-            printf("    %-22s %s\n", $cmd, COMMAND_MAP[$cmd]);
+        echo "  \033[1m{$group}\033[0m\n";
+        ksort($commands);
+        foreach ($commands as $cmd => $path) {
+            printf("    \033[36m%-26s\033[0m %s\n", $cmd, basename($path));
         }
         echo "\n";
     }
 
-    echo "Run: php bin/moko <command> --help   for command-specific options.\n";
-    echo "All platforms: php bin/moko <command>\n";
+    $total = count(COMMAND_MAP) + count($pluginCommands);
+    echo "{$total} command(s) available.\n";
+    echo "Run: php bin/moko <command> --help\n";
+}
+
+/**
+ * Load commands from registered plugins.
+ *
+ * @return array<string, array{plugin: string, description: string, script: string}>
+ */
+function loadPluginCommands(): array
+{
+    $pluginDir = dirname(__DIR__) . '/lib/Enterprise/Plugins';
+    if (!is_dir($pluginDir)) {
+        return [];
+    }
+
+    $commands = [];
+
+    foreach (glob("{$pluginDir}/*Plugin.php") as $file) {
+        $className = 'MokoEnterprise\\Plugins\\'
+            . pathinfo($file, PATHINFO_FILENAME);
+
+        if (!class_exists($className)) {
+            continue;
+        }
+
+        try {
+            $ref = new \ReflectionClass($className);
+            if ($ref->isAbstract()) {
+                continue;
+            }
+
+            $plugin = $ref->newInstanceWithoutConstructor();
+            $pluginCmds = $plugin->getCommands();
+
+            foreach ($pluginCmds as $cmd) {
+                $name = $cmd['name'] ?? '';
+                if ($name === '') {
+                    continue;
+                }
+
+                $type = method_exists($plugin, 'getProjectType')
+                    ? $plugin->getProjectType() : 'unknown';
+
+                $commands[$name] = [
+                    'plugin' => $type,
+                    'description' => $cmd['description'] ?? '',
+                    'script' => $cmd['script'] ?? '',
+                ];
+            }
+        } catch (\Throwable $e) {
+            // Skip plugins that can't be instantiated
+            continue;
+        }
+    }
+
+    return $commands;
 }

cli/client_health_check.php

@@ -0,0 +1,188 @@
+#!/usr/bin/env php
+<?php
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: moko-platform.CLI
+ * INGROUP: moko-platform
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+ * PATH: /cli/client_health_check.php
+ * BRIEF: Verify a client site's update server, installed version, and release availability
+ *
+ * Usage:
+ *   php client_health_check.php --update-url URL
+ *   php client_health_check.php --path /repo --github-output
+ *
+ * Options:
+ *   --path           Repository root (reads update server URL from manifest)
+ *   --update-url     Update server XML URL (overrides manifest)
+ *   --site-url       Live site URL for version checking via Joomla API (optional)
+ *   --api-token      Joomla API token for site-url (optional)
+ *   --github-output  Export results to $GITHUB_OUTPUT
+ */
+
+declare(strict_types=1);
+
+$path = '.';
+$updateUrl = null;
+$siteUrl = null;
+$apiToken = null;
+$ghOutput = false;
+
+foreach ($argv as $i => $arg) {
+	if ($arg === '--path' && isset($argv[$i + 1])) $path = $argv[$i + 1];
+	if ($arg === '--update-url' && isset($argv[$i + 1])) $updateUrl = $argv[$i + 1];
+	if ($arg === '--site-url' && isset($argv[$i + 1])) $siteUrl = $argv[$i + 1];
+	if ($arg === '--api-token' && isset($argv[$i + 1])) $apiToken = $argv[$i + 1];
+	if ($arg === '--github-output') $ghOutput = true;
+}
+
+$root = realpath($path) ?: $path;
+$checks = [];
+
+// ── Resolve update server URL from manifest ─────────────────────────────
+if ($updateUrl === null) {
+	$searchDirs = ["{$root}/src", $root];
+	foreach ($searchDirs as $dir) {
+		if (!is_dir($dir)) continue;
+		foreach (glob("{$dir}/*.xml") ?: [] as $f) {
+			$xml = file_get_contents($f);
+			if (preg_match('/<server[^>]*>([^<]+)<\/server>/', $xml, $m)) {
+				$updateUrl = trim($m[1]);
+				break 2;
+			}
+		}
+	}
+}
+
+if ($updateUrl === null) {
+	fwrite(STDERR, "No update server URL found. Use --update-url or provide a manifest with <updateservers>.\n");
+	exit(1);
+}
+
+echo "Update server: {$updateUrl}\n\n";
+
+// ── Check 1: Update server accessible ───────────────────────────────────
+echo "--- Update Server ---\n";
+$ch = curl_init($updateUrl);
+curl_setopt_array($ch, [
+	CURLOPT_RETURNTRANSFER => true,
+	CURLOPT_TIMEOUT => 15,
+	CURLOPT_FOLLOWLOCATION => true,
+	CURLOPT_HTTPHEADER => ['User-Agent: MokoHealthCheck/1.0'],
+]);
+$response = curl_exec($ch);
+$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+curl_close($ch);
+
+if ($httpCode === 200 && !empty($response)) {
+	echo "  PASS: HTTP {$httpCode}, " . strlen($response) . " bytes\n";
+	$checks['update_server'] = 'pass';
+} else {
+	echo "  FAIL: HTTP {$httpCode}\n";
+	$checks['update_server'] = 'fail';
+}
+
+// ── Check 2: Parse updates.xml for stable version ───────────────────────
+$stableVersion = null;
+$downloadUrl = null;
+
+if (!empty($response)) {
+	$sections = preg_split('/<update>/', $response);
+	foreach ($sections as $section) {
+		if (strpos($section, '<tag>stable</tag>') !== false) {
+			if (preg_match('/<version>([^<]+)<\/version>/', $section, $m)) {
+				$stableVersion = $m[1];
+			}
+			if (preg_match('/<downloadurl[^>]*>([^<]+)<\/downloadurl>/', $section, $m)) {
+				$downloadUrl = trim($m[1]);
+			}
+			break;
+		}
+	}
+
+	if ($stableVersion === null && preg_match('/<version>([^<]+)<\/version>/', $response, $m)) {
+		$stableVersion = $m[1];
+	}
+}
+
+echo "\n--- Stable Release ---\n";
+if ($stableVersion !== null) {
+	echo "  Version: {$stableVersion}\n";
+	$checks['stable_version'] = $stableVersion;
+} else {
+	echo "  FAIL: Could not parse stable version\n";
+	$checks['stable_version'] = 'fail';
+}
+
+// ── Check 3: Download URL accessible ────────────────────────────────────
+if ($downloadUrl !== null) {
+	echo "\n--- Download URL ---\n";
+	$ch = curl_init($downloadUrl);
+	curl_setopt_array($ch, [
+		CURLOPT_NOBODY => true,
+		CURLOPT_TIMEOUT => 15,
+		CURLOPT_FOLLOWLOCATION => true,
+	]);
+	curl_exec($ch);
+	$dlCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+	$dlSize = curl_getinfo($ch, CURLINFO_CONTENT_LENGTH_DOWNLOAD);
+	curl_close($ch);
+
+	if ($dlCode === 200) {
+		$sizeKb = $dlSize > 0 ? round($dlSize / 1024) . 'KB' : 'unknown size';
+		echo "  PASS: HTTP {$dlCode}, {$sizeKb}\n";
+		$checks['download'] = 'pass';
+	} else {
+		echo "  FAIL: HTTP {$dlCode}\n";
+		$checks['download'] = 'fail';
+	}
+}
+
+// ── Check 4: Site version (optional) ────────────────────────────────────
+if ($siteUrl !== null && $apiToken !== null) {
+	echo "\n--- Site Version ---\n";
+	$apiUrl = rtrim($siteUrl, '/') . '/api/index.php/v1/extensions?filter[type]=file';
+	$ch = curl_init($apiUrl);
+	curl_setopt_array($ch, [
+		CURLOPT_RETURNTRANSFER => true,
+		CURLOPT_TIMEOUT => 15,
+		CURLOPT_HTTPHEADER => [
+			"X-Joomla-Token: {$apiToken}",
+			'Accept: application/json',
+		],
+	]);
+	$siteResponse = curl_exec($ch);
+	$siteCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+	curl_close($ch);
+
+	if ($siteCode === 200) {
+		echo "  API accessible (HTTP {$siteCode})\n";
+		$checks['site_api'] = 'pass';
+	} else {
+		echo "  WARN: Site API returned HTTP {$siteCode}\n";
+		$checks['site_api'] = 'warn';
+	}
+}
+
+// ── Summary ─────────────────────────────────────────────────────────────
+echo "\n=== Health Check Summary ===\n";
+$failed = 0;
+foreach ($checks as $name => $result) {
+	$icon = ($result === 'fail') ? 'FAIL' : (($result === 'warn') ? 'WARN' : 'OK');
+	if ($result === 'fail') $failed++;
+	echo "  {$icon}: {$name} = {$result}\n";
+}
+
+if ($ghOutput) {
+	$ghFile = getenv('GITHUB_OUTPUT');
+	if ($ghFile) {
+		file_put_contents($ghFile, "health_status=" . ($failed > 0 ? 'fail' : 'pass') . "\n", FILE_APPEND);
+		file_put_contents($ghFile, "health_version=" . ($stableVersion ?? 'unknown') . "\n", FILE_APPEND);
+		file_put_contents($ghFile, "health_failures={$failed}\n", FILE_APPEND);
+	}
+}
+
+exit($failed > 0 ? 1 : 0);

cli/joomla_compat_check.php

@@ -0,0 +1,136 @@
+#!/usr/bin/env php
+<?php
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: moko-platform.CLI
+ * INGROUP: moko-platform
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+ * PATH: /cli/joomla_compat_check.php
+ * BRIEF: Check if extension targetplatform regex matches the latest Joomla version
+ *
+ * Usage:
+ *   php joomla_compat_check.php --path /repo
+ *   php joomla_compat_check.php --path /repo --github-output
+ *
+ * Options:
+ *   --path           Repository root (default: .)
+ *   --github-output  Export results to $GITHUB_OUTPUT
+ */
+
+declare(strict_types=1);
+
+$path = '.';
+$ghOutput = false;
+
+foreach ($argv as $i => $arg) {
+	if ($arg === '--path' && isset($argv[$i + 1])) $path = $argv[$i + 1];
+	if ($arg === '--github-output') $ghOutput = true;
+}
+
+$root = realpath($path) ?: $path;
+
+// ── Find manifest and extract targetplatform ────────────────────────────
+$manifest = null;
+$searchDirs = ["{$root}/src", $root];
+foreach ($searchDirs as $dir) {
+	if (!is_dir($dir)) continue;
+	foreach (glob("{$dir}/*.xml") ?: [] as $f) {
+		$xml = file_get_contents($f);
+		if (strpos($xml, '<extension') !== false && strpos($xml, 'targetplatform') !== false) {
+			$manifest = $f;
+			break 2;
+		}
+	}
+}
+
+if ($manifest === null) {
+	fwrite(STDERR, "No manifest with targetplatform found\n");
+	exit(1);
+}
+
+$xml = file_get_contents($manifest);
+$relManifest = str_replace($root . '/', '', $manifest);
+
+// Extract targetplatform version regex
+$targetRegex = '';
+if (preg_match('/targetplatform[^>]*version="([^"]+)"/', $xml, $m)) {
+	$targetRegex = $m[1];
+}
+
+if (empty($targetRegex)) {
+	echo "No targetplatform version found in {$relManifest}\n";
+	exit(1);
+}
+
+echo "Manifest:        {$relManifest}\n";
+echo "Target regex:    {$targetRegex}\n";
+
+// ── Fetch latest Joomla version ─────────────────────────────────────────
+$joomlaVersions = [];
+$updateUrl = 'https://update.joomla.org/core/sts/list_sts.xml';
+$updateXml = @file_get_contents($updateUrl);
+
+if ($updateXml === false) {
+	// Fallback: try the LTS feed
+	$updateUrl = 'https://update.joomla.org/core/list.xml';
+	$updateXml = @file_get_contents($updateUrl);
+}
+
+if ($updateXml !== false) {
+	// Parse all version entries
+	preg_match_all('/<version>([^<]+)<\/version>/', $updateXml, $matches);
+	$joomlaVersions = $matches[1] ?? [];
+}
+
+if (empty($joomlaVersions)) {
+	echo "WARNING: Could not fetch Joomla versions from update server\n";
+	echo "Tested URL: {$updateUrl}\n";
+	exit(0);
+}
+
+// Sort and get latest
+usort($joomlaVersions, 'version_compare');
+$latestJoomla = end($joomlaVersions);
+
+echo "Latest Joomla:   {$latestJoomla}\n";
+
+// ── Test compatibility ──────────────────────────────────────────────────
+// The targetplatform regex uses Joomla's regex format
+// Common patterns: "5\.[0-9]+" or "((5.[0-9])|(6.[0-9]))"
+$compatible = @preg_match("/{$targetRegex}/", $latestJoomla);
+
+if ($compatible === false) {
+	echo "ERROR: Invalid regex in targetplatform: {$targetRegex}\n";
+	$result = 'error';
+} elseif ($compatible === 1) {
+	echo "PASS: Joomla {$latestJoomla} matches targetplatform regex\n";
+	$result = 'pass';
+} else {
+	// Check which major versions are supported
+	$supported = [];
+	foreach (['5.0', '5.1', '5.2', '5.3', '5.4', '6.0', '6.1', '6.2', '7.0'] as $v) {
+		if (@preg_match("/{$targetRegex}/", $v)) {
+			$supported[] = $v;
+		}
+	}
+
+	echo "WARN: Joomla {$latestJoomla} does NOT match targetplatform regex\n";
+	echo "Supported versions: " . implode(', ', $supported) . "\n";
+	echo "Consider updating targetplatform to include Joomla {$latestJoomla}\n";
+	$result = 'warn';
+}
+
+// ── Export ───────────────────────────────────────────────────────────────
+if ($ghOutput) {
+	$ghFile = getenv('GITHUB_OUTPUT');
+	if ($ghFile) {
+		file_put_contents($ghFile, "compat_result={$result}\n", FILE_APPEND);
+		file_put_contents($ghFile, "compat_joomla={$latestJoomla}\n", FILE_APPEND);
+		file_put_contents($ghFile, "compat_regex={$targetRegex}\n", FILE_APPEND);
+	}
+}
+
+exit($result === 'error' ? 1 : 0);

cli/joomla_release.php

@@ -24,9 +24,17 @@ declare(strict_types=1);
 
 require_once __DIR__ . '/../vendor/autoload.php';
 
-use MokoEnterprise\{ApiClient, AuditLogger, CLIApp, Config, PlatformAdapterFactory};
+use MokoEnterprise\{ApiClient, AuditLogger, CliFramework, Config, PlatformAdapterFactory};
 
-class JoomlaRelease extends CLIApp
+/**
+ * Joomla Release Manager
+ *
+ * Creates and manages Joomla extension releases on Gitea, including
+ * package building, asset upload, and update stream management.
+ *
+ * @since 04.06.00
+ */
+class JoomlaRelease extends CliFramework
 {
     private const VERSION = '04.06.00';
     private const ORG     = 'mokoconsulting-tech';
@@ -48,7 +56,7 @@ class JoomlaRelease extends CLIApp
     ];
 
     private ApiClient   $api;
-    private AuditLogger $logger;
+    private \MokoEnterprise\GitPlatformAdapter $adapter;
 
     protected function configure(): void
     {
@@ -75,7 +83,6 @@ class JoomlaRelease extends CLIApp
         $config       = Config::load();
         $this->adapter = PlatformAdapterFactory::create($config);
         $this->api    = $this->adapter->getApiClient();
-        $this->logger = new AuditLogger('joomla_release');
 
         if ($repo !== '') {
             $path = $this->cloneRepo($repo);
@@ -498,5 +505,5 @@ class JoomlaRelease extends CLIApp
     }
 }
 
-$script = new JoomlaRelease('joomla_release', 'Joomla release pipeline');
-exit($script->execute());
+$app = new JoomlaRelease();
+exit($app->execute());

cli/manifest_element.php

@@ -0,0 +1,235 @@
+#!/usr/bin/env php
+<?php
+
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: moko-platform.CLI
+ * INGROUP: moko-platform
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+ * PATH: /cli/manifest_element.php
+ * BRIEF: Extract element name, type, type prefix, and ZIP name from manifest
+ *
+ * Usage:
+ *   php manifest_element.php --path .
+ *   php manifest_element.php --path . --version 09.01.00 --stability dev --github-output
+ *
+ * Detects platform (joomla, dolibarr, generic) and resolves:
+ *   ext_element   — canonical element name (e.g. mokojgdpc)
+ *   ext_type      — extension type (plugin, module, component, package, etc.)
+ *   ext_folder    — group/folder for plugins (e.g. system)
+ *   ext_name      — human-readable name (e.g. "Moko JGDPC")
+ *   type_prefix   — Joomla type prefix (plg_system_, com_, mod_, etc.)
+ *   zip_name      — computed ZIP filename
+ */
+
+declare(strict_types=1);
+
+$path = '.';
+$version = null;
+$stability = 'stable';
+$githubOutput = false;
+$repoName = '';
+
+foreach ($argv as $i => $arg) {
+    if ($arg === '--path' && isset($argv[$i + 1])) {
+        $path = $argv[$i + 1];
+    }
+    if ($arg === '--version' && isset($argv[$i + 1])) {
+        $version = $argv[$i + 1];
+    }
+    if ($arg === '--stability' && isset($argv[$i + 1])) {
+        $stability = $argv[$i + 1];
+    }
+    if ($arg === '--repo' && isset($argv[$i + 1])) {
+        $repoName = $argv[$i + 1];
+    }
+    if ($arg === '--github-output') {
+        $githubOutput = true;
+    }
+}
+
+$root = realpath($path) ?: $path;
+
+// ── Detect platform from manifest.xml ────────────────────────────────────────
+$platform = 'generic';
+$manifestXml = "{$root}/.mokogitea/manifest.xml";
+if (file_exists($manifestXml)) {
+    $content = file_get_contents($manifestXml);
+    if (preg_match('/<platform>([^<]+)<\/platform>/', $content, $pm)) {
+        $platform = trim($pm[1]);
+    }
+}
+
+// ── Find extension manifest (Joomla XML) ─────────────────────────────────────
+$extManifest = null;
+$manifestFiles = array_merge(
+    glob("{$root}/src/pkg_*.xml") ?: [],
+    glob("{$root}/src/*.xml") ?: [],
+    glob("{$root}/*.xml") ?: []
+);
+foreach ($manifestFiles as $file) {
+    $c = file_get_contents($file);
+    if (strpos($c, '<extension') !== false) {
+        $extManifest = $file;
+        break;
+    }
+}
+
+// ── Find Dolibarr module file ────────────────────────────────────────────────
+$modFile = null;
+$modFiles = array_merge(
+    glob("{$root}/src/core/modules/mod*.class.php") ?: [],
+    glob("{$root}/htdocs/core/modules/mod*.class.php") ?: [],
+    glob("{$root}/core/modules/mod*.class.php") ?: []
+);
+foreach ($modFiles as $file) {
+    $c = file_get_contents($file);
+    if (strpos($c, 'extends DolibarrModules') !== false) {
+        $modFile = $file;
+        break;
+    }
+}
+
+// ── Extract metadata ─────────────────────────────────────────────────────────
+$extElement = '';
+$extType = '';
+$extFolder = '';
+$extName = '';
+
+switch (true) {
+    // Joomla platforms
+    case in_array($platform, ['joomla', 'waas-component'], true) && $extManifest !== null:
+        $xml = file_get_contents($extManifest);
+
+        // Extension type and folder
+        if (preg_match('/type="([^"]*)"/', $xml, $tm)) {
+            $extType = $tm[1];
+        }
+        if (preg_match('/group="([^"]*)"/', $xml, $gm)) {
+            $extFolder = $gm[1];
+        }
+
+        // Element name: <element>, plugin= attribute, <packagename>, or filename
+        if (preg_match('/<element>([^<]+)<\/element>/', $xml, $em)) {
+            $extElement = $em[1];
+        }
+        if (empty($extElement) && preg_match('/plugin="([^"]*)"/', $xml, $pm)) {
+            $extElement = $pm[1];
+        }
+        if ($extType === 'package' && preg_match('/<packagename>([^<]+)<\/packagename>/', $xml, $pn)) {
+            $extElement = $pn[1];
+        }
+        if (empty($extElement)) {
+            $extElement = strtolower(basename($extManifest, '.xml'));
+            if (in_array($extElement, ['templatedetails', 'manifest'], true)) {
+                $extElement = strtolower(str_replace([' ', '-'], '', $repoName ?: basename($root)));
+            }
+        }
+
+        // Human-readable name
+        if (preg_match('/<name>([^<]+)<\/name>/', $xml, $nm)) {
+            $extName = trim($nm[1]);
+        }
+        break;
+
+    // Dolibarr platforms
+    case in_array($platform, ['dolibarr', 'crm-module'], true) && $modFile !== null:
+        $extType = 'dolibarr-module';
+        $modBasename = basename($modFile, '.class.php');
+        $extElement = strtolower(preg_replace('/^mod/', '', $modBasename));
+
+        $modContent = file_get_contents($modFile);
+        if (preg_match('/\$this->name\s*=\s*[\'"]([^\'"]+)[\'"]/', $modContent, $nm)) {
+            $extName = $nm[1];
+        }
+        break;
+
+    // Generic / fallback
+    default:
+        $extElement = strtolower(str_replace([' ', '-'], '', $repoName ?: basename($root)));
+        $extType = 'generic';
+        break;
+}
+
+// ── Strip existing type prefix from element to prevent duplication ────────────
+$extElement = preg_replace('/^(pkg_|com_|mod_|plg_[a-z]+_|tpl_|lib_)/', '', $extElement);
+
+// ── Compute type prefix ──────────────────────────────────────────────────────
+$typePrefix = '';
+switch ($extType) {
+    case 'plugin':
+        $typePrefix = "plg_{$extFolder}_";
+        break;
+    case 'module':
+        $typePrefix = 'mod_';
+        break;
+    case 'component':
+        $typePrefix = 'com_';
+        break;
+    case 'template':
+        $typePrefix = 'tpl_';
+        break;
+    case 'library':
+        $typePrefix = 'lib_';
+        break;
+    case 'package':
+        $typePrefix = 'pkg_';
+        break;
+}
+
+// ── Compute ZIP name ─────────────────────────────────────────────────────────
+$suffixMap = [
+    'development' => '-dev',
+    'dev'         => '-dev',
+    'alpha'       => '-alpha',
+    'beta'        => '-beta',
+    'rc'          => '-rc',
+    'release-candidate' => '-rc',
+    'stable'      => '',
+];
+$suffix = $suffixMap[$stability] ?? '';
+$zipName = '';
+if ($version !== null) {
+    $zipName = "{$typePrefix}{$extElement}-{$version}{$suffix}.zip";
+}
+
+// Fallback name
+if (empty($extName)) {
+    $extName = $repoName ?: basename($root);
+}
+
+// ── Output ───────────────────────────────────────────────────────────────────
+$outputs = [
+    'platform'    => $platform,
+    'ext_element' => $extElement,
+    'ext_type'    => $extType,
+    'ext_folder'  => $extFolder,
+    'ext_name'    => $extName,
+    'type_prefix' => $typePrefix,
+    'zip_name'    => $zipName,
+];
+
+if ($githubOutput) {
+    $ghOutput = getenv('GITHUB_OUTPUT');
+    $lines = [];
+    foreach ($outputs as $key => $value) {
+        $lines[] = "{$key}={$value}";
+    }
+    if ($ghOutput) {
+        file_put_contents($ghOutput, implode("\n", $lines) . "\n", FILE_APPEND);
+    } else {
+        // Fallback: echo ::set-output (legacy)
+        foreach ($outputs as $key => $value) {
+            echo "::set-output name={$key}::{$value}\n";
+        }
+    }
+} else {
+    foreach ($outputs as $key => $value) {
+        echo "{$key}={$value}\n";
+    }
+}
+
+exit(0);

cli/manifest_read.php

@@ -103,6 +103,7 @@ if ($xml === false) {
         'language'          => (string)($xml->build->language ?? ''),
         'package-type'      => (string)($xml->build->{"package-type"} ?? ''),
         'entry-point'       => (string)($xml->build->{"entry-point"} ?? ''),
+        'version'           => (string)($xml->identity->version ?? ''),
         'source-dir'        => (string)($xml->deploy->{"source-dir"} ?? ''),
         'remote-subdir'     => (string)($xml->deploy->{"remote-subdir"} ?? ''),
         'excludes'          => (string)($xml->deploy->excludes ?? ''),

cli/release_cascade.php

@@ -1,5 +1,6 @@
 #!/usr/bin/env php
 <?php
+
 /* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
  *
  * SPDX-License-Identifier: GPL-3.0-or-later
@@ -14,12 +15,16 @@
  * Usage:
  *   php release_cascade.php --stability stable --token TOKEN --api-base URL
  *   php release_cascade.php --stability rc --token TOKEN --api-base URL
+ *   php release_cascade.php --stability stable --version 09.01.00 --token TOKEN --api-base URL
  *
  * Cascade rules:
  *   stable -> deletes development, alpha, beta, release-candidate
  *   rc     -> deletes development, alpha, beta
  *   beta   -> deletes development, alpha
  *   alpha  -> deletes development
+ *
+ * When --version is given, also deletes releases on any channel whose version
+ * is lower than the specified version (prevents stale pre-releases lingering).
  */
 
 declare(strict_types=1);
@@ -27,90 +32,176 @@ declare(strict_types=1);
 $stability = null;
 $token = null;
 $apiBase = null;
+$version = null;
 
 foreach ($argv as $i => $arg) {
-	if ($arg === '--stability' && isset($argv[$i + 1])) $stability = $argv[$i + 1];
-	if ($arg === '--token' && isset($argv[$i + 1])) $token = $argv[$i + 1];
-	if ($arg === '--api-base' && isset($argv[$i + 1])) $apiBase = $argv[$i + 1];
+    if ($arg === '--stability' && isset($argv[$i + 1])) {
+        $stability = $argv[$i + 1];
+    }
+    if ($arg === '--token' && isset($argv[$i + 1])) {
+        $token = $argv[$i + 1];
+    }
+    if ($arg === '--api-base' && isset($argv[$i + 1])) {
+        $apiBase = $argv[$i + 1];
+    }
+    if ($arg === '--version' && isset($argv[$i + 1])) {
+        $version = $argv[$i + 1];
+    }
 }
 
 // Allow token from environment
 if ($token === null) {
-	$token = getenv('GA_TOKEN') ?: getenv('GITEA_TOKEN') ?: null;
+    $token = getenv('GA_TOKEN') ?: getenv('GITEA_TOKEN') ?: null;
 }
 
 if ($stability === null || $token === null || $apiBase === null) {
-	fwrite(STDERR, "Usage: release_cascade.php --stability [stable|rc|beta|alpha] --token TOKEN --api-base URL\n");
-	fwrite(STDERR, "  --api-base: e.g. https://git.mokoconsulting.tech/api/v1/repos/Org/Repo\n");
-	fwrite(STDERR, "  Token can also be set via GA_TOKEN or GITEA_TOKEN env var\n");
-	exit(1);
+    fwrite(STDERR, "Usage: release_cascade.php --stability [stable|rc|beta|alpha] --token TOKEN --api-base URL\n");
+    fwrite(STDERR, "  --api-base: e.g. https://git.mokoconsulting.tech/api/v1/repos/Org/Repo\n");
+    fwrite(STDERR, "  Token can also be set via GA_TOKEN or GITEA_TOKEN env var\n");
+    exit(1);
 }
 
 // Define cascade hierarchy
 $cascadeMap = [
-	'stable'            => ['development', 'alpha', 'beta', 'release-candidate'],
-	'release-candidate' => ['development', 'alpha', 'beta'],
-	'rc'                => ['development', 'alpha', 'beta'],
-	'beta'              => ['development', 'alpha'],
-	'alpha'             => ['development'],
+    'stable'            => ['development', 'alpha', 'beta', 'release-candidate'],
+    'release-candidate' => ['development', 'alpha', 'beta'],
+    'rc'                => ['development', 'alpha', 'beta'],
+    'beta'              => ['development', 'alpha'],
+    'alpha'             => ['development'],
 ];
 
 if (!isset($cascadeMap[$stability])) {
-	fwrite(STDERR, "Unknown stability level: {$stability}\n");
-	fwrite(STDERR, "Valid options: stable, rc, beta, alpha\n");
-	exit(1);
+    fwrite(STDERR, "Unknown stability level: {$stability}\n");
+    fwrite(STDERR, "Valid options: stable, rc, beta, alpha\n");
+    exit(1);
 }
 
 $tagsToDelete = $cascadeMap[$stability];
 $deleted = 0;
 
 foreach ($tagsToDelete as $tag) {
-	// Get release by tag
-	$ch = curl_init("{$apiBase}/releases/tags/{$tag}");
-	curl_setopt_array($ch, [
-		CURLOPT_RETURNTRANSFER => true,
-		CURLOPT_HTTPHEADER => ["Authorization: token {$token}"],
-		CURLOPT_TIMEOUT => 30,
-	]);
-	$response = curl_exec($ch);
-	$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
-	curl_close($ch);
+    // Get release by tag
+    $ch = curl_init("{$apiBase}/releases/tags/{$tag}");
+    curl_setopt_array($ch, [
+        CURLOPT_RETURNTRANSFER => true,
+        CURLOPT_HTTPHEADER => ["Authorization: token {$token}"],
+        CURLOPT_TIMEOUT => 30,
+    ]);
+    $response = curl_exec($ch);
+    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+    curl_close($ch);
 
-	if ($httpCode !== 200 || empty($response)) {
-		continue;
-	}
+    if ($httpCode !== 200 || empty($response)) {
+        continue;
+    }
 
-	$data = json_decode($response, true);
-	$releaseId = $data['id'] ?? null;
+    $data = json_decode($response, true);
+    $releaseId = $data['id'] ?? null;
 
-	if ($releaseId === null) {
-		continue;
-	}
+    if ($releaseId === null) {
+        continue;
+    }
 
-	// Delete release
-	$ch = curl_init("{$apiBase}/releases/{$releaseId}");
-	curl_setopt_array($ch, [
-		CURLOPT_CUSTOMREQUEST => 'DELETE',
-		CURLOPT_RETURNTRANSFER => true,
-		CURLOPT_HTTPHEADER => ["Authorization: token {$token}"],
-		CURLOPT_TIMEOUT => 30,
-	]);
-	curl_exec($ch);
-	curl_close($ch);
+    // Delete release
+    $ch = curl_init("{$apiBase}/releases/{$releaseId}");
+    curl_setopt_array($ch, [
+        CURLOPT_CUSTOMREQUEST => 'DELETE',
+        CURLOPT_RETURNTRANSFER => true,
+        CURLOPT_HTTPHEADER => ["Authorization: token {$token}"],
+        CURLOPT_TIMEOUT => 30,
+    ]);
+    curl_exec($ch);
+    curl_close($ch);
 
-	// Delete tag
-	$ch = curl_init("{$apiBase}/tags/{$tag}");
-	curl_setopt_array($ch, [
-		CURLOPT_CUSTOMREQUEST => 'DELETE',
-		CURLOPT_RETURNTRANSFER => true,
-		CURLOPT_HTTPHEADER => ["Authorization: token {$token}"],
-		CURLOPT_TIMEOUT => 30,
-	]);
-	curl_exec($ch);
-	curl_close($ch);
+    // Delete tag
+    $ch = curl_init("{$apiBase}/tags/{$tag}");
+    curl_setopt_array($ch, [
+        CURLOPT_CUSTOMREQUEST => 'DELETE',
+        CURLOPT_RETURNTRANSFER => true,
+        CURLOPT_HTTPHEADER => ["Authorization: token {$token}"],
+        CURLOPT_TIMEOUT => 30,
+    ]);
+    curl_exec($ch);
+    curl_close($ch);
 
-	echo "Deleted: {$tag} (release id: {$releaseId})\n";
-	$deleted++;
+    echo "Deleted: {$tag} (release id: {$releaseId})\n";
+    $deleted++;
+}
+
+// ── Version-aware cleanup: delete releases with lesser version numbers ───────
+if ($version !== null) {
+    // Normalize version for comparison (strip any suffix)
+    $baseVersion = preg_replace('/-[a-z]+$/', '', $version);
+
+    // Check all channels (including ones not in the cascade map for this stability)
+    $allChannels = ['development', 'alpha', 'beta', 'release-candidate', 'stable'];
+    foreach ($allChannels as $tag) {
+        // Skip the current stability channel
+        if ($tag === $stability) {
+            continue;
+        }
+        // Skip channels already deleted by cascade above
+        if (in_array($tag, $tagsToDelete, true)) {
+            continue;
+        }
+
+        $ch = curl_init("{$apiBase}/releases/tags/{$tag}");
+        curl_setopt_array($ch, [
+            CURLOPT_RETURNTRANSFER => true,
+            CURLOPT_HTTPHEADER => ["Authorization: token {$token}"],
+            CURLOPT_TIMEOUT => 30,
+        ]);
+        $response = curl_exec($ch);
+        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+        curl_close($ch);
+
+        if ($httpCode !== 200 || empty($response)) {
+            continue;
+        }
+
+        $data = json_decode($response, true);
+        $releaseId = $data['id'] ?? null;
+        $releaseName = $data['name'] ?? '';
+        if ($releaseId === null) {
+            continue;
+        }
+
+        // Extract version from release name (e.g. "element 09.00.01 (development)")
+        $releaseVersion = null;
+        if (preg_match('/(\d{2}\.\d{2}\.\d{2})/', $releaseName, $vm)) {
+            $releaseVersion = $vm[1];
+        }
+
+        if ($releaseVersion === null) {
+            continue;
+        }
+
+        // Delete if release version is less than the promoted version
+        if (version_compare($releaseVersion, $baseVersion, '<')) {
+            $delCh = curl_init("{$apiBase}/releases/{$releaseId}");
+            curl_setopt_array($delCh, [
+                CURLOPT_CUSTOMREQUEST => 'DELETE',
+                CURLOPT_RETURNTRANSFER => true,
+                CURLOPT_HTTPHEADER => ["Authorization: token {$token}"],
+                CURLOPT_TIMEOUT => 30,
+            ]);
+            curl_exec($delCh);
+            curl_close($delCh);
+
+            $tagCh = curl_init("{$apiBase}/tags/{$tag}");
+            curl_setopt_array($tagCh, [
+                CURLOPT_CUSTOMREQUEST => 'DELETE',
+                CURLOPT_RETURNTRANSFER => true,
+                CURLOPT_HTTPHEADER => ["Authorization: token {$token}"],
+                CURLOPT_TIMEOUT => 30,
+            ]);
+            curl_exec($tagCh);
+            curl_close($tagCh);
+
+            echo "Deleted: {$tag} — version {$releaseVersion} < {$baseVersion}\n";
+            $deleted++;
+        }
+    }
 }
 
 echo "Cleaned up {$deleted} pre-release channel(s)\n";

cli/release_create.php

@@ -0,0 +1,328 @@
+#!/usr/bin/env php
+<?php
+
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: moko-platform.CLI
+ * INGROUP: moko-platform
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+ * PATH: /cli/release_create.php
+ * BRIEF: Create or overwrite a Gitea release with proper naming
+ *
+ * Usage:
+ *   php release_create.php --version 09.01.00 --tag stable --token TOKEN --api-base URL
+ *   php release_create.php --version 09.01.00 --tag development --token TOKEN --api-base URL --prerelease
+ *   php release_create.php --version 09.01.00 --tag stable --token TOKEN --api-base URL --path . --repo MyRepo
+ *
+ * Replaces the inline bash in auto-release.yml Step 7b.
+ * Detects extension metadata from manifest, builds a proper release name,
+ * generates release notes, and creates (or overwrites) a Gitea release.
+ */
+
+declare(strict_types=1);
+
+// ── Argument parsing ────────────────────────────────────────────────────────
+
+$path = '.';
+$version = null;
+$tag = null;
+$token = null;
+$apiBase = null;
+$branch = 'main';
+$repoName = '';
+$prerelease = false;
+
+foreach ($argv as $i => $arg) {
+    if ($arg === '--path' && isset($argv[$i + 1])) {
+        $path = $argv[$i + 1];
+    }
+    if ($arg === '--version' && isset($argv[$i + 1])) {
+        $version = $argv[$i + 1];
+    }
+    if ($arg === '--tag' && isset($argv[$i + 1])) {
+        $tag = $argv[$i + 1];
+    }
+    if ($arg === '--token' && isset($argv[$i + 1])) {
+        $token = $argv[$i + 1];
+    }
+    if ($arg === '--api-base' && isset($argv[$i + 1])) {
+        $apiBase = $argv[$i + 1];
+    }
+    if ($arg === '--branch' && isset($argv[$i + 1])) {
+        $branch = $argv[$i + 1];
+    }
+    if ($arg === '--repo' && isset($argv[$i + 1])) {
+        $repoName = $argv[$i + 1];
+    }
+    if ($arg === '--prerelease') {
+        $prerelease = true;
+    }
+}
+
+// Allow token from environment
+if ($token === null) {
+    $envToken = getenv('GA_TOKEN');
+    if ($envToken === false || $envToken === '') {
+        $envToken = getenv('GITEA_TOKEN');
+    }
+    if ($envToken !== false && $envToken !== '') {
+        $token = $envToken;
+    }
+}
+
+if ($version === null || $tag === null || $token === null || $apiBase === null) {
+    fwrite(STDERR, "Usage: release_create.php --version VER --tag TAG --token TOKEN --api-base URL [options]\n");
+    fwrite(STDERR, "  --path .          Repo root for manifest detection (default: .)\n");
+    fwrite(STDERR, "  --branch main     Target commitish (default: main)\n");
+    fwrite(STDERR, "  --repo REPO       Repo name for fallback element detection\n");
+    fwrite(STDERR, "  --prerelease      Mark release as prerelease\n");
+    fwrite(STDERR, "  Token can also be set via GA_TOKEN or GITEA_TOKEN env var\n");
+    exit(1);
+}
+
+// ── Helper: Gitea API request ───────────────────────────────────────────────
+
+/**
+ * Send a request to the Gitea API.
+ *
+ * @param string      $url    Full API URL
+ * @param string      $token  Authorization token
+ * @param string      $method HTTP method (GET, POST, DELETE, etc.)
+ * @param string|null $body   JSON request body
+ *
+ * @return array<string, mixed>|null Decoded response or null on failure
+ */
+function giteaApi(string $url, string $token, string $method = 'GET', ?string $body = null): ?array
+{
+    $ch = curl_init($url);
+    if ($ch === false) {
+        return null;
+    }
+    curl_setopt_array($ch, [
+        CURLOPT_RETURNTRANSFER => true,
+        CURLOPT_HTTPHEADER => [
+            "Authorization: token {$token}",
+            'Content-Type: application/json',
+        ],
+        CURLOPT_TIMEOUT => 30,
+        CURLOPT_CUSTOMREQUEST => $method,
+    ]);
+    if ($body !== null) {
+        curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
+    }
+    $response = curl_exec($ch);
+    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+    curl_close($ch);
+
+    if ($httpCode < 200 || $httpCode >= 300 || empty($response) || !is_string($response)) {
+        return null;
+    }
+
+    $decoded = json_decode($response, true);
+    return is_array($decoded) ? $decoded : null;
+}
+
+// ── Detect element metadata ─────────────────────────────────────────────────
+
+$root = realpath($path) ?: $path;
+
+$extElement = '';
+$extType = '';
+$extFolder = '';
+$extName = '';
+$typePrefix = '';
+
+// Detect platform from manifest.xml
+$platform = 'generic';
+$manifestXml = "{$root}/.mokogitea/manifest.xml";
+if (file_exists($manifestXml)) {
+    $content = file_get_contents($manifestXml);
+    if ($content !== false && preg_match('/<platform>([^<]+)<\/platform>/', $content, $pm)) {
+        $platform = trim($pm[1]);
+    }
+}
+
+// Find extension manifest (Joomla XML)
+$extManifest = null;
+$manifestFiles = array_merge(
+    glob("{$root}/src/pkg_*.xml") ?: [],
+    glob("{$root}/src/*.xml") ?: [],
+    glob("{$root}/*.xml") ?: []
+);
+foreach ($manifestFiles as $file) {
+    $c = file_get_contents($file);
+    if ($c !== false && strpos($c, '<extension') !== false) {
+        $extManifest = $file;
+        break;
+    }
+}
+
+// Find Dolibarr module file
+$modFile = null;
+$modFiles = array_merge(
+    glob("{$root}/src/core/modules/mod*.class.php") ?: [],
+    glob("{$root}/htdocs/core/modules/mod*.class.php") ?: [],
+    glob("{$root}/core/modules/mod*.class.php") ?: []
+);
+foreach ($modFiles as $file) {
+    $c = file_get_contents($file);
+    if ($c !== false && strpos($c, 'extends DolibarrModules') !== false) {
+        $modFile = $file;
+        break;
+    }
+}
+
+// Extract metadata based on platform
+switch (true) {
+    case in_array($platform, ['joomla', 'waas-component'], true) && $extManifest !== null:
+        $xml = file_get_contents($extManifest);
+        if ($xml === false) {
+            break;
+        }
+
+        if (preg_match('/type="([^"]*)"/', $xml, $tm)) {
+            $extType = $tm[1];
+        }
+        if (preg_match('/group="([^"]*)"/', $xml, $gm)) {
+            $extFolder = $gm[1];
+        }
+
+        // Element name: <element>, plugin= attribute, <packagename>, or filename
+        if (preg_match('/<element>([^<]+)<\/element>/', $xml, $em)) {
+            $extElement = $em[1];
+        }
+        if (empty($extElement) && preg_match('/plugin="([^"]*)"/', $xml, $pm2)) {
+            $extElement = $pm2[1];
+        }
+        if ($extType === 'package' && preg_match('/<packagename>([^<]+)<\/packagename>/', $xml, $pn)) {
+            $extElement = $pn[1];
+        }
+        if (empty($extElement)) {
+            $extElement = strtolower(basename($extManifest, '.xml'));
+            if (in_array($extElement, ['templatedetails', 'manifest'], true)) {
+                $extElement = strtolower(str_replace([' ', '-'], '', $repoName !== '' ? $repoName : basename($root)));
+            }
+        }
+
+        // Human-readable name
+        if (preg_match('/<name>([^<]+)<\/name>/', $xml, $nm)) {
+            $extName = trim($nm[1]);
+        }
+        break;
+
+    case in_array($platform, ['dolibarr', 'crm-module'], true) && $modFile !== null:
+        $extType = 'dolibarr-module';
+        $modBasename = basename($modFile, '.class.php');
+        $extElement = strtolower(preg_replace('/^mod/', '', $modBasename) ?? $modBasename);
+
+        $modContent = file_get_contents($modFile);
+        if ($modContent !== false && preg_match('/\$this->name\s*=\s*[\'"]([^\'"]+)[\'"]/', $modContent, $nm2)) {
+            $extName = $nm2[1];
+        }
+        break;
+
+    default:
+        $extElement = strtolower(str_replace([' ', '-'], '', $repoName !== '' ? $repoName : basename($root)));
+        $extType = 'generic';
+        break;
+}
+
+// Strip existing type prefix from element to prevent duplication
+$extElement = preg_replace('/^(pkg_|com_|mod_|plg_[a-z]+_|tpl_|lib_)/', '', $extElement) ?? $extElement;
+
+// Compute type prefix
+switch ($extType) {
+    case 'plugin':
+        $typePrefix = "plg_{$extFolder}_";
+        break;
+    case 'module':
+        $typePrefix = 'mod_';
+        break;
+    case 'component':
+        $typePrefix = 'com_';
+        break;
+    case 'template':
+        $typePrefix = 'tpl_';
+        break;
+    case 'library':
+        $typePrefix = 'lib_';
+        break;
+    case 'package':
+        $typePrefix = 'pkg_';
+        break;
+}
+
+// Fallback name
+if (empty($extName)) {
+    $extName = $repoName !== '' ? $repoName : basename($root);
+}
+
+echo "Element: {$extElement}, Type: {$extType}, Prefix: {$typePrefix}, Name: {$extName}\n";
+
+// ── Build release name ──────────────────────────────────────────────────────
+
+$releaseName = "{$extName} {$version} ({$typePrefix}{$extElement}-{$version})";
+echo "Release name: {$releaseName}\n";
+
+// ── Generate release notes ──────────────────────────────────────────────────
+
+$releaseNotes = "Release {$version}";
+$releaseNotesScript = dirname(__DIR__) . '/cli/release_notes.php';
+if (file_exists($releaseNotesScript)) {
+    $cmd = sprintf(
+        'php %s --path %s --version %s',
+        escapeshellarg($releaseNotesScript),
+        escapeshellarg($root),
+        escapeshellarg($version)
+    );
+    $output = [];
+    $exitCode = 0;
+    exec($cmd, $output, $exitCode);
+    if ($exitCode === 0 && count($output) > 0) {
+        $notes = implode("\n", $output);
+        if (trim($notes) !== '') {
+            $releaseNotes = $notes;
+            echo "Release notes: generated from CHANGELOG.md\n";
+        }
+    }
+}
+
+// ── Delete existing release at tag (if present) ─────────────────────────────
+
+$existing = giteaApi("{$apiBase}/releases/tags/{$tag}", $token);
+if ($existing !== null && !empty($existing['id'])) {
+    $existingId = $existing['id'];
+    echo "Deleting existing release: {$tag} (id: {$existingId})\n";
+
+    // Delete release
+    giteaApi("{$apiBase}/releases/{$existingId}", $token, 'DELETE');
+
+    // Delete tag
+    giteaApi("{$apiBase}/tags/{$tag}", $token, 'DELETE');
+}
+
+// ── Create new release ──────────────────────────────────────────────────────
+
+$payload = json_encode([
+    'tag_name'         => $tag,
+    'target_commitish' => $branch,
+    'name'             => $releaseName,
+    'body'             => $releaseNotes,
+    'prerelease'       => $prerelease,
+]);
+
+$newRelease = giteaApi("{$apiBase}/releases", $token, 'POST', $payload !== false ? $payload : '{}');
+if ($newRelease === null || empty($newRelease['id'])) {
+    fwrite(STDERR, "Failed to create release at tag: {$tag}\n");
+    exit(1);
+}
+
+$releaseId = $newRelease['id'];
+echo "Created release: {$tag} (id: {$releaseId})\n";
+
+// Output release_id to stdout for CI consumption
+echo "release_id={$releaseId}\n";
+exit(0);

cli/release_mirror.php

@@ -0,0 +1,300 @@
+#!/usr/bin/env php
+<?php
+
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: moko-platform.CLI
+ * INGROUP: moko-platform
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+ * PATH: /cli/release_mirror.php
+ * BRIEF: Mirror a Gitea release (with assets) to a GitHub repository
+ *
+ * Usage:
+ *   php release_mirror.php --version 09.01.00 --tag stable --token TOKEN --api-base URL \
+ *       --gh-token GH_TOKEN --gh-repo MokoConsulting/MokoWaaS
+ *
+ * Mirrors a Gitea release (title, body, assets) to a corresponding GitHub release.
+ * If the GitHub release already exists at the same tag, its title is updated via PATCH.
+ * All assets from the Gitea release are downloaded and uploaded to the GitHub release.
+ */
+
+declare(strict_types=1);
+
+// ── Argument parsing ─────────────────────────────────────────────────────────
+
+$version = null;
+$tag = null;
+$token = null;
+$apiBase = null;
+$ghToken = null;
+$ghRepo = null;
+$branch = 'main';
+
+foreach ($argv as $i => $arg) {
+    if ($arg === '--version' && isset($argv[$i + 1])) {
+        $version = $argv[$i + 1];
+    }
+    if ($arg === '--tag' && isset($argv[$i + 1])) {
+        $tag = $argv[$i + 1];
+    }
+    if ($arg === '--token' && isset($argv[$i + 1])) {
+        $token = $argv[$i + 1];
+    }
+    if ($arg === '--api-base' && isset($argv[$i + 1])) {
+        $apiBase = $argv[$i + 1];
+    }
+    if ($arg === '--gh-token' && isset($argv[$i + 1])) {
+        $ghToken = $argv[$i + 1];
+    }
+    if ($arg === '--gh-repo' && isset($argv[$i + 1])) {
+        $ghRepo = $argv[$i + 1];
+    }
+    if ($arg === '--branch' && isset($argv[$i + 1])) {
+        $branch = $argv[$i + 1];
+    }
+}
+
+// Allow tokens from environment
+$token = $token ?: (getenv('GA_TOKEN') ?: (getenv('GITEA_TOKEN') ?: null));
+$ghToken = $ghToken ?: (getenv('GH_TOKEN') ?: null);
+
+if (
+    $version === null || $tag === null || $token === null || $apiBase === null
+    || $ghToken === null || $ghRepo === null
+) {
+    fwrite(STDERR, "Usage: release_mirror.php --version VER --tag TAG --token TOKEN " .
+        "--api-base URL --gh-token GH_TOKEN --gh-repo org/repo [--branch main]\n");
+    fwrite(STDERR, "  --token: Gitea token (or GA_TOKEN / GITEA_TOKEN env)\n");
+    fwrite(STDERR, "  --gh-token: GitHub token (or GH_TOKEN env)\n");
+    exit(1);
+}
+
+// ── Helper: Gitea API request ────────────────────────────────────────────────
+
+/**
+ * Send a request to the Gitea API.
+ *
+ * @param string      $url    Full Gitea API URL
+ * @param string      $token  Gitea API token
+ * @param string      $method HTTP method (GET, POST, PATCH, DELETE)
+ * @param string|null $body   JSON request body or null
+ *
+ * @return array<string, mixed>|null Decoded response or null on failure
+ */
+function giteaApi(string $url, string $token, string $method = 'GET', ?string $body = null): ?array
+{
+    $ch = curl_init($url);
+    curl_setopt_array($ch, [
+        CURLOPT_RETURNTRANSFER => true,
+        CURLOPT_HTTPHEADER => [
+            "Authorization: token {$token}",
+            'Content-Type: application/json',
+        ],
+        CURLOPT_TIMEOUT => 30,
+        CURLOPT_CUSTOMREQUEST => $method,
+    ]);
+    if ($body !== null) {
+        curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
+    }
+    $response = curl_exec($ch);
+    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+    curl_close($ch);
+
+    if ($httpCode < 200 || $httpCode >= 300 || empty($response)) {
+        return null;
+    }
+    return json_decode($response, true) ?: null;
+}
+
+/**
+ * Download a file from Gitea to a local path.
+ *
+ * @param string $url   Download URL
+ * @param string $token Gitea API token
+ * @param string $dest  Local destination path
+ *
+ * @return bool True on success
+ */
+function giteaDownload(string $url, string $token, string $dest): bool
+{
+    $ch = curl_init($url);
+    $fp = fopen($dest, 'wb');
+    curl_setopt_array($ch, [
+        CURLOPT_HTTPHEADER => ["Authorization: token {$token}"],
+        CURLOPT_FILE => $fp,
+        CURLOPT_FOLLOWLOCATION => true,
+        CURLOPT_TIMEOUT => 120,
+    ]);
+    curl_exec($ch);
+    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+    curl_close($ch);
+    fclose($fp);
+    return $httpCode >= 200 && $httpCode < 300;
+}
+
+/**
+ * Send a request to the GitHub API.
+ *
+ * @param string      $url    Full GitHub API URL
+ * @param string      $token  GitHub personal access token
+ * @param string      $method HTTP method (GET, POST, PATCH, DELETE)
+ * @param string|null $body   JSON request body or null
+ *
+ * @return array<string, mixed>|null Decoded response or null on failure
+ */
+function githubApi(string $url, string $token, string $method = 'GET', ?string $body = null): ?array
+{
+    $ch = curl_init($url);
+    curl_setopt_array($ch, [
+        CURLOPT_RETURNTRANSFER => true,
+        CURLOPT_HTTPHEADER => [
+            "Authorization: token {$token}",
+            'Accept: application/vnd.github+json',
+            'User-Agent: moko-platform',
+            'Content-Type: application/json',
+        ],
+        CURLOPT_TIMEOUT => 30,
+        CURLOPT_CUSTOMREQUEST => $method,
+    ]);
+    if ($body !== null) {
+        curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
+    }
+    $response = curl_exec($ch);
+    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+    curl_close($ch);
+
+    if ($httpCode < 200 || $httpCode >= 300 || empty($response)) {
+        return null;
+    }
+    return json_decode($response, true) ?: null;
+}
+
+/**
+ * Upload a binary asset to a GitHub release.
+ *
+ * @param string $uploadUrl GitHub upload URL (uploads.github.com)
+ * @param string $token     GitHub personal access token
+ * @param string $filePath  Local file path to upload
+ * @param string $name      Asset filename for GitHub
+ *
+ * @return int HTTP status code
+ */
+function githubUploadAsset(string $uploadUrl, string $token, string $filePath, string $name): int
+{
+    $url = $uploadUrl . '?name=' . urlencode($name);
+    $ch = curl_init($url);
+    curl_setopt_array($ch, [
+        CURLOPT_POST => true,
+        CURLOPT_HTTPHEADER => [
+            "Authorization: token {$token}",
+            'Accept: application/vnd.github+json',
+            'User-Agent: moko-platform',
+            'Content-Type: application/octet-stream',
+        ],
+        CURLOPT_POSTFIELDS => file_get_contents($filePath),
+        CURLOPT_RETURNTRANSFER => true,
+        CURLOPT_TIMEOUT => 120,
+    ]);
+    curl_exec($ch);
+    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+    curl_close($ch);
+    return $httpCode;
+}
+
+// ── Step 1: Get Gitea release by tag ─────────────────────────────────────────
+
+echo "Fetching Gitea release: {$tag}\n";
+$giteaRelease = giteaApi("{$apiBase}/releases/tags/{$tag}", $token);
+if (!$giteaRelease || empty($giteaRelease['id'])) {
+    fwrite(STDERR, "No Gitea release found with tag: {$tag}\n");
+    exit(1);
+}
+
+$giteaId = $giteaRelease['id'];
+$releaseName = $giteaRelease['name'] ?? "{$version}";
+$releaseBody = $giteaRelease['body'] ?? '';
+$assets = $giteaRelease['assets'] ?? [];
+
+echo "  Name: {$releaseName}\n";
+echo "  Assets: " . count($assets) . " file(s)\n";
+
+// ── Step 2: Check / create GitHub release ────────────────────────────────────
+
+$ghApiBase = "https://api.github.com/repos/{$ghRepo}";
+$ghUploadBase = "https://uploads.github.com/repos/{$ghRepo}";
+
+echo "Checking GitHub release: {$tag}\n";
+$ghRelease = githubApi("{$ghApiBase}/releases/tags/{$tag}", $ghToken);
+
+if ($ghRelease && !empty($ghRelease['id'])) {
+    // Update existing release title
+    $ghReleaseId = $ghRelease['id'];
+    echo "  GitHub release exists (id: {$ghReleaseId}), updating title\n";
+    $patchPayload = json_encode([
+        'name' => $releaseName,
+        'body' => $releaseBody,
+    ]);
+    githubApi("{$ghApiBase}/releases/{$ghReleaseId}", $ghToken, 'PATCH', $patchPayload);
+} else {
+    // Create new release
+    echo "  Creating GitHub release\n";
+    $createPayload = json_encode([
+        'tag_name'         => $tag,
+        'target_commitish' => $branch,
+        'name'             => $releaseName,
+        'body'             => $releaseBody,
+        'draft'            => false,
+        'prerelease'       => ($tag !== 'stable'),
+    ]);
+    $ghRelease = githubApi("{$ghApiBase}/releases", $ghToken, 'POST', $createPayload);
+    if (!$ghRelease || empty($ghRelease['id'])) {
+        fwrite(STDERR, "Failed to create GitHub release\n");
+        exit(1);
+    }
+    $ghReleaseId = $ghRelease['id'];
+    echo "  Created GitHub release (id: {$ghReleaseId})\n";
+}
+
+// ── Step 3: Download assets from Gitea ───────────────────────────────────────
+
+$tmpDir = sys_get_temp_dir() . '/moko-mirror-' . getmypid();
+@mkdir($tmpDir, 0755, true);
+
+$uploadUrl = "{$ghUploadBase}/releases/{$ghReleaseId}/assets";
+
+foreach ($assets as $asset) {
+    $name = $asset['name'] ?? '';
+    $downloadUrl = $asset['browser_download_url'] ?? '';
+    if ($name === '' || $downloadUrl === '') {
+        continue;
+    }
+
+    $localPath = "{$tmpDir}/{$name}";
+    echo "  Downloading: {$name}\n";
+
+    if (!giteaDownload($downloadUrl, $token, $localPath)) {
+        fwrite(STDERR, "  Failed to download: {$name}\n");
+        continue;
+    }
+
+    // ── Step 4: Upload asset to GitHub ───────────────────────────────────────
+    echo "  Uploading: {$name}\n";
+    $code = githubUploadAsset($uploadUrl, $ghToken, $localPath, $name);
+    $status = ($code >= 200 && $code < 300) ? 'OK' : "FAILED ({$code})";
+    echo "    {$status}\n";
+}
+
+// ── Cleanup ──────────────────────────────────────────────────────────────────
+
+array_map('unlink', glob("{$tmpDir}/*") ?: []);
+@rmdir($tmpDir);
+
+// ── Summary ──────────────────────────────────────────────────────────────────
+
+echo "\nMirror complete: {$tag} -> github.com/{$ghRepo}\n";
+echo "  Version: {$version}\n";
+echo "  Assets: " . count($assets) . " file(s)\n";
+exit(0);

cli/release_package.php

@@ -0,0 +1,548 @@
+#!/usr/bin/env php
+<?php
+
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: moko-platform.CLI
+ * INGROUP: moko-platform
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+ * PATH: /cli/release_package.php
+ * BRIEF: Build packages (ZIP + tar.gz) with SHA-256 and upload to Gitea release
+ *
+ * Usage:
+ *   php release_package.php --path . --version 09.01.00 --tag stable --token TOKEN --api-base URL
+ *   php release_package.php --path . --version 09.01.00 --tag development --token TOKEN --api-base URL --repo myrepo
+ *
+ * Builds ZIP and tar.gz packages from src/ or htdocs/, computes SHA-256 checksums,
+ * creates .sha256 sidecar files, and uploads all assets to an existing Gitea release.
+ *
+ * For Joomla packages (type=package with packages/ subdir):
+ *   - ZIPs each sub-extension directory
+ *   - Copies top-level XML/PHP to package root before archiving
+ *
+ * For standard extensions:
+ *   - Builds ZIP and tar.gz from source dir
+ *   - Excludes: sftp-config*, .ftpignore, *.ppk, *.pem, *.key, .env*, *.local, .build-trigger
+ */
+
+declare(strict_types=1);
+
+// ── Argument parsing ─────────────────────────────────────────────────────────
+
+$path = '.';
+$version = null;
+$tag = null;
+$token = null;
+$apiBase = null;
+$repoName = '';
+$outputDir = sys_get_temp_dir();
+
+foreach ($argv as $i => $arg) {
+    if ($arg === '--path' && isset($argv[$i + 1])) {
+        $path = $argv[$i + 1];
+    }
+    if ($arg === '--version' && isset($argv[$i + 1])) {
+        $version = $argv[$i + 1];
+    }
+    if ($arg === '--tag' && isset($argv[$i + 1])) {
+        $tag = $argv[$i + 1];
+    }
+    if ($arg === '--token' && isset($argv[$i + 1])) {
+        $token = $argv[$i + 1];
+    }
+    if ($arg === '--api-base' && isset($argv[$i + 1])) {
+        $apiBase = $argv[$i + 1];
+    }
+    if ($arg === '--repo' && isset($argv[$i + 1])) {
+        $repoName = $argv[$i + 1];
+    }
+    if ($arg === '--output' && isset($argv[$i + 1])) {
+        $outputDir = $argv[$i + 1];
+    }
+}
+
+// Allow token from environment
+if ($token === null) {
+    $token = getenv('GA_TOKEN') ?: (getenv('GITEA_TOKEN') ?: null);
+}
+
+if ($version === null || $tag === null || $token === null || $apiBase === null) {
+    fwrite(STDERR, "Usage: release_package.php --path . --version VER --tag TAG --token TOKEN --api-base URL\n");
+    fwrite(STDERR, "  --repo REPO       Repo name for element detection fallback\n");
+    fwrite(STDERR, "  --output DIR      Output directory for built packages (default: sys_get_temp_dir())\n");
+    fwrite(STDERR, "  Token can also be set via GA_TOKEN or GITEA_TOKEN env var\n");
+    exit(1);
+}
+
+$root = realpath($path) ?: $path;
+
+// ── Helper: Gitea API request ────────────────────────────────────────────────
+
+/**
+ * Perform a Gitea API request.
+ *
+ * @param string      $url    Full API URL
+ * @param string      $token  API token
+ * @param string      $method HTTP method
+ * @param string|null $body   Request body (JSON)
+ *
+ * @return array{data: array<string, mixed>|null, code: int}
+ */
+function giteaApiRequest(string $url, string $token, string $method = 'GET', ?string $body = null): array
+{
+    $ch = curl_init($url);
+    if ($ch === false) {
+        return ['data' => null, 'code' => 0];
+    }
+    curl_setopt_array($ch, [
+        CURLOPT_RETURNTRANSFER => true,
+        CURLOPT_HTTPHEADER => [
+            "Authorization: token {$token}",
+            'Content-Type: application/json',
+        ],
+        CURLOPT_TIMEOUT => 30,
+        CURLOPT_CUSTOMREQUEST => $method,
+    ]);
+    if ($body !== null) {
+        curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
+    }
+    $response = curl_exec($ch);
+    $httpCode = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
+    curl_close($ch);
+
+    if ($httpCode < 200 || $httpCode >= 300 || !is_string($response) || $response === '') {
+        return ['data' => null, 'code' => $httpCode];
+    }
+
+    $decoded = json_decode($response, true);
+    return ['data' => is_array($decoded) ? $decoded : null, 'code' => $httpCode];
+}
+
+/**
+ * Upload a file as a release asset.
+ *
+ * @param string $url       Upload endpoint URL
+ * @param string $token     API token
+ * @param string $filePath  Local file path
+ *
+ * @return int HTTP status code
+ */
+function giteaUploadAsset(string $url, string $token, string $filePath): int
+{
+    $ch = curl_init($url);
+    if ($ch === false) {
+        return 0;
+    }
+    $fileContent = file_get_contents($filePath);
+    if ($fileContent === false) {
+        return 0;
+    }
+    curl_setopt_array($ch, [
+        CURLOPT_POST => true,
+        CURLOPT_HTTPHEADER => [
+            "Authorization: token {$token}",
+            'Content-Type: application/octet-stream',
+        ],
+        CURLOPT_POSTFIELDS => $fileContent,
+        CURLOPT_RETURNTRANSFER => true,
+        CURLOPT_TIMEOUT => 120,
+    ]);
+    curl_exec($ch);
+    $httpCode = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
+    curl_close($ch);
+
+    return $httpCode;
+}
+
+// ── Read platform from .mokogitea/manifest.xml ───────────────────────────────
+
+$detectedPlatform = 'generic';
+$detectedEntryPoint = '';
+$mokoManifest = "{$root}/.mokogitea/manifest.xml";
+if (file_exists($mokoManifest)) {
+    $mokoXml = @simplexml_load_file($mokoManifest);
+    if ($mokoXml !== false) {
+        $rawPlatform = (string)($mokoXml->governance->platform ?? '');
+        if ($rawPlatform !== '') {
+            $detectedPlatform = match ($rawPlatform) {
+                'waas-component' => 'joomla',
+                'crm-module' => 'dolibarr',
+                default => $rawPlatform,
+            };
+        }
+        $detectedEntryPoint = (string)($mokoXml->build->{"entry-point"} ?? '');
+    }
+}
+
+// ── Detect element metadata from manifest XML ────────────────────────────────
+
+$extElement = '';
+$extType = '';
+$extFolder = '';
+$typePrefix = '';
+
+$manifestFiles = array_merge(
+    glob("{$root}/src/pkg_*.xml") ?: [],
+    glob("{$root}/src/*.xml") ?: [],
+    glob("{$root}/*.xml") ?: []
+);
+
+$extManifest = null;
+foreach ($manifestFiles as $file) {
+    $content = file_get_contents($file);
+    if ($content !== false && strpos($content, '<extension') !== false) {
+        $extManifest = $file;
+        break;
+    }
+}
+
+if ($extManifest !== null) {
+    $xml = file_get_contents($extManifest);
+    if ($xml === false) {
+        $xml = '';
+    }
+
+    // Extension type and folder
+    if (preg_match('/type="([^"]*)"/', $xml, $tm)) {
+        $extType = $tm[1];
+    }
+    if (preg_match('/group="([^"]*)"/', $xml, $gm)) {
+        $extFolder = $gm[1];
+    }
+
+    // Element name: <element>, plugin= attribute, <packagename>, or filename
+    if (preg_match('/<element>([^<]+)<\/element>/', $xml, $em)) {
+        $extElement = $em[1];
+    }
+    if ($extElement === '' && preg_match('/plugin="([^"]*)"/', $xml, $pm)) {
+        $extElement = $pm[1];
+    }
+    // For packages: prefer <packagename> over filename
+    if ($extType === 'package' && preg_match('/<packagename>([^<]+)<\/packagename>/', $xml, $pn)) {
+        $extElement = $pn[1];
+    }
+    if ($extElement === '') {
+        $extElement = strtolower(basename($extManifest, '.xml'));
+        if (in_array($extElement, ['templatedetails', 'manifest'], true)) {
+            $extElement = strtolower(str_replace([' ', '-'], '', $repoName !== '' ? $repoName : basename($root)));
+        }
+    }
+}
+
+// Fallback to repo name
+if ($extElement === '') {
+    $extElement = strtolower(str_replace([' ', '-'], '', $repoName !== '' ? $repoName : basename($root)));
+}
+
+// Strip existing type prefix to prevent duplication
+$extElement = (string) preg_replace('/^(pkg_|com_|mod_|plg_[a-z]+_|tpl_|lib_)/', '', $extElement);
+
+// Compute type prefix
+switch ($extType) {
+    case 'plugin':
+        $typePrefix = "plg_{$extFolder}_";
+        break;
+    case 'module':
+        $typePrefix = 'mod_';
+        break;
+    case 'component':
+        $typePrefix = 'com_';
+        break;
+    case 'template':
+        $typePrefix = 'tpl_';
+        break;
+    case 'library':
+        $typePrefix = 'lib_';
+        break;
+    case 'package':
+        $typePrefix = 'pkg_';
+        break;
+}
+
+echo "Element: {$typePrefix}{$extElement}\n";
+echo "Type: {$extType}\n";
+
+// ── Compute filenames ────────────────────────────────────────────────────────
+
+$baseName = "{$typePrefix}{$extElement}-{$version}";
+$zipFile = "{$outputDir}/{$baseName}.zip";
+$tarFile = "{$outputDir}/{$baseName}.tar.gz";
+
+echo "ZIP: {$baseName}.zip\n";
+echo "TAR: {$baseName}.tar.gz\n";
+
+// ── Find source directory ────────────────────────────────────────────────────
+
+$sourceDir = null;
+
+// Use entry-point from manifest.xml if available
+if ($detectedEntryPoint !== '') {
+    $entryDir = rtrim(dirname($detectedEntryPoint) === '.' ? $detectedEntryPoint : dirname($detectedEntryPoint), '/');
+    if (is_dir("{$root}/{$entryDir}")) {
+        $sourceDir = "{$root}/{$entryDir}";
+    }
+}
+
+// Fallback to common directories
+if ($sourceDir === null && is_dir("{$root}/src")) {
+    $sourceDir = "{$root}/src";
+} elseif ($sourceDir === null && is_dir("{$root}/htdocs")) {
+    $sourceDir = "{$root}/htdocs";
+}
+
+if ($sourceDir === null) {
+    echo "No src/ or htdocs/ directory found — skipping package build\n";
+    exit(0);
+}
+
+echo "Source: {$sourceDir}\n";
+
+// ── File exclusion patterns ──────────────────────────────────────────────────
+
+/** @var array<int, string> */
+$excludePatterns = [
+    'sftp-config*',
+    '.ftpignore',
+    '*.ppk',
+    '*.pem',
+    '*.key',
+    '.env*',
+    '*.local',
+    '.build-trigger',
+];
+
+/**
+ * Check if a filename matches any exclusion pattern.
+ *
+ * @param string            $filename Filename to check
+ * @param array<int,string> $patterns Glob patterns to exclude
+ *
+ * @return bool True if the file should be excluded
+ */
+function isExcluded(string $filename, array $patterns): bool
+{
+    $basename = basename($filename);
+    foreach ($patterns as $pattern) {
+        if (fnmatch($pattern, $basename)) {
+            return true;
+        }
+    }
+    return false;
+}
+
+/**
+ * Recursively add files from a directory to a ZipArchive.
+ *
+ * @param ZipArchive        $zip        ZipArchive instance
+ * @param string            $sourceDir  Source directory path
+ * @param string            $prefix     Path prefix inside the archive
+ * @param array<int,string> $excludes   Exclusion patterns
+ */
+function addDirToZip(ZipArchive $zip, string $sourceDir, string $prefix, array $excludes): void
+{
+    $iterator = new RecursiveIteratorIterator(
+        new RecursiveDirectoryIterator($sourceDir, RecursiveDirectoryIterator::SKIP_DOTS),
+        RecursiveIteratorIterator::LEAVES_ONLY
+    );
+
+    foreach ($iterator as $file) {
+        if (!$file instanceof SplFileInfo || !$file->isFile()) {
+            continue;
+        }
+
+        $realPath = $file->getRealPath();
+        if ($realPath === false) {
+            continue;
+        }
+
+        if (isExcluded($file->getFilename(), $excludes)) {
+            continue;
+        }
+
+        $relativePath = substr($realPath, strlen($sourceDir) + 1);
+        // Normalise to forward slashes for ZIP compatibility
+        $relativePath = str_replace('\\', '/', $relativePath);
+        $archivePath = $prefix !== '' ? "{$prefix}/{$relativePath}" : $relativePath;
+        $zip->addFile($realPath, $archivePath);
+    }
+}
+
+// ── Build packages ───────────────────────────────────────────────────────────
+
+$isJoomlaPackage = ($extType === 'package' && is_dir("{$sourceDir}/packages"));
+
+if ($isJoomlaPackage) {
+    // ── Joomla package: ZIP each sub-extension, then combine ─────────────────
+    echo "Building Joomla package (sub-extensions)...\n";
+
+    $zip = new ZipArchive();
+    if ($zip->open($zipFile, ZipArchive::CREATE | ZipArchive::OVERWRITE) !== true) {
+        fwrite(STDERR, "Failed to create ZIP: {$zipFile}\n");
+        exit(1);
+    }
+
+    // ZIP each sub-extension directory
+    $packageDirs = glob("{$sourceDir}/packages/*", GLOB_ONLYDIR) ?: [];
+    foreach ($packageDirs as $pkgDir) {
+        $subName = basename($pkgDir);
+        $subZipPath = "{$outputDir}/{$subName}.zip";
+
+        $subZip = new ZipArchive();
+        if ($subZip->open($subZipPath, ZipArchive::CREATE | ZipArchive::OVERWRITE) !== true) {
+            fwrite(STDERR, "Failed to create sub-package ZIP: {$subZipPath}\n");
+            continue;
+        }
+        addDirToZip($subZip, $pkgDir, '', $excludePatterns);
+        $subZip->close();
+
+        $zip->addFile($subZipPath, "packages/{$subName}.zip");
+        echo "  Sub-package: {$subName}.zip\n";
+    }
+
+    // Copy top-level XML and PHP files into the package root
+    $topLevelFiles = array_merge(
+        glob("{$sourceDir}/*.xml") ?: [],
+        glob("{$sourceDir}/*.php") ?: []
+    );
+    foreach ($topLevelFiles as $tlFile) {
+        if (!isExcluded(basename($tlFile), $excludePatterns)) {
+            $zip->addFile($tlFile, basename($tlFile));
+        }
+    }
+
+    $zip->close();
+    echo "ZIP created: {$zipFile}\n";
+} else {
+    // ── Standard extension: ZIP from source dir ──────────────────────────────
+    echo "Building standard extension ZIP...\n";
+
+    $zip = new ZipArchive();
+    if ($zip->open($zipFile, ZipArchive::CREATE | ZipArchive::OVERWRITE) !== true) {
+        fwrite(STDERR, "Failed to create ZIP: {$zipFile}\n");
+        exit(1);
+    }
+    addDirToZip($zip, $sourceDir, '', $excludePatterns);
+    $zip->close();
+    echo "ZIP created: {$zipFile}\n";
+}
+
+// ── Build tar.gz ─────────────────────────────────────────────────────────────
+
+$tarExcludeArgs = [];
+foreach ($excludePatterns as $pattern) {
+    $tarExcludeArgs[] = '--exclude=' . escapeshellarg($pattern);
+}
+
+$tarCommand = sprintf(
+    'tar -czf %s -C %s %s .',
+    escapeshellarg($tarFile),
+    escapeshellarg($sourceDir),
+    implode(' ', $tarExcludeArgs)
+);
+
+$tarReturnCode = 0;
+$tarOutputLines = [];
+exec($tarCommand . ' 2>&1', $tarOutputLines, $tarReturnCode);
+
+if (!file_exists($tarFile)) {
+    fwrite(STDERR, "Failed to create tar.gz: {$tarFile}\n");
+    if ($tarOutputLines !== []) {
+        fwrite(STDERR, implode("\n", $tarOutputLines) . "\n");
+    }
+    exit(1);
+}
+echo "TAR created: {$tarFile}\n";
+
+// ── Compute SHA-256 checksums ────────────────────────────────────────────────
+
+$zipHash = hash_file('sha256', $zipFile);
+$tarHash = hash_file('sha256', $tarFile);
+
+if ($zipHash === false || $tarHash === false) {
+    fwrite(STDERR, "Failed to compute SHA-256 checksums\n");
+    exit(1);
+}
+
+$zipSha = "{$zipFile}.sha256";
+$tarSha = "{$tarFile}.sha256";
+
+file_put_contents($zipSha, "{$zipHash}  {$baseName}.zip\n");
+file_put_contents($tarSha, "{$tarHash}  {$baseName}.tar.gz\n");
+
+echo "SHA-256 (ZIP): {$zipHash}\n";
+echo "SHA-256 (TAR): {$tarHash}\n";
+
+// ── Get release ID from tag ──────────────────────────────────────────────────
+
+$result = giteaApiRequest("{$apiBase}/releases/tags/{$tag}", $token);
+if ($result['data'] === null || !isset($result['data']['id'])) {
+    fwrite(STDERR, "No release found for tag: {$tag} (HTTP {$result['code']})\n");
+    exit(1);
+}
+
+$releaseId = (int) $result['data']['id'];
+echo "Release ID: {$releaseId} (tag: {$tag})\n";
+
+// ── Delete existing assets with same names ───────────────────────────────────
+
+$assetsResult = giteaApiRequest("{$apiBase}/releases/{$releaseId}/assets", $token);
+$existingAssets = $assetsResult['data'] ?? [];
+
+$uploadNames = [
+    "{$baseName}.zip",
+    "{$baseName}.tar.gz",
+    "{$baseName}.zip.sha256",
+    "{$baseName}.tar.gz.sha256",
+];
+
+foreach ($existingAssets as $asset) {
+    if (!is_array($asset)) {
+        continue;
+    }
+    $assetName = $asset['name'] ?? '';
+    $assetId = $asset['id'] ?? 0;
+    if (in_array($assetName, $uploadNames, true) && $assetId > 0) {
+        giteaApiRequest("{$apiBase}/releases/{$releaseId}/assets/{$assetId}", $token, 'DELETE');
+        echo "Deleted existing asset: {$assetName}\n";
+    }
+}
+
+// ── Upload assets ────────────────────────────────────────────────────────────
+
+$filesToUpload = [
+    "{$baseName}.zip"           => $zipFile,
+    "{$baseName}.tar.gz"        => $tarFile,
+    "{$baseName}.zip.sha256"    => $zipSha,
+    "{$baseName}.tar.gz.sha256" => $tarSha,
+];
+
+$uploaded = 0;
+foreach ($filesToUpload as $name => $localPath) {
+    if (!file_exists($localPath)) {
+        fwrite(STDERR, "File not found, skipping: {$localPath}\n");
+        continue;
+    }
+
+    $uploadUrl = "{$apiBase}/releases/{$releaseId}/assets?name=" . urlencode($name);
+    $httpCode = giteaUploadAsset($uploadUrl, $token, $localPath);
+    $status = ($httpCode >= 200 && $httpCode < 300) ? 'OK' : "FAILED ({$httpCode})";
+    echo "Upload: {$name} — {$status}\n";
+
+    if ($httpCode >= 200 && $httpCode < 300) {
+        $uploaded++;
+    }
+}
+
+// ── Summary ──────────────────────────────────────────────────────────────────
+
+echo "\n";
+echo "Package build complete\n";
+echo "  Element:  {$typePrefix}{$extElement}\n";
+echo "  Version:  {$version}\n";
+echo "  Tag:      {$tag}\n";
+echo "  Uploaded: {$uploaded}/" . count($filesToUpload) . " asset(s)\n";
+
+exit($uploaded === count($filesToUpload) ? 0 : 1);

cli/release_promote.php

@@ -0,0 +1,316 @@
+#!/usr/bin/env php
+<?php
+
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: moko-platform.CLI
+ * INGROUP: moko-platform
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+ * PATH: /cli/release_promote.php
+ * BRIEF: Promote a Gitea release from one channel to another (rename release, tag, assets)
+ *
+ * Usage:
+ *   php release_promote.php --from development --to release-candidate --token TOKEN --api-base URL
+ *   php release_promote.php --from release-candidate --to stable --token TOKEN --api-base URL --path .
+ *
+ * When promoting to stable, --path detects extension type prefix for asset renaming.
+ * When --from is "auto", checks beta > alpha > development and uses the first found.
+ */
+
+declare(strict_types=1);
+
+$from = null;
+$to = null;
+$token = null;
+$apiBase = null;
+$path = '.';
+$branch = 'main';
+
+foreach ($argv as $i => $arg) {
+    if ($arg === '--from' && isset($argv[$i + 1])) {
+        $from = $argv[$i + 1];
+    }
+    if ($arg === '--to' && isset($argv[$i + 1])) {
+        $to = $argv[$i + 1];
+    }
+    if ($arg === '--token' && isset($argv[$i + 1])) {
+        $token = $argv[$i + 1];
+    }
+    if ($arg === '--api-base' && isset($argv[$i + 1])) {
+        $apiBase = $argv[$i + 1];
+    }
+    if ($arg === '--path' && isset($argv[$i + 1])) {
+        $path = $argv[$i + 1];
+    }
+    if ($arg === '--branch' && isset($argv[$i + 1])) {
+        $branch = $argv[$i + 1];
+    }
+}
+
+$token = $token ?: (getenv('GA_TOKEN') ?: (getenv('GITEA_TOKEN') ?: null));
+
+if ($to === null || $token === null || $apiBase === null) {
+    fwrite(STDERR, "Usage: release_promote.php --from <channel|auto> --to <channel> --token TOKEN --api-base URL [--path .]\n");
+    fwrite(STDERR, "  --from auto: checks beta > alpha > development\n");
+    exit(1);
+}
+
+// ── Suffix maps ──────────────────────────────────────────────────────────────
+$suffixMap = [
+    'development'       => '-dev',
+    'alpha'             => '-alpha',
+    'beta'              => '-beta',
+    'release-candidate' => '-rc',
+    'stable'            => '',
+];
+
+// ── Channel hierarchy (highest first) ────────────────────────────────────────
+$channelOrder = ['beta', 'alpha', 'development'];
+
+// ── Helper: Gitea API request ────────────────────────────────────────────────
+/** @return array<string, mixed>|null */
+function giteaApi(string $url, string $token, string $method = 'GET', ?string $body = null): ?array
+{
+    $ch = curl_init($url);
+    curl_setopt_array($ch, [
+        CURLOPT_RETURNTRANSFER => true,
+        CURLOPT_HTTPHEADER => [
+            "Authorization: token {$token}",
+            'Content-Type: application/json',
+        ],
+        CURLOPT_TIMEOUT => 30,
+        CURLOPT_CUSTOMREQUEST => $method,
+    ]);
+    if ($body !== null) {
+        curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
+    }
+    $response = curl_exec($ch);
+    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+    curl_close($ch);
+
+    if ($httpCode < 200 || $httpCode >= 300 || empty($response)) {
+        return null;
+    }
+    return json_decode($response, true) ?: null;
+}
+
+function giteaDownload(string $url, string $token, string $dest): bool
+{
+    $ch = curl_init($url);
+    $fp = fopen($dest, 'wb');
+    curl_setopt_array($ch, [
+        CURLOPT_HTTPHEADER => ["Authorization: token {$token}"],
+        CURLOPT_FILE => $fp,
+        CURLOPT_FOLLOWLOCATION => true,
+        CURLOPT_TIMEOUT => 120,
+    ]);
+    curl_exec($ch);
+    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+    curl_close($ch);
+    fclose($fp);
+    return $httpCode >= 200 && $httpCode < 300;
+}
+
+// ── Resolve --from auto ──────────────────────────────────────────────────────
+if ($from === 'auto') {
+    foreach ($channelOrder as $candidate) {
+        $data = giteaApi("{$apiBase}/releases/tags/{$candidate}", $token);
+        if ($data && !empty($data['id'])) {
+            $from = $candidate;
+            echo "Auto-detected source channel: {$from}\n";
+            break;
+        }
+    }
+    if ($from === 'auto') {
+        echo "No pre-release found to promote\n";
+        exit(0);
+    }
+}
+
+// ── Find source release ──────────────────────────────────────────────────────
+$sourceRelease = giteaApi("{$apiBase}/releases/tags/{$from}", $token);
+if (!$sourceRelease || empty($sourceRelease['id'])) {
+    fwrite(STDERR, "No release found with tag: {$from}\n");
+    exit(1);
+}
+
+$sourceId = $sourceRelease['id'];
+$sourceName = $sourceRelease['name'] ?? '';
+$sourceBody = $sourceRelease['body'] ?? '';
+echo "Source: {$from} (id: {$sourceId}) — {$sourceName}\n";
+
+// ── Get source assets ────────────────────────────────────────────────────────
+$assets = giteaApi("{$apiBase}/releases/{$sourceId}/assets", $token) ?: [];
+echo "Assets: " . count($assets) . " file(s)\n";
+
+// ── Download assets to temp ──────────────────────────────────────────────────
+$tmpDir = sys_get_temp_dir() . '/moko-promote-' . getmypid();
+@mkdir($tmpDir, 0755, true);
+
+foreach ($assets as $asset) {
+    $name = $asset['name'];
+    $downloadUrl = $asset['browser_download_url'];
+    echo "  Downloading: {$name}\n";
+    giteaDownload($downloadUrl, $token, "{$tmpDir}/{$name}");
+}
+
+// ── Detect type prefix for stable promotion ──────────────────────────────────
+$typePrefix = '';
+if ($to === 'stable') {
+    $root = realpath($path) ?: $path;
+    $manifestFiles = array_merge(
+        glob("{$root}/src/pkg_*.xml") ?: [],
+        glob("{$root}/src/*.xml") ?: [],
+        glob("{$root}/*.xml") ?: []
+    );
+    foreach ($manifestFiles as $xmlFile) {
+        $xmlContent = file_get_contents($xmlFile);
+        if (strpos($xmlContent, '<extension') === false) {
+            continue;
+        }
+
+        $extType = '';
+        $extFolder = '';
+        if (preg_match('/type="([^"]*)"/', $xmlContent, $tm)) {
+            $extType = $tm[1];
+        }
+        if (preg_match('/group="([^"]*)"/', $xmlContent, $gm)) {
+            $extFolder = $gm[1];
+        }
+
+        switch ($extType) {
+            case 'plugin':
+                $typePrefix = "plg_{$extFolder}_";
+                break;
+            case 'module':
+                $typePrefix = 'mod_';
+                break;
+            case 'component':
+                $typePrefix = 'com_';
+                break;
+            case 'template':
+                $typePrefix = 'tpl_';
+                break;
+            case 'library':
+                $typePrefix = 'lib_';
+                break;
+            case 'package':
+                $typePrefix = 'pkg_';
+                break;
+        }
+        if ($typePrefix !== '') {
+            break;
+        }
+    }
+}
+
+// ── Rename assets ────────────────────────────────────────────────────────────
+$oldSuffix = $suffixMap[$from] ?? '';
+$newSuffix = $suffixMap[$to] ?? '';
+
+$renamedAssets = [];
+foreach ($assets as $asset) {
+    $oldName = $asset['name'];
+    $newName = $oldName;
+
+    // Strip old suffix
+    if ($oldSuffix !== '') {
+        $newName = str_replace($oldSuffix, '', $newName);
+    }
+
+    // Add type prefix for stable (if not already prefixed)
+    if ($to === 'stable' && $typePrefix !== '' && strpos($newName, $typePrefix) !== 0) {
+        // Strip any existing type prefix to prevent duplication
+        $newName = preg_replace('/^(pkg_|com_|mod_|plg_[a-z]+_|tpl_|lib_)/', '', $newName);
+        $newName = $typePrefix . $newName;
+    }
+
+    // Add new suffix (for non-stable targets)
+    if ($newSuffix !== '' && strpos($newName, $newSuffix) === false) {
+        // Insert before extension
+        $newName = preg_replace('/(\.(zip|tar\.gz|sha256))$/', $newSuffix . '$1', $newName);
+    }
+
+    $renamedAssets[] = ['old' => $oldName, 'new' => $newName];
+    if ($oldName !== $newName) {
+        echo "  Rename: {$oldName} → {$newName}\n";
+    }
+}
+
+// ── Delete source release + tag ──────────────────────────────────────────────
+giteaApi("{$apiBase}/releases/{$sourceId}", $token, 'DELETE');
+giteaApi("{$apiBase}/tags/{$from}", $token, 'DELETE');
+echo "Deleted source: {$from} release + tag\n";
+
+// ── Delete existing target release + tag (if any) ────────────────────────────
+$existingTarget = giteaApi("{$apiBase}/releases/tags/{$to}", $token);
+if ($existingTarget && !empty($existingTarget['id'])) {
+    giteaApi("{$apiBase}/releases/{$existingTarget['id']}", $token, 'DELETE');
+    giteaApi("{$apiBase}/tags/{$to}", $token, 'DELETE');
+    echo "Deleted existing target: {$to} release + tag\n";
+}
+
+// ── Create target release ────────────────────────────────────────────────────
+$isPrerelease = ($to !== 'stable');
+$newName = preg_replace('/\(' . preg_quote($from, '/') . '\)/', "({$to})", $sourceName);
+if ($newName === $sourceName) {
+    $newName = str_ireplace($from, $to, $sourceName);
+}
+
+$newBody = str_ireplace($from, $to, $sourceBody);
+
+$payload = json_encode([
+    'tag_name'         => $to,
+    'target_commitish' => $branch,
+    'name'             => $newName,
+    'body'             => $newBody,
+    'prerelease'       => $isPrerelease,
+]);
+
+$newRelease = giteaApi("{$apiBase}/releases", $token, 'POST', $payload);
+if (!$newRelease || empty($newRelease['id'])) {
+    fwrite(STDERR, "Failed to create {$to} release\n");
+    exit(1);
+}
+
+$newId = $newRelease['id'];
+echo "Created: {$to} release (id: {$newId})\n";
+
+// ── Upload renamed assets ────────────────────────────────────────────────────
+foreach ($renamedAssets as $entry) {
+    $localFile = "{$tmpDir}/{$entry['old']}";
+    if (!file_exists($localFile)) {
+        continue;
+    }
+
+    $uploadName = urlencode($entry['new']);
+    $url = "{$apiBase}/releases/{$newId}/assets?name={$uploadName}";
+
+    $ch = curl_init($url);
+    curl_setopt_array($ch, [
+        CURLOPT_POST => true,
+        CURLOPT_HTTPHEADER => [
+            "Authorization: token {$token}",
+            'Content-Type: application/octet-stream',
+        ],
+        CURLOPT_POSTFIELDS => file_get_contents($localFile),
+        CURLOPT_RETURNTRANSFER => true,
+        CURLOPT_TIMEOUT => 120,
+    ]);
+    curl_exec($ch);
+    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+    curl_close($ch);
+
+    $status = ($code >= 200 && $code < 300) ? 'OK' : "FAILED ({$code})";
+    echo "  Upload: {$entry['new']} — {$status}\n";
+}
+
+// ── Cleanup temp ─────────────────────────────────────────────────────────────
+array_map('unlink', glob("{$tmpDir}/*") ?: []);
+@rmdir($tmpDir);
+
+echo "Promoted: {$from} → {$to}\n";
+exit(0);

cli/release_validate.php

@@ -1,5 +1,6 @@
 #!/usr/bin/env php
 <?php
+
 /* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
  *
  * SPDX-License-Identifier: GPL-3.0-or-later
@@ -26,153 +27,231 @@ declare(strict_types=1);
 
 $path = '.';
 $version = null;
-$platform = 'joomla';
+$platform = null;
 $outputSummary = false;
+$githubOutput = false;
 
 foreach ($argv as $i => $arg) {
-	if ($arg === '--path' && isset($argv[$i + 1])) $path = $argv[$i + 1];
-	if ($arg === '--version' && isset($argv[$i + 1])) $version = $argv[$i + 1];
-	if ($arg === '--platform' && isset($argv[$i + 1])) $platform = $argv[$i + 1];
-	if ($arg === '--output-summary') $outputSummary = true;
+    if ($arg === '--path' && isset($argv[$i + 1])) {
+        $path = $argv[$i + 1];
+    }
+    if ($arg === '--version' && isset($argv[$i + 1])) {
+        $version = $argv[$i + 1];
+    }
+    if ($arg === '--platform' && isset($argv[$i + 1])) {
+        $platform = $argv[$i + 1];
+    }
+    if ($arg === '--output-summary') {
+        $outputSummary = true;
+    }
+    if ($arg === '--github-output') {
+        $githubOutput = true;
+    }
 }
 
 if ($version === null) {
-	fwrite(STDERR, "Usage: release_validate.php --path . --version XX.YY.ZZ [--platform joomla]\n");
-	exit(1);
+    fwrite(STDERR, "Usage: release_validate.php --path . --version XX.YY.ZZ [--platform joomla]\n");
+    exit(1);
 }
 
 $root = realpath($path) ?: $path;
+
+// Auto-detect platform from manifest.xml if not specified
+if ($platform === null) {
+    $manifestXml = "{$root}/.mokogitea/manifest.xml";
+    if (file_exists($manifestXml)) {
+        $mContent = file_get_contents($manifestXml);
+        if (preg_match('/<platform>([^<]+)<\/platform>/', $mContent, $pm)) {
+            $platform = trim($pm[1]);
+        }
+    }
+    // Normalize platform aliases
+    if (in_array($platform, ['waas-component'], true)) {
+        $platform = 'joomla';
+    }
+    if (in_array($platform, ['crm-module'], true)) {
+        $platform = 'dolibarr';
+    }
+    if ($platform === null) {
+        $platform = 'generic';
+    }
+}
+
 $pass = 0;
 $fail = 0;
 $warn = 0;
+/** @var array<int, array{check: string, status: string, details: string}> */
 $results = [];
 
-function addResult(string $check, string $status, string $details): void {
-	global $pass, $fail, $warn, $results;
-	$results[] = ['check' => $check, 'status' => $status, 'details' => $details];
-	if ($status === 'PASS') $pass++;
-	elseif ($status === 'FAIL') $fail++;
-	elseif ($status === 'WARN') $warn++;
+/**
+ * Record a validation result.
+ *
+ * @param string $check Check name
+ * @param string $status PASS, FAIL, or WARN
+ * @param string $details Human-readable details
+ */
+function addResult(string $check, string $status, string $details): void
+{
+    global $pass, $fail, $warn, $results;
+    $results[] = ['check' => $check, 'status' => $status, 'details' => $details];
+    if ($status === 'PASS') {
+        $pass++;
+    } elseif ($status === 'FAIL') {
+        $fail++;
+    } elseif ($status === 'WARN') {
+        $warn++;
+    }
+}
+
+// 0. Source directory check
+$hasSource = is_dir("{$root}/src") || is_dir("{$root}/htdocs");
+if ($hasSource) {
+    addResult('Source directory', 'PASS', 'src/ or htdocs/ found');
+} else {
+    addResult('Source directory', 'WARN', 'No src/ or htdocs/ directory');
 }
 
 // 1. README.md exists and contains VERSION
 if (!file_exists("{$root}/README.md")) {
-	addResult('README.md', 'FAIL', 'Not found');
+    addResult('README.md', 'FAIL', 'Not found');
 } else {
-	$readme = file_get_contents("{$root}/README.md");
-	if (preg_match('/VERSION:\s*' . preg_quote($version, '/') . '/', $readme) ||
-		strpos($readme, $version) !== false) {
-		addResult('README.md version', 'PASS', "`{$version}` found");
-	} else {
-		addResult('README.md version', 'FAIL', "`{$version}` not found in README.md");
-	}
+    $readme = file_get_contents("{$root}/README.md");
+    if (
+        preg_match('/VERSION:\s*' . preg_quote($version, '/') . '/', $readme) ||
+        strpos($readme, $version) !== false
+    ) {
+        addResult('README.md version', 'PASS', "`{$version}` found");
+    } else {
+        addResult('README.md version', 'FAIL', "`{$version}` not found in README.md");
+    }
 }
 
 // 2. CHANGELOG.md exists with matching section
 if (!file_exists("{$root}/CHANGELOG.md")) {
-	addResult('CHANGELOG.md', 'WARN', 'Not found');
+    addResult('CHANGELOG.md', 'WARN', 'Not found');
 } else {
-	$cl = file_get_contents("{$root}/CHANGELOG.md");
-	if (preg_match('/^##\s.*' . preg_quote($version, '/') . '/m', $cl)) {
-		addResult('CHANGELOG.md version', 'PASS', "Section for `{$version}` found");
-	} else {
-		addResult('CHANGELOG.md version', 'WARN', "No section header for `{$version}`");
-	}
+    $cl = file_get_contents("{$root}/CHANGELOG.md");
+    if (preg_match('/^##\s.*' . preg_quote($version, '/') . '/m', $cl)) {
+        addResult('CHANGELOG.md version', 'PASS', "Section for `{$version}` found");
+    } else {
+        addResult('CHANGELOG.md version', 'WARN', "No section header for `{$version}`");
+    }
 }
 
 // 3. LICENSE file exists
 $licenseFound = false;
 foreach (['LICENSE', 'LICENSE.md', 'LICENSE.txt', 'COPYING'] as $lf) {
-	if (file_exists("{$root}/{$lf}")) { $licenseFound = true; break; }
+    if (file_exists("{$root}/{$lf}")) {
+        $licenseFound = true;
+        break;
+    }
 }
 addResult('LICENSE', $licenseFound ? 'PASS' : 'FAIL', $licenseFound ? 'Found' : 'Not found');
 
 // 4. Platform-specific checks
 if ($platform === 'joomla') {
-	// Find XML manifest
-	$manifest = null;
-	$searchDirs = ["{$root}/src", $root];
-	foreach ($searchDirs as $dir) {
-		if (!is_dir($dir)) continue;
-		foreach (glob("{$dir}/*.xml") as $xmlFile) {
-			$content = file_get_contents($xmlFile);
-			if (strpos($content, '<extension') !== false) {
-				$manifest = $xmlFile;
-				break 2;
-			}
-		}
-	}
-	if ($manifest === null) {
-		addResult('XML manifest', 'FAIL', 'No Joomla manifest found');
-	} else {
-		if (preg_match('/<version>([^<]+)<\/version>/', file_get_contents($manifest), $m)) {
-			$mVer = trim($m[1]);
-			if ($mVer === $version) {
-				addResult('Manifest version', 'PASS', "`{$mVer}` matches");
-			} else {
-				addResult('Manifest version', 'FAIL', "`{$mVer}` != `{$version}`");
-			}
-		} else {
-			addResult('Manifest version', 'FAIL', 'No <version> tag in manifest');
-		}
-	}
+    // Find XML manifest
+    $manifest = null;
+    $searchDirs = ["{$root}/src", $root];
+    foreach ($searchDirs as $dir) {
+        if (!is_dir($dir)) {
+            continue;
+        }
+        foreach (glob("{$dir}/*.xml") as $xmlFile) {
+            $content = file_get_contents($xmlFile);
+            if (strpos($content, '<extension') !== false) {
+                $manifest = $xmlFile;
+                break 2;
+            }
+        }
+    }
+    if ($manifest === null) {
+        addResult('XML manifest', 'FAIL', 'No Joomla manifest found');
+    } else {
+        if (preg_match('/<version>([^<]+)<\/version>/', file_get_contents($manifest), $m)) {
+            $mVer = trim($m[1]);
+            if ($mVer === $version) {
+                addResult('Manifest version', 'PASS', "`{$mVer}` matches");
+            } else {
+                addResult('Manifest version', 'FAIL', "`{$mVer}` != `{$version}`");
+            }
+        } else {
+            addResult('Manifest version', 'FAIL', 'No <version> tag in manifest');
+        }
+    }
 
-	// updates.xml
-	if (!file_exists("{$root}/updates.xml")) {
-		addResult('updates.xml', 'WARN', 'Not found');
-	} else {
-		$ux = file_get_contents("{$root}/updates.xml");
-		if (preg_match('/<version>' . preg_quote($version, '/') . '<\/version>/', $ux)) {
-			addResult('updates.xml version', 'PASS', "`{$version}` found");
-		} else {
-			addResult('updates.xml version', 'FAIL', "`{$version}` not in updates.xml");
-		}
-	}
+    // updates.xml
+    if (!file_exists("{$root}/updates.xml")) {
+        addResult('updates.xml', 'WARN', 'Not found');
+    } else {
+        $ux = file_get_contents("{$root}/updates.xml");
+        if (preg_match('/<version>' . preg_quote($version, '/') . '<\/version>/', $ux)) {
+            addResult('updates.xml version', 'PASS', "`{$version}` found");
+        } else {
+            addResult('updates.xml version', 'FAIL', "`{$version}` not in updates.xml");
+        }
+    }
 } elseif ($platform === 'dolibarr') {
-	$modFile = null;
-	foreach (['src', 'htdocs'] as $sd) {
-		$pattern = "{$root}/{$sd}/mod*.class.php";
-		$matches = glob($pattern);
-		if (!empty($matches)) { $modFile = $matches[0]; break; }
-	}
-	if ($modFile === null) {
-		addResult('Dolibarr mod file', 'FAIL', 'No mod*.class.php found');
-	} else {
-		$mc = file_get_contents($modFile);
-		if (preg_match("/\\\$this->version\s*=\s*'" . preg_quote($version, '/') . "'/", $mc)) {
-			addResult('Dolibarr version', 'PASS', "`{$version}` matches");
-		} else {
-			addResult('Dolibarr version', 'FAIL', "`{$version}` not found in " . basename($modFile));
-		}
-	}
+    $modFile = null;
+    foreach (['src', 'htdocs'] as $sd) {
+        $pattern = "{$root}/{$sd}/mod*.class.php";
+        $matches = glob($pattern);
+        if (!empty($matches)) {
+            $modFile = $matches[0];
+            break;
+        }
+    }
+    if ($modFile === null) {
+        addResult('Dolibarr mod file', 'FAIL', 'No mod*.class.php found');
+    } else {
+        $mc = file_get_contents($modFile);
+        if (preg_match("/\\\$this->version\s*=\s*'" . preg_quote($version, '/') . "'/", $mc)) {
+            addResult('Dolibarr version', 'PASS', "`{$version}` matches");
+        } else {
+            addResult('Dolibarr version', 'FAIL', "`{$version}` not found in " . basename($modFile));
+        }
+    }
 }
 
 // 5. composer.json version (if present)
 if (file_exists("{$root}/composer.json")) {
-	$composer = json_decode(file_get_contents("{$root}/composer.json"), true);
-	if (isset($composer['version'])) {
-		if ($composer['version'] === $version) {
-			addResult('composer.json version', 'PASS', "`{$version}` matches");
-		} else {
-			addResult('composer.json version', 'WARN', "`{$composer['version']}` != `{$version}`");
-		}
-	}
+    $composer = json_decode(file_get_contents("{$root}/composer.json"), true);
+    if (isset($composer['version'])) {
+        if ($composer['version'] === $version) {
+            addResult('composer.json version', 'PASS', "`{$version}` matches");
+        } else {
+            addResult('composer.json version', 'WARN', "`{$composer['version']}` != `{$version}`");
+        }
+    }
 }
 
 // Output
 $table = "| Check | Result | Details |\n|-------|--------|--------|\n";
 foreach ($results as $r) {
-	$table .= "| {$r['check']} | {$r['status']} | {$r['details']} |\n";
+    $table .= "| {$r['check']} | {$r['status']} | {$r['details']} |\n";
 }
 $table .= "\n**Validation: {$pass} passed, {$fail} failed, {$warn} warnings**\n";
 
 echo $table;
 
 if ($outputSummary) {
-	$summaryFile = getenv('GITHUB_STEP_SUMMARY');
-	if ($summaryFile) {
-		file_put_contents($summaryFile, "### Pre-Release Validation\n\n{$table}\n", FILE_APPEND);
-	}
+    $summaryFile = getenv('GITHUB_STEP_SUMMARY');
+    if ($summaryFile) {
+        file_put_contents($summaryFile, "## Pre-Release Sanity Checks ({$platform})\n\n{$table}\n", FILE_APPEND);
+    }
+}
+
+if ($githubOutput) {
+    $ghOutput = getenv('GITHUB_OUTPUT');
+    $lines = [
+        "validation_pass={$pass}",
+        "validation_fail={$fail}",
+        "validation_warn={$warn}",
+        "validation_platform={$platform}",
+    ];
+    if ($ghOutput) {
+        file_put_contents($ghOutput, implode("\n", $lines) . "\n", FILE_APPEND);
+    }
 }
 
 exit($fail > 0 ? 1 : 0);

cli/theme_lint.php

@@ -0,0 +1,209 @@
+#!/usr/bin/env php
+<?php
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: moko-platform.CLI
+ * INGROUP: moko-platform
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+ * PATH: /cli/theme_lint.php
+ * BRIEF: Lint theme files — CSS syntax, image sizes, hardcoded URLs
+ *
+ * Usage:
+ *   php theme_lint.php --path /repo
+ *   php theme_lint.php --path /repo --max-image-kb 500
+ *   php theme_lint.php --path /repo --github-output
+ *
+ * Options:
+ *   --path           Repository root (default: .)
+ *   --max-image-kb   Maximum image file size in KB (default: 500)
+ *   --github-output  Export results to $GITHUB_OUTPUT
+ *   --strict         Exit 1 on any warning (default: only on errors)
+ */
+
+declare(strict_types=1);
+
+$path = '.';
+$maxImageKb = 500;
+$ghOutput = false;
+$strict = false;
+
+foreach ($argv as $i => $arg) {
+	if ($arg === '--path' && isset($argv[$i + 1])) $path = $argv[$i + 1];
+	if ($arg === '--max-image-kb' && isset($argv[$i + 1])) $maxImageKb = (int)$argv[$i + 1];
+	if ($arg === '--github-output') $ghOutput = true;
+	if ($arg === '--strict') $strict = true;
+}
+
+$root = realpath($path) ?: $path;
+$errors = 0;
+$warnings = 0;
+
+// ── Find source directory ───────────────────────────────────────────────
+$srcDir = null;
+foreach (['src', 'htdocs'] as $d) {
+	if (is_dir("{$root}/{$d}")) { $srcDir = "{$root}/{$d}"; break; }
+}
+if ($srcDir === null) {
+	fwrite(STDERR, "No src/ or htdocs/ directory in {$root}\n");
+	exit(1);
+}
+
+echo "Theme Lint: {$srcDir}\n\n";
+
+// ── Check 1: CSS syntax validation ──────────────────────────────────────
+echo "--- CSS Syntax ---\n";
+$cssFiles = findFiles($srcDir, '*.css');
+$cssMinFiles = findFiles($srcDir, '*.min.css');
+$cssToCheck = array_diff($cssFiles, $cssMinFiles);
+
+if (empty($cssToCheck)) {
+	echo "  No CSS files to check\n";
+} else {
+	foreach ($cssToCheck as $file) {
+		$content = file_get_contents($file);
+		$relPath = str_replace($root . '/', '', $file);
+
+		// Check for unmatched braces
+		$openBraces = substr_count($content, '{');
+		$closeBraces = substr_count($content, '}');
+		if ($openBraces !== $closeBraces) {
+			echo "  ERROR: {$relPath}: unmatched braces (open={$openBraces}, close={$closeBraces})\n";
+			$errors++;
+		}
+
+		// Check for empty rules
+		if (preg_match_all('/\{[\s]*\}/', $content, $m)) {
+			$count = count($m[0]);
+			echo "  WARN:  {$relPath}: {$count} empty rule(s)\n";
+			$warnings++;
+		}
+
+		// Check for !important abuse (more than 10 in one file)
+		$importantCount = substr_count($content, '!important');
+		if ($importantCount > 10) {
+			echo "  WARN:  {$relPath}: {$importantCount} !important declarations (consider refactoring)\n";
+			$warnings++;
+		}
+	}
+
+	if ($errors === 0) {
+		echo "  OK: " . count($cssToCheck) . " CSS file(s) checked\n";
+	}
+}
+
+// ── Check 2: Image file sizes ───────────────────────────────────────────
+echo "\n--- Image Sizes (max {$maxImageKb}KB) ---\n";
+$imageExts = ['*.jpg', '*.jpeg', '*.png', '*.gif', '*.webp', '*.svg', '*.bmp'];
+$images = [];
+foreach ($imageExts as $ext) {
+	$images = array_merge($images, findFiles($srcDir, $ext));
+}
+// Also check root images/ directory
+if (is_dir("{$root}/images")) {
+	foreach ($imageExts as $ext) {
+		$images = array_merge($images, findFiles("{$root}/images", $ext));
+	}
+}
+
+$oversized = 0;
+$totalSize = 0;
+foreach ($images as $file) {
+	$size = filesize($file);
+	$totalSize += $size;
+	$relPath = str_replace($root . '/', '', $file);
+	$sizeKb = round($size / 1024);
+
+	if ($sizeKb > $maxImageKb) {
+		echo "  WARN:  {$relPath}: {$sizeKb}KB (exceeds {$maxImageKb}KB limit)\n";
+		$oversized++;
+		$warnings++;
+	}
+}
+
+$totalMb = round($totalSize / 1024 / 1024, 1);
+echo "  " . count($images) . " image(s), {$totalMb}MB total";
+if ($oversized > 0) {
+	echo ", {$oversized} oversized";
+}
+echo "\n";
+
+// ── Check 3: Hardcoded URLs in CSS/JS ───────────────────────────────────
+echo "\n--- Hardcoded URLs ---\n";
+$codeFiles = array_merge(
+	findFiles($srcDir, '*.css'),
+	findFiles($srcDir, '*.js')
+);
+// Exclude minified files
+$codeFiles = array_filter($codeFiles, function($f) {
+	return !preg_match('/\.min\.(css|js)$/', $f);
+});
+
+$urlPatterns = [
+	'/https?:\/\/clarksvillefurs\.com/' => 'hardcoded production URL',
+	'/https?:\/\/[a-z]+\.dev\.mokoconsulting\.tech/' => 'hardcoded dev URL',
+	'/https?:\/\/localhost/' => 'localhost reference',
+];
+
+$urlIssues = 0;
+foreach ($codeFiles as $file) {
+	$content = file_get_contents($file);
+	$relPath = str_replace($root . '/', '', $file);
+
+	foreach ($urlPatterns as $pattern => $desc) {
+		if (preg_match_all($pattern, $content, $matches)) {
+			$count = count($matches[0]);
+			echo "  WARN:  {$relPath}: {$count} {$desc}\n";
+			$urlIssues++;
+			$warnings++;
+		}
+	}
+}
+
+if ($urlIssues === 0) {
+	echo "  OK: No hardcoded URLs found\n";
+}
+
+// ── Summary ─────────────────────────────────────────────────────────────
+echo "\n=== Summary ===\n";
+echo "Errors:   {$errors}\n";
+echo "Warnings: {$warnings}\n";
+
+if ($ghOutput) {
+	$ghFile = getenv('GITHUB_OUTPUT');
+	if ($ghFile) {
+		file_put_contents($ghFile, "lint_errors={$errors}\n", FILE_APPEND);
+		file_put_contents($ghFile, "lint_warnings={$warnings}\n", FILE_APPEND);
+		file_put_contents($ghFile, "lint_images=" . count($images) . "\n", FILE_APPEND);
+		file_put_contents($ghFile, "lint_css=" . count($cssToCheck) . "\n", FILE_APPEND);
+	}
+}
+
+if ($errors > 0) {
+	exit(1);
+}
+if ($strict && $warnings > 0) {
+	exit(1);
+}
+exit(0);
+
+// ── Helper: recursively find files matching a glob pattern ──────────────
+function findFiles(string $dir, string $pattern): array
+{
+	$results = [];
+	if (!is_dir($dir)) return $results;
+
+	$iterator = new RecursiveIteratorIterator(
+		new RecursiveDirectoryIterator($dir, RecursiveDirectoryIterator::SKIP_DOTS)
+	);
+
+	foreach ($iterator as $file) {
+		if (fnmatch($pattern, $file->getFilename())) {
+			$results[] = $file->getPathname();
+		}
+	}
+
+	return $results;
+}

cli/updates_xml_build.php

@@ -1,5 +1,6 @@
 #!/usr/bin/env php
 <?php
+
 /* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
  *
  * SPDX-License-Identifier: GPL-3.0-or-later
@@ -42,306 +43,408 @@ $outputFile = null;
 $githubOutput = false;
 
 foreach ($argv as $i => $arg) {
-	if ($arg === '--path' && isset($argv[$i + 1])) $path = $argv[$i + 1];
-	if ($arg === '--version' && isset($argv[$i + 1])) $version = $argv[$i + 1];
-	if ($arg === '--stability' && isset($argv[$i + 1])) $stability = $argv[$i + 1];
-	if ($arg === '--sha' && isset($argv[$i + 1])) $sha = $argv[$i + 1];
-	if ($arg === '--gitea-url' && isset($argv[$i + 1])) $giteaUrl = $argv[$i + 1];
-	if ($arg === '--org' && isset($argv[$i + 1])) $org = $argv[$i + 1];
-	if ($arg === '--repo' && isset($argv[$i + 1])) $repo = $argv[$i + 1];
-	if ($arg === '--output' && isset($argv[$i + 1])) $outputFile = $argv[$i + 1];
-	if ($arg === '--github-output') $githubOutput = true;
+    if ($arg === '--path' && isset($argv[$i + 1])) {
+        $path = $argv[$i + 1];
+    }
+    if ($arg === '--version' && isset($argv[$i + 1])) {
+        $version = $argv[$i + 1];
+    }
+    if ($arg === '--stability' && isset($argv[$i + 1])) {
+        $stability = $argv[$i + 1];
+    }
+    if ($arg === '--sha' && isset($argv[$i + 1])) {
+        $sha = $argv[$i + 1];
+    }
+    if ($arg === '--gitea-url' && isset($argv[$i + 1])) {
+        $giteaUrl = $argv[$i + 1];
+    }
+    if ($arg === '--org' && isset($argv[$i + 1])) {
+        $org = $argv[$i + 1];
+    }
+    if ($arg === '--repo' && isset($argv[$i + 1])) {
+        $repo = $argv[$i + 1];
+    }
+    if ($arg === '--output' && isset($argv[$i + 1])) {
+        $outputFile = $argv[$i + 1];
+    }
+    if ($arg === '--github-output') {
+        $githubOutput = true;
+    }
 }
 
 if ($version === null) {
-	fwrite(STDERR, "Usage: updates_xml_build.php --path . --version XX.YY.ZZ [--stability stable] [--sha SHA]\n");
-	exit(1);
+    fwrite(STDERR, "Usage: updates_xml_build.php --path . --version XX.YY.ZZ [--stability stable] [--sha SHA]\n");
+    exit(1);
 }
 
 $root = realpath($path) ?: $path;
 
+// -- Read platform from .mokogitea/manifest.xml --------------------------------
+$detectedPlatform = 'joomla'; // default for backward compat
+$detectedName = $repo;
+$detectedPackageType = '';
+$mokoManifest = "{$root}/.mokogitea/manifest.xml";
+if (file_exists($mokoManifest)) {
+    $mokoXml = @simplexml_load_file($mokoManifest);
+    if ($mokoXml !== false) {
+        $rawPlatform = (string)($mokoXml->governance->platform ?? '');
+        if ($rawPlatform !== '') {
+            $detectedPlatform = match ($rawPlatform) {
+                'waas-component' => 'joomla',
+                'crm-module' => 'dolibarr',
+                default => $rawPlatform,
+            };
+        }
+        $detectedName = (string)($mokoXml->identity->name ?? $repo);
+        $detectedPackageType = (string)($mokoXml->build->{"package-type"} ?? '');
+    }
+}
+
 // -- Locate Joomla manifest ---------------------------------------------------
 $manifest = null;
 
 // Priority: pkg_*.xml in src/ > any extension XML in src/ > any in root
 $candidates = glob("{$root}/src/pkg_*.xml") ?: [];
 foreach ($candidates as $f) {
-	if (strpos(file_get_contents($f), '<extension') !== false) {
-		$manifest = $f;
-		break;
-	}
+    if (strpos(file_get_contents($f), '<extension') !== false) {
+        $manifest = $f;
+        break;
+    }
 }
 
 if ($manifest === null) {
-	$searchDirs = ["{$root}/src", "{$root}"];
-	foreach ($searchDirs as $dir) {
-		if (!is_dir($dir)) continue;
-		foreach (glob("{$dir}/*.xml") ?: [] as $f) {
-			if (strpos(file_get_contents($f), '<extension') !== false) {
-				$manifest = $f;
-				break 2;
-			}
-		}
-	}
+    $searchDirs = ["{$root}/src", "{$root}"];
+    foreach ($searchDirs as $dir) {
+        if (!is_dir($dir)) {
+            continue;
+        }
+        foreach (glob("{$dir}/*.xml") ?: [] as $f) {
+            if (strpos(file_get_contents($f), '<extension') !== false) {
+                $manifest = $f;
+                break 2;
+            }
+        }
+    }
 }
 
-if ($manifest === null) {
-	fwrite(STDERR, "No Joomla XML manifest found in {$root}\n");
-	exit(1);
+if ($manifest === null && $detectedPlatform === 'joomla') {
+    fwrite(STDERR, "No Joomla XML manifest found in {$root}\n");
+    exit(1);
 }
 
 // -- Parse extension metadata -------------------------------------------------
-$xml = file_get_contents($manifest);
-
-// Extract fields via regex (more portable than SimpleXML for malformed manifests)
 $extName = '';
-if (preg_match('/<name>([^<]+)<\/name>/', $xml, $m)) $extName = $m[1];
-
 $extType = '';
-if (preg_match('/<extension[^>]*type="([^"]+)"/', $xml, $m)) $extType = $m[1];
-
 $extElement = '';
-if (preg_match('/<element>([^<]+)<\/element>/', $xml, $m)) $extElement = $m[1];
-// For packages, prefer <packagename> to avoid pkg_pkg_ duplication
-if (empty($extElement) && preg_match('/<packagename>([^<]+)<\/packagename>/', $xml, $m)) $extElement = $m[1];
-if (empty($extElement) && preg_match('/plugin="([^"]+)"/', $xml, $m)) $extElement = $m[1];
-if (empty($extElement) && preg_match('/module="([^"]+)"/', $xml, $m)) $extElement = $m[1];
-if (empty($extElement)) {
-	$fname = strtolower(pathinfo($manifest, PATHINFO_FILENAME));
-	if (in_array($fname, ['templatedetails', 'manifest'])) {
-		$extElement = strtolower(str_replace([' ', '-'], '', $repo ?: basename($root)));
-	} else {
-		$extElement = $fname;
-	}
-}
-// Strip existing type prefix to prevent duplication (e.g. pkg_mokowaas → mokowaas)
-$extElement = preg_replace('/^(pkg_|com_|mod_|plg_\w+_|tpl_|lib_)/', '', $extElement);
-
 $extClient = '';
-if (preg_match('/<extension[^>]*client="([^"]+)"/', $xml, $m)) $extClient = $m[1];
-
 $extFolder = '';
-if (preg_match('/<extension[^>]*group="([^"]+)"/', $xml, $m)) $extFolder = $m[1];
-
 $targetPlatform = '';
-if (preg_match('/(<targetplatform[^\/]*\/>)/', $xml, $m)) $targetPlatform = $m[1];
-if (empty($targetPlatform)) {
-	$targetPlatform = '<targetplatform name="joomla" version="(5|6)\..*" />';
-}
-
 $phpMinimum = '';
-if (preg_match('/<php_minimum>([^<]+)<\/php_minimum>/', $xml, $m)) $phpMinimum = $m[1];
+
+if ($manifest !== null) {
+    // Joomla manifest found — parse extension metadata from it
+    $xml = file_get_contents($manifest);
+
+    if (preg_match('/<name>([^<]+)<\/name>/', $xml, $m)) {
+        $extName = $m[1];
+    }
+    if (preg_match('/<extension[^>]*type="([^"]+)"/', $xml, $m)) {
+        $extType = $m[1];
+    }
+    if (preg_match('/<element>([^<]+)<\/element>/', $xml, $m)) {
+        $extElement = $m[1];
+    }
+    if (empty($extElement) && preg_match('/<packagename>([^<]+)<\/packagename>/', $xml, $m)) {
+        $extElement = $m[1];
+    }
+    if (empty($extElement) && preg_match('/plugin="([^"]+)"/', $xml, $m)) {
+        $extElement = $m[1];
+    }
+    if (empty($extElement) && preg_match('/module="([^"]+)"/', $xml, $m)) {
+        $extElement = $m[1];
+    }
+    if (empty($extElement)) {
+        $fname = strtolower(pathinfo($manifest, PATHINFO_FILENAME));
+        if (in_array($fname, ['templatedetails', 'manifest'])) {
+            $extElement = strtolower(str_replace([' ', '-'], '', $repo ?: basename($root)));
+        } else {
+            $extElement = $fname;
+        }
+    }
+    $extElement = preg_replace('/^(pkg_|com_|mod_|plg_\w+_|tpl_|lib_)/', '', $extElement);
+
+    if (preg_match('/<extension[^>]*client="([^"]+)"/', $xml, $m)) {
+        $extClient = $m[1];
+    }
+    if (preg_match('/<extension[^>]*group="([^"]+)"/', $xml, $m)) {
+        $extFolder = $m[1];
+    }
+    if (preg_match('/(<targetplatform[^\/]*\/>)/', $xml, $m)) {
+        $targetPlatform = $m[1];
+    }
+    if (empty($targetPlatform)) {
+        $targetPlatform = '<targetplatform name="joomla" version="(5|6)\..*" />';
+    }
+    if (preg_match('/<php_minimum>([^<]+)<\/php_minimum>/', $xml, $m)) {
+        $phpMinimum = $m[1];
+    }
+} else {
+    // Non-Joomla platform — derive metadata from .mokogitea/manifest.xml
+    $extName = $detectedName ?: ($repo ?: basename($root));
+    $extElement = strtolower(str_replace([' ', '-'], '', $extName));
+    $extType = $detectedPackageType ?: 'generic';
+    $targetPlatform = "<targetplatform name=\"{$detectedPlatform}\" version=\".*\" />";
+}
 
 // Resolve language key names (e.g. PLG_SYSTEM_MOKOJOOMTOS)
 if (preg_match('/^[A-Z_]+$/', $extName)) {
-	$iniFiles = [];
-	$iterator = new RecursiveIteratorIterator(
-		new RecursiveDirectoryIterator($root, RecursiveDirectoryIterator::SKIP_DOTS)
-	);
-	foreach ($iterator as $file) {
-		if (preg_match('/\.sys\.ini$/i', $file->getFilename())) {
-			$iniFiles[] = $file->getPathname();
-		}
-	}
-	foreach ($iniFiles as $ini) {
-		$content = file_get_contents($ini);
-		if (preg_match('/^' . preg_quote($extName, '/') . '="([^"]+)"/m', $content, $m)) {
-			$extName = $m[1];
-			break;
-		}
-	}
+    $iniFiles = [];
+    $iterator = new RecursiveIteratorIterator(
+        new RecursiveDirectoryIterator($root, RecursiveDirectoryIterator::SKIP_DOTS)
+    );
+    foreach ($iterator as $file) {
+        if (preg_match('/\.sys\.ini$/i', $file->getFilename())) {
+            $iniFiles[] = $file->getPathname();
+        }
+    }
+    foreach ($iniFiles as $ini) {
+        $content = file_get_contents($ini);
+        if (preg_match('/^' . preg_quote($extName, '/') . '="([^"]+)"/m', $content, $m)) {
+            $extName = $m[1];
+            break;
+        }
+    }
 }
 
 // Fallbacks
-if (empty($extName)) $extName = $repo ?: basename($root);
-if (empty($extType)) $extType = 'component';
+if (empty($extName)) {
+    $extName = $repo ?: basename($root);
+}
+if (empty($extType)) {
+    $extType = 'component';
+}
 
 // -- Build type prefix --------------------------------------------------------
 $typePrefix = '';
 switch ($extType) {
-	case 'plugin':    $typePrefix = "plg_{$extFolder}_"; break;
-	case 'module':    $typePrefix = 'mod_'; break;
-	case 'component': $typePrefix = 'com_'; break;
-	case 'template':  $typePrefix = 'tpl_'; break;
-	case 'library':   $typePrefix = 'lib_'; break;
-	case 'package':   $typePrefix = 'pkg_'; break;
+    case 'plugin':
+        $typePrefix = "plg_{$extFolder}_";
+        break;
+    case 'module':
+        $typePrefix = 'mod_';
+        break;
+    case 'component':
+        $typePrefix = 'com_';
+        break;
+    case 'template':
+        $typePrefix = 'tpl_';
+        break;
+    case 'library':
+        $typePrefix = 'lib_';
+        break;
+    case 'package':
+        $typePrefix = 'pkg_';
+        break;
 }
 
 // -- Export to GITHUB_OUTPUT if requested -------------------------------------
 if ($githubOutput) {
-	$ghOutput = getenv('GITHUB_OUTPUT');
-	$lines = [
-		"ext_element={$extElement}",
-		"ext_name={$extName}",
-		"ext_type={$extType}",
-		"ext_folder={$extFolder}",
-		"type_prefix={$typePrefix}",
-	];
-	if ($ghOutput) {
-		file_put_contents($ghOutput, implode("\n", $lines) . "\n", FILE_APPEND);
-		fwrite(STDERR, "Exported " . count($lines) . " fields to GITHUB_OUTPUT\n");
-	} else {
-		foreach ($lines as $line) echo "{$line}\n";
-	}
+    $ghOutput = getenv('GITHUB_OUTPUT');
+    $lines = [
+        "ext_element={$extElement}",
+        "ext_name={$extName}",
+        "ext_type={$extType}",
+        "ext_folder={$extFolder}",
+        "type_prefix={$typePrefix}",
+    ];
+    if ($ghOutput) {
+        file_put_contents($ghOutput, implode("\n", $lines) . "\n", FILE_APPEND);
+        fwrite(STDERR, "Exported " . count($lines) . " fields to GITHUB_OUTPUT\n");
+    } else {
+        foreach ($lines as $line) {
+            echo "{$line}\n";
+        }
+    }
 }
 
 // -- Stability suffix map -----------------------------------------------------
 $stabilitySuffixMap = [
-	'stable'      => '',
-	'rc'          => '-rc',
-	'beta'        => '-beta',
-	'alpha'       => '-alpha',
-	'development' => '-dev',
+    'stable'      => '',
+    'rc'          => '-rc',
+    'beta'        => '-beta',
+    'alpha'       => '-alpha',
+    'development' => '-dev',
 ];
 
+// Joomla <tags><tag> values — maps to Joomla's stabilityTagToInteger()
 $stabilityTagMap = [
-	'stable'      => 'stable',
-	'rc'          => 'rc',
-	'beta'        => 'beta',
-	'alpha'       => 'alpha',
-	'development' => 'development',
+    'stable'      => 'stable',
+    'rc'          => 'rc',
+    'beta'        => 'beta',
+    'alpha'       => 'alpha',
+    'development' => 'dev',
+];
+
+// Gitea release tag names (used in download/info URLs)
+$releaseTagMap = [
+    'stable'      => 'stable',
+    'rc'          => 'release-candidate',
+    'beta'        => 'beta',
+    'alpha'       => 'alpha',
+    'development' => 'development',
 ];
 
 // -- Build update entries -----------------------------------------------------
-$releaseTag = $stabilityTagMap[$stability] ?? $stability;
-
 // For the primary entry: apply suffix if not stable
 $primarySuffix = $stabilitySuffixMap[$stability] ?? '';
 $primaryVersion = $version . $primarySuffix;
 
-$downloadUrl = "{$giteaUrl}/{$org}/{$repo}/releases/download/{$releaseTag}/{$typePrefix}{$extElement}-{$primaryVersion}.zip";
-$infoUrl = "{$giteaUrl}/{$org}/{$repo}/releases/tag/{$releaseTag}";
-
-// Build client tag
+// Build client tag — Joomla requires <client>site</client> to match updates
+// to installed extensions. Without it, extension_id=0 in #__updates.
 $clientTag = '';
 if (!empty($extClient)) {
-	$clientTag = "    <client>{$extClient}</client>";
-} elseif ($extType === 'module' || $extType === 'plugin') {
-	$clientTag = '    <client>site</client>';
+    $clientTag = "    <client>{$extClient}</client>";
+} else {
+    $clientTag = '    <client>site</client>';
 }
 
 // Build folder tag
 $folderTag = '';
 if (!empty($extFolder) && $extType === 'plugin') {
-	$folderTag = "    <folder>{$extFolder}</folder>";
+    $folderTag = "    <folder>{$extFolder}</folder>";
 }
 
 // PHP minimum tag
 $phpTag = '';
 if (!empty($phpMinimum)) {
-	$phpTag = "    <php_minimum>{$phpMinimum}</php_minimum>";
+    $phpTag = "    <php_minimum>{$phpMinimum}</php_minimum>";
 }
 
 // SHA tag
 $shaTag = '';
 if (!empty($sha)) {
-	$shaTag = "    <sha256>{$sha}</sha256>";
+    $shaTag = "    <sha256>{$sha}</sha256>";
 }
 
 /**
  * Build a single <update> entry for a given stability tag
  */
 function buildEntry(
-	string $tagName,
-	string $entryVersion,
-	string $entryDownloadUrl,
-	string $extName,
-	string $extElement,
-	string $extType,
-	string $clientTag,
-	string $folderTag,
-	string $infoUrl,
-	string $targetPlatform,
-	string $phpTag,
-	string $shaTag
+    string $tagName,
+    string $entryVersion,
+    string $entryDownloadUrl,
+    string $extName,
+    string $extElement,
+    string $extType,
+    string $clientTag,
+    string $folderTag,
+    string $infoUrl,
+    string $targetPlatform,
+    string $phpTag,
+    string $shaTag
 ): string {
-	$lines = [];
-	$lines[] = '  <update>';
-	$lines[] = "    <name>{$extName}</name>";
-	$lines[] = "    <description>{$extName} update</description>";
-	// Element in updates.xml must match what Joomla stores in #__extensions
-	// For packages: pkg_elementname. For plugins: elementname (folder handles grouping).
-	$dbElement = ($extType === 'package') ? "pkg_{$extElement}" : $extElement;
-	$lines[] = "    <element>{$dbElement}</element>";
-	$lines[] = "    <type>{$extType}</type>";
-	$lines[] = "    <version>{$entryVersion}</version>";
-	if (!empty($clientTag)) $lines[] = $clientTag;
-	if (!empty($folderTag)) $lines[] = $folderTag;
-	$lines[] = "    <tags><tag>{$tagName}</tag></tags>";
-	$lines[] = "    <infourl title=\"{$extName}\">{$infoUrl}</infourl>";
-	$lines[] = '    <downloads>';
-	$lines[] = "      <downloadurl type=\"full\" format=\"zip\">{$entryDownloadUrl}</downloadurl>";
-	$lines[] = '    </downloads>';
-	if (!empty($shaTag)) $lines[] = $shaTag;
-	$lines[] = "    {$targetPlatform}";
-	if (!empty($phpTag)) $lines[] = $phpTag;
-	$lines[] = '    <maintainer>Moko Consulting</maintainer>';
-	$lines[] = '    <maintainerurl>https://mokoconsulting.tech</maintainerurl>';
-	$lines[] = '  </update>';
-	return implode("\n", $lines);
+    $lines = [];
+    $lines[] = '  <update>';
+    $lines[] = "    <name>{$extName}</name>";
+    $lines[] = "    <description>{$extName} update</description>";
+    // Element in updates.xml must match what Joomla stores in #__extensions
+    // For packages: pkg_elementname. For plugins: elementname (folder handles grouping).
+    $dbElement = ($extType === 'package') ? "pkg_{$extElement}" : $extElement;
+    $lines[] = "    <element>{$dbElement}</element>";
+    $lines[] = "    <type>{$extType}</type>";
+    $lines[] = "    <version>{$entryVersion}</version>";
+    if (!empty($clientTag)) {
+        $lines[] = $clientTag;
+    }
+    if (!empty($folderTag)) {
+        $lines[] = $folderTag;
+    }
+    $lines[] = "    <tags><tag>{$tagName}</tag></tags>";
+    $lines[] = "    <infourl title=\"{$extName}\">{$infoUrl}</infourl>";
+    $lines[] = '    <downloads>';
+    $lines[] = "      <downloadurl type=\"full\" format=\"zip\">{$entryDownloadUrl}</downloadurl>";
+    $lines[] = '    </downloads>';
+    if (!empty($shaTag)) {
+        $lines[] = $shaTag;
+    }
+    $lines[] = "    {$targetPlatform}";
+    if (!empty($phpTag)) {
+        $lines[] = $phpTag;
+    }
+    $lines[] = '    <maintainer>Moko Consulting</maintainer>';
+    $lines[] = '    <maintainerurl>https://mokoconsulting.tech</maintainerurl>';
+    $lines[] = '  </update>';
+    return implode("\n", $lines);
 }
 
 // -- Determine which channels to write ----------------------------------------
-// Stable cascades to all channels; pre-releases only write their level and below
-// Each channel gets its own suffixed version:
-//   development -> 04.01.00-dev
-//   alpha       -> 04.01.00-alpha
-//   beta        -> 04.01.00-beta
-//   rc          -> 04.01.00-rc
-//   stable      -> 04.01.00
+// Stable cascades to all channels; pre-releases cascade down to lower channels.
+// Each channel entry represents "latest release available at this stability or higher".
+// When stable releases, ALL channels point to stable (it's the newest for everyone).
+// When RC releases, rc/beta/alpha/dev point to RC; stable is preserved.
+// When dev releases, only dev is updated; everything else is preserved.
 $allChannels = ['development', 'alpha', 'beta', 'rc', 'stable'];
 $stabilityIndex = array_search($stability === 'development' ? 'development' : $stability, $allChannels);
-if ($stabilityIndex === false) $stabilityIndex = 4; // default to stable
+if ($stabilityIndex === false) {
+    $stabilityIndex = 4; // default to stable
+}
 
-// Write only the current channel entry (not cascade)
-// Each channel release only creates its own entry; preserved entries handle other channels
+// Write entries for the current channel AND all lower channels (cascade down)
+// All cascaded entries point to the CURRENT release (the highest stability being built)
 $entries = [];
-$channelName = $allChannels[$stabilityIndex];
-$channelSuffix = $stabilitySuffixMap[$channelName] ?? '';
-$channelVersion = $version . $channelSuffix;
-$channelTag = $stabilityTagMap[$channelName] ?? $channelName;
-$channelDownloadUrl = "{$giteaUrl}/{$org}/{$repo}/releases/download/{$channelTag}/{$typePrefix}{$extElement}-{$channelVersion}.zip";
-$channelInfoUrl = "{$giteaUrl}/{$org}/{$repo}/releases/tag/{$channelTag}";
+$giteaTag = $releaseTagMap[$stability] ?? $stability;
+$channelVersion = $version . ($stabilitySuffixMap[$stability] ?? '');
+$channelDownloadUrl = "{$giteaUrl}/{$org}/{$repo}/releases/download/{$giteaTag}/{$typePrefix}{$extElement}-{$channelVersion}.zip";
+$channelInfoUrl = "{$giteaUrl}/{$org}/{$repo}/releases/tag/{$giteaTag}";
 
-$entries[] = buildEntry(
-	$channelName,
-	$channelVersion,
-	$channelDownloadUrl,
-	$extName,
-	$extElement,
-	$extType,
-	$clientTag,
-	$folderTag,
-	$channelInfoUrl,
-	$targetPlatform,
-	$phpTag,
-	$shaTag
-);
+for ($i = 0; $i <= $stabilityIndex; $i++) {
+    $channelName = $allChannels[$i];
+    $joomlaTag = $stabilityTagMap[$channelName] ?? $channelName;
+    // Only attach SHA to the primary channel entry
+    $entrySha = ($i === $stabilityIndex) ? $shaTag : '';
+
+    $entries[] = buildEntry(
+        $joomlaTag,
+        $channelVersion,
+        $channelDownloadUrl,
+        $extName,
+        $extElement,
+        $extType,
+        $clientTag,
+        $folderTag,
+        $channelInfoUrl,
+        $targetPlatform,
+        $phpTag,
+        $entrySha
+    );
+}
 
 // -- Preserve existing entries for channels not being updated -----------------
 $dest = $outputFile ?? "{$root}/updates.xml";
 $preservedEntries = [];
 
 if (file_exists($dest)) {
-	$existingXml = @simplexml_load_file($dest);
-	if ($existingXml) {
-		// Channels we're writing — don't preserve these
-		$writtenChannels = [];
-		for ($i = 0; $i <= $stabilityIndex; $i++) {
-			$writtenChannels[] = $allChannels[$i];
-		}
+    $existingXml = @simplexml_load_file($dest);
+    if ($existingXml) {
+        // Joomla tags we're writing — don't preserve these
+        $writtenChannels = [];
+        for ($i = 0; $i <= $stabilityIndex; $i++) {
+            $writtenChannels[] = $stabilityTagMap[$allChannels[$i]] ?? $allChannels[$i];
+        }
+        // Also match legacy/alternate tag names (e.g. 'development' = 'dev')
+        $writtenChannels[] = 'development'; // alias for 'dev'
 
-		foreach ($existingXml->update as $existingUpdate) {
-			$existingTag = '';
-			if (isset($existingUpdate->tags->tag)) {
-				$existingTag = (string) $existingUpdate->tags->tag;
-			}
-			// Keep entries for channels we're NOT overwriting
-			if (!empty($existingTag) && !in_array($existingTag, $writtenChannels, true)) {
-				$preservedEntries[] = '  ' . trim($existingUpdate->asXML());
-			}
-		}
-	}
+        foreach ($existingXml->update as $existingUpdate) {
+            $existingTag = '';
+            if (isset($existingUpdate->tags->tag)) {
+                $existingTag = (string) $existingUpdate->tags->tag;
+            }
+            // Keep entries for channels we're NOT overwriting
+            if (!empty($existingTag) && !in_array($existingTag, $writtenChannels, true)) {
+                $preservedEntries[] = '  ' . trim($existingUpdate->asXML());
+            }
+        }
+    }
 }
 
 // -- Write updates.xml --------------------------------------------------------

cli/version_bump.php

@@ -9,7 +9,7 @@
  * INGROUP: moko-platform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
  * PATH: /cli/version_bump.php
- * BRIEF: Auto-increment patch version — checks both README.md and manifest XML, uses the higher version as base
+ * BRIEF: Auto-increment version — manifest.xml is canonical, cascades to all XML and MD files
  */
 
 declare(strict_types=1);
@@ -24,7 +24,18 @@ foreach ($argv as $i => $arg) {
 
 $root = realpath($path) ?: $path;
 
-// ── Read version from README.md ──────────────────────────────────────────────
+// -- 1. Read version from .mokogitea/manifest.xml (canonical) --
+$mokoVersion = null;
+$mokoManifest = "{$root}/.mokogitea/manifest.xml";
+$mokoContent = '';
+if (file_exists($mokoManifest)) {
+    $mokoContent = file_get_contents($mokoManifest);
+    if (preg_match('|<version>(\d{2}\.\d{2}\.\d{2})</version>|', $mokoContent, $m)) {
+        $mokoVersion = $m[1];
+    }
+}
+
+// -- 2. Fallback: README.md --
 $readmeVersion = null;
 $readme = "{$root}/README.md";
 $readmeContent = '';
@@ -35,10 +46,8 @@ if (file_exists($readme)) {
     }
 }
 
-// ── Read version from Joomla manifest XML ────────────────────────────────────
+// -- 3. Fallback: Joomla manifest XML --
 $manifestVersion = null;
-
-// Check package manifest first (pkg_*.xml), then sub-extension manifests
 $manifestFiles = array_merge(
     glob("{$root}/src/pkg_*.xml") ?: [],
     glob("{$root}/src/*.xml") ?: [],
@@ -60,23 +69,21 @@ foreach ($manifestFiles as $xmlFile) {
     }
 }
 
-// ── Use the higher version as base ───────────────────────────────────────────
+// -- Use the highest version as base --
 $baseVersion = null;
-
-if ($readmeVersion !== null && $manifestVersion !== null) {
-    $baseVersion = version_compare($manifestVersion, $readmeVersion, '>') ? $manifestVersion : $readmeVersion;
-} elseif ($manifestVersion !== null) {
-    $baseVersion = $manifestVersion;
-} elseif ($readmeVersion !== null) {
-    $baseVersion = $readmeVersion;
+$candidates = array_filter([$mokoVersion, $readmeVersion, $manifestVersion]);
+foreach ($candidates as $v) {
+    if ($baseVersion === null || version_compare($v, $baseVersion, '>')) {
+        $baseVersion = $v;
+    }
 }
 
 if ($baseVersion === null) {
-    fwrite(STDERR, "No version found in README.md or manifest XML\n");
+    fwrite(STDERR, "No version found in manifest.xml, README.md, or Joomla XML\n");
     exit(1);
 }
 
-// ── Parse and bump ───────────────────────────────────────────────────────────
+// -- Parse and bump --
 if (!preg_match('/^(\d{2})\.(\d{2})\.(\d{2})$/', $baseVersion, $parts)) {
     fwrite(STDERR, "Invalid version format: {$baseVersion}\n");
     exit(1);
@@ -99,7 +106,18 @@ switch ($type) {
 
 $new = sprintf('%02d.%02d.%02d', $major, $minor, $patch);
 
-// ── Update README.md ─────────────────────────────────────────────────────────
+// -- Update .mokogitea/manifest.xml (canonical target) --
+if (file_exists($mokoManifest) && !empty($mokoContent)) {
+    $updated = preg_replace(
+        '|<version>\d{2}\.\d{2}\.\d{2}</version>|',
+        "<version>{$new}</version>",
+        $mokoContent,
+        1
+    );
+    file_put_contents($mokoManifest, $updated);
+}
+
+// -- Update README.md --
 if (file_exists($readme) && !empty($readmeContent)) {
     $updated = preg_replace(
         '/(VERSION:\s*)\d{2}\.\d{2}\.\d{2}/m',
@@ -110,5 +128,37 @@ if (file_exists($readme) && !empty($readmeContent)) {
     file_put_contents($readme, $updated);
 }
 
-echo "{$old} → {$new}\n";
+// -- Cascade to ALL Joomla extension XML manifests --
+$xmlPatterns = [
+    "{$root}/src/pkg_*.xml",
+    "{$root}/src/*.xml",
+    "{$root}/src/packages/*/*.xml",
+    "{$root}/*.xml",
+];
+
+$updatedFiles = [];
+foreach ($xmlPatterns as $pattern) {
+    foreach (glob($pattern) ?: [] as $xmlFile) {
+        $content = file_get_contents($xmlFile);
+        // Only update files that have an <extension> tag (Joomla manifests)
+        if (strpos($content, '<extension') === false) {
+            continue;
+        }
+        $newContent = preg_replace(
+            '|<version>\d{2}\.\d{2}\.\d{2}(?:-[a-z]+)?</version>|',
+            "<version>{$new}</version>",
+            $content
+        );
+        if ($newContent !== $content) {
+            file_put_contents($xmlFile, $newContent);
+            $updatedFiles[] = substr($xmlFile, strlen($root) + 1);
+        }
+    }
+}
+
+if (!empty($updatedFiles)) {
+    fwrite(STDERR, "Updated " . count($updatedFiles) . " Joomla manifest(s): " . implode(', ', $updatedFiles) . "\n");
+}
+
+echo "{$old} -> {$new}\n";
 exit(0);

cli/version_check.php

@@ -0,0 +1,138 @@
+#!/usr/bin/env php
+<?php
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: moko-platform.CLI
+ * INGROUP: moko-platform
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+ * PATH: /cli/version_check.php
+ * VERSION: 05.00.00
+ * BRIEF: Validate version consistency across README, manifests, and sub-packages
+ *
+ * Usage:
+ *   php version_check.php --path /repo
+ *   php version_check.php --path /repo --strict    # exit 1 on mismatch
+ *   php version_check.php --path /repo --fix       # fix mismatches to highest version
+ */
+
+declare(strict_types=1);
+
+$path   = '.';
+$strict = false;
+$fix    = false;
+
+foreach ($argv as $i => $arg) {
+    if ($arg === '--path' && isset($argv[$i + 1])) $path = $argv[$i + 1];
+    if ($arg === '--strict') $strict = true;
+    if ($arg === '--fix')    $fix = true;
+}
+
+$root = realpath($path) ?: $path;
+$errors = 0;
+$versions = [];
+
+// ── Read README.md version ───────────────────────────────────────────────────
+$readme = "{$root}/README.md";
+if (file_exists($readme)) {
+    $content = file_get_contents($readme);
+    if (preg_match('/VERSION:\s*(\d{2}\.\d{2}\.\d{2})/m', $content, $m)) {
+        $versions['README.md'] = $m[1];
+    }
+}
+
+// ── Read manifest XML versions ───────────────────────────────────────────────
+$xmlGlobs = [
+    "{$root}/src/pkg_*.xml",
+    "{$root}/src/*.xml",
+    "{$root}/src/packages/*/*.xml",
+    "{$root}/*.xml",
+];
+
+foreach ($xmlGlobs as $glob) {
+    foreach (glob($glob) ?: [] as $file) {
+        // Skip updates.xml
+        if (basename($file) === 'updates.xml') continue;
+
+        $xmlContent = file_get_contents($file);
+        if (strpos($xmlContent, '<extension') === false) continue;
+
+        if (preg_match('|<version>(\d{2}\.\d{2}\.\d{2})(?:-[a-z]+)?</version>|', $xmlContent, $xm)) {
+            $relPath = str_replace($root . '/', '', $file);
+            $relPath = str_replace($root . '\\', '', $relPath);
+            $versions[$relPath] = $xm[1];
+        }
+    }
+}
+
+if (empty($versions)) {
+    fwrite(STDERR, "No version sources found\n");
+    exit(1);
+}
+
+// ── Compare versions ─────────────────────────────────────────────────────────
+$uniqueVersions = array_unique(array_values($versions));
+$highestVersion = '00.00.00';
+foreach ($versions as $v) {
+    if (version_compare($v, $highestVersion, '>')) {
+        $highestVersion = $v;
+    }
+}
+
+echo "=== Version Consistency Check ===\n";
+foreach ($versions as $source => $ver) {
+    $status = ($ver === $highestVersion) ? 'OK' : 'MISMATCH';
+    if ($status === 'MISMATCH') $errors++;
+    echo sprintf("  %-50s %s  %s\n", $source, $ver, $status === 'OK' ? '' : "** MISMATCH (expected {$highestVersion})");
+}
+
+if (count($uniqueVersions) === 1) {
+    echo "\nAll {$ver} — consistent.\n";
+} else {
+    echo "\n** {$errors} mismatch(es) found. Highest version: {$highestVersion}\n";
+
+    if ($fix) {
+        echo "\n=== Fixing mismatches to {$highestVersion} ===\n";
+
+        // Fix README.md
+        if (isset($versions['README.md']) && $versions['README.md'] !== $highestVersion) {
+            $content = file_get_contents($readme);
+            $content = preg_replace(
+                '/(VERSION:\s*)\d{2}\.\d{2}\.\d{2}/m',
+                '${1}' . $highestVersion,
+                $content,
+                1
+            );
+            file_put_contents($readme, $content);
+            echo "  Fixed: README.md -> {$highestVersion}\n";
+        }
+
+        // Fix XML manifests
+        foreach ($versions as $source => $ver) {
+            if ($source === 'README.md') continue;
+            if ($ver === $highestVersion) continue;
+
+            $file = "{$root}/{$source}";
+            if (!file_exists($file)) continue;
+
+            $content = file_get_contents($file);
+            $content = preg_replace(
+                '|<version>[^<]*</version>|',
+                "<version>{$highestVersion}</version>",
+                $content
+            );
+            file_put_contents($file, $content);
+            echo "  Fixed: {$source} -> {$highestVersion}\n";
+        }
+
+        echo "Done.\n";
+    }
+}
+
+if ($strict && $errors > 0) {
+    exit(1);
+}
+
+exit(0);

cli/version_read.php

@@ -9,7 +9,7 @@
  * INGROUP: moko-platform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
  * PATH: /cli/version_read.php
- * BRIEF: Read version from README.md or manifest XML — outputs the higher of the two
+ * BRIEF: Read version — manifest.xml is canonical, falls back to README.md and Joomla XML
  */
 
 declare(strict_types=1);
@@ -23,7 +23,26 @@ foreach ($argv as $i => $arg) {
 
 $root = realpath($path) ?: $path;
 
-// ── Read from README.md ──────────────────────────────────────────────────────
+// -- 1. Read from .mokogitea/manifest.xml (canonical source) --
+$mokoVersion = null;
+$mokoManifest = "{$root}/.mokogitea/manifest.xml";
+if (file_exists($mokoManifest)) {
+    $xml = @simplexml_load_file($mokoManifest);
+    if ($xml !== false) {
+        $v = (string)($xml->identity->version ?? '');
+        if (preg_match('/^\d{2}\.\d{2}\.\d{2}$/', $v)) {
+            $mokoVersion = $v;
+        }
+    }
+}
+
+// If manifest.xml has a version, that is authoritative
+if ($mokoVersion !== null) {
+    echo $mokoVersion . "\n";
+    exit(0);
+}
+
+// -- 2. Fallback: README.md --
 $readmeVersion = null;
 $readme = "{$root}/README.md";
 if (file_exists($readme)) {
@@ -33,7 +52,7 @@ if (file_exists($readme)) {
     }
 }
 
-// ── Read from Joomla manifest XML ────────────────────────────────────────────
+// -- 3. Fallback: Joomla manifest XML --
 $manifestVersion = null;
 $manifestFiles = array_merge(
     glob("{$root}/src/pkg_*.xml") ?: [],
@@ -55,7 +74,7 @@ foreach ($manifestFiles as $xmlFile) {
     }
 }
 
-// ── Output the higher version ────────────────────────────────────────────────
+// -- Output the higher version --
 $version = null;
 if ($readmeVersion !== null && $manifestVersion !== null) {
     $version = version_compare($manifestVersion, $readmeVersion, '>') ? $manifestVersion : $readmeVersion;
@@ -66,9 +85,33 @@ if ($readmeVersion !== null && $manifestVersion !== null) {
 }
 
 if ($version === null) {
-    fwrite(STDERR, "No version found in README.md or manifest XML\n");
+    fwrite(STDERR, "No version found in manifest.xml, README.md, or Joomla XML\n");
     exit(1);
 }
 
+// -- Backfill: if manifest.xml exists but lacks <version>, insert it --
+if ($mokoVersion === null && file_exists($mokoManifest)) {
+    $content = file_get_contents($mokoManifest);
+    if (!preg_match('|<version>\d{2}\.\d{2}\.\d{2}</version>|', $content)) {
+        if (strpos($content, '<license') !== false) {
+            $content = preg_replace(
+                '|(\s*<license)|',
+                "\n    <version>{$version}</version>\$1",
+                $content,
+                1
+            );
+        } elseif (strpos($content, '</identity>') !== false) {
+            $content = preg_replace(
+                '|(</identity>)|',
+                "    <version>{$version}</version>\n  \$1",
+                $content,
+                1
+            );
+        }
+        file_put_contents($mokoManifest, $content);
+        fwrite(STDERR, "Backfilled manifest.xml with version {$version}\n");
+    }
+}
+
 echo $version . "\n";
 exit(0);

cli/version_reset_dev.php

@@ -0,0 +1,319 @@
+#!/usr/bin/env php
+<?php
+
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: moko-platform.CLI
+ * INGROUP: moko-platform
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+ * PATH: /cli/version_reset_dev.php
+ * BRIEF: Reset platform version to 'development' on a branch via Gitea API
+ *
+ * Usage:
+ *   php version_reset_dev.php --token TOKEN --api-base URL
+ *   php version_reset_dev.php --token TOKEN --api-base URL --branch dev
+ *   php version_reset_dev.php --token TOKEN --api-base URL --platform dolibarr
+ *   php version_reset_dev.php --token TOKEN --api-base URL --path /repo/root
+ *
+ * This replaces the inline curl+python3+sed block previously used in
+ * auto-release.yml to reset Dolibarr's $this->version on the dev branch
+ * after a stable release.
+ */
+
+declare(strict_types=1);
+
+// ── Argument parsing ─────────────────────────────────────────────────────────
+
+$token = null;
+$apiBase = null;
+$branch = 'dev';
+$platform = null;
+$path = null;
+
+foreach ($argv as $i => $arg) {
+    if ($arg === '--token' && isset($argv[$i + 1])) {
+        $token = $argv[$i + 1];
+    }
+    if ($arg === '--api-base' && isset($argv[$i + 1])) {
+        $apiBase = rtrim($argv[$i + 1], '/');
+    }
+    if ($arg === '--branch' && isset($argv[$i + 1])) {
+        $branch = $argv[$i + 1];
+    }
+    if ($arg === '--platform' && isset($argv[$i + 1])) {
+        $platform = $argv[$i + 1];
+    }
+    if ($arg === '--path' && isset($argv[$i + 1])) {
+        $path = $argv[$i + 1];
+    }
+    if ($arg === '--help' || $arg === '-h') {
+        printUsage();
+        exit(0);
+    }
+}
+
+// Allow token from environment
+if ($token === null) {
+    $envToken = getenv('GA_TOKEN');
+    if ($envToken !== false && $envToken !== '') {
+        $token = $envToken;
+    }
+}
+if ($token === null) {
+    $envToken = getenv('GITEA_TOKEN');
+    if ($envToken !== false && $envToken !== '') {
+        $token = $envToken;
+    }
+}
+
+if ($token === null || $apiBase === null) {
+    fwrite(STDERR, "Error: --token and --api-base are required.\n\n");
+    printUsage();
+    exit(1);
+}
+
+// ── Platform detection ───────────────────────────────────────────────────────
+
+if ($platform === null && $path !== null) {
+    $platform = detectPlatform($path);
+    if ($platform !== null) {
+        echo "Detected platform: {$platform}\n";
+    }
+}
+
+if ($platform === null) {
+    fwrite(STDERR, "Error: could not determine platform. Use --platform or --path.\n");
+    exit(1);
+}
+
+// ── Dispatch by platform ─────────────────────────────────────────────────────
+
+$changed = 0;
+
+if (in_array($platform, ['dolibarr', 'crm-module'], true)) {
+    $changed = resetDolibarrVersion($apiBase, $token, $branch);
+} elseif (in_array($platform, ['joomla', 'waas-component'], true)) {
+    echo "Joomla version reset is not yet implemented — skipping.\n";
+} else {
+    echo "Platform '{$platform}' has no version-reset logic — skipping.\n";
+}
+
+echo "Reset {$changed} file(s) to 'development' on branch '{$branch}'.\n";
+exit(0);
+
+// ══════════════════════════════════════════════════════════════════════════════
+// Helper functions
+// ══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Print usage information to stdout.
+ *
+ * @return void
+ */
+function printUsage(): void
+{
+    echo <<<'USAGE'
+    Reset platform version to 'development' on a branch via Gitea API.
+
+    Usage:
+      php version_reset_dev.php --token TOKEN --api-base URL [options]
+
+    Required:
+      --token TOKEN       Gitea API token (also reads GA_TOKEN / GITEA_TOKEN env)
+      --api-base URL      Gitea API base URL for the repo
+                          e.g. https://git.mokoconsulting.tech/api/v1/repos/Org/Repo
+
+    Options:
+      --branch BRANCH     Target branch (default: dev)
+      --platform TYPE     Platform type: dolibarr, crm-module, joomla, waas-component
+      --path DIR          Repo root for auto-detecting platform from manifest.xml
+      --help              Show this help
+
+    USAGE;
+}
+
+/**
+ * Detect the platform type from a repo's .mokogitea/manifest.xml file.
+ *
+ * @param string $repoPath Path to the repository root
+ * @return string|null The detected platform, or null if detection fails
+ */
+function detectPlatform(string $repoPath): ?string
+{
+    $root = realpath($repoPath) ?: $repoPath;
+    $manifestXml = "{$root}/.mokogitea/manifest.xml";
+
+    if (!file_exists($manifestXml)) {
+        return null;
+    }
+
+    $xml = @simplexml_load_file($manifestXml);
+    if ($xml === false) {
+        return null;
+    }
+
+    if (isset($xml->governance->platform)) {
+        $platform = (string) $xml->governance->platform;
+        if ($platform !== '') {
+            return $platform;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Make a Gitea API call and return the decoded JSON response.
+ *
+ * @param string      $url    Full API URL
+ * @param string      $token  Gitea API token
+ * @param string      $method HTTP method (GET, PUT, POST, DELETE)
+ * @param string|null $body   JSON request body, or null for bodiless requests
+ * @return array<string, mixed>|null Decoded JSON response, or null on failure
+ */
+function giteaApiCall(string $url, string $token, string $method = 'GET', ?string $body = null): ?array
+{
+    $ch = curl_init($url);
+    if ($ch === false) {
+        fwrite(STDERR, "Error: curl_init() failed for {$url}\n");
+        return null;
+    }
+
+    $headers = [
+        "Authorization: token {$token}",
+        'Accept: application/json',
+    ];
+    if ($body !== null) {
+        $headers[] = 'Content-Type: application/json';
+    }
+
+    curl_setopt_array($ch, [
+        CURLOPT_RETURNTRANSFER => true,
+        CURLOPT_HTTPHEADER     => $headers,
+        CURLOPT_TIMEOUT        => 30,
+        CURLOPT_CUSTOMREQUEST  => $method,
+    ]);
+
+    if ($body !== null) {
+        curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
+    }
+
+    $response = curl_exec($ch);
+    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+    curl_close($ch);
+
+    if ($httpCode < 200 || $httpCode >= 300 || !is_string($response) || $response === '') {
+        return null;
+    }
+
+    $data = json_decode($response, true);
+    if (!is_array($data)) {
+        return null;
+    }
+
+    return $data;
+}
+
+/**
+ * Reset Dolibarr module version to 'development' on the target branch.
+ *
+ * Searches the repository tree for mod*.class.php files that contain
+ * `extends DolibarrModules`, then replaces `$this->version = '...'`
+ * with `$this->version = 'development'` via the Gitea file contents API.
+ *
+ * @param string $apiBase Gitea API base URL for the repo
+ * @param string $token   Gitea API token
+ * @param string $branch  Target branch name
+ * @return int Number of files modified
+ */
+function resetDolibarrVersion(string $apiBase, string $token, string $branch): int
+{
+    // Search the repo tree for mod*.class.php files
+    $treeUrl = "{$apiBase}/git/trees/{$branch}?recursive=true";
+    $tree = giteaApiCall($treeUrl, $token);
+
+    if ($tree === null || !isset($tree['tree']) || !is_array($tree['tree'])) {
+        fwrite(STDERR, "Error: could not read repository tree for branch '{$branch}'.\n");
+        return 0;
+    }
+
+    // Find candidate files: mod*.class.php anywhere in the tree
+    $candidates = [];
+    foreach ($tree['tree'] as $entry) {
+        if (!isset($entry['path']) || !is_string($entry['path'])) {
+            continue;
+        }
+        $basename = basename($entry['path']);
+        if (preg_match('/^mod[A-Za-z0-9_]+\.class\.php$/', $basename)) {
+            $candidates[] = $entry['path'];
+        }
+    }
+
+    if (empty($candidates)) {
+        echo "No mod*.class.php files found on branch '{$branch}'.\n";
+        return 0;
+    }
+
+    $changed = 0;
+
+    foreach ($candidates as $filePath) {
+        // GET file contents via API
+        $encodedPath = implode('/', array_map('rawurlencode', explode('/', $filePath)));
+        $fileUrl = "{$apiBase}/contents/{$encodedPath}?ref={$branch}";
+        $fileData = giteaApiCall($fileUrl, $token);
+
+        if ($fileData === null || !isset($fileData['content'])) {
+            echo "Skipping {$filePath}: could not fetch contents.\n";
+            continue;
+        }
+
+        // Decode base64 content
+        $rawContent = is_string($fileData['content']) ? $fileData['content'] : '';
+        $content = base64_decode($rawContent, true);
+        if ($content === false) {
+            echo "Skipping {$filePath}: could not decode content.\n";
+            continue;
+        }
+
+        // Verify this file extends DolibarrModules
+        if (!str_contains($content, 'extends DolibarrModules')) {
+            continue;
+        }
+
+        // Replace $this->version = '...' with $this->version = 'development'
+        $updated = preg_replace(
+            '/(\$this->version\s*=\s*)[\'"][^\'"]*[\'"]/',
+            "\${1}'development'",
+            $content
+        );
+
+        if ($updated === null || $updated === $content) {
+            echo "Skipping {$filePath}: no version change needed.\n";
+            continue;
+        }
+
+        // PUT updated content back via API
+        $sha = $fileData['sha'] ?? '';
+        $putBody = json_encode([
+            'content'  => base64_encode($updated),
+            'message'  => 'chore(version): reset dev version [skip ci]',
+            'branch'   => $branch,
+            'sha'      => $sha,
+        ]);
+
+        $putUrl = "{$apiBase}/contents/{$encodedPath}";
+        $result = giteaApiCall($putUrl, $token, 'PUT', $putBody);
+
+        if ($result !== null) {
+            echo "Reset: {$filePath} -> \$this->version = 'development'\n";
+            $changed++;
+        } else {
+            fwrite(STDERR, "Error: failed to update {$filePath} on branch '{$branch}'.\n");
+        }
+    }
+
+    return $changed;
+}

cli/wiki_sync.php

@@ -0,0 +1,282 @@
+#!/usr/bin/env php
+<?php
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: moko-platform.CLI
+ * INGROUP: moko-platform
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+ * PATH: /cli/wiki_sync.php
+ * VERSION: 01.00.00
+ * BRIEF: Sync select wiki pages from moko-platform to all template repos
+ */
+
+declare(strict_types=1);
+
+final class WikiSync
+{
+    private string $giteaUrl = 'https://git.mokoconsulting.tech';
+    private string $token = '';
+    private string $org = 'MokoConsulting';
+    private string $sourceRepo = 'moko-platform';
+    private array $targetRepos = [];
+    private array $pages = [];
+    private bool $dryRun = false;
+    private bool $allTemplates = false;
+
+    private int $synced = 0;
+    private int $created = 0;
+    private int $skipped = 0;
+    private int $errors = 0;
+
+    public function run(): int
+    {
+        $this->parseArgs();
+
+        if ($this->token === '') {
+            $this->log('ERROR: --token is required.');
+            $this->printUsage();
+            return 1;
+        }
+
+        if (empty($this->pages) && !$this->allTemplates) {
+            $this->log('ERROR: --page or --all-standards is required.');
+            $this->printUsage();
+            return 1;
+        }
+
+        // Discover template repos if --all-templates
+        if ($this->allTemplates || empty($this->targetRepos)) {
+            $this->targetRepos = $this->discoverTemplateRepos();
+        }
+
+        if (empty($this->targetRepos)) {
+            $this->log('No target repos found.');
+            return 0;
+        }
+
+        // If --all-standards, get all pages that start with uppercase
+        if (empty($this->pages)) {
+            $this->pages = $this->getStandardsPages();
+        }
+
+        $this->log("Syncing " . count($this->pages) . " page(s) to " . count($this->targetRepos) . " repo(s)");
+        if ($this->dryRun) {
+            $this->log("[DRY RUN] No changes will be made.\n");
+        }
+
+        foreach ($this->pages as $pageName) {
+            $this->log("\n--- Page: {$pageName} ---");
+            $sourceContent = $this->getWikiPage($this->sourceRepo, $pageName);
+            if ($sourceContent === null) {
+                $this->log("  WARNING: page not found in {$this->sourceRepo}");
+                $this->errors++;
+                continue;
+            }
+
+            foreach ($this->targetRepos as $repo) {
+                $existing = $this->getWikiPage($repo, $pageName);
+                if ($existing !== null && $existing === $sourceContent) {
+                    $this->log("  {$repo}: IDENTICAL (skipped)");
+                    $this->skipped++;
+                    continue;
+                }
+
+                if ($this->dryRun) {
+                    $action = $existing !== null ? 'WOULD UPDATE' : 'WOULD CREATE';
+                    $this->log("  {$repo}: {$action}");
+                    continue;
+                }
+
+                if ($existing !== null) {
+                    $ok = $this->updateWikiPage($repo, $pageName, $sourceContent);
+                    $this->log("  {$repo}: " . ($ok ? 'UPDATED' : 'ERROR'));
+                    $ok ? $this->synced++ : $this->errors++;
+                } else {
+                    $ok = $this->createWikiPage($repo, $pageName, $sourceContent);
+                    $this->log("  {$repo}: " . ($ok ? 'CREATED' : 'ERROR'));
+                    $ok ? $this->created++ : $this->errors++;
+                }
+            }
+        }
+
+        $this->log("\nDone: {$this->synced} updated, {$this->created} created, {$this->skipped} skipped, {$this->errors} error(s)");
+        return $this->errors > 0 ? 1 : 0;
+    }
+
+    private function discoverTemplateRepos(): array
+    {
+        $repos = $this->apiGet("/orgs/{$this->org}/repos?limit=100");
+        $templates = [];
+        foreach ($repos as $repo) {
+            if (str_starts_with($repo['name'], 'Template-') && !($repo['archived'] ?? false)) {
+                $templates[] = $repo['name'];
+            }
+        }
+        sort($templates);
+        $this->log("Found template repos: " . implode(', ', $templates));
+        return $templates;
+    }
+
+    private function getStandardsPages(): array
+    {
+        $pages = $this->apiGet("/repos/{$this->org}/{$this->sourceRepo}/wiki/pages");
+        $standards = [];
+        foreach ($pages as $page) {
+            $title = $page['title'] ?? '';
+            // Sync pages that are all-caps with underscores (standards pages)
+            if (preg_match('/^[A-Z][A-Z0-9_-]+$/', $title)) {
+                $standards[] = $title;
+            }
+        }
+        sort($standards);
+        $this->log("Found " . count($standards) . " standards pages: " . implode(', ', $standards));
+        return $standards;
+    }
+
+    private function getWikiPage(string $repo, string $pageName): ?string
+    {
+        $data = $this->apiGet("/repos/{$this->org}/{$repo}/wiki/page/{$pageName}");
+        if ($data === null || !isset($data['content_base64'])) {
+            return null;
+        }
+        return base64_decode($data['content_base64']);
+    }
+
+    private function createWikiPage(string $repo, string $pageName, string $content): bool
+    {
+        $payload = json_encode([
+            'title' => $pageName,
+            'content_base64' => base64_encode($content),
+        ]);
+        return $this->apiPost("/repos/{$this->org}/{$repo}/wiki/new", $payload) !== null;
+    }
+
+    private function updateWikiPage(string $repo, string $pageName, string $content): bool
+    {
+        $payload = json_encode([
+            'title' => $pageName,
+            'content_base64' => base64_encode($content),
+        ]);
+        return $this->apiPatch("/repos/{$this->org}/{$repo}/wiki/page/{$pageName}", $payload) !== null;
+    }
+
+    private function apiGet(string $endpoint): ?array
+    {
+        $url = "{$this->giteaUrl}/api/v1{$endpoint}";
+        $opts = [
+            'http' => [
+                'method' => 'GET',
+                'header' => "Authorization: token {$this->token}\r\nAccept: application/json\r\n",
+                'ignore_errors' => true,
+            ],
+        ];
+        $ctx = stream_context_create($opts);
+        $result = @file_get_contents($url, false, $ctx);
+        if ($result === false) return null;
+        $data = json_decode($result, true);
+        return is_array($data) ? $data : null;
+    }
+
+    private function apiPost(string $endpoint, string $payload): ?array
+    {
+        return $this->apiWrite('POST', $endpoint, $payload);
+    }
+
+    private function apiPatch(string $endpoint, string $payload): ?array
+    {
+        return $this->apiWrite('PATCH', $endpoint, $payload);
+    }
+
+    private function apiWrite(string $method, string $endpoint, string $payload): ?array
+    {
+        $url = "{$this->giteaUrl}/api/v1{$endpoint}";
+        $opts = [
+            'http' => [
+                'method' => $method,
+                'header' => "Authorization: token {$this->token}\r\nContent-Type: application/json\r\nAccept: application/json\r\n",
+                'content' => $payload,
+                'ignore_errors' => true,
+            ],
+        ];
+        $ctx = stream_context_create($opts);
+        $result = @file_get_contents($url, false, $ctx);
+        if ($result === false) return null;
+        $data = json_decode($result, true);
+        return is_array($data) ? $data : null;
+    }
+
+    private function parseArgs(): void
+    {
+        global $argv;
+        $args = $argv;
+        for ($i = 1; $i < count($args); $i++) {
+            switch ($args[$i]) {
+                case '--token':
+                    $this->token = $args[++$i] ?? '';
+                    break;
+                case '--org':
+                    $this->org = $args[++$i] ?? '';
+                    break;
+                case '--source':
+                    $this->sourceRepo = $args[++$i] ?? '';
+                    break;
+                case '--target':
+                    $this->targetRepos[] = $args[++$i] ?? '';
+                    break;
+                case '--page':
+                    $this->pages[] = $args[++$i] ?? '';
+                    break;
+                case '--all-standards':
+                    $this->pages = []; // will be populated from source wiki
+                    $this->allTemplates = true;
+                    break;
+                case '--all-templates':
+                    $this->allTemplates = true;
+                    break;
+                case '--dry-run':
+                    $this->dryRun = true;
+                    break;
+                case '--help':
+                case '-h':
+                    $this->printUsage();
+                    exit(0);
+                default:
+                    $this->log("WARNING: Unknown argument: {$args[$i]}");
+                    break;
+            }
+        }
+    }
+
+    private function printUsage(): void
+    {
+        $this->log('Usage: wiki_sync.php --token <token> [options]');
+        $this->log('');
+        $this->log('Sync wiki pages from moko-platform to template repos.');
+        $this->log('');
+        $this->log('Options:');
+        $this->log('  --token <token>       Gitea API token (required)');
+        $this->log('  --org <org>           Organization (default: MokoConsulting)');
+        $this->log('  --source <repo>       Source repo (default: moko-platform)');
+        $this->log('  --target <repo>       Target repo (can repeat; default: all Template-* repos)');
+        $this->log('  --page <name>         Page to sync (can repeat)');
+        $this->log('  --all-standards       Sync all UPPERCASE standards pages');
+        $this->log('  --all-templates       Target all Template-* repos');
+        $this->log('  --dry-run             Show what would be done');
+        $this->log('  --help, -h            Show this help');
+        $this->log('');
+        $this->log('Examples:');
+        $this->log('  php wiki_sync.php --token xxx --page MANIFEST_STANDARD --all-templates');
+        $this->log('  php wiki_sync.php --token xxx --all-standards --all-templates --dry-run');
+        $this->log('  php wiki_sync.php --token xxx --page WORKFLOW_STANDARDS --target Template-Joomla');
+    }
+
+    private function log(string $msg): void
+    {
+        fwrite(STDERR, $msg . "\n");
+    }
+}
+
+(new WikiSync())->run();

composer.json

@@ -2,7 +2,7 @@
     "name": "mokoconsulting-tech/enterprise",
     "description": "MokoStandards Enterprise API \u2014 PHP implementation",
     "type": "library",
-    "version": "06.00.00",
+    "version": "09.01.00",
     "license": "GPL-3.0-or-later",
     "authors": [
         {

definitions/manifest-schema.xsd

@@ -0,0 +1,126 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+  SPDX-License-Identifier: GPL-3.0-or-later
+
+  MokoStandards Manifest Schema v09.01.00
+  Defines the structure of .mokogitea/manifest.xml
+
+  Validate: xmllint - -schema definitions/manifest-schema.xsd .mokogitea/manifest.xml
+-->
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+           xmlns:moko="https://standards.mokoconsulting.tech/moko-platform/1.0"
+           targetNamespace="https://standards.mokoconsulting.tech/moko-platform/1.0"
+           elementFormDefault="qualified"
+           version="09.01.00">
+
+  <!-- Root element -->
+  <xs:element name="moko-platform">
+    <xs:complexType>
+      <xs:sequence>
+        <xs:element name="identity" type="moko:identityType"/>
+        <xs:element name="governance" type="moko:governanceType"/>
+        <xs:element name="build" type="moko:buildType"/>
+        <xs:element name="deploy" type="moko:deployType" minOccurs="0"/>
+      </xs:sequence>
+      <xs:attribute name="schema-version" type="xs:string" use="required"/>
+    </xs:complexType>
+  </xs:element>
+
+  <!-- Identity block -->
+  <xs:complexType name="identityType">
+    <xs:sequence>
+      <xs:element name="name" type="xs:string"/>
+      <xs:element name="org" type="xs:string"/>
+      <xs:element name="description" type="xs:string"/>
+      <xs:element name="version" type="moko:versionType"/>
+      <xs:element name="license" type="moko:licenseType"/>
+    </xs:sequence>
+  </xs:complexType>
+
+  <!-- Version format: XX.YY.ZZ -->
+  <xs:simpleType name="versionType">
+    <xs:restriction base="xs:string">
+      <xs:pattern value="\d{2}\.\d{2}\.\d{2}"/>
+    </xs:restriction>
+  </xs:simpleType>
+
+  <!-- License with SPDX attribute -->
+  <xs:complexType name="licenseType">
+    <xs:simpleContent>
+      <xs:extension base="xs:string">
+        <xs:attribute name="spdx" type="xs:string" use="required"/>
+      </xs:extension>
+    </xs:simpleContent>
+  </xs:complexType>
+
+  <!-- Governance block -->
+  <xs:complexType name="governanceType">
+    <xs:sequence>
+      <xs:element name="platform" type="moko:platformType"/>
+      <xs:element name="standards-version" type="moko:versionType"/>
+      <xs:element name="standards-source" type="xs:anyURI"/>
+      <xs:element name="last-synced" type="xs:dateTime" minOccurs="0"/>
+    </xs:sequence>
+  </xs:complexType>
+
+  <!-- Allowed platform values -->
+  <xs:simpleType name="platformType">
+    <xs:restriction base="xs:string">
+      <xs:enumeration value="joomla"/>
+      <xs:enumeration value="dolibarr"/>
+      <xs:enumeration value="go"/>
+      <xs:enumeration value="node"/>
+      <xs:enumeration value="rust"/>
+      <xs:enumeration value="python"/>
+      <xs:enumeration value="generic"/>
+    </xs:restriction>
+  </xs:simpleType>
+
+  <!-- Build block -->
+  <xs:complexType name="buildType">
+    <xs:sequence>
+      <xs:element name="language" type="moko:languageType"/>
+      <xs:element name="package-type" type="moko:packageType"/>
+      <xs:element name="entry-point" type="xs:string"/>
+    </xs:sequence>
+  </xs:complexType>
+
+  <!-- Allowed languages -->
+  <xs:simpleType name="languageType">
+    <xs:restriction base="xs:string">
+      <xs:enumeration value="PHP"/>
+      <xs:enumeration value="Go"/>
+      <xs:enumeration value="JavaScript"/>
+      <xs:enumeration value="TypeScript"/>
+      <xs:enumeration value="Rust"/>
+      <xs:enumeration value="Python"/>
+      <xs:enumeration value="HCL"/>
+      <xs:enumeration value="Shell"/>
+    </xs:restriction>
+  </xs:simpleType>
+
+  <!-- Allowed package types -->
+  <xs:simpleType name="packageType">
+    <xs:restriction base="xs:string">
+      <xs:enumeration value="joomla-extension"/>
+      <xs:enumeration value="dolibarr"/>
+      <xs:enumeration value="application"/>
+      <xs:enumeration value="library"/>
+      <xs:enumeration value="mcp-server"/>
+      <xs:enumeration value="generic"/>
+    </xs:restriction>
+  </xs:simpleType>
+
+  <!-- Deploy block (optional) -->
+  <xs:complexType name="deployType">
+    <xs:sequence>
+      <xs:element name="source-dir" type="xs:string" minOccurs="0"/>
+      <xs:element name="remote-subdir" type="xs:string" minOccurs="0"/>
+      <xs:element name="excludes" type="xs:string" minOccurs="0"/>
+      <xs:element name="dev-host" type="xs:string" minOccurs="0"/>
+      <xs:element name="demo-host" type="xs:string" minOccurs="0"/>
+    </xs:sequence>
+  </xs:complexType>
+
+</xs:schema>

lib/Enterprise/ApiClient.php

@@ -92,6 +92,8 @@ class CircuitBreakerOpen extends RuntimeException
  * );
  * $response = $client->get('/repos/owner/repo');
  * ```
+ *
+ * @since 04.00.00
  */
 class ApiClient
 {
@@ -124,7 +126,6 @@ class ApiClient
     private ?DateTime $circuitLastFailure = null;
 
     /** @var LoggerInterface|null Optional logger instance */
-    private ?LoggerInterface $logger = null;
 
     /** @var array<string, mixed> Request metrics */
     private array $metrics = [
@@ -179,7 +180,6 @@ class ApiClient
         $this->circuitBreakerTimeout = $circuitBreakerTimeout;
         $this->enableCaching = $enableCaching;
         $this->userAgent = $userAgent;
-        $this->logger = $logger;
         $this->authScheme = $authScheme;
 
         // Initialize HTTP client
@@ -261,9 +261,9 @@ class ApiClient
      * @throws RateLimitExceeded
      * @throws CircuitBreakerOpen
      */
-    public function delete(string $endpoint): array
+    public function delete(string $endpoint, ?array $body = null): array
     {
-        return $this->request('DELETE', $endpoint);
+        return $this->request('DELETE', $endpoint, $body);
     }
 
     /**

lib/Enterprise/AuditLogger.php

@@ -58,6 +58,8 @@ use RuntimeException;
  * $transaction->logSecurityEvent('file_modified', ['file' => 'README.md']);
  * $transaction->end();
  * ```
+ *
+ * @since 04.00.00
  */
 class AuditLogger
 {

lib/Enterprise/CliFramework.php

@@ -716,6 +716,9 @@ class ValidationCLI extends CLIApp
  * Lifecycle: configure() -> parseArguments() -> printBanner() -> initialize() -> run()
  *
  * All new scripts must extend CliFramework and implement configure() + run().
+ *
+ * @since   04.00.15
+ * @see     CLIApp Legacy base class (deprecated)
  */
 abstract class CliFramework
 {
@@ -932,6 +935,11 @@ abstract class CliFramework
     // Argument parsing (internal)
     // =========================================================================
 
+    /**
+     * Parse CLI arguments from $_SERVER['argv'] into registered argument definitions.
+     *
+     * @since 04.00.15
+     */
     private function parseArguments(): void
     {
         $argv = array_slice($_SERVER['argv'] ?? [], 1);
@@ -970,6 +978,11 @@ abstract class CliFramework
     // Help screen
     // =========================================================================
 
+    /**
+     * Print auto-generated help screen from registered arguments.
+     *
+     * @since 04.00.15
+     */
     protected function printHelp(): void
     {
         $w = $this->termWidth();

lib/Enterprise/ConfigValidator.php

@@ -0,0 +1,255 @@
+<?php
+
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * This file is part of a Moko Consulting project.
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: MokoStandards.Enterprise
+ * INGROUP: MokoStandards.Enterprise
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+ * PATH: /lib/Enterprise/ConfigValidator.php
+ * BRIEF: Validate project config against plugin JSON schema
+ */
+
+declare(strict_types=1);
+
+namespace MokoEnterprise;
+
+/**
+ * Configuration Validator
+ *
+ * Validates moko-platform configuration files (YAML, JSON, HCL)
+ * against expected schemas and reports errors.
+ *
+ * @since 04.00.00
+ */
+class ConfigValidator
+{
+    /** @var array<int, string> */
+    private array $errors = [];
+
+    /** @var array<int, string> */
+    private array $warnings = [];
+
+    /**
+     * Validate config data against a JSON schema.
+     *
+     * @param array<string, mixed> $config Config to validate
+     * @param array<string, mixed> $schema JSON Schema definition
+     * @return bool True if valid
+     */
+    public function validate(array $config, array $schema): bool
+    {
+        $this->errors = [];
+        $this->warnings = [];
+
+        $this->validateNode($config, $schema, '');
+
+        return empty($this->errors);
+    }
+
+    /** @return array<int, string> */
+    public function getErrors(): array
+    {
+        return $this->errors;
+    }
+
+    /** @return array<int, string> */
+    public function getWarnings(): array
+    {
+        return $this->warnings;
+    }
+
+    /**
+     * @param mixed $data
+     * @param array<string, mixed> $schema
+     */
+    private function validateNode(
+        mixed $data,
+        array $schema,
+        string $path
+    ): void {
+        $type = $schema['type'] ?? null;
+
+        if ($type !== null && !$this->checkType($data, $type)) {
+            $actual = gettype($data);
+            $this->errors[] = $path === ''
+                ? "Root must be {$type}, got {$actual}"
+                : "{$path}: expected {$type}, got {$actual}";
+            return;
+        }
+
+        if ($type === 'object') {
+            $this->validateObject($data, $schema, $path);
+        }
+
+        if ($type === 'array' && isset($schema['items'])) {
+            $this->validateArray($data, $schema, $path);
+        }
+
+        if (isset($schema['enum'])) {
+            $this->validateEnum($data, $schema['enum'], $path);
+        }
+
+        if ($type === 'string') {
+            $this->validateString($data, $schema, $path);
+        }
+
+        if ($type === 'integer' || $type === 'number') {
+            $this->validateNumber($data, $schema, $path);
+        }
+    }
+
+    /**
+     * @param array<string, mixed> $data
+     * @param array<string, mixed> $schema
+     */
+    private function validateObject(
+        array $data,
+        array $schema,
+        string $path
+    ): void {
+        $properties = $schema['properties'] ?? [];
+        $required = $schema['required'] ?? [];
+
+        foreach ($required as $field) {
+            if (!array_key_exists($field, $data)) {
+                $fieldPath = $path === '' ? $field : "{$path}.{$field}";
+                $this->errors[] = "{$fieldPath}: required field missing";
+            }
+        }
+
+        foreach ($properties as $field => $fieldSchema) {
+            if (!array_key_exists($field, $data)) {
+                continue;
+            }
+
+            $fieldPath = $path === '' ? $field : "{$path}.{$field}";
+            $this->validateNode($data[$field], $fieldSchema, $fieldPath);
+        }
+
+        $known = array_keys($properties);
+
+        foreach (array_keys($data) as $field) {
+            if (!in_array($field, $known, true)) {
+                $fieldPath = $path === '' ? $field : "{$path}.{$field}";
+                $this->warnings[] = "{$fieldPath}: unknown property";
+            }
+        }
+    }
+
+    /**
+     * @param array<int, mixed> $data
+     * @param array<string, mixed> $schema
+     */
+    private function validateArray(
+        array $data,
+        array $schema,
+        string $path
+    ): void {
+        $itemSchema = $schema['items'];
+
+        foreach ($data as $i => $item) {
+            $this->validateNode(
+                $item,
+                $itemSchema,
+                "{$path}[{$i}]"
+            );
+        }
+
+        if (
+            isset($schema['minItems'])
+            && count($data) < $schema['minItems']
+        ) {
+            $this->errors[] = "{$path}: "
+                . "needs at least {$schema['minItems']} items";
+        }
+    }
+
+    /**
+     * @param mixed $data
+     * @param array<int, mixed> $allowed
+     */
+    private function validateEnum(
+        mixed $data,
+        array $allowed,
+        string $path
+    ): void {
+        if (!in_array($data, $allowed, true)) {
+            $values = implode(', ', $allowed);
+            $label = $path ?: 'value';
+            $this->errors[] = "{$label}: "
+                . "'{$data}' not in [{$values}]";
+        }
+    }
+
+    /**
+     * @param array<string, mixed> $schema
+     */
+    private function validateString(
+        mixed $data,
+        array $schema,
+        string $path
+    ): void {
+        if (!is_string($data)) {
+            return;
+        }
+
+        if (
+            isset($schema['minLength'])
+            && strlen($data) < $schema['minLength']
+        ) {
+            $this->errors[] = "{$path}: "
+                . "too short (min {$schema['minLength']})";
+        }
+
+        if (
+            isset($schema['pattern'])
+            && !preg_match('/' . $schema['pattern'] . '/', $data)
+        ) {
+            $this->errors[] = "{$path}: "
+                . "does not match pattern {$schema['pattern']}";
+        }
+    }
+
+    /**
+     * @param array<string, mixed> $schema
+     */
+    private function validateNumber(
+        mixed $data,
+        array $schema,
+        string $path
+    ): void {
+        if (!is_numeric($data)) {
+            return;
+        }
+
+        if (isset($schema['minimum']) && $data < $schema['minimum']) {
+            $this->errors[] = "{$path}: "
+                . "below minimum {$schema['minimum']}";
+        }
+
+        if (isset($schema['maximum']) && $data > $schema['maximum']) {
+            $this->errors[] = "{$path}: "
+                . "above maximum {$schema['maximum']}";
+        }
+    }
+
+    private function checkType(mixed $data, string $type): bool
+    {
+        return match ($type) {
+            'object' => is_array($data),
+            'array' => is_array($data)
+                && array_is_list($data),
+            'string' => is_string($data),
+            'integer' => is_int($data),
+            'number' => is_int($data) || is_float($data),
+            'boolean' => is_bool($data),
+            'null' => is_null($data),
+            default => true,
+        };
+    }
+}

lib/Enterprise/DefinitionParser.php

@@ -43,6 +43,8 @@ namespace MokoEnterprise;
  *   'inline_content'   => string  — rendered template content (ready to push)
  *   'destination'      => string  — path in the target repository
  *   'always_overwrite' => bool    — true: overwrite existing file; false: create-only
+ *
+ * @since 04.00.00
  */
 class DefinitionParser
 {

lib/Enterprise/GitHubAdapter.php

@@ -32,12 +32,17 @@ use RuntimeException;
  * - Workflow dir: .github/workflows
  *
  * @package MokoStandards\Enterprise
- * @version 04.06.10
+ * @since   04.06.10
+ * @see     GitPlatformAdapter
  */
 class GitHubAdapter implements GitPlatformAdapter
 {
+    /** @var ApiClient HTTP client for GitHub API calls. */
     private ApiClient $apiClient;
 
+    /**
+     * @param ApiClient $apiClient Configured API client for api.github.com
+     */
     public function __construct(ApiClient $apiClient)
     {
         $this->apiClient = $apiClient;
@@ -405,7 +410,7 @@ class GitHubAdapter implements GitPlatformAdapter
             $page++;
         }
 
-        return $all;
+        return array_values($all);
     }
 
     // ──────────────────────────────────────────────

lib/Enterprise/GitPlatformAdapter.php

@@ -175,7 +175,7 @@ interface GitPlatformAdapter
     /**
      * List all branches in a repository.
      *
-     * @return array<int, array<string, mixed>>
+     * @return array<mixed>
      */
     public function listBranches(string $org, string $repo): array;
 
@@ -202,7 +202,7 @@ interface GitPlatformAdapter
      * @param string $repo Repository name
      * @param string $path File path within the repository
      * @param string|null $ref Branch/tag/SHA reference (null = default branch)
-     * @return array{content: string, sha: string, size: int, encoding: string} File data (content is base64-encoded)
+     * @return array<string, mixed> File data (content is base64-encoded)
      */
     public function getFileContents(string $org, string $repo, string $path, ?string $ref = null): array;
 
@@ -258,7 +258,7 @@ interface GitPlatformAdapter
      * @param string $org Organization name
      * @param string $repo Repository name
      * @param array<string, mixed> $filters Filters (state, head, base, sort, direction)
-     * @return array<int, array<string, mixed>> Pull request list
+     * @return array<mixed> Pull request list
      */
     public function listPullRequests(string $org, string $repo, array $filters = []): array;
 
@@ -305,7 +305,7 @@ interface GitPlatformAdapter
      * @param string $org Organization name
      * @param string $repo Repository name
      * @param array<string, mixed> $filters Filters (state, labels, assignee, etc.)
-     * @return array<int, array<string, mixed>> Issue list
+     * @return array<mixed> Issue list
      */
     public function listIssues(string $org, string $repo, array $filters = []): array;
 
@@ -357,7 +357,7 @@ interface GitPlatformAdapter
      *
      * @param string $org Organization name
      * @param string $repo Repository name
-     * @return array<int, array{name: string, color: string, description: string}> Label list
+     * @return array<mixed> Label list
      */
     public function listLabels(string $org, string $repo): array;
 
@@ -406,7 +406,7 @@ interface GitPlatformAdapter
      *
      * @param string $org Organization name
      * @param string $repo Repository name
-     * @return array<int, array<string, mixed>> Protection rules
+     * @return array<mixed> Protection rules
      */
     public function listBranchProtections(string $org, string $repo): array;
 
@@ -445,7 +445,7 @@ interface GitPlatformAdapter
      * @param string $endpoint API endpoint path
      * @param array<string, mixed> $params Query parameters
      * @param int $perPage Items per page (platform default if 0)
-     * @return array<int, array<string, mixed>> All items across all pages
+     * @return array<mixed> All items across all pages
      */
     public function paginateAll(string $endpoint, array $params = [], int $perPage = 100): array;
 

lib/Enterprise/ManifestReader.php

@@ -0,0 +1,196 @@
+#!/usr/bin/env php
+<?php
+
+/**
+ * Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: moko-platform.Enterprise
+ * INGROUP: moko-platform
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+ * PATH: /lib/Enterprise/ManifestReader.php
+ * BRIEF: Read and parse .mokogitea/manifest.xml — shared across all CLI tools
+ */
+
+declare(strict_types=1);
+
+namespace MokoEnterprise;
+
+/**
+ * Manifest Reader
+ *
+ * Parses .mokogitea/manifest.xml and provides typed access to all fields.
+ * Used by CLI tools and the Enterprise library to determine platform,
+ * build configuration, and deployment settings from the repository manifest.
+ *
+ * @since 09.01.00
+ */
+class ManifestReader
+{
+    /** @var array<string, string> Parsed manifest fields */
+    private array $fields = [];
+
+    /** @var bool Whether a manifest was found and parsed */
+    private bool $loaded = false;
+
+    /**
+     * Load manifest from a repository root directory.
+     *
+     * @param string $root Repository root path
+     * @return self
+     */
+    public static function fromPath(string $root): self
+    {
+        $reader = new self();
+        $reader->load($root);
+        return $reader;
+    }
+
+    /**
+     * Load and parse the manifest file.
+     *
+     * @param string $root Repository root path
+     */
+    public function load(string $root): void
+    {
+        $candidates = [
+            "{$root}/.mokogitea/manifest.xml",
+            "{$root}/.mokogitea/.manifest.xml",
+            "{$root}/.mokogitea/.moko-platform",
+        ];
+
+        $manifestFile = null;
+        foreach ($candidates as $candidate) {
+            if (file_exists($candidate)) {
+                $manifestFile = $candidate;
+                break;
+            }
+        }
+
+        if ($manifestFile === null) {
+            return;
+        }
+
+        $xml = @simplexml_load_file($manifestFile);
+        if ($xml === false) {
+            // Fallback: YAML legacy format
+            $content = file_get_contents($manifestFile);
+            if (preg_match('/^platform:\s*(.+)/m', $content, $m)) {
+                $this->fields['platform'] = trim($m[1], " \t\n\r\"'");
+            }
+            $this->loaded = true;
+            return;
+        }
+
+        $this->fields = [
+            'name'              => (string)($xml->identity->name ?? ''),
+            'org'               => (string)($xml->identity->org ?? ''),
+            'description'       => (string)($xml->identity->description ?? ''),
+            'license'           => (string)($xml->identity->license ?? ''),
+            'license-spdx'      => (string)($xml->identity->license['spdx'] ?? ''),
+            'version'           => (string)($xml->identity->version ?? ''),
+            'platform'          => (string)($xml->governance->platform ?? ''),
+            'standards-version' => (string)($xml->governance->{"standards-version"} ?? ''),
+            'language'          => (string)($xml->build->language ?? ''),
+            'package-type'      => (string)($xml->build->{"package-type"} ?? ''),
+            'entry-point'       => (string)($xml->build->{"entry-point"} ?? ''),
+            'source-dir'        => (string)($xml->deploy->{"source-dir"} ?? ''),
+            'remote-subdir'     => (string)($xml->deploy->{"remote-subdir"} ?? ''),
+            'dev-host'          => (string)($xml->deploy->{"dev-host"} ?? ''),
+            'demo-host'         => (string)($xml->deploy->{"demo-host"} ?? ''),
+        ];
+
+        // Strip empty values
+        $this->fields = array_filter($this->fields, fn($v) => $v !== '');
+        $this->loaded = true;
+    }
+
+    /**
+     * Whether a manifest was found and loaded.
+     *
+     * @return bool
+     */
+    public function isLoaded(): bool
+    {
+        return $this->loaded;
+    }
+
+    /**
+     * Get a single field value.
+     *
+     * @param string $key Field name (e.g. 'platform', 'package-type')
+     * @param string $default Default value if field is missing
+     * @return string
+     */
+    public function get(string $key, string $default = ''): string
+    {
+        return $this->fields[$key] ?? $default;
+    }
+
+    /**
+     * Get the platform slug, normalized to canonical values.
+     *
+     * @return string One of: joomla, dolibarr, generic, mcp, nodejs
+     */
+    public function getPlatform(): string
+    {
+        $raw = $this->get('platform', 'generic');
+        return match ($raw) {
+            'waas-component' => 'joomla',
+            'crm-module' => 'dolibarr',
+            default => $raw,
+        };
+    }
+
+    /**
+     * Get the source/entry-point directory.
+     *
+     * @param string $root Repository root for existence checking
+     * @return string Resolved source directory path (e.g. 'src', 'htdocs')
+     */
+    public function getSourceDir(string $root = ''): string
+    {
+        $entryPoint = $this->get('entry-point', '');
+        if ($entryPoint !== '') {
+            // Strip trailing filename (e.g. src/index.ts → src)
+            $dir = rtrim(dirname($entryPoint) === '.' ? $entryPoint : dirname($entryPoint), '/');
+            if ($root === '' || is_dir("{$root}/{$dir}")) {
+                return $dir;
+            }
+        }
+
+        // Fallback: check common directories
+        if ($root !== '') {
+            if (is_dir("{$root}/src")) {
+                return 'src';
+            }
+            if (is_dir("{$root}/htdocs")) {
+                return 'htdocs';
+            }
+        }
+
+        return 'src';
+    }
+
+    /**
+     * Get the package type for build decisions.
+     *
+     * @return string e.g. 'package', 'dolibarr', 'generic', 'mcp-server'
+     */
+    public function getPackageType(): string
+    {
+        return $this->get('package-type', 'generic');
+    }
+
+    /**
+     * Get all parsed fields.
+     *
+     * @return array<string, string>
+     */
+    public function getAll(): array
+    {
+        return $this->fields;
+    }
+}

lib/Enterprise/MetricsCollector.php

@@ -59,6 +59,8 @@ use DateTimeZone;
 
 /**
  * Timer class for timing operations
+ *
+ * @since 04.00.00
  */
 class MetricsTimer
 {

lib/Enterprise/MokoGiteaAdapter.php

@@ -34,13 +34,21 @@ use RuntimeException;
  * - Workflow dir: .mokogitea/workflows
  *
  * @package MokoStandards\Enterprise
- * @version 04.06.10
+ * @since   04.06.10
+ * @see     GitPlatformAdapter
  */
 class MokoGiteaAdapter implements GitPlatformAdapter
 {
+    /** @var ApiClient HTTP client for Gitea API calls. */
     private ApiClient $apiClient;
+
+    /** @var string Base URL for Gitea API (e.g. https://git.mokoconsulting.tech/api/v1). */
     private string $baseUrl;
 
+    /**
+     * @param ApiClient $apiClient Configured API client
+     * @param string    $baseUrl   Gitea API base URL
+     */
     public function __construct(ApiClient $apiClient, string $baseUrl = 'https://git.mokoconsulting.tech/api/v1')
     {
         $this->apiClient = $apiClient;
@@ -468,7 +476,7 @@ class MokoGiteaAdapter implements GitPlatformAdapter
             $page++;
         }
 
-        return $all;
+        return array_values($all);
     }
 
     // ──────────────────────────────────────────────

lib/Enterprise/PlatformAdapterFactory.php

@@ -35,6 +35,8 @@ use RuntimeException;
  *
  * @package MokoStandards\Enterprise
  * @version 04.06.10
+ *
+ * @since 04.00.00
  */
 class PlatformAdapterFactory
 {

lib/Enterprise/ProjectConfigValidator.php

@@ -24,6 +24,8 @@ namespace MokoEnterprise;
  *
  * Enterprise library for validating project configurations against
  * project type templates and standards.
+ *
+ * @since 04.00.00
  */
 class ProjectConfigValidator
 {

lib/Enterprise/ProjectTypeDetector.php

@@ -24,6 +24,8 @@ namespace MokoEnterprise;
  *
  * Enterprise library for automatically detecting project types based on
  * repository structure, configuration files, and code patterns.
+ *
+ * @since 04.00.00
  */
 class ProjectTypeDetector
 {

lib/Enterprise/RepositoryHealthChecker.php

@@ -24,12 +24,13 @@ namespace MokoEnterprise;
  *
  * Enterprise library for performing comprehensive repository health checks
  * with scoring system and category-based validation.
+ *
+ * @since 04.00.00
  */
 class RepositoryHealthChecker
 {
     private AuditLogger $logger;
     private MetricsCollector $metrics;
-    private UnifiedValidator $validator;
 
     private array $results = [
         'categories' => [],
@@ -50,7 +51,6 @@ class RepositoryHealthChecker
     ) {
         $this->logger = $logger ?? new AuditLogger('repo_health_checker');
         $this->metrics = $metrics ?? new MetricsCollector();
-        $this->validator = $validator ?? new UnifiedValidator();
     }
 
     /**

lib/Enterprise/RepositorySynchronizer.php

@@ -27,6 +27,8 @@ use RuntimeException;
  *
  * Enterprise library for synchronizing files across multiple repositories
  * based on configuration and override files.
+ *
+ * @since 04.00.00
  */
 class RepositorySynchronizer
 {
@@ -39,7 +41,6 @@ class RepositorySynchronizer
     private const VERSION_BRANCH      = 'version/' . self::STANDARDS_MAJOR;
     private const SYNC_BRANCH         = 'chore/sync-mokostandards-v' . self::STANDARDS_MINOR;
 
-    private ApiClient $apiClient;
     private GitPlatformAdapter $adapter;
     private AuditLogger $logger;
     private MetricsCollector $metrics;
@@ -65,7 +66,6 @@ class RepositorySynchronizer
         ?DefinitionParser $definitionParser = null,
         ?GitPlatformAdapter $adapter = null
     ) {
-        $this->apiClient        = $apiClient;
         $this->adapter          = $adapter ?? new MokoGiteaAdapter($apiClient);
         $this->logger           = $logger;
         $this->metrics          = $metrics;
@@ -1083,28 +1083,140 @@ HCL;
     /**
      * Template repo mapping — canonical source for each platform's workflows.
      * The sync engine clones these at runtime to get the latest workflow files.
+     *
+     * Template-Generic is the single source of truth for universal workflows.
+     * During sync, universal workflows flow: Generic → Joomla/Dolibarr → governed repos.
      */
     private const TEMPLATE_REPOS = [
-        'joomla'   => 'MokoConsulting/MokoStandards-Template-Joomla',
-        'dolibarr' => 'MokoConsulting/MokoStandards-Template-Dolibarr',
-        'generic'  => 'MokoConsulting/MokoStandards-Template-Generic',
-        'client'   => 'MokoConsulting/MokoStandards-Template-Client',
+        'joomla'         => 'MokoConsulting/Template-Joomla',
+        'waas-component' => 'MokoConsulting/Template-Joomla',
+        'dolibarr'       => 'MokoConsulting/Template-Dolibarr',
+        'crm-module'     => 'MokoConsulting/Template-Dolibarr',
+        'generic'        => 'MokoConsulting/Template-Generic',
+        'mcp'            => 'MokoConsulting/Template-Generic',
+        'client'         => 'MokoConsulting/Template-Client-WaaS',
     ];
 
+    /**
+     * Universal workflows sourced from Template-Generic and pushed to all templates.
+     * These are platform-agnostic — they detect platform from manifest.xml at runtime.
+     */
+    private const UNIVERSAL_WORKFLOWS = [
+        'auto-release.yml',
+        'pre-release.yml',
+    ];
+
+    /**
+     * All template repos that receive universal workflows from Template-Generic.
+     */
+    private const TEMPLATE_SYNC_TARGETS = [
+        'MokoConsulting/Template-Joomla',
+        'MokoConsulting/Template-Dolibarr',
+        'MokoConsulting/Template-Client-WaaS',
+    ];
+
+    /**
+     * Sync universal workflows from Template-Generic to all other template repos.
+     *
+     * This ensures Template-Generic is the single source of truth for universal
+     * workflows (auto-release.yml, pre-release.yml). Called once at the start
+     * of a bulk sync before processing individual repos.
+     *
+     * @param string $org Organization name
+     * @return int Number of files updated across template repos
+     */
+    public function syncUniversalWorkflowsToTemplates(string $org): int
+    {
+        $wfDir = $this->adapter->getWorkflowDir();
+        $genericRepo = self::TEMPLATE_REPOS['generic'];
+        $genericParts = explode('/', $genericRepo);
+        $genericOrg = $genericParts[0];
+        $genericName = $genericParts[1];
+        $updated = 0;
+
+        // Read universal workflow files from Template-Generic
+        $sourceFiles = [];
+        foreach (self::UNIVERSAL_WORKFLOWS as $wfName) {
+            $path = "{$wfDir}/{$wfName}";
+            try {
+                $file = $this->adapter->getFileContents($genericOrg, $genericName, $path, 'dev');
+                $content = $file['content'] ?? '';
+                if (!empty($content)) {
+                    $sourceFiles[$wfName] = [
+                        'content' => $content,
+                        'path'    => $path,
+                    ];
+                    $this->logger->logInfo("Read universal workflow: {$wfName} from {$genericRepo}");
+                }
+            } catch (Exception $e) {
+                $this->logger->logWarning("Failed to read {$wfName} from {$genericRepo}: " . $e->getMessage());
+                $this->adapter->getApiClient()->resetCircuitBreaker();
+            }
+        }
+
+        if (empty($sourceFiles)) {
+            $this->logger->logWarning("No universal workflows found in {$genericRepo}");
+            return 0;
+        }
+
+        // Push to each template target
+        foreach (self::TEMPLATE_SYNC_TARGETS as $targetRepo) {
+            $targetParts = explode('/', $targetRepo);
+            $targetOrg = $targetParts[0];
+            $targetName = $targetParts[1];
+
+            foreach ($sourceFiles as $wfName => $source) {
+                $destPath = $source['path'];
+                try {
+                    // Get existing file SHA for update
+                    $existing = null;
+                    try {
+                        $existing = $this->adapter->getFileContents($targetOrg, $targetName, $destPath, 'dev');
+                    } catch (Exception $e) {
+                        $this->adapter->getApiClient()->resetCircuitBreaker();
+                    }
+
+                    $existingSha = $existing['sha'] ?? null;
+
+                    // Skip if content is identical
+                    if ($existing !== null) {
+                        $existingContent = $existing['content'] ?? '';
+                        if (str_replace("\n", '', $existingContent) === str_replace("\n", '', $source['content'])) {
+                            $this->logger->logInfo("  {$targetName}/{$wfName}: identical — skipped");
+                            continue;
+                        }
+                    }
+
+                    // Push update via Contents API
+                    $this->adapter->createOrUpdateFile(
+                        $targetOrg,
+                        $targetName,
+                        $destPath,
+                        $source['content'],
+                        "chore(ci): sync {$wfName} from Template-Generic [skip ci]",
+                        $existingSha,
+                        'dev'
+                    );
+
+                    $this->logger->logInfo("  {$targetName}/{$wfName}: updated");
+                    $updated++;
+                } catch (Exception $e) {
+                    $this->logger->logWarning("  {$targetName}/{$wfName}: failed — " . $e->getMessage());
+                    $this->adapter->getApiClient()->resetCircuitBreaker();
+                }
+            }
+        }
+
+        $this->logger->logInfo("Universal workflow sync complete: {$updated} file(s) updated across templates");
+        return $updated;
+    }
+
     private function getSharedWorkflows(string $platform, string $repoRoot): array
     {
         $wfDir = $this->adapter->getWorkflowDir();
 
         // Determine which template repo to source from
-        $templateType = match (true) {
-            in_array($platform, ['dolibarr', 'platform']) => 'dolibarr',
-            in_array($platform, ['joomla', 'joomla']) => 'joomla',
-            str_starts_with($platform, 'client') => 'client',
-            default => 'generic',
-        };
-
-        // Clone template repo to tmp if not already cached
-        $templateRepo = self::TEMPLATE_REPOS[$templateType];
+        $templateRepo = self::TEMPLATE_REPOS[$platform] ?? self::TEMPLATE_REPOS['generic'];
         $cacheDir = sys_get_temp_dir() . '/mokostandards-sync/' . basename($templateRepo);
 
         if (!is_dir($cacheDir)) {
@@ -1116,8 +1228,12 @@ HCL;
             }
         }
 
-        // Read all .yml files from the template's .gitea/workflows/
-        $sourceDir = "{$cacheDir}/.gitea/workflows";
+        // Read all .yml files from the template's workflow directory
+        $sourceDir = "{$cacheDir}/.mokogitea/workflows";
+        // Fallback to legacy path if .mokogitea doesn't exist
+        if (!is_dir($sourceDir)) {
+            $sourceDir = "{$cacheDir}/.gitea/workflows";
+        }
         $shared = [];
 
         if (is_dir($sourceDir)) {
@@ -1510,16 +1626,16 @@ HCL;
 
                     if ($updated) {
                         $results['success']++;
-                        $this->metrics->increment('repos_updated_total', ['status' => 'success']);
+                        $this->metrics->increment('repos_updated_total', 1, ['status' => 'success']);
                         $results['repositories'][$repoName] = 'updated';
                     } else {
                         $results['skipped']++;
-                        $this->metrics->increment('repos_updated_total', ['status' => 'skipped']);
+                        $this->metrics->increment('repos_updated_total', 1, ['status' => 'skipped']);
                         $results['repositories'][$repoName] = 'skipped';
                     }
                 } catch (Exception $e) {
                     $results['failed']++;
-                    $this->metrics->increment('repos_updated_total', ['status' => 'failed']);
+                    $this->metrics->increment('repos_updated_total', 1, ['status' => 'failed']);
                     $results['repositories'][$repoName] = 'failed: ' . $e->getMessage();
                 }
 

lib/Enterprise/SecurityValidator.php

@@ -59,6 +59,8 @@ use RecursiveIteratorIterator;
 
 /**
  * Exception raised when security violations are detected
+ *
+ * @since 04.00.00
  */
 class SecurityViolation extends Exception
 {

lib/Enterprise/TransactionManager.php

@@ -96,8 +96,6 @@ class TransactionStep
  */
 class Transaction
 {
-    private const VERSION = '04.06.00';
-
     private string $name;
     /** @var array<int, TransactionStep> */
     private array $steps = [];

phpstan.neon

@@ -6,7 +6,7 @@
 
 # PHPStan configuration for moko-platform projects
 parameters:
-    level: 2
+    level: 6
     paths:
         - lib
         - validate
@@ -16,12 +16,11 @@ parameters:
         analyseAndScan:
             - vendor
             - node_modules (?)
-            # Legacy CLIApp scripts — need migration to CliFramework
-            - automation/repo_cleanup.php
-            - automation/push_files.php
-            - cli/joomla_release.php
 
     reportUnmatchedIgnoredErrors: false
 
     checkFunctionNameCase: true
     checkInternalClassCaseSensitivity: true
+
+includes:
+    - phpstan-baseline.neon

phpunit.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+SPDX-License-Identifier: GPL-3.0-or-later
+-->
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         colors="true"
+         failOnRisky="true"
+         failOnWarning="true">
+    <testsuites>
+        <testsuite name="Unit">
+            <directory>tests/Unit</directory>
+        </testsuite>
+    </testsuites>
+</phpunit>

tests/Unit/ConfigValidatorTest.php

@@ -0,0 +1,141 @@
+<?php
+
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace MokoStandards\Tests\Unit;
+
+use MokoEnterprise\ConfigValidator;
+use PHPUnit\Framework\TestCase;
+
+class ConfigValidatorTest extends TestCase
+{
+    private ConfigValidator $validator;
+
+    protected function setUp(): void
+    {
+        $this->validator = new ConfigValidator();
+    }
+
+    public function testValidConfigPasses(): void
+    {
+        $schema = [
+            'type' => 'object',
+            'properties' => [
+                'name' => ['type' => 'string'],
+                'version' => ['type' => 'string'],
+            ],
+            'required' => ['name'],
+        ];
+
+        $config = ['name' => 'MyProject', 'version' => '1.0'];
+
+        $this->assertTrue($this->validator->validate($config, $schema));
+        $this->assertEmpty($this->validator->getErrors());
+    }
+
+    public function testMissingRequiredField(): void
+    {
+        $schema = [
+            'type' => 'object',
+            'properties' => [
+                'name' => ['type' => 'string'],
+            ],
+            'required' => ['name'],
+        ];
+
+        $this->assertFalse($this->validator->validate([], $schema));
+        $this->assertStringContainsString(
+            'required',
+            $this->validator->getErrors()[0]
+        );
+    }
+
+    public function testEnumValidation(): void
+    {
+        $schema = [
+            'type' => 'object',
+            'properties' => [
+                'type' => [
+                    'type' => 'string',
+                    'enum' => ['component', 'module', 'plugin'],
+                ],
+            ],
+        ];
+
+        $valid = ['type' => 'component'];
+        $this->assertTrue($this->validator->validate($valid, $schema));
+
+        $invalid = ['type' => 'banana'];
+        $this->assertFalse($this->validator->validate($invalid, $schema));
+    }
+
+    public function testNestedObjectValidation(): void
+    {
+        $schema = [
+            'type' => 'object',
+            'properties' => [
+                'db' => [
+                    'type' => 'object',
+                    'properties' => [
+                        'host' => ['type' => 'string'],
+                        'port' => ['type' => 'integer'],
+                    ],
+                    'required' => ['host'],
+                ],
+            ],
+        ];
+
+        $valid = ['db' => ['host' => 'localhost', 'port' => 3306]];
+        $this->assertTrue($this->validator->validate($valid, $schema));
+
+        $invalid = ['db' => ['port' => 3306]];
+        $this->assertFalse($this->validator->validate($invalid, $schema));
+    }
+
+    public function testUnknownPropertiesWarn(): void
+    {
+        $schema = [
+            'type' => 'object',
+            'properties' => [
+                'name' => ['type' => 'string'],
+            ],
+        ];
+
+        $config = ['name' => 'ok', 'extra' => 'unknown'];
+        $this->assertTrue($this->validator->validate($config, $schema));
+        $this->assertNotEmpty($this->validator->getWarnings());
+    }
+
+    public function testTypeMismatch(): void
+    {
+        $schema = [
+            'type' => 'object',
+            'properties' => [
+                'count' => ['type' => 'integer'],
+            ],
+        ];
+
+        $invalid = ['count' => 'not-a-number'];
+        $this->assertFalse($this->validator->validate($invalid, $schema));
+    }
+
+    public function testStringMinLength(): void
+    {
+        $schema = [
+            'type' => 'object',
+            'properties' => [
+                'name' => ['type' => 'string', 'minLength' => 3],
+            ],
+        ];
+
+        $short = ['name' => 'ab'];
+        $this->assertFalse($this->validator->validate($short, $schema));
+
+        $ok = ['name' => 'abc'];
+        $this->assertTrue($this->validator->validate($ok, $schema));
+    }
+}

tests/Unit/VersionBumpTest.php

@@ -0,0 +1,164 @@
+<?php
+
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace MokoStandards\Tests\Unit;
+
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Tests for cli/version_bump.php
+ */
+class VersionBumpTest extends TestCase
+{
+    private string $tmpDir;
+    private string $script;
+
+    protected function setUp(): void
+    {
+        $this->tmpDir = sys_get_temp_dir() . '/moko-test-' . uniqid();
+        mkdir($this->tmpDir, 0755, true);
+        $this->script = dirname(__DIR__, 2) . '/cli/version_bump.php';
+    }
+
+    protected function tearDown(): void
+    {
+        $this->rmdir($this->tmpDir);
+    }
+
+    public function testPatchBump(): void
+    {
+        $this->writeReadme('01.02.03');
+        $output = $this->execute();
+        $this->assertStringContainsString('01.02.04', $output);
+        $this->assertReadmeVersion('01.02.04');
+    }
+
+    public function testPatchBumpRollover(): void
+    {
+        $this->writeReadme('01.02.99');
+        $this->execute();
+        $this->assertReadmeVersion('01.03.00');
+    }
+
+    public function testMinorBump(): void
+    {
+        $this->writeReadme('01.02.03');
+        $this->execute(['--minor']);
+        $this->assertReadmeVersion('01.03.00');
+    }
+
+    public function testMajorBump(): void
+    {
+        $this->writeReadme('01.02.03');
+        $this->execute(['--major']);
+        $this->assertReadmeVersion('02.00.00');
+    }
+
+    public function testBumpsFromHtmlComment(): void
+    {
+        file_put_contents(
+            "{$this->tmpDir}/README.md",
+            "<!-- VERSION: 03.05.01 -->\nSome content\n"
+        );
+
+        $this->execute();
+        $content = file_get_contents("{$this->tmpDir}/README.md");
+        $this->assertStringContainsString('03.05.02', $content);
+        $this->assertStringContainsString('Some content', $content);
+    }
+
+    public function testBumpsWhenXmlHasSuffix(): void
+    {
+        $this->writeReadme('01.00.00');
+        mkdir("{$this->tmpDir}/src", 0755, true);
+        file_put_contents(
+            "{$this->tmpDir}/src/test.xml",
+            '<extension type="component">'
+            . '<version>01.00.00-dev</version></extension>'
+        );
+
+        $output = $this->execute();
+        $this->assertStringContainsString('01.00.01', $output);
+    }
+
+    public function testFailsWithNoVersion(): void
+    {
+        file_put_contents(
+            "{$this->tmpDir}/README.md",
+            "# No version\n"
+        );
+
+        $code = 0;
+        $this->execute([], $code);
+        $this->assertSame(1, $code);
+    }
+
+    private function writeReadme(string $version): void
+    {
+        file_put_contents(
+            "{$this->tmpDir}/README.md",
+            "<!-- VERSION: {$version} -->\n"
+        );
+    }
+
+    private function assertReadmeVersion(string $expected): void
+    {
+        $content = file_get_contents("{$this->tmpDir}/README.md");
+        $this->assertMatchesRegularExpression(
+            '/VERSION:\s*' . preg_quote($expected, '/') . '/',
+            $content
+        );
+    }
+
+    /**
+     * @param string[] $extraArgs
+     */
+    private function execute(
+        array $extraArgs = [],
+        int &$exitCode = 0
+    ): string {
+        $cmd = ['php', $this->script, '--path', $this->tmpDir];
+        $cmd = array_merge($cmd, $extraArgs);
+
+        $descriptors = [
+            1 => ['pipe', 'w'],
+            2 => ['pipe', 'w'],
+        ];
+
+        $proc = proc_open($cmd, $descriptors, $pipes);
+        $stdout = stream_get_contents($pipes[1]);
+        fclose($pipes[1]);
+        fclose($pipes[2]);
+        $exitCode = proc_close($proc);
+
+        return $stdout ?: '';
+    }
+
+    private function rmdir(string $dir): void
+    {
+        if (!is_dir($dir)) {
+            return;
+        }
+
+        $iter = new \RecursiveIteratorIterator(
+            new \RecursiveDirectoryIterator(
+                $dir,
+                \FilesystemIterator::SKIP_DOTS
+            ),
+            \RecursiveIteratorIterator::CHILD_FIRST
+        );
+
+        foreach ($iter as $file) {
+            $file->isDir()
+                ? rmdir($file->getPathname())
+                : unlink($file->getPathname());
+        }
+
+        rmdir($dir);
+    }
+}

tests/Unit/VersionReadTest.php

@@ -0,0 +1,133 @@
+<?php
+
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace MokoStandards\Tests\Unit;
+
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Tests for cli/version_read.php
+ */
+class VersionReadTest extends TestCase
+{
+    private string $tmpDir;
+    private string $script;
+
+    protected function setUp(): void
+    {
+        $this->tmpDir = sys_get_temp_dir() . '/moko-test-' . uniqid();
+        mkdir($this->tmpDir, 0755, true);
+        $this->script = dirname(__DIR__, 2) . '/cli/version_read.php';
+    }
+
+    protected function tearDown(): void
+    {
+        $this->rmdir($this->tmpDir);
+    }
+
+    public function testReadsVersionFromReadme(): void
+    {
+        file_put_contents(
+            "{$this->tmpDir}/README.md",
+            "# Test\n<!-- VERSION: 02.03.04 -->\n"
+        );
+
+        $this->assertSame('02.03.04', trim($this->runScript()));
+    }
+
+    public function testReadsVersionFromXmlManifest(): void
+    {
+        mkdir("{$this->tmpDir}/src", 0755, true);
+        file_put_contents(
+            "{$this->tmpDir}/src/test.xml",
+            '<extension type="component">'
+            . '<version>05.01.00</version></extension>'
+        );
+
+        $this->assertSame('05.01.00', trim($this->runScript()));
+    }
+
+    public function testStripsStabilitySuffixFromXml(): void
+    {
+        mkdir("{$this->tmpDir}/src", 0755, true);
+        file_put_contents(
+            "{$this->tmpDir}/src/test.xml",
+            '<extension type="component">'
+            . '<version>01.00.00-dev</version></extension>'
+        );
+
+        $this->assertSame('01.00.00', trim($this->runScript()));
+    }
+
+    public function testReturnsHigherOfReadmeAndManifest(): void
+    {
+        file_put_contents(
+            "{$this->tmpDir}/README.md",
+            "<!-- VERSION: 01.02.00 -->\n"
+        );
+        mkdir("{$this->tmpDir}/src", 0755, true);
+        file_put_contents(
+            "{$this->tmpDir}/src/test.xml",
+            '<extension type="component">'
+            . '<version>01.03.00</version></extension>'
+        );
+
+        $this->assertSame('01.03.00', trim($this->runScript()));
+    }
+
+    public function testExitsNonZeroWhenNoVersion(): void
+    {
+        file_put_contents(
+            "{$this->tmpDir}/README.md",
+            "# No version here\n"
+        );
+
+        $code = 0;
+        $this->runScript($code);
+        $this->assertSame(1, $code);
+    }
+
+    private function runScript(int &$exitCode = 0): string
+    {
+        $proc = proc_open(
+            ['php', $this->script, '--path', $this->tmpDir],
+            [1 => ['pipe', 'w'], 2 => ['pipe', 'w']],
+            $pipes
+        );
+
+        $stdout = stream_get_contents($pipes[1]);
+        fclose($pipes[1]);
+        fclose($pipes[2]);
+        $exitCode = proc_close($proc);
+
+        return $stdout ?: '';
+    }
+
+    private function rmdir(string $dir): void
+    {
+        if (!is_dir($dir)) {
+            return;
+        }
+
+        $iter = new \RecursiveIteratorIterator(
+            new \RecursiveDirectoryIterator(
+                $dir,
+                \FilesystemIterator::SKIP_DOTS
+            ),
+            \RecursiveIteratorIterator::CHILD_FIRST
+        );
+
+        foreach ($iter as $file) {
+            $file->isDir()
+                ? rmdir($file->getPathname())
+                : unlink($file->getPathname());
+        }
+
+        rmdir($dir);
+    }
+}

validate/auto_detect_platform.php

@@ -22,7 +22,7 @@ require_once __DIR__ . '/../../vendor/autoload.php';
 require_once __DIR__ . '/../lib/Enterprise/CliFramework.php';
 
 use MokoEnterprise\{
-    CLIApp,
+    CliFramework,
     ProjectTypeDetector,
     PluginFactory,
     PluginRegistry,
@@ -36,7 +36,7 @@ use MokoEnterprise\{
  * Detects whether a repository is a Joomla/WaaS component, Dolibarr/CRM module,
  * or generic repository, then validates against appropriate schema
  */
-class AutoDetectPlatform extends CLIApp
+class AutoDetectPlatform extends CliFramework
 {
     private const DETECTION_THRESHOLD = 0.5; // 50% confidence required
 
@@ -62,20 +62,19 @@ class AutoDetectPlatform extends CLIApp
     private string $schemaFile = '';
     private ?object $detectedPlugin = null;
 
-    protected function setupArguments(): array
+    protected function configure(): void
     {
-        return [
-            'repo-path:' => 'Path to repository to analyze (default: current directory)',
-            'schema-dir:' => 'Path to schema definitions directory (default: definitions/default)',
-            'output-dir:' => 'Directory for output reports (default: var/logs/validation)',
-        ];
+        $this->setDescription('Automatically detect platform type and validate repository');
+        $this->addArgument('--repo-path', 'Path to repository to analyze', '.');
+        $this->addArgument('--schema-dir', 'Path to schema definitions directory', 'definitions/default');
+        $this->addArgument('--output-dir', 'Directory for output reports', 'var/logs/validation');
     }
 
     protected function run(): int
     {
-        $repoPath = $this->getOption('repo-path', '.');
-        $schemaDir = $this->getOption('schema-dir', 'definitions/default');
-        $outputDir = $this->getOption('output-dir', 'var/logs/validation');
+        $repoPath = $this->getArgument('--repo-path', '.');
+        $schemaDir = $this->getArgument('--schema-dir', 'definitions/default');
+        $outputDir = $this->getArgument('--output-dir', 'var/logs/validation');
 
         // Make paths absolute
         $repoPath = $this->getAbsolutePath($repoPath);
@@ -151,7 +150,7 @@ class AutoDetectPlatform extends CLIApp
         }
 
         // Output results
-        if ($this->jsonOutput) {
+        if ($this->getArgument("--json", false)) {
             $this->outputJson();
         } else {
             $this->displayResults();
@@ -953,5 +952,5 @@ class AutoDetectPlatform extends CLIApp
 }
 
 // Run the application
-$app = new AutoDetectPlatform('auto_detect_platform', 'Automatically detect platform type and validate repository');
+$app = new AutoDetectPlatform();
 exit($app->execute());

validate/check_file_integrity.php

@@ -25,7 +25,7 @@ final class CheckFileIntegrity
     private bool $verbose = false;
     private bool $jsonOutput = false;
 
-    /** @var array{host: string, port: int, user: string, identity: string} */
+    /** @var array<string, mixed> */
     private array $sftpConfig = [];
 
     public function run(): int

validate/check_repo_health.php

@@ -33,12 +33,18 @@ require_once __DIR__ . '/../vendor/autoload.php';
 
 use MokoEnterprise\{AuditLogger, CliFramework, MetricsCollector, PluginFactory};
 
+/**
+ * Repository Health Checker
+ *
+ * Validates repository structure, standards compliance, and configuration
+ * against MokoStandards definitions. Produces a health score and report.
+ *
+ * @since 04.00.00
+ */
 class RepoHealthChecker extends CliFramework
 {
-    private const DEFAULT_THRESHOLD = 70.0;
     private AuditLogger $logger;
     private MetricsCollector $metrics;
-    private PluginFactory $pluginFactory;
     private string $apiBaseUrl = 'https://git.mokoconsulting.tech/api/v1';
 
     private array $results = [
@@ -61,7 +67,6 @@ class RepoHealthChecker extends CliFramework
         parent::initialize();
         $this->logger = new AuditLogger('repo_health_checker');
         $this->metrics = new MetricsCollector();
-        $this->pluginFactory = new PluginFactory($this->logger, $this->metrics);
         $config = \MokoEnterprise\Config::load();
         $this->apiBaseUrl = rtrim($config->getString('gitea.url', 'https://git.mokoconsulting.tech'), '/') . '/api/v1';
     }

validate/check_wiki_health.php

@@ -17,29 +17,32 @@ declare(strict_types=1);
 
 require_once __DIR__ . '/../vendor/autoload.php';
 
-use MokoEnterprise\CLIApp;
+use MokoEnterprise\CliFramework;
 
-class CheckWikiHealth extends CLIApp
+/**
+ * Wiki Health Checker
+ *
+ * Validates Gitea wiki structure and content for a repository,
+ * checking for required pages, broken links, and formatting issues.
+ *
+ * @since 04.00.00
+ */
+class CheckWikiHealth extends CliFramework
 {
-    public function __construct()
+    protected function configure(): void
     {
-        parent::__construct('check-wiki-health', 'Validate wiki health for a repository', '01.00.00');
-    }
-
-    protected function setupArguments(): array
-    {
-        return [
-            'path:'     => 'Repository path (default: current directory)',
-            'gitea-url:' => 'Gitea base URL (default: https://git.mokoconsulting.tech)',
-            'token:'    => 'Gitea API token (or set GITEA_TOKEN env var)',
-        ];
+        $this->setDescription('Validate wiki health for a repository');
+        $this->addArgument('--path', 'Repository path (default: current directory)', '.');
+        $this->addArgument('--gitea-url', 'Gitea base URL', 'https://git.mokoconsulting.tech');
+        $this->addArgument('--token', 'Gitea API token (or set GITEA_TOKEN env var)', '');
+        $this->addArgument('--json', 'Output as JSON', false);
     }
 
     protected function run(): int
     {
-        $repoPath = realpath($this->getOption('path', '.')) ?: '.';
-        $giteaUrl = $this->getOption('gitea-url', 'https://git.mokoconsulting.tech');
-        $token = $this->getOption('token', getenv('GITEA_TOKEN') ?: '');
+        $repoPath = realpath($this->getArgument('--path', '.')) ?: '.';
+        $giteaUrl = $this->getArgument('--gitea-url', 'https://git.mokoconsulting.tech');
+        $token = $this->getArgument('--token', getenv('GITEA_TOKEN') ?: '');
 
         // Detect repo owner/name from git config
         $configFile = $repoPath . '/.git/config';
@@ -76,7 +79,7 @@ class CheckWikiHealth extends CLIApp
         if ($pages === null) {
             $this->log('  No wiki found or API error', 'WARNING');
             $issues++;
-            if ($this->jsonOutput) {
+            if ($this->getArgument("--json", false)) {
                 echo json_encode(['status' => 'no_wiki', 'issues' => $issues]);
             }
             return 0;
@@ -118,7 +121,7 @@ class CheckWikiHealth extends CLIApp
             }
         }
 
-        if ($this->jsonOutput) {
+        if ($this->getArgument("--json", false)) {
             echo json_encode([
                 'repo' => "{$owner}/{$repo}",
                 'pages' => $pageCount,
@@ -153,4 +156,5 @@ class CheckWikiHealth extends CLIApp
     }
 }
 
-(new CheckWikiHealth())->execute();
+$app = new CheckWikiHealth();
+exit($app->execute());

validate/scan_drift.php

@@ -38,7 +38,6 @@ class DriftScanner extends CliFramework
     private const DEFAULT_ORG = 'mokoconsulting-tech';
 
     private ApiClient $apiClient;
-    private AuditLogger $logger;
     private MetricsCollector $metrics;
     private \MokoEnterprise\GitPlatformAdapter $adapter;
 
@@ -60,7 +59,6 @@ class DriftScanner extends CliFramework
     {
         parent::initialize();
 
-        $this->logger = new AuditLogger('drift_scanner');
         $this->metrics = new MetricsCollector();
 
         // Initialize API client via platform adapter